ruvnet-brain 4.5.16 → 4.5.17

package/plugin/scripts/grounding-turn-mark.mjs

@@ -18,11 +18,12 @@
  * tests/unit/ruvnet-gate1-pattern.test.mjs. ground-ruvnet.sh itself is UNTOUCHED by this file — it
  * is a hot, heavily-tuned, every-prompt hook, and this feature does not need to change it.
  *
- * WHAT THIS WRITES: a marker file under ~/.cache/ruvnet-brain/grounding-turn/<session_id>, whose
- * MTIME is the signal (same idiom grounding-stamp.sh and ground-before-write.sh already use for
- * their own 24h stamps — this reuses that mtime-comparison convention rather than inventing a new
- * one). Its CONTENT is a JSON blob for a human reading the cache, but the Stop-time gate only ever
- * trusts the mtime.
+ * WHAT THIS WRITES: a per-host/session marker carrying a random episode nonce, typed native identity,
+ * and a digest of the real project path. Same-turn queued prompts merge without changing the nonce;
+ * an observed new native turn or project replaces the episode. PostToolUse records successful search
+ * receipts through this same module and lock. Receipts retain only product terms and query/answer
+ * hashes. Stop consumes the marker and its bound receipt together; shared 24h freshness is not proof
+ * that this session searched during this turn.
  *
  * 2026-09-30 — TWO ARMS, ONE MARKER (ADR-0030 decision point #1). The marker now also records, as
  * JSON content, whether the prompt ASKS for a capability / feasibility / architecture judgement about
@@ -52,9 +53,11 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readStdinBounded, isHarnessGenerated } from './hook-input.mjs';
 import { ruvnetGate1Matches, groundingScopeMatches, groundingSubjectAllowed, normalizeGroundingScope, mergeGroundingScopes } from './ruvnet-gate1-pattern.mjs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { loadSettings, writeAtomic } from './user-settings.mjs';
 import { classifyPrompt, loadVocabulary } from './grounding-turn-evidence.mjs';
+import { answerOf, brainAnsweredResponse } from './grounding-answer.mjs';
+import { RUVNET_GATE1_TERMS } from './ruvnet-gate1-pattern.mjs';
 
 const HOME = os.homedir();
 export const MARKER_DIR = process.env.RUVNET_GROUNDING_TURN_DIR
@@ -63,9 +66,10 @@ export const MARKER_DIR = process.env.RUVNET_GROUNDING_TURN_DIR
 /** Filesystem-safe key for a session id — mirrors continuation-gate.mjs's own `replace(':', '-')`
  *  idiom, generalised: a session id is host-supplied and must never be trusted as a bare path
  *  segment. */
-export function markerPathFor(sessionId, dir = MARKER_DIR) {
+export function markerPathFor(sessionId, dir = MARKER_DIR, host = 'claude') {
+  if (!['claude', 'codex'].includes(host)) return null;
   const safe = String(sessionId ?? '').replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 200);
-  return safe ? path.join(dir, `${safe}.json`) : null;
+  return safe ? path.join(dir, `${host}-${safe}.json`) : null;
 }
 
 const promptOf = (hookInput) => String(hookInput?.prompt ?? hookInput?.user_prompt ?? hookInput?.input ?? '');
@@ -111,7 +115,8 @@ export function readMarker(file, { locked = false } = {}) {
     if (!m || typeof m !== 'object') return conservativeArm();
     return { gate1: uncertain || m.gate1 !== false, assert: !!m.assert, architecture: !!m.architecture,
       groundingScope: uncertain ? 'all' : normalizeGroundingScope(m.groundingScope ?? 'all').value,
-      subjects: Array.isArray(m.subjects) ? m.subjects.map(String) : [], at: m.at };
+      subjects: Array.isArray(m.subjects) ? m.subjects.map(String) : [], at: m.at,
+      host: m.host, nativeKind: m.nativeKind, sessionId: m.sessionId, turnId: m.turnId, projectId: m.projectId, nonce: uncertain ? null : m.nonce };
   } catch (e) { return uncertain || e.code !== 'ENOENT' ? conservativeArm() : null; }
 }
 
