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

package/packages/extension/src/__tests__/connection-suppress-auto-start.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Tests for the auto-start suppression window driven by `server_restarting`.
+ * See change: fix-restart-bridge-auto-start-race.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { ConnectionManager } from "../connection.js";
+import { autoStartServer, type AutoStartDeps } from "../server-auto-start.js";
+
+describe("ConnectionManager.pauseAutoStart", () => {
+  let cm: ConnectionManager;
+
+  beforeEach(() => {
+    cm = new ConnectionManager({
+      url: "ws://localhost:9999",
+      WebSocketImpl: class FakeWS { constructor() { /* never connects */ } onopen?: any; onmessage?: any; onclose?: any; onerror?: any; close() { /* no-op */ } },
+      watchdogTimeout: 0,
+    });
+  });
+
+  it("returns false when no pause has been issued", () => {
+    expect(cm.shouldSuppressAutoStart()).toBe(false);
+  });
+
+  it("returns true within the requested window", () => {
+    cm.pauseAutoStart(5000);
+    expect(cm.shouldSuppressAutoStart()).toBe(true);
+  });
+
+  it("returns false after the window expires", async () => {
+    vi.useFakeTimers();
+    cm.pauseAutoStart(100);
+    expect(cm.shouldSuppressAutoStart()).toBe(true);
+    vi.advanceTimersByTime(150);
+    expect(cm.shouldSuppressAutoStart()).toBe(false);
+    vi.useRealTimers();
+  });
+
+  it("ignores non-positive durations", () => {
+    cm.pauseAutoStart(0);
+    expect(cm.shouldSuppressAutoStart()).toBe(false);
+    cm.pauseAutoStart(-1000);
+    expect(cm.shouldSuppressAutoStart()).toBe(false);
+  });
+
+  it("only extends the window — overlapping pauses don't shrink it", () => {
+    vi.useFakeTimers();
+    cm.pauseAutoStart(10_000);
+    cm.pauseAutoStart(100); // shorter — must not shrink
+    vi.advanceTimersByTime(500);
+    expect(cm.shouldSuppressAutoStart()).toBe(true);
+    vi.useRealTimers();
+  });
+});
+
+describe("autoStartServer respects shouldSuppressAutoStart", () => {
+  function makeDeps(overrides: Partial<AutoStartDeps> = {}): AutoStartDeps {
+    return {
+      discoverDashboard: vi.fn().mockResolvedValue([]),
+      isDashboardRunning: vi.fn().mockResolvedValue({ running: false }),
+      launchServer: vi.fn().mockResolvedValue({ success: true, message: "ok" }),
+      notify: vi.fn(),
+      ...overrides,
+    };
+  }
+
+  const baseConfig = { piPort: 9999, port: 8000, autoStart: true };
+
+  it("skips launchServer while suppression is active", async () => {
+    const deps = makeDeps({ shouldSuppressAutoStart: () => true });
+    const result = await autoStartServer(baseConfig, deps);
+    expect(deps.launchServer).not.toHaveBeenCalled();
+    expect(result.server).toBeUndefined();
+  });
+
+  it("still runs discovery + health check when suppressed", async () => {
+    const deps = makeDeps({
+      shouldSuppressAutoStart: () => true,
+      isDashboardRunning: vi.fn().mockResolvedValue({ running: true }),
+    });
+    const result = await autoStartServer(baseConfig, deps);
+    // Health check found the orchestrator-spawned server — return it.
+    expect(result.server).toEqual({ host: "localhost", port: 8000, piPort: 9999 });
+    expect(deps.launchServer).not.toHaveBeenCalled();
+  });
+
+  it("calls launchServer normally when not suppressed", async () => {
+    const deps = makeDeps({ shouldSuppressAutoStart: () => false });
+    await autoStartServer(baseConfig, deps);
+    expect(deps.launchServer).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls launchServer when no predicate is provided (back-compat)", async () => {
+    const deps = makeDeps(); // no shouldSuppressAutoStart
+    await autoStartServer(baseConfig, deps);
+    expect(deps.launchServer).toHaveBeenCalledTimes(1);
+  });
+});

