@bongos/core 1.19.972 → 1.19.973

package/modules/public-landing/public/terms.html

@@ -81,6 +81,6 @@
   </section>
 </main>
 
-<footer class="foot"><!--apex-only:start--><span>A non-profit, capture-resistant commons. </span><!--apex-only:end-->Built by agents, on Cloud&nbsp;Bongos. <a href="https://www.gnu.org/licenses/agpl-3.0.html" target="_blank" rel="noopener">Open source (AGPL-3.0)</a>.<nav class="footNav" aria-label="Site"><a href="/privacy">Privacy</a><a href="/terms" aria-current="page">Terms</a><a href="/contact">Contact</a></nav></footer>
+<footer class="foot"><!--apex-only:start--><span>A non-profit, capture-resistant commons. </span><!--apex-only:end-->Built by agents, on Cloud&nbsp;Bongos. <a href="https://www.npmjs.com/package/@bongos/core" target="_blank" rel="noopener">Open source</a> (<a href="https://www.gnu.org/licenses/agpl-3.0.html" target="_blank" rel="noopener">AGPL-3.0</a>).<nav class="footNav" aria-label="Site"><a href="/privacy">Privacy</a><a href="/terms" aria-current="page">Terms</a><a href="/contact">Contact</a></nav></footer>
 </body>
 </html>

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.972",
+  "version": "1.19.973",
   "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/scripts/gds/api-alias-caller-scan.js

@@ -41,11 +41,22 @@
 //      gate that cannot state its own rule cannot explain itself.
 //   5. tests/ (path-excluded). Tests are what keeps the alias exercised in CI. Moving them off it
 //      would retire the alias by accident.
-//   6. docs/ (path-excluded) — a DELIBERATE SCOPE CALL, not an oversight. It is the largest
-//      remaining bucket (~320) and it is where rename-history-check's per-file floors live, so a
-//      docs pass has to separate the record of what we used to call it from instructions that
-//      still teach the old spelling. 1004064's own brief says to treat docs as out of scope and
-//      file it rather than widen the task; filed as the follow-up named in that task's session log.
+//   6. THE FROZEN RECORD UNDER docs/ (path-excluded) — narrowed from a blanket `docs/` by task
+//      1004113, which is the scope call 1004064 deferred. docs/ is not one kind of thing: part of
+//      it is the RECORD of what we used to call the thing, and part of it is live instruction that
+//      still TEACHES a reader to call the alias. A blanket exclusion left the second unpoliced
+//      forever; a blind sweep would have destroyed the first.
+//      The line is not invented here — it is the one the repo already draws twice over. The
+//      subtrees excluded (docs/adr, docs/session-logs, docs/audits) are exactly the frozen-record
+//      path list in the sibling detector gds-literal-scan.js, and — measured, not assumed — all 134 per-file
+//      floors in config/rename-history-baseline.json fall inside them (adr 116, session-logs 15,
+//      audits 3) and NONE falls outside. Rewriting a file with a floor fails the build on purpose:
+//      an ADR rewritten to today's vocabulary destroys the evidence that the words changed.
+//      docs/governance joins them on the same reading: every file in it is a dated authority sweep
+//      or a payment PROOF — an audit filed under another name. docs/recipes/failed-ship-recovery-proof.md
+//      is the one file named individually, for the same reason: it is a transcript of a recovery
+//      that happened, and rewriting the calls it records would make it misreport them.
+//      Everything else under docs/ is now COUNTED, and 1004113 swept it.
 //   7. MIGRATIONS + THE FROZEN RECORD (path-excluded). Same rule as the sibling detector: an
 //      applied migration renamed is an applied migration re-run, and a rewritten ADR destroys the
 //      evidence that the words changed.
@@ -55,6 +66,14 @@
 //      so the ratchet and the sweep agree by construction.
 //   9. CAPTURED FIXTURES (path-excluded). scripts/hall-preview/fixtures/*.json are snapshots of
 //      real API responses; rewriting one would make the fixture misreport what the server returned.
