@loicngr/kobo 2.1.10 → 2.1.12

package/AGENTS.md

@@ -197,6 +197,15 @@ Every feature that touches the schema:
 
 ## WebSocket protocol
 
+Claude streaming input is correlated by per-message UUIDs. A result can cover
+several prompts through `user_message_uuids` (messages folded into one turn),
+not one result per sent message. Retire only the matching yielded inputs;
+locally queued or unacknowledged messages still block `turn:completed` and
+input closure. UUID-less legacy results retain a conservative one-input
+fallback for already yielded inputs only; a result never credits a future send.
+Backpressure caps unacknowledged yielded inputs at 64, matching the SDK's result
+UUID list bound. Keep the inactivity watchdog for genuinely unanswered work.
+
 Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `task_type` by task/tool identity across progress and terminal messages, which often omit it. The existing `subagent:progress` envelope also carries this lifecycle metadata for compatibility; `local_bash`, `local_workflow` and `mcp_task` must be excluded from agent cards, busy-agent counts, chat agent-name resolution and the selective stop-subagents action. Keep tracking these jobs for engine liveness and whole-session interruption. Legacy/unknown classifications and Codex agents remain supported; never classify from a description or from the agent's last tool (`Bash` can be a real agent's current action).
 
 ### External MCP dialogue and update checks
@@ -220,8 +229,10 @@ Clients subscribe to individual workspace ids. The server sends `WsEvent` object
 Agent engines emit a normalized `AgentEvent` union, carried by `agent:event`. Common outer types include `user:message`, `task:updated`, `devserver:status`, `workspace:status`, `workspace:archived`, `workspace:unarchived`, and `sync:response`. Legacy `agent:output` rows remain supported through content migration. Keep the backend union in `services/agent/engines/types.ts` and its client mirror in `client/src/types/agent-event.ts` synchronized.
 
 Error events may carry a stable `code`. Claude's post-result drain timeout uses
-`result_drain_timeout` and its stream inactivity timeout uses `stream_idle_timeout`:
-keep both in the chat but exclude them from `AgentErrorBanner`. The selector also
+`result_drain_timeout` and its stream inactivity timeout uses `stream_idle_timeout`.
+Background agents, background tools, and compaction use `subagent_stall_timeout`,
+`background_task_stall_timeout`, and `compaction_stall_timeout`, respectively:
+keep these notices in the chat but exclude them from `AgentErrorBanner`. The selector also
 recognizes their exact legacy messages for persisted history. Other errors keep
 their banners. A `session:ended` with reason `watchdog` leaves a manual workspace
 `idle`, unless accompanied by a nonzero exit code. Preserve the watchdog end reason
@@ -256,7 +267,15 @@ See the "Notion integration" section of the README for the end-user setup guide.
 
 Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:
 
-**Claude Code** (`claude-code/`): consumes the `@anthropic-ai/claude-agent-sdk` async iterator. The SDK manages the Claude runtime; Kōbō does not launch a separate `claude` CLI command. Authentication reuses the user's Claude login or `ANTHROPIC_API_KEY`. The engine arms a **15 s result-drain watchdog** when the SDK emits its `result` message: if the async iterator does not close cleanly within the window, `session:ended` is force-emitted so the orchestrator and auto-loop never hang on a stuck generator. The watchdog is idempotent via a `sessionEndedEmitted` guard and the timer is cleared in `finally`.
+**Claude Code** (`claude-code/`): consumes the `@anthropic-ai/claude-agent-sdk` async iterator. The SDK manages the Claude runtime; Kōbō does not launch a separate `claude` CLI command. Authentication reuses the user's Claude login or `ANTHROPIC_API_KEY`. A settled result gets a **3 s continuation grace**, then a **15 s result-drain watchdog**. Trailing metadata and child output must not cancel the parent's drain/grace. Silence is bounded at **2 minutes** without tools, **30 minutes** for foreground tools and background shell/workflow/MCP jobs, and **10 minutes** for agents. Compaction has an absolute **10-minute** ceiling; repeated status messages cannot extend it. Human questions/permissions pause inactivity; resolution AND SDK cancellation re-evaluate that pause. Watchdogs request abort plus SDK `query.close()`; neither is proof of closure: controller ownership is released only when `EngineProcess.closed` confirms it. Never fake closure or allow a second writer if the SDK ignores termination. End emission is idempotent and timers are cleared on termination and in `finally`.
+
+After the continuation grace, Claude explicitly calls `query.close()`; closing
+the input iterator alone can leave the SDK waiting for an idle notification after
+a successful result. The 15-second drain watchdog is a failed-close backstop,
+not normal cleanup. The SDK still constructs its runtime command; Kōbō's
+`spawnClaudeCodeProcess` hook tracks actual child exit and forwards stderr.
+`EngineProcess.closed` waits for both that exit and iterator completion because
+the SDK's internal cleanup wait is bounded and can return before child exit.
 
 **OpenAI Codex** (`codex/`): uses the **`codex app-server` JSON-RPC protocol** (line-delimited JSON over stdio with a long-lived `codex` subprocess). The engine layers are:
 - `jsonrpc/transport.ts` + `jsonrpc/peer.ts`: generic JSON-RPC 2.0 stdio peer (request correlation, notifications, server-initiated requests)
