@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.822c9439

package/dist/resources/extensions/gsd/unit-registry.js

@@ -22,6 +22,7 @@
 // (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
 // against the registry's `UnitType`) and prompt-template association (still
 // implicit in auto-prompts.ts builders).
+import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
 // ─── Shared tool-name constants (used by registry rows) ──────────────────
 export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
     "gsd_uat_exec",
@@ -37,26 +38,12 @@ export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
     "ls",
     "read",
 ];
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
+/**
+ * Browser tools presented to run-uat. A derived view of the Browser Automation
+ * Contract vocabulary (shared/browser-contract.ts) — the contract module is the
+ * only place browser tool names are declared.
+ */
+export const RUN_UAT_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
 // ─── The registry ─────────────────────────────────────────────────────────
 export const UNIT_REGISTRY = {
     "research-milestone": {

package/dist/resources/extensions/gsd/verdict-parser.js

@@ -128,7 +128,7 @@ export function isValidMilestoneVerdict(verdict) {
  * Extract the UAT type from content, defaulting to `"artifact-driven"`.
  *
  * The `"artifact-driven"` fallback is the original default used throughout
- * the codebase when a UAT file lacks an explicit `## UAT Type` section.
+ * the codebase when a UAT file has no parseable UAT mode declaration.
  */
 export function getUatType(content) {
     return getDeclaredUatType(content);

package/dist/resources/extensions/gsd/verification-verdict.js

@@ -1,5 +1,6 @@
 // Project/App: gsd-pi
 // File Purpose: Host-owned verification verdict policy for auto-mode units.
+export const NO_HOST_CHECKS_FAILURE_CONTEXT = "No runnable host-owned verification command was discovered. Add project verification_commands in .gsd/PREFERENCES.md or a runnable task-plan Verify command, then resume with /gsd next.";
 export function decideVerificationVerdict(unitType, result) {
     if (unitType === "execute-task" && result.discoverySource === "task-plan-prose" && result.checks.length === 0) {
         return {
@@ -14,7 +15,7 @@ export function decideVerificationVerdict(unitType, result) {
             passed: false,
             reason: "no-host-checks",
             retryable: false,
-            failureContext: "No runnable host-owned verification command was discovered. Add project verification_commands or a runnable task-plan Verify command before completing this execute-task.",
+            failureContext: NO_HOST_CHECKS_FAILURE_CONTEXT,
         };
     }
     if (!result.passed) {

package/dist/resources/extensions/gsd/web-app-uat.js

@@ -1,8 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES } from "./uat-policy.js";
 export { detectWebApp };
 function readPackageJson(projectRoot) {
     const packageJsonPath = resolve(projectRoot, "package.json");
@@ -39,24 +41,56 @@ export function findPlaywrightTestScript(projectRoot) {
     }
     return null;
 }
+function describeBrowserToolBacking(engineResolution) {
+    switch (engineResolution.engine) {
+        case "gsd-browser":
+            return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+        case "legacy":
+            return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+        case "off":
+            return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+    }
+}
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE = [
+    {
+        mode: "browser-executable",
+        bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    },
+    {
+        mode: "runtime-executable",
+        bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    },
+    {
+        mode: "mixed",
+        bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    },
+];
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot) {
+export function buildWebAppUatGuidanceBlock(projectRoot, engineResolution) {
     if (!detectWebApp(projectRoot))
         return null;
+    const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+    const browserToolsAvailable = resolvedEngine.engine !== "off";
     const playwrightScript = findPlaywrightTestScript(projectRoot);
     const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
     const lines = [
         "### Web App UAT (detected)",
         "",
-        "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+        describeBrowserToolBacking(resolvedEngine),
         "",
         "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-        "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-        "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-        "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+        ...UAT_MODE_GUIDANCE
+            .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+            .map(({ bullet }) => bullet),
         "",
         "**Planning / closeout rules:**",
         "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -74,7 +108,10 @@ export function buildWebAppUatGuidanceBlock(projectRoot) {
         lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
     }
     else {
-        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command", "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command");
+        if (browserToolsAvailable) {
+            lines.push("- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        }
     }
     return lines.join("\n");
 }

package/dist/resources/extensions/gsd/workflow-event-ledger.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { normalizeWorkflowEventCommand } from "./workflow-event-vocabulary.js";
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+export function resolveWorkflowEventLedgerLocation(basePath, originalProjectRoot) {
+    const contract = resolveGsdPathContract(basePath, originalProjectRoot);
+    return {
+        projectRoot: contract.projectRoot,
+        workRoot: contract.workRoot,
+        projectGsd: contract.projectGsd,
+        worktreeGsd: contract.worktreeGsd,
+        projectLogPath: join(contract.projectGsd, WORKFLOW_EVENT_LOG_FILENAME),
+        worktreeLogPath: contract.worktreeGsd
+            ? join(contract.worktreeGsd, WORKFLOW_EVENT_LOG_FILENAME)
+            : null,
+        isWorktree: contract.isWorktree,
+    };
+}
+export function workflowEventLogPath(basePath) {
+    return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+export function workflowEventArchivePath(basePath, milestoneId) {
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+export function readWorktreeEventLogPath(worktreeBasePath) {
+    const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+    return location.worktreeLogPath ?? location.projectLogPath;
+}
+export function buildWorkflowEvent(event, sessionId) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
+        .digest("hex")
+        .slice(0, 16);
+    return {
+        v: 2,
+        ...event,
+        hash,
+        session_id: sessionId,
+    };
+}
+export function appendWorkflowEvent(basePath, event, sessionId) {
+    const fullEvent = buildWorkflowEvent(event, sessionId);
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    mkdirSync(location.projectGsd, { recursive: true });
+    appendFileSync(location.projectLogPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+    emitWorkflowEventAudit(location.projectRoot, fullEvent);
+    return fullEvent;
+}
+export function writeWorkflowEventLog(basePath, events) {
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    mkdirSync(location.projectGsd, { recursive: true });
+    const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+    atomicWriteSync(location.projectLogPath, content);
+}
+export function writeWorktreeEventLog(worktreeBasePath, events) {
+    const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+    const logPath = location.worktreeLogPath ?? location.projectLogPath;
+    mkdirSync(dirname(logPath), { recursive: true });
+    const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+    atomicWriteSync(logPath, content);
+}
+function emitWorkflowEventAudit(basePath, event) {
+    if (!isUnifiedAuditEnabled())
+        return;
+    try {
+        const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId: event.session_id,
+            category: "orchestration",
+            type: `workflow-event-${normalized}`,
+            payload: {
+                cmd: event.cmd,
+                params: event.params,
+                actor: event.actor,
+                actorName: event.actor_name,
+                triggerReason: event.trigger_reason,
+                eventTs: event.ts,
+                hash: event.hash,
+            },
+        }));
+    }
+    catch {
+        // Best-effort: audit projection must never block the workflow event ledger.
+    }
+}

package/dist/resources/extensions/gsd/workflow-event-vocabulary.js

@@ -0,0 +1,46 @@
+export function normalizeWorkflowEventCommand(cmd) {
+    return typeof cmd === "string" ? cmd.replace(/-/g, "_") : null;
+}
+/**
+ * Workflow progress events are keyed by the domain entity they mutate.
+ * Keep command aliases and conflict identity in this module so replay,
+ * conflict detection, and tests do not each grow their own vocabulary.
+ */
+export function workflowEventEntityKey(event) {
+    const p = event.params;
+    const cmd = normalizeWorkflowEventCommand(event.cmd);
+    if (!cmd)
+        return null;
+    switch (cmd) {
+        case "complete_task":
+        case "start_task":
+        case "skip_task":
+        case "report_blocker":
+        case "record_verification":
+        case "plan_task":
+            return typeof p["taskId"] === "string"
+                ? { type: "task", id: p["taskId"] }
+                : null;
+        case "complete_slice":
+        case "replan_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice", id: p["sliceId"] }
+                : null;
+        case "plan_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice_plan", id: p["sliceId"] }
+                : null;
+        case "complete_milestone":
+        case "plan_milestone":
+            return typeof p["milestoneId"] === "string"
+                ? { type: "milestone", id: p["milestoneId"] }
+                : null;
+        case "save_decision":
+            if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+                return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+            }
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/resources/extensions/gsd/workflow-events.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import { appendWorkflowEvent, workflowEventArchivePath, workflowEventLogPath, } from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Session ID ───────────────────────────────────────────────────────────
 /**
@@ -20,19 +20,7 @@ export function getSessionId() {
  * Creates .gsd directory if needed.
  */
 export function appendEvent(basePath, event) {
-    const hash = createHash("sha256")
-        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-        .digest("hex")
-        .slice(0, 16);
-    const fullEvent = {
-        v: 2,
-        ...event,
-        hash,
-        session_id: ENGINE_SESSION_ID,
-    };
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+    appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 // ─── readEvents ──────────────────────────────────────────────────────────
 /**
@@ -87,8 +75,8 @@ export function findForkPoint(logA, logB) {
  * @returns { archived: number } — count of events moved to archive
  */
 export function compactMilestoneEvents(basePath, milestoneId) {
-    const logPath = join(basePath, ".gsd", "event-log.jsonl");
-    const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+    const logPath = workflowEventLogPath(basePath);
+    const archivePath = workflowEventArchivePath(basePath, milestoneId);
     return withFileLockSync(logPath, () => {
         const allEvents = readEvents(logPath);
         // Single-pass partition to halve the work (per reviewer agent)

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,6 +2,8 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
+import { normalizeWorkflowEventCommand, workflowEventEntityKey, } from "./workflow-event-vocabulary.js";
+import { readWorktreeEventLogPath, workflowEventLogPath, writeWorkflowEventLog, writeWorktreeEventLog, } from "./workflow-event-ledger.js";
 import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
 import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -48,14 +50,11 @@ function replayEvents(events) {
     transaction(() => {
         for (const event of events) {
             const p = event.params;
-            // Normalize cmd format: completion tools write hyphens ("complete-task"),
-            // legacy logs use underscores ("complete_task"). Accept both formats.
-            // Type guard: malformed event lines with non-string cmd are skipped.
-            if (typeof event.cmd !== "string") {
+            const cmd = normalizeWorkflowEventCommand(event.cmd);
+            if (!cmd) {
                 logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
                 continue;
             }
-            const cmd = event.cmd.replace(/-/g, "_");
             switch (cmd) {
                 case "complete_task": {
                     const milestoneId = p["milestoneId"];
@@ -199,43 +198,7 @@ function replayEvents(events) {
  * (e.g. unknown or future cmds).
  */
 export function extractEntityKey(event) {
-    const p = event.params;
-    // Normalize cmd format: accept both hyphens and underscores
-    if (typeof event.cmd !== "string")
-        return null;
-    const cmd = event.cmd.replace(/-/g, "_");
-    switch (cmd) {
-        case "complete_task":
-        case "start_task":
-        case "skip_task":
-        case "report_blocker":
-        case "record_verification":
-        case "plan_task":
-            return typeof p["taskId"] === "string"
-                ? { type: "task", id: p["taskId"] }
-                : null;
-        case "complete_slice":
-        case "replan_slice":
-            return typeof p["sliceId"] === "string"
-                ? { type: "slice", id: p["sliceId"] }
-                : null;
-        case "plan_slice":
-            return typeof p["sliceId"] === "string"
-                ? { type: "slice_plan", id: p["sliceId"] }
-                : null;
-        case "complete_milestone":
-        case "plan_milestone":
-            return typeof p["milestoneId"] === "string"
-                ? { type: "milestone", id: p["milestoneId"] }
-                : null;
-        case "save_decision":
-            if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-                return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-            }
-            return null;
-        default:
-            return null;
-    }
+    return workflowEventEntityKey(event);
 }
 // ─── detectConflicts ──────────────────────────────────────────────────────────
 /**
@@ -302,12 +265,6 @@ function rewriteDivergedEventsForEntity(divergedEvents, entityType, entityId, re
     }
     return rewritten;
 }
-function writeEventLog(basePath, events) {
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-    atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 /**
  * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
@@ -375,10 +332,15 @@ export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
 }
 function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     // Step 1: Read both logs
-    const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(mainBasePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
+    // Canonical worktree appends are already durable in the project ledger.
+    // Empty/missing worktree shards are legacy-only absence, not divergence.
+    if (wtEvents.length === 0) {
+        return { autoMerged: 0, conflicts: [] };
+    }
     // Step 2: Find fork point
     const forkPoint = findForkPoint(mainEvents, wtEvents);
     // Step 3: Slice diverged sets
@@ -412,9 +374,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     }
     const baseEvents = mainEvents.slice(0, forkPoint + 1);
     const mergedLog = baseEvents.concat(merged);
-    const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-    mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-    atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+    writeWorkflowEventLog(mainBasePath, mergedLog);
     // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
     openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
     replayEvents(merged);
@@ -533,8 +493,8 @@ pick) {
         throw new Error(`No conflict found for entity ${entityKey}`);
     const conflict = conflicts[idx];
     const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
-    const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(basePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
     const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -547,7 +507,12 @@ pick) {
         : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay);
     const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
     const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-    writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    if (pick === "main") {
+        writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
+    else {
+        writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
     // Replay resolved events through the DB (updates DB state)
     openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);
     replayEvents(eventsToReplay);

package/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -32,6 +32,7 @@ import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } fr
 // callers — production wiring previously injected them via deps; the seam
 // added type churn without enabling test variation.
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { isolationDegradedFallbackGuidance, worktreeCreationFailedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -343,7 +344,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
                 s.basePath = basePath;
                 rebuildGitService(s, deps);
                 invalidateAllCaches();
-                ctx.notify(`Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`, "warning");
+                ctx.notify(isolationDegradedFallbackGuidance(milestoneId), "warning");
                 return { ok: true, mode: "branch", path: basePath };
             }
             catch (err) {
@@ -517,7 +518,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
             eventType: "worktree-create-failed",
             data: { milestoneId, error: msg, fallback: "project-root" },
         });
-        ctx.notify(`Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`, "warning");
+        ctx.notify(worktreeCreationFailedGuidance(milestoneId, msg), "warning");
         // Degrade isolation for the rest of this session so mergeAndExit
         // doesn't try to merge a nonexistent worktree branch (#2483)
         s.isolationDegraded = true;

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -528,7 +528,13 @@ export function removeWorktree(basePath, name, opts = {}) {
     // inside .gsd/worktrees/ — a symlink inside the directory could point out.
     const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
     // If we're inside the worktree, move out first — git can't remove an in-use directory
-    const cwd = process.cwd();
+    let cwd;
+    try {
+        cwd = process.cwd();
+    }
+    catch {
+        cwd = basePath;
+    }
     const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
     if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
         process.chdir(basePath);

package/dist/resources/extensions/gsd/worktree.js

@@ -195,7 +195,14 @@ export function resolveGitHeadPath(dir) {
  */
 export function nudgeGitBranchCache(previousCwd) {
     const now = new Date();
-    for (const dir of [previousCwd, process.cwd()]) {
+    let currentCwd = null;
+    try {
+        currentCwd = process.cwd();
+    }
+    catch {
+        currentCwd = null;
+    }
+    for (const dir of [previousCwd, currentCwd].filter((dir) => Boolean(dir))) {
         try {
             const headPath = resolveGitHeadPath(dir);
             if (headPath)

package/dist/resources/extensions/search-the-web/native-search.js

@@ -214,9 +214,11 @@ export function registerNativeSearchHooks(pi) {
             isAnthropic = isAnthropicProvider && payloadLooksAnthropic !== false;
         }
         else {
-            // Last resort: session-restore paths where the SDK doesn't pass model.
-            // The model-name prefix is best-effort and assumes direct Anthropic.
-            isAnthropic = payloadLooksAnthropic === true;
+            // No authoritative provider info available (no event.model, no model_select).
+            // Do NOT inject native web_search — guessing on model name alone causes 400
+            // "unsupported_value" errors when the actual provider (copilot, openrouter,
+            // proxy, etc.) doesn't expose the server-side search tool (#648).
+            isAnthropic = false;
         }
         if (!isAnthropic)
             return;

package/dist/resources/extensions/shared/browser-contract.js

@@ -0,0 +1,59 @@
+// Project/App: gsd-pi
+// File Purpose: Browser Automation Contract — the single source for the canonical
+// Pi-facing browser tool vocabulary. Engine adapters (legacy Playwright, managed
+// gsd-browser), UAT policy, dispatch preflight, and evidence detection all derive
+// their browser tool knowledge from this module instead of re-listing names.
+/**
+ * Canonical `browser_*` tool names of the Browser Automation Contract.
+ *
+ * These are the product-level names Units see regardless of which Browser
+ * Automation Engine serves them (ADR-024). Adding a capability here is the
+ * one-line vocabulary change; the engine adapters and presentation surfaces
+ * are typed against this list, so missing coverage fails typecheck.
+ */
+export const BROWSER_CONTRACT_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_fill_form",
+    "browser_click_ref",
+    "browser_fill_ref",
+    "browser_wait_for",
+    "browser_assert",
+    "browser_verify",
+    "browser_screenshot",
+    "browser_snapshot_refs",
+    "browser_find",
+    "browser_get_console_logs",
+    "browser_get_network_logs",
+    "browser_evaluate",
+    "browser_reload",
+    "browser_batch",
+    "browser_act",
+];
+const BROWSER_CONTRACT_TOOL_NAME_SET = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+export function isBrowserContractToolName(name) {
+    return BROWSER_CONTRACT_TOOL_NAME_SET.has(name);
+}
+/**
+ * Whether a canonical (non-MCP-prefixed) tool name belongs to the browser tool
+ * family. Broader than the contract list on purpose: an External MCP Client or
+ * host integration may supply additional `browser_*` tools that still satisfy
+ * browser-backed UAT.
+ */
+export function hasBrowserContractPrefix(canonicalToolName) {
+    return canonicalToolName.startsWith("browser_");
+}
+/**
+ * Contract tool names whose appearance in prose marks browser-backed UAT
+ * activity (requirement or evidence language). Consumed by the
+ * browser-evidence regexes so textual detection stays derived from the
+ * contract vocabulary.
+ */
+export const BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES = [
+    "browser_assert",
+    "browser_batch",
+    "browser_find",
+    "browser_verify",
+    "browser_snapshot_refs",
+];