gsd-pi 2.71.0 → 2.72.0-dev.3118184

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

@@ -115,6 +115,7 @@ import {
   resetSkillTelemetry,
 } from "./skill-telemetry.js";
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
+import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import {
   initMetrics,
   resetMetrics,
@@ -165,6 +166,7 @@ import {
   reconcileMergeState,
 } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
+import { getErrorMessage } from "./error-utils.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
 import {
@@ -272,6 +274,53 @@ function restoreProjectRootEnv(): void {
   s.projectRootEnvCaptured = false;
 }
 
+function captureMilestoneLockEnv(milestoneId: string | null): void {
+  if (!s.milestoneLockEnvCaptured) {
+    s.hadMilestoneLockEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_MILESTONE_LOCK");
+    s.previousMilestoneLockEnv = process.env.GSD_MILESTONE_LOCK ?? null;
+    s.milestoneLockEnvCaptured = true;
+  }
+
+  if (milestoneId) {
+    process.env.GSD_MILESTONE_LOCK = milestoneId;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+}
+
+function restoreMilestoneLockEnv(): void {
+  if (!s.milestoneLockEnvCaptured) return;
+
+  if (s.hadMilestoneLockEnv && s.previousMilestoneLockEnv !== null) {
+    process.env.GSD_MILESTONE_LOCK = s.previousMilestoneLockEnv;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+
+  s.previousMilestoneLockEnv = null;
+  s.hadMilestoneLockEnv = false;
+  s.milestoneLockEnvCaptured = false;
+}
+
+export function startAutoDetached(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  base: string,
+  verboseMode: boolean,
+  options?: {
+    step?: boolean;
+    interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
+  },
+): void {
+  void startAuto(ctx, pi, base, verboseMode, options).catch((err) => {
+    const message = getErrorMessage(err);
+    ctx.ui.notify(`Auto-start failed: ${message}`, "error");
+    logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
+    debugLog("auto-start-failed", { error: message });
+  });
+}
+
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -549,11 +598,13 @@ function buildSnapshotOpts(
   _unitType: string,
   _unitId: string,
 ): {
+  autoSessionKey?: string;
   continueHereFired?: boolean;
   promptCharCount?: number;
   baselineCharCount?: number;
 } & Record<string, unknown> {
   return {
+    ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
     promptCharCount: s.lastPromptCharCount,
     baselineCharCount: s.lastBaselineCharCount,
     ...(s.currentUnitRouting ?? {}),
@@ -572,8 +623,10 @@ function handleLostSessionLock(
   });
   s.active = false;
   s.paused = false;
+  deactivateGSD();
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   deregisterSigtermHandler();
   clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
   const base = lockBase();
@@ -608,8 +661,10 @@ function handleLostSessionLock(
 function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.currentUnit = null;
   s.active = false;
+  deactivateGSD();
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
 
   // Clear crash lock and release session lock so the next `/gsd next` does
   // not see a stale lock with the current PID and treat it as a "remote"
@@ -622,9 +677,13 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
     logWarning("session", `lock cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
   }
 
-  ctx.ui.setStatus("gsd-auto", undefined);
-  ctx.ui.setWidget("gsd-progress", undefined);
-  ctx.ui.setFooter(undefined);
+  // A transient provider-error pause intentionally leaves the paused badge
+  // visible so the user still has a resumable auto-mode signal on screen.
+  if (!s.paused) {
+    ctx.ui.setStatus("gsd-auto", undefined);
+    ctx.ui.setWidget("gsd-progress", undefined);
+    ctx.ui.setFooter(undefined);
+  }
 
   // Restore CWD out of worktree back to original project root
   if (s.originalBasePath) {
@@ -736,7 +795,22 @@ export async function stopAuto(
       debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });
     }
 
-    // ── Step 5: DB cleanup ──
+    // ── Step 5: Rebuild state while DB is still open (#3599) ──
+    // rebuildState() calls deriveState() which needs the DB for authoritative
+    // state. Previously this ran after closeDatabase(), forcing a filesystem
+    // fallback that could disagree with the DB-backed dispatch decisions —
+    // a split-brain where dispatch says "blocked" but STATE.md shows work.
+    if (s.basePath) {
+      try {
+        await rebuildState(s.basePath);
+      } catch (e) {
+        debugLog("stop-rebuild-state-failed", {
+          error: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+
+    // ── Step 6: DB cleanup ──
     if (isDbAvailable()) {
       try {
         const { closeDatabase } = await import("./gsd-db.js");
@@ -748,7 +822,7 @@ export async function stopAuto(
       }
     }
 
-    // ── Step 6: Restore basePath and chdir ──
+    // ── Step 7: Restore basePath and chdir ──
     try {
       if (s.originalBasePath) {
         s.basePath = s.originalBasePath;
@@ -763,7 +837,7 @@ export async function stopAuto(
       debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
     }
 
-    // ── Step 7: Ledger notification ──
+    // ── Step 8: Ledger notification ──
     try {
       const ledger = getLedger();
       if (ledger && ledger.units.length > 0) {
@@ -779,17 +853,6 @@ export async function stopAuto(
       debugLog("stop-cleanup-ledger", { error: e instanceof Error ? e.message : String(e) });
     }
 
-    // ── Step 8: Rebuild state ──
-    if (s.basePath) {
-      try {
-        await rebuildState(s.basePath);
-      } catch (e) {
-        debugLog("stop-rebuild-state-failed", {
-          error: e instanceof Error ? e.message : String(e),
-        });
-      }
-    }
-
     // ── Step 9: Cmux sidebar / event log ──
     try {
       clearCmuxSidebar(loadedPreferences);
@@ -880,6 +943,7 @@ export async function stopAuto(
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
     restoreProjectRootEnv();
+    restoreMilestoneLockEnv();
 
     // Reset all session state in one call
     s.reset();
@@ -933,6 +997,7 @@ export async function pauseAuto(
       activeEngineId: s.activeEngineId,
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
+      milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
     mkdirSync(runtimeDir, { recursive: true });
@@ -970,7 +1035,9 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  deactivateGSD();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   s.pendingVerificationRetry = null;
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
@@ -1154,6 +1221,7 @@ export async function startAuto(
   options?: {
     step?: boolean;
     interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
   },
 ): Promise<void> {
   if (s.active) {
@@ -1163,6 +1231,12 @@ export async function startAuto(
 
   const requestedStepMode = options?.step ?? false;
   const interruptedAssessment = options?.interrupted ?? null;
+  if (options?.milestoneLock !== undefined) {
+    s.sessionMilestoneLock = options.milestoneLock ?? null;
+  }
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
 
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
@@ -1194,6 +1268,7 @@ export async function startAuto(
         s.originalBasePath = meta.originalBasePath || base;
         s.stepMode = meta.stepMode ?? requestedStepMode;
         s.autoStartTime = meta.autoStartTime || Date.now();
+        s.sessionMilestoneLock = meta.milestoneLock ?? null;
         s.paused = true;
         try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
         ctx.ui.notify(
@@ -1228,6 +1303,7 @@ export async function startAuto(
             s.pausedUnitType = meta.unitType ?? null;
             s.pausedUnitId = meta.unitId ?? null;
             s.autoStartTime = meta.autoStartTime || Date.now();
+            s.sessionMilestoneLock = meta.milestoneLock ?? null;
             s.paused = true;
             try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
             ctx.ui.notify(
@@ -1247,6 +1323,10 @@ export async function startAuto(
     if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now();
   }
 
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
+
   if (!s.paused) {
     s.stepMode = requestedStepMode;
   }
@@ -1641,9 +1721,6 @@ export async function dispatchHookUnit(
   return true;
 }
 
-// Direct phase dispatch → auto-direct-dispatch.ts
-export { dispatchDirectPhase } from "./auto-direct-dispatch.js";
-
 // Re-export recovery functions for external consumers
 export {
   buildLoopRemediationSteps,

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -1026,12 +1026,12 @@ export function registerDbTools(pi: ExtensionAPI): void {
     name: "gsd_save_gate_result",
     label: "Save Gate Result",
     description:
-      "Save the result of a quality gate evaluation (Q3-Q8) to the GSD database. " +
+      "Save the result of a quality gate evaluation (Q3-Q8 or MV01-MV04) to the GSD database. " +
       "Called by gate evaluation sub-agents after analyzing a specific quality question.",
     promptSnippet: "Save quality gate evaluation result (verdict, rationale, findings)",
     promptGuidelines: [
       "Use gsd_save_gate_result after evaluating a quality gate question.",
-      "gateId must be one of: Q3, Q4, Q5, Q6, Q7, Q8.",
+      "gateId must be one of: Q3, Q4, Q5, Q6, Q7, Q8, MV01, MV02, MV03, MV04.",
       "verdict must be: pass (no concerns), flag (concerns found), or omitted (not applicable).",
       "rationale should be a one-sentence justification for the verdict.",
       "findings should contain detailed markdown analysis (or empty string if omitted).",
@@ -1039,7 +1039,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     parameters: Type.Object({
       milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
       sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-      gateId: Type.String({ description: "Gate ID: Q3, Q4, Q5, Q6, Q7, or Q8" }),
+      gateId: Type.String({ description: "Gate ID: Q3, Q4, Q5, Q6, Q7, Q8, MV01, MV02, MV03, or MV04" }),
       taskId: Type.Optional(Type.String({ description: "Task ID for task-scoped gates (Q5/Q6/Q7)" })),
       verdict: Type.String({ description: "pass, flag, or omitted" }),
       rationale: Type.String({ description: "One-sentence justification" }),

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

@@ -121,6 +121,8 @@ export function registerHooks(pi: ExtensionAPI): void {
       return { cancel: true };
     }
     const basePath = process.cwd();
+    const { ensureDbOpen } = await import("./dynamic-tools.js");
+    await ensureDbOpen();
     const state = await deriveState(basePath);
     if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
     if (state.phase !== "executing") return;
@@ -179,14 +181,10 @@ export function registerHooks(pi: ExtensionAPI): void {
     // 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") {
-      const milestoneId = getDiscussionMilestoneId(discussionBasePath);
-      const inDiscussion = milestoneId !== null || isQueuePhaseActive();
-      if (inDiscussion) {
-        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") {
-          setPendingGate(questionId);
-        }
+      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") {
+        setPendingGate(questionId);
       }
     }
 
@@ -284,7 +282,6 @@ export function registerHooks(pi: ExtensionAPI): void {
     if (event.toolName !== "ask_user_questions") return;
     const milestoneId = getDiscussionMilestoneId(process.cwd());
     const queueActive = isQueuePhaseActive();
-    if (!milestoneId && !queueActive) return;
 
     const details = event.details as any;
 
@@ -317,13 +314,16 @@ export function registerHooks(pi: ExtensionAPI): void {
         // Only unlock the gate if the user selected the first option (confirmation).
         // Cross-references against the question's defined options to reject free-form "Other" text.
         const answer = details.response?.answers?.[question.id];
+        const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
         if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
-          markDepthVerified(extractDepthVerificationMilestoneId(question.id) ?? milestoneId);
+          markDepthVerified(inferredMilestoneId);
+          clearPendingGate();
         }
         break;
       }
     }
 
+    if (!milestoneId && !queueActive) return;
     if (!milestoneId) return;
 
     const basePath = process.cwd();

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

@@ -1,79 +1,98 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { Key } from "@gsd/pi-tui";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.js";
 import { GSDNotificationOverlay } from "../notification-overlay.js";
 import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js";
+import { GSD_SHORTCUTS } from "../shortcut-defs.js";
 import { projectRoot } from "../commands/context.js";
 import { shortcutDesc } from "../../shared/mod.js";
 
 export function registerShortcuts(pi: ExtensionAPI): void {
-  pi.registerShortcut(Key.ctrlAlt("g"), {
-    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      if (!existsSync(join(basePath, ".gsd"))) {
-        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
+  const overlayOptions = {
+    width: "90%",
+    minWidth: 80,
+    maxHeight: "92%",
+    anchor: "center",
+  } as const;
+
+  const openDashboardOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    if (!existsSync(join(basePath, ".gsd"))) {
+      ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  const openNotificationsOverlay = async (ctx: ExtensionContext) => {
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions: {
+          width: "80%",
+          minWidth: 60,
+          maxHeight: "88%",
+          anchor: "center",
+          backdrop: true,
         },
-      );
-    },
+      },
+    );
+  };
+
+  const openParallelOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    const parallelDir = join(basePath, ".gsd", "parallel");
+    if (!existsSync(parallelDir)) {
+      ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true), basePath),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.dashboard.action, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("n"), {
-    description: shortcutDesc("Open notification history", "/gsd notifications"),
-    handler: async (ctx) => {
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "80%",
-            minWidth: 60,
-            maxHeight: "88%",
-            anchor: "center",
-            backdrop: true,
-          },
-        },
-      );
-    },
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.dashboard.action} (fallback)`, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("p"), {
-    description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      const parallelDir = join(basePath, ".gsd", "parallel");
-      if (!existsSync(parallelDir)) {
-        ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
-        },
-      );
-    },
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.notifications.action, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
   });
+
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.notifications.action} (fallback)`, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
+  });
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.parallel.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.parallel.action, GSD_SHORTCUTS.parallel.command),
+    handler: openParallelOverlay,
+  });
+
+  // No Ctrl+Shift+P fallback — conflicts with cycleModelBackward (shift+ctrl+p).
+  // Use Ctrl+Alt+P or /gsd parallel watch instead.
 }

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -293,6 +293,11 @@ function buildWorktreeContextBlock(): string {
 const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
 
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
+  const ensureStateDbOpen = async () => {
+    const { ensureDbOpen } = await import("./dynamic-tools.js");
+    await ensureDbOpen();
+  };
+
   const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
   if (executeMatch) {
     const [, taskId, taskTitle, sliceId, milestoneId] = executeMatch;
@@ -302,6 +307,7 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
   const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
   if (resumeMatch) {
     const [, sliceId, milestoneId] = resumeMatch;
+    await ensureStateDbOpen();
     const state = await deriveState(basePath);
     if (state.activeMilestone?.id === milestoneId && state.activeSlice?.id === sliceId && state.activeTask) {
       return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, state.activeTask.id, state.activeTask.title);
@@ -317,6 +323,7 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
   // replanning, gate evaluation, or other non-execution phases.
   const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
   if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+    await ensureStateDbOpen();
     const state = await deriveState(basePath);
     if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {
       return buildTaskExecutionContextInjection(

package/src/resources/extensions/gsd/commands/context.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
-import { assertSafeDirectory } from "../validate-directory.js";
+import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
 import { handleStatus } from "./handlers/core.js";
@@ -12,6 +12,17 @@ export interface GsdDispatchContext {
   trimmed: string;
 }
 
+/**
+ * Typed error for when GSD is run outside a valid project directory.
+ * Command handlers catch this to show a friendly message instead of a raw exception.
+ */
+export class GSDNoProjectError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = "GSDNoProjectError";
+  }
+}
+
 export function projectRoot(): string {
   let cwd: string;
   try {
@@ -21,10 +32,10 @@ export function projectRoot(): string {
     cwd = process.env.HOME ?? "/";
   }
   const root = resolveProjectRoot(cwd);
-  if (root !== cwd) {
-    assertSafeDirectory(cwd);
-  } else {
-    assertSafeDirectory(root);
+  const pathToCheck = root !== cwd ? cwd : root;
+  const result = validateDirectory(pathToCheck);
+  if (result.severity === "blocked") {
+    throw new GSDNoProjectError(result.reason ?? "GSD must be run inside a project directory.");
   }
   return root;
 }

package/src/resources/extensions/gsd/commands/dispatcher.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
+import { GSDNoProjectError } from "./context.js";
 import { handleAutoCommand } from "./handlers/auto.js";
 import { handleCoreCommand } from "./handlers/core.js";
 import { handleOpsCommand } from "./handlers/ops.js";
@@ -21,10 +22,21 @@ export async function handleGSDCommand(
     () => handleOpsCommand(trimmed, ctx, pi),
   ];
 
-  for (const handler of handlers) {
-    if (await handler()) {
+  try {
+    for (const handler of handlers) {
+      if (await handler()) {
+        return;
+      }
+    }
+  } catch (err) {
+    if (err instanceof GSDNoProjectError) {
+      ctx.ui.notify(
+        `${err.message} \`cd\` into a project directory first.`,
+        "warning",
+      );
       return;
     }
+    throw err;
   }
 
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");