ruvnet-brain 4.0.35 → 4.0.90-dev

package/plugin/mcp/server.mjs

@@ -33,6 +33,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline';
+import { writeOwn as writeOwnReadiness } from '../scripts/mcp-readiness.mjs';
 import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
@@ -66,12 +67,16 @@ const clientOk = (id, result) => out({ jsonrpc: '2.0', id, result });
 const clientErr = (id, code, message) => out({ jsonrpc: '2.0', id, error: { code, message } });
 const readJSON = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
 
+/**
+ * ISSUE #133 (second half). This used to write ONE shared file, last writer wins — so a second MCP
+ * shell's `degraded` overwrote this one's `ready`, and `--doctor` reported the state of whichever
+ * process wrote last as the state of the machine. A process now owns only its own record; the
+ * machine-level answer is DERIVED from the live ones by mcp-readiness.mjs. Same fix as everything
+ * else closed today: one producer per fact.
+ */
 function writeReadiness(value) {
   try {
-    fs.mkdirSync(BRAIN_HOME, { recursive: true });
-    const tmp = `${READINESS}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, `${JSON.stringify({ ...value, pid: process.pid, at: new Date().toISOString() })}\n`, { mode: 0o600 });
-    fs.renameSync(tmp, READINESS);
+    writeOwnReadiness(BRAIN_HOME, value);
   } catch (error) {
     console.error(`[ruvnet-brain] could not persist MCP readiness: ${error.message}`);
   }
@@ -194,11 +199,23 @@ async function ensureChild() {
         const waiter = c.pending.get(msg.id);
         if (waiter) { c.pending.delete(msg.id); waiter.resolve(msg); }
       });
-      proc.on('exit', () => {
+      proc.on('exit', (code, signal) => {
         if (child === c) child = null;
         for (const [, p] of c.pending) p.reject(new Error('brain worker exited'));
         c.pending.clear();
-        if (!c.intentionalStop) {
+        // A CLEAN EXIT IS NOT A CRASH (issue #133, the sibling of the #122 idle-exit fix).
+        //
+        // #122 gave the worker a 15-minute idle retirement so a quiet session stops holding 3-15GB.
+        // It exits deliberately, with process.exit(0). This handler only knew about
+        // `intentionalStop`, which the PARENT sets when IT kills the child — so the worker retiring
+        // ITSELF was recorded as `degraded / worker-exit … exited unexpectedly`, and --doctor then
+        // exited 1 on a machine where nothing was wrong and the next search would respawn it by
+        // design. A fix that frees memory should not make the product report itself broken.
+        //
+        // Exit 0 with no signal is a deliberate stop — the idle retirement, or stdin EOF when the
+        // host goes away. A crash carries a non-zero code or a signal, and still degrades.
+        const cleanExit = code === 0 && !signal;
+        if (!c.intentionalStop && !cleanExit) {
           writeReadiness({
             state: 'degraded', phase: 'worker-exit', generation: c.generation,
             elapsedMs: Date.now() - startedAt, retryable: true,

package/plugin/scripts/adr-currency-gate.mjs

@@ -0,0 +1,150 @@
+/**
+ * adr-currency-gate.mjs — the ADR check, moved from the LAST possible moment to the FIRST.
+ *
+ * WHAT HAPPENED, 2026-08-13. Three commits touched code governed by ADR-055, 065, 066 and 067. All
+ * four ADRs were left describing a world the code had left. The pre-push gate caught it and refused
+ * — correctly, and it is a good gate. But look at WHEN: after the files were written, after three
+ * commits, after I had moved on. By then the work read as a toll booth, and my own words for it were
+ * "real work I skipped". The owner quoted that line back at me as the exhibit, and he was right to.
+ *
+ * A gate at push time cannot shape the work; it can only penalise it afterwards. Worse, it TRAINS
+ * the behaviour it exists to stop — if the wall is at the end, the cheap move is always to run at it
+ * and let it sort you out. The instinct the owner keeps asking for is not something exhortation can
+ * install; it is what you get when the right action is the only action available at the moment of
+ * acting.
+ *
+ * SO THIS FIRES ON THE EDIT, AND IT REFUSES DEBT RATHER THAN CHANGE. It does NOT ask you to document
+ * an edit you have not made yet — that would be incoherent. It refuses to let you write MORE code
+ * governed by a document that is ALREADY stale from your last round. One unreconciled ADR is a
+ * conversation; four is the mess that shipped today.
+ *
+ * REUSED, NOT REIMPLEMENTED. Every verdict comes from `scripts/doc-currency.mjs` — the same
+ * `evaluateDoc`/`resolveGoverned` the pre-push gate calls. A second implementation of "is this ADR
+ * current" would be one fact restated in two places, which is the defect this repo has paid for at
+ * least five times (orgTotalApprox in two producers, seven store-root expressions, a hand-listed
+ * import graph in four fixtures, two ship-command definitions shipped disagreeing on day one).
+ *
+ * FAIL OPEN, ALWAYS. Not a git repo, unreadable doc, git unavailable, anything unexpected: ALLOW,
+ * silently. An adversarial review earlier today found a sibling hook turning a missing `sqlite3`
+ * into a confident claim that the memory store was corrupt. A gate that fabricates a reason is worse
+ * than no gate, because it spends the credibility every other gate is drawing on.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..', '..');
+
+/** States that mean "the code moved and nobody has reconciled the document since". */
+const STALE = new Set(['presumed-stale']);
+
+/**
+ * Which documents govern this file, and are they current?
+ *
+ * Only the ADRs that actually govern the edited path are evaluated — `evaluate()` walks 83 documents
+ * with git calls per document, which is fine for a pre-push gate and far too slow for something on
+ * the Write path. Same logic, narrower question.
+ */
+/**
+ * doc-currency lives OUTSIDE the payload, and that is correct rather than an oversight worked
+ * around. `plugin/` is what reaches a user (marketplace.json `"source": "./plugin"`), a user's
+ * install has no `docs/adr/`, and a gate about THIS repo's ADRs has nothing to say there. A static
+ * `import('../../scripts/doc-currency.mjs')` would have shipped a specifier that resolves only in a
+ * checkout and throws ERR_MODULE_NOT_FOUND on every real install — the exact defect ADR-065 exists
+ * to stop, which `payload-self-contained.test.mjs` caught in the very commit citing ADR-065.
+ *
+ * So the dependency is resolved at runtime and its ABSENCE IS A CLEAN SKIP, not an error: outside a
+ * checkout this gate simply has no opinion.
+ */
+async function loadDocCurrency(root) {
+  const p = path.join(root, 'scripts', 'doc-currency.mjs');
+  if (!fs.existsSync(p)) return null;
+  try { return await import(pathToFileURL(p).href); } catch { return null; }
+}
+
+export async function staleGovernorsOf(relPath, { root = REPO, docCurrency = null, readFile = null } = {}) {
+  const mod = docCurrency ?? await loadDocCurrency(root);
+  if (!mod) return [];
+  const { listDocs, evaluateDoc, parseFrontmatter, DEFAULT_DIRS, isGitRepo } = mod;
+  // `readFile` is injectable for one reason, and it is not tidiness: with `fs.readFileSync` hardcoded
+  // here, a test that injects `listDocs`/`parseFrontmatter` never reaches them — the read throws on a
+  // fixture path that does not exist, the loop `continue`s, and NO CANDIDATE IS EVER FOUND. The first
+  // mutation run of this file reported "STALE ADR -> DID NOT FIRE", while all three allow-cases
+  // passed. A suite of only allow-cases would have shipped this green and unfireable, which is the
+  // exact defect class this repo has now hit four times in one day.
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
+  if (!isGitRepo(root)) return [];
+
+  // TWO PASSES, AND THE ORDER IS THE WHOLE DESIGN. Measured before writing it, not after:
+  // `evaluateDoc` costs ~190-240ms because it shells out to git, and there are 83 documents — a
+  // naive loop is ~19 SECONDS on the Write path, which would make this the gate everybody disables.
+  // Reading frontmatter for all 83 costs 40ms total. So: cheap pass to find WHICH documents govern
+  // this file (usually one), expensive pass on only those. ~250ms typical, and exactly 40ms for the
+  // overwhelmingly common case of a file no ADR governs.
+  const candidates = [];
+  for (const docRel of listDocs(root, DEFAULT_DIRS)) {
+    let fm;
+    try { fm = parseFrontmatter(read(path.join(root, docRel))); } catch { continue; }
+    const governs = fm?.keys?.governs;
+    if (!Array.isArray(governs)) continue;
+    // Entries are exact paths or directory prefixes, read the way the pre-push gate reads them.
+    const governsThis = governs.some((p) => typeof p === 'string'
+      && (relPath === p || relPath.startsWith(p.endsWith('/') ? p : `${p}/`)));
+    if (governsThis) candidates.push({ docRel, id: fm?.keys?.id ?? path.basename(docRel) });
+  }
+  if (!candidates.length) return [];
+
+  const out = [];
+  for (const c of candidates) {
+    let doc;
+    try { doc = evaluateDoc(root, c.docRel); } catch { continue; }
+    if (STALE.has(doc?.drift?.state)) out.push({ doc: c.docRel, id: c.id, why: doc?.drift?.why ?? '' });
+  }
+  return out;
+}
+
+export function refusalText(relPath, stale) {
+  const names = stale.map((s) => `${s.id} (${s.doc})`).join('\n           ');
+  return `⛔ BLOCKED — ${relPath} is governed by a document that is ALREADY stale.
+
+  stale:   ${names}
+
+Reconcile it BEFORE writing more of what it governs. Not because the rule says so, but because
+this is the moment the reconciliation is cheap: you still remember what changed and why. On
+2026-08-13 four ADRs went stale together and the pre-push gate caught them after three commits,
+when the work read as a toll booth and got called "real work I skipped".
+
+  1. add a Currency-log row to the document: what changed, and why, with referents
+  2. \`node scripts/doc-currency.mjs --fix\` backfills only the dates git can prove
+  3. status, and every claim in the row, is yours to make — no script may write it
+
+An ADR describing a world the code left is worse than no ADR: the next reader trusts it.`;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  // Every failure path below ALLOWS. This gate may never be the reason work cannot proceed for a
+  // reason it cannot explain.
+  let allow = 0;
+  try {
+    const payload = fs.readFileSync(0, 'utf8');
+    const input = JSON.parse(payload)?.tool_input ?? {};
+    const file = input.file_path || input.path || '';
+    if (!file) process.exit(allow);
+    const rel = path.relative(REPO, path.resolve(file));
+    // Edits OUTSIDE the repo, and edits to the documents themselves, are never blocked — the second
+    // exemption is essential: reconciling a stale ADR must not be refused by the staleness it fixes.
+    if (rel.startsWith('..') || rel.startsWith('docs/')) process.exit(allow);
+    const stale = await staleGovernorsOf(rel);
+    if (!stale.length) process.exit(allow);
+    process.stderr.write(`${refusalText(rel, stale)}\n`);
+    process.exit(2);
+  } catch {
+    process.exit(allow);
+  }
+}

package/plugin/scripts/capability-registry.mjs

@@ -244,13 +244,22 @@ function lineCount(file) {
  */
 export function dispatchGateWiring({ repo = REPO, home = HOME } = {}) {
   const PREIMAGE = new Set(['plugin', 'marketplace-clone']);
+  // 'codex' joined hook-registry.mjs's mesh 2026-08-20 (Dream Cycle cross-host-conformance) so M1/
+  // M3/M5/M6 could see codex-hooks.json — but this function asks a CLAUDE CODE question ("is a
+  // PreToolUse gate on subagent dispatch wired to the cheap-model router" for THIS session), and
+  // Claude Code never loads codex-hooks.json under any circumstance. Without this exclusion, a
+  // resolved codex route-dispatch registration (now correctly matched to route-dispatch.sh via the
+  // shared shim table) reported `wired: true` on a machine that had never installed Codex at all —
+  // caught by re-running this function before/after the hook-registry.mjs change.
+  const NOT_CLAUDE_CODE = new Set(['codex']);
   let records;
   try { records = buildRegistry({ repo, home }).records; }
   catch { return { wired: false, layer: null, unreadable: true }; }
   const hits = records.filter((r) => r.event === 'PreToolUse'
     && r.handler === 'route-dispatch.sh'
     && r.tools.some((t) => t === 'Task' || t === 'Agent' || t === '*')
-    && !PREIMAGE.has(r.layer));
+    && !PREIMAGE.has(r.layer)
+    && !NOT_CLAUDE_CODE.has(r.layer));
   const external = hits.find((r) => r.layer !== 'plugin-installed');
   if (external) return { wired: true, layer: external.layer, unreadable: false };
   const enabled = Object.entries(readJSON(path.join(home, '.claude/settings.json')).value?.enabledPlugins || {})

package/plugin/scripts/codex-hook-adapter.mjs

@@ -1,4 +1,32 @@
 #!/usr/bin/env node
+/**
+ * codex-hook-adapter.mjs — the host boundary. Codex payloads in, shared Brain hook bodies out, and
+ * Codex-VALID output back.
+ *
+ * THE OUTPUT CONTRACT IS NOT GUESSED. Every rule below was read out of the real host: the JSON
+ * schemas Codex 0.147.0 carries inside its own binary — `<event>.command.output`, extracted
+ * 2026-08-14 with `strings` from
+ * `~/.codex/packages/standalone/releases/0.147.0-aarch64-apple-darwin/bin/codex` — plus the host's
+ * own error strings. The three that shaped this file:
+ *
+ *   · "hook returned invalid post-tool-use JSON output"  — PostToolUse stdout is PARSED. Plain text
+ *     is a host error, not a message. signal-watch.mjs prints one advisory LINE on a failed
+ *     gh/vercel/npm command, which reached Codex as invalid JSON on every such command, and nothing
+ *     in this file wrapped it: the old envelope branch covered SessionStart and UserPromptSubmit
+ *     only. Measured before the fix: raw text passed straight through.
+ *   · The events that may carry `hookSpecificOutput.additionalContext` are exactly the ones with a
+ *     *HookSpecificOutputWire definition — PreToolUse, PostToolUse, PermissionRequest, SessionStart,
+ *     SubagentStart, UserPromptSubmit. `session-end.command.output` DOES NOT EXIST, and
+ *     pre-compact/post-compact/stop/subagent-stop have no additionalContext at all. So for those,
+ *     unparseable stdout is DROPPED. Wrapping it would trade a silent no-op for a host error.
+ *   · "PreToolUse hook returned unsupported permissionDecision:allow" / ":ask" — the wire enum has
+ *     three values and Codex accepts exactly one of them, `deny`. Anything else is stripped, which
+ *     is why the pre-existing `defer` strip is now a general rule rather than one special case.
+ *
+ * Exit-2-plus-stderr is the refusal channel on every blocking event ("PreToolUse hook exited with
+ * code 2 but did not write a blocking reason to stderr" is the host's complaint when the stderr half
+ * is missing), so a non-zero status is forwarded verbatim and never reinterpreted.
+ */
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -13,8 +41,27 @@ const event = String(input.hook_event_name || '');
 let adapted = false;
 const codexToolName = String(input.tool_name).toLowerCase();
 
+/**
+ * Events whose output schema defines a *HookSpecificOutputWire with `additionalContext`. Only these
+ * may carry a hook's prose back to the model.
+ */
+const CONTEXT_EVENTS = new Set([
+  'PreToolUse', 'PostToolUse', 'PermissionRequest', 'SessionStart', 'SubagentStart', 'UserPromptSubmit',
+]);
+
+/** Every file an apply_patch touches, in patch order. Codex patches are routinely multi-file. */
+export function patchFiles(patch) {
+  const out = [];
+  for (const m of String(patch || '').matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)) {
+    const f = m[1].trim();
+    if (f && !out.includes(f)) out.push(f);
+  }
+  return out;
+}
+
 // Codex names these tools differently from the shared Claude hook contracts. Normalize at the
 // host boundary once so every existing safety/learning body sees the same typed event.
+let files = [];
 if (['exec_command', 'functions.exec_command', 'functions__exec_command'].includes(codexToolName)) {
   input.tool_name = 'Bash';
   input.tool_input = {
@@ -24,11 +71,11 @@ if (['exec_command', 'functions.exec_command', 'functions__exec_command'].includ
   adapted = true;
 } else if (codexToolName === 'apply_patch') {
   const patch = typeof input.tool_input?.command === 'string' ? input.tool_input.command : '';
-  const filePath = patch.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/m)?.[1]?.trim() || '';
+  files = patchFiles(patch);
   input.tool_name = 'Edit';
   input.tool_input = {
     ...(input.tool_input || {}),
-    ...(filePath ? { file_path: filePath } : {}),
+    ...(files[0] ? { file_path: files[0] } : {}),
     new_string: patch,
   };
   adapted = true;
@@ -51,40 +98,95 @@ const env = {
   CLAUDE_PROJECT_DIR: String(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd()),
   RUVNET_HOOK_HOST: 'codex',
 };
-const result = spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
-  input: hookInput,
-  encoding: 'utf8',
-  env,
+
+const runShim = (payload) => spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
+  input: payload, encoding: 'utf8', env,
 });
 
-if (result.status && result.stderr) process.stderr.write(result.stderr);
-if (result.status) process.exit(result.status);
+/**
+ * ONE PAYLOAD PER FILE for a multi-file patch.
+ *
+ * Every write policy on both hosts reads a single `tool_input.file_path` (protect-brain-state.sh
+ * line 56, ground-before-write.sh line 109, adr-currency-gate.mjs line 137). A Codex `apply_patch`
+ * carries N files in one call, so exposing only the first meant files 2..N were never shown to any
+ * wall — the same shape as every other defect in this area: the check exists and points one surface
+ * away from the failure.
+ *
+ * BOUNDED, because the wrapper SIGKILLs this process at its own budget and a kill is invisible. The
+ * wrapper hands its budget down; iteration stops at 75% of it and ALLOWS, which is decision-gate's
+ * own rule for a blown budget ("a blown budget ALLOWS and says nothing"): the gate's slowness must
+ * never be indistinguishable from the user doing something wrong.
+ */
+const BUDGET_MS = Number(process.env.RUVNET_CODEX_BUDGET_MS) || 0;
+const started = Date.now();
+const spent = () => Date.now() - started;
+
+const payloads = files.length > 1
+  ? files.map((file) => JSON.stringify({
+    ...input,
+    tool_input: { ...input.tool_input, file_path: file },
+  }))
+  : [hookInput];
 
-const stdout = result.stdout || '';
-if (!stdout) process.exit(0);
+const stdouts = [];
+for (const payload of payloads) {
+  const r = runShim(payload);
+  // A refusal (or any error) from ANY file is the decision for the whole patch, forwarded verbatim
+  // and immediately — there is nothing to compose once one wall has said no.
+  if (r.status && r.stderr) process.stderr.write(r.stderr);
+  if (r.status) process.exit(r.status);
+  if (r.stdout) stdouts.push(r.stdout);
+  if (BUDGET_MS && spent() > BUDGET_MS * 0.75) break;
+}
+
+if (!stdouts.length) process.exit(0);
+
+/** Merge N bodies' output into ONE value. Envelopes join by context; anything else joins as text. */
+function merge(outs) {
+  if (outs.length === 1) return outs[0];
+  const parsedAll = outs.map((s) => { try { return JSON.parse(s); } catch { return null; } });
+  const contexts = parsedAll.map((p) => p?.hookSpecificOutput?.additionalContext);
+  if (parsedAll.every((p) => p) && contexts.every((c) => typeof c === 'string')) {
+    const first = parsedAll[0];
+    return JSON.stringify({
+      ...first,
+      hookSpecificOutput: { ...first.hookSpecificOutput, additionalContext: contexts.join('\n') },
+    });
+  }
+  return outs.map((s) => s.trim()).filter(Boolean).join('\n');
+}
+
+const stdout = merge(stdouts);
 
 let parsed = null;
-try { parsed = JSON.parse(stdout); } catch { /* plain text is valid for some Codex events */ }
+try { parsed = JSON.parse(stdout); } catch { /* a shared body may legitimately print prose */ }
 
 if (event === 'Stop') {
   const reason = parsed?.hookSpecificOutput?.additionalContext
     || parsed?.reason
     || parsed?.stopReason;
+  // `stop.command.output` has no hookSpecificOutput; `decision: "block"` REQUIRES a non-empty
+  // `reason` ("Stop hook returned decision:block without a non-empty reason"). No reason ⇒ say
+  // nothing at all, which is the allow.
   if (reason) process.stdout.write(JSON.stringify({ decision: 'block', reason }));
   process.exit(0);
 }
 
-if ((event === 'SessionStart' || event === 'UserPromptSubmit') && !parsed) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: event,
-      additionalContext: stdout,
-    },
-  }));
+if (!parsed) {
+  // Prose from a shared body. It is only deliverable on an event whose schema has somewhere to put
+  // it; everywhere else it is dropped rather than emitted as output the host will reject.
+  if (CONTEXT_EVENTS.has(event)) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: event, additionalContext: stdout },
+    }));
+  }
   process.exit(0);
 }
 
