@flowrail/init 0.0.17 → 0.1.0

package/README.md

@@ -21,6 +21,24 @@ What it writes:
 
 The installer finishes by probing `https://api.flowrail.ai/mcp` with your key to confirm end-to-end auth before exiting. A 401 gets an actionable message; transport failures get a different one.
 
+## OpenAI Codex (experimental)
+
+```bash
+npx @flowrail/init@latest --agent codex
+```
+
+This installs and self-tests the exact `@flowrail/hook` release it pins, then writes:
+- `.codex/hooks.json`: four exact-pinned hooks.
+- `.codex/config.toml`: the MCP server; the bearer comes from `FLOWRAIL_API_KEY`.
+- `.agents/skills/` and a FlowRail section in `AGENTS.md`.
+- `scripts/check-flowrail-codex.mjs`: the readiness check.
+
+Nothing under `.claude/` changes.
+
+Codex runs the hooks only after you **trust the project** and **approve the hooks in `/hooks`**.
+Run `node scripts/check-flowrail-codex.mjs` until it reports `readiness: active`. Details:
+<https://flowrail.ai/docs>.
+
 ## Links
 
 - Website: <https://flowrail.ai>

package/dist/app-instance.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * ADR-019 M0' — durable app-instance identity (Decision 1).
+ * ADR-021 M0' — durable app-instance identity (§1).
  *
  * ``init`` mints an ``app_instance_id`` (mint-if-absent) into
  * ``.flowrail/app.json`` and registers it with the server via the
