@hellcoder/companion 0.96.0

package/server/image-pull-manager.ts

@@ -0,0 +1,279 @@
+import { join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { containerManager, ContainerManager } from "./container-manager.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ImagePullState {
+  image: string;
+  status: "idle" | "pulling" | "ready" | "error";
+  /** Last N lines of pull/build output (ring buffer) */
+  progress: string[];
+  error?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_PROGRESS_LINES = 50;
+const WEB_DIR = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// ImagePullManager — singleton that tracks background image pulls
+// ---------------------------------------------------------------------------
+
+type ReadyListener = () => void;
+
+class ImagePullManager {
+  private states = new Map<string, ImagePullState>();
+  /** Listeners waiting for a specific image to become ready */
+  private readyListeners = new Map<string, ReadyListener[]>();
+
+  /**
+   * Get the current state for an image.
+   * If the image exists locally and we have no tracking entry, return "ready".
+   */
+  getState(image: string): ImagePullState {
+    const existing = this.states.get(image);
+    if (existing) return existing;
+
+    // Check if already available locally
+    const ready = containerManager.imageExists(image);
+    return {
+      image,
+      status: ready ? "ready" : "idle",
+      progress: [],
+    };
+  }
+
+  /** Quick check: is the image available locally right now? */
+  isReady(image: string): boolean {
+    return this.getState(image).status === "ready";
+  }
+
+  /**
+   * Ensure the image is available. Starts a background pull if missing.
+   * No-op if already pulling or ready.
+   */
+  ensureImage(image: string): void {
+    const state = this.getState(image);
+    if (state.status === "ready" || state.status === "pulling") return;
+    this.startPull(image);
+  }
+
+  /**
+   * Wait for an image that is currently pulling to become ready.
+   * Resolves true if ready, false if pull failed or timed out.
+   * If image is already ready, resolves immediately.
+   */
+  waitForReady(image: string, timeoutMs = 300_000): Promise<boolean> {
+    const state = this.getState(image);
+    if (state.status === "ready") return Promise.resolve(true);
+    if (state.status === "error") return Promise.resolve(false);
+    if (state.status === "idle") {
+      // Not pulling yet — start it
+      this.startPull(image);
+    }
+
+    return new Promise<boolean>((resolve) => {
+      let settled = false;
+      const done = (result: boolean) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        // Clean up the listener to avoid memory leaks
+        const arr = this.readyListeners.get(image);
+        if (arr) {
+          const idx = arr.indexOf(listener);
+          if (idx >= 0) arr.splice(idx, 1);
+          if (arr.length === 0) this.readyListeners.delete(image);
+        }
+        resolve(result);
+      };
+
+      const timer = setTimeout(() => done(false), timeoutMs);
+
+      const listener: ReadyListener = () => {
+        const s = this.getState(image);
+        if (s.status === "ready") done(true);
+        else if (s.status === "error") done(false);
+        // else still pulling — keep waiting
+      };
+
+      const listeners = this.readyListeners.get(image) ?? [];
+      listeners.push(listener);
+      this.readyListeners.set(image, listeners);
+
+      // Re-check after registering the listener to catch races where
+      // the pull completed synchronously before the listener was added.
+      const currentState = this.getState(image);
+      if (currentState.status === "ready") done(true);
+      else if (currentState.status === "error") done(false);
+    });
+  }
+
+  /**
+   * Trigger a pull even if image is already present (for updates).
+   */
+  pull(image: string): void {
+    const state = this.getState(image);
+    if (state.status === "pulling") return; // already in progress
+    this.startPull(image);
+  }
+
+  /**
+   * Subscribe to progress lines for a specific image.
+   * Returns an unsubscribe function.
+   * The callback fires for each new progress line while pulling.
+   */
+  onProgress(image: string, cb: (line: string) => void): () => void {
+    const key = `progress:${image}`;
+    const listeners = (this.progressListeners.get(key) ?? []);
+    listeners.push(cb);
+    this.progressListeners.set(key, listeners);
+    return () => {
+      const arr = this.progressListeners.get(key);
+      if (arr) {
+        const idx = arr.indexOf(cb);
+        if (idx >= 0) arr.splice(idx, 1);
+      }
+    };
+  }
+  private progressListeners = new Map<string, Array<(line: string) => void>>();
+
+  /**
+   * On server startup, check all environments and pre-pull missing images.
+   * Environments no longer carry Docker fields — this is now a no-op stub
+   * kept for backwards compatibility with callers.
+   */
+  initFromEnvironments(): void {
+    // Environments no longer have imageTag/baseImage (moved to Sandboxes).
+    // Nothing to pre-pull from envs.
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  private startPull(image: string): void {
+    const state: ImagePullState = {
+      image,
+      status: "pulling",
+      progress: [],
+      startedAt: Date.now(),
+    };
+    this.states.set(image, state);
+
+    // Determine if we can pull from registry
+    const registryImage = ContainerManager.getRegistryImage(image);
+
+    if (registryImage) {
+      this.doPullFromRegistry(image, registryImage);
+    } else {
+      // No registry mapping — mark as error since we can't pull custom images
+      this.markError(image, `No registry mapping for image "${image}". Build it from a Dockerfile instead.`);
+    }
+  }
+
+  private async doPullFromRegistry(localTag: string, registryImage: string): Promise<void> {
+    try {
+      const pulled = await containerManager.pullImage(registryImage, localTag, (line) => {
+        this.appendProgress(localTag, line);
+      });
+
+      if (pulled) {
+        this.markReady(localTag);
+      } else {
+        // Pull failed — try local build for default image
+        if (localTag === "the-companion:latest") {
+          this.appendProgress(localTag, "Pull failed, falling back to local build...");
+          await this.doLocalBuild(localTag);
+        } else {
+          this.markError(localTag, "Pull failed from registry");
+        }
+      }
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      // Try local build fallback for default image
+      if (localTag === "the-companion:latest") {
+        this.appendProgress(localTag, `Pull error (${reason}), falling back to local build...`);
+        await this.doLocalBuild(localTag);
+      } else {
+        this.markError(localTag, reason);
+      }
+    }
+  }
+
+  private async doLocalBuild(localTag: string): Promise<void> {
+    const dockerfilePath = join(WEB_DIR, "docker", "Dockerfile.the-companion");
+    if (!existsSync(dockerfilePath)) {
+      this.markError(localTag, `Dockerfile not found at ${dockerfilePath}`);
+      return;
+    }
+
+    try {
+      this.appendProgress(localTag, `Building ${localTag} from local Dockerfile...`);
+      containerManager.buildImage(dockerfilePath, localTag);
+      this.markReady(localTag);
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      this.markError(localTag, `Build failed: ${reason}`);
+    }
+  }
+
+  private appendProgress(image: string, line: string): void {
+    const state = this.states.get(image);
+    if (!state) return;
+    state.progress.push(line);
+    if (state.progress.length > MAX_PROGRESS_LINES) {
+      state.progress.splice(0, state.progress.length - MAX_PROGRESS_LINES);
+    }
+
+    // Notify progress listeners
+    const key = `progress:${image}`;
+    const listeners = this.progressListeners.get(key);
+    if (listeners) {
+      for (const cb of listeners) {
+        try { cb(line); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  private markReady(image: string): void {
+    const state = this.states.get(image);
+    if (state) {
+      state.status = "ready";
+      state.completedAt = Date.now();
+      this.appendProgress(image, "Image ready");
+    }
+    this.notifyListeners(image);
+  }
+
+  private markError(image: string, error: string): void {
+    const state = this.states.get(image);
+    if (state) {
+      state.status = "error";
+      state.error = error;
+      state.completedAt = Date.now();
+      this.appendProgress(image, `Error: ${error}`);
+    }
+    this.notifyListeners(image);
+  }
+
+  private notifyListeners(image: string): void {
+    const listeners = this.readyListeners.get(image);
+    if (listeners) {
+      for (const listener of listeners) {
+        try { listener(); } catch { /* ignore */ }
+      }
+      this.readyListeners.delete(image);
+    }
+  }
+}
+
+// Singleton export
+export const imagePullManager = new ImagePullManager();

package/server/index.ts

@@ -0,0 +1,396 @@
+process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
+
+// Enrich process PATH at startup so binary resolution and `which` calls can find
+// binaries installed via version managers (nvm, volta, fnm, etc.).
+// Critical when running as a launchd/systemd service with a restricted PATH.
+import { getEnrichedPath } from "./path-resolver.js";
+process.env.PATH = getEnrichedPath();
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { serveStatic } from "hono/bun";
+import { cacheControlMiddleware } from "./cache-headers.js";
+import { createRoutes } from "./routes.js";
+import { CliLauncher } from "./cli-launcher.js";
+import { WsBridge } from "./ws-bridge.js";
+import { SessionStore } from "./session-store.js";
+import { WorktreeTracker } from "./worktree-tracker.js";
+import { containerManager } from "./container-manager.js";
+import { join } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+import { TerminalManager } from "./terminal-manager.js";
+import { PRPoller } from "./pr-poller.js";
+import { RecorderManager } from "./recorder.js";
+import { initLogFile, closeLogFile } from "./logger.js";
+import { CronScheduler } from "./cron-scheduler.js";
+import { AgentExecutor } from "./agent-executor.js";
+import { SessionOrchestrator } from "./session-orchestrator.js";
+import { migrateCronJobsToAgents } from "./agent-cron-migrator.js";
+import { migrateLinearCredentialsToAgents } from "./linear-credential-migration.js";
+import { authenticateManagedWebSocket } from "./ws-auth.js";
+import { LinearAgentBridge } from "./linear-agent-bridge.js";
+import { NoVncProxy } from "./novnc-proxy.js";
+
+import { startPeriodicCheck, setServiceMode } from "./update-checker.js";
+import { imagePullManager } from "./image-pull-manager.js";
+import { restoreIfNeeded as restoreTailscaleFunnel, cleanup as cleanupTailscaleFunnel } from "./tailscale-manager.js";
+import { isRunningAsService } from "./service.js";
+import { getToken, verifyToken } from "./auth-manager.js";
+import { getCookie } from "hono/cookie";
+import type { SocketData } from "./ws-bridge.js";
+import type { ServerWebSocket } from "bun";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = process.env.__COMPANION_PACKAGE_ROOT || resolve(__dirname, "..");
+
+import { DEFAULT_PORT_DEV, DEFAULT_PORT_PROD } from "./constants.js";
+
+const defaultPort = process.env.NODE_ENV === "production" ? DEFAULT_PORT_PROD : DEFAULT_PORT_DEV;
+const port = Number(process.env.PORT) || defaultPort;
+const host = process.env.HOST || "0.0.0.0";
+const sessionStore = new SessionStore(process.env.COMPANION_SESSION_DIR);
+const wsBridge = new WsBridge();
+const launcher = new CliLauncher(port);
+const worktreeTracker = new WorktreeTracker();
+const CONTAINER_STATE_PATH = join(COMPANION_HOME, "containers.json");
+const terminalManager = new TerminalManager();
+const noVncProxy = new NoVncProxy();
+const prPoller = new PRPoller(wsBridge);
+const recorder = new RecorderManager();
+const cronScheduler = new CronScheduler(launcher, wsBridge);
+const agentExecutor = new AgentExecutor(launcher, wsBridge);
+const linearAgentBridge = new LinearAgentBridge(agentExecutor, wsBridge);
+
+const orchestrator = new SessionOrchestrator({
+  launcher, wsBridge, sessionStore, worktreeTracker,
+  prPoller, agentExecutor,
+});
+
+// ── Cloud relay connection (for receiving webhooks behind a firewall) ────────
+// The relay forwards platform webhooks (e.g. GitHub, Slack) to the Companion
+// instance via an outbound WebSocket. Currently no webhook handlers are
+// registered (Chat SDK was removed). The relay is left disabled until handlers
+// are wired up (e.g. LinearAgentBridge or future platform integrations).
+if (process.env.COMPANION_RELAY_URL && process.env.COMPANION_RELAY_SECRET) {
+  console.warn(
+    "[server] COMPANION_RELAY_URL is set but no relay webhook handlers are registered. " +
+    "The relay client will not be started. Remove COMPANION_RELAY_URL/COMPANION_RELAY_SECRET " +
+    "or wire up webhook handlers to use relay mode.",
+  );
+}
+
+// ── Restore persisted sessions from disk ────────────────────────────────────
+wsBridge.setStore(sessionStore);
+wsBridge.setRecorder(recorder);
+launcher.setStore(sessionStore);
+launcher.setRecorder(recorder);
+launcher.restoreFromDisk();
+wsBridge.restoreFromDisk();
+containerManager.restoreState(CONTAINER_STATE_PATH);
+
+// ── Session orchestrator — centralizes lifecycle event wiring ────────────────
+orchestrator.initialize();
+
+console.log(`[server] Session persistence: ${sessionStore.directory}`);
+if (recorder.isGloballyEnabled()) {
+  console.log(`[server] Recording enabled (dir: ${recorder.getRecordingsDir()}, max: ${recorder.getMaxLines()} lines)`);
+}
+
+// ── Log file persistence — writes all log output to ~/.companion/logs/ ───────
+const logFileWriter = initLogFile();
+if (logFileWriter) {
+  console.log(`[server] Log file enabled (dir: ${logFileWriter.getLogsDir()}, max: ${logFileWriter.getMaxLines()} lines, file: ${logFileWriter.filePath})`);
+}
+
+const app = new Hono();
+
+// ── Health endpoint — always unauthenticated (used by Fly.io + control plane) ─
+const startTime = Date.now();
+app.get("/health", (c) => {
+  return c.json({
+    ok: true,
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    sessions: launcher.listSessions().length,
+  });
+});
+
+// ── Managed auth middleware — only active when COMPANION_AUTH_ENABLED=1 ────
+const hasManagedAuthSecret = Boolean(process.env.COMPANION_AUTH_SECRET?.trim());
+const managedAuthEnabled =
+  process.env.COMPANION_AUTH_ENABLED === "1" ||
+  (hasManagedAuthSecret && process.env.COMPANION_AUTH_ENABLED !== "0");
+
+if (managedAuthEnabled) {
+  const { managedAuth } = await import("./middleware/managed-auth.js");
+  app.use("/*", managedAuth);
+  console.log("[server] Managed auth enabled");
+} else {
+  console.log("[server] Managed auth disabled");
+}
+
+app.use("/api/*", cors());
+app.route("/api", createRoutes(orchestrator, launcher, wsBridge, terminalManager, prPoller, recorder, cronScheduler, agentExecutor, linearAgentBridge, port));
+
+// Dynamic manifest — embeds auth token in start_url so PWA auto-authenticates
+// on first launch. iOS gives standalone PWAs isolated storage from Safari,
+// so this is the only way to bridge auth across the install boundary.
+app.get("/manifest.json", (c) => {
+  const manifest = {
+    name: "The Companion",
+    short_name: "Companion",
+    description: "Web UI for Claude Code and Codex",
+    start_url: "/",
+    scope: "/",
+    display: "standalone" as const,
+    background_color: "#262624",
+    theme_color: "#d97757",
+    icons: [
+      { src: "/icon-192.png", sizes: "192x192", type: "image/png", purpose: "any" },
+      { src: "/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any" },
+    ],
+  };
+
+  // If the user has an auth cookie (set during login), embed token in start_url.
+  // Safari sends this cookie when fetching the manifest at "Add to Home Screen" time.
+  const authCookie = getCookie(c, "companion_auth");
+  if (authCookie && verifyToken(authCookie)) {
+    manifest.start_url = `/?token=${authCookie}`;
+  } else {
+    // Localhost bypass — always embed the token for same-machine installs
+    const bunServer = c.env as { requestIP?: (req: Request) => { address: string } | null };
+    const ip = bunServer?.requestIP?.(c.req.raw);
+    const addr = ip?.address ?? "";
+    if (addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1") {
+      manifest.start_url = `/?token=${getToken()}`;
+    }
+  }
+
+  c.header("Content-Type", "application/manifest+json");
+  return c.json(manifest);
+});
+
+// In production, serve built frontend using absolute path (works when installed as npm package)
+if (process.env.NODE_ENV === "production") {
+  const distDir = resolve(packageRoot, "dist");
+  app.use("/*", cacheControlMiddleware());
+  app.use("/*", serveStatic({ root: distDir }));
+  app.get("/*", serveStatic({ path: resolve(distDir, "index.html") }));
+}
+
+const server = Bun.serve<SocketData>({
+  hostname: host,
+  port,
+  idleTimeout: 0, // Disable top-level idle timeout — it kills idle browser WebSockets (code 1006)
+  async fetch(req, server) {
+    const url = new URL(req.url);
+
+    // ── CLI WebSocket — Claude Code CLI connects here via --sdk-url ────
+    const cliMatch = url.pathname.match(/^\/ws\/cli\/([a-f0-9-]+)$/);
+    if (cliMatch) {
+      const sessionId = cliMatch[1];
+      const upgraded = server.upgrade(req, {
+        data: { kind: "cli" as const, sessionId },
+      });
+      if (upgraded) return undefined;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    }
+
+    // Helper: check if request is from localhost (same machine)
+    const reqIp = server.requestIP(req);
+    const reqAddr = reqIp?.address ?? "";
+    const isLocalhost = reqAddr === "127.0.0.1" || reqAddr === "::1" || reqAddr === "::ffff:127.0.0.1";
+
+    // ── Browser WebSocket — connects to a specific session ─────────────
+    const browserMatch = url.pathname.match(/^\/ws\/browser\/([a-f0-9-]+)$/);
+    if (browserMatch) {
+      if (managedAuthEnabled) {
+        const auth = await authenticateManagedWebSocket(req);
+        if (!auth.ok) {
+          return new Response(auth.body || "Unauthorized", { status: auth.status });
+        }
+      } else {
+        const wsToken = url.searchParams.get("token");
+        if (!isLocalhost && !verifyToken(wsToken)) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+      }
+      const sessionId = browserMatch[1];
+      const upgraded = server.upgrade(req, {
+        data: { kind: "browser" as const, sessionId },
+      });
+      if (upgraded) return undefined;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    }
+
+    // ── Terminal WebSocket — embedded terminal PTY connection ─────────
+    const termMatch = url.pathname.match(/^\/ws\/terminal\/([a-f0-9-]+)$/);
+    if (termMatch) {
+      if (managedAuthEnabled) {
+        const auth = await authenticateManagedWebSocket(req);
+        if (!auth.ok) {
+          return new Response(auth.body || "Unauthorized", { status: auth.status });
+        }
+      } else {
+        const wsToken = url.searchParams.get("token");
+        if (!isLocalhost && !verifyToken(wsToken)) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+      }
+      const terminalId = termMatch[1];
+      const upgraded = server.upgrade(req, {
+        data: { kind: "terminal" as const, terminalId },
+      });
+      if (upgraded) return undefined;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    }
+
+    // ── noVNC WebSocket — proxies VNC data to container's websockify ────
+    const novncMatch = url.pathname.match(/^\/ws\/novnc\/([a-f0-9-]+)$/);
+    if (novncMatch) {
+      if (managedAuthEnabled) {
+        const auth = await authenticateManagedWebSocket(req);
+        if (!auth.ok) {
+          return new Response(auth.body || "Unauthorized", { status: auth.status });
+        }
+      } else {
+        const wsToken = url.searchParams.get("token");
+        if (!isLocalhost && !verifyToken(wsToken)) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+      }
+      const sessionId = novncMatch[1];
+      const upgraded = server.upgrade(req, {
+        data: { kind: "novnc" as const, sessionId },
+      });
+      if (upgraded) return undefined;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    }
+
+    // Hono handles the rest
+    return app.fetch(req, server);
+  },
+  websocket: {
+    idleTimeout: 0,
+    sendPings: false, // Disable Bun ping timeout that kills CLI connections (code 1006)
+    open(ws: ServerWebSocket<SocketData>) {
+      const data = ws.data;
+      if (data.kind === "cli") {
+        wsBridge.handleCLIOpen(ws, data.sessionId);
+        launcher.markConnected(data.sessionId);
+      } else if (data.kind === "browser") {
+        wsBridge.handleBrowserOpen(ws, data.sessionId);
+      } else if (data.kind === "terminal") {
+        terminalManager.addBrowserSocket(ws);
+      } else if (data.kind === "novnc") {
+        noVncProxy.handleOpen(ws, data.sessionId);
+      }
+    },
+    message(ws: ServerWebSocket<SocketData>, msg: string | Buffer) {
+      const data = ws.data;
+      if (data.kind === "cli") {
+        wsBridge.handleCLIMessage(ws, msg);
+      } else if (data.kind === "browser") {
+        wsBridge.handleBrowserMessage(ws, msg);
+      } else if (data.kind === "terminal") {
+        terminalManager.handleBrowserMessage(ws, msg);
+      } else if (data.kind === "novnc") {
+        noVncProxy.handleMessage(ws, msg);
+      }
+    },
+    close(ws: ServerWebSocket<SocketData>, code?: number, _reason?: string) {
+      console.log("[ws-close]", ws.data.kind, "code=" + code);
+      const data = ws.data;
+      if (data.kind === "cli") {
+        wsBridge.handleCLIClose(ws);
+      } else if (data.kind === "browser") {
+        wsBridge.handleBrowserClose(ws);
+      } else if (data.kind === "terminal") {
+        terminalManager.removeBrowserSocket(ws);
+      } else if (data.kind === "novnc") {
+        noVncProxy.handleClose(ws);
+      }
+    },
+  },
+});
+
+const authToken = getToken();
+console.log(`Server running on http://${host}:${server.port}`);
+console.log();
+console.log(`  Auth token: ${authToken}`);
+if (process.env.COMPANION_AUTH_TOKEN) {
+  console.log("  (using COMPANION_AUTH_TOKEN env var)");
+}
+console.log();
+console.log(`  CLI WebSocket:     ws://localhost:${server.port}/ws/cli/:sessionId`);
+console.log(`  Browser WebSocket: ws://localhost:${server.port}/ws/browser/:sessionId`);
+
+if (process.env.NODE_ENV !== "production") {
+  console.log("Dev mode: frontend at http://localhost:5174");
+}
+
+// ── Cron scheduler ──────────────────────────────────────────────────────────
+cronScheduler.startAll();
+
+// ── Agent system ────────────────────────────────────────────────────────────
+migrateCronJobsToAgents();
+migrateLinearCredentialsToAgents();
+agentExecutor.startAll();
+
+// ── Image pull manager — pre-pull missing Docker images for environments ────
+imagePullManager.initFromEnvironments();
+
+// ── Tailscale Funnel restoration ────────────────────────────────────────────
+restoreTailscaleFunnel(port).catch((err) => {
+  console.warn("[server] Tailscale Funnel restoration failed:", err);
+});
+
+// ── Update checker ──────────────────────────────────────────────────────────
+startPeriodicCheck();
+if (isRunningAsService()) {
+  setServiceMode(true);
+  console.log("[server] Running as background service (auto-update available)");
+}
+
+// ── Runtime diagnostics ──────────────────────────────────────────────────────
+import { log } from "./logger.js";
+import { metricsCollector } from "./metrics-collector.js";
+
+const DIAGNOSTICS_INTERVAL_MS = 5 * 60_000; // every 5 minutes
+setInterval(() => {
+  const snap = metricsCollector.getSnapshot(wsBridge);
+  const mem = snap.gauges.memory;
+  const mb = (bytes: number) => (bytes / 1024 / 1024).toFixed(1);
+  const sessionStats = wsBridge.getSessionMemoryStats();
+  const topSessions = sessionStats
+    .sort((a, b) => b.historyLen - a.historyLen)
+    .slice(0, 3)
+    .map((s) => `${s.id.slice(0, 8)}(h=${s.historyLen},b=${s.browsers})`)
+    .join(", ");
+
+  log.info("diagnostics", "Runtime snapshot", {
+    rss: `${mb(mem.rss)}MB`,
+    heap: `${mb(mem.heapUsed)}/${mb(mem.heapTotal)}MB`,
+    external: `${mb(mem.external)}MB`,
+    sessions: snap.gauges.totalActiveSessions,
+    browsers: snap.gauges.connectedBrowsers,
+    historyMsgs: snap.gauges.totalHistoryMessages,
+    pendingMsgs: snap.gauges.totalPendingMessages,
+    eventBuffer: snap.gauges.totalEventBufferSize,
+    errors: Object.values(snap.counters.errors).reduce((a, b) => a + b, 0),
+    topSessions: topSessions || "none",
+  });
+}, DIAGNOSTICS_INTERVAL_MS);
+
+// ── Graceful shutdown — persist container state ──────────────────────────────
+function gracefulShutdown() {
+  console.log("[server] Persisting container state before shutdown...");
+  containerManager.persistState(CONTAINER_STATE_PATH);
+  cleanupTailscaleFunnel(port);
+  closeLogFile();
+  process.exit(0);
+}
+process.on("SIGTERM", gracefulShutdown);
+process.on("SIGINT", gracefulShutdown);
+