ruvnet-brain 3.9.134-dev → 4.0.2

package/plugin/scripts/learn-capture.sh

@@ -0,0 +1,173 @@
+#!/bin/bash
+# learn-capture.sh — PostToolUse (Write|Edit|Bash). Appends ONE compact step to this session's learning
+# queue. A session is a trajectory (task -> steps -> outcome); learn-flush.mjs feeds the queue to the
+# GLOBAL SONA learner at SessionEnd, so "how you work" accumulates per-user across ALL projects — while
+# project FACTS stay in each project's .swarm/memory.db, never here. We record the workflow ACTION (a
+# command verb, a file's basename), never file CONTENT or secrets. ADR-0017.
+#
+# CONTRACT: PostToolUse is non-blocking — always exit 0, swallow every failure, no process spawn (fast).
+
+set -uo pipefail
+
+# One policy source for both capture and flush. `off` means zero bytes written. `project` keeps the
+# trajectory queue under this project's .swarm directory; `user` preserves the cross-project learner
+# introduced by ADR-0017. Tests and managed hosts may pass an already-resolved snapshot in
+# RUVNET_LEARNING_SCOPE so the two halves cannot disagree during one hook invocation.
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+SCOPE="${RUVNET_LEARNING_SCOPE:-}"
+if [ -z "$SCOPE" ] && [ -f "$HERE/runtime-preferences.mjs" ] && command -v node >/dev/null 2>&1; then
+  SCOPE=$(node "$HERE/runtime-preferences.mjs" --learning-scope 2>/dev/null) || SCOPE=""
+fi
+case "$SCOPE" in
+  off) exit 0 ;;
+  user|project) ;;
+  *) SCOPE="project" ;;
+esac
+
+# BOUNDED READ. An unqualified `read` waits forever on a stdin that is opened and never closed, and
+# an unbounded accumulator turns a large payload into an unbounded regex scan. Claude Code always
+# writes the payload and closes, so neither costs a normal turn — which is exactly why a hook that
+# CAN hang survives: the only thing ending it is a timeout owned by someone else. -t 2 is ~40x a real
+# payload's delivery time; the size cap is ~30x the largest real payload. The trailing `[ -n "$_l" ]`
+# keeps the final unterminated line, which is what the original `||` clause was for.
+INPUT=""
+while IFS= read -r -t 2 _l; do
+  INPUT+="$_l"
+  [ ${#INPUT} -ge 65536 ] && break
+done
+# Truncate the ASSEMBLED string, not just each iteration: a hook payload is one line with no trailing
+# newline, so `read` hands back the whole thing at once in $_l and the in-loop cap never fires.
+[ -n "$_l" ] && INPUT+="$_l"
+INPUT="${INPUT:0:65536}"
+[ -n "$INPUT" ] || exit 0
+
+TOOL=""
+re_t='"tool_name"[[:space:]]*:[[:space:]]*"([^"]*)"'
+[[ $INPUT =~ $re_t ]] && TOOL="${BASH_REMATCH[1]}"
+[ -n "$TOOL" ] || exit 0
+
+ACTION=""
+case "$TOOL" in
+  Bash)
+    # Capture the VERB CHAIN ONLY — "git push", "npm test", "npx vercel" — never the arguments.
+    #
+    # This previously took the first 120 chars up to an embedded quote and called that "verb, not
+    # facts". It wasn't. Unquoted inline secrets were captured in full and written to disk, proven
+    # by test: `export AWS_SECRET_ACCESS_KEY=wJalr... && psql postgres://admin:Hunter2Pass@db/prod`
+    # landed verbatim in session-*.jsonl, and from there fed the global learner. Real command lines
+    # routinely carry API keys, DB URLs with inline passwords, and internal hostnames — on a
+    # corporate laptop the hostnames alone are a DLP finding.
+    #
+    # Now: keep at most the first two tokens, and stop at the first token that carries DATA rather
+    # than INTENT (contains = / @ : , is a flag, or is improbably long). "export FOO=secret" records
+    # "export"; "cd /Users/me/ClientProject" records "cd". The learner only ever needed the verb.
+    # THE CAPTURE WAS MANGLED, and the mangling was invisible (fixed 2026-07-27).
+    #
+    # `"command"…"([^"]*)"` cannot cross a JSON-escaped quote — the exact bug hook-input.mjs exists to
+    # end — so `cd "/tmp/some dir"` captured the two bytes `cd \`, and that trailing backslash then
+    # broke the JSON line it was printed into. Measured on the owner's live queue:
+    #
+    #     {"tool":"Bash","action":"cd \"}      ← JSON.parse: Unterminated string at position 31
+    #
+    # learn-flush drops every unparseable line with a bare `continue`, so the capture reported success,
+    # the queue grew, and the learner received nothing. A pipe severed in the middle while both ends
+    # report health is this project's signature failure mode.
+    #
+    # The fix is to stop at the first quote OR backslash and take a PREFIX — no closing-quote anchor,
+    # because the first two tokens are all this hook ever wanted. A command that opens with a quoted
+    # path yields an empty prefix and is simply not captured, which is strictly better than writing a
+    # line that cannot be read back.
+    re_c='"command"[[:space:]]*:[[:space:]]*"([^"\]*)'
+    if [[ $INPUT =~ $re_c ]]; then
+      set -f                      # no globbing while we word-split untrusted text
+      _n=0
+      for _tok in ${BASH_REMATCH[1]}; do
+        case "$_tok" in
+          *=*|*/*|*@*|*:*|-*) break ;;
+        esac
+        [ ${#_tok} -gt 24 ] && break
+        ACTION="${ACTION:+$ACTION }$_tok"
+        _n=$((_n + 1))
+        [ "$_n" -ge 2 ] && break
+      done
+      set +f
+    fi
+    ;;
+  Write|Edit|MultiEdit)
+    re_f='"file_path"[[:space:]]*:[[:space:]]*"([^"]*)"'
+    [[ $INPUT =~ $re_f ]] && ACTION="edit ${BASH_REMATCH[1]##*/}"   # basename only — no full path
+    ;;
+esac
+[ -n "$ACTION" ] || exit 0
+
+# THE SESSION ID IS IN THE PAYLOAD WE ALREADY READ — and it was being thrown away.
+#
+# This read `${CLAUDE_SESSION_ID:-default}`, an env var Claude Code does not set, so EVERY session on
+# a machine appended to one shared `session-default.jsonl`. Measured on the owner's machine
+# 2026-07-27: one file, 147 lines deep, written concurrently by several live sessions — the same
+# many-writers-one-path shape as ADR-050, and it makes "this session's trajectory" a fiction, because
+# the queue is a blend of every session that happened to be open.
+#
+# `session_id` is a field on the very payload this hook already parsed. Prefer it; fall back to the
+# env var; then to 'default'. SANITISED before it becomes a filename component: the payload is
+# untrusted input, and `session_id` reaching an unfiltered path join is a traversal waiting to happen.
+SID=""
+re_s='"session_id"[[:space:]]*:[[:space:]]*"([^"\]*)"'
+[[ $INPUT =~ $re_s ]] && SID="${BASH_REMATCH[1]}"
+[ -n "$SID" ] || SID="${CLAUDE_SESSION_ID:-}"
+# Dots are dropped along with everything else outside this set: real session ids are uuids, and
+# keeping `.` would let a crafted id survive as `..`-shaped debris in a filename for no benefit.
+SID="${SID//[^A-Za-z0-9_-]/}"           # a filename COMPONENT, never a path
+[ -n "$SID" ] || SID="default"
+if [ "$SCOPE" = "user" ]; then
+  DIR="$HOME/.cache/ruvnet-brain/learn"
+else
+  DIR="$PWD/.swarm/ruvnet-brain-learn"
+fi
+# Owner-only (0700 dir / 0600 file). This queue was 0644 inside a 0755 dir: on macOS every local
+# account is normally in `staff`, so any other user on a shared or corporate machine could read it.
+( umask 077 && mkdir -p "$DIR" ) 2>/dev/null || exit 0
+QUEUE="$DIR/session-$SID.jsonl"
+[ -e "$QUEUE" ] || { : > "$QUEUE" 2>/dev/null && chmod 600 "$QUEUE" 2>/dev/null; } || true
+printf '{"tool":"%s","action":"%s"}\n' "$TOOL" "${ACTION//\"/\\\"}" >> "$QUEUE" 2>/dev/null || true
+
+# ── HEARTBEAT FLUSH (ADR-027) ────────────────────────────────────────────────────────────────────
+# The flush used to fire ONLY on a clean SessionEnd. Sessions compact, crash, get resumed, or are
+# killed — none of those reach SessionEnd — so the queue silently grew to 1,884 undelivered events
+# over days while the learner sat at 5 trajectories, last trained six days earlier. Draining it took
+# the learner to 412/412 in one command. A queue that only empties on a graceful exit will always
+# leak; activity itself must be the trigger.
+#
+# So: every HEARTBEAT_EVERY captures, drain in the BACKGROUND. Detached and fully silent — this runs
+# inside a PostToolUse hook and must never add latency to the user's turn or fail one. Cheap check
+# (a line count) on the common path; real work only at the threshold.
+# LEVEL-TRIGGERED, NOT EDGE-TRIGGERED. This is the whole fix, and the bug it replaces was severe.
+#
+# The condition used to be `LINES >= 200 && LINES % 200 == 0` — it fired ONLY when the count landed
+# exactly on a multiple of 200. Two captures arriving between checks, or any concurrent write,
+# steps the counter over the window and the flush NEVER fires again. Measured on the owner's machine
+# 2026-07-22: the queue was at 491. It had sailed past both 200 and 400 without draining once, and
+# would have grown forever.
+#
+# The failure mode is the nastiest kind: capture works, the learner works, and the PIPE BETWEEN THEM
+# is severed — while every surface honestly reports both ends as healthy. "Is learning on?" had no
+# true answer, because learning is not a switch; it is a chain, and one link was open.
+#
+# `-ge` cannot skip a window. It fires on every capture past the threshold until the queue is
+# actually drained, which is the definition of level-triggered: the condition is the QUEUE'S DEPTH,
+# not the instant it crossed a line.
+HEARTBEAT_EVERY=200
+LINES=$(wc -l < "$DIR/session-$SID.jsonl" 2>/dev/null || echo 0)
+if [ "$LINES" -ge "$HEARTBEAT_EVERY" ]; then
+  # Debounce so a deep queue doesn't spawn a flush on EVERY subsequent capture: at most one drain
+  # per minute. Without this, level-triggering trades a stuck queue for a fork storm.
+  STAMP="$DIR/.last-flush"
+  NOW=$(date +%s)
+  LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
+  if [ $((NOW - LAST)) -ge 60 ]; then
+    echo "$NOW" > "$STAMP" 2>/dev/null || true
+    FLUSH="$HERE/learn-flush.mjs"
+    [ -f "$FLUSH" ] && (RUVNET_LEARNING_SCOPE="$SCOPE" nohup node "$FLUSH" >/dev/null 2>&1 &) || true
+  fi
+fi
+exit 0

