flowviant 0.101.2 → 0.102.2

package/README.md

@@ -52,6 +52,25 @@ flowviant login
 
 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.
 
+## Commands
+
+`flowviant help` lists every command, and `flowviant help <command>` (or `<command> --help`) shows one command's options. A word that isn't a command is refused with the nearest match; it never starts the daemon.
+
+| Command | What it does |
+| --- | --- |
+| `flowviant` / `flowviant start` | Serve this repo's project here |
+| `flowviant login` | Connect this repo to a project (approve the link it prints) |
+| `flowviant stop` | Stop every flowviant daemon on this computer |
+| `flowviant status` | Each project connected here: repo, running/serving, live agents |
+| `flowviant logs [-f]` | This repo's daemon log (`-f` follows it) |
+| `flowviant open` | Open this project's board in the browser |
+| `flowviant projects` | Every stored login and the repo it serves |
+| `flowviant machines` | Every computer serving your projects; a menu on a terminal |
+| `flowviant doctor` | Check git, a coding CLI, the connection and the daemon |
+| `flowviant update` | Install the newest version now |
+| `flowviant clean` | Delete kept agent worktrees |
+| `flowviant uninstall` | Remove every copy (`--purge` for logins too) |
+
 ## 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.

package/bin/cli.mjs

@@ -75,10 +75,14 @@
 // is that the login ended; wait for stdout to drain before exiting.
 const flushStdout = () => new Promise((resolve) => process.stdout.write('', resolve));
 
+// `flowviant start` is the spelled-out form of a bare `flowviant`; everything
+// below reads the start path from argv, so the word is simply dropped.
+if (process.argv[2] === 'start' && !process.argv.slice(3).some((arg) => arg === '--help' || arg === '-h')) process.argv.splice(2, 1);
+
 // 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']);
