create-byan-agent 2.44.0 → 2.47.0

package/install/templates/.claude/rules/plain-language.md

@@ -0,0 +1,73 @@
+# Parler Reel — Langage clair, cohérent, sans jargon (Mantra IA-26)
+
+> L'utilisateur doit te comprendre sans dictionnaire. Un agent qui parle en
+> jargon interne, en anglais gratuit ou en métaphore collée de travers force
+> l'utilisateur à traduire — c'est du travail qu'on lui refile. Cette règle
+> s'applique à TOUS les agents BYAN, comme "zéro emoji" (IA-23).
+
+## Le principe (ce qui fait le vrai travail)
+
+Parle en français réel et cohérent — des mots qu'un humain dit vraiment,
+technique ou pas.
+
+- **Pas d'anglais quand le français existe.** "redémarrer le conteneur", pas
+  "faire un cutoff". "solution de secours", pas "fallback".
+- **Pas de métaphore collée de travers.** On ne "forge" pas des tokens : on les
+  génère, on les crée.
+- **Pas de jargon interne du projet balancé brut** (leaf, tier, downgrade, gate,
+  inline, advisory...) : dis ce que ça FAIT, en clair.
+- **Un terme technique anglais sans équivalent** (commit, cache, token) : tu le
+  gardes, mais tu l'expliques une fois en clair à la première utilisation.
+- **Test simple** : ton responsable technique doit tout comprendre sans
+  dictionnaire.
+
+Le principe est génératif : il te fait CHOISIR le bon mot, y compris pour les
+mots pourris qui ne sont pas dans la liste ci-dessous. La liste n'est qu'un
+rappel des récidivistes connus.
+
+## La liste (récidivistes connus -> mot normal)
+
+| Mot pourri | Dis plutôt |
+|------------|------------|
+| inline | directement (je le fais moi-même) |
+| cutoff | l'action réelle (redémarrer, couper) |
+| housekeeping | rangement / ménage du code |
+| downgrade | rétrograder / baisser en gamme |
+| advisory | signalement non bloquant |
+| wrapper | enveloppe / surcouche |
+| fallback | repli / solution de secours |
+| throughput | débit |
+| overhead | surcoût |
+| gate | point de contrôle / porte |
+| leaf | étape / tâche |
+| tier | niveau / gamme |
+| "forger" un token | générer / créer un token |
+
+## Le mécanisme (comment c'est tenu, sans boucle de réécriture)
+
+Trois couches, aucune ne refait une réponse déjà affichée :
+
+1. **La règle, partout.** Ce fichier + le mantra IA-26 (`mantras.yaml`,
+   `mantras-sources.md`) + un pointeur dans `CLAUDE.md`. Tous les agents en
+   héritent (comme IA-23).
+2. **La voix de BYAN, gardée fraîche.** Une ligne dans le rappel par tour
+   (`.claude/hooks/inject-voice-anchor.js`) + des entrées dans
+   `_byan/agent/byan/tao.md` (Section 4, Vocabulaire Interdit).
+3. **Le filet vers l'avant (sans blocage).** À la fin de chaque réponse, le
+   programme `.claude/hooks/plain-language-check.js` (Stop) repère les
+   récidivistes connus et écrit un drapeau sous `_byan-output/.jargon-slip.json`.
+   Le rappel du tour SUIVANT lit le drapeau, le signale en clair, et l'efface.
+   Pas de réécriture, pas de régénération : la correction est portée au tour
+   d'après. C'est volontaire — un blocage forcerait une régénération coûteuse et
+   l'utilisateur a déjà lu le dérapage de toute façon (aucun contrôle ne
+   s'exécute avant l'affichage).
+
+Le cœur logique est isolé dans `.claude/hooks/lib/plain-language.js` (liste +
+détection + drapeau), testé par `.claude/__tests__/plain-language.test.js`.
+
+## Coût
+
+Le filet ne coûte quasiment rien : le programme qui relit tourne en local, aucun
+appel au modèle. Le rappel ajoute une poignée de mots par tour, du même ordre
+que le rappel de voix déjà présent. Ce n'est PAS une économie de tokens — c'est
+du confort de compréhension pour l'utilisateur, assumé comme tel.

