@blackbelt-technology/pi-agent-dashboard 0.5.1 → 0.5.2

package/packages/server/src/server.ts

@@ -35,6 +35,7 @@ import { discoverAndBroadcastSessions } from "./session-bootstrap.js";
 import { scanAllSessions } from "./session-scanner.js";
 import { needsMigration, runMigration } from "./migrate-persistence.js";
 import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel, scavengeOrphanZrokProcesses, getTunnelUrl } from "./tunnel.js";
+import { startTunnelWatchdog, stopTunnelWatchdog } from "./tunnel-watchdog.js";
 import { registerAuthPlugin, validateWsUpgrade } from "./auth-plugin.js";
 import { findBundledExtension, registerBridgeExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import { createNetworkGuard, isLoopback, isBypassedHost } from "./localhost-guard.js";
@@ -45,6 +46,8 @@ import { registerSessionRoutes } from "./routes/session-routes.js";
 import { registerGitRoutes } from "./routes/git-routes.js";
 import { registerFileRoutes } from "./routes/file-routes.js";
 import { registerOpenSpecRoutes } from "./routes/openspec-routes.js";
+import { registerOpenSpecGroupRoutes } from "./routes/openspec-group-routes.js";
+import { createOpenSpecGroupStore, joinGroupIdsToOpenSpecData } from "./openspec-group-store.js";
 import { registerSystemRoutes } from "./routes/system-routes.js";
 import { registerDoctorRoutes } from "./routes/doctor-routes.js";
 import { registerProviderAuthRoutes } from "./routes/provider-auth-routes.js";
@@ -58,6 +61,7 @@ import { registerToolRoutes } from "./routes/tool-routes.js";
 import { registerJjRoutes } from "./routes/jj-routes.js";
 import { registerBootstrapRoutes } from "./routes/bootstrap-routes.js";
 import { createBootstrapState, type BootstrapStateStore } from "./bootstrap-state.js";
+import { detectLegacyPiInstalls } from "./legacy-pi-cleanup.js";
 import { createBootstrapQueue } from "./bootstrap-queue.js";
 import { bootstrapInstall } from "@blackbelt-technology/pi-dashboard-shared/bootstrap-install.js";
 import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
@@ -68,6 +72,11 @@ import { createEditorPidRegistry } from "./editor-pid-registry.js";
 import { registerEditorRoutes } from "./routes/editor-routes.js";
 import { registerKnownServersRoutes } from "./routes/known-servers-routes.js";
 import { registerPluginConfigRoutes } from "./routes/plugin-config-routes.js";
+import { createModelProxyAuthGate } from "./model-proxy/auth-gate.js";
+import { registerModelProxyRoutes } from "./routes/model-proxy-routes.js";
+import { registerModelProxyApiKeyRoutes } from "./routes/model-proxy-api-key-routes.js";
+import { registerModelProxyRefreshRoutes } from "./routes/model-proxy-refresh-routes.js";
+import { getModelRegistry, getStreamSimpleFn } from "./model-proxy/registry-singleton.js";
 import { writeConfigPartial } from "./config-api.js";
 import { loadServerEntries, discoverPlugins, getPluginStatusStore } from "@blackbelt-technology/dashboard-plugin-runtime/server";
 import { createServerPluginContext } from "@blackbelt-technology/dashboard-plugin-runtime/server";
@@ -84,6 +93,12 @@ export interface ServerConfig {
   shutdownIdleSeconds: number;
   tunnel: boolean;
   tunnelReservedToken?: string;
+  tunnelWatchdog?: {
+    enabled: boolean;
+    intervalMs: number;
+    failureThreshold: number;
+    probeTimeoutMs: number;
+  };
   authConfig?: AuthConfig;
   /** Override WS ping interval for pi-gateway (ms). Default 60000. Set 0 to disable. */
   pingInterval?: number;
@@ -479,14 +494,32 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     knownSessionIds.add(s.id);
   }
 
+  // Create the OpenSpec change-grouping store BEFORE the directory-service so
+  // the latter can join `groupId` into every `OpenSpecChange` it produces.
+  // See change: add-openspec-change-grouping (task 4.2).
+  const openspecGroupStore = createOpenSpecGroupStore();
+
   const directoryService = createDirectoryService(
     preferencesStore,
     sessionManager,
     config.openspec,
+    {
+      enrichOpenSpecData: async (cwd, data) => {
+        try {
+          const file = await openspecGroupStore.read(cwd);
+          return joinGroupIdsToOpenSpecData(data, file.assignments);
+        } catch {
+          // Bad file (e.g., unsupported schemaVersion) — fall back to unjoined.
+          return data;
+        }
+      },
+    },
   );
 
   // mDNS peer discovery state
   let mdnsBrowser: DashboardBrowser | null = null;
+  // Optional second-port Fastify instance for model proxy (/v1/*)
+  let secondFastify: Awaited<ReturnType<typeof import("fastify").default>> | null = null;
   const peerServers = new Map<string, DiscoveredServer>();
 
   const piGateway = createPiGateway(sessionManager, {
@@ -661,6 +694,14 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   // routes can gate spawn operations on bootstrap status.
   // See change: unified-bootstrap-install.
   const bootstrapState = createBootstrapState();
+  // Scan for legacy `@mariozechner/pi-coding-agent` installs so the UI can
+  // offer a one-click cleanup. See: legacy-pi-cleanup.ts. Best-effort —
+  // detection failure is non-fatal (returns []).
+  try {
+    bootstrapState.set({ legacyPiInstalls: detectLegacyPiInstalls() });
+  } catch (err: any) {
+    console.warn("[legacy-pi] detection failed:", err?.message ?? err);
+  }
   const bootstrapQueue = createBootstrapQueue();
   // Centralized post-install repair: full ToolRegistry rescan +
   // OpenSpec / pi-resources force-refresh on every `installing → ready`
@@ -721,6 +762,29 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
     },
   });
