@celilo/cli 1.12.0 → 1.14.0

package/src/hooks/capability-loader.ts

@@ -15,6 +15,7 @@ import { join } from 'node:path';
 import {
   createPublicWeb,
   isCompiledCapabilityFactory,
+  orderFirewallChain,
   wrapWithLogging,
 } from '@celilo/capabilities';
 import type {
@@ -38,8 +39,10 @@ import {
   systemConfig,
   webRoutes,
 } from '../db/schema';
+import { resolveModuleWebRoot } from '../module/web-root';
 import { decryptSecret } from '../secrets/encryption';
 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';
@@ -219,6 +222,26 @@ export async function resolveCaddyZoneIp(db: DbClient): Promise<string | undefin
   return undefined;
 }
 
+/**
+ * Does this module's manifest declare `capabilityName`, under `requires` or
+ * `optional`?
+ *
+ * Reads the manifest stored at import rather than the one on disk, so the
+ * answer is the one the operator's `module import` actually validated.
+ */
+function consumerDeclares(db: DbClient, moduleId: string, capabilityName: string): boolean {
+  const row = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  const manifest = row?.manifestData;
+  if (!manifest) return false;
+
+  type Declarations = { capabilities?: { name?: string }[] } | undefined;
+  const declared = [
+    ...((manifest.requires as Declarations)?.capabilities ?? []),
+    ...((manifest.optional as Declarations)?.capabilities ?? []),
+  ];
+  return declared.some((cap) => cap?.name === capabilityName);
+}
+
 export async function loadCapabilityFunctions(
   consumingModuleId: string,
   db: DbClient,
@@ -380,6 +403,11 @@ export async function loadCapabilityFunctions(
           // which made a module-provided capability structurally unable to
           // offer `unregisterRoutes()`-style methods.
           consumerModuleId: consumingModuleId,
+          // WHERE THE CALLER'S BYTES ARE, for the same reason and by the same
+          // seam. `private_web` and `external_web` publish static sites too, and
+          // without this they could not find the caller's web root now that
+          // `sourceDir` has left the request (D10 amendment).
+          consumerWebRoot: resolveModuleWebRoot(consumingModuleId, db),
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -563,6 +591,9 @@ export async function loadCapabilityFunctions(
       providerByCapability.set(provider.capabilityName, provider.moduleId);
       result.public_web = createPublicWeb({
         moduleId: consumingModuleId,
+        // Resolved here, not in the capability: on a converge there is no
+        // consumer process to ask (D10 amendment).
+        webRoot: resolveModuleWebRoot(consumingModuleId, db),
         logger,
         config: providerConfig,
         secrets: providerSecrets,
@@ -641,6 +672,30 @@ export async function loadCapabilityFunctions(
     debugLog('public_web: not registered in DB, skipping');
   }
 
+  // Framework-granted, so unlike everything above there is no provider row to
+  // look up and no script to import — celilo IS the management server whose
+  // principals these are (web-ui-console D7b).
+  //
+  // Gated on the DECLARATION, which the rest of this function deliberately is
+  // not: the loop injects every capability it can build "not just required
+  // ones", so a module that never asked still gets `idp` and `firewall`. That is
+  // fine for a capability whose worst outcome is an unused OIDC client. This one
+  // mints an SSH principal into celilo's own control plane, so the `requires`
+  // line is the authorization and a module that did not write one does not get
+  // the object at all.
+  if (consumerDeclares(db, consumingModuleId, 'control_plane_api')) {
+    // Wrapped like every other capability, so an enrolment that fails mid-deploy
+    // leaves a `✗ control_plane_api.enrol_principal` in the hook log rather than
+    // only a thrown error further up. The `defineCapabilityFunction` path wraps
+    // itself; a framework-built table has to be wrapped here.
+    result.control_plane_api = wrapWithLogging(
+      buildControlPlaneApi(consumingModuleId),
+      logger,
+      'control_plane_api',
+    );
+    debugLog(`control_plane_api: framework-granted, injected for ${consumingModuleId}`);
+  }
+
   // celilo#1072: the CALL is the binding, not the resolution. Everything above
   // is injected whether or not the consumer declared it — the loop's own
   // comment says "not just required ones" — so recording what was resolved
@@ -1104,20 +1159,19 @@ async function buildFirewallChain(
   // attributable. Only the layers that render their own ruleset receive it.
   const trustedSourceStore = buildTrustedSourceStore(db, consumingModuleId);
 
-  // Find the provider with has_external (the leaf — has direct internet access)
-  const hasExternal = allProviders.find((p) => {
-    const data = (typeof p.data === 'string' ? JSON.parse(p.data) : p.data) as Record<
-      string,
-      unknown
-    >;
-    return data.has_external === true;
-  });
+  // The delegation order, most downstream first. Shared with the console's
+  // closure so the wiring and the picture cannot disagree about which firewall
+  // stands on which — see `orderFirewallChain`.
+  const chainOrder = orderFirewallChain(allProviders);
 
-  if (!hasExternal) {
+  if (chainOrder.length === 0) {
     debugLog('firewall chain: no provider with external interface found');
     return { chain: null, self: null };
   }
 
+  // The leaf is the upstream end: the provider with the direct internet leg.
+  const hasExternal = chainOrder[chainOrder.length - 1] as (typeof chainOrder)[number];
+
   // Build the leaf (external) firewall first
   const leafModule = db.select().from(modules).where(eq(modules.id, hasExternal.moduleId)).get();
   if (!leafModule) return { chain: null, self: null };
@@ -1173,7 +1227,10 @@ async function buildFirewallChain(
   // Build downstream providers, wiring each to the upstream. iptables
   // remains a legacy factory because its second arg (upstreamFirewall)
   // doesn't fit defineCapabilityFunction's single-context shape.
-  const downstream = allProviders.filter((p) => p.moduleId !== hasExternal.moduleId);
+  // Back into wiring order: each layer is built taking the previous one as its
+  // upstream, so the build runs from the leaf outwards while the chain reads
+  // from the consumer inwards.
+  const downstream = chainOrder.slice(0, -1).reverse();
 
   // Each layer as its OWN provider sees it, so `on_consumer_removed` converges
   // the firewall that declares the hook rather than whichever layer a consumer

package/src/hooks/executor.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, test } from 'bun:test';
-import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { ContractHookSignature } from '../manifest/contracts';
 import {
   checkRequiredCapabilities,
+  declaredPathInputs,
   executeHookScript,
   invokeHook,
   resolveHookScript,
@@ -11,6 +13,7 @@ import {
   validateHookInputs,
   validateHookOutputs,
 } from './executor';
+import { readJailMode } from './jail';
 import { createCapturingLogger } from './logger';
 import type { HookDefinition } from './types';
 
@@ -241,12 +244,90 @@ describe('Hook Executor', () => {
 
       // 8s of silence against a 1ms idle bound: killed at the first poll.
       // Under the old hardcoded 30s idle this resolved instead.
-      await expect(executeHookScript(scriptPath, context, 60_000, 1)).rejects.toThrow(
-        'idle timeout exceeded',
-      );
+      await expect(
+        executeHookScript(scriptPath, context, { timeoutMs: 60_000, idleTimeoutMs: 1 }),
+      ).rejects.toThrow('idle timeout exceeded');
     }, 20_000);
   });
 
+  describe('declaredPathInputs', () => {
+    // The jail's bind mounts come from this, so a wrong answer here is a hook
+    // that cannot read a file it was handed — or one that can read a file
+    // nobody declared.
+    const SIG: ContractHookSignature = {
+      inputs: {
+        backup_dir: { required: true, path: { access: 'write' } },
+        artifact_path: { required: true, path: { access: 'read' } },
+        artifact_count: { required: false },
+      },
+      outputs: {},
+    };
+
+    test('walks the declaration and carries the declared access', () => {
+      expect(
+        declaredPathInputs(SIG, {
+          backup_dir: '/tmp/stage/data',
+          artifact_path: '/tmp/stage/db.sqlite',
+          artifact_count: 3,
+        }),
+      ).toEqual([
+        { name: 'backup_dir', value: '/tmp/stage/data', access: 'write' },
+        { name: 'artifact_path', value: '/tmp/stage/db.sqlite', access: 'read' },
+      ]);
+    });
+
+    test('a path-shaped input the contract does not declare contributes nothing', () => {
+      // `db_path` was passed by backup-create.ts for months and declared
+      // nowhere (celilo#1118). The derivation walks declarations, so the jail
+      // withholds it — which is the correct outcome and the reason the
+      // contract has to declare what it passes.
+      expect(declaredPathInputs(SIG, { db_path: '/var/celilo/celilo.db' })).toEqual([]);
+    });
+
+    test('a name that merely LOOKS like a path is not one', () => {
+      // Never inferred from the name. A heuristic silently changes what a hook
+      // can reach the day somebody adds an input called `workspace`.
+      const noPaths: ContractHookSignature = {
+        inputs: { restore_dir: { required: true } },
+        outputs: {},
+      };
+      expect(declaredPathInputs(noPaths, { restore_dir: '/tmp/x' })).toEqual([]);
+    });
+
+    test('a declared input this run did not receive is skipped', () => {
+      expect(declaredPathInputs(SIG, {})).toEqual([]);
+    });
+  });
+
+  describe('the recorded jail mode describes the HOST', () => {
+    test('an invocation with no module tree records nothing', async () => {
+      // Such a run is unjailable whatever the host can do, so recording it
+      // would overwrite a `jailed` record with an `unjailed` one — exactly the
+      // transition a self-monitor raises an alert on (design D8, task 4.4).
+      const store = join(mkdtempSync(join(tmpdir(), 'celilo-mode-')), 'mode.json');
+      const saved = process.env.CELILO_HOOK_JAIL_MODE_PATH;
+      process.env.CELILO_HOOK_JAIL_MODE_PATH = store;
+      try {
+        const { logger } = createCapturingLogger();
+        await executeHookScript(join(FIXTURES_DIR, 'void-hook.ts'), {
+          config: {},
+          secrets: {},
+          systems: [],
+          logger,
+          debug: false,
+          screenshotDir: '/tmp',
+          stateDir: '/tmp',
+          capabilities: {},
+        });
+        expect(readJailMode()).toBeUndefined();
+        expect(existsSync(store)).toBe(false);
+      } finally {
+        if (saved === undefined) delete process.env.CELILO_HOOK_JAIL_MODE_PATH;
+        else process.env.CELILO_HOOK_JAIL_MODE_PATH = saved;
+      }
+    });
+  });
+
   describe('resolveHookTimeouts', () => {
     test('no declaration: 60s total, 30s idle heuristic', () => {
       expect(resolveHookTimeouts(undefined, false)).toEqual({

package/src/hooks/executor.ts

@@ -24,16 +24,24 @@
  *     records after celilo reported the deploy failed (celilo#1003).
  *   - A hook's memory is its own process's, not celilo's heap.
  *
+ * **Stage 2 has landed and the child is JAILED where a backend exists.** The
+ * filesystem view is derived per run (`mount-set.ts`, design D9) and built with
+ * bubblewrap (`jail.ts`, design D8). A jailed hook reaching for celilo's master
+ * key gets `ENOENT` — the path is not denied, it is absent. Where no backend
+ * exists (a Mac today, task 4.8) the hook runs unjailed and the mode is
+ * RECORDED, so a host that quietly stops jailing is visible rather than silent.
+ *
  * Hooks still do NOT execute on the target machine. One that needs to touch a
  * target initiates SSH outbound itself, so anything it depends on (chromium,
  * system binaries, credentials) must be available on the celilo CLI host.
- * Stage 2 of the change above jails the filesystem and stage 3 scopes that
- * reachability; neither has landed.
+ * Stage 3 scopes that reachability and has not landed, which is why `~/.ssh`
+ * is still bound into the jail read-only.
  *
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
 
 import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import {
   type DeployedSystem,
@@ -57,6 +65,16 @@ import {
   createLineReader,
   deserializeError,
 } from './hook-protocol';
+import {
+  type JailPlan,
+  detectJailBackend,
+  jailPolicy,
+  planJailedSpawn,
+  realpathRequest,
+  recordJailMode,
+  runtimeModulePathsFor,
+} from './jail';
+import { type DeclaredPathInput, type MountSetRequest, deriveMountSet } from './mount-set';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
 
 /** Default total timeout: 60 seconds */
@@ -218,6 +236,37 @@ export function resolveHookScript(modulePath: string, scriptPath: string): strin
   return resolved;
 }
 
+/**
+ * What the jail needs that only the caller knows.
+ *
+ * Everything else in a `MountSetRequest` the executor already holds or is: the
+ * writable directories are on the context, the socket belongs to the broker it
+ * just started, and the runtime and the shim are its own. These two are not.
+ * `modulePath` is the module's identity and `pathInputs` needs the contract
+ * signature, and neither reaches `executeHookScript` any other way.
+ *
+ * Absent means "do not jail this invocation" rather than "jail it with
+ * nothing" — an empty mount set is a hook that cannot read its own script.
+ */
+export interface HookJailInputs {
+  /** The module's own tree, `mod.sourcePath`. Realpath'd here, not by the caller. */
+  readonly modulePath: string;
+  /** Contract-declared path inputs, paired with the values this run resolved. */
+  readonly pathInputs: readonly DeclaredPathInput[];
+}
+
+export interface ExecuteHookOptions {
+  /** Total timeout in milliseconds. */
+  timeoutMs?: number;
+  /**
+   * Kill after this much silence (no output of any kind from the child).
+   * Pass `timeoutMs` to disable the idle heuristic — see `IDLE_TIMEOUT_MS`.
+   */
+  idleTimeoutMs?: number;
+  /** What to jail this run with. Absent runs the hook unjailed. */
+  jail?: HookJailInputs;
+}
+
 /**
  * Execute a hook script
  *
@@ -225,17 +274,17 @@ export function resolveHookScript(modulePath: string, scriptPath: string): strin
  *
  * @param scriptPath - Absolute path to the hook script
  * @param context - Hook context with config, secrets, logger, and inputs
- * @param timeoutMs - Total timeout in milliseconds
- * @param idleTimeoutMs - Kill after this much silence (no `ctx.logger` call).
- *   Pass `timeoutMs` to disable the idle heuristic — see `IDLE_TIMEOUT_MS`.
+ * @param options - Timeouts and the jail inputs
  * @returns Hook result with outputs
  */
 export async function executeHookScript(
   scriptPath: string,
   context: HookContext,
-  timeoutMs: number = DEFAULT_TIMEOUT_MS,
-  idleTimeoutMs: number = IDLE_TIMEOUT_MS,
+  options: ExecuteHookOptions = {},
 ): Promise<Record<string, unknown>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const idleTimeoutMs = options.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
+
   if (!existsSync(scriptPath)) {
     throw new Error(`Hook script not found: ${scriptPath}`);
   }
@@ -261,8 +310,22 @@ export async function executeHookScript(
   });
 
   try {
+    const jail = planJailedSpawn(
+      [process.execPath, HOOK_RUNNER_PATH],
+      options.jail &&
+        deriveMountSet(realpathRequest(jailRequest(options.jail, context, broker.socketPath))),
+      detectJailBackend(),
+      jailPolicy(),
+    );
+    reportJail(jail, logger);
+    // Only a real module hook says anything about whether this HOST jails. An
+    // invocation with no module tree is unjailable whatever the host can do,
+    // and recording it would overwrite a `jailed` record with an `unjailed`
+    // one — which is precisely the transition task 4.4 raises an alert on.
+    if (options.jail) recordJailMode(jail);
+
     const child = Bun.spawn({
-      cmd: [process.execPath, HOOK_RUNNER_PATH],
+      cmd: [...jail.cmd],
       env: hookChildEnv(broker.socketPath),
       stdout: 'pipe',
       stderr: 'pipe',
@@ -376,6 +439,64 @@ export function hookChildEnv(socketPath: string): Record<string, string> {
   return env;
 }
 
+/**
+ * Assemble this run's mount-set request (design D9).
+ *
+ * Planning function (Rule 10.4) — pure. It names every path the jail will
+ * bind, and reading it is how you answer "why can the hook not see X".
+ *
+ * The two writable directories are carved out of the module's own read-only
+ * tree, which is the one exception to D9's sentence that the tree is bound
+ * read-only. `state/` and `screenshots/<run>` both sit INSIDE `<store>/<id>`,
+ * and bubblewrap resolves that by order: a later `--bind` wins over an earlier
+ * `--ro-bind`. The derivation emits them in that order deliberately.
+ */
+function jailRequest(
+  inputs: HookJailInputs,
+  context: HookContext,
+  socketPath: string,
+): MountSetRequest {
+  return {
+    modulePath: inputs.modulePath,
+    stateDir: context.stateDir,
+    screenshotDir: context.screenshotDir,
+    socketDir: dirname(socketPath),
+    runtimePath: process.execPath,
+    runnerPath: HOOK_RUNNER_PATH,
+    runtimeModulePaths: runtimeModulePathsFor(HOOK_RUNNER_PATH),
+    pathInputs: inputs.pathInputs,
+    // Stage 2 only. `remote.ts` still runs inside the hook and needs the key;
+    // stage 3 brokers those calls and drops this row (D9, D12). Dropping it
+    // early hardens nothing — it stops every hook reaching its own systems.
+    sshDir: join(homedir(), '.ssh'),
+  };
+}
+
+/**
+ * Say what the jail did, once per run, at a level that matches how surprising
+ * it is.
+ *
+ * `skipped` is a warning rather than debug output on purpose. A dropped
+ * `/lib64` on arm64 is routine; a dropped contract input means the hook is
+ * about to write into the run's private tmpfs and report success over a
+ * directory that is discarded when it exits (task 4.2j). Both look identical
+ * here, so the line names the paths and lets a reader tell them apart.
+ */
+function reportJail(plan: JailPlan, logger: HookLogger): void {
+  if (plan.mode === 'jailed') {
+    if (plan.skipped.length > 0) {
+      logger.warn(
+        `Hook jail: ${plan.skipped.length} mount(s) absent on this host and dropped: ${plan.skipped.join(', ')}`,
+      );
+    }
+    return;
+  }
+  // Not a warning. D8 is explicit that a steady-state unjailed host (a Mac) is
+  // not an event, and a per-invocation warning on a fleet that deploys often
+  // is noise that gets filtered. The recorded mode is what raises the alarm.
+  if (plan.reason) logger.info(`Hook jail unavailable: ${plan.reason}`);
+}
+
 /** Read a piped stream line by line into the logger. */
 async function forwardStream(
   stream: ReadableStream<Uint8Array>,
@@ -492,6 +613,36 @@ export function checkRequiredCapabilities(
   return lines.join(' ');
 }
 
+/**
+ * The contract's declared path inputs, paired with the values this run got.
+ *
+ * Policy function (Rule 10.1) — pure.
+ *
+ * Walks the DECLARATION, never the values. A heuristic over the input names
+ * ("does it end in `_dir`?") silently changes what a hook can reach the day
+ * somebody adds an input called `workspace`, and the symptom is an `ENOENT` on
+ * a path that visibly exists on the box. `ContractField.path` says which
+ * fields are paths and at what access, and this reads only that.
+ *
+ * The corollary is that an undeclared path input contributes nothing to the
+ * jail, so the hook cannot reach it. That is the correct outcome and it is why
+ * `db_path` had to be declared (celilo#1118, task 4.2h): the contract lying
+ * about what a backup hook receives now costs the hook the file.
+ */
+export function declaredPathInputs(
+  signature: ContractHookSignature,
+  inputs: Record<string, unknown>,
+): DeclaredPathInput[] {
+  const declared: DeclaredPathInput[] = [];
+  for (const [name, field] of Object.entries(signature.inputs)) {
+    if (!field.path) continue;
+    const value = inputs[name];
+    if (typeof value !== 'string' || value === '') continue;
+    declared.push({ name, value, access: field.path.access });
+  }
+  return declared;
+}
+
 /**
  * Find the most recently created screenshot in a directory
  *
@@ -691,7 +842,11 @@ export async function invokeHook(
   // Execute
   try {
     logger.info(`Executing hook: ${hookName}`);
-    const outputs = await executeHookScript(scriptPath, context, timeoutMs, idleTimeoutMs);
+    const outputs = await executeHookScript(scriptPath, context, {
+      timeoutMs,
+      idleTimeoutMs,
+      jail: { modulePath, pathInputs: declaredPathInputs(signature, inputs) },
+    });
 
     // Validate outputs against the contract signature
     const outputError = validateHookOutputs(signature, outputs);

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

@@ -0,0 +1,173 @@
+/**
+ * The live half of the hook jail: a hook that genuinely cannot reach a path
+ * (design D9, tasks 4.9 and 4.2j).
+ *
+ * **This suite needs a real jail and SKIPS without one, loudly.** A Mac has no
+ * backend until task 4.8, and neither does a runner with no bubblewrap, so the
+ * skip is the common case on a development box. It prints the reason the probe
+ * gave rather than passing quietly — CLAUDE.md's whole point about a check that
+ * cannot reach its subject is that silence and success look identical.
+ *
+ * Two properties, and they fail in opposite directions:
+ *
+ *   - **Unreachability, asserted as unreachability.** bubblewrap removes the
+ *     path (`ENOENT`), `sandbox-exec` denies it (`EPERM`), and both satisfy
+ *     D9. So the assertion is "the read did not succeed", never a match on an
+ *     errno — a test pinned to `ENOENT` would go red on macOS for a jail that
+ *     was working perfectly.
+ *
+ *   - **The staged input survived the tmpfs.** `/tmp` is a fresh tmpfs mounted
+ *     FIRST, and every staged contract input lives under `os.tmpdir()`. Mount
+ *     the tmpfs after them and they vanish — and a hook whose `backup_dir` is
+ *     silently an empty tmpfs directory writes into it, returns success, and
+ *     produces a backup containing NOTHING. It is found at restore. So this
+ *     asserts the bytes are on disk in the PARENT afterwards, never that the
+ *     hook exited zero (task 4.2j).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { executeHookScript } from './executor';
+import { detectJailBackend } from './jail';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const PROBE_HOOK = resolve(__dirname, 'test-fixtures/jail-probe-hook.ts');
+
+interface Probe {
+  succeeded: boolean;
+  detail: string;
+}
+
+const availability = detectJailBackend();
+const jailed = availability.backend !== 'none';
+
+interface Rig {
+  outputs: {
+    planted_secret: Probe;
+    sibling_write: Probe;
+    state_write: Probe;
+    staged_write: Probe;
+  };
+  stagedInput: string;
+  siblingFile: string;
+  cleanup: () => void;
+}
+
+/**
+ * Lay out a module store the way celilo does, run the probe hook against it,
+ * and hand back both the hook's report and the paths so the parent can check
+ * the disk rather than the report.
+ */
+async function runProbe(): Promise<Rig> {
+  const scratch = mkdtempSync(join(tmpdir(), 'celilo-jail-live-'));
+  const store = join(scratch, 'modules');
+  const modulePath = join(store, 'jail-probe');
+  const stateDir = join(modulePath, 'state');
+  const screenshotDir = join(modulePath, 'screenshots', 'run');
+  mkdirSync(join(modulePath, 'scripts'), { recursive: true });
+  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(screenshotDir, { recursive: true });
+
+  // A sibling module, one `..` away from the hook's own tree.
+  const sibling = join(store, 'technitium');
+  mkdirSync(sibling, { recursive: true });
+  const siblingFile = join(sibling, 'trespassed');
+
+  // celilo's master key, outside the store entirely. Planted rather than real:
+  // the operator's key is never read (CLAUDE.md, never test against live data).
+  const plantedSecret = join(scratch, 'master.key');
+  writeFileSync(plantedSecret, 'not-the-real-key');
+
+  // A staged contract input, under os.tmpdir() exactly as `stagingDirFor`
+  // produces. This is the path the tmpfs would erase.
+  const stagedInput = mkdtempSync(join(tmpdir(), 'celilo-jail-staged-'));
+
+  const { logger } = createCapturingLogger();
+  const context: HookContext = {
+    config: {
+      planted_secret: plantedSecret,
+      sibling_file: siblingFile,
+      staged_input: stagedInput,
+    },
+    secrets: {},
+    systems: [],
+    logger,
+    debug: false,
+    screenshotDir,
+    stateDir,
+    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 });
+    },
+  };
+}
+
+describe.skipIf(!jailed)(`the jail is real (backend: ${availability.backend})`, () => {
+  test('a hook cannot reach celilo’s master key, or a sibling module', async () => {
+    const rig = await runProbe();
+    try {
+      const { planted_secret, sibling_write, state_write, staged_write } = rig.outputs;
+      console.log(['', 'jail probe:', JSON.stringify(rig.outputs, null, 2)].join('\n'));
+
+      // Unreachability, not an errno. Under bubblewrap the message is ENOENT
+      // and under sandbox-exec it is EPERM; asserting either one would make
+      // this suite red on a platform whose jail works.
+      expect(planted_secret.succeeded).toBe(false);
+      expect(sibling_write.succeeded).toBe(false);
+      // And the parent's own view: the write did not land by another route.
+      expect(existsSync(rig.siblingFile)).toBe(false);
+
+      // The carve-out. `state/` is inside the read-only module tree and is
+      // bound read-write on top of it; if the ordering were wrong this is the
+      // assertion that would catch it.
+      expect(state_write.succeeded).toBe(true);
+      expect(staged_write.succeeded).toBe(true);
+    } finally {
+      rig.cleanup();
+    }
+  }, 90_000);
+
+  test('a staged contract input survives the /tmp tmpfs (task 4.2j)', async () => {
+    const rig = await runProbe();
+    try {
+      // The hook reported success above. That is exactly the signal that is
+      // worthless here: a write into a private tmpfs succeeds and is gone.
+      // Read the bytes from the parent.
+      const produced = join(rig.stagedInput, 'produced');
+      expect(existsSync(produced)).toBe(true);
+      expect(readFileSync(produced, 'utf-8').length).toBeGreaterThan(0);
+    } finally {
+      rig.cleanup();
+    }
+  }, 90_000);
+});
+
+describe.skipIf(jailed)('no jail on this host', () => {
+  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".
+    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).`,
+    );
+    expect(availability.backend).toBe('none');
+  });
+});