create-byan-agent 2.45.0 → 2.47.1

package/install/templates/_byan/mcp/byan-mcp-server/lib/agent-matcher.js

@@ -0,0 +1,167 @@
+// F1 — the agent SUITABILITY matcher: the pre-filter Hermes+BYAN present at the
+// entry gate. Given a task description and the agent roster, it ranks the
+// candidates and returns a verdict {fit | no-fit}. It NEVER decides alone — it
+// PROPOSES; the user validates (double validation IA + human). A no-fit verdict
+// is the signal to run the interview -> web-research -> create-agent path instead
+// of a workflow.
+//
+// Pure core (matchAgents) has no I/O so it is fully unit-testable. The loader
+// (loadRoster) reads the roster from _byan/_config/agent-manifest.csv, isolated
+// from the scoring.
+//
+// Scoring = curated Hermes trigger words (strong signal) layered on top of a
+// plain text overlap with each agent's title+role. Deterministic: same input,
+// same ranking.
+
+import fs from 'node:fs';
+
+// Fit verdict floor. A best score at/above this = at least one solid signal that
+// an existing agent covers the need; below it, no agent fits -> interview.
+export const FIT_THRESHOLD = 3;
+
+// Curated Hermes routing signal: trigger word (deburred) -> agent name. This is
+// the strong layer (weighted x3 in the score) because these are the hand-picked
+// dispatch cues, not incidental text. Kept in sync in spirit with
+// .claude/rules/hermes-dispatcher.md.
+export const DOMAIN_KEYWORDS = Object.freeze({
+  analyst: ['analyse', 'analyser', 'requirement', 'requirements', 'brief', 'etude', 'marche', 'concurrent', 'besoin'],
+  architect: ['architecture', 'architect', 'conception', 'concois', 'systeme', 'stack', 'scalab', 'infrastructure', 'api'],
+  dev: ['code', 'coder', 'implemente', 'implementer', 'implement', 'developpe', 'dev', 'feature', 'refactor', 'bug', 'debug', 'fix', 'script', 'module', 'fonction', 'endpoint'],
+  quinn: ['test', 'tester', 'qa', 'coverage', 'couverture', 'assurance qualite'],
+  'tea-tea': ['atdd', 'nfr', 'test architect', 'ci/cd', 'automation de test'],
+  sm: ['sprint', 'backlog', 'scrum', 'planifier', 'planification', 'story', 'epic'],
+  'tech-writer': ['documente', 'documenter', 'documentation', 'guide', 'readme', 'redige'],
+  'ux-designer': ['ux', 'ui', 'mockup', 'maquette', 'interface', 'wireframe', 'design ux'],
+  pm: ['prd', 'produit', 'roadmap', 'product', 'vision produit'],
+  byan: ['creer un agent', 'nouvel agent', 'workflow byan', 'nouveau module'],
+  'brainstorming-coach': ['brainstorm', 'idee', 'ideation', 'innovation', 'remue-meninge'],
+  carmack: ['optimiser', 'optimisation', 'token', 'performance', 'perf'],
+});
+
+const STOPWORDS = new Set([
+  'le', 'la', 'les', 'un', 'une', 'des', 'de', 'du', 'et', 'ou', 'pour', 'avec',
+  'sur', 'dans', 'que', 'qui', 'ce', 'cette', 'mon', 'ma', 'mes', 'ton', 'son',
+  'the', 'a', 'an', 'of', 'to', 'and', 'or', 'for', 'with', 'on', 'in', 'is',
+  'fait', 'faire', 'veux', 'peux', 'ajoute', 'cree', 'creer', 'besoin', 'agent',
+]);
+
+// deburr: lowercase + strip French diacritics so "marché" matches "marche".
+export function deburr(s) {
+  return String(s == null ? '' : s)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, ''); // strip combining diacritics
+}
+
+function tokenize(text) {
+  return deburr(text)
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length >= 3 && !STOPWORDS.has(w));
+}
+
+// scoreAgent — pure per-agent score. keyword hits (x3) + title/role text overlap.
+export function scoreAgent(taskText, agent) {
+  const task = deburr(taskText);
+  const taskTokens = new Set(tokenize(taskText));
+  let keywordScore = 0;
+  const hits = [];
+  const kws = DOMAIN_KEYWORDS[agent.name] || [];
+  for (const kw of kws) {
+    if (task.includes(deburr(kw))) { keywordScore += 1; hits.push(kw); }
+  }
+  const agentTokens = tokenize(`${agent.title || ''} ${agent.role || ''}`);
+  let textScore = 0;
+  for (const t of agentTokens) if (taskTokens.has(t)) textScore += 1;
+  return { score: keywordScore * 3 + textScore, keywordScore, textScore, hits };
+}
+
+// matchAgents(taskText, roster) -> {
+//   fit, needsInterview, best, candidates: [{ name, title, score, why }]
+// }
+// candidates are ranked desc and limited to those with a non-zero score.
+export function matchAgents(taskText, roster, { threshold = FIT_THRESHOLD, limit = 3 } = {}) {
+  const scored = (Array.isArray(roster) ? roster : [])
+    .map((agent) => {
+      const s = scoreAgent(taskText, agent);
+      return {
+        name: agent.name,
+        title: agent.title || agent.displayName || agent.name,
+        score: s.score,
+        why: s.hits.length ? `mots-cles: ${s.hits.join(', ')}` : (s.textScore ? 'recoupement titre/role' : ''),
+      };
+    })
+    .filter((c) => c.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  const candidates = scored.slice(0, limit);
+  const best = candidates[0] || null;
+  const fit = Boolean(best && best.score >= threshold);
+  return {
+    fit,
+    needsInterview: !fit,
+    best,
+    candidates,
+    recommendation: fit
+      ? `Un agent adapte existe : @${best.name} (${best.why}). A valider.`
+      : "Aucun agent adapte trouve. Proposer une interview pour en creer un sur mesure.",
+  };
+}
+
+// --- loader (I/O isolated) ------------------------------------------------
+
+// Minimal RFC-4180-ish CSV parser: handles double-quoted fields with embedded
+// commas and escaped quotes (""). Enough for agent-manifest.csv; not a general
+// CSV engine.
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  const src = String(text == null ? '' : text);
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (src[i + 1] === '"') { field += '"'; i++; }
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') {
+      inQuotes = true;
+    } else if (c === ',') {
+      row.push(field); field = '';
+    } else if (c === '\n' || c === '\r') {
+      if (c === '\r' && src[i + 1] === '\n') i++;
+      row.push(field); field = '';
+      if (row.length > 1 || row[0] !== '') rows.push(row);
+      row = [];
+    } else field += c;
+  }
+  if (field !== '' || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+// rosterFromCsv(text) -> [{ name, displayName, title, role }]. Pure (no fs).
+export function rosterFromCsv(text) {
+  const rows = parseCsv(text);
+  if (!rows.length) return [];
+  const header = rows[0].map((h) => h.trim());
+  const idx = (col) => header.indexOf(col);
+  const iName = idx('name'), iDisplay = idx('displayName'), iTitle = idx('title'), iRole = idx('role');
+  return rows.slice(1)
+    .filter((r) => r[iName])
+    .map((r) => ({
+      name: r[iName],
+      displayName: iDisplay >= 0 ? r[iDisplay] : '',
+      title: iTitle >= 0 ? r[iTitle] : '',
+      role: iRole >= 0 ? r[iRole] : '',
+    }));
+}
+
+// loadRoster(manifestPath) -> roster array, or [] if the file is unreadable.
+export function loadRoster(manifestPath) {
+  try {
+    return rosterFromCsv(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return [];
+  }
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/codex-bridge.js

@@ -0,0 +1,176 @@
+// F2 — the Codex TRANSPORT, behind a clean adapter seam.
+//
+// Design (agreed with the user): the durable core (F1 router, F4 loop) must not
+// care HOW we talk to Codex. So the transport is a swappable adapter:
+//   - codex-exec  : SHIPPED. Runs `codex exec` non-interactively, read-only, and
+//                   asks Codex for a unified DIFF on stdout. Codex never writes a
+//                   file (works under Landlock) ; Claude applies the diff. This
+//                   also keeps the verification red line: Claude, not Codex, is
+//                   the one that lands and later checks the change.
+//   - codex-mcp   : V2 SLOT. `codex mcp-server` exposes Codex as a callable tool
+//                   for the tightest live coupling. Not wired yet — the adapter
+//                   exists and honestly reports { available: false } so the loop
+//                   can detect it and stay on codex-exec. It is a declared seam,
+//                   not a stub pretending to work.
+//
+// Purity: everything that BUILDS a command or a prompt is pure and unit-tested.
+// Everything that SPAWNS a process is isolated behind an injected `runner`, so
+// tests exercise the bridge without ever invoking the real Codex CLI.
+//
+// Failure is a value, not an exception: runCodexExec returns { ok:false, reason }
+// on any wire/availability/error path, so F4 can fall back to Claude (the "repli
+// quand Codex sature" the user asked for) instead of crashing the loop.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { CODEX_MODEL, EFFORTS, assertNoFable } from './dispatch-router.js';
+
+export const ADAPTERS = Object.freeze({ EXEC: 'codex-exec', MCP: 'codex-mcp' });
+
+// Codex config keys we drive via `codex exec -c key=value` (TOML values). Kept
+// as named constants: if a Codex release renames one, this is the only edit.
+// sandbox_permissions=["disk-full-read-access"] = read-only (from `codex --help`).
+export const CODEX_CONFIG_KEYS = Object.freeze({
+  MODEL: 'model',
+  EFFORT: 'model_reasoning_effort',
+  SANDBOX: 'sandbox_permissions',
+});
+const READONLY_SANDBOX_TOML = '["disk-full-read-access"]';
+
+// wrapDiffPrompt(task) — wrap a task so Codex returns a unified diff ONLY and does
+// not attempt to modify files. The read-only sandbox already blocks writes; the
+// prompt makes the intent explicit so Codex emits an appliable patch, not prose.
+export function wrapDiffPrompt(task) {
+  const body = String(task == null ? '' : task).trim();
+  return [
+    'You are a delegated implementer. Do NOT modify files directly.',
+    'Produce ONLY a unified diff (git apply compatible) implementing the task,',
+    'between the exact markers <<<DIFF and DIFF>>>. No prose outside the markers.',
+    '',
+    'Task:',
+    body,
+  ].join('\n');
+}
+
+// extractDiff(stdout) — pull the unified diff back out of Codex stdout. Prefers
+// the explicit markers from wrapDiffPrompt; falls back to the first `diff --git`
+// / `---`+`+++` block so a marker-less answer is still usable. Returns '' when no
+// diff is present (caller treats that as "nothing to apply").
+export function extractDiff(stdout) {
+  const text = String(stdout == null ? '' : stdout);
+  const marked = text.match(/<<<DIFF\s*([\s\S]*?)\s*DIFF>>>/);
+  if (marked) return marked[1].trim();
+  const gitDiff = text.match(/(diff --git [\s\S]*)$/);
+  if (gitDiff) return gitDiff[1].trim();
+  return '';
+}
+
+// buildCodexExecArgs({ model, effort, prompt }) -> argv for the `codex` binary.
+// Pure. Fable is refused here too (defence in depth). Effort is validated to the
+// known set; the prompt is the trailing positional argument.
+export function buildCodexExecArgs({ model = CODEX_MODEL, effort = EFFORTS.MEDIUM, prompt = '' } = {}) {
+  assertNoFable(model);
+  const effortValue = Object.values(EFFORTS).includes(effort) ? effort : EFFORTS.MEDIUM;
+  return [
+    'exec',
+    '-c', `${CODEX_CONFIG_KEYS.MODEL}="${model}"`,
+    '-c', `${CODEX_CONFIG_KEYS.EFFORT}="${effortValue}"`,
+    '-c', `${CODEX_CONFIG_KEYS.SANDBOX}=${READONLY_SANDBOX_TOML}`,
+    wrapDiffPrompt(prompt),
+  ];
+}
+
+// buildGitApplyArgs(diffPath) -> argv for `git`. --check first is the caller's
+// choice; this returns the apply form. Pure.
+export function buildGitApplyArgs(diffPath) {
+  return ['apply', '--whitespace=nowarn', String(diffPath)];
+}
+
+// The default process runner. Isolated so every other function stays testable
+// with a fake. Returns a normalized { code, stdout, stderr } shape.
+export function defaultRunner({ cmd, args = [], input = '', cwd = process.cwd(), timeoutMs = 120000 }) {
+  const res = spawnSync(cmd, args, { input, cwd, timeout: timeoutMs, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  return {
+    code: typeof res.status === 'number' ? res.status : (res.error ? -1 : null),
+    stdout: res.stdout || '',
+    stderr: res.stderr || (res.error ? String(res.error.message) : ''),
+  };
+}
+
+// runCodexExec({ model, effort, prompt, cwd, runner, timeoutMs }) ->
+//   { ok:true, diff, raw } | { ok:false, reason, detail }
+// reason: 'unavailable' (binary missing / spawn failed) | 'error' (non-zero exit)
+//         | 'empty' (ran but produced no diff). Never throws for a wire issue —
+// F4 reads ok:false and falls back to Claude.
+export function runCodexExec({ model = CODEX_MODEL, effort = EFFORTS.MEDIUM, prompt = '', cwd = process.cwd(), runner = defaultRunner, timeoutMs = 120000 } = {}) {
+  const args = buildCodexExecArgs({ model, effort, prompt });
+  let res;
+  try {
+    res = runner({ cmd: 'codex', args, cwd, timeoutMs });
+  } catch (e) {
+    return { ok: false, reason: 'unavailable', detail: String(e && e.message || e) };
+  }
+  if (!res || res.code == null || res.code < 0) {
+    return { ok: false, reason: 'unavailable', detail: (res && res.stderr) || 'codex not runnable' };
+  }
+  if (res.code !== 0) {
+    return { ok: false, reason: 'error', detail: res.stderr || `exit ${res.code}` };
+  }
+  const diff = extractDiff(res.stdout);
+  if (!diff) return { ok: false, reason: 'empty', detail: 'codex produced no diff' };
+  return { ok: true, diff, raw: res.stdout };
+}
+
+// applyDiff({ diff, cwd, runner }) -> { ok, detail }. Claude-side apply of the
+// Codex diff via `git apply`. Writes the diff to a temp file (isolated I/O),
+// runs git apply, cleans up. Guards against an empty diff.
+export function applyDiff({ diff, cwd = process.cwd(), runner = defaultRunner } = {}) {
+  const body = String(diff == null ? '' : diff).trim();
+  if (!body) return { ok: false, detail: 'empty diff' };
+  const tmp = path.join(os.tmpdir(), `byan-codex-diff-${process.pid}-${body.length}.patch`);
+  try {
+    fs.writeFileSync(tmp, body.endsWith('\n') ? body : body + '\n');
+    const res = runner({ cmd: 'git', args: buildGitApplyArgs(tmp), cwd, timeoutMs: 30000 });
+    if (res && res.code === 0) return { ok: true, detail: 'applied' };
+    return { ok: false, detail: (res && res.stderr) || 'git apply failed' };
+  } catch (e) {
+    return { ok: false, detail: String(e && e.message || e) };
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
+  }
+}
+
+// probeCodex(runner) -> { available, version|reason }. A cheap liveness check the
+// loop can call once before routing anything to Codex.
+export function probeCodex(runner = defaultRunner) {
+  let res;
+  try {
+    res = runner({ cmd: 'codex', args: ['--version'], timeoutMs: 8000 });
+  } catch (e) {
+    return { available: false, reason: String(e && e.message || e) };
+  }
+  if (res && res.code === 0) return { available: true, version: String(res.stdout || '').trim() };
+  return { available: false, reason: (res && res.stderr) || 'codex --version failed' };
+}
+
+// getAdapter(name, { execImpl }) -> an adapter object. The exec adapter is fully
+// wired; the mcp adapter is the declared V2 seam and reports available:false so
+// the loop stays on exec until it is built (honest, not a fake).
+export function getAdapter(name = ADAPTERS.EXEC, { execImpl = runCodexExec } = {}) {
+  if (name === ADAPTERS.EXEC) {
+    return { name: ADAPTERS.EXEC, available: true, run: execImpl };
+  }
+  if (name === ADAPTERS.MCP) {
+    return {
+      name: ADAPTERS.MCP,
+      available: false, // V2 slot: `codex mcp-server` handshake not wired yet
+      run() {
+        return { ok: false, reason: 'unavailable', detail: 'codex-mcp adapter not wired (V2 slot)' };
+      },
+    };
+  }
+  throw new Error(`codex-bridge: unknown adapter "${name}"`);
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/dispatch-blackboard.js

@@ -0,0 +1,114 @@
+// F3 — the shared BLACKBOARD: the turn-by-turn message log the agents use to
+// exchange information (the honest substitute for a live peer chat). It is the
+// analogue of the byan_web server holding the conversation: each agent reads the
+// board at the start of its turn and appends to it at the end. The orchestrating
+// loop (F4) owns the turn order; this module only stores and renders the exchange.
+//
+// A message is { turn, from, to, kind, content }. `to` may be a specific agent or
+// '*' (broadcast). kind is one of KINDS. Pure functions build and render entries;
+// I/O (append/read a JSONL sidecar under _byan-output/) is isolated so the pure
+// core is unit-testable without the filesystem.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const KINDS = Object.freeze({
+  DESIGN: 'design',
+  WORK: 'work',
+  QUESTION: 'question',
+  ANSWER: 'answer',
+  RESULT: 'result',
+  NOTE: 'note',
+});
+
+export const BROADCAST = '*';
+
+// makeEntry — normalize a raw message into the stored shape. Pure. Coerces the
+// turn to a non-negative integer and trims strings; an unknown kind becomes NOTE
+// (never rejected, so a caller mistake degrades to a visible note rather than a
+// throw mid-loop).
+export function makeEntry({ turn = 0, from = '', to = BROADCAST, kind = KINDS.NOTE, content = '' } = {}) {
+  const t = Number.isInteger(turn) && turn >= 0 ? turn : 0;
+  const k = Object.values(KINDS).includes(kind) ? kind : KINDS.NOTE;
+  return {
+    turn: t,
+    from: String(from).trim(),
+    to: String(to).trim() || BROADCAST,
+    kind: k,
+    content: String(content == null ? '' : content).trim(),
+  };
+}
+
+// entriesForAgent — the subset an agent should see: broadcasts plus anything
+// addressed to it, plus its own messages (so it recalls what it already said).
+// Pure.
+export function entriesForAgent(entries, agentName) {
+  const me = String(agentName || '').trim();
+  return (Array.isArray(entries) ? entries : []).filter(
+    (e) => e && (e.to === BROADCAST || e.to === me || e.from === me)
+  );
+}
+
+// pendingQuestions — questions with no later ANSWER referencing the same asker.
+// A question is answered when a later entry of kind ANSWER is sent to its `from`.
+// Pure; lets the loop decide whether the exchange has converged.
+export function pendingQuestions(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  const questions = list.filter((e) => e && e.kind === KINDS.QUESTION);
+  return questions.filter((q) => {
+    return !list.some(
+      (a) => a && a.kind === KINDS.ANSWER && a.to === q.from && a.turn > q.turn
+    );
+  });
+}
+
+// renderForAgent — the plain-text transcript an agent reads at the start of its
+// turn. One line per relevant entry, in order, direction shown. Pure.
+export function renderForAgent(entries, agentName) {
+  const relevant = entriesForAgent(entries, agentName);
+  if (!relevant.length) return 'Tableau partage : (vide - tu ouvres l echange)';
+  const lines = relevant.map(
+    (e) => `[t${e.turn} ${e.from} -> ${e.to}] ${e.kind}: ${e.content}`
+  );
+  return ['Tableau partage (echange en cours, lis avant de repondre) :', ...lines].join('\n');
+}
+
+// --- I/O (isolated) -------------------------------------------------------
+
+// The board lives under _byan-output/ (gitignored), one JSONL file per dispatch
+// session. Session id is caller-supplied (the loop passes the fd/dispatch id).
+export function blackboardPath(projectDir, sessionId) {
+  const safe = String(sessionId || 'default').replace(/[^A-Za-z0-9._-]/g, '_');
+  return path.join(projectDir, '_byan-output', 'dispatch', safe, 'blackboard.jsonl');
+}
+
+// appendEntry — normalize + append one line. Creates the session dir on first
+// write. Returns the stored entry (best-effort: returns null on an I/O failure so
+// the loop can note it without crashing).
+export function appendEntry(projectDir, sessionId, raw) {
+  const entry = makeEntry(raw);
+  try {
+    const p = blackboardPath(projectDir, sessionId);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+// readEntries — parse the JSONL board into an array, skipping malformed lines.
+// Missing file -> []. Never throws.
+export function readEntries(projectDir, sessionId) {
+  try {
+    const raw = fs.readFileSync(blackboardPath(projectDir, sessionId), 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch { /* skip malformed line */ }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/dispatch-orchestrator.js

@@ -0,0 +1,116 @@
+// F4 — the ORCHESTRATOR core: the loop that makes an architect (Claude) and a
+// dev (Codex or Claude, per F1) exchange turn by turn through the shared board
+// (F3) until the exchange converges, then returns the result. This is the durable,
+// unit-testable heart of "launch a workflow and the agents talk to each other".
+//
+// It runs as full Node (main thread or an MCP worker), NOT inside a sandboxed
+// .claude/workflows script — that sandbox has no imports and no filesystem, so it
+// could never use F1/F2/F3. A native workflow script can only be a THIN launch
+// façade over this core (see docs). The core here owns the routing, the loop, and
+// the convergence rule.
+//
+// Executors are INJECTED so the loop is testable without real agents or Codex:
+//   executors.architect(ctx) -> { content, question? }   (always Claude)
+//   executors.claude(ctx)    -> { content, question? }   (dev work on Claude)
+//   executors.codex(ctx)     -> { content, question?, diff? }  (dev work on Codex)
+// The orchestrator picks executors[route.runtime] for the dev turn; the architect
+// is always Claude (judgment stays on Claude — the verification red line's sibling).
+//
+// Pure control flow: no direct I/O beyond the injected board writer/reader, which
+// default to F3's fs-backed pair but are overridable in tests.
+
+import { dispatch } from './dispatch-router.js';
+import {
+  KINDS,
+  makeEntry,
+  renderForAgent,
+  pendingQuestions,
+  appendEntry as fsAppend,
+  readEntries as fsRead,
+} from './dispatch-blackboard.js';
+
+export const ARCHITECT = 'claude-architect';
+export const DEV = 'dev';
+export const DEFAULT_MAX_ROUNDS = 4;
+
+// A board handle backed by F3's fs sidecar. Tests pass an in-memory one.
+export function fsBoard(projectDir, sessionId) {
+  return {
+    append: (entry) => fsAppend(projectDir, sessionId, entry),
+    read: () => fsRead(projectDir, sessionId),
+  };
+}
+
+// An in-memory board (no I/O) — the default when no projectDir is given, and what
+// tests use. Same shape as fsBoard.
+export function memoryBoard(seed = []) {
+  const entries = seed.map(makeEntry);
+  return {
+    append: (raw) => { const e = makeEntry(raw); entries.push(e); return e; },
+    read: () => entries.slice(),
+  };
+}
+
+// orchestrateTask — run ONE task to convergence. Returns
+//   { route, rounds, entries, status, diffs }
+// status: 'converged' (dev produced a result with no open question)
+//       | 'max-rounds' (hit the round cap still exchanging)
+//       | 'dev-failed' (the dev executor reported a failure -> caller may fall back)
+export function orchestrateTask({ task = {}, board, executors = {}, maxRounds = DEFAULT_MAX_ROUNDS } = {}) {
+  const route = dispatch({ nature: task.nature, complexity: task.complexity });
+  const devExec = executors[route.runtime];
+  const architectExec = executors.architect;
+  if (typeof devExec !== 'function' || typeof architectExec !== 'function') {
+    throw new Error(`orchestrateTask: missing executor for runtime "${route.runtime}" or architect`);
+  }
+
+  // Monotonic message counter (NOT per-round): each append gets the next turn, so
+  // an architect ANSWER always carries a turn strictly greater than the dev
+  // QUESTION it follows — which is what pendingQuestions needs to mark it resolved.
+  let turn = 0;
+  const post = (from, to, kind, content) => board.append({ turn: turn++, from, to, kind, content: content || '' });
+
+  // The architect opens with the design brief (addressed to dev).
+  const opening = architectExec({ task, route, round: 0, transcript: renderForAgent(board.read(), ARCHITECT) });
+  post(ARCHITECT, DEV, KINDS.DESIGN, (opening && opening.content) || task.brief || '');
+
+  const diffs = [];
+  let status = 'max-rounds';
+  for (let round = 1; round <= maxRounds; round++) {
+    // Dev turn: reads the board, does the work on its routed runtime.
+    const devOut = devExec({ task, route, round, transcript: renderForAgent(board.read(), DEV) }) || {};
+    if (devOut.ok === false || devOut.failed === true) {
+      post(DEV, ARCHITECT, KINDS.NOTE, `dev failed: ${devOut.detail || 'unknown'}`);
+      status = 'dev-failed';
+      break;
+    }
+    if (devOut.diff) diffs.push(devOut.diff);
+    post(DEV, ARCHITECT, devOut.question ? KINDS.WORK : KINDS.RESULT, devOut.content);
+    if (devOut.question) post(DEV, ARCHITECT, KINDS.QUESTION, devOut.question);
+
+    // Converged: dev delivered a result and left no open question.
+    if (!pendingQuestions(board.read()).length) { status = 'converged'; break; }
+
+    // Architect answers the open question(s); the higher turn resolves them.
+    const archOut = architectExec({ task, route, round, transcript: renderForAgent(board.read(), ARCHITECT) }) || {};
+    post(ARCHITECT, DEV, KINDS.ANSWER, archOut.content);
+  }
+
+  return { route, messages: board.read().filter((e) => e.turn > 0).length, entries: board.read(), status, diffs };
+}
+
+// orchestrate — run a whole task list. Each task gets its own board namespace when
+// an fs board factory is supplied; otherwise an in-memory board per task. Returns
+// one result per task, in order. Never routes verification to Codex (guaranteed by
+// F1's router, re-asserted here as defence in depth).
+export function orchestrate({ tasks = [], executors = {}, maxRounds = DEFAULT_MAX_ROUNDS, boardFor } = {}) {
+  return (Array.isArray(tasks) ? tasks : []).map((task, i) => {
+    const board = typeof boardFor === 'function' ? boardFor(task, i) : memoryBoard();
+    const result = orchestrateTask({ task, board, executors, maxRounds });
+    if (result.route.runtime === 'codex' && /verif|review|validate|audit/i.test(String(task.nature || ''))) {
+      // Should be impossible (router forces Claude), but fail loud if it ever regresses.
+      throw new Error(`orchestrate: verification task "${task.id || i}" routed to Codex — red line breached`);
+    }
+    return { taskId: task.id != null ? task.id : i, ...result };
+  });
+}