flowviant 0.124.0 → 0.124.1

package/README.md

@@ -37,6 +37,12 @@ flowviant
 
 It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `flowviant` just runs. The installer prints a PATH hint if needed; `FLOWVIANT_INSTALL_DIR` changes its destination. It verifies SHA-256 and never uses sudo.
 
+Run `flowviant login` from another checkout and choose the same project in the
+browser to add its repository to that board. Project settings → General lists
+the repositories, their remotes and base branches. The project's merge mode
+applies to all of them. Credentials keep the named checkout paths together;
+each directory still belongs to only one project on this machine.
+
 Prefer an explicit token? Create a machine credential in the app and pass it directly:
 
 ```bash

package/bin/cli.mjs

@@ -80,6 +80,11 @@
 // answered here before anything else loads: no config, no update check, no
 // output but the hook's. An unknown hook exits 2, which Claude Code reads as a
 // refusal — the read guard's own rule for a hook that cannot judge.
+if (['__repository', '__repository-mcp'].includes(process.argv[2])) {
+  await (await import('./lib/repositoryTool.mjs')).repositoryToolMain(process.argv[2] === '__repository-mcp');
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__hook') {
   const HOOKS = {
     'read-guard': () => import('./lib/hooks/readGuard.mjs'),
@@ -279,6 +284,8 @@ async function cleanCommand() {
     /* du unavailable — skip the size */
   }
   console.log('note: stop any running flowviant daemon first — in-flight local work is discarded.');
+  const { unlockRepositorySnapshots } = await import('./lib/repositoryPlaces.mjs');
+  unlockRepositorySnapshots(dir);
   rmSync(dir, { recursive: true, force: true });
   console.log(`cleaned ~/.flowviant/worktrees${size}.`);
   process.exit(0);

package/bin/lib/agentInternalWait.mjs

@@ -5,6 +5,7 @@
  * measured failure for the lane's existing one-shot settlement. */
 import { parseTurnResult } from './agentPlan.mjs';
 import { limitLine } from './cliLimit.mjs';
+import { addUsage } from './turnUsage.mjs';
 
 export const INTERNAL_WAIT_RECOVERIES = 2;
 export const INTERNAL_WAIT_CONTRACT = `Your own command or test still running is internal work, never a human blocker.
