flowviant 0.10.0 → 0.12.0

package/bin/cli.mjs

@@ -4,9 +4,14 @@
  *
  * Three modes, picked by which env var is set:
  *
- *   FLOWVIANT_TOKEN=fva_…   npx flowviant        # 1 worker, current checkout
- *   FLOWVIANT_TOKENS=a,b,c  npx flowviant        # static fleet, 1 worktree each
- *   FLOWVIANT_FLEET=fft_…   npx flowviant        # FLEET DAEMON (recommended)
+ *   FLOWVIANT_TOKEN=fva_…   npx flowviant@latest  # 1 worker, current checkout
+ *   FLOWVIANT_TOKENS=a,b,c  npx flowviant@latest  # static fleet, 1 worktree each
+ *   FLOWVIANT_FLEET=fft_…   npx flowviant@latest  # FLEET DAEMON (recommended)
+ *
+ * Launch with `@latest` so each start pulls the newest published version (bare
+ * `npx flowviant` can reuse a stale cache). A running daemon also self-updates
+ * on its own — at startup and when idle — so it stays current without restarts
+ * (FLOWVIANT_NO_UPDATE=1 makes it nag-only; `flowviant update` updates now).
  *
  * Fleet daemon: install ONCE with a fleet credential, then manage everything
  * from Flowviant. The daemon polls GET /api/v2/fleet/agents, reconciles one
@@ -44,6 +49,28 @@ if (process.argv[2] === 'login') {
   process.exit(0);
 }
 
+// `flowviant update` — install the latest published version now. The daemon also
+// self-updates on its own (at startup + when idle); this is the manual path.
+if (process.argv[2] === 'update') {
+  const { runUpdateCommand } = await import('./lib/update.mjs');
+  runUpdateCommand();
+  process.exit(0);
+}
+
+// `flowviant gh-auth` — sign in the gh CLI (incl. a copy we bundled into
+// ~/.flowviant/bin), so the isolated install doesn't need gh on your global PATH.
+if (process.argv[2] === 'gh-auth') {
+  const { addLocalBinToPath } = await import('./lib/install.mjs');
+  const { execFileSync } = await import('node:child_process');
+  addLocalBinToPath();
+  try {
+    execFileSync('gh', ['auth', 'login'], { stdio: 'inherit' });
+  } catch {
+    console.error('gh not found — run `flowviant` once to install it, or see https://cli.github.com');
+  }
+  process.exit(0);
+}
+
 // `flowviant clean` — reclaim the persistent worktrees (~/.flowviant/worktrees).
 // They're kept across runs so in-flight work survives Ctrl+C; this is the drain.
 // Repos self-heal: the daemon runs `git worktree prune` if a stale registration
@@ -93,7 +120,7 @@ async function main() {
       ? '» safe mode: restricted toolset (unset FLOWVIANT_SAFE for full autonomy).'
       : '» unattended mode: permission prompts skipped so the agent runs hands-off.'
   );
