@celilo/cli 1.13.0 → 2.0.0

package/src/hooks/jail.ts

@@ -37,9 +37,57 @@ import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { getDataDir } from '../config/paths';
 import { type MountSet, type MountSetRequest, toBwrapArgs } from './mount-set';
+import { JAIL_PROVIDED_PATHS } from './unjailed-lint';
 
-/** Which jail celilo can build here. `none` means the hook runs unjailed. */
-export type JailBackend = 'bubblewrap' | 'none';
+/**
+ * Which jail celilo can build here. `none` means the hook runs unjailed.
+ *
+ * `sandbox-exec` is in the union ahead of its backend (task 4.8) because the
+ * POLICY for it is decided and landed first (ce-29z): `auto` defers on it
+ * until D14's declared-path mounts exist, and the planner below enforces
+ * that whether or not a platform reports the backend yet.
+ */
+export type JailBackend = 'bubblewrap' | 'sandbox-exec' | 'none';
+
+/**
+ * Whether `auto` may jail through `sandbox-exec`.
+ *
+ * False on purpose, and the load-bearing fact of ce-29z. Measured there,
+ * same hardware, one variable (`CELILO_HOOK_JAIL=off` equals main's
+ * behaviour): under bubblewrap a fixture hook's write to an undeclared host
+ * path lands in the private tmpfs (D13b) and succeeds silently, while under
+ * `sandbox-exec` the same write is `EPERM` — the hook exits non-zero and the
+ * full `apps/celilo` suite goes red on macOS where it is green on Linux CI.
+ * Sandbox-exec DENIES rather than masks, so the macOS jail is stricter than
+ * the Linux one for exactly the paths nobody declared.
+ *
+ * The mechanism that declares them is D14 (`type: path` on a manifest
+ * variable), and D14 is not built speculatively — task 4.2a measured the
+ * population and found no consumer that survives D9b. So `auto` defers on
+ * this backend until that mechanism lands; flip this to `true` as part of
+ * that landing, never before. `CELILO_HOOK_JAIL=required` bypasses the
+ * deferral: it is the operator's explicit act (D8), and an operator who sets
+ * it on macOS has opted into the strictness.
+ */
+const SANDBOX_EXEC_AUTO_JAIL_ENABLED = false;
+
+/**
+ * Why an `auto` sandbox-exec spawn was deferred. Operator-facing: it names
+ * the decision and the one way past it. Exported because `system doctor`
+ * renders the same deferral from (policy, availability) alone, where no plan
+ * — and so no plan reason — exists yet.
+ */
+export const SANDBOX_EXEC_AUTO_DEFERRED_REASON =
+  'macOS hooks run unjailed: sandbox-exec denies (EPERM) a hook write to any host path the mount set does not declare, where bubblewrap masks it into its private tmpfs — undeclared config paths would break module hooks on this host. The declaration mechanism (D14, manifest `type: path`) is not built, so auto defers on this backend (ce-29z). Set CELILO_HOOK_JAIL=required to jail anyway.';
+
+/**
+ * Does `auto` defer on this backend? Shared by the planner and by
+ * `system doctor`, so the doctor cannot report a jail the executor will not
+ * build.
+ */
+export function autoJailDefers(availability: JailAvailability): boolean {
+  return availability.backend === 'sandbox-exec' && !SANDBOX_EXEC_AUTO_JAIL_ENABLED;
+}
 
 /**
  * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `auto`.
@@ -75,8 +123,8 @@ 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,
-   * `<module>/generated` only appears once celilo has generated something, and
-   * `~/.ssh` need not exist at all. Dropping them is the caller's job rather
+   * 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.
@@ -104,7 +152,17 @@ export interface JailPlan {
  * `--new-session` is NOT here. It defends against TIOCSTI injection into a
  * controlling terminal, and the child is spawned with `stdout: 'pipe'` and no
  * tty, so there is nothing to inject into.
+ *
+ * The `--proc`/`--dev` pairs are BUILT from `JAIL_PROVIDED_PATHS`
+ * (unjailed-lint.ts), the same list the advisory lint reads, so the spawn and
+ * the lint cannot disagree about what the namespace itself provides. Adding a
+ * path to that constant without a flag here is a compile error.
  */
