@canonmsg/claude-code-plugin 0.28.1 → 0.29.0

package/dist/host.js

@@ -27,14 +27,14 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { isAnthropicImageAttachment, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
-import { captureTurnArtifactSnapshot, collectTurnArtifacts, } from '@canonmsg/coding-agent-host';
-import { CLAUDE_EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonInboundFrameV1, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, normalizeRuntimeCommandDescriptors, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, ControlChannelPoller, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, RuntimeRequestManager, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, readLocalRuntimeEntry, resolveCanonAgent, verifyResolvedAgentEnvironment, initRTDBAuth, sendMessageWithRetry, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { captureTurnArtifactSnapshot, collectTurnArtifacts, IDLE_TIMEOUT_MS, } from '@canonmsg/coding-agent-host';
+import { CLAUDE_EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonInboundFrameV1, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, normalizeRuntimeCommandDescriptors, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, buildBoundedTurnTrail, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, ControlChannelPoller, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, RuntimeRequestManager, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, readLocalRuntimeEntry, resolveCanonAgent, verifyResolvedAgentEnvironment, initRTDBAuth, isChunkedSendMessageError, sendMessageWithRetry, sendMessageWithRetryChunked, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { decideAutoReply, } from './inbound-policy.js';
 import { runCli } from './cli-entry.js';
 import { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer } from '@canonmsg/agent-tools';
 import { synthesizeClaudeApprovalDiff } from './approval-diff.js';
 import { decideClaudeToolPermissionForMode, parseAllowedNonOwnerClaudeTools, } from './tool-policy.js';
-import { applyClaudeSessionControl, buildClaudeFinalMessageId, buildClaudeFinalTurnMetadata, buildClaudeTurnFailureNotice, claudeInputOwnsTurnSlot, rememberDispatchedClaudeInput, takeClaudeResultOwner, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeFinalText, describeUndeliveredClaudeFinal, confirmClaudeInterrupt, createClaudeInputEnvelope, deriveClaudeSupplementalModelProbes, formatClaudeCliVersion, formatClaudeControlError, isClaudeCustomModelOption, isSupportedClaudeCliVersion, mergeClaudeDiscoveredModelOptions, parseClaudeCliVersion, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, MINIMUM_CLAUDE_CLI_VERSION, } from './session-state.js';
+import { applyClaudeSessionControl, boundClaudeFinalMetadata, buildClaudeFinalChunkingOptions, buildClaudeFinalMessageId, buildClaudeFinalTurnMetadata, buildClaudePendingFinalDelivery, buildClaudeTurnFailureNotice, buildTruncatedFinalText, buildUndeliverableFinalNotice, canDrainClaudeQueuedInput, claudeFinalWillChunk, classifyFinalDeliveryFailure, claudeInputOwnsTurnSlot, createClaudeTurnActivityState, decideClaudeControlSignalAction, decideClaudeInboundDispatch, dispatchClaudeInput, isClaudeTurnSlotReserved, readClaudeFinalDeliveryResume, releaseClaudeTurnSlot, runClaudeExhaustedFinalDelivery, shouldApplyClaudeEchoedSessionState, shouldReleaseClaudeTurnSlot, isClaudeMainTurnMessage, openClaudeTurn, planClaudeAssistantTrail, planClaudeToolCallStart, planClaudeToolProgress, planClaudeToolResults, prepareTurnTrailForDelivery, rememberDispatchedClaudeInput, resetClaudeTurnActivityState, shouldOpenClaudeTurnOnRunning, isOpenClaudeTurnState, takeClaudeResultOwner, takeClaudeToolBlockIdByIndex, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeFinalText, describeUndeliveredClaudeFinal, confirmClaudeInterrupt, createClaudeInputEnvelope, deriveClaudeSupplementalModelProbes, formatClaudeCliVersion, formatClaudeControlError, isClaudeCustomModelOption, isSupportedClaudeCliVersion, mergeClaudeDiscoveredModelOptions, parseClaudeCliVersion, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, MINIMUM_CLAUDE_CLI_VERSION, } from './session-state.js';
 import { CLAUDE_SUPPORTED_DIALOG_KINDS, buildClaudeAskUserPermissionDenied, buildClaudeAskUserPermissionResult, createClaudeUserDialogCoordinator, parseClaudeAskUserDialog, parseClaudeAskUserToolInput, resolveClaudeUserDialogRequestId, } from './user-dialog.js';
 import { collectMissedInboundMessages, createReconnectRecoveryGate, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
 function parseRuntimeVisibilityPreset(value) {
@@ -677,7 +677,7 @@ function buildClaudeRuntimeInfo(input) {
 }
 // ── Constants ───────────────────────────────────────────────────────
 const MAX_SESSIONS = 5;
-const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+// IDLE_TIMEOUT_MS (30 minutes) is shared with the other coding-agent hosts.
 const STREAMING_THROTTLE_MS = 250;
 const HEARTBEAT_MS = 30_000;
 const IDLE_CHECK_MS = 60_000;
@@ -685,7 +685,11 @@ const CONTROL_POLL_MS = 2000;
 const IDLE_CONTROL_POLL_MS = 10_000;
 const CONTROL_POLL_JITTER_MS = 1_000;
 const FINAL_DELIVERY_RETRY_MS = 30_000;
-const MAX_FINAL_DELIVERY_RETRIES = 1;
+// The timer now only ever re-sends genuinely retryable failures (429/5xx/
+// transport) — permanent rejections are surfaced immediately instead of
+// consuming this budget — so one more attempt buys a longer outage window
+// without delaying anything that was going to fail anyway.
+const MAX_FINAL_DELIVERY_RETRIES = 2;
 const CLAUDE_RECOVERY_CURSOR_WORKSPACE_ID = 'claude-recovery-cursor-v1';
 const CLAUDE_RUNTIME_CAPABILITIES = {
     ...DEFAULT_RUNTIME_CAPABILITIES,
@@ -1120,6 +1124,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         finalDeliveryTimer: null,
         pendingInputs: [],
         activeInput: null,
+        dispatchingInput: null,
         finalizedTurnKeys: new Set(),
         interruptedTurnKeys: new Set(),
         pendingFinalText: null,
@@ -1130,6 +1135,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         currentTurnId: null,
         currentTurnOpenedAt: null,
         currentTurnUpdatedAt: null,
+        turnActivity: createClaudeTurnActivityState(),
         activeSelfContextId: null,
         lastAcceptedIntent: null,
         lastActivity: Date.now(),
@@ -1183,6 +1189,10 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         return Boolean(turnKey && session.interruptedTurnKeys.has(turnKey));
     }
     function clearStreaming() {
+        // The trail bookkeeping only ever points at blocks inside the node being
+        // cleared, so it dies with it. Doing this here covers every caller —
+        // interrupts, session reset, session close — rather than each remembering.
+        resetClaudeTurnActivityState(session.turnActivity);
         return streamingOutput.clear().catch(() => { });
     }
     function markInputCompleted(input) {
@@ -1203,9 +1213,20 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         }
         config.onInputCompleted?.(input.sourceMessageId);
     }
-    function getFinalTurnTrail() {
+    /**
+     * The turn trail to attach to the final send.
+     *
+     * Filtering runs BEFORE bounding on purpose. `buildBoundedTurnTrail` walks
+     * blocks in sequence order and stops at the first one that would exceed its
+     * byte budget, and Claude's text blocks are the fattest entries — bounding
+     * first would spend the budget on blocks a chunked final then discards,
+     * leaving the margin with fewer tool blocks than it could have shown. With
+     * `willChunk` false this is exactly `getFinalTrail()`.
+     */
+    function getFinalTurnTrail(willChunk) {
         const turnId = session.currentTurnId ?? `claude-${conversationId}`;
-        return streamingOutput.getFinalTrail().map((block) => ({ ...block, turnId }));
+        const blocks = prepareTurnTrailForDelivery(streamingOutput.getBlocks(), willChunk);
+        return buildBoundedTurnTrail(blocks).map((block) => ({ ...block, turnId }));
     }
     function clearIdleResetTimer() {
         if (!session.idleResetTimer)
@@ -1219,10 +1240,31 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         clearTimeout(session.finalDeliveryTimer);
         session.finalDeliveryTimer = null;
     }
+    /**
+     * Retire the finished turn and start the next queued one.
+     *
+     * The live node is cleared HERE, unconditionally, rather than only at the
+     * three call sites that remembered to: `drainPendingInput` below opens the
+     * next turn, and a surviving `/streaming` node still carrying the previous
+     * turn's id makes the client drop the new turn's live row entirely
+     * (chat-domain buildSyntheticTurnMessages skips a turn whose streaming turnId
+     * disagrees) — the same silence this PR is closing.
+     *
+     * Clearing `/streaming` fires functions' `onStreamingCleared`, which persists
+     * the streamed text as a "preserved" progress message when the turn has no
+     * `turn_complete`. Doing it universally does NOT widen that: every existing
+     * caller (final handoff, retry exhaustion, and the gated/no-final branch of
+     * the result handler) already clears immediately before calling this, so a
+     * gated turn's node is deleted today exactly as it is here — RTDB fires the
+     * trigger on the delete that had data, and the redundant second delete has
+     * nothing to fire on. The turn-open seed is empty (no text, no blocks), which
+     * the trigger itself skips as `empty_streaming_content`.
+     */
     function resetTurnToIdle() {
         if (session.closed)
             return;
         clearFinalDeliveryTimer();
+        clearStreaming().catch(() => { });
         resetClaudeCompletedTurnState(session);
         stopVisibleWorkSignal();
         writeState();
@@ -1238,23 +1280,23 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             resetTurnToIdle();
         }, FINAL_MESSAGE_HANDOFF_MS);
     }
-    function markPendingFinalDelivery(finalText, turn, suppressAutoReply = false) {
+    function markPendingFinalDelivery(finalText, turn, suppressAutoReply = false, progress = {}) {
         clearIdleResetTimer();
-        const retryCount = session.pendingFinalDelivery?.turnKey === turn.turnKey
-            ? session.pendingFinalDelivery.retryCount
-            : 0;
         session.pendingFinalText = finalText;
-        session.pendingFinalDelivery = {
+        // Records how far the send got, so the retry resumes at the first part that
+        // is NOT durable instead of replaying the answer from part 1.
+        session.pendingFinalDelivery = buildClaudePendingFinalDelivery({
+            previous: session.pendingFinalDelivery,
             turnKey: turn.turnKey,
             text: finalText,
-            retryCount,
-            ...(suppressAutoReply ? { suppressAutoReply: true } : {}),
             messageId: buildClaudeFinalMessageId({
                 agentId,
                 conversationId,
                 turnKey: turn.turnKey,
             }),
-        };
+            suppressAutoReply,
+            ...progress,
+        });
         session.state.state = 'running';
         session.turnState = 'streaming';
         stopVisibleWorkSignal();
@@ -1263,6 +1305,119 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         writeTurn();
         typingSignals.start(conversationId, 'typing').catch(() => { });
     }
+    /**
+     * Hand the turn slot back for a turn that has finished — unless a NEWER turn
+     * already holds it.
+     *
+     * Finishing a turn spans awaits (the final send, the context-usage read), and
+     * the session reads 'idle' to inbound messages from the SDK's idle echo
+     * onward. A message arriving in that window reserves the slot for itself;
+     * releasing it unconditionally afterwards would hand the same slot to a
+     * second message and race two turns into the SDK — the very thing the
+     * reservation exists to prevent.
+     */
+    function releaseTurnSlotFor(turn) {
+        if (!shouldReleaseClaudeTurnSlot({
+            dispatching: session.dispatchingInput !== null,
+            activeTurnKey: session.activeInput?.turnKey ?? null,
+            completedTurnKey: turn?.turnKey ?? null,
+        }))
+            return;
+        releaseClaudeTurnSlot(session);
+    }
+    function markFinalTurnDelivered(turn) {
+        session.finalizedTurnKeys.add(turn.turnKey);
+        markInputCompleted(turn);
+        releaseTurnSlotFor(turn);
+        session.pendingFinalDelivery = null;
+        clearFinalDeliveryTimer();
+        writeState();
+    }
+    /**
+     * The standalone "Canon rejected the reply" message — additive, and it
+     * carries the `turn_complete` the interim→final handoff needs. Shared by the
+     * permanent-rejection path and by retry exhaustion after a partial chunked
+     * delivery, so both say the same thing under the same id.
+     */
+    async function sendUndeliverableFinalNotice(input) {
+        const selfContextId = input.selfContextId !== undefined
+            ? input.selfContextId
+            : session.activeSelfContextId;
+        try {
+            await sendMessageWithRetry(client, conversationId, input.notice, {
+                messageId: `${input.finalMessageId}-undelivered`,
+                ...(selfContextId ? { selfContextId } : {}),
+                metadata: {
+                    turnId: session.currentTurnId,
+                    turnSemantics: 'turn_complete',
+                    replyBehavior: 'suppress_auto_reply',
+                },
+            });
+            return 'notice';
+        }
+        catch (noticeErr) {
+            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Undeliverable-final notice also rejected:`, noticeErr);
+            return 'none';
+        }
+    }
+    /**
+     * Last resort when Canon permanently refuses the final: get SOMETHING durable
+     * into the conversation rather than letting the turn end on a torn-down live
+     * bubble.
+     *
+     * A SINGLE-MESSAGE final is re-sent under the normal final message id with no
+     * turn trail — the trail is the likeliest residual cause of a 4xx, and that id
+     * is idempotent, threads correctly and completes the interim handoff.
+     * (`buildTruncatedFinalText` is the bound that keeps the payload legal; text
+     * reaching this path already fits, so nothing is actually cut.)
+     *
+     * A CHUNKED final is deliberately NOT re-sent. Its parts are already durable
+     * under `${finalMessageId}-part-N`, so re-sending the answer's head would
+     * repeat what the reader already has and still leave the tail missing — and
+     * the resume path has by now exhausted the ways of delivering that tail. Only
+     * the notice goes out — additive, and it carries the `turn_complete` the
+     * handoff needs.
+     */
+    async function surfaceUndeliverableFinal(input) {
+        const selfContextId = input.selfContextId !== undefined
+            ? input.selfContextId
+            : session.activeSelfContextId;
+        const selfContext = selfContextId ? { selfContextId } : {};
+        if (!input.chunked) {
+            const degraded = buildTruncatedFinalText(input.finalText);
+            try {
+                await sendMessageWithRetry(client, conversationId, degraded, {
+                    messageId: input.finalMessageId,
+                    ...selfContext,
+                    // No turn trail: the metadata is a candidate cause of a residual 4xx,
+                    // and an activity record is worth less than the answer itself.
+                    metadata: buildClaudeFinalTurnMetadata({
+                        turnId: session.currentTurnId,
+                        turnKey: input.turn.turnKey,
+                        sourceMessageId: input.turn.sourceMessageId,
+                        deliveryIntent: session.lastAcceptedIntent,
+                        suppressAutoReply: input.suppressAutoReply,
+                    }),
+                });
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+                    + (degraded.length === input.finalText.length
+                        ? 'Delivered the final without its turn trail after a permanent rejection'
+                        : `Delivered a truncated final (${degraded.length} of ${input.finalText.length} chars) after a permanent rejection`));
+                return 'resent';
+            }
+            catch (resendErr) {
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] Trail-free final also rejected:`, resendErr);
+            }
+        }
+        return sendUndeliverableFinalNotice({
+            finalMessageId: input.finalMessageId,
+            selfContextId,
+            notice: buildUndeliverableFinalNotice({
+                error: input.error,
+                partiallyDelivered: input.partiallyDelivered,
+            }),
+        });
+    }
     async function deliverFinalReply(finalText, turn = session.activeInput, suppressAutoReply = false) {
         if (!shouldDeliverClaudeFinal({
             turn,
@@ -1279,33 +1434,100 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             conversationId,
             turnKey: deliverTurn.turnKey,
         });
+        // A final over Canon's 4 KB text cap is split into ordered messages instead
+        // of being rejected whole. A final that fits keeps the plain message id and
+        // metadata core uses for single-chunk sends, so the common case is
+        // unchanged.
+        const willChunk = claudeFinalWillChunk(finalText);
+        // A retry of THIS turn's final picks up where the last attempt stopped: the
+        // parts already durable are skipped, and the metadata that attempt built is
+        // replayed byte-for-byte (the server's idempotency fingerprint spans
+        // metadata, so a rebuilt trail would turn a replay into a 409).
+        const resume = readClaudeFinalDeliveryResume(session.pendingFinalDelivery, deliverTurn.turnKey);
+        const metadata = resume.metadata ?? boundClaudeFinalMetadata(buildClaudeFinalTurnMetadata({
+            turnId: session.currentTurnId,
+            turnKey: deliverTurn.turnKey,
+            sourceMessageId: deliverTurn.sourceMessageId,
+            deliveryIntent: session.lastAcceptedIntent,
+            turnTrail: getFinalTurnTrail(willChunk),
+            suppressAutoReply,
+        }));
+        // Pinned for the same reason as the metadata: `selfContextId` is part of the
+        // server's idempotency fingerprint, and `session.activeSelfContextId` moves
+        // with every inbound message — including the ones that merely queue behind
+        // this delivery. Reading it fresh per attempt would land a resumed tail in a
+        // different self-context from its own head.
+        const selfContextId = resume.selfContextId !== undefined
+            ? resume.selfContextId
+            : session.activeSelfContextId;
         try {
-            await sendMessageWithRetry(client, conversationId, finalText, {
+            const { messageIds } = await sendMessageWithRetryChunked(client, conversationId, finalText, {
                 messageId: finalMessageId,
-                ...(session.activeSelfContextId
-                    ? { selfContextId: session.activeSelfContextId }
-                    : {}),
-                metadata: buildClaudeFinalTurnMetadata({
-                    turnId: session.currentTurnId,
-                    turnKey: deliverTurn.turnKey,
-                    sourceMessageId: deliverTurn.sourceMessageId,
-                    deliveryIntent: session.lastAcceptedIntent,
-                    turnTrail: getFinalTurnTrail(),
-                    suppressAutoReply,
-                }),
-            });
-            session.finalizedTurnKeys.add(deliverTurn.turnKey);
-            markInputCompleted(deliverTurn);
-            session.state.state = 'idle';
-            session.pendingFinalDelivery = null;
-            clearFinalDeliveryTimer();
-            writeState();
-            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Sent final reply (${finalText.length} chars)`);
+                ...(selfContextId ? { selfContextId } : {}),
+                metadata,
+            }, {}, buildClaudeFinalChunkingOptions(resume));
+            markFinalTurnDelivered(deliverTurn);
+            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Sent final reply (${finalText.length} chars`
+                + `${messageIds.length > 1 ? `, ${messageIds.length} parts` : ''}`
+                + `${resume.deliveredMessageIds.length > 0
+                    ? `, resumed at part ${resume.deliveredMessageIds.length + 1}`
+                    : ''})`);
             return true;
         }
         catch (err) {
-            markPendingFinalDelivery(finalText, deliverTurn, suppressAutoReply);
-            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to send final reply:`, err);
+            // A chunked failure carries how far it got; everything below classifies
+            // and reports the CAUSE, not the wrapper.
+            const chunkedFailure = isChunkedSendMessageError(err) ? err : null;
+            const cause = chunkedFailure ? chunkedFailure.cause : err;
+            const deliveredMessageIds = chunkedFailure
+                ? chunkedFailure.deliveredMessageIds
+                : resume.deliveredMessageIds;
+            const failure = classifyFinalDeliveryFailure(cause, { chunked: willChunk });
+            if (failure === 'already-delivered') {
+                // The server's idempotency guard says this final is already durable.
+                markFinalTurnDelivered(deliverTurn);
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] Final reply was already delivered under this id`);
+                return true;
+            }
+            if (failure === 'permanent') {
+                // Re-sending is pointless — the same request fails the same way. Surface
+                // what can be surfaced and finish the turn instead of burning the retry
+                // budget and dropping the answer in silence.
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] Final reply permanently rejected:`, err);
+                // Surface FIRST, mark delivered SECOND. markFinalTurnDelivered persists
+                // the inbound recovery cursor (so a restart will not replay this
+                // message) and reopens the session to new input; neither may happen
+                // while delivery is still unresolved.
+                const outcome = await surfaceUndeliverableFinal({
+                    finalText,
+                    turn: deliverTurn,
+                    finalMessageId,
+                    suppressAutoReply,
+                    selfContextId,
+                    chunked: willChunk,
+                    // The notice only claims the reply "stops short" when parts of it
+                    // really are in the conversation — now known exactly, instead of
+                    // being inferred from "this was a chunked send".
+                    partiallyDelivered: deliveredMessageIds.length > 0,
+                    error: cause,
+                });
+                if (outcome === 'none') {
+                    console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+                        + 'Nothing durable could be sent for this turn; the streamed text is the only record left');
+                }
+                markFinalTurnDelivered(deliverTurn);
+                return true;
+            }
+            markPendingFinalDelivery(finalText, deliverTurn, suppressAutoReply, {
+                metadata,
+                selfContextId,
+                deliveredMessageIds,
+                lastErrorMessage: cause instanceof Error ? cause.message : String(cause),
+            });
+            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to send final reply`
+                + `${deliveredMessageIds.length > 0
+                    ? ` after ${deliveredMessageIds.length} of ${chunkedFailure?.totalParts ?? '?'} parts`
+                    : ''}:`, err);
             return false;
         }
     }
@@ -1351,9 +1573,29 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         if (!pending || session.closed || session.pendingFinalDelivery?.turnKey !== pending.turnKey)
             return;
         if (pending.retryCount >= MAX_FINAL_DELIVERY_RETRIES) {
-            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Final reply delivery exhausted after bounded retries`);
-            session.pendingFinalDelivery = null;
-            resetTurnToIdle();
+            const deliveredParts = pending.deliveredMessageIds?.length ?? 0;
+            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Final reply delivery exhausted after bounded retries`
+                + `${deliveredParts > 0 ? ` with ${deliveredParts} part(s) delivered` : ''}`);
+            // Part of the answer IS in the conversation and the tail is never coming;
+            // the notice says it stops short instead of leaving the last delivered
+            // part looking like the end. The pending record stays set until the turn
+            // is actually retired, so inbound messages keep queueing across the send.
+            void runClaudeExhaustedFinalDelivery(session, pending, {
+                sendNotice: (notice) => sendUndeliverableFinalNotice({
+                    finalMessageId: pending.messageId,
+                    selfContextId: pending.selfContextId,
+                    notice,
+                }),
+                retireTurn: () => {
+                    // Hand the answer to the server-side safety net: clearing /streaming
+                    // fires onStreamingCleared, which persists the streamed text as a
+                    // durable progress message when the turn has no turn_complete.
+                    // Without this the live bubble was torn down by the idle reset and
+                    // the work was lost.
+                    clearStreaming().catch(() => { });
+                    resetTurnToIdle();
+                },
+            });
             return;
         }
         pending.retryCount += 1;
