ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/issue-watch.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// scripts/issue-watch.mjs — GitHub-issues SLA watcher.
+//
+// Stuart's mandate: no open issue on stuinfla/ruvnet-brain may sit >4h without a response, or an
+// ntfy alert must reach his phone. "Response" = a comment from the repo owner (stuinfla) — a
+// contributor's comment (see issue #12, commented by @sparkling) does NOT satisfy the SLA.
+//
+// 2026-07-24 incident, two rules born from it:
+//   1. A BOT comment is not an owner response. issue-fix.mjs posts through the owner's gh auth, so
+//      its comments arrive as stuinfla — and four issues (#38/#39/#41/#42) sat 28h with ZERO pages
+//      because those bot comments satisfied the owner-comment check below. The fixer manufactured
+//      the exact signal that silences the watcher. Marked comments (BOT_MARKER) never count.
+//   2. The breach alert is the ESCALATION channel, not the AWARENESS channel. Waiting 4h to say
+//      anything is how the maintainer learned about four issues from a GitHub email instead of a
+//      page. The watcher now pages ONCE, immediately, the first time it sees any open issue.
+//
+// Follows the house positive-confirmation pattern established 2026-07-13 (scripts/job-heartbeat.sh,
+// scripts/nightly-watchdog.mjs, config/scheduled-jobs.json): this script is meant to run WRAPPED by
+// job-heartbeat.sh from a launchd plist, so a crash still leaves a receipt and a failed run still
+// pages the phone via the wrapper's own "SCHEDULED JOB FAILED" alert. This script's own exit code is
+// therefore reserved for real execution failures (gh unreachable, bad JSON) — finding an SLA breach
+// is the job working correctly, not a failure, so it always exits 0 on a clean run.
+//
+// Dedup: alerts for a given issue repeat at most once per SLA window (4h), tracked in a small state
+// file, so a still-breaching issue doesn't re-page every hourly run.
+//
+// Usage:
+//   node scripts/issue-watch.mjs             # check + alert on breaches
+//   node scripts/issue-watch.mjs --dry-run   # check + print what WOULD be sent; no ntfy push, no state write
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REPO = 'stuinfla/ruvnet-brain';
+export const OWNER_LOGIN = 'stuinfla';
+// Every comment the automation posts through the owner's gh auth begins with this prefix — the
+// watcher's acknowledgment ("🤖 Automated acknowledgment …") and the fixer child's notes
+// ("🤖 Automated issue-fix run …") both start with it. Spoof-safety: only comments AUTHORED BY
+// the owner are checked against it, so a stranger opening their comment with the marker changes
+// nothing — and the owner starting a personal reply with a robot emoji is not a realistic
+// collision. (Generalized from the fixer-specific wording 2026-07-24 when the acknowledgment
+// moved here.)
+export const BOT_MARKER = '🤖 Automated';
+const SLA_HOURS = 4;
+const STATE_PATH = process.env.ISSUE_WATCH_STATE
+  || path.join(os.homedir(), '.claude', 'ruvnet-brain', 'issue-watch-state.json');
+// A compact, always-current snapshot the SessionStart hook surfaces (2026-07-17). ntfy alerts are
+// easy to miss — issues stacked unseen for 29h precisely because the only channel was the phone.
+// The session banner is a channel the maintainer cannot miss; this file is how it learns the count.
+const STATUS_PATH = path.join(os.homedir(), '.cache', 'ruvnet-brain', 'open-issues.json');
+const GH_BIN = process.env.GH_BIN || 'gh';
+
+function ghJson(args) {
+  // Retry ONCE on a transient network-shaped failure (2026-07-19, same class as issue-fix's 1am
+  // "TLS handshake timeout" page): 20s of patience absorbs a blip; a second failure still fails
+  // LOUD. Bounded, logged, never silent.
+  let lastErr;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const res = spawnSync(GH_BIN, args, { encoding: 'utf8' });
+    if (res.status === 0) return JSON.parse(res.stdout);
+    const err = (res.stderr || res.stdout || '').trim();
+    lastErr = new Error(`gh ${args.join(' ')} failed (exit ${res.status}): ${err}`);
+    const transient = /TLS handshake|unexpected EOF|timeout|ECONNRESET|ETIMEDOUT|EAI_AGAIN|connection refused|temporarily unavailable/i.test(err);
+    if (attempt === 1 && transient) {
+      console.error(`issue-watch: transient gh/network failure (${err.slice(0, 90)}) — retrying once in 20s`);
+      spawnSync('sleep', ['20']);
+      continue;
+    }
+    break;
+  }
+  throw lastErr;
+}
+
+/** Resolve the ntfy topic the same way the rest of the repo does: env, then the machine-wide
+ * cache file, then the repo .env — see scripts/notify.sh / scripts/job-heartbeat.sh / scripts/nightly-watchdog.mjs. */
+function resolveTopic() {
+  if (process.env.NTFY_TOPIC) return process.env.NTFY_TOPIC;
+  try {
+    const t = fs.readFileSync(path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ntfy-topic'), 'utf8').trim();
+    if (t) return t;
+  } catch { /* fall through */ }
+  try {
+    const env = fs.readFileSync(path.join(ROOT, '.env'), 'utf8');
+    const m = env.match(/^NTFY_TOPIC=(.*)$/m);
+    if (m) return m[1].trim();
+  } catch { /* fall through */ }
+  return null;
+}
+
+async function pushNtfy(topic, { title, body, priority = 'urgent', tags = 'rotating_light' }) {
+  try {
+    const res = await fetch(`https://ntfy.sh/${topic}`, {
+      method: 'POST',
+      headers: { Title: title, Priority: priority, Tags: tags },
+      body,
+    });
+    return res.ok;
+  } catch {
+    return false; // alerting must never break the job — fail-silent, matching scripts/notify.sh
+  }
+}
+
+function loadState() {
+  try { return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')); } catch { return {}; }
+}
+
+function saveState(state) {
+  fs.mkdirSync(path.dirname(STATE_PATH), { recursive: true });
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+
+function fmtAge(hours) {
+  const h = Math.floor(hours);
+  const m = Math.round((hours - h) * 60);
+  return `${h}h ${m}m`;
+}
+
+/** Judge one issue. Comments are re-fetched per-issue via `gh issue view` (not trusted from the
+ * list call) so owner-comment presence is computed off the authoritative per-issue payload. */
+export function judgeIssue(issue, comments, now) {
+  const ageHours = (now - new Date(issue.createdAt).getTime()) / 3_600_000;
+  // An owner response is a HUMAN response: bot-marked comments never satisfy the SLA (see header,
+  // 2026-07-24 — the fixer's failure notes muted every page for four real issues).
+  const ownerComment = comments.find((c) => c.author?.login === OWNER_LOGIN
+    && !String(c.body || '').trimStart().startsWith(BOT_MARKER));
+  const breach = ageHours > SLA_HOURS && !ownerComment;
+  return { ageHours, ownerComment: !!ownerComment, breach };
+}
+
+export async function run({ dryRun = false, now = Date.now(), repo = REPO } = {}) {
+  const issues = ghJson(['issue', 'list', '--repo', repo, '--state', 'open', '--json',
+    'number,title,createdAt,comments,updatedAt']);
+
+  const state = loadState();
+  const results = [];
+  const alertsSent = [];
+
+  for (const issue of issues) {
+    const detail = ghJson(['issue', 'view', String(issue.number), '--repo', repo, '--json', 'comments']);
+    const { ageHours, ownerComment, breach } = judgeIssue(issue, detail.comments || [], now);
+    const url = `https://github.com/${repo}/issues/${issue.number}`;
+    const key = String(issue.number);
+    const last = state[key]?.lastAlertAt ? Date.parse(state[key].lastAlertAt) : null;
+    const dueForAlert = breach && (!last || (now - last) / 3_600_000 >= SLA_HOURS);
+    // First sighting → page once, immediately (rule 2 in the header). Delivery-derived like
+    // lastAlertAt: state is only written when the push actually went out, so a failed push
+    // retries next run instead of burying the sighting.
+    const firstSighting = !state[key];
+
+    results.push({ number: issue.number, title: issue.title, ageHours, ownerComment, breach, dueForAlert, firstSighting, url });
+
+    if (firstSighting) {
+      if (dryRun) {
+        alertsSent.push({ number: issue.number, sent: false, kind: 'new-issue', reason: 'dry-run' });
+      } else {
+        const topic = resolveTopic();
+        let sent = false;
+        if (topic) sent = await pushNtfy(topic, {
+          title: `New issue #${issue.number} (open ${fmtAge(ageHours)})`,
+          body: `${issue.title}\n${url}`,
+          priority: 'high', tags: 'new,eyes',
+        });
+        // THE ONE PUBLIC ACKNOWLEDGMENT (owner directive, 2026-07-24): tell the reporter we have
+        // it and it's being worked — once, warmly, with zero excuses and zero deadlines. After
+        // this, the thread's next post is a real fix, real findings, or the maintainer in person;
+        // failure-progress notes never appear anywhere ("we gave it 15 minutes and quit" reads as
+        // not caring — the opposite of the point). Carries BOT_MARKER so judgeIssue() can never
+        // mistake it for the owner responding. Best-effort like ntfy: a comment failure must not
+        // break the watch; unacked issues simply retry next run (ackAt is delivery-derived).
+        let ackAt = null;
+        const ackBody = `🤖 Automated acknowledgment — received and opened. The maintainer has been paged and this is being worked. The next update here will be a fix, findings, or the maintainer in person.`;
+        const ack = spawnSync(GH_BIN, ['issue', 'comment', String(issue.number), '--repo', repo, '--body', ackBody], { encoding: 'utf8' });
+        if (ack.status === 0) ackAt = new Date(now).toISOString();
+        if (sent || ackAt) state[key] = { firstSeenAt: new Date(now).toISOString(), ...(sent ? { newAlertAt: new Date(now).toISOString() } : {}), ...(ackAt ? { ackAt } : {}), title: issue.title, url };
+        alertsSent.push({ number: issue.number, sent, acked: Boolean(ackAt), kind: 'new-issue', reason: topic ? null : 'no ntfy topic configured' });
+      }
+    }
+
+    if (dueForAlert) {
+      const title = `SLA breach: issue #${issue.number}`;
+      const body = `${issue.title}\nopen ${fmtAge(ageHours)}, no response from ${OWNER_LOGIN}\n${url}`;
+      if (dryRun) {
+        alertsSent.push({ number: issue.number, sent: false, reason: 'dry-run' });
+      } else {
+        const topic = resolveTopic();
+        let sent = false;
+        if (topic) sent = await pushNtfy(topic, { title, body, priority: 'urgent', tags: 'rotating_light,warning' });
+        // DERIVED, not asserted (F5, 2026-07-18): lastAlertAt may only be written when the page was
+        // actually DELIVERED (sent===true). The old line stamped it unconditionally, so a breach whose
+        // push failed (ntfy down, no topic) was suppressed for the whole 4h cooldown — the alert ledger
+        // asserted a delivery it never verified. A failed attempt records itself as failed and the next
+        // hourly run retries; the ledger can no longer claim a page that didn't happen.
+        // Spread-merge, never overwrite: the record may already carry firstSeenAt/newAlertAt from
+        // the first-sighting page above — clobbering them would re-page "new" forever (the exact
+        // state-erasure class that broke issue-fix's comment dedup, 2026-07-24).
+        if (sent) state[key] = { ...(state[key] || {}), lastAlertAt: new Date(now).toISOString(), title: issue.title, url };
+        else state[key] = { ...(state[key] || {}), lastAttemptAt: new Date(now).toISOString(), sent: false, title: issue.title, url };
+        alertsSent.push({ number: issue.number, sent, kind: 'sla-breach', reason: topic ? null : 'no ntfy topic configured' });
+      }
+    }
+  }
+
+  if (!dryRun) saveState(state);
+
+  return { results, alertsSent, checkedAt: new Date(now).toISOString() };
+}
+
+async function main() {
+  const dryRun = process.argv.includes('--dry-run');
+  const asJson = process.argv.includes('--json');
+
+  let output;
+  try {
+    output = await run({ dryRun });
+  } catch (err) {
+    console.error(`issue-watch: FAILED — ${err.message}`);
+    process.exit(1);
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(`GitHub issue SLA watch — ${REPO} (SLA: ${SLA_HOURS}h to first owner (@${OWNER_LOGIN}) response)${dryRun ? '  [DRY-RUN]' : ''}\n`);
+    for (const r of output.results) {
+      const icon = r.breach ? '\u{1F534}' : '✅';
+      console.log(`${icon} #${r.number}  ${r.title}`);
+      console.log(`   age: ${fmtAge(r.ageHours)} · owner comment: ${r.ownerComment ? 'yes' : 'no'} · breach: ${r.breach ? 'YES' : 'no'}`);
+      if (r.firstSighting) {
+        const na = output.alertsSent.find((a) => a.number === r.number && a.kind === 'new-issue');
+        console.log(`   🆕 first sighting — ${dryRun ? '[DRY-RUN] would push new-issue page' : na?.sent ? 'new-issue page pushed' : `new-issue page NOT sent (${na?.reason})`}`);
+      }
+      if (r.dueForAlert) {
+        const alert = output.alertsSent.find((a) => a.number === r.number && a.kind === 'sla-breach');
+        console.log(`   ${dryRun ? '[DRY-RUN] would push ntfy alert' : alert?.sent ? 'ntfy alert pushed' : `ntfy alert NOT sent (${alert?.reason})`}`);
+      } else if (r.breach) {
+        console.log(`   already alerted within the last ${SLA_HOURS}h — not repeating`);
+      }
+      console.log('');
+    }
+    const breaches = output.results.filter((r) => r.breach).length;
+    console.log(breaches
+      ? `${breaches} of ${output.results.length} open issue(s) are in SLA breach.`
+      : `All ${output.results.length} open issue(s) are within the ${SLA_HOURS}h SLA.`);
+    if (dryRun) console.log('(dry-run: no ntfy pushed, no state file written)');
+  }
+
+  // Write the snapshot the SessionStart hook reads. Best-effort — a status-file failure must never
+  // fail the watcher (whose real job, alerting, already succeeded above).
+  if (!dryRun) {
+    try {
+      const issues = output.results.map((r) => ({
+        number: r.number, title: r.title, ageHours: Math.round(r.ageHours),
+        breach: !!r.breach, url: `https://github.com/${REPO}/issues/${r.number}`,
+      }));
+      fs.mkdirSync(path.dirname(STATUS_PATH), { recursive: true });
+      fs.writeFileSync(STATUS_PATH, JSON.stringify({
+        at: new Date().toISOString(), repo: REPO,
+        open: issues.length, breaches: issues.filter((i) => i.breach).length, issues,
+      }, null, 2));
+    } catch { /* status file is best-effort; never break the watcher */ }
+  }
+
+  // Finding a breach is the watcher doing its job — exit 0. But a due alert that FAILED TO DELIVER
+  // is an execution failure (Sol amendment to F5, 2026-07-18): this watcher's one real job is the
+  // page, and if the page didn't go out, "ok" would be asserted, not derived. Exit 1 so the
+  // heartbeat records the failure and the wrapper's own channel escalates — that duplicate-looking
+  // page IS the correct behavior when the primary page provably never left the building.
+  const undeliveredAlert = !dryRun && (output.alertsSent || []).some((a) => !a.sent && a.reason !== 'dry-run');
+  process.exit(undeliveredAlert ? 1 : 0);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();

package/scripts/issue4-close-note.md

@@ -0,0 +1,31 @@
+## Fixed — and thank you
+
+Updated: 2026-07-10
+
+First: thank you for this report. It was precise, fully evidenced, and correct on every point — you quoted the exact claims, traced the exact files, and demonstrated the exact staleness on a clean install. Reports of this quality are rare and genuinely valuable; this one drove a same-day overhaul of the whole freshness pipeline. (Your PR #5 is under real review as well — separately, so it gets the attention it deserves.)
+
+### What you reported, and what we changed
+
+**1. "The nightly LaunchAgent is author-only, and even the upstream publish isn't nightly."**
+Confirmed, with a root cause you couldn't have seen from outside: the author-side 3:15 AM job had been dying **every night** on `spawnSync gh ENOENT` — launchd's default `PATH` omits `/opt/homebrew/bin`, so the publish step never ran and `releases/latest` sat frozen while `main` advanced.
+*Fixed in `2622c25`*: the LaunchAgent now exports its `PATH` explicitly; verified under the exact launchd environment before reload. **Proof this worked: `releases/latest` is now `__TAG__`, published `__PUB__` — by that nightly job, unattended.**
+
+**2. "No end-user mechanism enables a per-user nightly."**
+Correct — and the fix was closer than we realized: every bundle already ships a non-publishing updater (`forge-update.mjs --apply`: fetch canonical bundle → back up → extract → re-verify; loud failures, no partial clobber). What was missing was scheduling and honest wording. *Shipped in `158e888`*:
+- `npx ruvnet-brain --update` — one-shot check + update of **your** install
+- `npx ruvnet-brain --enable-nightly` — per-user LaunchAgent at 03:47, templated to **your** KB path, logging to `<kb>/update.log`; `--disable-nightly` reverts cleanly
+- Linux/Windows: the cron pattern documented inside `forge-update.mjs` itself
+- Off by default — nothing is ever scheduled on your machine unasked, and the installer now says exactly that instead of the old "auto-updating nightly? Just tell Claude" line, which promised something that never got scheduled. The README carries the same honest wording.
+
+**3. "The deck's 'never goes stale / CURRENT · last rebuild · last night' doesn't match reality."**
+You were right, and the deck itself was the problem — a stale deploy that should not have remained live. It hasn't been softened; it's been **retired**: `deck-six-liart.vercel.app` now permanently redirects (308) to the canonical explainer at https://isovision.ai/ruvnet-brain/, whose claims are the ones we deploy-verify.
+
+### On your machine
+```
+npx ruvnet-brain --update            # pulls the fresh bundle now
+npx ruvnet-brain --enable-nightly    # optional: 03:47 nightly, non-publishing, easy to disable
+```
+
+If your install still lags after `--update`, please reopen — that would be a new bug and we want it.
+
+Thanks again. The grounding idea only works if the ground is current; you made that true for everyone downstream.

package/scripts/key-canary.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// key-canary.mjs — live-probe every provider API key the environment delivers, and GONG on death.
+//
+// Built 2026-07-12, the day two dead keys were found by accident months after they died
+// (ANTHROPIC_API_KEY and the machine-wide OPENAI_API_KEY, both 401). Stuart's mandate: staleness
+// must be a monitoring problem, not a memory problem — "I'm just trying to find a way to not keep
+// dealing with stale keys project to project."
+//
+// WHAT IT DOES: for each known provider key PRESENT in the environment, makes the cheapest
+// possible authenticated call (list-models class — $0, no tokens billed) and classifies:
+//   alive   — HTTP 2xx
+//   DEAD    — HTTP 401/403 (the key itself is rejected)
+//   unknown — network error / timeout / 5xx (NOT a key problem; never alarms)
+// Absent keys are reported as absent (informational — many machines won't have every provider).
+//
+// GONG DISCIPLINE (same transition model as kb/brain-alarm.mjs): --notify sends ONE urgent push
+// when a key TRANSITIONS to dead, and one recovery push when it comes back — not a re-alarm every
+// night for a key you already know about (state: ~/.claude/metaharness/key-canary-state.json).
+// Exit code: 1 if any key is DEAD (so wrappers/CI can react), else 0.
+//
+// RUN IT THROUGH THE REAL DELIVERY CHAIN: `zsh -lc 'node scripts/key-canary.mjs'` — a login shell
+// sources ~/.zshrc -> env.global + the openclaw SOPS secrets, so the canary tests the exact env
+// every real shell and script inherits, not a hand-fed copy. Never prints a key value.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const STATE = path.join(os.homedir(), '.claude', 'metaharness', 'key-canary-state.json');
+const NOTIFY = process.argv.includes('--notify');
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const PROBES = [
+  { env: 'ANTHROPIC_API_KEY', provider: 'Anthropic', url: 'https://api.anthropic.com/v1/models', headers: (k) => ({ 'x-api-key': k, 'anthropic-version': '2023-06-01' }) },
+  { env: 'OPENAI_API_KEY', provider: 'OpenAI', url: 'https://api.openai.com/v1/models', headers: (k) => ({ Authorization: `Bearer ${k}` }) },
+  { env: 'OPENROUTER_API_KEY', provider: 'OpenRouter', url: 'https://openrouter.ai/api/v1/key', headers: (k) => ({ Authorization: `Bearer ${k}` }) },
+  { env: 'GOOGLE_API_KEY', provider: 'Google/Gemini', url: null, headers: null }, // key goes in query string, built below
+  { env: 'GEMINI_API_KEY', provider: 'Google/Gemini (GEMINI_API_KEY)', url: null, headers: null },
+  { env: 'XAI_API_KEY', provider: 'xAI', url: 'https://api.x.ai/v1/models', headers: (k) => ({ Authorization: `Bearer ${k}` }) },
+];
+
+async function probe(p, key) {
+  const url = p.url || `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(key)}`;
+  try {
+    const res = await fetch(url, { headers: p.headers ? p.headers(key) : {}, signal: AbortSignal.timeout(12000) });
+    if (res.ok) return 'alive';
+    if (res.status === 401 || res.status === 403) return 'DEAD';
+    return `unknown(HTTP ${res.status})`;
+  } catch (e) {
+    return `unknown(${e.name === 'TimeoutError' ? 'timeout' : 'network'})`;
+  }
+}
+
+function notify(title, message, priority, tags) {
+  try {
+    execFileSync('sh', [path.join(REPO, 'scripts', 'notify.sh'), title, message, priority, tags], { cwd: REPO, stdio: 'ignore', timeout: 15000 });
+  } catch { /* notification failure must not break the canary */ }
+}
+
+const prev = (() => { try { return JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return {}; } })();
+const now = {};
+let anyDead = false;
+
+for (const p of PROBES) {
+  const key = process.env[p.env];
+  if (!key) { console.log(`  ${p.env.padEnd(20)} absent`); continue; }
+  const status = await probe(p, key);
+  now[p.env] = { status, ts: new Date().toISOString() };
+  const mark = status === 'alive' ? '✅' : status === 'DEAD' ? '🚨' : '❓';
+  console.log(`  ${p.env.padEnd(20)} ${mark} ${status}  (${p.provider}, key len ${key.length})`);
+  if (status === 'DEAD') {
+    anyDead = true;
+    if (NOTIFY && prev[p.env]?.status !== 'DEAD') {
+      notify(`🚨 ${p.provider} API key is DEAD`,
+        `${p.env} was rejected (401/403) by ${p.provider} just now. Every script using it is silently failing. `
+        + `Rotate it: edit ~/Code/openclaw-stack/secrets.env, then run secrets-sync.sh seal.`,
+        'urgent', 'rotating_light,key');
+    }
+  } else if (status === 'alive' && NOTIFY && prev[p.env]?.status === 'DEAD') {
+    notify(`✅ ${p.provider} API key recovered`, `${p.env} is working again.`, 'default', 'white_check_mark,key');
+  }
+}
+
+try {
+  fs.mkdirSync(path.dirname(STATE), { recursive: true });
+  fs.writeFileSync(STATE, JSON.stringify(now, null, 2) + '\n');
+} catch { /* state persistence is best-effort */ }
+
+process.exit(anyDead ? 1 : 0);

package/scripts/latency-to-surface.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * latency-to-surface.mjs — the metric ADR-028 calls "the single best summary metric", finally measured.
+ *
+ * ADR-028:103 defines it: "time between a capability becoming dormant and the user being told."
+ * Target "hours, not weeks", against a 21-day baseline that the ADR says "this whole project exists
+ * to destroy." An independent grader on 2026-07-24 charged -6 against the Proactive pillar for it,
+ * with a fair description: the 21-day baseline was still prose. Nothing recorded when a capability
+ * went dormant, so nothing could subtract.
+ *
+ * WHY IT COULD NOT BE COMPUTED BEFORE, and what actually had to be built. The advocacy ledger already
+ * records when we SPOKE (`action:'offered'`, with an `at`). That is one end of the subtraction. The
+ * other end — when the capability BECAME dormant — existed nowhere, because the registry is a pure
+ * detector: it reports the state it observes right now and keeps no history. A detector with no
+ * memory can say "this is off"; it can never say "this has been off since Tuesday."
+ *
+ * So this file adds the missing half: an append-only log of capability state TRANSITIONS.
+ *
+ * ONLY TRANSITIONS, and that is a correctness decision rather than a disk-space one. If every
+ * observation were appended, "when did it become dormant" would depend on how often the console
+ * happened to be opened — a capability observed hourly would look freshly dormant, and the same
+ * capability observed weekly would look dormant for a week, from identical facts. Recording only
+ * changes makes the onset a property OF THE CAPABILITY rather than of our sampling schedule.
+ *
+ * WHAT COUNTS AS DORMANT — off and idle only.
+ *   off     → present and not running. Dormant.
+ *   idle    → set up, proven, nothing calling it. Dormant, and the state this product exists for.
+ *   absent  → NOT dormant. It was never installed; there is nothing lying unused.
+ *   unknown → NOT dormant. We could not establish the state, and "we could not tell" must never be
+ *             silently converted into "it is off" — that is the fabrication this repo's registry
+ *             rule exists to prevent, and it would inflate the metric with invented dormancy.
+ *
+ * THE HONEST NULL. With no history, every latency is `null`, never `0`. A fresh install has not
+ * achieved instant surfacing; it has no measurement at all, and the difference is the whole
+ * difference between this product and one that lies. `summarize()` reports `measured: 0` in that
+ * case and every caller must render it as "not measured yet".
+ *
+ * THE NUMBER THAT MATTERS MOST is not the average of what we surfaced — it is `stillDark`: things
+ * dormant right now that we have NEVER told the user about, with their clocks still running. A
+ * project that only averages its successes reports a beautiful latency while a capability quietly
+ * rots. Those are counted separately and never folded into the mean.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+
+export const STATE_LOG_PATH = process.env.RUVNET_CAPABILITY_STATE_LOG
+  || path.join(HOME, '.config', 'ruvnet-brain', 'capability-states.jsonl');
+
+/** The states that mean "you have this, and it is not doing anything." See the header. */
+export const DORMANT = new Set(['off', 'idle']);
+
+const MAX_KEY = 120;
+const MAX_LINE = 512;
+
+/** Same never-throws contract as the advocacy ledger: an unreadable log degrades to "no history". */
+export function loadStateLog(file = STATE_LOG_PATH) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    let r;
+    try { r = JSON.parse(s); } catch { continue; }
+    if (!r || typeof r.key !== 'string' || typeof r.state !== 'string') continue;
+    if (!Number.isFinite(Date.parse(r.at))) continue;
+    out.push(r);
+  }
+  return out;
+}
+
+/** The most recent recorded state per key — what a new observation is compared against. */
+function lastStates(log) {
+  const last = new Map();
+  for (const r of log) last.set(r.key, r);   // log is append-ordered
+  return last;
+}
+
+/**
+ * Record an observation, writing ONLY the keys whose state actually changed.
+ *
+ * Returns the transitions written, so a caller can act on them (and so a test can assert that a
+ * repeated identical observation writes nothing — the property the whole metric depends on).
+ */
+export function recordObservation(rows, { file = STATE_LOG_PATH, at = new Date() } = {}) {
+  const list = (Array.isArray(rows) ? rows : []).filter((r) => r && typeof r.key === 'string' && typeof r.state === 'string');
+  if (!list.length) return [];
+
+  const last = lastStates(loadStateLog(file));
+  const iso = (at instanceof Date && !Number.isNaN(at.getTime())) ? at.toISOString() : new Date().toISOString();
+
+  const transitions = [];
+  for (const r of list) {
+    const prev = last.get(r.key);
+    if (prev && prev.state === r.state) continue;   // unchanged — the sampling schedule must not leak in
+    transitions.push({
+      v: 1,
+      key: r.key.slice(0, MAX_KEY),
+      state: r.state,
+      from: prev ? prev.state : null,   // null = first time we ever saw this capability
+      at: iso,
+    });
+  }
+  if (!transitions.length) return [];
+
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const payload = transitions.map((t) => JSON.stringify(t)).join('\n') + '\n';
+    if (payload.length > MAX_LINE * transitions.length * 2) return [];   // absurd input: refuse rather than corrupt
+    const fd = fs.openSync(file, 'a');
+    try { fs.writeSync(fd, payload); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  } catch { return []; }   // an unwritable log must never break the console; it degrades to no history
+
+  return transitions;
+}
+
+/**
+ * When did this capability most recently BECOME dormant, and has it left dormancy since?
+ * Returns the ISO instant of the latest entry into a dormant state that it is still in, else null.
+ */
+function currentDormancyOnset(entries) {
+  let onset = null;
+  for (const e of entries) {
+    if (DORMANT.has(e.state)) { if (onset === null) onset = e.at; }
+    else onset = null;   // left dormancy (on / absent / unknown) — any earlier clock is void
+  }
+  return onset;
+}
+
+/**
+ * Join the state log against the advocacy ledger and compute the metric.
+ *
+ * `outcomes` is the advocacy ledger's rows (loadOutcomes()). Only `action:'offered'` counts as
+ * "the user was told" — an apply or a dismissal is a REPLY to having been told, and using it would
+ * measure the user's reaction time rather than ours.
+ */
+export function computeLatencies({ stateLog = loadStateLog(), outcomes = [], now = Date.now() } = {}) {
+  const byKey = new Map();
+  for (const e of stateLog) {
+    if (!byKey.has(e.key)) byKey.set(e.key, []);
+    byKey.get(e.key).push(e);
+  }
+
+  const toldAt = new Map();   // key → earliest 'offered' instant
+  for (const o of outcomes) {
+    if (!o || o.action !== 'offered' || typeof o.id !== 'string') continue;
+    const t = Date.parse(o.at);
+    if (!Number.isFinite(t)) continue;
+    const prev = toldAt.get(o.id);
+    if (prev === undefined || t < prev) toldAt.set(o.id, t);
+  }
+
+  const results = [];
+  for (const [key, entries] of byKey) {
+    const onsetIso = currentDormancyOnset(entries);
+    if (onsetIso === null) continue;   // not dormant right now — nothing to measure
+    const onset = Date.parse(onsetIso);
+    if (!Number.isFinite(onset)) continue;
+
+    // Only an offer made AT OR AFTER this dormancy began counts. An offer from a previous dormant
+    // spell says nothing about whether we surfaced THIS one, and crediting it would let a single old
+    // notification make every future lapse look instantly surfaced.
+    const told = toldAt.get(key);
+    const surfaced = Number.isFinite(told) && told >= onset;
+
+    results.push({
+      key,
+      dormantSince: onsetIso,
+      surfaced,
+      latencyMs: surfaced ? told - onset : null,
+      darkMs: surfaced ? null : Math.max(0, now - onset),
+    });
+  }
+  return results;
+}
+
+/**
+ * The reportable rollup. Everything here is `null` rather than `0` when unmeasured — see the header.
+ */
+export function summarize(rows) {
+  const measuredRows = rows.filter((r) => r.surfaced && Number.isFinite(r.latencyMs));
+  const dark = rows.filter((r) => !r.surfaced);
+  const lat = measuredRows.map((r) => r.latencyMs).sort((a, b) => a - b);
+
+  return {
+    dormantNow: rows.length,
+    measured: lat.length,
+    medianMs: lat.length ? lat[Math.floor((lat.length - 1) / 2)] : null,
+    worstMs: lat.length ? lat[lat.length - 1] : null,
+    // The number that matters most: dormant, never surfaced, clock running. Never averaged in.
+    stillDark: dark.length,
+    longestDarkMs: dark.length ? Math.max(...dark.map((r) => r.darkMs ?? 0)) : null,
+    baselineDays: 21,   // ADR-028:103 — the number this project exists to destroy
+  };
+}
+
+export function humanMs(ms) {
+  if (ms === null || ms === undefined || !Number.isFinite(ms)) return 'not measured';
+  const h = ms / 3_600_000;
+  if (h < 1) return `${Math.max(1, Math.round(ms / 60_000))}m`;
+  if (h < 48) return `${h < 10 ? h.toFixed(1) : Math.round(h)}h`;
+  return `${(h / 24).toFixed(1)}d`;
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────────────────
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { loadOutcomes } = await import('./advocacy-outcomes.mjs');
+  const rows = computeLatencies({ outcomes: loadOutcomes() });
+  const s = summarize(rows);
+
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ summary: s, rows }, null, 2));
+  } else {
+    console.log('latency-to-surface — ADR-028\'s "single best summary metric"');
+    console.log(`  baseline to beat : ${s.baselineDays}d`);
+    console.log(`  dormant now      : ${s.dormantNow}`);
+    if (!s.measured && !s.stillDark) {
+      console.log('  measured         : nothing yet — no capability has gone dormant since logging began.');
+      console.log('                     (This is "no data", NOT "instant". The distinction is the product.)');
+    } else {
+      console.log(`  median latency   : ${humanMs(s.medianMs)}  (from ${s.measured} surfaced)`);
+      console.log(`  worst latency    : ${humanMs(s.worstMs)}`);
+      if (s.stillDark) {
+        console.log(`  STILL DARK       : ${s.stillDark} dormant and never surfaced — longest ${humanMs(s.longestDarkMs)} and counting`);
+        console.log('                     These are excluded from the median on purpose: averaging only');
+        console.log('                     the successes is how a rotting capability hides behind a good number.');
+      }
+    }
+  }
+}