flowviant 0.99.0 → 0.100.0

package/README.md

@@ -2,8 +2,9 @@
 
 Run your own coding CLIs as build agents for [Flowviant](https://flowviant.com) — [Claude Code](https://claude.com/claude-code), Codex or Antigravity, on your own credentials. This daemon holds your sessions, keeps a worktree per tab, and ships branches on your word. Flowviant never sees your Claude, Codex or GitHub logins.
 
-```bash
-npx flowviant@latest login   # approve the code in Flowviant → connected
+```sh
+curl -fsSL https://api.flowviant.com/install.sh | sh
+flowviant   # approve the code in Flowviant → connected
 ```
 
 Login keeps going straight into the daemon — there is no second command to run.
@@ -21,40 +22,39 @@ Because it drives the CLIs you're already logged into, **the cost is yours** (yo
 On the machine that runs the daemon:
 
 - **at least one coding CLI** installed and signed in — [Claude Code](https://claude.com/claude-code) (`claude`), Codex (`codex`) or Antigravity (`agy`)
-- **git**, and **Node 20+**
+- **git** (Node 20+ is needed only for a Node-based install)
 - **[GitHub CLI](https://cli.github.com)** (`gh`) — optional; the daemon offers to fetch an isolated copy, and `flowviant gh-auth` signs it in
 - run it from inside the git repository you want worked
 
 ## Connecting
 
-The easy way — device login, like `gh auth login`:
+Download the standalone binary, then start it in your checkout:
 
-```bash
-npx flowviant@latest login
+```sh
+curl -fsSL https://api.flowviant.com/install.sh | sh
+flowviant
 ```
 
-It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `npx flowviant@latest` just runs.
+It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `flowviant` just runs. The installer prints a PATH hint if needed; `FLOWVIANT_INSTALL_DIR` changes its destination. It verifies SHA-256 and never uses sudo.
 
 Prefer an explicit token? Create a machine credential in the app and pass it directly:
 
 ```bash
-FLOWVIANT_MACHINE_TOKEN=fva_… npx flowviant@latest   # FLOWVIANT_FLEET still works
+FLOWVIANT_MACHINE_TOKEN=fva_… flowviant   # FLOWVIANT_FLEET still works
 ```
 
-Prefer a plain command to `npx`? Install it once and every `npx flowviant@latest` in this README is just `flowviant`:
+With Node already installed, a global install also gives you the same command:
 
 ```bash
 npm i -g flowviant
 flowviant login
 ```
 
-Either way is fine and both stay current on their own (below). npx is the zero-install door; a global install is what you want on a box you keep running, so the daemon, `flowviant login` and `flowviant machines` are ordinary commands.
-
-Launch with `@latest` so each start pulls the newest published version — a bare `npx flowviant` can reuse a stale cache. A running daemon also keeps itself current: from **0.58.0** it restarts itself through `npx flowviant@latest` when a new version ships, so npx launches stay up to date the same way a global install does. (Before 0.58.0 that was only true of a global install — under npx the daemon printed a notice and stayed put, which is how machines ended up sitting several releases back.) It only ever restarts when no turn is running. `FLOWVIANT_NO_UPDATE=1` makes it nag-only; `flowviant update` updates now.
+The binary and global npm installs update when idle. The binary fetches the release manifest and verifies the new executable before replacing itself. The global install refreshes from npm before restarting. `flowviant update` checks on demand. `FLOWVIANT_NO_UPDATE=1` makes updates manual.
 
 ## Machines on this box
 
-One box can serve several projects — one daemon per repository directory, each connected with its own `flowviant login` run inside that repo. `flowviant machines` lists every project connected on this box with the id and date it was connected, and under each one every computer that has polled it (the app's Home lists the same across your whole account). Two projects bound to one repository are named out loud at the foot of the listing, because that is the one shape that reads as "the same project connected twice" and is not — and a directory serves one project, so `npx flowviant` there refuses to start until one of them goes.
+One box can serve several projects — one daemon per repository directory, each connected with its own `flowviant login` run inside that repo. `flowviant machines` lists every project connected on this box with the id and date it was connected, and under each one every computer that has polled it (the app's Home lists the same across your whole account). Two projects bound to one repository are named out loud at the foot of the listing, because that is the one shape that reads as "the same project connected twice" and is not — and a directory serves one project, so `flowviant` there refuses to start until one of them goes.
 
 On a terminal the listing is a menu: ↑/↓ over the projects, enter for what you can do about one, esc to leave. Two verbs, each acting on **this box's own connection** and nothing else:
 
@@ -128,6 +128,8 @@ The posture is reported on every poll and shown in the project's
 Settings → Machine section, so the team can see whether the box runs the
 guarded toolset or full permissions.
 
+With Node: `npx flowviant@latest login` runs without a global install and updates by restarting through the package runner when idle.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/bin/cli.mjs

@@ -70,9 +70,31 @@
  * env (the box keypair, the uplink scrubber, the env-comparison scan) + vault
  * (the knowledge wiki, not secrets), resources, deploy, shot.
  */
-import { FLEET_TOKEN, CREDENTIAL, adoptStoredCredential } from './lib/config.mjs';
-import { runFleetDaemon } from './lib/fleet.mjs';
-import { runLogin } from './lib/login.mjs';
+// Resolve --dir before config reads the project bound to cwd. A tray process
+// starts outside the checkout; its explicit folder is the daemon's checkout.
+const dirAt = process.argv.indexOf('--dir');
+const noCheckoutCommand = new Set(['--version', '-v', 'version', 'status', 'stop', 'machines', 'projects', 'update', 'shot', 'clean', 'gh-auth', 'mcp']);
+if (dirAt >= 0 && !noCheckoutCommand.has(process.argv[2])) {
+  const dir = process.argv[dirAt + 1];
+  try {
+    if (!dir || dir.startsWith('--')) throw new Error('missing directory');
+    process.chdir(dir);
+  } catch (e) {
+    if (process.argv.includes('--json') && process.argv[2] === 'login')
+      process.stdout.write(`${JSON.stringify({ event: 'error', message: `Cannot use directory ${dir ?? ''}: ${e.message}` })}\n`);
+    else console.error(`error: cannot use directory ${dir ?? ''}: ${e.message}`);
+    process.exit(1);
+  }
+}
+const { FLEET_TOKEN, CREDENTIAL, VERSION, adoptStoredCredential } = await import('./lib/config.mjs');
+const { runFleetDaemon } = await import('./lib/fleet.mjs');
+const { runLogin } = await import('./lib/login.mjs');
+const { launchCommand, terminalCommand } = await import('./lib/launchCommand.mjs');
+
+if (process.argv.includes('--remote') && !(process.argv[2] === 'status' && process.argv.includes('--json'))) {
+  console.error('error: --remote requires status --json');
+  process.exit(1);
+}
 
 // `flowviant login` — device auth (recommended): approve a code in the app, the
 // credential is stored locally, and then we KEEP GOING into the daemon.
@@ -86,9 +108,17 @@ import { runLogin } from './lib/login.mjs';
 //
 // `--no-start` for scripts and CI, which want the credential and not a
 // long-running process.
+// `flowviant --version` prints and exits — the first thing a person runs after
+// a curl install, and it must never start a daemon.
+if (process.argv[2] === '--version' || process.argv[2] === '-v' || process.argv[2] === 'version') {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 if (process.argv[2] === 'login') {
   const noStart = process.argv.includes('--no-start');
-  const login = await runLogin({ thenStart: !noStart });
+  const json = process.argv.includes('--json');
+  const login = await runLogin({ thenStart: !noStart, json, dir: process.cwd() });
   // A login the person CANCELLED at the second-project question saved nothing,
   // so there is no credential for the child to serve — starting it would end
   // in "no credential found" over a choice they just made on purpose.
@@ -101,7 +131,8 @@ if (process.argv[2] === 'login') {
   // 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]], {
+  const startArgs = process.argv[1]?.startsWith('/$bunfs/') ? [] : [process.argv[1]];
+  const child = spawn(process.execPath, [...startArgs, ...(json ? ['--json-events'] : [])], {
     stdio: 'inherit',
     env: process.env,
   });
@@ -111,11 +142,18 @@ if (process.argv[2] === 'login') {
   process.exit(await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0))));
 }
 
+if (process.argv[2] === 'status' && process.argv.includes('--json')) {
+  const { desktopStatus, desktopStatusRemote } = await import('./lib/desktopContract.mjs');
+  const status = process.argv.includes('--remote') ? await desktopStatusRemote() : desktopStatus();
+  process.stdout.write(`${JSON.stringify(status)}\n`);
+  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();
+  await runUpdateCommand();
   process.exit(0);
 }
 
@@ -192,8 +230,16 @@ if (process.argv[2] === 'shot') {
 // daemon is running on this machine." is the answer the asker came for, not an
 // error. Non-zero only when something was alive and could not be stopped.
 if (process.argv[2] === 'stop') {
-  const { stopAllDaemons } = await import('./lib/instance.mjs');
-  const { failed } = stopAllDaemons({ log: (m) => console.log(m) });
+  const { stopAllDaemons, stopDaemonFor } = await import('./lib/instance.mjs');
+  let result;
+  if (process.argv.includes('--project')) {
+    const { matchStoredProject } = await import('./lib/credentials.mjs');
+    const at = process.argv.indexOf('--project');
+    const match = matchStoredProject(process.argv[at + 1]);
+    if (match.error) { console.error(`error: ${match.error}`); process.exit(1); }
+    result = stopDaemonFor(match.entry.fleetToken, { log: (m) => console.log(m) });
+  } else result = stopAllDaemons({ log: (m) => console.log(m) });
+  const { failed } = result;
   process.exit(failed > 0 ? 1 : 0);
 }
 
@@ -206,7 +252,7 @@ if (process.argv[2] === 'projects') {
   const { listStoredProjects, projectLabel } = await import('./lib/credentials.mjs');
   const entries = listStoredProjects();
   if (entries.length === 0) {
-    console.log('no projects connected on this machine yet — run `flowviant login` inside a repo.');
+    console.log(`no projects connected on this machine yet — run \`${terminalCommand('login')}\` inside a repo.`);
     process.exit(0);
   }
   for (const e of entries) {
@@ -227,8 +273,8 @@ if (process.argv[2] === 'projects') {
     );
   }
   console.log(
-    '\n  `npx flowviant` picks by the repo it is started in; `--project <name|id>` overrides;\n' +
-      '  `flowviant login` in a new repo connects another project.'
+    `\n  \`${launchCommand()}\` picks by the repo it is started in; \`--project <name|id>\` overrides;\n` +
+      `  \`${terminalCommand('login')}\` in a new repo connects another project.`
   );
   process.exit(0);
 }
@@ -267,20 +313,27 @@ if (process.argv[2] === 'projects') {
 // is the one exit that can be 1, when the daemon it had to stop would not.
 if (process.argv[2] === 'machines') {
   const creds = await import('./lib/credentials.mjs');
+  const machineJson = process.argv.includes('--json');
   const forgetAt = process.argv.indexOf('--forget');
   if (forgetAt >= 0) {
+    if (machineJson && !process.argv.includes('--yes')) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: '--yes is required with --json' })}\n`);
+      process.exit(1);
+    }
     // THE LOCAL-ONLY WRITE. Named explicitly, matched by full id or a ≥6
     // prefix, and AMBIGUITY REFUSES rather than guessing — this deletes a
     // credential, and two projects that look alike is the case that produced
     // the command.
     const res = creds.forgetStoredProject(process.argv[forgetAt + 1]);
     if (res.error) {
+      if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: false, error: res.error })}\n`); process.exit(1); }
       console.error(`error: ${res.error}`);
       process.exit(1);
     }
+    if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: true, action: 'forget', projectId: res.entry.projectId })}\n`); process.exit(0); }
     console.log(
       `forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box.\n` +
-        '  Nothing was stopped or deleted anywhere else — `flowviant login` connects it again.'
+        `  Nothing was stopped or deleted anywhere else — \`${terminalCommand('login')}\` connects it again.`
     );
     process.exit(0);
   }
