@stigmer/runner 3.1.2 → 3.1.4

package/dist/activities/execute-cursor/index.js

@@ -30,20 +30,19 @@ import { create, clone } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
-import { ExecutionControlSignal, ExecutionPhase, FileChangeSetStatus, InteractionMode, MessageType, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ExecutionPhase, FileChangeSetStatus, InteractionMode, MessageType, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { StigmerClient } from "../../client/stigmer-client.js";
 import { resolveAgent } from "./session-lifecycle.js";
 import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
 import { determineCursorMode, isCloudMode } from "./cursor-mode.js";
-import { MessageAccumulator, reconcileDeniedToolCalls, clearProvisionalPostDenialNarration, cancelInProgressSubAgentProtos, collapseRedundantToolCallTwins } from "./message-translator.js";
+import { MessageAccumulator, cancelInProgressSubAgentProtos, collapseRedundantToolCallTwins } from "./message-translator.js";
 import { utcTimestamp, persistStatus, reportSetupProgress, slimStatus } from "../../shared/status.js";
-import { collectSubAgentToolCallIds, withholdSecretContentFromMessages } from "../../shared/tool-row.js";
-import { startStallWatchdog, StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
+import { withholdSecretContentFromMessages } from "../../shared/tool-row.js";
+import { StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
 import { resolveUsableArtifactStorage, loadArtifactStorageConfig } from "../../shared/artifact-storage.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
-import { shouldPersistStreamingStatus } from "./persist-decision.js";
 import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
 import { resolveMcpServers, validateMcpServerEnv } from "./mcp-resolver.js";
@@ -61,11 +60,13 @@ import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
 import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import { acquireWorkspaceLock, WorkspaceLockCancelledError, WorkspaceLockTimeoutError, } from "../../shared/workspace/workspace-lock.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
-import { buildApprovalState, buildApprovalGrants, emitCursorGrantReceipts, primaryToken, readDenialLedger, reconstructAdjudicatedApprovals, watchDenialLedger } from "./approval-state.js";
-import { deriveTurnCommandProvenance } from "./command-provenance.js";
+import { buildApprovalState, buildApprovalGrants, emitCursorGrantReceipts, reconstructAdjudicatedApprovals, watchDenialLedger } from "./approval-state.js";
 import { applyApprovedWholeFileWrites, excludeAppliedFromGrants } from "./exact-apply.js";
 import { isGitWorkTree } from "../../shared/filereview/git-substrate.js";
-import { captureBaselineToLedger, captureTurnToLedger, applyCaptureDecisions, deriveCaptureMode, } from "./capture-flow.js";
+import { captureBaselineToLedger, buildCursorProgressSubstrate, applyCaptureDecisions, deriveCaptureMode, } from "./capture-flow.js";
+import { runTurnBoundary } from "./turn-boundary.js";
+import { consumeCursorTurnStream, makeCursorTurnOnDelta, newTurnStreamState, } from "./turn-stream.js";
+import { newProgressCaptureState, } from "../../shared/filereview/progress.js";
 import { deriveExecutionFingerprintKey } from "../../shared/approval-fingerprint.js";
 import { getRunnerHitlMasterSecret } from "../../shared/fingerprint-secret.js";
 import { provisionCursorWorkspace } from "./workspace-provision.js";
@@ -82,11 +83,6 @@ import { createAgent, createCloudAgent } from "./session-lifecycle.js";
 import { setMaxListeners } from "node:events";
 import { startHeartbeat } from "../../shared/heartbeat.js";
 import { getShutdownSignalForQueue } from "../../runner-manager.js";
-// How long Phase 12 waits for the first-denial-stop's run.cancel() to settle
-// before reading the final denial ledger and capturing the turn's tree. Long
-// enough for the SDK's normal teardown, short enough that a wedged cancel
-// cannot noticeably delay the approval pause the user is already waiting on.
-const FIRST_DENIAL_CANCEL_TIMEOUT_MS = 5_000;
 /**
  * Creates the activity functions bound to the runner config.
  * Returned object is passed to Temporal Worker.create({ activities }).
@@ -159,40 +155,30 @@ turnSeq) {
     };
     let sessionId;
     let session;
-    let pauseDetected = false;
+    // Single owner for every flag the turn's stream produces (pause, stall,
+    // first-denial, platform-stop, event count, the stall watchdog, …). Created
+    // once here — before the fs denial-watcher, the SDK onDelta, the stall
+    // watchdog, and the stream loop are wired — so all four producers plus the
+    // epilogue and the outer catch/finally share ONE source of truth. The primary
+    // turn and both recovery retries drive the same stream code against this
+    // object (see turn-stream.ts for per-field ownership).
+    const turnState = newTurnStreamState();
+    // NOT part of turnState: derived post-loop from the periodic heartbeat +
+    // shutdown signal (a runner-manager shutdown, not a stream event), and read by
+    // the epilogue + outer catch. Kept as a plain let alongside the stream flags.
     let workerShutdownDetected = false;
-    // Set by the stall watchdog when the SDK stream makes no progress for
-    // config.cursorStreamStallTimeoutMs. stallError carries the recognizable
-    // message surfaced to the user; both feed the Phase 11a stall branch.
-    let stallDetected = false;
-    let stallError;
-    // Set the moment the preToolUse hook records its first denial in the ledger.
-    // We then stop consuming the stream and cancel the run so the model never
-    // reacts to Cursor's tool-failure surface (narrate defeat, attempt a second
-    // gated tool) — converging the Cursor harness toward the native harness, which
-    // pauses BEFORE the model sees a denial. Phase 12 reconciles the denied tool
-    // calls into WAITING_FOR_APPROVAL exactly as after a natural stream end.
-    let firstDenialDetected = false;
-    // Flipped by the denial-ledger fs watcher the instant the hook writes a
-    // denial, so the NEXT stream event of ANY type triggers the ledger read —
-    // instead of waiting for the next tool_call event, during which the model's
-    // full post-denial reaction (thinking, narration, a workaround tool) would
-    // stream and persist (observed in production: aex_01kwj07f7g23c3wp9sn8496z5g).
-    // The tool_call-event read below remains the backstop where fs.watch is
-    // unreliable.
-    let denialLedgerDirty = false;
     let stopDenialWatcher;
-    // The in-flight run.cancel() started by the first-denial stop. Awaited
-    // (timeboxed) before Phase 12 so the agent process has actually stopped
-    // before the final ledger read and the turn-boundary tree capture — closing
-    // the race where a post-denial workaround's ledger entry lands after the
-    // read (it would then never be collapsed) or a late tool mutates the tree
-    // mid-capture.
-    let denialCancelSettled;
     let periodicHeartbeat;
-    // Progress-based stall watchdog (see ../../shared/stall-watchdog.ts). Stopped
-    // in the finally on every exit path; complements the liveness heartbeat.
-    let stallWatchdog;
+    // Ends the OTel turn span + records turn metrics with the FINAL token snapshot.
+    // Hoisted and invoked from the finally so the span is closed exactly once on
+    // EVERY exit path — a happy completion, an approval pause, an early return, a
+    // throw, or a recovery retry (whose tokens accrue AFTER the primary stream
+    // ends). Ending it inline in the epilogue leaked the span on every non-happy
+    // path and excluded retry tokens/duration. Assigned when the span is created
+    // (once usageAccumulator exists); undefined — a no-op — before then (e.g. a
+    // pure-reconcile resume that returns before the agent runs) or when OTel is
+    // off. Idempotent: safe to call more than once.
+    let finishTurnTelemetry;
     // Session HITL directory (runner-owned, outside the workspace) where the hook
     // script, approval-state file, and denial ledger live. Set once the gate is
     // installed; the WAITING_FOR_APPROVAL path reads the denial ledger from here.
@@ -254,6 +240,9 @@ turnSeq) {
         // Pre-turn baseline tree, pinned before the agent runs (capture mode only)
         // so the turn-end capture diffs against it and the tree restores exactly.
         let baselineTree;
+        // Per-turn state for mid-run live capture (DD-32): the last progress tree sha
+        // (short-circuit) + last capture time (floor), threaded across persists.
+        const progressState = newProgressCaptureState();
         // Deterministic id of the change set this turn may produce:
         // `${executionId}:${turnSeq}`. Minted from the workflow-threaded turn index
         // so it is stable across a Temporal retry (idempotent ledger authoring) and
@@ -586,7 +575,21 @@ turnSeq) {
         // reset may flip the flag once before the run starts; the loop's read then
         // sees an empty ledger and clears it — harmless by construction.
         stopDenialWatcher = watchDenialLedger(hitlDir, () => {
-            denialLedgerDirty = true;
+            turnState.denialLedgerDirty = true;
+        });
+        // Mid-run live capture (DD-32 / DD-33): choose the progress substrate for this
+        // turn's workspace shape ONCE (git / non-git CAS / hybrid). It owns its own
+        // short-circuit cache across the loop's persists; the floor lives in
+        // progressState. Undefined outside capture mode — writes are deny-gated and
+        // nothing is captured.
+        const progressSubstrate = buildCursorProgressSubstrate({
+            captureMode,
+            gitWorkspace,
+            workspaceRoot: primaryWorkspaceDir,
+            baselineTree,
+            executionId,
+            hitlDir,
+            storage: artifactStorage,
         });
         // Phase 5d: Ensure model pricing registry is populated before validation
         await ensurePricingLoaded();
@@ -702,25 +705,62 @@ turnSeq) {
         // Phase 10b: Initialize usage accumulator for runner-side token tracking
         await ensurePricingLoaded();
         const usageAccumulator = new UsageAccumulator(validatedModel);
-        // Phase 10c: Start OTel turn span (coarse-grained — wraps entire agent.send + stream)
+        // Phase 10c: Start OTel turn span. Coarse-grained — spans the whole turn
+        // (agent.send + stream + any recovery retry + the turn boundary), ended once
+        // from the finally via finishTurnTelemetry with the final token snapshot.
         const { startCursorTurnSpan } = await import("../../otel.js");
         const turnSpan = await startCursorTurnSpan({
             model: validatedModel,
             mode: agentMode,
             sessionId: sessionId ?? "",
         });
+        // Bind the telemetry-finish closure now that the span + usage accumulator
+        // exist. Reads usageAccumulator at CALL time (in the finally), so it captures
+        // tokens from any recovery retry that ran after the primary stream. Guarded
+        // so a second call (finally after an inline path already finished it) is a
+        // no-op. Metrics failures are swallowed — OTel is optional.
+        let turnTelemetryFinished = false;
+        finishTurnTelemetry = async () => {
+            if (turnTelemetryFinished)
+                return;
+            turnTelemetryFinished = true;
+            const usage = usageAccumulator.snapshot();
+            turnSpan.setTokens(Number(usage.inputTokens), Number(usage.outputTokens));
+            turnSpan.end();
+            try {
+                const { recordTurnMetrics } = await import("../../otel.js");
+                const durationMs = Date.now() - (status.startedAt ? new Date(status.startedAt).getTime() : Date.now());
+                await recordTurnMetrics({
+                    durationMs,
+                    inputTokens: Number(usage.inputTokens),
+                    outputTokens: Number(usage.outputTokens),
+                    model: validatedModel,
+                    mode: agentMode,
+                });
+            }
+            catch {
+                // Metrics not initialized — silently skip.
+            }
+        };
         // Phase 11: Send message and stream events
         status.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
         const deltaEnricher = new DeltaEnricher();
         const todoTracker = new TodoTracker(status.todos);
         const eventRecorder = createCursorEventRecorder(executionId);
-        let platformStopSignaled = false;
-        let firstTurnAttributionLogged = false;
-        let streamErrorMessage;
+        // The two recovery retries (poisoned-handle / transport-timeout) below run at
+        // most once per turn; this guard is the latch.
         let alreadyRetriedWithFreshAgent = false;
-        // Most recent tool name observed on the stream, used only to enrich the
-        // stall message ("last tool: …") so a wedged turn names the likely culprit.
-        let lastToolName;
+        // The shared onDelta only needs the usage/enricher/heartbeat/state subset,
+        // and it is wired at SEND time — before the accumulator exists — so it takes
+        // the narrow deps. The primary send and both retry sends reuse this object.
+        const onDeltaDeps = {
+            usageAccumulator,
+            deltaEnricher,
+            heartbeat,
+            promptEstimatedTokens,
+            executionId,
+            state: turnState,
+        };
         // Periodic heartbeat keeps Temporal informed during silent SDK operations
         // (e.g. long tool calls, MCP requests, model thinking). Without this,
         // the 2-minute heartbeat timeout can cancel the activity and mislabel
@@ -746,54 +786,11 @@ turnSeq) {
             // Fallback: if the Temporal signal doesn't support setMaxListeners
             // (e.g. older SDK), the warning is harmless — ignore.
         }
+        // The stall watchdog is armed inside consumeCursorTurnStream (it needs the
+        // run to cancel), stored on turnState.stallWatchdog so this shared onDelta can
+        // reset it and the activity's finally can stop it as a backstop.
         const run = await resolution.agent.send(effectivePrompt, {
-            onDelta: ({ update }) => {
-                // Reset the stall timer on the delta channel too: a long model
-                // generation emits token deltas but few discrete stream events, so
-                // resetting only in the stream loop would false-positive a stall.
-                stallWatchdog?.recordActivity();
-                if (update.type === "turn-ended" && update.usage) {
-                    usageAccumulator.addTurn(update.usage);
-                    if (!firstTurnAttributionLogged) {
-                        firstTurnAttributionLogged = true;
-                        const sdkInputTokens = update.usage.inputTokens ?? 0;
-                        const cursorOverhead = Math.max(0, sdkInputTokens - promptEstimatedTokens);
-                        console.log(`ExecuteCursor context attribution (first turn): execution=${executionId}, ` +
-                            `sdkInputTokens=${sdkInputTokens}, stigmerPreamble=${promptEstimatedTokens}, ` +
-                            `cursorOverhead=${cursorOverhead} (estimated)`);
-                    }
-                }
-                deltaEnricher.processDelta(update);
-                try {
-                    heartbeat();
-                }
-                catch (hbErr) {
-                    if (hbErr instanceof CancelledFailure) {
-                        pauseDetected = true;
-                        return;
-                    }
-                    throw hbErr;
-                }
-            },
-        });
-        // Arm the stall watchdog now that the run exists. The periodic heartbeat
-        // above proves the process is alive, not that the agent is progressing: if
-        // the stream wedges (a tool call or model connection that never returns),
-        // no event/delta arrives, Phase 12 below is never reached, and the
-        // execution hangs at EXECUTION_IN_PROGRESS forever. On stall we end the run
-        // cleanly via the SDK's run.cancel() (guarded by supports("cancel")), which
-        // unblocks the for-await; the stallDetected branch in Phase 11a then
-        // reports EXECUTION_FAILED with a recognizable, actionable message.
-        stallWatchdog = startStallWatchdog(config.cursorStreamStallTimeoutMs, (idleMs) => {
-            stallDetected = true;
-            stallError = new StallTimeoutError(idleMs, lastToolName ? `last tool: ${lastToolName}` : undefined);
-            console.warn(`ExecuteCursor stall detected: execution=${executionId}, idleMs=${idleMs}, lastTool=${lastToolName ?? "none"}`);
-            if (run.supports?.("cancel")) {
-                void run.cancel().catch((cancelErr) => {
-                    console.warn(`ExecuteCursor run.cancel() after stall failed (non-fatal): execution=${executionId}, ` +
-                        `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`);
-                });
-            }
+            onDelta: makeCursorTurnOnDelta(onDeltaDeps),
         });
         // Everything at an index >= this was produced by THIS turn's stream — the
         // positional turn boundary the approved-command provenance (DD-28) scopes
@@ -809,385 +806,243 @@ turnSeq) {
         // flush; high-frequency token deltas ride this scheduler's time cadence
         // (env-tunable via STREAMING_* — see loadStreamingConfig).
         const scheduler = new StreamingUpdateScheduler(loadStreamingConfig());
-        let eventCount = 0;
-        try {
-            for await (const event of run.stream()) {
-                if (pauseDetected || Context.current().cancellationSignal.aborted) {
-                    pauseDetected = true;
-                    break;
-                }
-                if (stallDetected)
-                    break;
-                // Progress: reset the stall timer on every stream event.
-                stallWatchdog.recordActivity();
-                if (event.type === "tool_call" && typeof event.name === "string") {
-                    lastToolName = event.name;
-                }
-                eventRecorder?.record(event, eventCount);
-                accumulator.processEvent(event);
-                todoTracker.processEvent(event);
-                if (event.type === "tool_call" && event.name === "task") {
-                    accumulator.trackSubAgentExecution(event);
-                }
-                // First-denial stop (HITL clean pause). In CAPTURE mode this fires only for
-                // an IRREVERSIBLE tool the hook still gates (shell, MCP, or a gitignored
-                // write/delete) — file edits flow freely and are captured at the turn
-                // boundary, so they never enter the ledger. In the deny-gate FALLBACK
-                // (non-git workspace) it fires for every gated file edit too. Either way:
-                // the preToolUse hook appends to the denial ledger the instant it gates a
-                // tool — before Cursor surfaces the failure to the model — and the fs
-                // watcher flips denialLedgerDirty the moment that write lands. Confirming
-                // the flag with a read on the very next event (of ANY type — thinking
-                // deltas arrive within milliseconds) ends the turn before the model's
-                // reaction can persist: waiting for the next tool_call event let the full
-                // post-denial reaction (thinking, narration, a workaround shell) stream
-                // and persist live (production case aex_01kwj07f7g23c3wp9sn8496z5g). The
-                // tool_call-event read stays as the backstop for platforms where fs.watch
-                // is unreliable; the current event was already accumulated above, so the
-                // anchor's own row is always present for the Phase 12 gate overlay. This
-                // mirrors the native harness's pause-before-react semantics; Phase 12
-                // reconciles the denied calls and its trim remains the last-resort
-                // backstop for anything that persisted before the stop.
-                if (!firstDenialDetected && hitlDir && (denialLedgerDirty || event.type === "tool_call")) {
-                    denialLedgerDirty = false;
-                    const denials = await readDenialLedger(hitlDir);
-                    if (denials.length > 0) {
-                        firstDenialDetected = true;
-                        console.log(`ExecuteCursor first denial detected (${denials.length} ledger ` +
-                            `entr${denials.length === 1 ? "y" : "ies"}); stopping turn to pause ` +
-                            `cleanly for approval: execution=${executionId}`);
-                        if (run.supports?.("cancel")) {
-                            // Kept (not fire-and-forget): awaited timeboxed before Phase 12 so
-                            // the ledger read and tree capture see a stopped agent.
-                            denialCancelSettled = run.cancel().then(() => { }, (cancelErr) => {
-                                console.warn(`ExecuteCursor run.cancel() after first denial failed (non-fatal): ` +
-                                    `execution=${executionId}, ` +
-                                    `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`);
-                            });
-                        }
-                        break;
-                    }
-                }
-                deltaEnricher.applyEnrichments(status.messages);
-                eventCount++;
-                if (event.type === "status") {
-                    console.log(`ExecuteCursor stream status: execution=${executionId}, status=${JSON.stringify(event)}`);
-                    const statusEvent = event;
-                    if (statusEvent.status === "ERROR" && statusEvent.message) {
-                        streamErrorMessage = statusEvent.message;
-                    }
-                }
-                const shouldPersist = shouldPersistStreamingStatus({
-                    deltaEnricherDirty: deltaEnricher.isDirty,
-                    todosDirty: todoTracker.isDirty,
-                    contentDirty: accumulator.isDirty,
-                }, scheduler, eventCount);
-                if (usageAccumulator.hasTurns) {
-                    status.streamingUsage = create(StreamingUsageSummarySchema, usageAccumulator.snapshot());
-                }
-                if (shouldPersist) {
-                    // Sync sub-agent executions into status before every persist so the
-                    // live UI reflects delegation (including the IN_PROGRESS state) while
-                    // the parent is still running — matching the native harness, which
-                    // calls syncSubAgentExecutions() on each persist. Without this, the
-                    // accumulator tracked sub-agents in memory but they only reached the
-                    // status (and the subscriber stream) after the loop ended.
-                    status.subAgentExecutions = accumulator.subAgentExecutions;
-                    const signal = await persist(status);
-                    deltaEnricher.markPersisted();
-                    todoTracker.markPersisted();
-                    accumulator.markPersisted();
-                    scheduler.markUpdateSent(eventCount);
-                    heartbeat();
-                    if (signal === ExecutionControlSignal.STOP) {
-                        platformStopSignaled = true;
-                        console.warn(`ExecuteCursor platform stop signal received: execution=${executionId}`);
-                    }
-                }
-                if (platformStopSignaled) {
-                    console.log(`ExecuteCursor stopping stream due to platform stop signal: execution=${executionId}`);
-                    break;
-                }
-            }
-        }
-        catch (streamErr) {
-            // run.cancel() — from the stall watchdog or the first-denial stop — can
-            // make the stream iterator reject as it tears down; that is the expected
-            // teardown for both, so swallow it and fall through (stallDetected ->
-            // Phase 11a; firstDenialDetected -> Phase 12). Anything else is a genuine
-            // stream failure — rethrow it to the outer error handler.
-            if (!stallDetected && !firstDenialDetected)
-                throw streamErr;
-            console.warn(`ExecuteCursor stream ended via cancel: execution=${executionId}, ` +
-                `stall=${stallDetected}, firstDenial=${firstDenialDetected}`);
-        }
+        // Full deps for the shared stream loop — the collaborators + the injected
+        // heartbeat/cancellation (so the loop is testable, mirroring the deep-agent
+        // streamExecution seam), all keyed off the single turnState. Consumed by the
+        // primary stream here and by both recovery retries below.
+        const streamDeps = {
+            ...onDeltaDeps,
+            status,
+            accumulator,
+            todoTracker,
+            eventRecorder,
+            scheduler,
+            progressSubstrate,
+            progressState,
+            changeSetId,
+            hitlDir,
+            stallTimeoutMs: config.cursorStreamStallTimeoutMs,
+            persist,
+            isCancelled: () => Context.current().cancellationSignal.aborted,
+        };
+        // Primary stream. consumeCursorTurnStream owns the per-event loop (transcript,
+        // todos, sub-agent tracking, live persist, DD-32/DD-33 mid-run progress, the
+        // first-denial early stop, and the stall watchdog) and reports why it ended;
+        // resolvePreBoundaryTerminal below maps that to a terminal outcome. The two
+        // recovery retries drive the identical loop, so they inherit every one of
+        // these behaviors instead of the old bare loop that dropped them.
+        await consumeCursorTurnStream(run, streamDeps);
         periodicHeartbeat.stop();
-        stallWatchdog.stop();
-        // Check both the heartbeat flag AND the shutdown signal directly.
-        // Race condition: the heartbeat timer may detect Temporal's CancelledFailure
-        // (from worker.shutdown()) before the AbortSignal microtask propagates,
-        // causing it to set `cancelled` instead of `workerShutdown`. The direct
-        // signal check catches this case.
+        // Worker-shutdown vs. user-pause disambiguation. Primary-only: the periodic
+        // heartbeat is stopped here, before any recovery retry runs, so a retry
+        // classifies a shutdown from the shutdown signal directly (in
+        // resolvePreBoundaryTerminal). The heartbeat timer may set `cancelled` before
+        // the AbortSignal microtask propagates; the direct signal check catches that.
         const isShutdown = periodicHeartbeat.workerShutdown || (shutdownSignal?.aborted ?? false);
         if (isShutdown) {
-            pauseDetected = false;
+            turnState.pauseDetected = false;
         }
         else if (periodicHeartbeat.cancelled) {
-            pauseDetected = true;
+            turnState.pauseDetected = true;
         }
         workerShutdownDetected = isShutdown;
-        accumulator.finalize();
-        deltaEnricher.finalize(status.messages);
-        // A pause / cancel / worker shutdown aborts the Cursor SDK run, so any
-        // sub-agent the parent had delegated is no longer executing. Mark it
-        // CANCELLED rather than leaving a permanent IN_PROGRESS "zombie" in the
-        // final snapshot (parity with the native harness's cancelSubAgents()).
-        if (pauseDetected || workerShutdownDetected || stallDetected || Context.current().cancellationSignal.aborted) {
-            accumulator.cancelInProgressSubAgents();
-        }
-        status.subAgentExecutions = accumulator.subAgentExecutions;
-        await eventRecorder?.flush();
-        if (usageAccumulator.hasTurns) {
-            status.streamingUsage = create(StreamingUsageSummarySchema, usageAccumulator.snapshot());
-        }
-        console.log(`ExecuteCursor stream ended: execution=${executionId}, events=${eventCount}, messages=${status.messages.length}, subAgents=${status.subAgentExecutions.length}`);
-        // Persist immediately after finalize so the UI sees correct tool
-        // call statuses before run.wait() / structured output extraction.
-        // This is unconditional (not throttled) because finalize is a
-        // once-per-execution correctness boundary.
-        await persist(status);
-        heartbeat();
-        // End OTel turn span with accumulated token usage
-        const usageSnapshot = usageAccumulator.snapshot();
-        turnSpan.setTokens(Number(usageSnapshot.inputTokens), Number(usageSnapshot.outputTokens));
-        turnSpan.end();
-        // Record cursor turn metrics (duration, tokens)
-        try {
-            const { recordTurnMetrics } = await import("../../otel.js");
-            const turnDurationMs = Date.now() - (status.startedAt ? new Date(status.startedAt).getTime() : Date.now());
-            await recordTurnMetrics({
-                durationMs: turnDurationMs,
-                inputTokens: Number(usageSnapshot.inputTokens),
-                outputTokens: Number(usageSnapshot.outputTokens),
-                model: validatedModel,
-                mode: agentMode,
-            });
-        }
-        catch {
-            // Metrics not initialized — silently skip.
-        }
-        // Phase 11a: Handle stall, worker shutdown, pause, or infrastructure cancellation.
-        // Stall: the watchdog cancelled a turn that made no progress for longer
-        // than config.cursorStreamStallTimeoutMs (a wedged tool call or a dead
-        // model connection). The keep-alive heartbeat proves liveness, so Temporal
-        // never reaps this on its own — this branch is the only clean exit. We
-        // RETURN (not throw): re-running the identical prompt via Temporal retry
-        // would very likely wedge again. accumulator.finalize() above already
-        // cleared isStreaming, so the UI spinners stop.
-        if (stallDetected) {
-            const err = stallError ?? new StallTimeoutError(config.cursorStreamStallTimeoutMs);
-            status.phase = ExecutionPhase.EXECUTION_FAILED;
-            status.error = formatStallFailure(err);
-            status.completedAt = utcTimestamp();
-            status.messages.push(create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: `Execution failed: the agent made no progress for too long and was stopped (${err.message}). You can retry or resume.`,
-                timestamp: utcTimestamp(),
-            }));
-            await persist(status);
-            console.warn(`ExecuteCursor stalled: execution=${executionId}, events=${eventCount}, error=${status.error}`);
-            return slimStatus(status);
-        }
-        // Worker shutdown: the runner-manager aborted the shutdown signal before
-        // calling worker.shutdown(). This is NOT a user-initiated pause — it's
-        // an infrastructure event (e.g., premature removal from UI race).
-        if (workerShutdownDetected) {
-            status.phase = ExecutionPhase.EXECUTION_FAILED;
-            status.error = "Execution interrupted: runner worker was shut down. Retry or resume.";
-            status.completedAt = utcTimestamp();
-            status.messages.push(create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: "Execution interrupted: the runner worker was shut down while the agent was still running. You can retry or resume.",
-                timestamp: utcTimestamp(),
-            }));
-            await persist(status);
-            console.log(`ExecuteCursor interrupted (worker shutdown): execution=${executionId}, events=${eventCount}`);
-            throw new CancelledFailure("Activity cancelled (worker shutdown, not user pause)");
-        }
-        // pauseDetected is only true if a heartbeat() call threw CancelledFailure,
-        // confirming the orchestrator explicitly requested a pause.
-        if (pauseDetected) {
-            status.phase = ExecutionPhase.EXECUTION_PAUSED;
-            status.messages.push(create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: "Execution paused by user. Use resume to continue.",
-                timestamp: utcTimestamp(),
-            }));
-            await persist(status);
-            console.log(`ExecuteCursor paused: execution=${executionId}, events=${eventCount}`);
-            throw new CancelledFailure("Activity paused by orchestrator");
-        }
-        // If cancellation arrived without pauseDetected (e.g. heartbeat timeout
-        // that slipped past the periodic heartbeat, or worker shutdown), report
-        // as failed rather than misleadingly labeling it as user-paused.
-        if (Context.current().cancellationSignal.aborted) {
-            status.phase = ExecutionPhase.EXECUTION_FAILED;
-            status.error = "Execution interrupted: agent was unresponsive (heartbeat timeout). Retry or resume.";
-            status.completedAt = utcTimestamp();
-            status.messages.push(create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: "Execution interrupted: the agent was unresponsive for too long. You can retry or resume.",
-                timestamp: utcTimestamp(),
-            }));
-            await persist(status);
-            console.log(`ExecuteCursor interrupted (infrastructure cancel): execution=${executionId}, events=${eventCount}`);
-            throw new CancelledFailure("Activity cancelled (heartbeat timeout, not user pause)");
-        }
-        // Phase 11b: Handle platform stop signal early exit
-        if (platformStopSignaled) {
-            status.phase = ExecutionPhase.EXECUTION_COMPLETED;
-            status.completedAt = utcTimestamp();
-            status.messages.push(create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: "Execution stopped by the platform.",
-                timestamp: utcTimestamp(),
-            }));
+        // Post-stream finalize, shared by the primary turn and both recovery retries:
+        // finalize the transcript + streaming flags, mark any in-flight sub-agent
+        // CANCELLED on an aborted turn, snapshot usage, flush the recorder, and
+        // persist so the UI sees the settled rows. The unified loop applies delta
+        // enrichments per-iteration, so — unlike the old bare retry path — no
+        // compensating applyEnrichments() is needed here.
+        const finalizeStreamPhase = async () => {
+            accumulator.finalize();
+            deltaEnricher.finalize(status.messages);
+            // A pause / cancel / worker shutdown aborts the Cursor SDK run, so any
+            // sub-agent the parent had delegated is no longer executing. Mark it
+            // CANCELLED rather than leaving a permanent IN_PROGRESS "zombie" in the
+            // final snapshot (parity with the native harness's cancelSubAgents()).
+            if (turnState.pauseDetected ||
+                workerShutdownDetected ||
+                turnState.stallDetected ||
+                Context.current().cancellationSignal.aborted) {
+                accumulator.cancelInProgressSubAgents();
+            }
+            status.subAgentExecutions = accumulator.subAgentExecutions;
+            await eventRecorder?.flush();
+            if (usageAccumulator.hasTurns) {
+                status.streamingUsage = create(StreamingUsageSummarySchema, usageAccumulator.snapshot());
+            }
+            console.log(`ExecuteCursor stream ended: execution=${executionId}, events=${turnState.eventCount}, messages=${status.messages.length}, subAgents=${status.subAgentExecutions.length}`);
+            // Persist immediately after finalize so the UI sees correct tool-call
+            // statuses before the boundary / run.wait() / structured-output extraction.
             await persist(status);
-            try {
-                resolution.agent.close();
+            heartbeat();
+        };
+        const resolvePreBoundaryTerminal = async () => {
+            // Stall: the watchdog cancelled a turn that made no progress. RETURN (not
+            // throw): re-running the identical prompt via Temporal retry would very
+            // likely wedge again.
+            if (turnState.stallDetected) {
+                const err = turnState.stallError ?? new StallTimeoutError(config.cursorStreamStallTimeoutMs);
+                status.phase = ExecutionPhase.EXECUTION_FAILED;
+                status.error = formatStallFailure(err);
+                status.completedAt = utcTimestamp();
+                status.messages.push(create(AgentMessageSchema, {
+                    type: MessageType.MESSAGE_SYSTEM,
+                    content: `Execution failed: the agent made no progress for too long and was stopped (${err.message}). You can retry or resume.`,
+                    timestamp: utcTimestamp(),
+                }));
+                await persist(status);
+                console.warn(`ExecuteCursor stalled: execution=${executionId}, events=${turnState.eventCount}, error=${status.error}`);
+                return { kind: "return" };
             }
-            catch { /* best effort */ }
-            console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
-            return slimStatus(status);
-        }
-        // Phase 12: Surface tools the preToolUse hook gated (HITL).
-        //
-        // The hook records each denial to the ledger; we mark the corresponding tool
-        // calls WAITING_APPROVAL. The backend projects pending_approvals from that
-        // tool-call status (PendingApprovalComputer), so — exactly like the native
-        // harness — the approval surface is driven entirely by tool-call status. We
-        // deliberately do NOT set status.pendingApprovals here: any value would be
-        // discarded by the backend's recompute on the next updateStatus.
-        //
-        // Before reading the ledger, wait (timeboxed) for the first-denial-stop's
-        // run.cancel() to settle. run.cancel() races the SDK's auto-execution: until
-        // it lands, the agent process may still attempt a post-denial workaround
-        // whose hook denial would land AFTER a premature ledger read — the row then
-        // never collapses and renders as RUNNING forever (production case
-        // aex_01kwj07f7g23c3wp9sn8496z5g) — or a late tool could mutate the tree
-        // mid-capture. The timebox keeps a wedged cancel from hanging the pause;
-        // the Phase 12 trims below remain the backstop for that degraded case.
-        if (firstDenialDetected && denialCancelSettled) {
-            await Promise.race([
-                denialCancelSettled,
-                new Promise((resolve) => {
-                    const timer = setTimeout(resolve, FIRST_DENIAL_CANCEL_TIMEOUT_MS);
-                    timer.unref();
-                }),
-            ]);
-        }
-        const deniedLedger = await readDenialLedger(hitlDir ?? "");
-        // Capture mode: author the net change set to the file_review ledger as the
-        // CANDIDATE_CAPTURED event (projected server-side to a file_change_set
-        // AWAITING_REVIEW — the single review surface). The runner-owned gate files
-        // are excluded from the capture. The agent's edits are LEFT applied on the
-        // working tree (Cursor parity — the user reviews the real change; nothing is
-        // committed and the next turn is blocked until approval, and a reject snaps
-        // each file back on resume). Runs BEFORE the denial reconcile so a denied
-        // (gitignored) write stays on the deny-gate path while every flowed edit is
-        // captured to the ledger.
-        let capturedChangeCount = 0;
-        // `baselineTree !== undefined` means a baseline was authored this turn — the
-        // git tree sha for a git workspace, or "" (empty, but authored) for a non-git
-        // one. A plain truthiness check would wrongly skip the non-git capture.
-        if (captureMode && baselineTree !== undefined && primaryWorkspaceDir) {
-            const deniedTokens = new Set(deniedLedger.map((e) => e.token));
-            // Approved-command turn facts (DD-28): when every mutation-capable call
-            // this turn was a consented shell command, attach the provenance so the
-            // backend can verify the cited consent rows and auto-keep the set instead
-            // of arming a second gate. Fail-closed: any non-qualifying turn attaches
-            // nothing and reviews manually exactly as before.
-            const commandProvenance = deriveTurnCommandProvenance({
-                messages: status.messages,
-                turnStartIndex: turnStartMessageIndex,
-                deniedTokens,
-                grantTokenToConsentId: new Map((approvalGrants ?? []).map((g) => [
-                    primaryToken(g.key, g.salient, g.contentDigest),
-                    g.sourceToolCallId,
-                ])),
-                globalBypass,
-            });
-            if (commandProvenance) {
-                console.log(`ExecuteCursor capture: turn qualifies for approved-command auto-keep ` +
-                    `(consent rows: ${commandProvenance.consentToolCallIds.join(",") || "(auto_approve_all)"}); ` +
-                    `attaching provenance to candidate (execution=${executionId})`);
+            // Worker shutdown: the runner-manager aborted the shutdown signal. NOT a
+            // user pause. Checked via the shutdown signal directly so a retry (whose
+            // periodic heartbeat is already stopped) still classifies it correctly.
+            if (workerShutdownDetected || (shutdownSignal?.aborted ?? false)) {
+                status.phase = ExecutionPhase.EXECUTION_FAILED;
+                status.error = "Execution interrupted: runner worker was shut down. Retry or resume.";
+                status.completedAt = utcTimestamp();
+                status.messages.push(create(AgentMessageSchema, {
+                    type: MessageType.MESSAGE_SYSTEM,
+                    content: "Execution interrupted: the runner worker was shut down while the agent was still running. You can retry or resume.",
+                    timestamp: utcTimestamp(),
+                }));
+                await persist(status);
+                console.log(`ExecuteCursor interrupted (worker shutdown): execution=${executionId}, events=${turnState.eventCount}`);
+                return { kind: "throw", message: "Activity cancelled (worker shutdown, not user pause)" };
             }
-            const captured = await captureTurnToLedger({
-                status,
-                gitRoot: primaryWorkspaceDir,
-                executionId,
-                changeSetId,
-                baselineTree,
-                messages: status.messages,
-                deniedTokens,
-                commandProvenance,
-                // Scope sub-agent row stamping to this turn: the seeded prior sub-agents
-                // (cloned in on resume) are the "before this turn" rows to skip.
-                priorSubAgentToolCallIds: collectSubAgentToolCallIds(seededSubAgents),
-                // The CAS half: read the sidecar the hook staged this turn and compose it
-                // into the change set. hitlDir + storage are present when captureIgnored
-                // was on (a git tree's gitignored writes, or ALL writes in a non-git
-                // workspace). In a git tree this composes with the git diff (HYBRID); in a
-                // non-git workspace it IS the whole change set (CAS-only).
-                hitlDir,
-                storage: artifactStorage,
-                gitWorkspace,
-            });
-            capturedChangeCount = captured.length;
-            if (capturedChangeCount > 0) {
-                console.log(`ExecuteCursor capture: ${capturedChangeCount} file change(s) authored to the ` +
-                    `file_review ledger (change_set=${changeSetId}), working tree left applied ` +
-                    `for review (execution=${executionId})`);
+            // pauseDetected is only true if a heartbeat() call threw CancelledFailure,
+            // confirming the orchestrator explicitly requested a pause.
+            if (turnState.pauseDetected) {
+                status.phase = ExecutionPhase.EXECUTION_PAUSED;
+                status.messages.push(create(AgentMessageSchema, {
+                    type: MessageType.MESSAGE_SYSTEM,
+                    content: "Execution paused by user. Use resume to continue.",
+                    timestamp: utcTimestamp(),
+                }));
+                await persist(status);
+                console.log(`ExecuteCursor paused: execution=${executionId}, events=${turnState.eventCount}`);
+                return { kind: "throw", message: "Activity paused by orchestrator" };
             }
-        }
-        // The gate reads each denied file's pre-edit `before` from the workspace the
-        // runner is co-located with (local FS for OSS; the sandbox in cloud), so a
-        // whole-file rewrite gate renders a true before/after diff. The tool was
-        // DENIED, so disk still holds the old content. User files are never platform
-        // paths, so no platformDir routing is needed here.
-        const gateWorkspaceBackend = new LocalWorkspaceBackend(primaryWorkspaceDir);
-        const deniedToolCalls = await reconcileDeniedToolCalls(status.messages, deniedLedger, mergedPolicies, gateWorkspaceBackend);
-        // Observability: a synthesized placeholder (id `approval:*`) means a denial
-        // correlated to NO streamed tool call in either the exact or the normalized
-        // pass. After the normalized-path fallback this should be ~0; a non-zero rate
-        // is the early-warning signal of a NEW identity drift (the gate would then
-        // show "No preview available" with no diff). Logged, not thrown — the
-        // synthesized gate still safely surfaces the approval.
-        const synthesizedGateCount = deniedToolCalls.filter((tc) => tc.id.startsWith("approval:")).length;
-        if (synthesizedGateCount > 0) {
-            console.warn(`ExecuteCursor reconcile synthesized ${synthesizedGateCount} placeholder gate(s) ` +
-                `with no correlated stream call (execution=${executionId}); ` +
-                `possible hook/stream identity drift — gate(s) will lack a diff`);
-        }
-        if (deniedToolCalls.length > 0 || capturedChangeCount > 0) {
-            if (deniedToolCalls.length > 0) {
-                // Deterministic clean-pause: a turn that pauses for approval must read as
-                // the same shape the native harness produces — pre-tool text + the gated
-                // tool calls — never the model's provisional reaction to Cursor's deny
-                // (e.g. "blocked by a hook; enable it in your Cursor settings"). We blank
-                // that reaction in place (keeping the message count, so the finalize stays
-                // append-only) rather than removing it. See
-                // clearProvisionalPostDenialNarration for the full rationale.
-                const redactedNarration = clearProvisionalPostDenialNarration(status.messages, deniedToolCalls);
-                if (redactedNarration.length > 0) {
-                    console.log(`ExecuteCursor redacted ${redactedNarration.length} provisional post-denial narration message(s) before pausing for approval`);
+            // Cancellation without pauseDetected (e.g. heartbeat timeout): report as
+            // failed rather than misleadingly labeling it a user pause.
+            if (Context.current().cancellationSignal.aborted) {
+                status.phase = ExecutionPhase.EXECUTION_FAILED;
+                status.error = "Execution interrupted: agent was unresponsive (heartbeat timeout). Retry or resume.";
+                status.completedAt = utcTimestamp();
+                status.messages.push(create(AgentMessageSchema, {
+                    type: MessageType.MESSAGE_SYSTEM,
+                    content: "Execution interrupted: the agent was unresponsive for too long. You can retry or resume.",
+                    timestamp: utcTimestamp(),
+                }));
+                await persist(status);
+                console.log(`ExecuteCursor interrupted (infrastructure cancel): execution=${executionId}, events=${turnState.eventCount}`);
+                return { kind: "throw", message: "Activity cancelled (heartbeat timeout, not user pause)" };
+            }
+            // Platform stop signal: a clean COMPLETED early exit.
+            if (turnState.platformStopSignaled) {
+                status.phase = ExecutionPhase.EXECUTION_COMPLETED;
+                status.completedAt = utcTimestamp();
+                status.messages.push(create(AgentMessageSchema, {
+                    type: MessageType.MESSAGE_SYSTEM,
+                    content: "Execution stopped by the platform.",
+                    timestamp: utcTimestamp(),
+                }));
+                await persist(status);
+                try {
+                    resolution.agent.close();
                 }
+                catch { /* best effort */ }
+                console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
+                return { kind: "return" };
             }
+            return { kind: "proceed" };
+        };
+        await finalizeStreamPhase();
+        const primaryTerminal = await resolvePreBoundaryTerminal();
+        if (primaryTerminal.kind === "return")
+            return slimStatus(status);
+        if (primaryTerminal.kind === "throw")
+            throw new CancelledFailure(primaryTerminal.message);
+        // Phase 12: The turn boundary — author this turn's change set to the
+        // file_review ledger (CANDIDATE_CAPTURED) and overlay the hook's denials as
+        // WAITING_APPROVAL gate rows. The full pipeline and its ordering rationale
+        // live in turn-boundary.ts; this closure binds the turn's state so the
+        // recovery retries below (which re-run the agent AFTER this primary call)
+        // can re-enter the IDENTICAL pipeline — a retry's edits must reach the
+        // ledger or they silently escape review. `baselineTree` is read at call
+        // time, so both entries see the baseline authored at turn start.
+        const runBoundary = (denialSettled) => runTurnBoundary({
+            status,
+            executionId,
+            changeSetId,
+            hitlDir,
+            captureMode,
+            baselineTree,
+            primaryWorkspaceDir,
+            gitWorkspace,
+            turnStartMessageIndex,
+            approvalGrants,
+            globalBypass,
+            seededSubAgents,
+            artifactStorage,
+            mergedPolicies,
+            denialCancelSettled: denialSettled,
+        });
+        // Pauses for review exactly like the native harness: the boundary mutated
+        // the transcript in place; we flip the phase, persist, and RETURN to the
+        // workflow, which waits for the approval/file-review signal and reinvokes.
+        const enterApprovalPause = async (boundary) => {
             status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
             await persist(status);
-            console.log(`ExecuteCursor returning WAITING_FOR_APPROVAL: ${deniedToolCalls.length} gated tool(s), ` +
-                `${capturedChangeCount} file card(s) pending`);
+            console.log(`ExecuteCursor returning WAITING_FOR_APPROVAL: ${boundary.deniedToolCallCount} gated tool(s), ` +
+                `${boundary.capturedChangeCount} file card(s) pending`);
             return slimStatus(status);
+        };
+        // Re-enter the turn boundary for a recovery retry: author the retry's net
+        // change set to the file_review ledger and overlay any denials as gates —
+        // without this a retry's file edits silently escape review (production case
+        // aex_01kws27q1e2esvkqjpvectttxf). The stream finalize now runs through the
+        // shared finalizeStreamPhase (in runRecoveryStream), so this is only the
+        // boundary + completedAt. Returns undefined for a cancelled retry — there is
+        // no review to open. Passes denialCancelSettled so a first denial that stopped
+        // the RETRY waits for run.cancel() before the ledger read, exactly like the
+        // primary path.
+        const settleRetryTurn = async (retryResultStatus) => {
+            const retryBoundary = retryResultStatus === "cancelled"
+                ? undefined
+                : await runBoundary(turnState.firstDenialDetected ? turnState.denialCancelSettled : undefined);
+            // Phase 13 stamped completedAt BEFORE the retry ran. A terminal outcome
+            // re-stamps it to the true end; a review pause CLEARS it — the primary
+            // pause path never stamps it (a waiting turn is not complete).
+            status.completedAt = retryBoundary?.waiting ? "" : utcTimestamp();
+            return retryBoundary;
+        };
+        const runRecoveryStream = async (freshAgent, retryPrompt) => {
+            // The fresh agent is now the live handle: point resolution at it so the
+            // terminal close() (platform stop, or Phase 14 success) frees THIS agent's
+            // executor lease rather than the disposed one it replaced. (Without this the
+            // poisoned-handle path leaked the fresh agent — it closed the stale one.)
+            resolution = { ...resolution, agent: freshAgent, agentId: freshAgent.agentId, isNew: true };
+            turnState.streamErrorMessage = undefined;
+            const retryRun = await freshAgent.send(retryPrompt, {
+                onDelta: makeCursorTurnOnDelta(onDeltaDeps),
+            });
+            await consumeCursorTurnStream(retryRun, streamDeps);
+            await finalizeStreamPhase();
+            const terminal = await resolvePreBoundaryTerminal();
+            if (terminal.kind !== "proceed")
+                return { proceeded: false, terminal };
+            const retryResult = await retryRun.wait();
+            console.log(`ExecuteCursor retry run.wait(): execution=${executionId}, ` +
+                `retryResult=${JSON.stringify(retryResult)}`);
+            const retryBoundary = await settleRetryTurn(retryResult.status);
+            return { proceeded: true, retryRun, retryResult, retryBoundary };
+        };
+        // The denial-settle wait applies only when a first denial stopped THIS run;
+        // a normal completion passes no promise.
+        const boundary = await runBoundary(turnState.firstDenialDetected ? turnState.denialCancelSettled : undefined);
+        if (boundary.waiting) {
+            return enterApprovalPause(boundary);
         }
         // Phase 13: Map final result
         const result = await run.wait();
@@ -1218,7 +1073,7 @@ turnSeq) {
                     clearCapturedRejection(executionId);
                 const classified = synthesizeError({
                     sdkResultFields: sdkErrorStr,
-                    streamErrorMessage,
+                    streamErrorMessage: turnState.streamErrorMessage,
                     capturedRejection,
                     conversationErrorText,
                     isResumedHandle: resolution.reason === "resumed_successfully",
@@ -1273,50 +1128,21 @@ turnSeq) {
                     catch (updateErr) {
                         console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
                     }
-                    let retryWatchdog;
-                    const retryRun = await freshAgent.send(freshPrompt, {
-                        onDelta: ({ update }) => {
-                            retryWatchdog?.recordActivity();
-                            if (update.type === "turn-ended" && update.usage) {
-                                usageAccumulator.addTurn(update.usage);
-                            }
-                            deltaEnricher.processDelta(update);
-                            try {
-                                heartbeat();
-                            }
-                            catch { /* swallow during retry */ }
-                        },
-                    });
-                    // Mirror the primary stream's stall protection: a wedged retry must
-                    // not hang the activity. On stall, cancel the run so the loop ends and
-                    // retryRun.wait() resolves down the existing non-finished failure path.
-                    retryWatchdog = startStallWatchdog(config.cursorStreamStallTimeoutMs, (idleMs) => {
-                        console.warn(`ExecuteCursor retry stall detected: execution=${executionId}, idleMs=${idleMs}`);
-                        if (retryRun.supports?.("cancel"))
-                            void retryRun.cancel().catch(() => { });
-                    });
-                    streamErrorMessage = undefined;
-                    try {
-                        for await (const retryEvent of retryRun.stream()) {
-                            if (Context.current().cancellationSignal.aborted)
-                                break;
-                            retryWatchdog.recordActivity();
-                            accumulator.processEvent(retryEvent);
-                            if (retryEvent.type === "status") {
-                                const retryStatusEvent = retryEvent;
-                                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
-                                    streamErrorMessage = retryStatusEvent.message;
-                                }
-                            }
-                            heartbeat();
-                        }
+                    const outcome = await runRecoveryStream(freshAgent, freshPrompt);
+                    if (!outcome.proceeded) {
+                        if (outcome.terminal.kind === "return")
+                            return slimStatus(status);
+                        throw new CancelledFailure(outcome.terminal.message);
                     }
-                    finally {
-                        retryWatchdog.stop();
+                    const { retryRun, retryResult, retryBoundary } = outcome;
+                    if (retryBoundary?.waiting) {
+                        // The retry's edits/denials armed the gate — pause for review. On a
+                        // retry error this supersedes the failure, exactly as on the primary
+                        // path (a captured change pauses the turn before run.wait() is
+                        // consulted).
+                        console.log(`ExecuteCursor poisoned-handle recovery paused for review: execution=${executionId}`);
+                        return enterApprovalPause(retryBoundary);
                     }
-                    const retryResult = await retryRun.wait();
-                    console.log(`ExecuteCursor retry run.wait(): execution=${executionId}, ` +
-                        `retryResult=${JSON.stringify(retryResult)}`);
                     if (retryResult.status === "finished") {
                         status.phase = ExecutionPhase.EXECUTION_COMPLETED;
                         console.log(`ExecuteCursor poisoned-handle recovery SUCCEEDED: execution=${executionId}`);
@@ -1332,7 +1158,7 @@ turnSeq) {
                     const retryConversationErrorText = await introspectConversation(retryRun, executionId);
                     const retryClassified = synthesizeError({
                         sdkResultFields: retryResult.result ? String(retryResult.result) : undefined,
-                        streamErrorMessage,
+                        streamErrorMessage: turnState.streamErrorMessage,
                         capturedRejection: retryRejection,
                         conversationErrorText: retryConversationErrorText,
                         isResumedHandle: false,
@@ -1370,51 +1196,21 @@ turnSeq) {
                     catch (updateErr) {
                         console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
                     }
-                    let retryWatchdog;
-                    const retryRun = await freshAgent.send(effectivePrompt, {
-                        onDelta: ({ update }) => {
-                            retryWatchdog?.recordActivity();
-                            if (update.type === "turn-ended" && update.usage) {
-                                usageAccumulator.addTurn(update.usage);
-                            }
-                            deltaEnricher.processDelta(update);
-                            try {
-                                heartbeat();
-                            }
-                            catch { /* swallow during retry */ }
-                        },
-                    });
-                    // Mirror the primary stream's stall protection: a wedged retry must
-                    // not hang the activity. On stall, cancel the run so the loop ends and
-                    // retryRun.wait() resolves down the existing non-finished failure path.
-                    retryWatchdog = startStallWatchdog(config.cursorStreamStallTimeoutMs, (idleMs) => {
-                        console.warn(`ExecuteCursor retry stall detected: execution=${executionId}, idleMs=${idleMs}`);
-                        if (retryRun.supports?.("cancel"))
-                            void retryRun.cancel().catch(() => { });
-                    });
-                    streamErrorMessage = undefined;
-                    try {
-                        for await (const retryEvent of retryRun.stream()) {
-                            if (Context.current().cancellationSignal.aborted)
-                                break;
-                            retryWatchdog.recordActivity();
-                            accumulator.processEvent(retryEvent);
-                            if (retryEvent.type === "status") {
-                                const retryStatusEvent = retryEvent;
-                                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
-                                    streamErrorMessage = retryStatusEvent.message;
-                                }
-                            }
-                            heartbeat();
-                        }
+                    const outcome = await runRecoveryStream(freshAgent, effectivePrompt);
+                    if (!outcome.proceeded) {
+                        if (outcome.terminal.kind === "return")
+                            return slimStatus(status);
+                        throw new CancelledFailure(outcome.terminal.message);
                     }
-                    finally {
-                        retryWatchdog.stop();
+                    const { retryResult, retryBoundary } = outcome;
+                    if (retryBoundary?.waiting) {
+                        // The retry's edits/denials armed the gate — pause for review (see
+                        // the poisoned-handle branch above for the precedence rationale).
+                        console.log(`ExecuteCursor transport-timeout recovery paused for review: execution=${executionId}`);
+                        return enterApprovalPause(retryBoundary);
                     }
-                    const retryResult = await retryRun.wait();
                     if (retryResult.status === "finished") {
                         status.phase = ExecutionPhase.EXECUTION_COMPLETED;
-                        resolution = { ...resolution, agent: freshAgent, agentId: freshAgent.agentId, isNew: true };
                         break;
                     }
                     status.phase = ExecutionPhase.EXECUTION_FAILED;
@@ -1471,10 +1267,10 @@ turnSeq) {
             if (structuredOutput !== undefined) {
                 status.structuredOutput = structuredOutput;
             }
-            // Plan mode: publish the final plan message as a plan.md artifact. The
-            // Cursor harness has no auto-publish pipeline, so this is the only
-            // artifact path; build storage from the same config-driven factory the
-            // native harness uses.
+            // Plan mode: publish the final plan message as a plan artifact (named
+            // from the plan's title). The Cursor harness has no auto-publish
+            // pipeline, so this is the only artifact path; build storage from the
+            // same config-driven factory the native harness uses.
             if (interactionMode === InteractionMode.PLAN && finalText && artifactStorage) {
                 try {
                     await publishPlanArtifact({ status, executionId, planText: finalText, artifactStorage });
@@ -1533,7 +1329,7 @@ turnSeq) {
                     timestamp: utcTimestamp(),
                 }));
             }
-            else if (pauseDetected) {
+            else if (turnState.pauseDetected) {
                 console.log(`ExecuteCursor cancelled (pause) for execution ${executionId}`);
                 status.phase = ExecutionPhase.EXECUTION_PAUSED;
                 status.messages.push(create(AgentMessageSchema, {
@@ -1563,7 +1359,7 @@ turnSeq) {
         // treat the execution as paused rather than failed. The error was likely
         // caused by the cancellation (e.g. SDK stream teardown) and should not
         // overwrite the PAUSED state that the Pause RPC already set in the DB.
-        if (pauseDetected) {
+        if (turnState.pauseDetected) {
             const errDetail = err instanceof Error ? err.message : String(err);
             console.log(`ExecuteCursor error during pause (treating as pause): execution=${executionId}, error=${errDetail}`);
             status.phase = ExecutionPhase.EXECUTION_PAUSED;
@@ -1654,10 +1450,15 @@ turnSeq) {
         return slimStatus(status);
     }
     finally {
-        // Disarm the stall watchdog on EVERY exit path (idempotent). The happy
-        // path stops it after the stream loop; this covers throws before that
-        // point so no orphaned timer survives the activity.
-        stallWatchdog?.stop();
+        // End the OTel turn span + record metrics with the final token snapshot on
+        // EVERY exit path (idempotent). Placed here so the span covers any recovery
+        // retry (whose tokens accrue after the primary stream) and never leaks on an
+        // early return or throw. A no-op when OTel is off or the span never opened.
+        await finishTurnTelemetry?.();
+        // Disarm the stall watchdog on EVERY exit path (idempotent). consumeCursorTurnStream
+        // stops the one it armed; this covers throws before that point so no orphaned
+        // timer survives the activity.
+        turnState.stallWatchdog?.stop();
         // Close the denial-ledger watcher on EVERY exit path (idempotent) so no
         // orphaned fs.watch handle survives the activity.
         stopDenialWatcher?.();