ruvnet-brain 3.9.133-dev → 4.0.1

package/plugin/scripts/signal-watch.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// plugin/scripts/signal-watch.mjs — PostToolUse (matcher ^Bash$, anchored — ADR-058 §D3). The
+// OBSERVED half ("W1") of the external-signal watch plane (DDD-0013 Context 2, aggregate SignalDebt).
+//
+// THE FAILURE THIS CLOSES: on 2026-07-27 GitHub CI was failing and the OWNER had to tell the model.
+// A product that pitches "proactive" and needs a human to report a red pipeline has failed. This
+// hook is the free half: the model already runs gh/vercel/netlify/npm publish/git push, so this
+// classifies the command it already ran (no new polling, no new cost, no new tokens) and:
+//   - a SUCCESSFUL `git push` opens a pending CI-verdict debt keyed (repo, sha) — appended to
+//     pending.jsonl. scripts/signal-watch.mjs (the W2 poller — a SEPARATE process, SEPARATE file,
+//     SEPARATE cadence) resolves it later via `gh run list`; plugin/scripts/session-start.sh
+//     surfaces the transition. This is 2026-07-27 replayed with the human removed.
+//   - a FAILING gh/vercel/netlify/npm-publish invocation also appends a debt and prints one
+//     advisory line (additionalContext — never blocking; PostToolUse cannot block anyway).
+//
+// CLASSIFICATION IS STRUCTURAL, NEVER A GREP (ADR-058; hook-input.mjs's own header; issues
+// #12/#13/#41/#44): findInvocations() below is hook-input.mjs's shared classifier, reused rather
+// than reimplemented — it works in EXECUTABLE POSITION only, so the word "vercel" inside a commit
+// message or a heredoc body can never fire this (the #12 lesson, generalized).
+//
+// ── VERIFY-FIRST CLAUSE (mandatory, ADR-058 §D3) — read before touching tool_response parsing ────
+//
+// The real Bash PostToolUse tool_response shape was captured from THREE live envelopes on
+// 2026-07-28, BEFORE this parsing code was written (see
+// tests/fixtures/signal-watch/bash-posttooluse-envelopes.json for the captures, their session IDs,
+// and full provenance). Confirmed real shape: `{ stdout, stderr, interrupted, isImage,
+// noOutputExpected }`. No exit-code field was ever observed in any of the three captures.
+//
+// That same investigation surfaced a SECOND, more consequential fact, reproduced FIVE separate
+// times (a plain `false`, `false` run mid-sequence between two successful calls, a compound
+// stderr+exit-1 command, and `ls` on a nonexistent path — twice, the second time with an
+// invocation marker written to disk BEFORE the hook process even attempted to read stdin): a Bash
+// tool call that itself exits non-zero never invoked this hook's process AT ALL, when driven via
+// `claude -p` (the sdk-cli entrypoint), Claude Code v2.1.220. A parallel PreToolUse debug hook fired
+// reliably on the byte-identical failing command in the same run, which isolates the gap to
+// PostToolUse-after-a-Bash-error specifically, rather than a general hook-loading problem. This is
+// reported as a MEASUREMENT (Rule 22/23), not a verdict: it may be an sdk-cli/print-mode-specific
+// behavior rather than true interactive-session behavior, and is not asserted to hold universally.
+//
+// CONSEQUENCE FOR THIS DESIGN: the git-push SUCCESS path this entire feature depends on is
+// unaffected — every one of the three real captures was a zero-exit Bash call, and every one fired
+// this hook reliably. The "detect a failing gh/vercel/netlify/npm-publish command directly" behavior
+// below is therefore built defensively (cliOutcome() below never assumes a field that was not
+// actually observed) and stays ADVISORY ONLY, matching the ADR's own framing ("advisory, never
+// blocking — malfunction is never a decision"). The AUTHORITATIVE verdict for any CI-shaped question
+// always comes from scripts/signal-watch.mjs's poller (a real `gh run list`, resolved independently
+// of whether this hook fired at all) — never from this observer's best-effort guess.
+//
+// SINGLE WRITER (DDD-0013 Context 2 invariant 3): this file is the ONLY writer of pending.jsonl.
+// scripts/signal-watch.mjs (the poller) only ever reads it.
+//
+// CONTRACT (matches every other node hook body in this dir — md-stamp.mjs, learn-flush.mjs):
+// dispatched via hook-shim.mjs (mode: advisory). ALWAYS exits 0; never throws to the caller; a
+// parse/IO failure degrades to silence, never a crash the harness has to survive (DDD invariant 4:
+// "observation never blocks and never manufactures a refusal").
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseHookEvent, toolName, commandOf, findInvocations, rawToolResponse, readStdinBounded } from './hook-input.mjs';
+
+const MANAGED_TOOLS = ['gh', 'vercel', 'netlify', 'npm', 'git'];
+
+/**
+ * Every managed invocation in `command`, structurally classified. Reuses hook-input.mjs's
+ * findInvocations() so npx/bunx/pnpx wrapping and executable-position rules are shared with every
+ * other gate in this repo instead of re-derived here (the ADR's explicit "do not reimplement").
+ */
+export function detectManagedInvocations(command) {
+  const hits = [];
+  for (const inv of findInvocations(command, MANAGED_TOOLS)) {
+    if (inv.tool === 'npm') { if (inv.args[0] === 'publish') hits.push({ tool: 'npm-publish', args: inv.args }); }
+    else if (inv.tool === 'git') { if (inv.args[0] === 'push') hits.push({ tool: 'git-push', args: inv.args }); }
+    else hits.push({ tool: inv.tool, args: inv.args });
+  }
+  return hits;
+}
+
+/**
+ * Raw Bash tool_response -> a small typed CliOutcome (DDD-0013 anti-corruption boundary: "the
+ * domain holds CliOutcome {exitClass, firstActionableLine}, never raw host JSON"). Defensive by
+ * construction per the VERIFY-FIRST note above: honors an explicit numeric exit code if a future
+ * Claude Code version ever adds one; otherwise falls back to "stderr is non-empty" as the best
+ * available signal from the shape actually observed.
+ */
+export function cliOutcome(raw) {
+  if (!raw || typeof raw !== 'object') return { failed: false, firstActionableLine: '' };
+  const exitCode = typeof raw.exitCode === 'number' ? raw.exitCode
+    : typeof raw.exit_code === 'number' ? raw.exit_code : null;
+  const stderr = typeof raw.stderr === 'string' ? raw.stderr : '';
+  const stdout = typeof raw.stdout === 'string' ? raw.stdout : '';
+  const failed = exitCode !== null ? exitCode !== 0 : stderr.trim().length > 0;
+  const firstActionableLine = (stderr.trim().split('\n')[0] || stdout.trim().split('\n')[0] || '').slice(0, 200);
+  return { failed, firstActionableLine };
+}
+
+function parseRepoSlug(remoteUrl) {
+  const m = /github\.com[:/]+([^/]+)\/([^/.]+?)(\.git)?$/.exec(String(remoteUrl || '').trim());
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** The (repo, sha) a push/observation belongs to, from plain READ-ONLY git plumbing — never `gh`.
+ * The observer needs no auth; only the poller (scripts/signal-watch.mjs) talks to GitHub's API. */
+function resolveGitContext(cwd) {
+  let sha = null;
+  let repo = null;
+  try {
+    const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', timeout: 2000 });
+    if (r.status === 0) sha = r.stdout.trim();
+  } catch { /* not a git repo, or git missing */ }
+  try {
+    const r = spawnSync('git', ['config', '--get', 'remote.origin.url'], { cwd, encoding: 'utf8', timeout: 2000 });
+    if (r.status === 0) repo = parseRepoSlug(r.stdout);
+  } catch { /* no remote configured */ }
+  return { sha, repo };
+}
+
+function signalDir() {
+  return process.env.RUVNET_SIGNAL_DIR
+    || path.join(process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'), 'external-signals');
+}
+
+export function pendingPath() { return process.env.SIGNAL_WATCH_PENDING || path.join(signalDir(), 'pending.jsonl'); }
+
+/** Append ONE SignalDebt-open event. SINGLE WRITER of pending.jsonl (DDD-0013 §Context 2 inv. 3). */
+export function appendDebt(event, file = pendingPath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(event) + '\n');
+  } catch { /* observation never blocks, never throws (DDD invariant 4) */ }
+}
+
+/**
+ * The pure decision: given a parsed hook event, what debts (if any) does it open, and what advisory
+ * lines (if any) does it print? Exported so a test can drive it directly with a constructed event,
+ * in addition to the subprocess-level tests that feed real envelope JSON on stdin.
+ */
+export function evaluate(ev, { cwd = process.cwd(), file = pendingPath() } = {}) {
+  const result = { debts: [], lines: [] };
+  if (toolName(ev) !== 'Bash') return result;
+  const command = commandOf(ev);
+  const hits = detectManagedInvocations(command);
+  if (!hits.length) return result;
+
+  const outcome = cliOutcome(rawToolResponse(ev));
+  for (const hit of hits) {
+    if (hit.tool === 'git-push') {
+      if (outcome.failed) continue; // nothing landed on origin — there is no SHA to poll a verdict for
+      const { sha, repo } = resolveGitContext(cwd);
+      if (!sha || !repo) continue; // can't key a debt without both halves of (repo, ref)
+      const debt = {
+        ts: new Date().toISOString(), kind: 'git-push', repo, ref: sha,
+        toolUseId: ev.tool_use_id || null, sessionId: ev.session_id || null,
+      };
+      appendDebt(debt, file);
+      result.debts.push(debt);
+    } else if (outcome.failed) {
+      const debt = {
+        ts: new Date().toISOString(), kind: 'cli-exit-nonzero', tool: hit.tool,
+        firstActionableLine: outcome.firstActionableLine,
+        toolUseId: ev.tool_use_id || null, sessionId: ev.session_id || null,
+      };
+      appendDebt(debt, file);
+      result.debts.push(debt);
+      result.lines.push(`[RuvNet Brain — external signal] ${hit.tool} command failed: ${outcome.firstActionableLine || '(no output captured)'}`);
+    }
+  }
+  return result;
+}
+
+async function readHookInput() {
+  if (process.stdin.isTTY) return null; // never block on a TTY with nothing to give
+  try { return parseHookEvent((await readStdinBounded()).toString('utf8')); } catch { return null; }
+}
+
+async function main() {
+  const ev = await readHookInput();
+  if (!ev) return;
+  const { lines } = evaluate(ev);
+  for (const l of lines) console.log(l);
+}
+
+function isMain() {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+
+if (isMain()) {
+  try { await main(); } catch { /* fail open, always — see CONTRACT above */ }
+  process.exit(0);
+}

package/plugin/scripts/unprompted-runtime.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+// unprompted-runtime.mjs — THE enforcement chokepoint for unprompted speech (ADR-040 / DDD-0004 §"The
+// enforcement chokepoint"). This is the CORE of the 4.0 dial-scope work. Read this header as the
+// contract every producer, test, and later hooks.json rewrite must build to.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY THIS FILE EXISTS. DDD-0004 states the invariant verbatim: "Every unprompted utterance passes
+// through ONE runtime that reads the level and the DismissalLedger and alone decides whether bytes
+// reach the user. An emitter returns a structured candidate; it never writes user-facing bytes
+// directly. Raw text from an emitter is a protocol violation — dropped, not forwarded." Until this
+// build no such runtime existed: anticipate.sh read the dial itself, lesson-gate read no dial at all,
+// and both were wired BARE in hooks.json (`bash … || true`) instead of through the shim. This file is
+// that ONE runtime. It is the SOLE writer of user-facing bytes for unprompted hooks.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE SEAM (build to THIS — do not invent a parallel one).
+//
+// INVOCATION. hook-shim.mjs dispatches this file under the single id 'unprompted-speech', forwarding
+// the Claude Code event name as argv:
+//     node hook-shim.mjs unprompted-speech <CCEventName>   →   node unprompted-runtime.mjs <CCEventName>
+// <CCEventName> is the token hooks.json passes (a real CC event like "UserPromptSubmit", or an
+// internal sub-event like "PreToolUse-bash"/"PreToolUse-write" that distinguishes which producer to
+// run — the same tokens lesson-hooks.sh already switches on). The CC hook JSON payload arrives on this
+// process's stdin, exactly as it would for a bare hook.
+//
+// PRODUCER CANDIDATE MODE. For the given event the runtime spawns the real producer(s) as CAPTURED
+// child processes (stdio piped, NEVER inherited) with env RUVNET_EMIT_CANDIDATES=1 and the payload on
+// their stdin. A producer in candidate mode writes ZERO user-facing bytes and instead prints ONE JSON
+// object per line to stdout:
+//     {"channel":"advocacy|promotion|lesson|alarm","effect":"advisory|block","copy":"<text>","hookEventName":"<CCevent>"}
+// advocacy/promotion candidates additionally carry: "findingId","severity","observationHash".
+// With RUVNET_EMIT_CANDIDATES unset a producer behaves EXACTLY as today (its own CLI/direct output) —
+// candidate mode is purely additive. The runtime captures every producer's stdout, discards its
+// stderr, and never lets a producer touch the real process streams.
+//
+// PER-CHANNEL POLICY (applied by the runtime to each parsed candidate, keyed on the candidate's own
+// `channel`, never on which producer emitted it):
+//   advocacy  → honour the advocacy dial (settings `.settings.advocacy`) AND the DismissalLedger
+//               (advocacy-outcomes.shouldStillOffer). Off ⇒ dropped. Suppressed ⇒ dropped. On delivery
+//               the runtime records the OFFERED denominator centrally via advocacy-outcomes.record.
+//               The real modules are reused — suppression is NOT hand-rolled here.
+//   promotion → onboarding policy + advocacy level: delivered only at advocacy `all` (DDD-0004's
+//               "silenced by anything below all"); the once-per-install / never-repeat part is the
+//               promotion producer's own job (it emits a candidate only when it is due).
+//   lesson    → NEVER the advocacy dial. The lesson producer (lesson-gate via lesson-hooks) owns its
+//               frequency cap, project scope, and blocking opt-in. `effect:'advisory'` is delivered as
+//               a nudge; `effect:'block'` becomes exit 2 with the reason on stderr and byte-empty
+//               stdout — an opted-in refusal is never swallowed.
+//   alarm     → always delivered. Not gated by anything. Silence here = a broken install looking healthy.
+//
+// DELIVERY (the runtime writes the final envelope to the REAL streams, itself):
+//   advisory → exit 0, stdout = {"hookSpecificOutput":{"hookEventName":…, "additionalContext":…}}.
+//   block    → exit 2, reason on stderr, stdout byte-empty.
+// A block (only ever from the lesson channel) dominates: if any block survives policy, advisories are
+// discarded and the runtime exits 2. Otherwise every surviving advisory copy is concatenated into ONE
+// additionalContext string under ONE envelope (two JSON documents on stdout parse as neither).
+//
+// THE DROP RULE that makes "raw bytes are a protocol violation" mechanically true: on the ADVISORY
+// path, invalid JSON / a non-object / an unknown channel / an unknown effect / a missing copy / a
+// missing required advocacy field is SILENTLY dropped. A rogue producer that prints raw bytes instead
+// of candidate JSON therefore reaches NEITHER user stream. A block is only ever produced by a VALID
+// lesson candidate with `effect:'block'`; raw bytes can never manufacture a refusal.
+//
+// FAIL-SAFE. This never throws out to the caller. Any internal failure resolves toward SILENCE (exit
+// 0, empty stdout) — never toward speaking, and never toward a spurious refusal.
+//
+// NON-NEGOTIABLE INVARIANTS (each proven by a test that breaks it):
+//   1. An opted-in BLOCK lesson still exits 2 with byte-empty stdout.
+//   2. advocacy=off ⇒ an advocacy candidate yields exit 0 and byte-EXACT stdout === "".
+//   3. A rogue producer printing raw bytes ⇒ nothing reaches either user stream on the advisory path.
+//   4. (Registry-test territory, not this file) a bare unprompted line in hooks.json fails the test.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readStdinBounded } from './hook-input.mjs';
+
+// <codeRoot>/plugin/scripts/unprompted-runtime.mjs → <codeRoot>. Resolved from THIS file's own
+// location so it is correct under the Stable Spine (an immutable versions/<gen> tree) and in a dev
+// checkout alike — hook-shim.mjs has already chosen the tree by the time it dispatches this body.
+const SELF = fileURLToPath(import.meta.url);
+const SCRIPTS_DIR = path.dirname(SELF);                     // <codeRoot>/plugin/scripts
+const CODE_ROOT = path.resolve(SCRIPTS_DIR, '..', '..');    // <codeRoot>
+
+// The CC event name the shim forwarded. No event → nothing to run; stay silent.
+const EVENT = process.argv[2] || '';
+
+// Bound the whole runtime well under the 5s hook budget: producers run sequentially and each has its
+// own internal watchdog, but a backstop timeout here means a wedged producer can never hang the turn.
+const PRODUCER_TIMEOUT_MS = Number(process.env.RUVNET_UNPROMPTED_TIMEOUT_MS) || 4000;
+const MAX_BUFFER = 1 << 20;
+
+const VALID_CHANNELS = new Set(['advocacy', 'promotion', 'lesson', 'alarm']);
+const VALID_EFFECTS = new Set(['advisory', 'block']);
+
+/** Exit 0 with byte-empty stdout — the fail-safe and the "nothing to say" path. */
+function silent() { process.exit(0); }
+
+// ── Producer registry: CC event token → the producers to spawn in candidate mode ──────────────────
+// Each producer is an argv array + whether it is fed the payload on stdin. The channel is NOT declared
+// here — it travels on each emitted candidate, so one producer may legitimately emit more than one
+// channel and the runtime still routes every line by its own `channel`.
+//
+// Producers are the adapters that already own event→trigger mapping and payload parsing (lesson-hooks
+// maps "PreToolUse-bash" → the mutate-machine trigger and pulls session_id/command off stdin;
+// anticipate reads the prompt off stdin). Keeping that mapping in the producer layer is deliberate:
+// this core file decides WHETHER bytes reach the user, not WHAT each producer looks for.
+//
+// TEST SEAM: RUVNET_UNPROMPTED_PRODUCERS, when set to a JSON array of {argv:[...],feedStdin:bool},
+// REPLACES the built-in registry for every event — so a test can inject a fake block-emitter, an
+// advocacy-emitter, or a rogue raw-bytes emitter without touching real producers.
+// `channels` binds each producer to the ONLY channels it is authorised to emit (GPT-5.6-Sol anti-spoof).
+// Without it, any producer could emit `{channel:'alarm'}` (always-delivered) or `lesson:block` (force
+// exit 2) and bypass its intended per-channel policy — defeating the whole point of the chokepoint.
+const ANTICIPATE = { argv: ['/bin/bash', path.join(SCRIPTS_DIR, 'anticipate.sh')], feedStdin: true, channels: ['advocacy', 'promotion'] };
+const lesson = (subEvent) => ({ argv: ['/bin/bash', path.join(SCRIPTS_DIR, 'lesson-hooks.sh'), subEvent], feedStdin: true, channels: ['lesson'] });
+
+const BUILTIN_REGISTRY = {
+  'UserPromptSubmit': [ANTICIPATE, lesson('UserPromptSubmit')],
+  'PreToolUse-write': [lesson('PreToolUse-write')],
+  'PreToolUse-bash':  [lesson('PreToolUse-bash')],
+  'PreToolUse-push':  [lesson('PreToolUse-push')],
+};
+
+function resolveProducers(event) {
+  const override = process.env.RUVNET_UNPROMPTED_PRODUCERS;
+  if (override) {
+    try {
+      const specs = JSON.parse(override);
+      if (Array.isArray(specs)) {
+        return specs
+          .filter((s) => s && Array.isArray(s.argv) && s.argv.length && s.argv.every((a) => typeof a === 'string'))
+          .map((s) => ({
+            argv: s.argv,
+            feedStdin: s.feedStdin !== false,
+            // The test seam may declare `channels` to exercise the anti-spoof; absent, it defaults to all
+            // (a test injects a trusted fake). Production spoof-protection lives on the built-in entries.
+            channels: Array.isArray(s.channels) ? s.channels.filter((c) => VALID_CHANNELS.has(c)) : [...VALID_CHANNELS],
+          }));
+      }
+    } catch { /* malformed override → fall through to the built-in registry */ }
+  }
+  return BUILTIN_REGISTRY[event] || [];
+}
+
+// ── Read the payload ONCE, forward the same bytes to every producer ────────────────────────────────
+// Claude Code pipes the hook JSON and closes stdin, so a synchronous read to EOF is safe and simplest.
+// GUARD: an interactive/attached stdin (a TTY) is NOT piped and would block readFileSync(0) forever —
+// so read only when fd 0 is a real pipe/file. A manual run with no redirect yields empty, not a hang.
+let payload = Buffer.alloc(0);
+if (!process.stdin.isTTY) {
+  try { payload = await readStdinBounded(); } catch { payload = Buffer.alloc(0); }
+}
+
+// AN UNPROMPTED UTTERANCE MUST BE OCCASIONED BY A REAL EVENT (fixed 2026-07-27).
+//
+// Measured on origin/main, the same runtime, three inputs:
+//
+//     empty stdin  -> 2453 bytes, exit 0
+//     garbage      -> 2453 bytes
+//     real payload -> 0 bytes
+//
+// Read those together: it was silent when a real event arrived and spoke when none did. The producers
+// downstream match triggers that are true unconditionally (report-status, claim-done), so with no
+// payload to constrain them they emit on every fire — payload-independent speech, which is noise with
+// a JSON envelope around it, injected into the user's context.
+//
+// The header already commits to the shape of this: "never speak on a guess" is why an unknown event
+// stays silent. A payload that is absent, truncated, or not a JSON object is the same class of
+// not-knowing, and resolves the same way — toward silence, per the FAIL-SAFE rule above. Claude Code
+// always writes a JSON object and closes, so no real fire is affected; the test seam's fixtures all
+// pass a real payload for the same reason.
+let event = null;
+try {
+  const parsed = JSON.parse(payload.toString('utf8'));
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) event = parsed;
+} catch { /* not JSON → no occasion → silence, below */ }
+if (!event) silent();
+
+const producers = resolveProducers(EVENT);
+if (!producers.length) silent();   // unknown event, or nothing wired for it — never speak on a guess
+
+// ── Spawn producers as CAPTURED children, collect candidate lines ──────────────────────────────────
+// stdio is piped (input buffer for stdin; stdout/stderr captured into the result). NOTHING a producer
+// writes touches the real streams — that is what makes the runtime the sole writer, and what drops a
+// rogue producer's raw bytes before they can reach a terminal.
+// ONE global deadline for ALL producers combined (GPT-5.6-Sol): sequential per-producer timeouts could
+// otherwise sum past the 5s hook budget. Each producer gets only the remaining budget; once it is spent,
+// no further producer runs. rawLines carries each line WITH its producer's authorised channel set.
+const rawLines = [];   // { s, channels }
+const DEADLINE = Date.now() + PRODUCER_TIMEOUT_MS;
+for (const p of producers) {
+  const remaining = DEADLINE - Date.now();
+  if (remaining <= 0) break;                 // global budget spent → run no more producers
+  let out = '';
+  try {
+    const r = spawnSync(p.argv[0], p.argv.slice(1), {
+      input: p.feedStdin ? payload : Buffer.alloc(0),
+      env: { ...process.env, RUVNET_EMIT_CANDIDATES: '1' },
+      timeout: remaining,
+      maxBuffer: MAX_BUFFER,
+    });
+    // FAIL CLOSED (GPT-5.6-Sol): a producer that errored, exited non-zero, was signalled (a timeout kill),
+    // or overflowed maxBuffer has UNTRUSTWORTHY partial output — discard it, never deliver a fragment.
+    if (!r.error && r.status === 0 && !r.signal && r.stdout) out = r.stdout.toString('utf8');
+  } catch { out = ''; }   // a failed spawn contributes no candidates — never a failure of the turn
+  for (const line of out.split('\n')) {
+    const s = line.trim();
+    if (s) rawLines.push({ s, channels: p.channels });
+  }
+}
+
+// ── Parse candidates. Anything that is not a well-formed candidate object is dropped here, which is
+// where the "raw bytes are a protocol violation" guarantee is actually enforced. ───────────────────
+const MAX_COPY = 8192;   // a real advisory is short; cap so a rogue/buggy 900KB emission cannot bloat delivery
+const candidates = [];
+for (const { s, channels } of rawLines) {
+  let c;
+  try { c = JSON.parse(s); } catch { continue; }              // not JSON → drop (a rogue's raw line)
+  if (!c || typeof c !== 'object' || Array.isArray(c)) continue;
+  if (!VALID_CHANNELS.has(c.channel)) continue;               // unknown/absent channel → drop
+  if (!channels.includes(c.channel)) continue;                // ANTI-SPOOF (GPT-5.6-Sol): this producer is
+                                                              // not authorised for this channel → drop
+  if (!VALID_EFFECTS.has(c.effect)) continue;                 // unknown/absent effect → drop
+  if (typeof c.copy !== 'string' || !c.copy.trim()) continue; // nothing to say → drop
+  c.copy = c.copy.slice(0, MAX_COPY);                         // cap size; delivery below is synchronous
+  candidates.push(c);
+}
+if (!candidates.length) silent();
+
+// ── Lazy access to the REAL dial read and the REAL DismissalLedger. Reused, not re-implemented. ────
+// The dial comes from user-settings.loadSettings() (the versioned-envelope reader that honours
+// RUVNET_SETTINGS_FILE); suppression comes from advocacy-outcomes.shouldStillOffer()/record(). Both
+// are loaded only if an advocacy/promotion candidate is actually present, so a lesson- or alarm-only
+// event pays nothing for them.
+const SETTINGS_MODULE = process.env.RUVNET_USER_SETTINGS_MODULE || path.join(CODE_ROOT, 'scripts', 'user-settings.mjs');
+const ADVOCACY_MODULE = process.env.RUVNET_ADVOCACY_OUTCOMES_MODULE || path.join(CODE_ROOT, 'scripts', 'advocacy-outcomes.mjs');
+
+// THE 1–5 DIAL (ADR-052). This runtime is the SINGLE enforcement chokepoint (DDD-0004): the level maps
+// to exactly what each channel is allowed to deliver, and no producer decides. LEVEL_POLICY is the one
+// source of truth for that mapping — it is mirrored in the human copy of user-settings.mjs's `levels`,
+// and the two must move together.
+//   1 Only-when-I-ask : nothing unprompted (alarms still fire)
+//   2 Critical-only   : advocacy for HIGH-severity findings only; no promotions
+//   3 Balanced        : advocacy for relevant findings; no promotions          ← default
+//   4 Proactive       : advocacy + lesson-promotion nudges
+//   5 Maximum help    : advocacy + promotions (broadest)
+const LEVEL_POLICY = {
+  1: { advocacy: false, promotion: false, severityFloor: null },
+  2: { advocacy: true,  promotion: false, severityFloor: 'high' },
+  3: { advocacy: true,  promotion: false, severityFloor: null },
+  4: { advocacy: true,  promotion: true,  severityFloor: null },
+  5: { advocacy: true,  promotion: true,  severityFloor: null },
+};
+const LEGACY_LEVEL = { off: 1, 'important-only': 3, all: 4 };   // defensive: map a raw pre-migration value too
+
+let _level;
+async function advocacyLevel() {
+  if (_level !== undefined) return _level;
+  // Default 3 (Balanced) — matches user-settings' default AND preserves the old 'important-only'
+  // behaviour (advocacy on, promotion off) for anyone who never touched the setting.
+  _level = 3;
+  try {
+    const m = await import(pathToFileURL(SETTINGS_MODULE).href);
+    if (typeof m.loadSettings === 'function') {
+      const v = m.loadSettings().values?.advocacy;   // loadSettings already migrates legacy strings → 1-5
+      const n = typeof v === 'number' ? v : LEGACY_LEVEL[v];
+      if (Number.isInteger(n) && n >= 1 && n <= 5) _level = n;
+    }
+  } catch { /* keep the safe default */ }
+  return _level;
+}
+async function policy() { return LEVEL_POLICY[await advocacyLevel()] || LEVEL_POLICY[3]; }
+
+let _ledger = null;      // { shouldStillOffer, record, ACTIONS } or null if unavailable
+let _ledgerTried = false;
+async function ledger() {
+  if (_ledgerTried) return _ledger;
+  _ledgerTried = true;
+  try {
+    const m = await import(pathToFileURL(ADVOCACY_MODULE).href);
+    if (typeof m.shouldStillOffer === 'function' && typeof m.record === 'function' && m.ACTIONS) {
+      _ledger = { shouldStillOffer: m.shouldStillOffer, record: m.record, ACTIONS: m.ACTIONS };
+    }
+  } catch { _ledger = null; }
+  return _ledger;
+}
+
+// ── Apply per-channel policy ───────────────────────────────────────────────────────────────────────
+const advisories = [];   // { copy, hookEventName }
+const blocks = [];       // reason strings
+
+for (const c of candidates) {
+  const hookEventName = typeof c.hookEventName === 'string' && c.hookEventName.trim() ? c.hookEventName.trim() : null;
+  const copy = c.copy.trim();
+
+  switch (c.channel) {
+    case 'alarm':
+      // Always delivered, never gated. Alarms inform; they do not refuse — a stray block effect on an
+      // alarm is treated as advisory rather than allowed to refuse the user's work.
+      advisories.push({ copy, hookEventName });
+      break;
+
+    case 'lesson':
+      if (c.effect === 'block') {
+        // The lesson producer only emits effect:'block' for a lesson the user personally opted into
+        // (blocking-optin.json). The runtime propagates that refusal untouched — it never invents one
+        // and never swallows one.
+        blocks.push(copy);
+      } else {
+        advisories.push({ copy, hookEventName });
+      }
+      break;
+
+    case 'promotion': {
+      // DDD-0004's three-channels table + ADR-052's 1–5 dial: lesson-promotion nudges are delivered
+      // only at levels 4–5 (Proactive / Maximum). A block effect from promotion is a protocol
+      // violation → drop it.
+      if (c.effect !== 'advisory') break;
+      if (!(await policy()).promotion) break;   // levels 1–3 ⇒ no promotion nudges
+      advisories.push({ copy, hookEventName });
+      break;
+    }
+
+    case 'advocacy': {
+      // The dial AND the DismissalLedger, enforced centrally on the candidate — this is the chokepoint's
+      // whole point: even a naive or rogue producer that emits an advocacy candidate is dropped when the
+      // dial is off or the finding is suppressed.
+      if (c.effect !== 'advisory') break;                    // advocacy cannot block
+      const findingId = typeof c.findingId === 'string' && c.findingId.trim() ? c.findingId.trim() : '';
+      if (!findingId) break;                                 // malformed advocacy candidate → drop
+      const severity = typeof c.severity === 'string' && c.severity.trim() ? c.severity.trim() : null;
+      const pol = await policy();
+      if (!pol.advocacy) break;                              // level 1 ⇒ nothing (INVARIANT 2: exit 0, stdout "")
+      if (pol.severityFloor === 'high' && severity !== 'high' && severity !== 'critical') break;   // level 2 ⇒ high-severity only
+      const led = await ledger();
+      if (!led) break;                                       // cannot verify the ledger → stay silent (safe)
+      const stateHash = typeof c.observationHash === 'string' && c.observationHash.trim() ? c.observationHash.trim() : null;
+      let offer = true;
+      try { offer = led.shouldStillOffer(findingId, { severity, stateHash }); } catch { offer = false; }
+      if (!offer) break;                                     // dismissed / budget spent → drop
+      // Deliver, and record the OFFERED denominator centrally (best-effort; recording never breaks
+      // the hook it measures). Moving OFFERED here is what makes precision computable at the one place
+      // that actually decides to show a card.
+      try { led.record({ id: findingId, action: led.ACTIONS.OFFERED, severity, stateHash }); } catch { /* a lost row costs one denominator, never the turn */ }
+      advisories.push({ copy, hookEventName });
+      break;
+    }
+
+    default:
+      break;   // unreachable — VALID_CHANNELS already filtered
+  }
+}
+
+// ── Deliver. A surviving block dominates everything. ───────────────────────────────────────────────
+if (blocks.length) {
+  // Exit 2: stdout is ignored by the harness and MUST be byte-empty; stderr becomes the model's refusal
+  // reason. SYNCHRONOUS write (GPT-5.6-Sol) — process.exit() after an async write drops buffered bytes on a
+  // pipe (measured 900KB→8KB). Advisories collected this pass are discarded: a refusal supersedes.
+  try { fs.writeSync(2, blocks.join('\n') + '\n'); } catch { /* nothing else to do at the boundary */ }
+  process.exit(2);
+}
+
+if (!advisories.length) silent();
+
+// hookEventName MUST name the firing CC event or the harness discards the envelope. DERIVE it from the
+// runtime's own EVENT (GPT-5.6-Sol) rather than trusting a producer-stamped value — the runtime knows the
+// real event and a producer must not be able to restamp it. "PreToolUse-bash" → "PreToolUse".
+const hookEventName = EVENT ? EVENT.split('-')[0] : 'UserPromptSubmit';
+
+// SYNCHRONOUS write — the truncation fix on the byte-owner itself (see the block path above).
+const additionalContext = advisories.map((a) => a.copy).join('\n\n');
+try { fs.writeSync(1, JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext } })); }
+catch { /* if even the final write fails, silence is the fail-safe */ }
+process.exit(0);