@bongos/core 1.21.146 → 1.21.148

package/modules/hall-ui/public/watch.html

@@ -167,7 +167,7 @@
      chrome exists before the page script runs. -->
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-10-09-living3"></script>
-<script src="/builders/shell.js?v=2026-10-17-upgrade-hold1"></script>
+<script src="/builders/shell.js?v=2026-10-18-core-move1"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded before watch.js, which pulls from it. -->

package/modules/hall-ui/public/work.html

@@ -173,7 +173,7 @@
      time so the chrome exists before the deferred page scripts execute. -->
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-10-09-living3"></script>
-<script src="/builders/shell.js?v=2026-10-17-upgrade-hold1"></script>
+<script src="/builders/shell.js?v=2026-10-18-core-move1"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded FIRST so work.js can pull from it. -->

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.146",
+  "version": "1.21.148",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.146",
+      "version": "1.21.148",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.146",
+  "version": "1.21.148",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9890,5 +9890,17 @@
       "id": "1004730",
       "text": "When an automatic core update fails on a hosted project and is rolled back, that version is not retried over and over, and the project's owner now sees in their own Settings and update banner which version was tried, that it w"
     }
+  ],
+  "1.21.147": [
+    {
+      "id": "1004731",
+      "text": "After a project's software is updated, its owner now sees a one-time note saying which version it moved to, when, and what changed, and the Software update page lists the recent updates, including any that failed and were undo"
+    }
+  ],
+  "1.21.148": [
+    {
+      "id": "1004732",
+      "text": "When the hub upgrades a project's core, your laptop now notices at the next session start or ship, says so in one line, and on a clean main catches up and reinstalls the new core by itself."
+    }
   ]
 }

package/scripts/gds/core-origin-follow.js