@@ -289,22 +342,28 @@ if (process.argv[2] === 'machines') {
   const { FLEET_URL } = await import('./lib/config.mjs');
   const removeAt = process.argv.indexOf('--remove');
   if (removeAt >= 0) {
+    if (machineJson && !process.argv.includes('--yes')) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: '--yes is required with --json' })}\n`);
+      process.exit(1);
+    }
     // THE SCRIPTED DISCONNECT — the menu's first verb, named by id for a
     // terminal nobody is sitting at. Same matcher and the same refusal of an
     // ambiguous prefix as --forget: a name two projects share is exactly the
     // input this command exists to untangle, and it must not pick one.
     const m = creds.matchStoredProject(process.argv[removeAt + 1]);
     if (m.error) {
-      console.error(`error: ${m.error}. \`flowviant machines\` lists what is stored.`);
+      if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: false, error: m.error })}\n`); process.exit(1); }
+      console.error(`error: ${m.error}. \`${terminalCommand('machines')}\` lists what is stored.`);
       process.exit(1);
     }
-    const res = await disconnectHere(m.entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL) }));
+    const res = await disconnectHere(m.entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL), log: machineJson ? () => {} : undefined }), { log: machineJson ? () => {} : undefined });
+    if (machineJson) process.stdout.write(`${JSON.stringify({ ok: res.ok, action: 'disconnect', projectId: m.entry.projectId })}\n`);
     process.exit(res.ok ? 0 : 1);
   }
 
   let entries = creds.listStoredProjects();
   if (entries.length === 0) {
-    console.log('no projects connected on this machine yet — run `flowviant login` inside a repo.');
+    console.log(`no projects connected on this machine yet — run \`${terminalCommand('login')}\` inside a repo.`);
     process.exit(0);
   }
   // OUR OWN BOX ID, so the listing can mark "← this box".
@@ -391,7 +450,7 @@ if (process.argv[2] === 'machines') {
       console.log(
         res.error
           ? `  ${res.error}`
-          : `  forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box. Nothing was stopped or deleted anywhere else — \`flowviant login\` connects it again.`
+          : `  forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box. Nothing was stopped or deleted anywhere else — \`${terminalCommand('login')}\` connects it again.`
       );
     }
     entries = creds.listStoredProjects();
@@ -466,7 +525,7 @@ async function reexecAfterLogin() {
   const login = await runLogin({ thenStart: false });
   if (!login?.saved) process.exit(1); // refused: the directory already serves another project
   const { spawn } = await import('node:child_process');
-  const child = spawn(process.execPath, [process.argv[1]], { stdio: 'inherit', env: process.env });
+  const child = spawn(process.execPath, process.argv[1]?.startsWith('/$bunfs/') ? [] : [process.argv[1]], { stdio: 'inherit', env: process.env });
   process.exit(await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0))));
 }
 
