flowviant 0.37.0 → 0.38.0

package/bin/lib/claude.mjs

@@ -1,7 +1,14 @@
 /**
- * Driving Claude Code: the operating-contract system prompts, the permission
- * posture, and one `claude -p` turn. The hard rule baked into both prompts:
- * there is no interactive user — the only channel to a human is the blocker loop.
+ * Driving a coding CLI: the operating-contract system prompts, the permission
+ * posture, and one headless turn. The hard rule baked into both prompts: there
+ * is no interactive user — the only channel to a human is the blocker loop.
+ *
+ * `runTurn` used to BE `claude -p`, argv and all. The argv, the binary, the way
+ * the MCP server is handed over and the shape of the event stream now come from
+ * the runtime registry (runtimes.mjs), because those four things are exactly
+ * what differs between one CLI and the next. What stays here is everything that
+ * is about FLOWVIANT rather than about a vendor: the contract prompts, the
+ * permission sets, the sentinel protocol, and the turn plumbing.
  */
 
 import { spawn } from 'node:child_process';
@@ -9,6 +16,7 @@ import { mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SAFE, MODEL } from './config.mjs';
+import { runtimeById, humanizeClaudeTool } from './runtimes.mjs';
 
 // Multi-task loop (TOKEN / TOKENS modes): drain the whole queue in one session.
 export const SYSTEM_MULTI = `You are a Flowviant build agent running FULLY AUTONOMOUSLY via the "flowviant" MCP
@@ -16,13 +24,13 @@ server. There is NO interactive user and NO terminal to ask in. The ONLY way to
 reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
 
 Operate this loop:
-1. Call claim_next_intent to PICK UP the next task someone @mentioned you on. If it
+1. Call claim_next_task to PICK UP the next task someone @mentioned you on. If it
    returns claimed:false, output exactly ALL_CLEAR on its own line and stop.
 2. Read the brief, and read its "thread" FIRST — that is the task conversation, and the
    newest human message is usually the specific reason you were brought in. If the brief
    has an existing "branch" (a REVISION), \`git checkout <branch>\` to resume your prior
    work and address what the thread asks for. Use get_module_files / search_wiki /
-   list_related_intents for context. Call report_progress as you go.
+   list_related_tasks for context. Call report_progress as you go.
 3. If you hit ANYTHING only a human can decide, call report_blocker with a clear
    question (and options when you can), then call get_blocker_resolution. If it is
    not yet resolved, output exactly BLOCKED:<blockerId> on its own line and STOP.
@@ -48,14 +56,14 @@ server. There is NO interactive user and NO terminal to ask in. The ONLY way to
 reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
 
 Do EXACTLY ONE task this turn:
-1. Call claim_next_intent to PICK UP the task someone @mentioned you on. If it returns
+1. Call claim_next_task to PICK UP the task someone @mentioned you on. If it returns
    claimed:false, output exactly NOTHING on its own line and stop. Do NOT retry.
 2. Read the brief, and read its "thread" FIRST — that is the task conversation, and the
    newest human message is usually the specific reason you were brought in. If the brief
    has an existing "branch" (a REVISION), first \`git fetch && git checkout <branch>\` to
    resume YOUR prior work and address what the thread asks for. Otherwise work from the
    clean base checkout. Use get_module_files / search_wiki /
-   list_related_intents for context. report_progress as you go.
+   list_related_tasks for context. report_progress as you go.
 3. If you hit ANYTHING only a human can decide, call report_blocker (with options when
    you can), then get_blocker_resolution. If unresolved, output exactly
    BLOCKED:<blockerId> on its own line and STOP. Do NOT guess past a real decision.
@@ -97,7 +105,7 @@ export const RESUME =
 // server, or nothing waiting) it falls back to the original free pick.
 export const SINGLE_KICKOFF = (intentId) =>
   intentId
-    ? `Pick up Flowviant task ${intentId} — call claim_next_intent with intentId "${intentId}" — ` +
+    ? `Pick up Flowviant task ${intentId} — call claim_next_task with taskId "${intentId}" — ` +
       'complete exactly that ONE task per your instructions, then stop. If that ' +
       'claim comes back unavailable, claim whatever is next for you instead.'
     : 'Pick up and complete exactly ONE Flowviant task per your instructions, then stop.';
@@ -508,49 +516,32 @@ export function mcpConfigFor(token, mcpUrl) {
   return { dir, path: p };
 }
 
-// Shorten an absolute tool path to a repo-relative one for legible output.
-const shortPath = (p, cwd) => {
-  if (typeof p !== 'string') return '';
-  let s = p;
-  if (cwd && s.startsWith(cwd)) s = s.slice(cwd.length).replace(/^\/+/, '');
-  return s;
-};
+/**
+ * Hand a runtime the flowviant MCP server, however that runtime wants it.
+ *
+ * Returns `{ dir, args, env }`: `dir` is a temp directory to delete after the
+ * turn (null when the runtime needed no file at all), `args` splice into argv,
+ * `env` merges into the child's environment. The shape is identical for every
+ * runtime precisely because the mechanism is not — Claude wants a JSON file
+ * path, Codex wants two `-c` overrides and reads the token out of the
+ * environment. Callers should not have to know which.
+ */
+export function mcpFor(runtimeId, token, mcpUrl) {
+  const rt = runtimeById(runtimeId);
+  if (!rt.mcp) throw new Error(`runtime '${rt.id}' cannot take an MCP server: ${rt.blocked}`);
+  return rt.mcp(token, mcpUrl);
+}
 
 // Turn one Claude tool_use into a compact activity {kind, label}, or null for
 // tools not worth surfacing. `kind:'read'` is what the file counter counts; a
 // Write/Edit of a vault page is the "writing" signal. Used by wiki turns to
 // stream exactly which files Claude is touching (daemon console + app cover).
-export function humanizeToolUse(name, input = {}, cwd = '') {
-  switch (name) {
-    case 'Read':
-      return { kind: 'read', label: `read ${shortPath(input.file_path, cwd)}` };
-    // Vault authoring: Write/Edit of a markdown page is the "writing" signal
-    // (the wiki turn's only legal writes are vault files). Label with the last
-    // two path segments — the vault lives outside cwd, so shortPath can't trim.
-    case 'Write':
-    case 'Edit': {
-      const p = String(input.file_path ?? '');
-      const tail = p.split('/').slice(-2).join('/');
-      // `path` is what lets a caller count DISTINCT pages: a page written once
-      // and then edited twice is one page, and the label alone cannot say that
-      // (it changes between '+ page' and '~ page' for the same file).
-      return { kind: 'write', path: p, label: `${name === 'Write' ? '+ page' : '~ page'} ${tail}` };
-    }
-    case 'Grep':
-      return {
-        kind: 'search',
-        label: `grep ${JSON.stringify(input.pattern ?? '')}${input.path ? ` in ${shortPath(input.path, cwd)}` : ''}`,
-      };
-    case 'Glob':
-      return { kind: 'glob', label: `glob ${input.pattern ?? ''}` };
-    case 'LS':
-      return { kind: 'list', label: `ls ${shortPath(input.path ?? '.', cwd)}` };
-    case 'Bash':
-      return { kind: 'bash', label: `$ ${String(input.command ?? '').replace(/\s+/g, ' ').slice(0, 60)}` };
-    default:
-      return null; // other tools: silent
-  }
-}
+//
+// The body moved to runtimes.mjs, beside Codex's equivalent, because they are
+// the same job for two vendors and keeping them apart is how the two activity
+// vocabularies drift. Re-exported under its original name: a dozen call sites
+// know it, and none of them care where it lives.
+export const humanizeToolUse = humanizeClaudeTool;
 
 // Collapse whitespace + clip so a narration/thinking snippet is one tidy feed line.
 const oneLine = (s, n = 160) => String(s).replace(/\s+/g, ' ').trim().slice(0, n);
@@ -603,24 +594,40 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText }) {
 // returned string for sentinel detection, and each activity is handed to
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
-export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn, streamJson, onActivity, wikiPerm, readOnly, model, effort }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, onActivity, wikiPerm, readOnly, model, effort }) {
   return new Promise((resolve) => {
-    const args = [];
-    if (resume) args.push('--continue');
-    args.push('-p', prompt, '--append-system-prompt', system);
-    // Wiki-vault turns are pure file work — no MCP server at all.
-    if (mcpConfig) args.push('--mcp-config', mcpConfig);
-    // Pin the model — never inherit the user's global default (which may be a
-    // 1M/long-context tier their subscription can't bill autonomous work on).
-    // A per-task override (chosen in the app, validated server-side against a
-    // fixed list before it ever reaches this argv) wins over the machine pin;
-    // absent, the pin stands. Effort has no machine-level pin at all: unset
-    // means Claude Code's own default, which is the honest resting state.
-    args.push('--model', model || MODEL);
-    if (effort) args.push('--effort', effort);
-    if (streamJson) args.push('--output-format', 'stream-json', '--verbose');
+    const rt = runtimeById(runtime);
+    if (!rt.args) {
+      // Reached only if a brief names a runtime this daemon declares but cannot
+      // drive. Fail as a turn with no sentinel — the loop already treats that as
+      // "the protocol did not complete" and retries, rather than inventing a
+      // completion for work that never started.
+      console.error(`\nerror: cannot run '${rt.label}' — ${rt.blocked}`);
+      resolve('');
+      return;
+    }
+    // Pin the model — never inherit the user's global default (which for Claude
+    // may be a 1M/long-context tier their subscription can't bill autonomous
+    // work on). A per-task override (chosen in the app, validated server-side
+    // against a fixed list before it ever reaches this argv) wins over the
+    // machine pin; absent, the pin stands. Effort has no machine-level pin at
+    // all: unset means the CLI's own default, the honest resting state.
+    //
     // readOnly wins over wikiPerm: a consult must never inherit write tools.
-    args.push(...(readOnly ? CONSULT_PERM : wikiPerm ? WIKI_PERM : PERM));
+    const args = rt.args({
+      prompt,
+      system,
+      model,
+      effort,
+      resume,
+      streamJson,
+      perm: readOnly ? CONSULT_PERM : wikiPerm ? WIKI_PERM : PERM,
+      // Handed to the adapter rather than appended here, because WHERE these go
+      // is a property of the CLI: Codex reads its prompt as a trailing
+      // positional, so a flag after it is a flag in the wrong place.
+      // Wiki-vault turns are pure file work and pass neither — no MCP at all.
+      mcp: mcpConfig ? ['--mcp-config', mcpConfig] : (mcpArgs ?? []),
+    });
     // Whatever this machine is signed in with, we use. We do NOT pick.
     //
     // This used to delete ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN to force
@@ -632,26 +639,49 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn
     // deliberately configured.
     //
     // Which credential is correct, and whether an account may be shared, is
-    // between the operator and Anthropic. Flowviant does not detect it and does
-    // not enforce it; it runs Claude the ordinary way and relays what happens.
-    const child = spawn('claude', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    // between the operator and the vendor. Flowviant does not detect it and does
+    // not enforce it; it runs the CLI the ordinary way and relays what happens.
+    const child = spawn(rt.bin, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Only ADDS to the environment (the worker token, for runtimes that read
+      // it from there). Never replaces it: the CLI's own credentials live in
+      // this environment, and handing it a curated one signs it out.
+      ...(mcpEnv ? { env: { ...process.env, ...mcpEnv } } : {}),
+    });
     onSpawn?.(child);
     let out = '';
     const pfx = label ? `${label} ` : '';
     const emit = (s) => process.stdout.write(pfx ? s.replace(/\n/g, `\n${pfx}`) : s);
 
-    if (streamJson) {
+    // A runtime with its own parser is ALWAYS line-parsed — for Codex the JSONL
+    // stream is the only output there is, so treating it as raw text would print
+    // event objects at the operator and, worse, hand the sentinel matcher a
+    // string containing every word the model reasoned about.
+    const lineParsed = streamJson || Boolean(rt.parse);
+    if (lineParsed) {
       let buf = '';
       const appendText = (t) => {
         out += t;
       };
+      /** One line of the child's stdout, in whichever dialect it speaks. */
+      const onLine = (line) => {
+        if (!rt.parse) return handleStreamLine(line, { cwd, emit, onActivity, appendText });
+        const ev = rt.parse(line, cwd);
+        if (!ev) return;
+        if (ev.text) appendText(ev.text);
+        if (ev.activity) {
+          emit(`${ev.activity.label}\n`);
+          onActivity?.(ev.activity);
+        }
+      };
       child.stdout.on('data', (d) => {
         buf += d.toString();
         let nl;
         while ((nl = buf.indexOf('\n')) >= 0) {
           const line = buf.slice(0, nl);
           buf = buf.slice(nl + 1);
-          if (line.trim()) handleStreamLine(line, { cwd, emit, onActivity, appendText });
+          if (line.trim()) onLine(line);
         }
       });
       // stderr is not JSON (warnings/errors) — pass through and keep for sentinels.
@@ -662,14 +692,14 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn
       });
       child.on('error', (e) => {
         if (e.code === 'ENOENT') {
-          console.error("\nerror: 'claude' CLI not found on PATH. Install Claude Code first.");
+          console.error(`\nerror: '${rt.bin}' CLI not found on PATH. Install ${rt.label} first: ${rt.install}`);
           process.exit(1);
         }
         console.error(e);
         resolve(out);
       });
       child.on('close', () => {
-        if (buf.trim()) handleStreamLine(buf, { cwd, emit, onActivity, appendText });
+        if (buf.trim()) onLine(buf);
         resolve(out);
       });
       return;
@@ -684,7 +714,7 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn
     child.stderr.on('data', onChunk);
     child.on('error', (e) => {
       if (e.code === 'ENOENT') {
-        console.error("\nerror: 'claude' CLI not found on PATH. Install Claude Code first.");
+        console.error(`\nerror: '${rt.bin}' CLI not found on PATH. Install ${rt.label} first: ${rt.install}`);
         process.exit(1);
       }
       console.error(e);

package/bin/lib/fleet.mjs

@@ -44,7 +44,7 @@ import { c, LABEL_COLORS, info, note, ok, warn, fail } from './ui.mjs';
 import { revertPatch, withPatchLock } from './patch.mjs';
 import {
   sleep,
-  mcpConfigFor,
+  mcpFor,
   runTurn,
   sawSentinel,
   blockedId,
@@ -76,6 +76,7 @@ import {
 } from './env.mjs';
 import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
 import { machineSnapshot } from './resources.mjs';
+import { detectRuntimes } from './runtimes.mjs';
 
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
@@ -85,6 +86,26 @@ async function fetchRoster(haveIds) {
   // machine knows its cores, its RAM and whose Claude quota is being spent.
   // Older servers ignore the param, so sending it is always safe.
   url.searchParams.set('capacity', String(MAX_CONCURRENT));
+  // WHICH CLIs this machine actually has, so the app can stop guessing.
+  //
+  // Until now every surface that listed Gemini or Codex said "not wired up yet"
+  // and meant it literally: nothing had ever looked. That was the honest answer
+  // while it was true, and it stops being honest the moment a second runtime can
+  // run — an app that cannot tell "Codex is not installed" from "we never
+  // checked" will confidently tell you the wrong one.
+  //
+  // A statement about this MACHINE and nothing else: no account, no quota, no
+  // entitlement. Detection is cached after the first poll (one version probe per
+  // CLI), so this costs a query param thereafter. Older servers ignore an
+  // unknown param, so sending it is always safe.
+  try {
+    const drivable = detectRuntimes()
+      .filter((r) => r.dispatchable)
+      .map((r) => r.id);
+    if (drivable.length) url.searchParams.set('runtimes', drivable.join(','));
+  } catch {
+    /* detection is best-effort — a probe must never fail the poll */
+  }
   // Env-sync identity + materialized version (the Settings "env vN" chip).
   try {
     for (const [k, v] of Object.entries(await envQueryParams())) {
@@ -204,6 +225,9 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
   // intent — without remembering it here, the entire post-blocker half of a run
   // reports no diffstat and the tray blanks mid-build.
   let heldIntentId = null;
+  // The CLI the task in flight is being built by — held across a resume for
+  // the reason documented at the assignment below.
+  let heldRuntime = 'claude';
   let phase = ''; // '', 'idle', 'blocked' — log each transition once, not per poll
   const enter = (p, fn, msg) => {
     if (phase !== p) {
@@ -230,13 +254,21 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
       materializeInto(cwd); // reset wiped the env files (git clean -fd) — rewrite
       needsReset = false;
     }
-    const { dir, path: mcpConfig } = mcpConfigFor(token, getMcpUrl());
     // The task the server says is next for this lane, read ONCE per turn: the
-    // model and effort below become process flags, so they must describe the
-    // same task the kickoff tells Claude to claim. Re-reading the map mid-turn
-    // could pair one task's flags with another's work.
+    // runtime, model and effort below become process flags, so they must
+    // describe the same task the kickoff tells the agent to claim. Re-reading
+    // the map mid-turn could pair one task's flags with another's work.
     const next = resuming ? null : getNext?.(agentId) || null;
     if (next?.intentId) heldIntentId = next.intentId;
+    // WHICH CLI builds this one. Chosen in the app by @mentioning it and carried
+    // on the roster hint; absent (older server, or a task captured before there
+    // was a choice) it is Claude, which is what every task ran on until now.
+    //
+    // A resume must keep the runtime it started on — the session, the worktree
+    // and the branch all belong to that CLI, and handing its half-finished work
+    // to a different one mid-task is not a fallback, it is a second author.
+    if (!resuming) heldRuntime = next?.runtime || 'claude';
+    const { dir, args: mcpArgs, env: mcpEnv } = mcpFor(heldRuntime, token, getMcpUrl());
     let out = '';
     // Report what this run is changing, while it is changing it. The commits
     // endpoint can only describe work that has already reached the provider, so
@@ -255,10 +287,12 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
         resume: resuming,
         system: SYSTEM_SINGLE,
         cwd,
-        mcpConfig,
+        runtime: heldRuntime,
+        mcpArgs,
+        mcpEnv,
         label,
         // Per-task overrides — null/absent means this machine's own defaults
-        // (FLOWVIANT_MODEL, and Claude Code's own effort). A resume keeps the
+        // (FLOWVIANT_MODEL, and the CLI's own effort). A resume keeps the
         // session it already has, so there is nothing to re-pick there.
         model: next?.model || undefined,
         effort: next?.effort || undefined,
@@ -266,7 +300,9 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
       });
     } finally {
       stopDiffstat?.();
-      rmSync(dir, { recursive: true, force: true });
+      // `dir` is null for a runtime that needed no file on disk (Codex reads its
+      // token from the environment) — rmSync would throw on undefined.
+      if (dir) rmSync(dir, { recursive: true, force: true });
       onChild?.(null);
     }
     if (!isAlive()) break;

package/bin/lib/live.mjs

@@ -568,7 +568,7 @@ export async function runLiveTask({
   sampleDiffstat,
   agentId,
 }) {
-  const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
+  const claim = await mcpCall(mcpUrl, token, 'claim_next_task', {}).catch(() => null);
   if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
   const { runId, intentId } = claim;
   const brief = claim.brief ?? {};

package/bin/lib/runtimes.mjs

@@ -0,0 +1,363 @@
+/**
+ * WHICH CLI builds a task, and how you drive it.
+ *
+ * The daemon spoke exactly one runtime for its whole life, and that assumption
+ * is spread thinner than it looks: `claude -p` argv in one place, but also a
+ * `--mcp-config` file, an `--append-system-prompt`, a `stream-json` event schema
+ * and a set of sentinel words the turn loop reads out of stdout. A second CLI is
+ * not a different binary name — it is a different answer to each of those.
+ *
+ * So each runtime declares its own answers here, and everything else in the
+ * daemon asks this module rather than knowing them.
+ *
+ * WHAT A RUNTIME MUST BE ABLE TO DO to build a Flowviant task at all:
+ *   1. run headless from one prompt and exit,
+ *   2. talk to the flowviant MCP server — this is the whole control plane, and a
+ *      runtime that cannot reach it cannot claim work, report a blocker, attach
+ *      a PR or complete, which is to say it cannot participate,
+ *   3. act without asking permission per tool call (there is no terminal here),
+ *   4. emit machine-readable progress, or the thread goes silent for the length
+ *      of a build.
+ * Claude Code and Codex both do all four. Antigravity does 1, 3 and 4 and is
+ * declared below with the exact reason it cannot yet do 2.
+ *
+ * WHAT THIS MODULE DELIBERATELY DOES NOT DO: pick. Which runtime runs a task is
+ * decided in the app, by @mentioning it (CLAUDE.md: the @mention is the only
+ * dispatch), and arrives on the brief. Detection here answers "what does this
+ * machine HAVE" — activity, never capacity, and never a default we invented.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SAFE, MODEL, USER_AGENT } from './config.mjs';
+
+/** Truncate for a one-line activity label. */
+const oneLine = (s, n = 140) =>
+  String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, n);
+
+const shortPath = (p, cwd) => {
+  const s = String(p ?? '');
+  return cwd && s.startsWith(cwd) ? s.slice(cwd.length).replace(/^\//, '') : s;
+};
+
+// ── Claude Code ────────────────────────────────────────────────────────────
+
+/**
+ * Tool-call → one line of activity. Claude's tool names, unchanged from when
+ * this lived in claude.mjs; `kind` is the daemon's own vocabulary and every
+ * runtime's parser must speak it (`read` is what the wiki file counter counts,
+ * `write` carries `path` so distinct pages can be counted).
+ */
+export function humanizeClaudeTool(name, input = {}, cwd = '') {
+  switch (name) {
+    case 'Read':
+      return { kind: 'read', label: `read ${shortPath(input.file_path, cwd)}` };
+    case 'Write':
+    case 'Edit': {
+      const p = String(input.file_path ?? '');
+      const tail = p.split('/').slice(-2).join('/');
+      return { kind: 'write', path: p, label: `${name === 'Write' ? '+ page' : '~ page'} ${tail}` };
+    }
+    case 'Grep':
+      return {
+        kind: 'search',
+        label: `grep ${JSON.stringify(input.pattern ?? '')}${input.path ? ` in ${shortPath(input.path, cwd)}` : ''}`,
+      };
+    case 'Glob':
+      return { kind: 'glob', label: `glob ${input.pattern ?? ''}` };
+    case 'LS':
+      return { kind: 'list', label: `ls ${shortPath(input.path ?? '.', cwd)}` };
+    case 'Bash':
+      return { kind: 'bash', label: `$ ${oneLine(input.command, 60)}` };
+    default:
+      return null; // other tools: silent
+  }
+}
+
+// ── Codex ──────────────────────────────────────────────────────────────────
+
+/**
+ * Codex item → activity, in the daemon's vocabulary.
+ *
+ * The event names and item types below are not guesses: they were read off the
+ * shipped 0.147 binary (`ThreadStarted`/`TurnCompleted`/`ItemCompleted`, items
+ * `agent_message` / `reasoning` / `command_execution` / `file_change` /
+ * `mcp_tool_call` / `web_search` / `todo_list`). Unknown item types return null
+ * and stay silent rather than printing a raw JSON blob into someone's console.
+ */
+function humanizeCodexItem(item = {}, cwd = '') {
+  switch (item.item_type ?? item.type) {
+    case 'agent_message':
+      return { kind: 'say', label: oneLine(item.text ?? item.message) };
+    case 'reasoning':
+      return { kind: 'think', label: oneLine(item.text) || 'thinking…' };
+    case 'command_execution':
+      return { kind: 'bash', label: `$ ${oneLine(item.command, 60)}` };
+    case 'file_change': {
+      // `changes` is a list of touched paths; the daemon counts distinct files,
+      // so emit one activity per path rather than one for the batch.
+      const first = (item.changes ?? [])[0] ?? {};
+      const p = String(first.path ?? '');
+      const tail = p.split('/').slice(-2).join('/');
+      const verb = first.kind === 'add' ? '+' : first.kind === 'delete' ? '-' : '~';
+      return { kind: 'write', path: p, label: `${verb} ${tail || 'file'}` };
+    }
+    case 'mcp_tool_call':
+      return { kind: 'tool', label: `${item.server ?? 'mcp'}.${item.tool ?? ''}` };
+    case 'web_search':
+      return { kind: 'search', label: `search ${oneLine(item.query, 60)}` };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Codex `--json` emits JSONL of ThreadEvents. Returns `{ activity, text }` —
+ * `text` accumulates the agent's own words, because the turn loop reads its
+ * sentinels (NOTHING / BLOCKED:<id> / DONE) out of exactly that.
+ */
+function parseCodexLine(line, cwd) {
+  let ev;
+  try {
+    ev = JSON.parse(line);
+  } catch {
+    return null; // not every line is JSON (warnings go to stderr, but be safe)
+  }
+  switch (ev.type) {
+    case 'item.completed': {
+      const item = ev.item ?? {};
+      const activity = humanizeCodexItem(item, cwd);
+      // Only the agent's MESSAGES are sentinel-bearing text. Reasoning is not:
+      // a model that muses "I could output NOTHING here" must not end the turn.
+      const text =
+        (item.item_type ?? item.type) === 'agent_message'
+          ? `${item.text ?? item.message ?? ''}\n`
+          : '';
+      return { activity, text };
+    }
+    case 'turn.failed':
+      return {
+        activity: { kind: 'error', label: oneLine(ev.error?.message ?? 'turn failed') },
+        text: '',
+      };
+    default:
+      return null; // thread.started / turn.started / item.started / item.updated
+  }
+}
+
+// ── The registry ───────────────────────────────────────────────────────────
+
+/**
+ * How each runtime is told about the flowviant MCP server.
+ *
+ * This is the part that differs most, and it is worth naming why it matters:
+ * the token handed over here is a WORKER token scoped to one lane, minted fresh
+ * and dropped at the end of the turn. Anything that forces a machine-wide config
+ * file forces one shared token for every lane instead, which is a real downgrade
+ * in blast radius — so a runtime that cannot take per-invocation config does not
+ * get to run, rather than getting to run less safely.
+ *
+ * Claude takes a config file path (`--mcp-config`), so the token lands in a
+ * 0600 temp file the caller deletes. Codex takes dotted `-c` overrides and can
+ * read the bearer token from an ENV VAR (`bearer_token_env_var`), so its token
+ * never touches disk at all — strictly better, and the reason Codex was the
+ * first second-runtime rather than the easiest-looking one.
+ */
+function claudeMcp(token, mcpUrl) {
+  const dir = mkdtempSync(join(tmpdir(), 'flowviant-mcp-'));
+  const path = join(dir, 'mcp.json');
+  writeFileSync(
+    path,
+    JSON.stringify({
+      mcpServers: {
+        flowviant: {
+          type: 'http',
+          url: mcpUrl,
+          headers: { Authorization: `Bearer ${token}`, 'User-Agent': USER_AGENT },
+        },
+      },
+    }),
+    { mode: 0o600 }
+  );
+  return { dir, args: ['--mcp-config', path], env: {} };
+}
+
+function codexMcp(token, mcpUrl) {
+  return {
+    dir: null, // nothing written — the token rides in the environment
+    args: [
+      '-c',
+      `mcp_servers.flowviant.url="${mcpUrl}"`,
+      '-c',
+      'mcp_servers.flowviant.bearer_token_env_var="FLOWVIANT_MCP_TOKEN"',
+    ],
+    env: { FLOWVIANT_MCP_TOKEN: token },
+  };
+}
+
+export const RUNTIMES = {
+  claude: {
+    id: 'claude',
+    label: 'Claude Code',
+    vendor: 'Anthropic',
+    bin: 'claude',
+    install: 'npm i -g @anthropic-ai/claude-code',
+    login: 'claude',
+    /** The Agent-SDK live session (persistent, injectable mid-task) is Claude
+     *  only — it is an Anthropic SDK, not a CLI contract. Everything else runs
+     *  the subprocess path. */
+    live: true,
+    mcp: claudeMcp,
+    /**
+     * Claude takes the operating contract as a real system prompt, which is the
+     * strongest form of it available anywhere: `--append-system-prompt` sits
+     * above the conversation rather than inside it.
+     */
+    args({ prompt, system, model, effort, resume, streamJson, perm, mcp = [] }) {
+      const a = [];
+      if (resume) a.push('--continue');
+      a.push('-p', prompt, '--append-system-prompt', system);
+      a.push(...mcp);
+      a.push('--model', model || MODEL);
+      if (effort) a.push('--effort', effort);
+      if (streamJson) a.push('--output-format', 'stream-json', '--verbose');
+      a.push(...perm);
+      return a;
+    },
+    parse: null, // claude.mjs owns its own stream parser (unchanged)
+  },
+
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    vendor: 'OpenAI',
+    bin: 'codex',
+    install: 'npm i -g @openai/codex',
+    login: 'codex login',
+    live: false,
+    mcp: codexMcp,
+    /**
+     * Codex has NO system-prompt flag. The contract therefore rides inside the
+     * prompt, fenced and placed first, and this is a genuine weakening worth
+     * stating plainly: a system prompt is a rule, and a prompt preamble is a
+     * strong suggestion the model may drift from over a long turn. It is the
+     * best available; AGENTS.md was the alternative and is worse, because it is
+     * a FILE IN THE WORKTREE — one `git add -A` from being committed into the
+     * user's repository, which is not a risk worth taking for a slightly
+     * stickier instruction.
+     *
+     * `--skip-git-repo-check` is deliberately NOT passed: a task always builds
+     * in a git worktree, and if it somehow is not one, failing loudly beats
+     * silently editing files nobody can diff.
+     *
+     * THE PROMPT IS LAST, and that is load-bearing rather than tidy. Codex takes
+     * it as a trailing POSITIONAL, so every flag — including the two `-c` MCP
+     * overrides, which the caller hands in rather than appending — has to be
+     * 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, perm: _perm, mcp = [] }) {
+      const a = ['exec'];
+      if (resume) a.push('resume', '--last');
+      a.push('--json');
+      if (model) a.push('--model', model);
+      // Effort is a config value on Codex rather than a flag.
+      if (effort) a.push('-c', `model_reasoning_effort="${effort}"`);
+      // The daemon's posture, mapped: SAFE keeps writes inside the workspace,
+      // the default lets the agent run its own tests and git commands. Neither
+      // asks a human — there is no human on this end of the pipe.
+      a.push('--sandbox', SAFE ? 'workspace-write' : 'danger-full-access');
+      a.push(...mcp);
+      a.push(`${system}\n\n---\n\n${prompt}`);
+      return a;
+    },
+    parse: parseCodexLine,
+  },
+
+  /**
+   * DECLARED, NOT DRIVABLE — and the reason is specific, not a shrug.
+   *
+   * `agy` has everything else this needs: `-p` for headless, `--output-format
+   * stream-json`, `--model`, `--effort`, `--continue`, and
+   * `--dangerously-skip-permissions`. What it has no per-invocation form of is
+   * the MCP server: config lives at `~/.gemini/config/mcp_config.json`, the
+   * workspace-local `.agents/mcp_config.json` is read-but-ignored (upstream
+   * antigravity-cli#60), and the HOME-level file cannot be made per-lane —
+   * pointing HOME elsewhere would take the cached credentials the headless mode
+   * signs in with along with it.
+   *
+   * So running Antigravity today means one shared MCP token across every lane on
+   * the machine, which is exactly the blast radius the per-lane token exists to
+   * prevent. It is listed so `flowviant doctor` can say "installed, and here is
+   * what is missing" rather than pretending we never looked — the same posture
+   * the app's @ tray takes. When either the workspace config is fixed upstream
+   * or a flag appears, this becomes an `mcp` function and a `parse`, and nothing
+   * else in the daemon changes.
+   */
+  antigravity: {
+    id: 'antigravity',
+    label: 'Antigravity',
+    vendor: 'Google',
+    bin: 'agy',
+    install: 'see antigravity.google/docs/cli',
+    login: 'agy',
+    live: false,
+    mcp: null,
+    args: null,
+    parse: null,
+    blocked: 'no per-invocation MCP config — its server list is machine-wide, so every lane would share one token',
+  },
+};
+
+/** Runtimes this daemon can actually put a task on. */
+export const DISPATCHABLE = Object.values(RUNTIMES).filter((r) => r.mcp && r.args);
+
+export const runtimeById = (id) => RUNTIMES[id] ?? RUNTIMES.claude;
+
+// ── Detection ──────────────────────────────────────────────────────────────
+
+/**
+ * Which of these is on this machine, asked once.
+ *
+ * `--version` rather than `which`: a binary on PATH that cannot execute (a
+ * broken install, a wrong-arch download, a shell alias pointing at nothing) is
+ * not a runtime you can dispatch to, and reporting it as one sends work into a
+ * hole. 5s is generous for a version print and short enough that three missing
+ * CLIs cannot stall a roster poll.
+ *
+ * Reported to the server on the roster poll so the app can stop saying "we have
+ * not looked". It is a statement about THIS MACHINE and nothing else — no
+ * account, no quota, no entitlement. Flowviant relays; it does not enforce.
+ */
+let detectedCache = null;
+export function detectRuntimes({ refresh = false } = {}) {
+  if (detectedCache && !refresh) return detectedCache;
+  detectedCache = Object.values(RUNTIMES).map((rt) => {
+    let version = null;
+    try {
+      version = String(
+        execFileSync(rt.bin, ['--version'], {
+          timeout: 5000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+      )
+        .trim()
+        .split('\n')[0]
+        .slice(0, 40);
+    } catch {
+      version = null;
+    }
+    return {
+      id: rt.id,
+      installed: version !== null,
+      version,
+      // Installed and drivable are different questions, and conflating them is
+      // how a user ends up @mentioning something that silently never starts.
+      dispatchable: version !== null && Boolean(rt.mcp && rt.args),
+      blocked: rt.blocked ?? null,
+    };
+  });
+  return detectedCache;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flowviant",
-  "version": "0.37.0",
-  "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
+  "version": "0.38.0",
+  "description": "Run your own coding CLIs as headless build agents for Flowviant \u2014 Claude Code or Codex, on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {
     "flowviant": "bin/cli.mjs"