ruvnet-brain 4.3.40 → 4.4.1

package/scripts/hook-qualify-core.mjs

@@ -0,0 +1,346 @@
+// hook-qualify-core.mjs — the pure + process-boundary parts of the hook qualification harness.
+//
+// WHY THIS EXISTS. A hook that writes to stderr, exits non-zero, prints a malformed envelope or
+// outlives its timeout is surfaced to the user as a "hook error". That is the failure that makes
+// people switch the product off, so every registered hook is qualified against the HOST contract,
+// not against its own header comment.
+//
+// NOTHING IS HAND-LISTED. The hooks come from plugin/hooks/hooks.json (Claude Code, and Grok through
+// its Claude-compat layer) and plugin/hooks/codex-hooks.json (Codex); the hook's mode from
+// hook-shim.mjs's TABLE (plugin/scripts/hook-registry.mjs parses it); the payload shapes from REAL
+// captures of each host (tests/fixtures/hook-payloads/<host>/, provenance recorded inside each file).
+//
+// What the EXISTING tests already prove (hook-registry-lint, hook-contract, hook-hardening,
+// hook-battery, hook-shim*, codex-*-parity, codex-lifecycle-hooks) is registry shape, per-hook unit
+// behaviour and Codex envelope translation. What they do not do — and this does — is run EVERY
+// registered command, exactly as the host would, through the adverse-input matrix with the host's
+// own exit/stdout/stderr/timeout contract as the oracle.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { shimIdIn, codexDispatchIdIn, shimTable, matchedTools, REPO } from '../plugin/scripts/hook-registry.mjs';
+
+export const HOSTS = ['claude', 'codex', 'grok'];
+/** Hosts clamp some events below the registered timeout (Codex prints "clamping SessionEnd hook timeout to 3s"). */
+export const HOST_CAP_SEC = { codex: { SessionEnd: 3 }, claude: {}, grok: {} };
+/** A hook must finish inside this fraction of its effective timeout on an idle machine. */
+export const TIMEOUT_MARGIN = 0.6;
+
+// ── registry ─────────────────────────────────────────────────────────────────────────────────────
+export function registrations(root = REPO, hosts = HOSTS) {
+  const table = shimTable(root);
+  const out = [];
+  for (const host of hosts) {
+    const file = path.join(root, 'plugin', 'hooks', host === 'codex' ? 'codex-hooks.json' : 'hooks.json');
+    const hooks = JSON.parse(fs.readFileSync(file, 'utf8')).hooks || {};
+    for (const [event, groups] of Object.entries(hooks)) {
+      for (const g of groups) for (const h of g.hooks || []) {
+        const hookId = host === 'codex' ? codexDispatchIdIn(h.command) : shimIdIn(h.command);
+        const tail = (host === 'codex' ? /"\s+\d+\s+\S+\s*(.*)$/ : /hook-shim\.mjs["'`]?\s+\S+\s*(.*?)(?:\s*\|\|\s*true)?\s*$/).exec(h.command)?.[1]?.trim() || '';
+        const mode = table[hookId]?.mode || 'unknown';
+        const cap = HOST_CAP_SEC[host]?.[event];
+        out.push({ host, event, matcher: g.matcher ?? '*', command: h.command, timeoutSec: h.timeout, effectiveSec: cap ? Math.min(h.timeout, cap) : h.timeout,
+          hookId, args: tail, mode, body: table[hookId], label: `${host}/${event}/${hookId}${tail ? ` ${tail}` : ''}` });
+      }
+    }
+  }
+  return out;
+}
+
+// ── fixtures (REAL host captures, tokenised) ─────────────────────────────────────────────────────
+const FIXDIR = (root, host) => path.join(root, 'tests', 'fixtures', 'hook-payloads', host);
+// MEASURED (grok 1.0.13, tests: scratch probe 4): a registered matcher written with Claude tool names fires on Grok's
+// native `write` tool (matchers `Write` and the plugin's ^(Write|...)$ fired; the native spelling ^write$ did NOT), so Grok
+// matches against the Claude-name alias while the payload keeps the native name. Only that one pair was measured.
+const GROK_ALIAS = { write: 'Write' };
+// Grok sends snake_case event names (`pre_tool_use`); the registry speaks Claude's PascalCase.
+const pascal = (e) => String(e).split('_').map((x) => x[0].toUpperCase() + x.slice(1)).join('');
+const eventOf = (host, p) => (host === 'grok' ? pascal(p.hook_event_name) : p.hook_event_name);
+export function fixturesFor(reg, root = REPO) {
+  const dir = FIXDIR(root, reg.host);
+  const all = fs.readdirSync(dir).map((f) => ({ name: f.replace(/\.json$/, ''), ...JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) }));
+  const ofEvent = all.filter((f) => eventOf(reg.host, f.payload) === reg.event);
+  if (!/ToolUse$/.test(reg.event) && ofEvent.length) return ofEvent;
+  // DERIVED (labelled) fixtures: an event or tool no capture exercised.
+  if (reg.event === 'PreCompact') {
+    const base = all.find((f) => eventOf(reg.host, f.payload) === 'SessionEnd');
+    return base ? [{ name: 'PreCompact-derived', _provenance: 'DERIVED from the captured SessionEnd payload + the documented PreCompact fields (trigger, custom_instructions); the host was not driven to compact', payload: { ...base.payload, hook_event_name: reg.host === 'grok' ? 'pre_compact' : 'PreCompact', trigger: 'manual', custom_instructions: '' } }] : [];
+  }
+  if (!/ToolUse$/.test(reg.event)) return [];
+  const re = new RegExp(reg.matcher);
+  const hits = ofEvent.filter((f) => re.test(reg.host === 'grok' ? (GROK_ALIAS[f.payload.tool_name] || f.payload.tool_name) : f.payload.tool_name));
+  if (hits.length) return hits;
+  const probe = 'mcp__ruvnet_brain__search_ruvnet';
+  if (re.test(probe) && ofEvent[0]) {
+    const p = { ...ofEvent[0].payload, tool_name: probe, tool_input: { query: 'what is ruflo' } };
+    if (reg.event === 'PostToolUse') p.tool_response = { content: [{ type: 'text', text: 'Searched 1 RuvNet repos (ruflo).\n#1  repo=ruflo\npath : ruflo/docs/x.md' }] };
+    return [{ name: `${reg.event}-derived-search_ruvnet`, _provenance: 'DERIVED from the captured shape of the same host/event; matcher selects a tool no capture exercised', payload: p }];
+  }
+  return [];
+}
+
+// ── world: an isolated HOME + cwd + TMPDIR, and (for Codex) an installed wrapper + active generation ─
+export function makeWorld(host, { root = REPO, label = 'qual' } = {}) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `hq-${label}-`)));
+  const w = { dir, home: path.join(dir, 'home'), cwd: path.join(dir, 'cwd'), tmp: path.join(dir, 'tmp'), host, root, n: 0 };
+  for (const d of [w.home, w.cwd, w.tmp]) fs.mkdirSync(d, { recursive: true });
+  spawnSync('git', ['init', '-q', '.'], { cwd: w.cwd, env: { ...process.env, HOME: w.home } });
+  const brain = path.join(w.home, '.cache', 'ruvnet-brain');
+  fs.mkdirSync(path.join(brain, 'versions'), { recursive: true });
+  fs.cpSync(path.join(root, 'plugin'), path.join(brain, 'versions', 'qual'), { recursive: true });
+  fs.writeFileSync(path.join(brain, 'active.json'), JSON.stringify({ generation: 'qual', version: 'qual', codeRoot: 'versions/qual' }));
+  if (host === 'codex') {
+    fs.copyFileSync(path.join(root, 'plugin', 'scripts', 'codex-hook-wrapper.mjs'), path.join(brain, 'codex-hook.mjs'));
+    fs.copyFileSync(path.join(root, 'plugin', 'scripts', 'development-maintenance.mjs'), path.join(brain, 'development-maintenance.mjs'));
+  }
+  return w;
+}
+export function worldEnv(w, extra = {}) {
+  const env = {};
+  for (const k of ['PATH', 'LANG', 'LC_ALL', 'SHELL', 'USER']) if (process.env[k] !== undefined) env[k] = process.env[k];
+  env.PATH = `${path.dirname(process.execPath)}${path.delimiter}${env.PATH || '/usr/bin:/bin'}`;
+  Object.assign(env, { HOME: w.home, USERPROFILE: w.home, TMPDIR: w.tmp, CLAUDE_PROJECT_DIR: w.cwd, RUVNET_BRAIN_HOME: path.join(w.home, '.cache', 'ruvnet-brain') });
+  if (w.host === 'codex') env.CODEX_HOME = path.join(w.home, '.codex');
+  else env.CLAUDE_PLUGIN_ROOT = path.join(w.root, 'plugin');
+  if (w.host === 'grok') env.GROK_PLUGIN_ROOT = path.join(w.root, 'plugin');
+  return Object.assign(env, extra);
+}
+export function cleanupWorld(w) {
+  try { spawnSync('chmod', ['-R', 'u+rwX', w.dir]); fs.rmSync(w.dir, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+function realise(fix, w) {
+  const sid = `qual-${process.pid}-${++w.n}`;
+  const transcript = path.join(w.home, '.claude', 'projects', 'p', `${sid}.jsonl`);
+  fs.mkdirSync(path.dirname(transcript), { recursive: true });
+  fs.writeFileSync(transcript, JSON.stringify({ type: 'user', message: { role: 'user', content: 'hi' } }) + '\n');
+  const s = JSON.stringify(fix.payload).split('{{TRANSCRIPT_DIR}}').join(transcript.replace(/\.jsonl$/, '')).split('{{TRANSCRIPT}}').join(transcript)
+    .split('{{ROOT}}').join(w.cwd).split('{{CWD}}').join(w.cwd).split('{{SESSION_ID}}').join(sid).split('{{PROMPT_ID}}').join('p1').split('{{TURN_ID}}').join('t1')
+    .split('{{TOOL_USE_ID}}').join('toolu_1').split('{{HOME}}').join(w.home);
+  const p = JSON.parse(s);
+  if (p.transcript_path === null) p.transcript_path = null;
+  return p;
+}
+
+// ── the contract (the ORACLE) ────────────────────────────────────────────────────────────────────
+const CLAUDE_TOP = new Set(['continue', 'stopReason', 'suppressOutput', 'systemMessage', 'decision', 'reason', 'hookSpecificOutput']);
+const CLAUDE_SPECIFIC = {
+  SessionStart: ['additionalContext', 'initialUserMessage', 'sessionTitle', 'watchPaths', 'reloadSkills'],
+  UserPromptSubmit: ['additionalContext', 'sessionTitle'],
+  PreToolUse: ['permissionDecision', 'permissionDecisionReason', 'updatedInput', 'additionalContext'],
+  PostToolUse: ['additionalContext', 'updatedToolOutput', 'updatedMCPToolOutput'],
+  Stop: ['additionalContext'], PreCompact: [], SessionEnd: [],
+};
+// Codex: read out of the host binary's own `<event>.command.output` schemas (codex-hook-adapter.mjs header).
+const CODEX_SPECIFIC = { SessionStart: ['additionalContext'], UserPromptSubmit: ['additionalContext'], PreToolUse: ['permissionDecision', 'permissionDecisionReason', 'additionalContext'],
+  PostToolUse: ['additionalContext', 'updatedToolOutput', 'updatedMCPToolOutput'] };
+const CODEX_TOP = new Set(['continue', 'stopReason', 'suppressOutput', 'systemMessage', 'terminalSequence', 'decision', 'reason', 'hookSpecificOutput']);
+
+/** Returns a list of contract violations for one stdout on one (host, event). Pure. */
+export function checkStdout(host, event, stdout, { eventNameChecked = true } = {}) {
+  const errs = [];
+  const text = stdout.toString('utf8');
+  if (!text.trim()) return errs;
+  if (/\u0000/.test(text)) errs.push('stdout contains a NUL byte');
+  const codex = host === 'codex';
+  if (event === 'SessionEnd' || (codex && event === 'PreCompact')) return [`${event} must write nothing to stdout (host discards or rejects it), wrote ${stdout.length} bytes`];
+  // `[RuvNet Brain — ...]` banners are plain text, so only `{` (or a `[` that really parses) is JSON.
+  const looksJson = /^\s*\{/.test(text) || (/^\s*\[/.test(text) && (() => { try { JSON.parse(text); return true; } catch { return false; } })());
+  if (!looksJson) {
+    if (!codex && (event === 'SessionStart' || event === 'UserPromptSubmit')) return errs;   // plain text is added as context
+    return [`stdout is plain text on ${host}/${event}, where the host requires a JSON envelope: ${JSON.stringify(text.slice(0, 60))}`];
+  }
+  let obj;
+  try { obj = JSON.parse(text); } catch (e) { return [`stdout is not ONE valid JSON value (${e.message.slice(0, 60)})`]; }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return ['stdout JSON is not an object'];
+  const top = codex ? CODEX_TOP : CLAUDE_TOP;
+  for (const k of Object.keys(obj)) if (!top.has(k)) errs.push(`unknown top-level field "${k}" for ${host}`);
+  if (obj.decision !== undefined) {
+    if (obj.decision !== 'block' && !(host !== 'codex' && obj.decision === 'approve')) errs.push(`decision "${obj.decision}" is not accepted on ${host}`);
+    if (obj.decision === 'block' && !(typeof obj.reason === 'string' && obj.reason.trim())) errs.push('decision:block without a non-empty reason');
+  }
+  if (codex && event === 'Stop' && Object.keys(obj).some((k) => k !== 'decision' && k !== 'reason' && k !== 'continue' && k !== 'stopReason' && k !== 'systemMessage' && k !== 'suppressOutput')) errs.push('Codex Stop has no hookSpecificOutput');
+  if (obj.hookSpecificOutput !== undefined) {
+    const hs = obj.hookSpecificOutput;
+    const allowed = (codex ? CODEX_SPECIFIC : CLAUDE_SPECIFIC)[event];
+    if (!hs || typeof hs !== 'object' || Array.isArray(hs)) errs.push('hookSpecificOutput is not an object');
+    else {
+      if (!allowed) errs.push(`${event} has no hookSpecificOutput on ${host}`);
+      if (eventNameChecked && hs.hookEventName !== event) errs.push(`hookSpecificOutput.hookEventName ${JSON.stringify(hs.hookEventName)} != ${event}`);
+      for (const k of Object.keys(hs)) if (k !== 'hookEventName' && !(allowed || []).includes(k)) errs.push(`unknown hookSpecificOutput field "${k}" for ${host}/${event}`);
+      if (codex && hs.permissionDecision !== undefined && hs.permissionDecision !== 'deny') errs.push(`Codex accepts only permissionDecision:"deny", got "${hs.permissionDecision}"`);
+      if (hs.additionalContext !== undefined && typeof hs.additionalContext !== 'string') errs.push('additionalContext is not a string');
+    }
+  }
+  return errs;
+}
+
+/** All contract violations for one run. Pure — this is what the guard proofs break. */
+export function judge(reg, caseName, r, { maxMs = null, mayBlock = false } = {}) {
+  const f = [];
+  const allowed = new Set([0]);
+  if (reg.mode === 'blocking' && mayBlock) allowed.add(2);
+  if (r.timedOut) f.push(`TIMEOUT: still running after ${r.ms}ms (registered ${reg.timeoutSec}s, effective ${reg.effectiveSec}s)`);
+  else if (r.signal) f.push(`killed by ${r.signal}`);
+  else if (!allowed.has(r.status)) f.push(`exit ${r.status} (allowed: ${[...allowed].join(',')}; a non-zero exit is shown to the user as a hook error)`);
+  if (r.stderr.length) f.push(`stderr not empty (${r.stderr.length} bytes): ${JSON.stringify(r.stderr.toString('utf8').slice(0, 120))}`);
+  if (!r.timedOut) f.push(...checkStdout(reg.host, reg.event, r.stdout, { eventNameChecked: caseName !== 'wrong-event-name' }));
+  const budget = maxMs ?? reg.effectiveSec * 1000 * TIMEOUT_MARGIN;
+  if (!r.timedOut && r.ms > budget) f.push(`SLOW: ${r.ms}ms > ${Math.round(budget)}ms (${TIMEOUT_MARGIN * 100}% of the ${reg.effectiveSec}s effective timeout)`);
+  return f;
+}
+
+/** Static contract checks that need no process. */
+export function staticFindings(regs) {
+  const f = [];
+  for (const r of regs) {
+    const cap = HOST_CAP_SEC[r.host]?.[r.event];
+    if (cap && r.timeoutSec > cap) f.push({ reg: r, msg: `registers timeout ${r.timeoutSec}s but ${r.host} clamps ${r.event} to ${cap}s and prints a warning on every session ("clamping ${r.event} hook timeout to ${cap}s")` });
+    if (r.host === 'codex') {
+      const inline = Number(/"\s+(\d+)\s+/.exec(r.command)?.[1]);
+      if (inline && inline >= r.effectiveSec * 1000) f.push({ reg: r, msg: `inline budget ${inline}ms is not inside the ${r.effectiveSec}s effective host timeout` });
+    }
+    if (r.mode === 'unknown') f.push({ reg: r, msg: `hook id "${r.hookId}" is not in hook-shim.mjs's TABLE` });
+  }
+  return f;
+}
+
+// ── process runner ───────────────────────────────────────────────────────────────────────────────
+const sandboxOk = process.platform === 'darwin' && fs.existsSync('/usr/bin/sandbox-exec');
+export const sandboxAvailable = () => sandboxOk;
+export const NET_DENY = '(version 1)(allow default)(deny network*)';
+export const writeProfile = (dir) => `(version 1)(allow default)(deny file-write* (require-all (require-not (subpath "${dir}")) (require-not (subpath "/dev"))) (with send-signal SIGKILL))`;
+
+/** Run one command string through /bin/sh as a host would. */
+export function runCommand(command, { cwd, env, stdin = '', stdinMode = 'pipe', timeoutMs, profile = null, argv = null }) {
+  return new Promise((resolve) => {
+    const [cmd, args] = profile ? ['/usr/bin/sandbox-exec', ['-p', profile, ...(argv || ['/bin/sh', '-c', command])]] : (argv ? [argv[0], argv.slice(1)] : ['/bin/sh', ['-c', command]]);
+    const t0 = Date.now();
+    const child = spawn(cmd, args, { cwd, env, stdio: [stdinMode === 'closed' ? 'ignore' : 'pipe', 'pipe', 'pipe'], detached: true });
+    const out = []; const err = []; let bytes = 0; let timedOut = false;
+    child.stdout.on('data', (d) => { if (bytes < 16e6) { out.push(d); bytes += d.length; } });
+    child.stderr.on('data', (d) => { if (bytes < 16e6) { err.push(d); bytes += d.length; } });
+    const timer = setTimeout(() => { timedOut = true; try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); } }, timeoutMs);
+    if (child.stdin) {
+      child.stdin.on('error', () => {});
+      if (stdinMode === 'held') child.stdin.write(stdin);          // one complete value, pipe left open
+      else child.stdin.end(stdin);
+    }
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { /* group already gone */ }
+      resolve({ status, signal: timedOut ? null : signal, stdout: Buffer.concat(out), stderr: Buffer.concat(err), ms: Date.now() - t0, timedOut });
+    });
+  });
+}
+
+const json = (o) => JSON.stringify(o);
+const promptKey = (p) => ('prompt' in p ? 'prompt' : null);
+function deadPid() { const r = spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))']); return Number(r.stdout.toString()); }
+function makeReadOnly(dir) {
+  const walk = (d) => { for (const e of fs.readdirSync(d, { withFileTypes: true })) { const p = path.join(d, e.name); if (e.isDirectory()) walk(p); else fs.chmodSync(p, 0o444); } fs.chmodSync(d, 0o555); };
+  walk(dir);
+}
+
+/** The adverse-input matrix. `stdin(payload)` -> string|Buffer. */
+export const CASES = [
+  { name: 'baseline-real', stdin: (p) => json(p) },
+  { name: 'empty-stdin', stdin: () => '' },
+  { name: 'closed-stdin', stdinMode: 'closed' },
+  { name: 'held-open-stdin', stdinMode: 'held', stdin: (p) => json(p) },
+  { name: 'malformed-json', stdin: () => '{"hook_event_name": nope, "prompt": ' },
+  { name: 'truncated-json', stdin: (p) => json(p).slice(0, Math.floor(json(p).length / 2)) },
+  { name: '5mb-payload', stdin: (p) => json({ ...p, ...(promptKey(p) ? { prompt: `${p.prompt} ${'x'.repeat(5 * 1024 * 1024)}` } : { padding: 'x'.repeat(5 * 1024 * 1024) }) }) },
+  { name: 'unicode-emoji', stdin: (p) => json({ ...p, ...(promptKey(p) ? { prompt: 'héllo 🚀 你好 ñ — ruflo agentdb ‮' } : { last_assistant_message: 'héllo 🚀 你好' }) }) },
+  { name: 'nul-bytes', stdin: (p) => Buffer.concat([Buffer.from(json({ ...p, ...(promptKey(p) ? { prompt: 'a\u0000b ruflo' } : {}) })), Buffer.from([0]), Buffer.from('\n')]) },
+  { name: 'missing-fields', stdin: () => '{}' },
+  { name: 'only-event-name', stdin: (p) => json({ hook_event_name: p.hook_event_name }) },
+  { name: 'wrong-types', stdin: (p) => json({ ...p, session_id: 123, prompt: null, cwd: {}, tool_input: 'x', transcript_path: 5, last_assistant_message: [] }) },
+  { name: 'wrong-event-name', stdin: (p) => json({ ...p, hook_event_name: p.hook_event_name === 'Stop' ? 'SessionStart' : 'Stop' }) },
+  { name: 'home-unset', stdin: (p) => json(p), env: (e) => { delete e.HOME; delete e.USERPROFILE; } },
+  { name: 'home-readonly', stdin: (p) => json(p), pre: (w) => makeReadOnly(w.home) },
+  { name: 'no-network', stdin: (p) => json(p), profile: NET_DENY, env: (e) => { e.HTTP_PROXY = e.HTTPS_PROXY = 'http://127.0.0.1:9'; e.NO_PROXY = ''; } },
+  { name: 'dead-pid-lock', stdin: (p) => json(p), pre: (w) => {
+    const pid = deadPid(); const brain = path.join(w.home, '.cache', 'ruvnet-brain'); const at = new Date().toISOString();
+    fs.mkdirSync(brain, { recursive: true });
+    fs.writeFileSync(path.join(brain, 'auto-update.lock'), JSON.stringify({ pid, at }) + '\n');
+    fs.mkdirSync(path.join(brain, '.update.lock'), { recursive: true });
+    fs.writeFileSync(path.join(brain, '.update.lock', 'owner.json'), JSON.stringify({ pid, at }));
+    fs.writeFileSync(path.join(w.cwd, '.cooldown'), at);
+  } },
+];
+
+/** Run one (registration, fixture, case). World is fresh per call unless one is supplied. */
+export async function runCase(reg, fix, c, { root = REPO, world = null, timeoutMs = null, maxMs = null } = {}) {
+  const w = world || makeWorld(reg.host, { root, label: c.name });
+  try {
+    const payload = realise(fix, w);
+    c.pre?.(w);
+    const env = worldEnv(w); c.env?.(env);
+    const stdin = c.stdin ? c.stdin(payload) : '';
+    const r = await runCommand(reg.command, { cwd: w.cwd, env, stdin, stdinMode: c.stdinMode || 'pipe', timeoutMs: timeoutMs ?? (reg.effectiveSec * 1000 + 4000),
+      profile: c.profile && sandboxOk ? c.profile : null });
+    return { reg, fixture: fix.name, case: c.name, skipped: c.profile && !sandboxOk ? 'sandbox-exec unavailable' : null, ...r, findings: judge(reg, c.name, r, { maxMs }) };
+  } finally { if (!world) cleanupWorld(w); }
+}
+
+/** 20 concurrent invocations of the same hook in one world. */
+export async function runConcurrent(reg, fix, n = 20, opts = {}) {
+  const w = makeWorld(reg.host, { root: opts.root || REPO, label: 'conc' });
+  try {
+    const rs = await Promise.all(Array.from({ length: n }, () => runCase(reg, fix, { name: 'concurrent', stdin: (p) => json(p) }, { ...opts, world: w, timeoutMs: reg.effectiveSec * 1000 * 4 })));
+    // Concurrency is a LOAD test: the slow-path budget is checked against the registered timeout, not the idle margin.
+    for (const r of rs) r.findings = judge(reg, 'concurrent', r, { maxMs: reg.effectiveSec * 1000 });
+    return rs;
+  } finally { cleanupWorld(w); }
+}
+
+/** N sequential invocations; returns per-call ms and the on-disk growth of HOME. */
+export async function runRepeat(reg, fix, n = 50, opts = {}) {
+  const w = makeWorld(reg.host, { root: opts.root || REPO, label: 'repeat' });
+  const size = () => { let files = 0; let bytes = 0; const walk = (d) => { for (const e of fs.readdirSync(d, { withFileTypes: true })) { const p = path.join(d, e.name); if (e.isDirectory()) walk(p); else { try { bytes += fs.statSync(p).size; files++; } catch { /* raced */ } } } }; walk(w.home); return { files, bytes }; };
+  try {
+    const before = size(); const rs = [];
+    for (let i = 0; i < n; i++) rs.push(await runCase(reg, fix, { name: 'repeat', stdin: (p) => json(p) }, { ...opts, world: w }));
+    const after = size();
+    return { runs: rs, growth: { files: after.files - before.files, bytes: after.bytes - before.bytes }, firstMs: rs[0].ms, lastMs: rs.at(-1).ms };
+  } finally { cleanupWorld(w); }
+}
+
+/** Run the hook BODY directly under a write-containment sandbox; a write outside the world kills it. */
+export async function auditWrites(reg, fix, { root = REPO } = {}) {
+  if (!sandboxOk) return { skipped: 'sandbox-exec unavailable on this platform' };
+  if (!reg.body?.file) return { skipped: 'no body in hook-shim TABLE' };
+  const w = makeWorld(reg.host, { root, label: 'wr' });
+  try {
+    const payload = realise(fix, w);
+    const env = worldEnv(w); if (reg.host === 'codex') env.RUVNET_HOOK_HOST = 'codex';
+    const file = path.join(root, 'plugin', 'scripts', reg.body.file);
+    const interp = reg.body.interpreter === 'node' ? process.execPath : '/bin/bash';
+    const extra = reg.args ? reg.args.split(/\s+/) : [];
+    const r = await runCommand('', { cwd: w.cwd, env, stdin: json(payload), timeoutMs: reg.effectiveSec * 1000 + 4000, profile: writeProfile(w.dir), argv: [interp, file, ...extra] });
+    return { violated: r.signal === 'SIGKILL', status: r.status, signal: r.signal, ms: r.ms };
+  } finally { cleanupWorld(w); }
+}
+
+// ── overload measurement ─────────────────────────────────────────────────────────────────────────
+export const PROMPTS = ['ok', 'what is ruflo?', 'build a REST API service with agentdb memory', 'Fix the failing test in src/foo.test.ts',
+  'can ruflo do swarm consensus? check the architecture and plan the refactor'];
+/** Bytes every SessionStart + UserPromptSubmit hook injects, per prompt, for one host. */
+export async function measureInjection(host, { root = REPO } = {}) {
+  const regs = registrations(root, [host]).filter((r) => r.event === 'SessionStart' || r.event === 'UserPromptSubmit');
+  const rows = [];
+  for (const prompt of PROMPTS) {
+    const per = [];
+    for (const reg of regs) {
+      if (reg.event === 'SessionStart' && prompt !== PROMPTS[0]) continue;
+      const fix = fixturesFor(reg, root)[0];
+      const fx = reg.event === 'UserPromptSubmit' ? { ...fix, payload: { ...fix.payload, prompt } } : fix;
+      const r = await runCase(reg, fx, { name: 'measure', stdin: (p) => json(p) }, { root });
+      per.push({ hook: reg.label, bytes: r.stdout.length, ms: r.ms });
+    }
+    rows.push({ prompt, perHook: per, totalBytes: per.reduce((a, b) => a + b.bytes, 0) });
+  }
+  return rows;
+}
+export { matchedTools };

package/scripts/hook-qualify-hosts.mjs

@@ -0,0 +1,115 @@
+// hook-qualify-hosts.mjs — LAYER 2: one short REAL turn per host binary, plugin hooks live, scanned for
+// any hook error. Never loops; cwd is a throwaway git-init'ed temp dir so no real project state is
+// touched. The host binaries use the owner's real HOME (auth lives there), so host-level state such as
+// ~/.cache/ruvnet-brain is exercised exactly as in use — that is the point of the layer.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { REPO } from '../plugin/scripts/hook-registry.mjs';
+
+const BIN = {
+  claude: process.env.HOOK_QUALIFY_CLAUDE || path.join(os.homedir(), '.npm-global', 'bin', 'claude'),
+  codex: process.env.HOOK_QUALIFY_CODEX || path.join(os.homedir(), '.local', 'bin', 'codex'),
+  grok: process.env.HOOK_QUALIFY_GROK || path.join(os.homedir(), '.local', 'bin', 'grok'),
+};
+const PROMPT = 'Reply with exactly: ok';
+
+export async function waitForLoad(maxLoad, waitMs, log = () => {}) {
+  const until = Date.now() + waitMs;
+  while (os.loadavg()[0] >= maxLoad) {
+    if (Date.now() > until) return false;
+    log(`load ${os.loadavg()[0].toFixed(0)} >= ${maxLoad}; waiting`);
+    await new Promise((r) => setTimeout(r, 10_000));
+  }
+  return true;
+}
+function scratch(name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `hq-l2-${name}-`));
+  const cwd = path.join(dir, 'cwd'); fs.mkdirSync(cwd);
+  spawnSync('git', ['init', '-q', '.'], { cwd });
+  return { dir, cwd };
+}
+const cleanEnv = () => { const e = { ...process.env }; for (const k of Object.keys(e)) if (/^CLAUDE_CODE_|^CLAUDECODE$|^CLAUDE_PID$/.test(k) && k !== 'CLAUDE_CODE_EXECPATH') delete e[k]; return e; };
+const lines = (s) => String(s || '').split('\n').filter(Boolean);
+const jsonl = (s) => lines(s).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+
+/** Pure: scan a real `claude -p --output-format stream-json --verbose --include-hook-events` run. */
+export function scanClaude({ stdout, stderr, debug = '' }) {
+  const f = []; const ev = jsonl(stdout);
+  for (const o of ev) {
+    if (o.type !== 'system' || o.subtype !== 'hook_response') continue;
+    const who = `${o.hook_event}:${o.hook_name}`;
+    if (o.exit_code !== 0) f.push(`${who} exit ${o.exit_code} (${o.outcome})`);
+    else if (o.outcome && o.outcome !== 'success') f.push(`${who} outcome ${o.outcome}`);
+    if (o.stderr) f.push(`${who} wrote stderr: ${JSON.stringify(String(o.stderr).slice(0, 120))}`);
+    if (/^\s*\{/.test(o.stdout || '')) { try { JSON.parse(o.stdout); } catch { f.push(`${who} stdout is not valid JSON`); } }
+  }
+  if (stderr.trim()) f.push(`process stderr: ${JSON.stringify(stderr.trim().slice(0, 300))}`);
+  for (const l of lines(debug)) if (/\] (?:Hook|SessionEnd|SessionStart|PreToolUse|PostToolUse|Stop|UserPromptSubmit)\b.*(?:timed out|cancelled|failed|invalid)/i.test(l)) f.push(`debug: ${l.replace(/^\S+ \[DEBUG\] /, '').slice(0, 220)}`);
+  return { findings: [...new Set(f)], hookResponses: ev.filter((o) => o.subtype === 'hook_response').length };
+}
+/** Pure: scan a real `codex exec --json` run. */
+export function scanCodex({ stdout, stderr }) {
+  const f = [];
+  for (const o of jsonl(stdout)) {
+    if (o.item?.type === 'error' || o.type === 'error') { const m = o.item?.message || o.message || ''; if (/hook|clamp/i.test(m)) f.push(`host reports: ${m.slice(0, 200)}`); }
+  }
+  for (const l of lines(stderr)) if (/hook/i.test(l)) f.push(`stderr: ${l.slice(0, 200)}`);
+  return { findings: [...new Set(f)], unrelatedStderr: lines(stderr).filter((l) => !/hook/i.test(l)).slice(0, 3) };
+}
+/** Pure: scan a real `grok -p --debug-file` run. */
+export function scanGrok({ stdout, stderr, debug = '' }) {
+  const f = []; let loaded = null; const pluginHooks = /plugin discovered name=ruvnet-brain .*has_hooks=true/.test(debug);
+  for (const l of lines(debug)) {
+    const m = /loaded hooks hook_count=(\d+)/.exec(l); if (m) loaded = Number(m[1]);
+    if (/xai_grok_hooks/.test(l) && /\b(WARN|ERROR)\b/.test(l)) f.push(`grok hooks: ${l.replace(/^\S+\s+/, '').slice(0, 240)}`);
+    if (/hook (failed|timed out|error)|hook_error|hook.*(exit code|invalid)/i.test(l) && /xai_grok_hooks|dispatcher/.test(l)) f.push(`grok hooks: ${l.replace(/^\S+\s+/, '').slice(0, 240)}`);
+  }
+  if (stderr.trim()) f.push(`process stderr: ${JSON.stringify(stderr.trim().slice(0, 300))}`);
+  if (/hook/i.test(stdout) && /(error|failed)/i.test(stdout.match(/.{0,80}hook.{0,120}/i)?.[0] || '')) f.push('hook error text in the output stream');
+  return { findings: [...new Set(f)], hooksLoaded: loaded, pluginHasHooks: pluginHooks, pluginHooksRan: /hook_name=plugin|hook_name=ruvnet/.test(debug) };
+}
+
+async function runClaude(root, dbgDir) {
+  const { dir, cwd } = scratch('claude'); const debugFile = path.join(dbgDir, 'claude-debug.log');
+  const r = spawnSync(BIN.claude, ['-p', PROMPT, '--output-format', 'stream-json', '--verbose', '--include-hook-events', '--no-session-persistence',
+    '--setting-sources', 'project', '--plugin-dir', path.join(root, 'plugin'), '--debug-file', debugFile, '--max-turns', '2'],
+  { cwd, env: cleanEnv(), encoding: 'utf8', timeout: 240_000, maxBuffer: 64e6 });
+  const debug = fs.existsSync(debugFile) ? fs.readFileSync(debugFile, 'utf8') : '';
+  const s = scanClaude({ stdout: r.stdout || '', stderr: r.stderr || '', debug });
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'plugin loaded from this checkout via --plugin-dir; user/local settings not loaded' };
+}
+async function runCodex(root, dbgDir) {
+  const { dir, cwd } = scratch('codex');
+  const r = spawnSync(BIN.codex, ['exec', '--json', '--ephemeral', '--skip-git-repo-check', '-C', cwd, PROMPT], { cwd, env: process.env, encoding: 'utf8', timeout: 240_000, maxBuffer: 64e6 });
+  fs.writeFileSync(path.join(dbgDir, 'codex-out.jsonl'), r.stdout || '');
+  const s = scanCodex({ stdout: r.stdout || '', stderr: r.stderr || '' });
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'runs the hooks INSTALLED in ~/.codex (the owner\'s real configuration), not this checkout' };
+}
+async function runGrok(root, dbgDir) {
+  const { dir, cwd } = scratch('grok'); const debugFile = path.join(dbgDir, 'grok-debug.log');
+  const r = spawnSync(BIN.grok, ['-p', PROMPT, '--output-format', 'streaming-json', '--debug-file', debugFile, '--always-approve', '--max-turns', '2', '--cwd', cwd],
+    { cwd, env: process.env, encoding: 'utf8', timeout: 240_000, maxBuffer: 64e6 });
+  const blob = `${r.stdout || ''}${r.stderr || ''}`;
+  if (/not signed in|grok login/i.test(blob)) { fs.rmSync(dir, { recursive: true, force: true }); return { status: 'BLOCKED', reason: 'Grok is not signed in (owner action: grok login --device-code)' }; }
+  const debug = fs.existsSync(debugFile) ? fs.readFileSync(debugFile, 'utf8') : '';
+  const s = scanGrok({ stdout: r.stdout || '', stderr: r.stderr || '', debug });
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'throwaway cwd is untrusted by Grok, so project/plugin hook loading there is part of what is measured' };
+}
+
+export async function layer2(hosts, { maxLoad = 40, waitMs = 15 * 60_000, log = () => {}, root = REPO } = {}) {
+  const dbgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-l2-logs-'));
+  const out = [];
+  for (const host of hosts) {
+    if (!(await waitForLoad(maxLoad, waitMs, log))) { out.push({ host, status: 'BLOCKED', reason: `machine load stayed >= ${maxLoad}` }); continue; }
+    if (!fs.existsSync(BIN[host])) { out.push({ host, status: 'BLOCKED', reason: `${BIN[host]} not found` }); continue; }
+    const fn = { claude: runClaude, codex: runCodex, grok: runGrok }[host];
+    const t0 = Date.now();
+    out.push({ host, ...(await fn(root, dbgDir)), ms: Date.now() - t0, logs: dbgDir });
+  }
+  return out;
+}

