@hienlh/ppm 0.9.0-beta.4 → 0.9.0-beta.6

package/src/providers/claude-agent-sdk.ts

@@ -25,6 +25,84 @@ function getSdkSessionId(ppmId: string): string {
   return getSessionMapping(ppmId) ?? ppmId;
 }
 
+// ── Streaming Input: message channel for persistent query ──
+
+interface MessageController {
+  push(msg: any): void;
+  done(): void;
+}
+
+function createMessageChannel(): {
+  generator: AsyncGenerator<any, void, undefined>;
+  controller: MessageController;
+} {
+  const queue: any[] = [];
+  let resolve: ((msg: any) => void) | null = null;
+  let isDone = false;
+
+  async function* gen(): AsyncGenerator<any, void, undefined> {
+    while (!isDone) {
+      if (queue.length > 0) {
+        yield queue.shift()!;
+      } else {
+        const msg = await new Promise<any>((r) => { resolve = r; });
+        if (!isDone) yield msg;
+      }
+    }
+  }
+
+  return {
+    generator: gen(),
+    controller: {
+      push(msg: any) {
+        if (isDone) return;
+        if (resolve) {
+          const r = resolve;
+          resolve = null;
+          r(msg);
+        } else {
+          queue.push(msg);
+        }
+      },
+      done() {
+        isDone = true;
+        if (resolve) {
+          const r = resolve;
+          resolve = null;
+          r(null); // Unblock pending promise; isDone prevents yield
+        }
+      },
+    },
+  };
+}
+
+/** Build a MessageParam with optional image content blocks */
+function buildMessageParam(
+  text: string,
+  images?: Array<{ data: string; mediaType: string }>,
+): { role: 'user'; content: string | any[] } {
+  if (!images || images.length === 0) {
+    return { role: 'user' as const, content: text };
+  }
+  const blocks: any[] = [];
+  for (const img of images) {
+    blocks.push({
+      type: 'image',
+      source: { type: 'base64', media_type: img.mediaType, data: img.data },
+    });
+  }
+  if (text.trim()) {
+    blocks.push({ type: 'text', text });
+  }
+  return { role: 'user' as const, content: blocks };
+}
+
+interface StreamingSession {
+  meta: Session;
+  query: any;
+  controller: MessageController;
+}
+
 /**
  * Pending approval: canUseTool callback creates a promise,
  * yields an approval_request event, then awaits resolution from FE.
@@ -50,6 +128,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   private activeQueries = new Map<string, { close: () => void }>();
   /** Fork source: ppmSessionId → sourceSessionId (used on first message to fork) */
   private forkSources = new Map<string, string>();
+  /** Streaming sessions: persistent query + message channel per session */
+  private streamingSessions = new Map<string, StreamingSession>();
 
   /** Auth-related env keys for diagnostic logging */
   private readonly AUTH_ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
@@ -220,6 +300,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   }
 
   async deleteSession(sessionId: string): Promise<void> {
+    this.closeStreamingSession(sessionId);
     this.activeSessions.delete(sessionId);
     this.messageCount.delete(sessionId);
   }
@@ -260,11 +341,63 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     }
   }
 
