gsd-pi 2.75.0-next.9c0ec0ba1 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/ask-user-questions.ts

@@ -37,7 +37,7 @@ interface RemoteResultDetails {
 	threadUrl?: string;
 	status?: string;
 	questions?: Question[];
-	response?: import("./remote-questions/types.js").RemoteAnswer;
+	response?: RoundResult;
 	error?: boolean;
 }
 
@@ -435,10 +435,13 @@ export default function AskUserQuestions(pi: ExtensionAPI) {
 							lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
 							continue;
 						}
-						const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
+						const selected = answer.selected;
+						const answerText = Array.isArray(selected)
+							? (selected.length > 0 ? selected.join(", ") : "(custom)")
+							: (selected || "(custom)");
 						let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-						if (answer.user_note) {
-							line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
+						if (answer.notes) {
+							line += ` ${theme.fg("muted", `[note: ${answer.notes}]`)}`;
 						}
 						lines.push(line);
 					}

package/src/resources/extensions/claude-code-cli/readiness.ts

@@ -11,6 +11,40 @@
 
 import { execFileSync } from "node:child_process";
 
+/**
+ * Candidate executable names for the Claude Code CLI.
+ *
+ * Keep the explicit win32 ternary selector for regression coverage (Issue #4424):
+ * Node's execFileSync must target `claude.cmd` directly on Windows.
+ */
+const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
+
+/**
+ * Windows installs vary: some environments expose `claude.cmd` (npm shim),
+ * others expose a `claude` shim on PATH (for example Git Bash wrappers).
+ * Try both to avoid false "not installed" results in readiness checks.
+ */
+const CLAUDE_COMMAND_CANDIDATES = process.platform === "win32" ? [CLAUDE_COMMAND, "claude"] : [CLAUDE_COMMAND];
+
+function execClaude(args: string[]): Buffer {
+	let lastError: unknown;
+	for (const command of CLAUDE_COMMAND_CANDIDATES) {
+		try {
+			return execFileSync(command, args, { timeout: 5_000, stdio: "pipe" });
+		} catch (error) {
+			lastError = error;
+			const code = (error as NodeJS.ErrnoException | undefined)?.code;
+			// Windows Git Bash can surface `.cmd` spawn failures as EINVAL instead
+			// of ENOENT. Treat both as "try next candidate".
+			if (code === "ENOENT" || code === "EINVAL") {
+				continue;
+			}
+			throw error;
+		}
+	}
+	throw lastError ?? new Error(`Claude CLI executable not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(", ")})`);
+}
+
 let cachedBinaryPresent: boolean | null = null;
 let cachedAuthed: boolean | null = null;
 let lastCheckMs = 0;
