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

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

@@ -142,23 +142,53 @@ function getActiveDecisions(): DecisionRow[] {
 }
 
 /**
- * True when a memory row has a `structured_fields` JSON payload containing
- * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
- * `backfillDecisionsToMemories` so the scanner is consistent with the
- * backfill's idempotency check.
+ * Source IDs already present in memory `structured_fields`. Collected with one
+ * pass over the memories table so the scanner does not perform a non-indexable
+ * LIKE probe for every decision and KNOWLEDGE.md row.
  */
-function memoryHasSourceMarker(markerKey: string, value: string): boolean {
-  if (!isDbAvailable()) return false;
+interface MemorySourceMarkers {
+  decisionIds: Set<string>;
+  knowledgeIds: Set<string>;
+}
+
+function emptyMemorySourceMarkers(): MemorySourceMarkers {
+  return { decisionIds: new Set(), knowledgeIds: new Set() };
+}
+
+function getMemorySourceMarkers(): MemorySourceMarkers {
+  const markers = emptyMemorySourceMarkers();
+  if (!isDbAvailable()) return markers;
   const adapter = _getAdapter();
-  if (!adapter) return false;
+  if (!adapter) return markers;
+  try {
+    const rows = adapter
+      .prepare("SELECT structured_fields FROM memories WHERE structured_fields IS NOT NULL")
+      .all() as Array<Record<string, unknown>>;
+    for (const row of rows) {
+      collectMemorySourceMarker(markers, row["structured_fields"]);
+    }
+  } catch {
+    return markers;
+  }
+  return markers;
+}
+
+function collectMemorySourceMarker(markers: MemorySourceMarkers, raw: unknown): void {
+  if (typeof raw !== "string" || raw.length === 0) return;
   try {
-    const pattern = `%"${markerKey}":"${value}"%`;
-    const row = adapter
-      .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
-      .get({ ":pattern": pattern });
-    return row !== undefined;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    const fields = parsed as Record<string, unknown>;
+    const decisionId = fields["sourceDecisionId"];
+    if (typeof decisionId === "string" && decisionId.length > 0) {
+      markers.decisionIds.add(decisionId);
+    }
+    const knowledgeId = fields["sourceKnowledgeId"];
+    if (typeof knowledgeId === "string" && knowledgeId.length > 0) {
+      markers.knowledgeIds.add(knowledgeId);
+    }
   } catch {
-    return false;
+    return;
   }
 }
 
@@ -174,10 +204,14 @@ const SAMPLE_LIMIT = 5;
 export function scanConsolidationGaps(basePath: string): ConsolidationGapReport {
   // ── Decisions ────────────────────────────────────────────────────────
   const decisions = getActiveDecisions();
+  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+  const memorySourceMarkers = decisions.length > 0 || knowledgeRows.length > 0
+    ? getMemorySourceMarkers()
+    : emptyMemorySourceMarkers();
   const decisionSamples: DecisionsSurfaceReport["samples"] = [];
   let decisionMigrated = 0;
   for (const decision of decisions) {
-    if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+    if (memorySourceMarkers.decisionIds.has(decision.id)) {
       decisionMigrated += 1;
       continue;
     }
@@ -190,16 +224,14 @@ export function scanConsolidationGaps(basePath: string): ConsolidationGapReport
   }
 
   // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
-  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
   const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
   const knowledgeSamples: KnowledgeSurfaceReport["samples"] = [];
   let knowledgeMigrated = 0;
   for (const row of knowledgeRows) {
     knowledgeByTable[row.table] += 1;
-    // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
-    // KNOWLEDGE.md backfill. Until that path ships, this check returns
-    // false for every row, which is the honest state of the consolidation.
-    if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+    // KNOWLEDGE.md backfill writes `sourceKnowledgeId`; rows without that
+    // marker are still reported as consolidation gaps.
+    if (memorySourceMarkers.knowledgeIds.has(row.id)) {
       knowledgeMigrated += 1;
       continue;
     }
@@ -264,7 +296,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/memory-relations.ts

@@ -3,7 +3,7 @@
 // Phase 4 companion to memory-store.ts. Edges live in the `memory_relations`
 // table and are created by (a) explicit LINK actions emitted by the memory
 // extractor, or (b) future `/gsd memory link` CLI commands. All writes go
-// through the single-writer gate in `gsd-db.ts`.
+// through typed writer wrappers re-exported by `gsd-db.ts`.
 
 import {
   _getAdapter,

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

@@ -846,12 +846,22 @@ function defaultLedger(): MetricsLedger {
   return { version: 1, projectStartedAt: Date.now(), units: [] };
 }
 
+export const METRICS_LEDGER_KEEP_UNITS = 1500;
+
+function compareUnitsByTime(a: UnitMetrics, b: UnitMetrics): number {
+  return a.finishedAt - b.finishedAt || a.startedAt - b.startedAt;
+}
+
+function keepNewestUnits(units: UnitMetrics[], keepCount = METRICS_LEDGER_KEEP_UNITS): UnitMetrics[] {
+  return units.length > keepCount ? [...units].sort(compareUnitsByTime).slice(-keepCount) : units;
+}
+
 /**
  * Prune the metrics ledger to at most `keepCount` most-recent unit entries.
  *
  * Called by the doctor when the ledger exceeds the bloat threshold.
- * Keeps the newest entries (highest index = most recent) and discards
- * the oldest from the head of the array. Preserves `projectStartedAt`.
+ * Keeps the newest entries by unit timestamps and discards the oldest.
+ * Preserves `projectStartedAt`.
  *
  * Updates both the on-disk file and the in-memory ledger if it is loaded,
  * so the current session sees the pruned state immediately.
@@ -862,11 +872,11 @@ export function pruneMetricsLedger(base: string, keepCount: number): number {
   const disk = loadLedgerFromDisk(base);
   if (!disk || disk.units.length <= keepCount) return 0;
   const removed = disk.units.length - keepCount;
-  disk.units = disk.units.slice(-keepCount);
+  disk.units = keepNewestUnits(disk.units, keepCount);
   saveJsonFile(metricsPath(base), disk);
   // Keep the in-memory ledger in sync if it is loaded for this session.
   if (ledger) {
-    ledger.units = ledger.units.slice(-keepCount);
+    ledger.units = keepNewestUnits(ledger.units, keepCount);
   }
   // Invalidate all scoped ledger cache entries. Prune is rare; clearing the
   // entire map is simpler than tracking which entry belongs to `base`. Without
@@ -1024,12 +1034,14 @@ function saveLedger(base: string, data: MetricsLedger): void {
       // Read current on-disk state and merge with worker's in-memory units.
       // Worker units take precedence on conflict (by finishedAt in deduplicateUnits).
       const onDisk = loadJsonFileOrNull(path, isMetricsLedger);
-      if (onDisk && onDisk.units.length > 0) {
-        const merged = deduplicateUnits([...onDisk.units, ...data.units]);
-        saveJsonFile(path, { ...data, units: merged });
-      } else {
-        saveJsonFile(path, data);
-      }
+      const dataUnits = keepNewestUnits(data.units);
+      const merged =
+        onDisk && onDisk.units.length > 0
+          ? deduplicateUnits([...keepNewestUnits(onDisk.units), ...dataUnits])
+          : dataUnits;
+      merged.sort(compareUnitsByTime);
+      data.units = keepNewestUnits(merged);
+      saveJsonFile(path, data);
     } finally {
       releaseLock(lockPath);
     }
@@ -1040,6 +1052,7 @@ function saveLedger(base: string, data: MetricsLedger): void {
     // to a torn write caused by two writers simultaneously executing the
     // read-merge-write sequence without mutual exclusion.
     logWarning("fs", "saveLedger: lock not acquired — falling back to direct write (no merge)");
+    data.units = keepNewestUnits(data.units);
     saveJsonFile(path, data);
   }
 }

package/src/resources/extensions/gsd/migrate/layout-detect.ts

@@ -0,0 +1,38 @@
+// Project/App: gsd-pi
+// File Purpose: Classify a parsed .planning/ tree into its layout so the
+// round-trip writer can recreate the same structure gsd-core wrote.
+//
+// This extracts the implicit 3-way branch that was buried in transformer.ts
+// transformToGSD (lines 425-467). Priority matches the transformer's if/else
+// chain: legacy-milestone-dir > multi-milestone > flat-phases.
+
+import type { PlanningProject } from "./types.js";
+import type { PlanningLayout } from "../compat/compat-marker.js";
+
+/**
+ * Determine which .planning/ layout a parsed project uses. Returns null when
+ * no layout signal is present (caller decides: treat as inactive or error).
+ *
+ * Priority (must match transformer.ts transformToGSD):
+ *   1. legacy-milestone-dir — milestones/<id>/ contains <id>-phases/ subdirs
+ *      with phase content. Detected when parsed.milestones has any entry with
+ *      non-empty phases.
+ *   2. multi-milestone — ROADMAP.md parsed into milestone sections.
+ *      Detected when roadmap.milestones.length > 0.
+ *   3. flat-phases — ROADMAP.md parsed into checkbox phase lines only.
+ *      Detected when roadmap.phases.length > 0.
+ */
+export function detectPlanningLayout(parsed: PlanningProject): PlanningLayout | null {
+  const hasMilestoneDirectories = parsed.milestones.some(
+    (m) => Object.keys(m.phases).length > 0,
+  );
+  if (hasMilestoneDirectories) return "legacy-milestone-dir";
+
+  const isMultiMilestone = parsed.roadmap !== null && parsed.roadmap.milestones.length > 0;
+  if (isMultiMilestone) return "multi-milestone";
+
+  const hasFlatPhases = parsed.roadmap !== null && parsed.roadmap.phases.length > 0;
+  if (hasFlatPhases) return "flat-phases";
+
+  return null;
+}

package/src/resources/extensions/gsd/migrate/planning-writer.ts

@@ -0,0 +1,259 @@
+// Project/App: gsd-pi
+// File Purpose: DB → .planning/ projection. Parallel to writer.ts (which
+// emits .gsd/). Produces the .planning/ markdown shape that gsd-core reads.
+//
+// Layout policy (spec §4.4): emits the layout recorded in the compat marker.
+// v1 supports flat-phases; multi-milestone and legacy-milestone-dir are stubbed
+// with a clear error until fixtures exist to validate them.
+
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { saveFile } from "../files.js";
+import type { PlanningLayout } from "../compat/compat-marker.js";
+import {
+  applyPlanningProjectionWrites,
+  type PlanningProjectionWrite,
+} from "../compat/planning-compat.js";
+
+export interface PlanningWrittenFiles {
+  paths: string[];
+  layout: PlanningLayout;
+}
+
+function planningRoot(basePath: string): string {
+  return join(basePath, ".planning");
+}
+
+function slugify(title: string, fallback: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return slug || fallback;
+}
+
+function pad(n: number, width = 2): string {
+  return String(n).padStart(width, "0");
+}
+
+/**
+ * Format a roadmap for the flat-phases layout. Mirrors the checkbox line
+ * format that parsers.ts parsePhaseEntry recognizes: `- [x] NN — Title`.
+ */
+function formatPlanningRoadmapFlat(
+  entries: Array<{ number: number; title: string; done: boolean }>,
+): string {
+  const lines = ["# Roadmap", "", "## Phases", ""];
+  for (const e of entries) {
+    const box = e.done ? "[x]" : "[ ]";
+    lines.push(`- ${box} ${pad(e.number)} — ${e.title}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Format STATE.md in gsd-core's phase-progress schema. gsd-pi is authoritative
+ * for status; this is a one-way DB→projection (edits to STATE.md are not
+ * re-imported — see spec §7).
+ */
+function formatPlanningState(
+  activeMilestone: string,
+  totalPhases: number,
+  completedPhases: number,
+): string {
+  const pct = totalPhases === 0 ? 0 : Math.round((completedPhases / totalPhases) * 100);
+  const ts = new Date().toISOString();
+  return [
+    "---",
+    "gsd_state_version: 1.0",
+    `milestone: ${activeMilestone}`,
+    'milestone_name: "milestone"',
+    "status: active",
+    `stopped_at: Phase 01 — in progress`,
+    `last_updated: "${ts}"`,
+    `last_activity: ${ts.slice(0, 10)}`,
+    "progress:",
+    `  total_phases: ${totalPhases}`,
+    `  completed_phases: ${completedPhases}`,
+    `  total_plans: ${totalPhases}`,
+    `  completed_plans: ${completedPhases}`,
+    `  percent: ${pct}`,
+    "---",
+    "",
+    "# Project State",
+    "",
+    "Current Phase: **01**",
+    "Status: **active**",
+    "",
+  ].join("\n");
+}
+
+function formatPlanningProject(title: string): string {
+  return `# ${title}\n`;
+}
+
+/**
+ * Format a phase plan file with the XML-tagged structure parsers.ts
+ * parseOldPlan recognizes: <objective>, <tasks>, <verification>.
+ */
+function formatPlanningPlan(
+  phaseNum: number,
+  planNum: number,
+  title: string,
+  tasks: Array<{ id: string; title: string; estimate?: string }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
+  lines.push("<objective>");
+  lines.push(`${title}.`);
+  lines.push("</objective>");
+  lines.push("");
+  lines.push("<tasks>");
+  for (const t of tasks) {
+    const est = t.estimate ? ` _(${t.estimate})_` : "";
+    lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+  }
+  lines.push("</tasks>");
+  lines.push("");
+  lines.push("<verification>");
+  lines.push("All tasks complete and tests pass.");
+  lines.push("</verification>");
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Project DB state to .planning/ in the recorded layout.
+ * Reads DB directly (canonical source). Writes via saveFile (atomic).
+ *
+ * v1: flat-phases only. Each milestone's slices become sequentially-numbered
+ * phase dirs; each task within a slice becomes a plan file (NN-MM-PLAN.md).
+ */
+export async function writePlanningDirectory(
+  basePath: string,
+  layout: PlanningLayout,
+): Promise<PlanningWrittenFiles> {
+  if (layout !== "flat-phases") {
+    // v1: flat-phases only. multi-milestone and legacy-milestone-dir need
+    // fixtures to validate the reverse-mapping (transformer.ts is non-injective
+    // — three layouts collapse to one .gsd/ shape); stub until then.
+    throw new Error(
+      `writePlanningDirectory: layout "${layout}" not yet supported (v1 supports flat-phases only)`,
+    );
+  }
+
+  const root = planningRoot(basePath);
+  mkdirSync(root, { recursive: true });
+  const paths: string[] = [];
+  const projectionWrites: PlanningProjectionWrite[] = [];
+  const toPlanningRel = (absPath: string): string =>
+    relative(root, absPath).replace(/\\/g, "/");
+
+  const milestones = getAllMilestones();
+  if (milestones.length === 0) {
+    return { paths, layout };
+  }
+
+  // Flat-phases: each slice becomes one phase. Tasks within become plan files.
+  let phaseNum = 0;
+  const roadmapEntries: Array<{ number: number; title: string; done: boolean }> = [];
+
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    for (const slice of slices) {
+      phaseNum++;
+      const phaseSlug = slugify(slice.title || slice.id, slice.id.toLowerCase());
+      const phaseDirName = `${pad(phaseNum)}-${phaseSlug}`;
+      const phaseDir = join(root, "phases", phaseDirName);
+      mkdirSync(phaseDir, { recursive: true });
+
+      const tasks = getSliceTasks(milestone.id, slice.id);
+      const isDone =
+        tasks.length > 0 && tasks.every((t) => t.status === "complete");
+      roadmapEntries.push({
+        number: phaseNum,
+        title: slice.title || slice.id,
+        done: isDone,
+      });
+
+      if (tasks.length === 0) {
+        // Empty phase — write a single placeholder plan so the dir isn't empty.
+        const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
+        await saveFile(
+          planPath,
+          formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []),
+        );
+        paths.push(planPath);
+        projectionWrites.push({
+          relPath: toPlanningRel(planPath),
+          entities: [`${milestone.id}/${slice.id}`],
+        });
+      } else {
+        for (let ti = 0; ti < tasks.length; ti++) {
+          const task = tasks[ti]!;
+          const planNum = ti + 1;
+          const planPath = join(phaseDir, `${pad(phaseNum)}-${pad(planNum)}-PLAN.md`);
+          await saveFile(
+            planPath,
+            formatPlanningPlan(phaseNum, planNum, task.title || task.id, [
+              {
+                id: task.id,
+                title: task.title || task.id,
+                estimate: task.estimate || undefined,
+              },
+            ]),
+          );
+          paths.push(planPath);
+          projectionWrites.push({
+            relPath: toPlanningRel(planPath),
+            entities: [`${milestone.id}/${slice.id}/${task.id}`],
+          });
+        }
+      }
+    }
+  }
+
+  // If no slices produced any phases, write a single empty phase so ROADMAP.md
+  // isn't blank and the layout is still discoverable.
+  if (roadmapEntries.length === 0) {
+    const phaseDirName = `${pad(1)}-milestone`;
+    const phaseDir = join(root, "phases", phaseDirName);
+    mkdirSync(phaseDir, { recursive: true });
+    const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
+    await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0]!.title || milestones[0]!.id, []));
+    paths.push(planPath);
+    projectionWrites.push({
+      relPath: toPlanningRel(planPath),
+      entities: [milestones[0]!.id],
+    });
+    roadmapEntries.push({ number: 1, title: milestones[0]!.title || milestones[0]!.id, done: false });
+  }
+
+  // Root files
+  const milestoneEntities = milestones.map((m) => m.id);
+  const roadmapPath = join(root, "ROADMAP.md");
+  await saveFile(roadmapPath, formatPlanningRoadmapFlat(roadmapEntries));
+  paths.push(roadmapPath);
+  projectionWrites.push({ relPath: toPlanningRel(roadmapPath), entities: milestoneEntities });
+
+  const completedPhases = roadmapEntries.filter((e) => e.done).length;
+  const statePath = join(root, "STATE.md");
+  await saveFile(
+    statePath,
+    formatPlanningState(milestones[0]!.id, roadmapEntries.length, completedPhases),
+  );
+  paths.push(statePath);
+  projectionWrites.push({ relPath: toPlanningRel(statePath), entities: [milestones[0]!.id] });
+
+  const projectPath = join(root, "PROJECT.md");
+  await saveFile(projectPath, formatPlanningProject(milestones[0]!.title || milestones[0]!.id));
+  paths.push(projectPath);
+  projectionWrites.push({ relPath: toPlanningRel(projectPath), entities: [milestones[0]!.id] });
+
+  applyPlanningProjectionWrites(basePath, projectionWrites);
+  return { paths, layout };
+}

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

@@ -7,9 +7,10 @@ import { homedir } from "node:os";
 
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
-import { closeDatabase } from "../gsd-db.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,14 +107,24 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
-  const worktreesDir = join(gsdRoot(targetRoot), "worktrees");
-  if (!existsSync(worktreesDir)) return false;
-  try {
-    return readdirSync(worktreesDir, { withFileTypes: true })
-      .some((entry) => entry.isDirectory() || entry.isFile());
-  } catch {
-    return true;
+  // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+  // migration targets may have .gsd in the external-state layout.
+  const containers = [
+    canonicalWorktreesDir(targetRoot),
+    join(gsdRoot(targetRoot), "worktrees"),
+  ];
+  for (const worktreesDir of containers) {
+    if (!existsSync(worktreesDir)) continue;
+    try {
+      if (readdirSync(worktreesDir, { withFileTypes: true })
+        .some((entry) => entry.isDirectory() || entry.isFile())) {
+        return true;
+      }
+    } catch {
+      return true;
+    }
   }
+  return false;
 }
 
 export async function assertMigrationTargetAvailable(targetRoot: string): Promise<void> {
@@ -144,6 +155,6 @@ export async function assertMigrationTargetAvailable(targetRoot: string): Promis
       );
     }
   } finally {
-    closeDatabase();
+    closeWorkflowDatabase();
   }
 }

