flowviant 0.14.0 → 0.17.0

package/bin/cli.mjs

@@ -80,6 +80,9 @@ if (process.argv[2] === 'clean') {
   const { join } = await import('node:path');
   const { homedir } = await import('node:os');
   const { execFileSync } = await import('node:child_process');
+  // Also reap any preview dev-server/tunnel groups a crashed daemon left running.
+  const { reapOrphanPreviews } = await import('./lib/preview.mjs');
+  reapOrphanPreviews((m) => console.log(m));
   const dir = join(homedir(), '.flowviant', 'worktrees');
   if (!existsSync(dir)) {
     console.log('nothing to clean — no worktrees at ~/.flowviant/worktrees.');

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
-export const VERSION = '0.14.0';
+export const VERSION = '0.17.0';
 
 // Credential stored by `flowviant login` (device auth) — the no-token,
 // no-env-var path. An explicit --fleet flag or FLOWVIANT_FLEET env still wins.

package/bin/lib/fleet.mjs

@@ -47,6 +47,7 @@ import {
   SINGLE_RESUME,
 } from './claude.mjs';
 import { runLiveWorker } from './live.mjs';
+import { reapOrphanPreviews } from './preview.mjs';
 import { preflight } from './preflight.mjs';
 
 async function fetchRoster(haveIds) {
@@ -176,6 +177,9 @@ export async function runFleetDaemon() {
   info(`server · ${FLEET_URL}`);
   console.log('');
   await preflight({ needGit: true });
+  // Kill any preview dev-server/tunnel groups a previously-crashed daemon left
+  // running (detached children survive an ungraceful exit) before we start fresh.
+  reapOrphanPreviews((m) => info(m));
 
   // Persistent worktree home (0.9.0) — survives daemon restarts AND reboots,
   // so Ctrl+C mid-task never loses local work. Keyed per repo path; each
@@ -481,6 +485,8 @@ export async function runFleetDaemon() {
           label,
           cwd: wt,
           baseRef,
+          repoRoot, // for copying the repo's local env into the preview worktree
+
           getToken: (id) => tokenByAgent.get(id),
           getHasWork: (id) => hasWorkByAgent.get(id) ?? false,
           getMcpUrl: () => mcpUrl,

package/bin/lib/live.mjs

@@ -16,7 +16,7 @@
  * live fleet + repo to shake out. Old (poll/sentinel) mode is untouched.
  */
 
-import { readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, rmSync, existsSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import {
@@ -37,6 +37,13 @@ import { loadPreviewConfig, startPreview } from './preview.mjs';
 // Register a branch preview's tunnel URL with Flowviant (fleet-authed). The
 // reviewer then drives it via "Open live preview" in the node.
 const LIVE_TARGET_URL = FLEET_URL.replace(/\/agents\/?$/, '/live-target');
+// Short TTL + a heartbeat that re-asserts while the tunnel is alive. So a live
+// preview stays linked indefinitely (survives long reviews), but one whose
+// daemon DIED ungracefully (no more heartbeats) drops off the card within the
+// TTL instead of showing a dead URL for 2 hours. TTL comfortably covers a few
+// missed heartbeats.
+const PREVIEW_TTL_MINUTES = 6;
+const PREVIEW_HEARTBEAT_MS = 90_000;
 async function registerLiveTarget(intentId, kind, url) {
   try {
     await fetch(LIVE_TARGET_URL, {
@@ -47,7 +54,7 @@ async function registerLiveTarget(intentId, kind, url) {
         'Content-Type': 'application/json',
       },
       signal: AbortSignal.timeout(30_000),
-      body: JSON.stringify({ intentId, kind, url }),
+      body: JSON.stringify({ intentId, kind, url, ttlMinutes: PREVIEW_TTL_MINUTES }),
     });
   } catch {
     /* best-effort — the tunnel still works; it just isn't linked in the app */
@@ -586,11 +593,39 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
 
 // Per-agent loop — same signature/scaffolding as runFleetWorker, but each task
 // is a persistent SDK session instead of a one-shot claude turn.
+// A preview runs in the agent's WORKTREE — a fresh checkout that lacks the repo's
+// gitignored env files (.env.local etc.), so the app's DB/auth secrets are absent
+// and anything that hits them (sign-in!) 500s. Copy the files the checkout is
+// missing from the real repo into the worktree so the preview runs like local
+// dev. We only copy files ABSENT from the worktree — i.e. the gitignored ones —
+// so nothing tracked is overwritten and (being gitignored) nothing gets committed.
+const PREVIEW_ENV_FILES = ['.env', '.env.local', '.env.development', '.env.development.local'];
+function copyLocalEnvFiles(repoRoot, worktree, log) {
+  if (!repoRoot || repoRoot === worktree) return;
+  let copied = 0;
+  for (const f of PREVIEW_ENV_FILES) {
+    const src = join(repoRoot, f);
+    const dst = join(worktree, f);
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        copyFileSync(src, dst);
+        copied++;
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+  if (copied) {
+    log?.(`preview: brought ${copied} local env file(s) into the worktree so the app has its secrets.`);
+  }
+}
+
 export async function runLiveWorker({
   agentId,
   label,
   cwd,
   baseRef,
+  repoRoot,
   getToken,
   getHasWork,
   getMcpUrl,
@@ -615,8 +650,16 @@ export async function runLiveWorker({
   // kept up while it's in review (a gated agent parks, so it lives until review
   // resolves). Replaced when the next task finishes; torn down on shutdown.
   let preview = null;
-  let previewTarget = null; // { intentId, kind } of the currently-registered link
+  let previewTarget = null; // { intentId, kind, url } of the currently-registered link
+  let previewHeartbeat = null;
+  const stopHeartbeat = () => {
+    if (previewHeartbeat) {
+      clearInterval(previewHeartbeat);
+      previewHeartbeat = null;
+    }
+  };
   const stopPreview = () => {
+    stopHeartbeat();
     if (preview) {
       try {
         preview.stop();
@@ -657,18 +700,30 @@ export async function runLiveWorker({
     if (cfg.dir && cfg.dir !== '.') {
       info(`${label} ${c.dim(`live preview: detected a frontend at ${cfg.dir}/ (port ${entry.port})`)}`);
     }
+    // Give the dev server the repo's local env (gitignored secrets the fresh
+    // worktree is missing) so DB/auth-backed paths like sign-in don't 500.
+    copyLocalEnvFiles(repoRoot, cwd, (m) => info(`${label} ${c.dim(m)}`));
     info(`${label} ${c.dim('starting a live preview of the branch for review…')}`);
     preview = await startPreview({
       worktree: cwd,
       kind,
       cmd: entry.cmd,
       port: entry.port,
+      env: entry.env, // optional: extra env from .flowviant/preview.json
+      hostHeader: entry.hostHeader, // optional: override/disable the Host rewrite
       log: (m) => info(`${label} ${c.dim(m)}`),
     });
     if (preview) {
       onPreview?.(stopPreview); // hand the daemon a stop handle for shutdown
       await registerLiveTarget(intentId, kind, preview.url);
-      previewTarget = { intentId, kind }; // so teardown can drop the link
+      previewTarget = { intentId, kind, url: preview.url }; // teardown drops it; heartbeat re-asserts it
+      // Re-assert the link while the tunnel is alive so it survives long reviews
+      // (and a dead daemon stops re-asserting → the record expires by itself).
+      stopHeartbeat();
+      previewHeartbeat = setInterval(() => {
+        if (previewTarget) void registerLiveTarget(previewTarget.intentId, previewTarget.kind, previewTarget.url);
+      }, PREVIEW_HEARTBEAT_MS);
+      previewHeartbeat.unref?.();
       ok(`${label} ${c.dim('live preview ready — open the node to drive it in your review')}`);
     }
   };

package/bin/lib/preview.mjs

@@ -11,9 +11,17 @@
  * cloudflared / no inferable config → no live preview, and review falls back to
  * the captured evidence the agent attached (never a hard failure).
  *
- * Config shape:
- *   { "ui": { "cmd": "<start dev server>", "port": 5173 },
- *     "api": { "cmd": "<start api>",        "port": 8787 } }
+ * Config shape (the escape hatch for any setup the defaults don't handle — the
+ * repo declares its own recipe, so the daemon never needs per-framework code):
+ *   { "ui": {
+ *       "cmd": "<start dev server>",   // required
+ *       "port": 5173,                  // required
+ *       "env": { "FOO": "bar" },       // optional — extra env for the dev server
+ *       "hostHeader": "localhost"      // optional — Host sent to the origin;
+ *                                      //   false disables the rewrite (for apps
+ *                                      //   that need their real public Host)
+ *     },
+ *     "api": { "cmd": "<start api>", "port": 8787 } }
  */
 
 import { spawn, execFileSync } from 'node:child_process';
@@ -204,6 +212,74 @@ const TUNNEL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
 // Where a dev server announces it bound — "Local: http://localhost:3001/".
 const BIND_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):(\d+)/i;
 
+// ── Orphan reaping ─────────────────────────────────────────────────────────
+// Preview children (dev server + tunnel) are detached so we can kill the whole
+// group — but that also means they SURVIVE an ungraceful daemon death (SIGKILL,
+// crash, box sleep), leaking ports/memory. We record each spawned group's pid +
+// a signature; on the next daemon start we reap any that are still ours.
+const PREVIEW_REGISTRY = join(homedir(), '.flowviant', 'previews.json');
+function readRegistry() {
+  try {
+    const v = JSON.parse(readFileSync(PREVIEW_REGISTRY, 'utf8'));
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+function writeRegistry(list) {
+  try {
+    mkdirSync(join(homedir(), '.flowviant'), { recursive: true });
+    writeFileSync(PREVIEW_REGISTRY, JSON.stringify(list));
+  } catch {
+    /* best-effort */
+  }
+}
+function recordPreviewPid(pid, sig) {
+  if (!pid) return;
+  writeRegistry([...readRegistry(), { pid, sig }]);
+}
+function forgetPreviewPid(pid) {
+  if (!pid) return;
+  writeRegistry(readRegistry().filter((e) => e.pid !== pid));
+}
+// Only kill a pid we can VERIFY is still one of ours — its /proc cmdline must
+// still contain the signature we stored. A reused pid (belonging to something
+// unrelated) won't match, so we never kill a stranger. Linux-only (that's where
+// /proc + process groups work); elsewhere we just clear the registry.
+function stillOurs(pid, sig) {
+  if (platform() !== 'linux') return false;
+  try {
+    const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+    return typeof sig === 'string' && sig.length > 0 && cmd.includes(sig);
+  } catch {
+    return false; // process gone / unreadable
+  }
+}
+
+/** Reap preview process groups left behind by a previously-crashed daemon.
+ *  Call once at daemon startup, before spawning workers. */
+export function reapOrphanPreviews(log) {
+  const list = readRegistry();
+  if (list.length === 0) return;
+  let killed = 0;
+  for (const { pid, sig } of list) {
+    if (!stillOurs(pid, sig)) continue;
+    try {
+      process.kill(-pid, 'SIGKILL'); // whole group
+      killed++;
+    } catch {
+      try {
+        process.kill(pid, 'SIGKILL');
+        killed++;
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+  writeRegistry([]);
+  if (killed) log?.(`reaped ${killed} orphaned preview process${killed === 1 ? '' : 'es'} from a previous run.`);
+}
+
 /**
  * Start the dev server + tunnel for one worktree. Resolves { url, kind, stop }
  * once the tunnel URL is captured, or null if it can't come up. stop() kills
@@ -214,16 +290,37 @@ const BIND_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):(\d+)/i;
  * theirs is taken, and tunneling to the guess then 502s. We fall back to the
  * configured port only if the server never announces one.
  */
-export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs = 180_000 }) {
+export async function startPreview({
+  worktree,
+  kind,
+  cmd,
+  port,
+  env: extraEnv,
+  hostHeader,
+  log,
+  timeoutMs = 180_000,
+}) {
   const cf = await ensureCloudflared(log);
   if (!cf) return null; // fall back to captured evidence
+  // Host the origin sees. Default 'localhost' (what a local browser sends) so
+  // dev servers that validate Host — Vite server.allowedHosts, webpack, Next's
+  // allowedDevOrigins — accept the tunnel. `hostHeader: false` in preview.json
+  // disables the rewrite for apps that route on their real public Host.
+  const hostRewrite =
+    hostHeader === false ? null : typeof hostHeader === 'string' && hostHeader ? hostHeader : 'localhost';
   return new Promise((resolve) => {
     // We SIGKILL the dev server's whole group on teardown, which skips a tool's
     // graceful cleanup — some dev servers (e.g. vinext) leave a singleton
     // dev-lock behind and then REFUSE to start next time. Disable known locks so
     // a reused/uncleaned worktree still previews. Harmless to tools that ignore
-    // these vars; BROWSER=none stops any auto-open.
-    const env = { ...process.env, VINEXT_NO_DEV_LOCK: '1', BROWSER: 'none' };
+    // these vars; BROWSER=none stops any auto-open. A repo's preview.json `env`
+    // is layered last, so it can override any of these.
+    const env = {
+      ...process.env,
+      VINEXT_NO_DEV_LOCK: '1',
+      BROWSER: 'none',
+      ...(extraEnv && typeof extraEnv === 'object' ? extraEnv : {}),
+    };
     // detached so each gets its own process group — `bun run dev` via a shell
     // spawns a grandchild dev server that would otherwise SURVIVE a kill of the
     // shell. We kill the whole group instead. stdout/stderr piped so we can read
@@ -235,6 +332,9 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
       stdio: ['ignore', 'pipe', 'pipe'],
       env,
     });
+    // Track for orphan reaping: the shell's cmdline stays `sh -c <cmd>`, so `cmd`
+    // is a safe signature to re-verify against later.
+    recordPreviewPid(server.pid, cmd);
 
     let settled = false;
     let tunnel = null;
@@ -254,6 +354,8 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
       }
     };
     const stop = () => {
+      forgetPreviewPid(server.pid);
+      forgetPreviewPid(tunnel?.pid);
       killGroup(server);
       killGroup(tunnel);
     };
@@ -274,16 +376,13 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
       tunnelStarted = true;
       clearTimeout(bindTimer);
       log?.(`preview: dev server on :${p} — opening the tunnel…`);
-      // --http-host-header localhost: send the origin the Host it expects. Vite
-      // (5+) rejects any Host it doesn't recognize (server.allowedHosts), and the
-      // tunnel's public hostname isn't in that list → "Blocked request". Rewriting
-      // the Host to localhost — what a local browser sends anyway — passes the
-      // check with zero repo config, and is harmless to servers that don't check.
-      tunnel = spawn(
-        cf,
-        ['tunnel', '--url', `http://localhost:${p}`, '--http-host-header', 'localhost'],
-        { detached: true, stdio: ['ignore', 'pipe', 'pipe'] },
-      );
+      // --http-host-header: send the origin the Host it expects (default
+      // localhost — see hostRewrite above). Passes Vite/webpack/Next host checks
+      // with zero repo config; skipped when preview.json sets hostHeader:false.
+      const args = ['tunnel', '--url', `http://localhost:${p}`];
+      if (hostRewrite) args.push('--http-host-header', hostRewrite);
+      tunnel = spawn(cf, args, { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+      recordPreviewPid(tunnel.pid, 'cloudflared'); // signature for orphan reaping
       const onTunnel = (d) => {
         const m = TUNNEL_RE.exec(d.toString());
         if (m) finish({ url: m[0], kind, stop });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.14.0",
+  "version": "0.17.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {