gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -93,10 +93,10 @@ export type PreferencesPolicy = "none" | "active-only" | "full";
 /**
  * Tool-access policy per unit type (#4934).
  *
- * Declarative-only in this PR — runtime enforcement (write-gate.ts predicate
- * + dispatch-time isolation) lands in follow-up PRs. The shape is the
- * agreement between manifest authors and enforcement; surfacing it now lets
- * reviewers ratify per-unit policy intent before any blocking logic ships.
+ * Runtime-enforced by the GSD write gate for active auto-mode units. The
+ * manifest declares the allowed tool surface; register-hooks.ts resolves the
+ * active unit's manifest before each tool call and write-gate.ts rejects
+ * violations before the tool executes.
  *
  * Modes:
  *   - "all"        — Read + Edit/Write/MultiEdit/NotebookEdit + Bash + Task.
@@ -111,6 +111,12 @@ export type PreferencesPolicy = "none" | "active-only" | "full";
  *                    Task subagent dispatch denied. Catches the bug class
  *                    where a discuss-milestone turn modifies user source
  *                    files (forensics: ~/Github/test-apps/b23, #4934).
+ *   - "planning-dispatch"
+ *                  — Same read + .gsd/** write + safe-Bash surface as
+ *                    "planning", but permits controlled subagent dispatch
+ *                    only to the agents listed in the ToolsPolicy
+ *                    `allowedSubagents` field. See write-gate.ts for the
+ *                    runtime agent-class enforcement details.
  *   - "docs"       — Read tools always; writes restricted to .gsd/** AND
  *                    the explicit `allowedPathGlobs` set; Bash safe-allowlist;
  *                    no subagents. Reserved for rewrite-docs, which legitimately
@@ -125,6 +131,7 @@ export type ToolsPolicy =
   | { readonly mode: "all" }
   | { readonly mode: "read-only" }
   | { readonly mode: "planning" }
+  | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
   | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
@@ -214,10 +221,10 @@ export interface UnitContextManifest {
   /** Preferences block policy. */
   readonly preferences: PreferencesPolicy;
   /**
-   * Tool-access policy (#4934). Declarative in this PR; runtime enforcement
-   * (path-scoped write blocking + subagent denial + bash allowlist) lands
-   * in follow-ups. Required on every manifest so missing entries fail loud
-   * via the CI invariant test rather than defaulting to "all" silently.
+   * Tool-access policy (#4934). Runtime enforcement covers path-scoped write
+   * blocking, subagent denial, and bash allowlisting for active auto-mode
+   * units. Required on every manifest so missing entries fail loud via the CI
+   * invariant test rather than defaulting to "all" silently.
    */
   readonly tools: ToolsPolicy;
   /** Artifact handling: inline (full body), excerpt (compact), or on-demand (path only). */
@@ -268,6 +275,18 @@ const COMMON_BUDGET_SMALL = 250_000;    // ~65K tokens
 
 const TOOLS_ALL: ToolsPolicy = { mode: "all" };
 const TOOLS_PLANNING: ToolsPolicy = { mode: "planning" };
+// Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
+// specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
+const TOOLS_PLANNING_DISPATCH_RECON: ToolsPolicy = {
+  mode: "planning-dispatch",
+  allowedSubagents: ["scout", "planner"],
+};
+// Like TOOLS_PLANNING_DISPATCH_RECON, but for closeout units that fan out
+// verification work to review-tier specialists.
+const TOOLS_PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
+  mode: "planning-dispatch",
+  allowedSubagents: ["reviewer", "security", "tester"],
+};
 const TOOLS_DOCS: ToolsPolicy = {
   mode: "docs",
   // Globs are resolved relative to project basePath. The set is intentionally
@@ -306,6 +325,12 @@ export const KNOWN_UNIT_TYPES = [
   "run-uat",
   "gate-evaluate",
   "rewrite-docs",
+  // Deep planning mode (project-level) units
+  "workflow-preferences",
+  "discuss-project",
+  "discuss-requirements",
+  "research-decision",
+  "research-project",
 ] as const;
 
 export type UnitType = typeof KNOWN_UNIT_TYPES[number];
@@ -362,7 +387,11 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: validation is a verification-fan-out unit. It reads
+    // the milestone surface and dispatches reviewer/security/tester subagents
+    // to report findings without touching user source. Mirrors
+    // complete-milestone's policy. Write isolation to .gsd/ is preserved.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -376,7 +405,11 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: completion is a high-leverage place to fan out to
+    // reviewer / security / tester subagents. They read the diff and report
+    // findings; they do not write user source. Write isolation to .gsd/ is
+    // preserved.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       // #4780 landed slice-summary as excerpt for this unit; phase 2 of
       // the architecture will read this manifest as the source of truth
@@ -409,7 +442,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: allows subagent dispatch so the planner can fan out
+    // to scout for codebase recon and to planner/decompose-style specialists
+    // for sub-decomposition. Write-isolation to .gsd/ is preserved.
+    tools: TOOLS_PLANNING_DISPATCH_RECON,
     artifacts: {
       inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -423,7 +459,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // See plan-slice — same rationale: dispatch to scout/planner-style
+    // specialists during refinement is materially better than re-doing recon
+    // inline.
+    tools: TOOLS_PLANNING_DISPATCH_RECON,
     artifacts: {
       inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
       excerpt: [],
@@ -451,7 +490,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // See complete-milestone — same rationale: dispatch to reviewer / security /
+    // tester subagents to fan out review work without bloating this unit's
+    // context.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       // Phase 3 migration (#4782): matches today's actual
       // buildCompleteSlicePrompt inlining order. Overrides prepend +
@@ -558,6 +600,92 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     },
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
+
+  // ─── Deep planning mode (project-level) units ────────────────────────
+  // workflow-preferences: default-writing stage that records
+  // commit_policy / branch_model in PREFERENCES.md, defaults
+  // uat_dispatch/executor_class, and records the research decision. No project artifacts needed.
+  "workflow-preferences": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // discuss-project: PROJECT.md interview (deep mode only). Project-scoped
+  // discussion runs before any milestone exists, so milestone artifacts are
+  // not loaded. Keeps templates available for PROJECT.md scaffolding.
+  "discuss-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // discuss-requirements: REQUIREMENTS.md interview. PROJECT.md is the
+  // primary context input; templates carry the requirements format.
+  "discuss-requirements": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["project", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // research-decision: lightweight one-question yes/no unit. Writes a
+  // marker JSON; no project artifacts needed.
+  "research-decision": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // research-project: orchestrator that fans out 4 parallel scout subagents
+  // for project research (stack, features, architecture, pitfalls). Needs the
+  // planning-dispatch policy to dispatch them. PROJECT.md + REQUIREMENTS.md
+  // give the orchestrator the framing context.
+  "research-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: { mode: "planning-dispatch", allowedSubagents: ["scout"] },
+    artifacts: {
+      inline: ["project", "requirements", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
 };
 
 // ─── Lookup helper ────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
 import {
   gsdRoot,
   relSliceFile,
@@ -10,6 +11,57 @@ import {
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
 
+// Per-record advisory lock — prevents read-modify-write races between
+// concurrent writers updating disjoint fields of the same runtime record.
+// Within a single Node process this is moot (writeUnitRuntimeRecord is sync),
+// but cross-process callers (parallel slice executors, doctor --fix while a
+// detached auto-mode session is alive) can otherwise clobber each other.
+const RECORD_LOCK_TIMEOUT_MS = 2_000;
+const RECORD_LOCK_STALE_MS = 5_000;
+const RECORD_LOCK_SLEEP_BUFFER = new SharedArrayBuffer(4);
+const RECORD_LOCK_SLEEP_VIEW = new Int32Array(RECORD_LOCK_SLEEP_BUFFER);
+
+function withRecordLock<T>(recordPath: string, fn: () => T): T {
+  const lockPath = recordPath + ".lock";
+  try {
+    mkdirSync(dirname(lockPath), { recursive: true });
+  } catch {
+    // best-effort
+  }
+  const deadline = Date.now() + RECORD_LOCK_TIMEOUT_MS;
+  while (true) {
+    try {
+      // O_EXCL atomic create-if-not-exists.
+      closeSync(openSync(lockPath, "wx"));
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      // Existing lock — check for staleness before either waiting or stealing.
+      try {
+        const stat = statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > RECORD_LOCK_STALE_MS) {
+          try { unlinkSync(lockPath); } catch { /* race: already removed */ }
+          continue;
+        }
+      } catch {
+        // stat failed (file removed between EEXIST and stat) — retry create.
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        // Last-resort steal — unlikely in practice but avoids permanent wedge.
+        try { unlinkSync(lockPath); } catch { /* race */ }
+        continue;
+      }
+      Atomics.wait(RECORD_LOCK_SLEEP_VIEW, 0, 0, 5);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lockPath); } catch { /* best-effort */ }
+  }
+}
+
 export type UnitRuntimePhase =
   | "dispatched"
   | "wrapup-warning-sent"
@@ -65,29 +117,29 @@ export function writeUnitRuntimeRecord(
   startedAt: number,
   updates: Partial<AutoUnitRuntimeRecord> = {},
 ): AutoUnitRuntimeRecord {
-  const dir = runtimeDir(basePath);
-  mkdirSync(dir, { recursive: true });
   const path = runtimePath(basePath, unitType, unitId);
-  const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
-  const next: AutoUnitRuntimeRecord = {
-    version: 1,
-    unitType,
-    unitId,
-    startedAt,
-    updatedAt: Date.now(),
-    phase: updates.phase ?? prev?.phase ?? "dispatched",
-    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
-    continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
-    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
-    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
-    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
-    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
-    recovery: updates.recovery ?? prev?.recovery,
-    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
-    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
-  };
-  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
-  return next;
+  return withRecordLock(path, () => {
+    const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const next: AutoUnitRuntimeRecord = {
+      version: 1,
+      unitType,
+      unitId,
+      startedAt,
+      updatedAt: Date.now(),
+      phase: updates.phase ?? prev?.phase ?? "dispatched",
+      wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+      continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
+      timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+      lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+      progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+      lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+      recovery: updates.recovery ?? prev?.recovery,
+      recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+      lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+    };
+    atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+    return next;
+  });
 }
 
 export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -21,8 +21,10 @@ export function isExecutionEntryPhase(phase: Phase): boolean {
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
+  emptyGraph?: boolean;
   graphPath?: string;
   nodeCount?: number;
+  sliceCount?: number;
   clarifyRoundLimit?: number;
   researchSynthesized?: boolean;
   draftContextIncluded?: boolean;
@@ -73,6 +75,10 @@ export function isMissingFinalizedContextResult(result: PlanV2CompileResult): bo
   return !result.ok && result.finalizedContextIncluded === false;
 }
 
+export function isEmptyPlanV2GraphResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.emptyGraph === true;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -170,6 +176,7 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
     ok: true,
     graphPath: outPath,
     nodeCount: nodes.length,
+    sliceCount: slices.length,
     clarifyRoundLimit,
     researchSynthesized: output.pipeline.researchSynthesized,
     draftContextIncluded: output.pipeline.draftContextIncluded,
@@ -181,7 +188,18 @@ export function ensurePlanV2Graph(basePath: string, state: GSDState): PlanV2Comp
   const compiled = compileUnitGraphFromState(basePath, state);
   if (!compiled.ok) return compiled;
   if ((compiled.nodeCount ?? 0) <= 0) {
-    return { ok: false, reason: "compiled graph is empty" };
+    if (
+      (state.phase === "validating-milestone" || state.phase === "completing-milestone") &&
+      (compiled.sliceCount ?? 0) > 0
+    ) {
+      return compiled;
+    }
+    return {
+      ...compiled,
+      ok: false,
+      reason: "compiled graph is empty",
+      emptyGraph: true,
+    };
   }
   return compiled;
 }

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -0,0 +1,166 @@
+const USER_APPROVAL_UNIT_TYPES = new Set([
+  "discuss-project",
+  "discuss-requirements",
+  "discuss-milestone",
+  "research-decision",
+]);
+
+const REMOTE_QUESTION_FAILURE_RE =
+  /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
+
+const APPROVAL_WAIT_RE =
+  /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
+
+const APPROVAL_QUESTION_RE =
+  /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
+
+const APPROVAL_RIGHT_QUESTION_RE =
+  /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
+
+const APPROVAL_CHANGE_QUESTION_RE =
+  /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
+
+const RESEARCH_DECISION_QUESTION_RE =
+  /\b(?:research|skip)\b/i;
+
+function extractTextFromMessage(msg: unknown): string {
+  if (!msg || typeof msg !== "object") return "";
+  const content = (msg as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const typed = block as { type?: unknown; text?: unknown };
+    if (typed.type === "text" && typeof typed.text === "string") {
+      parts.push(typed.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+function lastAssistantText(messages: unknown[] | undefined): string {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== "object") continue;
+    if ((msg as { role?: unknown }).role !== "assistant") continue;
+    const text = extractTextFromMessage(msg).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+function anyMessageMatches(messages: unknown[] | undefined, pattern: RegExp): boolean {
+  if (!Array.isArray(messages)) return false;
+  return messages.some((msg) => {
+    if (!msg || typeof msg !== "object") return false;
+    if ((msg as { role?: unknown }).role === "user") return false;
+    return pattern.test(extractTextFromMessage(msg));
+  });
+}
+
+function hasApprovalQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (APPROVAL_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_RIGHT_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_CHANGE_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+function hasResearchDecisionQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (RESEARCH_DECISION_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+export function approvalGateIdForUnit(
+  unitType: string | undefined,
+  unitId?: string | null,
+): string | null {
+  if (!unitType) return null;
+  if (unitType === "discuss-project") return "depth_verification_project_confirm";
+  if (unitType === "discuss-requirements") return "depth_verification_requirements_confirm";
+  if (unitType === "research-decision") return "depth_verification_research_decision_confirm";
+  if (unitType === "discuss-milestone") {
+    const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
+      ? unitId
+      : "milestone";
+    return `depth_verification_${safeUnitId}_confirm`;
+  }
+  return null;
+}
+
+const CHANGE_REQUEST_RESPONSE_RE =
+  /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
+
+const APPROVAL_RESPONSE_RE =
+  /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
+
+const RESEARCH_DECISION_RESPONSE_RE =
+  /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
+
+export function isExplicitApprovalResponse(
+  input: string | undefined,
+  pendingGateId?: string | null,
+): boolean {
+  const text = input?.trim() ?? "";
+  if (!text) return false;
+  if (pendingGateId?.includes("research_decision")) {
+    return RESEARCH_DECISION_RESPONSE_RE.test(text);
+  }
+  if (CHANGE_REQUEST_RESPONSE_RE.test(text)) return false;
+  return APPROVAL_RESPONSE_RE.test(text);
+}
+
+export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.some((line) => line.endsWith("?"))) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function isAwaitingApprovalBoundary(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function shouldPauseForUserApprovalQuestion(
+  unitType: string | undefined,
+  messages: unknown[] | undefined,
+): boolean {
+  if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType)) return false;
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  if (unitType === "research-decision") return hasResearchDecisionQuestion(text);
+  return hasApprovalQuestion(text);
+}

package/src/resources/extensions/gsd/visualizer-overlay.ts

@@ -20,7 +20,7 @@ import { writeExportFile } from "./export.js";
 import { gsdRoot } from "./paths.js";
 import { stripAnsi } from "../shared/mod.js";
 
-const TAB_COUNT = 10;
+export const TAB_COUNT = 10;
 const TAB_LABELS = [
   "1 Progress",
   "2 Timeline",

package/src/resources/extensions/gsd/watch/header-renderer.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { visibleWidth, truncateToWidth } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { gsdHome } from "../gsd-home.js";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -98,13 +99,15 @@ export function readGitBranch(projectRoot: string): string {
 }
 
 /**
- * Read MCP server names from .mcp.json or .gsd/mcp.json.
+ * Read MCP server names from .mcp.json, .gsd/mcp.json, and the global
+ * ~/.gsd/mcp.json (or $GSD_HOME/mcp.json).
  * Returns array of server name strings.
  */
 export function readMcpServerNames(projectRoot: string): string[] {
   const configPaths = [
     join(projectRoot, ".mcp.json"),
     join(projectRoot, ".gsd", "mcp.json"),
+    join(gsdHome(), "mcp.json"),
   ];
   const names: string[] = [];
   const seen = new Set<string>();

package/src/resources/extensions/gsd/workflow-install.ts

@@ -22,12 +22,12 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { extname, join, resolve, sep as pathSep } from "node:path";
 import { createHash } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 
 import { validateDefinition } from "./definition-loader.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
@@ -73,8 +73,7 @@ export interface InstallTarget {
 }
 
 export function globalInstallDir(): string {
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  return join(gsdHome, "workflows");
+  return join(gsdHome(), "workflows");
 }
 
 export function projectInstallDir(basePath: string): string {

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -66,6 +66,7 @@ export type LogComponent =
   | "memory-embeddings" // Memory layer embedding generation
   | "memory-ingest"     // Memory layer ingestion pipeline
   | "memory-backfill"   // ADR-013: decisions->memories backfill
+  | "memory-store"      // Memory CRUD layer — surfaces SQLite/store-level faults (#4967)
   | "context-mode"     // Context-mode exec sandbox and compaction snapshot
   | "preflight"        // Clean-root preflight gate at milestone completion
   | "postUnit";     // Post-unit processing (abandon detection, overrides)

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -76,7 +76,9 @@ export function snapshotState(): StateManifest {
   // Wrap all reads in a deferred transaction so the snapshot is consistent
   // (all SELECTs see the same DB state even if a concurrent write lands between them).
   return readTransaction(() => {
-  const rawMilestones = db.prepare("SELECT * FROM milestones ORDER BY id").all() as Record<string, unknown>[];
+  const rawMilestones = db.prepare(
+    "SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id",
+  ).all() as Record<string, unknown>[];
   const milestones: MilestoneRow[] = rawMilestones.map((r) => ({
     id: r["id"] as string,
     title: r["title"] as string,
@@ -95,6 +97,7 @@ export function snapshotState(): StateManifest {
     definition_of_done: JSON.parse((r["definition_of_done"] as string) || "[]"),
     requirement_coverage: (r["requirement_coverage"] as string) ?? "",
     boundary_map_markdown: (r["boundary_map_markdown"] as string) ?? "",
+    sequence: Number(r["sequence"] ?? 0),
   }));
 
   const rawSlices = db.prepare("SELECT * FROM slices ORDER BY milestone_id, sequence, id").all() as Record<string, unknown>[];