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

package/src/resources/extensions/gsd/tests/destructive-guard.test.ts

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { classifyCommand } from "../safety/destructive-guard.ts";
+
+test("destructive guard ignores rm -rf text inside quoted literals and comments", () => {
+  const readOnlyCommands = [
+    'grep -rn "rm -rf" .',
+    'echo "rm -rf /tmp/x"',
+    'git commit -m "remove stray rm -rf usage"',
+    "cat notes.md  # remove stray rm -rf usage",
+    'printf "rm -rf /tmp/x\\n"',
+  ];
+
+  for (const command of readOnlyCommands) {
+    assert.deepEqual(classifyCommand(command), { destructive: false, labels: [] }, command);
+  }
+});
+
+test("destructive guard still detects direct and wrapper-prefixed recursive deletes", () => {
+  const destructiveCommands = [
+    "rm -rf build",
+    "rm build -rf",
+    "sudo rm -rf /",
+    "doas rm -rf /",
+    "sudo -u bob rm -rf /x",
+    "timeout 5 rm -rf /x",
+    "time rm -rf build",
+    "find . -exec rm -rf {} \\;",
+    "cat doomed.txt | xargs rm -rf /tmp/x",
+    'rm -rf "/tmp/my build"',
+  ];
+
+  for (const command of destructiveCommands) {
+    assert.deepEqual(classifyCommand(command), {
+      destructive: true,
+      labels: ["recursive delete"],
+    }, command);
+  }
+});
+
+test("destructive guard treats quoted interpreter payloads as literals", () => {
+  assert.deepEqual(classifyCommand('bash -c "rm -rf /"'), { destructive: false, labels: [] });
+});

package/src/resources/extensions/gsd/tests/dispatch-missing-task-plans.test.ts

@@ -96,6 +96,40 @@ function scaffoldMilestoneContext(basePath: string, mid: string): void {
   ].join("\n"));
 }
 
+function scaffoldLegacyMilestoneContext(basePath: string, mid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-CONTEXT.md`), [
+    `# ${mid}: Test Milestone`,
+    "",
+    "Context for legacy dispatch recovery tests.",
+    "",
+  ].join("\n"));
+}
+
+function scaffoldLegacySlicePlan(basePath: string, mid: string, sid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid);
+  mkdirSync(join(dir, "tasks"), { recursive: true });
+  writeFileSync(join(dir, `${sid}-PLAN.md`), [
+    `# ${sid}: Legacy Slice`,
+    "",
+    "## Tasks",
+    "- T01: Do something",
+    "",
+  ].join("\n"));
+}
+
+function scaffoldLegacyTaskPlan(basePath: string, mid: string, sid: string, tid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${tid}-PLAN.md`), [
+    `# ${tid}: First Task`,
+    "",
+    "Implement the task.",
+    "",
+  ].join("\n"));
+}
+
 function scaffoldTaskPlan(basePath: string, mid: string, sid: string, tid: string): void {
   // Flat-phase: no per-task plan files. This is a no-op — tasks live as
   // checkboxes inside the slice plan. Kept for backward-compat with tests
@@ -167,6 +201,115 @@ test("dispatch: present task plan proceeds to execute-task normally", async (t)
     `unitId should be M002/S03/T01, got: ${result.action === "dispatch" ? result.unitId : "(stop)"}`);
 });
 
