@zgeoff/atc 3.3.0 → 3.4.0

package/src/test-utils/build-stub-daemon-context.ts

@@ -0,0 +1,81 @@
+import type { DaemonContext } from '../daemon/daemon-context';
+import { TargetAccess } from '../daemon/target-access';
+import { toDaemonID } from '../shared/to-daemon-id';
+
+/**
+ * The daemon a connection serves, for tests that drive one connection
+ * without a daemon behind it: build `atc/test`, daemon id `d-1`, a 64 KiB
+ * outbound queue, a day's idempotency retention, no sessions, `claude` as
+ * the last agent used, an empty fleet, a principal that reaches no target,
+ * every session bound to the `local` target and visible, and resyncs and
+ * detaches that do nothing. Every other
+ * member throws when called, naming itself, so a test that reaches one it
+ * did not wire fails loudly. An override replaces the member it names.
+ */
+export function buildStubDaemonContext(overrides: Partial<DaemonContext> = {}): DaemonContext {
+  return {
+    build: 'atc/test',
+    daemonID: toDaemonID('d-1'),
+    queueBytes: 65_536,
+    idempotencyRetentionMs: 86_400_000,
+    collectSessions: () => [],
+    collectSpawnDirs: makeUnreached('collectSpawnDirs'),
+    collectAgents: makeUnreached('collectAgents'),
+    collectFleet: () => Promise.resolve([]),
+    loadLastUsedAgent: () => Promise.resolve('claude'),
+    findAdapter: makeUnreached('findAdapter'),
+    buildTargetAccess: () => new TargetAccess([]),
+    hasListedPrincipal: makeUnreached('hasListedPrincipal'),
+    findSessionGrant: () => ({ target: 'local', targetIdentity: 'local-pty' }),
+    findTargetIdentity: makeUnreached('findTargetIdentity'),
+    canSeeSession: () => true,
+    isSessionVisible: makeUnreached('isSessionVisible'),
+    findPermissionSession: makeUnreached('findPermissionSession'),
+    resolveSpawnParent: makeUnreached('resolveSpawnParent'),
+    resolveSpawnTarget: makeUnreached('resolveSpawnTarget'),
+    requireWorkspaceTarget: makeUnreached('requireWorkspaceTarget'),
+    buildDefaultWorkspaceDir: makeUnreached('buildDefaultWorkspaceDir'),
+    requireAgentTarget: makeUnreached('requireAgentTarget'),
+    findSource: makeUnreached('findSource'),
+    collectAlternateGitURLs: makeUnreached('collectAlternateGitURLs'),
+    checkRepositoryAccess: makeUnreached('checkRepositoryAccess'),
+    spawnSession: makeUnreached('spawnSession'),
+    killSession: makeUnreached('killSession'),
+    forgetSession: makeUnreached('forgetSession'),
+    revokeSessionAuth: makeUnreached('revokeSessionAuth'),
+    updateSessionAuth: makeUnreached('updateSessionAuth'),
+    updateSession: makeUnreached('updateSession'),
+    quitDaemon: makeUnreached('quitDaemon'),
+    ackSession: makeUnreached('ackSession'),
+    buildResumeCommand: makeUnreached('buildResumeCommand'),
+    readSessionScreen: makeUnreached('readSessionScreen'),
+    readSessionRecord: makeUnreached('readSessionRecord'),
+    loadSessionTranscript: makeUnreached('loadSessionTranscript'),
+    readEvents: makeUnreached('readEvents'),
+    readReport: makeUnreached('readReport'),
+    answerPermission: makeUnreached('answerPermission'),
+    restoreFleet: makeUnreached('restoreFleet'),
+    attachSession: makeUnreached('attachSession'),
+    detachSession: () => {},
+    detachClient: makeUnreached('detachClient'),
+    writeSessionInput: makeUnreached('writeSessionInput'),
+    writeSessionLine: makeUnreached('writeSessionLine'),
+    ejectSession: makeUnreached('ejectSession'),
+    adoptSession: makeUnreached('adoptSession'),
+    resizeSession: makeUnreached('resizeSession'),
+    resyncClient: () => Promise.resolve(),
+    getEffectiveDims: makeUnreached('getEffectiveDims'),
+    writeSessionMessage: makeUnreached('writeSessionMessage'),
+    readMessage: makeUnreached('readMessage'),
+    attachTap: makeUnreached('attachTap'),
+    detachTap: () => {},
+    ackMessage: makeUnreached('ackMessage'),
+    ...overrides,
+  };
+}
+
+function makeUnreached(member: string): () => never {
+  return () => {
+    throw new Error(`the stub daemon context has no ${member}`);
+  };
+}