package/packages/extension/src/__tests__/session-sync.test.ts

@@ -2,7 +2,7 @@
  * Tests for session-sync: sendStateSync and handleSessionSwitch.
  */
 import { describe, it, expect, vi } from "vitest";
-import { sendStateSync } from "../session-sync.js";
+import { sendStateSync, handleSessionChange } from "../session-sync.js";
 import type { BridgeContext } from "../bridge-context.js";
 
 function createMockBridgeContext(overrides?: Partial<BridgeContext>): BridgeContext {
@@ -34,6 +34,7 @@ function createMockBridgeContext(overrides?: Partial<BridgeContext>): BridgeCont
     lastGitBranch: undefined,
     lastGitPrNumber: undefined,
     lastSessionName: undefined,
+    hasRegisteredOnce: false,
     ...overrides,
     // Expose sent messages for assertions
     _sent: sent,
@@ -52,4 +53,83 @@ describe("sendStateSync", () => {
     expect(typeof registerMsg.pid).toBe("number");
     expect(registerMsg.pid).toBeGreaterThan(0);
   });
+
+  // ── reattach-move-to-front ──
+
+  it("first sendStateSync after boot tags registerReason: spawn", () => {
+    const bc = createMockBridgeContext();
+    expect(bc.hasRegisteredOnce).toBe(false);
+
+    sendStateSync(bc, () => []);
+
+    const sent = (bc as any)._sent;
+    const registerMsg = sent.find((m: any) => m.type === "session_register");
+    expect(registerMsg.registerReason).toBe("spawn");
+    expect(bc.hasRegisteredOnce).toBe(true);
+  });
+
+  it("second sendStateSync (reconnect) tags registerReason: reattach", () => {
+    const bc = createMockBridgeContext();
+
+    sendStateSync(bc, () => []);
+    // Clear sent, simulate reconnect
+    (bc as any)._sent.length = 0;
+    sendStateSync(bc, () => []);
+
+    const sent = (bc as any)._sent;
+    const registerMsg = sent.find((m: any) => m.type === "session_register");
+    expect(registerMsg.registerReason).toBe("reattach");
+    expect(bc.hasRegisteredOnce).toBe(true);
+  });
+
+  it("hasRegisteredOnce flips exactly once and stays true", () => {
+    const bc = createMockBridgeContext();
+
+    sendStateSync(bc, () => []);
+    expect(bc.hasRegisteredOnce).toBe(true);
+
+    sendStateSync(bc, () => []);
+    expect(bc.hasRegisteredOnce).toBe(true);
+
+    sendStateSync(bc, () => []);
+    expect(bc.hasRegisteredOnce).toBe(true);
+  });
+
+  it("third+ sendStateSync continues to tag reattach", () => {
+    const bc = createMockBridgeContext();
+
+    sendStateSync(bc, () => []);
+    sendStateSync(bc, () => []);
+    (bc as any)._sent.length = 0;
+    sendStateSync(bc, () => []);
+
+    const sent = (bc as any)._sent;
+    const registerMsg = sent.find((m: any) => m.type === "session_register");
+    expect(registerMsg.registerReason).toBe("reattach");
+  });
+});
+
+describe("handleSessionChange", () => {
+  it("always tags registerReason: spawn even after reattach", () => {
+    const bc = createMockBridgeContext({ hasRegisteredOnce: true } as any);
+
+    const ctx = {
+      cwd: "/proj",
+      sessionManager: {
+        getSessionId: () => "sess-new",
+        getSessionFile: () => "/path/new.json",
+        getSessionDir: () => "/path",
+        getBranch: () => [],
+        getEntries: () => [],
+      },
+    };
+
+    handleSessionChange(bc, ctx as any, () => []);
+
+    const sent = (bc as any)._sent;
+    const registerMsg = sent.find((m: any) => m.type === "session_register");
+    expect(registerMsg).toBeDefined();
+    expect(registerMsg.sessionId).toBe("sess-new");
+    expect(registerMsg.registerReason).toBe("spawn");
+  });
 });