@@ -0,0 +1,185 @@
+// scripts/gds/core-origin-follow.js — the laptop follows a core move the hub made (task 1004732)
+//
+// WHY. When the hub moves a hosted project's core (provision-core-upgrade.js), it commits
+// the new pin — package.json + lockfile, usually a vendored `file:vendor/bongos-core-X.tgz`
+// rewritten to an exact registry version — on the box and pushes it to the project's
+// GitHub repo. The owner's laptop checkout never hears of it: the next session runs the
+// old core, and the next ship merges against the old pin. Seen on toast (1.21.20 on the
+// laptop while fixes sat in newer releases).
+//
+// THE FIX. Before `bongos start` (an instance's session start: its CLAUDE.md opens every
+// session with it, and a package-installed instance carries no SessionStart hooks) and
+// before `bongos ship`, the dispatcher calls ensureCurrentCore(). It fetches origin/main
+// (bounded; allowed to fail) and compares the checkout's @bongos/core pin with
+// origin/main's. When ORIGIN moved it, the builder gets one plain line saying so. On a
+// clean `main` with no local commits, the checkout is fast-forwarded and the pinned core
+// is installed through core-pin-sync.js (task 1004632) — whose gates (the pin's shape,
+// and the pin having landed on main) still decide what may be installed — then the
+// command re-runs under the new core. A dirty tree, a feature branch or local commits get
+// the line and the command to run, never a forced change. So does a move that is not
+// pin-only (notPinOnly): the fast-forward installs and runs what it brings in, so it is
+// taken only for the hub's commit shape — the pin, the lockfile, a removed tarball — onto
+// a published registry release; anything wider waits for the owner to look.
+//
+// Silent and fail-open: in the core repo itself (the running package is not
+// @bongos/core) it returns before any git spawn; outside git, with no pin, when origin
+// cannot be read, or when the pins already agree it says nothing. A pin the LOCAL side
+// moved (origin's pin is still the one this branch forked from) is not a hub move.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const pinSync = require('./core-pin-sync.js');
+
+const FETCH_TIMEOUT_MS = 5000;
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(String(fsImpl.readFileSync(file, 'utf8')).replace(/^/, '')); } catch { return null; }
+}
+
+function gitOut(args, cwd, run, extra = {}) {
+  try {
+    const r = run('git', args, { cwd, encoding: 'utf8', ...extra });
+    return r && r.status === 0 ? String(r.stdout || '').trim() : null;
+  } catch { return null; }
+}
+
+function specOf(pkg) {
+  if (!pkg) return null;
+  return (pkg.dependencies || {})[pinSync.CORE_PKG] || (pkg.devDependencies || {})[pinSync.CORE_PKG] || null;
+}
+
+// The core pin package.json carries at `rev`, or null when that file cannot be read there.
+function specAt(root, rev, run) {
+  const body = gitOut(['show', `${rev}:package.json`], root, run, { maxBuffer: 8 * 1024 * 1024 });
+  if (body == null) return null;
+  try { return specOf(JSON.parse(body.replace(/^/, ''))); } catch { return null; }
+}
+
+const shown = (spec) => pinSync.versionFromSpec(spec) || spec;
+
+// Why the move cannot be applied to this checkout automatically, or null when it can.
+function blockedReason({ branch, dirty, ahead }) {
+  if (!branch) return 'this checkout is not on a branch';
+  if (branch !== 'main') return `you are on branch ${branch}, which picks the move up when it merges main`;
+  if (dirty == null || dirty !== '') return 'this checkout has uncommitted changes';
+  if (!Number.isFinite(ahead) || ahead !== 0) return 'main has local commits GitHub does not have';
+  return null;
+}
+
+const REMEDY = 'On a clean main: `git pull --ff-only origin main`, then `npm ci`.';
+const REVIEW_REMEDY = 'Review what GitHub has (`git log HEAD..origin/main`), then `git pull --ff-only origin main` and `npm ci`.';
+const REGISTRY = 'https://registry.npmjs.org/';
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$/;
+
+function jsonAt(root, rev, file, run) {
+  const body = gitOut(['show', `${rev}:${file}`], root, run, { maxBuffer: 64 * 1024 * 1024 });
+  if (body == null) return null;
+  try { return JSON.parse(body.replace(/^/, '')); } catch { return null; }
+}
+
+// The fast-forward installs and then RUNS what it brings in, unattended — so it is taken
+// only when what GitHub has is the hub's pin move and nothing else (the shape
+// provision-core-upgrade.js pushes). Anything wider is reported, never applied. Returns
+// null when the move is pin-only, else the reason it is not.
+//   - the only files that differ are package.json, package-lock.json and a removed
+//     vendored tarball;
+//   - package.json differs ONLY in the @bongos/core spec;
+//   - the new spec is an exact version, i.e. a published release (a tarball brought in
+//     from GitHub is code nobody released);
+//   - the lockfile pins that version from the public registry, and every lockfile
+//     source it adds is the public registry too.
+function notPinOnly(root, run) {
+  const diff = gitOut(['diff', '--name-status', '--no-renames', 'HEAD', 'origin/main'], root, run, { maxBuffer: 16 * 1024 * 1024 });
+  if (diff == null) return 'the change on GitHub could not be read';
+  for (const line of diff.split('\n').filter(Boolean)) {
+    const [status, file] = line.split('\t');
+    const ok = file === 'package.json' || file === 'package-lock.json' ||
+      (status === 'D' && /^vendor\/bongos-core-[^/]+\.tgz$/.test(file));
+    if (!ok) return 'GitHub has other changes besides the core move';
+  }
+  const before = jsonAt(root, 'HEAD', 'package.json', run);
+  const after = jsonAt(root, 'origin/main', 'package.json', run);
+  if (!before || !after) return 'package.json could not be read';
+  const spec = specOf(after);
+  const strip = (pkg) => {
+    const c = JSON.parse(JSON.stringify(pkg));
+    for (const k of ['dependencies', 'devDependencies']) if (c[k]) delete c[k][pinSync.CORE_PKG];
+    return JSON.stringify(c);
+  };
+  if (strip(before) !== strip(after)) return 'package.json changed beyond the core pin';
+  if (!EXACT_SEMVER.test(String(spec || ''))) return 'the new pin is not a published release';
+  const lock = jsonAt(root, 'origin/main', 'package-lock.json', run);
+  const entry = lock && lock.packages && lock.packages[`node_modules/${pinSync.CORE_PKG}`];
+  if (!entry || entry.version !== spec || !String(entry.resolved || '').startsWith(`${REGISTRY}${pinSync.CORE_PKG}/-/`)) {
+    return 'the lockfile does not pin that release from the public registry';
+  }
+  const prior = new Set(Object.values(((jsonAt(root, 'HEAD', 'package-lock.json', run) || {}).packages) || {}).map((p) => p && p.resolved));
+  for (const p of Object.values(lock.packages)) {
+    const r = p && p.resolved;
+    if (r && !prior.has(r) && !String(r).startsWith(REGISTRY)) return 'the lockfile adds a source outside the public registry';
+  }
+  return null;
+}
+
+// Returns { action: 'none' | 'reported' | 'fast-forwarded', reason, from?, to? }.
+function followOriginPin({ coreRoot, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, fetchTimeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const none = (reason) => ({ action: 'none', reason });
+  if (env && (env.BONGOS_SKIP_CORE_SYNC || env[pinSync.SYNCED_ENV])) return none('skipped');
+  const running = readJson(path.join(coreRoot, 'package.json'), fsImpl);
+  if (!running || running.name !== pinSync.CORE_PKG) return none('core-repo'); // no git spawn
+  const top = gitOut(['rev-parse', '--show-toplevel'], cwd, run);
+  if (!top) return none('no-git');
+  const root = path.resolve(top);
+  const local = specOf(readJson(path.join(root, 'package.json'), fsImpl));
+  if (!local) return none('no-pin');
+
+  // Bounded, quiet, never prompts; a failure is fine — the ref below decides.
+  gitOut(['fetch', '--quiet', 'origin', 'main'], root, run, {
+    timeout: fetchTimeoutMs, env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  const origin = specAt(root, 'origin/main', run);
+  if (!origin) return none('origin-unreadable');
+  if (origin === local) return none('in-step');
+  const forkPoint = gitOut(['merge-base', 'HEAD', 'origin/main'], root, run);
+  if (forkPoint && specAt(root, forkPoint, run) === origin) return none('local-change');
+
+  const say = log || ((s) => process.stderr.write(s + '\n'));
+  const move = { from: local, to: origin };
+  say(`bongos: this project was upgraded to core ${shown(origin)} on GitHub (this checkout has ${shown(local)}).`);
+  const why = blockedReason({
+    branch: gitOut(['symbolic-ref', '--short', '-q', 'HEAD'], root, run),
+    dirty: gitOut(['status', '--porcelain', '--untracked-files=no'], root, run),
+    ahead: Number(gitOut(['rev-list', '--count', 'origin/main..HEAD'], root, run)),
+  });
+  if (why) {
+    say(`  Not updated here: ${why}. ${REMEDY}`);
+    return { action: 'reported', reason: why, ...move };
+  }
+  const wider = notPinOnly(root, run);
+  if (wider) {
+    say(`  Not updated automatically: ${wider}. ${REVIEW_REMEDY}`);
+    return { action: 'reported', reason: wider, ...move };
+  }
+  if (gitOut(['merge', '--ff-only', '--quiet', 'origin/main'], root, run) == null) {
+    say(`  The fast-forward did not go through. ${REMEDY}`);
+    return { action: 'reported', reason: 'ff-failed', ...move };
+  }
+  say('  Fast-forwarded this checkout to it; installing that core next.');
+  return { action: 'fast-forwarded', reason: 'origin-moved', ...move };
+}
+
+// The dispatcher's one call, for `ship` and `start`. Returns an exit code when it handled
+// the command (installed and re-ran, or refused), or null to run the verb as it is.
+// `ship` always checks the running core against the pin (task 1004632); `start` only
+// after a fast-forward actually moved the pin, so a normal session start pays no more
+// than the fetch.
+function ensureCurrentCore({ coreRoot, argv, verb, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, npmCli } = {}) {
+  const followed = followOriginPin({ coreRoot, cwd, env, run, fsImpl, log });
+  if (verb !== 'ship' && followed.action !== 'fast-forwarded') return null;
+  return pinSync.ensurePinnedCore({ coreRoot, argv, cwd, env, run, fsImpl, log, ...(npmCli !== undefined ? { npmCli } : {}) });
+}
+
+module.exports = { followOriginPin, ensureCurrentCore };

package/scripts/gds/core-pin-sync.js

@@ -172,6 +172,28 @@ function unlinkLink(linkPath, { platform = process.platform, fsImpl = fs } = {})
   }
 }
 
+// A vendored instance keeps an untracked `scripts -> node_modules/@bongos/core/scripts`
+// link in its main checkout (grading needs it; task 1004728). After an install it must
+// still resolve (task 1004732): a link left dangling is re-pointed at the installed core.
+// Only ever a LINK — a real scripts/ directory (the core repo) is never touched.
+// Returns 'absent' | 'not-a-link' | 'ok' | 'repointed' | 'unresolved'.
+function healScriptsLink(root, { fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), platform = process.platform } = {}) {
+  const link = path.join(root, 'scripts');
+  let st = null;
+  try { st = fsImpl.lstatSync(link); } catch { return 'absent'; }
+  if (!st.isSymbolicLink()) return 'not-a-link';
+  if (fsImpl.existsSync(path.join(link, 'gds'))) return 'ok';
+  const target = path.join(root, 'node_modules', '@bongos', 'core', 'scripts');
+  const fix = `bongos: the \`scripts\` link in ${root} no longer resolves; point it at ${target}.`;
+  if (!fsImpl.existsSync(target)) { log(fix); return 'unresolved'; }
+  try {
+    unlinkLink(link, { platform, fsImpl });
+    fsImpl.symlinkSync(target, link, 'junction');
+  } catch { log(fix); return 'unresolved'; }
+  log('bongos: re-pointed the `scripts` link at the installed core.');
+  return 'repointed';
+}
+
 // Install the pinned core into `root` and re-run the same bongos command under it.
 // Returns the exit code to use.
 function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), env = process.env, platform = process.platform, npmCli = npmCliPath(process.execPath, fsImpl) } = {}) {
@@ -192,10 +214,13 @@ function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => p
   // npm's JS entry under this node — no shell. Fallback: `npm`, which on win32 is
   // npm.cmd and needs a shell (Node refuses a .cmd without one); the args are fixed
   // strings, never branch data.
+  // npm's output goes to stderr (task 1004732): `bongos start --widget` hands stdout to
+  // the renderer verbatim, so an install must never print there.
   const cli = npmCli;
+  const stdio = ['ignore', 2, 2];
   const inst = cli
-    ? run(process.execPath, [cli, ...installArgs(hasLock)], { cwd: root, stdio: 'inherit', env })
-    : run('npm', installArgs(hasLock), { cwd: root, stdio: 'inherit', env, ...(platform === 'win32' ? { shell: true } : {}) });
+    ? run(process.execPath, [cli, ...installArgs(hasLock)], { cwd: root, stdio, env })
+    : run('npm', installArgs(hasLock), { cwd: root, stdio, env, ...(platform === 'win32' ? { shell: true } : {}) });
   if (!inst || inst.error || inst.status !== 0) {
     log(`bongos: installing core ${pinned} failed.`);
     remedy();
@@ -203,6 +228,7 @@ function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => p
   }
   const bin = path.join(nm, '@bongos', 'core', 'bin', 'bongos.js');
   if (!fsImpl.existsSync(bin)) { remedy(); return 1; }
+  healScriptsLink(root, { fsImpl, log, platform });
   const res = run(process.execPath, [bin, ...argv.slice(2)], { stdio: 'inherit', env: { ...env, [SYNCED_ENV]: '1' } });
   if (!res || res.error) return 1;
   return res.status == null ? 1 : res.status;
@@ -210,7 +236,7 @@ function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => p
 
 // The dispatcher's one call. Returns an exit code when it handled the command (synced
 // and re-ran, or refused), or null to run the verb on the current core.
-function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log } = {}) {
+function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, npmCli } = {}) {
   if (env && env.BONGOS_SKIP_CORE_SYNC) return null;
   const runningPkg = readJson(path.join(coreRoot, 'package.json'), fsImpl);
   if (!runningPkg || runningPkg.name !== CORE_PKG) return null; // fast path: the core repo itself
@@ -227,7 +253,7 @@ function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.e
     say(remedyLine({ ...plan, hasLock: fsImpl.existsSync(path.join(root, 'package-lock.json')) }));
     return 1;
   }
