@celilo/cli 2.0.0 → 2.2.0

package/src/hooks/mount-set.test.ts

@@ -7,8 +7,18 @@
  */
 
 import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
 import { BROWSER_ROOT } from '@celilo/capabilities';
-import { deriveMountSet, forbiddenPaths, isForbidden, toBwrapArgs } from './mount-set';
+import { planJailedSpawn, realpathRequest, runtimeModulePathsFor } from './jail';
+import {
+  deriveMountSet,
+  forbiddenPaths,
+  isForbidden,
+  toBwrapArgs,
+  toSandboxProfile,
+} from './mount-set';
 
 const BASE = {
   modulePath: '/var/celilo/modules/caddy',
@@ -98,6 +108,27 @@ describe('ordering is semantic', () => {
   });
 });
 
+describe('a hook write to the module tree is refused at mount time (celilo#1265)', () => {
+  // The recurrence gate for celilo#1265: hello-private-foo failed at deploy
+  // because its hook wrote ca.crt into site/dist, which the jail binds only
+  // through the module tree's read-only row. The sanctioned writable directory
+  // is `<module>/state` (celilo#1000). This pins the DERIVED mount set, with
+  // no docker and no bubblewrap: no row may make the built web root writable,
+  // and the state dir must stay writable. If a carve-out for site/dist ever
+  // appears here, this fails before a fixture can fail at deploy again.
+  test('no entry makes site/dist writable; state stays writable', () => {
+    const set = deriveMountSet(BASE);
+    const webRoot = `${BASE.modulePath}/site/dist`;
+    const writableCovering = set.entries.filter(
+      (e) => e.mode === 'rw' && (e.path === webRoot || webRoot.startsWith(`${e.path}/`)),
+    );
+    expect(writableCovering).toEqual([]);
+
+    const state = set.entries.find((e) => e.path === BASE.stateDir);
+    expect(state?.mode).toBe('rw');
+  });
+});
+
 describe('contract inputs are bound at their declared access', () => {
   test("'write' is read-write and 'read' is read-only", () => {
     const set = deriveMountSet({
@@ -168,3 +199,267 @@ describe('the fleet browser is reachable, and only read-only (task 4.10)', () =>
     expect(pathsOf(BASE)).not.toContain('/var/lib/celilo');
   });
 });
+
+describe('the sandbox-exec profile renders the same set (task 4.8)', () => {
+  const profileOf = (r: Parameters<typeof deriveMountSet>[0] = BASE) =>
+    toSandboxProfile(deriveMountSet(r));
+
+  test('a read-only mount is denied write and allowed read, in that order', () => {
+    const lines = profileOf().split('\n');
+    const deny = lines.indexOf(`(deny file-write* (subpath "${BASE.modulePath}"))`);
+    const allow = lines.indexOf(`(allow file-read* (subpath "${BASE.modulePath}"))`);
+    expect(deny).toBeGreaterThan(-1);
+    // SBPL is last-match-wins, so the deny must come FIRST or it would revoke
+    // the read it is paired with.
+    expect(allow).toBeGreaterThan(deny);
+  });
+
+  test('a writable directory nested in the read-only tree comes after it', () => {
+    const lines = profileOf().split('\n');
+    expect(
+      lines.indexOf(`(allow file-read* file-write* (subpath "${BASE.stateDir}"))`),
+    ).toBeGreaterThan(lines.indexOf(`(allow file-read* (subpath "${BASE.modulePath}"))`));
+  });
+
+  test('the tmpfs row grants nothing: macOS has no tmpfs and deny-default covers it', () => {
+    // The row still appears, as a comment, so a reader of the profile can see
+    // that the derivation asked for something this backend cannot give.
+    const profile = profileOf();
+    expect(profile).toContain('; /tmp: no tmpfs backend');
+    expect(profile).not.toContain('(subpath "/tmp")');
+  });
+
+  test('every ancestor is a literal, never a subpath', () => {
+    // A `subpath` grant on an ancestor would expose everything beneath it —
+    // `/var/celilo` holds master.key. `literal` permits stat and readdir of the
+    // directory node alone. This is the difference between D9's acceptance
+    // criterion holding and not.
+    const profile = profileOf();
+    expect(profile).toContain('(allow file-read* (literal "/var/celilo"))');
+    expect(profile).not.toContain('(allow file-read* (subpath "/var/celilo"))');
+    expect(profile).not.toContain('(subpath "/"))');
+  });
+
+  test('a forbidden path never reaches the profile', () => {
+    const profile = profileOf({
+      ...BASE,
+      pathInputs: [{ name: 'evil', value: '/usr/bin/bwrap', access: 'write' as const }],
+    });
+    expect(profile).not.toContain('(subpath "/usr/bin/bwrap")');
+  });
+
+  test('a quote in a path cannot end the rule early', () => {
+    const profile = profileOf({ ...BASE, modulePath: '/var/celilo/modules/od"d' });
+    expect(profile).toContain('(subpath "/var/celilo/modules/od\\"d")');
+  });
+
+  test('the network is allowed, because D9 does not namespace it', () => {
+    expect(profileOf()).toContain('(allow network*)');
+  });
+});
+
+describe('name resolution inside the jail (celilo#1225)', () => {
+  test('the resolver config is bound read-only', () => {
+    // Without these a hook resolves no NAME. getaddrinfo finds no nameserver
+    // and the call dies as ETIMEOUT, which reads as the remote endpoint being
+    // down. Measured on namecheap's validate_config against an endpoint that
+    // was up.
+    const set = deriveMountSet(BASE);
+    for (const path of ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts']) {
+      const row = set.entries.find((e) => e.path === path);
+      expect(row).toBeDefined();
+      expect(row?.mode).toBe('ro');
+    }
+  });
+
+  test('binding the resolver does not bind the rest of /etc', () => {
+    // The acceptance criterion for this jail is absence. Naming three files
+    // must not become naming a directory.
+    const set = deriveMountSet(BASE);
+    expect(set.entries.some((e) => e.path === '/etc')).toBe(false);
+    expect(set.entries.some((e) => e.path === '/etc/shadow')).toBe(false);
+  });
+});
+
+describe('every row states what its own absence means (celilo#1244 family)', () => {
+  const rowFor = (set: ReturnType<typeof deriveMountSet>, path: string) =>
+    set.entries.find((e) => e.path === path);
+
+  test('a contract path input is REQUIRED, so dropping it can never be a warning', () => {
+    // The case the old undifferentiated warning buried. A hook whose declared
+    // write path is dropped writes into the run's private tmpfs and reports
+    // success over a directory discarded when it exits.
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [{ name: 'backup_dir', value: '/srv/staged', access: 'write' }],
+    });
+    expect(rowFor(set, '/srv/staged')?.absence).toBe('required');
+  });
+
+  test('a runtime support directory is RUNTIME, so its absence is not reported', () => {
+    // /lib64 does not exist on arm64 and never will. A genuinely needed one
+    // fails the runtime, which is a louder and more specific signal than a
+    // warning that fired 96 times in one `cele2e run --all`.
+    const set = deriveMountSet(BASE);
+    expect(rowFor(set, '/lib64')?.absence).toBe('runtime');
+    expect(rowFor(set, '/usr/lib')?.absence).toBe('runtime');
+  });
+
+  test("the module's own tree and its state dir are REQUIRED", () => {
+    // Neither is ever legitimately absent: executor.ts mkdirSyncs the state dir
+    // before deriving the set, so an absent one means something is wrong that a
+    // dropped mount would only make more confusing later.
+    const set = deriveMountSet(BASE);
+    expect(rowFor(set, BASE.modulePath)?.absence).toBe('required');
+    expect(rowFor(set, BASE.stateDir)?.absence).toBe('required');
+  });
+
+  test('generated output is CONDITIONAL, because it appears only after generation', () => {
+    const set = deriveMountSet(BASE);
+    expect(rowFor(set, `${BASE.modulePath}/generated`)?.absence).toBe('conditional');
+  });
+
+  test('every row carries a policy, so a new mount cannot inherit a default', () => {
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [{ name: 'cert', value: '/srv/certs', access: 'read' }],
+    });
+    for (const e of set.entries) {
+      expect(e.absence).toBeDefined();
+    }
+  });
+});
+
+describe('a jailed hook cannot spawn /bin/sh, by derivation (e2e-recovery lane B)', () => {
+  // The full derivation lives in openspec/changes/e2e-suite-recovery/
+  // jail-shell-derivation.md. The short form: the derivation names NO system
+  // executable directory. It binds the interpreter as one file, the runner
+  // shim's directory, celilo's own node_modules, the module tree, the broker
+  // socket, the declared inputs, and library/resolver support dirs
+  // (/usr/lib, /lib, /lib64, /etc/ssl, the three resolver files). /bin and
+  // /usr/bin are in none of those families, so a shell is ABSENT — bubblewrap
+  // builds a namespace where the lookup dies with ENOENT, and sandbox-exec
+  // denies the read under deny-default (EPERM) — which is the measured
+  // `ENOENT: no such file or directory, posix_spawn '/bin/sh'` from
+  // e2e-suite-recovery's proposal.md.
+  //
+  // The assertion is absence of COVERAGE, never a specific errno, for the same
+  // reason hook-jail-unreachability.test.ts refuses to match on one: ENOENT
+  // and EPERM are both the jail working, and a test pinned to one goes red on
+  // the other platform for a jail that was working perfectly.
+  //
+  // These are tests over the DERIVED set, computed against a real mirrored
+  // layout with the real code path (realpathRequest -> runtimeModulePathsFor
+  // -> deriveMountSet -> planJailedSpawn), not against hand-built arguments:
+  // a hand-built set proves what the author believed, not what the jail does.
+
+  const EXECUTABLE_DIRS = ['/bin', '/usr/bin', '/sbin', '/usr/sbin', '/usr/local/bin'];
+  const SHELL = '/bin/sh';
+
+  /** Mirror a real module layout into a temp dir and derive through the real path. */
+  function derivedForMirroredModule() {
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-laneb-'));
+    const modulePath = join(scratch, 'modules', 'caddy');
+    const stateDir = join(modulePath, 'state');
+    const screenshotDir = join(modulePath, 'screenshots', 'run1');
+    mkdirSync(join(modulePath, 'generated'), { recursive: true });
+    mkdirSync(stateDir, { recursive: true });
+    mkdirSync(screenshotDir, { recursive: true });
+    const socketDir = mkdtempSync(join(tmpdir(), 'celilo-laneb-sock-'));
+    const stagedInput = mkdtempSync(join(tmpdir(), 'celilo-laneb-stage-'));
+    const runnerPath = resolve(__dirname, 'hook-runner.ts');
+
+    const request = realpathRequest({
+      modulePath,
+      stateDir,
+      screenshotDir,
+      socketDir,
+      runtimePath: process.execPath,
+      runnerPath,
+      runtimeModulePaths: runtimeModulePathsFor(runnerPath),
+      pathInputs: [{ name: 'backup_dir', value: join(stagedInput, 'data'), access: 'write' }],
+    });
+    const set = deriveMountSet(request);
+    return {
+      set,
+      cleanup: () => {
+        rmSync(scratch, { recursive: true, force: true });
+        rmSync(socketDir, { recursive: true, force: true });
+        rmSync(stagedInput, { recursive: true, force: true });
+      },
+    };
+  }
+
+  test('nothing in the jail covers /bin/sh, on any backend', () => {
+    const { set, cleanup } = derivedForMirroredModule();
+    try {
+      // A row covers /bin/sh only if it IS the shell or an ancestor of it.
+      // No entry is: nothing mounts /bin, and / is never a row (its grant, on
+      // macOS, is a literal on the node alone, which confers nothing on
+      // contents — pinned separately below).
+      const covering = set.entries.filter(
+        (e) => e.path === SHELL || SHELL.startsWith(`${e.path}/`),
+      );
+      expect(covering).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test('no system executable directory is a row, and the interpreter is the one exception', () => {
+    const { set, cleanup } = derivedForMirroredModule();
+    try {
+      const paths = set.entries.map((e) => e.path);
+      expect(paths.filter((p) => EXECUTABLE_DIRS.includes(p))).toEqual([]);
+
+      // A file bind under an executable directory (the interpreter can live in
+      // /usr/local/bin) is legitimate ONLY as the single runtime row. Any
+      // wider row there would drag the directory's other contents in.
+      for (const e of set.entries) {
+        const dir = EXECUTABLE_DIRS.find((d) => e.path.startsWith(`${d}/`));
+        if (dir) expect(e.path).toBe(process.execPath);
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test('the rendered bubblewrap command exposes no shell path either', () => {
+    // Measure reach on the artifact the kernel actually receives, not on the
+    // intermediate set: planJailedSpawn filters absent sources and renders the
+    // argv, and that argv is the last thing a future edit could corrupt.
+    const { set, cleanup } = derivedForMirroredModule();
+    try {
+      const plan = planJailedSpawn(
+        [process.execPath, resolve(__dirname, 'hook-runner.ts')],
+        set,
+        { backend: 'bubblewrap' },
+        'required',
+      );
+      expect(plan.mode).toBe('jailed');
+      expect(plan.cmd).not.toContain(SHELL);
+      expect(plan.cmd).not.toContain('/bin');
+    } finally {
+      cleanup();
+    }
+  });
+
+  test('the sandbox profile grants no read on /bin, as subpath or as literal', () => {
+    const { set, cleanup } = derivedForMirroredModule();
+    try {
+      const profile = toSandboxProfile(set);
+      // A subpath grant on /bin (or any executable directory) would make the
+      // shell readable, and (allow process*) does the rest — exec is not
+      // restricted; what the hook can READ is the boundary in both backends.
+      for (const dir of EXECUTABLE_DIRS) {
+        expect(profile).not.toContain(`(subpath "${dir}")`);
+      }
+      // /bin must not even appear as an ancestor literal: a literal permits
+      // stat and readdir of the node alone, but its presence would still mean
+      // something began mounting beneath /bin.
+      expect(profile).not.toContain('(literal "/bin")');
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/hooks/mount-set.ts

@@ -39,6 +39,8 @@ export interface MountEntry {
   readonly mode: MountMode;
   /** Why this row exists. Surfaced by the unjailed lint and by `system doctor`. */
   readonly reason: string;
+  /** What this row's absence from the host means. See `MountAbsence`. */
+  readonly absence: MountAbsence;
 }
 
 export interface MountSet {
@@ -110,6 +112,29 @@ export interface MountSetRequest {
 /** Directories whose contents the runtime needs in order to start at all. */
 const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
 
+/**
+ * What resolving a hostname needs. Read-only, and absent ones are dropped.
+ *
+ * Without these a jailed hook cannot resolve a NAME. `getaddrinfo` finds no
+ * nameserver, falls back to a loopback that answers nothing, and the call dies
+ * as `ETIMEOUT` — which reads as the remote endpoint being down rather than as
+ * the jail having no resolver. Measured on `namecheap`'s `validate_config`:
+ * `getaddrinfo ETIMEOUT dynamicdns.park-your-domain.com`, against an endpoint
+ * that was up and one the e2e topology answers for.
+ *
+ * This is not a widening of what a hook may reach. Design D12 already records
+ * as a residual that "a hook can still `fetch()` any HTTP endpoint directly;
+ * only `probeHttp` consults the target check" — so the network is already
+ * open, and a hook could always dial a literal IP. Withholding the resolver
+ * config did not close that door; it only made the door work for addresses and
+ * not for names, which is an accident rather than a policy.
+ *
+ * It sits beside `/etc/ssl` for the same reason that does: an outbound call
+ * needs a trust store AND a way to turn a name into an address, and binding
+ * one without the other leaves half a capability.
+ */
+const RESOLVER_FILES = ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts'] as const;
+
 /**
  * Paths that must NEVER appear in a mount set, whatever asks for them.
  *
@@ -131,8 +156,27 @@ const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const
  */
 const NEVER_MOUNT = ['/usr/bin/bwrap', '/usr/local/bin/bwrap', '/bin/bwrap'] as const;
 
-function entry(path: string, mode: MountMode, reason: string): MountEntry {
-  return { path, mode, reason };
+/**
+ * What a row's ABSENCE from the host means. Required, never defaulted: a default
+ * lets the next mount be added without deciding which kind it is, and that is
+ * exactly how the undifferentiated `skipped` list came to exist.
+ *
+ * bubblewrap fails the whole jail on a bind whose source is missing, so an
+ * absent row must be dropped. The question this answers is whether dropping it
+ * is fine, fatal, or nobody's business.
+ */
+export type MountAbsence =
+  /** Fatal. The hook cannot do what it was asked without this. */
+  | 'required'
+  /** Fatal only for a module that declared it needs the facility. */
+  | 'declared-only'
+  /** Not reported. A genuinely needed one fails the runtime, which is louder. */
+  | 'runtime'
+  /** Expected at some lifecycle points. Debug at most. */
+  | 'conditional';
+
+function entry(path: string, mode: MountMode, reason: string, absence: MountAbsence): MountEntry {
+  return { path, mode, reason, absence };
 }
 
 /**
@@ -159,18 +203,25 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   // silently an empty tmpfs directory writes into it, returns success, and
   // produces a backup containing NOTHING. It is found at restore. So the gate
   // on this asserts the artifact is non-empty, never that the hook exited zero.
-  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run'));
+  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run', 'runtime'));
 
   // 2. The runtime. Without it nothing runs, so it is not really a policy row.
-  entries.push(entry(request.runtimePath, 'ro', 'the interpreter'));
-  entries.push(entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns'));
+  entries.push(entry(request.runtimePath, 'ro', 'the interpreter', 'required'));
+  entries.push(
+    entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns', 'required'),
+  );
   // See MountSetRequest.runtimeModulePaths. Without these the shim starts and
   // immediately dies on `Cannot find module`.
   for (const dir of request.runtimeModulePaths ?? []) {
-    entries.push(entry(resolve(dir), 'ro', "celilo's own dependencies, which the shim imports"));
+    entries.push(
+      entry(resolve(dir), 'ro', "celilo's own dependencies, which the shim imports", 'required'),
+    );
   }
   for (const dir of RUNTIME_SUPPORT_DIRS) {
-    entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
+    entries.push(entry(dir, 'ro', 'shared libraries and trust store', 'runtime'));
+  }
+  for (const file of RESOLVER_FILES) {
+    entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES', 'runtime'));
   }
   // The fleet browser, read-only (task 4.10).
   //
@@ -199,7 +250,9 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   // the browser rather than here. That interim landed 2026-08-31 (celilo#1215):
   // the launch path in `test-fixtures/jail-toolchain-hook.ts` carries the flag,
   // and `jail-browser-launch-flags.test.ts` pins it there.
-  entries.push(entry(BROWSER_ROOT, 'ro', 'the fleet browser, when one is provisioned'));
+  entries.push(
+    entry(BROWSER_ROOT, 'ro', 'the fleet browser, when one is provisioned', 'declared-only'),
+  );
 
   // 3. The module's own tree, read-only, then its writable directories carved
   //    on top. bubblewrap resolves that in the right order, which is why the
@@ -208,19 +261,36 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   //    D9 says "the module's own tree is bound read-only". These are the
   //    carved exceptions to that sentence, and there are three of them rather
   //    than the one D9's prose implies.
-  entries.push(entry(modulePath, 'ro', "the module's own tree"));
+  entries.push(entry(modulePath, 'ro', "the module's own tree", 'required'));
   entries.push(
-    entry(resolve(request.stateDir), 'rw', 'ctx.stateDir, the sanctioned writable directory'),
+    entry(
+      resolve(request.stateDir),
+      'rw',
+      'ctx.stateDir, the sanctioned writable directory',
+      'required',
+    ),
   );
   entries.push(
-    entry(join(modulePath, 'generated'), 'rw', "celilo's generated output the hook may amend"),
+    entry(
+      join(modulePath, 'generated'),
+      'rw',
+      "celilo's generated output the hook may amend",
+      'conditional',
+    ),
   );
   if (request.screenshotDir) {
-    entries.push(entry(resolve(request.screenshotDir), 'rw', 'ctx.screenshotDir, this run only'));
+    entries.push(
+      entry(
+        resolve(request.screenshotDir),
+        'rw',
+        'ctx.screenshotDir, this run only',
+        'conditional',
+      ),
+    );
   }
 
   // 4. The broker channel. Bound AFTER the tmpfs, per the note above.
-  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket'));
+  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket', 'required'));
 
   // 5. Contract-declared path inputs, at the access the contract declares.
   //    Never inferred from the name — see ContractField.path.
@@ -230,6 +300,10 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
         resolve(input.value),
         input.access === 'write' ? 'rw' : 'ro',
         `contract input '${input.name}' (${input.access})`,
+        // Fatal, always. A hook whose declared WRITE path is dropped writes into
+        // the run's private tmpfs and reports success over a directory that is
+        // discarded when it exits. celilo#1248-adjacent; see jail.ts's note.
+        'required',
       ),
     );
   }
@@ -270,3 +344,132 @@ export function toBwrapArgs(set: MountSet): string[] {
   args.push('--chdir', set.chdir);
   return args;
 }
+
+/**
+ * Render a mount set as a `sandbox-exec` profile, in order (task 4.8).
+ *
+ * The SECOND renderer of the same derivation, alongside `toBwrapArgs`. That is
+ * the property task 4.7 asks for and the reason both live here: one
+ * computation, several consumers, so a macOS jail and a Linux jail cannot come
+ * to different conclusions about what a hook may see.
+ *
+ * **Order is semantic here for the same reason it is in `toBwrapArgs`, by a
+ * different mechanism.** SBPL is last-match-wins, so a read-write directory
+ * nested inside a read-only tree works exactly as bubblewrap's later-`--bind`-
+ * wins does. Measured 2026-08-27: with `state/` emitted after the module tree,
+ * a write to the tree gives `EPERM` and a write to `state/` succeeds.
+ *
+ * Three rules are not derived from the mount set, and each is a parity
+ * statement rather than a convenience:
+ *
+ *   - `(import bsd.sb)` supplies what any process needs to start at all —
+ *     the dyld shared cache, `file-read-metadata` for symlink traversal, the
+ *     `logd`/`cfprefsd` lookups. Without it `bun` dies before `main` with no
+ *     diagnostic (`SIGABRT`, no stderr, because stderr is denied too).
+ *   - `(allow process*)` matches bubblewrap, which does not restrict `exec`
+ *     either. A hook can run whatever it can READ, and what it can read is the
+ *     mount set. Withholding the path is the boundary in both backends.
+ *   - `(allow network*)` is D9: the network is not namespaced. D12 scopes
+ *     reachability by withholding the credential, never by filtering packets.
+ *
+ * Everything else this profile does NOT say is deliberate. `/etc` is absent
+ * because it is absent from D9's table, so on macOS a hook that resolves a
+ * hostname is not stopped by THIS profile: `(allow network*)` lets it reach
+ * the system resolver, which answers out of process in mDNSResponder
+ * (measured 2026-08-30, task 4.13's suite). Withholding `/etc/resolv.conf`
+ * does withhold resolution on Linux, where the file is the resolver's
+ * configuration. Adding `/etc` here alone is the drift task 4.7 exists to
+ * prevent.
+ *
+ * @param set - Paths already resolved through `realpath`. Not optional: a rule
+ *   naming an unresolved path does not match, and the failure is silent in
+ *   both directions (D8). Measured: with the module tree named as `/tmp/…`
+ *   rather than `/private/tmp/…` the rule does not apply, and bun cannot read
+ *   the cwd it was handed.
+ */
+export function toSandboxProfile(set: MountSet): string {
+  const lines = [
+    '(version 1)',
+    '(import "/System/Library/Sandbox/Profiles/bsd.sb")',
+    '(deny default)',
+    '(allow process*)',
+    '(allow network*)',
+  ];
+
+  // Every ANCESTOR of every mount, as a directory node and nothing more.
+  //
+  // This row has no bubblewrap counterpart and that is exactly why it exists.
+  // bubblewrap builds a new filesystem: to bind `/a/b/c` it must CREATE `/a/b`
+  // inside the namespace, so the parents come for free. `sandbox-exec` filters
+  // the tree that is already there and grants nothing implicitly, so every
+  // parent stays denied.
+  //
+  // What breaks is module resolution, and it breaks in a way that names none of
+  // this. Bun resolves a bare import by walking UP from the importing file
+  // testing each `<ancestor>/node_modules`. The shim's own `node_modules` is
+  // bound, but the directories BETWEEN are not, so the walk dies early, bun
+  // falls back to auto-install, and it tries to create `node_modules` in the
+  // read-only module tree. The message is `bun is unable to write files:
+  // PermissionDenied` — a write error for what is really a read denial three
+  // steps earlier. Measured 2026-08-27 by A/B on one variable: with a writable
+  // working directory the shim starts, with a read-only one it does not.
+  //
+  // `literal`, never `subpath`. A literal grant on a directory permits `stat`
+  // and `readdir` of that directory ALONE and confers nothing on the files in
+  // it. So `/var/celilo` becomes listable, which reveals that a file named
+  // `master.key` exists, and reading its bytes stays denied. That is the
+  // difference between D9's criterion holding and not, so do not "simplify"
+  // this to a subpath.
+  for (const path of ancestorsOf(set.entries)) {
+    lines.push(`(allow file-read* (literal ${sbplString(path)}))`);
+  }
+
+  for (const e of set.entries) {
+    // No tmpfs on macOS, and none is needed: `deny default` already makes the
+    // path unreadable, which is the privacy half of the row. The usability
+    // half — a working scratch directory — is what macOS does not get, so a
+    // hook writing to /tmp gets EPERM here and a discarded success on Linux.
+    // Louder than Linux rather than weaker, and named so nobody has to guess.
+    if (e.mode === 'tmpfs') {
+      lines.push(`; ${e.path}: no tmpfs backend; denied by default (${e.reason})`);
+      continue;
+    }
+    lines.push(`; ${e.reason}`);
+    if (e.mode === 'rw') {
+      lines.push(`(allow file-read* file-write* (subpath ${sbplString(e.path)}))`);
+      continue;
+    }
+    // The explicit deny makes `ro` mean read-only whatever preceded it, rather
+    // than relying on nothing earlier having granted write to a parent. That
+    // is true of today's derivation order and is not a property anyone should
+    // have to re-verify after editing it.
+    lines.push(`(deny file-write* (subpath ${sbplString(e.path)}))`);
+    lines.push(`(allow file-read* (subpath ${sbplString(e.path)}))`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Every directory strictly above one of these mounts, nearest-first order
+ * irrelevant, deduplicated. Excludes the mount paths themselves, which carry
+ * their own rules.
+ */
+function ancestorsOf(entries: readonly MountEntry[]): string[] {
+  const own = new Set(entries.map((e) => e.path));
+  const found = new Set<string>();
+  for (const e of entries) {
+    let dir = dirname(e.path);
+    while (dir !== dirname(dir)) {
+      if (!own.has(dir)) found.add(dir);
+      dir = dirname(dir);
+    }
+    found.add('/');
+  }
+  return [...found];
+}
+
+/** A path as an SBPL string literal. */
+function sbplString(path: string): string {
+  return `"${path.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/src/hooks/run-named-hook.ts

@@ -26,6 +26,7 @@ import {
 import { remoteAccessPolicy } from '../services/remote-access';
 import { loadCapabilityFunctions } from './capability-loader';
 import { invokeHook } from './executor';
+import { createHookStores } from './hook-store';
 import { loadHookConfigMap } from './load-hook-config';
 import type { HookLogger, HookName, HookResult } from './types';
 
@@ -192,6 +193,7 @@ export async function runNamedHook(
       requiredCapabilities,
       systems: getModuleSystems(moduleId, db),
       remoteAccess: remoteAccessPolicy(moduleId, db),
+      hookStores: () => createHookStores(db, moduleId),
       timeoutMs: options.timeoutMs,
     },
   );

package/src/hooks/test-fixtures/jail-probe-hook.ts

@@ -26,7 +26,7 @@ export default defineHook({
   hook: 'container_created',
   requires: [],
   handler: async (ctx) => {
-    const config = ctx.config as {
+    const config = ctx.config as unknown as {
       planted_secret: string;
       sibling_file: string;
       staged_input: string;

package/src/hooks/test-fixtures/on-restore-staging-hook.ts

@@ -0,0 +1,26 @@
+/**
+ * Test fixture: an on_restore hook in the celilo-mgmt staging shape, minus
+ * everything the real one owns but the staging itself. Copies the artifact's
+ * celilo.db into restore_dir/system/ so the Phase 4 wrapper's
+ * applyStagedSystemFiles has something to swap.
+ */
+
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'on_restore',
+  requires: [],
+  optional: [],
+  handler: async (ctx) => {
+    const restoreDir = (ctx as unknown as { restore_dir: string }).restore_dir;
+    const systemDir = join(restoreDir, 'system');
+    mkdirSync(systemDir, { recursive: true });
+    const artifactDb = join(restoreDir, 'celilo.db');
+    if (existsSync(artifactDb)) {
+      cpSync(artifactDb, join(systemDir, 'celilo.db'));
+    }
+    return { restored_items: 1 };
+  },
+});