ruvnet-brain 4.5.16 → 4.6.0

package/plugin/scripts/capability-registry.mjs

@@ -356,6 +356,45 @@ function countCaptureCommands(groups) {
   return n;
 }
 
+/** Read declared capture wiring only; plugin cache presence is not activation or execution. */
+export function captureDeclarationCounts({ home = HOME, project = process.cwd() } = {}) {
+  const counts = { pre: 0, end: 0, unknown: false };
+  const enabled = {};
+  const settings = [...new Set([path.join(home, '.claude/settings.json'), path.join(project, '.claude/settings.json'), path.join(project, '.claude/settings.local.json')])];
+  const add = (hooks) => {
+    if (hooks !== undefined && (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))) { counts.unknown = true; return; }
+    const pre = countCaptureCommands(hooks?.PreCompact), end = countCaptureCommands(hooks?.SessionEnd);
+    if (pre === null || end === null) counts.unknown = true;
+    else { counts.pre += pre; counts.end += end; }
+  };
+  for (const file of settings) {
+    const result = readJSON(file);
+    if (result.missing) continue;
+    if (result.err) { counts.unknown = true; continue; }
+    add(result.value?.hooks);
+    if (result.value?.enabledPlugins !== undefined && (!result.value.enabledPlugins || typeof result.value.enabledPlugins !== 'object' || Array.isArray(result.value.enabledPlugins))) counts.unknown = true;
+    else Object.assign(enabled, result.value?.enabledPlugins || {});
+  }
+  const active = Object.entries(enabled).filter(([, value]) => value === true).map(([id]) => id);
+  if (active.length) {
+    const installed = readJSON(path.join(home, '.claude/plugins/installed_plugins.json'));
+    if (installed.missing || installed.err || !installed.value?.plugins || typeof installed.value.plugins !== 'object') counts.unknown = true;
+    else for (const id of active) {
+      const entries = installed.value.plugins[id];
+      if (!Array.isArray(entries) || !entries.length) { counts.unknown = true; continue; }
+      const candidates = entries.filter((entry) => entry?.scope !== 'project' || entry.projectPath === project);
+      if (candidates.length !== 1) { counts.unknown = true; continue; }
+      for (const entry of candidates) {
+        if (typeof entry?.installPath !== 'string' || !path.isAbsolute(entry.installPath)) { counts.unknown = true; continue; }
+        const manifest = readJSON(path.join(entry.installPath, 'hooks/hooks.json'));
+        if (manifest.missing || manifest.err) { counts.unknown = true; continue; }
+        add(manifest.value?.hooks);
+      }
+    }
+  }
+  return counts;
+}
+
 // ── The capabilities ─────────────────────────────────────────────────────────────────────────────
 // Ordered by blast radius: the ones whose dormancy costs the most sit at the top, because this list
 // is rendered in order and nobody reads to the bottom.