package/packages/extension/src/bridge-context.ts

@@ -21,6 +21,16 @@ export interface BridgeContext {
   lastGitBranch: string | undefined;
   lastGitPrNumber: number | undefined;
   lastSessionName: string | undefined;
+  /**
+   * `false` until the very first `sendStateSync` after the bridge
+   * process boots; `true` for the rest of the process lifetime.
+   * Drives `registerReason` on `session_register` so the server can
+   * distinguish initial spawn vs. dashboard-restart reattach.
+   * `handleSessionChange` (new/fork/resume) ignores this flag and
+   * always tags `"spawn"` because it mints a fresh sessionId.
+   * See change: reattach-move-to-front.
+   */
+  hasRegisteredOnce: boolean;
 }
 
 // Commands that the dashboard handles natively with superior UX.

package/packages/extension/src/bridge.ts

@@ -186,6 +186,7 @@ function initBridge(pi: ExtensionAPI) {
   let cachedCtx: any | undefined = prev.ctx;
   let lastModel: string | undefined;
   let lastThinkingLevel: string | undefined;
+  let hasRegisteredOnce = false; // see change: reattach-move-to-front
   let promptBus: PromptBus | undefined;
 
   // ── Per-message entry id tracking (for fix-per-message-fork) ──
@@ -288,6 +289,20 @@ function initBridge(pi: ExtensionAPI) {
         handleUiManagement(uiModulesBridgeCtx, msg as any);
         return;
       }
+      // Server announced a deliberate restart/shutdown. Pause the auto-start
+      // spawn step in `server-auto-start.ts` for `quiesceMs` so we don't
+      // race the orchestrator that's about to bring up the replacement.
+      // Discovery + reconnection still run via the normal backoff path.
+      // See change: fix-restart-bridge-auto-start-race.
+      if ((msg as any).type === "server_restarting") {
+        const reason = (msg as any).reason;
+        const quiesceMs = (msg as any).quiesceMs;
+        if (typeof quiesceMs === "number" && quiesceMs > 0) {
+          connection.pauseAutoStart(quiesceMs);
+          console.log(`[dashboard] server announced restart (reason=${reason} quiesceMs=${quiesceMs})`);
+        }
+        return;
+      }
       // Legacy extension_ui_response removed — now handled by prompt_response → promptBus.respond()
       // Reload auth credentials when dashboard notifies of changes
       if (msg.type === "credentials_updated") {
@@ -596,6 +611,7 @@ function initBridge(pi: ExtensionAPI) {
       lastModel, lastThinkingLevel,
       lastSessionFile, lastSessionDir, lastFirstMessage,
       lastGitBranch, lastGitPrNumber, lastSessionName,
+      hasRegisteredOnce,
     };
   }
   /** Sync BridgeContext mutations back to local variables */
@@ -612,6 +628,7 @@ function initBridge(pi: ExtensionAPI) {
     lastGitBranch = bc.lastGitBranch;
     lastGitPrNumber = bc.lastGitPrNumber;
     lastSessionName = bc.lastSessionName;
+    hasRegisteredOnce = bc.hasRegisteredOnce;
   }
 
   // Local wrappers that sync bc around extracted module calls
@@ -1195,6 +1212,11 @@ function initBridge(pi: ExtensionAPI) {
       onLaunchEnd: () => {
         stopSpinner();
       },
+      // Honor the server's `server_restarting` quiesce window. While a
+      // deliberate restart/shutdown is in flight, skip the spawn step so we
+      // don't race the orchestrator. Discovery + reconnection still run.
+      // See change: fix-restart-bridge-auto-start-race.
+      shouldSuppressAutoStart: () => connection.shouldSuppressAutoStart(),
     }).then((result) => {
       stopSpinner(); // safety net — covers onLaunchEnd not firing
       if (result.server && result.server.piPort !== config.piPort) {

package/packages/extension/src/connection.ts

@@ -35,6 +35,16 @@ export class ConnectionManager {
   private watchdogTimer: ReturnType<typeof setInterval> | null = null;
   private watchdogTimeout: number;
 
+  /**
+   * Auto-start suppression deadline (epoch ms). When the server announces
+   * a deliberate restart/shutdown via `server_restarting`, the bridge sets
+   * this to `Date.now() + quiesceMs` so the spawn step in `autoStartServer`
+   * is skipped while the orchestrator does its work. Discovery + reconnect
+   * are NOT suppressed.
+   * See change: fix-restart-bridge-auto-start-race.
+   */
+  private suppressUntil = 0;
+
   constructor(options: ConnectionManagerOptions) {
     this.url = options.url;
     this.WS = options.WebSocketImpl ?? (globalThis as any).WebSocket;
@@ -90,6 +100,25 @@ export class ConnectionManager {
     return this.ws?.readyState === 1;
   }
 
+  /**
+   * Pause auto-start spawn for `ms` milliseconds. Idempotent: only extends
+   * the suppression window, never shortens it. See change:
+   * fix-restart-bridge-auto-start-race.
+   */
+  pauseAutoStart(ms: number): void {
+    if (!Number.isFinite(ms) || ms <= 0) return;
+    const next = Date.now() + ms;
+    if (next > this.suppressUntil) this.suppressUntil = next;
+  }
+
+  /**
+   * Returns true while the auto-start spawn step should be suppressed.
+   * See change: fix-restart-bridge-auto-start-race.
+   */
+  shouldSuppressAutoStart(): boolean {
+    return Date.now() < this.suppressUntil;
+  }
+
   /**
    * Update the WebSocket URL and reconnect.
    * Used when mDNS discovers the server on a different address/port.

package/packages/extension/src/server-auto-start.ts

@@ -32,6 +32,14 @@ export interface AutoStartDeps {
    * Passes the final success state so the caller can clear spinners.
    */
   onLaunchEnd?: (success: boolean) => void;
+  /**
+   * Optional predicate. When it returns true, the auto-start spawn step
+   * (step 3 below) is skipped — mDNS discovery + health check still run,
+   * so the bridge will pick up the orchestrator-spawned replacement as
+   * soon as it advertises. Used by the bridge to honor `server_restarting`
+   * bursts. See change: fix-restart-bridge-auto-start-race.
+   */
+  shouldSuppressAutoStart?: () => boolean;
 }
 
 export interface AutoStartResult {
@@ -73,6 +81,14 @@ export async function autoStartServer(
     return {};
   }
 
+  // Suppress the spawn step while a deliberate restart/shutdown is in
+  // flight. Discovery + health check above already ran, so if the
+  // orchestrator has finished bringing up the replacement we already
+  // returned. See change: fix-restart-bridge-auto-start-race.
+  if (deps.shouldSuppressAutoStart?.()) {
+    return {};
+  }
+
   // 3. Auto-start server
   deps.onLaunchStart?.();
   const result = await deps.launchServer(config);

package/packages/extension/src/session-sync.ts

@@ -33,6 +33,13 @@ export function sendStateSync(
     if (entries) eventCount = entries.length;
   } catch { /* ignore */ }
 
+  // Tag the very first sendStateSync after process boot as "spawn";
+  // every subsequent invocation (driven by WebSocket reconnect after a
+  // dashboard restart) is a "reattach". Server applies the configured
+  // `reattachPlacement` policy on "reattach".
+  // See change: reattach-move-to-front.
+  const registerReason: "spawn" | "reattach" = bc.hasRegisteredOnce ? "reattach" : "spawn";
+
   bc.connection.send({
     type: "session_register",
     sessionId: bc.sessionId,
@@ -46,8 +53,11 @@ export function sendStateSync(
     firstMessage,
     eventCount,
     pid: process.pid,
+    registerReason,
   });
 
+  bc.hasRegisteredOnce = true;
+
   const commands = filterHiddenCommands(bc.pi.getCommands());
   bc.connection.send({ type: "commands_list", sessionId: bc.sessionId, commands });
 
@@ -111,6 +121,9 @@ export function handleSessionChange(
     if (entries) eventCount = entries.length;
   } catch { /* ignore */ }
 
+  // handleSessionChange always mints a fresh sessionId (new/fork/resume),
+  // so registerReason is unconditionally "spawn" — even after the bridge
+  // has previously reattached. See change: reattach-move-to-front.
   bc.connection.send({
     type: "session_register",
     sessionId: bc.sessionId,
@@ -124,6 +137,7 @@ export function handleSessionChange(
     firstMessage,
     eventCount,
     pid: process.pid,
+    registerReason: "spawn",
   });
 
   replaySessionEntries(bc);

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "repository": {
@@ -31,9 +31,9 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/dashboard-plugin-runtime": "^0.4.4",
-    "@blackbelt-technology/pi-dashboard-extension": "^0.4.4",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.4.4",
+    "@blackbelt-technology/dashboard-plugin-runtime": "^0.4.5",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.4.5",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.4.5",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",

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

@@ -0,0 +1,78 @@
+/**
+ * Tests for `cmdRestart` — `pi-dashboard restart` delegates to `/api/restart`
+ * when the dashboard is up, falls back to local stop/start when it is not.
+ * See change: fix-restart-bridge-auto-start-race.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { cmdRestart } from "../cli.js";
+import type { ServerConfig } from "../server.js";
+
+function makeConfig(overrides: Partial<ServerConfig> = {}): ServerConfig {
+  return {
+    port: 8000,
+    piPort: 9999,
+    dev: false,
+    autoShutdown: false,
+    shutdownIdleSeconds: 0,
+    tunnel: false,
+    maxWsBufferBytes: 0,
+    ...overrides,
+  } as ServerConfig;
+}
+
+describe("cmdRestart", () => {
+  it("delegates to /api/restart when dashboard is running", async () => {
+    const fetchImpl = vi.fn(async () => ({ ok: true, status: 200, text: async () => "" })) as unknown as typeof fetch;
+    const cmdStopImpl = vi.fn(async () => {});
+    const cmdStartImpl = vi.fn(async () => {});
+    const isDashboardRunning = vi.fn(async () => ({ running: true }));
+
+    await cmdRestart(makeConfig({ dev: true }), { isDashboardRunning, fetchImpl, cmdStopImpl, cmdStartImpl });
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, init] = (fetchImpl as any).mock.calls[0];
+    expect(url).toBe("http://localhost:8000/api/restart");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body)).toEqual({ dev: true });
+    expect(cmdStopImpl).not.toHaveBeenCalled();
+    expect(cmdStartImpl).not.toHaveBeenCalled();
+  });
+
+  it("falls back to cmdStop + cmdStart when dashboard is NOT running", async () => {
+    const fetchImpl = vi.fn() as unknown as typeof fetch;
+    const cmdStopImpl = vi.fn(async () => {});
+    const cmdStartImpl = vi.fn(async () => {});
+    const isDashboardRunning = vi.fn(async () => ({ running: false }));
+
+    await cmdRestart(makeConfig(), { isDashboardRunning, fetchImpl, cmdStopImpl, cmdStartImpl });
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+    expect(cmdStopImpl).toHaveBeenCalledTimes(1);
+    expect(cmdStartImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to local stop/start when /api/restart returns non-2xx", async () => {
+    const fetchImpl = vi.fn(async () => ({ ok: false, status: 500, text: async () => "boom" })) as unknown as typeof fetch;
+    const cmdStopImpl = vi.fn(async () => {});
+    const cmdStartImpl = vi.fn(async () => {});
+    const isDashboardRunning = vi.fn(async () => ({ running: true }));
+
+    await cmdRestart(makeConfig(), { isDashboardRunning, fetchImpl, cmdStopImpl, cmdStartImpl });
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(cmdStopImpl).toHaveBeenCalledTimes(1);
+    expect(cmdStartImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to local stop/start when fetch throws", async () => {
+    const fetchImpl = vi.fn(async () => { throw new Error("ECONNREFUSED"); }) as unknown as typeof fetch;
+    const cmdStopImpl = vi.fn(async () => {});
+    const cmdStartImpl = vi.fn(async () => {});
+    const isDashboardRunning = vi.fn(async () => ({ running: true }));
+
+    await cmdRestart(makeConfig(), { isDashboardRunning, fetchImpl, cmdStopImpl, cmdStartImpl });
+
+    expect(cmdStopImpl).toHaveBeenCalledTimes(1);
+    expect(cmdStartImpl).toHaveBeenCalledTimes(1);
+  });
+});

package/packages/server/src/__tests__/config-api.test.ts

@@ -168,5 +168,14 @@ describe("config-api", () => {
       const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
       expect(written.auth.bypassUrls).toEqual(["/webhooks/", "/metrics"]);
     });
+
+    it("should persist reattachPlacement (change: reattach-move-to-front)", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+      const result = writeConfigPartial({ reattachPlacement: "preserve" });
+      expect(result.success).toBe(true);
+      const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      expect(written.reattachPlacement).toBe("preserve");
+      expect(written.port).toBe(8000); // existing fields preserved
+    });
   });
 });

package/packages/server/src/__tests__/is-activity-event.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { isActivityEvent } from "../event-status-extraction.js";
+
+/**
+ * Activity-event allowlist for `session.lastActivityAt` stamping.
+ * See change: session-card-last-activity-badge.
+ */
+describe("isActivityEvent", () => {
+  describe("included (user-or-agent action)", () => {
+    const included = [
+      "prompt_send",
+      "message_start",
+      "message_end",
+      "turn_end",
+      "tool_execution_start",
+      "tool_execution_end",
+      "agent_start",
+      "agent_end",
+      "bash_output",
+      "flow_started",
+      "flow_complete",
+      "flow_agent_started",
+      "flow_agent_complete",
+      "architect_started",
+      "architect_complete",
+      "architect_cancelled",
+    ];
+
+    for (const t of included) {
+      it(`returns true for "${t}"`, () => {
+        expect(isActivityEvent(t)).toBe(true);
+      });
+    }
+  });
+
+  describe("excluded (plumbing / noise / UI state)", () => {
+    const excluded = [
+      // Pure heartbeat / metrics
+      "process_metrics",
+      "heartbeat",
+      // Stats roll-ups (covered by turn_end)
+      "stats_update",
+      // Selection / config
+      "model_select",
+      // Git polling
+      "git_info_update",
+      // OpenSpec polling
+      "openspec_update",
+      // Extension UI plumbing
+      "ui_modules_list",
+      "ui_data_list",
+      "ext_ui_decorator",
+      // Command UI noise
+      "command_feedback",
+      // Internal entry tracking
+      "entry_persisted",
+      // Lifecycle (not event_forward types, but defensive)
+      "session_register",
+      "session_unregister",
+    ];
+
+    for (const t of excluded) {
+      it(`returns false for "${t}"`, () => {
+        expect(isActivityEvent(t)).toBe(false);
+      });
+    }
+  });
+
+  describe("unknown event types", () => {
+    it("returns false for an unknown type", () => {
+      expect(isActivityEvent("definitely_not_a_real_event")).toBe(false);
+    });
+
+    it("returns false for empty string", () => {
+      expect(isActivityEvent("")).toBe(false);
+    });
+  });
+});