flowviant 0.117.0 → 0.124.1

package/bin/lib/repositoryMerge.mjs

@@ -0,0 +1,116 @@
+/** A place lands as a coordinated set. Positive landings are never undone. */
+import { join } from 'node:path';
+import { git, gitNet as network, gitOrNull, baseBranchName, usableBaseRef, detectBaseRef } from './git.mjs';
+import { gitMergeIn } from './gitMergeIdentity.mjs';
+import { mergeOutward, isRaceRejection } from './shipMerge.mjs';
+import { ensureOpenPr, mergeAndVerifyTip, ghReady, linkRepositoryPrs, relayedFailure } from './prWorkflow.mjs';
+
+export function repositoryMergeOrder(cards, changed) {
+  const edges = new Map(changed.map((id) => [id, new Set()]));
+  for (const card of cards) {
+    const ids = card.repos.filter((id) => changed.includes(id));
+    if (ids.length > 1 && (!card.mergeOrderReason?.trim() || card.mergeOrder.length !== card.repos.length || new Set(card.mergeOrder).size !== card.repos.length || card.repos.some((id) => !card.mergeOrder.includes(id)))) throw new Error(`Card ${card.id} needs a merge order covering every changed repository and a reason.`);
+    const order = card.mergeOrder.filter((id) => ids.includes(id));
+    for (let i = 1; i < order.length; i++) edges.get(order[i - 1]).add(order[i]);
+  }
+  const result = [];
+  while (result.length < changed.length) {
+    const next = changed.find((id) => !result.includes(id) && ![...edges].some(([from, to]) => !result.includes(from) && to.has(id)));
+    if (!next) throw new Error('The delivered cards specify conflicting merge orders. Restate a consistent order for these cards.');
+    result.push(next);
+  }
+  return result;
+}
+
+export async function mergeRepositoryPlace({ job, entries, baseDir, progress, check, gitNet = network,
+  land = mergeOutward, pr = { ghReady, ensureOpenPr, mergeAndVerifyTip, linkRepositoryPrs } }) {
+  const spec = job.repositoryMerge;
+  const ids = [...new Set(spec.cards.flatMap((c) => c.repos))];
+  const rows = ids.map((id) => {
+    const row = entries.find((r) => r.id === id && r.writable);
+    if (!row?.repoRoot) throw new Error(`Repository ${spec.repositories.find((r) => r.id === id)?.name ?? id} has no writable worktree on this machine.`);
+    const configured = spec.repositories.find((r) => r.id === id);
+    return { ...row, name: configured?.name ?? row.name, configuredBase: configured?.baseBranch };
+  });
+  const states = structuredClone(spec.progress ?? {});
+  const report = async (retry = false) => progress(states, retry);
+  const ancestor = (a, b, wt) => { try { git(['merge-base', '--is-ancestor', a, b], wt); return true; } catch { return false; } };
+  const fetch = (r) => {
+    if (gitOrNull(['remote', 'get-url', 'origin'], r.repoRoot)) gitNet(['fetch', 'origin', '--quiet'], r.repoRoot, 60_000);
+    r.baseRef = r.configuredBase ? usableBaseRef(r.repoRoot, `origin/${baseBranchName(r.configuredBase)}`) : detectBaseRef(r.repoRoot);
+    r.baseTip = git(['rev-parse', r.baseRef], r.repoRoot);
+  };
+  let order;
+  try { order = repositoryMergeOrder(spec.cards, ids); }
+  catch (e) { return { ok: false, conflict: true, detail: e.message }; }
+  if (job.prMode && pr.ghReady()) return { ok: false, fix: 'person', detail: 'GitHub CLI is not installed or signed in on this machine.' };
+  // Yield the lease after bounded races, retaining approval and all observations.
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const pending = [], conflicts = [];
+    for (const r of rows) {
+      fetch(r);
+      const head = git(['rev-parse', 'HEAD'], r.wt);
+      if (ancestor(head, r.baseTip, r.wt)) { states[r.id] = { ...states[r.id], head, landed: head }; continue; }
+      pending.push(r);
+      try { gitMergeIn(r.repoRoot)(['merge', '--no-edit', r.baseTip], r.wt); }
+      catch (e) {
+        const files = git(['diff', '--name-only', '--diff-filter=U'], r.wt).trim();
+        if (files || gitOrNull(['rev-parse', '--verify', 'MERGE_HEAD'], r.wt)) conflicts.push(`${r.name} (${r.wt}):\n${files || relayedFailure(e)}`);
+        else throw e;
+      }
+      states[r.id] = { ...states[r.id], head: git(['rev-parse', 'HEAD'], r.wt) };
+    }
+    await report();
+    if (conflicts.length) return { ok: false, conflict: true, detail: `Resolve and commit every conflicted repository in this place before any remaining repository lands:\n${conflicts.join('\n\n')}` };
+    // All branches have caught up. A failing repository prevents every new landing.
+    const failed = [];
+    for (const r of pending) {
+      await report();
+      const result = await check(r);
+      await report();
+      if (result?.status !== 'passed' && result?.status !== 'none') failed.push(r.name);
+      else if (git(['rev-parse', 'HEAD'], r.wt) !== states[r.id].head) failed.push(`${r.name} (branch changed during its check)`);
+    }
+    if (failed.length) return { ok: false, fix: 'person', detail: `Repository checks failed or could not be measured: ${failed.join(', ')}. Review the checks before approving again.` };
+    if (job.prMode) {
+      for (const r of pending) {
+        const branch = git(['symbolic-ref', '--quiet', '--short', 'HEAD'], r.wt);
+        if (branch === baseBranchName(r.baseRef)) throw new Error(`Refusing to publish ${r.name}'s base as a PR branch.`);
+        gitNet(['push', '-u', 'origin', branch], r.wt, 120_000);
+        const opened = pr.ensureOpenPr(branch, baseBranchName(r.baseRef), { cwd: r.wt });
+        if (opened.error || opened.wrongBase || !opened.url) return { ok: false, fix: 'person', detail: opened.error || `No verified pull request for ${r.name}.` };
+        states[r.id].prUrl = opened.url;
+      }
+      await report();
+      for (const r of pending) await pr.linkRepositoryPrs(states[r.id].prUrl, { cwd: r.wt, cards: spec.cards, order, repositories: spec.repositories, states });
+    }
+    let raced = false;
+    for (const id of order) {
+      const r = pending.find((r) => r.id === id);
+      if (!r) continue;
+      // Refuse a changed base before landing. Another writer can still win the push.
+      fetch(r);
+      if (!ancestor(r.baseTip, 'HEAD', r.wt)) { raced = true; break; }
+      const head = git(['rev-parse', 'HEAD'], r.wt);
+      const branch = git(['symbolic-ref', '--quiet', '--short', 'HEAD'], r.wt);
+      try {
+        if (job.prMode) {
+          const merged = await pr.mergeAndVerifyTip(branch, { cwd: r.wt, tip: head, baseRef: () => r.baseRef, repoRoot: r.repoRoot, fetchOrigin: () => fetch(r) });
+          if (!merged.ok) { fetch(r); if (merged.notOnBase || !ancestor(r.baseTip, 'HEAD', r.wt)) { raced = true; break; } throw new Error(merged.error || `Pull request for ${r.name} has not merged.`); }
+        } else land({ tip: head, count: Number(git(['rev-list', '--count', `${r.baseRef}..HEAD`], r.wt)), branch,
+          label: job.agentName || job.placeId, git, gitMerge: gitMergeIn(r.repoRoot), repoRoot: r.repoRoot,
+          tmpDir: join(baseDir, 'ship', `${job.placeId}-${r.id}`), baseRef: () => r.baseRef, baseTip: r.baseTip, workingTree: r.wt, gitNet, retryRace: false });
+      } catch (e) {
+        if (isRaceRejection(e)) { raced = true; break; }
+        return { ok: false, fix: e?.fix === 'person' || job.prMode ? 'person' : 'agent', detail: `${r.name}: ${relayedFailure(e)}` };
+      }
+      fetch(r);
+      if (!ancestor(head, r.baseTip, r.wt)) { raced = true; break; }
+      states[r.id] = { ...states[r.id], head, landed: head };
+      await report();
+    }
+    if (!raced) return { ok: true, sha: states[order.at(-1)]?.head ?? git(['rev-parse', 'HEAD'], entries.find((r) => r.writable).wt) };
+  }
+  await report(true);
+  return { retry: true };
+}

