@celilo/cli 2.0.0 → 2.2.0

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

@@ -31,8 +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(
@@ -150,11 +153,11 @@ afterAll(() => {
   rmSync(scratchHome, { recursive: true, force: true });
 });
 
-async function runTrespass(): Promise<{ report: TrespassReport; lines: string[] }> {
+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,
@@ -163,14 +166,28 @@ async function runTrespass(): Promise<{ report: TrespassReport; lines: string[]
     capabilities: {},
   };
 
-  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, {
-    timeoutMs: 60_000,
-    idleTimeoutMs: 60_000,
-  });
-  return {
-    report: outputs as unknown as TrespassReport,
-    lines: messages.map((m) => m.message),
-  };
+  // The jailed run jails under `required`, not the `auto` default. ce-29z
+  // made `auto` defer on sandbox-exec until D14 exists (undeclared host-path
+  // writes would break module hooks), so the test's jail is the operator's
+  // explicit act — exactly the bypass the deferral leaves open.
+  const savedPolicy = process.env.CELILO_HOOK_JAIL;
+  if (jail) process.env.CELILO_HOOK_JAIL = 'required';
+  try {
+    const outputs = await executeHookScript(TRESPASS_SCRIPT, context, {
+      timeoutMs: 60_000,
+      idleTimeoutMs: 60_000,
+      // The module's own tree, two levels above the hook script. Absent means
+      // "run unjailed", which is what the stage 1 assertions below need.
+      ...(jail ? { jail: { modulePath: dirname(dirname(TRESPASS_SCRIPT)), pathInputs: [] } } : {}),
+    });
+    return {
+      report: outputs as unknown as TrespassReport,
+      lines: messages.map((m) => m.message),
+    };
+  } finally {
+    if (savedPolicy === undefined) delete process.env.CELILO_HOOK_JAIL;
+    else process.env.CELILO_HOOK_JAIL = savedPolicy;
+  }
 }
 
 describe('the child environment is an allow-list', () => {
@@ -185,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();
 
@@ -222,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', () => {
@@ -251,3 +290,44 @@ describe('hook process boundary — hello-trespass gate', () => {
     expect(report.ssh_key.attempted && !report.ssh_key.succeeded).toBe(false);
   });
 });
+
+const availability = detectJailBackend();
+const jailed = availability.backend !== 'none' && jailPolicy() !== 'off';
+
+describe.skipIf(!jailed)(
+  `stage 2: the same hook, jailed (backend: ${availability.backend})`,
+  () => {
+    // Task 4.12's platform half that a Mac can run. The e2e stage
+    // (`e2e/tests/hook-jail-trespass.test.ts`) is the other one, because
+    // bubblewrap needs a Linux kernel and a container to hold it.
+    //
+    // The SAME fixture, run twice, is the whole design of this gate: the stage 1
+    // block above asserts these two trespasses SUCCEED, and this one asserts the
+    // jail refuses them. Neither reading is available from one run.
+    test('trespasses 1 and 2 are refused, and the environment is still clean', async () => {
+      const { report, lines } = await runTrespass(true);
+      console.log(['', 'hello-trespass (jailed):', ...lines.slice(1)].join('\n'));
+
+      // What stage 2 claims: celilo's data directory is not bound, so the master
+      // key is unreachable. `<store>` is not bound either, so a sibling is too.
+      expect(report.master_key.succeeded).toBe(false);
+      expect(report.sibling_write.succeeded).toBe(false);
+
+      // Unreachability, never an errno. bubblewrap removes the path and reports
+      // ENOENT; sandbox-exec denies it and reports EPERM. Pinning either one
+      // would go red on a platform whose jail works perfectly (D9).
+      expect(report.master_key.detail).toMatch(/ENOENT|EPERM/);
+
+      // Stage 1's claim has not regressed on the way to stage 2.
+      expect(report.sensitive_env).toEqual([]);
+    }, 120_000);
+
+    // Trespass 3 is deliberately NOT asserted here, and the reason is a property
+    // of this fixture rather than of the jail. `jailRequest` binds `~/.ssh` from
+    // `os.homedir()`, which on macOS reads the password database and ignores the
+    // `HOME` this file redirects — so the hook looks in the scratch home and the
+    // jail bound the real one, and the row reports a refusal that says nothing
+    // about stage 3. The e2e stage asserts it, where the two agree. Filed as
+    // celilo#1211.
+  },
+);

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

