flowviant 0.101.0 → 0.102.0

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

@@ -70,10 +70,19 @@
  * env (the box keypair, the uplink scrubber, the env-comparison scan) + vault
  * (the knowledge wiki, not secrets), resources, deploy, shot.
  */
+// The tray app reads `login --json` through a pipe (wsl.exe). A line written
+// just before process.exit() can be dropped there, and then all the tray knows
+// 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 {
@@ -83,6 +92,7 @@ if (dirAt >= 0 && !noCheckoutCommand.has(process.argv[2])) {
     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}`);
+    await flushStdout();
     process.exit(1);
   }
 }
@@ -115,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');
@@ -122,6 +148,7 @@ if (process.argv[2] === 'login') {
   // 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.
+  if (json) await flushStdout();
   if (!login?.saved) process.exit(1); // refused: the directory already serves another project
   if (noStart) process.exit(0);
   // Re-exec as a plain `flowviant` rather than falling through. config.mjs reads
@@ -149,6 +176,33 @@ if (process.argv[2] === 'status' && process.argv.includes('--json')) {
   process.exit(0);
 }
 
+// `flowviant status` — the same facts, for a person.
+if (process.argv[2] === 'status') {
+  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') {
+  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') {
@@ -498,6 +552,15 @@ 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);
+}
+
 // ── 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/login.mjs

@@ -51,10 +51,14 @@ export async function runLogin({ thenStart = false, json = false, dir = process.
   // 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.
-  if (json) event({ event: 'open_url', url: APP_URL, code: pretty });
+  // `/connect?code=` (2026-09-25) takes the code, asks which project, and
+  // approves: the code no longer has to be carried by hand into a project's
+  // Connect a machine panel, which is where people got lost.
+  const approveUrl = `${APP_URL}/connect?code=${encodeURIComponent(pretty)}`;
+  if (json) event({ event: 'open_url', url: approveUrl, 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`);
+    console.log(`  Open ${c.cyan(approveUrl)}`);
+    console.log(`  and approve this computer for your project. Check the code there is ${c.bold(c.green(pretty))}.\n`);
     info('waiting for you to approve…');
   }
 

package/bin/lib/uninstall.mjs

@@ -259,7 +259,8 @@ export async function runUninstall(options = {}) {
     if (others && c.kind === 'path-line' && plan.copies.some((copy) => copy.kind === 'binary' && copy.current && c.block === exactBlock(dirname(copy.path), c.path))) reason = 'needed by the running binary';
     if (reason) {
       result.skipped.push({ ...item, reason });
-      if (!json) line(`skipped ${c.path}: ${reason}`);
+      // The copy doing the work is not news; every other skip is.
+      if (!json && reason !== 'running copy') line(`skipped ${c.path}: ${reason}`);
       continue;
     }
     try {
@@ -269,7 +270,7 @@ export async function runUninstall(options = {}) {
       else if (c.kind === 'path-line') removePathBlock(o, c.path, c.block);
       else o.fs.rmSync(c.removal, { recursive: c.kind === 'npx-cache', force: true });
       result.removed.push(item);
-      if (!json) line(`removed ${c.path}`);
+      if (!json) line(c.kind === 'path-line' ? `removed the flowviant PATH line from ${c.path}` : `removed ${c.path}`);
     } catch (e) { result.errors.push(`${c.path}: ${errorWords(e)}`); }
   }
   if (purge && !others) {

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.0",
+  "version": "0.102.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": {