@stigmer/runner 3.0.8-dev.20260613085218 → 3.0.8

package/src/activities/execute-cursor/hook-script.ts

@@ -1,15 +1,23 @@
 /**
- * Template for the preToolUse hook script that Cursor spawns.
+ * Template for the approval hook script that Cursor spawns.
  *
- * This module doesn't execute as a hook itself — it generates the shell
- * script that is written to .cursor/hooks/stigmer-approval.sh. That script
- * is invoked by Cursor for every tool call via the preToolUse hook.
+ * This module doesn't execute as a hook itself — it generates the shell script
+ * written to the HITL dir as stigmer-approval.sh. Cursor invokes that ONE script
+ * for TWO events (registered in .cursor/hooks.json by workspace-setup.ts):
+ *   - `preToolUse`         — fires for built-in tools (Write/Shell/Delete/…).
+ *   - `beforeMCPExecution` — the only event Cursor enforces for MCP tool calls;
+ *                            `preToolUse` does NOT gate MCP (confirmed by a live
+ *                            payload capture). MCP is therefore gated in exactly
+ *                            ONE place, so a denial is never double-recorded.
+ * The script branches on the payload's `hook_event_name`: MCP tools are gated on
+ * the beforeMCPExecution invocation, built-ins on the preToolUse invocation.
  *
  * The hook script:
  * 1. Reads the tool call JSON from stdin
  * 2. Reads the approval state JSON file written by the cursor-runner
- * 3. Evaluates the policy: auto-approve, approved grants (reinvocation),
- *    gated built-in tools, MCP require-approval policies
+ * 3. Evaluates the policy: auto-approve, approved grants (reinvocation), then —
+ *    by event — gated built-in tools (preToolUse) or MCP require-approval
+ *    policies (beforeMCPExecution)
  * 4. On a deny, appends the call's identity token to the denial ledger
  *    (stigmer-denials.jsonl) so the runner can mark the gated tool call as
  *    WAITING_APPROVAL — the hook is the only place the deny decision is made,
@@ -49,23 +57,35 @@
  * Policy evaluation order (first match wins). The model is "gate the dangerous
  * set, allow the rest" — matching the native harness and avoiding denial of
  * auto-approved MCP tools (which are absent from mcpToolPolicies):
- * 1. autoApproveAll → allow
- * 2. Gated built-in (category non-empty):
- *    a. identity token in approvedGrantTokens → allow (reinvocation grant)
+ * 0. Scope guard: not the runner's own agent → allow (never touch the ledger)
+ * 1. Missing state file → deny (fail-closed); autoApproveAll → allow
+ * 2. beforeMCPExecution event → MCP tool present in mcpToolPolicies
+ *    (require-approval):
+ *    a. name token in approvedGrantTokens → allow (reinvocation grant)
  *    b. otherwise → record denial, deny
- * 3. MCP tool present in mcpToolPolicies (require-approval):
- *    a. name token in approvedGrantTokens → allow
+ *    (auto-approved / unlisted MCP tools fall through → allow)
+ * 3. preToolUse event → gated built-in (category non-empty):
+ *    a. identity token in approvedGrantTokens → allow (reinvocation grant)
  *    b. otherwise → record denial, deny
- * 4. Everything else (read-only built-ins, auto-approved MCP, unknown) → allow
+ *    (read-only / ungated built-ins fall through → allow)
  */
 
 import { SALIENT_ARG_FIELDS, getBuiltInGatedCategories } from "./approval-policy.js";
 
+// Shown to the model when the gate denies a tool call. It must NOT teach the
+// model to ask for permission in prose or to "stop and wait" — that framing
+// makes the model narrate approval requests instead of invoking tools (the
+// platform's approval surface is driven by tool invocation; see
+// formatToolApprovalProtocol in prompt-builder.ts). Instead it tells the model
+// the approval is automatic and that it should not retry or work around THIS
+// action. Embedded verbatim into the generated hook script inside a
+// single-quoted bash echo of a JSON object, so the text must contain no double
+// quotes, apostrophes, or backslashes.
 const APPROVAL_REQUIRED_AGENT_MESSAGE =
