@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

package/src/resources/extensions/gsd/db/writers/status.ts

@@ -19,11 +19,18 @@ import { getDbOrNull } from "../engine.js";
 import { GSDError, GSD_STALE_STATE } from "../../errors.js";
 import { isClosedStatus } from "../../status-guards.js";
 
-/** A single row-level status write, discriminated by entity (the faces' arity). */
+/**
+ * A single row-level status write, discriminated by entity (the faces' arity).
+ *
+ * preserveCompletion (#1291): when true, an existing non-null completed_at on the
+ * row is kept rather than overwritten. Mirrors the task upsert's guard so a
+ * markdown re-import cannot re-stamp an already-complete slice/milestone with the
+ * current import time — the DB row is strictly richer than the plan.
+ */
 export type StatusTransition =
-  | { entity: "task"; milestoneId: string; sliceId: string; taskId: string; status: string; completedAt?: string | null }
-  | { entity: "slice"; milestoneId: string; sliceId: string; status: string; completedAt?: string | null }
-  | { entity: "milestone"; milestoneId: string; status: string; completedAt?: string | null };
+  | { entity: "task"; milestoneId: string; sliceId: string; taskId: string; status: string; completedAt?: string | null; preserveCompletion?: boolean }
+  | { entity: "slice"; milestoneId: string; sliceId: string; status: string; completedAt?: string | null; preserveCompletion?: boolean }
+  | { entity: "milestone"; milestoneId: string; status: string; completedAt?: string | null; preserveCompletion?: boolean };
 
 function requireDb() {
   const db = getDbOrNull();
@@ -44,15 +51,19 @@ function requireDb() {
 export function applyStatusTransition(t: StatusTransition): void {
   const db = requireDb();
   const completedAt = t.completedAt ?? null;
+  const preserve = t.preserveCompletion ? 1 : 0;
 
   switch (t.entity) {
     case "task":
       db.prepare(
-        `UPDATE tasks SET status = :status, completed_at = :completed_at
+        `UPDATE tasks SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND tasks.completed_at IS NOT NULL
+                               THEN tasks.completed_at ELSE :completed_at END
          WHERE milestone_id = :milestone_id AND slice_id = :slice_id AND id = :id`,
       ).run({
         ":status": t.status,
         ":completed_at": completedAt,
+        ":preserve_completion": preserve,
         ":milestone_id": t.milestoneId,
         ":slice_id": t.sliceId,
         ":id": t.taskId,
@@ -61,11 +72,14 @@ export function applyStatusTransition(t: StatusTransition): void {
 
     case "slice":
       db.prepare(
-        `UPDATE slices SET status = :status, completed_at = :completed_at
+        `UPDATE slices SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND slices.completed_at IS NOT NULL
+                               THEN slices.completed_at ELSE :completed_at END
          WHERE milestone_id = :milestone_id AND id = :id`,
       ).run({
         ":status": t.status,
         ":completed_at": completedAt,
+        ":preserve_completion": preserve,
         ":milestone_id": t.milestoneId,
         ":id": t.sliceId,
       });
@@ -80,8 +94,11 @@ export function applyStatusTransition(t: StatusTransition): void {
         );
       }
       db.prepare(
-        `UPDATE milestones SET status = :status, completed_at = :completed_at WHERE id = :id`,
-      ).run({ ":status": t.status, ":completed_at": completedAt, ":id": t.milestoneId });
+        `UPDATE milestones SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND milestones.completed_at IS NOT NULL
+                               THEN milestones.completed_at ELSE :completed_at END
+         WHERE id = :id`,
+      ).run({ ":status": t.status, ":completed_at": completedAt, ":preserve_completion": preserve, ":id": t.milestoneId });
       return;
     }
   }

package/src/resources/extensions/gsd/db-base-schema.ts