-  return syncAndRerun(plan, { argv, run, fsImpl, log: say, env });
+  return syncAndRerun(plan, { argv, run, fsImpl, log: say, env, ...(npmCli !== undefined ? { npmCli } : {}) });
 }
 
-module.exports = { CORE_PKG, SYNCED_ENV, LANDED_REFS, pinLanded, npmCliPath, parseSpec, versionFromSpec, installArgs, pinnedCoreVersion, planCoreSync, remedyLine, syncAndRerun, ensurePinnedCore };
+module.exports = { CORE_PKG, SYNCED_ENV, LANDED_REFS, pinLanded, npmCliPath, parseSpec, versionFromSpec, installArgs, pinnedCoreVersion, planCoreSync, remedyLine, syncAndRerun, healScriptsLink, ensurePinnedCore };

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

@@ -321,7 +321,10 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // the one field task 1004121 exists to keep identical. Skipped when !apply, where the
   // command is printed and never run — a plan should not spend a subprocess per tick.
   const { runAs, migrateAs } = resolveRunAs(inst, deps, { probe: apply });
-  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, selfRoot, runAs, migrateAs });
+  // A move the hub queued by itself (provision-auto-upgrade.js) says so in the project's
+  // own ledger, so its hall can tell its owner "upgraded automatically" (task 1004731).
+  const automatic = !!intent && intent.requested_by === 'runner:auto-upgrade';
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, automatic, selfRoot, runAs, migrateAs });
 
   if (!apply) {
     // A --dry-run runner tick used to only PRINT this command. It now runs the CLI's own
@@ -668,7 +671,7 @@ function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
 // HERE rather than left to instanceUser()'s own throw: that throw is correct today, but
 // a call site whose safety depends on a helper's internals is one refactor away from a
 // shell-injection path (and the apply leg's own guard sits at the route, not here).
-function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', selfRoot = selfInstanceRoot, runAs = null, migrateAs = null } = {}) {
+function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', automatic = false, selfRoot = selfInstanceRoot, runAs = null, migrateAs = null } = {}) {
   if (!isValidSlug(inst && inst.slug)) {
     throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
   }
@@ -729,7 +732,10 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
       // token; the upgrade process cannot (task 1004065, pushUpgradePin).
       hubPushesPin(inst) ? '--pin-no-push' : '',
       requestedBy ? `--requested-by ${requestedBy}` : '',
-      requestedBy ? '--upgrade-source owner-control' : ''];
+      requestedBy ? '--upgrade-source owner-control' : '',
+      // The ledger's existing mark for an unattended move (the self-host sweep writes
+      // `auto-subscription (<rule>)`); one shell-safe word here (task 1004731).
+      automatic && !requestedBy ? '--note auto-subscription' : ''];
   return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account, migrateAs: dbAccount };
 }
 

