@zgeoff/atc 3.4.0 → 3.4.2

package/src/run-gateway.ts

@@ -14,6 +14,35 @@ interface GatewayFlags {
   readonly stateDir: string;
 }
 
+// What the gateway reaches outside itself, the process's own by default:
+// the environment its daemon tokens come from, the console, the exit, and
+// the signal listeners that stop it.
+interface GatewayIO {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly print: (line: string) => void;
+  readonly printError: (line: string) => void;
+  readonly exit: (code: number) => void;
+  readonly registerSignal: (signal: 'SIGINT' | 'SIGTERM', listener: () => Promise<void>) => void;
+}
+
+const PROCESS_IO: GatewayIO = {
+  env: process.env,
+  print: (line) => {
+    console.log(line);
+  },
+  printError: (line) => {
+    console.error(line);
+  },
+  exit: (code) => {
+    process.exit(code);
+  },
+  registerSignal: (signal, listener) => {
+    process.on(signal, () => {
+      void listener();
+    });
+  },
+};
+
 /**
  * Runs `atc-gateway` in the foreground: serves the MCP tools over HTTP for
  * the daemons the registry lists, routing every call to one of them over
@@ -23,15 +52,21 @@ interface GatewayFlags {
  * registry that fails to load, or a server that fails to start, prints the
  * reason and exits 1.
  */
