gsd-pi 2.78.1-dev.82bcf6b71 → 2.78.1-dev.84c045fd2

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

@@ -38,10 +38,9 @@ import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
 import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { preflightCleanRoot, postflightPopStash } from "./clean-root-preflight.js";
-import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
@@ -57,11 +56,13 @@ import { getErrorMessage } from "./error-utils.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
+import { isClosedStatus } from "./status-guards.js";
 import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS } from "../shared/cmux-events.js";
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 function makeCmuxEmitters(pi) {
     return {
         syncCmuxSidebar: (preferences, state) => pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences, state }),
@@ -75,13 +76,16 @@ import { runPostUnitVerification } from "./auto-verification.js";
 import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop } from "./auto/loop.js";
+import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto/resolve.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
+import { validateDirectory } from "./validate-directory.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
 import { autoSession as s } from "./auto-runtime-state.js";
+import { gsdHome } from "./gsd-home.js";
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
 // This file must NOT declare module-level `let` or `var` variables for state.
@@ -178,11 +182,7 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
 }
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath) {
-    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-    if (prefs?.isolation === "worktree")
-        return true;
-    // Default is false — worktree isolation requires explicit opt-in
-    return false;
+    return getIsolationMode(basePath) === "worktree";
 }
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
 /** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
@@ -875,8 +875,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
             milestoneLock: s.sessionMilestoneLock ?? undefined,
         };
         const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-        mkdirSync(runtimeDir, { recursive: true });
-        writeFileSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
+        atomicWriteSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
     }
     catch (err) {
         // Non-fatal — resume will still work via full bootstrap, just without worktree context
@@ -893,6 +892,19 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
         }
         s.currentUnit = null;
     }
+    // Keep STATE.md aligned with the DB-backed state before releasing pause state.
+    // Without this, an interrupted deep run can leave STATE.md saying "no active
+    // milestone" even after the DB/disk reconciliation has recovered the next unit.
+    if (s.basePath) {
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("pause-rebuild-state-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
     if (lockBase()) {
         releaseSessionLock(lockBase());
         clearLock(lockBase());
@@ -1092,6 +1104,11 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     // Escape stale worktree cwd from a previous milestone (#608).
     base = escapeStaleWorktree(base);
+    const dirCheck = validateDirectory(base);
+    if (dirCheck.severity === "blocked") {
+        ctx.ui.notify(dirCheck.reason, "error");
+        return;
+    }
     // Heal .gsd.migrating before any branching — covers both fresh-start and
     // resume paths (#4416). The matching call in auto-start.ts covers the
     // bootstrap-only path; this call ensures the resume path is also protected.
@@ -1139,15 +1156,31 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         || !!freshStartAssessment.lock);
                 if (shouldResumePausedSession) {
                     // Validate the milestone still exists and isn't already complete (#1664).
+                    // DB status is authoritative when available; SUMMARY.md is a legacy
+                    // fallback only for unmigrated/offline projects.
                     const mDir = resolveMilestonePath(base, meta.milestoneId);
-                    const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
                     let summaryIsTerminal = false;
-                    if (summaryFile) {
-                        try {
-                            summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                    let dbAvailable = isDbAvailable();
+                    let milestoneRow = dbAvailable ? getMilestone(meta.milestoneId) : null;
+                    if (!milestoneRow) {
+                        const opened = await ensureDbOpen(base);
+                        dbAvailable = opened || isDbAvailable();
+                        if (dbAvailable) {
+                            milestoneRow = getMilestone(meta.milestoneId);
                         }
-                        catch {
-                            summaryIsTerminal = false;
+                    }
+                    if (dbAvailable) {
+                        summaryIsTerminal = !!milestoneRow && isClosedStatus(milestoneRow.status);
+                    }
+                    else {
+                        const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
+                        if (summaryFile) {
+                            try {
+                                summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                            }
+                            catch {
+                                summaryIsTerminal = false;
+                            }
                         }
                     }
                     if (!mDir || summaryIsTerminal) {
@@ -1295,7 +1328,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
         // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
         // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent");
+        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
         const pkgRoot = process.env.GSD_PKG_ROOT;
         const resourceLoaderPath = pkgRoot
             ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,11 +1,12 @@
 import { logWarning } from "../workflow-logger.js";
-import { checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
+import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
-import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
+import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto/resolve.js";
 import { resolveModelId } from "../auto-model-selection.js";
+import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
@@ -30,6 +31,14 @@ export const MAX_TRANSIENT_AUTO_RESUMES = 8;
 export function resetTransientRetryState() {
     resetRetryState(retryState);
 }
+function resolveAgentEndBasePath() {
+    try {
+        return resolveProjectRoot(process.cwd());
+    }
+    catch {
+        return undefined;
+    }
+}
 async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -67,6 +76,15 @@ export async function handleAgentEnd(pi, event, ctx) {
     // falsely report files as missing — producing a spurious "ready signal
     // rejected" loop even though the files are on disk.
     clearPathCache();
+    try {
+        if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+            return;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
+    }
     if (checkAutoStartAfterDiscuss()) {
         clearDiscussionFlowState();
         return;

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

@@ -2,6 +2,7 @@ import { Type } from "@sinclair/typebox";
 import { Text } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 async function loadWorkflowExecutors() {
@@ -20,6 +21,16 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+function requirementRootWriteGuard(operation) {
+    const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+    if (!guard.block)
+        return null;
+    return {
+        content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
+        details: { operation, error: "root_artifact_write_blocked" },
+        isError: true,
+    };
+}
 /**
  * Read a tool result's structured payload, accommodating MCP's `details` →
  * `structuredContent` rename (#4472, #4477). In-process executions still
@@ -119,6 +130,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
     // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
     const requirementUpdateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("update_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -201,6 +215,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
     // ─── gsd_requirement_save ─────────────────────────────────────────────
     const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("save_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -242,13 +259,28 @@ export function registerDbTools(pi) {
             "Requirement IDs are auto-assigned — never provide an ID manually.",
         promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
         promptGuidelines: [
-            "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+            "Use gsd_requirement_save when recording a new capability, quality attribute, constraint, or anti-feature requirement.",
+            "Use one of these classes: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, anti-feature.",
             "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
             "class, description, why, and source are required. All other fields are optional.",
             "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
         ],
         parameters: Type.Object({
-            class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+            class: StringEnum([
+                "core-capability",
+                "primary-user-loop",
+                "launchability",
+                "continuity",
+                "failure-visibility",
+                "integration",
+                "quality-attribute",
+                "operability",
+                "admin/support",
+                "compliance/security",
+                "differentiator",
+                "constraint",
+                "anti-feature",
+            ], { description: "Requirement class" }),
             description: Type.String({ description: "Short description of the requirement" }),
             why: Type.String({ description: "Why this requirement matters" }),
             source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
@@ -291,17 +323,18 @@ export function registerDbTools(pi) {
             "Computes the file path from milestone/slice/task IDs automatically.",
         promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
         promptGuidelines: [
-            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).",
-            "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT).",
+            "milestone_id is required for milestone/slice/task artifacts. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT.",
             "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.",
+            "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
+            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
             "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
         ],
         parameters: Type.Object({
-            milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
             slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
             task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-            artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }),
+            artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
             content: Type.String({ description: "The full markdown content of the artifact" }),
         }),
         execute: summarySaveExecute,

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { setLogBasePath, logWarning } from "../workflow-logger.js";
+import { resolveGsdPathContract } from "../paths.js";
 /**
  * Resolve the correct DB path for the current working directory.
  * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
@@ -10,67 +11,15 @@ import { setLogBasePath, logWarning } from "../workflow-logger.js";
  * returns `<basePath>/.gsd/gsd.db`.
  */
 export function resolveProjectRootDbPath(basePath) {
-    // Detect worktree: look for `.gsd/worktrees/` in the path segments.
-    // A worktree path looks like: /project/root/.gsd/worktrees/M001/...
-    // We need to resolve back to /project/root/.gsd/gsd.db
-    const marker = `${sep}.gsd${sep}worktrees${sep}`;
-    const idx = basePath.indexOf(marker);
-    if (idx !== -1) {
-        const projectRoot = basePath.slice(0, idx);
-        return join(projectRoot, ".gsd", "gsd.db");
-    }
-    // Also handle forward-slash paths on all platforms
-    const fwdMarker = "/.gsd/worktrees/";
-    const fwdIdx = basePath.indexOf(fwdMarker);
-    if (fwdIdx !== -1) {
-        const projectRoot = basePath.slice(0, fwdIdx);
-        return join(projectRoot, ".gsd", "gsd.db");
-    }
-    // External-state layout: ~/.gsd/projects/<hash>/worktrees/<MID>/...
-    // Resolve to ~/.gsd/projects/<hash>/gsd.db (the canonical project DB) (#2952).
-    // Must be checked before the generic symlink-resolved handler: both match
-    // /.gsd/projects/<hash>/worktrees/ but require different resolution targets.
-    const extRe = /[/\\]\.gsd[/\\]projects[/\\][a-f0-9]+[/\\]worktrees(?:[/\\]|$)/;
-    const extMatch = extRe.exec(basePath);
-    if (extMatch) {
-        const matchStr = extMatch[0];
-        // Find the "/worktrees" portion within the match and slice up to it
-        const wtIdx = matchStr.search(/[/\\]worktrees(?:[/\\]|$)/);
-        const projectStateRoot = basePath.slice(0, extMatch.index + wtIdx);
-        return join(projectStateRoot, "gsd.db");
-    }
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/M001/...
-    // The project root is everything before /.gsd/projects/ (#2517)
-    const symlinkMarker = `${sep}.gsd${sep}projects${sep}`;
-    const symlinkIdx = basePath.indexOf(symlinkMarker);
-    if (symlinkIdx !== -1) {
-        const afterProjects = basePath.slice(symlinkIdx + symlinkMarker.length);
-        // Expect: <hash>/worktrees/...
-        const worktreeSeg = `${sep}worktrees${sep}`;
-        if (afterProjects.includes(worktreeSeg)) {
-            const projectRoot = basePath.slice(0, symlinkIdx);
-            return join(projectRoot, ".gsd", "gsd.db");
-        }
-    }
-    // Forward-slash variant for symlink-resolved layout
-    const fwdSymlinkMarker = "/.gsd/projects/";
-    const fwdSymlinkIdx = basePath.indexOf(fwdSymlinkMarker);
-    if (fwdSymlinkIdx !== -1) {
-        const afterProjects = basePath.slice(fwdSymlinkIdx + fwdSymlinkMarker.length);
-        if (afterProjects.includes("/worktrees/")) {
-            const projectRoot = basePath.slice(0, fwdSymlinkIdx);
-            return join(projectRoot, ".gsd", "gsd.db");
-        }
-    }
-    return join(basePath, ".gsd", "gsd.db");
+    return resolveGsdPathContract(basePath).projectDb;
 }
 export async function ensureDbOpen(basePath = process.cwd()) {
     try {
         const db = await import("../gsd-db.js");
-        const dbPath = resolveProjectRootDbPath(basePath);
-        const gsdDir = join(basePath, ".gsd");
-        // Derive the project root from the DB path (strip .gsd/gsd.db)
-        const projectRoot = join(dbPath, "..", "..");
+        const contract = resolveGsdPathContract(basePath);
+        const dbPath = contract.projectDb;
+        const gsdDir = contract.projectGsd;
+        const projectRoot = dirname(dirname(dbPath));
         // Open existing DB file (may be at project root for worktrees)
         if (existsSync(dbPath)) {
             const opened = db.openDatabase(dbPath);
@@ -78,26 +27,9 @@ export async function ensureDbOpen(basePath = process.cwd()) {
                 setLogBasePath(projectRoot);
             return opened;
         }
-        // No DB file — create + migrate from Markdown if .gsd/ has content
+        // No DB file — create an empty authoritative DB. Markdown migration is
+        // explicit-only; runtime startup must not import projections into state.
         if (existsSync(gsdDir)) {
-            const hasDecisions = existsSync(join(gsdDir, "DECISIONS.md"));
-            const hasRequirements = existsSync(join(gsdDir, "REQUIREMENTS.md"));
-            const hasMilestones = existsSync(join(gsdDir, "milestones"));
-            if (hasDecisions || hasRequirements || hasMilestones) {
-                const opened = db.openDatabase(dbPath);
-                if (opened) {
-                    setLogBasePath(projectRoot);
-                    try {
-                        const { migrateFromMarkdown } = await import("../md-importer.js");
-                        migrateFromMarkdown(basePath);
-                    }
-                    catch (err) {
-                        logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${err.message}`);
-                    }
-                }
-                return opened;
-            }
-            // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
             const opened = db.openDatabase(dbPath);
             if (opened)
                 setLogBasePath(projectRoot);

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -17,9 +17,11 @@ import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
+import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
+let approvalQuestionAbortInFlight = false;
 async function deriveGsdState(basePath) {
     const { deriveState } = await import("../state.js");
     return deriveState(basePath);
@@ -60,6 +62,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         resetWriteGateState();
         resetToolCallLoopGuard();
+        approvalQuestionAbortInFlight = false;
         await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
@@ -134,6 +137,14 @@ export function registerHooks(pi, ecosystemHandlers) {
         // Wait for ecosystem loader to finish (no-op after first turn).
         const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
+        const pendingApprovalGate = getPendingGate();
+        if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
+            markApprovalGateVerified(pendingApprovalGate);
+            const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
+            if (milestoneId)
+                markDepthVerified(milestoneId);
+            clearPendingGate();
+        }
         // GSD's own context injection (existing behavior — unchanged).
         const { buildBeforeAgentStartResult } = await import("./system-context.js");
         const gsdResult = await buildBeforeAgentStartResult(event, ctx);
@@ -173,6 +184,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         };
     });
     pi.on("agent_end", async (event, ctx) => {
+        approvalQuestionAbortInFlight = false;
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
@@ -278,6 +290,44 @@ export function registerHooks(pi, ecosystemHandlers) {
             safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
+    pi.on("message_update", async (event, ctx) => {
+        if (approvalQuestionAbortInFlight)
+            return;
+        const dash = getAutoRuntimeSnapshot();
+        let unitType = dash.currentUnit?.type;
+        let unitId = dash.currentUnit?.id;
+        if (!unitType) {
+            try {
+                const { getPendingDeepProjectSetupUnitForContext } = await import("../guided-flow.js");
+                const pending = getPendingDeepProjectSetupUnitForContext(ctx, process.cwd());
+                unitType = pending?.unitType;
+                unitId = pending?.unitId;
+            }
+            catch {
+                // Best-effort foreground detection only.
+            }
+        }
+        if (!unitType) {
+            const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+            if (milestoneId) {
+                unitType = "discuss-milestone";
+                unitId = milestoneId;
+            }
+        }
+        if (!shouldPauseForUserApprovalQuestion(unitType, [event.message]))
+            return;
+        const gateId = approvalGateIdForUnit(unitType, unitId);
+        if (gateId)
+            setPendingGate(gateId);
+        approvalQuestionAbortInFlight = true;
+        ctx.ui.notify(`${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
+        // The pending gate set above blocks subsequent non-read-only tool calls
+        // via the tool_call hook below, so we do not abort the in-flight stream.
+        // Aborting mid-stream eats the model's question text on external CLI
+        // providers (Claude Code SDK) because lastTextContent isn't populated
+        // from in-flight builder state — the user only ever sees "Claude Code
+        // stream aborted by caller" instead of the question.
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
@@ -297,15 +347,16 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("tool_call", async (event) => {
         const discussionBasePath = process.cwd();
+        const toolName = canonicalToolName(event.toolName);
         // ── Loop guard: block repeated identical tool calls ──
-        const loopCheck = checkToolCallLoop(event.toolName, event.input);
+        const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
         // ── Discussion gate enforcement: track pending gate questions ─────────
         // Only gate-shaped ask_user_questions calls should block execution.
         // The gate stays pending until the user selects the approval option.
-        if (event.toolName === "ask_user_questions") {
+        if (toolName === "ask_user_questions") {
             const questions = event.input?.questions ?? [];
             const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
             if (typeof questionId === "string") {
@@ -323,7 +374,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     return bashGuard;
             }
             else {
-                const gateGuard = shouldBlockPendingGate(event.toolName, milestoneId, isQueuePhaseActive());
+                const gateGuard = shouldBlockPendingGate(toolName, milestoneId, isQueuePhaseActive());
                 if (gateGuard.block)
                     return gateGuard;
             }
@@ -343,7 +394,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             else if (isToolCallEventType("bash", event)) {
                 queueInput = event.input.command;
             }
-            const queueGuard = shouldBlockQueueExecution(event.toolName, queueInput, true);
+            const queueGuard = shouldBlockQueueExecution(toolName, queueInput, true);
             if (queueGuard.block)
                 return queueGuard;
         }
@@ -447,7 +498,8 @@ export function registerHooks(pi, ecosystemHandlers) {
             // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
-        if (event.toolName !== "ask_user_questions")
+        const toolName = canonicalToolName(event.toolName);
+        if (toolName !== "ask_user_questions")
             return;
         const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
         const queueActive = isQueuePhaseActive();
@@ -461,14 +513,30 @@ export function registerHooks(pi, ecosystemHandlers) {
         const currentPendingGate = getPendingGate();
         if (currentPendingGate) {
             if (details?.cancelled || !details?.response) {
-                // Gate stays pending — model will be blocked from non-read-only tools
-                // until it re-asks and gets a valid response
+                // Gate stays pending. Return a hard instruction as the tool result so
+                // the model cannot reinterpret a cancelled prompt as prior approval.
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `HARD BLOCK: approval gate "${currentPendingGate}" is still pending.`,
+                                "No user response was received for the confirmation question.",
+                                "Do not infer approval from earlier or prior messages.",
+                                "Do not proceed, write files, save artifacts, or call more tools.",
+                                "Ask the user to confirm in plain chat, then stop and wait for their next message.",
+                            ].join(" "),
+                        }],
+                };
             }
             else {
                 const pendingQuestion = questions.find((question) => question?.id === currentPendingGate);
                 if (pendingQuestion) {
                     const answer = details.response?.answers?.[currentPendingGate];
                     if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
+                        markApprovalGateVerified(currentPendingGate);
+                        const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
+                        if (milestoneIdFromGate)
+                            markDepthVerified(milestoneIdFromGate);
                         clearPendingGate();
                     }
                 }
@@ -483,6 +551,9 @@ export function registerHooks(pi, ecosystemHandlers) {
                 const answer = details.response?.answers?.[question.id];
                 const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
                 if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+                    if (currentPendingGate && question.id !== currentPendingGate)
+                        break;
+                    markApprovalGateVerified(question.id);
                     markDepthVerified(inferredMilestoneId);
                     clearPendingGate();
                 }

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
@@ -17,7 +16,7 @@ import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "../gsd-home.js";
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -75,7 +74,7 @@ function buildBundledSkillsTable() {
 }
 function warnDeprecatedAgentInstructions() {
     const paths = [
-        join(gsdHome, "agent-instructions.md"),
+        join(gsdHome(), "agent-instructions.md"),
         join(process.cwd(), ".gsd", "agent-instructions.md"),
     ];
     for (const path of paths) {
@@ -119,7 +118,7 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
         }
     }
-    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome, process.cwd());
+    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }