@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/__tests__/json-store.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { readJsonFile, writeJsonFile } from "../json-store.js";
+
+describe("json-store", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "json-store-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("readJsonFile", () => {
+    it("returns fallback when file does not exist", () => {
+      const result = readJsonFile(path.join(tmpDir, "missing.json"), { x: 1 });
+      expect(result).toEqual({ x: 1 });
+    });
+
+    it("returns fallback for empty file", () => {
+      const fp = path.join(tmpDir, "empty.json");
+      fs.writeFileSync(fp, "");
+      expect(readJsonFile(fp, [])).toEqual([]);
+    });
+
+    it("returns fallback for invalid JSON", () => {
+      const fp = path.join(tmpDir, "bad.json");
+      fs.writeFileSync(fp, "{not valid json");
+      expect(readJsonFile(fp, "default")).toBe("default");
+    });
+
+    it("parses valid JSON", () => {
+      const fp = path.join(tmpDir, "good.json");
+      fs.writeFileSync(fp, JSON.stringify({ a: 1, b: [2, 3] }));
+      expect(readJsonFile(fp, {})).toEqual({ a: 1, b: [2, 3] });
+    });
+  });
+
+  describe("writeJsonFile", () => {
+    it("writes JSON atomically", () => {
+      const fp = path.join(tmpDir, "out.json");
+      writeJsonFile(fp, { hello: "world" });
+      const content = JSON.parse(fs.readFileSync(fp, "utf-8"));
+      expect(content).toEqual({ hello: "world" });
+    });
+
+    it("creates parent directories", () => {
+      const fp = path.join(tmpDir, "a", "b", "out.json");
+      writeJsonFile(fp, [1, 2, 3]);
+      expect(JSON.parse(fs.readFileSync(fp, "utf-8"))).toEqual([1, 2, 3]);
+    });
+
+    it("overwrites existing file", () => {
+      const fp = path.join(tmpDir, "overwrite.json");
+      writeJsonFile(fp, { v: 1 });
+      writeJsonFile(fp, { v: 2 });
+      expect(JSON.parse(fs.readFileSync(fp, "utf-8"))).toEqual({ v: 2 });
+    });
+
+    it("does not leave .tmp file", () => {
+      const fp = path.join(tmpDir, "clean.json");
+      writeJsonFile(fp, {});
+      expect(fs.existsSync(fp + ".tmp")).toBe(false);
+    });
+  });
+});