package/bin/lib/repositoryPlaces.mjs

@@ -0,0 +1,179 @@
+/** One durable place manifest; all targeted worktrees share session/<place>.
+ * Untargeted siblings are base snapshots, not links to the operator's checkout.
+ * Read-only file modes prevent ordinary writes; build CLIs still run as the
+ * operator and this is not a security boundary against chmod or privileged code.
+ */
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { git, gitRaw, gitOrNull, isSafePathSegment, sessionBranch } from './git.mjs';
+import { setupRepository } from './repositorySetup.mjs';
+
+export const PLACE_MANIFEST = '.flowviant-place.json';
+export function readRepositoryPlace(home) {
+  try {
+    const row = JSON.parse(readFileSync(join(home, PLACE_MANIFEST), 'utf8'));
+    if (row.version !== 1 || !Array.isArray(row.repositories) ||
+        row.repositories.some((r) => !isSafePathSegment(r.folder) || typeof r.id !== 'string') ||
+        !(row.preparing === true || row.repositories.some((r) => r.id === row.primary && r.writable))) return null;
+    return row;
+  } catch { return null; }
+}
+function modeTree(dir, writable) {
+  const st = lstatSync(dir);
+  if (st.isSymbolicLink()) return;
+  if (writable) chmodSync(dir, st.isDirectory() ? 0o700 : 0o600 | (st.mode & 0o111));
+  if (st.isDirectory()) for (const name of readdirSync(dir)) modeTree(join(dir, name), writable);
+  if (!writable) chmodSync(dir, st.isDirectory() ? 0o500 : 0o400 | (st.mode & 0o111));
+}
+/** The explicit `clean` command also owns these snapshots. Never chmod links. */
+export function unlockRepositorySnapshots(root) {
+  for (const project of readdirSync(root, { withFileTypes: true })) {
+    if (!project.isDirectory()) continue;
+    const sessions = join(root, project.name, 'sessions');
+    if (!existsSync(sessions)) continue;
+    for (const place of readdirSync(sessions)) {
+      if (!isSafePathSegment(place)) continue;
+      const home = join(sessions, place), state = readRepositoryPlace(home);
+      for (const repo of state?.repositories ?? []) if (!repo.writable && existsSync(join(home, repo.folder))) modeTree(join(home, repo.folder), true);
+    }
+  }
+}
+export function createRepositoryPlaces({ repoRoot, baseDir, repositories, setup = setupRepository, changed = () => {} }) {
+  const homeFor = (place) => {
+    if (!isSafePathSegment(place)) throw new Error('Invalid place.');
+    return join(baseDir, 'sessions', place);
+  };
+  const save = (home, state) => {
+    const path = join(home, PLACE_MANIFEST);
+    writeFileSync(`${path}.tmp`, JSON.stringify(state), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+  };
+  const stateFor = (place) => readRepositoryPlace(homeFor(place));
+  const entries = (place) => {
+    const state = stateFor(place);
+    return (state?.repositories ?? []).map((r) => ({ ...r, wt: join(homeFor(place), r.folder),
+      repoRoot: repositories.list().find((repo) => repo.id === r.id)?.repoRoot }));
+  };
+  const ensure = async (place, ids, setupOptions = {}) => {
+    const home = homeFor(place), catalog = repositories.list();
+    for (const id of ids) if (!catalog.find((r) => r.id === id)?.repoRoot)
+      throw new Error(`Repository ${catalog.find((r) => r.id === id)?.name ?? id} is not checked out on this machine.`);
+    const folders = catalog.filter((r) => r.repoRoot).map((r) => basename(r.repoRoot));
+    if (new Set(folders).size !== folders.length || folders.some((f) => !isSafePathSegment(f)))
+      throw new Error('Project checkouts need distinct directory names to create sibling worktrees.');
+    let state = stateFor(place);
+    if (!state) {
+      const primary = catalog.find((r) => r.isPrimary && ids.includes(r.id))?.id ?? catalog.find((r) => ids.includes(r.id))?.id;
+      const old = existsSync(join(home, '.git'));
+      // Upgrade a pre-existing single-repo place without resetting its branch,
+      // private git metadata or dirty files. git moves the registration too.
+      if (old || existsSync(join(`${home}.moving`, '.git'))) {
+        const first = catalog.find((r) => r.repoRoot && git(['worktree', 'list', '--porcelain'], r.repoRoot).split('\n')
+          .some((line) => line === `worktree ${home}` || line === `worktree ${home}.moving`));
+        if (!first?.repoRoot) throw new Error('The checkout owning this worktree is needed to upgrade this place.');
+        const temporary = `${home}.moving`;
+        if (old) git(['worktree', 'move', home, temporary], first.repoRoot);
+        mkdirSync(home, { recursive: true });
+        git(['worktree', 'move', temporary, join(home, basename(first.repoRoot))], first.repoRoot);
+        state = { version: 1, primary: first.id, repositories: [{ id: first.id, name: first.name, folder: basename(first.repoRoot), baseRef: first.baseRef, writable: true, setup: true }] };
+      } else {
+        mkdirSync(home, { recursive: true });
+        state = { version: 1, primary, preparing: true, repositories: [] };
+      }
+      save(home, state);
+    }
+    for (const repo of catalog.filter((r) => r.repoRoot)) {
+      setupOptions.signal?.throwIfAborted();
+      let item = state.repositories.find((r) => r.id === repo.id);
+      let writable = ids.includes(repo.id) || item?.writable === true;
+      const folder = item?.folder ?? basename(repo.repoRoot), wt = join(home, folder);
+      if (existsSync(join(wt, '.git'))) {
+        const registered = git(['worktree', 'list', '--porcelain'], repo.repoRoot).split('\n').includes(`worktree ${wt}`);
+        if (!registered) throw new Error(`The git directory at ${wt} is not this repository's worktree.`);
+        writable = true; // promotion or legacy move completed before its save
+        if (item && !item.writable) { item.writable = true; item.setup = false; }
+      }
+      if (!item) {
+        if (existsSync(wt)) {
+          // Recover the crash window after git moved a legacy place but
+          // before its manifest was saved. Never adopt an unrelated folder.
+          const registered = git(['worktree', 'list', '--porcelain'], repo.repoRoot).split('\n').includes(`worktree ${wt}`);
+          if (!registered) throw new Error(`A directory already exists at ${wt}; it is not this repository's worktree.`);
+        }
+        item = { id: repo.id, name: repo.name, folder, baseRef: repo.baseRef, writable, setup: false };
+        state.repositories.push(item);
+        save(home, state);
+      }
+      item.baseRef = repo.baseRef;
+      item.name = repo.name;
+      const head = gitOrNull(['rev-parse', repo.baseRef], repo.repoRoot);
+      if (item && item.writable === writable && existsSync(wt) && (writable ? item.setup : item.head === head)) continue;
+      if (item && !item.writable && writable && existsSync(wt)) { modeTree(wt, true); rmSync(wt, { recursive: true }); }
+      if (item && !writable && existsSync(wt)) { modeTree(wt, true); rmSync(wt, { recursive: true }); }
+      if (!existsSync(wt)) {
+        if (writable) {
+          const branch = sessionBranch(place);
+          git(['worktree', 'prune'], repo.repoRoot);
+          if (gitOrNull(['show-ref', '--verify', `refs/heads/${branch}`], repo.repoRoot))
+            git(['worktree', 'add', wt, branch], repo.repoRoot);
+          else git(['worktree', 'add', '-b', branch, wt, repo.baseRef], repo.repoRoot);
+        } else {
+          mkdirSync(wt, { recursive: true });
+          // tar extracts only git's archive, never ignored files or credentials.
+          const archive = gitRaw(['archive', '--format=tar', repo.baseRef], repo.repoRoot, { encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 });
+          execFileSync('tar', ['-xf', '-', '-C', wt], { input: archive });
+          modeTree(wt, false);
+        }
+      }
+      item.writable = writable;
+      item.head = head;
+      // Create every sibling before any install. Local file dependencies and
+      // setup hooks must resolve ../cli to this place, never a main checkout.
+      save(home, state);
+    }
+    for (const item of state.repositories.filter((r) => r.writable && !r.setup)) {
+      const repo = catalog.find((r) => r.id === item.id);
+      if (!repo?.repoRoot) throw new Error(`Repository ${item.name} is not checked out on this machine.`);
+      setupOptions.signal?.throwIfAborted();
+      await setup(repo.repoRoot, join(home, item.folder), setupOptions);
+      item.setup = true;
+      save(home, state);
+    }
+    state.preparing = false;
+    save(home, state);
+    changed();
+    return { wt: join(home, state.repositories.find((r) => r.id === state.primary).folder), fresh: false };
+  };
+  const remove = (place) => {
+    const rows = entries(place);
+    if (!rows.length) return false;
+    // Measure every writable repo BEFORE removing any of them.
+    if (rows.some((r) => r.writable && existsSync(r.wt) && (!r.repoRoot || git(['status', '--porcelain'], r.wt)))) return false;
+    for (const row of rows) {
+      if (!existsSync(row.wt)) continue;
+      if (row.writable) git(['worktree', 'remove', row.wt], row.repoRoot);
+      else { modeTree(row.wt, true); rmSync(row.wt, { recursive: true }); }
+    }
+    rmSync(homeFor(place), { recursive: true });
+    changed();
+    return true;
+  };
+  const receipts = (place, before) => entries(place).filter((r) => r.writable).flatMap((r) => {
+    const from = before.get(r.id);
+    if (!from) return [];
+    const out = gitOrNull(['log', '--format=%H', '--no-merges', `${from}..HEAD`, '--not', r.baseRef], r.wt);
+    return out?.split('\n').filter(Boolean).slice(0, 50).map((sha) => ({ sha, repo: r.id })) ?? [];
+  });
+  const pending = (place, taskId, repoId, clear = false) => {
+    const state = stateFor(place);
+    const rows = state.pending ?? [];
+    if (repoId) {
+      state.pending = rows.filter((r) => r.taskId !== taskId || r.repoId !== repoId);
+      if (!clear) state.pending.push({ taskId, repoId });
+      save(homeFor(place), state);
+    }
+    return (state.pending ?? []).filter((r) => r.taskId === taskId).map((r) => r.repoId);
+  };
+  return { ensure, entries, stateFor, remove, receipts, pending };
+}

package/bin/lib/repositorySetup.mjs

@@ -0,0 +1,58 @@
+/** Fresh multi-repository worktrees each get their own environment and install.
+ * A checked-in .flowviant/setup.sh replaces the default dependency install. */
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { spawn } from 'node:child_process';
+import { killGroup } from './processGroup.mjs';
+import { git } from './git.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+export async function setupRepository(root, wt, { signal, onSpawn = () => {}, onClose = () => {} } = {}) {
+  signal?.throwIfAborted();
+  if (workLanesStopped()) throw new Error('The daemon is stopping. Repository setup has not started.');
+  const copyEnv = (relative = '') => {
+    for (const name of readdirSync(join(root, relative))) {
+      if (['.git', 'node_modules', '.flowviant', 'dist', 'target', '.next', '.cache', '.venv'].includes(name)) continue;
+      const rel = join(relative, name), src = join(root, rel), dest = join(wt, rel);
+      const st = lstatSync(src);
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) {
+        if (existsSync(dest)) copyEnv(rel);
+      } else if (/^\.env(?:\.|$)/.test(name) && !existsSync(dest)) {
+        try { git(['check-ignore', '--quiet', '--', rel], wt); } catch { continue; }
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(src, dest);
+        chmodSync(dest, 0o600);
+      }
+    }
+  };
+  copyEnv();
+  const command = existsSync(join(wt, '.flowviant/setup.sh')) ? ['sh', '.flowviant/setup.sh'] :
+    ['bun.lock', 'bun.lockb'].some((f) => existsSync(join(wt, f))) ? ['bun', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'pnpm-lock.yaml')) ? ['pnpm', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'package-lock.json')) ? ['npm', 'ci'] :
+    existsSync(join(wt, 'yarn.lock')) ? ['yarn', 'install', '--frozen-lockfile'] : null;
+  if (!command) return;
+  await new Promise((resolve, reject) => {
+    const child = spawn(command[0], command.slice(1), { cwd: wt, env: unattendedEnv({ ...process.env, GIT_TERMINAL_PROMPT: '0' }), detached: true, stdio: ['ignore', 'ignore', 'pipe'] });
+    const abort = () => killGroup(child);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    onSpawn(child);
+    let tail = '';
+    child.stderr.on('data', (s) => { tail = (tail + s).slice(-2000); });
+    const timer = setTimeout(() => { killGroup(child); }, 10 * 60_000);
+    child.once('error', (e) => { clearTimeout(timer); reject(e); });
+    child.once('close', (code) => {
+      clearTimeout(timer); signal?.removeEventListener('abort', abort); onClose(child);
+      code === 0 ? resolve() : reject(new Error(`${command.join(' ')} failed in ${wt}: ${tail}`));
+    });
+  });
+}
+
+/** Installs are daemon children too: shutdown must drain their process groups. */
+export const trackedRepositorySetup = (children, groups) => (root, wt, options) => setupRepository(root, wt, {
+  ...options, onSpawn: (child) => { children.set(child, null); groups.add(child); },
+  onClose: (child) => { children.delete(child); groups.delete(child); },
+});

