agent-relay 10.1.0 → 10.2.0

package/dist/cli/lib/attach-drive.js

@@ -11,37 +11,50 @@
  * mode, and leaves the agent running under the broker — `drive` never kills the
  * worker.
  *
- * Sequence of operations on attach:
+ * Sequence of operations on attach (subscribe-first, so no output around
+ * attach time is lost and none is double-painted):
  *
  *   1. Discover broker connection (CLI flag → env → connection.json).
  *   2. `GET  /api/spawned/{name}/delivery-mode`  → remember the previous mode.
  *   3. `PUT  /api/spawned/{name}/delivery-mode`  → switch to `manual_flush`.
- *   4. `captureAndRenderSnapshot`       → repaint the agent's current screen.
- *   5. `GET  /api/spawned/{name}/pending` → seed the status-line counter.
- *   6. Open `/ws`, subscribe to events for this worker.
- *   7. Open the SDK PTY input stream, then switch local stdin to raw
- *      mode and forward bytes through that stream.
+ *   4. `GET /api/events/replay` → capture the durable-event `sinceSeq` cutoff,
+ *      then `GET /api/spawned/{name}/pending` → seed the status-line counter
+ *      and the set of already-queued `event_id`s. Cutoff-first + id-dedupe
+ *      keeps the counter exact across the attach race (no under/over-count).
+ *   5. Open `/ws?sinceSeq=<cutoff>`, subscribe, and buffer live output. The
+ *      cutoff stops the broker replaying historical durable events that would
+ *      inflate the pending counter; any replayed `delivery_queued` already in
+ *      the seed is deduped by `event_id`.
+ *   6. On subscribe: `captureAndRenderSnapshot` repaints the agent's current
+ *      screen; buffered chunks are reconciled against the snapshot's stream
+ *      offset (drop what the snapshot already shows, apply the rest).
+ *   7. Forward the initial terminal size (resize now lands in the live stream,
+ *      not a dead zone), then open the SDK PTY input stream and switch local
+ *      stdin to raw mode.
  *
  * On detach (clean or abnormal), best-effort `PUT .../delivery-mode` restores the
  * previous mode so the queue doesn't fill up indefinitely.
  */
 import { Buffer } from 'node:buffer';