package/src/bongos/core-moves.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// src/bongos/core-moves.js — "you were upgraded, and this is what changed": what THIS
+// project's own hall says after its core moved, and the short list of moves Settings →
+// Software update keeps (task 1004731).
+//
+// WHY. Since task 1004729 the hub moves a hosted project's core on its own, by its update
+// rule. The owner found out only by noticing a different number. The goal state is "a
+// changelog is visible inside the update": the hall says once, after the move, which core
+// it is on now, when it moved, and what the releases in between brought.
+//
+// NO NEW CHANNEL — the same reading task 1004730's hold makes (upgrade-hold.js). Every move,
+// automatic or by hand, is `bongos upgrade` run against THIS project's database, and it
+// writes one row to this project's own `core_upgrades` ledger: a landed move as from → to,
+// a failed one as its `rolled_back:` row. And the release notes for every version up to
+// the one now running ship INSIDE the running core (release-notes.json, task 1004218), so
+// the entries between the old and the new version are read from this project's own disk.
+// The hub is never asked.
+//
+// HOW IT WAS MOVED is only as precise as the ledger: `source = 'owner-control'` is the
+// Update button (a person); a note carrying `auto-subscription` is an automatic move (the
+// self-host sweep has always written it, and since this task the hub's automatic move
+// passes it too, provision-core-upgrade.js); anything else was run on the server, and the
+// ledger cannot say by whom, so it says "on the server" rather than guess. A failed
+// automatic move keeps no note of its own (rollback() writes `rolled_back:` in the one note
+// column), so it reads as "on the server" too.
+
+const fs = require('fs');
+const path = require('path');
+const { notesBetween, RELEASE_NOTES_FILE } = require('../../scripts/gds/release-notes.js');
+
+const VERSION_RE = /^\d{1,4}\.\d{1,5}\.\d{1,6}$/;
+const ROLLED_BACK_RE = /^rolled_back:/;
+const DOWNGRADE_RE = /^downgrade\b/;
+const AUTO_RE = /auto-subscription/;
+
+// A notice is about a move that just happened. A project whose last move was months ago
+// (the ledger outlives this feature) is not told about it as news.
+const NOTICE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+// The notice is a banner, not the changelog: a few lines, then "and N more" with the way
+// to the full list.
+const NOTICE_ENTRIES_MAX = 6;
+// "A short history of moves."
+const HISTORY_MAX = 8;
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August',
+  'September', 'October', 'November', 'December'];
+
+function isoOrNull(v) {
+  const d = v ? new Date(v) : null;
+  return d && Number.isFinite(d.getTime()) ? d.toISOString() : null;
+}
+
+// "15 October 2026", in UTC so the same move reads the same date for every reader and test.
+function longDate(iso) {
+  const d = new Date(iso);
+  return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+}
+
+/** How a ledger row's move was started: 'automatic' | 'by_hand' | 'on_server'. PURE. */
+function moveHow(row) {
+  if (row && row.source === 'owner-control') return 'by_hand';
+  if (row && typeof row.note === 'string' && AUTO_RE.test(row.note)) return 'automatic';
+  return 'on_server';
+}
+
+/** What a ledger row says happened: 'upgraded' | 'moved_back' | 'rolled_back'. PURE. */
+function moveOutcome(row) {
+  const note = row && typeof row.note === 'string' ? row.note : '';
+  if (ROLLED_BACK_RE.test(note)) return 'rolled_back';
+  if (DOWNGRADE_RE.test(note)) return 'moved_back';
+  return 'upgraded';
+}
+
+/**
+ * The short history Settings → Software update shows, newest first, failed moves included.
+ * PURE over core_upgrades rows (newest first). `version` is the core the move went to, or
+ * for a rolled-back row the one it tried.
+ */
+function moveHistory(rows) {
+  if (!Array.isArray(rows)) return [];
+  return rows
+    .filter((r) => r && VERSION_RE.test(String(r.to_version || '')))
+    .slice(0, HISTORY_MAX)
+    .map((r) => ({
+      id: r.id == null ? null : String(r.id),
+      version: String(r.to_version),
+      from: VERSION_RE.test(String(r.from_version || '')) ? String(r.from_version) : null,
+      at: isoOrNull(r.applied_at),
+      how: moveHow(r),
+      outcome: moveOutcome(r),
+    }));
+}
+
+/**
+ * The one-time notice after a move, or null. PURE.
+ *
+ * Shown only while it is true and new: the newest ledger row is a move that went in (not a
+ * rollback), this server runs the version it went to (so "upgraded to X" is a fact: this
+ * answer is served by X), it is recent, and this builder has not seen it (`seenId`, the
+ * ledger row id they last acknowledged).
+ *
+ * @param {object[]} rows     core_upgrades rows, newest first
+ * @param {string}   running  the core this server runs
+ * @param {object?}  notes    the running core's release-notes.json (null if unreadable)
+ * @param {string?}  seenId   the ledger row id this builder has acknowledged
+ * @param {number}   now      ms clock
+ */
+function moveNotice({ rows, running, notes = null, seenId = null, now = Date.now() }) {
+  const last = Array.isArray(rows) ? rows[0] : null;
+  if (!last || last.id == null) return null;
+  const id = String(last.id);
+  const to = String(last.to_version || '');
+  if (!VERSION_RE.test(to) || to !== String(running || '')) return null;
+  const outcome = moveOutcome(last);
+  if (outcome === 'rolled_back') return null;
+  if (seenId != null && String(seenId) === id) return null;
+  const at = isoOrNull(last.applied_at);
+  if (!at || now - Date.parse(at) > NOTICE_MAX_AGE_MS) return null;
+  const from = VERSION_RE.test(String(last.from_version || '')) ? String(last.from_version) : null;
+  const how = moveHow(last);
+
+  // The release-note entries between the old and the new version, from this core's own file.
+  let entries = null;
+  let more = 0;
+  if (outcome === 'upgraded' && from && notes) {
+    const r = notesBetween(notes, from, to);
+    if (r.entries) {
+      entries = r.entries.slice(0, NOTICE_ENTRIES_MAX);
+      more = r.entries.length - entries.length;
+    }
+  }
+  const verb = outcome === 'moved_back' ? 'Moved back' : 'Upgraded';
+  return {
+    id,
+    version: to,
+    from,
+    at,
+    how,
+    outcome,
+    message: `${verb}${how === 'automatic' ? ' automatically' : ''} to core ${to} on ${longDate(at)}.`,
+    entries,
+    more,
+  };
+}
+
+/**
+ * The running core's own release notes, or null. Never throws. The file sits at the package
+ * root beside package.json (release-notes.js); a core checkout run in place has none.
+ */
+function readInstalledReleaseNotes({ fsImpl = fs, root = path.join(__dirname, '..', '..') } = {}) {
+  try { return JSON.parse(fsImpl.readFileSync(path.join(root, RELEASE_NOTES_FILE), 'utf8')); } catch { return null; }
+}
+
+module.exports = { moveHistory, moveNotice, readInstalledReleaseNotes };