package/packages/server/src/__tests__/localhost-guard.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "vitest";
+import { isLoopback, isBypassedHost, matchCidr, ipToNum, createNetworkGuard, netmaskToCidrBits, networkAddress } from "../localhost-guard.js";
+
+describe("isLoopback", () => {
+  it("should match loopback addresses", () => {
+    expect(isLoopback("127.0.0.1")).toBe(true);
+    expect(isLoopback("::1")).toBe(true);
+    expect(isLoopback("::ffff:127.0.0.1")).toBe(true);
+  });
+
+  it("should reject non-loopback", () => {
+    expect(isLoopback("192.168.1.1")).toBe(false);
+    expect(isLoopback("10.0.0.1")).toBe(false);
+  });
+});
+
+describe("isBypassedHost", () => {
+  it("should match exact IP", () => {
+    expect(isBypassedHost("192.168.1.42", ["192.168.1.42"])).toBe(true);
+    expect(isBypassedHost("192.168.1.43", ["192.168.1.42"])).toBe(false);
+  });
+
+  it("should match wildcard", () => {
+    expect(isBypassedHost("10.0.0.5", ["10.0.0.*"])).toBe(true);
+    expect(isBypassedHost("10.0.1.5", ["10.0.0.*"])).toBe(false);
+  });
+
+  it("should match CIDR", () => {
+    expect(isBypassedHost("192.168.1.42", ["192.168.1.0/24"])).toBe(true);
+    expect(isBypassedHost("192.168.2.1", ["192.168.1.0/24"])).toBe(false);
+  });
+
+  it("should match wide CIDR", () => {
+    expect(isBypassedHost("10.255.0.1", ["10.0.0.0/8"])).toBe(true);
+    expect(isBypassedHost("11.0.0.1", ["10.0.0.0/8"])).toBe(false);
+  });
+
+  it("should return false for empty list", () => {
+    expect(isBypassedHost("192.168.1.1", [])).toBe(false);
+  });
+
+  it("should match any entry in the list", () => {
+    expect(isBypassedHost("10.0.0.5", ["192.168.1.0/24", "10.0.0.*"])).toBe(true);
+  });
+
+  it("should strip ::ffff: IPv4-mapped prefix", () => {
+    expect(isBypassedHost("::ffff:192.168.1.42", ["192.168.1.0/24"])).toBe(true);
+    expect(isBypassedHost("::ffff:10.0.0.5", ["10.0.0.*"])).toBe(true);
+    expect(isBypassedHost("::ffff:10.0.0.5", ["10.0.0.5"])).toBe(true);
+    expect(isBypassedHost("::ffff:192.168.2.1", ["192.168.1.0/24"])).toBe(false);
+  });
+});
+
+describe("matchCidr", () => {
+  it("should handle /32 (exact match)", () => {
+    expect(matchCidr("10.0.0.1", "10.0.0.1/32")).toBe(true);
+    expect(matchCidr("10.0.0.2", "10.0.0.1/32")).toBe(false);
+  });
+
+  it("should handle /0 (match all)", () => {
+    expect(matchCidr("1.2.3.4", "0.0.0.0/0")).toBe(true);
+  });
+
+  it("should reject invalid CIDR bits", () => {
+    expect(matchCidr("10.0.0.1", "10.0.0.0/33")).toBe(false);
+    expect(matchCidr("10.0.0.1", "10.0.0.0/-1")).toBe(false);
+  });
+});
+
+describe("ipToNum", () => {
+  it("should convert valid IPv4", () => {
+    expect(ipToNum("0.0.0.0")).toBe(0);
+    expect(ipToNum("255.255.255.255")).toBe(0xFFFFFFFF);
+    expect(ipToNum("192.168.1.1")).toBe((192 << 24 | 168 << 16 | 1 << 8 | 1) >>> 0);
+  });
+
+  it("should return null for invalid input", () => {
+    expect(ipToNum("not-an-ip")).toBeNull();
+    expect(ipToNum("::1")).toBeNull();
+    expect(ipToNum("256.0.0.0")).toBeNull();
+  });
+});
+
+describe("netmaskToCidrBits", () => {
+  it("should convert common netmasks", () => {
+    expect(netmaskToCidrBits("255.255.255.0")).toBe(24);
+    expect(netmaskToCidrBits("255.255.0.0")).toBe(16);
+    expect(netmaskToCidrBits("255.0.0.0")).toBe(8);
+    expect(netmaskToCidrBits("255.255.255.255")).toBe(32);
+    expect(netmaskToCidrBits("0.0.0.0")).toBe(0);
+    expect(netmaskToCidrBits("255.255.255.128")).toBe(25);
+  });
+});
+
+describe("networkAddress", () => {
+  it("should compute network address", () => {
+    expect(networkAddress("192.168.1.42", "255.255.255.0")).toBe("192.168.1.0");
+    expect(networkAddress("10.0.5.100", "255.255.0.0")).toBe("10.0.0.0");
+    expect(networkAddress("172.16.3.1", "255.0.0.0")).toBe("172.0.0.0");
+  });
+});
+
+describe("createNetworkGuard", () => {
+  function mockRequest(ip: string, isAuthenticated = false) {
+    return { ip, isAuthenticated } as any;
+  }
+
+  function mockReply() {
+    const r: any = { statusCode: 0, body: null };
+    r.code = (c: number) => { r.statusCode = c; return r; };
+    r.send = (b: any) => { r.body = b; return r; };
+    return r;
+  }
+
+  it("should allow loopback", async () => {
+    const guard = createNetworkGuard([]);
+    const reply = mockReply();
+    await guard(mockRequest("127.0.0.1"), reply);
+    expect(reply.statusCode).toBe(0);
+  });
+
+  it("should allow trusted network CIDR", async () => {
+    const guard = createNetworkGuard(["192.168.1.0/24"]);
+    const reply = mockReply();
+    await guard(mockRequest("192.168.1.42"), reply);
+    expect(reply.statusCode).toBe(0);
+  });
+
+  it("should allow authenticated request", async () => {
+    const guard = createNetworkGuard([]);
+    const reply = mockReply();
+    await guard(mockRequest("203.0.113.5", true), reply);
+    expect(reply.statusCode).toBe(0);
+  });
+
+  it("should block untrusted unauthenticated request", async () => {
+    const guard = createNetworkGuard(["192.168.1.0/24"]);
+    const reply = mockReply();
+    await guard(mockRequest("10.0.0.5", false), reply);
+    expect(reply.statusCode).toBe(403);
+  });
+
+  it("should block when no trusted networks and not authenticated", async () => {
+    const guard = createNetworkGuard([]);
+    const reply = mockReply();
+    await guard(mockRequest("192.168.1.5", false), reply);
+    expect(reply.statusCode).toBe(403);
+  });
+});

