@zgeoff/atc 3.3.0 → 3.4.0

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

@@ -0,0 +1,120 @@
+import { cpSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { $ } from 'bun';
+import { setupTempDir } from './setup-temp-dir';
+
+interface GitFixtureConfig {
+  // The temp directory's name prefix.
+  readonly prefix?: string;
+}
+
+/**
+ * A bare upstream at `upstream.git` on branch `main` and a work clone of it
+ * at `work`, both in a fresh temp directory, holding one pushed commit that
+ * adds `README.md`. The clone commits as `atc <atc@example.com>` without
+ * signing, and its origin is this fixture's own upstream. `sha` is that
+ * commit's id, the same in every fixture. `env` is the process environment
+ * without any `GIT_*` variable and with the host's system and global git
+ * config switched off: a git hook exports `GIT_DIR` and friends, which
+ * would point git at the repository running the hook, and a system-wide Git
+ * LFS install adds a pre-push hook that refuses the fixture. Run every git
+ * command a test adds with it.
+ *
+ * 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`.
+ */
+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 upstream = join(tmp.dir, 'upstream.git');
+  const work = join(tmp.dir, 'work');
+
+  cpSync(template.dir, tmp.dir, { recursive: true });
+
+  // The copied clone's config still holds the template's upstream as its
+  // origin; it is pointed at this fixture's own upstream instead, so a push
+  // never reaches the template or another fixture.
+  const gitConfig = join(work, '.git', 'config');
+
+  writeFileSync(
+    gitConfig,
+    readFileSync(gitConfig, 'utf8').replace(
+      `url = ${join(template.dir, 'upstream.git')}`,
+      `url = ${upstream}`,
+    ),
+  );
+
+  const owned = stack.move();
+
+  return {
+    dir: tmp.dir,
+    env,
+    upstream,
+    work,
+    sha: template.sha,
+    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+  };
+}
+
+function buildGitEnv(
+  source: Readonly<Record<string, string | undefined>>,
+): Record<string, string | undefined> {
+  return {
+    ...Object.fromEntries(Object.entries(source).filter(([name]) => !name.startsWith('GIT_'))),
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: '/dev/null',
+  };
+}
+
+interface GitTemplate {
+  readonly dir: string;
+  readonly sha: string;
+}
+
+// The template pair, built once per process.
+let template: Promise<GitTemplate> | null = null;
+
+function resolveTemplate(): Promise<GitTemplate> {
+  template ??= createTemplate();
+
+  return template;
+}
+
+// The template lives under the test home, which the test script removes
+// when the run ends.
+async function createTemplate(): Promise<GitTemplate> {
+  const env = buildGitEnv(process.env);
+  const home = process.env['ATC_TEST_HOME'];
+
+  if (home === undefined) {
+    throw new Error('a git fixture needs the test home; run `bun run test`');
+  }
+
+  const dir = mkdtempSync(join(home, 'git-fixture-template-'));
+  const upstream = join(dir, 'upstream.git');
+  const work = join(dir, 'work');
+
+  await $`git init --quiet --bare --template= --initial-branch=main ${upstream}`.env(env).quiet();
+  await $`git clone --quiet --template= ${upstream} ${work}`.env(env).quiet();
+  await $`git config user.name atc`.env(env).cwd(work).quiet();
+  await $`git config user.email atc@example.com`.env(env).cwd(work).quiet();
+  await $`git config commit.gpgsign false`.env(env).cwd(work).quiet();
+  await $`git config tag.gpgsign false`.env(env).cwd(work).quiet();
+
+  writeFileSync(join(work, 'README.md'), 'hello\n');
+
+  await $`git add README.md`.env(env).cwd(work).quiet();
+  await $`git commit --quiet -m initial`.env(env).cwd(work).quiet();
+  await $`git push --quiet origin main`.env(env).cwd(work).quiet();
+
+  const head = await $`git rev-parse HEAD`.env(env).cwd(work).quiet().text();
+
+  return { dir, sha: head.trim() };
+}

