@0xmaxma/claude-gateway 1.8.2 → 1.8.3

package/dist/agent/runner.js

@@ -35,10 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRunner = exports.CHANNEL_COALESCE_WINDOW_MS = exports.DEFAULT_MODELS = exports.MAX_IMAGE_SIZE_BYTES = void 0;
 exports.toRelMediaFiles = toRelMediaFiles;
+const crypto_1 = require("crypto");
 const events_1 = require("events");
 const fs = __importStar(require("fs"));
 const fsPromises = __importStar(require("fs/promises"));
 const http = __importStar(require("http"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const logger_1 = require("../logger");
 const process_1 = require("../session/process");
@@ -53,6 +55,7 @@ const skills_1 = require("../skills");
 const builtin_commands_1 = require("./builtin-commands");
 const model_catalog_1 = require("./model-catalog");
 const safe_mode_1 = require("./safe-mode");
+const turn_stream_1 = require("./turn-stream");
 const recovery_executor_1 = require("./recovery-executor");
 const recovery_policy_1 = require("./recovery-policy");
 const incident_1 = require("./incident");
@@ -214,6 +217,11 @@ class AgentRunner extends events_1.EventEmitter {
         this.idleCleanerTimer = null;
         // Tracks session IDs with an in-flight API request (prevents concurrent turns)
         this.pendingApiSessions = new Set();
+        // Per-session buffer of the current turn's stream events, so a disconnected or
+        // timed-out client can re-attach and pick the turn back up (#421). Distinct
+        // from pendingApiSessions: that clears the moment the turn settles, this one
+        // survives it for the replay grace window.
+        this.turnStreams = new turn_stream_1.TurnStreamRegistry();
         // Serialises concurrent getOrSpawnSession calls for the same key to prevent double-spawn
         this.sessionSpawnLocks = new Map();
         // Consecutive request_too_large (32MB) recoveries per mapKey. Survives the
@@ -951,6 +959,32 @@ class AgentRunner extends events_1.EventEmitter {
             this.turnQueue.delete(chatId);
         }
     }
+    /**
+     * Delete a channel's throwaway staging copy of an inbound attachment, once
+     * MediaStore holds the permanent one.
+     *
+     * Opt-in via `meta.media_ephemeral === '1'` — only a channel that created the
+     * file under the system temp dir sets it, and only for a path it built itself.
+     * Meta arrives over the local /channel intake, so the flag alone is not
+     * authority to unlink: the path is resolved (symlinks included) and must sit
+     * INSIDE the real temp dir, which bounds a forged flag to deleting something
+     * already in a world-writable scratch directory. Every failure is swallowed —
+     * a leftover temp file is a wart, and a throw here would abort recording the
+     * turn that was already delivered.
+     */
+    static discardEphemeralStaging(stagedPath) {
+        try {
+            const tmpRoot = fs.realpathSync(os.tmpdir());
+            const real = fs.realpathSync(stagedPath);
+            const rel = path.relative(tmpRoot, real);
+            if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+                return;
+            fs.rmSync(real, { force: true });
+        }
+        catch {
+            // Already gone, unreadable, or outside the temp dir — leave it alone.
+        }
+    }
     /**
      * Inject one coalesced turn into the session immediately. The caller must have
      * already marked the chat active in `turnActive`. Records each buffered message
@@ -976,6 +1010,7 @@ class AgentRunner extends events_1.EventEmitter {
                 // Persist to permanent history DB (separate from session context)
                 const mediaFiles = [];
                 if (meta['image_path']) {
+                    const stagedPath = meta['image_path'];
                     try {
                         const rel = media_store_1.MediaStore.copyToMedia(this.agentsBaseDir, this.agentConfig.id, `${channelSource}-${chatId}`, meta['image_path']);
                         mediaFiles.push(rel);
@@ -986,6 +1021,11 @@ class AgentRunner extends events_1.EventEmitter {
                         // Mutating meta['image_path'] here (same object as entry.meta) makes the
                         // channel XML and image-size tracker below both use the readable path.
                         meta['image_path'] = media_store_1.MediaStore.resolvePath(this.agentsBaseDir, this.agentConfig.id, rel);
+                        // The staging copy has served its purpose — drop it (see
+                        // discardEphemeralStaging). Only after a SUCCESSFUL copy: the catch
+                        // below keeps the original path as the agent's only route to the bytes.
+                        if (meta['media_ephemeral'] === '1')
+                            AgentRunner.discardEphemeralStaging(stagedPath);
                     }
                     catch {
                         // Non-fatal — leave the original path so host agents still read it
@@ -1045,7 +1085,15 @@ class AgentRunner extends events_1.EventEmitter {
                 }
                 blocks.push(channelXml);
                 const imagePath = entry.meta?.['image_path'];
-                if (imagePath) {
+                // Non-image attachments (LINE files) ride the same image_path channel so
+                // the runner stages them into MediaStore, but they must NOT count toward
+                // the image-size restart budget below: that budget exists because images
+                // are pulled into context as pixels, whereas a document the agent may
+                // never open would push the chat into a summary+restart it never needed.
+                // media_type is set by the LINE router alone; everything else (Telegram,
+                // Slack, web upload) omits it and keeps counting as an image.
+                const isImageMedia = (entry.meta?.['media_type'] ?? 'image') === 'image';
+                if (imagePath && isImageMedia) {
                     const queue = this.pendingImagePaths.get(chatId) ?? [];
                     queue.push(imagePath);
                     this.pendingImagePaths.set(chatId, queue);
@@ -1424,6 +1472,17 @@ class AgentRunner extends events_1.EventEmitter {
             // Auto-forward result text to channel if agent didn't call reply tool.
             let replyCalled = false;
             let replyToolUseId = null; // track id to detect failed tool calls
+            // Reply tool_use blocks re-appear across cumulative `assistant` snapshots
+            // exactly like line_image ones, so a repeat is skipped by block id rather
+            // than by `replyCalled`. Gating on the flag also froze `replyToolUseId` on
+            // the turn's FIRST reply call, so a LATER call's failure never matched the
+            // unblock below and the turn's final message was dropped silently (#422).
+            const seenReplyToolIds = new Set();
+            // Set when a reply tool call failed this turn. The fallback forward must
+            // then reach the channel even though an EARLIER successful reply in the
+            // same turn already wrote a `.replied` marker carrying this turn's id —
+            // see writeAutoForward()'s forceDeliver argument.
+            let replySendFailed = false;
             // line_image tool_use blocks re-appear across cumulative `assistant` stream
             // snapshots (--include-partial-messages), so dedupe history inserts by the
             // block id — otherwise one sent image lands in the transcript N times and
@@ -1438,6 +1497,14 @@ class AgentRunner extends events_1.EventEmitter {
             // so the result's plain-text auto-forward is skipped (no duplicate message).
             let menuSentThisTurn = false;
             let menuPromptTextThisTurn = '';
+            // Text of the most recent assistant message this turn. Used only as a
+            // fallback when the turn's `result` is an empty string — some backends
+            // (OpenRouter) stream the answer as assistant text and then close the turn
+            // with `result: ""`, which would otherwise leave the history DB with no row
+            // for the reply. Replaced, never appended: assistant messages arrive as
+            // cumulative snapshots, so the last one is the complete text (same
+            // semantics as `result`).
+            let lastAssistantTextThisTurn = '';
             let typingDoneTimer = null;
             const TYPING_DONE_DELAY_MS = 3000;
             const replyToolName = source === 'discord'
@@ -1459,6 +1526,12 @@ class AgentRunner extends events_1.EventEmitter {
                     if (obj['type'] === 'assistant') {
                         const msg = obj['message'];
                         if (Array.isArray(msg?.content)) {
+                            const textThisMessage = msg.content
+                                .filter((b) => b.type === 'text' && typeof b.text === 'string')
+                                .map((b) => b.text)
+                                .join('');
+                            if (textThisMessage.trim())
+                                lastAssistantTextThisTurn = textThisMessage;
                             for (const block of msg.content) {
                                 // Skill-learning: count every tool_use this turn (deduped by block
                                 // id inside the manager, since cumulative assistant snapshots re-emit
@@ -1492,9 +1565,22 @@ class AgentRunner extends events_1.EventEmitter {
                                         });
                                     }
                                 }
-                                if (block.type === 'tool_use' && block.name === replyToolName && !replyCalled) {
+                                if (block.type === 'tool_use' && block.name === replyToolName) {
+                                    // The block comes off the CLI's stdout — validate the id rather
+                                    // than casting, so a malformed one degrades to the flag check
+                                    // instead of poisoning the Set with a non-string key.
+                                    const rawBlockId = block['id'];
+                                    const replyBlockId = typeof rawBlockId === 'string' && rawBlockId ? rawBlockId : null;
+                                    // Skip a re-emitted snapshot of a block already handled. Blocks
+                                    // with no id fall back to the old flag check, which is the best
+                                    // dedup available without an id.
+                                    const alreadyHandled = replyBlockId !== null ? seenReplyToolIds.has(replyBlockId) : replyCalled;
+                                    if (alreadyHandled)
+                                        continue;
+                                    if (replyBlockId !== null)
+                                        seenReplyToolIds.add(replyBlockId);
                                     replyCalled = true;
-                                    replyToolUseId = block['id'] ?? null;
+                                    replyToolUseId = replyBlockId;
                                     // Persist the reply text to history so it appears in chat history API
                                     const replyText = typeof block.input?.['text'] === 'string' ? block.input['text'].trim() : '';
                                     // Capture any images the reply attached (reply tool's `files`)
@@ -1535,6 +1621,7 @@ class AgentRunner extends events_1.EventEmitter {
                                 if (block.type === 'tool_result' && block.tool_use_id === replyToolUseId && block.is_error) {
                                     replyCalled = false;
                                     replyToolUseId = null;
+                                    replySendFailed = true;
                                 }
                             }
                         }
@@ -1652,10 +1739,12 @@ class AgentRunner extends events_1.EventEmitter {
                         // Detect Anthropic API socket drop — Claude CLI emits this as is_error:false
                         // with "API Error: The socket connection was closed unexpectedly". The error
                         // bypasses the replyCalled gate so the user always gets notified, even when
-                        // the agent already called the reply tool earlier in the same turn.
+                        // the agent already called the reply tool earlier in the same turn — hence
+                        // forceDeliver, or that earlier reply's `.replied` marker would dedup this
+                        // notice away and defeat the bypass (#422).
                         const isSocketError = !proc.queryMode && resultText.includes(ANTHROPIC_SOCKET_ERROR);
                         if (isSocketError) {
-                            this.writeAutoForward(mapKey, '⚡ Connection to Anthropic API dropped. Please resend your message.');
+                            this.writeAutoForward(mapKey, '⚡ Connection to Anthropic API dropped. Please resend your message.', 'text', true);
                         }
                         // Bug B: headless (claude --print) reports a too-large request as a
                         // synthetic `result` (is_error + "Request too large (max"), NOT as the
@@ -1697,8 +1786,26 @@ class AgentRunner extends events_1.EventEmitter {
                                 forwardableText = '';
                             }
                         }
-                        if (!isSocketError && !isRequestTooLarge && forwardableText && !proc.queryMode && !replyCalled && !isThinkingCorruption) {
-                            const text = forwardableText;
+                        // A backend that closes the turn with `result: ""` after streaming the
+                        // answer as assistant text (OpenRouter) leaves nothing to store here.
+                        // SessionProcess still appends that text to the session JSON, so the
+                        // history DB would be the only layer missing the reply — and the
+                        // cross-channel producer used to hide that by writing a second copy of
+                        // every reply (see sendMessageToSession's done()). Persist the fallback
+                        // instead, but only for the shape it was written for: an *empty* result
+                        // ending a whole turn on the headless backend.
+                        //   • A menu turn is excluded because `forwardableText` above may have
+                        //     been blanked on purpose — falling back there would resurrect the
+                        //     option list the strip removed and duplicate the prompt row
+                        //     already inserted when the menu was rendered.
+                        //   • pty-shell is excluded because its `result` fires per sub-turn, so
+                        //     every tool-call boundary with an empty result would add a phantom
+                        //     row of that sub-turn's narration.
+                        // Forwarding deliberately keeps using forwardableText alone: recovering
+                        // a missing history row is not a reason to post a new channel message.
+                        const canFallBack = !menuSentThisTurn && proc.backend !== 'pty-shell';
+                        const persistableText = forwardableText || (canFallBack ? lastAssistantTextThisTurn.trim() : '');
+                        if (!isSocketError && !isRequestTooLarge && persistableText && !proc.queryMode && !replyCalled && !isThinkingCorruption) {
                             const channelSrcForResult = this.channelSourceMap.get(mapKey) ?? 'telegram';
                             // Persist assistant reply to permanent history DB
                             this.historyDb.insertMessage({
@@ -1706,39 +1813,44 @@ class AgentRunner extends events_1.EventEmitter {
                                 sessionId: actualSessionId,
                                 source: channelSrcForResult,
                                 role: 'assistant',
-                                content: text,
+                                content: persistableText,
                                 ts: Date.now(),
                             });
-                            // Forward to channel. LINE has no .forward consumer — the gateway
-                            // delivers via LineReplyManager (free reply, or cache + postback
-                            // button when slow) instead of writeAutoForward.
-                            const channelText = (0, markdown_1.normalizeTelegramLineBreaks)(text);
-                            if (channelSrcForResult === 'line' && this.lineReply) {
-                                void this.lineReply.onAnswer(mapKey, channelText);
-                            }
-                            else if (channelSrcForResult !== 'discord' &&
-                                channelSrcForResult !== 'slack' &&
-                                ((0, markdown_1.hasMarkdown)(channelText) || (0, markdown_1.containsTelegramHtml)(channelText))) {
-                                // Telegram HTML entities — Slack has its own mrkdwn format and
-                                // would display these tags literally, so Slack skips this and
-                                // falls through to the plain-text branch below.
-                                this.writeAutoForward(mapKey, (0, markdown_1.toTelegramHtml)(channelText), 'html');
-                            }
-                            else {
-                                this.writeAutoForward(mapKey, channelText);
+                            if (forwardableText) {
+                                // Forward to channel. LINE has no .forward consumer — the gateway
+                                // delivers via LineReplyManager (free reply, or cache + postback
+                                // button when slow) instead of writeAutoForward.
+                                const channelText = (0, markdown_1.normalizeTelegramLineBreaks)(forwardableText);
+                                if (channelSrcForResult === 'line' && this.lineReply) {
+                                    void this.lineReply.onAnswer(mapKey, channelText);
+                                }
+                                else if (channelSrcForResult !== 'discord' &&
+                                    channelSrcForResult !== 'slack' &&
+                                    ((0, markdown_1.hasMarkdown)(channelText) || (0, markdown_1.containsTelegramHtml)(channelText))) {
+                                    // Telegram HTML entities — Slack has its own mrkdwn format and
+                                    // would display these tags literally, so Slack skips this and
+                                    // falls through to the plain-text branch below.
+                                    this.writeAutoForward(mapKey, (0, markdown_1.toTelegramHtml)(channelText), 'html', replySendFailed);
+                                }
+                                else {
+                                    this.writeAutoForward(mapKey, channelText, 'text', replySendFailed);
+                                }
+                                // Assistant output reached the channel — mark the turn delivered so
+                                // a later recovery does not resend a message that was answered (C1).
+                                const lt = this.lastTurn.get(mapKey);
+                                if (lt)
+                                    lt.delivered = true;
                             }
-                            // Assistant output reached the channel — mark the turn delivered so
-                            // a later recovery does not resend a message that was answered (C1).
-                            const lt = this.lastTurn.get(mapKey);
-                            if (lt)
-                                lt.delivered = true;
                         }
                         replyCalled = false; // reset for next turn
                         replyToolUseId = null;
+                        replySendFailed = false;
+                        seenReplyToolIds.clear();
                         seenLineImageIds.clear();
                         pendingLineImageMedia.clear();
                         menuSentThisTurn = false;
                         menuPromptTextThisTurn = '';
+                        lastAssistantTextThisTurn = '';
                         // In pty-shell mode, a `result` fires after every Claude API sub-turn
                         // (there can be many per user message, separated by tool-call gaps of
                         // arbitrary length). Starting the typing-done timer here would stop
@@ -2462,7 +2574,7 @@ class AgentRunner extends events_1.EventEmitter {
         }
         this.pendingRestarts.add(chatId);
     }
-    writeAutoForward(chatId, text, format = 'text') {
+    writeAutoForward(chatId, text, format = 'text', forceDeliver = false) {
         // LINE has no .forward consumer — route through LineReplyManager's push path.
         if (this.channelFor(chatId) === 'line') {
             if (this.lineReply)
@@ -2498,6 +2610,11 @@ class AgentRunner extends events_1.EventEmitter {
             // state) must both reach the user, not have the second clobber the
             // first. turnId is the live typing-signal timestamp — the receiver uses
             // it to scope the `.replied` dedup marker to the turn that wrote it.
+            // forceDeliver writes a null turnId instead: `isEntryAlreadyReplied()`
+            // never matches a null on either side, so the entry survives a `.replied`
+            // marker left by an EARLIER successful reply in this same turn. Used for
+            // text that is NOT the one that marker covers — a fallback forward after a
+            // reply call failed, and the socket-drop notice (#422).
             let entries = [];
             try {
                 const raw = fs.readFileSync(forwardPath, 'utf8').trim();
@@ -2516,7 +2633,7 @@ class AgentRunner extends events_1.EventEmitter {
             catch {
                 // No existing file — fresh queue.
             }
-            entries.push({ text, format, turnId: this.readCurrentTurnId(chatId) });
+            entries.push({ text, format, turnId: forceDeliver ? null : this.readCurrentTurnId(chatId) });
             // Atomic write (tmp + rename): the receiver polls this directory on
             // every typing tick, so a non-atomic write could be read mid-flush.
             const tmpPath = `${forwardPath}.tmp`;
@@ -2697,6 +2814,8 @@ class AgentRunner extends events_1.EventEmitter {
             clearTimeout(buf.timer);
         }
         this.channelCoalesce.clear();
+        // Drops every turn record and its replay-grace timer (#421).
+        this.turnStreams.clear();
         // Receiver teardown now resolves only once the child has exited, so it must
         // be awaited or shutdown() can exit the gateway out from under a receiver
         // that is still shutting down (issue #405). Run it concurrently with session
@@ -2921,14 +3040,14 @@ class AgentRunner extends events_1.EventEmitter {
                 }
                 resolve({ text: finalText, attachments });
             };
-            const fail = (err) => {
+            const fail = (err, partialText) => {
                 if (settled)
                     return;
                 settled = true;
                 // Terminal close for a turn that produced no result (#75): record it so
                 // history does not end on a dangling user message, and drain the
                 // attachment buffer so nothing leaks into the next turn.
-                this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage);
+                this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage, partialText);
                 cleanup();
                 reject(err); // no-op when the soft timeout already rejected
             };
@@ -2950,7 +3069,10 @@ class AgentRunner extends events_1.EventEmitter {
                     done(buffer.join(''), true);
                     return;
                 }
-                fail(Object.assign(new Error('Session process exited unexpectedly before responding.'), { code: 'PROCESS_EXITED' }));
+                // Whatever streamed before the crash is real work the caller may already
+                // have read; persist it alongside the notice rather than replacing it,
+                // exactly as the hard cap below does.
+                fail(Object.assign(new Error('Session process exited unexpectedly before responding.'), { code: 'PROCESS_EXITED' }), buffer.join(''));
             };
             const cleanup = () => {
                 clearTimeout(globalTimer);
@@ -3019,10 +3141,17 @@ class AgentRunner extends events_1.EventEmitter {
             // bounds a genuinely hung turn.
             let hardCapTimer;
             const globalTimer = setTimeout(() => {
-                reject(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+                // TIMEOUT_SOFT: the caller's budget elapsed, the turn has not. The hard
+                // cap below rejects nobody — the promise is already settled — but it
+                // does stop the turn, so only IT gets the terminal TIMEOUT.
+                reject(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT_SOFT' }));
                 hardCapTimer = setTimeout(() => {
+                    // Interrupt before clearing the processing flag — interrupt() no-ops
+                    // once `_processing` is false. See the streaming path for why the cap
+                    // stops the turn instead of only detaching from it.
+                    session.interrupt();
                     session.setProcessing(false);
-                    fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }));
+                    fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }), buffer.join(''));
                 }, API_TIMEOUT_HARD_CAP_EXTRA_MS);
             }, opts.timeoutMs);
             session.on('output', onOutput);
@@ -3038,7 +3167,9 @@ class AgentRunner extends events_1.EventEmitter {
      * Send a message to an API session and stream back events via callbacks.
      *
      * Returns a disconnect handler for the caller to wire to the SSE close event.
-     * On client disconnect the stream continues server-side until the result is saved to DB.
+     * It detaches this caller's sink; the turn keeps running, keeps buffering, and
+     * stays re-attachable via attachTurnStream() until the replay grace window
+     * expires (#421).
      */
     async sendApiMessageStream(sessionId, chatId, message, callbacks, opts) {
         if (this.pendingApiSessions.has(sessionId)) {
@@ -3092,17 +3223,12 @@ class AgentRunner extends events_1.EventEmitter {
         session.touch();
         const buffer = [];
         let settled = false;
-        let clientGone = false;
-        // onError must fire at most once per turn. The soft timeout notifies the
-        // client directly (below) WITHOUT setting `settled`, so the later hard-cap
-        // fail() would otherwise call onError a second time.
-        let errorNotified = false;
-        const notifyError = (err) => {
-            if (errorNotified)
-                return;
-            errorNotified = true;
-            callbacks.onError(err);
-        };
+        // The turn's event buffer. Every emission below records into it whether or
+        // not anyone is listening; the sink decides only what reaches a socket, so a
+        // disconnect no longer costs the client the rest of the turn (#421).
+        const turn = this.turnStreams.start((0, turn_stream_1.turnStreamKey)('api', sessionId), opts.requestId ?? (0, crypto_1.randomUUID)());
+        const initialSink = (0, turn_stream_1.callbackSink)(callbacks);
+        turn.attach(initialSink, 0);
         // Track partial message text for delta computation (--include-partial-messages)
         let lastPartialText = '';
         // Accumulate tool_use blocks from stream_event (content_block_start → delta → stop)
@@ -3148,9 +3274,9 @@ class AgentRunner extends events_1.EventEmitter {
                     ts: streamAssistantTs,
                 });
             }
-            callbacks.onDone(finalText, attachments);
+            this.turnStreams.complete(turn, (0, turn_stream_1.resultEvent)(finalText, attachments));
         };
-        const fail = (err) => {
+        const fail = (err, partialText) => {
             if (settled)
                 return;
             settled = true;
@@ -3159,8 +3285,8 @@ class AgentRunner extends events_1.EventEmitter {
             // history does not end on a dangling user message (the web reads that
             // state as "still thinking" and spins forever), and drain the attachment
             // buffer so nothing leaks into the next turn.
-            this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage);
-            notifyError(err);
+            this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage, partialText);
+            this.turnStreams.complete(turn, (0, turn_stream_1.errorEvent)(err), err);
         };
         // The subprocess died without ever emitting a final `result` line (crash,
         // an unexpected signal — distinct from a graceful /stop, whose SIGINT
@@ -3180,7 +3306,11 @@ class AgentRunner extends events_1.EventEmitter {
                 done(buffer.join(''), true);
                 return;
             }
-            fail(Object.assign(new Error('Session process exited unexpectedly before responding.'), { code: 'PROCESS_EXITED' }));
+            // Whatever streamed before the crash is real work the client may already
+            // have rendered; persist it alongside the notice rather than replacing it,
+            // exactly as the hard cap below does. A crash is the case partialText was
+            // added for — the client saw the deltas and no `result` will ever land.
+            fail(Object.assign(new Error('Session process exited unexpectedly before responding.'), { code: 'PROCESS_EXITED' }), buffer.join(''));
         };
         const cleanup = () => {
             clearTimeout(globalTimer);
@@ -3190,9 +3320,12 @@ class AgentRunner extends events_1.EventEmitter {
             session.off('exit', onExit);
             this.pendingApiSessions.delete(sessionId);
         };
-        // Called when the SSE client disconnects. Marks clientGone so SSE writes
-        // fail silently, but keeps onOutput listening so the result is still saved to DB.
-        const onClientDisconnect = () => { clientGone = true; };
+        // Called when the SSE client disconnects. Detaches that connection's sink —
+        // the producer below keeps recording, so a re-attach can still deliver
+        // everything that arrived while nobody was listening (#421). Passing the
+        // sink means a stale close from a superseded connection cannot silence the
+        // one that replaced it.
+        const onClientDisconnect = () => { turn.detach(initialSink); };
         const onOutput = (line) => {
             try {
                 const obj = JSON.parse(line);
@@ -3207,15 +3340,13 @@ class AgentRunner extends events_1.EventEmitter {
                                 fullText += block.text;
                             // PTY mode (headless=false) emits tool_use blocks inside assistant messages
                             if (block.type === 'tool_use' && block.name && block.id) {
-                                if (!clientGone)
-                                    callbacks.onChunk({ type: 'tool_use', name: block.name, id: block.id, input: block.input });
+                                turn.emit({ type: 'tool_use', name: block.name, id: block.id, input: block.input });
                             }
                         }
                         if (fullText.length > lastPartialText.length) {
                             const delta = fullText.slice(lastPartialText.length);
                             buffer.push(delta);
-                            if (!clientGone)
-                                callbacks.onChunk({ type: 'text_delta', text: delta });
+                            turn.emit({ type: 'text_delta', text: delta });
                         }
                         lastPartialText = fullText;
                     }
@@ -3225,34 +3356,27 @@ class AgentRunner extends events_1.EventEmitter {
                     const text = obj['text'] ?? '';
                     if (text) {
                         buffer.push(text);
-                        if (!clientGone)
-                            callbacks.onChunk({ type: 'text_delta', text });
+                        turn.emit({ type: 'text_delta', text });
                     }
                 }
                 // stream_event from --output-format stream-json (tool_use + text_delta)
-                this._applyStreamEvent(obj, toolBlocks, clientGone ? () => { } : callbacks.onChunk, (text) => {
+                this._applyStreamEvent(obj, toolBlocks, (event) => turn.emit(event), (text) => {
                     buffer.push(text);
                     // Update lastPartialText so the final 'assistant' message won't re-send the full text
                     lastPartialText += text;
-                    if (!clientGone)
-                        callbacks.onChunk({ type: 'text_delta', text });
+                    turn.emit({ type: 'text_delta', text });
                 });
                 // Text from delta field (other formats)
                 if (obj['type'] !== 'assistant' && obj['type'] !== 'text' && obj['type'] !== 'result' && obj['type'] !== 'stream_event') {
                     const deltaText = obj['delta']?.['text'];
                     if (deltaText) {
                         buffer.push(deltaText);
-                        if (!clientGone)
-                            callbacks.onChunk({ type: 'text_delta', text: deltaText });
+                        turn.emit({ type: 'text_delta', text: deltaText });
                     }
                 }
                 // Thinking
                 if (obj['type'] === 'thinking') {
-                    if (!clientGone)
-                        callbacks.onChunk({
-                            type: 'thinking',
-                            text: obj['text'] ?? '',
-                        });
+                    turn.emit({ type: 'thinking', text: obj['text'] ?? '' });
                 }
                 // Result = end of turn
                 if (obj['type'] === 'result') {
@@ -3272,25 +3396,40 @@ class AgentRunner extends events_1.EventEmitter {
                 /* non-JSON stdout line */
             }
         };
-        // Soft timeout (#75): tell the SSE client now, but KEEP the output listener
-        // attached — exactly like onClientDisconnect — so a turn that finishes a few
-        // seconds past the budget still lands in history with its attachments
+        // Soft timeout (#75, reworked in #421): tell the client the budget elapsed,
+        // but say so with a NON-terminal `timeout` event rather than an `error`. The
+        // turn is not cancelled — the output listener stays attached so a turn that
+        // finishes a few seconds late still lands in history with its attachments
         // (observed: 304s image turn vs 300s budget → image generated, reply lost,
-        // spinner stuck). The hard cap bounds a genuinely hung turn.
+        // spinner stuck) — and the buffer keeps recording, so whether the client
+        // stays on this connection or reconnects to …/stream, it still gets the
+        // reply. Reporting a still-running turn as `error` was the bug: history
+        // gained a message no live client could ever see. The hard cap below bounds
+        // a genuinely hung turn and IS a real error.
         let hardCapTimer;
         const globalTimer = setTimeout(() => {
-            clientGone = true;
-            try {
-                notifyError(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
-            }
-            catch { /* client already gone */ }
+            turn.emit({ type: 'timeout', message: 'Agent response timeout', resumable: true });
             // The session stays in-flight (pendingApiSessions) until the hard cap so a
             // retry on the SAME session_id gets a 409 CONFLICT rather than interleaving
             // with the subprocess that is still processing this turn. This lock is
-            // intentionally held for the whole soft→hard window (see API.md §409).
+            // intentionally held for the whole soft→hard window (see API.md §409) —
+            // resuming the turn goes through …/stream, which is never a conflict.
             hardCapTimer = setTimeout(() => {
+                // Genuinely end the turn rather than just unsubscribing from it. The old
+                // cleanup() only did `session.off('output')`, so past the cap the
+                // subprocess kept running and kept burning tokens while its eventual
+                // `result` line was parsed by nobody — the worst of both worlds, and the
+                // reason the `⚠️` row this writes could contradict a turn that was still
+                // alive. After the interrupt the row is simply true.
+                //
+                // ORDER MATTERS: interrupt() gates on `_processing` and no-ops once it
+                // is false, so it must come BEFORE setProcessing(false).
+                session.interrupt();
                 session.setProcessing(false);
-                fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }));
+                // Whatever the turn did stream before the cap is real work the client
+                // may already have rendered; persist it alongside the notice instead of
+                // replacing it, exactly as the /stop path does.
+                fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }), buffer.join(''));
             }, API_TIMEOUT_HARD_CAP_EXTRA_MS);
         }, opts.timeoutMs);
         session.on('output', onOutput);
