@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.fb12b103

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -13,7 +13,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, loadWriteGateSnapshot, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, loadWriteGateSnapshot, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -39,7 +39,14 @@ import { saveActivityLog } from "../activity-log.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
 import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
+import {
+  confirmDestructiveCommand,
+  consumeDestructiveConfirmation,
+  isDestructiveConfirmGateId,
+  requestDestructiveConfirmation,
+} from "../safety/destructive-confirmation.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
@@ -57,11 +64,14 @@ import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.j
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, canonicalWorkflowToolName, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
 import { filterToolsForProvider } from "../model-router.js";
 import { mcpToolMatchesBaseName } from "../mcp-tool-name.js";
 import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 import { supportsSourceObservationsForUnit } from "../source-observations.js";
 import { clearPendingAutoStart } from "../pending-auto-start.js";
+import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -178,7 +188,7 @@ function withPreservedShimTools(toolNames: readonly string[]): string[] {
 
 /** True for the browser automation tools (browser_navigate, browser_click, ...). */
 function isBrowserTool(toolName: string): boolean {
-  return canonicalToolName(toolName).startsWith("browser_");
+  return hasBrowserContractPrefix(canonicalToolName(toolName));
 }
 
 /**
@@ -259,6 +269,7 @@ export function buildMinimalAutoGsdToolSet(
   activeToolNames: readonly string[],
   unitType: string | undefined,
   registeredToolNames: readonly string[] = activeToolNames,
+  warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames,
 ): string[] {
   if (unitType === "run-uat") {
     return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
@@ -274,7 +285,36 @@ export function buildMinimalAutoGsdToolSet(
     [...activeToolNames, ...registeredToolNames],
     [...MINIMAL_GSD_TOOL_NAMES, ...unitTools],
   );
-  return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+  const result = withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+  warnIfRequiredWorkflowToolsUnresolved(unitType, result, warnOnUnresolvedRequiredTools);
+  return result;
+}
+
+function hasResolvedWorkflowTool(
+  resolvedToolNames: readonly string[],
+  requiredToolName: string,
+): boolean {
+  return resolvedToolNames.some(
+    (name) => name === requiredToolName || mcpToolMatchesBaseName(name, requiredToolName),
+  );
+}
+
+function warnIfRequiredWorkflowToolsUnresolved(
+  unitType: string | undefined,
+  scopedToolNames: readonly string[],
+  shouldWarn: boolean,
+): void {
+  if (!unitType || !shouldWarn) return;
+
+  const unresolved = getRequiredWorkflowToolsForUnit(unitType).filter(
+    (toolName) => !hasResolvedWorkflowTool(scopedToolNames, toolName),
+  );
+  if (unresolved.length === 0) return;
+
+  safetyLogWarning(
+    "bootstrap",
+    `buildMinimalAutoGsdToolSet(${unitType}): required workflow tool(s) not in active/registered surface after scoping: ${unresolved.join(", ")}. Tool registration may have partially failed, provider filtering may have removed a required tool, or workflow MCP may be disconnected.`,
+  );
 }
 
 export function buildRunUatGsdToolSet(
@@ -327,6 +367,7 @@ export function buildRequestScopedGsdToolSet(
   requestCustomMessages: readonly { customType?: string }[] | undefined,
   registeredToolNames: readonly string[] = activeToolNames,
   guidedUnitType?: string,
+  warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames,
 ): string[] | undefined {
   for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
     const currentCustomType = requestCustomMessages?.[index]?.customType;
@@ -337,7 +378,12 @@ export function buildRequestScopedGsdToolSet(
       currentCustomType === "gsd-triage"
     ) {
       if (guidedUnitType) {
-        return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames);
+        return buildMinimalAutoGsdToolSet(
+          activeToolNames,
+          guidedUnitType,
+          registeredToolNames,
+          warnOnUnresolvedRequiredTools,
+        );
       }
       return buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames);
     }
@@ -386,11 +432,13 @@ function applyMinimalGsdToolSurface(pi: ExtensionAPI): void {
   const dash = getAutoRuntimeSnapshot();
   if (dash.active && dash.currentUnit) {
     const currentToolNames = pi.getActiveTools();
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
     const scopedToolNames = buildMinimalAutoGsdToolSet(
       currentToolNames,
       dash.currentUnit.type,
       registeredToolNames,
+      hasRegisteredSurface,
     );
     recordAutoToolSurfaceSnapshot({
       source: "runtime-scope",
@@ -412,9 +460,10 @@ export function scopeGsdWorkflowToolsForDispatch(
 ): ScopedGsdWorkflowState | null {
   if (isFullGsdToolSurfaceRequested()) return null;
   const current = pi.getActiveTools();
+  const hasRegisteredSurface = typeof pi.getAllTools === "function";
   const registeredToolNames = resolveRegisteredToolNames(pi, current);
   const scoped = unitType
-    ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
+    ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames, hasRegisteredSurface)
     : buildMinimalGsdWorkflowToolSet(current, registeredToolNames);
   recordAutoToolSurfaceSnapshot({
     source: "dispatch-scope",
@@ -575,8 +624,7 @@ function activateDeferredApprovalGate(basePath: string): void {
   if (deferredApprovalGate?.basePath !== basePath) return;
   const gateId = deferredApprovalGate.gateId;
   deferredApprovalGate = null;
-  refreshWriteGateStateFromDisk(basePath);
-  const snapshot = loadWriteGateSnapshot(basePath);
+  const snapshot = refreshWriteGateStateFromDisk(basePath);
   const milestoneId = extractDepthVerificationMilestoneId(gateId);
   if (isApprovalGateVerifiedInSnapshot(snapshot, gateId)) return;
   if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return;
@@ -600,6 +648,26 @@ function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
   return (input as { artifact_type?: unknown }).artifact_type === "CONTEXT-DRAFT";
 }
 
+/**
+ * External engines (claude-code-cli) deliver ask_user_questions results as
+ * relayed MCP tool results: the structured round payload arrives in
+ * `result.structuredContent`, not in pi-native `event.details`. Without this
+ * fallback, applyAskUserQuestionsGateResult sees no response for an answered
+ * gate question and lands in the "waiting" branch — leaving a re-armed gate
+ * permanently pending and the discuss→auto handoff blocked.
+ */
+function resolveAskUserQuestionsGateDetails(event: { details?: unknown; result?: unknown }): any {
+  const hasRoundShape = (value: any): boolean =>
+    !!value && typeof value === "object" &&
+    (value.cancelled !== undefined || value.response !== undefined);
+
+  const details = event.details as any;
+  if (hasRoundShape(details)) return details;
+  const structured = (event.result as { structuredContent?: unknown } | undefined)?.structuredContent;
+  if (hasRoundShape(structured)) return structured;
+  return details ?? {};
+}
+
 type StructuredQuestion = {
   id?: string;
   header?: string;
@@ -1328,23 +1396,39 @@ export function registerHooks(
 
     // Destructive command classification + hard gate in all modes.
     if (isToolCallEventType("bash", event)) {
-      const classification = classifyCommand(event.input.command);
+      const command = event.input.command;
+      const classification = classifyCommand(command);
       if (classification.destructive) {
+        const guardBasePath = contextBasePath(ctx);
+        // Escape hatch: if the user already confirmed this exact command via a
+        // destructive_confirm gate, consume the one-shot token and let it run.
+        // Without this, the block below loops forever — the model cannot satisfy
+        // "confirm in the current turn" because nothing ever clears the gate.
+        if (consumeDestructiveConfirmation(command, guardBasePath)) {
+          safetyLogWarning("safety", `destructive command confirmed: ${classification.labels.join(", ")}`, {
+            command: String(command).slice(0, 200),
+          });
+          return;
+        }
+        // Record the command as pending so an affirmative answer to a
+        // destructive_confirm gate (handled in tool_result) can confirm it.
+        requestDestructiveConfirmation(command, guardBasePath);
         const reason = [
           "HARD BLOCK: destructive Bash command requires explicit human confirmation.",
           `Detected: ${classification.labels.join(", ")}`,
-          "Run this via ask_user_questions, wait for the user's response,",
-          "then issue the command only when confirmed in the current turn.",
+          "Call ask_user_questions with a question id containing \"destructive_confirm\"",
+          "and a first option that affirms the action; wait for the user's response,",
+          "then re-issue this exact command in the same turn to run it once.",
         ].join(" ");
         safetyLogWarning("safety", `destructive command: ${classification.labels.join(", ")}`, {
-          command: String(event.input.command).slice(0, 200),
+          command: String(command).slice(0, 200),
         });
         if (ctx) {
           await maybePauseAutoForApprovalGate(
             ctx,
             pi,
             isAutoActive(),
-            "Depth confirmation is waiting for your answer — pausing auto-mode.",
+            "Destructive-command confirmation is waiting for your answer — pausing auto-mode.",
           );
         }
         return { block: true, reason };
@@ -1382,13 +1466,27 @@ export function registerHooks(
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }
+    // Interactive Closeout adapter (ADR-032): auto-mode owns closeout for its
+    // own units; interactive completions get the durable git subset (commit +
+    // Closeout Git Verdict) instead of silently bypassing git.isolation.
+    if (!event.isError && !isAutoActive() && isUnitCloseoutTool(toolName)) {
+      try {
+        runInteractiveUnitCloseout({
+          basePath: resolveWorkflowToolBasePath(ctx, event.input as { milestone_id?: string }),
+          canonicalToolName: toolName,
+          input: event.input,
+        });
+      } catch (err) {
+        safetyLogWarning("engine", `interactive unit closeout failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
     if (toolName !== "ask_user_questions") return;
     const basePath = contextBasePath(ctx);
     const milestoneId = await getDiscussionMilestoneIdFor(basePath);
 
-    const details = event.details as any;
+    const details = resolveAskUserQuestionsGateDetails(event);
 
-    const questions: any[] = (event.input as any)?.questions ?? [];
+    const questions: any[] = (event.input as any)?.questions ?? details?.questions ?? [];
     const gateResult = applyAskUserQuestionsGateResult({
       basePath,
       questions,
@@ -1419,6 +1517,24 @@ export function registerHooks(
     }
 
     if (details?.cancelled || !details?.response) return;
+
+    // Destructive-command confirmation: an affirmative answer to a
+    // destructive_confirm gate promotes the pending blocked command to a
+    // one-shot confirmed token, which the bash tool_call guard consumes on the
+    // next attempt. Rejecting/declining leaves the command blocked.
+    // (Depth-verification gate handling now lives in
+    // applyAskUserQuestionsGateResult above; only the destructive-confirm gate
+    // is handled inline here.)
+    for (const question of questions) {
+      if (isDestructiveConfirmGateId(question?.id)) {
+        const answer = details.response?.answers?.[question.id];
+        if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+          confirmDestructiveCommand(basePath);
+        }
+        break;
+      }
+    }
+
     if (!milestoneId) return;
     await saveDiscussionQuestionRound(basePath, milestoneId, questions, details);
   });
@@ -1429,7 +1545,24 @@ export function registerHooks(
     if (toolName === "ask_user_questions") {
       const questionId = extractGateQuestionId(event.args);
       if (typeof questionId === "string") {
-        setPendingGate(questionId, basePath);
+        // External engines (claude-code-cli) ingest the SDK turn's tool blocks
+        // post-hoc, so this event can fire AFTER the workflow MCP child already
+        // verified this gate and allowed the CONTEXT save. setPendingGate also
+        // revokes verifiedDepthMilestones/verifiedApprovalGates, so an
+        // unconditional re-arm here wipes the child's verification and leaves
+        // the discuss→auto handoff permanently blocked. Skip the re-arm when
+        // the snapshot already records this exact gate as verified — mirrors
+        // activateDeferredApprovalGate's guard. Stale verified state cannot
+        // leak into a later re-discussion: a successful handoff deletes the
+        // snapshot via clearDiscussionFlowState.
+        const snapshot = refreshWriteGateStateFromDisk(basePath);
+        const gateMilestoneId = extractDepthVerificationMilestoneId(questionId);
+        const alreadyVerified =
+          isApprovalGateVerifiedInSnapshot(snapshot, questionId) ||
+          isMilestoneDepthVerifiedInSnapshot(snapshot, gateMilestoneId);
+        if (!alreadyVerified) {
+          setPendingGate(questionId, basePath);
+        }
         clearDeferredApprovalGate(basePath);
       }
     }
@@ -1528,6 +1661,7 @@ export function registerHooks(
       return surfaceReduced ? { toolNames: providerCompatible } : undefined;
     }
     const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const compatibleRegisteredToolNames = filterToolsForProvider(
       registeredToolNames,
       event.selectedModelApi,
@@ -1542,6 +1676,7 @@ export function registerHooks(
       event.requestCustomMessages,
       requestRegisteredToolNames,
       guidedUnit?.unitType,
+      hasRegisteredSurface,
     );
     if (requestScoped) {
       recordAutoToolSurfaceSnapshot({
@@ -1562,6 +1697,7 @@ export function registerHooks(
         dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible,
         dash.currentUnit.type,
         registeredForUnit,
+        hasRegisteredSurface,
       );
       recordAutoToolSurfaceSnapshot({
         source: "provider-adjustment",

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -251,15 +251,19 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
  * verification there; without this refresh the extension host keeps stale
  * pending-gate memory and `activateDeferredApprovalGate` can re-arm a gate
  * that the subprocess already cleared on disk.
+ *
+ * Returns the snapshot used for the refresh so callers that need to inspect
+ * it (e.g. re-arm guards) avoid a second disk read.
  */
-export function refreshWriteGateStateFromDisk(basePath: string): void {
-  if (!shouldPersistWriteGateSnapshot()) return;
+export function refreshWriteGateStateFromDisk(basePath: string): WriteGateSnapshot {
   const snapshot = loadWriteGateSnapshot(basePath);
+  if (!shouldPersistWriteGateSnapshot()) return snapshot;
   const state = getWriteGateState(basePath);
   state.pendingGateId = snapshot.pendingGateId;
   state.activeQueuePhase = snapshot.activeQueuePhase;
   state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
   state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+  return snapshot;
 }
 
 export function isDepthVerified(basePath: string = process.cwd()): boolean {

package/src/resources/extensions/gsd/branch-patterns.ts

@@ -14,3 +14,6 @@ export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 
 /** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
 export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;
+
+/** Auto-mode milestone branch prefix: milestone/<MID>. */
+export const MILESTONE_BRANCH_PREFIX = "milestone/";

package/src/resources/extensions/gsd/browser-daemon-auto-prep.ts

@@ -0,0 +1,108 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+import {
+  resolveAmbientBrowserEngineResolution,
+  resolveBrowserEngineResolution,
+  type BrowserEngineMode,
+} from "../browser-tools/engine/selection.js";
+import {
+  resolveGsdBrowserCliAvailability,
+  resolveGsdBrowserDaemonStartInvocation,
+} from "../shared/gsd-browser-cli.js";
+import { uatTypeIncludesBrowser, type UatType } from "./uat-policy.js";
+
+const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+
+function isEnvDisabled(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "0" || normalized === "false" || normalized === "off";
+}
+
+function isWarmUpDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
+  return value === "0" || value === "false" || value === "off";
+}
+
+export interface BrowserDaemonWarmContext {
+  uatType: UatType;
+  sessionProvider?: string;
+  sessionAuthMode?: "apiKey" | "oauth" | "externalCli" | "none";
+  sessionBaseUrl?: string;
+  projectRoot: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Active engine for warm-up: explicit env override, else session-committed ambient resolution. */
+function resolveActiveBrowserEngine(projectRoot: string, env: NodeJS.ProcessEnv): BrowserEngineMode {
+  if (env.GSD_BROWSER_ENGINE?.trim()) {
+    return resolveBrowserEngineResolution(env, projectRoot).engine;
+  }
+  return resolveAmbientBrowserEngineResolution(projectRoot).engine;
+}
+
+export function shouldWarmBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): boolean {
+  if (!uatTypeIncludesBrowser(ctx.uatType)) return false;
+
+  const env = ctx.env ?? process.env;
+  if (isWarmUpDisabled(env)) return false;
+  if (isEnvDisabled(env.GSD_BROWSER_MCP_ENABLED)) return false;
+
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) return false;
+
+  const projectRoot = resolve(ctx.projectRoot);
+  return resolveActiveBrowserEngine(projectRoot, env) === "gsd-browser";
+}
+
+export function ensureBrowserDaemonStarted(
+  projectRoot: string,
+  options: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { ok: true } | { ok: false; error: string } {
+  const env = options.env ?? process.env;
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) {
+    return { ok: false, error: availability.detail };
+  }
+
+  let invocation: ReturnType<typeof resolveGsdBrowserDaemonStartInvocation>;
+  try {
+    invocation = resolveGsdBrowserDaemonStartInvocation(projectRoot, env);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  try {
+    execFileSync(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? DEFAULT_DAEMON_START_TIMEOUT_MS,
+      encoding: "utf-8",
+    });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Best-effort pre-warm of the gsd-browser session daemon before browser-backed
+ * run-uat dispatch. Returns an actionable stop reason when warm-up is required
+ * but fails; returns null when warm-up is skipped or succeeds.
+ */
+export function prepareBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): string | null {
+  if (!shouldWarmBrowserDaemonForUat(ctx)) return null;
+
+  const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
+  if (result.ok) return null;
+
+  return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
+}

package/src/resources/extensions/gsd/browser-evidence.ts

@@ -1,9 +1,25 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
 
-export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
+import { BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES } from "../shared/browser-contract.js";
+
+// Alternation fragment over the contract's evidence-signal names, e.g.
+// `browser_(?:assert|batch|...)`. The names are `browser_`-prefixed
+// identifiers (pinned by tests/browser-contract.test.ts), so no escaping is
+// needed.
+const BROWSER_TOOL_SIGNAL = `browser_(?:${
+  BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES.map((name) => name.slice("browser_".length)).join("|")
+})`;
+
+export const BROWSER_REQUIREMENT_RE = new RegExp(
+  String.raw`\b(?:file://|localhost|playwright|chrome|screenshot|snapshot|${BROWSER_TOOL_SIGNAL})\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file://)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b`,
+  "i",
+);
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
-export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
+export const BROWSER_RUNTIME_RE = new RegExp(
+  String.raw`\b(?:browser|playwright|chrome|camoufox|${BROWSER_TOOL_SIGNAL}|screenshot|snapshot|file://|localhost)\b`,
+  "i",
+);
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
 const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;

package/src/resources/extensions/gsd/captures.ts

@@ -12,7 +12,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -60,11 +60,9 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath: string): string {
-  const resolved = resolve(basePath);
-  const segment = findWorktreeSegment(resolved.replaceAll("\\", "/"));
-  if (segment) {
-    // basePath is inside a worktree — resolve to project root
-    const projectRoot = resolved.slice(0, segment.gsdIdx);
+  // If basePath is inside a worktree, resolve to the project root.
+  const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+  if (projectRoot) {
     return join(projectRoot, ".gsd", CAPTURES_FILENAME);
   }
   return join(gsdRoot(basePath), CAPTURES_FILENAME);

package/src/resources/extensions/gsd/constants.ts

@@ -9,9 +9,6 @@
 /** Default timeout for verification-gate commands (ms). */
 export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 
-/** Default timeout for the dynamic bash tool (seconds). */
-export const DEFAULT_BASH_TIMEOUT_SECS = 120;
-
 // ─── Cache Sizes ──────────────────────────────────────────────────────────────
 
 /** Max directory-listing cache entries before eviction (#611). */

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -39,6 +39,7 @@ import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/uni
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
+import { crashResumeHint } from "./guidance.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
 import { isInFlightRuntimePhase, listUnitRuntimeRecords, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
@@ -321,15 +322,8 @@ export function formatCrashInfo(lock: LockData): string {
     `  PID: ${lock.pid}`,
   ];
 
-  if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
-    lines.push(`No work was lost. Run /gsd auto to restart.`);
-  } else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
-    lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);
-  } else if (lock.unitType.includes("execute")) {
-    lines.push(`Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`);
-  } else if (lock.unitType.includes("complete")) {
-    lines.push(`Slice/milestone completion was interrupted. Run /gsd auto to finish.`);
-  }
+  const hint = crashResumeHint(lock.unitType, lock.unitId);
+  if (hint) lines.push(hint);
 
   return lines.join("\n");
 }

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -15,7 +15,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { detectPythonExecutable } from "./python-resolver.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -50,12 +50,7 @@ const CMD_TIMEOUT = 5_000;
 function resolveWorktreeProjectRoot(basePath: string): string | null {
   const envRoot = process.env.GSD_WORKTREE;
   if (envRoot) return envRoot;
-
-  const segment = findWorktreeSegment(basePath.replace(/\\/g, "/"));
-  if (!segment) return null;
-
-  // Everything before the worktree segment is the project root
-  return basePath.slice(0, segment.gsdIdx);
+  return projectRootFromWorktreePath(basePath);
 }
 
 function tryExec(cmd: string, cwd: string): string | null {

package/src/resources/extensions/gsd/doctor-format.ts

@@ -1,4 +1,9 @@
-import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary, DoctorSeverity } from "./doctor-types.js";
+import { doctorFixHint } from "./guidance.js";
+
+function severityTag(severity: DoctorSeverity): string {
+  return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 
 function matchesScope(unitId: string, scope?: string): boolean {
   if (!scope) return true;
@@ -53,8 +58,9 @@ export function formatDoctorReport(
   if (scopedIssues.length > 0) {
     lines.push("Priority issues:");
     for (const issue of scopedIssues.slice(0, maxIssues)) {
-      const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-      lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      const hint = doctorFixHint(issue.code);
+      if (hint && issue.severity !== "info") lines.push(`  Fix: ${hint}`);
     }
     if (scopedIssues.length > maxIssues) {
       lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -72,10 +78,9 @@ export function formatDoctorReport(
 
 export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   if (issues.length === 0) return "- No remaining issues in scope.";
-  return issues.map(issue => {
-    const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-    return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-  }).join("\n");
+  return issues.map(issue =>
+    `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`
+  ).join("\n");
 }
 
 /**

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -425,22 +425,20 @@ export async function checkRuntimeHealth(
         missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
       }
 
-      {
-        if (missing.length > 0) {
-          issues.push({
-            severity: "warning",
-            code: "gitignore_missing_patterns",
-            scope: "project",
-            unitId: "project",
-            message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-            file: ".gitignore",
-            fixable: true,
-          });
+      if (missing.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "gitignore_missing_patterns",
+          scope: "project",
+          unitId: "project",
+          message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+          file: ".gitignore",
+          fixable: true,
+        });
 
-          if (shouldFix("gitignore_missing_patterns")) {
-            ensureGitignore(basePath, { manageGitignore });
-            fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-          }
+        if (shouldFix("gitignore_missing_patterns")) {
+          ensureGitignore(basePath, { manageGitignore });
+          fixesApplied.push("added missing GSD runtime patterns to .gitignore");
         }
       }
     }