@blackbelt-technology/pi-agent-dashboard 0.4.4 → 0.4.5

package/packages/server/src/__tests__/session-order-reboot.test.ts

@@ -16,7 +16,11 @@
 import { describe, it, expect, beforeEach } from "vitest";
 import { createPendingResumeIntentRegistry } from "../pending-resume-intent-registry.js";
 import { createSessionOrderManager } from "../session-order-manager.js";
+import { applyReattachPolicy } from "../reattach-placement.js";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+import type { ReattachPlacement } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import type { PreferencesStore } from "../preferences-store.js";
+import type { BrowserGateway } from "../browser-gateway.js";
 
 // In-memory PreferencesStore mock matching the slice of the interface
 // `sessionOrderManager` consumes.
@@ -207,6 +211,119 @@ describe("ended\u2192alive sessionOrder gate", () => {
     expect(sessionOrderManager.getOrder(cwd)).toEqual(["X", "A"]);
   });
 
+  // ── reattach-move-to-front ──
+
+  it("reattach with policy 'always' on persisted-active session lands at index 0 + broadcasts", () => {
+    // Repro: 6 alive sessions in cwd, none ended. The user's was at
+    // index 5. Dashboard restarts; bridge reconnects with
+    // registerReason: "reattach" for that session id.
+    sessionOrderManager.reorder(cwd, ["S0", "S1", "S2", "S3", "S4", "S5"]);
+
+    // No ended→alive transition fires (wasEnded=false, isEnded=false)
+    // for these reattaches; we exercise the new branch in server.ts
+    // directly via the helper.
+    const sm = createMemorySessionManager();
+    sm.register({ id: "S5", cwd, source: "tui" });
+
+    const broadcasts: any[] = [];
+    const gateway = { broadcastToAll: (m: any) => broadcasts.push(m) } as unknown as BrowserGateway;
+
+    const action = applyReattachPolicy("S5", cwd, "always", {
+      sessionManager: sm,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("moveToFront");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["S5", "S0", "S1", "S2", "S3", "S4"]);
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0].sessionIds[0]).toBe("S5");
+  });
+
+  it("reattach with policy 'preserve' is a no-op (legacy behavior)", () => {
+    sessionOrderManager.reorder(cwd, ["S0", "S1", "S2"]);
+    const sm = createMemorySessionManager();
+    sm.register({ id: "S2", cwd, source: "tui" });
+
+    const broadcasts: any[] = [];
+    const gateway = { broadcastToAll: (m: any) => broadcasts.push(m) } as unknown as BrowserGateway;
+
+    const action = applyReattachPolicy("S2", cwd, "preserve", {
+      sessionManager: sm,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("preserve");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["S0", "S1", "S2"]);
+    expect(broadcasts).toEqual([]);
+  });
+
+  it("legacy bridge (no registerReason) does NOT trigger reattach policy", () => {
+    // Spec scenario: "Legacy bridge reattach without registerReason
+    // preserves layout". Pre-this-change bridges omit the field; the
+    // server treats omission as `"spawn"` and skips the policy entirely.
+    sessionOrderManager.reorder(cwd, ["S0", "S1", "S2"]);
+
+    // Simulate the alive→alive branch's gate condition with a missing
+    // registerReason (i.e. ctx?.registerReason === undefined). Per the
+    // server.ts onChange code, the branch should not fire.
+    const ctx = { registerReason: undefined } as { registerReason?: "spawn" | "reattach" };
+    const shouldFire = ctx.registerReason === "reattach";
+    expect(shouldFire).toBe(false);
+
+    // Order remains untouched.
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["S0", "S1", "S2"]);
+  });
+
+  it("registry intent wins over registerReason: reattach (defensive guarantee)", () => {
+    // Spec scenario: "Registry intent wins over reattach". A registry
+    // intent of "front" or "keep" must override any registerReason:
+    // "reattach" so user actions are never clobbered by the policy.
+    sessionOrderManager.reorder(cwd, ["S0", "S1", "S2"]);
+    const sm = createMemorySessionManager();
+    sm.register({ id: "S2", cwd, source: "tui" });
+
+    // Replicate the server.ts alive→alive branch logic verbatim:
+    // consume registry first, defer to it if non-null.
+    pendingResumeIntents.record("S2", "front");
+    const intent = pendingResumeIntents.consume("S2");
+    expect(intent).toBe("front");
+
+    // With intent === "front", the registry path moves to front;
+    // the reattach policy is NOT invoked.
+    sessionOrderManager.moveToFront(cwd, "S2");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["S2", "S0", "S1"]);
+
+    // Verify policy.applyReattachPolicy would also have moved-to-front;
+    // the test guarantees registry-path wins by being executed first.
+    // (If both paths fired, S2 would still be at front, but only one
+    // sessions_reordered broadcast should be emitted in production.)
+  });
+
+  it("reattach respects 'streaming-only' policy: only moves streaming sessions", () => {
+    sessionOrderManager.reorder(cwd, ["S0", "S1", "S2"]);
+    const sm = createMemorySessionManager();
+    sm.register({ id: "S1", cwd, source: "tui" });
+    sm.register({ id: "S2", cwd, source: "tui" });
+    sm.update("S2", { status: "streaming" });
+
+    const policies: ReattachPlacement[] = ["streaming-only"];
+    for (const p of policies) {
+      // S1 is active, not streaming → preserve
+      const broadcastsA: any[] = [];
+      const gA = { broadcastToAll: (m: any) => broadcastsA.push(m) } as unknown as BrowserGateway;
+      expect(applyReattachPolicy("S1", cwd, p, { sessionManager: sm, sessionOrderManager, browserGateway: gA })).toBe("preserve");
+      expect(broadcastsA).toEqual([]);
+
+      // S2 is streaming → moveToFront
+      const broadcastsB: any[] = [];
+      const gB = { broadcastToAll: (m: any) => broadcastsB.push(m) } as unknown as BrowserGateway;
+      expect(applyReattachPolicy("S2", cwd, p, { sessionManager: sm, sessionOrderManager, browserGateway: gB })).toBe("moveToFront");
+      expect(broadcastsB).toHaveLength(1);
+    }
+  });
+
   it("end → resume → end → resume cycle always lands id at index 0", () => {
     // Regression for `top-of-tier-on-status-change`: pre-fix the
     // ended→alive branch used insert-if-absent, so on the second resume

package/packages/server/src/__tests__/session-scanner.test.ts

@@ -108,6 +108,37 @@ describe("session-scanner", () => {
     expect(meta.cachedAt).toBeGreaterThan(0);
   });
 
+  it("should seed lastActivityAt from events.jsonl mtime (cold-start, cached meta path)", () => {
+    const dir = createSessionDir("--test-cwd--");
+    const sf = createJsonl(dir, "2026-03-30T21-39-43-034Z_seed-id.jsonl", { id: "seed-id", cwd: "/seed" });
+    writeSessionMeta(sf, {
+      cwd: "/seed",
+      status: "ended",
+      startedAt: 1000,
+      cachedAt: Date.now() + 10_000, // fresh cache so we hit the cached-meta arm
+    });
+
+    // Force a known mtime on the .jsonl
+    const knownMtime = new Date("2026-04-15T10:00:00.000Z");
+    fs.utimesSync(sf, knownMtime, knownMtime);
+
+    const result = scanAllSessions(tmpDir);
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0].lastActivityAt).toBe(knownMtime.getTime());
+  });
+
+  it("should seed lastActivityAt from events.jsonl mtime (fallback parse path)", () => {
+    const dir = createSessionDir("--test-cwd--");
+    const sf = createJsonl(dir, "2026-03-30T21-39-43-034Z_fallback-seed.jsonl", { id: "fallback-seed", cwd: "/seed2" });
+    // No .meta.json — forces the fallback-parse arm.
+    const knownMtime = new Date("2026-04-16T11:30:00.000Z");
+    fs.utimesSync(sf, knownMtime, knownMtime);
+
+    const result = scanAllSessions(tmpDir);
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0].lastActivityAt).toBe(knownMtime.getTime());
+  });
+
   it("should ignore orphaned .meta.json without .jsonl", () => {
     const dir = createSessionDir("--test-cwd--");
     // Write .meta.json without a corresponding .jsonl

package/packages/server/src/__tests__/system-routes-restart.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Tests for `/api/restart` and `/api/shutdown` `server_restarting` broadcast.
+ * See change: fix-restart-bridge-auto-start-race.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import { registerSystemRoutes } from "../routes/system-routes.js";
+import type { PiGateway } from "../pi-gateway.js";
+import type { ServerToExtensionMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+
+function noGuard() {
+  return async () => { /* allow all */ };
+}
+
+function makeNoopDeps() {
+  return {
+    sessionManager: {} as never,
+    preferencesStore: { flush: () => {} } as never,
+    metaPersistence: { flushAll: () => {} } as never,
+    config: { port: 8000, piPort: 9999, dev: false } as never,
+    networkGuard: noGuard(),
+  };
+}
+
+function makeFakeGateway(): { gateway: PiGateway; broadcasts: ServerToExtensionMessage[] } {
+  const broadcasts: ServerToExtensionMessage[] = [];
+  const gateway: PiGateway = {
+    broadcast(msg) { broadcasts.push(msg); },
+    sendToSession() { return false; },
+    isSessionConnected() { return false; },
+    connectionCount() { return 0; },
+    onSessionRegistered() { /* no-op */ },
+    onConnectionClosed() { /* no-op */ },
+    close() { /* no-op */ },
+  } as unknown as PiGateway;
+  return { gateway, broadcasts };
+}
+
+describe("POST /api/restart broadcasts server_restarting", () => {
+  let fastify: FastifyInstance;
+  let exitSpy: ReturnType<typeof vi.spyOn>;
+  let broadcasts: ServerToExtensionMessage[];
+
+  beforeEach(() => {
+    fastify = Fastify();
+    const fake = makeFakeGateway();
+    broadcasts = fake.broadcasts;
+    // process.exit is deferred via setTimeout(...,200); silence it for the test
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((_code?: number) => undefined as never));
+    registerSystemRoutes(fastify, { ...makeNoopDeps(), piGateway: fake.gateway });
+  });
+
+  afterEach(async () => {
+    // Wait long enough for the route's deferred setTimeout(process.exit, 200)
+    // to fire WHILE the spy is still active, so the mock absorbs it instead
+    // of leaking to the real process.exit after mockRestore.
+    await new Promise((r) => setTimeout(r, 300));
+    await fastify.close();
+    exitSpy.mockRestore();
+  });
+
+  it("sends server_restarting with reason=restart and quiesceMs=5000 to bridges before exit", async () => {
+    const res = await fastify.inject({ method: "POST", url: "/api/restart", payload: {} });
+    // The handler returns ok:true synchronously (orchestrator + exit are deferred).
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true });
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({
+      type: "server_restarting",
+      reason: "restart",
+      quiesceMs: 5000,
+    });
+  });
+});
+
+describe("POST /api/shutdown broadcasts server_restarting", () => {
+  let fastify: FastifyInstance;
+  let exitSpy: ReturnType<typeof vi.spyOn>;
+  let broadcasts: ServerToExtensionMessage[];
+
+  beforeEach(() => {
+    fastify = Fastify();
+    const fake = makeFakeGateway();
+    broadcasts = fake.broadcasts;
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((_code?: number) => undefined as never));
+    registerSystemRoutes(fastify, { ...makeNoopDeps(), piGateway: fake.gateway });
+  });
+
+  afterEach(async () => {
+    await new Promise((r) => setTimeout(r, 300));
+    await fastify.close();
+    exitSpy.mockRestore();
+  });
+
+  it("sends server_restarting with reason=shutdown and quiesceMs=60000", async () => {
+    const res = await fastify.inject({ method: "POST", url: "/api/shutdown", payload: {} });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true });
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({
+      type: "server_restarting",
+      reason: "shutdown",
+      quiesceMs: 60000,
+    });
+  });
+});
+
+describe("/api/restart works without piGateway (no-op broadcast)", () => {
+  let fastify: FastifyInstance;
+  let exitSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fastify = Fastify();
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((_code?: number) => undefined as never));
+    registerSystemRoutes(fastify, makeNoopDeps()); // no piGateway
+  });
+
+  afterEach(async () => {
+    await new Promise((r) => setTimeout(r, 300));
+    await fastify.close();
+    exitSpy.mockRestore();
+  });
+
+  it("does not throw when there is no gateway", async () => {
+    const res = await fastify.inject({ method: "POST", url: "/api/restart", payload: {} });
+    expect(res.statusCode).toBe(200);
+  });
+});

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

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  writeSessionMeta,
+  readSessionMeta,
+  type SessionMeta,
+} from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
+
+/**
+ * Persistence round-trip for `SessionMeta.unread`.
+ * See change: session-card-unread-stripes.
+ */
+describe("unread persistence", () => {
+  it("round-trips unread=true through .meta.json", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "unread-meta-"));
+    const sessionFile = path.join(dir, "session-1.jsonl");
+    fs.writeFileSync(sessionFile, "");
+
+    const meta: SessionMeta = {
+      source: "tui",
+      cwd: "/tmp",
+      status: "idle",
+      unread: true,
+    };
+    writeSessionMeta(sessionFile, meta);
+
+    const restored = readSessionMeta(sessionFile);
+    expect(restored?.unread).toBe(true);
+  });
+
+  it("round-trips unread=false through .meta.json", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "unread-meta-"));
+    const sessionFile = path.join(dir, "session-2.jsonl");
+    fs.writeFileSync(sessionFile, "");
+
+    writeSessionMeta(sessionFile, { source: "tui", unread: false });
+    const restored = readSessionMeta(sessionFile);
+    expect(restored?.unread).toBe(false);
+  });
+
+  it("absent unread field is undefined on read (back-compat)", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "unread-meta-"));
+    const sessionFile = path.join(dir, "session-3.jsonl");
+    fs.writeFileSync(sessionFile, "");
+    fs.writeFileSync(
+      path.join(dir, "session-3.meta.json"),
+      JSON.stringify({ source: "tui", cwd: "/tmp" }),
+    );
+
+    const restored = readSessionMeta(sessionFile);
+    expect(restored?.unread).toBeUndefined();
+  });
+});