-  "STIGMER_APPROVAL_REQUIRED: This tool call requires user approval before " +
-  "execution. Do not attempt alternative approaches or workarounds (including " +
-  "shell commands). Stop and wait — the execution will resume after the user " +
-  "reviews and approves this tool call.";
+  "This action has been submitted to the user for approval automatically; you " +
+  "do not need to ask for permission. Do not retry it or attempt a workaround " +
+  "for this action. The platform will resume you automatically after the user " +
+  "responds — continue with the rest of the task.";
 
 /**
  * Build the bash `case` arms that map an incoming hook `tool_name` to its
@@ -91,9 +111,11 @@ function buildCategoryCaseArms(): string {
  * Build the inline Node.js identity extractor embedded in the hook script.
  *
  * Parses the hook's stdin JSON properly (the bash fallback's grep truncates
- * string values at the first escaped quote) and emits four lines:
- * tool_name, canonical category, identity token, and MCP name-token. The token
- * encodings must stay byte-identical to grantToken() in approval-state.ts.
+ * string values at the first escaped quote) and emits five lines: tool_name,
+ * canonical category, identity token, MCP name-token, and hook_event_name (the
+ * event discriminator: `preToolUse` for built-ins, `beforeMCPExecution` for MCP).
+ * The token encodings must stay byte-identical to grantToken() in
+ * approval-state.ts.
  *
  * Authored as a single-quoted bash string, so the JS must not contain single
  * quotes. The category map and salient field list are baked from
@@ -115,7 +137,8 @@ function buildNodeIdentityScript(): string {
     `let s="";`,
     `for(const f of ${fields}){const v=a[f];if(typeof v==="string"&&v){s=v;break;}}`,
     `const b=(x)=>Buffer.from(x,"utf8").toString("base64");`,
-    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n"));`,
+    `const ev=typeof t.hook_event_name==="string"?t.hook_event_name:"";`,
+    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n")+"\\n"+ev);`,
   ].join("");
 }
 
@@ -156,13 +179,15 @@ export function generateHookScript(
   const categoryCaseArms = buildCategoryCaseArms();
   const nodeIdentityScript = buildNodeIdentityScript();
   return `#!/bin/bash
-# Stigmer HITL approval hook for Cursor preToolUse
+# Stigmer HITL approval hook for Cursor (preToolUse + beforeMCPExecution).
 # Generated by cursor-runner — do not edit manually.
 #
-# Reads tool call from stdin (JSON), checks approval state file, returns a
-# permission decision on stdout (JSON). On a deny, appends the call's canonical
-# identity token to the denial ledger so the runner can mark the gated tool call
-# as WAITING_APPROVAL. See hook-script.ts for the cross-taxonomy identity design.
+# Reads a tool call from stdin (JSON), checks the approval state file, returns a
+# permission decision on stdout (JSON). Branches on hook_event_name: MCP tools
+# are gated on beforeMCPExecution, built-ins on preToolUse (preToolUse does not
+# enforce MCP). On a deny, appends the call's canonical identity token to the
+# denial ledger so the runner can mark the gated tool call as WAITING_APPROVAL.
+# See hook-script.ts for the cross-taxonomy identity design.
 
 set -euo pipefail
 
@@ -219,6 +244,7 @@ if [ -n "$IDENTITY" ]; then
   CATEGORY=$(printf '%s\\n' "$IDENTITY" | sed -n 2p)
   TOKEN=$(printf '%s\\n' "$IDENTITY" | sed -n 3p)
   MCP_TOKEN=$(printf '%s\\n' "$IDENTITY" | sed -n 4p)
+  HOOK_EVENT=$(printf '%s\\n' "$IDENTITY" | sed -n 5p)
 else
   # Fallback when the Node binary cannot run: grep/cut extraction. Best-effort
   # only — '"field":"[^"]*"' truncates at the first JSON-escaped quote, so the
@@ -227,6 +253,7 @@ else
   # Every extraction ends with '|| true': under 'set -e' a non-matching grep
   # would otherwise abort the script and emit no decision.
   TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+  HOOK_EVENT=$(echo "$INPUT" | grep -o '"hook_event_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
   SALIENT=""
   for field in ${salientFields}; do
     v=$(echo "$INPUT" | grep -o "\\"$field\\":\\"[^\\"]*\\"" | head -1 | cut -d'"' -f4 || true)
@@ -262,7 +289,37 @@ record_denial() {
   echo '{"toolName":"'"$TOOL_NAME"'","token":"'"$1"'"}' >> "$LEDGER_FILE" 2>/dev/null || true
 }
 
-# --- 2. Gated built-in tools (category non-empty) ---
+# --- 2. MCP tools (beforeMCPExecution event) ---
+# preToolUse does NOT enforce gating for MCP calls — beforeMCPExecution does — so
+# MCP is gated here and ONLY here (never double-recorded). mcpToolPolicies holds
+# only require-approval tools (auto-approved MCP tools are absent), so presence
+# means "deny" unless an entry is explicitly false. MCP tool names are consistent
+# across the hook and the stream, so the identity token is name-only:
+# base64("$TOOL_NAME\\n").
+if [ "$HOOK_EVENT" = "beforeMCPExecution" ]; then
+  if echo "$STATE" | grep -q "\\"mcpToolPolicies\\"" && [ -n "$TOOL_NAME" ]; then
+    TOOL_POLICY=$(echo "$STATE" | grep -o "\\"$TOOL_NAME\\":{[^}]*}" | head -1 || true)
+    if [ -n "$TOOL_POLICY" ] && ! echo "$TOOL_POLICY" | grep -q '"requiresApproval":false'; then
+      # Reinvocation grant: this tool was approved earlier → allow.
+      if echo "$STATE" | grep -qF "\\"$MCP_TOKEN\\""; then
+        echo '{"permission":"allow"}'
+        exit 0
+      fi
+      MSG=$(echo "$TOOL_POLICY" | grep -o '"message":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+      if [ -z "$MSG" ]; then
+        MSG="Tool requires approval: $TOOL_NAME"
+      fi
+      record_denial "$MCP_TOKEN"
+      echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"'"$MSG"'"}'
+      exit 0
+    fi
+  fi
+  # Auto-approved or unlisted MCP tool → allow.
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# --- 3. Gated built-in tools (preToolUse event, category non-empty) ---
 if [ -n "$CATEGORY" ]; then
   # Reinvocation grant: this exact resource was approved earlier → allow.
   if echo "$STATE" | grep -qF "\\"$TOKEN\\""; then
@@ -274,32 +331,9 @@ if [ -n "$CATEGORY" ]; then
   exit 0
 fi
 
-# --- 3. MCP tools that require approval → deny ---
-# mcpToolPolicies holds only require-approval tools (auto-approved MCP tools are
-# absent), so presence means "deny" unless an entry is explicitly false. MCP tool
-# names are consistent across the hook and the stream, so the identity token is
-# name-only: base64("$TOOL_NAME\\n").
-if echo "$STATE" | grep -q "\\"mcpToolPolicies\\"" && [ -n "$TOOL_NAME" ]; then
-  TOOL_POLICY=$(echo "$STATE" | grep -o "\\"$TOOL_NAME\\":{[^}]*}" | head -1 || true)
-  if [ -n "$TOOL_POLICY" ] && ! echo "$TOOL_POLICY" | grep -q '"requiresApproval":false'; then
-    if echo "$STATE" | grep -qF "\\"$MCP_TOKEN\\""; then
-      echo '{"permission":"allow"}'
-      exit 0
-    fi
-    MSG=$(echo "$TOOL_POLICY" | grep -o '"message":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
-    if [ -z "$MSG" ]; then
-      MSG="Tool requires approval: $TOOL_NAME"
-    fi
-    record_denial "$MCP_TOKEN"
-    echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"'"$MSG"'"}'
-    exit 0
-  fi
-fi
-
 # --- 4. Everything else → allow ---
-# Read-only built-ins, auto-approved MCP tools, and anything not explicitly
-# gated. Fail-open mirrors the native harness (gate the dangerous set, allow the
-# rest) and prevents denying auto-approved MCP tools the state cannot enumerate.
+# Read-only built-ins and anything not explicitly gated. Fail-open mirrors the
+# native harness (gate the dangerous set, allow the rest).
 echo '{"permission":"allow"}'
 exit 0
 `;

package/src/activities/execute-cursor/index.ts

@@ -43,7 +43,8 @@ import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_p
 import { determineCursorMode, isCloudMode } from "./cursor-mode.js";
 import { MessageAccumulator, reconcileDeniedToolCalls, cancelInProgressSubAgentProtos } from "./message-translator.js";
 import { utcTimestamp, persistStatus, reportSetupProgress, slimStatus } from "../../shared/status.js";
-import { createArtifactStorage, loadArtifactStorageConfig } from "../../shared/artifact-storage.js";
+import { startStallWatchdog, StallTimeoutError, formatStallFailure, type StallWatchdog } from "../../shared/stall-watchdog.js";
+import { createArtifactStorage, loadArtifactStorageConfig, type ArtifactStorage } from "../../shared/artifact-storage.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -127,11 +128,43 @@ async function executeCursorInner(
     startedAt: utcTimestamp(),
   });
 
+  // Artifact storage for offloading oversized tool outputs (screenshots, giant
+  // dumps) out of the persisted status, and for publishing the plan artifact.
+  // Created once here so it is available to EVERY persist below. Best-effort:
+  // if it can't be built (e.g. proxy mode without a token), offload is disabled
+  // but persistStatus still enforces the aggregate size cap, so persistence can
+  // never silently blow past the gRPC limit.
+  let artifactStorage: ArtifactStorage | undefined;
+  try {
+    artifactStorage = createArtifactStorage(loadArtifactStorageConfig(config));
+  } catch (storageErr) {
+    console.warn(
+      `ExecuteCursor artifact storage unavailable — tool-output offload disabled ` +
+      `(aggregate size guard still active): execution=${executionId}, error=${storageErr}`,
+    );
+  }
+  const statusOffload = artifactStorage
+    ? { artifactStorage, executionId }
+    : undefined;
+  // ALL status persistence in this activity flows through `persist`, so the
+  // single size-bounding guard (offload + aggregate elision) is unforgeable and
+  // a future call site cannot accidentally skip it.
+  const persist = (s: AgentExecutionStatus = status) =>
+    persistStatus(client, executionId, s, { offload: statusOffload });
+
   let sessionId: string | undefined;
   let session: import("@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb").Session | undefined;
   let pauseDetected = false;
   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: StallTimeoutError | undefined;
   let periodicHeartbeat: ReturnType<typeof startHeartbeat> | undefined;
+  // Progress-based stall watchdog (see ../../shared/stall-watchdog.ts). Stopped
+  // in the finally on every exit path; complements the liveness heartbeat.
+  let stallWatchdog: StallWatchdog | undefined;
   // 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.
@@ -227,7 +260,7 @@ async function executeCursorInner(
             content: "Execution was rejected by the user during tool approval.",
             timestamp: utcTimestamp(),
           }));
-          await persistStatus(client, executionId, status);
+          await persist(status);
           return slimStatus(status);
         }
       }
@@ -496,6 +529,9 @@ async function executeCursorInner(
     let firstTurnAttributionLogged = false;
     let streamErrorMessage: string | undefined;
     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: string | undefined;
 
     // Periodic heartbeat keeps Temporal informed during silent SDK operations
     // (e.g. long tool calls, MCP requests, model thinking). Without this,
@@ -525,6 +561,10 @@ async function executeCursorInner(
 
     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);
 
@@ -552,14 +592,46 @@ async function executeCursorInner(
       },
     });
 
+    // 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}`,
+          );
+        });
+      }
+    });
+
     const accumulator = new MessageAccumulator(status.messages, { mergedPolicies });
     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);
 
@@ -598,7 +670,7 @@ async function executeCursorInner(
         // 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 persistStatus(client, executionId, status);
+        const signal = await persist(status);
         deltaEnricher.markPersisted();
         todoTracker.markPersisted();
         accumulator.markSubAgentPersisted();
@@ -616,8 +688,17 @@ async function executeCursorInner(
         break;
       }
     }
+    } catch (streamErr) {
+      // run.cancel() from the stall watchdog can make the stream iterator
+      // reject; that is the expected teardown, so swallow it and fall through
+      // to the stallDetected branch in Phase 11a. Anything else is a genuine
+      // stream failure — rethrow it to the outer error handler.
+      if (!stallDetected) throw streamErr;
+      console.warn(`ExecuteCursor stream ended via stall cancel: execution=${executionId}`);
+    }
 
     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,
@@ -638,7 +719,7 @@ async function executeCursorInner(
     // 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 || Context.current().cancellationSignal.aborted) {
+    if (pauseDetected || workerShutdownDetected || stallDetected || Context.current().cancellationSignal.aborted) {
       accumulator.cancelInProgressSubAgents();
     }
     status.subAgentExecutions = accumulator.subAgentExecutions;
@@ -654,7 +735,7 @@ async function executeCursorInner(
     // call statuses before run.wait() / structured output extraction.
     // This is unconditional (not throttled) because finalize is a
     // once-per-execution correctness boundary.
-    await persistStatus(client, executionId, status);
+    await persist(status);
     heartbeat();
 
     // End OTel turn span with accumulated token usage
@@ -678,7 +759,29 @@ async function executeCursorInner(
     }
 
 
-    // Phase 11a: Handle worker shutdown, pause, or infrastructure cancellation.
+    // 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
@@ -692,7 +795,7 @@ async function executeCursorInner(
         content: "Execution interrupted: the runner worker was shut down while the agent was still running. You can retry or resume.",
         timestamp: utcTimestamp(),
       }));
-      await persistStatus(client, executionId, status);      console.log(`ExecuteCursor interrupted (worker shutdown): execution=${executionId}, events=${eventCount}`);
+      await persist(status);      console.log(`ExecuteCursor interrupted (worker shutdown): execution=${executionId}, events=${eventCount}`);
       throw new CancelledFailure("Activity cancelled (worker shutdown, not user pause)");
     }
 
@@ -705,7 +808,7 @@ async function executeCursorInner(
         content: "Execution paused by user. Use resume to continue.",
         timestamp: utcTimestamp(),
       }));
-      await persistStatus(client, executionId, status);      console.log(`ExecuteCursor paused: execution=${executionId}, events=${eventCount}`);
+      await persist(status);      console.log(`ExecuteCursor paused: execution=${executionId}, events=${eventCount}`);
       throw new CancelledFailure("Activity paused by orchestrator");
     }
 
@@ -721,7 +824,7 @@ async function executeCursorInner(
         content: "Execution interrupted: the agent was unresponsive for too long. You can retry or resume.",
         timestamp: utcTimestamp(),
       }));
-      await persistStatus(client, executionId, status);      console.log(`ExecuteCursor interrupted (infrastructure cancel): execution=${executionId}, events=${eventCount}`);
+      await persist(status);      console.log(`ExecuteCursor interrupted (infrastructure cancel): execution=${executionId}, events=${eventCount}`);
       throw new CancelledFailure("Activity cancelled (heartbeat timeout, not user pause)");
     }
 
@@ -734,7 +837,7 @@ async function executeCursorInner(
         content: "Execution stopped by the platform.",
         timestamp: utcTimestamp(),
       }));
-      await persistStatus(client, executionId, status);      try { resolution.agent.close(); } catch { /* best effort */ }
+      await persist(status);      try { resolution.agent.close(); } catch { /* best effort */ }
       console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
       return slimStatus(status);
     }
