ruvnet-brain 4.3.20 → 4.3.25

package/scripts/github-health-watch.mjs

@@ -24,6 +24,7 @@
  *   node scripts/github-health-watch.mjs --json     # machine-readable, for hooks/CI
  */
 import { execFileSync } from 'node:child_process';
+import { describeLatestPointer, latestCodeReleaseTag } from './release-channel-kind.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const JSON_OUT = process.argv.includes('--json');
@@ -92,12 +93,21 @@ const npmLatest = (() => {
   try { return execFileSync('npm', ['view', 'ruvnet-brain', 'dist-tags.latest'], { encoding: 'utf8', timeout: 60_000 }).trim(); }
   catch { return null; }
 })();
-const release = ghJson(['api', `repos/${REPO}/releases/latest`, '--jq', '.tag_name']);
+// ADR-086 S1: `releases/latest` is the customer download pointer and is a corpus generation on any
+// night a corpus round shipped. A `corpus-sha256-<digest>` tag can NEVER equal an npm semver, so
+// comparing against it would fire "issue #77 recurring" every single night, for a healthy system —
+// a false alarm that trains the owner to ignore the one alert that matters.
+const releases = ghJson(['api', `repos/${REPO}/releases?per_page=30`]);
+const release = latestCodeReleaseTag(releases);
+const latestPointer = (Array.isArray(releases) ? releases.find((row) => row && !row.draft) : null)?.tag_name || null;
 if (npmLatest && typeof release === 'string' && release) {
   if (npmLatest !== release.replace(/^v/, '')) {
-    note('fail', 'surfaces', `npm ${npmLatest} != GitHub ${release}`,
+    note('fail', 'surfaces', `npm ${npmLatest} != GitHub code release ${release}`,
       'run scripts/published-surface-probe.mjs; this is issue #77 recurring');
   }
+} else if (npmLatest && latestPointer) {
+  note('warn', 'surfaces', `no semver-tagged GitHub release found (${describeLatestPointer(latestPointer)})`,
+    'npm-to-GitHub coherence could not be proven; check the release list by hand');
 }
 
 // ── 6. Issues past their response SLA. ──────────────────────────────────────────────────────────

package/scripts/handoff-asset.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/** Copy a generated asset from a tunneled host to a user's client Downloads folder. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const assetArg = args.find((arg) => arg.startsWith('--asset='));
+const client = (args.find((arg) => arg.startsWith('--client='))?.slice(9) || 'm4').toLowerCase();
+const clients = {
+  m4: 'stuartkerr@100.95.179.114',
+  air: 'macbook-air',
+};
+const host = args.find((arg) => arg.startsWith('--host='))?.slice(7) || clients[client];
+const remoteDir = args.find((arg) => arg.startsWith('--remote-dir='))?.slice(13) || '/Users/stuartkerr/Downloads';
+if (!assetArg || args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: node scripts/handoff-asset.mjs --asset=/absolute/path/to/file [--client=m4|air] [--host=user@client] [--remote-dir=/Users/user/Downloads]');
+  process.exit(assetArg ? 0 : 2);
+}
+if (!host) { console.error(`Unknown client '${client}'. Use --client=m4, --client=air, or an explicit --host.`); process.exit(2); }
+const asset = path.resolve(assetArg.slice(8));
+if (!existsSync(asset)) { console.error(`Asset does not exist: ${asset}`); process.exit(2); }
+const filename = path.basename(asset);
+const localHash = createHash('sha256').update(readFileSync(asset)).digest('hex');
+const copy = spawnSync('scp', ['-q', asset, `${host}:${remoteDir}/${filename}`], { encoding: 'utf8' });
+if (copy.status !== 0) { console.error(copy.stderr || `scp failed with exit ${copy.status}`); process.exit(copy.status || 1); }
+const verify = spawnSync('ssh', ['-o', 'BatchMode=yes', host, `shasum -a 256 ${JSON.stringify(`${remoteDir}/${filename}`)}`], { encoding: 'utf8' });
+const remoteHash = verify.stdout.trim().split(/\s+/)[0];
+if (verify.status !== 0 || remoteHash !== localHash) {
+  console.error(`Checksum verification failed for ${filename}: local=${localHash} remote=${remoteHash || 'unavailable'}`);
+  process.exit(1);
+}
+console.log(JSON.stringify({ host, path: `${remoteDir}/${filename}`, sha256: localHash, verified: true }, null, 2));

package/scripts/hook-retirement-check.mjs

@@ -2,6 +2,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { automaticHookRetirementStatus } from '../bin/install.mjs';
+import { continuityRegistrations } from '../plugin/scripts/continuity-hook-policy.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -13,7 +14,13 @@ export function main() {
     for (const item of result.registrations) console.error(`  ${item.file} ${item.event}: ${item.command || '(empty command)'}`);
     return 1;
   }
-  console.log(`hook-policy-check: PASS — continuity-only lifecycle plane (SessionStart + guarded Stop); all legacy Brain gates retired across ${result.files.length} source, contract, and host-pointer surfaces`);
+  // NAME THE PLANE, don't describe it from memory. The previous line said "SessionStart + guarded
+  // Stop" and kept saying it after the plane changed — a green check that describes the wrong
+  // system is worse than no check, because it is the thing people read instead of the manifest.
+  const plane = continuityRegistrations()
+    .map((spec) => `${spec.event}:${spec.id}[${spec.hosts.join('+')}]`).join(' ');
+  console.log(`hook-policy-check: PASS — continuity-only lifecycle plane (${plane});`
+    + ` all legacy Brain gates retired across ${result.files.length} source, contract, and host-pointer surfaces`);
   return 0;
 }
 

package/scripts/host-registry.mjs

@@ -115,4 +115,4 @@ export function main(args = process.argv.slice(2)) {
   }
 }
 
-if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) process.exitCode = main();
+if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) process.exitCode = main();

package/scripts/ingest-gists.mjs

@@ -13,24 +13,37 @@
 // KB already stamps `ADR STATUS: PROPOSED` onto ADR passages. Retrieval then hands the model the
 // claim AND its epistemic status together; they cannot be separated downstream.
 //
-//   node scripts/ingest-gists.mjs                    # incremental (only re-fetch changed gists)
-//   node scripts/ingest-gists.mjs --full             # ignore the cache, refetch everything
+// STEP 2 (2026-09-13): this file no longer owns its own fetch+write+chunk logic. Actual content
+// ingestion routes through the one canonical pipeline (gist-receipts.mjs's captureGistSources ->
+// buildGistAggregate), the same producer corpus-reconcile.mjs and seal-gist-receipt.mjs use. This
+// file's own job is now just: (1) the cheap human-index/discovery operation (--index-only,
+// --dry-run — pure listing, no per-gist fetch), and (2) deciding WHEN to invoke the canonical
+// pipeline and with what local capture cache, never re-rendering a passage itself.
+//
+//   node scripts/ingest-gists.mjs                    # incremental (only re-fetches changed gists)
+//   node scripts/ingest-gists.mjs --full             # ignore the local capture cache, refetch everything
 //   node scripts/ingest-gists.mjs --owner ruvnet     # default owner
 //   node scripts/ingest-gists.mjs --dry-run          # list what would change, write nothing
 //
-// Then embed (the store becomes searchable with no restart — forge-ask-all discovers *.rvf at query
-// time):
+// Embedding is a SEPARATE step (this file never builds vectors — nightly-gists.sh's own sharded
+// `forge-big.mjs shard-all` does, after this exits 0 with real changes):
 //   node kb/forge-big.mjs both --dir kb --name ruv-gists
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { digest } from './coverage-integrity.mjs';
+import { buildGistAggregate, captureGistSources } from './gist-receipts.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
 const NAME = 'ruv-gists';
-const CACHE = path.join(KB, `.${NAME}.cache.json`);
+// The RESUMABLE capture cache (raw body text included) -- kept in the preparation workspace (kb/,
+// this job's own working directory) and NEVER published: build-bundle.mjs only ever ships named,
+// non-dotfile artifacts. It is purely an optimization; a missing or `--full`-ignored cache just
+// means every currently-listed gist is treated as changed and refetched.
+const CAPTURE_CACHE = path.join(KB, `.${NAME}.capture-cache.json`);
 
 const argv = process.argv.slice(2);
 const arg = (f, d = null) => { const i = argv.indexOf(f); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
@@ -44,10 +57,6 @@ const INDEX_ONLY = argv.includes('--index-only');
 const INDEX_PATH = path.join(ROOT, 'docs', 'RUV-GISTS.md');
 const FETCH_TIMEOUT_MS = Number(process.env.RUVNET_GISTS_FETCH_TIMEOUT_MS || 30_000);
 
-// Markdown/text only. A gist's code files are better read from the repo they land in; prose is the
-// thing repos don't carry.
-const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.rst']);
-
 /** Authenticated GitHub calls via `gh` — 5000 req/hr instead of 60, and no token handling here. */
 function gh(endpointArgs) {
   const r = spawnSync('gh', endpointArgs, {
@@ -102,31 +111,6 @@ async function listGistsPublic(owner) {
   return all;
 }
 
-/** Raw file bodies. The list endpoint truncates `content`, so fetch each gist individually. */
-function fetchGist(id) {
-  return JSON.parse(gh(['api', `gists/${id}`]));
-}
-
-// ~3200-char paragraph-aligned chunks — same shape build-concepts.mjs uses, so the reader's chunk
-// handling and the `#N` suffix convention stay uniform across stores.
-function chunk(text, size = 3200) {
-  const out = [];
-  let buf = '';
-  for (const para of text.split(/\n\n+/)) {
-    if (buf && buf.length + para.length + 2 > size) { out.push(buf); buf = ''; }
-    buf = buf ? `${buf}\n\n${para}` : para;
-  }
-  if (buf.trim()) out.push(buf);
-  return out.length ? out : [];
-}
-
-/** The banner that travels WITH the text, so a retrieval hit can never lose its provenance. */
-const banner = (g, file) =>
-  `SOURCE: GitHub gist by @${OWNER} — "${(g.description || file).replace(/\s+/g, ' ').trim().slice(0, 160)}"\n` +
-  `GIST STATUS: rUv's own notes / release announcement — may describe PROPOSED or UNRELEASED work.\n` +
-  `Treat as intent, not as confirmed shipped behavior: verify against repo source before asserting.\n` +
-  `updated: ${g.updated_at?.slice(0, 10)} · https://gist.github.com/${OWNER}/${g.id}\n\n`;
-
 /** A tiny, git-trackable feed of what rUv has published, newest first. Costs ~5 API calls. */
 function writeIndex(gists) {
   const rows = [...gists].sort((a, b) => b.updated_at.localeCompare(a.updated_at));
@@ -153,10 +137,20 @@ function writeIndex(gists) {
   console.log(`  wrote ${path.relative(ROOT, INDEX_PATH)} (${rows.length} rows)`);
 }
 
+function loadCaptureCache() {
+  if (FULL || !fs.existsSync(CAPTURE_CACHE)) return null;
+  try { return JSON.parse(fs.readFileSync(CAPTURE_CACHE, 'utf8')); }
+  catch { return null; } // a corrupt local cache is a MISS, never a crash — everything refetches.
+}
+
+function saveCaptureCache(captured) {
+  try { fs.writeFileSync(CAPTURE_CACHE, JSON.stringify(captured)); }
+  catch (error) { console.error(`  note: could not persist the local capture cache (${error.message})`); }
+}
+
 async function main() {
   if (!fs.existsSync(KB)) { console.error(`ingest-gists: no kb dir at ${KB}`); process.exit(2); }
 
-  const cache = !FULL && fs.existsSync(CACHE) ? JSON.parse(fs.readFileSync(CACHE, 'utf8')) : {};
   console.log(`ingest-gists: listing public gists for @${OWNER}…`);
   let gists;
   try {
@@ -174,7 +168,20 @@ async function main() {
 
   if (INDEX_ONLY) { writeIndex(gists); return; }
 
-  const changed = gists.filter((g) => cache[g.id] !== g.updated_at);
+  // "changed" is computed against the ONE canonical schema-3 receipt (kb/ruv-gists.sources.json) —
+  // never a private cache file's idea of the truth. Absent/unreadable/pre-schema-3 reads as "nothing
+  // known yet", so every listed gist counts as changed (a correct, if conservative, first run).
+  const receiptFile = path.join(KB, `${NAME}.sources.json`);
+  let knownUpdatedAt = new Map();
+  if (!FULL && fs.existsSync(receiptFile)) {
+    try {
+      const receipt = JSON.parse(fs.readFileSync(receiptFile, 'utf8'));
+      if (receipt.schemaVersion === 3) {
+        knownUpdatedAt = new Map(Object.entries(receipt.gists || {}).map(([id, row]) => [id, row.updatedAt]));
+      }
+    } catch { /* treat as "nothing known yet" */ }
+  }
+  const changed = gists.filter((g) => knownUpdatedAt.get(g.id) !== g.updated_at);
   console.log(`  ${changed.length} new or updated since last run${FULL ? ' (--full: cache ignored)' : ''}`);
   if (DRY) {
     for (const g of changed.slice(0, 20)) console.log(`    ${g.updated_at.slice(0, 10)}  ${Object.keys(g.files)[0]}`);
@@ -186,73 +193,39 @@ async function main() {
     return;
   }
 
-  // Full rebuild of the passage file (ids must stay dense and aligned with the .rvf idmap; a
-  // partial append would desynchronise them — the failure mode that maps a vector to the wrong text).
-  const passages = [];
-  const entries = {};
-  let id = 0;
-  let files = 0;
-  let skipped = 0;
-
-  for (const [i, stub] of gists.entries()) {
-    if (i % 25 === 0) process.stdout.write(`\r  fetching ${i}/${gists.length}…`);
-    let g;
-    try {
-      g = fetchGist(stub.id);
-    } catch (err) {
-      skipped++;
-      console.error(`\n  fetch failed for gist ${stub.id}: ${err.message}`);
-      continue;
-    }
-    for (const [fname, f] of Object.entries(g.files || {})) {
-      if (!TEXT_EXT.has(path.extname(fname).toLowerCase())) continue;
-      // JSONL readers treat U+2028/U+2029 as physical line separators on some runtimes. Normalize
-      // them before serialization so one JSON object always remains one physical passage line.
-      const body = (f.truncated && f.raw_url ? '' : (f.content || '')).replace(/[\u2028\u2029]/g, '\n');
-      if (!body.trim()) {
-        skipped++;
-        console.error(`\n  empty or truncated text file: ${stub.id}/${fname}`);
-        continue;
-      }
-      const title = (g.description || fname).replace(/\s+/g, ' ').trim().slice(0, 180) || fname;
-      const head = banner(g, fname);
-      // Banner on EVERY chunk, not just the first. Retrieval returns ONE chunk — if the provenance
-      // lives only in chunk 0, then chunk 2 reaches the model as an unlabelled assertion, which is
-      // exactly the fence this file claims to build. (Caught by reading a real retrieval: the top
-      // hit for "enable the flywheel" was `…flywheel.md#2` and carried no status line.)
-      const chunks = chunk(body);
-      chunks.forEach((c, ci) => {
-        const sid = String(id++);
-        const p = `${g.id.slice(0, 8)}/${fname}${chunks.length > 1 ? `#${ci}` : ''}`;
-        const text = head + c;
-        passages.push({ id: sid, text, path: p, title });
-        entries[sid] = { path: p, kind: 'doc', title, chunk: ci, preview: text.slice(0, 200) };
-      });
-      files++;
-    }
-    cache[stub.id] = stub.updated_at;
-  }
-  process.stdout.write('\r');
-
-  // A receipt-only or partial corpus is more dangerous than a failed run: its RVF idmap can look
-  // healthy while silently omitting live source. Preserve the previous complete corpus and make
-  // the nightly job retry instead of publishing incomplete search data.
-  if (skipped > 0) {
-    throw new Error(`ingest-gists: refusing to write partial corpus (${skipped} fetch/content failures)`);
+  const observedAt = new Date().toISOString();
+  const rows = gists.map((g) => ({ id: g.id, updated_at: g.updated_at, files: g.files }));
+  const observation = {
+    owner: OWNER, observedAt,
+    observationSha256: digest({ owner: OWNER, rows: rows.map(({ id, updated_at }) => ({ id, updated_at })) }),
+    gists: { rows },
+  };
+  const now = () => observedAt;
+
+  // Capture once ourselves (reusing the local body-bearing cache for anything unchanged) so we have
+  // real raw bytes to persist for NEXT run's reuse. Handing that same captured set to
+  // buildGistAggregate as ITS cache means its own internal capture pass is a 100%-reuse, zero-network
+  // pass — this file still routes every byte through the one canonical pipeline, it just does not
+  // throw away the bytes it already paid to fetch.
+  const priorCache = loadCaptureCache();
+  const captured = await captureGistSources({ observation, cache: priorCache, now });
+  // Embedding is deliberately NOT done here (buildVector: null) — nightly-gists.sh's own sharded
+  // `forge-big.mjs shard-all` embeds afterward, only when this process reports real changes; see the
+  // module header. generation stays null and RVF-GENERATIONS.json is left untouched.
+  const result = await buildGistAggregate({ observation, cache: captured, outDir: KB, buildVector: null, now });
+  saveCaptureCache(captured);
+
+  if (result.omitted) {
+    console.log(`ingest-gists: @${OWNER} currently has zero public gists — aggregate omitted, nothing ingested.`);
+    writeIndex(gists);
+    return;
   }
-
-  fs.writeFileSync(path.join(KB, `${NAME}.passages.jsonl`), passages.map((p) => JSON.stringify(p)).join('\n') + '\n');
-  fs.writeFileSync(path.join(KB, `${NAME}.meta.json`), JSON.stringify({
-    model: NAME, dimensions: 0, metric: 'cosine', name: NAME,
-    generated: new Date().toISOString(), repo: `gists/${OWNER}`,
-    note: "rUv's public gists — announcements and thinking, PROPOSED unless confirmed in repo source.",
-    entries,
-  }, null, 2));
-  fs.writeFileSync(CACHE, JSON.stringify(cache, null, 2));
-
-  console.log(`ingest-gists: ${gists.length} gists · ${files} text files · ${passages.length} passages · ${skipped} skipped`);
+  // Report OUR OWN capture pass's reuseEvidence, not buildGistAggregate's internal one -- the latter
+  // is a 100%-reuse pass by construction (it is handed the set WE just captured) and would always
+  // read "reused N, fetched 0" regardless of how much real network work just happened.
+  console.log(`ingest-gists: ${gists.length} gists · reused ${captured.reuseEvidence.reused.length} · fetched ${captured.reuseEvidence.fetched.length} fresh`);
   writeIndex(gists);
-  console.log(`  wrote kb/${NAME}.passages.jsonl + kb/${NAME}.meta.json`);
+  console.log(`  wrote kb/${NAME}.passages.jsonl + kb/${NAME}.meta.json + kb/${NAME}.sources.json`);
   console.log(`  next: node kb/forge-big.mjs both --dir kb --name ${NAME}   (embed → ${NAME}.big.rvf)`);
 }
 

package/scripts/job-heartbeat.sh

@@ -6,16 +6,41 @@
 # identical to one that ran and succeeded. That ambiguity let com.ruvnet.brain-nightly sit unfired
 # and look healthy. Per-job good intentions rot; a wrapper cannot forget.
 #
+# WHY THE WRAPPER, NOT THE CHILD, WRITES THE TERMINAL RECORD (2026-09-11 review correction): a
+# SIGKILLed child cannot write its own outcome — no handler runs, by definition. So this script never
+# asks the wrapped command to self-report; the WRAPPER is the supervisor. It writes "running" before
+# the child starts, watches it via `wait`, and derives the terminal record (ok / failed / killed)
+# from the child's OWN wait status — the one piece of truth a dying child cannot fake or withhold.
+#
 # Usage (from a LaunchAgent's ProgramArguments):
 #   /bin/sh /path/to/job-heartbeat.sh <label> -- <command> [args...]
 #
 # Guarantees:
-#   1. A "start" receipt is written BEFORE the command runs.
-#   2. An "end" receipt with the REAL exit code is written even if the command dies, is killed, or
-#      the machine yanks it away — the trap fires on EXIT/INT/TERM. There is no silent death.
-#   3. A non-zero exit pushes an URGENT ntfy alert immediately (topic: $NTFY_TOPIC, or the file
+#   1. A "start" receipt is written BEFORE the command runs, carrying a `run_id` unique to THIS
+#      invocation (pid + start-epoch). A second, concurrent invocation for the same label gets its
+#      own run_id and overwrites the "running" record with its own — see the STALE WRITER GUARD
+#      below for what that means for the terminal write.
+#   2. A terminal receipt is written even if the command dies, is killed, or the machine yanks it
+#      away — the trap fires on EXIT/INT/TERM. Its `state` is one of:
+#        ok      — exited zero.
+#        failed  — exited non-zero, NOT via a signal (POSIX: an exit code in 1..128).
+#        killed  — died to a signal (POSIX: `wait` reports 128+signal for a signal-killed child, and
+#                  the two in-wrapper traps below reuse that exact convention for TERM/INT delivered
+#                  to the WRAPPER itself). The signal number is carried as `"signal"`.
+#      SIGKILL (-9) of the WRAPPER itself is the one death nothing here can catch — no handler runs,
+#      the receipt is left stuck at "running" with its run_id, and that is deliberately NOT
+#      "fixed" here: scripts/nightly-watchdog.mjs already derives FAILING from a stale receipt whose
+#      pid no longer exists (see its `judge()` — this is the "started and never finished" case,
+#      because a run_id can never reach a terminal state if nothing survived to write one).
+#   3. STALE WRITER GUARD: before writing the terminal record, the wrapper re-reads the on-disk
+#      receipt's run_id. If some OTHER, newer invocation has since overwritten it (a different
+#      run_id — meaning a fresh "running" record was written after this one), this process's
+#      terminal write is REFUSED. An old, dying writer must never clobber a newer run's evidence
+#      with its own stale outcome; the newer run owns the receipt and will write its own terminal
+#      record when it finishes.
+#   4. A non-zero exit pushes an URGENT ntfy alert immediately (topic: $NTFY_TOPIC, or the file
 #      ~/.cache/ruvnet-brain/ntfy-topic). No topic = no push, but the receipt is still written.
-#   4. The wrapper's own exit code is the job's exit code — launchd still sees the truth.
+#   5. The wrapper's own exit code is the job's exit code — launchd still sees the truth.
 
 set -u
 
@@ -28,9 +53,23 @@ HB_DIR="${JOB_HEARTBEAT_DIR:-$HOME/.cache/ruvnet-brain/heartbeats}"
 mkdir -p "$HB_DIR"
 HB="$HB_DIR/$LABEL.json"
 
+# Atomic write: tmp file (same filesystem) + rename. `cat > "$HB"` directly would let a concurrent
+# reader (nightly-watchdog.mjs, or another job-heartbeat.sh instance's stale-writer check) observe a
+# half-written file mid-write and fail to parse it — a real, if rare, race under load. `mv` on the
+# same filesystem is a single rename() syscall: readers see either the old content or the new, never
+# a partial file.
+write_receipt() { # write_receipt <content>
+  tmp="$HB.tmp-$$"
+  printf '%s' "$1" > "$tmp" && mv -f "$tmp" "$HB"
+}
+
 ts() { date -u +%Y-%m-%dT%H:%M:%SZ; }
 STARTED="$(ts)"
 START_EPOCH="$(date +%s)"
+# RUN_ID: pid + start-epoch-second. Unique enough to tell "this invocation" apart from any other
+# invocation of the SAME label that might be alive at the same time — a second's collision would
+# also require a recycled pid inside that same second, which the OS does not do.
+RUN_ID="$$-$START_EPOCH"
 
 # F3 (2026-07-18): remember the receipt as it was BEFORE this fire. A skip-fire (exit 75, the
 # reserved "another instance is already running" code) must not destroy the live run's evidence —
@@ -42,9 +81,7 @@ PREV_HB=""
 
 # 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.
-cat > "$HB" <<EOF
-{"label":"$LABEL","started_at":"$STARTED","state":"running","pid":$$,"command":"$(echo "$@" | sed 's/"/\\"/g')"}
-EOF
+write_receipt "{\"label\":\"$LABEL\",\"started_at\":\"$STARTED\",\"state\":\"running\",\"pid\":$$,\"run_id\":\"$RUN_ID\",\"command\":\"$(echo "$@" | sed 's/"/\\"/g')\"}"
 
 notify() { # notify <title> <body> <priority>
   # NTFY_TOPIC set-but-EMPTY is an explicit opt-out (2026-07-18): unit tests wrap this script around
@@ -59,6 +96,12 @@ notify() { # notify <title> <body> <priority>
   curl -sS -m 10 -H "Title: $1" -H "Priority: $3" -H "Tags: rotating_light" -d "$2" "https://ntfy.sh/$topic" >/dev/null 2>&1 || true
 }
 
+# The run_id currently on disk for this label, or empty if the receipt is missing/unreadable/has
+# none (an old receipt written before this field existed). No jq dependency — one anchored sed.
+current_run_id() {
+  sed -n 's/.*"run_id":"\([^"]*\)".*/\1/p' "$HB" 2>/dev/null | head -1
+}
+
 finish() {
   code=${FORCED_CODE:-$?}
   ended="$(ts)"
@@ -67,15 +110,32 @@ finish() {
   # survives; report 0 to launchd (a skip is not a failure). If no receipt ever existed, record an
   # honest "skipped" — which the watchdog treats as NOT proof of a real run.
   if [ "$code" -eq 75 ]; then
-    if [ -n "$PREV_HB" ]; then printf '%s' "$PREV_HB" > "$HB"; else
-      printf '{"label":"%s","started_at":"%s","ended_at":"%s","state":"skipped","duration_sec":%s}' "$LABEL" "$STARTED" "$ended" "$dur" > "$HB"
+    if [ -n "$PREV_HB" ]; then write_receipt "$PREV_HB"; else
+      write_receipt "$(printf '{"label":"%s","started_at":"%s","ended_at":"%s","state":"skipped","duration_sec":%s,"run_id":"%s"}' "$LABEL" "$STARTED" "$ended" "$dur" "$RUN_ID")"
     fi
     exit 0
   fi
-  if [ "$code" -eq 0 ]; then state="ok"; else state="failed"; fi
-  cat > "$HB" <<EOF
-{"label":"$LABEL","started_at":"$STARTED","ended_at":"$ended","state":"$state","exit_code":$code,"duration_sec":$dur}
-EOF
+  # STALE WRITER GUARD: a newer invocation for this same label may have already taken the receipt
+  # over (its own "running" record carries a DIFFERENT run_id). If so, this process's outcome is
+  # stale — it must not overwrite evidence that belongs to a run that is still, or already, ahead of
+  # it. Say so on stderr (so it is not a silent no-op) and exit with the real code regardless.
+  ON_DISK_RUN_ID="$(current_run_id)"
+  if [ -n "$ON_DISK_RUN_ID" ] && [ "$ON_DISK_RUN_ID" != "$RUN_ID" ]; then
+    echo "job-heartbeat: $LABEL receipt now belongs to run $ON_DISK_RUN_ID — not overwriting it with stale run $RUN_ID (exit $code)" >&2
+    exit "$code"
+  fi
+  # Derive ok / failed / killed from the CHILD'S OWN wait status, never from anything the child said
+  # about itself. POSIX: a process terminated by signal N is reported by `wait`/`$?` as 128+N — the
+  # same convention this wrapper's own TERM/INT traps below use when THEY are what killed the child.
+  if [ "$code" -eq 0 ]; then
+    state="ok"; extra=""
+  elif [ "$code" -gt 128 ]; then
+    sig=$((code - 128))
+    state="killed"; extra=",\"signal\":$sig"
+  else
+    state="failed"; extra=""
+  fi
+  write_receipt "{\"label\":\"$LABEL\",\"started_at\":\"$STARTED\",\"ended_at\":\"$ended\",\"state\":\"$state\",\"exit_code\":$code,\"duration_sec\":$dur,\"run_id\":\"$RUN_ID\"$extra}"
   # Gong on failure, immediately — not at the next watchdog sweep. A failing nightly should reach the
   # phone while it is still tonight's problem.
   if [ "$code" -ne 0 ]; then
@@ -85,6 +145,9 @@ EOF
 }
 trap finish EXIT
 # A signal handler must KILL THE CHILD, then exit — letting the EXIT trap write the receipt once.
+# The exit codes (143 = 128+15 TERM, 130 = 128+2 INT) intentionally reuse the same 128+signal
+# convention `wait` uses for a directly-signalled child, so finish() classifies BOTH as "killed"
+# with the right signal number, whether the signal reached the child directly or via this wrapper.
 trap 'FORCED_CODE=143; kill -TERM "$CHILD" 2>/dev/null; exit 143' TERM
 trap 'FORCED_CODE=130; kill -TERM "$CHILD" 2>/dev/null; exit 130' INT
 

package/scripts/learning-replay-execution.mjs

@@ -27,10 +27,15 @@ const MUTATING_SUBCOMMANDS = new Set([
   'backup', 'init', 'configure',
 ]);
 
-function spawnRuflo(bin, args, options) {
+// Every `ruflo` invocation auto-starts a project background daemon unless RUFLO_DAEMON_AUTOSTART=0
+// is set (verified live against the installed CLI: ~/.npm-global/lib/node_modules/ruflo/
+// node_modules/@claude-flow/cli/dist/src/services/daemon-autostart.js:85). Applied here, once, so
+// every caller of spawnRuflo() gets it regardless of whether it passed its own `env`.
+function spawnRuflo(bin, args, options = {}) {
+  const opts = { ...options, env: { ...(options.env || process.env), RUFLO_DAEMON_AUTOSTART: '0' } };
   return /\.[cm]?js$/i.test(bin)
-    ? spawnSync(process.execPath, [bin, ...args], options)
-    : spawnSync(bin, args, options);
+    ? spawnSync(process.execPath, [bin, ...args], opts)
+    : spawnSync(bin, args, opts);
 }
 
 export function assertRetrieved(out) {
@@ -115,7 +120,7 @@ export function executeProducedCommand(cmd, {
     .find((value) => MUTATING_SUBCOMMANDS.has(value));
   if (mutating) return reject(`refused mutating subcommand "${mutating}"`, { argv: ['ruflo', ...args] });
 
-  const env = { ...process.env };
+  const env = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
   delete env.CLAUDE_FLOW_DB_PATH;
   delete env.CLAUDE_FLOW_MEMORY_PATH;
   const result = spawnRuflo(ruflo, args, {
@@ -146,6 +151,7 @@ export function verifyRufloFlag(bin = RUFLO_BIN) {
   const result = spawnSync(bin, ['memory', 'search', '--help'], {
     encoding: 'utf8',
     timeout: 30_000,
+    env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
   });
   const output = `${result.stdout || ''}${result.stderr || ''}`;
   if (result.status !== 0 && !output) return { ok: false, why: `help exited ${result.status} empty` };

package/scripts/nightly-gists.sh

@@ -22,9 +22,27 @@ 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"
 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"
 
 command -v gh >/dev/null 2>&1 || { log "FATAL: gh not on PATH"; exit 1; }
@@ -52,20 +70,16 @@ fi
 # POSIX, so a failed shard was structurally invisible — the script would proceed to ingest and log
 # "done — rebuilt" over a half-embedded corpus. Now every shard PID is waited on individually and a
 # single failure aborts BEFORE ingest, loudly. "done" is only printed over a fully-embedded corpus.
+#
+# 2026-09-11: the manual `&`/`wait` fan-out above (kept in history, replaced below) could not see
+# whether a shard was still doing WORK or just still alive — an 8-shard run once sat at 0% CPU for
+# six hours with every pid alive and no failure ever detected. `forge-big.mjs shard-all` is the
+# supervising "parent embed process": it owns the fan-out itself, reads each shard's per-batch
+# progress file, and SIGTERMs+exits non-zero the moment any shard stops advancing for longer than
+# its stall budget — so a genuine hang aborts in minutes instead of surviving until a human notices.
 log "corpus changed — re-embedding"
-i=0
-pids=""
-while [ "$i" -lt 8 ]; do
-  node kb/forge-big.mjs embed --dir kb --name ruv-gists --shard "$i" --of 8 >>"$LOG" 2>&1 &
-  pids="$pids $!"
-  i=$((i + 1))
-done
-FAILED_SHARDS=0
-for p in $pids; do
-  wait "$p" || FAILED_SHARDS=$((FAILED_SHARDS + 1))
-done
-if [ "$FAILED_SHARDS" -gt 0 ]; then
-  log "EMBED FAILED — $FAILED_SHARDS of 8 shards exited nonzero; refusing to ingest a half-embedded corpus"
+if ! node kb/forge-big.mjs shard-all --dir kb --name ruv-gists --shards 8 --stall-minutes 15 >>"$LOG" 2>&1; then
+  log "EMBED FAILED — shard-all reported a failure or a stall; refusing to ingest a half-embedded corpus"
   exit 1
 fi
 node kb/forge-big.mjs ingest --dir kb --name ruv-gists >>"$LOG" 2>&1 || { log "INGEST FAILED — store NOT rebuilt"; exit 1; }

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

@@ -599,7 +599,7 @@ export async function runNightlyTwoRunProof({ packagePath, bundlePath, out, time
   }
 }
 
-if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) {
   try {
     const args = parseArgs(process.argv.slice(2));
     const receipt = await runNightlyTwoRunProof({ packagePath: args.package, bundlePath: args.bundle, out: args.out,