gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/gsd/auto.ts

@@ -128,7 +128,6 @@ import {
 } from "./metrics.js";
 import { setLogBasePath, logWarning, logError } 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";
@@ -176,6 +175,7 @@ import { getErrorMessage } from "./error-utils.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
+import { isClosedStatus } from "./status-guards.js";
 import {
   type AutoDashboardData,
   updateProgressWidget as _updateProgressWidget,
@@ -195,6 +195,7 @@ import {
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS, type CmuxLogLevel } from "../shared/cmux-events.js";
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 
 function makeCmuxEmitters(pi: ExtensionAPI) {
   return {
@@ -217,9 +218,13 @@ import {
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop } from "./auto/loop.js";
+import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto/resolve.js";
+import type { LoopDeps } from "./auto/loop-deps.js";
+import type { ErrorContext } from "./auto/types.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
+import { validateDirectory } from "./validate-directory.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -250,6 +255,7 @@ export type {
   StartModel,
 } 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).
@@ -373,10 +379,7 @@ export function startAutoDetached(
 
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath?: string): boolean {
-  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 */
@@ -1167,8 +1170,7 @@ export async function pauseAuto(
       milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-    mkdirSync(runtimeDir, { recursive: true });
-    writeFileSync(
+    atomicWriteSync(
       join(runtimeDir, "paused-session.json"),
       JSON.stringify(pausedMeta, null, 2),
       "utf-8",
@@ -1189,6 +1191,19 @@ export async function pauseAuto(
     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());
@@ -1432,6 +1447,12 @@ export async function startAuto(
   // 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.
@@ -1487,14 +1508,29 @@ export async function startAuto(
           );
         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";
-            } catch {
-              summaryIsTerminal = false;
+          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);
+            }
+          }
+          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) {
@@ -1651,7 +1687,7 @@ export async function startAuto(
     // 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/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
 import {
+  checkDeepProjectSetupAfterTurn,
   checkAutoStartAfterDiscuss,
   maybeHandleReadyPhraseWithoutFiles,
   maybeHandleEmptyIntentTurn,
@@ -11,8 +12,9 @@ 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 {
@@ -46,6 +48,14 @@ export function resetTransientRetryState(): void {
   resetRetryState(retryState);
 }
 
+function resolveAgentEndBasePath(): string | undefined {
+  try {
+    return resolveProjectRoot(process.cwd());
+  } catch {
+    return undefined;
+  }
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -95,6 +105,15 @@ export async function handleAgentEnd(
   // 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/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -4,6 +4,7 @@ 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";
 import { getErrorMessage } from "../error-utils.js";
@@ -26,6 +27,16 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+function requirementRootWriteGuard(operation: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
+  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
@@ -130,6 +141,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
 
   const requirementUpdateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("update_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -208,6 +221,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
   const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("save_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -253,13 +268,28 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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')" }),
@@ -305,17 +335,18 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 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.
@@ -14,75 +15,16 @@ import { setLogBasePath, logWarning } from "../workflow-logger.js";
  * returns `<basePath>/.gsd/gsd.db`.
  */
 export function resolveProjectRootDbPath(basePath: string): string {
-  // 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: string = process.cwd()): Promise<boolean> {
   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)) {
@@ -91,26 +33,9 @@ export async function ensureDbOpen(basePath: string = process.cwd()): Promise<bo
       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 as Error).message}`);
-          }
-        }
-        return opened;
-      }
-
-      // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
       const opened = db.openDatabase(dbPath);
       if (opened) setLogBasePath(projectRoot);
       return opened;

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -7,7 +7,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 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";
@@ -23,10 +23,12 @@ 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: string) {
   const { deriveState } = await import("../state.js");
@@ -76,6 +78,7 @@ export function registerHooks(
     }
     resetWriteGateState();
     resetToolCallLoopGuard();
+    approvalQuestionAbortInFlight = false;
     await resetAskUserQuestionsTurnCache();
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
@@ -152,6 +155,14 @@ export function registerHooks(
     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);
@@ -197,6 +208,7 @@ export function registerHooks(
   });
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    approvalQuestionAbortInFlight = false;
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
@@ -305,6 +317,50 @@ export function registerHooks(
     }
   });
 
+  pi.on("message_update", async (event, ctx: ExtensionContext) => {
+    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: ExtensionContext) => {
     const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
     if (isParallelActive()) {
@@ -323,8 +379,9 @@ export function registerHooks(
 
   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 as Record<string, unknown>);
+    const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
       return { block: true, reason: loopCheck.reason };
     }
@@ -332,7 +389,7 @@ export function registerHooks(
     // ── 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: any[] = (event.input as any)?.questions ?? [];
       const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
       if (typeof questionId === "string") {
@@ -354,7 +411,7 @@ export function registerHooks(
         if (bashGuard.block) return bashGuard;
       } else {
         const gateGuard = shouldBlockPendingGate(
-          event.toolName,
+          toolName,
           milestoneId,
           isQueuePhaseActive(),
         );
@@ -375,7 +432,7 @@ export function registerHooks(
       } 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;
     }
 
@@ -496,7 +553,8 @@ export function registerHooks(
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
     }
-    if (event.toolName !== "ask_user_questions") return;
+    const toolName = canonicalToolName(event.toolName);
+    if (toolName !== "ask_user_questions") return;
     const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
     const queueActive = isQueuePhaseActive();
 
@@ -511,13 +569,28 @@ export function registerHooks(
     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" as const,
+            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();
           }
         }
@@ -533,6 +606,8 @@ export function registerHooks(
         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/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
@@ -20,8 +19,8 @@ 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";
+import { gsdHome } from "../gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
@@ -81,7 +80,7 @@ function buildBundledSkillsTable(): string {
 
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
-    join(gsdHome, "agent-instructions.md"),
+    join(gsdHome(), "agent-instructions.md"),
     join(process.cwd(), ".gsd", "agent-instructions.md"),
   ];
   for (const path of paths) {
@@ -138,7 +137,7 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  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.`,