gsd-pi 2.51.0 → 2.52.0-dev.655ad8a

package/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts

@@ -11,6 +11,13 @@ import type { SessionStats } from "../../core/agent-session.js";
 import type { BashResult } from "../../core/bash-executor.js";
 import type { CompactionResult } from "../../core/compaction/index.js";
 
+// ============================================================================
+// RPC Protocol Versioning
+// ============================================================================
+
+/** Supported protocol versions. v1 is the implicit default; v2 requires an init handshake. */
+export type RpcProtocolVersion = 1 | 2;
+
 // ============================================================================
 // RPC Commands (stdin)
 // ============================================================================
@@ -69,7 +76,12 @@ export type RpcCommand =
 	// Bridge-hosted native terminal
 	| { id?: string; type: "terminal_input"; data: string }
 	| { id?: string; type: "terminal_resize"; cols: number; rows: number }
-	| { id?: string; type: "terminal_redraw" };
+	| { id?: string; type: "terminal_redraw" }
+
+	// v2 Protocol
+	| { id?: string; type: "init"; protocolVersion: 2; clientId?: string }
+	| { id?: string; type: "shutdown"; graceful?: boolean }
+	| { id?: string; type: "subscribe"; events: string[] };
 
 // ============================================================================
 // RPC Slash Command (for get_commands response)
@@ -120,9 +132,9 @@ export interface RpcSessionState {
 // Success responses with data
 export type RpcResponse =
 	// Prompting (async - events follow)
-	| { id?: string; type: "response"; command: "prompt"; success: true }
-	| { id?: string; type: "response"; command: "steer"; success: true }
-	| { id?: string; type: "response"; command: "follow_up"; success: true }
+	| { id?: string; type: "response"; command: "prompt"; success: true; runId?: string }
+	| { id?: string; type: "response"; command: "steer"; success: true; runId?: string }
+	| { id?: string; type: "response"; command: "follow_up"; success: true; runId?: string }
 	| { id?: string; type: "response"; command: "abort"; success: true }
 	| { id?: string; type: "response"; command: "new_session"; success: true; data: { cancelled: boolean } }
 
@@ -216,9 +228,54 @@ export type RpcResponse =
 	| { id?: string; type: "response"; command: "terminal_resize"; success: true }
 	| { id?: string; type: "response"; command: "terminal_redraw"; success: true }
 
+	// v2 Protocol
+	| { id?: string; type: "response"; command: "init"; success: true; data: RpcInitResult }
+	| { id?: string; type: "response"; command: "shutdown"; success: true }
+	| { id?: string; type: "response"; command: "subscribe"; success: true }
+
 	// Error response (any command can fail)
 	| { id?: string; type: "response"; command: string; success: false; error: string };
 
+// ============================================================================
+// v2 Protocol Types
+// ============================================================================
+
+/** Result of the init handshake (v2 only) */
+export interface RpcInitResult {
+	protocolVersion: 2;
+	sessionId: string;
+	capabilities: {
+		events: string[];
+		commands: string[];
+	};
+}
+
+/** v2 execution_complete event — emitted when a prompt/steer/follow_up finishes */
+export interface RpcExecutionCompleteEvent {
+	type: "execution_complete";
+	runId: string;
+	status: "completed" | "error" | "cancelled";
+	reason?: string;
+	stats: SessionStats;
+}
+
+/** v2 cost_update event — emitted per-turn with running cost data */
+export interface RpcCostUpdateEvent {
+	type: "cost_update";
+	runId: string;
+	turnCost: number;
+	cumulativeCost: number;
+	tokens: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+}
+
+/** Discriminated union of all v2-only event types */
+export type RpcV2Event = RpcExecutionCompleteEvent | RpcCostUpdateEvent;
+
 // ============================================================================
 // Extension UI Events (stdout)
 // ============================================================================

package/packages/pi-coding-agent/src/utils/shell.ts

@@ -192,7 +192,6 @@ export function killProcessTree(pid: number): void {
 		try {
 			spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
 				stdio: "ignore",
-				detached: true,
 			});
 		} catch {
 			// Ignore errors if taskkill fails

package/packages/rpc-client/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@gsd/rpc-client",
+  "version": "2.51.0",
+  "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/scripts/ensure-workspace-builds.cjs

@@ -3,15 +3,18 @@
  * ensure-workspace-builds.cjs
  *
  * Checks whether workspace packages have been compiled (dist/ exists with
- * index.js). If any are missing, runs the build for those packages.
+ * index.js) and that the build is not stale (no src/ file newer than dist/).
+ * If any are missing or stale, runs the build for those packages.
  *
  * Designed for the postinstall hook so that `npm install` in a fresh clone
