gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

package/README.md

@@ -27,34 +27,70 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.77
+## What's New in v2.78
 
-### Context Mode & Execution
+### Worktree Lifecycle & Forensics
 
-- **Context Mode** — a dispatch behavior that builds task-ready context automatically: it pulls in the most relevant project artifacts, prior session state, milestone/slice signals, and execution metadata before the model runs. This reduces manual prompt assembly, improves continuity across turns, and helps tasks start with the right files and constraints from the first dispatch. Enabled by default for new projects (opt out with `enabled: false`).
-- **Sandboxed execution tools** — added `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output execution paths for context-mode flows, so search/resume and follow-up execution can run with tighter boundaries and more predictable runtime behavior.
-- **Preflight hardening** — milestone completion now performs stricter clean-root preflight checks and can auto-stash when needed, reducing accidental dirty-tree transitions and helping completion flows fail fast with clearer remediation.
+- **Slice-cadence worktree collapse (#4765)** — new `git.collapse_cadence: "milestone" | "slice"` preference. With `slice`, each validated slice squash-merges to main immediately, shrinking the orphan window from milestone-size to slice-size. Pair with `git.milestone_resquash: true` to collapse per-slice commits into one milestone commit at completion.
+- **Worktree telemetry (#4764)** — new journal events (`worktree-created`, `worktree-merged`, `worktree-orphaned`, `auto-exit`, `canonical-root-redirect`, `slice-merged`, `milestone-resquash`) and a `summarizeWorktreeTelemetry` aggregator that reports orphan breakdowns, merge durations, conflict counts, exit reasons, and unmerged-exit metrics.
+- **`/gsd forensics` worktree section** — surfaces the telemetry above with two new anomalies: `worktree-orphan` and `worktree-unmerged-exit`.
+- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators and cross-session readers through the live worktree, so milestone validation no longer silently reads stale project-root state.
+- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main no longer get skipped; the audit emits a warning with commit count and worktree location so interrupted auto-runs are visible.
 
-### Memory Architecture (ADR-013)
+### Auto Pipeline & Component System
 
-- **Memories table is now authoritative** — all memory reads and writes now flow through the `memories` table as the single source of truth. By removing split legacy paths, memory state stays consistent across agents, tools, and UI surfaces, with fewer reconciliation edge cases and less sync drift.
-- **Structured memory fields** — `structured_fields` adds typed metadata (instead of only free-form text), so memories can carry machine-usable attributes for more accurate retrieval, stronger filtering, and more dependable downstream automation and tooling.
-- **Dual-write migration completed** — the staged migration that wrote to both old and new paths is now fully landed, including decisions backfill and parity wiring across agents, MCP tools, and extract-learnings flows. That gives a safer upgrade path while preserving historical data and reducing cutover risk.
+- **Unified component system** — skills, agents, pipelines, and marketplace are now one component model wired through runtime, dispatch, and telemetry, replacing per-surface plumbing.
+- **UnitContextManifest v2 (#4924, #4934)** — auto dispatch runs through a typed manifest with declarative tools-policy and typed computed artifacts. CI guards the schema so drift fails fast.
+- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, and `reassess-roadmap` now build context through the manifest composer for a consistent shape across units.
+- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape, so research-heavy and execution-heavy milestones no longer share a one-size dispatch path.
+- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on, with manifests expanded across the remaining types.
+- **Single-writer-v3 control plane** — closes outstanding gaps in the durable-state writer model so concurrent writers can't desync workflow state.
+- **Opt-in `reassess-roadmap` (#4778)** — gated behind the `skip_clean_reassess` preference per ADR-003 §4; auto no longer triggers reassessment unprompted.
 
-### Skills, Tooling, and UX
+### Extensions Framework
 
-- **Skill coverage expanded** — 9 gap-closing skills landed and 6 planning/design skills were surfaced, improving end-to-end workflow coverage and making specialized guidance easier to discover at the point of use.
-- **Hook stack upgrades** — Layer 0 shell hooks and additional Layer 2 events were added to widen extension integration points: hooks can act earlier in command execution, and lifecycle consumers now receive richer event signals for orchestration, policy checks, and observability.
-- **TUI polish** — skill invocations now render in a dedicated chat-frame style for clearer scanability, and active-row overflow handling was fixed to prevent terminal layout breakage during long outputs.
+- **Extension lifecycle commands** — `gsd extensions install / update / uninstall / list / info / validate` for npm, git, and local sources, with dependency warnings and user-metadata tracking.
+- **Topological extension load order** — Kahn's-algorithm sort with surfaced `ExtensionLoadWarning`s, so dependent extensions resolve deterministically and misconfigurations are visible instead of silent.
+- **cmux ↔ gsd decoupling** — static cross-imports replaced with a shared `cmux-events` contract and dynamic imports, isolating extension boundaries.
+- **Extracted `@gsd-extensions/google-search` workspace** — first reference extension carved out of core; legacy in-tree source replaced with a deprecation stub.
+
+### Models, Agent, and UX
+
+- **GPT-5.5 Codex support** — added across `gsd` and `pi-ai`, including `xhigh` thinking level for custom GPT-5.5 models.
+- **Auth mode in `/model`** — providers display alongside auth mode for clearer routing.
+- **Permission granularity picker** — Claude Code "Always Allow" prompts let you scope the grant instead of approving the broad case.
+- **Headless auto default → `bypassPermissions` (#4657)** — Claude Code CLI headless auto-mode runs without permission prompts by default.
+- **`skillFilter` for system prompts** — `pi-coding-agent` filters which skills are surfaced in `buildSystemPrompt`, with consumer exceptions guarded.
+- **Visual postinstall (#4641)** — install shows a spinner/banner UX so first-run state is legible.
+- **PR-risk verification** — risk prompt emits a copy-pasteable code block to make follow-up commands one step.
 
 ### Reliability & Safety
 
-- **Worktree and dispatch resilience** — crash-recovery dispatch is more robust, path derivation is safer, and worktree context fallback is improved, reducing stuck states and misrouted artifact operations after interruptions.
-- **DB/schema guardrails** — migration/index ordering and schema version stamping were tightened so upgrades apply deterministically and avoid index/version drift across mixed or legacy states.
-- **Security and validation fixes** — multiple hardening fixes landed across redaction paths, file/path checks, and pre-execution validation, closing false-positive/false-negative gaps while improving safety boundaries.
+- **Major git-safety pass** — clarified TOCTOU ancestry guard, atomic sync-lock acquire with PID-verified stale override, `.git/index.lock` force-removal gated by 5-min age, `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE` stripped from env overlays, rebase/cherry-pick/revert state detected and aborted in recovery, working tree stashed before `reset --hard` in self-heal/rollback, worktree create guarded against unborn branches, and user hooks + `commit.gpgsign` honored on auto-commits.
+- **Atomic `.gsd/` state writes** — file-locks now actually lock and throw on contention; appends are lock-wrapped to prevent interleaved writes.
+- **Compaction correctness (#4665)** — fixed chunker/truncation mismatch and silent chunk-drops that produced degenerate or empty summaries.
+- **Write-gate (#4950)** — fail-closed depth confirmation, EXDEV-safe snapshot rename, opt-out persistence default, off-by-one max-attempts fix, exception capture in `gate.execute`, and audit/DB rows for unknown gate ids.
+- **Auto state machine** — deterministic policy errors classified non-retriable (#4973), depth-verification bypass for non-interactive sessions, baseline restored between units (#4961), `restoreToolBaseline` gated by `isAutoMode` (#4966).
+- **Slice + crash recovery** — slice orchestrator state persists across crashes; ancestry-guarded force-reset, detached-HEAD refusal, and stash-by-ref recovery.
+- **Empty-turn recovery** — Claude Code CLI tool-block shape canonicalized so empty-turn recovery matches real provider output.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
+<details>
+<summary>v2.77 highlights</summary>
+
+- **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
+- **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
+- **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
+- **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
+- **Worktree + dispatch resilience** — crash-recovery dispatch hardened, safer path derivation, improved worktree context fallback
+- **DB/schema guardrails** — migration/index ordering and schema version stamping tightened
+- **Preflight hardening** — milestone completion enforces stricter clean-root checks with auto-stash
+
+</details>
+
 <details>
 <summary>v2.75 highlights</summary>
 
@@ -288,7 +324,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

@@ -20,33 +20,71 @@ export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'cla
  * expose a bare `claude` shim. Try all three so no valid install is missed.
  */
 const CLAUDE_COMMAND_CANDIDATES = process.platform === 'win32' ? [CLAUDE_COMMAND, 'claude.exe', 'claude'] : [CLAUDE_COMMAND];
+// Codes treated as "this candidate didn't run — try the next one" rather than
+// fatal failures. ETIMEDOUT/EAGAIN cover slow-spawn cases on Windows where
+// cmd.exe wrapping plus the Claude CLI startup path together exceed the
+// per-attempt timeout (Issue #4997 regression on Windows + Node 25).
+const SOFT_FAIL_CODES = new Set(['ENOENT', 'EINVAL', 'ETIMEDOUT', 'EAGAIN']);
+const VERSION_TIMEOUT_MS = 5_000;
+// Auth probe needs more headroom on Windows because the spawn goes through
+// cmd.exe → claude.cmd → node → Claude CLI.
+const AUTH_TIMEOUT_MS = 15_000;
 /**
  * Try to run `args` against each candidate binary.
  * Returns the output buffer on first success, throws the last error if all fail.
  */
-function execClaudeCheck(args) {
+function execClaudeCheck(args, timeoutMs) {
     let lastError;
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, { timeout: 5_000, stdio: 'pipe' });
+            return execFileSync(command, args, {
+                timeout: timeoutMs,
+                stdio: 'pipe',
+                shell: process.platform === 'win32',
+            });
         }
         catch (error) {
             lastError = error;
             const code = error?.code;
-            // EINVAL can surface on Windows Git Bash for .cmd spawn failures.
-            if (code === 'ENOENT' || code === 'EINVAL')
+            if (code && SOFT_FAIL_CODES.has(code))
                 continue;
             throw error;
         }
     }
     throw lastError ?? new Error(`Claude CLI not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(', ')})`);
 }
+/**
+ * Decide auth state from `claude auth status` output.
+ *
+ * Newer Claude CLI builds emit JSON with a `loggedIn` boolean. Older builds
+ * emit free-form text. Prefer the structured signal; fall back to a text
+ * heuristic. The text heuristic only covers English phrasing.
+ */
+function parseAuthStatus(output) {
+    const trimmed = output.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.loggedIn === 'boolean') {
+                return parsed.loggedIn;
+            }
+        }
+        catch {
+            // Fall through to text heuristic.
+        }
+    }
+    const lower = trimmed.toLowerCase();
+    if (/not logged in|no credentials|unauthenticated|not authenticated/.test(lower)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */
 export function isClaudeBinaryInstalled() {
     try {
-        execClaudeCheck(['--version']);
+        execClaudeCheck(['--version'], VERSION_TIMEOUT_MS);
         return true;
     }
     catch {
@@ -58,16 +96,14 @@ export function isClaudeBinaryInstalled() {
  */
 export function isClaudeCliReady() {
     try {
-        execClaudeCheck(['--version']);
+        execClaudeCheck(['--version'], VERSION_TIMEOUT_MS);
     }
     catch {
         return false;
     }
     try {
-        const output = execClaudeCheck(['auth', 'status'])
-            .toString()
-            .toLowerCase();
-        return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));
+        const output = execClaudeCheck(['auth', 'status', '--json'], AUTH_TIMEOUT_MS).toString();
+        return parseAuthStatus(output);
     }
     catch {
         return false;

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`,
 			);
-		});
-	}
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------