@zgeoff/atc 3.3.0 → 3.4.0

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

@@ -0,0 +1,58 @@
+import type { ExecutionProvider, HarnessSpec, HostRequest } from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+/**
+ * An execution provider that runs on this machine as the local
+ * pseudo-terminal provider does, except that each host preparation holds
+ * until the test calls `release` with that host, so a test can act while a
+ * harness is still starting. `prepares` holds the host of each preparation
+ * in the order it began, and `harnesses` each harness spec in the order it
+ * started.
+ */
+export function buildStubHeldProvider() {
+  const local = new LocalPTYProvider();
+  const gates = new Map<string, PromiseWithResolvers<void>>();
+
+  const prepares: string[] = [];
+  const harnesses: HarnessSpec[] = [];
+
+  const getGate = (host: string): PromiseWithResolvers<void> => {
+    const gate = gates.get(host) ?? Promise.withResolvers<void>();
+
+    gates.set(host, gate);
+
+    return gate;
+  };
+
+  const provider: ExecutionProvider = {
+    kind: local.kind,
+    remote: local.remote,
+    capabilities: local.capabilities,
+    prepareHost: async (request: HostRequest) => {
+      prepares.push(request.host);
+
+      await getGate(request.host).promise;
+
+      await local.prepareHost();
+    },
+    spawnHarness: (spec) => {
+      harnesses.push(spec);
+
+      return local.spawnHarness(spec);
+    },
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: local.suspendHost,
+    destroyHost: local.destroyHost,
+    dispose: local.dispose,
+  };
+
+  return {
+    provider,
+    prepares,
+    harnesses,
+    release: (host: string) => {
+      getGate(host).resolve();
+    },
+  };
+}

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

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

package/src/test-utils/build-stub-host-hold.ts

@@ -0,0 +1,31 @@
+/**
+ * A host operation a test can hold open, for a host preparation or sleep
+ * that must stay in flight while the test changes something. Unarmed, the
+ * operation resolves at once, so the arrange steps before the hold pass
+ * through. Once armed, the next call resolves `entered` and every call
+ * waits until `release`; after the release, calls resolve at once again.
+ */
+export function buildStubHostHold() {
+  const entered = Promise.withResolvers<void>();
+  const released = Promise.withResolvers<void>();
+  let armed = false;
+
+  return {
+    hold: (): Promise<void> => {
+      if (!armed) {
+        return Promise.resolve();
+      }
+
+      entered.resolve();
+
+      return released.promise;
+    },
+    arm: () => {
+      armed = true;
+    },
+    entered: entered.promise,
+    release: () => {
+      released.resolve();
+    },
+  };
+}

package/src/test-utils/build-stub-host-provider.ts

@@ -0,0 +1,26 @@
+import type { ExecutionProvider } from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+/**
+ * An execution provider of kind `imp-like` whose hosts can be put to sleep
+ * and destroyed, as an imp's can, while every harness, archive transfer, and
+ * command runs on this machine through the local terminal provider.
+ * Readying, suspending, and destroying a host each do nothing and settle at
+ * once.
+ */
+export function buildStubHostProvider(): ExecutionProvider {
+  const local = new LocalPTYProvider();
+
+  return {
+    kind: 'imp-like',
+    remote: false,
+    capabilities: { ...local.capabilities, suspend: true, destroy: true },
+    prepareHost: () => Promise.resolve(),
+    spawnHarness: local.spawnHarness,
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: () => Promise.resolve(),
+    destroyHost: () => Promise.resolve(),
+    dispose: local.dispose,
+  };
+}

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

@@ -36,39 +36,24 @@ 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 builds, one per call.
+ */
+class StubImpPort implements ImpPort {
   // Every port call, in order, as `<call> <imp> [<detail>]`.
   readonly calls: string[] = [];
 
@@ -150,6 +135,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.
@@ -183,9 +173,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 }>();
 
@@ -308,7 +301,7 @@ export class FixtureImpPort implements ImpPort {
       );
     }
 
