ruvnet-brain 4.7.20 → 4.7.21

package/scripts/model-weekly-cycle.mjs

@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { digest, currencyStatus, WEEK_MS } from './model-currency-evidence.mjs';
 import { subscriptionOnlyEnv } from './subscription-hosts.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const RETRY_MS = 3600000;
 function read(file, limit) {
@@ -212,7 +213,7 @@ export async function runWeeklyCycle({ routerDir = path.join(os.homedir(), '.cla
     try { save('weekly-cycle-last-attempt.json', record); } catch { /* superseded cannot write */ } return record;
   } finally { release(routerDir, token); }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const i = process.argv.indexOf('--router-dir'); const t = process.argv.indexOf('--claim-token'); runWeeklyCycle({ routerDir: i >= 0 ? process.argv[i + 1] : undefined, claimToken: t >= 0 ? process.argv[t + 1] : null }).then((r) => {
     if (r.status !== 'unchanged' || process.argv.includes('--json')) console.log(JSON.stringify(r));
     if (['failed', 'deferred', 'qualification-pending'].includes(r.status)) process.exitCode = 1;

package/scripts/model-weekly-qualification.mjs

@@ -6,6 +6,7 @@ import os from 'node:os';
 import { randomUUID, randomInt } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { candidateSha256, sha256, promoteRoutingPolicy } from './model-routing-policy-promotion.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const same = (a, b) => candidateSha256(a) === candidateSha256(b);
@@ -359,7 +360,7 @@ async function qualify(ctx) {
   return promoted;
 }
 
-if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(SELF)) {
+if (isDirectInvocation(import.meta.url)) {
   const args = process.argv.slice(2); const value = (flag) => args.includes(flag) ? args[args.indexOf(flag) + 1] : undefined;
   const result = await runWeeklyQualification({ routerDir: value('--router-dir'), semanticReceipt: value('--semantic-receipt'),
     deadline: args.includes('--deadline') ? Number(value('--deadline')) : undefined });

package/scripts/nightly-gists.sh

@@ -25,29 +25,25 @@ export KB_MODEL_CACHE="${KB_MODEL_CACHE:-/Users/stuartkerr/Code/PowerPlatePulse/
 
 mkdir -p logs
 LOG="logs/gists-nightly.log"
-# Heartbeat file: written every 30s to prove the job is still running.
-# Must match JOB_HEARTBEAT_DIR convention from job-heartbeat.sh and nightly-watchdog.mjs.
-HEARTBEAT_FILE="${JOB_HEARTBEAT_DIR:-$HOME/.cache/ruvnet-brain/heartbeats}/com.ruvnet.brain-gists.heartbeat"
+# Liveness proof is the job-heartbeat.sh wrapper's <label>.json receipt (read by nightly-watchdog.mjs).
+# A 30-second <label>.heartbeat writer used to live here; nothing ever read that file, so it was removed.
 ts() { date '+%Y-%m-%dT%H:%M:%S%z'; }
 log() { printf '[%s] %s\n' "$(ts)" "$1" >>"$LOG"; }
 
-# Heartbeat: write a timestamp every 30 seconds to prove the job is still running.
-# Runs in background; killed when the main script exits.
-start_heartbeat() {
-  mkdir -p "$(dirname "$HEARTBEAT_FILE")"
-  (
-    while true; do
-      printf '%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$HEARTBEAT_FILE"
-      sleep 30
-    done
-  ) &
-  HEARTBEAT_PID=$!
-  trap "kill $HEARTBEAT_PID 2>/dev/null || true" EXIT
-}
-start_heartbeat
-
 log "start"
 
+# The plist must NOT say ProcessType=Background. launchd then runs every process in the job under
+# macOS's background policy (efficiency cores only, throttled I/O): measured 2026-10-25 under launchd,
+# one 32-passage bge batch took 111-176 s as Background, 18 s as Standard, 10 s Interactive, 7-13 s
+# from a shell. Eight shards at once pushed a batch past the 15-minute stall budget, so every changed
+# night from 2026-10-08 on aborted as "stalled". Nice 5 plus forge-big's below-normal priority already
+# keep the job polite. Warn loudly if the installed plist regresses.
+PLIST="$HOME/Library/LaunchAgents/com.ruvnet.brain-gists.plist"
+if [ -x /usr/libexec/PlistBuddy ] && [ -f "$PLIST" ] \
+  && [ "$(/usr/libexec/PlistBuddy -c 'Print :ProcessType' "$PLIST" 2>/dev/null)" = "Background" ]; then
+  log "WARN: $PLIST has ProcessType=Background — the re-embed will crawl on efficiency cores and trip the stall budget; set it to Standard"
+fi
+
 command -v gh >/dev/null 2>&1 || { log "FATAL: gh not on PATH"; exit 1; }
 gh auth status >/dev/null 2>&1 || { log "FATAL: gh not authenticated"; exit 1; }
 
@@ -63,9 +59,19 @@ if ! OUT=$(node scripts/ingest-gists.mjs 2>&1); then
 fi
 printf '%s\n' "$OUT" >>"$LOG"
 
+# A night whose embed FAILED has already rewritten the passages and the sources receipt, so the next
+# night's ingest says "nothing to do" while the store is still the old one. Without this check that
+# night skipped the embed and exited 0 over a stale store (2026-10-25 20:18: "0 new", store dated
+# 2026-10-07). The store must be at least as new as the passages it is built from.
+PASSAGES="kb/ruv-gists.passages.jsonl"
+STORE="kb/ruv-gists.big.rvf"
 if printf '%s' "$OUT" | grep -q 'nothing to do'; then
-  log "no new gists — skipping embed (cost: 0)"
-  exit 0
+  if [ -f "$PASSAGES" ] && ! [ "$STORE" -nt "$PASSAGES" ]; then
+    log "no new gists, but $STORE is older than $PASSAGES (an earlier embed did not finish) — re-embedding"
+  else
+    log "no new gists — skipping embed (cost: 0)"
+    exit 0
+  fi
 fi
 
 # 3 — re-embed, only because the corpus actually changed. 8 shards, then one assemble.

package/scripts/nightly-two-run-proof.mjs

@@ -13,6 +13,7 @@ import { npmInvocation } from './npm-invocation.mjs';
 import { packageTreeObservation, observeNpxPackage, validateNpxObservations } from './nightly-package-observation.mjs';
 import { NIGHTLY_LABEL, NIGHTLY_PROOF_LABEL, validateRefreshReceiptEnvelope } from '../plugin/scripts/nightly-scheduler.mjs';
 import { validateCoverageDirectory, validateCoverageLedger } from '../plugin/scripts/coverage-integrity.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const PUBLIC_KEY = fs.readFileSync(new URL('../keys/ruvnet-brain-signing.pub.pem', import.meta.url), 'utf8');
 
@@ -599,7 +600,7 @@ export async function runNightlyTwoRunProof({ packagePath, bundlePath, out, time
   }
 }
 
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) {
+if (isDirectInvocation(import.meta.url)) {
   try {
     const args = parseArgs(process.argv.slice(2));
     const receipt = await runNightlyTwoRunProof({ packagePath: args.package, bundlePath: args.bundle, out: args.out,

package/scripts/nightly-watchdog.mjs

@@ -20,6 +20,8 @@
 //   NEVER-RAN — loaded, but no receipt has EVER been written (the brain-nightly case)
 //   STALE     — a receipt exists but is older than the job's schedule allows (it stopped)
 //   FAILING   — it ran and reported a non-zero exit, or it started and never finished
+//   STALLED   — running, but its per-shard progress has not moved within its stallMinutes
+//   STUCK     — still running past its registry maxRunHours with a live wrapper pid (4.7.21)
 //   OK        — a fresh receipt says it ran and exited 0. The ONLY state that counts as working.
 //
 // Shape confirmed against prior art in the ecosystem: agentic-qe/src/workers/workers/heartbeat-scheduler.ts
@@ -28,10 +30,20 @@
 // Alerts are TRANSITION-ONLY (the discipline proven in kb/brain-alarm.mjs): a state change pages once.
 // Constant redness must never become constant noise, or the gong trains you to ignore it.
 //
+// EXIT CODE = "was the verdict DELIVERED?", not "is every job green?" (4.7.21). A red job is the watchdog doing
+// its job; exiting 1 for it made the heartbeat wrapper page "SCHEDULED JOB FAILED: nightly-watchdog" on top of
+// the real page, every day. Exit 1 now means a page went undelivered or the watchdog itself broke, which the
+// wrapper's own curl page then reports by a second path.
+//
 // Usage:
-//   node scripts/nightly-watchdog.mjs           # verdict + exit 1 if ANY job is not OK
-//   node scripts/nightly-watchdog.mjs --json
-//   node scripts/nightly-watchdog.mjs --quiet   # cron mode: speak only when something is wrong
+//   node scripts/nightly-watchdog.mjs             # verdict; pages transitions; exit 0 when delivered
+//   node scripts/nightly-watchdog.mjs --strict    # for a human: also exit 1 if ANY job is not OK
+//   node scripts/nightly-watchdog.mjs --no-push   # judge and print only: no pages, no state write
+//   node scripts/nightly-watchdog.mjs --json      # machine-readable verdict (implies --no-push)
+//   node scripts/nightly-watchdog.mjs --quiet     # cron mode: speak only when something is wrong
+//   node scripts/nightly-watchdog.mjs --test-page # send one "watchdog delivery test" page; exit 0 only on 2xx
+// Exit codes: 0 delivered (or nothing due) · 1 a page was not delivered, an internal error, or --strict and red ·
+// 2 `launchctl list` was empty or failed (nothing judged, nothing paged, no state written).
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -40,6 +52,7 @@ import { spawnSync, execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { NIGHTLY_LABEL, schedulerStatus, updateOwnedByAgenticKit } from '../plugin/scripts/nightly-scheduler.mjs';
 import { oldestIncompleteProgress } from '../kb/shard-progress.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REGISTRY = process.env.WATCHDOG_REGISTRY || path.join(ROOT, 'config', 'scheduled-jobs.json');
@@ -53,6 +66,10 @@ export const NEVER_RAN = 'NEVER-RAN';
 export const STALE = 'STALE';
 export const FAILING = 'FAILING';
 export const STALLED = 'STALLED';
+/** Running longer than the job's registry `maxRunHours`, with its wrapper pid still alive (4.7.21). */
+export const STUCK = 'STUCK';
+/** The watchdog's own label: its receipt reads "running" while it judges, so it never judges itself. */
+const SELF_LABEL = process.env.WATCHDOG_SELF_LABEL || 'com.ruvnet.nightly-watchdog';
 
 /**
  * Per-shard progress evidence for a job that declares `progressGlob` + `stallMinutes` in the
@@ -86,6 +103,16 @@ export function loadedLabels(run = () => spawnSync('launchctl', ['list'], { enco
   );
 }
 
+/** Is `pid` still OUR wrapper for this label (not a recycled pid)? */
+function wrapperAlive(pid, label) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0); // signal 0 = existence check, sends nothing
+    const cmd = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+    return cmd.includes('job-heartbeat.sh') && cmd.includes(label); // guard against pid recycling
+  } catch { return false; }
+}
+
 /**
  * Judge one job from its receipt. `hb === null` means NO RECEIPT EXISTS — which is NEVER-RAN, never OK.
  * This single line is the whole lesson of 2026-07-13: absence of evidence is not evidence of health.
@@ -117,6 +144,16 @@ export function judge(job, hb, loaded, now, { root = ROOT } = {}) {
     }
   }
 
+  // STUCK (4.7.21): a job that declares `maxRunHours` and is still "running" past it is stuck even with a live
+  // wrapper pid — the 6 h long-run grace below exists for the corpus rebuild, not for a 2-minute job that hung.
+  // A gone pid is still the started-and-never-finished FAILING case.
+  if (hb.state === 'running' && job.maxRunHours && ageHours > job.maxRunHours) {
+    if (wrapperAlive(hb.pid, job.label)) {
+      return { state: STUCK, ageHours, detail: `still running after ${ageHours.toFixed(1)}h — its limit is ${job.maxRunHours}h. Wrapper pid ${hb.pid} is alive; the job is not finishing.` };
+    }
+    return { state: FAILING, ageHours, detail: `started ${ageHours.toFixed(1)}h ago and NEVER FINISHED — receipt says "running" but pid ${hb.pid ?? '?'} is GONE (killed/power loss skipped the trap)` };
+  }
+
   // Started and never finished? DERIVE it from process liveness, not wall-clock alone (2026-07-19):
   // a full corpus rebuild legitimately runs 12h+ (five changed repos = a long day), and the old
   // ">6h running ⇒ FAILING" rule false-alarmed on exactly that — a 13.5h nightly whose worker was
@@ -125,15 +162,7 @@ export function judge(job, hb, loaded, now, { root = ROOT } = {}) {
   // progress — OK, stated as such. If the pid is GONE while the receipt still says "running", THAT
   // is the real started-and-never-finished (SIGKILL/power loss skipped the trap) — FAILING.
   if (hb.state === 'running' && ageHours > 6) {
-    let alive = false;
-    if (hb.pid) {
-      try {
-        process.kill(hb.pid, 0); // signal 0 = existence check, sends nothing
-        const cmd = execFileSync('ps', ['-o', 'command=', '-p', String(hb.pid)], { encoding: 'utf8' });
-        alive = cmd.includes('job-heartbeat.sh') && cmd.includes(job.label); // guard against pid recycling
-      } catch { alive = false; }
-    }
-    if (alive) {
+    if (wrapperAlive(hb.pid, job.label)) {
       return { state: OK, ageHours, detail: `LONG RUN in progress — running ${ageHours.toFixed(1)}h, wrapper pid ${hb.pid} verified alive (full rebuilds legitimately take 12h+)` };
     }
     return { state: FAILING, ageHours, detail: `started ${ageHours.toFixed(1)}h ago and NEVER FINISHED — receipt says "running" but pid ${hb.pid ?? '?'} is GONE (killed/power loss skipped the trap)` };
@@ -190,19 +219,34 @@ export function readLegacyLog(job, root = ROOT) {
   } catch { return null; }
 }
 
-export function checkAll(now, { registry = REGISTRY, loaded = loadedLabels(), hbDir = HB_DIR, root = ROOT } = {}) {
+export function checkAll(now, { registry = REGISTRY, loaded = loadedLabels(), hbDir = HB_DIR, root = ROOT, self = SELF_LABEL } = {}) {
   const { jobs } = JSON.parse(fs.readFileSync(registry, 'utf8'));
   return jobs.map((job) => {
     const hb = readHeartbeat(job.label, hbDir) || readLegacyLog(job, root);
+    // Its own receipt says "running" because this IS that run: judging it is meaningless (it would always read
+    // OK, and announce a false recovery). SessionStart and the spend guard judge the watchdog instead (4.7.21).
+    if (job.label === self && hb?.state === 'running') {
+      return { ...job, state: OK, self: true, detail: 'this run — the watchdog does not judge itself; SessionStart and the spend guard do' };
+    }
     const verdict = judge(job, hb, loaded.has(job.label), now, { root });
     if (hb?._tier2 && verdict.state === OK) verdict.detail += ' (via its log — no receipt yet; the next run writes one)';
-    return { ...job, ...verdict };
+    // The heartbeat wrapper already paged (or deliberately damped) this failing streak itself (4.7.21).
+    // Only for a TERMINAL receipt: a "running" receipt that never finished carries the old streak's fields forward, but
+    // the wrapper never saw that death, so the watchdog must page it.
+    const wrapperPaged = verdict.state === FAILING && (hb?.state === 'failed' || hb?.state === 'killed')
+      && !!hb.failing_since && (hb.paged === true || hb.paged === 'suppressed');
+    // The wrapper will send its own "Recovered: X" when this job next passes: its receipt carries a failing streak
+    // whose page was delivered (job-heartbeat.sh announces recovery exactly then, also after a never-finished run).
+    // A watchdog page sent meanwhile (STALE, STUCK, ...) is then recorded as 'both', and its recovery note is left to
+    // the wrapper, so one recovery is announced once (4.7.21 review, Fable P2-2).
+    const wrapperRecovers = ['failed', 'killed', 'running'].includes(hb?.state) && !!hb.failing_since && hb.paged === true;
+    return { ...job, ...verdict, ...(wrapperPaged ? { wrapperPaged: true } : {}), ...(wrapperRecovers ? { wrapperRecovers: true } : {}) };
   });
 }
 
 export function productSchedulerVerdict(status) {
   const base = { label: NIGHTLY_LABEL, what: 'Refreshes the installed Brain corpus and converges every detected host',
-    schedule: 'daily 03:47', maxAgeHours: 30, required: true };
+    schedule: 'daily 03:30', maxAgeHours: 30, required: true };
   // A 'degraded' adapter whose only defect is a NON-ZERO LAST EXIT is a job that is loaded, verified
   // and FIRED — the exact opposite of MISSING ("not loaded — it can never fire", top of this file).
   // Its truth is the receipt. Measured 2026-09-12 against two FAILED receipts: this projected as
@@ -240,54 +284,116 @@ const saveState = (s) => { fs.mkdirSync(path.dirname(STATE), { recursive: true }
 
 /** Page only on a CHANGE of state. Repeating the same alarm nightly is how alarms get ignored. */
 export function transitions(results, prev) {
-  return results.filter((r) => (prev[r.label] ?? OK) !== r.state);
+  return results.filter((r) => !r.self && (prev[r.label] ?? OK) !== r.state);
+}
+
+/** An HTTP header value must be a ByteString. An emoji in `Title` made fetch() throw before sending a byte, so
+ *  this watchdog never delivered a page (4.7.21). Titles are plain ASCII; the meaning rides in `Tags`. */
+export const asciiTitle = (s) => String(s).replace(/[^\x20-\x7e]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200) || 'RuvNet Brain';
+
+/** The topic: NTFY_TOPIC when set (set-but-EMPTY is an explicit opt-out: null), else the owner's topic file. */
+function ntfyTopic() {
+  if (process.env.NTFY_TOPIC !== undefined) return process.env.NTFY_TOPIC.trim() || null;
+  try { return fs.readFileSync(path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ntfy-topic'), 'utf8').trim() || null; } catch { return null; }
 }
 
-async function push(title, body, priority) {
-  const topic = process.env.NTFY_TOPIC
-    || (() => { try { return fs.readFileSync(path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ntfy-topic'), 'utf8').trim(); } catch { return null; } })();
-  if (!topic) return false;
+/** One POST. Delivered means a 2xx answer — a 429 or 5xx is not a page. */
+async function push(topic, title, body, priority) {
+  const base = (process.env.NTFY_URL || 'https://ntfy.sh').replace(/\/+$/, '');
   try {
-    await fetch(`https://ntfy.sh/${topic}`, {
+    const res = await fetch(`${base}/${encodeURIComponent(topic)}`, {
       method: 'POST',
-      headers: { Title: title, Priority: priority, Tags: priority === 'urgent' ? 'rotating_light' : 'white_check_mark' },
+      headers: { Title: asciiTitle(title), Priority: priority, Tags: priority === 'urgent' ? 'rotating_light' : 'white_check_mark' },
       body,
+      signal: AbortSignal.timeout(10_000),
     });
-    return true;
+    return res.ok;
   } catch { return false; }
 }
 
+const RETRY_MS = Number(process.env.WATCHDOG_RETRY_MS ?? 30_000);
+const ATTEMPTS = 3;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Send every message, retrying the undelivered ones up to ATTEMPTS times, RETRY_MS apart. Returns the
+ *  indexes that never landed. */
+async function deliverAll(topic, messages) {
+  let pending = messages.map((_, i) => i);
+  for (let attempt = 1; attempt <= ATTEMPTS && pending.length; attempt++) {
+    if (attempt > 1) await sleep(RETRY_MS);
+    const still = [];
+    for (const i of pending) if (!(await push(topic, ...messages[i]))) still.push(i);
+    pending = still;
+  }
+  return new Set(pending);
+}
+
 async function main() {
-  const json = process.argv.includes('--json');
-  const quiet = process.argv.includes('--quiet');
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const quiet = argv.includes('--quiet');
+  const strict = argv.includes('--strict');
+  const noPush = json || argv.includes('--no-push');
+
+  if (argv.includes('--test-page')) {
+    const topic = ntfyTopic();
+    if (!topic) { console.error('nightly-watchdog: no ntfy topic configured (NTFY_TOPIC or ~/.cache/ruvnet-brain/ntfy-topic) — nothing sent'); process.exit(1); }
+    const failed = await deliverAll(topic, [['Watchdog delivery test', `nightly-watchdog --test-page from ${os.hostname()} at ${new Date().toISOString()}. If you can read this, pages reach you.`, 'default']]);
+    console.log(failed.size ? 'nightly-watchdog: test page NOT delivered (no 2xx after 3 attempts)' : 'nightly-watchdog: test page delivered (2xx)');
+    process.exit(failed.size ? 1 : 0);
+  }
+
+  // An empty or failed `launchctl list` (launchd busy, sandbox, a broken PATH) would read EVERY job as MISSING and
+  // page them all. It is not evidence about any job: say so, page nothing, keep the state (4.7.21).
+  const listing = spawnSync('launchctl', ['list'], { encoding: 'utf8' });
+  const loaded = loadedLabels(() => (listing.status === 0 ? listing.stdout || '' : ''));
+  if (!loaded.size) {
+    console.error(`nightly-watchdog: \`launchctl list\` returned no jobs (exit ${listing.status ?? listing.error?.code ?? '?'}) — cannot judge anything; nothing paged, state unchanged`);
+    process.exit(2);
+  }
+
   const brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
-  const results = [...checkAll(new Date()), ...(brainUpdateOwnedByAgenticKit() ? [] : [productSchedulerVerdict(schedulerStatus({
+  const results = [...checkAll(new Date(), { loaded }), ...(brainUpdateOwnedByAgenticKit() ? [] : [productSchedulerVerdict(schedulerStatus({
     brainHome, kbDir: process.env.RUVNET_BRAIN_KB || path.join(brainHome, 'kb'),
   }))])];
   const bad = results.filter((r) => r.state !== OK);
 
-  const prev = loadState();
-  // DERIVED, not asserted (F1, 2026-07-18): a transition is only recorded as handled when its page
-  // was actually DELIVERED (push() returned true). The old code saved every new state unconditionally
-  // — so a FAILING job whose urgent page failed (ntfy down for a minute) was marked "alerted" and,
-  // because alerts are transition-only, would NEVER page again. Now an undelivered transition keeps
-  // its PREVIOUS state in the snapshot, so the same transition re-fires (and re-pages) on the next
-  // run until a page genuinely lands. The ledger can no longer claim a page that didn't happen.
-  const undelivered = new Set();
-  for (const c of transitions(results, prev)) {
-    const delivered = c.state === OK
-      ? await push(`✅ ${c.label} is healthy again`, c.detail, 'default')
-      : await push(`🔴 ${c.state}: ${c.label}`, `${c.what}\n\n${c.detail}\n\nschedule: ${c.schedule}`, 'urgent');
-    if (!delivered) undelivered.add(c.label);
+  // DERIVED, not asserted (F1, 2026-07-18): a transition is only recorded as handled when its page was actually
+  // DELIVERED. An undelivered transition keeps its PREVIOUS state, so it re-fires on the next run until a page
+  // genuinely lands. A failure the heartbeat wrapper already paged is handled; so is the recovery of a failure the
+  // watchdog never paged itself (the wrapper sends that note). The watchdog pages what the wrapper cannot see:
+  // MISSING, NEVER-RAN, STALE, STALLED, STUCK, a run that never finished, and their recoveries (4.7.21).
+  const topic = noPush ? null : ntfyTopic();
+  const optedOut = !noPush && process.env.NTFY_TOPIC !== undefined && !topic;
+  let undelivered = new Set();
+  if (!noPush && !optedOut) {
+    const prev = loadState();
+    const pagedBy = { ...(prev._pagedBy || {}) };
+    const sends = []; const owners = []; const viaBoth = new Set();
+    for (const c of transitions(results, prev)) {
+      if (c.wrapperPaged) { pagedBy[c.label] = 'wrapper'; continue; }
+      if (c.state === OK) {
+        if (pagedBy[c.label] === 'both') { delete pagedBy[c.label]; continue; } // the wrapper's "Recovered" covers it
+        if (prev[c.label] === FAILING && pagedBy[c.label] !== 'watchdog') { delete pagedBy[c.label]; continue; }
+        sends.push([`${c.label} is healthy again`, c.detail, 'default']); owners.push(c.label);
+      } else {
+        if (c.wrapperRecovers) viaBoth.add(c.label);
+        sends.push([`${c.state}: ${c.label}`, `${c.what}\n\n${c.detail}\n\nschedule: ${c.schedule}`, 'urgent']); owners.push(c.label);
+      }
+    }
+    const failed = topic ? await deliverAll(topic, sends) : new Set(sends.map((_, i) => i));
+    undelivered = new Set([...failed].map((i) => owners[i]));
+    for (const [i, label] of owners.entries()) {
+      if (failed.has(i)) continue;
+      if (sends[i][2] === 'urgent') pagedBy[label] = viaBoth.has(label) ? 'both' : 'watchdog'; else delete pagedBy[label];
+    }
+    const next = Object.fromEntries(results.map((r) => [r.label,
+      r.self || undelivered.has(r.label) ? (prev[r.label] ?? OK) : r.state]));
+    saveState({ ...next, _pagedBy: pagedBy });
   }
-  saveState(Object.fromEntries(results.map((r) => [r.label, undelivered.has(r.label) ? (prev[r.label] ?? OK) : r.state])));
-  // Sol amendment to F1: an undelivered page also FAILS this run (exitCode, not exit — the report
-  // below still prints). The watchdog's own heartbeat then records the degradation, so "the pager is
-  // broken" is itself a paged, visible condition instead of a silent one.
-  if (undelivered.size > 0) process.exitCode = 1;
 
   if (json) console.log(JSON.stringify({ results, checkedAt: new Date().toISOString() }, null, 2));
-  else if (!quiet || bad.length) {
+  else if (!quiet || bad.length || undelivered.size) {
     console.log('Scheduled-job watchdog — proof each job RAN, not just that it exists\n');
     for (const r of results) {
       const icon = r.state === OK ? '✅' : '🔴';
@@ -298,8 +404,13 @@ async function main() {
     console.log(bad.length
       ? `${bad.length} of ${results.length} job(s) are NOT confirmed working. NEVER-RAN means the schedule has never fired — it does not mean "probably fine".`
       : `All ${results.length} jobs produced a fresh, successful receipt.`);
+    if (undelivered.size) console.log(`PAGE NOT DELIVERED for: ${[...undelivered].join(', ')} — it re-fires on the next run.`);
+    if (optedOut) console.log('(NTFY_TOPIC="" — paging disabled; no state recorded)');
   }
-  process.exit(bad.length || undelivered.size ? 1 : 0);
+  // Sol amendment to F1: an undelivered page FAILS this run, so "the pager is broken" is itself visible.
+  process.exit(undelivered.size || (strict && bad.length) ? 1 : 0);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();
+if (isDirectInvocation(import.meta.url)) {
+  try { await main(); } catch (e) { console.error(`nightly-watchdog: internal error — ${e?.stack || e}`); process.exit(1); }
+}

package/scripts/no-silent-substitution.mjs

@@ -29,6 +29,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { substitutionVerdict, inScope, codeOf, message } from '../plugin/scripts/substitution-wall.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -237,4 +238,4 @@ function main() {
   process.exit(1);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();
+if (isDirectInvocation(import.meta.url)) main();

package/scripts/notify.sh

@@ -1,12 +1,17 @@
 #!/bin/sh
 # notify.sh "<title>" "<message>" [priority] [tags] — push alert to Stuart's phone via ntfy.sh.
-# Topic from $NTFY_TOPIC or the project .env. Fail-silent: alerting must never break a pipeline.
+# Topic from $NTFY_TOPIC or the project .env. Alerting must never break a pipeline (no caller runs under
+# `set -e`), but the exit code now tells the truth so a caller can record delivery (4.7.21):
+#   0 delivered (2xx) · 1 not delivered (network or HTTP error; curl --fail) · 2 paging off (NTFY_TOPIC="" or no topic)
+# NTFY_TOPIC set-but-EMPTY is an explicit opt-out (job-heartbeat.sh's convention): it never falls through to .env.
 DIR=$(dirname "$0")
-TOPIC="${NTFY_TOPIC:-$(grep -m1 '^NTFY_TOPIC=' "$DIR/../.env" 2>/dev/null | cut -d= -f2)}"
-[ -z "$TOPIC" ] && exit 0
-curl -sS --max-time 10 \
+if [ "${NTFY_TOPIC+set}" = "set" ]; then TOPIC="$NTFY_TOPIC"
+else TOPIC="$(grep -m1 '^NTFY_TOPIC=' "$DIR/../.env" 2>/dev/null | cut -d= -f2)"; fi
+[ -z "$TOPIC" ] && exit 2
+curl -sS --fail --max-time 10 \
   -H "Title: ${1:-RuvNet Brain}" \
   -H "Priority: ${3:-default}" \
   -H "Tags: ${4:-brain}" \
-  -d "${2:-（no message)}" \
-  "https://ntfy.sh/$TOPIC" >/dev/null 2>&1 || true
+  -d "${2:-(no message)}" \
+  "${NTFY_URL:-https://ntfy.sh}/$TOPIC" >/dev/null 2>&1 || exit 1
+exit 0

package/scripts/ntfy-inbox.mjs

@@ -23,6 +23,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { isPersonIssue, judgeIssue } from './issue-watch.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = 'stuinfla/ruvnet-brain';
@@ -61,14 +62,27 @@ export function classify(msg) {
   let m;
   // job-heartbeat.sh pages "SCHEDULED JOB FAILED: X" / "Recovered: X"; nightly-watchdog.mjs pages "🔴 <STATE>: X" /
   // "✅ X is healthy again". Same cause, same key, so either recovery closes either failure.
-  if ((m = /SCHEDULED JOB FAILED: (\S+)/.exec(title)) || (m = /^\W*(?:FAILING|NEVER-RAN|STALE|MISSING|STALLED): (\S+)/.exec(title))) return { kind: 'job', key: `job:${m[1]}`, label: m[1], actionable: true };
+  if ((m = /SCHEDULED JOB FAILED: (\S+)/.exec(title)) || (m = /^\W*(?:FAILING|NEVER-RAN|STALE|MISSING|STALLED|STUCK): (\S+)/.exec(title))) return { kind: 'job', key: `job:${m[1]}`, label: m[1], actionable: true };
   if ((m = /Recovered: (\S+)/.exec(title)) || (m = /^\W*(\S+) is healthy again/.exec(title))) return { kind: 'job-recovered', key: `job:${m[1]}`, label: m[1], actionable: false, resolves: true };
   if ((m = /CI \w+: (.+)$/.exec(title))) {
     const b = /branch ([\w./-]{1,100})/.exec(body);
     // Keyed by workflow AND branch: a green main must never close a still-red release branch (review round 4).
     return { kind: 'ci', key: `ci:${m[1].trim()}@${b ? b[1] : 'main'}`, workflow: m[1].trim(), ...(b ? { branch: b[1] } : {}), actionable: true };
   }
-  if ((m = /(?:New issue|SLA breach: issue) #(\d+)/.exec(title))) return { kind: 'issue', key: `issue:${m[1]}`, number: Number(m[1]), actionable: true };
+  if ((m = /(?:New issue|SLA breach: issue) #(\d+)/.exec(title))) {
+    // ONE combined SLA page names every breaching issue (scripts/issue-watch.mjs: a "#N (age) title" line each, and
+    // "…and K more: #a #b" past 8). Each named issue is its own alert, so a 17-issue breach counts 17, not 1.
+    const numbers = [Number(m[1])];
+    if (/^SLA breach/.test(title)) {
+      for (const line of body.split('\n')) {
+        const listed = /^#(\d+) \(/.exec(line);
+        if (listed) numbers.push(Number(listed[1]));
+        else if (/^…and \d+ more:/.test(line)) for (const x of line.matchAll(/#(\d+)/g)) numbers.push(Number(x[1]));
+      }
+    }
+    const unique = [...new Set(numbers.filter((n) => Number.isSafeInteger(n) && n > 0))].slice(0, MAX_OPEN_ALERTS);
+    return { kind: 'issue', key: `issue:${unique[0]}`, number: unique[0], actionable: true, ...(unique.length > 1 ? { numbers: unique } : {}) };
+  }
   if ((m = /New PR #(\d+)/.exec(title))) return { kind: 'pr', key: `pr:${m[1]}`, number: Number(m[1]), actionable: true };
   if (/^Waiting on a reply/.test(title)) return { kind: 'digest', key: 'digest:issues', actionable: false };
   if (/New star/.test(title)) return { kind: 'info', key: `info:${msg.id}`, actionable: false };
@@ -115,23 +129,32 @@ export function fold(open, messages, { now = Date.now(), resolver = resolvedNow,
   for (const msg of messages) {
     if (!msg || typeof msg.id !== 'string' || folded.has(msg.id)) continue;
     folded.add(msg.id);
-    const c = classify(msg);
+    const classified = classify(msg);
     const at = new Date((msg.time || now / 1000) * 1000).toISOString();
-    if (c.resolves) {
-      const a = byKey.get(c.key);
-      if (a && !a.closedAt && Date.parse(at) >= Date.parse(a.lastAt) && resolver(a)) { a.closedAt = at; a.closedBy = 'recovered notice (confirmed)'; a.closedByMsg = msg.id; }
-      continue;
-    }
-    if (!c.actionable) continue;
-    const existing = byKey.get(c.key);
-    if (existing && !existing.closedAt) {
-      // lastAt only moves forward: a delayed older message must not make a newer failure look resolved.
-      existing.count += 1;
-      if (Date.parse(at) > Date.parse(existing.lastAt)) { existing.lastAt = at; existing.lastTitle = msg.title; }
-      existing.msgIds = [...(existing.msgIds || []), msg.id].slice(-10);
-      continue;
+    // A combined SLA page becomes one alert per issue it names; the first keeps the message id, the rest get id-N.
+    const parts = classified.numbers ? classified.numbers.map((n, i) => {
+      const one = { ...classified, key: `issue:${n}`, number: n, alertId: i === 0 ? msg.id : `${msg.id}-${n}` };
+      delete one.numbers;
+      return one;
+    }) : [classified];
+    for (const c of parts) {
+      if (c.resolves) {
+        const a = byKey.get(c.key);
+        if (a && !a.closedAt && Date.parse(at) >= Date.parse(a.lastAt) && resolver(a)) { a.closedAt = at; a.closedBy = 'recovered notice (confirmed)'; a.closedByMsg = msg.id; }
+        continue;
+      }
+      if (!c.actionable) continue;
+      const existing = byKey.get(c.key);
+      if (existing && !existing.closedAt) {
+        // lastAt only moves forward: a delayed older message must not make a newer failure look resolved.
+        existing.count += 1;
+        if (Date.parse(at) > Date.parse(existing.lastAt)) { existing.lastAt = at; existing.lastTitle = msg.title; }
+        existing.msgIds = [...(existing.msgIds || []), msg.id].slice(-10);
+        continue;
+      }
+      const { alertId, ...fields } = c;
+      byKey.set(c.key, { id: alertId || msg.id, ...fields, firstAt: at, lastAt: at, count: 1, title: msg.title || '', body: String(msg.message || '').slice(0, 200), msgIds: [msg.id], attempts: 0 });
     }
-    byKey.set(c.key, { id: msg.id, ...c, firstAt: at, lastAt: at, count: 1, title: msg.title || '', body: String(msg.message || '').slice(0, 200), msgIds: [msg.id], attempts: 0 });
   }
   const byOldestCheck = [...byKey.values()].sort((x, y) => Date.parse(x.lastCheckedAt || 0) - Date.parse(y.lastCheckedAt || 0));
   for (const a of byOldestCheck) {
@@ -506,7 +529,7 @@ export function formatOpen(alerts) {
     + `${a.count > 1 ? `  (×${a.count}, since ${clean(a.firstAt, 30)})` : ''}\n    ${clean(String(a.body || '').split('\n')[0], 160)}`).join('\n') + tail;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const args = process.argv.slice(2);
   try {
     if (args[0] === '--open') {