ruvnet-brain 4.7.20 → 4.7.22

package/scripts/issue-fix.mjs

@@ -46,7 +46,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { BOT_MARKER, OWNER_LOGIN } from './issue-watch.mjs';
+import { BOT_MARKER, OWNER_LOGIN, ghJsonWithRetry } 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';
@@ -118,28 +119,10 @@ export function executionPolicy(mode = 'unattended') {
   throw new Error(`unsupported issue-fix mode: ${mode}`);
 }
 
-function ghJson(args) {
-  // Retry ONCE on a transient network-shaped failure (2026-07-19: a 1am GitHub API blip — "TLS
-  // handshake timeout" / "unexpected EOF" — failed the whole run and gonged the phone, when 20s of
-  // patience was the honest fix). Same bounded philosophy as nightly-wrapper's retry: blind retries
-  // fix exactly one class (transient network), so retry exactly once, log the first failure, and
-  // still fail LOUD if it happens twice. Never a silent swallow.
-  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-fix: transient gh/network failure (${err.slice(0, 90)}) — retrying once in 20s`);
-      spawnSync('sleep', ['20']);
-      continue;
-    }
-    break;
-  }
-  throw lastErr;
-}
+// Transient gh failures (TLS handshake, "error connecting to api.github.com", HTTP 502/503/504) are retried with
+// backoff by the watcher's shared helper — one rule in one place (4.7.21: the old copy here missed the 1 a.m.
+// "error connecting" blip and paged). Anything else still fails LOUD on the first attempt.
+const ghJson = (args) => ghJsonWithRetry(args, { bin: GH_BIN, who: 'issue-fix' });
 
 function loadState() {
   try { return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')); } catch { return {}; }
@@ -555,4 +538,4 @@ async function main() {
   process.exit(failedAttempt ? 1 : 0);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/issue-watch.mjs

@@ -33,6 +33,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = 'stuinfla/ruvnet-brain';
@@ -46,6 +47,8 @@ export const OWNER_LOGIN = 'stuinfla';
 // moved here.)
 export const BOT_MARKER = '🤖 Automated';
 const SLA_HOURS = 4;
+// A person's issue whose detail AND list comments cannot be read this many runs in a row fails the run once (review fix).
+const UNREADABLE_RUNS = 3;
 // WHO IS WAITING (owner, 2026-10-25: "10,747 notifications"). An issue opened by the owner's own account or a bot is
 // work the owner's automation filed (Dream Cycle, dependabot), not a person waiting for an answer: it never pages
 // and gets no acknowledgment. Only a person's issue pages.
@@ -69,26 +72,33 @@ const STATE_PATH = process.env.ISSUE_WATCH_STATE
 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.
+/** A network-shaped gh failure worth waiting out (2026-07-19 "TLS handshake timeout"; 4.7.21 adds the 1 a.m.
+ *  "error connecting to api.github.com" and GitHub's 502/503/504). Anything else — auth, 404, bad JSON — is real. */
+export function isTransientGhError(text) {
+  return /TLS handshake|unexpected EOF|timeout|ECONNRESET|ETIMEDOUT|EAI_AGAIN|connection refused|temporarily unavailable|error connecting to api\.github\.com|HTTP 50[234]/i.test(String(text || ''));
+}
+/** Seconds to wait before attempts 2 and 3. Bounded: three attempts, then the failure is loud. */
+export const GH_RETRY_DELAYS_S = [10, 30];
+
+/** `gh … --json` with backoff on transient failures. Shared by issue-fix.mjs (one rule, one place). */
+export function ghJsonWithRetry(args, { bin = GH_BIN, who = 'issue-watch' } = {}) {
   let lastErr;
-  for (let attempt = 1; attempt <= 2; attempt++) {
-    const res = spawnSync(GH_BIN, args, { encoding: 'utf8' });
+  for (let attempt = 1; attempt <= GH_RETRY_DELAYS_S.length + 1; attempt++) {
+    const res = spawnSync(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']);
+    if (attempt <= GH_RETRY_DELAYS_S.length && isTransientGhError(err)) {
+      const wait = GH_RETRY_DELAYS_S[attempt - 1];
+      console.error(`${who}: transient gh/network failure (${err.slice(0, 90)}) — retry ${attempt} in ${wait}s`);
+      spawnSync('sleep', [String(wait)]);
       continue;
     }
     break;
   }
   throw lastErr;
 }
+const ghJson = (args) => ghJsonWithRetry(args);
 
 /** 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. */
@@ -109,11 +119,15 @@ function resolveTopic() {
 }
 
 async function pushNtfy(topic, { title, body, priority = 'urgent', tags = 'rotating_light' }) {
+  const base = (process.env.NTFY_URL || 'https://ntfy.sh').replace(/\/+$/, '');
   try {
-    const res = await fetch(`https://ntfy.sh/${topic}`, {
+    // Title is ASCII only: a non-ByteString header makes fetch() throw before sending (4.7.21). Issue titles never
+    // go in the header — they are public, untrusted text — only the body.
+    const res = await fetch(`${base}/${encodeURIComponent(topic)}`, {
       method: 'POST',
-      headers: { Title: title, Priority: priority, Tags: tags },
+      headers: { Title: String(title).replace(/[^\x20-\x7e]+/g, ' ').trim(), Priority: priority, Tags: tags },
       body,
+      signal: AbortSignal.timeout(10_000),
     });
     return res.ok;
   } catch {
@@ -121,8 +135,15 @@ async function pushNtfy(topic, { title, body, priority = 'urgent', tags = 'rotat
   }
 }
 
+/** A missing or unreadable state file is an empty one. That is safe since 4.7.21 (a reset state replayed 17
+ *  "SLA breach" pages in 11 s): every breach due in one run is ONE page, and an acknowledgment already on the
+ *  thread is recognised from the thread itself, never posted twice. */
 function loadState() {
-  try { return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')); } catch { return {}; }
+  try {
+    const v = JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+    if (v && typeof v === 'object' && !Array.isArray(v)) return v;
+  } catch { /* fall through */ }
+  return {};
 }
 
 function saveState(state) {
@@ -155,12 +176,43 @@ export async function run({ dryRun = false, now = Date.now(), repo = REPO } = {}
   const state = loadState();
   const results = [];
   const alertsSent = [];
+  const degraded = [];
+  const dueBreaches = [];
+  const unreadable = []; // person issues unreadable for UNREADABLE_RUNS runs and no other way to judge them: fail once
 
   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);
+    // One issue whose detail cannot be read does not stop the run (4.7.21). It is judged from the comments the list
+    // call already returned (review fix: before, it was skipped forever and never got its SLA page); with no list
+    // comments either it is skipped, and once it has been unreadable on UNREADABLE_RUNS runs in a row the run fails
+    // ONCE so the heartbeat wrapper pages. Never acknowledged from the list copy (it may be incomplete, and a second
+    // public acknowledgment is worse than none).
+    let detail; let fromList = false;
+    try { detail = ghJson(['issue', 'view', String(issue.number), '--repo', repo, '--json', 'comments']); }
+    catch (err) {
+      degraded.push(issue.number);
+      const prev = state[key] || {};
+      const runs = (Number(prev.unreadableRuns) || 0) + 1;
+      state[key] = { ...prev, unreadableRuns: runs, unreadableSince: prev.unreadableSince || new Date(now).toISOString() };
+      if (Array.isArray(issue.comments)) {
+        detail = { comments: issue.comments }; fromList = true;
+        console.error(`issue-watch: #${issue.number} detail unreadable — judged from the list's comments — ${err.message.slice(0, 160)}`);
+      } else {
+        console.error(`issue-watch: #${issue.number} skipped this run (${runs} in a row) — ${err.message.slice(0, 160)}`);
+        if (isPersonIssue(issue) && runs >= UNREADABLE_RUNS && !prev.unreadableEscalatedAt) {
+          unreadable.push(issue.number);
+          state[key].unreadableEscalatedAt = new Date(now).toISOString();
+        }
+        continue;
+      }
+    }
+    if (!fromList && state[key]?.unreadableRuns) { // readable again: the next unreadable streak counts from zero
+      state[key] = { ...state[key] };
+      for (const f of ['unreadableRuns', 'unreadableSince', 'unreadableEscalatedAt']) delete state[key][f];
+    }
+    const comments = detail.comments || [];
+    const { ageHours, ownerComment, breach } = judgeIssue(issue, comments, now);
     // A person's issue pages ONCE when it first passes the SLA, never again (it used to repeat every 4 h, forever,
     // which with ~14 old issues and an hourly run was most of the 10,747 notifications). The morning digest below
     // carries whatever is still waiting. An existing lastAlertAt means that one page already went out.
@@ -175,7 +227,13 @@ export async function run({ dryRun = false, now = Date.now(), repo = REPO } = {}
     // Arrival is paged once, instantly, by .github/workflows/ntfy-alerts.yml (the `issues: opened` event). Paging it
     // here too sent every new issue twice (review 2026-10-25), so this watcher owns only the SLA page and the digest.
     const needsNewPage = false;
-    const needsAck = person && !state[key]?.ackAt;
+    // Our acknowledgment already on the thread (a lost or reset state file) is never posted twice in public.
+    const alreadyAcked = comments.some((c) => c.author?.login === OWNER_LOGIN
+      && /^🤖 Automated acknowledgment/.test(String(c.body || '').trimStart()));
+    if (person && !state[key]?.ackAt && alreadyAcked) {
+      state[key] = { ...(state[key] || {}), ackAt: new Date(now).toISOString(), ackBaselined: true, title: issue.title, url };
+    }
+    const needsAck = person && !fromList && !state[key]?.ackAt;
 
     results.push({ number: issue.number, title: issue.title, ageHours, ownerComment, breach, dueForAlert, firstSighting, url, person });
 
@@ -214,34 +272,47 @@ export async function run({ dryRun = false, now = Date.now(), repo = REPO } = {}
       }
     }
 
-    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 (dueForAlert) dueBreaches.push({ issue, ageHours, url, key });
+  }
+
+  // ONE page per run for every breach that is due (4.7.21), oldest first, body bounded to 8 lines. The title keeps
+  // the "SLA breach: issue #N" shape scripts/ntfy-inbox.mjs classifies. DERIVED, not asserted (F5, 2026-07-18):
+  // lastAlertAt is written only for a delivered page; a failed page retries next run as the same single page.
+  // Spread-merge, never overwrite (2026-07-24: clobbering firstSeenAt/newAlertAt re-paged forever).
+  let breachPaged = new Set();
+  if (dueBreaches.length) {
+    dueBreaches.sort((a, b) => b.ageHours - a.ageHours);
+    const [first, ...rest] = dueBreaches;
+    const title = rest.length
+      ? `SLA breach: issue #${first.issue.number} (+${rest.length} more waiting > ${SLA_HOURS}h)`
+      : `SLA breach: issue #${first.issue.number}`;
+    const lines = dueBreaches.slice(0, 8).map((b) => `#${b.issue.number} (${fmtAge(b.ageHours)}) ${String(b.issue.title).slice(0, 70)}`);
+    // Past 8 lines the rest are still NAMED ("…and K more: #a #b"): scripts/ntfy-inbox.mjs files one alert per issue,
+    // so the session banner counts the breach truly (a 17-issue page used to count as 1).
+    const body = `${dueBreaches.length} contributor issue(s) past ${SLA_HOURS}h with no response from ${OWNER_LOGIN}:\n${lines.join('\n')}`
+      + (dueBreaches.length > 8 ? `\n…and ${dueBreaches.length - 8} more: ${dueBreaches.slice(8).map((b) => `#${b.issue.number}`).join(' ')}` : '')
+      + `\nhttps://github.com/${repo}/issues`;
+    if (dryRun) {
+      for (const b of dueBreaches) alertsSent.push({ number: b.issue.number, sent: false, kind: 'sla-breach', reason: 'dry-run' });
+    } else {
+      const topic = resolveTopic();
+      const sent = topic ? await pushNtfy(topic, { title, body, priority: 'urgent', tags: 'rotating_light,warning' }) : false;
+      for (const b of dueBreaches) {
+        if (sent) state[b.key] = { ...(state[b.key] || {}), lastAlertAt: new Date(now).toISOString(), title: b.issue.title, url: b.url };
+        else state[b.key] = { ...(state[b.key] || {}), lastAttemptAt: new Date(now).toISOString(), sent: false, title: b.issue.title, url: b.url };
+        alertsSent.push({ number: b.issue.number, sent, kind: 'sla-breach', reason: topic ? null : 'no ntfy topic configured' });
       }
+      if (sent) breachPaged = new Set(dueBreaches.map((b) => b.issue.number));
     }
   }
 
   // The morning digest: one notification naming every person's issue still unanswered, oldest first.
   const waiting = results.filter((r) => r.person && r.breach).sort((a, b) => b.ageHours - a.ageHours);
   const digest = digestDue(state._digest?.day, now);
-  if (waiting.length && digest.due) {
+  // Everything still waiting was named in this run's breach page: that page IS today's summary.
+  if (waiting.length && digest.due && waiting.every((r) => breachPaged.has(r.number))) {
+    state._digest = { day: digest.day, sentAt: new Date(now).toISOString(), count: waiting.length, viaBreachPage: true };
+  } else if (waiting.length && digest.due) {
     const title = `Waiting on a reply: ${waiting.length} contributor issue${waiting.length === 1 ? '' : 's'}`;
     const body = waiting.slice(0, 8).map((r) => `#${r.number} (${fmtAge(r.ageHours)}) ${r.title.slice(0, 70)}`).join('\n')
       + (waiting.length > 8 ? `\n…and ${waiting.length - 8} more` : '') + `\nhttps://github.com/${repo}/issues`;
@@ -256,7 +327,7 @@ export async function run({ dryRun = false, now = Date.now(), repo = REPO } = {}
 
   if (!dryRun) saveState(state);
 
-  return { results, alertsSent, checkedAt: new Date(now).toISOString() };
+  return { results, alertsSent, degraded, unreadable, checkedAt: new Date(now).toISOString() };
 }
 
 /**
@@ -430,7 +501,12 @@ async function main() {
   // 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);
+  // Skipping one unreadable issue is a degraded run, not a failed one; reading NONE of them is a failure.
+  const allDegraded = output.degraded.length > 0 && output.results.length === 0;
+  if (output.degraded.length) console.error(`issue-watch: ${output.degraded.length} issue(s) not fully readable this run: #${output.degraded.join(', #')}`);
+  const stuck = !dryRun && (output.unreadable || []).length > 0;
+  if (stuck) console.error(`issue-watch: FAILING this run once — a person's issue has been unreadable ${UNREADABLE_RUNS} runs in a row and cannot be judged: #${output.unreadable.join(', #')}`);
+  process.exit(undeliveredAlert || allDegraded || stuck ? 1 : 0);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/job-heartbeat.sh

@@ -78,24 +78,41 @@ RUN_ID="$$-$START_EPOCH"
 # SIGKILLed, the watchdog's started-and-never-finished detection had nothing left to see.
 PREV_HB=""
 [ -f "$HB" ] && PREV_HB="$(cat "$HB" 2>/dev/null)"
+# The failing streak and the last page time ride in EVERY receipt, including "running" (4.7.21): a run that is
+# SIGKILLed mid-streak must not erase them, or the next failure would page as a brand-new streak.
+field_str() { printf '%s' "$PREV_HB" | sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p" | head -1; }
+field_num() { printf '%s' "$PREV_HB" | sed -n "s/.*\"$1\":\([0-9][0-9]*\).*/\1/p" | head -1; }
+prev_state="$(field_str state)"
+prev_since="$(field_str failing_since)"
+prev_page_epoch="$(field_num last_page_epoch)"
+prev_page_at="$(field_str last_page_at)"
+prev_paged="$(printf '%s' "$PREV_HB" | sed -nE 's/.*"paged":("[a-z]*"|true|false).*/\1/p' | head -1)"
+CARRY=""
+[ -n "$prev_page_epoch" ] && CARRY="$CARRY,\"last_page_epoch\":$prev_page_epoch"
+[ -n "$prev_page_at" ] && CARRY="$CARRY,\"last_page_at\":\"$prev_page_at\""
+case "$prev_state" in failed|killed|running)
+  [ -n "$prev_since" ] && CARRY="$CARRY,\"failing_since\":\"$prev_since\""
+  [ -n "$prev_since" ] && [ -n "$prev_paged" ] && CARRY="$CARRY,\"paged\":$prev_paged" ;;
+esac
 
 # Start receipt. If the job vanishes without ever writing an end receipt, THIS is the evidence that
 # it started and never finished — a state the watchdog reports as FAILING, not as silence.
-write_receipt "{\"label\":\"$LABEL\",\"started_at\":\"$STARTED\",\"state\":\"running\",\"pid\":$$,\"run_id\":\"$RUN_ID\",\"command\":\"$(printf '%s %s' "$1" "${2:-}" | tr -d '"\\\n\r' | cut -c1-200)\"}"
+write_receipt "{\"label\":\"$LABEL\",\"started_at\":\"$STARTED\",\"state\":\"running\",\"pid\":$$,\"run_id\":\"$RUN_ID\",\"command\":\"$(printf '%s %s' "$1" "${2:-}" | tr -d '"\\\n\r' | cut -c1-200)\"$CARRY}"
 
-notify() { # notify <title> <body> <priority>
+notify() { # notify <title> <body> <priority> — 0 delivered · 1 not delivered · 2 paging disabled (opt-out)
   # NTFY_TOPIC set-but-EMPTY is an explicit opt-out (2026-07-18): unit tests wrap this script around
   # deliberately-failing fixture commands (t-fail, t.bad, exit 7), and the topic-file fallback below
   # meant every test run PAGED Stuart's real phone — 16+ fixture pages in one morning, indistinguishable
   # from real job failures. Tests set NTFY_TOPIC="" and stay silent; production (unset) still falls
-  # through to the topic file.
-  if [ "${NTFY_TOPIC+set}" = "set" ] && [ -z "$NTFY_TOPIC" ]; then return 0; fi
+  # through to the topic file. An opt-out is NOT a delivered page: it returns 2 and the receipt records
+  # "paged":"disabled", never true (4.7.21).
+  if [ "${NTFY_TOPIC+set}" = "set" ] && [ -z "$NTFY_TOPIC" ]; then return 2; fi
   topic="${NTFY_TOPIC:-}"
   [ -z "$topic" ] && [ -f "$HOME/.cache/ruvnet-brain/ntfy-topic" ] && topic="$(cat "$HOME/.cache/ruvnet-brain/ntfy-topic")"
   [ -z "$topic" ] && return 1
   # --fail: an HTTP error is a failed delivery. The caller records whether the page landed, so a page that
   # never arrived is retried on the next run instead of muting the whole failing streak (review 2026-10-25).
-  curl -sS --fail -m 10 -H "Title: $1" -H "Priority: $3" -H "Tags: ${4:-rotating_light}" -d "$2" "https://ntfy.sh/$topic" >/dev/null 2>&1
+  curl -sS --fail -m 10 -H "Title: $1" -H "Priority: $3" -H "Tags: ${4:-rotating_light}" -d "$2" "${NTFY_URL:-https://ntfy.sh}/$topic" >/dev/null 2>&1
 }
 
 # The run_id currently on disk for this label, or empty if the receipt is missing/unreadable/has
@@ -112,8 +129,10 @@ finish() {
   timed_out=0
   if [ -f "$HB.timeout-$RUN_ID" ]; then
     # Anything the overrunning job left behind (started during its TERM handling, say) goes now.
-    timed_out=1; stop_job; rm -f "$HB.timeout-$RUN_ID"
+    timed_out=1; stop_job
   fi
+  # Always, on every exit path: the timer may have written the marker after the check above (4.7.21).
+  rm -f "$HB.timeout-$RUN_ID"
   # An overrun is a failure however the job chose to exit on TERM, including 0 and 75 (the skip code), so this
   # comes before the skip branch (GPT-6.1 review round 2).
   [ "$timed_out" -eq 1 ] && [ "$code" -le 128 ] && code=143
@@ -152,28 +171,44 @@ finish() {
   # PAGE ON THE TRANSITION, NOT ON EVERY RUN (owner, 2026-10-25: 10,747 notifications on one topic). A job that
   # starts failing pages once, urgently, while it is still tonight's problem; while it KEEPS failing it stays
   # quiet (failing_since carries the first failure; the nightly watchdog's digest still lists it); the run
-  # that passes again sends one low-priority "recovered" note. The previous run's state comes from PREV_HB.
-  prev_state="$(printf '%s' "$PREV_HB" | sed -n 's/.*"state":"\([^"]*\)".*/\1/p' | head -1)"
-  prev_since="$(printf '%s' "$PREV_HB" | sed -n 's/.*"failing_since":"\([^"]*\)".*/\1/p' | head -1)"
-  was_failing=0; case "$prev_state" in failed|killed) was_failing=1 ;; esac
-  # A failing streak counts as already paged only if that page was delivered ("paged":false = retry it).
-  # Only a page PROVEN delivered ("paged":true) keeps the streak quiet; a receipt from before this field existed
-  # counts as unknown and is paged once more (review round 2).
-  prev_unpaged=1; case "$PREV_HB" in *'"paged":true'*) prev_unpaged=0 ;; esac
+  # that passes again sends one low-priority "recovered" note — only if that streak was actually paged.
+  # FLAP DAMPING (4.7.21): a NEW streak within 6 h of the last delivered page is recorded "paged":"suppressed"
+  # instead of paging (4 fail/ok cycles were 8 notifications). A suppressed streak still failing after 6 h pages.
+  # A prior "running" receipt that carries failing_since (a SIGKILLed run) continues its streak.
+  was_failing=0
+  case "$prev_state" in failed|killed) was_failing=1 ;; running) [ -n "$prev_since" ] && was_failing=1 ;; esac
+  # A failing streak counts as already paged only if that page was PROVEN delivered ("paged":true). false (retry),
+  # "suppressed", "disabled", or a receipt from before this field existed are paged (again) when allowed.
+  prev_unpaged=1; [ "$prev_paged" = "true" ] && prev_unpaged=0
+  QUIET_SECONDS=21600
+  now_epoch="$(date +%s)"
+  page_epoch="$prev_page_epoch"; page_at="$prev_page_at"
   since=""
   if [ "$code" -ne 0 ]; then
     if [ "$was_failing" -eq 1 ] && [ -n "$prev_since" ]; then since="$prev_since"; else since="$STARTED"; fi
     extra="$extra,\"failing_since\":\"$since\""
   fi
   if [ "$code" -ne 0 ] && { [ "$was_failing" -eq 0 ] || [ "$prev_unpaged" -eq 1 ]; }; then
-    reason="exit $code after ${dur}s"; [ "$timed_out" -eq 1 ] && reason="stopped after running past its ${MAX_SECONDS}s limit"
-    if notify "🔴 SCHEDULED JOB FAILED: $LABEL" "$reason — see the job's log. Receipt: $HB. Further failures stay quiet until it recovers." "urgent"; then
-      extra="$extra,\"paged\":true"; else extra="$extra,\"paged\":false"; fi
+    if [ -n "$prev_page_epoch" ] && [ $((now_epoch - prev_page_epoch)) -lt "$QUIET_SECONDS" ] \
+       && ! { [ "$was_failing" -eq 1 ] && [ "$prev_paged" = "false" ]; }; then
+      # Inside the quiet window. (A streak whose own page simply failed to deliver is retried, not damped.)
+      extra="$extra,\"paged\":\"suppressed\""
+    else
+      reason="exit $code after ${dur}s"; [ "$timed_out" -eq 1 ] && reason="stopped after running past its ${MAX_SECONDS}s limit"
+      notify "SCHEDULED JOB FAILED: $LABEL" "$reason — see the job's log. Receipt: $HB. Further failures stay quiet until it recovers." "urgent"
+      rc=$?
+      if [ "$rc" -eq 0 ]; then
+        extra="$extra,\"paged\":true"; page_epoch="$now_epoch"; page_at="$(ts)"
+      elif [ "$rc" -eq 2 ]; then extra="$extra,\"paged\":\"disabled\""
+      else extra="$extra,\"paged\":false"; fi
+    fi
   elif [ "$code" -ne 0 ]; then
     extra="$extra,\"paged\":true"
-  elif [ "$was_failing" -eq 1 ]; then
-    notify "✅ Recovered: $LABEL" "passed again after failing since ${prev_since:-an earlier run}" "low" "white_check_mark" || true
+  elif [ "$was_failing" -eq 1 ] && [ "$prev_paged" = "true" ]; then
+    notify "Recovered: $LABEL" "passed again after failing since ${prev_since:-an earlier run}" "low" "white_check_mark" || true
   fi
+  [ -n "$page_epoch" ] && extra="$extra,\"last_page_epoch\":$page_epoch"
+  [ -n "$page_at" ] && extra="$extra,\"last_page_at\":\"$page_at\""
   write_receipt "{\"label\":\"$LABEL\",\"started_at\":\"$STARTED\",\"ended_at\":\"$ended\",\"state\":\"$state\",\"exit_code\":$code,\"duration_sec\":$dur,\"run_id\":\"$RUN_ID\"$extra}"
   exit "$code"
 }

package/scripts/key-canary.mjs

@@ -53,10 +53,14 @@ async function probe(p, key) {
   }
 }
 
+/** true only when notify.sh reports a delivered page (exit 0). A failed or opted-out page (NTFY_TOPIC="") is not
+ *  delivered, so the key's previous state is kept and the transition fires again next run (4.7.21). Titles are
+ *  plain ASCII; the emoji rides in Tags. */
 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 */ }
+    return true;
+  } catch { return false; /* notification failure must not break the canary */ }
 }
 
 const prev = (() => { try { return JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return {}; } })();
@@ -73,13 +77,15 @@ for (const p of PROBES) {
   if (status === 'DEAD') {
     anyDead = true;
     if (NOTIFY && prev[p.env]?.status !== 'DEAD') {
-      notify(`🚨 ${p.provider} API key is DEAD`,
+      const sent = 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');
+      if (!sent) now[p.env] = prev[p.env] ?? { status: 'unpaged', ts: now[p.env].ts };
     }
   } 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');
+    const sent = notify(`${p.provider} API key recovered`, `${p.env} is working again.`, 'default', 'white_check_mark,key');
+    if (!sent) now[p.env] = prev[p.env];
   }
 }
 

package/scripts/latency-to-surface.mjs

@@ -43,6 +43,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HOME = os.homedir();
 
@@ -206,7 +207,7 @@ export function humanMs(ms) {
 }
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────────────────
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   const { loadOutcomes } = await import('./advocacy-outcomes.mjs');
   const rows = computeLatencies({ outcomes: loadOutcomes() });
   const s = summarize(rows);