flowviant 0.97.0 → 0.100.0

package/bin/lib/landed.mjs

@@ -29,7 +29,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { git, baseBranchName } from './git.mjs';
-import { stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
+import { commitRecord, stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
 import { warn } from './ui.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 
@@ -95,41 +95,39 @@ export function createLandedObserver({ repoRoot, baseRef }) {
    *  merge commit describes a range rather than doing work, and its
    *  constituents are walked as themselves.
    *
-   *  THE SHA LIST COMES FROM REV-LIST, NEVER FROM THE FORMATTED LOG. Git
-   *  preserves the 0x1e/0x1f delimiter bytes inside a commit BODY (verified
-   *  empirically), so a crafted message can fabricate whole records — an
-   *  arbitrary sha plus Flowviant-Task ids that /fleet/base-landed would close
-   *  cards on. rev-list prints nothing an author controls, so its output is
-   *  the set of commits that exist: a parsed record whose sha is not in the
-   *  batch is a forgery and is dropped, a repeated sha is the same forgery
-   *  wearing a real commit's name, and the delimiter bytes are stripped from
-   *  every surviving field.
+   *  THE SHA LIST COMES FROM REV-LIST, NEVER FROM THE FORMATTED LOG, and each
+   *  commit is then read BY ITS OWN SHA (`commitRecord`, one `git show` per
+   *  commit) rather than as one delimited multi-record log. A batched log
+   *  used to print every commit's `%H%x1f%s%x1f%B%x1e` back to back and split
+   *  the blob on those same delimiter bytes — bytes git preserves verbatim
+   *  inside a commit BODY (verified empirically), so a crafted message could
+   *  embed its own fake `%x1e`/`%x1f%1f` run and fabricate an extra "record"
+   *  naming an arbitrary sha and Flowviant-Task ids that /fleet/base-landed
+   *  would close cards on. Reading one sha at a time removes the multi-record
+   *  parse entirely — there is no blob to split, so there is nothing for an
+   *  embedded delimiter to forge a SECOND record out of. `stripDelims` still
+   *  scrubs whatever lands in the subject/body of the commit it actually
+   *  belongs to, the same defence-in-depth `branchCommits` above keeps.
    *
-   *  BOUNDING THE BODY FETCH TO THE BATCH is what makes the header's batching
-   *  contract true at any range size: `%B` over the whole range grows without
-   *  bound, so the formatted log runs over exactly the shas being reported
-   *  this beat (`--no-walk=unsorted` shows precisely the commits named, in
-   *  argv order — measured). */
+   *  ONE UNREADABLE COMMIT IS SKIPPED, NOT AN ABORT OF THE WHOLE BATCH:
+   *  `commitRecord` runs through `gitRaw`, whose `maxBuffer` is git.mjs's
+   *  plain default (1MiB) rather than this module's widened `gitWide` — a
+   *  single commit whose message alone exceeds that returns null and is
+   *  dropped, while every other commit in the batch still reports. */
   const walk = (from, to) => {
     const shas = gitWide(['rev-list', '--reverse', '--no-merges', `${from}..${to}`])
       .split('\n')
       .filter((s) => SHA_RE.test(s));
     const batch = shas.slice(0, MAX_COMMITS);
     const tipAfter = shas.length > MAX_COMMITS ? batch[batch.length - 1] : null;
-    if (batch.length === 0) return { commits: [], tipAfter };
-    const real = new Set(batch);
-    const raw = gitWide(['log', '--no-walk=unsorted', '--format=%H%x1f%s%x1f%B%x1e', ...batch]);
     const out = [];
-    for (const rec of raw.split('\x1e')) {
-      const line = rec.replace(/^\n+/, '');
-      if (!line.trim()) continue;
-      const [sha, subject, ...bodyParts] = line.split('\x1f');
-      if (!real.has(sha)) continue;
-      real.delete(sha);
+    for (const sha of batch) {
+      const rec = commitRecord(sha, repoRoot);
+      if (!rec) continue;
       out.push({
         sha,
-        subject: stripDelims(subject).slice(0, 200),
-        taskIds: taskIdsFromMessage(stripDelims(bodyParts.join('\n'))).slice(0, 8),
+        subject: stripDelims(rec.subject).slice(0, 200),
+        taskIds: taskIdsFromMessage(stripDelims(rec.body)).slice(0, 8),
       });
     }
     return { commits: out, tipAfter };
@@ -202,13 +200,23 @@ export function createLandedObserver({ repoRoot, baseRef }) {
         for (const r of j?.data?.deployRefused ?? []) {
           warn(`deploy-on-merge refused for target "${r?.targetId}": ${r?.reason}`);
         }
+      } else if (res.status === 408 || res.status === 429) {
+        // A TIMEOUT OR A RATE LIMIT IS "NOT NOW", NOT "NEVER". Both used to
+        // land in the drop below, so one 429 — a busy operator IP past the
+        // limiter — skipped the range for good: its trailers and receipt shas
+        // never closed their cards (in PR mode the observer is the ONLY road
+        // to Done) and deploy-on-merge for that tip was never queued. Keep the
+        // stored tip, exactly as a 5xx does; the next beat re-walks it.
       } else if (res.status >= 400 && res.status < 500) {
         // A persistent 4xx (deploy skew, a payload this server refuses) would
         // otherwise re-send the same poison range on every beat forever.
-        // Drop the range — the closes it carried re-run at the next REAL tip
-        // move only if their cards are still open, which is the idempotent
-        // half; the honest cost is stated out loud.
-        writeState({ ref, tip });
+        // Drop THIS BATCH — to `reportedTip`, the last commit it carried, never
+        // the full tip: a range past the cap has a remainder this batch never
+        // sent, and advancing to the tip discarded that too. The closes it
+        // carried re-run at the next REAL tip move only if their cards are
+        // still open, which is the idempotent half; the honest cost is stated
+        // out loud.
+        writeState({ ref, tip: reportedTip });
         warn(`base-landed report refused (${res.status}) — skipped ${commits.length} commit(s)`);
       }
     } catch {

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/listeners.mjs

@@ -509,3 +509,214 @@ export function isListening(port, timeoutMs = 1500) {
     sock.once('error', () => finish(false));
   });
 }
+
+// ── the address a share dials ────────────────────────────────────────────────
+
+/**
+ * WHICH ADDRESS REACHES THE ATTRIBUTED PROCESS on `port`, or why none does
+ * (audit 2026-09-24).
+ *
+ * Attribution above is keyed on the PORT, and the gate used to dial
+ * `127.0.0.1:<port>` whatever socket had been attributed. Linux and macOS let
+ * two processes hold one port on the two loopback families side by side, so a
+ * dev server in this worktree on `[::1]:5173` and an unrelated process on
+ * `127.0.0.1:5173` passed the attribution check while the tunnel published the
+ * UNRELATED one — the exact thing attribution exists to prevent. And the
+ * ordinary case broke the other way: Vite's default `localhost` bind resolves
+ * to `::1` on a Mac, so the share opened and every request answered 502.
+ *
+ * So the dial address is DERIVED FROM THE ATTRIBUTED SOCKET: a wildcard bind is
+ * reached on its own family's loopback, a specific bind on its own address —
+ * and a candidate is REFUSED when a process outside the worktree holds that
+ * same address (or the same wildcard, via SO_REUSEPORT) on that port, because
+ * the kernel may then hand the connection to either. IPv4 is preferred when
+ * both reach the attributed process, since that is what every dev server's
+ * own printed URL means.
+ *
+ * `{ host }` on success, `{ error }` with a sentence otherwise. A platform this
+ * file cannot measure answers the loopback it always dialled — the same
+ * behaviour as before, never a refusal invented from ignorance.
+ */
+export function originFor(worktree, port) {
+  if (!worktree || !Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { error: `nothing is listening on port ${port} in this worktree.` };
+  }
+  let sockets;
+  try {
+    sockets =
+      platform() === 'linux'
+        ? socketsOnPortLinux(worktree, port)
+        : platform() === 'darwin'
+          ? socketsOnPortDarwin(worktree, port)
+          : null;
+  } catch {
+    sockets = null;
+  }
+  if (sockets == null) return { host: '127.0.0.1' };
+  return pickOrigin(sockets, port);
+}
+
+/**
+ * The rule alone, over `[{ family: 4|6, addr, ours }]` — split out so it is
+ * testable without two address families on the test box.
+ */
+export function pickOrigin(sockets, port) {
+  const ours = sockets.filter((s) => s.ours);
+  if (!ours.length) return { error: `nothing is listening on port ${port} in this worktree.` };
+  const foreign = sockets.filter((s) => !s.ours);
+  const dialOf = (s) =>
+    s.family === 6 ? (s.addr === '::' ? '::1' : s.addr) : s.addr === '0.0.0.0' ? '127.0.0.1' : s.addr;
+  const rank = (s) => {
+    const d = dialOf(s);
+    return d === '127.0.0.1' ? 0 : d === '::1' ? 1 : s.family === 4 ? 2 : 3;
+  };
+  let contested = false;
+  for (const s of [...ours].sort((a, b) => rank(a) - rank(b))) {
+    const dial = dialOf(s);
+    const shadowed = foreign.some((f) => f.family === s.family && (f.addr === dial || f.addr === s.addr));
+    if (shadowed) {
+      contested = true;
+      continue;
+    }
+    return { host: dial };
+  }
+  return contested
+    ? {
+        error: `another process on this machine, outside this worktree, also listens on port ${port} at the same address, so it was not shared.`,
+      }
+    : { error: `nothing is listening on port ${port} in this worktree.` };
+}
+
+/** /proc/net/tcp{,6} address hex → a printable address. Each 32-bit word is
+ *  stored little-endian. */
+function hexAddr(hex, family) {
+  const words = hex.match(/.{8}/g) || [];
+  const bytes = [];
+  for (const w of words) for (let i = 6; i >= 0; i -= 2) bytes.push(parseInt(w.slice(i, i + 2), 16));
+  if (family === 4) return bytes.join('.');
+  if (bytes.slice(0, 10).every((b) => b === 0) && bytes[10] === 0xff && bytes[11] === 0xff) {
+    return `::ffff:${bytes.slice(12).join('.')}`;
+  }
+  const groups = [];
+  for (let i = 0; i < 16; i += 2) groups.push(((bytes[i] << 8) | bytes[i + 1]).toString(16));
+  // Compress the longest run of zero groups, the way the address is written.
+  let best = [-1, 0];
+  for (let i = 0; i < 8; ) {
+    if (groups[i] !== '0') {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < 8 && groups[j] === '0') j++;
+    if (j - i > best[1]) best = [i, j - i];
+    i = j;
+  }
+  if (best[1] < 2) return groups.join(':');
+  const head = groups.slice(0, best[0]).join(':');
+  const tail = groups.slice(best[0] + best[1]).join(':');
+  return `${head}::${tail}`;
+}
+
+function socketsOnPortLinux(worktree, port) {
+  const byInode = new Map(); // inode -> { family, addr }
+  for (const [f, family] of [
+    ['/proc/net/tcp', 4],
+    ['/proc/net/tcp6', 6],
+  ]) {
+    let text;
+    try {
+      text = readFileSync(f, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n').slice(1)) {
+      const c = line.trim().split(/\s+/);
+      if (c.length < 10 || c[3] !== '0A') continue;
+      const [a, p] = String(c[1]).split(':');
+      if (parseInt(p, 16) !== port) continue;
+      if (c[9] && c[9] !== '0') byInode.set(c[9], { family, addr: hexAddr(a, family) });
+    }
+  }
+  if (byInode.size === 0) return [];
+  let root;
+  try {
+    root = realpathSync(worktree);
+  } catch {
+    return [];
+  }
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  const ours = new Set();
+  let pids;
+  try {
+    pids = readdirSync('/proc').filter((d) => /^\d+$/.test(d));
+  } catch {
+    return null;
+  }
+  if (pids.length > MAX_PIDS) pids = pids.slice(0, MAX_PIDS);
+  for (const pid of pids) {
+    let cwd;
+    try {
+      cwd = readlinkSync(`/proc/${pid}/cwd`);
+    } catch {
+      continue;
+    }
+    if (cwd !== root && !cwd.startsWith(prefix)) continue;
+    if (Number(pid) === process.pid || infraPids.has(Number(pid))) continue;
+    let fds;
+    try {
+      fds = readdirSync(`/proc/${pid}/fd`);
+    } catch {
+      continue;
+    }
+    for (const fd of fds) {
+      let link;
+      try {
+        link = readlinkSync(`/proc/${pid}/fd/${fd}`);
+      } catch {
+        continue;
+      }
+      const m = /^socket:\[(\d+)\]$/.exec(link);
+      if (m && byInode.has(m[1])) ours.add(m[1]);
+    }
+  }
+  // A socket whose holder we could not read (another user's process) is
+  // FOREIGN — the safe reading for a refusal check.
+  return [...byInode.entries()].map(([inode, s]) => ({ ...s, ours: ours.has(inode) }));
+}
+
+function socketsOnPortDarwin(worktree, port) {
+  const rows = []; // { pid, family, addr }
+  let pid = null;
+  let family = null;
+  for (const line of lsof(['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-F', 'ptn']).split('\n')) {
+    if (line.startsWith('p')) pid = line.slice(1);
+    else if (line.startsWith('t')) family = line.slice(1) === 'IPv6' ? 6 : line.slice(1) === 'IPv4' ? 4 : null;
+    else if (line.startsWith('n') && pid && family) {
+      const m = /^n(.*):(\d+)$/.exec(line);
+      if (!m || Number(m[2]) !== port) continue;
+      let addr = m[1].replace(/^\[|\]$/g, '');
+      if (addr === '*') addr = family === 6 ? '::' : '0.0.0.0';
+      rows.push({ pid, family, addr });
+    }
+  }
+  if (!rows.length) return [];
+  let root;
+  try {
+    root = realpathSync(worktree);
+  } catch {
+    return [];
+  }
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  const inside = new Set();
+  const self = String(process.pid);
+  let cur = null;
+  const pids = [...new Set(rows.map((r) => r.pid))];
+  for (const line of lsof(['-a', '-d', 'cwd', '-F', 'pn', '-p', pids.join(',')]).split('\n')) {
+    if (line.startsWith('p')) cur = line.slice(1);
+    else if (line.startsWith('n') && cur) {
+      const cwd = line.slice(1);
+      if ((cwd === root || cwd.startsWith(prefix)) && cur !== self && !infraPids.has(Number(cur))) inside.add(cur);
+    }
+  }
+  return rows.map((r) => ({ family: r.family, addr: r.addr, ours: inside.has(r.pid) }));
+}

package/bin/lib/localSessions.mjs

@@ -105,7 +105,7 @@ export function titleForSession(cwd, sessionId) {
     /* the place is gone — nothing to read */
   }
   for (const dir of dirs) {
-    const file = join(projects, dir.replace(/[/.]/g, '-'), `${sessionId}.jsonl`);
+    const file = join(projects, claudeProjectDir(dir), `${sessionId}.jsonl`);
     try {
       return transcriptTitle(file, statSync(file).mtimeMs);
     } catch {
@@ -115,6 +115,27 @@ export function titleForSession(cwd, sessionId) {
   return null;
 }
 
+/**
+ * THE DIRECTORY CLAUDE CODE FILES A CWD'S TRANSCRIPTS UNDER — its own rule,
+ * copied exactly (2.1.281): every character that is not an ASCII letter or
+ * digit becomes `-`, and a name past 200 characters is cut there and suffixed
+ * with a base-36 Java-style string hash of the ORIGINAL path.
+ *
+ * This file used `replace(/[/.]/g, '-')`, which agrees with Claude Code only
+ * while a path holds nothing but letters, digits, `/` and `.` — so a repo at
+ * `~/code/my_app` or `~/My Projects/x` never offered an ended terminal session
+ * for adoption and never got a tab auto-title, silently (audit 2026-09-24).
+ */
+const CLAUDE_DIR_MAX = 200;
+export function claudeProjectDir(path) {
+  const p = String(path);
+  const s = p.replace(/[^a-zA-Z0-9]/g, '-');
+  if (s.length <= CLAUDE_DIR_MAX) return s;
+  let h = 0;
+  for (let i = 0; i < p.length; i++) h = ((h << 5) - h + p.charCodeAt(i)) | 0;
+  return `${s.slice(0, CLAUDE_DIR_MAX)}-${Math.abs(h).toString(36)}`;
+}
+
 /** Path-prefix containment on already-realpath'd absolute paths. */
 const inside = (p, root) => p === root || p.startsWith(root.endsWith('/') ? root : `${root}/`);
 
@@ -373,7 +394,7 @@ export function scanLocalSessions({ repoRoot, excludeDirs = [], excludeIds }) {
           homedir(),
           '.claude',
           'projects',
-          cwd.replace(/[/.]/g, '-'),
+          claudeProjectDir(cwd),
           `${rec.sessionId}.jsonl`
         );
         liveTitle = transcriptTitle(liveFile, statSync(liveFile).mtimeMs);
@@ -400,7 +421,11 @@ export function scanLocalSessions({ repoRoot, excludeDirs = [], excludeIds }) {
     // But so does a sibling repo ('flowviant-two' shares 'flowviant' + '-'),
     // which is why every candidate is verified against the cwd its own records
     // embed rather than trusted on its directory name.
-    const munged = realRoot.replace(/[/.]/g, '-');
+    const munged = claudeProjectDir(realRoot);
+    // A root past Claude's 200-character cut carries a hash of ITSELF, which a
+    // subdirectory's name does not share — so the prefix a subdirectory can
+    // match is the cut, and the cwd verification below does the rest.
+    const mungedStem = munged.length > CLAUDE_DIR_MAX ? munged.slice(0, CLAUDE_DIR_MAX) : `${munged}-`;
     const projectsDir = join(homedir(), '.claude', 'projects');
     let projDirs = [];
     try {
@@ -411,7 +436,7 @@ export function scanLocalSessions({ repoRoot, excludeDirs = [], excludeIds }) {
     const cutoff = Date.now() - ENDED_WINDOW_MS;
     const candidates = [];
     for (const dirName of projDirs) {
-      if (dirName !== munged && !dirName.startsWith(`${munged}-`)) continue;
+      if (dirName !== munged && !dirName.startsWith(mungedStem)) continue;
       let entries = [];
       try {
         entries = readdirSync(join(projectsDir, dirName), { withFileTypes: true });

package/bin/lib/login.mjs

@@ -7,9 +7,10 @@
  */
 
 import { FLEET_URL, USER_AGENT, VERSION } from './config.mjs';
-import { saveLogin, detectRepoRoot, projectLabel, listStoredProjects, boundElsewhere, directoryTakenRefusal } from './credentials.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,12 +81,12 @@ 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,
         mcpUrl: poll.mcpUrl,
-        name: typeof poll.projectName === 'string' && poll.projectName ? poll.projectName : null,
+        name: safeName(poll.projectName),
         repoRoot,
       };
       // A DIRECTORY SERVES ONE PROJECT (2026-09-23). The owner, verbatim: "a
@@ -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

@@ -72,7 +72,9 @@
  */
 
 import { USER_AGENT } from './config.mjs';
-import { projectLabel, repoCollisions } from './credentials.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. */
@@ -178,7 +180,13 @@ function roleWord(role) {
  *  does not — and the words beside it are all the server's or the box's own. */
 export function renderBox(box, { me = null, latest = null } = {}, now = Date.now()) {
   const mark = box.fresh ? '●' : '○';
-  const name = box.boxName || 'an unnamed machine';
+  // SCRUBBED HERE TOO (2026-09-24, the audit) — a belt against the server's
+  // own display scrub, in defence of a stale stored row or a server this
+  // fix has not reached: the terminal is where an escape sequence in a
+  // box's name or its checkout path actually does harm, so this is the one
+  // place it must never be trusted to have already been cleaned. See
+  // printable.mjs.
+  const name = safeName(box.boxName) ?? 'an unnamed machine';
   // "LAST heard" is the staleness mark, and the row is never hidden for it —
   // the owner's answer to "what about a box that stopped" was exactly this.
   const heard = heardPhrase(box, now);
@@ -190,7 +198,7 @@ export function renderBox(box, { me = null, latest = null } = {}, now = Date.now
   const cells = [
     `${mark} ${name}`,
     roleWord(box.role),
-    box.checkoutPath || '(checkout not reported)',
+    safeName(box.checkoutPath) ?? '(checkout not reported)',
     box.daemonVersion ? `v${box.daemonVersion}` : 'version not reported',
     heard,
   ].filter(Boolean);
@@ -223,7 +231,7 @@ export function renderMachines(entries, results, { now = Date.now() } = {}) {
   // to notice a suffix to know whether it matters has already been asked to do
   // the work this listing is for.
   for (const e of entries) {
-    const label = e.name || `project ${e.projectId.slice(0, 8)}…`;
+    const label = projectLabel(e);
     const connected = connectedOn(e.savedAt);
     const id = `(id ${e.projectId.slice(0, 8)}…${connected ? `, connected ${connected}` : ''})`;
     lines.push(
@@ -239,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;
     }
@@ -290,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.'
     );
   });
@@ -310,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.',
 ];
 
@@ -318,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.',
 ];
@@ -332,15 +340,16 @@ 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 (res.status === 401 || res.status === 403) return { rejected: true };
+    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` };
     if (res.status === 404) return { unsupported: true };
     if (!res.ok) return { error: `HTTP ${res.status}` };
     const body = await res.json();
@@ -367,7 +376,7 @@ export function otherBoxesLine(boxes, me, now = Date.now()) {
   if (others.length === 0) return null;
   const parts = others.slice(0, 6).map((b) => {
     const role = roleWord(b.role);
-    return `${b.boxName || 'an unnamed machine'} (${role ? `${role} · ` : ''}${heardPhrase(b, now)})`;
+    return `${safeName(b.boxName) ?? 'an unnamed machine'} (${role ? `${role} · ` : ''}${heardPhrase(b, now)})`;
   });
   const more = others.length - parts.length;
   return `other machines on this project: ${parts.join(', ')}${more > 0 ? `, and ${more} more` : ''}`;
@@ -403,7 +412,8 @@ export async function leaveBoxFor(entry, { url, envpub, fetchImpl = fetch } = {}
       body: JSON.stringify({ envpub }),
       signal: AbortSignal.timeout(15_000),
     });
-    if (res.status === 401 || res.status === 403) return { rejected: true };
+    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` };
     if (res.status === 404) return { unsupported: true };
     if (!res.ok) return { error: `HTTP ${res.status}` };
     const body = await res.json();
@@ -478,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 };
 }