@@ -21,22 +21,32 @@
  *     reads.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import type { Dirent } from 'node:fs';
 import {
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   readdirSync,
   realpathSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { hostname } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { getDataDir } from '../config/paths';
-import { type MountSet, type MountSetRequest, toBwrapArgs } from './mount-set';
+import { HOOK_SOCKET_ENV } from './hook-protocol';
+import {
+  type MountEntry,
+  type MountSet,
+  type MountSetRequest,
+  deriveMountSet,
+  toBwrapArgs,
+  toSandboxProfile,
+} from './mount-set';
 import { JAIL_PROVIDED_PATHS } from './unjailed-lint';
 
 /**
@@ -123,13 +133,31 @@ 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 MountEntry[];
+  /**
+   * The directory to spawn the child in, when the backend cannot set it itself.
+   *
+   * bubblewrap takes `--chdir`, so its plans leave this absent and the child
+   * inherits celilo's cwd — which the jail has replaced anyway.
+   * `sandbox-exec` has no equivalent, so the child inherits the OPERATOR's cwd
+   * and the profile does not name it. Measured 2026-08-27: `bun` reads its
+   * working directory before running anything, so a cwd outside the profile
+   * kills it with `error: An unknown error occurred (Unexpected)` and no
+   * further diagnostic. Naming the mount set's `chdir` here is the fix.
    */
-  readonly skipped: readonly string[];
+  readonly cwd?: string;
 }
 
 /**
@@ -186,6 +214,24 @@ const JAIL_NAMESPACE_ARGS = [
  */
 const BWRAP = 'bwrap';
 
+/**
+ * The macOS jail builder.
+ *
+ * Pinned absolute, unlike `BWRAP`. There is no AppArmor-style profile to miss
+ * here, so `PATH` buys nothing and costs the one thing that matters: a
+ * `sandbox-exec` earlier on `PATH` would be handed every hook's profile and
+ * could report a jail it never built. The probe below would catch that, and
+ * pinning means it never has to.
+ */
+const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+
+/**
+ * The runner shim, named here as well as in the executor because the probe has
+ * to spawn the REAL one. A probe that starts a smaller program answers a
+ * question about a smaller program.
+ */
+const HOOK_RUNNER_PATH = join(import.meta.dir, 'hook-runner.ts');
+
 /** How long to wait for the probe before calling the backend unavailable. */
 const PROBE_TIMEOUT_MS = 10_000;
 
