@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -16,7 +16,7 @@ import { deriveState } from "./state.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
-import { isAwaitingUserInput } from "./user-input-boundary.js";
+import { isAwaitingUserInput } from "./consent-question.js";
 import { resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, buildTaskFileName, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { rebuildState } from "./doctor.js";
@@ -30,8 +30,7 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
-import { renderPlanCheckboxes, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
+import { renderPlanCheckboxes, renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import { checkPostUnitHooks, consumeHookFailure, isRetryPending, consumeRetryTrigger, consumeGateBlock, persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js";
 import { hasPendingCaptures, loadPendingCaptures, revertExecutorResolvedCaptures } from "./captures.js";
@@ -39,7 +38,7 @@ import { debugLog } from "./debug-logger.js";
 import { runSafely } from "./auto-utils.js";
 import { isMilestoneCloseoutSettled, runMilestoneCloseoutGitHub, } from "./milestone-closeout.js";
 import { getEvidence, clearEvidenceFromDisk, isExecutionToolName } from "./safety/evidence-collector.js";
-import { validateFileChanges } from "./safety/file-change-validator.js";
+import { validateFileChanges, effectiveFileChangeAllowlist } from "./safety/file-change-validator.js";
 import { crossReferenceEvidence } from "./safety/evidence-cross-ref.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
@@ -55,11 +54,12 @@ import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
 import { detectAbandonMilestone } from "./abandon-detect.js";
 import { getPendingGate } from "./bootstrap/write-gate.js";
-import { isDeterministicPolicyError } from "./auto-tool-tracking.js";
+import { isDeterministicPolicyError, isToolUnavailableError } from "./auto-tool-tracking.js";
 import { formatConnectedStepStack, formatPostUnitStatusCard } from "./auto-status-message.js";
 import { clearProjectResearchInflightMarker, finalizeProjectResearchTimeout, } from "./project-research-policy.js";
 import { validateArtifact } from "./schemas/validate.js";
 import { verificationRetryKey } from "./auto/verification-retry-policy.js";
+import { saveCustomVerifyRetryCounts } from "./auto/custom-verify-retry-store.js";
 import { getLedger } from "./metrics.js";
 import { getUnitCostSpikeAction, resolveUnitCostSpikeMultiplier } from "./auto-budget.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
@@ -507,9 +507,10 @@ export function _hasExecutionToolCallsInSessionForTest(entries) {
         if (e?.type === "toolCall" && isExecutionToolName(e?.name ?? e?.toolName)) {
             return true;
         }
-        if (e?.type !== "message")
-            continue;
-        const msg = e?.message;
+        // Accept both session-manager entries ({type: "message", message}) and
+        // bare agent-end messages ({role, content}) — the auto loop passes the
+        // latter via opts.agentEndMessages.
+        const msg = e?.type === "message" ? e?.message : e;
         if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content))
             continue;
         for (const block of msg.content) {
@@ -721,7 +722,7 @@ export const USER_DRIVEN_DEEP_UNITS = new Set([
     "discuss-milestone",
     "research-decision",
 ]);
-export { isAwaitingUserInput } from "./user-input-boundary.js";
+export { isAwaitingUserInput } from "./consent-question.js";
 function artifactValidationKind(unitType) {
     if (unitType === "discuss-project")
         return "project";
@@ -799,11 +800,13 @@ async function repairCompleteSliceRoadmapProjection(unitType, unitId, basePath)
     if (!summaryPath || !existsSync(summaryPath) || !uatPath || !existsSync(uatPath)) {
         return false;
     }
+    // Stale-render detection (ADR-017): the DB already says the slice is closed;
+    // this only checks whether the rendered ROADMAP projection reflects it, to
+    // decide whether a repair re-render is needed.
     const roadmapPath = resolveMilestoneFile(artifactBase, mid, "ROADMAP");
     if (roadmapPath && existsSync(roadmapPath)) {
         try {
-            const roadmap = parseLegacyRoadmap(readFileSync(roadmapPath, "utf-8"));
-            if (roadmap.slices.find((roadmapSlice) => roadmapSlice.id === sid)?.done) {
+            if (roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sid)) {
                 return false;
             }
         }
@@ -1289,6 +1292,7 @@ export async function postUnitPreVerification(pctx, opts) {
             const safetyConfig = resolveSafetyHarnessConfig(prefs?.safety_harness);
             if (safetyConfig.enabled) {
                 const { milestone: sMid, slice: sSid, task: sTid } = parseUnitId(s.currentUnit.id);
+                const fileChangeAllowlist = effectiveFileChangeAllowlist(safetyConfig.file_change_allowlist, prefs?.git?.manage_gitignore);
                 // File change validation (execute-task only, after unit execution)
                 if (safetyConfig.file_change_validation && s.currentUnit.type === "execute-task" && sMid && sSid && sTid) {
                     try {
@@ -1303,7 +1307,7 @@ export async function postUnitPreVerification(pctx, opts) {
                             const plannedFiles = getPlannedKeyFiles(sliceTaskRows.map((taskRow) => ({
                                 files: taskRow.files,
                             })));
-                            const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, safetyConfig.file_change_allowlist);
+                            const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, fileChangeAllowlist);
                             if (audit && audit.violations.length > 0) {
                                 const warnings = audit.violations.filter(v => v.severity === "warning");
                                 for (const v of warnings) {
@@ -1319,7 +1323,7 @@ export async function postUnitPreVerification(pctx, opts) {
                             if (taskRow) {
                                 const expectedOutput = taskRow.expected_output ?? [];
                                 const plannedFiles = taskRow.files ?? [];
-                                const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, safetyConfig.file_change_allowlist);
+                                const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, fileChangeAllowlist);
                                 if (audit && audit.violations.length > 0) {
                                     const warnings = audit.violations.filter(v => v.severity === "warning");
                                     for (const v of warnings) {
@@ -1699,7 +1703,27 @@ export async function postUnitPreVerification(pctx, opts) {
                 ctx.ui.notify(`Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — DB unavailable, skipping retry.${dbSkipDiag ? ` Expected: ${dbSkipDiag}` : ""}`, "error");
             }
             else if (!triggerArtifactVerified) {
-                if (s.lastToolInvocationError) {
+                if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
+                    // Tool-unavailable is transient: the workflow MCP server registers
+                    // its surface asynchronously, so a Unit's first call can race the
+                    // registration. Retry with escalating delay, bounded at 3 attempts.
+                    // ponytail: MAX constant so the guard, log, and display all agree
+                    const MAX_TOOL_UNAVAIL_RETRIES = 3;
+                    if (s.toolUnavailableRetries >= MAX_TOOL_UNAVAIL_RETRIES) {
+                        debugLog("postUnit", { phase: "tool-unavailable-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, retries: s.toolUnavailableRetries });
+                        ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type} after ${MAX_TOOL_UNAVAIL_RETRIES} retries: ${s.lastToolInvocationError}. MCP server may not be starting — pausing auto-mode.`, "error");
+                        s.lastToolInvocationError = null;
+                        await pauseAuto(ctx, pi);
+                        return "dispatched";
+                    }
+                    s.toolUnavailableRetries++;
+                    const delayMs = s.toolUnavailableRetries * 1000;
+                    debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError, attempt: s.toolUnavailableRetries, delayMs });
+                    ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Waiting ${delayMs}ms for MCP server — retry ${s.toolUnavailableRetries}/${MAX_TOOL_UNAVAIL_RETRIES}.`, "warning");
+                    s.lastToolInvocationError = null;
+                    await new Promise(r => setTimeout(r, delayMs));
+                }
+                else if (s.lastToolInvocationError) {
                     const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
                     const errMsg = isUserSkip
                         ? `Tool skipped for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Queued user message interrupted the turn — pausing auto-mode.`
@@ -1787,12 +1811,14 @@ export async function postUnitPreVerification(pctx, opts) {
                             }
                         }
                         s.exhaustedVerificationUnits.add(retryKey);
+                        saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                         debugLog("postUnit", { phase: "artifact-verify-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });
                         ctx.ui.notify(`${failureDetails} Pausing auto-mode after ${MAX_ARTIFACT_VERIFICATION_RETRIES} retries.`, "error");
                         await pauseAuto(ctx, pi);
                         return "dispatched";
                     }
                     s.verificationRetryCount.set(retryKey, attempt);
+                    saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                     s.pendingVerificationRetry = {
                         unitId: s.currentUnit.id,
                         failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
@@ -1810,8 +1836,11 @@ export async function postUnitPreVerification(pctx, opts) {
                 if (s.pendingVerificationRetry?.unitId === s.currentUnit.id) {
                     s.pendingVerificationRetry = null;
                 }
+                s.toolUnavailableRetries = 0;
                 s.verificationRetryCount.delete(retryKey);
                 s.verificationRetryFailureHashes.delete(retryKey);
+                s.exhaustedVerificationUnits.delete(retryKey);
+                saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                 if (s.currentUnit.type === "complete-milestone") {
                     const { milestone: mid } = parseUnitId(s.currentUnit.id);
                     if (mid) {

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -21,7 +21,7 @@ import { getPendingGatesForTurn } from "./gsd-db.js";
 import { assertGateCoverage, getGatesForTurn, } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, composeUnitContext, } from "./unit-context-composer.js";
+import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, composeToolSurfaceInstructions, composeUnitContext, } from "./unit-context-composer.js";
 import { resolveManifest } from "./unit-context-manifest.js";
 import { compileUnitContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
@@ -33,7 +33,7 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent } from "./uat-policy.js";
+import { classifyUatContentForRun, shouldDispatchUatForContent, } from "./uat-policy.js";
 import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
@@ -224,12 +224,14 @@ function renderContextModeBlockForPrompt(unitType, base, renderMode = "standalon
     return `${contextMode}\n\n## Context Snapshot\nSource: \`.gsd/last-snapshot.md\`\n\n${snapshot.trimEnd()}`;
 }
 function prependContextModeToBlock(unitType, base, block, renderMode = "standalone") {
+    const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
     const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-    if (!contextMode)
+    const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+    if (!guidance)
         return block;
     if (!block.trim())
-        return contextMode;
-    return `${contextMode}\n\n${block}`;
+        return guidance;
+    return `${guidance}\n\n${block}`;
 }
 function requireUnitPromptContextContract(unitType) {
     const result = compileUnitContextContract(unitType);
@@ -841,7 +843,7 @@ export async function inlineDecisionsFromDb(base, milestoneId, scope, level) {
 }
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(base, milestoneId, sliceId, level) {
     const inlineLevel = level ?? resolveInlineLevel();
@@ -849,14 +851,28 @@ export async function inlineRequirementsFromDb(base, milestoneId, sliceId, level
         const { isDbAvailable } = await import("./gsd-db.js");
         if (isDbAvailable()) {
             const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-            const requirements = queryRequirements({ milestoneId, sliceId });
+            let requirements = queryRequirements({ milestoneId, sliceId });
+            let broadenedScope = false;
+            if (requirements.length === 0 && sliceId) {
+                requirements = queryRequirements({ milestoneId });
+                broadenedScope = true;
+            }
+            if (requirements.length === 0 && milestoneId) {
+                requirements = queryRequirements({ status: "active" });
+                broadenedScope = true;
+            }
             if (requirements.length > 0) {
-                // Use compact format for non-full levels to save ~40% tokens
-                const formatted = inlineLevel !== "full"
+                // Use compact format for non-full levels, milestone-scoped calls, and
+                // any cascade stage that broadened past the originally requested scope —
+                // a slice-scoped "full" call that fell through to the project-wide
+                // active fallback must not format those rows as full requirements.
+                const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+                const formatted = useCompact
                     ? formatRequirementsCompact(requirements)
                     : formatRequirementsForPrompt(requirements);
                 return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
             }
+            return null;
         }
     }
     catch (err) {
@@ -1265,6 +1281,32 @@ export async function checkNeedsReassessment(base, mid, state) {
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(base, mid, sliceId, uatContent) {
+    let summaryContent = "";
+    try {
+        const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+        if (summaryPath) {
+            summaryContent = (await loadFile(summaryPath)) ?? "";
+        }
+    }
+    catch (err) {
+        logWarning("prompt", `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
 export async function checkNeedsRunUat(base, mid, state, prefs) {
     // DB primary path — fall through to file-based when DB has no data for this milestone
     try {
@@ -1297,7 +1339,8 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
                     }
                     if (!shouldDispatchUatForContent(uatContent, prefs))
                         continue;
-                    return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+                    const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+                    return { sliceId: sid, uatType };
                 }
                 return null;
             }
@@ -1338,7 +1381,8 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
         }
         if (!shouldDispatchUatForContent(uatContentFb, prefs))
             continue;
-        return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+        const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+        return { sliceId: uatSid, uatType };
     }
     return null;
 }
@@ -2146,6 +2190,9 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
             `Either (a) add an earlier task that creates X on disk before the task that needs it, ` +
             `or (b) if this task IS the one that creates X, move X from inputs to expected_output. ` +
             `Do NOT put X in a task's expected_output if that task only reads or verifies X — only tasks that actually write X to disk should list it in expected_output.\n` +
+            `- **"[file] X: ... GSD planning artifacts are projections preloaded as context / written by workflow tools"**: ` +
+            `Remove X from the task's inputs, files, and expectedOutput entirely. Planning artifacts (anything under .gsd/, .planning/, or .audits/, or names like M001-CONTEXT.md / S01-PLAN.md) are preloaded as context and written by workflow tools — ` +
+            `do NOT add a task that creates X and do NOT move X to expectedOutput.\n` +
             `- **"[file] X: Task T_early reads X but it's created by task T_late (sequence violation)"**: ` +
             `Either (a) reorder tasks so T_late (the creator) runs before T_early (the reader), ` +
             `or (b) if T_late doesn't actually create X (it only reads/tests it), remove X from T_late's expected_output entirely.\n` +
@@ -3094,10 +3141,25 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
     const rawInlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${composedBody}`;
     const cappedInlinedContext = capPreamble(rawInlinedContext);
     trackPromptContext(contextTelemetry, "cap", cappedInlinedContext.length < rawInlinedContext.length ? "skipped" : "inline", null, cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget");
-    const inlinedContext = prependContextModeToBlock("run-uat", base, cappedInlinedContext);
+    const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+    const uatType = uatPolicy.effectiveType;
+    const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+        ? [
+            "## Runtime harness override",
+            "",
+            "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+            "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+            "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+            "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+            "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+            "",
+        ].join("\n")
+        : "";
+    const inlinedContext = prependContextModeToBlock("run-uat", base, runtimeHarnessOverride
+        ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+        : cappedInlinedContext);
     emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
     const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-    const uatType = resolveEffectiveUatType(uatContent);
     const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
     return loadPrompt("run-uat", {
         workingDirectory: base,
@@ -3338,18 +3400,18 @@ opts) {
     }
     const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
     trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
-    const prompt = loadPrompt("reactive-execute", {
+    const prompt = prependContextModeToBlock("reactive-execute", base, loadPrompt("reactive-execute", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
+        graphContext,
         readyTaskCount: String(readyTaskIds.length),
         readyTaskList: readyTaskListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
         inlinedTemplates,
-    });
+    }));
     emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
     return prompt;
 }
@@ -3489,17 +3551,17 @@ export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base,
             "```",
         ].join("\n"));
     }
-    return loadPrompt("gate-evaluate", {
+    return prependContextModeToBlock("gate-evaluate", base, loadPrompt("gate-evaluate", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
+        slicePlanContent: planContent,
         gateCount: String(pending.length),
         gateList: gateListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    });
+    }));
 }
 export async function buildRewriteDocsPrompt(mid, midTitle, activeSlice, base, overrides) {
     const sid = activeSlice?.id;

package/dist/resources/extensions/gsd/auto-start.js

@@ -11,12 +11,14 @@
  * remains in auto.ts — this module handles only the fresh-start path.
  */
 import { deriveState } from "./state.js";
+import { findWorktreeSegment, isGsdWorktreePath } from "./worktree-root.js";
 import { loadFile, getManifestStatus } from "./files.js";
 import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode, } from "./preferences.js";
 import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-identity.js";
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
 import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
@@ -24,7 +26,8 @@ import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, nativeHasChanges, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
-import { getAutoWorktreePath, checkoutBranchWithStashGuard } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
+import { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
 import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { emitWorktreeOrphaned } from "./worktree-telemetry.js";
@@ -45,7 +48,6 @@ import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug
 import { logWarning, logError } from "./workflow-logger.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, } from "node:fs";
 import { join } from "node:path";
-import { sep as pathSep } from "node:path";
 import { validateDirectory } from "./validate-directory.js";
 import { isCustomProvider, resolveDefaultSessionModel, resolveDynamicRoutingConfig, } from "./preferences-models.js";
 import { getSessionModelOverride } from "./session-model-override.js";
@@ -403,7 +405,7 @@ export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps
                         }
                     }
                     else {
-                        warnings.push(`Orphaned worktree directory for ${milestoneId} is outside .gsd/worktrees/ — skipping removal for safety.`);
+                        warnings.push(`Orphaned worktree directory for ${milestoneId} is outside the GSD worktrees containers — skipping removal for safety.`);
                     }
                 }
                 else {
@@ -522,7 +524,7 @@ export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps
         if (!existsSync(wtDir))
             continue;
         if (!isInsideWorktreesDir(basePath, wtDir)) {
-            warnings.push(`Orphaned worktree directory for ${m.id} is outside .gsd/worktrees/ — skipping removal for safety.`);
+            warnings.push(`Orphaned worktree directory for ${m.id} is outside the GSD worktrees containers — skipping removal for safety.`);
             continue;
         }
         // Try `git worktree remove` first in case the dir is still registered
@@ -740,12 +742,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     // phase-specific planning model for a discuss turn (#2829).
     //
     // Precedence:
-    // 1) Explicit session override via /gsd model (this session)
-    // 2) Current session model from settings/session restore (if provider ready)
-    // 3) GSD model preferences from PREFERENCES.md (validated against live auth)
+    // 1) Explicit session override via /gsd model or /gsd auto --model (this session)
+    // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
+    // 3) Current session model from settings/session restore (if provider ready)
     //
-    // This preserves #3517 defaults while honoring explicit runtime model
-    // selection for subsequent /gsd runs in the same session.
+    // PREFERENCES.md wins over the ambient session default (#3517) so /gsd auto
+    // does not stick on claude-code/claude-sonnet-4-6 when the user configured
+    // models via /gsd workflow-preferences or PREFERENCES.md. Custom providers
+    // still skip PREFERENCES.md entirely (#4122).
     //
     // Exception (#4122): when the session provider is a custom provider declared
     // in ~/.gsd/agent/models.json (Ollama, vLLM, OpenAI-compatible proxy, etc.),
@@ -757,7 +761,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     const sessionProviderIsCustom = isCustomProvider(ctx.model?.provider);
     const preferredModel = sessionProviderIsCustom
         ? null
-        : resolveDefaultSessionModel(ctx.model?.provider);
+        : resolveDefaultSessionModel(ctx.model?.provider, base);
     // Validate the preferred model against the live registry + provider auth so
     // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
     // start-model snapshot. Without this, every subsequent unit would try to
@@ -780,8 +784,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         : null;
     const startThinkingSnapshot = pi.getThinkingLevel();
     const startModelSnapshot = manualSessionOverride
-        ?? currentSessionModel
         ?? validatedPreferredModel
+        ?? currentSessionModel
         ?? null;
     try {
         // Validate GSD_PROJECT_ID early so the user gets immediate feedback
@@ -972,9 +976,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(wtPath);
             }
         }
-        const blockingStrandedRecoveryAction = state.activeMilestone
-            ? strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction
-            : strandedRecoveryAction;
+        const requestedMilestoneLock = process.env.GSD_MILESTONE_LOCK?.trim() || null;
+        const lockedActiveMilestone = requestedMilestoneLock && state.activeMilestone?.id === requestedMilestoneLock;
+        let blockingStrandedRecoveryAction;
+        if (lockedActiveMilestone) {
+            // Parallel worker or explicit `/gsd auto Mxxx`: sibling milestones'
+            // stranded work must not block this milestone's resumption, and the
+            // downstream `strandedRecoveryAction` (used for currentMilestoneId,
+            // setActiveMilestoneId, and adoptStrandedMilestone) must be scoped to
+            // the locked milestone only. Falling back to the first sibling action
+            // would mis-target adoption (#742).
+            const lockMatch = strandedRecoveryActions.find((action) => action.milestoneId === requestedMilestoneLock) ?? null;
+            blockingStrandedRecoveryAction = lockMatch;
+            strandedRecoveryAction = lockMatch;
+        }
+        else if (state.activeMilestone) {
+            blockingStrandedRecoveryAction = strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction;
+        }
+        else {
+            blockingStrandedRecoveryAction = strandedRecoveryAction;
+        }
         if (blockingStrandedRecoveryAction) {
             if (!state.activeMilestone) {
                 ctx.ui.notify(formatStrandedWorkBlockerMessage(blockingStrandedRecoveryAction, null), "error");
@@ -987,6 +1008,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             strandedRecoveryAction = blockingStrandedRecoveryAction;
             ctx.ui.notify(formatStrandedWorkRecoveryMessage(strandedRecoveryAction), "info");
         }
+        else if (lockedActiveMilestone) {
+            strandedRecoveryAction = null;
+        }
         if (process.env.GSD_HEADLESS === "1" &&
             orphanAuditRecovered &&
             !state.activeMilestone &&
@@ -1010,7 +1034,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             (state.phase === "pre-planning" || state.phase === "complete") &&
             survivorIsolationMode !== "none" &&
             !detectWorktreeName(base) &&
-            !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
+            !isGsdWorktreePath(base)) {
             const milestoneBranch = `milestone/${survivorMilestoneId}`;
             const { nativeBranchExists } = await import("./native-git-bridge.js");
             hasSurvivorBranch = nativeBranchExists(base, milestoneBranch);
@@ -1246,16 +1270,13 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // (ADR-016 phase 2 / B2, #5620). The redundant assignment that used to
         // live here is gone.
         const isUnderGsdWorktrees = (p) => {
-            // Direct layout: /.gsd/worktrees/
-            const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-            if (p.includes(marker))
+            const normalized = p.replaceAll("\\", "/");
+            if (findWorktreeSegment(normalized) !== null)
                 return true;
-            const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
-            if (p.endsWith(worktreesSuffix))
-                return true;
-            // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-            const symlinkRe = new RegExp(`\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees(?:\\${pathSep}|$)`);
-            return symlinkRe.test(p);
+            // The container directory itself (no trailing worktree name), in any layout.
+            return normalized.endsWith("/.gsd/worktrees")
+                || normalized.endsWith("/.gsd-worktrees")
+                || /\/\.gsd\/projects\/[^/]+\/worktrees$/.test(normalized);
         };
         if (s.currentMilestoneId &&
             (getIsolationMode(base) !== "none" || strandedRecoveryAction?.recoveryMode) &&
@@ -1272,11 +1293,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 if (enterResult.reason === "lease-conflict") {
                     ctx.ui.notify(`Cannot enter milestone ${s.currentMilestoneId}: lease is held by another worker.`, "error");
                 }
-                else if (enterResult.reason === "creation-failed") {
-                    ctx.ui.notify(`Cannot enter milestone ${s.currentMilestoneId}: worktree/branch creation failed. Isolation is degraded.`, "error");
-                }
-                else if (enterResult.reason === "isolation-degraded") {
-                    ctx.ui.notify(`Cannot enter milestone ${s.currentMilestoneId}: isolation is degraded from a prior worktree failure. Close processes locking the worktree and retry, or run /gsd doctor fix.`, "error");
+                else if (enterResult.reason === "creation-failed" || enterResult.reason === "isolation-degraded") {
+                    ctx.ui.notify(milestoneEntryBlockedGuidance(s.currentMilestoneId, enterResult.reason), "error");
                 }
                 else if (enterResult.reason === "invalid-milestone-id") {
                     ctx.ui.notify(`Cannot enter milestone ${s.currentMilestoneId}: milestone id is invalid.`, "error");

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -4,6 +4,7 @@
  * can distinguish "waiting for tool completion" from "truly idle".
  */
 import { stripMcpToolPrefix } from "@gsd/pi-ai";
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 const inFlightTools = new Map();
 /**
  * Tools that block waiting for human input by design.
@@ -117,6 +118,14 @@ export function clearInFlightTools() {
  */
 const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Input validation error|Invalid arguments for tool|MCP error -32602|No such tool available|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON|does not provide an export named|Named export .* not found|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_MODULE_NOT_EXPORTED|ERR_PACKAGE_PATH_NOT_EXPORTED/i;
 const DETERMINISTIC_POLICY_ERROR_RE = /(?:^|\b)(?:HARD BLOCK:|Blocked: \/gsd queue is a planning tool|Direct writes to \.gsd\/STATE\.md and \.gsd\/gsd\.db are blocked|This is a mechanical gate)/i;
+/**
+ * Matches the runtime's "tool not registered" error. Unlike the deterministic
+ * invocation failures above, this one is usually transient: the workflow MCP
+ * server registers its tool surface asynchronously after session start, so a
+ * Unit's first tool call can race the registration. Callers should retry
+ * (bounded) instead of breaking the loop.
+ */
+const TOOL_UNAVAILABLE_ERROR_RE = new RegExp(`No such tool available|${TOOL_SURFACE_NOT_READY}`, "i");
 /**
  * Returns true if the error message indicates a deterministic invocation or
  * policy failure (as opposed to a normal tool execution error).
@@ -126,6 +135,15 @@ export function isToolInvocationError(errorMsg) {
         return false;
     return TOOL_INVOCATION_ERROR_RE.test(errorMsg) || isDeterministicPolicyError(errorMsg);
 }
+/**
+ * Returns true if the error message indicates the called tool was not on the
+ * session's tool surface (MCP startup race — see TOOL_UNAVAILABLE_ERROR_RE).
+ */
+export function isToolUnavailableError(errorMsg) {
+    if (!errorMsg)
+        return false;
+    return TOOL_UNAVAILABLE_ERROR_RE.test(errorMsg);
+}
 /**
  * Returns true if the error message indicates the tool was skipped because
  * a queued user message interrupted the turn (#3595).  Retrying will produce