@celilo/cli 2.0.0 → 2.1.0

package/CELILO_CORE_MODULES.md

@@ -54,7 +54,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## Celilo's own infrastructure (self-hosted)
 
-- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
+- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations). Has **no `on_install`** — celilo initialises the box itself during the deploy (`bootstrapControlPlane`), because a jailed hook cannot spawn the CLI it used to reach (celilo#1225). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
 - **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. Its `sweep_revisions` hook is the store's ONLY delete path — `yank` flips a boolean in the index entry and frees nothing, so before it existed every build revision ever published was retained forever and a `+N` revision is auto-assigned on every publish. The production store reached 18 GB of which ~93% was superseded history, filled a 20 GB disk and took the release pipeline down. The sweep keeps the newest `sweep_keep_build_revisions` (default 1) of EVERY release, so no release can disappear and a manual rollback still works — that is what makes the hourly `timer.tick.1h` subscription defensible. It removes the index line BEFORE the payload, because the download route reads the payload file directly and never consults the index: that order leaves an interrupted sweep with an unlisted-but-served version rather than a listed one that 404s, and the orphan it leaves is reclaimed by the next run. On demand with `celilo module run-hook celilo-registry sweep_revisions` (add `dry_run=true` to see the plan). **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
 - **celilo-apt-repo** — Debian apt repository (reprepro + Bun HTTP server) serving the celilo `.deb` at apt.celilo.computer. **provides:** `apt_publish`. **requires:** `public_web`, `dns_registrar`.
 - **signal** — bidirectional Signal transport for alerts and deploy-interview questions; runs signal-cli in daemon mode with its JSON-RPC socket bound to the host's own address (never public) and **`--receive-mode=manual`**, which is load-bearing: signal-cli's default (`on-start`) leaves the daemon permanently receiving, so it drains every reply into an SSE stream nothing is attached to and REFUSES celilo's `receive` call — replies arrive and are unreadable, while `send` and every health check keep passing. Enrolled as a SECONDARY DEVICE of an existing Signal account rather than registering its own number — Signal blocks most VOIP ranges and bans bot-ish registrations. Recipient addresses live on celilo routes, not in module config, so adding a person never requires a redeploy. Runs on x86_64 and aarch64. `libsignal-client` ships no linux-aarch64 native, so celilo builds one (`modules/signal/build/`) and installs it as a `libsignal-jni` .deb on ARM hosts; x86_64 uses the JAR's bundled native. **provides:** `notification` (`send`, `receive`). **requires:** no capabilities — a transport that depended on the proxy, registrar or firewall could not tell you those were broken — and a system in the **`secure-mgmt`** zone: it holds a linked Signal account (the operator's own messaging identity and keys), and its job is to observe every tier while depending on none, which is what the control-plane zone is for. See `openspec/changes/add-alerting/`.

package/CELILO_SUBSYSTEMS.md

@@ -205,6 +205,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 - **Remote-ops broker (reachability scoped by the credential, stage 3 / D12)** — `apps/celilo/src/hooks/remote-broker.ts` (`startRemoteBroker`, `RemoteAccessPolicy`) answering a SECOND socket beside the capability one, with the policy in `apps/celilo/src/services/remote-access.ts` (`remoteAccessPolicy`) and the asking half inside `@celilo/capabilities`' own remote primitives (`packages/capabilities/src/remote.ts`, "The hook remote-ops bridge"). The jail binds no `~/.ssh`, so a hand-built `ssh` cannot authenticate; the primitives detect `CELILO_HOOK_REMOTE_SOCKET`, send each operation as a STRUCTURED request (never a shell string — the broker rebuilds the ssh line itself), and the broker checks the target against `ownedSystemModuleIds` + `getModuleSystems` before running anything, refusing with the module, the target, and the capability route named. Requests carrying the module's OWN credential (an `identityFile` crossing as content and materialised per call, or `installAuthorizedKey`'s password — the cPanel case) are scoped by that credential instead; an explicit non-root user likewise, because the fleet key's authority is root on fleet systems. Stream primitives' LOCAL paths are confined to the run's granted roots (stateDir, screenshots, generated/, declared path inputs), or `streamBackup` would be a write-as-celilo oracle. Attribution is by the module that PERFORMS the operation: a hook's request to the hook's module (the nine `invokeHook` sites build the policy), a provider's transport to the provider's module — providers run in-process and do not cross this socket, and `public_web`'s hand-built upload was replaced by the Ansible static-content converge (capability-owned-tables stage 4, celilo#1014). Residual, recorded rather than papered over: a hook can still `fetch()` any HTTP endpoint directly; only `probeHttp` consults the target check.
 - **Hook jail (a hook sees the paths it was given, and nothing else)** — `apps/celilo/src/hooks/mount-set.ts` (`deriveMountSet`, `toBwrapArgs`, `forbiddenPaths` — PURE, computes a filesystem view and touches nothing) and `apps/celilo/src/hooks/jail.ts` (`detectJailBackend`, `planJailedSpawn`, `realpathRequest`, `runtimeModulePathsFor`, `recordJailMode` — the half that touches the machine). `executeHookScript` spawns the shim under `bwrap` with the module's tree read-only, `state/` + `generated/` + this run's `screenshots/<run>` read-write on top of it, each contract-declared path input at its declared access, the broker's socket directory, the runtime and the `node_modules` the shim resolves through, and `/tmp` a fresh tmpfs FIRST so it cannot erase the socket or a staged input. `~/.ssh` is deliberately NOT bound (stage 3, D12): withholding the credential is what makes the remote-ops broker's target check a boundary. **The acceptance criterion is absence, not a check**: the module store and the data directory are simply not bound, so `master.key` and a sibling module give `ENOENT`. The set is DERIVED — a module cannot ask for more — and `bwrap` itself is never in it, because the AppArmor profile grants `userns` to `/usr/bin/bwrap` for anyone on the box (design D9). Backend detection RUNS bubblewrap rather than looking for it (four different denials all leave the binary in place), and the resulting mode is written to `hook-jail-mode.json` beside celilo's other per-machine state rather than logged, so a host that stops jailing is readable. `CELILO_HOOK_JAIL` = `auto` (default) / `required` / `off`. macOS has a `sandbox-exec` backend in the union, but `auto` defers on it (ce-29z: sandbox-exec DENIES undeclared writes where bubblewrap masks them, and D14's declared-path mechanism is not built), so the hook runs unjailed with the mode recorded; `required` bypasses the deferral for an operator who opts in. An `unjailed` record carries `lastJailed` (the jailed record it replaced on the same host), which is what the `hook_jail` self-monitor reads (`services/alerting/hook-jail.ts`, created unsuppressible by `celilo monitor add hook_jail`) to alert on a host that used to jail and has stopped. `celilo system doctor`'s "Hook execution" section (`renderHookExecutionSection`) reports the live mode and, when unjailed, why.
 - **Deploy pipeline** — `apps/celilo/src/services/module-deploy.ts`.
+- **Control-plane bootstrap (celilo initialises its own box)** — `apps/celilo/src/services/control-plane-bootstrap.ts` (`bootstrapControlPlane`) with `apps/celilo/src/services/dns-discovery.ts` (`discoverDns`) beside `network-discovery.ts`. Called from `module-deploy.ts` at the point `on_install` runs, for `CONTROL_PLANE_MODULE_ID` (exported from `services/deployed-systems.ts`, replacing three private copies of the string). Reads the box's upstream resolvers, mints the fleet key via `ensureFleetKey`, writes `dns.*` + `ssh.public_key` in ONE `initializeSystem` call, records the network via `discoverAndRecordNetwork`, then polls `checkDispatcher` and FAILS the deploy if no dispatcher answers. **It is not a hook, and that is the point** (celilo#1225): it was `modules/celilo-mgmt/scripts/on_install.ts`, which reached all of this by spawning the `celilo` CLI — impossible inside the jail, whose mount set binds no `/usr/bin`, no `/usr/local/bin` and no shell, so the deploy ran Ansible clean and then died in its own install hook on every host with a jail backend. celilo-mgmt is never deployed to a remote box, so the host being configured is always the host celilo runs on and the hook was a process boundary with celilo on both sides. Self-registering the management host into its own pool did NOT move: celilo places a module only on a machine already in the pool. The dispatcher read is celilo's four-part `checkDispatcher`, not the "is a process up?" probe the hook used.
 - **DNS provider backfill** (re-emit registrations when a provider deploys) — `apps/celilo/src/services/dns-provider-backfill.ts` — `isDnsInternalProvider`, `backfillProviderDns`.
 - **Base-module aspects (fan-out across the fleet)** — `apps/celilo/src/services/aspect-runner.ts` — `planAspectFanOut`, `runAspectFanOut`, `maybeRunAspectForTrigger`. Aspect content lives in `modules/<m>/base-module-aspect/` (e.g. knot-unbound-internal, technitium). Two directions, with DELIBERATELY OPPOSITE failure semantics:
   - **Outbound** (`maybeRunAspectForTrigger`, `on_install`): one provider's aspect across the whole fleet, enumerated at that instant. A failure never fails the provider's own deploy — aspects are forward-progress and a partial fleet converges on the next fan-out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^4.0.0",
+    "@celilo/capabilities": "^4.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.11.0",
     "@celilo/event-bus": "^0.6.0",

package/src/hooks/capability-loader.ts

@@ -45,7 +45,7 @@ import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildControlPlaneApi } from '../services/api-principal-enrolment';
 import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
-import { getModuleSystems } from '../services/deployed-systems';
+import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
 import { buildPortForwardStore } from '../services/port-forwards';
@@ -952,7 +952,6 @@ interface FirewallZones {
 }
 
 /** The module that IS celilo's control plane; its network is what we trust. */
-const CONTROL_PLANE_MODULE_ID = 'celilo-mgmt';
 
 function readZoneSubnet(db: DbClient, zone: string): string | undefined {
   const row = db

package/src/hooks/executor.ts

@@ -367,6 +367,12 @@ export async function executeHookScript(
 
     const child = Bun.spawn({
       cmd: [...jail.cmd],
+      // `sandbox-exec` has no `--chdir`, so the plan names one and the spawn
+      // sets it. Without it the child inherits the operator's shell directory,
+      // which the profile does not name — and `bun` reads its cwd before it
+      // runs anything, so the hook dies with a message about nothing in
+      // particular. bubblewrap plans leave this absent and use `--chdir`.
+      ...(jail.cwd ? { cwd: jail.cwd } : {}),
       env: hookChildEnv(
         broker.socketPath,
         remoteBroker.socketPath,

package/src/hooks/hook-jail-toolchain-reach.test.ts

@@ -125,22 +125,38 @@ async function measureReach(): Promise<{ reach: Reach; cleanup: () => void }> {
     capabilities: {},
   };
 
-  const reach = (await executeHookScript(PROBE_HOOK, context, {
-    timeoutMs: 60_000,
-    idleTimeoutMs: 60_000,
-    jail: {
-      modulePath,
-      // The browser reaches the jail as a DECLARED PATH INPUT, which is the
-      // mechanism 4.10's fix would use. Binding it by editing the derivation
-      // and then asking the derivation whether it is bound would prove
-      // nothing.
-      pathInputs: PROBE_BROWSER
-        ? [{ name: 'browser_executable', value: probeBrowserDir(), access: 'read' as const }]
-        : [],
-    },
-  })) as unknown as Reach;
-
-  return { reach, cleanup: () => rmSync(scratch, { recursive: true, force: true }) };
+  // The jailed run jails under `required`: ce-29z made `auto` defer on
+  // sandbox-exec until D14 exists, so this suite's jail is the operator's
+  // explicit act — the bypass the deferral deliberately leaves open.
+  const savedPolicy = process.env.CELILO_HOOK_JAIL;
+  process.env.CELILO_HOOK_JAIL = 'required';
+  try {
+    const reach = (await executeHookScript(PROBE_HOOK, context, {
+      timeoutMs: 60_000,
+      idleTimeoutMs: 60_000,
+      jail: {
+        modulePath,
+        // The browser reaches the jail as a DECLARED PATH INPUT, which is the
+        // mechanism 4.10's fix would use. Binding it by editing the derivation
+        // and then asking the derivation whether it is bound would prove
+        // nothing.
+        pathInputs: PROBE_BROWSER
+          ? [{ name: 'browser_executable', value: probeBrowserDir(), access: 'read' as const }]
+          : [],
+      },
+    })) as unknown as Reach;
+
+    return { reach, cleanup: restorePolicy };
+  } catch (error) {
+    restorePolicy();
+    throw error;
+  }
+
+  function restorePolicy() {
+    if (savedPolicy === undefined) delete process.env.CELILO_HOOK_JAIL;
+    else process.env.CELILO_HOOK_JAIL = savedPolicy;
+    rmSync(scratch, { recursive: true, force: true });
+  }
 }
 
 describe.skipIf(!jailed)(`what a jailed hook can run (backend: ${availability.backend})`, () => {
@@ -157,18 +173,46 @@ describe.skipIf(!jailed)(`what a jailed hook can run (backend: ${availability.ba
         console.error(`  ${probe.succeeded ? 'REACHED' : 'ABSENT '} ${name}: ${probe.detail}`);
       }
 
-      // ── The finding ────────────────────────────────────────────────────
-      // No shell, so `execSync` cannot run and neither can any hook that uses
-      // it. 22 module script files import `node:child_process`.
-      expect(reach.shell.succeeded).toBe(false);
-      expect(reach.exec_without_shell.succeeded).toBe(false);
+      // ── The finding, per backend ────────────────────────────────────────
+      // bubblewrap BUILDS a namespace, so reach is filesystem absence: no
+      // `/bin` is bound, so no shell, so `execSync` cannot run at all. 22
+      // module script files import `node:child_process`.
+      //
+      // `sandbox-exec` FILTERS the tree that is already there, and its parity
+      // statements change what exec means. `(allow process*)` lets the kernel
+      // map and run an image the jail cannot READ — exec is not file-read in
+      // SBPL — so `/bin/sh` runs, `/bin/echo` runs, and `ssh` spawns. Measured
+      // 2026-08-30, first run of this suite under the second backend. The
+      // boundary that DOES hold on macOS is the filesystem and the credential:
+      // writes outside the mount set are EPERM, secrets are unreadable, and
+      // the `~/.ssh` key stage 3 withheld is not in the jail for ssh to use —
+      // asserted by hook-trespass.test.ts and hook-jail-unreachability.test.ts,
+      // which pass under both backends.
+      if (availability.backend === 'sandbox-exec') {
+        expect(reach.shell.succeeded).toBe(true);
+        expect(reach.exec_without_shell.succeeded).toBe(true);
+        // It spawns; it cannot authenticate. That is stage 3's boundary, not
+        // this suite's.
+        expect(reach.ssh.succeeded).toBe(true);
+        // `ansible-playbook` is not installed on the probe host, so the row
+        // measures the HOST, not the jail: posix_spawn of anything present is
+        // allowed. No assertion either way.
+        // `dns_lookup` also stays a printed row rather than an assertion:
+        // measured REACHED — `(allow network*)` plus macOS resolving
+        // out-of-process in mDNSResponder — but gating on it needs a live
+        // resolver, which a unit suite should not require.
+      } else {
+        expect(reach.shell.succeeded).toBe(false);
+        expect(reach.exec_without_shell.succeeded).toBe(false);
 
-      // `~/.ssh` is bound read-only in stage 2 specifically so `remote.ts`
-      // keeps working. There is no `ssh` to hand that key to.
-      expect(reach.ssh.succeeded).toBe(false);
-      expect(reach.ansible.succeeded).toBe(false);
+        // `~/.ssh` is bound read-only in stage 2 specifically so `remote.ts`
+        // keeps working. There is no `ssh` to hand that key to.
+        expect(reach.ssh.succeeded).toBe(false);
+        expect(reach.ansible.succeeded).toBe(false);
+      }
 
-      // Nothing binds the resolver's configuration.
+      // Nothing binds the resolver's configuration, on either platform:
+      // bubblewrap by absence, sandbox-exec by `deny default` (EPERM).
       expect(reach.resolv_conf.succeeded).toBe(false);
 
       // ── Task 4.10 ──────────────────────────────────────────────────────
@@ -209,7 +253,12 @@ describe.skipIf(!jailed)(`what a jailed hook can run (backend: ${availability.ba
       // edit that would flip it: someone reads the failures above, binds
       // `/usr/bin` to fix them, and brings `bwrap` in with it. `isForbidden`
       // compares whole paths, so a bind of the DIRECTORY passes that filter.
-      expect(reach.bwrap_present.succeeded).toBe(false);
+      // Asserted under bubblewrap only: there is no bubblewrap jail on macOS,
+      // so the row would measure whether the OPERATOR has bwrap installed,
+      // and posix_spawn of it is allowed anyway.
+      if (availability.backend !== 'sandbox-exec') {
+        expect(reach.bwrap_present.succeeded).toBe(false);
+      }
     } finally {
       cleanup();
     }

package/src/hooks/hook-jail-unreachability.test.ts

@@ -33,7 +33,7 @@ import { join, resolve } from 'node:path';
 /** Uniquely named so it never collides with a real key on a jailed dev box. */
 const PLANTED_KEY_NAME = 'id_celilo_jail_probe';
 import { executeHookScript } from './executor';
-import { detectJailBackend } from './jail';
+import { detectJailBackend, jailPolicy } from './jail';
 import { createCapturingLogger } from './logger';
 import type { HookContext } from './types';
 
@@ -45,7 +45,12 @@ interface Probe {
 }
 
 const availability = detectJailBackend();
-const jailed = availability.backend !== 'none';
+// A host with a backend is not a host that JAILS: `CELILO_HOOK_JAIL=off` is an
+// operator switch and the executor honours it, so without this the suite runs
+// its assertions against a deliberately unjailed hook and reports the jail
+// broken. Only reachable since macOS gained a backend (task 4.8) — before that
+// every Mac skipped for want of one and the hole never showed.
+const jailed = availability.backend !== 'none' && jailPolicy() !== 'off';
 
 interface Rig {
   outputs: {
@@ -119,26 +124,38 @@ async function runProbe(): Promise<Rig> {
     capabilities: {},
   };
 
-  const outputs = (await executeHookScript(PROBE_HOOK, context, {
-    timeoutMs: 60_000,
-    idleTimeoutMs: 60_000,
-    jail: {
-      modulePath,
-      pathInputs: [{ name: 'staged_input', value: stagedInput, access: 'write' }],
-    },
-  })) as unknown as Rig['outputs'];
-
-  return {
-    outputs,
-    stagedInput,
-    siblingFile,
-    cleanup: () => {
-      rmSync(scratch, { recursive: true, force: true });
-      rmSync(stagedInput, { recursive: true, force: true });
-      rmSync(plantedKey, { force: true });
-      if (createdSshDir) rmSync(sshDir, { recursive: true, force: true });
-    },
-  };
+  // The jailed run jails under `required`: ce-29z made `auto` defer on
+  // sandbox-exec until D14 exists, so this suite's jail is the operator's
+  // explicit act — the bypass the deferral deliberately leaves open.
+  const savedPolicy = process.env.CELILO_HOOK_JAIL;
+  process.env.CELILO_HOOK_JAIL = 'required';
+  try {
+    const outputs = (await executeHookScript(PROBE_HOOK, context, {
+      timeoutMs: 60_000,
+      idleTimeoutMs: 60_000,
+      jail: {
+        modulePath,
+        pathInputs: [{ name: 'staged_input', value: stagedInput, access: 'write' }],
+      },
+    })) as unknown as Rig['outputs'];
+    return {
+      outputs,
+      stagedInput,
+      siblingFile,
+      cleanup: () => {
+        if (savedPolicy === undefined) delete process.env.CELILO_HOOK_JAIL;
+        else process.env.CELILO_HOOK_JAIL = savedPolicy;
+        rmSync(scratch, { recursive: true, force: true });
+        rmSync(stagedInput, { recursive: true, force: true });
+        rmSync(plantedKey, { force: true });
+        if (createdSshDir) rmSync(sshDir, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    if (savedPolicy === undefined) delete process.env.CELILO_HOOK_JAIL;
+    else process.env.CELILO_HOOK_JAIL = savedPolicy;
+    throw error;
+  }
 }
 
 describe.skipIf(!jailed)(`the jail is real (backend: ${availability.backend})`, () => {
@@ -187,13 +204,21 @@ describe.skipIf(!jailed)(`the jail is real (backend: ${availability.backend})`,
   }, 90_000);
 });
 
-describe.skipIf(jailed)('no jail on this host', () => {
+describe.skipIf(jailed)('this run is not jailed', () => {
   test('says so, rather than reporting a pass it did not earn', () => {
     // Not an assertion about the product. It is the line that stops a green
-    // run on a Mac reading as "the jail was proven".
+    // run on an unjailed host reading as "the jail was proven".
+    const why =
+      availability.backend === 'none'
+        ? (availability.reason ?? 'no backend')
+        : `CELILO_HOOK_JAIL=${process.env.CELILO_HOOK_JAIL}, so the operator switched the ${availability.backend} jail off here`;
     console.log(
-      `\nhook jail: SKIPPED the live suite — ${availability.reason ?? 'no backend'}\nThese properties are proven on Linux with bubblewrap. The hermetic half runs everywhere (jail.test.ts).`,
+      `\nhook jail: SKIPPED the live suite — ${why}\nThese properties are proven wherever a backend is available and enabled. The hermetic half runs everywhere (jail.test.ts).`,
     );
-    expect(availability.backend).toBe('none');
+    // Both reasons are legitimate and they are different facts, so assert the
+    // disjunction rather than one of them. Asserting `backend === 'none'` alone
+    // went red the day macOS got a backend AND the operator turned it off — a
+    // combination that is not a defect in anything.
+    expect(availability.backend === 'none' || jailPolicy() === 'off').toBe(true);
   });
 });

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

@@ -32,6 +32,7 @@ import {
   planFallbacks,
 } from '../../../../scripts/workspace-fallback';
 import { executeHookScript, hookChildEnv } from './executor';
+import { detectJailBackend, jailPolicy } from './jail';
 import { createCapturingLogger } from './logger';
 import type { HookContext } from './types';
 
@@ -150,7 +151,7 @@ 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: '' },
@@ -163,14 +164,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', () => {
@@ -251,3 +266,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.
+  },
+);