@@ -213,17 +259,7 @@ export function detectJailBackend(): JailAvailability {
 }
 
 function probeJailBackend(): JailAvailability {
-  if (process.platform === 'darwin') {
-    // `sandbox-exec` is measured working (D8) but the backend that generates
-    // its profile is task 4.8 and is not built. Claiming macOS is jailed
-    // because the tool exists would be the fail-open jail D8 calls worse than
-    // no jail at all.
-    return {
-      backend: 'none',
-      reason:
-        'macOS has no hook jail yet: the sandbox-exec backend is designed but not built (hook-process-boundary task 4.8). Hooks run unjailed on this host.',
-    };
-  }
+  if (process.platform === 'darwin') return probeSandboxExec();
   if (process.platform !== 'linux') {
     return {
       backend: 'none',
@@ -243,6 +279,118 @@ function probeJailBackend(): JailAvailability {
   }
 }
 
+/**
+ * What the probe plants and then tries to read. Its ABSENCE from the output is
+ * the evidence, so it is a string nothing else would print.
+ */
+const SANDBOX_PROBE_MARKER = 'celilo-jail-probe-reached-the-planted-file';
+
+/**
+ * Can this Mac jail? Measured by proving a DENIAL, never by finding the binary.
+ *
+ * This probe is shaped differently from bubblewrap's and the difference is the
+ * point. bubblewrap FAILS when it cannot build a namespace, loudly, with one of
+ * four distinct denials — so running it at all is the measurement.
+ * `sandbox-exec` does not fail. A profile it cannot apply to a path is simply
+ * not applied: the access succeeds and nothing anywhere reports an error (D8,
+ * measured, and re-measured 2026-08-27 in both directions — a rule naming
+ * `/tmp/x` where the kernel sees `/private/tmp/x` neither denies nor grants).
+ *
+ * So "sandbox-exec exists" is not evidence of anything, and neither is "the
+ * profile parsed". The only honest question is whether a file this probe
+ * planted, outside the profile, is actually unreachable from inside it. That is
+ * CLAUDE.md's reach probe applied to the jail itself: plant a marker, run the
+ * REAL machinery, and read which markers fired.
+ *
+ * Three outcomes, and the middle one is the one worth having:
+ *
+ *   - the read was refused          → `sandbox-exec`, the jail is real
+ *   - the read SUCCEEDED            → `none`, and the reason says fail-open.
+ *     A jail that is believed and absent is worse than no jail (D8).
+ *   - `sandbox-exec` never ran      → `none`, with its own message
+ */
+function probeSandboxExec(): JailAvailability {
+  let scratch: string | undefined;
+  try {
+    scratch = mkdtempSync(join(realpathOrSelf(tmpdir()), 'celilo-jail-probe-'));
+    const allowed = join(scratch, 'allowed');
+    const planted = join(scratch, 'planted');
+    mkdirSync(join(allowed, 'state'), { recursive: true });
+    writeFileSync(planted, SANDBOX_PROBE_MARKER);
+
+    // The REAL derivation, the REAL renderer, and the REAL shim path, so this
+    // clears the same bar the spawn does. Every shortcut here has already been
+    // measured to matter: a mount set built around `bun -e` omits the shim's
+    // `node_modules` rows, and the runtime then starts under the probe's
+    // profile and dies under the executor's.
+    const profile = toSandboxProfile(
+      deriveMountSet({
+        modulePath: allowed,
+        stateDir: join(allowed, 'state'),
+        socketDir: allowed,
+        runtimePath: process.execPath,
+        runnerPath: HOOK_RUNNER_PATH,
+        runtimeModulePaths: runtimeModulePathsFor(HOOK_RUNNER_PATH),
+        pathInputs: [],
+      }),
+    );
+    const run = (cmd: readonly string[]) =>
+      spawnSync(SANDBOX_EXEC, ['-p', profile, '--', ...cmd], {
+        cwd: allowed,
+        encoding: 'utf-8',
+        timeout: PROBE_TIMEOUT_MS,
+      });
+
+    // 1. Can the RUNTIME start? Spawn the actual shim with no socket in its
+    //    environment: it refuses immediately with a known message, having
+    //    already loaded itself, `@celilo/capabilities` and Zod. That is the
+    //    whole of the startup path, and it is where a jail that denies the
+    //    runtime something it needs shows up.
+    const started = run([process.execPath, HOOK_RUNNER_PATH]);
+    if (started.error) throw started.error;
+    if (!started.stderr?.includes(HOOK_SOCKET_ENV)) {
+      return {
+        backend: 'none',
+        reason: `sandbox-exec built a jail the hook runner cannot start in, so hooks run unjailed rather than failing one at a time. The runner exited ${started.status} saying: ${(started.stderr || started.stdout || '').trim().split('\n')[0] || '(nothing)'}`,
+      };
+    }
+
+    // 2. Does a DENIAL actually apply? `sandbox-exec` never fails on a rule it
+    //    cannot match — the access simply succeeds and nothing reports an
+    //    error (D8, measured). So the profile is not evidence; a file this
+    //    probe planted outside the mount set, and could not read, is.
+    const denied = run([
+      process.execPath,
+      '-e',
+      `try{require('node:fs').readFileSync(${JSON.stringify(planted)});console.log('${SANDBOX_PROBE_MARKER}')}catch{console.log('refused')}`,
+    ]);
+    if (denied.error) throw denied.error;
+    if ((denied.stdout ?? '').includes(SANDBOX_PROBE_MARKER)) {
+      return {
+        backend: 'none',
+        reason:
+          'sandbox-exec ran but did not enforce the profile: a file outside the mount set was still readable. Hooks run unjailed rather than appearing jailed and not being, which is the one outcome worse than no jail. This is usually an unresolved path in a rule — every path must be realpath()d before it is written.',
+      };
+    }
+
+    return { backend: 'sandbox-exec' };
+  } catch (error) {
+    const spawnFailure = (error as { code?: string } | null)?.code;
+    if (spawnFailure === 'ENOENT') {
+      return {
+        backend: 'none',
+        reason: `${SANDBOX_EXEC} is not on this macOS, so hooks run unjailed. It has carried a deprecation notice since 10.8; if Apple has removed it, this host has no hook jail backend.`,
+      };
+    }
+    return {
+      backend: 'none',
+      reason: `sandbox-exec could not run the probe, so hooks run unjailed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
 /**
  * Turn the probe's failure into something an operator can act on.
  *
@@ -467,21 +615,35 @@ export function planJailedSpawn(
   }
 
   // A tmpfs needs no source — bubblewrap creates it — so it is never dropped.
-  // @psbanka-agent note (ce-29z, 2026-09): with SANDBOX_EXEC_AUTO_JAIL_ENABLED
-  // still false, the only way to reach this line with a sandbox-exec
-  // availability is policy 'required', and task 4.8 owns the spawn arm that
-  // makes that real. Until it lands, do not flip the flag.
+  // The note below (ce-29z, 2026-09) is why 'required' is the only policy that
+  // 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
+  // bind with no source — and is merely tidy for `sandbox-exec`, which happily
+  // names a path that is not there. Both backends drop the same rows anyway,
+  // because a mount set that means two things on two platforms is exactly the
+  // drift task 4.7 exists to prevent.
+  if (availability.backend === 'sandbox-exec') {
+    // `-p` rather than a profile FILE: nothing to create, nothing to clean
+    // up, and nothing whose own readability has to be reasoned about.
+    // `sandbox-exec` reads the profile before it applies the sandbox, so a
+    // file would not have needed to be in the mount set — but it would have
+    // needed a lifetime, and this has none.
+    return {
+      cmd: [SANDBOX_EXEC, '-p', toSandboxProfile(applied), '--', ...cmd],
+      mode: 'jailed',
+      backend: availability.backend,
+      skipped,
+      cwd: set.chdir,
+    };
+  }
 
   return {
-    cmd: [
-      BWRAP,
-      ...JAIL_NAMESPACE_ARGS,
-      ...toBwrapArgs({ ...set, entries: present }),
-      '--',
-      ...cmd,
-    ],
+    cmd: [BWRAP, ...JAIL_NAMESPACE_ARGS, ...toBwrapArgs(applied), '--', ...cmd],
     mode: 'jailed',
     backend: availability.backend,
     skipped,