gsd-pi 2.75.0 → 2.76.0

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

@@ -18,7 +18,7 @@ import type {
 	ToolCall,
 } from "@gsd/pi-ai";
 import type { ExtensionUIContext } from "@gsd/pi-coding-agent";
-import { EventStream, mapThinkingLevelToEffort, supportsAdaptiveThinking } from "@gsd/pi-ai";
+import { EventStream } from "@gsd/pi-ai";
 import { execSync } from "node:child_process";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
@@ -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 {
@@ -679,6 +715,44 @@ export async function resolveClaudePermissionMode(
 	return "bypassPermissions";
 }
 
+// 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")
+		|| modelId.includes("opus-4.6")
+		|| modelId.includes("opus-4-7")
+		|| 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":
+		case "low":
+			return "low";
+		case "medium":
+			return "medium";
+		case "high":
+			return "high";
+		case "xhigh":
+			if (modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) return "xhigh";
+			if (modelId.includes("opus-4-6") || modelId.includes("opus-4.6")) return "max";
+			return "high";
+		default:
+			return "high";
+	}
+}
+
 /**
  * Build the options object passed to the Claude Agent SDK's `query()` call.
  *
@@ -715,10 +789,21 @@ export function buildSdkOptions(
 		"Bash(pwd)",
 		...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
 	];
+	const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
 	const effort =
-		reasoning && supportsAdaptiveThinking(modelId)
-			? mapThinkingLevelToEffort(reasoning, 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,
@@ -732,12 +817,14 @@ export function buildSdkOptions(
 		disallowedTools,
 		...(allowedTools.length > 0 ? { allowedTools } : {}),
 		...(mcpServers ? { mcpServers } : {}),
-		betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
+		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 }];
@@ -780,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;
@@ -830,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>,
@@ -888,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

@@ -431,6 +431,14 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		);
 	});
 
+	test("buildSdkOptions enables context-1m beta for opus-4-7 (#4348)", () => {
+		const opts = buildSdkOptions("claude-opus-4-7", "test");
+		assert.ok(
+			Array.isArray(opts.betas) && opts.betas.includes("context-1m-2025-08-07"),
+			"claude-opus-4-7 should have context-1m beta enabled for 1M token context window",
+		);
+	});
+
 	test("buildSdkOptions maps reasoning to effort for adaptive Claude Code models (#3917)", () => {
 		const options = buildSdkOptions("claude-sonnet-4-6", "test", undefined, { reasoning: "high" });
 		assert.equal(options.effort, "high");
@@ -441,6 +449,16 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		assert.equal(options.effort, "max");
 	});
 
+	test("buildSdkOptions maps reasoning to effort for opus-4-7 (#4348)", () => {
+		const options = buildSdkOptions("claude-opus-4-7", "test", undefined, { reasoning: "high" });
+		assert.equal(options.effort, "high");
+	});
+
+	test("buildSdkOptions passes xhigh reasoning natively for opus-4-7 (#4348)", () => {
+		const options = buildSdkOptions("claude-opus-4-7", "test", undefined, { reasoning: "xhigh" });
+		assert.equal(options.effort, "xhigh");
+	});
+
 	test("buildSdkOptions omits effort when reasoning is undefined (#3917)", () => {
 		const options = buildSdkOptions("claude-sonnet-4-6", "test");
 		assert.equal("effort" in options, false);
@@ -451,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/detect-stuck.ts

@@ -20,6 +20,7 @@ const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
  *
  * Rule 1: Same error string twice in a row → stuck immediately.
  * Rule 2: Same unit key 3+ consecutive times → stuck (preserves prior behavior).
+ * Rule 2b: Same unit key appears 3+ times anywhere in the active window → stuck.
  * Rule 3: Oscillation A→B→A→B in last 4 entries → stuck.
  * Rule 4: Same ENOENT path in any 2 entries within the window → stuck (#3575).
  *         Missing files don't self-heal between retries — retrying wastes budget.
@@ -58,6 +59,15 @@ export function detectStuck(
     }
   }
 
+  // Rule 2b: Same unit key 3+ times anywhere in the active window
+  const countInWindow = window.filter((entry) => entry.key === last.key).length;
+  if (countInWindow >= 3) {
+    return {
+      stuck: true,
+      reason: `${last.key} derived ${countInWindow} times in last ${window.length} attempts without progress${suffix}`,
+    };
+  }
+
   // Rule 3: Oscillation (A→B→A→B in last 4)
   if (window.length >= 4) {
     const w = window.slice(-4);

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,14 +145,7 @@ export interface LoopDeps {
   } | null>;
 
   // Dispatch
-  resolveDispatch: (dctx: {
-    basePath: string;
-    mid: string;
-    midTitle: string;
-    state: GSDState;
-    prefs: GSDPreferences | undefined;
-    session?: AutoSession;
-  }) => Promise<DispatchAction>;
+  resolveDispatch: (dctx: DispatchContext) => Promise<DispatchAction>;
   runPreDispatchHooks: (
     unitType: string,
     unitId: string,

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

@@ -14,6 +14,7 @@ import type { AutoSession, SidecarItem } from "./session.js";
 import type { LoopDeps } from "./loop-deps.js";
 import {
   MAX_LOOP_ITERATIONS,
+  type PhaseResult,
   type LoopState,
   type IterationContext,
   type IterationData,
@@ -33,6 +34,8 @@ import { logWarning } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { scheduleSidecarQueue } from "../uok/execution-graph.js";
+import { ExecutionGraphScheduler } from "../uok/execution-graph.js";
+import type { UokGraphNode } from "../uok/contracts.js";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
@@ -78,6 +81,12 @@ function saveStuckState(basePath: string, state: LoopState): void {
 const MEMORY_CHECK_INTERVAL = 5; // check every 5 iterations
 const MEMORY_PRESSURE_THRESHOLD = 0.85; // 85% of heap limit
 
+type DispatchContract = "legacy-direct" | "uok-scheduler";
+
+interface AutoLoopOptions {
+  dispatchContract?: DispatchContract;
+}
+
 function checkMemoryPressure(): { pressured: boolean; heapMB: number; limitMB: number; pct: number } {
   const mem = process.memoryUsage();
   // v8.getHeapStatistics() gives heap_size_limit but requires import
@@ -95,22 +104,90 @@ function checkMemoryPressure(): { pressured: boolean; heapMB: number; limitMB: n
   return { pressured: pct > MEMORY_PRESSURE_THRESHOLD, heapMB, limitMB, pct };
 }
 
+function resolveDispatchNodeKind(
+  unitType: string,
+  sidecarItem?: SidecarItem,
+): UokGraphNode["kind"] {
+  if (sidecarItem?.kind === "hook") return "hook";
+  if (sidecarItem?.kind === "triage") return "verification";
+  if (sidecarItem?.kind === "quick-task") return "team-worker";
+
+  if (unitType.startsWith("hook/")) return "hook";
+  if (unitType === "reactive-execute") return "subagent";
+  if (
+    unitType === "gate-evaluate"
+    || unitType === "validate-milestone"
+    || unitType === "run-uat"
+    || unitType === "complete-slice"
+  ) {
+    return "verification";
+  }
+  if (unitType === "replan-slice" || unitType === "reassess-roadmap") {
+    return "reprocess";
+  }
+  return "unit";
+}
+
+async function runUnitPhaseViaContract(
+  dispatchContract: DispatchContract,
+  ic: IterationContext,
+  iterData: IterationData,
+  loopState: LoopState,
+  sidecarItem?: SidecarItem,
+): Promise<PhaseResult<{ unitStartedAt: number }>> {
+  if (dispatchContract === "legacy-direct") {
+    return runUnitPhase(ic, iterData, loopState, sidecarItem);
+  }
+
+  const scheduler = new ExecutionGraphScheduler();
+  let outcome: PhaseResult<{ unitStartedAt: number }> | null = null;
+  const executeNode = async (): Promise<void> => {
+    outcome = await runUnitPhase(ic, iterData, loopState, sidecarItem);
+  };
+  const kinds: UokGraphNode["kind"][] = [
+    "unit",
+    "hook",
+    "subagent",
+    "team-worker",
+    "verification",
+    "reprocess",
+  ];
+  for (const kind of kinds) scheduler.registerHandler(kind, executeNode);
+
+  const nodeId = `dispatch:${ic.iteration}:${iterData.unitType}:${iterData.unitId}`;
+  await scheduler.run([
+    {
+      id: nodeId,
+      kind: resolveDispatchNodeKind(iterData.unitType, sidecarItem),
+      dependsOn: [],
+      metadata: {
+        unitType: iterData.unitType,
+        unitId: iterData.unitId,
+      },
+    },
+  ], { parallel: false, maxWorkers: 1 });
+
+  return outcome ?? { action: "break", reason: "scheduler-dispatch-missing-result" };
+}
+
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
  * runUnit → finalize → repeat. Exits when s.active becomes false or a
  * terminal condition is reached.
  *
  * This is the linear replacement for the recursive
- * dispatchNextUnit → handleAgentEnd → dispatchNextUnit chain.
+ * dispatchNextUnit → resolveAgentEnd → dispatchNextUnit chain.
  */
 export async function autoLoop(
   ctx: ExtensionContext,
   pi: ExtensionAPI,
   s: AutoSession,
   deps: LoopDeps,
+  options?: AutoLoopOptions,
 ): Promise<void> {
   debugLog("autoLoop", { phase: "enter" });
   let iteration = 0;
+  const dispatchContract = options?.dispatchContract ?? "legacy-direct";
   // Load persisted stuck state so counters survive session restarts (#3704)
   const persisted = loadStuckState(s.basePath);
   const loopState: LoopState = {
@@ -324,7 +401,12 @@ export async function autoLoop(
         }
 
         // ── Unit execution (shared with dev path) ──
-        const unitPhaseResult = await runUnitPhase(ic, iterData, loopState);
+        const unitPhaseResult = await runUnitPhaseViaContract(
+          dispatchContract,
+          ic,
+          iterData,
+          loopState,
+        );
         deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
           unitType: iterData.unitType,
           unitId: iterData.unitId,
@@ -469,7 +551,13 @@ export async function autoLoop(
         });
       }
 
-      const unitPhaseResult = await runUnitPhase(ic, iterData, loopState, sidecarItem);
+      const unitPhaseResult = await runUnitPhaseViaContract(
+        dispatchContract,
+        ic,
+        iterData,
+        loopState,
+        sidecarItem,
+      );
       deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
         unitType: iterData.unitType,
         unitId: iterData.unitId,
@@ -622,3 +710,21 @@ export async function autoLoop(
   _clearCurrentResolve();
   debugLog("autoLoop", { phase: "exit", totalIterations: iteration });
 }
+
+export async function runUokKernelLoop(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  s: AutoSession,
+  deps: LoopDeps,
+): Promise<void> {
+  return autoLoop(ctx, pi, s, deps, { dispatchContract: "uok-scheduler" });
+}
+
+export async function runLegacyAutoLoop(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  s: AutoSession,
+  deps: LoopDeps,
+): Promise<void> {
+  return autoLoop(ctx, pi, s, deps, { dispatchContract: "legacy-direct" });
+}