package/plugin/scripts/learn-flush.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// learn-flush.mjs — SessionEnd. Reads this session's learning queue (the workflow you just performed)
+// and feeds the distinct steps into the GLOBAL per-user SONA learner — ruflo hooks run with cwd=$HOME
+// so learnings accumulate in ONE store (~/.claude-flow), shared across ALL your projects. Project FACTS
+// never come here (the queue holds command verbs + file basenames, no content). Each installed RuvNet
+// Brain does this for its own user → everyone's brain gets recursively smarter about how THEY work. ADR-0017.
+//
+// Non-blocking, best-effort. Bounded (distinct actions, short timeouts). `--sync` waits (for tests);
+// the hook default backgrounds so SessionEnd never stalls.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { readStdinBounded } from './hook-input.mjs';
+import { loadRuntimePreferences } from './runtime-preferences.mjs';
+
+const HOME = os.homedir();
+const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
+const configuredScope = process.env.RUVNET_LEARNING_SCOPE
+  || loadRuntimePreferences({ cwd: PROJECT }).values.learningScope;
+const LEARNING_SCOPE = ['off', 'project', 'user'].includes(configuredScope)
+  ? configuredScope : 'project';
+if (LEARNING_SCOPE === 'off') process.exit(0);
+
+// THE SESSION ID COMES OFF THE PAYLOAD, exactly as it does in learn-capture.sh (fixed 2026-07-27).
+//
+// This used to be `process.env.CLAUDE_SESSION_ID || 'default'`. Claude Code does not set that
+// variable, so every session on the machine read and rewrote ONE shared session-default.jsonl —
+// measured live at 147 lines, appended by several concurrent sessions. Both halves of this pipeline
+// have to agree about which file they mean, so both now read `session_id` from the payload the hook
+// is already handed, sanitise it the same way, and fall back the same way.
+//
+// The read is bounded: SessionEnd hands us a small JSON object and closes, but an unbounded
+// readFileSync(0) on a stdin that never closes is a hang with no upper bound. A payload we cannot
+// read in time simply yields no id, which lands on the same fallback as no payload at all.
+async function payloadSessionId() {
+  if (process.stdin.isTTY) return '';
+  try {
+    const raw = (await readStdinBounded()).toString('utf8');
+    const v = JSON.parse(raw)?.session_id;
+    return typeof v === 'string' ? v : '';
+  } catch { return ''; }
+}
+// A filename COMPONENT, never a path — the payload is untrusted input.
+const SID = ((await payloadSessionId()) || process.env.CLAUDE_SESSION_ID || '').replace(/[^A-Za-z0-9_-]/g, '') || 'default';
+const QUEUE_ROOT = LEARNING_SCOPE === 'user'
+  ? path.join(HOME, '.cache', 'ruvnet-brain', 'learn')
+  : path.join(PROJECT, '.swarm', 'ruvnet-brain-learn');
+const QUEUE = process.env.LEARN_QUEUE || path.join(QUEUE_ROOT, `session-${SID}.jsonl`);
+const RUFLO = path.join(HOME, '.npm-global/bin/ruflo');
+const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
+const MAX_ACTIONS = 8; // bound the work so SessionEnd stays fast
+
+// THE DEADLINE. SessionEnd's registered timeout is 30s (plugin/hooks/hooks.json) and this hook fires
+// on EVERY session end — including every `/clear`. Measured on the owner's machine 2026-07-27, in all
+// four stdin regimes: 48–50s wall, killed at the cap every single time.
+//
+// The arithmetic was never survivable. MAX_ACTIONS is 8 and a real `ruflo hooks` call measured 3.83s,
+// so the feed queued ~31s of work into a 30s budget and was killed part-way through it. Worse, the
+// kill lands BEFORE the write-back that preserves the remainder, so the queue never shrinks and never
+// drains — a cap that guarantees the work it defers can never be done.
+//
+// A work limit has to be expressed in the currency the budget is denominated in. MAX_ACTIONS bounds
+// COUNT; this bounds TIME, and the two together mean the hook stops cleanly, keeps what it did not
+// feed, and exits well inside the cap. 20s leaves a full third of the budget for the write-back, the
+// process teardown, and a slow machine. Measured with a 4s-per-call stub and a 147-entry queue: 22.5s
+// wall at a 20s deadline (execFileSync's own kill handling costs a couple of seconds on top of the
+// budget), so the number is set at 18s to keep the real worst case around 20s — a third of the cap in
+// hand. The budget is the thing being bounded; the constant is chosen from the measurement, not from
+// how round it looks.
+const DEADLINE_MS = Number(process.env.LEARN_FLUSH_DEADLINE_MS) || 18_000;
+const DEADLINE = Date.now() + DEADLINE_MS;
+
+let lines = [];
+try { lines = fs.readFileSync(QUEUE, 'utf8').split('\n').filter(Boolean); } catch { process.exit(0); }
+if (!lines.length) process.exit(0);
+
+// Distinct workflow actions this session (dedupe → a session has only a handful of real patterns).
+//
+// COLLECT ALL, FEED SOME, KEEP THE REST (fixed 2026-07-22). This used to `break` at MAX_ACTIONS and
+// then delete the ENTIRE queue, so a session with 30 distinct actions fed 8 and destroyed 22 —
+// permanently, silently, while reporting success. Measured on the owner's machine the same day: the
+// queue stood at 491 raw captures, every one of which would have been discarded after feeding 8.
+//
+// The cap exists for a good reason (SessionEnd must stay fast) but a work LIMIT is not a licence to
+// destroy the work you didn't do. Now the remainder is written back and drains on the next flush,
+// so a deep queue converges instead of being truncated.
+const allDistinct = [];
+const seen = new Set();
+for (const line of lines) {
+  let s; try { s = JSON.parse(line); } catch { continue; }
+  const key = `${s.tool}|${(s.action || '').slice(0, 60)}`;
+  if (!s.action || seen.has(key)) continue;
+  seen.add(key);
+  allDistinct.push(s);
+}
+const actions = allDistinct.slice(0, MAX_ACTIONS);
+const deferred = allDistinct.slice(MAX_ACTIONS);
+
+let fed = 0;
+let stoppedAt = actions.length;   // how far the feed actually got before the deadline
+for (let i = 0; i < actions.length; i++) {
+  const remaining = DEADLINE - Date.now();
+  // STOP CLEANLY, and stop BEFORE starting work that cannot finish inside the budget. A call begun
+  // at 19.9s with a 6s timeout would run to 25.9s, which is the whole failure in miniature — the
+  // budget has to bound the call, not just the decision to make it.
+  if (remaining <= 0) { stoppedAt = i; break; }
+  const s = actions[i];
+  const args = s.tool === 'Bash'
+    ? ['hooks', 'post-command', '-c', s.action, '-s', 'true']
+    : ['hooks', 'post-edit', '-f', s.action, '-s', 'true', '-o', 'session edit'];
+  try {
+    // One command, two real Ruflo scopes: project cwd keeps patterns local; HOME retains the
+    // cross-project SONA learner for users who explicitly chose `user`.
+    execFileSync(RUFLO, args, {
+      cwd: LEARNING_SCOPE === 'user' ? HOME : PROJECT,
+      env: RUFLO_ENV,
+      stdio: 'ignore',
+      timeout: Math.min(6000, remaining),
+    });
+    fed++;
+  } catch { /* best-effort — one slow/failed record must not stall session end */ }
+}
+// Whatever the deadline cut off is WORK, not waste: it goes back on the front of the queue so the
+// next flush continues from there. Dropping it would turn a time limit into the same silent data
+// loss the count limit used to cause.
+if (stoppedAt < actions.length) deferred.unshift(...actions.slice(stoppedAt));
+
+// DERIVED, not asserted (F14, 2026-07-18): the queue is EVIDENCE, and it may only be destroyed when
+// its contents were actually fed. The old line deleted it unconditionally — a session where every
+// `ruflo hooks` call failed (fed=0) silently discarded the whole learning queue with nothing learned
+// and no trace. Now: nothing fed + something to feed ⇒ the queue survives for the next session-end
+// to retry. An empty queue (nothing to feed) is safe to remove.
+if (fed > 0 || allDistinct.length === 0) {
+  if (deferred.length) {
+    // Work remains. Write back ONLY what was not fed, so the next flush continues where this one
+    // stopped. Deleting here is what turned a rate limit into data loss.
+    try {
+      fs.writeFileSync(QUEUE, deferred.map((s) => JSON.stringify(s)).join('\n') + '\n');
+    } catch { /* if we cannot rewrite it, leaving the full queue is strictly safer than removing it */ }
+  } else {
+    try { fs.rmSync(QUEUE); } catch { /* leave it if we can't remove */ }
+  }
+} else if (process.argv.includes('--sync')) {
+  console.log(`learn-flush: 0/${actions.length} fed (ruflo hooks failing?) — queue KEPT for retry next session-end`);
+}
+if (process.argv.includes('--sync')) {
+  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the ${LEARNING_SCOPE} learner`
+    // Say the deadline out loud when it fires. A budget that silently truncates reads as "that was
+    // all there was", which is the same lie as the count cap that preceded it.
+    + (stoppedAt < actions.length ? `; STOPPED at ${stoppedAt}/${actions.length} on the ${DEADLINE_MS}ms deadline` : '')
+    + (deferred.length ? `; ${deferred.length} distinct action(s) deferred to the next flush (queue kept, nothing discarded)` : ''));
+}
+process.exit(0);

package/plugin/scripts/lesson-hooks.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# lesson-hooks.sh — THE LAST MILE. Connects lessons to the events that actually fire.
+#
+# WHY THIS EXISTS, measured 2026-07-22 05:50:
+#
+#     trigger              enforcing?  wired to a hook that runs?
+#     ship                 yes         YES  ← the only real one
+#     assert-fact          yes         no
+#     report-status        yes         no   ← this is why the model still stopped
+#     write-code           yes         no
+#     claim-done           yes         no
+#     mutate-machine       yes         no
+#
+# Five lessons the owner had personally ratified reported "enforcing" and NOTHING CALLED THEM. The
+# store said armed; the machine said unconnected.
+#
+# ONE dispatcher, not five hooks. ADR-030's constraint holds: gates scale with decision TYPES, never
+# with lesson count. This file maps Claude Code's real events onto the store's triggers and asks the
+# store what applies. Adding a lesson requires no change here — that asymmetry is the architecture.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# WHAT CHANGED, 2026-07-22: THIS FILE WAS THE THIRD LAYER OF A BLOCK THAT COULD NOT BLOCK.
+#
+# The old body ran the gate as `... 2>/dev/null || true`, echoed whatever came back, and then
+# `exit 0` unconditionally — with this comment above it, which was true as a promise and fatal as a
+# design: "FAILS OPEN, ALWAYS. Exit 0 unconditionally on every path."
+#
+# Measured, before the fix:
+#     $ bash plugin/scripts/lesson-hooks.sh Stop ; echo $?
+#       ⛔ BLOCKED — you are about to report progress or state.
+#       0                    ← printed BLOCKED, returned ALLOW
+#
+# Three bugs stacked so neatly that each one alone would have been enough: the gate exited 1 (not the
+# harness's blocking code 2), wrote its reason to stdout (which exit-2 ignores), and this file threw
+# the code away regardless. `|| true` is what turned "the gate is broken" into "the gate is silent",
+# which is why it survived long enough to be documented as working.
+#
+# FAIL-OPEN IS STILL THE RULE — it was just implemented as "always allow", which is not the same
+# thing. Failing open means an ERROR must not refuse the user: a missing node, an unreadable store, a
+# timeout. It never meant discarding a DELIBERATE refusal. Those are now distinguished by exit code:
+# 2 is a decision and propagates; every other non-zero is a malfunction and allows.
+#
+# AND THE DEFAULT IS NOW A NUDGE, not a block (the owner, same day: "Nudging somebody is very fair.
+# Forcing them through a gate is not."). The gate emits `additionalContext` on exit 0 for nudges —
+# the model reads it, nothing is refused. Exit 2 happens only for a lesson the user has personally
+# opted into blocking, in a file only they write.
+
+EVENT="${1:-}"
+[ -z "$EVENT" ] && exit 0
+
+# Resolve the gate relative to this script so it works from the repo, the marketplace clone, or an
+# installed bundle without a hardcoded path (a hardcoded ~/.npm-global path told users ruflo was
+# missing when it sat on their PATH — same class of bug).
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+GATE=""
+for c in "$HERE/../../scripts/lesson-gate.mjs" "$HERE/../scripts/lesson-gate.mjs" "$HOME/.claude/plugins/marketplaces/ruvnet-brain/scripts/lesson-gate.mjs"; do
+  [ -f "$c" ] && GATE="$c" && break
+done
+[ -z "$GATE" ] && exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+# Read the hook's JSON payload off stdin ONCE, via the same shared Node parser the other PreToolUse
+# gates on Bash already use for this — never a hand-rolled bash regex, which is how a JSON-escaped
+# quote once silently truncated a command in this exact codebase. Safe for every event this script
+# handles: the harness always pipes a payload, and a caller with no stdin (a manual test) gets EOF
+# immediately, not a hang — an empty result just means no command text was found.
+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"$'\n'
+  [ ${#INPUT} -ge 65536 ] && break
+done
+[ -n "$_l" ] && INPUT+="$_l"$'\n'
+INPUT="${INPUT:0:65536}"
+HOOK_INPUT_JS="$HERE/hook-input.mjs"
+
+# Map a real Claude Code event onto the store's decision points, and onto the event name the harness
+# will accept back. An event may carry more than one decision point: ending a turn is simultaneously
+# "reporting status" and "claiming done", and both have lessons.
+#
+# CLAUDE_EVENT is what goes into hookSpecificOutput.hookEventName, and it MUST be the harness's real
+# event name — "PreToolUse", never our internal "PreToolUse-write" — or the envelope is discarded and
+# the nudge silently reaches nobody. That is this project's signature failure; it is not repeating here.
+TRIGGERS=""
+CLAUDE_EVENT=""
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# WHY `Stop` IS NO LONGER HERE (2026-07-22, and this is the fix for a live, machine-wide defect).
+#
+# `additionalContext` at Stop does not merely inform — it CONTINUES THE TURN, and counts against the
+# 8-consecutive-continuation cap. The doc is explicit: "It keeps the conversation going through the
+# same loop protections as decision: 'block'... Claude Code overrides the hook and ends the turn
+# after 8 consecutive blocks."
+#
+# This dispatcher fired on Stop with triggers `report-status claim-done`, which match lessons that
+# match ALWAYS. So EVERY turn-end was continued, in every project, until the harness killed it on the
+# ninth. Observed live on 2026-07-22 in three separate projects; the harness's own error text named
+# the missing guard.
+#
+# The deeper error was not the missing guard, it was the DESIGN: this gate fires on the ACT of
+# stopping with no state check, so it cannot tell "stopped early" from "genuinely finished". A guard
+# that fires unconditionally carries no information, and paying a forced model turn to deliver a
+# reminder is the ham-fisted behaviour that gets a tool switched off.
+#
+# So Stop is now owned by ONE hook — continuation-gate.mjs — which reads a real work ledger, speaks
+# only when committed work is actually outstanding, honours stop_hook_active, and nudges at most once
+# per session. The `report-status` and `claim-done` lessons moved to UserPromptSubmit, where they
+# reach the model BEFORE the work rather than after it, and cost nothing to deliver.
+TRIGGERS=""
+CLAUDE_EVENT=""
+case "$EVENT" in
+  Stop)             exit 0 ;;   # deliberately inert — see above. continuation-gate.mjs owns Stop.
+  PreToolUse-write) TRIGGERS="write-code";                      CLAUDE_EVENT="PreToolUse" ;;
+  PreToolUse-bash)  TRIGGERS="mutate-machine";                  CLAUDE_EVENT="PreToolUse" ;;
+  PreToolUse-push)  TRIGGERS="ship";                            CLAUDE_EVENT="PreToolUse" ;;
+  # `choose-work` ADDED 2026-07-24 — the omission that made the Learning pillar look broken.
+  #
+  # THE FAILURE, in the owner's words: "why aren't you spinning up parallel swarms... isn't that a
+  # definition of a huge failure of the learning?" He was right, and the cause was one missing word on
+  # this line. L16-parallel-by-default ("when given multiple independent pieces of work, FAN OUT
+  # IMMEDIATELY... serial execution of independent work is a defect, not a style") is RATIFIED, taught
+  # FOUR times — and had never been delivered once, in any session, because nothing ever requested its
+  # trigger. The lesson was not ignored; it was never spoken.
+  #
+  # WHY IT WAS MISSED, and the trap worth naming: `choose-work`'s surface is `plan`, and lesson-store
+  # correctly refuses to let a `plan` lesson claim `block` enforcement — no hook can observe the
+  # instant a model forms an intention. That true statement was silently over-read as "plan lessons
+  # cannot be delivered at all," so the trigger was left off every event. But UserPromptSubmit IS the
+  # work-choice moment: a request arrives and the very next act is deciding how to attack it. The
+  # lesson cannot BLOCK there — it stays advisory, exactly as its enforcement says — but advisory
+  # delivered beats enforcing never. "Cannot be a gate" and "cannot be heard" are different claims,
+  # and conflating them cost four repetitions of the same correction.
+  #
+  # This is the same defect the header table already recorded for `report-status` ("enforcing? yes /
+  # wired to a hook that runs? no ← this is why the model still stopped"). Fixed there, missed here.
+  # One bug, found once, fixed once, left everywhere else.
+  # `relay-number` ADDED 2026-07-24 — the SECOND inert lesson found the same day, and this one is
+  # about the failure it was itself unable to prevent.
+  #
+  # L04-never-relay-a-number ("never repeat a score, benchmark, or subagent result without re-checking
+  # the underlying artifact yourself") is RATIFIED and taught 5 times, and no event has ever requested
+  # its trigger — so it had never fired, in any session, ever. Found by the new lesson-trigger audit in
+  # wired-check.mjs, which exists because L16 had exactly this defect hours earlier. The audit's first
+  # real run immediately found a second instance: evidence the class was systemic, not a one-off.
+  #
+  # The irony is the useful part, not the joke: on the day this was found, three subagents reported
+  # results and TWO of them contained a confident claim the artifact contradicted (a "1,266 = 14"
+  # equality that a single query disproves, and an upgrade-notice fix reported missing because the grep
+  # demanded `function` on a `const` arrow). The lesson that would have flagged both was in force,
+  # weighted, and mute.
+  #
+  # UserPromptSubmit is the right event: relaying happens while composing a reply, and this is the last
+  # observable moment before that. It cannot BLOCK there (surface `text`), which matches its
+  # `checklist` enforcement exactly — advisory delivered beats enforcing never.
+  UserPromptSubmit) TRIGGERS="assert-fact recommend-architecture report-status claim-done choose-work relay-number"; CLAUDE_EVENT="UserPromptSubmit" ;;
+  *) exit 0 ;;
+esac
+
+# ONE invocation carrying every trigger for this event — not one per trigger. Two reasons, both hard:
+# a nudge must be a SINGLE JSON document (two concatenated objects on stdout parse as neither), and
+# this runs on every matching event, so one node spawn instead of two is latency the user feels.
+ARGS=()
+for t in $TRIGGERS; do ARGS+=(--trigger "$t"); done
+
+# Session identity for the gate's per-session frequency cap (scripts/lesson-gate.mjs) — extracted from
+# the same payload via the shared parser, never a hand-rolled regex. A missing/empty id just means the
+# gate falls back to a cwd+day key, so the cap stays bounded either way; it is never a hard requirement.
+if [ -f "$HOOK_INPUT_JS" ]; then
+  SID=$(printf '%s' "$INPUT" | node "$HOOK_INPUT_JS" field session_id 2>/dev/null) || SID=""
+  [ -n "$SID" ] && ARGS+=(--session "$SID")
+fi
+
+# THE FIX for the mutate-machine false-positive nag: `mutate-machine` fired on EVERY Bash call — `ls`,
+# `grep`, `git status` included — because this dispatcher requested the trigger unconditionally, with
+# no inspection of the command at all (there was nothing here to inspect it WITH). The gate now takes
+# `--command <text>` and narrows `mutate-machine` to commands that plausibly mutate something OUTSIDE
+# this repo (scripts/lesson-gate.mjs, looksLikeOutsideRepoMutation) — so extract the real command text
+# for exactly the one event that carries it, and hand it to the gate to decide.
+if [ "$EVENT" = "PreToolUse-bash" ] && [ -f "$HOOK_INPUT_JS" ]; then
+  CMD=$(printf '%s' "$INPUT" | node "$HOOK_INPUT_JS" command 2>/dev/null) || CMD=""
+  ARGS+=(--command "$CMD")
+fi
+
+# A hard timeout, because this runs on every matching event and must never add perceptible latency.
+# BUT `timeout` is GNU coreutils and STOCK macOS DOES NOT SHIP IT — on this dev machine it exists
+# only because Homebrew put it there, which is exactly how a bug like this hides. Unguarded,
+# `timeout 5 node ...` on a clean Mac exits 127 (command not found), so the gate would never run at
+# all: no nudge, no block, and — worst of all — silence indistinguishable from "no lessons applied".
+# So the timeout is used when present and skipped when not. A missing convenience must degrade the
+# latency guarantee, never the gate. (Same lesson as the CI runner that went red because a test
+# assumed macOS-only paths.)
+TIMEOUT=""
+command -v timeout  >/dev/null 2>&1 && TIMEOUT="timeout 5"
+[ -z "$TIMEOUT" ] && command -v gtimeout >/dev/null 2>&1 && TIMEOUT="gtimeout 5"
+
+# Streams pass straight through, UNREDIRECTED and UNCAPTURED. This is deliberate and it is the fix:
+#   • stdout carries the nudge JSON — capturing it into a shell variable and re-echoing it risks
+#     mangling (trailing-newline stripping, glob expansion) the harness's parse depends on.
+#   • stderr carries a block's reason and must arrive as stderr, because exit 2 ignores stdout.
+# The old `2>/dev/null` discarded precisely the stream a refusal needs.
+$TIMEOUT node "$GATE" --event "$CLAUDE_EVENT" "${ARGS[@]}"
+CODE=$?
+
+# THE PROPAGATION. Exit 2 is the gate's considered decision that the user asked to be refused here —
+# it is the only code that means anything to the harness, and it is passed through untouched.
+# Everything else — 0, a crash, a 124 from timeout, node dying — allows the action. An error must
+# never masquerade as a refusal, and a refusal must never be downgraded to an error.
+[ "$CODE" -eq 2 ] && exit 2
+exit 0