ruvnet-brain 4.7.19 → 4.7.21

package/scripts/model-router-dispatch.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { assertCurrentSelection, selectionEvidenceStatus, loadSelection, loadCatalog, loadProfile, applyProfile, eligibleCandidates, TASK_CLASSES } from './model-router-engine.mjs';
 
 import { readCodexAllowance } from './native-subscription-usage.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const BILLING_ENV = /^(OPENAI_API_KEY|OPENAI_BASE_URL|ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|ANTHROPIC_CUSTOM_HEADERS|CLAUDE_CODE_USE_BEDROCK|CLAUDE_CODE_USE_VERTEX|CLAUDE_CODE_USE_FOUNDRY|CODEX_API_KEY)$/;
@@ -156,6 +157,6 @@ async function main(argv) {
       taskClass: decision.taskClass, executed: false }) + '\n');
   } else process.exitCode = await dispatch(decision, prompt, { interactive });
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   main(process.argv.slice(2)).catch((e) => { process.stderr.write(`model-router-dispatch: ${e.message}\n`); process.exitCode = 1; });
 }

package/scripts/model-router-engine.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { pathToFileURL, fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 import { estTokens } from './route-cheap.mjs'; // reuse the verified char/4 estimator (DRY)
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -309,6 +310,6 @@ async function main() {
   }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   main().catch((e) => { process.stderr.write(`model-router-engine: ${e.stack || e.message}\n`); process.exit(1); });
 }

package/scripts/model-router-outcome.mjs

@@ -25,6 +25,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const OUTCOMES_LOG =
   process.env.MODEL_ROUTER_OUTCOMES ||
@@ -105,6 +106,6 @@ function main() {
   console.log(`[model-router-outcome] logged: ${JSON.stringify(entry)}`);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   try { main(); } catch (e) { process.stderr.write(`model-router-outcome: ${e.message}\n`); process.exit(1); }
 }

package/scripts/model-router-setup.mjs

@@ -27,6 +27,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import readline from 'node:readline/promises';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const CONFIG_DIR = path.join(os.homedir(), '.claude', 'model-router');
 export const PROFILE_PATH = process.env.MODEL_ROUTER_PROFILE || path.join(CONFIG_DIR, 'profile.json');
@@ -136,6 +137,6 @@ async function main() {
 }
 
 const { pathToFileURL } = await import('node:url');
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   main().catch((e) => { console.error(`model-router-setup: ${e.message}`); process.exit(1); });
 }

package/scripts/model-routing-eval.mjs

@@ -8,6 +8,7 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import { classify } from '../config/model-router/policy.default.mjs';
 import { extractFeatures } from './model-router-engine.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const DEFAULT_CASES = path.join(ROOT, 'config/model-router/routing-eval-cases.json');
