diff --git a/packages/pi-coding-agent/src/core/agent-session.ts b/packages/pi-coding-agent/src/core/agent-session.ts
index acd234702..859ab1a7f 100644
--- a/packages/pi-coding-agent/src/core/agent-session.ts
+++ b/packages/pi-coding-agent/src/core/agent-session.ts
@@ -25,6 +25,7 @@ import type {
 } from "@gsd/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@gsd/pi-ai";
 import { modelsAreEqual, resetApiProviders, supportsXhigh } from "@gsd/pi-ai";
+import { Type } from "@sinclair/typebox";
 import { getDocsPath } from "../config.js";
 import { getErrorMessage } from "../utils/error.js";
 import { theme } from "../modes/interactive/theme/theme.js";
@@ -732,9 +733,10 @@ export class AgentSession {
 	 * Changes take effect on the next agent turn.
 	 */
 	setActiveToolsByName(toolNames: string[]): void {
+		const requestedToolNames = [...new Set([...toolNames, ...this._getBuiltinToolNames()])];
 		const tools: AgentTool[] = [];
 		const validToolNames: string[] = [];
-		for (const name of toolNames) {
+		for (const name of requestedToolNames) {
 			const tool = this._toolRegistry.get(name);
 			if (tool) {
 				tools.push(tool);
@@ -743,6 +745,7 @@ export class AgentSession {
 		}
 		this.agent.setTools(tools);
 
+
 		// Rebuild base system prompt with new tool set
 		this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
 		this.agent.setSystemPrompt(this._baseSystemPrompt);
@@ -858,6 +861,48 @@ export class AgentSession {
 		return Array.from(unique);
 	}
 
+	private _findSkillByName(skillName: string) {
+		return this.resourceLoader.getSkills().skills.find((skill) => skill.name === skillName);
+	}
+
+	private _formatMissingSkillMessage(skillName: string): string {
+		const availableSkills = this.resourceLoader.getSkills().skills.map((skill) => skill.name).join(", ") || "(none)";
+		return `Skill "${skillName}" not found. Available skills: ${availableSkills}`;
+	}
+
+	private _emitSkillExpansionError(skillFilePath: string, err: unknown): void {
+		this._extensionRunner?.emitError({
+			extensionPath: skillFilePath,
+			event: "skill_expansion",
+			error: getErrorMessage(err),
+		});
+	}
+
+	private _renderSkillInvocation(skill: { name: string; filePath: string; baseDir: string }, args?: string): string {
+		const content = readFileSync(skill.filePath, "utf-8");
+		const body = stripFrontmatter(content).trim();
+		const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+		return args && args.trim() ? `${skillBlock}\n\n${args.trim()}` : skillBlock;
+	}
+
+	private _expandSkillByName(skillName: string, args?: string): string {
+		const skill = this._findSkillByName(skillName);
+		if (!skill) {
+			throw new Error(this._formatMissingSkillMessage(skillName));
+		}
+
+		try {
+			return this._renderSkillInvocation(skill, args);
+		} catch (err) {
+			this._emitSkillExpansionError(skill.filePath, err);
+			throw err;
+		}
+	}
+
+	private _formatSkillInvocation(skillName: string, args?: string): string {
+		return this._expandSkillByName(skillName, args);
+	}
+
 	private _rebuildSystemPrompt(toolNames: string[]): string {
 		const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
 		const toolSnippets: Record<string, string> = {};
@@ -1103,25 +1148,78 @@ export class AgentSession {
 		const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
 		const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
 
-		const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);
-		if (!skill) return text; // Unknown skill, pass through
+		if (!this._findSkillByName(skillName)) return text;
 
 		try {
-			const content = readFileSync(skill.filePath, "utf-8");
-			const body = stripFrontmatter(content).trim();
-			const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
-			return args ? `${skillBlock}\n\n${args}` : skillBlock;
-		} catch (err) {
-			// Emit error like extension commands do
-			this._extensionRunner?.emitError({
-				extensionPath: skill.filePath,
-				event: "skill_expansion",
-				error: getErrorMessage(err),
-			});
-			return text; // Return original on error
+			return this._formatSkillInvocation(skillName, args);
+		} catch {
+			return text;
 		}
 	}
 
+	private _createBuiltInSkillTool(): AgentTool {
+		const skillSchema = Type.Object({
+			skill: Type.String({ description: "The skill name. E.g., 'commit', 'review-pr', or 'pdf'" }),
+			args: Type.Optional(Type.String({ description: "Optional arguments for the skill" })),
+		});
+
+		return {
+			name: "Skill",
+			label: "Skill",
+			description:
+				"Execute a skill within the main conversation. Use this tool when users ask for a slash command or reference a skill by name. Returns the expanded skill block and appends args after it.",
+			parameters: skillSchema,
+			execute: async (_toolCallId, params: unknown) => {
+				const input = params as { skill: string; args?: string };
+				try {
+					return {
+						content: [
+							{
+								type: "text",
+								text: this._expandSkillByName(input.skill, input.args),
+							},
+						],
+						details: undefined,
+					};
+				} catch (err) {
+					return {
+						content: [{ type: "text", text: getErrorMessage(err) }],
+						details: undefined,
+					};
+				}
+			},
+		};
+	}
+
+	private _getBuiltinToolNames(): string[] {
+		return this._getBuiltinTools().map((tool) => tool.name);
+	}
+
+	private _getBuiltinTools(): AgentTool[] {
+		return [this._createBuiltInSkillTool()];
+	}
+
+	private _getRegisteredToolDefinitions(): ToolDefinition[] {
+		const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+		return registeredTools.map((tool) => tool.definition);
+	}
+
+	private _getBuiltinToolDefinitions(): ToolDefinition[] {
+		return this._getBuiltinTools().map((tool) => ({
+			name: tool.name,
+			label: tool.label,
+			description: tool.description,
+			parameters: tool.parameters,
+			execute: async () => ({ content: [], details: undefined }),
+		}));
+	}
+
+	getRenderableToolDefinition(toolName: string): ToolDefinition | undefined {
+		return [...this._getBuiltinToolDefinitions(), ...this._getRegisteredToolDefinitions()].find(
+			(tool) => tool.name === toolName,
+		);
+	}
+
 	/**
 	 * Queue a steering message to interrupt the agent mid-run.
 	 * Delivered after current tool execution, skips remaining tools.
@@ -1967,8 +2065,12 @@ export class AgentSession {
 		const wrappedExtensionTools = this._extensionRunner
 			? wrapRegisteredTools(allCustomTools, this._extensionRunner)
 			: [];
+		const builtinTools = this._getBuiltinTools();
 
 		const toolRegistry = new Map(this._baseToolRegistry);
+		for (const tool of builtinTools) {
+			toolRegistry.set(tool.name, tool);
+		}
 		for (const tool of wrappedExtensionTools as AgentTool[]) {
 			toolRegistry.set(tool.name, tool);
 		}
@@ -2694,14 +2796,11 @@ export class AgentSession {
 	async exportToHtml(outputPath?: string): Promise<string> {
 		const themeName = this.settingsManager.getTheme();
 
-		// Create tool renderer if we have an extension runner (for custom tool HTML rendering)
-		let toolRenderer: ToolHtmlRenderer | undefined;
-		if (this._extensionRunner) {
-			toolRenderer = createToolHtmlRenderer({
-				getToolDefinition: (name) => this._extensionRunner!.getToolDefinition(name),
-				theme,
-			});
-		}
+		// Create tool renderer for extension and built-in tool HTML rendering
+		const toolRenderer = createToolHtmlRenderer({
+			getToolDefinition: (name) => this.getRenderableToolDefinition(name),
+			theme,
+		});
 
 		return await exportSessionToHtml(this.sessionManager, this.state, {
 			outputPath,
diff --git a/packages/pi-coding-agent/src/core/skill-tool.test.ts b/packages/pi-coding-agent/src/core/skill-tool.test.ts
new file mode 100644
index 000000000..e8a3b2964
--- /dev/null
+++ b/packages/pi-coding-agent/src/core/skill-tool.test.ts
@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+
+import { Agent } from "@gsd/pi-agent-core";
+import { AuthStorage } from "./auth-storage.js";
+import { AgentSession } from "./agent-session.js";
+import { ModelRegistry } from "./model-registry.js";
+import { DefaultResourceLoader } from "./resource-loader.js";
+import { SessionManager } from "./session-manager.js";
+import { SettingsManager } from "./settings-manager.js";
+
+let testDir: string;
+
+function writeSkill(cwd: string, name: string, description: string, body = `# ${name}\n`): string {
+	const skillDir = join(cwd, ".pi", "skills", name);
+	mkdirSync(skillDir, { recursive: true });
+	const skillPath = join(skillDir, "SKILL.md");
+	writeFileSync(skillPath, `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}`);
+	return skillPath;
+}
+
+describe("Skill tool", () => {
+	beforeEach(() => {
+		testDir = mkdtempSync(join(tmpdir(), "skill-tool-test-"));
+	});
+
+	afterEach(() => {
+		rmSync(testDir, { recursive: true, force: true });
+	});
+
+	async function createSession() {
+		const agentDir = join(testDir, "agent-home");
+		const authStorage = AuthStorage.inMemory({});
+		const modelRegistry = new ModelRegistry(authStorage, join(agentDir, "models.json"));
+		const settingsManager = SettingsManager.inMemory();
+		const resourceLoader = new DefaultResourceLoader({
+			cwd: testDir,
+			agentDir,
+			settingsManager,
+			noExtensions: true,
+			noPromptTemplates: true,
+			noThemes: true,
+		});
+		await resourceLoader.reload();
+
+		return new AgentSession({
+			agent: new Agent(),
+			sessionManager: SessionManager.inMemory(testDir),
+			settingsManager,
+			cwd: testDir,
+			resourceLoader,
+			modelRegistry,
+		});
+	}
+
+	it("resolves a project-level skill to the exact skill block format", async () => {
+		const skillPath = writeSkill(
+			testDir,
+			"swift-testing",
+			"Use for Swift Testing assertions and verification patterns.",
+			"# Swift Testing\nUse this skill.\n",
+		);
+		const session = await createSession();
+
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+
+		const result = await tool.execute("call-1", { skill: "swift-testing" });
+		assert.equal(
+			result.content[0]?.type === "text" ? result.content[0].text : "",
+			`<skill name="swift-testing" location="${skillPath}">\nReferences are relative to ${join(testDir, ".pi", "skills", "swift-testing")}.\n\n# Swift Testing\nUse this skill.\n</skill>`,
+		);
+	});
+
+	it("returns a helpful error for unknown skills", async () => {
+		writeSkill(testDir, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
+		const session = await createSession();
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+
+		const result = await tool.execute("call-2", { skill: "nonexistent" });
+		const message = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(message, /^Skill "nonexistent" not found\. Available skills: /);
+		assert.match(message, /swift-testing/);
+	});
+});
diff --git a/packages/pi-coding-agent/src/core/skills.ts b/packages/pi-coding-agent/src/core/skills.ts
index ba59cf7fa..9868b1546 100644
--- a/packages/pi-coding-agent/src/core/skills.ts
+++ b/packages/pi-coding-agent/src/core/skills.ts
@@ -299,7 +299,8 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
 
 	const lines = [
 		"\n\nThe following skills provide specialized instructions for specific tasks.",
-		"Use the read tool to load a skill's file when the task matches its description.",
+		"Use the Skill tool with the exact skill name from <available_skills> when the task matches its description.",
+		"If the Skill tool reports an unknown skill, do not guess: use an exact name from <available_skills> or tell the user the skill is unavailable.",
 		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
 		"",
 		"<available_skills>",
diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts
new file mode 100644
index 000000000..f1ec8dd6e
--- /dev/null
+++ b/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts
@@ -0,0 +1,302 @@
+import { Loader, Spacer, Text } from "@gsd/pi-tui";
+
+import type { InteractiveModeEvent, InteractiveModeStateHost } from "../interactive-mode-state.js";
+import { theme } from "../theme/theme.js";
+import { AssistantMessageComponent } from "../components/assistant-message.js";
+import { ToolExecutionComponent } from "../components/tool-execution.js";
+import { appKey } from "../components/keybinding-hints.js";
+
+export async function handleAgentEvent(host: InteractiveModeStateHost & {
+	init: () => Promise<void>;
+	getMarkdownThemeWithSettings: () => any;
+	addMessageToChat: (message: any, options?: any) => void;
+	formatWebSearchResult: (content: unknown) => string;
+	getRegisteredToolDefinition: (toolName: string) => any;
+	checkShutdownRequested: () => Promise<void>;
+	rebuildChatFromMessages: () => void;
+	flushCompactionQueue: (options?: { willRetry?: boolean }) => Promise<void>;
+	showStatus: (message: string) => void;
+	showError: (message: string) => void;
+	updatePendingMessagesDisplay: () => void;
+}, event: InteractiveModeEvent): Promise<void> {
+	if (!host.isInitialized) {
+		await host.init();
+	}
+
+	host.footer.invalidate();
+
+	switch (event.type) {
+		case "agent_start":
+			if (host.retryEscapeHandler) {
+				host.defaultEditor.onEscape = host.retryEscapeHandler;
+				host.retryEscapeHandler = undefined;
+			}
+			if (host.retryLoader) {
+				host.retryLoader.stop();
+				host.retryLoader = undefined;
+			}
+			if (host.loadingAnimation) {
+				host.loadingAnimation.stop();
+			}
+			host.statusContainer.clear();
+			host.loadingAnimation = new Loader(
+				host.ui,
+				(spinner) => theme.fg("accent", spinner),
+				(text) => theme.fg("muted", text),
+				host.defaultWorkingMessage,
+			);
+			host.statusContainer.addChild(host.loadingAnimation);
+			if (host.pendingWorkingMessage !== undefined) {
+				if (host.pendingWorkingMessage) {
+					host.loadingAnimation.setMessage(host.pendingWorkingMessage);
+				}
+				host.pendingWorkingMessage = undefined;
+			}
+			host.ui.requestRender();
+			break;
+
+		case "message_start":
+			if (event.message.role === "custom") {
+				host.addMessageToChat(event.message);
+				host.ui.requestRender();
+			} else if (event.message.role === "user") {
+				host.addMessageToChat(event.message);
+				host.updatePendingMessagesDisplay();
+				host.ui.requestRender();
+			} else if (event.message.role === "assistant") {
+				host.streamingComponent = new AssistantMessageComponent(
+					undefined,
+					host.hideThinkingBlock,
+					host.getMarkdownThemeWithSettings(),
+				);
+				host.streamingMessage = event.message;
+				host.chatContainer.addChild(host.streamingComponent);
+				host.streamingComponent.updateContent(host.streamingMessage);
+				host.ui.requestRender();
+			}
+			break;
+
+		case "message_update":
+			if (host.streamingComponent && event.message.role === "assistant") {
+				host.streamingMessage = event.message;
+				host.streamingComponent.updateContent(host.streamingMessage);
+				for (const content of host.streamingMessage.content) {
+					if (content.type === "toolCall") {
+						if (!host.pendingTools.has(content.id)) {
+							const component = new ToolExecutionComponent(
+								content.name,
+								content.arguments,
+								{ showImages: host.settingsManager.getShowImages() },
+								host.getRegisteredToolDefinition(content.name),
+								host.ui,
+							);
+							component.setExpanded(host.toolOutputExpanded);
+							host.chatContainer.addChild(component);
+							host.pendingTools.set(content.id, component);
+						} else {
+							host.pendingTools.get(content.id)?.updateArgs(content.arguments);
+						}
+					} else if (content.type === "serverToolUse") {
+						if (!host.pendingTools.has(content.id)) {
+							const component = new ToolExecutionComponent(
+								content.name,
+								content.input ?? {},
+								{ showImages: host.settingsManager.getShowImages() },
+								undefined,
+								host.ui,
+							);
+							component.setExpanded(host.toolOutputExpanded);
+							host.chatContainer.addChild(component);
+							host.pendingTools.set(content.id, component);
+						}
+					} else if (content.type === "webSearchResult") {
+						const component = host.pendingTools.get(content.toolUseId);
+						if (component) {
+							const searchContent = content.content;
+							const isError = searchContent && typeof searchContent === "object" && "type" in (searchContent as any) && (searchContent as any).type === "web_search_tool_result_error";
+							component.updateResult({
+								content: [{ type: "text", text: host.formatWebSearchResult(searchContent) }],
+								isError: !!isError,
+							});
+							host.pendingTools.delete(content.toolUseId);
+						}
+					}
+				}
+				host.ui.requestRender();
+			}
+			break;
+
+		case "message_end":
+			if (event.message.role === "user") break;
+			if (host.streamingComponent && event.message.role === "assistant") {
+				host.streamingMessage = event.message;
+				let errorMessage: string | undefined;
+				if (host.streamingMessage.stopReason === "aborted") {
+					const retryAttempt = host.session.retryAttempt;
+					errorMessage = retryAttempt > 0
+						? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
+						: "Operation aborted";
+					host.streamingMessage.errorMessage = errorMessage;
+				}
+				host.streamingComponent.updateContent(host.streamingMessage);
+				if (host.streamingMessage.stopReason === "aborted" || host.streamingMessage.stopReason === "error") {
+					if (!errorMessage) {
+						errorMessage = host.streamingMessage.errorMessage || "Error";
+					}
+					for (const [, component] of host.pendingTools.entries()) {
+						component.updateResult({ content: [{ type: "text", text: errorMessage }], isError: true });
+					}
+					host.pendingTools.clear();
+				} else {
+					for (const [, component] of host.pendingTools.entries()) {
+						component.setArgsComplete();
+					}
+				}
+				host.streamingComponent = undefined;
+				host.streamingMessage = undefined;
+				host.footer.invalidate();
+			}
+			host.ui.requestRender();
+			break;
+
+		case "tool_execution_start":
+			if (!host.pendingTools.has(event.toolCallId)) {
+				const component = new ToolExecutionComponent(
+					event.toolName,
+					event.args,
+					{ showImages: host.settingsManager.getShowImages() },
+					host.getRegisteredToolDefinition(event.toolName),
+					host.ui,
+				);
+				component.setExpanded(host.toolOutputExpanded);
+				host.chatContainer.addChild(component);
+				host.pendingTools.set(event.toolCallId, component);
+				host.ui.requestRender();
+			}
+			break;
+
+		case "tool_execution_update": {
+			const component = host.pendingTools.get(event.toolCallId);
+			if (component) {
+				component.updateResult({ ...event.partialResult, isError: false }, true);
+				host.ui.requestRender();
+			}
+			break;
+		}
+
+		case "tool_execution_end": {
+			const component = host.pendingTools.get(event.toolCallId);
+			if (component) {
+				component.updateResult({ ...event.result, isError: event.isError });
+				host.pendingTools.delete(event.toolCallId);
+				host.ui.requestRender();
+			}
+			break;
+		}
+
+		case "agent_end":
+			if (host.loadingAnimation) {
+				host.loadingAnimation.stop();
+				host.loadingAnimation = undefined;
+				host.statusContainer.clear();
+			}
+			if (host.streamingComponent) {
+				host.chatContainer.removeChild(host.streamingComponent);
+				host.streamingComponent = undefined;
+				host.streamingMessage = undefined;
+			}
+			host.pendingTools.clear();
+			await host.checkShutdownRequested();
+			host.ui.requestRender();
+			break;
+
+		case "auto_compaction_start":
+			host.autoCompactionEscapeHandler = host.defaultEditor.onEscape;
+			host.defaultEditor.onEscape = () => host.session.abortCompaction();
+			host.statusContainer.clear();
+			host.autoCompactionLoader = new Loader(
+				host.ui,
+				(spinner) => theme.fg("accent", spinner),
+				(text) => theme.fg("muted", text),
+				`${event.reason === "overflow" ? "Context overflow detected, " : ""}Auto-compacting... (${appKey(host.keybindings, "interrupt")} to cancel)`,
+			);
+			host.statusContainer.addChild(host.autoCompactionLoader);
+			host.ui.requestRender();
+			break;
+
+		case "auto_compaction_end":
+			if (host.autoCompactionEscapeHandler) {
+				host.defaultEditor.onEscape = host.autoCompactionEscapeHandler;
+				host.autoCompactionEscapeHandler = undefined;
+			}
+			if (host.autoCompactionLoader) {
+				host.autoCompactionLoader.stop();
+				host.autoCompactionLoader = undefined;
+				host.statusContainer.clear();
+			}
+			if (event.aborted) {
+				host.showStatus("Auto-compaction cancelled");
+			} else if (event.result) {
+				host.chatContainer.clear();
+				host.rebuildChatFromMessages();
+				host.addMessageToChat({
+					role: "compactionSummary",
+					tokensBefore: event.result.tokensBefore,
+					summary: event.result.summary,
+					timestamp: Date.now(),
+				});
+				host.footer.invalidate();
+			} else if (event.errorMessage) {
+				host.chatContainer.addChild(new Spacer(1));
+				host.chatContainer.addChild(new Text(theme.fg("error", event.errorMessage), 1, 0));
+			}
+			void host.flushCompactionQueue({ willRetry: event.willRetry });
+			host.ui.requestRender();
+			break;
+
+		case "auto_retry_start":
+			host.retryEscapeHandler = host.defaultEditor.onEscape;
+			host.defaultEditor.onEscape = () => host.session.abortRetry();
+			host.statusContainer.clear();
+			host.retryLoader = new Loader(
+				host.ui,
+				(spinner) => theme.fg("warning", spinner),
+				(text) => theme.fg("muted", text),
+				`Retrying (${event.attempt}/${event.maxAttempts}) in ${Math.round(event.delayMs / 1000)}s... (${appKey(host.keybindings, "interrupt")} to cancel)`,
+			);
+			host.statusContainer.addChild(host.retryLoader);
+			host.ui.requestRender();
+			break;
+
+		case "auto_retry_end":
+			if (host.retryEscapeHandler) {
+				host.defaultEditor.onEscape = host.retryEscapeHandler;
+				host.retryEscapeHandler = undefined;
+			}
+			if (host.retryLoader) {
+				host.retryLoader.stop();
+				host.retryLoader = undefined;
+				host.statusContainer.clear();
+			}
+			if (!event.success) {
+				host.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
+			}
+			host.ui.requestRender();
+			break;
+
+		case "fallback_provider_switch":
+			host.showStatus(`Switched from ${event.from} → ${event.to} (${event.reason})`);
+			host.ui.requestRender();
+			break;
+
+		case "fallback_provider_restored":
+			host.showStatus(`Restored to ${event.provider}`);
+			host.ui.requestRender();
+			break;
+
+		case "fallback_chain_exhausted":
+			host.showError(event.reason);
+			host.ui.requestRender();
+			break;
+	}
+}
diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/extension-ui-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/extension-ui-controller.ts
new file mode 100644
index 000000000..c4ce6c527
--- /dev/null
+++ b/packages/pi-coding-agent/src/modes/interactive/controllers/extension-ui-controller.ts
@@ -0,0 +1,59 @@
+import type { ExtensionUIContext } from "../../../core/extensions/index.js";
+
+import { Theme, getAvailableThemesWithPaths, getThemeByName, setTheme, setThemeInstance, theme } from "../theme/theme.js";
+import { appKey } from "../components/keybinding-hints.js";
+
+export function createExtensionUIContext(host: any): ExtensionUIContext {
+	return {
+		select: (title, options, opts) => host.showExtensionSelector(title, options, opts),
+		confirm: (title, message, opts) => host.showExtensionConfirm(title, message, opts),
+		input: (title, placeholder, opts) => host.showExtensionInput(title, placeholder, opts),
+		notify: (message, type) => host.showExtensionNotify(message, type),
+		onTerminalInput: (handler) => host.addExtensionTerminalInputListener(handler),
+		setStatus: (key, text) => host.setExtensionStatus(key, text),
+		setWorkingMessage: (message) => {
+			if (host.loadingAnimation) {
+				if (message) {
+					host.loadingAnimation.setMessage(message);
+				} else {
+					host.loadingAnimation.setMessage(`${host.defaultWorkingMessage} (${appKey(host.keybindings, "interrupt")} to interrupt)`);
+				}
+			} else {
+				host.pendingWorkingMessage = message;
+			}
+		},
+		setWidget: (key, content, options) => host.setExtensionWidget(key, content, options),
+		setFooter: (factory) => host.setExtensionFooter(factory),
+		setHeader: (factory) => host.setExtensionHeader(factory),
+		setTitle: (title) => host.ui.terminal.setTitle(title),
+		custom: (factory, options) => host.showExtensionCustom(factory, options),
+		pasteToEditor: (text) => host.editor.handleInput(`\x1b[200~${text}\x1b[201~`),
+		setEditorText: (text) => host.editor.setText(text),
+		getEditorText: () => host.editor.getText(),
+		editor: (title, prefill) => host.showExtensionEditor(title, prefill),
+		setEditorComponent: (factory) => host.setCustomEditorComponent(factory),
+		get theme() {
+			return theme;
+		},
+		getAllThemes: () => getAvailableThemesWithPaths(),
+		getTheme: (name) => getThemeByName(name),
+		setTheme: (themeOrName) => {
+			if (themeOrName instanceof Theme) {
+				setThemeInstance(themeOrName);
+				host.ui.requestRender();
+				return { success: true };
+			}
+			const result = setTheme(themeOrName, true);
+			if (result.success) {
+				if (host.settingsManager.getTheme() !== themeOrName) {
+					host.settingsManager.setTheme(themeOrName);
+				}
+				host.ui.requestRender();
+			}
+			return result;
+		},
+		getToolsExpanded: () => host.toolOutputExpanded,
+		setToolsExpanded: (expanded) => host.setToolsExpanded(expanded),
+	};
+}
+
diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts
new file mode 100644
index 000000000..9473da995
--- /dev/null
+++ b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts
@@ -0,0 +1,68 @@
+import { dispatchSlashCommand } from "../slash-command-handlers.js";
+import type { InteractiveModeStateHost } from "../interactive-mode-state.js";
+
+export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
+	getSlashCommandContext: () => any;
+	handleBashCommand: (command: string, excludeFromContext?: boolean) => Promise<void>;
+	showWarning: (message: string) => void;
+	updateEditorBorderColor: () => void;
+	isExtensionCommand: (text: string) => boolean;
+	queueCompactionMessage: (text: string, mode: "steer" | "followUp") => void;
+	updatePendingMessagesDisplay: () => void;
+	flushPendingBashComponents: () => void;
+}): void {
+	host.defaultEditor.onSubmit = async (text: string) => {
+		text = text.trim();
+		if (!text) return;
+
+		if (text.startsWith("/")) {
+			const handled = await dispatchSlashCommand(text, host.getSlashCommandContext());
+			if (handled) {
+				host.editor.setText("");
+				return;
+			}
+		}
+
+		if (text.startsWith("!")) {
+			const isExcluded = text.startsWith("!!");
+			const command = isExcluded ? text.slice(2).trim() : text.slice(1).trim();
+			if (command) {
+				if (host.session.isBashRunning) {
+					host.showWarning("A bash command is already running. Press Esc to cancel it first.");
+					host.editor.setText(text);
+					return;
+				}
+				host.editor.addToHistory?.(text);
+				await host.handleBashCommand(command, isExcluded);
+				host.isBashMode = false;
+				host.updateEditorBorderColor();
+				return;
+			}
+		}
+
+		if (host.session.isCompacting) {
+			if (host.isExtensionCommand(text)) {
+				host.editor.addToHistory?.(text);
+				host.editor.setText("");
+				await host.session.prompt(text);
+			} else {
+				host.queueCompactionMessage(text, "steer");
+			}
+			return;
+		}
+
+		if (host.session.isStreaming) {
+			host.editor.addToHistory?.(text);
+			host.editor.setText("");
+			await host.session.prompt(text, { streamingBehavior: "steer" });
+			host.updatePendingMessagesDisplay();
+			host.ui.requestRender();
+			return;
+		}
+
+		host.flushPendingBashComponents();
+		host.onInputCallback?.(text);
+		host.editor.addToHistory?.(text);
+	};
+}
+
diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/model-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/model-controller.ts
new file mode 100644
index 000000000..ab6ccf6a9
--- /dev/null
+++ b/packages/pi-coding-agent/src/modes/interactive/controllers/model-controller.ts
@@ -0,0 +1,71 @@
+import type { Model } from "@gsd/pi-ai";
+
+export async function handleModelCommand(host: any, searchTerm?: string): Promise<void> {
+	if (!searchTerm) {
+		host.showModelSelector();
+		return;
+	}
+
+	const model = await findExactModelMatch(host, searchTerm);
+	if (model) {
+		try {
+			await host.session.setModel(model);
+			host.footer.invalidate();
+			host.updateEditorBorderColor();
+			host.showStatus(`Model: ${model.id}`);
+			host.checkDaxnutsEasterEgg(model);
+		} catch (error) {
+			host.showError(error instanceof Error ? error.message : String(error));
+		}
+		return;
+	}
+
+	host.showModelSelector(searchTerm);
+}
+
+export async function findExactModelMatch(host: any, searchTerm: string): Promise<Model<any> | undefined> {
+	const term = searchTerm.trim();
+	if (!term) return undefined;
+
+	let targetProvider: string | undefined;
+	let targetModelId = "";
+
+	if (term.includes("/")) {
+		const parts = term.split("/", 2);
+		targetProvider = parts[0]?.trim().toLowerCase();
+		targetModelId = parts[1]?.trim().toLowerCase() ?? "";
+	} else {
+		targetModelId = term.toLowerCase();
+	}
+
+	if (!targetModelId) return undefined;
+
+	const models = await getModelCandidates(host);
+	const exactMatches = models.filter((item) => {
+		const idMatch = item.id.toLowerCase() === targetModelId;
+		const providerMatch = !targetProvider || item.provider.toLowerCase() === targetProvider;
+		return idMatch && providerMatch;
+	});
+
+	return exactMatches.length === 1 ? exactMatches[0] : undefined;
+}
+
+export async function getModelCandidates(host: any): Promise<Model<any>[]> {
+	if (host.session.scopedModels.length > 0) {
+		return host.session.scopedModels.map((scoped: any) => scoped.model);
+	}
+
+	host.session.modelRegistry.refresh();
+	try {
+		return await host.session.modelRegistry.getAvailable();
+	} catch {
+		return [];
+	}
+}
+
+export async function updateAvailableProviderCount(host: any): Promise<void> {
+	const models = await getModelCandidates(host);
+	const uniqueProviders = new Set(models.map((m) => m.provider));
+	host.footerDataProvider.setAvailableProviderCount(uniqueProviders.size);
+}
+
diff --git a/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts b/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts
new file mode 100644
index 000000000..cf91b00b1
--- /dev/null
+++ b/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts
@@ -0,0 +1,37 @@
+import type { AgentSessionEvent } from "../../core/agent-session.js";
+
+export interface InteractiveModeStateHost {
+	defaultEditor: any;
+	editor: any;
+	session: any;
+	ui: any;
+	footer: any;
+	keybindings: any;
+	statusContainer: any;
+	chatContainer: any;
+	settingsManager: any;
+	pendingTools: Map<string, any>;
+	toolOutputExpanded: boolean;
+	hideThinkingBlock: boolean;
+	isBashMode: boolean;
+	onInputCallback?: (text: string) => void;
+	isInitialized: boolean;
+	loadingAnimation?: any;
+	pendingWorkingMessage?: string;
+	defaultWorkingMessage: string;
+	streamingComponent?: any;
+	streamingMessage?: any;
+	retryEscapeHandler?: () => void;
+	retryLoader?: any;
+	autoCompactionLoader?: any;
+	autoCompactionEscapeHandler?: () => void;
+	compactionQueuedMessages: Array<{ text: string; mode: "steer" | "followUp" }>;
+	extensionSelector?: any;
+	extensionInput?: any;
+	extensionEditor?: any;
+	editorContainer: any;
+	keybindingsManager?: any;
+}
+
+export type InteractiveModeEvent = AgentSessionEvent;
+
diff --git a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts
index 162b25913..6795d2064 100644
--- a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts
+++ b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts
@@ -89,6 +89,15 @@ import { TreeSelectorComponent } from "./components/tree-selector.js";
 import { UserMessageComponent } from "./components/user-message.js";
 import { UserMessageSelectorComponent } from "./components/user-message-selector.js";
 import { type SlashCommandContext, dispatchSlashCommand, getAppKeyDisplay } from "./slash-command-handlers.js";
+import { handleAgentEvent } from "./controllers/chat-controller.js";
+import { createExtensionUIContext as buildExtensionUIContext } from "./controllers/extension-ui-controller.js";
+import { setupEditorSubmitHandler as setupEditorSubmitHandlerController } from "./controllers/input-controller.js";
+import {
+	findExactModelMatch as findExactModelMatchController,
+	getModelCandidates as getModelCandidatesController,
+	handleModelCommand as handleModelCommandController,
+	updateAvailableProviderCount as updateAvailableProviderCountController,
+} from "./controllers/model-controller.js";
 import {
 	getAvailableThemes,
 	getAvailableThemesWithPaths,
@@ -1175,12 +1184,10 @@ export class InteractiveMode {
 	}
 
 	/**
-	 * Get a registered tool definition by name (for custom rendering).
+	 * Get a tool definition by name (for custom rendering).
 	 */
 	private getRegisteredToolDefinition(toolName: string) {
-		const tools = this.session.extensionRunner?.getAllRegisteredTools() ?? [];
-		const registeredTool = tools.find((t) => t.definition.name === toolName);
-		return registeredTool?.definition;
+		return this.session.getRenderableToolDefinition(toolName);
 	}
 
 	/**
@@ -1486,60 +1493,7 @@ export class InteractiveMode {
 	 * Create the ExtensionUIContext for extensions.
 	 */
 	private createExtensionUIContext(): ExtensionUIContext {
-		return {
-			select: (title, options, opts) => this.showExtensionSelector(title, options, opts),
-			confirm: (title, message, opts) => this.showExtensionConfirm(title, message, opts),
-			input: (title, placeholder, opts) => this.showExtensionInput(title, placeholder, opts),
-			notify: (message, type) => this.showExtensionNotify(message, type),
-			onTerminalInput: (handler) => this.addExtensionTerminalInputListener(handler),
-			setStatus: (key, text) => this.setExtensionStatus(key, text),
-			setWorkingMessage: (message) => {
-				if (this.loadingAnimation) {
-					if (message) {
-						this.loadingAnimation.setMessage(message);
-					} else {
-						this.loadingAnimation.setMessage(
-							`${this.defaultWorkingMessage} (${appKey(this.keybindings, "interrupt")} to interrupt)`,
-						);
-					}
-				} else {
-					// Queue message for when loadingAnimation is created (handles agent_start race)
-					this.pendingWorkingMessage = message;
-				}
-			},
-			setWidget: (key, content, options) => this.setExtensionWidget(key, content, options),
-			setFooter: (factory) => this.setExtensionFooter(factory),
-			setHeader: (factory) => this.setExtensionHeader(factory),
-			setTitle: (title) => this.ui.terminal.setTitle(title),
-			custom: (factory, options) => this.showExtensionCustom(factory, options),
-			pasteToEditor: (text) => this.editor.handleInput(`\x1b[200~${text}\x1b[201~`),
-			setEditorText: (text) => this.editor.setText(text),
-			getEditorText: () => this.editor.getText(),
-			editor: (title, prefill) => this.showExtensionEditor(title, prefill),
-			setEditorComponent: (factory) => this.setCustomEditorComponent(factory),
-			get theme() {
-				return theme;
-			},
-			getAllThemes: () => getAvailableThemesWithPaths(),
-			getTheme: (name) => getThemeByName(name),
-			setTheme: (themeOrName) => {
-				if (themeOrName instanceof Theme) {
-					setThemeInstance(themeOrName);
-					this.ui.requestRender();
-					return { success: true };
-				}
-				const result = setTheme(themeOrName, true);
-				if (result.success) {
-					if (this.settingsManager.getTheme() !== themeOrName) {
-						this.settingsManager.setTheme(themeOrName);
-					}
-					this.ui.requestRender();
-				}
-				return result;
-			},
-			getToolsExpanded: () => this.toolOutputExpanded,
-			setToolsExpanded: (expanded) => this.setToolsExpanded(expanded),
-		};
+		return buildExtensionUIContext(this);
 	}
 
 	/**
@@ -2017,69 +1971,7 @@ export class InteractiveMode {
 	}
 
 	private setupEditorSubmitHandler(): void {
-		this.defaultEditor.onSubmit = async (text: string) => {
-			text = text.trim();
-			if (!text) return;
-
-			// Handle slash commands
-			if (text.startsWith("/")) {
-				const handled = await dispatchSlashCommand(text, this.getSlashCommandContext());
-				if (handled) {
-					this.editor.setText("");
-					return;
-				}
-			}
-
-			// Handle bash command (! for normal, !! for excluded from context)
-			if (text.startsWith("!")) {
-				const isExcluded = text.startsWith("!!");
-				const command = isExcluded ? text.slice(2).trim() : text.slice(1).trim();
-				if (command) {
-					if (this.session.isBashRunning) {
-						this.showWarning("A bash command is already running. Press Esc to cancel it first.");
-						this.editor.setText(text);
-						return;
-					}
-					this.editor.addToHistory?.(text);
-					await this.handleBashCommand(command, isExcluded);
-					this.isBashMode = false;
-					this.updateEditorBorderColor();
-					return;
-				}
-			}
-
-			// Queue input during compaction (extension commands execute immediately)
-			if (this.session.isCompacting) {
-				if (this.isExtensionCommand(text)) {
-					this.editor.addToHistory?.(text);
-					this.editor.setText("");
-					await this.session.prompt(text);
-				} else {
-					this.queueCompactionMessage(text, "steer");
-				}
-				return;
-			}
-
-			// If streaming, use prompt() with steer behavior
-			// This handles extension commands (execute immediately), prompt template expansion, and queueing
-			if (this.session.isStreaming) {
-				this.editor.addToHistory?.(text);
-				this.editor.setText("");
-				await this.session.prompt(text, { streamingBehavior: "steer" });
-				this.updatePendingMessagesDisplay();
-				this.ui.requestRender();
-				return;
-			}
-
-			// Normal message submission
-			// First, move any pending bash components to chat
-			this.flushPendingBashComponents();
-
-			if (this.onInputCallback) {
-				this.onInputCallback(text);
-			}
-			this.editor.addToHistory?.(text);
-		};
+		setupEditorSubmitHandlerController(this as any);
 	}
 
 	private subscribeToAgent(): void {
@@ -2089,338 +1981,7 @@ export class InteractiveMode {
 	}
 
 	private async handleEvent(event: AgentSessionEvent): Promise<void> {
-		if (!this.isInitialized) {
-			await this.init();
-		}
-
-		this.footer.invalidate();
-
-		switch (event.type) {
-			case "agent_start":
-				// Restore main escape handler if retry handler is still active
-				// (retry success event fires later, but we need main handler now)
-				if (this.retryEscapeHandler) {
-					this.defaultEditor.onEscape = this.retryEscapeHandler;
-					this.retryEscapeHandler = undefined;
-				}
-				if (this.retryLoader) {
-					this.retryLoader.stop();
-					this.retryLoader = undefined;
-				}
-				if (this.loadingAnimation) {
-					this.loadingAnimation.stop();
-				}
-				this.statusContainer.clear();
-				this.loadingAnimation = new Loader(
-					this.ui,
-					(spinner) => theme.fg("accent", spinner),
-					(text) => theme.fg("muted", text),
-					this.defaultWorkingMessage,
-				);
-				this.statusContainer.addChild(this.loadingAnimation);
-				// Apply any pending working message queued before loader existed
-				if (this.pendingWorkingMessage !== undefined) {
-					if (this.pendingWorkingMessage) {
-						this.loadingAnimation.setMessage(this.pendingWorkingMessage);
-					}
-					this.pendingWorkingMessage = undefined;
-				}
-				this.ui.requestRender();
-				break;
-
-			case "message_start":
-				if (event.message.role === "custom") {
-					this.addMessageToChat(event.message);
-					this.ui.requestRender();
-				} else if (event.message.role === "user") {
-					this.addMessageToChat(event.message);
-					this.updatePendingMessagesDisplay();
-					this.ui.requestRender();
-				} else if (event.message.role === "assistant") {
-					this.streamingComponent = new AssistantMessageComponent(
-						undefined,
-						this.hideThinkingBlock,
-						this.getMarkdownThemeWithSettings(),
-					);
-					this.streamingMessage = event.message;
-					this.chatContainer.addChild(this.streamingComponent);
-					this.streamingComponent.updateContent(this.streamingMessage);
-					this.ui.requestRender();
-				}
-				break;
-
-			case "message_update":
-				if (this.streamingComponent && event.message.role === "assistant") {
-					this.streamingMessage = event.message;
-					this.streamingComponent.updateContent(this.streamingMessage);
-
-					for (const content of this.streamingMessage.content) {
-						if (content.type === "toolCall") {
-							if (!this.pendingTools.has(content.id)) {
-								const component = new ToolExecutionComponent(
-									content.name,
-									content.arguments,
-									{
-										showImages: this.settingsManager.getShowImages(),
-									},
-									this.getRegisteredToolDefinition(content.name),
-									this.ui,
-								);
-								component.setExpanded(this.toolOutputExpanded);
-								this.chatContainer.addChild(component);
-								this.pendingTools.set(content.id, component);
-							} else {
-								const component = this.pendingTools.get(content.id);
-								if (component) {
-									component.updateArgs(content.arguments);
-								}
-							}
-						} else if (content.type === "serverToolUse") {
-							// Server-side tool (e.g., native web search) — show as pending tool execution
-							if (!this.pendingTools.has(content.id)) {
-								const component = new ToolExecutionComponent(
-									content.name,
-									content.input ?? {},
-									{
-										showImages: this.settingsManager.getShowImages(),
-									},
-									undefined,
-									this.ui,
-								);
-								component.setExpanded(this.toolOutputExpanded);
-								this.chatContainer.addChild(component);
-								this.pendingTools.set(content.id, component);
-							}
-						} else if (content.type === "webSearchResult") {
-							// Server-side tool result — resolve the pending server tool execution
-							const component = this.pendingTools.get(content.toolUseId);
-							if (component) {
-								const searchContent = content.content;
-								const isError = searchContent && typeof searchContent === "object" && "type" in (searchContent as any) && (searchContent as any).type === "web_search_tool_result_error";
-								const resultText = this.formatWebSearchResult(searchContent);
-								component.updateResult({
-									content: [{ type: "text", text: resultText }],
-									isError: !!isError,
-								});
-								this.pendingTools.delete(content.toolUseId);
-							}
-						}
-					}
-					this.ui.requestRender();
-				}
-				break;
-
-			case "message_end":
-				if (event.message.role === "user") break;
-				if (this.streamingComponent && event.message.role === "assistant") {
-					this.streamingMessage = event.message;
-					let errorMessage: string | undefined;
-					if (this.streamingMessage.stopReason === "aborted") {
-						const retryAttempt = this.session.retryAttempt;
-						errorMessage =
-							retryAttempt > 0
-								? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-								: "Operation aborted";
-						this.streamingMessage.errorMessage = errorMessage;
-					}
-					this.streamingComponent.updateContent(this.streamingMessage);
-
-					if (this.streamingMessage.stopReason === "aborted" || this.streamingMessage.stopReason === "error") {
-						if (!errorMessage) {
-							errorMessage = this.streamingMessage.errorMessage || "Error";
-						}
-						for (const [, component] of this.pendingTools.entries()) {
-							component.updateResult({
-								content: [{ type: "text", text: errorMessage }],
-								isError: true,
-							});
-						}
-						this.pendingTools.clear();
-					} else {
-						// Args are now complete - trigger diff computation for edit tools
-						for (const [, component] of this.pendingTools.entries()) {
-							component.setArgsComplete();
-						}
-					}
-					this.streamingComponent = undefined;
-					this.streamingMessage = undefined;
-					this.footer.invalidate();
-				}
-				this.ui.requestRender();
-				break;
-
-			case "tool_execution_start": {
-				if (!this.pendingTools.has(event.toolCallId)) {
-					const component = new ToolExecutionComponent(
-						event.toolName,
-						event.args,
-						{
-							showImages: this.settingsManager.getShowImages(),
-						},
-						this.getRegisteredToolDefinition(event.toolName),
-						this.ui,
-					);
-					component.setExpanded(this.toolOutputExpanded);
-					this.chatContainer.addChild(component);
-					this.pendingTools.set(event.toolCallId, component);
-					this.ui.requestRender();
-				}
-				break;
-			}
-
-			case "tool_execution_update": {
-				const component = this.pendingTools.get(event.toolCallId);
-				if (component) {
-					component.updateResult({ ...event.partialResult, isError: false }, true);
-					this.ui.requestRender();
-				}
-				break;
-			}
-
-			case "tool_execution_end": {
-				const component = this.pendingTools.get(event.toolCallId);
-				if (component) {
-					component.updateResult({ ...event.result, isError: event.isError });
-					this.pendingTools.delete(event.toolCallId);
-					this.ui.requestRender();
-				}
-				break;
-			}
-
-			case "agent_end":
-				if (this.loadingAnimation) {
-					this.loadingAnimation.stop();
-					this.loadingAnimation = undefined;
-					this.statusContainer.clear();
-				}
-				if (this.streamingComponent) {
-					this.chatContainer.removeChild(this.streamingComponent);
-					this.streamingComponent = undefined;
-					this.streamingMessage = undefined;
-				}
-				this.pendingTools.clear();
-
-				await this.checkShutdownRequested();
-
-				this.ui.requestRender();
-				break;
-
-			case "auto_compaction_start": {
-				// Keep editor active; submissions are queued during compaction.
-				// Set up escape to abort auto-compaction
-				this.autoCompactionEscapeHandler = this.defaultEditor.onEscape;
-				this.defaultEditor.onEscape = () => {
-					this.session.abortCompaction();
-				};
-				// Show compacting indicator with reason
-				this.statusContainer.clear();
-				const reasonText = event.reason === "overflow" ? "Context overflow detected, " : "";
-				this.autoCompactionLoader = new Loader(
-					this.ui,
-					(spinner) => theme.fg("accent", spinner),
-					(text) => theme.fg("muted", text),
-					`${reasonText}Auto-compacting... (${appKey(this.keybindings, "interrupt")} to cancel)`,
-				);
-				this.statusContainer.addChild(this.autoCompactionLoader);
-				this.ui.requestRender();
-				break;
-			}
-
-			case "auto_compaction_end": {
-				// Restore escape handler
-				if (this.autoCompactionEscapeHandler) {
-					this.defaultEditor.onEscape = this.autoCompactionEscapeHandler;
-					this.autoCompactionEscapeHandler = undefined;
-				}
-				// Stop loader
-				if (this.autoCompactionLoader) {
-					this.autoCompactionLoader.stop();
-					this.autoCompactionLoader = undefined;
-					this.statusContainer.clear();
-				}
-				// Handle result
-				if (event.aborted) {
-					this.showStatus("Auto-compaction cancelled");
-				} else if (event.result) {
-					// Rebuild chat to show compacted state
-					this.chatContainer.clear();
-					this.rebuildChatFromMessages();
-					// Add compaction component at bottom so user sees it without scrolling
-					this.addMessageToChat({
-						role: "compactionSummary",
-						tokensBefore: event.result.tokensBefore,
-						summary: event.result.summary,
-						timestamp: Date.now(),
-					});
-					this.footer.invalidate();
-				} else if (event.errorMessage) {
-					// Compaction failed (e.g., quota exceeded, API error)
-					this.chatContainer.addChild(new Spacer(1));
-					this.chatContainer.addChild(new Text(theme.fg("error", event.errorMessage), 1, 0));
-				}
-				void this.flushCompactionQueue({ willRetry: event.willRetry });
-				this.ui.requestRender();
-				break;
-			}
-
-			case "auto_retry_start": {
-				// Set up escape to abort retry
-				this.retryEscapeHandler = this.defaultEditor.onEscape;
-				this.defaultEditor.onEscape = () => {
-					this.session.abortRetry();
-				};
-				// Show retry indicator
-				this.statusContainer.clear();
-				const delaySeconds = Math.round(event.delayMs / 1000);
-				this.retryLoader = new Loader(
-					this.ui,
-					(spinner) => theme.fg("warning", spinner),
-					(text) => theme.fg("muted", text),
-					`Retrying (${event.attempt}/${event.maxAttempts}) in ${delaySeconds}s... (${appKey(this.keybindings, "interrupt")} to cancel)`,
-				);
-				this.statusContainer.addChild(this.retryLoader);
-				this.ui.requestRender();
-				break;
-			}
-
-			case "auto_retry_end": {
-				// Restore escape handler
-				if (this.retryEscapeHandler) {
-					this.defaultEditor.onEscape = this.retryEscapeHandler;
-					this.retryEscapeHandler = undefined;
-				}
-				// Stop loader
-				if (this.retryLoader) {
-					this.retryLoader.stop();
-					this.retryLoader = undefined;
-					this.statusContainer.clear();
-				}
-				// Show error only on final failure (success shows normal response)
-				if (!event.success) {
-					this.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
-				}
-				this.ui.requestRender();
-				break;
-			}
-
-			case "fallback_provider_switch": {
-				this.showStatus(`Switched from ${event.from} → ${event.to} (${event.reason})`);
-				this.ui.requestRender();
-				break;
-			}
-
-			case "fallback_provider_restored": {
-				this.showStatus(`Restored to ${event.provider}`);
-				this.ui.requestRender();
-				break;
-			}
-
-			case "fallback_chain_exhausted": {
-				this.showError(event.reason);
-				this.ui.requestRender();
-				break;
-			}
-		}
+		await handleAgentEvent(this as any, event);
 	}
 
 	/** Extract text content from a user message */
@@ -3299,73 +2860,20 @@ export class InteractiveMode {
 	}
 
 	private async handleModelCommand(searchTerm?: string): Promise<void> {
-		if (!searchTerm) {
-			this.showModelSelector();
-			return;
-		}
-
-		const model = await this.findExactModelMatch(searchTerm);
-		if (model) {
-			try {
-				await this.session.setModel(model);
-				this.footer.invalidate();
-				this.updateEditorBorderColor();
-				this.showStatus(`Model: ${model.id}`);
-				this.checkDaxnutsEasterEgg(model);
-			} catch (error) {
-				this.showError(error instanceof Error ? error.message : String(error));
-			}
-			return;
-		}
-
-		this.showModelSelector(searchTerm);
+		await handleModelCommandController(this, searchTerm);
 	}
 
 	private async findExactModelMatch(searchTerm: string): Promise<Model<any> | undefined> {
-		const term = searchTerm.trim();
-		if (!term) return undefined;
-
-		let targetProvider: string | undefined;
-		let targetModelId = "";
-
-		if (term.includes("/")) {
-			const parts = term.split("/", 2);
-			targetProvider = parts[0]?.trim().toLowerCase();
-			targetModelId = parts[1]?.trim().toLowerCase() ?? "";
-		} else {
-			targetModelId = term.toLowerCase();
-		}
-
-		if (!targetModelId) return undefined;
-
-		const models = await this.getModelCandidates();
-		const exactMatches = models.filter((item) => {
-			const idMatch = item.id.toLowerCase() === targetModelId;
-			const providerMatch = !targetProvider || item.provider.toLowerCase() === targetProvider;
-			return idMatch && providerMatch;
-		});
-
-		return exactMatches.length === 1 ? exactMatches[0] : undefined;
+		return findExactModelMatchController(this, searchTerm);
 	}
 
 	private async getModelCandidates(): Promise<Model<any>[]> {
-		if (this.session.scopedModels.length > 0) {
-			return this.session.scopedModels.map((scoped) => scoped.model);
-		}
-
-		this.session.modelRegistry.refresh();
-		try {
-			return await this.session.modelRegistry.getAvailable();
-		} catch {
-			return [];
-		}
+		return getModelCandidatesController(this);
 	}
 
 	/** Update the footer's available provider count from current model candidates */
 	private async updateAvailableProviderCount(): Promise<void> {
-		const models = await this.getModelCandidates();
-		const uniqueProviders = new Set(models.map((m) => m.provider));
-		this.footerDataProvider.setAvailableProviderCount(uniqueProviders.size);
+		await updateAvailableProviderCountController(this);
 	}
 
 	private showModelSelector(initialSearchInput?: string): void {
diff --git a/src/resource-loader.ts b/src/resource-loader.ts
index 03dc9acb0..c421d40bd 100644
--- a/src/resource-loader.ts
+++ b/src/resource-loader.ts
@@ -33,6 +33,13 @@ interface ManagedResourceManifest {
   syncedAt?: number
   /** Content fingerprint of bundled resources — detects same-version content changes. */
   contentHash?: string
+  /**
+   * Root-level files installed in extensions/ by this GSD version.
+   * Used on the next upgrade to detect and prune files that were removed or
+   * moved into a subdirectory, preventing orphaned non-extension files from
+   * causing extension load errors.
+   */
+  installedExtensionRootFiles?: string[]
 }
 
 export { discoverExtensionEntryPaths } from './extension-discovery.js'
@@ -60,10 +67,22 @@ function getBundledGsdVersion(): string {
 }
 
 function writeManagedResourceManifest(agentDir: string): void {
+  // Record root-level files currently in the bundled extensions source so that
+  // future upgrades can detect and prune any that get removed or moved.
+  let installedExtensionRootFiles: string[] = []
+  try {
+    if (existsSync(bundledExtensionsDir)) {
+      installedExtensionRootFiles = readdirSync(bundledExtensionsDir, { withFileTypes: true })
+        .filter(e => e.isFile())
+        .map(e => e.name)
+    }
+  } catch { /* non-fatal */ }
+
   const manifest: ManagedResourceManifest = {
     gsdVersion: getBundledGsdVersion(),
     syncedAt: Date.now(),
     contentHash: computeResourceFingerprint(),
+    installedExtensionRootFiles,
   }
   writeFileSync(getManagedResourceManifestPath(agentDir), JSON.stringify(manifest))
 }
@@ -266,6 +285,51 @@ function ensureNodeModulesSymlink(agentDir: string): void {
   }
 }
 
+/**
+ * Prune root-level extension files that were installed by a previous GSD version
+ * but have since been removed or relocated to a subdirectory.
+ *
+ * Two strategies:
+ * 1. Manifest-based (preferred): the manifest records which root files were installed
+ *    last time; any that are no longer in the current bundle are deleted.
+ * 2. Known-stale fallback: for upgrades from versions before manifest tracking,
+ *    explicitly delete files known to have been moved (e.g. env-utils.js → gsd/).
+ */
+function pruneRemovedBundledExtensions(
+  manifest: ManagedResourceManifest | null,
+  agentDir: string,
+): void {
+  const extensionsDir = join(agentDir, 'extensions')
+  if (!existsSync(extensionsDir)) return
+
+  // Current bundled root-level files (what the new version provides)
+  const currentSourceFiles = new Set<string>()
+  try {
+    if (existsSync(bundledExtensionsDir)) {
+      for (const e of readdirSync(bundledExtensionsDir, { withFileTypes: true })) {
+        if (e.isFile()) currentSourceFiles.add(e.name)
+      }
+    }
+  } catch { /* non-fatal */ }
+
+  const removeIfStale = (fileName: string) => {
+    if (currentSourceFiles.has(fileName)) return  // still in bundle, not stale
+    const stale = join(extensionsDir, fileName)
+    try { if (existsSync(stale)) rmSync(stale, { force: true }) } catch { /* non-fatal */ }
+  }
+
+  if (manifest?.installedExtensionRootFiles) {
+    // Manifest-based: remove previously-installed root files that are no longer bundled
+    for (const prevFile of manifest.installedExtensionRootFiles) {
+      removeIfStale(prevFile)
+    }
+  } else {
+    // Fallback: explicitly remove known stale files from pre-manifest-tracking versions
+    // env-utils.js was moved from extensions/ root → gsd/ in v2.39.x (#1634)
+    removeIfStale('env-utils.js')
+  }
+}
+
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
@@ -284,11 +348,18 @@ function ensureNodeModulesSymlink(agentDir: string): void {
 export function initResources(agentDir: string): void {
   mkdirSync(agentDir, { recursive: true })
 
+  const currentVersion = getBundledGsdVersion()
+  const manifest = readManagedResourceManifest(agentDir)
+
+  // Always prune root-level extension files that were removed from the bundle.
+  // This is cheap (a few existence checks + at most one rmSync) and must run
+  // unconditionally so that stale files left by a previous version are cleaned
+  // up even when the version/hash match causes the full sync to be skipped.
+  pruneRemovedBundledExtensions(manifest, agentDir)
+
   // Skip the full copy when both version AND content fingerprint match.
   // Version-only checks miss same-version content changes (npm link dev workflow,
   // hotfixes within a release). The content hash catches those at ~1ms cost.
-  const currentVersion = getBundledGsdVersion()
-  const manifest = readManagedResourceManifest(agentDir)
   if (manifest && manifest.gsdVersion === currentVersion) {
     // Version matches — check content fingerprint for same-version staleness.
     const currentHash = computeResourceFingerprint()
diff --git a/src/resources/extensions/get-secrets-from-user.ts b/src/resources/extensions/get-secrets-from-user.ts
index 58906c7d3..e80c0c0db 100644
--- a/src/resources/extensions/get-secrets-from-user.ts
+++ b/src/resources/extensions/get-secrets-from-user.ts
@@ -70,7 +70,7 @@ async function writeEnvKey(filePath: string, key: string, value: string): Promis
 // Re-export from env-utils.ts so existing consumers still work.
 // The implementation lives in env-utils.ts to avoid pulling @gsd/pi-tui
 // into modules that only need env-checking (e.g. files.ts during reports).
-import { checkExistingEnvKeys } from "./env-utils.js";
+import { checkExistingEnvKeys } from "./gsd/env-utils.js";
 export { checkExistingEnvKeys };
 
 /**
diff --git a/src/resources/extensions/gsd/auto-dashboard.ts b/src/resources/extensions/gsd/auto-dashboard.ts
index 5f44e763e..f2c77d168 100644
--- a/src/resources/extensions/gsd/auto-dashboard.ts
+++ b/src/resources/extensions/gsd/auto-dashboard.ts
@@ -390,6 +390,8 @@ export interface WidgetStateAccessors {
   getCmdCtx(): ExtensionCommandContext | null;
   getBasePath(): string;
   isVerbose(): boolean;
+  /** True while newSession() is in-flight — render must not access session state. */
+  isSessionSwitching(): boolean;
 }
 
 export function updateProgressWidget(
@@ -460,6 +462,14 @@ export function updateProgressWidget(
       render(width: number): string[] {
         if (cachedLines && cachedWidth === width) return cachedLines;
 
+        // While newSession() is in-flight, session state is mid-mutation.
+        // Accessing cmdCtx.sessionManager or cmdCtx.getContextUsage() can
+        // block the render loop and freeze the TUI. Return the last cached
+        // frame (or an empty frame on first render) until the switch settles.
+        if (accessors.isSessionSwitching()) {
+          return cachedLines ?? [];
+        }
+
         const ui = makeUI(theme, width);
         const lines: string[] = [];
         const pad = INDENT.base;
diff --git a/src/resources/extensions/gsd/auto-loop.ts b/src/resources/extensions/gsd/auto-loop.ts
index 080d92451..c45fcfafd 100644
--- a/src/resources/extensions/gsd/auto-loop.ts
+++ b/src/resources/extensions/gsd/auto-loop.ts
@@ -74,6 +74,47 @@ export interface UnitResult {
   event?: AgentEndEvent;
 }
 
+// ─── Phase pipeline types ────────────────────────────────────────────────────
+
+type PhaseResult<T = void> =
+  | { action: "continue" }
+  | { action: "break"; reason: string }
+  | { action: "next"; data: T }
+
+interface IterationContext {
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+  s: AutoSession;
+  deps: LoopDeps;
+  prefs: GSDPreferences | undefined;
+  iteration: number;
+}
+
+interface LoopState {
+  recentUnits: Array<{ key: string; error?: string }>;
+  stuckRecoveryAttempts: number;
+}
+
+interface PreDispatchData {
+  state: GSDState;
+  mid: string;
+  midTitle: string;
+}
+
+interface IterationData {
+  unitType: string;
+  unitId: string;
+  prompt: string;
+  finalPrompt: string;
+  pauseAfterUatDispatch: boolean;
+  observabilityIssues: unknown[];
+  state: GSDState;
+  mid: string | undefined;
+  midTitle: string | undefined;
+  isRetry: boolean;
+  previousTier: string | undefined;
+}
+
 // ─── Per-unit one-shot promise state ────────────────────────────────────────
 //
 // A single module-level resolve function scoped to the current unit execution.
@@ -656,6 +697,1031 @@ async function closeoutAndStop(
   await deps.stopAuto(ctx, pi, reason);
 }
 
+// ─── runPreDispatch ───────────────────────────────────────────────────────────
+
+/**
+ * Phase 1: Pre-dispatch — resource guard, health gate, state derivation,
+ * milestone transition, terminal conditions.
+ * Returns break to exit the loop, or next with PreDispatchData on success.
+ */
+async function runPreDispatch(
+  ic: IterationContext,
+  loopState: LoopState,
+): Promise<PhaseResult<PreDispatchData>> {
+  const { ctx, pi, s, deps, prefs } = ic;
+
+  // Resource version guard
+  const staleMsg = deps.checkResourcesStale(s.resourceVersionOnStart);
+  if (staleMsg) {
+    await deps.stopAuto(ctx, pi, staleMsg);
+    debugLog("autoLoop", { phase: "exit", reason: "resources-stale" });
+    return { action: "break", reason: "resources-stale" };
+  }
+
+  deps.invalidateAllCaches();
+  s.lastPromptCharCount = undefined;
+  s.lastBaselineCharCount = undefined;
+
+  // Pre-dispatch health gate
+  try {
+    const healthGate = await deps.preDispatchHealthGate(s.basePath);
+    if (healthGate.fixesApplied.length > 0) {
+      ctx.ui.notify(
+        `Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`,
+        "info",
+      );
+    }
+    if (!healthGate.proceed) {
+      ctx.ui.notify(
+        healthGate.reason ?? "Pre-dispatch health check failed.",
+        "error",
+      );
+      await deps.pauseAuto(ctx, pi);
+      debugLog("autoLoop", { phase: "exit", reason: "health-gate-failed" });
+      return { action: "break", reason: "health-gate-failed" };
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // Sync project root artifacts into worktree
+  if (
+    s.originalBasePath &&
+    s.basePath !== s.originalBasePath &&
+    s.currentMilestoneId
+  ) {
+    deps.syncProjectRootToWorktree(
+      s.originalBasePath,
+      s.basePath,
+      s.currentMilestoneId,
+    );
+  }
+
+  // Derive state
+  let state = await deps.deriveState(s.basePath);
+  deps.syncCmuxSidebar(prefs, state);
+  let mid = state.activeMilestone?.id;
+  let midTitle = state.activeMilestone?.title;
+  debugLog("autoLoop", {
+    phase: "state-derived",
+    iteration: ic.iteration,
+    mid,
+    statePhase: state.phase,
+  });
+
+  // ── Milestone transition ────────────────────────────────────────────
+  if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
+    ctx.ui.notify(
+      `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}: ${midTitle}.`,
+      "info",
+    );
+    deps.sendDesktopNotification(
+      "GSD",
+      `Milestone ${s.currentMilestoneId} complete!`,
+      "success",
+      "milestone",
+    );
+    deps.logCmuxEvent(
+      prefs,
+      `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`,
+      "success",
+    );
+
+    const vizPrefs = prefs;
+    if (vizPrefs?.auto_visualize) {
+      ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
+    }
+    if (vizPrefs?.auto_report !== false) {
+      try {
+        await generateMilestoneReport(s, ctx, s.currentMilestoneId!);
+      } catch (err) {
+        ctx.ui.notify(
+          `Report generation failed: ${err instanceof Error ? err.message : String(err)}`,
+          "warning",
+        );
+      }
+    }
+
+    // Reset dispatch counters for new milestone
+    s.unitDispatchCount.clear();
+    s.unitRecoveryCount.clear();
+    s.unitLifetimeDispatches.clear();
+    loopState.recentUnits.length = 0;
+    loopState.stuckRecoveryAttempts = 0;
+
+    // Worktree lifecycle on milestone transition — merge current, enter next
+    deps.resolver.mergeAndExit(s.currentMilestoneId!, ctx.ui);
+
+    // Opt-in: create draft PR on milestone completion
+    if (prefs?.git?.auto_pr) {
+      try {
+        const { createDraftPR } = await import("./git-service.js");
+        const prUrl = createDraftPR(
+          s.basePath,
+          s.currentMilestoneId!,
+          `[GSD] ${s.currentMilestoneId} complete`,
+          `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+        );
+        if (prUrl) {
+          ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+        }
+      } catch {
+        // Non-fatal — PR creation is best-effort
+      }
+    }
+
+    deps.invalidateAllCaches();
+
+    state = await deps.deriveState(s.basePath);
+    mid = state.activeMilestone?.id;
+    midTitle = state.activeMilestone?.title;
+
+    if (mid) {
+      if (deps.getIsolationMode() !== "none") {
+        deps.captureIntegrationBranch(s.basePath, mid, {
+          commitDocs: prefs?.git?.commit_docs,
+        });
+      }
+      deps.resolver.enterMilestone(mid, ctx.ui);
+    } else {
+      // mid is undefined — no milestone to capture integration branch for
+    }
+
+    const pendingIds = state.registry
+      .filter(
+        (m: { status: string }) =>
+          m.status !== "complete" && m.status !== "parked",
+      )
+      .map((m: { id: string }) => m.id);
+    deps.pruneQueueOrder(s.basePath, pendingIds);
+  }
+
+  if (mid) {
+    s.currentMilestoneId = mid;
+    deps.setActiveMilestoneId(s.basePath, mid);
+  }
+
+  // ── Terminal conditions ──────────────────────────────────────────────
+
+  if (!mid) {
+    if (s.currentUnit) {
+      await deps.closeoutUnit(
+        ctx,
+        s.basePath,
+        s.currentUnit.type,
+        s.currentUnit.id,
+        s.currentUnit.startedAt,
+        deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id),
+      );
+    }
+
+    const incomplete = state.registry.filter(
+      (m: { status: string }) =>
+        m.status !== "complete" && m.status !== "parked",
+    );
+    if (incomplete.length === 0 && state.registry.length > 0) {
+      // All milestones complete — merge milestone branch before stopping
+      if (s.currentMilestoneId) {
+        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+
+        // Opt-in: create draft PR on milestone completion
+        if (prefs?.git?.auto_pr) {
+          try {
+            const { createDraftPR } = await import("./git-service.js");
+            const prUrl = createDraftPR(
+              s.basePath,
+              s.currentMilestoneId,
+              `[GSD] ${s.currentMilestoneId} complete`,
+              `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+            );
+            if (prUrl) {
+              ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+            }
+          } catch {
+            // Non-fatal — PR creation is best-effort
+          }
+        }
+      }
+      deps.sendDesktopNotification(
+        "GSD",
+        "All milestones complete!",
+        "success",
+        "milestone",
+      );
+      deps.logCmuxEvent(
+        prefs,
+        "All milestones complete.",
+        "success",
+      );
+      await deps.stopAuto(ctx, pi, "All milestones complete");
+    } else if (incomplete.length === 0 && state.registry.length === 0) {
+      // Empty registry — no milestones visible, likely a path resolution bug
+      const diag = `basePath=${s.basePath}, phase=${state.phase}`;
+      ctx.ui.notify(
+        `No milestones visible in current scope. Possible path resolution issue.\n   Diagnostic: ${diag}`,
+        "error",
+      );
+      await deps.stopAuto(
+        ctx,
+        pi,
+        `No milestones found — check basePath resolution`,
+      );
+    } else if (state.phase === "blocked") {
+      const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+      await deps.stopAuto(ctx, pi, blockerMsg);
+      ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+      deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+      deps.logCmuxEvent(prefs, blockerMsg, "error");
+    } else {
+      const ids = incomplete.map((m: { id: string }) => m.id).join(", ");
+      const diag = `basePath=${s.basePath}, milestones=[${state.registry.map((m: { id: string; status: string }) => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
+      ctx.ui.notify(
+        `Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`,
+        "error",
+      );
+      await deps.stopAuto(
+        ctx,
+        pi,
+        `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`,
+      );
+    }
+    debugLog("autoLoop", { phase: "exit", reason: "no-active-milestone" });
+    return { action: "break", reason: "no-active-milestone" };
+  }
+
+  if (!midTitle) {
+    midTitle = mid;
+    ctx.ui.notify(
+      `Milestone ${mid} has no title in roadmap — using ID as fallback.`,
+      "warning",
+    );
+  }
+
+  // Mid-merge safety check
+  if (deps.reconcileMergeState(s.basePath, ctx)) {
+    deps.invalidateAllCaches();
+    state = await deps.deriveState(s.basePath);
+    mid = state.activeMilestone?.id;
+    midTitle = state.activeMilestone?.title;
+  }
+
+  if (!mid || !midTitle) {
+    const noMilestoneReason = !mid
+      ? "No active milestone after merge reconciliation"
+      : `Milestone ${mid} has no title after reconciliation`;
+    await closeoutAndStop(ctx, pi, s, deps, noMilestoneReason);
+    debugLog("autoLoop", {
+      phase: "exit",
+      reason: "no-milestone-after-reconciliation",
+    });
+    return { action: "break", reason: "no-milestone-after-reconciliation" };
+  }
+
+  // Terminal: complete
+  if (state.phase === "complete") {
+    // Milestone merge on complete (before closeout so branch state is clean)
+    if (s.currentMilestoneId) {
+      deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+
+      // Opt-in: create draft PR on milestone completion
+      if (prefs?.git?.auto_pr) {
+        try {
+          const { createDraftPR } = await import("./git-service.js");
+          const prUrl = createDraftPR(
+            s.basePath,
+            s.currentMilestoneId,
+            `[GSD] ${s.currentMilestoneId} complete`,
+            `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+          );
+          if (prUrl) {
+            ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+          }
+        } catch {
+          // Non-fatal — PR creation is best-effort
+        }
+      }
+    }
+    deps.sendDesktopNotification(
+      "GSD",
+      `Milestone ${mid} complete!`,
+      "success",
+      "milestone",
+    );
+    deps.logCmuxEvent(
+      prefs,
+      `Milestone ${mid} complete.`,
+      "success",
+    );
+    await closeoutAndStop(ctx, pi, s, deps, `Milestone ${mid} complete`);
+    debugLog("autoLoop", { phase: "exit", reason: "milestone-complete" });
+    return { action: "break", reason: "milestone-complete" };
+  }
+
+  // Terminal: blocked
+  if (state.phase === "blocked") {
+    const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+    await closeoutAndStop(ctx, pi, s, deps, blockerMsg);
+    ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+    deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+    deps.logCmuxEvent(prefs, blockerMsg, "error");
+    debugLog("autoLoop", { phase: "exit", reason: "blocked" });
+    return { action: "break", reason: "blocked" };
+  }
+
+  return { action: "next", data: { state, mid, midTitle } };
+}
+
+// ─── runDispatch ──────────────────────────────────────────────────────────────
+
+/**
+ * Phase 3: Dispatch resolution — resolve next unit, stuck detection, pre-dispatch hooks.
+ * Returns break/continue to control the loop, or next with IterationData on success.
+ */
+async function runDispatch(
+  ic: IterationContext,
+  preData: PreDispatchData,
+  loopState: LoopState,
+): Promise<PhaseResult<IterationData>> {
+  const { ctx, pi, s, deps, prefs } = ic;
+  const { state, mid, midTitle } = preData;
+  const STUCK_WINDOW_SIZE = 6;
+
+  debugLog("autoLoop", { phase: "dispatch-resolve", iteration: ic.iteration });
+  const dispatchResult = await deps.resolveDispatch({
+    basePath: s.basePath,
+    mid,
+    midTitle,
+    state,
+    prefs,
+    session: s,
+  });
+
+  if (dispatchResult.action === "stop") {
+    await closeoutAndStop(ctx, pi, s, deps, dispatchResult.reason);
+    debugLog("autoLoop", { phase: "exit", reason: "dispatch-stop" });
+    return { action: "break", reason: "dispatch-stop" };
+  }
+
+  if (dispatchResult.action !== "dispatch") {
+    // Non-dispatch action (e.g. "skip") — re-derive state
+    await new Promise((r) => setImmediate(r));
+    return { action: "continue" };
+  }
+
+  let unitType = dispatchResult.unitType;
+  let unitId = dispatchResult.unitId;
+  let prompt = dispatchResult.prompt;
+  const pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
+
+  // ── Sliding-window stuck detection with graduated recovery ──
+  const derivedKey = `${unitType}/${unitId}`;
+
+  if (!s.pendingVerificationRetry) {
+    loopState.recentUnits.push({ key: derivedKey });
+    if (loopState.recentUnits.length > STUCK_WINDOW_SIZE) loopState.recentUnits.shift();
+
+    const stuckSignal = detectStuck(loopState.recentUnits);
+    if (stuckSignal) {
+      debugLog("autoLoop", {
+        phase: "stuck-check",
+        unitType,
+        unitId,
+        reason: stuckSignal.reason,
+        recoveryAttempts: loopState.stuckRecoveryAttempts,
+      });
+
+      if (loopState.stuckRecoveryAttempts === 0) {
+        // Level 1: try verifying the artifact, then cache invalidation + retry
+        loopState.stuckRecoveryAttempts++;
+        const artifactExists = deps.verifyExpectedArtifact(
+          unitType,
+          unitId,
+          s.basePath,
+        );
+        if (artifactExists) {
+          debugLog("autoLoop", {
+            phase: "stuck-recovery",
+            level: 1,
+            action: "artifact-found",
+          });
+          ctx.ui.notify(
+            `Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`,
+            "info",
+          );
+          deps.invalidateAllCaches();
+          return { action: "continue" };
+        }
+        ctx.ui.notify(
+          `Stuck on ${unitType} ${unitId} (${stuckSignal.reason}). Invalidating caches and retrying.`,
+          "warning",
+        );
+        deps.invalidateAllCaches();
+      } else {
+        // Level 2: hard stop — genuinely stuck
+        debugLog("autoLoop", {
+          phase: "stuck-detected",
+          unitType,
+          unitId,
+          reason: stuckSignal.reason,
+        });
+        await deps.stopAuto(
+          ctx,
+          pi,
+          `Stuck: ${stuckSignal.reason}`,
+        );
+        ctx.ui.notify(
+          `Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}. The expected artifact was not written.`,
+          "error",
+        );
+        return { action: "break", reason: "stuck-detected" };
+      }
+    } else {
+      // Progress detected — reset recovery counter
+      if (loopState.stuckRecoveryAttempts > 0) {
+        debugLog("autoLoop", {
+          phase: "stuck-counter-reset",
+          from: loopState.recentUnits[loopState.recentUnits.length - 2]?.key ?? "",
+          to: derivedKey,
+        });
+        loopState.stuckRecoveryAttempts = 0;
+      }
+    }
+  }
+
+  // Pre-dispatch hooks
+  const preDispatchResult = deps.runPreDispatchHooks(
+    unitType,
+    unitId,
+    prompt,
+    s.basePath,
+  );
+  if (preDispatchResult.firedHooks.length > 0) {
+    ctx.ui.notify(
+      `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
+      "info",
+    );
+  }
+  if (preDispatchResult.action === "skip") {
+    ctx.ui.notify(
+      `Skipping ${unitType} ${unitId} (pre-dispatch hook).`,
+      "info",
+    );
+    await new Promise((r) => setImmediate(r));
+    return { action: "continue" };
+  }
+  if (preDispatchResult.action === "replace") {
+    prompt = preDispatchResult.prompt ?? prompt;
+    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
+  } else if (preDispatchResult.prompt) {
+    prompt = preDispatchResult.prompt;
+  }
+
+  const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
+    s.basePath,
+    deps.getMainBranch(s.basePath),
+    unitType,
+    unitId,
+  );
+  if (priorSliceBlocker) {
+    await deps.stopAuto(ctx, pi, priorSliceBlocker);
+    debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
+    return { action: "break", reason: "prior-slice-blocker" };
+  }
+
+  const observabilityIssues = await deps.collectObservabilityWarnings(
+    ctx,
+    s.basePath,
+    unitType,
+    unitId,
+  );
+
+  return {
+    action: "next",
+    data: {
+      unitType, unitId, prompt, finalPrompt: prompt,
+      pauseAfterUatDispatch, observabilityIssues,
+      state, mid, midTitle,
+      isRetry: false, previousTier: undefined,
+    },
+  };
+}
+
+// ─── runGuards ────────────────────────────────────────────────────────────────
+
+/**
+ * Phase 2: Guards — budget ceiling, context window, secrets re-check.
+ * Returns break to exit the loop, or next to proceed to dispatch.
+ */
+async function runGuards(
+  ic: IterationContext,
+  mid: string,
+): Promise<PhaseResult> {
+  const { ctx, pi, s, deps, prefs } = ic;
+
+  // Budget ceiling guard
+  const budgetCeiling = prefs?.budget_ceiling;
+  if (budgetCeiling !== undefined && budgetCeiling > 0) {
+    const currentLedger = deps.getLedger() as { units: unknown } | null;
+    const totalCost = currentLedger
+      ? deps.getProjectTotals(currentLedger.units).cost
+      : 0;
+    const budgetPct = totalCost / budgetCeiling;
+    const budgetAlertLevel = deps.getBudgetAlertLevel(budgetPct);
+    const newBudgetAlertLevel = deps.getNewBudgetAlertLevel(
+      s.lastBudgetAlertLevel,
+      budgetPct,
+    );
+    const enforcement = prefs?.budget_enforcement ?? "pause";
+    const budgetEnforcementAction = deps.getBudgetEnforcementAction(
+      enforcement,
+      budgetPct,
+    );
+
+    // Data-driven threshold check — loop descending, fire first match
+    const threshold = BUDGET_THRESHOLDS.find(
+      (t) => newBudgetAlertLevel >= t.pct,
+    );
+    if (threshold) {
+      s.lastBudgetAlertLevel =
+        newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
+
+      if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
+        // 100% — special enforcement logic (halt/pause/warn)
+        const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
+        if (budgetEnforcementAction === "halt") {
+          deps.sendDesktopNotification("GSD", msg, "error", "budget");
+          await deps.stopAuto(ctx, pi, "Budget ceiling reached");
+          debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
+          return { action: "break", reason: "budget-halt" };
+        }
+        if (budgetEnforcementAction === "pause") {
+          ctx.ui.notify(
+            `${msg} Pausing auto-mode — /gsd auto to override and continue.`,
+            "warning",
+          );
+          deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+          deps.logCmuxEvent(prefs, msg, "warning");
+          await deps.pauseAuto(ctx, pi);
+          debugLog("autoLoop", { phase: "exit", reason: "budget-pause" });
+          return { action: "break", reason: "budget-pause" };
+        }
+        ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
+        deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+        deps.logCmuxEvent(prefs, msg, "warning");
+      } else if (threshold.pct < 100) {
+        // Sub-100% — simple notification
+        const msg = `${threshold.label}: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`;
+        ctx.ui.notify(msg, threshold.notifyLevel);
+        deps.sendDesktopNotification(
+          "GSD",
+          msg,
+          threshold.notifyLevel,
+          "budget",
+        );
+        deps.logCmuxEvent(prefs, msg, threshold.cmuxLevel);
+      }
+    } else if (budgetAlertLevel === 0) {
+      s.lastBudgetAlertLevel = 0;
+    }
+  } else {
+    s.lastBudgetAlertLevel = 0;
+  }
+
+  // Context window guard
+  const contextThreshold = prefs?.context_pause_threshold ?? 0;
+  if (contextThreshold > 0 && s.cmdCtx) {
+    const contextUsage = s.cmdCtx.getContextUsage();
+    if (
+      contextUsage &&
+      contextUsage.percent !== null &&
+      contextUsage.percent >= contextThreshold
+    ) {
+      const msg = `Context window at ${contextUsage.percent}% (threshold: ${contextThreshold}%). Pausing to prevent truncated output.`;
+      ctx.ui.notify(
+        `${msg} Run /gsd auto to continue (will start fresh session).`,
+        "warning",
+      );
+      deps.sendDesktopNotification(
+        "GSD",
+        `Context ${contextUsage.percent}% — paused`,
+        "warning",
+        "attention",
+      );
+      await deps.pauseAuto(ctx, pi);
+      debugLog("autoLoop", { phase: "exit", reason: "context-window" });
+      return { action: "break", reason: "context-window" };
+    }
+  }
+
+  // Secrets re-check gate
+  try {
+    const manifestStatus = await deps.getManifestStatus(s.basePath, mid, s.originalBasePath);
+    if (manifestStatus && manifestStatus.pending.length > 0) {
+      const result = await deps.collectSecretsFromManifest(
+        s.basePath,
+        mid,
+        ctx,
+      );
+      if (
+        result &&
+        result.applied &&
+        result.skipped &&
+        result.existingSkipped
+      ) {
+        ctx.ui.notify(
+          `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
+          "info",
+        );
+      } else {
+        ctx.ui.notify("Secrets collection skipped.", "info");
+      }
+    }
+  } catch (err) {
+    ctx.ui.notify(
+      `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
+      "warning",
+    );
+  }
+
+  return { action: "next", data: undefined as void };
+}
+
+// ─── runUnitPhase ─────────────────────────────────────────────────────────────
+
+/**
+ * Phase 4: Unit execution — dispatch prompt, await agent_end, closeout, artifact verify.
+ * Returns break or next with unitStartedAt for downstream phases.
+ */
+async function runUnitPhase(
+  ic: IterationContext,
+  iterData: IterationData,
+  loopState: LoopState,
+  sidecarItem?: SidecarItem,
+): Promise<PhaseResult<{ unitStartedAt: number }>> {
+  const { ctx, pi, s, deps, prefs } = ic;
+  const { unitType, unitId, prompt, observabilityIssues, state, mid } = iterData;
+
+  debugLog("autoLoop", {
+    phase: "unit-execution",
+    iteration: ic.iteration,
+    unitType,
+    unitId,
+  });
+
+  // Detect retry and capture previous tier for escalation
+  const isRetry = !!(
+    s.currentUnit &&
+    s.currentUnit.type === unitType &&
+    s.currentUnit.id === unitId
+  );
+  const previousTier = s.currentUnitRouting?.tier;
+
+  s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
+  deps.captureAvailableSkills();
+  deps.writeUnitRuntimeRecord(
+    s.basePath,
+    unitType,
+    unitId,
+    s.currentUnit.startedAt,
+    {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: s.currentUnit.startedAt,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+    },
+  );
+
+  // Status bar + progress widget
+  ctx.ui.setStatus("gsd-auto", "auto");
+  if (mid)
+    deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
+  deps.updateProgressWidget(ctx, unitType, unitId, state);
+
+  deps.ensurePreconditions(unitType, unitId, s.basePath, state);
+
+  // Prompt injection
+  let finalPrompt = prompt;
+
+  if (s.pendingVerificationRetry) {
+    const retryCtx = s.pendingVerificationRetry;
+    s.pendingVerificationRetry = null;
+    const capped =
+      retryCtx.failureContext.length > MAX_RECOVERY_CHARS
+        ? retryCtx.failureContext.slice(0, MAX_RECOVERY_CHARS) +
+          "\n\n[...failure context truncated]"
+        : retryCtx.failureContext;
+    finalPrompt = `**VERIFICATION FAILED — AUTO-FIX ATTEMPT ${retryCtx.attempt}**\n\nThe verification gate ran after your previous attempt and found failures. Fix these issues before completing the task.\n\n${capped}\n\n---\n\n${finalPrompt}`;
+  }
+
+  if (s.pendingCrashRecovery) {
+    const capped =
+      s.pendingCrashRecovery.length > MAX_RECOVERY_CHARS
+        ? s.pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) +
+          "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
+        : s.pendingCrashRecovery;
+    finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
+    s.pendingCrashRecovery = null;
+  } else if ((s.unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
+    const diagnostic = deps.getDeepDiagnostic(s.basePath);
+    if (diagnostic) {
+      const cappedDiag =
+        diagnostic.length > MAX_RECOVERY_CHARS
+          ? diagnostic.slice(0, MAX_RECOVERY_CHARS) +
+            "\n\n[...diagnostic truncated to prevent memory exhaustion]"
+          : diagnostic;
+      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
+    }
+  }
+
+  const repairBlock =
+    deps.buildObservabilityRepairBlock(observabilityIssues);
+  if (repairBlock) {
+    finalPrompt = `${finalPrompt}${repairBlock}`;
+  }
+
+  // Prompt char measurement
+  s.lastPromptCharCount = finalPrompt.length;
+  s.lastBaselineCharCount = undefined;
+  if (deps.isDbAvailable()) {
+    try {
+      const { inlineGsdRootFile } = await importExtensionModule<typeof import("./auto-prompts.js")>(import.meta.url, "./auto-prompts.js");
+      const [decisionsContent, requirementsContent, projectContent] =
+        await Promise.all([
+          inlineGsdRootFile(s.basePath, "decisions.md", "Decisions"),
+          inlineGsdRootFile(s.basePath, "requirements.md", "Requirements"),
+          inlineGsdRootFile(s.basePath, "project.md", "Project"),
+        ]);
+      s.lastBaselineCharCount =
+        (decisionsContent?.length ?? 0) +
+        (requirementsContent?.length ?? 0) +
+        (projectContent?.length ?? 0);
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // Cache-optimize prompt section ordering
+  try {
+    finalPrompt = deps.reorderForCaching(finalPrompt);
+  } catch (reorderErr) {
+    const msg =
+      reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
+    process.stderr.write(
+      `[gsd] prompt reorder failed (non-fatal): ${msg}\n`,
+    );
+  }
+
+  // Select and apply model (with tier escalation on retry — normal units only)
+  const modelResult = await deps.selectAndApplyModel(
+    ctx,
+    pi,
+    unitType,
+    unitId,
+    s.basePath,
+    prefs,
+    s.verbose,
+    s.autoModeStartModel,
+    sidecarItem ? undefined : { isRetry, previousTier },
+  );
+  s.currentUnitRouting =
+    modelResult.routing as AutoSession["currentUnitRouting"];
+
+  // Start unit supervision
+  deps.clearUnitTimeout();
+  deps.startUnitSupervision({
+    s,
+    ctx,
+    pi,
+    unitType,
+    unitId,
+    prefs,
+    buildSnapshotOpts: () => deps.buildSnapshotOpts(unitType, unitId),
+    buildRecoveryContext: () => ({}),
+    pauseAuto: deps.pauseAuto,
+  });
+
+  // Session + send + await
+  const sessionFile = deps.getSessionFile(ctx);
+  deps.updateSessionLock(
+    deps.lockBase(),
+    unitType,
+    unitId,
+    s.completedUnits.length,
+    sessionFile,
+  );
+  deps.writeLock(
+    deps.lockBase(),
+    unitType,
+    unitId,
+    s.completedUnits.length,
+    sessionFile,
+  );
+
+  debugLog("autoLoop", {
+    phase: "runUnit-start",
+    iteration: ic.iteration,
+    unitType,
+    unitId,
+  });
+  const unitResult = await runUnit(
+    ctx,
+    pi,
+    s,
+    unitType,
+    unitId,
+    finalPrompt,
+  );
+  debugLog("autoLoop", {
+    phase: "runUnit-end",
+    iteration: ic.iteration,
+    unitType,
+    unitId,
+    status: unitResult.status,
+  });
+
+  // Tag the most recent window entry with error info for stuck detection
+  if (unitResult.status === "error" || unitResult.status === "cancelled") {
+    const lastEntry = loopState.recentUnits[loopState.recentUnits.length - 1];
+    if (lastEntry) {
+      lastEntry.error = `${unitResult.status}:${unitType}/${unitId}`;
+    }
+  } else if (unitResult.event?.messages?.length) {
+    const lastMsg = unitResult.event.messages[unitResult.event.messages.length - 1];
+    const msgStr = typeof lastMsg === "string" ? lastMsg : JSON.stringify(lastMsg);
+    if (/error|fail|exception/i.test(msgStr)) {
+      const lastEntry = loopState.recentUnits[loopState.recentUnits.length - 1];
+      if (lastEntry) {
+        lastEntry.error = msgStr.slice(0, 200);
+      }
+    }
+  }
+
+  if (unitResult.status === "cancelled") {
+    ctx.ui.notify(
+      `Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`,
+      "warning",
+    );
+    await deps.stopAuto(ctx, pi, "Session creation failed");
+    debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
+    return { action: "break", reason: "session-failed" };
+  }
+
+  // ── Immediate unit closeout (metrics, activity log, memory) ────────
+  // Run right after runUnit() returns so telemetry is never lost to a
+  // crash between iterations.
+  await deps.closeoutUnit(
+    ctx,
+    s.basePath,
+    unitType,
+    unitId,
+    s.currentUnit.startedAt,
+    deps.buildSnapshotOpts(unitType, unitId),
+  );
+
+  if (s.currentUnitRouting) {
+    deps.recordOutcome(
+      unitType,
+      s.currentUnitRouting.tier as "light" | "standard" | "heavy",
+      true, // success assumed; dispatch will re-dispatch if artifact missing
+    );
+  }
+
+  const isHookUnit = unitType.startsWith("hook/");
+  const artifactVerified =
+    isHookUnit ||
+    deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
+  if (artifactVerified) {
+    s.completedUnits.push({
+      type: unitType,
+      id: unitId,
+      startedAt: s.currentUnit.startedAt,
+      finishedAt: Date.now(),
+    });
+    if (s.completedUnits.length > 200) {
+      s.completedUnits = s.completedUnits.slice(-200);
+    }
+    // Flush completed-units to disk so the record survives crashes
+    try {
+      const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
+      const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
+      atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
+    } catch { /* non-fatal: disk flush failure */ }
+
+    deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
+    s.unitDispatchCount.delete(`${unitType}/${unitId}`);
+    s.unitRecoveryCount.delete(`${unitType}/${unitId}`);
+  }
+
+  return { action: "next", data: { unitStartedAt: s.currentUnit.startedAt } };
+}
+
+// ─── runFinalize ──────────────────────────────────────────────────────────────
+
+/**
+ * Phase 5: Post-unit finalize — pre/post verification, UAT pause, step-wizard.
+ * Returns break/continue/next to control the outer loop.
+ */
+async function runFinalize(
+  ic: IterationContext,
+  iterData: IterationData,
+  sidecarItem?: SidecarItem,
+): Promise<PhaseResult> {
+  const { ctx, pi, s, deps } = ic;
+  const { pauseAfterUatDispatch } = iterData;
+
+  debugLog("autoLoop", { phase: "finalize", iteration: ic.iteration });
+
+  // Clear unit timeout (unit completed)
+  deps.clearUnitTimeout();
+
+  // Post-unit context for pre/post verification
+  const postUnitCtx: PostUnitContext = {
+    s,
+    ctx,
+    pi,
+    buildSnapshotOpts: deps.buildSnapshotOpts,
+    lockBase: deps.lockBase,
+    stopAuto: deps.stopAuto,
+    pauseAuto: deps.pauseAuto,
+    updateProgressWidget: deps.updateProgressWidget,
+  };
+
+  // Pre-verification processing (commit, doctor, state rebuild, etc.)
+  // Sidecar items use lightweight pre-verification opts
+  const preVerificationOpts: PreVerificationOpts | undefined = sidecarItem
+    ? sidecarItem.kind === "hook"
+      ? { skipSettleDelay: true, skipDoctor: true, skipStateRebuild: true, skipWorktreeSync: true }
+      : { skipSettleDelay: true, skipStateRebuild: true }
+    : undefined;
+  const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts);
+  if (preResult === "dispatched") {
+    debugLog("autoLoop", {
+      phase: "exit",
+      reason: "pre-verification-dispatched",
+    });
+    return { action: "break", reason: "pre-verification-dispatched" };
+  }
+
+  if (pauseAfterUatDispatch) {
+    ctx.ui.notify(
+      "UAT requires human execution. Auto-mode will pause after this unit writes the result file.",
+      "info",
+    );
+    await deps.pauseAuto(ctx, pi);
+    debugLog("autoLoop", { phase: "exit", reason: "uat-pause" });
+    return { action: "break", reason: "uat-pause" };
+  }
+
+  // Verification gate
+  // Hook sidecar items skip verification entirely.
+  // Non-hook sidecar items run verification but skip retries (just continue).
+  const skipVerification = sidecarItem?.kind === "hook";
+  if (!skipVerification) {
+    const verificationResult = await deps.runPostUnitVerification(
+      { s, ctx, pi },
+      deps.pauseAuto,
+    );
+
+    if (verificationResult === "pause") {
+      debugLog("autoLoop", { phase: "exit", reason: "verification-pause" });
+      return { action: "break", reason: "verification-pause" };
+    }
+
+    if (verificationResult === "retry") {
+      if (sidecarItem) {
+        // Sidecar verification retries are skipped — just continue
+        debugLog("autoLoop", { phase: "sidecar-verification-retry-skipped", iteration: ic.iteration });
+      } else {
+        // s.pendingVerificationRetry was set by runPostUnitVerification.
+        // Continue the loop — next iteration will inject the retry context into the prompt.
+        debugLog("autoLoop", { phase: "verification-retry", iteration: ic.iteration });
+        return { action: "continue" };
+      }
+    }
+  }
+
+  // Post-verification processing (DB dual-write, hooks, triage, quick-tasks)
+  const postResult = await deps.postUnitPostVerification(postUnitCtx);
+
+  if (postResult === "stopped") {
+    debugLog("autoLoop", {
+      phase: "exit",
+      reason: "post-verification-stopped",
+    });
+    return { action: "break", reason: "post-verification-stopped" };
+  }
+
+  if (postResult === "step-wizard") {
+    // Step mode — exit the loop (caller handles wizard)
+    debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
+    return { action: "break", reason: "step-wizard" };
+  }
+
+  return { action: "next", data: undefined as void };
+}
+
 // ─── autoLoop ────────────────────────────────────────────────────────────────
 
 /**
@@ -674,11 +1740,7 @@ export async function autoLoop(
 ): Promise<void> {
   debugLog("autoLoop", { phase: "enter" });
   let iteration = 0;
-  // ── Sliding-window stuck detection ──
-  const recentUnits: Array<{ key: string; error?: string }> = [];
-  const STUCK_WINDOW_SIZE = 6;
-  let stuckRecoveryAttempts = 0;
-
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
   let consecutiveErrors = 0;
 
   while (s.active) {
@@ -740,973 +1802,51 @@ export async function autoLoop(
         }
       }
 
-      // Variables shared between the sidecar and normal paths
-      let unitType: string;
-      let unitId: string;
-      let prompt: string;
-      let pauseAfterUatDispatch = false;
-      let state: GSDState;
-      let mid: string | undefined;
-      let midTitle: string | undefined;
-      let observabilityIssues: unknown[] = [];
+      const ic: IterationContext = { ctx, pi, s, deps, prefs, iteration };
+      let iterData: IterationData;
 
       if (!sidecarItem) {
-      // ── Phase 1: Pre-dispatch ───────────────────────────────────────────
+        // ── Phase 1: Pre-dispatch ─────────────────────────────────────────
+        const preDispatchResult = await runPreDispatch(ic, loopState);
+        if (preDispatchResult.action === "break") break;
+        if (preDispatchResult.action === "continue") continue;
 
-      // Resource version guard
-      const staleMsg = deps.checkResourcesStale(s.resourceVersionOnStart);
-      if (staleMsg) {
-        await deps.stopAuto(ctx, pi, staleMsg);
-        debugLog("autoLoop", { phase: "exit", reason: "resources-stale" });
-        break;
-      }
+        const preData = preDispatchResult.data;
 
-      deps.invalidateAllCaches();
-      s.lastPromptCharCount = undefined;
-      s.lastBaselineCharCount = undefined;
-
-      // Pre-dispatch health gate
-      try {
-        const healthGate = await deps.preDispatchHealthGate(s.basePath);
-        if (healthGate.fixesApplied.length > 0) {
-          ctx.ui.notify(
-            `Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`,
-            "info",
-          );
-        }
-        if (!healthGate.proceed) {
-          ctx.ui.notify(
-            healthGate.reason ?? "Pre-dispatch health check failed.",
-            "error",
-          );
-          await deps.pauseAuto(ctx, pi);
-          debugLog("autoLoop", { phase: "exit", reason: "health-gate-failed" });
-          break;
-        }
-      } catch {
-        // Non-fatal
-      }
-
-      // Sync project root artifacts into worktree
-      if (
-        s.originalBasePath &&
-        s.basePath !== s.originalBasePath &&
-        s.currentMilestoneId
-      ) {
-        deps.syncProjectRootToWorktree(
-          s.originalBasePath,
-          s.basePath,
-          s.currentMilestoneId,
-        );
-      }
-
-      // Derive state
-      state = await deps.deriveState(s.basePath);
-      deps.syncCmuxSidebar(prefs, state);
-      mid = state.activeMilestone?.id;
-      midTitle = state.activeMilestone?.title;
-      debugLog("autoLoop", {
-        phase: "state-derived",
-        iteration,
-        mid,
-        statePhase: state.phase,
-      });
-
-      // ── Milestone transition ────────────────────────────────────────────
-      if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
-        ctx.ui.notify(
-          `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}: ${midTitle}.`,
-          "info",
-        );
-        deps.sendDesktopNotification(
-          "GSD",
-          `Milestone ${s.currentMilestoneId} complete!`,
-          "success",
-          "milestone",
-        );
-        deps.logCmuxEvent(
-          prefs,
-          `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`,
-          "success",
-        );
-
-        const vizPrefs = prefs;
-        if (vizPrefs?.auto_visualize) {
-          ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
-        }
-        if (vizPrefs?.auto_report !== false) {
-          try {
-            await generateMilestoneReport(s, ctx, s.currentMilestoneId!);
-          } catch (err) {
-            ctx.ui.notify(
-              `Report generation failed: ${err instanceof Error ? err.message : String(err)}`,
-              "warning",
-            );
-          }
-        }
-
-        // Reset dispatch counters for new milestone
-        s.unitDispatchCount.clear();
-        s.unitRecoveryCount.clear();
-        s.unitLifetimeDispatches.clear();
-        recentUnits.length = 0;
-        stuckRecoveryAttempts = 0;
-
-        // Worktree lifecycle on milestone transition — merge current, enter next
-        deps.resolver.mergeAndExit(s.currentMilestoneId!, ctx.ui);
-
-        // Opt-in: create draft PR on milestone completion
-        if (prefs?.git?.auto_pr) {
-          try {
-            const { createDraftPR } = await import("./git-service.js");
-            const prUrl = createDraftPR(
-              s.basePath,
-              s.currentMilestoneId!,
-              `[GSD] ${s.currentMilestoneId} complete`,
-              `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
-            );
-            if (prUrl) {
-              ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-            }
-          } catch {
-            // Non-fatal — PR creation is best-effort
-          }
-        }
-
-        deps.invalidateAllCaches();
-
-        state = await deps.deriveState(s.basePath);
-        mid = state.activeMilestone?.id;
-        midTitle = state.activeMilestone?.title;
-
-        if (mid) {
-          if (deps.getIsolationMode() !== "none") {
-            deps.captureIntegrationBranch(s.basePath, mid, {
-              commitDocs: prefs?.git?.commit_docs,
-            });
-          }
-          deps.resolver.enterMilestone(mid, ctx.ui);
-        } else {
-          // mid is undefined — no milestone to capture integration branch for
-        }
-
-        const pendingIds = state.registry
-          .filter(
-            (m: { status: string }) =>
-              m.status !== "complete" && m.status !== "parked",
-          )
-          .map((m: { id: string }) => m.id);
-        deps.pruneQueueOrder(s.basePath, pendingIds);
-      }
-
-      if (mid) {
-        s.currentMilestoneId = mid;
-        deps.setActiveMilestoneId(s.basePath, mid);
-      }
-
-      // ── Terminal conditions ──────────────────────────────────────────────
-
-      if (!mid) {
-        if (s.currentUnit) {
-          await deps.closeoutUnit(
-            ctx,
-            s.basePath,
-            s.currentUnit.type,
-            s.currentUnit.id,
-            s.currentUnit.startedAt,
-            deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id),
-          );
-        }
-
-        const incomplete = state.registry.filter(
-          (m: { status: string }) =>
-            m.status !== "complete" && m.status !== "parked",
-        );
-        if (incomplete.length === 0 && state.registry.length > 0) {
-          // All milestones complete — merge milestone branch before stopping
-          if (s.currentMilestoneId) {
-            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-
-            // Opt-in: create draft PR on milestone completion
-            if (prefs?.git?.auto_pr) {
-              try {
-                const { createDraftPR } = await import("./git-service.js");
-                const prUrl = createDraftPR(
-                  s.basePath,
-                  s.currentMilestoneId,
-                  `[GSD] ${s.currentMilestoneId} complete`,
-                  `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
-                );
-                if (prUrl) {
-                  ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                }
-              } catch {
-                // Non-fatal — PR creation is best-effort
-              }
-            }
-          }
-          deps.sendDesktopNotification(
-            "GSD",
-            "All milestones complete!",
-            "success",
-            "milestone",
-          );
-          deps.logCmuxEvent(
-            prefs,
-            "All milestones complete.",
-            "success",
-          );
-          await deps.stopAuto(ctx, pi, "All milestones complete");
-        } else if (incomplete.length === 0 && state.registry.length === 0) {
-          // Empty registry — no milestones visible, likely a path resolution bug
-          const diag = `basePath=${s.basePath}, phase=${state.phase}`;
-          ctx.ui.notify(
-            `No milestones visible in current scope. Possible path resolution issue.\n   Diagnostic: ${diag}`,
-            "error",
-          );
-          await deps.stopAuto(
-            ctx,
-            pi,
-            `No milestones found — check basePath resolution`,
-          );
-        } else if (state.phase === "blocked") {
-          const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-          await deps.stopAuto(ctx, pi, blockerMsg);
-          ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-          deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
-          deps.logCmuxEvent(prefs, blockerMsg, "error");
-        } else {
-          const ids = incomplete.map((m: { id: string }) => m.id).join(", ");
-          const diag = `basePath=${s.basePath}, milestones=[${state.registry.map((m: { id: string; status: string }) => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
-          ctx.ui.notify(
-            `Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`,
-            "error",
-          );
-          await deps.stopAuto(
-            ctx,
-            pi,
-            `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`,
-          );
-        }
-        debugLog("autoLoop", { phase: "exit", reason: "no-active-milestone" });
-        break;
-      }
-
-      if (!midTitle) {
-        midTitle = mid;
-        ctx.ui.notify(
-          `Milestone ${mid} has no title in roadmap — using ID as fallback.`,
-          "warning",
-        );
-      }
-
-      // Mid-merge safety check
-      if (deps.reconcileMergeState(s.basePath, ctx)) {
-        deps.invalidateAllCaches();
-        state = await deps.deriveState(s.basePath);
-        mid = state.activeMilestone?.id;
-        midTitle = state.activeMilestone?.title;
-      }
-
-      if (!mid || !midTitle) {
-        const noMilestoneReason = !mid
-          ? "No active milestone after merge reconciliation"
-          : `Milestone ${mid} has no title after reconciliation`;
-        await closeoutAndStop(ctx, pi, s, deps, noMilestoneReason);
-        debugLog("autoLoop", {
-          phase: "exit",
-          reason: "no-milestone-after-reconciliation",
-        });
-        break;
-      }
-
-      // Terminal: complete
-      if (state.phase === "complete") {
-        // Milestone merge on complete (before closeout so branch state is clean)
-        if (s.currentMilestoneId) {
-          deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-
-          // Opt-in: create draft PR on milestone completion
-          if (prefs?.git?.auto_pr) {
-            try {
-              const { createDraftPR } = await import("./git-service.js");
-              const prUrl = createDraftPR(
-                s.basePath,
-                s.currentMilestoneId,
-                `[GSD] ${s.currentMilestoneId} complete`,
-                `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
-              );
-              if (prUrl) {
-                ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-              }
-            } catch {
-              // Non-fatal — PR creation is best-effort
-            }
-          }
-        }
-        deps.sendDesktopNotification(
-          "GSD",
-          `Milestone ${mid} complete!`,
-          "success",
-          "milestone",
-        );
-        deps.logCmuxEvent(
-          prefs,
-          `Milestone ${mid} complete.`,
-          "success",
-        );
-        await closeoutAndStop(ctx, pi, s, deps, `Milestone ${mid} complete`);
-        debugLog("autoLoop", { phase: "exit", reason: "milestone-complete" });
-        break;
-      }
-
-      // Terminal: blocked
-      if (state.phase === "blocked") {
-        const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-        await closeoutAndStop(ctx, pi, s, deps, blockerMsg);
-        ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-        deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
-        deps.logCmuxEvent(prefs, blockerMsg, "error");
-        debugLog("autoLoop", { phase: "exit", reason: "blocked" });
-        break;
-      }
-
-      // ── Phase 2: Guards ─────────────────────────────────────────────────
-
-      // Budget ceiling guard
-      const budgetCeiling = prefs?.budget_ceiling;
-      if (budgetCeiling !== undefined && budgetCeiling > 0) {
-        const currentLedger = deps.getLedger() as { units: unknown } | null;
-        const totalCost = currentLedger
-          ? deps.getProjectTotals(currentLedger.units).cost
-          : 0;
-        const budgetPct = totalCost / budgetCeiling;
-        const budgetAlertLevel = deps.getBudgetAlertLevel(budgetPct);
-        const newBudgetAlertLevel = deps.getNewBudgetAlertLevel(
-          s.lastBudgetAlertLevel,
-          budgetPct,
-        );
-        const enforcement = prefs?.budget_enforcement ?? "pause";
-        const budgetEnforcementAction = deps.getBudgetEnforcementAction(
-          enforcement,
-          budgetPct,
-        );
-
-        // Data-driven threshold check — loop descending, fire first match
-        const threshold = BUDGET_THRESHOLDS.find(
-          (t) => newBudgetAlertLevel >= t.pct,
-        );
-        if (threshold) {
-          s.lastBudgetAlertLevel =
-            newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
-
-          if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
-            // 100% — special enforcement logic (halt/pause/warn)
-            const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
-            if (budgetEnforcementAction === "halt") {
-              deps.sendDesktopNotification("GSD", msg, "error", "budget");
-              await deps.stopAuto(ctx, pi, "Budget ceiling reached");
-              debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
-              break;
-            }
-            if (budgetEnforcementAction === "pause") {
-              ctx.ui.notify(
-                `${msg} Pausing auto-mode — /gsd auto to override and continue.`,
-                "warning",
-              );
-              deps.sendDesktopNotification("GSD", msg, "warning", "budget");
-              deps.logCmuxEvent(prefs, msg, "warning");
-              await deps.pauseAuto(ctx, pi);
-              debugLog("autoLoop", { phase: "exit", reason: "budget-pause" });
-              break;
-            }
-            ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
-            deps.sendDesktopNotification("GSD", msg, "warning", "budget");
-            deps.logCmuxEvent(prefs, msg, "warning");
-          } else if (threshold.pct < 100) {
-            // Sub-100% — simple notification
-            const msg = `${threshold.label}: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`;
-            ctx.ui.notify(msg, threshold.notifyLevel);
-            deps.sendDesktopNotification(
-              "GSD",
-              msg,
-              threshold.notifyLevel,
-              "budget",
-            );
-            deps.logCmuxEvent(prefs, msg, threshold.cmuxLevel);
-          }
-        } else if (budgetAlertLevel === 0) {
-          s.lastBudgetAlertLevel = 0;
-        }
-      } else {
-        s.lastBudgetAlertLevel = 0;
-      }
-
-      // Context window guard
-      const contextThreshold = prefs?.context_pause_threshold ?? 0;
-      if (contextThreshold > 0 && s.cmdCtx) {
-        const contextUsage = s.cmdCtx.getContextUsage();
-        if (
-          contextUsage &&
-          contextUsage.percent !== null &&
-          contextUsage.percent >= contextThreshold
-        ) {
-          const msg = `Context window at ${contextUsage.percent}% (threshold: ${contextThreshold}%). Pausing to prevent truncated output.`;
-          ctx.ui.notify(
-            `${msg} Run /gsd auto to continue (will start fresh session).`,
-            "warning",
-          );
-          deps.sendDesktopNotification(
-            "GSD",
-            `Context ${contextUsage.percent}% — paused`,
-            "warning",
-            "attention",
-          );
-          await deps.pauseAuto(ctx, pi);
-          debugLog("autoLoop", { phase: "exit", reason: "context-window" });
-          break;
-        }
-      }
-
-      // Secrets re-check gate
-      try {
-        const manifestStatus = await deps.getManifestStatus(s.basePath, mid, s.originalBasePath);
-        if (manifestStatus && manifestStatus.pending.length > 0) {
-          const result = await deps.collectSecretsFromManifest(
-            s.basePath,
-            mid,
-            ctx,
-          );
-          if (
-            result &&
-            result.applied &&
-            result.skipped &&
-            result.existingSkipped
-          ) {
-            ctx.ui.notify(
-              `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
-              "info",
-            );
-          } else {
-            ctx.ui.notify("Secrets collection skipped.", "info");
-          }
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
-          "warning",
-        );
-      }
-
-      // ── Phase 3: Dispatch resolution ────────────────────────────────────
-
-      debugLog("autoLoop", { phase: "dispatch-resolve", iteration });
-      const dispatchResult = await deps.resolveDispatch({
-        basePath: s.basePath,
-        mid,
-        midTitle: midTitle!,
-        state,
-        prefs,
-        session: s,
-      });
-
-      if (dispatchResult.action === "stop") {
-        await closeoutAndStop(ctx, pi, s, deps, dispatchResult.reason);
-        debugLog("autoLoop", { phase: "exit", reason: "dispatch-stop" });
-        break;
-      }
-
-      if (dispatchResult.action !== "dispatch") {
-        // Non-dispatch action (e.g. "skip") — re-derive state
-        await new Promise((r) => setImmediate(r));
-        continue;
-      }
-
-      unitType = dispatchResult.unitType;
-      unitId = dispatchResult.unitId;
-      prompt = dispatchResult.prompt;
-      pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
-
-      // ── Sliding-window stuck detection with graduated recovery ──
-      const derivedKey = `${unitType}/${unitId}`;
-
-      if (!s.pendingVerificationRetry) {
-        recentUnits.push({ key: derivedKey });
-        if (recentUnits.length > STUCK_WINDOW_SIZE) recentUnits.shift();
-
-        const stuckSignal = detectStuck(recentUnits);
-        if (stuckSignal) {
-          debugLog("autoLoop", {
-            phase: "stuck-check",
-            unitType,
-            unitId,
-            reason: stuckSignal.reason,
-            recoveryAttempts: stuckRecoveryAttempts,
-          });
-
-          if (stuckRecoveryAttempts === 0) {
-            // Level 1: try verifying the artifact, then cache invalidation + retry
-            stuckRecoveryAttempts++;
-            const artifactExists = deps.verifyExpectedArtifact(
-              unitType,
-              unitId,
-              s.basePath,
-            );
-            if (artifactExists) {
-              debugLog("autoLoop", {
-                phase: "stuck-recovery",
-                level: 1,
-                action: "artifact-found",
-              });
-              ctx.ui.notify(
-                `Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`,
-                "info",
-              );
-              deps.invalidateAllCaches();
-              continue;
-            }
-            ctx.ui.notify(
-              `Stuck on ${unitType} ${unitId} (${stuckSignal.reason}). Invalidating caches and retrying.`,
-              "warning",
-            );
-            deps.invalidateAllCaches();
-          } else {
-            // Level 2: hard stop — genuinely stuck
-            debugLog("autoLoop", {
-              phase: "stuck-detected",
-              unitType,
-              unitId,
-              reason: stuckSignal.reason,
-            });
-            await deps.stopAuto(
-              ctx,
-              pi,
-              `Stuck: ${stuckSignal.reason}`,
-            );
-            ctx.ui.notify(
-              `Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}. The expected artifact was not written.`,
-              "error",
-            );
-            break;
-          }
-        } else {
-          // Progress detected — reset recovery counter
-          if (stuckRecoveryAttempts > 0) {
-            debugLog("autoLoop", {
-              phase: "stuck-counter-reset",
-              from: recentUnits[recentUnits.length - 2]?.key ?? "",
-              to: derivedKey,
-            });
-            stuckRecoveryAttempts = 0;
-          }
-        }
-      }
-
-      // Pre-dispatch hooks
-      const preDispatchResult = deps.runPreDispatchHooks(
-        unitType,
-        unitId,
-        prompt,
-        s.basePath,
-      );
-      if (preDispatchResult.firedHooks.length > 0) {
-        ctx.ui.notify(
-          `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
-          "info",
-        );
-      }
-      if (preDispatchResult.action === "skip") {
-        ctx.ui.notify(
-          `Skipping ${unitType} ${unitId} (pre-dispatch hook).`,
-          "info",
-        );
-        await new Promise((r) => setImmediate(r));
-        continue;
-      }
-      if (preDispatchResult.action === "replace") {
-        prompt = preDispatchResult.prompt ?? prompt;
-        if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
-      } else if (preDispatchResult.prompt) {
-        prompt = preDispatchResult.prompt;
-      }
-
-      const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
-        s.basePath,
-        deps.getMainBranch(s.basePath),
-        unitType,
-        unitId,
-      );
-      if (priorSliceBlocker) {
-        await deps.stopAuto(ctx, pi, priorSliceBlocker);
-        debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
-        break;
-      }
-
-      observabilityIssues = await deps.collectObservabilityWarnings(
-        ctx,
-        s.basePath,
-        unitType,
-        unitId,
-      );
-
-      // Derive state for shared use in execution phase
-      // (state, mid, midTitle already set above)
+        // ── Phase 2: Guards ───────────────────────────────────────────────
+        const guardsResult = await runGuards(ic, preData.mid);
+        if (guardsResult.action === "break") break;
 
+        // ── Phase 3: Dispatch ─────────────────────────────────────────────
+        const dispatchResult = await runDispatch(ic, preData, loopState);
+        if (dispatchResult.action === "break") break;
+        if (dispatchResult.action === "continue") continue;
+        iterData = dispatchResult.data;
       } else {
         // ── Sidecar path: use values from the sidecar item directly ──
-        unitType = sidecarItem.unitType;
-        unitId = sidecarItem.unitId;
-        prompt = sidecarItem.prompt;
-        // Derive minimal state for progress widget / execution context
-        state = await deps.deriveState(s.basePath);
-        mid = state.activeMilestone?.id;
-        midTitle = state.activeMilestone?.title;
+        const sidecarState = await deps.deriveState(s.basePath);
+        iterData = {
+          unitType: sidecarItem.unitType,
+          unitId: sidecarItem.unitId,
+          prompt: sidecarItem.prompt,
+          finalPrompt: sidecarItem.prompt,
+          pauseAfterUatDispatch: false,
+          observabilityIssues: [],
+          state: sidecarState,
+          mid: sidecarState.activeMilestone?.id,
+          midTitle: sidecarState.activeMilestone?.title,
+          isRetry: false, previousTier: undefined,
+        };
       }
 
-      // ── Phase 4: Unit execution ─────────────────────────────────────────
-
-      debugLog("autoLoop", {
-        phase: "unit-execution",
-        iteration,
-        unitType,
-        unitId,
-      });
-
-      // Detect retry and capture previous tier for escalation
-      const isRetry = !!(
-        s.currentUnit &&
-        s.currentUnit.type === unitType &&
-        s.currentUnit.id === unitId
-      );
-      const previousTier = s.currentUnitRouting?.tier;
-
-      s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
-      deps.captureAvailableSkills();
-      deps.writeUnitRuntimeRecord(
-        s.basePath,
-        unitType,
-        unitId,
-        s.currentUnit.startedAt,
-        {
-          phase: "dispatched",
-          wrapupWarningSent: false,
-          timeoutAt: null,
-          lastProgressAt: s.currentUnit.startedAt,
-          progressCount: 0,
-          lastProgressKind: "dispatch",
-        },
-      );
-
-      // Status bar + progress widget
-      ctx.ui.setStatus("gsd-auto", "auto");
-      if (mid)
-        deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
-      deps.updateProgressWidget(ctx, unitType, unitId, state);
-
-      deps.ensurePreconditions(unitType, unitId, s.basePath, state);
-
-      // Prompt injection
-      let finalPrompt = prompt;
-
-      if (s.pendingVerificationRetry) {
-        const retryCtx = s.pendingVerificationRetry;
-        s.pendingVerificationRetry = null;
-        const capped =
-          retryCtx.failureContext.length > MAX_RECOVERY_CHARS
-            ? retryCtx.failureContext.slice(0, MAX_RECOVERY_CHARS) +
-              "\n\n[...failure context truncated]"
-            : retryCtx.failureContext;
-        finalPrompt = `**VERIFICATION FAILED — AUTO-FIX ATTEMPT ${retryCtx.attempt}**\n\nThe verification gate ran after your previous attempt and found failures. Fix these issues before completing the task.\n\n${capped}\n\n---\n\n${finalPrompt}`;
-      }
-
-      if (s.pendingCrashRecovery) {
-        const capped =
-          s.pendingCrashRecovery.length > MAX_RECOVERY_CHARS
-            ? s.pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) +
-              "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
-            : s.pendingCrashRecovery;
-        finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
-        s.pendingCrashRecovery = null;
-      } else if ((s.unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
-        const diagnostic = deps.getDeepDiagnostic(s.basePath);
-        if (diagnostic) {
-          const cappedDiag =
-            diagnostic.length > MAX_RECOVERY_CHARS
-              ? diagnostic.slice(0, MAX_RECOVERY_CHARS) +
-                "\n\n[...diagnostic truncated to prevent memory exhaustion]"
-              : diagnostic;
-          finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
-        }
-      }
-
-      const repairBlock =
-        deps.buildObservabilityRepairBlock(observabilityIssues);
-      if (repairBlock) {
-        finalPrompt = `${finalPrompt}${repairBlock}`;
-      }
-
-      // Prompt char measurement
-      s.lastPromptCharCount = finalPrompt.length;
-      s.lastBaselineCharCount = undefined;
-      if (deps.isDbAvailable()) {
-        try {
-          const { inlineGsdRootFile } = await importExtensionModule<typeof import("./auto-prompts.js")>(import.meta.url, "./auto-prompts.js");
-          const [decisionsContent, requirementsContent, projectContent] =
-            await Promise.all([
-              inlineGsdRootFile(s.basePath, "decisions.md", "Decisions"),
-              inlineGsdRootFile(s.basePath, "requirements.md", "Requirements"),
-              inlineGsdRootFile(s.basePath, "project.md", "Project"),
-            ]);
-          s.lastBaselineCharCount =
-            (decisionsContent?.length ?? 0) +
-            (requirementsContent?.length ?? 0) +
-            (projectContent?.length ?? 0);
-        } catch {
-          // Non-fatal
-        }
-      }
-
-      // Cache-optimize prompt section ordering
-      try {
-        finalPrompt = deps.reorderForCaching(finalPrompt);
-      } catch (reorderErr) {
-        const msg =
-          reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
-        process.stderr.write(
-          `[gsd] prompt reorder failed (non-fatal): ${msg}\n`,
-        );
-      }
-
-      // Select and apply model (with tier escalation on retry — normal units only)
-      const modelResult = await deps.selectAndApplyModel(
-        ctx,
-        pi,
-        unitType,
-        unitId,
-        s.basePath,
-        prefs,
-        s.verbose,
-        s.autoModeStartModel,
-        sidecarItem ? undefined : { isRetry, previousTier },
-      );
-      s.currentUnitRouting =
-        modelResult.routing as AutoSession["currentUnitRouting"];
-
-      // Start unit supervision
-      deps.clearUnitTimeout();
-      deps.startUnitSupervision({
-        s,
-        ctx,
-        pi,
-        unitType,
-        unitId,
-        prefs,
-        buildSnapshotOpts: () => deps.buildSnapshotOpts(unitType, unitId),
-        buildRecoveryContext: () => ({}),
-        pauseAuto: deps.pauseAuto,
-      });
-
-      // Session + send + await
-      const sessionFile = deps.getSessionFile(ctx);
-      deps.updateSessionLock(
-        deps.lockBase(),
-        unitType,
-        unitId,
-        s.completedUnits.length,
-        sessionFile,
-      );
-      deps.writeLock(
-        deps.lockBase(),
-        unitType,
-        unitId,
-        s.completedUnits.length,
-        sessionFile,
-      );
-
-      debugLog("autoLoop", {
-        phase: "runUnit-start",
-        iteration,
-        unitType,
-        unitId,
-      });
-      const unitResult = await runUnit(
-        ctx,
-        pi,
-        s,
-        unitType,
-        unitId,
-        finalPrompt,
-      );
-      debugLog("autoLoop", {
-        phase: "runUnit-end",
-        iteration,
-        unitType,
-        unitId,
-        status: unitResult.status,
-      });
-
-      // Tag the most recent window entry with error info for stuck detection
-      if (unitResult.status === "error" || unitResult.status === "cancelled") {
-        const lastEntry = recentUnits[recentUnits.length - 1];
-        if (lastEntry) {
-          lastEntry.error = `${unitResult.status}:${unitType}/${unitId}`;
-        }
-      } else if (unitResult.event?.messages?.length) {
-        const lastMsg = unitResult.event.messages[unitResult.event.messages.length - 1];
-        const msgStr = typeof lastMsg === "string" ? lastMsg : JSON.stringify(lastMsg);
-        if (/error|fail|exception/i.test(msgStr)) {
-          const lastEntry = recentUnits[recentUnits.length - 1];
-          if (lastEntry) {
-            lastEntry.error = msgStr.slice(0, 200);
-          }
-        }
-      }
-
-      if (unitResult.status === "cancelled") {
-        ctx.ui.notify(
-          `Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`,
-          "warning",
-        );
-        await deps.stopAuto(ctx, pi, "Session creation failed");
-        debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
-        break;
-      }
-
-      // ── Immediate unit closeout (metrics, activity log, memory) ────────
-      // Run right after runUnit() returns so telemetry is never lost to a
-      // crash between iterations.
-      await deps.closeoutUnit(
-        ctx,
-        s.basePath,
-        unitType,
-        unitId,
-        s.currentUnit.startedAt,
-        deps.buildSnapshotOpts(unitType, unitId),
-      );
-
-      if (s.currentUnitRouting) {
-        deps.recordOutcome(
-          unitType,
-          s.currentUnitRouting.tier as "light" | "standard" | "heavy",
-          true, // success assumed; dispatch will re-dispatch if artifact missing
-        );
-      }
-
-      const isHookUnit = unitType.startsWith("hook/");
-      const artifactVerified =
-        isHookUnit ||
-        deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
-      if (artifactVerified) {
-        s.completedUnits.push({
-          type: unitType,
-          id: unitId,
-          startedAt: s.currentUnit.startedAt,
-          finishedAt: Date.now(),
-        });
-        if (s.completedUnits.length > 200) {
-          s.completedUnits = s.completedUnits.slice(-200);
-        }
-        // Flush completed-units to disk so the record survives crashes
-        try {
-          const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
-          const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
-          atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
-        } catch { /* non-fatal: disk flush failure */ }
-
-        deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
-        s.unitDispatchCount.delete(`${unitType}/${unitId}`);
-        s.unitRecoveryCount.delete(`${unitType}/${unitId}`);
-      }
+      const unitPhaseResult = await runUnitPhase(ic, iterData, loopState, sidecarItem);
+      if (unitPhaseResult.action === "break") break;
 
       // ── Phase 5: Finalize ───────────────────────────────────────────────
 
-      debugLog("autoLoop", { phase: "finalize", iteration });
-
-      // Clear unit timeout (unit completed)
-      deps.clearUnitTimeout();
-
-      // Post-unit context for pre/post verification
-      const postUnitCtx: PostUnitContext = {
-        s,
-        ctx,
-        pi,
-        buildSnapshotOpts: deps.buildSnapshotOpts,
-        lockBase: deps.lockBase,
-        stopAuto: deps.stopAuto,
-        pauseAuto: deps.pauseAuto,
-        updateProgressWidget: deps.updateProgressWidget,
-      };
-
-      // Pre-verification processing (commit, doctor, state rebuild, etc.)
-      // Sidecar items use lightweight pre-verification opts
-      const preVerificationOpts: PreVerificationOpts | undefined = sidecarItem
-        ? sidecarItem.kind === "hook"
-          ? { skipSettleDelay: true, skipDoctor: true, skipStateRebuild: true, skipWorktreeSync: true }
-          : { skipSettleDelay: true, skipStateRebuild: true }
-        : undefined;
-      const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts);
-      if (preResult === "dispatched") {
-        debugLog("autoLoop", {
-          phase: "exit",
-          reason: "pre-verification-dispatched",
-        });
-        break;
-      }
-
-      if (pauseAfterUatDispatch) {
-        ctx.ui.notify(
-          "UAT requires human execution. Auto-mode will pause after this unit writes the result file.",
-          "info",
-        );
-        await deps.pauseAuto(ctx, pi);
-        debugLog("autoLoop", { phase: "exit", reason: "uat-pause" });
-        break;
-      }
-
-      // Verification gate
-      // Hook sidecar items skip verification entirely.
-      // Non-hook sidecar items run verification but skip retries (just continue).
-      const skipVerification = sidecarItem?.kind === "hook";
-      if (!skipVerification) {
-        const verificationResult = await deps.runPostUnitVerification(
-          { s, ctx, pi },
-          deps.pauseAuto,
-        );
-
-        if (verificationResult === "pause") {
-          debugLog("autoLoop", { phase: "exit", reason: "verification-pause" });
-          break;
-        }
-
-        if (verificationResult === "retry") {
-          if (sidecarItem) {
-            // Sidecar verification retries are skipped — just continue
-            debugLog("autoLoop", { phase: "sidecar-verification-retry-skipped", iteration });
-          } else {
-            // s.pendingVerificationRetry was set by runPostUnitVerification.
-            // Continue the loop — next iteration will inject the retry context into the prompt.
-            debugLog("autoLoop", { phase: "verification-retry", iteration });
-            continue;
-          }
-        }
-      }
-
-      // Post-verification processing (DB dual-write, hooks, triage, quick-tasks)
-      const postResult = await deps.postUnitPostVerification(postUnitCtx);
-
-      if (postResult === "stopped") {
-        debugLog("autoLoop", {
-          phase: "exit",
-          reason: "post-verification-stopped",
-        });
-        break;
-      }
-
-      if (postResult === "step-wizard") {
-        // Step mode — exit the loop (caller handles wizard)
-        debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
-        break;
-      }
+      const finalizeResult = await runFinalize(ic, iterData, sidecarItem);
+      if (finalizeResult.action === "break") break;
+      if (finalizeResult.action === "continue") continue;
 
       consecutiveErrors = 0; // Iteration completed successfully
       debugLog("autoLoop", { phase: "iteration-complete", iteration });
diff --git a/src/resources/extensions/gsd/auto-post-unit.ts b/src/resources/extensions/gsd/auto-post-unit.ts
index ca6760011..ce6492100 100644
--- a/src/resources/extensions/gsd/auto-post-unit.ts
+++ b/src/resources/extensions/gsd/auto-post-unit.ts
@@ -168,8 +168,12 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       const sliceTerminalUnits = new Set(["complete-slice", "run-uat"]);
       const effectiveFixLevel = sliceTerminalUnits.has(s.currentUnit.type) ? "all" as const : "task" as const;
       const report = await runGSDDoctor(s.basePath, { fix: true, scope: doctorScope, fixLevel: effectiveFixLevel });
+      // Human-readable fix notification with details
       if (report.fixesApplied.length > 0) {
-        ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
+        const fixSummary = report.fixesApplied.length <= 2
+          ? report.fixesApplied.join("; ")
+          : `${report.fixesApplied[0]}; +${report.fixesApplied.length - 1} more`;
+        ctx.ui.notify(`Doctor: ${fixSummary}`, "info");
       }
 
       // Proactive health tracking — filter to current milestone to avoid
@@ -181,7 +185,11 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
             i.unitId.startsWith(`${currentMilestoneId}/`))
         : report.issues;
       const summary = summarizeDoctorIssues(milestoneIssues);
-      recordHealthSnapshot(summary.errors, summary.warnings, report.fixesApplied.length);
+      // Pass issue details + scope for real-time visibility in the progress widget
+      const issueDetails = milestoneIssues
+        .filter(i => i.severity === "error" || i.severity === "warning")
+        .map(i => ({ code: i.code, message: i.message, severity: i.severity, unitId: i.unitId }));
+      recordHealthSnapshot(summary.errors, summary.warnings, report.fixesApplied.length, issueDetails, report.fixesApplied, doctorScope);
 
       // Check if we should escalate to LLM-assisted heal
       if (summary.errors > 0) {
diff --git a/src/resources/extensions/gsd/auto-prompts.ts b/src/resources/extensions/gsd/auto-prompts.ts
index 5b290e705..9cae54994 100644
--- a/src/resources/extensions/gsd/auto-prompts.ts
+++ b/src/resources/extensions/gsd/auto-prompts.ts
@@ -759,8 +759,8 @@ export async function checkNeedsRunUat(
     if (hasResult) return null;
   }
 
-  // Classify UAT type; unknown type → treat as human-experience (human review)
-  const uatType = extractUatType(uatContent) ?? "human-experience";
+  // Classify UAT type; default to artifact-driven (LLM-executed UATs are always artifact-driven)
+  const uatType = extractUatType(uatContent) ?? "artifact-driven";
 
   return { sliceId: sid, uatType };
 }
@@ -1403,7 +1403,7 @@ export async function buildRunUatPrompt(
   const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "UAT-RESULT"));
-  const uatType = extractUatType(uatContent) ?? "human-experience";
+  const uatType = extractUatType(uatContent) ?? "artifact-driven";
 
   return loadPrompt("run-uat", {
     workingDirectory: base,
diff --git a/src/resources/extensions/gsd/auto-start.ts b/src/resources/extensions/gsd/auto-start.ts
index 7a9920689..8f59bbe1c 100644
--- a/src/resources/extensions/gsd/auto-start.ts
+++ b/src/resources/extensions/gsd/auto-start.ts
@@ -56,7 +56,7 @@ import { readResourceVersion } from "./auto-worktree-sync.js";
 import { initMetrics } from "./metrics.js";
 import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
-import { resetProactiveHealing } from "./doctor-proactive.js";
+import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
 import { isDbAvailable } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
@@ -415,6 +415,11 @@ export async function bootstrapAutoSession(
     resetHookState();
     restoreHookState(base);
     resetProactiveHealing();
+    // Notify user on health level transitions (green→yellow→red and back)
+    setLevelChangeCallback((_from, to, summary) => {
+      const level = to === "red" ? "error" : to === "yellow" ? "warning" : "info";
+      ctx.ui.notify(summary, level as "info" | "warning" | "error");
+    });
     s.autoStartTime = Date.now();
     s.resourceVersionOnStart = readResourceVersion();
     s.completedUnits = [];
diff --git a/src/resources/extensions/gsd/auto.ts b/src/resources/extensions/gsd/auto.ts
index 89e227449..c419933df 100644
--- a/src/resources/extensions/gsd/auto.ts
+++ b/src/resources/extensions/gsd/auto.ts
@@ -111,6 +111,7 @@ import {
   recordHealthSnapshot,
   checkHealEscalation,
   resetProactiveHealing,
+  setLevelChangeCallback,
   formatHealthSummary,
   getConsecutiveErrorUnits,
 } from "./doctor-proactive.js";
@@ -195,7 +196,7 @@ import {
   postUnitPostVerification,
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, type BootstrapDeps } from "./auto-start.js";
-import { autoLoop, resolveAgentEnd, type LoopDeps } from "./auto-loop.js";
+import { autoLoop, resolveAgentEnd, isSessionSwitchInFlight, type LoopDeps } from "./auto-loop.js";
 import {
   WorktreeResolver,
   type WorktreeResolverDeps,
@@ -687,6 +688,7 @@ export async function stopAuto(
     clearInFlightTools();
     clearSliceProgressCache();
     clearActivityLogState();
+    setLevelChangeCallback(null);
     resetProactiveHealing();
 
     // UI cleanup
@@ -1129,6 +1131,7 @@ const widgetStateAccessors: WidgetStateAccessors = {
   getCmdCtx: () => s.cmdCtx,
   getBasePath: () => s.basePath,
   isVerbose: () => s.verbose,
+  isSessionSwitching: isSessionSwitchInFlight,
 };
 
 // ─── Preconditions ────────────────────────────────────────────────────────────
@@ -1183,15 +1186,6 @@ function buildRecoveryContext(): import("./auto-timeout-recovery.js").RecoveryCo
   };
 }
 
-// Re-export recovery functions for external consumers
-export {
-  resolveExpectedArtifactPath,
-  verifyExpectedArtifact,
-  writeBlockerPlaceholder,
-  skipExecuteTask,
-  buildLoopRemediationSteps,
-} from "./auto-recovery.js";
-
 /**
  * Test-only: expose skip-loop state for unit tests.
  * Not part of the public API.
@@ -1327,3 +1321,12 @@ export async function dispatchHookUnit(
 
 // Direct phase dispatch → auto-direct-dispatch.ts
 export { dispatchDirectPhase } from "./auto-direct-dispatch.js";
+
+// Re-export recovery functions for external consumers
+export {
+  resolveExpectedArtifactPath,
+  verifyExpectedArtifact,
+  writeBlockerPlaceholder,
+  skipExecuteTask,
+  buildLoopRemediationSteps,
+} from "./auto-recovery.js";
diff --git a/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts b/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts
new file mode 100644
index 000000000..e9c018101
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts
@@ -0,0 +1,142 @@
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js";
+import { getNextFallbackModel, isTransientNetworkError, resolveModelWithFallbacksForUnit } from "../preferences.js";
+import { classifyProviderError, pauseAutoForProviderError } from "../provider-error-pause.js";
+import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
+import { clearDiscussionFlowState } from "./write-gate.js";
+
+const networkRetryCounters = new Map<string, number>();
+const MAX_TRANSIENT_AUTO_RESUMES = 3;
+let consecutiveTransientErrors = 0;
+
+export async function handleAgentEnd(
+  pi: ExtensionAPI,
+  event: { messages: any[] },
+  ctx: ExtensionContext,
+): Promise<void> {
+  if (checkAutoStartAfterDiscuss()) {
+    clearDiscussionFlowState();
+    return;
+  }
+  if (!isAutoActive()) return;
+  if (isSessionSwitchInFlight()) return;
+
+  const lastMsg = event.messages[event.messages.length - 1];
+  if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+    await pauseAuto(ctx, pi);
+    return;
+  }
+  if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
+    const errorDetail = "errorMessage" in lastMsg && lastMsg.errorMessage ? `: ${lastMsg.errorMessage}` : "";
+    const errorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+
+    if (isTransientNetworkError(errorMsg)) {
+      const currentModelId = ctx.model?.id ?? "unknown";
+      const retryKey = `network-retry:${currentModelId}`;
+      const currentRetries = networkRetryCounters.get(retryKey) ?? 0;
+      const maxRetries = 2;
+      if (currentRetries < maxRetries) {
+        networkRetryCounters.set(retryKey, currentRetries + 1);
+        const attempt = currentRetries + 1;
+        const delayMs = attempt * 3000;
+        ctx.ui.notify(`Network error on ${currentModelId}${errorDetail}. Retry ${attempt}/${maxRetries} in ${delayMs / 1000}s...`, "warning");
+        setTimeout(() => {
+          pi.sendMessage(
+            { customType: "gsd-auto-timeout-recovery", content: "Continue execution — retrying after transient network error.", display: false },
+            { triggerTurn: true },
+          );
+        }, delayMs);
+        return;
+      }
+      networkRetryCounters.delete(retryKey);
+      ctx.ui.notify(`Network retries exhausted for ${currentModelId}. Attempting model fallback.`, "warning");
+    }
+
+    const dash = getAutoDashboardData();
+    if (dash.currentUnit) {
+      const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
+      if (modelConfig && modelConfig.fallbacks.length > 0) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const nextModelId = getNextFallbackModel(ctx.model?.id, modelConfig);
+        if (nextModelId) {
+          networkRetryCounters.clear();
+          const slashIdx = nextModelId.indexOf("/");
+          const modelToSet = slashIdx !== -1
+            ? availableModels.find((m) => m.provider.toLowerCase() === nextModelId.substring(0, slashIdx).toLowerCase() && m.id.toLowerCase() === nextModelId.substring(slashIdx + 1).toLowerCase())
+            : (availableModels.find((m) => m.id === nextModelId && m.provider === ctx.model?.provider) ?? availableModels.find((m) => m.id === nextModelId));
+          if (modelToSet) {
+            const ok = await pi.setModel(modelToSet, { persist: false });
+            if (ok) {
+              ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
+              pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+              return;
+            }
+          }
+        }
+      }
+    }
+
+    const sessionModel = getAutoModeStartModel();
+    if (sessionModel) {
+      if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
+        const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
+        if (startModel) {
+          const ok = await pi.setModel(startModel, { persist: false });
+          if (ok) {
+            networkRetryCounters.clear();
+            ctx.ui.notify(`Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`, "warning");
+            pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+            return;
+          }
+        }
+      }
+    }
+
+    const classification = classifyProviderError(errorMsg);
+    const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
+    if (classification.isTransient) {
+      consecutiveTransientErrors += 1;
+    } else {
+      consecutiveTransientErrors = 0;
+    }
+    const baseRetryAfterMs = explicitRetryAfterMs ?? classification.suggestedDelayMs;
+    const retryAfterMs = classification.isTransient
+      ? baseRetryAfterMs * 2 ** Math.max(0, consecutiveTransientErrors - 1)
+      : baseRetryAfterMs;
+    const allowAutoResume = classification.isTransient && consecutiveTransientErrors <= MAX_TRANSIENT_AUTO_RESUMES;
+    if (classification.isTransient && !allowAutoResume) {
+      ctx.ui.notify(`Transient provider errors persisted after ${MAX_TRANSIENT_AUTO_RESUMES} auto-resume attempts. Pausing for manual review.`, "warning");
+    }
+    await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi), {
+      isRateLimit: classification.isRateLimit,
+      isTransient: allowAutoResume,
+      retryAfterMs,
+      resume: allowAutoResume
+        ? () => {
+          pi.sendMessage(
+            { customType: "gsd-auto-timeout-recovery", content: "Continue execution — provider error recovery delay elapsed.", display: false },
+            { triggerTurn: true },
+          );
+        }
+        : undefined,
+    });
+    return;
+  }
+
+  try {
+    consecutiveTransientErrors = 0;
+    networkRetryCounters.clear();
+    resolveAgentEnd(event);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`, "error");
+    try {
+      await pauseAuto(ctx, pi);
+    } catch {
+      // best-effort
+    }
+  }
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/db-tools.ts b/src/resources/extensions/gsd/bootstrap/db-tools.ts
new file mode 100644
index 000000000..2e55ff6cc
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/db-tools.ts
@@ -0,0 +1,238 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { findMilestoneIds, nextMilestoneId } from "../guided-flow.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { ensureDbOpen } from "./dynamic-tools.js";
+
+export function registerDbTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gsd_save_decision",
+    label: "Save Decision",
+    description:
+      "Record a project decision to the GSD database and regenerate DECISIONS.md. " +
+      "Decision IDs are auto-assigned — never provide an ID manually.",
+    promptSnippet: "Record a project decision to the GSD database (auto-assigns ID, regenerates DECISIONS.md)",
+    promptGuidelines: [
+      "Use gsd_save_decision when recording an architectural, pattern, library, or observability decision.",
+      "Decision IDs are auto-assigned (D001, D002, ...) — never guess or provide an ID.",
+      "All fields except revisable and when_context are required.",
+      "The tool writes to the DB and regenerates .gsd/DECISIONS.md automatically.",
+    ],
+    parameters: Type.Object({
+      scope: Type.String({ description: "Scope of the decision (e.g. 'architecture', 'library', 'observability')" }),
+      decision: Type.String({ description: "What is being decided" }),
+      choice: Type.String({ description: "The choice made" }),
+      rationale: Type.String({ description: "Why this choice was made" }),
+      revisable: Type.Optional(Type.String({ description: "Whether this can be revisited (default: 'Yes')" })),
+      when_context: Type.Optional(Type.String({ description: "When/context for the decision (e.g. milestone ID)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save decision." }],
+          details: { operation: "save_decision", error: "db_unavailable" } as any,
+        };
+      }
+      try {
+        const { saveDecisionToDb } = await import("../db-writer.js");
+        const { id } = await saveDecisionToDb(
+          {
+            scope: params.scope,
+            decision: params.decision,
+            choice: params.choice,
+            rationale: params.rationale,
+            revisable: params.revisable,
+            when_context: params.when_context,
+          },
+          process.cwd(),
+        );
+        return {
+          content: [{ type: "text" as const, text: `Saved decision ${id}` }],
+          details: { operation: "save_decision", id } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
+          details: { operation: "save_decision", error: msg } as any,
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_update_requirement",
+    label: "Update Requirement",
+    description:
+      "Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md. " +
+      "Provide the requirement ID (e.g. R001) and any fields to update.",
+    promptSnippet: "Update an existing GSD requirement by ID (regenerates REQUIREMENTS.md)",
+    promptGuidelines: [
+      "Use gsd_update_requirement to change status, validation, notes, or other fields on an existing requirement.",
+      "The id parameter is required — it must be an existing RXXX identifier.",
+      "All other fields are optional — only provided fields are updated.",
+      "The tool verifies the requirement exists before updating.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({ description: "The requirement ID (e.g. R001, R014)" }),
+      status: Type.Optional(Type.String({ description: "New status (e.g. 'active', 'validated', 'deferred')" })),
+      validation: Type.Optional(Type.String({ description: "Validation criteria or proof" })),
+      notes: Type.Optional(Type.String({ description: "Additional notes" })),
+      description: Type.Optional(Type.String({ description: "Updated description" })),
+      primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })),
+      supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot update requirement." }],
+          details: { operation: "update_requirement", id: params.id, error: "db_unavailable" } as any,
+        };
+      }
+      try {
+        const db = await import("../gsd-db.js");
+        const existing = db.getRequirementById(params.id);
+        if (!existing) {
+          return {
+            content: [{ type: "text" as const, text: `Error: Requirement ${params.id} not found.` }],
+            details: { operation: "update_requirement", id: params.id, error: "not_found" } as any,
+          };
+        }
+        const { updateRequirementInDb } = await import("../db-writer.js");
+        const updates: Record<string, string | undefined> = {};
+        if (params.status !== undefined) updates.status = params.status;
+        if (params.validation !== undefined) updates.validation = params.validation;
+        if (params.notes !== undefined) updates.notes = params.notes;
+        if (params.description !== undefined) updates.description = params.description;
+        if (params.primary_owner !== undefined) updates.primary_owner = params.primary_owner;
+        if (params.supporting_slices !== undefined) updates.supporting_slices = params.supporting_slices;
+        await updateRequirementInDb(params.id, updates, process.cwd());
+        return {
+          content: [{ type: "text" as const, text: `Updated requirement ${params.id}` }],
+          details: { operation: "update_requirement", id: params.id } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
+          details: { operation: "update_requirement", id: params.id, error: msg } as any,
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_save_summary",
+    label: "Save Summary",
+    description:
+      "Save a summary, research, context, or assessment artifact to the GSD database and write it to disk. " +
+      "Computes the file path from milestone/slice/task IDs automatically.",
+    promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
+    promptGuidelines: [
+      "Use gsd_save_summary to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT).",
+      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+      "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
+      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT.",
+    ],
+    parameters: Type.Object({
+      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+      task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT" }),
+      content: Type.String({ description: "The full markdown content of the artifact" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save artifact." }],
+          details: { operation: "save_summary", error: "db_unavailable" } as any,
+        };
+      }
+      const validTypes = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT"];
+      if (!validTypes.includes(params.artifact_type)) {
+        return {
+          content: [{ type: "text" as const, text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${validTypes.join(", ")}` }],
+          details: { operation: "save_summary", error: "invalid_artifact_type" } as any,
+        };
+      }
+      try {
+        let relativePath: string;
+        if (params.task_id && params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+        } else if (params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+        } else {
+          relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+        }
+        const { saveArtifactToDb } = await import("../db-writer.js");
+        await saveArtifactToDb(
+          {
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            content: params.content,
+            milestone_id: params.milestone_id,
+            slice_id: params.slice_id,
+            task_id: params.task_id,
+          },
+          process.cwd(),
+        );
+        return {
+          content: [{ type: "text" as const, text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
+          details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
+          details: { operation: "save_summary", error: msg } as any,
+        };
+      }
+    },
+  });
+
+  const reservedMilestoneIds = new Set<string>();
+  pi.registerTool({
+    name: "gsd_generate_milestone_id",
+    label: "Generate Milestone ID",
+    description:
+      "Generate the next milestone ID for a new GSD milestone. " +
+      "Scans existing milestones on disk and respects the unique_milestone_ids preference. " +
+      "Always use this tool when creating a new milestone — never invent milestone IDs manually.",
+    promptSnippet: "Generate a valid milestone ID (respects unique_milestone_ids preference)",
+    promptGuidelines: [
+      "ALWAYS call gsd_generate_milestone_id before creating a new milestone directory or writing milestone files.",
+      "Never invent or hardcode milestone IDs like M001, M002 — always use this tool.",
+      "Call it once per milestone you need to create. For multi-milestone projects, call it once for each milestone in sequence.",
+      "The tool returns the correct format based on project preferences (e.g. M001 or M001-r5jzab).",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      try {
+        const basePath = process.cwd();
+        const existingIds = findMilestoneIds(basePath);
+        const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
+        const allIds = [...new Set([...existingIds, ...reservedMilestoneIds])];
+        const newId = nextMilestoneId(allIds, uniqueEnabled);
+        reservedMilestoneIds.add(newId);
+        return {
+          content: [{ type: "text" as const, text: newId }],
+          details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, reservedCount: reservedMilestoneIds.size, uniqueEnabled } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
+          details: { operation: "generate_milestone_id", error: msg } as any,
+        };
+      }
+    },
+  });
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts b/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts
new file mode 100644
index 000000000..3dab4b47a
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts
@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
+
+import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
+
+export async function ensureDbOpen(): Promise<boolean> {
+  try {
+    const db = await import("../gsd-db.js");
+    if (db.isDbAvailable()) return true;
+    const dbPath = join(process.cwd(), ".gsd", "gsd.db");
+    if (existsSync(dbPath)) {
+      return db.openDatabase(dbPath);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function registerDynamicTools(pi: ExtensionAPI): void {
+  const baseBash = createBashTool(process.cwd(), {
+    spawnHook: (ctx) => ({ ...ctx, cwd: process.cwd() }),
+  });
+  const dynamicBash = {
+    ...baseBash,
+    execute: async (
+      toolCallId: string,
+      params: { command: string; timeout?: number },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const paramsWithTimeout = {
+        ...params,
+        timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
+      };
+      return (baseBash as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
+    },
+  };
+  pi.registerTool(dynamicBash as any);
+
+  const baseWrite = createWriteTool(process.cwd());
+  pi.registerTool({
+    ...baseWrite,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; content: string },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createWriteTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+
+  const baseRead = createReadTool(process.cwd());
+  pi.registerTool({
+    ...baseRead,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; offset?: number; limit?: number },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createReadTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+
+  const baseEdit = createEditTool(process.cwd());
+  pi.registerTool({
+    ...baseEdit,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; oldText: string; newText: string },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createEditTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/register-extension.ts b/src/resources/extensions/gsd/bootstrap/register-extension.ts
new file mode 100644
index 000000000..0f5b5ea42
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/register-extension.ts
@@ -0,0 +1,46 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { registerGSDCommand } from "../commands.js";
+import { registerExitCommand } from "../exit-command.js";
+import { registerWorktreeCommand } from "../worktree-command.js";
+import { registerDbTools } from "./db-tools.js";
+import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerHooks } from "./register-hooks.js";
+import { registerShortcuts } from "./register-shortcuts.js";
+
+function installEpipeGuard(): void {
+  if (!process.listeners("uncaughtException").some((listener) => listener.name === "_gsdEpipeGuard")) {
+    const _gsdEpipeGuard = (err: Error): void => {
+      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+        process.exit(0);
+      }
+      if ((err as NodeJS.ErrnoException).code === "ENOENT" && (err as any).syscall?.startsWith("spawn")) {
+        process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
+        return;
+      }
+      throw err;
+    };
+    process.on("uncaughtException", _gsdEpipeGuard);
+  }
+}
+
+export function registerGsdExtension(pi: ExtensionAPI): void {
+  registerGSDCommand(pi);
+  registerWorktreeCommand(pi);
+  registerExitCommand(pi);
+
+  installEpipeGuard();
+
+  pi.registerCommand("kill", {
+    description: "Exit GSD immediately (no cleanup)",
+    handler: async (_args: string, _ctx: ExtensionCommandContext) => {
+      process.exit(0);
+    },
+  });
+
+  registerDynamicTools(pi);
+  registerDbTools(pi);
+  registerShortcuts(pi);
+  registerHooks(pi);
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/register-hooks.ts b/src/resources/extensions/gsd/bootstrap/register-hooks.ts
new file mode 100644
index 000000000..dc2632fbd
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/register-hooks.ts
@@ -0,0 +1,167 @@
+import { join } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { isToolCallEventType } from "@gsd/pi-coding-agent";
+
+import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
+import { buildBeforeAgentStartResult } from "./system-context.js";
+import { handleAgentEnd } from "./agent-end-recovery.js";
+import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
+import { getDiscussionMilestoneId } from "../guided-flow.js";
+import { loadToolApiKeys } from "../commands-config.js";
+import { loadFile, saveFile, formatContinue } from "../files.js";
+import { deriveState } from "../state.js";
+import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart } from "../auto.js";
+import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
+import { saveActivityLog } from "../activity-log.js";
+import { maybeRenderGsdHeader } from "./register-shortcuts.js";
+
+export function registerHooks(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    resetWriteGateState();
+    maybeRenderGsdHeader(ctx);
+    loadToolApiKeys();
+    try {
+      const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
+        import("../../remote-questions/config.js"),
+        import("../../remote-questions/status.js"),
+      ]);
+      const status = getRemoteConfigStatus();
+      const latest = getLatestPromptSummary();
+      if (!status.includes("not configured")) {
+        const suffix = latest ? `\nLast remote prompt: ${latest.id} (${latest.status})` : "";
+        ctx.ui.notify(`${status}${suffix}`, status.includes("disabled") ? "warning" : "info");
+      }
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+    return buildBeforeAgentStartResult(event, ctx);
+  });
+
+  pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    await handleAgentEnd(pi, event, ctx);
+  });
+
+  pi.on("session_before_compact", async () => {
+    if (isAutoActive() || isAutoPaused()) {
+      return { cancel: true };
+    }
+    const basePath = process.cwd();
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
+    if (state.phase !== "executing") return;
+
+    const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
+    if (!sliceDir) return;
+
+    const existingFile = resolveSliceFile(basePath, state.activeMilestone.id, state.activeSlice.id, "CONTINUE");
+    if (existingFile && await loadFile(existingFile)) return;
+    const legacyContinue = join(sliceDir, "continue.md");
+    if (await loadFile(legacyContinue)) return;
+
+    const continuePath = join(sliceDir, `${state.activeSlice.id}-CONTINUE.md`);
+    await saveFile(continuePath, formatContinue({
+      frontmatter: {
+        milestone: state.activeMilestone.id,
+        slice: state.activeSlice.id,
+        task: state.activeTask.id,
+        step: 0,
+        totalSteps: 0,
+        status: "compacted" as const,
+        savedAt: new Date().toISOString(),
+      },
+      completedWork: `Task ${state.activeTask.id} (${state.activeTask.title}) was in progress when compaction occurred.`,
+      remainingWork: "Check the task plan for remaining steps.",
+      decisions: "Check task summary files for prior decisions.",
+      context: "Session was auto-compacted by Pi. Resume with /gsd.",
+      nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
+    }));
+  });
+
+  pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
+    if (isParallelActive()) {
+      try {
+        await shutdownParallel(process.cwd());
+      } catch {
+        // best-effort
+      }
+    }
+    if (!isAutoActive() && !isAutoPaused()) return;
+    const dash = getAutoDashboardData();
+    if (dash.currentUnit) {
+      saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
+    }
+  });
+
+  pi.on("tool_call", async (event) => {
+    if (!isToolCallEventType("write", event)) return;
+    const result = shouldBlockContextWrite(
+      event.toolName,
+      event.input.path,
+      getDiscussionMilestoneId(),
+      isDepthVerified(),
+      isQueuePhaseActive(),
+    );
+    if (result.block) return result;
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "ask_user_questions") return;
+    const milestoneId = getDiscussionMilestoneId();
+    if (!milestoneId) return;
+
+    const details = event.details as any;
+    if (details?.cancelled || !details?.response) return;
+
+    const questions: any[] = (event.input as any)?.questions ?? [];
+    for (const question of questions) {
+      if (typeof question.id === "string" && question.id.includes("depth_verification")) {
+        markDepthVerified();
+        break;
+      }
+    }
+
+    const basePath = process.cwd();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) return;
+
+    const discussionPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "DISCUSSION"));
+    const timestamp = new Date().toISOString();
+    const lines: string[] = [`## Exchange — ${timestamp}`, ""];
+    for (const question of questions) {
+      lines.push(`### ${question.header ?? "Question"}`, "", question.question ?? "");
+      if (Array.isArray(question.options)) {
+        lines.push("");
+        for (const opt of question.options) {
+          lines.push(`- **${opt.label}** — ${opt.description ?? ""}`);
+        }
+      }
+      const answer = details.response?.answers?.[question.id];
+      if (answer) {
+        lines.push("");
+        const selected = Array.isArray(answer.selected) ? answer.selected.join(", ") : answer.selected;
+        lines.push(`**Selected:** ${selected}`);
+        if (answer.notes) {
+          lines.push(`**Notes:** ${answer.notes}`);
+        }
+      }
+      lines.push("");
+    }
+    lines.push("---", "");
+    const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
+    await saveFile(discussionPath, existing + lines.join("\n"));
+  });
+
+  pi.on("tool_execution_start", async (event) => {
+    if (!isAutoActive()) return;
+    markToolStart(event.toolCallId);
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    markToolEnd(event.toolCallId);
+  });
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts b/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts
new file mode 100644
index 000000000..c04f58cb7
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts
@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Key, Text } from "@gsd/pi-tui";
+
+import { GSDDashboardOverlay } from "../dashboard-overlay.js";
+import { shortcutDesc } from "../../shared/mod.js";
+
+export const GSD_LOGO_LINES = [
+  "   ██████╗ ███████╗██████╗ ",
+  "  ██╔════╝ ██╔════╝██╔══██╗",
+  "  ██║  ███╗███████╗██║  ██║",
+  "  ██║   ██║╚════██║██║  ██║",
+  "  ╚██████╔╝███████║██████╔╝",
+  "   ╚═════╝ ╚══════╝╚═════╝ ",
+];
+
+export function registerShortcuts(pi: ExtensionAPI): void {
+  pi.registerShortcut(Key.ctrlAlt("g"), {
+    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
+    handler: async (ctx) => {
+      if (!existsSync(join(process.cwd(), ".gsd"))) {
+        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
+        return;
+      }
+      await ctx.ui.custom<void>(
+        (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done()),
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "90%",
+            minWidth: 80,
+            maxHeight: "92%",
+            anchor: "center",
+          },
+        },
+      );
+    },
+  });
+}
+
+export function maybeRenderGsdHeader(ctx: { ui: any }): void {
+  try {
+    const theme = ctx.ui.theme;
+    const version = process.env.GSD_VERSION || "0.0.0";
+    const logoText = GSD_LOGO_LINES.map((line) => theme.fg("accent", line)).join("\n");
+    const titleLine = `  ${theme.bold("Get Shit Done")} ${theme.fg("dim", `v${version}`)}`;
+    const headerContent = `${logoText}\n${titleLine}`;
+    ctx.ui.setHeader((_ui: unknown, _theme: unknown) => new Text(headerContent, 1, 0));
+  } catch {
+    // no TUI
+  }
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/system-context.ts b/src/resources/extensions/gsd/bootstrap/system-context.ts
new file mode 100644
index 000000000..6d4070d7f
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/system-context.ts
@@ -0,0 +1,340 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { debugTime } from "../debug-logger.js";
+import { loadPrompt } from "../prompt-loader.js";
+import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
+import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
+import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
+import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
+import { deriveState } from "../state.js";
+import { formatOverridesSection, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
+import { toPosixPath } from "../../shared/mod.js";
+import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
+function warnDeprecatedAgentInstructions(): void {
+  const paths = [
+    join(gsdHome, "agent-instructions.md"),
+    join(process.cwd(), ".gsd", "agent-instructions.md"),
+  ];
+  for (const path of paths) {
+    if (existsSync(path)) {
+      console.warn(
+        `[GSD] DEPRECATED: ${path} is no longer loaded. ` +
+        `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+        `See https://github.com/gsd-build/GSD-2/issues/1492`,
+      );
+    }
+  }
+}
+
+export async function buildBeforeAgentStartResult(
+  event: { prompt: string; systemPrompt: string },
+  ctx: ExtensionContext,
+): Promise<{ systemPrompt: string; message?: { customType: string; content: string; display: false } } | undefined> {
+  if (!existsSync(join(process.cwd(), ".gsd"))) return undefined;
+
+  const stopContextTimer = debugTime("context-inject");
+  const systemContent = loadPrompt("system");
+  const loadedPreferences = loadEffectiveGSDPreferences();
+  if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+    markCmuxPromptShown();
+    ctx.ui.notify(
+      "cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.",
+      "info",
+    );
+  }
+
+  let preferenceBlock = "";
+  if (loadedPreferences) {
+    const cwd = process.cwd();
+    const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
+    preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
+    if (report.warnings.length > 0) {
+      ctx.ui.notify(
+        `GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`,
+        "warning",
+      );
+    }
+  }
+
+  let knowledgeBlock = "";
+  const knowledgePath = resolveGsdRootFile(process.cwd(), "KNOWLEDGE");
+  if (existsSync(knowledgePath)) {
+    try {
+      const content = readFileSync(knowledgePath, "utf-8").trim();
+      if (content) {
+        knowledgeBlock = `\n\n[PROJECT KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${content}`;
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  let memoryBlock = "";
+  try {
+    const { formatMemoriesForPrompt, getActiveMemoriesRanked } = await import("../memory-store.js");
+    const memories = getActiveMemoriesRanked(30);
+    if (memories.length > 0) {
+      const formatted = formatMemoriesForPrompt(memories, 2000);
+      if (formatted) {
+        memoryBlock = `\n\n${formatted}`;
+      }
+    }
+  } catch {
+    // non-fatal
+  }
+
+  let newSkillsBlock = "";
+  if (hasSkillSnapshot()) {
+    const newSkills = detectNewSkills();
+    if (newSkills.length > 0) {
+      newSkillsBlock = formatSkillsXml(newSkills);
+    }
+  }
+
+  warnDeprecatedAgentInstructions();
+
+  const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+  const worktreeBlock = buildWorktreeContextBlock();
+  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+
+  stopContextTimer({
+    systemPromptSize: fullSystem.length,
+    injectionSize: injection?.length ?? 0,
+    hasPreferences: preferenceBlock.length > 0,
+    hasNewSkills: newSkillsBlock.length > 0,
+  });
+
+  return {
+    systemPrompt: fullSystem,
+    ...(injection
+      ? {
+        message: {
+          customType: "gsd-guided-context",
+          content: injection,
+          display: false as const,
+        },
+      }
+      : {}),
+  };
+}
+
+function buildWorktreeContextBlock(): string {
+  const worktreeName = getActiveWorktreeName();
+  const worktreeMainCwd = getWorktreeOriginalCwd();
+  const autoWorktree = getActiveAutoWorktreeContext();
+
+  if (worktreeName && worktreeMainCwd) {
+    return [
+      "",
+      "",
+      "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
+      `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
+      `The actual current working directory is: ${toPosixPath(process.cwd())}`,
+      "",
+      `You are working inside a GSD worktree.`,
+      `- Worktree name: ${worktreeName}`,
+      `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
+      `- Main project: ${toPosixPath(worktreeMainCwd)}`,
+      `- Branch: worktree/${worktreeName}`,
+      "",
+      "All file operations, bash commands, and GSD state resolve against the worktree path above.",
+      "Use /worktree merge to merge changes back. Use /worktree return to switch back to the main tree.",
+    ].join("\n");
+  }
+
+  if (autoWorktree) {
+    return [
+      "",
+      "",
+      "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
+      `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
+      `The actual current working directory is: ${toPosixPath(process.cwd())}`,
+      "",
+      "You are working inside a GSD auto-worktree.",
+      `- Milestone worktree: ${autoWorktree.worktreeName}`,
+      `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
+      `- Main project: ${toPosixPath(autoWorktree.originalBase)}`,
+      `- Branch: ${autoWorktree.branch}`,
+      "",
+      "All file operations, bash commands, and GSD state resolve against the worktree path above.",
+      "Write every .gsd artifact in the worktree path above, never in the main project tree.",
+    ].join("\n");
+  }
+
+  return "";
+}
+
+async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
+  const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
+  if (executeMatch) {
+    const [, taskId, taskTitle, sliceId, milestoneId] = executeMatch;
+    return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, taskId, taskTitle);
+  }
+
+  const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
+  if (resumeMatch) {
+    const [, sliceId, milestoneId] = resumeMatch;
+    const state = await deriveState(basePath);
+    if (state.activeMilestone?.id === milestoneId && state.activeSlice?.id === sliceId && state.activeTask) {
+      return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, state.activeTask.id, state.activeTask.title);
+    }
+  }
+
+  return null;
+}
+
+async function buildTaskExecutionContextInjection(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+  taskTitle: string,
+): Promise<string> {
+  const taskPlanPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+  const taskPlanRelPath = relTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+  const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
+  const taskPlanInline = taskPlanContent
+    ? ["## Inlined Task Plan (authoritative local execution contract)", `Source: \`${taskPlanRelPath}\``, "", taskPlanContent.trim()].join("\n")
+    : ["## Inlined Task Plan (authoritative local execution contract)", `Task plan not found at dispatch time. Read \`${taskPlanRelPath}\` before executing.`].join("\n");
+
+  const slicePlanPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  const slicePlanRelPath = relSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  const slicePlanContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
+  const slicePlanExcerpt = extractSliceExecutionExcerpt(slicePlanContent, slicePlanRelPath);
+  const priorTaskLines = await buildCarryForwardLines(basePath, milestoneId, sliceId, taskId);
+  const resumeSection = await buildResumeSection(basePath, milestoneId, sliceId);
+  const activeOverrides = await loadActiveOverrides(basePath);
+  const overridesSection = formatOverridesSection(activeOverrides);
+
+  return [
+    "[GSD Guided Execute Context]",
+    "Use this injected context as startup context for guided task execution. Treat the inlined task plan as the authoritative local execution contract. Use source artifacts to verify details and run checks.",
+    overridesSection, "",
+    "",
+    resumeSection,
+    "",
+    "## Carry-Forward Context",
+    ...priorTaskLines,
+    "",
+    taskPlanInline,
+    "",
+    slicePlanExcerpt,
+    "",
+    "## Backing Source Artifacts",
+    `- Slice plan: \`${slicePlanRelPath}\``,
+    `- Task plan source: \`${taskPlanRelPath}\``,
+  ].join("\n");
+}
+
+async function buildCarryForwardLines(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): Promise<string[]> {
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (!tasksDir) return ["- No prior task summaries in this slice."];
+
+  const currentNum = parseInt(taskId.replace(/^T/, ""), 10);
+  const sliceRel = relSlicePath(basePath, milestoneId, sliceId);
+  const summaryFiles = resolveTaskFiles(tasksDir, "SUMMARY")
+    .filter((file) => parseInt(file.replace(/^T/, ""), 10) < currentNum)
+    .sort();
+
+  if (summaryFiles.length === 0) return ["- No prior task summaries in this slice."];
+
+  return Promise.all(summaryFiles.map(async (file) => {
+    const absPath = join(tasksDir, file);
+    const content = await loadFile(absPath);
+    const relPath = `${sliceRel}/tasks/${file}`;
+    if (!content) return `- \`${relPath}\``;
+
+    const summary = parseSummary(content);
+    const provided = summary.frontmatter.provides.slice(0, 2).join("; ");
+    const decisions = summary.frontmatter.key_decisions.slice(0, 2).join("; ");
+    const patterns = summary.frontmatter.patterns_established.slice(0, 2).join("; ");
+    const diagnostics = extractMarkdownSection(content, "Diagnostics");
+    const parts = [summary.title || relPath];
+    if (summary.oneLiner) parts.push(summary.oneLiner);
+    if (provided) parts.push(`provides: ${provided}`);
+    if (decisions) parts.push(`decisions: ${decisions}`);
+    if (patterns) parts.push(`patterns: ${patterns}`);
+    if (diagnostics) parts.push(`diagnostics: ${oneLine(diagnostics)}`);
+    return `- \`${relPath}\` — ${parts.join(" | ")}`;
+  }));
+}
+
+async function buildResumeSection(basePath: string, milestoneId: string, sliceId: string): Promise<string> {
+  const continueFile = resolveSliceFile(basePath, milestoneId, sliceId, "CONTINUE");
+  const legacyDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  const legacyPath = legacyDir ? join(legacyDir, "continue.md") : null;
+  const continueContent = continueFile ? await loadFile(continueFile) : null;
+  const legacyContent = !continueContent && legacyPath ? await loadFile(legacyPath) : null;
+  const resolvedContent = continueContent ?? legacyContent;
+  const resolvedRelPath = continueContent
+    ? relSliceFile(basePath, milestoneId, sliceId, "CONTINUE")
+    : (legacyPath ? `${relSlicePath(basePath, milestoneId, sliceId)}/continue.md` : null);
+
+  if (!resolvedContent || !resolvedRelPath) {
+    return ["## Resume State", "- No continue file present. Start from the top of the task plan."].join("\n");
+  }
+
+  const cont = parseContinue(resolvedContent);
+  const lines = [
+    "## Resume State",
+    `Source: \`${resolvedRelPath}\``,
+    `- Status: ${cont.frontmatter.status || "in_progress"}`,
+  ];
+  if (cont.frontmatter.step && cont.frontmatter.totalSteps) {
+    lines.push(`- Progress: step ${cont.frontmatter.step} of ${cont.frontmatter.totalSteps}`);
+  }
+  if (cont.completedWork) lines.push(`- Completed: ${oneLine(cont.completedWork)}`);
+  if (cont.remainingWork) lines.push(`- Remaining: ${oneLine(cont.remainingWork)}`);
+  if (cont.decisions) lines.push(`- Decisions: ${oneLine(cont.decisions)}`);
+  if (cont.nextAction) lines.push(`- Next action: ${oneLine(cont.nextAction)}`);
+  return lines.join("\n");
+}
+
+function extractSliceExecutionExcerpt(content: string | null, relPath: string): string {
+  if (!content) {
+    return ["## Slice Plan Excerpt", `Slice plan not found at dispatch time. Read \`${relPath}\` before running slice-level verification.`].join("\n");
+  }
+  const lines = content.split("\n");
+  const goalLine = lines.find((line) => line.startsWith("**Goal:**"))?.trim();
+  const demoLine = lines.find((line) => line.startsWith("**Demo:**"))?.trim();
+  const verification = extractMarkdownSection(content, "Verification");
+  const observability = extractMarkdownSection(content, "Observability / Diagnostics");
+  const parts = ["## Slice Plan Excerpt", `Source: \`${relPath}\``];
+  if (goalLine) parts.push(goalLine);
+  if (demoLine) parts.push(demoLine);
+  if (verification) parts.push("", "### Slice Verification", verification.trim());
+  if (observability) parts.push("", "### Slice Observability / Diagnostics", observability.trim());
+  return parts.join("\n");
+}
+
+function extractMarkdownSection(content: string, heading: string): string | null {
+  const match = new RegExp(`^## ${escapeRegExp(heading)}\\s*$`, "m").exec(content);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  const rest = content.slice(start);
+  const nextHeading = rest.match(/^##\s+/m);
+  const end = nextHeading?.index ?? rest.length;
+  return rest.slice(0, end).trim();
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
diff --git a/src/resources/extensions/gsd/bootstrap/write-gate.ts b/src/resources/extensions/gsd/bootstrap/write-gate.ts
new file mode 100644
index 000000000..75a964021
--- /dev/null
+++ b/src/resources/extensions/gsd/bootstrap/write-gate.ts
@@ -0,0 +1,51 @@
+const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+
+let depthVerificationDone = false;
+let activeQueuePhase = false;
+
+export function isDepthVerified(): boolean {
+  return depthVerificationDone;
+}
+
+export function isQueuePhaseActive(): boolean {
+  return activeQueuePhase;
+}
+
+export function setQueuePhaseActive(active: boolean): void {
+  activeQueuePhase = active;
+}
+
+export function resetWriteGateState(): void {
+  depthVerificationDone = false;
+}
+
+export function clearDiscussionFlowState(): void {
+  depthVerificationDone = false;
+  activeQueuePhase = false;
+}
+
+export function markDepthVerified(): void {
+  depthVerificationDone = true;
+}
+
+export function shouldBlockContextWrite(
+  toolName: string,
+  inputPath: string,
+  milestoneId: string | null,
+  depthVerified: boolean,
+  queuePhaseActive?: boolean,
+): { block: boolean; reason?: string } {
+  if (toolName !== "write") return { block: false };
+
+  const inDiscussion = milestoneId !== null;
+  const inQueue = queuePhaseActive ?? false;
+  if (!inDiscussion && !inQueue) return { block: false };
+  if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
+  if (depthVerified) return { block: false };
+
+  return {
+    block: true,
+    reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
+  };
+}
+
diff --git a/src/resources/extensions/gsd/commands-handlers.ts b/src/resources/extensions/gsd/commands-handlers.ts
index 13089df2c..e43ecb0fa 100644
--- a/src/resources/extensions/gsd/commands-handlers.ts
+++ b/src/resources/extensions/gsd/commands-handlers.ts
@@ -21,7 +21,7 @@ import {
   filterDoctorIssues,
 } from "./doctor.js";
 import { isAutoActive } from "./auto.js";
-import { projectRoot } from "./commands.js";
+import { projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
diff --git a/src/resources/extensions/gsd/commands.ts b/src/resources/extensions/gsd/commands.ts
index df72e2d4e..9d98fc068 100644
--- a/src/resources/extensions/gsd/commands.ts
+++ b/src/resources/extensions/gsd/commands.ts
@@ -1,1336 +1,17 @@
-/**
- * GSD Command — /gsd
- *
- * One command, one wizard. Routes to smart entry or status.
- */
-
-import { importExtensionModule, type ExtensionAPI, type ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import type { GSDState } from "./types.js";
-import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
-
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-import { enableDebug } from "./debug-logger.js";
-import { deriveState } from "./state.js";
-import { GSDDashboardOverlay } from "./dashboard-overlay.js";
-import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
-import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote, checkRemoteAutoSession } from "./auto.js";
-import { dispatchDirectPhase } from "./auto-direct-dispatch.js";
-import { resolveProjectRoot } from "./worktree.js";
-import { assertSafeDirectory } from "./validate-directory.js";
-import {
-  getGlobalGSDPreferencesPath,
-  getProjectGSDPreferencesPath,
-  loadEffectiveGSDPreferences,
-} from "./preferences.js";
-import { handleRemote } from "../remote-questions/mod.js";
-import { handleQuick } from "./quick.js";
-import { handleHistory } from "./history.js";
-import { handleUndo } from "./undo.js";
-import { handleExport } from "./export.js";
-import {
-  isParallelActive, getOrchestratorState, getWorkerStatuses,
-  prepareParallelStart, startParallel, stopParallel,
-  pauseWorker, resumeWorker,
-} from "./parallel-orchestrator.js";
-import { formatEligibilityReport } from "./parallel-eligibility.js";
-import { mergeAllCompleted, mergeCompletedMilestone, formatMergeResults } from "./parallel-merge.js";
-import { resolveParallelConfig } from "./preferences.js";
-
-// ─── Imports from extracted modules ──────────────────────────────────────────
-import { handlePrefs, handlePrefsMode, handlePrefsWizard, ensurePreferencesFile } from "./commands-prefs-wizard.js";
-import { handleConfig } from "./commands-config.js";
-import { handleInspect } from "./commands-inspect.js";
-import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleDryRun } from "./commands-maintenance.js";
-import { handleDoctor, handleSteer, handleCapture, handleTriage, handleKnowledge, handleRunHook, handleUpdate, handleSkillHealth } from "./commands-handlers.js";
-import { computeProgressScore, formatProgressLine } from "./progress-score.js";
-import { runEnvironmentChecks } from "./doctor-environment.js";
-import { handleLogs } from "./commands-logs.js";
-import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
-import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
-import { handleCmux } from "./commands-cmux.js";
-import { showNextAction } from "../shared/mod.js";
-
-
-/** Resolve the effective project root, accounting for worktree paths. */
-export function projectRoot(): string {
-  const cwd = process.cwd();
-  const root = resolveProjectRoot(cwd);
-
-  // When running inside a GSD worktree, the resolved root may be a "dangerous"
-  // directory (e.g., $HOME used as a git repo root — #1317). The safety check
-  // should validate the actual working directory, not the upstream root,
-  // because the worktree itself is a safe project subdirectory.
-  // Only skip the root check when we can confirm we're in a valid worktree.
-  if (root !== cwd) {
-    // We're in a worktree — validate the worktree path instead of the root
-    assertSafeDirectory(cwd);
-  } else {
-    assertSafeDirectory(root);
-  }
-  return root;
-}
-
-/**
- * Guard against starting auto-mode when a remote session is already running.
- * Returns true if the caller should proceed with startAuto, false if handled.
- */
-async function guardRemoteSession(
-  ctx: ExtensionCommandContext,
-  pi: ExtensionAPI,
-): Promise<boolean> {
-  // Local session already active — proceed (startAuto handles re-entrant calls)
-  if (isAutoActive() || isAutoPaused()) return true;
-
-  const remote = checkRemoteAutoSession(projectRoot());
-  if (!remote.running || !remote.pid) return true;
-
-  const unitLabel = remote.unitType && remote.unitId
-    ? `${remote.unitType} (${remote.unitId})`
-    : "unknown unit";
-  const unitsMsg = remote.completedUnits != null
-    ? `${remote.completedUnits} units completed`
-    : "";
-
-  const choice = await showNextAction(ctx, {
-    title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
-    summary: [
-      `Currently executing: ${unitLabel}`,
-      ...(unitsMsg ? [unitsMsg] : []),
-      ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
-    ],
-    actions: [
-      {
-        id: "status",
-        label: "View status",
-        description: "Show the current GSD progress dashboard.",
-        recommended: true,
-      },
-      {
-        id: "steer",
-        label: "Steer the session",
-        description: "Use /gsd steer <instruction> to redirect the running session.",
-      },
-      {
-        id: "stop",
-        label: "Stop remote session",
-        description: `Send SIGTERM to PID ${remote.pid} to stop it gracefully.`,
-      },
-      {
-        id: "force",
-        label: "Force start (steal lock)",
-        description: "Start a new session, terminating the existing one.",
-      },
-    ],
-    notYetMessage: "Run /gsd when ready.",
-  });
-
-  if (choice === "status") {
-    await handleStatus(ctx);
-    return false;
-  }
-  if (choice === "steer") {
-    ctx.ui.notify(
-      "Use /gsd steer <instruction> to redirect the running auto-mode session.\n" +
-      "Example: /gsd steer Use Postgres instead of SQLite",
-      "info",
-    );
-    return false;
-  }
-  if (choice === "stop") {
-    const result = stopAutoRemote(projectRoot());
-    if (result.found) {
-      ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
-    } else if (result.error) {
-      ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
-    } else {
-      ctx.ui.notify("Remote session is no longer running.", "info");
-    }
-    return false;
-  }
-  if (choice === "force") {
-    return true; // Proceed — startAuto will steal the lock
-  }
-
-  // "not_yet" or escape
-  return false;
-}
-
-export function registerGSDCommand(pi: ExtensionAPI): void {
-  pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|capture|triage|dispatch|history|undo|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update",
-    getArgumentCompletions: (prefix: string) => {
-      const subcommands = [
-        { cmd: "help", desc: "Categorized command reference with descriptions" },
-        { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
-        { cmd: "auto", desc: "Autonomous mode — research, plan, execute, commit, repeat" },
-        { cmd: "stop", desc: "Stop auto mode gracefully" },
-        { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
-        { cmd: "status", desc: "Progress dashboard" },
-        { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
-        { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
-        { cmd: "queue", desc: "Queue and reorder future milestones" },
-        { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
-        { cmd: "discuss", desc: "Discuss architecture and decisions" },
-        { cmd: "capture", desc: "Fire-and-forget thought capture" },
-        { cmd: "changelog", desc: "Show categorized release notes" },
-        { cmd: "triage", desc: "Manually trigger triage of pending captures" },
-        { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
-        { cmd: "history", desc: "View execution history" },
-        { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
-        { cmd: "undo", desc: "Revert last completed unit" },
-        { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
-        { cmd: "export", desc: "Export milestone/slice results" },
-        { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
-        { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
-        { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
-        { cmd: "config", desc: "Set API keys for external tools" },
-        { cmd: "keys", desc: "API key manager — list, add, remove, test, rotate, doctor" },
-        { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
-        { cmd: "run-hook", desc: "Manually trigger a specific hook" },
-        { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
-        { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
-        { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
-        { cmd: "forensics", desc: "Examine execution logs" },
-        { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
-        { cmd: "setup", desc: "Global setup status and configuration" },
-        { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
-        { cmd: "remote", desc: "Control remote auto-mode" },
-        { cmd: "steer", desc: "Hard-steer plan documents during execution" },
-        { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
-        { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
-        { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
-        { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
-        { cmd: "cmux", desc: "Manage cmux integration (status, sidebar, notifications, splits)" },
-        { cmd: "park", desc: "Park a milestone — skip without deleting" },
-        { cmd: "unpark", desc: "Reactivate a parked milestone" },
-        { cmd: "update", desc: "Update GSD to the latest version" },
-        { cmd: "start", desc: "Start a workflow template (bugfix, spike, feature, etc.)" },
-        { cmd: "templates", desc: "List available workflow templates" },
-        { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
-      ];
-      const hasTrailingSpace = prefix.endsWith(" ");
-      const parts = prefix.trim().split(/\s+/);
-      if (hasTrailingSpace && parts.length >= 1) {
-        parts.push("");
-      }
-
-      if (parts.length <= 1) {
-        return subcommands
-          .filter((item) => item.cmd.startsWith(parts[0] ?? ""))
-          .map((item) => ({
-            value: item.cmd,
-            label: item.cmd,
-            description: item.desc
-          }));
-      }
-
-      if (parts[0] === "auto" && parts.length <= 2) {
-        const flagPrefix = parts[1] ?? "";
-        const flags = [
-          { flag: "--verbose", desc: "Show detailed execution output" },
-          { flag: "--debug", desc: "Enable debug logging" },
-        ];
-        return flags
-          .filter((f) => f.flag.startsWith(flagPrefix))
-          .map((f) => ({ value: `auto ${f.flag}`, label: f.flag, description: f.desc }));
-      }
-
-      if (parts[0] === "mode" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const modes = [
-          { cmd: "global", desc: "Edit global workflow mode" },
-          { cmd: "project", desc: "Edit project-specific workflow mode" },
-        ];
-        return modes
-          .filter((m) => m.cmd.startsWith(subPrefix))
-          .map((m) => ({ value: `mode ${m.cmd}`, label: m.cmd, description: m.desc }));
-      }
-
-      if (parts[0] === "parallel" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "start", desc: "Start parallel milestone orchestration" },
-          { cmd: "status", desc: "Show parallel worker statuses" },
-          { cmd: "stop", desc: "Stop all parallel workers" },
-          { cmd: "pause", desc: "Pause a specific worker" },
-          { cmd: "resume", desc: "Resume a paused worker" },
-          { cmd: "merge", desc: "Merge completed milestone branches" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `parallel ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "cmux") {
-        if (parts.length <= 2) {
-          const subPrefix = parts[1] ?? "";
-          const subs = [
-            { cmd: "status", desc: "Show cmux detection, prefs, and capabilities" },
-            { cmd: "on", desc: "Enable cmux integration" },
-            { cmd: "off", desc: "Disable cmux integration" },
-            { cmd: "notifications", desc: "Toggle cmux desktop notifications" },
-            { cmd: "sidebar", desc: "Toggle cmux sidebar metadata" },
-            { cmd: "splits", desc: "Toggle cmux visual subagent splits" },
-            { cmd: "browser", desc: "Toggle future browser integration flag" },
-          ];
-          return subs
-            .filter((s) => s.cmd.startsWith(subPrefix))
-            .map((s) => ({ value: `cmux ${s.cmd}`, label: s.cmd, description: s.desc }));
-        }
-
-        if (parts.length <= 3 && ["notifications", "sidebar", "splits", "browser"].includes(parts[1])) {
-          const togglePrefix = parts[2] ?? "";
-          return [
-            { cmd: "on", desc: "Enable this cmux area" },
-            { cmd: "off", desc: "Disable this cmux area" },
-          ]
-            .filter((item) => item.cmd.startsWith(togglePrefix))
-            .map((item) => ({
-              value: `cmux ${parts[1]} ${item.cmd}`,
-              label: item.cmd,
-              description: item.desc,
-            }));
-        }
-      }
-
-      if (parts[0] === "setup" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "llm", desc: "Configure LLM provider settings" },
-          { cmd: "search", desc: "Configure web search provider" },
-          { cmd: "remote", desc: "Configure remote integrations" },
-          { cmd: "keys", desc: "Manage API keys" },
-          { cmd: "prefs", desc: "Configure global preferences" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `setup ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "logs" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "debug", desc: "List or view debug log files" },
-          { cmd: "tail", desc: "Show last N activity log summaries" },
-          { cmd: "clear", desc: "Remove old activity and debug logs" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `logs ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "keys" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "list", desc: "Show key status dashboard" },
-          { cmd: "add", desc: "Add a key for a provider" },
-          { cmd: "remove", desc: "Remove a key" },
-          { cmd: "test", desc: "Validate key(s) with API call" },
-          { cmd: "rotate", desc: "Replace an existing key" },
-          { cmd: "doctor", desc: "Health check all keys" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `keys ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "prefs" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "global", desc: "Edit global preferences file" },
-          { cmd: "project", desc: "Edit project preferences file" },
-          { cmd: "status", desc: "Show effective preferences" },
-          { cmd: "wizard", desc: "Interactive preferences wizard" },
-          { cmd: "setup", desc: "First-time preferences setup" },
-          { cmd: "import-claude", desc: "Import settings from Claude Code" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `prefs ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "remote" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "slack", desc: "Configure Slack integration" },
-          { cmd: "discord", desc: "Configure Discord integration" },
-          { cmd: "status", desc: "Show remote connection status" },
-          { cmd: "disconnect", desc: "Disconnect remote integrations" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `remote ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "next" && parts.length <= 2) {
-        const flagPrefix = parts[1] ?? "";
-        const flags = [
-          { flag: "--verbose", desc: "Show detailed step output" },
-          { flag: "--dry-run", desc: "Preview next step without executing" },
-        ];
-        return flags
-          .filter((f) => f.flag.startsWith(flagPrefix))
-          .map((f) => ({ value: `next ${f.flag}`, label: f.flag, description: f.desc }));
-      }
-
-      if (parts[0] === "history" && parts.length <= 2) {
-        const flagPrefix = parts[1] ?? "";
-        const flags = [
-          { flag: "--cost", desc: "Show cost breakdown per entry" },
-          { flag: "--phase", desc: "Filter by phase type" },
-          { flag: "--model", desc: "Filter by model used" },
-          { flag: "10", desc: "Show last 10 entries" },
-          { flag: "20", desc: "Show last 20 entries" },
-          { flag: "50", desc: "Show last 50 entries" },
-        ];
-        return flags
-          .filter((f) => f.flag.startsWith(flagPrefix))
-          .map((f) => ({ value: `history ${f.flag}`, label: f.flag, description: f.desc }));
-      }
-
-      if (parts[0] === "undo" && parts.length <= 2) {
-        return [{ value: "undo --force", label: "--force", description: "Skip confirmation prompt" }];
-      }
-
-      if (parts[0] === "export" && parts.length <= 2) {
-        const flagPrefix = parts[1] ?? "";
-        const flags = [
-          { flag: "--json", desc: "Export as JSON" },
-          { flag: "--markdown", desc: "Export as Markdown" },
-          { flag: "--html", desc: "Export as HTML" },
-          { flag: "--html --all", desc: "Export all milestones as HTML" },
-        ];
-        return flags
-          .filter((f) => f.flag.startsWith(flagPrefix))
-          .map((f) => ({ value: `export ${f.flag}`, label: f.flag, description: f.desc }));
-      }
-
-      if (parts[0] === "cleanup" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "branches", desc: "Remove merged milestone branches" },
-          { cmd: "snapshots", desc: "Remove old execution snapshots" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `cleanup ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "knowledge" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "rule", desc: "Add a project rule (always/never do X)" },
-          { cmd: "pattern", desc: "Add a code pattern to follow" },
-          { cmd: "lesson", desc: "Record a lesson learned" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `knowledge ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "start" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "bugfix", desc: "Triage, fix, test, and ship a bug fix" },
-          { cmd: "small-feature", desc: "Lightweight feature with optional discussion" },
-          { cmd: "spike", desc: "Research, prototype, and document findings" },
-          { cmd: "hotfix", desc: "Minimal: fix it, test it, ship it" },
-          { cmd: "refactor", desc: "Inventory, plan waves, migrate, verify" },
-          { cmd: "security-audit", desc: "Scan, triage, remediate, re-scan" },
-          { cmd: "dep-upgrade", desc: "Assess, upgrade, fix breaks, verify" },
-          { cmd: "full-project", desc: "Complete GSD workflow with full ceremony" },
-          { cmd: "resume", desc: "Resume an in-progress workflow" },
-          { cmd: "--list", desc: "List all available templates" },
-          { cmd: "--dry-run", desc: "Preview workflow without executing" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `start ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "templates" && parts.length <= 2) {
-        const subPrefix = parts[1] ?? "";
-        const subs = [
-          { cmd: "info", desc: "Show detailed template info" },
-        ];
-        return subs
-          .filter((s) => s.cmd.startsWith(subPrefix))
-          .map((s) => ({ value: `templates ${s.cmd}`, label: s.cmd, description: s.desc }));
-      }
-
-      if (parts[0] === "templates" && parts[1] === "info" && parts.length <= 3) {
-        const namePrefix = parts[2] ?? "";
-        return getTemplateCompletions(namePrefix)
-          .map((c) => ({ value: `templates ${c.value}`, label: c.label, description: c.description }));
-      }
-
-      if (parts[0] === "extensions") {
-        if (parts.length <= 2) {
-          const subPrefix = parts[1] ?? "";
-          const subs = [
-            { cmd: "list", desc: "List all extensions and their status" },
-            { cmd: "enable", desc: "Enable a disabled extension" },
-            { cmd: "disable", desc: "Disable an extension" },
-            { cmd: "info", desc: "Show extension details" },
-          ];
-          return subs
-            .filter((s) => s.cmd.startsWith(subPrefix))
-            .map((s) => ({ value: `extensions ${s.cmd}`, label: s.cmd, description: s.desc }));
-        }
-        if (parts.length === 3 && ["enable", "disable", "info"].includes(parts[1])) {
-          const idPrefix = parts[2] ?? "";
-          try {
-            const extDir = join(gsdHome, "agent", "extensions");
-            const ids: { id: string; name: string }[] = [];
-            for (const entry of readdirSync(extDir, { withFileTypes: true })) {
-              if (!entry.isDirectory()) continue;
-              const mPath = join(extDir, entry.name, "extension-manifest.json");
-              if (!existsSync(mPath)) continue;
-              try {
-                const m = JSON.parse(readFileSync(mPath, "utf-8"));
-                if (typeof m?.id === "string") ids.push({ id: m.id, name: m.name ?? m.id });
-              } catch { /* skip malformed */ }
-            }
-            return ids
-              .filter((e) => e.id.startsWith(idPrefix))
-              .map((e) => ({
-                value: `extensions ${parts[1]} ${e.id}`,
-                label: e.id,
-                description: e.name,
-              }));
-          } catch {
-            return [];
-          }
-        }
-        return [];
-      }
-
-      if (parts[0] === "doctor") {
-        const modePrefix = parts[1] ?? "";
-        const modes = [
-          { cmd: "fix", desc: "Auto-fix detected issues" },
-          { cmd: "heal", desc: "AI-driven deep healing" },
-          { cmd: "audit", desc: "Run health audit without fixing" },
-          { cmd: "--dry-run", desc: "Show what --fix would change without applying" },
-          { cmd: "--json", desc: "Output report as JSON (CI/tooling friendly)" },
-          { cmd: "--build", desc: "Include slow build health check (npm run build)" },
-          { cmd: "--test", desc: "Include slow test health check (npm test)" },
-        ];
-
-        if (parts.length <= 2) {
-          return modes
-            .filter((m) => m.cmd.startsWith(modePrefix))
-            .map((m) => ({ value: `doctor ${m.cmd}`, label: m.cmd, description: m.desc }));
-        }
-
-        return [];
-      }
-
-      if (parts[0] === "dispatch" && parts.length <= 2) {
-        const phasePrefix = parts[1] ?? "";
-        const phases = [
-          { cmd: "research", desc: "Run research phase" },
-          { cmd: "plan", desc: "Run planning phase" },
-          { cmd: "execute", desc: "Run execution phase" },
-          { cmd: "complete", desc: "Run completion phase" },
-          { cmd: "reassess", desc: "Reassess current progress" },
-          { cmd: "uat", desc: "Run user acceptance testing" },
-          { cmd: "replan", desc: "Replan the current slice" },
-        ];
-        return phases
-          .filter((p) => p.cmd.startsWith(phasePrefix))
-          .map((p) => ({ value: `dispatch ${p.cmd}`, label: p.cmd, description: p.desc }));
-      }
-
-      if (parts[0] === "rate" && parts.length <= 2) {
-        const tierPrefix = parts[1] ?? "";
-        const tiers = [
-          { cmd: "over", desc: "Model was overqualified for this task" },
-          { cmd: "ok", desc: "Model was appropriate for this task" },
-          { cmd: "under", desc: "Model was underqualified for this task" },
-        ];
-        return tiers
-          .filter((t) => t.cmd.startsWith(tierPrefix))
-          .map((t) => ({ value: `rate ${t.cmd}`, label: t.cmd, description: t.desc }));
-      }
-
-      return [];
-    },
-
-    async handler(args: string, ctx: ExtensionCommandContext) {
-      await handleGSDCommand(args, ctx, pi);
-    },
-  });
-}
+export { registerGSDCommand } from "./commands/index.js";
 
 export async function handleGSDCommand(
-  args: string,
-  ctx: ExtensionCommandContext,
-  pi: ExtensionAPI,
-): Promise<void> {
-  const trimmed = (typeof args === "string" ? args : "").trim();
-
-  if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
-    showHelp(ctx);
-    return;
-  }
-
-  if (trimmed === "status") {
-    await handleStatus(ctx);
-    return;
-  }
-
-  if (trimmed === "widget" || trimmed.startsWith("widget ")) {
-    const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await importExtensionModule<typeof import("./auto-dashboard.js")>(import.meta.url, "./auto-dashboard.js");
-    const arg = trimmed.replace(/^widget\s*/, "").trim();
-    if (arg === "full" || arg === "small" || arg === "min" || arg === "off") {
-      setWidgetMode(arg);
-    } else {
-      cycleWidgetMode();
-    }
-    ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
-    return;
-  }
-
-  if (trimmed === "visualize") {
-    await handleVisualize(ctx);
-    return;
-  }
-
-  if (trimmed === "mode" || trimmed.startsWith("mode ")) {
-    const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
-    const scope = modeArgs === "project" ? "project" : "global";
-    const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
-    await ensurePreferencesFile(path, ctx, scope);
-    await handlePrefsMode(ctx, scope);
-    return;
-  }
-
-  if (trimmed === "prefs" || trimmed.startsWith("prefs ")) {
-    await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
-    return;
-  }
-
-  if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
-    await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
-    return;
-  }
-
-      if (trimmed === "init") {
-        const { detectProjectState } = await import("./detection.js");
-        const { showProjectInit, handleReinit } = await import("./init-wizard.js");
-        const basePath = projectRoot();
-        const detection = detectProjectState(basePath);
-        if (detection.state === "v2-gsd" || detection.state === "v2-gsd-empty") {
-          await handleReinit(ctx, detection);
-        } else {
-          await showProjectInit(ctx, pi, basePath, detection);
-        }
-        return;
-      }
-
-      if (trimmed === "keys" || trimmed.startsWith("keys ")) {
-        const { handleKeys } = await import("./key-manager.js");
-        const keysArgs = trimmed.replace(/^keys\s*/, "").trim();
-        await handleKeys(keysArgs, ctx);
-        return;
-      }
-
-      if (trimmed === "setup" || trimmed.startsWith("setup ")) {
-        const setupArgs = trimmed.replace(/^setup\s*/, "").trim();
-        await handleSetup(setupArgs, ctx);
-        return;
-      }
-
-      if (trimmed === "doctor" || trimmed.startsWith("doctor ")) {
-        await handleDoctor(trimmed.replace(/^doctor\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "logs" || trimmed.startsWith("logs ")) {
-        await handleLogs(trimmed.replace(/^logs\s*/, "").trim(), ctx);
-        return;
-      }
-
-      if (trimmed === "forensics" || trimmed.startsWith("forensics ")) {
-        const { handleForensics } = await import("./forensics.js");
-        await handleForensics(trimmed.replace(/^forensics\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "changelog" || trimmed.startsWith("changelog ")) {
-        const { handleChangelog } = await import("./changelog.js");
-        await handleChangelog(trimmed.replace(/^changelog\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "next" || trimmed.startsWith("next ")) {
-        if (trimmed.includes("--dry-run")) {
-          await handleDryRun(ctx, projectRoot());
-          return;
-        }
-        const verboseMode = trimmed.includes("--verbose");
-        const debugMode = trimmed.includes("--debug");
-        if (debugMode) enableDebug(projectRoot());
-        if (!(await guardRemoteSession(ctx, pi))) return;
-        await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
-        return;
-      }
-
-      if (trimmed === "auto" || trimmed.startsWith("auto ")) {
-        const verboseMode = trimmed.includes("--verbose");
-        const debugMode = trimmed.includes("--debug");
-        if (debugMode) enableDebug(projectRoot());
-        if (!(await guardRemoteSession(ctx, pi))) return;
-        await startAuto(ctx, pi, projectRoot(), verboseMode);
-        return;
-      }
-
-      if (trimmed === "stop") {
-        if (!isAutoActive() && !isAutoPaused()) {
-          // Not running in this process — check for a remote auto-mode session
-          const result = stopAutoRemote(projectRoot());
-          if (result.found) {
-            ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
-          } else if (result.error) {
-            ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
-          } else {
-            ctx.ui.notify("Auto-mode is not running.", "info");
-          }
-          return;
-        }
-        await stopAuto(ctx, pi, "User requested stop");
-        return;
-      }
-
-      if (trimmed === "pause") {
-        if (!isAutoActive()) {
-          if (isAutoPaused()) {
-            ctx.ui.notify("Auto-mode is already paused. /gsd auto to resume.", "info");
-          } else {
-            ctx.ui.notify("Auto-mode is not running.", "info");
-          }
-          return;
-        }
-        await pauseAuto(ctx, pi);
-        return;
-      }
-
-      if (trimmed === "history" || trimmed.startsWith("history ")) {
-        await handleHistory(trimmed.replace(/^history\s*/, "").trim(), ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed === "undo" || trimmed.startsWith("undo ")) {
-        await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
-        return;
-      }
-
-      if (trimmed === "rate" || trimmed.startsWith("rate ")) {
-        const { handleRate } = await import("./commands-rate.js");
-        await handleRate(trimmed.replace(/^rate\s*/, "").trim(), ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed.startsWith("skip ")) {
-        await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed === "export" || trimmed.startsWith("export ")) {
-        await handleExport(trimmed.replace(/^export\s*/, "").trim(), ctx, projectRoot());
-        return;
-      }
-
-      // ─── Parallel Orchestration ────────────────────────────────────────
-      if (trimmed.startsWith("parallel")) {
-        const parallelArgs = trimmed.slice("parallel".length).trim();
-        const [subCmd = "", ...restParts] = parallelArgs.split(/\s+/);
-        const rest = restParts.join(" ");
-
-        if (subCmd === "start" || subCmd === "") {
-          const loaded = loadEffectiveGSDPreferences();
-          const config = resolveParallelConfig(loaded?.preferences);
-          if (!config.enabled) {
-            pi.sendMessage({
-              customType: "gsd-parallel",
-              content: "Parallel mode is not enabled. Set `parallel.enabled: true` in your preferences.",
-              display: false,
-            });
-            return;
-          }
-          const candidates = await prepareParallelStart(projectRoot(), loaded?.preferences);
-          const report = formatEligibilityReport(candidates);
-          if (candidates.eligible.length === 0) {
-            pi.sendMessage({ customType: "gsd-parallel", content: report + "\n\nNo milestones are eligible for parallel execution.", display: false });
-            return;
-          }
-          const result = await startParallel(
-            projectRoot(),
-            candidates.eligible.map(e => e.milestoneId),
-            loaded?.preferences,
-          );
-          const lines = [`Parallel orchestration started.`, `Workers: ${result.started.join(", ")}`];
-          if (result.errors.length > 0) {
-            lines.push(`Errors: ${result.errors.map(e => `${e.mid}: ${e.error}`).join("; ")}`);
-          }
-          pi.sendMessage({ customType: "gsd-parallel", content: report + "\n\n" + lines.join("\n"), display: false });
-          return;
-        }
-
-        if (subCmd === "status") {
-          if (!isParallelActive()) {
-            pi.sendMessage({ customType: "gsd-parallel", content: "No parallel orchestration is currently active.", display: false });
-            return;
-          }
-          const workers = getWorkerStatuses();
-          const lines = ["# Parallel Workers\n"];
-          for (const w of workers) {
-            lines.push(`- **${w.milestoneId}** (${w.title}) — ${w.state} — ${w.completedUnits} units — $${w.cost.toFixed(2)}`);
-          }
-          const orchState = getOrchestratorState();
-          if (orchState) {
-            lines.push(`\nTotal cost: $${orchState.totalCost.toFixed(2)}`);
-          }
-          pi.sendMessage({ customType: "gsd-parallel", content: lines.join("\n"), display: false });
-          return;
-        }
-
-        if (subCmd === "stop") {
-          const mid = rest.trim() || undefined;
-          await stopParallel(projectRoot(), mid);
-          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Stopped worker for ${mid}.` : "All parallel workers stopped.", display: false });
-          return;
-        }
-
-        if (subCmd === "pause") {
-          const mid = rest.trim() || undefined;
-          pauseWorker(projectRoot(), mid);
-          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Paused worker for ${mid}.` : "All parallel workers paused.", display: false });
-          return;
-        }
-
-        if (subCmd === "resume") {
-          const mid = rest.trim() || undefined;
-          resumeWorker(projectRoot(), mid);
-          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Resumed worker for ${mid}.` : "All parallel workers resumed.", display: false });
-          return;
-        }
-
-        if (subCmd === "merge") {
-          const mid = rest.trim() || undefined;
-          if (mid) {
-            // Merge a specific milestone
-            const result = await mergeCompletedMilestone(projectRoot(), mid);
-            pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults([result]), display: false });
-            return;
-          }
-          // Merge all completed milestones
-          const workers = getWorkerStatuses();
-          if (workers.length === 0) {
-            pi.sendMessage({ customType: "gsd-parallel", content: "No parallel workers to merge.", display: false });
-            return;
-          }
-          const results = await mergeAllCompleted(projectRoot(), workers);
-          pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults(results), display: false });
-          return;
-        }
-
-        pi.sendMessage({
-          customType: "gsd-parallel",
-          content: `Unknown parallel subcommand "${subCmd}". Usage: /gsd parallel [start|status|stop|pause|resume|merge]`,
-          display: false,
-        });
-        return;
-      }
-
-      if (trimmed === "cleanup") {
-        await handleCleanupBranches(ctx, projectRoot());
-        await handleCleanupSnapshots(ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed === "cleanup branches") {
-        await handleCleanupBranches(ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed === "cleanup snapshots") {
-        await handleCleanupSnapshots(ctx, projectRoot());
-        return;
-      }
-
-      if (trimmed === "queue") {
-        await showQueue(ctx, pi, projectRoot());
-        return;
-      }
-
-      if (trimmed === "discuss") {
-        await showDiscuss(ctx, pi, projectRoot());
-        return;
-      }
-
-      if (trimmed === "park" || trimmed.startsWith("park ")) {
-        const basePath = projectRoot();
-        const arg = trimmed.replace(/^park\s*/, "").trim();
-        const { parkMilestone, isParked } = await import("./milestone-actions.js");
-        const { deriveState } = await import("./state.js");
-
-        let targetId = arg;
-        if (!targetId) {
-          // Park the current active milestone
-          const state = await deriveState(basePath);
-          if (!state.activeMilestone) {
-            ctx.ui.notify("No active milestone to park.", "warning");
-            return;
-          }
-          targetId = state.activeMilestone.id;
-        }
-
-        if (isParked(basePath, targetId)) {
-          ctx.ui.notify(`${targetId} is already parked. Use /gsd unpark ${targetId} to reactivate.`, "info");
-          return;
-        }
-
-        // Extract reason from remaining args (e.g., /gsd park M002 "reason here")
-        const reasonParts = arg.replace(targetId, "").trim().replace(/^["']|["']$/g, "");
-        const reason = reasonParts || "Parked via /gsd park";
-
-        const success = parkMilestone(basePath, targetId, reason);
-        if (success) {
-          ctx.ui.notify(`Parked ${targetId}. Run /gsd unpark ${targetId} to reactivate.`, "info");
-        } else {
-          ctx.ui.notify(`Could not park ${targetId} — milestone not found.`, "warning");
-        }
-        return;
-      }
-
-      if (trimmed === "unpark" || trimmed.startsWith("unpark ")) {
-        const basePath = projectRoot();
-        const arg = trimmed.replace(/^unpark\s*/, "").trim();
-        const { unparkMilestone } = await import("./milestone-actions.js");
-        const { deriveState } = await import("./state.js");
-
-        let targetId = arg;
-        if (!targetId) {
-          // List parked milestones and let user pick
-          const state = await deriveState(basePath);
-          const parkedEntries = state.registry.filter(e => e.status === "parked");
-          if (parkedEntries.length === 0) {
-            ctx.ui.notify("No parked milestones.", "info");
-            return;
-          }
-          if (parkedEntries.length === 1) {
-            targetId = parkedEntries[0].id;
-          } else {
-            ctx.ui.notify(`Parked milestones: ${parkedEntries.map(e => e.id).join(", ")}. Specify which to unpark: /gsd unpark <id>`, "info");
-            return;
-          }
-        }
-
-        const success = unparkMilestone(basePath, targetId);
-        if (success) {
-          ctx.ui.notify(`Unparked ${targetId}. It will resume its normal position in the queue.`, "info");
-        } else {
-          ctx.ui.notify(`Could not unpark ${targetId} — milestone not found or not parked.`, "warning");
-        }
-        return;
-      }
-
-      if (trimmed === "new-milestone") {
-        const basePath = projectRoot();
-        const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
-        if (existsSync(headlessContextPath)) {
-          const seedContext = readFileSync(headlessContextPath, "utf-8");
-          try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }
-          await showHeadlessMilestoneCreation(ctx, pi, basePath, seedContext);
-        } else {
-          // No headless context — fall back to interactive smart entry
-          const { showSmartEntry } = await import("./guided-flow.js");
-          await showSmartEntry(ctx, pi, basePath);
-        }
-        return;
-      }
-
-      if (trimmed.startsWith("capture ") || trimmed === "capture") {
-        await handleCapture(trimmed.replace(/^capture\s*/, "").trim(), ctx);
-        return;
-      }
-
-      if (trimmed === "triage") {
-        await handleTriage(ctx, pi, process.cwd());
-        return;
-      }
-
-      if (trimmed === "quick" || trimmed.startsWith("quick ")) {
-        await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "config") {
-        await handleConfig(ctx);
-        return;
-      }
-
-      if (trimmed === "hooks") {
-        const { formatHookStatus } = await import("./post-unit-hooks.js");
-        ctx.ui.notify(formatHookStatus(), "info");
-        return;
-      }
-
-      // ─── Skill Health ────────────────────────────────────────────
-      if (trimmed === "skill-health" || trimmed.startsWith("skill-health ")) {
-        await handleSkillHealth(trimmed.replace(/^skill-health\s*/, "").trim(), ctx);
-        return;
-      }
-
-      if (trimmed.startsWith("run-hook ")) {
-        await handleRunHook(trimmed.replace(/^run-hook\s*/, "").trim(), ctx, pi);
-        return;
-      }
-      if (trimmed === "run-hook") {
-        ctx.ui.notify(`Usage: /gsd run-hook <hook-name> <unit-type> <unit-id>
-
-Unit types:
-  execute-task   - Task execution (unit-id: M001/S01/T01)
-  plan-slice     - Slice planning (unit-id: M001/S01)
-  research-milestone - Milestone research (unit-id: M001)
-  complete-slice - Slice completion (unit-id: M001/S01)
-  complete-milestone - Milestone completion (unit-id: M001)
-
-Examples:
-  /gsd run-hook code-review execute-task M001/S01/T01
-  /gsd run-hook lint-check plan-slice M001/S01`, "warning");
-        return;
-      }
-
-      if (trimmed.startsWith("steer ")) {
-        await handleSteer(trimmed.replace(/^steer\s+/, "").trim(), ctx, pi);
-        return;
-      }
-      if (trimmed === "steer") {
-        ctx.ui.notify("Usage: /gsd steer <description of change>. Example: /gsd steer Use Postgres instead of SQLite", "warning");
-        return;
-      }
-
-      if (trimmed.startsWith("knowledge ")) {
-        await handleKnowledge(trimmed.replace(/^knowledge\s+/, "").trim(), ctx);
-        return;
-      }
-      if (trimmed === "knowledge") {
-        ctx.ui.notify("Usage: /gsd knowledge <rule|pattern|lesson> <description>. Example: /gsd knowledge rule Use real DB for integration tests", "warning");
-        return;
-      }
-
-      if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
-        const { handleMigrate } = await import("./migrate/command.js");
-        await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "remote" || trimmed.startsWith("remote ")) {
-        await handleRemote(trimmed.replace(/^remote\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "dispatch" || trimmed.startsWith("dispatch ")) {
-        const phase = trimmed.replace(/^dispatch\s*/, "").trim();
-        if (!phase) {
-          ctx.ui.notify("Usage: /gsd dispatch <phase>  (research|plan|execute|complete|reassess|uat|replan)", "warning");
-          return;
-        }
-        await dispatchDirectPhase(ctx, pi, phase, projectRoot());
-        return;
-      }
-
-      if (trimmed === "inspect") {
-        await handleInspect(ctx);
-        return;
-      }
-
-      if (trimmed === "update") {
-        await handleUpdate(ctx);
-        return;
-      }
-
-      // ─── Workflow Templates ────────────────────────────────────────
-      if (trimmed === "start" || trimmed.startsWith("start ")) {
-        await handleStart(trimmed.replace(/^start\s*/, "").trim(), ctx, pi);
-        return;
-      }
-
-      if (trimmed === "templates" || trimmed.startsWith("templates ")) {
-        await handleTemplates(trimmed.replace(/^templates\s*/, "").trim(), ctx);
-        return;
-      }
-
-      if (trimmed === "") {
-        if (!(await guardRemoteSession(ctx, pi))) return;
-        await startAuto(ctx, pi, projectRoot(), false, { step: true });
-        return;
-      }
-
-      if (trimmed === "extensions" || trimmed.startsWith("extensions ")) {
-        const { handleExtensions } = await import("./commands-extensions.js");
-        await handleExtensions(trimmed.replace(/^extensions\s*/, "").trim(), ctx);
-        return;
-      }
-
-  ctx.ui.notify(
-    `Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`,
-    "warning",
-  );
-}
-
-function showHelp(ctx: ExtensionCommandContext): void {
-  const lines = [
-    "GSD — Get Shit Done\n",
-    "WORKFLOW",
-    "  /gsd start <tpl>   Start a workflow template (bugfix, spike, feature, hotfix, etc.)",
-    "  /gsd templates     List available workflow templates  [info <name>]",
-    "  /gsd               Run next unit in step mode (same as /gsd next)",
-    "  /gsd next           Execute next task, then pause  [--dry-run] [--verbose]",
-    "  /gsd auto           Run all queued units continuously  [--verbose]",
-    "  /gsd stop           Stop auto-mode gracefully",
-    "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
-    "  /gsd discuss        Start guided milestone/slice discussion",
-    "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
-    "",
-    "VISIBILITY",
-    "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",
-    "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
-    "  /gsd queue          Show queued/dispatched units and execution order",
-    "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
-    "  /gsd changelog      Show categorized release notes  [version]",
-    "",
-    "COURSE CORRECTION",
-    "  /gsd steer <desc>   Apply user override to active work",
-    "  /gsd capture <text> Quick-capture a thought to CAPTURES.md",
-    "  /gsd triage         Classify and route pending captures",
-    "  /gsd skip <unit>    Prevent a unit from auto-mode dispatch",
-    "  /gsd undo           Revert last completed unit  [--force]",
-    "  /gsd park [id]      Park a milestone — skip without deleting  [reason]",
-    "  /gsd unpark [id]    Reactivate a parked milestone",
-    "",
-    "PROJECT KNOWLEDGE",
-    "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
-    "",
-    "SETUP & CONFIGURATION",
-    "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
-    "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
-    "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
-    "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
-    "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
-    "  /gsd config         Set API keys for external tools",
-    "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
-    "  /gsd hooks          Show post-unit hook configuration",
-    "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
-    "",
-    "MAINTENANCE",
-    "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
-    "  /gsd export         Export milestone/slice results  [--json|--markdown|--html] [--all]",
-    "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
-    "  /gsd migrate        Migrate .planning/ (v1) to .gsd/ (v2) format",
-    "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
-    "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
-    "  /gsd update         Update GSD to the latest version via npm",
-  ];
-  ctx.ui.notify(lines.join("\n"), "info");
-}
-
-async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
-  const basePath = projectRoot();
-  const state = await deriveState(basePath);
-
-  if (state.registry.length === 0) {
-    ctx.ui.notify("No GSD milestones found. Run /gsd to start.", "info");
-    return;
-  }
-
-  const result = await ctx.ui.custom<void>(
-    (tui, theme, _kb, done) => {
-      return new GSDDashboardOverlay(tui, theme, () => done());
-    },
-    {
-      overlay: true,
-      overlayOptions: {
-        width: "70%",
-        minWidth: 60,
-        maxHeight: "90%",
-        anchor: "center",
-      },
-    },
-  );
-
-  // Fallback for RPC mode where ctx.ui.custom() returns undefined.
-  // Produce a text-based status summary so the turn is not empty.
-  if (result === undefined) {
-    ctx.ui.notify(formatTextStatus(state), "info");
-  }
+  ...args: Parameters<typeof import("./commands/dispatcher.js").handleGSDCommand>
+) {
+  const { handleGSDCommand: dispatch } = await import("./commands/dispatcher.js");
+  return dispatch(...args);
 }
 
 export async function fireStatusViaCommand(
-  ctx: import("@gsd/pi-coding-agent").ExtensionContext,
-): Promise<void> {
-  await handleStatus(ctx as ExtensionCommandContext);
-}
-
-async function handleVisualize(ctx: ExtensionCommandContext): Promise<void> {
-  if (!ctx.hasUI) {
-    ctx.ui.notify("Visualizer requires an interactive terminal.", "warning");
-    return;
-  }
-
-  const result = await ctx.ui.custom<void>(
-    (tui, theme, _kb, done) => {
-      return new GSDVisualizerOverlay(tui, theme, () => done());
-    },
-    {
-      overlay: true,
-      overlayOptions: {
-        width: "80%",
-        minWidth: 80,
-        maxHeight: "90%",
-        anchor: "center",
-      },
-    },
+  ...args: Parameters<typeof import("./commands/handlers/core.js").fireStatusViaCommand>
+) {
+  const { fireStatusViaCommand: fireStatus } = await import(
+    "./commands/handlers/core.js"
   );
-
-  // Fallback for RPC mode where ctx.ui.custom() returns undefined.
-  if (result === undefined) {
-    ctx.ui.notify("Visualizer requires an interactive terminal. Use /gsd status for a text-based overview.", "warning");
-  }
-}
-
-async function handleSetup(args: string, ctx: ExtensionCommandContext): Promise<void> {
-  const { detectProjectState, hasGlobalSetup } = await import("./detection.js");
-
-  // Show current global setup status
-  const globalConfigured = hasGlobalSetup();
-  const detection = detectProjectState(projectRoot());
-
-  const statusLines = ["GSD Setup Status\n"];
-  statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
-  statusLines.push(`  Project state: ${detection.state}`);
-  if (detection.projectSignals.primaryLanguage) {
-    statusLines.push(`  Detected: ${detection.projectSignals.primaryLanguage}`);
-  }
-
-  if (args === "llm" || args === "auth") {
-    ctx.ui.notify("Use /login to configure LLM authentication.", "info");
-    return;
-  }
-
-  if (args === "search") {
-    ctx.ui.notify("Use /search-provider to configure web search.", "info");
-    return;
-  }
-
-  if (args === "remote") {
-    ctx.ui.notify("Use /gsd remote to configure remote questions.", "info");
-    return;
-  }
-
-  if (args === "keys") {
-    const { handleKeys } = await import("./key-manager.js");
-    await handleKeys("", ctx);
-    return;
-  }
-
-  if (args === "prefs") {
-    await ensurePreferencesFile(getGlobalGSDPreferencesPath(), ctx, "global");
-    await handlePrefsWizard(ctx, "global");
-    return;
-  }
-
-  // Full setup summary
-  ctx.ui.notify(statusLines.join("\n"), "info");
-  ctx.ui.notify(
-    "Available setup commands:\n" +
-    "  /gsd setup llm     — LLM authentication\n" +
-    "  /gsd setup search  — Web search provider\n" +
-    "  /gsd setup remote  — Remote questions (Discord/Slack/Telegram)\n" +
-    "  /gsd setup keys    — Tool API keys\n" +
-    "  /gsd setup prefs   — Global preferences wizard",
-    "info",
-  );
-}
-
-// ─── Text-based status for RPC mode ────────────────────────────────────────
-
-/**
- * Generate a text-based status summary for non-TUI environments (RPC mode).
- * Used as a fallback when the interactive dashboard overlay is unavailable.
- */
-function formatTextStatus(state: GSDState): string {
-  const lines: string[] = ["GSD Status\n"];
-
-  // Progress score — traffic light (#1221)
-  const progressScore = computeProgressScore();
-  lines.push(formatProgressLine(progressScore));
-  lines.push("");
-
-  // Phase
-  lines.push(`Phase: ${state.phase}`);
-
-  // Active milestone
-  if (state.activeMilestone) {
-    lines.push(`Active milestone: ${state.activeMilestone.id} — ${state.activeMilestone.title}`);
-  }
-
-  // Active slice / task
-  if (state.activeSlice) {
-    lines.push(`Active slice: ${state.activeSlice.id} — ${state.activeSlice.title}`);
-  }
-  if (state.activeTask) {
-    lines.push(`Active task: ${state.activeTask.id} — ${state.activeTask.title}`);
-  }
-
-  // Progress
-  if (state.progress) {
-    const { milestones, slices, tasks } = state.progress;
-    const parts: string[] = [];
-    parts.push(`milestones ${milestones.done}/${milestones.total}`);
-    if (slices) parts.push(`slices ${slices.done}/${slices.total}`);
-    if (tasks) parts.push(`tasks ${tasks.done}/${tasks.total}`);
-    lines.push(`Progress: ${parts.join(", ")}`);
-  }
-
-  // Next action
-  if (state.nextAction) {
-    lines.push(`Next: ${state.nextAction}`);
-  }
-
-  // Blockers
-  if (state.blockers.length > 0) {
-    lines.push(`Blockers: ${state.blockers.join("; ")}`);
-  }
-
-  // Milestone registry summary
-  if (state.registry.length > 0) {
-    lines.push("");
-    lines.push("Milestones:");
-    for (const m of state.registry) {
-      const statusIcon = m.status === "complete" ? "✓" : m.status === "active" ? "▶" : m.status === "parked" ? "⏸" : "○";
-      lines.push(`  ${statusIcon} ${m.id}: ${m.title} (${m.status})`);
-    }
-  }
-
-  // Environment health (#1221)
-  const envResults = runEnvironmentChecks(projectRoot());
-  const envIssues = envResults.filter(r => r.status !== "ok");
-  if (envIssues.length > 0) {
-    lines.push("");
-    lines.push("Environment:");
-    for (const r of envIssues) {
-      const icon = r.status === "error" ? "✗" : "⚠";
-      lines.push(`  ${icon} ${r.message}`);
-    }
-  }
-
-  return lines.join("\n");
+  return fireStatus(...args);
 }
diff --git a/src/resources/extensions/gsd/commands/catalog.ts b/src/resources/extensions/gsd/commands/catalog.ts
new file mode 100644
index 000000000..e085730e1
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/catalog.ts
@@ -0,0 +1,301 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { loadRegistry } from "../workflow-templates.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
+export interface GsdCommandDefinition {
+  cmd: string;
+  desc: string;
+}
+
+type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
+
+export const GSD_COMMAND_DESCRIPTION =
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|capture|triage|dispatch|history|undo|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update";
+
+export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
+  { cmd: "help", desc: "Categorized command reference with descriptions" },
+  { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
+  { cmd: "auto", desc: "Autonomous mode — research, plan, execute, commit, repeat" },
+  { cmd: "stop", desc: "Stop auto mode gracefully" },
+  { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
+  { cmd: "status", desc: "Progress dashboard" },
+  { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
+  { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
+  { cmd: "queue", desc: "Queue and reorder future milestones" },
+  { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
+  { cmd: "discuss", desc: "Discuss architecture and decisions" },
+  { cmd: "capture", desc: "Fire-and-forget thought capture" },
+  { cmd: "changelog", desc: "Show categorized release notes" },
+  { cmd: "triage", desc: "Manually trigger triage of pending captures" },
+  { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+  { cmd: "history", desc: "View execution history" },
+  { cmd: "undo", desc: "Revert last completed unit" },
+  { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
+  { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
+  { cmd: "export", desc: "Export milestone/slice results" },
+  { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+  { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
+  { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
+  { cmd: "config", desc: "Set API keys for external tools" },
+  { cmd: "keys", desc: "API key manager — list, add, remove, test, rotate, doctor" },
+  { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
+  { cmd: "run-hook", desc: "Manually trigger a specific hook" },
+  { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+  { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
+  { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
+  { cmd: "forensics", desc: "Examine execution logs" },
+  { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
+  { cmd: "setup", desc: "Global setup status and configuration" },
+  { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
+  { cmd: "remote", desc: "Control remote auto-mode" },
+  { cmd: "steer", desc: "Hard-steer plan documents during execution" },
+  { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
+  { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
+  { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
+  { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
+  { cmd: "cmux", desc: "Manage cmux integration (status, sidebar, notifications, splits)" },
+  { cmd: "park", desc: "Park a milestone — skip without deleting" },
+  { cmd: "unpark", desc: "Reactivate a parked milestone" },
+  { cmd: "update", desc: "Update GSD to the latest version" },
+  { cmd: "start", desc: "Start a workflow template (bugfix, spike, feature, etc.)" },
+  { cmd: "templates", desc: "List available workflow templates" },
+  { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
+];
+
+const NESTED_COMPLETIONS: CompletionMap = {
+  auto: [
+    { cmd: "--verbose", desc: "Show detailed execution output" },
+    { cmd: "--debug", desc: "Enable debug logging" },
+  ],
+  next: [
+    { cmd: "--verbose", desc: "Show detailed step output" },
+    { cmd: "--dry-run", desc: "Preview next step without executing" },
+  ],
+  mode: [
+    { cmd: "global", desc: "Edit global workflow mode" },
+    { cmd: "project", desc: "Edit project-specific workflow mode" },
+  ],
+  parallel: [
+    { cmd: "start", desc: "Start parallel milestone orchestration" },
+    { cmd: "status", desc: "Show parallel worker statuses" },
+    { cmd: "stop", desc: "Stop all parallel workers" },
+    { cmd: "pause", desc: "Pause a specific worker" },
+    { cmd: "resume", desc: "Resume a paused worker" },
+    { cmd: "merge", desc: "Merge completed milestone branches" },
+  ],
+  setup: [
+    { cmd: "llm", desc: "Configure LLM provider settings" },
+    { cmd: "search", desc: "Configure web search provider" },
+    { cmd: "remote", desc: "Configure remote integrations" },
+    { cmd: "keys", desc: "Manage API keys" },
+    { cmd: "prefs", desc: "Configure global preferences" },
+  ],
+  logs: [
+    { cmd: "debug", desc: "List or view debug log files" },
+    { cmd: "tail", desc: "Show last N activity log summaries" },
+    { cmd: "clear", desc: "Remove old activity and debug logs" },
+  ],
+  keys: [
+    { cmd: "list", desc: "Show key status dashboard" },
+    { cmd: "add", desc: "Add a key for a provider" },
+    { cmd: "remove", desc: "Remove a key" },
+    { cmd: "test", desc: "Validate key(s) with API call" },
+    { cmd: "rotate", desc: "Replace an existing key" },
+    { cmd: "doctor", desc: "Health check all keys" },
+  ],
+  prefs: [
+    { cmd: "global", desc: "Edit global preferences file" },
+    { cmd: "project", desc: "Edit project preferences file" },
+    { cmd: "status", desc: "Show effective preferences" },
+    { cmd: "wizard", desc: "Interactive preferences wizard" },
+    { cmd: "setup", desc: "First-time preferences setup" },
+    { cmd: "import-claude", desc: "Import settings from Claude Code" },
+  ],
+  remote: [
+    { cmd: "slack", desc: "Configure Slack integration" },
+    { cmd: "discord", desc: "Configure Discord integration" },
+    { cmd: "status", desc: "Show remote connection status" },
+    { cmd: "disconnect", desc: "Disconnect remote integrations" },
+  ],
+  history: [
+    { cmd: "--cost", desc: "Show cost breakdown per entry" },
+    { cmd: "--phase", desc: "Filter by phase type" },
+    { cmd: "--model", desc: "Filter by model used" },
+    { cmd: "10", desc: "Show last 10 entries" },
+    { cmd: "20", desc: "Show last 20 entries" },
+    { cmd: "50", desc: "Show last 50 entries" },
+  ],
+  export: [
+    { cmd: "--json", desc: "Export as JSON" },
+    { cmd: "--markdown", desc: "Export as Markdown" },
+    { cmd: "--html", desc: "Export as HTML" },
+    { cmd: "--html --all", desc: "Export all milestones as HTML" },
+  ],
+  cleanup: [
+    { cmd: "branches", desc: "Remove merged milestone branches" },
+    { cmd: "snapshots", desc: "Remove old execution snapshots" },
+  ],
+  knowledge: [
+    { cmd: "rule", desc: "Add a project rule (always/never do X)" },
+    { cmd: "pattern", desc: "Add a code pattern to follow" },
+    { cmd: "lesson", desc: "Record a lesson learned" },
+  ],
+  start: [
+    { cmd: "bugfix", desc: "Triage, fix, test, and ship a bug fix" },
+    { cmd: "small-feature", desc: "Lightweight feature with optional discussion" },
+    { cmd: "spike", desc: "Research, prototype, and document findings" },
+    { cmd: "hotfix", desc: "Minimal: fix it, test it, ship it" },
+    { cmd: "refactor", desc: "Inventory, plan waves, migrate, verify" },
+    { cmd: "security-audit", desc: "Scan, triage, remediate, re-scan" },
+    { cmd: "dep-upgrade", desc: "Assess, upgrade, fix breaks, verify" },
+    { cmd: "full-project", desc: "Complete GSD workflow with full ceremony" },
+    { cmd: "resume", desc: "Resume an in-progress workflow" },
+    { cmd: "--list", desc: "List all available templates" },
+    { cmd: "--dry-run", desc: "Preview workflow without executing" },
+  ],
+  templates: [
+    { cmd: "info", desc: "Show detailed template info" },
+  ],
+  extensions: [
+    { cmd: "list", desc: "List all extensions and their status" },
+    { cmd: "enable", desc: "Enable a disabled extension" },
+    { cmd: "disable", desc: "Disable an extension" },
+    { cmd: "info", desc: "Show extension details" },
+  ],
+  doctor: [
+    { cmd: "fix", desc: "Auto-fix detected issues" },
+    { cmd: "heal", desc: "AI-driven deep healing" },
+    { cmd: "audit", desc: "Run health audit without fixing" },
+    { cmd: "--dry-run", desc: "Show what --fix would change without applying" },
+    { cmd: "--json", desc: "Output report as JSON (CI/tooling friendly)" },
+    { cmd: "--build", desc: "Include slow build health check (npm run build)" },
+    { cmd: "--test", desc: "Include slow test health check (npm test)" },
+  ],
+  dispatch: [
+    { cmd: "research", desc: "Run research phase" },
+    { cmd: "plan", desc: "Run planning phase" },
+    { cmd: "execute", desc: "Run execution phase" },
+    { cmd: "complete", desc: "Run completion phase" },
+    { cmd: "reassess", desc: "Reassess current progress" },
+    { cmd: "uat", desc: "Run user acceptance testing" },
+    { cmd: "replan", desc: "Replan the current slice" },
+  ],
+  rate: [
+    { cmd: "over", desc: "Model was overqualified for this task" },
+    { cmd: "ok", desc: "Model was appropriate for this task" },
+    { cmd: "under", desc: "Model was underqualified for this task" },
+  ],
+};
+
+function filterOptions(
+  partial: string,
+  options: readonly GsdCommandDefinition[],
+  prefix = "",
+) {
+  const normalizedPrefix = prefix ? `${prefix} ` : "";
+  return options
+    .filter((option) => option.cmd.startsWith(partial))
+    .map((option) => ({
+      value: `${normalizedPrefix}${option.cmd}`,
+      label: option.cmd,
+      description: option.desc,
+    }));
+}
+
+function getExtensionCompletions(prefix: string, action: string) {
+  try {
+    const extDir = join(gsdHome, "agent", "extensions");
+    const ids: Array<{ id: string; name: string }> = [];
+    for (const entry of readdirSync(extDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const manifestPath = join(extDir, entry.name, "extension-manifest.json");
+      if (!existsSync(manifestPath)) continue;
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        if (typeof manifest?.id === "string") {
+          ids.push({ id: manifest.id, name: manifest.name ?? manifest.id });
+        }
+      } catch {
+        // ignore malformed manifests
+      }
+    }
+    return ids
+      .filter((entry) => entry.id.startsWith(prefix))
+      .map((entry) => ({
+        value: `extensions ${action} ${entry.id}`,
+        label: entry.id,
+        description: entry.name,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export function getGsdArgumentCompletions(prefix: string) {
+  const hasTrailingSpace = prefix.endsWith(" ");
+  const parts = prefix.trim().split(/\s+/);
+  if (hasTrailingSpace && parts.length >= 1) {
+    parts.push("");
+  }
+
+  if (parts.length <= 1) {
+    return filterOptions(parts[0] ?? "", TOP_LEVEL_SUBCOMMANDS);
+  }
+
+  const [command, subcommand = "", third = ""] = parts;
+
+  if (command === "cmux") {
+    if (parts.length <= 2) {
+      return filterOptions(subcommand, [
+        { cmd: "status", desc: "Show cmux detection, prefs, and capabilities" },
+        { cmd: "on", desc: "Enable cmux integration" },
+        { cmd: "off", desc: "Disable cmux integration" },
+        { cmd: "notifications", desc: "Toggle cmux desktop notifications" },
+        { cmd: "sidebar", desc: "Toggle cmux sidebar metadata" },
+        { cmd: "splits", desc: "Toggle cmux visual subagent splits" },
+        { cmd: "browser", desc: "Toggle future browser integration flag" },
+      ], "cmux");
+    }
+    if (parts.length <= 3 && ["notifications", "sidebar", "splits", "browser"].includes(subcommand)) {
+      return filterOptions(third, [
+        { cmd: "on", desc: "Enable this cmux area" },
+        { cmd: "off", desc: "Disable this cmux area" },
+      ], `cmux ${subcommand}`);
+    }
+    return [];
+  }
+
+  if (command === "templates" && subcommand === "info" && parts.length <= 3) {
+    try {
+      const registry = loadRegistry();
+      return Object.entries(registry.templates)
+        .filter(([id]) => id.startsWith(third))
+        .map(([id, entry]) => ({
+          value: `templates info ${id}`,
+          label: id,
+          description: entry.description,
+        }));
+    } catch {
+      return [];
+    }
+  }
+
+  if (command === "extensions" && parts.length === 3 && ["enable", "disable", "info"].includes(subcommand)) {
+    return getExtensionCompletions(third, subcommand);
+  }
+
+  if (command === "undo" && parts.length <= 2) {
+    return [{ value: "undo --force", label: "--force", description: "Skip confirmation prompt" }];
+  }
+
+  const nested = NESTED_COMPLETIONS[command];
+  if (nested && parts.length <= 2) {
+    return filterOptions(subcommand, nested, command);
+  }
+
+  return [];
+}
diff --git a/src/resources/extensions/gsd/commands/context.ts b/src/resources/extensions/gsd/commands/context.ts
new file mode 100644
index 000000000..b8c95e608
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/context.ts
@@ -0,0 +1,101 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
+import { assertSafeDirectory } from "../validate-directory.js";
+import { resolveProjectRoot } from "../worktree.js";
+import { showNextAction } from "../../shared/mod.js";
+import { handleStatus } from "./handlers/core.js";
+
+export interface GsdDispatchContext {
+  ctx: ExtensionCommandContext;
+  pi: ExtensionAPI;
+  trimmed: string;
+}
+
+export function projectRoot(): string {
+  const cwd = process.cwd();
+  const root = resolveProjectRoot(cwd);
+  if (root !== cwd) {
+    assertSafeDirectory(cwd);
+  } else {
+    assertSafeDirectory(root);
+  }
+  return root;
+}
+
+export async function guardRemoteSession(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  if (isAutoActive() || isAutoPaused()) return true;
+
+  const remote = checkRemoteAutoSession(projectRoot());
+  if (!remote.running || !remote.pid) return true;
+
+  const unitLabel = remote.unitType && remote.unitId
+    ? `${remote.unitType} (${remote.unitId})`
+    : "unknown unit";
+  const unitsMsg = remote.completedUnits != null
+    ? `${remote.completedUnits} units completed`
+    : "";
+
+  const choice = await showNextAction(ctx, {
+    title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
+    summary: [
+      `Currently executing: ${unitLabel}`,
+      ...(unitsMsg ? [unitsMsg] : []),
+      ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
+    ],
+    actions: [
+      {
+        id: "status",
+        label: "View status",
+        description: "Show the current GSD progress dashboard.",
+        recommended: true,
+      },
+      {
+        id: "steer",
+        label: "Steer the session",
+        description: "Use /gsd steer <instruction> to redirect the running session.",
+      },
+      {
+        id: "stop",
+        label: "Stop remote session",
+        description: `Send SIGTERM to PID ${remote.pid} to stop it gracefully.`,
+      },
+      {
+        id: "force",
+        label: "Force start (steal lock)",
+        description: "Start a new session, terminating the existing one.",
+      },
+    ],
+    notYetMessage: "Run /gsd when ready.",
+  });
+
+  if (choice === "status") {
+    await handleStatus(ctx);
+    return false;
+  }
+  if (choice === "steer") {
+    ctx.ui.notify(
+      "Use /gsd steer <instruction> to redirect the running auto-mode session.\n" +
+      "Example: /gsd steer Use Postgres instead of SQLite",
+      "info",
+    );
+    return false;
+  }
+  if (choice === "stop") {
+    const result = stopAutoRemote(projectRoot());
+    if (result.found) {
+      ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+    } else if (result.error) {
+      ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+    } else {
+      ctx.ui.notify("Remote session is no longer running.", "info");
+    }
+    return false;
+  }
+
+  return choice === "force";
+}
+
diff --git a/src/resources/extensions/gsd/commands/dispatcher.ts b/src/resources/extensions/gsd/commands/dispatcher.ts
new file mode 100644
index 000000000..9f28cbbaa
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/dispatcher.ts
@@ -0,0 +1,32 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { handleAutoCommand } from "./handlers/auto.js";
+import { handleCoreCommand } from "./handlers/core.js";
+import { handleOpsCommand } from "./handlers/ops.js";
+import { handleParallelCommand } from "./handlers/parallel.js";
+import { handleWorkflowCommand } from "./handlers/workflow.js";
+
+export async function handleGSDCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const trimmed = (typeof args === "string" ? args : "").trim();
+
+  const handlers = [
+    () => handleCoreCommand(trimmed, ctx),
+    () => handleAutoCommand(trimmed, ctx, pi),
+    () => handleParallelCommand(trimmed, ctx, pi),
+    () => handleWorkflowCommand(trimmed, ctx, pi),
+    () => handleOpsCommand(trimmed, ctx, pi),
+  ];
+
+  for (const handler of handlers) {
+    if (await handler()) {
+      return;
+    }
+  }
+
+  ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
+}
+
diff --git a/src/resources/extensions/gsd/commands/handlers/auto.ts b/src/resources/extensions/gsd/commands/handlers/auto.ts
new file mode 100644
index 000000000..b261d8a34
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/handlers/auto.ts
@@ -0,0 +1,74 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { enableDebug } from "../../debug-logger.js";
+import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAuto, stopAuto, stopAutoRemote } from "../../auto.js";
+import { handleRate } from "../../commands-rate.js";
+import { guardRemoteSession, projectRoot } from "../context.js";
+
+export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  if (trimmed === "next" || trimmed.startsWith("next ")) {
+    if (trimmed.includes("--dry-run")) {
+      const { handleDryRun } = await import("../../commands-maintenance.js");
+      await handleDryRun(ctx, projectRoot());
+      return true;
+    }
+    const verboseMode = trimmed.includes("--verbose");
+    const debugMode = trimmed.includes("--debug");
+    if (debugMode) enableDebug(projectRoot());
+    if (!(await guardRemoteSession(ctx, pi))) return true;
+    await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
+    return true;
+  }
+
+  if (trimmed === "auto" || trimmed.startsWith("auto ")) {
+    const verboseMode = trimmed.includes("--verbose");
+    const debugMode = trimmed.includes("--debug");
+    if (debugMode) enableDebug(projectRoot());
+    if (!(await guardRemoteSession(ctx, pi))) return true;
+    await startAuto(ctx, pi, projectRoot(), verboseMode);
+    return true;
+  }
+
+  if (trimmed === "stop") {
+    if (!isAutoActive() && !isAutoPaused()) {
+      const result = stopAutoRemote(projectRoot());
+      if (result.found) {
+        ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+      } else if (result.error) {
+        ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+      } else {
+        ctx.ui.notify("Auto-mode is not running.", "info");
+      }
+      return true;
+    }
+    await stopAuto(ctx, pi, "User requested stop");
+    return true;
+  }
+
+  if (trimmed === "pause") {
+    if (!isAutoActive()) {
+      if (isAutoPaused()) {
+        ctx.ui.notify("Auto-mode is already paused. /gsd auto to resume.", "info");
+      } else {
+        ctx.ui.notify("Auto-mode is not running.", "info");
+      }
+      return true;
+    }
+    await pauseAuto(ctx, pi);
+    return true;
+  }
+
+  if (trimmed === "rate" || trimmed.startsWith("rate ")) {
+    await handleRate(trimmed.replace(/^rate\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
+
+  if (trimmed === "") {
+    if (!(await guardRemoteSession(ctx, pi))) return true;
+    await startAuto(ctx, pi, projectRoot(), false, { step: true });
+    return true;
+  }
+
+  return false;
+}
+
diff --git a/src/resources/extensions/gsd/commands/handlers/core.ts b/src/resources/extensions/gsd/commands/handlers/core.ts
new file mode 100644
index 000000000..3f759daf9
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/handlers/core.ts
@@ -0,0 +1,274 @@
+import type { ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { GSDState } from "../../types.js";
+
+import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
+import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
+import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard } from "../../commands-prefs-wizard.js";
+import { runEnvironmentChecks } from "../../doctor-environment.js";
+import { deriveState } from "../../state.js";
+import { handleCmux } from "../../commands-cmux.js";
+import { projectRoot } from "../context.js";
+
+export function showHelp(ctx: ExtensionCommandContext): void {
+  const lines = [
+    "GSD — Get Shit Done\n",
+    "WORKFLOW",
+    "  /gsd start <tpl>   Start a workflow template (bugfix, spike, feature, hotfix, etc.)",
+    "  /gsd templates     List available workflow templates  [info <name>]",
+    "  /gsd               Run next unit in step mode (same as /gsd next)",
+    "  /gsd next           Execute next task, then pause  [--dry-run] [--verbose]",
+    "  /gsd auto           Run all queued units continuously  [--verbose]",
+    "  /gsd stop           Stop auto-mode gracefully",
+    "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
+    "  /gsd discuss        Start guided milestone/slice discussion",
+    "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
+    "",
+    "VISIBILITY",
+    "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",
+    "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
+    "  /gsd queue          Show queued/dispatched units and execution order",
+    "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
+    "  /gsd changelog      Show categorized release notes  [version]",
+    "",
+    "COURSE CORRECTION",
+    "  /gsd steer <desc>   Apply user override to active work",
+    "  /gsd capture <text> Quick-capture a thought to CAPTURES.md",
+    "  /gsd triage         Classify and route pending captures",
+    "  /gsd skip <unit>    Prevent a unit from auto-mode dispatch",
+    "  /gsd undo           Revert last completed unit  [--force]",
+    "  /gsd park [id]      Park a milestone — skip without deleting  [reason]",
+    "  /gsd unpark [id]    Reactivate a parked milestone",
+    "",
+    "PROJECT KNOWLEDGE",
+    "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "",
+    "SETUP & CONFIGURATION",
+    "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
+    "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
+    "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
+    "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
+    "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
+    "  /gsd config         Set API keys for external tools",
+    "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
+    "  /gsd hooks          Show post-unit hook configuration",
+    "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
+    "",
+    "MAINTENANCE",
+    "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
+    "  /gsd export         Export milestone/slice results  [--json|--markdown|--html] [--all]",
+    "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
+    "  /gsd migrate        Migrate .planning/ (v1) to .gsd/ (v2) format",
+    "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
+    "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
+    "  /gsd update         Update GSD to the latest version via npm",
+  ];
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+export async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const state = await deriveState(basePath);
+
+  if (state.registry.length === 0) {
+    ctx.ui.notify("No GSD milestones found. Run /gsd to start.", "info");
+    return;
+  }
+
+  const { GSDDashboardOverlay } = await import("../../dashboard-overlay.js");
+  const result = await ctx.ui.custom<void>(
+    (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done()),
+    {
+      overlay: true,
+      overlayOptions: {
+        width: "70%",
+        minWidth: 60,
+        maxHeight: "90%",
+        anchor: "center",
+      },
+    },
+  );
+
+  if (result === undefined) {
+    ctx.ui.notify(formatTextStatus(state), "info");
+  }
+}
+
+export async function fireStatusViaCommand(ctx: ExtensionContext): Promise<void> {
+  await handleStatus(ctx as ExtensionCommandContext);
+}
+
+export async function handleVisualize(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Visualizer requires an interactive terminal.", "warning");
+    return;
+  }
+
+  const { GSDVisualizerOverlay } = await import("../../visualizer-overlay.js");
+  const result = await ctx.ui.custom<void>(
+    (tui, theme, _kb, done) => new GSDVisualizerOverlay(tui, theme, () => done()),
+    {
+      overlay: true,
+      overlayOptions: {
+        width: "80%",
+        minWidth: 80,
+        maxHeight: "90%",
+        anchor: "center",
+      },
+    },
+  );
+
+  if (result === undefined) {
+    ctx.ui.notify("Visualizer requires an interactive terminal. Use /gsd status for a text-based overview.", "warning");
+  }
+}
+
+export async function handleSetup(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
+
+  const globalConfigured = hasGlobalSetup();
+  const detection = detectProjectState(projectRoot());
+
+  const statusLines = ["GSD Setup Status\n"];
+  statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
+  statusLines.push(`  Project state: ${detection.state}`);
+  if (detection.projectSignals.primaryLanguage) {
+    statusLines.push(`  Detected: ${detection.projectSignals.primaryLanguage}`);
+  }
+
+  if (args === "llm" || args === "auth") {
+    ctx.ui.notify("Use /login to configure LLM authentication.", "info");
+    return;
+  }
+  if (args === "search") {
+    ctx.ui.notify("Use /search-provider to configure web search.", "info");
+    return;
+  }
+  if (args === "remote") {
+    ctx.ui.notify("Use /gsd remote to configure remote questions.", "info");
+    return;
+  }
+  if (args === "keys") {
+    const { handleKeys } = await import("../../key-manager.js");
+    await handleKeys("", ctx);
+    return;
+  }
+  if (args === "prefs") {
+    await ensurePreferencesFile(getGlobalGSDPreferencesPath(), ctx, "global");
+    await handlePrefsWizard(ctx, "global");
+    return;
+  }
+
+  ctx.ui.notify(statusLines.join("\n"), "info");
+  ctx.ui.notify(
+    "Available setup commands:\n" +
+    "  /gsd setup llm     — LLM authentication\n" +
+    "  /gsd setup search  — Web search provider\n" +
+    "  /gsd setup remote  — Remote questions (Discord/Slack/Telegram)\n" +
+    "  /gsd setup keys    — Tool API keys\n" +
+    "  /gsd setup prefs   — Global preferences wizard",
+    "info",
+  );
+}
+
+export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandContext): Promise<boolean> {
+  if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
+    showHelp(ctx);
+    return true;
+  }
+  if (trimmed === "status") {
+    await handleStatus(ctx);
+    return true;
+  }
+  if (trimmed === "visualize") {
+    await handleVisualize(ctx);
+    return true;
+  }
+  if (trimmed === "widget" || trimmed.startsWith("widget ")) {
+    const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await import("../../auto-dashboard.js");
+    const arg = trimmed.replace(/^widget\s*/, "").trim();
+    if (arg === "full" || arg === "small" || arg === "min" || arg === "off") {
+      setWidgetMode(arg);
+    } else {
+      cycleWidgetMode();
+    }
+    ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
+    return true;
+  }
+  if (trimmed === "mode" || trimmed.startsWith("mode ")) {
+    const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
+    const scope = modeArgs === "project" ? "project" : "global";
+    const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+    await ensurePreferencesFile(path, ctx, scope);
+    await handlePrefsMode(ctx, scope);
+    return true;
+  }
+  if (trimmed === "prefs" || trimmed.startsWith("prefs ")) {
+    await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
+    await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "setup" || trimmed.startsWith("setup ")) {
+    await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx);
+    return true;
+  }
+  return false;
+}
+
+export function formatTextStatus(state: GSDState): string {
+  const lines: string[] = ["GSD Status\n"];
+  lines.push(formatProgressLine(computeProgressScore()));
+  lines.push("");
+  lines.push(`Phase: ${state.phase}`);
+
+  if (state.activeMilestone) {
+    lines.push(`Active milestone: ${state.activeMilestone.id} — ${state.activeMilestone.title}`);
+  }
+  if (state.activeSlice) {
+    lines.push(`Active slice: ${state.activeSlice.id} — ${state.activeSlice.title}`);
+  }
+  if (state.activeTask) {
+    lines.push(`Active task: ${state.activeTask.id} — ${state.activeTask.title}`);
+  }
+  if (state.progress) {
+    const { milestones, slices, tasks } = state.progress;
+    const parts: string[] = [`milestones ${milestones.done}/${milestones.total}`];
+    if (slices) parts.push(`slices ${slices.done}/${slices.total}`);
+    if (tasks) parts.push(`tasks ${tasks.done}/${tasks.total}`);
+    lines.push(`Progress: ${parts.join(", ")}`);
+  }
+  if (state.nextAction) {
+    lines.push(`Next: ${state.nextAction}`);
+  }
+  if (state.blockers.length > 0) {
+    lines.push(`Blockers: ${state.blockers.join("; ")}`);
+  }
+  if (state.registry.length > 0) {
+    lines.push("");
+    lines.push("Milestones:");
+    for (const milestone of state.registry) {
+      const icon = milestone.status === "complete"
+        ? "✓"
+        : milestone.status === "active"
+          ? "▶"
+          : milestone.status === "parked"
+            ? "⏸"
+            : "○";
+      lines.push(`  ${icon} ${milestone.id}: ${milestone.title} (${milestone.status})`);
+    }
+  }
+
+  const envResults = runEnvironmentChecks(projectRoot());
+  const envIssues = envResults.filter((result) => result.status !== "ok");
+  if (envIssues.length > 0) {
+    lines.push("");
+    lines.push("Environment:");
+    for (const issue of envIssues) {
+      lines.push(`  ${issue.status === "error" ? "✗" : "⚠"} ${issue.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
diff --git a/src/resources/extensions/gsd/commands/handlers/ops.ts b/src/resources/extensions/gsd/commands/handlers/ops.ts
new file mode 100644
index 000000000..c28574196
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/handlers/ops.ts
@@ -0,0 +1,169 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { enableDebug } from "../../debug-logger.js";
+import { dispatchDirectPhase } from "../../auto-direct-dispatch.js";
+import { handleConfig } from "../../commands-config.js";
+import { handleDoctor, handleCapture, handleKnowledge, handleRunHook, handleSkillHealth, handleSteer, handleTriage, handleUpdate } from "../../commands-handlers.js";
+import { handleInspect } from "../../commands-inspect.js";
+import { handleLogs } from "../../commands-logs.js";
+import { handleCleanupBranches, handleCleanupSnapshots, handleSkip } from "../../commands-maintenance.js";
+import { handleExport } from "../../export.js";
+import { handleHistory } from "../../history.js";
+import { handleUndo } from "../../undo.js";
+import { handleRemote } from "../../../remote-questions/mod.js";
+import { projectRoot } from "../context.js";
+
+export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  if (trimmed === "init") {
+    const { detectProjectState } = await import("../../detection.js");
+    const { handleReinit, showProjectInit } = await import("../../init-wizard.js");
+    const basePath = projectRoot();
+    const detection = detectProjectState(basePath);
+    if (detection.state === "v2-gsd" || detection.state === "v2-gsd-empty") {
+      await handleReinit(ctx, detection);
+    } else {
+      await showProjectInit(ctx, pi, basePath, detection);
+    }
+    return true;
+  }
+  if (trimmed === "keys" || trimmed.startsWith("keys ")) {
+    const { handleKeys } = await import("../../key-manager.js");
+    await handleKeys(trimmed.replace(/^keys\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "doctor" || trimmed.startsWith("doctor ")) {
+    await handleDoctor(trimmed.replace(/^doctor\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "logs" || trimmed.startsWith("logs ")) {
+    await handleLogs(trimmed.replace(/^logs\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "forensics" || trimmed.startsWith("forensics ")) {
+    const { handleForensics } = await import("../../forensics.js");
+    await handleForensics(trimmed.replace(/^forensics\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "changelog" || trimmed.startsWith("changelog ")) {
+    const { handleChangelog } = await import("../../changelog.js");
+    await handleChangelog(trimmed.replace(/^changelog\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "history" || trimmed.startsWith("history ")) {
+    await handleHistory(trimmed.replace(/^history\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
+  if (trimmed === "undo" || trimmed.startsWith("undo ")) {
+    await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
+    return true;
+  }
+  if (trimmed.startsWith("skip ")) {
+    await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
+  if (trimmed === "export" || trimmed.startsWith("export ")) {
+    await handleExport(trimmed.replace(/^export\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
+  if (trimmed === "cleanup") {
+    await handleCleanupBranches(ctx, projectRoot());
+    await handleCleanupSnapshots(ctx, projectRoot());
+    return true;
+  }
+  if (trimmed === "cleanup branches") {
+    await handleCleanupBranches(ctx, projectRoot());
+    return true;
+  }
+  if (trimmed === "cleanup snapshots") {
+    await handleCleanupSnapshots(ctx, projectRoot());
+    return true;
+  }
+  if (trimmed.startsWith("capture ") || trimmed === "capture") {
+    await handleCapture(trimmed.replace(/^capture\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "triage") {
+    await handleTriage(ctx, pi, process.cwd());
+    return true;
+  }
+  if (trimmed === "config") {
+    await handleConfig(ctx);
+    return true;
+  }
+  if (trimmed === "hooks") {
+    const { formatHookStatus } = await import("../../post-unit-hooks.js");
+    ctx.ui.notify(formatHookStatus(), "info");
+    return true;
+  }
+  if (trimmed === "skill-health" || trimmed.startsWith("skill-health ")) {
+    await handleSkillHealth(trimmed.replace(/^skill-health\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed.startsWith("run-hook ")) {
+    await handleRunHook(trimmed.replace(/^run-hook\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "run-hook") {
+    ctx.ui.notify(`Usage: /gsd run-hook <hook-name> <unit-type> <unit-id>
+
+Unit types:
+  execute-task   - Task execution (unit-id: M001/S01/T01)
+  plan-slice     - Slice planning (unit-id: M001/S01)
+  research-milestone - Milestone research (unit-id: M001)
+  complete-slice - Slice completion (unit-id: M001/S01)
+  complete-milestone - Milestone completion (unit-id: M001)
+
+Examples:
+  /gsd run-hook code-review execute-task M001/S01/T01
+  /gsd run-hook lint-check plan-slice M001/S01`, "warning");
+    return true;
+  }
+  if (trimmed.startsWith("steer ")) {
+    await handleSteer(trimmed.replace(/^steer\s+/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "steer") {
+    ctx.ui.notify("Usage: /gsd steer <description of change>. Example: /gsd steer Use Postgres instead of SQLite", "warning");
+    return true;
+  }
+  if (trimmed.startsWith("knowledge ")) {
+    await handleKnowledge(trimmed.replace(/^knowledge\s+/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "knowledge") {
+    ctx.ui.notify("Usage: /gsd knowledge <rule|pattern|lesson> <description>. Example: /gsd knowledge rule Use real DB for integration tests", "warning");
+    return true;
+  }
+  if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
+    const { handleMigrate } = await import("../../migrate/command.js");
+    await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "remote" || trimmed.startsWith("remote ")) {
+    await handleRemote(trimmed.replace(/^remote\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "dispatch" || trimmed.startsWith("dispatch ")) {
+    const phase = trimmed.replace(/^dispatch\s*/, "").trim();
+    if (!phase) {
+      ctx.ui.notify("Usage: /gsd dispatch <phase>  (research|plan|execute|complete|reassess|uat|replan)", "warning");
+      return true;
+    }
+    await dispatchDirectPhase(ctx, pi, phase, projectRoot());
+    return true;
+  }
+  if (trimmed === "inspect") {
+    await handleInspect(ctx);
+    return true;
+  }
+  if (trimmed === "update") {
+    await handleUpdate(ctx);
+    return true;
+  }
+  if (trimmed === "extensions" || trimmed.startsWith("extensions ")) {
+    const { handleExtensions } = await import("../../commands-extensions.js");
+    await handleExtensions(trimmed.replace(/^extensions\s*/, "").trim(), ctx);
+    return true;
+  }
+  return false;
+}
diff --git a/src/resources/extensions/gsd/commands/handlers/parallel.ts b/src/resources/extensions/gsd/commands/handlers/parallel.ts
new file mode 100644
index 000000000..0aa27c385
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/handlers/parallel.ts
@@ -0,0 +1,118 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import {
+  getOrchestratorState,
+  getWorkerStatuses,
+  isParallelActive,
+  pauseWorker,
+  prepareParallelStart,
+  resumeWorker,
+  startParallel,
+  stopParallel,
+} from "../../parallel-orchestrator.js";
+import { formatEligibilityReport } from "../../parallel-eligibility.js";
+import { formatMergeResults, mergeAllCompleted, mergeCompletedMilestone } from "../../parallel-merge.js";
+import { loadEffectiveGSDPreferences, resolveParallelConfig } from "../../preferences.js";
+import { projectRoot } from "../context.js";
+
+export async function handleParallelCommand(trimmed: string, _ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  if (!trimmed.startsWith("parallel")) return false;
+
+  const parallelArgs = trimmed.slice("parallel".length).trim();
+  const [subcommand = "", ...restParts] = parallelArgs.split(/\s+/);
+  const rest = restParts.join(" ");
+
+  if (subcommand === "start" || subcommand === "") {
+    const loaded = loadEffectiveGSDPreferences();
+    const config = resolveParallelConfig(loaded?.preferences);
+    if (!config.enabled) {
+      pi.sendMessage({
+        customType: "gsd-parallel",
+        content: "Parallel mode is not enabled. Set `parallel.enabled: true` in your preferences.",
+        display: false,
+      });
+      return true;
+    }
+    const candidates = await prepareParallelStart(projectRoot(), loaded?.preferences);
+    const report = formatEligibilityReport(candidates);
+    if (candidates.eligible.length === 0) {
+      pi.sendMessage({ customType: "gsd-parallel", content: `${report}\n\nNo milestones are eligible for parallel execution.`, display: false });
+      return true;
+    }
+    const result = await startParallel(
+      projectRoot(),
+      candidates.eligible.map((candidate) => candidate.milestoneId),
+      loaded?.preferences,
+    );
+    const lines = ["Parallel orchestration started.", `Workers: ${result.started.join(", ")}`];
+    if (result.errors.length > 0) {
+      lines.push(`Errors: ${result.errors.map((entry) => `${entry.mid}: ${entry.error}`).join("; ")}`);
+    }
+    pi.sendMessage({ customType: "gsd-parallel", content: `${report}\n\n${lines.join("\n")}`, display: false });
+    return true;
+  }
+
+  if (subcommand === "status") {
+    if (!isParallelActive()) {
+      pi.sendMessage({ customType: "gsd-parallel", content: "No parallel orchestration is currently active.", display: false });
+      return true;
+    }
+    const workers = getWorkerStatuses();
+    const lines = ["# Parallel Workers\n"];
+    for (const worker of workers) {
+      lines.push(`- **${worker.milestoneId}** (${worker.title}) — ${worker.state} — ${worker.completedUnits} units — $${worker.cost.toFixed(2)}`);
+    }
+    const state = getOrchestratorState();
+    if (state) {
+      lines.push(`\nTotal cost: $${state.totalCost.toFixed(2)}`);
+    }
+    pi.sendMessage({ customType: "gsd-parallel", content: lines.join("\n"), display: false });
+    return true;
+  }
+
+  if (subcommand === "stop") {
+    const milestoneId = rest.trim() || undefined;
+    await stopParallel(projectRoot(), milestoneId);
+    pi.sendMessage({ customType: "gsd-parallel", content: milestoneId ? `Stopped worker for ${milestoneId}.` : "All parallel workers stopped.", display: false });
+    return true;
+  }
+
+  if (subcommand === "pause") {
+    const milestoneId = rest.trim() || undefined;
+    pauseWorker(projectRoot(), milestoneId);
+    pi.sendMessage({ customType: "gsd-parallel", content: milestoneId ? `Paused worker for ${milestoneId}.` : "All parallel workers paused.", display: false });
+    return true;
+  }
+
+  if (subcommand === "resume") {
+    const milestoneId = rest.trim() || undefined;
+    resumeWorker(projectRoot(), milestoneId);
+    pi.sendMessage({ customType: "gsd-parallel", content: milestoneId ? `Resumed worker for ${milestoneId}.` : "All parallel workers resumed.", display: false });
+    return true;
+  }
+
+  if (subcommand === "merge") {
+    const milestoneId = rest.trim() || undefined;
+    if (milestoneId) {
+      const result = await mergeCompletedMilestone(projectRoot(), milestoneId);
+      pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults([result]), display: false });
+      return true;
+    }
+    const workers = getWorkerStatuses();
+    if (workers.length === 0) {
+      pi.sendMessage({ customType: "gsd-parallel", content: "No parallel workers to merge.", display: false });
+      return true;
+    }
+    const results = await mergeAllCompleted(projectRoot(), workers);
+    pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults(results), display: false });
+    return true;
+  }
+
+  pi.sendMessage({
+    customType: "gsd-parallel",
+    content: `Unknown parallel subcommand "${subcommand}". Usage: /gsd parallel [start|status|stop|pause|resume|merge]`,
+    display: false,
+  });
+  return true;
+}
+
diff --git a/src/resources/extensions/gsd/commands/handlers/workflow.ts b/src/resources/extensions/gsd/commands/handlers/workflow.ts
new file mode 100644
index 000000000..a74bc3f07
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/handlers/workflow.ts
@@ -0,0 +1,109 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { handleQuick } from "../../quick.js";
+import { showDiscuss, showHeadlessMilestoneCreation, showQueue } from "../../guided-flow.js";
+import { handleStart, handleTemplates } from "../../commands-workflow-templates.js";
+import { gsdRoot } from "../../paths.js";
+import { deriveState } from "../../state.js";
+import { isParked, parkMilestone, unparkMilestone } from "../../milestone-actions.js";
+import { loadEffectiveGSDPreferences } from "../../preferences.js";
+import { nextMilestoneId } from "../../milestone-ids.js";
+import { findMilestoneIds } from "../../guided-flow.js";
+import { projectRoot } from "../context.js";
+
+export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  if (trimmed === "queue") {
+    await showQueue(ctx, pi, projectRoot());
+    return true;
+  }
+  if (trimmed === "discuss") {
+    await showDiscuss(ctx, pi, projectRoot());
+    return true;
+  }
+  if (trimmed === "quick" || trimmed.startsWith("quick ")) {
+    await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "new-milestone") {
+    const basePath = projectRoot();
+    const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
+    if (existsSync(headlessContextPath)) {
+      const seedContext = readFileSync(headlessContextPath, "utf-8");
+      try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }
+      await showHeadlessMilestoneCreation(ctx, pi, basePath, seedContext);
+    } else {
+      const { showSmartEntry } = await import("../../guided-flow.js");
+      await showSmartEntry(ctx, pi, basePath);
+    }
+    return true;
+  }
+  if (trimmed === "start" || trimmed.startsWith("start ")) {
+    await handleStart(trimmed.replace(/^start\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "templates" || trimmed.startsWith("templates ")) {
+    await handleTemplates(trimmed.replace(/^templates\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "park" || trimmed.startsWith("park ")) {
+    const basePath = projectRoot();
+    const arg = trimmed.replace(/^park\s*/, "").trim();
+    let targetId = arg;
+    if (!targetId) {
+      const state = await deriveState(basePath);
+      if (!state.activeMilestone) {
+        ctx.ui.notify("No active milestone to park.", "warning");
+        return true;
+      }
+      targetId = state.activeMilestone.id;
+    }
+    if (isParked(basePath, targetId)) {
+      ctx.ui.notify(`${targetId} is already parked. Use /gsd unpark ${targetId} to reactivate.`, "info");
+      return true;
+    }
+    const reasonParts = arg.replace(targetId, "").trim().replace(/^["']|["']$/g, "");
+    const reason = reasonParts || "Parked via /gsd park";
+    const success = parkMilestone(basePath, targetId, reason);
+    ctx.ui.notify(
+      success ? `Parked ${targetId}. Run /gsd unpark ${targetId} to reactivate.` : `Could not park ${targetId} — milestone not found.`,
+      success ? "info" : "warning",
+    );
+    return true;
+  }
+  if (trimmed === "unpark" || trimmed.startsWith("unpark ")) {
+    const basePath = projectRoot();
+    const arg = trimmed.replace(/^unpark\s*/, "").trim();
+    let targetId = arg;
+    if (!targetId) {
+      const state = await deriveState(basePath);
+      const parkedEntries = state.registry.filter((entry) => entry.status === "parked");
+      if (parkedEntries.length === 0) {
+        ctx.ui.notify("No parked milestones.", "info");
+        return true;
+      }
+      if (parkedEntries.length === 1) {
+        targetId = parkedEntries[0].id;
+      } else {
+        ctx.ui.notify(`Parked milestones: ${parkedEntries.map((entry) => entry.id).join(", ")}. Specify which to unpark: /gsd unpark <id>`, "info");
+        return true;
+      }
+    }
+    const success = unparkMilestone(basePath, targetId);
+    ctx.ui.notify(
+      success ? `Unparked ${targetId}. It will resume its normal position in the queue.` : `Could not unpark ${targetId} — milestone not found or not parked.`,
+      success ? "info" : "warning",
+    );
+    return true;
+  }
+  return false;
+}
+
+export function getNextMilestoneId(basePath: string): string {
+  const milestoneIds = findMilestoneIds(basePath);
+  const uniqueIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
+  return nextMilestoneId(milestoneIds, uniqueIds);
+}
+
diff --git a/src/resources/extensions/gsd/commands/index.ts b/src/resources/extensions/gsd/commands/index.ts
new file mode 100644
index 000000000..38f55e0bb
--- /dev/null
+++ b/src/resources/extensions/gsd/commands/index.ts
@@ -0,0 +1,14 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { GSD_COMMAND_DESCRIPTION, getGsdArgumentCompletions } from "./catalog.js";
+
+export function registerGSDCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("gsd", {
+    description: GSD_COMMAND_DESCRIPTION,
+    getArgumentCompletions: getGsdArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const { handleGSDCommand } = await import("./dispatcher.js");
+      await handleGSDCommand(args, ctx, pi);
+    },
+  });
+}
diff --git a/src/resources/extensions/gsd/dashboard-overlay.ts b/src/resources/extensions/gsd/dashboard-overlay.ts
index 9c4ca6bdb..337899c4d 100644
--- a/src/resources/extensions/gsd/dashboard-overlay.ts
+++ b/src/resources/extensions/gsd/dashboard-overlay.ts
@@ -320,6 +320,16 @@ export class GSDDashboardOverlay {
         : progressScore.level === "yellow" ? th.fg("warning", "●")
           : th.fg("error", "●");
       lines.push(row(`${progressIcon} ${th.fg("text", progressScore.summary)}`));
+
+      // Show signal details when degraded — real-time visibility into what doctor found
+      if (progressScore.level !== "green" && progressScore.signals.length > 0) {
+        for (const signal of progressScore.signals) {
+          const prefix = signal.kind === "positive" ? th.fg("success", "  ✓")
+            : signal.kind === "negative" ? th.fg("error", "  ✗")
+              : th.fg("dim", "  ·");
+          lines.push(row(`${prefix} ${th.fg("dim", signal.label)}`));
+        }
+      }
     }
     lines.push(blank());
 
diff --git a/src/resources/extensions/gsd/doctor-proactive.ts b/src/resources/extensions/gsd/doctor-proactive.ts
index f4202afc6..2e30e090a 100644
--- a/src/resources/extensions/gsd/doctor-proactive.ts
+++ b/src/resources/extensions/gsd/doctor-proactive.ts
@@ -26,12 +26,26 @@ import { nativeBranchExists, nativeIsRepo } from "./native-git-bridge.js";
 
 // ── Health Score Tracking ──────────────────────────────────────────────────
 
+/** Compact issue detail stored per snapshot for real-time visibility. */
+export interface HealthIssueDetail {
+  code: string;
+  message: string;
+  severity: "error" | "warning" | "info";
+  unitId: string;
+}
+
 export interface HealthSnapshot {
   timestamp: number;
   errors: number;
   warnings: number;
   fixesApplied: number;
   unitIndex: number; // which unit dispatch triggered this snapshot
+  /** Top issues from the doctor run that produced this snapshot. */
+  issues: HealthIssueDetail[];
+  /** Fixes that were auto-applied during this snapshot's doctor run. */
+  fixes: string[];
+  /** Milestone/slice scope this snapshot belongs to (e.g. "M001" or "M001/S02"). */
+  scope?: string;
 }
 
 /** In-memory health history for the current auto-mode session. */
@@ -43,11 +57,33 @@ let consecutiveErrorUnits = 0;
 /** Unit index counter for health tracking. */
 let healthUnitIndex = 0;
 
+/** Previous progress level for state transition detection. */
+let previousProgressLevel: "green" | "yellow" | "red" = "green";
+
+/** Callback for state transition notifications. Set by auto-mode. */
+let onLevelChange: ((from: string, to: string, summary: string) => void) | null = null;
+
+/**
+ * Register a callback for progress level transitions (green→yellow, yellow→red, etc.).
+ * Called once when auto-mode starts. Pass null to unregister.
+ */
+export function setLevelChangeCallback(cb: ((from: string, to: string, summary: string) => void) | null): void {
+  onLevelChange = cb;
+  previousProgressLevel = "green";
+}
+
 /**
  * Record a health snapshot after a doctor run.
- * Called from the post-unit hook in auto.ts.
+ * Called from the post-unit hook in auto-post-unit.ts.
  */
-export function recordHealthSnapshot(errors: number, warnings: number, fixesApplied: number): void {
+export function recordHealthSnapshot(
+  errors: number,
+  warnings: number,
+  fixesApplied: number,
+  issues?: HealthIssueDetail[],
+  fixes?: string[],
+  scope?: string,
+): void {
   healthUnitIndex++;
   healthHistory.push({
     timestamp: Date.now(),
@@ -55,6 +91,9 @@ export function recordHealthSnapshot(errors: number, warnings: number, fixesAppl
     warnings,
     fixesApplied,
     unitIndex: healthUnitIndex,
+    issues: issues ?? [],
+    fixes: fixes ?? [],
+    scope,
   });
 
   // Keep only the last 50 snapshots to bound memory
@@ -67,6 +106,19 @@ export function recordHealthSnapshot(errors: number, warnings: number, fixesAppl
   } else {
     consecutiveErrorUnits = 0;
   }
+
+  // Detect progress level transitions and notify
+  if (onLevelChange) {
+    const newLevel = consecutiveErrorUnits >= 3 ? "red"
+      : consecutiveErrorUnits >= 1 || getHealthTrend() === "degrading" ? "yellow"
+        : "green";
+    if (newLevel !== previousProgressLevel) {
+      const topIssue = (issues ?? []).find(i => i.severity === "error") ?? (issues ?? [])[0];
+      const detail = topIssue ? `: ${topIssue.message}` : "";
+      onLevelChange(previousProgressLevel, newLevel, `Health ${previousProgressLevel} → ${newLevel}${detail}`);
+      previousProgressLevel = newLevel;
+    }
+  }
 }
 
 /**
@@ -104,6 +156,27 @@ export function getHealthHistory(): readonly HealthSnapshot[] {
   return healthHistory;
 }
 
+/**
+ * Get the latest health issues from the most recent snapshot.
+ * Returns issues from the last snapshot that had any, for real-time visibility.
+ */
+export function getLatestHealthIssues(): HealthIssueDetail[] {
+  for (let i = healthHistory.length - 1; i >= 0; i--) {
+    if (healthHistory[i]!.issues.length > 0) return healthHistory[i]!.issues;
+  }
+  return [];
+}
+
+/**
+ * Get the latest fixes applied from the most recent snapshot.
+ */
+export function getLatestHealthFixes(): string[] {
+  for (let i = healthHistory.length - 1; i >= 0; i--) {
+    if (healthHistory[i]!.fixes.length > 0) return healthHistory[i]!.fixes;
+  }
+  return [];
+}
+
 /**
  * Reset health tracking state. Called on auto-mode start/stop.
  */
@@ -111,6 +184,7 @@ export function resetHealthTracking(): void {
   healthHistory = [];
   consecutiveErrorUnits = 0;
   healthUnitIndex = 0;
+  previousProgressLevel = "green";
 }
 
 // ── Pre-Dispatch Health Gate ───────────────────────────────────────────────
@@ -285,26 +359,48 @@ export function resetEscalation(): void {
 
 /**
  * Format a health summary for display in the auto-mode dashboard.
+ * Human-readable with full words, not abbreviations.
  */
 export function formatHealthSummary(): string {
   if (healthHistory.length === 0) return "No health data yet.";
 
   const latest = healthHistory[healthHistory.length - 1]!;
   const trend = getHealthTrend();
-  const trendIcon = trend === "improving" ? "+" : trend === "degrading" ? "-" : "=";
+  const trendLabel = trend === "improving" ? "improving"
+    : trend === "degrading" ? "degrading"
+      : trend === "stable" ? "stable"
+        : "unknown";
   const totalFixes = healthHistory.reduce((sum, s) => sum + s.fixesApplied, 0);
 
-  const parts = [
-    `Health: ${latest.errors}E/${latest.warnings}W`,
-    `trend:${trendIcon}`,
-    `fixes:${totalFixes}`,
-  ];
+  const parts: string[] = [];
 
-  if (consecutiveErrorUnits > 0) {
-    parts.push(`streak:${consecutiveErrorUnits}/${ESCALATION_THRESHOLD}`);
+  // Error/warning summary
+  if (latest.errors === 0 && latest.warnings === 0) {
+    parts.push("No issues");
+  } else {
+    const counts: string[] = [];
+    if (latest.errors > 0) counts.push(`${latest.errors} error${latest.errors > 1 ? "s" : ""}`);
+    if (latest.warnings > 0) counts.push(`${latest.warnings} warning${latest.warnings > 1 ? "s" : ""}`);
+    parts.push(counts.join(", "));
   }
 
-  return parts.join(" | ");
+  parts.push(`trend ${trendLabel}`);
+
+  if (totalFixes > 0) {
+    parts.push(`${totalFixes} fix${totalFixes > 1 ? "es" : ""} applied`);
+  }
+
+  if (consecutiveErrorUnits > 0) {
+    parts.push(`${consecutiveErrorUnits} of ${ESCALATION_THRESHOLD} consecutive errors before escalation`);
+  }
+
+  // Include top issue from latest snapshot
+  if (latest.issues.length > 0) {
+    const topIssue = latest.issues.find(i => i.severity === "error") ?? latest.issues[0]!;
+    parts.push(`latest: ${topIssue.message}`);
+  }
+
+  return parts.join(" · ");
 }
 
 /**
diff --git a/src/resources/extensions/gsd/doctor.ts b/src/resources/extensions/gsd/doctor.ts
index 88112f79a..9af4f063b 100644
--- a/src/resources/extensions/gsd/doctor.ts
+++ b/src/resources/extensions/gsd/doctor.ts
@@ -387,18 +387,62 @@ function detectCircularDependencies(slices: RoadmapSliceEntry[]): string[][] {
 }
 
 // ── Helper: doctor run history ──────────────────────────────────────────────
-interface DoctorHistoryEntry { ts: string; ok: boolean; errors: number; warnings: number; fixes: number; codes: string[] }
+export interface DoctorHistoryEntry {
+  ts: string;
+  ok: boolean;
+  errors: number;
+  warnings: number;
+  fixes: number;
+  codes: string[];
+  /** Issue messages with severity and scope (added in Phase 2). */
+  issues?: Array<{ severity: string; code: string; message: string; unitId: string }>;
+  /** Fix descriptions applied during this run (added in Phase 2). */
+  fixDescriptions?: string[];
+  /** Milestone/slice scope this doctor run was scoped to (e.g. "M001/S02"). */
+  scope?: string;
+  /** Human-readable one-line summary of this doctor run. */
+  summary?: string;
+}
 
 async function appendDoctorHistory(basePath: string, report: DoctorReport): Promise<void> {
   try {
     const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    const errorCount = report.issues.filter(i => i.severity === "error").length;
+    const warningCount = report.issues.filter(i => i.severity === "warning").length;
+    const issueDetails = report.issues
+      .filter(i => i.severity === "error" || i.severity === "warning")
+      .slice(0, 10) // cap to keep JSONL lines bounded
+      .map(i => ({ severity: i.severity, code: i.code, message: i.message, unitId: i.unitId }));
+
+    // Human-readable one-line summary
+    const summaryParts: string[] = [];
+    if (report.ok) {
+      summaryParts.push("Clean");
+    } else {
+      const counts: string[] = [];
+      if (errorCount > 0) counts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
+      if (warningCount > 0) counts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
+      summaryParts.push(counts.join(", "));
+    }
+    if (report.fixesApplied.length > 0) {
+      summaryParts.push(`${report.fixesApplied.length} fixed`);
+    }
+    if (issueDetails.length > 0) {
+      const topIssue = issueDetails.find(i => i.severity === "error") ?? issueDetails[0]!;
+      summaryParts.push(topIssue.message);
+    }
+
     const entry = JSON.stringify({
       ts: new Date().toISOString(),
       ok: report.ok,
-      errors: report.issues.filter(i => i.severity === "error").length,
-      warnings: report.issues.filter(i => i.severity === "warning").length,
+      errors: errorCount,
+      warnings: warningCount,
       fixes: report.fixesApplied.length,
       codes: [...new Set(report.issues.map(i => i.code))],
+      issues: issueDetails.length > 0 ? issueDetails : undefined,
+      fixDescriptions: report.fixesApplied.length > 0 ? report.fixesApplied : undefined,
+      scope: (report as any).scope as string | undefined,
+      summary: summaryParts.join(" · "),
     } satisfies DoctorHistoryEntry);
     const existing = existsSync(historyPath) ? readFileSync(historyPath, "utf-8") : "";
     await saveFile(historyPath, existing + entry + "\n");
diff --git a/src/resources/extensions/env-utils.ts b/src/resources/extensions/gsd/env-utils.ts
similarity index 100%
rename from src/resources/extensions/env-utils.ts
rename to src/resources/extensions/gsd/env-utils.ts
diff --git a/src/resources/extensions/gsd/export-html.ts b/src/resources/extensions/gsd/export-html.ts
index 18c367aaf..09c40a022 100644
--- a/src/resources/extensions/gsd/export-html.ts
+++ b/src/resources/extensions/gsd/export-html.ts
@@ -296,9 +296,60 @@ function buildHealthSection(data: VisualizerData): string {
       </tbody>
     </table>` : '';
 
+  // Progress score section
+  let progressHtml = '';
+  if (h.progressScore) {
+    const ps = h.progressScore;
+    const scoreColor = ps.level === 'green' ? '#22c55e' : ps.level === 'yellow' ? '#eab308' : '#ef4444';
+    const signalRows = ps.signals.map(s => {
+      const icon = s.kind === 'positive' ? '✓' : s.kind === 'negative' ? '✗' : '·';
+      const color = s.kind === 'positive' ? '#22c55e' : s.kind === 'negative' ? '#ef4444' : '#888';
+      return `<div style="margin-left:1em;color:${color}">${icon} ${esc(s.label)}</div>`;
+    }).join('');
+    progressHtml = `
+      <h3>Progress Score</h3>
+      <div style="font-size:1.1em;font-weight:bold;color:${scoreColor}">● ${esc(ps.summary)}</div>
+      ${signalRows}`;
+  }
+
+  // Doctor history section
+  let historyHtml = '';
+  const doctorHistory = h.doctorHistory ?? [];
+  if (doctorHistory.length > 0) {
+    const historyRows = doctorHistory.slice(0, 20).map(entry => {
+      const statusIcon = entry.ok ? '✓' : '✗';
+      const statusColor = entry.ok ? '#22c55e' : '#ef4444';
+      const ts = entry.ts.replace('T', ' ').slice(0, 19);
+      const scopeTag = entry.scope ? `<span class="mono" style="color:#888"> [${esc(entry.scope)}]</span>` : '';
+      const summaryText = entry.summary ? esc(entry.summary) : `${entry.errors} errors, ${entry.warnings} warnings, ${entry.fixes} fixes`;
+      const issueDetails = (entry.issues ?? []).slice(0, 3).map(i => {
+        const iColor = i.severity === 'error' ? '#ef4444' : '#eab308';
+        return `<div style="margin-left:2em;color:${iColor};font-size:0.85em">${i.severity === 'error' ? '✗' : '⚠'} ${esc(i.message)} <span class="mono" style="color:#888">${esc(i.unitId)}</span></div>`;
+      }).join('');
+      const fixDetails = (entry.fixDescriptions ?? []).slice(0, 2).map(f =>
+        `<div style="margin-left:2em;color:#22c55e;font-size:0.85em">↳ ${esc(f)}</div>`
+      ).join('');
+      return `<tr style="color:${statusColor}">
+        <td class="mono">${statusIcon}</td>
+        <td class="mono">${esc(ts)}${scopeTag}</td>
+        <td>${summaryText}</td>
+      </tr>
+      ${issueDetails || fixDetails ? `<tr><td colspan="3">${issueDetails}${fixDetails}</td></tr>` : ''}`;
+    }).join('');
+
+    historyHtml = `
+      <h3>Doctor Run History</h3>
+      <table class="tbl">
+        <thead><tr><th></th><th>Time</th><th>Summary</th></tr></thead>
+        <tbody>${historyRows}</tbody>
+      </table>`;
+  }
+
   return section('health', 'Health', `
     <table class="tbl tbl-kv"><tbody>${rows.join('')}</tbody></table>
     ${tierRows}
+    ${progressHtml}
+    ${historyHtml}
   `);
 }
 
diff --git a/src/resources/extensions/gsd/files.ts b/src/resources/extensions/gsd/files.ts
index 6c17362ef..f60c697a5 100644
--- a/src/resources/extensions/gsd/files.ts
+++ b/src/resources/extensions/gsd/files.ts
@@ -20,7 +20,7 @@ import type {
   ManifestStatus,
 } from './types.js';
 
-import { checkExistingEnvKeys } from '../env-utils.js';
+import { checkExistingEnvKeys } from './env-utils.js';
 import { parseRoadmapSlices } from './roadmap-slices.js';
 import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativeParseSummaryFile, NATIVE_UNAVAILABLE } from './native-parser-bridge.js';
 import { debugTime, debugCount } from './debug-logger.js';
diff --git a/src/resources/extensions/gsd/health-widget.ts b/src/resources/extensions/gsd/health-widget.ts
index 03afa7d3f..fa63e6677 100644
--- a/src/resources/extensions/gsd/health-widget.ts
+++ b/src/resources/extensions/gsd/health-widget.ts
@@ -15,7 +15,8 @@ import { runEnvironmentChecks } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
-import { projectRoot } from "./commands.js";
+import { projectRoot } from "./commands/context.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import {
   buildHealthLines,
   detectHealthWidgetProjectState,
diff --git a/src/resources/extensions/gsd/index.ts b/src/resources/extensions/gsd/index.ts
index 4114639cc..13e6dc97c 100644
--- a/src/resources/extensions/gsd/index.ts
+++ b/src/resources/extensions/gsd/index.ts
@@ -1,1315 +1,13 @@
-/**
- * GSD Extension — /gsd
- *
- * One command, one wizard. Reads state from disk, shows contextual options,
- * dispatches through GSD-WORKFLOW.md. The LLM does the rest.
- *
- * Auto-mode: /gsd auto loops fresh sessions until milestone complete.
- *
- * Commands:
- *   /gsd        — contextual wizard (smart entry point)
- *   /gsd auto   — start auto-mode (fresh session per unit)
- *   /gsd stop   — stop auto-mode gracefully
- *   /gsd status — progress dashboard
- *
- * Hooks:
- *   before_agent_start — inject GSD system context for GSD projects
- *   agent_end — auto-mode advancement
- *   session_before_compact — save continue.md OR block during auto
- */
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  ExtensionContext,
-} from "@gsd/pi-coding-agent";
-import { createBashTool, createWriteTool, createReadTool, createEditTool, isToolCallEventType } from "@gsd/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+export {
+  isDepthVerified,
+  isQueuePhaseActive,
+  setQueuePhaseActive,
+  shouldBlockContextWrite,
+} from "./bootstrap/write-gate.js";
 
-import { debugLog, debugTime } from "./debug-logger.js";
-import { registerGSDCommand } from "./commands.js";
-import { loadToolApiKeys } from "./commands-config.js";
-import { registerExitCommand } from "./exit-command.js";
-import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
-import { getActiveAutoWorktreeContext } from "./auto-worktree.js";
-import { saveFile, formatContinue, loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection } from "./files.js";
-import { loadPrompt } from "./prompt-loader.js";
-import { deriveState } from "./state.js";
-import { isAutoActive, isAutoPaused, pauseAuto, getAutoDashboardData, getAutoModeStartModel, markToolStart, markToolEnd } from "./auto.js";
-import { isSessionSwitchInFlight, resolveAgentEnd } from "./auto-loop.js";
-import { saveActivityLog } from "./activity-log.js";
-import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId, findMilestoneIds, nextMilestoneId } from "./guided-flow.js";
-import { GSDDashboardOverlay } from "./dashboard-overlay.js";
-import {
-  loadEffectiveGSDPreferences,
-  renderPreferencesForSystemPrompt,
-  resolveAllSkillReferences,
-  resolveModelWithFallbacksForUnit,
-  getNextFallbackModel,
-  isTransientNetworkError,
-} from "./preferences.js";
-import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "./skill-discovery.js";
-import {
-  resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTaskFiles, resolveTasksDir,
-  relSliceFile, relSlicePath, relTaskFile,
-  buildSliceFileName, buildMilestoneFileName, gsdRoot, resolveMilestonePath,
-  resolveGsdRootFile,
-} from "./paths.js";
-import { Key } from "@gsd/pi-tui";
-import { join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { shortcutDesc } from "../shared/mod.js";
-
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-import { Text } from "@gsd/pi-tui";
-import { pauseAutoForProviderError, classifyProviderError } from "./provider-error-pause.js";
-import { toPosixPath } from "../shared/mod.js";
-import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
-import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
-import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js";
-
-// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
-// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
-// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
-
-function warnDeprecatedAgentInstructions(): void {
-  const paths = [
-    join(gsdHome, "agent-instructions.md"),
-    join(process.cwd(), ".gsd", "agent-instructions.md"),
-  ];
-  for (const p of paths) {
-    if (existsSync(p)) {
-      console.warn(
-        `[GSD] DEPRECATED: ${p} is no longer loaded. ` +
-        `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
-        `See https://github.com/gsd-build/GSD-2/issues/1492`,
-      );
-    }
-  }
-}
-
-// ── Depth verification state ──────────────────────────────────────────────
-let depthVerificationDone = false;
-
-// ── DB lazy-open helper ───────────────────────────────────────────────────
-// In manual sessions (no auto-mode), the DB is never opened by bootstrapAutoSession.
-// This helper ensures the DB is lazily opened on first tool call that needs it.
-async function ensureDbOpen(): Promise<boolean> {
-  try {
-    const db = await import("./gsd-db.js");
-    if (db.isDbAvailable()) return true;
-    const dbPath = join(process.cwd(), ".gsd", "gsd.db");
-    if (existsSync(dbPath)) {
-      return db.openDatabase(dbPath);
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-// ── Queue phase tracking ──────────────────────────────────────────────────
-// When true, the LLM is in a queue flow writing CONTEXT.md files.
-// The write-gate applies during queue flows just like discussion flows.
-let activeQueuePhase = false;
-
-// ── Network error retry counters ──────────────────────────────────────────
-// Tracks per-model retry attempts for transient network errors.
-// Cleared when a model switch occurs or retries are exhausted.
-const networkRetryCounters = new Map<string, number>();
-const MAX_TRANSIENT_AUTO_RESUMES = 3;
-let consecutiveTransientErrors = 0;
-
-export function isDepthVerified(): boolean {
-  return depthVerificationDone;
-}
-
-/** Check whether a queue phase is active. */
-export function isQueuePhaseActive(): boolean {
-  return activeQueuePhase;
-}
-
-/** Set the queue phase state — called from guided-flow-queue.ts on dispatch. */
-export function setQueuePhaseActive(active: boolean): void {
-  activeQueuePhase = active;
-}
-
-// ── Write-gate: block CONTEXT.md writes during discussion without depth verification ──
-const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
-
-export function shouldBlockContextWrite(
-  toolName: string,
-  inputPath: string,
-  milestoneId: string | null,
-  depthVerified: boolean,
-  queuePhaseActive?: boolean,
-): { block: boolean; reason?: string } {
-  if (toolName !== "write") return { block: false };
-
-  // Gate applies during both discussion (milestoneId set) and queue (queuePhaseActive) flows
-  const inDiscussion = milestoneId !== null;
-  const inQueue = queuePhaseActive ?? false;
-  if (!inDiscussion && !inQueue) return { block: false };
-
-  if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
-  if (depthVerified) return { block: false };
-
-  return {
-    block: true,
-    reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
-  };
-}
-
-// ── ASCII logo ────────────────────────────────────────────────────────────
-const GSD_LOGO_LINES = [
-  "   ██████╗ ███████╗██████╗ ",
-  "  ██╔════╝ ██╔════╝██╔══██╗",
-  "  ██║  ███╗███████╗██║  ██║",
-  "  ██║   ██║╚════██║██║  ██║",
-  "  ╚██████╔╝███████║██████╔╝",
-  "   ╚═════╝ ╚══════╝╚═════╝ ",
-];
-
-export default function (pi: ExtensionAPI) {
-  registerGSDCommand(pi);
-  registerWorktreeCommand(pi);
-  registerExitCommand(pi);
-
-  // ── EPIPE guard — prevent crash when stdout/stderr pipe closes unexpectedly ──
-  // Node.js throws a fatal `Error: write EPIPE` when the parent process closes
-  // its end of the stdio pipe (e.g. during shell/IPC teardown) while auto-mode
-  // is still writing diagnostics. Catching this here gives auto-mode a clean
-  // chance to persist state and pause instead of crashing (see issue #739).
-  if (!process.listeners("uncaughtException").some(l => l.name === "_gsdEpipeGuard")) {
-    const _gsdEpipeGuard = (err: Error): void => {
-      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
-        // Pipe closed — nothing we can write; just exit cleanly
-        process.exit(0);
-      }
-      if ((err as NodeJS.ErrnoException).code === "ENOENT" &&
-          (err as any).syscall?.startsWith("spawn")) {
-        // spawn ENOENT — command not found (e.g., npx on Windows).
-        // This surfaces as an uncaught exception from child_process but
-        // is not a fatal process error. Log and continue instead of
-        // crashing auto-mode (#1384).
-        process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
-        return;
-      }
-      // Re-throw anything that isn't EPIPE/ENOENT so real crashes still surface
-      throw err;
-    };
-    process.on("uncaughtException", _gsdEpipeGuard);
-  }
-
-  // ── /kill — immediate exit (bypass cleanup) ─────────────────────────────
-  pi.registerCommand("kill", {
-    description: "Exit GSD immediately (no cleanup)",
-    handler: async (_args: string, _ctx: ExtensionCommandContext) => {
-      process.exit(0);
-    },
-  });
-
-  // ── Dynamic-cwd bash tool with default timeout ────────────────────────
-  // The built-in bash tool captures cwd at startup. This replacement uses
-  // a spawnHook to read process.cwd() dynamically so that process.chdir()
-  // (used by /worktree switch) propagates to shell commands.
-  //
-  // The upstream SDK's bash tool has no default timeout — if the LLM omits
-  // the timeout parameter, commands run indefinitely, causing hangs on
-  // Windows where process killing is unreliable (see #40). We wrap execute
-  // to inject a 120-second default when no timeout is provided.
-  const baseBash = createBashTool(process.cwd(), {
-    spawnHook: (ctx) => ({ ...ctx, cwd: process.cwd() }),
-  });
-  const dynamicBash = {
-    ...baseBash,
-    execute: async (
-      toolCallId: string,
-      params: { command: string; timeout?: number },
-      signal?: AbortSignal,
-      onUpdate?: any,
-      ctx?: any,
-    ) => {
-      const paramsWithTimeout = {
-        ...params,
-        timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
-      };
-      return (baseBash as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
-    },
-  };
-  pi.registerTool(dynamicBash as any);
-
-  // ── Dynamic-cwd file tools (write, read, edit) ────────────────────────
-  // The built-in file tools capture cwd at startup. When process.chdir()
-  // moves us into a worktree, relative paths still resolve against the
-  // original launch directory. These replacements delegate to freshly-
-  // created tools on each call so that process.cwd() is read dynamically.
-  const baseWrite = createWriteTool(process.cwd());
-  const dynamicWrite = {
-    ...baseWrite,
-    execute: async (
-      toolCallId: string,
-      params: { path: string; content: string },
-      signal?: AbortSignal,
-      onUpdate?: any,
-      ctx?: any,
-    ) => {
-      const fresh = createWriteTool(process.cwd());
-      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
-    },
-  };
-  pi.registerTool(dynamicWrite as any);
-
-  const baseRead = createReadTool(process.cwd());
-  const dynamicRead = {
-    ...baseRead,
-    execute: async (
-      toolCallId: string,
-      params: { path: string; offset?: number; limit?: number },
-      signal?: AbortSignal,
-      onUpdate?: any,
-      ctx?: any,
-    ) => {
-      const fresh = createReadTool(process.cwd());
-      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
-    },
-  };
-  pi.registerTool(dynamicRead as any);
-
-  const baseEdit = createEditTool(process.cwd());
-  const dynamicEdit = {
-    ...baseEdit,
-    execute: async (
-      toolCallId: string,
-      params: { path: string; oldText: string; newText: string },
-      signal?: AbortSignal,
-      onUpdate?: any,
-      ctx?: any,
-    ) => {
-      const fresh = createEditTool(process.cwd());
-      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
-    },
-  };
-  pi.registerTool(dynamicEdit as any);
-
-  // ── Structured LLM tools — DB-first write path (R014) ──────────────────
-
-  pi.registerTool({
-    name: "gsd_save_decision",
-    label: "Save Decision",
-    description:
-      "Record a project decision to the GSD database and regenerate DECISIONS.md. " +
-      "Decision IDs are auto-assigned — never provide an ID manually.",
-    promptSnippet: "Record a project decision to the GSD database (auto-assigns ID, regenerates DECISIONS.md)",
-    promptGuidelines: [
-      "Use gsd_save_decision when recording an architectural, pattern, library, or observability decision.",
-      "Decision IDs are auto-assigned (D001, D002, ...) — never guess or provide an ID.",
-      "All fields except revisable and when_context are required.",
-      "The tool writes to the DB and regenerates .gsd/DECISIONS.md automatically.",
-    ],
-    parameters: Type.Object({
-      scope: Type.String({ description: "Scope of the decision (e.g. 'architecture', 'library', 'observability')" }),
-      decision: Type.String({ description: "What is being decided" }),
-      choice: Type.String({ description: "The choice made" }),
-      rationale: Type.String({ description: "Why this choice was made" }),
-      revisable: Type.Optional(Type.String({ description: "Whether this can be revisited (default: 'Yes')" })),
-      when_context: Type.Optional(Type.String({ description: "When/context for the decision (e.g. milestone ID)" })),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      // Ensure DB is open (lazy-open on first tool call in manual sessions)
-      const dbAvailable = await ensureDbOpen();
-
-      if (!dbAvailable) {
-        return {
-          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save decision." }],
-          isError: true,
-          details: { operation: "save_decision", error: "db_unavailable" },
-        };
-      }
-
-      try {
-        const { saveDecisionToDb } = await import("./db-writer.js");
-        const { id } = await saveDecisionToDb(
-          {
-            scope: params.scope,
-            decision: params.decision,
-            choice: params.choice,
-            rationale: params.rationale,
-            revisable: params.revisable,
-            when_context: params.when_context,
-          },
-          process.cwd(),
-        );
-        return {
-          content: [{ type: "text" as const, text: `Saved decision ${id}` }],
-          details: { operation: "save_decision", id },
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
-        return {
-          content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
-          isError: true,
-          details: { operation: "save_decision", error: msg },
-        };
-      }
-    },
-  });
-
-  pi.registerTool({
-    name: "gsd_update_requirement",
-    label: "Update Requirement",
-    description:
-      "Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md. " +
-      "Provide the requirement ID (e.g. R001) and any fields to update.",
-    promptSnippet: "Update an existing GSD requirement by ID (regenerates REQUIREMENTS.md)",
-    promptGuidelines: [
-      "Use gsd_update_requirement to change status, validation, notes, or other fields on an existing requirement.",
-      "The id parameter is required — it must be an existing RXXX identifier.",
-      "All other fields are optional — only provided fields are updated.",
-      "The tool verifies the requirement exists before updating.",
-    ],
-    parameters: Type.Object({
-      id: Type.String({ description: "The requirement ID (e.g. R001, R014)" }),
-      status: Type.Optional(Type.String({ description: "New status (e.g. 'active', 'validated', 'deferred')" })),
-      validation: Type.Optional(Type.String({ description: "Validation criteria or proof" })),
-      notes: Type.Optional(Type.String({ description: "Additional notes" })),
-      description: Type.Optional(Type.String({ description: "Updated description" })),
-      primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })),
-      supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const dbAvailable = await ensureDbOpen();
-
-      if (!dbAvailable) {
-        return {
-          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot update requirement." }],
-          isError: true,
-          details: { operation: "update_requirement", id: params.id, error: "db_unavailable" },
-        };
-      }
-
-      try {
-        // Verify requirement exists
-        const db = await import("./gsd-db.js");
-        const existing = db.getRequirementById(params.id);
-        if (!existing) {
-          return {
-            content: [{ type: "text" as const, text: `Error: Requirement ${params.id} not found.` }],
-            isError: true,
-            details: { operation: "update_requirement", id: params.id, error: "not_found" },
-          };
-        }
-
-        const { updateRequirementInDb } = await import("./db-writer.js");
-        const updates: Record<string, string | undefined> = {};
-        if (params.status !== undefined) updates.status = params.status;
-        if (params.validation !== undefined) updates.validation = params.validation;
-        if (params.notes !== undefined) updates.notes = params.notes;
-        if (params.description !== undefined) updates.description = params.description;
-        if (params.primary_owner !== undefined) updates.primary_owner = params.primary_owner;
-        if (params.supporting_slices !== undefined) updates.supporting_slices = params.supporting_slices;
-
-        await updateRequirementInDb(params.id, updates, process.cwd());
-
-        return {
-          content: [{ type: "text" as const, text: `Updated requirement ${params.id}` }],
-          details: { operation: "update_requirement", id: params.id },
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
-        return {
-          content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
-          isError: true,
-          details: { operation: "update_requirement", id: params.id, error: msg },
-        };
-      }
-    },
-  });
-
-  pi.registerTool({
-    name: "gsd_save_summary",
-    label: "Save Summary",
-    description:
-      "Save a summary, research, context, or assessment artifact to the GSD database and write it to disk. " +
-      "Computes the file path from milestone/slice/task IDs automatically.",
-    promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
-    promptGuidelines: [
-      "Use gsd_save_summary to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT).",
-      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
-      "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT.",
-    ],
-    parameters: Type.Object({
-      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
-      slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
-      task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT" }),
-      content: Type.String({ description: "The full markdown content of the artifact" }),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const dbAvailable = await ensureDbOpen();
-
-      if (!dbAvailable) {
-        return {
-          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save artifact." }],
-          isError: true,
-          details: { operation: "save_summary", error: "db_unavailable" },
-        };
-      }
-
-      // Validate artifact_type
-      const validTypes = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT"];
-      if (!validTypes.includes(params.artifact_type)) {
-        return {
-          content: [{ type: "text" as const, text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${validTypes.join(", ")}` }],
-          isError: true,
-          details: { operation: "save_summary", error: "invalid_artifact_type" },
-        };
-      }
-
-      try {
-        // Compute relative path from IDs
-        let relativePath: string;
-        if (params.task_id && params.slice_id) {
-          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
-        } else if (params.slice_id) {
-          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
-        } else {
-          relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
-        }
-
-        const { saveArtifactToDb } = await import("./db-writer.js");
-        await saveArtifactToDb(
-          {
-            path: relativePath,
-            artifact_type: params.artifact_type,
-            content: params.content,
-            milestone_id: params.milestone_id,
-            slice_id: params.slice_id,
-            task_id: params.task_id,
-          },
-          process.cwd(),
-        );
-
-        return {
-          content: [{ type: "text" as const, text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-          details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
-        return {
-          content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
-          isError: true,
-          details: { operation: "save_summary", error: msg },
-        };
-      }
-    },
-  });
-
-  // ── gsd_generate_milestone_id — canonical milestone ID generation ──────
-  // The LLM cannot generate random suffixes for unique_milestone_ids on its
-  // own. This tool calls back into the TS code that owns ID generation,
-  // ensuring the preference is always respected and IDs are always valid.
-  //
-  // Reservation set: tracks IDs returned by this tool but not yet persisted
-  // to disk, preventing duplicate M001 when called multiple times (#961).
-  const reservedMilestoneIds = new Set<string>();
-
-  pi.registerTool({
-    name: "gsd_generate_milestone_id",
-    label: "Generate Milestone ID",
-    description:
-      "Generate the next milestone ID for a new GSD milestone. " +
-      "Scans existing milestones on disk and respects the unique_milestone_ids preference. " +
-      "Always use this tool when creating a new milestone — never invent milestone IDs manually.",
-    promptSnippet: "Generate a valid milestone ID (respects unique_milestone_ids preference)",
-    promptGuidelines: [
-      "ALWAYS call gsd_generate_milestone_id before creating a new milestone directory or writing milestone files.",
-      "Never invent or hardcode milestone IDs like M001, M002 — always use this tool.",
-      "Call it once per milestone you need to create. For multi-milestone projects, call it once for each milestone in sequence.",
-      "The tool returns the correct format based on project preferences (e.g. M001 or M001-r5jzab).",
-    ],
-    parameters: Type.Object({}),
-    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
-      try {
-        const basePath = process.cwd();
-        const existingIds = findMilestoneIds(basePath);
-        const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
-        // Combine on-disk IDs with previously reserved (but not yet persisted) IDs
-        const allIds = [...new Set([...existingIds, ...reservedMilestoneIds])];
-        const newId = nextMilestoneId(allIds, uniqueEnabled);
-        reservedMilestoneIds.add(newId);
-        return {
-          content: [{ type: "text" as const, text: newId }],
-          details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, reservedCount: reservedMilestoneIds.size, uniqueEnabled },
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
-          isError: true,
-          details: { operation: "generate_milestone_id", error: msg },
-        };
-      }
-    },
-  });
-
-  // ── session_start: render branded GSD header + load tool keys + remote status ──
-  pi.on("session_start", async (_event, ctx) => {
-    // Clear per-session state that must not leak across sessions (e.g. RPC mode)
-    depthVerificationDone = false;
-
-    // Theme access throws in RPC mode (no TUI) — header is decorative, skip it
-    try {
-      const theme = ctx.ui.theme;
-      const version = process.env.GSD_VERSION || "0.0.0";
-
-      const logoText = GSD_LOGO_LINES.map((line) => theme.fg("accent", line)).join("\n");
-      const titleLine = `  ${theme.bold("Get Shit Done")} ${theme.fg("dim", `v${version}`)}`;
-
-      const headerContent = `${logoText}\n${titleLine}`;
-      ctx.ui.setHeader((_ui, _theme) => new Text(headerContent, 1, 0));
-    } catch {
-      // RPC mode — no TUI, skip header rendering
-    }
-
-    // Load tool API keys from auth.json into environment
-    loadToolApiKeys();
-
-    // Notify remote questions status if configured
-    try {
-      const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
-        import("../remote-questions/config.js"),
-        import("../remote-questions/status.js"),
-      ]);
-      const status = getRemoteConfigStatus();
-      const latest = getLatestPromptSummary();
-      if (!status.includes("not configured")) {
-        const suffix = latest ? `\nLast remote prompt: ${latest.id} (${latest.status})` : "";
-        ctx.ui.notify(`${status}${suffix}`, status.includes("disabled") ? "warning" : "info");
-      }
-    } catch {
-      // Remote questions module not available — ignore
-    }
-  });
-
-  // ── Ctrl+Alt+G shortcut — GSD dashboard overlay ────────────────────────
-  pi.registerShortcut(Key.ctrlAlt("g"), {
-    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
-    handler: async (ctx) => {
-      // Only show if .gsd/ exists
-      if (!existsSync(join(process.cwd(), ".gsd"))) {
-        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
-        return;
-      }
-
-      await ctx.ui.custom<void>(
-        (tui, theme, _kb, done) => {
-          return new GSDDashboardOverlay(tui, theme, () => done());
-        },
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
-        },
-      );
-    },
-  });
-
-  // ── before_agent_start: inject GSD contract into true system prompt ─────
-  pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
-    if (!existsSync(join(process.cwd(), ".gsd"))) return;
-
-    const stopContextTimer = debugTime("context-inject");
-    const systemContent = loadPrompt("system");
-    const loadedPreferences = loadEffectiveGSDPreferences();
-    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-      markCmuxPromptShown();
-      ctx.ui.notify(
-        "cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.",
-        "info",
-      );
-    }
-    let preferenceBlock = "";
-    if (loadedPreferences) {
-      const cwd = process.cwd();
-      const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
-      preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
-
-      // Emit warnings for unresolved skill references
-      if (report.warnings.length > 0) {
-        ctx.ui.notify(
-          `GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`,
-          "warning",
-        );
-      }
-    }
-
-    // Load project knowledge if available
-    let knowledgeBlock = "";
-    const knowledgePath = resolveGsdRootFile(process.cwd(), "KNOWLEDGE");
-    if (existsSync(knowledgePath)) {
-      try {
-        const content = readFileSync(knowledgePath, "utf-8").trim();
-        if (content) {
-          knowledgeBlock = `\n\n[PROJECT KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${content}`;
-        }
-      } catch {
-        // File read error — skip knowledge injection
-      }
-    }
-
-    // Inject auto-learned project memories
-    let memoryBlock = "";
-    try {
-      const { getActiveMemoriesRanked, formatMemoriesForPrompt } = await import("./memory-store.js");
-      const memories = getActiveMemoriesRanked(30);
-      if (memories.length > 0) {
-        const formatted = formatMemoriesForPrompt(memories, 2000);
-        if (formatted) {
-          memoryBlock = `\n\n${formatted}`;
-        }
-      }
-    } catch { /* non-fatal */ }
-
-    // Detect skills installed during this auto-mode session
-    let newSkillsBlock = "";
-    if (hasSkillSnapshot()) {
-      const newSkills = detectNewSkills();
-      if (newSkills.length > 0) {
-        newSkillsBlock = formatSkillsXml(newSkills);
-      }
-    }
-
-    // Warn if deprecated agent-instructions.md files are still present
-    warnDeprecatedAgentInstructions();
-
-    const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
-
-    // Worktree context — override the static CWD in the system prompt
-    let worktreeBlock = "";
-    const worktreeName = getActiveWorktreeName();
-    const worktreeMainCwd = getWorktreeOriginalCwd();
-    const autoWorktree = getActiveAutoWorktreeContext();
-    if (worktreeName && worktreeMainCwd) {
-      worktreeBlock = [
-        "",
-        "",
-        "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
-        `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
-        `The actual current working directory is: ${toPosixPath(process.cwd())}`,
-        "",
-        `You are working inside a GSD worktree.`,
-        `- Worktree name: ${worktreeName}`,
-        `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
-        `- Main project: ${toPosixPath(worktreeMainCwd)}`,
-        `- Branch: worktree/${worktreeName}`,
-        "",
-        "All file operations, bash commands, and GSD state resolve against the worktree path above.",
-        "Use /worktree merge to merge changes back. Use /worktree return to switch back to the main tree.",
-      ].join("\n");
-    } else if (autoWorktree) {
-      worktreeBlock = [
-        "",
-        "",
-        "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
-        `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
-        `The actual current working directory is: ${toPosixPath(process.cwd())}`,
-        "",
-        "You are working inside a GSD auto-worktree.",
-        `- Milestone worktree: ${autoWorktree.worktreeName}`,
-        `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
-        `- Main project: ${toPosixPath(autoWorktree.originalBase)}`,
-        `- Branch: ${autoWorktree.branch}`,
-        "",
-        "All file operations, bash commands, and GSD state resolve against the worktree path above.",
-        "Write every .gsd artifact in the worktree path above, never in the main project tree.",
-      ].join("\n");
-    }
-
-    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
-    stopContextTimer({
-      systemPromptSize: fullSystem.length,
-      injectionSize: injection?.length ?? 0,
-      hasPreferences: preferenceBlock.length > 0,
-      hasNewSkills: newSkillsBlock.length > 0,
-    });
-
-    return {
-      systemPrompt: fullSystem,
-      ...(injection
-        ? {
-          message: {
-            customType: "gsd-guided-context",
-            content: injection,
-            display: false,
-          },
-        }
-        : {}),
-    };
-  });
-
-  // ── agent_end: auto-mode advancement or auto-start after discuss ───────────
-  pi.on("agent_end", async (event, ctx: ExtensionContext) => {
-    // If discuss phase just finished, start auto-mode
-    if (checkAutoStartAfterDiscuss()) {
-      depthVerificationDone = false;
-      activeQueuePhase = false;
-      return;
-    }
-
-    // If auto-mode is already running, advance to next unit
-    if (!isAutoActive()) return;
-
-    // Fresh-session auto-mode intentionally aborts the previous session during
-    // cmdCtx.newSession(). Ignore that agent_end so we neither pause nor
-    // resolve the new unit with an event from the old session.
-    if (isSessionSwitchInFlight()) {
-      return;
-    }
-
-    // If the agent was aborted (user pressed Escape) or hit a provider
-    // error (fetch failure, rate limit, etc.), pause auto-mode instead of
-    // advancing. This preserves the conversation so the user can inspect
-    // what happened, interact with the agent, or resume.
-    const lastMsg = event.messages[event.messages.length - 1];
-    if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
-      await pauseAuto(ctx, pi);
-      return;
-    }
-    if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
-      const errorDetail =
-        "errorMessage" in lastMsg && lastMsg.errorMessage
-          ? `: ${lastMsg.errorMessage}`
-          : "";
-
-      const errorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
-
-      // ── Transient network error retry ──────────────────────────────────
-      // Before falling back to a different model, retry the current model
-      // for transient network errors (connection reset, timeout, DNS, etc.).
-      // This prevents providers with occasional network flakiness from being
-      // immediately abandoned in favor of fallback models (#941).
-      if (isTransientNetworkError(errorMsg)) {
-        const currentModelId = ctx.model?.id ?? "unknown";
-        const retryKey = `network-retry:${currentModelId}`;
-        const maxRetries = 2;
-        const currentRetries = networkRetryCounters.get(retryKey) ?? 0;
-
-        if (currentRetries < maxRetries) {
-          networkRetryCounters.set(retryKey, currentRetries + 1);
-          const attempt = currentRetries + 1;
-          const delayMs = attempt * 3000; // 3s, 6s backoff
-          ctx.ui.notify(
-            `Network error on ${currentModelId}${errorDetail}. Retry ${attempt}/${maxRetries} in ${delayMs / 1000}s...`,
-            "warning",
-          );
-          setTimeout(() => {
-            pi.sendMessage(
-              { customType: "gsd-auto-timeout-recovery", content: "Continue execution — retrying after transient network error.", display: false },
-              { triggerTurn: true },
-            );
-          }, delayMs);
-          return;
-        }
-        // Retries exhausted — clear counter and fall through to fallback logic
-        networkRetryCounters.delete(retryKey);
-        ctx.ui.notify(
-          `Network retries exhausted for ${currentModelId}. Attempting model fallback.`,
-          "warning",
-        );
-      }
-
-      const dash = getAutoDashboardData();
-      if (dash.currentUnit) {
-        const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
-        if (modelConfig && modelConfig.fallbacks.length > 0) {
-          const availableModels = ctx.modelRegistry.getAvailable();
-          const currentModelId = ctx.model?.id;
-
-          const nextModelId = getNextFallbackModel(currentModelId, modelConfig);
-
-          if (nextModelId) {
-            // Clear any network retry counters when switching models
-            networkRetryCounters.clear();
-
-            let modelToSet;
-            const slashIdx = nextModelId.indexOf("/");
-            if (slashIdx !== -1) {
-              const provider = nextModelId.substring(0, slashIdx);
-              const id = nextModelId.substring(slashIdx + 1);
-              modelToSet = availableModels.find(
-                m => m.provider.toLowerCase() === provider.toLowerCase()
-                  && m.id.toLowerCase() === id.toLowerCase()
-              );
-            } else {
-              const currentProvider = ctx.model?.provider;
-              const exactProviderMatch = availableModels.find(
-                m => m.id === nextModelId && m.provider === currentProvider
-              );
-              modelToSet = exactProviderMatch ?? availableModels.find(m => m.id === nextModelId);
-            }
-
-            if (modelToSet) {
-              const ok = await pi.setModel(modelToSet, { persist: false });
-              if (ok) {
-                ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
-                // Trigger a generic "Continue execution" to resume the task since the previous attempt failed
-                pi.sendMessage(
-                  { customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false },
-                  { triggerTurn: true }
-                );
-                return;
-              }
-            }
-          }
-        }
-      }
-
-      // ── Session model recovery (#1065) ──────────────────────────────────
-      // Before pausing, attempt to restore the model captured at auto-mode
-      // start. This prevents cross-session model leakage: when fallback
-      // chains are exhausted (or absent), the session retries with the model
-      // the user originally chose instead of reading (possibly stale) global
-      // preferences that another concurrent session may have modified.
-      const sessionModel = getAutoModeStartModel();
-      if (sessionModel) {
-        const currentModelId = ctx.model?.id;
-        const currentProvider = ctx.model?.provider;
-        // Only attempt recovery if the current model diverged from the session model
-        if (currentModelId !== sessionModel.id || currentProvider !== sessionModel.provider) {
-          const availableModels = ctx.modelRegistry.getAvailable();
-          const startModel = availableModels.find(
-            m => m.provider === sessionModel.provider && m.id === sessionModel.id,
-          );
-          if (startModel) {
-            const ok = await pi.setModel(startModel, { persist: false });
-            if (ok) {
-              networkRetryCounters.clear();
-              ctx.ui.notify(
-                `Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`,
-                "warning",
-              );
-              pi.sendMessage(
-                { customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false },
-                { triggerTurn: true },
-              );
-              return;
-            }
-          }
-        }
-      }
-
-      // Classify the error: transient (auto-resume) vs permanent (manual resume)
-      const classification = classifyProviderError(errorMsg);
-
-      // Extract explicit retry-after from the message or response metadata
-      const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number")
-        ? lastMsg.retryAfterMs
-        : undefined;
-      if (classification.isTransient) {
-        consecutiveTransientErrors += 1;
-      } else {
-        consecutiveTransientErrors = 0;
-      }
-      const baseRetryAfterMs = explicitRetryAfterMs ?? classification.suggestedDelayMs;
-      const retryAfterMs = classification.isTransient ? baseRetryAfterMs * 2 ** Math.max(0, consecutiveTransientErrors - 1) : baseRetryAfterMs;
-      const allowAutoResume = classification.isTransient
-        && consecutiveTransientErrors <= MAX_TRANSIENT_AUTO_RESUMES;
-
-      if (classification.isTransient && !allowAutoResume) {
-        ctx.ui.notify(
-          `Transient provider errors persisted after ${MAX_TRANSIENT_AUTO_RESUMES} auto-resume attempts. Pausing for manual review.`,
-          "warning",
-        );
-      }
-
-      await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi), {
-        isRateLimit: classification.isRateLimit,
-        isTransient: allowAutoResume,
-        retryAfterMs,
-        resume: allowAutoResume
-          ? () => {
-            pi.sendMessage(
-              { customType: "gsd-auto-timeout-recovery", content: "Continue execution \u2014 provider error recovery delay elapsed.", display: false },
-              { triggerTurn: true },
-            );
-          }
-          : undefined,
-      });
-      return;
-    }
-
-    try {
-      consecutiveTransientErrors = 0;
-      networkRetryCounters.clear(); // Clear network retry state on successful unit completion
-      resolveAgentEnd(event);
-    } catch (err) {
-      // Safety net: if resolveAgentEnd throws, ensure auto-mode stops gracefully (#381).
-      const message = err instanceof Error ? err.message : String(err);
-      ctx.ui.notify(
-        `Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`,
-        "error",
-      );
-      try {
-        await pauseAuto(ctx, pi);
-      } catch {
-        // Last resort — at least log
-      }
-    }
-  });
-
-  // ── session_before_compact ────────────────────────────────────────────────
-  pi.on("session_before_compact", async (_event, _ctx: ExtensionContext) => {
-    // Block compaction during auto-mode — each unit is a fresh session
-    // Also block during paused state — context is valuable for the user
-    if (isAutoActive() || isAutoPaused()) {
-      return { cancel: true };
-    }
-
-    const basePath = process.cwd();
-    const state = await deriveState(basePath);
-
-    // Only save continue.md if we're actively executing a task
-    if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
-    if (state.phase !== "executing") return;
-
-    const sDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
-    if (!sDir) return;
-
-    // Check for existing continue file (new naming or legacy)
-    const existingFile = resolveSliceFile(basePath, state.activeMilestone.id, state.activeSlice.id, "CONTINUE");
-    if (existingFile && await loadFile(existingFile)) return;
-    const legacyContinue = join(sDir, "continue.md");
-    if (await loadFile(legacyContinue)) return;
-
-    const continuePath = join(sDir, buildSliceFileName(state.activeSlice.id, "CONTINUE"));
-
-    const continueData = {
-      frontmatter: {
-        milestone: state.activeMilestone.id,
-        slice: state.activeSlice.id,
-        task: state.activeTask.id,
-        step: 0,
-        totalSteps: 0,
-        status: "compacted" as const,
-        savedAt: new Date().toISOString(),
-      },
-      completedWork: `Task ${state.activeTask.id} (${state.activeTask.title}) was in progress when compaction occurred.`,
-      remainingWork: "Check the task plan for remaining steps.",
-      decisions: "Check task summary files for prior decisions.",
-      context: "Session was auto-compacted by Pi. Resume with /gsd.",
-      nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
-    };
-
-    await saveFile(continuePath, formatContinue(continueData));
-  });
-
-  // ── session_shutdown: save activity log on Ctrl+C / SIGTERM ─────────────
-  pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
-    if (isParallelActive()) {
-      try {
-        await shutdownParallel(process.cwd());
-      } catch { /* best-effort */ }
-    }
-
-    if (!isAutoActive() && !isAutoPaused()) return;
-
-    // Save the current session — the lock file stays on disk
-    // so the next /gsd auto knows it was interrupted
-    const dash = getAutoDashboardData();
-    if (dash.currentUnit) {
-      saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
-    }
-  });
-
-  // ── tool_call: block CONTEXT.md writes during discussion without depth verification ──
-  pi.on("tool_call", async (event) => {
-    if (!isToolCallEventType("write", event)) return;
-    const result = shouldBlockContextWrite(
-      event.toolName,
-      event.input.path,
-      getDiscussionMilestoneId(),
-      isDepthVerified(),
-      activeQueuePhase,
-    );
-    if (result.block) return result;
-  });
-
-  // ── tool_result: persist discussion exchanges & detect depth gate ──────
-  pi.on("tool_result", async (event) => {
-    if (event.toolName !== "ask_user_questions") return;
-
-    const milestoneId = getDiscussionMilestoneId();
-    if (!milestoneId) return;
-
-    const details = event.details as any;
-    if (details?.cancelled || !details?.response) return;
-
-    // ── Depth gate detection ──────────────────────────────────────────
-    const questions: any[] = (event.input as any)?.questions ?? [];
-    for (const q of questions) {
-      if (typeof q.id === "string" && q.id.includes("depth_verification")) {
-        depthVerificationDone = true;
-        break;
-      }
-    }
-
-    // ── Persist exchange to DISCUSSION.md ──────────────────────────────
-    const basePath = process.cwd();
-    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
-    if (!milestoneDir) return;
-
-    const fileName = buildMilestoneFileName(milestoneId, "DISCUSSION");
-    const discussionPath = join(milestoneDir, fileName);
-    const timestamp = new Date().toISOString();
-
-    // Format exchange as markdown
-    const lines: string[] = [`## Exchange — ${timestamp}`, ""];
-
-    for (const q of questions) {
-      lines.push(`### ${q.header ?? "Question"}`);
-      lines.push("");
-      lines.push(q.question ?? "");
-      if (Array.isArray(q.options)) {
-        lines.push("");
-        for (const opt of q.options) {
-          lines.push(`- **${opt.label}** — ${opt.description ?? ""}`);
-        }
-      }
-
-      // Append user response for this question
-      const answer = details.response?.answers?.[q.id];
-      if (answer) {
-        lines.push("");
-        const selected = Array.isArray(answer.selected) ? answer.selected.join(", ") : answer.selected;
-        lines.push(`**Selected:** ${selected}`);
-        if (answer.notes) {
-          lines.push(`**Notes:** ${answer.notes}`);
-        }
-      }
-      lines.push("");
-    }
-
-    lines.push("---", "");
-
-    const newBlock = lines.join("\n");
-    const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
-    await saveFile(discussionPath, existing + newBlock);
-  });
-
-  // ── tool_execution_start/end: track in-flight tools for idle detection ──
-  pi.on("tool_execution_start", async (event) => {
-    if (!isAutoActive()) return;
-    markToolStart(event.toolCallId);
-  });
-
-  pi.on("tool_execution_end", async (event) => {
-    markToolEnd(event.toolCallId);
-  });
-}
-
-async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
-  const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
-  if (executeMatch) {
-    const [, taskId, taskTitle, sliceId, milestoneId] = executeMatch;
-    return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, taskId, taskTitle);
-  }
-
-  const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
-  if (resumeMatch) {
-    const [, sliceId, milestoneId] = resumeMatch;
-    const state = await deriveState(basePath);
-    if (
-      state.activeMilestone?.id === milestoneId &&
-      state.activeSlice?.id === sliceId &&
-      state.activeTask
-    ) {
-      return buildTaskExecutionContextInjection(
-        basePath,
-        milestoneId,
-        sliceId,
-        state.activeTask.id,
-        state.activeTask.title,
-      );
-    }
-  }
-
-  return null;
-}
-
-async function buildTaskExecutionContextInjection(
-  basePath: string,
-  milestoneId: string,
-  sliceId: string,
-  taskId: string,
-  taskTitle: string,
-): Promise<string> {
-  const taskPlanPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
-  const taskPlanRelPath = relTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
-  const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
-  const taskPlanInline = taskPlanContent
-    ? [
-      "## Inlined Task Plan (authoritative local execution contract)",
-      `Source: \`${taskPlanRelPath}\``,
-      "",
-      taskPlanContent.trim(),
-    ].join("\n")
-    : [
-      "## Inlined Task Plan (authoritative local execution contract)",
-      `Task plan not found at dispatch time. Read \`${taskPlanRelPath}\` before executing.`,
-    ].join("\n");
-
-  const slicePlanPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
-  const slicePlanRelPath = relSliceFile(basePath, milestoneId, sliceId, "PLAN");
-  const slicePlanContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
-  const slicePlanExcerpt = extractSliceExecutionExcerpt(slicePlanContent, slicePlanRelPath);
-
-  const priorTaskLines = await buildCarryForwardLines(basePath, milestoneId, sliceId, taskId);
-  const resumeSection = await buildResumeSection(basePath, milestoneId, sliceId);
-
-  const activeOverrides = await loadActiveOverrides(basePath);
-  const overridesSection = formatOverridesSection(activeOverrides);
-
-  return [
-    "[GSD Guided Execute Context]",
-    "Use this injected context as startup context for guided task execution. Treat the inlined task plan as the authoritative local execution contract. Use source artifacts to verify details and run checks.",
-    overridesSection, "",
-    "",
-    resumeSection,
-    "",
-    "## Carry-Forward Context",
-    ...priorTaskLines,
-    "",
-    taskPlanInline,
-    "",
-    slicePlanExcerpt,
-    "",
-    "## Backing Source Artifacts",
-    `- Slice plan: \`${slicePlanRelPath}\``,
-    `- Task plan source: \`${taskPlanRelPath}\``,
-  ].join("\n");
-}
-
-async function buildCarryForwardLines(
-  basePath: string,
-  milestoneId: string,
-  sliceId: string,
-  taskId: string,
-): Promise<string[]> {
-  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
-  if (!tDir) return ["- No prior task summaries in this slice."];
-
-  const currentNum = parseInt(taskId.replace(/^T/, ""), 10);
-  const sRel = relSlicePath(basePath, milestoneId, sliceId);
-  const summaryFiles = resolveTaskFiles(tDir, "SUMMARY")
-    .filter((file) => parseInt(file.replace(/^T/, ""), 10) < currentNum)
-    .sort();
-
-  if (summaryFiles.length === 0) return ["- No prior task summaries in this slice."];
-
-  const lines = await Promise.all(summaryFiles.map(async (file) => {
-    const absPath = join(tDir, file);
-    const content = await loadFile(absPath);
-    const relPath = `${sRel}/tasks/${file}`;
-    if (!content) return `- \`${relPath}\``;
-
-    const summary = parseSummary(content);
-    const provided = summary.frontmatter.provides.slice(0, 2).join("; ");
-    const decisions = summary.frontmatter.key_decisions.slice(0, 2).join("; ");
-    const patterns = summary.frontmatter.patterns_established.slice(0, 2).join("; ");
-    const diagnostics = extractMarkdownSection(content, "Diagnostics");
-
-    const parts = [summary.title || relPath];
-    if (summary.oneLiner) parts.push(summary.oneLiner);
-    if (provided) parts.push(`provides: ${provided}`);
-    if (decisions) parts.push(`decisions: ${decisions}`);
-    if (patterns) parts.push(`patterns: ${patterns}`);
-    if (diagnostics) parts.push(`diagnostics: ${oneLine(diagnostics)}`);
-
-    return `- \`${relPath}\` — ${parts.join(" | ")}`;
-  }));
-
-  return lines;
-}
-
-async function buildResumeSection(basePath: string, milestoneId: string, sliceId: string): Promise<string> {
-  const continueFile = resolveSliceFile(basePath, milestoneId, sliceId, "CONTINUE");
-  const legacyDir = resolveSlicePath(basePath, milestoneId, sliceId);
-  const legacyPath = legacyDir ? join(legacyDir, "continue.md") : null;
-  const continueContent = continueFile ? await loadFile(continueFile) : null;
-  const legacyContent = !continueContent && legacyPath ? await loadFile(legacyPath) : null;
-  const resolvedContent = continueContent ?? legacyContent;
-  const resolvedRelPath = continueContent
-    ? relSliceFile(basePath, milestoneId, sliceId, "CONTINUE")
-    : (legacyPath ? `${relSlicePath(basePath, milestoneId, sliceId)}/continue.md` : null);
-
-  if (!resolvedContent || !resolvedRelPath) {
-    return ["## Resume State", "- No continue file present. Start from the top of the task plan."].join("\n");
-  }
-
-  const cont = parseContinue(resolvedContent);
-  const lines = [
-    "## Resume State",
-    `Source: \`${resolvedRelPath}\``,
-    `- Status: ${cont.frontmatter.status || "in_progress"}`,
-  ];
-
-  if (cont.frontmatter.step && cont.frontmatter.totalSteps) {
-    lines.push(`- Progress: step ${cont.frontmatter.step} of ${cont.frontmatter.totalSteps}`);
-  }
-  if (cont.completedWork) lines.push(`- Completed: ${oneLine(cont.completedWork)}`);
-  if (cont.remainingWork) lines.push(`- Remaining: ${oneLine(cont.remainingWork)}`);
-  if (cont.decisions) lines.push(`- Decisions: ${oneLine(cont.decisions)}`);
-  if (cont.nextAction) lines.push(`- Next action: ${oneLine(cont.nextAction)}`);
-
-  return lines.join("\n");
-}
-
-function extractSliceExecutionExcerpt(content: string | null, relPath: string): string {
-  if (!content) {
-    return [
-      "## Slice Plan Excerpt",
-      `Slice plan not found at dispatch time. Read \`${relPath}\` before running slice-level verification.`,
-    ].join("\n");
-  }
-
-  const lines = content.split("\n");
-  const goalLine = lines.find((line) => line.startsWith("**Goal:**"))?.trim();
-  const demoLine = lines.find((line) => line.startsWith("**Demo:**"))?.trim();
-  const verification = extractMarkdownSection(content, "Verification");
-  const observability = extractMarkdownSection(content, "Observability / Diagnostics");
-
-  const parts = ["## Slice Plan Excerpt", `Source: \`${relPath}\``];
-  if (goalLine) parts.push(goalLine);
-  if (demoLine) parts.push(demoLine);
-  if (verification) parts.push("", "### Slice Verification", verification.trim());
-  if (observability) parts.push("", "### Slice Observability / Diagnostics", observability.trim());
-  return parts.join("\n");
-}
-
-function extractMarkdownSection(content: string, heading: string): string | null {
-  const match = new RegExp(`^## ${escapeRegExp(heading)}\\s*$`, "m").exec(content);
-  if (!match) return null;
-  const start = match.index + match[0].length;
-  const rest = content.slice(start);
-  const nextHeading = rest.match(/^##\s+/m);
-  const end = nextHeading?.index ?? rest.length;
-  return rest.slice(0, end).trim();
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function oneLine(text: string): string {
-  return text.replace(/\s+/g, " ").trim();
+export default async function registerExtension(pi: ExtensionAPI) {
+  const { registerGsdExtension } = await import("./bootstrap/register-extension.js");
+  registerGsdExtension(pi);
 }
diff --git a/src/resources/extensions/gsd/progress-score.ts b/src/resources/extensions/gsd/progress-score.ts
index 59b71f602..1d1e0f3f9 100644
--- a/src/resources/extensions/gsd/progress-score.ts
+++ b/src/resources/extensions/gsd/progress-score.ts
@@ -14,6 +14,8 @@ import {
   getHealthTrend,
   getConsecutiveErrorUnits,
   getHealthHistory,
+  getLatestHealthIssues,
+  getLatestHealthFixes,
   type HealthSnapshot,
 } from "./doctor-proactive.js";
 
@@ -77,6 +79,27 @@ export function computeProgressScore(): ProgressScore {
     signals.push({ kind: "neutral", label: "No health data yet" });
   }
 
+  // Surface actual doctor issue details when degraded
+  if (level !== "green") {
+    const latestIssues = getLatestHealthIssues();
+    // Show up to 5 most relevant issues (errors first, then warnings)
+    const sorted = [...latestIssues].sort((a, b) => {
+      const rank = { error: 0, warning: 1, info: 2 };
+      return rank[a.severity] - rank[b.severity];
+    });
+    for (const issue of sorted.slice(0, 5)) {
+      signals.push({
+        kind: issue.severity === "error" ? "negative" : "neutral",
+        label: issue.message,
+      });
+    }
+
+    const latestFixes = getLatestHealthFixes();
+    for (const fix of latestFixes.slice(0, 3)) {
+      signals.push({ kind: "positive", label: `Fixed: ${fix}` });
+    }
+  }
+
   const summary = level === "green"
     ? "Progressing well"
     : level === "yellow"
diff --git a/src/resources/extensions/gsd/prompts/forensics.md b/src/resources/extensions/gsd/prompts/forensics.md
index a3922e8e8..71225fcf8 100644
--- a/src/resources/extensions/gsd/prompts/forensics.md
+++ b/src/resources/extensions/gsd/prompts/forensics.md
@@ -1,4 +1,4 @@
-You are investigating a GSD auto-mode failure. The user has described their problem and a structured forensic report has been gathered automatically.
+You are debugging GSD itself. The user is donating their tokens to help find bugs in GSD's source code. Your job is to trace from symptom to root cause in the actual source and produce a filing-ready GitHub issue with specific file:line references and a concrete fix suggestion.
 
 ## User's Problem
 
@@ -10,62 +10,137 @@ You are investigating a GSD auto-mode failure. The user has described their prob
 
 ## GSD Source Location
 
-GSD extension source code is at: {{gsdSourceDir}}
-Key files for understanding failures:
-- auto.ts — unit dispatch loop, stuck detection, timeout recovery
-- session-forensics.ts — trace extraction from activity logs
-- auto-recovery.ts — artifact verification, skip logic
-- crash-recovery.ts — crash lock lifecycle
-- doctor.ts — state integrity checks
+GSD extension source code is at: `{{gsdSourceDir}}`
 
-You may read these files to identify the specific code path that caused the failure.
+### Source Map by Domain
 
-## Your Task
+| Domain | Files |
+|--------|-------|
+| **Auto-mode engine** | `auto.ts` `auto-loop.ts` `auto-dispatch.ts` `auto-start.ts` `auto-supervisor.ts` `auto-timers.ts` `auto-timeout-recovery.ts` `auto-unit-closeout.ts` `auto-post-unit.ts` `auto-verification.ts` `auto-recovery.ts` `auto-worktree.ts` `auto-worktree-sync.ts` `auto-model-selection.ts` `auto-budget.ts` `dispatch-guard.ts` |
+| **State & persistence** | `state.ts` `types.ts` `files.ts` `paths.ts` `json-persistence.ts` `atomic-write.ts` |
+| **Forensics & recovery** | `forensics.ts` `session-forensics.ts` `crash-recovery.ts` `session-lock.ts` |
+| **Metrics & telemetry** | `metrics.ts` `skill-telemetry.ts` `token-counter.ts` |
+| **Health & diagnostics** | `doctor.ts` `doctor-types.ts` `doctor-checks.ts` `doctor-format.ts` `doctor-environment.ts` |
+| **Prompts & context** | `prompt-loader.ts` `prompt-cache-optimizer.ts` `context-budget.ts` |
+| **Git & worktrees** | `git-service.ts` `worktree.ts` `worktree-manager.ts` `git-self-heal.ts` |
+| **Commands** | `commands.ts` `commands-inspect.ts` `commands-maintenance.ts` |
 
-1. **Analyze** the forensic report. Identify the root cause of the user's problem.
+### Runtime Path Reference
 
-2. **Clarify** if needed. Use ask_user_questions (max 2 questions) to narrow down ambiguity. Only ask if the report is genuinely insufficient — do not ask questions you can answer from the data.
+```
+.gsd/
+├── PROJECT.md, DECISIONS.md, QUEUE.md, STATE.md, REQUIREMENTS.md, OVERRIDES.md, KNOWLEDGE.md, RUNTIME.md
+├── auto.lock                    — crash lock (JSON: pid, unitType, unitId, sessionFile)
+├── metrics.json                 — token/cost ledger (units array with cost, tokens, duration)
+├── completed-units.json         — array of "type/id" strings
+├── doctor-history.jsonl         — doctor check history
+├── activity/                    — session activity logs (JSONL per unit)
+│   └── {seq}-{unitType}-{unitId}.jsonl
+├── runtime/
+│   ├── paused-session.json      — serialized session when auto pauses
+│   └── headless-context.md      — headless resume context
+├── debug/                       — debug logs
+├── forensics/                   — saved forensic reports
+├── milestones/{ID}/             — milestone artifacts
+│   ├── {ID}-ROADMAP.md, {ID}-RESEARCH.md, {ID}-CONTEXT.md, {ID}-SUMMARY.md
+│   └── slices/{SID}/            — slice artifacts
+│       ├── {SID}-PLAN.md, {SID}-RESEARCH.md, {SID}-UAT-RESULT.md, {SID}-SUMMARY.md
+│       └── tasks/{TID}-PLAN.md, {TID}-SUMMARY.md
+└── worktrees/{milestoneId}/     — per-milestone worktree with replicated .gsd/
+```
 
-3. **Explain** your findings clearly:
-   - What happened (the failure sequence)
-   - Why it happened (root cause in GSD's logic)
-   - What the user can do to recover (immediate fix)
+### Activity Log Format
 
-4. **Offer GitHub issue creation.** Ask the user:
-   "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?"
+- **Filename**: `{3-digit-seq}-{unitType}-{unitId}.jsonl`
+- Each line is a JSON object with `type: "message"` and a `message` field
+- `message.role: "assistant"` — contains `content[]` array:
+  - `type: "text"` entries hold the agent's reasoning
+  - `type: "toolCall"` entries hold tool invocations (`name`, `id`, `arguments`)
+- `message.role: "toolResult"` — contains `toolCallId`, `toolName`, `isError`, `content`
+- `usage` field on assistant messages: `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, `cost`
+- **To trace a failure**: find the last activity log, search for `isError: true` tool results, then read the agent's reasoning text preceding that error
 
-   If yes, create the issue using bash with `gh issue create`:
-   - Repository: gsd-build/gsd-2
-   - Labels: bug, auto-generated
-   - Title: concise description of the failure
-   - Body format:
-     ```
-     ## Problem
-     [1-2 sentence summary]
+### Crash Lock Format (`auto.lock`)
 
-     ## Environment
-     - GSD version: [from report]
-     - Model: [from report]
-     - Unit: [type/id that failed]
+JSON with fields: `pid`, `startedAt`, `unitType`, `unitId`, `unitStartedAt`, `completedUnits`, `sessionFile`
 
-     ## Reproduction Context
-     [What was happening when it failed — phase, milestone, slice]
+A stale lock (PID is dead) means the previous auto-mode session crashed mid-unit.
 
-     ## Forensic Findings
-     [Key anomalies detected, error traces, relevant tool call sequences]
+### Metrics Ledger Format (`metrics.json`)
 
-     ## Suggested Fix Area
-     [File:line references in GSD source if identified]
+```
+{ version: 1, projectStartedAt: <ms>, units: [{ type, id, model, startedAt, finishedAt, tokens: { input, output, cacheRead, cacheWrite, total }, cost, toolCalls, assistantMessages, ... }] }
+```
 
-     ---
-     *Auto-generated by `/gsd forensics`*
-     ```
+A unit dispatched more than once (`type/id` appears multiple times) indicates a stuck loop — the unit completed but artifact verification failed.
 
-   **CRITICAL REDACTION RULES** before creating the issue:
-   - Replace all absolute paths with relative paths
-   - Remove any API keys, tokens, or credentials
-   - Remove any environment variable values
-   - Do not include file content (code written by the user)
-   - Only include GSD structural information (tool names, file names, error messages)
+## Investigation Protocol
 
-5. **Report saved.** Remind the user that the full forensic report was saved locally (the path will be in the notification).
+1. **Start with the pre-parsed forensic report** above. The anomaly section contains automated findings — treat these as leads, not conclusions.
+
+2. **Form hypotheses** about which module and code path is responsible. Use the source map to identify candidate files.
+
+3. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
+
+4. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
+
+5. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:
+   - Missing edge case / unhandled condition
+   - Wrong boolean logic or comparison
+   - Race condition or ordering issue
+   - State corruption (e.g. completed-units.json out of sync with artifacts)
+   - Timeout / recovery logic not triggering correctly
+
+6. **Clarify if needed.** Use ask_user_questions (max 2 questions) only if the report is genuinely insufficient. Do not ask questions you can answer from the data or source code.
+
+## Output
+
+Explain your findings:
+- **What happened** — the failure sequence reconstructed from activity logs and anomalies
+- **Why it happened** — root cause traced to specific code in GSD source, with `file:line` references
+- **Code snippet** — the problematic code and what it should do instead
+- **Recovery** — what the user can do right now to get unstuck
+
+Then **offer GitHub issue creation**: "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?"
+
+If yes, create using `gh issue create` with this format:
+
+```
+## Problem
+[1-2 sentence summary]
+
+## Root Cause
+[Specific file:line in GSD source, with code snippet showing the bug]
+
+## Expected Behavior
+[What the code should do instead — concrete fix suggestion]
+
+## Environment
+- GSD version: [from report]
+- Model: [from report]
+- Unit: [type/id that failed]
+
+## Reproduction Context
+[Phase, milestone, slice, what was happening when it failed]
+
+## Forensic Evidence
+[Key anomalies, error traces, relevant tool call sequences from the report]
+
+---
+*Auto-generated by `/gsd forensics`*
+```
+
+**Repository:** gsd-build/gsd-2
+**Labels:** bug, auto-generated
+
+### Redaction Rules (CRITICAL)
+
+Before creating the issue, you MUST:
+- Replace all absolute paths with relative paths
+- Remove any API keys, tokens, or credentials
+- Remove any environment variable values
+- Do not include user's project code — only GSD structural information (tool names, file names, error messages)
+
+## Report Saved
+
+Remind the user that the full forensic report was saved locally (the path will be in the notification).
diff --git a/src/resources/extensions/gsd/tests/auto-loop.test.ts b/src/resources/extensions/gsd/tests/auto-loop.test.ts
index e51fb40fa..d1070021d 100644
--- a/src/resources/extensions/gsd/tests/auto-loop.test.ts
+++ b/src/resources/extensions/gsd/tests/auto-loop.test.ts
@@ -962,21 +962,25 @@ test("auto.ts startAuto calls autoLoop (not dispatchNextUnit as first dispatch)"
   );
 });
 
-test("index.ts agent_end handler calls resolveAgentEnd (not handleAgentEnd)", () => {
-  const src = readFileSync(
-    resolve(import.meta.dirname, "..", "index.ts"),
+test("agent_end handler calls resolveAgentEnd (not handleAgentEnd)", () => {
+  const hooksSrc = readFileSync(
+    resolve(import.meta.dirname, "..", "bootstrap", "register-hooks.ts"),
+    "utf-8",
+  );
+  // Verify the agent_end hook is registered
+  const handlerIdx = hooksSrc.indexOf('pi.on("agent_end"');
+  assert.ok(handlerIdx > -1, "register-hooks.ts must have an agent_end handler");
+
+  const recoverySrc = readFileSync(
+    resolve(import.meta.dirname, "..", "bootstrap", "agent-end-recovery.ts"),
     "utf-8",
   );
-  // Find the agent_end handler success path
-  const handlerIdx = src.indexOf('pi.on("agent_end"');
-  assert.ok(handlerIdx > -1, "index.ts must have an agent_end handler");
-  const handlerBlock = src.slice(handlerIdx, handlerIdx + 10000);
   assert.ok(
-    handlerBlock.includes("resolveAgentEnd(event)"),
+    recoverySrc.includes("resolveAgentEnd(event)"),
     "agent_end success path must call resolveAgentEnd(event) instead of handleAgentEnd(ctx, pi)",
   );
   assert.ok(
-    handlerBlock.includes("isSessionSwitchInFlight()"),
+    recoverySrc.includes("isSessionSwitchInFlight()"),
     "agent_end handler must ignore session-switch agent_end events from cmdCtx.newSession()",
   );
 });
diff --git a/src/resources/extensions/gsd/tests/doctor-proactive.test.ts b/src/resources/extensions/gsd/tests/doctor-proactive.test.ts
index 0bbbf2a83..f45f6a75e 100644
--- a/src/resources/extensions/gsd/tests/doctor-proactive.test.ts
+++ b/src/resources/extensions/gsd/tests/doctor-proactive.test.ts
@@ -176,9 +176,9 @@ async function main(): Promise<void> {
 
       recordHealthSnapshot(2, 3, 1);
       const summary = formatHealthSummary();
-      assertTrue(summary.includes("2E/3W"), "summary includes error/warning counts");
-      assertTrue(summary.includes("fixes:1"), "summary includes fix count");
-      assertTrue(summary.includes("streak:1/5"), "summary includes error streak");
+      assertTrue(summary.includes("2 errors") && summary.includes("3 warnings"), "summary includes error/warning counts");
+      assertTrue(summary.includes("1 fix applied"), "summary includes fix count");
+      assertTrue(summary.includes("1 of 5 consecutive errors"), "summary includes error streak");
     }
 
     // ─── Pre-Dispatch Health Gate ─────────────────────────────────────
diff --git a/src/resources/extensions/gsd/tests/provider-errors.test.ts b/src/resources/extensions/gsd/tests/provider-errors.test.ts
index 35a7dd9ff..0512b4d90 100644
--- a/src/resources/extensions/gsd/tests/provider-errors.test.ts
+++ b/src/resources/extensions/gsd/tests/provider-errors.test.ts
@@ -261,38 +261,38 @@ test("pauseAutoForProviderError falls back to indefinite pause when not rate lim
 
 // ── Escalating backoff for transient errors (#1166) ─────────────────────────
 
-test("index.ts tracks consecutive transient errors for escalating backoff", () => {
-  const indexSource = readFileSync(join(__dirname, "..", "index.ts"), "utf-8");
+test("agent-end-recovery.ts tracks consecutive transient errors for escalating backoff", () => {
+  const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
 
   assert.ok(
-    indexSource.includes("consecutiveTransientErrors"),
-    "index.ts must track consecutiveTransientErrors for escalating backoff (#1166)",
+    src.includes("consecutiveTransientErrors"),
+    "agent-end-recovery.ts must track consecutiveTransientErrors for escalating backoff (#1166)",
   );
   assert.ok(
-    indexSource.includes("MAX_TRANSIENT_AUTO_RESUMES"),
-    "index.ts must define MAX_TRANSIENT_AUTO_RESUMES to cap infinite retries (#1166)",
+    src.includes("MAX_TRANSIENT_AUTO_RESUMES"),
+    "agent-end-recovery.ts must define MAX_TRANSIENT_AUTO_RESUMES to cap infinite retries (#1166)",
   );
 });
 
-test("index.ts resets consecutive transient error counter on success", () => {
-  const indexSource = readFileSync(join(__dirname, "..", "index.ts"), "utf-8");
+test("agent-end-recovery.ts resets consecutive transient error counter on success", () => {
+  const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
 
-  // After successful unit completion, the counter must be reset.
+  // After successful agent_end (before resolveAgentEnd), the counter must be reset.
   // Use a regex across the success block so CRLF checkouts on Windows do not
   // push the reset line outside a fixed substring window.
   assert.ok(
-    /consecutiveTransientErrors\s*=\s*0\s*;[\s\S]{0,250}successful unit completion/.test(indexSource),
-    "consecutive transient error counter must be reset on successful unit completion (#1166)",
+    /consecutiveTransientErrors\s*=\s*0\s*;[\s\S]{0,250}resolveAgentEnd/.test(src),
+    "consecutive transient error counter must be reset before resolveAgentEnd on the success path (#1166)",
   );
 });
 
-test("index.ts applies escalating delay for repeated transient errors", () => {
-  const indexSource = readFileSync(join(__dirname, "..", "index.ts"), "utf-8");
+test("agent-end-recovery.ts applies escalating delay for repeated transient errors", () => {
+  const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
 
-  // Must contain the exponential backoff formula
+  // Must contain the exponential backoff formula (may span multiple lines)
   assert.ok(
-    /retryAfterMs\s*[=*].*2\s*\*\*/.test(indexSource),
-    "index.ts must escalate retryAfterMs exponentially for consecutive transient errors (#1166)",
+    src.includes("2 ** Math.max(0, consecutiveTransientErrors"),
+    "agent-end-recovery.ts must escalate retryAfterMs exponentially for consecutive transient errors (#1166)",
   );
 });
 
diff --git a/src/resources/extensions/gsd/tests/skill-activation.test.ts b/src/resources/extensions/gsd/tests/skill-activation.test.ts
index 23df394ca..e2c6c7be0 100644
--- a/src/resources/extensions/gsd/tests/skill-activation.test.ts
+++ b/src/resources/extensions/gsd/tests/skill-activation.test.ts
@@ -60,17 +60,17 @@ test("buildSkillActivationBlock matches installed skills from task context", ()
   }
 });
 
-test("buildSkillActivationBlock includes always_use_skills from preferences", () => {
+test("buildSkillActivationBlock includes always_use_skills from preferences using exact Skill tool format", () => {
   const base = makeTempBase();
   try {
-    writeSkill(base, "testing", "Use for test setup, assertions, and verification patterns.");
+    writeSkill(base, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
     loadOnlyTestSkills(base);
 
     const result = buildBlock(base, { taskTitle: "Unrelated task title" }, {
-      always_use_skills: ["testing"],
+      always_use_skills: ["swift-testing"],
     });
 
-    assert.match(result, /Call Skill\('testing'\)/);
+    assert.equal(result, "<skill_activation>Call Skill('swift-testing').</skill_activation>");
   } finally {
     cleanup(base);
   }
diff --git a/src/resources/extensions/gsd/tests/visualizer-data.test.ts b/src/resources/extensions/gsd/tests/visualizer-data.test.ts
index 06ce5a89b..9f9548169 100644
--- a/src/resources/extensions/gsd/tests/visualizer-data.test.ts
+++ b/src/resources/extensions/gsd/tests/visualizer-data.test.ts
@@ -422,25 +422,25 @@ assertTrue(
   "overlay has 10 tab labels",
 );
 
-// Verify commands.ts integration
-const commandsPath = join(__dirname, "..", "commands.ts");
-const commandsSrc = readFileSync(commandsPath, "utf-8");
+// Verify commands/handlers/core.ts integration
+const coreHandlerPath = join(__dirname, "..", "commands", "handlers", "core.ts");
+const coreHandlerSrc = readFileSync(coreHandlerPath, "utf-8");
 
-console.log("\n=== commands.ts integration ===");
+console.log("\n=== commands/handlers/core.ts integration ===");
 
 assertTrue(
-  commandsSrc.includes('"visualize"'),
-  "commands.ts has visualize in subcommands array",
+  coreHandlerSrc.includes('"visualize"'),
+  "core.ts has visualize in subcommands array",
 );
 
 assertTrue(
-  commandsSrc.includes("GSDVisualizerOverlay"),
-  "commands.ts imports GSDVisualizerOverlay",
+  coreHandlerSrc.includes("GSDVisualizerOverlay"),
+  "core.ts imports GSDVisualizerOverlay",
 );
 
 assertTrue(
-  commandsSrc.includes("handleVisualize"),
-  "commands.ts has handleVisualize handler",
+  coreHandlerSrc.includes("handleVisualize"),
+  "core.ts has handleVisualize handler",
 );
 
 report();
diff --git a/src/resources/extensions/gsd/visualizer-data.ts b/src/resources/extensions/gsd/visualizer-data.ts
index b06fe92d2..b196b7efa 100644
--- a/src/resources/extensions/gsd/visualizer-data.ts
+++ b/src/resources/extensions/gsd/visualizer-data.ts
@@ -1,10 +1,11 @@
 // Data loader for workflow visualizer overlay — aggregates state + metrics.
 
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { deriveState } from './state.js';
 import { parseRoadmap, parsePlan, parseSummary, loadFile } from './files.js';
 import { findMilestoneIds } from './milestone-ids.js';
-import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile } from './paths.js';
+import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile, gsdRoot } from './paths.js';
 import {
   getLedger,
   getProjectTotals,
@@ -21,6 +22,8 @@ import { loadEffectiveGSDPreferences } from './preferences.js';
 import { runProviderChecks, type ProviderCheckResult } from './doctor-providers.js';
 import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks, type EnvironmentCheckResult } from './doctor-environment.js';
+import { computeProgressScore } from './progress-score.js';
+import { getHealthHistory } from './doctor-proactive.js';
 
 import type { Phase } from './types.js';
 import type { CaptureEntry } from './captures.js';
@@ -161,6 +164,27 @@ export interface SkillSummaryInfo {
   topIssue: string | null;
 }
 
+/** A single doctor history entry for visualizer display. */
+export interface VisualizerDoctorEntry {
+  ts: string;
+  ok: boolean;
+  errors: number;
+  warnings: number;
+  fixes: number;
+  codes: string[];
+  issues?: Array<{ severity: string; code: string; message: string; unitId: string }>;
+  fixDescriptions?: string[];
+  scope?: string;
+  summary?: string;
+}
+
+/** Current progress score snapshot for health display. */
+export interface VisualizerProgressScore {
+  level: "green" | "yellow" | "red";
+  summary: string;
+  signals: Array<{ kind: "positive" | "negative" | "neutral"; label: string }>;
+}
+
 export interface HealthInfo {
   budgetCeiling: number | undefined;
   tokenProfile: string;
@@ -174,6 +198,10 @@ export interface HealthInfo {
   providers: ProviderStatusSummary[];
   skillSummary: SkillSummaryInfo;
   environmentIssues: import("./doctor-environment.js").EnvironmentCheckResult[];
+  /** Persisted doctor run history (most recent first, up to 20 entries). */
+  doctorHistory?: VisualizerDoctorEntry[];
+  /** Current in-memory progress score (null if auto-mode not active). */
+  progressScore?: VisualizerProgressScore | null;
 }
 
 export interface VisualizerData {
@@ -608,6 +636,26 @@ function loadHealth(units: UnitMetrics[], totals: ProjectTotals | null, basePath
     environmentIssues = runEnvironmentChecks(basePath).filter(r => r.status !== "ok");
   } catch { /* non-fatal */ }
 
+  // Doctor run history — persisted across sessions (sync read to keep loadHealth sync)
+  let doctorHistory: VisualizerDoctorEntry[] = [];
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    if (existsSync(historyPath)) {
+      const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+      doctorHistory = lines.slice(-20).reverse().map(l => JSON.parse(l) as VisualizerDoctorEntry);
+    }
+  } catch { /* non-fatal */ }
+
+  // Current progress score — only meaningful when auto-mode has health data
+  let progressScore: VisualizerProgressScore | null = null;
+  try {
+    const history = getHealthHistory();
+    if (history.length > 0) {
+      const score = computeProgressScore();
+      progressScore = { level: score.level, summary: score.summary, signals: score.signals };
+    }
+  } catch { /* non-fatal */ }
+
   return {
     budgetCeiling,
     tokenProfile,
@@ -621,6 +669,8 @@ function loadHealth(units: UnitMetrics[], totals: ProjectTotals | null, basePath
     providers,
     skillSummary,
     environmentIssues,
+    doctorHistory,
+    progressScore,
   };
 }
 
diff --git a/src/resources/extensions/gsd/visualizer-views.ts b/src/resources/extensions/gsd/visualizer-views.ts
index 30e459390..44de80d41 100644
--- a/src/resources/extensions/gsd/visualizer-views.ts
+++ b/src/resources/extensions/gsd/visualizer-views.ts
@@ -1150,6 +1150,64 @@ export function renderHealthView(
     }
   }
 
+  // Progress score section — current traffic light status
+  if (health.progressScore) {
+    lines.push("");
+    lines.push(th.fg("accent", th.bold("Progress Score")));
+    lines.push("");
+    const ps = health.progressScore;
+    const scoreColor = ps.level === "green" ? "success" : ps.level === "yellow" ? "warning" : "error";
+    const scoreIcon = ps.level === "green" ? "●" : ps.level === "yellow" ? "◐" : "○";
+    lines.push(`  ${th.fg(scoreColor, scoreIcon)} ${th.fg(scoreColor, ps.summary)}`);
+    for (const signal of ps.signals) {
+      const prefix = signal.kind === "positive" ? th.fg("success", "  ✓")
+        : signal.kind === "negative" ? th.fg("error", "  ✗")
+          : th.fg("dim", "  ·");
+      lines.push(`  ${prefix} ${th.fg("dim", signal.label)}`);
+    }
+  }
+
+  // Doctor history section — persisted across sessions
+  const doctorHistory = health.doctorHistory ?? [];
+  if (doctorHistory.length > 0) {
+    lines.push("");
+    lines.push(th.fg("accent", th.bold("Doctor History")));
+    lines.push("");
+
+    for (const entry of doctorHistory.slice(0, 10)) {
+      const icon = entry.ok ? th.fg("success", "✓") : th.fg("error", "✗");
+      const ts = entry.ts.replace("T", " ").slice(0, 19);
+      const scopeTag = entry.scope ? th.fg("accent", ` [${entry.scope}]`) : "";
+      // Prefer human-readable summary, fall back to counts
+      const detail = entry.summary
+        ? th.fg("text", entry.summary)
+        : th.fg("text", `${entry.errors} errors, ${entry.warnings} warnings, ${entry.fixes} fixes`);
+      lines.push(`  ${icon} ${th.fg("dim", ts)}${scopeTag}  ${detail}`);
+
+      // Show issue details if available
+      if (entry.issues && entry.issues.length > 0) {
+        for (const issue of entry.issues.slice(0, 3)) {
+          const issuePfx = issue.severity === "error" ? th.fg("error", "    ✗") : th.fg("warning", "    ⚠");
+          lines.push(`  ${issuePfx} ${th.fg("dim", truncateToWidth(issue.message, width - 12))}`);
+        }
+        if (entry.issues.length > 3) {
+          lines.push(`    ${th.fg("dim", `+${entry.issues.length - 3} more`)}`);
+        }
+      }
+
+      // Show fixes if available
+      if (entry.fixDescriptions && entry.fixDescriptions.length > 0) {
+        for (const fix of entry.fixDescriptions.slice(0, 2)) {
+          lines.push(`    ${th.fg("success", "↳")} ${th.fg("dim", truncateToWidth(fix, width - 12))}`);
+        }
+      }
+    }
+
+    if (doctorHistory.length > 10) {
+      lines.push(`  ${th.fg("dim", `...${doctorHistory.length - 10} older entries`)}`);
+    }
+  }
+
   // Skills section
   if (health.skillSummary?.total > 0) {
     lines.push("");
diff --git a/src/welcome-screen.ts b/src/welcome-screen.ts
index 4d4b13772..7b8d37773 100644
--- a/src/welcome-screen.ts
+++ b/src/welcome-screen.ts
@@ -1,8 +1,9 @@
 /**
  * GSD Welcome Screen
  *
- * Rendered to stderr before the TUI takes over.
- * No box, no panels — logo with metadata alongside, dim hint below.
+ * Two-panel bar layout: full-width accent bars at top/bottom (matching the
+ * auto-mode progress widget style), logo left (fixed width), info right.
+ * Falls back to simple text on narrow terminals (<70 cols) or non-TTY.
  */
 
 import os from 'node:os'
@@ -21,44 +22,95 @@ function getShortCwd(): string {
   return cwd.startsWith(home) ? '~' + cwd.slice(home.length) : cwd
 }
 
+/** Visible length — strips ANSI escape codes before measuring. */
+function visLen(s: string): number {
+  return s.replace(/\x1b\[[0-9;]*m/g, '').length
+}
+
+/** Right-pad a string to the given visible width. */
+function rpad(s: string, w: number): string {
+  return s + ' '.repeat(Math.max(0, w - visLen(s)))
+}
+
 export function printWelcomeScreen(opts: WelcomeScreenOptions): void {
   if (!process.stderr.isTTY) return
 
   const { version, modelName, provider } = opts
   const shortCwd = getShortCwd()
+  const termWidth = Math.min((process.stderr.columns || 80) - 1, 200)
 
-  // Info lines to sit alongside the logo (one per logo row)
-  const modelLine = [modelName, provider].filter(Boolean).join('  ·  ')
-  const INFO: (string | undefined)[] = [
-    `  ${chalk.bold('Get Shit Done')}  ${chalk.dim('v' + version)}`,
-    undefined,
-    modelLine ? `  ${chalk.dim(modelLine)}` : undefined,
-    `  ${chalk.dim(shortCwd)}`,
-    undefined,
-    undefined,
-  ]
-
-  const lines: string[] = ['']
-  for (let i = 0; i < GSD_LOGO.length; i++) {
-    lines.push(chalk.cyan(GSD_LOGO[i]) + (INFO[i] ?? ''))
+  // Narrow terminal fallback
+  if (termWidth < 70) {
+    process.stderr.write(`\n  Get Shit Done v${version}\n  ${shortCwd}\n\n`)
+    return
   }
 
-  // Tool status + hint — dim, aligned under the info text
-  const pad = ' '.repeat(28) + '  '  // aligns with the info text column
+  // ── Panel widths ────────────────────────────────────────────────────────────
+  // Layout: 1 leading space + LEFT_INNER logo content + 1 inner divider + RIGHT_INNER info
+  // Total: 1 + LEFT_INNER + 1 + RIGHT_INNER = termWidth
+  const LEFT_INNER = 34
+  const RIGHT_INNER = termWidth - LEFT_INNER - 2  // 2 = leading space + inner divider
+
+  // ── Bar/divider chars (matching GLYPH.separator + widget ui.bar() style) ────
+  const H = '─', DV = '│', DS = '├'
+
+  // ── Left rows: blank + 6 logo lines + blank (8 total) ───────────────────────
+  const leftRows = ['', ...GSD_LOGO, '']
+
+  // ── Right rows (8 total, null = divider) ────────────────────────────────────
+  const titleLeft  = `  ${chalk.bold('Get Shit Done')}`
+  const titleRight = chalk.dim(`v${version}`)
+  const titleFill  = RIGHT_INNER - visLen(titleLeft) - visLen(titleRight)
+  const titleRow   = titleLeft + ' '.repeat(Math.max(1, titleFill)) + titleRight
 
   const toolParts: string[] = []
-  if (process.env.BRAVE_API_KEY)    toolParts.push('Brave ✓')
-  if (process.env.BRAVE_ANSWERS_KEY) toolParts.push('Answers ✓')
-  if (process.env.JINA_API_KEY)     toolParts.push('Jina ✓')
-  if (process.env.TAVILY_API_KEY)   toolParts.push('Tavily ✓')
-  if (process.env.CONTEXT7_API_KEY) toolParts.push('Context7 ✓')
+  if (process.env.BRAVE_API_KEY)      toolParts.push('Brave ✓')
+  if (process.env.BRAVE_ANSWERS_KEY)  toolParts.push('Answers ✓')
+  if (process.env.JINA_API_KEY)       toolParts.push('Jina ✓')
+  if (process.env.TAVILY_API_KEY)     toolParts.push('Tavily ✓')
+  if (process.env.CONTEXT7_API_KEY)   toolParts.push('Context7 ✓')
 
-  if (toolParts.length > 0) {
-    lines.push(chalk.dim(pad + ['Web search loaded', ...toolParts].join('  ·  ')))
+  // Tools left, hint right-aligned on the same row
+  const toolsLeft  = toolParts.length > 0 ? chalk.dim('  ' + toolParts.join('  ·  ')) : ''
+  const hintRight  = chalk.dim('/gsd to begin  ·  /gsd help')
+  const footerFill = RIGHT_INNER - visLen(toolsLeft) - visLen(hintRight)
+  const footerRow  = toolsLeft + ' '.repeat(Math.max(1, footerFill)) + hintRight
+
+  const DIVIDER = null
+  const rightRows: (string | null)[] = [
+    titleRow,
+    DIVIDER,
+    modelName ? `  Model      ${chalk.dim(modelName)}`  : '',
+    provider  ? `  Provider   ${chalk.dim(provider)}`   : '',
+    `  Directory  ${chalk.dim(shortCwd)}`,
+    DIVIDER,
+    footerRow,
+    '',
+  ]
+
+  // ── Render ──────────────────────────────────────────────────────────────────
+  const out: string[] = ['']
+
+  // Top bar — full-width accent separator, matches auto-mode widget ui.bar()
+  out.push(chalk.cyan(H.repeat(termWidth)))
+
+  for (let i = 0; i < 8; i++) {
+    const row      = leftRows[i] ?? ''
+    const lContent = rpad(row ? chalk.cyan(row) : '', LEFT_INNER)
+    const rRow     = rightRows[i]
+
+    if (rRow === null) {
+      // Section divider: left logo area + dim ├────... extending right
+      out.push(' ' + lContent + chalk.dim(DS + H.repeat(RIGHT_INNER)))
+    } else {
+      // Content row: 1 space + logo │ info (no outer vertical borders)
+      out.push(' ' + lContent + chalk.dim(DV) + rpad(rRow, RIGHT_INNER))
+    }
   }
 
-  lines.push(chalk.dim(pad + '/gsd to begin  ·  /gsd help for all commands'))
-  lines.push('')
+  // Bottom bar — full-width accent separator
+  out.push(chalk.cyan(H.repeat(termWidth)))
+  out.push('')
 
-  process.stderr.write(lines.join('\n') + '\n')
+  process.stderr.write(out.join('\n') + '\n')
 }