-if (parsed?.hookSpecificOutput?.permissionDecision === 'defer') {
+// `deny` is the only permissionDecision Codex accepts; `allow`, `ask` and the shared bodies' own
+// `defer` are all rejected by name. Strip, then drop an envelope that has nothing left to say.
+const decision = parsed?.hookSpecificOutput?.permissionDecision;
+if (decision && decision !== 'deny') {
   delete parsed.hookSpecificOutput.permissionDecision;
   if (Object.keys(parsed.hookSpecificOutput).length === 1 && parsed.hookSpecificOutput.hookEventName) {
     delete parsed.hookSpecificOutput;

package/plugin/scripts/codex-hook-wrapper.mjs

@@ -2,13 +2,18 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
 const brainHome = process.env.RUVNET_BRAIN_HOME
   || path.join(path.dirname(codexHome), '.cache', 'ruvnet-brain');
 const versions = path.join(brainHome, 'versions');
 const blockingHooks = new Set([
+  // decision-gate composes every refusal policy into ONE verdict and speaks the same exit-2 +
+  // stderr contract Codex documents ("PreToolUse hook exited with code 2 but did not write a
+  // blocking reason to stderr"). Absent from this set it would be wired and toothless: the exit 2
+  // would be swallowed here and every refusal would silently become an allow.
+  'decision-gate',
   'route-dispatch',
   'hijack-ruvnet',   // ADR-063: opt-in managed-memory refusal; exits 0 at the default
   'ground-before-write',
@@ -17,10 +22,38 @@ const blockingHooks = new Set([
   'unprompted-speech',
 ]);
 
+/**
+ * HOOKS WHOSE WORK OUTLIVES ANY BUDGET THE HOST WILL GRANT, so waiting for them is not an option.
+ *
+ * MEASURED 2026-08-14 on a live Codex 0.147.0 session — the host prints it itself:
+ *
+ *     warning: clamping SessionEnd hook timeout to 3s in .../hooks.json
+ *
+ * SessionEnd is HARD-CAPPED at 3 seconds and no registration can ask for more. learn-flush needs
+ * 18s: measured with a real 10-entry queue and the real `ruflo`, 18342 / 18347 / 18384 ms, because
+ * one `ruflo hooks` call alone costs seconds and it self-bounds at LEARN_FLUSH_DEADLINE_MS.
+ *
+ * So the arithmetic never closes, and what shipped was the worst version of that: this wrapper
+ * budgeted 2250ms, SIGKILLed the flush, and exited 0 with `status === null` — measured end to end,
+ * exit 0, 2760ms, ZERO bytes of stdout, ZERO bytes of stderr, and a 10-line queue still 10 lines
+ * afterwards. Codex lessons never flushed, on every session, and nothing on any surface said so.
+ *
+ * The host caps how long it will WAIT, not how long work may take. Detaching honours the cap
+ * exactly — the hook returns immediately — while the flush runs to its own deadline and does its
+ * own write-back. Raising the number instead would have been a fiction the host silently clamps.
+ */
+const DETACHED_HOOKS = new Set(['learn-flush']);
+
+/** THE BUDGET IS DERIVED FROM WHAT THE HOOK MEASURABLY COSTS, never from what looks tidy. */
 function timeoutFor(hookId) {
   const override = Number(process.env.RUVNET_CODEX_HOOK_TIMEOUT_MS);
   if (Number.isFinite(override) && override > 0) return override;
-  if (hookId === 'learn-flush') return 2_250;
+  // decision-gate's own internal budget is 4000ms (RUVNET_DECISION_BUDGET_MS) and it is allowed to
+  // spend all of it: measured 986–4015ms across ten runs in a project this plugin does not own. A
+  // budget at or below the gate's own would make the gate's slowest legitimate refusal indis-
+  // tinguishable from a crash; 6000ms covers the gate's cap plus this chain's spawn overhead
+  // (measured 773–1145ms end-to-end warm, so ~150–400ms of that is the wrapper/adapter/shim).
+  if (hookId === 'decision-gate') return 6_000;
   if (hookId === 'ground-ruvnet' || hookId === 'unprompted-speech' || hookId === 'continuation-gate') {
     return 8_500;
   }
@@ -119,11 +152,35 @@ const adapter = root && path.join(root, 'scripts', 'codex-hook-adapter.mjs');
 if (!adapter || !fs.existsSync(adapter)) process.exit(0);
 
 const hookId = process.argv[2] || '';
+
+if (DETACHED_HOOKS.has(hookId)) {
+  // stdio ignored on purpose: a detached child outlives this process, so anything it wrote would
+  // arrive at a host that has already moved on — and stderr from a hook is what a host renders as a
+  // hook error. It reports through its own channels or not at all.
+  const child = spawn(process.execPath, [adapter, ...process.argv.slice(2)], {
+    detached: true, stdio: ['pipe', 'ignore', 'ignore'], env: process.env,
+  });
+  child.unref();
+  child.stdin.on('error', () => { /* a dead optional child must never surface to the host */ });
+  // AWAIT THE FLUSH, don't assume it. `process.exit()` on the line after `end()` truncates the pipe
+  // and the detached child reads an empty payload — which is the same silent no-op this whole change
+  // exists to remove, reintroduced one layer down. Bounded so a stuck pipe cannot hold the host.
+  await new Promise((resolve) => {
+    try { child.stdin.end(input, resolve); } catch { resolve(); }
+    setTimeout(resolve, 250);
+  });
+  process.exit(0);
+}
+
+const budgetMs = timeoutFor(hookId);
 const result = spawnSync(process.execPath, [adapter, ...process.argv.slice(2)], {
   input,
   encoding: 'utf8',
-  env: process.env,
-  timeout: timeoutFor(hookId),
+  // The adapter may fan one multi-file patch out into several body runs, and only this process knows
+  // when the axe falls. Hand the budget down so it can stop and fail open instead of being killed
+  // mid-loop with nothing written — a SIGKILL here is invisible to the host and to the user.
+  env: { ...process.env, RUVNET_CODEX_BUDGET_MS: String(budgetMs) },
+  timeout: budgetMs,
   killSignal: 'SIGKILL',
 });