@@ -96,7 +97,7 @@ export function runEvaluation({ caseFile = DEFAULT_CASES, generatedAt } = {}) {
   return report;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const args = process.argv.slice(2);
   if (args.length && (args.length !== 2 || args[0] !== '--out')) throw new Error('Usage: node scripts/model-routing-eval.mjs [--out <report.json>]');
   const report = runEvaluation();

package/scripts/model-routing-gateway.mjs

@@ -11,6 +11,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { spawn, execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { subscriptionEnvironment, assertSubscriptionAuth, validateDispatchDecision, loadNativeCodexModels } from './model-router-dispatch.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REFUSED = 'Current reviewed native model/effort allocation unavailable; new turn was not forwarded.';
@@ -448,6 +449,6 @@ async function main(argv) {
   child.once('exit', (code, signal) => { process.stdin.pause(); process.stdin.unref?.(); process.exitCode = code ?? (signal ? 1 : 0); });
   child.once('error', () => { process.stderr.write('[native-model-routing] Native host transport unavailable.\n'); process.exitCode = 1; });
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   main(process.argv.slice(2)).catch(() => { process.stderr.write('[native-model-routing] Explicit native executable or subscription authentication unavailable.\n'); process.exitCode = 1; });
 }

package/scripts/model-routing-launchers.mjs

@@ -218,7 +218,10 @@ export function updateLauncherSettings(file, requested, { apply = false } = {})
   return receipt;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === SELF) {
+// installNativeLaunchers() copies THIS file alone to ~/.cache/ruvnet-brain/model-routing/ as the
+// launcher runner, so it cannot import plugin/scripts/entrypoint.mjs; this is that helper's
+// comparison, inline: real paths on both sides.
+if ((() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(SELF); } catch { return false; } })()) {
   const argv = process.argv.slice(2);
   if (argv[0] === '--launch') {
     try {

package/scripts/model-terminal-gateway.mjs

@@ -11,6 +11,7 @@ import { spawn } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import { connectNativeGateway, decideNativeTurn, nativeGatewayLaunch } from './model-routing-gateway.mjs';
 import { subscriptionEnvironment, assertSubscriptionAuth } from './model-router-dispatch.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const MAX_TERMINAL_BYTES = 64 * 1024 * 1024;
 const REFUSED = 'Native terminal routing unavailable; request was not sent.';
@@ -302,7 +303,7 @@ function exitOf(child) {
   });
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   runTerminalGateway(parseTerminalInvocation(process.argv.slice(2))).then(({ code, signal }) => {
     if (signal) { process.removeAllListeners(signal); process.kill(process.pid, signal); }
     else process.exitCode = code ?? 1;

package/scripts/model-terminal-launchers.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { classifyTerminalArguments, validateUpstreamSocket, terminalTempRoot } from './model-terminal-gateway.mjs';
 import { nativeGatewayLaunch } from './model-routing-gateway.mjs';
 import { subscriptionEnvironment, assertSubscriptionAuth } from './model-router-dispatch.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const MARKER = '# Managed RuvNet Brain terminal launcher';
@@ -343,7 +344,7 @@ export async function runTerminalLauncher({ host, args = [], config, env = proce
   const unforward = forwardSignals(child, signalSource);
   try { return await exitOf(child); } finally { unforward(); }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === SELF) {
+if (isDirectInvocation(import.meta.url)) {
   const argv = process.argv.slice(2);
   Promise.resolve().then(() => {
     if (argv[0] !== '--launch' || argv[2] !== '--config' || argv[4] !== '--') throw new Error('Explicit host/config terminal launcher required');

package/scripts/model-weekly-analyst.mjs

@@ -11,6 +11,7 @@ import { subscriptionOnlyEnv } from './subscription-hosts.mjs';
 import { applyProfile, loadCatalog, selectionEvidenceStatus } from './model-router-engine.mjs';
 import { createAnalystHome, trustAnalystDenial } from './model-analyst-sandbox.mjs';
 import { digest, currencyStatus, WEEK_MS } from './model-currency-evidence.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const text = { type: 'string', maxLength: 320 };
 const sourceId = { type: 'string', maxLength: 64 };
@@ -328,7 +329,7 @@ export function maybeLaunchWeeklyAnalyst({ routerDir = path.join(os.homedir(), '
     } catch (error) { release(routerDir, token); throw error; }
   } catch (error) { return { status: 'blocked', launched: false, reason: error.message.slice(0, 240) }; }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const index = process.argv.indexOf('--router-dir'); const routerDir = index >= 0 ? process.argv[index + 1] : undefined;
   const claimIndex = process.argv.indexOf('--claim-token');
   if (!process.argv.includes('--run')) { console.log(JSON.stringify(maybeLaunchWeeklyAnalyst({ routerDir }))); } else runWeeklyAnalyst({ routerDir, claimToken: claimIndex >= 0 ? process.argv[claimIndex + 1] : null, ...(process.argv.includes('--timeout-ms') ? { timeoutMs: Number(process.argv[process.argv.indexOf('--timeout-ms') + 1]) } : {}) }).then((result) => { console.log(JSON.stringify(result)); if (result.status === 'failed') process.exitCode = 1; }).catch((error) => { console.error(error.message); process.exitCode = 1; });

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

@@ -17,34 +17,33 @@
 set -eu
 
 cd "$(dirname "$0")/.."
-export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+# The owner's macOS-approved node (~/.local/share/ruvnet-brain/job-bin) and Apple's tools come first: this repo and
+# the model cache live on an external volume, and launchd-started Homebrew node is held at its first read there
+# (2026-10-25: every embedding shard "stalled" for 15 min, then the run failed after 1 h 49 min).
+export PATH="$HOME/.local/share/ruvnet-brain/job-bin:/usr/bin:/bin:/opt/homebrew/bin:/usr/local/bin"
 export KB_MODEL_CACHE="${KB_MODEL_CACHE:-/Users/stuartkerr/Code/PowerPlatePulse/scripts/models-cache}"
 
 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; }
 
@@ -60,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();