@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

package/dist/resources/extensions/gsd/flat-phase-migration.js

@@ -9,16 +9,62 @@ import { migrateFromMarkdown } from "./md-importer.js";
 import { countDbHierarchy } from "./migration-auto-check.js";
 import { logWarning } from "./workflow-logger.js";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
-import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+import { canonicalPhaseDirName, dirIsContentBearingLegacyMilestone, milestonesDir, resolveMilestonePath, } from "./paths.js";
 const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+const RETRYABLE_FS_ERROR_CODES = new Set(["EPERM", "EBUSY", "ENOTEMPTY"]);
+const RM_RETRY_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 };
+let fsOps = { cpSync, renameSync, rmSync };
+export function _setFlatPhaseMigrationFsOpsForTest(overrides) {
+    const previous = fsOps;
+    fsOps = { ...fsOps, ...overrides };
+    return () => {
+        fsOps = previous;
+    };
+}
 function legacyMigratingPath(basePath) {
     return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
 }
+function removePathWithRetries(path) {
+    fsOps.rmSync(path, { recursive: true, force: true, maxRetries: RM_RETRY_OPTIONS.maxRetries, retryDelay: RM_RETRY_OPTIONS.retryDelay });
+}
+function isRetryableFsError(err) {
+    const code = err?.code;
+    return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+function movePathWithCopyDeleteFallback(src, dst) {
+    try {
+        fsOps.renameSync(src, dst);
+        return;
+    }
+    catch (err) {
+        if (!isRetryableFsError(err))
+            throw err;
+    }
+    try {
+        fsOps.cpSync(src, dst, { recursive: true, force: true });
+        removePathWithRetries(src);
+    }
+    catch (fallbackErr) {
+        if (existsSync(src) && existsSync(dst)) {
+            try {
+                removePathWithRetries(dst);
+            }
+            catch {
+                // Leave the original error intact; the next run can pre-clean dst.
+            }
+        }
+        throw fallbackErr;
+    }
+}
+function expectedPhaseDirs(basePath) {
+    return getAllMilestones().map((milestone) => resolveMilestonePath(basePath, milestone.id) ??
+        join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)));
+}
 function hasLegacyMilestoneSubdirs(dirPath) {
     if (!existsSync(dirPath))
         return false;
     try {
-        return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+        return readdirSync(dirPath).some((e) => statSync(join(dirPath, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(dirPath, e)));
     }
     catch {
         return false;
@@ -26,19 +72,24 @@ function hasLegacyMilestoneSubdirs(dirPath) {
 }
 function rollbackPartialMigration(basePath, backupDir, migratingPath) {
     // Remove the partially-written phases/ dir.
-    rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+    try {
+        removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
+    }
+    catch (removeErr) {
+        logWarning("migration", `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${removeErr.message}`);
+    }
     // Restore milestones/ — prefer renaming the preserved migrating copy back.
     const milestonesPath = join(basePath, ".gsd", "milestones");
     try {
         if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
-            renameSync(migratingPath, milestonesPath);
+            movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
             return;
         }
         if (existsSync(backupDir)) {
             cpSync(backupDir, milestonesPath, { recursive: true });
         }
         if (migratingPath && existsSync(migratingPath)) {
-            rmSync(migratingPath, { recursive: true, force: true });
+            removePathWithRetries(migratingPath);
         }
     }
     catch (restoreErr) {
@@ -59,6 +110,51 @@ export function needsFlatPhaseMigration(basePath) {
     // Resume an interrupted migration where the legacy tree was renamed aside.
     return hasLegacyMilestoneSubdirs(legacyMigratingPath(basePath));
 }
+/** Retention window before flat-phase migration backups are auto-pruned. */
+export const FLAT_PHASE_BACKUP_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Remove stale flat-phase migration backups after the retention window.
+ * Only runs when migration is complete (.gsd/phases/ exists, legacy layout gone).
+ * Returns the number of migrate-* directories removed.
+ */
+export function pruneStaleFlatPhaseBackups(basePath) {
+    if (needsFlatPhaseMigration(basePath))
+        return 0;
+    const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+    if (!existsSync(phasesPath))
+        return 0;
+    const backupRoot = join(basePath, ".gsd-backups");
+    if (!existsSync(backupRoot))
+        return 0;
+    const now = Date.now();
+    let removed = 0;
+    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 (now - st.mtimeMs < FLAT_PHASE_BACKUP_RETENTION_MS)
+                continue;
+            rmSync(dirPath, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Non-fatal: leave backup for manual recovery.
+        }
+    }
+    try {
+        if (readdirSync(backupRoot).length === 0) {
+            rmSync(backupRoot, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Non-fatal.
+    }
+    return removed;
+}
 /**
  * Migrate from legacy nested .gsd/milestones/ to flat-phase .gsd/phases/.
  *
@@ -101,20 +197,29 @@ export async function migrateToFlatPhase(basePath) {
             logWarning("migration", `flat-phase migration backup failed: ${err.message}`);
             throw err;
         }
+        if (existsSync(migratingPath)) {
+            removePathWithRetries(migratingPath);
+        }
         // 3. Rename legacy tree aside before rendering so path resolvers target
         // phases/ instead of writing back into the nested milestones/ layout.
         // Keep the full tree on disk until render+verify succeed (unlike rmSync).
         try {
-            renameSync(milestonesPath, migratingPath);
+            movePathWithCopyDeleteFallback(milestonesPath, migratingPath);
         }
         catch (err) {
             logWarning("migration", `failed to rename legacy milestones/ before render: ${err.message}`);
             throw err;
         }
     }
-    else {
-        // Interrupted run: clear any partial phases/ projection before retrying.
-        rmSync(phasesPath, { recursive: true, force: true });
+    // Clear any stale or partially-rendered flat projection before this run
+    // writes. Verification below checks the current DB render, not leftovers.
+    try {
+        removePathWithRetries(phasesPath);
+    }
+    catch (err) {
+        logWarning("migration", `failed to clear stale phases/ before render: ${err.message}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw err;
     }
     // 4. Render flat-phase from DB
     let renderResult;
@@ -146,20 +251,11 @@ export async function migrateToFlatPhase(basePath) {
         throw new Error(`flat-phase migration render failed: ${renderResult.errors.slice(0, 3).join("; ")}`);
     }
     const db = countDbHierarchy();
-    let renderedDirCount = 0;
-    try {
-        // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
-        // whose dirs start with "100-slug" are counted correctly.
-        renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
-            .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
-    }
-    catch {
-        // phases/ doesn't exist or is unreadable — same as zero dirs
-    }
-    if (db.milestones > 0 && renderedDirCount !== db.milestones) {
-        logWarning("migration", `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`);
+    const missingPhaseDirs = expectedPhaseDirs(basePath).filter((phaseDir) => !existsSync(phaseDir));
+    if (db.milestones > 0 && missingPhaseDirs.length > 0) {
+        logWarning("migration", `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`);
         rollbackPartialMigration(basePath, backupDir, migratingPath);
-        throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+        throw new Error("flat-phase migration verification failed: missing rendered phase directories");
     }
     if (db.slices > 0 && renderResult.rendered === 0) {
         logWarning("migration", "flat-phase migration verification failed: render produced no artifacts for populated DB");
@@ -168,7 +264,7 @@ export async function migrateToFlatPhase(basePath) {
     }
     // 6. Verified — remove the renamed legacy tree (backup already on disk).
     try {
-        rmSync(migratingPath, { recursive: true, force: true });
+        removePathWithRetries(migratingPath);
     }
     catch (err) {
         logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);

package/dist/resources/extensions/gsd/git-service.js

@@ -16,7 +16,7 @@ import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
-import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "./repository-registry.js";
 import { isGsdGitignored } from "./gitignore.js";
 import { detectWorktreeName, } from "./worktree.js";
 import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
@@ -208,6 +208,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -1023,25 +1024,78 @@ export function handleTurnGitActionError(action, err) {
         error: errorWithStreams.stderr?.trim() || errorWithStreams.message || getErrorMessage(err),
     };
 }
+export function isRepositoryDirty(repoRoot) {
+    try {
+        return runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+    }
+    catch {
+        // Fallback preserves legacy behavior if explicit status probing fails.
+        return nativeHasChanges(repoRoot);
+    }
+}
 function collectRepositoryDirtyStatus(basePath) {
     const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
     const dirtyByRepository = {};
+    const registeredRoots = new Set(registry.repositories.map((repo) => resolve(repo.root)));
     for (const repo of registry.repositories) {
+        dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
+    }
+    for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+        const dirty = isRepositoryDirty(repoRoot);
+        if (!dirty)
+            continue;
+        const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
+        const label = `${relPath} (undeclared)`;
+        dirtyByRepository[label] = true;
+        logWarning("engine", `undeclared dirty nested git repo ${relPath}; declare it under workspace.repositories or commit manually`, { file: "git-service.ts" });
+    }
+    return dirtyByRepository;
+}
+const UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH = 4;
+const UNDECLARED_NESTED_REPO_SKIP_DIRS = new Set([
+    ".git",
+    ".gsd",
+    ".gsd-worktrees",
+    "node_modules",
+    "dist",
+    "dist-test",
+]);
+function findUndeclaredNestedGitRepositories(projectRoot, registeredRoots) {
+    const found = [];
+    function visit(dir, depth) {
+        if (depth >= UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH)
+            return;
+        let entries;
         try {
-            dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
+            entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            // Fallback preserves legacy behavior if explicit status probing fails.
-            dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (UNDECLARED_NESTED_REPO_SKIP_DIRS.has(entry.name))
+                continue;
+            const child = join(dir, entry.name);
+            const childRoot = resolve(child);
+            const hasGitDir = existsSync(join(child, ".git"));
+            const isRegistered = registeredRoots.has(childRoot);
+            if (hasGitDir && !isRegistered) {
+                found.push(childRoot);
+                continue;
+            }
+            visit(child, depth + 1);
         }
     }
-    return dirtyByRepository;
+    visit(projectRoot, 0);
+    return found;
 }
 function runPerRepositoryCommitAction(args) {
     const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
-    const repoIds = args.targetRepositories?.length ? args.targetRepositories : ["project"];
+    const repoIds = args.targetRepositories?.length ? args.targetRepositories : defaultRepositoryTargets(registry);
     const gitPrefs = preferences?.git ?? {};
     const commitMessages = {};
     const commitErrors = {};
@@ -1109,8 +1163,7 @@ export function runTurnGitAction(args) {
                 skippedRepositories: repoCommitResult.skippedRepositories,
             };
         }
-        const primaryMessage = repoCommitResult.commitMessages[args.targetRepositories?.[0] ?? "project"]
-            ?? Object.values(repoCommitResult.commitMessages)[0];
+        const primaryMessage = Object.values(repoCommitResult.commitMessages)[0];
         return {
             action: args.action,
             status: "ok",

package/dist/resources/extensions/gsd/gitignore.js

@@ -22,8 +22,9 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  * With external state (symlink), these are a no-op in most cases,
  * but retained for backwards compatibility during migration.
  */
-const GSD_RUNTIME_PATTERNS = [
+export const GSD_RUNTIME_PATTERNS = [
     ".gsd-worktrees/",
+    ".gsd-backups/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -48,6 +49,8 @@ const BASELINE_PATTERNS = [
     ".gsd",
     // Worktree container sibling — NOT covered by the ".gsd" pattern above.
     ".gsd-worktrees/",
+    // Flat-phase migration snapshots — NOT covered by the ".gsd" pattern above.
+    ".gsd-backups/",
     ".gsd-id",
     ".mcp.json",
     ".bg-shell/",

package/dist/resources/extensions/gsd/guidance.js

@@ -151,6 +151,7 @@ const DOCTOR_FIX_HINTS = {
     state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
     state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
     projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
+    artifact_user_content_missing: "Doctor cannot recreate user-authored content from the database. Re-run `/gsd discuss` for CONTEXT artifacts or `/gsd auto` for RESEARCH artifacts in that milestone.",
     uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };
 export function doctorFixHint(code) {

package/dist/resources/extensions/gsd/guided-flow-queue.js

@@ -274,21 +274,28 @@ function capExistingMilestonesContext(sections, cap = QUEUE_EXISTING_MILESTONES_
     if (fullContext.length <= cap)
         return fullContext;
     const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
-    const compactSections = sections.map(compactSectionForQueueBudget);
+    const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
     const selected = [];
-    for (let i = 0; i < sections.length; i++) {
-        const withFullSection = [
-            ...selected,
-            sections[i],
-            ...compactSections.slice(i + 1),
-            notice,
-        ].join(QUEUE_CONTEXT_SECTION_SEPARATOR);
-        selected.push(withFullSection.length <= cap ? sections[i] : compactSections[i]);
+    for (const section of sections) {
+        const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+        if (candidate.length <= cap) {
+            selected.push(section);
+            continue;
+        }
+        break;
+    }
+    if (selected.length === sections.length) {
+        return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
     }
-    const capped = [...selected, notice].join(QUEUE_CONTEXT_SECTION_SEPARATOR);
-    if (capped.length <= cap)
-        return capped;
-    return `${capped.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+    const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+    const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (hybrid.length <= cap)
+        return hybrid;
+    const compact = sections.map(compactSectionForQueueBudget);
+    const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (compactContext.length <= cap)
+        return compactContext;
+    return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
 }
 function compactSectionForQueueBudget(section) {
     const lines = section.split("\n");

package/dist/resources/extensions/gsd/guided-flow.js

@@ -20,7 +20,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -53,6 +53,7 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { countPlanMilestoneRoadmapSlices } from "./artifact-verification.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
@@ -78,20 +79,57 @@ export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
 // The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
-// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+// state.ts remain the default for non-scope-specific units.
 /**
  * Scope-based overload of verifyExpectedArtifact.
  * Uses scope.workspace.projectRoot as the authoritative base path, making
  * the check immune to cwd-drift and worktree-path divergence.
  */
 export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
+    if (unitId === scope.milestoneId &&
+        (unitType === "discuss-milestone" || unitType === "plan-milestone")) {
+        // Layout-aware scope paths use resolveMilestoneFile; clear stale dir listings
+        // primed before discuss/plan wrote CONTEXT.md or ROADMAP.md (see checkAutoStartAfterDiscuss).
+        clearPathCache();
+    }
+    if (unitId === scope.milestoneId &&
+        unitType === "discuss-milestone") {
+        const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+        return path ? existsSync(path) : false;
+    }
+    if (unitId === scope.milestoneId && unitType === "plan-milestone") {
+        const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+        return verifyScopedPlanMilestoneArtifact(path, unitType, unitId);
+    }
     return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
 }
+function verifyScopedPlanMilestoneArtifact(path, unitType, unitId) {
+    if (!path || !existsSync(path))
+        return false;
+    try {
+        const roadmapContent = readFileSync(path, "utf-8");
+        if (countPlanMilestoneRoadmapSlices(roadmapContent) === 0) {
+            logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${path}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 /**
  * Scope-based overload of resolveExpectedArtifactPath.
  * Returns the canonical absolute path (or null) using the scope's projectRoot.
  */
 export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
+    if (unitId === scope.milestoneId) {
+        if (unitType === "discuss-milestone")
+            return scope.contextFile();
+        if (unitType === "plan-milestone")
+            return scope.roadmapFile();
+    }
     return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 async function runQuickTaskChoice(ctx, pi) {

package/dist/resources/extensions/gsd/json-persistence.js

@@ -56,6 +56,26 @@ export function saveJsonFile(filePath, data) {
         // Non-fatal — don't let persistence failures break operation
     }
 }
+/**
+ * Save a JSON file atomically using compact serialization.
+ *
+ * Intended for machine-only ledgers where pretty-printing has no consumer.
+ * Keeps the same write-tmp-rename safety and non-fatal error behavior as
+ * saveJsonFile.
+ */
+export function saveJsonFileCompact(filePath, data) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        // Use randomized tmp suffix to prevent concurrent-write data loss
+        const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(data) + "\n", "utf-8");
+        renameSync(tmp, filePath);
+        // No cleanup needed — renameSync atomically removes tmp on success
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break operation
+    }
+}
 /**
  * Write a JSON file atomically (write to .tmp, then rename).
  * Creates parent directories as needed. Non-fatal on error.

package/dist/resources/extensions/gsd/key-manager.js

@@ -19,6 +19,7 @@ export const PROVIDER_REGISTRY = [
     // must be in the canonical registry so all consumers see the same catalog.
     // See: https://github.com/open-gsd/gsd-pi/issues/4541
     { id: "claude-code", label: "Claude Code CLI", category: "llm", authMode: "externalCli" },
+    { id: "cursor-agent", label: "Cursor Agent", category: "llm", envVar: "CURSOR_API_KEY", authMode: "externalCli" },
     { id: "openai", label: "OpenAI", category: "llm", envVar: "OPENAI_API_KEY", prefixes: ["sk-"], dashboardUrl: "platform.openai.com/api-keys" },
     { id: "github-copilot", label: "GitHub Copilot", category: "llm", envVar: "GITHUB_TOKEN", authMode: "browserOAuth" },
     { id: "openai-codex", label: "ChatGPT Plus/Pro (Codex)", category: "llm", authMode: "browserOAuth" },

package/dist/resources/extensions/gsd/knowledge-backfill.js

@@ -24,8 +24,8 @@ import { logWarning } from "./workflow-logger.js";
  * - Idempotent (per-row): each migrated memory carries
  *   `structured_fields.sourceKnowledgeId = "<P|L>NNN"`. Rows whose ID is
  *   already present in the memory store are skipped.
- * - Best-effort: never throws. Logs and returns 0 on failure so a broken
- *   backfill cannot block agent startup.
+ * - Best-effort: never throws. Failed memory inserts are logged and skipped;
+ *   setup/read failures log and return 0 so backfill cannot block startup.
  * - Rules (K###) are intentionally skipped — they remain manually maintained
  *   in `KNOWLEDGE.md` per ADR-013.
  *
@@ -56,15 +56,22 @@ export function backfillKnowledgeToMemories(basePath) {
             const matchPattern = `%"sourceKnowledgeId":"${synth.id}"%`;
             if (checkExisting.get({ ":pattern": matchPattern }))
                 continue;
-            const id = createMemory({
-                category: synth.category,
-                content: synth.content,
-                scope: synth.scope,
-                confidence: 0.85,
-                structuredFields: synth.structuredFields,
-            });
-            if (id)
-                written += 1;
+            try {
+                const id = createMemory({
+                    category: synth.category,
+                    content: synth.content,
+                    scope: synth.scope,
+                    confidence: 0.85,
+                    structuredFields: synth.structuredFields,
+                });
+                if (id)
+                    written += 1;
+            }
+            catch (rowErr) {
+                const message = rowErr instanceof Error ? rowErr.message : String(rowErr);
+                logWarning("knowledge-backfill", `KNOWLEDGE.md -> memories backfill skipped ${synth.id}: ${message}`);
+                continue;
+            }
         }
         return written;
     }

package/dist/resources/extensions/gsd/layout-policy.js

@@ -40,8 +40,10 @@ export function dbPath(basePath) {
  * Used by the renderer to derive the phase number from the DB's milestone_id.
  */
 export function milestoneIdToPhaseNum(milestoneId) {
-    // No $ anchor: accepts bare (M012) and team-suffixed (M012-abc123) IDs.
+    // No $ anchor: accepts bare (M012), team-suffixed (M012-abc123), and legacy numeric IDs.
     const m = milestoneId.match(/^M0*(\d+)/i);
+    if (!m && /^\d+$/.test(milestoneId))
+        return Number.parseInt(milestoneId, 10);
     return m ? Number.parseInt(m[1], 10) : 1;
 }
 /** Team-mode suffix from milestone ids like M001-abc123. */