package/src/resources/extensions/gsd/migrate-external.ts

@@ -7,12 +7,13 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { gsdRoot, milestonesDir, resolveGsdRootFile } from "./paths.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -159,6 +160,10 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
     }
 
+    // Remove .gsd.migrating once the junction is verified. The git-index cleanup
+    // below is best-effort and does not need the staging copy to survive.
+    rmSync(migratingPath, { recursive: true, force: true });
+
     // Clean the git index — any .gsd/* files tracked before migration now
     // sit behind the symlink and git can't follow it, causing them to show
     // as deleted. Remove them from the index so the working tree stays clean.
@@ -174,9 +179,6 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       // Non-fatal — git may be unavailable or nothing was tracked
     }
 
-    // Remove .gsd.migrating only after symlink is verified and index is clean
-    rmSync(migratingPath, { recursive: true, force: true });
-
     return { migrated: true };
   } catch (err) {
     // Rollback: rename .gsd.migrating back to .gsd
@@ -195,16 +197,57 @@ export function migrateToExternalState(basePath: string): MigrationResult {
   }
 }
 
+export function isCurrentGsdStateIntactForMigratingCleanup(basePath: string): boolean {
+  try {
+    const stateFile = resolveGsdRootFile(basePath, "STATE");
+    const milestonesPath = milestonesDir(basePath);
+    const dbPath = join(gsdRoot(basePath), "gsd.db");
+    const hasDbFile = existsSync(dbPath);
+    const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
+    return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeResolvedPath(p: string): string {
+  const normalized = p.replaceAll("\\", "/").replace(/\/+$/, "");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isLocalGsdExternalStateJunction(basePath: string, localGsd: string): boolean {
+  try {
+    const stat = lstatSync(localGsd);
+    if (!stat.isSymbolicLink()) return false;
+    const resolved = normalizeResolvedPath(realpathSync(localGsd));
+    const resolvedExternal = normalizeResolvedPath(realpathSync(externalGsdRoot(basePath)));
+    return resolved === resolvedExternal;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Recover from a failed migration (`.gsd.migrating` exists).
- * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist.
+ * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist, or removes an
+ * orphaned staging directory when `.gsd` is already a verified external state
+ * junction with intact current state.
  */
 export function recoverFailedMigration(basePath: string): boolean {
   const localGsd = join(basePath, ".gsd");
   const migratingPath = join(basePath, ".gsd.migrating");
 
   if (!existsSync(migratingPath)) return false;
-  if (existsSync(localGsd)) return false; // both exist -- ambiguous, don't touch
+  if (existsSync(localGsd)) {
+    if (!isLocalGsdExternalStateJunction(basePath, localGsd)) return false;
+    if (!isCurrentGsdStateIntactForMigratingCleanup(basePath)) return false;
+    try {
+      rmSync(migratingPath, { recursive: true, force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
   try {
     renameSync(migratingPath, localGsd);