@celilo/cli 2.1.0 → 2.2.0

package/src/hooks/hook-store.ts

@@ -0,0 +1,290 @@
+/**
+ * The broker side of the hook-owned-state accessor (hook-owned-state tasks
+ * 3.1-3.4, design option C).
+ *
+ * A hook runs out of process and reaches its own persistent state only through
+ * the wire (see `hook-protocol.ts` `StoreCallFrame`). This module is the thing
+ * those frames land on: two stores over `(db, moduleId, manifest, masterKey)`
+ * — `secrets`, validated against `manifest.secrets.declares` and encrypted,
+ * and `config`, validated against `variables.owns` where `source: hook` and
+ * stored plaintext in `module_configs`.
+ *
+ * Validation is against the MANIFEST, not the database. The whole point
+ * (design D2) is that a typo in a hook is a loud error naming the module and
+ * the declared set, never a phantom row some later reader mistakes for state.
+ *
+ * The transaction is applied inside one `db.transaction` (same mechanism as
+ * IPAM allocation in `variables/context.ts`). The buffering half lives
+ * child-side in the runner proxy, so a throwing `fn` sends no frame at all;
+ * what arrives here is a finished operation list that either applies whole or
+ * throws whole.
+ *
+ * Execution functions (Rule 10.1) — each method performs its own storage
+ * effects; construction is pure planning.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { z } from 'zod';
+import type { DbClient } from '../db/client';
+import { moduleConfigs, modules, secrets } from '../db/schema';
+import { type EncryptedSecret, decryptSecret, encryptSecret } from '../secrets/encryption';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { deleteModuleConfig, upsertModuleConfig } from '../services/module-config';
+import type { BufferedStoreOp } from './hook-protocol';
+
+/**
+ * The manifest surface the stores validate against, read out of
+ * `modules.manifestData` and narrowed. Everything else in the manifest is
+ * irrelevant here — this is deliberately a projection, not a parse of the
+ * whole schema, so a manifest feature the stores never read cannot break a
+ * hook run.
+ */
+const StoreManifestSchema = z.object({
+  secrets: z
+    .object({ declares: z.array(z.object({ name: z.string() }).passthrough()).optional() })
+    .optional(),
+  variables: z
+    .object({
+      owns: z
+        .array(z.object({ name: z.string(), source: z.string().optional() }).passthrough())
+        .optional(),
+    })
+    .optional(),
+});
+
+/** The two stores a hook may touch, keyed as the wire names them. */
+export interface HookStores {
+  readonly secrets: HookStoreBackend;
+  readonly config: HookStoreBackend;
+  /** Diagnostic mirror of what each store validates against. */
+  readonly declaredSecretNames: string[];
+  readonly declaredConfigNames: string[];
+}
+
+/**
+ * One store's answering half. Shaped like `HookStore` from
+ * `@celilo/capabilities` except that `transaction` takes the operation list
+ * the child buffered — the buffering happens there, the atomicity here.
+ */
+export interface HookStoreBackend {
+  get(name: string): Promise<string | undefined>;
+  set(name: string, value: string): Promise<void>;
+  delete(name: string): Promise<void>;
+  applyTransaction(ops: readonly BufferedStoreOp[]): Promise<void>;
+}
+
+/**
+ * Throw for an undeclared name, naming the module and the declared set
+ * (task 3.4 — ERROR, not warning, design D2).
+ */
+function undeclared(
+  moduleId: string,
+  kind: 'secret' | 'hook-owned config',
+  name: string,
+  declared: string[],
+): Error {
+  const declaredList = declared.length > 0 ? declared.join(', ') : '(none)';
+  const where =
+    kind === 'secret'
+      ? `Add '${name}' to secrets.declares in the module's manifest.yml.`
+      : `Add '${name}' to variables.owns with source: hook in the module's manifest.yml.`;
+  return new Error(
+    `Module '${moduleId}' has no declared ${kind} '${name}'. Declared ${kind} names: ${declaredList}. ${where}`,
+  );
+}
+
+/** Secrets store: encrypted rows in the `secrets` table, keyed `(moduleId, name)`. */
+function createSecretsStore(db: DbClient, moduleId: string, declared: string[]): HookStoreBackend {
+  const assertDeclared = (name: string) => {
+    if (!declared.includes(name)) throw undeclared(moduleId, 'secret', name, declared);
+  };
+
+  const upsert = (name: string, encrypted: EncryptedSecret) => {
+    const existing = db
+      .select()
+      .from(secrets)
+      .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+      .get();
+    if (existing) {
+      db.update(secrets)
+        .set({
+          encryptedValue: encrypted.encryptedValue,
+          iv: encrypted.iv,
+          authTag: encrypted.authTag,
+          updatedAt: new Date(),
+        })
+        .where(eq(secrets.id, existing.id))
+        .run();
+    } else {
+      db.insert(secrets)
+        .values({ moduleId, name, ...encrypted })
+        .run();
+    }
+  };
+
+  return {
+    async get(name) {
+      assertDeclared(name);
+      const row = db
+        .select()
+        .from(secrets)
+        .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+        .get();
+      if (!row) return undefined;
+      const masterKey = await getOrCreateMasterKey();
+      return decryptSecret(
+        { encryptedValue: row.encryptedValue, iv: row.iv, authTag: row.authTag },
+        masterKey,
+      );
+    },
+
+    async set(name, value) {
+      assertDeclared(name);
+      const masterKey = await getOrCreateMasterKey();
+      upsert(name, encryptSecret(value, masterKey));
+    },
+
+    async delete(name) {
+      assertDeclared(name);
+      db.delete(secrets)
+        .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+        .run();
+    },
+
+    async applyTransaction(ops) {
+      // Validate EVERY name before writing ANY row: a batch with one undeclared
+      // name must discard whole, not half-apply then throw (task 3.7).
+      for (const entry of ops) assertDeclared(entry.name);
+      const masterKey = await getOrCreateMasterKey();
+      db.transaction((tx) => {
+        for (const entry of ops) {
+          if (entry.op === 'set') {
+            upsertTx(
+              tx as unknown as DbClient,
+              entry.name,
+              encryptSecret(entry.value ?? '', masterKey),
+            );
+          } else {
+            tx.delete(secrets)
+              .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, entry.name)))
+              .run();
+          }
+        }
+      });
+    },
+  };
+
+  function upsertTx(tx: DbClient, name: string, encrypted: EncryptedSecret): void {
+    const existing = tx
+      .select()
+      .from(secrets)
+      .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+      .get();
+    if (existing) {
+      tx.update(secrets)
+        .set({
+          encryptedValue: encrypted.encryptedValue,
+          iv: encrypted.iv,
+          authTag: encrypted.authTag,
+          updatedAt: new Date(),
+        })
+        .where(eq(secrets.id, existing.id))
+        .run();
+    } else {
+      tx.insert(secrets)
+        .values({ moduleId, name, ...encrypted })
+        .run();
+    }
+  }
+}
+
+/** Config store: plaintext rows in `module_configs`, `source: hook`. */
+function createConfigStore(db: DbClient, moduleId: string, declared: string[]): HookStoreBackend {
+  const assertDeclared = (name: string) => {
+    if (!declared.includes(name)) {
+      throw undeclared(moduleId, 'hook-owned config', name, declared);
+    }
+  };
+
+  return {
+    async get(name) {
+      assertDeclared(name);
+      const row = db
+        .select()
+        .from(moduleConfigs)
+        .where(and(eq(moduleConfigs.moduleId, moduleId), eq(moduleConfigs.key, name)))
+        .get();
+      // Hook-owned rows are always written through `set`, so `valueJson` holds
+      // a JSON string literal of exactly what the hook sent. Absent means never
+      // written; null valueJson is a legacy row shape no hook-owned key can
+      // have (the source column did not exist when those were written).
+      if (!row?.valueJson) return undefined;
+      const parsed: unknown = JSON.parse(row.valueJson);
+      return typeof parsed === 'string' ? parsed : JSON.stringify(parsed);
+    },
+
+    async set(name, value) {
+      assertDeclared(name);
+      upsertModuleConfig(db, moduleId, name, value, 'hook');
+    },
+
+    async delete(name) {
+      assertDeclared(name);
+      deleteModuleConfig(db, moduleId, name);
+    },
+
+    async applyTransaction(ops) {
+      for (const entry of ops) assertDeclared(entry.name);
+      db.transaction((tx) => {
+        // Same narrowing the secrets store applies below: drizzle hands the
+        // callback a transaction handle, and module-config's writers accept
+        // the full client it derives from.
+        const txDb = tx as unknown as DbClient;
+        for (const entry of ops) {
+          if (entry.op === 'set') {
+            upsertModuleConfig(txDb, moduleId, entry.name, entry.value ?? '', 'hook');
+          } else {
+            deleteModuleConfig(txDb, moduleId, entry.name);
+          }
+        }
+      });
+    },
+  };
+}
+
+/**
+ * Build both stores for a module from its stored manifest.
+ *
+ * The master key is NOT touched here — it loads lazily inside the operations
+ * that need it, so building stores for a hook that never writes a secret has
+ * no key-file side effect.
+ *
+ * Execution function — reads the module row. Throws when the module row or its
+ * manifest is missing, because a hook for a module celilo cannot describe is a
+ * run that cannot be attributed.
+ */
+export async function createHookStores(db: DbClient, moduleId: string): Promise<HookStores> {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    throw new Error(`Cannot build hook stores: module '${moduleId}' not found.`);
+  }
+
+  const parsed = StoreManifestSchema.safeParse(module.manifestData);
+  if (!parsed.success) {
+    throw new Error(
+      `Cannot build hook stores for '${moduleId}': stored manifest does not match the expected shape (${parsed.error.issues[0]?.message ?? 'invalid'}).`,
+    );
+  }
+
+  const declaredSecretNames = (parsed.data.secrets?.declares ?? []).map((s) => s.name);
+  const declaredConfigNames = (parsed.data.variables?.owns ?? [])
+    .filter((v) => v.source === 'hook')
+    .map((v) => v.name);
+
+  return {
+    secrets: createSecretsStore(db, moduleId, declaredSecretNames),
+    config: createConfigStore(db, moduleId, declaredConfigNames),
+    declaredSecretNames,
+    declaredConfigNames,
+  };
+}

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