@@ -245,6 +245,34 @@ export function createBaseSchemaObjects(db: DbAdapter, hooks: BaseSchemaHooks):
     )
   `);
 
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_briefs (
+      id TEXT PRIMARY KEY,
+      milestone_id TEXT NOT NULL DEFAULT '',
+      slice_id TEXT NOT NULL DEFAULT '',
+      task_id TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_brief_findings (
+      brief_id TEXT NOT NULL,
+      finding_id TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'blocking',
+      description TEXT NOT NULL DEFAULT '',
+      required_fix TEXT NOT NULL DEFAULT '',
+      verification_commands TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'pending',
+      evidence TEXT NOT NULL DEFAULT '',
+      decision_ref TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (brief_id, finding_id),
+      FOREIGN KEY (brief_id) REFERENCES rework_briefs(id)
+    )
+  `);
+
   db.exec(`
     CREATE TABLE IF NOT EXISTS assessments (
       path TEXT PRIMARY KEY,
@@ -367,6 +395,8 @@ export function createBaseSchemaObjects(db: DbAdapter, hooks: BaseSchemaHooks):
 
   db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_active ON tasks(milestone_id, slice_id, status)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_slices_active ON slices(milestone_id, status)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)");

package/src/resources/extensions/gsd/db-migration-steps.ts

@@ -462,3 +462,35 @@ export function applyMigrationV22QualityGateRepair(db: DbAdapter, hooks: Migrati
   ensureColumn(db, "quality_gates", "scope", "ALTER TABLE quality_gates ADD COLUMN scope TEXT NOT NULL DEFAULT 'slice'");
   ensureColumn(db, "assessments", "scope", "ALTER TABLE assessments ADD COLUMN scope TEXT NOT NULL DEFAULT ''");
 }
+
+
+export function applyMigrationV30ReworkBriefs(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_briefs (
+      id TEXT PRIMARY KEY,
+      milestone_id TEXT NOT NULL DEFAULT '',
+      slice_id TEXT NOT NULL DEFAULT '',
+      task_id TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_brief_findings (
+      brief_id TEXT NOT NULL,
+      finding_id TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'blocking',
+      description TEXT NOT NULL DEFAULT '',
+      required_fix TEXT NOT NULL DEFAULT '',
+      verification_commands TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'pending',
+      evidence TEXT NOT NULL DEFAULT '',
+      decision_ref TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (brief_id, finding_id),
+      FOREIGN KEY (brief_id) REFERENCES rework_briefs(id)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
+}

package/src/resources/extensions/gsd/db-schema-metadata.ts

@@ -19,8 +19,11 @@ export function ensureColumn(db: DbAdapter, table: string, column: string, ddl:
 }
 
 export function getCurrentSchemaVersion(db: DbAdapter): number {
+  // MAX(version) on an empty table returns a row whose value is NULL —
+  // treat that (and any non-numeric value) as version 0, not NULL-as-number.
   const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
-  return row ? (row["v"] as number) : 0;
+  const v = row?.["v"];
+  return typeof v === "number" ? v : 0;
 }
 
 export function recordSchemaVersion(db: DbAdapter, version: number): void {

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -128,7 +128,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - Two equivalent ways to set it: inline as `models.<phase>.thinking`, or as a separate `thinking:` block keyed by phase. For the same phase, the inline value wins over the block; project preferences win over global; a phase that's unset inherits via the same sibling chain as `models` (e.g. `discuss → planning`).
   - If no thinking is configured for a phase, the session level (set via `/model`) is used, exactly as before — this is fully backward-compatible.
   - `execute-task` (code-writing) has a measured reasoning floor of `medium`: at lower levels models stop planning edits and thrash on file re-reads. The floor applies to the session/default path. An **explicit** `execution` thinking level bypasses the floor and is honored verbatim (with a one-time advisory) — set `execution: low` deliberately if you want it.
-  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` is only honored by select model families.
+  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` support is model-dependent; current examples include OpenAI Codex Max models and Claude Sonnet 5 on Amazon Bedrock.
 
 - `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`.
 
@@ -357,6 +357,28 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `planning_subagents`: object — project-local widening for read-only planning subagent dispatch. Supported unit keys are `plan-milestone` and `plan-slice`; each has:
+  - `allowed`: string[] — additional planning-safe agents for that unit.
+
+  Agents must already be classified by GSD as read-only planning specialists: `mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the global read-only registry, and agents not listed for the active unit.
+
+  Example:
+
+  ```yaml
+  planning_subagents:
+    plan-milestone:
+      allowed:
+        - scout
+        - planner
+        - security
+    plan-slice:
+      allowed:
+        - scout
+        - planner
+        - reviewer
+        - security
+  ```
+
   **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
 
 - `experimental`: opt-in experimental features. All features here are **off by default** — you must explicitly set each one to `true` to enable it. Features in this block may change or be removed without a deprecation cycle while in experimental status. Keys:
@@ -482,13 +504,13 @@ Inline form — thinking pinned alongside the model:
 version: 1
 models:
   planning:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: xhigh
   execution:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: low      # explicit → bypasses the execute-task medium floor
   validation:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: high
 ---
 ```

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -15,13 +15,13 @@ import {
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import {
-  buildTaskFileName,
   gsdProjectionRoot,
   gsdRoot,
   resolveGsdPathContract,
   resolveMilestoneFile,
   resolveMilestonePath,
   resolveSliceFile,
+  resolveTaskFile,
 } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -95,6 +95,25 @@ function reportCheckboxDbStatusDivergence(
   });
 }
 
+function bareDuplicateMilestoneId(milestoneId: string): string | null {
+  const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+  return match?.[1]?.toUpperCase() ?? null;
+}
+
+function checkboxDbStatusMilestoneIds(basePath: string, milestoneIds: string[]): string[] {
+  if (!hasFlatPhaseLayout(basePath)) return milestoneIds;
+
+  // Flat-phase directories are keyed by phase number. A restored
+  // M003-xxxxxx row alongside M003 is a stale duplicate for the same
+  // phases/03-* projection, so checking both can compare DB status against two
+  // competing PLAN files and report a persistent false divergence.
+  const allIds = new Set(milestoneIds.map((id) => id.toUpperCase()));
+  return milestoneIds.filter((milestoneId) => {
+    const bareId = bareDuplicateMilestoneId(milestoneId);
+    return !bareId || !allIds.has(bareId);
+  });
+}
+
 function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
   for (const milestoneId of milestoneIds) {
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -208,10 +227,8 @@ function resolveFlatPhaseArtifactDiskPath(basePath: string, row: ArtifactRow): s
   if (!artifactType) return null;
 
   if (row.slice_id && row.task_id) {
-    const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
-    if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir)) return null;
-    const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
-    return existsSync(candidate) ? candidate : null;
+    const candidate = resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, artifactType);
+    return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
   }
 
   const candidate = row.slice_id
@@ -436,7 +453,9 @@ function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, a
 
 function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
   const issuePath = artifactPathRelativeToGsd(row.path);
-  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) &&
+    (hasPresentFlatPhaseReplacement(basePath, row, artifactRows) ||
+      hasPresentMilestonesReplacement(basePath, row, artifactRows));
 }
 
 function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
@@ -809,7 +828,11 @@ export async function checkEngineHealth(
   // block doctor.
   try {
     if (isDbAvailable()) {
-      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+      checkProjectionCheckboxDbStatus(
+        basePath,
+        checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)),
+        issues,
+      );
     }
   } catch {
     // Non-fatal: checkbox-vs-DB divergence check must never block doctor

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

@@ -65,8 +65,12 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
 const SERVER_RE = /internal(?: server)?[ _-]?error|server[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+// Provider adapters throw this when an upstream stop reason reaches Pi before
+// the adapter knows how to map it. Keep the match scoped so plain "unknown"
+// runtime errors still pause for inspection instead of being retried forever.
+const PROVIDER_STOP_REASON_RE = /unhandled stop reason:\s*(?:abort|unknown)\b/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|\babort\b|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
@@ -103,7 +107,7 @@ const UNSUPPORTED_MODEL_SCOPE_RE = /\b(?:account|plan|tier|subscription)\b/i;
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)
- *  6. Connection (terminated, ECONNREFUSED, EPIPE, other side closed)
+ *  6. Connection (terminated, abort/unknown stop reason, ECONNREFUSED, EPIPE, other side closed)
  *  7. Model error (400 invalid argument / payload rejected for this model)
  *  8. Unknown
  */
@@ -163,6 +167,13 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "rate-limit", retryAfterMs: delayMs };
   }
 
+  // Provider stop-reason adapter gaps are usually request/stream failures from
+  // the current model. Treat the scoped adapter message as fallback-eligible,
+  // but keep generic unknown errors on the indefinite pause path.
+  if (PROVIDER_STOP_REASON_RE.test(errorMsg)) {
+    return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
   // 3. Network errors — same-model retry candidate
   if (NETWORK_RE.test(errorMsg)) {
     // Exclude if also matches permanent signals (already handled above for

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

@@ -111,6 +111,7 @@ export const EXEC_DEFAULTS = {
     "LOGNAME",
     "TMPDIR",
     "NODE_OPTIONS",
+    "NODE_PATH",
     "PYTHONPATH",
     "PYTHONIOENCODING",
   ] as const,

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -6,7 +6,13 @@ import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSyn
 import { join } from "node:path";
 
 import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { deleteArtifactsByPathPrefix, getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import {
+  deleteArtifactByPath,
+  deleteArtifactsByPathPrefix,
+  getAllMilestones,
+  getArtifactsByPathPrefix,
+  getMilestoneSlices,
+} from "./gsd-db.js";
 import { migrateFromMarkdown } from "./md-importer.js";
 import { countDbHierarchy } from "./migration-auto-check.js";
 import { logWarning } from "./workflow-logger.js";
@@ -14,6 +20,7 @@ import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 import {
   canonicalPhaseDirName,
   dirIsContentBearingLegacyMilestone,
+  gsdProjectionRoot,
   milestonesDir,
   resolveMilestonePath,
 } from "./paths.js";
@@ -83,6 +90,40 @@ function expectedPhaseDirs(basePath: string): string[] {
   );
 }
 
+/**
+ * Return the most-recent existing `.gsd-backups/migrate-<ts>/` snapshot, or null.
+ *
+ * The flat-phase migration can re-fire on later dispatches when the legacy
+ * `.gsd/milestones/` layout reappears (e.g. a marker-key mismatch re-triggers a
+ * whole-tree re-import — issue #1292). The DB was already reconciled from that
+ * tree before the backup step runs, so re-snapshotting an identical legacy tree
+ * on every dispatch only leaks a fresh `migrate-<ts>/` directory each time. When
+ * a prior snapshot already exists we reuse it as the rollback fallback instead
+ * of creating a duplicate, bounding the accumulation to one recovery copy.
+ */
+function existingMigrateBackup(basePath: string): string | null {
+  const backupRoot = join(basePath, ".gsd-backups");
+  if (!existsSync(backupRoot)) return null;
+  try {
+    let latest: { path: string; mtimeMs: number } | null = null;
+    for (const entry of readdirSync(backupRoot)) {
+      if (!entry.startsWith("migrate-")) continue;
+      const dirPath = join(backupRoot, entry);
+      try {
+        const st = statSync(dirPath);
+        if (!st.isDirectory()) continue;
+        if (!hasLegacyMilestoneSubdirs(dirPath)) continue;
+        if (!latest || st.mtimeMs > latest.mtimeMs) latest = { path: dirPath, mtimeMs: st.mtimeMs };
+      } catch {
+        // Non-fatal: skip unreadable entries.
+      }
+    }
+    return latest?.path ?? null;
+  } catch {
+    return null;
+  }
+}
+
 function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
   if (!existsSync(dirPath)) return false;
   try {
@@ -94,10 +135,76 @@ function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
   }
 }
 
+function backupFlatProjectionIfPresent(basePath: string, phasesPath: string, backupDir: string): void {
+  if (!existsSync(phasesPath)) return;
+  const phaseBackupDir = join(backupDir, "__phases");
+  try {
+    mkdirSync(backupDir, { recursive: true });
+    if (existsSync(phaseBackupDir)) {
+      removePathWithRetries(phaseBackupDir);
+    }
+    fsOps.cpSync(phasesPath, phaseBackupDir, { recursive: true, force: true });
+  } catch (err) {
+    logWarning("migration", `flat-phase projection backup failed: ${(err as Error).message}`);
+    throw err;
+  }
+}
+
+function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
+  const phaseBackupDir = join(backupDir, "__phases");
+  return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
+}
+
+function removeFlatProjectionBackup(backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  try {
+    removePathWithRetries(phaseBackupDir);
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${(err as Error).message}`,
+    );
+  }
+}
+
+function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+  try {
+    if (existsSync(phasesPath)) {
+      removePathWithRetries(phasesPath);
+    }
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    cpSync(phaseBackupDir, phasesPath, { recursive: true });
+  } catch (restoreErr) {
+    logWarning(
+      "migration",
+      `rollback: could not restore ${LAYOUT_SEGMENTS.level1}/ from backup: ${(restoreErr as Error).message}`,
+    );
+  }
+}
+
+function pruneStaleFlatPhaseArtifactRows(basePath: string): number {
+  const projectionRoot = gsdProjectionRoot(basePath);
+  let pruned = 0;
+  for (const row of getArtifactsByPathPrefix(`${LAYOUT_SEGMENTS.level1}/`)) {
+    if (existsSync(join(projectionRoot, row.path))) continue;
+    const staleTaskPlan = row.artifact_type.toUpperCase() === "PLAN" && Boolean(row.task_id);
+    const skippedEmptyArtifact = row.full_content.trim() === "";
+    if (!staleTaskPlan && !skippedEmptyArtifact) continue;
+    deleteArtifactByPath(row.path);
+    pruned++;
+  }
+  return pruned;
+}
+
 function rollbackPartialMigration(
   basePath: string,
   backupDir: string,
   migratingPath?: string,
+  backupCreatedThisRun = true,
 ): void {
   // Remove the partially-written phases/ dir.
   try {
@@ -113,7 +220,8 @@ function rollbackPartialMigration(
   // preserved migrating tree (the sole surviving data source) and must never be
   // removed here. Deleting the backup after a successful rollback keeps the gate
   // from leaking one .gsd-backups/migrate-<ts>/ per session_start.
-  const isDisposableBackup = Boolean(backupDir) && backupDir !== migratingPath;
+  const isDisposableBackup =
+    Boolean(backupDir) && backupDir !== migratingPath && backupCreatedThisRun;
   const cleanupBackup = (): void => {
     if (!isDisposableBackup || !existsSync(backupDir)) return;
     try {
@@ -131,11 +239,16 @@ function rollbackPartialMigration(
   try {
     if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
       movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
+      restoreFlatProjectionFromBackup(basePath, backupDir);
       cleanupBackup();
       return;
     }
     if (existsSync(backupDir)) {
-      cpSync(backupDir, milestonesPath, { recursive: true });
+      cpSync(backupDir, milestonesPath, {
+        recursive: true,
+        filter: (src) => !isInsideFlatProjectionBackup(backupDir, src),
+      });
+      restoreFlatProjectionFromBackup(basePath, backupDir);
       cleanupBackup();
     }
     if (migratingPath && existsSync(migratingPath)) {
@@ -244,16 +357,34 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
   }
 
   let backupDir = migratingPath;
+  let backupCreatedThisRun = false;
   if (!resumingInterrupted) {
-    // 2. Backup (only reached when the DB has rows and migration will proceed)
-    const ts = Date.now();
-    backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
-    try {
-      mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
-      cpSync(milestonesPath, backupDir, { recursive: true });
-    } catch (err) {
-      logWarning("migration", `flat-phase migration backup failed: ${(err as Error).message}`);
-      throw err;
+    // 2. Backup (only reached when the DB has rows and migration will proceed).
+    // migrateFromMarkdown above already reconciled the legacy tree into the DB,
+    // so its content is safely persisted. If a prior successful migration
+    // already snapshotted the legacy tree, a re-fire of this gate (issue #1292:
+    // marker-key mismatch re-importing the whole tree at dispatch boundaries)
+    // must not leak a fresh .gsd-backups/migrate-<ts>/ every dispatch. Treat it
+    // as a marker-refresh re-projection: reuse the existing snapshot as the
+    // rollback fallback instead of creating a duplicate.
+    const priorBackup = existingMigrateBackup(basePath);
+    if (priorBackup) {
+      backupDir = priorBackup;
+      logWarning(
+        "migration",
+        `flat-phase migration re-fired; reusing existing backup ${priorBackup} instead of re-snapshotting (issue #1292)`,
+      );
+    } else {
+      const ts = Date.now();
+      backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+      try {
+        mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+        cpSync(milestonesPath, backupDir, { recursive: true });
+        backupCreatedThisRun = true;
+      } catch (err) {
+        logWarning("migration", `flat-phase migration backup failed: ${(err as Error).message}`);
+        throw err;
+      }
     }
 
     if (existsSync(migratingPath)) {
@@ -269,15 +400,35 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       logWarning("migration", `failed to rename legacy milestones/ before render: ${(err as Error).message}`);
       throw err;
     }
+  } else {
+    const priorBackup = existingMigrateBackup(basePath);
+    if (priorBackup) {
+      backupDir = priorBackup;
+    } else {
+      const ts = Date.now();
+      backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+      try {
+        mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+        cpSync(migratingPath, backupDir, { recursive: true });
+        backupCreatedThisRun = true;
+      } catch (err) {
+        logWarning(
+          "migration",
+          `flat-phase migration backup failed during resume: ${(err as Error).message}`,
+        );
+        throw err;
+      }
+    }
   }
 
   // Clear any stale or partially-rendered flat projection before this run
   // writes. Verification below checks the current DB render, not leftovers.
   try {
+    backupFlatProjectionIfPresent(basePath, phasesPath, backupDir);
     removePathWithRetries(phasesPath);
   } catch (err) {
     logWarning("migration", `failed to clear stale phases/ before render: ${(err as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 
@@ -299,7 +450,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
     }
   } catch (err) {
     logWarning("migration", `flat-phase render failed: ${(err as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 
@@ -309,7 +460,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "migration",
       `flat-phase render had ${renderResult.errors.length} error(s): ${renderResult.errors.join("; ")}`,
     );
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw new Error(
       `flat-phase migration render failed: ${renderResult.errors.slice(0, 3).join("; ")}`,
     );
@@ -322,7 +473,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "migration",
       `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`,
     );
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw new Error("flat-phase migration verification failed: missing rendered phase directories");
   }
   if (db.slices > 0 && renderResult.rendered === 0) {
@@ -330,17 +481,20 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "migration",
       "flat-phase migration verification failed: render produced no artifacts for populated DB",
     );
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw new Error("flat-phase migration verification failed: no artifacts rendered");
   }
 
   // 6. Verified — prune legacy artifact rows now that renderAllFromDb has
-  // re-inserted flat-phase rows for artifacts that still have files.
+  // re-inserted flat-phase rows for artifacts that still have files. Also
+  // prune flat-phase rows whose files the renderer intentionally no longer
+  // materializes, such as task PLAN files and empty-content artifacts.
   try {
     deleteArtifactsByPathPrefix("milestones/");
+    pruneStaleFlatPhaseArtifactRows(basePath);
   } catch (err) {
     logWarning("migration", `flat-phase migration could not prune legacy artifact rows: ${(err as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 
@@ -353,4 +507,5 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
     );
   }
+  removeFlatProjectionBackup(backupDir);
 }