@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

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

@@ -21,8 +21,9 @@ 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, composeInlinedContext, composeUnitContext } from "./unit-context-composer.js";
+import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, 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";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
@@ -33,6 +34,7 @@ import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-acti
 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 { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
@@ -229,6 +231,29 @@ function prependContextModeToBlock(unitType, base, block, renderMode = "standalo
         return contextMode;
     return `${contextMode}\n\n${block}`;
 }
+function requireUnitPromptContextContract(unitType) {
+    const result = compileUnitContextContract(unitType);
+    if (result.ok)
+        return result.contract;
+    throw new Error(result.detail);
+}
+function requireComposedArtifactBlock(blocks, unitType, key) {
+    const block = blocks.find((item) => item.key === key);
+    if (!block) {
+        throw new Error(`Unit Context Contract for ${unitType} did not compose required artifact ${key}`);
+    }
+    return block.body;
+}
+function renderExecuteTaskOnDemandContext(base, mid, sid, artifacts) {
+    if (!artifacts.includes("slice-research"))
+        return "";
+    const researchPath = relSliceFile(base, mid, sid, "RESEARCH");
+    return [
+        "## On-demand Context",
+        "",
+        `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
+    ].join("\n");
+}
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 /**
  * Format executor context constraints for injection into the plan-slice prompt.
@@ -1745,6 +1770,13 @@ export async function buildPlanMilestonePrompt(mid, midTitle, base, level) {
     else {
         trackPromptContext(contextTelemetry, "knowledge", "skipped", null, "missing");
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance) {
+        pushTracked("web-app-uat", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+    }
     pushTracked("templates", inlineTemplate("roadmap", "Roadmap"));
     if (inlineLevel === "full") {
         pushTracked("templates", inlineTemplate("decisions", "Decisions"));
@@ -2032,6 +2064,14 @@ async function renderSlicePrompt(options) {
     else {
         trackPromptContext(contextTelemetry, "graph-subgraph", "skipped", null, "missing");
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance) {
+        inlined.push(webAppUatGuidance);
+        trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+    }
     const planTemplateInline = level === "minimal" ? inlineCompactTemplate("plan", "Slice Plan") : inlineTemplate("plan", "Slice Plan");
     inlined.push(planTemplateInline);
     trackPromptContext(contextTelemetry, "templates", "inline", planTemplateInline);
@@ -2106,6 +2146,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` +
@@ -2173,7 +2216,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
     const taskPlanRelPath = relSlicePath(base, mid, sid) + `/tasks/${tid}-PLAN.md`;
-    const taskPlanInline = taskPlanContent
+    const taskPlanContext = taskPlanContent
         ? [
             "## Inlined Task Plan (authoritative local execution contract)",
             `Source: \`${taskPlanRelPath}\``,
@@ -2184,11 +2227,11 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
             "## Inlined Task Plan (authoritative local execution contract)",
             `Task plan not found at dispatch time. Read \`${taskPlanRelPath}\` before executing.`,
         ].join("\n");
-    trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanInline, taskPlanContent ? undefined : "missing at dispatch");
+    trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanContext, taskPlanContent ? undefined : "missing at dispatch");
     const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN");
     const slicePlanContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
-    const slicePlanExcerpt = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
-    trackPromptContext(contextTelemetry, "slice-plan", slicePlanExcerpt ? "excerpt" : "skipped", slicePlanExcerpt, slicePlanExcerpt ? undefined : "missing");
+    const slicePlanContext = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
+    trackPromptContext(contextTelemetry, "slice-plan", slicePlanContext ? "excerpt" : "skipped", slicePlanContext, slicePlanContext ? undefined : "missing");
     // Check for continue file (new naming or legacy)
     const continueFile = resolveSliceFile(base, mid, sid, "CONTINUE");
     const legacyContinueDir = resolveSlicePath(base, mid, sid);
@@ -2287,6 +2330,30 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
         trackPromptContext(contextTelemetry, "decisions-template", "on-demand", decisionsOnDemandET);
     }
     trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates, inlineLevel);
