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

package/packages/server/src/browser-gateway.ts

@@ -17,6 +17,7 @@ import type { SessionOrderManager } from "./session-order-manager.js";
 import type { PreferencesStore } from "./preferences-store.js";
 import type { DirectoryService } from "./directory-service.js";
 import { createPendingResumeRegistry, type PendingResumeRegistry } from "./pending-resume-registry.js";
+import { createViewedSessionTracker, type ViewedSessionTracker } from "./viewed-session-tracker.js";
 import type { TerminalManager } from "./terminal-manager.js";
 import type { BrowserHandlerContext } from "./browser-handlers/handler-context.js";
 import { handleSubscribe } from "./browser-handlers/subscription-handler.js";
@@ -53,6 +54,12 @@ export interface BrowserGateway {
   headlessPidRegistry: HeadlessPidRegistry;
   /** Registry for pending auto-resume prompts */
   pendingResumeRegistry: PendingResumeRegistry;
+  /**
+   * Tracker for which browser is currently viewing which session. Used by
+   * the unread-trigger evaluation in event-wiring.ts.
+   * See change: session-card-unread-stripes.
+   */
+  viewedSessionTracker: ViewedSessionTracker;
   /** Send a message to a specific WebSocket client */
   sendToClient(ws: WebSocket, msg: ServerToBrowserMessage): void;
   /** Callback invoked when a new browser client connects */
@@ -86,6 +93,10 @@ export function createBrowserGateway(
   // Track headless child processes with sessionId linkage
   const headlessPidRegistry = createHeadlessPidRegistry();
 
+  // Track which browser is viewing which session (for unread state machine).
+  // See change: session-card-unread-stripes.
+  const viewedSessionTracker = createViewedSessionTracker();
+
   // Track pending interactive UI requests per session for replay on reconnect
   const pendingUiRequests = new Map<string, Map<string, { requestId: string; method: string; params: Record<string, unknown> }>>();
 
@@ -454,6 +465,26 @@ export function createBrowserGateway(
           case "rename_terminal":
             handleRenameTerminal(msg, ctx);
             break;
+          case "session_view": {
+            // Browser declares it is currently displaying this session.
+            // Track the (sessionId, ws) pair AND clear `unread` if set.
+            // See change: session-card-unread-stripes.
+            viewedSessionTracker.view(msg.sessionId, ws);
+            const session = sessionManager.get(msg.sessionId);
+            if (session?.unread) {
+              sessionManager.update(msg.sessionId, { unread: false });
+              broadcast({
+                type: "session_updated",
+                sessionId: msg.sessionId,
+                updates: { unread: false },
+              });
+            }
+            break;
+          }
+          case "session_unview": {
+            viewedSessionTracker.unview(msg.sessionId, ws);
+            break;
+          }
           default:
             // Forward simple pi-gateway commands
             handlePiGatewayForward(msg, ctx);
@@ -473,6 +504,9 @@ export function createBrowserGateway(
       console.error(`[browser-gw] browser client disconnected (remaining: ${subscriptions.size - 1})`);
       subscriptions.delete(ws);
       replayingSessions.delete(ws);
+      // Drop this ws from every viewed-session entry so disconnected browsers
+      // don't hold sessions in the viewed state. See change: session-card-unread-stripes.
+      viewedSessionTracker.unviewAll(ws);
     });
   });
 
@@ -560,6 +594,8 @@ export function createBrowserGateway(
     headlessPidRegistry,
 
     pendingResumeRegistry,
+
+    viewedSessionTracker,
   };
 
   return gateway;

package/packages/server/src/cli.ts

@@ -467,6 +467,75 @@ async function cmdStop(): Promise<void> {
   }
 }
 