+  /**
+   * Push a follow-up message into an existing streaming session's generator.
+   * Called by WS handler for follow-up messages (Phase 2).
+   */
+  pushMessage(sessionId: string, content: string, opts?: { priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }> }): void {
+    const ss = this.streamingSessions.get(sessionId);
+    if (!ss) {
+      console.warn(`[sdk] pushMessage: no streaming session for ${sessionId}`);
+      return;
+    }
+    const msgContent = buildMessageParam(content, opts?.images);
+    ss.controller.push({
+      type: 'user',
+      message: msgContent,
+      parent_tool_use_id: null,
+      session_id: sessionId,
+      priority: opts?.priority ?? 'next',
+    });
+    console.log(`[sdk] pushMessage: session=${sessionId} priority=${opts?.priority ?? 'next'}`);
+  }
+
+  /** Close a streaming session — generator + query cleanup */
+  closeStreamingSession(sessionId: string): void {
+    const ss = this.streamingSessions.get(sessionId);
+    if (ss) {
+      ss.controller.done();
+      ss.query.close();
+      this.streamingSessions.delete(sessionId);
+      console.log(`[sdk] closeStreamingSession: session=${sessionId}`);
+    }
+  }
+
+  /** Check if a streaming session is active for a given session ID */
+  hasStreamingSession(sessionId: string): boolean {
+    return this.streamingSessions.has(sessionId);
+  }
+
   async *sendMessage(
     sessionId: string,
     message: string,
-    opts?: import("./provider.interface.ts").SendMessageOpts & { forkSession?: boolean },
+    opts?: import("./provider.interface.ts").SendMessageOpts & { forkSession?: boolean; priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }> },
   ): AsyncIterable<ChatEvent> {
+    // Follow-up: push into existing streaming session, yield nothing
+    const existingStream = this.streamingSessions.get(sessionId);
+    if (existingStream) {
+      const msgContent = buildMessageParam(message, opts?.images);
+      existingStream.controller.push({
+        type: 'user',
+        message: msgContent,
+        parent_tool_use_id: null,
+        session_id: sessionId,
+        priority: opts?.priority ?? 'next',
+      });
+      console.log(`[sdk] sendMessage follow-up: session=${sessionId} pushed to generator`);
+      return; // Events flow through first-message's consumer loop
+    }
+
     if (!this.activeSessions.has(sessionId)) {
       await this.resumeSession(sessionId);
     }
@@ -387,6 +520,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     let resultSubtype: string | undefined;
     let resultNumTurns: number | undefined;
     let resultContextWindowPct: number | undefined;
+    let yieldedDone = false;
     try {
       // Resolve SDK's actual session ID for resume (may differ from PPM's UUID)
       // For fork: use the source session's SDK id
@@ -458,14 +592,25 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         includePartialMessages: true,
       };
 
+      // Streaming input: create message channel and persistent query
+      const { generator: streamGen, controller: streamCtrl } = createMessageChannel();
+      const firstMsg = {
+        type: 'user' as const,
+        message: buildMessageParam(message),
+        parent_tool_use_id: null,
+        session_id: sessionId,
+      };
+      streamCtrl.push(firstMsg);
+
       const q = query({
-        prompt: message,
+        prompt: streamGen,
         options: {
           ...queryOptions,
           ...(permissionHooks && { hooks: permissionHooks }),
           canUseTool,
         } as any,
       });
+      this.streamingSessions.set(sessionId, { meta, query: q, controller: streamCtrl });
       this.activeQueries.set(sessionId, q);
       let eventSource: AsyncIterable<any> = q;
 
@@ -480,22 +625,29 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       let retryCount = 0;
       let authRetried = false;
 
+      let hadAnyEvents = false;
       retryLoop: while (true) {
       let sdkEventCount = 0;
       for await (const msg of eventSource) {
         sdkEventCount++;
+        hadAnyEvents = true;
         if (sdkEventCount === 1) {
           console.log(`[sdk] first event received: type=${(msg as any).type} subtype=${(msg as any).subtype ?? "none"}`);
           // Detect immediate failure: first event is a result with error + 0 turns
           if ((msg as any).type === "result" && (msg as any).subtype === "error_during_execution" && ((msg as any).num_turns ?? 0) === 0 && retryCount < MAX_RETRIES) {
             retryCount++;
             console.warn(`[sdk] transient error on first event — retrying (attempt ${retryCount}/${MAX_RETRIES})`);
-            // Re-create query for retry — don't reuse sessionId in case SDK partially created it
+            // Close failed query and old channel, create new channel + query for retry
+            streamCtrl.done();
+            q.close();
+            const { generator: retryGen, controller: retryCtrl } = createMessageChannel();
+            retryCtrl.push(firstMsg);
             const retryOpts = { ...queryOptions, sessionId: undefined, resume: undefined };
             const rq = query({
-              prompt: message,
+              prompt: retryGen,
               options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
             });
+            this.streamingSessions.set(sessionId, { meta, query: rq, controller: retryCtrl });
             this.activeQueries.set(sessionId, rq);
             eventSource = rq;
             continue retryLoop;
@@ -641,11 +793,17 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                 const refreshedAccount = accountService.getWithTokens(account.id);
                 if (refreshedAccount) {
                   const retryEnv = this.buildQueryEnv(meta.projectPath, refreshedAccount);
+                  // Close failed query and old channel, create new channel + query with refreshed token
+                  streamCtrl.done();
+                  q.close();
+                  const { generator: authRetryGen, controller: authRetryCtrl } = createMessageChannel();
+                  authRetryCtrl.push(firstMsg);
                   const retryOpts = { ...queryOptions, sessionId: undefined, resume: undefined, env: retryEnv };
                   const rq = query({
-                    prompt: message,
+                    prompt: authRetryGen,
                     options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
                   });
+                  this.streamingSessions.set(sessionId, { meta, query: rq, controller: authRetryCtrl });
                   this.activeQueries.set(sessionId, rq);
                   eventSource = rq;
                   continue retryLoop;
@@ -717,9 +875,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             const errCode = this.detectResultErrorCode(msg);
             if (errCode === 429) {
               accountSelector.onRateLimit(account.id);
-              // Post-stream 429 already has content — surface error to user
+              // Post-stream 429 — surface error, continue waiting for next turn
               yield { type: "error", message: "Rate limited. This account is now on cooldown. Please retry." };
-              break;
+              continue;
             } else if (errCode === 401) {
               // Try refresh once
               try {
@@ -827,7 +985,26 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               }
             }
           }
-          break;
+
+          // Streaming input: yield done for this turn, then continue for next turn
+          yieldedDone = true;
+          yield {
+            type: "done",
+            sessionId,
+            resultSubtype: resultSubtype as any,
+            numTurns: resultNumTurns,
+            contextWindowPct: resultContextWindowPct,
+          };
+
+          // Reset per-turn state for next turn
+          lastPartialText = "";
+          pendingToolCount = 0;
+          assistantContent = "";
+          resultSubtype = undefined;
+          resultNumTurns = undefined;
+          resultContextWindowPct = undefined;
+          sdkEventCount = 0;
+          continue; // Wait for next turn from generator
         }
       }
 
@@ -836,7 +1013,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         yield approvalEvents.shift()!;
       }
 
-      if (sdkEventCount === 0) {
+      if (!hadAnyEvents) {
         yield { type: "error", message: "Claude did not respond. Check that 'claude' CLI works in your terminal." };
       }
       break; // Exit retryLoop — normal completion
@@ -846,88 +1023,47 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       console.error(`[sdk] session=${sessionId} cwd=${meta.projectPath} error: ${msg}`);
       if (msg.includes("abort") || msg.includes("closed")) {
         // User-initiated abort or WS closed — nothing to report
-      } else if (!isFirstMessage && msg.includes("exited with code")) {
-        // SDK subprocess crashed during session resume — retry as fresh session
-        console.warn(`[sdk] session resume failed, retrying as fresh session`);
-        try {
-          const providerConfig = this.getProviderConfig();
-          const effectiveCwd = meta.projectPath || homedir();
-          const retryAccount = accountSelector.isEnabled() ? accountSelector.next() : null;
-          const queryEnv = this.buildQueryEnv(meta.projectPath, retryAccount);
-          const retryOptions = {
-              ...(process.platform === "win32" && { executable: "node" }),
-              cwd: effectiveCwd,
-              systemPrompt: systemPromptOpt,
-              settingSources: ["user", "project"],
-              env: queryEnv,
-              settings: { permissions: { allow: [], deny: [] } },
-              allowedTools,
-              permissionMode,
-              allowDangerouslySkipPermissions: isBypass,
-              ...(providerConfig.model && { model: providerConfig.model }),
-              maxTurns: providerConfig.max_turns ?? 100,
-              includePartialMessages: true,
-            };
-          const retryQuery = query({
-              prompt: message,
-              options: {
-                ...retryOptions,
-                ...(permissionHooks && { hooks: permissionHooks }),
-                canUseTool,
-              } as any,
-            });
-          this.activeQueries.set(sessionId, retryQuery);
-          for await (const retryMsg of retryQuery) {
-            if (retryMsg.type === "system") continue;
-            if (retryMsg.type === "result") {
-              const r = retryMsg as any;
-              if (r.subtype && r.subtype !== "success") {
-                const retryErrors = Array.isArray(r.errors) ? r.errors.join("\n") : "";
-                yield { type: "error", message: retryErrors || `Agent stopped: ${r.subtype}` };
-              }
-              resultSubtype = r.subtype;
-              resultNumTurns = r.num_turns;
-              break;
-            }
-            if ((retryMsg as any).type === "assistant") {
-              const content = (retryMsg as any).message?.content;
-              if (Array.isArray(content)) {
-                for (const block of content) {
-                  if (block.type === "text" && typeof block.text === "string") {
-                    yield { type: "text", content: block.text };
-                  }
-                }
-              }
-            }
-          }
-        } catch (retryErr) {
-          const retryMsg = (retryErr as Error).message ?? String(retryErr);
-          console.error(`[sdk] retry also failed: ${retryMsg}`);
-          yield { type: "error", message: `SDK error: ${msg}` };
-        }
+      } else if (msg.includes("exited with code")) {
+        // Subprocess crashed — session will auto-recover on next message
+        console.warn(`[sdk] session=${sessionId} subprocess crashed: ${msg}`);
+        yield { type: "error", message: `SDK subprocess crashed. Send another message to auto-recover.` };
       } else {
         yield { type: "error", message: `SDK error: ${msg}` };
       }
     } finally {
       this.activeQueries.delete(sessionId);
+      this.streamingSessions.delete(sessionId);
+      console.log(`[sdk] session=${sessionId} streaming session ended`);
     }
 
-    yield {
-      type: "done",
-      sessionId,
-      resultSubtype: resultSubtype as any,
-      numTurns: resultNumTurns,
-      contextWindowPct: resultContextWindowPct,
-    };
+    // Final done event when query ends (crash, close, generator done)
+    // Skip if we already yielded done from the result handler (avoid duplicate)
+    if (!yieldedDone) {
+      yield {
+        type: "done",
+        sessionId,
+        resultSubtype: resultSubtype as any,
+        numTurns: resultNumTurns,
+        contextWindowPct: resultContextWindowPct,
+      };
+    }
   }
 
 
-  /** Abort an active query for a session */
+  /** Interrupt the current turn — session stays alive for the next message */
   abortQuery(sessionId: string): void {
+    const ss = this.streamingSessions.get(sessionId);
+    if (ss && typeof ss.query.interrupt === "function") {
+      ss.query.interrupt().catch(() => {});
+      console.log(`[sdk] abortQuery: interrupted session=${sessionId}`);
+      return;
+    }
+    // Fallback: close query entirely and clean up streaming session
     const q = this.activeQueries.get(sessionId);
     if (q) {
       q.close();
       this.activeQueries.delete(sessionId);
+      this.streamingSessions.delete(sessionId);
     }
   }
 

package/src/server/index.ts

@@ -455,12 +455,15 @@ export async function startServer(options: {
   }
   console.log();
 
-  // Graceful shutdown — stop server + tunnel + DB on exit
+  // Graceful shutdown — stop server + tunnel + preview tunnels + DB on exit
   const shutdown = () => {
     try { server.stop(true); } catch {}
     try {
       import("../services/tunnel.service.ts").then(({ tunnelService }) => tunnelService.stopTunnel()).catch(() => {});
     } catch {}
+    try {
+      import("./routes/browser-preview.ts").then(({ stopAllPreviewTunnels }) => stopAllPreviewTunnels()).catch(() => {});
+    } catch {}
     try {
       import("../services/db.service.ts").then(({ closeDb }) => closeDb()).catch(() => {});
     } catch {}

package/src/server/routes/browser-preview.ts

@@ -1,89 +1,159 @@
 import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { ensureCloudflared } from "../../services/cloudflared.service.ts";
 
 /**
- * Browser preview reverse proxy — forwards requests to localhost:<port>.
- * Mounted at /api/preview/:port/* so the frontend iframe can load
- * any localhost dev server through PPM's own origin (avoiding CORS/framing issues).
+ * Browser preview API — starts per-port Cloudflare Quick Tunnels so the
+ * frontend can iframe any localhost dev server without CORS/path issues.
+ *
+ * POST /api/preview/tunnel { port: 3000 } → { url: "https://xxx.trycloudflare.com" }
+ * DELETE /api/preview/tunnel/:port → stops tunnel for that port
+ * GET /api/preview/tunnels → list active tunnels
  */
 export const browserPreviewRoutes = new Hono();
 
-/** Only allow proxying to localhost ports (security: prevent SSRF) */
-function isValidPort(port: string): boolean {
-  const n = parseInt(port, 10);
-  return !isNaN(n) && n >= 1 && n <= 65535;
+const TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+interface ActiveTunnel {
+  port: number;
+  url: string;
+  process: import("bun").Subprocess;
+  startedAt: number;
 }
 
-browserPreviewRoutes.all("/:port{[0-9]+}/*", async (c) => {
-  const port = c.req.param("port");
-  if (!isValidPort(port)) {
-    return c.text("Invalid port", 400);
+/** Active tunnels keyed by port */
+const activeTunnels = new Map<number, ActiveTunnel>();
+
+/** Start a tunnel for a localhost port */
+browserPreviewRoutes.post("/tunnel", async (c) => {
+  const body = await c.req.json<{ port: number }>().catch(() => null);
+  const port = body?.port;
+  if (!port || port < 1 || port > 65535) {
+    return c.json(err("Invalid port (1-65535)"), 400);
   }
 
-  // Build target URL — strip the /api/preview/:port prefix
-  const url = new URL(c.req.url);
-  const prefix = `/api/preview/${port}`;
-  const targetPath = url.pathname.slice(prefix.length) || "/";
-  const targetUrl = `http://localhost:${port}${targetPath}${url.search}`;
+  // Return existing tunnel if already running
+  const existing = activeTunnels.get(port);
+  if (existing) {
+    return c.json(ok({ port, url: existing.url }));
+  }
 
   try {
-    // Forward the request with original method, headers, and body
-    const headers = new Headers(c.req.raw.headers);
-    // Remove host header so target server sees localhost
-    headers.delete("host");
-
-    const resp = await fetch(targetUrl, {
-      method: c.req.method,
-      headers,
-      body: ["GET", "HEAD"].includes(c.req.method) ? undefined : c.req.raw.body,
-      redirect: "manual",
-    });
+    const bin = await ensureCloudflared();
+    const proc = Bun.spawn(
+      [bin, "tunnel", "--url", `http://127.0.0.1:${port}`],
+      { stderr: "pipe", stdout: "ignore", stdin: "ignore" },
+    );
 
-    // Clone response headers, remove framing restrictions so iframe works
-    const respHeaders = new Headers(resp.headers);
-    respHeaders.delete("x-frame-options");
-    respHeaders.delete("content-security-policy");
+    // Read stderr to find tunnel URL
+    const reader = proc.stderr.getReader();
+    const decoder = new TextDecoder();
+    const url = await new Promise<string>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        try { proc.kill(); } catch {}
+        reject(new Error("Tunnel timed out after 30s"));
+      }, 30_000);
 
-    return new Response(resp.body, {
-      status: resp.status,
-      statusText: resp.statusText,
-      headers: respHeaders,
+      let buffer = "";
+      let found = false;
+      const read = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (found) continue;
+            buffer += decoder.decode(value, { stream: true });
+            const match = buffer.match(TUNNEL_URL_REGEX);
+            if (match) {
+              found = true;
+              buffer = "";
+              clearTimeout(timeout);
+              resolve(match[0]);
+            }
+          }
+          if (!found) {
+            clearTimeout(timeout);
+            reject(new Error("cloudflared exited without tunnel URL"));
+          }
+        } catch (e) {
+          if (!found) { clearTimeout(timeout); reject(e); }
+        }
+      };
+      read();
     });
-  } catch {
-    return c.text(`Cannot connect to localhost:${port}`, 502);
+
+    activeTunnels.set(port, { port, url, process: proc, startedAt: Date.now() });
+
+    // Auto-cleanup when process exits
+    proc.exited.then(() => activeTunnels.delete(port)).catch(() => activeTunnels.delete(port));
+
+    console.log(`[preview] tunnel started for port ${port} → ${url}`);
+    return c.json(ok({ port, url }));
+  } catch (e: any) {
+    return c.json(err(e.message || "Failed to start tunnel"), 500);
   }
 });
 
-// Handle root path (no trailing slash)
-browserPreviewRoutes.all("/:port{[0-9]+}", async (c) => {
-  const port = c.req.param("port");
-  if (!isValidPort(port)) {
-    return c.text("Invalid port", 400);
+/** Stop a tunnel */
+browserPreviewRoutes.delete("/tunnel/:port{[0-9]+}", (c) => {
+  const port = parseInt(c.req.param("port"), 10);
+  const tunnel = activeTunnels.get(port);
+  if (!tunnel) {
+    return c.json(err("No tunnel running for this port"), 404);
   }
 
-  const url = new URL(c.req.url);
-  const targetUrl = `http://localhost:${port}/${url.search}`;
+  try { tunnel.process.kill(); } catch {}
+  activeTunnels.delete(port);
+  console.log(`[preview] tunnel stopped for port ${port}`);
+  return c.json(ok({ port }));
+});
 
-  try {
-    const headers = new Headers(c.req.raw.headers);
-    headers.delete("host");
-
-    const resp = await fetch(targetUrl, {
-      method: c.req.method,
-      headers,
-      body: ["GET", "HEAD"].includes(c.req.method) ? undefined : c.req.raw.body,
-      redirect: "manual",
-    });
+/** List active tunnels */
+browserPreviewRoutes.get("/tunnels", (c) => {
+  const list = Array.from(activeTunnels.values()).map((t) => ({
+    port: t.port,
+    url: t.url,
+    startedAt: t.startedAt,
+  }));
+  return c.json(ok(list));
+});
 
-    const respHeaders = new Headers(resp.headers);
-    respHeaders.delete("x-frame-options");
-    respHeaders.delete("content-security-policy");
+/** Check if a cloudflared process is still alive */
+function isProcessAlive(proc: import("bun").Subprocess): boolean {
+  try { process.kill(proc.pid, 0); return true; } catch { return false; }
+}
 
-    return new Response(resp.body, {
-      status: resp.status,
-      statusText: resp.statusText,
-      headers: respHeaders,
-    });
-  } catch {
-    return c.text(`Cannot connect to localhost:${port}`, 502);
+/** Remove ghost tunnels (process died or target port no longer listening) */
+async function cleanupGhostTunnels() {
+  for (const [port, tunnel] of activeTunnels) {
+    // Check if cloudflared process is still running
+    if (!isProcessAlive(tunnel.process)) {
+      console.log(`[preview] ghost cleanup: tunnel for port ${port} — process dead`);
+      activeTunnels.delete(port);
+      continue;
+    }
+    // Check if target port is still listening
+    try {
+      const conn = await Bun.connect({ hostname: "127.0.0.1", port, socket: {
+        data() {}, open(s) { s.end(); }, error() {}, close() {},
+      }});
+      conn.end();
+    } catch {
+      // Port not listening — kill tunnel
+      console.log(`[preview] ghost cleanup: tunnel for port ${port} — port not listening`);
+      try { tunnel.process.kill(); } catch {}
+      activeTunnels.delete(port);
+    }
   }
-});
+}
+
+// Run ghost cleanup every 30s
+setInterval(cleanupGhostTunnels, 30_000);
+
+/** Cleanup all tunnels on server shutdown */
+export function stopAllPreviewTunnels() {
+  for (const [port, tunnel] of activeTunnels) {
+    try { tunnel.process.kill(); } catch {}
+    activeTunnels.delete(port);
+  }
+}