-export async function runGateway(build: string, flags: GatewayFlags): Promise<void> {
-  const loaded = loadGatewayRegistry(flags.registryPath, process.env);
+export async function runGateway(
+  build: string,
+  flags: GatewayFlags,
+  io: GatewayIO = PROCESS_IO,
+): Promise<void> {
+  const loaded = loadGatewayRegistry(flags.registryPath, io.env);
 
   if (!loaded.ok) {
     for (const error of loaded.errors) {
-      console.error(`atc-gateway: ${error}`);
+      io.printError(`atc-gateway: ${error}`);
     }
 
-    process.exit(1);
+    io.exit(1);
+
+    return;
   }
 
   mkdirSync(flags.stateDir, { recursive: true });
@@ -59,19 +94,21 @@ export async function runGateway(build: string, flags: GatewayFlags): Promise<vo
       // The line carries a client's name, so control and format characters
       // are dropped before it reaches the log.
       printApproval: (line) => {
-        console.log(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
+        io.print(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
       },
 
       // Request lines go to stderr, so stdout keeps the approval lines alone.
       printRequest: (line) => {
-        console.error(line);
+        io.printError(line);
       },
     });
   } catch (error) {
     await gateway.stop();
 
-    console.error(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
+    io.printError(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
+    io.exit(1);
+
+    return;
   }
 
   // The handlers go in before the serving line, so a signal sent once the
@@ -80,16 +117,10 @@ export async function runGateway(build: string, flags: GatewayFlags): Promise<vo
     await server.stop();
     await gateway.stop();
 
-    process.exit(0);
+    io.exit(0);
   };
 
-  process.on('SIGINT', () => {
-    void stopServing();
-  });
-
-  process.on('SIGTERM', () => {
-    void stopServing();
-  });
-
-  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
+  io.registerSignal('SIGINT', stopServing);
+  io.registerSignal('SIGTERM', stopServing);
+  io.print(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
 }

package/src/sources/github/run-gh.ts

@@ -5,6 +5,12 @@ export interface GHRun {
   readonly timedOut: boolean;
 }
 
+interface GHRunOptions {
+  // Called with the pid of the started gh right after it starts; that pid
+  // is also its process group's id.
+  readonly onSpawn?: (pid: number) => void;
+}
+
 /**
  * Runs gh with arguments until it exits or the signal aborts, killing its
  * whole process group on abort, so a wrapper or extension leaves no process
@@ -15,6 +21,7 @@ export async function runGH(
   bin: string,
   signal: Readonly<AbortSignal>,
   args: readonly string[],
+  options: GHRunOptions = {},
 ): Promise<GHRun> {
   const proc = Bun.spawn([bin, ...args], {
     env: {
@@ -34,6 +41,8 @@ export async function runGH(
     detached: true,
   });
 
+  options.onSpawn?.(proc.pid);
+
   const finished = Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/test-utils/build-mock-execution-target.ts

@@ -0,0 +1,25 @@
+import { faker } from '@faker-js/faker';
+import type { ExecutionTarget } from '../daemon/build-execution-targets';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A local-pty execution target with an arbitrary id and identity, no
+ * options, and no provider, as a target of a kind this daemon lacks has.
+ * Overrides merge into fresh defaults at every depth; a provider override
+ * replaces the default whole.
+ */
+export function buildMockExecutionTarget(
+  overrides: MockOverrides<ExecutionTarget, keyof ExecutionTarget> = {},
+): ExecutionTarget {
+  return mergeDeep<ExecutionTarget>(
+    {
+      id: faker.word.noun(),
+      kind: 'local-pty',
+      options: {},
+      identity: `local-pty:${faker.string.uuid()}`,
+      provider: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-mock-imp-session-request.ts

@@ -0,0 +1,53 @@
+import { faker } from '@faker-js/faker';
+import type { ImpSessionRequest } from '../daemon/imp-port';
+
+/**
+ * The request that starts a process on an imp.
+ */
+type StartRequest = Extract<ImpSessionRequest, { readonly kind: 'start' }>;
+
+/**
+ * The request that attaches to a process already running on an imp.
+ */
+type AttachRequest = Extract<ImpSessionRequest, { readonly kind: 'attach' }>;
+
+type AttachOverrides = Partial<AttachRequest> & { readonly kind: 'attach' };
+
+/**
+ * A request that starts `true` on an imp with an empty environment, or, for
+ * an override of kind `attach`, one that attaches without waking the imp.
+ * Either carries no resume point and no requirements, and an arbitrary imp
+ * name, session name, and terminal size; a start's directory is arbitrary
+ * too. Each override replaces the default of its field.
+ */
+export function buildMockImpSessionRequest(overrides?: Partial<StartRequest>): StartRequest;
+export function buildMockImpSessionRequest(overrides: AttachOverrides): AttachRequest;
+
+export function buildMockImpSessionRequest(
+  overrides: Partial<StartRequest> | AttachOverrides = {},
+): ImpSessionRequest {
+  const name = `imp-${faker.string.alpha({ length: 6, casing: 'lower' })}`;
+  const session = faker.string.uuid();
+  const cols = faker.number.int({ min: 20, max: 300 });
+  const rows = faker.number.int({ min: 5, max: 100 });
+
+  return isAttachOverrides(overrides)
+    ? { name, session, cols, rows, wake: false, ...overrides }
+    : {
+        kind: 'start',
+        name,
+        session,
+        argv: ['true'],
+        env: {},
+        cwd: faker.system.directoryPath(),
+        cols,
+        rows,
+        ...overrides,
+      };
+}
+
+function isAttachOverrides(
+  overrides: Partial<StartRequest> | AttachOverrides,
+): overrides is AttachOverrides {
+  return overrides.kind === 'attach';
+}

package/src/test-utils/build-mock-message-record.ts

@@ -3,13 +3,17 @@ import { toMessageID } from '../shared/to-message-id';
 import { toSessionID } from '../shared/to-session-id';
 import type { MessageRecord } from '../store/message-record';
 
+type MessageRecordOverrides = {
+  readonly [K in keyof MessageRecord]?: MessageRecord[K] | undefined;
+};
+
 /**
  * A message accepted for a session and not yet delivered: a fresh message
  * id and a fresh atc id, an arbitrary sender, text, and send time, and no
  * agent session id, delivery, answer, or turn. An override replaces the
- * field it names.
+ * field it names, and an override of undefined leaves that field out.
  */
-export function buildMockMessageRecord(overrides: Partial<MessageRecord> = {}): MessageRecord {
+export function buildMockMessageRecord(overrides: MessageRecordOverrides = {}): MessageRecord {
   return {
     id: toMessageID(faker.string.uuid()),
     atcID: toSessionID(faker.string.uuid()),
@@ -17,6 +21,6 @@ export function buildMockMessageRecord(overrides: Partial<MessageRecord> = {}):
     text: faker.lorem.sentence(),
     status: 'accepted',
     sentAt: faker.date.past().getTime(),
-    ...overrides,
+    ...Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)),
   };
 }

package/src/test-utils/build-mock-stored-event.ts

@@ -0,0 +1,20 @@
+import { faker } from '@faker-js/faker';
+import { toSessionID } from '../shared/to-session-id';
+import type { StoredEvent } from '../store/state-store';
+
+/**
+ * A row of the event trail as the store reads it back: a `turn-done` event
+ * with an arbitrary row id, time, and fresh atc id, and no agent session
+ * id, detail, message, or label. Each override replaces the default of its field.
+ */
+export function buildMockStoredEvent(overrides: Partial<StoredEvent> = {}): StoredEvent {
+  return {
+    id: faker.number.int({ min: 1, max: 1_000_000 }),
+    at: faker.date.past().getTime(),
+    atcID: toSessionID(faker.string.uuid()),
+    agentSessionID: null,
+    kind: 'turn-done',
+    detail: null,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-stored-row.ts

@@ -0,0 +1,23 @@
+import { faker } from '@faker-js/faker';
+import type { StoredRow } from '../read-stored-rows';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+/**
+ * A fleet row a daemon has stored, for a live session with a fresh id, an
+ * arbitrary name, and no known agent session id. Overrides replace the
+ * defaults field by field.
+ */
+export function buildMockStoredRow(
+  overrides: MockOverrides<StoredRow, keyof StoredRow> = {},
+): StoredRow {
+  return mergeDeep<StoredRow>(
+    {
+      id: faker.string.uuid(),
+      name: faker.word.noun(),
+      exited: false,
+      agentSessionID: null,
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-stub-brokered-gateway-adapter.ts

@@ -0,0 +1,50 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+/**
+ * An agent adapter `glm` for daemon tests that only starts behind impd's
+ * broker and takes the credential of a GLM gateway from it: the auth
+ * profile `glm`, a custom bearer secret `glm` for api.z.ai, behind the
+ * gateway at https://api.z.ai/api/anthropic with the placeholder
+ * `ANTHROPIC_AUTH_TOKEN`. Every guest spawn sleeps, with the binding's
+ * variables, when it has one, and `CLAUDE_CONFIG_DIR` set to
+ * `claude-config` in the guest folder. Every other member is the plain
+ * agent adapter's.
+ */
+export function buildStubBrokeredGatewayAdapter(): AgentAdapter {
+  return buildMockAgentAdapter({
+    id: 'glm',
+    planGuestSpawn: (_opts, guest) => ({
+      bin: 'sleep',
+      args: ['30'],
+      files: {},
+      env: { ...guest.auth?.env, CLAUDE_CONFIG_DIR: `${guest.dir}/claude-config` },
+    }),
+    findAuthSelection: () => ({
+      brokerRequired: true,
+      gateway: {
+        id: 'glm',
+        baseURL: 'https://api.z.ai/api/anthropic',
+        auth: {
+          profiles: ['glm'],
+          placeholderEnv: { ANTHROPIC_AUTH_TOKEN: 'imp-broker-placeholder' },
+        },
+      },
+      profiles: new Map([
+        [
+          'glm',
+          {
+            name: 'glm',
+            secret: 'glm',
+            kind: 'custom',
+            host: 'api.z.ai',
+            header: 'authorization',
+            scheme: 'bearer',
+            env: {},
+            dependencies: [],
+          },
+        ],
+      ]),
+    }),
+  });
+}

package/src/test-utils/build-stub-held-gh.ts

@@ -1,18 +1,16 @@
 /**
  * The script of a stand-in `gh` whose repository listing waits for the
- * test. `gh config …` prints `https`. Any other command touches
- * `$HOME/gh-held` and waits while `$HOME/gh-hold` exists, then prints one
- * repository, `me/dots`, in the JSON shape `gh repo list` prints.
+ * test. `gh config …` prints `https`. Any other command waits while
+ * `$HOME/gh-hold` exists, touching `$HOME/gh-held` on each pass of the
+ * wait, so the marker appears only once the stand-in is held, then prints
+ * one repository, `me/dots`, in the JSON shape `gh repo list` prints.
  */
 export function buildStubHeldGH(): string {
   return `#!/bin/sh
 case "$1" in
   config) echo https ;;
   *)
-    if [ -f "$HOME/gh-hold" ]; then
-      touch "$HOME/gh-held"
-      while [ -f "$HOME/gh-hold" ]; do sleep 0.05; done
-    fi
+    while [ -f "$HOME/gh-hold" ]; do touch "$HOME/gh-held"; sleep 0.05; done
     echo '[{"nameWithOwner":"me/dots","description":"dotfiles","isPrivate":false,"url":"https://github.com/me/dots","sshUrl":"git@github.com:me/dots.git"}]' ;;
 esac
 `;

package/src/test-utils/build-stub-held-zoxide.ts

@@ -1,13 +1,11 @@
 /**
  * The script of a stand-in `zoxide` that lists no directories, and waits
- * for the test first: while `$HOME/zoxide-hold` exists, it touches
- * `$HOME/zoxide-held` and waits for the file to go.
+ * for the test first: while `$HOME/zoxide-hold` exists, it waits for the
+ * file to go, touching `$HOME/zoxide-held` on each pass of the wait, so the
+ * marker appears only once the stand-in is held.
  */
 export function buildStubHeldZoxide(): string {
   return `#!/bin/sh
-if [ -f "$HOME/zoxide-hold" ]; then
-  touch "$HOME/zoxide-held"
-  while [ -f "$HOME/zoxide-hold" ]; do sleep 0.05; done
-fi
+while [ -f "$HOME/zoxide-hold" ]; do touch "$HOME/zoxide-held"; sleep 0.05; done
 `;
 }

package/src/test-utils/build-stub-mcp-stdio-server.ts

@@ -0,0 +1,20 @@
+/**
+ * The script of a stand-in `atc mcp` server on stdio that answers each line
+ * it reads with the next of `replies`, printed as given, whether JSON or
+ * not, and reads stdin without answering once the replies run out. It
+ * exits without a reply when stdin ends before a line arrives. Before
+ * it reads anything, it records its pid in the file at its own path with
+ * `.pid` appended, moving the file into place so it appears whole.
+ */
+export function buildStubMCPStdioServer(replies: readonly string[]): string {
+  const answers = replies
+    .map((reply) => `read -r _ || exit 0\nprintf '%s\\n' ${toShellLiteral(reply)}\n`)
+    .join('');
+
+  return `#!/usr/bin/env bash\necho $$ > "$0.pid.tmp"\nmv "$0.pid.tmp" "$0.pid"\n${answers}exec cat > /dev/null\n`;
+}
+
+// Quotes a value for the shell as one word, whatever it holds.
+function toShellLiteral(value: string): string {
+  return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}

package/src/test-utils/build-stub-recording-filter.ts

@@ -0,0 +1,9 @@
+/**
+ * The script of a stand-in git filter driver that records each run by
+ * appending the line `ran` to the record file and passes its input through
+ * unchanged, as a smudge filter that changes nothing does, so a test can
+ * tell whether git ran a filter the host configured.
+ */
+export function buildStubRecordingFilter(record: string): string {
+  return `#!/bin/sh\necho ran >> '${record}'\ncat\n`;
+}

package/src/test-utils/build-stub-recording-git.ts

@@ -0,0 +1,8 @@
+/**
+ * The script of a stand-in `git` that records each run by appending the
+ * line `ran` to the record file, then exits 0 without doing anything else,
+ * so a test can tell whether the code under test ran git at all.
+ */
+export function buildStubRecordingGit(record: string): string {
+  return `#!/bin/sh\necho ran >> '${record}'\n`;
+}

package/src/test-utils/create-git-fixture.ts

@@ -22,17 +22,16 @@ interface GitFixtureConfig {
  *
  * The first call in a process builds a template pair under the test home,
  * and each call copies it, so a fixture costs a copy instead of a run of
- * git commands. Disposal removes the directory; hold the result with
- * `await using`.
+ * git commands. The directory is removed once the current test finishes,
+ * so it must run inside a test; disposal removes it sooner, and a second
+ * removal does nothing.
  */
 export async function createGitFixture(config: GitFixtureConfig = {}) {
   const env = buildGitEnv(process.env);
 
   const template = await resolveTemplate();
 
-  await using stack = new AsyncDisposableStack();
-
-  const tmp = stack.use(setupTempDir(config.prefix ?? 'atc-git-fixture-'));
+  const tmp = setupTempDir(config.prefix ?? 'atc-git-fixture-');
   const upstream = join(tmp.dir, 'upstream.git');
   const work = join(tmp.dir, 'work');
 
@@ -51,15 +50,13 @@ export async function createGitFixture(config: GitFixtureConfig = {}) {
     ),
   );
 
-  const owned = stack.move();
-
   return {
     dir: tmp.dir,
     env,
     upstream,
     work,
     sha: template.sha,
-    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+    [Symbol.asyncDispose]: tmp[Symbol.asyncDispose],
   };
 }
 

package/src/test-utils/create-stub-claude.ts

@@ -29,7 +29,8 @@ interface StubClaudeConfig {
  * first stub to find it removes it; `fake-claude-tap` runs `atc tap` into
  * `$HOME/tap.jsonl`; `fake-claude-events.jsonl` holds more hook payloads to
  * report, one per line, after the `Notification`; `fake-claude-exit` exits
- * once they are reported.
+ * once they are reported; `fake-claude-composer-last` runs the composer once
+ * they are reported.
  */
 export function createStubClaude(dir: string, config: StubClaudeConfig): string {
   const atc = config.atc.map((part) => `"${part}"`).join(' ');
@@ -69,6 +70,7 @@ if [ -f "$HOME/fake-claude-events.jsonl" ]; then
   done < "$HOME/fake-claude-events.jsonl"
 fi
 if [ -f "$HOME/fake-claude-exit" ]; then exit 0; fi
+if [ -f "$HOME/fake-claude-composer-last" ]; then exec "${process.execPath}" "${config.composer}"; fi
 while read -r line; do echo "GOT:$line"; done
 `,
   );

package/src/test-utils/create-stub-echo-claude.ts

@@ -0,0 +1,21 @@
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in for the Claude CLI as `fake-claude` under the directory
+ * and returns its path. It prints `UP:<pid>`, then reads one line at a time
+ * and prints `GOT:<line>:<pid>` after each, so a test sees which process
+ * took its input. A `quit` line ends it with exit code 3.
+ */
+export function createStubEchoClaude(dir: string): string {
+  return createStubBin(
+    dir,
+    'fake-claude',
+    `#!/usr/bin/env bash
+echo "UP:$$"
+while read -r line; do
+  if [ "$line" = "quit" ]; then exit 3; fi
+  echo "GOT:$line:$$"
+done
+`,
+  );
+}

package/src/test-utils/{build-stub-imp-port.ts → create-stub-imp-port.ts}

@@ -29,6 +29,7 @@ import type {
 import { ImpPortError } from '../daemon/imp-port-error';
 import { isImpNameAllowed } from '../daemon/is-imp-name-allowed';
 import { isBrokerVariable } from '../shared/is-broker-variable';
+import { registerTestCleanup } from './register-test-cleanup';
 
 // impd keeps exactly this many bytes of each generation's output.
 const RING_BYTES = 262_144;
@@ -51,7 +52,7 @@ interface StubCommandHold {
 }
 
 /**
- * The impd stand-in the factory below builds, one per call.
+ * The impd stand-in the factory below creates, one per call.
  */
 class StubImpPort implements ImpPort {
   // Every port call, in order, as `<call> <imp> [<detail>]`.
@@ -60,6 +61,9 @@ class StubImpPort implements ImpPort {
   // Every session request the port received, in order.
   readonly sessionRequests: ImpSessionRequest[] = [];
 
+  // The spec of every imp create the port received, in order.
+  readonly createSpecs: ImpCreateSpec[] = [];
+
   features: ImpFeatures = {
     sessionOffsets: true,
     leases: true,
@@ -117,6 +121,9 @@ class StubImpPort implements ImpPort {
   // Feature reads still to fail as an unreachable impd before they answer.
   private featureFailures = 0;
 
+  // Feature reads that failed as an unreachable impd.
+  private failedFeatureReads = 0;
+
   // Session connections whose opening still throws before it returns, as
   // an invalid authorization header makes the socket's constructor throw.
   private openFailures = 0;
@@ -153,6 +160,9 @@ class StubImpPort implements ImpPort {
     readonly done: PromiseWithResolvers<void>;
   } | null = null;
 
+  // How many commands wait on a command hold.
+  private heldCommands = 0;
+
   // Commands whose argv holds this text exit 1 without running, or null.
   private commandFailure: string | null = null;
 
@@ -191,6 +201,7 @@ class StubImpPort implements ImpPort {
 
     if (this.featureFailures > 0) {
       this.featureFailures -= 1;
+      this.failedFeatureReads += 1;
 
       return Promise.reject(new ImpPortError('UNREACHABLE', 'impd did not answer'));
     }
@@ -294,6 +305,7 @@ class StubImpPort implements ImpPort {
 
   createImp(spec: ImpCreateSpec): Promise<ImpView> {
     this.calls.push(`imps.create ${spec.name}`);
+    this.createSpecs.push(spec);
 
     if (this.imps.has(spec.name)) {
       return Promise.reject(
@@ -591,7 +603,11 @@ class StubImpPort implements ImpPort {
     if (hold !== null && line.includes(hold.match)) {
       hold.entered.resolve(line);
 
+      this.heldCommands += 1;
+
       await hold.done.promise;
+
+      this.heldCommands -= 1;
     }
 
     if (this.commandFailure !== null && line.includes(this.commandFailure)) {
@@ -1054,6 +1070,11 @@ class StubImpPort implements ImpPort {
     return { entered: hold.entered.promise, stop, [Symbol.dispose]: stop };
   }
 
+  // How many commands wait for their command hold to stop.
+  countHeldCommands(): number {
+    return this.heldCommands;
+  }
+
   // Lets every command the active hold holds run, and the next at once.
   stopCommandHold(): void {
     const hold = this.commandHold;
@@ -1092,6 +1113,11 @@ class StubImpPort implements ImpPort {
     this.featureFailures = count;
   }
 
+  // How many feature reads failed as an unreachable impd.
+  countFailedFeatureReads(): number {
+    return this.failedFeatureReads;
+  }
+
   /**
    * Refuses the next session request with an impd code and its data, or the
    * message of the refusal when it carries one instead.
@@ -1604,7 +1630,7 @@ class StubImpPort implements ImpPort {
 }
 
 /**
- * Builds an in-process stand-in for impd behind the imp port, calling impd
+ * Creates an in-process stand-in for impd behind the imp port, calling impd
  * as the principal, `token:atc` when absent. Each imp is a set of
  * real `bun-pty` processes on this machine; a sleeping imp stops them with
  * SIGSTOP and a wake continues them, so a memory wake keeps each process
@@ -1622,10 +1648,18 @@ class StubImpPort implements ImpPort {
  * `PRECONDITION_FAILED` and reason `broker_not_ready`, and runs nothing,
  * while the broker fails or the imp holds no grant, when the start sets a
  * broker variable, and when it would join a process that started without
- * the broker required.
+ * the broker required. Once the current test finishes, the stand-in kills
+ * every process and stops every forward it holds, so it must be created inside
+ * a test; disposal does so sooner, and a second disposal does nothing.
  */
-export function buildStubImpPort(principal = 'token:atc'): StubImpPort {
-  return new StubImpPort(principal);
+export function createStubImpPort(principal = 'token:atc'): StubImpPort {
+  const port = new StubImpPort(principal);
+
+  registerTestCleanup(() => {
+    port[Symbol.dispose]();
+  });
+
+  return port;
 }
 
 interface StubLease {

package/src/test-utils/create-stub-recording-codex.ts

@@ -0,0 +1,20 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in for the Codex CLI as `fake-codex` under the directory
+ * and returns its path. Each start appends one line to `codex-starts.log`
+ * under the same directory: the `CODEX_HOME` it started with, then its
+ * arguments, separated by spaces. It then stays up without reporting
+ * anything. The log exists only once a start has run, so a test proves that
+ * no harness started by its absence.
+ */
+export function createStubRecordingCodex(dir: string): string {
+  const log = join(dir, 'codex-starts.log');
+
+  return createStubBin(
+    dir,
+    'fake-codex',
+    `#!/bin/sh\necho "$CODEX_HOME $*" >> '${log}'\nexec sleep 30\n`,
+  );
+}