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

package/packages/server/src/routes/system-routes.ts

@@ -6,6 +6,7 @@ import type { SessionManager } from "../memory-session-manager.js";
 import type { PreferencesStore } from "../preferences-store.js";
 import type { MetaPersistence } from "../meta-persistence.js";
 import type { DirectoryService } from "../directory-service.js";
+import type { PiGateway } from "../pi-gateway.js";
 import type { ServerConfig } from "../server.js";
 import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { NetworkGuard } from "./route-deps.js";
@@ -31,9 +32,23 @@ export function registerSystemRoutes(
     networkGuard: NetworkGuard;
     version?: string;
     directoryService?: DirectoryService;
+    piGateway?: PiGateway;
   },
 ) {
-  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService } = deps;
+  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService, piGateway } = deps;
+
+  // Quiesce windows for the bridge `server_restarting` broadcast. See change
+  // `fix-restart-bridge-auto-start-race`. Bridges that receive this message
+  // suppress only the spawn step in `server-auto-start.ts` for `quiesceMs`;
+  // discovery + reconnection still run.
+  const RESTART_QUIESCE_MS = 5000;
+  const SHUTDOWN_QUIESCE_MS = 60000;
+  const announceRestart = (reason: "restart" | "shutdown", quiesceMs: number) => {
+    if (!piGateway) return;
+    try {
+      piGateway.broadcast({ type: "server_restarting", reason, quiesceMs });
+    } catch { /* best-effort — never block exit on a flaky bridge socket */ }
+  };
   const serverStartTime = Date.now();
 
   // Editor detection endpoint