+/**
+ * `pi-dashboard restart` — restart the daemon.
+ *
+ * If a dashboard is currently running, POST to `/api/restart` so the proven
+ * `restart-helper.ts` orchestrator handles the stop/start atomically in a
+ * detached child. This avoids the bridge-auto-start race that occurs when
+ * `cmdStop()` kills the daemon in-process: every connected bridge sees its
+ * WS close and fires `server-auto-start.ts`, racing the subsequent
+ * `cmdStart()` to bind the port.
+ *
+ * If the dashboard is NOT running (or is unreachable), fall back to the
+ * existing `cmdStop()` + `cmdStart()` sequence.
+ *
+ * See change: fix-restart-bridge-auto-start-race.
+ */
+export async function cmdRestart(
+  config: ServerConfig,
+  injected?: {
+    isDashboardRunning?: typeof isDashboardRunning;
+    fetchImpl?: typeof fetch;
+    cmdStopImpl?: () => Promise<void>;
+    cmdStartImpl?: (cfg: ServerConfig) => Promise<void>;
+  },
+): Promise<void> {
+  const probe = injected?.isDashboardRunning ?? isDashboardRunning;
+  const fetchFn = injected?.fetchImpl ?? fetch;
+  const stopFn = injected?.cmdStopImpl ?? cmdStop;
+  const startFn = injected?.cmdStartImpl ?? cmdStart;
+  return cmdRestartImpl(config, probe, fetchFn, stopFn, startFn);
+}
+
+async function cmdRestartImpl(
+  config: ServerConfig,
+  probe: typeof isDashboardRunning,
+  fetchFn: typeof fetch,
+  stopFn: () => Promise<void>,
+  startFn: (cfg: ServerConfig) => Promise<void>,
+): Promise<void> {
+  const status = await probe(config.port);
+  if (status.running) {
+    console.log(
+      `[restart] dashboard running at http://localhost:${config.port}, delegating to /api/restart`,
+    );
+    try {
+      const res = await fetchFn(`http://localhost:${config.port}/api/restart`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ dev: !!config.dev }),
+      });
+      if (res.ok) {
+        console.log("[restart] orchestrator queued; CLI exits now.");
+        return;
+      }
+      const body = await res.text();
+      console.error(
+        `[restart] server rejected restart: HTTP ${res.status} ${body}; falling back to local stop/start`,
+      );
+    } catch (err) {
+      console.error(
+        `[restart] failed to reach server (${(err as Error).message ?? err}); falling back to local stop/start`,
+      );
+    }
+    // Fall through to local sequence on HTTP failure so the user is never
+    // left with a half-restarted server.
+  }
+  await stopFn();
+  await startFn(config);
+}
+
 /**
  * Show server status.
  */
@@ -589,8 +658,7 @@ async function main() {
       await cmdStop();
       break;
     case "restart":
-      await cmdStop();
-      await cmdStart(config);
+      await cmdRestart(config);
       break;
     case "status":
       await cmdStatus(config.port);

package/packages/server/src/event-status-extraction.ts

@@ -2,7 +2,7 @@
  * Extract session status/tool updates from forwarded events.
  * Returns partial DashboardSession updates, or null if the event is not relevant.
  */
-import type { DashboardEvent, DashboardSession, FlowStatus } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { DashboardEvent, DashboardSession, FlowStatus, SessionStatus } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 
 // Use null (not undefined) for fields that must be cleared — undefined is
 // dropped during JSON serialisation so the browser would keep the stale value.
@@ -136,3 +136,100 @@ export function extractSessionUpdates(event: DashboardEvent): SessionUpdates | n
       return null;
   }
 }