package/src/test-utils/create-migrated-state-db.ts

@@ -11,24 +11,26 @@ let template: Promise<string> | undefined;
  * that needs a ready store skips the migration ladder. Each copy is a file of
  * its own; every copy holds the same daemon id, minted when the template was
  * migrated. The template sits in the test home, which the test script removes
- * on exit.
+ * on exit, under a name of its own per process, since parallel test processes
+ * share that home. It rejects when `ATC_TEST_HOME` is unset, as it is
+ * outside the test script.
  */
 export async function createMigratedStateDB(dbPath: string): Promise<void> {
-  template ??= createTemplateStateDB();
-
-  const templatePath = await template;
-
-  copyFileSync(templatePath, dbPath);
-}
-
-async function createTemplateStateDB(): Promise<string> {
   const home = process.env['ATC_TEST_HOME'];
 
   if (home === undefined) {
     throw new Error('ATC_TEST_HOME is unset; run the tests through `bun run test`');
   }
 
-  const path = join(home, 'migrated-state.db');
+  template ??= createTemplateStateDB(home);
+
+  const templatePath = await template;
+
+  copyFileSync(templatePath, dbPath);
+}
+
+async function createTemplateStateDB(home: string): Promise<string> {
+  const path = join(home, `migrated-state-${String(process.pid)}.db`);
 
   const store = await StateStore.open(path);
 

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

@@ -0,0 +1,19 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Creates a stand-in command-line tool: the script, shebang included, as an
+ * executable file under the directory, which it creates when missing.
+ * Returns the script's path. Writing over an existing file replaces its
+ * content and makes it executable as well, so a test can swap a tool's
+ * behaviour mid-run.
+ */
+export function createStubBin(dir: string, name: string, script: string): string {
+  const path = join(dir, name);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, script);
+  chmodSync(path, 0o755);
+
+  return path;
+}

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

