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

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -158,6 +158,65 @@ export function parseDoctorArgs(args) {
 export function isDoctorHealActionable(issue) {
     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) {
+    try {
+        const { readCompatMarker, computeProjectionSha } = await import("./compat/compat-marker.js");
+        const marker = readCompatMarker(basePath);
+        const countDrifted = (entries, root) => {
+            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 = [];
+        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, ctx, pi) {
     const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
     const scope = await selectDoctorScope(projectRoot(), requestedScope);
@@ -181,7 +240,12 @@ export async function handleDoctor(args, ctx, pi) {
         maxIssues: mode === "audit" ? 50 : 12,
         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, {
             scope: effectiveScope,
@@ -362,6 +426,8 @@ export async function handleKnowledge(args, ctx) {
     }
     const type = typeArg;
     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}` : ""}`

package/dist/resources/extensions/gsd/commands-maintenance.js

@@ -699,11 +699,88 @@ export async function rebuildMarkdownProjectionsFromDb(basePath) {
         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, basePath, args = "") {
+    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 = ["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;
+            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;
+                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.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
+ * 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, basePath, args = "") {

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -8,9 +8,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, loadEffectiveGSDPreferences, normalizePreferencesShape, resolveAllSkillReferences, } from "./preferences.js";
+import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, 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"];
 /** Extract body content after frontmatter closing delimiter, or null if none. */
@@ -245,6 +246,7 @@ export async function handleImportClaude(ctx, scope) {
                 body = preserved;
         }
         await saveFile(path, `---\n${frontmatter}---${body}`);
+        clearGSDPreferencesCache();
     };
     await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
 }
@@ -264,6 +266,7 @@ export async function handlePrefsMode(ctx, scope) {
     }
     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");
@@ -1626,7 +1629,15 @@ export async function writePreferencesFile(path, prefs, ctx, opts) {
     }
     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).length > 0) {
+            const sessionId = ctx.sessionManager?.getSessionId?.();
+            if (sessionId)
+                clearSessionModelOverride(sessionId);
+        }
         await ctx.waitForIdle();
         await ctx.reload();
         if (opts?.notifyOnSave !== false) {
@@ -1742,6 +1753,7 @@ export async function ensurePreferencesFile(path, ctx, scope) {
             return;
         }
         await saveFile(path, template);
+        clearGSDPreferencesCache();
         ctx.ui.notify(`Created ${scope} GSD skill preferences at ${path}`, "info");
     }
     else {
@@ -1792,6 +1804,7 @@ export async function handleLanguage(args, ctx) {
     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/dist/resources/extensions/gsd/commands-verdict.js

@@ -1,9 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Handles manual milestone validation verdict overrides.
 import { loadFile } from "./files.js";
-import { gsdProjectionRoot, resolveMilestoneFile } from "./paths.js";
+import { resolveMilestoneFile } from "./paths.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
-import { join } from "node:path";
 import { deriveState } from "./state.js";
 import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
@@ -89,17 +88,24 @@ export function parseValidationFile(content) {
     };
 }
 async function loadExistingValidation(basePath, milestoneId) {
+    // 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 = join(gsdProjectionRoot(canonicalBase), "milestones", milestoneId, `${milestoneId}-VALIDATION.md`);
-    const canonicalContent = await loadFile(canonicalValidationPath);
-    if (canonicalContent) {
-        return { content: canonicalContent, source: canonicalValidationPath };
+    const canonicalValidationPath = resolveMilestoneFile(canonicalBase, milestoneId, "VALIDATION");
+    if (canonicalValidationPath) {
+        const canonicalContent = await loadFile(canonicalValidationPath);
+        if (canonicalContent) {
+            return { content: canonicalContent, source: canonicalValidationPath };
+        }
     }
-    const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
-    if (validationPath && validationPath !== canonicalValidationPath) {
-        const content = await loadFile(validationPath);
-        if (content)
-            return { content, source: validationPath };
+    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);
     const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -0,0 +1,172 @@
+// Project/App: gsd-pi
+// File Purpose: gsd-core ↔ gsd-pi compatibility marker (`.gsd/.compat.json`).
+//
+// Records per-projection content hashes so the ADR-017 reconcile pipeline can
+// distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
+// (drift to import). gsd-core is oblivious to this file and ignores it.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Current marker schema version. Bump on breaking format changes + migrate. */
+export const COMPAT_MARKER_SCHEMA = 2;
+/** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
+export const EMPTY_MARKER = {
+    schema: COMPAT_MARKER_SCHEMA,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: false, layout: null, projections: {}, passthrough: {} },
+    piVersion: "",
+};
+export function compatMarkerPath(basePath) {
+    return join(basePath, ".gsd", ".compat.json");
+}
+/**
+ * Normalize markdown content before hashing so cosmetic differences (trailing
+ * whitespace, CRLF) don't produce false-positive drift. Conservative: only
+ * transforms that are provably round-trippable through gsd-pi's projection.
+ */
+export function normalizeForHash(content) {
+    return content.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+}
+export function computeProjectionSha(content) {
+    return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
+}
+/**
+ * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
+ * projection as external on next reconcile). A malformed marker is quarantined
+ * to `.compat.json.bad-<ts>` (never overwrite without backup) then returns
+ * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
+ * to act on a future format we don't understand).
+ */
+export function readCompatMarker(basePath) {
+    const path = compatMarkerPath(basePath);
+    if (!existsSync(path))
+        return emptyMarker();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return emptyMarker();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        quarantine(basePath, raw);
+        return emptyMarker();
+    }
+    if (!isValidMarker(parsed)) {
+        quarantine(basePath, raw);
+        return emptyMarker();
+    }
+    // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
+    // the optional `planning` field; treat its absence as planning-inactive so
+    // existing PR #802 users upgrade transparently. (A future schema 3 would
+    // need an explicit migration here; for now anything that passes isValidMarker
+    // is safe to read.)
+    if (!parsed.planning) {
+        parsed.planning = { active: false, layout: null, projections: {}, passthrough: {} };
+    }
+    return parsed;
+}
+/**
+ * Fresh deep copy of EMPTY_MARKER. Callers mutate the returned `projections`
+ * object (e.g. repair refreshes an entry), so a shallow copy would share the
+ * reference and pollute the module constant across calls. Always deep-copy.
+ */
+function emptyMarker() {
+    return {
+        schema: EMPTY_MARKER.schema,
+        lastWriter: EMPTY_MARKER.lastWriter,
+        lastProjectedAt: EMPTY_MARKER.lastProjectedAt,
+        projections: {},
+        planning: { active: false, layout: null, projections: {}, passthrough: {} },
+        piVersion: EMPTY_MARKER.piVersion,
+    };
+}
+/**
+ * Write the marker atomically (write-temp then rename) so a crash mid-write
+ * can't leave a half-written file that next startup would quarantine.
+ */
+export function writeCompatMarker(basePath, marker) {
+    const path = compatMarkerPath(basePath);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+    renameSync(tmp, path);
+}
+function quarantine(basePath, raw) {
+    const path = compatMarkerPath(basePath);
+    const badPath = `${path}.bad-${Date.now()}`;
+    try {
+        mkdirSync(dirname(badPath), { recursive: true });
+        try {
+            renameSync(path, badPath);
+        }
+        catch {
+            writeFileSync(badPath, raw, "utf-8");
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Best-effort: if we can't quarantine, leave the original in place — next
+        // read will quarantine. Never throw out of marker I/O.
+    }
+}
+function isValidProjectionEntry(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const e = x;
+    if (typeof e.sha !== "string")
+        return false;
+    if (!Array.isArray(e.entities) || !e.entities.every((s) => typeof s === "string"))
+        return false;
+    return true;
+}
+function isValidProjectionMap(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    for (const v of Object.values(x)) {
+        if (!isValidProjectionEntry(v))
+            return false;
+    }
+    return true;
+}
+function isValidPlanningMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const p = x;
+    if (typeof p.active !== "boolean")
+        return false;
+    if (p.layout !== null &&
+        !["flat-phases", "multi-milestone", "legacy-milestone-dir"].includes(p.layout)) {
+        return false;
+    }
+    if (!isValidProjectionMap(p.projections))
+        return false;
+    if (!isValidProjectionMap(p.passthrough))
+        return false;
+    return true;
+}
+function isValidMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const m = x;
+    if (m.lastWriter !== "gsd-pi")
+        return false;
+    if (typeof m.schema !== "number")
+        return false;
+    if (typeof m.lastProjectedAt !== "string")
+        return false;
+    if (typeof m.piVersion !== "string")
+        return false;
+    if (!isValidProjectionMap(m.projections))
+        return false;
+    // planning is optional; when present, must validate.
+    if (m.planning !== undefined && !isValidPlanningMarker(m.planning))
+        return false;
+    return true;
+}

package/dist/resources/extensions/gsd/compat/index.js

@@ -0,0 +1,3 @@
+// Project/App: gsd-pi
+// File Purpose: Public exports for the gsd-core compat module.
+export { COMPAT_MARKER_SCHEMA, EMPTY_MARKER, compatMarkerPath, computeProjectionSha, normalizeForHash, readCompatMarker, writeCompatMarker, } from "./compat-marker.js";

package/dist/resources/extensions/gsd/compat/planning-compat.js

@@ -0,0 +1,142 @@
+// Project/App: gsd-pi
+// File Purpose: `.planning/` compat helpers — layout capture and projection sha
+// recording. Parallel to the .gsd/ write-time flush in markdown-renderer.ts.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { computeProjectionSha, readCompatMarker, writeCompatMarker, } from "./compat-marker.js";
+import { logWarning } from "../workflow-logger.js";
+export function isPlanningPassthroughRelPath(relPath) {
+    if (relPath.startsWith("codebase/") || relPath.startsWith("research/"))
+        return true;
+    if (relPath === "config.json")
+        return true;
+    const name = relPath.split("/").pop() ?? relPath;
+    if (name === "PATTERNS.md" || name === "REVIEWS.md")
+        return true;
+    if (name.endsWith("-DISCUSSION-LOG.md"))
+        return true;
+    if (name.endsWith("-RESEARCH.md") && !name.endsWith("-PLAN.md"))
+        return true;
+    return false;
+}
+// Files that gsd-pi creates in .gsd/ at startup and that do not constitute
+// markdown content written by gsd-core. Excluded from the content check so a
+// .planning/-only project that already has a gsd.db (but no milestone markdown)
+// is not mistakenly treated as a coexistence project.
+const KNOWN_NON_CONTENT_FILES = new Set([
+    "gsd.db",
+    "gsd.db-wal",
+    "gsd.db-shm",
+    "completed-units.json",
+]);
+export function gsdTreeHasContent(basePath) {
+    const gsdDir = join(basePath, ".gsd");
+    return (existsSync(gsdDir) &&
+        readdirSync(gsdDir).some((name) => !name.startsWith(".") && !KNOWN_NON_CONTENT_FILES.has(name)));
+}
+export function walkPlanningRelPaths(planningDir, prefix = "") {
+    const paths = [];
+    let entries;
+    try {
+        entries = readdirSync(join(planningDir, prefix), { withFileTypes: true });
+    }
+    catch {
+        return paths;
+    }
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (entry.name === "workstreams")
+                continue;
+            paths.push(...walkPlanningRelPaths(planningDir, rel));
+        }
+        else {
+            paths.push(rel);
+        }
+    }
+    return paths;
+}
+/**
+ * Record freshly written `.planning/` projection files in the compat marker.
+ */
+export function applyPlanningProjectionWrites(basePath, writes) {
+    if (writes.length === 0)
+        return;
+    const marker = readCompatMarker(basePath);
+    if (!marker.planning) {
+        marker.planning = { active: true, layout: null, projections: {}, passthrough: {} };
+    }
+    marker.planning.active = true;
+    for (const write of writes) {
+        const abs = join(basePath, ".planning", write.relPath);
+        if (!existsSync(abs))
+            continue;
+        const entry = {
+            sha: computeProjectionSha(readFileSync(abs, "utf-8")),
+            entities: write.entities,
+        };
+        const map = write.passthrough ? marker.planning.passthrough : marker.planning.projections;
+        map[write.relPath] = entry;
+    }
+    marker.lastWriter = "gsd-pi";
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(basePath, marker);
+}
+/**
+ * Capture-on-first-read: infer `.planning/` layout from disk, import content
+ * into the DB so gsd-pi's projection reflects gsd-core's tree instead of
+ * overwriting it, then activate the compat marker. Projection shas are seeded
+ * by drift repair / write-time hooks — not from raw disk here.
+ *
+ * Must only be called when !dryRun — it writes both the DB and the marker.
+ */
+export async function capturePlanningCompatIfNeeded(basePath, options) {
+    if (options?.dryRun)
+        return;
+    const planningDir = join(basePath, ".planning");
+    if (!existsSync(planningDir))
+        return;
+    const marker = readCompatMarker(basePath);
+    if (marker.planning?.active && marker.planning.layout)
+        return;
+    // First encounter: parse layout, import content into the DB, then activate the
+    // marker. When `.gsd/` already exists (coexistence), import from disk via
+    // migrateHierarchyToDb and do not call writeGSDDirectory — reconcile runs
+    // external-markdown-edit before external-planning-edit and must not destroy
+    // gsd-core `.gsd/` edits before that pipeline can see them. Planning-only
+    // projects materialize `.gsd/` from the parsed tree first, then import.
+    const { parsePlanningDirectory } = await import("../migrate/parser.js");
+    const { detectPlanningLayout } = await import("../migrate/layout-detect.js");
+    const parsed = await parsePlanningDirectory(planningDir);
+    const layout = detectPlanningLayout(parsed);
+    if (!layout)
+        return;
+    // Import into the DB. Dynamic imports break the module-init cycle
+    // (planning-compat ← reconcile ← state ← md-importer). Matches the import
+    // pattern in repairExternalPlanningEdit.
+    try {
+        const { migrateHierarchyToDb } = await import("../md-importer.js");
+        const { invalidateStateCache } = await import("../state.js");
+        if (!gsdTreeHasContent(basePath)) {
+            const { transformToGSD } = await import("../migrate/transformer.js");
+            const { writeGSDDirectory } = await import("../migrate/writer.js");
+            const gsdProject = transformToGSD(parsed);
+            await writeGSDDirectory(gsdProject, basePath);
+        }
+        migrateHierarchyToDb(basePath);
+        invalidateStateCache();
+    }
+    catch (e) {
+        logWarning("reconcile", `planning DB import failed on initial capture — reconcile may overwrite gsd-core content: ${e.message}`);
+    }
+    // Activate the marker. Leave projections/passthrough empty: the next
+    // writePlanningDirectory → applyPlanningProjectionWrites call will seed
+    // accurate SHAs from the normalized output rather than the raw gsd-core files.
+    const freshMarker = readCompatMarker(basePath);
+    if (!freshMarker.planning) {
+        freshMarker.planning = { active: false, layout: null, projections: {}, passthrough: {} };
+    }
+    freshMarker.planning.active = true;
+    freshMarker.planning.layout = layout;
+    writeCompatMarker(basePath, freshMarker);
+}

package/dist/resources/extensions/gsd/config-overlay.js

@@ -10,11 +10,14 @@ import { matchesKey, Key, truncateToWidth } from "@gsd/pi-tui";
 import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, loadProjectGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, resolveDynamicRoutingConfig, resolveEffectiveProfile, resolveModelWithFallbacksForUnit, resolveAutoSupervisorConfig, } from "./preferences.js";
 const DEFAULT_WIDGET_MODE = "small";