@@ -493,7 +552,7 @@ let afterLock = null;
 
 if (!FLEET_TOKEN) {
   if (CREDENTIAL.error) {
-    console.error(`error: ${CREDENTIAL.error}. \`flowviant projects\` lists what is stored.`);
+    console.error(`error: ${CREDENTIAL.error}. \`${terminalCommand('projects')}\` lists what is stored.`);
     process.exit(1);
   }
   // A DIRECTORY SERVES ONE PROJECT (2026-09-23, the owner, verbatim: "a
@@ -521,7 +580,7 @@ if (!FLEET_TOKEN) {
         : `This repo (${repoRoot}) is not connected to any project yet. Connected on this machine:`
     );
 
-    const loginLabel = `connect ${repoRoot ? 'this repo' : 'a repo'} to a different project (flowviant login)`;
+    const loginLabel = `connect ${repoRoot ? 'this repo' : 'a repo'} to a different project (${terminalCommand('login')})`;
     // WHICH ONE LOOKS RIGHT — a pre-selection, never an auto-serve. The resolver
     // refuses to serve a project the repo PATH did not name (the skadooble law);
     // this only decides which row the cursor starts on, using the repo's folder
@@ -605,14 +664,14 @@ if (!FLEET_TOKEN) {
     console.error(
       'error: more than one project is connected on this machine and this repo is not bound to any of them:\n' +
         listLines(CREDENTIAL.choices, creds) +
-        '\nPick one with `--project <name|id>`, bind this repo by running `flowviant` here in a terminal once,\n' +
-        'or connect this repo to its own project with `flowviant login`.'
+        `\nPick one with \`--project <name|id>\`, bind this repo by running \`${terminalCommand()}\` here in a terminal once,\n` +
+        `or connect this repo to its own project with \`${terminalCommand('login')}\`.`
     );
     process.exit(1);
   } else {
     console.error(
       'error: no credential found. Easiest:\n' +
-        '  flowviant login      (approve in the app — recommended)\n' +
+        `  ${terminalCommand('login')}      (approve in the app — recommended)\n` +
         'Or set:\n' +
         '  FLOWVIANT_FLEET=fva_…   (machine token, from the app)'
     );
@@ -652,18 +711,29 @@ if (!FLEET_TOKEN) {
   if (raw === null) {
     console.log(
       `\n  could not read an answer — serving ${label} for this run ` +
-        `without tying it to this repo. Run \`flowviant\` here and answer to make it stick.`
+        `without tying it to this repo. Run \`${terminalCommand()}\` here and answer to make it stick.`
     );
   } else if (raw === '' || raw === 'y' || raw === 'yes') {
     // After the lock, for the reason the picker's bind gives above.
     afterLock = () => creds.bindStoredRepo(CREDENTIAL.entry.projectId, CREDENTIAL.repoRoot);
   } else {
     console.error(
-      `nothing started. Connect this repo to its own project with \`flowviant login\`, ` +
-        `or see what is stored with \`flowviant projects\`.`
+      `nothing started. Connect this repo to its own project with \`${terminalCommand('login')}\`, ` +
+        `or see what is stored with \`${terminalCommand('projects')}\`.`
     );
     process.exit(1);
   }
 }
 
+if (process.argv.includes('--json-events') && dirAt >= 0 && CREDENTIAL?.entry) {
+  const { detectRepoRoot, listStoredProjects, boundElsewhere } = await import('./lib/credentials.mjs');
+  const repo = detectRepoRoot();
+  const entry = CREDENTIAL.entry;
+  if (!repo || entry.repoRoot !== repo || boundElsewhere(listStoredProjects(), repo, entry.projectId).length) {
+    console.error('error: this project is not connected to this repository. Run `flowviant login` for the selected folder.');
+    process.exit(1);
+  }
+}
+const { installDaemonLogging } = await import('./lib/desktopContract.mjs');
+installDaemonLogging(CREDENTIAL?.entry?.projectId, { jsonEvents: process.argv.includes('--json-events') });
 await runFleetDaemon({ afterLock });

package/bin/lib/config.mjs

@@ -11,14 +11,18 @@ import { cpus, hostname, totalmem } from 'node:os';
 // '0.28.0' across every release through 0.28.6, so the startup banner, the
 // User-Agent the server version-gates on, and the self-update check all reported
 // a stale version (and the "update available" nag never cleared).
-export const VERSION = (() => {
-  try {
-    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
-    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-})();
+// The compile script substitutes this constant into the binary. npm installs
+// still read their own package.json exactly as before (including on Node 20).
+export const VERSION = typeof __FLOWVIANT_BUILD_VERSION__ === 'string'
+  ? __FLOWVIANT_BUILD_VERSION__
+  : (() => {
+      try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        return JSON.parse(readFileSync(pkgPath, 'utf8')).version || '0.0.0';
+      } catch {
+        return '0.0.0';
+      }
+    })();
 
 // The model EVERY daemon Claude turn runs on — pinned so autonomous work never
 // inherits your interactive `~/.claude/settings.json` default. That matters: a

package/bin/lib/credentials.mjs

@@ -49,6 +49,7 @@ import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { printable } from './printable.mjs';
+import { terminalCommand } from './launchCommand.mjs';
 
 const CRED_DIR = join(homedir(), '.flowviant');
 const CRED_FILE = join(CRED_DIR, 'credentials.json');
@@ -281,7 +282,7 @@ export function directoryTakenRefusal(bound, repoRoot, { incoming } = {}) {
     `${head}\n` +
     'A directory serves one project — two projects must not edit it at the same time.\n' +
     'Delete the project you do not mean in Flowviant first (project settings → General → Delete project),\n' +
-    'or disconnect this box from it with `flowviant machines`, then run this again.'
+    `or disconnect this box from it with \`${terminalCommand('machines')}\`, then run this again.`
   );
 }
 

package/bin/lib/desktopContract.mjs

@@ -0,0 +1,227 @@
+/** Local, read-only desktop contract and bounded daemon logs. */
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { format } from 'node:util';
+import { FLEET_URL, MACHINE_HOST, USER_AGENT, VERSION } from './config.mjs';
+import { listStoredProjects } from './credentials.mjs';
+import { readStoredPubB64 } from './env.mjs';
+import { daemonRunningFor } from './instance.mjs';
+import { runningViaNpx } from './launchCommand.mjs';
+import { boxesUrlFrom, fetchBoxesFor } from './machines.mjs';
+import { detectRuntimes } from './runtimes.mjs';
+import { runningCompiledBinary } from './update.mjs';
+
+export const MAX_DAEMON_LOG_BYTES = 2 * 1024 * 1024;
+const store = () => join(homedir(), '.flowviant');
+const key = (projectId) => createHash('sha256').update(String(projectId)).digest('hex').slice(0, 16);
+export const daemonLogPath = (projectId) => join(store(), `daemon-${key(projectId)}.log`);
+export const daemonStatePath = (projectId) => join(store(), `daemon-${key(projectId)}.state.json`);
+
+function readState(projectId) {
+  try {
+    const value = JSON.parse(readFileSync(daemonStatePath(projectId), 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+export function writeDaemonState(projectId, change) {
+  if (!projectId) return;
+  try {
+    mkdirSync(store(), { recursive: true });
+    const path = daemonStatePath(projectId);
+    const current = readState(projectId);
+    const next = { ...current, ...change, pid: process.pid };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next), { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch { /* a local readout must never interrupt a daemon */ }
+}
+
+export function setRuntimeLimit(projectId, runtime, words) {
+  if (!projectId || !runtime) return false;
+  const state = readState(projectId);
+  const limits = { ...(state.limits ?? {}) };
+  if (words == null) {
+    if (!Object.hasOwn(limits, runtime)) return false;
+    delete limits[runtime];
+  } else {
+    if (limits[runtime] === words) return false;
+    limits[runtime] = words;
+  }
+  writeDaemonState(projectId, { limits });
+  emitMachineEvent({ event: words == null ? 'limit-cleared' : 'limit-hit', runtime, ...(words == null ? {} : { message: words }) });
+  return true;
+}
+
+export function installChannel() {
+  return runningCompiledBinary() ? 'binary' : runningViaNpx() ? 'npx' : 'npm-g';
+}
+
+export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readState, pidFor = lockPid } = {}) {
+  return {
+    schema: 1,
+    version: VERSION,
+    installChannel: installChannel(),
+    projects: entries.map((entry) => {
+      const running = runningFor(entry.fleetToken);
+      const state = stateFor(entry.projectId);
+      const liveState = running === true && state.pid != null && state.pid === pidFor(entry.fleetToken) ? state : null;
+      return {
+        id: entry.projectId,
+        name: entry.name ?? null,
+        dir: entry.repoRoot ?? null,
+        running,
+        holder: liveState?.holder ?? null,
+        lastPoll: state.lastPoll ?? null,
+        logFile: daemonLogPath(entry.projectId),
+        runtimes: runtimes.map((rt) => ({
+          id: rt.id,
+          installed: rt.installed,
+          version: rt.version ?? null,
+          dispatchable: rt.dispatchable,
+          ...(liveState?.limits?.[rt.id] ? { parkedByLimit: true, message: liveState.limits[rt.id] } : {}),
+        })),
+      };
+    }),
+    // A box with no projects still has installed CLIs.
+    runtimes: runtimes.map((rt) => ({ id: rt.id, installed: rt.installed, version: rt.version ?? null, dispatchable: rt.dispatchable })),
+  };
+}
+
+const REMOTE_TIMEOUT_MS = 4_000;
+
+async function remoteRead(read, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    // Abort the request and bound body parsing even if a fetch ignores its signal.
+    return await Promise.race([
+      read(controller.signal),
+      new Promise((resolve) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          resolve({ error: `timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    return { error: String(error?.message ?? error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function liveAgent(row) {
+  if (!row || typeof row !== 'object' || typeof row.id !== 'string' || !row.id ||
+      typeof row.name !== 'string' || !row.name || typeof row.status !== 'string' ||
+      typeof row.runtime !== 'string' || !row.runtime ||
+      !['delivered', 'total'].every((field) => Number.isInteger(row[field]) && row[field] >= 0) ||
+      !['asks', 'parked'].every((field) => typeof row[field] === 'boolean') ||
+      !(row.since === null || typeof row.since === 'string')) return null;
+  const { id, name, status, runtime, delivered, total, asks, parked, since } = row;
+  return { id, name, status, runtime, delivered, total, asks, parked, since };
+}
+
+async function fetchLiveAgentsFor(entry, { url, fetchImpl, signal }) {
+  const res = await fetchImpl(url, {
+    headers: { Authorization: `Bearer ${entry.fleetToken}`, 'User-Agent': USER_AGENT },
+    signal,
+  });
+  if (!res.ok) return { error: `HTTP ${res.status}` };
+  const body = await res.json();
+  const data = body?.data ?? body;
+  if (!data || !Array.isArray(data.agents)) return { error: 'unexpected answer shape' };
+  const pressure = data.pressure;
+  return {
+    agents: data.agents.map(liveAgent).filter(Boolean),
+    pressure: pressure && typeof pressure.reason === 'string' && typeof pressure.at === 'string'
+      ? { reason: pressure.reason, at: pressure.at } : null,
+  };
+}
+
+export async function desktopStatusRemote({ entries = listStoredProjects(), runtimes = detectRuntimes(),
+  runningFor = daemonRunningFor, stateFor = readState, pidFor = lockPid,
+  fetchImpl = fetch, envpub = readStoredPubB64(), fleetUrl = FLEET_URL, host = MACHINE_HOST,
+  now = () => new Date().toISOString(), timeoutMs = REMOTE_TIMEOUT_MS, log = console.error } = {}) {
+  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor });
+  const boxesUrl = boxesUrlFrom(fleetUrl);
+  const liveUrl = String(fleetUrl).replace(/\/agents\/?$/, '/live-agents');
+  const remotes = await Promise.all(entries.map(async (entry) => {
+    if (!entry.fleetToken) return null;
+    const [boxes, live] = await Promise.all([
+      remoteRead((signal) => fetchBoxesFor(entry, { url: boxesUrl, envpub, fetchImpl, signal }), timeoutMs),
+      remoteRead((signal) => fetchLiveAgentsFor(entry, { url: liveUrl, fetchImpl, signal }), timeoutMs),
+    ]);
+    const boxesOk = Array.isArray(boxes.boxes);
+    const liveOk = Array.isArray(live.agents);
+    if (!boxesOk) {
+      const reason = boxes.error ?? (boxes.unsupported ? 'HTTP 404' : boxes.rejected ? 'credential rejected' : 'unexpected answer shape');
+      log(`status --remote ${entry.projectId} boxes: ${reason}`);
+    }
+    if (!liveOk) log(`status --remote ${entry.projectId} live-agents: ${live.error ?? 'unexpected answer shape'}`);
+    if (!boxesOk && !liveOk) return null;
+    const mine = boxesOk ? boxes.boxes.find((box) => box?.boxId === boxes.me) : null;
+    const serving = boxesOk ? boxes.boxes.find((box) => box?.role === 'serving') : null;
+    return {
+      at: now(),
+      boxName: boxesOk ? (typeof mine?.boxName === 'string' && mine.boxName ? mine.boxName : host || null) : null,
+      role: mine?.role === 'serving' || mine?.role === 'inactive' ? mine.role : null,
+      servingBoxName: typeof serving?.boxName === 'string' ? serving.boxName : null,
+      daemonVersion: typeof mine?.daemonVersion === 'string' ? mine.daemonVersion : null,
+      latest: boxesOk ? boxes.latest : null,
+      agents: liveOk ? live.agents : null,
+      pressure: liveOk ? live.pressure : null,
+    };
+  }));
+  status.projects.forEach((project, index) => { project.remote = remotes[index]; });
+  return status;
+}
+
+function lockPid(token) {
+  try {
+    const hash = createHash('sha256').update(String(token || 'anon')).digest('hex').slice(0, 12);
+    return JSON.parse(readFileSync(join(store(), `daemon-${hash}.lock`), 'utf8')).pid;
+  } catch { return null; }
+}
+
+let events = false;
+let eventWriter = process.stdout.write.bind(process.stdout);
+export function enableMachineEvents(write = eventWriter) { events = true; eventWriter = write; }
+export function emitMachineEvent(value) {
+  if (events) eventWriter(`${JSON.stringify(value)}\n`);
+}
+
+/** All human output stays on its existing stream in terminal mode. In desktop
+ * mode stdout is reserved for JSONL and those same lines go to stderr. */
+export function installDaemonLogging(projectId, { jsonEvents = false } = {}) {
+  if (!projectId) return;
+  if (jsonEvents) {
+    enableMachineEvents();
+    process.stdout.write = (...args) => process.stderr.write(...args);
+  }
+  const original = { log: console.log, info: console.info, warn: console.warn, error: console.error };
+  const logPath = daemonLogPath(projectId);
+  for (const method of Object.keys(original)) {
+    console[method] = (...args) => {
+      const line = format(...args);
+      try {
+        mkdirSync(store(), { recursive: true });
+        const encoded = Buffer.from(`${line}\n`);
+        const tail = Buffer.from('\n[truncated]\n');
+        const chunk = encoded.length > MAX_DAEMON_LOG_BYTES
+          ? Buffer.concat([encoded.subarray(0, MAX_DAEMON_LOG_BYTES - tail.length), tail])
+          : encoded;
+        let size = 0;
+        try { size = statSync(logPath).size; } catch { /* new file */ }
+        if (size + chunk.length > MAX_DAEMON_LOG_BYTES) {
+          try { renameSync(logPath, `${logPath}.1`); } catch { /* no old log */ }
+        }
+        appendFileSync(logPath, chunk, { mode: 0o600 });
+      } catch { /* logging must never stop service */ }
+      if (jsonEvents) process.stderr.write(`${line}\n`);
+      else original[method](...args);
+    };
+  }
+}

package/bin/lib/fleet.mjs

@@ -39,7 +39,8 @@ import {
 } from './config.mjs';
 import { projectLabel, safeName, setStoredProjectName } from './credentials.mjs';
 import { credentialRejected } from './authReject.mjs';
-import { handleVersionSignal } from './update.mjs';
+import { handleVersionSignal, cmpVersion } from './update.mjs';
+import { emitMachineEvent, writeDaemonState } from './desktopContract.mjs';
 import {
   git,
   gitNetAsync,
@@ -1128,6 +1129,8 @@ export async function standDownDisplaced({
         ? `this project's machine moved to ${name} — standing down.`
         : "this project's machine moved to another box — standing down."
   );
+  if (removed) emitMachineEvent({ event: 'stopped', reason: 'removed' });
+  else emitMachineEvent({ event: 'displaced', message: displacedTurnSentence(by) });
   // FIRST, and awaited: an unsettled turn is the one thing here that no later
   // poll from anybody can fix — this process holds the only copy of the fact
   // that it was running.
@@ -1160,6 +1163,10 @@ export async function standDownDisplaced({
 // base between tasks (fresh conversation), resume in place while on a blocker.
 
 export async function runFleetDaemon({ afterLock = null } = {}) {
+  let desktopProjectId = CREDENTIAL?.entry?.projectId ?? null;
+  let wasServing = false;
+  if (process.env.FLOWVIANT_UPDATE_TARGET && cmpVersion(VERSION, process.env.FLOWVIANT_UPDATE_TARGET) >= 0)
+    emitMachineEvent({ event: 'update-applied', from: process.env.FLOWVIANT_UPDATE_FROM ?? null, to: VERSION });
   console.log('');
   console.log(`  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`machine daemon · v${VERSION}`)}`);
   console.log(`  ${c.dim('──────────────────────────────────────────────')}`);
@@ -1279,6 +1286,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   } catch {
     /* the binding is asked again next time */
   }
+  writeDaemonState(desktopProjectId, { limits: {}, holder: null });
 
   await preflight({ needGit: true });
 
@@ -1443,6 +1451,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // A SAME-REPO TAKEOVER IS DELIBERATELY NOT DISTINGUISHED, and that is a
   };
   process.on('SIGINT', () => {
+    emitMachineEvent({ event: 'stopped', reason: 'signal' });
     console.log('');
     note('shutting down — stopping workers. Worktrees are kept: in-flight work resumes next run.');
     teardown();
@@ -1452,6 +1461,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   // handler every child survived a `systemctl stop` — the exact orphaning the
   // teardown exists to prevent.
   process.on('SIGTERM', () => {
+    emitMachineEvent({ event: 'stopped', reason: 'signal' });
     console.log('');
     note('shutting down (SIGTERM) — stopping workers. Worktrees are kept: in-flight work resumes next run.');
     teardown();
@@ -2407,6 +2417,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       );
     } catch (e) {
       if (e.auth) {
+        emitMachineEvent({ event: 'stopped', reason: 'credential-revoked' });
         fail(`${e.message} — credential revoked or invalid. Shutting down.`);
         teardown();
         // EXIT 0, for the same reason the commanded-stop path does: a revoked
@@ -2467,6 +2478,8 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
         }
       })();
     }
+    if (roster.project?.id) desktopProjectId = roster.project.id;
+    writeDaemonState(desktopProjectId, { lastPoll: new Date().toISOString() });
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
     /**
      * HOW MANY TURNS THE APP SAYS THIS MACHINE MAY RUN (2026-09-17).
@@ -2495,6 +2508,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // going away.
     const stopSignal = shouldStop(roster.daemon);
     if (stopSignal) {
+      emitMachineEvent({ event: 'stopped', reason: stopSignal.reason ?? null });
       warn(
         stopSignal.reason
           ? `stopped by Flowviant — ${stopSignal.reason}`
@@ -2599,6 +2613,12 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
      * would start deleting worktrees it cannot see the tabs for.
      */
     holderState = holderWatch.observe(roster.holder);
+    writeDaemonState(desktopProjectId, {
+      lastPoll: new Date().toISOString(),
+      holder: ({ mine: 'serving', standby: 'inactive' })[holderState] ?? null,
+    });
+    if (holderState === 'mine' && !wasServing) emitMachineEvent({ event: 'serving' });
+    wasServing = holderState === 'mine';
     // 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.
@@ -2620,7 +2640,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
         safeToUpdate,
         teardown,
       });
-      if (updating) return;
+      if (await updating) return;
     }
     // Settle any turn/ship answers whose earlier report POST failed BEFORE
     // taking new work — the skip-if-pending guards make the ordering safe, but

package/bin/lib/instance.mjs

@@ -139,6 +139,20 @@ function readHolder(path) {
   }
 }
 
+/** Read-only desktop measurement. No lock is unknown because an unguarded or
+ * older daemon may still run; a stale lock with a dead pid measures empty. */
+export function daemonRunningFor(fleetToken) {
+  const path = instanceLockPath(fleetToken);
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); }
+  catch { return null; }
+  let holder;
+  try { holder = JSON.parse(raw); } catch { return null; }
+  if (!Number.isInteger(holder?.pid) || holder.pid <= 0) return null;
+  if (!alive(holder.pid)) return false;
+  return stillTheHolder(holder);
+}
+
 /**
  * argv[1] AS IT WAS TYPED, when that differs from the resolved form.
  *

package/bin/lib/launchCommand.mjs

@@ -0,0 +1,23 @@
+import { fileURLToPath } from 'node:url';
+
+/** The updater and terminal advice share one detection of the launch channel. */
+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);
+}
+
+/** Name the command that launched this process when giving a person a next step. */
+export function launchCommand() {
+  return 'flowviant';
+}
+
+export function terminalCommand(args = '') {
+  return `${launchCommand()}${args ? ` ${args}` : ''}`;
+}

package/bin/lib/login.mjs

@@ -10,6 +10,7 @@ import { FLEET_URL, USER_AGENT, VERSION } from './config.mjs';
 import { saveLogin, detectRepoRoot, projectLabel, safeName, listStoredProjects, boundElsewhere, directoryTakenRefusal } from './credentials.mjs';
 import { c, info, ok, warn, fail } from './ui.mjs';
 import { sleep } from './claude.mjs';
+import { launchCommand, terminalCommand } from './launchCommand.mjs';
 
 const DEVICE_START = FLEET_URL.replace(/\/agents\/?$/, '/device/start');
 const DEVICE_POLL = FLEET_URL.replace(/\/agents\/?$/, '/device/poll');
@@ -27,24 +28,35 @@ async function post(url, body) {
   return j.data ?? j;
 }
 
-export async function runLogin({ thenStart = false } = {}) {
-  console.log(`\n  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`login · v${VERSION}`)}\n`);
+export async function runLogin({ thenStart = false, json = false, dir = process.cwd() } = {}) {
+  const event = (value) => { if (json) process.stdout.write(`${JSON.stringify(value)}\n`); };
+  const selectedRepo = json ? detectRepoRoot(dir) : null;
+  if (json && !selectedRepo) { event({ event: 'error', message: `No git repository found in ${dir}.` }); return { saved: false }; }
+  if (!json) console.log(`\n  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`login · v${VERSION}`)}\n`);
   let start;
   try {
     start = await post(DEVICE_START, {});
   } catch (e) {
+    if (json) { event({ event: 'error', message: `couldn't reach Flowviant (${e.message}).` }); return { saved: false }; }
     fail(`couldn't reach Flowviant (${e.message}).`);
     process.exit(1);
   }
   const { deviceCode, userCode, intervalSeconds = 5, expiresInSeconds = 600 } = start;
+  if (json && (typeof deviceCode !== 'string' || typeof userCode !== 'string' || userCode.length < 8)) {
+    event({ event: 'error', message: 'Flowviant returned an invalid login code.' });
+    return { saved: false };
+  }
   const pretty = `${userCode.slice(0, 4)}-${userCode.slice(4)}`;
   // Where the control ACTUALLY is. It was "the Agents panel", a settings
   // section deleted 2026-08-17; connecting a machine is offered on the surface
   // you are on when it matters, and for a new operator that is the Workbench —
   // the project's empty state says so before it can show you any sessions.
-  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Workbench')} → ${c.bold('Connect a machine')}.`);
-  console.log(`  2. Enter this code:   ${c.bold(c.green(pretty))}\n`);
-  info('waiting for you to approve…');
+  if (json) event({ event: 'open_url', url: APP_URL, code: pretty });
+  else {
+    console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Workbench')} → ${c.bold('Connect a machine')}.`);
+    console.log(`  2. Enter this code:   ${c.bold(c.green(pretty))}\n`);
+    info('waiting for you to approve…');
+  }
 
   const deadline = Date.now() + expiresInSeconds * 1000;
   while (Date.now() < deadline) {
@@ -56,6 +68,10 @@ export async function runLogin({ thenStart = false } = {}) {
       continue; // transient — keep polling
     }
     if (poll.status === 'approved') {
+      if (json && (!poll.projectId || !(poll.machineToken ?? poll.fleetToken))) {
+        event({ event: 'error', message: 'Flowviant did not return a project credential.' });
+        return { saved: false };
+      }
       // `machineToken` is the wire's new name; `fleetToken` is the one every
       // published daemon reads. The server dual-sends until DAEMON_MIN clears
       // the release that reads the new one (0.54.2+) — reading both here is
@@ -65,7 +81,7 @@ export async function runLogin({ thenStart = false } = {}) {
       // know for certain which checkout this project means, and the binding is
       // what lets a multi-project VM resolve `npx flowviant` by DIRECTORY
       // instead of by whichever login happened last.
-      const repoRoot = detectRepoRoot();
+      const repoRoot = selectedRepo ?? detectRepoRoot(dir);
       const entry = {
         fleetToken: poll.machineToken ?? poll.fleetToken,
         projectId: poll.projectId,
@@ -86,12 +102,18 @@ export async function runLogin({ thenStart = false } = {}) {
       // (`directoryTakenRefusal`, shared with the daemon's own start).
       const clash = boundElsewhere(listStoredProjects(), repoRoot, entry.projectId);
       if (clash.length > 0) {
+        if (json) { event({ event: 'error', message: directoryTakenRefusal(clash, repoRoot, { incoming: entry }) }); return { saved: false }; }
         console.log('');
         warn(directoryTakenRefusal(clash, repoRoot, { incoming: entry }));
         console.log('');
         return { saved: false };
       }
-      saveLogin(entry);
+      try { saveLogin(entry); }
+      catch (e) {
+        if (json) { event({ event: 'error', message: `Could not save this connection: ${e.message}` }); return { saved: false }; }
+        throw e;
+      }
+      if (json) { event({ event: 'bound', projectId: entry.projectId, name: entry.name, dir: repoRoot }); return { saved: true }; }
       ok(
         `connected to ${c.bold(projectLabel(entry))}` +
           `${repoRoot ? ` for ${c.dim(repoRoot)}` : ''} — saved to ~/.flowviant/credentials.json`
@@ -102,15 +124,17 @@ export async function runLogin({ thenStart = false } = {}) {
       console.log(
         thenStart
           ? `\n  ${c.dim('starting your agent — leave this running')}\n`
-          : `\n  Now run:  ${c.bold('npx flowviant')}\n`
+          : `\n  Now run:  ${c.bold(launchCommand())}\n`
       );
       return { saved: true };
     }
     if (poll.status === 'expired') {
-      warn('that code expired — run `flowviant login` again.');
+      if (json) { event({ event: 'error', message: 'Login code expired.' }); return { saved: false }; }
+      warn(`that code expired — run \`${terminalCommand('login')}\` again.`);
       process.exit(1);
     }
   }
-  warn('login timed out — run `flowviant login` again.');
+  if (json) { event({ event: 'error', message: 'Login timed out.' }); return { saved: false }; }
+  warn(`login timed out — run \`${terminalCommand('login')}\` again.`);
   process.exit(1);
 }

package/bin/lib/machines.mjs

@@ -74,6 +74,7 @@
 import { USER_AGENT } from './config.mjs';
 import { projectLabel, repoCollisions, safeName } from './credentials.mjs';
 import { credentialRejected } from './authReject.mjs';
+import { launchCommand, terminalCommand } from './launchCommand.mjs';
 
 /** The boxes read, derived from the roster URL the way the diffstat post is —
  *  one place configures the API base and everything else is a suffix swap. */
@@ -246,7 +247,7 @@ export function renderMachines(entries, results, { now = Date.now() } = {}) {
     if (r.rejected) {
       lines.push(
         '    credential rejected — this project was disconnected or deleted. ' +
-          `\`flowviant machines --forget ${e.projectId.slice(0, 8)}\` removes it here.`
+          `\`${terminalCommand(`machines --forget ${e.projectId.slice(0, 8)}`)}\` removes it here.`
       );
       continue;
     }
@@ -297,7 +298,7 @@ export function renderCollisions(entries) {
     const list = `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
     return (
       `  ! ${g.entries.length} projects are connected for ${g.repoRoot}: ${list} — ` +
-      'a directory serves one project, and `npx flowviant` there refuses to start until it does. ' +
+      `a directory serves one project, and \`${launchCommand()}\` there refuses to start until it does. ` +
       'Delete the one you do not mean in Flowviant (project settings → General → Delete project), or disconnect this box from it.'
     );
   });
@@ -317,7 +318,7 @@ export function renderCollisions(entries) {
  */
 export const MACHINES_FOOTER = [
   '  stop a machine from the app: project settings → Machine → Disconnect;',
-  '  a new `npx flowviant` on another box takes the project over.',
+  `  a new \`${launchCommand()}\` on another box takes the project over.`,
   '  this lists the projects connected on THIS box; the app’s Home lists every machine on your account.',
 ];
 
@@ -325,7 +326,7 @@ export const MACHINES_FOOTER = [
  *  terminal that could draw the menu was offered the same two things by name,
  *  and repeating the flags under it would be a manual under a control. */
 export const MACHINES_FLAGS_FOOTER = [
-  '  `flowviant machines --remove <id>` disconnects this box from a project: stops its daemon here,',
+  `  \`${terminalCommand('machines --remove <id>')}\` disconnects this box from a project: stops its daemon here,`,
   '  removes this box from that project’s machines list in the app, and forgets its credential here.',
   '  `--forget <id>` forgets the credential here only.',
 ];
@@ -339,13 +340,13 @@ export const MACHINES_FLAGS_FOOTER = [
  * probably forget. Two different next moves; collapsing them is how somebody
  * deletes a working credential.
  */
-export async function fetchBoxesFor(entry, { url, envpub, fetchImpl = fetch } = {}) {
+export async function fetchBoxesFor(entry, { url, envpub, fetchImpl = fetch, signal = AbortSignal.timeout(15_000) } = {}) {
   const target = new URL(url);
   if (envpub) target.searchParams.set('envpub', envpub);
   try {
     const res = await fetchImpl(target, {
       headers: { Authorization: `Bearer ${entry.fleetToken}`, 'User-Agent': USER_AGENT },
-      signal: AbortSignal.timeout(15_000),
+      signal,
     });
     if (await credentialRejected(res)) return { rejected: true };
     if (res.status === 401 || res.status === 403) return { error: `HTTP ${res.status} from something in front of the app` };
@@ -487,7 +488,7 @@ export async function disconnectHere(entry, deps, { log = (m) => console.log(m)
     log(`could not forget the credential here: ${gone.error}`);
     return { ok: false };
   }
-  log(`forgot ${who}’s credential on this box. \`flowviant login\` in its repo connects it again.`);
+  log(`forgot ${who}’s credential on this box. \`${terminalCommand('login')}\` in its repo connects it again.`);
   return { ok: true };
 }
 

package/bin/lib/mcp-cli.mjs

@@ -18,15 +18,16 @@
  */
 
 import { FLEET_TOKEN, USER_AGENT, MCP_URL, FLEET_URL } from './config.mjs';
+import { terminalCommand } from './launchCommand.mjs';
 
 const CLI_TOKEN_URL = FLEET_URL.replace(/\/agents\/?$/, '/cli-token');
 
 export async function runMcpCommand(args = []) {
   if (!FLEET_TOKEN) {
     console.error(
-      'error: no credential resolves here. Run `flowviant login` first — or, with\n' +
+      `error: no credential resolves here. Run \`${terminalCommand('login')}\` first — or, with\n` +
         'several projects connected on this box, run this inside the project\'s own\n' +
-        'repo or pass `--project <name|id>` (`flowviant projects` lists them).'
+        `repo or pass \`--project <name|id>\` (\`${terminalCommand('projects')}\` lists them).`
     );
     process.exit(1);
   }
@@ -50,7 +51,7 @@ export async function runMcpCommand(args = []) {
     console.error(
       `error: could not mint a CLI credential (${res.status}). ` +
         (res.status === 401 || res.status === 403
-          ? 'Your credential may have been revoked — try `flowviant login` again.'
+          ? `Your credential may have been revoked — try \`${terminalCommand('login')}\` again.`
           : 'Try again in a moment.')
     );
     process.exit(1);

package/bin/lib/preflight.mjs

@@ -8,6 +8,7 @@ import { execFileSync } from 'node:child_process';
 import { ok, warn, info, c } from './ui.mjs';
 import { addLocalBinToPath, promptYesNo, installClaude, installGh } from './install.mjs';
 import { RUNTIMES, detectRuntimes, mediatedSafeGap } from './runtimes.mjs';
+import { terminalCommand } from './launchCommand.mjs';
 
 function present(cmd) {
   try {
@@ -106,7 +107,7 @@ export async function preflight({ needGit = true } = {}) {
       if (await installGh((m) => info(m))) gh = present('gh');
     }
     gh
-      ? ok('gh installed to ~/.flowviant/bin — authenticate with: flowviant gh-auth')
+      ? ok(`gh installed to ~/.flowviant/bin — authenticate with: ${terminalCommand('gh-auth')}`)
       : info(c.dim('or install it later: https://cli.github.com, then: gh auth login'));
   }
 

package/bin/lib/update.mjs

@@ -30,7 +30,14 @@
  */
 
 import { execFileSync, spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { chmod, mkdtemp, open, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { platform, arch } from 'node:process';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { runningViaNpx, terminalCommand } from './launchCommand.mjs';
 import { VERSION } from './config.mjs';
 import { note, ok, warn } from './ui.mjs';
 
@@ -45,22 +52,66 @@ export function cmpVersion(a, b) {
   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 = '';
+/** Bun marks compiled entrypoints with a virtual /$bunfs/ script path. */
+export function runningCompiledBinary() {
+  return Boolean(process.versions.bun && process.argv[1]?.startsWith('/$bunfs/'));
+}
+
+const RELEASE_ORIGIN = 'https://api.flowviant.com';
+
+/** Download and verify before replacing the executable. Exposed for temp-dir tests. */
+export async function installBinaryUpdate({
+  executable = process.execPath,
+  target = `${platform === 'darwin' ? 'darwin' : platform}-${arch}`,
+  fetchImpl = fetch,
+  origin = RELEASE_ORIGIN,
+  minimumVersion = null,
+} = {}) {
+  if (!/^(linux|darwin)-(x64|arm64)$/.test(target)) throw new Error(`unsupported binary target ${target}`);
+  const manifestResponse = await fetchImpl(`${origin}/dl/latest.json`);
+  if (!manifestResponse.ok) throw new Error(`release manifest: HTTP ${manifestResponse.status}`);
+  const manifest = await manifestResponse.json();
+  const version = manifest?.version;
+  const file = manifest?.files?.[target];
+  if (!/^\d+\.\d+\.\d+$/.test(version) ||
+      file?.name !== `flowviant-${version}-${target}` ||
+      !/^[a-f0-9]{64}$/.test(file?.sha256) ||
+      !Number.isSafeInteger(file?.bytes) || file.bytes <= 0) {
+    throw new Error('invalid release manifest');
+  }
+  if (minimumVersion && cmpVersion(version, minimumVersion) < 0) {
+    throw new Error(`release manifest still serves ${version}; waiting for ${minimumVersion}`);
+  }
+  const binaryResponse = await fetchImpl(`${origin}/dl/${version}/${file.name}`);
+  if (!binaryResponse.ok || !binaryResponse.body) throw new Error(`binary download: HTTP ${binaryResponse.status}`);
+  const parent = dirname(executable);
+  const temporaryDir = await mkdtemp(join(parent, '.flowviant-update-'));
+  const temporaryFile = join(temporaryDir, file.name);
   try {
-    self = fileURLToPath(import.meta.url);
-  } catch {
-    /* non-file URL — ignore */
+    await pipeline(Readable.fromWeb(binaryResponse.body), createWriteStream(temporaryFile, { mode: 0o755 }));
+    const digest = createHash('sha256');
+    let bytes = 0;
+    for await (const chunk of createReadStream(temporaryFile)) {
+      digest.update(chunk);
+      bytes += chunk.length;
+    }
+    if (bytes !== file.bytes || digest.digest('hex') !== file.sha256) {
+      throw new Error('downloaded binary failed SHA-256 or size verification');
+    }
+    await chmod(temporaryFile, 0o755);
+    const handle = await open(temporaryFile, 'r');
+    try { await handle.sync(); } finally { await handle.close(); }
+    await rename(temporaryFile, executable);
+    // The rename has committed. Directory fsync is best effort on filesystems
+    // that do not support it; a failure here must not claim the binary survived.
+    try {
+      const dirHandle = await open(parent, 'r');
+      try { await dirHandle.sync(); } finally { await dirHandle.close(); }
+    } catch { /* rename already succeeded */ }
+    return version;
+  } finally {
+    await rm(temporaryDir, { recursive: true, force: true }).catch(() => {});
   }
-  return /\bnpx\b/.test(ua) || /[\\/]_npx[\\/]/.test(argv1) || /[\\/]_npx[\\/]/.test(self);
 }
 
 /**
@@ -70,7 +121,7 @@ export function runningViaNpx() {
  * 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, { viaNpx = false, target = null } = {}) {
+function reexec(teardown, { viaNpx = false, viaBinary = false, target = null } = {}) {
   try {
     teardown?.();
   } catch {
@@ -84,7 +135,7 @@ function reexec(teardown, { viaNpx = false, target = null } = {}) {
   // on npx's install prompt — the same rule FLOWVIANT_REEXEC keeps below.
   const [cmd, args] = viaNpx
     ? ['npx', ['-y', 'flowviant@latest', ...process.argv.slice(2)]]
-    : [process.execPath, process.argv.slice(1)];
+    : [process.execPath, process.argv.slice(viaBinary ? 2 : 1)];
   const child = spawn(cmd, args, {
     stdio: 'inherit',
     // MARK THE CHILD AS A RESTART, not as a person typing `flowviant`.
@@ -113,6 +164,7 @@ function reexec(teardown, { viaNpx = false, target = null } = {}) {
       // the global path there is no install step whose failure would throw and
       // stop it.
       ...(target ? { FLOWVIANT_UPDATE_TARGET: target } : {}),
+      FLOWVIANT_UPDATE_FROM: VERSION,
     },
   });
   child.on('exit', (code) => process.exit(code ?? 0));
@@ -138,9 +190,18 @@ function installLatest() {
 
 /** `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() {
+export async function runUpdateCommand() {
+  if (runningCompiledBinary()) {
+    try {
+      const version = await installBinaryUpdate();
+      ok(`updated to ${version}. Relaunch \`flowviant\` to run the new version.`);
+    } catch (e) {
+      warn(`update failed (${e?.message ?? e}) — running binary untouched.`);
+    }
+    return;
+  }
   if (runningViaNpx()) {
-    note('running via npx — just relaunch with `npx flowviant@latest` to get the newest.');
+    note('running via npx — relaunch `flowviant` to get the newest.');
     return;
   }
   try {
@@ -148,7 +209,7 @@ export function runUpdateCommand() {
     installLatest();
     ok('updated. Relaunch `flowviant` to run the new version.');
   } catch (e) {
-    warn(`update failed (${e?.message ?? e}). Try: npm i -g flowviant@latest`);
+    warn(`update failed (${e?.message ?? e}). Try: ${terminalCommand('update')}`);
   }
 }
 
@@ -170,13 +231,14 @@ const INSTALL_RETRY_MS = 15 * 60_000;
  * 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 }) {
+export async 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 binary = runningCompiledBinary();
   const wantInstall = belowMin || autoUpdate;
 
   // A RESTART THAT DID NOT TAKE must not be tried again on the next poll. The
@@ -189,13 +251,35 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
       naggedFor = target;
       warn(
         `restarted to pick up ${target} but came back as ${cur} — staying put. Update by hand: ${
-          npx ? 'relaunch with `npx flowviant@latest`' : 'npm i -g flowviant@latest'
+          binary ? 'run `flowviant update`' : npx ? 'relaunch `flowviant`' : `run \`${terminalCommand('update')}\``
         }.`
       );
     }
     return false;
   }
 
+  if (wantInstall && binary) {
+    if (!safeToUpdate) {
+      if (naggedFor !== target) {
+        naggedFor = target;
+        note(`flowviant ${cur} → ${target} available — self-updating once no turn is running.`);
+      }
+      return false;
+    }
+    if (Date.now() - lastInstallFailAt < INSTALL_RETRY_MS) return false;
+    try {
+      note(`flowviant ${cur} → ${target}: downloading binary…`);
+      const installed = await installBinaryUpdate({ minimumVersion: target });
+      ok('updated — restarting into the new version.');
+      reexec(teardown, { viaBinary: true, target: installed });
+      return true;
+    } catch (e) {
+      lastInstallFailAt = Date.now();
+      warn(`binary self-update failed (${e?.message ?? e}) — running binary untouched; retrying in 15m.`);
+      return false;
+    }
+  }
+
   // UNDER NPX THERE IS NOTHING TO INSTALL — the relaunch IS the update, because
   // `npx -y flowviant@latest` resolves `latest` against the registry. Same two
   // gates as the global path: the operator's AUTO_UPDATE choice, and an idle
@@ -215,7 +299,7 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
     return true;
   }
 
-  if (wantInstall && !npx) {
+  if (wantInstall && !npx && !binary) {
     if (!safeToUpdate) {
       // Outdated but a turn is running — wait until the machine is quiet. Nag
       // once meanwhile.
@@ -265,7 +349,7 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
     } catch (e) {
       lastInstallFailAt = Date.now();
       warn(
-        `self-update failed (${e?.message ?? e}) — retrying in 15m; to fix it now: npm i -g flowviant@latest`
+        `self-update failed (${e?.message ?? e}) — retrying in 15m; to fix it now: ${terminalCommand('update')}`
       );
       return false;
     }
@@ -274,7 +358,7 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
   // 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`';
+    const how = binary ? 'run `flowviant update`' : npx ? 'relaunch `flowviant`' : `run \`${terminalCommand('update')}\``;
     if (belowMin) {
       warn(`flowviant ${cur} is below the minimum ${min} — live mode may not work. Update: ${how}.`);
     } else {

package/bin/lib/workAgentTurns.mjs

@@ -2,7 +2,8 @@
 import { limitLine } from './workAgentReview.mjs';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT, PROJECT_ID } from './config.mjs';
+import { setRuntimeLimit } from './desktopContract.mjs';
 import { git, isSafePathSegment } from './git.mjs';
 import { parseTurnResult } from './agentPlan.mjs';
 import { stashCard } from './agentCards.mjs';
@@ -813,7 +814,9 @@ export function createWorkAgentTurns({
        * sentence it failed with.
        */
       const limit = res ? null : limitLine(out);
+      if (res) setRuntimeLimit(PROJECT_ID, rt, null);
       if (limit) {
+        setRuntimeLimit(PROJECT_ID, rt, limit);
         // Every agent ON THIS CLI parks, because that account is shared: one
         // hitting the limit means all of them have. Named since 2026-09-24 —
         // a machine can hold a Claude login and a Codex login, and a Codex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "description": "Run your own coding CLIs as build agents for Flowviant — Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {
@@ -19,7 +19,6 @@
     "test": "node --test bin/lib/*.test.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "libsodium-wrappers-sumo": "^0.8.4",
     "ws": "^8.18.0"
   },