@zgeoff/atc 3.4.0 → 3.4.1

package/src/test-utils/setup-mcp-home.ts

@@ -5,6 +5,7 @@ import { stopDaemonProcess } from '../stop-daemon-process';
 import { buildStubMCPClaude } from './build-stub-mcp-claude';
 import { buildStubMCPGrok } from './build-stub-mcp-grok';
 import { createStubBin } from './create-stub-bin';
+import { registerTestCleanup } from './register-test-cleanup';
 import { setupTempDir } from './setup-temp-dir';
 import { waitFor } from './wait-for';
 
@@ -17,13 +18,33 @@ import { waitFor } from './wait-for';
  * home. Disposal stops the daemon, when one wrote its pid file here, and
  * waits for it to exit; then it kills the daemon's process group and every
  * group `stub-pids` records, such as a reporter a stopped session left
- * behind, waits until each group is empty, and removes the home. Hold the
- * result with `await using`.
+ * behind, waits until each group is empty, and removes the home. That
+ * disposal runs once the current test finishes, so it must run inside a
+ * test; disposing sooner runs it then, and a second disposal does nothing.
  */
 export function setupMCPHome() {
   const tmp = setupTempDir('atc-mcp-');
+
+  // Registered after the home, so it releases first: the daemon and the
+  // stand-ins stop before the home that records them is removed.
+  const stack = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => stack.disposeAsync());
+
+  stack.use(tmp);
+
   const home = tmp.dir;
 
+  stack.defer(async () => {
+    const pid = findPidFilePID(join(home, 'atc-daemon.pid'));
+
+    if (pid !== null) {
+      await stopDaemonProcess(pid);
+    }
+
+    await killProcessGroups([...(pid === null ? [] : [pid]), ...readStubPIDs(home)]);
+  });
+
   mkdirSync(join(home, '.config', 'atc'), { recursive: true });
   mkdirSync(join(home, '.local', 'state', 'atc'), { recursive: true });
 
@@ -39,17 +60,7 @@ export function setupMCPHome() {
     home,
     claudeBin,
     grokBin,
-    async [Symbol.asyncDispose]() {
-      const pid = findPidFilePID(join(home, 'atc-daemon.pid'));
-
-      if (pid !== null) {
-        await stopDaemonProcess(pid);
-      }
-
-      await killProcessGroups([...(pid === null ? [] : [pid]), ...readStubPIDs(home)]);
-
-      tmp[Symbol.dispose]();
-    },
+    [Symbol.asyncDispose]: dispose,
   };
 }
 

package/src/test-utils/setup-mcp-http.ts

@@ -7,6 +7,7 @@ import { openMCPAuth } from '../mcp/open-mcp-auth';
 import { ReconnectingCaller } from '../mcp/reconnecting-caller';
 import { startMCPHTTPServer } from '../mcp/start-mcp-http-server';
 import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+import { registerTestCleanup } from './register-test-cleanup';
 import { setupTempDir } from './setup-temp-dir';
 
 interface MCPHTTPSetupOptions {
@@ -24,13 +25,22 @@ interface MCPHTTPSetupOptions {
  * through it and returns the client id. `restartDaemon` stops the daemon and
  * starts a fresh one on the same socket and database, the way an operator
  * restarts it, with the principals it is given; `countDaemonClients` reads
- * how many connections the current daemon holds open. Hold the result with
- * `await using`.
+ * how many connections the current daemon holds open. Everything it starts
+ * stops, and the directory is removed, once the current test finishes, so it
+ * must run inside a test; disposal does so sooner, and a second disposal
+ * does nothing.
  */
 export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
-  await using stack = new AsyncDisposableStack();
+  const tmp = setupTempDir('atc-mcp-http-');
+
+  // Registered after the directory, so it releases first: each part stops
+  // before the one it depends on, and the directory goes last.
+  const stack = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => stack.disposeAsync());
+
+  stack.use(tmp);
 
-  const tmp = stack.use(setupTempDir('atc-mcp-http-'));
   const socketPath = join(tmp.dir, 'daemon.sock');
   const stateDir = join(tmp.dir, '.local', 'state', 'atc');
 
@@ -83,8 +93,6 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
 
   stack.defer(() => store.close());
 
-  const owned = stack.move();
-
   return {
     home: tmp.dir,
     url: server.url,
@@ -109,6 +117,6 @@ export async function setupMCPHTTP(options: MCPHTTPSetupOptions = {}) {
 
       daemon = await startTestDaemon(principals);
     },
-    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+    [Symbol.asyncDispose]: dispose,
   };
 }