-function collectConfigSections() {
+function collectConfigSections(options) {
     const sections = [];
     const globalPrefs = loadGlobalGSDPreferences();
-    const projectPrefs = loadProjectGSDPreferences();
-    const effective = loadEffectiveGSDPreferences();
+    const projectPrefs = loadProjectGSDPreferences(options?.basePath);
+    const loadOpts = options?.availableModelIds
+        ? { availableModelIds: options.availableModelIds, preferredModelId: options.preferredModelId }
+        : undefined;
+    const effective = loadEffectiveGSDPreferences(options?.basePath, loadOpts);
     const prefs = effective?.preferences;
     // ─── Sources ─────────────────────────────────────────────────────────
     sections.push({
@@ -43,7 +46,7 @@ function collectConfigSections() {
     ];
     const modelRows = [];
     for (const [label, unitType] of unitTypes) {
-        const resolved = resolveModelWithFallbacksForUnit(unitType);
+        const resolved = resolveModelWithFallbacksForUnit(unitType, options?.basePath, options?.availableModelIds, options?.preferredModelId);
         if (resolved) {
             let val = resolved.primary;
             if (resolved.fallbacks.length > 0) {
@@ -203,8 +206,8 @@ function collectConfigSections() {
     return sections;
 }
 // ─── Plain Text Formatter (headless/RPC fallback) ─────────────────────────
-export function formatConfigText() {
-    const sections = collectConfigSections();
+export function formatConfigText(options) {
+    const sections = collectConfigSections(options);
     const lines = ["GSD Configuration\n"];
     let maxLabel = 0;
     for (const section of sections) {
@@ -233,11 +236,11 @@ export class GSDConfigOverlay {
     cachedWidth;
     scrollOffset = 0;
     disposed = false;
-    constructor(tui, theme, onClose) {
+    constructor(tui, theme, onClose, options) {
         this.tui = tui;
         this.theme = theme;
         this.onClose = onClose;
-        this.sections = collectConfigSections();
+        this.sections = collectConfigSections(options);
     }
     invalidate() {
         this.cachedLines = undefined;