+import { randomUUID } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
-import { captureAndRenderSnapshot, captureInitialSnapshot, pickInitialTerminalRows, prepareAttachTarget, switchInboundDeliveryModeOrAbort, syncInitialPtySize, } from '../lib/attach.js';
+import { captureAndRenderSnapshot, createBackpressureAwareWriter, DETACH_CLEANUP_DEADLINE_MS, pickInitialTerminalRows, prepareAttachTarget, resetLocalTerminalOnDetach, restoreInboundDeliveryModeOnDetach, StatusLineController, StreamSyncBuffer, switchInboundDeliveryModeOrAbort, syncInitialPtySize, } from '../lib/attach.js';
 import { defaultStateDir, readConnectionFileFromDisk, toWsUrl, } from '../lib/broker-connection.js';
 import { defaultExit, runSignalHandler } from '../lib/exit.js';
 import { createBrokerClient, mapBrokerSdkFailure, } from '../lib/attach-broker.js';
 import { createPredictiveEcho } from './predictive-echo-screen.js';
 function withDefaults(overrides = {}) {
     const fetchFn = overrides.fetch ?? ((input, init) => fetch(input, init));
+    const writer = createBackpressureAwareWriter(process.stdout);
     return {
         readConnectionFile: readConnectionFileFromDisk,
         getDefaultStateDir: defaultStateDir,
         env: process.env,
         createWebSocket: (url, headers) => new WebSocket(url, { headers }),
-        writeChunk: (chunk) => {
-            process.stdout.write(chunk);
-        },
+        writeChunk: writer.write,
+        disposeWriter: writer.dispose,
+        statusRepaintCoalesceMs: 40,
         onSignal: (signal, handler) => {
             const listener = () => runSignalHandler(handler);
             process.on(signal, listener);
@@ -99,10 +112,37 @@ export async function setInboundDeliveryMode(connection, name, mode, fetchFn) {
         return { ok: false, status: failure.status, message: failure.message };
     }
 }
-/** `GET /api/spawned/{name}/pending` → count, or `0` on failure (best-effort). */
-export async function getPendingCount(connection, name, fetchFn) {
+/**
+ * `GET /api/spawned/{name}/pending` → `{ count, eventIds }`, or an empty seed
+ * on failure (best-effort). The `eventIds` set carries every pending
+ * delivery's `event_id` (deliveries without one are still counted but can't
+ * be deduped) so a replayed `delivery_queued` frame for an already-seeded
+ * delivery doesn't inflate the counter.
+ */
+export async function getPendingSeed(connection, name, fetchFn) {
+    try {
+        const pending = await createBrokerClient(connection, fetchFn).getPending(name);
+        const eventIds = new Set();
+        for (const message of pending) {
+            if (typeof message.event_id === 'string')
+                eventIds.add(message.event_id);
+        }
+        return { count: pending.length, eventIds };
+    }
+    catch {
+        return { count: 0, eventIds: new Set() };
+    }
+}
+/**
+ * Current durable-event sequence cutoff, used as the event WS `sinceSeq` so
+ * the broker does not replay historical durable events (old `delivery_queued`
+ * frames) that would otherwise inflate the freshly-seeded pending counter.
+ * Returns `0` on failure (best-effort) — the caller then omits `sinceSeq`
+ * and behaves as before.
+ */
+export async function getCurrentEventSeq(connection, fetchFn) {
     try {
-        return (await createBrokerClient(connection, fetchFn).getPending(name)).length;
+        return await createBrokerClient(connection, fetchFn).currentEventSeq();
     }
     catch {
         return 0;
@@ -140,9 +180,9 @@ export function openPtyInputStream(connection, name, fetchFn, options) {
  * running in it) sees the size the human is actually looking at.
  * Called once on attach and again on every local-terminal resize.
  */
-export async function resizeWorker(connection, name, rows, cols, fetchFn) {
+export async function resizeWorker(connection, name, rows, cols, fetchFn, options) {
     try {
-        await createBrokerClient(connection, fetchFn).resizePty(name, rows, cols);
+        await createBrokerClient(connection, fetchFn).resizePty(name, rows, cols, options);
         return { ok: true };
     }
     catch (err) {
@@ -150,6 +190,24 @@ export async function resizeWorker(connection, name, rows, cols, fetchFn) {
         return { ok: false, message: failure.message };
     }
 }
+/**
+ * Release this session's PTY resize ownership on detach (single-resizer
+ * policy, #1247), so the next client that attaches can resize the shared PTY.
+ * Best-effort: the broker also supersedes a crashed owner after an idle window.
+ */
+export async function releaseResizeOwnership(connection, name, sessionId, fetchFn) {
+    try {
+        // A pure release carries no dimensions — the broker skips the resize and
+        // only drops ownership, so there are no placeholder sizes to invent.
+        await createBrokerClient(connection, fetchFn).resizePty(name, undefined, undefined, {
+            sessionId,
+            release: true,
+        });
+    }
+    catch {
+        // Best-effort — ownership falls back to the broker's idle-takeover net.
+    }
+}
 /** ----- WS message classification ----- */
 function isStringObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -178,10 +236,16 @@ export function classifyWsEvent(rawMessage, name) {
         const chunk = parsed.chunk;
         if (typeof chunk !== 'string')
             return { kind: 'other' };
-        return { kind: 'worker_stream', chunk };
+        const offset = typeof parsed.offset === 'number' ? parsed.offset : undefined;
+        return { kind: 'worker_stream', chunk, offset };
     }
     if (parsed.kind === 'delivery_queued') {
-        return { kind: 'delivery_queued' };
+        // `event_id` correlates a replayed frame with the pending seed so the
+        // counter isn't double-incremented for a delivery already reflected in
+        // the seed (see the seed-dedup note in `runDriveSession`). Absent on
+        // legacy/mixed frames — treated as "not in the seed" (counted).
+        const eventId = typeof parsed.event_id === 'string' ? parsed.event_id : undefined;
+        return { kind: 'delivery_queued', eventId };
     }
     if (parsed.kind === 'agent_pending_drained') {
         const count = typeof parsed.count === 'number' ? parsed.count : undefined;
@@ -232,14 +296,19 @@ export function renderStatusLine(opts) {
     return `\x1b7\x1b[${row};1H\x1b[2K\x1b[7m${text}\x1b[0m\x1b8`;
 }
 /**
- * Run the interactive session: opens the WS, takes over stdin on
- * `open`, drives resize/status-line handling, and restores the
- * worker's previous mode on any exit path. Resolves with the exit
- * code the CLI should propagate.
+ * Run the interactive session. Subscribe-first: opens the event WS, buffers
+ * live `worker_stream` chunks, then (on subscribe) paints the snapshot,
+ * reconciles the buffer against the snapshot offset, forwards the initial
+ * resize, and takes over stdin. Restores the worker's previous mode on any
+ * exit path. Resolves with the exit code the CLI should propagate.
  */
 function runDriveSessionLoop(state, deps) {
-    const { connection, name, previousMode } = state;
-    const wsUrl = toWsUrl(connection.url);
+    const { connection, name, previousMode, sessionRevision, seededEventIds } = state;
+    // Connect with a `sinceSeq` cutoff so the broker replays only events after
+    // attach — historical durable events must not inflate the pending counter.
+    // Omit it when the cutoff is 0 (no durable events yet / lookup failed) so
+    // the URL and behaviour match the pre-cutoff default.
+    const wsUrl = state.cutoffSeq > 0 ? `${toWsUrl(connection.url)}?sinceSeq=${state.cutoffSeq}` : toWsUrl(connection.url);
     const headers = {};
     if (connection.apiKey) {
         headers['X-API-Key'] = connection.apiKey;
@@ -248,31 +317,86 @@ function runDriveSessionLoop(state, deps) {
         let settled = false;
         let rawModeWasSet = false;
         let unsubscribeResize = null;
+        // Stable per-attach id for the broker's single-resizer policy (#1247): all
+        // of this session's resizes carry it so we own the shared PTY size while
+        // driving, and we release it on detach.
+        const resizeSessionId = randomUUID();
+        // In-flight resize requests. Detach awaits these before releasing ownership
+        // so a late-resolving SIGWINCH resize can't re-claim the PTY *after* the
+        // release lands (single-resizer detach race, #1247).
+        const outstandingResizes = new Set();
+        const trackResize = (p) => {
+            outstandingResizes.add(p);
+            void p.finally(() => outstandingResizes.delete(p));
+        };
+        // Periodic ownership re-assert timer (see `ownershipReassertMs`).
+        let reassertTimer = null;
         let pending = state.initialPending;
-        let terminalRows = state.initialTerminalRows;
+        let terminalRows = pickInitialTerminalRows(state.initialLocalSize, undefined);
         const parser = new KeybindParser();
+        // Stateful UTF-8 decoder for forwarded stdin. Decoding each raw stdin chunk
+        // independently would turn a multi-byte character split across `data`
+        // events (routine in large pastes / IME) into U+FFFD; the StringDecoder
+        // buffers a trailing incomplete sequence until the next chunk completes it.
+        // Detach scanning still runs on raw bytes upstream (0x03 can't appear inside
+        // a multi-byte sequence), so this only touches the forwarded payload.
+        const inputDecoder = new StringDecoder('utf8');
         let inputStream = null;
         const cleanupSignals = [];
+        // Skip the status line entirely when stdout is not a TTY (e.g. piped to
+        // `tee`) — a fabricated row-24 repaint would corrupt the captured log.
+        const statusLineEnabled = state.initialLocalSize !== null;
+        // Subscribe-first: buffer live `worker_stream` chunks until the snapshot
+        // is painted and reconciled against its per-worker offset.
+        const sync = new StreamSyncBuffer();
         // Adaptive predictive echo masks round-trip latency on remote brokers.
-        // Seeded with the snapshot so its confirmed model matches the screen.
+        // Seeded with the snapshot (once painted) so its confirmed model matches
+        // the screen.
         const predictiveEcho = deps.createPredictiveEcho?.({
             cols: state.initialLocalSize?.cols ?? 0,
             rows: state.initialLocalSize?.rows ?? 0,
             write: deps.writeChunk,
             getInputSrtt: () => inputStream?.srttMs ?? null,
         }) ?? null;
-        if (predictiveEcho) {
-            void predictiveEcho.seed(state.snapshotBytes);
-        }
+        // Tee the snapshot's painted bytes so we can seed the predictive-echo
+        // model with them — its cursor must match the real screen before we
+        // optimistically echo, or predicted glyphs land at the wrong position.
+        let snapshotBytes = '';
+        // Guard the snapshot paint on `settled`: a Ctrl+C during the snapshot HTTP
+        // fetch would otherwise paint the snapshot after teardown began (the render
+        // runs inside the awaited `captureAndRenderSnapshot`, past the WS guard).
+        const captureWrite = (chunk) => {
+            if (settled)
+                return;
+            deps.writeChunk(chunk);
+            snapshotBytes += chunk;
+        };
+        // Boundary-held + coalesced status painter. Holds repaints while the agent
+        // is mid escape-sequence (no splicing into a half-sent CSI), rate-limits
+        // per-chunk repaints, and skips painting entirely on a non-TTY stdout.
+        const statusController = new StatusLineController({
+            render: () => renderStatusLine({ name, mode: 'manual_flush', pending, rows: terminalRows }),
+            write: deps.writeChunk,
+            enabled: statusLineEnabled,
+            coalesceMs: deps.statusRepaintCoalesceMs ?? 40,
+        });
         const paintStatus = () => {
-            deps.writeChunk(renderStatusLine({
-                name,
-                mode: 'manual_flush',
-                pending,
-                rows: terminalRows,
-            }));
+            statusController.request();
+        };
+        // Route server output through the predictive-echo engine (which owns
+        // cursor save/restore) or straight to stdout, then repaint the status.
+        // Feed every chunk to the status controller for boundary tracking so the
+        // repaint holds off until the stream is back at a sequence boundary.
+        const applyServerOutput = (chunk) => {
+            statusController.observeOutput(chunk);
+            if (predictiveEcho) {
+                void predictiveEcho.onServerOutput(chunk).then(paintStatus, paintStatus);
+            }
+            else {
+                deps.writeChunk(chunk);
+                paintStatus();
+            }
         };
-        paintStatus();
         // Local-terminal resize handler. Forwards to the broker and
         // repaints the status line at the new bottom-row index. Registered
         // on `socket.on('open')` (same point we take over stdin) so a
@@ -284,11 +408,13 @@ function runDriveSessionLoop(state, deps) {
                 return;
             terminalRows = size.rows;
             predictiveEcho?.onResize(size.cols, size.rows);
-            void resizeWorker(connection, name, size.rows, size.cols, deps.fetch).then((res) => {
+            trackResize(resizeWorker(connection, name, size.rows, size.cols, deps.fetch, {
+                sessionId: resizeSessionId,
+            }).then((res) => {
                 if (!res.ok) {
                     deps.log(`[drive] resize forward failed: ${res.message ?? 'unknown error'}`);
                 }
-            });
+            }));
             // Repaint regardless of fetch outcome — the local terminal has
             // already moved, so the status line position needs to move with
             // it whether or not the broker accepted the resize.
@@ -303,22 +429,24 @@ function runDriveSessionLoop(state, deps) {
                     deps.log('[drive] input stream is not ready');
                     return;
                 }
-                // Fire-and-forget; surface errors via log but don't block the
-                // event loop on every keystroke.
-                // UTF-8, not latin1 — the broker input stream forwards string
-                // payload bytes verbatim to the PTY.
-                // 'binary' would map bytes ≥ 0x80 to Latin-1 code points,
-                // which then get UTF-8 re-encoded on the wire, doubling
-                // multi-byte characters (e.g. `é` → `é` on the agent's side).
-                void stream.send(outcome.forward.toString('utf-8')).catch((err) => {
-                    if (settled)
-                        return;
-                    const message = err instanceof Error ? err.message : String(err);
-                    deps.log(`[drive] input stream send failed: ${message}`);
-                    // The keystroke never reached the PTY — drop any optimistic echo
-                    // for it so the screen doesn't show input the agent didn't get.
-                    predictiveEcho?.rollback();
-                });
+                // Decode through the stateful UTF-8 decoder so a multi-byte character
+                // split across stdin chunks is forwarded intact rather than as U+FFFD.
+                // An incomplete trailing sequence decodes to '' and is held until the
+                // next chunk completes it.
+                const decoded = inputDecoder.write(outcome.forward);
+                if (decoded.length > 0) {
+                    // Fire-and-forget; surface errors via log but don't block the
+                    // event loop on every keystroke.
+                    void stream.send(decoded).catch((err) => {
+                        if (settled)
+                            return;
+                        const message = err instanceof Error ? err.message : String(err);
+                        deps.log(`[drive] input stream send failed: ${message}`);
+                        // The keystroke never reached the PTY — drop any optimistic echo
+                        // for it so the screen doesn't show input the agent didn't get.
+                        predictiveEcho?.rollback();
+                    });
+                }
                 predictiveEcho?.onUserInput(outcome.forward);
             }
             for (const action of outcome.actions) {
@@ -349,6 +477,15 @@ function runDriveSessionLoop(state, deps) {
             catch {
                 // best effort
             }
+            try {
+                // Heal the local terminal: the snapshot + live stream may have left it
+                // in app-cursor / mouse / bracketed-paste / alt-screen mode. Gate on a
+                // TTY stdout (same signal that gates the status line).
+                resetLocalTerminalOnDetach(deps.writeChunk, statusLineEnabled);
+            }
+            catch {
+                // best effort
+            }
             try {
                 deps.stdin.pause();
             }
@@ -364,6 +501,15 @@ function runDriveSessionLoop(state, deps) {
             catch {
                 // best effort
             }
+            try {
+                if (reassertTimer) {
+                    clearInterval(reassertTimer);
+                    reassertTimer = null;
+                }
+            }
+            catch {
+                // best effort
+            }
             rawModeWasSet = false;
         };
         const closeInputStream = () => {
@@ -382,6 +528,9 @@ function runDriveSessionLoop(state, deps) {
             if (settled)
                 return;
             settled = true;
+            // Stop the status painter first so no queued repaint fires after we
+            // restore cooked mode (output would otherwise spray past detach).
+            statusController.dispose();
             for (const cleanup of cleanupSignals.splice(0)) {
                 try {
                     cleanup();
@@ -393,15 +542,55 @@ function runDriveSessionLoop(state, deps) {
             teardownStdin();
             predictiveEcho?.reset();
             closeInputStream();
+            // Release resize ownership so the next client can size the shared PTY.
+            // Await any in-flight resizes first: the release must be ordered *after*
+            // the last SIGWINCH resize resolves, or that resize could re-claim the
+            // PTY just after the release lands (detach race, #1247). `teardownStdin`
+            // has already stopped the resize handler and re-assert timer above, so
+            // no new resizes are enqueued past this point.
+            const releasePromise = (async () => {
+                try {
+                    if (outstandingResizes.size > 0) {
+                        await Promise.allSettled([...outstandingResizes]);
+                    }
+                    await releaseResizeOwnership(connection, name, resizeSessionId, deps.fetch);
+                }
+                catch {
+                    // Best-effort — the broker's idle-takeover net still frees ownership.
+                }
+            })();
             try {
                 socket.close(1000, 'drive client exiting');
             }
             catch {
                 // best effort
             }
-            // Best-effort: restore the worker's previous mode so we don't
-            // leave it stuck in manual_flush and silently piling up queued messages.
-            void setInboundDeliveryMode(connection, name, previousMode ?? 'auto_inject', deps.fetch).finally(() => {
+            // Drop the writer's pending queue and unhook its drain listener so no
+            // buffered chunk flushes to stdout after detach.
+            deps.disposeWriter?.();
+            // Best-effort restore: re-read the mode and only revert if it's still
+            // what this session set, so we don't leave the worker stuck in
+            // manual_flush and don't clobber a change another session made.
+            //
+            // Await the release alongside the restore before resolving: `resolve`
+            // typically ends the process, which aborts any still-pending fetch. The
+            // release awaits `outstandingResizes` first, so it would otherwise lose
+            // the race to the restore and be aborted, defeating the detach-race fix.
+            //
+            // Bound the wait: both are best-effort HTTP round-trips that can stall if
+            // the broker is down, and terminal exit must not hang on them. Resolve
+            // once they settle or after DETACH_CLEANUP_DEADLINE_MS, whichever first.
+            const cleanup = Promise.allSettled([
+                releasePromise,
+                restoreInboundDeliveryModeOnDetach(connection, name, previousMode, 'manual_flush', sessionRevision, 'drive', deps),
+            ]);
+            let deadlineTimer;
+            const deadline = new Promise((res) => {
+                deadlineTimer = setTimeout(res, DETACH_CLEANUP_DEADLINE_MS);
+            });
+            void Promise.race([cleanup, deadline]).finally(() => {
+                if (deadlineTimer !== undefined)
+                    clearTimeout(deadlineTimer);
                 resolve(code);
             });
         };
@@ -424,6 +613,26 @@ function runDriveSessionLoop(state, deps) {
                 // we take over stdin so the lifecycles match — both go away in
                 // `teardownStdin` on any exit path.
                 unsubscribeResize = deps.terminal.onResize(resizeHandler);
+                // Start the periodic ownership re-assert so an idle-but-live session
+                // keeps the single-resizer lease past the broker's stale window. The
+                // broker no-ops a same-size re-assert (no SIGWINCH/repaint).
+                const reassertMs = deps.ownershipReassertMs ?? 60_000;
+                if (reassertMs > 0) {
+                    reassertTimer = setInterval(() => {
+                        const size = deps.terminal.getSize() ?? state.initialLocalSize;
+                        if (!size)
+                            return;
+                        trackResize(resizeWorker(connection, name, size.rows, size.cols, deps.fetch, {
+                            sessionId: resizeSessionId,
+                        }).then((res) => {
+                            if (!res.ok) {
+                                deps.log(`[drive] resize ownership re-assert failed: ${res.message ?? 'unknown error'}`);
+                            }
+                        }));
+                    }, reassertMs);
+                    // Don't let the keep-alive timer hold the process open on its own.
+                    reassertTimer.unref?.();
+                }
             }
             catch (err) {
                 if (settled)
@@ -433,36 +642,88 @@ function runDriveSessionLoop(state, deps) {
                 finish(1);
             }
         };
+        // Runs once the event WS is subscribed: paint the snapshot, seed
+        // predictive echo, reconcile buffered live output against the snapshot
+        // offset, forward the initial resize (now that we're subscribed, so its
+        // SIGWINCH repaint lands in the live stream instead of a dead zone before
+        // subscription), then open the input stream and take over stdin.
+        const onSubscribed = async () => {
+            const snapshot = await deps.captureAndRenderSnapshot({ url: connection.url, apiKey: connection.apiKey }, name, { fetch: deps.fetch, writeChunk: captureWrite });
+            if (settled)
+                return;
+            switch (snapshot.status) {
+                case 'ok':
+                    break;
+                case 'not_found':
+                    deps.error(`Error: ${snapshot.message ?? `no agent named '${name}'`}`);
+                    finish(1);
+                    return;
+                case 'no_pty':
+                    deps.error(`Error: ${snapshot.message ?? `agent '${name}' has no PTY to drive`}`);
+                    finish(1);
+                    return;
+                case 'unavailable':
+                case 'transport_error':
+                    deps.log(`[drive] could not capture initial screen (${snapshot.message ?? snapshot.status}); streaming live output only`);
+                    break;
+            }
+            if (predictiveEcho)
+                void predictiveEcho.seed(snapshotBytes);
+            terminalRows = pickInitialTerminalRows(state.initialLocalSize, snapshot.rows);
+            // Track the snapshot bytes for boundary state before the first repaint.
+            statusController.observeOutput(snapshotBytes);
+            paintStatus();
+            // Reconcile buffered chunks. On `ok`, drop what the snapshot already
+            // reflects (by offset); with no offset this drops the pre-snapshot
+            // buffer (snapshot-authoritative, matching the legacy behaviour). On a
+            // transient snapshot failure nothing was painted, so apply everything.
+            const pendingChunks = snapshot.status === 'ok' ? sync.reconcile(snapshot.offset) : sync.flushAll();
+            for (const chunk of pendingChunks)
+                applyServerOutput(chunk);
+            const initialResize = syncInitialPtySize(connection, name, state.initialLocalSize, 'drive', deps, {
+                sessionId: resizeSessionId,
+            });
+            trackResize(initialResize);
+            await initialResize;
+            if (settled)
+                return;
+            // Open the SDK input stream before taking over stdin. A failed stream
+            // should not leave the user's terminal in raw mode with nowhere to
+            // send bytes.
+            await openInputStreamAndTakeStdin();
+        };
+        // Hand off from the early restore handlers (installed before the awaited
+        // setup) to the fuller session-loop handlers — no double restore.
+        state.disposeEarlySignals();
         for (const signal of ['SIGINT', 'SIGTERM']) {
             const cleanup = deps.onSignal(signal, () => finish(0));
             if (typeof cleanup === 'function')
                 cleanupSignals.push(cleanup);
         }
         socket.on('open', () => {
-            // Now that the event WS is up, open the SDK input stream before
-            // taking over stdin. A failed stream should not leave the user's
-            // terminal in raw mode with nowhere to send bytes.
-            void openInputStreamAndTakeStdin();
+            void onSubscribed();
         });
         socket.on('message', (data) => {
+            // Once teardown has begun, drop inbound frames so we don't write output
+            // or repaint the status line after cooked mode is restored.
+            if (settled)
+                return;
             const text = typeof data === 'string' ? data : Buffer.isBuffer(data) ? data.toString('utf-8') : String(data);
             const event = classifyWsEvent(text, name);
             switch (event.kind) {
                 case 'worker_stream':
-                    if (predictiveEcho) {
-                        // The engine owns pass-through (it must restore the cursor
-                        // before writing server bytes when predictions are live);
-                        // repaint the status line once it has flushed.
-                        void predictiveEcho.onServerOutput(event.chunk).then(paintStatus, paintStatus);
-                    }
-                    else {
-                        deps.writeChunk(event.chunk);
-                        // Repaint the status line so the worker's writes don't
-                        // obscure it. Cheap — it's just an ANSI escape sequence.
-                        paintStatus();
-                    }
+                    if (sync.push(event.chunk, event.offset))
+                        applyServerOutput(event.chunk);
                     break;
                 case 'delivery_queued':
+                    // A replayed frame (seq > cutoff) can still be for a delivery
+                    // already reflected in the seeded pending count when it raced the
+                    // cutoff/seed capture. Dedupe by `event_id`: count it once, then
+                    // forget the id so a genuine re-queue of the same event later still
+                    // registers.
+                    if (event.eventId !== undefined && seededEventIds.delete(event.eventId)) {
+                        break;
+                    }
                     pending += 1;
                     paintStatus();
                     break;
@@ -505,36 +766,71 @@ export async function runDriveSession(agentName, options, deps) {
     const flipResult = await switchInboundDeliveryModeOrAbort(connection, name, 'manual_flush', `switch '${name}' to manual_flush mode`, deps);
     if (!flipResult)
         return 1;
-    const { previousMode } = flipResult;
-    // Tee the snapshot's painted bytes so we can seed the predictive-echo
-    // model with them — its cursor must match the real screen before we
-    // optimistically echo, or predicted glyphs land at the wrong position.
-    let snapshotBytes = '';
-    const captureWrite = (chunk) => {
-        deps.writeChunk(chunk);
-        snapshotBytes += chunk;
+    const { previousMode, sessionRevision } = flipResult;
+    // The mode is now flipped to `manual_flush`, but the terminal is still cooked
+    // and we have several awaited HTTP round-trips (pending, cutoff, snapshot,
+    // input stream) before the session loop installs its signal handlers. Ctrl+C
+    // in that window would otherwise kill the process with the worker stranded in
+    // `manual_flush`, silently queueing every later relay message. Register early
+    // restore-and-exit handlers immediately; the loop disposes them once its own
+    // handlers are ready (no double restore — see `disposeEarlySignals`).
+    let earlyHandled = false;
+    const earlyCleanups = [];
+    const earlyRestore = async () => {
+        if (earlyHandled)
+            return;
+        earlyHandled = true;
+        for (const cleanup of earlyCleanups.splice(0)) {
+            try {
+                cleanup();
+            }
+            catch {
+                // best effort
+            }
+        }
+        await restoreInboundDeliveryModeOnDetach(connection, name, previousMode, 'manual_flush', sessionRevision, 'drive', deps);
+        deps.exit(0);
     };
-    const snapshotResult = await captureInitialSnapshot(connection, name, previousMode, 'drive', 'drive', {
-        fetch: deps.fetch,
-        writeChunk: captureWrite,
-        log: deps.log,
-        error: deps.error,
-        captureAndRenderSnapshot: deps.captureAndRenderSnapshot,
-    });
-    if (!snapshotResult)
-        return 1;
-    const initialPending = await getPendingCount(connection, name, deps.fetch);
+    const disposeEarlySignals = () => {
+        earlyHandled = true;
+        for (const cleanup of earlyCleanups.splice(0)) {
+            try {
+                cleanup();
+            }
+            catch {
+                // best effort
+            }
+        }
+    };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const cleanup = deps.onSignal(signal, earlyRestore);
+        if (typeof cleanup === 'function')
+            earlyCleanups.push(cleanup);
+    }
     const initialLocalSize = deps.terminal.getSize();
-    const initialTerminalRows = pickInitialTerminalRows(initialLocalSize, snapshotResult.snapshotRows);
-    await syncInitialPtySize(connection, name, initialLocalSize, 'drive', deps);
+    // Capture the durable-event cutoff *first*, then seed the pending counter.
+    //
+    // The event WS replays durable `delivery_queued` frames with `seq >
+    // cutoffSeq`. Reading the cutoff before the seed guarantees every delivery
+    // NOT captured in the seed has `seq > cutoffSeq` (it was queued after the
+    // cutoff snapshot), so it is replayed and counted — closing the
+    // undercount hole where a delivery racing between the two reads was in
+    // neither the seed nor the replay. The flip side (a delivery that IS in the
+    // seed and also replays because its `seq > cutoffSeq`) is handled by
+    // deduping replayed frames against the seed's `event_id`s (see
+    // `seededEventIds` in the WS handler), so it's counted exactly once.
+    const cutoffSeq = await getCurrentEventSeq(connection, deps.fetch);
+    const { count: initialPending, eventIds: seededEventIds } = await getPendingSeed(connection, name, deps.fetch);
     return runDriveSessionLoop({
         connection,
         name,
         previousMode,
+        sessionRevision,
         initialPending,
-        initialTerminalRows,
+        seededEventIds,
         initialLocalSize,
-        snapshotBytes,
+        cutoffSeq,
+        disposeEarlySignals,
     }, deps);
 }
 /** Run a drive session with default dependencies. Used by `runtime agent attach --mode drive`. */