- * produces a working runtime without a manual `npm run build` step.
+ * produces a working runtime without a manual `npm run build` step. Also
+ * catches the common case where `git pull` updates package sources but the
+ * old dist/ remains, causing TypeScript type errors.
  *
  * Skipped in CI (where the full build pipeline handles this) and when
  * installing as an end-user dependency (no packages/ directory).
  */
-const { existsSync } = require('fs')
+const { existsSync, statSync, readdirSync } = require('fs')
 const { resolve, join } = require('path')
 const { execSync } = require('child_process')
 
@@ -34,19 +37,44 @@ const WORKSPACE_PACKAGES = [
   'pi-coding-agent',
 ]
 
-const missing = []
+/**
+ * Returns the most recent mtime (ms) of any .ts file under dir, recursively.
+ * Returns 0 if no .ts files found.
+ */
+function newestSrcMtime(dir) {
+  if (!existsSync(dir)) return 0
+  let newest = 0
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules') continue
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      newest = Math.max(newest, newestSrcMtime(full))
+    } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+      newest = Math.max(newest, statSync(full).mtimeMs)
+    }
+  }
+  return newest
+}
+
+const stale = []
 for (const pkg of WORKSPACE_PACKAGES) {
   const distIndex = join(packagesDir, pkg, 'dist', 'index.js')
   if (!existsSync(distIndex)) {
-    missing.push(pkg)
+    stale.push(pkg)
+    continue
+  }
+  const distMtime = statSync(distIndex).mtimeMs
+  const srcMtime = newestSrcMtime(join(packagesDir, pkg, 'src'))
+  if (srcMtime > distMtime) {
+    stale.push(pkg)
   }
 }
 
-if (missing.length === 0) process.exit(0)
+if (stale.length === 0) process.exit(0)
 
-process.stderr.write(`  Building ${missing.length} workspace package(s) missing dist/: ${missing.join(', ')}\n`)
+process.stderr.write(`  Building ${stale.length} workspace package(s) with stale or missing dist/: ${stale.join(', ')}\n`)
 