+const JAIL_PROVIDED_FLAGS: Record<(typeof JAIL_PROVIDED_PATHS)[number], string> = {
+  '/proc': '--proc',
+  '/dev': '--dev',
+};
+
 const JAIL_NAMESPACE_ARGS = [
   '--unshare-user',
   '--unshare-ipc',
@@ -113,10 +171,7 @@ const JAIL_NAMESPACE_ARGS = [
   // The one unshare that legitimately may be unavailable on an older kernel.
   '--unshare-cgroup-try',
   '--die-with-parent',
-  '--proc',
-  '/proc',
-  '--dev',
-  '/dev',
+  ...JAIL_PROVIDED_PATHS.flatMap((path) => [JAIL_PROVIDED_FLAGS[path], path]),
 ] as const;
 
 /**
@@ -258,7 +313,6 @@ export function realpathRequest(request: MountSetRequest): MountSetRequest {
       ...input,
       value: realpathOrSelf(input.value),
     })),
-    sshDir: request.sshDir ? realpathOrSelf(request.sshDir) : undefined,
   };
 }
 
@@ -362,6 +416,14 @@ function realpathOrSelf(path: string): string {
  * @param set - The derived mount set, or `undefined` when the caller has no
  *   module tree to jail (the executor's own fixtures, and the bus handler path).
  */
+/**
+ * Why an `off` policy runs unjailed, shared with `celilo system doctor` (task
+ * 4.6) so the sentence the operator reads there is the sentence the record
+ * carries.
+ */
+export const JAIL_OFF_REASON =
+  'CELILO_HOOK_JAIL=off: the operator switched the hook jail off on this host.';
+
 export function planJailedSpawn(
   cmd: readonly string[],
   set: MountSet | undefined,
@@ -374,7 +436,7 @@ export function planJailedSpawn(
       cmd,
       mode: 'unjailed',
       backend: availability.backend,
-      reason: 'CELILO_HOOK_JAIL=off: the operator switched the hook jail off on this host.',
+      reason: JAIL_OFF_REASON,
       skipped: [],
     };
   }
@@ -391,7 +453,24 @@ export function planJailedSpawn(
     return { cmd, mode: 'unjailed', backend: availability.backend, reason, skipped: [] };
   }
 
+  // ce-29z: auto defers on sandbox-exec until D14 exists. Not an availability
+  // question — the backend is there; it is a policy one, which is why this
+  // sits in the planner rather than the probe.
+  if (policy === 'auto' && autoJailDefers(availability)) {
+    return {
+      cmd,
+      mode: 'unjailed',
+      backend: availability.backend,
+      reason: SANDBOX_EXEC_AUTO_DEFERRED_REASON,
+      skipped: [],
+    };
+  }
+
   // 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.
   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);
 
@@ -423,6 +502,20 @@ export interface JailModeRecord {
    */
   readonly host: string;
   readonly recordedAt: string;
+  /**
+   * The jailed record this host most recently held, present only on an
+   * `unjailed` record that replaced one on the SAME host.
+   *
+   * This is what makes the jailed-to-unjailed transition durable. The write
+   * below overwrites the previous record, so without this field the file for
+   * a host that used to jail and has stopped reads identically to a Mac that
+   * never jailed — and the self-monitor (task 4.4) runs on a sweep, long
+   * after `recordJailMode`'s return value is gone.
+   */
+  readonly lastJailed?: {
+    readonly backend: JailBackend;
+    readonly recordedAt: string;
+  };
 }
 
 /**
@@ -457,12 +550,14 @@ export function readJailMode(): JailModeRecord | undefined {
  */
 export function recordJailMode(plan: JailPlan): { previous?: JailModeRecord } {
   const previous = readJailMode();
+  const host = hostname();
   const record: JailModeRecord = {
     mode: plan.mode,
     backend: plan.backend,
     ...(plan.reason ? { reason: plan.reason } : {}),
-    host: hostname(),
+    host,
     recordedAt: new Date().toISOString(),
+    ...(lastJailedFor(plan.mode, previous, host) ?? {}),
   };
 
   if (
@@ -489,3 +584,25 @@ export function recordJailMode(plan: JailPlan): { previous?: JailModeRecord } {
   }
   return { previous };
 }
+
+/**
+ * What an unjailed record remembers about the last time this host jailed.
+ *
+ * A record from a DIFFERENT host contributes nothing: that is the
+ * copied-between-boxes case the `host` field exists for, and reading it as a
+ * transition would alert on a move that regressed nothing. A jailed record
+ * remembers nothing either — re-jailing is the recovery, and a later
+ * regression should date from the NEW jailed record, not the first ever.
+ */
+function lastJailedFor(
+  mode: JailMode,
+  previous: JailModeRecord | undefined,
+  host: string,
+): Pick<JailModeRecord, 'lastJailed'> | undefined {
+  if (mode !== 'unjailed' || !previous || previous.host !== host) return undefined;
+  if (previous.mode === 'jailed') {
+    return { lastJailed: { backend: previous.backend, recordedAt: previous.recordedAt } };
+  }
+  // unjailed → unjailed (a backend or reason change): the memory rides along.
+  return previous.lastJailed ? { lastJailed: previous.lastJailed } : undefined;
+}

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

@@ -7,6 +7,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
+import { BROWSER_ROOT } from '@celilo/capabilities';
 import { deriveMountSet, forbiddenPaths, isForbidden, toBwrapArgs } from './mount-set';
 
 const BASE = {
@@ -136,13 +137,34 @@ describe('paths are identical inside and outside', () => {
   });
 });
 