@@ -751,7 +854,7 @@ async function executeCursorInner(
     const deniedToolCalls = reconcileDeniedToolCalls(status.messages, deniedLedger, mergedPolicies);
     if (deniedToolCalls.length > 0) {
       status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
-      await persistStatus(client, executionId, status);
+      await persist(status);
       console.log(`ExecuteCursor returning WAITING_FOR_APPROVAL: ${deniedToolCalls.length} tools pending`);
       return slimStatus(status);
     }
@@ -858,8 +961,10 @@ async function executeCursorInner(
             console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
           }
 
+          let retryWatchdog: StallWatchdog | undefined;
           const retryRun = await freshAgent.send(freshPrompt, {
             onDelta: ({ update }) => {
+              retryWatchdog?.recordActivity();
               if (update.type === "turn-ended" && update.usage) {
                 usageAccumulator.addTurn(update.usage);
               }
@@ -867,19 +972,31 @@ async function executeCursorInner(
               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(() => { /* best effort */ });
+          });
 
           streamErrorMessage = undefined;
 
-          for await (const retryEvent of retryRun.stream()) {
-            if (Context.current().cancellationSignal.aborted) break;
-            accumulator.processEvent(retryEvent);
-            if (retryEvent.type === "status") {
-              const retryStatusEvent = retryEvent as { status?: string; message?: string };
-              if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
-                streamErrorMessage = retryStatusEvent.message;
+          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 as { status?: string; message?: string };
+                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
+                  streamErrorMessage = retryStatusEvent.message;
+                }
               }
+              heartbeat();
             }
-            heartbeat();
+          } finally {
+            retryWatchdog.stop();
           }
 
           const retryResult = await retryRun.wait();
@@ -953,8 +1070,10 @@ async function executeCursorInner(
             console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
           }
 
+          let retryWatchdog: StallWatchdog | undefined;
           const retryRun = await freshAgent.send(effectivePrompt, {
             onDelta: ({ update }) => {
+              retryWatchdog?.recordActivity();
               if (update.type === "turn-ended" && update.usage) {
                 usageAccumulator.addTurn(update.usage);
               }
@@ -962,19 +1081,31 @@ async function executeCursorInner(
               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(() => { /* best effort */ });
+          });
 
           streamErrorMessage = undefined;
 
-          for await (const retryEvent of retryRun.stream()) {
-            if (Context.current().cancellationSignal.aborted) break;
-            accumulator.processEvent(retryEvent);
-            if (retryEvent.type === "status") {
-              const retryStatusEvent = retryEvent as { status?: string; message?: string };
-              if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
-                streamErrorMessage = retryStatusEvent.message;
+          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 as { status?: string; message?: string };
+                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
+                  streamErrorMessage = retryStatusEvent.message;
+                }
               }
+              heartbeat();
             }
-            heartbeat();
+          } finally {
+            retryWatchdog.stop();
           }
 
           const retryResult = await retryRun.wait();
@@ -1059,9 +1190,8 @@ async function executeCursorInner(
       // 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) {
+      if (interactionMode === InteractionMode.PLAN && finalText && artifactStorage) {
         try {
-          const artifactStorage = createArtifactStorage(loadArtifactStorageConfig(config));
           await publishPlanArtifact({ status, executionId, planText: finalText, artifactStorage });
         } catch (err) {
           console.warn(
@@ -1073,7 +1203,7 @@ async function executeCursorInner(
     }
 
     // NOW persist — subscriber sees COMPLETED + structured_output atomically
-    await persistStatus(client, executionId, status);
+    await persist(status);
 
     console.log(
       `ExecuteCursor completed: execution=${executionId}, phase=${ExecutionPhase[status.phase]}, ` +
@@ -1131,7 +1261,7 @@ async function executeCursorInner(
       // The aborted Cursor run leaves no live sub-agent — mark any in-flight
       // delegation CANCELLED so the final snapshot has no zombie sub-agent.
       cancelInProgressSubAgentProtos(status.subAgentExecutions);
-      await persistStatus(client, executionId, status).catch(() => {});      throw err;
+      await persist(status).catch(() => {});      throw err;
     }
 
     // If a non-CancelledFailure error occurs while a pause is in progress,
@@ -1150,7 +1280,7 @@ async function executeCursorInner(
         timestamp: utcTimestamp(),
       }));
       cancelInProgressSubAgentProtos(status.subAgentExecutions);
-      await persistStatus(client, executionId, status).catch(() => {});      throw new CancelledFailure("Activity paused by orchestrator (error during pause)");
+      await persist(status).catch(() => {});      throw new CancelledFailure("Activity paused by orchestrator (error during pause)");
     }
 
     // Infrastructure cancellation (e.g. heartbeat timeout) with a
@@ -1169,7 +1299,7 @@ async function executeCursorInner(
         timestamp: utcTimestamp(),
       }));
       cancelInProgressSubAgentProtos(status.subAgentExecutions);
-      await persistStatus(client, executionId, status).catch(() => {});      throw new CancelledFailure("Activity cancelled (infrastructure, not user pause)");
+      await persist(status).catch(() => {});      throw new CancelledFailure("Activity cancelled (infrastructure, not user pause)");
     }
 
     // A thrown CursorSdkError carries structured fields (code/status/endpoint/
@@ -1207,7 +1337,7 @@ async function executeCursorInner(
         }),
       );
       try {
-        await persistStatus(client, executionId, status);
+        await persist(status);
       } catch (persistErr) {
         console.error("Failed to persist error status (best-effort):", persistErr);
       }      return slimStatus(status);
@@ -1234,13 +1364,18 @@ async function executeCursorInner(
     );
 
     try {
-      await persistStatus(client, executionId, status);
+      await persist(status);
     } catch (persistErr) {
       console.error("Failed to persist error status (best-effort):", persistErr);
     }
 
     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();
+
     // Tear down the HITL gate on EVERY exit path (success, error, approval
     // pause, cancellation) so attaching a real repo leaves the user's
     // .cursor/hooks.json and workspace untouched between turns (issue #173).