@bongos/core 1.19.1032 → 1.19.1034

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/plain-cards.js

@@ -281,6 +281,10 @@ const CARDS = Object.freeze({
     'Your work touches a protected part of the project that your rank may not change, so the server would not accept it.',
     'Asking again will be refused again. I will take the protected files out and hand in the rest, or we pass the task to someone with the rank.',
     'A builder with a high enough rank, for the protected part.', RULE),
+  grade_unbacked_score: card(
+    'One of the automatic reviewers gave your work a low mark without saying what is wrong, so there is nothing listed to fix. It is not accepted yet, but it was not turned down for a named problem either.',
+    'I will ask for the review again. If the low mark comes back still without a reason, I will ask for your work to be accepted by hand, with an explanation.',
+    'Only if it keeps happening — an Archon decides whether to accept it by hand.', FAULT),
   grade_failed: card(
     'The automatic reviewers found problems in your work, so it is not accepted yet.',
     'I will fix what they listed, save it, and ask for the review again. That costs nothing extra.',

package/scripts/gds/preflight.js

@@ -28,6 +28,7 @@
 const nodeFs = require('node:fs');
 const nodePath = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { resolveEnv, envPrefix, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
 
 const REPO_ROOT = nodePath.resolve(__dirname, '..', '..');
 const MIN_NODE_MAJOR = 22;
@@ -155,9 +156,16 @@ function preflightChecks({
   //    /builder-start caller via depsFinding() (task 1002403).
   out.push(depsFinding({ repoRoot, fs }));
 
-  // 3. `claude` CLI launchable — same resolution order the grader uses.
-  const bin = env.OTB_CLAUDE_BIN || env.CLAUDE_BIN || 'claude';
-  const via = env.OTB_CLAUDE_BIN ? ' (via OTB_CLAUDE_BIN)' : env.CLAUDE_BIN ? ' (via CLAUDE_BIN)' : '';
+  // 3. `claude` CLI launchable — same resolution order the grader uses:
+  //    <PREFIX>_CLAUDE_BIN (legacy spellings still read), then CLAUDE_BIN, then `claude`.
+  const prefixed = resolveEnv('CLAUDE_BIN', { env });
+  const bin = prefixed || env.CLAUDE_BIN || 'claude';
+  // The label names the spelling that actually supplied the value, so a builder who
+  // set the legacy OTB_CLAUDE_BIN is told so rather than shown a name they never set.
+  const viaName = prefixed
+    ? [envPrefix(), ...LEGACY_ENV_PREFIXES].map((p) => `${p}_CLAUDE_BIN`).find((n) => env[n] === prefixed)
+    : env.CLAUDE_BIN ? 'CLAUDE_BIN' : null;
+  const via = viaName ? ` (via ${viaName})` : '';
   let r;
   try {
     r = spawn(bin, ['--version'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
@@ -174,7 +182,7 @@ function preflightChecks({
       level: 'fail',
       title: 'claude CLI',
       detail: `not launchable (${bin}: ${why}) — the grader spawns it per worker, so ships fail grading with SUBAGENT_SPAWN_FAILED.`,
-      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set OTB_CLAUDE_BIN to its full path.',
+      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set ' + envPrefix() + '_CLAUDE_BIN to its full path.',
     });
   }
 

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

@@ -28,10 +28,15 @@
 // 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 crypto = require('crypto');
+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 { appUser, dbName, instanceUser, parseTargetRef, resolveOwnerGithubToken, 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
@@ -269,14 +274,161 @@ async function coreUpgradeInstance(inst, deps, intent) {
     // reaching here means the two disagree. Report what was SEEN rather than a verdict.
     return { ok: false, error: `the box is serving core ${served}, not the requested ${to} — the move did not take` };
   }
+
+  // ---- 5. the pin reaches the project's own repo, pushed from HERE (task 1004065) ----
+  // Only now: a pin worth saving is one the box is serving. upgrade.js was told
+  // --pin-no-push for this shape, so it committed and stopped; see pushUpgradePin.
+  const repo = hubPushesPin(inst) ? await pushUpgradePin(inst, deps, { instanceDir }) : null;
+  const unsaved = repo && !repo.pushed ? `; GitHub was not updated (${repo.code})` : '';
   await provisioning.recordEvent(db, {
     instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'core-upgraded',
-    detail: served ? `core pin moved to ${served}` : `core pin moved to ${to}; the box did not answer /version, so this is unconfirmed`,
+    detail: (served ? `core pin moved to ${served}` : `core pin moved to ${to}; the box did not answer /version, so this is unconfirmed`) + unsaved,
     actor: intent.requested_by || 'runner',
   }).catch(() => {});
   if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id, 'core-upgrade').catch(() => {});
   log(served ? `  ✓ ${inst.slug} serves core ${served}` : `  ⚠ ${inst.slug} upgraded to ${to}, but did not answer /version — unconfirmed`);
-  return { ok: true, served, confirmed: served === to };
+  // `doneNote`: the drain loop resolves the intent DONE and stores this beside it, which
+  // is how the deploy page learns the upgrade landed but GitHub did not get it.
+  return { ok: true, served, confirmed: served === to, repo, doneNote: repo && !repo.pushed ? repo.note : null };
+}
+
+// ── the pin reaches the project's GitHub repo, pushed from the HUB (task 1004065) ──
+//
+// THE BUG THIS EXISTS FOR. upgrade.js commits the new pin on the box and then pushes it.
+// On a hosted project it runs connected to the PROJECT's database — it has to, for
+// migrations — while the owner's GitHub token lives in the HUB's. Its token lookup found
+// no provisioning table there (ADR 0281), fell back to `git push origin`, and origin is a
+// read-only deploy key (ADR 0176). GitHub refused, the refusal reached only the journal
+// and named the wrong cause, and the intent resolved `done`. The box ran the new core,
+// GitHub still pinned the old one, and the box's local commit stopped its fast-forward
+// pulls from taking the owner's new work: hermeslines-marketing served 1.19.994 against
+// a repo pinning 1.19.881, and pages pushed to that repo 404'd on the live site.
+//
+// WHY THE RUNNER PUSHES rather than handing upgrade.js the token. This process already
+// holds the hub's database, where the token is, and it runs as the account that owns the
+// checkout (the project's own account only READS it — grantInstanceRepoReadCmd). Passing
+// the token into the upgrade would put a credential that can write the repo inside the
+// project's own process. So the move passes --pin-no-push, upgrade.js commits, and the
+// push happens here, in the shape refreshStandaloneCorePin already uses for this repo.
+//
+// A FAILED PUSH IS NOT A FAILED UPGRADE. The site runs the new core, and rolling a good
+// deploy back would be worse than the split. The move still resolves `done`, carrying a
+// note the deploy page reads: `repo_not_updated:<code>: <sentence>`, parsed by
+// parseRepoNote in modules/provisioning/core-upgrade.js (re-stated there because a
+// module may not require a script; tests/core_upgrade_runner.mjs round-trips the two).
+//
+// NOTHING IS FORCED OR REBASED. When GitHub has commits the box does not, putting the pin
+// on top of them would change what the live box runs with no restart and no health check.
+// That is reported for an operator to reconcile, never resolved here.
+//
+// THE LIMIT, stated so nobody mistakes this for durable: the owner's token is kept for an
+// hour after they sign in with repository access (GITHUB_TOKEN_TTL_MS in src/bongos/db.js
+// — one wizard sitting). An upgrade days later usually finds none; the box's own remote
+// is then tried, and it can only read a private repo. The note says so in words.
+
+const REPO_NOTE_PREFIX = 'repo_not_updated';
+const REPO_NOTES = Object.freeze({
+  no_repo: 'This project has no GitHub repository on record, so the new version was saved on the server only.',
+  no_branch: 'The server\'s copy of the project is not on a branch, so there was nothing to save to GitHub.',
+  no_access: 'The hub had no permission to write to the project\'s GitHub repository: the owner\'s GitHub access is only kept for an hour after they connect GitHub, and the server\'s own key can only read the repository.',
+  refused: 'GitHub turned down the owner\'s GitHub access — it may have expired, or lack permission to write to the repository.',
+  behind: 'GitHub has changes the server does not have, so the new version could not be added on top of them. An operator needs to bring the two back in line; the site itself is running normally.',
+  failed: 'The hub could not save the new version to GitHub.',
+});
+// A branch name that is safe to interpolate. Narrower than git's own ref grammar on
+// purpose: a name outside it is refused, never quoted.
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$/;
+
+/** The note a done-but-unsaved move carries, bounded for the DOM it reaches. PURE. */
+function repoNote(code, extra = '') {
+  const known = Object.prototype.hasOwnProperty.call(REPO_NOTES, code) ? code : 'failed';
+  return `${REPO_NOTE_PREFIX}:${known}: ${REPO_NOTES[known]}${extra ? ` ${extra}` : ''}`.slice(0, 600);
+}
+
+// Which shapes get their pin pushed from here: a hosted project, whose repo is the
+// owner's own. The platform's own row pushes to a repo its key CAN write, and a
+// co-tenant shares the platform's checkout, so neither changes.
+function hubPushesPin(inst) { return !!inst && inst.hosting_shape === 'cloud-host'; }
+
+// Why a push did not happen, from what git said. `behind` is checked first: a rejected
+// update means the credential WORKED and the history is what stopped it.
+function pushFault(r) {
+  const said = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
+  if (/\[rejected\]|non-fast-forward|fetch first|Updates were rejected/i.test(said)) return 'behind';
+  if (/\b403\b|Authentication failed|Invalid username or password|Write access to repository not granted|Permission to \S+ denied|marked as read only|Permission denied \(publickey\)|could not read Username/i.test(said)) return 'refused';
+  return 'failed';
+}
+
+// GitHub's own line beats git's closing `fatal:`, which names no reason (upgrade.js
+// gitSaid has the same preference).
+function gitLine(r) {
+  const lines = String((r && r.stderr) || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const server = lines.filter((l) => /^(ERROR:|remote:|!)/i.test(l));
+  const said = server.length ? server[server.length - 1] : lines[lines.length - 1];
+  return said ? `(git: ${said.slice(0, 200)})` : '';
+}
+
+/**
+ * Push a confirmed upgrade's committed pin to the project's repo. NEVER THROWS: every
+ * miss returns `{ pushed:false, code, note }`, because the drain loop turns a throw into
+ * a broken instance and this instance is running fine.
+ *
+ * The token rides a chmod-600 credential file that is removed whatever the push did —
+ * never argv (ps, the journal), never a log line. The helper list is reset first
+ * (helpers are cumulative, so a global one would answer with some other account) and
+ * hooks are off, so nothing in the project's checkout runs as this account.
+ */
+async function pushUpgradePin(inst, deps, { instanceDir }) {
+  const log = deps.log || (() => {});
+  // The CONTROL PLANE's executor and writer: the checkout, the hub db and the token are
+  // all here, never on a remote co-hosting box (refreshStandaloneCorePin's routing).
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile || ((p, body, o) => fs.writeFileSync(p, body, o));
+  const failedRun = (r) => !r || r.softFailed === true || r.ok === false;
+  const miss = (code, extra = '') => {
+    log(`  ⚠ ${inst.slug}: GitHub was not updated — ${REPO_NOTES[code] || REPO_NOTES.failed}${extra ? ` ${extra}` : ''}`);
+    return { pushed: false, code, note: repoNote(code, extra) };
+  };
+  const repo = parseTargetRef(inst.target_ref);
+  if (!repo) return miss('no_repo');
+  const head = exec(`git -C ${instanceDir} symbolic-ref --short HEAD`, { allowFail: true });
+  const branch = failedRun(head) ? '' : String(head.stdout || '').trim();
+  if (!BRANCH_RE.test(branch)) return miss('no_branch');
+  const at = `${repo.owner}/${repo.name}@${branch}`;
+  const hardened = `git -C ${instanceDir} -c core.hooksPath=/dev/null`;
+  const env = { GIT_TERMINAL_PROMPT: '0' };   // a refused credential fails; it never waits at a prompt
+
+  const token = await resolveOwnerGithubToken(inst, deps, { tag: '[core-upgrade]' });
+  if (token) {
+    const credFile = path.join(os.tmpdir(), `bongos-gitcred-upgrade-${inst.slug}-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+    let r = null;
+    try {
+      writeFile(credFile, `https://x-access-token:${token}@github.com\n`, { mode: 0o600 });
+      r = exec(`${hardened} -c credential.helper= -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:${branch}`,
+        { allowFail: true, env });
+    } catch (e) {
+      return miss('failed', `(could not stage the owner's credential: ${String((e && e.message) || e).slice(0, 160)})`);
+    } finally {
+      exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+    if (!failedRun(r)) {
+      log(`  ✓ pushed the pin to ${at} from the hub, over the owner's GitHub token`);
+      return { pushed: true, via: 'owner-token', branch };
+    }
+    return miss(pushFault(r), gitLine(r));
+  }
+
+  // No token stored — which is the ordinary case (see THE LIMIT above). The box's own
+  // remote is still tried: a checkout wired with a key that can write is not wrong to use.
+  const r = exec(`${hardened} push origin HEAD:${branch}`, { allowFail: true, env });
+  if (!failedRun(r)) {
+    log(`  ✓ pushed the pin to ${at} from the hub, over the checkout's own remote`);
+    return { pushed: true, via: 'origin', branch };
+  }
+  const fault = pushFault(r);
+  // A refusal here is not the owner's access being turned down — there was none to turn
+  // down. It is the read-only key, which is the no-access case.
+  return miss(fault === 'refused' ? 'no_access' : fault, gitLine(r));
 }
 
 // The pre-flight lines a dry run emits, and the refusal when it has one. upgrade.js writes
@@ -400,6 +552,9 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
       `--health-url http://127.0.0.1:${inst.port}/healthz`,
       `--version-url http://127.0.0.1:${inst.port}/version`,
       '--commit-pin',
+      // A hosted project's pin is pushed by the RUNNER, which can reach the owner's
+      // token; the upgrade process cannot (task 1004065, pushUpgradePin).
+      hubPushesPin(inst) ? '--pin-no-push' : '',
       requestedBy ? `--requested-by ${requestedBy}` : '',
       requestedBy ? '--upgrade-source owner-control' : ''];
   return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account };
@@ -452,74 +607,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)})` };
     }
-    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 });
+    // 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)})` };
+    }
+    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 +780,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 +807,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 +817,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 +982,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, REPO_NOTES, repoNote, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };