gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/tests/integration/workspace-collapse-integration.test.ts

@@ -0,0 +1,371 @@
+// GSD-2 + Integration regression suite for workspace collapse (feat/workspace-collapse)
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { createWorkspace, scopeMilestone } from "../../workspace.ts";
+import {
+  gsdRoot,
+  clearPathCache,
+  _clearGsdRootCache,
+} from "../../paths.ts";
+import {
+  loadWriteGateSnapshot,
+  markDepthVerified,
+  clearDiscussionFlowState,
+} from "../../bootstrap/write-gate.ts";
+import {
+  teardownAutoWorktree,
+  _resetAutoWorktreeOriginalBaseForTests,
+} from "../../auto-worktree.ts";
+import {
+  openDatabaseByWorkspace,
+  closeAllDatabases,
+  _getDbCache,
+} from "../../gsd-db.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-collapse-int-")));
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+function git(args: string[], cwd: string): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function makeGitRepo(): string {
+  const dir = makeProjectDir();
+  git(["init"], dir);
+  git(["config", "user.email", "test@gsd.test"], dir);
+  git(["config", "user.name", "GSD Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  return dir;
+}
+
+// ─── Test 1: Writer/validator path agreement under cwd-drift ─────────────────
+
+describe("workspace-collapse integration: Test 1 — cwd-drift path agreement", () => {
+  let projectDir: string;
+  let otherDir: string;
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    otherDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-cwd-drift-other-")));
+    _clearGsdRootCache();
+  });
+
+  afterEach(() => {
+    process.chdir(savedCwd);
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(otherDir, { recursive: true, force: true });
+    _clearGsdRootCache();
+  });
+
+  test("contextFile() returns same absolute path before and after cwd change", () => {
+    const worktreeDir = join(projectDir, ".gsd", "worktrees", "M001");
+    mkdirSync(worktreeDir, { recursive: true });
+
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+
+    // Record the path the "writer" would use
+    const writerPath = scope.contextFile();
+    assert.ok(writerPath.startsWith(projectDir), "writer path is under projectDir");
+
+    // Simulate cwd drift
+    process.chdir(otherDir);
+    assert.notEqual(process.cwd(), projectDir, "cwd has drifted away from projectDir");
+
+    // The "validator" recomputes via the same scope
+    const validatorPath = scope.contextFile();
+
+    assert.equal(
+      validatorPath,
+      writerPath,
+      "contextFile() must return the same absolute path regardless of cwd drift",
+    );
+  });
+
+  test("scopeMilestone paths are stable across cwd changes (roadmap, state, db)", () => {
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+
+    const before = {
+      roadmap: scope.roadmapFile(),
+      state: scope.stateFile(),
+      db: scope.dbPath(),
+      milestoneDir: scope.milestoneDir(),
+    };
+
+    process.chdir(otherDir);
+
+    assert.equal(scope.roadmapFile(), before.roadmap, "roadmapFile() stable after cwd drift");
+    assert.equal(scope.stateFile(), before.state, "stateFile() stable after cwd drift");
+    assert.equal(scope.dbPath(), before.db, "dbPath() stable after cwd drift");
+    assert.equal(scope.milestoneDir(), before.milestoneDir, "milestoneDir() stable after cwd drift");
+  });
+});
+
+// ─── Test 2: Abort path leaves no stale state ────────────────────────────────
+
+describe("workspace-collapse integration: Test 2 — abort teardown clears stale state", () => {
+  let repoDir: string;
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    repoDir = makeGitRepo();
+    _resetAutoWorktreeOriginalBaseForTests();
+  });
+
+  afterEach(() => {
+    process.chdir(savedCwd);
+    _resetAutoWorktreeOriginalBaseForTests();
+    rmSync(repoDir, { recursive: true, force: true });
+  });
+
+  test("STATE.md, auto.lock, and M001-META.json are removed by teardownAutoWorktree", () => {
+    const gsdDir = join(repoDir, ".gsd");
+    const milestonesDir = join(gsdDir, "milestones", "M001");
+    mkdirSync(milestonesDir, { recursive: true });
+
+    const stateMd = join(gsdDir, "STATE.md");
+    const autoLock = join(gsdDir, "auto.lock");
+    const metaJson = join(milestonesDir, "M001-META.json");
+
+    writeFileSync(stateMd, "# State\nactive\n");
+    writeFileSync(autoLock, JSON.stringify({ pid: process.pid, unitType: "plan-milestone", unitId: "M001" }));
+    writeFileSync(metaJson, JSON.stringify({ milestoneId: "M001" }));
+
+    assert.ok(existsSync(stateMd), "STATE.md exists before teardown");
+    assert.ok(existsSync(autoLock), "auto.lock exists before teardown");
+    assert.ok(existsSync(metaJson), "M001-META.json exists before teardown");
+
+    // teardownAutoWorktree clears state files before the git step; git removal
+    // may fail in a minimal test repo — that is acceptable.
+    try {
+      teardownAutoWorktree(repoDir, "M001");
+    } catch {
+      // git worktree removal may fail when no worktree was created — non-fatal for this assertion
+    }
+
+    assert.ok(!existsSync(stateMd), "STATE.md removed by teardownAutoWorktree (regression: A5)");
+    assert.ok(!existsSync(autoLock), "auto.lock removed by teardownAutoWorktree (regression: A5)");
+    assert.ok(!existsSync(metaJson), "M001-META.json removed by teardownAutoWorktree (regression: A5)");
+  });
+});
+
+// ─── Test 3: Cwd drift between persist and load of write-gate state ──────────
+
+describe("workspace-collapse integration: Test 3 — write-gate snapshot survives cwd drift", () => {
+  let projectDir: string;
+  let otherDir: string;
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    otherDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-wg-other-")));
+    // Start with a clean write-gate state for projectDir
+    clearDiscussionFlowState(projectDir);
+  });
+
+  afterEach(() => {
+    process.chdir(savedCwd);
+    clearDiscussionFlowState(projectDir);
+    try { clearDiscussionFlowState(otherDir); } catch { /* best-effort */ }
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(otherDir, { recursive: true, force: true });
+  });
+
+  test("loadWriteGateSnapshot returns persisted state after cwd drift", () => {
+    // Persist a snapshot: mark M001 depth-verified for projectDir
+    markDepthVerified("M001", projectDir);
+
+    // Drift cwd away from projectDir
+    process.chdir(otherDir);
+    assert.notEqual(process.cwd(), projectDir, "cwd has drifted");
+
+    // Load the snapshot using the explicit basePath — must not be affected by cwd
+    const snapshot = loadWriteGateSnapshot(projectDir);
+
+    assert.ok(
+      snapshot.verifiedDepthMilestones.includes("M001"),
+      "snapshot loaded from projectDir includes M001 despite cwd drift",
+    );
+  });
+
+  test("loadWriteGateSnapshot from different basePath does not bleed state", () => {
+    markDepthVerified("M001", projectDir);
+
+    process.chdir(otherDir);
+
+    // otherDir has no persisted state — should return empty snapshot
+    const snapshot = loadWriteGateSnapshot(otherDir);
+
+    assert.ok(
+      !snapshot.verifiedDepthMilestones.includes("M001"),
+      "otherDir snapshot must not bleed M001 state from projectDir",
+    );
+  });
+});
+
+// ─── Test 4: Sibling worktrees share DB connection ───────────────────────────
+
+describe("workspace-collapse integration: Test 4 — sibling worktrees share DB connection", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeAllDatabases();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("ws1 and ws2 (sibling worktrees) have same identityKey", () => {
+    const wt1 = join(projectDir, ".gsd", "worktrees", "M001");
+    const wt2 = join(projectDir, ".gsd", "worktrees", "M002");
+    mkdirSync(wt1, { recursive: true });
+    mkdirSync(wt2, { recursive: true });
+
+    const ws1 = createWorkspace(wt1);
+    const ws2 = createWorkspace(wt2);
+
+    assert.equal(
+      ws1.identityKey,
+      ws2.identityKey,
+      "sibling worktrees M001 and M002 must share the same identityKey",
+    );
+    assert.equal(
+      ws1.identityKey,
+      realpathSync(projectDir),
+      "identityKey is the realpath of the project root",
+    );
+  });
+
+  test("openDatabaseByWorkspace for sibling worktrees resolves to the same DB path", () => {
+    const wt1 = join(projectDir, ".gsd", "worktrees", "M001");
+    const wt2 = join(projectDir, ".gsd", "worktrees", "M002");
+    mkdirSync(wt1, { recursive: true });
+    mkdirSync(wt2, { recursive: true });
+
+    const ws1 = createWorkspace(wt1);
+    const ws2 = createWorkspace(wt2);
+
+    const ok1 = openDatabaseByWorkspace(ws1);
+    assert.ok(ok1, "openDatabaseByWorkspace(ws1) must succeed");
+    const cacheAfterWs1 = _getDbCache();
+    const entry1 = cacheAfterWs1.get(ws1.identityKey);
+    assert.ok(entry1, "cache entry for ws1.identityKey must exist");
+    const dbPath1 = entry1.dbPath;
+
+    const ok2 = openDatabaseByWorkspace(ws2);
+    assert.ok(ok2, "openDatabaseByWorkspace(ws2) must succeed");
+    const cacheAfterWs2 = _getDbCache();
+    const entry2 = cacheAfterWs2.get(ws2.identityKey);
+    assert.ok(entry2, "cache entry for ws2.identityKey must exist");
+    const dbPath2 = entry2.dbPath;
+
+    assert.equal(
+      dbPath1,
+      dbPath2,
+      "sibling worktrees must resolve to the same DB path (shared WAL)",
+    );
+    assert.equal(
+      cacheAfterWs2.size,
+      1,
+      "only one cache entry for project + two sibling worktrees",
+    );
+  });
+});
+
+// ─── Test 5: gsdRootCache normalization survives trailing-slash inputs ────────
+
+describe("workspace-collapse integration: Test 5 — gsdRootCache normalization deduplicates trailing-slash inputs", () => {
+  let projectDir: string;
+  let fakeHome: string;
+  let savedHome: string | undefined;
+  let savedUserProfile: string | undefined;
+  let savedGsdHome: string | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-cache-int-")));
+    mkdirSync(join(projectDir, ".gsd"), { recursive: true });
+
+    fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-cache-int-home-")));
+
+    savedHome = process.env.HOME;
+    savedUserProfile = process.env.USERPROFILE;
+    savedGsdHome = process.env.GSD_HOME;
+
+    // Prevent ~/.gsd interference
+    process.env.HOME = fakeHome;
+    process.env.USERPROFILE = fakeHome;
+    process.env.GSD_HOME = join(fakeHome, ".gsd");
+
+    clearPathCache();
+  });
+
+  afterEach(() => {
+    if (savedHome === undefined) delete process.env.HOME;
+    else process.env.HOME = savedHome;
+    if (savedUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = savedUserProfile;
+    if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = savedGsdHome;
+
+    clearPathCache();
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(fakeHome, { recursive: true, force: true });
+  });
+
+  test("gsdRoot('/path/to/project') and gsdRoot('/path/to/project/') return identical paths", () => {
+    const withoutSlash = gsdRoot(projectDir);
+    const withSlash = gsdRoot(projectDir + "/");
+
+    assert.equal(
+      withoutSlash,
+      withSlash,
+      "gsdRoot must return identical paths for inputs with and without trailing slash",
+    );
+    assert.equal(
+      withoutSlash,
+      join(projectDir, ".gsd"),
+      "both calls must resolve to projectDir/.gsd",
+    );
+  });
+
+  test("both calls after clearPathCache() return identical paths (no duplicate cache entries)", () => {
+    // Start clean
+    clearPathCache();
+
+    const r1 = gsdRoot(projectDir);
+    const r2 = gsdRoot(projectDir + "/");
+
+    assert.equal(r1, r2, "r1 and r2 must be the same string after normalization");
+    // The cache normalizes both inputs to the same key — no duplicate entries.
+    // We can't inspect the cache size directly, but the behavioral proof is
+    // that a second call after clearPathCache re-probes and still matches.
+    clearPathCache();
+    const r3 = gsdRoot(projectDir + "/");
+    assert.equal(r3, r1, "re-probe after clearPathCache must produce the same result");
+  });
+});

