gsd-pi 2.71.0 → 2.72.0-dev.3118184

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

@@ -5,6 +5,10 @@ import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import {
 	makeStreamExhaustedErrorMessage,
+	getResultErrorMessage,
+	makeAbortedMessage,
+	mergePendingToolCalls,
+	resolveClaudePermissionMode,
 	buildPromptFromContext,
 	buildSdkOptions,
 	createClaudeCodeElicitationHandler,
@@ -15,7 +19,7 @@ import {
 	parseClaudeLookupOutput,
 	roundResultToElicitationContent,
 } from "../stream-adapter.ts";
-import type { Context, Message } from "@gsd/pi-ai";
+import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
 import type { SDKUserMessage } from "../sdk-types.ts";
 
 // ---------------------------------------------------------------------------
@@ -40,6 +44,57 @@ describe("stream-adapter — exhausted stream fallback (#2575)", () => {
 	});
 });
 
+describe("stream-adapter — result error text (#3776)", () => {
+	test("prefers SDK result text when an error arrives with subtype success", () => {
+		const message = getResultErrorMessage({
+			type: "result",
+			subtype: "success",
+			uuid: "uuid-1",
+			session_id: "session-1",
+			duration_ms: 1,
+			duration_api_ms: 1,
+			is_error: true,
+			num_turns: 1,
+			result: 'API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}',
+			stop_reason: null,
+			total_cost_usd: 0,
+			usage: {
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_read_input_tokens: 0,
+				cache_creation_input_tokens: 0,
+			},
+		});
+
+		assert.match(message, /API Error: 529/);
+		assert.doesNotMatch(message, /^success$/i);
+	});
+
+	test("falls back to a stable classifier when success errors have no text", () => {
+		const message = getResultErrorMessage({
+			type: "result",
+			subtype: "success",
+			uuid: "uuid-2",
+			session_id: "session-2",
+			duration_ms: 1,
+			duration_api_ms: 1,
+			is_error: true,
+			num_turns: 1,
+			result: "   ",
+			stop_reason: null,
+			total_cost_usd: 0,
+			usage: {
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_read_input_tokens: 0,
+				cache_creation_input_tokens: 0,
+			},
+		});
+
+		assert.equal(message, "claude_code_request_failed");
+	});
+});
+
 // ---------------------------------------------------------------------------
 // Bug #2859 — stateless provider regression tests
 // ---------------------------------------------------------------------------
@@ -112,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 = {
@@ -222,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;
@@ -250,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;
@@ -362,7 +529,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			delete process.env.GSD_WORKFLOW_MCP_ARGS;
 			delete process.env.GSD_WORKFLOW_MCP_ENV;
 			delete process.env.GSD_WORKFLOW_MCP_CWD;
-			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", { onElicitation });
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { onElicitation });
 			assert.equal(options.onElicitation, onElicitation);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
@@ -598,9 +765,9 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 			requestedSchema: {
 				type: "object" as const,
 				properties: {
-					TEST_PASSWORD: {
+					TEST_SECURE_FIELD: {
 						type: "string",
-						title: "TEST_PASSWORD",
+						title: "TEST_SECURE_FIELD",
 						description: "Format: Your secure testing password\nLeave empty to skip.",
 					},
 				},
@@ -611,7 +778,7 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 		const handler = createClaudeCodeElicitationHandler({
 			input: async (_title: string, _placeholder?: string, opts?: { secure?: boolean }) => {
 				inputCalls.push({ opts });
-				return "super-secret";
+				return "example-secure-input";
 			},
 		} as any);
 		assert.ok(handler);
@@ -620,7 +787,7 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 		assert.deepEqual(result, {
 			action: "accept",
 			content: {
-				TEST_PASSWORD: "super-secret",
+				TEST_SECURE_FIELD: "example-secure-input",
 			},
 		});
 		assert.equal(inputCalls.length, 1);
@@ -628,6 +795,134 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 	});
 });
 
