@zgeoff/atc 3.6.0 → 3.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -85,5 +85,8 @@
     "smol-toml": "1.9.0",
     "tinypool": "2.1.2"
   },
-  "packageManager": "bun@1.3.10"
+  "packageManager": "bun@1.3.10",
+  "patchedDependencies": {
+    "knip@6.24.0": "patches/knip@6.24.0.patch"
+  }
 }

package/src/daemon/daemon.ts

@@ -163,6 +163,11 @@ export interface DaemonOptions {
   // Starts the eject settle timer; defaults to a real `setTimeout`.
   readonly scheduleEjectSettle?: SettleScheduler;
 
+  // How long a failed spawn's rollback waits for the killed process to
+  // exit, once after its kill and once more after a forced kill; 2 s when
+  // unset.
+  readonly failedSpawnExitWaitMs?: number;
+
   // A fleet-wide restore revives one session at a time, waiting for each to
   // report it has booted before starting the next so the machine is not
   // buried under a dozen simultaneous agent boots. This caps how long a
@@ -427,6 +432,10 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     mgr.log = opts.log;
   }
 
+  if (opts.failedSpawnExitWaitMs !== undefined) {
+    mgr.failedSpawnExitWaitMs = opts.failedSpawnExitWaitMs;
+  }
+
   const records = new PublishedRecords({
     store,
     daemonID: store.daemonID,

package/src/daemon/sessions.ts

@@ -290,8 +290,8 @@ interface SpawnReadied {
 // stored identity ran on.
 const LOCAL_TARGET_IDENTITY = buildTargetIdentity('local-pty', {});
 
-// How long a failed spawn's rollback waits for the killed process to exit,
-// once after its kill and once more after a forced kill.
+// How long a failed spawn's rollback waits for the killed process to exit
+// unless the manager is given another wait.
 const FAILED_SPAWN_EXIT_WAIT_MS = 2000;
 
 // How a harness takes its credential from impd's broker: the broker the
@@ -364,6 +364,11 @@ export class SessionManager {
   // sessions start without a record.
   records: PublishedRecords | null = null;
 
+  // How long a failed spawn's rollback waits for the killed process to
+  // exit, in milliseconds, once after its kill and once more after a forced
+  // kill.
+  failedSpawnExitWaitMs = FAILED_SPAWN_EXIT_WAIT_MS;
+
   // Whether any registered adapter has a screen detector, decided once at
   // construction since the registry never changes afterward. Lets a hot path
   // that only cares about this answer skip walking live sessions to find it.
@@ -2531,7 +2536,7 @@ export class SessionManager {
   // Waits for a killed harness to exit, ending it with a signal it cannot
   // ignore when the first wait runs out and its provider can send one.
   private async waitForKilledExit(pty: HarnessHandle): Promise<boolean> {
-    const exited = await pty.waitForExit(FAILED_SPAWN_EXIT_WAIT_MS);
+    const exited = await pty.waitForExit(this.failedSpawnExitWaitMs);
 
     if (exited) {
       return true;
@@ -2543,7 +2548,7 @@ export class SessionManager {
 
     pty.killForced();
 
-    return pty.waitForExit(FAILED_SPAWN_EXIT_WAIT_MS);
+    return pty.waitForExit(this.failedSpawnExitWaitMs);
   }
 
   // Whether a failed spawn's rollback leaves the session free to revive:

package/src/test-utils/build-stub-failing-attachment-listener.ts

@@ -0,0 +1,16 @@
+import type { HarnessAttachment } from '../daemon/execution-provider';
+
+/**
+ * An attachment listener that fails as a listener whose write to a closed
+ * peer fails: it throws an error with the given message each time a
+ * connection is attached, and returns quietly while one is reattaching.
+ */
+export function buildStubFailingAttachmentListener(
+  message: string,
+): (attachment: HarnessAttachment) => void {
+  return (attachment) => {
+    if (attachment === 'attached') {
+      throw new Error(message);
+    }
+  };
+}

package/src/test-utils/create-stub-failing-agent-adapter.ts

@@ -1,5 +1,6 @@
 import type { AgentAdapter } from '../agents/agent-adapter';
 import { buildMockAgentAdapter } from './build-mock-agent-adapter';
+import { runCommand } from './run-command';
 
 interface Plan {
   readonly bin: string;
@@ -34,20 +35,20 @@ interface FailingAgentAdapterConfig {
  * read finds no headless runner. Every member but the spawn plan and the
  * headless runner is the mock adapter's.
  *
- * With a ready pipe, the stub makes the pipe at that path, and the first
- * failing read blocks until a process writes its pid there, which the
- * headless runner read is synchronous for. A read that finds no writer
+ * With a ready pipe, the stub makes the pipe at that path before it
+ * resolves, and the first failing read blocks until a process writes its
+ * pid there, which the headless runner read is synchronous for. A read that finds no writer
  * within the timeout throws instead of failing the start. `getReadyPID`
  * returns the pid that read took. `countPlans` reads how many spawns the
  * adapter has planned.
  */
-export function createStubFailingAgentAdapter(config: FailingAgentAdapterConfig) {
+export async function createStubFailingAgentAdapter(config: FailingAgentAdapterConfig) {
   let planned = 0;
   let readsToFail = 0;
   let readyPID: number | null = null;
 
   if (config.ready !== null) {
-    createPipe(config.ready.path);
+    await createPipe(config.ready.path);
   }
 
   const adapter: AgentAdapter = {
@@ -90,11 +91,11 @@ export function createStubFailingAgentAdapter(config: FailingAgentAdapterConfig)
   };
 }
 
-function createPipe(path: string): void {
-  const made = Bun.spawnSync(['mkfifo', path]);
+async function createPipe(path: string): Promise<void> {
+  const made = await runCommand(['mkfifo', path]);
 
   if (made.exitCode !== 0) {
-    throw new Error(`mkfifo could not make ${path} (${made.stderr.toString().trim()})`);
+    throw new Error(`mkfifo could not make ${path} (${made.stderr.trim()})`);
   }
 }
 

package/src/test-utils/create-stub-harness-guest.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { createStubBin } from './create-stub-bin';
+import { runCommand } from './run-command';
 
 /**
  * Creates a stand-in guest program for a harness to run, under the
@@ -8,12 +9,13 @@ import { createStubBin } from './create-stub-bin';
  * `GOT:<line>`, prints `SIZE:<rows> <cols>` on `size`, and exits 3 on
  * `quit`. On `later` it waits for a line on the named pipe at `burstPath`,
  * then prints 300000 `x` bytes, more than impd's ring keeps, a newline, and
- * `BURST_DONE`. Returns the script's path and the pipe's.
+ * `BURST_DONE`. Resolves with the script's path and the pipe's once the pipe
+ * exists.
  */
-export function createStubHarnessGuest(dir: string) {
+export async function createStubHarnessGuest(dir: string) {
   const burstPath = join(dir, 'burst');
 
-  Bun.spawnSync(['mkfifo', burstPath]);
+  await runCommand(['mkfifo', burstPath]);
 
   const path = createStubBin(
     dir,

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

@@ -31,16 +31,92 @@ 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;
+/**
+ * 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; `stop` does so sooner, and a second stop does nothing.
+ */
+export function createStubImpPort(principal = 'token:atc'): StubImpPort {
+  return new StubImpPort(principal);
+}
 
-// The mode bytes a fresh attach sends ahead of a ring that has wrapped.
-const PRELUDE = '\u001B[0m';
+interface StubLease {
+  readonly principal: string;
+  readonly label: string;
+  readonly until: number;
+}
+
+interface StubConnection {
+  readonly handlers: ImpSessionHandlers;
+  sent: number;
+  finished: boolean;
+  process: StubProcess | null;
+  readonly stop: (outcome: ImpSessionOutcome) => void;
+}
+
+interface StubProcess {
+  readonly pty: IPty;
+  readonly generation: string;
+  ring: Uint8Array;
+  end: number;
+  exited: { readonly code: number | null } | null;
+
+  // Ended by a cold boot: its exit is never delivered.
+  ended: boolean;
+  connection: StubConnection | null;
+
+  // Whether its start required the broker, which an attach that requires
+  // it needs.
+  readonly requireBroker: boolean;
+}
+
+interface StubImp {
+  readonly id: string;
+  readonly name: string;
+  state: ImpState;
+  bootId: string;
+  coldBoots: ColdBoot[];
+  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>;
+}
 
 // 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';
 
+interface StubRelay {
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
+  readonly dataListeners: ((data: Uint8Array) => void)[];
+  readonly closeListeners: (() => void)[];
+
+  // Bytes a write handed over that the socket has not taken yet, and the
+  // writes waiting for them to go.
+  unsent: Uint8Array;
+  readonly roomWaiters: (() => void)[];
+}
+
 // 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.
@@ -49,8 +125,14 @@ interface StubCommandHold {
   readonly stop: () => void;
 }
 
+// impd keeps exactly this many bytes of each generation's output.
+const RING_BYTES = 262_144;
+
+// The mode bytes a fresh attach sends ahead of a ring that has wrapped.
+const PRELUDE = '\u001B[0m';
+
 /**
- * The impd stand-in the factory below creates, one per call.
+ * The impd stand-in the factory above creates, one per call.
  */
 class StubImpPort implements ImpPort {
   // Every port call, in order, as `<call> <imp> [<detail>]`.
@@ -1635,88 +1717,6 @@ class StubImpPort implements ImpPort {
   }
 }
 
-/**
- * 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; `stop` does so sooner, and a second stop does nothing.
- */
-export function createStubImpPort(principal = 'token:atc'): StubImpPort {
-  return new StubImpPort(principal);
-}
-
-interface StubLease {
-  readonly principal: string;
-  readonly label: string;
-  readonly until: number;
-}
-
-interface StubImp {
-  readonly id: string;
-  readonly name: string;
-  state: ImpState;
-  bootId: string;
-  coldBoots: ColdBoot[];
-  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 StubProcess {
-  readonly pty: IPty;
-  readonly generation: string;
-  ring: Uint8Array;
-  end: number;
-  exited: { readonly code: number | null } | null;
-
-  // Ended by a cold boot: its exit is never delivered.
-  ended: boolean;
-  connection: StubConnection | null;
-
-  // Whether its start required the broker, which an attach that requires
-  // it needs.
-  readonly requireBroker: boolean;
-}
-
-interface StubConnection {
-  readonly handlers: ImpSessionHandlers;
-  sent: number;
-  finished: boolean;
-  process: StubProcess | null;
-  readonly stop: (outcome: ImpSessionOutcome) => void;
-}
-
-interface StubRelay {
-  // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
-  readonly dataListeners: ((data: Uint8Array) => void)[];
-  readonly closeListeners: (() => void)[];
-
-  // Bytes a write handed over that the socket has not taken yet, and the
-  // writes waiting for them to go.
-  unsent: Uint8Array;
-  readonly roomWaiters: (() => void)[];
-}
-
 function buildNotFound(name: string): ImpPortError {
   return new ImpPortError('NOT_FOUND', `no imp ${name}`, { kind: 'imp', name });
 }

package/src/test-utils/run-command.ts

@@ -0,0 +1,73 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface CommandOptions {
+  readonly cwd?: string;
+
+  // The whole environment of the run, as the spawn takes it; left out, the
+  // run inherits the test's environment.
+  readonly env?: Readonly<Record<string, string | undefined>>;
+
+  readonly stdin?: string | Buffer;
+}
+
+interface CommandResult {
+  // Null when a signal ended the run.
+  readonly exitCode: number | null;
+  readonly signalCode: string | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * Runs a command as its own process and resolves once it exits and its
+ * output closes, with its exit code, the signal that ended it, and
+ * everything it printed. The run never blocks the test's event loop, so the
+ * test's timeout still applies. The command leads a process group of its
+ * own, and a run still incomplete when the test finishes has that whole
+ * group killed, so a child the command left holding its output ends too.
+ * Call it only inside a test, never from a cleanup.
+ */
+export async function runCommand(
+  cmd: readonly string[],
+  options: Readonly<CommandOptions> = {},
+): Promise<CommandResult> {
+  const proc = Bun.spawn([...cmd], {
+    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    ...(options.env === undefined ? {} : { env: { ...options.env } }),
+    stdin: options.stdin === undefined ? 'ignore' : Buffer.from(options.stdin),
+    stdout: 'pipe',
+    stderr: 'pipe',
+    detached: true,
+  });
+
+  let complete = false;
+
+  registerTestCleanup(async () => {
+    if (!complete) {
+      killProcessGroup(proc.pid);
+    }
+
+    await proc.exited;
+  });
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  complete = true;
+
+  return { exitCode: proc.exitCode, signalCode: proc.signalCode, stdout, stderr };
+}
+
+// A group already empty has nothing left to kill.
+function killProcessGroup(group: number): void {
+  try {
+    process.kill(-group, 'SIGKILL');
+  } catch (error) {
+    if (!(error instanceof Error && Reflect.get(error, 'code') === 'ESRCH')) {
+      throw error;
+    }
+  }
+}

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

@@ -22,6 +22,14 @@ interface TUIHarnessOptions {
   // How long a wait gives the client to draw its first byte; 9 seconds
   // unless set.
   readonly bootMs?: number;
+
+  // The clock the waits read their deadlines from; the wall clock unless
+  // set.
+  readonly now?: () => number;
+
+  // Waits out the interval between a wait's retries; a real sleep unless
+  // set.
+  readonly wait?: (ms: number) => Promise<void>;
 }
 
 /**
@@ -39,12 +47,16 @@ interface TUIHarnessOptions {
  * 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. `stop` kills every client a boot
+ * gets `bootMs` for that first byte. Every wait reads its deadline from
+ * `now` and sleeps between retries through `wait`, the wall clock and a real
+ * sleep unless the options set them. `stop` kills every client a boot
  * started, stops the daemon in the home, and removes the home. 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.
  */
 export function startTUIHarness(options: TUIHarnessOptions = {}) {
+  const now = options.now ?? Date.now;
+  const wait = options.wait ?? Bun.sleep;
   const tmp = setupTempDir('atc-tui-');
 
   // Registered after the home, so it releases first: the client and its
@@ -147,7 +159,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
       exited = exit.promise;
 
       capture = booted.onData((data) => {
-        firstOutputAt ??= Date.now();
+        firstOutputAt ??= now();
         out += data;
       });
 
@@ -171,7 +183,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
     },
 
     async waitFor(needle: string, ms = 4000): Promise<void> {
-      const start = Date.now();
+      const start = 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
@@ -190,7 +202,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
 
           return firstOutputAt;
         },
-        { timeoutMs: bootMs, intervalMs: 50 },
+        { timeoutMs: bootMs, intervalMs: 50, now, wait },
       );
 
       await waitFor(
@@ -201,7 +213,12 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
             );
           }
         },
-        { timeoutMs: Math.max(0, Math.max(start, firstAt) + ms - Date.now()), intervalMs: 50 },
+        {
+          timeoutMs: Math.max(0, Math.max(start, firstAt) + ms - now()),
+          intervalMs: 50,
+          now,
+          wait,
+        },
       );
     },
 
@@ -228,7 +245,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
             );
           }
         },
-        { timeoutMs: ms },
+        { timeoutMs: ms, now, wait },
       );
     },
 

package/src/test-utils/try-create-listeners.ts

@@ -0,0 +1,20 @@
+/**
+ * Creates a listener on a kernel-chosen port of every given address on this
+ * host and closes each at once, and returns whether every listener could be
+ * created, in place of the throw a failed one raises. A host without an
+ * address, such as stock macOS for any loopback address past 127.0.0.1,
+ * refuses the listener with EADDRNOTAVAIL.
+ */
+export function tryCreateListeners(hostnames: readonly string[]): boolean {
+  for (const hostname of hostnames) {
+    try {
+      const listener = Bun.listen({ hostname, port: 0, socket: { data() {} } });
+
+      listener.stop(true);
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/test-utils/try-bind-addresses.ts

@@ -1,20 +0,0 @@
-/**
- * Tries to bind a socket to every given address on this host, by listening
- * on a kernel-chosen port of each and closing it at once, and returns whether
- * every bind succeeded. A host
- * without an address, such as stock macOS for any loopback address past
- * 127.0.0.1, refuses the bind with EADDRNOTAVAIL.
- */
-export function tryBindAddresses(hostnames: readonly string[]): boolean {
-  for (const hostname of hostnames) {
-    try {
-      const listener = Bun.listen({ hostname, port: 0, socket: { data() {} } });
-
-      listener.stop(true);
-    } catch {
-      return false;
-    }
-  }
-
-  return true;
-}