ruvnet-brain 4.6.3 → 4.6.4

package/plugin/scripts/decision-record.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+/**
+ * decision-record.mjs — ADR-105 §8 as code: AgentDB is CONSULTED before a decision and the decision
+ * is RECORDED after it, in the one canonical store, through the one door (ADR-105 §1–§3).
+ *
+ *   node decision-record.mjs --consult "<topic>"            consequential recall + persisted receipt
+ *   node decision-record.mjs --record --what W --why Y --shape S --evidence kind:ref [...]
+ *                            [--supersedes <key>]... [--status ratified|detected-unconfirmed]
+ *   node decision-record.mjs --flush                        retry records left pending by a refusal
+ *
+ * Two hooks consume the facts this file produces (ADR-106): decision-gate's `decision-recall` policy
+ * reads the consult receipt before a new ADR or an ADR status change; continuation-gate reads the
+ * transcript audit below at Stop. Neither hook writes memory.
+ *
+ * Store contract (ADR-105 §3, `ruflo memory store --help` read 2026-10-11): every write is
+ * `--no-upsert --require-native --append-only --path <abs>` from a private scratch cwd with no
+ * CLAUDE_FLOW_MEMORY_PATH; a row is committed only when an exact-key readback returns the same
+ * bytes; any other refusal stays pending on disk (mode 0600, fsynced) and is never reported as done.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { redactText } from './continuity-events.mjs';
+import { maskExcludedPaths } from './turn-capture-privacy.mjs';
+import { resolveTurnDb, readSettledTranscript } from './turn-outcome-capture.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
+import { rufloRunDir } from './project-progression-store.mjs';
+import { currentTurnRecords } from './completion-claim-evidence.mjs';
+
+export const DECISION_SCHEMA = 'ruvnet-brain.decision-record';
+export const STATUSES = Object.freeze(['ratified', 'detected-unconfirmed']);
+export const EVIDENCE_KINDS = Object.freeze(['path', 'commit', 'receipt', 'adr', 'url']);
+export const BOUNDS = Object.freeze({ what: 400, why: 800, shape: 1200, evidence: 8, evidenceRef: 200, supersedes: 8, value: 4096 });
+export const CONSULT_MAX_AGE_MS = 2 * 3600_000;
+const KEY_RE = /^decision-[a-z0-9-]{1,48}-\d{8}T\d{9}Z$/;
+const SCRIPT = fileURLToPath(import.meta.url);
+
+/** An ADR document path (README/index files are not decisions). */
+export function isAdrPath(file) {
+  const p = String(file || '').replace(/\\/g, '/');
+  if (!/\.md$/i.test(p) || /(^|\/)(README|index)\.md$/i.test(p)) return false;
+  return /(^|\/)adrs?\/[^/]+\.md$/i.test(p) || /(^|\/)ADR-[^/]+\.md$/i.test(p);
+}
+
+const bound = (s, n) => String(s ?? '').slice(0, n);
+export const brainHomeOf = (env = process.env) => env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
+
+/** `decision-<kebab slug ≤48>-<YYYYMMDDTHHMMSSmmmZ>` (ADR-105 §8). */
+export function decisionKey(what, at) {
+  const slug = String(what || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48).replace(/-+$/, '') || 'decision';
+  const stamp = new Date(at).toISOString().replace(/[-:.]/g, '');
+  return `decision-${slug}-${stamp}`;
+}
+
+/** Structural validation of a stored record. Returns a list of problems (empty = valid). */
+export function validateDecisionRecord(r) {
+  const errors = [];
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return ['record must be an object'];
+  if (r.schema !== DECISION_SCHEMA || r.schemaVersion !== 1) errors.push('schema/schemaVersion');
+  for (const f of ['project', 'projectIdentity', 'at', 'host']) if (typeof r[f] !== 'string' || !r[f]) errors.push(`${f} required`);
+  if (r.session !== null && typeof r.session !== 'string') errors.push('session must be a string or null');
+  if (!['claude', 'codex', 'cli'].includes(r.host)) errors.push('host must be claude, codex or cli');
+  if (!STATUSES.includes(r.status)) errors.push(`status must be one of ${STATUSES.join(', ')}`);
+  if (typeof r.what !== 'string' || !r.what.trim()) errors.push('what required');
+  for (const f of ['what', 'why', 'shape']) if (r[f] !== undefined && (typeof r[f] !== 'string' || r[f].length > BOUNDS[f])) errors.push(`${f} exceeds ${BOUNDS[f]} chars`);
+  const evidence = Array.isArray(r.evidence) ? r.evidence : [];
+  if (r.evidence !== undefined && !Array.isArray(r.evidence)) errors.push('evidence must be an array');
+  if (evidence.length > BOUNDS.evidence) errors.push(`evidence exceeds ${BOUNDS.evidence} items`);
+  for (const e of evidence) {
+    if (!e || !EVIDENCE_KINDS.includes(e.kind) || typeof e.ref !== 'string' || !e.ref || e.ref.length > BOUNDS.evidenceRef) errors.push('evidence item must be {kind: path|commit|receipt|adr|url, ref ≤200}');
+  }
+  if (r.status === 'ratified') {
+    if (typeof r.why !== 'string' || !r.why.trim()) errors.push('why required for a ratified decision');
+    if (typeof r.shape !== 'string' || !r.shape.trim()) errors.push('shape required for a ratified decision');
+    if (!evidence.length) errors.push('at least one evidence item required for a ratified decision');
+  }
+  const sup = r.supersedes ?? [];
+  if (!Array.isArray(sup) || sup.length > BOUNDS.supersedes || sup.some((k) => !KEY_RE.test(k))) errors.push('supersedes must be ≤8 exact decision keys');
+  // A detected record is evidence, never authority: it may not retire a decision (append-only, no undo).
+  if (Array.isArray(sup) && sup.length && r.status !== 'ratified') errors.push('only a ratified decision may supersede');
+  return errors;
+}
+
+/** Redact (shared scanner), mask excluded paths, then bound — in that order (ADR-105 §8). */
+export function buildDecisionRecord(input, { projectRoot, projectIdentity, host = 'cli', session = null, now = Date.now(), exclusions = [] }) {
+  const clean = (s, n) => bound(maskExcludedPaths(redactText(String(s ?? '').trim()), exclusions, projectRoot), n);
+  const record = {
+    schema: DECISION_SCHEMA, schemaVersion: 1, project: projectRoot, projectIdentity,
+    at: new Date(now).toISOString(), host, session,
+    status: input.status || 'ratified',
+    what: clean(input.what, BOUNDS.what),
+    ...(input.why ? { why: clean(input.why, BOUNDS.why) } : {}),
+    ...(input.shape ? { shape: clean(input.shape, BOUNDS.shape) } : {}),
+    evidence: (input.evidence || []).slice(0, BOUNDS.evidence).map((e) => ({ kind: e.kind, ref: clean(e.ref, BOUNDS.evidenceRef) })),
+    supersedes: [...new Set(input.supersedes || [])],
+  };
+  const errors = validateDecisionRecord(record);
+  const value = JSON.stringify(record);
+  if (Buffer.byteLength(value) > BOUNDS.value) errors.push(`record exceeds ${BOUNDS.value} bytes`);
+  return { record, key: decisionKey(record.what, now), value, errors };
+}
+
+/**
+ * Supersession is a link on the NEWER record (an append-only store cannot edit the old row).
+ * Only a valid ratified record supersedes; a detected one is evidence, never authority.
+ */
+export function supersededKeys(records) {
+  const out = new Set();
+  for (const r of records) {
+    if (!r || r.schema !== DECISION_SCHEMA || r.status !== 'ratified' || validateDecisionRecord(r).length) continue;
+    for (const k of r.supersedes || []) out.add(k);
+  }
+  return out;
+}
+
+/**
+ * Supersession tombstones (review finding 1). A newer record's `supersedes` is only visible to recall
+ * when that newer record is itself read, so a superseder that ranking or the deadline left out let the
+ * old decision be served as live. Each superseded key therefore also gets an append-only tombstone row
+ * `supersession-<old key>` in the same namespace; recall sees it in the key enumeration it already does,
+ * with no extra read. The prefix never matches recall's `^decision[-_]` decision-key test.
+ */
+export const SUPERSESSION_SCHEMA = 'ruvnet-brain.decision-supersession';
+export const TOMBSTONE_PREFIX = 'supersession-';
+export const tombstoneKey = (oldKey) => `${TOMBSTONE_PREFIX}${oldKey}`;
+export function tombstonedKeys(keys) {
+  return new Set((keys || []).filter((k) => typeof k === 'string' && k.startsWith(`${TOMBSTONE_PREFIX}decision-`))
+    .map((k) => k.slice(TOMBSTONE_PREFIX.length)));
+}
+
+function runRuflo(ruflo, db, args, { spawn = spawnSync } = {}) {
+  const cwd = rufloRunDir(db);
+  try {
+    const { executable, args: argv } = rufloInvocation(ruflo, args);
+    const r = spawn(executable, argv, { cwd, encoding: 'utf8', timeout: 60_000, windowsHide: true,
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_MEMORY_PATH: undefined } });
+    return { status: Number.isInteger(r.status) ? r.status : 1, stdout: String(r.stdout || ''), output: `${r.stderr || ''}\n${r.stdout || ''}${r.error ? `\n${r.error.message}` : ''}` };
+  } finally { fs.rmSync(cwd, { recursive: true, force: true }); }
+}
+
+export function defaultStore({ ruflo, db, namespace, key, value }) {
+  return runRuflo(ruflo, db, ['memory', 'store', '--key', key, '--value', value, '--namespace', namespace,
+    '--no-upsert', '--require-native', '--append-only', '--provenance', 'agent_output', '--path', db]);
+}
+export function defaultReadBack({ ruflo, db, namespace, key }) {
+  const r = runRuflo(ruflo, db, ['memory', 'retrieve', '--key', key, '--namespace', namespace, '--value-only', '--path', db]);
+  return { content: r.status === 0 ? r.stdout.trim() : null };
+}
+
+const pendingDir = (db) => path.join(path.dirname(db), '.decision-records-pending');
+function writePending(db, entry) {
+  const dir = pendingDir(db);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${entry.key}.json`);
+  const fd = fs.openSync(file, 'w', 0o600);
+  try { fs.writeSync(fd, JSON.stringify(entry)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  return file;
+}
+
+/**
+ * The §3 door. committed | already-stored | quarantined | pending — never "committed" without an
+ * exact readback of the same bytes, and a refusal is never treated as a duplicate.
+ */
+export function storeDecision({ ruflo, db, namespace, key, value, store = defaultStore, readBack = defaultReadBack, keepPending = true }) {
+  const prior = readBack({ ruflo, db, namespace, key });
+  if (typeof prior.content === 'string' && prior.content === value) return { state: 'already-stored', key };
+  if (typeof prior.content === 'string' && prior.content && prior.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
+  const result = store({ ruflo, db, namespace, key, value });
+  const back = readBack({ ruflo, db, namespace, key });
+  if (result.status === 0 && back.content === value) return { state: 'committed', key };
+  if (typeof back.content === 'string' && back.content && back.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
+  const reason = redactText(String(result.output || '').trim().split('\n').filter(Boolean).slice(-1)[0] || `store exited ${result.status}`).slice(0, 300);
+  const pending = keepPending ? writePending(db, { key, namespace, value, at: new Date().toISOString(), reason }) : null;
+  return { state: 'pending', key, reason, pending };
+}
+
+/** Replay pending records through the same door; a committed one leaves the pending directory. */
+export function flushPending({ ruflo, db, store = defaultStore, readBack = defaultReadBack }) {
+  const out = [];
+  let names = [];
+  try { names = fs.readdirSync(pendingDir(db)).filter((n) => n.endsWith('.json')); } catch { return out; }
+  for (const name of names) {
+    const file = path.join(pendingDir(db), name);
+    let entry; try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { out.push({ state: 'unreadable', file }); continue; }
+    const r = storeDecision({ ruflo, db, namespace: entry.namespace, key: entry.key, value: entry.value, store, readBack, keepPending: false });
+    if (r.state === 'committed' || r.state === 'already-stored') fs.rmSync(file, { force: true });
+    out.push(r);
+  }
+  return out;
+}
+
+// ── consult receipt (read before deciding) ─────────────────────────────────────────────────────
+export const consultFile = (projectRoot, brainHome) => path.join(brainHome, 'decision-consult',
+  `${crypto.createHash('sha256').update(String(projectRoot)).digest('hex').slice(0, 24)}.json`);
+
+export function writeConsultReceipt({ projectRoot, brainHome, outcome, topic, records = [], categories = null, now = Date.now() }) {
+  const file = consultFile(projectRoot, brainHome);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ schemaVersion: 1, kind: 'decision-consult', projectRoot, at: new Date(now).toISOString(), outcome,
+    topicDigest: crypto.createHash('sha256').update(String(topic)).digest('hex'), records, categories }), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** The receipt for this project if it is younger than maxAgeMs, else null. Any outcome counts: it proves the consult ran. */
+export function freshConsultReceipt({ projectRoot, brainHome, now = Date.now(), maxAgeMs = CONSULT_MAX_AGE_MS }) {
+  try {
+    const r = JSON.parse(fs.readFileSync(consultFile(projectRoot, brainHome), 'utf8'));
+    const age = now - Date.parse(r.at);
+    return r.kind === 'decision-consult' && r.projectRoot === projectRoot && age >= 0 && age <= maxAgeMs ? r : null;
+  } catch { return null; }
+}
+
+// ── transcript audit (write after deciding) ────────────────────────────────────────────────────
+const RECORD_COMMAND = /decision-record\.mjs["']?\s[^\n|;&]*--record\b/;
+
+/**
+ * From the CURRENT turn's transcript records: ADR files this turn CREATED (Write result type
+ * `create`, measured on real Claude transcripts) and whether a successful `--record` ran after the
+ * last of them. Pure over parsed records.
+ */
+export function auditDecisionTurn(records) {
+  const results = new Map();
+  for (const o of records) {
+    const c = o?.message?.content;
+    if (!Array.isArray(c)) continue;
+    for (const r of c) if (r?.type === 'tool_result' && r.tool_use_id) results.set(r.tool_use_id, { error: r.is_error === true, use: o.toolUseResult });
+  }
+  const created = [];
+  let lastCreate = -1;
+  let recordedAt = -1;
+  let i = 0;
+  for (const o of records) {
+    const c = o?.message?.content;
+    if (o?.type !== 'assistant' || !Array.isArray(c)) continue;
+    for (const u of c) {
+      if (u?.type !== 'tool_use') continue;
+      i += 1;
+      const result = results.get(u.id);
+      if (!result || result.error) continue;
+      if (u.name === 'Write' && isAdrPath(u.input?.file_path) && result.use?.type === 'create') { created.push(u.input.file_path); lastCreate = i; }
+      if (u.name === 'Bash' && RECORD_COMMAND.test(String(u.input?.command || ''))) recordedAt = i;
+    }
+  }
+  return { created, recorded: created.length > 0 && recordedAt > lastCreate };
+}
+
+/** Stop-side debt: an ADR created this turn in an ADOPTED project with no later decision record. */
+export function decisionRecordDebt({ transcriptPath, cwd, read = readSettledTranscript, env = process.env }) {
+  if (String(env.RUVNET_DECISION_RECORD_CHECK || '').toLowerCase() === 'off' || String(env.RUVNET_AGENTDB_FIRST || '').toLowerCase() === 'off') return null;
+  if (typeof transcriptPath !== 'string' || !/\.jsonl$/i.test(transcriptPath) || !cwd) return null;
+  let audit;
+  try { audit = auditDecisionTurn(currentTurnRecords(read(transcriptPath, { maxMs: 0 })).recs); } catch { return null; }
+  if (!audit.created.length || audit.recorded) return null;
+  try { if (!fs.statSync(resolveProjectStore({ projectDir: cwd, gitTimeoutMs: 500 }).canonicalAgentDbPath).isFile()) return null; } catch { return null; }
+  return { created: audit.created, command: `node ${JSON.stringify(SCRIPT)} --record --what "…" --why "…" --shape "…" --evidence adr:${audit.created.at(-1)}` };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const o = { evidence: [], supersedes: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); return v; };
+    if (['--consult', '--record', '--flush'].includes(a)) { o.mode = a.slice(2); if (a === '--consult') o.topic = next(); }
+    else if (a === '--what') o.what = next();
+    else if (a === '--why') o.why = next();
+    else if (a === '--shape') o.shape = next();
+    else if (a === '--status') o.status = next();
+    else if (a === '--project') o.project = next();
+    else if (a === '--supersedes') o.supersedes.push(next());
+    else if (a === '--evidence') {
+      const v = next(); const at = v.indexOf(':');
+      if (at < 1) throw new Error('--evidence must be kind:ref');
+      o.evidence.push({ kind: v.slice(0, at), ref: v.slice(at + 1) });
+    } else throw new Error(`unknown argument ${a}`);
+  }
+  return o;
+}
+
+export async function main(argv = process.argv.slice(2), { env = process.env, out = process.stdout, err = process.stderr, recallFn, store, readBack } = {}) {
+  let o;
+  try { o = parseArgs(argv); } catch (e) { err.write(`decision-record: ${e.message}\n`); return 2; }
+  if (!o.mode) { err.write('decision-record: one of --consult "<topic>", --record, --flush is required\n'); return 2; }
+  const projectDir = path.resolve(o.project || process.cwd());
+  const brainHome = brainHomeOf(env);
+  let target;
+  try { target = resolveTurnDb({ projectDir, brainHome, gitTimeoutMs: 1000 }); } catch (e) { err.write(`decision-record: project store unresolved: ${redactText(e.message)}\n`); return 3; }
+  if (o.mode === 'consult') {
+    const recall = recallFn || (await import('./agentdb-recall.mjs')).recall;
+    const r = await recall({ prompt: o.topic, projectDir, env, consequential: true });
+    const projectRoot = target.projectRoot;
+    if (projectRoot) writeConsultReceipt({ projectRoot, brainHome, outcome: r.outcome || 'unavailable', topic: o.topic,
+      records: (r.receipt?.records || []).map((x) => x.key), categories: r.receipt?.categories || r.categories || null });
+    if (r.block) out.write(`${r.block}\n`);
+    const ok = /^ok-/.test(r.outcome || '');
+    out.write(`decision consult: ${r.outcome || 'unavailable'}${ok ? '' : ' — history is UNKNOWN for this decision; say so in the decision'}${r.reason ? ` (${r.reason})` : ''}\n`);
+    return ok ? 0 : 3;
+  }
+  if (target.skipped) { err.write(`decision-record: not recorded — ${target.skipped}\n`); return 3; }
+  const ruflo = resolveRuflo({ env });
+  if (!ruflo) { err.write('decision-record: not recorded — global ruflo not found\n'); return 3; }
+  try { if (!fs.statSync(target.db).isFile()) throw new Error(); } catch { err.write('decision-record: not recorded — project has no canonical store (.swarm/memory.db)\n'); return 3; }
+  if (o.mode === 'flush') {
+    const rows = flushPending({ ruflo, db: target.db });
+    out.write(`decision-record flush: ${rows.map((r) => `${r.key || r.file} ${r.state}`).join('; ') || 'nothing pending'}\n`);
+    return rows.every((r) => ['committed', 'already-stored'].includes(r.state)) ? 0 : 3;
+  }
+  const identity = resolveProjectStore({ projectDir, gitTimeoutMs: 1000 }).projectIdentity.id;
+  const built = buildDecisionRecord(o, { projectRoot: target.projectRoot, projectIdentity: identity,
+    host: env.RUVNET_HOOK_HOST === 'codex' ? 'codex' : env.CLAUDE_PLUGIN_ROOT || env.CLAUDECODE ? 'claude' : 'cli',
+    exclusions: target.contentPathExcludes || [] });
+  if (built.errors.length) { err.write(`decision-record: invalid — ${built.errors.join('; ')}\n`); return 2; }
+  const namespace = path.basename(target.projectRoot);
+  // Review finding 2: the store is append-only, so a wrong --supersedes key would hide a real decision
+  // with no undo. Every key must read back as a decision record of THIS project before anything is written.
+  for (const key of built.record.supersedes) {
+    const back = (readBack || defaultReadBack)({ ruflo, db: target.db, namespace, key });
+    let row = null; try { row = back.content ? JSON.parse(back.content) : null; } catch { /* not a record */ }
+    if (row?.schema !== DECISION_SCHEMA || row.project !== target.projectRoot) {
+      err.write(`decision-record: invalid — --supersedes ${key} is not an existing decision record of this project; nothing was written\n`);
+      return 2;
+    }
+    out.write(`decision-record: supersedes ${key} — ${String(row.what).slice(0, 120)}\n`);
+  }
+  const r = storeDecision({ ruflo, db: target.db, namespace, key: built.key, value: built.value, ...(store ? { store } : {}), ...(readBack ? { readBack } : {}) });
+  out.write(`decision-record: ${r.state} ${r.key} (namespace ${namespace})${r.reason ? ` — ${r.reason}` : ''}${r.pending ? ` — retained for --flush` : ''}\n`);
+  if (!['committed', 'already-stored'].includes(r.state)) return 3;
+  let ok = true;
+  for (const oldKey of built.record.supersedes) {
+    const value = JSON.stringify({ schema: SUPERSESSION_SCHEMA, schemaVersion: 1, project: target.projectRoot, superseded: oldKey, by: built.key, at: built.record.at });
+    let t = storeDecision({ ruflo, db: target.db, namespace, key: tombstoneKey(oldKey), value, ...(store ? { store } : {}), ...(readBack ? { readBack } : {}) });
+    if (t.state === 'quarantined') {
+      // A tombstone from an EARLIER superseder of the same decision already retires it: not a conflict.
+      let prior = null;
+      try { prior = JSON.parse((readBack || defaultReadBack)({ ruflo, db: target.db, namespace, key: t.key }).content || 'null'); } catch { /* conflict stands */ }
+      if (prior?.schema === SUPERSESSION_SCHEMA && prior.superseded === oldKey && prior.project === target.projectRoot) t = { state: 'already-stored', key: t.key };
+    }
+    out.write(`decision-record: tombstone ${t.state} ${t.key}${t.reason ? ` — ${t.reason}` : ''}\n`);
+    ok &&= ['committed', 'already-stored'].includes(t.state);
+  }
+  return ok ? 0 : 3;
+}
+
+function isMain() {
+  try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(SCRIPT); } catch { return false; }
+}
+if (isMain()) main().then((code) => { process.exitCode = code; }, (e) => { process.stderr.write(`decision-record: ${e.message}\n`); process.exitCode = 1; });

package/plugin/scripts/deferral-evidence.mjs

@@ -0,0 +1,134 @@
+/**
+ * deferral-evidence.mjs — "do not end the turn on authorized work by asking permission" as a pure,
+ * replayable detector (ADR-106 `no-deferral`; ADR-043 "must force, not whisper").
+ *
+ * The owner's measured complaint: turns end with "Say go and I'll start", "Decisions I need from you",
+ * "Do you want me to…", "Next: …", "I'll come back when…" on work he had already authorized. The
+ * Stop gate corrects completion claims and records promises; this file supplies the third check.
+ *
+ * A turn is a DEFERRAL only when all three hold, and each is a fact read from text:
+ *   (a) the END of the final answer seeks permission or lists its own next actions as future work;
+ *   (b) authorization exists — a standing instruction in the session's prompts, or an open promise;
+ *   (c) the answer names no genuine blocker class (credential, out-of-authority write, irreversible
+ *       action needing consent, hardware-key tap, evidenced outage, or a choice only the user can make).
+ * Heuristic by construction. scripts/deferral-replay.mjs measures it on real transcripts; the
+ * measured false-positive rate is recorded in ADR-106, not assumed.
+ */
+import { strippedProse } from './completion-claim-evidence.mjs';
+import { isHarnessGenerated } from './hook-input.mjs';
+
+const TAIL_CHARS = 700;
+
+/** Permission-seeking / hand-back phrasing. Matched only in the last part of the answer. */
+const PERMISSION = [
+  /\bsay\s+(?:the\s+word|go|yes)\b/i,
+  /\b(?:do\s+you\s+)?want\s+me\s+to\b/i,
+  /\bwould\s+you\s+like\s+(?:me\s+)?to\b/i,
+  /\b(?:should|shall)\s+I\b/i,
+  /\bdo\s+you\s+want\b/i,
+  /\blet\s+me\s+know\s+(?:if|whether|when|which|how)\b/i,
+  /(?<!\b(?:no|nothing|without|any)\s+(?:further\s+)?)\b(?:decisions?|input|approval|confirmation|sign-?off|answers?|go-?ahead)\s+(?:I\s+need\s+)?(?:from|needed\s+from)\s+you\b/i,
+  /\bI\s+need\s+(?:you|your)\b/i,
+  /\bwaiting\s+(?:on|for)\s+(?:you|your)\b/i,
+  /\b(?:ready\s+when\s+you\s+are|on\s+your\s+(?:go|word|ok))\b/i,
+  /\b(?:ok|okay)\s+to\s+proceed\b|\bproceed\?/i,
+  /\b(?:green[-\s]?light|your\s+call)\b/i,
+];
+
+/** Own next actions stated as future work instead of done. */
+const FUTURE_WORK = [
+  /^(?:\s*[-*•#]+\s*|\s*\*\*)*next(?:\s+steps?)?(?:\*\*)?\s*[:—–-]\s*\S/im,
+  /\bI(?:'ll|’ll|\s+will)\s+(?:come\s+back|follow\s+up|pick\s+(?:this|it)\s+(?:back\s+)?up|resume|continue|get\s+to|start|tackle|handle|do)\b[^.\n]{0,120}\b(?:after|when|once|later|next\s+(?:session|turn|time)|tomorrow)\b/i,
+  /\b(?:remaining|still\s+to\s+do|left\s+to\s+do|todo)\s*[:—–-]\s*\S/i,
+];
+
+/** A genuine authority boundary or an answer only the user can give. Matched anywhere in the answer. */
+export const BLOCKER_CLASSES = Object.freeze({
+  credential: /\b(?:setup\s+key|authenticator|backup\s+codes?)\b|\b(?:api[\s-]?key|token|secret|credential|password|passphrase|login|sign[\s-]?in|oauth)\b[^.\n]{0,80}\b(?:missing|needed|required|absent|expired|not\s+(?:set|available|present|found)|revoked|invalid)\b|\b(?:missing|need|needs|no)\s+(?:an?\s+)?(?:api[\s-]?key|token|secret|credential|password)\b/i,
+  hardwareTap: /\b(?:hardware[\s-]?key|security[\s-]?key|yubikey|touch\s?id|passkey|2fa|otp|tap\s+(?:the|your)\s+key)\b/i,
+  outsideAuthority: /\b(?:outside\s+(?:my|the)\s+(?:stated\s+)?(?:authority|scope)|not\s+(?:authori[sz]ed|permitted|allowed)\s+to|no\s+(?:write\s+)?authority|user-level|~\/\.claude|~\/\.codex|only\s+you\s+can|I\s+can(?:'t|’t|not)\s+(?:contact|reach|send|sign|log\s+in)|npm\s+(?:publish|deprecate)|deprecat(?:e|ed|ing)\s+(?:it\s+)?on\s+npm)\b/i,
+  irreversible: /\b(?:irreversible|cannot\s+be\s+undone|can't\s+be\s+undone|destructive|data\s+loss|force[\s-]?push|drop\s+(?:the\s+)?(?:table|database)|delete\s+(?:the\s+)?(?:branch|repo|database|production)|before\s+anything\s+is\s+deleted|rm\s+-rf)\b/i,
+  outage: /\b(?:outage|is\s+down|503|502|rate[\s-]?limit(?:ed)?|unreachable|connection\s+refused|timed?\s*out\s+(?:connecting|reaching))\b/i,
+  background: /\b(?:awaiting|standing\s+by\s+for|report(?:s)?\s+back|the\s+moment\b[^.\n]{0,60}\b(?:lands|has|finishes|arrives)|once\s+[^.\n]{0,60}\b(?:lands|finishes|completes|returns|is\s+back)|waiting\s+on\s+(?!you|your)[^.\n]{0,40}\b(?:CI|v\d|run|build|agent|tests?|review|suite|checks?)|still\s+running|running\s+in\s+the\s+background|I(?:'m|’m|\s+am)\s+waiting\s+for\s+(?:both|the|it|CI|checks?|reviews?|results?)|when\s+(?:the\s+)?[^.\n]{0,60}\b(?:arrives|lands|returns|reports|finishes|passes|completes|comes\s+back|is\s+back))\b/i,
+  userAction: /\b(?:restart\s+(?:the|your)\s+(?:Mac|computer|machine)|reboot|type\s+(?:the|your)\s+password|First\s+Aid|plug\s+(?:it\s+)?in|unplug|eject)\b/i,
+  purchase: /\b(?:amazon\.com|buy|purchase|price[ds]?|\$\s?\d)\b/i,
+  ownerFact: /\b(?:show\s+me\s+where|tell\s+me\s+(?:where|which\s+file|what\s+you\s+(?:mean|meant)))\b/i,
+  ownerChoice: /\b(?:should|do\s+you\s+want)\b[^?\n]{0,200}\bor\b[^?\n]{0,200}\?|\b(?:which\s+(?:one|option)\s+(?:do\s+)?you|(?:option|choice)\s+(?:A|1)\b[^.\n]{0,200}\b(?:option|choice)\s+(?:B|2)\b|only\s+you\s+(?:know|can\s+(?:decide|choose|answer)))\b/i,
+});
+
+/** Standing authorization phrases in the owner's prompts. */
+const STANDING = /\b(?:don['’]?t\s+stop|do\s+not\s+stop|keep\s+going|never\s+stop|get\s+it\s+(?:done|shipped)|finish\s+(?:it|this|the\s+job|everything)|until\s+(?:it['’]?s\s+)?done|carry\s+(?:it|this)\s+to\s+done|i\s+didn['’]?t\s+tell\s+you\s+to\s+stop|just\s+do\s+it|go\s+ahead|you\s+are\s+authori[sz]ed|fix\s+it\s+now|do\s+it\s+all|make\s+the\s+call)\b/i;
+
+const tailOf = (message) => {
+  const prose = strippedProse(message).replace(/\n{3,}/g, '\n\n').trim();
+  return prose.slice(-TAIL_CHARS);
+};
+
+/** The answer itself says work continues, or that nothing is needed from the owner: not a hand-back. */
+const PROGRESSING = /\b(?:I(?:'m|’m|\s+am)\s+(?:now\s+)?(?:continuing|starting|moving|proceeding)|starting\s+(?:on\s+)?[^.\n]{0,60}\bnow|moving\s+(?:into|on\s+to)\s+[^.\n]{0,60}\bnow|continuing\s+without|nothing\s+(?:is\s+)?(?:waiting\s+on|needed\s+from|required\s+from)\s+you|no\s+(?:further\s+)?input\s+(?:is\s+)?needed)\b/i;
+
+/** Pure: does this final answer end by deferring? Returns the matched phrase or null. */
+export function deferralIn(message) {
+  const tail = tailOf(message);
+  if (!tail || PROGRESSING.test(tail)) return null;
+  for (const re of [...PERMISSION, ...FUTURE_WORK]) {
+    const m = re.exec(tail);
+    if (m) return { phrase: m[0].trim().slice(0, 80), kind: PERMISSION.includes(re) ? 'permission' : 'future-work' };
+  }
+  return null;
+}
+
+/** Pure: which genuine blocker classes the answer names (empty = none). */
+export function blockersIn(message) {
+  const text = strippedProse(message);
+  return Object.entries(BLOCKER_CLASSES).filter(([, re]) => re.test(text)).map(([name]) => name);
+}
+
+/** Pure: is there a standing instruction in any of these owner prompts? */
+export function standingAuthorization(prompts) {
+  for (const p of prompts || []) {
+    const m = STANDING.exec(String(p || ''));
+    if (m) return m[0];
+  }
+  return null;
+}
+
+/**
+ * The verdict. `prompts` = owner prompt texts of the session so far; `openPromises` = count of open
+ * first-person promises from this session in the work ledger.
+ */
+export function auditDeferral(message, { prompts = [], openPromises = 0 } = {}) {
+  const deferral = deferralIn(message);
+  if (!deferral) return { verdict: 'NONE' };
+  const blockers = blockersIn(message);
+  if (blockers.length) return { verdict: 'BLOCKER', deferral, blockers };
+  const standing = standingAuthorization(prompts);
+  if (!standing && openPromises < 1) return { verdict: 'UNAUTHORIZED', deferral };
+  return { verdict: 'DEFERRAL', deferral, authorization: standing ? `standing instruction "${standing}"` : `${openPromises} open promise(s)` };
+}
+
+/** Owner prompt texts from raw Claude transcript lines (main thread, not tool results, not meta). */
+export function ownerPrompts(lines) {
+  const out = [];
+  for (const l of lines || []) {
+    let o; try { o = typeof l === 'string' ? JSON.parse(l) : l; } catch { continue; }
+    const c = o?.message?.content;
+    if (o?.type !== 'user' || o.isSidechain || o.isMeta) continue;
+    if (Array.isArray(c) && c.some((x) => x?.type === 'tool_result')) continue;
+    const text = typeof c === 'string' ? c : Array.isArray(c) ? c.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+    if (text.trim() && !isHarnessGenerated(text)) out.push(text.slice(0, 8000));
+  }
+  return out;
+}
+
+/**
+ * The Stop-side read (Claude): owner prompts from the transcript tail plus the current prompt's text,
+ * which keys the per-prompt force counter. A transcript we cannot read yields no verdict (fail open).
+ */
+export function deferralAtStop({ message, transcriptPath, openPromises = 0, read }) {
+  if (typeof transcriptPath !== 'string' || !/\.jsonl$/i.test(transcriptPath) || !message) return null;
+  let lines;
+  try { lines = read(transcriptPath, { maxMs: 0 }); } catch { return null; }
+  const prompts = ownerPrompts(lines);
+  return { ...auditDeferral(message, { prompts, openPromises }), prompt: prompts.at(-1) || '' };
+}

package/plugin/scripts/hook-failures.mjs

@@ -0,0 +1,45 @@
+/**
+ * hook-failures.mjs — the reader half of "a failed advisory hook is a status line" (ADR-106).
+ *
+ * hook-shim.mjs appends one line to `<Brain home>/hook-failures.jsonl` whenever an advisory body
+ * exits nonzero, is killed, or cannot spawn (the writer is inlined there because the shim is
+ * boot-frozen). SessionStart calls failureLine() once: it summarizes failures recorded since the
+ * last summary and advances a byte cursor, so each failure is reported exactly once, never per fire.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const FAILURE_FILE = 'hook-failures.jsonl';
+export const FAILURE_LINE_PREFIX = '[RuvNet Brain — HOOK FAILURES]';
+const CURSOR_FILE = 'hook-failures.cursor';
+const MAX_READ = 256 * 1024;
+
+/** Summarize failures recorded after the cursor; advance it. Returns '' when there is nothing new. */
+export function failureLine(brainHome, { advance = true } = {}) {
+  const file = path.join(brainHome, FAILURE_FILE);
+  const cursorFile = path.join(brainHome, CURSOR_FILE);
+  let size;
+  try { size = fs.statSync(file).size; } catch { return ''; }
+  let offset = 0;
+  try { offset = Number(JSON.parse(fs.readFileSync(cursorFile, 'utf8')).offset) || 0; } catch { /* first read */ }
+  if (offset > size) offset = 0; // rotated by the writer
+  if (offset === size) return '';
+  const start = Math.max(offset, size - MAX_READ);
+  const buf = Buffer.alloc(size - start);
+  const fd = fs.openSync(file, 'r');
+  try { fs.readSync(fd, buf, 0, buf.length, start); } finally { fs.closeSync(fd); }
+  const rows = buf.toString('utf8').split('\n').flatMap((l) => { try { return l ? [JSON.parse(l)] : []; } catch { return []; } });
+  if (advance) { try { fs.writeFileSync(cursorFile, JSON.stringify({ offset: size })); } catch { /* re-reported next session */ } }
+  if (!rows.length) return '';
+  const byHook = new Map();
+  for (const r of rows) {
+    const id = String(r.hook || 'unknown').slice(0, 40);
+    const why = r.note ? String(r.note).split(':')[0].slice(0, 48) : r.error ? String(r.error).slice(0, 40) : r.signal ? String(r.signal) : `exit ${r.status}`;
+    const e = byHook.get(id) || { n: 0, why: new Set() };
+    e.n += 1; e.why.add(why); byHook.set(id, e);
+  }
+  const parts = [...byHook.entries()].sort((a, b) => b[1].n - a[1].n)
+    .map(([id, e]) => `${id} ×${e.n} (${[...e.why].slice(0, 3).join(', ')})`);
+  return `${FAILURE_LINE_PREFIX} ${rows.length} advisory hook run(s) did not complete or did not resolve since ${rows[0].at}: ${parts.join('; ')}. `
+    + `They failed open. Details: ${file}`;
+}

package/plugin/scripts/hook-shim.mjs

@@ -312,6 +312,52 @@ function resolveCodeRoot() {
   } catch { return null; }
 }
 
+/**
+ * A FAILED ADVISORY BODY IS RECORDED, NEVER SILENT (ADR-106). Advisory bodies return 0 to the host
+ * whatever happened (below), and the host shows no stderr on exit 0 — so a crashed Stop gate used to
+ * leave no trace anywhere (measured 2026-10-11: a throwing continuation-gate body → shim exit 0,
+ * 0 bytes, nothing on disk). One bounded JSONL line per failure, read and summarized ONCE by
+ * SessionStart (hook-failures.mjs owns the reader and the file name; tests/unit/hook-failures.test.mjs
+ * holds the two copies of the name together, the same way brain-off.test.mjs holds the sentinel).
+ * Inlined, not imported, because this file is boot-frozen. Never throws, never prints.
+ */
+function recordFailure(fields) {
+  try {
+    const file = path.join(BRAIN_HOME, 'hook-failures.jsonl');
+    fs.mkdirSync(BRAIN_HOME, { recursive: true });
+    try { if (fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`); } catch { /* absent */ }
+    fs.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), hook: hookId, ...fields })}\n`, { mode: 0o600 });
+  } catch { /* an unrecordable failure must not become a second one */ }
+}
+
+/**
+ * THE WATCHDOG (ADR-106). The host kills a hook at its registered timeout and DISCARDS its output
+ * (measured: "UserPromptSubmit hook … timed out after 10s — output discarded"). So the shim stops the
+ * body itself 1.5 s before the registered timeout of THIS command (read from the frozen manifest it
+ * was registered from; under Codex the stable wrapper owns the kill instead), records one
+ * `timed-out-internally` line in the failure ledger, writes NOTHING partial, and exits 0. SessionStart
+ * then reports it once. stdout is captured and forwarded only when the body finished on its own.
+ */
+const WATCHDOG_MARGIN_MS = 1500;
+function registeredTimeoutMs(extraArgs) {
+  try {
+    // Under Codex the stable wrapper already owns a process-group kill below the host timeout
+    // (codex-hook-wrapper.mjs); a second, shorter watchdog here would pre-empt it and orphan the
+    // body's own children. So the watchdog is Claude's, where nothing else stands before the host.
+    if (process.env.RUVNET_CODEX_BUDGET_MS || process.env.RUVNET_HOOK_HOST === 'codex') return Infinity;
+    const manifest = JSON.parse(fs.readFileSync(path.join(PLUGIN_ROOT, 'hooks', 'hooks.json'), 'utf8'));
+    const want = ['hook-shim.mjs"', hookId, ...extraArgs].join(' ');
+    let best = Infinity;
+    for (const groups of Object.values(manifest.hooks || {})) {
+      for (const g of groups || []) for (const h of g.hooks || []) {
+        const c = String(h.command || '').replace(/\s+\|\|\s+true\s*$/, '');
+        if ((c.endsWith(want) || c.includes(`${want} `)) && Number.isFinite(h.timeout)) best = Math.min(best, h.timeout * 1000);
+      }
+    }
+    return best;
+  } catch { return Infinity; }
+}
+
 // Run one hook body. No shell is ever involved: spawnSync with an argument array, interpreter
 // chosen from the typed table — never from input.
 function runHook(file, activeVersion = '') {
@@ -345,11 +391,15 @@ function runHook(file, activeVersion = '') {
     ...(BRAIN_OFF && entry.offBehavior === 'partial' ? { RUVNET_BRAIN_OFF: '1' } : {}),
   };
   const io = hookInput !== null
-    ? { stdio: ['pipe', 'inherit', 'inherit'], input: hookInput }
-    : { stdio: 'inherit' };
+    ? { stdio: ['pipe', 'pipe', 'inherit'], input: hookInput }
+    : { stdio: ['inherit', 'pipe', 'inherit'] };
+  const registered = registeredTimeoutMs(extraArgs);
+  const watchdog = Number.isFinite(registered) ? Math.max(500, registered - WATCHDOG_MARGIN_MS) : undefined;
   let sessionTimeout;
   if (hookId === 'session-start') {
     try {
+      // The restore plans inside the watchdog, so it finishes cleanly instead of being killed mid-write.
+      if (watchdog) env.RUVNET_SESSION_START_DEADLINE_AT = String(Math.min(Number(env.RUVNET_SESSION_START_DEADLINE_AT) || Infinity, Date.now() + watchdog));
       const deadlineAt = sessionStartDeadlineAt({ host: env.RUVNET_HOOK_HOST || 'claude', env,
         startedAt: performance.timeOrigin, pluginRoot: path.resolve(path.dirname(file), '..') });
       env.RUVNET_SESSION_START_DEADLINE_AT = String(deadlineAt);
@@ -361,12 +411,28 @@ function runHook(file, activeVersion = '') {
     }
   }
   if (advisoryBudgetFor(hookId, extraArgs[0] || '') === null) recordContextBudget({ handler: hookId, event: extraArgs[0] || hookId, scope: 'unknown-unframed-context-unchanged' }, env);
-  const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env,
-    ...(sessionTimeout ? { timeout: sessionTimeout, killSignal: 'SIGKILL' } : {}) });
+  const limit = Math.min(sessionTimeout || Infinity, watchdog || Infinity);
+  const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env, maxBuffer: 16 * 1024 * 1024,
+    ...(Number.isFinite(limit) ? { timeout: limit, killSignal: 'SIGKILL' } : {}) });
+  const timedOut = r.error?.code === 'ETIMEDOUT' || (r.signal === 'SIGKILL' && Number.isFinite(limit));
+  if (timedOut) {
+    recordFailure({ event: extraArgs[0] || '', error: 'timed-out-internally', limitMs: limit, signal: r.signal || null });
+    return 0; // nothing partial reaches the host; a killed body never refuses
+  }
+  if (r.stdout?.length) {
+    // Synchronous, because process.exit() follows and an async pipe write could be cut off.
+    for (let off = 0, spins = 0; off < r.stdout.length && spins < 2000;) {
+      try { off += fs.writeSync(1, r.stdout, off); } catch (e) { if (e.code !== 'EAGAIN') break; spins += 1; Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5); }
+    }
+  }
   if (r.error) {
+    recordFailure({ event: extraArgs[0] || '', error: String(r.error.code || r.error.message).slice(0, 120), signal: r.signal || null });
     process.stderr.write(`[hook-shim] ${entry.file}: ${r.error.message}\n`);
     return entry.mode === 'blocking' ? 1 : 0;
   }
+  if (r.signal || (entry.mode !== 'blocking' && r.status !== 0)) {
+    recordFailure({ event: extraArgs[0] || '', status: r.status, signal: r.signal || null });
+  }
   // Blocking hooks: the exit code IS the contract — ground-before-write, design-wall, protect-state,
   // and hijack-ruvnet at an opted-in managedMemoryBoundary (ADR-063). Advisory hooks: always 0.
   //