+  // OpenSpec change-grouping routes (store created earlier next to
+  // directory-service so the join can run during polls).
+  // See change: add-openspec-change-grouping.
+  openspecGroupStore.subscribe((cwd, payload) => {
+    browserGateway.broadcastToAll({
+      type: "openspec_groups_update",
+      cwd,
+      groups: payload.groups,
+      assignments: payload.assignments,
+    });
+    // Refresh OpenSpecData so the joined `groupId` field reflects the new
+    // assignments on subscribers that don't consume `openspec_groups_update`
+    // directly. Fire-and-forget; failures are logged inside refreshOpenSpec.
+    directoryService.refreshOpenSpec(cwd).then((data) => {
+      browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
+    }).catch(() => {});
+  });
+  registerOpenSpecGroupRoutes(fastify, {
+    sessionManager,
+    preferencesStore,
+    networkGuard,
+    store: openspecGroupStore,
+  });
   registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService, piGateway, bootstrapState });
   // GET /api/doctor — see change: doctor-rich-output (task 4.2). Auth-gated identically to /api/config.
   registerDoctorRoutes(fastify);
@@ -792,7 +856,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       const prev = bootstrapState.getLastInstallPackages();
       const packages = prev.length > 0
         ? prev
-        : ["@earendil-works/pi-coding-agent", "@fission-ai/openspec", "tsx"];
+        : ["@earendil-works/pi-coding-agent", "@fission-ai/openspec"];
       bootstrapState.set({
         status: "installing",
         progress: { step: "retry", output: `restarting install (${packages.length} pkg${packages.length === 1 ? "" : "s"})…` },
@@ -953,7 +1017,51 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     networkGuard,
     broadcast: (msg) => browserGateway.broadcast(msg),
   });
