@zgeoff/atc 3.5.0 → 3.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.5.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/agents/gateway-adapter.ts

@@ -58,7 +58,7 @@ export class GatewayAdapter implements AgentAdapter {
 
   // A headless turn carries the same settings file the terminal spawn does,
   // so it reaches this backend rather than the default one. A gateway whose
-  // credential comes through impd's broker runs no headless turn.
+  // credential comes through impd's broker alone runs no headless turn.
   readonly headlessRunner: HeadlessRunner | null;
 
   // The CLI's hooks are authoritative; no screen heuristics needed.
@@ -132,7 +132,7 @@ export class GatewayAdapter implements AgentAdapter {
     );
 
     this.headlessRunner =
-      headlessRun === null || gateway.auth !== undefined
+      headlessRun === null || isBrokerOnlyGateway(gateway)
         ? null
         : makeClaudeHeadlessRunner(headlessRun, {
             claudeBin: gateway.bin,
@@ -169,15 +169,16 @@ export class GatewayAdapter implements AgentAdapter {
     return {
       gateway: { id: this.gateway.id, baseURL: this.gateway.baseURL, auth },
       profiles: this.config.authProfiles,
-      brokerRequired: true,
+      brokerRequired: isBrokerOnlyGateway(this.gateway),
     };
   }
 
-  // A gateway whose credential comes through impd's broker never starts on
-  // the daemon's machine: started without the broker, the CLI would send
-  // whatever credential it holds to the gateway's host.
+  // A gateway whose credential comes through impd's broker alone never
+  // starts on the daemon's machine: started without the broker, the CLI
+  // would send whatever credential it holds to the gateway's host. One
+  // with a credential helper as well starts there under that helper.
   planSpawn(opts: SpawnOptions): SpawnPlan {
-    if (this.gateway.auth !== undefined) {
+    if (isBrokerOnlyGateway(this.gateway)) {
       throw this.buildBrokerRefusal('which only an imp target can give it');
     }
 
@@ -186,7 +187,13 @@ export class GatewayAdapter implements AgentAdapter {
 
     return {
       bin: this.gateway.bin,
-      args: this.buildArgs(opts, modeArgs, this.writeSettings(), this.writeBridge()),
+      args: this.buildArgs(
+        this.gateway.args,
+        opts,
+        modeArgs,
+        this.writeSettings(),
+        this.writeBridge(),
+      ),
     };
   }
 
@@ -196,8 +203,9 @@ export class GatewayAdapter implements AgentAdapter {
   // and placeholders in place of the credential, which the broker swaps
   // for the real one on the host's side. A shell seeds the config folder
   // before it runs the CLI, since a transferred file would replace the
-  // state an earlier run left. Any other gateway's credential
-  // helper runs on the daemon's machine, so it never runs remotely.
+  // state an earlier run left. The launch takes the auth's own arguments
+  // when it sets them, and never the credential helper, which runs on the
+  // daemon's machine alone. A gateway without auth never runs remotely.
   planGuestSpawn(opts: SpawnOptions, guest: GuestPaths): GuestSpawnPlan | null {
     if (this.gateway.auth === undefined) {
       return null;
@@ -244,11 +252,14 @@ export class GatewayAdapter implements AgentAdapter {
       argv,
     );
 
+    const args = this.gateway.auth.args ?? this.gateway.args;
+
     const launch = buildClaudeGuestLaunch(guest.dir, [
       this.gateway.bin,
       ...this.buildArgs(
+        args,
         opts,
-        this.buildGuestModeArgs(),
+        this.buildGuestModeArgs(args),
         `${guest.dir}/${settingsPath}`,
         `${guest.dir}/atc-bridge`,
       ),
@@ -291,10 +302,10 @@ export class GatewayAdapter implements AgentAdapter {
   // explicit flag, so that mode overrides the one the CLI would restore, and
   // the generated settings file, because
   // without it the CLI would resume the session against the default backend.
-  // A gateway whose credential comes through impd's broker has none, since
-  // outside atc the broker never reaches it.
+  // A gateway whose credential comes through impd's broker alone has none,
+  // since outside atc the broker never reaches it.
   buildResumeCommand(cwd: string, agentSessionID: AgentSessionID | undefined): string | null {
-    if (this.gateway.auth !== undefined) {
+    if (isBrokerOnlyGateway(this.gateway)) {
       return null;
     }
 
@@ -312,13 +323,14 @@ export class GatewayAdapter implements AgentAdapter {
   }
 
   private buildArgs(
+    args: readonly string[],
     opts: SpawnOptions,
     modeArgs: readonly string[],
     settings: string,
     pluginDir: string,
   ): string[] {
     return [
-      ...buildClaudeOverrideArgs(this.gateway.args, opts),
+      ...buildClaudeOverrideArgs(args, opts),
       ...modeArgs,
       '--settings',
       settings,
@@ -332,11 +344,11 @@ export class GatewayAdapter implements AgentAdapter {
 
   // A brokered session's Claude config is fresh, so the CLI's own default
   // mode would apply rather than the one the owner's settings set. Every
-  // start therefore names its mode: the one the gateway's arguments or
-  // settings set, else the CLI's manual mode, which asks before each
-  // action.
-  private buildGuestModeArgs(): string[] {
-    if (findFlagValue(this.gateway.args, ['--permission-mode']) !== null) {
+  // start therefore names its mode: the one the launch's arguments or the
+  // gateway's settings set, else the CLI's manual mode, which asks before
+  // each action.
+  private buildGuestModeArgs(args: readonly string[]): string[] {
+    if (findFlagValue(args, ['--permission-mode']) !== null) {
       return [];
     }
 
@@ -464,6 +476,12 @@ export class GatewayAdapter implements AgentAdapter {
   }
 }
 
+// Whether a gateway takes its credential from impd's broker with no
+// credential helper to fall back on, so it starts only behind the broker.
+function isBrokerOnlyGateway(gateway: GatewayConfig): boolean {
+  return gateway.auth !== undefined && gateway.apiKeyHelper === undefined;
+}
+
 // The variable the Claude CLI sends as a bearer authorization header, and
 // the value impd's broker replaces with the credential on the host's side.
 const BEARER_VARIABLE = 'ANTHROPIC_AUTH_TOKEN';

package/src/build-migrated-config.ts

@@ -142,6 +142,7 @@ function renderAgentEntry(entry: AgentEntry): Record<string, unknown> {
       ...(Object.keys(entry.auth.placeholderEnv).length > 0
         ? { placeholderEnv: entry.auth.placeholderEnv }
         : {}),
+      ...(entry.auth.args === undefined ? {} : { args: entry.auth.args }),
       ...(entry.mcpServers === undefined
         ? {}
         : {

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/shared/check-gateway-auth.ts

@@ -7,11 +7,14 @@ import { resolveAuthProfiles } from './resolve-auth-profiles';
 /**
  * The auth profiles a gateway's sessions are bound to through impd's
  * broker, and the variables each session gets in place of a credential,
- * every value the fixed placeholder.
+ * every value the fixed placeholder. `args`, when set, replaces the
+ * gateway's arguments on a launch behind the broker, whose host lays out
+ * its files apart from the daemon's.
  */
 export interface GatewayAuth {
   readonly profiles: readonly string[];
   readonly placeholderEnv: Readonly<Record<string, string>>;
+  readonly args?: readonly string[];
 }
 
 /**
@@ -19,7 +22,6 @@ export interface GatewayAuth {
  */
 interface GatewayAuthEntry {
   readonly baseURL?: string | undefined;
-  readonly apiKeyHelper?: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly settings?: Readonly<Record<string, unknown>> | undefined;
 }
@@ -40,15 +42,9 @@ export function checkGatewayAuth(
 
   const problems: string[] = [];
 
-  if (entry.apiKeyHelper !== undefined) {
-    problems.push(
-      'apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
-    );
-  }
-
   if (entry.settings?.['apiKeyHelper'] !== undefined) {
     problems.push(
-      'settings.apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
+      'settings.apiKeyHelper cannot be set together with auth; apiKeyHelper holds the credential helper of a launch without the broker',
     );
   }
 
@@ -128,7 +124,17 @@ function parseGatewayAuth(raw: unknown): GatewayAuth | string {
     env[key] = value;
   }
 
-  return { profiles: profiles.map(String), placeholderEnv: env };
+  const args = raw['args'];
+
+  if (args === undefined) {
+    return { profiles: profiles.map(String), placeholderEnv: env };
+  }
+
+  if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string')) {
+    return 'auth.args must be an array of strings';
+  }
+
+  return { profiles: profiles.map(String), placeholderEnv: env, args: args.map(String) };
 }
 
 // A settings env's variable names; anything but an object sets none.

package/src/shared/collect-agents.ts

@@ -325,7 +325,6 @@ function readClaudeAuth(
       raw,
       {
         baseURL: entry.baseURL,
-        apiKeyHelper: entry.apiKeyHelper,
         env: entry.env,
         settings: entry.settings,
       },

package/src/shared/collect-gateways.ts

@@ -10,8 +10,10 @@ import { isRecord } from './report';
  * A Claude-compatible backend the Claude CLI is pointed at: its own agent id,
  * its own row in the spawn menu, and its own generated settings file. The
  * credential is never held here: a helper command supplies it at run time,
- * or, with `auth`, impd's credential broker adds it to each request on the
- * host's side, so it stays out of the file atc writes.
+ * and, with `auth`, impd's credential broker adds it to each request on the
+ * host's side, so it stays out of the file atc writes. A gateway with both
+ * runs the helper on the daemon's machine and takes the broker's
+ * credential on an imp.
  */
 export interface GatewayConfig {
   readonly id: AgentID;

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;
-}