+const noCheckoutCommand = new Set(['--version', '-v', 'version', 'status', 'stop', 'uninstall', 'machines', 'projects', 'update', 'shot', 'clean', 'gh-auth', 'mcp', 'help', '--help', '-h']);
 if (dirAt >= 0 && !noCheckoutCommand.has(process.argv[2])) {
   const dir = process.argv[dirAt + 1];
   try {
@@ -121,6 +125,22 @@ if (process.argv[2] === '--version' || process.argv[2] === '-v' || process.argv[
   process.exit(0);
 }
 
+// `flowviant help`, `--help`/`-h`, and `<command> --help`. Before any command
+// runs, so asking about one never runs it (bin/lib/help.mjs has the table).
+{
+  const asksHelp = (arg) => arg === '--help' || arg === '-h';
+  const first = process.argv[2];
+  if (first === 'help' || asksHelp(first) || process.argv.slice(3).some(asksHelp)) {
+    const { findCommand, renderCommandHelp, renderHelp, unknownCommandMessage } = await import('./lib/help.mjs');
+    const topic = first === 'help' ? process.argv[3] : asksHelp(first) ? undefined : first?.startsWith('-') ? 'start' : first;
+    if (!topic) { console.log(renderHelp(VERSION)); process.exit(0); }
+    const cmd = findCommand(topic);
+    if (!cmd) { console.error(unknownCommandMessage(topic)); process.exit(1); }
+    console.log(renderCommandHelp(cmd));
+    process.exit(0);
+  }
+}
+
 if (process.argv[2] === 'login') {
   const noStart = process.argv.includes('--no-start');
   const json = process.argv.includes('--json');
@@ -150,12 +170,43 @@ if (process.argv[2] === 'login') {
 }
 
 if (process.argv[2] === 'status' && process.argv.includes('--json')) {
+  // The tray polls this every 30 s: the fixed per-user bin dirs only, no shell.
+  await (await import('./lib/loginPath.mjs')).adoptLoginPathForProcess({ shell: false });
   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 status` — the same facts, for a person.
+if (process.argv[2] === 'status') {
+  await (await import('./lib/loginPath.mjs')).adoptLoginPathForProcess();
+  const { runStatus } = await import('./lib/views.mjs');
+  await runStatus();
+  process.exit(0);
+}
+
+// `flowviant logs [-f]` — this repo's daemon log.
+if (process.argv[2] === 'logs') {
+  const { runLogs } = await import('./lib/views.mjs');
+  await runLogs(process.argv);
+  process.exit(0);
+}
+
+// `flowviant open` — this repo's board, in the browser.
+if (process.argv[2] === 'open') {
+  const { runOpen } = await import('./lib/views.mjs');
+  runOpen(process.argv);
+  process.exit(0);
+}
+
+// `flowviant doctor` — what this computer needs, checked.
+if (process.argv[2] === 'doctor') {
+  await (await import('./lib/loginPath.mjs')).adoptLoginPathForProcess();
+  const { runDoctor } = await import('./lib/views.mjs');
+  process.exit((await runDoctor()) > 0 ? 1 : 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') {
@@ -505,6 +556,19 @@ if (process.argv[2] === 'mcp') {
   process.exit(0);
 }
 
+// A WORD THAT IS NOT A COMMAND IS REFUSED, not served. Every word used to fall
+// through to here, so `flowviant hlep` started the daemon. Flags still reach
+// the start path (`--project`, `--dir`, `--json-events`, …).
+if (process.argv[2] && !process.argv[2].startsWith('-')) {
+  const { unknownCommandMessage } = await import('./lib/help.mjs');
+  console.error(unknownCommandMessage(process.argv[2]));
+  process.exit(1);
+}
+
+// Find the CLIs where the person's own terminal would: the Windows tray starts
+// this through `wsl.exe --`, which reads no shell startup file (loginPath.mjs).
+await (await import('./lib/loginPath.mjs')).adoptLoginPathForProcess();
+
 // ── WHICH PROJECT THIS START SERVES — said, asked, or refused; never guessed.
 //
 // The store holds many projects since 0.55.0 and resolution is BY REPO

package/bin/lib/help.mjs

@@ -0,0 +1,197 @@
+/**
+ * `flowviant help` — what you can type, in one screen.
+ *
+ * There was no help at all, and a bare word fell through to STARTING the
+ * daemon: `flowviant --help`, `flowviant status` and a typo like
+ * `flowviant hlep` all started serving. The owner, 2026-09-25: "everytime i
+ * type flowviant it just starts, but what if i wanted to do --help or some cmd
+ * to see what cmds are there?" So this table is the list, `help <command>`
+ * and `<command> --help` print one entry, and an unknown word is refused with
+ * the nearest command instead of being served.
+ *
+ * THE TABLE IS PINNED TO THE DISPATCH: help.test.mjs reads every
+ * `process.argv[2] === '<name>'` in cli.mjs and fails if one is missing here
+ * (or listed here and not dispatched). `hidden` rows are real commands a
+ * person rarely types (an agent calls `shot`; `mcp` manages connectors from a
+ * script); they answer `help <name>` but stay off the main screen.
+ */
+
+import { c } from './ui.mjs';
+
+export const COMMANDS = [
+  {
+    name: 'start',
+    usage: 'flowviant [start] [--project <name|id>]',
+    summary: "Serve this repo's project: run agents and Workbench tabs here. Plain `flowviant` does the same.",
+    details: [
+      'Run it inside the repository you connected. The first run in a new repo asks you to approve this computer.',
+      '--project <name|id>   serve that stored project instead of the one this repo is bound to',
+    ],
+    group: 'run',
+  },
+  {
+    name: 'login',
+    usage: 'flowviant login [--no-start]',
+    summary: 'Connect this repo to a project: approve the code in your browser, then start serving.',
+    details: ['--no-start   save the connection without starting the daemon'],
+    group: 'run',
+  },
+  {
+    name: 'stop',
+    usage: 'flowviant stop [--project <name|id>]',
+    summary: 'Stop every flowviant daemon on this computer (or just one project’s).',
+    group: 'run',
+  },
+  {
+    name: 'status',
+    usage: 'flowviant status',
+    summary: 'Each project connected here: its repo, whether it is running and serving, and its live agents.',
+    details: ['--json   the machine-readable form the Windows tray reads'],
+    group: 'look',
+  },
+  {
+    name: 'logs',
+    usage: 'flowviant logs [-f] [--project <name|id>]',
+    summary: "The daemon's log for this repo's project.",
+    details: ['-f, --follow   keep printing new lines as they are written', '-n <lines>     how many lines to show first (default 80)'],
+    group: 'look',
+  },
+  {
+    name: 'open',
+    usage: 'flowviant open [--project <name|id>]',
+    summary: "Open this project's board in your browser (prints the link too).",
+    group: 'look',
+  },
+  {
+    name: 'projects',
+    usage: 'flowviant projects',
+    summary: 'Every project this computer has a login for, and the repo each one serves.',
+    group: 'look',
+  },
+  {
+    name: 'machines',
+    usage: 'flowviant machines [--remove <id> | --forget <id>] [--yes]',
+    summary: 'Every computer that serves your projects. On a terminal, a menu to disconnect or forget one here.',
+    group: 'look',
+  },
+  {
+    name: 'doctor',
+    usage: 'flowviant doctor',
+    summary: 'Check what this computer needs: git, a signed-in CLI, a connection to Flowviant, a running daemon.',
+    group: 'look',
+  },
+  {
+    name: 'update',
+    usage: 'flowviant update',
+    summary: 'Install the newest flowviant now. It also updates itself when idle.',
+    group: 'manage',
+  },
+  {
+    name: 'clean',
+    usage: 'flowviant clean',
+    summary: 'Delete the kept agent worktrees under ~/.flowviant/worktrees. Stop the daemon first.',
+    group: 'manage',
+  },
+  {
+    name: 'uninstall',
+    usage: 'flowviant uninstall [--purge] [--yes]',
+    summary: 'Remove every flowviant copy on this computer. Logins are kept unless you add --purge.',
+    details: ['--purge   also disconnect this computer from its projects and delete ~/.flowviant', '--yes     do not ask first'],
+    group: 'manage',
+  },
+  {
+    name: 'gh-auth',
+    usage: 'flowviant gh-auth',
+    summary: 'Sign in the GitHub CLI flowviant uses to open pull requests.',
+    group: 'manage',
+  },
+  {
+    name: 'version',
+    usage: 'flowviant --version',
+    summary: 'Print the installed version.',
+    group: 'manage',
+  },
+  {
+    name: 'help',
+    usage: 'flowviant help [command]',
+    summary: 'This list, or one command in detail.',
+    group: 'manage',
+  },
+  {
+    name: 'shot',
+    usage: 'flowviant shot <url> [--out <file>]',
+    summary: 'Screenshot a running page with a headless browser (agents use it to see their change).',
+    hidden: true,
+  },
+  {
+    name: 'mcp',
+    usage: 'flowviant mcp <subcommand>',
+    summary: "Manage the project's MCP connectors from a script.",
+    hidden: true,
+  },
+];
+
+const GROUPS = [
+  ['run', 'Run'],
+  ['look', 'Look'],
+  ['manage', 'Manage'],
+];
+
+const ALIASES = { '--version': 'version', '-v': 'version', '--help': 'help', '-h': 'help' };
+
+export function findCommand(name) {
+  const key = ALIASES[name] ?? name;
+  return COMMANDS.find((cmd) => cmd.name === key) ?? null;
+}
+
+/** The main screen: every visible command, grouped, one line each. */
+export function renderHelp(version) {
+  const width = Math.max(...COMMANDS.filter((cmd) => !cmd.hidden).map((cmd) => cmd.name.length));
+  const lines = [`${c.bold('flowviant')} ${c.dim(version ? `v${version}` : '')}`.trimEnd(), '', `Usage: flowviant [command] [options]`, ''];
+  for (const [group, title] of GROUPS) {
+    lines.push(c.bold(title));
+    for (const cmd of COMMANDS.filter((row) => row.group === group && !row.hidden)) {
+      lines.push(`  ${cmd.name.padEnd(width)}   ${cmd.summary}`);
+    }
+    lines.push('');
+  }
+  lines.push(`Run ${c.cyan('flowviant help <command>')} for one command's options. Everything else happens in the app: https://app.flowviant.com`);
+  return lines.join('\n');
+}
+
+/** One command, with its options. */
+export function renderCommandHelp(cmd) {
+  const lines = [`${c.bold(cmd.usage)}`, '', cmd.summary];
+  if (cmd.details?.length) lines.push('', ...cmd.details.map((line) => `  ${line}`));
+  return lines.join('\n');
+}
+
+/** Edit distance with a swapped pair counting once ("hlep" is one slip from
+ *  "help"), for "did you mean". Small inputs only. */
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+    }
+  }
+  return d[a.length][b.length];
+}
+
+/** The nearest real command to a mistyped word, or null when nothing is close. */
+export function nearestCommand(word) {
+  const w = String(word ?? '').toLowerCase();
+  let best = null;
+  for (const cmd of COMMANDS) {
+    const d = cmd.name.startsWith(w) && w.length >= 2 ? 0 : distance(w, cmd.name);
+    if (d <= Math.max(1, Math.floor(cmd.name.length / 3)) && (!best || d < best.d)) best = { name: cmd.name, d };
+  }
+  return best?.name ?? null;
+}
+
+export function unknownCommandMessage(word) {
+  const near = nearestCommand(word);
+  return `flowviant: '${word}' is not a command.${near ? ` Did you mean \`flowviant ${near}\`?` : ''}\nRun \`flowviant help\` to see them all.`;
+}

