gsd-pi 2.82.0 → 3.0.0-dev.04f5ccf82

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

@@ -28,6 +28,8 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
+import { loadProjectGSDPreferences } from "../gsd/preferences.js";
+import { discoverMcpServerNames, computeMcpDisallowedTools } from "../gsd/mcp-filter.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
 import type {
 	SDKAssistantMessage,
@@ -249,8 +251,8 @@ export function normalizeClaudePathForSdk(
 	bundledCliPath: string | null = resolveBundledClaudeCliPath(),
 ): string {
 	if (platform !== "win32") return resolvedPath;
-	if (/\.exe$/i.test(resolvedPath)) return resolvedPath;
-	if (bundledCliPath) return bundledCliPath;
+	if (/\.exe$/i.test(resolvedPath)) return resolvedPath.replaceAll("\\", "/");
+	if (bundledCliPath) return bundledCliPath.replaceAll("\\", "/");
 	return resolvedPath;
 }
 
@@ -314,6 +316,21 @@ export function buildPromptFromContext(context: Context): string {
 			"Do not emit <user_message>, <assistant_message>, or <prior_system_context> tags in your response.",
 	];
 
+	// The prior system context lists pi-native tool names (lowercase: bash, read, gsd_exec, etc.)
+	// but this process runs inside Claude Code where tool names differ. Inject a remapping note
+	// before the prior context so the model uses correct names regardless of what the prior
+	// context describes.
+	parts.push(
+		"<tool_context>\n" +
+			"You are running inside Claude Code. Use these exact tool names — do not use lowercase or pi-native names:\n" +
+			"- Shell commands: 'Bash' (not 'bash')\n" +
+			"- File operations: 'Read', 'Write', 'Edit', 'Glob', 'Grep' (PascalCase, not lowercase)\n" +
+			"- GSD workflow tools (gsd_exec, gsd_slice_complete, gsd_task_complete, gsd_plan_slice, etc.) " +
+			"are MCP tools — call them as mcp__gsd-workflow__<tool_name> " +
+			"(e.g. mcp__gsd-workflow__gsd_exec, mcp__gsd-workflow__gsd_slice_complete)\n" +
+			"</tool_context>",
+	);
+
 	if (context.systemPrompt) {
 		parts.push(`<prior_system_context>\n${context.systemPrompt}\n</prior_system_context>`);
 	}
@@ -426,7 +443,7 @@ function makeErrorMessage(model: string, errorMsg: string): AssistantMessage {
 
 export function isClaudeCodeAbortErrorMessage(message: string | undefined | null): boolean {
 	if (!message) return false;
-	return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+	return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user|aborterror)\b/i.test(message);
 }
 
 function isBareClaudeCodeAbortErrorMessage(message: string | undefined | null): boolean {
@@ -1317,13 +1334,42 @@ export function buildSdkOptions(
 	const sdkCwd = typeof cwd === "string" && cwd.trim().length > 0 ? cwd : process.cwd();
 	const mcpServers = buildWorkflowMcpServers(sdkCwd);
 	const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
+
+	const preferences = loadProjectGSDPreferences(sdkCwd);
+	const mcpConfig = preferences?.preferences.claude_code_mcp;
+	const workflowServerName = mcpServers ? Object.keys(mcpServers)[0] : undefined;
+
+	// Always discover project MCPs — needed for both duplicate detection and filtering.
+	const discovered = discoverMcpServerNames(sdkCwd);
+
+	// If the workflow MCP is already declared in the project's .mcp.json or
+	// .claude/settings.json, do not inject it again via mcpServers. Passing the
+	// same server name from two sources causes a duplicate registration conflict
+	// that prevents the MCP server from loading (tools become unavailable).
+	const workflowAlreadyInProject = workflowServerName !== undefined && discovered.includes(workflowServerName);
+	let filteredMcpServers = workflowAlreadyInProject ? undefined : mcpServers;
+	let extraDisallowedTools: string[] = [];
+	let workflowExplicitlyBlocked = false;
+
+	if (mcpConfig) {
+		extraDisallowedTools = computeMcpDisallowedTools(modelId, mcpConfig, discovered, workflowServerName);
+		if (workflowServerName && extraDisallowedTools.includes(`mcp__${workflowServerName}__*`)) {
+			filteredMcpServers = undefined;
+			workflowExplicitlyBlocked = true;
+		}
+	}
+
 	// Globally unblock the tools GSD expects Claude Code to run. When the
 	// workflow MCP server is available, prefer its `ask_user_questions` tool over
 	// Claude Code's native `AskUserQuestion`; the MCP path carries stable IDs and
 	// routes responses through the GSD elicitation bridge.
 	// Opt back into gated mode with GSD_CLAUDE_CODE_PERMISSION_MODE=acceptEdits.
-	const workflowMcpTools = mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : [];
-	const disallowedTools: string[] = workflowMcpTools.length > 0 ? ["AskUserQuestion"] : [];
+	// Include the workflow pattern in allowedTools whether the server is GSD-injected
+	// or declared in the project config — but not if explicitly blocked by user prefs.
+	const workflowMcpTools = filteredMcpServers
+		? Object.keys(filteredMcpServers).map((serverName) => `mcp__${serverName}__*`)
+		: (!workflowExplicitlyBlocked && workflowServerName ? [`mcp__${workflowServerName}__*`] : []);
+	const disallowedTools: string[] = [...(workflowMcpTools.length > 0 ? ["AskUserQuestion"] : []), ...extraDisallowedTools];
 	const allowedTools = [
 		"Read",
 		"Write",
@@ -1363,7 +1409,7 @@ export function buildSdkOptions(
 		systemPrompt: { type: "preset", preset: "claude_code" },
 		disallowedTools,
 		...(allowedTools.length > 0 ? { allowedTools } : {}),
-		...(mcpServers ? { mcpServers } : {}),
+		...(filteredMcpServers ? { mcpServers: filteredMcpServers } : {}),
 		betas: (modelId.includes("sonnet") || modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) ? ["context-1m-2025-08-07"] : [],
 		...(thinkingConfig ?? {}),
 		...(effort ? { effort } : {}),

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

@@ -1,7 +1,24 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { mapContentBlock, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
-import type { BetaContentBlock, BetaRawMessageStreamEvent } from "../sdk-types.ts";
+import { mapContentBlock, mapUsage, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
+import type { BetaContentBlock, BetaRawMessageStreamEvent, NonNullableUsage } from "../sdk-types.ts";
+
+describe("mapUsage", () => {
+	test("excludes cumulative cache reads from context-sized totalTokens (#5243)", () => {
+		const usage: NonNullableUsage = {
+			input_tokens: 150_000,
+			output_tokens: 2_000,
+			cache_read_input_tokens: 900_000,
+			cache_creation_input_tokens: 3_000,
+		};
+
+		const mapped = mapUsage(usage, 1.23);
+
+		assert.equal(mapped.cacheRead, 900_000);
+		assert.equal(mapped.totalTokens, 155_000);
+		assert.equal(mapped.cost.total, 1.23);
+	});
+});
 
 describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 	/**

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

@@ -54,6 +54,8 @@ const WORKFLOW_MCP_ENV_KEYS = [
 	"GSD_WORKFLOW_MCP_ARGS",
 	"GSD_WORKFLOW_MCP_ENV",
 	"GSD_WORKFLOW_MCP_CWD",
+	"GSD_PROJECT_ROOT",
+	"GSD_WORKFLOW_PROJECT_ROOT",
 ] as const;
 
 type WorkflowMcpEnvKey = (typeof WORKFLOW_MCP_ENV_KEYS)[number];
@@ -64,6 +66,9 @@ function setWorkflowMcpEnv(
 	const prev: Partial<Record<WorkflowMcpEnvKey, string | undefined>> = {};
 	for (const key of WORKFLOW_MCP_ENV_KEYS) {
 		prev[key] = process.env[key];
+		// Clear all managed keys so tests run in a clean env state.
+		// Keys present in `values` are set to the desired test value below.
+		delete process.env[key];
 	}
 	for (const [key, value] of Object.entries(values)) {
 		process.env[key] = value;
@@ -978,6 +983,39 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
+	test("buildSdkOptions does not inject workflow MCP when already declared in project .mcp.json (avoids duplicate registration)", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const projectDir = mkdtempSync(join(tmpdir(), "claude-mcp-dup-"));
+		try {
+			// Simulate a project that already has gsd-workflow in its .mcp.json
+			writeFileSync(
+				join(projectDir, ".mcp.json"),
+				JSON.stringify({ mcpServers: { "gsd-workflow": { command: "node", args: ["old-cli.js"] }, "other-mcp": { command: "npx", args: ["other"] } } }),
+			);
+			process.chdir(projectDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
+			// Should NOT inject gsd-workflow via mcpServers (project already has it)
+			assert.equal(options.mcpServers, undefined, "mcpServers should be omitted when workflow already in .mcp.json");
+			// But allowedTools should still include the workflow pattern
+			const allowedTools = options.allowedTools as string[];
+			assert.ok(allowedTools.includes("mcp__gsd-workflow__*"), "allowedTools must include workflow pattern even when not injected");
+			// AskUserQuestion should be disallowed (workflow is available via project config)
+			const disallowedTools = options.disallowedTools as string[];
+			assert.ok(disallowedTools.includes("AskUserQuestion"), "AskUserQuestion should be suppressed when workflow is available");
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(projectDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
 	test("buildSdkOptions preserves runtime callbacks such as onElicitation", () => {
 		const restore = setWorkflowMcpEnv({});
 		const onElicitation = async () => ({ action: "decline" as const });
@@ -1258,9 +1296,18 @@ describe("stream-adapter — abort classification (F2)", () => {
 	test("recognizes Claude Code SDK abort exceptions", () => {
 		assert.equal(isClaudeCodeAbortErrorMessage("Claude Code process aborted by user"), true);
 		assert.equal(isClaudeCodeAbortErrorMessage("Request aborted by user"), true);
+		assert.equal(isClaudeCodeAbortErrorMessage("AbortError: The operation was aborted"), true);
 		assert.equal(isClaudeCodeAbortErrorMessage("rate limit exceeded"), false);
 	});
 
+	test("does not misclassify non-user abort contexts", () => {
+		assert.equal(isClaudeCodeAbortErrorMessage("Job aborted due to timeout"), false);
+		assert.equal(isClaudeCodeAbortErrorMessage("Operation aborted: disk full"), false);
+		assert.equal(isClaudeCodeAbortErrorMessage("aborted by system cleanup"), false);
+		assert.equal(isClaudeCodeAbortErrorMessage("Database transaction aborted due to constraint violation"), false);
+		assert.equal(isClaudeCodeAbortErrorMessage("Connection aborted unexpectedly"), false);
+	});
+
 	test("makeAbortedMessage sets stopReason to 'aborted', not 'error'", () => {
 		const message = makeAbortedMessage("claude-sonnet-4-6", "");
 		assert.equal(message.stopReason, "aborted");
@@ -1459,8 +1506,8 @@ describe("stream-adapter — Windows Claude path lookup (#3770)", () => {
 	test("normalizeClaudePathForSdk swaps Windows shim paths to bundled cli.js", () => {
 		const shimPath = "C:\\Users\\djeff\\AppData\\Roaming\\npm\\claude";
 		const bundled = "C:\\repo\\node_modules\\@anthropic-ai\\claude-agent-sdk\\cli.js";
-		assert.equal(normalizeClaudePathForSdk(shimPath, "win32", bundled), bundled);
-		assert.equal(normalizeClaudePathForSdk("C:\\Program Files\\Claude\\claude.exe", "win32", bundled), "C:\\Program Files\\Claude\\claude.exe");
+		assert.equal(normalizeClaudePathForSdk(shimPath, "win32", bundled), "C:/repo/node_modules/@anthropic-ai/claude-agent-sdk/cli.js");
+		assert.equal(normalizeClaudePathForSdk("C:\\Program Files\\Claude\\claude.exe", "win32", bundled), "C:/Program Files/Claude/claude.exe");
 	});
 
 	test("resolveBundledClaudeCliPath returns a .js path when SDK package is present", () => {

package/src/resources/extensions/cmux/index.ts

@@ -374,6 +374,12 @@ export class CmuxClient {
     const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);
     return stdout !== null;
   }
+
+  // Send Ctrl-C (ETX) to a surface to interrupt the running command.
+  async sendInterrupt(surfaceId: string): Promise<boolean> {
+    const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, "\x03"]);
+    return stdout !== null;
+  }
 }
 
 export function syncCmuxSidebar(preferences: CmuxPreferences | undefined, state: CmuxState): void {

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

@@ -2,27 +2,34 @@
 // File Purpose: Auto Orchestration module interfaces and ADR-015 invariant adapter contracts.
 
 import type { GSDState } from "../types.js";
+import type { MinimalModelRegistry } from "../context-budget.js";
+import type { AutoSession } from "./session.js";
 
 export interface AutoSessionContext {
   basePath: string;
   trigger: "guided-flow" | "resume" | "auto-loop" | "manual";
 }
 
+export interface UnitRef {
+  unitType: string;
+  unitId: string;
+}
+
 export interface AutoStatus {
   phase: "idle" | "running" | "paused" | "stopped" | "error";
-  activeUnit?: {
-    unitType: string;
-    unitId: string;
-  };
+  activeUnit?: UnitRef;
   lastTransitionAt?: number;
   transitionCount: number;
 }
 
-export interface AutoAdvanceResult {
-  kind: "advanced" | "blocked" | "paused" | "stopped" | "error";
-  reason?: string;
-  stateSnapshot?: GSDState;
-}
+export type AutoAdvanceResult =
+  | { kind: "started" }
+  | { kind: "resumed" }
+  | { kind: "advanced"; unit: UnitRef; stateSnapshot: GSDState }
+  | { kind: "blocked"; reason: string; action: "pause" | "stop"; stateSnapshot?: GSDState }
+  | { kind: "stopped"; reason: string; stateSnapshot?: GSDState }
+  | { kind: "paused"; reason: string }
+  | { kind: "error"; reason: string };
 
 export interface AutoOrchestrationModule {
   start(sessionContext: AutoSessionContext): Promise<AutoAdvanceResult>;
@@ -33,12 +40,32 @@ export interface AutoOrchestrationModule {
 }
 
 export interface DispatchAdapter {
-  decideNextUnit(input: { stateSnapshot: GSDState }): Promise<{
-    unitType: string;
-    unitId: string;
-    reason: string;
-    preconditions: string[];
-  } | null>;
+  decideNextUnit(input: {
+    stateSnapshot: GSDState;
+    /** Optional live session context, forwarded to dispatch rules that need session-derived state. */
+    session?: AutoSession;
+    /** Mirrors `DispatchContext.structuredQuestionsAvailable` — "true"/"false" string per the dispatch contract. */
+    structuredQuestionsAvailable?: "true" | "false";
+    /** Session model context window in tokens, forwarded to the budget engine. */
+    sessionContextWindow?: number;
+    /** Session model provider, used for provider-specific effective context windows. */
+    sessionProvider?: string;
+    /** Model registry for executor-model lookups inside the budget engine. */
+    modelRegistry?: MinimalModelRegistry;
+  }): Promise<
+    | {
+        kind: "blocked";
+        reason: string;
+        action: "pause" | "stop";
+      }
+    | {
+        unitType: string;
+        unitId: string;
+        reason: string;
+        preconditions: string[];
+      }
+    | null
+  >;
 }
 
 export interface RecoveryAdapter {
@@ -70,11 +97,31 @@ export interface WorktreeAdapter {
   cleanupOnStop(reason: string): Promise<void>;
 }
 
+export type HealthGateResult =
+  | { kind: "pass"; fixesApplied?: readonly string[] }
+  | { kind: "fail"; reason: string }
+  | { kind: "threw"; error: unknown };
+
 export interface HealthAdapter {
-  preAdvanceGate(): Promise<{ allow: boolean; reason?: string }>;
+  checkResourcesStale(): string | null;
+  preAdvanceGate(): Promise<HealthGateResult>;
   postAdvanceRecord(result: AutoAdvanceResult): Promise<void>;
 }
 
+export interface UokGateInput {
+  gateId: string;
+  gateType: "policy" | "execution";
+  outcome: "pass" | "fail" | "manual-attention";
+  failureClass: "none" | "policy" | "manual-attention";
+  rationale: string;
+  findings?: string;
+  milestoneId?: string;
+}
+
+export interface UokGateAdapter {
+  emit(input: UokGateInput): Promise<void>;
+}
+
 export interface RuntimePersistenceAdapter {
   ensureLockOwnership(): Promise<void>;
   journalTransition(event: {
@@ -101,4 +148,5 @@ export interface AutoOrchestratorDeps {
   health: HealthAdapter;
   runtime: RuntimePersistenceAdapter;
   notifications: NotificationAdapter;
+  uokGate: UokGateAdapter;
 }

package/src/resources/extensions/gsd/auto/detect-stuck.ts

@@ -57,6 +57,7 @@ function retryBudgetSuppresses(unitKey: string): boolean {
  */
 export function detectStuck(
   window: readonly WindowEntry[],
+  _retryContext?: { pendingRetry?: boolean; retryAttempt?: number },
 ): { stuck: true; reason: string } | null {
   if (window.length < 2) return null;
 

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

@@ -7,9 +7,14 @@
  */
 
 /**
- * Error codes indicating infrastructure failures that cannot be recovered by
- * retrying. Each retry re-dispatches the unit at full LLM cost, so we bail
- * immediately rather than burning budget on guaranteed failures.
+ * Error codes indicating infrastructure-level failures from the OS,
+ * filesystem, or network. This set includes permanent resource failures
+ * (ENOSPC, ENOMEM, EROFS), transient resource exhaustion (EAGAIN, ENOBUFS),
+ * and network/offline errors (ECONNREFUSED, ENOTFOUND, ENETUNREACH).
+ *
+ * Transient git failures are retried separately through
+ * TRANSIENT_GIT_RETRY_CODES in native-git-bridge.ts before escalating to the
+ * auto-loop.
  */
 export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "ENOSPC",   // disk full
@@ -19,6 +24,7 @@ export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "EMFILE",   // too many open files (process)
   "ENFILE",   // too many open files (system)
   "EAGAIN",       // resource temporarily unavailable (resource exhaustion)
+  "ENOBUFS",      // no buffer space available (transient pipe exhaustion)
   "ECONNREFUSED", // connection refused (offline / local server down)
   "ENOTFOUND",    // DNS lookup failed (offline / no network)
   "ENETUNREACH",  // network unreachable (offline / no route)

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Main auto-mode execution loop.
 /**
  * auto/loop.ts — Main auto-mode execution loop.
  *
@@ -24,6 +26,7 @@ import {
   runDispatch,
   runGuards,
   runFinalize,
+  STUCK_WINDOW_SIZE,
 } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
@@ -78,7 +81,10 @@ import { createWorkflowTurnReporter } from "./workflow-turn-reporter.js";
 import { validateWorkflowSessionLock } from "./workflow-session-lock.js";
 import { dequeueSidecarItem } from "./workflow-sidecar-queue.js";
 import { maintainWorkerHeartbeat } from "./workflow-worker-heartbeat.js";
-import { measureMemoryPressure } from "./workflow-memory-pressure.js";
+import {
+  measureMemoryPressure,
+  shouldCheckMemoryPressure,
+} from "./workflow-memory-pressure.js";
 import { buildSidecarIterationData } from "./workflow-sidecar-iteration.js";
 import {
   createExecutionGraphUnitDispatchDeps,
@@ -106,7 +112,6 @@ import { handleCustomEngineReconcileOutcome } from "./workflow-custom-engine-rec
 // helpers degrade to the empty-state fallback that #3704 already
 // tolerates — same behavior as a fresh session.
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
-const RECENT_UNIT_KEYS_LIMIT = 20;
 
 function stableStuckStateScopeId(s: AutoSession): string {
   return normalizeRealPath(s.scope?.workspace.projectRoot ?? (s.originalBasePath || s.basePath));
@@ -116,7 +121,7 @@ function loadStuckState(s: AutoSession): { recentUnits: Array<{ key: string }>;
   const scopeId = stableStuckStateScopeId(s);
   if (!scopeId) return { recentUnits: [], stuckRecoveryAttempts: 0 };
   try {
-    const recentUnits = getRecentUnitKeysForProjectRoot(scopeId, RECENT_UNIT_KEYS_LIMIT);
+    const recentUnits = getRecentUnitKeysForProjectRoot(scopeId, STUCK_WINDOW_SIZE);
     const stuckRecoveryAttempts =
       getRuntimeKv<number>("global", scopeId, STUCK_RECOVERY_ATTEMPTS_KEY) ?? 0;
     return { recentUnits, stuckRecoveryAttempts };
@@ -203,9 +208,9 @@ function logCustomVerifyRetrySaveFailure(err: unknown): void {
 }
 
 // ── 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).
+// Check heap usage on session startup, then 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 MAX_CUSTOM_ENGINE_VERIFY_RETRIES = 3;
 
@@ -281,6 +286,9 @@ export async function autoLoop(
     recentUnits: persisted.recentUnits,
     stuckRecoveryAttempts: persisted.stuckRecoveryAttempts,
     consecutiveFinalizeTimeouts: 0,
+    consecutiveDispatchCount: new Map<string, number>(),
+    lastDispatchedKey: null,
+    lastDispatchPhase: null,
   };
   let consecutiveErrors = 0;
   let consecutiveCooldowns = 0;
@@ -372,7 +380,7 @@ export async function autoLoop(
 
     // ── Memory pressure check (#3331) ──
     // Graceful shutdown before OOM killer sends SIGKILL.
-    if (iteration % MEMORY_CHECK_INTERVAL === 0) {
+    if (shouldCheckMemoryPressure(iteration, MEMORY_CHECK_INTERVAL)) {
       const mem = measureMemoryPressure();
       debugLog("autoLoop", { phase: "memory-check", ...mem });
       const memoryDecision = decideMemoryPressure({ ...mem, iteration });
@@ -418,9 +426,11 @@ export async function autoLoop(
         logIterationComplete: () => debugLog("autoLoop", { phase: "iteration-complete", iteration }),
       });
     };
+    let stuckStatePersistedThisIteration = false;
     const finishIncompleteIteration = (details: Record<string, unknown>): void => {
       emitIterationEnd(details);
       saveStuckState(s, loopState);
+      stuckStatePersistedThisIteration = true;
     };
 
     try {
@@ -726,42 +736,98 @@ export async function autoLoop(
       }
 
       if (!sidecarItem) {
-        // ── Phase 1: Pre-dispatch ─────────────────────────────────────────
-        const preDispatchResult = await runPreDispatch(ic, loopState);
-        phaseReporter.report("pre-dispatch", preDispatchResult.action);
-        if (preDispatchResult.action === "break") {
-          finishTurn("stopped", "manual-attention", "pre-dispatch-break");
-          break;
-        }
-        if (preDispatchResult.action === "continue") {
-          finishTurn("skipped");
-          continue;
-        }
+        const orchestration = s.orchestration;
+        if (orchestration) {
+          const existingPendingDispatch = s.pendingOrchestrationDispatch;
+          const orchestrationResult = existingPendingDispatch
+            ? {
+                kind: "advanced" as const,
+                unit: {
+                  unitType: existingPendingDispatch.unitType,
+                  unitId: existingPendingDispatch.unitId,
+                },
+                stateSnapshot: existingPendingDispatch.state,
+              }
+            : await orchestration.advance();
 
-        const preData = preDispatchResult.data;
+          if (orchestrationResult.kind === "blocked") {
+            s.pendingOrchestrationDispatch = null;
+            if (orchestrationResult.action === "pause") {
+              await deps.pauseAuto(ctx, pi, {
+                message: orchestrationResult.reason,
+                category: "unknown",
+              });
+            } else {
+              await deps.stopAuto(ctx, pi, orchestrationResult.reason);
+            }
+            finishTurn("stopped", "manual-attention", "orchestration-blocked");
+            break;
+          }
 
-        // ── Phase 2: Guards ───────────────────────────────────────────────
-        const guardsResult = await runGuards(ic, preData.mid);
-        phaseReporter.report("guard", guardsResult.action);
-        if (guardsResult.action === "break") {
-          finishTurn("stopped", "manual-attention", "guard-break");
-          break;
-        }
+          if (orchestrationResult.kind === "stopped") {
+            s.pendingOrchestrationDispatch = null;
+            await deps.stopAuto(ctx, pi, orchestrationResult.reason);
+            finishTurn("stopped", "manual-attention", "orchestration-stopped");
+            break;
+          }
 
-        // ── Phase 3: Dispatch ─────────────────────────────────────────────
-        const dispatchResult = await runDispatch(ic, preData, loopState);
-        phaseReporter.report("dispatch", dispatchResult.action);
-        if (dispatchResult.action === "break") {
-          finishTurn("stopped", "manual-attention", "dispatch-break");
-          break;
-        }
-        if (dispatchResult.action === "continue") {
-          finishTurn("skipped");
-          continue;
+          if (orchestrationResult.kind !== "advanced") {
+            s.pendingOrchestrationDispatch = null;
+            finishTurn("skipped");
+            continue;
+          }
+          const pendingDispatch = s.pendingOrchestrationDispatch;
+          iterData = {
+            unitType: pendingDispatch?.unitType ?? orchestrationResult.unit.unitType,
+            unitId: pendingDispatch?.unitId ?? orchestrationResult.unit.unitId,
+            prompt: pendingDispatch?.prompt ?? "",
+            finalPrompt: pendingDispatch?.prompt ?? "",
+            pauseAfterUatDispatch: pendingDispatch?.pauseAfterUatDispatch ?? false,
+            state: pendingDispatch?.state ?? orchestrationResult.stateSnapshot,
+            mid: pendingDispatch?.mid ?? s.currentMilestoneId ?? "workflow",
+            midTitle: pendingDispatch?.midTitle ?? orchestrationResult.stateSnapshot.activeMilestone?.title ?? "Workflow",
+            isRetry: false,
+            previousTier: undefined,
+          };
+          s.pendingOrchestrationDispatch = null;
+          phaseReporter.report("dispatch", "next", {
+            unitType: iterData.unitType,
+            unitId: iterData.unitId,
+          });
+          observedUnitType = iterData.unitType;
+          observedUnitId = iterData.unitId;
+        } else {
+          const preDispatchResult = await runPreDispatch(ic, loopState);
+          phaseReporter.report("pre-dispatch", preDispatchResult.action);
+          if (preDispatchResult.action === "break") {
+            finishTurn("stopped", "manual-attention", "pre-dispatch-break");
+            break;
+          }
+          if (preDispatchResult.action === "continue") {
+            finishTurn("skipped");
+            continue;
+          }
+          const preData = preDispatchResult.data;
+          const guardsResult = await runGuards(ic, preData.mid);
+          phaseReporter.report("guard", guardsResult.action);
+          if (guardsResult.action === "break") {
+            finishTurn("stopped", "manual-attention", "guard-break");
+            break;
+          }
+          const dispatchResult = await runDispatch(ic, preData, loopState);
+          phaseReporter.report("dispatch", dispatchResult.action);
+          if (dispatchResult.action === "break") {
+            finishTurn("stopped", "manual-attention", "dispatch-break");
+            break;
+          }
+          if (dispatchResult.action === "continue") {
+            finishTurn("skipped");
+            continue;
+          }
+          iterData = dispatchResult.data;
+          observedUnitType = iterData.unitType;
+          observedUnitId = iterData.unitId;
         }
-        iterData = dispatchResult.data;
-        observedUnitType = iterData.unitType;
-        observedUnitId = iterData.unitId;
       } else {
         iterData = await buildSidecarIterationData({
           sidecarItem,
@@ -942,11 +1008,18 @@ export async function autoLoop(
         unitId: iterData.unitId,
       });
       const finalizeReason = finalizeResult.action === "break" ? finalizeResult.reason : undefined;
+      const finalizeStatus = finalizeReason === "step-wizard"
+        ? "completed"
+        : finalizeResult.action === "next"
+          ? "completed"
+          : finalizeResult.action === "continue"
+            ? "retry"
+            : "stopped";
       journalReporter.emit("post-unit-finalize-end", {
         iteration,
         unitType: iterData.unitType,
         unitId: iterData.unitId,
-        status: finalizeResult.action === "next" ? "completed" : finalizeResult.action === "continue" ? "retry" : "stopped",
+        status: finalizeStatus,
         action: finalizeResult.action,
         ...(finalizeReason ? { reason: finalizeReason } : {}),
       });
@@ -980,6 +1053,7 @@ export async function autoLoop(
         finishIncompleteIteration({
           status: "retry",
           reason: "finalize-retry",
+          retry: true,
           unitType: iterData.unitType,
           unitId: iterData.unitId,
         });
@@ -992,7 +1066,12 @@ export async function autoLoop(
         logWriteFailure: logDispatchLedgerWriteFailure,
       }) || dispatchSettled;
       completeIteration();
+      stuckStatePersistedThisIteration = true;
       finishTurn("completed");
+      if (finalizeDecision.action === "complete-and-break") {
+        s.preserveStepSurfaceAfterLoopExit = true;
+        break;
+      }
     } catch (loopErr) {
       // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ──
       const msg = loopErr instanceof Error ? loopErr.message : String(loopErr);
@@ -1139,6 +1218,10 @@ export async function autoLoop(
         ctx.ui.notify(errorDecision.notifyMessage, "warning");
       }
       finishTurn(errorDecision.turnStatus, "execution", msg);
+    } finally {
+      if (!stuckStatePersistedThisIteration) {
+        saveStuckState(s, loopState);
+      }
     }
   }