@zgeoff/atc 3.6.1 → 3.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.6.1",
+  "version": "3.6.2",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

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

@@ -12,6 +12,14 @@ interface StubExecutionProviderConfig {
   // Capabilities that differ from a local pseudo-terminal's.
   readonly capabilities?: Partial<ExecutionCapabilities>;
 
+  // Whether the daemon treats the host as another machine; false when left
+  // out.
+  readonly remote?: boolean;
+
+  // The error every command rejects with instead of running; left out,
+  // commands run on this machine.
+  readonly commandFailure?: Readonly<Error>;
+
   /**
    * Called with each harness spec before the harness starts; a throw from
    * it aborts the spawn.
@@ -42,9 +50,10 @@ interface StubExecutionProvider extends ExecutionProvider {
 /**
  * An execution provider for daemon tests that runs harnesses, transfers, and
  * commands on this machine as the local pseudo-terminal provider does, with
- * the capabilities the config changes on top of its own. It reports each
- * harness spec to the config before starting it. A host suspend or
- * destroy does nothing to the machine: it records the host in `suspended` or
+ * the capabilities the config changes on top of its own. The config can
+ * mark the host remote, and can make every command reject with an error
+ * instead of running. It reports each harness spec to the config before
+ * starting it. A host suspend or destroy does nothing to the machine: it records the host in `suspended` or
  * `destroyed` and resolves, or rejects with the error a failure setter gave.
  * The daemon calls them only when the capabilities declare `suspend` or
  * `destroy`.
@@ -55,6 +64,7 @@ export function buildStubExecutionProvider(
   const local = new LocalPTYProvider();
 
   const onSpawn = config.onSpawn ?? (() => {});
+  const commandFailure = config.commandFailure;
   const suspended: string[] = [];
   const destroyed: string[] = [];
 
@@ -67,7 +77,7 @@ export function buildStubExecutionProvider(
 
   return {
     kind: config.kind ?? 'stub',
-    remote: false,
+    remote: config.remote ?? false,
     capabilities: { ...local.capabilities, ...config.capabilities },
     prepareHost: local.prepareHost,
     spawnHarness: (spec) => {
@@ -76,7 +86,8 @@ export function buildStubExecutionProvider(
       return local.spawnHarness(spec);
     },
     transferArchive: local.transferArchive,
-    runCommand: local.runCommand,
+    runCommand:
+      commandFailure === undefined ? local.runCommand : () => Promise.reject(commandFailure),
     suspendHost: (host) => {
       const failure = failures.suspend;
 

package/src/test-utils/create-stub-imp-port.ts

@@ -1,6 +1,7 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 import { rmSync } from 'node:fs';
 import { posix } from 'node:path';
+import type { Subprocess } from 'bun';
 import { spawn } from 'bun-pty';
 import type { IPty } from 'bun-pty';
 import type {
@@ -52,16 +53,14 @@ import { registerTestCleanup } from './register-test-cleanup';
  * 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; `stop` does so sooner, and a second stop does nothing.
+ * a test; `stop` does so sooner, and a second stop does nothing. Leases
+ * expire, and cold boots are stamped, by `now`, the wall clock when absent.
  */
-export function createStubImpPort(principal = 'token:atc'): StubImpPort {
-  return new StubImpPort(principal);
-}
-
-interface StubLease {
-  readonly principal: string;
-  readonly label: string;
-  readonly until: number;
+export function createStubImpPort(
+  principal = 'token:atc',
+  now: () => number = Date.now,
+): StubImpPort {
+  return new StubImpPort(principal, now);
 }
 
 interface StubConnection {
@@ -88,6 +87,12 @@ interface StubProcess {
   readonly requireBroker: boolean;
 }
 
+interface StubLease {
+  readonly principal: string;
+  readonly label: string;
+  readonly until: number;
+}
+
 interface StubImp {
   readonly id: string;
   readonly name: string;
@@ -125,6 +130,9 @@ interface StubCommandHold {
   readonly stop: () => void;
 }
 
+// The exit code of a guest command killed by SIGKILL.
+const KILLED_CODE = 137;
+
 // impd keeps exactly this many bytes of each generation's output.
 const RING_BYTES = 262_144;
 
@@ -243,6 +251,12 @@ class StubImpPort implements ImpPort {
   // How many commands wait on a command hold.
   private heldCommands = 0;
 
+  // The guest commands running now, which a stop kills.
+  private readonly commands = new Set<Subprocess>();
+
+  // Set once the stand-in stops, so a command a hold released never runs.
+  private stopped = false;
+
   // Commands whose argv holds this text exit 1 without running, or null.
   private commandFailure: string | null = null;
 
@@ -268,12 +282,16 @@ class StubImpPort implements ImpPort {
 
   private readonly principal: string;
 
+  // The time in epoch milliseconds that leases expire against.
+  private readonly now: () => number;
+
   private readonly imps = new Map<string, StubImp>();
 
   private readonly forwards = new Set<{ stop: () => void; stopRelays: () => void }>();
 
-  constructor(principal = 'token:atc') {
+  constructor(principal: string, now: () => number) {
     this.principal = principal;
+    this.now = now;
   }
 
   readFeatures(): Promise<ImpFeatures> {
@@ -456,7 +474,7 @@ class StubImpPort implements ImpPort {
 
     this.updateAwake(imp);
 
-    const until = Date.now() + ttlSeconds * 1000;
+    const until = this.now() + ttlSeconds * 1000;
 
     imp.leases.set(`${this.principal}\u0000${label}`, { principal: this.principal, label, until });
 
@@ -470,11 +488,11 @@ class StubImpPort implements ImpPort {
     const key = `${this.principal}\u0000${label}`;
     const lease = imp?.leases.get(key);
 
-    if (imp === undefined || lease === undefined || lease.until <= Date.now()) {
+    if (imp === undefined || lease === undefined || lease.until <= this.now()) {
       return Promise.reject(new ImpPortError('LEASE_NOT_HELD', 'the caller holds no such lease'));
     }
 
-    const until = Date.now() + ttlSeconds * 1000;
+    const until = this.now() + ttlSeconds * 1000;
 
     imp.leases.set(key, { ...lease, until });
 
@@ -518,7 +536,7 @@ class StubImpPort implements ImpPort {
       return Promise.reject(buildNotFound(name));
     }
 
-    const live = [...imp.leases.values()].filter((lease) => lease.until > Date.now());
+    const live = [...imp.leases.values()].filter((lease) => lease.until > this.now());
 
     if (imp.state === 'running' && live.length > 0) {
       const own = live.filter((lease) => lease.principal === this.principal);
@@ -690,6 +708,12 @@ class StubImpPort implements ImpPort {
       this.heldCommands -= 1;
     }
 
+    // A command that gets past the hold after a stop, held or not, ends as a
+    // killed one does, so no process outlives the stop.
+    if (this.stopped) {
+      return { code: KILLED_CODE, stdout: new Uint8Array(0), stderr: new Uint8Array(0) };
+    }
+
     if (this.commandFailure !== null && line.includes(this.commandFailure)) {
       const encoder = new TextEncoder();
 
@@ -706,12 +730,16 @@ class StubImpPort implements ImpPort {
       stderr: 'pipe',
     });
 
+    this.commands.add(proc);
+
     const [stdout, stderr, code] = await Promise.all([
       new Response(proc.stdout).bytes(),
       new Response(proc.stderr).bytes(),
       proc.exited,
     ]);
 
+    this.commands.delete(proc);
+
     return { code, stdout, stderr };
   }
 
@@ -902,7 +930,7 @@ class StubImpPort implements ImpPort {
     imp.leases.set(`${principal}\u0000${label}`, {
       principal,
       label,
-      until: Date.now() + ttlSeconds * 1000,
+      until: this.now() + ttlSeconds * 1000,
     });
   }
 
@@ -1252,12 +1280,22 @@ class StubImpPort implements ImpPort {
     return proc.end;
   }
 
-  // Kills every process and stops every forward the stand-in holds. It runs
+  // Kills every process and stops every forward the stand-in holds, and
+  // resolves once every guest command it killed exits. A command a hold
+  // still holds then exits as a killed one does, without running. It runs
   // once the current test finishes; calling it sooner runs it then, and a
   // second call does nothing.
-  readonly stop: () => void = registerTestCleanup(() => {
+  readonly stop: () => Promise<void> = registerTestCleanup(async () => {
+    this.stopped = true;
+
     this.stopCommandHold();
 
+    const commands = [...this.commands];
+
+    for (const command of commands) {
+      command.kill('SIGKILL');
+    }
+
     for (const imp of this.imps.values()) {
       for (const proc of imp.sessions.values()) {
         tryKill(proc.pty, 'SIGCONT');
@@ -1270,6 +1308,8 @@ class StubImpPort implements ImpPort {
     }
 
     this.imps.clear();
+
+    await Promise.all(commands.map((command) => command.exited));
   });
 
   // impd's refusal of a grant or revoke: the scope and pattern checks run
@@ -1325,7 +1365,7 @@ class StubImpPort implements ImpPort {
   }
 
   private buildView(imp: StubImp): ImpView {
-    const live = [...imp.leases.values()].filter((lease) => lease.until > Date.now());
+    const live = [...imp.leases.values()].filter((lease) => lease.until > this.now());
     const own = live.filter((lease) => lease.principal === this.principal);
     const others = live.filter((lease) => lease.principal !== this.principal);
 
@@ -1381,7 +1421,7 @@ class StubImpPort implements ImpPort {
     imp.bootId = randomUUID();
 
     imp.coldBoots = [
-      { bootId: imp.bootId, cause, at: new Date().toISOString() },
+      { bootId: imp.bootId, cause, at: new Date(this.now()).toISOString() },
       ...imp.coldBoots,
     ].slice(0, 4);
   }
@@ -1725,6 +1765,25 @@ function buildLease(name: string, principal: string, label: string, until: numbe
   return { name, owner: { principal, display: principal, label }, until };
 }
 
+function tryKill(pty: IPty, signal: NodeJS.Signals): void {
+  try {
+    process.kill(pty.pid, signal);
+  } catch {}
+}
+
+// A gate that throws keeps the request from going out, as a closed one does.
+function tryPassGate(gate: () => boolean): boolean {
+  try {
+    return gate();
+  } catch {
+    return false;
+  }
+}
+
+function toSignal(name: string): NodeJS.Signals {
+  return name === 'SIGKILL' || name === 'SIGTERM' || name === 'SIGINT' ? name : 'SIGHUP';
+}
+
 // oxlint-disable-next-line prefer-readonly-parameter-types -- byte arrays have no readonly form
 function mergeTail(ring: Uint8Array, data: Uint8Array, limit: number): Uint8Array {
   const joined = new Uint8Array(ring.length + data.length);
@@ -1761,22 +1820,3 @@ function findSessionName(imp: StubImp, proc: StubProcess): string | undefined {
 
   return undefined;
 }
-
-function toSignal(name: string): NodeJS.Signals {
-  return name === 'SIGKILL' || name === 'SIGTERM' || name === 'SIGINT' ? name : 'SIGHUP';
-}
-
-function tryKill(pty: IPty, signal: NodeJS.Signals): void {
-  try {
-    process.kill(pty.pid, signal);
-  } catch {}
-}
-
-// A gate that throws keeps the request from going out, as a closed one does.
-function tryPassGate(gate: () => boolean): boolean {
-  try {
-    return gate();
-  } catch {
-    return false;
-  }
-}

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

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import type { Subprocess } from 'bun';
 import { DaemonClient } from '../client/daemon-client';
@@ -39,17 +39,30 @@ interface DaemonBoot {
  * sending no handshake, and fails at once with the daemon's stderr when the
  * daemon exits before it listens. `restart` stops the daemon with the given
  * signal, waits for it to exit, and starts another on the same home with the
- * same config. `readStderr` reads what the current boot printed. `stop`
- * 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. That stop runs once the current
- * test finishes, so it must run inside a test; calling `stop` sooner runs it
- * then, and a second stop does nothing.
+ * same config, and throws once the daemon is stopped. `readStderr` reads
+ * what the current boot printed, from a file in `stderrDir`, a directory
+ * under the home that no other daemon on the home writes. `stop` 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. That stop runs once the current test
+ * finishes, so it must run inside a test; calling `stop` sooner runs it
+ * then, and a second stop does nothing. `stderrDir` is removed once the
+ * current test finishes, after the stop, so a test can still read the
+ * stderr after an early stop.
  */
 export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
   const socketPath = join(config.home, 'atc-daemon.sock');
   const stateDir = join(config.home, '.local', 'state', 'atc');
 
+  // A directory of this helper's own under the home, so two daemons started
+  // on one home never write into one stderr file.
+  const stderrDir = mkdtempSync(join(config.home, 'daemon-stderr-'));
+
+  // Registered before the stop, so it runs after the daemon is gone.
+  registerTestCleanup(() => {
+    rmSync(stderrDir, { recursive: true, force: true });
+  });
+
   const clients = new Set<DaemonClient>();
 
   let boots = 0;
@@ -58,7 +71,7 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
   const boot = (): DaemonBoot => {
     boots++;
 
-    const stderrPath = join(config.home, `daemon-${boots}.stderr`);
+    const stderrPath = join(stderrDir, `boot-${boots}.stderr`);
 
     const proc = Bun.spawn([...config.command, 'daemon', ...(config.args ?? [])], {
       env: Object.fromEntries(
@@ -126,6 +139,11 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
     const watched = current.proc;
     let settled = false;
     const isSettled = () => settled;
+    const isWatchedExited = () => watched.exitCode !== null || watched.signalCode !== null;
+
+    // The poll's latest connect, so the wait after an exit can reuse one
+    // that was still in flight instead of dialing a second time.
+    let polled: Promise<DaemonClient> | null = null;
 
     // A daemon that has exited either refused to start or handed its socket
     // to a replacement, so one more connect tells the two apart.
@@ -136,6 +154,12 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
         return null;
       }
 
+      const inFlight = await polled?.catch(() => null);
+
+      if (inFlight !== undefined && inFlight !== null) {
+        return inFlight;
+      }
+
       try {
         return await openTrackedClient(isSettled);
       } catch {
@@ -145,16 +169,29 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
       }
     };
 
-    // Polls the socket while the daemon runs. Once the other wait settles or
-    // the daemon stops, each attempt resolves empty, which ends the
-    // polling.
+    // Polls the socket while the daemon runs. Once the daemon exits, it dials
+    // no more and leaves the connect to the wait after the exit. Once the
+    // other wait settles or the daemon stops, each attempt resolves empty,
+    // which ends the polling.
     const openWhenListening = () =>
-      waitFor(() => (settled || stopped ? null : openTrackedClient(isSettled)), {
-        timeoutMs: 15_000,
-        intervalMs: 50,
-      });
+      waitFor(
+        () => {
+          if (settled || stopped) {
+            return null;
+          }
+
+          if (isWatchedExited()) {
+            throw new Error('the daemon exited');
+          }
+
+          polled = openTrackedClient(isSettled);
 
-    const hasExited = watched.exitCode !== null || watched.signalCode !== null;
+          return polled;
+        },
+        { timeoutMs: 15_000, intervalMs: 50 },
+      );
+
+    const hasExited = isWatchedExited();
 
     try {
       const client = await (hasExited
@@ -176,12 +213,17 @@ export function startDaemonProcess(config: Readonly<DaemonProcessConfig>) {
     socketPath,
     reporterSocketPath: join(config.home, 'atc.sock'),
     stateDir,
+    stderrDir,
     get proc(): Subprocess {
       return current.proc;
     },
     readStderr,
     openClient,
     async restart(signal: NodeJS.Signals): Promise<void> {
+      if (stopped) {
+        throw new Error('a stopped daemon process cannot restart');
+      }
+
       current.proc.kill(signal);
 
       await current.proc.exited;