@@ -23,6 +23,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { executeHookScript } from './executor';
 import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 
 const FIXTURES = join(__dirname, 'test-fixtures');
@@ -40,8 +41,8 @@ function scratch(): string {
 
 function contextFor(config: Record<string, unknown>): HookContext {
   return {
-    config,
-    secrets: {},
+    config: configStore(config),
+    secrets: secretStore(),
     systems: [],
     logger: createCapturingLogger().logger,
     debug: false,

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

@@ -31,9 +31,11 @@ import {
   listUnpublishedWorkspacePackages,
   planFallbacks,
 } from '../../../../scripts/workspace-fallback';
-import { executeHookScript, hookChildEnv } from './executor';
+import { 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,25 @@ 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 runtime directory so the child reaches the parent CLI', () => {
+      const child = childPath('/usr/local/bin:/usr/bin');
+      expect(child.startsWith(`${dirname(process.execPath)}:`)).toBe(true);
+      expect(child.endsWith('/usr/local/bin:/usr/bin')).toBe(true);
+    });
+
+    test('leaves an inherited PATH that already carries the directory unchanged', () => {
+      const already = `${dirname(process.execPath)}:/usr/bin`;
+      expect(childPath(already)).toBe(already);
+    });
+
+    test('substitutes the directory when the parent has no PATH at all', () => {
+      expect(childPath(undefined)).toBe(dirname(process.execPath));
+    });
+  });
 });
 
 describe('hook process boundary — hello-trespass gate', () => {

package/src/hooks/jail.test.ts

@@ -137,7 +137,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);
   });
 

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.
    *
@@ -612,7 +619,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();
+    }
+  });
+});