package/install/templates/.claude/settings.json

@@ -82,6 +82,14 @@
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/punt-guard.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/plain-language-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/agent-gate-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/drain-advisory.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""

package/install/templates/.claude/skills/byan-byan/SKILL.md

@@ -7,6 +7,20 @@ description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Deve
 
 You are BYAN when this skill is active. You own the eight-phase Feature Development workflow and you enforce it mechanically. Every new feature the user asks for goes through all phases in order. No skipping. No implicit transitions. The cycle includes a REFACTOR loop back to BUILD when VALIDATE fails.
 
+## 0. Entry gate — agent dispatch first (match-or-create)
+
+Before doing any non-conversational task, run the mandatory agent entry gate:
+BYAN + Hermes evaluate which specialist agent fits the need (the matcher in
+`_byan/mcp/byan-mcp-server/lib/agent-matcher.js` pre-ranks the roster), and you
+PROPOSE it to the user, who validates (double validation IA + human). A suited
+agent -> launch its workflow (+ runtime dispatch). No suited agent -> propose an
+interview to frame the need, do web research on the trade's competencies + best
+practices, create the tailored agent, then launch the workflow. The interview is
+triggered by the ABSENCE of a suited agent, not by task size — a fit routes
+directly, no ceremony. Do NOT do a task inline without this proposal. Full
+doctrine + the reactive net (`agent-gate-check.js`): see
+@.claude/rules/agent-entry-gate.md
+
 ## 1. Activation triggers
 
 Invoke this protocol when the user :

package/install/templates/.claude/workflows/intelligent-dispatch.js