package/packages/server/src/__tests__/memory-event-store.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from "vitest";
+import { createMemoryEventStore } from "../memory-event-store.js";
+import type { DashboardEvent } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+function makeEvent(type: string = "test"): DashboardEvent {
+  return { eventType: type, timestamp: Date.now(), data: {} };
+}
+
+describe("memory-event-store", () => {
+  const neverPinned = () => false;
+
+  it("inserts and retrieves events", () => {
+    const store = createMemoryEventStore(neverPinned);
+    const seq1 = store.insertEvent("s1", makeEvent("a"));
+    const seq2 = store.insertEvent("s1", makeEvent("b"));
+    expect(seq1).toBe(1);
+    expect(seq2).toBe(2);
+
+    const events = store.getEvents("s1", 1);
+    expect(events).toHaveLength(2);
+    expect(events[0].seq).toBe(1);
+    expect(events[1].seq).toBe(2);
+  });
+
+  it("getEvents with minSeq filters correctly", () => {
+    const store = createMemoryEventStore(neverPinned);
+    store.insertEvent("s1", makeEvent());
+    store.insertEvent("s1", makeEvent());
+    store.insertEvent("s1", makeEvent());
+
+    const events = store.getEvents("s1", 2);
+    expect(events).toHaveLength(2);
+    expect(events[0].seq).toBe(2);
+  });
+
+  it("getEvents returns empty for unknown session", () => {
+    const store = createMemoryEventStore(neverPinned);
+    expect(store.getEvents("unknown", 1)).toEqual([]);
+  });
+
+  it("getEvent retrieves single event", () => {
+    const store = createMemoryEventStore(neverPinned);
+    const evt = makeEvent("special");
+    store.insertEvent("s1", evt);
+    const result = store.getEvent("s1", 1);
+    expect(result?.eventType).toBe("special");
+  });
+
+  it("getEvent returns undefined for missing", () => {
+    const store = createMemoryEventStore(neverPinned);
+    expect(store.getEvent("s1", 1)).toBeUndefined();
+  });
+
+  it("deleteEventsForSession clears buffer", () => {
+    const store = createMemoryEventStore(neverPinned);
+    store.insertEvent("s1", makeEvent());
+    store.insertEvent("s1", makeEvent());
+    const deleted = store.deleteEventsForSession("s1");
+    expect(deleted).toBe(2);
+    expect(store.getEvents("s1", 1)).toEqual([]);
+    expect(store.hasEvents("s1")).toBe(false);
+  });
+
+  it("deleteEventsForSession returns 0 for unknown session", () => {
+    const store = createMemoryEventStore(neverPinned);
+    expect(store.deleteEventsForSession("unknown")).toBe(0);
+  });
+
+  it("hasEvents checks correctly", () => {
+    const store = createMemoryEventStore(neverPinned);
+    expect(store.hasEvents("s1")).toBe(false);
+    store.insertEvent("s1", makeEvent());
+    expect(store.hasEvents("s1")).toBe(true);
+  });
+
+  it("sessionCount tracks number of sessions", () => {
+    const store = createMemoryEventStore(neverPinned);
+    expect(store.sessionCount()).toBe(0);
+    store.insertEvent("s1", makeEvent());
+    store.insertEvent("s2", makeEvent());
+    expect(store.sessionCount()).toBe(2);
+  });
+
+  it("assigns new seq numbers after deleteEventsForSession", () => {
+    const store = createMemoryEventStore(neverPinned);
+    store.insertEvent("s1", makeEvent());
+    store.insertEvent("s1", makeEvent());
+    store.deleteEventsForSession("s1");
+    const seq = store.insertEvent("s1", makeEvent());
+    expect(seq).toBe(1); // Resets after delete
+  });
+
+  describe("LRU eviction", () => {
+    it("evicts least-recently-accessed when over limit", () => {
+      const store = createMemoryEventStore(neverPinned, 3);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s2", makeEvent());
+      store.insertEvent("s3", makeEvent());
+      expect(store.sessionCount()).toBe(3);
+
+      // s4 should cause eviction of s1 (oldest)
+      store.insertEvent("s4", makeEvent());
+      expect(store.sessionCount()).toBe(3);
+      expect(store.hasEvents("s1")).toBe(false);
+      expect(store.hasEvents("s4")).toBe(true);
+    });
+
+    it("skips pinned sessions during eviction", () => {
+      const pinned = new Set(["s1"]);
+      const store = createMemoryEventStore((id) => pinned.has(id), 3);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s2", makeEvent());
+      store.insertEvent("s3", makeEvent());
+
+      // s4 should cause eviction of s2 (s1 is pinned)
+      store.insertEvent("s4", makeEvent());
+      expect(store.hasEvents("s1")).toBe(true); // pinned, not evicted
+      expect(store.hasEvents("s2")).toBe(false); // evicted
+    });
+
+    it("does not evict when all sessions are pinned", () => {
+      const store = createMemoryEventStore(() => true, 2);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s2", makeEvent());
+      store.insertEvent("s3", makeEvent());
+      // All pinned — can't evict, so size exceeds limit
+      expect(store.sessionCount()).toBe(3);
+    });
+
+    it("accessing events updates lastAccess to prevent eviction", async () => {
+      const store = createMemoryEventStore(neverPinned, 3);
+      store.insertEvent("s1", makeEvent());
+      await new Promise((r) => setTimeout(r, 5));
+      store.insertEvent("s2", makeEvent());
+      await new Promise((r) => setTimeout(r, 5));
+      store.insertEvent("s3", makeEvent());
+
+      // Access s1 so it becomes most recent
+      await new Promise((r) => setTimeout(r, 5));
+      store.getEvents("s1", 1);
+
+      // s4 should evict s2 (least recently accessed), not s1
+      store.insertEvent("s4", makeEvent());
+      expect(store.hasEvents("s1")).toBe(true);
+      expect(store.hasEvents("s2")).toBe(false);
+    });
+  });
+
+  describe("image data preservation", () => {
+    it("preserves base64 image data when sibling mimeType exists", () => {
+      // maxStringFieldSize = 100 so normal strings get truncated
+      const store = createMemoryEventStore(neverPinned, 100, 5000, 100);
+      const longBase64 = "A".repeat(500);
+      const event: DashboardEvent = {
+        eventType: "message_start",
+        timestamp: Date.now(),
+        data: {
+          message: {
+            role: "user",
+            content: [
+              { type: "image", data: longBase64, mimeType: "image/png" },
+            ],
+          },
+        },
+      };
+      store.insertEvent("s1", event);
+      const stored = store.getEvent("s1", 1);
+      const content = (stored as any).data.message.content[0];
+      expect(content.data).toBe(longBase64);
+      expect(content.data).toHaveLength(500);
+    });
+
+    it("still truncates data field without mimeType sibling", () => {
+      const store = createMemoryEventStore(neverPinned, 100, 5000, 100);
+      const longString = "B".repeat(500);
+      const event: DashboardEvent = {
+        eventType: "test",
+        timestamp: Date.now(),
+        data: { payload: { data: longString } },
+      };
+      store.insertEvent("s1", event);
+      const stored = store.getEvent("s1", 1);
+      const val = (stored as any).data.payload.data as string;
+      expect(val.length).toBeLessThan(500);
+      expect(val).toContain("truncated");
+    });
+
+    it("truncates other fields alongside preserved image data", () => {
+      const store = createMemoryEventStore(neverPinned, 100, 5000, 100);
+      const longBase64 = "C".repeat(500);
+      const longThinking = "D".repeat(5000);
+      const event: DashboardEvent = {
+        eventType: "message_start",
+        timestamp: Date.now(),
+        data: {
+          message: {
+            role: "user",
+            content: [
+              { type: "image", data: longBase64, mimeType: "image/png" },
+            ],
+          },
+          thinking: longThinking,
+        },
+      };
+      store.insertEvent("s1", event);
+      const stored = store.getEvent("s1", 1);
+      const content = (stored as any).data.message.content[0];
+      expect(content.data).toBe(longBase64); // preserved
+      const thinking = (stored as any).data.thinking as string;
+      expect(thinking).toContain("truncated"); // truncated
+      expect(thinking.length).toBeLessThan(longThinking.length); // shorter than original
+    });
+  });
+
+  describe("getMaxSeq", () => {
+    it("returns 0 for unknown session", () => {
+      const store = createMemoryEventStore(neverPinned);
+      expect(store.getMaxSeq("unknown")).toBe(0);
+    });
+
+    it("returns highest seq for session with events", () => {
+      const store = createMemoryEventStore(neverPinned);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent());
+      expect(store.getMaxSeq("s1")).toBe(3);
+    });
+
+    it("returns 0 after deleteEventsForSession", () => {
+      const store = createMemoryEventStore(neverPinned);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent());
+      store.deleteEventsForSession("s1");
+      expect(store.getMaxSeq("s1")).toBe(0);
+    });
+
+    it("returns correct seq after oldest events trimmed", () => {
+      const store = createMemoryEventStore(neverPinned, 100, 3);
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent());
+      store.insertEvent("s1", makeEvent()); // seq 4, oldest (seq 1) trimmed
+      expect(store.getMaxSeq("s1")).toBe(4);
+    });
+  });
+
+  it("trims oldest events when per-session limit exceeded", () => {
+    const store = createMemoryEventStore(neverPinned, 100, 3);
+    store.insertEvent("s1", makeEvent("a"));
+    store.insertEvent("s1", makeEvent("b"));
+    store.insertEvent("s1", makeEvent("c"));
+    store.insertEvent("s1", makeEvent("d"));
+
+    const events = store.getEvents("s1", 1);
+    expect(events).toHaveLength(3);
+    // Oldest event (seq 1) should be trimmed
+    expect(events[0].seq).toBe(2);
+    expect(events[2].seq).toBe(4);
+  });
+});

