@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

package/src/resources/extensions/browser-tools/capture.ts

@@ -6,58 +6,14 @@
  */
 
 import type { Frame, Page } from "playwright";
-
-// sharp is an optional native dependency. Load it lazily so that the extension
-// can still be loaded on platforms where sharp is unavailable (e.g. bunx on
-// Raspberry Pi). constrainScreenshot falls back to returning the raw buffer
-// when sharp is not installed, which means screenshots won't be resized but
-// the tool remains functional.
-let _sharp: typeof import("sharp") | null | undefined;
-async function getSharp(): Promise<typeof import("sharp") | null> {
-	if (_sharp !== undefined) return _sharp;
-	try {
-		_sharp = (await import("sharp")).default;
-	} catch {
-		_sharp = null;
-	}
-	return _sharp;
-}
-
-/**
- * Test-only seam: override the cached sharp module. Pass `null` to simulate
- * an environment where the sharp native dep is unavailable; pass `undefined`
- * to clear the cache and let the next getSharp() call re-import. See
- * tests/capture-sharp-optional.test.cjs.
- */
-export function __setSharpForTesting(
-	value: typeof import("sharp") | null | undefined,
-): void {
-	_sharp = value;
-}
+import { constrainScreenshot } from "./screenshot-constraints.js";
+export { constrainScreenshot, __setSharpForTesting } from "./screenshot-constraints.js";
 import type { CompactPageState, CompactSelectorState } from "./state.js";
 import { formatCompactStateSummary } from "./utils.js";
 
-// Anthropic vision: 1568px is the recommended optimal width. Height is capped
-// generously at 8000px so tall full-page screenshots remain readable rather
-// than being squished into a square constraint.
-//
 // Override via environment variables:
-//   SCREENSHOT_MAX_WIDTH=0   → uncap width (use raw resolution)
-//   SCREENSHOT_MAX_HEIGHT=0  → uncap height
 //   SCREENSHOT_FORMAT=png    → lossless PNG for all viewport/fullpage screenshots
 //   SCREENSHOT_QUALITY=100   → max JPEG quality (1-100, default 80)
-const MAX_SCREENSHOT_WIDTH = parseScreenshotDimension(process.env.SCREENSHOT_MAX_WIDTH, 1568);
-const MAX_SCREENSHOT_HEIGHT = parseScreenshotDimension(process.env.SCREENSHOT_MAX_HEIGHT, 8000);
-
-/** Parse a dimension env var: positive int = that value, 0 = Infinity (uncapped), absent/invalid = default. */
-function parseScreenshotDimension(value: string | undefined, fallback: number): number {
-	if (value === undefined || value === "") return fallback;
-	const n = parseInt(value, 10);
-	if (isNaN(n) || n < 0) return fallback;
-	if (n === 0) return Infinity;
-	return n;
-}
-
 /** Return the user-configured screenshot format override, or null for default behavior. */
 export function getScreenshotFormatOverride(): "png" | "jpeg" | null {
 	const fmt = process.env.SCREENSHOT_FORMAT?.toLowerCase();
@@ -176,46 +132,6 @@ export async function postActionSummary(p: Page, target?: Page | Frame): Promise
 	}
 }
 