-  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway });
+  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway, port: config.port });
+
+  // ── Model Proxy ───────────────────────────────────────────────────
+  {
+    const fullCfg = loadConfig();
+    if (fullCfg.modelProxy.enabled) {
+      // Register proxy auth gate (runs BEFORE JWT hook for /v1/* routes)
+      const proxyAuthGate = createModelProxyAuthGate({
+        getConfig: () => loadConfig().modelProxy,
+        persistKeyUsage: (apiKeys) => {
+          writeConfigPartial({ modelProxy: { apiKeys } });
+        },
+      });
+      fastify.addHook("onRequest", proxyAuthGate);
+
+      // Register /v1/* routes
+      registerModelProxyRoutes(fastify, {
+        getConfig: () => loadConfig().modelProxy,
+        getRegistry: async () => {
+          try {
+            return await getModelRegistry();
+          } catch {
+            return null;
+          }
+        },
+        streamSimple: (opts: any) => {
+          const fn = getStreamSimpleFn();
+          if (!fn) throw new Error("streamSimple not available");
+          return fn(opts.model, { messages: opts.messages, system: opts.system, tools: opts.tools }, opts);
+        },
+      });
+
+      // Register API key management routes (JWT-gated)
+      registerModelProxyApiKeyRoutes(fastify, {
+        networkGuard,
+        getModelProxyConfig: () => loadConfig().modelProxy,
+        writeModelProxyApiKeys: async (apiKeys) => {
+          writeConfigPartial({ modelProxy: { apiKeys } });
+        },
+      });
+
+      // Register refresh route (JWT-gated)
+      registerModelProxyRefreshRoutes(fastify);
+    }
+  }
 
   // Serve static files / SPA fallback.
   //
@@ -1086,6 +1194,19 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       // Clean up orphan headless processes from a previous server instance
       browserGateway.headlessPidRegistry.cleanupOrphans();
 
+      // Wire the singleton KeeperManager into the headless-pid registry so
+      // `writeRpc` can forward `dispatch_extension_command` lines to the
+      // session's keeper UDS, and so `cleanupKeeperOrphans` can reattach
+      // surviving keepers after a server restart. Same instance the spawn
+      // path uses. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+      try {
+        const { getKeeperManager } = await import("./process-manager.js");
+        browserGateway.headlessPidRegistry.setKeeperWriter(getKeeperManager());
+        await browserGateway.headlessPidRegistry.cleanupKeeperOrphans();
+      } catch (err) {
+        console.warn("[dashboard] keeper-manager wire-up failed (RPC dispatch disabled):", err);
+      }
+
       // Clean up orphan code-server processes from a previous server instance.
       // Runs before fastify.listen, so no editor start request can race with the sweep.
       await editorPidRegistry.cleanupOrphans();
@@ -1184,6 +1305,40 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       console.log(`Dashboard server running at http://localhost:${config.port}`);
       console.log(`Pi gateway listening on port ${config.piPort}`);
 
+      // ── Optional second port for model proxy (/v1/*) ──────────────
+      {
+        const proxyCfg = loadConfig().modelProxy;
+        if (proxyCfg.enabled && proxyCfg.secondPort) {
+          try {
+            const F = (await import("fastify")).default;
+            const sf = F({ logger: false });
+            const proxyAuthGate = createModelProxyAuthGate({
+              getConfig: () => loadConfig().modelProxy,
+              persistKeyUsage: (apiKeys) => {
+                writeConfigPartial({ modelProxy: { apiKeys } });
+              },
+            });
+            sf.addHook("onRequest", proxyAuthGate);
+            registerModelProxyRoutes(sf, {
+              getConfig: () => loadConfig().modelProxy,
+              getRegistry: async () => {
+                try { return await getModelRegistry(); } catch { return null; }
+              },
+              streamSimple: (opts: any) => {
+                const fn = getStreamSimpleFn();
+                if (!fn) throw new Error("streamSimple not available");
+                return fn(opts.model, { messages: opts.messages, system: opts.system, tools: opts.tools }, opts);
+              },
+            });
+            await sf.listen({ port: proxyCfg.secondPort, host: "127.0.0.1" });
+            secondFastify = sf as any;
+            console.log(`Model proxy second port listening at http://127.0.0.1:${proxyCfg.secondPort}`);
+          } catch (err) {
+            console.warn(`Model proxy second port bind failed (continuing without):`, err);
+          }
+        }
+      }
+
       // Advertise via mDNS
       try {
         advertiseDashboard(config.port, config.piPort);
@@ -1225,6 +1380,21 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
           const tunnelUrl = await createTunnel(config.port, config.tunnelReservedToken);
           if (tunnelUrl) {
             console.log(`🌐 Tunnel: ${tunnelUrl}`);
+            // Start the watchdog so a stale zrok edge connection is detected
+            // and recycled automatically (preserves reserved token / URL).
+            const wd = config.tunnelWatchdog;
+            if (wd?.enabled !== false) {
+              startTunnelWatchdog(
+                {
+                  getUrl: getTunnelUrl,
+                  recycle: async () => {
+                    await deleteTunnel(config.port);
+                    return await createTunnel(config.port, config.tunnelReservedToken);
+                  },
+                },
+                wd,
+              );
+            }
           }
         }
       }
