@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

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/files.js

@@ -576,38 +576,52 @@ export function parseTaskPlanIO(content) {
         outputFiles: extractPaths(outputSection),
     };
 }
+/** Canonical list of recognised UAT types — uat-policy.ts re-exports this as UAT_TYPES. */
+export const UAT_TYPE_KEYWORDS = [
+    'artifact-driven',
+    'browser-executable',
+    'runtime-executable',
+    'live-runtime',
+    'mixed',
+    'human-experience',
+];
+/** Match a value against the recognised UAT type keywords (leading-keyword-only). */
+function matchUatTypeKeyword(value) {
+    const normalized = value.trim().toLowerCase();
+    return UAT_TYPE_KEYWORDS.find(keyword => normalized.startsWith(keyword));
+}
 /**
  * Extract the UAT type from a UAT file's raw content.
  *
  * UAT files have no YAML frontmatter - pass raw file content directly.
  * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
  *
+ * The canonical form is a `- UAT mode: <type>` bullet under `## UAT Type`
+ * (case-insensitive prefix, `**bold**` tolerated). When no such line exists,
+ * a line that itself starts with a recognised keyword — e.g. a bare
+ * `browser-executable` under the heading — is accepted, so agent-authored
+ * format drift does not silently fall back to artifact-driven.
+ *
  * Returns `undefined` when:
  * - the `## UAT Type` section is absent
- * - no `UAT mode:` bullet is found in the section
- * - the value does not start with a recognised keyword
+ * - a `UAT mode:` line exists but its value starts with no recognised keyword
+ * - no line in the section starts with `UAT mode:` or a recognised keyword
  */
 export function extractUatType(content) {
     const sectionText = extractSection(content, 'UAT Type');
     if (!sectionText)
         return undefined;
-    const bullets = parseBullets(sectionText);
-    const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
-    if (!modeBullet)
-        return undefined;
-    const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
-    if (rawValue.startsWith('artifact-driven'))
-        return 'artifact-driven';
-    if (rawValue.startsWith('browser-executable'))
-        return 'browser-executable';
-    if (rawValue.startsWith('runtime-executable'))
-        return 'runtime-executable';
-    if (rawValue.startsWith('live-runtime'))
-        return 'live-runtime';
-    if (rawValue.startsWith('human-experience'))
-        return 'human-experience';
-    if (rawValue.startsWith('mixed'))
-        return 'mixed';
+    const lines = parseBullets(sectionText).map(line => line.replace(/\*\*/g, ''));
+    for (const line of lines) {
+        const declared = /^uat mode:\s*(.*)$/i.exec(line);
+        if (declared)
+            return matchUatTypeKeyword(declared[1]);
+    }
+    for (const line of lines) {
+        const matched = matchUatTypeKeyword(line);
+        if (matched)
+            return matched;
+    }
     return undefined;
 }
 /**

package/dist/resources/extensions/gsd/gsd-command-home.js

@@ -28,13 +28,17 @@ export function buildGsdHomeModel(state, closeout) {
     const workLabel = activeWorkLabel(state);
     const strandedQuick = closeout?.strandedQuick ?? null;
     const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+    const idleResidueHint = closeout?.idleResidueHint ?? null;
+    const hasIdleResidue = Boolean(idleResidueHint);
     const nextReason = complete
         ? "all milestones are complete"
         : blocked
             ? "the active milestone is blocked"
-            : !hasActiveWork
-                ? "there is no active milestone"
-                : "";
+            : hasIdleResidue
+                ? "milestone git residue needs recovery"
+                : !hasActiveWork
+                    ? "there is no active milestone"
+                    : "";
     const canAdvance = hasActiveWork && !blocked && !complete;
     const unmappedActive = complete ? countUnmappedActiveRequirements() : 0;
     const recommended = strandedQuick
@@ -43,11 +47,13 @@ export function buildGsdHomeModel(state, closeout) {
             ? "finish_milestone"
             : blocked
                 ? "fix_recover"
-                : canAdvance
-                    ? "continue_step"
-                    : complete && unmappedActive > 0
-                        ? "review_requirements_backlog"
-                        : "start_configure";
+                : hasIdleResidue
+                    ? "fix_recover"
+                    : canAdvance
+                        ? "continue_step"
+                        : complete && unmappedActive > 0
+                            ? "review_requirements_backlog"
+                            : "start_configure";
     const completionSummary = complete
         ? appendRequirementsBacklogToSummary(state, [
             `All milestones complete${state.lastCompletedMilestone ? ` after ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}` : ""}.`,
@@ -57,7 +63,9 @@ export function buildGsdHomeModel(state, closeout) {
         ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
         : unmergedMilestone
             ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
-            : completionSummary;
+            : idleResidueHint
+                ? [idleResidueHint.message]
+                : completionSummary;
     return {
         title: "GSD — What now?",
         summary: [
@@ -130,10 +138,12 @@ export function buildGsdHomeModel(state, closeout) {
                 label: "Fix or recover",
                 description: blocked
                     ? "Review the blocker and recovery commands for the active milestone."
-                    : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-                enabled: blocked,
+                    : hasIdleResidue
+                        ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
+                        : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
+                enabled: blocked || hasIdleResidue,
                 recommended: recommended === "fix_recover",
-                disabledReason: blocked ? undefined : "no blocker is active",
+                disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
             },
             {
                 id: "start_configure",

package/dist/resources/extensions/gsd/gsd-db.js

@@ -169,7 +169,7 @@ export function insertArtifact(a) {
 export function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
+    const result = getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
       verification_contract, verification_integration, verification_operational, verification_uat,
@@ -199,6 +199,7 @@ export function insertMilestone(m) {
         ":requirement_coverage": m.planning?.requirementCoverage ?? "",
         ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
     });
+    return (result.changes ?? 0) > 0;
 }
 export function upsertMilestonePlanning(milestoneId, planning) {
     if (!getDbOrNull())

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

@@ -55,6 +55,66 @@ export function needsRemediationBlockerGuidance(milestoneId) {
         `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
     ].join("\n");
 }
+// ─── Milestone closeout UAT sign-off blockers ───────────────────────────
+// The first sentence is the blocker finding; the numbered steps are the
+// resolution path. `verdict` is the recorded non-PASS verdict, or undefined
+// when no verdict has been recorded at all.
+export function uatSignoffBlockerGuidance(milestoneId, sliceId, verdict) {
+    const finding = verdict === undefined
+        ? `missing UAT PASS verdict for ${sliceId}`
+        : `UAT verdict for ${sliceId} is "${verdict}"`;
+    const sliceSpecificRerunStep = `If ${sliceId} is not the most recently completed slice, type a chat request to re-run UAT for ${sliceId}; run-uat will record the verdict through \`gsd_uat_result_save\`.`;
+    const steps = verdict === undefined
+        ? [
+            `1. Run UAT for the most recently completed slice to record a verdict: \`/gsd dispatch uat\``,
+            `2. ${sliceSpecificRerunStep}`,
+            `3. Review the UAT criteria and progress: \`/gsd status\``,
+            `4. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ]
+        : [
+            `1. Review the failing UAT findings: \`/gsd status\` (the ${sliceId} ASSESSMENT records what failed)`,
+            `2. Fix the issue, then re-run UAT for the most recently completed slice to record a fresh verdict: \`/gsd dispatch uat\``,
+            `3. ${sliceSpecificRerunStep}`,
+            `4. If the fix needs new implementation work, add remediation slices: \`/gsd dispatch reassess\``,
+            `5. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ];
+    return [
+        `Cannot complete milestone ${milestoneId}: ${finding}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+        `Fix options:`,
+        ...steps,
+    ].join("\n");
+}
+// ─── Worktree isolation degradation ─────────────────────────────────────
+// The first sentence of each notice is load-bearing for log matching and
+// tests — keep it intact and append guidance after it.
+function restoreIsolationHint(milestoneId) {
+    return `To restore isolation: close any processes using the old worktree, merge salvageable work with \`/gsd worktree merge ${milestoneId}\` or remove the stale worktree with \`/gsd worktree remove ${milestoneId}\`, then run \`/gsd doctor fix\`.`;
+}
+export function worktreeCreationFailedGuidance(milestoneId, error) {
+    return [
+        `Auto-worktree creation for ${milestoneId} failed: ${error}. Continuing in project root.`,
+        `Worktree isolation is degraded for this session.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+export function isolationDegradedFallbackGuidance(milestoneId) {
+    return [
+        `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+        `Work continues safely on the milestone branch in the project root.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+/** Hard entry blockers from auto-start: bootstrap stopped, user must act. */
+export function milestoneEntryBlockedGuidance(milestoneId, reason) {
+    const finding = reason === "creation-failed"
+        ? `worktree/branch creation failed. Isolation is degraded.`
+        : `isolation is degraded from a prior worktree failure.`;
+    return [
+        `Cannot enter milestone ${milestoneId}: ${finding}`,
+        restoreIsolationHint(milestoneId),
+        `Then run \`/gsd auto\` to retry.`,
+    ].join("\n");
+}
 // ─── Crash recovery resume hints ────────────────────────────────────────
 /** Resume hint for an interrupted auto-mode unit, by unit class. */
 export function crashResumeHint(unitType, unitId) {

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

@@ -42,9 +42,15 @@ export { nextMilestoneIdReserved } from "./milestone-id-reservation.js";
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { buildCloseoutMenuActions, buildIdleMenuSummary, getPrimaryCloseoutRecommendation, handleCloseoutChoice, loadCloseoutContext, } from "./closeout-wizard.js";
 import { buildRequirementsBacklogDiscussContext, countUnmappedActiveRequirements, showRequirementsBacklogReview, } from "./requirements-backlog.js";
-import { selectAndApplyModel } from "./auto-model-selection.js";
+import { selectAndApplyModel, getRegisteredToolSnapshot } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { detectWorkflowMcpLaunchConfig, resolveWorkflowMcpProjectRoot, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { usesWorkflowMcpTransport } from "./question-transport.js";
+import { getCachedWorkflowMcpProbe, probeAndCacheWorkflowMcp, warmWorkflowMcpProbeInBackground, workflowMcpProbeAdvertisesSurface, WORKFLOW_MCP_PROBE_TIMEOUT_MS, } from "./workflow-mcp-readiness-cache.js";
+import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
@@ -368,6 +374,67 @@ async function dispatchNextDeepProjectSetupStage(entry) {
 export function resolveGuidedDispatchProjectRoot(basePath) {
     return basePath ?? process.cwd();
 }
+/**
+ * Wait until the workflow MCP server is reachable and advertising its tool
+ * surface. Returns failure details when timed out, or null when ready (or MCP
+ * is not the transport). Called inside dispatchWorkflow() so every guided-flow
+ * dispatch path is gated automatically.
+ */
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+async function awaitWorkflowMcpReadiness(pi, ctx, basePath, options = {}) {
+    const provider = ctx.model?.provider;
+    const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined;
+    if (!usesWorkflowMcpTransport(authMode, ctx.model?.baseUrl))
+        return null;
+    const projectRoot = resolveWorkflowMcpProjectRoot(basePath);
+    const launch = detectWorkflowMcpLaunchConfig(projectRoot);
+    if (!launch)
+        return null;
+    const requiredTools = options.unitType
+        ? getRequiredWorkflowToolsForUnit(options.unitType).filter(isWorkflowToolSurfaceName)
+        : [];
+    const coversExpectedSurface = (tools) => requiredTools.length > 0
+        ? probeCoversRequiredWorkflowTools(tools, requiredTools)
+        : workflowMcpProbeAdvertisesSurface(tools);
+    const serverPrefix = `mcp__${launch.name}__`;
+    const systemPrompt = () => typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : "";
+    const systemPromptCoversExpectedSurface = () => {
+        const prompt = systemPrompt();
+        return requiredTools.length > 0
+            ? requiredTools.every((tool) => prompt.includes(`${serverPrefix}${tool}`))
+            : prompt.includes(serverPrefix);
+    };
+    const sessionAlreadyReady = () => coversExpectedSurface(getRegisteredToolSnapshot(pi)) ||
+        systemPromptCoversExpectedSurface();
+    if (sessionAlreadyReady())
+        return null;
+    if (coversExpectedSurface(getCachedWorkflowMcpProbe(projectRoot)?.tools ?? [])) {
+        return null;
+    }
+    const probe = options.probe ?? probeAndCacheWorkflowMcp;
+    const probeTimeoutMs = options.probeTimeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS;
+    ctx.ui.setStatus("gsd-step", `Waiting for ${launch.name} MCP server…`);
+    let lastError;
+    const deadline = Date.now() + (options.timeoutMs ?? MCP_READINESS_TIMEOUT_MS);
+    const pollMs = options.pollMs ?? MCP_READINESS_POLL_MS;
+    while (Date.now() < deadline) {
+        if (sessionAlreadyReady()) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        const result = await probe(projectRoot, { timeoutMs: probeTimeoutMs });
+        if (result.ok && coversExpectedSurface(result.tools)) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        lastError = result.error;
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    ctx.ui.setStatus("gsd-step", "");
+    return lastError ? { server: launch.name, error: lastError } : { server: launch.name };
+}
+export const _awaitWorkflowMcpReadinessForTest = awaitWorkflowMcpReadiness;
 /**
  * Read GSD-WORKFLOW.md and dispatch it to the LLM with a contextual note.
  * This is the only way the wizard triggers work — everything else is the LLM's job.
@@ -382,7 +449,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
     const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
     const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
     const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
-    const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
+    const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
+        ?? getUnitWorkflowDispatchReadinessError;
     // Route through the dynamic routing pipeline (complexity classification,
     // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
     if (ctx && unitType) {
@@ -396,7 +464,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                 routing: result.routing,
             });
         }
-        const compatibilityError = getTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+        const compatibilityError = getDispatchReadinessError({
+            provider: result.appliedModel?.provider ?? ctx.model?.provider,
             projectRoot,
             surface: "guided flow",
             unitType,
@@ -415,6 +484,25 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
             ctx.ui.notify(compatibilityError, "error");
             return;
         }
+        // ── Live MCP readiness gate ────────────────────────────────────────
+        // Units with required workflow tools must not dispatch until the MCP
+        // surface covers that exact contract; otherwise the model can race into
+        // "No such tool available" before recovery sees a clean readiness error.
+        warmWorkflowMcpProbeInBackground(projectRoot);
+        const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+        const strictBlocking = requiredWorkflowTools.length > 0
+            && (process.env.GSD_GUIDED_MCP_BLOCKING ?? "").trim() !== "0";
+        if (strictBlocking) {
+            // If the workflow MCP server is configured but still connecting, wait
+            // for it instead of dispatching into a child session that will abort.
+            const readinessFailure = await awaitWorkflowMcpReadiness(pi, ctx, projectRoot, { unitType });
+            if (readinessFailure) {
+                const detail = readinessFailure.error ? ` ${readinessFailure.error}` : "";
+                ctx.ui.notify(`GSD workflow server "${readinessFailure.server}" did not connect in time.${detail} ` +
+                    `Run \`/gsd mcp check ${readinessFailure.server}\` for details.`, "warning");
+                return;
+            }
+        }
     }
     // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
@@ -1297,6 +1385,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
 }
 export async function showSmartEntry(ctx, pi, basePath, options) {
     const stepMode = options?.step ?? true;
+    warmWorkflowMcpProbeInBackground(basePath);
     // ── Clear stale milestone ID reservations from previous cancelled sessions ──
     // Reservations only need to survive within a single /gsd interaction.
     // Without this, each cancelled session permanently bumps the next ID. (#2488)

package/dist/resources/extensions/gsd/health-widget.js

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Always-on ambient health signal rendered below the editor.
 import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
-import { runEnvironmentChecks } from "./doctor-environment.js";
+import { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
@@ -9,7 +9,28 @@ import { projectRoot } from "./commands/context.js";
 import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
 export const HEALTH_WIDGET_ACTIVE_HINTS = "  /gsd auto to run  ·  /gsd status to inspect  ·  /gsd report for snapshots  ·  /gsd notifications for history  ·  /gsd help";
 // ── Data loader ────────────────────────────────────────────────────────────────
-function loadHealthWidgetData(basePath) {
+// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
+// so it is treated like the other expensive checks: skipped on first paint,
+// run only by the background refresh.
+function loadLastCommitInfo(basePath) {
+    try {
+        if (nativeIsRepo(basePath)) {
+            const branch = nativeGetCurrentBranch(basePath);
+            const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+            if (epoch > 0) {
+                return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return { epoch: null, message: null };
+}
+function loadHealthWidgetData(basePath, options) {
+    // `includeChecks` gates the expensive subprocess-backed checks (provider +
+    // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
+    // synchronous render passes `false` so first paint is never blocked on them;
+    // the async refresh (off the first-paint path) runs the full suite.
+    const includeChecks = options?.includeChecks ?? true;
     let budgetCeiling;
     let budgetSpent = 0;
     let providerIssue = null;
@@ -28,13 +49,57 @@ function loadHealthWidgetData(basePath) {
         }
     }
     catch { /* non-fatal */ }
+    if (includeChecks) {
+        try {
+            const providerResults = runProviderChecks();
+            providerIssue = summariseProviderIssues(providerResults);
+        }
+        catch { /* non-fatal */ }
+        try {
+            const envResults = runEnvironmentChecks(basePath);
+            for (const r of envResults) {
+                if (r.status === "error")
+                    environmentErrorCount++;
+                else if (r.status === "warning")
+                    environmentWarningCount++;
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    // ── Last commit info ── (git spawns — gated like the other expensive checks)
+    if (includeChecks) {
+        const commit = loadLastCommitInfo(basePath);
+        lastCommitEpoch = commit.epoch;
+        lastCommitMessage = commit.message;
+    }
+    return {
+        projectState,
+        budgetCeiling,
+        budgetSpent,
+        providerIssue,
+        environmentErrorCount,
+        environmentWarningCount,
+        lastCommitEpoch,
+        lastCommitMessage,
+        lastRefreshed: Date.now(),
+    };
+}
+// Non-blocking variant used by the widget's background refresh: the cheap fields
+// come from the synchronous snapshot, then provider + environment checks are
+// layered in off the event-loop critical path (env checks run concurrently via
+// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
+// its initial enrichment or its 60s refresh.
+async function loadHealthWidgetDataAsync(basePath) {
+    const data = loadHealthWidgetData(basePath, { includeChecks: false });
+    let providerIssue = data.providerIssue;
+    let environmentErrorCount = 0;
+    let environmentWarningCount = 0;
     try {
-        const providerResults = runProviderChecks();
-        providerIssue = summariseProviderIssues(providerResults);
+        providerIssue = summariseProviderIssues(runProviderChecks());
     }
     catch { /* non-fatal */ }
     try {
-        const envResults = runEnvironmentChecks(basePath);
+        const envResults = await runEnvironmentChecksAsync(basePath);
         for (const r of envResults) {
             if (r.status === "error")
                 environmentErrorCount++;
@@ -43,27 +108,14 @@ function loadHealthWidgetData(basePath) {
         }
     }
     catch { /* non-fatal */ }
-    // ── Last commit info ──
-    try {
-        if (nativeIsRepo(basePath)) {
-            const branch = nativeGetCurrentBranch(basePath);
-            const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-            if (epoch > 0) {
-                lastCommitEpoch = epoch;
-                lastCommitMessage = nativeCommitSubject(basePath, branch || "HEAD") || null;
-            }
-        }
-    }
-    catch { /* non-fatal */ }
+    const commit = loadLastCommitInfo(basePath);
     return {
-        projectState,
-        budgetCeiling,
-        budgetSpent,
+        ...data,
         providerIssue,
         environmentErrorCount,
         environmentWarningCount,
-        lastCommitEpoch,
-        lastCommitMessage,
+        lastCommitEpoch: commit.epoch,
+        lastCommitMessage: commit.message,
         lastRefreshed: Date.now(),
     };
 }
@@ -77,8 +129,13 @@ export function initHealthWidget(ctx) {
     if (!ctx.hasUI)
         return;
     const basePath = projectRoot();
-    // String-array fallback — used in RPC mode (factory is a no-op there)
-    const initialData = loadHealthWidgetData(basePath);
+    // String-array fallback — used in RPC mode (factory is a no-op there).
+    // Skip the expensive provider/environment doctor checks here: this runs
+    // synchronously on the interactive-startup path, where running them would
+    // block first paint by ~0.9s (lsof/docker probes, otherwise run again
+    // immediately by the factory below). The factory's async refresh fills in
+    // real health once the screen is up.
+    const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
     ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
     // Factory-based widget for TUI mode — replaces the string-array above
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
@@ -91,7 +148,7 @@ export function initHealthWidget(ctx) {
                 return;
             refreshInFlight = true;
             try {
-                data = loadHealthWidgetData(basePath);
+                data = await loadHealthWidgetDataAsync(basePath);
                 cachedLines = undefined;
                 if (!isDisposed)
                     _tui.requestRender();
@@ -101,9 +158,11 @@ export function initHealthWidget(ctx) {
                 refreshInFlight = false;
             }
         };
-        // Fire first enrichment immediately. requestRender() inside is a no-op
-        // if the widget has not yet rendered, so this is safe before factory return.
-        void refresh();
+        // Fire the first full enrichment off the first-paint path. setTimeout(0)
+        // yields to the initial render + input loop, so the expensive doctor checks
+        // (provider + environment) never delay the moment the user sees the UI.
+        // requestRender() inside refresh repaints the widget once data is ready.
+        setTimeout(() => { void refresh(); }, 0);
         const refreshTimer = setInterval(() => {
             void refresh();
         }, REFRESH_INTERVAL_MS);

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -717,6 +717,16 @@ export function detectStaleRenders(basePath) {
     }
     return stale;
 }
+/**
+ * Render-verification helper: does the rendered ROADMAP markdown mark a slice
+ * as done? Used by completion code to verify/repair the *projection* after a
+ * DB write — never as a source of truth for dispatch or completion decisions
+ * (ADR-017). Lives here so decision-path modules need not import
+ * parsers-legacy directly.
+ */
+export function roadmapRenderMarksSliceDone(roadmapContent, sliceId) {
+    return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
+}
 export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanData) {
     const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
         ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);

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

@@ -0,0 +1,10 @@
+// mcp-bridge.ts — stable runtime seam for MCP server consumption (phase 1).
+export { loadWriteGateSnapshot, shouldBlockPendingGateInSnapshot, shouldBlockQueueExecutionInSnapshot, } from "./bootstrap/write-gate.js";
+export { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+export { _getAdapter, checkpointDatabase, closeDatabase, getAllMilestones, getDb, getGateResults, getMilestoneSlices, getPendingGates, getSliceTasks, insertDecision, insertMilestone, insertSlice, openDatabase, upsertMilestonePlanning, } from "./gsd-db.js";
+export { invalidateStateCache, isReusableGhostMilestone } from "./state.js";
+export { loadEffectiveGSDPreferences } from "./preferences.js";
+export { saveDecisionToDb, saveRequirementToDb, updateRequirementInDb, } from "./db-writer.js";
+export { rebuildState } from "./doctor.js";
+export { queryJournal } from "./journal.js";
+export { claimReservedId, findMilestoneIds, getReservedMilestoneIds, milestoneIdSort, nextMilestoneId, } from "./milestone-ids.js";