+test("dispatch: missing legacy task plan recovery increments a per-slice retry counter", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-1087-retry-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  scaffoldLegacyMilestoneContext(tmp, "M002");
+  scaffoldLegacySlicePlan(tmp, "M002", "S03");
+
+  const session = {
+    missingTaskPlanRetryCount: new Map<string, number>(),
+  };
+  const result = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+
+  assert.equal(result.action, "dispatch");
+  assert.ok(result.action === "dispatch" && result.unitType === "plan-slice",
+    `unitType should be plan-slice, got: ${result.action === "dispatch" ? result.unitType : "(stop)"}`);
+  assert.ok(result.action === "dispatch" && result.unitId === "M002/S03",
+    `unitId should be M002/S03, got: ${result.action === "dispatch" ? result.unitId : "(stop)"}`);
+  assert.equal(session.missingTaskPlanRetryCount.get("M002/S03"), 1);
+});
+
+test("dispatch: missing legacy task plan recovery stops when retry counter is exhausted", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-1087-stop-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  scaffoldLegacyMilestoneContext(tmp, "M002");
+  scaffoldLegacySlicePlan(tmp, "M002", "S03");
+
+  const session = {
+    missingTaskPlanRetryCount: new Map<string, number>([["M002/S03", 2]]),
+  };
+  const result = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+
+  assert.equal(result.action, "stop");
+  assert.ok(result.action === "stop");
+  assert.equal(result.level, "error");
+  assert.match(result.reason, /Missing task-plan recovery failed 2 times for M002\/S03/);
+  assert.match(result.reason, /manual intervention required/);
+  assert.equal(session.missingTaskPlanRetryCount.has("M002/S03"), false);
+});
+
+test("dispatch: present legacy task plan clears missing-plan recovery retry counter", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-1087-clear-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  scaffoldLegacyMilestoneContext(tmp, "M002");
+  scaffoldLegacySlicePlan(tmp, "M002", "S03");
+  scaffoldLegacyTaskPlan(tmp, "M002", "S03", "T01");
+
+  const session = {
+    missingTaskPlanRetryCount: new Map<string, number>([["M002/S03", 1]]),
+    preExecRetryCount: new Map<string, number>([["M002/S03", 2]]),
+  };
+  const result = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+
+  assert.equal(result.action, "dispatch");
+  assert.ok(result.action === "dispatch" && result.unitType === "execute-task",
+    `unitType should be execute-task, got: ${result.action === "dispatch" ? result.unitType : "(stop)"}`);
+  assert.equal(session.missingTaskPlanRetryCount.has("M002/S03"), false);
+  assert.equal(session.preExecRetryCount.get("M002/S03"), 2,
+    "pre-exec retry counter must not be cleared when task plan is present");
+});
+
+test("dispatch: missing-task-plan recovery loop terminates even when the shared pre-exec key is reset between rounds (#1087)", async (t) => {
+  // The recovery rule re-dispatches plan-slice with unitId "${mid}/${sid}".
+  // That regenerated plan-slice carries the same currentUnit.id, and on a
+  // pre-execution pass the post-unit hook deletes that key from
+  // preExecRetryCount (auto-post-unit.ts). Missing per-task PLAN projection
+  // files do not fail pre-exec checks, so the regenerated plan-slice typically
+  // passes and that delete fires every cycle. If recovery shared
+  // preExecRetryCount, its counter would be wiped to 0 each round and the loop
+  // would never reach the cap. Here we simulate that reset between rounds and
+  // assert the dedicated counter still climbs to MAX and stops.
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-1087-loop-term-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  scaffoldLegacyMilestoneContext(tmp, "M002");
+  scaffoldLegacySlicePlan(tmp, "M002", "S03");
+
+  const session = {
+    missingTaskPlanRetryCount: new Map<string, number>(),
+    preExecRetryCount: new Map<string, number>(),
+  };
+
+  // Round 1: missing task plan → recover (counter 0 → 1).
+  const r1 = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+  assert.ok(r1.action === "dispatch" && r1.unitType === "plan-slice",
+    `round 1 should re-dispatch plan-slice, got: ${r1.action === "dispatch" ? r1.unitType : "(stop)"}`);
+  assert.equal(session.missingTaskPlanRetryCount.get("M002/S03"), 1);
+
+  // The regenerated plan-slice passes its post-unit pre-exec check, deleting
+  // the shared "${mid}/${sid}" key from preExecRetryCount.
+  session.preExecRetryCount.delete("M002/S03");
+
+  // Round 2: still missing → recover (counter 1 → 2), unaffected by the reset.
+  const r2 = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+  assert.ok(r2.action === "dispatch" && r2.unitType === "plan-slice",
+    `round 2 should re-dispatch plan-slice, got: ${r2.action === "dispatch" ? r2.unitType : "(stop)"}`);
+  assert.equal(session.missingTaskPlanRetryCount.get("M002/S03"), 2);
+
+  session.preExecRetryCount.delete("M002/S03");
+
+  // Round 3: cap reached → stop. The loop terminates despite the resets.
+  const r3 = await resolveDispatch(makeContextFor(tmp, "M002", "S03", "T01", session));
+  assert.equal(r3.action, "stop");
+  assert.ok(r3.action === "stop" && r3.level === "error");
+  assert.match(r3.reason, /Missing task-plan recovery failed 2 times for M002\/S03/);
+  assert.equal(session.missingTaskPlanRetryCount.has("M002/S03"), false);
+});
+
 test("dispatch: session milestone mismatch stops before missing-task-plan recovery", async (t) => {
   const tmp = mkdtempSync(join(tmpdir(), "gsd-session-milestone-mismatch-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/doctor-scope-db-unavailable.test.ts

@@ -1,12 +1,22 @@
 import { afterEach, test } from "node:test";
 import assert from "node:assert/strict";
-import { _getAdapter, closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  _getAdapter,
+  closeDatabase,
+  insertArtifact,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { filterDoctorIssues } from "../doctor-format.ts";
 import { checkEngineHealth } from "../doctor-engine-checks.ts";
+import { MEMORIES_FTS_REBUILT_KEY } from "../db-memory-fts-schema.ts";
 import { appendEvent } from "../workflow-events.ts";
+import { renderPlanFromDb, renderRoadmapFromDb } from "../markdown-renderer.ts";
 
 afterEach(() => {
   closeDatabase();
@@ -61,6 +71,139 @@ test("checkEngineHealth reports db_unavailable when gsd.db exists but the DB is
   assert.equal(dbIssue.file, ".gsd/gsd.db");
 });
 
+test("checkEngineHealth reports memories_fts without the rebuild marker", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-memory-fts-marker-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  const adapter = _getAdapter()!;
+  const fts = adapter.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+  if (!fts) return;
+
+  adapter.prepare(
+    "DELETE FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+  ).run({ ":key": MEMORIES_FTS_REBUILT_KEY });
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const ftsIssue = issues.find((issue) => issue.code === "memories_fts_rebuild_missing");
+  assert.ok(ftsIssue, "doctor should surface a potentially desynced memory FTS index");
+  assert.equal(ftsIssue.severity, "warning");
+  assert.equal(ftsIssue.unitId, "project");
+  assert.equal(ftsIssue.file, ".gsd/gsd.db");
+  assert.equal(ftsIssue.fixable, false);
+});
+
+test("checkEngineHealth reports checkbox divergence against DB status", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-checkbox-drift-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  writeFileSync(roadmap.roadmapPath, readFileSync(roadmap.roadmapPath, "utf-8").replace("- [ ] **S01:", "- [x] **S01:"), "utf-8");
+  writeFileSync(plan.planPath, readFileSync(plan.planPath, "utf-8").replace("- [x] **T01**:", "- [ ] **T01**:"), "utf-8");
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId).sort(),
+    ["M001/S01", "M001/S01/T01"],
+  );
+});
+
+test("checkEngineHealth keeps PLAN checkbox divergence after stale projection flush", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-checkbox-plan-drift-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  writeFileSync(roadmap.roadmapPath, readFileSync(roadmap.roadmapPath, "utf-8").replace("- [ ] **S01:", "- [x] **S01:"), "utf-8");
+  writeFileSync(plan.planPath, readFileSync(plan.planPath, "utf-8").replace("- [x] **T01**:", "- [ ] **T01**:"), "utf-8");
+  appendEvent(base, {
+    cmd: "complete-task",
+    params: { milestoneId: "M001", sliceId: "S01", taskId: "T01" },
+    ts: "2999-01-01T00:00:00.000Z",
+    actor: "agent",
+  });
+
+  const issues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, issues, fixes);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId),
+    ["M001/S01/T01"],
+    "stale ROADMAP divergence is cleared after re-render, but stale PLAN task divergence remains",
+  );
+  assert.ok(fixes.includes("re-rendered stale projections for M001"));
+  assert.match(readFileSync(plan.planPath, "utf-8"), /- \[ \] \*\*T01\*\*:/);
+});
+
+test("checkEngineHealth reads task checkboxes from the <tasks> block, not a stray line above it", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-task-section-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  // Flip the authoritative <tasks> checkbox so it disagrees with the DB
+  // (DB: complete, markdown: unchecked = real drift), then inject a *checked*
+  // decoy line for the same task above the <tasks> block. The old whole-file
+  // regex matched the decoy first and hid the real drift; parsePlan reads the
+  // authoritative <tasks> block and still reports it. No events are appended,
+  // so the projection-drift re-render never runs and the crafted file stands.
+  const rendered = readFileSync(plan.planPath, "utf-8")
+    .replace("- [x] **T01**:", "- [ ] **T01**:")
+    .replace("<tasks>\n", "- [x] **T01**: stale duplicate above the tasks block\n\n<tasks>\n");
+  writeFileSync(plan.planPath, rendered, "utf-8");
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId),
+    ["M001/S01/T01"],
+    "task drift must be read from the authoritative <tasks> block, not a stray checkbox above it",
+  );
+});
+
 test("checkEngineHealth reads canonical reopen events from worktree bases", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-reopen-worktree-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));