@@ -1277,6 +1447,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       unsubscribeQueueComplete();
       bootstrapState.dispose();
       bootstrapQueue.clear("server shutting down");
+      stopTunnelWatchdog();
       await deleteTunnel(config.port);
       piGateway.stop();
       for (const client of browserGateway.wss.clients) {
@@ -1292,6 +1463,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       editorManager.stopAll();
       // Close any pending OAuth callback servers
       try { const { closeAllCallbackServers } = await import("./oauth-callback-server.js"); await closeAllCallbackServers(); } catch {}
+      // Close second port before main server
+      if (secondFastify) {
+        try { await secondFastify.close(); } catch { /* ignore */ }
+        secondFastify = null;
+      }
       await fastify.close();
     },
   };

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

@@ -17,6 +17,7 @@ import type { BootstrapStateStore } from "./bootstrap-state.js";
 import type { BootstrapQueue } from "./bootstrap-queue.js";
 import { attachRenameTarget, detachShouldClearName } from "./proposal-attach-naming.js";
 import { FORK_DEGRADED_TO_NEW_MESSAGE, FORK_DEGRADED_TO_NEW_CODE } from "./browser-handlers/session-action-handler.js";
+import { keeperOptsFromSpawnResult } from "./headless-pid-registry.js";
 
 export interface SessionApiDeps {
   sessionManager: SessionManager;
@@ -239,7 +240,13 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
         const config = loadConfig();
         const spawnResult = await spawnPiSession(cwd, { strategy: config.spawnStrategy });
         if (spawnResult.process && spawnResult.pid) {
-          browserGateway.headlessPidRegistry.register(spawnResult.pid, cwd, spawnResult.process);
+          browserGateway.headlessPidRegistry.register(
+            spawnResult.pid,
+            cwd,
+            spawnResult.process,
+            spawnResult.spawnToken,
+            keeperOptsFromSpawnResult(spawnResult),
+          );
         }
         if (spawnResult.dashboardSpawned && spawnResult.success) {
           pendingDashboardSpawns?.set(cwd, (pendingDashboardSpawns?.get(cwd) ?? 0) + 1);
@@ -309,6 +316,7 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
             session.cwd,
             degradeResult.process,
             degradeResult.spawnToken,
+            keeperOptsFromSpawnResult(degradeResult),
           );
         }
         if (degradeResult.dashboardSpawned && degradeResult.success) {

package/packages/server/src/tunnel-watchdog.ts

@@ -0,0 +1,230 @@
+/**
+ * Tunnel watchdog: periodically probes the public tunnel URL through the
+ * zrok edge and recycles the tunnel when consecutive failures (5xx, network
+ * errors, timeouts) exceed a threshold.
+ *
+ * The zrok `share` subprocess can stay running for days while its connection
+ * to the zrok edge silently goes stale, returning HTTP 502 from the public
+ * URL even though the local upstream is healthy. The fix is a `deleteTunnel`
+ * + `createTunnel` cycle (preserves the reserved token, so the URL stays the
+ * same).
+ *
+ * Probe semantics: we treat ONLY 5xx and network/timeout failures as bad.
+ * Any 2xx/3xx/4xx response proves zrok edge ↔ local server connectivity is
+ * fine and counts as success — even if the local route is auth-gated.
+ */
+
+export interface TunnelWatchdogDeps {
+  /** Returns the active public tunnel URL, or null if no tunnel is up. */
+  getUrl: () => string | null;
+  /** Recycle the tunnel: delete and recreate. Returns the new URL or null. */
+  recycle: () => Promise<string | null>;
+  /** Optional fetch override for tests. */
+  fetchFn?: typeof fetch;
+  /** Optional logger; defaults to console. */
+  log?: (level: "info" | "warn" | "error", msg: string) => void;
+}
+
+export interface TunnelWatchdogConfig {
+  /** Master switch. Default: true. */
+  enabled: boolean;
+  /** Probe cadence. Default: 60_000. */
+  intervalMs: number;
+  /** Consecutive failures before recycling. Default: 2. */
+  failureThreshold: number;
+  /** Per-probe HTTP timeout. Default: 10_000. */
+  probeTimeoutMs: number;
+}
+
+export const DEFAULT_TUNNEL_WATCHDOG_CONFIG: TunnelWatchdogConfig = {
+  enabled: true,
+  intervalMs: 60_000,
+  failureThreshold: 2,
+  probeTimeoutMs: 10_000,
+};
+
+export interface TunnelWatchdogStatus {
+  running: boolean;
+  intervalMs: number;
+  failureThreshold: number;
+  probeTimeoutMs: number;
+  lastProbeAt: number | null;
+  lastSuccessAt: number | null;
+  lastFailureAt: number | null;
+  lastFailureReason: string | null;
+  consecutiveFailures: number;
+  lastRecycleAt: number | null;
+  recycleCount: number;
+}
+
+interface WatchdogState {
+  cfg: TunnelWatchdogConfig;
+  deps: TunnelWatchdogDeps;
+  timer: ReturnType<typeof setTimeout> | null;
+  inFlight: boolean;
+  recycling: boolean;
+  /** Current backoff multiplier applied after a recycle failure (1, 2, 4, …, capped). */
+  backoffMultiplier: number;
+  status: TunnelWatchdogStatus;
+}
+
+let state: WatchdogState | null = null;
+
+const MAX_BACKOFF_MULTIPLIER = 8;
+
+function defaultLog(level: "info" | "warn" | "error", msg: string): void {
+  const prefix = "[tunnel-watchdog]";
+  if (level === "warn") console.warn(prefix, msg);
+  else if (level === "error") console.error(prefix, msg);
+  else console.log(prefix, msg);
+}
+
+function makeInitialStatus(cfg: TunnelWatchdogConfig): TunnelWatchdogStatus {
+  return {
+    running: false,
+    intervalMs: cfg.intervalMs,
+    failureThreshold: cfg.failureThreshold,
+    probeTimeoutMs: cfg.probeTimeoutMs,
+    lastProbeAt: null,
+    lastSuccessAt: null,
+    lastFailureAt: null,
+    lastFailureReason: null,
+    consecutiveFailures: 0,
+    lastRecycleAt: null,
+    recycleCount: 0,
+  };
+}
+
+/** Probe outcome: ok=true on 2xx/3xx/4xx, false on 5xx/network/timeout. */
+export async function probeTunnel(
+  url: string,
+  timeoutMs: number,
+  fetchFn: typeof fetch = fetch,
+): Promise<{ ok: boolean; status?: number; reason?: string }> {
+  const probeUrl = url.replace(/\/+$/, "") + "/api/health";
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(probeUrl, { method: "GET", signal: ctrl.signal });
+    if (res.status >= 500) {
+      return { ok: false, status: res.status, reason: `http ${res.status}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err: any) {
+    const reason = err?.name === "AbortError" ? `timeout ${timeoutMs}ms` : (err?.message || "network error");
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function scheduleNext(): void {
+  if (!state) return;
+  const delay = state.cfg.intervalMs * state.backoffMultiplier;
+  state.timer = setTimeout(() => { void tick(); }, delay);
+  // Don't keep the event loop alive for the watchdog alone.
+  if (typeof (state.timer as any).unref === "function") (state.timer as any).unref();
+}
+
+async function tick(): Promise<void> {
+  if (!state) return;
+  if (state.inFlight) { scheduleNext(); return; }
+  state.inFlight = true;
+  try {
+    const url = state.deps.getUrl();
+    if (!url) {
+      // No tunnel up — nothing to probe; keep ticking in case it comes up.
+      return;
+    }
+    const fetchFn = state.deps.fetchFn ?? fetch;
+    state.status.lastProbeAt = Date.now();
+    const result = await probeTunnel(url, state.cfg.probeTimeoutMs, fetchFn);
+    if (result.ok) {
+      state.status.lastSuccessAt = Date.now();
+      state.status.consecutiveFailures = 0;
+      state.backoffMultiplier = 1;
+      return;
+    }
+    state.status.lastFailureAt = Date.now();
+    state.status.lastFailureReason = result.reason ?? "unknown";
+    state.status.consecutiveFailures += 1;
+    (state.deps.log ?? defaultLog)(
+      "warn",
+      `probe failed (${state.status.consecutiveFailures}/${state.cfg.failureThreshold}): ${state.status.lastFailureReason}`,
+    );
+    if (state.status.consecutiveFailures >= state.cfg.failureThreshold && !state.recycling) {
+      await runRecycle();
+    }
+  } finally {
+    state.inFlight = false;
+    if (state) scheduleNext();
+  }
+}
+
+async function runRecycle(): Promise<void> {
+  if (!state) return;
+  state.recycling = true;
+  const log = state.deps.log ?? defaultLog;
+  log("warn", `recycling tunnel after ${state.status.consecutiveFailures} consecutive failures`);
+  try {
+    const newUrl = await state.deps.recycle();
+    state.status.lastRecycleAt = Date.now();
+    state.status.recycleCount += 1;
+    state.status.consecutiveFailures = 0;
+    if (newUrl) {
+      log("info", `tunnel recycled: ${newUrl}`);
+      state.backoffMultiplier = 1;
+    } else {
+      log("error", "tunnel recycle returned no URL — backing off");
+      state.backoffMultiplier = Math.min(state.backoffMultiplier * 2 || 2, MAX_BACKOFF_MULTIPLIER);
+    }
+  } catch (err: any) {
+    log("error", `tunnel recycle threw: ${err?.message ?? err}`);
+    state.backoffMultiplier = Math.min(state.backoffMultiplier * 2 || 2, MAX_BACKOFF_MULTIPLIER);
+  } finally {
+    state.recycling = false;
+  }
+}
+
+export function startTunnelWatchdog(
+  deps: TunnelWatchdogDeps,
+  cfg: Partial<TunnelWatchdogConfig> = {},
+): void {
+  if (state) return; // already running
+  const merged: TunnelWatchdogConfig = { ...DEFAULT_TUNNEL_WATCHDOG_CONFIG, ...cfg };
+  if (!merged.enabled) return;
+  state = {
+    cfg: merged,
+    deps,
+    timer: null,
+    inFlight: false,
+    recycling: false,
+    backoffMultiplier: 1,
+    status: makeInitialStatus(merged),
+  };
+  state.status.running = true;
+  scheduleNext();
+}
+
+export function stopTunnelWatchdog(): void {
+  if (!state) return;
+  if (state.timer) clearTimeout(state.timer);
+  state.status.running = false;
+  state = null;
+}
+
+export function getTunnelWatchdogStatus(): TunnelWatchdogStatus | null {
+  if (!state) return null;
+  return { ...state.status };
+}
+
+/** Test-only: force a tick now (returns when the tick completes). */
+export async function _runTickForTest(): Promise<void> {
+  await tick();
+}
+
+/** Test-only: reset module-level state. */
+export function _resetForTest(): void {
+  if (state?.timer) clearTimeout(state.timer);
+  state = null;
+}

package/packages/server/src/tunnel.ts

@@ -17,6 +17,7 @@ import {
 
 const zrokResolver = new ToolResolver({ processExecPath: process.execPath });
 import type { TunnelStatus } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { getTunnelWatchdogStatus } from "./tunnel-watchdog.js";
 import { CONFIG_FILE } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 
 export type { TunnelStatus };
@@ -458,7 +459,10 @@ export function getTunnelUrl(): string | null {
 export function getTunnelStatus(): TunnelStatus {
   const serverOs = process.platform;
   if (activeTunnelUrl) {
-    return { status: "active", url: activeTunnelUrl, serverOs };
+    const wd = getTunnelWatchdogStatus();
+    return wd
+      ? { status: "active", url: activeTunnelUrl, serverOs, watchdog: wd }
+      : { status: "active", url: activeTunnelUrl, serverOs };
   }
   if (detectZrokBinary()) {
     return { status: "inactive", serverOs };

package/packages/shared/package.json

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