flowviant 0.103.0 → 0.104.0

package/bin/lib/commandSpecs.mjs

@@ -0,0 +1,173 @@
+/**
+ * EVERY TERMINAL COMMAND, ONCE (2026-09-26, SOLID F054).
+ *
+ * A command used to live in three inventories: help.mjs's table, cli.mjs's
+ * `noCheckoutCommand` set (whether `--dir` moves the process into the
+ * checkout before config.mjs reads the project bound to cwd), and cli.mjs's
+ * chain of `process.argv[2] === '<name>'` conditionals — and help.test.mjs
+ * only kept two of them aligned. This table is the one list: help.mjs renders
+ * it, cli.mjs asks `commandUsesCheckout` for the --dir policy and dispatches
+ * by `findCommand(...).name` to a named handler in its HANDLERS map.
+ * help.test.mjs pins that every row has exactly one handler (or is one of the
+ * BUILTIN rows cli.mjs answers before dispatch).
+ *
+ * NO IMPORTS, on purpose: cli.mjs reads this before `--dir` is applied, which
+ * is before config.mjs may load.
+ *
+ * `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. `usesCheckout` is true where
+ * the command works on the checkout `--dir` names.
+ */
+
+export const COMMANDS = [
+  {
+    name: 'start',
+    usesCheckout: true,
+    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',
+    usesCheckout: true,
+    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',
+    usesCheckout: false,
+    usage: 'flowviant stop [--project <name|id>]',
+    summary: 'Stop every flowviant daemon on this computer (or just one project’s).',
+    group: 'run',
+  },
+  {
+    name: 'status',
+    usesCheckout: false,
+    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',
+    usesCheckout: true,
+    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',
+    usesCheckout: true,
+    usage: 'flowviant open [--project <name|id>]',
+    summary: "Open this project's board in your browser (prints the link too).",
+    group: 'look',
+  },
+  {
+    name: 'projects',
+    usesCheckout: false,
+    usage: 'flowviant projects',
+    summary: 'Every project this computer has a login for, and the repo each one serves.',
+    group: 'look',
+  },
+  {
+    name: 'machines',
+    usesCheckout: false,
+    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',
+    usesCheckout: true,
+    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',
+    usesCheckout: false,
+    usage: 'flowviant update',
+    summary: 'Install the newest flowviant now. It also updates itself when idle.',
+    group: 'manage',
+  },
+  {
+    name: 'clean',
+    usesCheckout: false,
+    usage: 'flowviant clean',
+    summary: 'Delete the kept agent worktrees under ~/.flowviant/worktrees. Stop the daemon first.',
+    group: 'manage',
+  },
+  {
+    name: 'uninstall',
+    usesCheckout: false,
+    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',
+    usesCheckout: false,
+    usage: 'flowviant gh-auth',
+    summary: 'Sign in the GitHub CLI flowviant uses to open pull requests.',
+    group: 'manage',
+  },
+  {
+    name: 'version',
+    usesCheckout: false,
+    usage: 'flowviant --version',
+    summary: 'Print the installed version.',
+    group: 'manage',
+  },
+  {
+    name: 'help',
+    usesCheckout: false,
+    usage: 'flowviant help [command]',
+    summary: 'This list, or one command in detail.',
+    group: 'manage',
+  },
+  {
+    name: 'shot',
+    usesCheckout: false,
+    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',
+    usesCheckout: false,
+    usage: 'flowviant mcp <subcommand>',
+    summary: "Manage the project's MCP connectors from a script.",
+    hidden: true,
+  },
+];
+
+/** Rows cli.mjs answers itself rather than through HANDLERS: `version` and
+ *  `help` before any command runs, `start` as the fall-through daemon path. */
+export const BUILTIN_COMMANDS = ['start', 'help', 'version'];
+
+export 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;
+}
+
+/**
+ * Does `--dir` move the process into the checkout before this word runs?
+ * Anything the table does not name — a flag such as `--project`, or no word at
+ * all — is the start path, which serves the checkout. (An unknown word is
+ * refused after the move, exactly as before.)
+ */
+export function commandUsesCheckout(word) {
+  const cmd = findCommand(word);
+  return cmd ? cmd.usesCheckout : true;
+}

package/bin/lib/config.mjs

@@ -4,7 +4,8 @@ import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cpus, hostname, totalmem } from 'node:os';
+import { hostname } from 'node:os';
+import { measureMachineLimits } from './machineLimits.mjs';
 
 // Read the daemon's version from its OWN package.json (always shipped in the npm
 // tarball) — never hardcode it. The hardcoded constant drifted: it sat at
@@ -36,7 +37,7 @@ export const MODEL = process.env.FLOWVIANT_MODEL || 'opus';
 // no-env-var path. An explicit --fleet flag or FLOWVIANT_FLEET env still wins.
 // Since 0.55.0 the store holds MANY projects and resolution is BY REPO — see
 // credentials.mjs for the whole rule. `CREDENTIAL` carries the resolution so
-// cli.mjs can turn an ambiguity into a picker instead of a guess.
+// startProject.mjs can turn an ambiguity into a picker instead of a guess.
 import { resolveStoredCredential } from './credentials.mjs';
 export const CREDENTIAL = resolveStoredCredential();
 
@@ -77,42 +78,10 @@ export const STREAM_URL =
   FLEET_URL.replace(/\/agents(\/?)$/, '/stream$1').replace(/^http/, 'ws');
 export const POLL_SECONDS = Number(process.env.POLL_SECONDS || 20);
 
-/**
- * What this machine can actually be given, read from the machine.
- *
- * `os.totalmem()` and `cpus().length` report the HOST inside a container: a
- * 4GB container on a 256GB box reads 256GB and cheerfully oversubscribes until
- * the OOM killer picks a victim — which, because it picks by resident size, is
- * frequently not the task that caused it. cgroup v2 publishes the real limits,
- * so read those first and treat the os module as the fallback it is.
- */
-function machineLimits() {
-  const readCgroup = (f) => {
-    try {
-      return readFileSync(`/sys/fs/cgroup/${f}`, 'utf8').trim();
-    } catch {
-      return null;
-    }
-  };
-  let memBytes = totalmem();
-  const memMax = readCgroup('memory.max');
-  if (memMax && memMax !== 'max') {
-    const n = Number(memMax);
-    if (Number.isFinite(n) && n > 0) memBytes = Math.min(memBytes, n);
-  }
-  let cores = cpus().length || 2;
-  // "<quota> <period>" in microseconds, or "max <period>" for unlimited.
-  const cpuMax = readCgroup('cpu.max');
-  if (cpuMax && !cpuMax.startsWith('max')) {
-    const [q, p] = cpuMax.split(/\s+/).map(Number);
-    if (Number.isFinite(q) && Number.isFinite(p) && p > 0) {
-      cores = Math.max(1, Math.min(cores, Math.floor(q / p)));
-    }
-  }
-  return { memBytes, cores };
-}
-
-export const MACHINE = machineLimits();
+// What this machine can actually be given — the cgroup's limits before the
+// host's. The rule and its reader live in machineLimits.mjs; this is the
+// measured result every importer of `MACHINE` has always read.
+export const MACHINE = measureMachineLimits();
 
 /**
  * How many tasks THIS MACHINE will build at once.
@@ -167,7 +136,7 @@ export const MACHINE = machineLimits();
  *    behind it. Most do not — an agent turn is a CLI that reads, edits and
  *    commits, and it is API-bound for nearly all of its life. 1GB per turn with
  *    the same 2GB held back for the operating system is the honest sizing, and
- *    the PRESSURE guard (resources.mjs) is what catches the turn that really
+ *    the PRESSURE guard (pressurePolicy.mjs) is what catches the turn that really
  *    does hold gigabytes: it measures at the moment of spawning, which is a
  *    thing a static divisor cannot do.
  *  · `cores − 1` is the laptop assumption this comment already claims to have
@@ -290,7 +259,7 @@ export const PROCESS_STARTED_AT = new Date(
 // --tokens) stood beside it and carried WORKER tokens into the pre-daemon loop;
 // that principal owns zero tools since dispatch was deleted, and the kind can no
 // longer be minted, so the plumbing went with the entrypoint (2026-08-19).
-// `let`, because ES named imports are LIVE bindings: when cli.mjs answers an
+// `let`, because ES named imports are LIVE bindings: when startProject.mjs answers an
 // ambiguous store with a picker, adoptStoredCredential updates every importer
 // before the daemon touches the network. Everything before that point (the
 // resolution, the flags) is settled synchronously at import, as it always was.
@@ -325,7 +294,7 @@ export let FLEET_TOKEN =
  * hashes would render as a confident "these boxes differ" beside a box holding
  * the identical value. Ignorance renders nothing.
  *
- * `let`, for the same reason `FLEET_TOKEN` is: when cli.mjs answers an
+ * `let`, for the same reason `FLEET_TOKEN` is: when startProject.mjs answers an
  * ambiguous store with a picker, `adoptStoredCredential` is what settles both,
  * and ES named imports are LIVE bindings so every importer sees the answer.
  * A frozen copy read at import would salt a picked project's report with null
@@ -356,7 +325,7 @@ export function storedCredentialInUse() {
   return Boolean(CREDENTIAL.entry?.fleetToken) && CREDENTIAL.entry.fleetToken === FLEET_TOKEN;
 }
 
-/** cli.mjs's picker chose. Must run BEFORE runFleetDaemon — nothing here
+/** startProject.mjs's picker chose. Must run BEFORE runFleetDaemon — nothing here
  *  re-authenticates a connection already made. */
 export function adoptStoredCredential(entry) {
   if (entry?.fleetToken) FLEET_TOKEN = entry.fleetToken;

package/bin/lib/credentialDate.mjs

@@ -0,0 +1,22 @@
+/**
+ * WHEN A CREDENTIAL WAS STORED, as a date a person can match against their own
+ * memory of setting it up ("I connected that one last month") — `Sep 16`.
+ *
+ * One home because three terminal sites spelled it independently (SOLID audit
+ * 2026-09-26, F168): the collision suffix in `credentials.mjs`
+ * (`projectRowLabel`), the `machines` listing, and `flowviant projects` in
+ * cli.mjs — each with its own copy of the en-US short-month format and its own
+ * decision about when the clause is dropped. The decision is the part that
+ * matters and is stated once here: ABSENT OR UNPARSEABLE STAYS ABSENT (null).
+ * A credential stored before `savedAt` existed has no date, and inventing one
+ * would be the listing asserting a day nobody recorded.
+ *
+ * Each caller places the returned date in its own sentence; only the date is
+ * shared. A leaf module on purpose: `credentials.mjs` imports it, so it must
+ * import nothing back (a cycle through the credential store).
+ */
+export function connectedOn(iso) {
+  const t = Date.parse(iso ?? '');
+  if (Number.isNaN(t)) return null;
+  return new Date(t).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}

package/bin/lib/credentials.mjs

@@ -33,7 +33,7 @@
  *                                 binds it (headless keeps the old behaviour —
  *                                 a systemd restart must not hang on a prompt).
  *   anything else                 a CHOICE, never a guess: the CLI lists every
- *                                 stored project and asks (cli.mjs), or — with
+ *                                 stored project and asks (startProject.mjs), or — with
  *                                 no TTY — refuses in words that name them all.
  *
  * The repoRoot binding is a SAFETY line, not bookkeeping: serving project X
@@ -49,7 +49,9 @@ import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { printable } from './printable.mjs';
+import { connectedOn } from './credentialDate.mjs';
 import { terminalCommand } from './launchCommand.mjs';
+import { samePath } from './repoPath.mjs';
 
 const CRED_DIR = join(homedir(), '.flowviant');
 const CRED_FILE = join(CRED_DIR, 'credentials.json');
@@ -86,19 +88,6 @@ export function detectRepoRoot(cwd = process.cwd()) {
   }
 }
 
