ruvnet-brain 3.9.133-dev → 4.0.1

package/plugin/scripts/continuation-gate.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * continuation-gate.mjs — the gate that fires on STOPPING, because nothing else can.
+ *
+ * THE HOLE THIS CLOSES, and it is a real architectural gap in ADR-030, not a missing feature.
+ *
+ * Every gate in this project fires on an ACTION: a Write, an Edit, a push, a claim, a status
+ * report. That is what makes them enforceable — there is a tool call to intercept.
+ *
+ * **Stopping is the absence of an action.** When the model finishes a unit of work, writes a
+ * summary, and waits — no tool fires, no text is classified, nothing is intercepted. The single
+ * most costly failure of 2026-07-22 had NO TRIGGER, which is why a system explicitly built to
+ * prevent it did not prevent it.
+ *
+ * The owner, 05:45, and it is the correct indictment: *"This was exactly the stuff that RuvNet-Brain
+ * was designed to stop, so the fact that you didn't is yet another failure... you agree you are
+ * going to finish something and you stop because you have some excuse, and then you don't start
+ * yourself up again."*
+ *
+ * L13 was recorded and ratified an hour earlier and did not help, because it fires on
+ * `report-status` — it can only catch a stop that ANNOUNCES itself. A silent stop is invisible to
+ * every gate in the system.
+ *
+ * HOW THIS WORKS. A `Stop` hook runs when a turn ends. It reads the work ledger — a plain list of
+ * committed-to items with a done state — and if authorized work remains unfinished, it says so, in
+ * the last place the model looks before going quiet.
+ *
+ * WHAT IT DOES, verified against code.claude.com/docs/en/hooks.md (2026-07-23, not recalled, ADR-043):
+ * a Stop hook's `additionalContext` at exit 0 DOES force a continuation — under the same loop
+ * protections as decision:block (the `stop_hook_active` input + the 8-consecutive-continuation cap). An
+ * earlier version of this header claimed "a Stop hook cannot force another turn"; that was wrong. The
+ * gate still exits 0 always — continuation is driven by the envelope, never by a non-zero exit code.
+ *
+ * FAILS OPEN ALWAYS. Exit 0 unconditionally. A gate that breaks a turn's completion because it
+ * could not read a JSON file would be disabled within a day, and a disabled gate protects nothing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readStdinBounded } from './hook-input.mjs';
+
+const HOME = os.homedir();
+
+// The only exit code this file may ever use. A Stop hook that exits non-zero refuses to let the turn
+// end; this gate informs and never refuses, so every path below returns exactly this.
+const EXIT_ALLOW = 0;
+/**
+ * PROJECT-SCOPED, because this runs machine-wide.
+ *
+ * The owner runs three projects simultaneously. A single global ledger would mix their commitments
+ * and fire "you did not finish X" in a repo that never heard of X — which is a false alarm, and
+ * ADR-028 fixes the false-alarm rate at ZERO. So the ledger is keyed by the git repo root (falling
+ * back to cwd), stored centrally under ~/.config so it survives `--update`, but partitioned per
+ * project so the three never see each other's work.
+ */
+function projectKey() {
+  let dir = process.cwd();
+  // Walk up to the git root — the stable identity of a project, regardless of which subdirectory
+  // a hook happens to fire from. (A CWD-derived key was exactly the bug that scattered ledgers
+  // through users' project trees in issue #36.)
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) break;
+    const up = path.dirname(dir);
+    if (up === dir) { dir = process.cwd(); break; }
+    dir = up;
+  }
+  return path.basename(dir).replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+const LEDGER = process.env.RUVNET_WORK_LEDGER
+  || path.join(HOME, '.config', 'ruvnet-brain', 'work-ledgers', `${projectKey()}.json`);
+
+const argv = process.argv.slice(2);
+const arg = (f) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : null; };
+const has = (f) => argv.includes(f);
+
+function load() {
+  try {
+    const j = JSON.parse(fs.readFileSync(LEDGER, 'utf8'));
+    return Array.isArray(j.items) ? j : { items: [] };
+  } catch { return { items: [] }; }
+}
+function save(led) {
+  try {
+    fs.mkdirSync(path.dirname(LEDGER), { recursive: true });
+    fs.writeFileSync(LEDGER, JSON.stringify({ ...led, updated: new Date().toISOString() }, null, 2) + '\n');
+  } catch { /* the ledger is advisory — never break a turn over it */ }
+}
+
+// ── commands ─────────────────────────────────────────────────────────────────────────────────────
+if (has('--commit-to')) {
+  // Record work the model AGREED to do. The agreement is the thing that makes stopping a defect —
+  // without it, ending a turn is simply finishing, and this gate must stay silent.
+  const led = load();
+  const text = arg('--commit-to');
+  if (text && !led.items.some((i) => i.text === text && !i.done)) {
+    led.items.push({ text, done: false, at: new Date().toISOString() });
+    save(led);
+  }
+  console.log(`committed: ${text}`);
+  process.exit(0);
+}
+
+if (has('--done')) {
+  const led = load();
+  const needle = arg('--done');
+  // EXACT text match only (GPT-5.6-Sol review). The earlier "unambiguous substring" fallback could still
+  // clear a SINGLETON open item via a fragment — a fake-completion valve under a gate that now applies real
+  // continuation pressure. Marking done requires the item's exact text (copy it from the ledger line).
+  const targets = led.items.filter((i) => !i.done && i.text === needle);
+  for (const i of targets) { i.done = true; i.doneAt = new Date().toISOString(); }
+  save(led);
+  console.log(`marked done: ${targets.length}`);
+  process.exit(0);
+}
+
+if (has('--clear')) { save({ items: [] }); console.log('ledger cleared'); process.exit(0); }
+
+// ── the Stop hook itself (default action) ────────────────────────────────────────────────────────
+/**
+ * READ THE PAYLOAD. Every Stop hook receives a JSON object on stdin, and until 2026-07-22 this file
+ * ignored it completely — which made the loop guard below not merely absent but UNREACHABLE.
+ *
+ * Never block waiting for stdin: the CLI paths (--commit-to / --done) are invoked from a terminal
+ * with no piped input, and a gate that hangs is worse than a gate that is silent.
+ */
+async function readHookInput() {
+  // Three cases, treated DIFFERENTLY (ADR-043, Fable red-team #1):
+  //  - 'tty'        : run bare in a terminal, not as a hook → never force.
+  //  - 'unreadable' : stdin present but read/parse FAILED. `fs.readFileSync(0)` throws EAGAIN
+  //                   intermittently on macOS — a real footgun. The old code returned {} here, which
+  //                   under a forcing gate LAUNDERS a read error into a fresh-stop verdict → a forced
+  //                   loop. We must not force when we could not confirm the payload.
+  //  - 'stdin'      : a payload we actually parsed → the only case allowed to force.
+  if (process.stdin.isTTY) return { __source: 'tty' };
+  try {
+    const raw = (await readStdinBounded()).toString('utf8');
+    return { ...JSON.parse(raw || '{}'), __source: 'stdin' };
+  } catch { return { __source: 'unreadable' }; }
+}
+const hookInput = await readHookInput();
+
+// LOOP-SAFETY 1 (ADR-043 / Fable #1) — only an affirmatively-parsed hook payload may force. A 'tty' or
+// 'unreadable' source cannot be confirmed a fresh stop, so it never forces.
+if (hookInput.__source !== 'stdin') process.exit(EXIT_ALLOW);
+
+/**
+ * LOOP-SAFETY 2 — the documented guard. `stop_hook_active` is true once Claude Code is already
+ * continuing because of a stop hook (verified against code.claude.com/docs/en/hooks.md, ADR-043).
+ * Honouring it caps each natural-stop episode at EXACTLY ONE forced continuation. Truthy, not
+ * `=== true`, so a future string/number drift ("true", 1) cannot slip past into a loop.
+ */
+if (hookInput.stop_hook_active) process.exit(EXIT_ALLOW);
+
+const led = load();
+const nowMs = Date.now();
+
+// LOOP-SAFETY 1b (GPT-5.6-Sol review) — an empty-but-parseable `{}` is NOT a real Stop payload; a genuine
+// one carries `session_id` (a documented Stop input). Without it we cannot confirm a real stop, so we never
+// force. This closes the empty-stdin hole that LOOP-SAFETY 1's `__source` check does not cover.
+if (!hookInput.session_id) process.exit(EXIT_ALLOW);
+
+const open = led.items.filter((i) => !i.done);
+if (!open.length) process.exit(EXIT_ALLOW);   // nothing outstanding: silence is correct
+
+/**
+ * FRESHNESS (ADR-043 / Fable #3, tightened by GPT-5.6-Sol) — only FORCE for work with a VALID, recent
+ * timestamp. A missing or unparseable `at` is treated as STALE and NOT forced: a real item always carries
+ * an `at` (set by --commit-to), so only a malformed/legacy row lacks one, and forcing forever on an item of
+ * UNKNOWN age is exactly the fabrication-pressure this guard exists to stop.
+ */
+// CORRECTED 2026-07-24, SAME DAY IT WAS INTRODUCED — and it had already broken the gate for ~30 hours.
+//
+// The guard above was written to stop "forcing forever on an item of UNKNOWN age." That intent is
+// right and is preserved: a row with a missing or unparseable `at` is still refused, because an item
+// of unknown age can nag forever with no evidence it is real.
+//
+// What shipped was different and wrong: `(nowMs - t) < 24h` ALSO discarded items with a perfectly
+// VALID timestamp that were merely old. Measured on this machine: four genuinely-open commitments
+// aged 53-56h, `forceable` came back empty, and the gate exited EXIT_ALLOW in silence. The owner's
+// single most emphatic standing rule — "do not stop until it is done" — was enforced by a mechanism
+// that had quietly switched itself off, and the only symptom was nothing happening.
+//
+// The inversion is the lesson: OLD OPEN WORK IS THE CASE THAT MOST NEEDS THE NUDGE. Work finished in
+// an hour never reaches this gate. Work still open after two days is exactly what gets forgotten, and
+// treating age as a reason for silence hands the failure mode a timer. It is the same shape as every
+// other defect found today — silence standing in for a measurement — committed inside the guard whose
+// whole job is to prevent stopping early.
+//
+// So: age no longer gates DELIVERY, it decorates it. An old item is still forced, and the nudge SAYS
+// how old it is, which is information the reader needs rather than a reason to withhold. If a ledger
+// is genuinely abandoned, the honest fix is to mark its items done — not to let a clock silently
+// decide the commitment expired.
+const forceable = open.filter((i) => Number.isFinite(Date.parse(i.at)));
+if (!forceable.length) process.exit(EXIT_ALLOW);
+
+/** Age, only ever used to LABEL an item — never to suppress one. See the note above. */
+const ageLabel = (i) => {
+  const h = (nowMs - Date.parse(i.at)) / 3_600_000;
+  if (h < 1) return '';
+  if (h < 24) return ` (committed ${Math.round(h)}h ago)`;
+  return ` (committed ${Math.round(h / 24)}d ago — still open)`;
+};
+
+/**
+ * LOOP-SAFETY 3 (belt-and-braces this file OWNS — Fable #1, made fail-closed + race-safe by the GPT-5.6-Sol
+ * review). Claim the force ATOMICALLY via an exclusive-create lock that doubles as the cooldown marker:
+ *   - a fresh lock (another force within COOLDOWN_MS, incl. a concurrent second Stop hook) → do NOT force;
+ *   - the claim cannot be persisted → do NOT force (fail CLOSED — never a force we could not record);
+ *   - exclusive create (`wx`) serialises two racing hooks so they can never both win.
+ * This replaces a read-lastForcedAt-then-write that failed OPEN on a write error and let two hooks race.
+ */
+const COOLDOWN_MS = Number(process.env.RUVNET_CONTINUATION_COOLDOWN_MS ?? 20000);
+const LOCK = LEDGER + '.cooldown';
+function claimCooldown(now, windowMs) {
+  try {
+    const prev = Date.parse(fs.readFileSync(LOCK, 'utf8'));
+    if (Number.isFinite(prev) && (now - prev) < windowMs) return false; // fresh lock: someone forced recently
+    fs.unlinkSync(LOCK);                                                 // stale: clear it so we can re-claim
+  } catch { /* no lock yet */ }
+  try { fs.writeFileSync(LOCK, new Date(now).toISOString(), { flag: 'wx' }); return true; }
+  catch { return false; }                                               // lost the race / cannot persist → fail closed
+}
+if (!claimCooldown(nowMs, COOLDOWN_MS)) process.exit(EXIT_ALLOW);
+
+/**
+ * DELIVERY. `additionalContext` in a Stop envelope forces the continuation (same protection as
+ * decision:block). Directive copy — continue, do not look for an exit.
+ */
+const lines = [
+  'You have unfinished work you committed to. Do NOT end the turn — continue now.',
+  'Pick the highest-leverage open item below and make real progress on it this turn. Stop only when',
+  'EVERY item is genuinely done or blocked; if one is blocked, say why in a single line and move to',
+  'the next — never stop on the first obstacle, and never manufacture a reason to go quiet.',
+  '',
+  // Age is LABELLED, never used to suppress — an item open for days is the one most worth naming.
+  ...forceable.slice(0, 8).map((i) => `  ☐ ${i.text}${ageLabel(i)}`),
+  ...(forceable.length > 8 ? [`  … and ${forceable.length - 8} more`] : []),
+  '',
+  'Mark each item done as you complete it:  node plugin/scripts/continuation-gate.mjs --done "<exact item text>"',
+  // THE HONEST EXIT, and it is what makes forcing old items safe.
+  //
+  // Fable's red-team #3 was right that a stale item pressuring every turn "breeds
+  // mark-done-without-doing". The first answer to that was a 24h TTL — which silently disabled the
+  // gate on genuine multi-day work (measured 2026-07-24: four real commitments, 53-56h old, gate mute
+  // for ~30 hours). Both failure modes are real, and they are not opposites: the pressure to fake a
+  // completion comes from being nagged with NO LEGITIMATE WAY OUT.
+  //
+  // So the resolution is neither silence nor endless nagging: keep forcing, and name the honest
+  // disposal out loud. An item that is genuinely dead gets cleared — a deliberate, recorded act —
+  // instead of expiring on a timer nobody sees, or being falsely marked done to stop the noise.
+  ...(forceable.some((i) => (nowMs - Date.parse(i.at)) > 24 * 3_600_000)
+    ? ['', 'Some of these are days old. If one is genuinely no longer real, say so and CLEAR it —',
+       'that is a legitimate answer and the right one. What is never acceptable is marking it done',
+       'without doing it, or letting it age quietly out of view.']
+    : []),
+];
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'Stop',            // must name the firing event or the envelope is discarded
+    additionalContext: lines.join('\n'),
+  },
+}));
+
+// Exit 0 regardless. This gate informs at the boundary; it never breaks the turn.
+process.exit(EXIT_ALLOW);

package/plugin/scripts/design-wall.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# design-wall.sh — PreToolUse gate on Bash. NOTHING VISUAL SHIPS, COMMITS, OR OPENS UNGRADED.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# WHY (2026-07-16). Stuart, after a carelessly-composed public band shipped twice: "You are always,
+# and I mean always, supposed to look at a page as an end user would: take pictures of it, review it,
+# analyze it, grade it, see if it gets a 95 or better, and if it doesn't, tweak it until it does —
+# before you ever tell me something is ready." And when that landed as a memory note instead of a
+# mechanism: "Suggestions mean bullshit to you. RuvNet Brain needs to be smart enough to make sure
+# those suggestions become law and the law becomes followed."
+#
+# He is right about the mechanism. This repo's entire history says advisory rules fail and walls hold
+# (route-dispatch, verify-interface, ground-before-write, substitution:check, narrative-version).
+# So the 95-gate is a WALL: deploying the explainer, committing visual surfaces, or opening a page
+# for the user REQUIRES a fresh passing design-grade stamp for that surface. The only key is
+# scripts/design-grade.mjs, which itself refuses to stamp without >=2 fresh screenshots at distinct
+# widths and written deductions. The grade stays judgment; the ritual is enforced; the receipt is
+# auditable.
+#
+# CONTRACT: exit 0 = allow · exit 2 + stderr = BLOCK (stderr returns to the model as the reason).
+# FAILS OPEN on anything it cannot parse — a gate that breaks the shell protects nothing.
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+set -uo pipefail
+
+INPUT=""
+# BOUNDED READ (2026-07-27, ADR-055 F20): an unqualified `read` never returns on a stdin that is
+# opened and never closed — measured across the mesh, 18 of 37 registered commands sat until the
+# harness killed them. Real Claude Code writes and closes, so this costs no normal turn; that is
+# exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
+# is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
+# the whole thing back at once and a per-iteration cap never fires.
+while IFS= read -r -t 2 _l; do
+  INPUT+="$_l"
+  [ ${#INPUT} -ge 65536 ] && break
+done
+[ -n "$_l" ] && INPUT+="$_l"
+INPUT="${INPUT:0:65536}"
+[ -n "$INPUT" ] || exit 0
+
+# Parse the payload with the shared JSON parser (hook-input.mjs), NOT a bash regex. The old
+# field() { …"([^"]*)"… } truncated any command containing a quote at the first one — the exact
+# #13 fail-open verify-interface.sh already fixed, silently reintroduced here (design-wall.sh was
+# written after). node is present in Claude Code's environment; fail open (exit 0) if it isn't. ADR-0021.
+NODE_BIN=$(command -v node) || exit 0
+HOOK_INPUT="$(dirname "${BASH_SOURCE[0]}")/hook-input.mjs"
+[ "$(printf '%s' "$INPUT" | "$NODE_BIN" "$HOOK_INPUT" tool_name 2>/dev/null)" = "Bash" ] || exit 0
+CMD=$(printf '%s' "$INPUT" | "$NODE_BIN" "$HOOK_INPUT" command 2>/dev/null)
+[ -n "$CMD" ] || exit 0
+
+# ── Repo identity gate (2026-07-17, issue #17) ───────────────────────────────────────────────────
+# BUG: this hook never checked WHICH repo it was running in, so a plain `git commit` touching a
+# README.md in ANY unrelated project on this machine (any repo where the plugin happens to be
+# installed) got blocked demanding a ruvnet-brain design-grade ritual for someone else's CLI tool.
+# The whole point of this wall is to guard ruvnet-brain's OWN surfaces — its stamp path lives under
+# ~/.cache/ruvnet-brain, and explainer/ + console/ only exist in ruvnet-brain's own checkout — so it
+# has no business firing anywhere else. Identify the repo via the plugin manifest's own name field
+# first (authoritative — a renamed clone/fork can't fake it just by matching a directory name), and
+# fall back to the console/+explainer/+design-grade.mjs trio only if the manifest is missing.
+ROOT=$(git -C "${CLAUDE_PROJECT_DIR:-.}" rev-parse --show-toplevel 2>/dev/null)
+[ -n "$ROOT" ] || exit 0
+IS_RUVNET_BRAIN=0
+if [ -f "$ROOT/plugin/.claude-plugin/plugin.json" ]; then
+  grep -Eq '"name"[[:space:]]*:[[:space:]]*"ruvnet-brain"' "$ROOT/plugin/.claude-plugin/plugin.json" 2>/dev/null && IS_RUVNET_BRAIN=1
+elif [ -d "$ROOT/console" ] && [ -d "$ROOT/explainer" ] && [ -f "$ROOT/scripts/design-grade.mjs" ]; then
+  IS_RUVNET_BRAIN=1
+fi
+[ "$IS_RUVNET_BRAIN" = "1" ] || exit 0
+
+# ── The escape hatch, made reachable (2026-07-17) ────────────────────────────────────────────────
+# BUG: this check read RUVNET_SKIP_DESIGN_WALL from the HOOK's own environment. But a PreToolUse
+# hook runs in its own process, spawned BEFORE the command exists — so `RUVNET_SKIP_DESIGN_WALL=1
+# git commit …` set the variable for git and the wall never saw it. The wall advertised an override
+# that nobody on the agent side could actually use. It deadlocked a commit whose only visual diff
+# was two version strings written by sync-version.mjs (zero pixels changed), leaving exactly two
+# exits: fake a >=95 self-grade to open the gate, or don't ship. That first exit is the precise
+# failure this repo learned the hard way on 2026-07-17 — a self-assigned grade of my own taste,
+# laundered into a timestamped receipt (Stuart looked at a page I had graded 96 and scored it 55).
+# An UNREACHABLE escape hatch is worse than none: it turns "this gate is wrong in this case" into
+# "this gate cannot be wrong", and a gate that cannot be wrong is not a gate, it is a wish.
+# So: still honored from the env, and now also from the command string — but LOUD. Every override
+# writes a receipt, so skipping the wall leaves the same auditable trail as being caught by it.
+# The wall still holds for anything that actually changed pixels; it just can no longer force a lie.
+if [ "${RUVNET_SKIP_DESIGN_WALL:-0}" = "1" ] || [[ $CMD == *"RUVNET_SKIP_DESIGN_WALL=1"* ]]; then
+  bash "$(dirname "${BASH_SOURCE[0]}")/gate-receipt.sh" design-wall override \
+    "deliberate override — wall skipped, reason stated in the turn" 2>/dev/null || true
+  exit 0
+fi
+
+STAMPDIR="$HOME/.cache/ruvnet-brain"
+need=()
+
+# 1) Production deploys of the public explainer.
+if [[ $CMD == *vercel* && $CMD == *--prod* ]]; then need+=("explainer"); fi
+
+# 2) Commits that stage visual surfaces.
+if [[ $CMD == *"git commit"* ]]; then
+  STAGED=$(git -C "${CLAUDE_PROJECT_DIR:-.}" diff --cached --name-only 2>/dev/null || true)
+  [[ $STAGED == *"explainer/"* ]] && need+=("explainer")
+  [[ $STAGED == *"console/"*   ]] && need+=("console")
+  [[ $STAGED == *"README.md"*  ]] && need+=("readme")
+fi
+
+# 3) Opening a page for the user — presenting IS shipping.
+if [[ $CMD =~ open[^\|\;]*https?:// ]]; then
+  [[ $CMD == *"isovision.ai/ruvnet-brain"* || $CMD == *"ruvnet-brain.vercel.app"* ]] && need+=("explainer")
+  [[ $CMD == *"localhost:7411"* || $CMD == *"127.0.0.1:7411"* ]] && need+=("console")
+fi
+
+[ ${#need[@]} -eq 0 ] && exit 0
+
+for s in "${need[@]}"; do
+  ST="$STAMPDIR/design-stamp-$s.json"
+  ok=0
+  if [ -f "$ST" ] && grep -Eq '"passing":[[:space:]]*true' "$ST" 2>/dev/null; then
+    agemin=$(( ( $(date +%s) - $(stat -f %m "$ST" 2>/dev/null || echo 0) ) / 60 ))
+    [ "$agemin" -le 45 ] && ok=1
+  fi
+  if [ "$ok" != "1" ]; then
+    # Record the catch BEFORE refusing. The block is the evidence — without this line the ledger
+    # shows only the passing grade that came after the fix, and the wall cannot prove it ever held.
+    bash "$(dirname "${BASH_SOURCE[0]}")/gate-receipt.sh" design-wall "$s" "ungraded visual surface, no fresh passing grade" 2>/dev/null || true
+    cat >&2 <<EOF
+⛔ DESIGN WALL — no fresh passing grade for surface '$s'.
+Nothing visual ships, commits, or opens for the user until it has been LOOKED AT as an end user
+would and graded 95 or better. The ritual (minutes, enforced):
+  1. Screenshot the REAL surface at TWO widths (1440 and ~1920).
+  2. LOOK at both. Actively: does it look great? typography right? does every block earn its place?
+     Write the deductions down.
+  3. node scripts/design-grade.mjs --surface $s --grade <n> --shot <p1> --shot <p2> --deductions "…"
+     Below 95 it records the grade and STAYS CLOSED — fix, re-shoot, re-grade until it opens.
+Stamp: $ST (valid 45 min — pages change, grades expire).
+Deliberate override (rare, say why out loud): RUVNET_SKIP_DESIGN_WALL=1
+EOF
+    exit 2
+  fi
+done
+exit 0

package/plugin/scripts/detach.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * detach.mjs — launch one long-running maintenance job OUT of the hook's process group, with an
+ * explicit lifetime and a written receipt.
+ *
+ * ── THE DEFECT THIS EXISTS TO CLOSE (measured, not reasoned) ────────────────────────────────────
+ * `scripts/selfcheck.mjs` fires every registration with the child in its OWN process group and then
+ * asks, at exit and again after SIGTERM, whether ANYTHING in that group is still alive
+ * (`kill(-pgid, 0)`). session-start.sh backgrounded three jobs with a bare `&`. A bare `&` in a
+ * non-interactive `sh` does NOT change the process group — the job stays a member of the hook's
+ * group — so the answer was "yes, descendants alive": the `orphan` violation the stranger-matrix
+ * reported on all five images. The failure is real and not cosmetic: on a stranger's machine those
+ * are `node` and `claude` processes still running after Claude Code has moved on, invisible to the
+ * user and multiplied by every session start.
+ *
+ * ── WHY THE JOBS ARE NOT SIMPLY KILLED AT EXIT ─────────────────────────────────────────────────
+ * "Kill the group on the way out" is the obvious fix and it is wrong for this workload. The three
+ * jobs are a spine seed, a signed-bundle freshness check, and a plugin auto-update; each is seconds
+ * to minutes of work, and session-start.sh exits in ~200ms. Killing them on exit would mean the
+ * update NEVER completes on any machine — trading a hygiene violation for a permanently broken
+ * updater. So the honest answer is the third one ADR-023 already implies: these jobs do not belong
+ * to the session's lifetime at all. They are machine maintenance, like a package manager's
+ * background install, and they are moved out of the session's process group ON PURPOSE.
+ *
+ * "On purpose" has to be worth something, so it comes with two obligations this file discharges:
+ *
+ *   1. AN EXPLICIT LIFETIME. Every job carries a TTL in seconds. A supervisor — itself detached —
+ *      holds a timer and SIGTERMs the job's whole group at the deadline (SIGKILL 3s later). A
+ *      detached job with no deadline is exactly the invisible-forever process this file is fixing;
+ *      moving it to a new process group without a clock would only hide it better.
+ *   2. A RECEIPT. Every start, exit and TTL-kill appends one line to
+ *      ~/.cache/ruvnet-brain/detached-jobs.jsonl. "Invisible and unkillable-by-the-user" was half
+ *      the complaint; a user who wants to know what is running, or wants to kill it, has a pid and
+ *      a command to look at rather than a mystery in `ps`.
+ *
+ * ── USAGE ───────────────────────────────────────────────────────────────────────────────────────
+ *   node detach.mjs <ttlSeconds> <logPath|-> <cmd> [args...]
+ * Returns in ~40ms having spawned nothing the caller must wait for. Exit code is always 0: a
+ * maintenance job that cannot be launched must never fail a session start.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SELF = fileURLToPath(import.meta.url);
+const SUPERVISOR = process.env.RUVNET_DETACH_SUPERVISOR === '1';
+const GRACE_MS = 3000; // SIGTERM → this long → SIGKILL. Matches selfcheck's own watchdog shape.
+
+let inputArgs = process.argv.slice(2);
+if (SUPERVISOR && inputArgs.length === 1 && inputArgs[0] === '--payload-env') {
+  try {
+    inputArgs = JSON.parse(Buffer.from(process.env.RUVNET_DETACH_PAYLOAD_B64 || '', 'base64').toString('utf8'));
+  } catch {
+    inputArgs = [];
+  }
+}
+const [ttlRaw, logPath, ...cmd] = inputArgs;
+const ttlSec = Number(ttlRaw);
+if (!cmd.length || !Number.isFinite(ttlSec) || ttlSec <= 0) {
+  process.stderr.write('usage: detach.mjs <ttlSeconds> <logPath|-> <cmd> [args...]\n');
+  process.exit(0); // never fail a hook over a bad maintenance invocation
+}
+
+const receiptPath = () => path.join(
+  process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ruvnet-brain', 'detached-jobs.jsonl',
+);
+
+/** Best-effort, fail-silent. A receipt that throws would defeat the point of writing one. */
+function receipt(row) {
+  try {
+    const p = receiptPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, `${JSON.stringify({ ts: new Date().toISOString(), ...row })}\n`);
+  } catch { /* a maintenance job must not die because its log directory is read-only */ }
+}
+
+/** Open the job's log, or /dev/null. Never throws — an unwritable log is not a reason to skip work. */
+function openLog() {
+  if (!logPath || logPath === '-') return 'ignore';
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    return fs.openSync(logPath, 'w');
+  } catch { return 'ignore'; }
+}
+
+if (!SUPERVISOR) {
+  // ── FOREGROUND HALF. Re-exec self, detached, and return immediately. This process IS still in the
+  // hook's process group, which is correct and is the whole trick: it is short-lived and finishes
+  // before the hook does, so the group is empty at exit. Everything with a real duration is on the
+  // far side of the setsid boundary below.
+  try {
+    const supervisorEnv = {
+      ...process.env,
+      RUVNET_DETACH_SUPERVISOR: '1',
+      RUVNET_DETACH_PAYLOAD_B64: Buffer.from(JSON.stringify(process.argv.slice(2))).toString('base64'),
+    };
+    let child;
+    if (process.platform === 'win32') {
+      // detached:true and `cmd start /b` both left the cold hook's capture pipe open on
+      // windows-latest after session-start.sh itself had finished. Start-Process crosses a native
+      // process-launch boundary without `/b`'s same-console inheritance. All variable arguments
+      // still travel in a base64 environment payload, so the PowerShell command contains only
+      // trusted executable paths and no job/log-path metacharacters.
+      const powershell = process.env.SystemRoot
+        ? path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+        : 'powershell.exe';
+      const quotePs = (value) => `'${String(value).replaceAll("'", "''")}'`;
+      const launch = [
+        'Start-Process',
+        '-FilePath', quotePs(process.execPath),
+        '-ArgumentList', `@(${quotePs(SELF)},${quotePs('--payload-env')})`,
+        '-WindowStyle', 'Hidden',
+      ].join(' ');
+      child = spawn(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', launch], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: supervisorEnv,
+      });
+    } else {
+      child = spawn(process.execPath, [SELF, ...process.argv.slice(2)], {
+        detached: true, // POSIX setsid() — the child leads its OWN process group, not the session's
+        stdio: 'ignore',
+        env: supervisorEnv,
+      });
+    }
+    child.on('error', () => {});
+    child.unref();
+  } catch { /* nothing to report — the session must start regardless */ }
+  process.exit(0);
+}
+
+// ── SUPERVISOR HALF (already outside the session's process group). Runs the real job, holds the
+// clock, and is the only thing that can end it early.
+const out = openLog();
+const job = spawn(cmd[0], cmd.slice(1), {
+  detached: true, // its own group again, so the TTL kill reaches ITS children too (npm, git, node)
+  stdio: ['ignore', out, out],
+  windowsHide: true,
+  env: process.env,
+});
+
+let killedAtTtl = false;
+receipt({ state: 'started', pid: job.pid ?? null, ttlSec, cmd });
+
+const deadline = setTimeout(() => {
+  killedAtTtl = true;
+  try { process.kill(-job.pid, 'SIGTERM'); } catch { /* already gone */ }
+  setTimeout(() => {
+    try { process.kill(-job.pid, 'SIGKILL'); } catch { /* already gone */ }
+    receipt({ state: 'killed-at-ttl', pid: job.pid ?? null, ttlSec, cmd });
+    process.exit(0);
+  }, GRACE_MS).unref();
+}, ttlSec * 1000);
+
+job.on('error', (e) => {
+  clearTimeout(deadline);
+  receipt({ state: 'spawn-failed', pid: null, ttlSec, cmd, detail: e.message });
+  process.exit(0);
+});
+job.on('exit', (code, signal) => {
+  clearTimeout(deadline);
+  if (killedAtTtl) return; // the TTL path writes its own, more specific receipt
+  receipt({ state: 'exited', pid: job.pid ?? null, code, signal, cmd });
+  process.exit(0);
+});

package/plugin/scripts/finalize-token-meter.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Replay one hook's captured stdout and append its exact byte count to the user-level ledger.
+// Kept in one process because spawning cat + wc + rm + date + pwd + sed on every SessionStart
+// consumed most of the 1s Windows UX budget.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [capturePath, ledgerDir, cwd] = process.argv.slice(2);
+
+try {
+  const output = fs.readFileSync(capturePath);
+  process.stdout.write(output);
+  fs.mkdirSync(ledgerDir, { recursive: true });
+  fs.appendFileSync(path.join(ledgerDir, 'token-ledger.jsonl'), `${JSON.stringify({
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    source: 'hook',
+    class: 'session-start',
+    bytes: output.length,
+    cwd,
+  })}\n`);
+} catch {
+  // Metering is observability, never a reason to break a session.
+} finally {
+  try { fs.rmSync(capturePath, { force: true }); } catch {}
+}

package/plugin/scripts/gate-receipt.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# gate-receipt.sh — record what a gate CAUGHT.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# WHY (2026-07-17). The walls logged only their successes. design-grades.jsonl held 13 receipts,
+# 13 of them passing — yet the design wall had just blocked a commit minutes earlier. The block left
+# no trace: the ledger showed the 96 that came after the fix, and nothing about the refusal that
+# forced it. So the system could prove Claude complied and could not prove it had ever CAUGHT Claude,
+# which is the only part anyone would want to see. Stuart, looking at the console: "make it worth
+# something, because right now it seems to be facts without purpose."
+#
+# A gate that stops something and says nothing is unfalsifiable. This makes the catch auditable.
+#
+# CONTRACT: called by a blocking gate immediately before it exits non-zero.
+#   gate-receipt.sh <gate> <subject> <reason>
+# NEVER fails, never blocks, never writes to stdout/stderr — a receipt that breaks a gate would
+# trade a real protection for a log line. Every failure path here is swallowed on purpose.
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+set -uo pipefail
+
+F="$HOME/.cache/ruvnet-brain/gate-blocks.jsonl"
+mkdir -p "$(dirname "$F")" 2>/dev/null || exit 0
+
+# Strip the few characters that would break a JSON line. Reasons are short human strings, not data.
+clean() { printf '%s' "${1:-}" | tr -d '"\\' | tr '\n\r\t' '   ' | cut -c1-160; }
+
+printf '{"at":"%s","gate":"%s","subject":"%s","reason":"%s","cwd":"%s"}\n' \
+  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  "$(clean "${1:-unknown}")" \
+  "$(clean "${2:-}")" \
+  "$(clean "${3:-}")" \
+  "$(clean "$(basename "${CLAUDE_PROJECT_DIR:-$PWD}")")" \
+  >> "$F" 2>/dev/null || true
+
+exit 0