flowviant 0.33.0 → 0.34.2

package/bin/cli.mjs

@@ -42,11 +42,37 @@ import { runWorker, runStaticFleet } from './lib/single.mjs';
 import { runLogin } from './lib/login.mjs';
 import { preflight } from './lib/preflight.mjs';
 
-// `flowviant login` — device auth (recommended): approve a code in the
-// app, the credential is stored locally, then plain `flowviant` just runs.
+// `flowviant login` — device auth (recommended): approve a code in the app, the
+// credential is stored locally, and then we KEEP GOING into the daemon.
+//
+// It used to print "Now just run: npx flowviant" and exit. Everything about that
+// was technically correct and practically a dead end: the line scrolled past in
+// a terminal the user had already stopped reading (they were in the browser,
+// typing a code), and the app told them their machine would "come online
+// shortly" — which it never did, because nothing was running. The product
+// promise is install once; a second command you have to notice is not that.
+//
+// `--no-start` for scripts and CI, which want the credential and not a
+// long-running process.
 if (process.argv[2] === 'login') {
-  await runLogin();
-  process.exit(0);
+  const noStart = process.argv.includes('--no-start');
+  await runLogin({ thenStart: !noStart });
+  if (noStart) process.exit(0);
+  // Re-exec as a plain `flowviant` rather than falling through. config.mjs reads
+  // the credential at IMPORT time — which was before the login we just did — so
+  // this process still has an empty FLEET_TOKEN and would exit with "no
+  // credential found" seconds after saving one. Same shape as the self-update
+  // re-exec: stay alive as a thin proxy so the user's shell keeps one foreground
+  // process.
+  const { spawn } = await import('node:child_process');
+  const child = spawn(process.execPath, [process.argv[1]], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  // AWAIT it. Registering an exit handler and falling through would run the rest
+  // of this file in the parent — which has no credential — and print "no
+  // credential found" over the daemon that just started in the child.
+  process.exit(await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0))));
 }
 
 // `flowviant update` — install the latest published version now. The daemon also

package/bin/lib/config.mjs

@@ -3,7 +3,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { homedir, cpus } from 'node:os';
 
 // Read the daemon's version from its OWN package.json (always shipped in the npm
 // tarball) — never hardcode it. The hardcoded constant drifted: it sat at
@@ -58,6 +58,32 @@ export const STREAM_URL =
   process.env.FLOWVIANT_STREAM_URL ||
   FLEET_URL.replace(/\/agents(\/?)$/, '/stream$1').replace(/^http/, 'ws');
 export const POLL_SECONDS = Number(process.env.POLL_SECONDS || 20);
+
+/**
+ * How many tasks THIS MACHINE will build at once.
+ *
+ * The limit belongs here, not on the server: a task in flight is a Claude Code
+ * session plus its own git worktree plus whatever the project's dev server and
+ * tests want, and this process is the only party that can see the cores, the
+ * RAM and the fan. The server used to decide it, indirectly, by how many lanes
+ * a user had pre-sized with a dial — which asked them to answer a question
+ * about their laptop in a web app, before they knew what they were going to
+ * dispatch.
+ *
+ * Sent to the server on every roster poll so it can grow lanes to meet waiting
+ * work UNDER this ceiling, and enforced locally besides — the roster can carry
+ * more lanes than this (someone added capacity by hand, or a second machine
+ * shares the fleet), and a ceiling that only exists as a request is not one.
+ *
+ * Half the cores, floor 1, cap 4. Half because a build agent is not the only
+ * thing running — the user is working on this machine too — and 4 because past
+ * that the shared Claude account, not the CPU, is what runs out.
+ */
+export const MAX_CONCURRENT = (() => {
+  const asked = Number(process.env.FLOWVIANT_MAX_CONCURRENT);
+  if (Number.isFinite(asked) && asked >= 1) return Math.min(Math.floor(asked), 32);
+  return Math.max(1, Math.min(4, Math.floor((cpus().length || 2) / 2)));
+})();
 export const IDLE_SECONDS = Number(process.env.IDLE_SECONDS || 30);
 // Live mode: after this long idle-parked on a blocker, tear the session down to
 // free the Claude process (the intent stays claimed; it resumes when answered).

package/bin/lib/fleet.mjs