@@ -578,70 +617,15 @@ export const CAPABILITIES = [
     // already standing in a ruvnet-brain checkout; everyone else got `Cannot find module`. A real
     // executor behind an unreachable path is a dead button with extra steps.
     turnOn: selfTurnOn('Route one read-only task through the cheap path', 'route-cheap.mjs', '--task "<text>"'),
-    detect() {
-      const bin = path.join(HOME, '.npm-global/bin/agentic-flow');
-      const installed = fs.existsSync(bin);
-      const receipts = process.env.METAHARNESS_RECEIPTS || path.join(HOME, '.claude/metaharness/routing-receipts.jsonl');
-      const n = lineCount(receipts);
-
-      // Receipts are the proof, and they outrank installation: a receipt file with lines means this
-      // genuinely ran, even if the binary later moved. Absence of the binary AND of receipts is the
-      // only honest 'absent'.
-      if (n === null && !fs.existsSync(receipts)) {
-        return installed
-          ? row(STATE.OFF, 'agentic-flow is installed but no routing receipt has ever been written — the cheap path exists and has never been used')
-          : row(STATE.ABSENT, 'agentic-flow is not installed and no routing receipts exist, so cheap routing has never been set up here');
-      }
-      if (n === null) return row(STATE.UNKNOWN, 'the routing receipt ledger exists but could not be read — usage not checked');
-      if (n === 0) return row(STATE.OFF, 'the routing receipt ledger is present but empty — no task has been routed to a cheaper model');
-      const age = daysSince(mtimeOf(receipts));
-
-      // THE AGE NOW DECIDES, INSTEAD OF DECORATING. This line used to return ON for any n > 0 and
-      // merely MENTION the age in the evidence — so a router with 38 receipts and nothing invoking it
-      // for a fortnight read as healthy. We were holding the disproving fact and printing it politely.
-      //
-      // 7 days: this path should fire on ordinary sessions, so a full quiet week means something
-      // upstream stopped calling it — not that the user had a light week. Measured on this machine
-      // 2026-07-24: 38 receipts, last one 4.8 days old, and the PreToolUse gate that invokes it
-      // (plugin/scripts/route-dispatch.sh, written 2026-07-13) had never been added to settings.json.
-      // Built, correct, and unwired — which no state in this registry could previously express.
-      // MEASURE THE CAUSE, NOT A SYMPTOM. An age threshold alone is a proxy and it FAILED on the real
-      // case: measured 2026-07-24, the last receipt was 5 days old — under any sane horizon — while the
-      // router was in fact never being consulted at all. A quiet week and a severed wire look identical
-      // from the receipt file, so read the wire directly.
-      //
-      // Two things must both be true for the host-limited dispatch audit to record anything: a
-      // PreToolUse hook on subagent dispatch and the opt-in profile it refuses to act without
-      // (route-dispatch.sh exits 0 when
-      // profile.json is absent). Either missing ⇒ the router cannot fire, regardless of how healthy
-      // the receipt ledger looks.
-      const profile = fs.existsSync(path.join(HOME, '.claude/model-router/profile.json'));
-      // ONE READING OF THE WIRING, from the module that owns it — see dispatchGateWiring(). Scanning
-      // settings.json here was a second, narrower implementation of that question, and it answered
-      // "not wired" for every plugin-marketplace install (issue #112).
-      const gate = dispatchGateWiring();
-      const gateWired = gate.wired;
-      // THE ONE RULE OF THIS FILE. A census we could not take is not a gate we observed to be
-      // missing, and "nothing can invoke it" is a claim about the user's machine.
-      if (gate.unreadable) return row(STATE.UNKNOWN, `${n} routing receipt${n === 1 ? '' : 's'} recorded, but the hook registries on this machine could not be read — whether anything is wired to invoke the router was not checked`);
-
-      if (!gateWired || !profile) {
-        const missing = [!gateWired && 'no PreToolUse gate on Task|Agent is wired to route-dispatch.sh',
-          !profile && 'no ~/.claude/model-router/profile.json (the opt-in the gate requires)'].filter(Boolean).join('; and ');
-        return row(STATE.IDLE,
-          `set up and proven — ${n} routing receipt${n === 1 ? '' : 's'} recorded — but nothing can invoke it: ${missing}. `
-          + 'Every receipt so far came from someone running the router by hand. Until the gate is wired, subagents keep '
-          + 'inheriting this session\'s model, which is the single largest cost leak in the harness.');
-      }
-
-      const IDLE_AFTER_DAYS = 7;
-      if (age !== null && age > IDLE_AFTER_DAYS) {
-        return row(STATE.IDLE,
-          `set up and proven — ${n} routing receipt${n === 1 ? '' : 's'} recorded — but nothing has routed through it in ${age} days. `
-          + 'It is configured; something that should be calling it is not. Check that the subagent-dispatch gate is wired '
-          + '(a PreToolUse hook on Task|Agent) and that ~/.claude/model-router/profile.json exists — without either, the router is never consulted.');
+    detect({ home = HOME } = {}) {
+      const config = readJSON(path.join(home, '.cache/ruvnet-brain/model-routing/terminal-launcher-config.json'));
+      if (config.err) return row(STATE.UNKNOWN, 'managed native routing settings are unreadable; routing and savings are not inferred');
+      if (!config.missing) {
+        const value = config.value;
+        if (!value || !path.isAbsolute(value.runtimeRoot || '') || !/^[a-f0-9]{64}$/.test(value.runtimeDigest || '')) return row(STATE.UNKNOWN, 'managed routing declaration is incomplete; no execution claim is made');
+        return row(STATE.UNKNOWN, 'a managed native routing runtime is configured. The retired Task dispatch hook is not a prerequisite. Configuration alone does not prove normal entry wiring, model allocation, execution or savings; those runtime facts were not checked by this declaration-only probe.');
       }
-      return row(STATE.ON, `${n} routing receipt${n === 1 ? '' : 's'} recorded${age === null ? '' : `, most recent ${age} day${age === 1 ? '' : 's'} ago`}`);
+      return row(STATE.UNKNOWN, 'no managed routing declaration was observed in this inspected location; legacy Task routing receipts or binary presence do not establish current native routing or its absence');
     },
   },
 
@@ -733,17 +717,9 @@ export const CAPABILITIES = [
   {
     key: 'harness-evolution',
     label: 'Harness self-improvement',
-    // Issue #116: this was `turnOn: null`, justified by a "VERIFIED NULL: evolve is not among them"
-    // measurement that has since drifted — ruflo v3.34.0 ships evolve, bench and flywheel. The
-    // precondition is named in the human text because brain-score/SKILL.md:97 requires the WRITE
-    // layer's OPENROUTER_API_KEY to be disclosed rather than discovered on failure.
-    turnOn: {
-      human: 'Evolve the harness and keep only measured winners (needs OPENROUTER_API_KEY; without it, `--subcommand score` is the free read-only layer)',
-      cmd: 'ruflo metaharness --subcommand evolve',
-    },
     whatItBuysYou: 'The rules your AI works by get tested against each other, and the version that measurably does better becomes the new default.',
     scope: SCOPE.MACHINE,
-    // VERIFIED NULL: `ruflo metaharness --help` enumerates its subcommands and `evolve` is not among them.
+    // No automatic enable action: policy evolution has separate authority and potential spend.
     turnOn: null,
     detect({ project = process.cwd() } = {}) {
       const policy = path.join(HOME, '.claude-flow/harness-active-policy.json');
@@ -808,48 +784,13 @@ export const CAPABILITIES = [
     scope: SCOPE.MACHINE,
     // Registering hooks means editing settings.json by hand — no single verified command.
     turnOn: null,
-    detect() {
-      const r = readJSON(path.join(HOME, '.claude/settings.json'));
-      if (r.missing) return row(STATE.ABSENT, 'no Claude Code settings file exists on this machine yet');
-      if (r.err) return row(STATE.UNKNOWN, `the settings file could not be parsed (${r.err}) — capture hooks not checked`);
-      const hooksRoot = r.value?.hooks;
-      if (hooksRoot !== undefined && (!hooksRoot || typeof hooksRoot !== 'object' || Array.isArray(hooksRoot))) {
-        return row(STATE.UNKNOWN, 'the settings file has a hooks section this version cannot interpret — capture hooks not counted');
-      }
-      const hooks = hooksRoot || {};
-      // COUNT COMMANDS, NOT MATCHER GROUPS. See countHookCommands: `[{matcher:'.*',hooks:[]}]` has
-      // length 1 and executes nothing, and the old `.length` check called that "both boundaries are
-      // covered" — a fabricated ON on a machine that saves nothing.
-      //
-      // AND COUNT *CAPTURE* COMMANDS, NOT ANY COMMAND. The old count accepted whatever was wired at
-      // those two boundaries, so a shell logger and a terminal beep — neither of which saves a byte of
-      // session state — produced "Session capture: ON". MEASURED with exactly that pair. The boundary
-      // a command is attached to says WHEN it runs, never WHAT it does, and this row's whole claim is
-      // about what it does. A command is only counted when it names a mechanism known to persist state.
-      //
-      // A MALFORMED GROUP POISONS THE COUNT rather than being skipped — the same rule, and the same
-      // words, as learning-enable.readSettingsWiring, which documents at length why skipping an
-      // unparseable entry and reporting the remainder as a total is this project's signature lie.
-      // MEASURED: a PreCompact written as an object instead of an array was silently skipped and the
-      // row reported OFF — "nothing is saved when a session compacts" — about a machine whose capture
-      // hook we simply failed to parse. Identical structure to the bug fixed in that file, opposite
-      // treatment, same commit.
-      const pre = countCaptureCommands(hooks.PreCompact);
-      const end = countCaptureCommands(hooks.SessionEnd);
-      if (pre === null || end === null) {
-        return row(STATE.UNKNOWN, `the ${pre === null ? 'pre-compaction' : 'session-end'} hook list could not be parsed, so whether anything is registered there cannot be read — no conclusion is drawn from the half that did parse`);
-      }
-      // "registered", never "capturing" — the same standard the MCP row holds itself to twenty lines
-      // below. A settings entry proves a command is wired to fire; no local artifact proves it ever
-      // ran or that it succeeded when it did, and claiming captured state from a config file would be
-      // exactly the fabricated status this registry exists to refuse.
-      if (pre && end) return row(STATE.ON, 'a state-saving hook is registered at both boundaries: one before compaction and one at session end — registered, which is not the same as proven to have captured anything');
-      // ON, not OFF: one boundary IS covered. Partially configured is not never-used — half the
-      // sessions are being saved today, and calling that "off" both understates what they have and
-      // invites them to re-enable a thing already running. The gap is named in the evidence, which is
-      // where a real but partial shortfall belongs. Found by GPT-5.6-Sol, 2026-07-24.
-      if (pre || end) return row(STATE.ON, `a state-saving hook is registered only at ${pre ? 'the pre-compaction' : 'the session-end'} boundary — the other one loses its state`);
-      return row(STATE.OFF, 'no hook that saves session state is registered at either boundary, so nothing is kept when a session compacts or closes');
+    detect({ home = HOME, project = process.cwd() } = {}) {
+      const { pre, end, unknown } = captureDeclarationCounts({ home, project });
+      if (unknown) return row(STATE.UNKNOWN, 'capture declarations could not be read completely; no absence or execution conclusion is drawn');
+      if (pre && end) return row(STATE.ON, 'commands naming capture mechanisms are declared at compaction and session end, including explicitly enabled installed-plugin manifests. Declared wiring is not proof of native activation or successful capture.');
+      if (pre || end) return row(STATE.ON, `a command naming a capture mechanism is declared at ${pre ? 'pre-compaction' : 'session end'} only in the inspected sources; actual capture and the other boundary remain unproved`);
+      return row(STATE.UNKNOWN, 'no state-saving declaration was observed in the inspected sources; runtime and invocation-only plugin hooks were not checked and may still exist');
+
     },
   },
 

package/plugin/scripts/capacity-aware-parallel-work.mjs

@@ -178,7 +178,7 @@ function collectLoadOnly() {
   return { normalizedLoad: load / cpuCount, loadAvg1: load };
 }
 
-function collectMacPressure() {
+export function collectMacPressure() {
   if (process.platform !== 'darwin') return collectLoadOnly();
   try {
     // One bounded subprocess gathers pressure, swap, and compressor bytes. Never use raw free RAM

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

@@ -28,6 +28,7 @@
  * is missing), so a non-zero status is forwarded verbatim and never reinterpreted.
  */
 import fs from 'node:fs';
+import { readContextFrame, contextFrame, selectContextFrame, renderContextFrame, recordContextBudget } from './hook-context-budget.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -115,6 +116,7 @@ const env = {
   CLAUDE_PLUGIN_ROOT: String(process.env.PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT || ''),
   CLAUDE_PROJECT_DIR: projectDir,
   RUVNET_HOOK_HOST: 'codex',
+  RUVNET_CODEX_CONTEXT_FRAMES: '1',
 };
 
 // Dream Cycle 2026-09-05. Codex's own dispatch trampoline (codex-hooks.json) never passes `cwd:`
@@ -131,7 +133,8 @@ let shimCwd = process.cwd();
 try { if (fs.statSync(projectDir).isDirectory()) shimCwd = projectDir; } catch { /* keep the default */ }
 
 const runShim = (payload) => spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
-  input: payload, encoding: 'utf8', env, cwd: shimCwd,
+  input: payload, encoding: 'utf8', env: { ...env, ...(BUDGET_MS ? { RUVNET_DECISION_DEADLINE: String(Date.now() + Math.max(1, BUDGET_MS - spent() - 350)) } : {}) }, cwd: shimCwd,
+  ...(BUDGET_MS ? { timeout: Math.max(1, BUDGET_MS - spent() - 100), killSignal: 'SIGKILL' } : {}),
 });
 
 /**
@@ -144,9 +147,9 @@ const runShim = (payload) => spawnSync(process.execPath, [shim, hookId, ...proce
  * away from the failure.
  *
  * BOUNDED, because the wrapper SIGKILLs this process at its own budget and a kill is invisible. The
- * wrapper hands its budget down; iteration stops at 75% of it and ALLOWS, which is decision-gate's
- * own rule for a blown budget ("a blown budget ALLOWS and says nothing"): the gate's slowness must
- * never be indistinguishable from the user doing something wrong.
+ * wrapper hands its budget down; advisory iteration may stop at 75% of it. A PreToolUse write-policy
+ * decision instead refuses the whole patch if any remaining path is unchecked, with explicit
+ * unchecked scope; a timeout can never authorize an uninspected write.
  */
 const BUDGET_MS = Number(process.env.RUVNET_CODEX_BUDGET_MS) || 0;
 const started = Date.now();
@@ -180,20 +183,44 @@ if (patchTool && hookId === 'md-stamp') {
 }
 
 const stdouts = [];
-for (const payload of payloads) {
+const guardedPatch = patchTool && hookId === 'decision-gate' && event === 'PreToolUse';
+// Materialize every path before consulting any policy; a move checks both ends.
+const patchScope = files.map((file) => path.resolve(projectDir, file));
+const refuseUnchecked = (index) => {
+  process.stderr.write(`Patch refused: write-policy inspection incomplete for ${JSON.stringify(patchScope.slice(index))}. Split the patch or retry after the bounded policy check is available.\n`);
+  process.exit(2);
+};
+if (guardedPatch && !patchScope.length) refuseUnchecked(0);
+for (const [index, payload] of payloads.entries()) {
+  if (guardedPatch && BUDGET_MS && BUDGET_MS - spent() <= 100) refuseUnchecked(index);
   const r = runShim(payload);
   // A refusal (or any error) from ANY file is the decision for the whole patch, forwarded verbatim
   // and immediately — there is nothing to compose once one wall has said no.
+  if (guardedPatch && (r.error || r.signal || r.status === null)) refuseUnchecked(index);
   if (r.status && r.stderr) process.stderr.write(r.stderr);
   if (r.status) process.exit(r.status);
   if (r.stdout) stdouts.push(r.stdout);
-  if (BUDGET_MS && spent() > BUDGET_MS * 0.75) break;
+  if (BUDGET_MS && spent() > BUDGET_MS * 0.75 && index + 1 < payloads.length) {
+    if (guardedPatch) refuseUnchecked(index + 1);
+    break;
+  }
 }
 
 if (!stdouts.length) process.exit(0);
 
 /** Merge N bodies' output into ONE value. Envelopes join by context; anything else joins as text. */
 function merge(outs) {
+  const frames = outs.map((value) => readContextFrame(value));
+  if (frames.every((frame) => frame && frame.event === event && frame.handler === hookId)) {
+    const selected = selectContextFrame(contextFrame(hookId, event, frames.flatMap((frame) => frame.blocks)));
+    recordContextBudget({ ...selected.receipt, stage: 'codex-final-fanout-merge' }, env);
+    return renderContextFrame(selected.frame);
+  }
+  if (frames.some(Boolean)) {
+    recordContextBudget({ handler: hookId, event, scope: 'mixed-framed-unframed-budget-unknown' }, env);
+    outs = outs.map((value, index) => frames[index] ? renderContextFrame({ ...frames[index], event }) : value);
+  }
+  if (!frames.some(Boolean)) recordContextBudget({ handler: hookId, event, scope: 'unframed-output-budget-unknown' }, env);
   if (outs.length === 1) return outs[0];
   const parsedAll = outs.map((s) => { try { return JSON.parse(s); } catch { return null; } });
   const contexts = parsedAll.map((p) => p?.hookSpecificOutput?.additionalContext);

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

@@ -60,8 +60,10 @@ const blockingHooks = new Set([
 const DETACHED_HOOKS = new Set(['learn-flush']);
 
 /** THE BUDGET IS DERIVED FROM WHAT THE HOOK MEASURABLY COSTS, never from what looks tidy. */
-function timeoutFor(hookId, event = '') {
+function timeoutFor(hookId, event = '', sessionBudgetMs = 0) {
   const override = Number(process.env.RUVNET_CODEX_HOOK_TIMEOUT_MS);
+  if (hookId === 'session-start') return Math.floor(Math.min(sessionBudgetMs,
+    Number.isFinite(override) && override > 0 ? override : Infinity));
   if (Number.isFinite(override) && override > 0) return override;
   // decision-gate's own internal budget is 4000ms (RUVNET_DECISION_BUDGET_MS) and it is allowed to
   // spend all of it: measured 986–4015ms across ten runs in a project this plugin does not own. A
@@ -198,17 +200,35 @@ if (DETACHED_HOOKS.has(hookId)) {
   process.exit(0);
 }
 
-const budgetMs = timeoutFor(hookId, process.argv[3] || '');
+let sessionDeadlineAt;
+if (hookId === 'session-start') {
+  try {
+    const { sessionStartDeadlineAt } = await import(path.join(root, 'scripts', 'session-start-budget.mjs'));
+    sessionDeadlineAt = sessionStartDeadlineAt({ host: 'codex', env: process.env, startedAt: performance.timeOrigin });
+  } catch {
+    process.stderr.write('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] SessionStart host budget unavailable; restoration was not attempted.\n');
+    process.exit(0);
+  }
+}
+const budgetMs = timeoutFor(hookId, process.argv[3] || '', Math.max(0, (sessionDeadlineAt || 0) - Date.now()));
+if (hookId === 'session-start' && budgetMs < 1) {
+  process.stderr.write('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] SessionStart deadline exhausted before restoration.\n');
+  process.exit(0);
+}
 const result = spawnSync(process.execPath, [adapter, ...process.argv.slice(2)], {
   input,
   encoding: 'utf8',
   // The adapter may fan one multi-file patch out into several body runs, and only this process knows
   // when the axe falls. Hand the budget down so it can stop and fail open instead of being killed
   // mid-loop with nothing written — a SIGKILL here is invisible to the host and to the user.
-  env: { ...process.env, RUVNET_CODEX_BUDGET_MS: String(budgetMs) },
+  env: { ...process.env, RUVNET_CODEX_BUDGET_MS: String(budgetMs),
+    ...(sessionDeadlineAt ? { RUVNET_SESSION_START_DEADLINE_AT: String(Math.min(sessionDeadlineAt, Date.now() + budgetMs)) } : {}) },
   timeout: budgetMs,
   killSignal: 'SIGKILL',
 });
+if (hookId === 'session-start' && result.status !== 0) {
+  process.stderr.write('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] SessionStart did not complete inside its host deadline; no restoration success is claimed.\n');
+}
 
 // A broken optional Brain hook must never degrade the host. The only non-zero status that carries
 // product meaning is an intentional exit-2 refusal from a hook whose contract is blocking.

package/plugin/scripts/continuation-gate.mjs

@@ -392,7 +392,8 @@ function promiseBookkeeping() {
         if (!assistantCommitmentOwned(item, hookInput.session_id, projectIdentity)) continue;
         const claim = completion.claims.find((c) => claimClosesPromise(c.text, item.text));
         if (!claim) continue;
-        Object.assign(item, { done: true, state: 'completed', doneAt: at, completionEvidence: { claim: claim.text,
+        const verifiedCompletion = completion.verdict === 'PASS' && Boolean(claim);
+        Object.assign(item, { done: verifiedCompletion, state: verifiedCompletion ? 'completed' : item.state, doneAt: at, completionEvidence: { claim: claim.text,
           checks: completion.verification.checks.slice(-5).map((c) => c.what),
           transcript: String(hookInput.transcript_path || ''), sessionId: hookInput.session_id } });
         changed = true;

package/plugin/scripts/continuity-brief.mjs

@@ -32,6 +32,7 @@ import { withProgressionReader } from './project-progression-reader.mjs';
 import { readWorkLedger } from './project-progression-sources.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { restoreProgressionForSession } from './project-progression-session-start.mjs';
+import { STAGE_BUDGETS_MS } from './session-start-budget.mjs';
 import { projectDirectory } from './project-identity.mjs';
 import { CONTINUITY_NAMESPACE, EVENT_KINDS, makeEvent, userLevelAgentdbHooks } from './continuity-events.mjs';
 import { ContinuityJournal, drain, launchDrain, recordingLine, storeReady } from './continuity-journal.mjs';
@@ -50,8 +51,20 @@ const OWNED_DIR = 'continuity-owned';
 const MAX_STORE_EVENTS = 600;
 const SECTION_CAPS = Object.freeze({ commit: 6, release: 3, decision: 5, lesson: 6, gate: 4, finding: 3, open: 5 });
 
-function git(cwd, args) {
-  try { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim(); } catch { return ''; }
+function checkDeadline({ deadlineAt = Infinity, signal } = {}) {
+  if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded');
+}
+function git(cwd, args, options = {}) {
+  checkDeadline(options);
+  try {
+    const value = execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: Math.max(1, Math.floor(Math.min(2000, (options.deadlineAt ?? Infinity) - Date.now()))), killSignal: 'SIGKILL' }).trim();
+    checkDeadline(options); return value;
+  } catch (error) {
+    checkDeadline(options);
+    if (error.code === 'ETIMEDOUT' && Number.isFinite(options.deadlineAt)) throw new Error('restore deadline exceeded');
+    return '';
+  }
 }
 const hhmm = (iso) => String(iso || '').replace(/:\d\d\.\d+Z$|:\d\dZ$/, 'Z');
 /** Data-safe one line: no control or bidi characters, no fence tokens, whitespace collapsed, capped. */
@@ -93,35 +106,42 @@ function appendOwned(file, record) {
 }
 
 /** Every continuity event: committed rows (read-only) plus pending outbox rows, oldest first. */
-export function readEvents(journal, { maxEvents = MAX_STORE_EVENTS } = {}) {
+export function readEvents(journal, { maxEvents = MAX_STORE_EVENTS, deadlineAt = Infinity, signal } = {}) {
+  const options = { deadlineAt, signal }; checkDeadline(options);
   const byKey = new Map();
   if (storeReady(journal.db)) {
     const read = withProgressionReader(journal.db, (reader) => {
       const keys = reader.listKeys(CONTINUITY_NAMESPACE, { maxEntries: 200_000 }).slice(-maxEvents);
       return keys.map((key) => ({ key, content: reader.readContent(CONTINUITY_NAMESPACE, key) }));
-    });
+    }, options);
+    if (!read.ok && Number.isFinite(deadlineAt)) throw new Error('continuity brief store read unavailable');
     if (read.ok) {
       for (const { key, content } of read.value) {
+        checkDeadline(options);
         try { byKey.set(key, { key, event: JSON.parse(content), pending: false }); } catch { /* malformed row: not an event */ }
       }
     }
   }
-  for (const rec of journal.pending()) if (!byKey.has(rec.key)) byKey.set(rec.key, { key: rec.key, event: rec.event, pending: true });
+  checkDeadline(options);
+  for (const rec of journal.pending()) { checkDeadline(options); if (!byKey.has(rec.key)) byKey.set(rec.key, { key: rec.key, event: rec.event, pending: true }); }
   return [...byKey.values()].sort((a, b) => (a.key < b.key ? -1 : 1));
 }
 
 /** The owner's `lesson-*` keys (project namespace, default, lessons) — read only when no user hook shows them. */
-function ownerLessons(db, namespaces) {
+function ownerLessons(db, namespaces, options = {}) {
+  checkDeadline(options);
   if (!storeReady(db)) return [];
   const read = withProgressionReader(db, (reader) => {
     const out = [];
     for (const ns of namespaces) {
       for (const key of reader.listKeys(ns, { maxEntries: 200_000 })) {
+        checkDeadline(options);
         if (ns === 'lessons' || key.startsWith('lesson-')) out.push({ key, ns, content: reader.readContent(ns, key) });
       }
     }
     return out;
-  });
+  }, options);
+  if (!read.ok && Number.isFinite(options.deadlineAt)) throw new Error('continuity brief lesson read unavailable');
   return read.ok ? read.value : [];
 }
 
@@ -143,25 +163,28 @@ const tag = (row) => {
  * an adopted project (no `.swarm`), where there is nothing to come up to speed on.
  */
 export function buildBrief({ projectDir, env = process.env, home = os.homedir(), now = Date.now(), limitBytes = BRIEF_LIMIT_BYTES,
-  pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), persistState = true } = {}) {
+  pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), persistState = true,
+  deadlineAt = Infinity, signal } = {}) {
+  const options = { deadlineAt, signal }; checkDeadline(options);
   let resolution;
-  try { resolution = resolveProjectStore({ projectDir }); } catch { return { context: '' }; }
-  const journal = new ContinuityJournal({ projectRoot: resolution.projectRoot, now: () => now });
+  try { resolution = resolveProjectStore({ projectDir, deadlineAt }); }
+  catch (error) { if (Number.isFinite(deadlineAt)) throw error; return { context: '' }; }
+  const journal = new ContinuityJournal({ projectRoot: resolution.projectRoot, now: () => now, deadlineAt, signal });
   try { if (!fs.lstatSync(journal.swarm).isDirectory()) return { context: '' }; } catch { return { context: '' }; }
   const state = readState(journal);
   const since = Number(state.lastBriefAt) || now - 86_400_000;
-  const rows = readEvents(journal);
+  const rows = readEvents(journal, options);
   const status = journal.status();
   const of = (kind) => rows.filter((r) => r.event?.kind === kind);
   const user = userLevelAgentdbHooks({ home });
 
   const root = resolution.checkoutRoot;
-  const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
-  const headLine = git(root, ['log', '-1', '--format=%h %s']);
-  const latestTag = git(root, ['describe', '--tags', '--abbrev=0']);
+  const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'], options);
+  const headLine = git(root, ['log', '-1', '--format=%h %s'], options);
+  const latestTag = git(root, ['describe', '--tags', '--abbrev=0'], options);
   let version = '';
   try { version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version || ''; } catch { /* not a node project */ }
-  const changed = git(root, ['log', '-n20', `--since=${new Date(since).toISOString()}`, '--format=%h %s', 'HEAD']).split('\n').filter(Boolean);
+  const changed = git(root, ['log', '-n20', `--since=${new Date(since).toISOString()}`, '--format=%h %s', 'HEAD'], options).split('\n').filter(Boolean);
   const newTags = of('release').filter((r) => Date.parse(r.event.at) >= since);
 
   const ledger = readWorkLedger({ projectId: resolution.projectIdentity.id, env, home });
@@ -181,7 +204,7 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
   if (user.ensure) {
     lessonNote = '(owner lesson-* keys and project-state-current are printed by your user-level agentdb-ensure hook; not repeated)';
   } else {
-    for (const l of ownerLessons(journal.db, [path.basename(resolution.projectRoot), 'default', 'lessons'])) {
+    for (const l of ownerLessons(journal.db, [path.basename(resolution.projectRoot), 'default', 'lessons'], options)) {
       storeLessonLines.push(`• ${oneLine(l.content)} [${oneLine(`${l.ns}/${l.key}`, 80)}]`);
     }
   }
@@ -190,7 +213,7 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
     { name: 'STANDING RULES (you recorded these with --record on this machine)', cap: SECTION_CAPS.lesson, items: ruleLines.reverse() },
   ];
   const data = [
-    { name: 'SINCE LAST SESSION', cap: SECTION_CAPS.commit, intro: `(${new Date(since).toISOString().slice(0, 16)}Z → now; git, read live): ${changed.length}${changed.length === 20 ? '+' : ''} commit(s) on ${oneLine(branch, 80) || '?'}${newTags.length ? `; releases: ${newTags.map((r) => oneLine(r.event.detail?.tag, 60)).join(', ')}` : ''}`,
+      { name: 'SINCE LAST SESSION', cap: SECTION_CAPS.commit, intro: `(${new Date(since).toISOString().slice(0, 16)}Z → now; git, read live): ${changed.length}${changed.length === 20 ? '+' : ''} commit(s) on ${oneLine(branch, 80) || '?'}${newTags.length ? `; local tags (publication unverified): ${newTags.map((r) => oneLine(r.event.detail?.tag, 60)).join(', ')}` : ''}`,
       items: changed.map((c) => `• ${oneLine(c, 140)}`) },
     { name: 'DECISIONS', cap: SECTION_CAPS.decision, items: of('decision').reverse().map((r) => `• ${oneLine(r.event.summary)} ${tag(r)}`) },
     { name: 'LESSONS FOUND IN THE PROJECT STORE (not confirmed as yours)', cap: SECTION_CAPS.lesson, intro: lessonNote, items: storeLessonLines.reverse() },
@@ -202,7 +225,7 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
   const sections = [...trusted, ...data];
 
   const head = [`${BRIEF_HEADER} — ${oneLine(path.basename(resolution.projectRoot), 80)} · AgentDB ${oneLine(journal.db, 300)}]`];
-  const now_ = `NOW: ${oneLine(branch, 80) || 'no branch'} @ ${oneLine(headLine, 160) || 'no commits'}${version ? ` · package ${oneLine(version, 40)}` : ''}${latestTag ? ` · latest tag ${oneLine(latestTag, 60)}` : ''} (git, live)`;
+  const now_ = `NOW: ${oneLine(branch, 80) || 'no branch'} @ ${oneLine(headLine, 160) || 'no commits'}${version ? ` · package ${oneLine(version, 40)}` : ''}${latestTag ? ` · local tag ${oneLine(latestTag, 60)} (publication unverified)` : ''} (git, live)`;
   const tail = [
     recordingLine(status, now),
     `MORE: ${env.RUVNET_HOOK_HOST === 'codex' ? '' : '/ruvnet-brain:rnb-brief, or '}node "${path.join(pluginRoot, 'scripts', 'continuity-brief.mjs')}" --full [--kind ${EVENT_KINDS.join('|')}] [--since 7d]`,
@@ -235,6 +258,7 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
     const room = Math.max(0, Buffer.byteLength(dataText, 'utf8') - (Buffer.byteLength(context, 'utf8') - limitBytes) - 80);
     context = render(caps, `${Buffer.from(dataText).subarray(0, room).toString('utf8').replace(/�$/, '')}\n[CUT to fit — the rest is in AgentDB: run the MORE command]`);
   }
+  checkDeadline(options);
   if (persistState) writeState(journal, { lastBriefAt: now });
   return { context, status, counts: Object.fromEntries(EVENT_KINDS.map((k) => [k, of(k).length])), journal };
 }
@@ -243,13 +267,22 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
  * SessionStart's continuity stage: the brief first, then the ADR-073 progression restore. A brief
  * failure never costs the restore; pending events get a detached drainer here too.
  */
-export async function restoreWithBrief({ env = process.env, cwd = process.cwd(), restore = restoreProgressionForSession, launch = launchDrain } = {}) {
-  const restored = await restore({ env, cwd });
+export async function restoreWithBrief({ env = process.env, cwd = process.cwd(), restore = restoreProgressionForSession, launch = launchDrain,
+  deadlineAt = Infinity, signal } = {}) {
+  deadlineAt = Math.min(deadlineAt, Date.now() + STAGE_BUDGETS_MS.restore);
+  const options = { deadlineAt, signal };
+  const restored = await restore({ env, cwd, ...options });
   let brief = { context: '' };
   try {
-    brief = buildBrief({ projectDir: env.CLAUDE_PROJECT_DIR || cwd, env, home: env.HOME || os.homedir() });
+    checkDeadline(options);
+    brief = buildBrief({ projectDir: env.CLAUDE_PROJECT_DIR || cwd, env, home: env.HOME || os.homedir(), ...options });
+    checkDeadline(options);
     if (brief.status?.pending && brief.status.applicable) launch({ projectRoot: brief.journal.projectRoot, env });
-  } catch { /* the restore still stands on its own */ }
+  } catch (error) {
+    const reason = /deadline|timed out/i.test(error.message) ? 'deadline-exceeded' : 'brief-read-failed';
+    return { ...(restored || {}), degraded: true, brief: { status: 'unknown', reason },
+      context: `[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]\nThe startup brief is incomplete (${reason}); no complete brief restoration is claimed.\n${restored?.context || ''}` };
+  }
   if (!brief.context) return restored;
   return { ...(restored || {}), brief: brief.status, context: restored?.context ? `${brief.context}\n${restored.context}` : brief.context };
 }