+
+/**
+ * Activity-event allowlist for `session.lastActivityAt` stamping.
+ *
+ * Returns `true` for event types that represent user-or-agent action
+ * (the kind of thing a human would call "this session did something"),
+ * and `false` for plumbing/heartbeat/UI-state noise.
+ *
+ * The allowlist is deliberately narrow. Adding a new pi event type that
+ * a user would consider "activity" requires adding it here.
+ *
+ * See change: session-card-last-activity-badge (design.md § "Activity-event allowlist").
+ */
+const ACTIVITY_EVENT_TYPES: ReadonlySet<string> = new Set([
+  // User input
+  "prompt_send",
+  // Assistant message lifecycle
+  "message_start",
+  "message_end",
+  "turn_end",
+  // Tool execution
+  "tool_execution_start",
+  "tool_execution_end",
+  // Agent lifecycle
+  "agent_start",
+  "agent_end",
+  // Bash command output
+  "bash_output",
+  // Flow lifecycle / agent steps
+  "flow_started",
+  "flow_complete",
+  "flow_agent_started",
+  "flow_agent_complete",
+  // Architect (flow design) lifecycle
+  "architect_started",
+  "architect_complete",
+  "architect_cancelled",
+]);
+
+export function isActivityEvent(eventType: string): boolean {
+  return ACTIVITY_EVENT_TYPES.has(eventType);
+}
+
+/**
+ * Snapshot of the session fields the unread classifier needs.
+ * Pulled out of `DashboardSession` to keep the helper testable without
+ * constructing a full session object.
+ */
+export interface UnreadTriggerSnapshot {
+  status?: SessionStatus;
+  currentTool?: string | null;
+}
+
+/**
+ * Pure classifier: should the given event flip a session to `unread: true`?
+ *
+ * Triggers (per change: session-card-unread-stripes):
+ *   1. status transition `streaming` -> `idle` or `streaming` -> `active`
+ *      (turn finished)
+ *   2. `currentTool` becomes `"ask_user"` (input requested)
+ *   3. `agent_end` event whose payload's `error` field is truthy
+ *
+ * Anything else (assistant message_end, tool_execution_*, model_select,
+ * git/process noise) returns false. This is intentionally narrower than
+ * `isActivityEvent` — unread is for moments that demand the user’s eyes,
+ * not every tick of work.
+ *
+ * The caller is responsible for the "not currently viewed" gate — this
+ * helper is concerned only with whether the event semantically qualifies.
+ */
+export function isUnreadTrigger(
+  eventType: string,
+  before: UnreadTriggerSnapshot,
+  after: UnreadTriggerSnapshot,
+  payload?: unknown,
+): boolean {
+  // Trigger 1: streaming -> idle | active (turn fully finished)
+  if (
+    before.status === "streaming" &&
+    (after.status === "idle" || after.status === "active")
+  ) {
+    return true;
+  }
+
+  // Trigger 2: currentTool flips to "ask_user"
+  if (after.currentTool === "ask_user" && before.currentTool !== "ask_user") {
+    return true;
+  }
+
+  // Trigger 3: agent_end with error
+  if (eventType === "agent_end") {
+    const data = (payload as { error?: unknown } | undefined) ?? undefined;
+    if (data && data.error) return true;
+  }
+
+  return false;
+}

package/packages/server/src/event-wiring.ts

@@ -9,7 +9,8 @@ import type { BrowserGateway } from "./browser-gateway.js";
 import type { SessionOrderManager } from "./session-order-manager.js";
 import type { PendingForkRegistry } from "./pending-fork-registry.js";
 import type { DirectoryService } from "./directory-service.js";