+// ---------------------------------------------------------------------------
+// F2 — abort vs stream-exhausted classification
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — abort classification (F2)", () => {
+	test("makeAbortedMessage sets stopReason to 'aborted', not 'error'", () => {
+		const message = makeAbortedMessage("claude-sonnet-4-6", "");
+		assert.equal(message.stopReason, "aborted");
+		assert.equal(message.errorMessage, undefined);
+	});
+
+	test("makeAbortedMessage preserves last-seen text content", () => {
+		const message = makeAbortedMessage("claude-sonnet-4-6", "partial mid-stream text");
+		assert.deepEqual(message.content, [{ type: "text", text: "partial mid-stream text" }]);
+	});
+
+	test("aborted message is distinguishable from stream-exhausted error", () => {
+		const aborted = makeAbortedMessage("claude-sonnet-4-6", "");
+		const exhausted = makeStreamExhaustedErrorMessage("claude-sonnet-4-6", "");
+		assert.notEqual(aborted.stopReason, exhausted.stopReason);
+		assert.equal(exhausted.errorMessage, "stream_exhausted_without_result");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// F3 — final-turn tool calls not dropped
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — final-turn tool-call merge (F3)", () => {
+	function toolCall(id: string, name = "bash"): AssistantMessage["content"][number] {
+		return { type: "toolCall", id, name, arguments: {} };
+	}
+
+	test("mergePendingToolCalls appends tool calls not already in intermediate", () => {
+		const intermediate: AssistantMessage["content"] = [toolCall("tool-1")];
+		const pending: AssistantMessage["content"] = [
+			toolCall("tool-2"),
+			{ type: "text", text: "trailing text" },
+		];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 2);
+		assert.equal((merged[0] as any).id, "tool-1");
+		assert.equal((merged[1] as any).id, "tool-2");
+	});
+
+	test("mergePendingToolCalls is idempotent across duplicate ids", () => {
+		const intermediate: AssistantMessage["content"] = [toolCall("tool-1")];
+		const pending: AssistantMessage["content"] = [toolCall("tool-1"), toolCall("tool-2")];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 2);
+		assert.deepEqual(
+			merged.map((b) => (b as any).id),
+			["tool-1", "tool-2"],
+		);
+	});
+
+	test("mergePendingToolCalls ignores non-toolCall blocks from pending", () => {
+		const intermediate: AssistantMessage["content"] = [];
+		const pending: AssistantMessage["content"] = [
+			{ type: "text", text: "hello" },
+			{ type: "thinking", thinking: "pondering" },
+			toolCall("tool-1"),
+		];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 1);
+		assert.equal((merged[0] as any).id, "tool-1");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// F10 — permission mode is configurable
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — permission mode (F10)", () => {
+	// Earlier tests in this file set GSD_WORKFLOW_MCP_* env vars and restore
+	// them by reassigning from `prev.*`. When `prev.*` was undefined, node
+	// coerces the assignment to the literal string "undefined", which then
+	// fails JSON.parse inside buildWorkflowMcpServers. Clear the relevant
+	// slots before each permission-mode test so buildSdkOptions doesn't throw.
+	function clearWorkflowMcpEnv(): void {
+		for (const key of [
+			"GSD_WORKFLOW_MCP_COMMAND",
+			"GSD_WORKFLOW_MCP_NAME",
+			"GSD_WORKFLOW_MCP_ARGS",
+			"GSD_WORKFLOW_MCP_ENV",
+			"GSD_WORKFLOW_MCP_CWD",
+		]) {
+			if (process.env[key] === undefined || process.env[key] === "undefined") {
+				delete process.env[key];
+			}
+		}
+	}
+
+	test("buildSdkOptions defaults to bypassPermissions for backwards compatibility", () => {
+		clearWorkflowMcpEnv();
+		const opts = buildSdkOptions("claude-sonnet-4-6", "test");
+		assert.equal(opts.permissionMode, "bypassPermissions");
+		assert.equal(opts.allowDangerouslySkipPermissions, true);
+	});
+
+	test("buildSdkOptions respects explicit acceptEdits override", () => {
+		clearWorkflowMcpEnv();
+		const opts = buildSdkOptions("claude-sonnet-4-6", "test", { permissionMode: "acceptEdits" });
+		assert.equal(opts.permissionMode, "acceptEdits");
+		assert.equal(
+			opts.allowDangerouslySkipPermissions,
+			false,
+			"allowDangerouslySkipPermissions must be false for non-bypass modes",
+		);
+	});
+
+	test("resolveClaudePermissionMode honours the GSD_CLAUDE_CODE_PERMISSION_MODE env override", async () => {
+		const env = { GSD_CLAUDE_CODE_PERMISSION_MODE: "acceptEdits" } as NodeJS.ProcessEnv;
+		const mode = await resolveClaudePermissionMode(env);
+		assert.equal(mode, "acceptEdits");
+	});
+
+	test("resolveClaudePermissionMode rejects unknown override values (fallback path)", async () => {
+		const env = { GSD_CLAUDE_CODE_PERMISSION_MODE: "nonsense" } as NodeJS.ProcessEnv;
+		const mode = await resolveClaudePermissionMode(env);
+		// Unknown override falls back to auto-detect → either bypass or acceptEdits
+		assert.ok(
+			mode === "bypassPermissions" || mode === "acceptEdits",
+			`expected bypass or acceptEdits, got ${mode}`,
+		);
+	});
+});
+
 describe("stream-adapter — Windows Claude path lookup (#3770)", () => {
 	test("getClaudeLookupCommand uses where on Windows", () => {
 		assert.equal(getClaudeLookupCommand("win32"), "where claude");

package/src/resources/extensions/gsd/auto/infra-errors.ts

@@ -46,3 +46,41 @@ export function isInfrastructureError(err: unknown): string | null {
   if (msg.includes("database disk image is malformed")) return "SQLITE_CORRUPT";
   return null;
 }
+
+/**
+ * Default wait duration when a cooldown error is detected but no specific
+ * expiry is available from AuthStorage (e.g., error propagated across
+ * process boundary without structured backoff data).
+ */
+export const COOLDOWN_FALLBACK_WAIT_MS = 35_000; // 35s — slightly longer than the 30s rate-limit backoff
+
+/** Maximum consecutive cooldown retries before the auto-loop gives up. */
+export const MAX_COOLDOWN_RETRIES = 5;
+
+/**
+ * Detect whether an error is a transient credential cooldown that should
+ * be waited out rather than counted as a consecutive failure.
+ *
+ * Prefers the structured `CredentialCooldownError` (code: AUTH_COOLDOWN)
+ * thrown by sdk.ts. Falls back to message matching for errors that
+ * propagated across process boundaries without the typed class.
+ */
+export function isTransientCooldownError(err: unknown): boolean {
+  if (err && typeof err === "object" && (err as Record<string, unknown>).code === "AUTH_COOLDOWN") {
+    return true;
+  }
+  // Fallback: message match for cross-process error propagation
+  const msg = err instanceof Error ? err.message : String(err);
+  return /in a cooldown window/i.test(msg);
+}
+
+/**
+ * Extract retryAfterMs from a CredentialCooldownError, if available.
+ * Returns undefined for unstructured errors or when no retry hint exists.
+ */
+export function getCooldownRetryAfterMs(err: unknown): number | undefined {
+  if (err && typeof err === "object" && (err as Record<string, unknown>).code === "AUTH_COOLDOWN") {
+    return (err as Record<string, unknown>).retryAfterMs as number | undefined;
+  }
+  return undefined;
+}

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

@@ -211,6 +211,8 @@ export interface LoopDeps {
     verbose: boolean,
     startModel: { provider: string; id: string } | null,
     retryContext?: { isRetry: boolean; previousTier?: string },
+    isAutoMode?: boolean,
+    sessionModelOverride?: { provider: string; id: string } | null,
   ) => Promise<{
     routing: { tier: string; modelDowngraded: boolean } | null;
     appliedModel: { provider: string; id: string } | null;

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

@@ -27,8 +27,71 @@ import {
   runFinalize,
 } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
-import { isInfrastructureError } from "./infra-errors.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,8 +109,15 @@ 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[] = [];
 
   while (s.active) {
@@ -73,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;
@@ -203,8 +291,10 @@ export async function autoLoop(
 
         deps.clearUnitTimeout();
         consecutiveErrors = 0;
+        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") {
@@ -265,6 +355,7 @@ export async function autoLoop(
       if (finalizeResult.action === "continue") continue;
 
       consecutiveErrors = 0; // Iteration completed successfully
+      consecutiveCooldowns = 0;
       recentErrorMessages.length = 0;
       deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
       debugLog("autoLoop", { phase: "iteration-complete", iteration });
@@ -300,6 +391,47 @@ export async function autoLoop(
         break;
       }
 
+      // ── Credential cooldown: wait and retry with bounded budget ──
+      // A 429 triggers a 30s credential backoff in AuthStorage. If the SDK's
+      // getApiKey() retries couldn't outlast the window, the error surfaces
+      // here. Wait for the cooldown to clear rather than counting it as a
+      // consecutive failure — but cap retries so we don't spin for hours
+      // on persistent quota exhaustion.
+      if (isTransientCooldownError(loopErr)) {
+        consecutiveCooldowns++;
+        const retryAfterMs = getCooldownRetryAfterMs(loopErr);
+        debugLog("autoLoop", {
+          phase: "cooldown-wait",
+          iteration,
+          consecutiveCooldowns,
+          retryAfterMs,
+          error: msg,
+        });
+
+        if (consecutiveCooldowns > MAX_COOLDOWN_RETRIES) {
+          ctx.ui.notify(
+            `Auto-mode stopped: ${consecutiveCooldowns} consecutive credential cooldowns — rate limit or quota may be persistently exhausted.`,
+            "error",
+          );
+          await deps.stopAuto(
+            ctx,
+            pi,
+            `${consecutiveCooldowns} consecutive credential cooldowns exceeded retry budget`,
+          );
+          break;
+        }
+
+        const waitMs = (retryAfterMs !== undefined && retryAfterMs > 0 && retryAfterMs <= 60_000)
+          ? retryAfterMs + 500 // Use structured hint + small buffer
+          : COOLDOWN_FALLBACK_WAIT_MS;
+        ctx.ui.notify(
+          `Credentials in cooldown (${consecutiveCooldowns}/${MAX_COOLDOWN_RETRIES}) — waiting ${Math.round(waitMs / 1000)}s before retrying.`,
+          "warning",
+        );
+        await new Promise(resolve => setTimeout(resolve, waitMs));
+        continue; // Retry iteration without incrementing consecutiveErrors
+      }
+
       consecutiveErrors++;
       recentErrorMessages.push(msg.length > 120 ? msg.slice(0, 120) + "..." : msg);
       debugLog("autoLoop", {

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

@@ -27,6 +27,7 @@ import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
 import { PROJECT_FILES } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
+import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
 import { join, basename, dirname, parse as parsePath } from "node:path";
 import { existsSync, cpSync, readdirSync } from "node:fs";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -1068,6 +1069,7 @@ export async function runUnitPhase(
   const previousTier = s.currentUnitRouting?.tier;
 
   s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
+  setCurrentPhase(unitType);
   s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
   const unitStartSeq = ic.nextSeq();
   deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
@@ -1183,6 +1185,8 @@ export async function runUnitPhase(
     s.verbose,
     s.autoModeStartModel,
     sidecarItem ? undefined : { isRetry, previousTier },
+    undefined,
+    s.manualSessionModelOverride,
   );
   s.currentUnitRouting =
     modelResult.routing as AutoSession["currentUnitRouting"];
@@ -1527,6 +1531,7 @@ export async function runFinalize(
     // Detach session from the timed-out unit so late async completions
     // cannot mutate state for the next unit (#3757).
     s.currentUnit = null;
+    clearCurrentPhase();
     loopState.consecutiveFinalizeTimeouts++;
     debugLog("autoLoop", {
       phase: "pre-verification-timeout",
@@ -1624,6 +1629,7 @@ export async function runFinalize(
     // Detach session from the timed-out unit so late async completions
     // cannot mutate state for the next unit (#3757).
     s.currentUnit = null;
+    clearCurrentPhase();
     loopState.consecutiveFinalizeTimeouts++;
     debugLog("autoLoop", {
       phase: "post-verification-timeout",