package/src/bongos/routes/core-update.js

@@ -35,6 +35,7 @@ const seams = require('../../module-seams');
 const { loadIdpConfig } = require('../auth-config');
 const upgradeRequest = require('../upgrade-request');
 const { readUpgradeHold } = require('../upgrade-hold');
+const { moveNotice, moveHistory, readInstalledReleaseNotes } = require('../core-moves');
 
 // WHERE A HOSTED PROJECT'S OWNER TAKES THE UPGRADE (task 1004174, ADR 0339): the hub's
 // own deploy door, scoped to this project — `<hub>/deploy?project=<slug>`. The act stays
@@ -222,6 +223,37 @@ async function safeHold(read, args) {
   try { return (await read(args)) || null; } catch { return null; }
 }
 
+// "Upgraded to core X on <date>, and this is what changed" (task 1004731,
+// src/bongos/core-moves.js): the one-time notice after a move and the short history of
+// moves, both read from this project's own core_upgrades ledger, the notes from the running
+// core's own release-notes.json. Gated like the ledger read (GET /core-upgrades): when and to
+// what this box moved is a vulnerability-window fact (ADR 0043).
+//
+// WHO HAS SEEN IT is per builder and server-side, in the builder-settings module's
+// behavior_prefs (core-move-seen.js), reached through its port: core never requires a module.
+// Without the module the hall remembers it in the browser instead ('browser').
+async function defaultSeenMove(req) {
+  const port = seams.resolveOptional('builder-settings');
+  if (!port || typeof port.coreMoveSeen !== 'function' || typeof port.getBuilderBehaviorPrefs !== 'function') {
+    return { remember: 'browser', seen: null };
+  }
+  return { remember: 'server', seen: port.coreMoveSeen(await port.getBuilderBehaviorPrefs(req.builder && req.builder.id)) };
+}
+
+// The notice for this viewer, or null. Fail-soft: a ledger, notes file or seen state that
+// cannot be read is no notice, never a failed banner read.
+async function safeMoved({ req, running, upgrades, releaseNotes, seenMove }) {
+  try {
+    const [rows, seen] = await Promise.all([upgrades({ limit: 1 }), seenMove(req)]);
+    const notice = moveNotice({ rows, running, notes: releaseNotes(), seenId: seen && seen.seen });
+    return notice ? { ...notice, remember: seen && seen.remember === 'server' ? 'server' : 'browser' } : null;
+  } catch { return null; }
+}
+
+async function safeHistory(upgrades) {
+  try { return moveHistory(await upgrades({ limit: 8 })); } catch { return null; }
+}
+
 function buildCoreUpdateRouter({
   coreUpdate = readCoreUpdate,
   selfChannel = storedSelfChannel,
@@ -231,6 +263,8 @@ function buildCoreUpdateRouter({
   doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig(), hubUpgradeUrl: safeHubUpgradeUrl() }),
   askDeps = defaultAskDeps,
   upgradeHold = readUpgradeHold,
+  releaseNotes = readInstalledReleaseNotes,
+  seenMove = defaultSeenMove,
 } = {}) {
   contributeCoreUpdateToDocket();
   const router = express.Router();
@@ -247,7 +281,7 @@ function buildCoreUpdateRouter({
     // grader caught here, and it is invisible to any test that does not drive a
     // real request through the assembled router; tests/core_update_banner.mjs now
     // does, and fails if this call is mis-shaped again.
-    asyncHandler('GET /core-update', async (_req, res) => {
+    asyncHandler('GET /core-update', async (req, res) => {
       // Fail-soft on the version read, exactly as GET /version does: an instance
       // that cannot name its own core reports `no_answer` and renders no banner.
       let running = null;
@@ -256,7 +290,11 @@ function buildCoreUpdateRouter({
       // own links to Settings → Software update, and the hand-off lives on GET /software-update.
       const { channel, source } = await resolveChannel(selfChannel);
       const update = await coreUpdate({ running, channel });
-      res.json({ ok: true, update: { ...update, channel_source: source }, held: await safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.latest : null }) });
+      const [held, moved] = await Promise.all([
+        safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.latest : null }),
+        safeMoved({ req, running, upgrades, releaseNotes, seenMove }),
+      ]);
+      res.json({ ok: true, update: { ...update, channel_source: source }, held, moved });
     }, { errorCode: 'core_update_failed', message: false }),
   );
 
@@ -295,7 +333,9 @@ function buildCoreUpdateRouter({
       const door = updateDoor(doorInputs());
       const ask = await readAsk({ update, door, deps: askDeps() });
       const held = await safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.offered : null });
-      res.json({ ok: true, update, door, can_update: can === true, ask, held });
+      // The history only for a viewer who holds core.pin.move (see safeMoved's gate note).
+      const history = can === true ? await safeHistory(upgrades) : null;
+      res.json({ ok: true, update, door, can_update: can === true, ask, held, history });
     }, { errorCode: 'software_update_failed', message: false }),
   );
 

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.146'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.148'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');