flowviant 0.124.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

@@ -23,6 +23,7 @@ import { initHarvestFor, recordMcpServers, recordSkills } from './runtimeCapabil
 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;
@@ -167,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,
@@ -277,7 +280,7 @@ function runPlainTurn(opts) {
         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.
          *
@@ -324,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
@@ -401,6 +405,14 @@ function runPlainTurn(opts) {
     const onLine = (line) => {
       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;
@@ -467,6 +479,8 @@ 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') {
@@ -479,11 +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);
       finishDiagnostics({ code, signal, pid: child.pid, output: out, cliFailed });
-      const handBack = () => {
+      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) {
@@ -514,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') {

package/bin/lib/runtimeClaude.mjs

@@ -101,7 +101,7 @@ export const CLAUDE_RUNTIME = {
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, streamInput = false }) {
     // THE CARTOGRAPHER'S FENCE NAMES ITS VAULT (2026-10-10): its one write rule
     // is the vault's absolute path (claudePosture.mjs `wikiPermFor`), so a turn
     // with no vault, or one no rule can name, has no list — refused here in
@@ -138,7 +138,9 @@ export const CLAUDE_RUNTIME = {
     if (adoptResumeId) a.push('--resume', adoptResumeId, '--fork-session');
     else if (resumeThreadId) a.push('--resume', resumeThreadId);
     else if (resume) a.push('--continue');
-    a.push('-p', prompt, '--append-system-prompt', system);
+    if (streamInput) a.push('-p', '--input-format', 'stream-json', '--replay-user-messages');
+    else a.push('-p', prompt);
+    a.push('--append-system-prompt', system);
     /**
      * WHOSE SETTINGS A TURN READS (2026-09-29, claudePersonal.mjs).
      *
@@ -205,6 +207,7 @@ export const CLAUDE_RUNTIME = {
     // worktree's cwd: named as a readable directory so a curated profile
     // does not refuse the path the prompt just handed it. Before `perm`,
     // because `--allowedTools` is variadic and would swallow the flag.
+    if (profile === 'build') for (const dir of writableDirs) a.push('--add-dir', dir);
     if (knowledgeDir) a.push('--add-dir', knowledgeDir);
     // THE VAULT, likewise (2026-10-10): it lives under ~/.flowviant/vaults,
     // outside the wiki worktree, and its `mkdir`/`rm` are path-validated to the

package/bin/lib/runtimeCodex.mjs

@@ -233,7 +233,7 @@ export const CODEX_RUNTIME = {
    * placed before it. Appending them after the positional is the kind of argv
    * that parses today and stops parsing on some future clap upgrade.
    */
-  args({ prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads }) {
     // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
     // agy moves) — codex has no adoptable store wired yet. Reaching here
     // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -277,6 +277,7 @@ export const CODEX_RUNTIME = {
       // `--sandbox` flag (codex-cli 0.156.1 lists only `-c`/`--enable`/…), so
       // every resumed turn — an agent's second card, an answer — was refused
       // before it started. `-c sandbox_mode=` means the same on both.
+      if (writableDirs.length) a.push('-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(writableDirs)}`);
       a.push('-c', `sandbox_mode="${SAFE ? 'workspace-write' : 'danger-full-access'}"`);
     }
 

package/bin/lib/shipMerge.mjs

@@ -26,12 +26,14 @@ export function mergeOutward({
   repoRoot,
   tmpDir,
   baseRef,
+  baseTip,
   workingTree,
   warn,
   // NETWORK calls only (push, fetch) — timed and non-interactive, so a
   // stale credential or a half-open connection cannot freeze the ship
   // path's writer lock. Injectable for tests; defaults to the real one.
   gitNet = gitNetDefault,
+  retryRace = true,
 }) {
   const dropTmp = () => {
     try {
@@ -56,6 +58,7 @@ export function mergeOutward({
     const base = baseBranchName(baseRef());
     const merged = String(git(['rev-parse', 'HEAD'], tmpDir)).trim();
     const before = String(git(['rev-parse', `refs/heads/${base}`], repoRoot)).trim();
+    if (baseTip && before !== baseTip) throw new Error(`base moved to ${before}, but expected ${baseTip}`);
     let current = null;
     try { current = String(git(['symbolic-ref', '--quiet', '--short', 'HEAD'], repoRoot)).trim(); } catch { /* detached */ }
     if (current === base) {
@@ -76,7 +79,7 @@ export function mergeOutward({
   };
   const attempt = () => {
     dropTmp();
-    git(['worktree', 'add', '--detach', tmpDir, baseRef()], repoRoot);
+    git(['worktree', 'add', '--detach', tmpDir, baseTip ?? baseRef()], repoRoot);
     gitMerge(
       ['merge', '--no-ff', tip, '-m', `ship(${label}): ${count} commit${count === 1 ? '' : 's'}`],
       tmpDir
@@ -110,7 +113,7 @@ export function mergeOutward({
        * re-pushing a stale merge. The TIP is untouched, so the receipts still
        * name exactly the same commits.
        */
-      if (!isRaceRejection(e)) throw e;
+      if (!retryRace || !isRaceRejection(e)) throw e;
       warn?.('ship: base moved under us — refetching and merging again');
       try {
         gitNet(['fetch', 'origin', '--quiet'], repoRoot, 60_000);

package/bin/lib/startProject.mjs

@@ -188,8 +188,8 @@ export async function resolveStartProject({ dirGiven }) {
       }
       // An answered question is consent: adopt it, and BIND it to this repo so
       // the next start needs no prompt. Repointing is legitimate and said aloud.
-      if (repoRoot && picked.repoRoot && picked.repoRoot !== repoRoot) {
-        console.log(`note: ${creds.projectLabel(picked)} was connected for ${picked.repoRoot} — now serving ${repoRoot} instead.`);
+      if (repoRoot && picked.repoRoot && !creds.isStoredRepo(picked, repoRoot)) {
+        console.log(`note: adding ${repoRoot} to ${creds.projectLabel(picked)}. Run ${terminalCommand('login')} here to register its repository in project settings.`);
       }
       adoptStoredCredential(picked);
       // BOUND ONLY ONCE THE START HAS THE LOCK. Written here, the answer moved
@@ -266,10 +266,10 @@ export async function resolveStartProject({ dirGiven }) {
   }
 
   if (process.argv.includes('--json-events') && dirGiven && CREDENTIAL?.entry) {
-    const { detectRepoRoot, listStoredProjects, boundElsewhere } = await import('./credentials.mjs');
+    const { detectRepoRoot, listStoredProjects, boundElsewhere, isStoredRepo } = await import('./credentials.mjs');
     const repo = detectRepoRoot();
     const entry = CREDENTIAL.entry;
-    if (!repo || entry.repoRoot !== repo || boundElsewhere(listStoredProjects(), repo, entry.projectId).length) {
+    if (!repo || !isStoredRepo(entry, repo) || boundElsewhere(listStoredProjects(), repo, entry.projectId).length) {
       console.error('error: this project is not connected to this repository. Run `flowviant login` for the selected folder.');
       process.exit(1);
     }