@celilo/cli 2.1.0 → 2.2.1

package/src/hooks/hook-trespass.test.ts

@@ -31,9 +31,11 @@ import {
   listUnpublishedWorkspacePackages,
   planFallbacks,
 } from '../../../../scripts/workspace-fallback';
-import { executeHookScript, hookChildEnv } from './executor';
+import { CLI_BIN_DIR, childPath, executeHookScript, hookChildEnv } from './executor';
+import { HOOK_PROTOCOL_VERSION } from './hook-protocol';
 import { detectJailBackend, jailPolicy } from './jail';
 import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 
 const TRESPASS_SCRIPT = resolve(
@@ -154,8 +156,8 @@ afterAll(() => {
 async function runTrespass(jail = false): Promise<{ report: TrespassReport; lines: string[] }> {
   const { logger, messages } = createCapturingLogger();
   const context: HookContext = {
-    config: { sibling_module_id: 'hello-foo', other_system_ip: '' },
-    secrets: {},
+    config: configStore({ sibling_module_id: 'hello-foo', other_system_ip: '' }),
+    secrets: secretStore(),
     systems: [],
     logger,
     debug: false,
@@ -200,8 +202,11 @@ describe('the child environment is an allow-list', () => {
 
       expect(env.CELILO_HOOK_SOCKET).toBe('/tmp/celilo-hook-x/s');
       expect(env.CELILO_HOOK_REMOTE_SOCKET).toBe('/tmp/celilo-hook-x/r');
-      expect(env.CELILO_HOOK_PROTOCOL_VERSION).toBe('1');
-      expect(env.PATH).toBe(process.env.PATH as string);
+      // Pinned to the constant, not the literal: the version moves when the
+      // wire does (2 added the hook-owned-state store frames), and this line
+      // is part of the handshake's contract, not a second copy of the number.
+      expect(env.CELILO_HOOK_PROTOCOL_VERSION).toBe(String(HOOK_PROTOCOL_VERSION));
+      expect(env.PATH).toBe(childPath(process.env.PATH));
       expect(env.HOME).toBe(process.env.HOME as string);
       expect(env.CELILO_TEST_SECRET).toBeUndefined();
 
@@ -237,6 +242,35 @@ describe('the child environment is an allow-list', () => {
       if (saved !== undefined) process.env.TZ = saved;
     }
   });
+
+  // celilo#1300: a hook that spawns `celilo` by name must find the same CLI
+  // the parent runs, whatever the inherited PATH looks like.
+  describe('childPath', () => {
+    test('prepends the CLI bin and runtime directories so the child reaches the parent CLI', () => {
+      const child = childPath('/usr/local/bin:/usr/bin');
+      expect(child.startsWith(`${CLI_BIN_DIR}:${dirname(process.execPath)}:`)).toBe(true);
+      expect(child.endsWith('/usr/local/bin:/usr/bin')).toBe(true);
+    });
+
+    test('leaves an inherited PATH that already carries the directories unchanged', () => {
+      const already = `${CLI_BIN_DIR}:${dirname(process.execPath)}:/usr/bin`;
+      expect(childPath(already)).toBe(already);
+    });
+
+    test('substitutes both directories when the parent has no PATH at all', () => {
+      expect(childPath(undefined)).toBe(`${CLI_BIN_DIR}:${dirname(process.execPath)}`);
+    });
+
+    // The fleet gate (ce-y0fd): the .deb layout runs the CLI through
+    // $CELILO_HOME/node_modules/@celilo/cli/bin/celilo, so the directory beside
+    // process.execPath holds only bun and holds no celilo. A PATH that resolves
+    // `celilo` must therefore come from the CLI package's own bin directory —
+    // and that directory must really contain the bin, or every prepended PATH
+    // entry is decoration over the same accident celilo#1300 recorded.
+    test('prepends a CLI bin directory that actually contains the celilo bin', () => {
+      expect(existsSync(join(CLI_BIN_DIR, 'celilo'))).toBe(true);
+    });
+  });
 });
 
 describe('hook process boundary — hello-trespass gate', () => {

package/src/hooks/jail.test.ts

@@ -27,6 +27,7 @@ import {
   readJailMode,
   realpathRequest,
   recordJailMode,
+  resolveJailPolicy,
   runtimeModulePathsFor,
 } from './jail';
 import { deriveMountSet } from './mount-set';
@@ -137,7 +138,7 @@ describe('a mount whose source is missing is dropped, not fatal', () => {
       'auto',
       exists,
     );
-    expect(skipped).toContain(missing);
+    expect(skipped.map((m) => m.path)).toContain(missing);
     expect(cmd.join(' ')).not.toContain(missing);
   });
 
@@ -272,8 +273,12 @@ describe('jailPolicy reads the operator’s switch', () => {
     }
   };
 
-  test('unset is auto', () => {
-    expect(withEnv(undefined, jailPolicy)).toBe('auto');
+  test('unset is off (peba, ce-rez7)', () => {
+    expect(withEnv(undefined, jailPolicy)).toBe('off');
+  });
+
+  test('an explicit auto still means auto', () => {
+    expect(withEnv('auto', jailPolicy)).toBe('auto');
   });
 
   test('a typo is refused rather than silently meaning auto', () => {
@@ -284,6 +289,60 @@ describe('jailPolicy reads the operator’s switch', () => {
   });
 });
 
+describe('resolveJailPolicy applies D2 precedence (hook-jail-config-surface)', () => {
+  test('an env value set and non-empty wins over stored config', () => {
+    expect(resolveJailPolicy('required', 'off')).toEqual({ policy: 'required', source: 'env' });
+  });
+
+  test('an EMPTY STRING env value counts as unset and falls through to config', () => {
+    // jailPolicy() already treats '' as unset, so the resolver agrees rather
+    // than inventing a second rule for what counts as set.
+    expect(resolveJailPolicy('', 'off')).toEqual({ policy: 'off', source: 'config' });
+  });
+
+  test('stored config wins when the env var is absent', () => {
+    expect(resolveJailPolicy(undefined, 'off')).toEqual({ policy: 'off', source: 'config' });
+    expect(resolveJailPolicy(undefined, 'required')).toEqual({
+      policy: 'required',
+      source: 'config',
+    });
+  });
+
+  test('both absent resolves to off from the default (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy(undefined, undefined)).toEqual({ policy: 'off', source: 'default' });
+    expect(resolveJailPolicy('', undefined)).toEqual({ policy: 'off', source: 'default' });
+  });
+
+  test('an explicit env auto still wins (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy('auto', 'off')).toEqual({ policy: 'auto', source: 'env' });
+  });
+
+  test('a stored empty jail_policy THROWS, it does not resolve to auto (peba, ce-8832)', () => {
+    // The set-time pattern ^(auto|off|required)$ rejects '', so a stored one
+    // can only arrive via a restore from file or a hand edit to the DB — the
+    // untrusted paths D3 exists to catch. It is outside the enum and fails
+    // closed like any other bad stored value.
+    expect(() => resolveJailPolicy(undefined, '')).toThrow(/is not a hook jail policy/);
+    expect(() => resolveJailPolicy(undefined, '')).toThrow(/hooks\.jail_policy=''/);
+  });
+
+  test('a typo in the STORED row is refused, not silently treated as auto (D3)', () => {
+    // The DB row is a trust boundary like any other (Rule 3.7): restores carry
+    // foreign state, and a typo that silently meant `auto` reads as an armed
+    // jail when nothing is armed. The config path is no laxer than the env
+    // path.
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe')).toThrow(/is not a hook jail policy/);
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe')).toThrow(
+      /hooks\.jail_policy='alwayssafe'/,
+    );
+  });
+
+  test('a typo in the env value is still refused (unchanged jailPolicy behaviour)', () => {
+    expect(() => resolveJailPolicy('requried', undefined)).toThrow(/is not a hook jail policy/);
+    expect(() => resolveJailPolicy('requried', 'off')).toThrow(/CELILO_HOOK_JAIL='requried'/);
+  });
+});
+
 describe('realpath at the caller (task 4.2k)', () => {
   test('a symlinked module root is resolved before it becomes a bind', () => {
     // `mod.sourcePath` comes out of the database, and a database restored from

package/src/hooks/jail.ts

@@ -40,6 +40,7 @@ import { dirname, join } from 'node:path';
 import { getDataDir } from '../config/paths';
 import { HOOK_SOCKET_ENV } from './hook-protocol';
 import {
+  type MountEntry,
   type MountSet,
   type MountSetRequest,
   deriveMountSet,
@@ -132,13 +133,19 @@ export interface JailPlan {
    *
    * bubblewrap fails the whole jail on a bind whose SOURCE is missing, and
    * several rows are legitimately absent: `/lib64` does not exist on arm64,
-   * and `<module>/generated` only appears once celilo has generated
-   * something. Dropping them is the caller's job rather
-   * than the derivation's, which is why they are reported rather than silently
-   * filtered — a contract input landing here is a real defect and this is
-   * where it becomes visible.
+   * and `<module>/generated` only appears once celilo has generated something.
+   * Dropping them is the caller's job rather than the derivation's, which is
+   * why they are reported rather than silently filtered.
+   *
+   * @psbanka - 2026-09: these carry the whole ROW now, not just the path. They
+   * used to be `string[]`, built by `.map((e) => e.path)`, which threw away the
+   * `reason` and left the caller to classify an absence by reading a path
+   * string. It could not, so it warned about every one of them: 96 identical
+   * lines in a single `cele2e run --all`, with the one case that means silent
+   * data loss hidden among them. A signal that repeats unchanged is one every
+   * reader learns to skip.
    */
-  readonly skipped: readonly string[];
+  readonly skipped: readonly MountEntry[];
   /**
    * The directory to spawn the child in, when the backend cannot set it itself.
    *
@@ -411,16 +418,68 @@ function unavailableReason(error: unknown): string {
  * `CELILO_HOOK_JAIL=requried` that silently meant `auto` would read as the
  * jail being enforced when it is not, which is the one mistake this variable
  * exists to prevent.
+ *
+ * The unset/empty default is `off` (peba's ruling on ce-rez7): jailing must
+ * begin because someone set a switch, not because a package upgrade installed
+ * a backend. Turning the jail ON is a deliberate act.
  */
 export function jailPolicy(): JailPolicy {
   const raw = process.env.CELILO_HOOK_JAIL;
-  if (raw === undefined || raw === '') return 'auto';
+  if (raw === undefined || raw === '') return 'off';
   if (raw === 'auto' || raw === 'off' || raw === 'required') return raw;
   throw new Error(
     `CELILO_HOOK_JAIL='${raw}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
   );
 }
 
+/** Where the effective jail policy came from. Rendered by `system doctor` (D4). */
+export type JailPolicySource = 'env' | 'config' | 'default';
+
+/**
+ * Apply D2's precedence to the two sources: env wins, then stored config,
+ * then the default, which is `off` (peba's ruling on ce-rez7; see
+ * openspec/changes/hook-jail-config-surface/design.md for the reversal
+ * trigger).
+ *
+ * Pure, so both consumers (executor.ts and system-doctor.ts) can fetch the
+ * stored row themselves and stay testable without a database.
+ *
+ * The empty-string env value is treated as unset, matching `jailPolicy()`'s
+ * own handling — one rule for "what counts as set", not a second one here.
+ *
+ * The config path is deliberately stricter than the env path: a stored
+ * empty string THROWS (peba's ruling on ce-8832). The set-time pattern
+ * `^(auto|off|required)$` rejects `''`, so a stored one can only arrive via
+ * a restore from file or a hand edit to the DB — exactly the untrusted
+ * paths D3 exists to catch. Resolving it to a silent `auto` would let
+ * foreign state pick the jailing default with nobody told, and failing
+ * closed is the whole point. An empty CELILO_HOOK_JAIL stays "not set",
+ * because `jailPolicy()` relies on that and slice 1's safety rests on the
+ * two resolvers agreeing.
+ */
+export function resolveJailPolicy(
+  envValue: string | undefined,
+  configValue: string | undefined,
+): { policy: JailPolicy; source: JailPolicySource } {
+  if (envValue !== undefined && envValue !== '') {
+    if (envValue === 'auto' || envValue === 'off' || envValue === 'required') {
+      return { policy: envValue, source: 'env' };
+    }
+    throw new Error(
+      `CELILO_HOOK_JAIL='${envValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
+  if (configValue !== undefined) {
+    if (configValue === 'auto' || configValue === 'off' || configValue === 'required') {
+      return { policy: configValue, source: 'config' };
+    }
+    throw new Error(
+      `hooks.jail_policy='${configValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
+  return { policy: 'off', source: 'default' };
+}
+
 /**
  * Resolve every path in a mount-set request through the filesystem (task 4.2k).
  *
@@ -612,7 +671,7 @@ export function planJailedSpawn(
   // reaches the sandbox-exec arm while SANDBOX_EXEC_AUTO_JAIL_ENABLED is
   // false: the flag flip is D14's landing, never 4.8's.
   const present = set.entries.filter((e) => e.mode === 'tmpfs' || exists(e.path));
-  const skipped = set.entries.filter((e) => !present.includes(e)).map((e) => e.path);
+  const skipped = set.entries.filter((e) => !present.includes(e));
   const applied: MountSet = { ...set, entries: present };
 
   // Dropping an absent path is a bubblewrap NEED — it fails the whole jail on a

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

@@ -7,7 +7,11 @@
  */
 
 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 { planJailedSpawn, realpathRequest, runtimeModulePathsFor } from './jail';
 import {
   deriveMountSet,
   forbiddenPaths,
@@ -104,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({
@@ -255,3 +280,186 @@ describe('name resolution inside the jail (celilo#1225)', () => {
     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 {
@@ -154,8 +156,27 @@ const RESOLVER_FILES = ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts']
  */
 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 };
 }
 
 /**
@@ -182,21 +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'));
+    entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES', 'runtime'));
   }
   // The fleet browser, read-only (task 4.10).
   //
@@ -225,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
@@ -234,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.
@@ -256,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',
       ),
     );
   }

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;