flowviant 0.99.0 → 0.101.0

package/bin/lib/fleet.mjs

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

package/bin/lib/instance.mjs

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

package/bin/lib/launchCommand.mjs

@@ -0,0 +1,23 @@
+import { fileURLToPath } from 'node:url';
+
+/** The updater and terminal advice share one detection of the launch channel. */
+export function runningViaNpx() {
+  const ua = process.env.npm_config_user_agent || '';
+  const argv1 = process.argv[1] || '';
+  let self = '';
+  try {
+    self = fileURLToPath(import.meta.url);
+  } catch {
+    /* non-file URL — ignore */
+  }
+  return /\bnpx\b/.test(ua) || /[\\/]_npx[\\/]/.test(argv1) || /[\\/]_npx[\\/]/.test(self);
+}
+
+/** Name the command that launched this process when giving a person a next step. */
+export function launchCommand() {
+  return 'flowviant';
+}
+
+export function terminalCommand(args = '') {
+  return `${launchCommand()}${args ? ` ${args}` : ''}`;
+}

package/bin/lib/login.mjs

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

package/bin/lib/machines.mjs

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

package/bin/lib/mcp-cli.mjs

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

package/bin/lib/preflight.mjs

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

package/bin/lib/tty.mjs

@@ -112,7 +112,7 @@ export function boundedTimer(timeoutMs, fire) {
  * answer everywhere (the binding confirm serves unbound; the project picker
  * refuses, exactly as it does headless).
  */
-export async function askWithTimeout(query, timeoutMs) {
+export async function askWithTimeout(query, timeoutMs, output = process.stdout) {
   const noop = () => {};
   // Replacing the DEFAULT disposition is the whole point — an empty handler is
   // enough, and it is what keeps the timer below able to run at all.
@@ -120,7 +120,7 @@ export async function askWithTimeout(query, timeoutMs) {
   process.on('SIGTTOU', noop);
   const rl = (await import('node:readline/promises')).createInterface({
     input: process.stdin,
-    output: process.stdout,
+    output,
   });
   const ac = new AbortController();
   const timer = boundedTimer(timeoutMs, () => ac.abort());