hammoc 1.8.3 → 1.9.0

package/packages/server/dist/services/streamHandler.js

@@ -4,8 +4,31 @@
  */
 import { correctContextWindow, sanitizeToolResultContent } from '@hammoc/shared';
 import { createLogger } from '../utils/logger.js';
+import { parseTaskNotification } from './historyParser.js';
 import { SDKMessageType, ContentBlockType, createInitialStreamingState, } from '@hammoc/shared';
 const log = createLogger('streamHandler');
+/**
+ * Bounded micro-grace (Story 38.2 AC7) for the rare case where the main Stop
+ * snapshot has not landed at the instant the result is consumed. The order probe
+ * (2026-07-08) showed the main Stop reliably LEADS the result by ~2-5ms, so this
+ * is a safety margin against the control-channel/main-stream race flipping — NOT
+ * the retired 45s follow-up grace. If Stop still never arrives (engine crash /
+ * lost control channel) the turn ends and the poller safety net covers survivors.
+ */
+export const STOP_SNAPSHOT_GRACE_MS = 250;
+/**
+ * Grace bound for a hold justified ONLY by the tracker (Stop ledger empty).
+ * Unlike a ledger hold — where the engine itself promises more work — a
+ * tracker-only hold waits for a queued notification to inject and its follow-up
+ * generation to start streaming. Injection lands within milliseconds of the
+ * Stop; the follow-up's first stream event needs an API roundtrip (TTFT, which
+ * can stretch on heavy contexts/retries). Each notification sighting re-arms the
+ * window; the first main-chain generation activity cancels it (normal hold until
+ * the next result takes over). Expiry ends the turn — covers stopped/failed
+ * notifications that never produce a follow-up, and tracker entries whose
+ * notification never arrives (engine stall → poller net territory).
+ */
+export const TRACKER_HOLD_GRACE_MS = 30_000;
 // Intentionally duplicated in chatService.ts for file independence
 function extractContextWindow(modelUsage) {
     if (!modelUsage)
@@ -28,12 +51,79 @@ export class StreamHandler {
     receivedStreamTextDelta = false;
     /** Whether stream_event thinking deltas have been received (to avoid duplicate thinking from assistant messages) */
     receivedStreamThinkingDelta = false;
+    /**
+     * Stable per-text-block chunk id. Every delta of ONE text block must carry the
+     * SAME messageId: the client re-attaches a delta to its block's segment by id
+     * when another card (e.g. a background subagent's tool activity) lands between
+     * two deltas — with a fresh id per delta the split is unrecoverable. The block
+     * key is (main-chain API message generation, content block index): indexes
+     * restart per API message, so message_start advances the generation.
+     */
+    apiMessageGeneration = 0;
+    currentTextBlockKey = null;
+    currentTextBlockMessageId = null;
+    /** Same contract for thinking blocks (kept separate — thinking and text never share a block index). */
+    currentThinkingBlockKey = null;
+    currentThinkingBlockMessageId = null;
     /** Throttle tracker: last emit time per tool ID for partial input updates */
     lastPartialEmitByTool = new Map();
     /** Running estimate of context window token consumption (updated from assistant usage + tool results) */
     estimatedContextTokens = 0;
     /** Known context window size from modelUsage (0 until first result arrives) */
     contextWindowSize = 0;
+    /**
+     * Turn-boundary source of truth for background work (Story 38.2). When set, a
+     * `result` message only ENDS THE TURN if the engine's Stop hook reports nothing
+     * in flight (`hadInFlight === false`) — otherwise the stream is held open so the
+     * completion notification, the engine's auto-resume follow-up generation, and the
+     * further result(s) arrive LIVE (probe-verified on bundled SDK 0.3.191: the
+     * generator keeps delivering and ends naturally after the follow-up's final
+     * result). Replaces the retired ack-marker `BackgroundTaskTracker.pending` guess.
+     */
+    stopSource;
+    /** AC7 micro-grace bound (overridable for deterministic tests). */
+    stopSnapshotGraceMs = STOP_SNAPSHOT_GRACE_MS;
+    /**
+     * Second turn-boundary gate (see {@link PendingTaskSource}): tracked background
+     * tasks not yet resolved by a completion notification. A result only ends the
+     * turn when the Stop ledger is empty AND this count is 0 — the tracker covers
+     * the queued-notification window the ledger cannot see.
+     */
+    pendingSource;
+    /** Tracker-only hold grace bound (overridable for deterministic tests). */
+    trackerHoldGraceMs = TRACKER_HOLD_GRACE_MS;
+    /**
+     * Deadline (epoch ms) of an active tracker-only hold, or null. Set at an
+     * intermediate result held on the tracker gate alone; extended by each task
+     * notification (injection progressing); cancelled by main-chain generation
+     * activity (a follow-up started — the next result re-evaluates); expiry ends
+     * the turn with the held result.
+     */
+    trackerHoldDeadline = null;
+    /**
+     * Task-notification dedupe (toolUseId, or taskId fallback): the same
+     * completion can surface BOTH as a stream `system/task_notification` event and
+     * as the injected `<task-notification>` user message — onTaskNotification must
+     * fire once per task (the tracker resolution is idempotent, but UI emits are not).
+     */
+    notifiedTaskKeys = new Set();
+    /**
+     * Set when this turn ended via tracker-hold grace EXPIRY (not a clean result).
+     * The expiry path abandons an in-flight `iterator.next()` — on a RESIDENT
+     * engine that parked read sits on the SHARED session iterator and would steal
+     * the NEXT turn's first message (async-generator next() calls are FIFO), and a
+     * late follow-up could still generate invisibly. The caller (websocket
+     * residency reconciliation) MUST therefore evict the resident engine when this
+     * is set: close() settles the parked read, kills any not-yet-started follow-up
+     * (its notification is already in the JSONL — the next resumed turn sees it),
+     * and the next send resumes fresh. Non-resident engines are closed by the
+     * chatService finally anyway.
+     */
+    _trackerHoldExpired = false;
+    /** Whether this turn ended via tracker-hold grace expiry (see field docs). */
+    get trackerHoldExpired() {
+        return this._trackerHoldExpired;
+    }
     /**
      * @param is1M Whether the request runs at a 1M context window (Opus auto or an
      *   explicit Sonnet `[1m]` opt-in). Drives the contextWindow meter correction —
@@ -44,6 +134,45 @@ export class StreamHandler {
         this.is1M = is1M;
         this.state = createInitialStreamingState();
     }
+    /**
+     * Unescape a JSON string body in ONE left-to-right pass. Sequential chained
+     * `.replace()` calls consume backslashes more than once — a literal `\\n` in
+     * the source (backslash + n as DATA) collapsed into a real newline because the
+     * `\n` pass ran before the `\\` pass. Each escape must be decoded exactly once.
+     * A trailing lone backslash / truncated `\uXX` (partial stream) stays as-is.
+     */
+    static unescapeJsonString(raw) {
+        return raw.replace(/\\(u[0-9a-fA-F]{4}|.)/g, (whole, esc) => {
+            switch (esc[0]) {
+                case 'n': return '\n';
+                case 't': return '\t';
+                case 'r': return '\r';
+                case 'b': return '\b';
+                case 'f': return '\f';
+                case '"': return '"';
+                case '\\': return '\\';
+                case '/': return '/';
+                case 'u': return esc.length === 5 ? String.fromCharCode(parseInt(esc.slice(1), 16)) : whole;
+                default: return whole; // unknown escape — keep verbatim (preview only)
+            }
+        });
+    }
+    /**
+     * Index of the first UNESCAPED double quote in `raw`, or -1. Walks backslash
+     * pairs so an escaped-backslash-then-quote (source `\\"` = data `\` + CLOSING
+     * quote) is detected — a single-character lookbehind cannot distinguish it.
+     */
+    static findUnescapedQuote(raw) {
+        for (let i = 0; i < raw.length; i++) {
+            if (raw[i] === '\\') {
+                i++;
+                continue;
+            }
+            if (raw[i] === '"')
+                return i;
+        }
+        return -1;
+    }
     /**
      * Extract partial fields from incomplete JSON for streaming preview.
      * Called when JSON.parse fails during input_json_delta accumulation.
@@ -54,7 +183,7 @@ export class StreamHandler {
         // Extract file_path (should be complete early in the stream)
         const pathMatch = rawJson.match(/"file_path"\s*:\s*"((?:[^"\\]|\\.)*)"/);
         if (pathMatch)
-            result.file_path = pathMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+            result.file_path = StreamHandler.unescapeJsonString(pathMatch[1]);
         // Extract partial content (may be incomplete — no closing quote)
         const contentStart = rawJson.match(/"content"\s*:\s*"/);
         if (contentStart) {
@@ -65,24 +194,16 @@ export class StreamHandler {
                 partial = partial.slice(0, -2);
             else if (partial.endsWith('"'))
                 partial = partial.slice(0, -1);
-            // Unescape JSON string escapes
-            result.content = partial
-                .replace(/\\n/g, '\n')
-                .replace(/\\t/g, '\t')
-                .replace(/\\r/g, '\r')
-                .replace(/\\"/g, '"')
-                .replace(/\\\\/g, '\\');
+            result.content = StreamHandler.unescapeJsonString(partial);
         }
         // Extract old_string for Edit tool
         const oldStart = rawJson.match(/"old_string"\s*:\s*"/);
         if (oldStart) {
             const start = oldStart.index + oldStart[0].length;
-            // Find the closing quote (not escaped)
             const remaining = rawJson.slice(start);
-            const closeMatch = remaining.match(/(?<!\\)"/);
-            if (closeMatch) {
-                result.old_string = remaining.slice(0, closeMatch.index)
-                    .replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+            const closeIdx = StreamHandler.findUnescapedQuote(remaining);
+            if (closeIdx !== -1) {
+                result.old_string = StreamHandler.unescapeJsonString(remaining.slice(0, closeIdx));
             }
         }
         // Extract new_string for Edit tool
@@ -94,8 +215,7 @@ export class StreamHandler {
                 partial = partial.slice(0, -2);
             else if (partial.endsWith('"'))
                 partial = partial.slice(0, -1);
-            result.new_string = partial
-                .replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+            result.new_string = StreamHandler.unescapeJsonString(partial);
         }
         return Object.keys(result).length > 0 ? result : null;
     }
@@ -116,8 +236,16 @@ export class StreamHandler {
         this.lastPartialEmitByTool.clear();
         this.receivedStreamTextDelta = false;
         this.receivedStreamThinkingDelta = false;
+        this.apiMessageGeneration = 0;
+        this.currentTextBlockKey = null;
+        this.currentTextBlockMessageId = null;
+        this.currentThinkingBlockKey = null;
+        this.currentThinkingBlockMessageId = null;
         this.estimatedContextTokens = 0;
         this.contextWindowSize = 0;
+        this.trackerHoldDeadline = null;
+        this.notifiedTaskKeys.clear();
+        this._trackerHoldExpired = false;
     }
     /**
      * Generate a unique message ID for stream chunks
@@ -276,6 +404,16 @@ export class StreamHandler {
                 toolUseId: taskMsg.tool_use_id,
             };
         }
+        if (msg.subtype === 'task_started') {
+            const taskMsg = message;
+            parsed.subtype = 'task_started';
+            parsed.taskStarted = {
+                taskId: taskMsg.task_id ?? '',
+                toolUseId: taskMsg.tool_use_id,
+                description: taskMsg.description,
+                taskType: taskMsg.task_type,
+            };
+        }
         return parsed;
     }
     /**
@@ -388,8 +526,14 @@ export class StreamHandler {
     /**
      * Process a stream of SDK messages and invoke callbacks
      */
-    async processStream(generator, callbacks) {
+    async processStream(generator, callbacks, opts) {
         this.reset();
+        this.stopSource = opts?.stopSource;
+        if (opts?.stopSnapshotGraceMs !== undefined)
+            this.stopSnapshotGraceMs = opts.stopSnapshotGraceMs;
+        this.pendingSource = opts?.pendingSource;
+        if (opts?.trackerHoldGraceMs !== undefined)
+            this.trackerHoldGraceMs = opts.trackerHoldGraceMs;
         let finalResponse = {
             id: '',
             sessionId: '',
@@ -397,14 +541,40 @@ export class StreamHandler {
             done: false,
             isError: false,
         };
+        // Whether a TURN-ENDING result was processed (its onComplete already fired
+        // inside handleResult). When the loop exits without one (generator ended
+        // mid-hold — e.g. engine death), the post-loop fallback fires onComplete.
+        let finalResultSeen = false;
+        const iterator = generator[Symbol.asyncIterator]();
         try {
-            for await (const message of generator) {
-                const parsed = this.parseMessage(message);
+            for (;;) {
+                let step;
+                if (this.trackerHoldDeadline === null) {
+                    step = await iterator.next();
+                }
+                else {
+                    // Tracker-only hold: bound the wait. The abandoned next() (on expiry)
+                    // is unwound by the finally's fire-and-forget iterator.return().
+                    const raced = await StreamHandler.raceDeadline(iterator.next(), this.trackerHoldDeadline);
+                    if (raced === 'expired') {
+                        // The queued notification never turned into a live follow-up within
+                        // the grace (stopped/failed notification with no auto-resume, or an
+                        // engine stall). End the turn with the held result — the post-loop
+                        // fallback fires onComplete; the poller net covers true survivors.
+                        // `trackerHoldExpired` tells the caller to EVICT a resident engine:
+                        // the abandoned iterator.next() above is parked on the shared session
+                        // iterator and would steal the next turn's first message otherwise.
+                        this._trackerHoldExpired = true;
+                        log.warn(`tracker-hold grace expired (${this.trackerHoldGraceMs}ms, ${this.pendingSource?.pending ?? 0} task(s) still tracked) — ending the turn with the held result (resident engine will be evicted)`);
+                        callbacks.onBackgroundState?.({ waiting: false, pendingCount: 0 });
+                        break;
+                    }
+                    step = raced;
+                }
+                if (step.done)
+                    break;
+                const parsed = this.parseMessage(step.value);
                 this.processMessage(parsed, callbacks);
-                // Capture final response from result message and exit immediately.
-                // The SDK generator may not close promptly after RESULT, so waiting
-                // for the next generator.next() can hang indefinitely, leaving the
-                // queue item stuck in "pending" state even though the response is done.
                 if (parsed.type === SDKMessageType.RESULT) {
                     const resultMsg = parsed;
                     finalResponse = {
@@ -415,7 +585,39 @@ export class StreamHandler {
                         isError: resultMsg.isError,
                         usage: resultMsg.usage,
                     };
-                    break;
+                    // Dual-gate turn boundary: the engine's Stop-hook ledger (gate 1) AND
+                    // the tracked-task pending set (gate 2). The ledger answers "is work
+                    // RUNNING"; the tracker additionally covers the queued-notification
+                    // window — a completed task whose notification has not been injected
+                    // yet is invisible to the ledger but guarantees a follow-up.
+                    const inFlight = await this.resolveInFlight(resultMsg);
+                    // Single source for the amber "background:waiting" card + inactivity
+                    // timer (AC6): derived from the SAME verdict that gates the turn.
+                    callbacks.onBackgroundState?.({ waiting: inFlight.hadInFlight, pendingCount: inFlight.pendingCount });
+                    // Exit at the final result rather than waiting for generator close —
+                    // the SDK generator may not close promptly after it, and waiting
+                    // for the next generator.next() could hang indefinitely. Fire onComplete
+                    // HERE (moved out of handleResult) now that the turn-ending decision is
+                    // async: only the turn-ending result completes; intermediate holds.
+                    if (!inFlight.hadInFlight) {
+                        finalResultSeen = true;
+                        this.state.isComplete = true;
+                        callbacks.onComplete?.(finalResponse);
+                        break;
+                    }
+                    if (inFlight.trackerOnly) {
+                        // Ledger empty but tracked tasks unresolved — the queued-notification
+                        // window. Hold, but grace-bounded (see TRACKER_HOLD_GRACE_MS).
+                        this.trackerHoldDeadline = Date.now() + this.trackerHoldGraceMs;
+                        log.info(`intermediate result: Stop ledger empty but ${inFlight.trackerPending} tracked task(s) unresolved (queued-notification window) — holding with ${this.trackerHoldGraceMs}ms grace`);
+                    }
+                    else {
+                        // The engine's own ledger promises more work — unbounded hold, the
+                        // live stream delivers the follow-up (Story 38.2 behavior).
+                        this.trackerHoldDeadline = null;
+                        log.info(`intermediate result: ${inFlight.pendingCount} background task(s) in flight (Stop hook) — holding the turn open for the live follow-up`);
+                    }
+                    continue;
                 }
             }
         }
@@ -426,16 +628,118 @@ export class StreamHandler {
             throw err;
         }
         finally {
+            // Fire-and-forget close. At a yield-suspended generator this unwinds it
+            // immediately (same as for-await break did); mid-await (grace abandon)
+            // the close queues behind the in-flight next() — awaiting it here could
+            // block turn finalization on a hung engine.
+            void iterator.return?.(undefined)?.catch(() => { });
             this.cleanup();
         }
+        // Loop exited without a turn-ending result (the generator ended mid-hold —
+        // e.g. engine death). Complete the turn with the last captured result so
+        // callers finalize normally; the JSONL poller safety net (websocket/queue
+        // layer) picks up surviving tasks.
+        if (!finalResultSeen && finalResponse.done) {
+            this.state.isComplete = true;
+            callbacks.onComplete?.(finalResponse);
+        }
         return finalResponse;
     }
+    /**
+     * Whether background work is still in flight at this result — the turn-boundary
+     * verdict. Two gates, both must clear (Story 38.2 + the 2026-07-12 fix):
+     *
+     * - **Gate 1 — the engine's Stop-hook `background_tasks[]` ledger**: work the
+     *   engine reports as running/pending. Consumed per turn; if the snapshot has
+     *   not landed yet, wait a bounded micro-grace (AC7). Never arrives → gate open
+     *   (crash → poller net).
+     * - **Gate 2 — the tracked-task pending set** (task_started / launch acks minus
+     *   completion notifications): covers the ledger's deterministic blind spot —
+     *   a task that COMPLETED while a generation was running has already left the
+     *   ledger, but its `<task-notification>` is still queued and will trigger an
+     *   auto-resume follow-up the instant the engine is free (production-verified:
+     *   injection +5ms after the Stop). A gate-2-only hold is grace-bounded by the
+     *   caller (trackerHoldDeadline) since a stopped/failed notification may never
+     *   produce a follow-up.
+     *
+     * Errors always end the turn (`hadInFlight=false`): a failed engine cannot be
+     * trusted to deliver task notifications, so holding would only hang (the
+     * poller safety net covers any survivors). No sources at all (unit tests
+     * without a bridge/tracker) → end the turn, matching pre-38.2 behavior.
+     */
+    async resolveInFlight(message) {
+        if (message.isError) {
+            return { hadInFlight: false, pendingCount: 0, trackerOnly: false, trackerPending: 0 };
+        }
+        let snapshotInFlight = false;
+        let snapshotCount = 0;
+        let snapshotAnswered = false;
+        if (this.stopSource) {
+            let snap = this.stopSource.consumeMainStopSnapshot();
+            if (!snap) {
+                const deadline = Date.now() + this.stopSnapshotGraceMs;
+                while (!snap && Date.now() < deadline) {
+                    await new Promise((resolve) => setTimeout(resolve, 5));
+                    snap = this.stopSource.consumeMainStopSnapshot();
+                }
+                if (!snap) {
+                    log.warn(`no main Stop snapshot within ${this.stopSnapshotGraceMs}ms of result — ending turn (crash fallback; poller net covers survivors)`);
+                }
+            }
+            snapshotAnswered = snap !== undefined;
+            snapshotInFlight = snap?.hadInFlight ?? false;
+            snapshotCount = snap?.backgroundTasks.length ?? 0;
+        }
+        const trackerPending = this.pendingSource?.pending ?? 0;
+        // Gate 2 applies only when gate 1 AFFIRMATIVELY answered empty: a MISSING
+        // snapshot means the control channel is suspect (engine crash), and holding
+        // on the tracker would wait for notifications a dead engine cannot deliver.
+        // End the turn instead (the pre-fix crash fallback) — the tracker still has
+        // its pendings, so the poller net engages and watches the JSONL.
+        const trackerHolds = snapshotAnswered && !snapshotInFlight && trackerPending > 0;
+        const hadInFlight = snapshotInFlight || trackerHolds;
+        return {
+            hadInFlight,
+            pendingCount: hadInFlight ? Math.max(snapshotCount, trackerPending) : snapshotCount,
+            trackerOnly: trackerHolds,
+            trackerPending,
+        };
+    }
+    /**
+     * Race a generator step against a tracker-hold deadline. Resolves 'expired'
+     * when the deadline passes first; the pending step promise is abandoned to the
+     * caller's teardown (iterator.return queues behind it — the documented
+     * "grace abandon" shape in processStream's finally).
+     */
+    static raceDeadline(step, deadline) {
+        const ms = deadline - Date.now();
+        if (ms <= 0)
+            return Promise.resolve('expired');
+        let timer;
+        const expiry = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('expired'), ms);
+        });
+        return Promise.race([step, expiry]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        });
+    }
     /**
      * Process a single parsed message and invoke appropriate callbacks
      */
     processMessage(message, callbacks) {
         // Fire activity callback for every SDK message (timeout reset)
         callbacks.onActivity?.(message.type);
+        // An active tracker-only hold waits for the queued notification's follow-up
+        // to START. Main-chain generation activity IS that start — cancel the grace;
+        // the follow-up's own result re-evaluates the boundary (normal hold).
+        // Sidechain records (a still-running subagent's activity) must not cancel.
+        if (this.trackerHoldDeadline !== null &&
+            (message.type === SDKMessageType.ASSISTANT || message.type === SDKMessageType.STREAM_EVENT) &&
+            !message.rawMessage.parent_tool_use_id) {
+            this.trackerHoldDeadline = null;
+            log.info('tracker-hold: main-chain generation activity detected — grace cancelled, holding until its result');
+        }
         switch (message.type) {
             case SDKMessageType.INIT:
                 this.handleInit(message, callbacks);
@@ -497,15 +801,25 @@ export class StreamHandler {
             this.state.metadata = this.state.metadata || {};
             callbacks.onSessionInit?.(rawSessionId, this.state.metadata);
         }
+        // Sidechain (subagent) assistant messages arrive on the parent stream as COMPLETED
+        // records (probe-verified: `assistant [text] parent_tool_use_id=…` lands mid-turn;
+        // sidechains never emit stream_event deltas). Their tool_use blocks stay visible as
+        // live activity cards, but their TEXT/THINKING must not masquerade as main-chain
+        // prose: outside the delta-dedup window (a background agent finishing before the new
+        // turn's first main text delta) handleTextBlock would emit subagent text as a main
+        // assistant card and pollute accumulatedText.
+        const isSidechainMsg = Boolean(message.rawMessage.parent_tool_use_id);
         for (const block of message.contentBlocks) {
             if (block.type === ContentBlockType.THINKING) {
                 // Skip if stream_event thinking deltas already handled this (avoids double emission)
-                if (!this.receivedStreamThinkingDelta) {
+                if (!isSidechainMsg && !this.receivedStreamThinkingDelta) {
                     callbacks.onThinking?.(block.thinking);
                 }
             }
             else if (block.type === ContentBlockType.TEXT) {
-                this.handleTextBlock(block, callbacks);
+                if (!isSidechainMsg) {
+                    this.handleTextBlock(block, callbacks);
+                }
             }
             else if (block.type === ContentBlockType.TOOL_USE) {
                 this.handleToolUseBlock(block, callbacks);
@@ -584,6 +898,22 @@ export class StreamHandler {
                     this.estimatedContextTokens += Math.ceil(contentLength / 4);
                 }
             }
+            else if (isMainChain && block.type === ContentBlockType.TEXT) {
+                // The engine injects a background task's completion as a
+                // `<task-notification>` user message (queued while a generation was
+                // running, injected the moment the engine is free). Surface it through
+                // the same callback as the stream's system/task_notification event —
+                // it resolves the tracker's pending entry (turn-boundary gate 2) and
+                // feeds the same UI emit, deduped against the system-event form.
+                // ID-less notifications are NOT emitted (same guard as the poller): the
+                // callback's no-id fallback removes an ARBITRARY tracker entry, which
+                // would punch a hole in gate 2. Requiring the tool-use-id also shrinks
+                // the pasted-notification-lookalike surface to exact live-id collisions.
+                const notif = parseTaskNotification(block.text);
+                if (notif?.toolUseId) {
+                    this.emitTaskNotification({ taskId: notif.taskId, status: notif.status, summary: notif.summary, toolUseId: notif.toolUseId }, callbacks);
+                }
+            }
         }
         // Emit updated context estimate after processing main-chain tool results
         if (isMainChain && this.estimatedContextTokens > 0) {
@@ -623,19 +953,53 @@ export class StreamHandler {
             this.state.metadata = this.state.metadata || {};
             callbacks.onSessionInit?.(rawSessionId, this.state.metadata);
         }
-        // Process thinking deltas
+        // Sidechain (subagent) stream events must not disturb the main chain's
+        // text-block key — their message_start/indexes belong to a different stream.
+        const rawEvent = message.rawMessage;
+        const isMainChain = !rawEvent.parent_tool_use_id;
+        // A new API message begins: content block indexes restart at 0, so advance
+        // the generation to keep text-block keys unique across messages.
+        if (message.eventType === 'message_start' && isMainChain) {
+            this.apiMessageGeneration++;
+        }
+        // Process thinking deltas — same block-stable id contract as text deltas, so an
+        // interleaved card (background subagent activity) can't split a thinking card either.
         if (message.thinkingDelta) {
             this.receivedStreamThinkingDelta = true;
-            callbacks.onThinking?.(message.thinkingDelta);
+            let thinkingMessageId;
+            if (isMainChain) {
+                const blockKey = `${this.apiMessageGeneration}:${rawEvent.event?.index ?? 0}`;
+                if (this.currentThinkingBlockKey !== blockKey || !this.currentThinkingBlockMessageId) {
+                    this.currentThinkingBlockKey = blockKey;
+                    this.currentThinkingBlockMessageId = this.generateMessageId();
+                }
+                thinkingMessageId = this.currentThinkingBlockMessageId;
+            }
+            callbacks.onThinking?.(message.thinkingDelta, undefined, thinkingMessageId);
         }
         // Process text deltas
         if (message.textDelta) {
             this.receivedStreamTextDelta = true;
             this.state.accumulatedText += message.textDelta;
+            // One messageId per text BLOCK (not per delta): the client merges chunks
+            // by id, so deltas re-attach to their segment even when a tool/thinking
+            // card (e.g. background subagent activity) interleaves mid-block.
+            let messageId;
+            if (isMainChain) {
+                const blockKey = `${this.apiMessageGeneration}:${rawEvent.event?.index ?? 0}`;
+                if (this.currentTextBlockKey !== blockKey || !this.currentTextBlockMessageId) {
+                    this.currentTextBlockKey = blockKey;
+                    this.currentTextBlockMessageId = this.generateMessageId();
+                }
+                messageId = this.currentTextBlockMessageId;
+            }
+            else {
+                messageId = this.generateMessageId();
+            }
             // Always emit - websocket.ts uses actualSessionId fallback
             callbacks.onTextChunk?.({
                 sessionId: this.state.sessionId ?? '',
-                messageId: this.generateMessageId(),
+                messageId,
                 content: message.textDelta,
                 done: false,
             });
@@ -722,7 +1086,10 @@ export class StreamHandler {
             callbacks.onCompact?.(message.compactMetadata);
         }
         if (message.subtype === 'task_notification' && message.taskNotification) {
-            callbacks.onTaskNotification?.(message.taskNotification);
+            this.emitTaskNotification(message.taskNotification, callbacks);
+        }
+        if (message.subtype === 'task_started' && message.taskStarted) {
+            callbacks.onTaskStarted?.(message.taskStarted);
         }
     }
     /**
@@ -741,7 +1108,6 @@ export class StreamHandler {
      * Handle result message - stream completion
      */
     handleResult(message, callbacks) {
-        this.state.isComplete = true;
         // Update known context window size from result's modelUsage
         if (message.usage?.contextWindow && message.usage.contextWindow > 0) {
             this.contextWindowSize = message.usage.contextWindow;
@@ -756,15 +1122,35 @@ export class StreamHandler {
                 result: message.result,
             });
         }
-        const response = {
-            id: message.uuid,
-            sessionId: message.sessionId,
-            content: this.state.accumulatedText,
-            done: true,
-            isError: message.isError,
-            usage: message.usage,
-        };
-        callbacks.onComplete?.(response);
+        // Completion (message:complete / deferred notifyComplete / queue advance)
+        // is NOT fired here anymore (Story 38.2): whether this result ENDS the turn
+        // is decided asynchronously in processStream from the engine's Stop hook,
+        // AFTER this synchronous per-message dispatch. processStream fires onComplete
+        // at the turn-ending result; an intermediate result (background_tasks[] still
+        // in flight) fires nothing — the auto-resume follow-up is still coming.
+        // The context-window update + onResultError dispatch above still run for
+        // every result, unchanged.
+    }
+    /**
+     * Fire onTaskNotification exactly once per task. The same completion can
+     * surface twice — as a stream `system/task_notification` event AND as the
+     * injected `<task-notification>` user message — and both must resolve the
+     * tracker (idempotent there), but the UI emit must not double. While a
+     * tracker-only hold is active, a sighting proves the injection chain is
+     * progressing — re-arm the grace for the follow-up generation to start.
+     */
+    emitTaskNotification(data, callbacks) {
+        const key = data.toolUseId || data.taskId;
+        if (key) {
+            if (this.notifiedTaskKeys.has(key))
+                return;
+            this.notifiedTaskKeys.add(key);
+        }
+        if (this.trackerHoldDeadline !== null) {
+            this.trackerHoldDeadline = Date.now() + this.trackerHoldGraceMs;
+            log.info(`tracker-hold: task notification sighted (${key || 'no-id'}) — grace re-armed for the follow-up start`);
+        }
+        callbacks.onTaskNotification?.(data);
     }
     /**
      * Cleanup resources after stream processing