@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/tests/mcp-filter.test.ts

@@ -1,6 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+import fs, { mkdtempSync, writeFileSync, mkdirSync, utimesSync } from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -107,6 +108,78 @@ describe("discoverMcpServerNames", () => {
     );
     assert.equal(discoverBrowserMcpServerName(dir), "browser-uat");
   });
+
+  it("invalidates cached project MCP config when .mcp.json changes", () => {
+    const dir = mkdtempSync(join(tmpdir(), "mcp-filter-cache-test-"));
+    const configPath = join(dir, ".mcp.json");
+    writeFileSync(configPath, JSON.stringify({ mcpServers: { "server-a": {} } }));
+    assert.deepEqual(discoverMcpServerNames(dir), ["server-a"]);
+
+    writeFileSync(configPath, JSON.stringify({ mcpServers: { "server-b": {} } }));
+    const later = new Date(Date.now() + 5_000);
+    utimesSync(configPath, later, later);
+
+    assert.deepEqual(discoverMcpServerNames(dir), ["server-b"]);
+  });
+
+  it("reuses parsed project MCP config across discovery helpers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "mcp-filter-cache-test-"));
+    const claudeDir = join(dir, ".claude");
+    const mcpJsonPath = join(dir, ".mcp.json");
+    const settingsPath = join(claudeDir, "settings.json");
+    const localSettingsPath = join(claudeDir, "settings.local.json");
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(
+      mcpJsonPath,
+      JSON.stringify({
+        mcpServers: {
+          "custom-workflow": {
+            command: "node",
+            args: ["custom-cli.js"],
+            env: { GSD_WORKFLOW_PROJECT_ROOT: dir },
+          },
+        },
+      }),
+    );
+    writeFileSync(
+      settingsPath,
+      JSON.stringify({ mcpServers: { "browser-uat": { command: "gsd-browser", args: ["mcp"] } } }),
+    );
+    writeFileSync(
+      localSettingsPath,
+      JSON.stringify({ mcpServers: { "local-server": { command: "npx", args: ["local"] } } }),
+    );
+
+    const trackedPaths = new Set([mcpJsonPath, settingsPath, localSettingsPath]);
+    const readCounts = new Map<string, number>();
+    const originalReadFileSync = fs.readFileSync;
+    fs.readFileSync = ((...args: Parameters<typeof fs.readFileSync>) => {
+      const path = args[0];
+      if (typeof path === "string" && trackedPaths.has(path)) {
+        readCounts.set(path, (readCounts.get(path) ?? 0) + 1);
+      }
+      return originalReadFileSync(...args);
+    }) as typeof fs.readFileSync;
+    syncBuiltinESMExports();
+
+    try {
+      const mcpFilter = await import(`../mcp-filter.ts?cache-test=${Date.now()}`);
+      const discovered = mcpFilter.discoverMcpServerNames(dir);
+      const workflowName = mcpFilter.discoverWorkflowMcpServerName(dir);
+      const browserName = mcpFilter.discoverBrowserMcpServerName(dir);
+
+      assert.deepEqual(discovered.sort(), ["browser-uat", "custom-workflow", "local-server"]);
+      assert.equal(workflowName, "custom-workflow");
+      assert.equal(browserName, "browser-uat");
+      assert.deepEqual(
+        [mcpJsonPath, settingsPath, localSettingsPath].map((path) => readCounts.get(path) ?? 0),
+        [1, 1, 1],
+      );
+    } finally {
+      fs.readFileSync = originalReadFileSync;
+      syncBuiltinESMExports();
+    }
+  });
 });
 
 // ─── computeMcpDisallowedTools ─────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/memory-consolidation-scanner.test.ts

@@ -16,6 +16,7 @@ import {
   openDatabase,
   closeDatabase,
   insertDecision,
+  _getAdapter,
 } from "../gsd-db.ts";
 import { createMemory } from "../memory-store.ts";
 import {
@@ -271,6 +272,83 @@ test("scanConsolidationGaps combines decisions and KNOWLEDGE.md gaps in summary"
   }
 });
 
