@stigmer/runner 3.0.8-dev.20260613074252 → 3.0.8

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

@@ -36,6 +36,7 @@ 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 { startStallWatchdog, StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
 import { createArtifactStorage, loadArtifactStorageConfig } from "../../shared/artifact-storage.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
@@ -102,11 +103,40 @@ async function executeCursorInner(config, client, executionId, threadId) {
         phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
         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;
+    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 = status) => persistStatus(client, executionId, s, { offload: statusOffload });
     let sessionId;
     let session;
     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;
     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;
     // 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.
@@ -186,7 +216,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                         content: "Execution was rejected by the user during tool approval.",
                         timestamp: utcTimestamp(),
                     }));
-                    await persistStatus(client, executionId, status);
+                    await persist(status);
                     return slimStatus(status);
                 }
             }
@@ -384,6 +414,9 @@ async function executeCursorInner(config, client, executionId, threadId) {
         let firstTurnAttributionLogged = false;
         let streamErrorMessage;
         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;
         // 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
@@ -411,6 +444,10 @@ async function executeCursorInner(config, client, executionId, threadId) {
         }
         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) {
@@ -435,57 +472,95 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 }
             },
         });
+        // 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;
-        for await (const event of run.stream()) {
-            if (pauseDetected || Context.current().cancellationSignal.aborted) {
-                pauseDetected = true;
-                break;
-            }
-            eventRecorder?.record(event, eventCount);
-            accumulator.processEvent(event);
-            todoTracker.processEvent(event);
-            if (event.type === "tool_call" && event.name === "task") {
-                accumulator.trackSubAgentExecution(event);
-            }
-            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;
+        try {
+            for await (const event of run.stream()) {
+                if (pauseDetected || Context.current().cancellationSignal.aborted) {
+                    pauseDetected = true;
+                    break;
                 }
-            }
-            const shouldPersist = eventCount % 20 === 0 || deltaEnricher.isDirty ||
-                todoTracker.isDirty || accumulator.subAgentDirty;
-            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 persistStatus(client, executionId, status);
-                deltaEnricher.markPersisted();
-                todoTracker.markPersisted();
-                accumulator.markSubAgentPersisted();
-                heartbeat();
-                if (signal === ExecutionControlSignal.STOP) {
-                    platformStopSignaled = true;
-                    console.warn(`ExecuteCursor platform stop signal received: execution=${executionId}`);
+                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);
+                }
+                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 = eventCount % 20 === 0 || deltaEnricher.isDirty ||
+                    todoTracker.isDirty || accumulator.subAgentDirty;
+                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.markSubAgentPersisted();
+                    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;
                 }
-            }
-            if (platformStopSignaled) {
-                console.log(`ExecuteCursor stopping stream due to platform stop signal: execution=${executionId}`);
-                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,
@@ -505,7 +580,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
         // 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;
@@ -518,7 +593,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
         // 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
         const usageSnapshot = usageAccumulator.snapshot();
@@ -539,7 +614,28 @@ async function executeCursorInner(config, client, executionId, threadId) {
         catch {
             // Metrics not initialized — silently skip.
         }
-        // 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
         // an infrastructure event (e.g., premature removal from UI race).
@@ -552,7 +648,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 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);
+            await persist(status);
             console.log(`ExecuteCursor interrupted (worker shutdown): execution=${executionId}, events=${eventCount}`);
             throw new CancelledFailure("Activity cancelled (worker shutdown, not user pause)");
         }
@@ -565,7 +661,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 content: "Execution paused by user. Use resume to continue.",
                 timestamp: utcTimestamp(),
             }));
-            await persistStatus(client, executionId, status);
+            await persist(status);
             console.log(`ExecuteCursor paused: execution=${executionId}, events=${eventCount}`);
             throw new CancelledFailure("Activity paused by orchestrator");
         }
@@ -581,7 +677,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 content: "Execution interrupted: the agent was unresponsive for too long. You can retry or resume.",
                 timestamp: utcTimestamp(),
             }));
-            await persistStatus(client, executionId, status);
+            await persist(status);
             console.log(`ExecuteCursor interrupted (infrastructure cancel): execution=${executionId}, events=${eventCount}`);
             throw new CancelledFailure("Activity cancelled (heartbeat timeout, not user pause)");
         }