-  preflight({ needGit: tokens.length > 1 });
+  await preflight({ needGit: tokens.length > 1 });
   if (tokens.length === 1) {
     console.log(`» flowviant → ${MCP_URL}  (1 worker · token fva_…${tokens[0].slice(-4)})`);
     await runWorker({ token: tokens[0], cwd: process.cwd(), label: '' });

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.10.0';
+export const VERSION = '0.12.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.
@@ -35,6 +35,11 @@ export const RECONCILE_SECONDS = Number(process.env.RECONCILE_SECONDS || 10);
 // so a long-lived daemon never silently 401s on an expired token.
 export const REFRESH_BEFORE_SECONDS = Number(process.env.REFRESH_BEFORE_SECONDS || 3600);
 export const SAFE = process.env.FLOWVIANT_SAFE === '1';
+// Self-update: a running daemon updates itself to the latest published version
+// (at startup + when idle) and re-execs. On by default; FLOWVIANT_NO_UPDATE=1
+// keeps it nag-only (it still tells you to update, never installs). Below the
+// server's MIN version it updates regardless, since live mode won't work.
+export const AUTO_UPDATE = process.env.FLOWVIANT_NO_UPDATE !== '1';
 // Live mode (DEFAULT since 0.8.0): persistent Agent-SDK session per task —
 // streams into the task channel, injectable mid-task, blocker-parks in place,
 // delivery card on complete, branch preview tunnels. The legacy poll/sentinel

package/bin/lib/fleet.mjs

@@ -22,7 +22,9 @@ import {
   RECONCILE_SECONDS,
   REFRESH_BEFORE_SECONDS,
   LIVE,
+  AUTO_UPDATE,
 } from './config.mjs';
+import { handleVersionSignal } from './update.mjs';
 import {
   git,
   resetWorktree,
@@ -173,7 +175,7 @@ export async function runFleetDaemon() {
   info(`base   · ${baseRef}`);
   info(`server · ${FLEET_URL}`);
   console.log('');
-  preflight({ needGit: true });
+  await preflight({ needGit: true });
 
   // 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
@@ -411,6 +413,20 @@ export async function runFleetDaemon() {
     }
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
+    // Keep the daemon current. Safe = no worker mid-task (true at startup, since
+    // no workers are spawned yet). If it self-updates it re-execs into the new
+    // version and this process becomes a proxy — stop the loop.
+    if (roster.daemon) {
+      const safeToUpdate = [...workers.values()].every((w) => w.state.child == null);
+      const updating = handleVersionSignal({
+        latest: roster.daemon.latest,
+        min: roster.daemon.min,
+        autoUpdate: AUTO_UPDATE,
+        safeToUpdate,
+        teardown,
+      });
+      if (updating) return;
+    }
     processMergeJobs(roster.mergeJobs);
     processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));

package/bin/lib/install.mjs

@@ -0,0 +1,110 @@
+/**
+ * Consent-based prerequisite installers. cloudflared is fetched silently (no
+ * login, isolated), but claude + gh are auth-bearing CLIs you likely manage
+ * yourself — so we DETECT-FIRST and only install on your explicit yes, never
+ * silently and never clobbering an existing install. Interactive login stays
+ * yours (`claude` sign-in, `flowviant gh-auth`).
+ *
+ * gh is dropped into ~/.flowviant/bin (like cloudflared) rather than a system
+ * path, so there's nothing to conflict with; addLocalBinToPath() puts that dir
+ * on PATH so the daemon (and `flowviant gh-auth`) find it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, existsSync, mkdirSync, chmodSync, rmSync, cpSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform, arch } from 'node:os';
+
+export const LOCAL_BIN = join(homedir(), '.flowviant', 'bin');
+
+/** Put ~/.flowviant/bin first on PATH so bundled binaries (gh, cloudflared)
+ *  resolve by bare name for this process and everything it spawns. Idempotent. */
+export function addLocalBinToPath() {
+  const sep = platform() === 'win32' ? ';' : ':';
+  const parts = (process.env.PATH || '').split(sep);
+  if (!parts.includes(LOCAL_BIN)) {
+    process.env.PATH = `${LOCAL_BIN}${sep}${process.env.PATH || ''}`;
+  }
+}
+
+/** TTY-guarded y/N. Non-interactive (no TTY) never auto-installs → returns false
+ *  so a headless/cron run just prints the manual instructions instead. */
+export async function promptYesNo(question, defaultYes) {
+  if (!process.stdin.isTTY) return false;
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((res) =>
+    rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `, res),
+  );
+  rl.close();
+  const a = answer.trim().toLowerCase();
+  if (!a) return defaultYes;
+  return a === 'y' || a === 'yes';
+}
+
+/** Install Claude Code via its official npm package (npm is present — you got
+ *  here through node). Lands on PATH; you still sign in by running `claude`. */
+export function installClaude(log) {
+  try {
+    log?.('installing Claude Code (npm i -g @anthropic-ai/claude-code)…');
+    execFileSync('npm', ['install', '-g', '@anthropic-ai/claude-code'], { stdio: 'inherit' });
+    return true;
+  } catch (e) {
+    log?.(`could not install Claude Code automatically (${e?.message ?? e}). Install: https://claude.com/claude-code`);
+    return false;
+  }
+}
+
+async function latestGhVersion() {
+  const res = await fetch('https://api.github.com/repos/cli/cli/releases/latest', {
+    headers: { 'User-Agent': 'flowviant', Accept: 'application/vnd.github+json' },
+    redirect: 'follow',
+  });
+  if (!res.ok) throw new Error(`gh release lookup failed (http ${res.status})`);
+  const tag = (await res.json())?.tag_name;
+  if (!tag) throw new Error('no gh release tag');
+  return String(tag).replace(/^v/, '');
+}
+
+/** Fetch the gh release archive into ~/.flowviant/bin and extract the binary —
+ *  the cloudflared pattern: isolated, no sudo, nothing to conflict with. Returns
+ *  the binary path or null (falls back to manual instructions). */
+export async function installGh(log) {
+  const os = platform();
+  const a = arch() === 'arm64' ? 'arm64' : 'amd64';
+  const osName = os === 'darwin' ? 'macOS' : os === 'win32' ? 'windows' : 'linux';
+  const ext = os === 'linux' ? 'tar.gz' : 'zip';
+  const binName = os === 'win32' ? 'gh.exe' : 'gh';
+  const dest = join(LOCAL_BIN, binName);
+  let archive;
+  let innerDir;
+  try {
+    mkdirSync(LOCAL_BIN, { recursive: true });
+    const ver = await latestGhVersion();
+    const stem = `gh_${ver}_${osName}_${a}`;
+    const url = `https://github.com/cli/cli/releases/download/v${ver}/${stem}.${ext}`;
+    log?.(`fetching gh ${ver} (${osName}-${a})…`);
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok) throw new Error(`http ${res.status}`);
+    archive = join(LOCAL_BIN, `${stem}.${ext}`);
+    writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
+    // linux ships tar.gz (GNU tar); mac + windows ship zip (bsdtar reads zip).
+    execFileSync('tar', [os === 'linux' ? '-xzf' : '-xf', archive, '-C', LOCAL_BIN], {
+      stdio: 'ignore',
+    });
+    innerDir = join(LOCAL_BIN, stem);
+    const inner = join(innerDir, 'bin', binName);
+    if (!existsSync(inner)) throw new Error('gh binary not found in the archive');
+    cpSync(inner, dest);
+    if (os !== 'win32') chmodSync(dest, 0o755);
+    return dest;
+  } catch (e) {
+    log?.(
+      `could not install gh automatically (${e?.message ?? e}). Install from https://cli.github.com, then run: gh auth login`,
+    );
+    return null;
+  } finally {
+    if (archive) rmSync(archive, { force: true });
+    if (innerDir) rmSync(innerDir, { recursive: true, force: true });
+  }
+}

