@opengsd/gsd-pi 1.3.0-dev.72e3af2a → 1.3.0-dev.738160b9

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, insertAssessment, isDbAvailable, transaction, } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk, } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
 import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
 import { relMilestoneFile, resolveSliceFile } from "./paths.js";
@@ -144,6 +144,8 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
         });
     }
     for (const slice of slices) {
+        if (isDeferredStatus(slice.status))
+            continue;
         if (!isClosedStatus(slice.status)) {
             return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
         }

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

@@ -190,7 +190,7 @@ export async function handleAutoCommand(trimmed, ctx, pi) {
             }
             return true;
         }
-        await pauseAuto(ctx, pi);
+        await pauseAuto(ctx, pi, undefined, { abortActiveTurn: true });
         return true;
     }
     if (trimmed === "rate" || trimmed.startsWith("rate ")) {

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

@@ -1164,7 +1164,7 @@ async function configureContextCodebase(ctx, prefs) {
         cm.observation_mask_turns = maskTurns;
     else if (maskTurns === "clear")
         delete cm.observation_mask_turns;
-    const thresh = await promptNumber(ctx, "Compaction threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
+    const thresh = await promptNumber(ctx, "Soft context warning threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
     if (thresh !== undefined && thresh !== "clear")
         cm.compaction_threshold_percent = thresh;
     else if (thresh === "clear")

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

@@ -83,7 +83,7 @@ function formatThresholdLines() {
     }
     const compactionThreshold = prefs?.context_management?.compaction_threshold_percent;
     if (typeof compactionThreshold === "number") {
-        lines.push(`Compaction: ${Math.round(compactionThreshold * 100)}%`);
+        lines.push(`Soft context warning: ${Math.round(compactionThreshold * 100)}%`);
     }
     return lines;
 }

package/dist/resources/extensions/gsd/db/engine.js

@@ -19,7 +19,7 @@ import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
 import { createDbConnectionCache } from "../db-connection-cache.js";
 import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
 import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "../db-migration-steps.js";
-import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "../db-memory-fts-schema.js";
+import { isMemoriesFtsAvailableSchema, rebuildMemoriesFtsSchemaOnce, tryCreateMemoriesFtsSchema, } from "../db-memory-fts-schema.js";
 import { createDbOpenState } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
 import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
@@ -101,6 +101,9 @@ function initSchema(db, fileBacked, dbPath) {
         throw err;
     }
     migrateSchema(db, dbPath);
+    rebuildMemoriesFtsSchemaOnce(db, {
+        onRebuildFailed: (message) => logWarning("db", message),
+    });
 }
 export function _isLikelyWslDrvFsPathForTest(dbPath) {
     if (!dbPath || process.platform !== "linux")

package/dist/resources/extensions/gsd/db-memory-fts-schema.js

@@ -1,5 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 function formatFtsUnavailableError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
@@ -54,3 +56,35 @@ export function isMemoriesFtsAvailableSchema(db) {
         return false;
     }
 }
+export function rebuildMemoriesFtsSchemaOnce(db, options = {}) {
+    if (!isMemoriesFtsAvailableSchema(db))
+        return;
+    createRuntimeKvTableV25(db);
+    const marker = db.prepare("SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key").get({ ":key": MEMORIES_FTS_REBUILT_KEY });
+    if (marker)
+        return;
+    const now = new Date().toISOString();
+    try {
+        db.exec("BEGIN");
+        db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+        db.prepare(`INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES ('global', '', :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`).run({
+            ":key": MEMORIES_FTS_REBUILT_KEY,
+            ":value_json": JSON.stringify(now),
+            ":updated_at": now,
+        });
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // Best effort: leave startup alive and retry the rebuild on next open.
+        }
+        options.onRebuildFailed?.(`FTS5 rebuild failed: ${err.message}`);
+    }
+}

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

@@ -94,7 +94,7 @@ const POLICY = {
     gsd_plan_task: {
         toolName: "gsd_plan_task",
         verdict: "no",
-        rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+        rationale: "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
     },
 };
 function resolveCanonical(name) {

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

@@ -273,10 +273,10 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `audit_unified.enabled`: boolean — dual-write unified audit envelope events. Default: `true`.
   - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow. Default: `true`.
 
-- `context_management`: configures context hygiene for auto-mode sessions. Keys:
+- `context_management`: configures context hygiene for auto-mode sessions. In step mode, the configurable threshold is a soft warning; automatic session re-rooting happens only at the fixed 90% hard context boundary. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.
-  - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.60`.
+  - `compaction_threshold_percent`: number — show a soft context warning at this fraction of the context window (0.5-0.95). Lower values warn earlier so operators can compact manually before drift accumulates. Default: `0.60`.
   - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`.
 
 - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,11 +1,115 @@
-import { existsSync, statSync } from "node:fs";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, isMemoriesFtsAvailable, _getAdapter, } from "./gsd-db.js";
+import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { parsePlan } from "./parsers-legacy.js";
+function relativeFile(basePath, filePath) {
+    return relative(basePath, filePath).split("\\").join("/");
+}
+function reportCheckboxDbStatusDivergence(issues, basePath, filePath, scope, unitId, status, checkboxDone) {
+    const dbDone = isClosedStatus(status);
+    if (checkboxDone === dbDone)
+        return;
+    issues.push({
+        severity: "error",
+        code: "checkbox_db_status_divergence",
+        scope,
+        unitId,
+        message: `${scope === "slice" ? "Slice" : "Task"} ${unitId} is ${dbDone ? "closed" : "open"} in the database (status: ${status}) but the markdown checkbox is ${checkboxDone ? "checked" : "unchecked"}.`,
+        file: relativeFile(basePath, filePath),
+        fixable: false,
+    });
+}
+function checkProjectionCheckboxDbStatus(basePath, milestoneIds, issues) {
+    for (const milestoneId of milestoneIds) {
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        const slices = getMilestoneSlices(milestoneId);
+        if (roadmapPath && existsSync(roadmapPath)) {
+            try {
+                const roadmap = readFileSync(roadmapPath, "utf-8");
+                const sliceDoneById = new Map(parseRoadmapSlices(roadmap).map((entry) => [entry.id, entry.done]));
+                for (const slice of slices) {
+                    const checkboxDone = sliceDoneById.get(slice.id);
+                    if (checkboxDone === undefined)
+                        continue;
+                    reportCheckboxDbStatusDivergence(issues, basePath, roadmapPath, "slice", `${milestoneId}/${slice.id}`, slice.status, checkboxDone);
+                }
+            }
+            catch {
+                // Non-fatal — checkbox drift diagnostics must never block doctor.
+            }
+        }
+        for (const slice of slices) {
+            const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+            if (!planPath || !existsSync(planPath))
+                continue;
+            try {
+                const plan = readFileSync(planPath, "utf-8");
+                // parsePlan reads the authoritative task checkboxes (the flat-phase
+                // <tasks> block / ## Tasks section), so a stray task-style checkbox
+                // line elsewhere in PLAN.md (e.g. a Must-Haves or Verification bullet
+                // above <tasks>) can no longer hide real drift or fake a divergence.
+                const taskDoneById = new Map(parsePlan(plan).tasks.map((entry) => [entry.id, entry.done]));
+                for (const task of getSliceTasks(milestoneId, slice.id)) {
+                    const checkboxDone = taskDoneById.get(task.id);
+                    if (checkboxDone === undefined)
+                        continue;
+                    reportCheckboxDbStatusDivergence(issues, basePath, planPath, "task", `${milestoneId}/${slice.id}/${task.id}`, task.status, checkboxDone);
+                }
+            }
+            catch {
+                // Non-fatal — checkbox drift diagnostics must never block doctor.
+            }
+        }
+    }
+}
+function isClearedByMilestoneShellProjectionFlush(basePath, issue, reRenderedMilestoneIds) {
+    if (issue.code !== "checkbox_db_status_divergence")
+        return false;
+    if (issue.scope !== "slice")
+        return false;
+    const milestoneId = issue.unitId.split("/")[0] ?? "";
+    if (!reRenderedMilestoneIds.has(milestoneId))
+        return false;
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath || !issue.file)
+        return false;
+    return issue.file === relativeFile(basePath, roadmapPath);
+}
+function artifactExistsOnDisk(basePath, artifactPath) {
+    if (isAbsolute(artifactPath))
+        return existsSync(artifactPath);
+    return [
+        join(gsdProjectionRoot(basePath), artifactPath),
+        join(gsdRoot(basePath), artifactPath),
+    ].some((candidate) => existsSync(candidate));
+}
+function artifactUnitId(row) {
+    if (!row.milestone_id)
+        return "project";
+    if (row.slice_id && row.task_id)
+        return `${row.milestone_id}/${row.slice_id}/${row.task_id}`;
+    if (row.slice_id)
+        return `${row.milestone_id}/${row.slice_id}`;
+    return row.milestone_id;
+}
+function artifactScope(row) {
+    if (row.task_id)
+        return "task";
+    if (row.slice_id)
+        return "slice";
+    if (row.milestone_id)
+        return "milestone";
+    return "project";
+}
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -23,6 +127,30 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     try {
         if (isDbAvailable()) {
             const adapter = _getAdapter();
+            try {
+                if (isMemoriesFtsAvailable(adapter)) {
+                    const runtimeKv = adapter
+                        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='runtime_kv'")
+                        .get();
+                    const marker = runtimeKv
+                        ? adapter.prepare("SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key").get({ ":key": MEMORIES_FTS_REBUILT_KEY })
+                        : undefined;
+                    if (!marker) {
+                        issues.push({
+                            severity: "warning",
+                            code: "memories_fts_rebuild_missing",
+                            scope: "project",
+                            unitId: "project",
+                            message: `Memory full-text index exists but runtime_kv has no ${MEMORIES_FTS_REBUILT_KEY} marker. The index may be stale or incomplete, so memory search can silently degrade to the LIKE fallback.`,
+                            file: ".gsd/gsd.db",
+                            fixable: false,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Non-fatal — memory FTS health check failed
+            }
             // a. Orphaned tasks (task.slice_id points to non-existent slice)
             try {
                 const orphanedTasks = adapter
@@ -172,7 +300,33 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
             catch {
                 // Non-fatal — completed-milestone reopen check failed
             }
-            // f. Completion artifacts disagree with open DB hierarchy rows.
+            // f. Artifact rows reference files that no longer exist on disk.
+            try {
+                const artifactRows = adapter
+                    .prepare(`SELECT path, artifact_type, milestone_id, slice_id, task_id
+             FROM artifacts
+             WHERE path != ''
+             ORDER BY path`)
+                    .all();
+                for (const row of artifactRows) {
+                    if (artifactExistsOnDisk(basePath, row.path))
+                        continue;
+                    const unitId = artifactUnitId(row);
+                    issues.push({
+                        severity: "error",
+                        code: "artifact_file_missing",
+                        scope: artifactScope(row),
+                        unitId,
+                        message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+                        file: row.path,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — artifact file existence check failed
+            }
+            // g. Completion artifacts disagree with open DB hierarchy rows.
             try {
                 const rows = adapter
                     .prepare(`SELECT a.path, a.artifact_type, a.milestone_id, a.slice_id, a.task_id, a.imported_at,
@@ -189,6 +343,8 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     .all();
                 const seen = new Set();
                 for (const row of rows) {
+                    if (!artifactExistsOnDisk(basePath, row.path))
+                        continue;
                     const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
                     if (!isAfter(row.imported_at, reopenAt))
                         continue;
@@ -223,9 +379,24 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     catch {
         // Non-fatal — DB constraint checks failed entirely
     }
+    // Checkbox-vs-DB divergence detection runs before projection drift auto-fix
+    // so stale re-renders cannot overwrite manually edited markdown first. Runs
+    // inside its own try/catch: getAllMilestones / getMilestoneSlices /
+    // getSliceTasks issue prepared queries that can throw on a corrupt or locked
+    // DB, and like every other DB-touching check here this diagnostic must never
+    // block doctor.
+    try {
+        if (isDbAvailable()) {
+            checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+        }
+    }
+    catch {
+        // Non-fatal: checkbox-vs-DB divergence check must never block doctor
+    }
     // ── Projection drift detection ──────────────────────────────────────────
     // If the DB is available, check whether markdown projections are stale
     // relative to the event log and re-render them.
+    const reRenderedMilestoneIds = [];
     try {
         if (isDbAvailable()) {
             const eventLogPath = workflowEventLogPath(basePath);
@@ -241,6 +412,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                         try {
                             await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
+                            reRenderedMilestoneIds.push(milestone.id);
                         }
                         catch {
                             // Non-fatal — projection re-render failed
@@ -252,6 +424,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                         try {
                             await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
+                            reRenderedMilestoneIds.push(milestone.id);
                         }
                         catch {
                             // Non-fatal — projection re-render failed
@@ -264,4 +437,19 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     catch {
         // Non-fatal — projection drift check must never block doctor
     }
+    if (reRenderedMilestoneIds.length > 0) {
+        const reRendered = new Set(reRenderedMilestoneIds);
+        for (let i = issues.length - 1; i >= 0; i--) {
+            const issue = issues[i];
+            // flushWorkflowProjections re-renders milestone shell projections (not
+            // slice PLAN.md files), so only clear stale ROADMAP checkbox diagnostics.
+            if (isClearedByMilestoneShellProjectionFlush(basePath, issue, reRendered)) {
+                issues.splice(i, 1);
+                continue;
+            }
+            if (issue.code === "artifact_file_missing" && issue.file && artifactExistsOnDisk(basePath, issue.file)) {
+                issues.splice(i, 1);
+            }
+        }
+    }
 }

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -387,6 +387,9 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
                 missing.push(".gsd-worktrees/");
             }
+            if (!existingLines.has(".gsd-backups/") && !existingLines.has(".gsd-backups")) {
+                missing.push(".gsd-backups/");
+            }
             if (!hasBlanketIgnore) {
                 missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
             }

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -11,7 +11,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
+import { getShellConfig, killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
 // SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
 // (shell.ts) — the single source of truth for the graceful-kill timing ladder —
@@ -60,7 +60,13 @@ function clampTimeout(request, opts) {
 function resolveCommand(runtime) {
     switch (runtime) {
         case "bash":
-            return { cmd: "bash", args: ["-c"] };
+            try {
+                const { shell, args } = getShellConfig();
+                return { cmd: shell, args };
+            }
+            catch {
+                return { cmd: "bash", args: ["-c"] };
+            }
         case "node":
             return { cmd: process.execPath, args: ["-e"] };
         case "python":

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

@@ -59,6 +59,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/.
  *

package/dist/resources/extensions/gsd/git-service.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/",
@@ -1027,6 +1028,7 @@ 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) {
         try {
             dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
@@ -1036,8 +1038,63 @@ function collectRepositoryDirtyStatus(basePath) {
             dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
         }
     }
+    for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+        let dirty = false;
+        try {
+            dirty = runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+        }
+        catch {
+            dirty = nativeHasChanges(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 {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            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);
+        }
+    }
+    visit(projectRoot, 0);
+    return found;
+}
 function runPerRepositoryCommitAction(args) {
     const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);

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/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/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;
     }