+    const contextContract = requireUnitPromptContextContract("execute-task");
+    const contractedContext = await composeContractedUnitContext(contextContract, {
+        base: { unitType: "execute-task", basePath: base, milestoneId: mid, sliceId: sid, taskId: tid },
+        resolveArtifact: async (key) => {
+            switch (key) {
+                case "task-plan":
+                    return taskPlanContext;
+                case "slice-plan":
+                    return slicePlanContext;
+                case "prior-task-summaries":
+                    return finalCarryForward;
+                case "templates":
+                    return inlinedTemplates;
+                default:
+                    return null;
+            }
+        },
+    });
+    const taskPlanInline = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "task-plan");
+    const slicePlanExcerpt = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "slice-plan");
+    const contractedCarryForward = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "prior-task-summaries");
+    const contractedTemplates = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "templates");
+    const onDemandContext = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+    trackPromptContext(contextTelemetry, "slice-research", onDemandContext ? "on-demand" : "skipped", onDemandContext, onDemandContext ? undefined : "not declared by contract");
     const prompt = loadPrompt("execute-task", {
         overridesSection,
         runtimeContext,
@@ -2298,11 +2365,12 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
         taskPlanPath: taskPlanRelPath,
         taskPlanInline,
         slicePlanExcerpt,
-        carryForwardSection: finalCarryForward,
+        carryForwardSection: contractedCarryForward,
         resumeSection,
         priorTaskLines: priorLines,
+        onDemandContext,
         taskSummaryPath,
-        inlinedTemplates,
+        inlinedTemplates: contractedTemplates,
         verificationBudget,
         gatesToClose,
         skillActivation: buildSkillActivationBlock({
@@ -2313,7 +2381,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
             taskId: tid,
             taskTitle: tTitle,
             taskPlanContent,
-            extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+            extraContext: [taskPlanInline, slicePlanExcerpt, contractedCarryForward, resumeSection],
             unitType: "execute-task",
         }),
     });
@@ -2424,6 +2492,14 @@ export async function buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, base,
             body = `${body}\n\n---\n\n${knowledgeInlineCS}`;
         }
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance && body) {
+        body = `${webAppUatGuidance}\n\n---\n\n${body}`;
+        trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, webAppUatGuidance ? "missing composed body" : "not a web app");
+    }
     // Overrides section prepends to the top of the inlined context —
     // standard pattern for slice-level builders (until composer v2 lands
     // the prepend contract).

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

