flowviant 0.124.0 → 0.125.0

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, rootFor: (id) => repositories.list().find((r) => r.id === id)?.repoRoot };
+}

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);
     }

package/bin/lib/trace.mjs

@@ -60,6 +60,7 @@
  */
 
 import { THINK_MARKER } from './runtimeEvents.mjs';
+import { withoutTurnDeclaration } from './turnDeclaration.mjs';
 
 /** One batch every two seconds — the discipline the tab's narrator keeps, for
  *  the same reason: a turn emits hundreds of entries and nobody is reading them
@@ -207,7 +208,8 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
      * did when a thought was 300 characters.
      */
     prose(kind, text) {
-      const t = scrub(String(text ?? ''))
+      const readable = kind === 'think' ? String(text ?? '') : withoutTurnDeclaration(text);
+      const t = scrub(readable)
         // One line ending, whatever the CLI printed.
         .replace(/\r\n?/g, '\n')
         // Spaces and tabs collapse; `\n` is deliberately excluded from the class.
@@ -216,7 +218,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
         .replace(/\n{3,}/g, '\n\n')
         .trim()
         .slice(0, TRACE_PROSE_CAP);
-      if (!t) return;
+      if (!t) return null;
       const k = kind === 'think' ? 'think' : kind === 'say' ? 'say' : 'note';
       /**
        * A RUN OF BARE "thinking…" IS ONE STEP, not forty.
@@ -238,9 +240,12 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
        * steps are not shown" count stays a count of steps that existed.
        */
       if (k === 'think' && t === THINK_MARKER && lastEntry?.k === 'think' && lastEntry.t === t) {
-        return;
+        return readable;
       }
       push({ k, t });
+      // The activity pulse uses this same filtering; its original compact
+      // label stands unless protocol text was removed from the full message.
+      return readable;
     },
     /** One structured tool event, exactly as `toolEventOf` built it. A tool this
      *  builder does not know returns null there and nothing is pushed here — a

package/bin/lib/turnDeclaration.mjs

@@ -0,0 +1,88 @@
+/** A final outcome is protocol, not conversation prose. Filter before trace
+ * normalization/caps; the unmodified answer still goes to parseTurnResult.
+ * Only standalone objects and JSON/unlabelled fences count. Code examples
+ * inside prose or another language's fence stay as the CLI wrote them. */
+import { jsonObjectClosers } from './agentPlan.mjs';
+
+const statuses = new Set(['delivered', 'blocked', 'prerequisite', 'nothing']);
+function declaration(body) {
+  const raw = body.trim();
+  if (!raw.startsWith('{')) return false;
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' && !Array.isArray(value)
+      && ((Object.hasOwn(value, 'summary') && Object.hasOwn(value, 'progress'))
+        || (typeof value.status === 'string'
+          && (statuses.has(value.status) || ['summary', 'progress', 'question'].some(key => Object.hasOwn(value, key)))));
+  } catch {
+    // A truncated/invalid declaration must not fall through as an answer.
+    // Require a protocol key at the root's opening and the declared status;
+    // arbitrary malformed JSON remains useful diagnostic output.
+    return /^\{\s*"(?:status|summary|progress|question)"\s*:/.test(raw)
+      && /"status"\s*:\s*"(?:delivered|blocked|prerequisite|nothing)"/.test(raw);
+  }
+}
+
+/** Objects on their own lines, including a final object after a preamble.
+ * Skip a whole outer span before looking again; nested examples are data. */
+function bareDeclarations(raw) {
+  const closes = jsonObjectClosers(raw);
+  let kept = '', from = 0, removed = false;
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] !== '{') continue;
+    const end = closes.get(i) ?? -1;
+    const lineStart = raw.lastIndexOf('\n', i - 1) + 1;
+    const nextLine = end < 0 ? -1 : raw.indexOf('\n', end + 1);
+    const alone = !raw.slice(lineStart, i).trim()
+      && (end < 0 || !raw.slice(end + 1, nextLine < 0 ? raw.length : nextLine).trim());
+    const finish = end < 0 ? raw.length : end + 1;
+    if (alone && declaration(raw.slice(i, finish))) {
+      kept += raw.slice(from, i); from = finish; removed = true;
+    }
+    if (end >= 0) i = end;
+    else {
+      // An unclosed outer object owns the remaining candidate. For a stray
+      // brace in prose, skip its line instead of rescanning a brace wall.
+      const newline = raw.indexOf('\n', i);
+      if (alone || newline < 0) break;
+      i = newline;
+    }
+  }
+  return removed ? kept + raw.slice(from) : null;
+}
+
+export function withoutTurnDeclaration(text) {
+  const raw = String(text ?? '');
+  const kept = [];
+  let block = [], fence = null, json = false, removed = false;
+  let prose = [];
+  const flushProse = () => {
+    const plain = bareDeclarations(prose.join('\n'));
+    if (plain !== null) { removed = true; kept.push(plain); }
+    else kept.push(...prose);
+    prose = [];
+  };
+  // Consume every fence, including other languages, in one forward pass.
+  // A nested JSON example is part of its outer code block, never a result.
+  for (const line of raw.split('\n')) {
+    if (fence) {
+      if (line.trim() === fence) {
+        if (json && declaration(block.slice(1).join('\n'))) removed = true;
+        else kept.push(...block, line);
+        block = []; fence = null;
+      } else block.push(line);
+    } else {
+      const open = line.trim().match(/^(`{3,}|~{3,})[ \t]*([\w-]*)$/);
+      if (open) {
+        flushProse();
+        fence = open[1]; json = !open[2] || open[2].toLowerCase() === 'json'; block = [line];
+      } else prose.push(line);
+    }
+  }
+  flushProse();
+  if (fence) {
+    if (json && declaration(block.slice(1).join('\n'))) removed = true;
+    else kept.push(...block);
+  }
+  return removed ? kept.join('\n').replace(/\n{3,}/g, '\n\n').trim() : raw;
+}