@@ -152,11 +157,16 @@ export function writeArm(file, arm, meta = {}, now = Date.now()) {
       let st = null;
       try { st = fs.lstatSync(file); } catch (e) { if (e.code !== 'ENOENT') throw e; }
       const prior = readMarker(file, { locked: true });
-      const prev = prior && (!st || now - st.mtimeMs < STALE_MS) ? prior : null;
-      const next = prev ? { ...meta, at: prev.at, gate1: prev.gate1 || arm.gate1, assert: prev.assert || arm.assert,
+      // Unknown native identity cannot inherit a proved episode or its search evidence.
+      // Pure scope-only callers may merge obligations, but carry no native identity to certify.
+      const scopeOnly = (value) => ['host', 'nativeKind', 'sessionId', 'turnId', 'projectId'].every(key => value?.[key] == null);
+      const sameEpisode = !prior || sameGroundingIdentity(prior, meta) || (scopeOnly(prior) && scopeOnly(meta));
+      const prev = prior && sameEpisode && (!st || now - st.mtimeMs < STALE_MS) ? prior : null;
+      const next = prev ? { ...meta, sessionId: prev.sessionId || meta.sessionId, turnId: prev.turnId || meta.turnId,
+        projectId: prev.projectId || meta.projectId, nonce: prev.nonce || randomUUID(), at: prev.at, gate1: prev.gate1 || arm.gate1, assert: prev.assert || arm.assert,
         architecture: prev.architecture || arm.architecture, groundingScope: mergeGroundingScopes(prev.groundingScope, arm.groundingScope),
         subjects: [...new Set([...prev.subjects, ...arm.subjects])].slice(0, 32) }
-        : { ...meta, at: new Date(now).toISOString(), ...arm };
+        : { ...meta, nonce: randomUUID(), at: new Date(now).toISOString(), ...arm };
       if (!owns()) throw new Error('marker owner changed');
       const staged = `${file}.staged-${randomUUID()}`;
       try {
@@ -165,6 +175,7 @@ export function writeArm(file, arm, meta = {}, now = Date.now()) {
         fs.renameSync(staged, file);
       } finally { try { fs.unlinkSync(staged); } catch {} }
       if (prev && st && owns()) fs.utimesSync(file, st.atime, st.mtime);
+      if (!prev && prior?.nonce) retireSearchEvidence(file, prior);
       return next;
     });
   } catch { return failSafeArm(file); }
@@ -172,7 +183,7 @@ export function writeArm(file, arm, meta = {}, now = Date.now()) {
 }
 
 /** Stop reads and consumes the same episode under the same exclusive protocol. */
-export function consumeMarker(file) {
+export function consumeMarker(file, expected = null) {
   // No episode directory is ordinary silence, not a lock failure or a grounding obligation.
   try { fs.lstatSync(path.dirname(file)); } catch (e) { if (e.code === 'ENOENT') return null; }
   let held;
@@ -182,37 +193,110 @@ export function consumeMarker(file) {
       if (observedLatches === null) throw new Error('marker latch read failed');
       const marker = readMarker(file, { locked: true });
       if (!marker) return null;
+      // An old native Stop must not retire a newer prompt's episode.
+      if (expected && ['host', 'nativeKind', 'sessionId', 'turnId', 'projectId'].some(key =>
+        marker[key] && expected[key] && marker[key] !== expected[key])) return null;
       let markerMs = Date.now();
       try { markerMs = fs.lstatSync(file).mtimeMs; } catch {}
+      // An unbound Stop cannot prove ownership of a fully typed episode. Preserve its proof,
+      // while exposing an UNKNOWN observation for this stop rather than consuming the successor.
+      if (expected && sameGroundingIdentity(marker, marker) && !sameGroundingIdentity(expected, expected)) {
+        return { marker, markerMs, ownershipUnknown: true };
+      }
       // Suspicious sidecars remain in place; never follow or retire their targets.
       if (observedLatches.some((flag) => fs.lstatSync(flag).isSymbolicLink())) return { marker: conservativeArm(), markerMs };
       if (!owns()) throw new Error('marker owner changed');
+      const searchEvidence = readSearchEvidence(file, marker);
       if (exists(file)) fs.unlinkSync(file);
+      retireSearchEvidence(file, marker);
       // Consume only witnessed latches; a contender publishes a new unique obligation.
       for (const flag of observedLatches) fs.unlinkSync(flag);
-      return { marker, markerMs };
+      return { marker, markerMs, searchEvidence };
     });
   } catch { failSafeArm(file); return { marker: conservativeArm(), markerMs: Date.now() }; }
   if (!held.ok) { failSafeArm(file); return { marker: conservativeArm(), markerMs: Date.now() }; }
   return held.value;
 }
 