@@ -149,3 +292,97 @@ test("checkEngineHealth treats explicit reopen as authoritative when dispatch ti
     "explicit reopen should exempt reopened milestone even when completion dispatch timestamps are absent",
   );
 });
+
+test("checkEngineHealth reports artifact rows whose files are missing on disk", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-missing-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  const worktree = join(gsdDir, "worktrees", "M001");
+  mkdirSync(join(worktree, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(worktree, ".git"), "gitdir: ../../../../.git/worktrees/M001\n", "utf-8");
+  writeFileSync(join(worktree, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# Context\n", "utf-8");
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertArtifact({
+    path: "milestones/M001/M001-CONTEXT.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Context\n",
+  });
+  insertArtifact({
+    path: "milestones/M001/M001-MISSING.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Missing\n",
+  });
+
+  const issues: any[] = [];
+  await checkEngineHealth(worktree, issues, []);
+
+  assert.equal(
+    issues.some((issue) => issue.code === "artifact_file_missing" && issue.file === "milestones/M001/M001-CONTEXT.md"),
+    false,
+    "worktree-local artifacts should resolve through the projection root",
+  );
+  const missing = issues.find((issue) => issue.code === "artifact_file_missing" && issue.file === "milestones/M001/M001-MISSING.md");
+  assert.ok(missing, "missing artifact rows should be reported");
+  assert.equal(missing.unitId, "M001");
+  assert.equal(missing.fixable, false);
+});
+
+test("checkEngineHealth clears artifact_file_missing after projection re-render recreates the file", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-stale-missing-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active", planning: { vision: "Ship the foundation." } });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertArtifact({
+    path: "phases/01-foundation/01-ROADMAP.md",
+    artifact_type: "ROADMAP",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# stale row only\n",
+  });
+  // CONTEXT is not re-rendered by flushWorkflowProjections, so its missing-file
+  // diagnostic must survive the post-re-render cleanup (guards against the
+  // clearing logic over-broadening to artifacts the same run did not recreate).
+  insertArtifact({
+    path: "phases/01-foundation/01-CONTEXT.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# stale context row only\n",
+  });
+  appendEvent(base, {
+    cmd: "plan-milestone",
+    params: { milestoneId: "M001" },
+    ts: "2999-01-01T00:00:00.000Z",
+    actor: "agent",
+  });
+
+  const issues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, issues, fixes);
+
+  assert.ok(fixes.includes("re-rendered missing projections for M001"));
+  assert.equal(
+    issues.some((issue) => issue.code === "artifact_file_missing" && issue.file === "phases/01-foundation/01-ROADMAP.md"),
+    false,
+    "doctor should not report a missing artifact that projection repair recreated in the same run",
+  );
+  assert.ok(
+    issues.some((issue) => issue.code === "artifact_file_missing" && issue.file === "phases/01-foundation/01-CONTEXT.md"),
+    "doctor should still report a missing artifact that projection repair did not recreate",
+  );
+});

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