@@ -58,7 +59,7 @@ export async function runAgentWithInternalWaits(run, options) {
         options.onAnswer?.(text);
       },
       onUsage: (usage) => {
-        currentUsage = usage;
+        currentUsage = addUsage(currentUsage, usage);
         options.onUsage?.(combine());
       },
       onToolEvent: (name, input, meta) => {

package/bin/lib/agentPlan.mjs

@@ -170,6 +170,8 @@ function fencedBody(text) {
  * so the nested object ends where it ends — and if that brace never closes,
  * neither does this one. What is left for each walk is its own top level.
  */
+// The conversation-prose filter uses the same brace/string boundaries.
+export { closers as jsonObjectClosers };
 function closers(s) {
   const close = new Map();
   for (let i = s.lastIndexOf('{'); i >= 0; i = i > 0 ? s.lastIndexOf('{', i - 1) : -1) {
@@ -260,6 +262,8 @@ export function parseProposal(text, scrub = envScrub) {
   const collisions = Array.isArray(parsed.collisions) ? parsed.collisions.map(c => ({ taskIds: c?.taskIds, files: lines(c?.files), rationale: scrubCut(c?.rationale, 1000, scrub) })) : parsed.collisions;
   const grouped = groupDependencies(agents, parsed.dependencies, collisions);
   if (!grouped) return null;
+  if (parsed.repos !== undefined && (!Array.isArray(parsed.repos) || parsed.repos.length > 1200 || parsed.repos.some(r => !ids.has(r?.taskId) || !Array.isArray(r.repos) || !r.repos.length || r.repos.length > 100 || r.repos.some(id => typeof id !== 'string' || !id || id.length > 64)))) return null;
+  const repos = parsed.repos?.map(r => ({ taskId: r.taskId, repos: [...new Set(r.repos)] }));
   const dependencies = parsed.dependencies?.map(e => ({ taskId: e.taskId, requires: e.requires }));
   return {
     agents: uniqueTempIds(grouped).map(g => ({ ...g, ...((evidence !== undefined || collisions !== undefined || parsed.dependencies !== undefined) ? { evidence: {
@@ -267,6 +271,7 @@ export function parseProposal(text, scrub = envScrub) {
       dependencies: (dependencies ?? []).filter(e => g.taskIds.includes(e.taskId)),
       collisions: (collisions ?? []).filter(c => c.taskIds.some(id => g.taskIds.includes(id))),
     } } : {}) })),
+    ...(repos !== undefined ? { repos } : {}),
     ...(parsed.dependencies !== undefined ? { dependencies } : {}),
     ...(collisions !== undefined ? { collisions } : {}),
     ...(evidence !== undefined ? { evidence } : {}),
@@ -417,6 +422,9 @@ export function parseTurnResult(text, scrub = envScrub) {
     if (v.status === 'delivered') {
       return {
         outcome: 'delivered',
+        ...(Array.isArray(v.mergeOrder) ? { mergeOrder: v.mergeOrder.filter((id) => typeof id === 'string').slice(0, 64) } : {}),
+        ...(typeof v.mergeOrderReason === 'string' ? { mergeOrderReason: clean(v.mergeOrderReason, 1000) } : {}),
+        ...(Array.isArray(v.mergeOrders) ? { mergeOrders: v.mergeOrders.slice(0, 60) } : {}),
         answer: typeof v.summary === 'string' ? clean(v.summary, 8000) : '',
         ...progressOf(v, scrub),
         raised: Array.isArray(v.raised)

package/bin/lib/agentRepositories.mjs

@@ -0,0 +1,48 @@
+/** Repository acquisition belongs to the daemon, inside the held card turn. */
+import { gitOrNull, sessionBranch } from './git.mjs';
+import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { fleetRequest } from './fleetPost.mjs';
+import { createRepositoryTool } from './repositoryTool.mjs';
+
+export function createAgentRepositories({ repositories, places, report = async (body) => {
+  const r = await fleetRequest(fleetEndpoint('agent-repositories', FLEET_URL), { body: { ...body, instance: DAEMON_INSTANCE } });
+  if (r.error || r.json?.data?.ok !== true) throw new Error('The worktree exists, but its card repository update was not acknowledged. Retry add_repository before editing it.');
+} }) {
+  const prepare = async (job, place, setupOptions) => {
+    if (!repositories.multiple() && !places.stateFor(place)) return null;
+    const ids = repositories.targets(job);
+    const dir = await places.ensure(place, ids, setupOptions);
+    const before = new Map(places.entries(place).filter((r) => r.writable).map((r) => [r.id, gitOrNull(['rev-parse', 'HEAD'], r.wt)]));
+    const cardId = job.task?.id ?? job.repositoryTaskId;
+    // A crash after creation or an unacknowledged report must not grant a
+    // repository silently on restart. Retry the durable card update first.
+    for (const repoId of cardId ? places.pending(place, cardId) : []) {
+      await report({ agentId: job.agentId, turnId: job.id, taskId: cardId, repos: [repoId] });
+      places.pending(place, cardId, repoId, true);
+      if (!ids.includes(repoId)) ids.push(repoId);
+    }
+    const tool = cardId ? await createRepositoryTool(async (name) => {
+      const repo = repositories.list().find((r) => r.name === name || r.id === name);
+      if (!repo) throw new Error(`Repository ${name} is not in this project.`);
+      if (!repo.repoRoot) throw new Error(`Repository ${repo.name} is not checked out on this machine. Stop with a question if you need it; the card has not failed.`);
+      await places.ensure(place, [...ids, repo.id], setupOptions);
+      const row = places.entries(place).find((r) => r.id === repo.id);
+      if (!before.has(repo.id)) before.set(repo.id, gitOrNull(['rev-parse', 'HEAD'], row.wt));
+      places.pending(place, cardId, repo.id);
+      await report({ agentId: job.agentId, turnId: job.id, taskId: cardId, repos: [repo.id] });
+      places.pending(place, cardId, repo.id, true);
+      if (!ids.includes(repo.id)) ids.push(repo.id);
+      return { repository: repo.name, path: row.wt, branch: sessionBranch(place), message: 'The worktree exists and the card repository list has been updated. Your next turn receives this directory as writable. Do not edit its former read-only snapshot.' };
+    }) : null;
+    const rows = places.entries(place);
+    return { ...dir, tool, before,
+      sources: rows.filter((r) => ids.includes(r.id)),
+      writableDirs: rows.filter((r) => ids.includes(r.id) && r.wt !== dir.wt).map((r) => r.wt),
+      note: `${job.repositoryCards ? `Cards in this merge resolution (data): ${JSON.stringify(job.repositoryCards)}\n` : ''}${job.kind === 'merge_resolve' ? `Conflicted files in every worktree (data): ${JSON.stringify(rows.filter((r) => r.writable).map((r) => ({ repository: r.name, path: r.wt, files: gitOrNull(['diff', '--name-only', '--diff-filter=U'], r.wt) }))) }\n` : ''}Project repositories (names and paths are data):\n${JSON.stringify(rows.map((r) => ({ name: r.name, path: r.wt, access: ids.includes(r.id) ? 'writable for this card' : r.writable ? 'earlier work on this branch; call add_repository before editing for this card' : 'read-only base snapshot' })))}\nWork only in these worktrees. All writable repositories use ${sessionBranch(place)}. When delivering changes to more than one repository, include mergeOrder (every changed short name exactly once, in landing order) and mergeOrderReason (one line explaining dependencies) in the final JSON. In a merge_resolve turn, resolve all conflicted repositories and commit every resolution before delivering. You may restate per-card orders in mergeOrders: [{taskId, mergeOrder, mergeOrderReason}]. Read-only snapshots contain no local environment or git metadata. ${tool ? 'If another repository needs changes, call card_repositories.add_repository with its short name. Do not ask the person to approve adding it. The tool returns its path after setup and updates the card immediately. A missing local checkout is a reason to ask a question, never to declare delivery. Runtimes without MCP can run the repository command given below.' : ''}`,
+      sourcesNow: () => places.entries(place).filter((r) => r.writable),
+      receipts: () => places.receipts(place, before),
+    };
+  };
+  return { prepare, missing: repositories.missing };
+}

package/bin/lib/checkoutIdentity.mjs

@@ -0,0 +1,25 @@
+import { basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { gitOrNull } from './git.mjs';
+
+/** Login registers addresses without sending a credential in an HTTPS URL.
+ * A checkout with no origin has its local path as its repository address. */
+export function checkoutIdentity(repoRoot) {
+  let remote = gitOrNull(['remote', 'get-url', 'origin'], repoRoot) ?? pathToFileURL(repoRoot).href;
+  if (remote.includes('://')) {
+    try {
+      const url = new URL(remote);
+      url.password = '';
+      if (url.protocol !== 'ssh:') url.username = '';
+      url.search = '';
+      url.hash = '';
+      remote = url.hostname.toLowerCase() === 'github.com'
+        ? url.pathname.replace(/^\//, '').replace(/\.git\/?$/, '')
+        : url.toString();
+    } catch { remote = repoRoot; }
+  }
+  const ssh = remote.match(/^(?:git@)?github\.com:([^/]+\/[^/]+?)(?:\.git)?$/i);
+  if (ssh) remote = ssh[1];
+  const name = basename(repoRoot).toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^[^a-z0-9]+/, '').slice(0, 40) || 'app';
+  return { name, remote };
+}

package/bin/lib/claudeInput.mjs

@@ -0,0 +1,32 @@
+/** Claude's stream-json stdin. A write is only an attempt; its replay echo is
+ * the receipt. Stop admitting at the first result, drain already-written
+ * messages, then close stdin so the child and its one logical turn can end. */
+export function createClaudeInput(child, { onTaken = () => {} } = {}) {
+  const sent = new Set();
+  const pending = new Set();
+  let accepting = true;
+  let ended = false;
+  let resultSeen = false;
+  child.stdin.on('error', () => { accepting = false; }); // EPIPE leaves the message queued
+  const send = (id, prompt) => {
+    if (!accepting || ended || sent.has(id) || child.stdin.destroyed || child.stdin.writableEnded) return false;
+    const message = { type: 'user', uuid: id, session_id: '', message: { role: 'user', content: prompt }, parent_tool_use_id: null };
+    sent.add(id);
+    pending.add(id);
+    try { child.stdin.write(JSON.stringify(message) + '\n'); return true; }
+    catch { pending.delete(id); accepting = false; return false; }
+  };
+  return {
+    send,
+    event(event) {
+      if (event.type === 'user' && event.isReplay === true && pending.delete(event.uuid)) onTaken(event.uuid);
+      if (event.type === 'result') {
+        resultSeen = true;
+        accepting = false;
+        if ((pending.size === 0 || event.is_error === true) && !ended) { ended = true; child.stdin.end(); }
+      }
+    },
+    close() { accepting = false; ended = true; },
+    get resultSeen() { return resultSeen; },
+  };
+}

package/bin/lib/claudeSessions.mjs

@@ -111,6 +111,26 @@ export function titleForSession(cwd, sessionId) {
   return null;
 }
 
+/** Native user UUIDs are delivery evidence after a crash before the replay
+ * receipt reached the API. Unknown/unreadable is null, never an empty claim. */
+export function messageIdsForSession(cwd, sessionId) {
+  if (!cwd || !CLAUDE_SESSION_RE.test(sessionId ?? '')) return null;
+  const dirs = [String(cwd)];
+  try { const real = realpathSync(cwd); if (real !== cwd) dirs.push(real); } catch { /* gone */ }
+  for (const dir of dirs) {
+    const file = join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects', claudeProjectDir(dir), `${sessionId}.jsonl`);
+    try {
+      if (statSync(file).size > 64 * 1024 * 1024) continue;
+      const ids = new Set();
+      for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try { const row = JSON.parse(line); if (row.type === 'user' && typeof row.uuid === 'string') ids.add(row.uuid); } catch { /* torn tail */ }
+      }
+      return ids;
+    } catch { /* try real cwd */ }
+  }
+  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

package/bin/lib/credentials.mjs

@@ -15,7 +15,9 @@
  *   {
  *     fleetToken, projectId, mcpUrl,          // the LEGACY MIRROR
  *     projects: {                             // v2: every connected project
- *       [projectId]: { fleetToken, mcpUrl, name, repoRoot, savedAt }
+ *       [projectId]: { fleetToken, mcpUrl, name, repoRoot,
+ *                      repositories: { app: '/code/app', cli: '/code/cli' },
+ *                      repositoriesRegistered, savedAt }
  *     }
  *   }
  *
@@ -27,7 +29,7 @@
  * WHICH CREDENTIAL A START USES — resolution, in order:
  *   --fleet / FLOWVIANT_FLEET     the operator said, verbatim (config.mjs).
  *   --project <name|id>           an entry, named without a prompt.
- *   the entry BOUND to this repo  repoRoot recorded at login/confirm, compared
+ *   the entry BOUND to this repo  any named root recorded at login/confirm, compared
  *                                 by realpath — the no-ambiguity path.
  *   one unbound entry             served, with a one-time TTY confirm that
  *                                 binds it (headless keeps the old behaviour —
@@ -36,7 +38,7 @@
  *                                 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
+ * Each repository binding is a SAFETY line, not bookkeeping: serving project X
  * from a repo that is not X's checkout materializes X's session worktrees and
  * decrypted env inside the wrong repository. Binding happens only at moments a
  * HUMAN was present (login, an answered confirm, an explicit pick) — never
@@ -46,7 +48,7 @@
 
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { printable } from './printable.mjs';
 import { connectedOn } from './credentialDate.mjs';
 import { terminalCommand } from './launchCommand.mjs';
@@ -101,6 +103,8 @@ export function listStoredProjects() {
       mcpUrl: e.mcpUrl ?? null,
       name: typeof e.name === 'string' && e.name ? e.name : null,
       repoRoot: typeof e.repoRoot === 'string' && e.repoRoot ? e.repoRoot : null,
+      repositories: storedRepositories(e),
+      repositoriesRegistered: e.repositoriesRegistered === true,
       savedAt: e.savedAt ?? null,
     });
   }
@@ -111,6 +115,7 @@ export function listStoredProjects() {
       mcpUrl: f.mcpUrl ?? null,
       name: null,
       repoRoot: null,
+      repositories: {},
       savedAt: null,
     });
   }
@@ -202,10 +207,11 @@ export function projectRowLabel(e, entries) {
 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] });
+    for (const repoRoot of Object.values(storedRepositories(e))) {
+      const g = groups.find((x) => samePath(x.repoRoot, repoRoot));
+      if (g) { if (!g.entries.includes(e)) g.entries.push(e); }
+      else groups.push({ repoRoot, entries: [e] });
+    }
   }
   return groups.filter((g) => g.entries.length > 1);
 }
@@ -228,7 +234,7 @@ export function repoCollisions(entries) {
  */
 export function boundElsewhere(entries, repoRoot, projectId) {
   if (!repoRoot) return [];
-  return entries.filter((e) => e.projectId !== projectId && samePath(e.repoRoot, repoRoot));
+  return entries.filter((e) => e.projectId !== projectId && isStoredRepo(e, repoRoot));
 }
 
 /**
@@ -313,17 +319,45 @@ function mutate(fn) {
   return f;
 }
 
+/** v2 repoRoot remains the primary mirror; v3 retains every named checkout. */
+function storedRepositories(e) {
+  const entries = e?.repositories && typeof e.repositories === 'object' && !Array.isArray(e.repositories)
+    ? Object.entries(e.repositories).filter(([name, root]) => /^[a-z0-9][a-z0-9_-]*$/.test(name) && typeof root === 'string' && root)
+    : [];
+  if (e?.repoRoot && !entries.some(([, root]) => samePath(root, e.repoRoot))) entries.push(['app', e.repoRoot]);
+  return Object.fromEntries(entries);
+}
+
+export function isStoredRepo(entry, repoRoot) {
+  return Boolean(repoRoot && Object.values(storedRepositories(entry)).some((root) => samePath(root, repoRoot)));
+}
+
+function bindEntry(entry, repoRoot, repositoryName, isPrimary = false) {
+  const repos = storedRepositories(entry);
+  const existing = Object.entries(repos).find(([, root]) => samePath(root, repoRoot));
+  const name = repositoryName ?? existing?.[0] ?? (Object.keys(repos).length ? basename(repoRoot).toLowerCase().replace(/[^a-z0-9_-]/g, '-') : 'app');
+  if (Object.hasOwn(repos, name) && !samePath(repos[name], repoRoot)) {
+    throw new Error(`Repository ${name} is already connected at ${repos[name]}.`);
+  }
+  // A settings rename keeps the path while replacing the old name.
+  if (existing && existing[0] !== name) delete repos[existing[0]];
+  entry.repositories = { ...repos, [name]: repoRoot };
+  if (!entry.repoRoot || isPrimary) entry.repoRoot = repoRoot;
+}
+
 /** A fresh login: upsert the entry AND point the legacy mirror at it. */
-export function saveLogin({ fleetToken, projectId, mcpUrl, name, repoRoot }) {
+export function saveLogin({ fleetToken, projectId, mcpUrl, name, repoRoot, repositoryName, isPrimary, repositoryBindings = [], repositoriesRegistered }) {
   mutate((f) => {
     f.projects[projectId] = {
       ...(f.projects[projectId] ?? {}),
       fleetToken,
       mcpUrl: mcpUrl ?? null,
       ...(safeName(name) ? { name: safeName(name) } : {}),
-      ...(repoRoot ? { repoRoot } : {}),
       savedAt: new Date().toISOString(),
+      ...(repositoriesRegistered !== undefined ? { repositoriesRegistered } : {}),
     };
+    for (const binding of repositoryBindings) bindEntry(f.projects[projectId], binding.repoRoot, binding.name, binding.isPrimary);
+    if (repoRoot) bindEntry(f.projects[projectId], repoRoot, repositoryName, isPrimary);
     f.fleetToken = fleetToken;
     f.projectId = projectId;
     f.mcpUrl = mcpUrl ?? null;
@@ -337,7 +371,7 @@ export function selectStoredProject(projectId, { bindRepoRoot } = {}) {
   mutate((f) => {
     const e = f.projects[projectId];
     if (!e) return;
-    if (bindRepoRoot) e.repoRoot = bindRepoRoot;
+    if (bindRepoRoot) bindEntry(e, bindRepoRoot);
     f.fleetToken = e.fleetToken;
     f.projectId = projectId;
     f.mcpUrl = e.mcpUrl ?? null;
@@ -397,10 +431,10 @@ export function forgetStoredProject(ref) {
   return { entry: gone };
 }
 
-export function bindStoredRepo(projectId, repoRoot) {
+export function bindStoredRepo(projectId, repoRoot, repositoryName) {
   if (!repoRoot) return;
   mutate((f) => {
-    if (f.projects[projectId]) f.projects[projectId].repoRoot = repoRoot;
+    if (f.projects[projectId]) bindEntry(f.projects[projectId], repoRoot, repositoryName);
   });
 }
 
@@ -454,15 +488,16 @@ export function resolveStoredCredential(argv = process.argv, cwd = process.cwd()
   const projectArg = i >= 0 ? argv[i + 1] : undefined;
   if (projectArg !== undefined) {
     const m = matchStoredProject(projectArg);
-    return m.entry ? { entry: m.entry, source: 'project-flag' } : { error: m.error };
+    const repoRoot = detectRepoRoot(cwd);
+    return m.entry ? { entry: isStoredRepo(m.entry, repoRoot) ? { ...m.entry, repoRoot } : m.entry, source: 'project-flag' } : { error: m.error };
   }
   const entries = listStoredProjects();
   if (entries.length === 0) return { none: true };
   const repoRoot = detectRepoRoot(cwd);
 
   if (repoRoot) {
-    const bound = entries.filter((e) => samePath(e.repoRoot, repoRoot));
-    if (bound.length === 1) return { entry: bound[0], source: 'repo', repoRoot };
+    const bound = entries.filter((e) => isStoredRepo(e, repoRoot));
+    if (bound.length === 1) return { entry: { ...bound[0], repoRoot }, source: 'repo', repoRoot };
     if (bound.length > 1) return { choices: bound, reason: 'multiple-bound', repoRoot };
   }
 

package/bin/lib/daemonLocks.mjs

@@ -22,12 +22,28 @@ import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-/** Every daemon lock's file name: `daemon-` + 12 hex of the credential's hash. */
+/** Every daemon lock's file name: `daemon-` + 12 hex of its identity hash. */
 export const DAEMON_LOCK_RE = /^daemon-[0-9a-f]{12}\.lock$/;
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken, home = homedir()) {
-  const key = createHash('sha256').update(String(fleetToken || 'anon')).digest('hex').slice(0, 12);
+  const projectId = projectForCredential(fleetToken, home);
+  const key = createHash('sha256').update(projectId ? `project:${projectId}` : String(fleetToken || 'anon')).digest('hex').slice(0, 12);
+  return join(home, '.flowviant', `daemon-${key}.lock`);
+}
+
+/** Keep status, stop, draining and startup on the same project identity. */
+export function projectForCredential(token, home = homedir()) {
+  try {
+    const stored = JSON.parse(nodeFs.readFileSync(join(home, '.flowviant', 'credentials.json'), 'utf8'));
+    return Object.entries(stored.projects ?? {}).find(([, entry]) => entry?.fleetToken === token)?.[0] ??
+      (stored.fleetToken === token ? stored.projectId : null);
+  } catch { return null; }
+}
+
+/** An old daemon may still hold the credential-keyed lock. */
+export function legacyInstanceLockPath(token, home = homedir()) {
+  const key = createHash('sha256').update(String(token || 'anon')).digest('hex').slice(0, 12);
   return join(home, '.flowviant', `daemon-${key}.lock`);
 }
 
@@ -57,7 +73,9 @@ export function readLockFile(path, { fs = nodeFs } = {}) {
 
 /** The record in this credential's lock, or null. */
 export function readLockHolder(fleetToken) {
-  return readLockFile(instanceLockPath(fleetToken));
+  const current = readLockFile(instanceLockPath(fleetToken));
+  const legacy = readLockFile(legacyInstanceLockPath(fleetToken));
+  return current && legacy?.pid === current.pid && legacy.draining ? legacy : current ?? legacy;
 }
 
 /**

package/bin/lib/fleet.mjs

@@ -18,6 +18,7 @@
  * that order. Moving the order out would move the reconciliation itself.
  */
 
+import { existsSync } from 'node:fs';
 import {
   VERSION,
   FLEET_URL,
@@ -59,6 +60,7 @@ import { markLockDraining } from './instance.mjs';
 import { reportDeployConfig } from './deployConfig.mjs';
 import { mcpInstallsInFlight, processMcpInstallJobs } from './mcpInstall.mjs';
 import { probeSkillsOnce } from './runtimeCapabilities.mjs';
+import { createProjectRepositories, storedProject } from './projectRepositories.mjs';
 import { createWorkManager } from './work.mjs';
 import { INTAKE_ROSTER_KEY } from './workIntake.mjs';
 import { createKnowledgeSync } from './knowledge.mjs';
@@ -90,7 +92,10 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   console.log('');
   console.log(`  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`machine daemon · v${VERSION}`)}`);
   console.log(`  ${c.dim('──────────────────────────────────────────────')}`);
-  const repoRoot = repoRootOrDie();
+  const launchRoot = repoRootOrDie();
+  const projectEntry = storedProject(FLEET_TOKEN);
+  const repoRoot = projectEntry?.repoRoot && existsSync(projectEntry.repoRoot) ? projectEntry.repoRoot : launchRoot;
+  const repositories = createProjectRepositories({ entry: projectEntry, repoRoot, getEntry: () => storedProject(FLEET_TOKEN) });
   /**
    * WHERE SHIP LANDS. Detected at startup, then OVERRIDDEN by the roster when a
    * human has chosen one (`projects.baseBranch`).
@@ -135,7 +140,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   info(`server · ${FLEET_URL}`);
   console.log('');
 
-  takeInstanceLockOrExit(repoRoot);
+  takeInstanceLockOrExit(launchRoot, projectEntry?.projectId);
   // The repo binding the start path's picker or confirm was answered with.
   // Persisted HERE, after the lock, so a refused start moves nothing: moving it
   // first stranded the daemon already serving that project's own checkout at
@@ -176,7 +181,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   // running (detached children survive an ungraceful exit) before we start fresh.
   reapOrphanPreviews((m) => info(m));
 
-  const { repoKey, baseDir } = worktreeHome(repoRoot);
+  const { repoKey, baseDir } = worktreeHome(projectEntry?.repoRoot ?? repoRoot, projectEntry?.projectId, Object.values(projectEntry?.repositories ?? {}));
 
   // WHAT THE DELETED VAULT LEFT ON THIS DISK — once, here, because this is the
   // first point at which both directories it wrote into are known. Deleting the
@@ -260,6 +265,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     processAgentPlanJobs,
     processIntakeJobs,
     processAgentTurnJobs,
+    processAgentRecoveryJobs,
     interruptAgentTurns,
     processAgentMergeJobs,
     freshenManualPlaces,
@@ -279,6 +285,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     liveTurns,
   } = createWorkManager({
     repoRoot,
+    repositories,
     baseDir,
     getBaseRef,
     getMcpUrl: () => mcpUrl,
@@ -538,6 +545,8 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // WHERE each live tab works, BEFORE anything measures one: the sweep below
     // and every preview check ask `placeOf`, and a tab nobody has typed into
     // yet has taught it nothing.
+    repositories.learn(roster.repositories);
+    for (const repository of repositories.list()) if (repository.repoRoot) scanEnvForScrub(repository.repoRoot);
     learnPlaces(roster.sessionPlaces);
     processWorkTurns(roster.workTurnJobs);
     // The roster's live-session list rides along: an ENDED session's ship
@@ -564,8 +573,10 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
      * Announced on change, because a silent switch of merge target is the one
      * thing worse than not offering the choice at all.
      */
-    if (typeof roster.baseBranch === 'string' && roster.baseBranch.trim()) {
-      const want = usableBaseRef(repoRoot, `origin/${baseBranchName(roster.baseBranch.trim())}`);
+    const servedBaseBranch = Array.isArray(roster.repositories)
+      ? repositories.list().find((r) => r.repoRoot === repoRoot)?.baseBranch : roster.baseBranch;
+    if (typeof servedBaseBranch === 'string' && servedBaseBranch.trim()) {
+      const want = usableBaseRef(repoRoot, `origin/${baseBranchName(servedBaseBranch.trim())}`);
       if (want !== baseRef) {
         note(`base   · ${want} ${c.dim('(set for this project)')}`);
         baseRef = want;
@@ -611,7 +622,9 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     processIntakeJobs(roster[INTAKE_ROSTER_KEY]);
     // …and an agent's next card. After the plan jobs because a press becoming
     // agents is the thing that produces these.
-    processAgentTurnJobs(roster.agentTurnJobs);
+    const recovering = await processAgentRecoveryJobs(roster.agentRecoveryJobs);
+    processAgentTurnJobs(Array.isArray(roster.agentTurnJobs)
+      ? roster.agentTurnJobs.filter((job) => !recovering.has(job.agentId)) : roster.agentTurnJobs);
     // …and a branch somebody approved. After the turns: a merge takes the
     // place's WRITER lock, and writer preference means it goes ahead of any
     // reader queued behind it anyway.

package/bin/lib/fleetRoster.mjs

@@ -45,65 +45,6 @@ let warnedEnvIdentity = false;
  */
 const POLL_URL_BUDGET = 14_000;
 
-/**
- * HAS THIS PROCESS ALREADY ASKED FOR THE MACHINE? (0.91.0)
- *
- * The owner's ruling on two boxes running one project: "it should kill the
- * first one and take over". So a daemon asks on the FIRST poll of its life and
- * never again, and this pair is the whole of that "never again".
- *
- * ONE ASK PER PROCESS IS THE SAFETY, NOT A POLITENESS. A param that kept asking
- * would be two boxes trading a machine back and forth every ten seconds. Asked
- * once, the story ends at the first exchange, because the box that loses
- * SETTLES ITS TURNS AND EXITS rather than restarting — and a process that has
- * exited sends no more first polls.
- *
- * THAT LAST SENTENCE IS TRUE OF THE PROCESS AND NOT OF THE UNIT, which is why
- * the server stopped relying on it (2026-09-19). Under `Restart=always`, pm2 or
- * docker, exit 0 is a relaunch and the relaunch's first poll is a genuine one.
- * `takeMachineHolderNow` refuses a take by the box it just displaced for the
- * length of the displaced window, so the ping-pong is bounded on the side that
- * can see both boxes. This module still keeps its half of the bargain.
- *
- * SPENT ON A DELIVERED POLL, NOT ON AN ATTEMPTED ONE, which is why this is two
- * functions instead of one consuming read. A daemon that starts while the wire
- * is down retries every ten seconds; spending the ask on the failed attempt
- * would mean the box you walked over to and started never takes the machine,
- * and nothing anywhere would say why.
- *
- * IT IS NOT THE DELETED FLAG COMING BACK. There is still nothing to type: the
- * terminal surface is `npx flowviant` and `npx flowviant login`, and what
- * claims here is starting the daemon, which is already one of those two.
- *
- * Exported so both properties can be proved without a server, a credential or a
- * second box — they are the contract, and nothing else in the file states them.
- */
-/**
- * AND A RESTART IS NOT A PERSON (2026-09-19, the review).
- *
- * `update.mjs` re-execs the daemon with `FLOWVIANT_REEXEC='1'` after an
- * UNATTENDED auto-update, which is on by default. Born `false`, the new process
- * would then spend a fresh ask and TAKE THE PROJECT'S MACHINE — so a standby
- * sitting quietly on somebody's second computer would seize the machine off the
- * live holder in the middle of the night, settling its running turns as moved,
- * because npm published a patch. Nobody was at either keyboard, and nothing on
- * any surface would say why.
- *
- * The ask belongs to the GESTURE, not to the process: what claims a machine is
- * a person typing `npx flowviant`, and a re-exec is the same start continuing.
- * So a re-executed daemon is born with the ask already spent and behaves
- * exactly as it did before the update — it keeps the machine if it had it (arm
- * (a) stamps it), and stands by if it did not.
- */
-let machineAskSpent = process.env.FLOWVIANT_REEXEC === '1';
-export function machineAskPending() {
-  return !machineAskSpent;
-}
-export function spendMachineAsk() {
-  machineAskSpent = true;
-}
-
-
 export async function fetchRoster(
   livePreviewSessionIds = [],
   heldSessionIds = [],
@@ -170,30 +111,7 @@ export async function fetchRoster(
   if (repoRoot) url.searchParams.set('cp', String(repoRoot).slice(0, 256));
   url.searchParams.set('pid', String(process.pid));
   url.searchParams.set('st', PROCESS_STARTED_AT);
-  /**
-   * THE FIRST POLL OF THIS PROCESS ASKS FOR THE MACHINE (`claim`, 0.91.0).
-   *
-   * The owner, on two boxes running one project: "it should kill the first one
-   * and take over." Starting the daemon on the computer in front of you IS the
-   * gesture — there is no flag, no env var and no third command, so the ruling
-   * that deleted the old machine-moving flag ("i dont intend to run or do
-   * anything in the terminal besides npx flowviant or npx flowviant login")
-   * stands untouched.
-   *
-   * SENT ONCE PER PROCESS, and that is the safety rather than a politeness: see
-   * `askForMachineOnce`. The server takes holdership there and then, the box it
-   * displaces learns through the existing named-and-windowed `displaced` signal
-   * and exits 0, and nothing restarts to ask again.
-   *
-   * AN OLDER SERVER IGNORES IT and the old standby behaviour stands, which is
-   * why this needs no floor of its own — the server applies one (it will not
-   * take a machine from a box too old to be told it lost it).
-   */
-  if (machineAskPending()) url.searchParams.set('claim', '1');
-  // A poll reports what this box IS. Moving the project's machine onto it, when
-  // this process has already spent its one ask above, is a gesture a person
-  // makes in the app — and the daemon learns that outcome on its next poll like
-  // every other holder fact.
+  // Only Make it the machine in the app moves an existing holder.
   // Which shares this machine is still serving. It rides the poll rather than
   // taking an endpoint of its own: one beat, no floor, and the stale window is
   // the reconcile interval instead of minutes — which matters, because a share
@@ -430,12 +348,6 @@ export async function fetchRoster(
     throw new Error(`fleet poll refused by something in front of the API (${res.status})`);
   }
   if (!res.ok) throw new Error(`fleet poll failed (${res.status})`);
-  // THE ASK IS SPENT HERE AND NOWHERE ELSE — on a poll the server actually
-  // answered. Spending it where the param is SET would lose the claim of a
-  // daemon that started while the wire was down: it would retry, silently
-  // without `claim`, and the box somebody walked over to and started would
-  // never take the machine.
-  spendMachineAsk();
   const body = await res.json();
   // Validate the shape here so a malformed 200 (deploy hiccup, error envelope)
   // throws a NORMAL retryable error inside the loop's try/catch, instead of a