@@ -594,7 +690,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 content: "Execution stopped by the platform.",
                 timestamp: utcTimestamp(),
             }));
-            await persistStatus(client, executionId, status);
+            await persist(status);
             try {
                 resolution.agent.close();
             }
@@ -614,7 +710,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
         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);
         }
@@ -702,8 +798,10 @@ async function executeCursorInner(config, client, executionId, threadId) {
                     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);
                             }
@@ -714,18 +812,32 @@ async function executeCursorInner(config, client, executionId, threadId) {
                             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;
-                    for await (const retryEvent of retryRun.stream()) {
-                        if (Context.current().cancellationSignal.aborted)
-                            break;
-                        accumulator.processEvent(retryEvent);
-                        if (retryEvent.type === "status") {
-                            const retryStatusEvent = retryEvent;
-                            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;
+                                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
+                                    streamErrorMessage = retryStatusEvent.message;
+                                }
                             }
+                            heartbeat();
                         }
-                        heartbeat();
+                    }
+                    finally {
+                        retryWatchdog.stop();
                     }
                     const retryResult = await retryRun.wait();
                     console.log(`ExecuteCursor retry run.wait(): execution=${executionId}, ` +
@@ -783,8 +895,10 @@ async function executeCursorInner(config, client, executionId, threadId) {
                     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);
                             }
@@ -795,18 +909,32 @@ async function executeCursorInner(config, client, executionId, threadId) {
                             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;
-                    for await (const retryEvent of retryRun.stream()) {
-                        if (Context.current().cancellationSignal.aborted)
-                            break;
-                        accumulator.processEvent(retryEvent);
-                        if (retryEvent.type === "status") {
-                            const retryStatusEvent = retryEvent;
-                            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;
+                                if (retryStatusEvent.status === "ERROR" && retryStatusEvent.message) {
+                                    streamErrorMessage = retryStatusEvent.message;
+                                }
                             }
+                            heartbeat();
                         }
-                        heartbeat();
+                    }
+                    finally {
+                        retryWatchdog.stop();
                     }
                     const retryResult = await retryRun.wait();
                     if (retryResult.status === "finished") {
@@ -872,9 +1000,8 @@ async function executeCursorInner(config, client, executionId, threadId) {
             // 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) {
@@ -884,7 +1011,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
             }
         }
         // 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]}, ` +
             `hasStructuredOutput=${structuredOutput !== undefined}` +
             (status.error ? `, error=${status.error}` : ""));
@@ -941,7 +1068,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
             // 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(() => { });
+            await persist(status).catch(() => { });
             throw err;
         }
         // If a non-CancelledFailure error occurs while a pause is in progress,
@@ -958,7 +1085,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 timestamp: utcTimestamp(),
             }));
             cancelInProgressSubAgentProtos(status.subAgentExecutions);
-            await persistStatus(client, executionId, status).catch(() => { });
+            await persist(status).catch(() => { });
             throw new CancelledFailure("Activity paused by orchestrator (error during pause)");
         }
         // Infrastructure cancellation (e.g. heartbeat timeout) with a
@@ -975,7 +1102,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 timestamp: utcTimestamp(),
             }));
             cancelInProgressSubAgentProtos(status.subAgentExecutions);
-            await persistStatus(client, executionId, status).catch(() => { });
+            await persist(status).catch(() => { });
             throw new CancelledFailure("Activity cancelled (infrastructure, not user pause)");
         }
         // A thrown CursorSdkError carries structured fields (code/status/endpoint/
@@ -1008,7 +1135,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
                 timestamp: utcTimestamp(),
             }));
             try {
-                await persistStatus(client, executionId, status);
+                await persist(status);
             }
             catch (persistErr) {
                 console.error("Failed to persist error status (best-effort):", persistErr);
@@ -1031,7 +1158,7 @@ async function executeCursorInner(config, client, executionId, threadId) {
             timestamp: utcTimestamp(),
         }));
         try {
-            await persistStatus(client, executionId, status);
+            await persist(status);
         }
         catch (persistErr) {
             console.error("Failed to persist error status (best-effort):", persistErr);
@@ -1039,6 +1166,10 @@ async function executeCursorInner(config, client, executionId, threadId) {
         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).