package/bin/lib/repositoryTool.mjs

@@ -0,0 +1,71 @@
+/** A held turn's local capability. The CLI never receives the machine token. */
+import { sameSecret } from './grant.mjs';
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { runningCompiledBinary } from './launchCommand.mjs';
+
+export async function createRepositoryTool(add) {
+  const capability = randomBytes(32).toString('hex');
+  let serial = Promise.resolve(), closed = false;
+  const server = createServer(async (req, res) => {
+    if (closed || req.method !== 'POST' || req.url !== '/' || !sameSecret(req.headers.authorization, `Bearer ${capability}`)) {
+      res.writeHead(403).end(); return;
+    }
+    try {
+      let body = '';
+      for await (const data of req) { body += data; if (body.length > 1024) throw new Error('Repository request is too large.'); }
+      const { name } = JSON.parse(body);
+      if (typeof name !== 'string' || !name.length || name.length > 64) throw new Error('Name a project repository.');
+      // A current turn already owns its place's writer lock. Serialize its
+      // acquisitions here instead of recursively waiting for that same lock.
+      const pending = serial.then(() => { if (closed) throw new Error('This turn has ended.'); return add(name); });
+      serial = pending.catch(() => {});
+      const result = await pending;
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify(result));
+    } catch (error) {
+      res.writeHead(409, { 'Content-Type': 'application/json' }).end(JSON.stringify({ error: String(error.message).slice(0, 2000) }));
+    }
+  });
+  server.requestTimeout = 15_000;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const env = { FLOWVIANT_REPOSITORY_URL: `http://127.0.0.1:${server.address().port}/`, FLOWVIANT_REPOSITORY_CAPABILITY: capability };
+  const args = runningCompiledBinary() ? ['__repository-mcp'] : [fileURLToPath(new URL('../cli.mjs', import.meta.url)), '__repository-mcp'];
+  return { env, config: { command: process.execPath, args, env },
+    async close() { closed = true; server.close(); server.closeIdleConnections(); await serial; server.closeAllConnections(); } };
+}
+
+async function callRepository(name) {
+  const url = new URL(process.env.FLOWVIANT_REPOSITORY_URL);
+  if (url.hostname !== '127.0.0.1' || url.protocol !== 'http:') throw new Error('No held card repository tool is available.');
+  const res = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_REPOSITORY_CAPABILITY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name }), signal: AbortSignal.timeout(12 * 60_000) });
+  const result = await res.json();
+  if (!res.ok) throw new Error(result.error ?? 'Repository could not be added.');
+  return result;
+}
+
+export async function repositoryToolMain(mcp) {
+  if (!mcp) {
+    try { process.stdout.write(`${JSON.stringify(await callRepository(process.argv[3]))}\n`); }
+    catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+    return;
+  }
+  for await (const line of createInterface({ input: process.stdin })) {
+    let request;
+    try {
+      request = JSON.parse(line);
+      if (request.id === undefined) continue;
+      let result;
+      if (request.method === 'initialize') result = { protocolVersion: request.params?.protocolVersion ?? '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'card-repositories', version: '1.0.0' } };
+      else if (request.method === 'ping') result = {};
+      else if (request.method === 'tools/list') result = { tools: [{ name: 'add_repository', description: 'Add a project repository to the held card and create its sibling worktree on the same session branch. No human confirmation is needed.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false } }] };
+      else if (request.method === 'tools/call' && request.params?.name === 'add_repository') {
+        try { result = { content: [{ type: 'text', text: JSON.stringify(await callRepository(request.params.arguments?.name)) }] }; }
+        catch (error) { result = { isError: true, content: [{ type: 'text', text: error.message }] }; }
+      } else { process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32601, message: 'Unknown method' } })}\n`); continue; }
+      process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`);
+    } catch { if (request?.id !== undefined) process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32602, message: 'Invalid request' } })}\n`); }
+  }
+}

package/bin/lib/runTurn.mjs

@@ -22,6 +22,8 @@ import { learnCodexLimits, recordClaudeRateLimit } from './runtimeLimits.mjs';
 import { initHarvestFor, recordMcpServers, recordSkills } from './runtimeCapabilities.mjs';
 import { codexTurnModel } from './turnModel.mjs';
 import { printableText } from './printable.mjs';
+import { startTurnDiagnostics } from './turnDiagnostics.mjs';
+import { createClaudeInput } from './claudeInput.mjs';
 
 /** How long a Codex turn's answer may wait on its rollout's model line. */
 const CODEX_MODEL_READ_MS = 1_500;
@@ -166,6 +168,8 @@ function runPlainTurn(opts) {
     // which posture a turn is running under. There is no precedence chain left
     // to get wrong: the caller named one profile (turnProfile.mjs).
     const args = rt.args({
+      streamInput: rt.id === 'claude' && Boolean(opts.liveMessages),
+      writableDirs: opts.writableDirs,
       personal,
       researchIsolation: opts.researchIsolation,
       prompt,
@@ -195,8 +199,8 @@ function runPlainTurn(opts) {
       // 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.
+      // Claude adds it as a directory; Codex includes only this library in
+      // its project read boundary; agy's `--add-dir` is spent on the 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
@@ -206,7 +210,16 @@ function runPlainTurn(opts) {
       // PLAN MODE REPLACES THE POSTURE, never joins it: beside
       // `--dangerously-skip-permissions` the bypass wins silently (measured —
       // see PLAN_MODE_PERM).
-      perm: claudePermFor(turnProfile.name, knowledgeDir, vaultDir),
+      //
+      // …AND THE PROJECT SERVERS IT MAY CALL (2026-10-10): the names of the
+      // base `.mcp.json` servers the caller mounted, each allowed by name on a
+      // profile that mounts them (`projectMcp`, turnProfile.mjs) — never on
+      // one that does not, whatever a caller passes.
+      perm: claudePermFor(turnProfile.name, knowledgeDir, vaultDir, turnProfile.projectMcp ? (opts.projectMcpServers ?? []) : []),
+      // …AND THE MACHINE'S OWN MCP SERVERS (2026-10-11): the `.mcp.json`
+      // server names an agent lane disables beside them, on a profile that
+      // mounts project servers — never on one that does not.
+      machineMcp: turnProfile.projectMcp ? opts.machineMcp : undefined,
       // Handed to the adapter rather than appended here, because WHERE these go
       // is a property of the CLI: Codex reads its prompt as a trailing
       // positional, so a flag after it is a flag in the wrong place.
@@ -253,14 +266,21 @@ function runPlainTurn(opts) {
     };
     let browser = null;
     let child;
+    let finishDiagnostics = () => {};
     try {
       // A turn nobody is sitting at keeps its browsers in a home of its own —
       // the lane's kept one (an agent's), else this spawn's, removed when the
       // CLI closes. See `cliEnv`.
       browser = display === true ? null : openBrowserHome(browserHome);
+      const childEnv = cliEnv(personal?.env ? { ...personal.env, ...(mcpEnv ?? {}) } : mcpEnv, {
+        display: display === true,
+        browserHome: browser?.dir,
+      });
+      finishDiagnostics = startTurnDiagnostics({ runtime, bin: rt.bin, env: childEnv,
+        cwd, args, profile: turnProfile.name, planId: opts.diagnosticPlanId });
       child = spawn(rt.bin, args, {
         cwd,
-        stdio: ['ignore', 'pipe', 'pipe'],
+        stdio: [rt.id === 'claude' && opts.liveMessages ? 'pipe' : 'ignore', 'pipe', 'pipe'],
         /**
          * ITS OWN PROCESS GROUP, so what the agent starts stays attributable.
          *
@@ -287,12 +307,10 @@ function runPlainTurn(opts) {
         // sitting at, every way to a window — see `cliEnv`.
         // The login's literal secrets first, so nothing of the lane's (its MCP
         // token, its CODEX_HOME) can be overwritten by one.
-        env: cliEnv(personal?.env ? { ...personal.env, ...(mcpEnv ?? {}) } : mcpEnv, {
-          display: display === true,
-          browserHome: browser?.dir,
-        }),
+        env: childEnv,
       });
     } catch (error) {
+      finishDiagnostics({ spawnError: typeof error?.code === 'string' ? error.code : 'SPAWN_THROW' });
       // A spawn that throws (an argument it refuses), or anything on the way
       // to it, still takes what the adapter wrote with it — and this spawn's
       // own browser home.
@@ -309,6 +327,7 @@ function runPlainTurn(opts) {
     // than this is a previous turn's (turnModel.mjs).
     const spawnedAt = Date.now();
     let out = '';
+    const input = rt.id === 'claude' && opts.liveMessages ? createClaudeInput(child, { onTaken: opts.liveMessages.onTaken }) : null;
     const pfx = label ? `${label} ` : '';
     /**
      * THE ONE SINK FOR WHAT A CLI OR A MODEL WROTE (2026-10-10, the audit's
@@ -378,19 +397,28 @@ function runPlainTurn(opts) {
     const harvest = initHarvestFor(rt, args);
     const onInitAll = (i) => {
       if (harvest.skills) recordSkills(i?.skills);
-      if (harvest.mcp) recordMcpServers(i?.mcpServers);
+      if (harvest.mcp) recordMcpServers(i?.mcpServers, i?.tools);
       onInit?.(i);
     };
     /** One line of the child's stdout, in whichever dialect it speaks. */
+    let cliFailed = false;
     const onLine = (line) => {
-      if (opts.onCliFailure) {
-        try {
-          const event = JSON.parse(line);
-          if ((event.type === 'result' && event.is_error === true) ||
-              event.type === 'error' || event.type === 'turn.failed')
-            opts.onCliFailure();
-        } catch { /* ordinary non-JSON CLI output */ }
-      }
+      try {
+        const event = JSON.parse(line);
+        if (input) {
+          input.event(event);
+          if (event.type === 'system' && event.subtype === 'init' && event.session_id) opts.liveMessages.onInit(event.session_id);
+          // A message written just before result may become a second native
+          // turn in this process. Return its final result alone, never two
+          // structured objects joined together; every result still reports spend.
+          if (event.type === 'result') out = '';
+        }
+        if ((event.type === 'result' && event.is_error === true) ||
+            event.type === 'error' || event.type === 'turn.failed') {
+          cliFailed = true;
+          opts.onCliFailure?.();
+        }
+      } catch { /* ordinary non-JSON CLI output */ }
       if (!rt.parse)
         return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit: onInitAll, onUsage, onRateLimit: onRate, onModel: onRanOn });
       const ev = rt.parse(line, cwd);
@@ -405,6 +433,7 @@ function runPlainTurn(opts) {
       // The runtime's own token count (codex's `turn.completed`) — the same
       // `onUsage` Claude's result event feeds, so a caller charges a turn
       // identically whichever CLI ran it.
+      if (ev.toolEvent) onToolEvent?.(...ev.toolEvent);
       if (ev.usage) onUsage?.(ev.usage);
       // One agent MESSAGE, alone — see parseCodexLine's `answer`. Last call
       // wins at the caller, which is what "the final answer" means.
@@ -450,6 +479,9 @@ function runPlainTurn(opts) {
      * resolves what was captured so far.
      */
     const onSpawnError = (e) => {
+      input?.close();
+      if (opts.liveMessages) void opts.liveMessages.stop();
+      finishDiagnostics({ pid: child.pid, spawnError: typeof e.code === 'string' ? e.code : 'SPAWN_ERROR' });
       releaseArgs();
       if (e.code === 'ENOENT') {
         console.error(`\nerror: '${rt.bin}' CLI not found on PATH. Install ${rt.label} first: ${rt.install}`);
@@ -461,10 +493,13 @@ function runPlainTurn(opts) {
     };
     child.on('error', onSpawnError);
     child.on('close', (code, signal) => {
+      input?.close();
       releaseArgs();
       opts.onExit?.(code, signal);
       if (buf.trim()) onLine(buf);
-      const handBack = () => {
+      finishDiagnostics({ code, signal, pid: child.pid, output: out, cliFailed });
+      const handBack = async () => {
+        if (opts.liveMessages) await opts.liveMessages.stop();
         resolve(out);
         // After the answer is handed back, never before it: see `onRate`.
         if (codexThread) {
@@ -495,5 +530,10 @@ function runPlainTurn(opts) {
       }
       handBack();
     });
+    if (input) {
+      const initial = opts.liveMessages.initialPrompt(prompt, resumeThreadId, resume, opts.liveContinuation === true);
+      input.send(opts.liveMessages.initialId || opts.liveMessages.turnId, initial);
+      opts.liveMessages.connect(input.send);
+    }
   });
 }

package/bin/lib/runtimeAntigravity.mjs

@@ -147,7 +147,7 @@ export const ANTIGRAVITY_RUNTIME = {
   planTurns: false,
   adopt: 'move',
   mcp: null,
-  args({ prompt, system, model, effort, resume, resumeConversationId, profile = 'build', vaultDir, resultSchemaArgs = [], adoptResumeId }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, resumeConversationId, profile = 'build', vaultDir, resultSchemaArgs = [], adoptResumeId }) {
     const a = [];
     // WHICH CONVERSATION IS THIS — one decision, answered one way (the same
     // rule as Claude's --resume/--continue). By id when the caller knows:
@@ -212,6 +212,7 @@ export const ANTIGRAVITY_RUNTIME = {
       // So a SAFE-mode operator gets an agy build that is not actually
       // narrowed — which is why `mediatedSafeGap` is surfaced rather than
       // quietly ignored.
+      for (const dir of writableDirs) a.push('--add-dir', dir);
       a.push('--dangerously-skip-permissions');
       a.push('--print-timeout', '60m');
     } else if (profile === 'consult') {