@@ -196,6 +211,10 @@ export function registerSystemRoutes(
     async () => {
       metaPersistence.flushAll();
       preferencesStore.flush();
+      // Tell every connected bridge that the server is going away deliberately
+      // BEFORE we start tearing down state, so bridges suppress auto-start.
+      // See change: fix-restart-bridge-auto-start-race.
+      announceRestart("shutdown", SHUTDOWN_QUIESCE_MS);
       // Tear down the zrok tunnel (and sweep orphans on our port) so restarts
       // don't leak reservations that leave stale URLs backed by nothing.
       try { await deleteTunnel(config.port); } catch { /* best-effort */ }
@@ -212,6 +231,11 @@ export function registerSystemRoutes(
       metaPersistence.flushAll();
       preferencesStore.flush();
 
+      // Announce restart to every bridge BEFORE spawning the replacement so
+      // bridges suppress their auto-start spawn step and don't race the
+      // orchestrator. See change: fix-restart-bridge-auto-start-race.
+      announceRestart("restart", RESTART_QUIESCE_MS);
+
       // Tear down tunnel before spawning the replacement process so the new
       // server doesn't race an orphan zrok agent on the same port.
       try { await deleteTunnel(config.port); } catch { /* best-effort */ }

package/packages/server/src/server.ts

@@ -20,6 +20,7 @@ import { createSessionOrderManager, type SessionOrderManager } from "./session-o
 import { createPendingForkRegistry, type PendingForkRegistry } from "./pending-fork-registry.js";
 import { createPendingAttachRegistry } from "./pending-attach-registry.js";
 import { createPendingResumeIntentRegistry } from "./pending-resume-intent-registry.js";
+import { applyReattachPolicy } from "./reattach-placement.js";
 
 // pending-load-manager removed — server loads sessions directly via DirectoryService
 import { createDirectoryService, type DirectoryService } from "./directory-service.js";
@@ -282,7 +283,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   }
 
   // Save per-session .meta.json on any change
-  sessionManager.onChange = (sessionId: string) => {
+  sessionManager.onChange = (sessionId: string, ctx) => {
     const session = sessionManager.get(sessionId);
     if (!session?.sessionFile) return;
     metaPersistence.save(session.sessionFile, {
@@ -304,6 +305,9 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       contextTokens: session.contextTokens ?? undefined,
       contextWindow: session.contextWindow,
       firstMessage: session.firstMessage,
+      // Persist unread bit so it survives server restart.
+      // See change: session-card-unread-stripes.
+      unread: session.unread,
       cachedAt: Date.now(),
     });
     // When a session ends, drop its id from the persisted drag-reorder list
@@ -352,17 +356,33 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       endedSessionIds.delete(sessionId);
       const intent = pendingResumeIntents.consume(sessionId);
       if (intent === null) {
-        // Bridge auto-reattach — leave order alone.
+        // No user-driven resume intent. If this register carried
+        // `registerReason: "reattach"`, apply the configured
+        // `reattachPlacement` policy. Otherwise (legacy bridge or
+        // genuine null reattach with `"preserve"` semantics) leave
+        // order alone.
+        // See change: reattach-move-to-front.
+        if (ctx?.registerReason === "reattach") {
+          applyReattachPolicy(
+            sessionId,
+            session.cwd,
+            config.reattachPlacement,
+            { sessionManager, sessionOrderManager, browserGateway },
+            ctx.priorStatus,
+          );
+        }
         return;
       }
       if (intent === "keep") {
         // Drag-to-resume — dropped slot wins; the earlier reorder_sessions
         // already broadcast. Do NOT mutate sessionOrder, do NOT broadcast.
+        // Registry intent overrides any `registerReason: "reattach"`.
         return;
       }
       // intent === "front": move-to-front so the just-resumed card
       // surfaces at the top of the alive tier, even on repeated end →
       // resume cycles where the id might still be in the order.
+      // Registry intent overrides any `registerReason: "reattach"`.
       sessionOrderManager.moveToFront(session.cwd, sessionId);
       const next = sessionOrderManager.getOrder(session.cwd) ?? [];
       browserGateway.broadcastToAll({
@@ -370,6 +390,37 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
         cwd: session.cwd,
         sessionIds: next,
       });
+    } else if (!isEnded && !wasEnded && ctx?.registerReason === "reattach") {
+      // Reattach of a session that was persisted as alive (the common
+      // case after `pi-dashboard restart` while pi processes stay
+      // alive). Neither alive→ended nor ended→alive transition fires;
+      // we apply the reattach policy directly here.
+      //
+      // Defensive: a registry intent for an alive session should not
+      // happen in practice (handleResumeSession only tags intents for
+      // ended sessions), but per spec scenario "Registry intent wins
+      // over reattach" we honor it if present and skip the policy.
+      // See change: reattach-move-to-front.
+      const intent = pendingResumeIntents.consume(sessionId);
+      if (intent === "front") {
+        sessionOrderManager.moveToFront(session.cwd, sessionId);
+        const next = sessionOrderManager.getOrder(session.cwd) ?? [];
+        browserGateway.broadcastToAll({
+          type: "sessions_reordered",
+          cwd: session.cwd,
+          sessionIds: next,
+        });
+      } else if (intent === "keep") {
+        // Honor dropped slot; do nothing.
+      } else {
+        applyReattachPolicy(
+          sessionId,
+          session.cwd,
+          config.reattachPlacement,
+          { sessionManager, sessionOrderManager, browserGateway },
+          ctx.priorStatus,
+        );
+      }
     }
   };
   // Track which session ids we've seen as ended at least once, so the
@@ -503,6 +554,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     knownSessionIds,
     pendingDashboardSpawns,
     pendingAttachRegistry,
+    viewedSessionTracker: browserGateway.viewedSessionTracker,
   });
 
   // Auto-shutdown idle timer
@@ -652,7 +704,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
     },
   });
-  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService });
+  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService, piGateway });
   registerToolRoutes(fastify, { registry: getDefaultRegistry(), networkGuard });
 
   // ── Bootstrap REST routes ────────────────────────────────────────

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

@@ -38,6 +38,19 @@ function extractTimestamp(filename: string): number {
   return isNaN(ts) ? Date.now() : ts;
 }
 
+/**
+ * Read the events.jsonl mtime as a cold-start seed for `lastActivityAt`.
+ * Returns `undefined` on stat failure — callers fall back to `startedAt` at
+ * render time. See change: session-card-last-activity-badge.
+ */
+function readJsonlMtime(sessionFile: string): number | undefined {
+  try {
+    return statSync(sessionFile).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Build a DashboardSession from cached `.meta.json` data */
 function sessionFromMeta(
   sessionId: string,
@@ -56,6 +69,9 @@ function sessionFromMeta(
     thinkingLevel: meta.thinkingLevel,
     startedAt: meta.startedAt ?? startedAt,
     endedAt: meta.endedAt,
+    // Seed last-activity from events.jsonl mtime so the session-card relative-time
+    // badge survives server restarts. See change: session-card-last-activity-badge.
+    lastActivityAt: readJsonlMtime(sessionFile),
     tokensIn: meta.tokensIn ?? 0,
     tokensOut: meta.tokensOut ?? 0,
     cacheRead: meta.cacheRead,
@@ -68,6 +84,9 @@ function sessionFromMeta(
     hidden: meta.hidden ?? false,
     firstMessage: meta.firstMessage,
     attachedProposal: meta.attachedProposal,
+    // Restore unread bit from .meta.json so it survives server restart.
+    // See change: session-card-unread-stripes.
+    unread: meta.unread,
     dataUnavailable: true,
   };
 }

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

@@ -0,0 +1,78 @@
+/**
+ * Viewed-session tracker.
+ *
+ * Per-session set of WebSocket connections that are currently displaying
+ * the session's chat panel (typically the browser is on `/session/:id`).
+ * Used by:
+ *   - `event-wiring.ts` to gate `isUnreadTrigger`-driven `unread = true`
+ *     stamps so a session being actively watched never becomes unread.
+ *   - the `session_view` handler in `browser-gateway.ts` to clear unread
+ *     when any browser opens an unread session.
+ *
+ * Read state is GLOBAL across browsers: a session is "viewed" iff at
+ * least one connected client has it open. This mirrors mail/Slack:
+ * opening on phone clears unread for the laptop too.
+ *
+ * In-memory only — view state is intrinsically per-connection and has
+ * no value to persist.
+ *
+ * See change: session-card-unread-stripes.
+ */
+
+import type { WebSocket } from "ws";
+
+export interface ViewedSessionTracker {
+  /** Mark `ws` as viewing `sessionId`. Idempotent. */
+  view(sessionId: string, ws: WebSocket): void;
+  /** Mark `ws` as no longer viewing `sessionId`. Idempotent. */
+  unview(sessionId: string, ws: WebSocket): void;
+  /**
+   * Remove `ws` from every viewed session. Called from the WebSocket
+   * `close` handler so a disconnected browser cannot hold sessions in
+   * the viewed state forever.
+   */
+  unviewAll(ws: WebSocket): void;
+  /** Returns true if at least one connected browser views the session. */
+  isViewedByAnyone(sessionId: string): boolean;
+  /** Test/diagnostic accessor — number of viewers for a session. */
+  viewerCount(sessionId: string): number;
+}
+
+export function createViewedSessionTracker(): ViewedSessionTracker {
+  const viewers = new Map<string, Set<WebSocket>>();
+
+  return {
+    view(sessionId: string, ws: WebSocket): void {
+      let set = viewers.get(sessionId);
+      if (!set) {
+        set = new Set<WebSocket>();
+        viewers.set(sessionId, set);
+      }
+      set.add(ws);
+    },
+
+    unview(sessionId: string, ws: WebSocket): void {
+      const set = viewers.get(sessionId);
+      if (!set) return;
+      set.delete(ws);
+      if (set.size === 0) viewers.delete(sessionId);
+    },
+
+    unviewAll(ws: WebSocket): void {
+      for (const [sessionId, set] of viewers) {
+        if (set.delete(ws) && set.size === 0) {
+          viewers.delete(sessionId);
+        }
+      }
+    },
+
+    isViewedByAnyone(sessionId: string): boolean {
+      const set = viewers.get(sessionId);
+      return !!set && set.size > 0;
+    },
+
+    viewerCount(sessionId: string): number {
+      return viewers.get(sessionId)?.size ?? 0;
+    },
+  };
+}

package/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-shared",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Shared types and utilities for pi-dashboard",
   "type": "module",
   "repository": {

package/packages/shared/src/__tests__/config.test.ts

@@ -412,3 +412,62 @@ describe("ensureConfig", () => {
     expect(content.piPort).toBeUndefined();
   });
 });
+
+describe("loadConfig reattachPlacement", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-reattach-${Date.now()}-${Math.random()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("defaults to 'always' when missing", () => {
+    fs.writeFileSync(configFile, JSON.stringify({}));
+    expect(loadConfig().reattachPlacement).toBe("always");
+  });
+
+  it("defaults to 'always' when config file does not exist", () => {
+    expect(loadConfig().reattachPlacement).toBe("always");
+  });
+
+  it("accepts 'preserve'", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ reattachPlacement: "preserve" }));
+    expect(loadConfig().reattachPlacement).toBe("preserve");
+  });
+
+  it("accepts 'streaming-only'", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ reattachPlacement: "streaming-only" }));
+    expect(loadConfig().reattachPlacement).toBe("streaming-only");
+  });
+
+  it("accepts 'always' explicitly", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ reattachPlacement: "always" }));
+    expect(loadConfig().reattachPlacement).toBe("always");
+  });
+
+  it("falls back to 'always' on invalid string", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ reattachPlacement: "wibble" }));
+    expect(loadConfig().reattachPlacement).toBe("always");
+  });
+
+  it("falls back to 'always' on non-string", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ reattachPlacement: 42 }));
+    expect(loadConfig().reattachPlacement).toBe("always");
+  });
+
+  it("ensureConfig does NOT write reattachPlacement to defaults", () => {
+    ensureConfig();
+    const content = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+    expect(content.reattachPlacement).toBeUndefined();
+  });
+});