package/packages/server/src/__tests__/unread-trigger-wiring.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { WebSocket } from "ws";
+import { createServer, type DashboardServer } from "../server.js";
+
+/**
+ * End-to-end wiring test for `session.unread`:
+ *  - trigger fires & not viewed → unread broadcast
+ *  - trigger fires & viewed     → no unread
+ *  - replay events do not trigger unread
+ *
+ * See change: session-card-unread-stripes.
+ */
+
+async function connectSession(piPort: number, sessionId: string): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://localhost:${piPort}`);
+  await new Promise<void>((resolve) => {
+    ws.on("open", () => {
+      ws.send(JSON.stringify({
+        type: "session_register",
+        sessionId,
+        cwd: "/tmp",
+        source: "cli",
+      }));
+      ws.send(JSON.stringify({ type: "replay_complete", sessionId }));
+      setTimeout(resolve, 60);
+    });
+  });
+  return ws;
+}
+
+async function connectBrowser(browserPort: number, sessionId: string): Promise<{
+  ws: WebSocket;
+  broadcasts: Array<Record<string, unknown>>;
+}> {
+  const ws = new WebSocket(`ws://localhost:${browserPort}/ws`);
+  const broadcasts: Array<Record<string, unknown>> = [];
+  await new Promise<void>((resolve) => {
+    ws.on("open", () => {
+      ws.on("message", (raw) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          if (msg.type === "session_updated" && msg.sessionId === sessionId) {
+            broadcasts.push(msg);
+          }
+        } catch { /* ignore */ }
+      });
+      ws.send(JSON.stringify({ type: "subscribe", sessionId }));
+      setTimeout(resolve, 80);
+    });
+  });
+  return { ws, broadcasts };
+}
+
+function sendEvent(
+  ws: WebSocket,
+  sessionId: string,
+  eventType: string,
+  data: Record<string, unknown> = {},
+): void {
+  ws.send(JSON.stringify({
+    type: "event_forward",
+    sessionId,
+    event: { eventType, timestamp: Date.now(), data },
+  }));
+}
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("unread trigger — server wiring", () => {
+  let server: DashboardServer;
+  let piPort: number;
+  let browserPort: number;
+  let testPort = 19400;
+
+  beforeEach(async () => {
+    testPort += 2;
+    browserPort = testPort;
+    piPort = testPort + 1;
+    server = await createServer({
+      port: browserPort,
+      piPort,
+      dev: true,
+      autoShutdown: false,
+      shutdownIdleSeconds: 999,
+      tunnel: false,
+      editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+    });
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it("streaming → idle while NOT viewed marks the session unread and broadcasts", async () => {
+    const piWs = await connectSession(piPort, "u1");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "u1");
+
+    // Drive the session into streaming
+    sendEvent(piWs, "u1", "agent_start");
+    await wait(60);
+    expect(server.sessionManager.get("u1")?.status).toBe("streaming");
+
+    // Now finish the turn — agent_end transitions back to idle
+    sendEvent(piWs, "u1", "agent_end");
+    await wait(120);
+
+    const session = server.sessionManager.get("u1");
+    expect(session?.unread).toBe(true);
+
+    const unreadTrue = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.unread === true,
+    );
+    expect(unreadTrue.length).toBeGreaterThanOrEqual(1);
+
+    piWs.close();
+    browser.close();
+  });
+
+  it("trigger fires while a browser IS viewing → unread stays false", async () => {
+    const piWs = await connectSession(piPort, "u2");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "u2");
+
+    // Browser declares it is viewing the session
+    browser.send(JSON.stringify({ type: "session_view", sessionId: "u2" }));
+    await wait(60);
+
+    sendEvent(piWs, "u2", "agent_start");
+    await wait(60);
+    sendEvent(piWs, "u2", "agent_end");
+    await wait(120);
+
+    const session = server.sessionManager.get("u2");
+    expect(session?.unread).toBeFalsy();
+
+    const unreadTrue = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.unread === true,
+    );
+    expect(unreadTrue.length).toBe(0);
+
+    piWs.close();
+    browser.close();
+  });
+
+  it("replay events do not flip unread", async () => {
+    const ws = new WebSocket(`ws://localhost:${piPort}`);
+    await new Promise<void>((resolve) => {
+      ws.on("open", () => {
+        ws.send(JSON.stringify({
+          type: "session_register",
+          sessionId: "u3",
+          cwd: "/tmp",
+          source: "cli",
+        }));
+        // Send a replayable agent_start/agent_end pair BEFORE replay_complete.
+        sendEvent(ws, "u3", "agent_start");
+        sendEvent(ws, "u3", "agent_end");
+        setTimeout(resolve, 150);
+      });
+    });
+
+    const session = server.sessionManager.get("u3");
+    expect(session?.unread).toBeFalsy();
+
+    ws.close();
+  });
+
+  it("session_view clears unread and broadcasts unread=false", async () => {
+    const piWs = await connectSession(piPort, "u4");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "u4");
+
+    // Drive into unread (browser not viewing)
+    sendEvent(piWs, "u4", "agent_start");
+    await wait(50);
+    sendEvent(piWs, "u4", "agent_end");
+    await wait(120);
+    expect(server.sessionManager.get("u4")?.unread).toBe(true);
+
+    // Now declare view
+    browser.send(JSON.stringify({ type: "session_view", sessionId: "u4" }));
+    await wait(80);
+
+    expect(server.sessionManager.get("u4")?.unread).toBe(false);
+
+    const unreadFalseBroadcast = broadcasts.find(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.unread === false,
+    );
+    expect(unreadFalseBroadcast).toBeDefined();
+
+    piWs.close();
+    browser.close();
+  });
+
+  it("session_view on an already-read session does not produce a redundant broadcast", async () => {
+    const piWs = await connectSession(piPort, "u5");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "u5");
+
+    browser.send(JSON.stringify({ type: "session_view", sessionId: "u5" }));
+    browser.send(JSON.stringify({ type: "session_view", sessionId: "u5" }));
+    await wait(80);
+
+    const unreadBroadcasts = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.unread !== undefined,
+    );
+    expect(unreadBroadcasts.length).toBe(0);
+
+    piWs.close();
+    browser.close();
+  });
+});