@@ -112,7 +112,7 @@ function readAppIdentity(projectRoot) {
 }
 /** Write ``.flowrail/app.json``. Never clobbers a DIFFERENT id — the
  *  mint is permanent for the life of the clone (re-mint only via
- *  delete/re-clone, per ADR-019 Decision 1). */
+ *  delete/re-clone, per ADR-021 §1). */
 function writeAppIdentity(projectRoot, identity) {
     const existing = readAppIdentity(projectRoot);
     if (existing !== null) {

package/dist/claude-settings.js

@@ -3,7 +3,7 @@
  * Read / merge / write ``.claude/settings.json``.
  *
  * Wires PreToolUse hooks for Write/Edit/MultiEdit (pre-write
- * dispatcher) and Bash (pre-bash dispatcher), plus the ADR-019 Stop
+ * dispatcher) and Bash (pre-bash dispatcher), plus the ADR-021 Stop
  * (turn-batched whole-app review) and SessionStart (coverage catch-up)
  * hooks. All invoke ``flowrail-hook`` from the @flowrail/hook package
  * the tester is expected to have installed alongside this init.
@@ -27,7 +27,7 @@ const HOOK_BIN_NAME = 'flowrail-hook';
 const HOOK_BIN = `npx --yes -p @flowrail/hook ${HOOK_BIN_NAME}`;
 exports.PRE_WRITE_MATCHER = 'Write|Edit|MultiEdit';
 exports.PRE_BASH_MATCHER = 'Bash';
-// ADR-019 failure posture: the Stop/SessionStart hook timeout is sized
+// ADR-021 §3 failure posture: the Stop/SessionStart hook timeout is sized
 // to batched whole-app reality and set EXPLICITLY in the generated
 // settings entry (seconds). It sits above the hook's own HTTP client
 // timeout so the client, not Claude Code, decides how a slow review

package/dist/codex-doctor-script.js

@@ -0,0 +1,388 @@
+"use strict";
+/**
+ * The generated Codex readiness doctor, `scripts/check-flowrail-codex.mjs`
+ * (ADR-050 D9). Self-contained ESM (node builtins only), regenerated by every
+ * `npx @flowrail/init --agent codex`.
+ *
+ * "Configured" is not "active": Codex only runs FlowRail's hooks after the
+ * user trusts the project AND approves each handler, and `codex exec` skips
+ * unapproved hooks silently. The doctor therefore reports one readiness
+ * state and never calls an install healthy unless Codex itself says the four
+ * FlowRail handlers are trusted and enabled:
+ *
+ *   configured | needs-project-trust | needs-handler-approval | disabled |
+ *   incompatible-version | active | unverified (codex not on PATH)
+ *
+ * Configuration errors (missing or malformed wiring, a hook release without
+ * the Codex adapter, a login shell that pollutes stdout) fail the check;
+ * pending approvals are warnings, so a fresh install never breaks a build
+ * before the user has had a chance to approve it in Codex.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_DOCTOR_FILENAME = void 0;
+exports.renderCodexDoctorScript = renderCodexDoctorScript;
+exports.writeCodexDoctorScript = writeCodexDoctorScript;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const codex_target_1 = require("./codex-target");
+exports.CODEX_DOCTOR_FILENAME = 'scripts/check-flowrail-codex.mjs';
+function renderCodexDoctorScript(version = codex_target_1.CODEX_HOOK_VERSION) {
+    return `#!/usr/bin/env node
+// FlowRail readiness check for OpenAI Codex — generated by
+// \`npx @flowrail/init --agent codex\`; re-running init regenerates it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+const EXPECTED_VERSION = ${JSON.stringify(version)};
+// The generated timeouts: a shorter one lets Codex kill the hook first, and
+// a Codex hook timeout is a silent allow.
+const TIMEOUTS = ${JSON.stringify(codex_target_1.CODEX_HOOK_TIMEOUTS)};
+const EVENT = { 'pre-write': 'preToolUse', 'pre-bash': 'preToolUse', stop: 'stop', 'session-start': 'sessionStart' };
+const TOML_MARKER = ${JSON.stringify(codex_target_1.TOML_BLOCK_BEGIN)};
+const PLACEMENT = {
+  'pre-write': ['PreToolUse', 'apply_patch'],
+  'pre-bash': ['PreToolUse', 'Bash'],
+  stop: ['Stop', null],
+  'session-start': ['SessionStart', null],
+};
+// Exactly the installer's grammar: the one endpoint assignment (bare or
+// single-quoted), the exact pin, nothing else (ADR-050 D8).
+const OURS = /^FLOWRAIL_MCP_URL=('(?:[^']|'\\\\'')*'|[A-Za-z0-9_@%+=:,.\\/-]+) npx --yes -p @flowrail\\/hook@(\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?) flowrail-hook agent codex (pre-write|pre-bash|stop|session-start)$/;
+const REINIT = \`npx --yes @flowrail/init@latest --agent codex\`;
+const LEGACY = /^(?:FLOWRAIL_[A-Z0-9_]*=\\S+\\s+)*npx\\s+--yes\\s+-p\\s+@flowrail\\/hook(?:@\\S+)?\\s+flowrail-hook\\s+(pre-write|pre-bash|stop|session-start)\\s*$/;
+
+// The hook's own grammar: an http(s) endpoint and exactly the installer's
+// text (canonical quoting) — anything else is not FlowRail wiring.
+const shellQuote = (v) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(v) ? v : "'" + v.replace(/'/g, "'\\\\''") + "'");
+function isInstallerCommand(command, m) {
+  const url = m[1].startsWith("'") ? m[1].slice(1, -1).replace(/'\\\\''/g, "'") : m[1];
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return false;
+  return command === \`FLOWRAIL_MCP_URL=\${shellQuote(url)} npx --yes -p @flowrail/hook@\${m[2]} flowrail-hook agent codex \${m[3]}\`;
+}
+
+let failures = 0;
+const ok = (m) => console.log(\`✓ \${m}\`);
+const warn = (m) => console.warn(\`⚠ \${m}\`);
+const fail = (m) => { failures++; console.error(\`✗ \${m}\`); };
+const root = process.cwd();
+let readiness = 'configured';
+let incompatible = false;
+
+// 1. .codex/hooks.json — the four FlowRail handlers, where Codex expects them.
+const handlers = {};
+let pinned = new Set();
+try {
+  const config = JSON.parse(fs.readFileSync(path.join(root, '.codex/hooks.json'), 'utf8'));
+  for (const [event, groups] of Object.entries(config.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((group) => {
+      (group?.hooks ?? []).forEach((h) => {
+        const m = h?.type === 'command' && typeof h?.command === 'string' ? OURS.exec(h.command) : null;
+        if (!m || !isInstallerCommand(h.command, m)) return;
+        const [wantEvent, wantMatcher] = PLACEMENT[m[3]];
+        if (event !== wantEvent) return;
+        // PreToolUse under its exact matcher; Stop and SessionStart under none.
+        if (wantMatcher === null ? group.matcher !== undefined && group.matcher !== null : group.matcher !== wantMatcher) return;
+        (handlers[m[3]] ??= []).push(h.command);
+        pinned.add(m[2]);
+        if (h.async === true) {
+          fail(\`.codex/hooks.json: the FlowRail \${m[3]} hook is asynchronous (async: true) — Codex would not wait for it, so it could not block anything — re-run \${REINIT}\`);
+        }
+        if (typeof h.timeout !== 'number' || h.timeout < TIMEOUTS[m[3]]) {
+          fail(\`.codex/hooks.json: the FlowRail \${m[3]} hook's timeout is \${h.timeout ?? 'unset (600s default)'}; it must be at least \${TIMEOUTS[m[3]]}s — re-run \${REINIT}\`);
+        }
+      });
+    });
+  }
+  for (const phase of Object.keys(PLACEMENT)) {
+    const found = handlers[phase] ?? [];
+    if (found.length === 1) continue;
+    fail(\`.codex/hooks.json: expected one FlowRail \${phase} hook, found \${found.length} — re-run \${REINIT}\`);
+  }
+  if (Object.keys(PLACEMENT).every((p) => (handlers[p] ?? []).length === 1)) ok('.codex/hooks.json wires all four FlowRail hooks');
+  if (pinned.size > 1) fail(\`.codex/hooks.json pins more than one @flowrail/hook version (\${[...pinned].join(', ')}) — re-run \${REINIT}\`);
+  else if (pinned.size === 1 && !pinned.has(EXPECTED_VERSION)) warn(\`hooks pin @flowrail/hook@\${[...pinned][0]}; this check expects \${EXPECTED_VERSION}\`);
+} catch (err) {
+  fail(\`.codex/hooks.json is missing or not valid JSON (\${err.message}) — re-run \${REINIT}\`);
+}
+
+// 2. .codex/config.toml — FlowRail's MCP server block.
+try {
+  const toml = fs.readFileSync(path.join(root, '.codex/config.toml'), 'utf8');
+  if (toml.includes(TOML_MARKER) && toml.includes('[mcp_servers.flowrail]') && toml.includes('bearer_token_env_var = "FLOWRAIL_API_KEY"')) {
+    ok('.codex/config.toml defines the FlowRail MCP server');
+  } else {
+    fail(\`.codex/config.toml has no FlowRail MCP block — re-run \${REINIT}\`);
+  }
+} catch {
+  fail(\`.codex/config.toml is missing — re-run \${REINIT}\`);
+}
+
+// 3. The credential the hooks and the MCP client read.
+if ((process.env.FLOWRAIL_API_KEY ?? '').trim()) ok('FLOWRAIL_API_KEY is set');
+else warn('FLOWRAIL_API_KEY is not set in this shell — Codex must be started from a shell that has it');
+
+// 4. Codex runs hooks through a login shell ($SHELL -lc) from the project.
+//    Anything that shell prints corrupts FlowRail's JSON decisions (Codex
+//    then IGNORES them — fails open), and a profile that changes PATH can
+//    hide npx entirely. So everything below runs exactly that way.
+const shell = process.env.SHELL || '/bin/sh';
+const firstLine = (t) => (t ?? '').trim().split('\\n')[0].slice(0, 160);
+const viaShell = (command, extra = {}) =>
+  spawnSync(shell, ['-lc', command], { cwd: root, encoding: 'utf8', timeout: 60000, ...extra });
+const probe = viaShell('true', { timeout: 10000 });
+let shellClean = false;
+if (probe.error) fail(\`could not start \${shell} -lc (\${probe.error.message}) — Codex could not run any hook\`);
+else if ((probe.stdout ?? '') !== '') fail(\`\${shell} -lc prints output on startup ("\${firstLine(probe.stdout)}") — Codex would ignore FlowRail's decisions. Move that output to stderr or an interactive-only block.\`);
+else { shellClean = true; ok(\`\${shell} -lc starts cleanly\`); }
+
+// 5. The exact pinned hook release, run the way Codex runs it, must
+//    implement the Codex adapter...
+let testedVersions = [];
+const version = pinned.size === 1 ? [...pinned][0] : EXPECTED_VERSION;
+if (shellClean) {
+  const caps = viaShell(\`npx --yes -p @flowrail/hook@\${version} flowrail-hook capabilities\`);
+  if (caps.error || caps.status !== 0) {
+    fail(\`@flowrail/hook@\${version} does not run through \${shell} -lc (\${caps.error?.message ?? firstLine(caps.stderr) ?? 'exit ' + caps.status}) — Codex runs hooks this way, so FlowRail would not run. Check that npx is on the PATH your login shell sets.\`);
+  } else {
+    try {
+      const c = JSON.parse(caps.stdout);
+      if (c.agents?.codex && c.adapter_protocol >= 1) {
+        ok(\`@flowrail/hook@\${version} implements the Codex adapter (\${c.agents.codex.state})\`);
+        testedVersions = Array.isArray(c.agents.codex.tested_versions) ? c.agents.codex.tested_versions : [];
+      } else { incompatible = true; fail(\`@flowrail/hook@\${version} does not implement the Codex adapter — re-run \${REINIT}\`); }
+    } catch {
+      fail(\`@flowrail/hook@\${version} capabilities printed something that is not JSON through \${shell} -lc — Codex would ignore FlowRail's decisions\`);
+    }
+  }
+
+  // ...and the generated pre-write command itself must block a patch that
+  // adds a test secret. Its endpoint is swapped for an unroutable one and
+  // the key for a dummy, so nothing reaches the FlowRail server.
+  const preWrite = (handlers['pre-write'] ?? [])[0];
+  if (preWrite && !incompatible) {
+    const probeCmd = preWrite.replace(/^FLOWRAIL_MCP_URL=('(?:[^']|'\\\\'')*'|\\S+)/, 'FLOWRAIL_MCP_URL=http://127.0.0.1:1');
+    const testSecret = 'AKIA' + 'IOSFODNN7' + 'EXAMPLE';
+    const payload = JSON.stringify({
+      session_id: '',
+      hook_event_name: 'PreToolUse',
+      cwd: root,
+      tool_name: 'apply_patch',
+      tool_input: { command: \`*** Begin Patch\\n*** Add File: flowrail-doctor-probe.ts\\n+const awsKey = "\${testSecret}";\\n*** End Patch\\n\` },
+    });
+    const r = viaShell(probeCmd, { input: payload, env: { ...process.env, FLOWRAIL_API_KEY: 'flowrail-doctor-probe' } });
+    if (r.status === 2 && /secret pattern detected/i.test(r.stderr ?? '')) ok('the generated pre-write hook blocks a test secret, run the way Codex runs it');
+    else fail(\`the generated pre-write hook did not block a test secret when run through \${shell} -lc (exit \${r.status}\${r.error ? ', ' + r.error.message : ''}) — FlowRail would not protect Codex writes\`);
+
+    // Its STRUCTURED deny (JSON on stdout, exit 0 — what a server-side
+    // verdict uses) must come back readable too: a patch for a file that
+    // does not exist is refused locally.
+    const missing = JSON.stringify({
+      session_id: '',
+      hook_event_name: 'PreToolUse',
+      cwd: root,
+      tool_name: 'apply_patch',
+      tool_input: { command: \`*** Begin Patch\\n*** Update File: flowrail-doctor-probe-missing.ts\\n@@\\n-a\\n+b\\n*** End Patch\\n\` },
+    });
+    const sd = viaShell(probeCmd, { input: missing, env: { ...process.env, FLOWRAIL_API_KEY: 'flowrail-doctor-probe' } });
+    let structured = false;
+    try {
+      structured = JSON.parse(sd.stdout).hookSpecificOutput?.permissionDecision === 'deny';
+    } catch {
+      structured = false;
+    }
+    if (sd.status === 0 && structured) ok('the generated pre-write hook returns a structured deny Codex can read, run the way Codex runs it');
+    else fail(\`the generated pre-write hook did not return a readable structured deny through \${shell} -lc (exit \${sd.status}) — Codex would ignore FlowRail's decisions\`);
+  }
+
+  // ...and a STRUCTURED deny (JSON on stdout — what shell noise corrupts)
+  // must come back readable: the pre-bash hook refusing a shell-run patch.
+  const preBash = (handlers['pre-bash'] ?? [])[0];
+  if (preBash && !incompatible) {
+    const probeCmd = preBash.replace(/^FLOWRAIL_MCP_URL=('(?:[^']|'\\\\'')*'|\\S+)/, 'FLOWRAIL_MCP_URL=http://127.0.0.1:1');
+    const payload = JSON.stringify({
+      session_id: '',
+      hook_event_name: 'PreToolUse',
+      cwd: root,
+      tool_name: 'Bash',
+      tool_input: { command: "apply_patch <<'EOF'\\n*** Begin Patch\\n*** End Patch\\nEOF" },
+    });
+    const r = viaShell(probeCmd, { input: payload, env: { ...process.env, FLOWRAIL_API_KEY: 'flowrail-doctor-probe' } });
+    let denied = false;
+    try {
+      denied = JSON.parse(r.stdout).hookSpecificOutput?.permissionDecision === 'deny';
+    } catch {
+      denied = false;
+    }
+    if (r.status === 0 && denied) ok('the generated pre-bash hook returns a structured deny Codex can read, run the way Codex runs it');
+    else fail(\`the generated pre-bash hook did not return a readable structured deny through \${shell} -lc (exit \${r.status}) — Codex would ignore FlowRail's decisions\`);
+  }
+}
+
+// 5b. Codex changes its hook payloads between releases: say so when the
+//     installed Codex is not one this hook release was tested with.
+if (testedVersions.length > 0) {
+  const cv = spawnSync('codex', ['--version'], { encoding: 'utf8', timeout: 10000 });
+  const installed = /(\\d+\\.\\d+\\.\\d+)/.exec(cv.stdout ?? '')?.[1];
+  if (installed && !testedVersions.includes(installed)) {
+    warn(\`Codex \${installed} is not a version this hook was tested with (\${testedVersions.join(', ')}) — FlowRail may miss writes if Codex changed its hook payloads\`);
+  }
+}
+
+// 6. Does Codex actually load, trust and enable the handlers? (model-free)
+async function codexHooks() {
+  return await new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('codex', ['app-server'], { cwd: root, stdio: ['pipe', 'pipe', 'ignore'] });
+    } catch {
+      return resolve({ absent: true });
+    }
+    const timer = setTimeout(() => { child.kill('SIGKILL'); resolve({ timeout: true }); }, 10000);
+    child.on('error', () => { clearTimeout(timer); resolve({ absent: true }); });
+    let buf = '';
+    child.stdout.on('data', (d) => {
+      buf += d.toString('utf8');
+      let i;
+      while ((i = buf.indexOf('\\n')) >= 0) {
+        const line = buf.slice(0, i); buf = buf.slice(i + 1);
+        let msg; try { msg = JSON.parse(line); } catch { continue; }
+        if (msg.id === 1) {
+          child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'initialized' }) + '\\n');
+          child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'hooks/list', params: { cwds: [root] } }) + '\\n');
+        } else if (msg.id === 2) {
+          clearTimeout(timer);
+          child.stdin.end(); child.kill();
+          resolve({ result: msg.result, error: msg.error });
+        }
+      }
+    });
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { clientInfo: { name: 'flowrail-doctor', version: EXPECTED_VERSION } } }) + '\\n');
+  });
+}
+
+const listed = await codexHooks();
+if (listed.absent) {
+  readiness = 'unverified';
+  warn('codex is not on PATH — cannot confirm Codex loads and trusts the FlowRail hooks');
+} else if (listed.timeout || listed.error) {
+  readiness = 'unverified';
+  warn('codex app-server did not answer hooks/list — cannot confirm readiness');
+} else {
+  const lists = listed.result?.data ?? [];
+  // Codex's own load problems (e.g. "failed to parse hooks config") are
+  // configuration errors, not pending approvals.
+  const describe = (w) => (typeof w === 'string' ? w : JSON.stringify(w));
+  for (const e of lists.flatMap((d) => d.errors ?? [])) {
+    fail(\`Codex reports an error loading hooks: \${firstLine(describe(e))} — fix the file it names, then re-run this check\`);
+  }
+  for (const w of lists.flatMap((d) => d.warnings ?? [])) {
+    const text = describe(w);
+    if (!/hook/i.test(text)) continue;
+    // A load failure drops the file (FlowRail is off); anything else — e.g.
+    // "prefer one representation" when hooks live in both config.toml and
+    // hooks.json — is advice and must not break the build.
+    // Codex 0.156 words load failures "failed to parse/read hooks config
+    // <path>: …"; match the message, never the path (which may say "error").
+    if (/^\\s*failed to /i.test(text)) {
+      fail(\`Codex reports a problem loading hooks: \${firstLine(text)} — fix the file it names, then re-run this check\`);
+    } else {
+      warn(\`Codex: \${firstLine(text)}\`);
+    }
+  }
+  // What Codex will actually run: FlowRail command handlers from this
+  // project's config, matched on event, matcher and exact command text.
+  const project = {};
+  let elsewhere = 0;
+  for (const h of lists.flatMap((d) => d.hooks ?? [])) {
+    const m = h.handlerType === 'command' && typeof h.command === 'string' ? OURS.exec(h.command) : null;
+    if (!m || !isInstallerCommand(h.command, m)) continue;
+    if (h.source !== 'project') {
+      elsewhere++;
+      continue;
+    }
+    const phase = m[3];
+    const wantMatcher = PLACEMENT[phase][1];
+    const placed = h.eventName === EVENT[phase] && (wantMatcher === null ? h.matcher === undefined || h.matcher === null : h.matcher === wantMatcher);
+    if (placed) (project[phase] ??= []).push({ ...h, pin: m[2] });
+  }
+  // A Claude Code FlowRail hook loaded by Codex (e.g. via import) receives
+  // Codex payloads and refuses every patch.
+  const legacyLoaded = lists
+    .flatMap((d) => d.hooks ?? [])
+    .filter((h) => h.handlerType === 'command' && typeof h.command === 'string' && LEGACY.test(h.command));
+  if (legacyLoaded.length > 0) {
+    fail(\`Codex loads \${legacyLoaded.length} Claude Code FlowRail hook(s) (\${legacyLoaded.map((h) => h.sourcePath || h.source).join(', ')}) — they would block every apply_patch; remove them\`);
+  }
+  if (elsewhere > 0) warn(\`\${elsewhere} FlowRail hook(s) are configured outside this project (user or managed config); Codex runs those as well\`);
+  const phases = Object.keys(PLACEMENT);
+  const loaded = phases.flatMap((p) => project[p] ?? []);
+  if (loaded.length === 0) {
+    readiness = 'needs-project-trust';
+    warn('Codex does not load this project\\'s FlowRail hooks yet: open the repo in Codex and trust the project');
+  } else {
+    let localReal = path.join(root, '.codex/hooks.json');
+    try {
+      localReal = fs.realpathSync.native(localReal);
+    } catch {}
+    const sources = [...new Set(loaded.map((h) => h.sourcePath).filter(Boolean))];
+    if (sources.some((src) => src !== localReal)) {
+      warn(\`Codex loads this project's hooks from \${sources.join(', ')} (a linked worktree loads the main checkout's), not this checkout's file — readiness is for what Codex loads\`);
+    }
+    let wrong = false;
+    for (const p of phases) {
+      const entries = project[p] ?? [];
+      if (entries.length !== 1) {
+        wrong = true;
+        fail(\`Codex loads \${entries.length} FlowRail \${p} hooks from this project (expected exactly 1, under the right event and matcher) — re-run \${REINIT}\`);
+        continue;
+      }
+      const h = entries[0];
+      if (h.pin !== version) {
+        wrong = true;
+        fail(\`the \${p} hook Codex loads runs @flowrail/hook@\${h.pin}, not the \${version} this check verified — re-run \${REINIT}\`);
+      }
+      if (h.async === true) {
+        wrong = true;
+        fail(\`the \${p} hook Codex loads is asynchronous — Codex runs it without waiting, so it cannot block anything — re-run \${REINIT}\`);
+      }
+      if (typeof h.timeoutSec === 'number' && h.timeoutSec < TIMEOUTS[p]) {
+        wrong = true;
+        fail(\`the \${p} hook Codex loads times out after \${h.timeoutSec}s (needs at least \${TIMEOUTS[p]}s; a Codex timeout lets the action through) — re-run \${REINIT}\`);
+      }
+    }
+    if (wrong) readiness = 'configured';
+    else if (loaded.some((h) => h.enabled === false)) {
+      readiness = 'disabled';
+      warn('a FlowRail hook is disabled in Codex: re-enable it with /hooks');
+    } else if (loaded.some((h) => h.trustStatus !== 'trusted')) {
+      readiness = 'needs-handler-approval';
+      warn(\`Codex has not approved every FlowRail hook (\${loaded.filter((h) => h.trustStatus === 'trusted').length}/4 trusted): run /hooks in Codex and approve them\`);
+    } else {
+      readiness = 'active';
+      ok('Codex loads, trusts and enables all four FlowRail hooks, as installed');
+    }
+  }
+}
+if (incompatible) readiness = 'incompatible-version';
+if (failures > 0 && readiness === 'active') readiness = 'configured';
+
+console.log(\`FlowRail for Codex readiness: \${readiness}\`);
+process.exit(failures > 0 ? 1 : 0);
+`;
+}
+function writeCodexDoctorScript(projectRoot, version = codex_target_1.CODEX_HOOK_VERSION) {
+    const target = path_1.default.join(projectRoot, exports.CODEX_DOCTOR_FILENAME);
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    fs_1.default.writeFileSync(target, renderCodexDoctorScript(version), 'utf8');
+}