@platless/axom-cli 0.1.0

package/dist/workstation/agentSessions.js

@@ -0,0 +1,1628 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { AGENT_WIRE_AUTH_URL_VERSION, AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION, AGENT_WIRE_ORPHAN_OFFER_VERSION, AGENT_WIRE_SESSION_AUTH_METHODS_VERSION, AGENT_WIRE_SESSION_LOST_VERSION, AGENT_WIRE_VERSION, outboundAgentFrameRejection, outboundFailureReply, } from './protocol/agent.js';
+import { DEFAULT_JOURNAL_MAX_BYTES, SessionJournal } from './journal.js';
+import { AGENT_PROBE_TIMEOUT_MS, AgentRefusedSessionError } from './acp/acpAgents.js';
+import { validateWireEvent } from './acp/validate.js';
+/**
+ * 从线上收来的验证预算的绝对上限。
+ *
+ * 服务端今天最长的那个预算是 180s（连接后台预热用的），比它留一截余量,是为了服务端把那个数
+ * 往上调时不必先发一版 daemon —— 预算跟着请求走的全部意义就在这里。但它必须**有**一个上限:
+ * 这个数直接变成一个 `setTimeout`,而在它到期之前,一个卡死的 agent 子进程一直活在用户自己的
+ * 机器上。没有上限，对面一个 bug（或者一个不该信的对面）就能把一个进程钉在那儿钉到 daemon
+ * 重启为止。五分钟不是一个精确的阈值,它只是「久到任何真实的冷启动都够用,短到即使白等也是
+ * 分钟级而不是无限」。
+ *
+ * 注意 {@link AcpAgents.verify} 对 connect 与 `session/new` **各用一次**这个数,所以一次验证
+ * 最坏是它的两倍。这个倍数是刻意留着的:要消掉它就得改 `acpAgents.ts` 里那两段的分账,而服务端
+ * 自己的 `withTimeout` 本来就还在外面兜底。
+ */
+export const MAX_PROBE_TIMEOUT_MS = 300_000;
+/**
+ * 把帧上的预算变成一个能用的毫秒数。
+ *
+ * 缺席 / `null` → {@link AGENT_PROBE_TIMEOUT_MS},即这个字段出现之前逐字相同的行为(**新
+ * daemon 收到老服务端的帧走的就是这条**)。成形但过大 → 夹到 {@link MAX_PROBE_TIMEOUT_MS}。
+ *
+ * 下界不在这里夹，由 `protocol/agent.ts` 的 `isNullableProbeTimeoutMs` 兜住(`> 0` 且有限):
+ * 一个比本地默认还短的预算是**调用方自己**的取舍(想快点失败就快点失败),拦下来只会让 daemon
+ * 单方面推翻一个没有害处的决定;而 `NaN` / 负数不是取舍,是错话,那种帧根本不该被解出来。这里
+ * 仍然把非数一并兜到默认值,是因为本函数也服务于绕过解码器直接构帧的调用者(测试是其一)。
+ */
+export function clampProbeTimeout(requested) {
+    if (typeof requested !== 'number' || !Number.isFinite(requested) || requested <= 0)
+        return AGENT_PROBE_TIMEOUT_MS;
+    return Math.min(requested, MAX_PROBE_TIMEOUT_MS);
+}
+/**
+ * One `agent_prompt` **or `agent_steer`** frame as the ACP `ContentBlock[]` both requests take
+ * (`PromptRequest.prompt`, `types.gen.d.ts:5160`; the steering extension's `parseSteerRequest` takes
+ * the same array and hands it to the same `promptToClaude(params)`).
+ *
+ * **Shared by both on purpose, not merely because the two frames happen to have the same fields.**
+ * A steered message and a prompted one *are* the same message — the reader's text plus whatever
+ * they attached — so assembling them differently is how one of them ends up carrying less than the
+ * other, which is exactly what used to happen while `agent_steer` had no `images` at all.
+ *
+ * **This is the only place a user message is assembled**, which is the point of doing it here
+ * rather than deeper: `acpAgents.ts` used to wrap the frame's `text` into a lone text block, and
+ * that wrapper was structurally incapable of carrying anything else — an image that had been
+ * uploaded, stored, put on the timeline and shown to the reader stopped dead at it, with no error
+ * anywhere.
+ *
+ * Order is text-then-images, matching the frame and matching what the platform's own runtime feeds
+ * its agent, so a bridged and a built-in session present the same message the same way.
+ *
+ * **An empty text block is dropped only when there are images to carry the message instead.** A
+ * reader who attached a picture and typed nothing said nothing, and an empty text part would put
+ * words in their mouth (several vendors reject a zero-length text part outright). With no images
+ * the empty block stays: that is the text-only path every existing bridged conversation runs on,
+ * and it must not shift by a byte.
+ *
+ * The image blocks are forwarded **verbatim** — `ImageBlockWire` is ACP `ImageContent` and its
+ * `data` is base64 on both sides of the tunnel, so nothing here decodes, re-encodes or re-wraps a
+ * payload that is ~10.7 MB for an 8 MiB picture.
+ */
+function promptBlocks(frame) {
+    const images = frame.images ?? [];
+    const text = frame.text.length > 0 || images.length === 0
+        ? [{ type: 'text', text: frame.text }]
+        : [];
+    return [...text, ...images];
+}
+/**
+ * The server's applied-through watermark on an open frame, sanitized. Absent means "nothing yet".
+ *
+ * The finiteness check is load-bearing, not defensive noise: the channel decoder is a bare `JSON.parse`
+ * with no runtime validation, so this field can arrive as a string, an object, or `Infinity`, and
+ * `Math.trunc` turns all of those into `NaN`. Since the value now seeds the seq allocator, a NaN
+ * would make `nextSeq()` return NaN forever and ship every later frame as `seq: null` — the same
+ * permanent, silent wedge the seeding exists to prevent, through a different door. Garbage is read
+ * as "the server has applied nothing", which costs at most a replay of entries it already has (its
+ * own de-duplication drops them).
+ */
+function resumeFromSeqOf(frame) {
+    const seq = Math.trunc(frame.resumeFromSeq ?? 0);
+    return Number.isFinite(seq) ? Math.max(0, seq) : 0;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Batch size for `agent_backfill_events`. Kept modest so a session with a long history does not
+ * arrive as one giant frame; the last batch of a stream is whatever remains below this size.
+ */
+export const BACKFILL_BATCH_SIZE = 64;
+/**
+ * Defensively turns the wire query of `agent_list_native` / `agent_verify` / `agent_authenticate`
+ * — one shape, because all three ask the same thing of an agent that has no session yet: where to
+ * run and how to launch — into an {@link AcpListSpec} (Global Constraint 3
+ * — the channel decoder is a bare `JSON.parse`, so `frame.query` could be missing fields, or missing
+ * entirely, at runtime regardless of what the wire type claims). Returns `null` rather than
+ * fabricating a `cwd` the agent would then list against.
+ *
+ * `cwd` is the only field that must be there. The wire query also carries `shell`, and the deleted
+ * SPI required it because a bridge spawned its listing process through one; an ACP agent is launched
+ * directly from its `command`/`args`, so nothing reads it any more and rejecting a query for the
+ * lack of it would be a refusal on a field this daemon no longer uses.
+ *
+ * `env`/`agentEnv` are optional on the wire but not in the spec, so absent fields become `{}` here —
+ * never passed through as `undefined`.
+ */
+function sanitizeNativeSessionQuery(agentId, query) {
+    if (!query || typeof query.cwd !== 'string' || !query.cwd)
+        return null;
+    return {
+        agentId,
+        cwd: query.cwd,
+        env: query.env ?? {},
+        agentEnv: query.agentEnv ?? {},
+        ...(query.command ? { command: query.command } : {}),
+        args: query.args ?? [],
+    };
+}
+/**
+ * Name an event for a diagnostic without trusting it: on a payload hostile enough that even
+ * `eventName` throws (the validator's 'event not inspectable' case), the log line itself must
+ * still come out.
+ */
+function wireEventName(e) {
+    try {
+        return String(e?.eventName);
+    }
+    catch {
+        return '<uninspectable>';
+    }
+}
+/**
+ * Owns the workstation's live external-agent sessions and translates between the tunnel's
+ * `agent_*` frames and the ACP client.
+ *
+ * Lifetime: one manager per daemon process, constructed outside the reconnect loop — agent sessions
+ * (and the subprocesses behind them) must survive a dropped websocket. The send binding is swapped
+ * per connection via {@link bindSend} / {@link closeAll}.
+ *
+ * Delivery is at-least-once, not best-effort: every outbound event is journaled before it is sent
+ * ({@link SessionJournal}), so a send that goes nowhere — socket down, or the daemon restarted
+ * entirely — is replayed when the server re-opens the ref with its `resumeFromSeq` watermark.
+ */
+export class AgentSessionManager {
+    agents;
+    journalDir;
+    maxJournalBytes;
+    tasks;
+    sessions = new Map();
+    /** In-flight opens, keyed by sessionRef, so two racing agent_open frames cannot spawn two agents. */
+    opening = new Map();
+    /**
+     * Refs whose open became pointless while the agent was still starting — either an
+     * `agent_close` arrived for a ref that had no live session yet, or the socket dropped (the server
+     * fails its pending open with ok:false and will never adopt the result). Without this, the native
+     * agent that finishes spawning afterwards is orphaned: alive, registered, and unknown to the
+     * server. {@link openSession} closes and discards any session whose ref is tombstoned, and uses
+     * the recorded {@link AbandonReason} to decide whether the journal dies with it.
+     */
+    closedDuringOpen = new Map();
+    /**
+     * Refs whose journal is still being torn down, and the promise that says when it is gone.
+     *
+     * A close and the reopen of the same ref are two independent inbound frames — the daemon does not
+     * serialize `handleFrame` (see daemon.ts's `ws.on('message', async …)`) — and `onClose` returns the
+     * ref to the "openable" state the moment it drops out of `sessions`, while the actual `destroy()`
+     * is still queued behind that session's pending writes. Letting the reopen build a second
+     * {@link SessionJournal} on the same path in that window is a data-loss race in both directions:
+     * the old `destroy()` can land after the new journal's first append and delete it, or the new
+     * `init()` can read a file the old `destroy()` then removes, leaving the new journal with a stale
+     * size and a seq counter recovered from bytes that no longer exist. The two instances also share a
+     * `.tmp` path, so a rewrite in one can be pulled out from under the other.
+     *
+     * {@link openSession} waits on this before constructing anything.
+     */
+    retiring = new Map();
+    /**
+     * sessionRefs swept while no v2-capable sender was bound. The sweep cannot un-reclaim them, but a
+     * server that still holds those refs only ever learns it from here — see {@link notifySwept}.
+     */
+    sweptWhileUnsent = [];
+    send;
+    /**
+     * How many frames `emit` has dropped since the sender went null, and when the mute began.
+     *
+     * Dropping while unbound is by design -- live events are replayed from the journal and pending
+     * requests are failed server-side -- but the *dangerous* variant is indistinguishable from the
+     * benign one without a record: a mute that never ends leaves the supervisor reporting CONNECTED
+     * while nothing reaches the server (see `closeAll`). One line at the start of the mute and one
+     * at its end make the two shapes tell apart in a log after the fact: a benign mute is a pair,
+     * a wedged one is an opening line with no partner.
+     */
+    mutedDrops = 0;
+    mutedSinceMs = null;
+    /**
+     * The agent-wire version the *server* advertised on the current connection. Frames introduced
+     * after v1 are only sent when it is high enough: an older server cannot decode the discriminator
+     * and drops the whole connection on receiving one.
+     *
+     * Defaults to this build's own version so a manager constructed without a connection (tests, the
+     * pre-`ready` window) behaves as fully capable rather than silently muting the notice.
+     */
+    serverAgentWire = AGENT_WIRE_VERSION;
+    /**
+     * One abort handle per login still running detached, so {@link closeAll} can end them.
+     *
+     * A login is the one piece of work here that outlives its own reply: it holds an agent subprocess
+     * for as long as a person takes in a browser, bounded only by `AGENT_LOGIN_CEILING_MS` (ten
+     * minutes). Sessions deliberately survive a dropped socket because a reconnect resumes them — a
+     * login cannot: its URL reaches the reader only as `agent_auth_url`, and {@link emit} drops every
+     * frame while the sender is unbound. So a login that outlives the disconnect is a subprocess
+     * running for a card nobody will ever see.
+     */
+    loginsInFlight = new Set();
+    constructor(
+    /** The one ACP client every external agent runs through; keyed per call by registry agent id. */
+    agents, send, 
+    /** Root for per-session journals; they live under `<journalDir>/sessions`. */
+    journalDir, 
+    /** Per-session journal cap. Beyond it the oldest half is dropped and the server told about the hole. */
+    maxJournalBytes = DEFAULT_JOURNAL_MAX_BYTES, 
+    /** Shared update admission and force-cancellation authority, when this daemon supports updates. */
+    tasks) {
+        this.agents = agents;
+        this.journalDir = journalDir;
+        this.maxJournalBytes = maxJournalBytes;
+        this.tasks = tasks;
+        this.send = send;
+    }
+    /** Where journals live: `<journalDir>/sessions/<sessionRef>.jsonl`. */
+    get sessionsDir() {
+        return path.join(this.journalDir, 'sessions');
+    }
+    /** Number of daemon-owned external-agent sessions, for the management heartbeat projection. */
+    activeSessionCount() {
+        return [...this.sessions.values()].filter((session) => !session.closed).length;
+    }
+    /** Snapshot advertised once after an agent-channel reconnect; the server remains replay authority. */
+    /**
+     * The reconnect inventory: the sessions this daemon holds, plus the journals a previous daemon
+     * life left on disk.
+     *
+     * **The orphan half is what makes recovery automatic.** A journal whose agent is gone -- the
+     * daemon restarted, or the machine rebooted -- is not in {@link sessions}, so before this it
+     * appeared in no inventory at all, and the server (which ends a live turn precisely because its
+     * ref is *missing* from the offer) ended it. The file had not been lost; nobody had ever been told
+     * it was there. It would sit on disk until the user happened to speak to that session again.
+     *
+     * **Orphans carry `journalMaxSeq: 0`, and that is not a placeholder for a number worth reading.**
+     * The server drives an orphan off `agentAlive` and its own live-turn ledger, never off a watermark
+     * comparison, so nothing reads the field. Filling it honestly would mean a `SessionJournal.init`
+     * per file -- each one reads the whole file, up to 64 MB -- on every agent-channel reconnect, to
+     * produce a number that is then discarded.
+     *
+     * **Gated on {@link AGENT_WIRE_ORPHAN_OFFER_VERSION}, and that gate is load-bearing** in a way the
+     * heartbeat-inventory floor is not: this widens the meaning of an existing list whose absence the
+     * server acts on. A server below the floor would read an orphan as a ref the client still holds,
+     * stop ending its turn, and never reopen it -- leaving it RUNNING forever, which is worse than the
+     * honest failure it produces today.
+     */
+    async resumeOfferSessions() {
+        const live = this.liveInventory();
+        if (this.serverAgentWire < AGENT_WIRE_ORPHAN_OFFER_VERSION)
+            return live;
+        // Every ref this daemon still has a handle on, not merely the ones it would report as live:
+        // a ref that is mid-open, mid-retire, or closed-but-not-yet-forgotten is one we are still the
+        // owner of, and announcing it as abandoned invites a reopen against a session we hold.
+        const held = new Set([...this.sessions.keys(), ...this.opening.keys(), ...this.retiring.keys()]);
+        const orphans = await this.orphanedJournalRefs(held);
+        // `turnRunning: false` is an observation here, not a default: an orphan has no agent process at
+        // all, so there is nothing that could be running on it.
+        return [
+            ...live,
+            ...orphans.map((sessionRef) => ({ sessionRef, journalMaxSeq: 0, agentAlive: false, turnRunning: false })),
+        ];
+    }
+    /**
+     * Journal files on disk whose ref this daemon holds no handle for.
+     *
+     * Reads names only -- never contents. A directory that does not exist is the ordinary state of a
+     * daemon that has never opened a session, so it is not a warning; anything else is, but it still
+     * degrades to "offer what we hold" rather than failing the whole offer, because losing the live
+     * half of the inventory would be a far bigger regression than missing the orphan half.
+     */
+    async orphanedJournalRefs(held) {
+        let names;
+        try {
+            names = await fs.readdir(this.sessionsDir);
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT') {
+                console.warn(`[agent] listing journals for the resume offer failed: ${errorMessage(error)}`);
+            }
+            return [];
+        }
+        const refs = [];
+        for (const name of names) {
+            if (!name.endsWith('.jsonl'))
+                continue;
+            let ref;
+            try {
+                ref = decodeURIComponent(name.slice(0, -'.jsonl'.length));
+            }
+            catch {
+                // Not a name this daemon wrote (`encodeURIComponent` never emits a malformed escape), so
+                // there is no ref behind it to offer.
+                continue;
+            }
+            if (!held.has(ref))
+                refs.push(ref);
+        }
+        // readdir order is filesystem-defined; the offer should not be.
+        return refs.sort();
+    }
+    /**
+     * The live half, shared with the heartbeat -- which must stay synchronous and touch no disk.
+     *
+     * `agentAlive` and `turnRunning` are sampled from the agent itself at the moment this is called
+     * (see {@link AgentSessionLiveness}), never from anything this manager recorded earlier. A
+     * session whose agent died while this daemon kept running therefore reports `agentAlive: false`
+     * here, and lands in exactly the same server-side branch as a journal left by a previous daemon
+     * life -- which is the point: "the agent is gone" is one fact with one handling, not a special
+     * case per way of getting there.
+     */
+    liveInventory() {
+        return [...this.sessions.values()]
+            .filter((session) => !session.closed)
+            .map((session) => {
+            const liveness = session.session.liveness;
+            return {
+                sessionRef: session.sessionRef,
+                journalMaxSeq: session.journal.lastSeq,
+                agentAlive: liveness.agentAlive,
+                turnRunning: liveness.turnRunning,
+            };
+        });
+    }
+    /**
+     * The same inventory, for the heartbeat that goes out every ten seconds.
+     *
+     * **Why the periodic copy exists at all.** The reconnect offer is sent once, right after the
+     * handshake, so it can only ever catch a divergence that already existed at that moment. One that
+     * opens afterwards — on a connection that stays up, with the workstation reporting ONLINE — had no
+     * observer: this journal reached seq 885 while the server's `bridge_seq` sat at 689 for four
+     * minutes, and neither side raised anything, because {@link emit} is a silent no-op on an unbound
+     * sender and the server's dispatcher returns for a ref it has no handler for. The two numbers were
+     * both already known; nothing was comparing them after the handshake.
+     *
+     * Returns `undefined` rather than `[]` when there is nothing to say, so the heartbeat frame stays
+     * byte-identical to the one this client has always sent:
+     *
+     * - the server predates the field ({@link AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION}) and would
+     *   discard it — it is ignored, not rejected, but ten seconds of overhead forever is worth
+     *   skipping;
+     * - or this daemon holds no live session, which is most of the time.
+     */
+    heartbeatInventory() {
+        if (this.serverAgentWire < AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION)
+            return undefined;
+        const sessions = this.liveInventory();
+        return sessions.length > 0 ? sessions : undefined;
+    }
+    /**
+     * Bind (or rebind, after a reconnect) the outbound frame sink, along with the agent-wire version
+     * the server advertised on this connection — the version is per-connection, so it is rebound with
+     * the sender rather than set once.
+     */
+    bindSend(send, serverAgentWire = AGENT_WIRE_VERSION) {
+        if (this.mutedDrops > 0) {
+            const seconds = this.mutedSinceMs === null ? '?' : ((Date.now() - this.mutedSinceMs) / 1000).toFixed(1);
+            console.warn(`[agent] sender rebound after ${seconds}s unbound; ${this.mutedDrops} frame(s) were dropped while muted`);
+        }
+        this.mutedDrops = 0;
+        this.mutedSinceMs = null;
+        this.send = send;
+        this.serverAgentWire = serverAgentWire;
+        // Before any inbound frame on this connection can be answered: a sweep notice that arrived here
+        // after the server had already re-opened its ref would invalidate a healthy generation.
+        this.flushSwept();
+    }
+    /**
+     * Called when the websocket drops. Despite the name, this does **not** close agent sessions — the
+     * agent subprocesses keep running so a reconnect can resume them. What it does is unbind the
+     * sender, tombstone in-flight opens, and end in-flight *logins*.
+     *
+     * Events produced while unbound are journaled and their `send` is a no-op; the server gets them
+     * back when it re-opens the ref with a `resumeFromSeq`.
+     *
+     * A login is the one piece of work here that cannot survive the drop, which is why it is the one
+     * thing this really does end: its URL reaches the reader only as `agent_auth_url`, and that frame
+     * is not journaled the way session events are, so one emitted while unbound is gone rather than
+     * replayed — leaving an agent subprocess held open, for up to `AGENT_LOGIN_CEILING_MS`, for a card
+     * nobody will ever see. See {@link loginsInFlight}, and the comment at the abort itself for why it
+     * is scoped to the teardown that actually unbinds.
+     *
+     * In-flight opens are the other exception: the server fails its pending open with ok:false on
+     * disconnect, so a session that finishes spawning after this point would be orphaned. Those refs
+     * are tombstoned and the resulting bridge session is closed on arrival — but as `disconnected`,
+     * which keeps the journal: the server is coming back for it.
+     */
+    closeAll(boundSender) {
+        // Unbinding is scoped to the connection that did the binding. The sender is one shared slot on
+        // a manager that deliberately outlives every socket, so an unconditional `this.send = null`
+        // makes correctness depend on a global ordering argument -- that no connection's teardown can
+        // ever settle after a newer one has bound. Losing that race does not fail loudly: it leaves the
+        // manager permanently muted while the supervisor still reports the agent channel CONNECTED, and
+        // every event from then on is journaled and silently dropped, which is precisely the shape of
+        // the failure this whole change exists to make impossible. Comparing identities makes the
+        // invariant local, so no ordering argument has to hold.
+        //
+        // The argument-less call still unbinds unconditionally, for callers that own the only binding
+        // (tests, and a shutdown path with no reconnect behind it).
+        //
+        // The tombstoning below is deliberately *not* scoped: an in-flight open is abandoned by the
+        // server the moment any connection it was issued on drops, so it must be marked regardless of
+        // which sender is current -- otherwise an agent that finishes spawning afterwards is left alive,
+        // registered, and unknown to the server.
+        if (boundSender === undefined || this.send === boundSender) {
+            this.send = null;
+            // Logins are the exception to "sessions keep running" — see {@link loginsInFlight}. Scoped to
+            // the teardown that actually unbinds, unlike the tombstoning below: if a newer connection has
+            // already rebound, this login's frames still have somewhere to go and killing it would be
+            // gratuitous. When nothing is bound, they do not: `agent_auth_url` is not journaled the way
+            // session events are, so a URL emitted while unbound is gone for good rather than replayed —
+            // which leaves an agent subprocess running for a card nobody will ever see.
+            for (const login of [...this.loginsInFlight])
+                login.abort();
+        }
+        for (const sessionRef of this.opening.keys()) {
+            // Never downgrade an explicit close into a disconnect: that would strand the journal.
+            if (!this.closedDuringOpen.has(sessionRef))
+                this.closedDuringOpen.set(sessionRef, 'disconnected');
+        }
+    }
+    /**
+     * Awaits every queued journal write and the send behind it. Used by tests, and available to a
+     * shutdown path that wants events on disk before the process exits.
+     *
+     * Bounded on purpose. A session that is actively streaming keeps appending to its own chain, so
+     * "wait until nothing is queued" has no fixed point while an agent is talking — an unbounded loop
+     * would hang the very shutdown it is meant to serve. After `maxRounds` passes it returns with work
+     * possibly still queued; a caller that needs a true quiesce must stop the source first (the
+     * agent's `close()`, or at least {@link closeAll}).
+     */
+    async drain(maxRounds = 50) {
+        for (let round = 0; round < maxRounds; round += 1) {
+            let progressed = false;
+            for (const live of [...this.sessions.values()]) {
+                const chain = live.writes;
+                await chain;
+                if (live.writes !== chain)
+                    progressed = true;
+            }
+            if (!progressed)
+                return;
+        }
+    }
+    async handleFrame(frame) {
+        switch (frame.t) {
+            case 'agent_open': {
+                const admission = this.reserveOpen(frame.id, frame.sessionRef);
+                if (admission === 'rejected')
+                    return;
+                try {
+                    await this.onOpen(frame);
+                }
+                finally {
+                    if (admission === 'reserved')
+                        this.tasks?.agentOpenFinished(frame.sessionRef);
+                }
+                return;
+            }
+            case 'agent_prompt': {
+                const live = this.routableSession(frame.sessionRef, 'prompt');
+                if (!live)
+                    return;
+                if (this.tasks && !this.tasks.agentTurnStarted(frame.sessionRef)) {
+                    // No `authMethods` here, deliberately, even though this is a failed turn on a session
+                    // whose agent we have certainly connected to: the prompt never reached that agent, so
+                    // nothing about credentials is being reported. This frame is built here rather than in
+                    // `onAgentTurnDone`, so it never passes the {@link TurnResult.agentRefused} gate — the
+                    // omission is structural, not a line someone has to remember.
+                    this.record(live, (seq) => ({
+                        t: 'agent_turn_done', sessionRef: frame.sessionRef, seq, status: 'failed',
+                        error: 'Workstation is not accepting new work',
+                    }));
+                    return;
+                }
+                live.session.prompt(promptBlocks(frame));
+                return;
+            }
+            case 'agent_answer': {
+                const live = this.routableSession(frame.sessionRef, 'answer');
+                live?.session.answer(frame.requestId, frame.outcome);
+                return;
+            }
+            case 'agent_interrupt': {
+                const live = this.routableSession(frame.sessionRef, 'interrupt');
+                if (!live)
+                    return;
+                try {
+                    await live.session.interrupt();
+                }
+                catch (err) {
+                    console.error(`[agent] interrupt failed for ${frame.sessionRef}: ${errorMessage(err)}`);
+                }
+                return;
+            }
+            /**
+             * A steer rides a turn that is **already** running, so it is deliberately not bracketed by
+             * `tasks.agentTurnStarted` / `agentTurnFinished` the way `agent_prompt` is: the agent still
+             * answers exactly one `session/prompt` and still sends exactly one `agent_turn_done`, so
+             * there is no second completion to close a second bracket with.
+             *
+             * The leak that would open is not hypothetical. The server steers whenever **it** believes a
+             * turn is running, and the agent is free to disagree and answer `promptRequired` — a steer on
+             * an idle session. Nothing will ever send a `turn_done` for that one, so the sessionRef would
+             * sit in `TaskRegistry`'s agent-task set forever and `canUpdate()` would be false for the rest
+             * of this daemon's life. Same shape as the hung-prompt leak `readLoopDead` exists for.
+             *
+             * Every exit answers. The server is holding the steered message in its own queue table
+             * (`session_message_queue`) while this request is in flight — the message is not on the
+             * timeline at all, and carries no "queued" mark: a `user_message` item exists only once some
+             * round (or a successful steer) has consumed it. Only the reply tells the server whether to
+             * keep holding that row or to deliver it the ordinary way. A silent drop parks it forever.
+             */
+            case 'agent_steer': {
+                const live = this.routableSession(frame.sessionRef, 'steer');
+                if (!live) {
+                    this.emit({ t: 'agent_steered', id: frame.id, ok: false, error: `no live session '${frame.sessionRef}'` });
+                    return;
+                }
+                try {
+                    this.emit({
+                        t: 'agent_steered',
+                        id: frame.id,
+                        ok: true,
+                        // The whole message, images and all, assembled by the same function `agent_prompt` uses
+                        // — see {@link promptBlocks}. `frame.priority` is passed through untouched, `undefined`
+                        // included: absent means the server named no timing, and inventing one here would be
+                        // this daemon deciding something the server deliberately left unsaid.
+                        outcome: await live.session.steer(promptBlocks(frame), frame.priority),
+                    });
+                }
+                catch (err) {
+                    // Includes the `Method not found` an agent that never advertised the extension answers
+                    // with, and the `startedNewTurn` refusal from `mapSteerOutcome`. Both are the server's to
+                    // recover from — it degrades to an ordinary queued delivery — so they travel, not hide.
+                    this.emit({ t: 'agent_steered', id: frame.id, ok: false, error: errorMessage(err) });
+                }
+                return;
+            }
+            /**
+             * Set one session config option, round-tripping ACP `session/set_config_option`. Same shape
+             * as `agent_steer` immediately above, and for the same reason: this is a real round trip the
+             * server is blocked waiting on, not a turn, so it is not bracketed by
+             * `tasks.agentTurnStarted` / `agentTurnFinished` — there is no second completion to close a
+             * second bracket with, and a bracket opened here would never close, leaking the ref for the
+             * life of the daemon.
+             *
+             * Every exit answers: a session that is not routable, an agent that throws (its own refusal,
+             * or `Method not found` from one that never advertised the method), all send
+             * `agent_config_option_set` with `ok: false` and the error. A silent drop parks the server on
+             * a request that never resolves.
+             */
+            case 'agent_set_config_option': {
+                const live = this.routableSession(frame.sessionRef, 'set_config_option');
+                if (!live) {
+                    this.emit({ t: 'agent_config_option_set', id: frame.id, ok: false, error: `no live session '${frame.sessionRef}'` });
+                    return;
+                }
+                try {
+                    const configOptions = await live.session.setConfigOption(frame.configId, frame.value);
+                    this.emit({ t: 'agent_config_option_set', id: frame.id, ok: true, configOptions });
+                }
+                catch (err) {
+                    // Includes the agent's own refusal ("Invalid value…", "Unknown config option…") and a
+                    // `Method not found` from an agent without the method — both are the server's to show.
+                    this.emit({ t: 'agent_config_option_set', id: frame.id, ok: false, error: errorMessage(err) });
+                }
+                return;
+            }
+            case 'agent_close':
+                await this.onClose(frame.sessionRef);
+                return;
+            case 'agent_event_ack': {
+                // An ack for a ref we no longer hold is normal (close and ack cross on the wire), so unlike
+                // the control frames above this one is dropped silently.
+                const live = this.liveSession(frame.sessionRef);
+                if (!live)
+                    return;
+                this.touch(live);
+                await this.enqueue(live, () => live.journal.truncateThrough(frame.throughSeq));
+                return;
+            }
+            case 'agent_list_native':
+                if (this.tasks && !this.tasks.accepting) {
+                    this.emit({ t: 'agent_native_sessions', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
+                    return;
+                }
+                await this.onListNative(frame);
+                return;
+            // Both of these spawn an agent subprocess, exactly as `agent_list_native` does, so they answer
+            // a draining workstation the same way rather than starting work it is trying to finish.
+            case 'agent_verify':
+                if (this.tasks && !this.tasks.accepting) {
+                    this.emit({ t: 'agent_verified', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
+                    return;
+                }
+                await this.onVerify(frame);
+                return;
+            case 'agent_authenticate':
+                if (this.tasks && !this.tasks.accepting) {
+                    this.emit({ t: 'agent_authenticated', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
+                    return;
+                }
+                await this.onAuthenticate(frame);
+                return;
+            // Downloads a package; starts nothing. Still refused while draining, because a workstation on
+            // its way down should not begin a multi-megabyte fetch it will be killed in the middle of.
+            case 'agent_install':
+                if (this.tasks && !this.tasks.accepting) {
+                    this.emit({ t: 'agent_installed', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
+                    return;
+                }
+                await this.onInstall(frame);
+                return;
+            default:
+                // Not an agent frame (or an outbound-only one) — the daemon routes those elsewhere.
+                return;
+        }
+    }
+    /**
+     * Classifies an open before its first await. A live or already-opening ref is continuation
+     * traffic, so graceful drain lets it replay/piggyback without acquiring (and later releasing)
+     * another reservation. Force-stop is different: it is destructive shutdown and rejects every
+     * open, including reconnects. A ref absent from both maps is genuinely new work and still needs
+     * the ordinary TaskRegistry admission reservation.
+     */
+    reserveOpen(openId, sessionRef) {
+        if (!this.tasks)
+            return 'continuation';
+        if (this.tasks.isForceStopping()) {
+            this.emit({ t: 'agent_opened', id: openId, ok: false, error: 'Workstation is not accepting new work' });
+            return 'rejected';
+        }
+        if (this.liveSession(sessionRef) || this.opening.has(sessionRef))
+            return 'continuation';
+        if (this.tasks.tryReserveAgentOpen(sessionRef))
+            return 'reserved';
+        this.emit({ t: 'agent_opened', id: openId, ok: false, error: 'Workstation is not accepting new work' });
+        return 'rejected';
+    }
+    /**
+     * Everything a failure frame says about a refusal **the agent itself** produced: the sign-in table
+     * it advertised, and the JSON-RPC code it answered with.
+     *
+     * ## One helper, because the reader makes one decision
+     *
+     * The server draws a login card only when the code is ACP's `auth_required` *and* the table is
+     * non-empty. Emitting the two from separate places is how the card's contents and the decision to
+     * draw it drift apart while each looks right, so the two keys are produced together, gated
+     * together, and every call site passes both or neither.
+     *
+     * ## Absent is not empty, and not zero
+     *
+     * Spread rather than assigned, because absent and `[]` are different answers and the card turns on
+     * the difference: `[]` says the agent was reached and advertised no way to sign in, absent says
+     * nobody has connected to it (or this server would not read the field anyway). A `?? []` anywhere
+     * on this path would collapse the two and make every cold daemon look like an agent with no login.
+     * `errorCode` is spread for the same reason — a refusal that was not a JSON-RPC one has no code,
+     * and `0` is a code.
+     *
+     * `agentId` is the **registry agent id** (`agent_open.bridge`, `LiveSession.agentId`), never the
+     * workstation's configured entry name: `AcpAgents.observed` is keyed by the former, so keying by
+     * the latter would report "never connected" for every session ever opened.
+     *
+     * The version check is a "worth sending" floor, not a compatibility gate — see
+     * {@link AGENT_WIRE_SESSION_AUTH_METHODS_VERSION}, which spells out why this one is unlike the
+     * login frames'. Both keys sit behind that one check because neither was worth a version of its
+     * own — **not** because they always go out together. The two spreads below are independent, and a
+     * refusal the agent made outside JSON-RPC really does emit the table with no code. The server is
+     * right to refuse that a login anyway: `auth_required` is a code, so a refusal without one is a
+     * different refusal.
+     */
+    refusalFields(agentId, errorCode) {
+        if (this.serverAgentWire < AGENT_WIRE_SESSION_AUTH_METHODS_VERSION)
+            return {};
+        const methods = this.agents.observedAuthMethods(agentId);
+        return {
+            ...(methods ? { authMethods: methods } : {}),
+            ...(errorCode !== undefined ? { errorCode } : {}),
+        };
+    }
+    liveSession(sessionRef) {
+        const live = this.sessions.get(sessionRef);
+        return live && !live.closed ? live : undefined;
+    }
+    /**
+     * Resolve a session for an inbound control frame, warning — and telling the server — when there is
+     * none.
+     *
+     * A silent drop here reads downstream as "the agent ignores me", so the daemon log must say what
+     * was discarded. But a log line on this machine is not enough: the server's own state still looks
+     * healthy (its applier is registered, the websocket never dropped), so it reuses that applier and
+     * keeps sending into a session that is gone. The user's message disappears with no reply, and so
+     * does every message after it. {@link reportSessionLost} is what makes that divergence
+     * self-healing — one frame is lost, and the user is told.
+     */
+    routableSession(sessionRef, action) {
+        const live = this.liveSession(sessionRef);
+        if (!live) {
+            console.warn(`[agent] dropped ${action} for unknown session '${sessionRef}'`);
+            this.reportSessionLost(sessionRef, action);
+        }
+        else
+            this.touch(live);
+        return live;
+    }
+    /**
+     * Tell the server this daemon holds no session for `sessionRef`, so it can retire its own state
+     * and fail the round instead of talking into a void.
+     *
+     * Two conditions suppress it, both to avoid making things worse than the silent drop:
+     *
+     * - **The server is older than the frame.** Its channel decoder fails on an unknown discriminator
+     *   and the gateway loop breaks, so sending this to a v1 server would take down the whole
+     *   multiplexed connection — every session, exec and heartbeat on this workstation.
+     * - **The ref is still opening.** The session genuinely exists (or is about to); the frame is lost
+     *   either way, but reporting it would have the server void a generation it is in the middle of
+     *   establishing. The server does not send control frames before `agent_opened`, so this is a
+     *   belt-and-braces guard rather than a live path.
+     */
+    reportSessionLost(sessionRef, action) {
+        if (this.serverAgentWire < AGENT_WIRE_SESSION_LOST_VERSION)
+            return;
+        if (this.opening.has(sessionRef))
+            return;
+        this.emit({ t: 'agent_session_lost', sessionRef, action });
+    }
+    /** The action a sweep reports under: no user input was lost, so the server's card logic must
+     * read it as "invalidate your state" rather than "tell the user to resend". */
+    static SWEEP_LOST_ACTION = 'sweep';
+    /** Bounds {@link sweptWhileUnsent} against a server that stays below the frame's wire version
+     * across reconnect after reconnect — the notices cost the server nothing to miss. */
+    static SWEEP_LOST_QUEUE_CAP = 128;
+    /**
+     * The sweep-side sibling of {@link reportSessionLost}: the ref went away on the timer, not under
+     * a dropped frame, so the server can retire its state *before* the user's next message runs into
+     * the hole instead of after. With this notice the divergence heals invisibly — ensureOpen re-opens
+     * with the persisted nativeSessionId, the conversation continues — and the lazy reply stays as
+     * the fallback for every path this cannot reach.
+     *
+     * Unlike the lazy reply this one must survive an unbound sender: the sweep fires precisely when
+     * nobody is talking, which is disproportionately *also* when the socket is down — a laptop that
+     * slept through its own deadline. An unsent notice therefore queues (bounded by
+     * {@link SWEEP_LOST_QUEUE_CAP}) and rides the next connection; see {@link flushSwept}.
+     */
+    notifySwept(sessionRef) {
+        if (this.send !== null && this.serverAgentWire >= AGENT_WIRE_SESSION_LOST_VERSION) {
+            this.reportSessionLost(sessionRef, AgentSessionManager.SWEEP_LOST_ACTION);
+            return;
+        }
+        if (this.sweptWhileUnsent.length >= AgentSessionManager.SWEEP_LOST_QUEUE_CAP) {
+            const dropped = this.sweptWhileUnsent.shift();
+            console.warn(`[agent] sweep notice for '${dropped}' dropped: queue capped at ${AgentSessionManager.SWEEP_LOST_QUEUE_CAP}`);
+        }
+        this.sweptWhileUnsent.push(sessionRef);
+    }
+    /** Delivers every sweep notice the queue held, on the first connection able to carry them. */
+    flushSwept() {
+        if (this.sweptWhileUnsent.length === 0)
+            return;
+        if (this.send === null || this.serverAgentWire < AGENT_WIRE_SESSION_LOST_VERSION)
+            return;
+        for (const sessionRef of this.sweptWhileUnsent.splice(0)) {
+            this.reportSessionLost(sessionRef, AgentSessionManager.SWEEP_LOST_ACTION);
+        }
+    }
+    /**
+     * Records a sign of life. Reads the wall clock on purpose: it is the *stamping* that needs the
+     * real time, while {@link sweepIdle} is handed `now` by its caller so its behaviour stays
+     * testable without waiting six hours.
+     */
+    touch(live) {
+        live.lastActivityAt = Date.now();
+    }
+    /**
+     * Closes every session that has neither received a server frame nor produced an event within
+     * `ttlMs` of `now`, and returns their sessionRefs.
+     *
+     * This is the last line of defence for orphaned agent subprocesses. The server's session
+     * table is in memory: after a server restart it knows nothing of the sessions this workstation
+     * still holds, so their `agent_close` is never sent — and a workstation that was offline when a
+     * run was archived never hears the close either. Without this sweep those agent processes live
+     * until the daemon is restarted, holding their cwd, their model quota and whatever they were
+     * mid-way through.
+     *
+     * `now` is a parameter rather than a clock read so the sweep is deterministic under test.
+     * The teardown is deliberately the same one `agent_close` performs ({@link retire}) — a swept
+     * session must leave nothing behind that a later frame could resurrect — with one deliberate
+     * exception: **the journal survives**.
+     *
+     * That exception is the difference between `agent_close` and this sweep. `agent_close` is the
+     * server saying "I am done with this ref", so its journal can never be asked for again. A sweep is
+     * unilateral: the server has not asked for anything and may well re-open the ref with a
+     * `resumeFromSeq` the moment it next hears from the user. The sweep also fires precisely when a
+     * journal is most likely to be holding undelivered output — the workstation was offline past the
+     * TTL (a laptop shut overnight), so a turn that finished while the socket was down is journaled
+     * and unsent. Destroying it there loses that turn outright, and `droppedOldest` is per-instance so
+     * not even a transport-gap card would mark the hole. The same distinction already exists one layer
+     * up as {@link AbandonReason}; a sweep is `disconnected`-shaped, not `closed`-shaped. Kill the
+     * process, keep the file.
+     *
+     * Each sweep also reports itself to the server ({@link notifySwept}) so its stale session state is
+     * retired before the next user message runs into it, rather than after — the sweep heals the
+     * daemon's side of the divergence; the notice heals the server's.
+     */
+    async sweepIdle(ttlMs, now) {
+        const idle = [...this.sessions.values()].filter((live) => now - live.lastActivityAt >= ttlMs);
+        // Snapshot first: retire() mutates `sessions`, and it awaits.
+        for (const live of idle) {
+            await this.retire(live, 'keep');
+            // Reported once the teardown has settled: nothing is gained by a notice that outruns the kill,
+            // and a reopen racing the retire would only park on `retiring`. The daemon-side frame drop
+            // already covers any server frame that lands in the gap.
+            this.notifySwept(live.sessionRef);
+        }
+        return idle.map((live) => live.sessionRef);
+    }
+    async onOpen(frame) {
+        // Reconnect / duplicate open: reuse the live session as-is and replay what the server
+        // still misses.
+        const existing = this.liveSession(frame.sessionRef);
+        if (existing) {
+            // Reusing a live session: neither the process nor the native session moved.
+            await this.resumeAndReply(existing, frame, false);
+            // The session already exists, so any history it has was already streamed under whichever
+            // open first established it (or never will be, if that open didn't ask for it) — replaying it
+            // again here would duplicate what the platform already holds. But if THIS frame asked for
+            // backfill, the server is waiting on exactly one `agent_backfill_done` for THIS open's id:
+            // silence is not "no", it is a wait that never resolves. Answer it without replaying.
+            this.replyNoReplayNeeded(frame);
+            return;
+        }
+        const inFlight = this.opening.get(frame.sessionRef);
+        if (inFlight) {
+            // Piggyback on the attempt already running, and report its real failure — not a generic one.
+            const { live, error, agentRefused } = await inFlight;
+            if (live) {
+                // Piggybacking on the attempt already running: a non-null `live` means that attempt was a
+                // real open (`session/load` or `session/new`), which this frame is reporting secondhand.
+                await this.resumeAndReply(live, frame, true);
+                // Same reasoning as the reconnect branch above: whichever frame actually drove openSession
+                // already streamed this session's history (if it asked to); this frame is a second, racing
+                // open of the same ref and must not trigger a second replay — but still owes its own
+                // `agent_backfill_done` if it asked for one.
+                this.replyNoReplayNeeded(frame);
+            }
+            else {
+                this.emit({
+                    t: 'agent_opened', id: frame.id, ok: false, error: error ?? 'concurrent open failed',
+                    // This frame is a second, racing open of a ref whose attempt already ran; it reports that
+                    // attempt's real failure, so it reports that attempt's agent's sign-in methods and that
+                    // attempt's own error code — keyed by the id the outcome carries, never by this frame's
+                    // own `bridge`, which is a different agent the moment two opens race on one ref with
+                    // different bridges.
+                    ...(agentRefused ? this.refusalFields(agentRefused.agentId, agentRefused.errorCode) : {}),
+                });
+            }
+            return;
+        }
+        const attempt = this.openSession(frame)
+            .catch((err) => ({ live: null, error: errorMessage(err) }));
+        this.opening.set(frame.sessionRef, attempt);
+        let outcome;
+        try {
+            outcome = await attempt;
+        }
+        finally {
+            this.opening.delete(frame.sessionRef);
+            // Clear the tombstone on EVERY exit, not just openSession's success path: an open that was
+            // tombstoned and then failed (ENOENT, bad resume) would otherwise leave the mark behind, and
+            // the next legitimate open of this ref would spawn a real agent only to be killed by it.
+            // Safe to do here: openSession consumes the tombstone before its promise resolves, and only
+            // microtasks separate that from this finally, so no inbound frame can interleave.
+            this.closedDuringOpen.delete(frame.sessionRef);
+        }
+        // Replay-then-reply happens AFTER the finally on purpose. It awaits disk I/O, which yields to
+        // the event loop; if it ran inside the try, the ref would sit in `sessions` and `opening` at
+        // once and an inbound agent_close could observe both. onClose checks `opening` first, so it
+        // would tombstone an already-registered session — and the finally above would then wipe the
+        // tombstone without anything ever closing it. Nothing but microtasks separates `attempt`
+        // resolving from the finally, and microtasks always drain before the next inbound frame.
+        if (outcome.live) {
+            // openSession returned successfully, having just done session/load or session/new.
+            await this.resumeAndReply(outcome.live, frame, true);
+            // Only the direct-attempt path: the existing-session and in-flight-piggyback branches above
+            // return before reaching here, so a racing duplicate `agent_open` (or a reconnect of an
+            // already-open ref) can never trigger a second replay of the same history.
+            if (frame.backfill)
+                await this.streamBackfill(frame.id, outcome.live.session);
+        }
+        else {
+            this.emit({
+                t: 'agent_opened', id: frame.id, ok: false, error: outcome.error,
+                // Only when the agent is the one that said no, and then it is the one refusal that can be
+                // an `auth_required`: `AcpAgents.open` records the `initialize` observation *before*
+                // `session/new`, so the method table is already there when the session it refused throws.
+                // The code says whether this particular refusal actually was that one.
+                ...(outcome.agentRefused
+                    ? this.refusalFields(outcome.agentRefused.agentId, outcome.agentRefused.errorCode)
+                    : {}),
+            });
+        }
+    }
+    /**
+     * Answers a backfill-flagged open that landed on an already-live (or already-being-opened)
+     * session, without replaying anything.
+     *
+     * Every `agent_open` with `backfill: true` owes the server exactly one `agent_backfill_done` for
+     * *that frame's* `id` — that is the only thing the server's adoption wait is keyed on (Task 12).
+     * The reconnect branch (an existing live session) and the in-flight-piggyback branch (a second
+     * `agent_open` racing an attempt already in `openSession`) both reuse a session whose history, if
+     * any, was already streamed once — under a *different* open's id, by {@link streamBackfill} off
+     * the direct-attempt path. Silently doing nothing here would leave the server waiting on this
+     * frame's id forever, since a wait with no reply is indistinguishable from one still in progress.
+     * `ok:true, count:0` is not a lie: from this frame's point of view there is genuinely nothing left
+     * to replay — it just was not this open that did the replaying.
+     */
+    replyNoReplayNeeded(frame) {
+        if (frame.backfill)
+            this.emit({ t: 'agent_backfill_done', id: frame.id, ok: true, count: 0 });
+    }
+    /**
+     * Streams an adopted session's history back to the server, after `agent_opened` and before
+     * anything else touches this ref. `agent_open` carries `backfill?: boolean` rather than a
+     * standalone request frame precisely so this can run here: the history only exists once the agent
+     * has actually loaded the native session (`AcpAgents.open` captures what `session/load` replays),
+     * and `agent_open` already has the whole open path (spec construction, ok/error reply) that a
+     * standalone frame would force the daemon to rebuild a second copy of.
+     *
+     * Deliberately outside the live event/journal machinery — no `bridge_seq`, no
+     * {@link SessionJournal} entry, no `agent_event_ack` round trip. `bridge_seq` means one specific
+     * thing: live-consumption progress, the only basis for de-duplication across reconnects. Backfill
+     * is a one-shot replay correlated purely by this open's `id`; folding it into that watermark would
+     * give it two meanings, which is exactly what produced two watermark bugs in an earlier phase.
+     *
+     * Exactly one `agent_backfill_done` is emitted on every path — success, a `backfill()` that throws
+     * mid-stream, and a session with no `backfill` method at all — via the single `emit` call below,
+     * which runs unconditionally after the try/catch rather than once per branch. A `backfill()` that
+     * throws still keeps every batch already emitted (partial history is the accepted degradation for
+     * a best-effort, third-party format); a session without `backfill()` is not an error (`ok:true,
+     * count:0` — that is every session that was not opened onto existing history). Must never throw:
+     * `handleFrame`'s caller is the frame-ingestion path, so an exception here would damage the whole
+     * tunnel rather than one request (same discipline as {@link onListNative}).
+     */
+    async streamBackfill(id, session) {
+        if (!session.backfill) {
+            this.emit({ t: 'agent_backfill_done', id, ok: true, count: 0 });
+            return;
+        }
+        let batch = [];
+        let count = 0;
+        let ok = true;
+        let error;
+        try {
+            // Called as `session.backfill()`, not through a destructured reference: an implementation may
+            // legitimately rely on `this`, and a bare local `const backfill = session.backfill` would call
+            // it unbound.
+            for await (const event of session.backfill()) {
+                batch.push(event);
+                count += 1;
+                if (batch.length >= BACKFILL_BATCH_SIZE) {
+                    this.emit({ t: 'agent_backfill_events', id, events: batch });
+                    batch = [];
+                }
+            }
+        }
+        catch (err) {
+            ok = false;
+            error = errorMessage(err);
+        }
+        if (batch.length > 0)
+            this.emit({ t: 'agent_backfill_events', id, events: batch });
+        this.emit({ t: 'agent_backfill_done', id, ok, count, ...(error !== undefined ? { error } : {}) });
+    }
+    /**
+     * Replays everything the server has not applied, then confirms the open.
+     *
+     * Replay comes first because the server registers its inbound handler *before* it sends
+     * `agent_open` (see AgentTunnelChannel): frames that arrive ahead of `agent_opened` are already
+     * dispatched, and going the other way round would leave a window in which a freshly produced
+     * event overtakes an older replayed one.
+     *
+     * `reloaded` is a parameter, not something derived here, on purpose: the `LiveSession` this
+     * receives looks identical whether the caller reused a live session, piggybacked on another
+     * open's real result, or just performed the open itself — only the caller knows which of those
+     * three happened, so any derivation from `live` alone would be guesswork.
+     */
+    async resumeAndReply(live, frame, reloaded) {
+        this.touch(live);
+        if (frame.nativeSessionId && frame.nativeSessionId !== live.nativeSessionId) {
+            // Not an error — the server's persisted id can lag a native session the agent rotated — but
+            // it is the only trace of "the conversation you think you are resuming is not this one".
+            console.warn(`[agent] ${live.sessionRef}: server asked to resume native session '${frame.nativeSessionId}' ` +
+                `but the live one is '${live.nativeSessionId}'`);
+        }
+        const resumeFrom = resumeFromSeqOf(frame);
+        // On the session's own queue so an agent event produced mid-replay is sent after it, not into
+        // the middle of it.
+        await this.enqueue(live, async () => {
+            const entries = await live.journal.entriesAfter(resumeFrom);
+            if (this.hasGap(live, entries, resumeFrom)) {
+                this.emit({
+                    t: 'agent_event',
+                    sessionRef: live.sessionRef,
+                    // The hole left by the overflow drop starts exactly here. Reusing that seq (rather than
+                    // taking a fresh one) is what makes the notice survive the server's `seq > bridgeSeq`
+                    // filter *without* pushing the watermark past the replayed entries behind it.
+                    seq: resumeFrom + 1,
+                    eventName: 'step',
+                    payload: { message: 'transport gap: oldest streamed output dropped', tone: 'neutral' },
+                });
+            }
+            // Already-formed frames, carrying their original seq — resent verbatim so the server's
+            // de-duplication does the deciding.
+            for (const entry of entries)
+                this.emit(entry.frame);
+        });
+        this.emit({
+            t: 'agent_opened',
+            id: frame.id,
+            ok: true,
+            nativeSessionId: live.nativeSessionId,
+            // Whether THIS open actually performed `session/load` or `session/new`, as the caller told
+            // us — see the parameter doc on `resumeAndReply` for why that has to come from the caller.
+            // Emitted only when true, the same `supportsSteering` convention as below: absent is the
+            // field's only "no", and it is also what an older peer sends.
+            ...(reloaded ? { reloaded: true } : {}),
+            // The server learns this here and nowhere else. It used to be published only on the roster in
+            // the `agent_hello` handshake, which is a snapshot taken *before* any agent was connected to —
+            // and the capability can only be observed on a live `initialize`, whose record
+            // (`AcpAgents.observed`) does not outlive this process. So the roster could never carry it,
+            // and a workstation whose adapter genuinely steers reported `false` forever. Read off the
+            // session rather than copied onto {@link LiveSession}: it is fixed for that session's life, so
+            // a second copy could only ever disagree with the first.
+            //
+            // Emitted only when true, like `BridgeInfo.supportsSteering`: absent is the field's only "no",
+            // and it is also what a peer too old to answer sends.
+            ...(live.session.supportsSteering ? { supportsSteering: true } : {}),
+            // Which delivery timings that same `initialize` declared. Emitted only when non-empty, for
+            // `supportsSteering`'s reason: absent and `[]` say the same thing — the agent named no
+            // timing, so the server may not name one either (ruling N4) — and absent is also what a peer
+            // too old to answer sends. Read off the session for the same session-not-roster reason.
+            // Read defensively, exactly as `supportsSteering` above already is — **not every driver of
+            // this manager is an object TypeScript ever checked.** `tsconfig.json` excludes
+            // `src/**/*.test.ts`, and the server's end-to-end replay harness is plain `.mjs`
+            // (`axom-server/src/test/resources/full-replay-agent-harness.mjs`); both hand this method a
+            // session carrying only the members they exercise, and neither declares this one. A bare
+            // `.length` on it threw `TypeError: Cannot read properties of undefined` *inside the open
+            // reply*, so `agent_opened` was never sent at all and the session stranded until the server
+            // timed out a minute later. Absent has to degrade to "the agent named no timing" — ruling
+            // N4's safe direction, never specify one — and not to a crash that costs the whole session.
+            ...((live.session.steeringTimings?.length ?? 0) > 0
+                ? { steeringTimings: [...live.session.steeringTimings] }
+                : {}),
+            // `InitializeResponse.agentInfo` verbatim, read off the session for the same reason
+            // `supportsSteering` is (see the comment above): fixed for the session's life, and only
+            // observable on a live `initialize`. Absent — never a fabricated placeholder — when the
+            // agent's own `initialize` never sent one; this does NOT go through `BridgeInfo` (pre-flight
+            // ruling R1: `agent_opened` is assembled from `live.session.*`, not from the roster, so a
+            // field added to `BridgeInfo` would have no reader here).
+            ...(live.session.agentInfo ? { agentInfo: live.session.agentInfo } : {}),
+            // ACP `PromptCapabilities.image`, learned at the same `initialize` and for the same
+            // session-not-roster reason as `supportsSteering` above: `true`-or-absent is this field's
+            // whole vocabulary, so an agent that said nothing (or a peer too old to answer) reads the
+            // same as one that explicitly said no.
+            ...(live.session.supportsImageInput ? { supportsImageInput: true } : {}),
+            // The session's own config option snapshot — model, reasoning effort, whatever else the
+            // agent declared — read off the session for the same reason `supportsSteering` is: it is
+            // observable only on this session's own `initialize`/`session/new`, never on the roster.
+            //
+            // Unlike `supportsSteering`, this one is **not** fixed for the session's life: every
+            // `agent_set_config_option` replaces it. That is why it is read through a getter here rather
+            // than copied onto {@link LiveSession} at open time — this line runs again on every reuse
+            // `agent_opened`, which is what a tunnel reconnect produces, and a snapshot frozen at open
+            // would report the pre-change values to the server after every config change. See
+            // {@link AcpAgentSession.configOptions} for what that costs.
+            configOptions: live.session.configOptions,
+        });
+    }
+    /**
+     * Whether the overflow drop actually took something the server still needs. `droppedOldest` alone
+     * is not enough: by the time of this reconnect the server may have acked past the hole, and
+     * announcing a gap that no longer exists would both mislead the user and collide with the seq of
+     * the first replayed entry.
+     */
+    hasGap(live, entries, resumeFrom) {
+        if (!live.journal.droppedOldest)
+            return false;
+        const first = entries[0];
+        return first ? first.seq > resumeFrom + 1 : live.journal.lastSeq > resumeFrom;
+    }
+    async openSession(frame) {
+        // A previous incarnation of this ref may still be deleting its journal; two SessionJournal
+        // instances must never share a path (see {@link retiring}). This is the first statement on
+        // purpose — before init, before the agent spawns, before anything touches the filesystem.
+        await this.retiring.get(frame.sessionRef);
+        // spec.env is an OVERLAY merged onto process.env when the agent is spawned (see
+        // AcpOpenSpec.env), so it is built from frame-supplied values only. The single exception is
+        // PATH: when pathPrepend is set we resolve the whole variable here — prepends first, then the
+        // frame's PATH or, failing that, the daemon's — so the launcher uses spec.env.PATH verbatim
+        // instead of re-deriving it.
+        const env = { ...(frame.env ?? {}) };
+        const pathPrepend = frame.pathPrepend ?? [];
+        if (pathPrepend.length > 0) {
+            env.PATH = [...pathPrepend, env.PATH ?? process.env.PATH ?? ''].filter(Boolean).join(path.delimiter);
+        }
+        // Recovered before the agent spawns, because nextSeq() is synchronous and the first event may
+        // arrive the instant onEvent is registered: the high-water mark has to be known by then or a
+        // restarted daemon would restart seq at 1 and the server would swallow the next turn as
+        // already-applied. The frame's watermark is passed in as a floor under whatever the file
+        // yields, because "the file is empty" is the *normal* state between turns — everything in it
+        // was acked and truncated — so the file alone would say 0 while the server sits at N.
+        // init() only reads — the file appears on the first append — so an open that fails here leaves
+        // nothing behind.
+        const journal = new SessionJournal(this.sessionsDir, frame.sessionRef, this.maxJournalBytes);
+        try {
+            await journal.init(resumeFromSeqOf(frame));
+        }
+        catch (err) {
+            return { live: null, error: `journal init failed: ${errorMessage(err)}` };
+        }
+        // Both journal recovery and a retiring prior incarnation can await before this point. Only a
+        // force-stop may cancel an open admitted before that await; graceful drain owns its reservation
+        // and must let it settle without starting a second admission decision halfway through.
+        if (this.tasks?.isForceStopping()) {
+            await journal.destroy();
+            return { live: null, error: 'Workstation is not accepting new work' };
+        }
+        let session;
+        let nativeSessionId;
+        try {
+            const result = await this.agents.open({
+                // `frame.bridge` is the registry agent id now — the wire field keeps its name because Plan A
+                // renames nothing (Global Constraint 3); ruling R2 replaced what it *means*.
+                agentId: frame.bridge,
+                cwd: frame.cwd,
+                env,
+                agentEnv: frame.agentEnv ?? {},
+                ...(frame.command ? { command: frame.command } : {}),
+                args: frame.args ?? [],
+                ...(frame.nativeSessionId ? { nativeSessionId: frame.nativeSessionId } : {}),
+                // Retaining a whole adopted history costs memory for the session's lifetime, so it is only
+                // kept when this open is the one that will stream it back.
+                backfill: frame.backfill === true,
+            });
+            session = result.session;
+            nativeSessionId = result.nativeSessionId;
+        }
+        catch (err) {
+            // `open` throws on both sides of the agent's `initialize` — nothing to launch and a spawn
+            // that failed look identical from here — so the marker is asked for rather than assumed. Only
+            // an {@link AgentRefusedSessionError} is the agent's own no, which is what an `auth_required`
+            // on `session/new` arrives as; see {@link OpenOutcome.agentRefused}.
+            return {
+                live: null,
+                error: errorMessage(err),
+                // The code comes off the marker, not off `errorMessage(err)` above: the wrapper captured it
+                // from the original rejection at the moment that object still existed.
+                ...(err instanceof AgentRefusedSessionError
+                    ? { agentRefused: { agentId: frame.bridge, ...(err.errorCode !== undefined ? { errorCode: err.errorCode } : {}) } }
+                    : {}),
+            };
+        }
+        // An accepted open is counted while startup is asynchronous. A graceful gate change therefore
+        // waits for it and leaves it alive; only force-stop authorizes destructive late completion.
+        if (this.tasks?.isForceStopping()) {
+            try {
+                await session.close();
+            }
+            catch (err) {
+                console.error(`[agent] close of force-stopped open failed for ${frame.sessionRef}: ${errorMessage(err)}`);
+            }
+            await journal.destroy();
+            return { live: null, error: 'Workstation is not accepting new work' };
+        }
+        // The session became pointless while it was spawning (agent_close, or the socket dropped and the
+        // server abandoned its pending open). Shut the agent down instead of registering an orphan
+        // nobody will ever close.
+        const abandonReason = this.closedDuringOpen.get(frame.sessionRef);
+        if (abandonReason) {
+            this.closedDuringOpen.delete(frame.sessionRef);
+            try {
+                await session.close();
+            }
+            catch (err) {
+                console.error(`[agent] close of abandoned open failed for ${frame.sessionRef}: ${errorMessage(err)}`);
+            }
+            // Only an explicit agent_close retires the ref, and only then does its journal go. A socket
+            // drop must leave the file alone: it may hold entries this daemon recovered from a previous
+            // life, and the server will re-open the ref and ask for exactly those.
+            if (abandonReason === 'closed')
+                await journal.destroy();
+            return { live: null, error: 'session closed during open' };
+        }
+        const live = {
+            sessionRef: frame.sessionRef,
+            agentId: frame.bridge,
+            agentKey: frame.agentKey,
+            session,
+            nativeSessionId,
+            journal,
+            writes: Promise.resolve(),
+            closed: false,
+            lastActivityAt: Date.now(),
+        };
+        this.sessions.set(frame.sessionRef, live);
+        this.tasks?.registerAgentSession(frame.sessionRef, () => this.retire(live, 'destroy'));
+        session.onEvent((e) => this.onAgentEvent(live, e));
+        session.onTurnDone((r) => this.onAgentTurnDone(live, r));
+        return { live };
+    }
+    /**
+     * Answers `agent_list_native` by asking the agent itself, over a throwaway connection this manager
+     * never sees. Deliberately involves no `LiveSession`: listing is what a user does *before* deciding
+     * to adopt a session, so there is nothing session-shaped to look up yet and inventing one would be
+     * pure ceremony. Do not add a `sessions`/`sessionRef` lookup here later; listing precedes opening
+     * by design.
+     *
+     * An agent that does not advertise `sessionCapabilities.list` answers `ok:true` with an empty list,
+     * not an error — `adoption.ts` gates on the capability and the directory hides the "not yet
+     * adopted" grouping accordingly. `ok:false` is reserved for a genuine failure (an agent id nothing
+     * can launch, a subprocess that will not start), because "cannot reach this agent" and "this agent
+     * has no sessions" must not look alike to the user.
+     *
+     * None of its exits may throw: `handleFrame`'s caller is the frame-ingestion path, and an
+     * exception there damages the whole tunnel, not just this request.
+     */
+    async onListNative(frame) {
+        const spec = sanitizeNativeSessionQuery(frame.bridge, frame.query);
+        if (!spec) {
+            this.emit({ t: 'agent_native_sessions', id: frame.id, ok: false, error: 'native session query is missing cwd' });
+            return;
+        }
+        try {
+            const sessions = await this.agents.listNativeSessions({ ...spec, filterCwd: frame.query.filterCwd ?? undefined });
+            // `updatedAtEpochMs` crosses to a Kotlin `Long`, and a fractional value does not degrade —
+            // the whole frame fails to decode, and the gateway answers an undecodable frame by closing
+            // the agent channel, which takes down every session on that workstation with it. Coerced
+            // here rather than trusted upstream: the deleted claude bridge reached the wire with a raw
+            // `stat().mtimeMs`, which is fractional on macOS, and a third-party agent can do the same.
+            this.emit({
+                t: 'agent_native_sessions',
+                id: frame.id,
+                ok: true,
+                sessions: sessions.map((session) => ({ ...session, updatedAtEpochMs: Math.round(session.updatedAtEpochMs) })),
+            });
+        }
+        catch (err) {
+            this.emit({ t: 'agent_native_sessions', id: frame.id, ok: false, error: errorMessage(err) });
+        }
+    }
+    /**
+     * Answers `agent_verify` by actually starting the agent and seeing what it says — the only way the
+     * roster's auth fields can be populated for an agent no session has ever run (see
+     * {@link AcpAgents.verify}).
+     *
+     * `ok: false` means the verification itself could not be carried out — an agent id nothing can
+     * launch, a subprocess that would not start. An agent that started but refused a session is
+     * `ok: true` with a `sessionError`: the verification succeeded, its answer is just
+     * "inconclusive". Collapsing the two would leave a settings page unable to tell "not
+     * installed" from "installed, and something is wrong with it".
+     *
+     * **`authenticated` is spread in, never assigned.** An explicit `authenticated: undefined` is
+     * still an own property, and the whole contract of this field is that a missing key means unknown.
+     * There is no `false` to send — the frame's own outbound check refuses one
+     * (`protocol/agent.ts`'s `authenticatedViolation`).
+     *
+     * None of its exits may throw, for the same reason {@link onListNative} says so: this runs on the
+     * frame-ingestion path, and an exception there damages the whole tunnel.
+     */
+    async onVerify(frame) {
+        const spec = sanitizeNativeSessionQuery(frame.bridge, frame.query);
+        if (!spec) {
+            this.emit({ t: 'agent_verified', id: frame.id, ok: false, error: 'agent verification query is missing cwd' });
+            return;
+        }
+        try {
+            // 预算跟着请求走:发起方说多久就多久（夹紧之后），没说就还是本地的
+            // AGENT_PROBE_TIMEOUT_MS。这一行是「一个超时贯通两端」缺的那一环 —— 在它之前，服务端
+            // 把后台预热放宽到 180s 而这里雷打不动 20s，于是先放弃的永远是 daemon，那 180s 一秒也
+            // 用不上（真机日志：`did not respond to initialize within 20000ms` / 服务端量到 20021ms）。
+            const verification = await this.agents.verify(spec, clampProbeTimeout(frame.timeoutMs));
+            this.emit({
+                t: 'agent_verified',
+                id: frame.id,
+                ok: true,
+                authMethods: verification.authMethods,
+                ...(verification.authenticated ? { authenticated: verification.authenticated } : {}),
+                ...(verification.sessionError ? { sessionError: verification.sessionError } : {}),
+                // Spread, never assigned — same rule as `authenticated` two lines up, and for the same
+                // reason: an explicit `undefined` is still an own property, and a missing key is this
+                // field's whole contract ("nobody looked"). `[]` is a different answer and must survive,
+                // which is why the test is `!== undefined` rather than a truthiness check.
+                ...(verification.availableCommands !== undefined
+                    ? { availableCommands: verification.availableCommands }
+                    : {}),
+                // Same absent-vs-`[]` convention as `availableCommands` above: absent means nobody looked
+                // (the probe never opened a session), `[]` means the agent declared zero config options.
+                ...(verification.configOptions !== undefined ? { configOptions: verification.configOptions } : {}),
+            });
+        }
+        catch (err) {
+            this.emit({ t: 'agent_verified', id: frame.id, ok: false, error: errorMessage(err) });
+        }
+    }
+    /**
+     * Answers `agent_authenticate` by running the agent's own `authenticate` for a method **it
+     * advertised**. A `methodId` it did not advertise is refused by `AcpAuth` without anything being
+     * written to the agent, and arrives here as `ok: false` with that reason.
+     *
+     * Reports no auth state: the reply says whether the call went through, and the caller asks
+     * `agent_verify` for an observation. Same no-throw rule as {@link onVerify}.
+     *
+     * ## Why the reply comes back before the login does
+     *
+     * A login is a round trip through a *person*, in a browser, on some machine. Awaiting it before
+     * replying parks the tunnel request for its whole duration, and the server's own deadline then
+     * ends it — spec §6.2 measured an agent whose `authenticate` had not returned after 25 seconds
+     * because it was still waiting on a browser callback. So this acknowledges the request
+     * immediately (`pending: true`) and sends the outcome as a second `agent_authenticated` when the
+     * login actually settles. Between the two, the URL the reader has to open travels as
+     * `agent_auth_url`, and its retraction as `agent_auth_url_done`.
+     *
+     * Below {@link AGENT_WIRE_AUTH_URL_VERSION} none of that exists on the peer, and the fallback is
+     * not a degraded version of it but literally the previous behaviour: await, then reply once. An
+     * old server cannot decode either new frame — it would count them as undecodable and close the
+     * whole agent channel — and it has no branch that would keep waiting after a `pending` reply it
+     * cannot see, so it must keep getting the shape it knows.
+     */
+    async onAuthenticate(frame) {
+        const spec = sanitizeNativeSessionQuery(frame.bridge, frame.query);
+        if (!spec) {
+            this.emit({ t: 'agent_authenticated', id: frame.id, ok: false, error: 'agent authentication query is missing cwd' });
+            return;
+        }
+        if (this.serverAgentWire < AGENT_WIRE_AUTH_URL_VERSION) {
+            await this.runLogin(frame, spec, {});
+            return;
+        }
+        this.emit({ t: 'agent_authenticated', id: frame.id, ok: true, pending: true });
+        const cancel = new AbortController();
+        this.loginsInFlight.add(cancel);
+        void this.runLogin(frame, spec, {
+            signal: cancel.signal,
+            // Gated here, inside the callbacks, rather than only at the top of this method: the sender is
+            // rebound on every reconnect and carries the *new* peer's version with it, so a login that
+            // outlives a reconnect to an older server must not keep sending frames that would close the
+            // channel it just came back on.
+            present: (elicitationId, url) => {
+                if (this.serverAgentWire < AGENT_WIRE_AUTH_URL_VERSION)
+                    return;
+                this.emit({ t: 'agent_auth_url', id: frame.id, elicitationId, url });
+            },
+            dismiss: (elicitationId) => {
+                if (this.serverAgentWire < AGENT_WIRE_AUTH_URL_VERSION)
+                    return;
+                this.emit({ t: 'agent_auth_url_done', id: frame.id, elicitationId });
+            },
+        }).finally(() => this.loginsInFlight.delete(cancel)).catch((err) => {
+            // Unreachable by construction ({@link runLogin} settles every path itself), and logged rather
+            // than left implicit because this promise is deliberately not awaited: an escaping rejection
+            // here would be an `unhandledRejection`, which this daemon treats as fatal.
+            console.error(`[agent] login for '${frame.bridge}' left an unhandled failure: ${errorMessage(err)}`);
+        });
+    }
+    /**
+     * Run one login to its end and report the outcome — the *final* `agent_authenticated`, the one
+     * without `pending`, which is the only one that carries an error.
+     *
+     * Called either awaited (an old peer, where it is the whole exchange) or detached (a new peer,
+     * after the acknowledgement), so it must never throw: it is the tail of the frame-ingestion path
+     * in the first case and an unowned promise in the second.
+     */
+    async runLogin(frame, spec, login) {
+        try {
+            await this.agents.authenticate(spec, frame.methodId, login);
+            this.emit({ t: 'agent_authenticated', id: frame.id, ok: true });
+        }
+        catch (err) {
+            this.emit({ t: 'agent_authenticated', id: frame.id, ok: false, error: errorMessage(err) });
+        }
+    }
+    /**
+     * Answers `agent_install` by fetching the agent's adapter — and **only** the adapter. Nothing is
+     * launched here, which is what separates it from `agent_verify`: this is the work the first
+     * session would otherwise do invisibly, brought forward to a button.
+     *
+     * `unsupported` travels as its own field rather than folded into `error`, because "this build
+     * cannot fetch this kind of adapter yet" is a permanent property of the build that the settings
+     * page renders as *coming soon*, while an `error` is a download the reader can retry.
+     *
+     * `adapterInstalled` is spread in, never assigned, for the reason `onVerify` gives about
+     * `authenticated`: an explicit `undefined` is still an own property, and the frame's own outbound
+     * check refuses anything but `true` or absent.
+     *
+     * None of its exits may throw — same rule as {@link onListNative}, same reason.
+     */
+    async onInstall(frame) {
+        try {
+            const result = await this.agents.install(frame.bridge);
+            if (result.ok) {
+                this.emit({
+                    t: 'agent_installed',
+                    id: frame.id,
+                    ok: true,
+                    adapterInstalled: result.adapterInstalled,
+                    alreadyInstalled: result.alreadyInstalled,
+                    ...(result.pinnedVersionUnavailable ? { pinnedVersionUnavailable: result.pinnedVersionUnavailable } : {}),
+                });
+                return;
+            }
+            this.emit({
+                t: 'agent_installed',
+                id: frame.id,
+                ok: false,
+                ...(result.unsupported ? { unsupported: true } : {}),
+                error: result.error,
+            });
+        }
+        catch (err) {
+            this.emit({ t: 'agent_installed', id: frame.id, ok: false, error: errorMessage(err) });
+        }
+    }
+    onAgentEvent(live, e) {
+        if (live.closed)
+            return;
+        // An agent can resume an existing native turn after a client restart, so an inbound prompt is
+        // not the only reliable start marker. These are the two wire events that represent work which
+        // may still require user action or native execution; turn_done below releases the mark.
+        if (e.eventName === 'tool_call' || e.eventName === 'permission_request')
+            this.tasks?.agentTurnStarted(live.sessionRef);
+        // Before the contract check: an agent emitting even non-conforming events is a live process,
+        // and the idle sweep is about liveness, not correctness.
+        this.touch(live);
+        // Contract check BEFORE record(): record() takes the next seq synchronously, so a violating
+        // event that got numbered and then dropped would leave a hole in the sequence — the server's
+        // watermark reads a hole as lost data. Drop, don't throw: one bad event must not poison the
+        // session, and the diagnostic (agent, session, event) is what makes the violation debuggable.
+        const rejection = validateWireEvent(e);
+        if (rejection) {
+            console.warn(`[acp:${live.agentId} agent:${live.agentKey}] dropped event '${wireEventName(e)}' for ${live.sessionRef}: ` +
+                `${rejection.reason}${rejection.detail ? ` (${rejection.detail})` : ''}`);
+            return;
+        }
+        this.record(live, (seq) => ({
+            t: 'agent_event',
+            sessionRef: live.sessionRef,
+            seq,
+            eventName: e.eventName,
+            payload: e.payload,
+            // Present only for a subagent's own output. The frame still rides this session's ref, journal
+            // and seq — one watermark per ref (see `WireEvent.acpSessionId`); this field only says which
+            // session on the far side the event belongs to.
+            ...(e.acpSessionId ? { acpSessionId: e.acpSessionId } : {}),
+        }));
+    }
+    onAgentTurnDone(live, r) {
+        if (live.closed)
+            return;
+        this.tasks?.agentTurnFinished(live.sessionRef);
+        this.touch(live);
+        if (r.nativeSessionId)
+            live.nativeSessionId = r.nativeSessionId;
+        this.record(live, (seq) => ({
+            t: 'agent_turn_done',
+            sessionRef: live.sessionRef,
+            seq,
+            status: r.status,
+            stopReason: r.stopReason,
+            nativeSessionId: r.nativeSessionId ?? null,
+            error: r.error ?? null,
+            // Only on a failure the agent itself answered. This is the frame credentials that expired
+            // mid-conversation arrive on — the agent answers the next `session/prompt` with
+            // `auth_required` rather than ending the session — and it is also the busiest frame on this
+            // channel, one per turn for the life of every session, which is why a completed turn carries
+            // no table nothing reads.
+            //
+            // `status === 'failed'` on its own would be wrong, and wrong in the direction that hurts:
+            // `AcpSession` synthesises that status on three paths the agent never answered (a prompt
+            // after the read loop died, a connection that aborted mid-turn, an unmappable update), all of
+            // them on a *live* session whose method table this daemon certainly holds. An agent process
+            // crashing mid-turn is plausibly more common than a token expiring mid-turn, so pairing those
+            // with `authMethods` would put more false login cards on screen than real ones. See
+            // {@link TurnResult.agentRefused}.
+            //
+            // And `agentRefused` on its own is not enough either, which is what `errorCode` is here for:
+            // an exceeded context window is a refusal the agent genuinely answered, and it is common.
+            ...(r.status === 'failed' && r.agentRefused ? this.refusalFields(live.agentId, r.errorCode) : {}),
+        }));
+    }
+    /**
+     * Numbers a frame, writes it, then sends it. The seq is taken synchronously so callbacks are
+     * numbered in arrival order; the write and the send ride the session's queue so they stay in that
+     * order on the wire.
+     */
+    record(live, build) {
+        const seq = live.journal.nextSeq();
+        const frame = build(seq);
+        void this.enqueue(live, async () => {
+            try {
+                await live.journal.append({ seq, frame });
+            }
+            catch (err) {
+                // Losing durability is bad; losing the event outright is worse. Send it anyway — it just
+                // will not survive a reconnect.
+                console.error(`[agent] journal append failed for ${live.sessionRef}: ${errorMessage(err)}`);
+            }
+            this.emit(frame);
+        });
+    }
+    /** Appends `op` to the session's serialized queue. The returned promise never rejects. */
+    enqueue(live, op) {
+        const next = live.writes.then(op).catch((err) => {
+            console.error(`[agent] journal operation failed for ${live.sessionRef}: ${errorMessage(err)}`);
+        });
+        live.writes = next;
+        return next;
+    }
+    async onClose(sessionRef) {
+        // Closing a ref that is still spawning: nothing to close yet, so tombstone it — openSession
+        // closes the session (and destroys its journal) the moment the bridge hands it over.
+        //
+        // Checking `opening` before `sessions` is only correct because nothing awaits between
+        // openSession's `sessions.set(...)` and onOpen's finally clearing `opening`: a ref is never in
+        // both maps at a point where an inbound frame could observe it. The journal replay onOpen added
+        // — which does await — deliberately runs *after* that finally for exactly this reason.
+        if (this.opening.has(sessionRef)) {
+            this.closedDuringOpen.set(sessionRef, 'closed');
+            return;
+        }
+        const live = this.sessions.get(sessionRef);
+        if (!live)
+            return;
+        await this.retire(live, 'destroy');
+    }
+    /**
+     * The teardown behind `agent_close`: stop emitting, unregister, kill the agent subprocess, and —
+     * when
+     * `journal` says so — delete the journal. Shared with {@link sweepIdle} so an orphan swept on the
+     * timer leaves exactly as little behind as one the server closed properly, except for the file
+     * itself (see {@link sweepIdle} for why that one differs).
+     *
+     * `journal: 'keep'` still rides the same queue and still publishes on {@link retiring}. The wait
+     * is not about the unlink: the point is that this session's pending appends must have landed
+     * before a reopen constructs a second {@link SessionJournal} on the same path, or the new
+     * instance recovers its seq counter from a file that is still being written behind it.
+     */
+    async retire(live, journal) {
+        const sessionRef = live.sessionRef;
+        live.closed = true;
+        this.sessions.delete(sessionRef);
+        this.tasks?.unregisterAgentSession(sessionRef);
+        // Queued behind the pending writes: an append that landed after the file was removed would
+        // resurrect a journal for a session that no longer exists. Published on `retiring` for the whole
+        // teardown, so a reopen of this ref parks until the file is actually gone.
+        const journalDone = this.enqueue(live, async () => {
+            if (journal === 'destroy')
+                await live.journal.destroy();
+        });
+        const retired = journalDone.finally(() => {
+            // Only clear our own entry: a later close of the same ref may already have replaced it.
+            if (this.retiring.get(sessionRef) === retired)
+                this.retiring.delete(sessionRef);
+        });
+        this.retiring.set(sessionRef, retired);
+        try {
+            await live.session.close();
+        }
+        catch (err) {
+            console.error(`[agent] close failed for ${sessionRef}: ${errorMessage(err)}`);
+        }
+        await journalDone;
+    }
+    /**
+     * The one place every outbound agent frame passes, and so the one place the wire contract can be
+     * enforced for all of them at once.
+     *
+     * A frame the server cannot decode is not a lost frame — the server has no way to tell which
+     * session or request the wreckage belonged to, so the damage lands wherever it falls. Per-agent
+     * care at each field is what failed twice already: the deleted codex bridge was fixed for exactly
+     * this and the deleted claude bridge shipped the same defect months later. Checking here covers
+     * every agent, including the ones nobody has written an adapter for yet.
+     *
+     * The cost is one serialize-and-parse per frame, which streaming events pay too. That is the
+     * price of the check being faithful to what the peer reads rather than to what this process
+     * believes it built.
+     */
+    emit(frame) {
+        const rejection = outboundAgentFrameRejection(frame);
+        if (rejection) {
+            console.error(`[agent] refusing to send a malformed ${frame.t}: ${rejection}`);
+            // Nothing is sent when the frame answered no request: an unreadable frame is worse than a
+            // missing one, and the server's own scoping decides what a gap costs.
+            const reply = outboundFailureReply(frame, rejection);
+            if (reply)
+                this.send?.(reply);
+            return;
+        }
+        if (this.send === null) {
+            if (this.mutedDrops === 0) {
+                this.mutedSinceMs = Date.now();
+                console.warn(`[agent] sender is unbound; dropping ${frame.t} and everything after it until a reconnect rebinds it`);
+            }
+            this.mutedDrops++;
+            return;
+        }
+        this.send(frame);
+    }
+}