@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { join, resolve as resolvePath, sep } from "node:path";
+import { join, resolve as resolvePath, sep, win32 as pathWin32 } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
@@ -28,6 +28,8 @@ import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";
+import { reconcileGsdBrowserPathAfterInstall } from "../../shared/gsd-browser-path-sync.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import {
   buildDoctorHealIssuePayload,
@@ -64,9 +66,48 @@ function isBunInstall(argv1: string | undefined = process.argv[1]): boolean {
 function resolveInstallCommand(pkg: string): string {
   if (isBunInstall()) return `bun add -g ${pkg}`;
   if (isPnpmInstall()) return `pnpm add -g ${pkg}`;
+  const npmPrefix = resolveWindowsNpmGlobalPrefix();
+  if (npmPrefix) return `npm --prefix ${quoteWindowsArg(npmPrefix)} install -g ${pkg}`;
   return `npm install -g ${pkg}`;
 }
 
+function resolveWindowsNpmGlobalPrefix(
+  argv1: string | undefined = process.argv[1],
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (platform !== "win32" || !argv1) return null;
+  const normalized = pathWin32.normalize(argv1);
+  const marker = `${pathWin32.sep}node_modules${pathWin32.sep}`;
+  const index = normalized.toLowerCase().lastIndexOf(marker);
+  if (index <= 0) return null;
+  const prefix = normalized.slice(0, index);
+  // Verify this is a real npm global prefix: such a directory always contains
+  // npm's own bin shim (`npm.cmd`) as a sibling of `node_modules/`. Local
+  // project `node_modules/`, npx caches, and other non-global layouts do not,
+  // so without this check `--prefix` would target the wrong directory.
+  if (!existsSync(pathWin32.join(prefix, "npm.cmd"))) return null;
+  return prefix;
+}
+
+function quoteWindowsArg(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function notifyClaudeRuntimeFloorAdvisory(ctx: ExtensionCommandContext): void {
+  let advisory: string | null = null;
+  try {
+    advisory = buildClaudeRuntimeFloorAdvisory({
+      agentDir: join(gsdHome(), "agent"),
+      cwd: process.cwd(),
+    });
+  } catch {
+    return;
+  }
+  if (advisory) {
+    ctx.ui.notify(advisory, "warning");
+  }
+}
+
 async function fetchLatestVersionForCommand(registryUrl: string = UPDATE_REGISTRY_URL): Promise<string | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
@@ -139,6 +180,73 @@ export function isDoctorHealActionable(issue: { fixable: boolean; severity: stri
   return issue.fixable && issue.severity !== "info";
 }
 
+/**
+ * Compat-health line for `/gsd doctor`. Reports the gsd-core compat marker's
+ * presence and the count of projection files whose on-disk sha has drifted
+ * from the recorded baseline. Returns "" if the marker module is unavailable
+ * (defensive — doctor must never fail because of compat reporting).
+ *
+ * Exported for unit testing.
+ */
+export async function formatCompatHealthLine(basePath: string): Promise<string> {
+  try {
+    const { readCompatMarker, computeProjectionSha } = await import("./compat/compat-marker.js");
+    const marker = readCompatMarker(basePath);
+
+    const countDrifted = (
+      entries: Record<string, { sha: string }>,
+      root: string,
+    ): number => {
+      let drifted = 0;
+      for (const [rel, entry] of Object.entries(entries)) {
+        const abs = join(basePath, root, rel);
+        if (!existsSync(abs)) continue;
+        if (computeProjectionSha(readFileSync(abs, "utf-8")) !== entry.sha) drifted++;
+      }
+      return drifted;
+    };
+
+    const lines: string[] = [];
+    const gsdEntryCount = Object.keys(marker.projections).length;
+    const planningActive = marker.planning?.active ?? false;
+    const planningEntryCount = planningActive
+      ? Object.keys(marker.planning!.projections).length +
+        Object.keys(marker.planning!.passthrough).length
+      : 0;
+
+    if (gsdEntryCount === 0 && !planningActive) {
+      return "  Compat health:      no baseline (run /gsd sync to establish)";
+    }
+
+    if (gsdEntryCount === 0) {
+      lines.push("  Compat health (.gsd):    no baseline (run /gsd sync to establish)");
+    } else {
+      const gsdDrifted = countDrifted(marker.projections, ".gsd");
+      lines.push(
+        `  Compat health (.gsd):    ${gsdDrifted === 0 ? "OK" : `${gsdDrifted} file(s) drifted — run /gsd sync`}`,
+      );
+    }
+
+    if (planningActive) {
+      if (planningEntryCount === 0) {
+        lines.push("  Compat health (.planning): no baseline (run /gsd sync to establish)");
+      } else {
+        const planningDrifted =
+          countDrifted(marker.planning!.projections, ".planning") +
+          countDrifted(marker.planning!.passthrough, ".planning");
+        lines.push(
+          `  Compat health (.planning): ${planningDrifted === 0 ? "OK" : `${planningDrifted} file(s) drifted — run /gsd sync`}`,
+        );
+      }
+    } else {
+      lines.push(`  Compat health (.planning): not active`);
+    }
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
 export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
@@ -165,7 +273,13 @@ export async function handleDoctor(args: string, ctx: ExtensionCommandContext, p
     title: mode === "audit" ? "GSD doctor audit." : mode === "heal" ? "GSD doctor heal prep." : undefined,
   });
 
-  ctx.ui.notify(reportText, report.ok ? "info" : "warning");
+  // Compat health: marker presence + drift vs current projections. Appended to
+  // the formatted report so it surfaces in every doctor run without touching
+  // the doctor report internals.
+  const compatLine = await formatCompatHealthLine(projectRoot());
+  const fullReport = compatLine ? `${reportText}\n${compatLine}` : reportText;
+
+  ctx.ui.notify(fullReport, report.ok ? "info" : "warning");
 
   if (mode === "heal") {
     const unresolved = filterDoctorIssues(report.issues, {
@@ -385,6 +499,8 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
 
   const type = typeArg as "rule" | "pattern" | "lesson";
   const basePath = currentDirectoryRoot();
+  const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+  await ensureDbOpen(basePath);
   const state = await deriveState(basePath);
   const scope = state.activeMilestone?.id
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
@@ -549,6 +665,7 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
 
   if (current && compareSemverLocal(latest, current) <= 0) {
     ctx.ui.notify(`Already up to date (${formatCommandVersion(current)}).`, "info");
+    if (!browserUpdate) notifyClaudeRuntimeFloorAdvisory(ctx);
     return;
   }
 
@@ -559,15 +676,34 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
     execSync(installCmd, {
       stdio: ["ignore", "pipe", "ignore"],
     });
+    let reconcile: ReturnType<typeof reconcileGsdBrowserPathAfterInstall> | null = null;
+    if (browserUpdate) {
+      try {
+        reconcile = reconcileGsdBrowserPathAfterInstall({
+          latestVersion: latest,
+          compareSemver: compareSemverLocal,
+          resolvePathVersion: resolveGsdBrowserPathVersionForCommand,
+        });
+      } catch {
+        // Reconciliation is best-effort: the install above already succeeded,
+        // so a reconcile failure must not flip the result to "Update failed".
+        reconcile = null;
+      }
+    }
     const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
-    const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
+    const pathNote = browserUpdate && !(newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0)
+      ? (reconcile?.message
+        ?? "Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+      : "";
     ctx.ui.notify(
       browserUpdate
         ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
-          (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+          (reconcile?.action === "synced" && reconcile.message ? `\n${reconcile.message}` : "") +
+          (pathNote ? `\nNote: ${pathNote}` : "")
         : `Updated to v${latest}. Restart your GSD session to use the new version.`,
       "info",
     );
+    if (!browserUpdate) notifyClaudeRuntimeFloorAdvisory(ctx);
   } catch {
     ctx.ui.notify(
       `Update failed. Try manually: ${installCmd}`,

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

@@ -5,9 +5,10 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import {
+  isWorkflowDatabaseOpen,
+  openExistingWorkflowDatabase,
+} from "./db-workspace.js";
 import { logWarning } from "./workflow-logger.js";
 import { getErrorMessage } from "./error-utils.js";
 
@@ -48,12 +49,10 @@ export function formatInspectOutput(data: InspectData): string {
 
 export async function handleInspect(ctx: ExtensionCommandContext): Promise<void> {
   try {
-    const { isDbAvailable, _getAdapter, openDatabase } = await import("./gsd-db.js");
+    const { _getAdapter } = await import("./gsd-db.js");
 
-    if (!isDbAvailable()) {
-      const gsdDir = gsdRoot(process.cwd());
-      const dbPath = join(gsdDir, "gsd.db");
-      if (!existsSync(gsdDir) || !existsSync(dbPath) || !openDatabase(dbPath)) {
+    if (!isWorkflowDatabaseOpen()) {
+      if (!openExistingWorkflowDatabase(process.cwd()).ok) {
         ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
         return;
       }

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

@@ -11,6 +11,7 @@ import { deriveState } from "./state.js";
 import { gsdProjectionRoot, gsdRoot } from "./paths.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { logWarning } from "./workflow-logger.js";
+import { backupWorkflowDatabaseSnapshot, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 
 export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
   let branches: string[];
@@ -581,7 +582,7 @@ async function confirmRecover(
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
-  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction, backupDatabaseSnapshot } = await import("./gsd-db.js");
+  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
   const { migrateHierarchyToDb } = await import("./md-importer.js");
   const { invalidateStateCache } = await import("./state.js");
   const { countDbHierarchy, countMarkdownHierarchy, recoverWouldDeleteDbRows } = await import("./migration-auto-check.js");
@@ -604,7 +605,7 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
 
   try {
     // 0. Snapshot the DB before the destructive clear so recover is reversible.
-    const backupPath = backupDatabaseSnapshot("pre-recover");
+    const backupPath = backupWorkflowDatabaseSnapshot("pre-recover");
 
     // 1. Delete + re-populate inside a single transaction for atomicity.
     //    clearEngineHierarchy() uses transaction() internally but transaction()
@@ -749,19 +750,168 @@ function parseRebuildTarget(args: string): RebuildTarget {
   return "usage";
 }
 
+export interface RebuildMarkdownProjectionsResult {
+  rendered: number;
+  skipped: number;
+  errors: string[];
+  quarantined: number;
+  quarantinedPaths: string[];
+}
+
 /**
- * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
+ * Re-render markdown planning projections from the authoritative DB.
  *
- * This is the DB-first realignment command. It does not import markdown into
- * the DB. Completion SUMMARY files that contradict open DB rows are preserved
- * under `.gsd/quarantine/projections/` before DB projections are rendered.
+ * Quarantines open-unit SUMMARY files that contradict DB status before
+ * rendering. Safe to call after milestone merge/transition or during startup
+ * self-heal when the DB holds rows markdown lacks.
  */
-export async function handleRebuild(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
-  const { isDbAvailable: dbAvailable, deleteArtifactByPath } = await import("./gsd-db.js");
+export async function rebuildMarkdownProjectionsFromDb(
+  basePath: string,
+): Promise<RebuildMarkdownProjectionsResult> {
+  const { deleteArtifactByPath } = await import("./gsd-db.js");
   const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
   const { renderAllFromDb } = await import("./markdown-renderer.js");
   const { invalidateStateCache } = await import("./state.js");
 
+  invalidateStateCache();
+  refreshWorkflowDatabaseFromDisk();
+
+  const state = await deriveState(basePath);
+  const drifts = detectArtifactDbDrift(state, { basePath, state });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const quarantined: string[] = [];
+  const seen = new Set<string>();
+
+  for (const drift of drifts) {
+    if (drift.kind !== "artifact-db-status-divergence") continue;
+    if (drift.artifactType !== "SUMMARY" || !drift.artifactPath) continue;
+    const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
+    if (seen.has(absPath) || !existsSync(absPath)) continue;
+    seen.add(absPath);
+    const artifactDbPath = artifactPathForDb(basePath, absPath);
+    const target = quarantineProjectionFile(basePath, absPath, stamp);
+    deleteArtifactByPath(artifactDbPath);
+    quarantined.push(target);
+  }
+
+  const rendered = await renderAllFromDb(basePath);
+  invalidateStateCache();
+
+  return {
+    rendered: rendered.rendered,
+    skipped: rendered.skipped,
+    errors: rendered.errors,
+    quarantined: quarantined.length,
+    quarantinedPaths: quarantined,
+  };
+}
+
+/**
+ * `/gsd sync` — pull in external (gsd-core) markdown edits and re-project.
+ *
+ * Non-destructive cousin of `/gsd recover`: does NOT clear the DB. Runs the
+ * ADR-017 reconcile pipeline (which picks up the external-markdown-edit handler
+ * automatically), then re-projects via renderAllFromDb, then refreshes the
+ * compat marker. Use this when switching from gsd-core mid-session.
+ *
+ * Accepts `--dry-run` to report what would change without writing.
+ */
+export async function handleSync(
+  ctx: ExtensionCommandContext,
+  basePath: string,
+  args = "",
+): Promise<void> {
+  const { isDbAvailable } = await import("./gsd-db.js");
+  const { reconcileBeforeDispatch } = await import("./state-reconciliation/index.js");
+  const { renderAllFromDb } = await import("./markdown-renderer.js");
+  const { writeCompatMarker, readCompatMarker } = await import("./compat/compat-marker.js");
+
+  const dryRun = args.trim() === "--dry-run";
+
+  if (!isDbAvailable()) {
+    ctx.ui.notify("gsd sync: No database open. Run a GSD command first to initialize the DB.", "error");
+    return;
+  }
+
+  const lines: string[] = ["gsd sync: reconciling .gsd/ for cross-tool edits…"];
+
+  try {
+    const result = await reconcileBeforeDispatch(basePath, { dryRun });
+    const repairedExternal = result.repaired.filter((r) => r.kind === "external-markdown-edit");
+    lines.push(
+      `  External .gsd/ edits ${dryRun ? "to import" : "imported"}: ${repairedExternal.length}`,
+    );
+    for (const r of repairedExternal) {
+      const e = r as { kind: "external-markdown-edit"; projectionPath: string };
+      lines.push(`    • ${e.projectionPath}`);
+    }
+    const repairedPlanningExternal = result.repaired.filter((r) => r.kind === "external-planning-edit");
+    if (repairedPlanningExternal.length > 0) {
+      lines.push(
+        `  External .planning/ edits ${dryRun ? "to import" : "imported"}: ${repairedPlanningExternal.length}`,
+      );
+      for (const r of repairedPlanningExternal) {
+        const e = r as { kind: "external-planning-edit"; projectionPath: string; passthrough: boolean };
+        const tag = e.passthrough ? " (passthrough)" : "";
+        lines.push(`    • ${e.projectionPath}${tag}`);
+      }
+    }
+    if (result.blockers.length > 0) {
+      lines.push("", "  ⚠ Blockers:");
+      for (const b of result.blockers) lines.push(`    • ${b}`);
+    }
+
+    if (dryRun) {
+      lines.push("", "  (dry-run: no repairs, projection, or marker writes performed)");
+      ctx.ui.notify(lines.join("\n"), "info");
+      return;
+    }
+
+    const renderResult = await renderAllFromDb(basePath);
+    if (renderResult.errors.length > 0) {
+      lines.push("", "  ⚠ Projection errors:");
+      for (const e of renderResult.errors) lines.push(`    • ${e}`);
+    }
+
+    // Refresh the marker to reflect the freshly re-projected state. The
+    // planning hook inside renderAllFromDb already recorded per-file SHAs
+    // into marker.planning.projections; we read back the fully-populated
+    // marker here so the timestamp is the last thing written.
+    const marker = readCompatMarker(basePath);
+    marker.lastWriter = "gsd-pi";
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(basePath, marker);
+    const planningShaCnt = Object.keys(marker.planning?.projections ?? {}).length;
+    const planningNote = planningShaCnt > 0
+      ? ` + ${planningShaCnt} .planning/ SHA${planningShaCnt !== 1 ? "s" : ""}`
+      : "";
+
+    const state = await deriveState(basePath);
+    lines.push(
+      "",
+      `  Phase:  ${state.phase}`,
+      `  Marker: .gsd/.compat.json refreshed${planningNote}`,
+    );
+    if (state.activeMilestone) {
+      lines.push(`  Active: ${state.activeMilestone.id}: ${state.activeMilestone.title}`);
+    }
+
+    ctx.ui.notify(lines.join("\n"), "info");
+  } catch (err) {
+    ctx.ui.notify(`gsd sync failed: ${(err as Error).message}`, "error");
+  }
+}
+
+/**
+ * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
+ *
+ * This is the DB-first realignment command. It does not import markdown into the
+ * DB. Completion SUMMARY files that contradict open DB rows are preserved
+ * under `.gsd/quarantine/projections/` before DB projections are rendered.
+ */
+export async function handleRebuild(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
+  const { isDbAvailable: dbAvailable } = await import("./gsd-db.js");
+
   const target = parseRebuildTarget(args);
   if (target === "usage") {
     ctx.ui.notify(
@@ -794,54 +944,34 @@ export async function handleRebuild(ctx: ExtensionCommandContext, basePath: stri
   }
 
   try {
-    invalidateStateCache();
-    const state = await deriveState(basePath);
-    const drifts = detectArtifactDbDrift(state, { basePath, state });
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const quarantined: string[] = [];
-    const seen = new Set<string>();
-
-    for (const drift of drifts) {
-      if (drift.kind !== "artifact-db-status-divergence") continue;
-      if (drift.artifactType !== "SUMMARY" || !drift.artifactPath) continue;
-      const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
-      if (seen.has(absPath) || !existsSync(absPath)) continue;
-      seen.add(absPath);
-      const artifactDbPath = artifactPathForDb(basePath, absPath);
-      const target = quarantineProjectionFile(basePath, absPath, stamp);
-      deleteArtifactByPath(artifactDbPath);
-      quarantined.push(target);
-    }
-
-    const rendered = await renderAllFromDb(basePath);
-    invalidateStateCache();
+    const result = await rebuildMarkdownProjectionsFromDb(basePath);
 
     const lines = [
       "gsd rebuild markdown: rebuilt markdown projections from the canonical DB",
-      `  Rendered:    ${rendered.rendered}`,
-      `  Skipped:     ${rendered.skipped}`,
-      `  Quarantined: ${quarantined.length}`,
+      `  Rendered:    ${result.rendered}`,
+      `  Skipped:     ${result.skipped}`,
+      `  Quarantined: ${result.quarantined}`,
     ];
-    if (rendered.errors.length > 0) {
-      lines.push(`  Errors:      ${rendered.errors.length}`);
-      for (const err of rendered.errors.slice(0, 5)) {
+    if (result.errors.length > 0) {
+      lines.push(`  Errors:      ${result.errors.length}`);
+      for (const err of result.errors.slice(0, 5)) {
         lines.push(`    - ${err}`);
       }
-      if (rendered.errors.length > 5) {
-        lines.push(`    - ${rendered.errors.length - 5} more`);
+      if (result.errors.length > 5) {
+        lines.push(`    - ${result.errors.length - 5} more`);
       }
     }
-    if (quarantined.length > 0) {
+    if (result.quarantined > 0) {
       lines.push("", "  Quarantine:");
-      for (const target of quarantined.slice(0, 5)) {
+      for (const target of result.quarantinedPaths.slice(0, 5)) {
         lines.push(`    - ${target}`);
       }
-      if (quarantined.length > 5) {
-        lines.push(`    - ${quarantined.length - 5} more`);
+      if (result.quarantined > 5) {
+        lines.push(`    - ${result.quarantined - 5} more`);
       }
     }
 
-    ctx.ui.notify(lines.join("\n"), rendered.errors.length > 0 ? "warning" : "success");
+    ctx.ui.notify(lines.join("\n"), result.errors.length > 0 ? "warning" : "success");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     logWarning("command", `rebuild failed: ${msg}`);

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -102,7 +102,7 @@ export function formatMcpStatusReport(servers: McpServerStatus[]): string {
       : s.connected
         ? `connected — ${s.toolCount} tools`
         : s.available
-          ? `available — ${s.toolCount} tools`
+          ? `probe available — ${s.toolCount} tools`
         : "disconnected";
     const warningText = s.envWarnings?.length ? ` — ${s.envWarnings.length} warning(s)` : "";
     lines.push(`  ${icon} ${s.name} (${s.transport}) — ${status}${warningText}`);
@@ -128,7 +128,7 @@ export function formatMcpServerDetail(server: McpServerDetail): string {
     lines.push(`  Status:    error`);
     lines.push(`  Error:     ${server.error}`);
   } else if (server.connected || server.available) {
-    lines.push(`  Status:    ${server.connected ? "connected" : "available"}`);
+    lines.push(`  Status:    ${server.connected ? "connected" : "probe available"}`);
     lines.push(`  Tools:     ${server.toolCount}`);
     if (server.tools.length > 0) {
       lines.push("");

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -19,9 +19,11 @@ import {
   loadEffectiveGSDPreferences,
   normalizePreferencesShape,
   resolveAllSkillReferences,
+  clearGSDPreferencesCache,
 } from "./preferences.js";
 import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 import { runClaudeImportFlow } from "./claude-import.js";
+import { clearSessionModelOverride } from "./session-model-override.js";
 
 const DEFAULT_WIDGET_MODE = "small";
 const WIDGET_MODE_OPTIONS = [DEFAULT_WIDGET_MODE, "full", "min", "off"] as const;
@@ -297,6 +299,7 @@ export async function handleImportClaude(ctx: ExtensionCommandContext, scope: "g
       if (preserved) body = preserved;
     }
     await saveFile(path, `---\n${frontmatter}---${body}`);
+    clearGSDPreferencesCache();
   };
 
   await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
@@ -321,6 +324,7 @@ export async function handlePrefsMode(ctx: ExtensionCommandContext, scope: "glob
 
   const content = `---\n${frontmatter}---${body}`;
   await saveFile(path, content);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
   ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
@@ -1676,8 +1680,15 @@ export async function writePreferencesFile(
 
   const content = `---\n${frontmatter}---${body}`;
   await saveFile(path, content);
+  clearGSDPreferencesCache();
 
   if (ctx) {
+    // Per-phase model prefs must beat an earlier /gsd model session pin.
+    const models = prefs.models;
+    if (models && typeof models === "object" && Object.keys(models as object).length > 0) {
+      const sessionId = ctx.sessionManager?.getSessionId?.();
+      if (sessionId) clearSessionModelOverride(sessionId);
+    }
     await ctx.waitForIdle();
     await ctx.reload();
     if (opts?.notifyOnSave !== false) {
@@ -1803,6 +1814,7 @@ export async function ensurePreferencesFile(
       return;
     }
     await saveFile(path, template);
+    clearGSDPreferencesCache();
     ctx.ui.notify(`Created ${scope} GSD skill preferences at ${path}`, "info");
   } else {
     ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
@@ -1859,6 +1871,7 @@ export async function handleLanguage(args: string, ctx: ExtensionCommandContext)
   const body = extractBodyAfterFrontmatter(rawContent)
     ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
   await saveFile(path, `---\n${frontmatter}---${body}`);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
 }

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

@@ -21,7 +21,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
-import { buildPrEvidence } from "./pr-evidence.js";
+import { buildPullRequestEvidence } from "./pull-request-process.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -178,7 +178,7 @@ function generatePRContent(basePath: string, milestoneId: string, milestoneTitle
     }
   }
 
-  return buildPrEvidence({
+  return buildPullRequestEvidence({
     milestoneId,
     milestoneTitle,
     changeType: "feat",

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

@@ -5,10 +5,12 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { loadFile } from "./files.js";
 import { resolveMilestoneFile } from "./paths.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { deriveState } from "./state.js";
 import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getLatestAssessmentByScope } from "./gsd-db.js";
+import { checkpointWorkflowDatabase } from "./db-workspace.js";
 import {
   VALIDATION_VERDICTS,
   extractVerdict,
@@ -122,10 +124,24 @@ async function loadExistingValidation(
   basePath: string,
   milestoneId: string,
 ): Promise<ExistingValidation | null> {
-  const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
-  if (validationPath) {
-    const content = await loadFile(validationPath);
-    if (content) return { content, source: validationPath };
+  // Layout-aware lookup against the canonical milestone root first (handles the
+  // worktree case via resolveCanonicalMilestoneRoot), then against the raw
+  // basePath if they differ. See open-gsd/gsd-pi#876.
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const canonicalValidationPath = resolveMilestoneFile(canonicalBase, milestoneId, "VALIDATION");
+  if (canonicalValidationPath) {
+    const canonicalContent = await loadFile(canonicalValidationPath);
+    if (canonicalContent) {
+      return { content: canonicalContent, source: canonicalValidationPath };
+    }
+  }
+
+  if (basePath !== canonicalBase) {
+    const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
+    if (validationPath && validationPath !== canonicalValidationPath) {
+      const content = await loadFile(validationPath);
+      if (content) return { content, source: validationPath };
+    }
   }
 
   await ensureDbOpen(basePath);
@@ -222,6 +238,8 @@ export async function handleVerdict(
     return;
   }
 
+  checkpointWorkflowDatabase();
+
   const prevVerdict = current.verdict ?? "unknown";
   const effectiveVerdict = extractEffectiveVerdict(result.details, parsed.verdict);
   if (effectiveVerdict !== parsed.verdict) {