@celilo/cli 1.12.0 → 1.13.0

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');
+  });
+});

package/src/hooks/hook-state-dir.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { moduleStateDir } from '@celilo/capabilities';
 import { classifyModulePath } from '../module/packaging/package-rules';
 import { invokeHook } from './executor';
@@ -25,9 +25,21 @@ const silent: HookLogger = {
   success() {},
 };
 
+/** The workspace copy of the package every module bundles. */
+const CAPABILITIES_PACKAGE = resolve(import.meta.dir, '../../../../packages/capabilities');
+
 function scratchModule(script: string): string {
   const root = mkdtempSync(join(tmpdir(), 'celilo-statedir-'));
   Bun.write(join(root, 'hook.ts'), script);
+  // A real module in the store carries its OWN bundled @celilo/capabilities
+  // (modules run their bundled copy, celilo#173), and the hook jail binds the
+  // module's tree and nothing above it. This fixture used to resolve the
+  // import through the test runner's own tree, which worked only because hooks
+  // ran unjailed; `--chdir` into the module root removed that accident.
+  // Linking it here is what makes the fixture a module rather than a loose
+  // script.
+  mkdirSync(join(root, 'node_modules', '@celilo'), { recursive: true });
+  symlinkSync(CAPABILITIES_PACKAGE, join(root, 'node_modules', '@celilo', 'capabilities'));
   return root;
 }
 

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

@@ -74,8 +74,7 @@ describe('hook timeout is a kill, not a race', () => {
       executeHookScript(
         join(FIXTURES, 'runaway-hook.ts'),
         contextFor({ sleep_ms: 1500, marker_path: marker }),
-        400,
-        400,
+        { timeoutMs: 400, idleTimeoutMs: 400 },
       ),
     ).rejects.toThrow(/timeout/i);
 
@@ -92,8 +91,7 @@ describe('hook timeout is a kill, not a race', () => {
       executeHookScript(
         join(FIXTURES, 'sigterm-ignoring-hook.ts'),
         contextFor({ sleep_ms: 6000, marker_path: marker }),
-        400,
-        400,
+        { timeoutMs: 400, idleTimeoutMs: 400 },
       ),
     ).rejects.toThrow(/timeout/i);
 

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

@@ -22,9 +22,15 @@
 
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import {
+  applyFallbacksToPackageJson,
+  isPublished,
+  listUnpublishedWorkspacePackages,
+  planFallbacks,
+} from '../../../../scripts/workspace-fallback';
 import { executeHookScript, hookChildEnv } from './executor';
 import { createCapturingLogger } from './logger';
 import type { HookContext } from './types';
@@ -75,9 +81,45 @@ let realHome: string | undefined;
 function ensureFixtureInstalled(): void {
   const scriptsDir = dirname(TRESPASS_SCRIPT);
   if (existsSync(join(scriptsDir, 'node_modules', '@celilo', 'capabilities'))) return;
-  // `process.execPath`, not `bun` on PATH: this is the bun already running the
-  // suite, so it works wherever the suite does.
-  execFileSync(process.execPath, ['install'], { cwd: scriptsDir, stdio: 'pipe' });
+
+  // On a version-packages PR the pin names a version that CANNOT be on the
+  // registry yet, because only merging that PR lets it publish. So a plain
+  // install here fails with `No version matching "^3.3.0" found`, and the
+  // version PR can never go green on its own.
+  //
+  // This is celilo#642 exactly, and check-modules.sh already solves it. Reuse
+  // that rather than resolving from the workspace unconditionally: doing it
+  // unconditionally would check the fixture against a copy it does not bundle,
+  // which is the celilo#173 property this module's scripts/ dir is kept out of
+  // the root workspace globs to preserve. The fallback fires only when the pin
+  // names a version the registry lacks AND the workspace holds exactly that
+  // version — where the workspace IS the artifact about to be published, same
+  // bytes by definition.
+  //
+  // The probe is scoped to this module's own dependencies: packages it does not
+  // depend on are reported published without asking the network, so this costs
+  // one registry call rather than one per publishable workspace package.
+  const pkgPath = join(scriptsDir, 'package.json');
+  const original = readFileSync(pkgPath, 'utf-8');
+  const dependencies =
+    (JSON.parse(original) as { dependencies?: Record<string, string> }).dependencies ?? {};
+  const unpublished = listUnpublishedWorkspacePackages((name, version) =>
+    name in dependencies ? isPublished(name, version) : true,
+  );
+  const fallbacks = planFallbacks(dependencies, unpublished);
+  if (fallbacks.length > 0)
+    writeFileSync(pkgPath, applyFallbacksToPackageJson(original, fallbacks));
+
+  try {
+    // `process.execPath`, not `bun` on PATH: this is the bun already running the
+    // suite, so it works wherever the suite does.
+    execFileSync(process.execPath, ['install'], { cwd: scriptsDir, stdio: 'pipe' });
+  } finally {
+    // Restore even when the install failed. A `file:` pin left in the tree
+    // points the fixture at one machine's checkout and would be swept up by the
+    // next `git add -A` — the same reason check-modules.sh restores from a trap.
+    if (fallbacks.length > 0) writeFileSync(pkgPath, original);
+  }
 }
 
 beforeAll(() => {
@@ -121,7 +163,10 @@ async function runTrespass(): Promise<{ report: TrespassReport; lines: string[]
     capabilities: {},
   };
 
-  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, 60_000, 60_000);
+  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),