package/packages/server/src/__tests__/viewed-session-tracker.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import type { WebSocket } from "ws";
+import { createViewedSessionTracker } from "../viewed-session-tracker.js";
+
+/**
+ * Server-side viewed-session tracker. Mirrors mail/Slack global read state.
+ * See change: session-card-unread-stripes.
+ */
+
+// Lightweight stand-ins for `ws.WebSocket`. The tracker only uses the
+// references for identity in `Set<WebSocket>`, so we don't need real sockets.
+function fakeWs(label: string): WebSocket {
+  return { __label: label } as unknown as WebSocket;
+}
+
+describe("createViewedSessionTracker", () => {
+  it("starts empty: no session is viewed", () => {
+    const t = createViewedSessionTracker();
+    expect(t.isViewedByAnyone("abc")).toBe(false);
+    expect(t.viewerCount("abc")).toBe(0);
+  });
+
+  it("view() makes a session viewed", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    t.view("abc", ws);
+    expect(t.isViewedByAnyone("abc")).toBe(true);
+    expect(t.viewerCount("abc")).toBe(1);
+  });
+
+  it("view() is idempotent for the same ws", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    t.view("abc", ws);
+    t.view("abc", ws);
+    expect(t.viewerCount("abc")).toBe(1);
+  });
+
+  it("two viewers, one disconnects → still viewed", () => {
+    const t = createViewedSessionTracker();
+    const a = fakeWs("a");
+    const b = fakeWs("b");
+    t.view("abc", a);
+    t.view("abc", b);
+    expect(t.viewerCount("abc")).toBe(2);
+    t.unview("abc", a);
+    expect(t.isViewedByAnyone("abc")).toBe(true);
+    expect(t.viewerCount("abc")).toBe(1);
+  });
+
+  it("last viewer unviews → no longer viewed", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    t.view("abc", ws);
+    t.unview("abc", ws);
+    expect(t.isViewedByAnyone("abc")).toBe(false);
+    expect(t.viewerCount("abc")).toBe(0);
+  });
+
+  it("unview() of an unknown session is a no-op", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    expect(() => t.unview("never-seen", ws)).not.toThrow();
+    expect(t.isViewedByAnyone("never-seen")).toBe(false);
+  });
+
+  it("unviewAll() removes a ws from every session", () => {
+    const t = createViewedSessionTracker();
+    const a = fakeWs("a");
+    const b = fakeWs("b");
+    t.view("s1", a);
+    t.view("s2", a);
+    t.view("s2", b);
+    t.unviewAll(a);
+    expect(t.isViewedByAnyone("s1")).toBe(false);
+    expect(t.isViewedByAnyone("s2")).toBe(true); // b still views s2
+    expect(t.viewerCount("s2")).toBe(1);
+  });
+
+  it("unviewAll() with no viewing sessions is a no-op", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    expect(() => t.unviewAll(ws)).not.toThrow();
+  });
+
+  it("multiple sessions are tracked independently", () => {
+    const t = createViewedSessionTracker();
+    const ws = fakeWs("a");
+    t.view("s1", ws);
+    expect(t.isViewedByAnyone("s1")).toBe(true);
+    expect(t.isViewedByAnyone("s2")).toBe(false);
+  });
+});