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

package/dist/resources/extensions/gsd/db-workspace.js

@@ -1,10 +1,24 @@
 // Project/App: gsd-pi
 // File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, openIsolatedDatabase, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { resolveGsdPathContract, gsdRoot } from "./paths.js";
+import { logWarning, setLogBasePath } from "./workflow-logger.js";
+/**
+ * Global SQLite handle invariants:
+ *
+ * - `openWorkflowDatabase` / `openDatabase` switch the process-global handle consumed by
+ *   deriveState, dispatch, reconciliation repairs, and domain writers. Only one active
+ *   project database should own the global handle at a time.
+ * - `openWorkflowDatabaseIsolated` opens a caller-owned connection that does not clobber
+ *   the global handle. Use for read-only observers (parallel monitor) and other background
+ *   probes that must not disturb the active workflow session.
+ * - Reconciliation repairs that write markdown/DB state must use `ensureWorkflowDbForBase`
+ *   so repairs target the correct project; those paths intentionally re-open the global handle.
+ * - Pair ad-hoc project switches with `closeWorkflowDatabase()` or restore via
+ *   `ensureWorkflowDbForBase(..., { refresh: true })` before returning to derive/dispatch.
+ */
 export function resolveWorkflowDatabaseLocation(basePath) {
     const contract = resolveGsdPathContract(basePath);
     return {
@@ -104,6 +118,44 @@ export function getWorkflowDatabasePath() {
 export function refreshWorkflowDatabaseFromDisk() {
     return refreshOpenDatabaseFromDisk();
 }
+export function expectedWorkflowDbPathForBase(basePath) {
+    return join(gsdRoot(basePath), "gsd.db");
+}
+export function ensureWorkflowDbAtPath(dbPath) {
+    if (!dbPath || dbPath === ":memory:")
+        return isDbAvailable();
+    if (isDbAvailable() && getWorkflowDatabasePath() === dbPath)
+        return true;
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `ensureWorkflowDbAtPath could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
+export function ensureWorkflowDbForBase(basePath, options = {}) {
+    const dbPath = expectedWorkflowDbPathForBase(basePath);
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        if (options.refresh) {
+            if (isDbAvailable() && getWorkflowDatabasePath() === dbPath && refreshWorkflowDatabaseFromDisk()) {
+                return true;
+            }
+            return openWorkflowDatabasePath(dbPath);
+        }
+        if (isDbAvailable() && getWorkflowDatabasePath() === dbPath)
+            return true;
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `ensureWorkflowDbForBase could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
 export function checkpointWorkflowDatabase() {
     checkpointDatabase();
 }

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