@@ -1443,10 +1685,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         writeState();
     }
     function writeTurn() {
-        const isOpenTurn = session.turnState === 'thinking'
-            || session.turnState === 'streaming'
-            || session.turnState === 'tool'
-            || session.turnState === 'waiting_input';
+        const isOpenTurn = isOpenClaudeTurnState(session.turnState);
         if (isOpenTurn) {
             session.currentTurnUpdatedAt = Date.now();
         }
@@ -1489,10 +1728,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
     async function prepareArtifactsForInput(input) {
         if (input.kind !== 'canon')
             return;
-        if (!session.currentTurnId) {
-            session.currentTurnId = randomUUID();
-            session.currentTurnOpenedAt = Date.now();
-        }
+        // The turn id is minted by openTurn(), which runs before this.
         if (input.artifactRoutingMode === 'workspace-generated') {
             input.artifactBaseline = await captureTurnArtifactSnapshot({ cwd: session.cwd }).catch((error) => {
                 console.error(`[canon-host] [${conversationId.slice(0, 8)}] Artifact snapshot failed:`, error instanceof Error ? error.message : error);
@@ -1501,24 +1737,149 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             return;
         }
     }
-    async function startCanonInput(input) {
-        await markQueuedMessageAccepted(input.sourceMessageId, input.markAccepted);
-        await prepareArtifactsForInput(input);
-        session.state.state = 'running';
-        sendInput(input);
+    /**
+     * Make the turn visible the moment it is dequeued, before the SDK has said
+     * anything.
+     *
+     * Until now the first publish of any kind came from the SDK echoing
+     * `session_state_changed: running`, and the first thing the reader saw came
+     * later still, with the first streamed token — so an accepted message looked
+     * like nothing had happened. Opening synchronously here (Codex does the same
+     * at its dequeue) gives the reader the thinking header, the typing dots and a
+     * live turn row immediately; the seed is status-only because text written to
+     * `/streaming` is rendered as the agent's speech.
+     */
+    function openTurn(input) {
+        // Only Canon turns are user-facing; internal envelopes stay invisible.
+        if (session.closed || !claudeInputOwnsTurnSlot(input))
+            return;
+        clearIdleResetTimer();
+        openClaudeTurn(session);
+        startVisibleWorkSignal();
+        writeTurn();
+        seedTurnStreaming();
+    }
+    /**
+     * Open `/streaming` for a turn that is starting: drop whatever the previous
+     * turn left there, then seed the empty thinking node.
+     *
+     * The clear is what makes the seed empty. `startThinking('')` resets the
+     * node's TEXT and nothing else — the controller's block array survives until
+     * `clear()` — and `openTurn` cancels (`clearIdleResetTimer`) the handoff reset
+     * that would otherwise have cleared it. So a turn opened inside the 750ms
+     * handoff window would republish the FINISHED turn's receipts and plan card
+     * under its own id, `openClaudeTurn` having just dropped the bookkeeping that
+     * could still complete them, and `getFinalTurnTrail` would then hang them on
+     * the next final's persisted trail.
+     *
+     * Safe with respect to functions' `onStreamingCleared`: the node being
+     * deleted still carries the finished turn's id, which by definition has a
+     * `turn_complete` message (its final was delivered), so the fallback skips as
+     * `turn_complete_exists`. On every other path the node is already gone and
+     * the delete has nothing to fire on.
+     */
+    function seedTurnStreaming() {
+        clearStreaming().catch(() => { });
+        streamingOutput.startThinking('').catch(() => { });
+    }
+    function applyTrailCommands(commands) {
+        for (const command of commands) {
+            switch (command.op) {
+                case 'add':
+                    streamingOutput.addBlock({
+                        id: command.id,
+                        kind: command.kind,
+                        ...(command.status ? { status: command.status } : {}),
+                        ...(command.title ? { title: command.title } : {}),
+                        ...(command.text ? { text: command.text } : {}),
+                    }).catch(() => { });
+                    break;
+                case 'update':
+                    streamingOutput.updateBlock(command.id, {
+                        ...(command.title !== undefined ? { title: command.title } : {}),
+                        ...(command.summary !== undefined ? { summary: command.summary } : {}),
+                    }).catch(() => { });
+                    break;
+                case 'complete':
+                    streamingOutput.completeBlock(command.id, command.summary === undefined ? undefined : { summary: command.summary }).catch(() => { });
+                    break;
+                case 'fail':
+                    streamingOutput.failBlock(command.id, { summary: command.summary }).catch(() => { });
+                    break;
+            }
+        }
+    }
+    /**
+     * Settle an input that never reached Claude.
+     *
+     * Both ways out of the dispatch window used to just drop it: the sender's
+     * message stayed 'accepted' forever, the id stayed in the host's in-flight
+     * set (it is in neither `pendingInputs` nor `activeInput`, so no reset path
+     * settles it either), and the reader watched a 'thinking' turn appear and
+     * vanish with no answer. Telling the sender it was rejected is the honest
+     * ending, and it matches what every other undelivered input gets.
+     */
+    function abandonDispatchedInput(input, reason, error) {
+        console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+            + `Turn dispatch ${reason === 'closed' ? 'abandoned: session closed mid-dispatch' : 'failed'} `
+            + `before the input reached Claude${input.sourceMessageId ? ` (message ${input.sourceMessageId})` : ''}${error === undefined ? '' : ':'}`, ...(error === undefined ? [] : [error instanceof Error ? error.message : error]));
+        if (input.markAccepted && input.sourceMessageId) {
+            void client
+                .updateMessageDisposition(conversationId, input.sourceMessageId, 'rejected')
+                .catch(() => { });
+        }
+        markInputCompleted(input);
+        // resetTurnToIdle releases the slot, tears the published turn down (typing
+        // signal, seeded /streaming, turn state) and drains the queue. On a closed
+        // session it is a no-op, which is correct: the teardown owns that path.
+        resetTurnToIdle();
+    }
+    function startCanonInput(input) {
+        return dispatchClaudeInput(session, input, {
+            openTurn,
+            markAccepted: (dispatched) => markQueuedMessageAccepted(dispatched.sourceMessageId, dispatched.markAccepted),
+            prepareArtifacts: prepareArtifactsForInput,
+            send: sendInput,
+            abandon: abandonDispatchedInput,
+        });
+    }
+    /**
+     * Fire-and-forget dispatch. `startCanonInput` handles its own failures, so
+     * this only catches what could throw before or after them — without it a
+     * rejection here would surface as an unhandled rejection and take the host
+     * process with it under `--unhandled-rejections=strict`.
+     */
+    function dispatchCanonInput(input) {
+        startCanonInput(input).catch((error) => {
+            if (session.dispatchingInput === input)
+                session.dispatchingInput = null;
+            abandonDispatchedInput(input, 'error', error);
+        });
     }
     function drainPendingInput() {
-        if (session.closed
-            || session.controlInterruptPending
-            || session.state.state === 'running'
-            || session.pendingInputs.length === 0)
+        if (!canDrainClaudeQueuedInput({
+            closed: session.closed,
+            controlInterruptPending: session.controlInterruptPending,
+            sessionState: session.state.state,
+            queueDepth: session.pendingInputs.length,
+        }))
             return;
         const next = session.pendingInputs.shift();
         if (!next)
             return;
         session.lastAcceptedIntent = next.intent;
-        writeTurn();
-        void startCanonInput(next);
+        // No writeTurn() here: it would publish the still-'idle' state (with a
+        // completedAt) for a turn that is starting. openTurn() publishes 'thinking'
+        // synchronously inside startCanonInput, carrying the new queue depth.
+        dispatchCanonInput(next);
+    }
+    /**
+     * True when an input has actually reached the SDK. Everything an interrupt
+     * acts on is keyed to this: in the dispatch window the input is still in the
+     * host's hands, so there is nothing for `query.interrupt()` to stop.
+     */
+    function hasInterruptibleSdkInput() {
+        return session.activeInput !== null && session.dispatchingInput === null;
     }
     enqueueInboundMessage = (msg, intent = 'queue', sourceMessageId = null, markAccepted = false, isOwnerTurn = false, requestingUserId = null, artifactRoutingMode = 'disabled') => {
         session.lastActivity = Date.now();
@@ -1532,17 +1893,28 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             requestingUserId,
             artifactRoutingMode,
         });
-        if (session.pendingFinalDelivery) {
-            session.pendingInputs.push(input);
-            writeTurn();
-            return;
-        }
-        if (session.state.state === 'running' && intent !== 'interrupt') {
-            session.pendingInputs.push(input);
+        const decision = decideClaudeInboundDispatch({
+            intent,
+            sessionState: session.state.state,
+            hasPendingFinalDelivery: Boolean(session.pendingFinalDelivery),
+            hasInterruptibleInput: hasInterruptibleSdkInput(),
+        });
+        if (decision === 'queue' || decision === 'queue-front') {
+            if (decision === 'queue-front') {
+                session.pendingInputs.unshift(input);
+                // An interrupt that arrived while the previous message was still being
+                // dispatched: nothing is in the SDK to stop, so it takes the front of
+                // the queue and starts the moment that turn ends.
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+                    + 'Interrupt arrived during turn dispatch; queued at the front instead');
+            }
+            else {
+                session.pendingInputs.push(input);
+            }
             writeTurn();
             return;
         }
-        if (session.state.state === 'running' && intent === 'interrupt') {
+        if (decision === 'interrupt') {
             session.pendingInputs.unshift(input);
             writeTurn();
             const interruptedInput = session.activeInput;
@@ -1561,10 +1933,27 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             return;
         }
         session.lastAcceptedIntent = intent;
-        writeTurn();
-        void startCanonInput(input);
+        // Same as in drainPendingInput: openTurn() does the publish, as 'thinking'.
+        dispatchCanonInput(input);
     };
     writeTurn();
+    // ── Turn activity (margin trail) ──
+    /** True when this `content_block_stop` closes a tool call this turn claimed. */
+    function isToolBlockStop(event) {
+        if (takeClaudeToolBlockIdByIndex(session.turnActivity, event?.index))
+            return true;
+        // Older runtimes may omit the index; fall back to the coarse flag rather
+        // than leaving the turn stuck in 'tool'.
+        return typeof event?.index !== 'number' && session.toolInProgress;
+    }
+    // The plan card is deliberately NOT pushed into the live bubble the way Codex
+    // does: Claude streams real speech there, and the plan belongs in the margin.
+    function applyAssistantToolCalls(content) {
+        applyTrailCommands(planClaudeAssistantTrail(session.turnActivity, content, session.currentTurnId ?? conversationId));
+    }
+    function applyToolResults(content) {
+        applyTrailCommands(planClaudeToolResults(session.turnActivity, content));
+    }
     // ── Process SDK output messages ──
     const processMessages = async () => {
         try {
@@ -1584,6 +1973,21 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         // the final. Gate on the owning turn instead of on arrival order.
                         if (!claudeInputOwnsTurnSlot(session.activeInput))
                             break;
+                        // A subagent's message is not this agent's speech. Its narration is
+                        // already kept out of the live bubble and its calls out of the
+                        // trail, so it must not become `pendingFinalText` either: that is
+                        // the fallback the final falls back to when the result carries no
+                        // text, and delivering it would surface as the answer text nobody
+                        // ever saw streamed.
+                        if (!isClaudeMainTurnMessage(msg.parent_tool_use_id))
+                            break;
+                        // The assistant message is the first place the tool call's typed
+                        // INPUT is visible — content_block_start carries only the name. It
+                        // is what turns "Bash" into "Running: npm test" and TodoWrite into
+                        // the plan card.
+                        if (!isActiveTurnInterrupted()) {
+                            applyAssistantToolCalls(msg.message?.content ?? []);
+                        }
                         const textBlocks = (msg.message?.content ?? [])
                             .filter((b) => b.type === 'text')
                             .map((b) => b.text);
@@ -1599,23 +2003,36 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                             stopVisibleWorkSignal();
                             break;
                         }
+                        // A subagent's own stream stays out of the turn ENTIRELY — its tool
+                        // calls and its text alike. The Task row stands for the whole
+                        // subagent; its calls would flood the trail (and the 20-block
+                        // budget the final's trail is bounded to), and its narration is not
+                        // this agent's speech: streamed into the live bubble it collides
+                        // with the main agent's own text segments and corrupts the answer
+                        // being written.
+                        if (!isClaudeMainTurnMessage(msg.parent_tool_use_id))
+                            break;
                         if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
+                            // Claimed per CALL, keyed by the SDK's tool_use id. The old id was
+                            // the turn id, so every call in a turn wrote over the same row.
+                            const commands = planClaudeToolCallStart(session.turnActivity, {
+                                toolUseId: event.content_block?.id,
+                                index: event.index,
+                                name: event.content_block?.name,
+                                turnId: session.currentTurnId ?? conversationId,
+                            });
                             session.toolInProgress = true;
                             session.turnState = 'tool';
-                            streamingOutput.addBlock({
-                                id: `tool:${session.currentTurnId ?? conversationId}`,
-                                kind: 'tool',
-                                status: 'running',
-                                title: typeof event.content_block?.name === 'string'
-                                    ? event.content_block.name
-                                    : 'Claude tool use',
-                            }).catch(() => { });
+                            applyTrailCommands(commands);
                             startVisibleWorkSignal();
                             writeTurn();
                         }
-                        else if (event?.type === 'content_block_stop' && session.toolInProgress) {
+                        else if (event?.type === 'content_block_stop' && isToolBlockStop(event)) {
+                            // The MODEL has finished writing the call; the tool has not run
+                            // yet. The row therefore stays 'running' until its tool_result
+                            // arrives — "completed" in the margin has to mean the tool
+                            // returned, which is what the old code got wrong.
                             session.toolInProgress = false;
-                            streamingOutput.completeBlock(`tool:${session.currentTurnId ?? conversationId}`).catch(() => { });
                             if (session.state.state === 'running') {
                                 session.turnState = 'thinking';
                                 startVisibleWorkSignal();
@@ -1632,21 +2049,70 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         }
                         break;
                     }
+                    case 'user': {
+                        // Where a tool call's OUTCOME arrives. Without this the margin's
+                        // receipts never resolved: rows were "completed" the moment the
+                        // model finished writing the call, and a failing tool looked
+                        // identical to a successful one.
+                        if (!isClaudeMainTurnMessage(msg.parent_tool_use_id))
+                            break;
+                        if (!claudeInputOwnsTurnSlot(session.activeInput))
+                            break;
+                        if (isActiveTurnInterrupted())
+                            break;
+                        applyToolResults(msg.message?.content);
+                        break;
+                    }
+                    case 'tool_progress': {
+                        // A long call would otherwise sit as a bare running row while the
+                        // typing signal quietly aged out.
+                        if (!isClaudeMainTurnMessage(msg.parent_tool_use_id))
+                            break;
+                        if (isActiveTurnInterrupted())
+                            break;
+                        applyTrailCommands(planClaudeToolProgress(session.turnActivity, {
+                            toolUseId: msg.tool_use_id,
+                            elapsedSeconds: msg.elapsed_time_seconds,
+                        }));
+                        refreshVisibleWorkSignal();
+                        break;
+                    }
                     case 'system': {
                         const subtype = msg.subtype;
                         if (subtype === 'session_state_changed') {
                             const state = msg.state;
+                            // The echo shares one field with the host's own reservation and
+                            // lags behind it: the 'idle' closing turn A arrives after A's
+                            // result, and the queue is drained INSIDE that result handler, so
+                            // turn B can already hold the slot. Applying it there would free a
+                            // slot that is taken and stop the typing signal B just started.
+                            if (!shouldApplyClaudeEchoedSessionState({
+                                echoed: state,
+                                dispatching: session.dispatchingInput !== null,
+                                hasPendingFinalDelivery: Boolean(session.pendingFinalDelivery),
+                            })) {
+                                console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+                                    + 'Ignoring a stale idle echo: the host still holds the turn slot');
+                                break;
+                            }
                             session.state.state = state;
                             if (state === 'running') {
                                 clearIdleResetTimer();
-                                if (!session.currentTurnId) {
-                                    session.currentTurnId = randomUUID();
-                                    session.currentTurnOpenedAt = Date.now();
-                                }
                                 session.state.contextUsage = undefined;
-                                session.pendingFinalText = null;
-                                session.toolInProgress = false;
-                                session.turnState = 'thinking';
+                                // Idempotent confirmation of a turn the host already opened —
+                                // re-seeding /streaming here would wipe the blocks and text the
+                                // turn has produced since. It still opens turns the host did not
+                                // start itself (an internal envelope, or a resumed session).
+                                if (shouldOpenClaudeTurnOnRunning(session.turnState)) {
+                                    openClaudeTurn(session);
+                                    seedTurnStreaming();
+                                }
+                                else if (session.turnState === 'waiting_input') {
+                                    // An approval was answered: the same turn is working again,
+                                    // so it leaves 'waiting_input' without being reopened.
+                                    session.turnState = 'thinking';
+                                    session.toolInProgress = false;
+                                }
                                 startVisibleWorkSignal();
                             }
                             else if (state === 'idle') {
@@ -1731,7 +2197,8 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                                 totalTokens: usage.totalTokens,
                                 maxTokens: usage.maxTokens,
                             };
-                            session.state.state = finalDelivered ? 'idle' : session.state.state;
+                            if (finalDelivered)
+                                releaseTurnSlotFor(completedInput);
                             writeState();
                         }
                         catch {
@@ -2318,8 +2785,12 @@ export async function main() {
     }
     async function resetRuntimeSession(session) {
         const conversationId = session.conversationId;
+        // `dispatchingInput` excludes the dispatch window: the slot is reserved but
+        // the SDK has nothing in flight, so there is nothing to interrupt. The
+        // dispatch itself bails on `session.closed` rather than pushing an input
+        // into a session that is being torn down.
         const sdkTurnActive = (session.state.state === 'running'
-            || session.state.state === 'requires_action') && !session.pendingFinalDelivery;
+            || session.state.state === 'requires_action') && !session.pendingFinalDelivery && !session.dispatchingInput;
         session.controlInterruptPending = sdkTurnActive;
         const interruptResult = await confirmClaudeInterrupt({
             active: sdkTurnActive,
@@ -2939,10 +3410,25 @@ export async function main() {
             }
             return;
         }
-        const isActive = session.state.state === 'running' || session.state.state === 'requires_action';
-        if (!isActive && (event.type !== 'stop_and_drop' || session.pendingInputs.length === 0)) {
+        const action = decideClaudeControlSignalAction({
+            type: event.type,
+            dispatching: session.dispatchingInput !== null,
+            sessionState: session.state.state,
+            queueDepth: session.pendingInputs.length,
+        });
+        if (action === 'defer') {
+            // Reserved but not yet dispatched: there is nothing in the SDK to stop
+            // YET. Consuming the signal here would make a Stop pressed in the
+            // accept/artifact window do nothing while the turn it was aimed at ran to
+            // completion; the poller revisits this a cycle later instead.
+            console.error(`[canon-host] [${convoId.slice(0, 8)}] `
+                + `${event.type} signal arrived during turn dispatch; retrying it`);
+            return { defer: true };
+        }
+        if (action === 'consume') {
             return; // Nothing to interrupt — consume the stale signal
         }
+        const isActive = isClaudeTurnSlotReserved(session.state.state);
         console.error(`[canon-host] [${convoId.slice(0, 8)}] ${event.type} signal`);
         const sdkTurnActive = isActive && !session.pendingFinalDelivery;
         session.controlInterruptPending = sdkTurnActive;