+test("scanConsolidationGaps collects memory source markers with one memories scan", () => {
+  const base = makeTmpBase();
+  try {
+    insertDecision({
+      id: "D001",
+      when_context: "2026-01-01",
+      scope: "M001",
+      decision: "Unmigrated decision",
+      choice: "A",
+      rationale: "x",
+      revisable: "yes",
+      made_by: "agent",
+      superseded_by: null,
+    });
+    insertDecision({
+      id: "D002",
+      when_context: "2026-01-02",
+      scope: "M001",
+      decision: "Migrated decision",
+      choice: "B",
+      rationale: "y",
+      revisable: "yes",
+      made_by: "agent",
+      superseded_by: null,
+    });
+    createMemory({
+      category: "architecture",
+      content: "Migrated decision Chose: B. Rationale: y.",
+      scope: "M001",
+      structuredFields: { sourceDecisionId: "D002" },
+    });
+    createMemory({
+      category: "pattern",
+      content: "Migrated knowledge pattern",
+      scope: "project",
+      structuredFields: { sourceKnowledgeId: "P001" },
+    });
+    writeKnowledgeMd(
+      base,
+      `## Patterns
+
+| # | Pattern | Where | Notes |
+|---|---------|-------|-------|
+| P001 | Migrated knowledge pattern | scanner | covered |
+| P002 | Unmigrated knowledge pattern | scanner | gap |
+`,
+    );
+
+    const adapter = _getAdapter();
+    assert.ok(adapter);
+    const originalPrepare = adapter.prepare.bind(adapter);
+    const memorySql: string[] = [];
+    adapter.prepare = (sql: string) => {
+      if (sql.includes("FROM memories")) memorySql.push(sql);
+      return originalPrepare(sql);
+    };
+
+    const report = scanConsolidationGaps(base);
+    assert.equal(report.decisions.migrated, 1);
+    assert.equal(report.decisions.unmigrated, 1);
+    assert.equal(report.knowledge.migrated, 1);
+    assert.equal(report.knowledge.unmigrated, 1);
+    assert.equal(
+      memorySql.filter((sql) => sql.includes("SELECT structured_fields FROM memories")).length,
+      1,
+      "source marker detection should read memories once",
+    );
+    assert.equal(
+      memorySql.some((sql) => sql.includes("LIKE :pattern")),
+      false,
+      "scanner must not reintroduce per-row LIKE marker probes",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 // ─── reportConsolidationGaps ───────────────────────────────────────────────
 
 test("reportConsolidationGaps emits a notification + warning when gaps exist", () => {

package/src/resources/extensions/gsd/tests/memory-store.test.ts

@@ -5,6 +5,9 @@ import {
   SCHEMA_VERSION,
   _getAdapter,
 } from '../gsd-db.ts';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
 import {
   _resetLogs,
   peekLogs,
@@ -22,6 +25,7 @@ import {
   markUnitProcessed,
   decayStaleMemories,
   enforceMemoryCap,
+  queryMemoriesRanked,
   applyMemoryActions,
   formatMemoriesForPrompt,
 } from '../memory-store.ts';
@@ -29,6 +33,16 @@ import type { MemoryAction } from '../memory-store.ts';
 import { describe, test, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-memory-store-test-'));
+  return path.join(dir, 'test.db');
+}
+
+function cleanupDbPath(dbPath: string): void {
+  closeDatabase();
+  fs.rmSync(path.dirname(dbPath), { recursive: true, force: true });
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // memory-store: fallback when DB not open
 // ═══════════════════════════════════════════════════════════════════════════
@@ -366,6 +380,40 @@ test('memory-store: schema includes memories table', () => {
   closeDatabase();
 });
 
+test('memory-store: reopening rebuilds FTS index for pre-FTS memories', () => {
+  const dbPath = tempDbPath();
+  try {
+    openDatabase(dbPath);
+    const id = createMemory({ category: 'gotcha', content: 'pre FTS auth memory must become searchable' });
+    assert.equal(id, 'MEM001');
+
+    const adapter = _getAdapter()!;
+    const fts = adapter.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+    if (!fts) return;
+
+    adapter.exec('DROP TRIGGER IF EXISTS memories_ai');
+    adapter.exec('DROP TRIGGER IF EXISTS memories_ad');
+    adapter.exec('DROP TRIGGER IF EXISTS memories_au');
+    adapter.exec('DROP TABLE IF EXISTS memories_fts');
+    adapter.prepare(
+      "DELETE FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = 'memories_fts_rebuilt_at'",
+    ).run();
+    closeDatabase();
+
+    openDatabase(dbPath);
+    const reopened = _getAdapter()!;
+    const marker = reopened.prepare(
+      "SELECT value_json FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = 'memories_fts_rebuilt_at'",
+    ).get();
+    assert.ok(marker, 'FTS rebuild marker should be set after reopening');
+
+    const hits = queryMemoriesRanked({ query: 'auth', k: 5 }).map((hit) => hit.memory.id);
+    assert.deepEqual(hits, ['MEM001']);
+  } finally {
+    cleanupDbPath(dbPath);
+  }
+});
+
 // ═══════════════════════════════════════════════════════════════════════════
 // regression #4967 — createMemory must not silently swallow SQL errors
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/merge-closeout-consistency-gate.test.ts

@@ -9,7 +9,15 @@ import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
 import { mergeMilestoneToMain } from "../auto-worktree.ts";
-import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
+import { checkCloseoutConsistencyGate } from "../closeout-consistency-gate.ts";
+import {
+  closeDatabase,
+  insertAssessment,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
 
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
@@ -61,3 +69,25 @@ test("mergeMilestoneToMain blocks when project DB closeout is still open", () =>
     if (existsSync(repo)) rmSync(repo, { recursive: true, force: true });
   }
 });
+
+test("closeout consistency treats deferred slices as inactive", () => {
+  try {
+    assert.equal(openDatabase(":memory:"), true);
+    insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+    insertSlice({ milestoneId: "M001", id: "S01", title: "Done", status: "complete" });
+    insertTask({ milestoneId: "M001", sliceId: "S01", id: "T01", title: "Done", status: "complete" });
+    insertSlice({ milestoneId: "M001", id: "S02", title: "Deferred", status: "deferred" });
+    insertTask({ milestoneId: "M001", sliceId: "S02", id: "T02", title: "Deferred", status: "pending" });
+    insertAssessment({
+      path: "milestones/M001/M001-VALIDATION.md",
+      milestoneId: "M001",
+      status: "pass",
+      scope: "milestone-validation",
+      fullContent: "verdict: pass",
+    });
+
+    assert.deepEqual(checkCloseoutConsistencyGate("M001"), { ok: true });
+  } finally {
+    closeDatabase();
+  }
+});

package/src/resources/extensions/gsd/tests/metrics-ledger-cap.test.ts

@@ -0,0 +1,239 @@
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  getLedger,
+  initMetrics,
+  METRICS_LEDGER_KEEP_UNITS,
+  resetMetrics,
+  snapshotUnitMetrics,
+  type MetricsLedger,
+  type UnitMetrics,
+} from "../metrics.js";
+
+function makeProjectDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-metrics-cap-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+function metricsPath(base: string): string {
+  return join(base, ".gsd", "metrics.json");
+}
+
+function assistantCtx(): any {
+  return {
+    sessionManager: {
+      getEntries: () => [
+        {
+          type: "message",
+          id: "entry-0",
+          parentId: null,
+          timestamp: new Date().toISOString(),
+          message: {
+            role: "assistant",
+            content: [{ type: "text", text: "Done" }],
+            usage: {
+              input: 100,
+              output: 50,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 150,
+              cost: 0.01,
+            },
+          },
+        },
+      ],
+    },
+  };
+}
+
+function makeUnit(index: number, id = `M001/S01/T${String(index).padStart(4, "0")}`): UnitMetrics {
+  const startedAt = 1_700_000_000_000 + index * 1000;
+  return {
+    type: "execute-task",
+    id,
+    model: "test-model",
+    startedAt,
+    finishedAt: startedAt + 500,
+    tokens: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, total: 15 },
+    cost: 0.001,
+    toolCalls: 1,
+    assistantMessages: 1,
+    userMessages: 1,
+    apiRequests: 1,
+  };
+}
+
+function writeLedger(base: string, units: UnitMetrics[]): void {
+  const ledger: MetricsLedger = {
+    version: 1,
+    projectStartedAt: 1_700_000_000_000,
+    units,
+  };
+  writeFileSync(metricsPath(base), JSON.stringify(ledger, null, 2) + "\n", "utf-8");
+}
+
+function readLedger(base: string): MetricsLedger {
+  return JSON.parse(readFileSync(metricsPath(base), "utf-8")) as MetricsLedger;
+}
+
+describe("metrics ledger steady-state cap", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    resetMetrics();
+  });
+
+  afterEach(() => {
+    resetMetrics();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("final cap preserves newest units by finishedAt when memory lags peer writes", () => {
+    // Scenario: memory loaded units 0..KEEP-1; a peer then advanced disk to
+    // units PEER_OFFSET..PEER_OFFSET+KEEP-1, adding PEER_OFFSET newer entries
+    // the worker has never seen.  The final keepNewestUnits call must rank by
+    // finishedAt, not by insertion order (disk-first), so old memory-only units
+    // do not crowd out newer on-disk peer units.
+    const KEEP = METRICS_LEDGER_KEEP_UNITS;
+    const PEER_OFFSET = 500;
+
+    // Load memory with units 0..KEEP-1.
+    const memUnits = Array.from({ length: KEEP }, (_, i) => makeUnit(i));
+    writeLedger(projectDir, memUnits);
+    initMetrics(projectDir);
+
+    // Peer advances disk to units PEER_OFFSET..PEER_OFFSET+KEEP-1.
+    const diskUnits = Array.from({ length: KEEP }, (_, i) => makeUnit(i + PEER_OFFSET));
+    writeLedger(projectDir, diskUnits);
+
+    // Trigger saveLedger.
+    const unit = snapshotUnitMetrics(
+      assistantCtx(),
+      "execute-task",
+      "M_STALE_MEM/S01/T01",
+      makeUnit(PEER_OFFSET + KEEP).startedAt,
+      "test-model",
+    );
+    assert.ok(unit, "snapshot must succeed");
+
+    const disk = readLedger(projectDir);
+    assert.equal(disk.units.length, KEEP, "disk must be capped at KEEP units");
+
+    // A disk unit that sits in the range evicted by insertion-order cap
+    // (positions 0..PEER_OFFSET-1 of the merged array) but must be kept
+    // by finishedAt-ordered cap because it is newer than memory-only units.
+    const diskUnitInEvictedRange = makeUnit(PEER_OFFSET + 1); // unit 501, newer than any memory-only unit
+    assert.ok(
+      disk.units.some((u) => u.id === diskUnitInEvictedRange.id),
+      `unit ${diskUnitInEvictedRange.id} (on-disk, newer than memory-only units) must not be displaced by stale memory tail`,
+    );
+
+    // The oldest surviving memory-only unit must be evicted.
+    const oldestMemOnlyUnit = makeUnit(1); // unit 1, older than all disk units (disk starts at 500)
+    assert.equal(
+      disk.units.some((u) => u.id === oldestMemOnlyUnit.id),
+      false,
+      `unit ${oldestMemOnlyUnit.id} (memory-only, older than all disk units) must be pruned`,
+    );
+  });
+
+  test("pre-merge cap preserves newest on-disk units even when disk order is stale", () => {
+    const KEEP = METRICS_LEDGER_KEEP_UNITS;
+
+    // Load memory with older local units.
+    const memUnits = Array.from(
+      { length: KEEP },
+      (_, i) => makeUnit(i, `M_MEM/S01/T${String(i).padStart(4, "0")}`),
+    );
+    writeLedger(projectDir, memUnits);
+    initMetrics(projectDir);
+
+    // Disk has more than KEEP entries, but its newest peer entries are at the
+    // head. A tail-slice pre-cap would discard these before the merge.
+    const newestPeerUnits = Array.from(
+      { length: 10 },
+      (_, i) => makeUnit(KEEP + i, `M_PEER/S01/T${String(i).padStart(4, "0")}`),
+    );
+    const olderPeerUnits = Array.from(
+      { length: KEEP },
+      (_, i) => makeUnit(i, `M_PEER_OLD/S01/T${String(i).padStart(4, "0")}`),
+    );
+    writeLedger(projectDir, [...newestPeerUnits, ...olderPeerUnits]);
+
+    const unit = snapshotUnitMetrics(
+      assistantCtx(),
+      "execute-task",
+      "M_STALE_DISK/S01/T01",
+      makeUnit(KEEP + newestPeerUnits.length).startedAt,
+      "test-model",
+    );
+    assert.ok(unit, "snapshot must succeed");
+
+    const disk = readLedger(projectDir);
+    assert.equal(disk.units.length, KEEP, "disk must be capped at KEEP units");
+    assert.ok(
+      disk.units.some((u) => u.id === newestPeerUnits[0]!.id),
+      "newer on-disk head unit must survive the pre-merge cap",
+    );
+  });
+
+  test("snapshot saves keep metrics.json and in-memory ledger bounded while preserving peer writes", () => {
+    const historicalUnits = Array.from(
+      { length: METRICS_LEDGER_KEEP_UNITS + 25 },
+      (_, index) => makeUnit(index),
+    );
+    writeLedger(projectDir, historicalUnits);
+
+    initMetrics(projectDir);
+
+    const peerUnit = makeUnit(historicalUnits.length, "M998/S01/T01");
+    writeLedger(projectDir, [...historicalUnits, peerUnit]);
+
+    const newStartedAt = peerUnit.startedAt + 1000;
+    const unit = snapshotUnitMetrics(
+      assistantCtx(),
+      "execute-task",
+      "M999/S01/T01",
+      newStartedAt,
+      "test-model",
+    );
+
+    assert.ok(unit, "snapshot should record the new unit");
+
+    const diskLedger = readLedger(projectDir);
+    assert.equal(diskLedger.units.length, METRICS_LEDGER_KEEP_UNITS);
+    assert.ok(
+      diskLedger.units.some((u) => u.id === peerUnit.id),
+      "peer unit written after init must survive the save merge",
+    );
+    assert.ok(
+      diskLedger.units.some((u) => u.id === "M999/S01/T01"),
+      "new unit must be persisted",
+    );
+    assert.equal(
+      diskLedger.units.some((u) => u.id === historicalUnits[0]!.id),
+      false,
+      "oldest history must be pruned from disk",
+    );
+
+    const memoryLedger = getLedger();
+    assert.equal(memoryLedger?.units.length, METRICS_LEDGER_KEEP_UNITS);
+    assert.equal(
+      memoryLedger?.units.some((u) => u.id === historicalUnits[0]!.id),
+      false,
+      "oldest history must be pruned from memory so the next save stays bounded",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/metrics-prune-cache-invalidation.test.ts

@@ -112,6 +112,12 @@ describe("pruneMetricsLedger: invalidates scoped ledger cache", () => {
     // 3. Prune to keepCount=2 — should evict 3 old units from disk AND clear scopedLedgers.
     const removed = pruneMetricsLedger(tmpDir, 2);
     assert.equal(removed, 3, "pruneMetricsLedger should report 3 removed units");
+    const prunedRaw = readFileSync(metricsPath(tmpDir), "utf-8");
+    assert.equal(
+      prunedRaw,
+      JSON.stringify(JSON.parse(prunedRaw)) + "\n",
+      "pruneMetricsLedger should persist compact metrics.json",
+    );
 
     // 4. Snapshot a new unit via scope. This exercises the lazy-reload path
     //    (scopedLedgers was cleared by prune) and writes the result to disk.

package/src/resources/extensions/gsd/tests/metrics.test.ts

@@ -259,6 +259,7 @@ test("initMetrics creates ledger, snapshotUnitMetrics persists across resets", (
     // Verify file content
     const raw = readFileSync(join(tmpBase, ".gsd", "metrics.json"), "utf-8");
     const parsed: MetricsLedger = JSON.parse(raw);
+    assert.equal(raw, JSON.stringify(parsed) + "\n", "metrics.json should be serialized compactly");
     assert.equal(parsed.version, 1);
     assert.equal(parsed.units.length, 1);
 

package/src/resources/extensions/gsd/tests/migrate-external-worktree.test.ts

@@ -7,7 +7,10 @@ import {
   existsSync,
   mkdirSync,
   realpathSync,
+  readFileSync,
 } from "node:fs";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -116,6 +119,60 @@ describe("migrate-external worktree guard (#2970)", () => {
   });
 });
 
+describe("migrateToExternalState copy failure rollback (#1047)", () => {
+  test("restores .gsd when a source entry fails to copy", () => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-migrate-copy-fail-")));
+    const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-state-copy-fail-")));
+    const previousStateDir = process.env.GSD_STATE_DIR;
+    const previousProjectId = process.env.GSD_PROJECT_ID;
+    const originalCpSync = fs.cpSync;
+    process.env.GSD_STATE_DIR = stateDir;
+    process.env.GSD_PROJECT_ID = "copy-fail";
+
+    try {
+      run("git init -b main", base);
+      mkdirSync(join(base, ".gsd"), { recursive: true });
+      writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "# prefs\n", "utf-8");
+      writeFileSync(join(base, ".gsd", "gsd.db"), "state", "utf-8");
+      const failingSource = join(base, ".gsd.migrating", "gsd.db");
+      fs.cpSync = ((...args: Parameters<typeof fs.cpSync>) => {
+        const src = args[0];
+        if (String(src) === failingSource) {
+          const error = new Error("simulated copy failure") as NodeJS.ErrnoException;
+          error.code = "EACCES";
+          throw error;
+        }
+        return originalCpSync(...args);
+      }) as typeof fs.cpSync;
+      syncBuiltinESMExports();
+
+      const result = migrateToExternalState(base);
+
+      assert.equal(result.migrated, false, "copy failure must fail the migration");
+      assert.match(result.error ?? "", /Migration copy failed/);
+      assert.ok(existsSync(join(base, ".gsd", "gsd.db")), "source .gsd must be restored");
+      assert.equal(readFileSync(join(base, ".gsd", "PREFERENCES.md"), "utf-8"), "# prefs\n");
+      assert.ok(!existsSync(join(base, ".gsd.migrating")), "backup staging dir must not remain after restore");
+      assert.ok(!existsSync(join(stateDir, "projects", "copy-fail", "gsd.db")), "failed file must not be reported as migrated");
+    } finally {
+      fs.cpSync = originalCpSync;
+      syncBuiltinESMExports();
+      if (previousStateDir === undefined) {
+        delete process.env.GSD_STATE_DIR;
+      } else {
+        process.env.GSD_STATE_DIR = previousStateDir;
+      }
+      if (previousProjectId === undefined) {
+        delete process.env.GSD_PROJECT_ID;
+      } else {
+        process.env.GSD_PROJECT_ID = previousProjectId;
+      }
+      rmSync(base, { recursive: true, force: true });
+      rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+});
+
 // Regression tests for #5571 — recoverFailedMigration handles orphaned .gsd.migrating
 describe("recoverFailedMigration (#5571)", () => {
   test("returns false when .gsd.migrating does not exist", () => {