kenaz 0.0.0-stage → 0.3.2

package/core/.formation/bifrost/openai/relay.js

@@ -0,0 +1,781 @@
+#!/usr/bin/env node
+/**
+ * Bifröst — OpenAI Codex Bridge
+ *
+ * Wraps OpenAI Codex CLI to produce Claude Code-compatible stream-json output.
+ * Codex handles the agent loop + tool execution internally (just like Claude Code).
+ * This relay only translates Codex's JSONL events → Formation's stream-json format.
+ *
+ * Usage (standalone test):
+ *   echo "prompt" | node relay.js [--model o4-mini] [--cwd /path]
+ *
+ * Usage (from runner.js — future integration):
+ *   Spawned as child process, same stdin/stdout protocol as claude CLI.
+ *
+ * Env:
+ *   CODEX_MODEL — model override (default: uses codex default)
+ *
+ * Codex JSONL events → Claude stream-json mapping:
+ *   thread.started           → system/init
+ *   item.completed(message)  → assistant/text
+ *   item.started(command)    → assistant/tool_use(Bash)
+ *   item.completed(command)  → (logged, not emitted as separate event)
+ *   turn.completed           → result
+ *   error                    → result(is_error)
+ */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { handleHookEvent } = require(path.resolve(__dirname, '../../..', '.specialist/tools/task-bridge.js'));
+const { createTranscriptTee, runStopConsolidation } = require(path.resolve(__dirname, '..', 'shared', 'consolidate.js'));
+// TASK_2160: discovery-mechanism registry for Bifröst Codex peer push —
+// records the thread_id this project's headless dispatch is using so
+// codex_wake.rs (Rust) can target `codex exec resume` without guessing.
+const { registerHeadless: registerCodexHeadless } = require(path.resolve(__dirname, '..', 'shared', 'codex-session-registry.js'));
+
+// ─────────────────────────────────────────
+// Model spec resolution (TASK_1816)
+//
+// Menu-entry id ≠ CLI model name. models.json entries may declare:
+//   model            — real model name for `-m` (defaults to the entry id)
+//   reasoning_effort — passed via `-c model_reasoning_effort=<value>`
+// Top-level default_reasoning_effort is the explicit project default: every
+// codex spawn passes an effort. Before TASK_1816 nothing did, so every
+// dispatch silently ran at codex's unset default (self-reported as `none`).
+// Measured 2026-07-26 on codex-cli 0.145.0: the session header echoes
+// `reasoning effort: high` with the -c flag, `none` without it.
+//
+// Exported for launch.js (interactive entry point) — the two codex entry
+// points MUST resolve identically (same twin-divergence class as
+// SUBAGENT_PREFIX, rune_704eeb83), so they share this one function.
+// ─────────────────────────────────────────
+
+const FALLBACK_REASONING_EFFORT = 'medium';
+// Guard: effort flows into a `shell: true` spawn on win32 — restrict to a
+// safe token shape. Pattern (not an allowlist) so future values like
+// `xhigh` work without a code change.
+const EFFORT_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+function resolveCodexModelSpec(modelId) {
+  let manifest = null;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(__dirname, 'models.json'), 'utf8'));
+  } catch { /* unreadable manifest — passthrough below */ }
+
+  const rawDefault = manifest && manifest.default_reasoning_effort;
+  const defaultEffort = (typeof rawDefault === 'string' && EFFORT_PATTERN.test(rawDefault))
+    ? rawDefault
+    : FALLBACK_REASONING_EFFORT;
+
+  // null/undefined modelId (no --model flag) matches the id:"" default entry.
+  const entry = (manifest && Array.isArray(manifest.models))
+    ? manifest.models.find((m) => m && m.id === (modelId ?? '')) || null
+    : null;
+
+  // Entry found: entry.model (fallback entry.id) is the -m value; '' → null (no -m).
+  // No entry (env override / standalone test with arbitrary id): pass through.
+  const model = entry ? (entry.model || entry.id || null) : (modelId || null);
+
+  let effort = (entry && entry.reasoning_effort != null) ? String(entry.reasoning_effort) : defaultEffort;
+  if (!EFFORT_PATTERN.test(effort)) {
+    process.stderr.write(`[relay] invalid reasoning_effort ${JSON.stringify(effort)} in models.json — using ${defaultEffort}\n`);
+    effort = defaultEffort;
+  }
+  return { entryId: modelId ?? null, model, reasoning_effort: effort, matched: Boolean(entry) };
+}
+
+// ─────────────────────────────────────────
+// Config
+// ─────────────────────────────────────────
+
+const args = parseArgs(process.argv.slice(2));
+const MODEL = args.model || process.env.CODEX_MODEL || null;
+const CWD = args.cwd || process.cwd();
+const CONSOLIDATE_ROOT = path.resolve(process.env.KENAZ_CONSOLIDATE_ROOT || CWD);
+const SANDBOX = args.sandbox || 'danger-full-access';
+const RESUME_ID = args.resume || null;  // thread_id for multi-turn
+const MCP_CONFIG_EXTRA = args.mcpConfigExtra || []; // TASK_1929 (Agent Hub M2)
+
+// TASK_1816: resolve menu-entry id → { real CLI model, reasoning effort }.
+const MODEL_SPEC = resolveCodexModelSpec(MODEL);
+const CLI_MODEL = MODEL_SPEC.model;
+const REASONING_EFFORT = MODEL_SPEC.reasoning_effort;
+
+// ─────────────────────────────────────────
+// Thread State (captured from thread.started for PreToolUse/PostToolUse session_id)
+// ─────────────────────────────────────────
+
+// Module-level variable; set in translateEvent() thread.started branch.
+// Forwarded as session_id in PreToolUse/PostToolUse payloads (TASK_1229).
+let capturedThreadId = null;
+
+// TASK_1735: transcript tee opened at relay start; written per JSONL line; closed+consolidated at stop.
+let transcriptTee = null;
+
+// TASK_1786: result-event fidelity (DEFECT-B). Count observed turn/tool events so
+// turn.completed can report a real num_turns instead of a hardcoded 1, and capture
+// the run start timestamp (thread.started / turn.started) to derive duration_ms.
+const RELAY_START_MS = Date.now();     // fallback anchor if no start event observed
+let countedTurnEvents = 0;             // agent_message + tool item.completed events
+let runStartedAtMs = null;             // first thread.started / turn.started timestamp
+
+// ─────────────────────────────────────────
+// Stream-JSON Emitter (inline — no external dep needed)
+// ─────────────────────────────────────────
+
+function emit(obj) {
+  try {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+  } catch { /* EPIPE — non-fatal */ }
+}
+
+function emitToolResult(tool_use_id, content, is_error = false) {
+  emit({
+    type: 'user',
+    message: {
+      role: 'user',
+      content: [{
+        type: 'tool_result',
+        tool_use_id,
+        content: typeof content === 'string' ? content : JSON.stringify(content),
+        is_error: Boolean(is_error)
+      }]
+    }
+  });
+}
+
+// ─────────────────────────────────────────
+// Hook Dispatch — relay.js (TASK_1229)
+//
+// Supported tool classes (by exact name emitted in PreToolUse/PostToolUse):
+//   'Bash'             — command_execution items
+//   'Edit'             — file_edit items + file_change changes[] fan-out (TASK_1793)
+//   'Read'             — file_read items
+//   'mcp__<s>__<t>'    — mcp_tool_call items (e.g. mcp__kenaz-dashboard__synapse_recall)
+//
+// Ordering per tool call:
+//   PreToolUse  → after tool_id assignment, before emit(tool_use)
+//   PostToolUse → after emitToolResult() (or after emit(tool_use) when no result)
+//
+// Dispatch: require() + handleHookEvent() (in-process, no subprocess overhead).
+// Canonical payload schema: BIFROST_HOOK_LIFECYCLE in task-bridge.js
+// ─────────────────────────────────────────
+
+function resolveProjectPath(cwd) {
+  return path.resolve(cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+}
+
+/**
+ * dispatchBifrostHook — relay.js (CGDD phantom: relay_dispatchBifrostHook)
+ * Calls handleHookEvent() from task-bridge. Hook failures are caught and
+ * logged to stderr — they must never interrupt the emit() sequence.
+ */
+function dispatchBifrostHook(eventName, payload) {
+  // AC2 (TASK_1733): suppress Pre/PostToolUse relay emulation when native hooks active.
+  // codex-hook-shim.js fires these directly via the native hook pipeline.
+  if ((eventName === "PreToolUse" || eventName === "PostToolUse") && process.env.CODEX_NATIVE_HOOKS_ACTIVE) {
+    console.error("[relay] " + eventName + " suppressed (CODEX_NATIVE_HOOKS_ACTIVE)");
+    return;
+  }
+  try {
+    handleHookEvent(payload).catch(err => {
+      console.error("[relay] " + eventName + " hook async error: " + err.message);
+    });
+  } catch (err) {
+    console.error("[relay] " + eventName + " hook error: " + err.message);
+  }
+}
+
+/**
+ * normalizeToolEvent — relay.js (CGDD phantom: relay_normalizeToolEvent)
+ *
+ * Shapes canonical PreToolUse or PostToolUse payload from a Codex item
+ * and the relay-assigned tool id.
+ *
+ * Supported tool classes by exact name:
+ *   'Bash'           (command_execution)
+ *   'Edit'           (file_edit | file_change — TASK_1793)
+ *   'Read'           (file_read)
+ *   'mcp__*__*'      (mcp_tool_call — e.g. mcp__kenaz-dashboard__synapse_recall)
+ */
+function normalizeToolEvent(eventName, toolName, toolId, toolInput, toolResponse) {
+  const payload = {
+    hook_event_name: eventName,
+    tool_name:       toolName,
+    tool_id:         toolId,
+    tool_input:      toolInput || {},
+    session_id:      capturedThreadId,
+    specialist:      null,           // relay subprocess does not receive --specialist
+    cwd:             CWD,
+    project_path:    resolveProjectPath(CWD),
+    timestamp:       new Date().toISOString(),
+  };
+  if (eventName === 'PostToolUse') {
+    payload.tool_response = toolResponse || {};
+    payload.is_error = Boolean(
+      (toolResponse && toolResponse.exit_code !== undefined && toolResponse.exit_code !== 0) ||
+      (toolResponse && toolResponse.error)
+    );
+  }
+  return payload;
+}
+
+// ─────────────────────────────────────────
+// Codex JSONL → Claude stream-json translator
+// ─────────────────────────────────────────
+
+function translateEvent(event) {
+  switch (event.type) {
+
+    case 'thread.started':
+      capturedThreadId = event.thread_id || null;  // TASK_1229: forward as session_id in Pre/PostToolUse
+      // TASK_2160: register the (possibly NEW, e.g. first dispatch) thread_id
+      // so a later peer-push wake knows what to resume into. No-op if
+      // event.thread_id is absent (never throws — see registerHeadless doc).
+      if (event.thread_id) registerCodexHeadless(resolveProjectPath(CWD), event.thread_id, process.pid);
+      if (runStartedAtMs === null) runStartedAtMs = Date.now();  // TASK_1786: duration anchor
+      emit({
+        type: 'system',
+        subtype: 'init',
+        model: CLI_MODEL || 'codex-default',
+        // TASK_1816: effort must be observable downstream — runner.js
+        // collectOutput surfaces this field into the dispatch log.
+        reasoning_effort: REASONING_EFFORT,
+        model_entry: MODEL_SPEC.entryId,
+        cwd: CWD,
+        thread_id: event.thread_id || null  // For multi-turn resume
+      });
+      // Also emit thread_id to stderr so callers can capture it
+      if (event.thread_id) {
+        process.stderr.write(`[relay] thread_id=${event.thread_id}\n`);
+      }
+      break;
+
+    case 'item.completed':
+      if (!event.item) break;
+
+      // TASK_1786: count message/tool events toward num_turns (≈ Claude's
+      // per-round-trip turn semantics: each assistant message or tool call).
+      // 'file_change' included: codex-cli 0.144.1 emits file_change (verified in
+      // TASK_1779-batch transcripts). Since TASK_1793 the translation section
+      // below handles BOTH names (file_edit legacy, file_change fan-out) —
+      // keep counting both here; this counter counts ITEMS, not fanned-out
+      // tool_use blocks, so a 2-file file_change item still counts once.
+      if (['agent_message', 'command_execution', 'file_edit', 'file_change', 'file_read', 'mcp_tool_call'].includes(event.item.type)) {
+        countedTurnEvents++;
+      }
+
+      if (event.item.type === 'agent_message' && event.item.text) {
+        emit({
+          type: 'assistant',
+          message: {
+            content: [{ type: 'text', text: event.item.text }]
+          }
+        });
+      }
+
+      if (event.item.type === 'command_execution') {
+        // Emit as tool_use (Bash) for Formation logger compatibility
+        const cmdId = event.item.id || 'cmd_' + Date.now();
+        const cmdInput = { command: event.item.command || '' };
+        // PreToolUse fires before emit(tool_use) — execution boundary (TASK_1229)
+        dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Bash', cmdId, cmdInput, null));
+        emit({
+          type: 'assistant',
+          message: {
+            content: [{
+              type: 'tool_use',
+              id: cmdId,
+              name: 'Bash',
+              input: cmdInput
+            }]
+          }
+        });
+        // Emit tool_result if output is present
+        const cmdOutput = event.item.output ?? event.item.stdout ?? null;
+        const cmdResponse = { output: cmdOutput, exit_code: event.item.exit_code };
+        if (cmdOutput !== null || event.item.exit_code !== undefined) {
+          const isError = event.item.exit_code !== undefined && event.item.exit_code !== 0;
+          emitToolResult(cmdId, cmdOutput !== null ? String(cmdOutput) : '', isError);
+        }
+        // PostToolUse fires after emitToolResult (TASK_1229)
+        dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Bash', cmdId, cmdInput, cmdResponse));
+      }
+
+      if (event.item.type === 'file_edit') {
+        const editId = event.item.id || 'edit_' + Date.now();
+        const editInput = { file_path: event.item.file_path || '', description: event.item.description || 'file edit' };
+        // PreToolUse fires before emit(tool_use) — execution boundary (TASK_1229)
+        dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Edit', editId, editInput, null));
+        emit({
+          type: 'assistant',
+          message: {
+            content: [{
+              type: 'tool_use',
+              id: editId,
+              name: 'Edit',
+              input: editInput
+            }]
+          }
+        });
+        // Emit tool_result if result is present
+        const editResult = event.item.result ?? event.item.output ?? null;
+        const editResponse = { result: editResult, error: event.item.error };
+        if (editResult !== null) {
+          emitToolResult(editId, typeof editResult === 'string' ? editResult : JSON.stringify(editResult), Boolean(event.item.error));
+        }
+        // PostToolUse fires after emitToolResult (TASK_1229)
+        dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Edit', editId, editInput, editResponse));
+      }
+
+      // TASK_1793: codex-cli ≥0.144.1 emits 'file_change' (changes[] fan-out)
+      // instead of the legacy single-file 'file_edit' above. ONE item carries
+      // N files — emit one Edit tool_use per changes[] entry so hooks see
+      // every file (an event listing only changes[0] silently drops the rest).
+      // Deliberate decisions:
+      //   - id: `${item.id}#${index}` — N tool_use blocks sharing the raw item
+      //     id would collide in hook/tool_use pairing. Codex ids ('item_5')
+      //     never contain '#', so derived ids cannot collide across items and
+      //     are stable across replays (no Date.now() component when id exists).
+      //   - path: passed through verbatim (absolute OS-native path, backslashes
+      //     on win32) — identical to how the file_edit branch forwards
+      //     file_path, and consistent with native Claude Code hook payloads,
+      //     which also carry absolute paths.
+      //   - kind (add|update|delete): forwarded in input, never discarded.
+      //     Tool name stays 'Edit' even for delete — a delete is still a
+      //     write-class mutation the scope/worktree guards must see (skipping
+      //     it would recreate this task's invisibility bug for deletes, and a
+      //     novel tool name would match no downstream consumer). Consumers
+      //     that act on content can branch on input.kind.
+      // Double-fire guard: item.started carries the IDENTICAL changes[] array;
+      // this branch lives inside the `case 'item.completed'` gate only (the
+      // 'item.started' case below is a no-op), so the fan-out fires exactly
+      // once per item.
+      if (event.item.type === 'file_change') {
+        const baseId = event.item.id || 'edit_' + Date.now();
+        const changes = Array.isArray(event.item.changes) ? event.item.changes : [];
+        changes.forEach((change, index) => {
+          if (!change || typeof change.path !== 'string') return;
+          const changeId = `${baseId}#${index}`;
+          const kind = change.kind || 'update';
+          const changeInput = { file_path: change.path, kind, description: `file ${kind} (codex file_change)` };
+          // PreToolUse fires before emit(tool_use) — execution boundary (TASK_1229)
+          dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Edit', changeId, changeInput, null));
+          emit({
+            type: 'assistant',
+            message: {
+              content: [{
+                type: 'tool_use',
+                id: changeId,
+                name: 'Edit',
+                input: changeInput
+              }]
+            }
+          });
+          // file_change carries per-item status only (no per-file result
+          // payload) — nothing to emitToolResult. Surface non-completed
+          // status as an error so PostToolUse is_error reflects reality.
+          const changeResponse = {
+            result: event.item.status || 'completed',
+            error: (event.item.status && event.item.status !== 'completed')
+              ? `file_change status=${event.item.status}`
+              : undefined
+          };
+          // PostToolUse fires after emit(tool_use) (TASK_1229)
+          dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Edit', changeId, changeInput, changeResponse));
+        });
+      }
+
+      if (event.item.type === 'file_read') {
+        const readId = event.item.id || 'read_' + Date.now();
+        const readInput = { file_path: event.item.file_path || '' };
+        // PreToolUse fires before emit(tool_use) — execution boundary (TASK_1229)
+        dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Read', readId, readInput, null));
+        emit({
+          type: 'assistant',
+          message: {
+            content: [{
+              type: 'tool_use',
+              id: readId,
+              name: 'Read',
+              input: readInput
+            }]
+          }
+        });
+        // Emit tool_result if content is present
+        const readContent = event.item.content ?? event.item.result ?? event.item.output ?? null;
+        const readResponse = { content: readContent, error: event.item.error };
+        if (readContent !== null) {
+          emitToolResult(readId, typeof readContent === 'string' ? readContent : JSON.stringify(readContent), Boolean(event.item.error));
+        }
+        // PostToolUse fires after emitToolResult (TASK_1229)
+        dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Read', readId, readInput, readResponse));
+      }
+
+      if (event.item.type === 'mcp_tool_call') {
+        // MCP tool calls (Synapse, Hippocampus, Thalamus, etc.)
+        // Map to Claude's mcp__<server>__<tool> naming convention.
+        // TASK_1780 verified: this is server-agnostic pass-through — tools of
+        // project-declared servers registered by ensureProjectMcpServers()
+        // (e.g. mcp__unity-mcp__compile) flow through unchanged.
+        const mcpId = event.item.id || 'mcp_' + Date.now();
+        const mcpName = event.item.server && event.item.tool
+          ? `mcp__${event.item.server}__${event.item.tool}`
+          : event.item.tool || 'unknown_mcp';
+        const mcpInput = event.item.arguments || {};
+        // PreToolUse fires before emit(tool_use) — execution boundary (TASK_1229)
+        dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', mcpName, mcpId, mcpInput, null));
+        emit({
+          type: 'assistant',
+          message: {
+            content: [{
+              type: 'tool_use',
+              id: mcpId,
+              name: mcpName,
+              input: mcpInput
+            }]
+          }
+        });
+        // Emit tool_result so info_gain can read pulse/recall/search results
+        const mcpResult = event.item.result ?? event.item.output ?? null;
+        const mcpResponse = { result: mcpResult, error: event.item.error };
+        if (mcpResult !== null || event.item.error) {
+          const content = mcpResult !== null
+            ? (typeof mcpResult === 'string' ? mcpResult : JSON.stringify(mcpResult))
+            : String(event.item.error);
+          emitToolResult(mcpId, content, Boolean(event.item.error));
+        }
+        // PostToolUse fires after emitToolResult (TASK_1229)
+        dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', mcpName, mcpId, mcpInput, mcpResponse));
+      }
+      break;
+
+    case 'item.started':
+      // Codex emits in-progress items — skip (we emit on completed)
+      break;
+
+    case 'turn.started':
+      if (runStartedAtMs === null) runStartedAtMs = Date.now();  // TASK_1786: duration anchor
+      break;
+
+    case 'turn.completed':
+      // Map usage to cost estimate
+      const usage = event.usage || {};
+      const costUsd = estimateCost(usage, CLI_MODEL);
+      emit({
+        type: 'result',
+        subtype: 'success',
+        total_cost_usd: costUsd,
+        // TASK_1786: real observed event count. CRITICAL: floor to 1 — runner.js
+        // treats zero-turn + zero-cost as FAILED (TASK_1774 defect-2), so the
+        // success path must never emit num_turns=0.
+        num_turns: Math.max(countedTurnEvents, 1),
+        duration_ms: Math.max(Date.now() - (runStartedAtMs ?? RELAY_START_MS), 1),
+        input_tokens: usage.input_tokens || 0,
+        output_tokens: usage.output_tokens || 0,
+        is_error: false
+      });
+      break;
+
+    case 'turn.failed':
+    case 'error':
+      emit({
+        type: 'result',
+        total_cost_usd: 0,
+        num_turns: 0,
+        is_error: true,
+        error: event.message || event.error?.message || 'Unknown error'
+      });
+      break;
+
+    // thread.completed — structural event, no Claude equivalent
+    default:
+      break;
+  }
+}
+
+// ─────────────────────────────────────────
+// Spawn Codex CLI
+// ─────────────────────────────────────────
+
+async function main() {
+  // Read prompt from stdin
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const prompt = Buffer.concat(chunks).toString('utf8').trim();
+
+  if (!prompt) {
+    emit({ type: 'result', is_error: true, error: 'No prompt received on stdin' });
+    process.exit(1);
+  }
+
+  // Build codex args — resume mode vs fresh exec
+  let codexArgs;
+  if (RESUME_ID) {
+    // Multi-turn: resume existing session
+    codexArgs = ['exec', 'resume', '--json', RESUME_ID, '-'];
+    // TASK_2160: register eagerly here too — don't rely on `codex exec
+    // resume` re-emitting thread.started (unverified either way), so the
+    // registry stays correct even if it doesn't.
+    registerCodexHeadless(resolveProjectPath(CWD), RESUME_ID, process.pid);
+    process.stderr.write(`[relay] Codex RESUME | Thread: ${RESUME_ID} | Effort: ${REASONING_EFFORT} | Prompt: ${prompt.length} chars\n`);
+  } else {
+    // Fresh session
+    codexArgs = ['exec', '--json', '-s', SANDBOX, '-'];
+    process.stderr.write(`[relay] Codex CLI | Model: ${CLI_MODEL || 'default'} | Effort: ${REASONING_EFFORT} | CWD: ${CWD} | Prompt: ${prompt.length} chars\n`);
+  }
+  // TASK_1816: -m carries the REAL model name (menu-entry ids like
+  // gpt-5.6-sol-high are resolved to gpt-5.6-sol by resolveCodexModelSpec).
+  if (CLI_MODEL) codexArgs.push('-m', CLI_MODEL);
+  // TASK_1816: ALWAYS pass an explicit reasoning effort — never inherit
+  // codex's unset default. Bare TOML value (no inner quotes): codex accepts
+  // it, and quoting would break under win32 `shell: true` cmd escaping.
+  codexArgs.push('-c', `model_reasoning_effort=${REASONING_EFFORT}`);
+  if (MODEL_SPEC.entryId && MODEL_SPEC.entryId !== CLI_MODEL) {
+    process.stderr.write(`[relay] model entry "${MODEL_SPEC.entryId}" resolved → -m ${CLI_MODEL || '(none)'}\n`);
+  }
+  // Full argv on stderr: the effective effort must be visible in dispatch
+  // output — the TASK_1816 root cause was that it never was.
+  process.stderr.write(`[relay] codex argv: codex ${codexArgs.join(' ')}\n`);
+
+  // TASK_1530: write-confinement for the Codex subprocess.
+  //   1. cwd: CWD — CWD is the worktree path passed via --cwd by runner.js's
+  //      spawnBifrost. Codex resolves its own file writes relative to this cwd,
+  //      so anchoring cwd to the worktree is the primary confinement.
+  //   2. CLAUDE_PROJECT_DIR: CWD — re-anchor the env var to the SAME worktree.
+  //      spawnBifrost now sets it (TASK_1530 part a), but we pin it to CWD here
+  //      too so the value can never drift from the cwd Codex actually runs in.
+  //      This is belt-and-braces: any tool in the Codex toolchain that consults
+  //      CLAUDE_PROJECT_DIR (instead of cwd) still resolves inside the worktree.
+  //
+  // CAVEAT (degrade-to-safe): the upstream `codex` CLI is third-party. It honors
+  // its spawn cwd for file operations, but it does not document any contract that
+  // it reads CLAUDE_PROJECT_DIR for its OWN writes. cwd anchoring is therefore the
+  // load-bearing guarantee; CLAUDE_PROJECT_DIR is defense-in-depth. If a future
+  // Codex version writes via an absolute path it computes itself, the runner-side
+  // worktree-leak detector (detectWorktreeLeak) is the final safety net: it
+  // salvages + blocks any dispatch whose writes still land in the main repo.
+  // TASK_1733: single choke point for the native-hooks dedupe flag. When the codex CLI
+  // supports hooks AND our shim is registered, set CODEX_NATIVE_HOOKS_ACTIVE so this
+  // relay's own dispatchBifrostHook guard suppresses Pre/PostToolUse emulation (AC2).
+  // Skipped when a parent (bifrost/session.js) already decided. Probe failure = flag unset
+  // = relay emulation stays on (graceful fallback, AC3).
+  if (!process.env.CODEX_NATIVE_HOOKS_ACTIVE) {
+    try {
+      const { nativeHooksActive } = require(path.resolve(__dirname, '..', 'setup-codex.js'));
+      if (nativeHooksActive(CWD)) {
+        process.env.CODEX_NATIVE_HOOKS_ACTIVE = '1';
+        console.error('[relay] native codex hooks active — relay Pre/PostToolUse emulation suppressed');
+      }
+    } catch { /* probe failure = keep emulation */ }
+  }
+
+  // TASK_1780: dispatch-time registration of project-declared MCP servers
+  // (.kenaz/project.yaml mcp_servers). Runs BEFORE the codex spawn so the
+  // servers are in $CODEX_HOME/config.toml when codex boots. Fail-open:
+  // any registration/probe problem warns to stderr and the dispatch proceeds.
+  try {
+    const { ensureProjectMcpServers, probeProjectMcpServers } =
+      require(path.resolve(__dirname, '..', 'setup-codex.js'));
+    const projectDir = resolveProjectPath(CWD);
+    const mcpSummary = ensureProjectMcpServers(projectDir, { silent: true });
+    if (mcpSummary.registered.length || mcpSummary.refreshed.length || mcpSummary.pruned.length) {
+      process.stderr.write(`[relay] project MCP ensure: +${mcpSummary.registered.join(',') || '0'} ~${mcpSummary.refreshed.join(',') || '0'} -${mcpSummary.pruned.join(',') || '0'}\n`);
+    }
+    for (const w of mcpSummary.warnings || []) process.stderr.write(`[relay] project MCP warning: ${w}\n`);
+    await probeProjectMcpServers(projectDir); // warn-only (writes [bifrost:probe] lines)
+  } catch (err) {
+    process.stderr.write(`[relay] project MCP registration skipped: ${err.message}\n`);
+  }
+
+  // TASK_1929 (Agent Hub M2): translate any --mcp-config-extra file(s) into
+  // ephemeral `-c mcp_servers.*` overrides + a bearer-token env var. No-op
+  // (empty array) for every dispatch path except agent_hub/launch.rs.
+  const { codexArgsExtra, env: mcpEnv } = buildCodexMcpOverrides(MCP_CONFIG_EXTRA);
+  if (codexArgsExtra.length > 0) {
+    codexArgs.push(...codexArgsExtra);
+    process.stderr.write(`[relay] Agent Hub MCP overrides: ${codexArgsExtra.join(' ')}\n`);
+  }
+
+  const codexEnv = { ...process.env, ...mcpEnv, CLAUDE_PROJECT_DIR: CWD };
+  codexEnv.KENAZ_PEER_PULL = '0'; // '0' (not delete): beats the hook's --pull flag. TASK_2299: headless workers must never pull (and ack) the peer inbox
+
+  const codex = spawn('codex', codexArgs, {
+    cwd: CWD,
+    env: codexEnv,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+    shell: process.platform === 'win32'
+  });
+
+  // Pipe prompt to codex stdin
+  codex.stdin.write(prompt);
+  codex.stdin.end();
+
+  // TASK_1735: open transcript tee before parsing output (eager open = crash-safe streaming write)
+  transcriptTee = createTranscriptTee(CONSOLIDATE_ROOT, RESUME_ID || null);
+
+  // Parse codex JSONL output and translate
+  let buffer = '';
+  codex.stdout.on('data', (data) => {
+    buffer += data.toString();
+    const lines = buffer.split('\n');
+    buffer = lines.pop(); // keep incomplete line
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
+        if (transcriptTee) transcriptTee.write(line);
+        translateEvent(event);
+      } catch {
+        // Non-JSON line — log to stderr
+        process.stderr.write(`[relay] non-json: ${line.slice(0, 100)}\n`);
+      }
+    }
+  });
+
+  // Forward stderr
+  codex.stderr.on('data', (data) => {
+    process.stderr.write(data);
+  });
+
+  codex.on('close', async (code) => {
+    // Process remaining buffer
+    if (buffer.trim()) {
+      try {
+        const ev = JSON.parse(buffer);
+        if (transcriptTee) transcriptTee.write(buffer);
+        translateEvent(ev);
+      } catch {}
+    }
+    process.stderr.write(`[relay] Codex exited with code ${code}\n`);
+    // TASK_1735: stop consolidation (tee+episode+handoff+heartbeat); fail-open
+    await runStopConsolidation({
+      projectRoot: CONSOLIDATE_ROOT,
+      sessionId:   capturedThreadId || RESUME_ID || null,
+      tee:         transcriptTee,
+      port:        process.env.KENAZ_HTTP_PORT || '18080',
+    }).catch(() => {});
+    process.exit(code || 0);
+  });
+
+  codex.on('error', (err) => {
+    emit({ type: 'result', is_error: true, error: `Failed to spawn codex: ${err.message}` });
+    process.exit(1);
+  });
+}
+
+// ─────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────
+
+function parseArgs(argv) {
+  const result = { mcpConfigExtra: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if ((argv[i] === '--model' || argv[i] === '-m') && argv[i + 1]) {
+      result.model = argv[++i];
+    } else if (argv[i] === '--cwd' && argv[i + 1]) {
+      result.cwd = argv[++i];
+    } else if ((argv[i] === '--sandbox' || argv[i] === '-s') && argv[i + 1]) {
+      result.sandbox = argv[++i];
+    } else if (argv[i] === '--resume' && argv[i + 1]) {
+      result.resume = argv[++i];
+    } else if (argv[i] === '--mcp-config-extra' && argv[i + 1]) {
+      // TASK_1929 (Agent Hub M2): repeatable — see buildCodexMcpOverrides.
+      result.mcpConfigExtra.push(argv[++i]);
+    }
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────
+// Agent Hub MCP overrides (TASK_1929, M2)
+//
+// Reads the SAME canonical MCP config JSON agent_hub/launch.rs writes for
+// Claude's native --mcp-config ({"mcpServers":{"<name>":{"type":"http",
+// "url":"...","headers":{"Authorization":"Bearer <cred>"}}}}) and
+// translates it into codex's ephemeral `-c mcp_servers.<name>.*` config
+// overrides. "Ephemeral" is the whole point: `-c` overrides apply only to
+// this one codex invocation and never touch ~/.codex/config.toml (verified
+// via `codex mcp add --help` + a scratch CODEX_HOME probe — the TOML key
+// path IS `mcp_servers.<name>.url` / `mcp_servers.<name>.bearer_token_env_var`,
+// confirmed against a real `codex mcp add ... --bearer-token-env-var ...`
+// run). The bearer token itself goes through an env var this function sets
+// on the CHILD's env, never through -c or the command line (command lines
+// are visible to other users on the same machine — requirement's own
+// wording).
+//
+// Server names are restricted to a safe charset (mirrors EFFORT_PATTERN's
+// rationale above: these values flow into a `shell: true` win32 spawn) and
+// URLs are rejected outright if they contain a single quote (the `-c`
+// values below are single-quoted TOML literals, which have no escape
+// mechanism) rather than attempting to escape them.
+const MCP_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+function buildCodexMcpOverrides(mcpConfigExtraPaths) {
+  const codexArgsExtra = [];
+  const env = {};
+  for (const configPath of mcpConfigExtraPaths) {
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (e) {
+      process.stderr.write(`[relay] Agent Hub MCP config unreadable, skipping: ${configPath}: ${e.message}\n`);
+      continue;
+    }
+    const servers = parsed && parsed.mcpServers ? parsed.mcpServers : {};
+    for (const [name, server] of Object.entries(servers)) {
+      const url = server && server.url;
+      const auth = server && server.headers && server.headers.Authorization;
+      if (!MCP_NAME_PATTERN.test(name)) {
+        process.stderr.write(`[relay] Agent Hub MCP server name rejected (unsafe charset): ${JSON.stringify(name)}\n`);
+        continue;
+      }
+      if (typeof url !== 'string' || url.includes("'") || url.includes('\n') || url.includes('\r')) {
+        process.stderr.write(`[relay] Agent Hub MCP url rejected for ${name} (missing, or unsafe for a TOML literal)\n`);
+        continue;
+      }
+      codexArgsExtra.push('-c', `mcp_servers.${name}.url='${url}'`);
+      const bearer = typeof auth === 'string' ? auth.replace(/^Bearer\s+/i, '') : null;
+      if (bearer) {
+        const envVar = `KENAZ_HUB_MCP_TOKEN_${name.replace(/-/g, '_').toUpperCase()}`;
+        env[envVar] = bearer;
+        codexArgsExtra.push('-c', `mcp_servers.${name}.bearer_token_env_var='${envVar}'`);
+      }
+    }
+  }
+  return { codexArgsExtra, env };
+}
+
+function estimateCost(usage, model) {
+  if (!usage) return 0;
+  const prices = {
+    'gpt-4o':       { input: 2.50, output: 10.00 },
+    'gpt-4o-mini':  { input: 0.15, output: 0.60 },
+    'gpt-4.1':      { input: 2.00, output: 8.00 },
+    'gpt-4.1-mini': { input: 0.40, output: 1.60 },
+    'gpt-4.1-nano': { input: 0.10, output: 0.40 },
+    'o3':           { input: 2.00, output: 8.00 },
+    'o4-mini':      { input: 1.10, output: 4.40 },
+  };
+  const p = prices[model] || prices['gpt-4o'];
+  const inputCost = (usage.input_tokens || 0) / 1_000_000 * p.input;
+  const outputCost = (usage.output_tokens || 0) / 1_000_000 * p.output;
+  return inputCost + outputCost;
+}
+
+// TASK_1816: require.main guard — launch.js requires this module for
+// resolveCodexModelSpec (shared model+effort resolution across both codex
+// entry points). main() reads stdin and must only run when spawned directly.
+if (require.main === module) {
+  main();
+}
+
+// translateEvent exported for replay-based verification (TASK_1793) — main()
+// stays behind the require.main guard above, so requiring this module never
+// reads stdin or spawns codex.
+module.exports = { resolveCodexModelSpec, translateEvent, buildCodexMcpOverrides };