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

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -221,16 +221,20 @@ export function loadWriteGateSnapshot(basePath) {
  * 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) {
-    if (!shouldPersistWriteGateSnapshot())
-        return;
     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 = process.cwd()) {
     return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;

package/dist/resources/extensions/gsd/branch-patterns.js

@@ -11,3 +11,5 @@ export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{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/dist/resources/extensions/gsd/browser-daemon-auto-prep.js

@@ -0,0 +1,83 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution, resolveBrowserEngineResolution, } from "../browser-tools/engine/selection.js";
+import { resolveGsdBrowserCliAvailability, resolveGsdBrowserDaemonStartInvocation, } from "../shared/gsd-browser-cli.js";
+import { uatTypeIncludesBrowser } from "./uat-policy.js";
+const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+function isEnvDisabled(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "0" || normalized === "false" || normalized === "off";
+}
+function isWarmUpDisabled(env = process.env) {
+    const value = env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
+    return value === "0" || value === "false" || value === "off";
+}
+/** Active engine for warm-up: explicit env override, else session-committed ambient resolution. */
+function resolveActiveBrowserEngine(projectRoot, env) {
+    if (env.GSD_BROWSER_ENGINE?.trim()) {
+        return resolveBrowserEngineResolution(env, projectRoot).engine;
+    }
+    return resolveAmbientBrowserEngineResolution(projectRoot).engine;
+}
+export function shouldWarmBrowserDaemonForUat(ctx) {
+    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, options = {}) {
+    const env = options.env ?? process.env;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available) {
+        return { ok: false, error: availability.detail };
+    }
+    let invocation;
+    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) {
+    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/dist/resources/extensions/gsd/browser-evidence.js

@@ -1,8 +1,14 @@
 // 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/dist/resources/extensions/gsd/captures.js

@@ -11,7 +11,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";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CAPTURES_FILENAME = "CAPTURES.md";
 const VALID_CLASSIFICATIONS = [
@@ -30,11 +30,9 @@ const VALID_CLASSIFICATIONS = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath) {
-    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/dist/resources/extensions/gsd/constants.js

@@ -6,8 +6,6 @@
 // ─── Timeouts ─────────────────────────────────────────────────────────────────
 /** 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). */
 export const DIR_CACHE_MAX = 200;

package/dist/resources/extensions/gsd/crash-recovery.js

@@ -29,6 +29,7 @@ import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
 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 } from "./unit-runtime.js";
@@ -289,18 +290,9 @@ export function formatCrashInfo(lock) {
         `  Started at: ${lock.unitStartedAt}`,
         `  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/dist/resources/extensions/gsd/doctor-environment.js

@@ -12,7 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { detectPythonExecutable } from "./python-resolver.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ── Constants ──────────────────────────────────────────────────────────────
 /** Default dev server ports to scan for conflicts. */
 const DEFAULT_DEV_PORTS = [3000, 3001, 4000, 5000, 5173, 8000, 8080, 8888];
@@ -33,11 +33,7 @@ function resolveWorktreeProjectRoot(basePath) {
     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, cwd) {
     try {

package/dist/resources/extensions/gsd/doctor-format.js

@@ -1,3 +1,7 @@
+import { doctorFixHint } from "./guidance.js";
+function severityTag(severity) {
+    return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 function matchesScope(unitId, scope) {
     if (!scope)
         return true;
@@ -47,8 +51,10 @@ export function formatDoctorReport(report, options) {
     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`);
@@ -66,10 +72,7 @@ export function formatDoctorReport(report, options) {
 export function formatDoctorIssuesForPrompt(issues) {
     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");
 }
 /**
  * Serialize a doctor report to JSON — suitable for CI/tooling integration.

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -401,21 +401,19 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             if (!hasBlanketIgnore) {
                 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 (shouldFix("gitignore_missing_patterns")) {
-                        ensureGitignore(basePath, { manageGitignore });
-                        fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-                    }
+            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");
                 }
             }
         }

package/dist/resources/extensions/gsd/error-classifier.js

@@ -9,6 +9,7 @@
  *
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 export function createRetryState() {
     return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
 }
@@ -44,6 +45,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -77,6 +82,10 @@ export function classifyError(errorMsg, retryAfterMs) {
     if (TOOL_SCHEMA_RE.test(errorMsg)) {
         return { kind: "tool-schema", retryAfterMs: 0 };
     }
+    // Tool-surface readiness abort — transient; retry the same model shortly.
+    if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
+        return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+    }
     const isPermanent = PERMANENT_RE.test(errorMsg);
     const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
     const isUnsupportedModel = UNSUPPORTED_MODEL_MODEL_RE.test(errorMsg) &&

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -11,7 +11,11 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
+// SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
+// (shell.ts) — the single source of truth for the graceful-kill timing ladder —
+// so this sandbox can never drift from the canonical kill path it delegates to.
 export const EXEC_DEFAULTS = {
     clampTimeoutMs: 600_000,
     defaultTimeoutMs: 30_000,
@@ -120,6 +124,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: null,
                 signal: null,
                 timed_out: false,
+                force_resolved: false,
                 duration_ms: duration,
                 stdout_bytes: 0,
                 stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
@@ -172,24 +177,38 @@ export function runExecSandbox(request, opts) {
                 stderrTruncated = true;
             }
         });
+        const effectiveGraceMs = opts.kill_grace_ms ?? SIGKILL_GRACE_MS;
+        const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
         let timedOut = false;
+        let settled = false;
+        let forceResolveTimer;
         const timer = setTimeout(() => {
             timedOut = true;
-            if (useProcessGroup && child.pid != null) {
-                try {
-                    process.kill(-child.pid, "SIGKILL");
-                }
-                catch {
-                    child.kill("SIGKILL");
-                }
+            // killProcessTree handles both platforms and kills the whole tree: on Unix
+            // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
+            // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
+            // would only terminate the direct child on Windows, orphaning grandchildren.
+            if (child.pid != null) {
+                killProcessTree(child.pid, { graceMs: effectiveGraceMs });
             }
             else {
-                child.kill("SIGKILL");
+                child.kill("SIGTERM");
             }
+            // Arm hard-deadline force-resolve in case child never closes (D-state).
+            // The "SIGKILL" here is a synthetic marker (the process may not have actually
+            // received it); force_resolved=true records that this was a deadline, not an exit.
+            forceResolveTimer = setTimeout(() => {
+                finalize(null, "SIGKILL", true);
+            }, effectiveForceResolveDelay);
+            forceResolveTimer.unref?.();
         }, timeoutMs);
         timer.unref?.();
-        const finalize = (exitCode, signal) => {
+        const finalize = (exitCode, signal, forceResolved = false) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
+            clearTimeout(forceResolveTimer);
             const duration = Date.now() - started;
             const stdoutBuf = Buffer.concat(stdoutChunks);
             const stderrBuf = Buffer.concat(stderrChunks);
@@ -211,6 +230,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: exitCode,
                 signal,
                 timed_out: timedOut,
+                force_resolved: forceResolved,
                 duration_ms: duration,
                 stdout_bytes: stdoutBytes,
                 stderr_bytes: stderrBytes,
@@ -254,6 +274,7 @@ function writeMeta(path, result, request, now) {
         exit_code: result.exit_code,
         signal: result.signal,
         timed_out: result.timed_out,
+        force_resolved: result.force_resolved,
         duration_ms: result.duration_ms,
         stdout_bytes: result.stdout_bytes,
         stderr_bytes: result.stderr_bytes,
@@ -261,7 +282,6 @@ function writeMeta(path, result, request, now) {
         stderr_truncated: result.stderr_truncated,
         stdout_path: result.stdout_path,
         stderr_path: result.stderr_path,
-        ...(request.metadata ? { metadata: request.metadata } : {}),
     };
     writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
 }

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

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance) {
+    if (guidance.steps.length === 0)
+        return guidance.summary;
+    const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+    return `${guidance.summary}\n\n${numbered}`;
+}
+const RECOVERY_REMEDIATION = {
+    "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+    "tool-contract": "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+    "tool-unavailable": "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+    "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+    "lifecycle-progression": "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+    "stale-worker": "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+    "worktree-invalid": "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+    "verification-drift": "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+    "reconciliation-drift": "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+    "illegal-transition": "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+    "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+    "provider-transient": "Retry after the provider/network condition clears.",
+    "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+export function recoveryRemediation(key) {
+    return RECOVERY_REMEDIATION[key];
+}
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+export function needsAttentionBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+        `Fix options:`,
+        `1. Review the validation details: \`/gsd status\``,
+        `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+        `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+        `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+    ].join("\n");
+}
+export function needsRemediationBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+        `Fix options:`,
+        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+        `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    ].join("\n");
+}
+// ─── Crash recovery resume hints ────────────────────────────────────────
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType, unitId) {
+    if (unitType === "starting" && unitId === "bootstrap") {
+        return `No work was lost. Run /gsd auto to restart.`;
+    }
+    if (unitType.includes("research") || unitType.includes("plan")) {
+        return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+    }
+    if (unitType.includes("execute")) {
+        return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+    }
+    if (unitType.includes("complete")) {
+        return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+    }
+    return undefined;
+}
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+const DOCTOR_FIX_HINTS = {
+    db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+    conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+    worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+    worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+    provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+    provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+export function doctorFixHint(code) {
+    return DOCTOR_FIX_HINTS[code];
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -47,10 +47,10 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { getPendingGate } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
-import { scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
 export { maybeHandleEmptyIntentTurn, maybeHandleReadyPhraseWithoutFiles, resetEmptyTurnCounter, } from "./guided-unit-completion.js";
 export { _getPendingAutoStart, clearPendingAutoStart, getDiscussionMilestoneId, setPendingAutoStart, } from "./pending-auto-start.js";
 export { checkAutoStartAfterDiscuss } from "./discussion-handoff.js";
@@ -1529,6 +1529,21 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 deletePendingAutoStart(basePath);
             }
             else {
+                if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+                    // The discussion already produced CONTEXT but the agent_end handoff
+                    // never consumed the entry — e.g. an external-engine post-hoc gate
+                    // re-arm wiped the depth verification after the save (write-gate
+                    // two-process sync). CONTEXT can only be written through a verified
+                    // depth gate, so a gate still pending for this milestone is stale:
+                    // clear it and re-run the handoff instead of dead-ending.
+                    const gateBasePath = entry.scope.workspace.projectRoot;
+                    const pendingGateId = getPendingGate(gateBasePath);
+                    if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+                        clearPendingGate(gateBasePath);
+                    }
+                    if (checkAutoStartAfterDiscuss(basePath))
+                        return;
+                }
                 ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
                 return;
             }

package/dist/resources/extensions/gsd/mcp-filter.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 function isRecord(value) {
@@ -63,29 +64,11 @@ function isWorkflowMcpServerConfig(config) {
     const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
     return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
 }
-function isBrowserMcpServerConfig(config) {
-    if (!isRecord(config))
-        return false;
-    const command = typeof config.command === "string" ? config.command : "";
-    if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
-        return true;
-    }
-    const env = config.env;
-    if (isRecord(env)) {
-        if (typeof env.GSD_BROWSER_CLI_PATH === "string"
-            || typeof env.GSD_BROWSER_BIN_PATH === "string"
-            || typeof env.GSD_BROWSER_MCP_COMMAND === "string") {
-            return true;
-        }
-    }
-    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
-    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
-}
 export function discoverWorkflowMcpServerName(projectDir) {
     return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
 }
 export function discoverBrowserMcpServerName(projectDir) {
-    return discoverMcpServers(projectDir).find((server) => isBrowserMcpServerConfig(server.config))?.name;
+    return discoverMcpServers(projectDir).find((server) => isGsdBrowserMcpServerConfig(server.config))?.name;
 }
 export function discoverMcpServerNames(projectDir) {
     return discoverMcpServers(projectDir).map((server) => server.name);

package/dist/resources/extensions/gsd/mcp-tool-name.js

@@ -1,20 +1,12 @@
 // Project/App: gsd-pi
-// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+// File Purpose: GSD-facing face over the shared @gsd/pi-ai MCP tool-name helpers.
+import { parseMcpToolName as parsePiAiMcpToolName, stripMcpToolPrefix } from "@gsd/pi-ai";
 const MCP_TOOL_PREFIX = "mcp__";
 export function parseMcpToolName(toolName) {
-    if (!toolName.startsWith(MCP_TOOL_PREFIX))
-        return null;
-    const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
-    if (toolSeparator < 0)
-        return null;
-    return {
-        serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
-        toolName: toolName.slice(toolSeparator + 2),
-    };
-}
-export function stripMcpToolPrefix(toolName) {
-    return parseMcpToolName(toolName)?.toolName ?? toolName;
+    const parsed = parsePiAiMcpToolName(toolName);
+    return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
 }
+export { stripMcpToolPrefix };
 export function toMcpToolName(serverName, toolName) {
     return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
 }

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -211,7 +211,7 @@ export function reportConsolidationGaps(basePath) {
         const report = scanConsolidationGaps(basePath);
         if (report.totalGaps === 0)
             return report;
-        appendNotification(report.summary, "warning", "workflow-logger");
+        appendNotification(report.summary, "warning", "workflow-logger", { kind: "memory-consolidation" });
         logWarning("memory-consolidation", report.summary);
         return report;
     }