-    const imp: FixtureImp = {
+    const imp: StubImp = {
       id: randomUUID(),
       name: spec.name,
       state: 'stopped',
@@ -335,8 +328,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 +398,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 +487,7 @@ export class FixtureImpPort implements ImpPort {
 
     const outcome = Promise.withResolvers<ImpSessionOutcome>();
 
-    const connection: FixtureConnection = {
+    const connection: StubConnection = {
       handlers,
       sent: 0,
       finished: false,
@@ -625,11 +626,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 +676,8 @@ export class FixtureImpPort implements ImpPort {
         },
         data: (socket, buf) => {
           if (this.droppingGuestBytes) {
+            this.droppedGuestBytes += buf.length;
+
             return;
           }
 
@@ -884,6 +887,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 +900,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 +983,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 +1003,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 +1030,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 +1043,15 @@ 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 };
   }
 
   // Lets every command the active hold holds run, and the next at once.
@@ -1083,7 +1105,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 +1126,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 +1205,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 +1215,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 +1231,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 +1243,7 @@ export class FixtureImpPort implements ImpPort {
     }
   }
 
-  private updateAsleep(imp: FixtureImp): void {
+  private updateAsleep(imp: StubImp): void {
     if (imp.state !== 'running') {
       return;
     }
@@ -1225,7 +1256,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 +1277,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 +1384,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 +1424,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 +1437,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 +1496,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 +1603,52 @@ export class FixtureImpPort implements ImpPort {
   }
 }
 
-interface FixtureLease {
+/**
+ * Builds 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.
+ */
+export function buildStubImpPort(principal = 'token:atc'): StubImpPort {
+  return new StubImpPort(principal);
+}
+
+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 +1657,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 +1703,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 +1718,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/build-stub-log.ts

@@ -0,0 +1,15 @@
+/**
+ * A log sink that records each line it is given, in order, in place of the
+ * daemon's stderr log: `log` takes a line and `lines` holds every line taken
+ * so far.
+ */
+export function buildStubLog() {
+  const lines: string[] = [];
+
+  return {
+    lines,
+    log: (line: string): void => {
+      lines.push(line);
+    },
+  };
+}

package/src/test-utils/build-stub-mcp-claude.ts

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+/**
+ * The script of a stand-in `claude` for the stdio MCP suites. It appends its
+ * pid to `$HOME/stub-pids`, prints `FAKE_CLAUDE_UP args: ` and its
+ * arguments, and ends by echoing its input back until that input closes.
+ * Unless the file
+ * `$HOME/fake-claude-hold-start` exists, it first reports `SessionStart`
+ * through the real reporter with session id `fake-1` and transcript
+ * `$HOME/fake-transcript.jsonl`, and when `$HOME/fake-claude-note` exists it
+ * files that file's text as a report labelled `decision`.
+ */
+export function buildStubMCPClaude(): string {
+  const cli = `"${process.execPath}" "${CLI_PATH}"`;
+
+  return `#!/usr/bin/env bash
+echo $$ >> "$HOME/stub-pids"
+echo "FAKE_CLAUDE_UP args: $@"
+if [ -f "$HOME/fake-claude-hold-start" ]; then exec cat; fi
+printf '{"hook_event_name":"SessionStart","session_id":"fake-1","transcript_path":"'"$HOME"'/fake-transcript.jsonl"}' | ${cli} hook-report
+if [ -f "$HOME/fake-claude-note" ]; then ${cli} report note --label decision < "$HOME/fake-claude-note"; fi
+exec cat
+`;
+}

package/src/test-utils/build-stub-mcp-grok.ts

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+
+const CLI_PATH = join(import.meta.dir, '..', 'cli.ts');
+
+/**
+ * The script of a stand-in `grok` for the stdio MCP suites. It appends its
+ * pid to `$HOME/stub-pids`, prints `FAKE_GROK_UP args: ` and its arguments,
+ * reports `session_start` through the real reporter with session id
+ * `fake-grok-1` and its working directory, then echoes its input back until
+ * that input closes.
+ */
+export function buildStubMCPGrok(): string {
+  return `#!/usr/bin/env bash
+echo $$ >> "$HOME/stub-pids"
+echo "FAKE_GROK_UP args: $@"
+printf '{"hookEventName":"session_start","sessionId":"fake-grok-1","cwd":"%s"}' "$PWD" | "${process.execPath}" "${CLI_PATH}" hook-report
+exec cat
+`;
+}