package/bin/lib/live.mjs

@@ -74,8 +74,11 @@ const SAFE_TOOLS = [
 // rides in the seed message below, so this degrades gracefully if the preset
 // shape shifts between SDK versions.
 const SYSTEM_LIVE = `You are a Flowviant build agent working ONE task inside a live, shared task
-channel. START by stating your approach in plain language (a short plan) BEFORE
-you touch any code — the whole team watches this channel and may redirect you.
+channel. START by stating your approach as a SHORT MARKDOWN LIST — one numbered
+line per step, not a dense paragraph — BEFORE you touch any code; the whole team
+watches this channel and may redirect you. Everything you post here renders as
+Markdown for humans, so write for them: short lists, \`code\` for identifiers and
+paths, **bold** for the key point — never a wall of run-on text.
 A human teammate may message you mid-task; treat any injected "The human
 answered…" or teammate line as a new instruction and adapt. There is NO terminal
 and NO interactive prompt — your only channel to a human is the flowviant MCP
@@ -106,7 +109,7 @@ function seedPrompt(runId, brief, transcript, resumedInPlace) {
       ? [``, `Conversation so far (you may be resuming — pick up where this left off):`, transcript]
       : []),
     ``,
-    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first, then: report_progress as you go; report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
+    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first as a Markdown list (one numbered line per step), then: report_progress as you go; report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
   ].join('\n');
 }
 
@@ -616,14 +619,21 @@ export async function runLiveWorker({
     const entry = kind ? cfg[kind] : null;
     if (!entry || !intentId) {
       // Say WHY there's no preview instead of skipping silently — this was a
-      // real "where's my preview?" support case.
+      // real "where's my preview?" support case. We search the root, common
+      // frontend dirs, and apps/* + packages/*, so if nothing matched either
+      // there's no runnable web app or it needs an explicit config.
       info(
         `${label} ${c.dim(
-          'no live preview: add .flowviant/preview.json ({"ui":{"cmd":"npm run dev","port":5173}}) — the framework could not be inferred from package.json.'
+          'no live preview: no runnable web frontend found (searched the repo root, web/frontend/client/…, and apps/* + packages/*). If your app is elsewhere or not vite/next/astro/etc., add .flowviant/preview.json: {"ui":{"cmd":"cd <dir> && npm install && npm run dev","port":5173}}.'
         )}`
       );
       return;
     }
+    // Zero-config win: when we found the app in a subdir, say where, so it's
+    // clear what's being served (and how to pin it if the guess is wrong).
+    if (cfg.dir && cfg.dir !== '.') {
+      info(`${label} ${c.dim(`live preview: detected a frontend at ${cfg.dir}/ (port ${entry.port})`)}`);
+    }
     info(`${label} ${c.dim('starting a live preview of the branch for review…')}`);
     preview = await startPreview({
       worktree: cwd,

package/bin/lib/preflight.mjs

@@ -6,6 +6,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { ok, warn, info, c } from './ui.mjs';
+import { addLocalBinToPath, promptYesNo, installClaude, installGh } from './install.mjs';
 
 function present(cmd) {
   try {
@@ -25,21 +26,48 @@ function ghAuthed() {
   }
 }
 
-/** Prints a checklist. Returns false only if a *fatal* prereq (claude, or git
- *  when worktrees are used) is missing — callers may warn-and-continue. */
-export function preflight({ needGit = true } = {}) {
-  const claude = present('claude');
-  const gh = present('gh');
+/** Prints a checklist and, when a missing prereq is auto-installable, OFFERS to
+ *  install it (consent-based, never silent). Returns false only if a *fatal*
+ *  prereq (claude, or git when worktrees are used) is still missing after. */
+export async function preflight({ needGit = true } = {}) {
+  addLocalBinToPath(); // find a gh/cloudflared we bundled on a previous run
+  let claude = present('claude');
+  let gh = present('gh');
   const node18 = Number(process.versions.node.split('.')[0]) >= 18;
   const git = needGit ? present('git') : true;
 
   info('checking your setup (this tool drives these — it never sees their logins):');
-  claude
-    ? ok(`claude installed ${c.dim('· must be signed in — run `claude` once if you haven’t')}`)
-    : warn('claude NOT found — install Claude Code: https://claude.com/claude-code');
-  gh && ghAuthed()
-    ? ok('gh authenticated')
-    : warn(gh ? 'gh not signed in — run: gh auth login' : 'gh NOT found — install it + run: gh auth login (needed to open PRs)');
+
+  // claude — fatal. Offer the official npm install (no-default: it's bigger and
+  // account-coupled, so we don't push it).
+  if (claude) {
+    ok(`claude installed ${c.dim('· must be signed in — run `claude` once if you haven’t')}`);
+  } else {
+    warn('claude NOT found — Claude Code is required.');
+    if (await promptYesNo('Install Claude Code now?', false)) {
+      if (installClaude((m) => info(m))) claude = present('claude');
+    }
+    claude
+      ? ok('claude installed — run `claude` once to sign in')
+      : warn('install Claude Code manually: https://claude.com/claude-code');
+  }
+
+  // gh — needed to open PRs. Offer to fetch the isolated binary (yes-default:
+  // low-risk, no login carried by the install itself).
+  if (gh && ghAuthed()) {
+    ok('gh authenticated');
+  } else if (gh) {
+    warn('gh not signed in — run: gh auth login');
+  } else {
+    warn('gh NOT found — needed to open PRs.');
+    if (await promptYesNo('Install GitHub CLI (gh) now?', true)) {
+      if (await installGh((m) => info(m))) gh = present('gh');
+    }
+    gh
+      ? ok('gh installed to ~/.flowviant/bin — authenticate with: flowviant gh-auth')
+      : warn('install gh manually: https://cli.github.com, then run: gh auth login');
+  }
+
   if (needGit) (git ? ok('git installed') : warn('git NOT found — install git'));
   node18 ? ok(`node ${process.versions.node}`) : warn(`node ${process.versions.node} — need 18+`);
   console.log('');

package/bin/lib/preview.mjs

@@ -17,7 +17,7 @@
  */
 
 import { spawn, execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
 
@@ -45,17 +45,37 @@ const FRAMEWORK_PORTS = [
   { re: /\bsvelte/, port: 5173 },
   { re: /\bgatsby\b/, port: 8000 },
   { re: /\bexpo\b/, port: 8081 },
+  { re: /@angular\/|\bng serve\b/, port: 4200 },
+  { re: /vue-cli-service/, port: 8080 },
 ];
 
-function pkgManager(repoRoot) {
-  if (existsSync(join(repoRoot, 'bun.lock')) || existsSync(join(repoRoot, 'bun.lockb'))) return 'bun';
-  if (existsSync(join(repoRoot, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (existsSync(join(repoRoot, 'yarn.lock'))) return 'yarn';
+// A repo whose ROOT is a library/monorepo often keeps its web app in a subdir,
+// so the root package.json has no dev server at all. Search these (plus every
+// child of apps/ and packages/) so a nested frontend previews with ZERO config.
+const SUBDIR_CANDIDATES = [
+  'web', 'webapp', 'frontend', 'client', 'ui', 'site', 'www', 'app', 'dashboard',
+];
+const SUBDIR_PARENTS = ['apps', 'packages'];
+
+function pkgManager(dir) {
+  if (existsSync(join(dir, 'bun.lock')) || existsSync(join(dir, 'bun.lockb'))) return 'bun';
+  if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(dir, 'yarn.lock'))) return 'yarn';
   return 'npm';
 }
 
-function inferPreviewConfig(repoRoot) {
-  const pkgPath = join(repoRoot, 'package.json');
+// An explicit port baked into the dev script (PORT=3005 …, -p 3005, --port 3005,
+// --port=3005) overrides the framework default — otherwise the tunnel would
+// target the wrong port and never connect.
+function portFromScript(s) {
+  const m = String(s).match(/(?:PORT=|(?:^|\s)-p[=\s]+|--port[=\s]+)(\d{2,5})\b/);
+  return m ? Number(m[1]) : null;
+}
+
+// Infer {script, port} from one directory's package.json, or null if it has no
+// dev/start script or no framework we can map to a port.
+function inferFromDir(absDir) {
+  const pkgPath = join(absDir, 'package.json');
   if (!existsSync(pkgPath)) return null;
   let pkg;
   try {
@@ -70,15 +90,58 @@ function inferPreviewConfig(repoRoot) {
   const hay = `${scripts[script]} ${Object.keys(deps).join(' ')}`.toLowerCase();
   const fw = FRAMEWORK_PORTS.find((f) => f.re.test(hay));
   if (!fw) return null; // can't safely guess the port
-  const pm = pkgManager(repoRoot);
+  return { script, port: portFromScript(scripts[script]) ?? fw.port };
+}
+
+// The ordered dirs to probe: root, then the common frontend names, then every
+// child of apps/ and packages/. Relative to repoRoot ('' = root).
+function candidateDirs(repoRoot) {
+  const dirs = ['', ...SUBDIR_CANDIDATES];
+  for (const parent of SUBDIR_PARENTS) {
+    const p = join(repoRoot, parent);
+    try {
+      for (const e of readdirSync(p, { withFileTypes: true })) {
+        if (e.isDirectory()) dirs.push(`${parent}/${e.name}`);
+      }
+    } catch {
+      /* no such parent dir */
+    }
+  }
+  return dirs;
+}
+
+function buildConfig(repoRoot, rel, hit) {
+  // Prefer the app dir's own package manager if it has a lockfile, else the repo
+  // root's (monorepos install from the root).
+  const abs = rel ? join(repoRoot, rel) : repoRoot;
+  const hasOwnLock = ['bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json'].some(
+    (f) => existsSync(join(abs, f)),
+  );
+  const pm = pkgManager(hasOwnLock ? abs : repoRoot);
   const install = pm === 'npm' ? 'npm install' : `${pm} install`;
-  const run = pm === 'yarn' ? `yarn ${script}` : `${pm} run ${script}`;
-  return { ui: { cmd: `${install} && ${run}`, port: fw.port } };
+  const run = pm === 'yarn' ? `yarn ${hit.script}` : `${pm} run ${hit.script}`;
+  const inner = `${install} && ${run}`;
+  // Subdir apps run from their own folder (shell:true honors the cd prefix).
+  const cmd = rel ? `cd ${rel} && ${inner}` : inner;
+  return { ui: { cmd, port: hit.port }, dir: rel || '.' };
+}
+
+// Infer a preview config by probing the root and likely frontend subdirs.
+function inferPreviewConfig(repoRoot) {
+  for (const rel of candidateDirs(repoRoot)) {
+    const hit = inferFromDir(rel ? join(repoRoot, rel) : repoRoot);
+    if (hit) return buildConfig(repoRoot, rel, hit);
+  }
+  return null;
 }
 
-/** The preview config for a repo — explicit file wins, else inferred. */
+/** The preview config for a repo — explicit file wins, else inferred from the
+ *  root or a nested frontend. Carries `dir` (relative) so callers can say where
+ *  it found the app. */
 export function loadPreviewConfig(repoRoot) {
-  return readPreviewConfig(repoRoot) ?? inferPreviewConfig(repoRoot);
+  const explicit = readPreviewConfig(repoRoot);
+  if (explicit) return explicit;
+  return inferPreviewConfig(repoRoot);
 }
 
 // ── cloudflared: use if installed, else auto-fetch ─────────────────────────
@@ -101,27 +164,38 @@ async function ensureCloudflared(log) {
   const dir = join(homedir(), '.flowviant', 'bin');
   const bin = join(dir, os === 'win32' ? 'cloudflared.exe' : 'cloudflared');
   if (existsSync(bin)) return bin;
-  // Raw single-file binaries exist for linux + windows; macOS ships a tarball,
-  // so point mac users at brew instead of unpacking here.
-  if (os === 'darwin') {
-    log?.('cloudflared not found — install it (`brew install cloudflared`) to enable live previews.');
-    return null;
-  }
-  const osName = os === 'win32' ? 'windows' : 'linux';
   const a = arch() === 'arm64' ? 'arm64' : 'amd64';
-  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-${osName}-${a}${
-    os === 'win32' ? '.exe' : ''
-  }`;
-  log?.(`fetching cloudflared (${osName}-${a}) to enable live previews…`);
   try {
+    mkdirSync(dir, { recursive: true });
+    if (os === 'darwin') {
+      // macOS ships a .tgz (not a raw binary) — download it and extract the
+      // single `cloudflared` executable with the system tar (always on macOS).
+      const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-${a}.tgz`;
+      log?.(`fetching cloudflared (darwin-${a}) to enable live previews…`);
+      const res = await fetch(url, { redirect: 'follow' });
+      if (!res.ok) throw new Error(`http ${res.status}`);
+      const tgz = join(dir, 'cloudflared.tgz');
+      writeFileSync(tgz, Buffer.from(await res.arrayBuffer()));
+      execFileSync('tar', ['-xzf', tgz, '-C', dir], { stdio: 'ignore' });
+      rmSync(tgz, { force: true });
+      if (!existsSync(bin)) throw new Error('archive did not contain cloudflared');
+      chmodSync(bin, 0o755);
+      return bin;
+    }
+    // linux + windows ship a raw single-file binary.
+    const osName = os === 'win32' ? 'windows' : 'linux';
+    const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-${osName}-${a}${
+      os === 'win32' ? '.exe' : ''
+    }`;
+    log?.(`fetching cloudflared (${osName}-${a}) to enable live previews…`);
     const res = await fetch(url, { redirect: 'follow' });
     if (!res.ok) throw new Error(`http ${res.status}`);
-    mkdirSync(dir, { recursive: true });
     writeFileSync(bin, Buffer.from(await res.arrayBuffer()));
     if (os !== 'win32') chmodSync(bin, 0o755);
     return bin;
   } catch (e) {
-    log?.(`could not fetch cloudflared (${e.message}) — install it manually to enable live previews.`);
+    const hint = os === 'darwin' ? ' (or `brew install cloudflared`)' : '';
+    log?.(`could not fetch cloudflared (${e.message}) — install it manually${hint} to enable live previews.`);
     return null;
   }
 }
@@ -133,20 +207,38 @@ const TUNNEL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
  * once the tunnel URL is captured, or null if it can't come up. stop() kills
  * both the server and the tunnel.
  */
-export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs = 90_000 }) {
+export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs = 180_000 }) {
   const cf = await ensureCloudflared(log);
   if (!cf) return null; // fall back to captured evidence
   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' };
     // 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, keep port bound, and get silently re-fronted by the NEXT task's
     // tunnel (reviewer sees the wrong branch). We kill the whole group instead.
+    // stdout/stderr are piped (not ignored) so we can show WHY a preview didn't
+    // come up — a swallowed "another dev server is already running" was a real
+    // dead-end.
     const server = spawn(cmd, {
       cwd: worktree,
       shell: true,
       detached: true,
-      stdio: ['ignore', 'ignore', 'ignore'],
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
     });
+    // Ring buffer of the dev server's recent output, surfaced on failure.
+    let out = '';
+    const capture = (d) => {
+      out = (out + d.toString()).slice(-4000);
+    };
+    server.stdout.on('data', capture);
+    server.stderr.on('data', capture);
+    const tail = () => out.trim().split('\n').slice(-15).join('\n');
     const tunnel = spawn(cf, ['tunnel', '--url', `http://localhost:${port}`], {
       detached: true,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -183,8 +275,24 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
     tunnel.stderr.on('data', onData);
     tunnel.on('error', () => finish(null));
     tunnel.on('close', () => finish(null));
+    // The dev server exiting BEFORE the tunnel came up is the loud failure mode
+    // (crash on boot, or a singleton lock refusing to start) — surface its
+    // output instead of a silent timeout.
+    server.on('exit', (code) => {
+      if (settled) return;
+      log?.(
+        `preview dev server exited (code ${code}) before it was reachable — no preview.${
+          tail() ? `\n  dev server said:\n${tail()}` : ''
+        }`,
+      );
+      finish(null);
+    });
     const timer = setTimeout(() => {
-      log?.('preview tunnel did not come up in time — skipping (captured evidence still applies).');
+      log?.(
+        `preview tunnel did not come up in ${Math.round(timeoutMs / 1000)}s — skipping.${
+          tail() ? `\n  last dev-server output:\n${tail()}` : ''
+        }`,
+      );
       finish(null);
     }, timeoutMs);
   });

package/bin/lib/update.mjs

@@ -0,0 +1,137 @@
+/**
+ * Self-update — keep a long-running daemon current without babysitting it.
+ *
+ * A daemon runs for hours/days from one launch, so "latest at launch" (even with
+ * `npx flowviant@latest`) doesn't help a process that's already up when a new
+ * version ships. The server reports {latest, min} on every roster poll; the
+ * daemon compares its own VERSION and, at a SAFE boundary (startup or idle —
+ * never mid-task), self-updates + re-execs. Below `min` it updates regardless
+ * (older protocol is known-broken); otherwise it honors AUTO_UPDATE. When it
+ * can't install (npx cache, or auto off) it nags with the exact command.
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from './config.mjs';
+import { note, ok, warn } from './ui.mjs';
+
+/** Compare x.y.z version strings → -1 | 0 | 1 (missing parts read as 0). */
+export function cmpVersion(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * npx runs from a per-invocation cache dir. `npm i -g` would install to a
+ * DIFFERENT location than the one executing, so re-execing our own path would
+ * loop on the stale cached copy. Detect npx and skip the install (nag instead —
+ * relaunching with `npx flowviant@latest` is the npx-native update).
+ */
+export function runningViaNpx() {
+  const ua = process.env.npm_config_user_agent || '';
+  const argv1 = process.argv[1] || '';
+  let self = '';
+  try {
+    self = fileURLToPath(import.meta.url);
+  } catch {
+    /* non-file URL — ignore */
+  }
+  return /\bnpx\b/.test(ua) || /[\\/]_npx[\\/]/.test(argv1) || /[\\/]_npx[\\/]/.test(self);
+}
+
+/**
+ * Replace this process with a fresh one running the just-installed version.
+ * `npm i -g` overwrote the global package in place, so re-running argv[1] loads
+ * the NEW code. We tear down first (idle-gated, so nothing's mid-task) and keep
+ * this process alive only as a thin proxy waiting on the child, so the user's
+ * shell stays attached to one foreground process.
+ */
+function reexec(teardown) {
+  try {
+    teardown?.();
+  } catch {
+    /* best-effort */
+  }
+  const child = spawn(process.execPath, process.argv.slice(1), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+/** Install @latest globally. Throws on failure (EACCES without sudo, offline…). */
+function installLatest() {
+  execFileSync('npm', ['install', '-g', 'flowviant@latest'], { stdio: 'inherit' });
+}
+
+/** `flowviant update` — explicit, manual update. Does not re-exec into a daemon
+ *  (the user ran a one-shot command); it installs and tells them to relaunch. */
+export function runUpdateCommand() {
+  if (runningViaNpx()) {
+    note('running via npx — just relaunch with `npx flowviant@latest` to get the newest.');
+    return;
+  }
+  try {
+    note(`updating flowviant (currently ${VERSION})…`);
+    installLatest();
+    ok('updated. Relaunch `flowviant` to run the new version.');
+  } catch (e) {
+    warn(`update failed (${e?.message ?? e}). Try: npm i -g flowviant@latest`);
+  }
+}
+
+// Nag at most once per target version, so a poll every ~10s doesn't spam.
+let naggedFor = null;
+
+/**
+ * React to the server's {latest, min} signal from a roster poll.
+ * @returns true if it kicked off a self-update + re-exec (caller must stop).
+ */
+export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, teardown }) {
+  const cur = VERSION;
+  const belowMin = min && cmpVersion(cur, min) < 0;
+  const belowLatest = latest && cmpVersion(cur, latest) < 0;
+  if (!belowMin && !belowLatest) return false; // current — nothing to do
+  const target = latest || min;
+  const npx = runningViaNpx();
+  const wantInstall = belowMin || autoUpdate;
+
+  if (wantInstall && !npx) {
+    if (!safeToUpdate) {
+      // Outdated but an agent is mid-task — wait for idle. Nag once meanwhile.
+      if (naggedFor !== target) {
+        naggedFor = target;
+        note(`flowviant ${cur} → ${target} available — self-updating once agents go idle.`);
+      }
+      return false;
+    }
+    try {
+      note(`flowviant ${cur} → ${target}: self-updating…`);
+      installLatest();
+      ok('updated — restarting into the new version.');
+      reexec(teardown);
+      return true;
+    } catch (e) {
+      warn(`self-update failed (${e?.message ?? e}) — update manually: npm i -g flowviant@latest`);
+      naggedFor = target; // don't retry-spam a failing install every poll
+      return false;
+    }
+  }
+
+  // Can't or won't auto-install → nag once per target version.
+  if (naggedFor !== target) {
+    naggedFor = target;
+    const how = npx ? 'relaunch with `npx flowviant@latest`' : 'run `npm i -g flowviant@latest`';
+    if (belowMin) {
+      warn(`flowviant ${cur} is below the minimum ${min} — live mode may not work. Update: ${how}.`);
+    } else {
+      note(`flowviant ${cur} → ${latest} available. Update: ${how}.`);
+    }
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.10.0",
+  "version": "0.12.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": {