-import { extractSessionUpdates } from "./event-status-extraction.js";
+import { extractSessionUpdates, isActivityEvent, isUnreadTrigger } from "./event-status-extraction.js";
+import type { ViewedSessionTracker } from "./viewed-session-tracker.js";
 import { spawnPiSession } from "./process-manager.js";
 import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { writeSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
@@ -34,6 +35,13 @@ export interface EventWiringDeps {
    * auto-rename. See change: add-folder-task-checker-and-spawn-attach.
    */
   pendingAttachRegistry?: import("./pending-attach-registry.js").PendingAttachRegistry;
+  /**
+   * Optional viewed-session tracker. When provided, the wiring evaluates
+   * `isUnreadTrigger(...)` on each forwarded event and stamps
+   * `session.unread = true` for sessions no browser is currently viewing.
+   * See change: session-card-unread-stripes.
+   */
+  viewedSessionTracker?: ViewedSessionTracker;
 }
 
 /**
@@ -52,6 +60,7 @@ export function wireEvents(deps: EventWiringDeps): void {
     knownSessionIds,
     pendingDashboardSpawns,
     pendingAttachRegistry,
+    viewedSessionTracker,
   } = deps;
 
   // Broadcast placeholder session to browsers when auto-created from early events
@@ -107,6 +116,13 @@ export function wireEvents(deps: EventWiringDeps): void {
   const skipReplayInsert = new Set<string>();
   // Debounce flows refresh to prevent infinite loop between sessions in same cwd
   const recentFlowsRefresh = new Set<string>();
+  // Per-session timestamp of the most recent `lastActivityAt` broadcast.
+  // In-memory state updates on every activity event; the WebSocket broadcast
+  // is throttled to at most one per `LAST_ACTIVITY_BROADCAST_INTERVAL_MS` per
+  // session. The client's local `now` ticker handles label refreshes between
+  // broadcasts. See change: session-card-last-activity-badge.
+  const lastActivityBroadcastAt = new Map<string, number>();
+  const LAST_ACTIVITY_BROADCAST_INTERVAL_MS = 30_000;
 
   piGateway.onEvent = (sessionId, msg) => {
     if (msg.type === "event_forward") {
@@ -134,6 +150,15 @@ export function wireEvents(deps: EventWiringDeps): void {
         browserGateway.broadcastEvent(sessionId, seq, storedEvent);
       }
 
+      // Snapshot pre-update fields used by `isUnreadTrigger`. Captured here
+      // so the trigger sees the before/after edges of `status` and
+      // `currentTool` cleanly. See change: session-card-unread-stripes.
+      const sessionBefore = sessionManager.get(sessionId);
+      const beforeSnapshot = {
+        status: sessionBefore?.status,
+        currentTool: sessionBefore?.currentTool,
+      };
+
       const updates = extractSessionUpdates(msg.event);
       if (updates) {
         if (updates.flowAgentsDone === -1) {
@@ -148,6 +173,47 @@ export function wireEvents(deps: EventWiringDeps): void {
         }
       }
 
+      // Unread-trigger evaluation. Only fires for live (non-replay) events
+      // and only stamps when no browser is currently viewing the session.
+      // The viewedSessionTracker dep is optional for backward compatibility
+      // (and to keep tests that don't need it lean).
+      // See change: session-card-unread-stripes.
+      if (!replayingSessions.has(sessionId) && viewedSessionTracker) {
+        const sessionAfter = sessionManager.get(sessionId);
+        const afterSnapshot = {
+          status: sessionAfter?.status,
+          currentTool: sessionAfter?.currentTool,
+        };
+        if (
+          isUnreadTrigger(
+            msg.event.eventType,
+            beforeSnapshot,
+            afterSnapshot,
+            msg.event.data,
+          ) &&
+          !viewedSessionTracker.isViewedByAnyone(sessionId)
+        ) {
+          if (sessionAfter && !sessionAfter.unread) {
+            sessionManager.update(sessionId, { unread: true });
+            browserGateway.broadcastSessionUpdated(sessionId, { unread: true });
+          }
+        }
+      }
+
+      // Stamp `session.lastActivityAt` on every live activity event.
+      // Skipped during replay — historical events should not retroactively
+      // bump the badge. In-memory updates always; broadcasts throttled per
+      // session. See change: session-card-last-activity-badge.
+      if (!replayingSessions.has(sessionId) && isActivityEvent(msg.event.eventType)) {
+        const now = Date.now();
+        sessionManager.update(sessionId, { lastActivityAt: now });
+        const lastBroadcast = lastActivityBroadcastAt.get(sessionId) ?? 0;
+        if (now - lastBroadcast >= LAST_ACTIVITY_BROADCAST_INTERVAL_MS) {
+          lastActivityBroadcastAt.set(sessionId, now);
+          browserGateway.broadcastSessionUpdated(sessionId, { lastActivityAt: now });
+        }
+      }
+
       // Server-side OpenSpec activity detection from forwarded events
       // Skip during replay — replayed events from a forked session would set stale phase/change
       if (msg.event.eventType === "tool_execution_start" && !replayingSessions.has(sessionId)) {
@@ -466,6 +532,9 @@ export function wireEvents(deps: EventWiringDeps): void {
     }
 
     if (msg.type === "session_unregister") {
+      // Drop the per-session debounce entry so a future re-register with the
+      // same id does not silently suppress its first activity broadcast.
+      lastActivityBroadcastAt.delete(sessionId);
       browserGateway.broadcastSessionRemoved(sessionId);
     }
 

package/packages/server/src/memory-session-manager.ts

@@ -16,6 +16,33 @@ export interface RegisterSessionParams {
   firstMessage?: string;
   startedAt?: number;
   pid?: number;
+  /**
+   * Why the bridge is registering this session. Forwarded from the
+   * `session_register` protocol message (see
+   * `SessionRegisterMessage.registerReason`). Used by `onChange` to
+   * decide whether to apply the configured `reattachPlacement` policy.
+   * See change: reattach-move-to-front.
+   */
+  registerReason?: "spawn" | "reattach";
+}
+
+export interface OnChangeContext {
+  /**
+   * Set when `onChange` is fired from `register(...)` and the inbound
+   * params carried a `registerReason`. Undefined for `update`/`unregister`
+   * paths and for legacy registers without the field.
+   * See change: reattach-move-to-front.
+   */
+  registerReason?: "spawn" | "reattach";
+  /**
+   * The session's status BEFORE `register(...)` overwrote it to `"active"`.
+   * Captured because `register()` unconditionally sets `status: "active"`,
+   * which would otherwise hide a `"streaming"` reattach from policies
+   * that gate on streaming. Undefined for first-ever registers and for
+   * `update`/`unregister` paths.
+   * See change: reattach-move-to-front.
+   */
+  priorStatus?: SessionStatus;
 }
 
 export interface SessionManager {
@@ -27,8 +54,8 @@ export interface SessionManager {
   get(sessionId: string): DashboardSession | undefined;
   listActive(): DashboardSession[];
   listAll(): DashboardSession[];
-  /** Called after any mutation (register, unregister, update). Receives the affected session ID. */
-  onChange?: (sessionId: string) => void;
+  /** Called after any mutation (register, unregister, update). Receives the affected session ID and optional context. */
+  onChange?: (sessionId: string, ctx?: OnChangeContext) => void;
   /** Called after a session is unregistered (status set to ended). */
   onUnregister?: (sessionId: string) => void;
 }
@@ -43,6 +70,7 @@ export function createMemorySessionManager(): SessionManager {
       // polled by the bridge extension shortly after reconnect, so they don't
       // need to be carried over.
       const existing = sessions.get(params.id);
+      const priorStatus = existing?.status;
 
       const session: DashboardSession = {
         // Carry over accumulated data from the existing session (e.g. restored after restart)
@@ -80,7 +108,10 @@ export function createMemorySessionManager(): SessionManager {
         pid: params.pid,
       };
       sessions.set(params.id, session);
-      mgr.onChange?.(params.id);
+      mgr.onChange?.(params.id, {
+        registerReason: params.registerReason,
+        priorStatus,
+      });
       return session;
     },
 

package/packages/server/src/pi-gateway.ts

@@ -297,6 +297,10 @@ export function createPiGateway(
                 sessionDir: msg.sessionDir,
                 firstMessage: msg.firstMessage,
                 pid: msg.pid,
+                // Forward registerReason so server.ts onChange can apply
+                // the configured reattach placement policy.
+                // See change: reattach-move-to-front.
+                registerReason: msg.registerReason,
               });
               console.error(`[gateway] session registered: ${msg.sessionId} cwd=${msg.cwd}`);
 

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

@@ -0,0 +1,98 @@
+/**
+ * Reattach placement policy: when a bridge sends `session_register` with
+ * `registerReason: "reattach"` (i.e. the dashboard restarted while pi
+ * stayed alive), this module decides how the re-registered session id
+ * should be placed in the cwd's `sessionOrder`.
+ *
+ * Pure decision logic is extracted into `decideReattachAction` so it
+ * can be unit-tested without spinning up managers or browser gateways;
+ * `applyReattachPolicy` is the I/O-bearing entry point that calls it
+ * and performs the actual mutation + broadcast.
+ *
+ * See change: reattach-move-to-front.
+ */
+import type { ReattachPlacement } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import type { SessionStatus } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { SessionManager } from "./memory-session-manager.js";
+import type { SessionOrderManager } from "./session-order-manager.js";
+import type { BrowserGateway } from "./browser-gateway.js";
+
+export type ReattachAction = "moveToFront" | "preserve";
+
+/**
+ * Pure helper: decide whether the policy demands a `moveToFront` for a
+ * reattaching session given the current configured placement and the
+ * session's current status.
+ *
+ * Mapping:
+ * - `"always"`     → always `"moveToFront"`
+ * - `"streaming-only"` → `"moveToFront"` iff `status === "streaming"`
+ * - `"preserve"`   → always `"preserve"`
+ */
+export function decideReattachAction(
+  policy: ReattachPlacement,
+  status: SessionStatus | undefined,
+): ReattachAction {
+  switch (policy) {
+    case "always":
+      return "moveToFront";
+    case "streaming-only":
+      return status === "streaming" ? "moveToFront" : "preserve";
+    case "preserve":
+    default:
+      return "preserve";
+  }
+}
+
+/**
+ * Apply the configured reattach placement policy to a session that just
+ * re-registered with `registerReason: "reattach"`.
+ *
+ * Calls `sessionOrderManager.moveToFront` and broadcasts
+ * `sessions_reordered` only when the policy demands it. No-op when the
+ * session no longer exists in the manager, when its status is
+ * `"ended"`, or when the policy resolves to `"preserve"`.
+ *
+ * `priorStatus` is the session's status BEFORE `register()` coerced it
+ * to `"active"`. It's the meaningful signal for `"streaming-only"`:
+ * a session mid-stream when the dashboard rebooted carries
+ * `priorStatus === "streaming"`, even though `session.status` is now
+ * `"active"`. Pass `undefined` when the prior status is unknown
+ * (first-ever register), in which case the helper falls back to
+ * `session.status`.
+ * See change: reattach-move-to-front.
+ */
+export function applyReattachPolicy(
+  sessionId: string,
+  cwd: string,
+  policy: ReattachPlacement,
+  deps: {
+    sessionManager: SessionManager;
+    sessionOrderManager: SessionOrderManager;
+    browserGateway: BrowserGateway;
+  },
+  priorStatus?: SessionStatus,
+): ReattachAction {
+  const session = deps.sessionManager.get(sessionId);
+  if (!session) return "preserve";
+  // Defensive: if the session somehow ended between register and this
+  // hook firing, skip — the alive→ended branch in server.ts handles it.
+  if (session.status === "ended") return "preserve";
+
+  // Use prior status when known so `streaming-only` honors a session
+  // that was streaming when the dashboard went down. `register()`
+  // unconditionally sets `status: "active"`, so without this fallback
+  // `streaming-only` would silently behave as `preserve`.
+  const effectiveStatus = priorStatus ?? session.status;
+  const action = decideReattachAction(policy, effectiveStatus);
+  if (action === "moveToFront") {
+    deps.sessionOrderManager.moveToFront(cwd, sessionId);
+    const next = deps.sessionOrderManager.getOrder(cwd) ?? [];
+    deps.browserGateway.broadcastToAll({
+      type: "sessions_reordered",
+      cwd,
+      sessionIds: next,
+    });
+  }
+  return action;
+}

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

@@ -36,6 +36,10 @@ export interface RestartParams {
 export function buildOrchestratorScript(params: RestartParams): string {
   const execPath = params.execPath ?? process.execPath;
   const logPath = path.join(os.homedir(), ".pi", "dashboard", "restart.log");
+  // Same convention as `server-pid.ts`. Embedded as a JSON-stringified literal
+  // so quoting/path-separator handling is correct on Windows.
+  // See change: fix-restart-bridge-auto-start-race.
+  const pidPath = path.join(os.homedir(), ".pi", "dashboard", "dashboard.pid");
   // Loader is always URL-wrapped (required on Windows for non-C: drives).
   // Entry is URL-wrapped only on Windows + non-tsx loader. POSIX + jiti MUST
   // pass raw path because jiti's resolver treats file:// URL entries as
@@ -66,6 +70,7 @@ const PORT = ${params.port};
 const EXEC = ${JSON.stringify(execPath)};
 const ARGS = ${JSON.stringify(spawnArgs)};
 const LOG_PATH = ${JSON.stringify(logPath)};
+const PID_PATH = ${JSON.stringify(pidPath)};
 
 function log(msg) {
   try {
@@ -99,9 +104,43 @@ function healthOk() {
 
 function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
+// The next three process.kill calls run inside the orchestrator's
+// 'node -e' subprocess (NOT in-host server code), so they cannot use
+// the platform/process.ts helpers — those modules are not bundled into
+// the embedded script. The repo-lint opt-out marker at the end of each
+// line keeps no-direct-process-kill.test.ts quiet.
+// See change: fix-restart-bridge-auto-start-race.
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (_) { return false; } // ban:process-kill-ok
+}
+
+// 0. Read PID file and terminate the previous daemon explicitly. Removes the
+// "wait for self-exit" ambiguity that lets bridge auto-start race the
+// orchestrator. See change: fix-restart-bridge-auto-start-race.
+async function killPriorDaemon() {
+  let pid = 0;
+  try {
+    const raw = fs.readFileSync(PID_PATH, "utf-8").trim();
+    pid = parseInt(raw, 10);
+  } catch (_) { return; /* no PID file — nothing to do */ }
+  if (!Number.isFinite(pid) || pid <= 0) return;
+  if (!isAlive(pid)) return;
+  try { process.kill(pid, "SIGTERM"); } catch (_) { /* ignore */ } // ban:process-kill-ok
+  for (let i = 0; i < 30; i++) { // up to 3 s
+    await sleep(100);
+    if (!isAlive(pid)) return;
+  }
+  try { process.kill(pid, "SIGKILL"); } catch (_) { /* ignore */ } // ban:process-kill-ok
+  await sleep(200);
+}
+
 (async () => {
-  // 1. Wait for port to be free (up to 10s)
-  for (let i = 0; i < 20; i++) {
+  // 0. Explicit kill of previous daemon (SIGTERM → SIGKILL).
+  await killPriorDaemon();
+
+  // 1. Wait for port to be free (up to 5s — reduced from 10s because step 0
+  //    already guarantees the previous server is dead).
+  for (let i = 0; i < 10; i++) {
     if (await portFree(PORT)) break;
     await sleep(500);
   }