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

package/packages/shared/src/platform/node-spawn.ts

@@ -116,6 +116,36 @@ export function toFileUrl(pathOrUrl: string): string {
  *
  * Keeps a `platform` parameter for testability so unit tests on a POSIX
  * host can exercise the Windows branch without mutating `process.platform`.
+ *
+ * !! JITI VERSION CONTRACT !!
+ * The Windows-non-tsx arm assumes the jiti loader is from
+ * `@mariozechner/pi-coding-agent@0.70.x` (jiti 2.x with the `file:///`
+ * triple-slash URL handling fix). jiti 2.x correctly handles `file:///`
+ * URL entries on Windows — it was the version we carved this contract
+ * around in change `fix-windows-entry-script-url`.
+ *
+ * Newer jiti versions (e.g. jiti 2.6.5 in `pi-coding-agent@0.71.x`)
+ * MISBEHAVE on `file:///` entries: they normalize triple-slash to
+ * single-slash and prepend cwd as if the entry were a relative
+ * specifier, producing `<cwd>/file:/...` ENOENT errors.
+ *
+ * The Electron Windows codepath defends against this version drift by
+ * resolving jiti from the managed dir's `pi-coding-agent@0.70.0` (the
+ * version pinned in `packages/electron/offline-packages.json` and
+ * extracted into `~/.pi-dashboard/` by `installStandalone()` on first
+ * launch — see Defect 1 of change
+ * `fix-electron-windows-installer-and-server-bootstrap`). Since the
+ * managed-dir tree is pinned, the contract holds regardless of what
+ * jiti is on the user's PATH.
+ *
+ * If a future change bumps the offline-cacache `pi-coding-agent` pin to
+ * a version with a different jiti, RE-VERIFY this contract on Windows
+ * manually (run a packaged Electron app on Win10 + Win11) and either:
+ *   1. Update the contract (fix the file:// URL handling expectation), OR
+ *   2. Add a per-jiti-version branch here, OR
+ *   3. Switch the bundled loader to tsx (which has its own contract).
+ *
+ * Locked by `node-spawn-jiti-contract.test.ts`.
  */
 export function shouldUrlWrapEntry(
   loader: string | null | undefined,

package/packages/shared/src/protocol.ts

@@ -22,6 +22,18 @@ export interface SessionRegisterMessage {
   eventCount?: number;
   /** OS process ID of the pi agent — used for force-kill escalation */
   pid?: number;
+  /**
+   * Why the bridge is registering this session. The bridge sets this to
+   * `"spawn"` for the very first `session_register` after process boot
+   * and for every register emitted by the new/fork/resume path
+   * (`handleSessionChange`), and `"reattach"` for any subsequent
+   * `sendStateSync` triggered by a WebSocket reconnect to the dashboard
+   * server (i.e. the dashboard restarted while the bridge stayed alive).
+   * When omitted (legacy bridges), the server treats the message as if
+   * `"spawn"` was specified.
+   * See change: reattach-move-to-front.
+   */
+  registerReason?: "spawn" | "reattach";
 }
 
 export interface SessionUnregisterMessage {
@@ -463,6 +475,22 @@ export interface PromptResponseServerMessage {
   source: string;
 }
 
+/**
+ * Server → extension: the dashboard server is about to exit as part of a
+ * deliberate restart or shutdown. Bridges that receive this MUST suppress
+ * the spawn step in `server-auto-start.ts` for `quiesceMs` ms; mDNS
+ * discovery + health-check probes still run, so reconnection to the
+ * orchestrator-spawned replacement is unaffected.
+ *
+ * See change: fix-restart-bridge-auto-start-race.
+ */
+export interface ServerRestartingExtensionMessage {
+  type: "server_restarting";
+  reason: "restart" | "shutdown";
+  /** Suppression window in ms. Default 5000 for restart, 60000 for shutdown. */
+  quiesceMs: number;
+}
+
 export type ServerToExtensionMessage =
   | SendPromptToExtensionMessage
   | AbortToExtensionMessage
@@ -489,4 +517,5 @@ export type ServerToExtensionMessage =
   | RolePresetDeleteExtensionMessage
   | RequestRolesMessage
   | UiManagementMessage
-  | KillProcessMessage;
+  | KillProcessMessage
+  | ServerRestartingExtensionMessage;

package/packages/shared/src/session-meta.ts

@@ -18,6 +18,12 @@ export interface SessionMeta {
   // Cached identity & state (from .jsonl header / bridge)
   cwd?: string;
   status?: string;
+  /**
+   * Per-session unread bit; mirrors `DashboardSession.unread`. Persists across
+   * server restarts so an unread session stays unread until viewed.
+   * See change: session-card-unread-stripes.
+   */
+  unread?: boolean;
   startedAt?: number;
   endedAt?: number;
   firstMessage?: string;

package/packages/shared/src/types.ts

@@ -15,6 +15,25 @@ export interface DashboardSession {
   thinkingLevel?: string;
   startedAt: number;
   endedAt?: number;
+  /**
+   * Epoch ms timestamp of the most recent activity event observed for this
+   * session. Server-managed: stamped in `event-wiring.ts` whenever an
+   * `event_forward` arrives whose `eventType` is on the activity-event
+   * allowlist (`isActivityEvent`). NOT persisted to `.meta.json`; cold-start
+   * seeded from `events.jsonl` mtime in `session-scanner.ts`. Drives the
+   * session-card relative-time badge via `selectBadgeTimestamp`.
+   * See change: session-card-last-activity-badge.
+   */
+  lastActivityAt?: number;
+  /**
+   * Server-managed per-session unread bit. `true` when an attention-worthy
+   * event (turn finished, ask_user appeared, agent_end with error) fired
+   * while no browser was viewing the session. Cleared when any browser
+   * sends `session_view`. Persisted to `.meta.json` so it survives reload.
+   * Bridges SHALL NOT send this field.
+   * See change: session-card-unread-stripes.
+   */
+  unread?: boolean;
   tokensIn?: number;
   tokensOut?: number;
   cacheRead?: number;