@bongos/core 1.19.1031 → 1.19.1033

package/scripts/gds/address-park-sweep.sh

@@ -31,7 +31,9 @@ DB="${PGDATABASE:-cloudbongos}"
 CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 case "$CORE_DIR" in */node_modules/@bongos/core) INSTANCE_DIR="${INSTANCE_DIR:-${CORE_DIR%/node_modules/@bongos/core}}" ;; esac
 [ -n "${INSTANCE_DIR:-}" ] || { echo "set INSTANCE_DIR to the control plane's instance checkout — this sweep is not running from one"; exit 1; }
-APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null)}"
+# Owner by name: GNU stat spells it `-c %U`, BSD/macOS stat `-f %Su`, and each refuses the
+# other's flag, so GNU is asked first and BSD answers when it refuses (task 1004170).
+APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null || stat -f %Su "$INSTANCE_DIR" 2>/dev/null)}"
 if [ "$APP_USER" = root ] || ! [[ "$APP_USER" =~ ^[a-z_][a-z0-9_-]{0,31}$ ]]; then
   echo "cannot use '$APP_USER' as the app account — set PROVISION_APP_USER to the unprivileged account that owns $INSTANCE_DIR"; exit 1
 fi

package/scripts/gds/autobongos-run.js

@@ -94,6 +94,56 @@ function logPath() {
   try { return require('../../src/instance-config.js').configPath('autobongos-runs.jsonl'); }
   catch (_) { return path.join(REPO_ROOT, 'autobongos-runs.jsonl'); }
 }