@@ -438,6 +457,14 @@ One task, two engines, two sibling worktrees. `POST /api/workspaces` accepts a `
 
 ### Workspace templates and duplication
 
+Workspace template presets include optional `tags`. New form captures always
+store the selection (including `[]`); legacy omission preserves the current
+form selection. Server reads/writes filter tags against the current global
+catalogue. Catalogue updates and config imports prune saved template references
+before saving settings, so removed tags cannot reappear when re-added later.
+Only affected presets are rewritten; existing workspace tags are untouched.
+A corrupt template file aborts catalogue cleanup without replacing that file.
+
 `workspace-template-service.ts` persists named presets of the create form in `<KOBO_HOME>/workspace-templates.json` (same JSON pattern as `templates.json`, no SQLite migration). `sanitizePreset` keeps known keys with the right type and drops the rest, so a hand-edited file degrades to unset fields rather than errors. `presetFromWorkspace(id)` derives the same shape from an existing workspace (tasks as titles, statuses dropped); `GET /api/workspaces/:id/preset` exposes it read-only and "Duplicate" opens `/create?from=<id>` with it. On the client, `utils/workspace-preset.ts` (`capturePreset` / `applyPreset`, pure, round-trip tested) is the single bridge between the form and a preset; the create page applies the engine first and waits a tick so its engine watchers normalise model / effort / permission mode before the preset's values land. See [CONFIGURATION.md → Workspace templates and duplication](CONFIGURATION.md#workspace-templates-and-duplication).
 
 ### Onboarding tours

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.12
+
+- fix(claude): close settled SDK sessions without false watchdogs
+
+## 2.1.11
+
+- fix: harden agent lifecycle and workspace workflows
+
 ## 2.1.10
 
 - fix: correct memory budgets and subagent detection

package/CONFIGURATION.md

@@ -623,7 +623,7 @@ original agent automatically; review output already recorded remains available.
 
 A template is a named preset of the create-workspace form: project (optional),
 source branch, branch type, engine, model, reasoning effort, permission mode,
-auto-loop settings, description, tasks and acceptance criteria. The workspace
+auto-loop settings, description, tasks, acceptance criteria and tags. The workspace
 name and working branch are never part of it - they are derived at each
 creation - and neither are Notion / Sentry / PR URLs, which are one-off
 context.
@@ -638,6 +638,14 @@ existing name asks before overwriting. Templates are managed (rename, delete,
 inspect) in **Settings → Workspace templates**; to edit one, load it on the
 create page, adjust, and save it again under the same name.
 
+Templates save the selected tags, including an explicit empty selection. Older
+templates without a tags field leave the current selection unchanged. Removing
+a tag from the global catalogue also removes it from every saved workspace
+template (including catalogue changes through configuration import). Other
+template fields and tags on existing workspaces are preserved. Stale clients
+cannot save removed tags back into templates. If the template file is corrupt,
+the catalogue change is refused and the file is preserved for recovery.
+
 **Duplicate**, in a workspace's context menu, opens the create page prefilled
 from that workspace - its settings, description, tasks and criteria (all reset
 to "to do") - with the name suffixed "(copy)". Nothing is created until you
@@ -647,8 +655,8 @@ brainstorm effort nor "skip setup script", which are creation-time choices.
 Archived workspaces can be duplicated too.
 
 Templates live in `<KOBO_HOME>/workspace-templates.json` (100 at most). A
-corrupt file is read as empty and reported in the server log, and is only
-rewritten by the next save.
+corrupt file produces an error and is preserved; restore a valid file before
+saving templates or changing the tag catalogue.
 
 ## Auto-purge worktree on PR merged
 
@@ -1262,6 +1270,27 @@ Kōbō talks to the embedded [`@anthropic-ai/claude-agent-sdk`](https://github.c
 
 The model selector is populated from [`src/shared/models.ts`](./src/shared/models.ts), also used by backend validation. This checkout includes Fable 5.1, Mythos 5, Opus 5, Opus 4.8, Sonnet 5 and older variants. Pick the default in **Settings → Agents**. Catalogue entries describe what Kōbō offers; provider access still depends on your account. `auto` leaves model selection to the runtime.
 
+#### Session watchdogs
+
+Kōbō distinguishes a finished response from a fully closed SDK session. Once a
+response is settled, it allows 3 seconds for continuation, then explicitly closes
+the SDK query. Normal cleanup is reported as completion, not a watchdog failure.
+A 15-second drain watchdog remains if that close fails to end the iterator.
+Metadata alone cannot extend this cleanup deadline. Writer ownership waits for
+both iterator completion and confirmed runtime exit, even if the SDK's own
+bounded cleanup returns earlier.
+
+Silence limits are 2 minutes without a pending tool, 10 minutes for background
+agents, and 30 minutes for tools (including background Bash, workflow and MCP
+jobs). A compaction has a separate absolute 10-minute limit. Waiting for your
+answer or permission pauses the inactivity watchdog.
+
+Watchdog notices remain in conversation history, but do not display a red error
+banner. Other failures retain their banners. Watchdog shutdown requests both
+cancellation and closure of the SDK transport. Kōbō still requires confirmed
+closure before another agent can write in the same workspace; a runtime that
+refuses to stop is not treated as safely terminated.
+
 ### OpenAI Codex
 
 > Experimental. The Claude Code engine remains the primary, battle-tested path.

package/dist/server/services/agent/engines/claude-code/engine.js

@@ -1,3 +1,5 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { nanoid } from 'nanoid';
 import { isSubagentTask } from '../../../../../shared/subagent-classification.js';
@@ -35,8 +37,7 @@ export const CLAUDE_STREAM_IDLE_TIMEOUT_MS = 120_000;
  * stream is still reaped once this longer ceiling elapses.
  */
 export const CLAUDE_TOOL_IDLE_TIMEOUT_MS = 30 * 60_000;
-/** Ceiling on a context compaction: past this, assume it wedged and let the
- *  liveness deadline take over instead of pausing forever. */
+/** Absolute ceiling on a context compaction, independent of tool idle time. */
 export const COMPACTION_STALL_TIMEOUT_MS = 10 * 60_000;
 // Safety net for a subagent whose terminal `task_notification` carries a
 // status outside the mapper's known-terminal set (SDK schema drift) — it
@@ -73,7 +74,7 @@ class ClaudeInputStream {
     waiting;
     closed = false;
     queuedForcedMessages = 0;
-    yieldedMessages = 0;
+    unansweredMessages = new Set();
     constructor(initialPrompt) {
         this.messages = [{ message: this.toUserMessage(initialPrompt), forced: false }];
     }
@@ -95,16 +96,43 @@ class ClaudeInputStream {
         this.waiting = undefined;
         wake?.();
     }
-    hasUnansweredInput(completedResponses) {
-        return this.queuedForcedMessages > 0 || this.yieldedMessages > completedResponses;
+    hasUnansweredInput() {
+        return this.queuedForcedMessages > 0 || this.unansweredMessages.size > 0;
+    }
+    acknowledgeResult(result) {
+        // One Claude turn can consume several queued prompts. A result counts
+        // turns, not messages: only retire the sends explicitly covered by it.
+        const ids = [...(result.user_message_uuids ?? []), ...(result.user_message_uuid ? [result.user_message_uuid] : [])];
+        if (result.user_message_uuids !== undefined || result.user_message_uuid !== undefined) {
+            for (const id of ids)
+                this.unansweredMessages.delete(id);
+        }
+        else {
+            // A legacy result can acknowledge an already delivered input, never a
+            // future one (e.g. an interrupted turn's result on resume).
+            const oldest = this.unansweredMessages.values().next().value;
+            if (oldest)
+                this.unansweredMessages.delete(oldest);
+        }
+        const wake = this.waiting;
+        this.waiting = undefined;
+        wake?.();
     }
     async *[Symbol.asyncIterator]() {
         while (!this.closed || this.messages.length > 0) {
+            // The SDK echoes at most 64 consumed UUIDs per result. Backpressure
+            // prevents losing correlation without guessing which inputs were read.
+            if (!this.closed && this.unansweredMessages.size >= 64) {
+                await new Promise((resolve) => {
+                    this.waiting = resolve;
+                });
+                continue;
+            }
             const next = this.messages.shift();
             if (next) {
                 if (next.forced)
                     this.queuedForcedMessages--;
-                this.yieldedMessages++;
+                this.unansweredMessages.add(next.message.uuid);
                 yield next.message;
                 continue;
             }
@@ -114,7 +142,7 @@ class ClaudeInputStream {
         }
     }
     toUserMessage(text) {
-        return { type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null };
+        return { type: 'user', uuid: randomUUID(), message: { role: 'user', content: text }, parent_tool_use_id: null };
     }
 }
 export function createClaudeCodeEngine() {
@@ -210,6 +238,9 @@ export function createClaudeCodeEngine() {
                     const onAbort = () => {
                         if (pendingResolvers.get(toolCallId) === resolver) {
                             pendingResolvers.delete(toolCallId);
+                            reevaluateLivenessPause();
+                            if (settlementPending)
+                                armContinuationGrace(RESULT_CONTINUATION_GRACE_MS);
                             const abortError = new Error('Pending user input aborted');
                             abortError.name = 'AbortError';
                             reject(abortError);
@@ -297,6 +328,31 @@ export function createClaudeCodeEngine() {
                 env: options.env,
             });
             sdkOptions.abortController = abortController;
+            // SDK cleanup has its own bounded wait. Iterator completion alone does
+            // not prove that its runtime exited: retain writer ownership until both.
+            let runtimeRunning = false;
+            let runtimeClosed = Promise.resolve();
+            sdkOptions.spawnClaudeCodeProcess = ({ command, args, cwd, env, signal }) => {
+                const child = spawn(command, args, { cwd, env, signal, windowsHide: true, stdio: 'pipe' });
+                runtimeRunning = true;
+                runtimeClosed = new Promise((resolve) => {
+                    const exited = () => {
+                        runtimeRunning = false;
+                        resolve();
+                    };
+                    child.once('exit', exited);
+                    child.once('error', () => {
+                        // A failed spawn has no process; an abort/kill error does not
+                        // establish that an already spawned runtime has actually exited.
+                        if (child.pid === undefined)
+                            exited();
+                    });
+                });
+                child.stderr.setEncoding('utf8');
+                child.stderr.on('data', (data) => sdkOptions.stderr?.(data));
+                child.stderr.on('error', () => { });
+                return child;
+            };
             // Override the SDK's libc-blind binary resolution on Linux glibc — see
             // resolve-binary.ts for the full rationale. No-op on macOS/Windows/musl.
             const explicitBinary = resolveClaudeBinaryPath();
@@ -304,6 +360,27 @@ export function createClaudeCodeEngine() {
                 sdkOptions.pathToClaudeCodeExecutable = explicitBinary;
             const inputStream = new ClaudeInputStream(effectivePrompt);
             const q = query({ prompt: inputStream, options: sdkOptions });
+            let queryCloseRequested = false;
+            const terminateQuery = () => {
+                if (queryCloseRequested)
+                    return;
+                queryCloseRequested = true;
+                inputStream.close();
+                abortController.abort();
+                turnLiveness.stop();
+                clearContinuationGrace();
+                clearResultDrainWatchdog();
+                clearSubagentStallWatchdog();
+                clearCompactionStallTimer();
+                // Abort alone can leave the SDK iterator parked. close() explicitly
+                // tears down its transport/process. Ownership still waits for closed.
+                try {
+                    q.close?.();
+                }
+                catch (error) {
+                    console.warn('[claude-engine] SDK transport close failed:', error);
+                }
+            };
             // Best-effort SDK stop of one background task; failures are ignored.
             const requestStopTask = (taskId) => {
                 try {
@@ -344,6 +421,9 @@ export function createClaudeCodeEngine() {
             const safeEmit = (ev) => streamingBatcher.push(ev);
             let iteratorRunning = false;
             let userInterrupted = false;
+            // Normal post-result disposal is distinct from a watchdog/user abort.
+            // The SDK can wait for an `idle` state even after stdin's iterable ends.
+            let settledCloseRequested = false;
             let completedResponses = 0;
             let waitingForBackground = false;
             let turnCompletedEmittedForResponse = 0;
@@ -356,7 +436,9 @@ export function createClaudeCodeEngine() {
                     completedResponses === turnCompletedEmittedForResponse ||
                     activeSubagentTaskIds.size > 0 ||
                     pendingResolvers.size > 0 ||
-                    inputStream.hasUnansweredInput(completedResponses)) {
+                    isCompacting ||
+                    pendingToolCallIds.size > 0 ||
+                    inputStream.hasUnansweredInput()) {
                     return;
                 }
                 turnCompletedEmittedForResponse = completedResponses;
@@ -366,6 +448,7 @@ export function createClaudeCodeEngine() {
             // catch block) never both emit `session:ended` for the same run.
             let sessionEndedEmitted = false;
             let isCompacting = false;
+            let settlementPending = false;
             const emitSessionEnded = (reason, exitCode) => {
                 if (sessionEndedEmitted)
                     return;
@@ -384,7 +467,7 @@ export function createClaudeCodeEngine() {
             // its task notification and an automatic continuation turn.
             let resultDrainTimer;
             // D2 — one shared liveness module for both engines. Armed before the
-            // first SDK message, re-armed on EVERY message, suspended while a human
+            // first SDK message, re-armed on meaningful progress, suspended while a human
             // decision or a background subagent is outstanding, stopped in `finally`.
             const turnLiveness = createTurnLiveness({
                 timeoutMs: CLAUDE_STREAM_IDLE_TIMEOUT_MS,
@@ -408,7 +491,7 @@ export function createClaudeCodeEngine() {
                         });
                         emitSessionEnded('watchdog', null);
                     }
-                    abortController.abort();
+                    terminateQuery();
                 },
             });
             // The single source of truth for "should the idle deadline be paused
@@ -430,9 +513,8 @@ export function createClaudeCodeEngine() {
             // Backstop for a compaction that never reports completion (stuck
             // `session:compacting` with `active: true` forever): `isCompacting`
             // pauses `turnLiveness` indefinitely, and a wedged-but-alive generator
-            // never trips `isAlive()`'s own sweep either. Past this ceiling, assume
-            // it wedged and resume the liveness deadline so the existing tool-aware
-            // / short deadline can reap it, mirroring `armSubagentStallWatchdog`.
+            // never trips `isAlive()`'s own sweep either. End it at the absolute
+            // ceiling instead of adding another tool-aware idle window afterward.
             let compactionStallTimer;
             const clearCompactionStallTimer = () => {
                 if (!compactionStallTimer)
@@ -441,15 +523,23 @@ export function createClaudeCodeEngine() {
                 compactionStallTimer = undefined;
             };
             const armCompactionStallTimer = () => {
-                clearCompactionStallTimer();
+                if (compactionStallTimer)
+                    return;
                 compactionStallTimer = setTimeout(() => {
                     compactionStallTimer = undefined;
                     if (!isCompacting)
                         return;
-                    console.warn(`[claude-engine] Compaction still reported active ${COMPACTION_STALL_TIMEOUT_MS}ms after it started — resuming the liveness deadline.`);
+                    console.warn(`[claude-engine] Compaction still reported active ${COMPACTION_STALL_TIMEOUT_MS}ms after it started — closing the session.`);
                     isCompacting = false;
                     safeEmit({ kind: 'session:compacting', active: false });
-                    reevaluateLivenessPause();
+                    safeEmit({
+                        kind: 'error',
+                        category: 'other',
+                        code: 'compaction_stall_timeout',
+                        message: 'Session force-ended: context compaction stopped reporting completion (watchdog).',
+                    });
+                    emitSessionEnded('watchdog', null);
+                    terminateQuery();
                 }, COMPACTION_STALL_TIMEOUT_MS);
                 compactionStallTimer.unref?.();
             };
@@ -471,7 +561,7 @@ export function createClaudeCodeEngine() {
                         });
                         emitSessionEnded('watchdog', null);
                     }
-                    abortController.abort();
+                    terminateQuery();
                 }, RESULT_DRAIN_TIMEOUT_MS);
                 resultDrainTimer.unref?.();
             };
@@ -495,16 +585,33 @@ export function createClaudeCodeEngine() {
                 clearContinuationGrace();
                 continuationGraceTimer = setTimeout(() => {
                     continuationGraceTimer = undefined;
-                    if (activeSubagentTaskIds.size > 0 ||
+                    if (completedResponses === 0 ||
+                        !settlementPending ||
+                        activeSubagentTaskIds.size > 0 ||
                         pendingResolvers.size > 0 ||
                         pendingToolCallIds.size > 0 ||
-                        inputStream.hasUnansweredInput(completedResponses))
+                        isCompacting ||
+                        inputStream.hasUnansweredInput())
                         return;
                     // Settled only now: a result the CLI follows up on (e.g. a resumed
                     // turn's empty result) must not hide the busy banner meanwhile.
                     emitTurnCompletedIfSettled();
                     inputStream.close();
                     armResultDrainWatchdog();
+                    // Closing the input iterable alone leaves the SDK in waitForRunEnd
+                    // when its last session state is still running. Dispose explicitly,
+                    // but let the iterator confirm actual closure before session:ended.
+                    // The drain watchdog now guards a FAILED close, not normal cleanup.
+                    if (!settledCloseRequested && typeof q.close === 'function') {
+                        settledCloseRequested = true;
+                        try {
+                            q.close();
+                        }
+                        catch (error) {
+                            settledCloseRequested = false;
+                            console.warn('[claude-engine] Post-result SDK close failed:', error);
+                        }
+                    }
                 }, delayMs);
                 continuationGraceTimer.unref?.();
             };
@@ -525,19 +632,26 @@ export function createClaudeCodeEngine() {
                 clearSubagentStallWatchdog();
                 if (pendingResolvers.size > 0 || activeSubagentTaskIds.size === 0)
                     return;
+                const hasAgent = [...activeSubagentTaskIds].some((id) => isSubagentTask({ taskType: mapperState.taskTypes.get(id) }));
+                // Shell/workflow/MCP jobs do not emit agent progress during a long
+                // command. Give them the same silence allowance as foreground tools.
+                const timeoutMs = hasAgent ? SUBAGENT_STALL_TIMEOUT_MS : CLAUDE_TOOL_IDLE_TIMEOUT_MS;
                 subagentStallTimer = setTimeout(() => {
                     subagentStallTimer = undefined;
                     if (pendingResolvers.size > 0 || activeSubagentTaskIds.size === 0)
                         return;
-                    console.warn(`[claude-engine] No subagent activity for ${SUBAGENT_STALL_TIMEOUT_MS}ms — forcing session:ended`);
+                    console.warn(`[claude-engine] No background activity for ${timeoutMs}ms — forcing session:ended`);
                     safeEmit({
                         kind: 'error',
                         category: 'other',
-                        message: 'Session force-ended: background subagents stopped reporting activity (watchdog).',
+                        message: hasAgent
+                            ? 'Session force-ended: background subagents stopped reporting activity (watchdog).'
+                            : 'Session force-ended: background tools stopped reporting activity (watchdog).',
+                        code: hasAgent ? 'subagent_stall_timeout' : 'background_task_stall_timeout',
                     });
                     emitSessionEnded('watchdog', null);
-                    abortController.abort();
-                }, SUBAGENT_STALL_TIMEOUT_MS);
+                    terminateQuery();
+                }, timeoutMs);
                 subagentStallTimer.unref?.();
             };
             const iteratorPromise = (async () => {
@@ -545,22 +659,27 @@ export function createClaudeCodeEngine() {
                 turnLiveness.start();
                 try {
                     for await (const msg of q) {
+                        const events = mapSdkMessage(msg, mapperState);
+                        const isForeground = !('parent_tool_use_id' in msg && msg.parent_tool_use_id != null);
+                        const foregroundProgress = isForeground &&
+                            events.some((ev) => ev.kind === 'message:text' ||
+                                ev.kind === 'message:thinking' ||
+                                ev.kind === 'tool:call' ||
+                                ev.kind === 'tool:result');
                         // A parent continuation owns the foreground again. Background
                         // progress notifications alone do not end the between-turn wait.
-                        if (msg.type === 'assistant' || msg.type === 'user' || msg.type === 'stream_event') {
+                        if (foregroundProgress) {
                             waitingForBackground = false;
+                            settlementPending = false;
                             clearContinuationGrace();
+                            clearResultDrainWatchdog();
                         }
                         else if (msg.type === 'system' && msg.subtype === 'init') {
                             // A new run starts on this stream (e.g. after a resumed turn's empty result).
                             clearContinuationGrace();
+                            settlementPending = false;
+                            clearResultDrainWatchdog();
                         }
-                        // This SDK message proves that any drain condition armed by a
-                        // *previous* message is no longer current. A drain armed while
-                        // processing this message remains active if the generator then
-                        // goes silent.
-                        clearResultDrainWatchdog();
-                        const events = mapSdkMessage(msg, mapperState);
                         for (const ev of events) {
                             if (ev.kind === 'subagent:progress')
                                 trackSubagentProgress(ev);
@@ -578,17 +697,26 @@ export function createClaudeCodeEngine() {
                             armSubagentStallWatchdog();
                         for (const ev of events) {
                             if (ev.kind === 'session:compacting') {
+                                const wasCompacting = isCompacting;
                                 isCompacting = ev.active;
-                                if (ev.active)
+                                if (ev.active) {
+                                    clearContinuationGrace();
+                                    clearResultDrainWatchdog();
                                     armCompactionStallTimer();
-                                else
+                                }
+                                else {
                                     clearCompactionStallTimer();
+                                    if (wasCompacting && settlementPending)
+                                        armContinuationGrace(RESULT_CONTINUATION_GRACE_MS);
+                                }
                             }
                             // Older SDKs can emit only compact_boundary, without a trailing
                             // status update. This boundary marks compaction as complete.
                             else if (ev.kind === 'session:compacted') {
                                 isCompacting = false;
                                 clearCompactionStallTimer();
+                                if (settlementPending)
+                                    armContinuationGrace(RESULT_CONTINUATION_GRACE_MS);
                             }
                         }
                         // Actual foreground output proves work resumed even if the SDK
@@ -602,18 +730,16 @@ export function createClaudeCodeEngine() {
                             safeEmit({ kind: 'session:compacting', active: false });
                         }
                         for (const ev of events) {
-                            if (ev.kind === 'tool:call')
+                            if (isForeground && ev.kind === 'tool:call')
                                 pendingToolCallIds.add(ev.toolCallId);
-                            else if (ev.kind === 'tool:result')
+                            else if (isForeground && ev.kind === 'tool:result')
                                 pendingToolCallIds.delete(ev.toolCallId);
                         }
                         // After a settled result, the last background completion drains
                         // the stream only if the parent does not continue (see
                         // BACKGROUND_CONTINUATION_GRACE_MS): its continuation still needs
                         // the input for permission requests.
-                        if (subagentStallTimer &&
-                            activeSubagentTaskIds.size === 0 &&
-                            !inputStream.hasUnansweredInput(completedResponses)) {
+                        if (subagentStallTimer && activeSubagentTaskIds.size === 0 && !inputStream.hasUnansweredInput()) {
                             clearSubagentStallWatchdog();
                             armContinuationGrace(BACKGROUND_CONTINUATION_GRACE_MS);
                         }
@@ -622,9 +748,12 @@ export function createClaudeCodeEngine() {
                                 discoveredSessionId = ev.engineSessionId;
                             safeEmit(ev);
                         }
-                        // Any SDK message is proof of life — re-arm on EVERY message, not
-                        // only on a text-without-tool-call one.
-                        turnLiveness.activity();
+                        // Transport metadata is not forward progress. In particular a
+                        // stream of trailing notifications must not defeat shutdown.
+                        if (foregroundProgress ||
+                            msg.type === 'result' ||
+                            events.some((ev) => ev.kind === 'subagent:progress' && !ev.ambient))
+                            turnLiveness.activity();
                         // A background subagent or a pending permission card can stay
                         // legitimately quiet for minutes; their own dedicated watchdogs
                         // own those windows, so suspend the turn deadline meanwhile.
@@ -634,11 +763,14 @@ export function createClaudeCodeEngine() {
                         reevaluateLivenessPause();
                         if (msg.type === 'result') {
                             waitingForBackground = false;
+                            settlementPending = true;
                             clearContinuationGrace();
                             pendingToolCallIds.clear();
+                            turnLiveness.setTimeoutMs(CLAUDE_STREAM_IDLE_TIMEOUT_MS);
                             completedResponses++;
+                            inputStream.acknowledgeResult(msg);
                             // A queued forced message starts the next response on this same SDK stream.
-                            if (!inputStream.hasUnansweredInput(completedResponses)) {
+                            if (!inputStream.hasUnansweredInput()) {
                                 if (activeSubagentTaskIds.size === 0) {
                                     clearSubagentStallWatchdog();
                                     armContinuationGrace(RESULT_CONTINUATION_GRACE_MS);
@@ -670,7 +802,12 @@ export function createClaudeCodeEngine() {
                         abortController.signal.aborted ||
                         /aborted by user|process aborted|abortError|ede_diagnostic/i.test(error.message ?? '');
                     if (isAbort) {
-                        emitSessionEnded('killed', null);
+                        if (settledCloseRequested && !userInterrupted && !abortController.signal.aborted) {
+                            const reason = mapperState.sawErrorResult ? 'error' : 'completed';
+                            emitSessionEnded(reason, reason === 'completed' ? 0 : null);
+                        }
+                        else
+                            emitSessionEnded('killed', null);
                     }
                     else {
                         safeEmit({
@@ -710,7 +847,7 @@ export function createClaudeCodeEngine() {
             })();
             const engineProcess = {
                 ready,
-                closed: iteratorPromise.then(() => { }),
+                closed: iteratorPromise.then(() => runtimeClosed),
                 get pid() {
                     return undefined;
                 },
@@ -718,10 +855,10 @@ export function createClaudeCodeEngine() {
                     return discoveredSessionId;
                 },
                 isAlive() {
-                    return iteratorRunning;
+                    return iteratorRunning || runtimeRunning;
                 },
                 sendMessage(text) {
-                    if (!iteratorRunning)
+                    if (!iteratorRunning || queryCloseRequested || settledCloseRequested || sessionEndedEmitted)
                         throw new Error(`Claude ${AGENT_NO_LONGER_RUNNING_TEXT}`);
                     inputStream.send(text);
                     armSubagentStallWatchdog();
@@ -735,7 +872,7 @@ export function createClaudeCodeEngine() {
                         pendingToolCallIds.size > 0 ||
                         pendingResolvers.size > 0 ||
                         isCompacting ||
-                        inputStream.hasUnansweredInput(completedResponses))
+                        inputStream.hasUnansweredInput())
                         return false;
                     inputStream.send(text);
                     waitingForBackground = false;
@@ -800,7 +937,7 @@ export function createClaudeCodeEngine() {
                     }
                 },
                 async stop() {
-                    abortController.abort();
+                    terminateQuery();
                     try {
                         await iteratorPromise;
                     }