flowviant 0.93.0 → 0.95.0

package/README.md

@@ -41,8 +41,30 @@ Prefer an explicit token? Create a machine credential in the app and pass it dir
 FLOWVIANT_MACHINE_TOKEN=fva_… npx flowviant@latest   # FLOWVIANT_FLEET still works
 ```
 
+Prefer a plain command to `npx`? Install it once and every `npx flowviant@latest` in this README is just `flowviant`:
+
+```bash
+npm i -g flowviant
+flowviant login
+```
+
+Either way is fine and both stay current on their own (below). npx is the zero-install door; a global install is what you want on a box you keep running, so the daemon, `flowviant login` and `flowviant machines` are ordinary commands.
+
 Launch with `@latest` so each start pulls the newest published version — a bare `npx flowviant` can reuse a stale cache. A running daemon also keeps itself current: from **0.58.0** it restarts itself through `npx flowviant@latest` when a new version ships, so npx launches stay up to date the same way a global install does. (Before 0.58.0 that was only true of a global install — under npx the daemon printed a notice and stayed put, which is how machines ended up sitting several releases back.) It only ever restarts when no turn is running. `FLOWVIANT_NO_UPDATE=1` makes it nag-only; `flowviant update` updates now.
 
+## Machines on this box
+
+One box can serve several projects — one daemon per repository directory, each connected with its own `flowviant login` run inside that repo. `flowviant machines` lists every project connected on this box with the id and date it was connected, and under each one every computer that has polled it (the app's Home lists the same across your whole account). Two projects bound to one repository are named out loud at the foot of the listing, because that is the one shape that reads as "the same project connected twice" and is not: every `npx flowviant` in that directory has to ask which of them to serve.
+
+On a terminal the listing is a menu: ↑/↓ over the projects, enter for what you can do about one, esc to leave. Two verbs, each acting on **this box's own connection** and nothing else:
+
+- **disconnect this box from it** — stops the daemon serving that project here (that one credential's daemon, never the others), removes this box from the project's machines list in the app, and forgets the credential here. `flowviant machines --remove <project id>` is the same thing for a script.
+- **forget it here only** — the credential is dropped from `~/.flowviant/credentials.json` and nothing else happens; the app keeps listing this box until it goes quiet. `--forget <project id>` for a script.
+
+Stopping or removing a daemon on **another** computer is done in the app (project settings → Machines), where the person pressing it can see what they are changing.
+
+`flowviant login` asks before it binds a second project to a repository that is already connected to one: keep both (every start there asks which to serve), replace (the repo serves the new project and this box is disconnected from the old one), or cancel.
+
 ## Sessions
 
 Each tab in the Workbench is a persistent Claude session with its own worktree, and it stays where you left it — the branch outlives the tab. The daemon runs each turn in event mode and relays what the CLI is printing (thinking, reads, greps, commands) back to the tab, reports the worktree's branch and diffstat after every turn, and fetches a commit's patch when you click a sha in the app.

package/bin/cli.mjs

@@ -41,9 +41,12 @@
  * Ambiguity is a picker on a TTY and a worded refusal headless — never a
  * guess. `flowviant projects` lists what is stored; `--project <name|id>`
  * picks without a prompt. `flowviant machines` (0.91.0) asks the server which
- * BOXES have polled each of those credentials — the view-only answer to "am I
- * running duplicate or redundant daemons?", which the store alone cannot give
- * because a daemon on another computer is invisible from here.
+ * BOXES have polled each of those credentials — the answer to "am I running
+ * duplicate or redundant daemons?", which the store alone cannot give because
+ * a daemon on another computer is invisible from here; since 0.95.0 it says
+ * out loud when two projects are bound to one repo, and on a terminal it is a
+ * menu (↑/↓, enter) whose verbs disconnect THIS box from a project or forget
+ * a credential here — `--remove <id>` / `--forget <id>` for a script.
  *
  * Env:
  *   FLOWVIANT_MACHINE_TOKEN  the machine credential (or use `flowviant login`);
@@ -82,8 +85,11 @@ import { runLogin } from './lib/login.mjs';
 // long-running process.
 if (process.argv[2] === 'login') {
   const noStart = process.argv.includes('--no-start');
-  await runLogin({ thenStart: !noStart });
-  if (noStart) process.exit(0);
+  const login = await runLogin({ thenStart: !noStart });
+  // 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 (noStart || !login?.saved) process.exit(0);
   // Re-exec as a plain `flowviant` rather than falling through. config.mjs reads
   // the credential at IMPORT time — which was before the login we just did — so
   // this process still has an empty FLEET_TOKEN and would exit with "no
@@ -224,16 +230,19 @@ if (process.argv[2] === 'projects') {
 }
 
 // ── `flowviant machines` — every project connected on THIS box, and every box
-//    that has polled each of them.
+//    that has polled each of them; and, on a terminal, a menu over them.
 //
 // A THIRD COMMAND, and the owner's ruling it amends is his own: the terminal
 // surface is `npx flowviant` and `npx flowviant login`, full stop — which is
 // what deleted the old terminal flag for moving a machine — and he asked for
-// this one directly ("the CLI gets a command to list connections"). So it is
-// amended in the narrowest form that ruling allows: VIEW-ONLY. It starts
-// nothing, stops nothing, moves nothing, takes no lock and reaches no daemon.
-// The only state it can change is this box's credential file, and only behind
-// an explicit `--forget`.
+// this one directly ("the CLI gets a command to list connections"). It shipped
+// VIEW-ONLY, and on 2026-09-23 he asked for the rest: "it seems to be only a
+// read cmd but I want to be able to interact with it and use arrow keys to
+// select the machines or to remove them." So: the listing, then — only where a
+// person can drive one — a menu. Its verbs act on THIS BOX'S OWN CONNECTIONS
+// (stop the daemon here, leave the project's list in the app, forget the
+// credential here) and never on another computer's daemon; machines.mjs
+// carries the argument.
 //
 // The question is the owner's, verbatim: "is there a way to view ALL the
 // connected flowviants? because im not sure if i have any duplicate or
@@ -250,14 +259,16 @@ if (process.argv[2] === 'projects') {
 //
 // EXIT 0 whatever it finds, including nothing: the listing is the answer the
 // asker came for, and a non-zero code over "you have no projects connected"
-// would make this command unusable in anything that checks one.
+// would make this command unusable in anything that checks one. `--remove`
+// is the one exit that can be 1, when the daemon it had to stop would not.
 if (process.argv[2] === 'machines') {
   const creds = await import('./lib/credentials.mjs');
   const forgetAt = process.argv.indexOf('--forget');
   if (forgetAt >= 0) {
-    // THE ONE WRITE. Named explicitly, matched by full id or a ≥6 prefix, and
-    // AMBIGUITY REFUSES rather than guessing — this deletes a credential, and
-    // two projects that look alike is the case that produced the command.
+    // THE LOCAL-ONLY WRITE. Named explicitly, matched by full id or a ≥6
+    // prefix, and AMBIGUITY REFUSES rather than guessing — this deletes a
+    // credential, and two projects that look alike is the case that produced
+    // the command.
     const res = creds.forgetStoredProject(process.argv[forgetAt + 1]);
     if (res.error) {
       console.error(`error: ${res.error}`);
@@ -269,16 +280,29 @@ if (process.argv[2] === 'machines') {
     );
     process.exit(0);
   }
+  const { boxesUrlFrom, leaveUrlFrom, fetchBoxesFor, renderMachines, disconnectHere, realDisconnectDeps, MACHINES_FOOTER, MACHINES_FLAGS_FOOTER } =
+    await import('./lib/machines.mjs');
+  const { FLEET_URL } = await import('./lib/config.mjs');
+  const removeAt = process.argv.indexOf('--remove');
+  if (removeAt >= 0) {
+    // THE SCRIPTED DISCONNECT — the menu's first verb, named by id for a
+    // terminal nobody is sitting at. Same matcher and the same refusal of an
+    // ambiguous prefix as --forget: a name two projects share is exactly the
+    // input this command exists to untangle, and it must not pick one.
+    const m = creds.matchStoredProject(process.argv[removeAt + 1]);
+    if (m.error) {
+      console.error(`error: ${m.error}. \`flowviant machines\` lists what is stored.`);
+      process.exit(1);
+    }
+    const res = await disconnectHere(m.entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL) }));
+    process.exit(res.ok ? 0 : 1);
+  }
 
