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

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

@@ -0,0 +1,87 @@
+// Project/App: gsd-pi
+// File Purpose: Publication module — push and draft-PR creation for a merged milestone (ADR-034).
+//
+// Publication is distinct from the merge verb: merging a milestone branch is a
+// Worktree Lifecycle concern (worktree, branch, lease, stash discipline);
+// publication needs only the resulting commit, a remote, and preferences.
+// Extracted from the tail of `mergeMilestoneToMain` (auto-worktree.ts) so it is
+// testable without a merge fixture and reachable from any closeout path.
+//
+// Publication failure is non-fatal to a completed local merge: every failure is
+// logged and reported in the result, never thrown.
+import { execFileSync } from "node:child_process";
+import { buildPullRequestEvidence, createDraftPullRequestFromEvidence, } from "./pull-request-process.js";
+import { logWarning } from "./workflow-logger.js";
+export function gitRemoteExists(basePath, remote) {
+    try {
+        execFileSync("git", ["remote", "get-url", remote], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Publish a merged milestone per preferences: push the integration branch
+ * (auto-push, suppressed when auto-PR owns the remote interaction) and/or
+ * push the milestone branch and open a draft PR (auto-PR).
+ */
+export function publishMilestone(request) {
+    const result = { pushed: false, prCreated: false };
+    if (request.nothingToCommit)
+        return result;
+    const { basePath, prefs } = request;
+    const remote = prefs.remote ?? "origin";
+    if (prefs.autoPush && !prefs.autoPr && gitRemoteExists(basePath, remote)) {
+        try {
+            execFileSync("git", ["push", remote, request.integrationBranch], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            });
+            result.pushed = true;
+        }
+        catch (err) {
+            // Push failure is non-fatal
+            logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // #2302: PR creation is not gated on pushed/auto-push.
+    if (prefs.autoPr && gitRemoteExists(basePath, remote)) {
+        try {
+            // Push the milestone branch to remote first
+            execFileSync("git", ["push", remote, request.milestoneBranch], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            });
+            const prEvidence = buildPullRequestEvidence({
+                milestoneId: request.milestoneId,
+                milestoneTitle: request.milestoneTitle,
+                changeType: "feat",
+                summaries: [...request.sliceSummaries],
+                testsRun: ["Auto-created after milestone merge. Run `npm run verify:merge` before marking this draft ready."],
+                rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
+                how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
+            });
+            const prUrl = createDraftPullRequestFromEvidence(basePath, request.milestoneId, prEvidence, {
+                head: request.milestoneBranch,
+                base: prefs.prTargetBranch ?? request.integrationBranch,
+            });
+            if (!prUrl) {
+                throw new Error("gh pr create returned no URL");
+            }
+            result.prCreated = true;
+            result.prUrl = prUrl;
+        }
+        catch (err) {
+            // PR creation failure is non-fatal — gh may not be installed or authenticated
+            logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}

package/dist/resources/extensions/gsd/reactive-graph.js

@@ -10,7 +10,11 @@
  */
 import { loadFile, parseTaskPlanIO } from "./files.js";
 import { isDbAvailable, getSliceTasks } from "./gsd-db.js";
+// Explicit degraded-mode fallback ONLY (ADR-017): parsePlan is consulted when
+// the DB is unavailable or has no task rows for the slice; the DB path in
+// loadSliceTaskIO always wins when rows exist, and the fallback logs a warning.
 import { parsePlan } from "./parsers-legacy.js";
+import { logWarning } from "./workflow-logger.js";
 import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
 import { join } from "node:path";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
@@ -178,7 +182,10 @@ export async function loadSliceTaskIO(basePath, mid, sid) {
     }
     catch { /* fall through */ }
     if (!taskEntries) {
-        // File-based fallback: parse slice plan for task entries
+        // Degraded-mode fallback (ADR-017): no DB task rows for this slice —
+        // parse the PLAN.md projection instead. Warn so silent drift from the
+        // DB-authoritative path is visible in logs.
+        logWarning("projection", `reactive-graph: DB unavailable or no task rows for ${mid}/${sid}; falling back to PLAN.md parsing`);
         const parsed = parsePlan(planContent);
         if (parsed.tasks.length > 0) {
             taskEntries = parsed.tasks.map(t => ({

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

@@ -1,6 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
+import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 export function classifyFailure(input) {
@@ -13,103 +15,44 @@ export function classifyFailure(input) {
         : input.error instanceof IllegalPhaseTransitionError
             ? "illegal-transition"
             : input.failureKind ?? inferFailureKind(message);
-    switch (failureKind) {
-        case "tool-schema":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-schema",
-                remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
-            };
-        case "tool-contract":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-contract",
-                remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
-            };
-        case "deterministic-policy":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
-                exitReason: "deterministic-policy",
-                remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
-            };
-        case "lifecycle-progression":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
-                exitReason: "lifecycle-progression",
-                remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
-            };
-        case "stale-worker":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
-                exitReason: "stale-worker",
-                remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
-            };
-        case "worktree-invalid":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
-                exitReason: "worktree-invalid",
-                remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
-            };
-        case "verification-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Verification drift${unitSuffix(input)}: ${message}`,
-                exitReason: "verification-drift",
-                remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
-            };
-        case "reconciliation-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
-                exitReason: "reconciliation-drift",
-                remediation: "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
-            };
-        case "illegal-transition":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Illegal phase transition${unitSuffix(input)}: ${message}`,
-                exitReason: "illegal-transition",
-                remediation: "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
-            };
-        case "provider": {
-            const providerClass = classifyError(message, input.retryAfterMs);
-            return {
-                failureKind,
-                action: isTransient(providerClass) ? "retry" : "escalate",
-                reason: message,
-                exitReason: `provider-${providerClass.kind}`,
-                remediation: isTransient(providerClass)
-                    ? "Retry after the provider/network condition clears."
-                    : "Inspect provider credentials, model entitlement, or request shape.",
-                providerClass: providerClass.kind,
-            };
-        }
-        case "runtime-unknown":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: message,
-                exitReason: "runtime-unknown",
-                remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
-            };
+    if (failureKind === "provider") {
+        const providerClass = classifyError(message, input.retryAfterMs);
+        const transient = isTransient(providerClass);
+        return {
+            failureKind,
+            action: transient ? "retry" : "escalate",
+            reason: message,
+            exitReason: `provider-${providerClass.kind}`,
+            remediation: recoveryRemediation(transient ? "provider-transient" : "provider-permanent"),
+            providerClass: providerClass.kind,
+        };
     }
+    const { action, label } = FAILURE_TAXONOMY[failureKind];
+    return {
+        failureKind,
+        action,
+        reason: label ? `${label}${unitSuffix(input)}: ${message}` : message,
+        exitReason: failureKind,
+        remediation: recoveryRemediation(failureKind),
+    };
 }
+/** Per-kind action and reason label. Remediation lives in the Guidance module. */
+const FAILURE_TAXONOMY = {
+    "tool-schema": { action: "stop", label: "Tool schema failure" },
+    "tool-contract": { action: "stop", label: "Tool Contract failure" },
+    "tool-unavailable": { action: "retry", label: "Tool unavailable" },
+    "deterministic-policy": { action: "stop", label: "Deterministic policy failure" },
+    "lifecycle-progression": { action: "stop", label: "Lifecycle progression failure" },
+    "stale-worker": { action: "stop", label: "Stale worker failure" },
+    "worktree-invalid": { action: "stop", label: "Worktree invalid" },
+    "verification-drift": { action: "escalate", label: "Verification drift" },
+    "reconciliation-drift": { action: "escalate", label: "Reconciliation drift" },
+    "illegal-transition": { action: "escalate", label: "Illegal phase transition" },
+    "runtime-unknown": { action: "escalate", label: null },
+};
 function inferFailureKind(message) {
+    if (isToolUnavailableError(message))
+        return "tool-unavailable";
     if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))
         return "tool-contract";
     if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message))

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -161,6 +161,26 @@ function parseTableSlices(section) {
     }
     return slices;
 }
+function looksLikeTable(section) {
+    const lines = section.split("\n");
+    // Checkbox format takes precedence — embedded demo tables must not switch mode (#721).
+    if (lines.some(line => /^\s*-\s+\[[ xX]\]/.test(line))) {
+        return false;
+    }
+    const pipeLines = lines.filter(line => /^\s*\|/.test(line));
+    if (pipeLines.length < 2)
+        return false;
+    const hasSeparatorRow = pipeLines.some((line, index) => {
+        if (index === 0)
+            return false;
+        const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+        return /^\s*\|[\s:-]+\|/.test(line) && cells.length >= 2 && cells.every(c => /^[\s:-]+$/.test(c));
+    });
+    if (hasSeparatorRow)
+        return true;
+    // Tables without a separator row still expose slice IDs in data rows.
+    return pipeLines.some(line => /\bS\d+\b/.test(line));
+}
 export function parseRoadmapSlices(content) {
     const slicesSection = extractSlicesSection(content);
     if (!slicesSection) {
@@ -171,9 +191,11 @@ export function parseRoadmapSlices(content) {
     }
     // Try table format first — if the section contains pipe-delimited rows with
     // slice IDs, parse them as a table (#1736).
-    const tableSlices = parseTableSlices(slicesSection);
-    if (tableSlices.length > 0) {
-        return tableSlices;
+    if (looksLikeTable(slicesSection)) {
+        const tableSlices = parseTableSlices(slicesSection);
+        if (tableSlices.length > 0) {
+            return tableSlices;
+        }
     }
     // Standard checkbox format
     const slices = [];

package/dist/resources/extensions/gsd/safety/destructive-confirmation.js

@@ -0,0 +1,108 @@
+/**
+ * One-shot confirmation token for destructive bash commands.
+ *
+ * The destructive-command guard hard-blocks classified commands (force push,
+ * rm -rf, SQL drop, etc.) in all modes. The block instructs the model to
+ * confirm via ask_user_questions and re-issue the command. This module is the
+ * missing escape hatch: it records the user's confirmation and lets the exact
+ * confirmed command through exactly once.
+ *
+ * Design constraints:
+ *  - In-memory only, never persisted. A confirmation token written to disk
+ *    could silently auto-approve a destructive command in a later session —
+ *    confirmation must be re-obtained every process lifetime.
+ *  - One-shot. Consuming a token clears it, so a second destructive command
+ *    (even an identical one) re-blocks and re-prompts.
+ *  - Command-bound. The token only matches the exact (normalized) command
+ *    string the user confirmed. A reworded command re-blocks, which is safe.
+ *  - Per basePath, so concurrent workspaces in one process never share tokens.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+import { resolve } from "node:path";
+/**
+ * Question-id substring that marks an ask_user_questions call as a
+ * destructive-command confirmation. The tool_result handler promotes the
+ * pending command to a confirmed token when an affirmative answer arrives for
+ * a question whose id contains this marker.
+ */
+export const DESTRUCTIVE_CONFIRM_GATE_MARKER = "destructive_confirm";
+const statesByBasePath = new Map();
+function stateKey(basePath) {
+    return resolve(basePath);
+}
+function getState(basePath) {
+    const key = stateKey(basePath);
+    let state = statesByBasePath.get(key);
+    if (!state) {
+        state = { pendingCommand: null, confirmedCommand: null };
+        statesByBasePath.set(key, state);
+    }
+    return state;
+}
+/**
+ * Normalize a command for stable matching across block → confirm → retry.
+ * Trims surrounding whitespace and collapses internal runs of whitespace so
+ * cosmetic reformatting of the same command still matches the token.
+ */
+export function normalizeDestructiveCommand(command) {
+    return command.replace(/\s+/g, " ").trim();
+}
+/**
+ * Whether an ask_user_questions question id is a destructive-confirm gate.
+ */
+export function isDestructiveConfirmGateId(questionId) {
+    return typeof questionId === "string" && questionId.includes(DESTRUCTIVE_CONFIRM_GATE_MARKER);
+}
+/**
+ * Record that a destructive command was blocked and is awaiting confirmation.
+ * Called by the guard at block time. Overwrites any prior pending command —
+ * only the most recently blocked command can be confirmed.
+ */
+export function requestDestructiveConfirmation(command, basePath = process.cwd()) {
+    const state = getState(basePath);
+    state.pendingCommand = normalizeDestructiveCommand(command);
+    // A fresh request invalidates any stale confirmed token for a different
+    // command so confirmation cannot leak across distinct destructive actions.
+    state.confirmedCommand = null;
+}
+/**
+ * Promote the pending command to a confirmed, one-shot token. Called by the
+ * tool_result handler when the user gives an affirmative answer to a
+ * destructive-confirm gate. Returns the confirmed command, or null if there
+ * was nothing pending (e.g. confirmation arrived without a preceding block).
+ */
+export function confirmDestructiveCommand(basePath = process.cwd()) {
+    const state = getState(basePath);
+    if (!state.pendingCommand)
+        return null;
+    state.confirmedCommand = state.pendingCommand;
+    state.pendingCommand = null;
+    return state.confirmedCommand;
+}
+/**
+ * Check whether the given command has been confirmed, consuming the token if
+ * so. Returns true exactly once per confirmation; subsequent calls (or a
+ * non-matching command) return false. Called by the guard before blocking.
+ */
+export function consumeDestructiveConfirmation(command, basePath = process.cwd()) {
+    const state = getState(basePath);
+    if (!state.confirmedCommand)
+        return false;
+    if (state.confirmedCommand !== normalizeDestructiveCommand(command))
+        return false;
+    state.confirmedCommand = null;
+    return true;
+}
+/**
+ * Inspect the pending command without consuming it (diagnostics/tests).
+ */
+export function peekPendingDestructiveCommand(basePath = process.cwd()) {
+    return getState(basePath).pendingCommand;
+}
+/**
+ * Clear all destructive-confirmation state for a basePath (tests / flow reset).
+ */
+export function resetDestructiveConfirmation(basePath = process.cwd()) {
+    statesByBasePath.delete(stateKey(basePath));
+}

package/dist/resources/extensions/gsd/session-lock.js

@@ -329,7 +329,7 @@ export function acquireSessionLock(basePath) {
         // #3218: Provide actionable workaround when lock recovery fails
         const lockDirPath = lockTarget + ".lock";
         const reason = existingPid
-            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
+            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nRun \`/gsd stop\` for graceful shutdown, or choose "Force start" from \`/gsd auto\` to terminate it.`
             : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`;
         return { acquired: false, reason, existingPid };
     }

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

@@ -3,6 +3,11 @@
 // GSD Extension — State Derivation
 // DB-authoritative runtime derivation with explicit legacy filesystem fallback.
 // Pure TypeScript, zero Pi dependencies.
+// Pre-migration fallback ONLY (ADR-017): deriveState must work on projects
+// whose DB does not exist yet (before md-importer runs), so it parses markdown
+// projections when `isDbAvailable()` is false or the DB has no rows. Once the
+// DB is populated, decision reads go through gsd-db queries — these parsers
+// must never be consulted when DB data is present.
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
@@ -22,26 +27,7 @@ import { isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getS
 import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
 import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from './milestone-readiness.js';
-function formatNeedsAttentionBlocker(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");
-}
-function formatNeedsRemediationBlocker(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");
-}
+import { needsAttentionBlockerGuidance as formatNeedsAttentionBlocker, needsRemediationBlockerGuidance as formatNeedsRemediationBlocker, } from './guidance.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
  * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY).  These appear when

package/dist/resources/extensions/gsd/stop-notice.js

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason) {
+    return /^Blocked:\s*/i.test(reason ?? "");
+}
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason) {
+    return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+export function stopNoticeKind(reason) {
+    return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason) {
+    const displayReason = stopNoticeDisplayReason(reason);
+    const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+    return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"];
+export const TERMINAL_NOTICE_PREFIXES = [
+    "auto-mode stopped",
+    "step-mode stopped",
+    "auto-mode complete",
+    "no active milestone",
+    "auto-mode idle",
+];
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message) {
+    return (message.includes("resolve manually and re-run /gsd auto") ||
+        message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+        message.includes("resolve and run /gsd auto to resume"));
+}
+export function isPauseNotice(message) {
+    return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+export function isTerminalNotice(message) {
+    return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message) {
+    return message.includes("idempotent advance: unit already active");
+}
+export function isBlockedNoticeMessage(message) {
+    return (message.includes("blocked:") ||
+        (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+        isManualResolutionNotice(message));
+}

package/dist/resources/extensions/gsd/tool-contract.js

@@ -1,8 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import { getWorkflowTransportSupportError, } from "./workflow-mcp.js";
+import { getRequiredWorkflowToolsForUnit, getUnitToolSurfaceContract, } from "./unit-tool-contracts.js";
 import { WHOLE_FILE_OBSERVATION_MAX_BYTES, WHOLE_FILE_OBSERVATION_MAX_LINES, } from "./source-observations.js";
 export function compileUnitContextContract(unitType) {
     const manifest = resolveManifest(unitType);
@@ -15,6 +15,17 @@ export function compileUnitContextContract(unitType) {
     }
     return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
 }
+export function getUnitWorkflowDispatchReadinessError(input) {
+    return getWorkflowTransportSupportError(input.provider, getRequiredWorkflowToolsForUnit(input.unitType), {
+        projectRoot: input.projectRoot,
+        env: input.env,
+        surface: input.surface,
+        unitType: input.unitType,
+        authMode: input.authMode,
+        baseUrl: input.baseUrl,
+        activeTools: input.activeTools,
+    });
+}
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -25,7 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `No Unit manifest is registered for ${unitType}`,
         };
     }
-    const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
     const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
         .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));

package/dist/resources/extensions/gsd/tool-presentation-plan.js

@@ -4,7 +4,7 @@ import { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_
 import { toMcpToolName } from "./mcp-tool-name.js";
 import { createToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
-import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 export { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
     "edit",
@@ -24,9 +24,9 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
     "Glob",
     "Grep",
 ];
-export function canonicalWorkflowToolName(toolName) {
-    return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
 export { parseMcpToolName } from "./mcp-tool-name.js";
 export function toWorkflowMcpToolName(serverName, toolName) {
     return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));

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

@@ -0,0 +1,56 @@
+// 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 { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+/**
+ * Stable phrase recognized as transient by auto-tool-tracking's
+ * isToolUnavailableError and error-classifier's transient buckets,
+ * which build their matchers from this constant.
+ */
+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 function getToolSurfaceReadinessError(input) {
+    const { unitType, workflowServerName, observation } = input;
+    if (!unitType || !workflowServerName)
+        return null;
+    const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+    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;
+    }
+    const missing = required.filter((tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+    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(", ")}`;
+}