@@ -27,7 +61,7 @@ function refreshCache(): void {
 
 	// Check binary presence
 	try {
-		execFileSync("claude", ["--version"], { timeout: 5_000, stdio: "pipe" });
+		execClaude(["--version"]);
 		cachedBinaryPresent = true;
 	} catch {
 		cachedBinaryPresent = false;
@@ -37,7 +71,7 @@ function refreshCache(): void {
 
 	// Check auth status — exit code 0 with non-error output means authenticated
 	try {
-		const output = execFileSync("claude", ["auth", "status"], { timeout: 5_000, stdio: "pipe" })
+		const output = execClaude(["auth", "status"])
 			.toString()
 			.toLowerCase();
 		// The CLI outputs "not logged in", "no credentials", or similar when unauthenticated

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

@@ -31,6 +31,7 @@ import type {
 	SDKUserMessage,
 } from "./sdk-types.js";
 
+/** A single content block returned by an external (SDK-executed) tool call. */
 export interface ExternalToolResultContentBlock {
 	type: string;
 	text?: string;
@@ -38,25 +39,30 @@ export interface ExternalToolResultContentBlock {
 	mimeType?: string;
 }
 
+/** The full result payload returned by an external tool, including content blocks and error status. */
 export interface ExternalToolResultPayload {
 	content: ExternalToolResultContentBlock[];
 	details?: Record<string, unknown>;
 	isError: boolean;
 }
 
+/** A `ToolCall` block augmented with the external result attached by the SDK synthetic user message. */
 type ToolCallWithExternalResult = ToolCall & {
 	externalResult?: ExternalToolResultPayload;
 };
 
+/** `SimpleStreamOptions` extended with an optional extension UI context for elicitation dialogs. */
 interface ClaudeCodeStreamOptions extends SimpleStreamOptions {
 	extensionUIContext?: ExtensionUIContext;
 }
 
+/** A single selectable option within an SDK elicitation schema field. */
 interface SdkElicitationRequestOption {
 	const?: string;
 	title?: string;
 }
 
+/** JSON-Schema-like descriptor for a single field within an SDK elicitation request schema. */
 interface SdkElicitationFieldSchema {
 	type?: string;
 	title?: string;
@@ -69,6 +75,7 @@ interface SdkElicitationFieldSchema {
 	};
 }
 
+/** The full elicitation request object received from an MCP server via the Claude Agent SDK. */
 interface SdkElicitationRequest {
 	serverName: string;
 	message: string;
@@ -80,15 +87,18 @@ interface SdkElicitationRequest {
 	};
 }
 
+/** The result returned by an elicitation handler back to the Claude Agent SDK. */
 interface SdkElicitationResult {
 	action: "accept" | "decline" | "cancel";
 	content?: Record<string, string | string[]>;
 }
 
+/** A TUI `Question` extended with an optional note-field ID for "None of the above" free-text capture. */
 interface ParsedElicitationQuestion extends Question {
 	noteFieldId?: string;
 }
 
+/** Descriptor for a single free-text input field parsed from an SDK elicitation form schema. */
 interface ParsedTextInputField {
 	id: string;
 	title: string;
@@ -97,6 +107,7 @@ interface ParsedTextInputField {
 	secure: boolean;
 }
 
+/** A base64-encoded image block in the format accepted by the Claude Agent SDK input message. */
 interface SDKInputImageBlock {
 	type: "image";
 	source: {
@@ -106,13 +117,16 @@ interface SDKInputImageBlock {
 	};
 }
 
+/** A plain-text block in the format accepted by the Claude Agent SDK input message. */
 interface SDKInputTextBlock {
 	type: "text";
 	text: string;
 }
 
+/** Union of content block types that may appear in a Claude Agent SDK user input message. */
 type SDKInputUserContentBlock = SDKInputImageBlock | SDKInputTextBlock;
 
+/** A synthetic user message in the Claude Agent SDK's async-iterable prompt format, used when images are present. */
 interface SDKInputUserMessage {
 	type: "user";
 	message: {
@@ -122,7 +136,9 @@ interface SDKInputUserMessage {
 	parent_tool_use_id: null;
 }
 
+/** Label used for the free-text fallback option in single-choice elicitation questions. */
 const OTHER_OPTION_LABEL = "None of the above";
+/** Regex pattern that identifies field names and descriptions that should be treated as sensitive/secure inputs. */
 const SENSITIVE_FIELD_PATTERN = /(password|passphrase|secret|token|api[_\s-]*key|private[_\s-]*key|credential)/i;
 
 // ---------------------------------------------------------------------------
@@ -144,6 +160,7 @@ function createAssistantStream(): AssistantMessageEventStream {
 	) as AssistantMessageEventStream;
 }
 
+/** Extract a human-readable error string from an SDK result message. */
 export function getResultErrorMessage(result: SDKResultMessage): string {
 	if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
 		return result.errors.join("; ");
@@ -160,12 +177,15 @@ export function getResultErrorMessage(result: SDKResultMessage): string {
 // Claude binary resolution
 // ---------------------------------------------------------------------------
 
+/** Cached result of the `which`/`where claude` lookup so the shell is only spawned once per process. */
 let cachedClaudePath: string | null = null;
 
+/** Return the shell command used to locate the `claude` binary on the given platform. */
 export function getClaudeLookupCommand(platform: NodeJS.Platform = process.platform): string {
 	return platform === "win32" ? "where claude" : "which claude";
 }
 
+/** Extract the first line of `which`/`where` output as the resolved binary path. */
 export function parseClaudeLookupOutput(output: Buffer | string): string {
 	return output
 		.toString()
@@ -248,6 +268,7 @@ export function buildPromptFromContext(context: Context): string {
 	return parts.join("\n\n");
 }
 
+/** Strip the `data:<mime>;base64,` prefix from a data URI, returning only the raw base64 payload. */
 function stripDataUriPrefix(value: string): string {
 	const commaIndex = value.indexOf(",");
 	if (value.startsWith("data:") && commaIndex !== -1) {
@@ -256,11 +277,13 @@ function stripDataUriPrefix(value: string): string {
 	return value;
 }
 
+/** Extract the MIME type from a data URI string, or return `null` if the value is not a valid data URI. */
 function inferMimeTypeFromDataUri(value: string): string | null {
 	const match = /^data:([^;,]+);base64,/.exec(value);
 	return match?.[1] ?? null;
 }
 
+/** Collect all base64 image blocks from user messages in the context for inclusion in the SDK prompt. */
 export function extractImageBlocksFromContext(context: Context): SDKInputImageBlock[] {
 	const imageBlocks: SDKInputImageBlock[] = [];
 
@@ -291,6 +314,7 @@ export function extractImageBlocksFromContext(context: Context): SDKInputImageBl
 	return imageBlocks;
 }
 
+/** Build the SDK query prompt, wrapping image blocks into an async iterable user message when present. */
 export function buildSdkQueryPrompt(
 	context: Context,
 	textPrompt: string = buildPromptFromContext(context),
@@ -320,6 +344,7 @@ export function buildSdkQueryPrompt(
 // Error helper
 // ---------------------------------------------------------------------------
 
+/** Build a minimal error `AssistantMessage` with the given model ID and error text. */
 function makeErrorMessage(model: string, errorMsg: string): AssistantMessage {
 	return {
 		role: "assistant",
@@ -348,6 +373,7 @@ export function makeStreamExhaustedErrorMessage(model: string, lastTextContent:
 	return message;
 }
 
+/** Extract the string labels from an array of SDK elicitation option objects, filtering out blank entries. */
 function readElicitationChoices(options: SdkElicitationRequestOption[] | undefined): string[] {
 	if (!Array.isArray(options)) return [];
 	return options
@@ -355,6 +381,7 @@ function readElicitationChoices(options: SdkElicitationRequestOption[] | undefin
 		.filter((option): option is string => option.length > 0);
 }
 
+/** Parse an SDK elicitation request into structured multiple-choice questions, or null if the schema is unsupported. */
 export function parseAskUserQuestionsElicitation(
 	request: Pick<SdkElicitationRequest, "mode" | "requestedSchema">,
 ): ParsedElicitationQuestion[] | null {
@@ -408,6 +435,7 @@ export function parseAskUserQuestionsElicitation(
 	return questions.length > 0 ? questions : null;
 }
 
+/** Return true if the elicitation field should be treated as sensitive and rendered as a secure/password input. */
 function isSecureElicitationField(
 	requestMessage: string,
 	fieldId: string,
@@ -431,6 +459,7 @@ function isSecureElicitationField(
 	return SENSITIVE_FIELD_PATTERN.test(haystack);
 }
 
+/** Parse an SDK elicitation request into free-text input field descriptors, or null if unsupported. */
 export function parseTextInputElicitation(
 	request: Pick<SdkElicitationRequest, "message" | "mode" | "requestedSchema">,
 ): ParsedTextInputField[] | null {
@@ -469,6 +498,7 @@ export function parseTextInputElicitation(
 	return fields.length > 0 ? fields : null;
 }
 
+/** Convert a TUI interview round result into the SDK elicitation content map. */
 export function roundResultToElicitationContent(
 	questions: ParsedElicitationQuestion[],
 	result: RoundResult,
@@ -495,6 +525,7 @@ export function roundResultToElicitationContent(
 	return content;
 }
 
+/** Build the dialog title string for a multiple-choice elicitation question, combining server name, header, and question text. */
 function buildElicitationPromptTitle(request: SdkElicitationRequest, question: ParsedElicitationQuestion): string {
 	const parts = [
 		request.serverName ? `[${request.serverName}]` : "",
@@ -504,6 +535,7 @@ function buildElicitationPromptTitle(request: SdkElicitationRequest, question: P
 	return parts.join("\n\n");
 }
 
+/** Drive each multiple-choice elicitation question through the extension UI's `select` dialog, collecting answers into an SDK result. */
 async function promptElicitationWithDialogs(
 	request: SdkElicitationRequest,
 	questions: ParsedElicitationQuestion[],
@@ -550,6 +582,7 @@ async function promptElicitationWithDialogs(
 	return { action: "accept", content };
 }
 
+/** Build the dialog title string for a free-text input field, combining server name, field title, and description. */
 function buildTextInputPromptTitle(request: SdkElicitationRequest, field: ParsedTextInputField): string {
 	const parts = [
 		request.serverName ? `[${request.serverName}]` : "",
@@ -559,6 +592,7 @@ function buildTextInputPromptTitle(request: SdkElicitationRequest, field: Parsed
 	return parts.join("\n\n");
 }
 
+/** Derive a placeholder hint for a free-text input field from its description, falling back to "Required" or "Leave empty to skip". */
 function buildTextInputPlaceholder(field: ParsedTextInputField): string | undefined {
 	const desc = field.description.trim();
 	if (!desc) return field.required ? "Required" : "Leave empty to skip";
@@ -573,6 +607,7 @@ function buildTextInputPlaceholder(field: ParsedTextInputField): string | undefi
 	return hint.length > 0 ? hint : field.required ? "Required" : "Leave empty to skip";
 }
 
+/** Collect each free-text input field via the extension UI's `input` dialog, returning the filled SDK elicitation result. */
 async function promptTextInputElicitation(
 	request: SdkElicitationRequest,
 	fields: ParsedTextInputField[],
@@ -596,6 +631,7 @@ async function promptTextInputElicitation(
 	return { action: "accept", content };
 }
 
+/** Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available. */
 export function createClaudeCodeElicitationHandler(
 	ui: ExtensionUIContext | undefined,
 ): ((request: SdkElicitationRequest, options: { signal: AbortSignal }) => Promise<SdkElicitationResult>) | undefined {
@@ -682,6 +718,7 @@ export async function resolveClaudePermissionMode(
 // NOTE: These helpers intentionally mirror @gsd/pi-ai anthropic-shared
 // behavior so this extension remains typecheck-stable even when the published
 // @gsd/pi-ai barrel lags behind monorepo source exports.
+/** Return true for model IDs that support the adaptive thinking API (Opus 4.6/4.7, Sonnet 4.6/4.7, Haiku 4.5). */
 function modelSupportsAdaptiveThinking(modelId: string): boolean {
 	return (
 		modelId.includes("opus-4-6")
@@ -690,9 +727,14 @@ function modelSupportsAdaptiveThinking(modelId: string): boolean {
 		|| modelId.includes("opus-4.7")
 		|| modelId.includes("sonnet-4-6")
 		|| modelId.includes("sonnet-4.6")
+		|| modelId.includes("sonnet-4-7")
+		|| modelId.includes("sonnet-4.7")
+		|| modelId.includes("haiku-4-5")
+		|| modelId.includes("haiku-4.5")
 	);
 }
 
+/** Map a GSD thinking level to the Anthropic effort value, clamping xhigh to max for models that lack native xhigh support. */
 function mapThinkingLevelToAnthropicEffort(level: ThinkingLevel | undefined, modelId: string): "low" | "medium" | "high" | "xhigh" | "max" {
 	switch (level) {
 		case "minimal":
@@ -747,10 +789,21 @@ export function buildSdkOptions(
 		"Bash(pwd)",
 		...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
 	];
+	const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
 	const effort =
-		reasoning && modelSupportsAdaptiveThinking(modelId)
+		reasoning && supportsAdaptive
 			? mapThinkingLevelToAnthropicEffort(reasoning, modelId)
 			: undefined;
+
+	// Bug B: SDK requires thinking:{type:"adaptive"} alongside effort for adaptive thinking to activate.
+	// Bug C: SDK requires thinking:{type:"disabled"} to actually stop adaptive thinking when reasoning is off;
+	//        omitting the field leaves the SDK in its adaptive default (or persisted session state).
+	const thinkingConfig = supportsAdaptive
+		? effort
+			? { thinking: { type: "adaptive" } }
+			: { thinking: { type: "disabled" } }
+		: undefined;
+
 	return {
 		pathToClaudeCodeExecutable: getClaudePath(),
 		model: modelId,
@@ -765,11 +818,13 @@ export function buildSdkOptions(
 		...(allowedTools.length > 0 ? { allowedTools } : {}),
 		...(mcpServers ? { mcpServers } : {}),
 		betas: (modelId.includes("sonnet") || modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) ? ["context-1m-2025-08-07"] : [],
+		...(thinkingConfig ?? {}),
 		...(effort ? { effort } : {}),
 		...sdkExtraOptions,
 	};
 }
 
+/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
 function normalizeToolResultContent(content: unknown): ExternalToolResultContentBlock[] {
 	if (typeof content === "string") {
 		return [{ type: "text", text: content }];
@@ -812,6 +867,7 @@ function normalizeToolResultContent(content: unknown): ExternalToolResultContent
 	return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
 }
 
+/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
 export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): Array<{
 	toolUseId: string;
 	result: ExternalToolResultPayload;
@@ -862,6 +918,7 @@ export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): A
 	return extracted;
 }
 
+/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
 function attachExternalResultsToToolBlocks(
 	toolBlocks: AssistantMessage["content"],
 	toolResultsById: ReadonlyMap<string, ExternalToolResultPayload>,
@@ -920,6 +977,7 @@ export function streamViaClaudeCode(
 	return stream;
 }
 
+/** Async pump that drives the Claude Agent SDK's async-iterable message stream and pushes events into `stream`. */
 async function pumpSdkMessages(
 	model: Model<any>,
 	context: Context,

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

@@ -469,6 +469,72 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		assert.equal("effort" in options, false);
 	});
 
+	// --- Bug fixes #4392: thinking field & model coverage ---
+
+	test("buildSdkOptions sets thinking disabled when reasoning is undefined on adaptive model (#4392)", () => {
+		// Bug C: thinkingLevel="off" means reasoning===undefined; SDK needs thinking:{type:"disabled"}
+		const options = buildSdkOptions("claude-sonnet-4-6", "test", undefined, {});
+		assert.deepEqual(
+			(options as any).thinking,
+			{ type: "disabled" },
+			"thinking must be {type:'disabled'} when reasoning is undefined so SDK stops adaptive thinking",
+		);
+	});
+
+	test("buildSdkOptions omits effort when reasoning is undefined (thinking disabled) (#4392)", () => {
+		// Bug C corollary: no effort when thinking is off
+		const options = buildSdkOptions("claude-sonnet-4-6", "test", undefined, {});
+		assert.equal("effort" in options, false, "effort must not be set when reasoning is undefined");
+	});
+
+	test("buildSdkOptions sets thinking adaptive when reasoning is provided (#4392)", () => {
+		// Bug B: when effort is set, thinking:{type:"adaptive"} must also be present
+		const options = buildSdkOptions("claude-opus-4-6", "test", undefined, { reasoning: "high" });
+		assert.deepEqual(
+			(options as any).thinking,
+			{ type: "adaptive" },
+			"thinking must be {type:'adaptive'} alongside effort when reasoning is set",
+		);
+	});
+
+	test("buildSdkOptions includes both effort and thinking.type=adaptive when reasoning is set (#4392)", () => {
+		// Bug B: both fields must be present together
+		const options = buildSdkOptions("claude-opus-4-6", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high", "effort must be set");
+		assert.deepEqual((options as any).thinking, { type: "adaptive" }, "thinking must be adaptive");
+	});
+
+	test("buildSdkOptions maps reasoning to effort for sonnet-4-7 (modelSupportsAdaptiveThinking #4392)", () => {
+		// Bug D: sonnet-4-7 was missing from modelSupportsAdaptiveThinking
+		const options = buildSdkOptions("claude-sonnet-4-7", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high", "sonnet-4-7 must support adaptive thinking and map effort");
+	});
+
+	test("buildSdkOptions maps reasoning to effort for haiku-4-5 (modelSupportsAdaptiveThinking #4392)", () => {
+		// Bug D: haiku-4-5 was missing from modelSupportsAdaptiveThinking
+		const options = buildSdkOptions("claude-haiku-4-5", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high", "haiku-4-5 must support adaptive thinking and map effort");
+	});
+
+	test("buildSdkOptions maps reasoning to effort for sonnet-4.7 dot-form (modelSupportsAdaptiveThinking #4392)", () => {
+		// Dot-form aliases (e.g. claude-sonnet-4.7) must also be recognised
+		const options = buildSdkOptions("claude-sonnet-4.7", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high", "claude-sonnet-4.7 must support adaptive thinking and map effort");
+	});
+
+	test("buildSdkOptions maps reasoning to effort for haiku-4.5 dot-form (modelSupportsAdaptiveThinking #4392)", () => {
+		// Dot-form aliases (e.g. claude-haiku-4.5) must also be recognised
+		const options = buildSdkOptions("claude-haiku-4.5", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high", "claude-haiku-4.5 must support adaptive thinking and map effort");
+	});
+
+	test("buildSdkOptions does not set thinking field for non-adaptive model when reasoning is undefined (#4392)", () => {
+		// Non-adaptive models (e.g. claude-sonnet-4-20250514) don't use the thinking API at all;
+		// no thinking field should be set when reasoning is undefined
+		const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, {});
+		assert.equal("thinking" in options, false, "non-adaptive models must not receive a thinking field");
+	});
+
 	test("buildSdkOptions includes workflow MCP server config when env is set", () => {
 		const prev = {
 			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,

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

@@ -16,7 +16,7 @@ import type {
   VerificationContext,
   VerificationResult,
 } from "../auto-verification.js";
-import type { DispatchAction } from "../auto-dispatch.js";
+import type { DispatchAction, DispatchContext } from "../auto-dispatch.js";
 import type { WorktreeResolver } from "../worktree-resolver.js";
 import type { CmuxLogLevel } from "../../cmux/index.js";
 import type { JournalEntry } from "../journal.js";
@@ -145,15 +145,7 @@ export interface LoopDeps {
   } | null>;
 
   // Dispatch
-  resolveDispatch: (dctx: {
-    basePath: string;
-    mid: string;
-    midTitle: string;
-    state: GSDState;
-    prefs: GSDPreferences | undefined;
-    session?: AutoSession;
-    structuredQuestionsAvailable?: "true" | "false";
-  }) => Promise<DispatchAction>;
+  resolveDispatch: (dctx: DispatchContext) => Promise<DispatchAction>;
   runPreDispatchHooks: (
     unitType: string,
     unitId: string,

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

@@ -50,6 +50,7 @@ import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
+import type { MinimalModelRegistry } from "../context-budget.js";
 import { ensurePlanV2Graph } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -857,6 +858,8 @@ export async function runDispatch(
     prefs,
     session: s,
     structuredQuestionsAvailable,
+    sessionContextWindow: ctx.model?.contextWindow,
+    modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
   });
 
   if (dispatchResult.action === "stop") {
@@ -1128,16 +1131,42 @@ export async function runGuards(
       s.lastBudgetAlertLevel =
         newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
 
-      if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
+      // Emit Layer 2 budget_threshold event (post-plan hook recommendation).
+      // Extensions / Layer 0 shell hooks may return an action override.
+      let hookAction: "pause" | "downgrade" | "continue" | undefined;
+      try {
+        const { emitBudgetThreshold } = await import("../hook-emitter.js");
+        const hookResult = await emitBudgetThreshold({
+          fraction: budgetPct,
+          spent: totalCost,
+          limit: budgetCeiling,
+        });
+        if (hookResult?.action) hookAction = hookResult.action;
+      } catch (hookErr) {
+        logWarning("engine", `budget_threshold hook emission failed: ${(hookErr as Error).message}`);
+      }
+
+      // Apply hook override to enforcement action. "continue" → "none" (no enforcement),
+      // "pause" and "downgrade" map to the matching enforcement path below.
+      let effectiveAction = budgetEnforcementAction;
+      if (hookAction === "continue") {
+        effectiveAction = "none";
+      } else if (hookAction === "pause") {
+        effectiveAction = "pause";
+      } else if (hookAction === "downgrade") {
+        effectiveAction = "warn";
+      }
+
+      if (threshold.pct === 100 && effectiveAction !== "none") {
         // 100% — special enforcement logic (halt/pause/warn)
         const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
-        if (budgetEnforcementAction === "halt") {
+        if (effectiveAction === "halt") {
           deps.sendDesktopNotification("GSD", msg, "error", "budget", basename(s.originalBasePath || s.basePath));
           await deps.stopAuto(ctx, pi, "Budget ceiling reached");
           debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
           return { action: "break", reason: "budget-halt" };
         }
-        if (budgetEnforcementAction === "pause") {
+        if (effectiveAction === "pause") {
           ctx.ui.notify(
             `${msg} Pausing auto-mode — /gsd auto to override and continue.`,
             "warning",
@@ -1586,21 +1615,24 @@ export async function runUnitPhase(
   }
 
   if (unitResult.status === "cancelled") {
+    const errorCategory = unitResult.errorContext?.category;
     // Provider-error pause: pauseAuto already handled cleanup and scheduled
     // recovery. Don't hard-stop — just break out of the loop (#2762).
-    if (unitResult.errorContext?.category === "provider") {
+    if (errorCategory === "provider") {
       await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-      debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
+      debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext?.isTransient });
       return { action: "break", reason: "provider-pause" };
     }
     // Timeout category covers two distinct scenarios:
     //   1. Session creation timeout (120s) — transient, auto-resume with backoff
     //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
+    // Transient session-failed covers recoverable newSession failures and should
+    // pause instead of hard-stopping.
     // Structural errors (TypeError, is not a function) are NOT transient
     // and must hard-stop to avoid infinite retry loops.
     if (
       unitResult.errorContext?.isTransient &&
-      unitResult.errorContext?.category === "timeout"
+      errorCategory === "timeout"
     ) {
       const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
 
@@ -1663,6 +1695,20 @@ export async function runUnitPhase(
       await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
       return { action: "break", reason: "unit-hard-timeout" };
     }
+    if (
+      unitResult.errorContext?.isTransient &&
+      errorCategory === "session-failed"
+    ) {
+      ctx.ui.notify(
+        `Session creation failed transiently for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Pausing auto-mode (recoverable).`,
+        "warning",
+      );
+      debugLog("autoLoop", { phase: "session-start-transient-pause", unitType, unitId, category: errorCategory });
+      await deps.pauseAuto(ctx, pi);
+      await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+      await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+      return { action: "break", reason: "session-timeout" };
+    }
     // All other cancelled states (structural errors, non-transient failures): hard stop
     if (s.currentUnit) {
       await deps.closeoutUnit(

package/src/resources/extensions/gsd/auto-artifact-paths.ts

@@ -43,6 +43,16 @@ export function resolveExpectedArtifactPath(
       return dir ? join(dir, buildMilestoneFileName(mid, "ROADMAP")) : null;
     }
     case "research-slice": {
+      // #4414: Sentinel unitId "{mid}/parallel-research" fans out across
+      // multiple slices. Resolve to a milestone-level placeholder path so
+      // blocker escalation has somewhere to write. Verification for this
+      // sentinel is handled directly in verifyExpectedArtifact.
+      if (sid === "parallel-research") {
+        const mdir = resolveMilestonePath(base, mid);
+        return mdir
+          ? join(mdir, buildMilestoneFileName(mid, "PARALLEL-BLOCKER"))
+          : null;
+      }
       const dir = resolveSlicePath(base, mid, sid!);
       return dir ? join(dir, buildSliceFileName(sid!, "RESEARCH")) : null;
     }
@@ -50,6 +60,11 @@ export function resolveExpectedArtifactPath(
       const dir = resolveSlicePath(base, mid, sid!);
       return dir ? join(dir, buildSliceFileName(sid!, "PLAN")) : null;
     }
+    case "refine-slice": {
+      // ADR-011: refine-slice expands a sketch and writes the same PLAN.md as plan-slice.
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "PLAN")) : null;
+    }
     case "reassess-roadmap": {
       const dir = resolveSlicePath(base, mid, sid!);
       return dir ? join(dir, buildSliceFileName(sid!, "ASSESSMENT")) : null;
@@ -109,9 +124,14 @@ export function diagnoseExpectedArtifact(
     case "plan-milestone":
       return `${relMilestoneFile(base, mid, "ROADMAP")} (milestone roadmap)`;
     case "research-slice":
+      if (sid === "parallel-research") {
+        return `${relMilestoneFile(base, mid, "PARALLEL-BLOCKER")} (parallel slice research sentinel)`;
+      }
       return `${relSliceFile(base, mid, sid!, "RESEARCH")} (slice research)`;
     case "plan-slice":
       return `${relSliceFile(base, mid, sid!, "PLAN")} (slice plan)`;
+    case "refine-slice":
+      return `${relSliceFile(base, mid, sid!, "PLAN")} (refined slice plan from sketch)`;
     case "execute-task": {
       return `Task ${tid} marked [x] in ${relSliceFile(base, mid, sid!, "PLAN")} + summary written`;
     }