+const sha256 = (value) => createHash('sha256').update(String(value)).digest('hex');
+/** Trusted adapter host selects its documented identity: Claude prompt_id, Codex turn_id.
+ * Never borrow the other field, and never copy a project path into the evidence receipt. */
+export function groundingIdentity(input, env = process.env) {
+  const host = ['claude', 'codex'].includes(env.RUVNET_HOOK_HOST) ? env.RUVNET_HOOK_HOST : null;
+  const nativeKind = host === 'claude' ? 'claude-prompt-id' : host === 'codex' ? 'codex-turn-id' : null;
+  const nativeId = host === 'claude' ? input.prompt_id : host === 'codex' ? input.turn_id : null;
+  let projectId = null;
+  try { projectId = sha256(fs.realpathSync(input.cwd || env.CLAUDE_PROJECT_DIR || process.cwd())); } catch {}
+  return { host, nativeKind, sessionId: input.session_id || null,
+    turnId: typeof nativeId === 'string' && nativeId.trim() ? nativeId : null, projectId };
+}
+function searchEvidencePath(file, marker) {
+  return /^[a-f0-9-]{36}$/.test(marker?.nonce || '') ? `${file}.search-${marker.nonce}` : null;
+}
+function retireSearchEvidence(file, marker) {
+  const receipt = searchEvidencePath(file, marker);
+  if (receipt) try { fs.unlinkSync(receipt); } catch {}
+}
+export const sameGroundingIdentity = (left, right) => ['host', 'nativeKind', 'sessionId', 'turnId', 'projectId'].every(key =>
+  typeof left?.[key] === 'string' && !!left[key] && left[key] === right?.[key]);
+/** Missing native identity is UNKNOWN; global product freshness cannot prove a turn. */
+export function readSearchEvidence(file, marker) {
+  const receipt = searchEvidencePath(file, marker);
+  if (!receipt) return null;
+  try {
+    const st = fs.lstatSync(receipt);
+    if (!st.isFile() || st.isSymbolicLink() || st.size > 32768) return null;
+    const row = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    if (row.schemaVersion !== 1 || !sameGroundingIdentity(row, marker) || row.nonce !== marker.nonce
+      || !Number.isSafeInteger(row.searchCount) || row.searchCount < 1
+      || !Array.isArray(row.terms) || !row.terms.every(term => typeof term === 'string')
+      || !Array.isArray(row.sources) || !row.sources.length
+      || !row.sources.every(source => /^[a-f0-9]{64}$/.test(source.querySha256) && /^[a-f0-9]{64}$/.test(source.answerSha256))) return null;
+    return row;
+  } catch { return null; }
+}
+/** Existing PostToolUse handler publishes only answered, native-turn-bound, redacted receipts. */
+export function recordSearchEvidence(input, env = process.env) {
+  if (!/(?:^|__)search_ruvnet$/.test(input.tool_name || '') || !brainAnsweredResponse(input.tool_response)) return false;
+  const identity = groundingIdentity(input, env), file = markerPathFor(input.session_id, MARKER_DIR, identity.host);
+  if (!file || !identity.turnId || !identity.projectId) return false;
+  const held = markerLock(file, owns => {
+    const marker = readMarker(file, { locked: true }), receipt = searchEvidencePath(file, marker);
+    if (!receipt || !sameGroundingIdentity(marker, identity)) return false;
+    const prior = readSearchEvidence(file, marker), query = String(input.tool_input?.query || '');
+    const terms = [...RUVNET_GATE1_TERMS, 'aidefence', 'agentic-qe', 'ruv-swarm']
+      .filter(term => query.toLowerCase().includes(term.toLowerCase()));
+    const row = { schemaVersion: 1, ...identity, nonce: marker.nonce, searchCount: (prior?.searchCount || 0) + 1,
+      terms: [...new Set([...(prior?.terms || []), ...terms])], sources: [...(prior?.sources || []),
+        { querySha256: sha256(query), answerSha256: sha256(answerOf(input.tool_response)) }].slice(-32) };
+    if (!owns()) return false;
+    writeAtomic(receipt, JSON.stringify(row) + '\n');
+    return true;
+  });
+  return held.ok && held.value === true;
+}
+
 async function main() {
   let hookInput;
   try {
-    const raw = (await readStdinBounded()).toString('utf8');
+    const raw = (await readStdinBounded({ maxBytes: process.argv.includes('--record-search') ? 2097152 : 65536 })).toString('utf8');
     hookInput = JSON.parse(raw || '{}');
   } catch { process.exit(0); }
 
+  if (process.argv.includes('--record-search')) {
+    try { recordSearchEvidence(hookInput); } catch {}
+    process.exit(0);
+  }
+
   let arm = null;
   const scope = loadSettings().values.groundingScope;
   try { arm = armFor(hookInput, loadVocabulary(), scope); } catch { arm = shouldMark(hookInput, scope) ? { gate1: true, assert: false, architecture: false, subjects: [], groundingScope: scope } : null; }
   if (!arm) process.exit(0);
 
-  const file = markerPathFor(hookInput.session_id);
+  const identity = groundingIdentity(hookInput), file = markerPathFor(hookInput.session_id, MARKER_DIR, identity.host);
   if (!file) process.exit(0);
   try {
-    writeArm(file, arm, { sessionId: hookInput.session_id, turnId: hookInput.turn_id || hookInput.prompt_id || null });
+    writeArm(file, arm, identity);
   } catch { /* fail-open: no marker means the Stop gate stays silent, never a false block */ }
   process.exit(0);
 }

