@cspeach/cli 0.6.0

package/dist/agent/loop.js

@@ -0,0 +1,709 @@
+import chalk from 'chalk';
+import { basename } from 'node:path';
+import { dispatchTool } from './tool-dispatch.js';
+import { listTools, toAnthropicTools } from '../tools/index.js';
+import { saveSession } from '../session/store.js';
+import { loadConfig } from '../config/loader.js';
+import { retryWithBackoff } from './retry.js';
+import { renderChunk, initialBufferState, render } from '../renderer/pipeline.js';
+import { renderToolCallTop, renderToolCallBottom, startToolSpinner, startThinkingSpinner } from '../renderer/tool-widget.js';
+import { startThinkingHeartbeat } from '../renderer/thinking-heartbeat.js';
+// (progress-chatter import removed 2026-05-01 — superseded by CC-style
+//  two-line dispatch renderer; re-add if a future in-place spinner returns)
+import { ERR } from '../errors/codes.js';
+import { lastAssistantIsAwaitingAnswer } from '../session/awaiting-answer.js';
+import { enrichUserMessage } from '../router/intent-extractor.js';
+import { resetRule8State } from '../repl/rule8-detector.js';
+import { runSaveCommand, runPromoteCommand } from '../projects/index.js';
+import { parseFromFlag } from '../skills/promotion-dispatch.js';
+import { input } from '@inquirer/prompts';
+import { withInquirer } from '../repl/inquirer-guard.js';
+import { expandTextFileAttachments } from '../projects/workspace.js';
+import { getSapSystemInfo, renderSapSystemBlock } from '../sap/system-info.js';
+import { objectKeyFromInput } from './retry-key.js';
+import { repairPartialBlocks } from './repair-partial.js';
+import { TurnStreamWriter } from './turn-stream.js';
+import { applyToolResultCheckpoint } from './skill-checkpoint.js';
+import { loadWatchdogConfig, evaluateWatchdog } from './turn-watchdog.js';
+import { maybeBuildProjectContext } from './maybe-build-project-context.js';
+import { buildSapConnectionContext } from './sap-connection-adapter.js';
+import { getCurrentTransport } from '../repl/current-transport.js';
+import { collectTurnAssistantText } from './turn-assistant-text.js';
+/**
+ * Author identity for project-file metadata. Reads CSPEACH_AUTHOR_NAME first,
+ * then platform USER/USERNAME, then a generic fallback. Role is fixed to
+ * 'consultant' until we add multi-role support.
+ *
+ * Exported for unit testing.
+ */
+export function getAuthorIdentity() {
+    const name = process.env.CSPEACH_AUTHOR_NAME ??
+        process.env.USER ??
+        process.env.USERNAME ??
+        'consultant';
+    return { name, role: 'consultant' };
+}
+// v0.5: design + estimate join the save-hook eligibility list. The save flow
+// itself is artefact-agnostic — runSaveCommand dispatches by skill name via
+// SKILL_REGISTRY and emits the right envelope shape.
+const SAVE_HOOK_SKILLS = new Set([
+    'abap-spec-gap',
+    'abap-design',
+    'abap-estimate',
+    // 2026-05-08: upgrade pipeline manifest envelopes. Each emits a
+    // <!-- csforge:upgrade-manifest --> block that the matching
+    // extract-upgrade.* parser turns into the manifest envelope. The
+    // heavy detail (per-finding data) stays in `.abapforge/upgrades/`,
+    // referenced by detail_path inside the envelope.
+    'abap-upgrade-scan',
+    'abap-upgrade-fix',
+    'abap-upgrade-verify',
+    'abap-upgrade-merge',
+    // 2026-05-09: CCA pipeline manifest envelopes. /abap-cca emits a
+    // <!-- csforge:cca-manifest --> block wrapping the heavy project.json
+    // detail at .abapforge/cca/projects/<slug>/. /abap-cca-merge produces
+    // a consolidated cca-assessment from N parallel consultant slices.
+    'abap-cca',
+    'abap-cca-merge',
+    // 2026-05-10: v0.7 trio chain. /abap-modernize emits modernize-result;
+    // /abap-test emits test-coverage. Both accept cca-assessment via --from
+    // and can fan out into further chains after their own envelope saves.
+    'abap-modernize',
+    'abap-test',
+]);
+/**
+ * True when any user message in the session already carries the rendered
+ * <project_context> block. Phase 2 uses this to inject the block exactly
+ * once per session, to the first user turn that doesn't have it.
+ *
+ * Why a content scan rather than a turn counter:
+ *
+ *  - On `cspeach --resume`, session.messages is rehydrated from disk
+ *    with the prior process's injected block already present. A
+ *    per-process counter would re-inject; the content scan correctly
+ *    short-circuits.
+ *
+ *  - tool_result entries push `role: 'user'` with array-shaped content.
+ *    The `typeof === 'string'` check skips those without iterating
+ *    multimodal blocks.
+ *
+ * Exported for unit testing only — the call site is one floor up in runTurn.
+ */
+export function hasProjectContextBlock(messages) {
+    for (const m of messages) {
+        if (m.role !== 'user')
+            continue;
+        if (typeof m.content === 'string' && m.content.includes('<project_context')) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function maybeOfferSave(p) {
+    if (!SAVE_HOOK_SKILLS.has(p.skill))
+        return;
+    if (p.assistantText.trim().length === 0)
+        return;
+    try {
+        await runSaveCommand({
+            skillOutput: p.assistantText,
+            skillName: p.skill,
+            skillVersion: '1.0',
+            skillInput: p.userMessage,
+            tokensUsed: p.tokensUsed,
+            model: p.model,
+            author: getAuthorIdentity(),
+            cwd: process.cwd(),
+            prompt: async (q) => withInquirer(() => input({ message: q })),
+            log: (...lines) => lines.forEach((l) => p.emit(l)),
+            promotedFrom: p.promotedFrom ?? null,
+        });
+    }
+    catch (err) {
+        p.emit(chalk.yellow(`\n[save] skipped: ${err?.message ?? err}`));
+    }
+}
+export async function runTurn(params) {
+    resetRule8State(); // Rule 8 — fresh batch counter per LLM turn (= per user prompt)
+    const cfg = await loadConfig();
+    const session = params.ctx.session;
+    // Define `emit` early so the Phase J promote dispatch (below) can stream
+    // its prompt + status lines through the same Ink-aware sink the rest of
+    // runTurn uses. Originally defined later in the function — hoisted in v0.5
+    // so --from interactivity sits above the LLM stream setup.
+    function emit(line) {
+        if (params.chunkEmitter)
+            params.chunkEmitter.emit('chunk', line + '\n');
+        else
+            console.log(line);
+    }
+    // Phase J — `--from @<source>` phase promotion.
+    // If the user typed `/abap-design --from @./spec-gap.cspeach.json` (or the
+    // estimate equivalent), strip the flag, validate + snapshot the source,
+    // prepend a "Promoted from..." block to the LLM input, and stash the
+    // snapshot for the post-turn save hook so the saved envelope's
+    // promotedFrom field is populated.
+    let promotedFromForSave = null;
+    let userMessageForLLM = params.userMessage;
+    let userMessageForSave = params.userMessage;
+    {
+        const { fromPath, rest } = parseFromFlag(params.userMessage);
+        if (fromPath) {
+            const result = await runPromoteCommand({
+                sourcePath: fromPath,
+                targetSkill: params.skill,
+                prompt: async (q) => withInquirer(() => input({ message: q })),
+                log: (...lines) => lines.forEach((l) => emit(l)),
+            });
+            if (!result) {
+                // User declined, source invalid, or unsupported target — skip the turn.
+                emit(chalk.yellow('\n[--from] aborted; turn cancelled.'));
+                return;
+            }
+            promotedFromForSave = result.promotedFrom;
+            // 2026-05-08: thread the original @<filename> token into the LLM
+            // prompt so skills that need to dispatch a follow-up command (e.g.
+            // dispatch_skill calling /abap-rap --from @<same-file>) can use the
+            // exact filename. Previously the filename was consumed by
+            // parseFromFlag and never reached the model — skills had to guess
+            // and frequently dropped the unique-id segment ("foo-d515-v1" →
+            // "foo-v1"), producing "no file matching" auto-routes. Use basename
+            // so absolute / relative paths normalise to the workspace @<token>
+            // form the picker resolves.
+            const sourceToken = `@${basename(fromPath)}`;
+            userMessageForLLM = `Source file: ${sourceToken}\n${result.extendedSkillInput}\n\n---\n\n${rest}`;
+            userMessageForSave = rest;
+        }
+    }
+    // Phase D — `@<text-file>` attachment expansion.
+    // After --from has consumed its own @<token>, scan what's left for
+    // `@<filename>` references that resolve to .txt / .md files in the
+    // workspace. Substitute each with an <attached file="..."> block
+    // containing the file content so the skill sees the user's
+    // requirement document as part of the prompt. .cspeach.json
+    // envelopes are NOT expanded here (they go through --from / --status).
+    // The save copy keeps the original `@<filename>` token rather than
+    // the expanded body so the saved envelope's source.input stays
+    // human-readable; only the LLM sees the inflated prose.
+    userMessageForLLM = await expandTextFileAttachments(userMessageForLLM, params.ctx.cwd, (line) => emit(chalk.dim(line)));
+    // 2026-05-06: alongside the deterministic prompt-fact extraction
+    // (package / transport / etc.), inject the connected SAP system's
+    // release + platform + ABAP version. One CVERS query the first time
+    // we see an alias; cached in-memory + on disk thereafter (~30-day
+    // TTL). Skills like /abap-spec-gap stop asking "are we on S/4HANA?"
+    // when the answer is already in the prompt.
+    // Failure mode: getSapSystemInfo returns null on any error. The
+    // SAP block is then empty and the rest of enrichment proceeds as
+    // before — no behavioral regression.
+    let sapSystemBlock = '';
+    let sapSystemInfo = null;
+    if (params.ctx.adt && params.ctx.sapAlias) {
+        sapSystemInfo = await getSapSystemInfo(params.ctx.adt, params.ctx.sapAlias);
+        sapSystemBlock = renderSapSystemBlock(sapSystemInfo);
+    }
+    // Deterministically extract structured facts from the user's prompt
+    // (package, transport, object names, environment hint, create intent)
+    // and prepend them as an XML `<session_context>` block. The model reads
+    // these as structured data — eliminates the "skill kept asking about X
+    // when user said X" failure class without relying on prose rules.
+    // See src/router/intent-extractor.ts for the rationale.
+    //
+    // Enrich on every turn, not just the first: a classifier / reroute flow
+    // may have pushed a user message into session.messages before we get
+    // here, which would defeat a "first turn only" check. Skip only when the
+    // message already begins with <session_context> (caller enriched it) or
+    // when extraction yields nothing (enrichUserMessage returns original).
+    const enriched = userMessageForLLM.startsWith('<session_context>')
+        ? userMessageForLLM
+        : enrichUserMessage(userMessageForLLM, sapSystemBlock);
+    // Phase 2 of Track B — opt-in project-context enrichment, gated by
+    // CSPEACH_PROJECT_CONTEXT=on. Default OFF: production behavior is
+    // identical to today. When on, the rendered <project_context> block
+    // (file index, conventions, domain objects, git state) is prepended
+    // ONCE per session — to the first user message that doesn't already
+    // carry one. The hasProjectContextBlock guard scans session.messages
+    // for the literal block; this is what makes `cspeach --resume` correct
+    // (the rehydrated messages already contain the block from the prior
+    // process; the helper short-circuits cleanly). Helper handles the
+    // env-var gate, walk, and per-process cache.
+    let projectContextBlock = '';
+    if (!hasProjectContextBlock(session.messages)) {
+        // Phase 2.1 — when an alias is active, assemble the
+        // SapConnectionContext so the rendered project_context includes a
+        // populated <sap_connection> sub-block. The adapter is best-effort:
+        // missing values become null. recentObjects stays empty until the
+        // tool dispatch layer captures last-N targets (Phase 2.2+).
+        const sapConnection = params.ctx.sapAlias
+            ? buildSapConnectionContext(params.ctx.sapAlias, sapSystemInfo, {
+                currentTransport: getCurrentTransport() ?? null,
+            })
+            : null;
+        projectContextBlock = await maybeBuildProjectContext({
+            cwd: params.ctx.cwd,
+            sapConnection,
+        });
+    }
+    const finalUserContent = projectContextBlock
+        ? `${projectContextBlock}\n\n${enriched}`
+        : enriched;
+    session.messages.push({ role: 'user', content: finalUserContent });
+    session.skill = params.skill;
+    /**
+     * key: `${tool_name}:${object}` — consecutive failures per (tool, target).
+     * For object-identifying tools (sap_set_source / sap_activate / etc.) the
+     * target is `${name}:${type}`. For tools without an object identity in
+     * their args (sap_sql_query / sap_search_object), the target falls back
+     * to a stable hash of the args — so different probes/queries are NOT
+     * counted as retries of each other. See ./retry-key.ts for the rationale.
+     */
+    const failMap = new Map();
+    const RETRY_CAP = 3;
+    // Snapshot output tokens at turn start so the post-turn save hook can
+    // report the per-turn delta (not the lifetime cumulative). usage may be
+    // missing on older session schemas; the loop initializes it before the
+    // first stream event, so 0 is a safe pre-init baseline.
+    const turnStartOutputTokens = session.usage?.output_tokens ?? 0;
+    // Snapshot session.messages.length at turn start so the save hook can
+    // walk every assistant message added during this turn — not just the
+    // final one. Skills like /abap-cca emit their manifest in an early
+    // message before a closing ask_question widget; the final wrap-up
+    // message ends the turn but doesn't carry the manifest. See
+    // ./turn-assistant-text.ts for the full rationale.
+    const turnStartMessageCount = session.messages.length;
+    // v0.6 — mirror assistant text to ~/.cspeach/streams/<sessionId>/<ts>.md
+    // so a renderer crash or terminal close never loses the on-screen prose.
+    // The graceful-error UX (T19) prints this path on any failed turn.
+    const turnStreamWriter = new TurnStreamWriter(session.id);
+    // v0.6 Layer 3 — long-turn watchdog. Tracked across the while-loop's
+    // tool-call rounds. The advisory fires AT MOST ONCE per turn between
+    // rounds so it doesn't spam the model. See agent/turn-watchdog.ts.
+    const watchdogConfig = loadWatchdogConfig();
+    const turnStartedAt = Date.now();
+    let watchdogWarned = false;
+    // (emit was hoisted to the top of the function in v0.5 so the Phase J
+    //  promote dispatch could share it. Original location was here.)
+    while (true) {
+        let buffer = initialBufferState();
+        let stream;
+        // 2026-05-06: paint a "thinking" spinner during the LLM round-trip
+        // wait so the user sees activity instead of staring at a silent
+        // prompt. The function disables itself when a chunkEmitter is
+        // provided (it would otherwise race with the chunkEmitter renderer's
+        // own paint loop), so call it without one — the spinner writes
+        // directly to stdout. Stopped on the first content_block_start (so
+        // the response stream paints in its place) and on any error path
+        // below.
+        const thinkingSpinner = startThinkingSpinner({});
+        // v0.6 — guaranteed-visible heartbeat alongside the in-place spinner.
+        // The spinner self-disables on non-TTY (Windows PowerShell sometimes
+        // reports isTTY=false; resume mode also lost spinner visibility) so a
+        // 45-second wait looked like a hang. The heartbeat prints fresh lines
+        // at 3s/10s/30s/60s/90s/2m/3m/5m thresholds — works on any terminal.
+        const thinkingHeartbeat = startThinkingHeartbeat();
+        try {
+            stream = await retryWithBackoff(() => (async () => {
+                const tools = toAnthropicTools(listTools());
+                const streamParams = {
+                    model: cfg.default_model,
+                    // v0.3.1 — was 8192. Bumped because code-gen skills (abap-generate
+                    // etc.) kept running out of budget mid-turn: adaptive thinking +
+                    // multiple tool-result prompts + TL;DR mandate + summary prose
+                    // + the final question widget didn't fit in 8K. Symptom: stream
+                    // ended with stop_reason='length' right before the widget, and
+                    // the user saw the skill "stuck" after the intro prose.
+                    // 32768 is Opus 4.7's recommended ceiling for agentic turns and
+                    // gives comfortable headroom for the investigate-first pattern.
+                    max_tokens: params.maxTokensOverride ?? 32768,
+                    messages: session.messages,
+                    tools,
+                    thinking: { type: 'adaptive', display: 'summarized' },
+                };
+                // Skill travels as a header per coordination doc §1.
+                // Do NOT add `skill` to streamParams — it is not part of the Anthropic SDK body schema.
+                // v0.6 — forward the per-turn abort signal so Esc / SIGINT-during-turn
+                // tears down the in-flight stream cleanly.
+                return params.provider.createStream(streamParams, {
+                    headers: { 'X-CSForge-Skill': params.skill },
+                    signal: params.signal,
+                });
+            })());
+        }
+        catch (err) {
+            // Stop the thinking spinner before printing any error — leaving
+            // it spinning while an error message is emitted looks broken.
+            thinkingSpinner.stop();
+            thinkingHeartbeat.stop();
+            // Proxy returns 409 upgrade_required when CLI is older than skill's min_cli_version.
+            const status = err?.status ?? err?.response?.status;
+            const bodyRaw = err?.error ?? err?.response?.data ?? err?.body;
+            const body = typeof bodyRaw === 'string' ? JSON.parse(bodyRaw) : bodyRaw;
+            if (status === 409 && body?.error === 'upgrade_required') {
+                emit(chalk.yellow.bold(`\n⚠  This skill requires cspeach >= ${body.min_cli_version} (you have ${body.current ?? 'unknown'}).`));
+                emit(chalk.yellow(`   Run: cspeach --upgrade`));
+                return;
+            }
+            throw err;
+        }
+        let currentAssistantContent = [];
+        let sawEndTurn = false;
+        let sawToolUse = false;
+        // M10 — ensure session.usage is present (shipped session schema may omit it
+        // for older saved sessions; we default to zero on first turn).
+        if (!session.usage) {
+            session.usage = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 };
+        }
+        // H2 — Anthropic's `message_delta.usage.output_tokens` is CUMULATIVE for the
+        // current message (it grows monotonically as the model streams). Naively
+        // doing `session.usage.output_tokens += deltaUsage.output_tokens` on every
+        // delta event multi-counts the same tokens N times. The correct pattern is
+        // to track the last-seen value per-message and add only the increment. This
+        // scratch is reset on every `message_start`.
+        //
+        // Reference: https://docs.anthropic.com/en/api/messages-streaming (see
+        // `message_delta` section — `usage.output_tokens` is "the cumulative number
+        // of output tokens generated so far for this message").
+        let messageOutputTokensSoFar = 0; // cumulative for the CURRENT message
+        // v0.6 resilience — capture any error thrown by the provider stream so we
+        // can persist whatever the model already emitted before the crash. The old
+        // behaviour was to let the exception propagate straight out of the for-await,
+        // skipping the assistant-message persistence below entirely. That's how a
+        // 77-minute /abap-cca turn with 200K tokens of output ended up entirely
+        // discarded when Undici reported the HTTP stream as "terminated".
+        let interruptedError = null;
+        try {
+            for await (const event of stream) {
+                const type = event.type;
+                if (type === 'content_block_start') {
+                    // First content event of this stream — stop the thinking spinner
+                    // so the response paints in its place. Idempotent: subsequent
+                    // content_block_start events (for follow-on text/tool blocks)
+                    // call stop on an already-stopped handle, which is a no-op.
+                    thinkingSpinner.stop();
+                    thinkingHeartbeat.stop();
+                    const block = event.content_block;
+                    currentAssistantContent.push(block);
+                    if (block.type === 'text') {
+                        const sep = chalk.gray('\n');
+                        if (params.chunkEmitter)
+                            params.chunkEmitter.emit('chunk', sep);
+                        else
+                            process.stdout.write(sep);
+                    }
+                }
+                else if (type === 'content_block_delta') {
+                    const delta = event.delta;
+                    const last = currentAssistantContent[currentAssistantContent.length - 1];
+                    if (delta.type === 'text_delta') {
+                        const { output, state } = renderChunk(delta.text, buffer);
+                        buffer = state;
+                        if (output) {
+                            if (params.chunkEmitter)
+                                params.chunkEmitter.emit('chunk', output);
+                            else
+                                process.stdout.write(output);
+                        }
+                        if (last?.type === 'text')
+                            last.text = (last.text ?? '') + delta.text;
+                        // v0.6 — also write the raw model text to disk so the user can
+                        // recover the prose if the terminal renderer crashes or the turn
+                        // aborts mid-stream. Best-effort fire-and-forget.
+                        void turnStreamWriter.append(delta.text);
+                    }
+                    else if (delta.type === 'input_json_delta') {
+                        if (last)
+                            last.partial_json = (last.partial_json ?? '') + delta.partial_json;
+                    }
+                    else if (delta.type === 'thinking_delta') {
+                        // Adaptive thinking streams content here. Must be preserved on the
+                        // assistant message so the next turn doesn't reject the block with
+                        // "each thinking block must contain thinking".
+                        if (last?.type === 'thinking')
+                            last.thinking = (last.thinking ?? '') + delta.thinking;
+                    }
+                    else if (delta.type === 'signature_delta') {
+                        // Thinking blocks may carry a signature used for server-side verification.
+                        if (last?.type === 'thinking')
+                            last.signature = (last.signature ?? '') + delta.signature;
+                    }
+                }
+                else if (type === 'content_block_stop') {
+                    const last = currentAssistantContent[currentAssistantContent.length - 1];
+                    if (last?.type === 'tool_use' && last.partial_json) {
+                        try {
+                            last.input = JSON.parse(last.partial_json);
+                        }
+                        catch {
+                            last.input = {};
+                        }
+                        delete last.partial_json;
+                    }
+                }
+                else if (type === 'message_start') {
+                    // message_start carries the prompt usage (input tokens + any cache reads).
+                    const msgUsage = event.message?.usage;
+                    if (msgUsage) {
+                        session.usage.input_tokens += msgUsage.input_tokens ?? 0;
+                        session.usage.cache_read_input_tokens += msgUsage.cache_read_input_tokens ?? 0;
+                    }
+                    // New message begins — reset the per-message cumulative-output scratch.
+                    messageOutputTokensSoFar = 0;
+                }
+                else if (type === 'message_delta') {
+                    const stop_reason = event.delta?.stop_reason;
+                    if (stop_reason === 'end_turn')
+                        sawEndTurn = true;
+                    if (stop_reason === 'tool_use')
+                        sawToolUse = true;
+                    // H2 — `deltaUsage.output_tokens` is the cumulative running total for
+                    // THIS message, NOT a per-event delta. Compute the increment vs the
+                    // last-seen cumulative and add only that. Guard against `null` /
+                    // missing-field and against monotonic-decrease edge cases.
+                    const deltaUsage = event.usage;
+                    if (deltaUsage?.output_tokens != null) {
+                        const inc = deltaUsage.output_tokens - messageOutputTokensSoFar;
+                        if (inc > 0) {
+                            session.usage.output_tokens += inc;
+                            messageOutputTokensSoFar = deltaUsage.output_tokens;
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // Provider stream broke mid-flight (Undici "terminated" / network drop /
+            // AbortController / Anthropic stream timeout). DO NOT lose the partial
+            // assistant content — capture the error and fall through to the persist
+            // block below so whatever the model already streamed lands on disk.
+            interruptedError = err;
+            thinkingSpinner.stop();
+            thinkingHeartbeat.stop();
+        }
+        // Final flush: emit any pending partial line after the stream ends.
+        // Runs on both clean completion and mid-stream interruption.
+        if (buffer.pending.length > 0) {
+            const flushed = render(buffer.pending);
+            if (params.chunkEmitter)
+                params.chunkEmitter.emit('chunk', flushed);
+            else
+                process.stdout.write(flushed);
+            buffer = initialBufferState();
+        }
+        // Repair partial blocks before persistence — drop incomplete tool_use
+        // fragments so the next API call doesn't reject the assistant message.
+        // See ./repair-partial.ts for the full rationale.
+        if (interruptedError !== null) {
+            currentAssistantContent = repairPartialBlocks(currentAssistantContent);
+        }
+        // Persist the assistant message — even if it's partial. Empty content
+        // arrays are skipped so we don't push a meaningless empty assistant
+        // message that would confuse the next round.
+        if (currentAssistantContent.length > 0) {
+            session.messages.push({ role: 'assistant', content: currentAssistantContent });
+        }
+        session.last_turn_at = new Date().toISOString();
+        if (interruptedError !== null) {
+            session.turnInterrupted = true;
+            const msg = interruptedError instanceof Error ? interruptedError.message : String(interruptedError);
+            session.turnInterruptedReason = msg.slice(0, 200);
+        }
+        else {
+            // Clean completion — clear any stale interrupted flag from a prior turn.
+            session.turnInterrupted = false;
+            session.turnInterruptedReason = undefined;
+        }
+        await saveSession(session);
+        // Close the stream-to-disk mirror with a footer (lightweight diagnostics).
+        // Best-effort — failure here is invisible to the turn flow.
+        void turnStreamWriter.close(interruptedError !== null
+            ? `_interrupted: ${session.turnInterruptedReason ?? 'unknown'}_`
+            : undefined);
+        // Re-throw AFTER persistence so the outer REPL catch can render the
+        // graceful error UX with full session-id + log-path context.
+        if (interruptedError !== null)
+            throw interruptedError;
+        if (sawEndTurn) {
+            emit('');
+            // v0.6 Layer 3 — stream-end watchdog warning. The between-rounds
+            // watchdog in the loop body only fires for multi-round turns (heavy
+            // tool calls). A single-round text-only emission (no tool calls)
+            // bypasses that path entirely, so a model can stream past the budget
+            // unchecked. We can't inject a synthetic advisory at this point —
+            // the turn is over — but we CAN warn the user that the turn went
+            // long, so they tighten the next prompt or disable the watchdog
+            // for genuinely-long-by-design analyses.
+            if (!watchdogWarned) {
+                const outputTokensThisTurn = Math.max(0, (session.usage?.output_tokens ?? 0) - turnStartOutputTokens);
+                const decision = evaluateWatchdog({
+                    startedAt: turnStartedAt,
+                    outputTokensThisTurn,
+                    config: watchdogConfig,
+                    alreadyWarned: false,
+                });
+                if (decision.shouldWarn) {
+                    emit(chalk.yellow(`[watchdog] Turn ran past budget: ${decision.reason}.`));
+                    emit(chalk.gray(`           Consider a more focused prompt next time, or set CSPEACH_TURN_WATCHDOG=off if`));
+                    emit(chalk.gray(`           this skill is genuinely long-by-design (e.g. /abap-cca on a large estate).`));
+                }
+            }
+            // v0.3.1 — if the last assistant message ended with a question marker
+            // ("Reply with your answer..." or <!-- widget-real -->), set the flag
+            // so the REPL routes the user's next prompt back to this same skill
+            // without re-classifying. Otherwise clear the flag so normal
+            // classification resumes.
+            session.awaitingSkillAnswer = lastAssistantIsAwaitingAnswer(session.messages);
+            await saveSession(session);
+            // Handover/takeover hook (Task C5):
+            // After certain skills (currently /abap-spec-gap) render their final
+            // answer, offer to save it as a project file. The hook runs AFTER the
+            // response is rendered (emit('') above flushed) and BEFORE returning,
+            // so the user sees the answer first, then is asked whether to save.
+            // It awaits the user's y/N reply before returning — interactive, not
+            // a background block on the next REPL prompt.
+            //
+            // 2026-05-12: collect text from ALL assistant messages added during
+            // this turn, not just the final one. Skills like /abap-cca emit
+            // their manifest in an early message before a closing ask_question
+            // widget; the final wrap-up message ends the turn but doesn't
+            // carry the manifest. See ./turn-assistant-text.ts for details.
+            const assistantText = collectTurnAssistantText(session.messages, turnStartMessageCount);
+            await maybeOfferSave({
+                skill: params.skill,
+                assistantText,
+                userMessage: userMessageForSave,
+                tokensUsed: Math.max(0, (session.usage?.output_tokens ?? 0) - turnStartOutputTokens),
+                model: cfg.default_model ?? session.model ?? 'unknown',
+                emit,
+                promotedFrom: promotedFromForSave,
+            });
+            return;
+        }
+        if (!sawToolUse) {
+            // Unexpected stop reason — bail to avoid infinite loop.
+            emit(chalk.yellow('\n[unexpected stop reason — ending turn]'));
+            return;
+        }
+        // Dispatch each tool_use block.
+        const toolResults = [];
+        for (const block of currentAssistantContent) {
+            if (block.type === 'tool_use') {
+                // Phase 1: print the dispatch line (CC-style: ⏺ name(args)).
+                renderToolCallTop({
+                    name: block.name,
+                    args: (block.input ?? {}),
+                    chunkEmitter: params.chunkEmitter,
+                });
+                // Phase 2a: start the peach-themed spinner. No-op outside TTY / Ink
+                // / CI — the result line still prints, just without the in-place
+                // animation. Spinner is purely a "still working" cue, not
+                // load-bearing for output.
+                const spinner = startToolSpinner({ chunkEmitter: params.chunkEmitter });
+                // Phase 2b: dispatch (may take 100ms–several seconds for write tools).
+                const dispatchStart = Date.now();
+                const result = await dispatchTool(block.name, block.input, params.ctx);
+                const durationMs = Date.now() - dispatchStart;
+                // Phase 2c: stop the spinner, which erases its line so the result
+                // row paints in place of it (no scrollback artifacts).
+                spinner.stop();
+                // Phase 3: print result line (  ⎿ ✓ summary · timing).
+                const resultSummary = result.is_error
+                    ? (typeof result.content === 'string' ? result.content.slice(0, 80) : 'error')
+                    : undefined;
+                renderToolCallBottom({
+                    durationMs,
+                    isError: result.is_error ?? false,
+                    resultSummary,
+                    chunkEmitter: params.chunkEmitter,
+                });
+                // v0.3 (Step 28.0): populate session.toolCalls so the SessionTimeline
+                // overlay can render per-write history. Cap per-entry payload size at
+                // 4kB to bound session.json growth.
+                const completedAt = new Date().toISOString();
+                {
+                    const resultText = typeof result.content === 'string'
+                        ? result.content
+                        : JSON.stringify(result.content);
+                    session.toolCalls.push({
+                        tool_use_id: block.id,
+                        tool: block.name,
+                        args: block.input ?? {},
+                        result: resultText.slice(0, 4_000),
+                        is_error: result.is_error ?? false,
+                        duration_ms: durationMs,
+                        completed_at: completedAt,
+                        completed: true,
+                    });
+                }
+                // Layer 2 — skill-level checkpoint. Always-on JSONL audit log of every
+                // tool call, plus optional skill-specific handlers (registered via
+                // skill-checkpoint.ts). Best-effort; failures are swallowed and never
+                // break a working turn. See agent/skill-checkpoint.ts for rationale.
+                void applyToolResultCheckpoint({
+                    sessionId: session.id,
+                    skill: session.skill,
+                    toolName: block.name,
+                    args: block.input ?? {},
+                    result: result.content,
+                    isError: result.is_error ?? false,
+                    durationMs,
+                    completedAt,
+                });
+                // Retry-cap: track consecutive failures per (tool, object) pair.
+                // This block runs BEFORE the normal toolResults.push below.
+                const objKey = objectKeyFromInput(block.name, block.input ?? {});
+                if (result.is_error) {
+                    const count = (failMap.get(objKey) ?? 0) + 1;
+                    failMap.set(objKey, count);
+                    if (count >= RETRY_CAP) {
+                        // Cap hit — push the error result, save session, and abort the turn.
+                        toolResults.push({
+                            type: 'tool_result',
+                            tool_use_id: block.id,
+                            is_error: true,
+                            content: JSON.stringify({
+                                error: ERR.APPROVAL_THRASH,
+                                detail: `Retry cap hit after ${RETRY_CAP} consecutive failures on ${objKey}. Aborting turn.`,
+                            }),
+                        });
+                        session.messages.push({ role: 'user', content: toolResults });
+                        await saveSession(session);
+                        emit(chalk.red(`\n[retry cap] ${objKey} failed ${RETRY_CAP} times — aborting turn.`));
+                        return;
+                    }
+                }
+                else {
+                    failMap.delete(objKey); // reset on success
+                }
+                // Normal path falls through: the existing `toolResults.push(...)` block
+                // immediately below handles both success and the not-yet-capped failure case.
+                toolResults.push({
+                    type: 'tool_result',
+                    tool_use_id: block.id,
+                    content: result.content,
+                    is_error: result.is_error,
+                });
+            }
+        }
+        session.messages.push({ role: 'user', content: toolResults });
+        await saveSession(session);
+        // v0.6 Layer 3 — between-rounds watchdog check. If the turn has been
+        // running too long (wall-clock or token budget), inject a synthetic
+        // user message asking the model to checkpoint + summarise + hand back
+        // to the user. The model decides whether to wrap up or push through.
+        {
+            const outputTokensThisTurn = Math.max(0, (session.usage?.output_tokens ?? 0) - turnStartOutputTokens);
+            const decision = evaluateWatchdog({
+                startedAt: turnStartedAt,
+                outputTokensThisTurn,
+                config: watchdogConfig,
+                alreadyWarned: watchdogWarned,
+            });
+            if (decision.shouldWarn) {
+                watchdogWarned = true;
+                emit(chalk.yellow(`\n[watchdog] ${decision.reason}. Asking the model to wrap up.`));
+                session.messages.push({ role: 'user', content: decision.message });
+                await saveSession(session);
+            }
+        }
+        // Loop continues → next messages.create with the tool results.
+    }
+}