package/src/test-utils/build-stub-daemon-requests.ts

@@ -0,0 +1,103 @@
+import { waitFor } from './wait-for';
+
+type DaemonAnswer = Readonly<Record<string, unknown>>;
+
+interface StubRequest {
+  readonly m: string;
+  readonly p: DaemonAnswer;
+  readonly resolve: (answer: DaemonAnswer) => void;
+}
+
+interface StubDaemonRequestsOptions {
+  // A count the client under test raises each time it acts on something,
+  // such as a draw or a callback it makes.
+  readonly countReactions: () => number;
+
+  // Milliseconds each wait for a request or a reaction lasts before it
+  // rejects; five seconds when absent.
+  readonly timeoutMs?: number;
+
+  // The clock each wait reads its deadline from; the wall clock when absent.
+  readonly now?: () => number;
+
+  // Waits out the pause between a wait's checks; a real sleep when absent.
+  readonly wait?: (ms: number) => Promise<void>;
+}
+
+/**
+ * A daemon request channel that answers only when the test says so. Every
+ * request sent through `sendRequest` waits until `answer` or
+ * `answerOldest` resolves it. Each of those waits for a request under the
+ * method to be waiting, resolves the latest or the oldest one, and then
+ * waits for the client to react: to send another request, or to raise the
+ * count `countReactions` reads. A wait that outlasts `timeoutMs` rejects:
+ * with `no <method> request is waiting for an answer` when nothing was
+ * sent under the method, and with `nothing reacted to the <method> answer`
+ * when the client never reacted. A test that takes the `now` and `wait`
+ * of a stub clock steps that timeout without waiting it out. `collectSent` returns the params of every
+ * request sent under a method, answered or not, in the order they were
+ * sent.
+ */
+export function buildStubDaemonRequests(options: StubDaemonRequestsOptions) {
+  const sent: StubRequest[] = [];
+
+  const answered = new Set<StubRequest>();
+
+  const waitOptions = {
+    timeoutMs: options.timeoutMs ?? 5000,
+    now: options.now ?? Date.now,
+    wait: options.wait ?? Bun.sleep,
+  };
+
+  const countAll = () => sent.length + options.countReactions();
+
+  const resolveAndWait = async (request: Readonly<StubRequest>, value: DaemonAnswer) => {
+    const before = countAll();
+
+    answered.add(request);
+    request.resolve(value);
+
+    await waitFor(() => {
+      if (countAll() <= before) {
+        throw new Error(`nothing reacted to the ${request.m} answer`);
+      }
+    }, waitOptions);
+  };
+
+  return {
+    sendRequest(m: string, p: DaemonAnswer = {}): Promise<DaemonAnswer> {
+      return new Promise((resolve) => {
+        sent.push({ m, p, resolve });
+      });
+    },
+    async answer(m: string, value: DaemonAnswer): Promise<void> {
+      const request = await waitFor(() => {
+        const latest = sent.findLast((r) => r.m === m && !answered.has(r));
+
+        if (latest === undefined) {
+          throw new Error(`no ${m} request is waiting for an answer`);
+        }
+
+        return latest;
+      }, waitOptions);
+
+      await resolveAndWait(request, value);
+    },
+    async answerOldest(m: string, value: DaemonAnswer): Promise<void> {
+      const request = await waitFor(() => {
+        const oldest = sent.find((r) => r.m === m && !answered.has(r));
+
+        if (oldest === undefined) {
+          throw new Error(`no ${m} request is waiting for an answer`);
+        }
+
+        return oldest;
+      }, waitOptions);
+
+      await resolveAndWait(request, value);
+    },
+    collectSent(m: string): DaemonAnswer[] {
+      return sent.filter((request) => request.m === m).map((request) => request.p);
+    },
+  };
+}

package/src/test-utils/{fixture-dir-provider.ts → build-stub-dir-provider.ts}