package/packages/server/src/__tests__/memory-session-manager.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+
+describe("memory-session-manager", () => {
+  it("registers a session", () => {
+    const sm = createMemorySessionManager();
+    const session = sm.register({
+      id: "s1",
+      cwd: "/tmp",
+      source: "tui",
+      name: "Test",
+    });
+    expect(session.id).toBe("s1");
+    expect(session.status).toBe("active");
+    expect(session.name).toBe("Test");
+  });
+
+  it("gets session by id", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    expect(sm.get("s1")).toBeDefined();
+    expect(sm.get("nonexistent")).toBeUndefined();
+  });
+
+  it("unregisters session", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.unregister("s1");
+    const s = sm.get("s1");
+    expect(s?.status).toBe("ended");
+    expect(s?.endedAt).toBeDefined();
+  });
+
+  it("updates session", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.update("s1", { tokensIn: 100, model: "test/model" });
+    expect(sm.get("s1")?.tokensIn).toBe(100);
+    expect(sm.get("s1")?.model).toBe("test/model");
+  });
+
+  it("updates hidden state on session object", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.update("s1", { hidden: true });
+    expect(sm.get("s1")?.hidden).toBe(true);
+  });
+
+  it("listActive excludes ended sessions", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.register({ id: "s2", cwd: "/tmp", source: "tui" });
+    sm.unregister("s1");
+    expect(sm.listActive()).toHaveLength(1);
+    expect(sm.listActive()[0].id).toBe("s2");
+  });
+
+  it("listAll includes all sessions", () => {
+    const sm = createMemorySessionManager();
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.register({ id: "s2", cwd: "/tmp", source: "tui" });
+    sm.unregister("s1");
+    expect(sm.listAll()).toHaveLength(2);
+  });
+
+  it("starts empty after creation", () => {
+    const sm = createMemorySessionManager();
+    expect(sm.listAll()).toHaveLength(0);
+  });
+
+  it("onChange receives sessionId", () => {
+    const sm = createMemorySessionManager();
+    const ids: string[] = [];
+    sm.onChange = (sessionId) => ids.push(sessionId);
+    sm.register({ id: "s1", cwd: "/tmp", source: "tui" });
+    sm.update("s1", { tokensIn: 50 });
+    sm.unregister("s1");
+    expect(ids).toEqual(["s1", "s1", "s1"]);
+  });
+});