@@ -3342,6 +3481,53 @@ class AgentRunner extends events_1.EventEmitter {
     hasActiveApiSession(sessionId) {
         return this.pendingApiSessions.has(sessionId);
     }
+    /**
+     * Attach a sink to a session's current turn stream (#421) — the server half of
+     * "resume a turn on a new connection".
+     *
+     * Replays every buffered event after `afterSeq` and then, if the turn is still
+     * running, installs `sink` as the live one. Both happen in one synchronous
+     * block inside TurnStream.attach, so nothing can slip through the seam.
+     *
+     * Returns a `detach` handler on success, or a reason the attach could not be
+     * honoured:
+     *  - `gone`      — no record: the turn never existed, or its replay grace
+     *                  window has expired. The client should read history instead.
+     *  - `mismatch`  — a record exists but for a different request_id, i.e. the
+     *                  turn the client asked for is already over.
+     *  - `truncated` — a non-zero cursor sits inside a region the bounded buffer
+     *                  has already evicted, so a gapless replay is impossible. A
+     *                  cursor-less attach is never truncated: it has no seam to
+     *                  keep, and takes whatever tail is still buffered.
+     *
+     * Looks only under the `api` namespace: this is the API resume endpoint, and a
+     * channel turn on the same session id is a different turn (see turnStreamKey).
+     */
+    attachTurnStream(sessionId, sink, opts = {}) {
+        const turn = this.turnStreams.get((0, turn_stream_1.turnStreamKey)('api', sessionId));
+        if (!turn)
+            return { ok: false, reason: 'gone' };
+        if (opts.requestId && opts.requestId !== turn.requestId)
+            return { ok: false, reason: 'mismatch' };
+        const failure = turn.attach(sink, opts.afterSeq ?? 0);
+        if (failure)
+            return { ok: false, reason: failure };
+        return { ok: true, requestId: turn.requestId, detach: () => turn.detach(sink) };
+    }
+    /**
+     * Identity and wall-clock start of the session's current API turn, or undefined
+     * when there is no resumable record.
+     *
+     * The resume endpoint needs both *before* it attaches, because attach() replays
+     * synchronously into a sink built from them: `startedAt` so a replayed terminal
+     * frame reports `duration_ms` for the turn rather than for the reconnect, and
+     * `requestId` so a client that reconnected without one still learns the token it
+     * needs to resume again from a cursor.
+     */
+    turnStreamInfo(sessionId) {
+        const turn = this.turnStreams.get((0, turn_stream_1.turnStreamKey)('api', sessionId));
+        return turn ? { requestId: turn.requestId, startedAt: turn.startedAt } : undefined;
+    }
     /**
      * Register file paths as attachments for the current API session turn.
      * Called by the api_reply MCP tool via the attachments endpoint.
@@ -3362,13 +3548,19 @@ class AgentRunner extends events_1.EventEmitter {
      * assistant row so history never ends on a dangling user message.
      * System-initiated turns (skipUserMessage) have nothing dangling to close —
      * only the buffer is drained.
+     *
+     * `partialText` is whatever the turn already streamed before it died. It is
+     * prepended rather than discarded, so the single row this writes carries both
+     * the work the client saw and the notice — never a failure row that erases a
+     * half-finished reply, and never a failure row *plus* a separate reply row
+     * (the callers' `settled` guard makes done() and fail() mutually exclusive).
      */
-    persistFailedApiTurn(chatId, sessionId, err, skipUserMessage) {
+    persistFailedApiTurn(chatId, sessionId, err, skipUserMessage, partialText) {
         const attachments = this.popApiAttachments(sessionId);
         if (skipUserMessage)
             return;
         const failTs = Date.now();
-        const content = `\u26a0\ufe0f ${err.message}`;
+        const content = [partialText?.trim(), `\u26a0\ufe0f ${err.message}`].filter(Boolean).join('\n\n');
         this.sessionStore
             .appendMessage(this.agentConfig.id, sessionId, { role: 'assistant', content, ts: failTs })
             .catch(() => { });
@@ -3694,6 +3886,14 @@ class AgentRunner extends events_1.EventEmitter {
     async listApiSessions(chatId) {
         return this.sessionStore.listSessions(this.agentConfig.id, chatId, 'api');
     }
+    /**
+     * Does `sessionId` already exist under `chatId`? The API layer calls this before
+     * honouring a client-supplied `session_id`, so an unknown id is rejected instead
+     * of silently becoming a brand-new session. Read-only — it never registers.
+     */
+    async apiSessionExists(chatId, sessionId) {
+        return this.sessionStore.apiSessionExists(this.agentConfig.id, chatId, sessionId);
+    }
     async createApiSession(chatId, prompt, name) {
         const sessionName = name ?? (prompt
             ? (prompt.length > 60 ? `${prompt.slice(0, 60)}...` : prompt)
@@ -3763,7 +3963,10 @@ class AgentRunner extends events_1.EventEmitter {
     /**
      * Send a message into an existing channel session (cross-channel continuation from UI).
      * The session process receives full history context from the session JSON (Layer 1).
-     * The reply is streamed back via SSE callbacks and persisted to history DB.
+     * The reply is streamed back via SSE callbacks; persistence is *not* this
+     * method's job. A channel session already has two session-bound writers — the
+     * long-lived output handler installed in spawnSession, and SessionProcess's own
+     * parser — and writing here as well produced a second row per turn. See done().
      */
     async sendMessageToSession(rawChatId, channel, sessionId, message, senderName, callbacks, opts) {
         // Ensure the session process uses the correct channel source
@@ -3788,38 +3991,54 @@ class AgentRunner extends events_1.EventEmitter {
         });
         const buffer = [];
         let settled = false;
-        let clientGone = false;
         let lastPartialText = '';
+        // Same event plumbing as the API path (#421) — one mechanism, not a
+        // per-producer copy. The key is namespaced per producer (turnStreamKey), so
+        // a channel turn and an API turn on one session id cannot displace each
+        // other's record. Re-attaching is *not* part of the deal here: the resume
+        // endpoint looks under `api` only, so this record exists to drive the live
+        // sink and is released the moment the turn ends (see done()/fail()).
+        const turn = this.turnStreams.start((0, turn_stream_1.turnStreamKey)(channel, sessionId), opts.requestId ?? (0, crypto_1.randomUUID)());
+        const initialSink = (0, turn_stream_1.callbackSink)(callbacks);
+        turn.attach(initialSink, 0);
         const toolBlocks = new Map();
         const done = (result) => {
             if (settled)
                 return;
             settled = true;
             cleanup();
-            if (result.trim()) {
-                const uiAssistantTs = Date.now();
-                this.sessionStore.appendTelegramMessage(this.agentConfig.id, rawChatId, sessionId, {
-                    role: 'assistant',
-                    content: result.trim(),
-                    ts: uiAssistantTs,
-                }, channel).catch(() => { });
-                this.historyDb.insertMessage({
-                    chatId: `${channel}-${rawChatId}`,
-                    sessionId,
-                    source: channel,
-                    role: 'assistant',
-                    content: result.trim(),
-                    ts: uiAssistantTs,
-                });
-            }
-            callbacks.onDone(result.trim());
+            // Deliberately does NOT persist the reply. This turn targets a *channel*
+            // session, and channel sessions already have two writers that are bound to
+            // the session rather than to this turn:
+            //   • history DB  — the long-lived proc.on('output') handler installed in
+            //     spawnSession, which writes either the reply-tool text or the result
+            //     text (and deliberately suppresses socket errors, request_too_large
+            //     and corrupted-thinking output).
+            //   • session JSON — SessionProcess's own parser, which appends for every
+            //     `source !== 'api'` session.
+            // Writing here as well produced two rows per cross-channel turn, and after
+            // a reply-tool turn the second row held the model's trailing `result`
+            // narration — text the user never received on the channel. The API path
+            // (sendApiMessage*) still persists its own reply: there neither writer
+            // exists, because `source === 'api'` disables SessionProcess's append and
+            // API sessions get no channel output handler.
+            //
+            // No-op once the soft timeout has answered: TurnStream.complete() keeps
+            // its first terminal frame.
+            //
+            // Released rather than kept for the replay grace window: this turn is filed
+            // under the channel namespace and attachTurnStream() only looks under `api`,
+            // so nothing can re-attach to it. See API.md — the live view is documented
+            // as non-resumable, and holding its buffer for two minutes would cost
+            // memory no client can spend.
+            this.turnStreams.completeAndRelease(turn, (0, turn_stream_1.resultEvent)(result.trim(), []));
         };
         const fail = (err) => {
             if (settled)
                 return;
             settled = true;
             cleanup();
-            callbacks.onError(err);
+            this.turnStreams.completeAndRelease(turn, (0, turn_stream_1.errorEvent)(err), err);
         };
         let globalTimer;
         const cleanup = () => {
@@ -3827,7 +4046,7 @@ class AgentRunner extends events_1.EventEmitter {
                 clearTimeout(globalTimer);
             session.off('output', onOutput);
         };
-        const onClientDisconnect = () => { clientGone = true; };
+        const onClientDisconnect = () => { turn.detach(initialSink); };
         const onOutput = (line) => {
             try {
                 const obj = JSON.parse(line);
@@ -3840,15 +4059,13 @@ class AgentRunner extends events_1.EventEmitter {
                                 fullText += block.text;
                             // PTY mode (headless=false) emits tool_use blocks inside assistant messages
                             if (block.type === 'tool_use' && block.name && block.id) {
-                                if (!clientGone)
-                                    callbacks.onChunk({ type: 'tool_use', name: block.name, id: block.id, input: block.input });
+                                turn.emit({ type: 'tool_use', name: block.name, id: block.id, input: block.input });
                             }
                         }
                         if (fullText.length > lastPartialText.length) {
                             const delta = fullText.slice(lastPartialText.length);
                             buffer.push(delta);
-                            if (!clientGone)
-                                callbacks.onChunk({ type: 'text_delta', text: delta });
+                            turn.emit({ type: 'text_delta', text: delta });
                         }
                         lastPartialText = fullText;
                     }
@@ -3857,17 +4074,15 @@ class AgentRunner extends events_1.EventEmitter {
                     const text = obj['text'] ?? '';
                     if (text) {
                         buffer.push(text);
-                        if (!clientGone)
-                            callbacks.onChunk({ type: 'text_delta', text });
+                        turn.emit({ type: 'text_delta', text });
                     }
                 }
                 // stream_event from --output-format stream-json (tool_use + text_delta)
-                this._applyStreamEvent(obj, toolBlocks, clientGone ? () => { } : callbacks.onChunk, (text) => {
+                this._applyStreamEvent(obj, toolBlocks, (event) => turn.emit(event), (text) => {
                     buffer.push(text);
                     // Update lastPartialText so the final 'assistant' message won't re-send the full text
                     lastPartialText += text;
-                    if (!clientGone)
-                        callbacks.onChunk({ type: 'text_delta', text });
+                    turn.emit({ type: 'text_delta', text });
                 });
                 if (obj['type'] === 'result') {
                     session.setProcessing(false);
@@ -3880,7 +4095,17 @@ class AgentRunner extends events_1.EventEmitter {
         };
         globalTimer = setTimeout(() => {
             session.setProcessing(false);
-            fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+            // TIMEOUT_SOFT, not TIMEOUT: this path has no hard cap and no resume
+            // endpoint, so the turn keeps running with nobody listening on the wire
+            // and its result lands in history alone. The API hard cap interrupts the
+            // turn and means the opposite — see the code vocabulary on StreamEvent's
+            // `error`.
+            //
+            // Detaching this turn's listener here costs nothing: this producer no
+            // longer persists anything (see done()). The session's own long-lived
+            // output handler and SessionProcess own both storage layers and are not
+            // bound to this turn, so the late answer still lands in history.
+            fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT_SOFT' }));
         }, opts.timeoutMs);
         session.on('output', onOutput);
         const channelXml = `<channel source="ui" chat_id="${AgentRunner.escapeXmlAttr(rawChatId)}" session_id="${AgentRunner.escapeXmlAttr(sessionId)}" ` +