@@ -7,6 +7,7 @@ import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { getShellConfig } from '@gsd/pi-coding-agent';
 import { EXEC_DEFAULTS, runExecSandbox, type ExecSandboxOptions } from '../exec-sandbox.ts';
 import { buildExecOptions, executeGsdExec } from '../tools/exec-tool.ts';
 import { isContextModeEnabled } from '../preferences-types.ts';
@@ -53,6 +54,21 @@ test('runExecSandbox: captures stdout, persists artifacts, returns digest', asyn
   }
 });
 
+test('runExecSandbox: bash runtime uses resolved shell config', async () => {
+  const base = freshBase();
+  try {
+    const { shell } = getShellConfig();
+    const result = await runExecSandbox(
+      { runtime: 'bash', script: 'printf "%s" "$0"' },
+      baseOpts(base),
+    );
+    assert.equal(result.exit_code, 0);
+    assert.equal(readFileSync(result.stdout_path, 'utf-8'), shell);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('runExecSandbox: persists optional request metadata', async () => {
   const base = freshBase();
   try {

package/src/resources/extensions/gsd/tests/file-change-validator.test.ts

@@ -116,6 +116,46 @@ test("effectiveFileChangeAllowlist keeps .gitignore auditable when management is
   assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], false), ["docs/**"]);
 });
 
+test("validateFileChanges excludes .gsd-backups/ migration snapshots from unexpected-change warnings", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const backupFile = join(
+    base,
+    ".gsd-backups",
+    "migrate-1782703701330",
+    "M010",
+    "slices",
+    "S01",
+    "S01-ASSESSMENT.md",
+  );
+  mkdirSync(join(base, "src"), { recursive: true });
+  mkdirSync(join(backupFile, ".."), { recursive: true });
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+
+  writeFileSync(join(base, "src", "app.ts"), "initial\n");
+  writeFileSync(backupFile, "legacy assessment\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "initial");
+
+  writeFileSync(join(base, "src", "app.ts"), "updated\n");
+  writeFileSync(backupFile, "legacy assessment touched\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "task commit");
+
+  const audit = validateFileChanges(base, ["src/app.ts"], []);
+  assert.ok(audit, "audit should be produced");
+  assert.deepEqual(audit!.unexpectedFiles, [], ".gsd-backups/ must not trigger warnings");
+  assert.equal(
+    audit!.violations.filter(v => v.severity === "warning").length,
+    0,
+    "no warnings when only source and migration backup files changed",
+  );
+});
+
 test("GSD-managed .gitignore edit swept into a task commit is not flagged", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

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

@@ -2,12 +2,16 @@
 // File Purpose: Tests the one-time migration from nested to flat-phase layout.
 import test, { afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, readFileSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { migrateToFlatPhase, needsFlatPhaseMigration } from "../flat-phase-migration.ts";
+import {
+  migrateToFlatPhase,
+  needsFlatPhaseMigration,
+  pruneStaleFlatPhaseBackups,
+} from "../flat-phase-migration.ts";
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
 
 const tmpDirs: string[] = [];
@@ -112,3 +116,34 @@ test("migrateToFlatPhase preserves slice sidecar artifacts and skips recovery pl
     "recovery placeholder PLAN should not be promoted when no DB tasks can render a real plan",
   );
 });
+
+test("pruneStaleFlatPhaseBackups removes migrate-* dirs older than retention window", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+
+  const backupRoot = join(base, ".gsd-backups");
+  assert.ok(existsSync(backupRoot), "backup should exist immediately after migration");
+
+  const staleDir = join(backupRoot, "migrate-stale");
+  mkdirSync(staleDir, { recursive: true });
+  writeFileSync(join(staleDir, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(staleDir, staleDate, staleDate);
+
+  const removed = pruneStaleFlatPhaseBackups(base);
+  assert.equal(removed, 1, "stale migrate-* dir should be pruned");
+  assert.equal(existsSync(staleDir), false, "stale backup dir should be gone");
+  assert.ok(existsSync(backupRoot), "fresh migration backup should remain");
+});
+
+test("pruneStaleFlatPhaseBackups is a no-op while flat-phase migration is still needed", () => {
+  const base = makeTmp();
+  const backupRoot = join(base, ".gsd-backups", "migrate-stale");
+  mkdirSync(backupRoot, { recursive: true });
+  writeFileSync(join(backupRoot, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(backupRoot, staleDate, staleDate);
+
+  assert.equal(pruneStaleFlatPhaseBackups(base), 0, "must not prune while migration is pending");
+  assert.ok(existsSync(backupRoot), "backup must remain until migration completes");
+});

package/src/resources/extensions/gsd/tests/gitignore-bg-shell-runtime.test.ts

@@ -40,6 +40,10 @@ describe('ensureGitignore writes .bg-shell/ baseline (#4902)', () => {
         lines.has('.bg-shell/'),
         `.gitignore should include .bg-shell/. Got:\n${ignore}`,
       );
+      assert.ok(
+        lines.has('.gsd-backups/'),
+        `.gitignore should include .gsd-backups/. Got:\n${ignore}`,
+      );
     } finally {
       cleanup(dir);
     }

package/src/resources/extensions/gsd/tests/integration/git-service.test.ts

@@ -294,12 +294,13 @@ describe('git-service', async () => {
 
   assert.deepStrictEqual(
     RUNTIME_EXCLUSION_PATHS.length,
-    17,
-    "exactly 17 runtime exclusion paths"
+    18,
+    "exactly 18 runtime exclusion paths"
   );
 
   const expectedPaths = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -1623,11 +1624,13 @@ process.exit(result.status ?? 0);
     // Create and track runtime files (simulates pre-.gitignore state)
     mkdirSync(join(repo, ".gsd", "activity"), { recursive: true });
     mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+    mkdirSync(join(repo, ".gsd-backups", "migrate-old"), { recursive: true });
     writeFileSync(join(repo, ".gsd", "completed-units.json"), '["u1"]');
     writeFileSync(join(repo, ".gsd", "metrics.json"), '{}');
     writeFileSync(join(repo, ".gsd", "STATE.md"), "# State");
     writeFileSync(join(repo, ".gsd", "activity", "log.jsonl"), "{}");
     writeFileSync(join(repo, ".gsd", "runtime", "data.json"), "{}");
+    writeFileSync(join(repo, ".gsd-backups", "migrate-old", "marker.txt"), "backup");
     writeFileSync(join(repo, "src.ts"), "code");
     runGit(repo, ["add", "-A"]);
     runGit(repo, ["commit", "-m", "init"]);
@@ -1636,6 +1639,8 @@ process.exit(result.status ?? 0);
     const trackedBefore = run("git ls-files .gsd/", repo);
     assert.ok(trackedBefore.includes("completed-units.json"), "untrack: precondition — completed-units tracked");
     assert.ok(trackedBefore.includes("metrics.json"), "untrack: precondition — metrics tracked");
+    const backupTrackedBefore = run("git ls-files .gsd-backups/", repo);
+    assert.ok(backupTrackedBefore.includes("marker.txt"), "untrack: precondition — migration backup tracked");
 
     // Run untrackRuntimeFiles
     untrackRuntimeFiles(repo);
@@ -1643,6 +1648,8 @@ process.exit(result.status ?? 0);
     // Runtime files should be removed from the index
     const trackedAfter = run("git ls-files .gsd/", repo);
     assert.deepStrictEqual(trackedAfter, "", "untrack: all runtime files removed from index");
+    const backupTrackedAfter = run("git ls-files .gsd-backups/", repo);
+    assert.deepStrictEqual(backupTrackedAfter, "", "untrack: migration backups removed from index");
 
     // Non-runtime files remain tracked
     const srcTracked = run("git ls-files src.ts", repo);
@@ -1653,6 +1660,8 @@ process.exit(result.status ?? 0);
       "untrack: completed-units.json still on disk");
     assert.ok(existsSync(join(repo, ".gsd", "metrics.json")),
       "untrack: metrics.json still on disk");
+    assert.ok(existsSync(join(repo, ".gsd-backups", "migrate-old", "marker.txt")),
+      "untrack: migration backup still on disk");
 
     // Idempotent — running again doesn't error
     untrackRuntimeFiles(repo);