@zgeoff/atc 3.3.0 → 3.4.0

package/src/test-utils/start-tui-harness.ts

@@ -0,0 +1,284 @@
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'bun-pty';
+import type { IDisposable, IPty } from 'bun-pty';
+import { buildStubTUIClaude } from './build-stub-tui-claude';
+import { buildStubTUIGrok } from './build-stub-tui-grok';
+import { createStubBin } from './create-stub-bin';
+import { mergeDeep } from './merge-deep';
+import { setupTempDir } from './setup-temp-dir';
+import { waitFor } from './wait-for';
+
+/**
+ * One home with the real client running in it under a pseudo-terminal,
+ * and the calls that drive and read it.
+ */
+export type TUIHarness = ReturnType<typeof startTUIHarness>;
+
+const cliPath = join(import.meta.dir, '..', 'cli.ts');
+
+interface TUIHarnessOptions {
+  // How long a wait gives the client to draw its first byte; 9 seconds
+  // unless set.
+  readonly bootMs?: number;
+}
+
+/**
+ * A fresh home for one run of the real `atc` client in a pseudo-terminal,
+ * holding stand-in `claude` and `grok` binaries, which take scenario files
+ * dropped into the home, and a config that points at them. `boot` starts
+ * the client in the home, which starts its own daemon there; a later `boot`
+ * starts a new client on the same home and stops capturing the old one.
+ * `read` returns every byte the client drew since the last `reset`, and
+ * `waitFor` polls that capture for a needle. The client appends what it
+ * decides without drawing to a log: `markClientLog` returns a cursor into
+ * it, and `waitForClientLog` polls for a line written after that cursor.
+ * `writeConfig` writes the home's config: the stand-in binaries and the git
+ * transports the fixture repositories need, with the fields given laid over
+ * them. `env` is the environment the client runs with, so a daemon started
+ * with it serves the client. A wait made before the client draws anything
+ * gets `bootMs` for that first byte. Disposal stops the client and the daemon in
+ * the home and removes it; hold the result with `await using`.
+ */
+export function startTUIHarness(options: TUIHarnessOptions = {}) {
+  using setup = new DisposableStack();
+
+  // The client boots with this home as its cwd and lists it first in the
+  // picker, so the path is resolved the way the client reports it.
+  const tmp = setup.use(setupTempDir('atc-tui-'));
+  const home = realpathSync(tmp.dir);
+  const configPath = join(home, '.config', 'atc', 'config.json');
+  const clientLogPath = join(home, 'client.log');
+  const fakeClaude = createStubBin(home, 'fake-claude', buildStubTUIClaude());
+  const fakeGrok = createStubBin(home, 'fake-grok', buildStubTUIGrok());
+
+  const bootConfig: Readonly<Record<string, unknown>> = {
+    claudeBin: fakeClaude,
+    claudeArgs: [],
+    grokBin: fakeGrok,
+    grokArgs: [],
+
+    // No codex binary is written to the home, so the agent picker sees
+    // Codex as uninstalled whatever the host machine has.
+    codexBin: join(home, 'fake-codex'),
+    codexArgs: [],
+    gateways: [],
+
+    // The fixture repositories are local paths and loopback HTTP, which the
+    // default transports refuse.
+    workspaces: { gitTransports: ['https', 'ssh', 'http', 'file'] },
+  };
+
+  const writeConfig = (fields: Readonly<Record<string, unknown>> = {}) => {
+    mkdirSync(join(home, '.config', 'atc'), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(mergeDeep(bootConfig, fields)));
+  };
+
+  writeConfig();
+
+  // A test that drops an executable into the home's bin directory puts it
+  // on the PATH of the client and of the daemons it starts.
+  const env = {
+    ...process.env,
+    HOME: home,
+    XDG_RUNTIME_DIR: home,
+    PATH: `${join(home, 'bin')}:/usr/sbin:/usr/bin:/bin`,
+    ATC_CLIENT_LOG: clientLogPath,
+  };
+
+  let pty: IPty | null = null;
+  let capture: IDisposable | null = null;
+  let exited: Promise<number> | null = null;
+  let out = '';
+
+  // When the latest client boot wrote its first byte. The client draws
+  // nothing until its daemon handshake completes, so that byte is the
+  // readiness signal: waits before it get the boot budget, waits after it
+  // the interaction budget.
+  let firstOutputAt: number | null = null;
+
+  const owned = new AsyncDisposableStack();
+
+  owned.use(setup.move());
+  owned.defer(() => stopClientAndDaemon(home, pty, firstOutputAt === null));
+
+  return {
+    home,
+    configPath,
+    env,
+    writeConfig,
+
+    boot(): IPty {
+      capture?.dispose();
+
+      const booted = spawn(process.execPath, [cliPath], {
+        name: 'xterm-256color',
+        cols: 110,
+        rows: 30,
+
+        // The picker lists the client's own directory first, so a spawn
+        // that takes the first entry lands in the home.
+        cwd: home,
+        env,
+      });
+
+      const exit = Promise.withResolvers<number>();
+
+      booted.onExit((event) => {
+        exit.resolve(event.exitCode);
+      });
+
+      firstOutputAt = null;
+      pty = booted;
+      exited = exit.promise;
+
+      capture = booted.onData((data) => {
+        firstOutputAt ??= Date.now();
+        out += data;
+      });
+
+      return booted;
+    },
+
+    write(data: string) {
+      if (pty === null) {
+        throw new Error('write before boot');
+      }
+
+      pty.write(data);
+    },
+
+    read(): string {
+      return out;
+    },
+
+    reset() {
+      out = '';
+    },
+
+    async waitFor(needle: string, ms = 4000): Promise<void> {
+      const start = Date.now();
+
+      // The client gives its daemon 8 seconds to answer before it draws an
+      // error, so the boot phase waits that long plus 1 second for the
+      // client's own cold start, which measures under 1.1 seconds on a
+      // runner loaded at four times its cores. Every wait after the first
+      // byte keeps its own deadline.
+      const bootMs = options.bootMs ?? 8000 + 1000;
+
+      const firstAt = await waitFor(
+        () => {
+          if (firstOutputAt === null) {
+            throw new Error(
+              `timed out waiting for ${JSON.stringify(needle)}; the client wrote nothing in ${bootMs}ms of boot`,
+            );
+          }
+
+          return firstOutputAt;
+        },
+        { timeoutMs: bootMs, intervalMs: 50 },
+      );
+
+      await waitFor(
+        () => {
+          if (!out.includes(needle)) {
+            throw new Error(
+              `timed out waiting for ${JSON.stringify(needle)}; tail: ${JSON.stringify(out.slice(-400))}`,
+            );
+          }
+        },
+        { timeoutMs: Math.max(0, Math.max(start, firstAt) + ms - Date.now()), intervalMs: 50 },
+      );
+    },
+
+    waitForExit(): Promise<number> {
+      if (exited === null) {
+        throw new Error('wait for exit before boot');
+      }
+
+      return exited;
+    },
+
+    markClientLog(): number {
+      return readClientLog(clientLogPath).length;
+    },
+
+    async waitForClientLog(line: string, mark: number, ms = 5000): Promise<void> {
+      await waitFor(
+        () => {
+          const written = readClientLog(clientLogPath).slice(mark);
+
+          if (!written.includes(line)) {
+            throw new Error(
+              `the client log never held ${JSON.stringify(line)} after line ${mark}; it holds ${JSON.stringify(written)} there`,
+            );
+          }
+        },
+        { timeoutMs: ms },
+      );
+    },
+
+    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+  };
+}
+
+// The client started a daemon inside the home; its pid file is how the
+// harness finds and stops it. The daemon writes that file once its modules
+// load, so a client killed before its first frame can leave a daemon that
+// has not written it yet.
+async function stopClientAndDaemon(home: string, pty: IPty | null, beforeFirstFrame: boolean) {
+  pty?.kill();
+
+  const pid = await waitFor(
+    () => {
+      const read = Number(readFileSync(join(home, 'atc-daemon.pid'), 'utf8'));
+
+      if (!Number.isInteger(read) || read <= 1) {
+        throw new Error(`the daemon pid file holds no pid: ${read}`);
+      }
+
+      return read;
+    },
+    { timeoutMs: pty !== null && beforeFirstFrame ? 5000 : 0, intervalMs: 50 },
+  ).catch(() => null);
+
+  if (pid === null) {
+    return;
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {}
+
+  // The next test's cold boot must not share the CPU with this daemon's
+  // shutdown, and the daemon must not outlive its home.
+  await waitFor(
+    () => {
+      if (isRunning(pid)) {
+        throw new Error(`daemon ${pid} still runs`);
+      }
+    },
+    { timeoutMs: 3000 },
+  ).catch(() => {});
+}
+
+function isRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The client log's lines, or none before the client writes the file.
+function readClientLog(path: string): string[] {
+  try {
+    return readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((line) => line !== '');
+  } catch {
+    return [];
+  }
+}

package/src/test-utils/subscribe-to-socket-lines.ts

@@ -1,21 +1,40 @@
+import { OutboundQueue } from '../protocol/outbound-queue';
 import { waitFor } from './wait-for';
 
 interface SocketLines {
+  // Every complete newline-terminated line the peer sent, in order.
   readonly lines: string[];
+
+  // Resolves once the connection has closed, from either end.
+  readonly closed: Promise<void>;
+
   readonly write: (data: string) => void;
   readonly waitForLine: (count?: number, timeoutMs?: number) => Promise<string[]>;
   readonly [Symbol.asyncDispose]: () => Promise<void>;
 }
 
+interface SocketLinesOptions {
+  // How many unsent bytes the connection holds before it refuses a write.
+  readonly queueBytes?: number;
+}
+
 /**
  * Connects to a unix socket and collects every complete newline-terminated
- * line it sends, buffering a partial line across reads. `waitForLine` polls
- * until the collected count reaches `count` and returns the lines, throwing
- * when `timeoutMs` passes first; disposal ends the connection.
+ * line it sends, buffering a partial line across reads. `write` sends the
+ * whole of what it is given, the rest going out as the socket drains,
+ * and throws instead when the unsent bytes already fill the queue. `waitForLine` polls until the collected count reaches
+ * `count` and returns the lines, throwing when `timeoutMs` passes first or
+ * the connection closes short of the count. Disposal ends the connection.
  */
-export async function subscribeToSocketLines(path: string): Promise<SocketLines> {
+export async function subscribeToSocketLines(
+  path: string,
+  options: SocketLinesOptions = {},
+): Promise<SocketLines> {
   const lines: string[] = [];
+  const closed = Promise.withResolvers<void>();
+  let isClosed = false;
   let buffer = '';
+  let queue: OutboundQueue | null = null;
 
   const socket = await Bun.connect({
     unix: path,
@@ -29,27 +48,55 @@ export async function subscribeToSocketLines(path: string): Promise<SocketLines>
 
         lines.push(...parts.filter((part) => part.trim() !== ''));
       },
-      close() {},
+      drain() {
+        queue?.drain();
+      },
+      close() {
+        isClosed = true;
+
+        closed.resolve();
+      },
       error() {},
     },
   });
 
+  // The default leaves room for the largest payload a test sends in one
+  // piece.
+  queue = new OutboundQueue(socket, options.queueBytes ?? 8 * 1024 * 1024);
+
+  const sending = queue;
+
+  const requireLines = (count: number) => {
+    if (lines.length < count) {
+      throw new Error(`timed out waiting for ${count} lines; got ${JSON.stringify(lines)}`);
+    }
+
+    return lines;
+  };
+
   return {
     lines,
+    closed: closed.promise,
     write(data: string) {
-      socket.write(data);
+      if (!sending.send(data)) {
+        throw new Error(
+          `the socket refused a ${data.length}-character write: ${sending.queuedBytes} bytes are still unsent`,
+        );
+      }
     },
-    waitForLine(count = 1, timeoutMs = 5000) {
-      return waitFor(
+    async waitForLine(count = 1, timeoutMs = 5000) {
+      // The poll ends early once the connection closes, since no more lines
+      // can arrive.
+      await waitFor(
         () => {
-          if (lines.length < count) {
-            throw new Error(`timed out waiting for ${count} lines; got ${JSON.stringify(lines)}`);
+          if (!isClosed) {
+            requireLines(count);
           }
-
-          return lines;
         },
         { timeoutMs },
       );
+
+      return requireLines(count);
     },
     [Symbol.asyncDispose]: () => {
       socket.end();

package/src/test-utils/try-send-request.ts

@@ -0,0 +1,29 @@
+import { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * Sends a request and returns its answer as plain data, `{ ok }` or, when
+ * the daemon refuses it, `{ error: { code, message, data } }`, with every
+ * occurrence of `id` replaced by `<id>`, so the answers to the same request
+ * for two ids compare whole: a refusal for a session a client may not see
+ * and one for a session that never existed must read alike. A failure that
+ * is not a daemon refusal rejects as it is.
+ */
+export async function trySendRequest(
+  send: () => Promise<Readonly<Record<string, unknown>>>,
+  id: string,
+): Promise<unknown> {
+  const answer = await send().then(
+    (ok) => ({ ok }),
+    (error: unknown) => ({ error: toRefusal(error) }),
+  );
+
+  return JSON.parse(JSON.stringify(answer).replaceAll(id, '<id>'));
+}
+
+function toRefusal(error: unknown): unknown {
+  if (!(error instanceof DaemonError)) {
+    throw error;
+  }
+
+  return { code: error.code, message: error.message, data: error.data ?? null };
+}

package/src/test-utils/wait-for-event.ts

@@ -0,0 +1,41 @@
+import { expect } from 'bun:test';
+import type { EventMsg } from '../protocol/protocol';
+import { waitFor } from './wait-for';
+
+/**
+ * Waits until the collected events hold one that matches the shape, as
+ * `toMatchObject` matches, and resolves with the first such event. Every
+ * event collected so far counts, so a wait finds an event that arrived
+ * before it began, and every event stays as it arrived. Throws once the
+ * deadline passes, five seconds unless the options set another, listing
+ * the shape and the events it saw.
+ */
+export function waitForEvent(
+  events: readonly EventMsg[],
+  shape: Readonly<Record<string, unknown>>,
+  options: Parameters<typeof waitFor>[1] = {},
+): Promise<EventMsg> {
+  return waitFor(() => {
+    const found = events.find((event) => isMatch(event, shape));
+
+    if (found === undefined) {
+      throw new Error(
+        `no event matches ${JSON.stringify(shape)}; got ${JSON.stringify(events.map((event) => event.ev))}`,
+      );
+    }
+
+    return found;
+  }, options);
+}
+
+// The match runs on a copy: Bun's toMatchObject writes each asymmetric
+// matcher it compares over the field it matched in the received object.
+function isMatch(event: EventMsg, shape: Readonly<Record<string, unknown>>): boolean {
+  try {
+    expect(structuredClone(event)).toMatchObject(shape);
+
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/test-utils/wait-for.ts

@@ -8,6 +8,16 @@ interface WaitForOptions {
    * Milliseconds before the wait gives up.
    */
   readonly timeoutMs?: number;
+
+  /**
+   * The clock the deadline is read from.
+   */
+  readonly now?: () => number;
+
+  /**
+   * Waits out the interval between retries.
+   */
+  readonly wait?: (ms: number) => Promise<void>;
 }
 
 /**
@@ -22,17 +32,19 @@ export async function waitFor<T>(
 ): Promise<T> {
   const intervalMs = options.intervalMs ?? 20;
   const timeoutMs = options.timeoutMs ?? 5000;
-  const deadline = Date.now() + timeoutMs;
+  const now = options.now ?? Date.now;
+  const wait = options.wait ?? Bun.sleep;
+  const deadline = now() + timeoutMs;
 
   for (;;) {
     try {
       return await attempt();
     } catch (error) {
-      if (Date.now() >= deadline) {
+      if (now() >= deadline) {
         throw error;
       }
     }
 
-    await Bun.sleep(intervalMs);
+    await wait(intervalMs);
   }
 }

package/src/verify-restored-fleet.ts

@@ -3,6 +3,8 @@ import type { RestartFailedRow } from './parse-restart-result';
 import type { StoredRow } from './read-stored-rows';
 import { readStoredRows } from './read-stored-rows';
 import { isRecord } from './shared/report';
+import { systemClock } from './shared/system-clock';
+import type { Clock } from './shared/system-clock';
 
 interface FleetVerdict {
   // The rows the daemon stored, exited ones included.
@@ -28,14 +30,18 @@ const UNSIZED_READ_MS = 30_000;
  * passes (`timeoutSeconds` when set, else the rows that are not exited times the restore boot cap, plus 30 s), and an exited row must be listed. A stored row that is not listed
  * failed to restore, and a listed row that is still without a live terminal
  * at the deadline failed to revive. The deadline counts from the call, and
- * every request to the daemon is held to it.
+ * every request to the daemon is held to it: the daemon must answer the first
+ * list before it, and when it overtakes a later list, the verdict comes from
+ * the last list the daemon answered. The deadline, the waits between lists,
+ * and every request's time limit run on `clock`, the wall clock unless given.
  */
 export async function verifyRestoredFleet(
   client: Pick<DaemonClient, 'sendRequest'>,
   timeoutSeconds: number | null,
   snapshot: readonly StoredRow[] | null,
+  clock: Clock = systemClock,
 ): Promise<FleetVerdict> {
-  const startedAt = Date.now();
+  const startedAt = clock.now();
 
   // Without a snapshot the rows come from the new daemon, and its count is
   // not known until they are read, so that read gets the fixed allowance.
@@ -44,19 +50,28 @@ export async function verifyRestoredFleet(
       ? await sendBounded(
           () => readStoredRows(client),
           startedAt + (timeoutSeconds === null ? UNSIZED_READ_MS : timeoutSeconds * 1000),
+          clock,
         )
       : null;
 
   const stored = snapshot ?? read ?? [];
   const deadline = startedAt + pickDeadlineMs(stored, timeoutSeconds);
 
-  const restored = await tryRestore(client, deadline);
-  let found = await sendBounded(() => collectFailedRows(client, stored, restored), deadline);
+  const restored = await tryRestore(client, deadline, clock);
+  let found = await sendBounded(() => collectFailedRows(client, stored, restored), deadline, clock);
 
-  while (found.pending && Date.now() < deadline) {
-    await Bun.sleep(250);
+  while (found.pending && clock.now() < deadline) {
+    await new Promise<void>((resolve) => {
+      clock.schedule(resolve, Math.min(250, deadline - clock.now()));
+    });
 
-    found = await sendBounded(() => collectFailedRows(client, stored, restored), deadline);
+    const polled = await tryCollectFailedRows(client, stored, restored, deadline, clock);
+
+    if (polled === null) {
+      break;
+    }
+
+    found = polled;
   }
 
   return { total: stored.length, failed: found.failed };
@@ -66,22 +81,22 @@ export async function verifyRestoredFleet(
  * Runs a request and rejects once the deadline passes, so a daemon that
  * stops answering cannot hold the restart, and its lock, open.
  */
-async function sendBounded<T>(send: () => Promise<T>, deadline: number): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
+async function sendBounded<T>(send: () => Promise<T>, deadline: number, clock: Clock): Promise<T> {
+  let stopTimer: (() => void) | undefined;
 
   const expired = new Promise<never>((_resolve, reject) => {
-    timer = setTimeout(
+    stopTimer = clock.schedule(
       () => {
         reject(new Error('the new daemon stopped answering before the restore deadline'));
       },
-      Math.max(0, deadline - Date.now()),
+      Math.max(0, deadline - clock.now()),
     );
   });
 
   try {
     return await Promise.race([send(), expired]);
   } finally {
-    clearTimeout(timer);
+    stopTimer?.();
   }
 }
 
@@ -99,9 +114,14 @@ function pickDeadlineMs(stored: readonly StoredRow[], timeoutSeconds: number | n
 async function tryRestore(
   client: Pick<DaemonClient, 'sendRequest'>,
   deadline: number,
+  clock: Clock,
 ): Promise<boolean> {
   try {
-    await sendBounded(() => client.sendRequest('fleet.restore', { cols: 80, rows: 24 }), deadline);
+    await sendBounded(
+      () => client.sendRequest('fleet.restore', { cols: 80, rows: 24 }),
+      deadline,
+      clock,
+    );
 
     return true;
   } catch {
@@ -109,6 +129,35 @@ async function tryRestore(
   }
 }
 
+/**
+ * Lists the rows again, or returns null when the deadline passes before the
+ * daemon answers, so the caller keeps the verdict of the last list it got.
+ */
+async function tryCollectFailedRows(
+  client: Pick<DaemonClient, 'sendRequest'>,
+  stored: readonly StoredRow[],
+  restored: boolean,
+  deadline: number,
+  clock: Clock,
+): Promise<FailedRows | null> {
+  let stopTimer: (() => void) | undefined;
+
+  const expired = new Promise<null>((resolve) => {
+    stopTimer = clock.schedule(
+      () => {
+        resolve(null);
+      },
+      Math.max(0, deadline - clock.now()),
+    );
+  });
+
+  try {
+    return await Promise.race([collectFailedRows(client, stored, restored), expired]);
+  } finally {
+    stopTimer?.();
+  }
+}
+
 async function collectFailedRows(
   client: Pick<DaemonClient, 'sendRequest'>,
   stored: readonly StoredRow[],

package/src/workspace/check-repository-access.ts

@@ -21,6 +21,9 @@ interface AccessRequest {
 
   // The transports the URL may use and git may fetch over.
   readonly transports: readonly string[];
+
+  // Called with the pid of the listing's git as it starts.
+  readonly onSpawn?: ((pid: number) => void) | undefined;
 }
 
 interface RepositoryAccess {
@@ -77,6 +80,7 @@ export async function checkRepositoryAccess(
       request.credential,
       request.transports,
       request.timeoutMs,
+      request.onSpawn,
     );
 
     if (!listing.ok) {

package/src/workspace/collect-remote-refs.ts

@@ -41,13 +41,15 @@ const REMOTE_TIMEOUT_MS = 20_000;
  * askpass helper for an env credential. git never prompts. A listing git
  * cannot read is refused as `clone_failed` with git's own message, and so
  * is one that takes longer than the time limit, 20 s unless given. git
- * fetches only over `transports`.
+ * fetches only over `transports`. `onSpawn` is called with the pid of the
+ * listing's git as it starts.
  */
 export async function collectRemoteRefs(
   url: string,
   credential: GitCredential | undefined,
   transports: readonly string[],
   timeoutMs: number = REMOTE_TIMEOUT_MS,
+  onSpawn?: (pid: number) => void,
 ): Promise<RemoteRefListing | RemoteRefRefusal> {
   const askpass = await createGitAskpass(credential);
 
@@ -72,7 +74,7 @@ export async function collectRemoteRefs(
         'refs/heads/*',
         'refs/tags/*',
       ],
-      { env: { ...askpass.env, ...sshEnv }, timeoutMs, transports },
+      { env: { ...askpass.env, ...sshEnv }, timeoutMs, transports, onSpawn },
     );
   } finally {
     await askpass[Symbol.asyncDispose]();