@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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/mcp-project-config.test.ts

@@ -60,7 +60,9 @@ test("ensureProjectWorkflowMcpConfig creates .mcp.json with workflow and browser
     assert.equal(typeof browserArgs[mcpArgIndex + 6], "string");
     assert.ok((browserArgs[mcpArgIndex + 6] ?? "").length > 0, "identity-key must be non-empty");
     assert.equal(browserArgs[mcpArgIndex + 7], "--identity-project");
-    assert.equal(browserArgs[mcpArgIndex + 8], projectRoot);
+    assert.equal(typeof browserArgs[mcpArgIndex + 8], "string");
+    assert.ok((browserArgs[mcpArgIndex + 8] ?? "").length > 0, "identity-project must be non-empty");
+    assert.doesNotMatch(browserArgs[mcpArgIndex + 8] ?? "", /[\\/]/, "identity-project must not be a filesystem path");
     assert.equal((browserServer as { cwd?: string })?.cwd, projectRoot);
 
     const settings = JSON.parse(readFileSync(join(projectRoot, ".claude", "settings.local.json"), "utf-8")) as {

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

@@ -0,0 +1,205 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the MCP readiness preflight gate in dispatchWorkflow.
+
+import { describe, test, mock } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { _awaitWorkflowMcpReadinessForTest as awaitWorkflowMcpReadiness } from "../guided-flow.ts";
+import { clearMcpConfigCache } from "../../mcp-client/manager.ts";
+import { clearWorkflowMcpProbeCache } from "../workflow-mcp-readiness-cache.ts";
+
+function makeCtx(opts: { authMode?: string; baseUrl?: string; systemPrompt?: string } = {}) {
+  const { authMode = "externalCli", baseUrl = "local://pipe", systemPrompt = "" } = opts;
+  return {
+    model: { provider: "anthropic", baseUrl },
+    modelRegistry: {
+      getProviderAuthMode: mock.fn(() => authMode),
+    },
+    getSystemPrompt: mock.fn(() => systemPrompt),
+    ui: {
+      setStatus: mock.fn(),
+      notify: mock.fn(),
+    },
+  } as any;
+}
+
+function makePi(tools: string[] | (() => string[])) {
+  const getTools = typeof tools === "function" ? tools : () => tools;
+  return {
+    getActiveTools: getTools,
+    getAllTools: () => getTools().map((name: string) => ({ name })),
+  } as any;
+}
+
+describe("awaitWorkflowMcpReadiness", () => {
+  test("returns null (ready) when not using MCP transport", async () => {
+    clearWorkflowMcpProbeCache();
+    const ctx = makeCtx({ authMode: "native", baseUrl: "https://api.anthropic.com" });
+    const pi = makePi([]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when provider has no auth mode", async () => {
+    const ctx = {
+      model: undefined,
+      modelRegistry: { getProviderAuthMode: mock.fn(() => undefined) },
+      ui: { setStatus: mock.fn(), notify: mock.fn() },
+    } as any;
+    const pi = makePi([]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when MCP tools are already registered", async () => {
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash", "mcp__gsd-workflow__ask_user_questions", "mcp__gsd-workflow__gsd_plan_slice"]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when host system prompt advertises workflow MCP tools", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx({
+      systemPrompt: "Available tools: read, bash, mcp__gsd-workflow__ask_user_questions",
+    });
+    const pi = makePi(["read", "bash"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("treats a successful direct probe as readiness when session tools are absent", async () => {
+    const previousGsdHome = process.env.GSD_HOME;
+    const projectDir = mkdtempSync(join(tmpdir(), "gsd-guided-mcp-probe-project-"));
+    const gsdHomeDir = mkdtempSync(join(tmpdir(), "gsd-guided-mcp-probe-home-"));
+    try {
+      process.env.GSD_HOME = gsdHomeDir;
+      mkdirSync(join(projectDir, ".gsd"), { recursive: true });
+
+      const require = createRequire(import.meta.url);
+      const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+      const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+      const serverPath = join(projectDir, "fake-workflow-mcp-server.mjs");
+      writeFileSync(
+        serverPath,
+        [
+          `const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+          `const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+          'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+          'server.tool("gsd_status", "Probe-visible workflow tool", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+          'await server.connect(new StdioServerTransport());',
+        ].join("\n"),
+        "utf-8",
+      );
+      writeFileSync(
+        join(projectDir, ".mcp.json"),
+        JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+        "utf-8",
+      );
+
+      const ctx = makeCtx();
+      const pi = makePi(["read", "bash"]);
+
+      assert.equal(
+        await awaitWorkflowMcpReadiness(pi, ctx, projectDir, { timeoutMs: 15_000, pollMs: 100 }),
+        null,
+      );
+    } finally {
+      if (previousGsdHome === undefined) {
+        delete process.env.GSD_HOME;
+      } else {
+        process.env.GSD_HOME = previousGsdHome;
+      }
+      rmSync(projectDir, { recursive: true, force: true });
+      rmSync(gsdHomeDir, { recursive: true, force: true });
+      clearMcpConfigCache();
+    }
+  });
+
+  test("returns server and probe error when workflow MCP never becomes ready", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      const failure = await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path", {
+        timeoutMs: 5,
+        pollMs: 1,
+        probe: async () => ({
+          ok: false,
+          tools: [],
+          serverName: "gsd-workflow",
+          error: "connection refused",
+        }),
+      });
+      assert.deepEqual(failure, { server: "gsd-workflow", error: "connection refused" });
+      assert.ok(ctx.ui.setStatus.mock.calls.length >= 2);
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("returns null (ready) when MCP tools appear during polling", async () => {
+    const ctx = makeCtx();
+    let callCount = 0;
+    const pi = makePi(() => {
+      callCount++;
+      if (callCount >= 3) return ["mcp__gsd-workflow__gsd_plan_slice"];
+      return ["read", "bash"];
+    });
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+    assert.ok(callCount >= 3, `expected at least 3 tool-check calls, got ${callCount}`);
+    assert.ok(ctx.ui.setStatus.mock.calls.length >= 2);
+  });
+
+  test("requires the active unit's workflow tools, not just any MCP workflow tool", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash", "mcp__gsd-workflow__gsd_slice_complete"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      const failure = await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path", {
+        unitType: "complete-slice",
+        timeoutMs: 5,
+        pollMs: 1,
+        probe: async () => ({
+          ok: true,
+          tools: ["gsd_slice_complete"],
+          serverName: "gsd-workflow",
+        }),
+      });
+
+      assert.deepEqual(failure, { server: "gsd-workflow" });
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("returns null when no launch config is discoverable", async () => {
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash"]);
+    const launch = (await import("../workflow-mcp.js")).detectWorkflowMcpLaunchConfig(process.cwd());
+    if (!launch) {
+      assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, process.cwd()), null);
+    }
+    // When launch config IS found, the function would timeout (15s) — skip that path in tests.
+  });
+});

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

@@ -58,13 +58,14 @@ describe("formatMcpStatusReport", () => {
     assert.match(result, /disabled/i);
   });
 
-  test("shows available state for servers that pass a status probe", () => {
+  test("labels probe-only availability separately from live connections", () => {
     const servers: McpServerStatus[] = [
       { name: "gsd-workflow", transport: "stdio", connected: false, available: true, toolCount: 62, error: undefined },
     ];
     const result = formatMcpStatusReport(servers);
     assert.match(result, /gsd-workflow/);
-    assert.match(result, /available — 62 tools/);
+    assert.match(result, /probe available — 62 tools/);
+    assert.doesNotMatch(result, /connected — 62 tools/);
     assert.doesNotMatch(result, /disconnected/);
   });
 
@@ -132,7 +133,7 @@ describe("formatMcpServerDetail", () => {
     assert.match(result, /disconnected/i);
   });
 
-  test("shows available status with tool names", () => {
+  test("shows probe-available status with tool names", () => {
     const result = formatMcpServerDetail({
       name: "gsd-workflow",
       transport: "stdio",
@@ -142,7 +143,7 @@ describe("formatMcpServerDetail", () => {
       tools: ["gsd_milestone_status"],
       error: undefined,
     });
-    assert.match(result, /available/i);
+    assert.match(result, /probe available/i);
     assert.match(result, /gsd_milestone_status/);
   });
 
@@ -206,7 +207,7 @@ describe("handleMcpStatus", () => {
       await handleMcpStatus("status", ctx as unknown as ExtensionCommandContext);
 
       assert.match(message, /gsd-workflow/);
-      assert.match(message, /available — 1 tools/);
+      assert.match(message, /probe available — 1 tools/);
       assert.doesNotMatch(message, /disconnected/);
     } finally {
       process.chdir(originalCwd);

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

@@ -0,0 +1,34 @@
+// Project/App: gsd-pi
+// File Purpose: Regression coverage for shared MCP tool-name parsing helpers.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mcpToolMatchesBaseName,
+  parseMcpToolName,
+  stripMcpToolPrefix,
+  toMcpToolName,
+  toMcpWildcardToolName,
+} from "../mcp-tool-name.ts";
+
+test("parseMcpToolName parses exact and wildcard MCP tool names", () => {
+  assert.deepEqual(parseMcpToolName("mcp__gsd-workflow__ask_user_questions"), {
+    serverName: "gsd-workflow",
+    toolName: "ask_user_questions",
+  });
+  assert.deepEqual(parseMcpToolName("mcp__gsd-browser__*"), {
+    serverName: "gsd-browser",
+    toolName: "*",
+  });
+  assert.equal(parseMcpToolName("browser_navigate"), null);
+});
+
+test("MCP tool-name helpers strip, match, and format names consistently", () => {
+  assert.equal(stripMcpToolPrefix("mcp__custom-workflow__gsd_exec"), "gsd_exec");
+  assert.equal(stripMcpToolPrefix("read"), "read");
+  assert.equal(mcpToolMatchesBaseName("mcp__custom-workflow__gsd_exec", "gsd_exec"), true);
+  assert.equal(mcpToolMatchesBaseName("mcp__custom-workflow__gsd_exec", "gsd_summary_save"), false);
+  assert.equal(toMcpToolName("custom-workflow", "gsd_exec"), "mcp__custom-workflow__gsd_exec");
+  assert.equal(toMcpWildcardToolName("custom-workflow"), "mcp__custom-workflow__*");
+});

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",
+    );
+  });
+});