flowviant 0.97.0 → 0.100.0

package/bin/lib/mcp-cli.mjs

@@ -18,15 +18,16 @@
  */
 
 import { FLEET_TOKEN, USER_AGENT, MCP_URL, FLEET_URL } from './config.mjs';
+import { terminalCommand } from './launchCommand.mjs';
 
 const CLI_TOKEN_URL = FLEET_URL.replace(/\/agents\/?$/, '/cli-token');
 
 export async function runMcpCommand(args = []) {
   if (!FLEET_TOKEN) {
     console.error(
-      'error: no credential resolves here. Run `flowviant login` first — or, with\n' +
+      `error: no credential resolves here. Run \`${terminalCommand('login')}\` first — or, with\n` +
         'several projects connected on this box, run this inside the project\'s own\n' +
-        'repo or pass `--project <name|id>` (`flowviant projects` lists them).'
+        `repo or pass \`--project <name|id>\` (\`${terminalCommand('projects')}\` lists them).`
     );
     process.exit(1);
   }
@@ -50,7 +51,7 @@ export async function runMcpCommand(args = []) {
     console.error(
       `error: could not mint a CLI credential (${res.status}). ` +
         (res.status === 401 || res.status === 403
-          ? 'Your credential may have been revoked — try `flowviant login` again.'
+          ? `Your credential may have been revoked — try \`${terminalCommand('login')}\` again.`
           : 'Try again in a moment.')
     );
     process.exit(1);

package/bin/lib/preflight.mjs

@@ -8,6 +8,7 @@ import { execFileSync } from 'node:child_process';
 import { ok, warn, info, c } from './ui.mjs';
 import { addLocalBinToPath, promptYesNo, installClaude, installGh } from './install.mjs';
 import { RUNTIMES, detectRuntimes, mediatedSafeGap } from './runtimes.mjs';
+import { terminalCommand } from './launchCommand.mjs';
 
 function present(cmd) {
   try {
@@ -106,7 +107,7 @@ export async function preflight({ needGit = true } = {}) {
       if (await installGh((m) => info(m))) gh = present('gh');
     }
     gh
-      ? ok('gh installed to ~/.flowviant/bin — authenticate with: flowviant gh-auth')
+      ? ok(`gh installed to ~/.flowviant/bin — authenticate with: ${terminalCommand('gh-auth')}`)
       : info(c.dim('or install it later: https://cli.github.com, then: gh auth login'));
   }
 

package/bin/lib/preview.mjs

@@ -46,7 +46,7 @@ import {
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
 import { startAuthProxy } from './authproxy.mjs';
-import { forgetInfraPid, isListening, noteInfraPid } from './listeners.mjs';
+import { forgetInfraPid, isListening, noteInfraPid, originFor } from './listeners.mjs';
 
 // ── cloudflared: pinned, verified, or not fetched at all ───────────────────
 
@@ -138,7 +138,19 @@ async function ensureCloudflared(log) {
   }
 }
 
-const TUNNEL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+/**
+ * The hostname cloudflared ASSIGNED, and nothing else it happens to print.
+ *
+ * `[a-z0-9-]+\.trycloudflare\.com` also matched cloudflared's own FAILURE line
+ * — `failed to request quick Tunnel: Post "https://api.trycloudflare.com/tunnel":
+ * dial tcp: lookup api.trycloudflare.com: …` — so on any box that could not
+ * reach the quick-tunnel API (offline, DNS failure, a proxy blocking it) the
+ * share was reported LIVE at Cloudflare's own API host, and cloudflared's real
+ * sentence, which the tail exists to relay, was replaced by a wrong one (audit
+ * 2026-09-24). `api.` is the service's endpoint and never an assigned name, and
+ * the trailing guard stops a longer hostname matching on its prefix.
+ */
+export const TUNNEL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com(?![a-z0-9.-])/i;
 
 // ── Orphan reaping ─────────────────────────────────────────────────────────
 // cloudflared is detached so we can kill its whole group — which also means it
@@ -228,6 +240,39 @@ function mutateRegistry(fn) {
   }
 }
 
+/**
+ * WHEN a process started, as the kernel reports it — or null when this box
+ * will not say. Paired with a pid it names ONE process: a pid alone is
+ * recycled, and the owner check below trusted signal 0 on a bare pid.
+ */
+export function processStartOf(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (platform() === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      // Field 22 (starttime), counted after the LAST ')' — the comm field in
+      // parentheses may itself hold spaces and parentheses.
+      const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+      return rest[19] ? `l:${rest[19]}` : null;
+    } catch {
+      return null;
+    }
+  }
+  if (platform() === 'darwin') {
+    try {
+      const out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+        encoding: 'utf8',
+        timeout: 5_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      return out ? `d:${out}` : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 /** Signal-0 liveness (EPERM = alive and not ours), for the OWNER check below. */
 function processAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -246,7 +291,15 @@ function recordPreviewPid(pid, sig) {
   // starting daemon reaped its PEER's live tunnels: killed them, wiped their
   // entries, and the peer kept heartbeating a URL that 530s (its probe watches
   // the origin port, which was still alive).
-  mutateRegistry((list) => [...list, { pid, sig, owner: process.pid }]);
+  //
+  // `ownerStart` pins the owner to ONE process (audit 2026-09-24). A daemon that
+  // is SIGKILLed with a share open leaves cloudflared up; if its pid is reused
+  // by the next start — any process, another user's included, since EPERM
+  // counts as alive — a pid-only check read the entry as a live peer's and
+  // skipped it forever, leaving a public hostname aimed at a dead gate's
+  // ephemeral port for anything that binds it next.
+  const ownerStart = processStartOf(process.pid);
+  mutateRegistry((list) => [...list, { pid, sig, owner: process.pid, ...(ownerStart ? { ownerStart } : {}) }]);
 }
 
 function forgetPreviewPid(pid) {
@@ -311,13 +364,24 @@ function stillOurs(pid, sig) {
  *  own teardown handles it) — killing those and wiping their entries was a
  *  peer daemon's startup silently breaking every live share on the box. Only
  *  the entries this pass handled are removed; a peer's records survive. */
+/** Is the daemon that recorded an entry still the process at that pid? With
+ *  a recorded start time, only when the pid's start time still matches (a
+ *  recycled pid is an orphaned entry); where this box cannot report a start
+ *  time now, or the entry predates the field, signal 0 is all there is. */
+function ownerStillRunning(owner, ownerStart) {
+  if (!processAlive(owner)) return false;
+  if (typeof ownerStart !== 'string') return true;
+  const now = processStartOf(owner);
+  return now == null ? true : now === ownerStart;
+}
+
 export function reapOrphanPreviews(log) {
   const list = readRegistry();
   if (list.length === 0) return;
   let killed = 0;
   const handled = new Set();
-  for (const { pid, sig, owner } of list) {
-    if (Number.isInteger(owner) && owner !== process.pid && processAlive(owner)) continue;
+  for (const { pid, sig, owner, ownerStart } of list) {
+    if (Number.isInteger(owner) && owner !== process.pid && ownerStillRunning(owner, ownerStart)) continue;
     const ours = stillOurs(pid, sig);
     /**
      * THE RECORD OUTLIVES A REAP THAT COULD NOT LOOK. `handled.add` ran BEFORE
@@ -396,6 +460,11 @@ export async function openTunnel({
   onAbuse,
   onTunnelGone,
   stillServing,
+  // The worktree the port was attributed to. When given, the gate dials the
+  // address the ATTRIBUTED socket holds (`originFor`) rather than assuming
+  // 127.0.0.1, and every liveness check re-derives it — so a neighbour on the
+  // other loopback family is never what the tunnel publishes.
+  worktree,
   probeMs = 20_000,
   // The members-gate triple, all three or none. Absent = an older server, or a
   // password-mode share: the gate runs exactly as it always has.
@@ -406,8 +475,15 @@ export async function openTunnel({
   // ONE predicate for every liveness question this function asks. Attribution
   // when the caller gave it, a bare TCP connect only when it did not; an
   // attribution check that errors is not a "yes".
+  // `origin` is decided once, at the gate's start; after that a change of
+  // address is a different process and reads as "not serving".
+  let origin = null;
   const serving = async () => {
     try {
+      if (worktree) {
+        const o = originFor(worktree, port);
+        if (o.error || (origin && o.host !== origin)) return false;
+      }
       return stillServing ? await stillServing() : await isListening(port);
     } catch {
       return false;
@@ -455,8 +531,14 @@ export async function openTunnel({
 
   // The gate comes up FIRST and the tunnel points at it, never at the origin —
   // so there is no window in which the public hostname is un-gated.
+  if (worktree) {
+    const o = originFor(worktree, port);
+    if (o.error) return { error: o.error };
+    origin = o.host;
+  }
   gate = await startAuthProxy({
     targetPort: port,
+    ...(origin ? { targetHost: origin } : {}),
     log,
     // Never logged, never written to previews.json, never in the reap
     // signature, never in argv or a child env — /proc/<pid>/cmdline is
@@ -529,7 +611,14 @@ export async function openTunnel({
     const onOut = (d) => {
       const s = d.toString();
       tail = (tail + s).slice(-TAIL_BYTES);
-      const m = TUNNEL_RE.exec(s);
+      // ONE URL, ONE PROBE. A second match after we settled (cloudflared
+      // repeats the banner, or a later line names another host) used to start
+      // a second probe interval and a second close listener on a tunnel whose
+      // answer had already been given.
+      if (settled) return;
+      // Matched over the TAIL, not the chunk: a pipe read can split the
+      // hostname across two chunks, and a half never matches.
+      const m = TUNNEL_RE.exec(tail);
       if (!m) return;
 
       // Watch the ORIGIN — with the caller's ATTRIBUTION check when it gave

package/bin/lib/printable.mjs

@@ -0,0 +1,42 @@
+/**
+ * PRINTABLE(): the CLI's own belt against a server-supplied string it is
+ * about to write to a TTY (2026-09-24, the audit's A3 CROSS 8a).
+ *
+ * `safeName` (credentials.mjs) already stripped C0/DEL/C1 for the same reason
+ * the server's own `parseBoxName`/`parseCheckoutPath` did — an escape
+ * sequence in a project or box name can clear the screen or, via OSC 52,
+ * rewrite the terminal's clipboard — but it stopped at C1 and never scrubbed
+ * the BIDI/format controls (U+200E/U+200F, U+202A–U+202E, U+2066–U+2069) that
+ * reorder a line to hide or forge part of it: a box named
+ * `evil‮txt.crt⁦` reads backwards on a bidi-aware terminal, so
+ * "evil" can visually swap places with an extension that was never there.
+ *
+ * THIS IS A LEAF MODULE ON PURPOSE. `machines.mjs` and `fleet.mjs` both need
+ * it, `machines.mjs` deliberately imports nothing from `fleet.mjs`'s world
+ * (its own header explains why: it runs before the auth gate, like `stop` and
+ * `projects`, and must not pull in the daemon's whole CLI/worktree
+ * machinery), and `credentials.mjs` is where `safeName` already lived. A leaf
+ * with zero imports is the one shape both can depend on without adding an
+ * edge neither wants.
+ *
+ * THE CHARACTER CLASS IS THE SERVER'S OWN (`stripDisplayControl`,
+ * machineBoxes.ts, 2026-09-24) — copied rather than re-derived, because the
+ * point of a BELT is that the two ends agree about what counts as printable
+ * without either one trusting the other to have applied it. The server scrub
+ * is the primary fix (it is what a stale stored row, upserted before this
+ * belt existed, is read back through); this is defence in depth, because the
+ * terminal is where the harm happens and the CLI should not trust that every
+ * string on the wire already passed through it — including a project's own
+ * `name`, which reaches every terminal that connects a machine (`login`, the
+ * banner, the picker, `projects`, `machines`) and had no scrub at all before
+ * `safeName`.
+ */
+// eslint-disable-next-line no-control-regex
+const DISPLAY_CONTROL = /[\u0000-\u001f\u007f-\u009f‎‏‪-‮⁦-⁩]/g;
+
+/** Strip the class above. Non-strings pass through unchanged — this is a
+ *  scrub, not a coercion, and a caller that hands it `undefined` should get
+ *  `undefined` back rather than the string `"undefined"`. */
+export function printable(raw) {
+  return typeof raw === 'string' ? raw.replace(DISPLAY_CONTROL, '') : raw;
+}

package/bin/lib/procRegistry.mjs

@@ -17,6 +17,8 @@
  *    does not become a file nobody can read.
  */
 
+import { execFileSync } from 'node:child_process';
+import { platform, uptime } from 'node:os';
 import {
   closeSync,
   mkdirSync,
@@ -95,6 +97,69 @@ export function writeRegistry(dir, path, list) {
   }
 }
 
+/**
+ * WHICH BOOT THIS IS — so a pid or process-group id read back off disk is only
+ * ever believed in the boot that wrote it.
+ *
+ * A registry outlives a reboot and pids do not: after one, the number a file
+ * remembers belongs to whatever the kernel handed it to next — another user's
+ * service, the operator's shell — and signal-0 says "alive" about a stranger.
+ * Linux names the boot outright (`boot_id`); elsewhere the boot INSTANT stands
+ * in, derived from the uptime and compared with slack, because two reads a
+ * second apart disagree by the rounding.
+ */
+const BOOT_SLACK_S = 120;
+export function bootMark() {
+  try {
+    const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    if (id) return id;
+  } catch {
+    /* not Linux, or /proc is not mounted */
+  }
+  return `bt:${Math.round(Date.now() / 1000 - uptime())}`;
+}
+/** Was `mark` written during this boot? An absent mark is NOT this boot —
+ *  an entry that cannot say when it was written cannot be trusted across one. */
+export function sameBoot(mark, now = bootMark()) {
+  if (typeof mark !== 'string' || !mark) return false;
+  if (mark.startsWith('bt:') && now.startsWith('bt:'))
+    return Math.abs(Number(mark.slice(3)) - Number(now.slice(3))) <= BOOT_SLACK_S;
+  return mark === now;
+}
+
+/**
+ * WHEN A PROCESS STARTED, as an opaque token — so a lock that remembers a pid
+ * can tell the process it meant from one that inherited the number.
+ *
+ * Linux: field 22 of `/proc/<pid>/stat` (start time in clock ticks since boot),
+ * read after the LAST `)` because the comm field may itself contain one.
+ * macOS: `ps -o lstart=`. Null when it cannot be read, which callers treat as
+ * "cannot tell" — never as a mismatch.
+ */
+export function processStartTime(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    // `rest[0]` is field 3 (state), so field 22 is rest[19].
+    const st = rest[19];
+    return st && /^\d+$/.test(st) ? `${bootMark()}:${st}` : null;
+  } catch {
+    /* not Linux, or the pid is gone */
+  }
+  if (platform() !== 'darwin') return null;
+  try {
+    const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5_000,
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /** Signal-0 liveness. EPERM means alive and not ours, which is still alive. */
 export function processAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;

package/bin/lib/processes.mjs

@@ -47,7 +47,13 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync, readdirSync } from 'node:fs';
 import { platform } from 'node:os';
 
-/** A box with more processes than this is not one we walk per sweep. */
+/** Matched rows collected per scan before the walk stops early — a bound on
+ *  the WORK done for one pathological group, never on which part of /proc is
+ *  looked at. It used to cut the pid LIST before filtering, and readdir answers
+ *  in string order, so a busy box kept '1', '10', '100'… and dropped a tab's
+ *  watcher at pid 912345 while `liveGroups` (which has no cap) still called its
+ *  group alive: the tab read "looked, found none" and a Stop on it answered
+ *  not_found. */
 const MAX_PIDS = 4000;
 /** Rows reported per session. A watcher, a dev server and its child is three;
  *  twenty is somebody's compose stack and the extra rows say nothing. */
@@ -113,25 +119,32 @@ function cmdlineOf(pid) {
   }
 }
 
-function scanLinux(pgids) {
+/** Exported with its readers injectable ONLY so the scan-order property can be
+ *  pinned without a box that runs four thousand processes. Nothing in the
+ *  daemon passes `io`. */
+export function scanLinux(pgids, io = {}) {
+  const list = io.list ?? (() => readdirSync('/proc'));
+  const pgrpFor = io.pgrpOf ?? pgrpOf;
+  const cmdFor = io.cmdlineOf ?? cmdlineOf;
+  const rssFor = io.rssBytes ?? rssBytes;
   let pids;
   try {
-    pids = readdirSync('/proc').filter((d) => /^\d+$/.test(d));
+    pids = list().filter((d) => /^\d+$/.test(d));
   } catch {
     return [];
   }
-  if (pids.length > MAX_PIDS) pids = pids.slice(0, MAX_PIDS);
 
   const out = [];
   for (const raw of pids) {
+    if (out.length >= MAX_PIDS) break;
     const pid = Number(raw);
-    const pgrp = pgrpOf(raw);
+    const pgrp = pgrpFor(raw);
     if (pgrp === null || !pgids.has(pgrp)) continue;
     // The CLI itself — its argv is the prompt. See the header.
     if (pid === pgrp) continue;
-    const cmd = cmdlineOf(raw);
+    const cmd = cmdFor(raw);
     if (!cmd) continue;
-    const rss = rssBytes(raw);
+    const rss = rssFor(raw);
     out.push({ pid, pgid: pgrp, cmd, ...(rss != null ? { rss } : {}) });
   }
   return out;

package/bin/lib/projectTools.mjs

@@ -0,0 +1,248 @@
+/** Repo-owned tool configuration, read from the base ref for every agent turn. */
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+
+const MAX_TOOLS = 40;
+const MAX_REPORT_TOOLS = 80; // 40 MCP servers plus 40 instruction directories
+const MAX_INSTRUCTION_FILES = 80;
+const MAX_INSTRUCTION_BYTES = 512 * 1024;
+const nameOk = (name) => /^[A-Za-z0-9_-]{1,80}$/.test(name) && name !== 'flowviant';
+const toml = (value) => JSON.stringify(String(value));
+const show = (root, ref, path) => {
+  try {
+    return execFileSync('git', ['show', `${ref}:${path}`], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024,
+    });
+  } catch { return null; }
+};
+const showBytes = (root, ref, path) => {
+  try {
+    return execFileSync('git', ['show', `${ref}:${path}`], {
+      cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024,
+    });
+  } catch { return null; }
+};
+
+function onPath(command, env) {
+  if (isAbsolute(command)) {
+    try { accessSync(command, constants.X_OK); return true; } catch { return false; }
+  }
+  if (command.includes('/') || command.includes('\\')) return false;
+  return (env.PATH ?? '').split(delimiter).some((dir) => {
+    try { accessSync(join(dir, command), constants.X_OK); return true; } catch { return false; }
+  });
+}
+
+function referenced(value) {
+  return [...String(value).matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
+}
+
+/** Pure mapping used before a future tool-attach gesture is offered. */
+export function runnerToolCapabilities(runner) {
+  return ({ claude: { mcp: true, skills: true }, codex: { mcp: true, skills: true }, antigravity: { mcp: false, skills: false } })[runner]
+    ?? { mcp: false, skills: false };
+}
+
+export function readBaseTools(root, ref, env = process.env) {
+  // Resolve once: a base branch may advance while the turn is being prepared.
+  const commit = execFileSync('git', ['rev-parse', '--verify', ref], {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+  const raw = show(root, commit, '.mcp.json');
+  let servers = {};
+  if (raw != null) {
+    try { servers = JSON.parse(raw).mcpServers ?? {}; } catch { servers = {}; }
+  }
+  const entries = Object.entries(servers).filter(([name, value]) => nameOk(name) && value && typeof value === 'object').slice(0, MAX_TOOLS);
+  const skills = [];
+  const skillFiles = [];
+  try {
+    const paths = execFileSync('git', ['ls-tree', '-r', '--name-only', commit, '--', '.claude/skills'], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024,
+    }).split('\n');
+    let bytes = 0;
+    for (const path of paths) {
+      if (!/^\.claude\/skills\/[A-Za-z0-9_-]+\/(?:[A-Za-z0-9_.-]+\/)*[A-Za-z0-9_.-]+$/.test(path)) continue;
+      if (skillFiles.length >= 200 || bytes >= 4 * 1024 * 1024) break;
+      const body = showBytes(root, commit, path);
+      if (body == null) continue;
+      bytes += body.length;
+      if (bytes > 4 * 1024 * 1024) break;
+      skillFiles.push({ path, body });
+      if (path.endsWith('/SKILL.md') && path.split('/').length === 4 && skills.length < MAX_TOOLS) skills.push({ path, body: body.toString('utf8') });
+    }
+  } catch { /* no skills at this ref */ }
+  const tools = entries.map(([name, config]) => {
+    const vars = new Set();
+    for (const value of [config.command, config.url, ...(Array.isArray(config.args) ? config.args : []), ...Object.values(config.env ?? {}), ...Object.values(config.headers ?? {})]) {
+      for (const key of referenced(value)) vars.add(key);
+    }
+    const missing = [...vars].filter((key) => !env[key]).sort();
+    const commandMissing = typeof config.command === 'string' && !onPath(expand(config.command, env), env);
+    const unsupported = typeof config.command !== 'string' && typeof config.url !== 'string';
+    const reason = missing.length ? `env ${missing.join(', ')} unset` : commandMissing ? `command ${config.command} not on PATH` : unsupported ? 'MCP configuration unsupported' : null;
+    return { name, config, state: reason ? 'missing' : 'ready', reason };
+  });
+  // Nested instructions are normally discovered when a CLI enters that path.
+  // Their worktree copies must not regain authority through that discovery.
+  const instructions = [];
+  const paths = execFileSync('git', ['ls-tree', '-r', '--name-only', commit], {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024,
+  }).split('\n').filter((path) => /(^|\/)(CLAUDE|AGENTS)\.md$/.test(path));
+  if (paths.length > MAX_INSTRUCTION_FILES) throw new Error('Base branch has too many agent instruction files');
+  let instructionBytes = 0;
+  for (const path of paths) {
+    const body = show(root, commit, path);
+    if (body == null) throw new Error(`Cannot read base instruction ${path}`);
+    instructionBytes += Buffer.byteLength(body);
+    if (instructionBytes > MAX_INSTRUCTION_BYTES) throw new Error('Base branch agent instructions exceed the turn limit');
+    instructions.push({ path, body });
+  }
+  return { tools, skills, skillFiles, instructions };
+}
+
+const expand = (value, env) => String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => env[key] ?? '');
+
+/** Keep personal Codex files, but do not copy its project trust grants. An
+ * untrusted worktree's .codex/config.toml is ignored by Codex 0.156.1. */
+function isolatedCodexHome(dir, env, worktree) {
+  const source = resolve(env.CODEX_HOME || join(homedir(), '.codex'));
+  const dest = join(dir, 'codex-home');
+  mkdirSync(dest, { mode: 0o700 });
+  if (existsSync(source)) {
+    for (const name of readdirSync(source)) {
+      if (name === 'config.toml') continue;
+      symlinkSync(join(source, name), join(dest, name));
+    }
+  }
+  const configPath = join(source, 'config.toml');
+  const sourceConfig = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const topLevel = sourceConfig.split(/^\s*\[/m, 1)[0];
+  const personalDeveloperInstructions = /^\s*developer_instructions\s*=/m.test(topLevel);
+  // These sections alone grant a checkout permission to supply project
+  // settings. Keep every other personal setting, skill and session store.
+  const lines = sourceConfig.split('\n');
+  let inProject = false;
+  let config = lines.filter((line) => {
+    const header = /^\s*(?:\[\[([^\]]+)\]\]|\[([^\]]+)\])\s*(?:#.*)?$/.exec(line);
+    if (header) {
+      const section = header[1] ?? header[2];
+      inProject = section === 'projects' || section.startsWith('projects.');
+    }
+    return !inProject;
+  }).join('\n');
+  if (worktree) {
+    // Codex discovers these even in an untrusted project. Disable exactly the
+    // worktree skill paths; the person's ~/.codex/skills and config remain.
+    const worktreeSkills = [];
+    for (const sourceDir of ['.agents/skills', '.codex/skills', '.claude/skills']) {
+      const skillsDir = join(worktree, sourceDir);
+      if (!existsSync(skillsDir)) continue;
+      for (const name of readdirSync(skillsDir)) {
+        const skill = join(skillsDir, name, 'SKILL.md');
+        if (existsSync(skill)) worktreeSkills.push(skill);
+      }
+    }
+    if (worktreeSkills.length && /^\s*skills\.config\s*=/m.test(config))
+      throw new Error('Cannot isolate Codex project skills with inline skills.config');
+    for (const skill of worktreeSkills) config += `\n[[skills.config]]\npath = ${toml(skill)}\nenabled = false\n`;
+  }
+  writeFileSync(join(dest, 'config.toml'), config, { mode: 0o600 });
+  return { path: dest, personalDeveloperInstructions };
+}
+
+/** Temporary per-turn files are removed after the last retry. No personal CLI config is written. */
+export function prepareAgentTools(snapshot, runner, env = process.env, worktree = null) {
+  const dir = mkdtempSync(join(tmpdir(), 'flowviant-agent-tools-'));
+  const caps = runnerToolCapabilities(runner);
+  const usable = snapshot.tools.filter((t) => t.state === 'ready' && caps.mcp && !(runner === 'codex' && t.config.type === 'sse'));
+  const mcpServers = {};
+  const codexArgs = [];
+  for (const { name, config } of usable) {
+    if (typeof config.command === 'string') {
+      const command = expand(config.command, env);
+      const args = Array.isArray(config.args) ? config.args.map((v) => expand(v, env)) : [];
+      const vars = Object.fromEntries(Object.entries(config.env ?? {}).map(([k, v]) => [k, expand(v, env)]));
+      mcpServers[name] = { command, args, env: vars };
+      codexArgs.push('-c', `mcp_servers.${name}.command=${toml(command)}`);
+      codexArgs.push('-c', `mcp_servers.${name}.args=${JSON.stringify(args)}`);
+      for (const [key, value] of Object.entries(vars)) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) codexArgs.push('-c', `mcp_servers.${name}.env.${key}=${toml(value)}`);
+      }
+    } else if (typeof config.url === 'string') {
+      const url = expand(config.url, env);
+      const headers = Object.fromEntries(Object.entries(config.headers ?? {}).map(([k, v]) => [k, expand(v, env)]));
+      mcpServers[name] = { type: config.type ?? 'http', url, ...(Object.keys(headers).length ? { headers } : {}) };
+      codexArgs.push('-c', `mcp_servers.${name}.url=${toml(url)}`);
+      if (Object.keys(headers).length) {
+        const inline = Object.entries(headers).map(([key, value]) => `${toml(key)}=${toml(value)}`).join(',');
+        codexArgs.push('-c', `mcp_servers.${name}.http_headers={${inline}}`);
+      }
+    }
+  }
+  const mcpPath = join(dir, 'mcp.json');
+  writeFileSync(mcpPath, JSON.stringify({ mcpServers }), { mode: 0o600 });
+  const pointers = [];
+  for (const { path, body } of [...snapshot.instructions, ...(caps.skills ? snapshot.skillFiles : [])]) {
+    const dest = join(dir, path);
+    mkdirSync(join(dest, '..'), { recursive: true });
+    writeFileSync(dest, body, { mode: 0o600 });
+    if (!path.startsWith('.claude/skills/') || path.endsWith('/SKILL.md')) pointers.push(`${path}: ${dest}`);
+  }
+  const baseInstructions = snapshot.instructions.map(({ path, body }) => `Base ${path}:\n${body}`).join('\n\n');
+  const instructions = [baseInstructions,
+    pointers.length ? `Base-branch instruction and skill copies (read the relevant nested files and skill files before acting):\n${pointers.join('\n')}` : '',
+  ].filter(Boolean).join('\n\n');
+  const pluginDir = runner === 'claude' && snapshot.skillFiles.length ? join(dir, 'reviewed-plugin') : null;
+  if (pluginDir) {
+    mkdirSync(join(pluginDir, '.claude-plugin'), { recursive: true });
+    writeFileSync(join(pluginDir, '.claude-plugin/plugin.json'), JSON.stringify({ name: 'flowviant-reviewed', version: '1.0.0', description: 'Base-branch agent skills' }), { mode: 0o600 });
+    for (const { path, body } of snapshot.skillFiles) {
+      const dest = join(pluginDir, path.replace(/^\.claude\//, ''));
+      mkdirSync(join(dest, '..'), { recursive: true });
+      writeFileSync(dest, body, { mode: 0o600 });
+    }
+  }
+  let codexHome = null;
+  let personalDeveloperInstructions = false;
+  try {
+    if (runner === 'codex') {
+      const isolated = isolatedCodexHome(dir, env, worktree);
+      codexHome = isolated.path;
+      personalDeveloperInstructions = isolated.personalDeveloperInstructions;
+    }
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    mcpPath,
+    codexArgs,
+    instructions,
+    pluginDir,
+    codexHome,
+    personalDeveloperInstructions,
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+export function toolReadout(snapshot, runner) {
+  const caps = runnerToolCapabilities(runner);
+  const short = (reason) => reason == null ? null : String(reason).slice(0, 200);
+  const mcp = snapshot.tools.map(({ name, config, state, reason }) => {
+    const unsupported = runner === 'codex' && config.type === 'sse';
+    return {
+      name, kind: 'mcp',
+      state: caps.mcp && !unsupported ? state : 'missing',
+      reason: short(!caps.mcp ? runner === 'none' ? 'no installed CLI can take MCP' : `${runner} cannot take MCP`
+        : unsupported ? 'Codex cannot take SSE MCP' : reason),
+    };
+  });
+  const instructions = snapshot.skills.map(({ path }) => ({
+    name: path.split('/')[2], kind: 'instruction', state: caps.skills ? 'ready' : 'missing',
+    reason: short(caps.skills ? null : runner === 'none' ? 'no installed CLI can take instructions' : `${runner} cannot take instructions`),
+  }));
+  return [...mcp, ...instructions].slice(0, MAX_REPORT_TOOLS);
+}