flowviant 0.99.0 → 0.101.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,43 @@ 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.
+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.
 
-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.
+## Uninstall
+
+`flowviant uninstall` stops local daemons and removes installed copies. It keeps logins and local state in `~/.flowviant`, so reinstalling resumes them. Use `flowviant uninstall --purge` to disconnect this box from stored projects and delete that local data too. Add `--yes` to skip confirmation.
 
 ## 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 +132,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', 'uninstall', '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,11 +230,32 @@ 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);
 }
 
+if (process.argv[2] === 'uninstall') {
+  const { runUninstall } = await import('./lib/uninstall.mjs');
+  const { askWithTimeout } = await import('./lib/tty.mjs');
+  const result = await runUninstall({
+    others: process.argv.includes('--others'),
+    purge: process.argv.includes('--purge'),
+    yes: process.argv.includes('--yes'),
+    json: process.argv.includes('--json'),
+    prompt: (query) => askWithTimeout(query, undefined, process.stderr),
+  });
+  process.exit(result.ok ? 0 : 1);
+}
+
 // `flowviant projects` — every project this box has a credential for, which
 // repo each is bound to, and which the legacy mirror points at. Needs no
 // network: it reads the store, which is the exact thing a confused person is
@@ -206,7 +265,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 +286,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 +326,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 +355,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 +463,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 +538,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 +565,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 +593,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 +677,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 +724,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);
+    };
+  }
+}