@zgeoff/atc 3.3.1 → 3.4.1

package/src/test-utils/{fixture-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;
@@ -36,45 +37,33 @@ const RING_BYTES = 262_144;
 // The mode bytes a fresh attach sends ahead of a ring that has wrapped.
 const PRELUDE = '\u001B[0m';
 
-// The PATH every fixture process runs with: a guest's own, never the
+// The PATH every stub process runs with: a guest's own, never the
 // daemon's.
 const GUEST_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
 
-/**
- * An in-process stand-in for impd behind the imp port. 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
- * and its generation. Every session keeps an exact 262144-byte ring with
- * offsets, a fresh attach skips to the next line and sends a mode prelude,
- * and impd's refusals carry its codes and data: `LEASED`, `LEASE_NOT_HELD`,
- * `NO_SESSION`, `INVALID_STATE`, `INVALID_RESUME`, `NOT_FOUND`, `CONFLICT`,
- * and `FORBIDDEN`. Leases belong to principals; the port acts as
- * `principal`, and a test adds other owners' leases, cold boots, and
- * dropped sockets through the controls. Grants follow impd 0.27: the
- * caller's identity must reach the imp and, under imp patterns, list the
- * secret as grantable; a grant is idempotent, one secret per host, and a
- * destroyed imp or a rebound or removed secret takes its grants with it. A
- * start or an attach that requires the broker is refused with
- * `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.
- */
 // A hold on the commands whose argv holds its text: entered resolves with
 // the argv of the first command it holds, and stop lets every command it
-// holds run.
-interface FixtureCommandHold {
+// holds run. Disposing the hold stops it, so a test that holds it with
+// `using` after its daemon lets the daemon stop even when the test fails.
+interface StubCommandHold {
   readonly entered: Promise<string>;
   readonly stop: () => void;
+  readonly [Symbol.dispose]: () => void;
 }
 
-export class FixtureImpPort implements ImpPort {
+/**
+ * The impd stand-in the factory below creates, one per call.
+ */
+class StubImpPort implements ImpPort {
   // Every port call, in order, as `<call> <imp> [<detail>]`.
   readonly calls: string[] = [];
 
   // 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,
@@ -150,6 +139,11 @@ export class FixtureImpPort implements ImpPort {
   // The lease acquisitions wait for this hold to end, while one is held.
   private leaseHold: PromiseWithResolvers<void> | null = null;
 
+  // How many lease acquisitions and releases wait on their holds.
+  private heldLeases = 0;
+
+  private heldReleases = 0;
+
   // The directory a relative or missing working directory resolves
   // against inside every imp, as a guest's home does; null for the test's
   // own working directory.
@@ -163,6 +157,9 @@ export class FixtureImpPort 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;
 
@@ -183,9 +180,12 @@ export class FixtureImpPort implements ImpPort {
   // what the daemon writes still reaches the guest.
   private droppingGuestBytes = false;
 
+  // How many guest bytes the drop has thrown away.
+  private droppedGuestBytes = 0;
+
   private readonly principal: string;
 
-  private readonly imps = new Map<string, FixtureImp>();
+  private readonly imps = new Map<string, StubImp>();
 
   private readonly forwards = new Set<{ stop: () => void; stopRelays: () => void }>();
 
@@ -301,6 +301,7 @@ export class FixtureImpPort 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(
@@ -308,7 +309,7 @@ export class FixtureImpPort implements ImpPort {
       );
     }
 
-    const imp: FixtureImp = {
+    const imp: StubImp = {
       id: randomUUID(),
       name: spec.name,
       state: 'stopped',
@@ -335,8 +336,12 @@ export class FixtureImpPort implements ImpPort {
   }
 
   private async waitForLease(name: string, label: string, ttlSeconds: number): Promise<ImpLease> {
+    this.heldLeases += 1;
+
     await this.leaseHold?.promise;
 
+    this.heldLeases -= 1;
+
     return this.applyLease(name, label, ttlSeconds);
   }
 
@@ -401,8 +406,12 @@ export class FixtureImpPort implements ImpPort {
   }
 
   private async waitForRelease(name: string, label: string): Promise<boolean> {
+    this.heldReleases += 1;
+
     await this.releaseHold?.promise;
 
+    this.heldReleases -= 1;
+
     return this.applyRelease(name, label);
   }
 
@@ -486,7 +495,7 @@ export class FixtureImpPort implements ImpPort {
 
     const outcome = Promise.withResolvers<ImpSessionOutcome>();
 
-    const connection: FixtureConnection = {
+    const connection: StubConnection = {
       handlers,
       sent: 0,
       finished: false,
@@ -590,7 +599,11 @@ export class FixtureImpPort 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)) {
@@ -625,11 +638,11 @@ export class FixtureImpPort implements ImpPort {
   ): ImpReverseForward {
     this.calls.push(`reverse ${name} ${guestPath}`);
 
-    const server = Bun.listen<FixtureRelay>({
+    const server = Bun.listen<StubRelay>({
       unix: guestPath,
       socket: {
         open: (socket) => {
-          const relay: FixtureRelay = {
+          const relay: StubRelay = {
             dataListeners: [],
             closeListeners: [],
             unsent: new Uint8Array(0),
@@ -675,6 +688,8 @@ export class FixtureImpPort implements ImpPort {
         },
         data: (socket, buf) => {
           if (this.droppingGuestBytes) {
+            this.droppedGuestBytes += buf.length;
+
             return;
           }
 
@@ -884,6 +899,11 @@ export class FixtureImpPort implements ImpPort {
     this.droppingGuestBytes = false;
   }
 
+  // How many bytes guests wrote that the drop threw away.
+  countDroppedGuestBytes(): number {
+    return this.droppedGuestBytes;
+  }
+
   /**
    * Holds every session answer back, as a slow network does, until the
    * hold stops.
@@ -892,6 +912,11 @@ export class FixtureImpPort implements ImpPort {
     this.held ??= [];
   }
 
+  // How many session answers wait for the answer hold to stop.
+  countHeldAnswers(): number {
+    return this.held?.length ?? 0;
+  }
+
   /**
    * Sends every held answer, in order, and answers at once again.
    */
@@ -970,6 +995,11 @@ export class FixtureImpPort implements ImpPort {
     this.leaseHold ??= Promise.withResolvers<void>();
   }
 
+  // How many lease acquisitions wait for the lease hold to stop.
+  countHeldLeases(): number {
+    return this.heldLeases;
+  }
+
   /**
    * Lets every held lease acquisition go through, and the next at once.
    */
@@ -985,6 +1015,11 @@ export class FixtureImpPort implements ImpPort {
     this.releaseHold ??= Promise.withResolvers<void>();
   }
 
+  // How many lease releases wait for the release hold to stop.
+  countHeldReleases(): number {
+    return this.heldReleases;
+  }
+
   /**
    * Lets every held lease release go through, and the next at once.
    */
@@ -1007,7 +1042,7 @@ export class FixtureImpPort implements ImpPort {
    * stops. Throws while another hold is active, so no hold replaces one a
    * command still waits on.
    */
-  startCommandHold(match: string): FixtureCommandHold {
+  startCommandHold(match: string): StubCommandHold {
     if (this.commandHold !== null) {
       throw new Error(`a hold on ${this.commandHold.match} is still active`);
     }
@@ -1020,16 +1055,20 @@ export class FixtureImpPort implements ImpPort {
 
     this.commandHold = hold;
 
-    return {
-      entered: hold.entered.promise,
-      stop: () => {
-        if (this.commandHold === hold) {
-          this.commandHold = null;
-        }
+    const stop = () => {
+      if (this.commandHold === hold) {
+        this.commandHold = null;
+      }
 
-        hold.done.resolve();
-      },
+      hold.done.resolve();
     };
+
+    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.
@@ -1083,7 +1122,7 @@ export class FixtureImpPort implements ImpPort {
     return this.imps.get(name)?.state ?? null;
   }
 
-  // The names of the imps the fixture holds.
+  // The names of the imps the stub holds.
   collectImpNames(): string[] {
     return [...this.imps.keys()];
   }
@@ -1104,6 +1143,15 @@ export class FixtureImpPort implements ImpPort {
     return proc.generation;
   }
 
+  /**
+   * The exit a session's process left that no connection has received, or
+   * null while the process runs, once an attach delivered the exit, and for
+   * a session the imp does not hold.
+   */
+  findUndeliveredExit(name: string, session: string): { readonly code: number | null } | null {
+    return this.imps.get(name)?.sessions.get(session)?.exited ?? null;
+  }
+
   // The offset after the last byte a session's running generation wrote.
   getEnd(name: string, session: string): number {
     const proc = this.getImp(name).sessions.get(session);
@@ -1174,7 +1222,7 @@ export class FixtureImpPort implements ImpPort {
     }
   }
 
-  private getImp(name: string): FixtureImp {
+  private getImp(name: string): StubImp {
     const imp = this.imps.get(name);
 
     if (imp === undefined) {
@@ -1184,7 +1232,7 @@ export class FixtureImpPort implements ImpPort {
     return imp;
   }
 
-  private buildView(imp: FixtureImp): ImpView {
+  private buildView(imp: StubImp): ImpView {
     const live = [...imp.leases.values()].filter((lease) => lease.until > Date.now());
     const own = live.filter((lease) => lease.principal === this.principal);
     const others = live.filter((lease) => lease.principal !== this.principal);
@@ -1200,7 +1248,7 @@ export class FixtureImpPort implements ImpPort {
 
   // A sleeping imp wakes from memory with every process as it was; a
   // stopped one boots cold.
-  private updateAwake(imp: FixtureImp): void {
+  private updateAwake(imp: StubImp): void {
     if (imp.state === 'sleeping') {
       imp.state = 'running';
 
@@ -1212,7 +1260,7 @@ export class FixtureImpPort implements ImpPort {
     }
   }
 
-  private updateAsleep(imp: FixtureImp): void {
+  private updateAsleep(imp: StubImp): void {
     if (imp.state !== 'running') {
       return;
     }
@@ -1225,7 +1273,7 @@ export class FixtureImpPort implements ImpPort {
     }
   }
 
-  private bootCold(imp: FixtureImp, cause: ColdBootCause): void {
+  private bootCold(imp: StubImp, cause: ColdBootCause): void {
     for (const proc of imp.sessions.values()) {
       proc.connection?.finish({ kind: 'detached', reason: 'lost', offset: proc.end });
       proc.ended = true;
@@ -1246,7 +1294,7 @@ export class FixtureImpPort implements ImpPort {
     ].slice(0, 4);
   }
 
-  private answerSession(request: ImpSessionRequest, connection: FixtureConnection): void {
+  private answerSession(request: ImpSessionRequest, connection: StubConnection): void {
     if (connection.finished) {
       return;
     }
@@ -1353,9 +1401,9 @@ export class FixtureImpPort implements ImpPort {
   // start sets, or a running process that started without the broker
   // required, fails the requirement as impd's would.
   private findBrokerProblem(
-    imp: FixtureImp,
+    imp: StubImp,
     request: ImpSessionRequest,
-    running: FixtureProcess | undefined,
+    running: StubProcess | undefined,
   ): string | null {
     if (request.require?.includes('broker') !== true) {
       return null;
@@ -1393,7 +1441,7 @@ export class FixtureImpPort implements ImpPort {
     return posix.resolve(this.homeDir, cwd ?? '.');
   }
 
-  private startProcess(imp: FixtureImp, request: ImpSessionRequest): FixtureProcess | null {
+  private startProcess(imp: StubImp, request: ImpSessionRequest): StubProcess | null {
     if (request.kind !== 'start') {
       return null;
     }
@@ -1406,7 +1454,7 @@ export class FixtureImpPort implements ImpPort {
       env: { ...request.env },
     });
 
-    const proc: FixtureProcess = {
+    const proc: StubProcess = {
       pty,
       generation: randomBytes(16).toString('hex'),
       ring: new Uint8Array(0),
@@ -1465,10 +1513,10 @@ export class FixtureImpPort implements ImpPort {
   }
 
   private attachProcess(
-    imp: FixtureImp,
-    proc: FixtureProcess,
+    imp: StubImp,
+    proc: StubProcess,
     request: ImpSessionRequest,
-    connection: FixtureConnection,
+    connection: StubConnection,
     created: boolean,
   ): void {
     const bufferStart = proc.end - proc.ring.length;
@@ -1572,27 +1620,60 @@ export class FixtureImpPort implements ImpPort {
   }
 }
 
-interface FixtureLease {
+/**
+ * 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
+ * and its generation. Every session keeps an exact 262144-byte ring with
+ * offsets, a fresh attach skips to the next line and sends a mode prelude,
+ * and impd's refusals carry its codes and data: `LEASED`, `LEASE_NOT_HELD`,
+ * `NO_SESSION`, `INVALID_STATE`, `INVALID_RESUME`, `NOT_FOUND`, `CONFLICT`,
+ * and `FORBIDDEN`. Leases belong to principals; the port acts as
+ * `principal`, and a test adds other owners' leases, cold boots, and
+ * dropped sockets through the controls. Grants follow impd 0.27: the
+ * caller's identity must reach the imp and, under imp patterns, list the
+ * secret as grantable; a grant is idempotent, one secret per host, and a
+ * destroyed imp or a rebound or removed secret takes its grants with it. A
+ * start or an attach that requires the broker is refused with
+ * `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. 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 createStubImpPort(principal = 'token:atc'): StubImpPort {
+  const port = new StubImpPort(principal);
+
+  registerTestCleanup(() => {
+    port[Symbol.dispose]();
+  });
+
+  return port;
+}
+
+interface StubLease {
   readonly principal: string;
   readonly label: string;
   readonly until: number;
 }
 
-interface FixtureImp {
+interface StubImp {
   readonly id: string;
   readonly name: string;
   state: ImpState;
   bootId: string;
   coldBoots: ColdBoot[];
-  readonly leases: Map<string, FixtureLease>;
-  readonly sessions: Map<string, FixtureProcess>;
+  readonly leases: Map<string, StubLease>;
+  readonly sessions: Map<string, StubProcess>;
   readonly previous: Map<string, PreviousGeneration>;
 
   // The secrets granted to the imp.
   readonly grants: Set<string>;
 }
 
-interface FixtureProcess {
+interface StubProcess {
   readonly pty: IPty;
   readonly generation: string;
   ring: Uint8Array;
@@ -1601,22 +1682,22 @@ interface FixtureProcess {
 
   // Ended by a cold boot: its exit is never delivered.
   ended: boolean;
-  connection: FixtureConnection | null;
+  connection: StubConnection | null;
 
   // Whether its start required the broker, which an attach that requires
   // it needs.
   readonly requireBroker: boolean;
 }
 
-interface FixtureConnection {
+interface StubConnection {
   readonly handlers: ImpSessionHandlers;
   sent: number;
   finished: boolean;
-  process: FixtureProcess | null;
+  process: StubProcess | null;
   readonly finish: (outcome: ImpSessionOutcome) => void;
 }
 
-interface FixtureRelay {
+interface StubRelay {
   // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
   readonly dataListeners: ((data: Uint8Array) => void)[];
   readonly closeListeners: (() => void)[];
@@ -1647,7 +1728,7 @@ function mergeTail(ring: Uint8Array, data: Uint8Array, limit: number): Uint8Arra
 
 // Calls a connection's handler as the imp client does: a handler that
 // throws ends the connection with a local error and closes it.
-function tryEmit(connection: FixtureConnection, emit: () => void): boolean {
+function tryEmit(connection: StubConnection, emit: () => void): boolean {
   try {
     emit();
 
@@ -1662,7 +1743,7 @@ function tryEmit(connection: FixtureConnection, emit: () => void): boolean {
   }
 }
 
-function findSessionName(imp: FixtureImp, proc: FixtureProcess): string {
+function findSessionName(imp: StubImp, proc: StubProcess): string {
   for (const [name, held] of imp.sessions) {
     if (held === proc) {
       return name;

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/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`,
+  );
+}

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

@@ -0,0 +1,56 @@
+import { join } from 'node:path';
+import { createStubBin } from './create-stub-bin';
+
+interface StubSharedServerCodexConfig {
+  // 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 a Codex CLI that shares one background server
+ * between its terminals, as `fake-codex` under the directory, and returns
+ * its path. Without `--no-daemon`, the first start records its own
+ * `ATC_SESSION_ID` and `ATC_SOCKET` in `codex-shared-server.env` under the
+ * directory, as the server it starts keeps its environment, and every start
+ * runs its hooks with the recorded pair, as Codex runs hooks inside that
+ * server. With `--no-daemon`, a start runs its hooks with its own pair. The
+ * stub prints its arguments, reports a `SessionStart` for its thread, which
+ * is `fake-thread-<its own ATC_SESSION_ID>` or the id after `resume`, then
+ * a `Stop` whose last message is `done <thread>`, then runs the composer.
+ */
+export function createStubSharedServerCodex(
+  dir: string,
+  config: StubSharedServerCodexConfig,
+): string {
+  const report = `${config.atc.map((part) => `"${part}"`).join(' ')} hook-report --agent codex`;
+  const server = join(dir, 'codex-shared-server.env');
+
+  return createStubBin(
+    dir,
+    'fake-codex',
+    `#!/usr/bin/env bash
+echo "FAKE_CODEX_UP args: $*"
+thread="fake-thread-$ATC_SESSION_ID"
+source=startup
+prev=''
+for arg in "$@"; do
+  if [ "$prev" = resume ]; then thread="$arg"; source=resume; fi
+  prev="$arg"
+done
+case " $* " in
+  *' --no-daemon '*) ;;
+  *)
+    (set -o noclobber; printf 'ATC_SESSION_ID=%q\\nATC_SOCKET=%q\\n' "$ATC_SESSION_ID" "$ATC_SOCKET" > '${server}') 2>/dev/null
+    . '${server}'
+    ;;
+esac
+printf '{"hook_event_name":"SessionStart","session_id":"%s","source":"%s"}' "$thread" "$source" | ${report}
+printf '{"hook_event_name":"Stop","session_id":"%s","last_assistant_message":"done %s"}' "$thread" "$thread" | ${report}
+exec "${process.execPath}" "${config.composer}"
+`,
+  );
+}

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

@@ -1,9 +1,10 @@
 import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { registerTestCleanup } from './register-test-cleanup';
 
-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,17 +28,24 @@ 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
  * `atcCommand daemon` in the background. `systemd-run` runs the command after
  * `--` in the background with only the `--setenv` variables, as a transient
  * unit sees them, and appends its output to the `StandardOutput=append:`
- * file. Every call is logged.
+ * file. Every call is logged. The stand-ins' 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 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 remove = registerTestCleanup(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
   const binDir = join(root, 'bin');
   const procRoot = join(root, 'proc');
   const atcLine = atcCommand.map((part) => `"${part}"`).join(' ');
@@ -118,8 +126,6 @@ exit 0
         `0::/user.slice/user-${process.getuid?.() ?? 0}.slice/user@${process.getuid?.() ?? 0}.service/app.slice/${unit}\n`,
       );
     },
-    [Symbol.dispose]: () => {
-      rmSync(root, { recursive: true, force: true });
-    },
+    [Symbol.dispose]: remove,
   };
 }

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`);

package/src/test-utils/get-only-effect-ref.ts

@@ -0,0 +1,21 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * Returns the effect ref of the one idempotency claim a state database
+ * holds, and throws when it holds none or several, so a test that expects
+ * one claim never reads another's.
+ */
+export function getOnlyEffectRef(db: Database): string {
+  const refs = db
+    .query<{ effect_ref: string }, []>('SELECT effect_ref FROM idempotency')
+    .all()
+    .map((row) => row.effect_ref);
+
+  const [ref] = refs;
+
+  if (refs.length !== 1 || ref === undefined) {
+    throw new Error(`expected one idempotency claim, found ${JSON.stringify(refs)}`);
+  }
+
+  return ref;
+}