@opengsd/gsd-pi 1.2.0-dev.9ad8ae33 → 1.2.0-dev.a6376d75

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/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";

package/dist/resources/extensions/gsd/milestone-settlement.js

@@ -43,8 +43,8 @@ export function evaluateAllCompleteSettlement(input) {
         reason: "merge-pending",
         action: "pause",
         message: `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
-            `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
-        nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+            `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` to finish the system-owned merge.`,
+        nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
         milestoneId,
     };
 }

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

@@ -2,31 +2,36 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { sendRemoteNotification } from "../remote-questions/notify.js";
+import { sendRemoteNotification as _sendRemoteNotification } from "../remote-questions/notify.js";
+/** Swappable dispatcher for remote notifications — exported so tests can mock it. */
+export const remoteNotificationDispatcher = {
+    send: _sendRemoteNotification,
+};
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
  */
-export function sendDesktopNotification(title, message, level = "info", kind = "complete", projectName) {
+export function sendDesktopNotification(title, message, level = "info", kind = "complete", projectName, deps = {}) {
     // When a projectName is provided and the title is the default "GSD",
     // replace it with a project-qualified title for multi-project clarity.
     if (projectName && title === "GSD") {
         title = formatNotificationTitle(projectName);
     }
-    const loaded = loadEffectiveGSDPreferences()?.preferences;
+    const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+    const notifications = deps.notifications ?? loadedPreferences?.notifications;
     // Remote notifications fire independently of desktop preferences.
     // sendRemoteNotification handles "not configured" gracefully (early return).
-    void sendRemoteNotification(title, message).catch(() => { });
-    if (!shouldSendDesktopNotification(kind, loaded?.notifications))
+    void remoteNotificationDispatcher.send(title, message).catch(() => { });
+    if (!shouldSendDesktopNotification(kind, notifications))
         return;
     // cmux delivery and desktop delivery are independent — if cmux import or
     // delivery fails, we must still attempt the native desktop notification.
     const runCmux = async () => {
         try {
             const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
-            const cmux = resolveCmuxConfig(loaded);
+            const cmux = resolveCmuxConfig(loadedPreferences);
             if (cmux.notifications) {
-                const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+                const delivered = CmuxClient.fromPreferences(loadedPreferences).notify(title, message);
                 if (delivered)
                     return true;
                 emitOsc777Notification(title, message);

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -38,7 +38,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
 11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare the type as a bullet under a `## UAT Type` heading, exactly like `- UAT mode: browser-executable`.
     **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
-12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `capture_thought`; do not append knowledge files.
+12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `gsd_capture_thought` (MCP-scoped `mcp__...__gsd_capture_thought`), not bare `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
 14. Do not run git commands.
 15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -52,6 +52,7 @@ You execute. The inlined task plan is authoritative. Verify referenced files and
 
 - If task sections exist for Failure Modes (Q5), Load Profile (Q6), Negative Tests (Q7), or Observability Impact, implement and verify them.
 - Verify must-haves with concrete commands or observable behavior.
+- Run verification commands through `gsd_exec` / Context Mode evidence when workflow MCP tools are presented. Use `gsd_exec_search` before rerunning noisy checks, and `gsd_resume` after compaction or resume. Do not call direct `bash` for final verification evidence in this unit.
 - Run slice-level verification from the slice plan. Final tasks need all checks passing; intermediate tasks should record partial passes.
 - Populate `## Verification Evidence` with `formatEvidenceTable` rows: command, exit code, verdict, duration. If no checks were found, say so.
 - For UI/browser/DOM/user-visible web changes, exercise the real flow and record explicit checks.
@@ -64,7 +65,7 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 - If the plan is fundamentally invalid, set `blocker_discovered: true` in the summary and explain.
 - For downstream-impacting ambiguity that cannot be resolved from code, plans, or decisions, include an `escalation` object with question, options, recommendation, rationale, and `continueWithDefault`.
-- Capture meaningful architecture/pattern/observability decisions with `capture_thought`; capture non-obvious gotchas or conventions only when they save future investigation.
+- Capture meaningful architecture/pattern/observability decisions with `gsd_capture_thought` (or MCP-scoped `mcp__...__gsd_capture_thought`) when workflow MCP tools are presented; capture non-obvious gotchas or conventions only when they save future investigation.
 - Use the inlined Task Summary template below. Read `{{taskSummaryTemplatePath}}` only if the inlined template is absent or visibly truncated.
 - Call `gsd_task_complete` with camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Include `blockerDiscovered: true` when a stale-path safety failure or other plan-invalidating blocker prevents execution.
 - The DB-backed tool is the canonical write path. Do **not** manually write `{{taskSummaryPath}}` or edit PLAN.md checkboxes; the tool renders the summary and updates state.

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -10,6 +10,8 @@ If any inlined plan, summary, verification command, or prior artifact names an a
 
 All relevant context has been preloaded below. Start working immediately without re-reading these files.
 
+If a `.gsd/**` or `.gsd/**/*` glob returns no matches, treat that as a possible symlink-backed traversal limitation; do not infer that the GSD harness is missing. Use the preloaded UAT context and direct `.gsd/...` file paths named in this prompt instead.
+
 {{inlinedContext}}
 
 {{skillActivation}}

package/dist/resources/extensions/gsd/prompts/workflow-start.md

@@ -25,4 +25,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
 4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
 5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new phase.
-6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.
+6. **Persist workflow state.** If the artifact directory contains `STATE.json`, update it after each phase: mark the finished phase `completed`, mark the next phase `active`, set `currentPhase` to the active phase index, and refresh `updatedAt`. When every phase is completed, set `completedAt` to the completion timestamp.
+7. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/dist/resources/extensions/gsd/skill-activation.js

@@ -108,11 +108,8 @@ function formatSkillActivationBlock(skillNames) {
     const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
     if (safe.length === 0)
         return "";
-    // Use explicit parameter syntax so LLMs pass { skill: "..." } instead of { name: "..." }.
-    // The function-call-like syntax `Skill('name')` led LLMs to infer a positional
-    // parameter name, causing tool validation failures — see #2224.
-    const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
-    return `<skill_activation>${calls}.</skill_activation>`;
+    const reads = safe.map(name => `Read the installed '${name}' skill file from <available_skills>`).join(". ");
+    return `<skill_activation>${reads}.</skill_activation>`;
 }
 /**
  * Manifest-driven recommendations block — informational only, does NOT
@@ -132,7 +129,7 @@ function formatSkillRecommendationsBlock(unitType, skillNames) {
     const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
     if (safe.length === 0)
         return "";
-    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider reading these installed skill files from <available_skills>: ${safe.join(", ")}. These are recommendations, not requirements.</skill_recommendations>`;
 }
 export function buildSkillActivationBlock(params) {
     const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;

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

@@ -23,7 +23,7 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
-import { isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { isDbAvailable, getAllMilestones, getMilestone, getSlicesByMilestoneIds, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
 import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
 import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from './milestone-readiness.js';
@@ -366,12 +366,16 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
     let activeMilestoneFound = false;
     let activeMilestoneHasDraft = false;
     let firstDeferredQueuedShell = null;
+    const activeMilestoneIds = milestones
+        .filter((m) => !parkedMilestoneIds.has(m.id))
+        .map((m) => m.id);
+    const slicesByMilestone = getSlicesByMilestoneIds(activeMilestoneIds);
     for (const m of milestones) {
         if (parkedMilestoneIds.has(m.id)) {
             registry.push({ id: m.id, title: stripMilestonePrefix(m.title) || m.id, status: 'parked' });
             continue;
         }
-        const slices = getMilestoneSlices(m.id);
+        const slices = slicesByMilestone.get(m.id) ?? [];
         // DB-authoritative completeness (#4179): only trust completeMilestoneIds,
         // which is itself derived from DB status. SUMMARY-file presence alone must
         // not imply completion.

package/dist/resources/extensions/gsd/tool-surface-readiness.js

@@ -1,7 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
+import { testMcpServerConnection } from "../mcp-client/manager.js";
 import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { recordWorkflowMcpProbe, WORKFLOW_MCP_PROBE_TIMEOUT_MS, } from "./workflow-mcp-readiness-cache.js";
+import { resolveWorkflowMcpProjectRoot } from "./workflow-mcp.js";
 import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 /**
  * Stable phrase recognized as transient by auto-tool-tracking's
@@ -11,20 +14,73 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
 /** MCP server statuses that will not self-heal within the session. */
 const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
-/**
- * Verify the live tool surface observed at SDK session init covers the Unit's
- * required workflow tools. Complements the static pre-dispatch gate
- * (getWorkflowTransportSupportError), which only proves the MCP launch config
- * is discoverable — the workflow server connects asynchronously after session
- * start, so the static gate cannot see whether the tools actually registered.
- *
- * Returns a transient, recovery-classifiable error (kind tool-unavailable →
- * retry) when the workflow server failed or has not yet registered a required
- * tool, so dispatch aborts before the first model turn instead of letting the
- * Unit improvise around "No such tool available". Returns null when no
- * workflow server is part of this session (native tool path), when the Unit
- * requires no workflow tools, or when the surface is ready.
- */
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS = 30_000;
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS = 200;
+const RUN_UAT_PREFLIGHT_TIMEOUT_MS = 90_000;
+function resolveWorkflowMcpPreflightTimeoutMs(unitType) {
+    if (unitType === "run-uat")
+        return RUN_UAT_PREFLIGHT_TIMEOUT_MS;
+    return DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS;
+}
+export function probeCoversRequiredWorkflowTools(tools, required) {
+    return required.every((tool) => tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+}
+export async function awaitWorkflowMcpToolRegistration(input) {
+    const { unitType, workflowServerName, projectRoot } = input;
+    if (!unitType || !workflowServerName)
+        return null;
+    const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+    if (required.length === 0)
+        return null;
+    const probe = input.probe ?? (async (serverName, root) => {
+        const result = await testMcpServerConnection(serverName, {
+            projectDir: resolveWorkflowMcpProjectRoot(root),
+            timeoutMs: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+        });
+        return { ok: result.ok, tools: result.tools };
+    });
+    const deadline = Date.now() + (input.timeoutMs ?? resolveWorkflowMcpPreflightTimeoutMs(unitType));
+    const pollMs = input.pollMs ?? DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS;
+    while (Date.now() < deadline) {
+        throwIfAborted(input.signal);
+        const result = await probe(workflowServerName, projectRoot);
+        throwIfAborted(input.signal);
+        if (result.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
+            recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
+            return null;
+        }
+        await sleep(pollMs, input.signal);
+    }
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+}
+function makeAbortError() {
+    const error = new Error("AbortError: The operation was aborted");
+    error.name = "AbortError";
+    return error;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw makeAbortError();
+}
+function sleep(ms, signal) {
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(makeAbortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Brief pause after a successful preflight before SDK query (race with MCP attach). */
+export const POST_PREFLIGHT_SDK_SETTLE_MS = 750;
+export const POST_PREFLIGHT_READINESS_RETRY_DELAYS_MS = [
+    1_000, 2_000, 3_000, 5_000, 8_000, 10_000, 15_000, 15_000, 15_000, 15_000,
+];
 export function getToolSurfaceReadinessError(input) {
     const { unitType, workflowServerName, observation } = input;
     if (!unitType || !workflowServerName)
@@ -33,24 +89,20 @@ export function getToolSurfaceReadinessError(input) {
     if (required.length === 0)
         return null;
     const server = observation.mcpServers.find((entry) => entry.name === workflowServerName);
-    if (!server) {
-        return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${required.join(", ")}`;
-    }
-    // The SDK does not wait for MCP servers before init — a still-connecting
-    // server reports "pending" there routinely, then registers within seconds,
-    // usually well before the Unit's first workflow tool call. Aborting on
-    // "pending" would fail the common healthy session, so it passes through;
-    // a genuine miss after pass-through still surfaces in-session as
-    // "No such tool available" and classifies tool-unavailable → bounded retry.
-    // Only statuses that cannot self-heal abort here.
-    if (server.status !== "connected" && !TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
-        return null;
+    if (server && TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
+        const missing = required.filter((tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+        const tools = missing.length > 0 ? missing : required;
+        return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (terminal) — cannot register: ${tools.join(", ")}`;
     }
     const missing = required.filter((tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
-    if (missing.length === 0)
+    if (missing.length === 0) {
         return null;
-    const serverDetail = server.status === "connected"
-        ? `MCP server "${workflowServerName}" is connected but has not registered`
-        : `MCP server "${workflowServerName}" status is "${server.status}" and it has not registered`;
-    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: ${serverDetail}: ${missing.join(", ")}`;
+    }
+    if (!server) {
+        return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${missing.join(", ")}`;
+    }
+    if (server.status !== "connected") {
+        return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (not yet connected): ${missing.join(", ")}`;
+    }
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is connected but has not registered: ${missing.join(", ")}`;
 }

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -8,6 +8,7 @@
  * Projection write failures are reported as stale projections and do not roll
  * back committed DB state.
  */
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { isClosedStatus } from "../status-guards.js";
 import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
@@ -29,6 +30,35 @@ import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.
 function taskSummaryPath(basePath, milestoneId, sliceId, taskId) {
     return join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks", `${taskId}-SUMMARY.md`);
 }
+async function repairMissingTaskSummaryProjection(artifactBasePath, taskRow) {
+    const summaryPath = taskSummaryPath(artifactBasePath, taskRow.milestone_id, taskRow.slice_id, taskRow.id);
+    const summaryMd = renderSummaryContent(taskRow, taskRow.slice_id, taskRow.milestone_id, []);
+    let stale = false;
+    try {
+        await saveFile(summaryPath, summaryMd);
+        await renderPlanCheckboxes(artifactBasePath, taskRow.milestone_id, taskRow.slice_id);
+    }
+    catch (renderErr) {
+        stale = true;
+        logWarning("projection", `complete_task missing-summary repair failed for ${taskRow.milestone_id}/${taskRow.slice_id}/${taskRow.id}`, { error: renderErr.message });
+    }
+    invalidateStateCache();
+    clearPathCache();
+    clearParseCache();
+    try {
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+    }
+    catch (projErr) {
+        logWarning("tool", `complete-task repair projection warning: ${projErr.message}`);
+    }
+    try {
+        writeManifest(artifactBasePath);
+    }
+    catch (mfErr) {
+        logWarning("tool", `complete-task repair manifest warning: ${mfErr.message}`);
+    }
+    return { summaryPath, stale };
+}
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
  * presence drives `pass` vs. `omitted`. Keep in lockstep with the gates
@@ -136,6 +166,7 @@ export async function handleCompleteTask(params, basePath) {
     const completedAt = new Date().toISOString();
     let guardError = null;
     let summaryMd = "";
+    let repairTaskSummaryRow = null;
     // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
     // Building the artifact runs the full shape validation (2-4 options, unique
     // ids, recommendation references a real id). If the payload is malformed
@@ -197,6 +228,12 @@ export async function handleCompleteTask(params, basePath) {
                 guardError = "__stale_duplicate__";
                 return;
             }
+            const existingSummaryPath = taskSummaryPath(artifactBasePath, params.milestoneId, params.sliceId, params.taskId);
+            if (existingTask.full_summary_md.trim() && !existsSync(existingSummaryPath)) {
+                repairTaskSummaryRow = existingTask;
+                guardError = "__repair_missing_summary__";
+                return;
+            }
             guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
             return;
         }
@@ -252,6 +289,17 @@ export async function handleCompleteTask(params, basePath) {
             stale: true,
         };
     }
+    if (guardError === "__repair_missing_summary__" && repairTaskSummaryRow) {
+        const repair = await repairMissingTaskSummaryProjection(artifactBasePath, repairTaskSummaryRow);
+        return {
+            taskId: params.taskId,
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            summaryPath: repair.summaryPath,
+            duplicate: true,
+            ...(repair.stale ? { stale: true } : {}),
+        };
+    }
     if (guardError) {
         return { error: guardError };
     }
@@ -349,6 +397,20 @@ export async function handleCompleteTask(params, basePath) {
         }
     }
     else if (params.escalation && !escalationWriteEnabled) {
+        if (params.escalation.continueWithDefault === false) {
+            const msg = `complete-task received a hard-blocker escalation (continueWithDefault=false) but phases.mid_execution_escalation is disabled for ${params.milestoneId}/${params.sliceId}/${params.taskId}; reverting to pending instead of silently advancing.`;
+            logWarning("tool", msg);
+            try {
+                deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+                updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+                invalidateStateCache();
+                logWarning("tool", `complete-task rolled back DB completion for ${params.milestoneId}/${params.sliceId}/${params.taskId} because hard-blocker escalation handling is disabled; SUMMARY.md left on disk for retry.`);
+            }
+            catch (rollbackErr) {
+                logWarning("tool", `complete-task rollback failed after disabled hard-blocker escalation for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${rollbackErr.message}`);
+            }
+            return { error: msg };
+        }
         logWarning("tool", `complete-task received escalation payload but phases.mid_execution_escalation is not enabled; ignoring (${params.milestoneId}/${params.sliceId}/${params.taskId})`);
     }
     // Invalidate all caches

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -125,7 +125,7 @@ export function composeContextModeInstructions(unitType, opts) {
 }
 const TOOL_SURFACE_GUIDANCE_BY_UNIT = {
     "run-uat": "Do not call `gsd_exec`, `Bash`, `Write`, or `Edit` — they are unavailable in this unit. Run every automated check through `gsd_uat_exec` with the appropriate `intent`. For browser UAT modes, use `browser_*` tools when presented; if browser automation fails, record the failure honestly and use `gsd_uat_exec` for the best objective substitute.",
-    "complete-slice": "Run slice-level verification through `gsd_exec` (or MCP-scoped `mcp__…__gsd_exec`), not direct `bash`. Do not call `gsd_uat_result_save` — run-uat owns persisted UAT assessment. On verification failure, do not edit user source files in this unit.",
+    "complete-slice": "Run slice-level verification through `gsd_exec` (or MCP-scoped `mcp__…__gsd_exec`), not direct `bash`. Capture learnings through `gsd_capture_thought` (or MCP-scoped `mcp__…__gsd_capture_thought`), not bare `capture_thought`, when workflow MCP tools are presented. Do not call `gsd_uat_result_save` — run-uat owns persisted UAT assessment. On verification failure, do not edit user source files in this unit.",
     "gate-evaluate": "Dispatch only **tester** subagents via `subagent`. Persist each gate with `gsd_save_gate_result`. Do not use `ToolSearch` — it is not available.",
     "reactive-execute": "Dispatch only **worker** subagents via `subagent`. Do not call `gsd_task_complete` from this parent batch — each worker owns its task completion. If a failed task left no summary, call `gsd_summary_save` with `blocker_discovered: true`.",
     "execute-task": "Complete only this task via `gsd_task_complete`. Do not call `gsd_slice_complete`, `gsd_validate_milestone`, or `gsd_complete_milestone` — the orchestrator owns phase transitions.",