gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Registers GSD keyboard shortcuts for dashboard, notifications, and parallel overlays.
+
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
@@ -39,18 +42,12 @@ export function registerShortcuts(pi: ExtensionAPI): void {
   };
 
   const openNotificationsOverlay = async (ctx: ExtensionContext) => {
-    const { GSDNotificationOverlay } = await import("../notification-overlay.js");
+    const { GSDNotificationOverlay, notificationOverlayOptions } = await import("../notification-overlay.js");
     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,
-        },
+        overlayOptions: notificationOverlayOptions(),
       },
     );
   };

package/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts

@@ -39,6 +39,8 @@ function toStrArray(v: unknown): string[] {
  * CompleteMilestoneParams, tolerating type mismatches from LLM JSON quirks.
  */
 export function sanitizeCompleteMilestoneParams(raw: Record<string, unknown>): CompleteMilestoneParams {
+  const actorName = toStr(raw.actorName);
+  const triggerReason = toStr(raw.triggerReason);
   return {
     milestoneId: toStr(raw.milestoneId),
     title: toStr(raw.title),
@@ -53,5 +55,7 @@ export function sanitizeCompleteMilestoneParams(raw: Record<string, unknown>): C
     followUps: toStr(raw.followUps),
     deviations: toStr(raw.deviations),
     verificationPassed: raw.verificationPassed === true || raw.verificationPassed === "true",
+    ...(actorName ? { actorName } : {}),
+    ...(triggerReason ? { triggerReason } : {}),
   };
 }

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: System prompt and hidden context bootstrap for GSD sessions.
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
@@ -21,6 +23,11 @@ import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 import { gsdHome } from "../gsd-home.js";
 
+const DEFAULT_CONTEXT_MESSAGE_MAX_CHARS = 4_000;
+const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
+const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
+const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
+const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
 
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
@@ -158,8 +165,6 @@ export async function buildBeforeAgentStartResult(
     logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
-  const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
-
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -190,11 +195,10 @@ export async function buildBeforeAgentStartResult(
       if (rawContent) {
         // Cap injection size to ~2 000 tokens to avoid bloating every request.
         // Full map is always available at .gsd/CODEBASE.md.
-        const MAX_CODEBASE_CHARS = 8_000;
         const generatedMatch = rawContent.match(/Generated: (\S+)/);
         const generatedAt = generatedMatch?.[1] ?? "unknown";
-        const content = rawContent.length > MAX_CODEBASE_CHARS
-          ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
+        const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
+          ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
           : rawContent;
         codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
       }
@@ -206,6 +210,9 @@ export async function buildBeforeAgentStartResult(
   warnDeprecatedAgentInstructions();
 
   const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+  const memoryBlock = await loadMemoryBlock(event.prompt ?? "", {
+    includePromptRelevant: !(injection && isLowEntropyResumePrompt(event.prompt ?? "")),
+  });
 
   // Re-inject forensics context on follow-up turns (#2941)
   const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd(), event.prompt) : null;
@@ -218,12 +225,9 @@ export async function buildBeforeAgentStartResult(
     : "";
 
   // memoryBlock is FTS-queried against the user prompt and changes per call.
-  // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
-  // stable across calls — the only scoped goal of this fix. The pi-ai
-  // Anthropic adapter additionally cache-marks the last user turn, so the
-  // memoryBlock injected via the context message may itself be cached up to
-  // that boundary; that's orthogonal and unchanged from prior behavior. The
-  // load-bearing win here is preserving the system+tools cache hit. (#5019)
+  // Keeping it out of `fullSystem` preserves provider prompt-cache stability
+  // for the static system/tool prefix. The dynamic memory block rides the
+  // volatile context message instead. (#5019)
   const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
 
   stopContextTimer({
@@ -255,21 +259,55 @@ export function buildContextMessage(opts: {
   injection: string | null;
   forensicsInjection: string | null;
 }): { customType: string; content: string; display: false } | null {
-  const memoryContent = opts.memoryBlock.trim();
+  const contextCharLimit = getContextMessageCharLimit();
+  const memoryContent = markMemoryContextSupplied(opts.memoryBlock.trim());
   if (opts.injection) {
-    const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+    const content = limitContextMessageContent(
+      memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection,
+      contextCharLimit,
+    );
     return { customType: "gsd-guided-context", content, display: false as const };
   }
   if (opts.forensicsInjection) {
-    const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+    const content = limitContextMessageContent(
+      memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection,
+      contextCharLimit,
+    );
     return { customType: "gsd-forensics", content, display: false as const };
   }
   if (memoryContent) {
-    return { customType: "gsd-memory", content: memoryContent, display: false as const };
+    return {
+      customType: "gsd-memory",
+      content: limitContextMessageContent(memoryContent, contextCharLimit),
+      display: false as const,
+    };
   }
   return null;
 }
 
+function getContextMessageCharLimit(): number | null {
+  const raw = process.env.PI_GSD_CONTEXT_MAX_CHARS;
+  if (!raw) return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+  if (raw === "0") return null;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < MIN_CONTEXT_MESSAGE_MAX_CHARS) {
+    return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+  }
+  return Math.floor(parsed);
+}
+
+function limitContextMessageContent(content: string, limit: number | null): string {
+  if (!limit || content.length <= limit) return content;
+  const suffix = "\n\n[GSD Context Truncated]\nFull context is available from the referenced .gsd files and tools; read on demand only if this excerpt lacks required evidence.";
+  const headBudget = Math.max(0, limit - suffix.length);
+  return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
+
+function markMemoryContextSupplied(memoryContent: string): string {
+  if (!memoryContent) return "";
+  return `[GSD Context Metadata]\n- Memory supplied: yes\n\n${memoryContent}`;
+}
+
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *
@@ -288,7 +326,10 @@ export function buildContextMessage(opts: {
  * with a token-budget cap. Failures degrade gracefully — the function never
  * throws and returns "" so the system prompt construction continues.
  */
-export async function loadMemoryBlock(userPrompt: string): Promise<string> {
+export async function loadMemoryBlock(
+  userPrompt: string,
+  opts: { includePromptRelevant?: boolean } = {},
+): Promise<string> {
   try {
     const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
 
@@ -310,7 +351,7 @@ export async function loadMemoryBlock(userPrompt: string): Promise<string> {
 
     let relevant: typeof allRanked = [];
     const trimmed = userPrompt.trim();
-    if (trimmed) {
+    if (trimmed && opts.includePromptRelevant !== false) {
       const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
       relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
     }
@@ -362,14 +403,37 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
   }
 
   const parts: string[] = [];
-  if (globalKnowledge) parts.push(`## Global Knowledge\n\n${globalKnowledge}`);
-  if (projectKnowledge) parts.push(`## Project Knowledge\n\n${projectKnowledge}`);
+  if (globalKnowledge) {
+    parts.push(`## Global Knowledge\nSource: \`${globalKnowledgePath}\`\n\n${globalKnowledge}`);
+  }
+  if (projectKnowledge) {
+    parts.push(`## Project Knowledge\nSource: \`${knowledgePath}\`\n\n${projectKnowledge}`);
+  }
+  const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
   return {
-    block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${parts.join("\n\n")}`,
+    block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
     globalSizeKb,
   };
 }
 
+function getKnowledgeCharLimit(): number | null {
+  const raw = process.env.PI_GSD_KNOWLEDGE_MAX_CHARS;
+  if (!raw) return DEFAULT_KNOWLEDGE_MAX_CHARS;
+  if (raw === "0") return null;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < MIN_KNOWLEDGE_MAX_CHARS) {
+    return DEFAULT_KNOWLEDGE_MAX_CHARS;
+  }
+  return Math.floor(parsed);
+}
+
+function limitKnowledgeBlock(content: string, limit: number | null): string {
+  if (!limit || content.length <= limit) return content;
+  const suffix = "\n\n[Knowledge Truncated]\nFull KNOWLEDGE.md content remains available at the source path(s) above; read on demand only if this excerpt lacks a required rule.";
+  const headBudget = Math.max(0, limit - suffix.length);
+  return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
+
 function buildWorktreeContextBlock(): string {
   const worktreeName = getActiveWorktreeName();
   const worktreeMainCwd = getWorktreeOriginalCwd();
@@ -423,6 +487,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)$/;
 
+export function isLowEntropyResumePrompt(prompt: string): boolean {
+  const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+  return RESUME_INTENT_PATTERNS.test(trimmed);
+}
+
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
   const ensureStateDbOpen = async () => {
     const { ensureDbOpen } = await import("./dynamic-tools.js");
@@ -452,8 +521,7 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
   // control/help/diagnostic prompts with unrelated execution context.
   // Phase-gated: only fire during "executing" to avoid misrouting during
   // replanning, gate evaluation, or other non-execution phases.
-  const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
-  if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+  if (isLowEntropyResumePrompt(prompt)) {
     await ensureStateDbOpen();
     const state = await deriveState(basePath);
     if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,10 +1,13 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+// GSD2 - Write gate runtime persistence and policy guards.
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
+import { getIsolationMode } from "../preferences.js";
 import type { ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -145,6 +148,22 @@ function writeGateSnapshotPath(basePath: string): string {
   return join(basePath, ".gsd", "runtime", "write-gate-state.json");
 }
 
+function ensureWriteGateSnapshotDirectory(basePath: string): void {
+  const gsdPath = join(basePath, ".gsd");
+  if (!existsSync(gsdPath)) {
+    try {
+      const stat = lstatSync(gsdPath);
+      if (stat.isSymbolicLink()) {
+        const target = readlinkSync(gsdPath);
+        mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+      }
+    } catch {
+      // If .gsd truly does not exist, the runtime mkdir below will create it.
+    }
+  }
+  mkdirSync(join(gsdPath, "runtime"), { recursive: true });
+}
+
 function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const state = getWriteGateState(basePath);
   return {
@@ -158,7 +177,7 @@ function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSn
 function persistWriteGateSnapshot(basePath: string): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
-  mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
+  ensureWriteGateSnapshotDirectory(basePath);
   const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
   writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(basePath), null, 2), "utf-8");
   try {
@@ -882,3 +901,135 @@ export function shouldBlockPlanningUnit(
   // avoids breaking gsd_* MCP tools or future safe additions.
   return { block: false };
 }
+
+// ─── Worktree isolation write gate (#5199) ────────────────────────────────
+//
+// When `git.isolation: worktree` is configured, the per-unit commit pipeline
+// only runs inside the auto-mode loop (`auto-post-unit.ts`). If the LLM
+// authors code at the project root before auto-mode is started, those writes
+// land in the working tree but never reach a commit — they're silently
+// orphaned outside git history. This guard blocks those writes at the
+// tool_call seam so the agent receives a clear error instead.
+
+const WORKTREE_GATE_BOOTSTRAP_UNITS = new Set([
+  "discuss-milestone",
+  "plan-milestone",
+  "init",
+]);
+
+function realpathOrResolve(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync(abs);
+  } catch {
+    // Path doesn't exist (yet) — realpath the deepest existing ancestor so
+    // platforms where /tmp -> /private/tmp don't break containment checks.
+    let dir = abs;
+    const tail: string[] = [];
+    while (dir && dir !== resolve(dir, "..")) {
+      try {
+        const real = realpathSync(dir);
+        return tail.length ? join(real, ...tail.reverse()) : real;
+      } catch {
+        const idx = dir.lastIndexOf(sep);
+        if (idx <= 0) break;
+        tail.push(dir.slice(idx + 1));
+        dir = dir.slice(0, idx) || sep;
+      }
+    }
+    return abs;
+  }
+}
+
+function isPathContained(target: string, container: string): boolean {
+  if (target === container) return true;
+  return target.startsWith(container.endsWith(sep) ? container : container + sep);
+}
+
+/**
+ * Block planning-write tool calls that would land code at the project root
+ * while `git.isolation: worktree` is in effect and auto-mode hasn't created
+ * (or flipped cwd into) the milestone worktree.
+ *
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
+ * project root and current auto liveness; this function does no I/O beyond
+ * realpath resolution.
+ *
+ * Allow rules (in order):
+ *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
+ *   2. `GSD_DISABLE_WORKTREE_WRITE_GUARD=1` self-hosting bypass.
+ *   3. Isolation mode is not "worktree".
+ *   4. Active unit is a bootstrap unit (discuss-milestone/plan-milestone/init).
+ *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
+ *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
+ *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
+ *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
+ *
+ * Otherwise: block with a message that points the agent at `/gsd` to start
+ * auto-mode.
+ */
+export function shouldBlockWorktreeWrite(
+  toolName: string,
+  targetPath: string,
+  effectiveBasePath: string,
+  isAutoLive: boolean,
+  currentUnitType?: string | null,
+): { block: boolean; reason?: string } {
+  const tool = canonicalToolName(toolName);
+  if (!PLANNING_WRITE_TOOLS.has(tool)) return { block: false };
+  if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1") return { block: false };
+  if (getIsolationMode(effectiveBasePath) !== "worktree") return { block: false };
+  if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType)) return { block: false };
+
+  if (!targetPath) {
+    return {
+      block: true,
+      reason: [
+        `HARD BLOCK: ${tool} called with empty path while \`git.isolation: worktree\` is configured`,
+        `and auto-mode is not active. Refusing to allow writes that cannot be located.`,
+      ].join(" "),
+    };
+  }
+
+  // Resolve the target relative to the project root, then realpath to defeat
+  // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
+  const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
+  const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+  const realTarget = realpathOrResolve(absTarget);
+  const realRoot = realpathOrResolve(projectRoot);
+  const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
+  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
+
+  // Allow writes inside the legitimate worktrees subtree.
+  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+
+  // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
+  // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
+  if (isPathContained(realTarget, realGsd)) {
+    const rel = relative(realGsd, realTarget);
+    const firstSeg = rel.split(/[\/\\]/)[0] ?? "";
+    if (!firstSeg.startsWith("worktrees")) return { block: false };
+    // fall through: looks like worktrees<something> sibling — block
+  }
+
+  // Auto is live and the caller is operating inside a worktree path —
+  // host tool's write happens in worktree context; let it through.
+  if (isAutoLive && isGsdWorktreePath(effectiveBasePath)) return { block: false };
+
+  // Block. Provide enough context that the agent can self-correct.
+  const displayTarget = isPathContained(realTarget, realRoot)
+    ? relative(realRoot, realTarget) || "."
+    : realTarget;
+  return {
+    block: true,
+    reason: [
+      `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+      `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+      `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+      `(auto-post-unit) commits work, and it never runs outside the loop.`,
+      `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+      `then write inside it. To disable this guard for self-hosting development, set`,
+      `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+    ].join(" "),
+  };
+}

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -3,13 +3,13 @@
  *
  * #2909: Adds a fast-path git status check before milestone completion merges.
  * When the working tree is dirty the user is warned and changes are auto-stashed
- * so the merge can proceed cleanly.  After the merge completes, postflightPopStash
- * restores the stashed changes.
+ * so the merge can proceed cleanly. After the merge completes, postflightPopStash
+ * restores the stashed changes and reports whether manual recovery is needed.
  *
  * Design constraints (from Trek-e approval):
  *  - Warn the user before stashing (no silent surprises)
  *  - git stash push / git stash pop only — no custom stash management layer
- *  - Stash/pop errors are logged but MUST NOT block the merge
+ *  - Stash/pop errors are logged but MUST NOT block the merge itself
  *  - Fast-path status check — clean trees pay no extra cost
  */
 
@@ -21,10 +21,41 @@ import { nativeHasChanges } from "./native-git-bridge.js";
 export interface PreflightResult {
   /** true when a stash was pushed and postflightPopStash should be called */
   stashPushed: boolean;
+  /** Unique marker embedded in the stash message for targeted restoration */
+  stashMarker?: string;
   /** human-readable summary of what happened (empty string for clean trees) */
   summary: string;
 }
 
+export interface PostflightResult {
+  restored: boolean;
+  needsManualRecovery: boolean;
+  message: string;
+  stashRef?: string;
+}
+
+function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
+  const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
+  let fallbackRef: string | null = null;
+  try {
+    const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    for (const line of list.split("\n")) {
+      const [ref, subject] = line.split("\x00");
+      if (!ref || !subject) continue;
+      if (stashMarker && subject.includes(stashMarker)) return ref;
+      if (!fallbackRef && subject.includes(markerPrefix)) fallbackRef = ref;
+    }
+  } catch (err) {
+    logWarning("preflight", `stash list failed before restore: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return fallbackRef;
+}
+
 /**
  * Check the working tree for dirty files before a milestone merge.
  *
@@ -62,7 +93,8 @@ export function preflightCleanRoot(
 
   // Push the stash
   try {
-    execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+    const stashMarker = `gsd-preflight-stash:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+    execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${stashMarker}]`], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
@@ -70,6 +102,7 @@ export function preflightCleanRoot(
     });
     return {
       stashPushed: true,
+      stashMarker,
       summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
     };
   } catch (err) {
@@ -86,26 +119,56 @@ export function preflightCleanRoot(
  *
  * Only called when preflightCleanRoot returned stashPushed=true.
  * Any pop error (e.g. conflict) is logged and notified but does NOT throw —
- * the merge already completed successfully.
+ * the merge already completed successfully. Callers must treat
+ * needsManualRecovery=true as a dirty workspace stop, not a clean completion.
  */
 export function postflightPopStash(
   basePath: string,
   milestoneId: string,
+  stashMarker: string | undefined,
   notify: (message: string, level: "info" | "warning" | "error") => void,
-): void {
+): PostflightResult {
+  let stashRef: string | null = null;
   try {
-    execFileSync("git", ["stash", "pop"], {
+    stashRef = findPreflightStashRef(basePath, milestoneId, stashMarker);
+    if (!stashRef) {
+      const msg = `No matching GSD preflight stash found for milestone ${milestoneId}; leaving stash list untouched.`;
+      logWarning("preflight", msg);
+      notify(msg, "warning");
+      return {
+        restored: false,
+        needsManualRecovery: true,
+        message: msg,
+      };
+    }
+    execFileSync("git", ["stash", "pop", stashRef], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
       env: GIT_NO_PROMPT_ENV,
     });
-    notify(`Restored stashed changes after milestone ${milestoneId} merge.`, "info");
+    const msg = `Restored stashed changes after milestone ${milestoneId} merge.`;
+    notify(msg, "info");
+    return {
+      restored: true,
+      needsManualRecovery: false,
+      message: msg,
+      stashRef,
+    };
   } catch (err) {
     // Pop conflicts mean the merged code collides with the stashed changes.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
-    const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+    const restoreHint = stashRef
+      ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+      : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
+    const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
     logWarning("preflight", msg);
     notify(msg, "warning");
+    return {
+      restored: false,
+      needsManualRecovery: true,
+      message: msg,
+      ...(stashRef ? { stashRef } : {}),
+    };
   }
 }

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

@@ -45,5 +45,11 @@ export async function handleGSDCommand(
 
   if (handled) return;
 
+  if (trimmed.includes(" ")) {
+    const { handleDo } = await import("../commands-do.js");
+    await handleDo(trimmed, ctx, pi);
+    return;
+  }
+
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }

package/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts

@@ -1,5 +1,5 @@
-// GSD Extension — /gsd notifications Command Handler
-// View, filter, and clear the persistent notification history.
+// Project/App: GSD-2
+// File Purpose: Handles /gsd notifications commands and opens the notification history overlay.
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
@@ -11,7 +11,7 @@ import {
   unsuppressPersistence,
   type NotifySeverity,
 } from "../../notification-store.js";
-import { GSDNotificationOverlay } from "../../notification-overlay.js";
+import { GSDNotificationOverlay, notificationOverlayOptions } from "../../notification-overlay.js";
 
 const MAX_INLINE_ENTRIES = 40;
 
@@ -108,13 +108,7 @@ export async function handleNotificationsCommand(
           (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
           {
             overlay: true,
-            overlayOptions: {
-              width: "80%",
-              minWidth: 60,
-              maxHeight: "88%",
-              anchor: "center",
-              backdrop: true,
-            },
+            overlayOptions: notificationOverlayOptions(),
           },
         );
         if (result !== undefined) {

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Handles operational /gsd subcommands.
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { enableDebug } from "../../debug-logger.js";
@@ -15,7 +17,7 @@ import { handleRemote } from "../../../remote-questions/mod.js";
 import { handleShip } from "../../commands-ship.js";
 import { handleSessionReport } from "../../commands-session-report.js";
 import { handlePrBranch } from "../../commands-pr-branch.js";
-import { projectRoot } from "../context.js";
+import { currentDirectoryRoot, projectRoot } from "../context.js";
 
 export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
   if (trimmed === "init") {
@@ -117,7 +119,7 @@ export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandCon
     return true;
   }
   if (trimmed === "triage") {
-    await handleTriage(ctx, pi, process.cwd());
+    await handleTriage(ctx, pi, currentDirectoryRoot());
     return true;
   }
   if (trimmed === "config") {

package/src/resources/extensions/gsd/commands-config.ts

@@ -23,7 +23,7 @@ export const TOOL_KEYS = [
   { id: "groq",     env: "GROQ_API_KEY",      label: "Groq Voice",        hint: "console.groq.com" },
 ] as const;
 
-function getStoredToolKey(auth: AuthStorage, providerId: string): string | undefined {
+export function getStoredToolKey(auth: AuthStorage, providerId: string): string | undefined {
   const creds = auth.getCredentialsForProvider(providerId);
   const cred = creds.find((c) => c.type === "api_key" && c.key);
   return cred?.type === "api_key" ? cred.key : undefined;

package/src/resources/extensions/gsd/commands-eval-review.ts

@@ -26,7 +26,7 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { open, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 
@@ -304,7 +304,7 @@ export async function buildEvalReviewContext(
   }
 
   const truncated = summaryRead.truncated || specTruncated;
-  const outputPath = evalReviewWritePath(state.sliceDir, state.sliceId);
+  const outputPath = evalReviewWritePath(realpathSync(state.sliceDir), state.sliceId);
   const basePath = projectRoot();
   const relativeOutputPath = relative(basePath, outputPath);