package/packages/server/src/__tests__/meta-persistence.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createMetaPersistence } from "../meta-persistence.js";
+import { metaPath, readSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
+
+describe("meta-persistence", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-persist-test-"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function sessionFile(name: string): string {
+    return path.join(tmpDir, `${name}.jsonl`);
+  }
+
+  it("should debounce writes (not write immediately)", () => {
+    const mp = createMetaPersistence();
+    const sf = sessionFile("a");
+    mp.save(sf, { source: "dashboard", cost: 1.0 });
+    // Not written yet
+    expect(fs.existsSync(metaPath(sf))).toBe(false);
+    mp.dispose();
+  });
+
+  it("should write after debounce period", () => {
+    const mp = createMetaPersistence();
+    const sf = sessionFile("a");
+    mp.save(sf, { source: "dashboard", cost: 1.0 });
+    vi.advanceTimersByTime(1000);
+    const meta = readSessionMeta(sf);
+    expect(meta?.cost).toBe(1.0);
+    mp.dispose();
+  });
+
+  it("should reset debounce on subsequent saves", () => {
+    const mp = createMetaPersistence();
+    const sf = sessionFile("a");
+    mp.save(sf, { source: "dashboard", cost: 1.0 });
+    vi.advanceTimersByTime(500);
+    // Update before debounce fires
+    mp.save(sf, { source: "dashboard", cost: 2.0 });
+    vi.advanceTimersByTime(500);
+    // First timer would have fired, but it was reset
+    expect(fs.existsSync(metaPath(sf))).toBe(false);
+    vi.advanceTimersByTime(500);
+    // Now the second timer fires
+    const meta = readSessionMeta(sf);
+    expect(meta?.cost).toBe(2.0);
+    mp.dispose();
+  });
+
+  it("should write sessions independently", () => {
+    const mp = createMetaPersistence();
+    const sfA = sessionFile("a");
+    const sfB = sessionFile("b");
+    mp.save(sfA, { source: "dashboard", name: "A" });
+    vi.advanceTimersByTime(500);
+    mp.save(sfB, { source: "dashboard", name: "B" });
+    vi.advanceTimersByTime(500);
+    // A's timer fired, B's hasn't
+    expect(readSessionMeta(sfA)?.name).toBe("A");
+    expect(fs.existsSync(metaPath(sfB))).toBe(false);
+    vi.advanceTimersByTime(500);
+    expect(readSessionMeta(sfB)?.name).toBe("B");
+    mp.dispose();
+  });
+
+  it("should flush all pending writes immediately", () => {
+    const mp = createMetaPersistence();
+    const sfA = sessionFile("a");
+    const sfB = sessionFile("b");
+    mp.save(sfA, { source: "dashboard", name: "A" });
+    mp.save(sfB, { source: "dashboard", name: "B" });
+    mp.flushAll();
+    expect(readSessionMeta(sfA)?.name).toBe("A");
+    expect(readSessionMeta(sfB)?.name).toBe("B");
+    mp.dispose();
+  });
+
+  it("should use atomic writes (no leftover .tmp files)", () => {
+    const mp = createMetaPersistence();
+    const sf = sessionFile("a");
+    mp.save(sf, { source: "dashboard" });
+    mp.flushAll();
+    expect(fs.existsSync(metaPath(sf) + ".tmp")).toBe(false);
+    expect(fs.existsSync(metaPath(sf))).toBe(true);
+    mp.dispose();
+  });
+
+  it("should dispose without writing", () => {
+    const mp = createMetaPersistence();
+    const sf = sessionFile("a");
+    mp.save(sf, { source: "dashboard" });
+    mp.dispose();
+    vi.advanceTimersByTime(2000);
+    expect(fs.existsSync(metaPath(sf))).toBe(false);
+  });
+});