package/scripts/hook-qualify.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// hook-qualify.mjs — qualify every registered hook against the host contract it runs under.
+//
+//   (defaults: --repeat 10 --concurrent 2 so a busy machine is not hammered; the owner's full ask is --repeat 50 --concurrent 20)
+//   node scripts/hook-qualify.mjs                      Layer 1 for claude+codex+grok (offline, deterministic)
+//   node scripts/hook-qualify.mjs --layer2 claude,codex,grok   real-host smoke, ONE turn each
+//   node scripts/hook-qualify.mjs --hosts codex --cases baseline-real,empty-stdin --repeat 5 --concurrent 5
+//   node scripts/hook-qualify.mjs --measure            bytes injected per prompt by SessionStart+UserPromptSubmit
+//   node scripts/hook-qualify.mjs --json out.json      machine-readable matrix
+//
+// Exit 0 only when every row is PASS. A qualification that cannot run (no sandbox, host not signed in)
+// is reported as SKIP/BLOCKED with the reason — never as PASS.
+import fs from 'node:fs';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+import {
+  CASES, HOSTS, auditWrites, fixturesFor, measureInjection, registrations, runCase, runConcurrent, runRepeat,
+  sandboxAvailable, staticFindings,
+} from './hook-qualify-core.mjs';
+
+function arg(name, dflt = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i < 0) return dflt;
+  const v = process.argv[i + 1];
+  return v === undefined || v.startsWith('--') ? true : v;
+}
+const pct = (xs, p) => { const s = [...xs].sort((a, b) => a - b); return s[Math.min(s.length - 1, Math.floor(s.length * p))] ?? 0; };
+
+export async function layer1({ hosts = HOSTS, cases = null, repeat = 50, concurrent = 20, log = () => {} } = {}) {
+  const regs = registrations(undefined, hosts);
+  const rows = [];
+  for (const f of staticFindings(regs)) rows.push({ reg: f.reg, kind: 'static', pass: false, findings: [f.msg] });
+  const selected = CASES.filter((c) => !cases || cases.includes(c.name));
+  for (const reg of regs) {
+    const fixes = fixturesFor(reg);
+    if (!fixes.length) { rows.push({ reg, kind: 'fixture', pass: false, findings: [`no captured payload for ${reg.host}/${reg.event} matcher ${reg.matcher}`] }); continue; }
+    const fix = fixes[0];
+    log(`  ${reg.label}`);
+    const runs = [];
+    for (const c of selected) runs.push(await runCase(reg, fix, c));
+    const failed = runs.filter((r) => r.findings.length);
+    const base = runs.find((r) => r.case === 'baseline-real');
+    const row = { reg, kind: 'matrix', fixture: fix.name, provenance: fix._provenance, cases: runs.length, failed: failed.length,
+      skipped: runs.filter((r) => r.skipped).map((r) => r.case), p50: pct(runs.map((r) => r.ms), 0.5), max: Math.max(...runs.map((r) => r.ms)),
+      baselineMs: base?.ms, baselineBytes: base?.stdout.length, failures: failed.map((r) => ({ case: r.case, findings: r.findings })) };
+    if (repeat && (!cases || cases.includes('repeat'))) { const rp = await runRepeat(reg, fix, repeat); row.repeat = { n: repeat, growth: rp.growth, firstMs: rp.firstMs, lastMs: rp.lastMs, p95: pct(rp.runs.map((r) => r.ms), 0.95), failed: rp.runs.filter((r) => r.findings.length).length, sample: rp.runs.find((r) => r.findings.length)?.findings }; }
+    if (concurrent && (!cases || cases.includes('concurrent'))) { const cr = await runConcurrent(reg, fix, concurrent); row.concurrent = { n: concurrent, maxMs: Math.max(...cr.map((r) => r.ms)), failed: cr.filter((r) => r.findings.length).length, sample: cr.find((r) => r.findings.length)?.findings }; }
+    if (!cases || cases.includes('write-audit')) row.writes = await auditWrites(reg, fix);
+    row.pass = !failed.length && !(row.repeat?.failed) && !(row.concurrent?.failed) && !row.writes?.violated;
+    rows.push(row);
+  }
+  return rows;
+}
+
+export function render(rows) {
+  const out = [];
+  out.push('HOST   EVENT             HOOK                          RESULT  cases  base(ms) p50/max(ms)  timeout(s)  bytes  x20max  growth(50x)   writes');
+  for (const r of rows) {
+    if (r.kind !== 'matrix') { out.push(`${r.reg.host.padEnd(6)} ${r.reg.event.padEnd(17)} ${r.reg.label.split('/').slice(2).join('/').padEnd(29)} FAIL    ${r.kind}: ${r.findings[0]}`); continue; }
+    const g = r.repeat ? `${r.repeat.growth.files}f/${r.repeat.growth.bytes}B` : '-';
+    const w = r.writes?.skipped ? `SKIP(${r.writes.skipped.slice(0, 18)})` : r.writes ? (r.writes.violated ? 'VIOLATION' : 'ok') : '-';
+    out.push(`${r.reg.host.padEnd(6)} ${r.reg.event.padEnd(17)} ${r.reg.label.split('/').slice(2).join('/').padEnd(29)} ${(r.pass ? 'PASS' : 'FAIL').padEnd(7)} ${String(r.cases - r.failed).padStart(2)}/${String(r.cases).padEnd(3)} ${String(r.baselineMs).padStart(7)} ${`${r.p50}/${r.max}`.padStart(12)}  ${String(r.reg.effectiveSec).padStart(6)}/${r.reg.timeoutSec}  ${String(r.baselineBytes).padStart(5)}  ${String(r.concurrent?.maxMs ?? '-').padStart(6)}  ${g.padEnd(13)} ${w}`);
+  }
+  const bad = rows.filter((r) => !r.pass);
+  if (bad.length) out.push('', 'FAILURES');
+  for (const r of bad) {
+    out.push(`- ${r.reg.label}`);
+    for (const f of r.findings || []) out.push(`    ${f}`);
+    for (const f of r.failures || []) out.push(`    [${f.case}] ${f.findings.join(' | ')}`);
+    if (r.repeat?.failed) out.push(`    [repeat x${r.repeat.n}] ${r.repeat.failed} failing: ${(r.repeat.sample || []).join(' | ')}`);
+    if (r.concurrent?.failed) out.push(`    [concurrent x${r.concurrent.n}] ${r.concurrent.failed} failing: ${(r.concurrent.sample || []).join(' | ')}`);
+    if (r.writes?.violated) out.push('    [write-audit] wrote outside the isolated HOME/cwd (killed by the sandbox)');
+  }
+  return out.join('\n');
+}
+
+async function main() {
+  const hosts = String(arg('hosts', HOSTS.join(','))).split(',');
+  const cases = arg('cases') ? String(arg('cases')).split(',') : null;
+  if (arg('measure')) {
+    for (const h of hosts.filter((x) => x !== 'grok')) {
+      console.log(`== bytes injected by SessionStart + UserPromptSubmit hooks (${h}) ==`);
+      for (const row of await measureInjection(h)) console.log(`${String(row.totalBytes).padStart(6)} B  ${JSON.stringify(row.prompt)}  ${row.perHook.map((p) => `${p.hook.split('/').slice(1).join('/')}=${p.bytes}`).join('  ')}`);
+    }
+    return 0;
+  }
+  if (arg('layer2')) {
+    const { layer2 } = await import('./hook-qualify-hosts.mjs');
+    const res = await layer2(String(arg('layer2')).split(','), { maxLoad: Number(arg('max-load', 40)), log: console.log });
+    console.log(JSON.stringify(res, null, 1));
+    return res.every((r) => r.status === 'PASS') ? 0 : 1;
+  }
+  if (!sandboxAvailable()) console.log('NOTE: sandbox-exec unavailable — the no-network and write-containment guards are SKIPPED, not passed.');
+  console.log(`load ${os.loadavg().map((x) => x.toFixed(1)).join(' ')} (timing assertions assume an idle machine)`);
+  const rows = await layer1({ hosts, cases, repeat: Number(arg('repeat', 10)), concurrent: Number(arg('concurrent', 2)), log: console.error });
+  console.log(render(rows));
+  if (arg('json')) fs.writeFileSync(String(arg('json')), JSON.stringify(rows, (k, v) => (k === 'body' ? undefined : v), 1));
+  return rows.every((r) => r.pass) ? 0 : 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().then((c) => process.exit(c), (e) => { console.error(e); process.exit(2); });