gsd-pi 2.72.0 → 2.73.0-dev.1cfd50c

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

@@ -24,6 +24,12 @@ export interface Job {
 	errorText?: string;
 	/** Set by await_job when results are consumed. Suppresses follow-up delivery. */
 	awaited?: boolean;
+	/**
+	 * Handle for the pending follow-up delivery timer (set by deliverResult).
+	 * Stored so suppressFollowUp() can cancel it before the notification fires,
+	 * even when await_job is called after the job has already completed (#3787).
+	 */
+	deliveryTimer?: ReturnType<typeof setTimeout>;
 }
 
 export interface JobManagerOptions {
@@ -170,12 +176,36 @@ export class AsyncJobManager {
 
 	// ── Private ────────────────────────────────────────────────────────────
 
+	/**
+	 * Suppress follow-up notification for a job — cancels any pending delivery
+	 * timer and marks the job as awaited. Safe to call at any time, including
+	 * before or after the job completes (#3787).
+	 */
+	suppressFollowUp(id: string): void {
+		const job = this.jobs.get(id);
+		if (!job) return;
+		job.awaited = true;
+		if (job.deliveryTimer !== undefined) {
+			clearTimeout(job.deliveryTimer);
+			job.deliveryTimer = undefined;
+		}
+	}
+
 	private deliverResult(job: Job): void {
 		if (!this.onJobComplete) return;
-		// Defer delivery by one microtask so await_job's .then() chain runs first
-		// and can set job.awaited = true before onJobComplete checks it (#2762).
+		// Use setTimeout(0) instead of queueMicrotask so the handle is cancellable.
+		// suppressFollowUp() can clear this timer even when await_job is called in
+		// a later LLM turn (after the job already completed). queueMicrotask ran
+		// immediately and could not be cancelled (#2762, #3787).
 		const cb = this.onJobComplete;
-		queueMicrotask(() => cb(job));
+		job.deliveryTimer = setTimeout(() => {
+			job.deliveryTimer = undefined;
+			if (!job.awaited) cb(job);
+		}, 0);
+		// Allow process to exit even if timer is pending
+		if (typeof job.deliveryTimer === "object" && "unref" in job.deliveryTimer) {
+			(job.deliveryTimer as NodeJS.Timeout).unref();
+		}
 	}
 
 	private scheduleEviction(id: string): void {

package/src/resources/extensions/claude-code-cli/partial-builder.ts

@@ -19,6 +19,49 @@ import type {
 import { hasXmlParameterTags, repairToolJson } from "@gsd/pi-ai";
 import type { BetaContentBlock, BetaRawMessageStreamEvent, NonNullableUsage } from "./sdk-types.js";
 
+// ---------------------------------------------------------------------------
+// MCP tool name parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a Claude Code MCP tool name (`mcp__<server>__<tool>`) into its parts.
+ * Returns null for non-prefixed names so callers can fall through unchanged.
+ *
+ * Server names may contain hyphens (`gsd-workflow`); the SDK uses the literal
+ * `__` delimiter between the server name and the tool name.
+ */
+export function parseMcpToolName(name: string): { server: string; tool: string } | null {
+	if (!name.startsWith("mcp__")) return null;
+	const rest = name.slice("mcp__".length);
+	const delim = rest.indexOf("__");
+	if (delim <= 0 || delim === rest.length - 2) return null;
+	return { server: rest.slice(0, delim), tool: rest.slice(delim + 2) };
+}
+
+/**
+ * Build a GSD ToolCall block from a Claude Code SDK tool_use block, stripping
+ * the `mcp__<server>__` prefix from the name so registered extension renderers
+ * (which use the unprefixed canonical names) can match. The original server
+ * name is preserved on the block for diagnostics and rendering.
+ */
+function toolCallFromBlock(
+	id: string,
+	rawName: string,
+	input: Record<string, unknown>,
+): ToolCall {
+	const parsed = parseMcpToolName(rawName);
+	const toolCall: ToolCall = {
+		type: "toolCall",
+		id,
+		name: parsed ? parsed.tool : rawName,
+		arguments: input,
+	};
+	if (parsed) {
+		(toolCall as ToolCall & { mcpServer?: string }).mcpServer = parsed.server;
+	}
+	return toolCall;
+}
+
 // ---------------------------------------------------------------------------
 // Content-block mapping helpers
 // ---------------------------------------------------------------------------
@@ -41,12 +84,7 @@ export function mapContentBlock(
 			} satisfies ThinkingContent;
 
 		case "tool_use":
-			return {
-				type: "toolCall",
-				id: block.id,
-				name: block.name,
-				arguments: block.input,
-			} satisfies ToolCall;
+			return toolCallFromBlock(block.id, block.name, block.input);
 
 		case "server_tool_use":
 			return {
@@ -183,12 +221,7 @@ export class PartialMessageBuilder {
 				}
 				if (block.type === "tool_use") {
 					this.toolJsonAccum.set(streamIndex, "");
-					this.partial.content.push({
-						type: "toolCall",
-						id: block.id,
-						name: block.name,
-						arguments: {},
-					});
+					this.partial.content.push(toolCallFromBlock(block.id, block.name, {}));
 					return { type: "toolcall_start", contentIndex, partial: this.partial };
 				}
 				if (block.type === "server_tool_use") {

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

@@ -187,20 +187,36 @@ function extractMessageText(msg: { role: string; content: unknown }): string {
  * call effectively stateless. This version serialises the complete
  * conversation history (system prompt + all user/assistant turns) so
  * Claude Code has full context for multi-turn continuity.
+ *
+ * History is wrapped in XML-tag structure rather than `[User]`/`[Assistant]`
+ * bracket headers. Bracket headers read to the model as an in-context
+ * demonstration of how turns are delimited, causing it to fabricate fake
+ * user turns in its own output. XML tags read as document structure and
+ * don't get mirrored in free text.
  */
 export function buildPromptFromContext(context: Context): string {
-	const parts: string[] = [];
+	const hasContent = Boolean(context.systemPrompt) || context.messages.some((m) => extractMessageText(m));
+	if (!hasContent) return "";
+
+	const parts: string[] = [
+		"Respond only to the final user message below. " +
+			"Do not emit <user_message>, <assistant_message>, or <prior_system_context> tags in your response.",
+	];
 
 	if (context.systemPrompt) {
-		parts.push(`[System]\n${context.systemPrompt}`);
+		parts.push(`<prior_system_context>\n${context.systemPrompt}\n</prior_system_context>`);
 	}
 
+	const turns: string[] = [];
 	for (const msg of context.messages) {
 		const text = extractMessageText(msg);
 		if (!text) continue;
-
-		const label = msg.role === "user" ? "User" : msg.role === "assistant" ? "Assistant" : "System";
-		parts.push(`[${label}]\n${text}`);
+		const tag =
+			msg.role === "user" ? "user_message" : msg.role === "assistant" ? "assistant_message" : "system_message";
+		turns.push(`<${tag}>\n${text}\n</${tag}>`);
+	}
+	if (turns.length > 0) {
+		parts.push(`<conversation_history>\n${turns.join("\n")}\n</conversation_history>`);
 	}
 
 	return parts.join("\n\n");
@@ -546,15 +562,18 @@ export function makeAbortedMessage(model: string, lastTextContent: string): Assi
 /**
  * Resolve the Claude Code permission mode for the current run.
  *
- * - Auto-mode / headless runs bypass permissions so tool calls don't block
- *   on prompts the user isn't watching.
- * - Interactive runs default to `acceptEdits` so file/bash writes still
- *   land quickly but the SDK retains a permission gate.
- * - `GSD_CLAUDE_CODE_PERMISSION_MODE` forces a specific mode when set.
+ * GSD subagents run underneath a host Claude Code session the user has
+ * already consented to, and their work (edits, shell inspection, MCP calls)
+ * spans the full workflow toolset. Defaulting the inner SDK to
+ * `bypassPermissions` avoids per-tool approval prompts that offer no
+ * meaningful safety beyond what the host session and the subagent prompts
+ * already enforce. `GSD_CLAUDE_CODE_PERMISSION_MODE` lets security-conscious
+ * users opt into a stricter mode (`acceptEdits`, `default`, `plan`).
  *
- * Cross-extension coupling is kept minimal by dynamically importing
- * `isAutoActive` and falling back to the bypass default if the import
- * fails (e.g. in unit tests that load stream-adapter in isolation).
+ * Tradeoff: bypass means a prompt-injection payload read from an untrusted
+ * file could trigger tool calls without a second gate. Accepted for GSD
+ * because the workflow is explicit user intent and the alternative
+ * (#4099) is continuous approval fatigue that blocks real work.
  */
 export async function resolveClaudePermissionMode(
 	env: NodeJS.ProcessEnv = process.env,
@@ -563,17 +582,7 @@ export async function resolveClaudePermissionMode(
 	if (override === "bypassPermissions" || override === "acceptEdits" || override === "default" || override === "plan") {
 		return override;
 	}
-
-	try {
-		const autoMod = (await import("../gsd/auto.js")) as { isAutoActive?: () => boolean };
-		if (typeof autoMod.isAutoActive === "function" && autoMod.isAutoActive()) {
-			return "bypassPermissions";
-		}
-		return "acceptEdits";
-	} catch {
-		// auto.ts unavailable (tests, non-GSD contexts) — stay permissive.
-		return "bypassPermissions";
-	}
+	return "bypassPermissions";
 }
 
 /**
@@ -596,6 +605,21 @@ export function buildSdkOptions(
 	const mcpServers = buildWorkflowMcpServers();
 	const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
 	const disallowedTools = ["AskUserQuestion"];
+	// Pre-authorize the safe built-ins and every registered workflow MCP
+	// server's tools. `acceptEdits` mode (the interactive default) only
+	// auto-approves file edits — Read/Glob/Grep, basic shell inspection, and
+	// every `mcp__gsd-workflow__*` call still surface as "This command
+	// requires approval" and block GSD actions (#4099).
+	const allowedTools = [
+		"Read",
+		"Write",
+		"Edit",
+		"Glob",
+		"Grep",
+		"Bash(ls:*)",
+		"Bash(pwd)",
+		...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
+	];
 	return {
 		pathToClaudeCodeExecutable: getClaudePath(),
 		model: modelId,
@@ -607,6 +631,7 @@ export function buildSdkOptions(
 		settingSources: ["project"],
 		systemPrompt: { type: "preset", preset: "claude_code" },
 		disallowedTools,
+		...(allowedTools.length > 0 ? { allowedTools } : {}),
 		...(mcpServers ? { mcpServers } : {}),
 		betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
 		...extraOptions,

package/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { PartialMessageBuilder } from "../partial-builder.ts";
-import type { BetaRawMessageStreamEvent } from "../sdk-types.ts";
+import { mapContentBlock, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
+import type { BetaContentBlock, BetaRawMessageStreamEvent } from "../sdk-types.ts";
 
 describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 	/**
@@ -148,3 +148,92 @@ describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 		}
 	});
 });
+
+describe("parseMcpToolName", () => {
+	test("splits mcp__<server>__<tool> into parts", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__gsd-workflow__gsd_plan_milestone"),
+			{ server: "gsd-workflow", tool: "gsd_plan_milestone" },
+		);
+	});
+
+	test("preserves server names containing hyphens", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__my-cool-server__do_thing"),
+			{ server: "my-cool-server", tool: "do_thing" },
+		);
+	});
+
+	test("preserves tool names containing underscores", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__srv__a_b_c_d"),
+			{ server: "srv", tool: "a_b_c_d" },
+		);
+	});
+
+	test("returns null for non-prefixed names", () => {
+		assert.equal(parseMcpToolName("Bash"), null);
+		assert.equal(parseMcpToolName("gsd_plan_milestone"), null);
+	});
+
+	test("returns null for malformed prefixes", () => {
+		assert.equal(parseMcpToolName("mcp__"), null);
+		assert.equal(parseMcpToolName("mcp__server"), null);
+		assert.equal(parseMcpToolName("mcp__server__"), null);
+		assert.equal(parseMcpToolName("mcp____tool"), null);
+	});
+});
+
+describe("PartialMessageBuilder — MCP tool name normalization", () => {
+	test("strips mcp__<server>__ prefix on content_block_start", () => {
+		const builder = new PartialMessageBuilder("claude-sonnet-4-20250514");
+		const event = builder.handleEvent({
+			type: "content_block_start",
+			index: 0,
+			content_block: {
+				type: "tool_use",
+				id: "tool_1",
+				name: "mcp__gsd-workflow__gsd_plan_milestone",
+				input: {},
+			},
+		} as BetaRawMessageStreamEvent);
+
+		assert.ok(event, "event should not be null");
+		assert.equal(event!.type, "toolcall_start");
+		if (event!.type === "toolcall_start") {
+			const toolCall = (event.partial.content[event.contentIndex] as any);
+			assert.equal(toolCall.name, "gsd_plan_milestone");
+			assert.equal(toolCall.mcpServer, "gsd-workflow");
+		}
+	});
+
+	test("leaves non-MCP tool names untouched", () => {
+		const builder = new PartialMessageBuilder("claude-sonnet-4-20250514");
+		const event = builder.handleEvent({
+			type: "content_block_start",
+			index: 0,
+			content_block: { type: "tool_use", id: "tool_1", name: "Bash", input: {} },
+		} as BetaRawMessageStreamEvent);
+
+		assert.ok(event);
+		if (event!.type === "toolcall_start") {
+			const toolCall = (event.partial.content[event.contentIndex] as any);
+			assert.equal(toolCall.name, "Bash");
+			assert.equal(toolCall.mcpServer, undefined);
+		}
+	});
+
+	test("mapContentBlock strips MCP prefix on full tool_use blocks", () => {
+		const block: BetaContentBlock = {
+			type: "tool_use",
+			id: "tool_2",
+			name: "mcp__gsd-workflow__gsd_task_complete",
+			input: { taskId: "T001" },
+		};
+		const mapped = mapContentBlock(block) as any;
+		assert.equal(mapped.type, "toolCall");
+		assert.equal(mapped.name, "gsd_task_complete");
+		assert.equal(mapped.mcpServer, "gsd-workflow");
+		assert.deepEqual(mapped.arguments, { taskId: "T001" });
+	});
+});

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

@@ -167,6 +167,98 @@ describe("stream-adapter — full context prompt (#2859)", () => {
 	});
 });
 
+// ---------------------------------------------------------------------------
+// Bug #4102 — transcript fabrication regression tests
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — no transcript fabrication (#4102)", () => {
+	test("buildPromptFromContext never emits forbidden [User]/[Assistant] bracket headers", () => {
+		const context: Context = {
+			systemPrompt: "You are a helpful assistant.",
+			messages: [
+				{ role: "user", content: "First" } as Message,
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "Second" }],
+					api: "anthropic-messages",
+					provider: "claude-code",
+					model: "claude-sonnet-4-20250514",
+					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+					stopReason: "stop",
+					timestamp: Date.now(),
+				} as Message,
+				{ role: "user", content: "Third" } as Message,
+			],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(!prompt.includes("[User]"), "prompt must not include literal [User] bracket header");
+		assert.ok(!prompt.includes("[Assistant]"), "prompt must not include literal [Assistant] bracket header");
+		assert.ok(!prompt.includes("[System]"), "prompt must not include literal [System] bracket header");
+	});
+
+	test("buildPromptFromContext wraps history in XML-tag structure", () => {
+		const context: Context = {
+			systemPrompt: "You are helpful.",
+			messages: [
+				{ role: "user", content: "Hello" } as Message,
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "Hi there" }],
+					api: "anthropic-messages",
+					provider: "claude-code",
+					model: "claude-sonnet-4-20250514",
+					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+					stopReason: "stop",
+					timestamp: Date.now(),
+				} as Message,
+			],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(prompt.includes("<conversation_history>"), "prompt must wrap history in <conversation_history>");
+		assert.ok(prompt.includes("</conversation_history>"), "prompt must close <conversation_history>");
+		assert.ok(prompt.includes("<user_message>\nHello\n</user_message>"), "user turn must use <user_message> tags");
+		assert.ok(prompt.includes("<assistant_message>\nHi there\n</assistant_message>"), "assistant turn must use <assistant_message> tags");
+		assert.ok(prompt.includes("<prior_system_context>\nYou are helpful.\n</prior_system_context>"), "system prompt must use <prior_system_context> tags");
+	});
+
+	test("buildPromptFromContext includes a do-not-echo-tags directive as primary instruction", () => {
+		const context: Context = {
+			messages: [{ role: "user", content: "Anything" } as Message],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(
+			prompt.startsWith("Respond only to the final user message"),
+			"primary directive must lead the prompt",
+		);
+		assert.ok(prompt.includes("Do not emit <user_message>"), "directive must forbid emitting user_message tag");
+		assert.ok(prompt.includes("<assistant_message>"), "directive must mention assistant_message tag");
+	});
+
+	test("buildPromptFromContext omits <conversation_history> when there are no messages but a system prompt", () => {
+		const context: Context = {
+			systemPrompt: "Seed",
+			messages: [],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(prompt.includes("<prior_system_context>"), "system prompt must still render");
+		assert.ok(!prompt.includes("<conversation_history>"), "no history wrapper when messages are empty");
+	});
+
+	test("buildPromptFromContext still returns empty string when context is entirely empty", () => {
+		const context: Context = { messages: [] };
+		const prompt = buildPromptFromContext(context);
+		assert.equal(prompt, "", "empty context must not emit a bare directive");
+	});
+});
+
 describe("stream-adapter — Claude Code external tool results", () => {
 	test("extractToolResultsFromSdkUserMessage maps tool_result content to tool payloads", () => {
 		const message: SDKUserMessage = {
@@ -277,6 +369,16 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
 			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
 			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+			assert.deepEqual(options.allowedTools, [
+				"Read",
+				"Write",
+				"Edit",
+				"Glob",
+				"Grep",
+				"Bash(ls:*)",
+				"Bash(pwd)",
+				"mcp__gsd-workflow__*",
+			]);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
@@ -305,6 +407,16 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const mcpServers = options.mcpServers as Record<string, any>;
 			assert.ok(mcpServers?.["custom-workflow"], "expected custom workflow server config");
 			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+			assert.deepEqual(options.allowedTools, [
+				"Read",
+				"Write",
+				"Edit",
+				"Glob",
+				"Grep",
+				"Bash(ls:*)",
+				"Bash(pwd)",
+				"mcp__custom-workflow__*",
+			]);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;

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

@@ -29,6 +29,69 @@ import {
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { resolveEngine } from "../engine-resolver.js";
+import { logWarning } from "../workflow-logger.js";
+import { gsdRoot } from "../paths.js";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Stuck detection persistence (#3704) ──────────────────────────────────
+// Persist stuck detection state to disk so it survives session restarts.
+// Without this, restarting auto-mode resets all counters, allowing the
+// same blocked unit to burn a full retry budget each session.
+function stuckStatePath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "stuck-state.json");
+}
+
+function loadStuckState(basePath: string): { recentUnits: Array<{ key: string }>; stuckRecoveryAttempts: number } {
+  try {
+    const data = JSON.parse(readFileSync(stuckStatePath(basePath), "utf-8"));
+    return {
+      recentUnits: Array.isArray(data.recentUnits) ? data.recentUnits : [],
+      stuckRecoveryAttempts: typeof data.stuckRecoveryAttempts === "number" ? data.stuckRecoveryAttempts : 0,
+    };
+  } catch (err) {
+    debugLog("autoLoop", { phase: "load-stuck-state-failed", error: err instanceof Error ? err.message : String(err) });
+    return { recentUnits: [], stuckRecoveryAttempts: 0 };
+  }
+}
+
+function saveStuckState(basePath: string, state: LoopState): void {
+  try {
+    const filePath = stuckStatePath(basePath);
+    mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+    writeFileSync(filePath, JSON.stringify({
+      recentUnits: state.recentUnits.slice(-20), // keep last 20 entries
+      stuckRecoveryAttempts: state.stuckRecoveryAttempts,
+      updatedAt: new Date().toISOString(),
+    }) + "\n");
+  } catch (err) {
+    debugLog("autoLoop", { phase: "save-stuck-state-failed", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+// ── Memory pressure monitoring (#3331) ──────────────────────────────────
+// Check heap usage every N iterations and trigger graceful shutdown before
+// the OS OOM killer sends SIGKILL. The threshold is 90% of the V8 heap
+// limit (--max-old-space-size or default ~1.5-4GB depending on platform).
+const MEMORY_CHECK_INTERVAL = 5; // check every 5 iterations
+const MEMORY_PRESSURE_THRESHOLD = 0.85; // 85% of heap limit
+
+function checkMemoryPressure(): { pressured: boolean; heapMB: number; limitMB: number; pct: number } {
+  const mem = process.memoryUsage();
+  // v8.getHeapStatistics() gives heap_size_limit but requires import
+  // Use a conservative estimate: RSS > 3GB is danger zone on most systems
+  const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
+  const rssMB = Math.round(mem.rss / 1024 / 1024);
+  // Try to get the actual V8 heap limit
+  let limitMB = 4096; // conservative default
+  try {
+    const v8 = require("node:v8");
+    const stats = v8.getHeapStatistics();
+    limitMB = Math.round(stats.heap_size_limit / 1024 / 1024);
+  } catch { limitMB = 4096; /* v8 stats unavailable — use conservative default */ }
+  const pct = heapMB / limitMB;
+  return { pressured: pct > MEMORY_PRESSURE_THRESHOLD, heapMB, limitMB, pct };
+}
 
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
@@ -46,7 +109,13 @@ export async function autoLoop(
 ): Promise<void> {
   debugLog("autoLoop", { phase: "enter" });
   let iteration = 0;
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
+  // Load persisted stuck state so counters survive session restarts (#3704)
+  const persisted = loadStuckState(s.basePath);
+  const loopState: LoopState = {
+    recentUnits: persisted.recentUnits,
+    stuckRecoveryAttempts: persisted.stuckRecoveryAttempts,
+    consecutiveFinalizeTimeouts: 0,
+  };
   let consecutiveErrors = 0;
   let consecutiveCooldowns = 0;
   const recentErrorMessages: string[] = [];
@@ -74,6 +143,24 @@ export async function autoLoop(
       break;
     }
 
+    // ── Memory pressure check (#3331) ──
+    // Graceful shutdown before OOM killer sends SIGKILL.
+    if (iteration % MEMORY_CHECK_INTERVAL === 0) {
+      const mem = checkMemoryPressure();
+      debugLog("autoLoop", { phase: "memory-check", ...mem });
+      if (mem.pressured) {
+        logWarning("dispatch", `Memory pressure: ${mem.heapMB}MB / ${mem.limitMB}MB (${Math.round(mem.pct * 100)}%) — stopping auto-mode to prevent OOM kill`);
+        await deps.stopAuto(
+          ctx,
+          pi,
+          `Memory pressure: heap at ${mem.heapMB}MB / ${mem.limitMB}MB (${Math.round(mem.pct * 100)}%). ` +
+          `Stopping gracefully to prevent OOM kill after ${iteration} iterations. ` +
+          `Resume with /gsd auto to continue from where you left off.`,
+        );
+        break;
+      }
+    }
+
     if (!s.cmdCtx) {
       debugLog("autoLoop", { phase: "exit", reason: "no-cmdCtx" });
       break;
@@ -207,6 +294,7 @@ export async function autoLoop(
         consecutiveCooldowns = 0;
         recentErrorMessages.length = 0;
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
+        saveStuckState(s.basePath, loopState); // persist across session restarts (#3704)
         debugLog("autoLoop", { phase: "iteration-complete", iteration });
 
         if (reconcileResult.outcome === "milestone-complete") {

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -25,6 +25,7 @@ import {
   buildTaskFileName,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
+import { rebuildState } from "./doctor.js";
 import { parseUnitId } from "./unit-id.js";
 import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
 import {
@@ -367,6 +368,12 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       }
     });
 
+    // Keep the on-disk STATE.md aligned with the live derived state after
+    // ordinary unit completion, before any worktree state is synced back.
+    await runSafely("postUnit", "state-rebuild", async () => {
+      await rebuildState(s.basePath);
+    });
+
     // Sync worktree state back to project root (skipped for lightweight sidecars)
     if (!opts?.skipWorktreeSync && s.originalBasePath && s.originalBasePath !== s.basePath) {
       await runSafely("postUnit", "worktree-sync", () => {

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

@@ -272,6 +272,16 @@ export function verifyExpectedArtifact(
     if (!isValidationTerminal(validationContent)) return false;
   }
 
+  if (unitType === "plan-milestone") {
+    try {
+      const roadmap = parseLegacyRoadmap(readFileSync(absPath, "utf-8"));
+      if (roadmap.slices.length === 0) return false;
+    } catch (err) {
+      logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }
+  }
+
   // plan-slice must produce a plan with actual task entries, not just a scaffold.
   // The plan file may exist from a prior discussion/context step with only headings
   // but no tasks. Without this check the artifact is considered "complete" and the