-/** Same directory whatever it is spelled as — the instance.mjs rule. */
-function samePath(a, b) {
-  if (!a || !b) return false;
-  const norm = (v) => {
-    try {
-      return realpathSync(v);
-    } catch {
-      return String(v).replace(/\/+$/, '');
-    }
-  };
-  return norm(a) === norm(b);
-}
-
 /**
  * Every stored project, NORMALIZED: the v2 map, plus the legacy trio surfaced
  * as an entry when no map row carries its token (a pre-0.55.0 file is one
@@ -187,11 +176,8 @@ export function projectRowLabel(e, entries) {
     Array.isArray(entries) &&
     entries.filter((x) => x !== e && projectLabel(x) === label).length > 0;
   if (!collides) return label;
-  const d = e?.savedAt ? new Date(e.savedAt) : null;
-  const when =
-    d && !Number.isNaN(d.getTime())
-      ? `, connected ${d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })}`
-      : '';
+  const connected = connectedOn(e?.savedAt);
+  const when = connected ? `, connected ${connected}` : '';
   return `${label} (id ${String(e?.projectId ?? '').slice(0, 8)}…${when})`;
 }
 
@@ -363,6 +349,19 @@ export function selectStoredProject(projectId, { bindRepoRoot } = {}) {
   });
 }
 
+/**
+ * WHICH STORED PROJECTS AN ID NAMES — the full project id, or a prefix of at
+ * least six characters. The one spelling of the boundary for both the lookup
+ * (`matchStoredProject`, which falls back to a name when no id matches) and
+ * the destructive forget (`forgetStoredProject`, which never matches a name):
+ * two copies of a rule that decides which credential gets DELETED is a second
+ * place for the boundary to drift (SOLID audit 2026-09-26, F169). Returns every
+ * hit — each caller refuses more than one in its own words.
+ */
+function storedProjectsById(q, entries) {
+  return (entries ?? []).filter((e) => e.projectId === q || (q.length >= 6 && e.projectId.startsWith(q)));
+}
+
 /**
  * FORGET A STORED CREDENTIAL — `flowviant machines --forget <id>` (2026-09-19).
  *
@@ -386,9 +385,7 @@ export function selectStoredProject(projectId, { bindRepoRoot } = {}) {
 export function forgetStoredProject(ref) {
   const q = String(ref ?? '').trim();
   if (!q) return { error: 'empty --forget value' };
-  const hits = listStoredProjects().filter(
-    (e) => e.projectId === q || (q.length >= 6 && e.projectId.startsWith(q))
-  );
+  const hits = storedProjectsById(q, listStoredProjects());
   if (hits.length === 0) return { error: `no stored project matches "${q}"` };
   if (hits.length > 1) {
     return { error: `"${q}" matches ${hits.length} stored projects — use the full project id` };
@@ -431,9 +428,7 @@ export function matchStoredProject(ref) {
   const entries = listStoredProjects();
   const q = String(ref ?? '').trim();
   if (!q) return { error: 'empty --project value' };
-  const byId = entries.filter(
-    (e) => e.projectId === q || (q.length >= 6 && e.projectId.startsWith(q))
-  );
+  const byId = storedProjectsById(q, entries);
   const byName = entries.filter((e) => e.name && e.name.toLowerCase() === q.toLowerCase());
   const hits = byId.length > 0 ? byId : byName;
   if (hits.length === 1) return { entry: hits[0] };
@@ -447,7 +442,7 @@ export function matchStoredProject(ref) {
  * this returns. Shapes:
  *   { entry, source: 'project-flag' | 'repo' | 'only', needsConfirm? }
  *   { choices, reason: 'no-match' | 'multiple-bound' | 'outside-repo', repoRoot }
- *     (`multiple-bound` is a REFUSAL in cli.mjs since 2026-09-23 — a directory
+ *     (`multiple-bound` is a REFUSAL on the start path (startProject.mjs) since 2026-09-23 — a directory
  *     serves one project — and never a picker; the shape is kept because it
  *     names the projects the refusal has to print)
  *   { none: true }

package/bin/lib/daemonLogging.mjs

@@ -0,0 +1,55 @@
+/**
+ * THE DAEMON'S OUTPUT: bounded per-project logs and the desktop JSONL events
+ * (2026-09-26, SOLID F061).
+ *
+ * Split out of desktopContract.mjs, which also built the status readout — so a
+ * change to how the daemon writes its output (console redirection, log
+ * rotation, the JSON event stream) and a change to the status wire edited one
+ * module. This one owns output only; it is handed the log path and never
+ * decides where per-project files live (daemonState.mjs does).
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { format } from 'node:util';
+
+export const MAX_DAEMON_LOG_BYTES = 2 * 1024 * 1024;
+
+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. Every
+ * line is also appended to `logPath`, rotated at MAX_DAEMON_LOG_BYTES. */
+export function installDaemonLogging(logPath, { jsonEvents = false } = {}) {
+  if (!logPath) 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 };
+  for (const method of Object.keys(original)) {
+    console[method] = (...args) => {
+      const line = format(...args);
+      try {
+        mkdirSync(dirname(logPath), { recursive: true });
+        const encoded = Buffer.from(`${line}\n`);
+        const tail = Buffer.from('\n[truncated]\n');
+        const chunk = encoded.length > MAX_DAEMON_LOG_BYTES
+          ? Buffer.concat([encoded.subarray(0, MAX_DAEMON_LOG_BYTES - tail.length), tail])
+          : encoded;
+        let size = 0;
+        try { size = statSync(logPath).size; } catch { /* new file */ }
+        if (size + chunk.length > MAX_DAEMON_LOG_BYTES) {
+          try { renameSync(logPath, `${logPath}.1`); } catch { /* no old log */ }
+        }
+        appendFileSync(logPath, chunk, { mode: 0o600 });
+      } catch { /* logging must never stop service */ }
+      if (jsonEvents) process.stderr.write(`${line}\n`);
+      else original[method](...args);
+    };
+  }
+}

package/bin/lib/daemonState.mjs

@@ -0,0 +1,64 @@
+/**
+ * WHERE A PROJECT'S DAEMON KEEPS ITS LOCAL READOUT, AND WHAT IT WRITES THERE
+ * (2026-09-26, SOLID F061).
+ *
+ * The per-project state file (holder, last poll, CLI limits) and log file
+ * under ~/.flowviant, named by a hash of the project id. Split out of
+ * desktopContract.mjs so the status readout only READS this, and so the
+ * daemon's writers (fleet.mjs, workAgentTurnExecution.mjs) do not import the status
+ * builder. A limit change is announced as a machine event (daemonLogging.mjs).
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { emitMachineEvent } from './daemonLogging.mjs';
+import { instanceLockPath } from './instance.mjs';
+
+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`);
+
+export function readDaemonState(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 = readDaemonState(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 = readDaemonState(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;
+}
+
+/** The pid in the instance lock for this credential, or null. */
+export function daemonLockPid(token) {
+  try {
+    return JSON.parse(readFileSync(instanceLockPath(token), 'utf8')).pid;
+  } catch { return null; }
+}