@@ -18,6 +18,7 @@ import {
   MCP_URL,
   SAFE,
   POLL_SECONDS,
+  MAX_CONCURRENT,
   IDLE_SECONDS,
   RECONCILE_SECONDS,
   REFRESH_BEFORE_SECONDS,
@@ -76,6 +77,11 @@ import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
+  // What this machine will run at once. The server grows lanes to meet waiting
+  // work beneath this, instead of the user pre-sizing a pool by hand — only the
+  // machine knows its cores, its RAM and whose Claude quota is being spent.
+  // Older servers ignore the param, so sending it is always safe.
+  url.searchParams.set('capacity', String(MAX_CONCURRENT));
   // Env-sync identity + materialized version (the Settings "env vN" chip).
   try {
     for (const [k, v] of Object.entries(await envQueryParams())) {
@@ -1170,6 +1176,7 @@ export async function runFleetDaemon() {
   let connected = false; // log the first successful poll once
   let rosterSig = null; // last roster membership, to log changes only
   let idleBeatAt = 0; // throttle the "still alive" idle heartbeat
+  let cappedWarned = false; // say once, not every reconcile, why extra lanes idle
   let joinCount = 0; // for stable per-agent label colours
 
   // ── Push channel: a server wake short-circuits the reconcile sleep so a job is
@@ -1296,6 +1303,23 @@ export async function runFleetDaemon() {
       }
       hasWorkByAgent.set(a.agentId, !!a.hasWork);
       if (!workers.has(a.agentId)) {
+        // Local ceiling, enforced and not merely requested. The roster can carry
+        // more lanes than this machine asked for — someone added capacity by
+        // hand, or a second machine shares the fleet — and each extra worker is
+        // another Claude session, another worktree and another dev server on
+        // somebody's laptop. Skipping the spawn does NOT strand the work: an
+        // @mention addresses the FLEET, so any running lane can claim it; the
+        // tasks queue behind the ones we did start.
+        if (workers.size >= MAX_CONCURRENT) {
+          if (!cappedWarned) {
+            cappedWarned = true;
+            info(
+              `running ${MAX_CONCURRENT} task${MAX_CONCURRENT === 1 ? '' : 's'} at a time on this machine — ` +
+                `more will queue (FLOWVIANT_MAX_CONCURRENT to change)`
+            );
+          }
+          continue;
+        }
         const wt = join(baseDir, `agent-${a.agentId}`);
         try {
           if (!existsSync(wt)) {

package/bin/lib/live.mjs

@@ -138,10 +138,15 @@ This IS your handover, so make it tangible; match the evidence to what you built
 • UI / any visible screen → attach a real SCREENSHOT. Start the app's dev server
   in your worktree, then capture it headlessly with
   \`flowviant shot http://localhost:<PORT>/<route> --out shot.png\` (it finds a
-  browser for you and never needs a display), and attach_evidence with kind
-  "screenshot" and the file's base64 (\`base64 -w0 shot.png\`). Shoot EVERY key
-  screen you changed. If \`flowviant shot\` reports that no browser is available,
-  do NOT block — fall back to the text evidence below.
+  browser for you and never needs a display). THEN READ shot.png BACK AND LOOK
+  AT IT before you attach — you can see images, and this is the only moment
+  anyone checks the thing you are about to call proof. A blank page, a 404, an
+  error overlay, a collapsed layout and the screen you meant all look identical
+  as a file path. If it is wrong, fix the code and shoot again; if it is right,
+  attach_evidence with kind "screenshot" and the file's base64
+  (\`base64 -w0 shot.png\`). Shoot EVERY key screen you changed. If
+  \`flowviant shot\` reports that no browser is available, do NOT block — fall
+  back to the text evidence below.
 • backend / API work → a request/response capture or a data sample showing the
   write (kind "request_response" or "sample").
 • a multi-step FLOW (login, signup, checkout): one screenshot does NOT prove it

package/bin/lib/login.mjs

@@ -45,7 +45,7 @@ async function post(url, body) {
   return j.data ?? j;
 }
 
-export async function runLogin() {
+export async function runLogin({ thenStart = false } = {}) {
   console.log(`\n  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`login · v${VERSION}`)}\n`);
   let start;
   try {
@@ -72,7 +72,14 @@ export async function runLogin() {
     if (poll.status === 'approved') {
       store({ fleetToken: poll.fleetToken, projectId: poll.projectId, mcpUrl: poll.mcpUrl });
       ok('connected — credential saved to ~/.flowviant/credentials.json');
-      console.log(`\n  Now just run:  ${c.bold('npx flowviant')}\n`);
+      // The daemon starts right here unless the caller opted out; telling
+      // someone to run a second command was the step that got missed, since by
+      // this point they are looking at the browser, not this terminal.
+      console.log(
+        thenStart
+          ? `\n  ${c.dim('starting your agent — leave this running')}\n`
+          : `\n  Now run:  ${c.bold('npx flowviant')}\n`
+      );
       return;
     }
     if (poll.status === 'expired') {

package/bin/lib/preview.mjs

@@ -28,6 +28,7 @@
  */
 
 import { spawn, execFileSync } from 'node:child_process';
+import { createServer } from 'node:net';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
@@ -216,6 +217,33 @@ 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;
 
+/**
+ * A port nobody is on right now — bind :0, read what the kernel handed us, let
+ * it go. Inherently a RACE (someone could take it in the gap), which is fine:
+ * this is a hint passed as $PORT, and the tunnel still aims at whatever the
+ * server ACTUALLY announces. Worst case we lose the hint and land back on
+ * today's behaviour.
+ *
+ * Why this exists: previews only survived concurrency by luck. vite/next hop to
+ * the next free port when theirs is taken, so two tasks in one repo happened to
+ * work. Anything that binds a FIXED port and exits on EADDRINUSE — the `api`
+ * preview kind, an explicit `port` in preview.json, a plain app.listen(3000) —
+ * had its second preview die outright, reported as "dev server exited before it
+ * was reachable" with the real cause buried in the tail. That's not an edge
+ * case on a machine running up to MAX_CONCURRENT tasks, and it stops being one
+ * at all once the box is shared.
+ */
+async function freePort() {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.once('error', () => resolve(null)); // no port to be had — fall through
+    srv.listen(0, '127.0.0.1', () => {
+      const p = srv.address()?.port ?? null;
+      srv.close(() => resolve(p));
+    });
+  });
+}
+
 // ── 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,
@@ -307,6 +335,10 @@ export async function startPreview({
 }) {
   const cf = await ensureCloudflared(log);
   if (!cf) return null; // fall back to captured evidence
+  // Ask for a port nobody's on, and TELL the dev server about it (below) rather
+  // than hoping its framework hops. Null if we couldn't get one — everything
+  // downstream then behaves exactly as before.
+  const bindPort = await freePort();
   // 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
@@ -320,10 +352,18 @@ export async function startPreview({
     // a reused/uncleaned worktree still previews. Harmless to tools that ignore
     // these vars; BROWSER=none stops any auto-open. A repo's preview.json `env`
     // is layered last, so it can override any of these.
+    // PORT is a HINT, deliberately: honoured by Next, Remix, Nuxt, CRA and any
+    // conventional `app.listen(process.env.PORT)`, ignored by Vite (which uses
+    // server.port and hops on its own) and overridden by an explicit --port in
+    // the dev script. All three outcomes are fine — the tunnel aims at the port
+    // the server ANNOUNCES, not at what we asked for, so a disregarded hint
+    // costs nothing and an honoured one is what makes two concurrent previews
+    // of one repo possible. Placed BEFORE extraEnv so preview.json still wins.
     const env = {
       ...process.env,
       VINEXT_NO_DEV_LOCK: '1',
       BROWSER: 'none',
+      ...(bindPort ? { PORT: String(bindPort) } : null),
       ...(extraEnv && typeof extraEnv === 'object' ? extraEnv : {}),
     };
     // detached so each gets its own process group — `bun run dev` via a shell
@@ -444,9 +484,11 @@ export async function startPreview({
       finish(null);
     });
 
-    // If the server never prints a URL we recognize (quiet server), tunnel to the
-    // configured port as a last resort.
-    bindTimer = setTimeout(() => void openTunnel(port), 30_000);
+    // If the server never prints a URL we recognize (quiet server), guess. Prefer
+    // the port we HANDED it over the one we inferred from its framework: a server
+    // quiet enough to reach this line is usually a plain node/express one, and
+    // those are exactly the ones that read $PORT.
+    bindTimer = setTimeout(() => void openTunnel(bindPort ?? port), 30_000);
     timer = setTimeout(() => {
       log?.(
         `preview tunnel did not come up in ${Math.round(timeoutMs / 1000)}s — skipping.${

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.33.0",
+  "version": "0.34.2",
   "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": {