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

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

@@ -0,0 +1,164 @@
+import { describe, it, expect } from "vitest";
+import { isUnreadTrigger } from "../event-status-extraction.js";
+
+/**
+ * Unread-trigger classifier for `session.unread` flipping to true.
+ * See change: session-card-unread-stripes.
+ */
+describe("isUnreadTrigger", () => {
+  describe("trigger 1: streaming -> quiescent (turn finished)", () => {
+    it("returns true on streaming -> idle", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          { status: "idle", currentTool: null },
+        ),
+      ).toBe(true);
+    });
+
+    it("returns true on streaming -> active", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          { status: "active", currentTool: null },
+        ),
+      ).toBe(true);
+    });
+
+    it("returns false on idle -> idle (no transition)", () => {
+      expect(
+        isUnreadTrigger(
+          "tool_execution_end",
+          { status: "idle", currentTool: null },
+          { status: "idle", currentTool: null },
+        ),
+      ).toBe(false);
+    });
+
+    it("returns false on active -> idle (was not streaming)", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "active", currentTool: null },
+          { status: "idle", currentTool: null },
+        ),
+      ).toBe(false);
+    });
+
+    it("returns false on streaming -> streaming", () => {
+      expect(
+        isUnreadTrigger(
+          "message_end",
+          { status: "streaming", currentTool: null },
+          { status: "streaming", currentTool: null },
+        ),
+      ).toBe(false);
+    });
+
+    it("returns false on streaming -> ended (death is not unread)", () => {
+      // streaming -> ended is also a transition out of streaming, but per
+      // design.md the unread state is only about quiescent-alive sessions.
+      // Status "ended" should NOT trigger unread on its own. (If we want
+      // to mark ended sessions as needing attention, that's a separate
+      // requirement.)
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          // @ts-expect-error simulating the broader status union
+          { status: "ended", currentTool: null },
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("trigger 2: currentTool becomes ask_user", () => {
+    it("returns true when currentTool flips from null to ask_user", () => {
+      expect(
+        isUnreadTrigger(
+          "tool_execution_start",
+          { status: "streaming", currentTool: null },
+          { status: "streaming", currentTool: "ask_user" },
+        ),
+      ).toBe(true);
+    });
+
+    it("returns true when currentTool flips from another tool to ask_user", () => {
+      expect(
+        isUnreadTrigger(
+          "tool_execution_start",
+          { status: "streaming", currentTool: "Read" },
+          { status: "streaming", currentTool: "ask_user" },
+        ),
+      ).toBe(true);
+    });
+
+    it("returns false when ask_user persists (no transition)", () => {
+      expect(
+        isUnreadTrigger(
+          "message_end",
+          { status: "streaming", currentTool: "ask_user" },
+          { status: "streaming", currentTool: "ask_user" },
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("trigger 3: agent_end with error", () => {
+    it("returns true when payload.error is set", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          { status: "streaming", currentTool: null },
+          { error: "rate limit exceeded" },
+        ),
+      ).toBe(true);
+    });
+
+    it("returns false when agent_end has no error", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          { status: "streaming", currentTool: null },
+          {},
+        ),
+      ).toBe(false);
+    });
+
+    it("returns false on agent_end with no payload", () => {
+      expect(
+        isUnreadTrigger(
+          "agent_end",
+          { status: "streaming", currentTool: null },
+          { status: "streaming", currentTool: null },
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("non-triggers (intentional false)", () => {
+    const states = { status: "streaming", currentTool: null } as const;
+
+    it.each([
+      "message_start",
+      "message_end",
+      "tool_execution_start",
+      "tool_execution_end",
+      "model_select",
+      "git_info_update",
+      "process_metrics",
+      "ui_modules_list",
+      "bash_output",
+    ])("returns false for %s when state is unchanged", (eventType) => {
+      expect(isUnreadTrigger(eventType, states, states)).toBe(false);
+    });
+
+    it("returns false for unknown event types", () => {
+      expect(isUnreadTrigger("totally_made_up_event", states, states)).toBe(false);
+    });
+  });
+});

package/packages/server/src/__tests__/last-activity-broadcast.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { WebSocket } from "ws";
+import { createServer, type DashboardServer } from "../server.js";
+
+/**
+ * Tests for `lastActivityAt` server-side stamping + 30s debounced broadcast.
+ * See change: session-card-last-activity-badge.
+ */
+
+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, 50);
+    });
+  });
+  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 sendActivityEvent(ws: WebSocket, sessionId: string, eventType: string): 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("lastActivityAt — server stamping and debounce", () => {
+  let server: DashboardServer;
+  let piPort: number;
+  let browserPort: number;
+  let testPort = 19200;
+
+  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("stamps lastActivityAt on an activity event and broadcasts immediately the first time", async () => {
+    const ws = await connectSession(piPort, "a1");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "a1");
+
+    const before = Date.now();
+    sendActivityEvent(ws, "a1", "message_start");
+    await wait(120);
+
+    const session = server.sessionManager.get("a1");
+    expect(session?.lastActivityAt).toBeDefined();
+    expect(session!.lastActivityAt!).toBeGreaterThanOrEqual(before);
+
+    const lastActivityBroadcasts = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.lastActivityAt !== undefined,
+    );
+    expect(lastActivityBroadcasts.length).toBeGreaterThanOrEqual(1);
+
+    ws.close();
+    browser.close();
+  });
+
+  it("does NOT broadcast lastActivityAt for non-activity events", async () => {
+    const ws = await connectSession(piPort, "a2");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "a2");
+
+    sendActivityEvent(ws, "a2", "process_metrics");
+    sendActivityEvent(ws, "a2", "git_info_update");
+    sendActivityEvent(ws, "a2", "ui_data_list");
+    await wait(120);
+
+    const session = server.sessionManager.get("a2");
+    expect(session?.lastActivityAt).toBeUndefined();
+
+    const lastActivityBroadcasts = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.lastActivityAt !== undefined,
+    );
+    expect(lastActivityBroadcasts.length).toBe(0);
+
+    ws.close();
+    browser.close();
+  });
+
+  it("debounces subsequent broadcasts within the 30s window — in-memory still updates", async () => {
+    const ws = await connectSession(piPort, "a3");
+    const { ws: browser, broadcasts } = await connectBrowser(browserPort, "a3");
+
+    sendActivityEvent(ws, "a3", "tool_execution_start");
+    await wait(120);
+
+    const t1 = server.sessionManager.get("a3")?.lastActivityAt;
+    expect(t1).toBeDefined();
+    const broadcastCountAfterFirst = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.lastActivityAt !== undefined,
+    ).length;
+    expect(broadcastCountAfterFirst).toBeGreaterThanOrEqual(1);
+
+    // Send several more activity events well within the 30s debounce window
+    await wait(200);
+    sendActivityEvent(ws, "a3", "tool_execution_end");
+    sendActivityEvent(ws, "a3", "message_end");
+    sendActivityEvent(ws, "a3", "turn_end");
+    await wait(120);
+
+    const t2 = server.sessionManager.get("a3")?.lastActivityAt;
+    expect(t2).toBeDefined();
+    expect(t2!).toBeGreaterThan(t1!); // in-memory advances on every activity event
+
+    const broadcastCountAfterMore = broadcasts.filter(
+      (b) => (b.updates as Record<string, unknown> | undefined)?.lastActivityAt !== undefined,
+    ).length;
+    // No new lastActivityAt-only broadcast within 30s.
+    expect(broadcastCountAfterMore).toBe(broadcastCountAfterFirst);
+
+    ws.close();
+    browser.close();
+  });
+
+  it("does not stamp lastActivityAt during replay (events arriving before replay_complete)", async () => {
+    // Connect raw without sending replay_complete — event-wiring treats events as replay
+    const ws = new WebSocket(`ws://localhost:${piPort}`);
+    await new Promise<void>((resolve) => {
+      ws.on("open", () => {
+        ws.send(JSON.stringify({
+          type: "session_register",
+          sessionId: "a4",
+          cwd: "/tmp",
+          source: "cli",
+        }));
+        // Intentionally NO replay_complete here.
+        sendActivityEvent(ws, "a4", "message_end");
+        sendActivityEvent(ws, "a4", "tool_execution_start");
+        setTimeout(resolve, 150);
+      });
+    });
+
+    const session = server.sessionManager.get("a4");
+    expect(session?.lastActivityAt).toBeUndefined();
+
+    ws.close();
+  });
+});