+// countWorkedSince — how many tasks this runner has worked since an epoch-second
+// mark. Reads the run log, because that is the only record that survives a
+// restart, and the cap it feeds has to hold across one (a runner that forgets
+// its count on every crash has no cap at all).
+//
+// BOUNDED ON BOTH AXES, because this runs every iteration of a loop that never
+// exits and the log only grows. It reads the TAIL rather than the file, and it
+// scans BACKWARDS and stops at the first row older than the mark — the rows that
+// can possibly count are the newest ones, so the common case touches a handful
+// of lines whatever the log's size.
+//
+// A torn or missing log counts as zero rather than refusing: the fence and the
+// gauge are the gates, this is a bound on top of them, and a bound that bricks
+// the runner when its own log is unreadable is worse than one that occasionally
+// allows an extra task.
+const WORKED_SCAN_TAIL_BYTES = 1024 * 1024;
+const NEWLINE = String.fromCharCode(10);
+
+function countWorkedSince(sinceEpochS) {
+  if (!Number.isFinite(sinceEpochS) || sinceEpochS <= 0) return 0;
+  let text;
+  try {
+    const p = logPath();
+    const { size } = fs.statSync(p);
+    const from = Math.max(0, size - WORKED_SCAN_TAIL_BYTES);
+    const fd = fs.openSync(p, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(size, WORKED_SCAN_TAIL_BYTES));
+      fs.readSync(fd, buf, 0, buf.length, from);
+      text = buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+    // A tail read can land mid-line; drop the first partial one.
+    if (from > 0) text = text.slice(text.indexOf(NEWLINE) + 1);
+  } catch (_) { return 0; }
+
+  const lines = text.split(NEWLINE);
+  let n = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch (_) { continue; }   // a torn line costs one row, not the count
+    const at = Date.parse(row.at);
+    if (!Number.isFinite(at)) continue;
+    if (at / 1000 < sinceEpochS) break;   // the log is append-ordered: nothing older can count
+    if (row.event === 'worked') n += 1;
+  }
+  return n;
+}
+
 function record(entry) {
   const row = { at: new Date().toISOString(), ...entry };
   try {
@@ -342,6 +392,36 @@ async function iteration(opts, deps = {}) {
     return log({ event: 'hold', go: false, unknown: !!g.decision.unknown, reason: g.decision.reason, sleep_until: g.decision.sleepUntil ?? null });
   }
 
+  // 1b. A DERIVED gauge buys a BOUNDED amount of work (task 1004178).
+  //
+  // `derived` means the last real reading's window had already reset, so the
+  // baseline is a retired observation rather than a measurement. That is sound
+  // for the FIVE-hour window, which turns over during a night. It does nothing
+  // for the SEVEN-day one, which does not — so the weekly pace check, the thing
+  // the module's notes call what actually binds a heavy week, is simply absent
+  // on a derived reading. A stale weekly figure cannot substitute: usage only
+  // grows, so an under-reported value makes the check more permissive, and that
+  // is the wrong direction to be wrong in.
+  //
+  // So the bound is a task count, not a percentage: on one derived window, do
+  // AUTOBONGOS_DERIVED_TASK_CAP tasks and then hold until a real reading exists.
+  // A terminal session writes one; the owner opening a terminal in the morning
+  // is what lifts it. Default 2 — each worker is wall-clock bounded at 90
+  // minutes, so two of them is well inside a five-hour window even at worst, and
+  // the cap only has to be small enough that being wrong is survivable.
+  if (g.decision.derived) {
+    const cap = Number(process.env.AUTOBONGOS_DERIVED_TASK_CAP ?? 2);
+    const since = Number(g.decision.derivedSince) || 0;
+    const done = countWorkedSince(since);
+    if (Number.isFinite(cap) && cap >= 0 && done >= cap) {
+      return log({
+        event: 'hold', go: false, unknown: false, derived: true, worked_since_derived: done,
+        reason: `derived gauge: ${done} task(s) already done since the window reset and the cap is ${cap} — holding for a real reading (a terminal session writes one)`,
+        sleep_until: null,
+      });
+    }
+  }
+
   // 2. Pick — from the ALLOWLISTED goals, never from what the command line asked
   // for. gate.goals is already the intersection.
   const picked = await pick(gate.goals, deps.pickDeps || {});
@@ -798,7 +878,7 @@ if (require.main === module) {
 
 module.exports = {
   readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, resolveWorkerBin,
-  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX,
+  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, countWorkedSince,
   heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
   isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT,
 };

package/scripts/gds/baseline-staleness.js

@@ -40,7 +40,7 @@
 //     anybody's diff. Hard-failing a PR because ambient debt turned eight weeks old
 //     punishes whoever pushed next and gets the gate disabled. The audit asked for
 //     "the repeatable, SCHEDULED version" of its own manual review, and the patrol
-//     is that: history-wide, time-based, filed for adjudication (ADR 0162).
+//     is that: history-wide, time-based, filed for adjudication (ADR 0158 §2).
 //
 // AGE COMES FROM GIT, NOT FROM A STORED TIMESTAMP. A `since:` field in the JSON
 // would be faster and hermetic, and it would also be the thing that silently

package/scripts/gds/db-backup-nightly.sh

@@ -131,7 +131,10 @@ pg_dump \
 # A SIGKILL mid-stream leaves a .partial that the next run will overwrite.
 mv "$OUT.partial" "$OUT"
 
-BYTES=$(stat -c '%s' "$OUT")
+# Size in bytes via POSIX `wc -c`, not `stat -c '%s'`: that is GNU-only, and BSD/macOS
+# stat refuses it outright, so every run on a Mac died here (task 1004170). tr drops the
+# padding BSD wc prints in front of the number.
+BYTES=$(wc -c < "$OUT" | tr -d '[:space:]')
 echo "[$(date -u +%FT%TZ)] gds-db-backup: wrote ${OUT} (${BYTES} bytes)"
 
 # Completeness guard (incident 2026-07-02, task 1711; task 1003925). pipefail already
@@ -190,7 +193,9 @@ ATTACH_OUT="${BACKUP_DIR}/${DB_NAME}-attachments-${TS}.tar.gz"
 ATTACH_GLOB="${DB_NAME}-attachments-${D}${D}${D}${D}-${D}${D}-${D}${D}T${D}${D}${D}${D}${D}${D}Z.tar.gz"
 
 if [ -d "$ATTACH_DIR" ]; then
-  ATTACH_COUNT=$(find "$ATTACH_DIR" -maxdepth 1 -type f | wc -l)
+  # Every count here goes through tr for the same reason as BYTES: BSD wc pads it, which
+  # put "pruned        1 dump(s)" in a Mac's log where Linux writes "pruned 1 dump(s)".
+  ATTACH_COUNT=$(find "$ATTACH_DIR" -maxdepth 1 -type f | wc -l | tr -d '[:space:]')
   if [ "$ATTACH_COUNT" -gt 0 ]; then
     if tar -czf "$ATTACH_OUT.partial" -C "$ATTACH_DIR" . 2>/dev/null; then
       mv "$ATTACH_OUT.partial" "$ATTACH_OUT"
@@ -215,7 +220,7 @@ fi
 PRUNED=$(find "$BACKUP_DIR" -maxdepth 1 -type f \
     \( -name "$DUMP_GLOB" -o -name "$ATTACH_GLOB" \) \
     -mtime +"${RETENTION_DAYS}" \
-    -print -delete | wc -l)
+    -print -delete | wc -l | tr -d '[:space:]')
 
 if [ "$PRUNED" -gt 0 ]; then
   echo "[$(date -u +%FT%TZ)] gds-db-backup: pruned ${PRUNED} dump(s) older than ${RETENTION_DAYS}d"
@@ -223,5 +228,5 @@ fi
 
 # ---- emit a one-line summary for journald + monitoring ---------------------
 
-REMAINING=$(find "$BACKUP_DIR" -maxdepth 1 -type f -name "$DUMP_GLOB" | wc -l)
+REMAINING=$(find "$BACKUP_DIR" -maxdepth 1 -type f -name "$DUMP_GLOB" | wc -l | tr -d '[:space:]')
 echo "[$(date -u +%FT%TZ)] gds-db-backup: ok · ${REMAINING} dump(s) retained · ${BYTES} bytes latest"

package/scripts/gds/db-backup-offsite.sh

@@ -169,7 +169,9 @@ if [ -z "$LATEST" ]; then
 fi
 
 BASENAME=$(basename "$LATEST")
-BYTES=$(stat -c '%s' "$LATEST")
+# Sizes via POSIX `wc -c`, never GNU-only `stat -c '%s'`, which BSD/macOS stat refuses
+# (task 1004170). tr drops the padding BSD wc prints in front of the number.
+BYTES=$(wc -c < "$LATEST" | tr -d '[:space:]')
 
 # ---- encrypt before it leaves the box ---------------------------------------
 #
@@ -189,7 +191,7 @@ fi
 
 # A zero-byte or missing ciphertext would upload happily and restore to nothing.
 # Checked here rather than trusted, because the failure is silent for a month.
-ENC_BYTES=$(stat -c '%s' "$ENC")
+ENC_BYTES=$(wc -c < "$ENC" | tr -d '[:space:]')
 if [ "$ENC_BYTES" -lt 1 ]; then
   echo "ERROR: encryption produced an empty file — refusing to upload it as a backup." >&2
   exit 2

package/scripts/gds/package-core.js

@@ -34,6 +34,10 @@
 //   3. Per file, IN MEMORY (processCoreFile): DOCS (.md) are genericized + secret-scrubbed
 //      like the mirror; FUNCTIONAL files are kept VERBATIM and scanned only for an exact
 //      live-credential leak (brand/IP hits are non-fatal ADVISORIES, surfaced for a human).
+//   3b. RELEASE NOTES (task 1004218): release-notes.json — what each release brought in,
+//      generated from the ref's HISTORY (scripts/gds/release-notes.js), its prose redacted
+//      exactly like a doc, and pinned like every other file. Skipped, with a line saying
+//      so, where there is no history to read (--from-worktree, a shallow clone).
 //   4. NO-LEAK GATE (fail-closed): if any DOC leaks post-redaction, or any FUNCTIONAL file
 //      carries a live credential verbatim, PRODUCE NOTHING — dist/ is never touched. The
 //      in-memory pass makes the abort atomic (same discipline as the mirror export).
@@ -105,6 +109,12 @@ const {
 const { collectEnvSecrets } = require(path.join(REPO_ROOT, 'modules/security/secret-scrub.js'));
 const { redactBlob, parseLsTree } = require(path.join(REPO_ROOT, 'scripts/public-mirror-export.js'));
 const { partitionHits, unusedEntries } = require(path.join(REPO_ROOT, 'scripts/gds/leak-scan-allowlist.js'));
+// The release notes shipped beside package.json (task 1004218). Required by a literal path:
+// the module is pure and requires nothing, so it adds no computed require to this file's
+// executed closure (tests/executed_closure.mjs counts those).
+const {
+  RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, generateReleaseNotes, boundReleaseNotes, serializeReleaseNotes,
+} = require('./release-notes.js');
 
 const MANIFEST_SCHEMA = 1;
 const ARTIFACT_NAME = 'bongos-core';
@@ -734,6 +744,42 @@ function scanArtifactForLeaks(files, { literals = PRIOR_INSTANCE_LITERALS } = {}
   return { literalHits, secretWarnings };
 }
 
+// release-notes.json — the one file the core carries that is derived from HISTORY rather
+// than from a committed file (task 1004218). It only exists where the history does, which
+// is the CI pack (publish.yml checks out at fetch-depth 0). main() stages it into the SAME
+// staged/filesMeta arrays as package.json, so the pin manifest covers it and --self-verify
+// reproduces it; a file written into the stage dir behind the manifest's back would fail
+// self-verify at publish time.
+//
+// ITS PROSE IS TREATED AS A DOC. These are merge summaries — builder-authored sentences — so
+// the neutral floor applies exactly as it does to a shipped .md: redacted with the same rules
+// (redactBlob), and any residue after redaction is a fatal no-leak failure. Not optional:
+// ten of the 1,399 summaries in the history (measured 2026-09-25) name a prior instance or
+// its owner, and history cannot be edited — shipped verbatim, they would fail the fail-closed
+// post-build scan on EVERY pack from now on, and the lane would never publish again. That
+// scan still reads the finished file, as it reads every staged one.
+//
+// Pure: notes + the rules main() already built in, `{ buf, notes, dropped, summaries,
+// redacted, leaks }` out.
+function releaseNotesArtifact(notes, { rules, sensitiveLiterals, envSecrets, knownDocNames, maxBytes = RELEASE_NOTES_MAX_BYTES }) {
+  const leaks = [];
+  let redacted = 0;
+  const clean = {};
+  for (const [version, entries] of Object.entries(notes || {})) {
+    clean[version] = entries.map((e) => {
+      const r = redactBlob({ buf: Buffer.from(e.text, 'utf8'), rules, sensitiveLiterals, envSecrets, knownDocNames });
+      for (const l of r.leaks) leaks.push({ label: `doc:${l.label}`, sample: l.sample });
+      if (r.secret) leaks.push({ label: 'doc:secret-shape' });
+      const text = r.buf.toString('utf8');
+      if (text !== e.text) redacted++;
+      return e.id ? { id: e.id, text } : { text };
+    });
+  }
+  const bounded = boundReleaseNotes(clean, maxBytes);
+  const summaries = Object.values(bounded.notes).reduce((n, list) => n + list.length, 0);
+  return { buf: serializeReleaseNotes(bounded.notes), notes: bounded.notes, dropped: bounded.dropped, summaries, redacted, leaks };
+}
+
 // Self-verify the built artifact (task 1002218 / audit H3, findings F1+F5). The packager
 // claims a consumer "verifies an install by recomputing [the pin] from the unpacked tree" —
 // this proves the packager's OWN output actually does, at build time, on the produce side:
@@ -964,6 +1010,29 @@ function main() {
     staged.push({ name: TAR_ROOT + relPath, mode: 0o644, buf });
   }
 
+  // 4b. The release notes (task 1004218): what each release brought in, generated from this
+  //     ref's history, redacted as a doc, and staged into the same arrays so the pin covers
+  //     them. A worktree build or a shallow clone has no history to read, so it ships without
+  //     — and an upgrade onto it says its notes are unavailable rather than listing nothing.
+  const notesGen = fromWorktree
+    ? { skipped: 'built from the working tree, which carries no history' }
+    : generateReleaseNotes({ git, ref: sha, version });
+  let notesStaged = false;
+  if (notesGen.skipped) {
+    console.error(`[package-core] ! ${RELEASE_NOTES_FILE} not generated — ${notesGen.skipped}.`);
+  } else {
+    const art = releaseNotesArtifact(notesGen.notes, { rules, sensitiveLiterals, envSecrets, knownDocNames });
+    for (const l of art.leaks) leaks.push({ path: RELEASE_NOTES_FILE, label: l.label, sample: l.sample });
+    filesMeta.push({ path: RELEASE_NOTES_FILE, mode: '100644', sha256: sha256hex(art.buf) });
+    staged.push({ name: TAR_ROOT + RELEASE_NOTES_FILE, mode: 0o644, buf: art.buf });
+    notesStaged = true;
+    const kept = Object.keys(art.notes);
+    const trimmed = art.dropped.length
+      ? ` — the ${art.dropped.length} oldest release(s) DROPPED to stay under ${RELEASE_NOTES_MAX_BYTES / 1024} KiB`
+      : '';
+    console.error(`[package-core] ${RELEASE_NOTES_FILE}: ${kept.length} release(s) ${kept[0]} → ${kept[kept.length - 1]}, ${art.summaries} summaries (${art.redacted} redacted), ${(art.buf.length / 1024).toFixed(1)} KiB${trimmed}.`);
+  }
+
   if (leaks.length > 0) {
     console.error(`\n[package-core] NO-LEAK GATE FAILED — ${leaks.length} real leak(s) (doc redaction residue or a live credential in a functional file). PRODUCING NOTHING (fail-closed):`);
     for (const l of leaks.slice(0, 50)) {
@@ -977,7 +1046,7 @@ function main() {
     console.error('     for a live-credential leak, remove the secret at SOURCE (it should never be committed). Then re-run. dist/ was NOT touched.');
     process.exit(1);
   }
-  console.error(`[package-core] no-leak gate PASSED — ${staged.length} files clean (${docCount} docs redacted, ${stubCount} agent-docs stubbed, ${funcCount} functional verbatim).`);
+  console.error(`[package-core] no-leak gate PASSED — ${staged.length} files clean (${docCount} docs redacted, ${stubCount} agent-docs stubbed, ${funcCount} functional verbatim${notesStaged ? `, ${RELEASE_NOTES_FILE} generated` : ''}).`);
 
   // Advisory: brand-identity + public-IP literals that ship VERBATIM inside functional
   // files. Not a leak (these are public, not secrets; a downstream rebrands via config) —
@@ -1139,6 +1208,8 @@ module.exports = {
   PRIOR_INSTANCE_FLOOR,
   // task 1003995 — --from-worktree's enumerator, for a core checkout with no git history
   walkWorktreeEntries,
+  // task 1004218 — release-notes.json: the history-derived file, redacted as a doc and bounded
+  releaseNotesArtifact,
 };
 
 if (require.main === module) main();

package/scripts/gds/provision-core-upgrade.js

@@ -28,10 +28,14 @@
 // Its own file because scripts/gds/provision.js sits at the 1500-line oversized-file
 // ratchet, the same reason provision-net.js and provision-units.js were carved out.
 
+const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
 const { appUser, dbName, instanceUser, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+const { RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, parseChangeRecords, notesBetween } = require('./release-notes.js');
 
 // The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
 // web-tier half, and deliberately EXCLUDES 'dedicated': a dedicated droplet is stood up
@@ -452,74 +456,101 @@ function preflightUpgrade(inst, to, deps) {
 // requires one and posts it to Discord. So this reads the merge summaries between the two
 // releases rather than inventing a changelog nobody would maintain.
 //
-// IT READS THE CONTROL PLANE'S OWN CORE CHECKOUT, ALWAYS, whichever instance is being
-// previewed. "What changed in the core between 1.19.881 and 1.19.972" is a question about
-// the CORE repository, and a tenant's instance directory is a checkout of the TENANT's
-// repo with the core vendored in from npm — no core history in it at all, and the wrong
-// history if you squint. The control plane is the machine that builds the core, so it is
-// the machine that can answer.
+// IT READS THE NOTES THE CORE PACKAGE CARRIES, and a core checkout only as a fallback
+// (task 1004218). "What changed in the core between 1.19.881 and 1.19.972" is a question
+// about the CORE repository, and no tenant box will ever hold its history — every project
+// is a checkout of its OWN repo with the core vendored in from npm. So the packer writes
+// the summaries down once, from the full history CI packs with (release-notes.json, built
+// by scripts/gds/release-notes.js), and any machine that can download a core version can
+// read what it carries. The checkout path below is kept for a machine that has one.
 const CHANGE_CAP = 20;
-const CHANGE_TEXT_MAX = 400;
+// One registry download of a core tarball. The preview's owner is waiting on the dry run
+// beside it anyway, but a hung registry must not hold the runner forever.
+const NOTES_FETCH_TIMEOUT_MS = 60000;
+
+function runFault(r) {
+  if (!r) return 'no answer';
+  if (r.error) return String(r.error.message || r.error).slice(0, 160);
+  const tail = String(r.stderr || '').trim().split('\n').filter(Boolean).slice(-1)[0] || '';
+  return (tail || `exit ${r.status}`).slice(0, 160);
+}
 
 /**
- * The merge summaries in a `git log --merges --format=%s%x1f%b%x1e` dump. PURE.
+ * The release notes the core THIS runner executes from carries, if any. Free to read, and
+ * enough on its own whenever the target is at or below this core's own version — a tenant
+ * catching up to where the platform already is.
+ */
+function readInstalledNotes(deps = {}) {
+  const fsImpl = deps.fs || fs;
+  let raw;
+  try { raw = fsImpl.readFileSync(path.join(REPO_ROOT, RELEASE_NOTES_FILE), 'utf8'); }
+  catch { return { missing: 'this core carries no release notes' }; }
+  try { return { notes: JSON.parse(raw) }; }
+  catch { return { error: "this core's release notes are not valid JSON" }; }
+}
+
+/**
+ * The release notes inside ONE published core package — the TARGET's own (task 1004218).
  *
- * TWO MERGE SHAPES CARRY A SUMMARY AND THE SECOND IS THE COMMON ONE. A hand-landed ship
- * writes `Merge <branch>: <summary>`; the CI auto-merge writes `Merge pull request #N
- * from <owner>/<branch>` with `task <id>: <summary>` in the BODY. Measured over
- * 1.19.881→1.19.972: 114 usable summaries, of which 98 were the second shape. A parser
- * that read subjects only would have found eleven of them and quietly called that the
- * release.
+ * WHY THE TARGET'S. The installed core's notes stop at its own version, which is zero
+ * coverage for the move looked at most — the platform's own, onto a release newer than
+ * itself. The target's package is the one guaranteed to reach the target, because that is
+ * where the target was packed. `npm pack` downloads it (the core is public, so no
+ * credential — the same registry listAvailableVersions reads) and `tar -xzOf` reads the one
+ * file out of it rather than unpacking the rest.
  *
- * EVERYTHING ELSE IS DROPPED, and the drops are the majority: `Merge origin/main into
- * <branch> (pre-stage freshness…)`, `Merge remote-tracking branch…`, a regen chore. Those
- * are the mechanics of landing work, not the work, and listing them would bury the
- * eleven sentences the owner actually wants under a hundred they do not.
+ * Returns `{ notes }`, `{ missing }` when the package carries none (every release published
+ * before the notes were packaged), or `{ error }`. The download never outlives the call.
  */
-function parseChangeRecords(stdout) {
-  const out = [];
-  const seen = new Set();
-  for (const rec of String(stdout || '').split('\x1e')) {
-    const r = rec.trim();
-    if (!r) continue;
-    const i = r.indexOf('\x1f');
-    const subject = (i < 0 ? r : r.slice(0, i)).trim();
-    const body = i < 0 ? '' : r.slice(i + 1);
-    let text = null;
-    let id = null;
-    // The negative lookahead is what keeps the two housekeeping shapes out: both begin
-    // "Merge " and both would otherwise match a `<token>:` somewhere later in the line.
-    let m = /^Merge\s+(?!pull request\b|remote-tracking\b)([^\s:]+):\s*(\S.*)$/.exec(subject);
-    if (m) {
-      text = m[2];
-    } else {
-      const first = body.split('\n').map((l) => l.trim()).find(Boolean) || '';
-      m = /^task\s+(\d+):\s*(\S.*)$/.exec(first);
-      if (m) { id = m[1]; text = m[2]; }
+function readPackagedNotes(version, deps = {}) {
+  if (!CORE_VERSION_RE.test(String(version || ''))) return { error: 'could not work out which package to read' };
+  const run = deps.spawn || spawnSync;
+  const fsImpl = deps.fs || fs;
+  let dir = null;
+  try {
+    dir = fsImpl.mkdtempSync(path.join(deps.tmpDir || os.tmpdir(), 'bongos-release-notes-'));
+    const packed = run('npm', ['pack', `@bongos/core@${version}`, '--pack-destination', dir, '--silent'],
+      { cwd: dir, env: deps.env || process.env, encoding: 'utf8', timeout: NOTES_FETCH_TIMEOUT_MS });
+    if (!packed || packed.error || packed.status !== 0) {
+      return { error: `could not download the core ${version} package to read its release notes (${runFault(packed)})` };
+    }
+    // Whatever npm named it: a scoped package's tarball is <scope>-<name>-<version>.tgz today.
+    const tgz = fsImpl.readdirSync(dir).find((f) => f.endsWith('.tgz'));
+    if (!tgz) return { error: `npm reported the core ${version} package downloaded, but left no tarball` };
+    const x = run('tar', ['-xzOf', path.join(dir, tgz), `package/${RELEASE_NOTES_FILE}`],
+      { encoding: 'utf8', maxBuffer: 4 * RELEASE_NOTES_MAX_BYTES, timeout: NOTES_FETCH_TIMEOUT_MS });
+    if (!x || x.error || x.status !== 0) {
+      if (/not found in archive/i.test(String((x && x.stderr) || ''))) {
+        return { missing: `the core ${version} package carries no release notes` };
+      }
+      return { error: `could not read the release notes out of the core ${version} package (${runFault(x)})` };
     }
-    if (!text) continue;
-    // It reaches a DOM, and a ship summary is occasionally a paragraph.
-    text = text.length > CHANGE_TEXT_MAX ? `${text.slice(0, CHANGE_TEXT_MAX - 1)}…` : text;
-    if (seen.has(text)) continue;   // a branch merged twice says its sentence once
-    seen.add(text);
-    out.push(id ? { id, text } : { text });
+    try { return { notes: JSON.parse(x.stdout) }; }
+    catch { return { error: `the release notes in the core ${version} package are not valid JSON` }; }
+  } catch (e) {
+    return { error: `could not fetch the core ${version} package (${String((e && e.message) || e).slice(0, 160)})` };
+  } finally {
+    if (dir) { try { fsImpl.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } }
   }
-  return out;
 }
 
 /**
- * What landed between two core releases, as the summaries their ships wrote.
- *
- * Returns `{ from, to, entries, more }`, or `{ from, to, error }` — NEVER an empty
- * `entries` for a range it could not resolve. An empty list reads as "nothing changed",
- * which on a page whose job is to say what a restart buys is the one wrong impression it
- * must not give, and it is exactly what a missing checkout or a shallow clone produces.
- *
- * Every version reaching a shell is re-checked against the strict three-number form
- * FIRST. They arrive from an intent row whose column has the same CHECK, but a value that
- * is interpolated into a command is checked where it is interpolated — the rule
- * upgradeInvocation states about the slug.
+ * The range, answered from release notes alone: `{ entries }`, or `{ why }` they cannot.
+ * The installed core first, when its notes already reach the target; the target's own
+ * package otherwise. No git, no SHAs, no checkout.
  */
+function changesFromNotes(fromVersion, toVersion, deps) {
+  const installed = (deps.readInstalledNotes || readInstalledNotes)(deps);
+  if (installed.notes) {
+    const r = notesBetween(installed.notes, fromVersion, toVersion);
+    if (r.entries) return r;
+  }
+  const target = (deps.readPackagedNotes || readPackagedNotes)(toVersion, deps);
+  if (!target.notes) return { why: target.missing || target.error || `the core ${toVersion} package's release notes could not be read` };
+  const r = notesBetween(target.notes, fromVersion, toVersion);
+  return r.entries ? r : { why: `the release notes in the core ${toVersion} package ${r.uncovered}` };
+}
+
 /**
  * Classify a git command that did not succeed. PURE.
  *
@@ -598,21 +629,11 @@ function findCoreCheckout(deps, git) {
 }
 
 /**
- * What landed between two core releases, as the summaries their ships wrote.
- *
- * Returns `{ from, to, entries, more }`, or `{ from, to, error }` — NEVER an empty
- * `entries` for a range it could not resolve. An empty list reads as "nothing changed",
- * which on a page whose job is to say what a restart buys is the one wrong impression it
- * must not give, and it is exactly what a missing checkout produces.
- *
- * Every version reaching a shell is re-checked against the strict three-number form
- * FIRST. They arrive from an intent row whose column has the same CHECK, but a value that
- * is interpolated into a command is checked where it is interpolated — the rule
- * upgradeInvocation states about the slug.
+ * The range, answered from a core CHECKOUT's git history: `{ entries }` or `{ error }`.
+ * The fallback for a machine that has one, since the package's notes only exist for
+ * releases published after they were introduced (task 1004218).
  */
-function changesBetween(fromVersion, toVersion, deps) {
-  const bad = [fromVersion, toVersion].find((v) => !CORE_VERSION_RE.test(String(v || '')));
-  if (bad !== undefined) return { from: fromVersion || null, to: toVersion || null, error: 'could not work out which releases this covers' };
+function changesFromCheckout(fromVersion, toVersion, deps) {
   // The CONTROL PLANE's executor, never the previewed instance's: under
   // PROVISION_REMOTE_HOST `exec` is the remote box, while the core history — and the whole
   // question of what changed in the CORE — belongs to the machine that builds it.
@@ -635,7 +656,7 @@ function changesBetween(fromVersion, toVersion, deps) {
     };
   };
   const found = findCoreCheckout(deps, git);
-  if (found.error) return { from: fromVersion, to: toVersion, error: found.error };
+  if (found.error) return { error: found.error };
   const dir = found.dir;
   const shaOf = (v) => {
     const r = git(dir, `log --format=%H --max-count=1 -F --grep='release: core ${v} '`);
@@ -645,18 +666,48 @@ function changesBetween(fromVersion, toVersion, deps) {
   };
   const from = shaOf(fromVersion);
   const to = shaOf(toVersion);
-  if (from.fault || to.fault) return { from: fromVersion, to: toVersion, error: from.fault || to.fault };
+  if (from.fault || to.fault) return { error: from.fault || to.fault };
   // LOOKED, AND DID NOT FIND — a different sentence from "could not look", and it names
   // WHICH version is missing so the reader can tell a not-yet-published target from a
   // checkout that has not been fetched.
   const missing = [!from.sha && fromVersion, !to.sha && toVersion].filter(Boolean);
   if (missing.length) {
-    return { from: fromVersion, to: toVersion, error: `core ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not in the core history on this machine yet` };
+    return { error: `core ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not in the core history on this machine yet` };
   }
   const r = git(dir, `log --merges --format=%s%x1f%b%x1e ${from.sha}..${to.sha}`);
-  if (!r.ok) return { from: fromVersion, to: toVersion, error: gitFault(r, dir) };
-  const all = parseChangeRecords(r.stdout);
-  return { from: fromVersion, to: toVersion, entries: all.slice(0, CHANGE_CAP), more: Math.max(0, all.length - CHANGE_CAP) };
+  if (!r.ok) return { error: gitFault(r, dir) };
+  return { entries: parseChangeRecords(r.stdout) };
+}
+
+/**
+ * What landed between two core releases, as the summaries their ships wrote.
+ *
+ * Returns `{ from, to, entries, more, source }`, or `{ from, to, error }` — NEVER an empty
+ * `entries` for a range it could not resolve. An empty list reads as "nothing changed",
+ * which on a page whose job is to say what a restart buys is the one wrong impression it
+ * must not give, and it is exactly what a missing checkout produces.
+ *
+ * THE PACKAGE'S NOTES FIRST, THE CHECKOUT SECOND (task 1004218). The notes answer on every
+ * box; the checkout only where one exists, which is never a tenant. When neither can, the
+ * error carries BOTH reasons — the notes' and the checkout's own precise sentence (task
+ * 1004212) — so the reader is told everything that was tried and why each fell short.
+ *
+ * Every version reaching a shell is re-checked against the strict three-number form
+ * FIRST. They arrive from an intent row whose column has the same CHECK, but a value that
+ * is interpolated into a command is checked where it is interpolated — the rule
+ * upgradeInvocation states about the slug.
+ */
+function changesBetween(fromVersion, toVersion, deps) {
+  const bad = [fromVersion, toVersion].find((v) => !CORE_VERSION_RE.test(String(v || '')));
+  if (bad !== undefined) return { from: fromVersion || null, to: toVersion || null, error: 'could not work out which releases this covers' };
+  const listed = (all, source) => ({
+    from: fromVersion, to: toVersion, entries: all.slice(0, CHANGE_CAP), more: Math.max(0, all.length - CHANGE_CAP), source,
+  });
+  const notes = changesFromNotes(fromVersion, toVersion, deps);
+  if (notes.entries) return listed(notes.entries, 'release-notes');
+  const checkout = changesFromCheckout(fromVersion, toVersion, deps);
+  if (checkout.entries) return listed(checkout.entries, 'checkout');
+  return { from: fromVersion, to: toVersion, error: `${notes.why}; ${checkout.error}` };
 }
 
 // Run a dry run for one instance and cache its verdict — the ON-DEMAND leg, drained from
@@ -780,4 +831,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/redteam-patrol.js

@@ -5,7 +5,7 @@
 // The patrol is the third enforcement layer (prevent → gate → PATROL): checks
 // too slow, too networked, or too history-wide for the merge gate, run weekly
 // by the .claude/scheduled-tasks/redteam-weekly routine. It is ADVISORY by
-// doctrine (ADR 0162 — verdicts never self-execute): findings are FILED as
+// doctrine (ADR 0158 §2 — a verdict never self-executes): findings are FILED as
 // security reports for Archon adjudication, never turned into gates here.
 //
 // Checks (all deterministic — no model reads anything):
@@ -40,7 +40,7 @@
 // log. Instead --file preflights the session and, when there is none, follows the
 // main-audit.js --require-roster doctrine: report LOUDLY rather than green-and-
 // vacuous. The exit code says whether a finding was LOST, not whether findings
-// exist — findings are advisory (ADR 0162) and a patrol that goes red merely for
+// exist — findings are advisory (ADR 0158 §2) and a patrol that goes red merely for
 // doing its job trains everyone to ignore it:
 //
 //   ran + filed                     → 0
@@ -271,7 +271,7 @@ function buildClassReport(className, findings, notes = []) {
     target: `redteam-patrol/${className}`,
     severity: maxSeverity(findings),
     title: `[patrol] ${className}: ${findings.length} finding(s)`,
-    description: `Weekly deterministic red-team patrol (task 1003128; advisory per ADR 0162 — adjudicate, then fix via ordinary tasks).`,
+    description: `Weekly deterministic red-team patrol (task 1003128; advisory per ADR 0158 §2 — adjudicate, then fix via ordinary tasks).`,
     repro_steps_md: body,
   };
 }
@@ -289,7 +289,7 @@ function stepSummary(md) {
 // that disposition deserves. Extracted so the honest-exit contract is a table a
 // test can enumerate rather than branching buried in main().
 //
-// The load-bearing row is the last one. Findings are ADVISORY (ADR 0162), so a
+// The load-bearing row is the last one. Findings are ADVISORY (ADR 0158 §2), so a
 // run that finds three things and files them is a SUCCESS — going red merely for
 // doing its job is how a weekly lane becomes noise everyone filters. Red is
 // reserved for the single state where evidence EVAPORATES: findings exist,