package/packages/shared/src/__tests__/mdns-discovery.test.ts

@@ -1,6 +1,53 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import os from "node:os";
-import { isLocalService, type DiscoveredServer } from "../mdns-discovery.js";
+import { isLocalService, pickBestHost, type DiscoveredServer } from "../mdns-discovery.js";
+
+describe("pickBestHost", () => {
+  it("keeps a DNS-safe hostname unchanged", () => {
+    const service = { host: "my-mac.local", addresses: ["192.168.1.5"] } as any;
+    expect(pickBestHost(service)).toBe("my-mac.local");
+  });
+
+  it("keeps a bare DNS-safe hostname unchanged", () => {
+    const service = { host: "macbook", addresses: ["192.168.1.5"] } as any;
+    expect(pickBestHost(service)).toBe("macbook");
+  });
+
+  it("falls back to IPv4 address when host has a space", () => {
+    const service = { host: "MacBook 242", addresses: ["192.168.16.242", "fe80::1"] } as any;
+    expect(pickBestHost(service)).toBe("192.168.16.242");
+  });
+
+  it("falls back to IPv4 when host has invalid characters", () => {
+    const service = { host: "my_mac@home", addresses: ["10.0.0.5"] } as any;
+    expect(pickBestHost(service)).toBe("10.0.0.5");
+  });
+
+  it("prefers IPv4 over IPv6 when both are present", () => {
+    const service = { host: "bad host", addresses: ["fe80::1", "192.168.1.7"] } as any;
+    expect(pickBestHost(service)).toBe("192.168.1.7");
+  });
+
+  it("falls back to first address when only IPv6 is available", () => {
+    const service = { host: "bad host", addresses: ["fe80::1"] } as any;
+    expect(pickBestHost(service)).toBe("fe80::1");
+  });
+
+  it("returns the original host when no addresses available (best-effort)", () => {
+    const service = { host: "bad host", addresses: [] } as any;
+    expect(pickBestHost(service)).toBe("bad host");
+  });
+
+  it("returns 'unknown' when host is missing and no addresses", () => {
+    const service = { host: undefined, addresses: [] } as any;
+    expect(pickBestHost(service)).toBe("unknown");
+  });
+
+  it("rejects host starting with hyphen", () => {
+    const service = { host: "-bad", addresses: ["10.0.0.1"] } as any;
+    expect(pickBestHost(service)).toBe("10.0.0.1");
+  });
+});
 
 // Test isLocalService with mock Service objects
 describe("isLocalService", () => {