package/bin/lib/loginPath.mjs

@@ -0,0 +1,116 @@
+/**
+ * THE PATH A PERSON'S TERMINAL HAS, for a daemon nobody started from one.
+ *
+ * Every CLI is found by name on PATH (`claude --version`, `codex`, `agy`,
+ * `gh`). A terminal's PATH comes from the shell's startup files; the Windows
+ * tray starts the daemon with `wsl.exe -d <distro> -- <binary>`, which reads
+ * none of them. That PATH is the distro's bare default, and it misses exactly
+ * where the CLIs usually live: `~/.local/bin` (Claude Code's own installer,
+ * put on PATH by ~/.profile) and version managers set up in ~/.bashrc (nvm,
+ * volta, bun). So a machine whose `claude` works in the owner's WSL terminal
+ * measured "not installed" under the tray (2026-09-25).
+ *
+ * So the daemon asks the person's login shell for its PATH once, and keeps
+ * every entry it already had FIRST (a terminal start is unchanged) with the
+ * shell's additions after it; then the usual per-user bin directories that
+ * exist. Best-effort and bounded: a shell that hangs or prints nothing costs a
+ * few seconds once, and nothing is ever removed from PATH.
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+const MARK = '__FLOWVIANT_PATH__=';
+
+/** The PATH an interactive login shell ends up with, or null. */
+export function loginShellPath({ env = process.env, exec = execFileSync, timeoutMs = 4000 } = {}) {
+  const shell = env.SHELL && env.SHELL.startsWith('/') ? env.SHELL : '/bin/bash';
+  try {
+    // -i so ~/.bashrc runs (nvm lives there, behind the "not interactive?
+    // return" guard); -l so ~/.profile runs (~/.local/bin lives there). The
+    // marker line survives whatever a startup file prints.
+    const out = String(exec(shell, ['-ilc', `printf '\\n${MARK}%s\\n' "$PATH"`], {
+      env: { ...env, TERM: 'dumb' },
+      timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }));
+    const line = out.split('\n').reverse().find((l) => l.startsWith(MARK));
+    const value = line?.slice(MARK.length).trim();
+    return value ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Per-user bin directories CLIs install into, that exist on this box. */
+export function userBinDirs({ home = homedir(), exists = existsSync, list = readdirSync } = {}) {
+  const dirs = ['.local/bin', '.npm-global/bin', '.bun/bin', '.volta/bin', '.cargo/bin'].map((d) => join(home, d));
+  // nvm: the newest installed node's bin (nvm's own "default" needs its shell
+  // function to resolve; the newest is the usual answer and only a fallback).
+  try {
+    const versions = list(join(home, '.nvm/versions/node'))
+      .filter((v) => /^v\d+\.\d+\.\d+$/.test(v))
+      .sort((a, b) => {
+        const pa = a.slice(1).split('.').map(Number);
+        const pb = b.slice(1).split('.').map(Number);
+        return pb[0] - pa[0] || pb[1] - pa[1] || pb[2] - pa[2];
+      });
+    if (versions[0]) dirs.push(join(home, '.nvm/versions/node', versions[0], 'bin'));
+  } catch { /* no nvm */ }
+  return dirs.filter((d) => exists(d));
+}
+
+/** Current entries first, then any the others add. Order-preserving, deduped. */
+export function mergePath(current, ...more) {
+  const seen = new Set();
+  const out = [];
+  for (const part of [current, ...more].flatMap((p) => (Array.isArray(p) ? p : String(p ?? '').split(':')))) {
+    if (!part || seen.has(part)) continue;
+    seen.add(part);
+    out.push(part);
+  }
+  return out.join(':');
+}
+
+/**
+ * Widen process.env.PATH in place. `shell: false` skips the login shell and
+ * only adds the fixed per-user directories (for the tray's frequent status
+ * polls, where a shell start every 30 s is not worth it).
+ */
+export function adoptLoginPath({ shell = true, env = process.env, ...deps } = {}) {
+  if (platform() === 'win32' || env.FLOWVIANT_KEEP_PATH === '1') return env.PATH;
+  const login = shell ? loginShellPath({ env, ...deps }) : null;
+  env.PATH = mergePath(env.PATH, login, userBinDirs(deps));
+  return env.PATH;
+}
+
+/**
+ * adoptLoginPath, for THIS process and every child it will start.
+ *
+ * Under Bun (the compiled binary the curl install and the tray ship) child
+ * processes are looked up and started with the environment the process
+ * STARTED with unless a spawn passes `env` — a later `process.env.PATH = …` is
+ * invisible to them (measured 2026-09-25: node found ~/.local/bin/claude after
+ * the change, the compiled binary did not). So when the PATH grew, the
+ * binary restarts itself once with it: a thin proxy, the same shape as the
+ * self-update re-exec, stdio inherited, exit code and signals passed through.
+ * Node needs none of that and adopts in place.
+ */
+export async function adoptLoginPathForProcess(opts = {}) {
+  if (process.env.FLOWVIANT_PATH_ADOPTED === '1') return;
+  const before = process.env.PATH;
+  const after = adoptLoginPath(opts);
+  if (!process.versions.bun || after === before) return;
+  const compiled = process.argv[1]?.startsWith('/$bunfs/');
+  const child = spawn(process.execPath, process.argv.slice(compiled ? 2 : 1), {
+    stdio: 'inherit',
+    env: { ...process.env, FLOWVIANT_PATH_ADOPTED: '1' },
+  });
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
+  }
+  const code = await new Promise((resolve) => child.on('exit', (status, signal) => resolve(status ?? (signal ? 1 : 0))));
+  process.exit(code);
+}

package/bin/lib/views.mjs

@@ -0,0 +1,218 @@
+/**
+ * The terminal's read-only views: `status`, `logs`, `open` and `doctor`.
+ *
+ * They decide nothing. Every decision is made in the app (the app repo's
+ * CLAUDE.md), so each of these only SHOWS what this computer knows, with the
+ * command or page that acts on it. Everything unmeasured renders nothing: a
+ * status line for a server that did not answer is left out, never guessed.
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { FLEET_URL, USER_AGENT, VERSION } from './config.mjs';
+import { detectRepoRoot, listStoredProjects, projectLabel, resolveStoredCredential } from './credentials.mjs';
+import { daemonLogPath, desktopStatusRemote, installChannel } from './desktopContract.mjs';
+import { daemonRunningFor } from './instance.mjs';
+import { agoFrom } from './machines.mjs';
+import { detectRuntimes } from './runtimes.mjs';
+import { c } from './ui.mjs';
+
+const APP_URL = process.env.FLOWVIANT_APP_URL || 'https://app.flowviant.com';
+
+function olderVersion(version, latest) {
+  const parse = (v) => /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? ''))?.slice(1, 4).map(Number);
+  const a = parse(version);
+  const b = parse(latest);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
+  return false;
+}
+
+function agentLine(agent, now) {
+  if (agent.asks) return `${agent.name} · ${c.yellow('asks you a question')}`;
+  const since = agent.status === 'working' && !agent.parked && agent.since ? Date.parse(agent.since) : NaN;
+  const minutes = Number.isFinite(since) ? Math.max(0, Math.floor((now - since) / 60_000)) : null;
+  const took = minutes == null ? '' : ` ${minutes < 60 ? `${minutes}m` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`}`;
+  const word = agent.parked ? 'parked' : agent.status;
+  const cards = `${agent.delivered} of ${agent.total} ${agent.total === 1 ? 'card' : 'cards'}${agent.delivered ? ' delivered' : ''}`;
+  return `${agent.name} · ${word === 'working' ? c.blue(`working${took}`) : word} · ${cards}`;
+}
+
+/** `flowviant status`, rendered from the same document `status --json --remote` prints. */
+export function renderStatus(status, { now = Date.now() } = {}) {
+  const lines = [`${c.bold('flowviant')} ${c.dim(`v${status.version} · ${status.installChannel}`)}`, ''];
+  if (status.projects.length === 0) {
+    lines.push('No project is connected on this computer yet.', `Run ${c.cyan('flowviant login')} inside your repository.`, '');
+  }
+  for (const project of status.projects) {
+    const remote = project.remote ?? null;
+    const label = (key, value) => `  ${c.dim(key.padEnd(8))}  ${value}`;
+    lines.push(`${c.bold(project.name ?? project.id)}  ${c.dim(`${project.id.slice(0, 8)}…`)}`);
+    lines.push(label('repo', project.dir ?? c.dim('not bound yet — the first start in its repo binds it')));
+    const role = remote?.role ?? null;
+    if (project.running === false) {
+      lines.push(label('here', `not running — run ${c.cyan('flowviant')} in that repo`));
+    } else if (project.running === true) {
+      const serves = role === 'serving' ? c.green('serving')
+        : role === 'inactive' ? `inactive${remote?.servingBoxName ? ` — ${remote.servingBoxName} serves this project` : ''}`
+        : project.holder === 'serving' ? c.green('serving') : null;
+      lines.push(label('here', serves ? `running · ${serves}` : 'running'));
+    }
+    const heard = agoFrom(project.lastPoll, now);
+    if (heard) lines.push(label('polled', heard));
+    const agents = remote?.agents ?? null;
+    if (agents && agents.length > 0) {
+      agents.forEach((agent, i) => lines.push(label(i === 0 ? 'agents' : '', agentLine(agent, now))));
+    }
+    if (remote?.pressure?.reason) lines.push(label('waiting', `Waiting for the machine — ${remote.pressure.reason}.`));
+    for (const rt of project.runtimes ?? []) {
+      if (rt.parkedByLimit && rt.message) lines.push(label('limit', `${rt.id} hit its limit: “${rt.message}”`));
+    }
+    const version = remote?.daemonVersion ?? status.version;
+    if (remote?.latest && olderVersion(version, remote.latest)) {
+      lines.push(label('update', `flowviant ${remote.latest} is out; this computer runs ${version}. It updates itself when idle.`));
+    }
+    lines.push('');
+  }
+  const clis = (status.runtimes ?? []).map((rt) => `${rt.id} ${rt.installed ? (rt.version ?? 'installed') : c.dim('not installed')}`);
+  if (clis.length) lines.push(`${c.dim('CLIs')}      ${clis.join(' · ')}`);
+  return lines.join('\n').trimEnd();
+}
+
+export async function runStatus() {
+  console.log(renderStatus(await desktopStatusRemote({ log: () => {} })));
+}
+
+/** Which stored project a `logs`/`open` means: `--project`, else this repo's,
+ *  else the only one. Several and none are answered in words, never guessed. */
+export function resolveProjectForView(argv = process.argv, cwd = process.cwd()) {
+  const resolved = resolveStoredCredential(argv, cwd);
+  if (resolved.entry) return { entry: resolved.entry };
+  if (resolved.error) return { message: `error: ${resolved.error}` };
+  const entries = listStoredProjects();
+  if (entries.length === 0) return { message: `No project is connected on this computer yet. Run \`flowviant login\` inside your repository.` };
+  return {
+    message: `Several projects are connected here, and this folder is not one of their repos. Pick one with --project:\n${
+      entries.map((e) => `  ${projectLabel(e)}  ${c.dim(e.projectId)}`).join('\n')}`,
+  };
+}
+
+/** The last `count` lines of a file, read from its end. */
+export function tailLines(path, count) {
+  const size = statSync(path).size;
+  const want = Math.min(size, 256 * 1024);
+  const buf = Buffer.alloc(want);
+  const fd = openSync(path, 'r');
+  try { readSync(fd, buf, 0, want, size - want); } finally { closeSync(fd); }
+  const lines = buf.toString('utf8').split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  if (want < size) lines.shift(); // the first line is cut mid-way
+  return { text: lines.slice(-count).join('\n'), size };
+}
+
+export async function runLogs(argv = process.argv) {
+  const which = resolveProjectForView(argv);
+  if (!which.entry) { console.error(which.message); process.exit(1); }
+  const path = daemonLogPath(which.entry.projectId);
+  const at = argv.indexOf('-n');
+  const count = at >= 0 && Number(argv[at + 1]) > 0 ? Math.floor(Number(argv[at + 1])) : 80;
+  const follow = argv.includes('-f') || argv.includes('--follow');
+  if (!existsSync(path)) {
+    console.log(`No log yet for ${projectLabel(which.entry)}. It starts when the daemon first runs: ${c.cyan('flowviant')} in its repo.`);
+    if (!follow) return;
+  } else {
+    const { text } = tailLines(path, count);
+    if (text) console.log(text);
+  }
+  if (!follow) return;
+  // Poll rather than fs.watch: the daemon rotates the file (a rename), and a
+  // watch on the old inode would go quiet exactly then.
+  let offset = existsSync(path) ? statSync(path).size : 0;
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    if (!existsSync(path)) continue;
+    const size = statSync(path).size;
+    if (size < offset) offset = 0; // rotated
+    if (size === offset) continue;
+    const buf = Buffer.alloc(size - offset);
+    const fd = openSync(path, 'r');
+    try { readSync(fd, buf, 0, buf.length, offset); } finally { closeSync(fd); }
+    process.stdout.write(buf);
+    offset = size;
+  }
+}
+
+/** The command that opens a URL in this computer's browser. Inside WSL that is
+ *  Windows' own browser, reached through explorer.exe. */
+export function browserCommand(url, { platform = process.platform, env = process.env } = {}) {
+  if (platform === 'darwin') return ['open', [url]];
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]];
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return ['explorer.exe', [url]];
+  return ['xdg-open', [url]];
+}
+
+export function runOpen(argv = process.argv) {
+  const which = resolveProjectForView(argv);
+  if (!which.entry) { console.error(which.message); process.exit(1); }
+  const url = `${APP_URL}/projects/${encodeURIComponent(which.entry.projectId)}/board`;
+  console.log(url);
+  const [cmd, args] = browserCommand(url);
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {}); // no browser here: the printed link is the answer
+    child.unref();
+  } catch { /* the link above is enough */ }
+}
+
+/** One doctor line: ✓ measured fine, ✗ measured wrong (with what to do), · unknown. */
+function check(state, text, fix) {
+  const mark = state === true ? c.green('✓') : state === false ? c.red('✗') : c.dim('·');
+  return `${mark} ${text}${state === false && fix ? `\n    ${c.dim(fix)}` : ''}`;
+}
+
+export async function runDoctor({ cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  const lines = [`${c.bold('flowviant')} ${c.dim(`v${VERSION} · ${installChannel()}`)}`, ''];
+  let failed = 0;
+  const add = (state, text, fix) => { if (state === false) failed++; lines.push(check(state, text, fix)); };
+
+  let git = null;
+  try { git = String(execFileSync('git', ['--version'], { timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })).trim(); } catch { /* absent */ }
+  add(Boolean(git), git ?? 'git is not installed', 'Install git; agents work in git worktrees.');
+
+  const installed = detectRuntimes().filter((rt) => rt.installed);
+  add(installed.length > 0,
+    installed.length ? `CLIs here: ${installed.map((rt) => `${rt.id}${rt.version ? ` ${rt.version}` : ''}`).join(', ')}` : 'No coding CLI found (Claude Code, Codex or Antigravity)',
+    'Install Claude Code or Codex on this computer and sign in to it; agents run through its login.');
+
+  const repo = detectRepoRoot(cwd);
+  add(Boolean(repo), repo ? `This folder is the repo ${repo}` : 'This folder is not inside a git repository',
+    'Run flowviant inside the repository you want agents to work in.');
+
+  const resolved = resolveStoredCredential(process.argv, cwd);
+  const entry = resolved.entry ?? null;
+  add(entry ? true : repo ? false : null,
+    entry ? `Connected to ${projectLabel(entry)}` : 'This repo is not connected to a project',
+    'Run `flowviant login` here and approve it in your browser.');
+
+  const health = String(FLEET_URL).replace(/\/api\/.*$/, '/health');
+  let reach = null;
+  try {
+    const res = await fetchImpl(health, { headers: { 'User-Agent': USER_AGENT }, signal: AbortSignal.timeout(5000) });
+    reach = res.ok ? true : `HTTP ${res.status}`;
+  } catch (error) { reach = String(error?.message ?? error); }
+  add(reach === true, reach === true ? 'Flowviant is reachable' : `Flowviant is not reachable (${reach})`,
+    'Check this computer’s internet connection or proxy.');
+
+  if (entry) {
+    const running = daemonRunningFor(entry.fleetToken);
+    // No lock file is UNKNOWN (an older daemon runs without one), so only a
+    // dead lock holder is said to be "not running".
+    add(running === true ? true : null,
+      running === true ? 'The daemon is running for this project'
+        : running === false ? 'The daemon is not running — start it with `flowviant`'
+        : 'No daemon has registered for this project here — start one with `flowviant`');
+  }
+  lines.push('', failed ? `${failed} thing${failed === 1 ? '' : 's'} to fix.` : 'Nothing to fix.');
+  console.log(lines.join('\n'));
+  return failed;
+}

package/package.json

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