package/plugin/scripts/hook-context-budget.mjs

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const FRAME_KIND = 'brain-owned-context-blocks';
+const digest = (value) => crypto.createHash('sha256').update(value).digest('hex');
+const bytes = (value) => Buffer.byteLength(value, 'utf8');
+export function advisoryBudgetFor(handler, event) {
+  if (handler === 'ground-ruvnet') return 8192;
+  if (handler === 'decision-gate') return 4096;
+  if (handler === 'unprompted-speech') return event === 'UserPromptSubmit' ? 2048 : 1024;
+  return null;
+}
+export function contextBlock(text, { id = 'block', critical = false } = {}) {
+  return { id: `${id.replace(/[^a-zA-Z0-9:_-]/g, '_').slice(0, 64)}:${digest(text).slice(0, 16)}`, text, critical };
+}
+export function contextFrame(handler, event, blocks) {
+  return { kind: FRAME_KIND, schemaVersion: 1, handler, event, blocks };
+}
+export function readContextFrame(raw) {
+  let value; try { value = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch { return null; }
+  if (value?.kind !== FRAME_KIND || value.schemaVersion !== 1 || !Array.isArray(value.blocks)
+    || Object.keys(value).some((key) => !['kind','schemaVersion','handler','event','blocks'].includes(key))
+    || typeof value.handler !== 'string' || typeof value.event !== 'string'
+    || value.blocks.some((block) => typeof block?.id !== 'string' || block.id.length > 96
+      || typeof block.text !== 'string' || typeof block.critical !== 'boolean')) return null;
+  return value;
+}
+export function selectContextFrame(frame, limit = advisoryBudgetFor(frame.handler, frame.event)) {
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new Error('No safe advisory allocation');
+  const seen = new Set(); const selected = []; const deferred = [];
+  let advisoryBytes = 0; let criticalBytes = 0;
+  for (const block of frame.blocks) {
+    const identity = JSON.stringify(block);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    if (block.critical) { selected.push(block); criticalBytes += bytes(block.text) + 2; continue; }
+    const cost = bytes(block.text) + 2;
+    if (advisoryBytes + cost > limit) deferred.push(block.id);
+    else { selected.push(block); advisoryBytes += cost; }
+  }
+  const selectedIds = selected.map((block) => block.id);
+  return { frame: { ...frame, blocks: selected }, receipt: { handler: frame.handler, event: frame.event,
+    budgetBytes: limit, advisoryBytes, criticalBytes, criticalExemption: criticalBytes > 0,
+    selectedIds: selectedIds.slice(0, 8), selectedCount: selectedIds.length,
+    deferredIds: deferred.slice(0, 8), deferredCount: deferred.length,
+    idsDigest: digest(JSON.stringify({ selectedIds, deferred })), scope: 'typed-advisories-per-event-not-whole-turn' } };
+}
+export function renderContextFrame(frame, { rawText = false } = {}) {
+  const text = frame.blocks.map((block) => block.text).join('\n\n');
+  return rawText ? text : JSON.stringify({ hookSpecificOutput: { hookEventName: frame.event, additionalContext: text } });
+}
+export function recordContextBudget(receipt, env = process.env) {
+  if (env.RUVNET_BRAIN_METER === '0') return;
+  try {
+    const directory = path.join(env.XDG_CACHE_HOME || path.join(env.HOME || os.homedir(), '.cache'), 'ruvnet-brain');
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (fs.lstatSync(directory).isSymbolicLink()) return;
+    const file = path.join(directory, 'token-ledger.jsonl');
+    if (fs.existsSync(file)) { const stat = fs.lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return; }
+    const line = JSON.stringify({ ts: new Date().toISOString(), source: 'hook', class: 'context-budget', ...receipt });
+    if (bytes(line) > 2048) return;
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    try { fs.writeSync(fd, line + '\n'); } finally { fs.closeSync(fd); }
+  } catch { /* Metrics never alter a guard or permission decision. */ }
+}
+export function emitOwnedContext(frame, { env = process.env, rawText = false } = {}) {
+  const selected = selectContextFrame(frame);
+  recordContextBudget(selected.receipt, env);
+  return env.RUVNET_CODEX_CONTEXT_FRAMES === '1' ? JSON.stringify(selected.frame) : renderContextFrame(selected.frame, { rawText });
+}
+
+let direct = false;
+try { direct = fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
+if (direct && process.argv[2] === '--ground-dir') {
+  const directory = process.argv[3]; const blocks = [];
+  for (const id of fs.readdirSync(directory).filter((id) => /^\d+-\d+-[\w-]+$/.test(id)).sort((a, b) => Number(a.split('-')[0]) - Number(b.split('-')[0]))) {
+    let picked; try { picked = fs.readFileSync(path.join(directory, id + '.pick'), 'utf8').trim(); } catch { continue; }
+    if (!['full', 'short'].includes(picked)) continue;
+    const text = fs.readFileSync(path.join(directory, id + (picked === 'short' ? '.short' : '')), 'utf8');
+    blocks.push(contextBlock(text, { id, critical: id.split('-')[1] === '0' }));
+  }
+  try {
+    const deferred = fs.readFileSync(path.join(directory, '.budget-deferred'), 'utf8').split('\n').filter(Boolean);
+    if (deferred.length) recordContextBudget({ handler: 'ground-ruvnet', event: 'UserPromptSubmit', scope: 'pre-mark-budget-deferral', deferredCount: deferred.length, deferredIds: deferred.slice(0, 8) });
+  } catch { /* No optional block was deferred by the existing assembler. */ }
+  process.stdout.write(emitOwnedContext(contextFrame('ground-ruvnet', 'UserPromptSubmit', blocks), { rawText: true }));
+}

package/plugin/scripts/hook-registry.mjs

@@ -69,6 +69,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
+import { createRequire, isBuiltin } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -488,6 +490,130 @@ export function census(reg) {
   };
 }
 
+const auditDigest = value => crypto.createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex');
+
+/** Contract IDs already distinguish event and host; foreign commands never inherit ownership. */
+export function canonicalHookAuditId(record) {
+  const host = record.layer === 'codex' ? 'codex' : 'claude';
+  const id = record.shimId ?? record.codexHookId;
+  return ['plugin', 'codex'].includes(record.layer) && id ? `${host}/${record.event}/${id}`
+    : `foreign/${host}/${auditDigest([record.layer, record.file, record.event, record.command]).slice(0, 24)}`;
+}
+
+/** A hash is integrity evidence only. No PASS or readComplete flag authorizes semantic closure. */
+export function hookAuditReviewStatus(entry, review) {
+  if (!review || typeof review.reviewer !== 'string' || !review.reviewer || !Array.isArray(review.readCoverage)
+    || !Array.isArray(review.findings) || !['source-read', 'subprocess', 'native'].includes(review.verificationStrength)) {
+    return { state: 'UNKNOWN', reason: 'substantive source-bound reviewer evidence missing' };
+  }
+  const evidence = { reviewer: review.reviewer, findings: review.findings, verificationStrength: review.verificationStrength,
+    reference: review.reference ?? null, readCoverage: review.readCoverage };
+  if (review.fingerprint !== entry.fingerprint) return { ...evidence, state: 'STALE', reason: 'registration, source, import or configuration fingerprint changed' };
+  const uncovered = entry.inputs.filter(input => input.sha256 && !review.readCoverage.some(read => read.path === input.path
+    && read.sha256 === input.sha256 && typeof read.notes === 'string' && read.notes.trim()
+    && Array.isArray(read.lineRanges) && read.lineRanges.some(range => Array.isArray(range) && range.length === 2
+      && Number.isInteger(range[0]) && Number.isInteger(range[1]) && range[0] > 0 && range[1] >= range[0] && range[1] <= input.lines)));
+  if (review.state !== 'complete' || uncovered.length || !Array.isArray(review.contractDimensions)
+    || !['purpose', 'inputs', 'outputs', 'authority', 'scope', 'failure', 'budgets', 'dependencies', 'parity'].every(dimension => review.contractDimensions.includes(dimension))) {
+    return { ...evidence, state: 'UNKNOWN', reason: 'review coverage remains open', uncovered: uncovered.map(input => input.path) };
+  }
+  return { ...evidence, state: 'REVIEW_RECORDED',
+    limitation: 'reviewer declaration bound to source; not native execution or promotion authority' };
+}
+
+/** Read-only audit of the existing registry. This does not resolve every effective native layer. */
+export function buildHookAudit({ repo = REPO, home = os.homedir(), includeMachine = true,
+  registry = buildRegistry({ repo, home, includeMachine }), configFiles = [], reviews = [], sourceSha = null } = {}) {
+  repo = fs.realpathSync(repo);
+  const scriptRoot = fs.existsSync(path.join(repo, 'plugin/scripts/hook-shim.mjs')) ? path.join(repo, 'plugin/scripts') : path.join(repo, 'scripts');
+  const contractsFile = registry.contractsFile;
+  const cache = new Map(), texts = new Map();
+  const input = (file, kind) => {
+    const name = file.startsWith(repo + path.sep) ? path.relative(repo, file).split(path.sep).join('/') : file;
+    if (cache.has(file)) return { ...cache.get(file), kind };
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || fs.realpathSync(file) !== file || stat.size > 1024 * 1024) throw new Error('unbounded or noncanonical source');
+      const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      let bytes;
+      try { bytes = Buffer.alloc(stat.size); let offset = 0;
+        while (offset < bytes.length) { const count = fs.readSync(fd, bytes, offset, Math.min(65536, bytes.length - offset), offset); if (!count) throw new Error('source truncated'); offset += count; }
+        const after = fs.fstatSync(fd), current = fs.lstatSync(file);
+        if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ino !== stat.ino || after.dev !== stat.dev
+          || current.ino !== stat.ino || current.dev !== stat.dev || current.size !== stat.size || current.mtimeMs !== stat.mtimeMs || current.isSymbolicLink()) throw new Error('source changed during audit');
+      } finally { fs.closeSync(fd); }
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+      const row = { path: name, sha256: auditDigest(bytes), bytes: bytes.length, lines: text.split('\n').length, uid: stat.uid };
+      texts.set(file, text);
+      cache.set(file, row); return { ...row, kind };
+    } catch (error) { return { path: name, sha256: null, kind, state: error.code === 'ENOENT' ? 'absent' : 'unavailable', reason: error.code === 'ENOENT' ? null : String(error.message) }; }
+  };
+  input(contractsFile, 'contract-declaration');
+  let document; try { document = JSON.parse(texts.get(contractsFile)); } catch { document = {}; }
+  const contracts = Array.isArray(document.contracts) ? document.contracts : [];
+  const packageFile = path.join(repo, 'package.json');
+  input(packageFile, 'package-declaration');
+  let packageDeclaration; try { packageDeclaration = JSON.parse(texts.get(packageFile)); } catch { packageDeclaration = null; }
+  const entries = registry.records.map(record => {
+    const host = record.layer === 'codex' ? 'codex' : 'claude', dispatchId = record.shimId ?? record.codexHookId;
+    const contract = contracts.find(row => row.id === dispatchId && row.event === record.event && row.hosts?.includes(host));
+    const purpose = document._eventOwners?.find(row => row.owner === dispatchId && row.event === record.event && row.hosts?.includes(host));
+    const seeds = [record.file, contractsFile, path.join(scriptRoot, 'hook-shim.mjs'), path.join(scriptRoot, record.handler ?? 'missing-body')];
+    if (host === 'codex') seeds.push(path.join(scriptRoot, 'codex-hook-wrapper.mjs'), path.join(scriptRoot, 'codex-hook-adapter.mjs'));
+    const refs = new Map(), unresolved = [], pending = [...seeds], seen = new Set(), allowedRoots = new Set([repo]);
+    while (pending.length && seen.size < 512) {
+      const file = path.resolve(pending.shift()); if (seen.has(file)) continue; seen.add(file);
+      const ref = input(file, 'source'); refs.set(ref.path, ref);
+      if (!ref.sha256 || !/\.(?:mjs|cjs|js|sh)$/.test(file)) continue;
+      const text = texts.get(file);
+      // Same literal relative-import mechanism used by the shipped-package falsifier. Dynamic
+      // resolution remains explicit incomplete evidence; this is never semantic read coverage.
+      for (const match of text.matchAll(/(?:from|import|require)\s*\(?\s*['"](\.[^'"]+)['"]/g)) {
+        const dependency = path.resolve(path.dirname(file), match[1]);
+        if ([...allowedRoots].some(root => dependency.startsWith(root + path.sep))) pending.push(dependency);
+        else unresolved.push({ file: ref.path, kind: 'outside-root-import', specifier: match[1] });
+      }
+      for (const match of text.matchAll(/(?:from|import|require)\s*\(?\s*['"]([^.'"][^'"]*)['"]/g)) {
+        if (isBuiltin(match[1])) continue;
+        try {
+          const resolved = createRequire(file).resolve(match[1]);
+          let directory = path.dirname(resolved);
+          while (!fs.existsSync(path.join(directory, 'package.json')) && directory !== path.dirname(directory)) directory = path.dirname(directory);
+          if (!fs.existsSync(path.join(directory, 'package.json'))) throw new Error('package declaration missing');
+          allowedRoots.add(directory); pending.push(resolved, path.join(directory, 'package.json'));
+        } catch { unresolved.push({ file: ref.path, kind: 'unresolved-package-import', specifier: match[1] }); }
+      }
+      if (/\bimport\s*\(\s*[^'"\s]/.test(text)) unresolved.push({ file: ref.path, kind: 'dynamic-import' });
+      if (/\.(?:sh)$/.test(file)) unresolved.push({ file: ref.path, kind: 'shell-child/config-resolution-requires-review' });
+    }
+    if (pending.length) unresolved.push({ kind: 'source-closure-bound' });
+    for (const file of configFiles) { const ref = input(path.resolve(file), 'configuration'); refs.set(ref.path, ref); }
+    const pkg = input(packageFile, 'package-declaration'); refs.set(pkg.path, pkg);
+    const inputs = [...refs.values()].sort((a, b) => a.path.localeCompare(b.path));
+    let declarationMatches = false;
+    try { declarationMatches = ['plugin', 'codex'].includes(record.layer) && readRegistrations(record.file).some(row => row.event === record.event
+      && row.matcher === record.matcher && row.command === record.command && row.timeout === record.timeout); } catch { /* ownership remains unknown */ }
+    const managed = declarationMatches && contract && packageDeclaration?.name === 'ruvnet-brain' && record.file.startsWith(repo + path.sep)
+      && inputs.every(ref => ref.sha256 && ref.uid === process.getuid?.());
+    const registration = { host, event: record.event, matcher: record.matcher, commandSha256: auditDigest(record.command), timeout: record.timeout,
+      asyncRewake: record.asyncRewake, condition: record.if, dispatchId, contract };
+    const entry = { id: canonicalHookAuditId(record), host, event: record.event, dispatchId, layer: record.layer,
+      purpose: purpose?.responsibility ?? null, intendedHosts: contract?.hosts ?? [], declaredMode: record.mode,
+      controlGuarantee: dispatchId === 'capacity-aware-parallel-work' && record.mode === 'advisory' ? 'advisory-only' : 'not-proven-by-inventory',
+      ownership: { status: managed ? 'CORRELATED_PACKAGE_SOURCE' : 'UNKNOWN', mutationAuthority: false,
+        proof: managed ? { declarationMatches, packageName: packageDeclaration.name, packageVersion: packageDeclaration.version, canonicalRoot: repo, uid: process.getuid() } : null },
+      registration, inputs, dependencyCoverage: { state: 'PARTIAL_STATIC', unresolved,
+        limitation: 'literal reachable imports and resolved package entries only; dynamic dispatch and runtime configuration require explicit reviewer coverage' },
+      fingerprint: auditDigest({ registration, inputs, unresolved }), nativeExecution: 'UNKNOWN' };
+    entry.review = hookAuditReviewStatus(entry, reviews.find(review => review.id === entry.id));
+    return entry;
+  });
+  const duplicates = entries.filter((entry, index) => entries.findIndex(other => other.id === entry.id) !== index).map(entry => entry.id);
+  return { schemaVersion: 1, kind: 'hook-registry-source-audit', sourceSha, entries, duplicates, registryErrors: registry.errors,
+    inventoryCoverage: 'existing registry discovery only; local/managed/native-active overlays are not exhaustive',
+    auditSha256: auditDigest(entries), promotionAuthority: false };
+}
+
 // ── THE MESH INVARIANTS (ADR-055 §7) ────────────────────────────────────────────────────────────
 //
 // Each is a PURE function from records → findings, for three reasons that all matter:
@@ -630,7 +756,9 @@ const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWit
 if (invokedDirectly) {
   const includeMachine = !process.argv.includes('--machine=0') && process.env.CI !== 'true';
   const reg = buildRegistry({ includeMachine });
-  if (process.argv.includes('--json')) {
+  if (process.argv.includes('--audit-json')) {
+    process.stdout.write(`${JSON.stringify(buildHookAudit({ registry: reg, includeMachine }), null, 2)}\n`);
+  } else if (process.argv.includes('--json')) {
     process.stdout.write(`${JSON.stringify(reg.records, null, 2)}\n`);
   } else if (process.argv.includes('--lint')) {
     const found = lintAll(reg);

package/plugin/scripts/hook-shim.mjs

@@ -31,9 +31,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { advisoryBudgetFor, recordContextBudget } from './hook-context-budget.mjs';
 import { fileURLToPath } from 'node:url';
 import { resolveBash, skipNoBash } from './hook-shim-bash.mjs';
 import { developmentHooksSuspended } from './development-maintenance.mjs';
+import { sessionStartDeadlineAt } from './session-start-budget.mjs';
 
 if (developmentHooksSuspended()) process.exit(0);
 
@@ -186,7 +188,7 @@ const TABLE = {
 
 const hookId = process.argv[2];
 // Native Claude supplies this exact registered plugin root; do not guess a host from absence.
-if (['session-snapshot', 'continuation-gate'].includes(hookId)
+if (['session-snapshot', 'continuation-gate', 'grounding-turn-mark', 'grounding-stamp', 'grounding-turn-gate'].includes(hookId)
     && process.env.RUVNET_HOOK_HOST === undefined && process.env.CLAUDE_PLUGIN_ROOT) {
   try {
     const ownPluginRoot = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'));
@@ -338,13 +340,29 @@ function runHook(file, activeVersion = '') {
     // The node running THIS shim, for bash bodies that need node (grounding-stamp.sh's verdict) on a
     // machine where `node` is not on the PATH the host hands its hooks. Additive: older bodies ignore it.
     RUVNET_NODE_BIN: process.execPath,
+    ...(['unprompted-speech', 'ground-ruvnet', 'decision-gate'].includes(hookId) ? { RUVNET_HOOK_CONTEXT_BUDGET: '1' } : {}),
     ...(activeVersion ? { RUVNET_BRAIN_ACTIVE_VERSION: activeVersion } : {}),
     ...(BRAIN_OFF && entry.offBehavior === 'partial' ? { RUVNET_BRAIN_OFF: '1' } : {}),
   };
   const io = hookInput !== null
     ? { stdio: ['pipe', 'inherit', 'inherit'], input: hookInput }
     : { stdio: 'inherit' };
-  const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env });
+  let sessionTimeout;
+  if (hookId === 'session-start') {
+    try {
+      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);
+      sessionTimeout = Math.floor(deadlineAt - Date.now());
+      if (sessionTimeout < 1) throw new Error('SessionStart deadline exhausted before restore');
+    } catch (error) {
+      process.stderr.write(`[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] ${error.message}; restoration was not attempted.\n`);
+      return 0;
+    }
+  }
+  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' } : {}) });
   if (r.error) {
     process.stderr.write(`[hook-shim] ${entry.file}: ${r.error.message}\n`);
     return entry.mode === 'blocking' ? 1 : 0;

package/plugin/scripts/lesson-gate.mjs

@@ -313,7 +313,7 @@ const effectiveTriggers = command === null
 const seen = new Set();
 const candidates = [];
 for (const t of effectiveTriggers) {
-  for (const l of lessonsFor(t, lessons, { limit: 3 })) {
+  for (const l of lessonsFor(t, lessons.filter((l) => isHome(l) || isUniversal(l)), { limit: 3 })) {
     if (seen.has(l.id)) continue;
     // Away from home, only a lesson with cross-project evidence may speak.
     if (!isHome(l) && !isUniversal(l)) continue;

package/plugin/scripts/project-capture-queue.mjs

@@ -264,38 +264,42 @@ export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn
  */
 export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_LOCK_TOKEN || null, budgetMs = DETACHED_REPLAY_BUDGET_MS,
   makeStoreFactory = boundedStoreFactory, now = Date.now, runCapture = runSessionSnapshotHook, onClaim = null,
-  captureNormalized = captureNormalizedTransition, onCaptured = null, env = process.env } = {}) {
-  const deadlineAt = now() + budgetMs;
+  captureNormalized = captureNormalizedTransition, onCaptured = null, env = process.env,
+  deadlineAt: inheritedDeadlineAt = Infinity, signal } = {}) {
+  const deadlineAt = Math.min(inheritedDeadlineAt, now() + budgetMs);
+  if (signal?.aborted || now() >= deadlineAt) return 0;
   if (developmentHooksSuspended(projectDir)) return 0;
   if (operatorProgressionSuspension(env)) { if (token) releaseReplayLock(projectDir, token); return 0; }
   const brainHome = env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
   try {
-    const consent = resolveTurnDb({ projectDir, brainHome });
+    const consent = resolveTurnDb({ projectDir, brainHome, deadlineAt, signal });
     if (consent.skipped && !consent.skipped.startsWith('no project memory db')) return 0;
   } catch { return 0; }
+  if (signal?.aborted || now() >= deadlineAt) return 0;
   let held = token || takeReplayLock(projectDir);
   let replayed = 0;
-  for (let round = 0; held && round < 8 && now() < deadlineAt; round += 1) {
+  for (let round = 0; held && round < 8 && now() < deadlineAt && !signal?.aborted; round += 1) {
     try {
       if (!adoptReplayLock(projectDir, held)) return replayed;
       reclaimOrphans(projectDir);
-      const resolution = resolveProjectStore({ projectDir });
-      const store = makeStoreFactory(deadlineAt)({ projectDir, env, requestedStorePath: resolution.canonicalAgentDbPath });
+      const resolution = resolveProjectStore({ projectDir, deadlineAt });
+      const store = makeStoreFactory(deadlineAt)({ projectDir, env, requestedStorePath: resolution.canonicalAgentDbPath, deadlineAt, signal });
       for (const snapshot of store.outbox.pendingSnapshots()) {
         if (operatorProgressionSuspension(env)) return replayed;
-        if (now() >= deadlineAt) return replayed;
+        if (signal?.aborted || now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
-        store.captureFrozen(snapshot, { canCommit: () => refreshReplayLock(projectDir, held) });
+        store.captureFrozen(snapshot, { canCommit: () => !signal?.aborted && now() < deadlineAt && refreshReplayLock(projectDir, held) });
         // captureFrozen commits only the verified key, retaining conflicting original history.
         replayed += 1;
       }
       for (const file of queuedCaptures(projectDir)) {
         if (operatorProgressionSuspension(env)) return replayed;
-        if (now() >= deadlineAt) return replayed;
+        if (signal?.aborted || now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
         const claimed = claimQueued(file);
         if (!claimed) continue;
         onClaim?.(claimed);
+        if (signal?.aborted || now() >= deadlineAt) { returnClaim(claimed); return replayed; }
         if (!refreshReplayLock(projectDir, held)) {
           returnClaim(claimed);
           return replayed;
@@ -308,16 +312,17 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
           if (job) {
             // Pre-upgrade raw queues lack origin identity and cannot be truthfully reconstructed.
             if (runCapture === runSessionSnapshotHook && (!job.originProjectDir || (!job.payload?.projectProgression && !job.payload?.normalizedTransition))) { returnClaim(claimed); return replayed; }
-            const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome });
+            const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome, deadlineAt, signal });
             if (developmentHooksSuspended(job.originProjectDir || projectDir)
               || (consent.skipped && !consent.skipped.startsWith('no project memory db'))) { returnClaim(claimed); return replayed; }
             const options = { rawInput: JSON.stringify(job.payload), host: job.host, env,
-              budgetMs: Math.max(0, deadlineAt - now()), makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
+              budgetMs: Math.max(0, deadlineAt - now()), deadlineAt, signal,
+              makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
               captureTurn: () => ({ recorded: false, skipped: 'detached replay' }),
               captureEvents: () => ({ recorded: 0, skipped: 'detached replay' }) };
             const result = job.payload?.normalizedTransition ? captureNormalized(job, options)
               : runCapture(job.originProjectDir || projectDir, job.event, options);
-            committed = result?.progressionCaptured === true && Boolean(result.receipt);
+            committed = now() < deadlineAt && !signal?.aborted && result?.progressionCaptured === true && Boolean(result.receipt);
             if (committed) onCaptured?.(result);
           }
         } catch { /* retain the queue until an exact-readback receipt exists */ }
@@ -327,7 +332,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
     } catch { /* the debt stays durable; the next boundary hands it on again */ } finally {
       releaseReplayLock(projectDir, held);
     }
-    held = now() < deadlineAt && queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
+    held = !signal?.aborted && now() < deadlineAt && queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
   }
   if (held) releaseReplayLock(projectDir, held);
   return replayed;
@@ -338,9 +343,11 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
 export function drainCaptureQueue({ projectDir, budgetMs = 1000, ...options } = {}) {
   if (operatorProgressionSuspension(options.env || process.env)) return { state: 'suspended', replayed: 0, pending: null };
   const startedAt = Date.now();
-  const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)) });
+  const deadlineAt = Math.min(options.deadlineAt ?? Infinity, startedAt + budgetMs);
+  if (options.signal?.aborted || startedAt >= deadlineAt) return { state: 'pending', replayed: 0, pending: null, reason: 'restore deadline exceeded' };
+  const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)), deadlineAt });
   const root = resolution.projectRoot;
-  const replayed = runOutboxReplay({ ...options, projectDir: root, budgetMs: Math.max(0, budgetMs - (Date.now() - startedAt)) });
+  const replayed = runOutboxReplay({ ...options, deadlineAt, projectDir: root, budgetMs: Math.max(0, deadlineAt - Date.now()) });
   let outboxPending = 0;
   try { outboxPending = new ProgressionOutbox({ projectRoot: root }).pendingSnapshots().length; } catch { return { state: 'degraded', replayed, pending: null }; }
   const pending = queuedWork(root) + outboxPending;