@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.fb12b103

package/src/resources/extensions/gsd/error-classifier.ts

@@ -10,6 +10,8 @@
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
 
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
+
 // ── ErrorClass discriminated union ──────────────────────────────────────────
 
 export type ErrorClass =
@@ -70,6 +72,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -108,6 +114,11 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "tool-schema", retryAfterMs: 0 };
   }
 
+  // Tool-surface readiness abort — transient; retry the same model shortly.
+  if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
+    return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+  }
+
   const isPermanent = PERMANENT_RE.test(errorMsg);
   const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
   const isUnsupportedModel =

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -12,6 +12,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -47,6 +48,17 @@ export interface ExecSandboxOptions {
   now?: () => Date;
   /** Optional override for id generation (tests). */
   generateId?: () => string;
+  /**
+   * Grace period (ms) between SIGTERM and SIGKILL on timeout.
+   * Defaults to SIGKILL_GRACE_MS. Exposed as a test seam.
+   */
+  kill_grace_ms?: number;
+  /**
+   * Delay (ms) after a kill is initiated before the hard-deadline force-resolves
+   * the promise (handles D-state / non-closing children).
+   * Defaults to SIGKILL_GRACE_MS + HARD_DEADLINE_MS. Exposed as a test seam.
+   */
+  force_resolve_delay_ms?: number;
 }
 
 export interface ExecSandboxResult {
@@ -55,6 +67,12 @@ export interface ExecSandboxResult {
   exit_code: number | null;
   signal: NodeJS.Signals | null;
   timed_out: boolean;
+  /**
+   * True when the result came from the hard-deadline force-resolve (a non-closing
+   * D-state child that never emitted 'close') rather than an observed process exit.
+   * In that case `signal` is the synthetic "SIGKILL" marker, not a delivered signal.
+   */
+  force_resolved: boolean;
   duration_ms: number;
   stdout_bytes: number;
   stderr_bytes: number;
@@ -68,6 +86,10 @@ export interface ExecSandboxResult {
 
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"] as const;
 
+// SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
+// (shell.ts) — the single source of truth for the graceful-kill timing ladder —
+// so this sandbox can never drift from the canonical kill path it delegates to.
+
 export const EXEC_DEFAULTS = {
   clampTimeoutMs: 600_000,
   defaultTimeoutMs: 30_000,
@@ -180,6 +202,7 @@ export function runExecSandbox(
         exit_code: null,
         signal: null,
         timed_out: false,
+        force_resolved: false,
         duration_ms: duration,
         stdout_bytes: 0,
         stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
@@ -233,23 +256,39 @@ export function runExecSandbox(
       }
     });
 
+    const effectiveGraceMs = opts.kill_grace_ms ?? SIGKILL_GRACE_MS;
+    const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
+
     let timedOut = false;
+    let settled = false;
+    let forceResolveTimer: NodeJS.Timeout | undefined;
+
     const timer = setTimeout(() => {
       timedOut = true;
-      if (useProcessGroup && child.pid != null) {
-        try {
-          process.kill(-child.pid, "SIGKILL");
-        } catch {
-          child.kill("SIGKILL");
-        }
+      // killProcessTree handles both platforms and kills the whole tree: on Unix
+      // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
+      // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
+      // would only terminate the direct child on Windows, orphaning grandchildren.
+      if (child.pid != null) {
+        killProcessTree(child.pid, { graceMs: effectiveGraceMs });
       } else {
-        child.kill("SIGKILL");
+        child.kill("SIGTERM");
       }
+      // Arm hard-deadline force-resolve in case child never closes (D-state).
+      // The "SIGKILL" here is a synthetic marker (the process may not have actually
+      // received it); force_resolved=true records that this was a deadline, not an exit.
+      forceResolveTimer = setTimeout(() => {
+        finalize(null, "SIGKILL", true);
+      }, effectiveForceResolveDelay);
+      forceResolveTimer.unref?.();
     }, timeoutMs);
     timer.unref?.();
 
-    const finalize = (exitCode: number | null, signal: NodeJS.Signals | null) => {
+    const finalize = (exitCode: number | null, signal: NodeJS.Signals | null, forceResolved = false) => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      clearTimeout(forceResolveTimer);
       const duration = Date.now() - started;
       const stdoutBuf = Buffer.concat(stdoutChunks);
       const stderrBuf = Buffer.concat(stderrChunks);
@@ -274,6 +313,7 @@ export function runExecSandbox(
         exit_code: exitCode,
         signal,
         timed_out: timedOut,
+        force_resolved: forceResolved,
         duration_ms: duration,
         stdout_bytes: stdoutBytes,
         stderr_bytes: stderrBytes,
@@ -324,6 +364,7 @@ function writeMeta(
     exit_code: result.exit_code,
     signal: result.signal,
     timed_out: result.timed_out,
+    force_resolved: result.force_resolved,
     duration_ms: result.duration_ms,
     stdout_bytes: result.stdout_bytes,
     stderr_bytes: result.stderr_bytes,
@@ -331,7 +372,6 @@ function writeMeta(
     stderr_truncated: result.stderr_truncated,
     stdout_path: result.stdout_path,
     stderr_path: result.stderr_path,
-    ...(request.metadata ? { metadata: request.metadata } : {}),
   };
   writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
 }

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

@@ -0,0 +1,139 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+
+import type { RecoveryFailureKind } from "./recovery-classification.js";
+import type { DoctorIssueCode } from "./doctor-types.js";
+
+// ─── Shape ──────────────────────────────────────────────────────────────
+
+export interface Guidance {
+  summary: string;
+  steps: string[];
+}
+
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance: Guidance): string {
+  if (guidance.steps.length === 0) return guidance.summary;
+  const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+  return `${guidance.summary}\n\n${numbered}`;
+}
+
+// ─── Recovery Classification remediation ────────────────────────────────
+// Keyed by RecoveryFailureKind. The provider kind is split by transience,
+// which Recovery Classification resolves before looking up guidance.
+
+export type RecoveryGuidanceKey =
+  | Exclude<RecoveryFailureKind, "provider">
+  | "provider-transient"
+  | "provider-permanent";
+
+const RECOVERY_REMEDIATION: Record<RecoveryGuidanceKey, string> = {
+  "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+  "tool-contract":
+    "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+  "tool-unavailable":
+    "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+  "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+  "lifecycle-progression":
+    "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+  "stale-worker":
+    "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+  "worktree-invalid":
+    "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+  "verification-drift":
+    "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+  "reconciliation-drift":
+    "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+  "illegal-transition":
+    "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+  "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+  "provider-transient": "Retry after the provider/network condition clears.",
+  "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+
+export function recoveryRemediation(key: RecoveryGuidanceKey): string {
+  return RECOVERY_REMEDIATION[key];
+}
+
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+
+export function needsAttentionBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+    `Fix options:`,
+    `1. Review the validation details: \`/gsd status\``,
+    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+  ].join("\n");
+}
+
+export function needsRemediationBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+    `Fix options:`,
+    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+  ].join("\n");
+}
+
+// ─── Crash recovery resume hints ────────────────────────────────────────
+
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType: string, unitId: string): string | undefined {
+  if (unitType === "starting" && unitId === "bootstrap") {
+    return `No work was lost. Run /gsd auto to restart.`;
+  }
+  if (unitType.includes("research") || unitType.includes("plan")) {
+    return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+  }
+  if (unitType.includes("execute")) {
+    return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+  }
+  if (unitType.includes("complete")) {
+    return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+  }
+  return undefined;
+}
+
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+
+const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
+  db_unavailable:
+    "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+  stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+  stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+  unresolved_git_conflicts:
+    "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+  conflict_markers_in_tracked_files:
+    "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+  worktree_dirty:
+    "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+  worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+  orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+  gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+  invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+  provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+  provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+  state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+  state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+  projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+  uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+
+export function doctorFixHint(code: DoctorIssueCode): string | undefined {
+  return DOCTOR_FIX_HINTS[code];
+}

package/src/resources/extensions/gsd/guided-flow.ts

@@ -90,7 +90,7 @@ import {
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import type { MilestoneScope } from "./workspace.js";
-import { getPendingGate } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import {
   _getPendingAutoStart,
   clearPendingAutoStart,
@@ -100,7 +100,7 @@ import {
   setPendingAutoStart,
 } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
-import { scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
 export {
   maybeHandleEmptyIntentTurn,
   maybeHandleReadyPhraseWithoutFiles,
@@ -1959,6 +1959,20 @@ export async function showSmartEntry(
         // Stale entry from an interrupted discussion — clear and continue
         deletePendingAutoStart(basePath);
       } else {
+        if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+          // The discussion already produced CONTEXT but the agent_end handoff
+          // never consumed the entry — e.g. an external-engine post-hoc gate
+          // re-arm wiped the depth verification after the save (write-gate
+          // two-process sync). CONTEXT can only be written through a verified
+          // depth gate, so a gate still pending for this milestone is stale:
+          // clear it and re-run the handoff instead of dead-ending.
+          const gateBasePath = entry.scope.workspace.projectRoot;
+          const pendingGateId = getPendingGate(gateBasePath);
+          if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+            clearPendingGate(gateBasePath);
+          }
+          if (checkAutoStartAfterDiscuss(basePath)) return;
+        }
         ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
         return;
       }

package/src/resources/extensions/gsd/mcp-filter.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 
 import type { ClaudeCodeMcpConfig } from "./preferences-types.js";
+import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 
@@ -83,34 +84,12 @@ function isWorkflowMcpServerConfig(config: unknown): boolean {
   return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
 }
 
-function isBrowserMcpServerConfig(config: unknown): boolean {
-  if (!isRecord(config)) return false;
-  const command = typeof config.command === "string" ? config.command : "";
-  if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
-    return true;
-  }
-
-  const env = config.env;
-  if (isRecord(env)) {
-    if (
-      typeof env.GSD_BROWSER_CLI_PATH === "string"
-      || typeof env.GSD_BROWSER_BIN_PATH === "string"
-      || typeof env.GSD_BROWSER_MCP_COMMAND === "string"
-    ) {
-      return true;
-    }
-  }
-
-  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
-  return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
-}
-
 export function discoverWorkflowMcpServerName(projectDir: string): string | undefined {
   return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
 }
 
 export function discoverBrowserMcpServerName(projectDir: string): string | undefined {
-  return discoverMcpServers(projectDir).find((server) => isBrowserMcpServerConfig(server.config))?.name;
+  return discoverMcpServers(projectDir).find((server) => isGsdBrowserMcpServerConfig(server.config))?.name;
 }
 
 export function discoverMcpServerNames(projectDir: string): string[] {

package/src/resources/extensions/gsd/mcp-tool-name.ts

@@ -1,5 +1,7 @@
 // Project/App: gsd-pi
-// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+// File Purpose: GSD-facing face over the shared @gsd/pi-ai MCP tool-name helpers.
+
+import { parseMcpToolName as parsePiAiMcpToolName, stripMcpToolPrefix } from "@gsd/pi-ai";
 
 const MCP_TOOL_PREFIX = "mcp__";
 
@@ -9,18 +11,11 @@ export interface ParsedMcpToolName {
 }
 
 export function parseMcpToolName(toolName: string): ParsedMcpToolName | null {
-  if (!toolName.startsWith(MCP_TOOL_PREFIX)) return null;
-  const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
-  if (toolSeparator < 0) return null;
-  return {
-    serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
-    toolName: toolName.slice(toolSeparator + 2),
-  };
+  const parsed = parsePiAiMcpToolName(toolName);
+  return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
 }
 
-export function stripMcpToolPrefix(toolName: string): string {
-  return parseMcpToolName(toolName)?.toolName ?? toolName;
-}
+export { stripMcpToolPrefix };
 
 export function toMcpToolName(serverName: string, toolName: string): string {
   return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;

package/src/resources/extensions/gsd/memory-consolidation-scanner.ts

@@ -264,7 +264,7 @@ export function reportConsolidationGaps(basePath: string): ConsolidationGapRepor
   try {
     const report = scanConsolidationGaps(basePath);
     if (report.totalGaps === 0) return report;
-    appendNotification(report.summary, "warning", "workflow-logger");
+    appendNotification(report.summary, "warning", "workflow-logger", { kind: "memory-consolidation" });
     logWarning("memory-consolidation", report.summary);
     return report;
   } catch (e) {

package/src/resources/extensions/gsd/migrate/safety.ts

@@ -10,6 +10,7 @@ import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
 import { closeWorkflowDatabase } from "../db-workspace.js";
 import { readPausedSessionMetadata } from "../interrupted-session.js";
 import { gsdRoot } from "../paths.js";
+import { canonicalWorktreesDir } from "../worktree-placement.js";
 import type { MigrationPreview } from "./writer.js";
 
 export interface MigrationPaths {
@@ -106,8 +107,10 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
+  // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+  // migration targets may have .gsd in the external-state layout.
   const containers = [
-    join(targetRoot, ".gsd-worktrees"),
+    canonicalWorktreesDir(targetRoot),
     join(gsdRoot(targetRoot), "worktrees"),
   ];
   for (const worktreesDir of containers) {

package/src/resources/extensions/gsd/notification-store.ts

@@ -12,6 +12,17 @@ import { randomUUID } from "node:crypto";
 export type NotifySeverity = "info" | "success" | "warning" | "error";
 export type NotificationSource = "notify" | "workflow-logger";
 
+/**
+ * Optional structured identity for a notification. When present, `kind`
+ * (a stable machine name like "auto-stop" or "provider-error-pause") plus
+ * `scope` (e.g. a milestone/slice id) — not the prose — key deduplication,
+ * and consumers can filter without parsing message text.
+ */
+export interface NotificationMeta {
+  kind?: string;
+  scope?: string;
+}
+
 export interface NotificationEntry {
   id: string;
   ts: string;
@@ -19,6 +30,8 @@ export interface NotificationEntry {
   message: string;
   source: NotificationSource;
   read: boolean;
+  kind?: string;
+  scope?: string;
 }
 
 // ─── Constants ──────────────────────────────────────────────────────────
@@ -60,11 +73,15 @@ export function appendNotification(
   message: string,
   severity: NotifySeverity,
   source: NotificationSource = "notify",
+  meta?: NotificationMeta,
 ): void {
   if (!_basePath) return;
   if (_suppressCount > 0) return;
   const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message;
-  const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`;
+  // Structured identity (kind + scope) keys dedup when present, so a rephrased
+  // message of the same event still dedups; otherwise fall back to the prose.
+  const identity = meta?.kind ? `${meta.kind}:${meta.scope ?? ""}` : persistedMessage;
+  const dedupKey = `${_basePath}:${severity}:${source}:${identity}`;
   const now = Date.now();
   const lastSeen = _recentMessageTimestamps.get(dedupKey);
   if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS) return;
@@ -82,6 +99,8 @@ export function appendNotification(
     message: persistedMessage,
     source,
     read: false,
+    ...(meta?.kind ? { kind: meta.kind } : {}),
+    ...(meta?.scope ? { scope: meta.scope } : {}),
   };
 
   try {
@@ -102,11 +121,15 @@ export function appendNotification(
 
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath?: string): NotificationEntry[] {
+export function readNotifications(basePath?: string, filter?: NotificationMeta): NotificationEntry[] {
   const bp = basePath ?? _basePath;
   if (!bp) return [];
-  return _readEntriesFromDisk(bp).reverse();
+  const entries = _readEntriesFromDisk(bp).filter(
+    (e) => (!filter?.kind || e.kind === filter.kind) && (!filter?.scope || e.scope === filter.scope),
+  );
+  return entries.reverse();
 }
 
 /**

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -128,8 +128,7 @@ function discoverWorkers(basePath: string): string[] {
   return [...mids].sort();
 }
 
-function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const workRoot = worktreePathFor(basePath, mid);
+function querySliceProgress(basePath: string, mid: string, workRoot: string = worktreePathFor(basePath, mid)): SliceProgress[] {
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
@@ -193,9 +192,12 @@ function collectWorkerData(basePath: string): WorkerView[] {
   const workers: WorkerView[] = [];
 
   for (const mid of mids) {
+    // Resolve the worktree path once per worker per tick — this runs on a
+    // 5-second refresh interval and worktreePathFor probes the filesystem.
+    const workRoot = worktreePathFor(basePath, mid);
     const status = readJsonSafe<StatusJson>(join(parallelDir, `${mid}.status.json`));
-    const lock = readJsonSafe<AutoLock>(join(worktreePathFor(basePath, mid), ".gsd", "auto.lock"));
-    const slices = querySliceProgress(basePath, mid);
+    const lock = readJsonSafe<AutoLock>(join(workRoot, ".gsd", "auto.lock"));
+    const slices = querySliceProgress(basePath, mid, workRoot);
 
     const pid = lock?.pid || status?.pid || 0;
     const alive = pid ? isPidAlive(pid) : false;

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

@@ -148,6 +148,39 @@ export function clearPathCache(): void {
 
 // ─── Name Builders ─────────────────────────────────────────────────────────
 
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS: readonly string[] = [".gsd", ".planning", ".audits"];
+
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES: readonly string[] = [
+  "CONTEXT",
+  "CONTEXT-DRAFT",
+  "ROADMAP",
+  "PLAN",
+  "REPLAN",
+  "SUMMARY",
+  "RESEARCH",
+  "VALIDATION",
+  "ASSESSMENT",
+  "UAT",
+  "DISCUSSION",
+  "EVAL-REVIEW",
+  "PARKED",
+  "VERIFICATION-FAILED",
+  "CONTINUE",
+];
+
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(
+  `^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`,
+  "i",
+);
+
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"