@@ -0,0 +1,68 @@
+export const meta = {
+  name: 'intelligent-dispatch',
+  description: 'Route a task to Codex or Claude (pre-decided by the F1 router), then run architect -> dev -> verify with the dev turn on the routed runtime.',
+  whenToUse: 'When you have a single task already routed by the dispatch brain (runtime/model/effort in args) and want the native architect<->dev<->verify pipeline. The Codex-inclusive multi-round loop lives in the dispatch-orchestrator lib on the main thread; this script is the native launch facade for one routed task.',
+  phases: [
+    { title: 'Design', detail: 'architect frames the change (Claude)' },
+    { title: 'Implement', detail: 'dev turn on the routed runtime (Codex via codex exec, or Claude)' },
+    { title: 'Verify', detail: 'a Claude reviewer checks the result (never Codex)' },
+  ],
+};
+
+// A native workflow script has NO imports and NO filesystem of its own, so it
+// cannot require the dispatch-router (F1) or the blackboard (F3). The doctrine's
+// hybrid pattern applies: routing is decided OUTSIDE (the main-thread skill calls
+// the F1 router / byan_dispatch) and handed in via `args`. This script only runs
+// the exchange for ONE already-routed task. The dev agent() leaf holds the tools
+// (Bash), so IT is what actually invokes `codex exec` and applies the diff — the
+// script never shells out itself.
+//
+// args shape: { brief, runtime: 'codex'|'claude', effort: 'low'|'medium'|'high',
+//               model?: string, codexModel?: string, paths?: string[] }
+
+const task = (args && typeof args === 'object') ? args : {};
+const brief = task.brief || 'No brief provided.';
+const runtime = task.runtime === 'codex' ? 'codex' : 'claude';
+const effort = ['low', 'medium', 'high'].includes(task.effort) ? task.effort : 'medium';
+const codexModel = task.codexModel || 'gpt-5.4';
+
+phase('Design');
+// The architect framing is the load-bearing reasoning step of the whole loop, so
+// it opts to the session model (the 'deep-' prefix = frontier analysis, no
+// downgrade) rather than the sonnet analysis default. On an Opus session the
+// design is framed by Opus; a lighter session inherits its own model.
+const design = await agent(
+  `You are the architect (Claude). Frame this task for a delegated dev.\n` +
+  `Give: the intended change, the interface/contract to honour, and the acceptance check.\n` +
+  `Keep it tight and unambiguous.\n\nTask:\n${brief}`,
+  { label: 'deep-design-architecture', phase: 'Design' }
+);
+
+phase('Implement');
+// Implementation leaf -> deep (inherit session model). The prompt BRANCHES on the
+// routed runtime: for Codex, the leaf runs `codex exec` read-only to get a diff
+// and applies it (Codex never writes; Claude applies). For Claude, it implements
+// directly. Routing was decided upstream by F1 — this leaf just executes it.
+const devPrompt = runtime === 'codex'
+  ? `You are the dev, delegating to Codex. Run Codex non-interactively to get a unified diff, then apply it.\n` +
+    `Command (adjust the task text): \`codex exec -c model="${codexModel}" -c model_reasoning_effort="${effort}" -c sandbox_permissions=["disk-full-read-access"] "<<diff-only instruction + the task>>"\`\n` +
+    `Extract the diff, apply it with \`git apply\`, and report what changed. Codex must NOT write files itself (read-only sandbox); YOU apply the diff.\n` +
+    `If Codex is unavailable or errors, say so plainly and implement the change yourself on Claude (the fallback).\n\n` +
+    `Design from the architect:\n${design}\n\nTask:\n${brief}`
+  : `You are the dev (Claude). Implement the change per the architect's design.\n` +
+    `Follow the interface exactly. Write the code and the tests.\n\n` +
+    `Design from the architect:\n${design}\n\nTask:\n${brief}`;
+const work = await agent(devPrompt, { label: 'implement-task', phase: 'Implement' });
+
+phase('Verify');
+// Verification leaf -> deep, and ALWAYS Claude (the red line: a runtime never
+// grades its own work). Never routed to Codex regardless of the dev runtime.
+const verdict = await agent(
+  `You are the reviewer (Claude, NOT the dev). Verify the implemented change against the architect's acceptance check.\n` +
+  `Report PASS or FAIL with the exact reasons. Do not fix — only judge.\n\n` +
+  `Design + acceptance:\n${design}\n\nDev report:\n${work}`,
+  { label: 'verify-result', phase: 'Verify' }
+);
+
+log(`intelligent-dispatch done: runtime=${runtime} effort=${effort}`);
+return { runtime, effort, design, work, verdict };

package/install/templates/_byan/agent/byan/byan-tao.md

@@ -155,6 +155,18 @@ Exemple : "Attends. Ca touche au noyau. On est jamais assez parano. Qu'est-ce qu
 **Pourquoi :** Faux enthousiasme. BYAN est sincere ou silencieux.
 **Au lieu de ca :** "Oui." ou "C'est ca."
 
+**Interdit :** l'anglais gratuit quand le francais existe ("cutoff", "fallback", "housekeeping", "wrapper", "throughput", "overhead")
+**Pourquoi :** Mantra IA-26 Parler Reel. Le lecteur doit comprendre sans dictionnaire.
+**Au lieu de ca :** le mot francais ("redemarrer le conteneur", "solution de secours", "menage du code", "surcouche", "debit", "surcout")
+
+**Interdit :** le jargon interne du projet balance brut ("leaf", "tier", "downgrade", "gate", "inline", "advisory")
+**Pourquoi :** Mantra IA-26. C'est le vocabulaire de la cuisine interne, pas celui de l'utilisateur.
+**Au lieu de ca :** dis ce que ca FAIT en clair ("etape", "niveau", "baisser en gamme", "point de controle", "directement", "signalement non bloquant")
+
+**Interdit :** la metaphore collee de travers ("forger un token")
+**Pourquoi :** Mantra IA-26. On forge une ame, pas un token.
+**Au lieu de ca :** le verbe reel ("generer un token", "creer un token")
+
 ---
 
 ### Section 5 — Non-dits

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 [];
+  }
+}