-  const entries = creds.listStoredProjects();
+  let entries = creds.listStoredProjects();
   if (entries.length === 0) {
     console.log('no projects connected on this machine yet — run `flowviant login` inside a repo.');
     process.exit(0);
   }
-  const { boxesUrlFrom, fetchBoxesFor, renderMachines, MACHINES_FOOTER } = await import(
-    './lib/machines.mjs'
-  );
-  const { FLEET_URL } = await import('./lib/config.mjs');
   // OUR OWN BOX ID, so the listing can mark "← this box".
   //
   // READ, NEVER CREATED. This called `ensureKeypair()` until 2026-09-19, which
@@ -299,16 +323,83 @@ if (process.argv[2] === 'machines') {
     /* unreadable keypair — nothing is marked, and nothing is claimed */
   }
   const url = boxesUrlFrom(FLEET_URL);
-  const results = {};
-  // SEQUENTIAL, not a fan-out: this is a handful of credentials on somebody's
-  // laptop, and a parallel burst against the API buys nothing a person waiting
-  // two seconds can perceive.
-  for (const e of entries) {
-    results[e.projectId] = await fetchBoxesFor(e, { url, envpub: me });
+  const listing = async () => {
+    const results = {};
+    // SEQUENTIAL, not a fan-out: this is a handful of credentials on somebody's
+    // laptop, and a parallel burst against the API buys nothing a person
+    // waiting two seconds can perceive.
+    for (const e of entries) {
+      results[e.projectId] = await fetchBoxesFor(e, { url, envpub: me });
+    }
+    console.log('');
+    for (const line of renderMachines(entries, results)) console.log(line);
+    console.log('');
+  };
+  await listing();
+
+  // THE MENU, only where a person can drive one. `canPrompt()` is the same
+  // gate the start path keeps — a backgrounded job or a pipe gets the listing
+  // and the flags, never a prompt that stops the process — and `menuSupported`
+  // is whether ↑/↓ can be read at all. Without both this is the command it was.
+  const { canPrompt, menuSupported, selectMenu, askWithTimeout } = await import('./lib/tty.mjs');
+  if (!(canPrompt() && menuSupported())) {
+    for (const line of MACHINES_FOOTER) console.log(line);
+    for (const line of MACHINES_FLAGS_FOOTER) console.log(line);
+    process.exit(0);
+  }
+  const deps = await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL) });
+  for (;;) {
+    // A ROW PER PROJECT connected on this box — the things this box can act on.
+    // The other computers under each project are printed above for the
+    // duplicate to be visible, and are not rows here: stopping or removing
+    // THEM is the app's verb, and a menu row that answers "not from here" is
+    // a control wired to a refusal.
+    console.log('  projects connected on this box — enter one for what you can do about it:');
+    const rowLabel = (e) => creds.projectRowLabel(e, entries) + (e.repoRoot ? `  — ${e.repoRoot}` : '  — not tied to a repo');
+    const pick = await selectMenu({ options: [...entries.map(rowLabel), 'done'] });
+    if (pick.cancelled || pick.unsupported || pick.index === entries.length) break;
+    const picked = entries[pick.index];
+    const who = creds.projectRowLabel(picked, entries);
+    // TWO VERBS, each row saying its whole consequence — the app's ⋯ menu on a
+    // machine row says the same two things, and a menu whose rows are verbs
+    // with the outcome in a manual somewhere is one you have to be sure about
+    // before you can use it.
+    const action = await selectMenu({
+      options: [
+        `disconnect this box from ${who} — stops its daemon here, removes this box from its machines list in the app, forgets its credential here`,
+        `forget ${who} here only — nothing is stopped; the app keeps listing this box until it goes quiet`,
+        'back',
+      ],
+    });
+    if (action.cancelled || action.unsupported || action.index === 2) continue;
+    // ONE CONFIRM, in words, because both verbs delete a credential and the
+    // arrow keys make a slip cheap. A read that failed (stdin gone) is "no".
+    const verb = action.index === 0 ? 'Disconnect this box from' : 'Forget';
+    const answer = await askWithTimeout(`  ${verb} ${who}? [y/N] `);
+    if (!/^y(es)?$/i.test(answer ?? '')) {
+      console.log('  left as it was.\n');
+      continue;
+    }
+    if (action.index === 0) {
+      await disconnectHere(picked, deps, { log: (m) => console.log(`  ${m}`) });
+    } else {
+      const res = creds.forgetStoredProject(picked.projectId);
+      console.log(
+        res.error
+          ? `  ${res.error}`
+          : `  forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box. Nothing was stopped or deleted anywhere else — \`flowviant login\` connects it again.`
+      );
+    }
+    entries = creds.listStoredProjects();
+    if (entries.length === 0) {
+      console.log('\n  no projects are connected on this box now.\n');
+      break;
+    }
+    // THE LISTING AGAIN, re-asked: the server's rows are the only true account
+    // of what the leave did, and a menu redrawn over a stale listing would be
+    // this command asserting the outcome it hoped for.
+    await listing();
   }