@@ -11,11 +11,11 @@ import type {
 import { LocalPTYProvider } from '../daemon/local-pty-provider';
 
 // One provider operation, in the order the daemon called it.
-type FixtureCall =
+type StubDirCall =
   | { readonly op: 'transfer'; readonly dir: string; readonly bytes: number }
   | { readonly op: 'run'; readonly argv: readonly string[]; readonly cwd: string };
 
-interface FixtureDirOptions {
+interface StubDirOptions {
   // Capabilities the provider declares as missing.
   readonly lacking?: readonly ExecutionCapability[];
 
@@ -25,22 +25,16 @@ interface FixtureDirOptions {
 }
 
 /**
- * An execution provider for tests whose host is a directory tree the test
- * owns: a transfer unpacks the archive with tar into the directory it is
- * given, and a command runs as a child process in its working directory.
- * Paths pass through unchanged, so a test points them into its own temp
- * tree. Every transfer and command is recorded in `calls`. Harnesses start
- * on a local pseudo-terminal, and each one's spec is recorded in
- * `harnesses`.
+ * The directory-tree provider the factory below builds, one per call.
  */
-export class FixtureDirProvider implements ExecutionProvider {
+class StubDirProvider implements ExecutionProvider {
   readonly kind = 'fixture-dir';
 
   readonly remote = false;
 
   readonly capabilities: ExecutionCapabilities;
 
-  readonly calls: FixtureCall[] = [];
+  readonly calls: StubDirCall[] = [];
 
   // Every harness the provider started, as the daemon specified it.
   readonly harnesses: HarnessSpec[] = [];
@@ -49,7 +43,7 @@ export class FixtureDirProvider implements ExecutionProvider {
 
   private readonly terminals = new LocalPTYProvider();
 
-  constructor(options: FixtureDirOptions = {}) {
+  constructor(options: StubDirOptions = {}) {
     const lacking = new Set(options.lacking);
 
     this.capabilities = {
@@ -129,3 +123,17 @@ export class FixtureDirProvider implements ExecutionProvider {
 
   readonly dispose = (): void => {};
 }
+
+/**
+ * Builds an execution provider of kind `fixture-dir` for tests whose host is
+ * a directory tree the test owns: a transfer unpacks the archive with tar
+ * into the directory it is given, and a command runs as a child process in
+ * its working directory. Paths pass through unchanged, so a test points them
+ * into its own temp tree. Every transfer and command is recorded in `calls`.
+ * Harnesses start on a local pseudo-terminal, and each one's spec is
+ * recorded in `harnesses`. Suspending or destroying a host rejects, since
+ * the test's own tree neither sleeps nor goes away.
+ */
+export function buildStubDirProvider(options: StubDirOptions = {}): StubDirProvider {
+  return new StubDirProvider(options);
+}

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

@@ -0,0 +1,112 @@
+import type {
+  ExecutionCapabilities,
+  ExecutionProvider,
+  HarnessSpec,
+} from '../daemon/execution-provider';
+import { LocalPTYProvider } from '../daemon/local-pty-provider';
+
+interface StubExecutionProviderConfig {
+  // The provider kind the daemon reports for the target.
+  readonly kind?: string;
+
+  // Capabilities that differ from a local pseudo-terminal's.
+  readonly capabilities?: Partial<ExecutionCapabilities>;
+
+  /**
+   * Called with each harness spec before the harness starts; a throw from
+   * it aborts the spawn.
+   */
+  readonly onSpawn?: (spec: HarnessSpec) => void;
+}
+
+interface StubExecutionProvider extends ExecutionProvider {
+  // Every host the daemon put to sleep, in order.
+  readonly suspended: string[];
+
+  // Every host the daemon destroyed, in order.
+  readonly destroyed: string[];
+
+  /**
+   * Rejects every host suspend with the error, recording nothing, until
+   * called with null.
+   */
+  readonly setSuspendFailure: (error: Readonly<Error> | null) => void;
+
+  /**
+   * Rejects every host destroy with the error, recording nothing, until
+   * called with null.
+   */
+  readonly setDestroyFailure: (error: Readonly<Error> | null) => void;
+}
+
+/**
+ * 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
+ * `destroyed` and resolves, or rejects with the error a failure setter gave.
+ * The daemon calls them only when the capabilities declare `suspend` or
+ * `destroy`.
+ */
+export function buildStubExecutionProvider(
+  config: StubExecutionProviderConfig = {},
+): StubExecutionProvider {
+  const local = new LocalPTYProvider();
+
+  const onSpawn = config.onSpawn ?? (() => {});
+  const suspended: string[] = [];
+  const destroyed: string[] = [];
+
+  // The errors a suspend and a destroy reject with, or null while they
+  // succeed.
+  const failures: { suspend: Readonly<Error> | null; destroy: Readonly<Error> | null } = {
+    suspend: null,
+    destroy: null,
+  };
+
+  return {
+    kind: config.kind ?? 'stub',
+    remote: false,
+    capabilities: { ...local.capabilities, ...config.capabilities },
+    prepareHost: local.prepareHost,
+    spawnHarness: (spec) => {
+      onSpawn(spec);
+
+      return local.spawnHarness(spec);
+    },
+    transferArchive: local.transferArchive,
+    runCommand: local.runCommand,
+    suspendHost: (host) => {
+      const failure = failures.suspend;
+
+      if (failure !== null) {
+        return Promise.reject(failure);
+      }
+
+      suspended.push(host);
+
+      return Promise.resolve();
+    },
+    destroyHost: (host) => {
+      const failure = failures.destroy;
+
+      if (failure !== null) {
+        return Promise.reject(failure);
+      }
+
+      destroyed.push(host);
+
+      return Promise.resolve();
+    },
+    dispose: local.dispose,
+    suspended,
+    destroyed,
+    setSuspendFailure: (error) => {
+      failures.suspend = error;
+    },
+    setDestroyFailure: (error) => {
+      failures.destroy = error;
+    },
+  };
+}

package/src/test-utils/build-stub-fleet-caller.ts

@@ -0,0 +1,60 @@
+import type { FleetCaller, FleetFeature } from '../mcp/types';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { DAEMON_FEATURES } from '../protocol/daemon-features';
+
+/**
+ * One request a stub fleet caller received: the method and each further
+ * argument the sender passed, with an argument left undefined left out.
+ */
+interface StubFleetRequest {
+  readonly m: string;
+  readonly p?: Readonly<Record<string, unknown>>;
+  readonly required?: readonly DaemonFeature[];
+  readonly principal?: string;
+}
+
+type StubFleetAnswer = (
+  request: StubFleetRequest,
+) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+
+interface StubFleetCallerConfig {
+  // Gives the reply to one request: a value, a promise, or a throw, which
+  // the caller turns into a rejection, as a daemon refusal arrives.
+  readonly answer?: StubFleetAnswer;
+
+  // The features the caller reports its daemon announced.
+  readonly features?: readonly FleetFeature[];
+}
+
+/**
+ * A fleet caller that stands in for a daemon connection: it records every
+ * request in `requests`, in the order sent, and replies through the
+ * config's `answer`, by default an empty record. It reports the config's
+ * `features`, by default every feature a current daemon announces, and it
+ * checks no request's required features against them, so a test that needs
+ * that refusal uses a real connection.
+ */
+export function buildStubFleetCaller(
+  config: StubFleetCallerConfig = {},
+): FleetCaller & { readonly requests: readonly StubFleetRequest[] } {
+  const answer: StubFleetAnswer = config.answer ?? (() => ({}));
+  const features: readonly FleetFeature[] = config.features ?? DAEMON_FEATURES;
+  const requests: StubFleetRequest[] = [];
+
+  return {
+    requests,
+    sendRequest: (m, p, required, principal) => {
+      const request: StubFleetRequest = {
+        m,
+        ...(p === undefined ? {} : { p }),
+        ...(required === undefined ? {} : { required }),
+        ...(principal === undefined ? {} : { principal }),
+      };
+
+      requests.push(request);
+
+      return Promise.try(() => answer(request));
+    },
+    readFeatures: () => Promise.resolve(new Set(features)),
+  };
+}

package/src/test-utils/build-stub-forking-gh.ts

@@ -0,0 +1,10 @@
+/**
+ * The script of a stand-in `gh` that starts a child of its own and waits on
+ * it, as a gh extension might. It writes its own process ID, which is also
+ * the ID of the process group it leads when started detached, and its
+ * child's ID to `pidsFile`, one per line, moving the file into place so it
+ * appears whole. The child runs until it is killed.
+ */
+export function buildStubForkingGH(pidsFile: string): string {
+  return `#!/bin/sh\nsh -c 'sleep 30' &\nprintf '%s\\n%s\\n' $$ $! > '${pidsFile}.tmp'\nmv '${pidsFile}.tmp' '${pidsFile}'\nwait\n`;
+}

package/src/test-utils/build-stub-gh.ts

@@ -0,0 +1,50 @@
+interface StubGHReply {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode?: number;
+}
+
+interface StubGHOptions {
+  // What each command prints and exits with, keyed by its first argument,
+  // such as `repo` or `config`; `hang` waits until the command is killed.
+  // A command without a reply prints nothing and exits 0.
+  readonly replies: Readonly<Record<string, StubGHReply | 'hang'>>;
+
+  // A file each run appends its arguments to, as one line.
+  readonly argvFile?: string;
+}
+
+/**
+ * The script of a stand-in `gh` that answers each command with the reply
+ * the test gave for its first argument: the stdout and stderr verbatim,
+ * then the exit code, 0 when unset. A `hang` reply waits until it is
+ * killed, as a gh that never answers does.
+ */
+export function buildStubGH(options: StubGHOptions): string {
+  const record =
+    options.argvFile === undefined
+      ? ''
+      : `printf '%s\\n' "$*" >> ${toShellLiteral(options.argvFile)}\n`;
+
+  const cases = Object.entries(options.replies)
+    .map(([command, reply]) => `  ${toShellLiteral(command)}) ${renderReply(reply)} ;;\n`)
+    .join('');
+
+  return `#!/bin/sh\n${record}case "$1" in\n${cases}esac\n`;
+}
+
+function toShellLiteral(value: string): string {
+  return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+
+function renderReply(reply: StubGHReply | 'hang'): string {
+  if (reply === 'hang') {
+    return 'exec sleep 30';
+  }
+
+  return [
+    `printf '%s' ${toShellLiteral(reply.stdout ?? '')}`,
+    `printf '%s' ${toShellLiteral(reply.stderr ?? '')} >&2`,
+    `exit ${reply.exitCode ?? 0}`,
+  ].join('; ');
+}

package/src/test-utils/build-stub-handoff-daemon.ts

@@ -0,0 +1,11 @@
+/**
+ * The script of a stand-in `atc` whose daemon hands its socket to a
+ * replacement: it moves the socket listening at `listeningPath` to
+ * `$HOME/atc-daemon.sock`, where a client of a daemon on that home dials,
+ * and exits 0. Write it with `createStubBin`.
+ */
+export function buildStubHandoffDaemon(listeningPath: string): string {
+  return `#!/usr/bin/env bash
+mv '${listeningPath}' "$HOME/atc-daemon.sock"
+`;
+}

package/src/test-utils/build-stub-harness-relay.ts

@@ -0,0 +1,50 @@
+import type { HarnessRelay } from '../daemon/execution-provider';
+
+/**
+ * A harness relay held in memory, as a provider hands one to the daemon for
+ * a guest's connection. `sendLine` delivers a value as one JSON line from
+ * the guest to every line listener, `written` holds every line written back
+ * to the guest, parsed, in order, and `isClosed` turns true once the relay
+ * is closed. A write settles at once, as a relay with room does. `hangUp`
+ * runs every close listener, as a guest that hangs up does; closing the
+ * relay from the daemon's end runs none.
+ */
+export function buildStubHarnessRelay() {
+  const lineListeners: ((line: string) => void)[] = [];
+  const closeListeners: (() => void)[] = [];
+  const written: unknown[] = [];
+  let closed = false;
+
+  const relay: HarnessRelay = {
+    onLine: (listener) => {
+      lineListeners.push(listener);
+    },
+    onClose: (listener) => {
+      closeListeners.push(listener);
+    },
+    writeLine: (line) => {
+      written.push(JSON.parse(line));
+
+      return Promise.resolve();
+    },
+    close: () => {
+      closed = true;
+    },
+  };
+
+  return {
+    relay,
+    written,
+    isClosed: () => closed,
+    sendLine: (value: Readonly<Record<string, unknown>>) => {
+      for (const listener of lineListeners) {
+        listener(JSON.stringify(value));
+      }
+    },
+    hangUp: () => {
+      for (const listener of closeListeners) {
+        listener();
+      }
+    },
+  };
+}

package/src/test-utils/build-stub-headless-runner.ts

@@ -0,0 +1,60 @@
+import type {
+  HeadlessRunEvents,
+  HeadlessRunRequest,
+  HeadlessRunner,
+} from '../agents/agent-adapter';
+
+interface StubHeadlessRun {
+  readonly request: HeadlessRunRequest;
+
+  // The events the daemon listens on, which the test calls to play the run.
+  readonly events: HeadlessRunEvents;
+  stopped: boolean;
+}
+
+interface StubHeadlessRunner {
+  readonly runner: HeadlessRunner;
+
+  // Every run the daemon started, in order, and whether it stopped it.
+  readonly runs: readonly StubHeadlessRun[];
+
+  // Resolves with the run at the index, counting from zero, once the
+  // daemon starts it.
+  readonly waitForRun: (index: number) => Promise<StubHeadlessRun>;
+}
+
+/**
+ * A headless runner for daemon tests that starts no process. Each run the
+ * daemon starts is recorded in `runs`, in order, and does nothing until
+ * the test plays it by calling the run's events: output, a finished turn,
+ * or a turn that needs the user. A stop marks the run stopped and plays
+ * nothing, as a killed turn reports nothing more.
+ */
+export function buildStubHeadlessRunner(): StubHeadlessRunner {
+  const runs: StubHeadlessRun[] = [];
+  const started: PromiseWithResolvers<StubHeadlessRun>[] = [];
+
+  const getStarted = (index: number) => {
+    started[index] ??= Promise.withResolvers<StubHeadlessRun>();
+
+    return started[index];
+  };
+
+  return {
+    runner: (request, events) => {
+      const run: StubHeadlessRun = { request, events, stopped: false };
+
+      runs.push(run);
+
+      getStarted(runs.length - 1).resolve(run);
+
+      return {
+        stop: () => {
+          run.stopped = true;
+        },
+      };
+    },
+    runs,
+    waitForRun: (index) => getStarted(index).promise,
+  };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The script of a stand-in `gh` whose repository listing waits for the
+ * test. `gh config …` prints `https`. Any other command touches
+ * `$HOME/gh-held` and waits while `$HOME/gh-hold` exists, then prints one
+ * repository, `me/dots`, in the JSON shape `gh repo list` prints.
+ */
+export function buildStubHeldGH(): string {
+  return `#!/bin/sh
+case "$1" in
+  config) echo https ;;
+  *)
+    if [ -f "$HOME/gh-hold" ]; then
+      touch "$HOME/gh-held"
+      while [ -f "$HOME/gh-hold" ]; do sleep 0.05; done
+    fi
+    echo '[{"nameWithOwner":"me/dots","description":"dotfiles","isPrivate":false,"url":"https://github.com/me/dots","sshUrl":"git@github.com:me/dots.git"}]' ;;
+esac
+`;
+}

package/src/test-utils/build-stub-held-inbox-source.ts

@@ -0,0 +1,36 @@
+import type { TapClient } from '../daemon/daemon-context';
+import type { InboxSource } from '../daemon/drain-inbox';
+import { TapRegistry } from '../daemon/tap-registry';
+import type { AgentSessionID } from '../shared/agent-session-id';
+import type { SessionID } from '../shared/session-id';
+import type { MessageRecord } from '../store/message-record';
+
+/**
+ * An inbox source over a real, empty tap registry, standing in for the
+ * daemon's store. It holds every session under the given agent session id,
+ * and its pending-message read waits until the test answers it: `reading`
+ * settles once a read starts, `read` answers the read with the given
+ * messages whatever owner it asked for.
+ */
+export function buildStubHeldInboxSource(agentSessionID: AgentSessionID) {
+  const pending = Promise.withResolvers<MessageRecord[]>();
+  const reading = Promise.withResolvers<void>();
+
+  const source: InboxSource = {
+    taps: new TapRegistry<TapClient>(),
+    findLinkedOwner: (sessionID: SessionID) => ({ atcID: sessionID, agentSessionID }),
+    collectPendingMessages: () => {
+      reading.resolve();
+
+      return pending.promise;
+    },
+  };
+
+  return {
+    source,
+    reading: reading.promise,
+    read: (records: readonly MessageRecord[]) => {
+      pending.resolve([...records]);
+    },
+  };
+}