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

package/src/resources/extensions/gsd/db-memory-fts-schema.ts

@@ -2,11 +2,18 @@
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
 
 import type { DbAdapter } from "./db-adapter.js";
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 
 export interface MemoryFtsSchemaOptions {
   onUnavailable?: (message: string) => void;
 }
 
+export interface MemoryFtsRebuildOptions {
+  onRebuildFailed?: (message: string) => void;
+}
+
 function formatFtsUnavailableError(err: unknown): string {
   const message = err instanceof Error ? err.message : String(err);
   return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
@@ -64,3 +71,41 @@ export function isMemoriesFtsAvailableSchema(db: DbAdapter): boolean {
     return false;
   }
 }
+
+export function rebuildMemoriesFtsSchemaOnce(
+  db: DbAdapter,
+  options: MemoryFtsRebuildOptions = {},
+): void {
+  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 as Error).message}`);
+  }
+}

package/src/resources/extensions/gsd/db-workspace.ts

@@ -2,7 +2,7 @@
 // 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 type { GsdWorkspace, MilestoneScope } from "./workspace.js";
 import type { DbAdapter } from "./db-adapter.js";
@@ -24,8 +24,8 @@ import {
   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";
 
 export interface WorkflowDatabaseLocation {
   projectRoot: string;
@@ -56,6 +56,20 @@ export type WorkflowDatabaseOpenResult =
 export type WorkflowDatabaseStatus = ReturnType<typeof getDbStatus>;
 export type WorkflowDatabaseProvider = ReturnType<typeof getDbProvider>;
 
+/**
+ * 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: string): WorkflowDatabaseLocation {
   const contract = resolveGsdPathContract(basePath);
   return {
@@ -172,6 +186,50 @@ export function refreshWorkflowDatabaseFromDisk(): boolean {
   return refreshOpenDatabaseFromDisk();
 }
 
+export function expectedWorkflowDbPathForBase(basePath: string): string {
+  return join(gsdRoot(basePath), "gsd.db");
+}
+
+export interface EnsureWorkflowDbOptions {
+  /** When true, refresh from disk before reopening if already open on the correct path. */
+  refresh?: boolean;
+}
+
+export function ensureWorkflowDbAtPath(dbPath: string | null): boolean {
+  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 as Error).message}`);
+    return false;
+  }
+}
+
+export function ensureWorkflowDbForBase(
+  basePath: string,
+  options: EnsureWorkflowDbOptions = {},
+): boolean {
+  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 as Error).message}`);
+    return false;
+  }
+}
+
 export function checkpointWorkflowDatabase(): void {
   checkpointDatabase();
 }

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -121,7 +121,7 @@ const POLICY: Record<string, DelegationPolicyEntry> = {
     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.",
+      "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
   },
 };
 

package/src/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/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -1,14 +1,148 @@
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+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: string, filePath: string): string {
+  return relative(basePath, filePath).split("\\").join("/");
+}
+
+function reportCheckboxDbStatusDivergence(
+  issues: DoctorIssue[],
+  basePath: string,
+  filePath: string,
+  scope: "slice" | "task",
+  unitId: string,
+  status: string,
+  checkboxDone: boolean,
+): void {
+  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: string, milestoneIds: string[], issues: DoctorIssue[]): void {
+  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: string,
+  issue: DoctorIssue,
+  reRenderedMilestoneIds: Set<string>,
+): boolean {
+  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: string, artifactPath: string): boolean {
+  if (isAbsolute(artifactPath)) return existsSync(artifactPath);
+  return [
+    join(gsdProjectionRoot(basePath), artifactPath),
+    join(gsdRoot(basePath), artifactPath),
+  ].some((candidate) => existsSync(candidate));
+}
+
+function artifactUnitId(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): string {
+  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: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): DoctorIssue["scope"] {
+  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: string,
@@ -34,6 +168,32 @@ export async function checkEngineHealth(
     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
@@ -196,7 +356,41 @@ export async function checkEngineHealth(
         // 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() as Array<{
+            path: string;
+            artifact_type: string;
+            milestone_id: string | null;
+            slice_id: string | null;
+            task_id: string | null;
+          }>;
+
+        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(
@@ -225,6 +419,7 @@ export async function checkEngineHealth(
 
         const seen = new Set<string>();
         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;
           const isSliceSummary = row.slice_id && !row.task_id && row.slice_status && !["complete", "done", "skipped", "closed"].includes(row.slice_status);
@@ -256,9 +451,24 @@ export async function checkEngineHealth(
     // 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: string[] = [];
   try {
     if (isDbAvailable()) {
       const eventLogPath = workflowEventLogPath(basePath);
@@ -273,6 +483,7 @@ export async function checkEngineHealth(
             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
             }
@@ -283,6 +494,7 @@ export async function checkEngineHealth(
             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
             }
@@ -293,4 +505,20 @@ export async function checkEngineHealth(
   } 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/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -408,6 +408,9 @@ export async function checkRuntimeHealth(
       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/src/resources/extensions/gsd/doctor-types.ts

@@ -84,10 +84,13 @@ export type DoctorIssueCode =
   | "db_orphaned_task"
   | "db_orphaned_slice"
   | "db_done_task_no_summary"
+  | "artifact_file_missing"
   | "artifact_db_status_divergence"
+  | "checkbox_db_status_divergence"
   | "completed_milestone_reopened"
   | "db_duplicate_id"
   | "db_unavailable"
+  | "memories_fts_rebuild_missing"
   | "projection_drift"
   // Milestone filesystem/DB drift (#4996)
   | "orphan_milestone_dir"

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

@@ -12,7 +12,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";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -138,7 +138,12 @@ function clampTimeout(request: ExecSandboxRequest, opts: ExecSandboxOptions): nu
 function resolveCommand(runtime: ExecSandboxRequest["runtime"]): { cmd: string; args: string[] } {
   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/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -70,6 +70,50 @@ export function needsFlatPhaseMigration(basePath: string): boolean {
   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: string): number {
+  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/src/resources/extensions/gsd/git-service.ts

@@ -12,6 +12,7 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import type { Dirent } from "node:fs";
 import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
@@ -360,6 +361,7 @@ export interface PreMergeCheckResult {
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd-worktrees/",
+  ".gsd-backups/**",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",
@@ -1268,6 +1270,7 @@ function collectRepositoryDirtyStatus(basePath: string): Record<string, boolean>
   const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
   const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
   const dirtyByRepository: Record<string, boolean> = {};
+  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;
@@ -1276,9 +1279,70 @@ function collectRepositoryDirtyStatus(basePath: string): Record<string, boolean>
       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: string, registeredRoots: ReadonlySet<string>): string[] {
+  const found: string[] = [];
+
+  function visit(dir: string, depth: number): void {
+    if (depth >= UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH) return;
+
+    let entries: Dirent[];
+    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: {
   basePath: string;
   unitType: string;