+//  10. A LINE NAMING AN AUTH URL (line-excluded, task 1004113). `/api/gds/auth/...` in prose is the
+//      SAME pinned callback reason 2 path-excludes in code, reached from the docs side: the
+//      Authorization callback URL registered in GitHub's app settings is `${publicOrigin}/api/gds/auth/web/callback`,
+//      and a recipe that teaches a builder to register anything else breaks sign-in for the
+//      instance they are standing up. Seven occurrences across four recipes turn on this, and they
+//      must not be swept to make a number fall. This is a LINE rule rather than a path rule
+//      because the files carrying them (ops-gotchas.md, local-dev.md, staging-environment.md)
+//      are otherwise ordinary live instruction that SHOULD be counted.
 //
 // Usage:
 //   node scripts/gds/api-alias-caller-scan.js            # count + the top offending files
@@ -99,8 +118,15 @@ const ALIAS_EXCLUDED_PATHS = [
   //    files are not tests (clients/bongos-client/index.mjs and its example, scripts/status-probe.mjs)
   //    and the client is exactly the kind of caller this ratchet exists to police.
   /(^|\/)tests?\//,
-  // 6. docs are a separate pass (scope call, see the header)
-  /(^|\/)docs\//,
+  // 6. the FROZEN RECORD under docs/ — narrowed from a blanket `docs/` by task 1004113. These
+  //    three subtrees mirror the frozen-record path list in gds-literal-scan.js and are where all 134
+  //    rename-history floors live; docs/governance is dated audits + payment proofs under another
+  //    name, and the one named file is a transcript of a recovery that happened.
+  /(^|\/)docs\/adr\//,
+  /(^|\/)docs\/session-logs\//,
+  /(^|\/)docs\/audits\//,
+  /(^|\/)docs\/governance\//,
+  /^docs\/recipes\/failed-ship-recovery-proof\.md$/,
   // 7. migrations + the frozen record
   /(^|\/)migrations\//,
   /(^|\/)limitations\//,
@@ -114,6 +140,15 @@ const ALIAS_EXCLUDED_TREES = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|(^|\
 // A line that is ABOUT the alias rather than a caller of it. Rule 8 above.
 const ALIAS_COMMENTARY_RE = /\balias\b|\blegacy\b|\bpermanent\b|\bforever\b/i;
 
+// A line naming an AUTH url under the alias. Rule 10 above: this is the pinned OAuth callback,
+// registered outside the repo, so it is a fact about GitHub's app settings rather than a caller
+// anyone may move. Kept as a line rule because the files it appears in are otherwise countable.
+// Two shapes: the URL itself, and prose ABOUT it — a heading such as "Authorized callback URL must
+// include the full /api/gds path" names the prefix without the /auth/ segment, and sweeping it left
+// the heading contradicting the body two lines below it. Caught in review on task 1004113; the rule
+// is widened rather than the heading rewritten, because the heading is right.
+const ALIAS_PINNED_AUTH_RE = /\/api\/gds\/auth\/|\bcallback\b/i;
+
 function isExcludedPath(relPath) {
   const p = relPath.replace(/\\/g, '/');
   if (ALIAS_EXCLUDED_TREES.test(p)) return true;
@@ -127,6 +162,7 @@ function isCountedLine(line) {
   if (!line.includes(ALIAS)) return false;
   if (line.includes(CANONICAL)) return false;
   if (ALIAS_COMMENTARY_RE.test(line)) return false;
+  if (ALIAS_PINNED_AUTH_RE.test(line)) return false;
   return true;
 }
 
@@ -193,8 +229,10 @@ function main() {
   const show = process.argv.includes('--files') ? ranked : ranked.slice(0, 20);
   console.log(`in-repo /api/gds callers: ${total} across ${ranked.length} file(s) (${scanned} file(s) scanned)`);
   console.log('(the alias contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails,');
-  console.log(' tests/, docs/, migrations/ and captured fixtures are excluded by construction; so is any line that');
-  console.log(' also names /api/bongos or carries the words alias / legacy / permanent / forever)');
+  console.log(' tests/, the FROZEN RECORD under docs/ (adr, session-logs, audits, governance), migrations/ and');
+  console.log(' captured fixtures are excluded by construction; so is any line that also names /api/bongos, carries');
+  console.log(' the words alias / legacy / permanent / forever, or names a pinned /api/gds/auth/ callback URL.');
+  console.log(' The REST of docs/ is counted — live instruction that still teaches the alias should shrink.)');
   console.log('');
   for (const [f, n] of show) console.log(`  ${String(n).padStart(5)}  ${f}`);
   if (show.length < ranked.length) console.log(`  … and ${ranked.length - show.length} more file(s) — pass --files for all`);

package/scripts/gds/cloudbongos-token-isolation.conf

@@ -0,0 +1,33 @@
+# /etc/systemd/system/cloudbongos.service.d/task-1004176-token-isolation.conf
+#
+# task 1004176 / ADR 0327 §5 — the web tier must not be able to read the
+# control-plane cloud tokens. Full rationale, the verification commands and the
+# trap that makes a working config look broken: docs/recipes/ops-gotchas.md,
+# "systemd". Kept there rather than repeated here so one edit cannot leave two
+# copies disagreeing.
+#
+# A drop-in, not a unit edit: cloudbongos.service was hand-written at standup and
+# is not generated from this repo, so an edit to it has no home here. A drop-in
+# is additive, survives a main-unit rewrite, and rolls back by deleting one file.
+#
+# WHAT IS DELIBERATELY ABSENT. The task originally asked for the "standard
+# sandboxing directives" and for the two tiers to run as different unix users.
+# Neither is here, and ADR 0327 §5 records why:
+#   ProtectHome=        would break the web tier outright — its checkout is
+#                       /home/lars/cloudbongos-instance, and the secret-box
+#                       master key it legitimately needs for per-builder AI keys
+#                       is ~/.config/cloudbongos/builder-secret.key.
+#   ProtectSystem=strict needs a ReadWritePaths allowlist that a live site should
+#                       not be handed blind. Worth doing deliberately, later.
+#   PrivateTmp=         unevaluated: nothing established whether the web tier and
+#                       the runners share anything through /tmp. Not guessed at.
+#   different users     would mean relocating the checkout, the config dir,
+#                       web.env and that master key. The namespace gives the same
+#                       protection for this file at a fraction of the risk.
+# NoNewPrivileges is present: no web-tier path shells out with sudo or setuid
+# (checked in src/ and modules/), and 30 days of the unit's own logs contain no
+# escalation or EPERM.
+#
+[Service]
+InaccessiblePaths=/etc/cloudbongos/box.env
+NoNewPrivileges=yes

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

@@ -41,6 +41,12 @@ const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 // changes between the request and the drain.
 const UPGRADE_SHAPES = Object.freeze(new Set(['co-tenant', 'standalone', 'control-plane']));
 
+// The strict three-number form a core version takes. Re-stated here rather than imported
+// from the web tier's core-upgrade.js: a module may not be required from scripts/ (ADR
+// 0083) and this side needs it to guard a SHELL interpolation, which is a stricter duty
+// than validating a request body.
+const CORE_VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
 // The box's own answer to "what core am I running?" — loopback, on the instance's port.
 //
 // THE APEX CANNOT BE ASKED (ADR 0293 D6). It sits behind pre-launch basic_auth and its
@@ -432,6 +438,115 @@ function preflightUpgrade(inst, to, deps) {
   };
 }
 
+// ── WHAT THE MOVE WOULD CARRY (task 1004173) ────────────────────────────────
+//
+// The owner, 2026-09-22: "I don't actually see what would change when I hit the button."
+// The pre-flight above answers a different question — whether the machinery will let the
+// move happen — and answering it was being presented as a preview. ADR 0293 D4 promised
+// both halves in so many words: "the control shows what a bump would move — live version
+// → target, AND WHAT SITS BETWEEN THEM." Only the first half was built, so the owner was
+// asked to restart a live site to take ninety-one releases of work the page named none of.
+//
+// WHERE THE ANSWER ALREADY LIVES. Every ship writes a merge commit whose summary is
+// already prose for exactly this reader — the owner, not a developer — because ship.js
+// 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.
+const CHANGE_CAP = 20;
+const CHANGE_TEXT_MAX = 400;
+
+/**
+ * The merge summaries in a `git log --merges --format=%s%x1f%b%x1e` dump. PURE.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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]; }
+    }
+    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 });
+  }
+  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.
+ */
+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' };
+  // The CONTROL PLANE's executor and the CONTROL PLANE's checkout, never the previewed
+  // instance's: under PROVISION_REMOTE_HOST `exec` is the remote box, and a tenant's own
+  // directory holds no core history at all.
+  const exec = deps.controlExec || deps.exec;
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const dir = selfRoot();
+  const shaOf = (v) => {
+    const r = exec(`git -C ${dir} log --format=%H --max-count=1 -F --grep='release: core ${v} '`, { allowFail: true });
+    const sha = String((r && r.stdout) || '').trim().split('\n')[0] || '';
+    return /^[0-9a-f]{7,40}$/.test(sha) ? sha : null;
+  };
+  const from = shaOf(fromVersion);
+  const to = shaOf(toVersion);
+  if (!from || !to) {
+    return { from: fromVersion, to: toVersion, error: 'could not find those releases in the core history on this machine' };
+  }
+  const r = exec(`git -C ${dir} log --merges --format=%s%x1f%b%x1e ${from}..${to}`, { allowFail: true });
+  if (!r || r.softFailed === true || r.ok === false) {
+    return { from: fromVersion, to: toVersion, error: 'could not read the core history on this machine' };
+  }
+  const all = parseChangeRecords(r.stdout);
+  return { from: fromVersion, to: toVersion, entries: all.slice(0, CHANGE_CAP), more: Math.max(0, all.length - CHANGE_CAP) };
+}
+
 // Run a dry run for one instance and cache its verdict — the ON-DEMAND leg, drained from
 // a `core-upgrade-preflight` intent the owner's arming queues (task 1004121). The tick
 // does not do this: a verdict that is only ever produced on a background schedule is
@@ -446,6 +561,22 @@ async function preflightCoreUpgrade(inst, deps, intent) {
   }
   if (!to) return { ok: false, error: 'no target version to preview' };
   const verdict = (deps.preflightUpgrade || preflightUpgrade)(inst, to, deps);
+  // AND WHAT THE MOVE WOULD CARRY, taken in the same breath (task 1004173). It rides the
+  // verdict rather than a column of its own for the reason the verdict's own `target`
+  // exists: both answers are about ONE move, and storing them together is what makes
+  // "is this still the move on offer" a single question with a single answer. It also
+  // costs the owner no second wait — the dry run is already the thing they are waiting on.
+  //
+  // `from` is the version the box is on RIGHT NOW, read back from the snapshot the tick
+  // writes, and it is stored because the answer is only true of that starting point. The
+  // web tier withholds the list when the box has moved since, the same way it withholds a
+  // verdict taken against a superseded target.
+  let servedNow = null;
+  try {
+    const { rows } = await db.query('SELECT served_version FROM provisioning_core_version_snapshot WHERE instance_id = $1', [inst.id]);
+    servedNow = (rows[0] && rows[0].served_version) || null;
+  } catch { /* no snapshot yet — changesBetween refuses on the missing version, and says so */ }
+  verdict.changes = (deps.changesBetween || changesBetween)(servedNow, to, deps);
   await db.query(
     `INSERT INTO provisioning_core_version_snapshot (instance_id, preflight, preflight_at, observed_at)
      VALUES ($1, $2::jsonb, now(), now())
@@ -537,4 +668,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, changesBetween, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/run-unit-tests.js

@@ -209,15 +209,20 @@ const INTEGRATION = new Set([
 // (V4.R16) diagnosed them as STALE — they predated #481's Narc-advisory change,
 // NOT a grader regression. Now green and back under this gate so the quality-
 // gate brain can't silently regress.
-const KNOWN_FAILING = new Set([
-  // #1002617: red in every clean environment (Linux CI and a Windows checkout
-  // alike), surfaced by the unit lane's first-ever runs. Parked so the `unit`
-  // check can be required (a gate that's already red gates nothing); per-test
-  // diagnoses live in that task. Remove each here as it is fixed.
-  // PAIRING: tests/known_failing_ratchet.mjs keeps EXECUTING each parked test
-  // and fails the suite the moment one starts passing — so this set cannot rot.
-  'served_paths_shipped',
-]);
+// EMPTY, and that is the intended steady state (task 1002617 closed the last entry).
+//
+// This set existed because the unit lane's first-ever runs (task 1002610) surfaced three
+// tests red in every clean environment, and a gate that is already red gates nothing —
+// so they were parked to make `unit` requireable while each was diagnosed. platform_boot
+// and publish_manifest were fixed earlier; served_paths_shipped was the survivor, and its
+// failure turned out to be its own self-guard correctly reporting that the source scan
+// had gone blind when the OpenAPI serve moved to a root ladder (task 1002200).
+//
+// Adding an entry here is a real cost and should be rare: a parked test is invisible
+// coverage, and this one sat parked long enough that its diagnosis had to be redone.
+// PAIRING: tests/known_failing_ratchet.mjs keeps EXECUTING each parked test and fails the
+// suite the moment one starts passing — so this set cannot rot silently.
+const KNOWN_FAILING = new Set([]);
 
 // Task 1003845: on Windows + Node 24 a suite that hard-exits after serving HTTP can
 // print a clean verdict and THEN abort natively (the cliExit class in

package/scripts/hall-preview/server.js

@@ -123,6 +123,11 @@ const FIXTURE_FALLBACKS = [
   // the profile's connections section (task 1002296) — one degree fixture serves
   // any handle, since the handle is the address and the label is the payload.
   [/^connections\/degree\/[^/]+$/, 'connections__degree'],
+  // the deploy door's per-project preview (task 1004171). One fixture serves any id
+  // because the page renders ONE project and the id is the address, not the payload —
+  // without it /deploy?project=… only ever rendered its "could not read" state, which
+  // is the trap this directory's README calls out by name.
+  [/^provisioning\/instances\/\d+\/core-upgrade$/, 'provisioning__instances__core-upgrade'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.972'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.973'; // 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('dev-box'); log.info('mounted');

package/tests/api_alias_caller_ratchet.mjs

@@ -39,7 +39,7 @@ test('a collapsed enumeration is visible as scanned=0, not as a flattering total
 
   const allExcluded = scan.scanAliasCallers(fake({
     'tests/x.mjs': '/api/gds\n',
-    'docs/x.md': '/api/gds\n',
+    'docs/adr/0001-x.md': '/api/gds\n', // frozen record — NOT `docs/x.md`, which counts since task 1004113
   }));
   assert.equal(allExcluded.total, 0);
   assert.equal(allExcluded.scanned, 0, 'an every-path-excluded run is also scanned=0 — the same signal');
@@ -67,7 +67,11 @@ test('the exclusions are real and each one is reachable', () => {
     'scripts/gds/api-alias-caller-scan.js',
     'tests/api_alias_exceptions.mjs',      // 5 tests
     'modules/dev-box/app/test/thing.mjs',
-    'docs/architecture.md',                // 6 docs
+    'docs/adr/0016-permissions.md',        // 6 the FROZEN RECORD under docs/ (narrowed, task 1004113)
+    'docs/session-logs/2026-09-16-x.md',
+    'docs/audits/2026-08-01-x.md',
+    'docs/governance/authority-sweep-2026-07-24.md',
+    'docs/recipes/failed-ship-recovery-proof.md',
     'migrations/033_audit_log.sql',        // 7 migrations
     'scripts/hall-preview/fixtures/tasks.json', // 9 captured fixtures
     'node_modules/pkg/index.js',           // vendored
@@ -81,11 +85,58 @@ test('the exclusions are real and each one is reachable', () => {
     'clients/bongos-client/index.mjs', // a .mjs that is NOT a test — a blanket \.mjs$ would blind the ratchet
     'bin/bongos.js',
     'CLAUDE.md',
+    // task 1004113: live instruction under docs/ is counted. If this list ever goes back to being
+    // excluded, the ~95 occurrences the sweep moved can silently grow back unpoliced.
+    'docs/architecture.md',
+    'docs/canonical-permissions.md',
+    'docs/recipes/parallel-goal-waves.md',
+    'docs/packs/engineer.md',
+    'docs/onboarding/drachmae-and-karma.md',
   ]) {
     assert.equal(scan.isExcludedPath(p), false, `${p} must NOT be excluded`);
   }
 });
 
+// ---------------------------------------------------------------------------
+// task 1004113 — the docs/ split. This is the case the parent task (1004064)
+// deferred, and it is proved in BOTH directions on purpose: a narrowing that
+// only asserts "the frozen record is excluded" would pass identically if the
+// blanket `docs/` exclusion were still in place, which is exactly the vacuous
+// shape this file's header warns about.
+// ---------------------------------------------------------------------------
+
+test('docs/ is SPLIT: the frozen record stays out, live instruction is now counted', () => {
+  const r = scan.scanAliasCallers(fake({
+    'docs/adr/0010-pms-architecture.md': 'GET /api/gds/tasks\n',
+    'docs/session-logs/2026-09-16-x.md': 'GET /api/gds/tasks\n',
+    'docs/audits/2026-08-01-x.md': 'GET /api/gds/tasks\n',
+    'docs/governance/rank-map-2026-08-06.md': 'GET /api/gds/tasks\n',
+    'docs/recipes/failed-ship-recovery-proof.md': 'POST /api/gds/claims/1/resolve\n',
+    'docs/recipes/how-to-do-a-thing.md': 'node scripts/gds/api.js GET /api/gds/tasks/1\n',
+    'docs/packs/engineer.md': 'create a task via POST /api/gds/tasks\n',
+  }));
+  assert.deepEqual(
+    Object.keys(r.byFile).sort(),
+    ['docs/packs/engineer.md', 'docs/recipes/how-to-do-a-thing.md'],
+    'only the instructional docs count — and they MUST count, or the narrowing did nothing',
+  );
+  assert.equal(r.total, 2);
+  assert.equal(r.scanned, 2, 'the frozen-record files are excluded before they are read, not counted as zero');
+});
+
+test('the rename-history floors all sit INSIDE the excluded subtrees — the line is measured, not asserted', () => {
+  // The narrowing's load-bearing evidence: rename-history-check.js fails the build when the old
+  // name is ERASED from a file with a floor, so a docs sweep could have failed a DIFFERENT gate.
+  // It did not, because every floor is in a subtree this scanner still excludes. If a floor is ever
+  // added outside them, this reds and whoever added it has to decide which gate wins.
+  const floors = Object.keys(
+    JSON.parse(readFileSync(path.join(ROOT, 'config', 'rename-history-baseline.json'), 'utf8')).frozenLiteralFloors || {},
+  );
+  assert.ok(floors.length > 100, `the baseline must actually carry floors (got ${floors.length})`);
+  const outside = floors.filter((f) => !scan.isExcludedPath(f));
+  assert.deepEqual(outside, [], 'a file with a rename-history floor must never be inside the caller ratchet');
+});
+
 test('a line ABOUT the alias is not a caller of it — and the rule is not so loose it excuses everything', () => {
   // Excluded: names the canonical prefix too, or says what it is.
   assert.equal(scan.isCountedLine('mount /api/bongos and /api/gds'), false);
@@ -100,6 +151,21 @@ test('a line ABOUT the alias is not a caller of it — and the rule is not so lo
   assert.equal(scan.isCountedLine('a line about a legacy alias, forever'), false);
 });
 
+test('a PINNED auth URL is not a caller anyone may move (rule 10, task 1004113)', () => {
+  // These are registered in GitHub's OAuth app settings. A recipe that teaches a builder to
+  // register /api/bongos/auth/web/callback breaks sign-in on the instance they are standing up,
+  // so the ratchet must never create pressure to rewrite them.
+  assert.equal(scan.isCountedLine('  https://example.com/api/gds/auth/web/callback'), false);
+  assert.equal(scan.isCountedLine('the server sends `${publicOrigin}/api/gds/auth/web/callback`'), false);
+  assert.equal(scan.isCountedLine('`/api/gds/auth/web/start` = no session'), false);
+  // …and prose ABOUT that URL, which names the prefix without the /auth/ segment. Sweeping this
+  // heading left it contradicting its own body two lines down; caught in review on 1004113.
+  assert.equal(scan.isCountedLine('### Authorized callback URL must include the full /api/gds path'), false);
+  // The rule is NOT so wide that an ordinary caller in an auth-adjacent file escapes it.
+  assert.equal(scan.isCountedLine('node scripts/gds/api.js GET /api/gds/me'), true);
+  assert.equal(scan.isCountedLine('POST /api/gds/auth-free/thing'), true, 'only the /auth/ segment, not any word starting auth');
+});
+
 test('occurrences are counted, not lines — moving ONE of two callers on a line lowers the number', () => {
   assert.equal(scan.countInText('f("/api/gds/a"); f("/api/gds/b");\n'), 2);
   assert.equal(scan.countInText('f("/api/bongos/a"); f("/api/gds/b");\n'), 0, 'the canonical name on the line is the alias-commentary rule, by design');

package/tests/core_upgrade_door.mjs

@@ -756,5 +756,86 @@ await t('lastCoreMove reads MOVES only — a preview refusal is not a failed dep
   assert.deepEqual(seen[0].params, [41]);
 });
 
+
+console.log('\nthe change list is withheld when the box has moved since (task 1004173):');
+
+const PF = (over = {}) => ({ target: '1.19.949', ok: true, lines: [], error: null,
+  changes: { from: '1.19.900', to: '1.19.949', entries: [{ text: 'a thing landed' }], more: 0 }, ...over });
+
+await t('a verdict taken from where the box IS keeps its change list', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, preflight: PF() }, null, null);
+  assert.equal(p.preflight.changes.entries.length, 1);
+});
+
+await t('THE LIST GOES WHEN THE BOX HAS MOVED — the verdict beside it does NOT', () => {
+  // Two independent staleness questions. The verdict is about a TARGET; the list is
+  // about a RANGE, so it also depends on where the box starts. Dropping both would throw
+  // away a good verdict; dropping neither would show a range starting somewhere the box
+  // no longer is.
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, served_version: '1.19.930', preflight: PF() }, null, null);
+  assert.equal(p.preflight.changes, null, 'the range no longer starts where the box is');
+  assert.equal(p.preflight.ok, true, 'but the check is still a true answer about this target');
+  assert.equal(p.preflight.target, '1.19.949');
+});
+
+await t('a verdict about a SUPERSEDED target is withheld whole, list and all', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, preflight: PF({ target: '1.19.920' }) }, null, null);
+  assert.equal(p.preflight, null, 'a stale pass reads as a guarantee — worse than no answer');
+});
+
+await t('withholding does not MUTATE the cached verdict', () => {
+  // previewFromSnapshot runs per request over a row the caller may reuse; blanking the
+  // list in place would make the second reader see a range the first one invalidated.
+  const snap = { ...SNAP, served_version: '1.19.930', preflight: PF() };
+  CU.previewFromSnapshot(ACTIVE, snap, null, null);
+  assert.ok(snap.preflight.changes, 'the snapshot is untouched');
+});
+
+console.log('\nis the last move still NEWS, or history the box moved past? (task 1004172):');
+
+await t('a failure the box has already moved past is marked superseded', () => {
+  // The live defect, 2026-09-22: the control plane's row led with "The move to core
+  // 1.19.921 did not land", undated, while the box served 1.19.969 and a move to
+  // 1.19.972 was on offer. Two days old, a different target, and a cause fixed and
+  // released in between — all of it rendered as the present.
+  const old = { action: 'core-upgrade', state: 'error', target_version: '1.19.921', resolved_at: new Date().toISOString(), last_error: 'Postgres has no role "root"' };
+  const p = CU.previewFromSnapshot(ACTIVE, SNAP, null, old);
+  assert.equal(p.last_move.superseded, true, 'a different move is on offer now');
+});
+
+await t('a failure against the move STILL on offer is NOT superseded', () => {
+  const now = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'working tree not clean' };
+  const p = CU.previewFromSnapshot(ACTIVE, SNAP, null, now);
+  assert.equal(p.last_move.superseded, false, 'this is the button in front of the owner');
+});
+
+await t('a box that reached the target by another road supersedes the failure', () => {
+  // The exact shape of the live case: the move failed, and the version arrived anyway.
+  const old = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'x' };
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, served_version: '1.19.949', recommended: '1.19.949' }, null, old);
+  assert.equal(p.last_move.superseded, true);
+});
+
+await t('AN UNREADABLE REGISTRY LEAVES A FAILURE STANDING — not knowing is not evidence of recovery', () => {
+  const now = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'x' };
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, recommended: null }, null, now);
+  assert.equal(p.last_move.superseded, false, 'the direction to fail in is showing an old failure, never hiding a live one');
+});
+
+await t('lastMoveSuperseded computes no version ORDERING — only identity', () => {
+  // The page's standing rule is that no version comparison happens outside the runner's
+  // channel resolution. This helper answers "is this news" without ever asking which of
+  // two versions is newer, and the source is held to that.
+  const src = read('modules', 'provisioning', 'core-upgrade.js');
+  const body = /function lastMoveSuperseded\([^)]*\) \{([\s\S]*?)\n\}/.exec(src);
+  assert.ok(body, 'the helper is there to read');
+  assert.doesNotMatch(body[1], /parseVersion|semver|split\(/, 'no version parsing');
+  assert.doesNotMatch(body[1], /[<>]=?/, 'and no ordering comparison');
+  // And it is genuinely reachable both ways from the same inputs.
+  assert.equal(CU.lastMoveSuperseded(null, '1.19.900', '1.19.949'), false, 'no target is not superseded');
+  assert.equal(CU.lastMoveSuperseded('1.19.949', '1.19.900', '1.19.949'), false);
+  assert.equal(CU.lastMoveSuperseded('1.19.921', '1.19.900', '1.19.949'), true);
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);