-  console.log('');
-  for (const line of renderMachines(entries, results)) console.log(line);
-  console.log('');
   for (const line of MACHINES_FOOTER) console.log(line);
   process.exit(0);
 }
@@ -368,7 +459,8 @@ const externalToken =
  *  pattern: config.mjs read the store at IMPORT time, before the credential
  *  existed, so this process cannot serve; the child can. */
 async function reexecAfterLogin() {
-  await runLogin({ thenStart: false });
+  const login = await runLogin({ thenStart: false });
+  if (!login?.saved) process.exit(0); // cancelled at the second-project question — nothing to serve
   const { spawn } = await import('node:child_process');
   const child = spawn(process.execPath, [process.argv[1]], { stdio: 'inherit', env: process.env });
   process.exit(await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0))));

package/bin/lib/artifacts.mjs

@@ -0,0 +1,298 @@
+/**
+ * ARTIFACTS, daemon side (2026-09-22, 0.94.0) — the files a turn wrote to SHOW
+ * the person, found after the turn and relayed.
+ *
+ * The owner asked whether Flowviant could "have it generate artifacts and
+ * display artifacts there". The turn contracts gain one paragraph
+ * (`ARTIFACTS_PARAGRAPH`, prompts.mjs): to show a page, a document, a chart or
+ * an image, write it under `.flowviant/artifacts/` in the directory you stand
+ * in. After each session turn and each agent turn this module lists that
+ * directory and uploads what the turn changed to `POST /fleet/artifact`; the
+ * Workbench draws it beside the thread. NOTHING HERE MAKES AN ARTIFACT — it
+ * reads what the CLI wrote and relays it, scrubbed.
+ *
+ * ── WHAT THE TURN CHANGED, NOT WHAT IS THERE ──
+ *
+ * The directory is snapshotted (name → size:mtime) BEFORE the CLI spawns and
+ * compared after it exits. The spec's words were "changed since the last
+ * report", and a per-turn snapshot is the strict form of that, chosen for two
+ * reasons: (1) every tab one person owns shares ONE place (the checkout, or
+ * their own copy), so a file one tab wrote is on disk when a sibling tab's turn
+ * ends — diffing against "last reported" per session would hand tab B every
+ * artifact tab A ever drew; and (2) a snapshot needs no memory across a daemon
+ * restart, which a "last reported" map would lose on every auto-update and then
+ * re-upload the whole directory. The residual, stated: two tabs in one place
+ * running turns AT THE SAME TIME (the place lock admits concurrent readers) can
+ * each see the other's write land inside their window. The server's upsert by
+ * (owner, name) and its bound keep that a duplicate, never a wrong answer.
+ *
+ * ── THE BOUNDS ──
+ *
+ * Regular files only, DEPTH ONE, `lstat` and never followed: a symlink an
+ * agent planted at `.flowviant/artifacts/x.txt -> ~/.ssh/id_ed25519` is
+ * reported as nothing, and the read itself opens with `O_NOFOLLOW` so a swap
+ * between the lstat and the open cannot turn one into a follow. The directory
+ * itself must be a real directory for the same reason. At most 40 files,
+ * newest first. Types off the allowlist (the server's list, repeated here —
+ * this is somebody's disk and one place checking is one deploy from zero) are
+ * reported BY NAME and never read. Over `ARTIFACT_MAX_BYTES` likewise.
+ *
+ * ── TEXT IS SCRUBBED ──
+ *
+ * html, md, svg, json, csv and txt pass through `envScrub` before upload — the
+ * turn trace's own scrub, for the trace's own reason: a page the agent wrote
+ * can quote a value out of the checkout's `.env`, and an artifact is served to
+ * a browser. Binary images are not scrubbed (there is no text to match), and
+ * the SERVER computes the sha256 of what it stored; the one sent here is for
+ * the log.
+ *
+ * ── DELIVERY ──
+ *
+ * A 2xx is delivered. A 4xx (other than 408/429) is TREATED AS DELIVERED — an
+ * older SERVER 404s the whole route, and holding bodies it will refuse forever
+ * would be the trace relay's wedge wearing a retry's clothes; a refusal of one
+ * file (ended session, wrong owner) is equally permanent. A 5xx, 408, 429 or a
+ * network error keeps the STORED BODY — the fields and the bytes as they were
+ * scrubbed — and retries it on the next report beat, the settle's shape, at
+ * most `MAX_TRIES` times; a newer copy of the same file replaces a held one.
+ *
+ * NO VERSION FLOOR: a daemon→server report on a new endpoint. The prompt
+ * paragraph is gated instead, on the roster's `artifactsAccepted` — a server
+ * that cannot show an artifact must not have the CLI told it will.
+ */
+
+import { constants, closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+/** Relative to the directory the turn stands in. Under `.flowviant/`, which
+ *  the exclude file already hides from git (`excludeInWorktree`). */
+export const ARTIFACT_DIR = '.flowviant/artifacts';
+/** The server's per-file ceiling, re-checked here. */
+export const ARTIFACT_MAX_BYTES = 2 * 1024 * 1024;
+/** Listed per scan, newest first — the server keeps as many per owner. */
+export const ARTIFACT_MAX_FILES = 40;
+/** A held upload is tried this many times in all, then dropped with a line. */
+const MAX_TRIES = 4;
+/** Held bodies across every owner — each can be two megabytes. */
+const MAX_PENDING = 40;
+
+/** The allowlist, by extension. The server's `ARTIFACT_TYPES`, repeated. */
+export const ARTIFACT_TYPES = {
+  html: { mime: 'text/html', text: true },
+  htm: { mime: 'text/html', text: true },
+  md: { mime: 'text/markdown', text: true },
+  svg: { mime: 'image/svg+xml', text: true },
+  png: { mime: 'image/png', text: false },
+  jpg: { mime: 'image/jpeg', text: false },
+  jpeg: { mime: 'image/jpeg', text: false },
+  gif: { mime: 'image/gif', text: false },
+  webp: { mime: 'image/webp', text: false },
+  json: { mime: 'application/json', text: true },
+  csv: { mime: 'text/csv', text: true },
+  txt: { mime: 'text/plain', text: true },
+};
+
+export function artifactTypeFor(name) {
+  const dot = String(name).lastIndexOf('.');
+  if (dot <= 0) return null;
+  return ARTIFACT_TYPES[String(name).slice(dot + 1).toLowerCase()] ?? null;
+}
+
+/**
+ * The directory's regular files, newest first, at most `ARTIFACT_MAX_FILES`.
+ * `[]` for a directory that does not exist, is not a directory, or is a
+ * symlink — nothing to report is the only honest reading of any of those.
+ */
+export function scanArtifacts(placeDir) {
+  const dir = join(placeDir, ARTIFACT_DIR);
+  /**
+   * BOTH components are checked, not only the last (2026-09-23). `lstat` on
+   * `.flowviant/artifacts` refuses a symlink AT that name, but it resolves
+   * THROUGH a symlinked `.flowviant` — and git commits symlinks, so a cloned
+   * repo carrying `.flowviant -> /some/dir` would have had this scan listing,
+   * reading and uploading `/some/dir/artifacts/*`, a directory outside the
+   * place the turn stood in. The knowledge sync already refuses a `.flowviant`
+   * that is not a real directory (`flowviantDirOk`); this is the same check on
+   * the read side.
+   */
+  try {
+    const parent = lstatSync(join(placeDir, '.flowviant'));
+    if (parent.isSymbolicLink() || !parent.isDirectory()) return [];
+    if (!lstatSync(dir).isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (name.startsWith('.')) continue; // editor swap files, `.DS_Store`
+    try {
+      const st = lstatSync(join(dir, name));
+      if (!st.isFile()) continue; // symlinks, directories, sockets: nothing
+      out.push({ name, path: join(dir, name), size: st.size, mtimeMs: st.mtimeMs });
+    } catch {
+      /* vanished between the list and the stat */
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
+  return out.slice(0, ARTIFACT_MAX_FILES);
+}
+
+const sigOf = (e) => `${e.size}:${e.mtimeMs}`;
+
+/** name → size:mtime, taken before the CLI spawns. */
+export function snapshotArtifacts(placeDir) {
+  return new Map(scanArtifacts(placeDir).map((e) => [e.name, sigOf(e)]));
+}
+
+/** What the turn wrote: every entry whose (name, size, mtime) is not what the
+ *  snapshot held. A deleted file is not reported — the server's copy is
+ *  scrollback and goes with the session or the agent. */
+export function changedArtifacts(before, entries) {
+  return entries.filter((e) => before?.get(e.name) !== sigOf(e));
+}
+
+/** Read a regular file WITHOUT following a symlink planted after the lstat. */
+function readNoFollow(path, limit) {
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > limit) return null;
+    const buf = Buffer.alloc(st.size);
+    let off = 0;
+    while (off < st.size) {
+      const n = readSync(fd, buf, off, st.size - off, off);
+      if (n <= 0) break;
+      off += n;
+    }
+    return buf.subarray(0, off);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * ONE UPLOAD BODY, as data — fields plus optional bytes — so a held body is
+ * re-sent exactly as it was first built (scrubbed once, never re-read from a
+ * disk the agent may have changed since).
+ */
+export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub = (s) => s) {
+  const type = artifactTypeFor(entry.name);
+  const fields = {
+    ...(sessionId ? { sessionId } : { agentId }),
+    ...(turnId ? { turnId } : {}),
+    name: entry.name,
+    bytes: String(entry.size),
+  };
+  if (!type) return { fields, bytes: null }; // reported by name only
+  if (entry.size > ARTIFACT_MAX_BYTES) return { fields: { ...fields, tooLarge: '1' }, bytes: null };
+  let bytes;
+  try {
+    bytes = readNoFollow(entry.path, ARTIFACT_MAX_BYTES);
+  } catch {
+    return null; // vanished, or a symlink swapped in: nothing to say
+  }
+  if (!bytes) return { fields: { ...fields, tooLarge: '1' }, bytes: null };
+  if (type.text) {
+    bytes = Buffer.from(String(scrub(bytes.toString('utf8'))), 'utf8');
+    // A redaction marker can be longer than the value it replaced.
+    if (bytes.byteLength > ARTIFACT_MAX_BYTES) {
+      return { fields: { ...fields, bytes: String(bytes.byteLength), tooLarge: '1' }, bytes: null };
+    }
+  }
+  return {
+    fields: {
+      ...fields,
+      bytes: String(bytes.byteLength),
+      mime: type.mime,
+      sha256: createHash('sha256').update(bytes).digest('hex'),
+    },
+    bytes,
+  };
+}
+
+/**
+ * The reporter a work manager holds for its life. `report` is called once per
+ * finished turn and never awaited by the turn (a slow uplink must not hold the
+ * next turn behind a readout); `retryPending` rides the settle retry beat.
+ */
+export function createArtifactReporter({ fleetUrl, token, userAgent, scrub, fetchImpl, log = () => {} }) {
+  const url = String(fleetUrl).replace(/\/agents\/?$/, '/artifact');
+  const doFetch = fetchImpl ?? ((...a) => fetch(...a));
+  const pending = new Map(); // `${owner}:${name}` -> { body, tries }
+
+  /** true = settled (delivered or permanently refused); false = hold it. */
+  const post = async (body) => {
+    const form = new FormData();
+    for (const [k, v] of Object.entries(body.fields)) form.set(k, v);
+    if (body.bytes) form.set('file', new Blob([body.bytes]), body.fields.name);
+    try {
+      const res = await doFetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent },
+        signal: AbortSignal.timeout(30_000),
+        body: form,
+      });
+      return (
+        res.ok || (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  const hold = (key, body, tries) => {
+    if (tries >= MAX_TRIES) {
+      pending.delete(key);
+      log(`artifact ${body.fields.name}: not delivered after ${tries} tries — dropped`);
+      return;
+    }
+    pending.delete(key); // re-insert at the tail, so the cap sheds the oldest
+    pending.set(key, { body, tries });
+    while (pending.size > MAX_PENDING) pending.delete(pending.keys().next().value);
+  };
+
+  const send = async (key, body, tries) => {
+    if (await post(body)) pending.delete(key);
+    else hold(key, body, tries + 1);
+  };
+
+  let retrying = false;
+  const retryPending = async () => {
+    if (retrying || pending.size === 0) return;
+    retrying = true;
+    try {
+      for (const [key, held] of [...pending]) {
+        if (pending.get(key) !== held) continue; // superseded meanwhile
+        await send(key, held.body, held.tries);
+      }
+    } finally {
+      retrying = false;
+    }
+  };
+
+  /** Upload what this turn changed in `placeDir`. Resolves to the number of
+   *  bodies SENT this call (delivered or held), for the tests and the log. */
+  const report = async ({ placeDir, before, sessionId, agentId, turnId }) => {
+    if (!placeDir || (!sessionId && !agentId)) return 0;
+    const changed = changedArtifacts(before, scanArtifacts(placeDir));
+    let n = 0;
+    for (const entry of changed) {
+      const body = buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub);
+      if (!body) continue;
+      const key = `${sessionId ?? agentId}:${entry.name}`;
+      pending.delete(key); // this copy supersedes a held older one
+      await send(key, body, 0);
+      n++;
+    }
+    return n;
+  };
+
+  return { report, retryPending, pendingCount: () => pending.size };
+}

package/bin/lib/claude.mjs

@@ -351,7 +351,7 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
 // returned string for sentinel detection, and each activity is handed to
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
-export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onToolEvent, onInit, onUsage, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onToolEvent, onInit, onUsage, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, knowledgeDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
   return new Promise((resolve) => {
     const rt = runtimeById(runtime);
     if (!rt.args) {
@@ -405,6 +405,14 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEn
       // runtime that can path-scope its writes needs to know WHERE the vault is,
       // and Claude — which cannot — simply ignores it.
       vaultDir,
+      // THE PROJECT'S KNOWLEDGE LIBRARY (0.94.0), when this box holds one. It
+      // lives in the CHECKOUT and a turn usually runs in a worktree, so the
+      // prompt hands an absolute path OUTSIDE the cwd — and a curated Claude
+      // profile (the capture chat's read-only list, `FLOWVIANT_SAFE=1`) may
+      // refuse a read there. `--add-dir` says the directory is one it may read.
+      // Only Claude's adapter uses it; codex's sandboxes read the filesystem
+      // already, and agy's `--add-dir` is spent on the wiki vault.
+      knowledgeDir,
       // Structured-output flags for the MEDIATED path. Handed to the adapter
       // rather than appended here for the same reason `mcp` is: Codex takes its
       // prompt as a trailing positional, so a flag after it is in the wrong

package/bin/lib/credentials.mjs

@@ -172,6 +172,61 @@ export function projectRowLabel(e, entries) {
   return `${label} (id ${String(e?.projectId ?? '').slice(0, 8)}…${when})`;
 }
 
+/**
+ * WHICH STORED PROJECTS SHARE ONE REPO — the duplicate the owner met and could
+ * not name (2026-09-23).
+ *
+ * `npx flowviant machines` printed "BRIF AI" twice, and he read it as two
+ * daemons or two "machine profiles" on one box for one project: *"when I go to
+ * BRIF AI to disconnect the duplicate, I only see one."* It was two PROJECTS
+ * with one name, both bound to one checkout — and the id-on-every-row rule
+ * (2026-09-19) had not made that legible, because two hex prefixes say
+ * "different" without saying "same repo". A project's Machines page shows its
+ * own credential's boxes, so neither page could show the other project at
+ * all.
+ *
+ * So the collision is stated as a FACT ABOUT THE REPO: every group of two or
+ * more entries bound to one directory, compared by realpath the way every
+ * other path here is. Pure over the entries; the listing prints each group as
+ * one line and the picker's row labels already carry the id and date.
+ *
+ * ONE REPO SERVES ONE PROJECT is the owner's own model ("i can have 1 daemon in
+ * one directory, 1 in another as a differentiator of projects"), which is why
+ * this is worth a sentence and an unbound duplicate is not: two projects with
+ * no repo are two things nothing has decided about yet.
+ */
+export function repoCollisions(entries) {
+  const groups = [];
+  for (const e of entries) {
+    if (!e?.repoRoot) continue;
+    const g = groups.find((x) => samePath(x.repoRoot, e.repoRoot));
+    if (g) g.entries.push(e);
+    else groups.push({ repoRoot: e.repoRoot, entries: [e] });
+  }
+  return groups.filter((g) => g.entries.length > 1);
+}
+
+/**
+ * THE OTHER PROJECTS ALREADY BOUND TO THIS REPO — what `flowviant login` asks
+ * about before it saves a second one (2026-09-23).
+ *
+ * The owner: *"im not sure how it even allowed me to run npx flowviant login
+ * twice and init a daemon twice on the same project/repository/directory in
+ * the first place."* Login binds the approved project to the repo it was run
+ * in and never looked at what was bound there already, so a second project —
+ * approved in a browser tab that happened to be open on a different project of
+ * the same name — landed beside the first without a word. The store's own
+ * resolution then turned every start into a picker between two identical
+ * rows.
+ *
+ * Excludes the project being logged into: re-running login for the SAME
+ * project is an upsert and asks nothing.
+ */
+export function boundElsewhere(entries, repoRoot, projectId) {
+  if (!repoRoot) return [];
+  return entries.filter((e) => e.projectId !== projectId && samePath(e.repoRoot, repoRoot));
+}
+
 /** Collapse a name or slug for loose comparison: "My Project", "my-project"
  *  and "myproject" all become "myproject". */
 function normalizeName(s) {