@@ -14,7 +14,8 @@ import { appendEvent } from "./workflow-events.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGatesForTurn, updateTaskStatus, updateSliceStatus, insertSlice, getMilestone, getMilestoneSlices, getLatestAssessmentByScope, updateMilestoneStatus, refreshOpenDatabaseFromDisk, transaction, } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGatesForTurn, updateTaskStatus, updateSliceStatus, insertSlice, getMilestone, updateMilestoneStatus, transaction, } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -32,7 +33,7 @@ import { isGsdWorktreePath } from "./worktree-root.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { loadAllCaptures, loadPendingCaptures } from "./captures.js";
-import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
+import { proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
 export { classifyMilestoneSummaryContent, } from "./milestone-summary-classifier.js";
@@ -66,12 +67,24 @@ function resolveArtifactVerificationBase(unitId, base) {
         return base;
     return resolveCanonicalMilestoneRoot(base, milestone);
 }
+function closeoutProofRecoveryReason(reason) {
+    switch (reason) {
+        case "slice-missing":
+            return "complete-milestone-slices-missing";
+        case "summary-artifact-missing":
+            return "complete-milestone-summary-missing";
+        case "summary-artifact-failed":
+            return "complete-milestone-summary-failed";
+        default:
+            return `complete-milestone-${reason}`;
+    }
+}
 export function refreshRecoveryDbForArtifact(unitType, unitId, basePath) {
     if (unitType !== "plan-slice" && unitType !== "execute-task" && unitType !== "complete-milestone")
         return { ok: true };
     if (!isDbAvailable())
         return { ok: true };
-    if (!refreshOpenDatabaseFromDisk()) {
+    if (!refreshWorkflowDatabaseFromDisk()) {
         return {
             ok: false,
             fatal: unitType === "execute-task" || unitType === "complete-milestone",
@@ -100,50 +113,29 @@ export function refreshRecoveryDbForArtifact(unitType, unitId, basePath) {
         }
         if (isClosedStatus(milestone.status))
             return { ok: true };
-        const validation = getLatestAssessmentByScope(mid, "milestone-validation");
-        if (validation?.status !== "pass") {
-            return {
-                ok: false,
-                fatal: true,
-                reason: "complete-milestone-validation-not-pass",
-                message: `Stuck recovery found complete-milestone ${unitId} artifacts, but milestone-validation is "${validation?.status ?? "absent"}" in the DB.`,
-            };
-        }
-        const slices = getMilestoneSlices(mid);
-        if (slices.length === 0) {
-            return {
-                ok: false,
-                fatal: true,
-                reason: "complete-milestone-slices-missing",
-                message: `Stuck recovery found complete-milestone ${unitId} artifacts, but no slices exist in the DB.`,
-            };
-        }
-        const openSlice = slices.find((slice) => !isClosedStatus(slice.status));
-        if (openSlice) {
-            return {
-                ok: false,
-                fatal: true,
-                reason: "complete-milestone-slice-open",
-                message: `Stuck recovery found complete-milestone ${unitId} artifacts, but slice ${openSlice.id} is still "${openSlice.status}" in the DB.`,
-            };
-        }
-        for (const slice of slices) {
-            const openTask = getSliceTasks(mid, slice.id).find((task) => !isClosedStatus(task.status));
-            if (openTask) {
+        const artifactBasePath = resolveArtifactVerificationBase(unitId, basePath);
+        const closeoutProof = proveMilestoneCloseout(mid, {
+            allowOpenMilestone: true,
+            summaryArtifactBasePath: artifactBasePath,
+            implementationEvidence: {
+                basePath,
+                requirement: "present",
+            },
+        });
+        if (!closeoutProof.ok) {
+            if (closeoutProof.reason === "implementation-evidence-missing") {
                 return {
                     ok: false,
                     fatal: true,
-                    reason: "complete-milestone-task-open",
-                    message: `Stuck recovery found complete-milestone ${unitId} artifacts, but task ${slice.id}/${openTask.id} is still "${openTask.status}" in the DB.`,
+                    reason: "complete-milestone-implementation-missing",
+                    message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
                 };
             }
-        }
-        if (hasImplementationArtifacts(basePath, mid) !== "present") {
             return {
                 ok: false,
                 fatal: true,
-                reason: "complete-milestone-implementation-missing",
-                message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
+                reason: closeoutProofRecoveryReason(closeoutProof.reason),
+                message: `Stuck recovery found complete-milestone ${unitId} artifacts, but ${closeoutProof.message}`,
             };
         }
         updateMilestoneStatus(mid, "complete", new Date().toISOString());
@@ -457,7 +449,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
             try {
                 let taskIds = null;
                 if (isDbAvailable()) {
-                    const refreshed = refreshOpenDatabaseFromDisk();
+                    const refreshed = refreshWorkflowDatabaseFromDisk();
                     if (refreshed) {
                         const tasks = getSliceTasks(mid, sid);
                         if (tasks.length > 0)
@@ -569,17 +561,24 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
     // A milestone with only .gsd/ plan files and zero implementation code is
     // not genuinely complete — the LLM wrote plan files but skipped actual work.
     if (unitType === "complete-milestone") {
-        const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
-        if (summaryOutcome === "failure")
-            return false;
         const { milestone: mid } = parseUnitId(unitId);
-        if (mid && isDbAvailable()) {
-            const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-            if (!closeoutGate.ok)
-                return false;
-        }
-        if (hasImplementationArtifacts(base, mid) === "absent")
+        if (!mid)
             return false;
+        const closeoutProof = proveMilestoneCloseout(mid, {
+            refreshFromDisk: true,
+            summaryArtifactBasePath: artifactBase,
+            implementationEvidence: {
+                basePath: base,
+                requirement: "not-absent",
+            },
+        });
+        if (!closeoutProof.ok) {
+            if (!isDbAvailable() && closeoutProof.reason === "db-unavailable") {
+                const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
+                return summaryOutcome !== "failure" && hasImplementationArtifacts(base, mid) !== "absent";
+            }
+            return false;
+        }
     }
     return true;
 }

package/dist/resources/extensions/gsd/auto-runtime-state.js

@@ -1,7 +1,13 @@
 // GSD auto-mode runtime state
 import { AutoSession } from "./auto/session.js";
 import { isDeterministicPolicyError, isQueuedUserMessageSkip, isToolInvocationError, markToolEnd as markTrackedToolEnd, markToolStart as markTrackedToolStart, } from "./auto-tool-tracking.js";
+// Re-exported as a pure pass-through. Must stay UNGATED (no autoSession.active
+// argument, unlike markToolStart at the bottom of this file) so it is true in
+// foreground where the foreground approval-gate pause consults it.
+export { isInteractiveElicitationInFlight } from "./auto-tool-tracking.js";
+import { createToolSurfaceSnapshot, } from "./tool-surface-snapshot.js";
 export const autoSession = new AutoSession();
+let currentToolSurfaceSnapshot = null;
 export function getAutoRuntimeSnapshot() {
     const orchestrationStatus = autoSession.orchestration?.getStatus();
     return {
@@ -12,8 +18,16 @@ export function getAutoRuntimeSnapshot() {
         orchestrationPhase: orchestrationStatus?.phase,
         orchestrationTransitionCount: orchestrationStatus?.transitionCount,
         orchestrationLastTransitionAt: orchestrationStatus?.lastTransitionAt,
+        toolSurface: autoSession.active || autoSession.paused ? currentToolSurfaceSnapshot : null,
     };
 }
+export function recordAutoToolSurfaceSnapshot(input) {
+    currentToolSurfaceSnapshot = createToolSurfaceSnapshot(input);
+    return currentToolSurfaceSnapshot;
+}
+export function clearAutoToolSurfaceSnapshot() {
+    currentToolSurfaceSnapshot = null;
+}
 export function isAutoActive() {
     return autoSession.active;
 }

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

@@ -11,6 +11,7 @@
  * 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";
@@ -24,7 +25,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";
@@ -34,7 +36,8 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, getAllMilestones, insertMilestone, openDatabase, getDbStatus, updateMilestoneStatus } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getAllMilestones, insertMilestone, updateMilestoneStatus } from "./gsd-db.js";
+import { getWorkflowDatabaseStatus, openExistingWorkflowDatabase, openWorkflowDatabase, resolveProjectRootDbPath, } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { extractVerdict } from "./verdict-parser.js";
@@ -44,8 +47,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 { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
 import { validateDirectory } from "./validate-directory.js";
 import { isCustomProvider, resolveDefaultSessionModel, resolveDynamicRoutingConfig, } from "./preferences-models.js";
 import { getSessionModelOverride } from "./session-model-override.js";
@@ -76,11 +77,9 @@ export async function openProjectDbIfPresent(basePath) {
     const gsdDbPath = resolveProjectRootDbPath(basePath);
     if (!existsSync(gsdDbPath) || isDbAvailable())
         return;
-    try {
-        openDatabase(gsdDbPath);
-    }
-    catch (err) {
-        logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`);
+    const result = openExistingWorkflowDatabase(basePath);
+    if (!result.ok && result.reason === "open-failed") {
+        logWarning("engine", `gsd-db: failed to open existing database: ${result.error?.message ?? "open failed"}`);
     }
 }
 export function reconcileProjectMilestonesFromDisk(basePath) {
@@ -405,7 +404,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 {
@@ -524,7 +523,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
@@ -1012,7 +1011,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);
@@ -1248,16 +1247,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) &&
@@ -1295,23 +1291,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         }
         // ── DB lifecycle ──
         const gsdDbPath = resolveProjectRootDbPath(s.basePath);
-        const gsdDirPath = join(s.basePath, ".gsd");
-        if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
-            try {
-                const { openDatabase: openDb } = await import("./gsd-db.js");
-                openDb(gsdDbPath);
-            }
-            catch (err) {
-                logError("engine", `failed to initialize project database: ${err.message}`);
-            }
+        const initialDbOpen = openWorkflowDatabase(s.basePath);
+        if (!initialDbOpen.ok && initialDbOpen.reason === "open-failed") {
+            logError("engine", `failed to initialize project database: ${initialDbOpen.error?.message ?? "open failed"}`);
         }
         if (_shouldAbortBootstrapForUnavailableDbForTest(gsdDbPath, isDbAvailable())) {
-            try {
-                const { openDatabase: openDb } = await import("./gsd-db.js");
-                openDb(gsdDbPath);
-            }
-            catch (err) {
-                logError("engine", `failed to open existing database: ${err.message}`);
+            const retryDbOpen = openWorkflowDatabase(s.basePath);
+            if (!retryDbOpen.ok && retryDbOpen.reason === "open-failed") {
+                logError("engine", `failed to open existing database: ${retryDbOpen.error?.message ?? "open failed"}`);
             }
         }
         // Gate: abort bootstrap if the DB file exists but the provider is
@@ -1320,7 +1307,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // call returns "db_unavailable", triggering artifact-retry which
         // re-dispatches the same task — producing an infinite loop (#2419).
         if (existsSync(gsdDbPath) && !isDbAvailable()) {
-            const dbStatus = getDbStatus();
+            const dbStatus = getWorkflowDatabaseStatus();
             const phaseHint = dbStatus.lastPhase === "open"
                 ? "The database file could not be opened"
                 : dbStatus.lastPhase === "initSchema"

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

@@ -233,11 +233,24 @@ export function startUnitSupervision(sctx) {
         }
     }, 15000);
     // ── 3. Hard timeout ──
-    s.unitTimeoutHandle = setTimeout(async () => {
+    const hardTimeoutBody = async () => {
         try {
             s.unitTimeoutHandle = null;
             if (!s.active)
                 return;
+            // User-interactive tools (ask_user_questions, secure_env_collect) block
+            // waiting for human input by design. Unlike the idle watchdog (above),
+            // the hard timeout had no interactive exemption, so a long human
+            // deliberation crossing the hard cap would still closeout + recover
+            // (triggerTurn) and abort the turn hosting the elicitation, reintroducing
+            // the self-cancel loop on slow answers (#2676). Re-arm instead of firing
+            // while a human is being asked, mirroring the idle watchdog's
+            // refresh-and-return. Conditional on hasInteractiveToolInFlight(), so a
+            // genuinely hung non-interactive unit still hits the hard cap.
+            if (getInFlightToolCount() > 0 && hasInteractiveToolInFlight()) {
+                s.unitTimeoutHandle = setTimeout(hardTimeoutBody, hardTimeoutMs);
+                return;
+            }
             const expectedCurrentUnit = s.currentUnit
                 ? { type: s.currentUnit.type, id: s.currentUnit.id, startedAt: s.currentUnit.startedAt }
                 : null;
@@ -269,7 +282,8 @@ export function startUnitSupervision(sctx) {
                 logWarning("timer", `notification failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-    }, hardTimeoutMs);
+    };
+    s.unitTimeoutHandle = setTimeout(hardTimeoutBody, hardTimeoutMs);
     // ── 4. Context-pressure continue-here monitor ──
     if (s.continueHereHandle) {
         clearInterval(s.continueHereHandle);

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

@@ -4,12 +4,23 @@
  * 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.
  * The idle watchdog must not treat these as stalled.
  */
 const INTERACTIVE_TOOLS = new Set(["ask_user_questions", "secure_env_collect"]);
+/**
+ * Mode-agnostic refcount of in-flight interactive elicitations that are an
+ * active human boundary (the model ASKED via ask_user_questions). Unlike the
+ * `inFlightTools` Map, this is NOT gated by auto-session.active, so it is true
+ * in FOREGROUND (where s.active is false). Kept SEPARATE from inFlightTools so
+ * getInFlightToolCount()/getOldestInFlightToolAgeMs()/hasInteractiveToolInFlight()
+ * and the auto-watchdog accounting are byte-for-byte unchanged. A refcount (not
+ * a boolean) handles nested/back-to-back elicitations in a single turn.
+ */
+let interactiveElicitationDepth = 0;
 /**
  * Mark a tool execution as in-flight.
  * Records start time and tool name so the idle watchdog can detect tools
@@ -26,6 +37,27 @@ export function markToolStart(toolCallId, isActive, toolName) {
 export function markToolEnd(toolCallId) {
     inFlightTools.delete(toolCallId);
 }
+/**
+ * Mark an interactive elicitation (the model asking via ask_user_questions) as
+ * in flight. Ungated by auto-session.active so it is observable in foreground.
+ */
+export function markInteractiveElicitationStart() {
+    interactiveElicitationDepth++;
+}
+/**
+ * Mark an interactive elicitation as completed. Idempotent below zero.
+ */
+export function markInteractiveElicitationEnd() {
+    if (interactiveElicitationDepth > 0)
+        interactiveElicitationDepth--;
+}
+/**
+ * Returns true if any interactive elicitation is currently the active human
+ * boundary. True in ALL modes (foreground and auto) while one is in flight.
+ */
+export function isInteractiveElicitationInFlight() {
+    return interactiveElicitationDepth > 0;
+}
 /**
  * Returns the age (ms) of the oldest currently in-flight tool, or 0 if none.
  */
@@ -75,6 +107,7 @@ export function hasInteractiveToolInFlight() {
  */
 export function clearInFlightTools() {
     inFlightTools.clear();
+    interactiveElicitationDepth = 0;
 }
 // ─── Tool invocation error classification (#2883) ────────────────────────
 /**
@@ -85,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).
@@ -94,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