kenaz 0.0.0-stage → 0.3.2

package/core/.formation/bifrost/setup-codex.js

@@ -0,0 +1,685 @@
+#!/usr/bin/env node
+/**
+ * setup-codex.js — Auto-register kenaz-dashboard MCP with Codex CLI
+ *
+ * Idempotent: safe to call multiple times. Does nothing if:
+ *   - codex CLI is not installed
+ *   - MCP is already registered
+ *
+ * Called from:
+ *   - sync.js (after AGENTS.md generation)
+ *   - launch.js (before interactive session)
+ *   - install.js (during hook setup)
+ *   - Manual: node .formation/bifrost/setup-codex.js
+ *
+ * What it does:
+ *   1. Checks if codex CLI is available
+ *   2. Reads $CODEX_HOME/config.toml (default ~/.codex) for existing kenaz-dashboard entry
+ *   3. If missing, runs `codex mcp add kenaz-dashboard --transport http --url <url>`
+ *   4. Reports result to stderr (non-blocking)
+ *
+ * TASK_1780 (Bifrost B2): additionally exposes ensureProjectMcpServers() /
+ * probeProjectMcpServers() so codex dispatches register the MCP servers a
+ * sub-project declares in its .kenaz/project.yaml (e.g. Ashfall Unity MCP,
+ * port 7891). See "Project-declared MCP servers" section below for the
+ * schema and the retention policy.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const KENAZ_HTTP_PORT = process.env.KENAZ_HTTP_PORT || '18080';
+const MCP_URL = `http://localhost:${KENAZ_HTTP_PORT}/api/mcp`;
+const MCP_NAME = 'kenaz-dashboard';
+
+// $CODEX_HOME is honored by the codex CLI itself (config dir override).
+// Honoring it here keeps our config reads/writes pointed at the SAME file
+// the CLI mutates, and lets tests isolate against a scratch CODEX_HOME.
+function getCodexHome() {
+  if (process.env.CODEX_HOME) return path.resolve(process.env.CODEX_HOME);
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  return path.join(home, '.codex');
+}
+
+function getCodexConfigPath() {
+  return path.join(getCodexHome(), 'config.toml');
+}
+
+let _codexInstalledCache = null; // process-lifetime cache — probe is ~1s on Windows
+function isCodexInstalled() {
+  if (_codexInstalledCache !== null) return _codexInstalledCache;
+  try {
+    execSync('codex --version', { stdio: 'pipe', timeout: 5000, windowsHide: true });
+    _codexInstalledCache = true;
+  } catch {
+    _codexInstalledCache = false;
+  }
+  return _codexInstalledCache;
+}
+
+function isMcpAlreadyRegistered() {
+  const configPath = getCodexConfigPath();
+  if (!fs.existsSync(configPath)) return false;
+  const content = fs.readFileSync(configPath, 'utf8');
+  const match = content.match(/\[mcp_servers\.kenaz-dashboard\][^\[]*url\s*=\s*"([^"]+)"/);
+  if (!match) return false;
+  return match[1] === MCP_URL;
+}
+
+function getRegisteredMcpUrl() {
+  const configPath = getCodexConfigPath();
+  if (!fs.existsSync(configPath)) return null;
+  const content = fs.readFileSync(configPath, 'utf8');
+  const match = content.match(/\[mcp_servers\.kenaz-dashboard\][^\[]*url\s*=\s*"([^"]+)"/);
+  return match ? match[1] : null;
+}
+
+// TASK_2384: `codex mcp remove` deletes the whole [mcp_servers.kenaz-dashboard] section, including the user's
+// own [mcp_servers.kenaz-dashboard.tools.<tool>] approval_mode entries. We carry those tables across a remove/add
+// cycle: setup's stale-URL refresh keeps them in memory, uninstall parks them in a sidecar that the next setup
+// restores (not left in config.toml: a server table without url/command can make codex reject the whole file).
+const TOOLS_SIDECAR = 'kenaz-dashboard-tools.toml';
+const TOOLS_HEADER = /^\s*\[mcp_servers\.(?:kenaz-dashboard|"kenaz-dashboard")\.tools\./;
+function extractToolTables(text) {
+  const out = []; let cur = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*\[/.test(line)) { cur = TOOLS_HEADER.test(line) ? [line] : null; if (cur) out.push(cur); }
+    else if (cur) cur.push(line);
+  }
+  return out.map((t) => t.join('\n').replace(/\s+$/, '')).join('\n\n');
+}
+function readToolTables() {
+  const cfg = getCodexConfigPath();
+  return fs.existsSync(cfg) ? extractToolTables(fs.readFileSync(cfg, 'utf8')) : '';
+}
+/** Append the saved tables that the config does not already have (by header). */
+function restoreToolTables(tables) {
+  if (!tables) return 0;
+  const cfg = getCodexConfigPath();
+  const cur = fs.existsSync(cfg) ? fs.readFileSync(cfg, 'utf8') : '';
+  const have = new Set(cur.split(/\r?\n/).map((l) => l.trim()));
+  const add = tables.split(/\n\n(?=\s*\[)/).filter((t) => !have.has(t.split('\n')[0].trim()));
+  if (add.length) fs.writeFileSync(cfg, cur.replace(/\s*$/, '\n') + '\n' + add.join('\n\n') + '\n', 'utf8');
+  return add.length;
+}
+function restoreSidecar() {
+  const f = path.join(getCodexHome(), TOOLS_SIDECAR);
+  if (!fs.existsSync(f)) return 0;
+  const n = restoreToolTables(fs.readFileSync(f, 'utf8'));
+  fs.rmSync(f, { force: true });
+  return n;
+}
+
+function registerMcp() {
+  try {
+    execSync(
+      `codex mcp add ${MCP_NAME} --url "${MCP_URL}"`,
+      { stdio: 'pipe', timeout: 10000, windowsHide: true }
+    );
+    return { success: true, action: 'registered' };
+  } catch (err) {
+    return { success: false, action: 'failed', error: err.message };
+  }
+}
+
+function setup(options = {}) {
+  const { silent = false } = options;
+  const log = silent ? () => {} : (msg) => process.stderr.write(`[setup-codex] ${msg}\n`);
+
+  if (!isCodexInstalled()) {
+    log('codex CLI not found — skipping MCP registration');
+    return { success: true, action: 'skipped', reason: 'codex_not_installed' };
+  }
+
+  // TASK_2377: kenaz install --dry-run - report what would change, touch nothing.
+  if (options.dryRun) {
+    const missingEv = missingHookEvents();
+    log('dry-run: MCP ' + MCP_NAME + ' ' + (isMcpAlreadyRegistered() ? 'already registered' : 'would run codex mcp add ' + MCP_NAME + ' --url ' + MCP_URL));
+    log('dry-run: native hooks ' + (missingEv.length === 0 ? 'already registered' : 'would append [[hooks.*]] for ' + missingEv.join(', ') + ' to ' + getCodexConfigPath()));
+    log('dry-run: /kenaz prompt would be written to ' + path.join(getCodexHome(), 'prompts', 'kenaz.md'));
+    return { success: true, action: 'dry_run' };
+  }
+
+  // An existing MCP entry must not end setup: hooks and the $kenaz skill below still need
+  // repairing on machines installed by an older setup (live check 2026-10-10: MCP present,
+  // only 1 of 5 hooks, no skill, and re-running setup changed nothing).
+  let result;
+  if (isMcpAlreadyRegistered()) {
+    log(`${MCP_NAME} already registered in codex config`);
+    result = { success: true, action: 'already_registered' };
+  } else {
+    const existingUrl = getRegisteredMcpUrl();
+    let keptTools = '';
+    if (existingUrl !== null) {
+      log('Stale URL detected, refreshing');
+      keptTools = readToolTables();
+      try {
+        execSync(`codex mcp remove ${MCP_NAME}`, { stdio: 'pipe', timeout: 10000, windowsHide: true });
+      } catch {}
+    }
+
+    log(`Registering ${MCP_NAME} MCP (${MCP_URL})...`);
+    result = registerMcp();
+
+    if (result.success) {
+      log(`✓ ${MCP_NAME} registered successfully`);
+      const back = restoreToolTables(keptTools) + restoreSidecar();
+      if (back) log(`restored ${back} user tool approval table(s) for ${MCP_NAME}`);
+    } else {
+      log(`✗ Registration failed: ${result.error}`);
+    }
+  }
+
+
+  // TASK_1733: register native hooks when codex CLI supports them.
+  // Graceful: if feature probe fails or hooks already registered, logs advisory and continues.
+  const projectRoot = options.projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // TASK_2299: per-event — an older install may have the shim for some events but not UserPromptSubmit (peer pull).
+  const missing = missingHookEvents();
+  if (missing.length === 0) {
+    log("kenaz native hooks already registered — skipping");
+  } else if (probeNativeHooksSupported()) {
+    registerHooks(log, projectRoot, missing);
+    log("Advisory: codex requires reviewing new hooks once - open codex and run /hooks to trust them (untrusted hooks do not run)");
+  } else {
+    log("codex_hooks feature not active in this codex version — native hook registration skipped");
+    log("Advisory: upgrade codex CLI and re-run setup to enable per-turn PostToolUse hooks (AC1)");
+  }
+
+  // TASK_2379: /kenaz custom prompt + hook trust diagnosis (never fails setup).
+  try {
+    const doctor = require('./codex-doctor');
+    log('/kenaz prompt+skill ' + doctor.installPrompts().action + ' (codex: $kenaz; older codex: /prompts:kenaz)');
+    doctor.diagnose().notes.forEach((n) => log('Advisory: ' + n));
+  } catch (err) { log('codex-doctor skipped: ' + err.message); }
+
+  return result;
+}
+
+// TASK_2377: inverse of setup() for `kenaz uninstall`. Removes only what setup() added:
+// the kenaz-dashboard MCP entry, [[hooks.*]] blocks pointing at our shim, the /kenaz prompt.
+function uninstall(options = {}) {
+  const { silent = false, dryRun = false } = options;
+  const log = silent ? () => {} : (msg) => process.stderr.write(`[setup-codex] ${msg}\n`);
+  const res = { mcp: 'absent', hooks: 'absent', prompt: 'absent' };
+  const cfg = getCodexConfigPath();
+  if (getRegisteredMcpUrl() !== null) {
+    res.mcp = 'removed';
+    if (!dryRun) {
+      const tools = readToolTables();
+      if (tools) fs.writeFileSync(path.join(getCodexHome(), TOOLS_SIDECAR), tools + '\n', 'utf8');
+      try { execSync(`codex mcp remove ${MCP_NAME}`, { stdio: 'pipe', timeout: 10000, windowsHide: true }); }
+      catch (e) { res.mcp = 'failed: ' + e.message; }
+    }
+  }
+  const text = fs.existsSync(cfg) ? fs.readFileSync(cfg, 'utf8') : ''; // after `codex mcp remove` rewrote the file
+  // Drop each [[hooks.EV]] group whose nested [[hooks.EV.hooks]] handler runs our shim, plus our marker comment.
+  const segs = []; // [header line | null, body lines]
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*\[/.test(line) || !segs.length) segs.push([/^\s*\[/.test(line) ? line : null, [line]]);
+    else segs[segs.length - 1][1].push(line);
+  }
+  const out = [];
+  for (let n = 0; n < segs.length; n++) {
+    const [h, body] = segs[n], nx = segs[n + 1];
+    if (h && /^\s*\[\[hooks\.\w+\]\]\s*$/.test(h) && nx && nx[0] && /^\s*\[\[hooks\.\w+\.hooks\]\]/.test(nx[0]) &&
+        nx[1].join('\n').split('\\').join('/').includes(HOOK_SHIM_REL)) { n++; res.hooks = 'removed'; continue; }
+    out.push(...body.filter((l) => !/^# kenaz-dashboard native hooks/.test(l)));
+  }
+  if (res.hooks === 'removed' && !dryRun) fs.writeFileSync(cfg, out.join('\n').replace(/\n{3,}/g, '\n\n'), 'utf8');
+  const prompt = path.join(getCodexHome(), 'prompts', 'kenaz.md');
+  if (fs.existsSync(prompt)) { res.prompt = 'removed'; if (!dryRun) fs.rmSync(prompt, { force: true }); }
+  log((dryRun ? 'dry-run: ' : '') + 'codex uninstall ' + JSON.stringify(res));
+  return { success: true, ...res };
+}
+
+// ── Native Hook Registration (TASK_1733) ──────────────────────────────────────────────────
+// Codex CLI supports lifecycle hooks via [[hooks.EventName]] array-of-tables in
+// ~/.codex/config.toml (PascalCase event names; nested [[hooks.EventName.hooks]] entries
+// with type="command"). Docs: https://developers.openai.com/codex/hooks
+// Feature probe: `codex features list` line format is `<feature name>  <stage words>  true|false`
+// where <stage words> can be multi-word (e.g. "under development"). Gate on trailing bool.
+// Graceful fallback when feature absent: log advisory, skip registration.
+//
+// TASK_2160 field fix: the feature was named `codex_hooks` in older codex-cli
+// builds but ships as plain `hooks` as of codex-cli 0.159.2 (live-checked:
+// `codex features list | grep -i hook` on this install prints
+// `hooks  stable  true` — no `codex_hooks` line exists at all anymore).
+// The old regex only matched the retired name, so on any current install
+// probeNativeHooksSupported() silently always returned false and
+// registerHooks() never ran — discovered while live-verifying TASK_2141
+// open risk 5 (Codex hook → turn injection) for TASK_2160, since that
+// verification is moot if native hooks were never registered in the first
+// place. Matching BOTH names keeps old installs working too.
+const HOOK_SHIM_REL = '.formation/bifrost/openai/codex-hook-shim.js';
+const HOOK_EVENTS = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart', 'Stop'];
+
+function probeNativeHooksSupported() {
+  if (!isCodexInstalled()) return false;
+  const list = () => execSync('codex features list', { stdio: 'pipe', timeout: 8000, windowsHide: true }).toString();
+  try {
+    const out = list();
+    if (/^\s*(?:codex_hooks|hooks)\b.*\btrue\s*$/im.test(out)) return true;
+    // codex 0.160 ships `hooks` as a stable feature that is off by default (field report 2026-10-10):
+    // turn it on with codex's own command (writes [features] hooks = true), then re-check.
+    const off = out.match(/^\s*(codex_hooks|hooks)\b.*\bfalse\s*$/im);
+    if (!off) return false;
+    execSync(`codex features enable ${off[1]}`, { stdio: 'pipe', timeout: 8000, windowsHide: true });
+    return /^\s*(?:codex_hooks|hooks)\b.*\btrue\s*$/im.test(list());
+  } catch {
+    return false;
+  }
+}
+
+// The shim ships next to this file in whatever core runs setup (repo checkout or ~/.kenaz/core from
+// npm). Resolving from the cwd pointed npm installs at <project>/.formation/... which does not exist.
+// projectRoot is kept in the signature for callers; it no longer changes the result.
+function getHookShimPath(_projectRoot) {
+  return path.resolve(__dirname, '..', '..', HOOK_SHIM_REL);
+}
+
+function areHooksAlreadyRegistered(projectRoot) {
+  const configPath = getCodexConfigPath();
+  if (!fs.existsSync(configPath)) return false;
+  const content = fs.readFileSync(configPath, 'utf8');
+  const shimPath = getHookShimPath(projectRoot);
+  // Registered if config contains our shim path in any hooks entry
+  return content.includes(HOOK_SHIM_REL) || content.includes(shimPath.split('\\').join('/'));
+}
+
+// TASK_2299: HOOK_EVENTS that have no [[hooks.EV.hooks]] block pointing at our shim in config.toml.
+function missingHookEvents() {
+  const configPath = getCodexConfigPath();
+  const content = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8').replace(/\\/g, '/') : '';
+  return HOOK_EVENTS.filter((ev) => {
+    const blocks = content.match(new RegExp('\\[\\[hooks\\.' + ev + '\\.hooks\\]\\][^\\[]*', 'g')) || [];
+    return !blocks.some((blk) => blk.includes(HOOK_SHIM_REL));
+  });
+}
+
+// True when the codex CLI both supports hooks AND our shim is registered.
+// Spawn sites (relay.js, bifrost/session.js) use this to set CODEX_NATIVE_HOOKS_ACTIVE,
+// which suppresses the relay-side Pre/PostToolUse emulation
+// (single-source-of-truth dedupe, AC2).
+function nativeHooksActive(projectRoot) {
+  return areHooksAlreadyRegistered(projectRoot) && probeNativeHooksSupported();
+}
+
+function registerHooks(log, projectRoot, events) {
+  const shimPath = getHookShimPath(projectRoot).split('\\').join('/');
+  const configPath = getCodexConfigPath();
+
+  // Ensure ~/.codex dir exists
+  const codexDir = path.dirname(configPath);
+  if (!fs.existsSync(codexDir)) {
+    try { fs.mkdirSync(codexDir, { recursive: true }); } catch { /* ignore */ }
+  }
+
+  // [[hooks.X]] array-of-tables entries are additive-safe TOML: appending is valid
+  // even if the user already has their own [[hooks.X]] entries from other tools.
+  const lines = ['', '# kenaz-dashboard native hooks (TASK_1733) -- auto-registered by setup-codex.js'];
+  for (const ev of events || HOOK_EVENTS) {
+    lines.push(
+      '[[hooks.' + ev + ']]',
+      '',
+      '[[hooks.' + ev + '.hooks]]',
+      'type = "command"',
+      'command = \'node "' + shimPath + '"' + (ev === 'UserPromptSubmit' ? ' --pull' : '') + '\'', // TASK_2379: --pull = interactive sessions pull peer mail
+      'timeout = 15',
+      ''
+    );
+  }
+  const hookBlock = lines.join('\n');
+
+  try {
+    fs.appendFileSync(configPath, hookBlock, 'utf8');
+    log('kenaz hooks appended to ' + configPath);
+    return { success: true, action: 'hooks_registered' };
+  } catch (err) {
+    log('hook registration failed: ' + err.message);
+    return { success: false, action: 'hooks_failed', error: err.message };
+  }
+}
+
+// ── Project-declared MCP servers (TASK_1780 · Bifrost B2) ─────────────────────
+//
+// Sub-projects declare the MCP servers their codex dispatches need in
+// <projectRoot>/.kenaz/project.yaml:
+//
+//   mcp_servers:
+//     - name: unity-mcp                       # required; [A-Za-z0-9_-]+ only.
+//                                             #   Tools surface as mcp__<name>__<tool>
+//       transport: http                       # required; "http" | "stdio"
+//       url: http://localhost:7891/mcp        # http only (required)
+//       # command: node                       # stdio only (required)
+//       # args: ["path/to/server.js"]         # stdio only (optional)
+//       # env: { KEY: value }                 # stdio only (optional, via --env)
+//       probe: true                           # optional; default true for http.
+//                                             #   Unreachable => WARNING only,
+//                                             #   dispatch proceeds.
+//
+// ensureProjectMcpServers(dir) is called at dispatch time (relay.js headless
+// path, launch.js interactive path). It is idempotent: already-registered
+// servers with a matching definition are skipped; a changed definition is
+// refreshed via `codex mcp remove` + `codex mcp add`.
+//
+// Retention policy (prevents unbounded ~/.codex/config.toml accumulation):
+// every entry we register is recorded in $CODEX_HOME/kenaz-project-mcp.json
+// with its owning project root. An entry is pruned from config.toml when:
+//   (a) its owning project's manifest no longer declares it (checked when
+//       that project dispatches), or
+//   (b) its owning project path no longer exists on disk, or
+//   (c) another project claims the same name with a different definition
+//       (remove + re-add; ownership reassigned to the newer project).
+// Entries owned by OTHER live projects are left alone (concurrent dispatches
+// for different projects share one config.toml). 'kenaz-dashboard' and any
+// server we did not register (absent from the sidecar) are NEVER touched.
+
+const PROJECT_MCP_REGISTRY = 'kenaz-project-mcp.json';
+const RESERVED_MCP_NAMES = new Set([MCP_NAME]);
+
+function loadYamlModule() {
+  try { return require('js-yaml'); } catch {
+    // Same fallback chain as .collaboration/core/task-api.js
+    const candidates = [
+      path.resolve(__dirname, '../..', '.vendor', 'js-yaml.cjs'),
+      path.resolve(__dirname, '.vendor', 'js-yaml.cjs'),
+    ];
+    if (process.env.KENAZ_SOURCE_DIR) {
+      candidates.unshift(path.join(process.env.KENAZ_SOURCE_DIR, '.vendor', 'js-yaml.cjs'));
+    }
+    for (const c of candidates) {
+      if (fs.existsSync(c)) { try { return require(c); } catch { /* next */ } }
+    }
+    return null;
+  }
+}
+
+/**
+ * Resolve the .kenaz/project.yaml governing `startDir`.
+ * Worktree-aware: dispatch cwd is usually a worktree; if the manifest is not
+ * checked in there (sub-project .kenaz/ is often local-only), fall back to the
+ * MAIN repo root via `git rev-parse --git-common-dir`.
+ */
+function resolveProjectManifest(startDir) {
+  const tryDirs = [];
+  if (startDir) tryDirs.push(path.resolve(startDir));
+  try {
+    const common = execSync(
+      `git -C "${startDir}" rev-parse --path-format=absolute --git-common-dir`,
+      { stdio: 'pipe', timeout: 5000, windowsHide: true }
+    ).toString().trim();
+    if (common) {
+      const mainRoot = path.dirname(common); // <repo>/.git -> <repo>
+      if (mainRoot && !tryDirs.includes(mainRoot)) tryDirs.push(mainRoot);
+    }
+  } catch { /* not a git dir — manifest lookup limited to startDir */ }
+  for (const dir of tryDirs) {
+    const p = path.join(dir, '.kenaz', 'project.yaml');
+    if (fs.existsSync(p)) return { projectRoot: dir, manifestPath: p };
+  }
+  return null;
+}
+
+/**
+ * Parse + validate the mcp_servers list from a project manifest.
+ * Returns { servers: [...normalized], warnings: [...strings] }.
+ * Invalid entries are skipped with a warning — never fatal.
+ */
+function parseProjectMcpServers(manifestPath) {
+  const warnings = [];
+  const yaml = loadYamlModule();
+  if (!yaml) return { servers: [], warnings: ['js-yaml unavailable — mcp_servers declarations ignored'] };
+  let doc;
+  try {
+    doc = yaml.load(fs.readFileSync(manifestPath, 'utf8'), { json: true });
+  } catch (err) {
+    return { servers: [], warnings: [`project.yaml parse failed: ${err.message}`] };
+  }
+  const raw = doc && doc.mcp_servers;
+  if (!Array.isArray(raw) || raw.length === 0) return { servers: [], warnings };
+
+  const servers = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') { warnings.push('mcp_servers entry is not a map — skipped'); continue; }
+    const name = String(entry.name || '').trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) { warnings.push(`mcp_servers entry has invalid name "${name}" — skipped`); continue; }
+    if (RESERVED_MCP_NAMES.has(name)) { warnings.push(`mcp_servers name "${name}" is reserved (managed by setup()) — skipped`); continue; }
+    const transport = String(entry.transport || '').trim().toLowerCase();
+    if (transport === 'http') {
+      const url = String(entry.url || '').trim();
+      if (!/^https?:\/\//.test(url)) { warnings.push(`mcp_servers "${name}": http transport requires url — skipped`); continue; }
+      servers.push({ name, transport, url, probe: entry.probe !== false });
+    } else if (transport === 'stdio') {
+      const command = String(entry.command || '').trim();
+      if (!command) { warnings.push(`mcp_servers "${name}": stdio transport requires command — skipped`); continue; }
+      const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
+      const env = (entry.env && typeof entry.env === 'object') ? entry.env : {};
+      servers.push({ name, transport, command, args, env, probe: entry.probe === true });
+    } else {
+      warnings.push(`mcp_servers "${name}": unknown transport "${transport}" — skipped`);
+    }
+  }
+  return { servers, warnings };
+}
+
+/** Parse [mcp_servers.<name>] sections out of config.toml → { name: { url, command, args } } */
+function parseRegisteredMcpServers() {
+  const configPath = getCodexConfigPath();
+  if (!fs.existsSync(configPath)) return {};
+  const content = fs.readFileSync(configPath, 'utf8');
+  const out = {};
+  const sectionRe = /^\[mcp_servers\.([A-Za-z0-9_-]+)\]\s*$/gm;
+  let m;
+  const marks = [];
+  while ((m = sectionRe.exec(content)) !== null) marks.push({ name: m[1], start: m.index + m[0].length });
+  for (let i = 0; i < marks.length; i++) {
+    const end = content.indexOf('\n[', marks[i].start);
+    const block = content.slice(marks[i].start, end === -1 ? content.length : end);
+    const url = (block.match(/^\s*url\s*=\s*"([^"]*)"/m) || [])[1] || null;
+    const command = (block.match(/^\s*command\s*=\s*"([^"]*)"/m) || [])[1] || null;
+    const argsRaw = (block.match(/^\s*args\s*=\s*\[([^\]]*)\]/m) || [])[1];
+    const args = argsRaw != null ? (argsRaw.match(/"([^"]*)"/g) || []).map(s => s.slice(1, -1)) : null;
+    out[marks[i].name] = { url, command, args };
+  }
+  return out;
+}
+
+/** True when the registered config.toml entry already matches the declared definition. */
+function registeredMatchesDeclared(registered, declared) {
+  if (!registered) return false;
+  if (declared.transport === 'http') return registered.url === declared.url;
+  // stdio: best-effort compare command + args (env not round-trippable — documented)
+  if (registered.command !== declared.command) return false;
+  const regArgs = registered.args || [];
+  const decArgs = declared.args || [];
+  return regArgs.length === decArgs.length && regArgs.every((a, i) => a === decArgs[i]);
+}
+
+function normalizeProjectKey(projectRoot) {
+  const p = path.resolve(projectRoot).split('\\').join('/');
+  return process.platform === 'win32' ? p.toLowerCase() : p;
+}
+
+function loadProjectMcpRegistry() {
+  const p = path.join(getCodexHome(), PROJECT_MCP_REGISTRY);
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+function saveProjectMcpRegistry(registry) {
+  const dir = getCodexHome();
+  try {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, PROJECT_MCP_REGISTRY), JSON.stringify(registry, null, 2), 'utf8');
+  } catch { /* sidecar write failure is non-fatal — worst case: no pruning */ }
+}
+
+function codexMcpRemove(name) {
+  try {
+    execSync(`codex mcp remove ${name}`, { stdio: 'pipe', timeout: 10000, windowsHide: true });
+    return true;
+  } catch { return false; }
+}
+
+function codexMcpAdd(declared) {
+  const q = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
+  let cmd;
+  if (declared.transport === 'http') {
+    cmd = `codex mcp add ${declared.name} --url ${q(declared.url)}`;
+  } else {
+    const envFlags = Object.entries(declared.env || {}).map(([k, v]) => `--env ${q(`${k}=${v}`)}`).join(' ');
+    const tail = [declared.command, ...(declared.args || [])].map(q).join(' ');
+    cmd = `codex mcp add ${declared.name} ${envFlags ? envFlags + ' ' : ''}-- ${tail}`;
+  }
+  try {
+    execSync(cmd, { stdio: 'pipe', timeout: 15000, windowsHide: true });
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * ensureProjectMcpServers — dispatch-time registration entry point (TASK_1780).
+ *
+ * Idempotent + fail-open: never throws, never blocks a dispatch. Call before
+ * spawning codex for a project so its declared MCP servers are usable.
+ *
+ * @param {string} dirOrCwd  dispatch cwd (worktree or project root)
+ * @param {object} options   { silent }
+ * @returns summary { action, registered[], refreshed[], pruned[], skipped[], warnings[] }
+ */
+function ensureProjectMcpServers(dirOrCwd, options = {}) {
+  const { silent = false } = options;
+  const log = silent ? () => {} : (msg) => process.stderr.write(`[setup-codex:project-mcp] ${msg}\n`);
+  const summary = { action: 'ok', registered: [], refreshed: [], pruned: [], skipped: [], warnings: [] };
+  try {
+    if (!isCodexInstalled()) { summary.action = 'skipped_no_codex'; return summary; }
+    const resolved = resolveProjectManifest(dirOrCwd);
+    if (!resolved) { summary.action = 'no_manifest'; return summary; }
+
+    const { servers, warnings } = parseProjectMcpServers(resolved.manifestPath);
+    summary.warnings = warnings;
+    for (const w of warnings) log(`warning: ${w}`);
+
+    const projectKey = normalizeProjectKey(resolved.projectRoot);
+    const registered = parseRegisteredMcpServers();
+    const registry = loadProjectMcpRegistry();
+    const declaredNames = new Set(servers.map(s => s.name));
+
+    // 1. Ensure declared servers
+    for (const declared of servers) {
+      const existing = registered[declared.name];
+      if (registeredMatchesDeclared(existing, declared)) {
+        summary.skipped.push(declared.name);
+      } else {
+        const isRefresh = Boolean(existing);
+        if (isRefresh) codexMcpRemove(declared.name);
+        const res = codexMcpAdd(declared);
+        if (res.success) {
+          (isRefresh ? summary.refreshed : summary.registered).push(declared.name);
+          log(`${isRefresh ? 'refreshed' : 'registered'} ${declared.name} (${declared.transport === 'http' ? declared.url : declared.command})`);
+        } else {
+          summary.warnings.push(`codex mcp add ${declared.name} failed: ${res.error}`);
+          log(`warning: codex mcp add ${declared.name} failed: ${res.error}`);
+          continue; // don't record ownership of an entry we failed to add
+        }
+      }
+      registry[declared.name] = {
+        project: projectKey,
+        transport: declared.transport,
+        signature: declared.transport === 'http' ? declared.url : [declared.command, ...(declared.args || [])].join(' '),
+        registered_at: new Date().toISOString(),
+      };
+    }
+
+    // 2. Prune per retention policy (see block comment above)
+    for (const [name, meta] of Object.entries(registry)) {
+      if (RESERVED_MCP_NAMES.has(name) || declaredNames.has(name)) continue;
+      const ownedByThisProject = meta && meta.project === projectKey;
+      const ownerGone = meta && meta.project && !fs.existsSync(meta.project);
+      if (ownedByThisProject || ownerGone) {
+        if (registered[name]) codexMcpRemove(name);
+        delete registry[name];
+        summary.pruned.push(name);
+        log(`pruned ${name} (${ownedByThisProject ? 'no longer declared by owning project' : 'owning project path gone'})`);
+      }
+    }
+
+    saveProjectMcpRegistry(registry);
+  } catch (err) {
+    summary.action = 'error';
+    summary.warnings.push(err.message);
+    log(`warning: ensure failed (dispatch proceeds): ${err.message}`);
+  }
+  return summary;
+}
+
+/**
+ * probeProjectMcpServers — optional pre-dispatch reachability probe (TASK_1780).
+ * Mirrors launch.js probeKenazMcp's tools/list POST, but WARN-ONLY: an
+ * unreachable project server never blocks the dispatch (the Ashfall Unity MCP
+ * only exists while the editor is open — codex should still be able to work).
+ */
+async function probeProjectMcpServers(dirOrCwd, options = {}) {
+  const { silent = false } = options;
+  const warn = silent ? () => {} : (msg) => process.stderr.write(`[bifrost:probe] ${msg}\n`);
+  const results = [];
+  try {
+    const resolved = resolveProjectManifest(dirOrCwd);
+    if (!resolved) return results;
+    const { servers } = parseProjectMcpServers(resolved.manifestPath);
+    for (const s of servers) {
+      if (s.transport !== 'http' || !s.probe) continue; // stdio servers are spawned by codex itself
+      const ok = await probeHttpMcp(s.url);
+      results.push({ name: s.name, url: s.url, reachable: ok });
+      if (ok) {
+        warn(`project-server=${s.name} reachable=true url=${s.url}`);
+      } else {
+        warn(`project-server=${s.name} reachable=false url=${s.url} — WARNING only, dispatch proceeds`);
+      }
+    }
+  } catch { /* probe is advisory — never fatal */ }
+  return results;
+}
+
+function probeHttpMcp(urlStr) {
+  return new Promise((resolve) => {
+    let url;
+    try { url = new URL(urlStr); } catch { return resolve(false); }
+    const body = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} });
+    const req = http.request({
+      hostname: url.hostname,
+      port: url.port || 80,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      timeout: 3000,
+    }, (res) => {
+      res.resume(); // drain — any HTTP response counts as reachable
+      res.on('end', () => resolve(res.statusCode != null && res.statusCode < 500));
+    });
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', () => resolve(false));
+    req.write(body);
+    req.end();
+  });
+}
+
+// Export for programmatic use
+module.exports = {
+  setup, uninstall, isCodexInstalled, isMcpAlreadyRegistered, getRegisteredMcpUrl, registerMcp,
+  probeNativeHooksSupported, areHooksAlreadyRegistered, missingHookEvents, registerHooks, getHookShimPath,
+  nativeHooksActive,
+  // TASK_1780 — project-declared MCP servers
+  getCodexHome, getCodexConfigPath, resolveProjectManifest, parseProjectMcpServers,
+  parseRegisteredMcpServers, ensureProjectMcpServers, probeProjectMcpServers,
+};
+
+// CLI mode
+if (require.main === module) {
+  const result = setup();
+  if (!result.success) process.exit(1);
+}