flowviant 0.9.1 → 0.11.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,14 @@ 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 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

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.9.1';
+export const VERSION = '0.11.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,
@@ -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/live.mjs

@@ -255,6 +255,52 @@ async function waitForMessage(mcpUrl, token, runId, afterId, isAlive) {
 
 // One task: claim → seed → stream/mirror/inject/park → complete. Returns
 // { outcome: 'nothing' | 'done' | 'blocked' | 'stalled' | 'error' }.
+// Distinguish "YOUR OWN Claude account is out of quota" (the user must wait or
+// hand off — a park) from a transient Anthropic-side hiccup (retry soon — a
+// plain error). Only the former parks. resetAt is lifted from the limit
+// response's retry headers when present, so the thread can say when it's back.
+export function classifyRateLimit(e) {
+  const status = e?.status ?? e?.statusCode ?? e?.response?.status;
+  const msg = String(e?.message ?? e ?? '').toLowerCase();
+  const overloaded = status === 529 || msg.includes('overloaded');
+  const isRateLimit =
+    !overloaded &&
+    (status === 429 ||
+      /rate.?limit|usage limit|quota|too many requests|exceeded your|reached your|limit reached/.test(
+        msg,
+      ));
+  if (!isRateLimit) return { isRateLimit: false };
+  let resetAt;
+  const hdrs = e?.headers ?? e?.response?.headers;
+  const get = (k) => hdrs?.get?.(k) ?? hdrs?.[k];
+  const retryAfter = Number(get?.('retry-after'));
+  const resetHdr = get?.('anthropic-ratelimit-unified-reset');
+  if (Number.isFinite(retryAfter) && retryAfter > 0) {
+    resetAt = new Date(Date.now() + retryAfter * 1000).toISOString();
+  } else if (resetHdr != null) {
+    const epoch = Number(resetHdr);
+    if (Number.isFinite(epoch) && epoch > 0) resetAt = new Date(epoch * 1000).toISOString();
+    else if (!Number.isNaN(Date.parse(resetHdr))) resetAt = new Date(resetHdr).toISOString();
+  }
+  return { isRateLimit: true, resetAt };
+}
+
+// Wait out a Claude-account limit, heartbeating so the 30-min lease stays warm
+// and the task isn't reclaimed while paused. Caps the wait so an unknown or very
+// distant reset still retries eventually (and re-parks if still limited).
+async function parkUntilReset(resetAt, { mcpUrl, getToken, runId, isAlive }) {
+  const MAX_PARK_MS = 60 * 60 * 1000; // never sit longer than an hour before retrying
+  const DEFAULT_PARK_MS = 15 * 60 * 1000; // no reset given → try again in 15 min
+  const now = Date.now();
+  const target = resetAt ? Date.parse(resetAt) : now + DEFAULT_PARK_MS;
+  const until = Math.min(Number.isFinite(target) ? target : now + DEFAULT_PARK_MS, now + MAX_PARK_MS);
+  while (isAlive() && Date.now() < until) {
+    const token = getToken();
+    if (token) await mcpCall(mcpUrl, token, 'heartbeat', { runId }).catch(() => {});
+    await sleep(IDLE_SECONDS);
+  }
+}
+
 export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resumeIntentId, onChild }) {
   const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
   if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
@@ -493,6 +539,14 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
     }
     return { outcome: completed ? 'done' : 'stalled', title, intentId };
   } catch (e) {
+    const rl = classifyRateLimit(e);
+    if (rl.isRateLimit) {
+      // The user's OWN Claude account is tapped. Park the run so the thread shows
+      // it as their plan's limit (not a Flowviant error) and the lease stays warm
+      // for a resume in place — never reset this worktree's work.
+      await mcpCall(mcpUrl, token, 'report_paused', { runId, resetAt: rl.resetAt }).catch(() => {});
+      return { outcome: 'rate_limited', resetAt: rl.resetAt, runId, title, intentId };
+    }
     return { outcome: 'error', error: e?.message ?? String(e), title, intentId };
   } finally {
     onChild?.(null); // no longer busy — token may rotate between tasks
@@ -617,7 +671,10 @@ export async function runLiveWorker({
     // stalled / errored → same worktree resumes). Finishing or finding no work
     // clears it so the next fresh task starts from a clean base.
     lastIntentId =
-      res.outcome === 'parked' || res.outcome === 'stalled' || res.outcome === 'error'
+      res.outcome === 'parked' ||
+      res.outcome === 'stalled' ||
+      res.outcome === 'error' ||
+      res.outcome === 'rate_limited'
         ? res.intentId
         : null;
     if (res.outcome === 'nothing') {
@@ -651,6 +708,25 @@ export async function runLiveWorker({
       // on reconnect. Nothing to do but stop cleanly.
       break;
     }
+    if (res.outcome === 'rate_limited') {
+      // The agent's OWN Claude account hit its limit — not a Flowviant failure.
+      // Hold the worktree + lease and wait it out (heartbeating so it isn't
+      // reclaimed), then resume the SAME task in place. Never reset the worktree.
+      const when = res.resetAt ? ` until ~${new Date(res.resetAt).toLocaleTimeString()}` : '';
+      enter(
+        'paused',
+        warn,
+        `${c.yellow('paused')} ${c.dim(`— your Claude account hit its usage limit; holding your work${when}`)}`,
+      );
+      await parkUntilReset(res.resetAt, {
+        mcpUrl: getMcpUrl() ?? MCP_URL,
+        getToken: () => getToken(agentId),
+        runId: res.runId,
+        isAlive,
+      });
+      phase = '';
+      continue;
+    }
     // stalled / error — usually a stale token or a stuck turn. Refresh + retry.
     enter('reconnect', warn, `${c.yellow(res.outcome)} ${c.dim('— refreshing token, retrying')}`);
     onTokenSuspect?.(agentId);

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.9.1",
+  "version": "0.11.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": {