package/src/test-utils/setup-temp-dir.ts

@@ -1,6 +1,7 @@
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface TempDir {
   readonly dir: string;
@@ -9,17 +10,17 @@ interface TempDir {
 }
 
 /**
- * Creates a disposable directory under the system temp root, named by the
- * prefix. Disposal removes the tree; hold the result with `using` in a
- * synchronous test and `await using` in an asynchronous one, so the
- * directory outlives exactly the test that made it.
+ * Creates a directory under the system temp root, named by the prefix, and
+ * registers its removal to run once the current test finishes, so it must
+ * run inside a test. Disposal removes the tree sooner; whichever comes
+ * second does nothing.
  */
 export function setupTempDir(prefix: string): TempDir {
   const dir = mkdtempSync(join(tmpdir(), prefix));
 
-  const remove = () => {
+  const remove = registerTestCleanup(() => {
     rmSync(dir, { recursive: true, force: true });
-  };
+  });
 
   return {
     dir,

package/src/test-utils/start-cut-proxy.ts

@@ -1,4 +1,5 @@
 import type { Socket } from 'bun';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface CutProxyOptions {
   // The address the proxy forwards to.
@@ -47,6 +48,9 @@ interface ProxyLink {
  * connection byte for byte, except that for the first `cuts` requests of
  * the method it loses the target's next answer after the request reached
  * the target: the request runs, and the client never sees its response.
+ * It stops, ending every link, once the current test finishes, so it must
+ * run inside a test; `stop` or disposal stops it sooner, and a second stop
+ * does nothing.
  */
 export function startCutProxy(options: CutProxyOptions): CutProxy {
   let cutsLeft = options.cuts;
@@ -121,14 +125,14 @@ export function startCutProxy(options: CutProxyOptions): CutProxy {
     },
   });
 
-  const stop = () => {
+  const stop = registerTestCleanup(() => {
     for (const client of links) {
       client.end();
       client.data.upstream?.end();
     }
 
     server.stop(true);
-  };
+  });
 
   return {
     port: server.port,

package/src/test-utils/start-daemon-process.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import type { Subprocess } from 'bun';
 import { DaemonClient } from '../client/daemon-client';
 import { findDaemonRecord } from '../shared/find-daemon-record';
+import { registerTestCleanup } from './register-test-cleanup';
 import { waitFor } from './wait-for';
 
 interface DaemonProcessConfig {
@@ -41,7 +42,9 @@ interface DaemonBoot {
  * same config. `readStderr` reads what the current boot printed. Disposal
  * closes every client it opened, kills the daemon and waits for it to exit,
  * then kills the daemon the home's state directory records, which a restart
- * the test asked atc for may have started; a second disposal does nothing.
+ * the test asked atc for may have started. That disposal runs once the
+ * current test finishes, so it must run inside a test; disposing sooner
+ * runs it then, and a second disposal does nothing.
  */
 export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
   const socketPath = join(config.home, 'atc-daemon.sock');
@@ -76,6 +79,26 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
 
   let current = boot();
 
+  const dispose = registerTestCleanup(async () => {
+    disposed = true;
+
+    for (const client of clients) {
+      client.stop();
+    }
+
+    current.proc.kill('SIGKILL');
+
+    await current.proc.exited;
+
+    const recorded = findDaemonRecord(join(stateDir, 'daemon.json'));
+
+    if (recorded !== null && recorded.pid !== current.proc.pid) {
+      try {
+        process.kill(recorded.pid, 'SIGKILL');
+      } catch {}
+    }
+  });
+
   const readStderr = () => {
     try {
       return readFileSync(current.stderrPath, 'utf8');
@@ -165,28 +188,6 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
 
       current = boot();
     },
-    async [Symbol.asyncDispose](): Promise<void> {
-      if (disposed) {
-        return;
-      }
-
-      disposed = true;
-
-      for (const client of clients) {
-        client.stop();
-      }
-
-      current.proc.kill('SIGKILL');
-
-      await current.proc.exited;
-
-      const recorded = findDaemonRecord(join(stateDir, 'daemon.json'));
-
-      if (recorded !== null && recorded.pid !== current.proc.pid) {
-        try {
-          process.kill(recorded.pid, 'SIGKILL');
-        } catch {}
-      }
-    },
+    [Symbol.asyncDispose]: dispose,
   };
 }

package/src/test-utils/start-git-http-server.ts

@@ -1,3 +1,5 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 interface GitHTTPServer {
   // The base URL a repository under the root is served at, ending in `/`.
   readonly url: string;
@@ -27,7 +29,9 @@ interface GitHTTPServerOptions {
  * authenticated request waits that long before it is served, which makes a
  * clone through it slow. An `onRequest` callback runs, and is awaited, while
  * each authenticated request is held, so it sees the client that sent the
- * request still running. Stop it with `stop`, or hold it with `await using`.
+ * request still running. It stops once the current test finishes, so it
+ * must run inside a test; `stop` or disposal stops it sooner, and a second
+ * stop does nothing.
  */
 export function startGitHTTPServer(
   root: string,
@@ -87,11 +91,13 @@ export function startGitHTTPServer(
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${server.port}/`,
     authorizations,
-    stop: () => server.stop(true),
-    [Symbol.asyncDispose]: () => server.stop(true),
+    stop,
+    [Symbol.asyncDispose]: stop,
   };
 }
 

package/src/test-utils/start-mcp-stdio.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
 
 const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
 
@@ -37,9 +38,10 @@ interface MCPToolResult {
  * an object. `spawnSession` spawns through `atc_session_spawn` and resolves
  * with the new session's id. A request still unanswered when the server's
  * stdout ends rejects. When `initialize` fails, the server is stopped
- * before the start rejects. Disposal stops the server and waits for it to exit,
- * and a second disposal waits for the same exit; the daemon stays up for
- * the home to stop.
+ * before the start rejects. The server stops once the current test
+ * finishes, so it must run inside a test; disposal stops it sooner and waits
+ * for it to exit, and a second disposal waits for the same exit. The daemon
+ * stays up for the home to stop.
  */
 export async function startMCPStdio(options: MCPStdioOptions) {
   const proc = Bun.spawn([...(options.command ?? [process.execPath, CLI_PATH, 'mcp'])], {
@@ -56,6 +58,13 @@ export async function startMCPStdio(options: MCPStdioOptions) {
     stderr: 'ignore',
   });
 
+  const stopServer = registerTestCleanup(async (): Promise<void> => {
+    void proc.stdin.end();
+    proc.kill();
+
+    await proc.exited;
+  });
+
   const pending = new Map<number, PromiseWithResolvers<Readonly<Record<string, unknown>>>>();
 
   void readResponses(proc.stdout, pending);
@@ -90,23 +99,6 @@ export async function startMCPStdio(options: MCPStdioOptions) {
     return toToolResult(response);
   };
 
-  let stopped = false;
-
-  const stopServer = async (): Promise<void> => {
-    if (!stopped) {
-      stopped = true;
-      void proc.stdin.end();
-      proc.kill();
-    }
-
-    await proc.exited;
-  };
-
-  // A failed initialize stops the server here, before the caller holds it.
-  await using stack = new AsyncDisposableStack();
-
-  stack.defer(stopServer);
-
   const server = {
     sendRequest,
     sendToolCall,
@@ -124,13 +116,16 @@ export async function startMCPStdio(options: MCPStdioOptions) {
     [Symbol.asyncDispose]: stopServer,
   };
 
+  // A failed initialize stops the server here, before the start rejects.
   await sendRequest('initialize', {
     protocolVersion: '2025-06-18',
     capabilities: {},
     clientInfo: { name: 'atc-test' },
-  });
+  }).catch(async (error: unknown) => {
+    await stopServer();
 
-  stack.move();
+    throw error;
+  });
 
   return server;
 }

package/src/test-utils/start-stub-answering-listener.ts

@@ -0,0 +1,65 @@
+import { createServer } from 'node:net';
+import type { Socket } from 'node:net';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubAnsweringListener {
+  // The server's side of each connection it accepted, in order.
+  readonly peers: readonly Socket[];
+
+  // The first read each connection sent, decoded, in arrival order.
+  readonly lines: readonly string[];
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * A stand-in for a daemon socket that answers a handshake: it listens on
+ * the unix socket path, records each connection it accepts and the first
+ * read each one sends, answers that read with the line `answer`, and
+ * leaves every later byte unread on the connection. Resolves once it
+ * listens. Once the current test finishes, it destroys every connection it
+ * accepted and closes, so it must run inside a test; disposal does so
+ * sooner and resolves once the server has closed, and a second stop does
+ * nothing.
+ */
+export async function startStubAnsweringListener(path: string): Promise<StubAnsweringListener> {
+  const peers: Socket[] = [];
+  const lines: string[] = [];
+
+  const server = createServer((peer) => {
+    peers.push(peer);
+
+    peer.once('data', (data) => {
+      peer.pause();
+      lines.push(data.toString());
+      peer.write('answer\n');
+    });
+  });
+
+  const listening = Promise.withResolvers<void>();
+
+  server.listen(path, () => {
+    listening.resolve();
+  });
+
+  await listening.promise;
+
+  const stop = registerTestCleanup(async () => {
+    for (const peer of peers) {
+      peer.destroy();
+    }
+
+    const closed = Promise.withResolvers<void>();
+
+    server.close(() => {
+      closed.resolve();
+    });
+
+    await closed.promise;
+  });
+
+  return {
+    peers,
+    lines,
+    [Symbol.asyncDispose]: stop,
+  };
+}

package/src/test-utils/start-stub-closing-listener.ts

@@ -0,0 +1,31 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubClosingListener {
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon that hangs up: it listens on the unix socket path
+ * and ends every connection as soon as it opens, reading nothing. It stops
+ * once the current test finishes, so it must run inside a test; disposal
+ * stops it sooner, and a second stop does nothing.
+ */
+export function startStubClosingListener(path: string): StubClosingListener {
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      open(socket) {
+        socket.end();
+      },
+      data() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    [Symbol.dispose]: stop,
+  };
+}

package/src/test-utils/start-stub-dropping-daemon.ts

@@ -6,6 +6,7 @@ import {
   decodeMessage,
   encodeMessage,
 } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface DroppingDaemonOptions {
   // The features the first handshake announces.
@@ -23,8 +24,9 @@ interface DroppingDaemonOptions {
  * and answers every later one with a session `s-1`. `keys` records the
  * idempotency key each of those requests carried, `undefined` for one that
  * carried none. `reads` counts the reads it has taken from every connection,
- * so a test can wait until one piece of a split write has arrived. Stop it
- * with `stop`, or hold it with `using`.
+ * so a test can wait until one piece of a split write has arrived. It stops
+ * once the current test finishes, so it must run inside a test; `stop` or
+ * disposal stops it sooner, and a second stop does nothing.
  */
 export function startStubDroppingDaemon(socketPath: string, options: DroppingDaemonOptions) {
   const keys: unknown[] = [];
@@ -88,16 +90,16 @@ export function startStubDroppingDaemon(socketPath: string, options: DroppingDae
     },
   });
 
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
   return {
     keys,
     get reads() {
       return reads;
     },
-    stop() {
-      server.stop(true);
-    },
-    [Symbol.dispose]() {
-      server.stop(true);
-    },
+    stop,
+    [Symbol.dispose]: stop,
   };
 }

package/src/test-utils/start-stub-impd-info.ts

@@ -1,10 +1,14 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 /**
  * An impd stand-in on a real HTTP port of the loopback address. Every call
  * is answered with HTTP 200 and the body impd's RPC sends for system info,
  * `{ json: info }`, so a client reads `info.features` as impd's features;
  * the test sets `info.features` to what impd should report. `paths` holds
- * the request path of each call, in order. Disposal stops the server; the
- * asynchronous form resolves once it has stopped.
+ * the request path of each call, in order. The server stops once the
+ * current test finishes, so it must run inside a test; disposal stops it
+ * sooner, the asynchronous form resolving once it has stopped, and a second
+ * stop does nothing.
  */
 export function startStubImpdInfo() {
   const paths: string[] = [];
@@ -20,13 +24,15 @@ export function startStubImpdInfo() {
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${String(server.port)}`,
     paths,
     info,
     [Symbol.dispose]: () => {
-      void server.stop(true);
+      void stop();
     },
-    [Symbol.asyncDispose]: () => server.stop(true),
+    [Symbol.asyncDispose]: stop,
   };
 }

package/src/test-utils/start-stub-impd.ts

@@ -1,5 +1,6 @@
 import type { ServerWebSocket } from 'bun';
 import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
 
 // What the stand-in does with an exec open: refuse it as a start whose
 // broker is not ready, start it and count its stdin bytes as `wc -c` does,
@@ -15,8 +16,10 @@ type StubExecReply = 'refuse' | 'count' | 'exit-early';
  * announce a guest connection on it. It records each exec open message in
  * `execOpens` and answers it as `exec.reply` says, a refusal as a start
  * whose broker is not ready by default. It takes no WebSocket message over
- * 2 MiB, as impd refuses one over its own limit. Disposal stops the server
- * and drops every open connection at once.
+ * 2 MiB, as impd refuses one over its own limit. The server stops, dropping
+ * every open connection at once, when the current test finishes, so it must
+ * run inside a test; disposal stops it sooner, and a second stop does
+ * nothing.
  */
 export function startStubImpd() {
   const authorizations: (string | null)[] = [];
@@ -123,6 +126,8 @@ export function startStubImpd() {
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${String(server.port)}`,
     authorizations,
@@ -132,7 +137,7 @@ export function startStubImpd() {
     execOpens,
     exec,
     [Symbol.dispose]: () => {
-      void server.stop(true);
+      void stop();
     },
   };
 }

package/src/test-utils/start-stub-legacy-daemon.ts

@@ -7,6 +7,7 @@ import {
   decodeMessage,
   encodeMessage,
 } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
 
 interface ReceivedRequest {
   readonly m: string;
@@ -28,6 +29,11 @@ interface StubLegacyDaemonOptions {
   readonly protocol?: number;
 
   readonly replies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+
+  // Who stops the daemon: the current test, once it finishes, or the
+  // caller alone, for a process that runs it outside any test; the test
+  // unless set.
+  readonly owner?: 'test' | 'caller';
 }
 
 /**
@@ -39,8 +45,10 @@ interface StubLegacyDaemonOptions {
  * `replies` with that method's reply, and refuses every other method with
  * `unknown_method`. Every request it receives is recorded in `requests`, and
  * `connections` counts the connections it accepted and those still open.
- * `port` holds the TCP port it bound, `null` on a unix socket. Stop
- * it with `stop`, or hold it with `using`.
+ * `port` holds the TCP port it bound, `null` on a unix socket. It stops
+ * once the current test finishes, so it must run inside a test, unless the
+ * options make the caller its owner; `stop` or disposal stops it sooner, and
+ * a second stop does nothing.
  */
 export function startStubLegacyDaemon(
   address: string | StubLegacyDaemonTCPAddress,
@@ -120,17 +128,14 @@ export function startStubLegacyDaemon(
   };
 
   const server = startListener(address, handlers);
+  const stop = options.owner === 'caller' ? server.stop : registerTestCleanup(server.stop);
 
   return {
     requests,
     connections,
     port: server.port,
-    stop() {
-      server.stop();
-    },
-    [Symbol.dispose]() {
-      server.stop();
-    },
+    stop,
+    [Symbol.dispose]: stop,
   };
 }
 

package/src/test-utils/start-stub-mcp-server.ts

@@ -1,3 +1,5 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
 interface StubMCPRequest {
   readonly method: string;
   readonly path: string;
@@ -19,7 +21,8 @@ interface StubMCPServer {
  * A stand-in for an MCP HTTP server on a loopback port: it answers every
  * request with the JSON body given, and records each request's method,
  * path, authorization and content-type headers, and JSON body. `url` holds
- * its origin. Disposal stops it; hold the result with `using`.
+ * its origin. It stops once the current test finishes, so it must run
+ * inside a test; disposal stops it sooner, and a second stop does nothing.
  */
 export function startStubMCPServer(answer: unknown): StubMCPServer {
   const requests: StubMCPRequest[] = [];
@@ -40,11 +43,13 @@ export function startStubMCPServer(answer: unknown): StubMCPServer {
     },
   });
 
+  const stop = registerTestCleanup(() => server.stop(true));
+
   return {
     url: `http://127.0.0.1:${String(server.port)}`,
     requests,
     [Symbol.dispose]: () => {
-      void server.stop(true);
+      void stop();
     },
   };
 }