-for (const pkg of missing) {
+for (const pkg of stale) {
   const pkgDir = join(packagesDir, pkg)
   try {
     execSync('npm run build', { cwd: pkgDir, stdio: 'pipe' })

package/src/resources/extensions/async-jobs/async-bash-tool.ts

@@ -14,7 +14,7 @@ import {
 	DEFAULT_MAX_LINES,
 } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -38,17 +38,24 @@ function getTempFilePath(): string {
 }
 
 /**
- * Kill a process and its children. Uses process group kill on Unix.
+ * Kill a process and its children (cross-platform).
+ * Uses process group kill on Unix; taskkill /F /T on Windows.
  */
 function killTree(pid: number): void {
-	try {
-		// Kill the process group (negative PID)
-		process.kill(-pid, "SIGTERM");
-	} catch {
+	if (process.platform === "win32") {
 		try {
-			process.kill(pid, "SIGTERM");
+			spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
+				timeout: 5_000,
+				stdio: "ignore",
+			});
+		} catch {
+			try { process.kill(pid, "SIGTERM"); } catch { /* already exited */ }
+		}
+	} else {
+		try {
+			process.kill(-pid, "SIGTERM");
 		} catch {
-			// Already exited
+			try { process.kill(pid, "SIGTERM"); } catch { /* already exited */ }
 		}
 	}
 }
@@ -118,9 +125,13 @@ function executeBashInBackground(
 		const rewrittenCommand = rewriteCommandWithRtk(command);
 		const resolvedCommand = sanitizeCommand(rewrittenCommand);
 
+		// On Windows, detached: true sets CREATE_NEW_PROCESS_GROUP which can
+		// cause EINVAL in VSCode/ConPTY terminal contexts.  The bg-shell
+		// extension already guards this (process-manager.ts); align here.
+		// Process-tree cleanup uses taskkill /F /T on Windows regardless.
 		const child = spawn(shell, [...args, resolvedCommand], {
 			cwd,
-			detached: true,
+			detached: process.platform !== "win32",
 			env: { ...process.env },
 			stdio: ["ignore", "pipe", "pipe"],
 		});
@@ -143,8 +154,8 @@ function executeBashInBackground(
 				// If the process ignores SIGTERM, escalate to SIGKILL
 				sigkillHandle = setTimeout(() => {
 					if (child.pid) {
-						try { process.kill(-child.pid, "SIGKILL"); } catch { /* ignore */ }
-						try { process.kill(child.pid, "SIGKILL"); } catch { /* ignore */ }
+						// killTree already uses taskkill /F /T on Windows
+						killTree(child.pid);
 					}
 
 					// Hard deadline: if even SIGKILL doesn't trigger 'close',

package/src/resources/extensions/async-jobs/job-manager.ts

@@ -172,7 +172,10 @@ export class AsyncJobManager {
 
 	private deliverResult(job: Job): void {
 		if (!this.onJobComplete) return;
-		this.onJobComplete(job);
+		// Defer delivery by one microtask so await_job's .then() chain runs first
+		// and can set job.awaited = true before onJobComplete checks it (#2762).
+		const cb = this.onJobComplete;
+		queueMicrotask(() => cb(job));
 	}
 
 	private scheduleEviction(id: string): void {

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -113,6 +113,20 @@ function makeErrorMessage(model: string, errorMsg: string): AssistantMessage {
 	};
 }
 
+/**
+ * Generator exhaustion without a terminal result means the SDK stream was
+ * interrupted mid-turn. Surface it as an error so downstream recovery logic
+ * can classify and retry it instead of treating it as a clean completion.
+ */
+export function makeStreamExhaustedErrorMessage(model: string, lastTextContent: string): AssistantMessage {
+	const errorMsg = "stream_exhausted_without_result";
+	const message = makeErrorMessage(model, errorMsg);
+	if (lastTextContent) {
+		message.content = [{ type: "text", text: lastTextContent }];
+	}
+	return message;
+}
+
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
@@ -339,26 +353,11 @@ async function pumpSdkMessages(
 			}
 		}
 
-		// Generator exhausted without a result message (unexpected)
-		const fallbackContent: AssistantMessage["content"] = [];
-		if (lastTextContent) {
-			fallbackContent.push({ type: "text", text: lastTextContent });
-		}
-		if (fallbackContent.length === 0) {
-			fallbackContent.push({ type: "text", text: "(Claude Code session ended without a response)" });
-		}
-
-		const fallback: AssistantMessage = {
-			role: "assistant",
-			content: fallbackContent,
-			api: "anthropic-messages",
-			provider: "claude-code",
-			model: modelId,
-			usage: { ...ZERO_USAGE },
-			stopReason: "stop",
-			timestamp: Date.now(),
-		};
-		stream.push({ type: "done", reason: "stop", message: fallback });
+		// Generator exhaustion without a terminal result is a stream interruption,
+		// not a successful completion. Emitting an error lets GSD classify it as a
+		// transient provider failure instead of advancing auto-mode state.
+		const fallback = makeStreamExhaustedErrorMessage(modelId, lastTextContent);
+		stream.push({ type: "error", reason: "error", error: fallback });
 	} catch (err) {
 		const errorMsg = err instanceof Error ? err.message : String(err);
 		stream.push({

package/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts

@@ -0,0 +1,21 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { makeStreamExhaustedErrorMessage } from "../stream-adapter.ts";
+
+describe("stream-adapter — exhausted stream fallback (#2575)", () => {
+	test("generator exhaustion becomes an error message instead of clean completion", () => {
+		const message = makeStreamExhaustedErrorMessage("claude-sonnet-4-20250514", "partial answer");
+
+		assert.equal(message.stopReason, "error");
+		assert.equal(message.errorMessage, "stream_exhausted_without_result");
+		assert.deepEqual(message.content, [{ type: "text", text: "partial answer" }]);
+	});
+
+	test("generator exhaustion without prior text still exposes a classifiable error", () => {
+		const message = makeStreamExhaustedErrorMessage("claude-sonnet-4-20250514", "");
+
+		assert.equal(message.stopReason, "error");
+		assert.equal(message.errorMessage, "stream_exhausted_without_result");
+		assert.match(String((message.content[0] as any)?.text ?? ""), /Claude Code error: stream_exhausted_without_result/);
+	});
+});

package/src/resources/extensions/get-secrets-from-user.ts

@@ -47,6 +47,12 @@ function shellEscapeSingle(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+function hydrateProcessEnv(key: string, value: string): void {
+	// Make newly collected secrets immediately visible to the current session.
+	// Some extensions read process.env directly and do not reload .env on every call.
+	process.env[key] = value;
+}
+
 async function writeEnvKey(filePath: string, key: string, value: string): Promise<void> {
 	let content = "";
 	try {
@@ -312,6 +318,7 @@ async function applySecrets(
 			try {
 				await writeEnvKey(opts.envFilePath, key, value);
 				applied.push(key);
+				hydrateProcessEnv(key, value);
 			} catch (err: any) {
 				errors.push(`${key}: ${err.message}`);
 			}
@@ -330,6 +337,7 @@ async function applySecrets(
 					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
 				} else {
 					applied.push(key);
+					hydrateProcessEnv(key, value);
 				}
 			} catch (err: any) {
 				errors.push(`${key}: ${err.message}`);

package/src/resources/extensions/gsd/auto/phases.ts

@@ -36,6 +36,15 @@ import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 
+/**
+ * Resolve the base path for milestone reports.
+ * Prefers originalBasePath (project root) over basePath (which may be a worktree).
+ * Exported for testing as _resolveReportBasePath.
+ */
+export function _resolveReportBasePath(s: Pick<AutoSession, "originalBasePath" | "basePath">): string {
+  return s.originalBasePath || s.basePath;
+}
+
 /**
  * Generate and write an HTML milestone report snapshot.
  * Extracted from the milestone-transition block in autoLoop.
@@ -50,13 +59,15 @@ async function generateMilestoneReport(
   const { writeReportSnapshot } = await importExtensionModule<typeof import("../reports.js")>(import.meta.url, "../reports.js");
   const { basename } = await import("node:path");
 
-  const snapData = await loadVisualizerData(s.basePath);
+  const reportBasePath = _resolveReportBasePath(s);
+
+  const snapData = await loadVisualizerData(reportBasePath);
   const completedMs = snapData.milestones.find(
     (m: { id: string }) => m.id === milestoneId,
   );
   const msTitle = completedMs?.title ?? milestoneId;
   const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
-  const projName = basename(s.basePath);
+  const projName = basename(reportBasePath);
   const doneSlices = snapData.milestones.reduce(
     (acc: number, m: { slices: { done: boolean }[] }) =>
       acc + m.slices.filter((sl: { done: boolean }) => sl.done).length,
@@ -67,10 +78,10 @@ async function generateMilestoneReport(
     0,
   );
   const outPath = writeReportSnapshot({
-    basePath: s.basePath,
+    basePath: reportBasePath,
     html: generateHtmlReport(snapData, {
       projectName: projName,
-      projectPath: s.basePath,
+      projectPath: reportBasePath,
       gsdVersion,
       milestoneId,
       indexRelPath: "index.html",
@@ -79,7 +90,7 @@ async function generateMilestoneReport(
     milestoneTitle: msTitle,
     kind: "milestone",
     projectName: projName,
-    projectPath: s.basePath,
+    projectPath: reportBasePath,
     gsdVersion,
     totalCost: snapData.totals?.cost ?? 0,
     totalTokens: snapData.totals?.tokens.total ?? 0,
@@ -250,8 +261,14 @@ export async function runPreDispatch(
         await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
         return { action: "break", reason: "merge-conflict" };
       }
-      // Non-conflict merge errors — log and continue
-      logWarning("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
+      // Non-conflict merge errors — stop auto to avoid advancing with unmerged work
+      logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
+      ctx.ui.notify(
+        `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
+        "error",
+      );
+      await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
+      return { action: "break", reason: "merge-failed" };
     }
 
     // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -344,6 +361,13 @@ export async function runPreDispatch(
             await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
             return { action: "break", reason: "merge-conflict" };
           }
+          logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
+          ctx.ui.notify(
+            `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
+            "error",
+          );
+          await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
+          return { action: "break", reason: "merge-failed" };
         }
 
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -441,6 +465,13 @@ export async function runPreDispatch(
           await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
           return { action: "break", reason: "merge-conflict" };
         }
+        logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
+        ctx.ui.notify(
+          `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
+          "error",
+        );
+        await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
+        return { action: "break", reason: "merge-failed" };
       }
 
       // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -1069,6 +1100,12 @@ export async function runUnitPhase(
   }
 
   if (unitResult.status === "cancelled") {
+    // Provider-error pause: pauseAuto already handled cleanup and scheduled
+    // recovery. Don't hard-stop — just break out of the loop (#2762).
+    if (unitResult.errorContext?.category === "provider") {
+      debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
+      return { action: "break", reason: "provider-pause" };
+    }
     ctx.ui.notify(
       `Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`,
       "warning",

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -626,6 +626,25 @@ export const DISPATCH_RULES: DispatchRule[] = [
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "completing-milestone") return null;
 
+      // Safety guard (#2675): block completion when VALIDATION verdict is
+      // needs-remediation. The state machine treats needs-remediation as
+      // terminal (to prevent validate-milestone loops per #832), but
+      // completing-milestone should NOT proceed — remediation work is needed.
+      const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
+      if (validationFile) {
+        const validationContent = await loadFile(validationFile);
+        if (validationContent) {
+          const verdict = extractVerdict(validationContent);
+          if (verdict === "needs-remediation") {
+            return {
+              action: "stop",
+              reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "needs-remediation". Address the remediation findings and re-run validation, or update the verdict manually.`,
+              level: "warning",
+            };
+          }
+        }
+      }
+
       // Safety guard (#1368): verify all roadmap slices have SUMMARY files.
       const missingSlices = findMissingSummaries(basePath, mid);
       if (missingSlices.length > 0) {
@@ -658,9 +677,14 @@ export const DISPATCH_RULES: DispatchRule[] = [
             if (validationPath) {
               const validationContent = await loadFile(validationPath);
               if (validationContent) {
-                const hasOperationalCheck =
+                // Accept either the structured template format (table with MET/N/A)
+                // or prose evidence patterns the validation agent may emit.
+                const structuredMatch =
                   validationContent.includes("Operational") &&
                   (validationContent.includes("MET") || validationContent.includes("N/A"));
+                const proseMatch =
+                  /[Oo]perational[\s:][^\n]*(?:pass|verified|confirmed|met|complete|true|yes|addressed|covered|n\/a|not\s+applicable)/i.test(validationContent);
+                const hasOperationalCheck = structuredMatch || proseMatch;
                 if (!hasOperationalCheck) {
                   return {
                     action: "stop" as const,

package/src/resources/extensions/gsd/auto-start.ts

@@ -67,6 +67,7 @@ import {
   getDebugLogPath,
 } from "./debug-logger.js";
 import { parseUnitId } from "./unit-id.js";
+import { setLogBasePath } from "./workflow-logger.js";
 import type { AutoSession } from "./auto/session.js";
 import {
   existsSync,
@@ -461,6 +462,7 @@ export async function bootstrapAutoSession(
     s.verbose = verboseMode;
     s.cmdCtx = ctx;
     s.basePath = base;
+    setLogBasePath(base);
     s.unitDispatchCount.clear();
     s.unitRecoveryCount.clear();
     s.lastBudgetAlertLevel = 0;

package/src/resources/extensions/gsd/auto-timers.ts

@@ -15,6 +15,8 @@ import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.j
 import {
   getInFlightToolCount,
   getOldestInFlightToolStart,
+  clearInFlightTools,
+  hasInteractiveToolInFlight,
 } from "./auto-tool-tracking.js";
 import { detectWorkingTreeActivity } from "./auto-supervisor.js";
 import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
@@ -146,7 +148,17 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
 
       // Agent has tool calls currently executing — not idle, just waiting.
       // But only suppress recovery if the tool started recently.
+      let stalledToolDetected = false;
       if (getInFlightToolCount() > 0) {
+        // User-interactive tools (ask_user_questions, secure_env_collect) block
+        // waiting for human input by design — never treat them as stalled (#2676).
+        if (hasInteractiveToolInFlight()) {
+          writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            lastProgressAt: Date.now(),
+            lastProgressKind: "interactive-tool-waiting",
+          });
+          return;
+        }
         const oldestStart = getOldestInFlightToolStart()!;
         const toolAgeMs = Date.now() - oldestStart;
         if (toolAgeMs < idleTimeoutMs) {
@@ -156,6 +168,12 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
           });
           return;
         }
+        // Tool has been in-flight longer than idle timeout — treat as hung.
+        // Clear the stale entries so subsequent ticks don't re-detect them,
+        // and set the flag so the filesystem-activity check below does not
+        // override the stall verdict (#2527).
+        stalledToolDetected = true;
+        clearInFlightTools();
         ctx.ui.notify(
           `Stalled tool detected: a tool has been in-flight for ${Math.round(toolAgeMs / 60000)}min. Treating as hung — attempting idle recovery.`,
           "warning",
@@ -163,7 +181,9 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       }
 
       // Check if the agent is producing work on disk.
-      if (detectWorkingTreeActivity(s.basePath)) {
+      // Skip this when a stalled tool was just detected — filesystem changes
+      // from earlier in the task should not override the stall verdict (#2527).
+      if (!stalledToolDetected && detectWorkingTreeActivity(s.basePath)) {
         writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
           lastProgressAt: Date.now(),
           lastProgressKind: "filesystem-activity",
@@ -180,6 +200,10 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle", buildRecoveryContext());
       if (recovery === "recovered") return;
 
+      // Guard: recoverTimedOutUnit is async — pauseAuto/stopAuto may have
+      // set s.currentUnit = null during the await (#2527).
+      if (!s.currentUnit) return;
+
       writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
         phase: "paused",
       });