@openparachute/agent 0.2.2 → 0.2.3-rc.10

package/src/backends/registry.test.ts

@@ -1,1494 +0,0 @@
-/**
- * Tests for the daemon-level PROGRAMMATIC-AGENT registry + per-channel serial queue
- * (`src/backends/registry.ts`) — the wiring that drives the {@link ProgrammaticBackend}.
- *
- * A FAKE backend (implements {@link AgentBackend}) lets us control each turn's
- * outcome + timing without a real `claude -p`: a deferred-promise gate makes a turn
- * "run" until the test releases it, so the FIFO / never-concurrent invariant is
- * directly observable. The outbound writes go to a recorder array. No tmux, no
- * vault, no hub.
- */
-
-import { describe, test, expect } from "bun:test";
-import {
-  ProgrammaticAgentRegistry,
-  OUTBOUND_MAX_RETRIES,
-  PENDING_INBOUND_CAP,
-  MAX_DELEGATION_DEPTH,
-  isTransientOutboundError,
-  type WriteOutbound,
-  type WriteThread,
-  type WriteCallback,
-  type CallbackMeta,
-  type ThreadNote,
-  type TurnEventSink,
-  type TurnLifecycleEvent,
-} from "./registry.ts";
-import type {
-  AgentBackend,
-  AgentHandle,
-  AgentStatus,
-  DeliverResult,
-  InterimSink,
-  TurnSession,
-} from "./types.ts";
-import type { AgentSpec } from "../sandbox/types.ts";
-
-/** A deferred promise — resolve it externally to release a gated turn. */
-function deferred<T>(): { promise: Promise<T>; resolve: (v: T) => void } {
-  let resolve!: (v: T) => void;
-  const promise = new Promise<T>((r) => (resolve = r));
-  return { promise, resolve };
-}
-
-/**
- * A controllable fake backend. `deliver` records each (channel, message), tracks how
- * many turns are CONCURRENTLY in flight (the serial-queue invariant asserts this
- * never exceeds 1), and resolves with whatever `nextResult` says. When `gate` is set,
- * a turn blocks on it until the test releases it — so we can hold a turn "running"
- * while we enqueue more.
- */
-class FakeBackend implements AgentBackend {
-  readonly kind = "programmatic";
-  /** Per-call records, in arrival order — including the caller-resolved {@link TurnSession}. */
-  readonly calls: { channel: string; message: string; session: TurnSession }[] = [];
-  /** Max concurrent in-flight turns observed (must stay ≤ 1 for serial). */
-  maxConcurrent = 0;
-  private inFlight = 0;
-  /** Whether `stop` was called, per channel. */
-  readonly stopped = new Set<string>();
-  /** A gate the next turn waits on (release to let it finish). Reset per use. */
-  gate: { promise: Promise<void>; resolve: () => void } | null = null;
-  /**
-   * The result function — given the message + the turn's session id, returns the
-   * DeliverResult to resolve. The DEFAULT ECHOES `sessionId` (mirroring real claude, which
-   * always echoes the `--session-id`/`--resume` id it was handed on a successful turn) so a
-   * successful turn's thread note carries the established session — the FIX-2 invariant.
-   * An override that omits `sessionId` models a turn that failed BEFORE establishing one.
-   */
-  resultFor: (message: string, sessionId: string) => DeliverResult = (m, sid) => ({
-    ok: true,
-    reply: "reply:" + m,
-    sessionId: sid,
-  });
-  /** If set, `deliver` THROWS this (to test the defensive catch). */
-  throwOnce: Error | null = null;
-  /** Interim events to emit (via `onInterim`) during the next turn — set per test. */
-  interimToEmit: Parameters<InterimSink>[0][] = [];
-
-  async start(spec: AgentSpec): Promise<AgentHandle> {
-    return { backend: this.kind, channel: spec.channels[0] as string, name: spec.name, spec };
-  }
-
-  async deliver(
-    handle: AgentHandle,
-    message: string,
-    session: TurnSession,
-    onInterim?: InterimSink,
-  ): Promise<DeliverResult> {
-    this.calls.push({ channel: handle.channel, message, session });
-    this.inFlight++;
-    this.maxConcurrent = Math.max(this.maxConcurrent, this.inFlight);
-    try {
-      // Emit any configured interim events (mirrors the real backend streaming text +
-      // tool_use as the turn runs) so the registry's forwarding can be asserted.
-      if (onInterim) for (const e of this.interimToEmit) onInterim(e);
-      if (this.gate) await this.gate.promise;
-      if (this.throwOnce) {
-        const e = this.throwOnce;
-        this.throwOnce = null;
-        throw e;
-      }
-      return this.resultFor(message, session.id);
-    } finally {
-      this.inFlight--;
-    }
-  }
-
-  async stop(handle: AgentHandle): Promise<void> {
-    this.stopped.add(handle.channel);
-  }
-
-  async status(_handle: AgentHandle): Promise<AgentStatus> {
-    return { live: true };
-  }
-}
-
-/** A recorder WriteOutbound — captures every posted reply. */
-function recorder(): { calls: { channel: string; reply: string; inReplyTo?: string }[]; fn: WriteOutbound } {
-  const calls: { channel: string; reply: string; inReplyTo?: string }[] = [];
-  const fn: WriteOutbound = async (channel, reply, inReplyTo) => {
-    calls.push({ channel, reply, ...(inReplyTo ? { inReplyTo } : {}) });
-  };
-  return { calls, fn };
-}
-
-/**
- * A recorder WriteThread — captures every `#agent/thread` note the registry writes.
- *
- * The thread-as-container lifecycle writes TWO notes per turn: a `phase:"start"`
- * working-ensure BEFORE the turn, then a `phase:"end"` final record after. `threads`
- * holds ALL writes in order; `ends()` / `starts()` filter by phase so a test can assert
- * the FINAL records (the pre-thread-as-container assertions) without counting the
- * working-ensure, or assert the working-ensure specifically.
- */
-function threadRecorder(): {
-  threads: ThreadNote[];
-  ends: () => ThreadNote[];
-  starts: () => ThreadNote[];
-  fn: WriteThread;
-} {
-  const threads: ThreadNote[] = [];
-  const fn: WriteThread = async (thread) => {
-    threads.push(thread);
-  };
-  return {
-    threads,
-    // `phase:"end"` is explicit on every registry-emitted final record; a write with no
-    // phase would also be a final record (back-compat), so treat absent as end too.
-    ends: () => threads.filter((t) => t.phase !== "start"),
-    starts: () => threads.filter((t) => t.phase === "start"),
-    fn,
-  };
-}
-
-/** A multi-threaded spec (materializes one `#agent/thread` note per fire). */
-const specMultiThreaded = (name: string, channel = name, definition?: string): AgentSpec => ({
-  name,
-  channels: [channel],
-  mode: "multi-threaded",
-  ...(definition ? { definition } : {}),
-});
-
-/** A recorder TurnEventSink — captures every (channel, event) the registry emits. */
-function turnRecorder(): { events: { channel: string; event: TurnLifecycleEvent }[]; fn: TurnEventSink } {
-  const events: { channel: string; event: TurnLifecycleEvent }[] = [];
-  const fn: TurnEventSink = (channel, event) => {
-    events.push({ channel, event });
-  };
-  return { events, fn };
-}
-
-const specFor = (name: string, channel = name): AgentSpec => ({ name, channels: [channel] });
-
-/** Spin the microtask/timer queue until `pred()` is true or we give up. */
-async function until(pred: () => boolean, tries = 200): Promise<void> {
-  for (let i = 0; i < tries && !pred(); i++) {
-    await new Promise<void>((r) => setTimeout(r, 1));
-  }
-}
-
-describe("ProgrammaticAgentRegistry — registration + indexes", () => {
-  test("register indexes by channel + name; has/get reflect it", async () => {
-    const backend = new FakeBackend();
-    const { fn } = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: fn });
-
-    expect(reg.hasChannel("eng")).toBe(false);
-    const h = await reg.register(specFor("eng"));
-    expect(h.name).toBe("eng");
-    expect(h.channel).toBe("eng");
-    expect(reg.hasChannel("eng")).toBe(true);
-    expect(reg.hasName("eng")).toBe(true);
-    expect(reg.getByChannel("eng")?.name).toBe("eng");
-    expect(reg.getByName("eng")?.channel).toBe("eng");
-    expect(reg.list().map((x) => x.name)).toEqual(["eng"]);
-  });
-
-  test("deregister drops the indexes + tears down the backend handle (stop)", async () => {
-    const backend = new FakeBackend();
-    const { fn } = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: fn });
-    await reg.register(specFor("eng"));
-    expect(await reg.deregister("eng")).toBe(true);
-    expect(reg.hasChannel("eng")).toBe(false);
-    expect(reg.hasName("eng")).toBe(false);
-    // deregister calls backend.stop (a no-op for programmatic) — it does NOT clear the
-    // thread-note session; re-registering should resume. Wiping continuity is resetSession.
-    expect(backend.stopped.has("eng")).toBe(true);
-    // A second deregister is a no-op false.
-    expect(await reg.deregister("eng")).toBe(false);
-  });
-
-  test("resetSession CLEARS the thread-note session (via clearSession) WITHOUT deregistering", async () => {
-    const backend = new FakeBackend();
-    const { fn } = recorder();
-    // Track the clearSession invocations + simulate the note's session being wiped: after a
-    // clear, readSession returns undefined for that (channel, name).
-    const cleared: { channel: string; name: string }[] = [];
-    let priorSession: string | undefined = "sess-OLD";
-    const clearSession = async (channel: string, name: string) => {
-      cleared.push({ channel, name });
-      priorSession = undefined; // the note's session is now empty.
-    };
-    const reader: { calls: { channel: string; name: string }[] } = { calls: [] };
-    const readSession = async (channel: string, name: string) => {
-      reader.calls.push({ channel, name });
-      return priorSession;
-    };
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: fn,
-      writeThread: threads.fn,
-      readSession,
-      clearSession,
-    });
-    await reg.register(specFor("eng"));
-
-    // RESET → invokes clearSession with the right (channel, name); does NOT deregister.
-    expect(await reg.resetSession("eng")).toBe(true);
-    expect(cleared).toEqual([{ channel: "eng", name: "eng" }]);
-    expect(reg.hasName("eng")).toBe(true); // still registered.
-    // reset() does NOT route through backend.stop anymore (the session lives on the note).
-    expect(backend.stopped.has("eng")).toBe(false);
-
-    // BONUS — after the reset, the next drain finds NO prior session → a fresh {resume:false}
-    // create (self-heal), proving reset actually wiped continuity (not a dead no-op).
-    reg.enqueue("eng", { content: "after reset" });
-    await until(() => backend.calls.length === 1);
-    expect(backend.calls[0]!.session.resume).toBe(false);
-    expect(backend.calls[0]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-
-    expect(await reg.resetSession("nope")).toBe(false);
-  });
-});
-
-describe("ProgrammaticAgentRegistry — inbound enqueue + outbound", () => {
-  test("a delivered turn writes a non-empty reply as an outbound note", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    expect(reg.enqueue("eng", { content: "hello", inReplyTo: "note-1" })).toBe(true);
-    await until(() => rec.calls.length === 1);
-
-    expect(backend.calls).toHaveLength(1);
-    expect(backend.calls[0]!.channel).toBe("eng");
-    expect(backend.calls[0]!.message).toBe("hello");
-    // No readSession wired → a single-threaded turn CREATES a fresh session (resume:false).
-    expect(backend.calls[0]!.session.resume).toBe(false);
-    expect(backend.calls[0]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-    expect(rec.calls).toEqual([{ channel: "eng", reply: "reply:hello", inReplyTo: "note-1" }]);
-  });
-
-  test("enqueue for an UNREGISTERED channel is a no-op false (caller falls back)", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    expect(reg.enqueue("ghost", { content: "x" })).toBe(false);
-    expect(backend.calls).toHaveLength(0);
-  });
-
-  test("an EMPTY reply writes NO outbound note (reviewer contract)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: true, reply: "" });
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "tool-only work" });
-    await until(() => backend.calls.length === 1);
-    // Give any erroneous outbound write a chance to land, then assert none did.
-    await new Promise<void>((r) => setTimeout(r, 5));
-    expect(backend.calls).toHaveLength(1);
-    expect(rec.calls).toHaveLength(0);
-  });
-
-  test("an ok:false turn writes a user-facing FAILURE note + does not crash/loop", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: false, error: "mint refused" });
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "do it" });
-    await until(() => rec.calls.length === 1);
-    await new Promise<void>((r) => setTimeout(r, 5));
-    // Exactly ONE turn ran (the backend owns turn-retry, not the drain), and the drain
-    // posted a SINGLE user-facing failure note carrying the reason (no silent no-reply).
-    expect(backend.calls).toHaveLength(1);
-    expect(rec.calls).toHaveLength(1);
-    expect(rec.calls[0]!.reply).toContain("mint refused");
-  });
-
-  test("a deliver() that THROWS is caught — the worker survives + drains the rest", async () => {
-    const backend = new FakeBackend();
-    backend.throwOnce = new Error("surprise throw");
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "first (throws)" });
-    reg.enqueue("eng", { content: "second (ok)" });
-    await until(() => rec.calls.length === 2);
-    // Both turns ran; the throw on the first didn't strand the second. The caught throw
-    // posts a user-facing failure note (carrying the reason); the second succeeds normally.
-    expect(backend.calls.map((c) => c.message)).toEqual(["first (throws)", "second (ok)"]);
-    expect(rec.calls).toHaveLength(2);
-    expect(rec.calls[0]!.reply).toContain("surprise throw");
-    expect(rec.calls[1]!).toEqual({ channel: "eng", reply: "reply:second (ok)" });
-  });
-});
-
-describe("ProgrammaticAgentRegistry — #agent/thread notes (unified lifecycle, BOTH modes)", () => {
-  test("a completed MULTI-THREADED turn materializes an #agent/thread note (status ok) carrying input/output/definition/mode/name", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specMultiThreaded("digest", "digest", "Agents/digest"));
-
-    reg.enqueue("digest", { content: "run the digest" });
-    await until(() => threads.ends().length === 1);
-
-    // Thread-as-container: ONE working-ensure (phase:start, status:working) BEFORE the turn,
-    // then ONE final record (phase:end, status:ok) after — for the same per-fire note.
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.starts()[0]!.status).toBe("working");
-    expect(threads.ends()).toHaveLength(1);
-    const thread = threads.ends()[0]!;
-    expect(thread.channel).toBe("digest");
-    expect(thread.name).toBe("digest");
-    expect(thread.status).toBe("ok");
-    expect(thread.mode).toBe("multi-threaded");
-    expect(thread.definition).toBe("Agents/digest");
-    expect(thread.input).toBe("run the digest");
-    expect(thread.output).toBe("reply:run the digest");
-    expect(typeof thread.started_at).toBe("string");
-    expect(typeof thread.ended_at).toBe("string");
-    // The start + end target the SAME per-fire note (same threadId) — no duplicate minted.
-    expect(threads.starts()[0]!.threadId).toBe(thread.threadId!);
-    // The dual-write is ADDITIVE: a non-empty reply writes EXACTLY one outbound
-    // (the chat delivery) AND exactly one FINAL thread note (the primary record).
-    await until(() => rec.calls.length === 1);
-    expect(rec.calls.length).toBe(1);
-    expect(threads.ends().length).toBe(1);
-  });
-
-  test("a SINGLE-THREADED turn ALSO materializes ONE #agent/thread note (the unified model — named after the def)", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    // specFor → no mode → single-threaded (the default).
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hello" });
-    await until(() => threads.ends().length === 1);
-
-    // BOTH modes materialize a thread note now (the structural unification): a
-    // single-threaded turn writes ONE FINAL record, mode single-threaded, NAMED AFTER THE
-    // DEF (the deterministic upsert key the transport derives the stable path from).
-    // Thread-as-container: a working-ensure (phase:start) preceded it (same upsert key).
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.starts()[0]!.name).toBe("eng");
-    expect(threads.ends()).toHaveLength(1);
-    expect(threads.ends()[0]!.mode).toBe("single-threaded");
-    expect(threads.ends()[0]!.name).toBe("eng");
-    expect(threads.ends()[0]!.channel).toBe("eng");
-    expect(threads.ends()[0]!.input).toBe("hello");
-    expect(threads.ends()[0]!.output).toBe("reply:hello");
-    // The single-threaded outbound reply was still written (no regression).
-    expect(rec.calls).toHaveLength(1);
-  });
-
-  test("a single-threaded agent over TWO turns records ONE thread (same name/channel — the upsert key) both turns, status carries forward", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specFor("eng")); // single-threaded (default).
-
-    // Two turns on the same channel — drained serially, FIFO.
-    reg.enqueue("eng", { content: "turn one" });
-    reg.enqueue("eng", { content: "turn two" });
-    await until(() => threads.ends().length === 2);
-
-    // recordThread (the FINAL record) is called for BOTH turns (the registry seam can't
-    // simulate the transport's read-existing upsert, so we assert the UPSERT KEY is stable
-    // across turns — same channel + same name + same mode — which the transport maps to the
-    // SAME deterministic path `Threads/<channel>/<name>`, overwriting in place. The per-turn
-    // turn_count/usage aggregation — incl. the start-ensure NOT double-counting — is covered
-    // at the vault-transport layer). Each turn ALSO emits its own working-ensure (phase:start).
-    expect(threads.starts()).toHaveLength(2);
-    expect(threads.ends()).toHaveLength(2);
-    const [t1, t2] = threads.ends();
-    expect(t1!.mode).toBe("single-threaded");
-    expect(t2!.mode).toBe("single-threaded");
-    expect(t1!.name).toBe("eng");
-    expect(t2!.name).toBe("eng"); // SAME upsert key → same note, upserted.
-    expect(t1!.channel).toBe("eng");
-    expect(t2!.channel).toBe("eng");
-    expect(t1!.input).toBe("turn one");
-    expect(t2!.input).toBe("turn two");
-  });
-
-  test("a multi-threaded fire writes a thread note per fire (each carries this fire's turn — distinct records)", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specMultiThreaded("digest"));
-
-    reg.enqueue("digest", { content: "fire A" });
-    reg.enqueue("digest", { content: "fire B" });
-    await until(() => threads.ends().length === 2);
-
-    // One FINAL thread note PER FIRE (today one fire = one thread = one note; the transport
-    // assigns each a fresh uuid path, so they're distinct records). Each fire's start-ensure
-    // shares that fire's threadId (so start + end target the SAME per-fire note).
-    expect(threads.ends()).toHaveLength(2);
-    expect(threads.ends().map((t) => t.input)).toEqual(["fire A", "fire B"]);
-    expect(threads.ends().every((t) => t.mode === "multi-threaded")).toBe(true);
-    expect(threads.starts()).toHaveLength(2);
-    // Per fire the working-ensure + final record share a threadId (distinct across fires).
-    expect(threads.starts()[0]!.threadId).toBe(threads.ends()[0]!.threadId!);
-    expect(threads.starts()[1]!.threadId).toBe(threads.ends()[1]!.threadId!);
-    expect(threads.ends()[0]!.threadId).not.toBe(threads.ends()[1]!.threadId);
-  });
-
-  test("a FAILED MULTI-THREADED turn still materializes an #agent/thread note with status:error + the reason", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: false, error: "mint refused" });
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specMultiThreaded("digest"));
-
-    reg.enqueue("digest", { content: "do it" });
-    await until(() => threads.ends().length === 1);
-
-    // The working-ensure (phase:start) still ran BEFORE the turn; the FINAL record is error.
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.ends()).toHaveLength(1);
-    expect(threads.ends()[0]!.mode).toBe("multi-threaded");
-    expect(threads.ends()[0]!.status).toBe("error");
-    expect(threads.ends()[0]!.output).toBe("mint refused");
-    // A user-facing failure note IS now written for a failed turn (carries the reason).
-    expect(rec.calls).toHaveLength(1);
-    expect(rec.calls[0]!.reply).toContain("mint refused");
-  });
-
-  test("a FAILED SINGLE-THREADED turn ALSO materializes an #agent/thread note with status:error (substantiates BOTH modes)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: false, error: "mint refused" });
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    // specFor → no mode → single-threaded (the default).
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "do it" });
-    await until(() => threads.ends().length === 1);
-
-    // The working-ensure (phase:start) still ran BEFORE the turn; the FINAL record is error.
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.ends()).toHaveLength(1);
-    expect(threads.ends()[0]!.mode).toBe("single-threaded");
-    expect(threads.ends()[0]!.name).toBe("eng");
-    expect(threads.ends()[0]!.status).toBe("error");
-    expect(threads.ends()[0]!.output).toBe("mint refused");
-    // A user-facing failure note IS now written for a failed turn (carries the reason).
-    expect(rec.calls).toHaveLength(1);
-    expect(rec.calls[0]!.reply).toContain("mint refused");
-  });
-
-  test("a turn with an empty reply STILL materializes a thread note (status ok, empty output)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: true, reply: "" });
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specMultiThreaded("digest"));
-
-    reg.enqueue("digest", { content: "tool-only run" });
-    await until(() => threads.ends().length === 1);
-    // The working-ensure (phase:start, no fake reply) preceded the empty-reply final record.
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.starts()[0]!.output).toBe("");
-    expect(threads.ends()[0]!.status).toBe("ok");
-    expect(threads.ends()[0]!.output).toBe("");
-    // Empty reply → no outbound message note (the thread note IS the record).
-    expect(rec.calls).toHaveLength(0);
-  });
-
-  test("REGRESSION (c34db03, now BOTH modes): a turn whose outbound write THROWS still leaves a primary #agent/thread note (now re-recorded as error — FIX 1)", async () => {
-    const backend = new FakeBackend();
-    const threads = threadRecorder();
-    // A THROWING WriteOutbound — the thread note is written BEFORE the additive outbound
-    // (c34db03, now applied uniformly to BOTH modes), so the failed transcript write must
-    // NOT cost us the primary record. Use a SINGLE-THREADED spec to prove the c34db03
-    // ordering now protects single-threaded too. (`recorder()` can't throw; inline variant.)
-    // The error message carries NO HTTP status → classified TRANSIENT → it RETRIES the
-    // bounded budget (FIX 1, PR #3) before giving up, then re-records the thread as error.
-    let outboundAttempts = 0;
-    const throwingWriteOutbound: WriteOutbound = async () => {
-      outboundAttempts++;
-      throw new Error("vault write boom"); // no (NNN) status → transient → retried.
-    };
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: throwingWriteOutbound,
-      writeThread: threads.fn,
-      outboundRetryBaseMs: 0,
-    });
-    await reg.register(specFor("eng")); // single-threaded (default) — the ordering applies here now.
-
-    reg.enqueue("eng", { content: "fire it" });
-    // Thread-as-container + FIX 1: a working-ensure (phase:start) is written first, then the
-    // primary `ok` FINAL record, then after retries exhaust a `error` FINAL record re-records
-    // the UN-DELIVERED reply — so `ends()` (the final records) is exactly [ok, error].
-    await until(() => threads.ends().length === 2);
-
-    // The working-ensure preceded everything (status:working, no fake reply).
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.starts()[0]!.status).toBe("working");
-    // First FINAL (optimistic) record was `ok`; the second re-records the failure so the
-    // durable thread record does NOT falsely claim the reply landed.
-    expect(threads.ends()[0]!.status).toBe("ok");
-    expect(threads.ends()[0]!.output).toBe("reply:fire it");
-    expect(threads.ends()[1]!.status).toBe("error");
-    expect(threads.ends()[1]!.mode).toBe("single-threaded");
-    // The undelivered reply text is preserved in the error record for recovery.
-    expect(threads.ends()[1]!.output).toContain("reply:fire it");
-    // The re-record reuses the SAME per-turn threadId + sameTurn (no double-count, no dup).
-    expect(threads.ends()[1]!.threadId).toBe(threads.ends()[0]!.threadId!);
-    expect(threads.ends()[1]!.sameTurn).toBe(true);
-    // Transient → the outbound was retried the full budget (1 initial + OUTBOUND_MAX_RETRIES).
-    expect(outboundAttempts).toBe(1 + OUTBOUND_MAX_RETRIES);
-  });
-});
-
-describe("ProgrammaticAgentRegistry — thread≡session (the daemon owns the uuid)", () => {
-  /** A recorder readSession — captures every (channel, name) consulted; returns `prior`. */
-  function sessionReader(prior?: string): {
-    calls: { channel: string; name: string }[];
-    fn: (channel: string, name: string) => Promise<string | undefined>;
-  } {
-    const calls: { channel: string; name: string }[] = [];
-    const fn = async (channel: string, name: string) => {
-      calls.push({ channel, name });
-      return prior;
-    };
-    return { calls, fn };
-  }
-
-  test("single-threaded with a PRIOR session: consults readSession + passes {resume:true} to deliver", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reader = sessionReader("11111111-1111-4111-8111-111111111111");
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: rec.fn,
-      writeThread: threads.fn,
-      readSession: reader.fn,
-    });
-    await reg.register(specFor("eng")); // single-threaded (default).
-
-    reg.enqueue("eng", { content: "hello" });
-    await until(() => backend.calls.length === 1);
-
-    // readSession was consulted with the channel + the def name (the deterministic key).
-    expect(reader.calls).toEqual([{ channel: "eng", name: "eng" }]);
-    // A prior session → RESUME it (continue the conversation), with that exact id.
-    expect(backend.calls[0]!.session).toEqual({
-      id: "11111111-1111-4111-8111-111111111111",
-      resume: true,
-    });
-    // The END record carries the session claude echoed (the persisted thread≡session record).
-    await until(() => threads.ends().length === 1);
-    expect(threads.ends()[0]!.session).toBe("11111111-1111-4111-8111-111111111111");
-    // The START-ensure carries NO session (FIX 2) — it runs before claude, so no session is
-    // established yet; persisting one there would brick the next turn if claude never inited.
-    // (Continuity for a single-threaded resume is preserved by the transport's prior-read.)
-    expect(threads.starts()[0]!.session).toBeUndefined();
-  });
-
-  test("single-threaded with NO prior session: consults readSession + passes {resume:false} + a fresh uuid", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reader = sessionReader(undefined); // no prior — first turn.
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: rec.fn,
-      writeThread: threads.fn,
-      readSession: reader.fn,
-    });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hello" });
-    await until(() => backend.calls.length === 1);
-
-    expect(reader.calls).toEqual([{ channel: "eng", name: "eng" }]);
-    // No prior → CREATE a fresh session with a generated uuid (--session-id, not --resume).
-    expect(backend.calls[0]!.session.resume).toBe(false);
-    expect(backend.calls[0]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-    // The fresh uuid is the one persisted onto the thread note (so turn 2 can resume it).
-    await until(() => threads.ends().length === 1);
-    expect(threads.ends()[0]!.session).toBe(backend.calls[0]!.session.id);
-  });
-
-  test("multi-threaded NEVER consults readSession + ALWAYS passes {resume:false} with a fresh uuid", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reader = sessionReader("should-never-be-used");
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: rec.fn,
-      writeThread: threads.fn,
-      readSession: reader.fn,
-    });
-    await reg.register(specMultiThreaded("digest", "digest"));
-
-    // Two fires — each must mint its OWN fresh session, never resume.
-    reg.enqueue("digest", { content: "fire one" });
-    await until(() => backend.calls.length === 1);
-    reg.enqueue("digest", { content: "fire two" });
-    await until(() => backend.calls.length === 2);
-
-    // readSession is NEVER consulted for a multi-threaded agent (each fire is a fresh thread).
-    expect(reader.calls).toHaveLength(0);
-    // Both fires CREATE fresh sessions (resume:false), with DISTINCT uuids.
-    expect(backend.calls[0]!.session.resume).toBe(false);
-    expect(backend.calls[1]!.session.resume).toBe(false);
-    expect(backend.calls[0]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-    expect(backend.calls[1]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-    expect(backend.calls[0]!.session.id).not.toBe(backend.calls[1]!.session.id);
-    // Each per-fire thread note carries its own fire's session.
-    await until(() => threads.ends().length === 2);
-    expect(threads.ends()[0]!.session).toBe(backend.calls[0]!.session.id);
-    expect(threads.ends()[1]!.session).toBe(backend.calls[1]!.session.id);
-  });
-
-  test("no readSession wired: a single-threaded turn still CREATES a fresh session", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hello" });
-    await until(() => backend.calls.length === 1);
-
-    expect(backend.calls[0]!.session.resume).toBe(false);
-    expect(backend.calls[0]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-    await until(() => threads.ends().length === 1);
-    expect(threads.ends()[0]!.session).toBe(backend.calls[0]!.session.id);
-  });
-
-  test("the captured backend sessionId (Claude's echoed id) is what lands on the thread note", async () => {
-    const backend = new FakeBackend();
-    // The backend echoes a DIFFERENT id than the one we passed (Claude's authoritative id).
-    backend.resultFor = (m) => ({ ok: true, reply: "reply:" + m, sessionId: "echoed-by-claude-id" });
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hello" });
-    await until(() => threads.ends().length === 1);
-
-    // The END record prefers Claude's echoed id (result.sessionId) over the uuid we passed.
-    expect(threads.ends()[0]!.session).toBe("echoed-by-claude-id");
-  });
-
-  test("FIX 2 — a failed turn that established NO session persists NONE → next turn self-heals (no brick)", async () => {
-    const backend = new FakeBackend();
-    // A turn that FAILS before claude ever creates a session: { ok:false } with NO sessionId
-    // (claude exited before emitting an init/result session_id). The OLD code persisted the
-    // passed uuid here → next turn `--resume`d a phantom id → "No conversation found" →
-    // permanent brick. FIX 2: persist NOTHING when claude echoed no session.
-    backend.resultFor = () => ({ ok: false, error: "claude exited 1 before init" });
-    const rec = recorder();
-    const threads = threadRecorder();
-    // Simulate the note: readSession returns whatever the last persisted end-record carried.
-    let stored: string | undefined; // no prior session.
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: rec.fn,
-      writeThread: async (t) => {
-        threads.threads.push(t);
-        // Mirror the transport's persistence: an end record with a session sets it; a start
-        // or a sessionless end leaves the prior value (the transport preserves single-threaded).
-        if (t.phase !== "start" && t.session) stored = t.session;
-      },
-      readSession: async () => stored,
-    });
-    await reg.register(specFor("eng")); // single-threaded (default).
-
-    // Turn 1 — fails before establishing a session.
-    reg.enqueue("eng", { content: "boom" });
-    await until(() => threads.ends().length === 1);
-    // The error end-record carries NO session (claude echoed none) — so the note stays clean.
-    expect(threads.ends()[0]!.status).toBe("error");
-    expect(threads.ends()[0]!.session).toBeUndefined();
-    expect(stored).toBeUndefined(); // nothing persisted → no phantom to --resume.
-
-    // Turn 2 — readSession finds no session → a FRESH {resume:false} create (self-heal,
-    // NOT a brick). The next turn is a clean new conversation, not a doomed --resume.
-    reg.enqueue("eng", { content: "again" });
-    await until(() => backend.calls.length === 2);
-    expect(backend.calls[1]!.session.resume).toBe(false);
-    expect(backend.calls[1]!.session.id).toMatch(/^[0-9a-f-]{36}$/);
-  });
-});
-
-describe("ProgrammaticAgentRegistry — outbound retry on transient failure (FIX 1, PR #3)", () => {
-  test("isTransientOutboundError: 5xx + network = transient; 4xx = permanent", () => {
-    expect(isTransientOutboundError(new Error("write reply failed (502) boom"))).toBe(true);
-    expect(isTransientOutboundError(new Error("write reply failed (503)"))).toBe(true);
-    expect(isTransientOutboundError(new Error("ECONNREFUSED"))).toBe(true); // no status → network.
-    expect(isTransientOutboundError(new Error("fetch failed"))).toBe(true);
-    expect(isTransientOutboundError(new Error("write reply failed (400) bad"))).toBe(false);
-    expect(isTransientOutboundError(new Error("write reply failed (401)"))).toBe(false);
-    expect(isTransientOutboundError(new Error("write reply failed (409)"))).toBe(false);
-  });
-
-  test("a transient-then-success outbound RETRIES and the reply LANDS (no loss, turn not re-run)", async () => {
-    const backend = new FakeBackend();
-    const threads = threadRecorder();
-    // Fail twice with a transient (5xx) error, then succeed — the retry must land the reply.
-    let attempts = 0;
-    const recorded: { reply: string }[] = [];
-    const flakyWriteOutbound: WriteOutbound = async (_channel, reply) => {
-      attempts++;
-      if (attempts <= 2) throw new Error("vault transport: write reply failed (502) blip");
-      recorded.push({ reply });
-    };
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: flakyWriteOutbound,
-      writeThread: threads.fn,
-      outboundRetryBaseMs: 0,
-    });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "important" });
-    await until(() => recorded.length === 1);
-    await new Promise<void>((r) => setTimeout(r, 5));
-
-    // The reply landed on the 3rd attempt (1 initial + 2 retries == OUTBOUND_MAX_RETRIES).
-    expect(attempts).toBe(1 + OUTBOUND_MAX_RETRIES);
-    expect(recorded).toEqual([{ reply: "reply:important" }]);
-    // The backend ran the turn EXACTLY ONCE (no re-run / fork on the retry).
-    expect(backend.calls).toHaveLength(1);
-    // The FINAL thread note is the single `ok` record (the reply was ultimately delivered) —
-    // no error re-record because delivery succeeded. (A working-ensure preceded it.)
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.ends()).toHaveLength(1);
-    expect(threads.ends()[0]!.status).toBe("ok");
-  });
-
-  test("a PERSISTENT failure surfaces an error event + re-records the thread as error + does NOT claim success", async () => {
-    const backend = new FakeBackend();
-    const threads = threadRecorder();
-    const turn = turnRecorder();
-    let attempts = 0;
-    const alwaysFail: WriteOutbound = async () => {
-      attempts++;
-      throw new Error("vault transport: write reply failed (503) down");
-    };
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: alwaysFail,
-      writeThread: threads.fn,
-      onTurnEvent: turn.fn,
-      outboundRetryBaseMs: 0,
-    });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "doomed" });
-    await until(() => threads.ends().length === 2);
-    await new Promise<void>((r) => setTimeout(r, 5));
-
-    // Retried the full budget then gave up (1 + OUTBOUND_MAX_RETRIES).
-    expect(attempts).toBe(1 + OUTBOUND_MAX_RETRIES);
-    // The live view resolved to ERROR (not `done`) — no silently-vanished reply.
-    const errorEvents = turn.events.filter((e) => e.event.kind === "error");
-    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
-    expect(turn.events.some((e) => e.event.kind === "done")).toBe(false);
-    // The FINAL thread record does NOT falsely claim a clean ok: the second final record is
-    // error, carrying the un-delivered reply text for recovery. (A working-ensure preceded.)
-    expect(threads.ends()).toHaveLength(2);
-    expect(threads.ends()[1]!.status).toBe("error");
-    expect(threads.ends()[1]!.output).toContain("reply:doomed");
-  });
-
-  test("a PERMANENT (4xx) outbound failure does NOT retry — gives up immediately", async () => {
-    const backend = new FakeBackend();
-    const threads = threadRecorder();
-    let attempts = 0;
-    const reject4xx: WriteOutbound = async () => {
-      attempts++;
-      throw new Error("vault transport: write reply failed (400) bad request");
-    };
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: reject4xx,
-      writeThread: threads.fn,
-      outboundRetryBaseMs: 0,
-    });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "rejected" });
-    await until(() => threads.ends().length === 2);
-    await new Promise<void>((r) => setTimeout(r, 5));
-
-    // A 4xx is a real rejection → exactly ONE attempt, no retry.
-    expect(attempts).toBe(1);
-    // The second FINAL record re-records the turn as error (the un-delivered reply).
-    expect(threads.ends()).toHaveLength(2);
-    expect(threads.ends()[1]!.status).toBe("error");
-  });
-});
-
-describe("ProgrammaticAgentRegistry — serial queue (the hard invariant)", () => {
-  test("two inbounds during a running turn are processed ONE AT A TIME, FIFO, never concurrent", async () => {
-    const backend = new FakeBackend();
-    const gate = deferred<void>();
-    backend.gate = { promise: gate.promise, resolve: gate.resolve };
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    // First enqueue starts a turn that blocks on the gate.
-    reg.enqueue("eng", { content: "m1" });
-    await until(() => backend.calls.length === 1);
-    expect(reg.statusOf("eng").state).toBe("working");
-
-    // Two more arrive WHILE the first turn is in flight — they queue.
-    reg.enqueue("eng", { content: "m2" });
-    reg.enqueue("eng", { content: "m3" });
-    // Still exactly one call has STARTED (the gate holds the first; the others wait).
-    expect(backend.calls).toHaveLength(1);
-    expect(reg.statusOf("eng")).toEqual({ state: "queued", queued: 2 });
-
-    // Release the gate: the worker drains m1, then m2, then m3 in order. Because the
-    // gate's promise is already resolved, subsequent turns don't block.
-    gate.resolve();
-    await until(() => rec.calls.length === 3);
-
-    expect(backend.calls.map((c) => c.message)).toEqual(["m1", "m2", "m3"]);
-    expect(rec.calls.map((c) => c.reply)).toEqual(["reply:m1", "reply:m2", "reply:m3"]);
-    // The invariant: never two concurrent turns for the same channel.
-    expect(backend.maxConcurrent).toBe(1);
-    // Queue fully drained → idle.
-    expect(reg.statusOf("eng").state).toBe("idle");
-  });
-
-  test("statusOf — idle with no work, working with one in flight, queued:N with a backlog", async () => {
-    const backend = new FakeBackend();
-    const gate = deferred<void>();
-    backend.gate = { promise: gate.promise, resolve: gate.resolve };
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-    expect(reg.statusOf("eng")).toEqual({ state: "idle", queued: 0 });
-
-    reg.enqueue("eng", { content: "a" });
-    await until(() => backend.calls.length === 1);
-    expect(reg.statusOf("eng")).toEqual({ state: "working", queued: 0 });
-
-    reg.enqueue("eng", { content: "b" });
-    expect(reg.statusOf("eng")).toEqual({ state: "queued", queued: 1 });
-
-    gate.resolve();
-    await until(() => rec.calls.length === 2);
-    expect(reg.statusOf("eng")).toEqual({ state: "idle", queued: 0 });
-  });
-});
-
-describe("ProgrammaticAgentRegistry — streaming turn view (onTurnEvent)", () => {
-  test("forwards the backend's interim events + a final 'done' (keyed by channel)", async () => {
-    const backend = new FakeBackend();
-    backend.interimToEmit = [
-      { kind: "init", sessionId: "s-1" },
-      { kind: "text", text: "thinking…" },
-      { kind: "tool", tool: "Read" },
-    ];
-    backend.resultFor = () => ({ ok: true, reply: "final answer" });
-    const rec = recorder();
-    const turns = turnRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, onTurnEvent: turns.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hi" });
-    await until(() => rec.calls.length === 1);
-    // Let the trailing 'done' (emitted after the outbound write) land.
-    await until(() => turns.events.some((e) => e.event.kind === "done"));
-
-    expect(turns.events.map((e) => e.channel)).toEqual(["eng", "eng", "eng", "eng"]);
-    expect(turns.events.map((e) => e.event)).toEqual([
-      { kind: "init", sessionId: "s-1" },
-      { kind: "text", text: "thinking…" },
-      { kind: "tool", tool: "Read" },
-      { kind: "done", reply: "final answer" },
-    ]);
-    // The durable outbound write is unchanged by the live view.
-    expect(rec.calls).toEqual([{ channel: "eng", reply: "final answer" }]);
-  });
-
-  test("an ok:false turn emits a 'error' lifecycle event (no stuck working state)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: false, error: "mint refused" });
-    const rec = recorder();
-    const turns = turnRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, onTurnEvent: turns.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "x" });
-    await until(() => rec.calls.length === 1);
-
-    expect(turns.events).toEqual([{ channel: "eng", event: { kind: "error", error: "mint refused" } }]);
-    // The failed turn ALSO posts a user-facing failure note (carrying the reason).
-    expect(rec.calls).toHaveLength(1);
-    expect(rec.calls[0]!.reply).toContain("mint refused");
-  });
-
-  test("a backend THROW also emits 'error' (the defensive catch resolves the live view)", async () => {
-    const backend = new FakeBackend();
-    backend.throwOnce = new Error("boom");
-    const rec = recorder();
-    const turns = turnRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, onTurnEvent: turns.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "x" });
-    await until(() => turns.events.some((e) => e.event.kind === "error"));
-
-    expect(turns.events).toEqual([{ channel: "eng", event: { kind: "error", error: "boom" } }]);
-  });
-
-  test("an empty reply still emits 'done' (with reply '') so the live view finalizes", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: true, reply: "" });
-    const rec = recorder();
-    const turns = turnRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, onTurnEvent: turns.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "tool-only" });
-    await until(() => turns.events.some((e) => e.event.kind === "done"));
-
-    expect(turns.events).toEqual([{ channel: "eng", event: { kind: "done", reply: "" } }]);
-    // No durable note for an empty reply (the existing contract), but the view finalizes.
-    expect(rec.calls).toHaveLength(0);
-  });
-
-  test("a throwing sink can't break the worker (the durable write still lands)", async () => {
-    const backend = new FakeBackend();
-    backend.interimToEmit = [{ kind: "text", text: "hi" }];
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: rec.fn,
-      onTurnEvent: () => {
-        throw new Error("dead stream");
-      },
-    });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hi" });
-    await until(() => rec.calls.length === 1);
-    expect(rec.calls).toEqual([{ channel: "eng", reply: "reply:hi" }]);
-  });
-
-  test("with NO sink wired, turns run exactly as before (no throw, durable write lands)", async () => {
-    const backend = new FakeBackend();
-    backend.interimToEmit = [{ kind: "text", text: "ignored" }];
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hi" });
-    await until(() => rec.calls.length === 1);
-    expect(rec.calls).toEqual([{ channel: "eng", reply: "reply:hi" }]);
-  });
-});
-
-describe("ProgrammaticAgentRegistry — pending-inbound queue + replay-on-register (agent#121)", () => {
-  test("an inbound for an EXPECTED-but-not-yet-registered channel is QUEUED pending (not dropped)", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-
-    // No live agent yet — but the channel is EXPECTED (the def-instantiation path marked it
-    // before bringing the agent up). enqueue() would no-op false here; queuePending OWNS it.
-    reg.expectChannel("eng");
-    expect(reg.hasChannel("eng")).toBe(false);
-    expect(reg.enqueue("eng", { content: "early" })).toBe(false); // not live → enqueue declines.
-    expect(reg.queuePending("eng", { content: "early" })).toBe("queued");
-    expect(reg.pendingCount("eng")).toBe(1);
-    // Nothing ran yet (no live agent), but nothing was lost either.
-    expect(backend.calls).toHaveLength(0);
-  });
-
-  test("queuePending for a genuinely UNKNOWN channel (not expected) returns 'unknown' (caller logs+drops)", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    // Never expected, never registered → nothing maps to it.
-    expect(reg.queuePending("ghost", { content: "x" })).toBe("unknown");
-    expect(reg.pendingCount("ghost")).toBe(0);
-  });
-
-  test("on register() the channel's pending queue DRAINS into the serial worker, in arrival order (FIFO)", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-
-    // Three inbound arrive BEFORE the agent is live — all buffered pending.
-    reg.expectChannel("eng");
-    expect(reg.queuePending("eng", { content: "first" })).toBe("queued");
-    expect(reg.queuePending("eng", { content: "second" })).toBe("queued");
-    expect(reg.queuePending("eng", { content: "third" })).toBe("queued");
-    expect(reg.pendingCount("eng")).toBe(3);
-
-    // The agent registers → the buffer replays through the normal serial path, FIFO.
-    await reg.register(specFor("eng"));
-    await until(() => rec.calls.length === 3);
-
-    // The buffer is drained + the EXPECTED mark cleared (the live index is the truth now).
-    expect(reg.pendingCount("eng")).toBe(0);
-    expect(reg.isExpected("eng")).toBe(false);
-    // Turns ran in arrival order (the serial worker drains FIFO).
-    expect(backend.calls.map((c) => c.message)).toEqual(["first", "second", "third"]);
-    expect(rec.calls.map((c) => c.reply)).toEqual(["reply:first", "reply:second", "reply:third"]);
-  });
-
-  test("the pending buffer is CAPPED — past the cap the OLDEST is evicted (FIFO), newest kept", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-
-    reg.expectChannel("eng");
-    // Fill to the cap, then push one MORE — the oldest ("m0") is evicted.
-    for (let i = 0; i < PENDING_INBOUND_CAP; i++) {
-      expect(reg.queuePending("eng", { content: `m${i}` })).toBe("queued");
-    }
-    expect(reg.pendingCount("eng")).toBe(PENDING_INBOUND_CAP);
-    expect(reg.queuePending("eng", { content: "overflow" })).toBe("queued");
-    // Still capped (didn't grow past the cap).
-    expect(reg.pendingCount("eng")).toBe(PENDING_INBOUND_CAP);
-  });
-
-  test("an UNKNOWN channel queuePending does NOT crash + leaves the registry usable", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    expect(() => reg.queuePending("ghost", { content: "x" })).not.toThrow();
-    // The registry still works for a real registration afterward.
-    expect(reg.queuePending("ghost", { content: "y" })).toBe("unknown");
-  });
-
-  test("register() clears the EXPECTED mark even with an EMPTY pending buffer", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    reg.expectChannel("eng");
-    expect(reg.isExpected("eng")).toBe(true);
-    await reg.register(specFor("eng"));
-    expect(reg.isExpected("eng")).toBe(false);
-    expect(reg.pendingCount("eng")).toBe(0);
-  });
-
-  test("unexpectChannel drops a stale EXPECTED mark + its buffered pending (teardown)", () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-    reg.expectChannel("eng");
-    reg.queuePending("eng", { content: "stranded" });
-    expect(reg.pendingCount("eng")).toBe(1);
-    reg.unexpectChannel("eng");
-    expect(reg.isExpected("eng")).toBe(false);
-    expect(reg.pendingCount("eng")).toBe(0);
-    // A subsequent inbound for the now-unexpected channel is 'unknown' (correctly dropped).
-    expect(reg.queuePending("eng", { content: "after" })).toBe("unknown");
-  });
-
-  test("a channel-move re-register clears the OLD channel's expected mark + pending buffer (no leak)", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-
-    // Register the agent on channel "old", then buffer a pending inbound for "old".
-    await reg.register({ name: "mover", channels: ["old"] });
-    reg.expectChannel("old");
-    reg.queuePending("old", { content: "stranded" });
-    expect(reg.pendingCount("old")).toBe(1);
-
-    // Re-register the SAME name onto a DIFFERENT wake channel — the old channel's indexes,
-    // expected mark, and pending buffer must all be dropped (nothing routes to "old" now).
-    await reg.register({ name: "mover", channels: ["new"] });
-    expect(reg.hasChannel("old")).toBe(false);
-    expect(reg.isExpected("old")).toBe(false);
-    expect(reg.pendingCount("old")).toBe(0);
-    expect(reg.hasChannel("new")).toBe(true);
-  });
-
-  test("a pending inbound that arrives DURING a drain (after register) still replays in order", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn });
-
-    // Two pending before register.
-    reg.expectChannel("eng");
-    reg.queuePending("eng", { content: "p1" });
-    reg.queuePending("eng", { content: "p2" });
-
-    await reg.register(specFor("eng"));
-    // After register the channel is LIVE — a further inbound goes through enqueue directly.
-    await until(() => rec.calls.length === 2);
-    expect(reg.enqueue("eng", { content: "p3" })).toBe(true);
-    await until(() => rec.calls.length === 3);
-
-    expect(backend.calls.map((c) => c.message)).toEqual(["p1", "p2", "p3"]);
-  });
-});
-
-describe("ProgrammaticAgentRegistry — thread-as-container working-ensure (Part B)", () => {
-  test("the working-ensure (phase:start, status:working) is written BEFORE deliver() runs", async () => {
-    const backend = new FakeBackend();
-    // Gate the turn so we can observe the working-ensure write WHILE the turn is in flight.
-    const gate = deferred<void>();
-    backend.gate = { promise: gate.promise, resolve: gate.resolve };
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "do work" });
-    // Wait until deliver() is in flight (the turn was handed the message + is blocked on the
-    // gate). The start-ensure is `await`ed BEFORE deliver() in the drain, so by the time
-    // deliver() has been called the working-ensure MUST already be written — and the FINAL
-    // (end) record must NOT be (the turn hasn't completed). This proves the ordering:
-    // working-ensure strictly precedes the turn.
-    await until(() => backend.calls.length === 1);
-    expect(threads.starts()).toHaveLength(1);
-    expect(threads.starts()[0]!.status).toBe("working");
-    expect(threads.starts()[0]!.output).toBe(""); // NO fake reply while working.
-    expect(threads.starts()[0]!.input).toBe("do work");
-    // The turn is in flight but hasn't produced its end record yet (gated).
-    expect(backend.calls).toHaveLength(1);
-    expect(threads.ends()).toHaveLength(0);
-
-    // Release the turn → it completes → the FINAL (ok) record lands, same threadId.
-    gate.resolve();
-    await until(() => threads.ends().length === 1);
-    expect(threads.ends()[0]!.status).toBe("ok");
-    expect(threads.ends()[0]!.threadId).toBe(threads.starts()[0]!.threadId!);
-  });
-
-  test("the start-ensure does NOT write a fake reply even though the turn ultimately replies", async () => {
-    const backend = new FakeBackend();
-    const rec = recorder();
-    const threads = threadRecorder();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: rec.fn, writeThread: threads.fn });
-    await reg.register(specFor("eng"));
-
-    reg.enqueue("eng", { content: "hi" });
-    await until(() => threads.ends().length === 1);
-    // The working-ensure carries status:working + empty output; the end carries the reply.
-    expect(threads.starts()[0]!.status).toBe("working");
-    expect(threads.starts()[0]!.output).toBe("");
-    expect(threads.ends()[0]!.output).toBe("reply:hi");
-  });
-
-  test("the OUTBOUND reply is stamped with the turn's thread id (definition→thread→message link); multi-threaded → the per-fire note leaf", async () => {
-    const backend = new FakeBackend();
-    const threads = threadRecorder();
-    // A recorder that ALSO captures the threadId the worker passes to writeOutbound.
-    const outbound: { reply: string; threadId?: string }[] = [];
-    const writeOutbound: WriteOutbound = async (_channel, reply, _inReplyTo, threadId) => {
-      outbound.push({ reply, ...(threadId ? { threadId } : {}) });
-    };
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound, writeThread: threads.fn });
-    await reg.register(specMultiThreaded("digest"));
-
-    reg.enqueue("digest", { content: "go" });
-    await until(() => outbound.length === 1);
-    // The outbound carries the per-turn thread id, which for multi-threaded equals the
-    // per-fire thread note's leaf — the explicit message↔thread link.
-    expect(outbound[0]!.threadId).toBeDefined();
-    expect(outbound[0]!.threadId).toBe(threads.ends()[0]!.threadId!);
-  });
-});
-
-// ───────────────────────────────────────────────────────────────────────────────
-// AGENT-TO-AGENT CALLBACK ROUTING ("reply_to") — design 2026-06-20-agent-callbacks.md.
-// A FAKE WriteCallback recorder captures every callback the drain delivers (its target
-// channel + content + the metadata contract), so we can assert: a reply_to message gets
-// exactly one callback w/ the right metadata; a no-reply_to message gets none; ok AND error
-// both fire; the depth guard suppresses; and N callbacks to one channel drain FIFO + none
-// is lost (the orchestrator-resume concurrency story).
-// ───────────────────────────────────────────────────────────────────────────────
-
-/** A recorder WriteCallback — captures every callback the registry delivers, in order. */
-function callbackRecorder(): {
-  calls: { channel: string; content: string; meta: CallbackMeta }[];
-  fn: WriteCallback;
-} {
-  const calls: { channel: string; content: string; meta: CallbackMeta }[] = [];
-  const fn: WriteCallback = async (channel, content, meta) => {
-    calls.push({ channel, content, meta });
-  };
-  return { calls, fn };
-}
-
-/** A WriteOutbound that returns a deterministic note id, so source_message is assertable. */
-function recorderWithId(noteId = "outbound-note-1"): {
-  calls: { channel: string; reply: string }[];
-  fn: WriteOutbound;
-} {
-  const calls: { channel: string; reply: string }[] = [];
-  const fn: WriteOutbound = async (channel, reply) => {
-    calls.push({ channel, reply });
-    return { id: noteId };
-  };
-  return { calls, fn };
-}
-
-describe("ProgrammaticAgentRegistry — agent-to-agent callbacks (reply_to)", () => {
-  test("an inbound WITH reply_to → exactly ONE callback to the reply_to channel with the full metadata contract (ok)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    const out = recorderWithId("reply-note-42");
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", {
-      content: "sub-task",
-      inReplyTo: "inbound-note-7",
-      replyTo: "orchestrator",
-      correlationId: "corr-abc",
-      delegationDepth: 2,
-    });
-    await until(() => cb.calls.length === 1);
-    // Let any erroneous SECOND callback land, then assert there was exactly one.
-    await new Promise<void>((r) => setTimeout(r, 5));
-    expect(cb.calls).toHaveLength(1);
-
-    const { channel, content, meta } = cb.calls[0]!;
-    expect(channel).toBe("orchestrator"); // delivered to the SENDER's channel.
-    expect(content).toContain("[callback]");
-    expect(content).not.toContain("done:sub-task"); // summary + link, NOT the full reply.
-    expect(meta.callback).toBe("true");
-    expect(meta.status).toBe("ok");
-    expect(meta.source_channel).toBe("worker");
-    expect(meta.source_message).toBe("reply-note-42"); // the delivered outbound note id.
-    expect(meta.source_thread).toBeDefined(); // the per-turn thread id (pull link).
-    expect(meta.correlation_id).toBe("corr-abc"); // echoed verbatim.
-    expect(meta.delegation_depth).toBe("3"); // incoming 2 + 1 hop.
-    // The callback note must NOT itself carry a reply_to (terminal — the loop guard).
-    expect((meta as unknown as Record<string, unknown>).reply_to).toBeUndefined();
-  });
-
-  test("an inbound WITHOUT reply_to → NO callback (a normal turn never emits one)", async () => {
-    const backend = new FakeBackend();
-    const out = recorderWithId();
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", { content: "plain message" });
-    await until(() => out.calls.length === 1);
-    await new Promise<void>((r) => setTimeout(r, 5));
-    expect(out.calls).toHaveLength(1); // the turn ran + replied normally,
-    expect(cb.calls).toHaveLength(0); // but no callback fired.
-  });
-
-  test("the callback fires on an ERROR turn too (status:error, no source_message)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = () => ({ ok: false, error: "mint refused" });
-    const out = recorderWithId();
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", { content: "do it", replyTo: "orchestrator", delegationDepth: 0 });
-    await until(() => cb.calls.length === 1);
-    await new Promise<void>((r) => setTimeout(r, 5));
-    expect(cb.calls).toHaveLength(1);
-    // An error turn now posts a user-facing failure note to the worker's own channel
-    // (in addition to the orchestrator callback) — carrying the reason.
-    expect(out.calls).toHaveLength(1);
-    expect(out.calls[0]!.reply).toContain("mint refused");
-    const { meta, content } = cb.calls[0]!;
-    expect(meta.status).toBe("error"); // but the orchestrator still learns it failed.
-    expect(content).toContain("error");
-    expect(meta.source_message).toBeUndefined(); // no delivered reply note.
-    expect(meta.delegation_depth).toBe("1"); // 0 + 1.
-  });
-
-  test("the callback fires when deliver() THROWS (defensive catch → status:error)", async () => {
-    const backend = new FakeBackend();
-    backend.throwOnce = new Error("surprise throw");
-    const out = recorderWithId();
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", { content: "boom", replyTo: "orchestrator" });
-    await until(() => cb.calls.length === 1);
-    expect(cb.calls[0]!.meta.status).toBe("error");
-  });
-
-  test("the callback fires status:error when the outbound write FAILS after retries (reply produced but not delivered)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    // Always-fail outbound (a permanent 4xx → no retry); the reply was produced but lost.
-    const alwaysFail: WriteOutbound = async () => {
-      throw new Error("vault transport: write reply failed (400) bad request");
-    };
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: alwaysFail,
-      writeCallback: cb.fn,
-      outboundRetryBaseMs: 1,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", { content: "x", replyTo: "orchestrator" });
-    await until(() => cb.calls.length === 1);
-    // The orchestrator learns the turn did NOT truly succeed (the reply never landed).
-    expect(cb.calls[0]!.meta.status).toBe("error");
-    expect(cb.calls[0]!.meta.source_message).toBeUndefined(); // the note never landed.
-  });
-
-  test("delegation_depth >= MAX → NO callback (the depth loop guard), turn still runs", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    const out = recorderWithId();
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    // An incoming message already AT the ceiling: a callback would push it over, so suppress.
-    reg.enqueue("worker", {
-      content: "deep",
-      replyTo: "orchestrator",
-      delegationDepth: MAX_DELEGATION_DEPTH,
-    });
-    await until(() => out.calls.length === 1); // the turn STILL ran + replied,
-    await new Promise<void>((r) => setTimeout(r, 5));
-    expect(out.calls).toHaveLength(1);
-    expect(cb.calls).toHaveLength(0); // but the callback was suppressed by the depth guard.
-  });
-
-  test("a message just UNDER the ceiling still gets a callback (boundary)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    const out = recorderWithId();
-    const cb = callbackRecorder();
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: cb.fn,
-    });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", {
-      content: "near-edge",
-      replyTo: "orchestrator",
-      delegationDepth: MAX_DELEGATION_DEPTH - 1,
-    });
-    await until(() => cb.calls.length === 1);
-    expect(cb.calls).toHaveLength(1);
-    expect(cb.calls[0]!.meta.delegation_depth).toBe(String(MAX_DELEGATION_DEPTH)); // the last hop.
-  });
-
-  test("no WriteCallback wired → reply_to is inert (the turn runs normally, no crash)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    const out = recorderWithId();
-    // NOTE: writeCallback intentionally NOT passed.
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: out.fn });
-    await reg.register(specFor("worker"));
-
-    reg.enqueue("worker", { content: "x", replyTo: "orchestrator" });
-    await until(() => out.calls.length === 1);
-    expect(out.calls).toHaveLength(1); // the turn ran fine despite reply_to + no sink.
-  });
-
-  test("a WriteCallback that THROWS does not strand the drain (best-effort, logged)", async () => {
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "done:" + m });
-    const out = recorderWithId();
-    const throwingCb: WriteCallback = async () => {
-      throw new Error("callback delivery boom");
-    };
-    const reg = new ProgrammaticAgentRegistry({
-      backend,
-      writeOutbound: out.fn,
-      writeCallback: throwingCb,
-    });
-    await reg.register(specFor("worker"));
-
-    // Two reply_to messages; the first callback throws — the second turn must still drain.
-    reg.enqueue("worker", { content: "first", replyTo: "orchestrator" });
-    reg.enqueue("worker", { content: "second", replyTo: "orchestrator" });
-    await until(() => out.calls.length === 2);
-    expect(out.calls.map((c) => c.reply)).toEqual(["done:first", "done:second"]);
-  });
-
-  test("CONCURRENCY: N callbacks returning to ONE orchestrator channel drain FIFO, none lost or clobbered", async () => {
-    // The orchestrator-resume story: an orchestrator fires N sub-tasks; each worker's turn
-    // completes and delivers a callback BACK to the orchestrator's channel. Those callbacks
-    // arrive as inbound on the orchestrator's channel and are handled by ITS per-channel
-    // serial drain — one at a time, FIFO, never concurrent (its --resume session carries
-    // state across them). We exercise the DRAIN-SIDE FIFO property directly here (enqueue N
-    // callback-shaped inbound messages on one channel + assert they drain in order, none
-    // lost, the backend never ran two concurrently) — NOT the real vault-IPC delivery path
-    // (callback note → trigger → /api/vault/inbound → emit), which the wiring + vault suites
-    // cover. The serial drain is the same machinery either way, so this pins the invariant.
-    const backend = new FakeBackend();
-    backend.resultFor = (m) => ({ ok: true, reply: "ack:" + m });
-    const out = recorderWithId();
-    const reg = new ProgrammaticAgentRegistry({ backend, writeOutbound: out.fn });
-    await reg.register(specFor("orchestrator"));
-
-    const N = 6;
-    for (let i = 0; i < N; i++) {
-      // A callback inbound carries NO reply_to (terminal) — exactly the shape the daemon
-      // writes. The orchestrator processes each as "a sub-task finished" message.
-      reg.enqueue("orchestrator", { content: `callback-${i}` });
-    }
-    await until(() => backend.calls.length === N);
-    // FIFO: arrival order preserved, NONE lost or duplicated.
-    expect(backend.calls.map((c) => c.message)).toEqual(
-      Array.from({ length: N }, (_, i) => `callback-${i}`),
-    );
-    // The per-channel serial worker never ran two turns at once (the --resume invariant).
-    expect(backend.maxConcurrent).toBe(1);
-    expect(out.calls.map((c) => c.reply)).toEqual(
-      Array.from({ length: N }, (_, i) => `ack:callback-${i}`),
-    );
-  });
-});