@@ -0,0 +1,75 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubClaudeConfig {
+  // The command atc runs as, which the stub's tap and restart go through.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in when the home asks for it.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Claude CLI as `fake-claude` under the
+ * directory and returns its path. Like the real CLI, it runs the
+ * `SessionStart` hook command from the `--settings` file atc passed it
+ * through a shell, feeding each hook its JSON payload on stdin, so a session
+ * reports with the command line atc wrote for its agent. It prints its
+ * arguments, its TERM, and whether it inherited a parent-session variable,
+ * appends its atc session id to `$HOME/fake-claude-starts.log`, reports a
+ * `SessionStart` as `fake-1` and a `Notification` asking for permission, then
+ * echoes each input line as `GOT:<line>`.
+ *
+ * Files in `$HOME` steer a scenario: `fake-claude-dies-<id>` exits at once
+ * when the stub resumes that agent session; `fake-claude-hold-start` reports
+ * nothing and only echoes input; `fake-claude-composer` runs the composer
+ * instead; `fake-claude-gate` waits for one input line before it reports,
+ * and the first stub to find it removes it; `fake-claude-own-id` reports the
+ * atc session id as the agent session; `fake-claude-restart` runs
+ * `atc daemon restart` into `$HOME/restart.out` after `SessionStart`, and the
+ * 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.
+ */
+export function createStubClaude(dir: string, config: StubClaudeConfig): string {
+  const atc = config.atc.map((part) => `"${part}"`).join(' ');
+
+  return createStubBin(
+    dir,
+    'fake-claude',
+    `#!/usr/bin/env bash
+echo "FAKE_CLAUDE_UP args: $@"
+echo "FAKE_CLAUDE_TERM:[\${TERM-unset}]"
+echo "FAKE_CLAUDE_PARENT:[\${CLAUDE_CODE_ATC_TEST-unset}]"
+echo "$ATC_SESSION_ID" >> "$HOME/fake-claude-starts.log"
+settings=""
+resume=""
+prev=""
+for arg in "$@"; do
+  if [ "$prev" = "--settings" ]; then settings="$arg"; fi
+  if [ "$prev" = "--resume" ]; then resume="$arg"; fi
+  prev="$arg"
+done
+if [ -n "$resume" ] && [ -f "$HOME/fake-claude-dies-$resume" ]; then exit 0; fi
+if [ -f "$HOME/fake-claude-hold-start" ]; then while read -r line; do echo "GOT:$line"; done; exit 0; fi
+if [ -f "$HOME/fake-claude-composer" ]; then exec "${process.execPath}" "${config.composer}"; fi
+hookCommand="$("${process.execPath}" -e 'const s = JSON.parse(require("fs").readFileSync(process.argv.at(-1), "utf8")); console.log(s.hooks.SessionStart[0].hooks[0].command)' "$settings" < /dev/null)"
+hookReport() { sh -c "$hookCommand"; }
+sessionID="fake-1"
+if [ -f "$HOME/fake-claude-own-id" ]; then sessionID="$ATC_SESSION_ID"; fi
+if [ -f "$HOME/fake-claude-gate" ]; then rm "$HOME/fake-claude-gate"; read -r _; fi
+printf '{"hook_event_name":"SessionStart","session_id":"%s","transcript_path":"%s/fake-transcript.jsonl"}' "$sessionID" "$HOME" | hookReport
+if [ -f "$HOME/fake-claude-restart" ]; then rm "$HOME/fake-claude-restart"; ${atc} daemon restart > "$HOME/restart.out" 2>&1; fi
+if [ -f "$HOME/fake-claude-tap" ]; then ${atc} tap --session "$ATC_SESSION_ID" >> "$HOME/tap.jsonl" & fi
+printf '{"hook_event_name":"Notification","session_id":"%s","message":"needs permission"}' "$sessionID" | hookReport
+if [ -f "$HOME/fake-claude-events.jsonl" ]; then
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    printf '%s' "$ev" | hookReport
+  done < "$HOME/fake-claude-events.jsonl"
+fi
+if [ -f "$HOME/fake-claude-exit" ]; then exit 0; fi
+while read -r line; do echo "GOT:$line"; done
+`,
+  );
+}

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

@@ -0,0 +1,31 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubCodexConfig {
+  // The command atc runs as; the stub reports each hook through its
+  // `hook-report --agent codex`, as the hook entries atc prints for Codex do.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Codex CLI as `fake-codex` under the directory
+ * and returns its path. It prints its arguments, reports a `SessionStart`
+ * as `fake-codex-1` with its working directory and a rollout under `$HOME`,
+ * then a `Stop` whose last message is `pong`, then runs the composer.
+ */
+export function createStubCodex(dir: string, config: StubCodexConfig): string {
+  const report = `${config.atc.map((part) => `"${part}"`).join(' ')} hook-report --agent codex`;
+
+  return createStubBin(
+    dir,
+    'fake-codex',
+    `#!/usr/bin/env bash
+echo "FAKE_CODEX_UP args: $@"
+printf '{"hook_event_name":"SessionStart","session_id":"fake-codex-1","transcript_path":"%s/fake-rollout.jsonl","cwd":"%s","source":"startup"}' "$HOME" "$PWD" | ${report}
+printf '{"hook_event_name":"Stop","session_id":"fake-codex-1","transcript_path":"%s/fake-rollout.jsonl","last_assistant_message":"pong"}' "$HOME" | ${report}
+exec "${process.execPath}" "${config.composer}"
+`,
+  );
+}

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

@@ -0,0 +1,65 @@
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates the composer the stub agents finish in, as `fake-composer.js`
+ * under the directory, and returns its path; run it with bun. It is modelled
+ * on the TUIs Codex and Grok draw: raw mode with bracketed paste on. Each
+ * read is one input event batch. A bracketed paste lands in the composer
+ * whole, newlines kept; a lone CR outside a paste submits; a lone LF is
+ * Ctrl-J and adds a newline; any other read of more than one byte is a paste
+ * burst whose line breaks stay in the composer. A read that ends partway
+ * into a paste marker holds that part for the next read. It prints
+ * `FAKE_COMPOSER_READY` once paste mode is on, every byte received so far as
+ * `RECEIVED:<json>` after each read, and each submission as `SUBMIT:<json>`.
+ */
+export function createStubComposer(dir: string): string {
+  return createStubBin(
+    dir,
+    'fake-composer.js',
+    String.raw`const OPEN = '\u001B[200~';
+const CLOSE = '\u001B[201~';
+let composer = '';
+let pasting = false;
+let held = '';
+let received = '';
+process.stdin.setRawMode(true);
+process.stdout.write('\u001B[?2004hFAKE_COMPOSER_READY\r\n');
+process.stdin.on('data', (buf) => {
+  const chunk = buf.toString('utf8');
+  received += chunk;
+  process.stdout.write('RECEIVED:' + JSON.stringify(received) + '\r\n');
+  let rest = held + chunk;
+  held = '';
+  const cut = rest.lastIndexOf('\u001B');
+  const tail = cut === -1 ? '' : rest.slice(cut);
+  if (tail !== '' && tail.length < CLOSE.length && (OPEN.startsWith(tail) || CLOSE.startsWith(tail))) {
+    held = tail;
+    rest = rest.slice(0, cut);
+  }
+  while (rest !== '') {
+    if (pasting) {
+      const end = rest.indexOf(CLOSE);
+      composer += (end === -1 ? rest : rest.slice(0, end)).replaceAll('\r', '\n');
+      pasting = end === -1;
+      rest = end === -1 ? '' : rest.slice(end + CLOSE.length);
+      continue;
+    }
+    if (rest.startsWith(OPEN)) {
+      pasting = true;
+      rest = rest.slice(OPEN.length);
+      continue;
+    }
+    const next = rest.indexOf(OPEN);
+    const plain = next === -1 ? rest : rest.slice(0, next);
+    rest = next === -1 ? '' : rest.slice(next);
+    if (plain === '\r') {
+      process.stdout.write('SUBMIT:' + JSON.stringify(composer) + '\r\n');
+      composer = '';
+    } else {
+      composer += plain.replaceAll('\r', '\n');
+    }
+  }
+});
+`,
+  );
+}

package/src/test-utils/create-stub-failing-agent-adapter.ts

@@ -0,0 +1,111 @@
+import type { AgentAdapter } from '../agents/agent-adapter';
+import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+
+interface Plan {
+  readonly bin: string;
+  readonly args: readonly string[];
+}
+
+// A named pipe the first spawn's process writes its pid to once it is ready
+// to be killed, and how long the first failing read waits for that pid.
+interface ReadyPipe {
+  readonly path: string;
+  readonly timeoutMs: number;
+}
+
+interface FailingAgentAdapterConfig {
+  // What the first spawn runs, and what every later spawn runs.
+  readonly firstPlan: Plan;
+  readonly laterPlan: Plan;
+
+  // How many reads of the headless runner throw once the first spawn is
+  // planned: one fails the start after its process started, and a second
+  // fails the kill that takes the process back.
+  readonly failedReads: number;
+
+  // The pipe the first failing read waits on. Null fails at once.
+  readonly ready: ReadyPipe | null;
+}
+
+/**
+ * An agent adapter whose first spawn fails after its process has started:
+ * the daemon reads the adapter's headless runner once the process runs, and
+ * that read throws, as many times as the config holds, while every other
+ * read finds no headless runner. Every member but the spawn plan and the
+ * headless runner is the mock adapter's.
+ *
+ * With a ready pipe, the stub makes the pipe at that path, and the first
+ * failing read blocks until a process writes its pid there, which the
+ * headless runner read is synchronous for. A read that finds no writer
+ * within the timeout throws instead of failing the start. `getReadyPID`
+ * returns the pid that read took. `countPlans` reads how many spawns the
+ * adapter has planned.
+ */
+export function createStubFailingAgentAdapter(config: FailingAgentAdapterConfig) {
+  let planned = 0;
+  let readsToFail = 0;
+  let readyPID: number | null = null;
+
+  if (config.ready !== null) {
+    createPipe(config.ready.path);
+  }
+
+  const adapter: AgentAdapter = {
+    ...buildMockAgentAdapter(),
+    planSpawn: () => {
+      planned += 1;
+
+      if (planned > 1) {
+        return { bin: config.laterPlan.bin, args: [...config.laterPlan.args] };
+      }
+
+      readsToFail = config.failedReads;
+
+      return { bin: config.firstPlan.bin, args: [...config.firstPlan.args] };
+    },
+    get headlessRunner() {
+      if (readsToFail === 0) {
+        return null;
+      }
+
+      if (readsToFail === config.failedReads && config.ready !== null) {
+        readyPID = readPID(config.ready);
+      }
+
+      readsToFail -= 1;
+      throw new Error('adapter failed after the process started');
+    },
+  };
+
+  return {
+    adapter,
+    countPlans: () => planned,
+    getReadyPID: (): number => {
+      if (readyPID === null) {
+        throw new Error('no process has written its pid to the ready pipe');
+      }
+
+      return readyPID;
+    },
+  };
+}
+
+function createPipe(path: string): void {
+  const made = Bun.spawnSync(['mkfifo', path]);
+
+  if (made.exitCode !== 0) {
+    throw new Error(`mkfifo could not make ${path} (${made.stderr.toString().trim()})`);
+  }
+}
+
+// Reading the pipe blocks until a writer opens it and closes it, so the
+// read returns once the process has written its pid.
+function readPID(ready: ReadyPipe): number {
+  const read = Bun.spawnSync({ cmd: ['cat', ready.path], timeout: ready.timeoutMs });
+
+  if (read.exitedDueToTimeout === true) {
+    throw new Error(`no process wrote ${ready.path} within ${String(ready.timeoutMs)}ms`);
+  }
+
+  return Number(read.stdout.toString().trim());
+}

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

@@ -0,0 +1,44 @@
+import { createStubBin } from './create-stub-bin';
+
+interface StubGrokConfig {
+  // The command atc runs as; the stub reports each hook through its
+  // `hook-report --agent grok`, as the hook file atc prints for Grok does.
+  readonly atc: readonly string[];
+
+  // The composer script the stub finishes in.
+  readonly composer: string;
+}
+
+/**
+ * Creates a stand-in for the Grok CLI as `fake-grok` under the directory and
+ * returns its path. It prints its arguments, reports a `session_start` as
+ * `fake-grok-1` with its working directory and a `notification` asking
+ * permission to edit, prints `FAKE_GROK_HOOKS_DONE` once its reports are
+ * sent, then runs the composer. Files in `$HOME` steer a scenario:
+ * `fake-grok-hold-start` reports nothing and only echoes input lines as
+ * `GOT:<line>`; `fake-grok-events.jsonl` holds the hook payloads to report
+ * after `session_start` in place of the notification, one per line.
+ */
+export function createStubGrok(dir: string, config: StubGrokConfig): string {
+  const report = `${config.atc.map((part) => `"${part}"`).join(' ')} hook-report --agent grok`;
+
+  return createStubBin(
+    dir,
+    'fake-grok',
+    `#!/usr/bin/env bash
+echo "FAKE_GROK_UP args: $@"
+if [ -f "$HOME/fake-grok-hold-start" ]; then while read -r line; do echo "GOT:$line"; done; exit 0; fi
+printf '{"hookEventName":"session_start","sessionId":"fake-grok-1","cwd":"%s"}' "$PWD" | ${report}
+if [ -f "$HOME/fake-grok-events.jsonl" ]; then
+  while IFS= read -r ev; do
+    [ -n "$ev" ] || continue
+    printf '%s' "$ev" | ${report}
+  done < "$HOME/fake-grok-events.jsonl"
+else
+  printf '{"hookEventName":"notification","sessionId":"fake-grok-1","notificationType":"permission_prompt","message":"allow edit?"}' | ${report}
+fi
+echo "FAKE_GROK_HOOKS_DONE"
+exec "${process.execPath}" "${config.composer}"
+`,
+  );
+}

package/src/test-utils/create-stub-guest-clis.ts

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates the command-line tools a remote host runs for a session, as
+ * scripts under the directory: `atc` runs the atc CLI from this source tree,
+ * and `claude` is a stand-in agent that prints `UP:<pid>`, then reads one
+ * command per line and prints `GOT:<line>` after each, reporting through
+ * that atc:
+ *
+ * - `start <id>`: a SessionStart for agent session `<id>`, with a
+ *   transcript at a path only the host holds;
+ * - `notify <text>`: a Notification carrying the text;
+ * - `nested <id>`: a SessionStart for agent session `<id>` from a Codex
+ *   harness nested inside the session;
+ * - `forge <session>`: a Notification as atc session `<session>` instead
+ *   of its own;
+ * - `tap <file>`: the session's tap, run in the background and printing
+ *   into the file;
+ * - `answer <message> <text>`: the message answered with the text;
+ * - `note <text>`: a note labelled `progress`.
+ *
+ * Returns each tool's path.
+ */
+export function createStubGuestCLIs(dir: string) {
+  const cliPath = join(import.meta.dir, '..', 'cli.ts');
+
+  const atc = createStubBin(
+    dir,
+    'atc',
+    `#!/bin/sh\nexec "${process.execPath}" "${cliPath}" "$@"\n`,
+  );
+
+  const claude = createStubBin(
+    dir,
+    'claude',
+    `#!/usr/bin/env bash
+echo "UP:$$"
+while read -r line; do
+  case "$line" in
+    start\\ *) printf '{"hook_event_name":"SessionStart","session_id":"%s","transcript_path":"/guest/only/transcript.jsonl"}' "\${line#start }" | "${atc}" hook-report --agent claude ;;
+    notify\\ *) printf '{"hook_event_name":"Notification","message":"%s"}' "\${line#notify }" | "${atc}" hook-report --agent claude ;;
+    nested\\ *) printf '{"hook_event_name":"SessionStart","session_id":"%s","source":"startup"}' "\${line#nested }" | "${atc}" hook-report --agent codex ;;
+    forge\\ *) echo '{"hook_event_name":"Notification","message":"forged"}' | ATC_SESSION_ID="\${line#forge }" "${atc}" hook-report --agent claude ;;
+    tap\\ *) "${atc}" tap --session "$ATC_SESSION_ID" >> "\${line#tap }" 2>&1 & ;;
+    answer\\ *) rest="\${line#answer }"; printf '%s' "\${rest#* }" | "${atc}" report answered --messages "\${rest%% *}" ;;
+    note\\ *) printf '%s' "\${line#note }" | "${atc}" report note --label progress ;;
+  esac
+  echo "GOT:$line"
+done
+`,
+  );
+
+  return { atc, claude };
+}

package/src/test-utils/create-stub-harness-guest.ts

@@ -0,0 +1,35 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in guest program for a harness to run, under the
+ * directory: a script that prints its pid and the terminal size it started
+ * at as `UP:<pid> START:<rows> <cols>`, echoes each line it reads as
+ * `GOT:<line>`, prints `SIZE:<rows> <cols>` on `size`, and exits 3 on
+ * `quit`. On `later` it waits for a line on the named pipe at `burstPath`,
+ * then prints 300000 `x` bytes, more than impd's ring keeps, a newline, and
+ * `BURST_DONE`. Returns the script's path and the pipe's.
+ */
+export function createStubHarnessGuest(dir: string) {
+  const burstPath = join(dir, 'burst');
+
+  Bun.spawnSync(['mkfifo', burstPath]);
+
+  const path = createStubBin(
+    dir,
+    'harness',
+    `#!/usr/bin/env bash
+echo "UP:$$ START:$(stty size)"
+while read -r line; do
+  if [ "$line" = "later" ]; then
+    (cat "${burstPath}" > /dev/null; head -c 300000 /dev/zero | tr '\\0' 'x'; echo; echo "BURST_DONE") &
+  fi
+  if [ "$line" = "size" ]; then echo "SIZE:$(stty size)"; fi
+  if [ "$line" = "quit" ]; then exit 3; fi
+  echo "GOT:$line"
+done
+`,
+  );
+
+  return { path, burstPath };
+}

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

@@ -0,0 +1,20 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+/**
+ * Creates a stand-in for the Claude CLI as `fake-claude` under the
+ * directory and returns its path. Each start appends its arguments to
+ * `claude-starts.log` under the same directory, one per line, ends the
+ * start with an empty line, and then stays up without reporting anything,
+ * as a session whose agent never speaks does. The log exists only once a
+ * start has run, so a test proves that no harness started by its absence.
+ */
+export function createStubRecordingClaude(dir: string): string {
+  const log = join(dir, 'claude-starts.log');
+
+  return createStubBin(
+    dir,
+    'fake-claude',
+    `#!/bin/sh\n{ printf '%s\\n' "$@"; echo; } >> '${log}'\nexec sleep 30\n`,
+  );
+}

package/src/test-utils/{setup-fake-systemd.ts → create-stub-systemd.ts}

@@ -2,8 +2,8 @@ import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-interface FakeSystemd {
-  // The directory that holds the fake `systemctl` and `systemd-run`, to put
+interface StubSystemd {
+  // The directory that holds the stand-in `systemctl` and `systemd-run`, to put
   // first on the PATH of every process that could reach a real one.
   readonly binDir: string;
 
@@ -27,7 +27,7 @@ interface FakeSystemd {
 }
 
 /**
- * Writes a fake `systemctl` and `systemd-run` that touch no service
+ * Writes a stand-in `systemctl` and `systemd-run` that touch no service
  * manager. Without a MainPID, `systemctl show -p MainPID` prints a pid no
  * process holds, so no daemon is ever a unit's main process. With
  * `writeMainPID`, `systemctl restart` stops that pid with SIGTERM and starts
@@ -36,8 +36,8 @@ interface FakeSystemd {
  * unit sees them, and appends its output to the `StandardOutput=append:`
  * file. Every call is logged.
  */
-export function setupFakeSystemd(atcCommand: readonly string[]): FakeSystemd {
-  const root = mkdtempSync(join(tmpdir(), 'atc-fake-systemd-'));
+export function createStubSystemd(atcCommand: readonly string[]): StubSystemd {
+  const root = mkdtempSync(join(tmpdir(), 'atc-stub-systemd-'));
   const binDir = join(root, 'bin');
   const procRoot = join(root, 'proc');
   const atcLine = atcCommand.map((part) => `"${part}"`).join(' ');

package/src/test-utils/get-gateway-config.ts

@@ -4,11 +4,11 @@ import { getAgentEntry } from './get-agent-entry';
 
 /**
  * The gateway a parsed config holds under an agent id: a Claude entry with a
- * base URL. Throws when the config holds no such agent or the entry has no
- * base URL.
+ * base URL, without the registry's `kind`, which a gateway does not carry.
+ * Throws when the config holds no such agent or the entry has no base URL.
  */
 export function getGatewayConfig(config: Pick<Config, 'agents'>, id: string): GatewayConfig {
-  const entry = getAgentEntry(config, id);
+  const { kind: _kind, ...entry } = getAgentEntry(config, id);
 
   if (entry.baseURL === undefined) {
     throw new Error(`the agent '${id}' has no baseURL`);