# Coral RFE: chroot maintainer scripts under `--root`

**Status:** Draft — ready to file with the Coral team
**Filed against:** Coral 0.4.2 (`reef.toml` version = "0.4.2")
**Reporter:** Chris Tusa <chris.tusa@leafscale.com>
**Consumer:** zyginstall (the Hammerhead system installer) — installs the OS into a
target root via `coral install --root /mnt ...` from an ISO live environment.

## Summary

When `coral install --root <dir>` (and the remove/upgrade paths) run a package's
maintainer scripts, the scripts execute against the **live host filesystem** with the
real `/` as root. Only the file *payload* is written under `<dir>`; the scriptlets are
not confined to it. There is no flag, config key, or env var to change this.

For an OS installer that stages a target root and then installs packages into it, a
package's `post-install.sh` that assumes it runs inside the installed system will
instead act on the host (the ISO live environment) — silently corrupting the host or
no-op'ing incorrectly. This makes package maintainer scripts unusable for
`--root` installs.

## Current behavior (evidence)

- File placement correctly honors `--root`: `install_files` writes every file to
  `path.join_path(root, rel_path)` (`src/core/package.reef:307`). ✅
- Script execution does **not**: the single executor `run_script`
  (`src/core/package.reef:508-536`) builds `zsh "<extract_dir>/.SCRIPTS/<name>.sh" <args>`
  and hands it to `process_spawn_shell` — no `chroot`, no `cd`, and `<root>` is never
  passed in. The hook wrappers `run_pre_install` / `run_post_install`
  (`package.reef:539-565`) take only `(pkg_dir, version)`; `run_stored_script`
  (`package.reef:624-651`) takes `(scripts_dir, script_name, script_args)` and the stored
  hook wrappers (`run_stored_pre_remove` etc., `package.reef:654+`) take
  `(scripts_dir, version)` — the target root is architecturally invisible to all of them.
- Call sites confirm the split: scripts run with `extract_dir`, files install with
  `install_root` (`src/commands/install.reef:443` / `:452` / `:461`).
- No `chroot` anywhere in `src/` (only the standalone `tools/mkchroot/` helper).
- No `$ROOT`/`$PKGROOT` env var is exported to scripts, so a script cannot even manually
  honor the root today (only `$VERSION`/`$OLD_VERSION`/`$NEW_VERSION` are passed
  positionally).

## Requested change

1. **Chroot maintainer scripts when the install root is non-`/`.** Thread the install
   root into the hook functions (`run_pre_install`, `run_post_install`,
   `run_pre_remove`, `run_post_remove`, `run_pre_upgrade`, `run_post_upgrade`,
   `run_stored_*` — all currently `(pkg_dir, version)`) and have `run_script` /
   `run_stored_script` emit `chroot "<root>" zsh /.SCRIPTS/<name> <args>`, with the
   `.SCRIPTS` dir staged inside `<root>` so it's reachable post-chroot.

2. **An explicit control** — e.g. a `--chroot-scripts` / `--no-chroot-scripts` flag or a
   `chroot_scripts` config key — since none exists today. Define the fallback when
   `chroot(2)` isn't permitted (non-root caller): fail loudly rather than silently
   running against the host.

3. **Until (1) ships, a safety note** in the docs that `coral install --root <dir>`
   stages *files* under `<dir>` but runs maintainer scripts against the host, and,
   as a stopgap, **export a `$CORAL_ROOT` env var** to scripts so a maintainer can
   defensively prefix paths.

## Impact on zyginstall (context for prioritization)

Not an immediate hard blocker for the first two packages: `hammerhead-kernel` and
`hammerhead-userland` have only one post-install script (a `svccfg import` guarded on
`svc.configd` running) which no-ops on a Hammerhead/zyginit system. But it is a
correctness landmine for any future package with a real post-install action, and the
installer would otherwise have to special-case / manually re-run scripts under
`chroot /mnt` itself. A stopgap `$CORAL_ROOT` env var (item 3) would let the installer
proceed safely before the full chroot work lands.