-// ---------------------------------------------------------------------------
-// Screenshot helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Constrain screenshot dimensions for the Anthropic vision API.
- * Width is capped at 1568px (optimal) and height at 8000px, each
- * independently, using `fit: "inside"` so aspect ratio is preserved.
- * Small images are never upscaled.
- *
- * `page` parameter is retained for ToolDeps signature stability (D008)
- * but is no longer used — all processing is server-side via sharp.
- */
-export async function constrainScreenshot(
-	_page: Page,
-	buffer: Buffer,
-	mimeType: string,
-	quality: number,
-): Promise<Buffer> {
-	const sharp = await getSharp();
-	if (!sharp) return buffer;
-
-	const meta = await sharp(buffer).metadata();
-	const width = meta.width;
-	const height = meta.height;
-
-	if (width === undefined || height === undefined) return buffer;
-	if (width <= MAX_SCREENSHOT_WIDTH && height <= MAX_SCREENSHOT_HEIGHT) return buffer;
-
-	const resizer = sharp(buffer).resize(MAX_SCREENSHOT_WIDTH, MAX_SCREENSHOT_HEIGHT, {
-		fit: "inside",
-		withoutEnlargement: true,
-	});
-
-	if (mimeType === "image/png") {
-		return Buffer.from(await resizer.png().toBuffer());
-	}
-	return Buffer.from(await resizer.jpeg({ quality }).toBuffer());
-}
-
 /** Capture a JPEG screenshot for error debugging. Returns base64 or null. */
 export async function captureErrorScreenshot(p: Page | null): Promise<{ data: string; mimeType: string } | null> {
 	if (!p) return null;

package/src/resources/extensions/browser-tools/screenshot-constraints.ts

@@ -0,0 +1,94 @@
+import type { Page } from "playwright";
+
+// sharp is an optional native dependency. Load it lazily so that screenshot
+// emitters still work on platforms where sharp is unavailable (e.g. bunx on
+// Raspberry Pi). constrainScreenshot falls back to returning the raw buffer
+// when sharp is not installed.
+let _sharp: typeof import("sharp") | null | undefined;
+async function getSharp(): Promise<typeof import("sharp") | null> {
+	if (_sharp !== undefined) return _sharp;
+	try {
+		_sharp = (await import("sharp")).default;
+	} catch {
+		_sharp = null;
+	}
+	return _sharp;
+}
+
+/**
+ * Test-only seam: override the cached sharp module. Pass `null` to simulate
+ * an environment where the sharp native dep is unavailable; pass `undefined`
+ * to clear the cache and let the next getSharp() call re-import. See
+ * tests/capture-sharp-optional.test.cjs.
+ */
+export function __setSharpForTesting(
+	value: typeof import("sharp") | null | undefined,
+): void {
+	_sharp = value;
+}
+
+// Anthropic vision: 1568px is the recommended optimal width. Height is capped
+// generously at 8000px so tall full-page screenshots remain readable rather
+// than being squished into a square constraint.
+//
+// Override via environment variables:
+//   SCREENSHOT_MAX_WIDTH=0   -> uncap width (use raw resolution)
+//   SCREENSHOT_MAX_HEIGHT=0  -> uncap height
+export const MAX_SCREENSHOT_WIDTH = parseScreenshotDimension(process.env.SCREENSHOT_MAX_WIDTH, 1568);
+export const MAX_SCREENSHOT_HEIGHT = parseScreenshotDimension(process.env.SCREENSHOT_MAX_HEIGHT, 8000);
+
+/** Parse a dimension env var: positive int = that value, 0 = Infinity (uncapped), absent/invalid = default. */
+function parseScreenshotDimension(value: string | undefined, fallback: number): number {
+	if (value === undefined || value === "") return fallback;
+	const n = parseInt(value, 10);
+	if (isNaN(n) || n < 0) return fallback;
+	if (n === 0) return Infinity;
+	return n;
+}
+
+export async function getScreenshotBufferDimensions(
+	buffer: Buffer,
+): Promise<{ width: number; height: number } | null> {
+	const sharp = await getSharp();
+	if (!sharp) return null;
+
+	const meta = await sharp(buffer).metadata();
+	if (meta.width === undefined || meta.height === undefined) return null;
+	return { width: meta.width, height: meta.height };
+}
+
+/**
+ * Constrain screenshot dimensions for the Anthropic vision API.
+ * Width is capped at 1568px (optimal) and height at 8000px, each
+ * independently, using `fit: "inside"` so aspect ratio is preserved.
+ * Small images are never upscaled.
+ *
+ * `page` parameter is retained for ToolDeps signature stability (D008)
+ * but is no longer used — all processing is server-side via sharp.
+ */
+export async function constrainScreenshot(
+	_page: Page | null,
+	buffer: Buffer,
+	mimeType: string,
+	quality: number,
+): Promise<Buffer> {
+	const sharp = await getSharp();
+	if (!sharp) return buffer;
+
+	const dimensions = await getScreenshotBufferDimensions(buffer);
+	const width = dimensions?.width;
+	const height = dimensions?.height;
+
+	if (width === undefined || height === undefined) return buffer;
+	if (width <= MAX_SCREENSHOT_WIDTH && height <= MAX_SCREENSHOT_HEIGHT) return buffer;
+
+	const resizer = sharp(buffer).resize(MAX_SCREENSHOT_WIDTH, MAX_SCREENSHOT_HEIGHT, {
+		fit: "inside",
+		withoutEnlargement: true,
+	});
+
+	if (mimeType === "image/png") {
+		return Buffer.from(await resizer.png().toBuffer());
+	}
+	return Buffer.from(await resizer.jpeg({ quality }).toBuffer());
+}

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

@@ -22,6 +22,7 @@ import type {
 import type { ExtensionUIContext } from "@gsd/pi-coding-agent";
 import { EventStream } from "@gsd/pi-ai";
 import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
@@ -583,6 +584,7 @@ function inferMimeTypeFromDataUri(value: string): string | 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[] = [];
+	const seenImageKeys = new Set<string>();
 
 	for (const msg of context.messages) {
 		if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
@@ -597,12 +599,17 @@ export function extractImageBlocksFromContext(context: Context): SDKInputImageBl
 					: inferMimeTypeFromDataUri(block.data);
 			if (!mimeType) continue;
 
+			const data = stripDataUriPrefix(block.data);
+			const imageKey = `${mimeType}\0${createHash("sha1").update(data).digest("hex")}`;
+			if (seenImageKeys.has(imageKey)) continue;
+			seenImageKeys.add(imageKey);
+
 			imageBlocks.push({
 				type: "image",
 				source: {
 					type: "base64",
 					media_type: mimeType,
-					data: stripDataUriPrefix(block.data),
+					data,
 				},
 			});
 		}
@@ -2252,6 +2259,7 @@ export function streamViaClaudeCode(
 interface SdkAttemptMessageState {
 	builder: PartialMessageBuilder | null;
 	intermediateToolBlocks: AssistantMessage["content"];
+	intermediateTextBlocks: AssistantMessage["content"];
 	toolResultsById: Map<string, ExternalToolResultPayload>;
 	toolCompletionTargetsById: Map<string, { partial: AssistantMessage; contentIndex: number }>;
 	emittedExternalToolResultIds: Set<string>;
@@ -2261,6 +2269,7 @@ function createSdkAttemptMessageState(): SdkAttemptMessageState {
 	return {
 		builder: null,
 		intermediateToolBlocks: [],
+		intermediateTextBlocks: [],
 		toolResultsById: new Map<string, ExternalToolResultPayload>(),
 		toolCompletionTargetsById: new Map<string, { partial: AssistantMessage; contentIndex: number }>(),
 		emittedExternalToolResultIds: new Set<string>(),
@@ -2402,6 +2411,7 @@ async function pumpSdkMessages(
 				let {
 					builder,
 					intermediateToolBlocks,
+					intermediateTextBlocks,
 					toolResultsById,
 					toolCompletionTargetsById,
 					emittedExternalToolResultIds,
@@ -2542,8 +2552,14 @@ async function pumpSdkMessages(
 								for (const [contentIndex, block] of builder.message.content.entries()) {
 									if (block.type === "text" && block.text) {
 										lastTextContent = block.text;
+										// Accumulate completed prose in order — a multi-question
+										// turn commits [prose][elicitation] segments across several
+										// synthetic-user boundaries, and overwriting a single
+										// scalar would drop every explanation but the last.
+										intermediateTextBlocks.push({ type: "text", text: block.text });
 									} else if (block.type === "thinking" && block.thinking) {
 										lastThinkingContent = block.thinking;
+										intermediateTextBlocks.push({ type: "thinking", thinking: block.thinking });
 									} else if (block.type === "toolCall" || block.type === "serverToolUse") {
 										// Collect tool blocks for externalToolExecution rendering
 										intermediateToolBlocks.push(block);
@@ -2641,6 +2657,7 @@ async function pumpSdkMessages(
 							const result = msg as SDKResultMessage;
 							const finalContent = buildFinalAssistantContent({
 								intermediateToolBlocks,
+								intermediateTextBlocks,
 								pendingContent: builder?.message.content,
 								toolResultsById,
 								lastThinkingContent,

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

@@ -363,6 +363,53 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 		]);
 	});
 
+	test("extractImageBlocksFromContext deduplicates byte-identical image parts", () => {
+		const context: Context = {
+			messages: [
+				{
+					role: "user",
+					content: [
+						{
+							type: "image",
+							data: "data:image/png;base64,abc123",
+							mimeType: "image/png",
+						},
+						{
+							type: "image",
+							data: "abc123",
+							mimeType: "image/png",
+						},
+						{
+							type: "image",
+							data: "def456",
+							mimeType: "image/png",
+						},
+					],
+				} as Message,
+			],
+		};
+
+		const imageBlocks = extractImageBlocksFromContext(context);
+		assert.deepEqual(imageBlocks, [
+			{
+				type: "image",
+				source: {
+					type: "base64",
+					media_type: "image/png",
+					data: "abc123",
+				},
+			},
+			{
+				type: "image",
+				source: {
+					type: "base64",
+					media_type: "image/png",
+					data: "def456",
+				},
+			},
+		]);
+	});
+
 	test("buildSdkQueryPrompt returns plain string when no images exist in context", () => {
 		const context: Context = {
 			messages: [{ role: "user", content: "hello" } as Message],
@@ -1365,6 +1412,67 @@ describe("stream-adapter — Claude Code external tool results", () => {
 		});
 		assert.deepEqual(finalContent[1], { type: "text", text: "Read complete." });
 	});
+
+	test("buildFinalAssistantContent keeps every prose segment across successive elicitation boundaries (#1284)", () => {
+		// A multi-question /gsd discuss turn: [prose A][Q1][prose B][Q2][prose C].
+		// Prose A and B are committed at synthetic-user boundaries (intermediate),
+		// prose C is still in the builder (pending) when `result` arrives.
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{ type: "toolCall", id: "q1", name: "ask_user_questions", arguments: {} } as any,
+				{ type: "toolCall", id: "q2", name: "ask_user_questions", arguments: {} } as any,
+			],
+			intermediateTextBlocks: [
+				{ type: "text", text: "prose A" },
+				{ type: "text", text: "prose B" },
+			],
+			pendingContent: [{ type: "text", text: "prose C" }],
+			toolResultsById: new Map(),
+		});
+
+		const textBlocks = finalContent.filter((b) => b.type === "text").map((b) => (b as any).text);
+		assert.deepEqual(textBlocks, ["prose A", "prose B", "prose C"]);
+	});
+
+	test("buildFinalAssistantContent does not duplicate the last prose when the turn ends on an elicitation (#1284)", () => {
+		// [prose A][Q1][prose B][Q2] — builder was reset at the final boundary, so
+		// pendingContent is empty and lastTextContent still holds "prose B".
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{ type: "toolCall", id: "q1", name: "ask_user_questions", arguments: {} } as any,
+				{ type: "toolCall", id: "q2", name: "ask_user_questions", arguments: {} } as any,
+			],
+			intermediateTextBlocks: [
+				{ type: "text", text: "prose A" },
+				{ type: "text", text: "prose B" },
+			],
+			toolResultsById: new Map(),
+			lastTextContent: "prose B",
+		});
+
+		const textBlocks = finalContent.filter((b) => b.type === "text").map((b) => (b as any).text);
+		assert.deepEqual(textBlocks, ["prose A", "prose B"]);
+	});
+
+	test("buildFinalAssistantContent emits scalar fallback prose/thinking not captured in the accumulator", () => {
+		// A non-streaming `assistant` SDK message sets lastText/lastThinkingContent
+		// only (never pushed to intermediateTextBlocks). With pendingContent empty
+		// and intermediate blocks present, the fallback must still be emitted.
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{ type: "toolCall", id: "q1", name: "ask_user_questions", arguments: {} } as any,
+			],
+			intermediateTextBlocks: [{ type: "text", text: "prose A" }],
+			toolResultsById: new Map(),
+			lastThinkingContent: "final thinking",
+			lastTextContent: "final prose",
+		});
+
+		const textBlocks = finalContent.filter((b) => b.type === "text").map((b) => (b as any).text);
+		const thinkingBlocks = finalContent.filter((b) => b.type === "thinking").map((b) => (b as any).thinking);
+		assert.deepEqual(textBlocks, ["prose A", "final prose"]);
+		assert.deepEqual(thinkingBlocks, ["final thinking"]);
+	});
 });
 
 describe("claude-code-cli — Claude Fable 5 Opus-tier support", () => {

package/src/resources/extensions/claude-code-cli/turn-assembler.ts

@@ -244,6 +244,7 @@ export function shouldSuppressDuplicateToolUnavailableBlock(
  */
 export function buildFinalAssistantContent(params: {
 	intermediateToolBlocks: AssistantMessage["content"];
+	intermediateTextBlocks?: AssistantMessage["content"];
 	pendingContent?: AssistantMessage["content"];
 	toolResultsById: ReadonlyMap<string, ExternalToolResultPayload>;
 	lastThinkingContent?: string;
@@ -259,6 +260,15 @@ export function buildFinalAssistantContent(params: {
 	const finalContent: AssistantMessage["content"] = mergedToolBlocks.filter(
 		(block) => !shouldSuppressDuplicateToolUnavailableBlock(block, mergedToolBlocks),
 	);
+	// Emit prose/thinking captured at earlier turn-boundaries (each successive
+	// `ask_user_questions` elicitation completes a turn) before the final
+	// segment. Capturing these in an ordered accumulator — symmetric with
+	// `intermediateToolBlocks` — is what keeps intermediate explanations from
+	// being collapsed to a single overwritten scalar and silently dropped.
+	const intermediateTextBlocks = params.intermediateTextBlocks ?? [];
+	for (const block of intermediateTextBlocks) {
+		finalContent.push(block);
+	}
 	if (params.pendingContent && params.pendingContent.length > 0) {
 		for (const block of params.pendingContent) {
 			if (block.type === "text" || block.type === "thinking") {
@@ -266,11 +276,29 @@ export function buildFinalAssistantContent(params: {
 			}
 		}
 	} else {
+		// No builder content survived to this turn boundary, so fall back to the
+		// last scalar thinking/text captured off the stream. When the turn ends
+		// on an elicitation these scalars just mirror the final intermediate
+		// block (they are overwritten at each synthetic-user boundary), so only
+		// emit them when they carry content not already accumulated — otherwise
+		// a non-streaming `assistant` message's prose/thinking is silently lost.
+		const lastBlockOfType = (type: "text" | "thinking") => {
+			for (let i = intermediateTextBlocks.length - 1; i >= 0; i--) {
+				if (intermediateTextBlocks[i].type === type) return intermediateTextBlocks[i];
+			}
+			return undefined;
+		};
 		if (params.lastThinkingContent) {
-			finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
+			const lastThinking = lastBlockOfType("thinking") as { thinking?: string } | undefined;
+			if (lastThinking?.thinking !== params.lastThinkingContent) {
+				finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
+			}
 		}
 		if (params.lastTextContent) {
-			finalContent.push({ type: "text", text: params.lastTextContent });
+			const lastText = lastBlockOfType("text") as { text?: string } | undefined;
+			if (lastText?.text !== params.lastTextContent) {
+				finalContent.push({ type: "text", text: params.lastTextContent });
+			}
 		}
 	}
 

package/src/resources/extensions/gsd/artifact-verification.ts

@@ -22,6 +22,7 @@ import {
   resolveSliceFile,
   resolveTasksDir,
   resolveTaskFiles,
+  resolveTaskFile,
   relSliceFile,
   resolveMilestoneFile,
   clearPathCache,
@@ -223,15 +224,9 @@ export function verifyExpectedArtifact(
     const batchIds = batchPart.slice(plusIdx + 1).split(",").filter(Boolean);
     if (batchIds.length === 0) return false;
 
-    const tDir = resolveTasksDir(base, mid, sid) ?? slicePath;
-    const existingSummaries = new Set(
-      resolveTaskFiles(tDir, "SUMMARY").map((f) =>
-        f.replace(/-SUMMARY\.md$/i, "").toUpperCase(),
-      ),
-    );
-
     for (const tid of batchIds) {
-      if (!existingSummaries.has(tid.toUpperCase())) return false;
+      const summaryPath = resolveTaskFile(base, mid, sid, tid, "SUMMARY");
+      if (!summaryPath || !existsSync(summaryPath)) return false;
     }
     return true;
   }

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

@@ -355,7 +355,41 @@ async function enforceMinRequestInterval(s: AutoSession, prefs: IterationContext
   }
 }
 
-function closeOutCrashedUnit(s: AutoSession, iterData: IterationData, err: unknown): void {
+async function snapshotCrashedUnitWork(
+  ctx: ExtensionContext,
+  s: AutoSession,
+  deps: LoopDeps,
+  iterData: IterationData,
+): Promise<void> {
+  try {
+    const commitMsg = await deps.autoCommitUnit?.(
+      s.basePath,
+      iterData.unitType,
+      iterData.unitId,
+      ctx,
+    );
+    if (commitMsg) {
+      debugLog("autoLoop", {
+        phase: "crash-snapshot-commit",
+        unitType: iterData.unitType,
+        unitId: iterData.unitId,
+      });
+    }
+  } catch (snapshotErr) {
+    logWarning(
+      "dispatch",
+      `unit crash snapshot failed: ${snapshotErr instanceof Error ? snapshotErr.message : String(snapshotErr)}`,
+    );
+  }
+}
+
+async function closeOutCrashedUnit(
+  ctx: ExtensionContext,
+  s: AutoSession,
+  deps: LoopDeps,
+  iterData: IterationData,
+  err: unknown,
+): Promise<void> {
   const summary = formatDispatchExceptionSummary({ error: err });
   try {
     emitOpenUnitEndForUnit(
@@ -383,6 +417,7 @@ function closeOutCrashedUnit(s: AutoSession, iterData: IterationData, err: unkno
   } catch (closeoutErr) {
     logWarning("dispatch", `unit crash closeout failed: ${closeoutErr instanceof Error ? closeoutErr.message : String(closeoutErr)}`);
   }
+  await snapshotCrashedUnitWork(ctx, s, deps, iterData);
 }
 
 /**
@@ -526,11 +561,20 @@ export async function autoLoop(
       active: s.active,
       iteration,
       maxIterations: MAX_LOOP_ITERATIONS,
-      hasCommandContext: Boolean(s.cmdCtx),
+      hasCommandContext: typeof s.cmdCtx?.newSession === "function",
       sessionLockValid: true,
     });
     if (commandContextDecision.action === "stop" && commandContextDecision.reason === "missing-command-context") {
       debugLog("autoLoop", { phase: "exit", reason: "no-cmdCtx" });
+      if (s.currentUnit) {
+        await deps.autoCommitUnit?.(
+          s.basePath,
+          s.currentUnit.type,
+          s.currentUnit.id,
+          ctx,
+        );
+      }
+      await deps.stopAuto(ctx, pi, commandContextDecision.message, { preserveWorktree: true });
       finishTurn("stopped", "manual-attention", commandContextDecision.reason);
       break;
     }
@@ -730,7 +774,7 @@ export async function autoLoop(
           if (err instanceof ModelPolicyDispatchBlockedError) {
             throw err;
           }
-          closeOutCrashedUnit(s, iterData, err);
+          await closeOutCrashedUnit(ctx, s, deps, iterData, err);
           throw err;
         }
         if (unitPhaseResult.action === "next") {
@@ -1285,7 +1329,7 @@ export async function autoLoop(
         if (err instanceof ModelPolicyDispatchBlockedError) {
           throw err;
         }
-        closeOutCrashedUnit(s, iterData, err);
+        await closeOutCrashedUnit(ctx, s, deps, iterData, err);
         dispatchSettled = settleDispatchFailed(
           dispatchId,
           formatDispatchExceptionSummary({ error: err }),

package/src/resources/extensions/gsd/auto/run-unit.ts

@@ -91,6 +91,25 @@ export async function runUnit(
   // ── Session creation with timeout ──
   debugLog("runUnit", { phase: "session-create", unitType, unitId });
 
+  const cmdCtx = s.cmdCtx;
+  if (typeof cmdCtx?.newSession !== "function") {
+    const msg = "command context is missing newSession";
+    debugLog("runUnit", {
+      phase: "session-error",
+      unitType,
+      unitId,
+      error: msg,
+    });
+    return {
+      status: "cancelled",
+      errorContext: {
+        message: `Session creation failed: ${msg}`,
+        category: "session-failed",
+        isTransient: false,
+      },
+    };
+  }
+
   let sessionResult: { cancelled: boolean };
   let sessionTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
   const mySessionSwitchGeneration = ++sessionSwitchGeneration;
@@ -100,7 +119,7 @@ export async function runUnit(
   const sessionAbortController = new AbortController();
   _setSessionSwitchInFlight(true);
   try {
-    const sessionPromise = s.cmdCtx!.newSession({
+    const sessionPromise = cmdCtx.newSession({
       abortSignal: sessionAbortController.signal,
       workspaceRoot: s.basePath,
     }).finally(() => {