-describe('~/.ssh is stage 2 only', () => {
-  test('bound read-only when supplied', () => {
-    const set = deriveMountSet({ ...BASE, sshDir: '/var/celilo/.ssh' });
-    expect(set.entries.find((e) => e.path === '/var/celilo/.ssh')?.mode).toBe('ro');
+describe('~/.ssh is never in the mount set (stage 3, D12)', () => {
+  test('no derivation produces an .ssh row', () => {
+    // Withholding the key is what turns the remote-ops broker's target check
+    // from a convention into a boundary: with no credential in the jail, a
+    // hand-built `ssh` cannot authenticate anywhere.
+    expect(pathsOf(BASE).some((p) => p.endsWith('/.ssh'))).toBe(false);
   });
+});
 
-  test('absent when not supplied, which is what stage 3 does', () => {
-    expect(pathsOf(BASE).some((p) => p.endsWith('/.ssh'))).toBe(false);
+describe('the fleet browser is reachable, and only read-only (task 4.10)', () => {
+  test('BROWSER_ROOT is bound', () => {
+    // Task 4.10 names `~/.cache/ms-playwright`. That path is stale:
+    // `managed-browser-runtime` moved the browser into a celilo-owned tree,
+    // and `resolveBrowser()` — the thing a hook actually asks — returns
+    // `BROWSER_EXECUTABLE_PATH` under this root. Asserted against the exported
+    // constant rather than a literal, so a future move cannot leave this test
+    // passing about a directory nothing launches from.
+    expect(pathsOf(BASE)).toContain(BROWSER_ROOT);
+  });
+
+  test('read-only, because a hook has no business writing the shared install', () => {
+    expect(deriveMountSet(BASE).entries.find((e) => e.path === BROWSER_ROOT)?.mode).toBe('ro');
+  });
+
+  test('the data directory beside it stays out', () => {
+    // The row is one named subdirectory, not `/var/lib/celilo`. Binding the
+    // parent would put `celilo.db` and `master.key` back inside the jail —
+    // the exact acceptance criterion D9 satisfies by absence.
+    expect(pathsOf(BASE)).not.toContain('/var/lib/celilo');
   });
 });

package/src/hooks/mount-set.ts

@@ -17,7 +17,7 @@
  */
 
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import type { PathAccess } from '@celilo/capabilities';
+import { BROWSER_ROOT, type PathAccess } from '@celilo/capabilities';
 
 /**
  * `tmpfs` is not an access level, it is "put a fresh empty filesystem here".
@@ -105,15 +105,6 @@ export interface MountSetRequest {
   readonly runtimeModulePaths?: readonly string[];
   /** Contract-declared path inputs, already resolved to values. */
   readonly pathInputs: readonly DeclaredPathInput[];
-  /**
-   * The operator's `~/.ssh`, read-only, STAGE 2 ONLY.
-   *
-   * `remote.ts` still runs inside the hook and needs the key. Stage 3 brokers
-   * those calls and drops this row, which is what turns D12's target check
-   * from a convention into a boundary. Dropping it before stage 3 lands
-   * hardens nothing — it just stops every hook reaching its own systems.
-   */
-  readonly sshDir?: string;
 }
 
 /** Directories whose contents the runtime needs in order to start at all. */
@@ -181,6 +172,34 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   for (const dir of RUNTIME_SUPPORT_DIRS) {
     entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
   }
+  // The fleet browser, read-only (task 4.10).
+  //
+  // `BROWSER_ROOT` rather than `~/.cache/ms-playwright`, which is what task 4.10
+  // says to bind and is now the wrong path: `managed-browser-runtime` moved the
+  // browser into a celilo-owned tree and `resolveBrowser()` is what a hook asks
+  // for it. Binding the cache would bind a directory nothing launches from.
+  //
+  // Read-only because a hook has no business writing to the shared browser
+  // install, and unconditional because it costs nothing when absent —
+  // `planJailedSpawn` drops a row whose source does not exist, so a host with no
+  // provisioned browser gets no row and no error. Gating it on some
+  // "this module uses a browser" signal would need a declaration that does not
+  // exist, and would fail closed in the one case that matters.
+  //
+  // Note what this does NOT bind: `/var/lib/celilo` itself stays out, so the
+  // data directory beside it is as absent as it was before. This is one
+  // subdirectory, named explicitly.
+  //
+  // ⚠️ The bind is necessary and not sufficient. Measured 2026-08-28 under a
+  // real bubblewrap jail (`hook-jail-toolchain-reach.test.ts`): Chromium with
+  // its own sandbox does NOT start inside the jail, and the same binary with
+  // `--no-sandbox` renders. Chromium's sandbox forks a helper into a new user
+  // namespace and nesting that inside bubblewrap's unprivileged one fails. So a
+  // browser hook also needs `--no-sandbox`, which belongs to whatever launches
+  // 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'));
 
   // 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
@@ -215,16 +234,11 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
     );
   }
 
-  // 6. Stage 2 only. See MountSetRequest.sshDir.
-  if (request.sshDir) {
-    entries.push(
-      entry(
-        resolve(request.sshDir),
-        'ro',
-        'remote.ts needs the key until the broker holds it (D12)',
-      ),
-    );
-  }
+  // There is deliberately NO `~/.ssh` row (stage 3, design D12). With no key
+  // in the jail, a hand-built `ssh` cannot authenticate anywhere; the remote
+  // primitives cross to the remote-ops broker instead, and withholding the
+  // key is what makes that broker's target check a boundary rather than a
+  // convention.
 
   return {
     entries: entries.filter((e) => !isForbidden(e.path)),