gsd-pi 2.77.0-dev.58d3d4d6c → 2.77.0-dev.cfd69e714

package/README.md

@@ -288,7 +288,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
 
-6. **Stuck detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). On detection, it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
+6. **Stuck and artifact detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.
 
 7. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
 

package/dist/claude-cli-check.js

@@ -28,7 +28,11 @@ function execClaudeCheck(args) {
     let lastError;
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, { timeout: 5_000, stdio: 'pipe' });
+            return execFileSync(command, args, {
+                timeout: 5_000,
+                stdio: 'pipe',
+                shell: process.platform === 'win32',
+            });
         }
         catch (error) {
             lastError = error;

package/dist/headless.js

@@ -11,7 +11,7 @@
  *   10 — blocked (command reported a blocker)
  *   11 — cancelled (SIGINT/SIGTERM received)
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, writeSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolve } from 'node:path';
 import { RpcClient, SessionManager } from '@gsd/pi-coding-agent';
@@ -250,6 +250,30 @@ async function runHeadlessOnce(options, restartCount) {
         const result = await handleQuery(process.cwd());
         return { exitCode: result.exitCode, interrupted: false };
     }
+    // Doctor: read-only health check, no RPC child needed (#4904 live-regression).
+    // The interactive `/gsd doctor` command lives in the GSD extension; this CLI
+    // path lets non-interactive callers (CI, recovery scripts, the live-regression
+    // suite) get the same diagnostic without a TTY.
+    if (options.command === 'doctor') {
+        const wantsJson = options.json || options.commandArgs.includes('--json');
+        const { runGSDDoctor } = await import('./resources/extensions/gsd/doctor.js');
+        const { formatDoctorReport, formatDoctorReportJson } = await import('./resources/extensions/gsd/doctor-format.js');
+        let exitCode = 1;
+        try {
+            const report = await runGSDDoctor(process.cwd());
+            const out = wantsJson ? formatDoctorReportJson(report) : formatDoctorReport(report);
+            process.stdout.write(`${out}\n`);
+            exitCode = report.ok ? 0 : 1;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[headless] doctor failed: ${msg}\n`);
+            exitCode = 1;
+        }
+        // Bypass the auto-restart loop in runHeadless — doctor is a one-shot
+        // diagnostic; exit 1 means "issues detected", not "crashed".
+        process.exit(exitCode);
+    }
     // Resolve CLI path for the child process
     const cliPath = process.env.GSD_BIN_PATH || process.argv[1];
     if (!cliPath) {
@@ -616,7 +640,15 @@ async function runHeadlessOnce(options, restartCount) {
     });
     // Signal handling
     const signalHandler = () => {
-        process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        // Use writeSync on fd 2 to guarantee the Interrupted marker reaches
+        // consumers before process.exit() truncates pending async writes.
+        try {
+            writeSync(2, '\n[headless] Interrupted, stopping child process...\n');
+        }
+        catch {
+            // Fallback to async write if fd 2 is somehow unavailable.
+            process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        }
         interrupted = true;
         exitCode = EXIT_CANCELLED;
         // Kill child process — don't await, just fire and exit.
@@ -635,8 +667,21 @@ async function runHeadlessOnce(options, restartCount) {
         }
         process.exit(exitCode);
     };
-    process.on('SIGINT', signalHandler);
-    process.on('SIGTERM', signalHandler);
+    // Use prependListener so our handler runs before pi-coding-agent's
+    // LSP-client module-load SIGINT handler, which calls process.exit(0)
+    // and would otherwise short-circuit our exit-code-11 contract.
+    process.prependListener('SIGINT', signalHandler);
+    process.prependListener('SIGTERM', signalHandler);
+    // Emit a deterministic readiness marker so test harnesses can wait for
+    // the SIGINT handler to be live before sending a signal. writeSync on
+    // fd 2 avoids any pipe-buffering race between the marker and subsequent
+    // signal delivery.
+    try {
+        writeSync(2, '[headless] signal-handlers-ready\n');
+    }
+    catch {
+        process.stderr.write('[headless] signal-handlers-ready\n');
+    }
     // Start the RPC session
     try {
         await client.start();

package/dist/resource-loader.d.ts

@@ -2,7 +2,47 @@ import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 export { discoverExtensionEntryPaths } from './extension-discovery.js';
 export declare function getExtensionKey(entryPath: string, extensionsDir: string): string;
 export declare function readManagedResourceVersion(agentDir: string): string | null;
+/**
+ * Computes a content fingerprint of a resources directory (defaults to the
+ * bundled resourcesDir).
+ *
+ * Walks all files under `rootDir` and hashes `${relativePath}:${sha256(contents)}`
+ * for each one. Using the file *contents* — not size — is what distinguishes
+ * this from the earlier implementation and closes #4787: a same-size edit
+ * (e.g. swapping one word for another word of the same byte length) produces
+ * a different file hash, bumps the aggregate fingerprint, and therefore
+ * triggers a full resync in `initResources`. The old path+size approach
+ * silently cached stale prompts across upgrades.
+ *
+ * Cost is ~1-2ms for a typical resources tree (~100 small .md files) —
+ * still negligible at startup. Files are streamed via `readFileSync` but
+ * bundled prompts are tiny so this is fine.
+ *
+ * Exported for unit tests and for callers that want to check a different
+ * directory (e.g. pre-install verification).
+ */
+export declare function computeResourceFingerprint(rootDir?: string): string;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
+/**
+ * Syncs a single bundled resource directory into the agent directory.
+ *
+ * 1. Makes the destination writable (handles Nix store read-only copies).
+ * 2. Removes destination subdirs that exist in source to clear stale files,
+ *    while preserving user-created directories.
+ * 3. Copies source into destination.
+ * 4. Makes the result writable for the next upgrade cycle.
+ */
+export declare function syncResourceDir(srcDir: string, destDir: string): void;
+/** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
+export declare function hasMissingWorkspaceScopes(hoisted: string, internal: string): boolean;
+/**
+ * Create a real node_modules directory containing symlinks from both the
+ * hoisted root (external deps) and internal root (@gsd/* workspace packages).
+ * Used for pnpm global installs where @gsd/* isn't hoisted.
+ */
+export declare function reconcileMergedNodeModules(agentNodeModules: string, hoisted: string, internal: string): void;
+/** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
+export declare function mergedFingerprint(hoisted: string, internal: string): string;
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *

package/dist/resource-loader.js

@@ -101,17 +101,27 @@ function readManagedResourceManifest(agentDir) {
     }
 }
 /**
- * Computes a lightweight content fingerprint of the bundled resources directory.
+ * Computes a content fingerprint of a resources directory (defaults to the
+ * bundled resourcesDir).
  *
- * Walks all files under resourcesDir and hashes their relative paths + sizes.
- * This catches same-version content changes (npm link dev workflow, hotfixes
- * within a release) without the cost of reading every file's contents.
+ * Walks all files under `rootDir` and hashes `${relativePath}:${sha256(contents)}`
+ * for each one. Using the file *contents* — not size — is what distinguishes
+ * this from the earlier implementation and closes #4787: a same-size edit
+ * (e.g. swapping one word for another word of the same byte length) produces
+ * a different file hash, bumps the aggregate fingerprint, and therefore
+ * triggers a full resync in `initResources`. The old path+size approach
+ * silently cached stale prompts across upgrades.
  *
- * ~1ms for a typical resources tree (~100 files) — just stat calls, no reads.
+ * Cost is ~1-2ms for a typical resources tree (~100 small .md files) —
+ * still negligible at startup. Files are streamed via `readFileSync` but
+ * bundled prompts are tiny so this is fine.
+ *
+ * Exported for unit tests and for callers that want to check a different
+ * directory (e.g. pre-install verification).
  */
-function computeResourceFingerprint() {
+export function computeResourceFingerprint(rootDir = resourcesDir) {
     const entries = [];
-    collectFileEntries(resourcesDir, resourcesDir, entries);
+    collectFileEntries(rootDir, rootDir, entries);
     entries.sort();
     return createHash('sha256').update(entries.join('\n')).digest('hex').slice(0, 16);
 }
@@ -125,8 +135,17 @@ function collectFileEntries(dir, root, out) {
         }
         else {
             const rel = relative(root, fullPath);
-            const size = statSync(fullPath).size;
-            out.push(`${rel}:${size}`);
+            // Hash the file contents — see function doc for #4787 rationale.
+            let contentHash;
+            try {
+                contentHash = createHash('sha256').update(readFileSync(fullPath)).digest('hex');
+            }
+            catch {
+                // Unreadable file — fall back to a stable marker so the entry still
+                // contributes to the aggregate hash and future reads will re-hash.
+                contentHash = 'unreadable';
+            }
+            out.push(`${rel}:${contentHash}`);
         }
     }
 }
@@ -188,7 +207,7 @@ function makeTreeWritable(dirPath) {
  * 3. Copies source into destination.
  * 4. Makes the result writable for the next upgrade cycle.
  */
-function syncResourceDir(srcDir, destDir) {
+export function syncResourceDir(srcDir, destDir) {
     makeTreeWritable(destDir);
     if (existsSync(srcDir)) {
         pruneStaleSiblingFiles(srcDir, destDir);
@@ -282,7 +301,7 @@ function ensureNodeModulesSymlink(agentDir) {
     reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
 }
 /** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
-function hasMissingWorkspaceScopes(hoisted, internal) {
+export function hasMissingWorkspaceScopes(hoisted, internal) {
     if (!existsSync(internal))
         return false;
     try {
@@ -326,7 +345,7 @@ function reconcileSymlink(link, target) {
  * hoisted root (external deps) and internal root (@gsd/* workspace packages).
  * Used for pnpm global installs where @gsd/* isn't hoisted.
  */
-function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
+export function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
     // Fast path: if already merged for this packageRoot + same directory contents, skip.
     // The fingerprint includes entry names from both roots so `pnpm add/remove` triggers rebuild.
     const marker = join(agentNodeModules, '.gsd-merged');
@@ -400,7 +419,7 @@ function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
     }
 }
 /** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
-function mergedFingerprint(hoisted, internal) {
+export function mergedFingerprint(hoisted, internal) {
     try {
         const h = readdirSync(hoisted).sort().join(',');
         const i = readdirSync(internal).sort().join(',');

package/dist/resources/extensions/browser-tools/capture.js

@@ -21,6 +21,15 @@ async function getSharp() {
     }
     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) {
+    _sharp = value;
+}
 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

package/dist/resources/extensions/browser-tools/tests/browser-tools-integration.test.mjs

@@ -12,76 +12,25 @@
 import { describe, it, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { chromium } from "playwright";
-import { readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, "..");
 
 // ---------------------------------------------------------------------------
-// Source extraction — get the IIFE strings we need for injection
+// Source loading — import the IIFE builders directly via jiti.
+// The test-only named exports in tools/intent.ts and tools/forms.ts exist
+// exactly so this test can call the real, in-tree builders. No brace
+// walking, no regex stripping — a refactor of the signatures just updates
+// the import surface, not the test.
 // ---------------------------------------------------------------------------
 
-// 1. EVALUATE_HELPERS_SOURCE — exported constant, extract via jiti
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const jiti = require("jiti")(__dirname, { interopDefault: true, debug: false });
 const { EVALUATE_HELPERS_SOURCE } = jiti("../evaluate-helpers.ts");
-
-// 2. Intent scoring — module-private buildIntentScoringScript.
-//    Extract the function from source, wrap it, and eval to get the builder.
-const intentSource = readFileSync(resolve(ROOT, "tools/intent.ts"), "utf-8");
-
-function extractBuildIntentScoringScript() {
-  // Match the function body: starts with "function buildIntentScoringScript"
-  // and returns a template literal string. We extract up to the matching closing brace.
-  const startMarker = "function buildIntentScoringScript(intent: string, scope?: string): string {";
-  const startIdx = intentSource.indexOf(startMarker);
-  if (startIdx === -1) throw new Error("Could not find buildIntentScoringScript in intent.ts");
-
-  // Walk from start, counting braces to find the end
-  let depth = 0;
-  let foundFirst = false;
-  let endIdx = startIdx;
-  for (let i = startIdx; i < intentSource.length; i++) {
-    if (intentSource[i] === "{") { depth++; foundFirst = true; }
-    if (intentSource[i] === "}") depth--;
-    if (foundFirst && depth === 0) { endIdx = i + 1; break; }
-  }
-
-  let fnBody = intentSource.slice(startIdx, endIdx);
-  // Strip TypeScript type annotations
-  fnBody = fnBody.replace(/\(intent:\s*string,\s*scope\?:\s*string\):\s*string/, "(intent, scope)");
-  return new Function("return " + fnBody)();
-}
-
-const buildIntentScoringScript = extractBuildIntentScoringScript();
-
-// 3. Form analysis — module-private buildFormAnalysisScript.
-const formsSource = readFileSync(resolve(ROOT, "tools/forms.ts"), "utf-8");
-
-function extractBuildFormAnalysisScript() {
-  const startMarker = "function buildFormAnalysisScript(selector?: string): string {";
-  const startIdx = formsSource.indexOf(startMarker);
-  if (startIdx === -1) throw new Error("Could not find buildFormAnalysisScript in forms.ts");
-
-  let depth = 0;
-  let foundFirst = false;
-  let endIdx = startIdx;
-  for (let i = startIdx; i < formsSource.length; i++) {
-    if (formsSource[i] === "{") { depth++; foundFirst = true; }
-    if (formsSource[i] === "}") depth--;
-    if (foundFirst && depth === 0) { endIdx = i + 1; break; }
-  }
-
-  let fnBody = formsSource.slice(startIdx, endIdx);
-  // Strip TypeScript type annotation
-  fnBody = fnBody.replace(/\(selector\?:\s*string\):\s*string/, "(selector)");
-  return new Function("return " + fnBody)();
-}
-
-const buildFormAnalysisScript = extractBuildFormAnalysisScript();
+const { buildIntentScoringScript } = jiti("../tools/intent.ts");
+const { buildFormAnalysisScript } = jiti("../tools/forms.ts");
 
 // ---------------------------------------------------------------------------
 // Browser lifecycle

package/dist/resources/extensions/browser-tools/tests/browser-tools-unit.test.cjs

@@ -387,32 +387,44 @@ describe("formatArtifactTimestamp", () => {
 // ---------------------------------------------------------------------------
 
 describe("EVALUATE_HELPERS_SOURCE", () => {
-	it("is a parseable string (valid JavaScript)", () => {
-		assert.doesNotThrow(() => {
-			new Function(EVALUATE_HELPERS_SOURCE);
-		});
-	});
+	// Behaviour test: executing the source in a Node vm sandbox must
+	// populate a `window.__pi` namespace with every expected helper.
+	// No source grep — we actually run the code and verify the resulting
+	// object shape.
+	it("executing the source assigns all expected helpers to window.__pi", () => {
+		const vm = require("node:vm");
+		const expectedFunctions = [
+			"cssPath",
+			"simpleHash",
+			"isVisible",
+			"isEnabled",
+			"inferRole",
+			"accessibleName",
+			"isInteractiveEl",
+			"domPath",
+			"selectorHints",
+		];
 
-	const expectedFunctions = [
-		"cssPath",
-		"simpleHash",
-		"isVisible",
-		"isEnabled",
-		"inferRole",
-		"accessibleName",
-		"isInteractiveEl",
-		"domPath",
-		"selectorHints",
-	];
-
-	for (const fnName of expectedFunctions) {
-		it(`contains assignment for pi.${fnName}`, () => {
-			assert.ok(
-				EVALUATE_HELPERS_SOURCE.includes(`pi.${fnName} = function`),
-				`Expected pi.${fnName} = function assignment in source`,
+		// Playwright evaluates the source in a page context where `window`
+		// exists, so the helpers attach to `window.__pi`. Provide a minimal
+		// window stub in a vm context so we avoid polluting the test globals.
+		const sandbox = { window: {} };
+		const script = new vm.Script(EVALUATE_HELPERS_SOURCE);
+		script.runInNewContext(sandbox, { timeout: 1000 });
+
+		assert.ok(
+			sandbox.window.__pi && typeof sandbox.window.__pi === "object",
+			"executing EVALUATE_HELPERS_SOURCE must assign window.__pi",
+		);
+
+		for (const fnName of expectedFunctions) {
+			assert.equal(
+				typeof sandbox.window.__pi[fnName],
+				"function",
+				`window.__pi.${fnName} must be a function after executing the source`,
 			);
-		});
-	}
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------

package/dist/resources/extensions/browser-tools/tests/capture-sharp-optional.test.cjs

@@ -1,93 +1,91 @@
 /**
  * Regression tests for the optional sharp dependency in capture.ts.
  *
- * Verifies two things:
- *   1. Static: the lazy-load pattern is structurally correct in the source.
- *   2. Behavioral: constrainScreenshot returns the raw buffer unchanged when
- *      sharp is unavailable, rather than throwing.
+ * Behaviour:
+ *   - constrainScreenshot must fall back to returning the raw buffer
+ *     unchanged when sharp is unavailable, rather than throwing.
+ *   - When sharp IS available, oversized screenshots get resized.
+ *
+ * No source-grep. The test drives the real constrainScreenshot function
+ * after seeding the module-private `_sharp` cache via the test-only
+ * `__setSharpForTesting` export.
  */
 
-const { describe, it } = require("node:test");
+const { describe, it, afterEach } = require("node:test");
 const assert = require("node:assert/strict");
-const { readFileSync } = require("node:fs");
-const { join } = require("node:path");
-
-// ---------------------------------------------------------------------------
-// 1. Static analysis — verify the lazy-load pattern is present in source
-// ---------------------------------------------------------------------------
+const jiti = require("jiti")(__filename, { interopDefault: true, debug: false });
 
-describe("capture.ts — sharp optional lazy-load (static)", () => {
-	const source = readFileSync(
-		join(process.cwd(), "src/resources/extensions/browser-tools/capture.ts"),
-		"utf-8",
-	);
+const { constrainScreenshot, __setSharpForTesting } = jiti("../capture.ts");
 
-	it("does not have a top-level static sharp import", () => {
-		assert.ok(
-			!source.includes('import sharp from "sharp"'),
-			'capture.ts must not contain a top-level `import sharp from "sharp"` — sharp must be loaded lazily',
-		);
+describe("constrainScreenshot — sharp unavailable (null)", () => {
+	afterEach(() => {
+		// Clear the test override so later tests don't inherit a null sharp.
+		__setSharpForTesting(undefined);
 	});
 
-	it("defines a getSharp lazy-loader function", () => {
-		assert.ok(
-			source.includes("async function getSharp()"),
-			"capture.ts must define an async getSharp() lazy-loader",
+	it("returns the raw buffer unchanged when sharp is null", async () => {
+		__setSharpForTesting(null);
+
+		const rawBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]); // PNG magic bytes
+		const result = await constrainScreenshot(null, rawBuffer, "image/png", 80);
+
+		assert.strictEqual(
+			result,
+			rawBuffer,
+			"constrainScreenshot must return the exact same buffer instance when sharp is null",
 		);
 	});
 
-	it("guards constrainScreenshot with a null-sharp early return", () => {
-		assert.ok(
-			source.includes("if (!sharp) return buffer"),
-			"constrainScreenshot must return the raw buffer early when sharp is null",
-		);
+	it("returns the raw buffer unchanged for JPEG input when sharp is null", async () => {
+		__setSharpForTesting(null);
+
+		const rawBuffer = Buffer.from([0xff, 0xd8, 0xff, 0xe0]); // JPEG magic bytes
+		const result = await constrainScreenshot(null, rawBuffer, "image/jpeg", 80);
+
+		assert.strictEqual(result, rawBuffer);
 	});
 });
 
-// ---------------------------------------------------------------------------
-// 2. Behavioral — constrainScreenshot passes through buffer when sharp is null
-// ---------------------------------------------------------------------------
-
-describe("capture.ts — constrainScreenshot with sharp unavailable", () => {
-	it("returns the raw buffer unchanged when sharp is null", async () => {
-		// Simulate what getSharp() returns on platforms without sharp by
-		// directly calling constrainScreenshot through a module whose _sharp
-		// cache has been pre-seeded to null via the module-level variable reset.
-		//
-		// Because jiti caches modules across the test suite we use a fresh
-		// require-cache trick: load capture.ts source manually and evaluate the
-		// constrainScreenshot function with a stub getSharp that always returns null.
-		const captureSource = readFileSync(
-			join(process.cwd(), "src/resources/extensions/browser-tools/capture.ts"),
-			"utf-8",
-		);
+describe("constrainScreenshot — sharp available", () => {
+	afterEach(() => {
+		__setSharpForTesting(undefined);
+	});
 
-		// Verify the guard line is reachable (structural check already done above).
-		// For the behavioral test we use the actual constrainScreenshot imported
-		// via jiti — but we force getSharp() to return null by calling the function
-		// with a very small buffer where sharp IS available. Separately we test the
-		// null path by crafting a minimal wrapper.
-		//
-		// The simplest verifiable behaviour: if the guard `if (!sharp) return buffer`
-		// is present, passing a Buffer through a version of constrainScreenshot where
-		// _sharp=null must return that exact buffer. We verify this by extracting and
-		// running a minimal inline version of the guard logic.
+	it("passes through a small image unchanged (below cap)", async () => {
+		const sharp = require("sharp");
+		const small = await sharp({
+			create: {
+				width: 400,
+				height: 300,
+				channels: 3,
+				background: { r: 128, g: 128, b: 128 },
+			},
+		})
+			.jpeg({ quality: 80 })
+			.toBuffer();
 
-		const rawBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]); // fake PNG header
+		const result = await constrainScreenshot(null, small, "image/jpeg", 80);
+		const meta = await sharp(result).metadata();
+		assert.equal(meta.width, 400, "small images must not be resized");
+		assert.equal(meta.height, 300);
+	});
 
-		// Inline the guard as it appears in capture.ts so the test is coupled to
-		// the actual contract, not an arbitrary helper.
-		async function constrainScreenshotWithNullSharp(buffer) {
-			const sharp = null; // simulates getSharp() returning null
-			if (!sharp) return buffer;
-			// (remainder of constrainScreenshot would run here with a real sharp)
-		}
+	it("resizes an oversized image to within 1568px", async () => {
+		const sharp = require("sharp");
+		const big = await sharp({
+			create: {
+				width: 3000,
+				height: 2000,
+				channels: 3,
+				background: { r: 128, g: 128, b: 128 },
+			},
+		})
+			.jpeg({ quality: 80 })
+			.toBuffer();
 
-		const result = await constrainScreenshotWithNullSharp(rawBuffer);
-		assert.strictEqual(
-			result,
-			rawBuffer,
-			"constrainScreenshot must return the exact same buffer instance when sharp is null",
-		);
+		const result = await constrainScreenshot(null, big, "image/jpeg", 80);
+		const meta = await sharp(result).metadata();
+		assert.ok(meta.width <= 1568, `width ${meta.width} must be <= 1568`);
+		assert.ok(meta.height <= 1568, `height ${meta.height} must be <= 1568`);
 	});
 });

package/dist/resources/extensions/browser-tools/tools/forms.js

@@ -4,7 +4,11 @@ import { setLastActionBeforeState, setLastActionAfterState, } from "../state.js"
  * Runs inside page.evaluate(). Finds the target form, inventories all fields
  * with full label resolution, and returns a structured result.
  */
-function buildFormAnalysisScript(selector) {
+// Exported for tests only (see tests/browser-tools-integration.test.mjs).
+// Keep this function treated as module-private for production call sites —
+// the only legitimate external caller is the Playwright-driven integration
+// suite that needs to evaluate the returned IIFE against real DOM.
+export function buildFormAnalysisScript(selector) {
     // We return a string that will be evaluated in the page context.
     // This avoids serialization issues with passing functions.
     return `(() => {

package/dist/resources/extensions/browser-tools/tools/intent.js

@@ -26,7 +26,11 @@ const INTENTS = [
  * Uses window.__pi utilities (injected via addInitScript) for element
  * metadata — no inline redeclarations.
  */
-function buildIntentScoringScript(intent, scope) {
+// Exported for tests only (see tests/browser-tools-integration.test.mjs).
+// Keep this function treated as module-private for production call sites —
+// the only legitimate external caller is the Playwright-driven integration
+// suite that needs to evaluate the returned IIFE against real DOM.
+export function buildIntentScoringScript(intent, scope) {
     const scopeSelector = JSON.stringify(scope ?? null);
     return `(() => {
 	var pi = window.__pi;

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -27,7 +27,11 @@ function execClaude(args) {
     let lastError;
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, { timeout: 5_000, stdio: "pipe" });
+            return execFileSync(command, args, {
+                timeout: 5_000,
+                stdio: "pipe",
+                shell: process.platform === "win32",
+            });
         }
         catch (error) {
             lastError = error;