package/packages/server/src/__tests__/reattach-placement.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Tests for the `applyReattachPolicy` helper and its pure
+ * `decideReattachAction` decision function.
+ *
+ * Covers the matrix from `specs/session-ordering` ADDED Requirement
+ * "Reattach placement policy applied on register":
+ *   policy × session.status → moveToFront | preserve
+ *
+ * See change: reattach-move-to-front.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  decideReattachAction,
+  applyReattachPolicy,
+} from "../reattach-placement.js";
+import { createMemorySessionManager, type SessionManager } from "../memory-session-manager.js";
+import { createSessionOrderManager, type SessionOrderManager } from "../session-order-manager.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { BrowserGateway } from "../browser-gateway.js";
+
+function makePrefs(): PreferencesStore {
+  let order: Record<string, string[]> = {};
+  return {
+    getSessionOrder: () => order,
+    setSessionOrder: (o) => { order = o; },
+    getPinnedDirectories: () => [],
+    setPinnedDirectories: () => {},
+    pinDirectory: () => {},
+    unpinDirectory: () => {},
+    reorderPinnedDirs: () => {},
+    flush: () => {},
+    dispose: () => {},
+  };
+}
+
+function makeBroadcastingGateway() {
+  const broadcasts: any[] = [];
+  const gateway = {
+    broadcastToAll: (msg: any) => { broadcasts.push(msg); },
+    // Other BrowserGateway members are unused by the helper.
+  } as unknown as BrowserGateway;
+  return { gateway, broadcasts };
+}
+
+describe("decideReattachAction (pure)", () => {
+  it("'always' moves on any non-ended status", () => {
+    expect(decideReattachAction("always", "active")).toBe("moveToFront");
+    expect(decideReattachAction("always", "streaming")).toBe("moveToFront");
+    expect(decideReattachAction("always", "idle")).toBe("moveToFront");
+  });
+
+  it("'streaming-only' moves only when status is 'streaming'", () => {
+    expect(decideReattachAction("streaming-only", "streaming")).toBe("moveToFront");
+    expect(decideReattachAction("streaming-only", "active")).toBe("preserve");
+    expect(decideReattachAction("streaming-only", "idle")).toBe("preserve");
+    expect(decideReattachAction("streaming-only", "ended")).toBe("preserve");
+    expect(decideReattachAction("streaming-only", undefined)).toBe("preserve");
+  });
+
+  it("'preserve' never moves", () => {
+    expect(decideReattachAction("preserve", "streaming")).toBe("preserve");
+    expect(decideReattachAction("preserve", "active")).toBe("preserve");
+  });
+});
+
+describe("applyReattachPolicy (I/O)", () => {
+  const cwd = "/proj";
+  let sessionManager: SessionManager;
+  let sessionOrderManager: SessionOrderManager;
+  let gateway: BrowserGateway;
+  let broadcasts: any[];
+
+  beforeEach(() => {
+    sessionManager = createMemorySessionManager();
+    sessionOrderManager = createSessionOrderManager(makePrefs());
+    const gw = makeBroadcastingGateway();
+    gateway = gw.gateway;
+    broadcasts = gw.broadcasts;
+  });
+
+  function setupSession(id: string, status: "active" | "streaming" | "idle" | "ended" = "active") {
+    sessionManager.register({ id, cwd, source: "tui" });
+    if (status !== "active") sessionManager.update(id, { status });
+  }
+
+  it("'always' moves a buried session to index 0 and broadcasts", () => {
+    setupSession("A");
+    setupSession("B");
+    setupSession("C");
+    sessionOrderManager.reorder(cwd, ["A", "B", "C"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("C", cwd, "always", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("moveToFront");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["C", "A", "B"]);
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toMatchObject({
+      type: "sessions_reordered",
+      cwd,
+      sessionIds: ["C", "A", "B"],
+    });
+  });
+
+  it("'streaming-only' moves a streaming session", () => {
+    setupSession("A");
+    setupSession("B", "streaming");
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("B", cwd, "streaming-only", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("moveToFront");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["B", "A"]);
+    expect(broadcasts).toHaveLength(1);
+  });
+
+  it("'streaming-only' does NOT move a non-streaming session", () => {
+    setupSession("A");
+    setupSession("B", "active");
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("B", cwd, "streaming-only", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("preserve");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B"]);
+    expect(broadcasts).toEqual([]);
+  });
+
+  it("'preserve' never moves regardless of status", () => {
+    setupSession("A");
+    setupSession("B", "streaming");
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("B", cwd, "preserve", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("preserve");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B"]);
+    expect(broadcasts).toEqual([]);
+  });
+
+  it("no-ops if session is missing from manager", () => {
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("ghost", cwd, "always", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("preserve");
+    expect(broadcasts).toEqual([]);
+  });
+
+  it("'streaming-only' honors priorStatus when post-register status is 'active' (regression: register() coerces status)", () => {
+    // Repro: pre-restart the session was streaming; the dashboard restarts;
+    // the bridge re-registers; `register()` overwrites status to "active".
+    // Without priorStatus, applyReattachPolicy would see status: "active"
+    // and `streaming-only` would be a silent no-op.
+    setupSession("A");
+    setupSession("B"); // status defaults to "active" post-register
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    // Pass priorStatus: "streaming" (what register() saw before overwriting)
+    const action = applyReattachPolicy(
+      "B",
+      cwd,
+      "streaming-only",
+      { sessionManager, sessionOrderManager, browserGateway: gateway },
+      "streaming",
+    );
+
+    expect(action).toBe("moveToFront");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["B", "A"]);
+    expect(broadcasts).toHaveLength(1);
+  });
+
+  it("'streaming-only' falls back to session.status when priorStatus is undefined", () => {
+    setupSession("A");
+    setupSession("B", "streaming");
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy(
+      "B",
+      cwd,
+      "streaming-only",
+      { sessionManager, sessionOrderManager, browserGateway: gateway },
+      undefined,
+    );
+
+    expect(action).toBe("moveToFront");
+  });
+
+  it("no-ops if session has ended (defensive)", () => {
+    setupSession("A");
+    setupSession("B", "ended");
+    sessionOrderManager.reorder(cwd, ["A", "B"]);
+    broadcasts.length = 0;
+
+    const action = applyReattachPolicy("B", cwd, "always", {
+      sessionManager,
+      sessionOrderManager,
+      browserGateway: gateway,
+    });
+
+    expect(action).toBe("preserve");
+    expect(sessionOrderManager.getOrder(cwd)).toEqual(["A", "B"]);
+    expect(broadcasts).toEqual([]);
+  });
+});

package/packages/server/src/__tests__/restart-helper.test.ts

@@ -108,4 +108,29 @@ describe("buildOrchestratorScript", () => {
     expect(script).toMatch(/const PORT = 8765/);
     expect(script).toMatch(/port: PORT/);
   });
+
+  // See change: fix-restart-bridge-auto-start-race.
+  describe("explicit kill of prior daemon", () => {
+    it("references the dashboard.pid file path", () => {
+      const script = buildOrchestratorScript(baseParams);
+      expect(script).toContain("dashboard.pid");
+      expect(script).toMatch(/const PID_PATH = /);
+    });
+
+    it("defines a killPriorDaemon function that uses SIGTERM then SIGKILL", () => {
+      const script = buildOrchestratorScript(baseParams);
+      expect(script).toMatch(/killPriorDaemon/);
+      expect(script).toMatch(/process\.kill\(\s*pid\s*,\s*"SIGTERM"\s*\)/);
+      expect(script).toMatch(/process\.kill\(\s*pid\s*,\s*"SIGKILL"\s*\)/);
+    });
+
+    it("the kill step runs BEFORE the portFree poll", () => {
+      const script = buildOrchestratorScript(baseParams);
+      const killIdx = script.indexOf("await killPriorDaemon()");
+      const portFreeIdx = script.indexOf("await portFree(PORT)");
+      expect(killIdx).toBeGreaterThan(-1);
+      expect(portFreeIdx).toBeGreaterThan(-1);
+      expect(killIdx).toBeLessThan(portFreeIdx);
+    });
+  });
 });