flowviant 0.11.0 → 0.13.0

package/bin/cli.mjs

@@ -57,6 +57,20 @@ if (process.argv[2] === 'update') {
   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
@@ -106,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.11.0';
+export const VERSION = '0.13.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

@@ -175,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

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

@@ -54,6 +54,23 @@ async function registerLiveTarget(intentId, kind, url) {
   }
 }
 
+// The preview's tunnel is going down (replaced by another task's, or the daemon
+// is stopping/restarting) — tell Flowviant to drop the link so it doesn't keep
+// offering a dead URL that 530s. Best-effort + short timeout so teardown is snappy.
+const LIVE_TARGET_CLEAR_URL = FLEET_URL.replace(/\/agents\/?$/, '/live-target-clear');
+function clearLiveTarget(intentId, kind) {
+  return fetch(LIVE_TARGET_CLEAR_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${FLEET_TOKEN}`,
+      'User-Agent': USER_AGENT,
+      'Content-Type': 'application/json',
+    },
+    signal: AbortSignal.timeout(5_000),
+    body: JSON.stringify({ intentId, kind }),
+  }).catch(() => {});
+}
+
 // Safe mode's curated toolset. Bash is scoped to the specific CLIs the agent
 // needs (git/gh/npm/bun) — NOT bare `Bash`, which would auto-approve arbitrary
 // shell (rm -rf, curl|sh, reading ~/.ssh) and defeat the point of safe mode.
@@ -74,8 +91,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 +126,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');
 }
 
@@ -595,6 +615,7 @@ 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
   const stopPreview = () => {
     if (preview) {
       try {
@@ -604,6 +625,11 @@ export async function runLiveWorker({
       }
       preview = null;
     }
+    // Drop the app-side link so it stops offering a now-dead tunnel (530).
+    if (previewTarget) {
+      void clearLiveTarget(previewTarget.intentId, previewTarget.kind);
+      previewTarget = null;
+    }
     // Detached preview children (dev server + tunnel) survive process exit, so
     // the daemon's SIGINT teardown needs a handle to stop them — clear it here
     // once they're down.
@@ -616,14 +642,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,
@@ -635,6 +668,7 @@ export async function runLiveWorker({
     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
       ok(`${label} ${c.dim('live preview ready — open the node to drive it in your review')}`);
     }
   };

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,59 +164,85 @@ 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;
   }
 }
 
 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;
 
 /**
  * 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
  * both the server and the tunnel.
+ *
+ * The tunnel target is the port the server ACTUALLY bound (read from its
+ * output), not the guessed one — vite/vinext/next hop to the next free port when
+ * 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 = 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.
+    // shell. We kill the whole group instead. stdout/stderr piped so we can read
+    // the bound port and surface failures.
     const server = spawn(cmd, {
       cwd: worktree,
       shell: true,
-      detached: true,
-      stdio: ['ignore', 'ignore', 'ignore'],
-    });
-    const tunnel = spawn(cf, ['tunnel', '--url', `http://localhost:${port}`], {
       detached: true,
       stdio: ['ignore', 'pipe', 'pipe'],
+      env,
     });
+
     let settled = false;
+    let tunnel = null;
+    let tunnelStarted = false;
+    let out = '';
+    const tail = () => out.trim().split('\n').slice(-15).join('\n');
     const killGroup = (child) => {
-      if (!child.pid) return;
+      if (!child?.pid) return;
       try {
         process.kill(-child.pid, 'SIGKILL'); // negative pid = the whole group
       } catch {
@@ -168,23 +257,68 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
       killGroup(server);
       killGroup(tunnel);
     };
+    let bindTimer;
+    let timer;
     const finish = (val) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      clearTimeout(bindTimer);
       if (!val) stop();
       resolve(val);
     };
-    const onData = (d) => {
-      const m = TUNNEL_RE.exec(d.toString());
-      if (m) finish({ url: m[0], kind, stop });
+
+    // Open the tunnel once we know the real port (detected or fallback).
+    const openTunnel = (p) => {
+      if (tunnelStarted || settled) return;
+      tunnelStarted = true;
+      clearTimeout(bindTimer);
+      log?.(`preview: dev server on :${p} — opening the tunnel…`);
+      tunnel = spawn(cf, ['tunnel', '--url', `http://localhost:${p}`], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      const onTunnel = (d) => {
+        const m = TUNNEL_RE.exec(d.toString());
+        if (m) finish({ url: m[0], kind, stop });
+      };
+      tunnel.stdout.on('data', onTunnel);
+      tunnel.stderr.on('data', onTunnel);
+      tunnel.on('error', () => finish(null));
+      tunnel.on('close', () => finish(null));
     };
-    tunnel.stdout.on('data', onData);
-    tunnel.stderr.on('data', onData);
-    tunnel.on('error', () => finish(null));
-    tunnel.on('close', () => finish(null));
-    const timer = setTimeout(() => {
-      log?.('preview tunnel did not come up in time — skipping (captured evidence still applies).');
+
+    const onServer = (d) => {
+      const s = d.toString();
+      out = (out + s).slice(-4000);
+      if (!tunnelStarted) {
+        const m = BIND_RE.exec(s);
+        if (m) openTunnel(Number(m[1]));
+      }
+    };
+    server.stdout.on('data', onServer);
+    server.stderr.on('data', onServer);
+    // A dev server that exits before it's reachable (crash on boot, a singleton
+    // lock refusing to start) is the loud failure mode — surface its output.
+    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);
+    });
+
+    // If the server never prints a URL we recognize (quiet server), tunnel to the
+    // configured port as a last resort.
+    bindTimer = setTimeout(() => openTunnel(port), 30_000);
+    timer = setTimeout(() => {
+      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

@@ -110,8 +110,28 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
       }
       return false;
     }
+    // Loop guard: the server can announce a version before it's published. npm is
+    // the source of truth — only install if npm ACTUALLY has something newer than
+    // us, else `npm i -g @latest` reinstalls our own version and we'd re-exec
+    // forever.
+    let published = null;
     try {
-      note(`flowviant ${cur} → ${target}: self-updating…`);
+      published = execFileSync('npm', ['view', 'flowviant', 'version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      /* offline / npm hiccup — treat as "can't confirm", skip this poll */
+    }
+    if (!published || cmpVersion(published, cur) <= 0) {
+      if (naggedFor !== target) {
+        naggedFor = target;
+        note(`update ${target} announced but npm still serves ${published ?? '?'} — waiting for the publish.`);
+      }
+      return false;
+    }
+    try {
+      note(`flowviant ${cur} → ${published}: self-updating…`);
       installLatest();
       ok('updated — restarting into the new version.');
       reexec(teardown);

package/package.json

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