package/src/resources/extensions/gsd/tests/markdown-renderer.test.ts

@@ -856,10 +856,10 @@ test('── markdown-renderer: renderAllFromDb produces all files ──', asyn
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Graceful Degradation (Disk Fallback)
+// DB-authoritative regeneration
 // ═══════════════════════════════════════════════════════════════════════════
 
-test('── markdown-renderer: graceful fallback reads from disk when artifact not in DB ──', async () => {
+test('── markdown-renderer: missing artifact regenerates from DB without importing disk projection ──', async () => {
   const tmpDir = makeTmpDir();
   const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
   openDatabase(dbPath);
@@ -874,7 +874,7 @@ test('── markdown-renderer: graceful fallback reads from disk when artifact
     // Write roadmap to disk but NOT in artifacts DB
     const roadmapContent = makeRoadmapContent([
       { id: 'S01', title: 'Core', done: false },
-    ]);
+    ]) + '\n\nDISK_ONLY_SENTINEL';
     const roadmapPath = path.join(tmpDir, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
     fs.writeFileSync(roadmapPath, roadmapContent);
     clearAllCaches();
@@ -883,14 +883,20 @@ test('── markdown-renderer: graceful fallback reads from disk when artifact
     const before = getArtifact('milestones/M001/M001-ROADMAP.md');
     assert.deepStrictEqual(before, null, 'artifact not in DB before render');
 
-    // Render — should read from disk, store in DB
+    // Render — should regenerate from DB rows, not import/patch disk content.
     const ok = await renderRoadmapCheckboxes(tmpDir, 'M001');
-    assert.ok(ok, 'render succeeds with disk fallback');
+    assert.ok(ok, 'render succeeds by regenerating from DB');
 
-    // Verify artifact now in DB (stored after reading from disk)
+    // Verify artifact now exists in DB but does not contain disk-only content.
     const after = getArtifact('milestones/M001/M001-ROADMAP.md');
-    assert.ok(after !== null, 'artifact stored in DB after disk fallback render');
-    assert.ok(after!.full_content.includes('[x] **S01:'), 'DB artifact reflects rendered state');
+    assert.ok(after !== null, 'artifact regenerated in DB');
+    assert.ok(!after!.full_content.includes('DISK_ONLY_SENTINEL'), 'disk projection content was not imported');
+    assert.ok(after!.full_content.includes('S01'), 'DB artifact reflects DB slice state');
+
+    assert.ok(fs.existsSync(roadmapPath), 'roadmap projection regenerated on disk');
+    const diskAfter = fs.readFileSync(roadmapPath, 'utf-8');
+    assert.ok(!diskAfter.includes('DISK_ONLY_SENTINEL'), 'disk projection was rewritten from DB');
+    assert.ok(diskAfter.includes('S01'), 'disk projection reflects DB slice state');
   } finally {
     closeDatabase();
     cleanupDir(tmpDir);

package/src/resources/extensions/gsd/tests/md-importer.test.ts

@@ -9,6 +9,7 @@ import {
   getRequirementById,
   getActiveRequirements,
   insertArtifact,
+  SCHEMA_VERSION,
   _getAdapter,
 } from '../gsd-db.ts';
 import {
@@ -363,7 +364,7 @@ test('md-importer: schema v1→v2 migration', () => {
   openDatabase(':memory:');
   const adapter = _getAdapter();
   const version = adapter?.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.v, 22, 'new DB should be at schema version 22');
+  assert.deepStrictEqual(version?.v, SCHEMA_VERSION, `new DB should be at schema version ${SCHEMA_VERSION}`);
 
   // Artifacts table should exist
   const tableCheck = adapter?.prepare("SELECT count(*) as c FROM sqlite_master WHERE type='table' AND name='artifacts'").get();

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

@@ -2,6 +2,7 @@ import {
   openDatabase,
   closeDatabase,
   isDbAvailable,
+  SCHEMA_VERSION,
   _getAdapter,
 } from '../gsd-db.ts';
 import {
@@ -328,9 +329,9 @@ test('memory-store: schema includes memories table', () => {
   const viewCount = adapter.prepare('SELECT count(*) as cnt FROM active_memories').get();
   assert.deepStrictEqual(viewCount?.['cnt'], 0, 'active_memories view should exist');
 
-  // Verify schema version is 22 (v22 quality_gates DDL fix included)
+  // Verify schema version is current (includes quality_gates DDL fix and later migrations)
   const version = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.["v"], 22, 'schema version should be 22');
+  assert.deepStrictEqual(version?.["v"], SCHEMA_VERSION, `schema version should be ${SCHEMA_VERSION}`);
 
   closeDatabase();
 });

package/src/resources/extensions/gsd/tests/metrics-atomic-merge.test.ts

@@ -0,0 +1,222 @@
+/**
+ * GSD2 Metrics — regression test for parallel-mode atomic merge
+ *
+ * Verifies that concurrent metrics.json writers do not silently discard
+ * each other's entries (last-writer-wins). Two child processes each write
+ * a distinct milestone unit; after both complete, the merged file must
+ * contain both units.
+ */
+
+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 { spawnSync } from "node:child_process";
+
+// ─── Worker script source ────────────────────────────────────────────────────
+//
+// Each child process runs this script with two env vars:
+//   GSD_TEST_METRICS_PATH — absolute path to metrics.json
+//   GSD_TEST_MILESTONE_ID — milestone ID to record (e.g. "M001" or "M002")
+//
+// The script uses the same lock-acquire → read → merge → atomic-write
+// pattern implemented in metrics.ts saveLedger(), but using only built-in
+// Node.js modules so it runs without the full extension dependency tree.
+//
+const WORKER_SCRIPT = `
+const { openSync, closeSync, unlinkSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } = require('node:fs');
+const { dirname } = require('node:path');
+const { randomBytes } = require('node:crypto');
+
+const metricsPath = process.env.GSD_TEST_METRICS_PATH;
+const milestoneId = process.env.GSD_TEST_MILESTONE_ID;
+const lockPath = metricsPath + '.lock';
+
+// ── Lock helpers ──────────────────────────────────────────────────────────
+function acquireLock(lockPath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(lockPath, 'wx');
+      closeSync(fd);
+      return true;
+    } catch {
+      const waitUntil = Date.now() + Math.min(50, deadline - Date.now());
+      while (Date.now() < waitUntil) { /* spin */ }
+    }
+  }
+  return false;
+}
+
+function releaseLock(lockPath) {
+  try { unlinkSync(lockPath); } catch {}
+}
+
+// ── Atomic write helper ───────────────────────────────────────────────────
+function saveJsonAtomic(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmp = filePath + '.tmp.' + randomBytes(4).toString('hex');
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\\n', 'utf-8');
+  renameSync(tmp, filePath);
+}
+
+// ── Dedup helper (same logic as metrics.ts deduplicateUnits) ─────────────
+function deduplicateUnits(units) {
+  const map = new Map();
+  for (const u of units) {
+    const key = u.type + '\\0' + u.id + '\\0' + u.startedAt;
+    const existing = map.get(key);
+    if (!existing || u.finishedAt > existing.finishedAt) {
+      map.set(key, u);
+    }
+  }
+  return Array.from(map.values());
+}
+
+// ── Worker unit ───────────────────────────────────────────────────────────
+const workerUnit = {
+  type: 'execute-task',
+  id: milestoneId + '/S01/T01',
+  model: 'test-model',
+  startedAt: 1000,
+  finishedAt: Date.now(),
+  tokens: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, total: 150 },
+  cost: 0.01,
+  toolCalls: 1,
+  assistantMessages: 1,
+  userMessages: 1,
+};
+
+const workerLedger = {
+  version: 1,
+  projectStartedAt: 1000,
+  units: [workerUnit],
+};
+
+// ── Merge write ───────────────────────────────────────────────────────────
+const acquired = acquireLock(lockPath, 5000);
+try {
+  let onDiskUnits = [];
+  if (existsSync(metricsPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(metricsPath, 'utf-8'));
+      if (parsed && Array.isArray(parsed.units)) onDiskUnits = parsed.units;
+    } catch {}
+  }
+  const merged = deduplicateUnits([...onDiskUnits, ...workerLedger.units]);
+  saveJsonAtomic(metricsPath, { ...workerLedger, units: merged });
+} finally {
+  if (acquired) releaseLock(lockPath);
+}
+`;
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function spawnWorker(metricsPath: string, milestoneId: string): void {
+  const result = spawnSync(process.execPath, ["-e", WORKER_SCRIPT], {
+    env: {
+      ...process.env,
+      GSD_TEST_METRICS_PATH: metricsPath,
+      GSD_TEST_MILESTONE_ID: milestoneId,
+    },
+    encoding: "utf-8",
+    timeout: 10_000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(
+      `Worker for ${milestoneId} exited with status ${result.status}:\n${result.stderr}`,
+    );
+  }
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("metrics atomic merge — parallel workers", () => {
+  let tmpDir: string;
+  let gsdDir: string;
+  let metricsPath: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gsd-metrics-atomic-"));
+    gsdDir = join(tmpDir, ".gsd");
+    mkdirSync(gsdDir, { recursive: true });
+    metricsPath = join(gsdDir, "metrics.json");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("sequential writes from two workers both land in metrics.json", () => {
+    // Sequential baseline: M001 then M002. Both must survive.
+    spawnWorker(metricsPath, "M001");
+    spawnWorker(metricsPath, "M002");
+
+    const raw = readFileSync(metricsPath, "utf-8");
+    const ledger = JSON.parse(raw);
+
+    assert.ok(Array.isArray(ledger.units), "units must be an array");
+
+    const ids = ledger.units.map((u: { id: string }) => u.id) as string[];
+    assert.ok(ids.some(id => id.startsWith("M001")), "M001 unit must be present");
+    assert.ok(ids.some(id => id.startsWith("M002")), "M002 unit must be present");
+  });
+
+  test("concurrent writes from two workers both land in metrics.json (no last-writer-wins)", () => {
+    // Write an existing M001 entry to disk first, then run M002 worker.
+    // This simulates the race: M001 finishes and saves, then M002 reads-merges-writes.
+    const initialLedger = {
+      version: 1,
+      projectStartedAt: 1000,
+      units: [
+        {
+          type: "execute-task",
+          id: "M001/S01/T01",
+          model: "test-model",
+          startedAt: 1000,
+          finishedAt: 2000,
+          tokens: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, total: 150 },
+          cost: 0.01,
+          toolCalls: 1,
+          assistantMessages: 1,
+          userMessages: 1,
+        },
+      ],
+    };
+    writeFileSync(metricsPath, JSON.stringify(initialLedger, null, 2) + "\n", "utf-8");
+
+    // M002 worker runs — without merge semantics it would overwrite M001's data.
+    spawnWorker(metricsPath, "M002");
+
+    const raw = readFileSync(metricsPath, "utf-8");
+    const ledger = JSON.parse(raw);
+
+    assert.ok(Array.isArray(ledger.units), "units must be an array");
+    assert.equal(ledger.units.length, 2, "must contain exactly 2 units (M001 + M002)");
+
+    const ids = ledger.units.map((u: { id: string }) => u.id) as string[];
+    assert.ok(ids.some(id => id.startsWith("M001")), "M001 unit must be preserved after M002 write");
+    assert.ok(ids.some(id => id.startsWith("M002")), "M002 unit must be present");
+  });
+
+  test("idempotent write does not duplicate units", () => {
+    // Writing the same milestone unit twice must not create duplicates.
+    spawnWorker(metricsPath, "M001");
+    spawnWorker(metricsPath, "M001");
+
+    const raw = readFileSync(metricsPath, "utf-8");
+    const ledger = JSON.parse(raw);
+
+    assert.ok(Array.isArray(ledger.units), "units must be an array");
+    const m001Units = ledger.units.filter((u: { id: string }) => u.id.startsWith("M001"));
+    assert.equal(m001Units.length, 1, "duplicate units must be collapsed to one");
+  });
+});