@bongos/core 1.19.1031 → 1.19.1033

package/scripts/gds/upgrade.js

@@ -8,7 +8,7 @@
 //   pre-flight   clean git tree + module-compat vs the TARGET core version + the artist gate (ADR 0241)
 //     → bump pin   vendor the new core .tgz, rewrite the package.json `file:` dependency
 //     → npm install  node_modules/@bongos/core becomes the new version
-//     → migrate      `npm run migrate` → the core's migrate.sh applies additive `core_*` migrations
+//     → migrate      `npm run migrate` (no such script: the core's migrate.sh itself, upgrade-migrate.js) applies additive `core_*` migrations
 //     → materialize  refresh .claude/ skills+settings+hooks from the new core (claude-materialize / W3)
 //     → restart      restart the instance's service so the new core is live
 //     → verify       installed package version == target (+ optional /healthz + ledger row)
@@ -538,7 +538,8 @@ function preflightDbIdentity({ instanceDir, db }, run = spawnSync) {
 }
 
 function runMigrate(instanceDir, run = spawnSync) {
-  const r = run('npm', ['run', 'migrate'], { cwd: instanceDir, stdio: 'inherit' });
+  const { cmd, args, env } = require('./upgrade-migrate').migratePlan(instanceDir); // its own migrate script, else the core's migrate.sh (task 1004274)
+  const r = run(cmd, args, { cwd: instanceDir, stdio: 'inherit', ...(env ? { env } : {}) });
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
@@ -1142,6 +1143,7 @@ async function runUpgrade(opts, deps = {}) {
     if (!dbId.ok) return { ok: false, error: dbId.reason };
     if (dbId.skipped) log(`  • db identity pre-check${db ? ` (${db})` : ''}: ${dbId.skipped}`);
     else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as the current user`);
+    const { note: migrateNote } = require('./upgrade-migrate').migratePlan(instanceDir); if (migrateNote) log(`  ✓ pre-flight: ${migrateNote}`);
   }
 
   // 1a. artist gate (ADR 0241, task 1004205): an open review holds the pin, --force too; a downgrade never waits.
@@ -1181,7 +1183,7 @@ async function runUpgrade(opts, deps = {}) {
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
   }
 
-  if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
+  if (dryRun) { log(`  [dry-run] would: npm install → ${opts.skipMigrate ? '(no migrate)' : require('./upgrade-migrate').migratePlan(instanceDir).label} → materialize .claude → regen API docs+client → restart → verify`); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
 
   // 3. npm install.
   const inst = npmInstall(instanceDir, run);
@@ -1455,7 +1457,7 @@ async function main(argv = process.argv.slice(2)) {
       '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
       '  --version-url <url>  read the RUNNING process\'s coreVersion back after restart and require it to equal --to (default: /version on the --health-url origin). A health check alone cannot tell a new core from an old one that never went down.',
       '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves); also skips the served-version read-back',
-      '  --skip-migrate       do not run `npm run migrate`',
+      '  --skip-migrate       do not migrate (the default runs the instance\'s `migrate` script, else the core\'s scripts/migrate.sh)',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
       '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',

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.1031'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1033'; // 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/adr_0162_citation.mjs

@@ -0,0 +1,184 @@
+// tests/adr_0162_citation.mjs — "a verdict is advisory, never self-executing" is
+// ADR 0158 §2's rule, not ADR 0162's; no surface may cite 0162 for it (task 1003573).
+//
+// WHAT WENT WRONG. ADR 0162 retired REVIEW gates on `main`: no human approval sits in
+// the land path, and the compensating controls it keeps are automatic — three of its
+// four fail CLOSED, the grader among them. Surfaces across the repo nonetheless cited it
+// by a slogan, "verdicts are advisory, never self-executing". ADR 0241 caught that the
+// slogan is false as a blanket claim about gates. This task found the slogan is not
+// 0162's wording at all: it is, nearly verbatim, the heading of ADR 0158 §2 — a rule
+// about what an audit FINDING authorizes (nothing, until a human acts on it). So every
+// gloss of 0162 with that slogan cited the wrong ADR, and the worst of them turned it
+// into a claim 0162 contradicts ("grader verdicts are advisory").
+//
+// WHAT THIS PINS. (1) The premise, read from the two ADRs themselves: the slogan's text
+// is in 0158 and absent from 0162. If either ADR is amended, this goes red and the
+// question is re-asked, instead of the citations quietly drifting back. (2) No tracked
+// surface glosses 0162 with the verdict rule, in any of the shapes the sweep found.
+//
+// Run:  node --test tests/adr_0162_citation.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+
+const ADR_0158 = 'docs/adr/0158-choke-point-verdict-taxonomy.md';
+const ADR_0162 = 'docs/adr/0162-review-gates-retired-rank-consistent-ci-only.md';
+
+// The shapes the 2026-09-25 sweep found, each named by the surface it came from.
+// A match is a line that attributes the verdict rule to 0162.
+const MISATTRIBUTIONS = [
+  // 0162 glossed with the rule: "0162 (verdicts advisory, never self-executing)",
+  // "0162 (grader verdicts are advisory…)", "[ADR 0162] (patrol findings are advisory…)",
+  // "ADR 0162 — verdicts never self-execute", "[ADR 0162]: verdicts advisory".
+  /\b0162\b[\])]?\s*(?:\(|—|–|:|=)\s*(?:[\w-]+\s+){0,2}(?:verdicts?|findings?)\b[^\n]{0,30}?\b(?:advisory|self-execut)/i,
+  // The rule, then 0162 as its source: "findings are advisory (ADR 0162)",
+  // "never self-executes (ADR 0162)", "advisory per ADR 0162", "(advisory, ADR 0162)".
+  /\b(?:advisory|self-execut\w*)\b\**\s*(?:\(ADR\s+0162\b|,\s*ADR 0162\b|per ADR 0162\b)/i,
+  // 0162's real content, then the rule tacked on as if it were 0162's too:
+  // "[ADR 0162] — review gates retired on `main`; a verdict is advisory and never …".
+  /\b0162\b[^\n]{0,70};\s*an? verdicts? (?:is|are) advisory/i,
+  // The rule's consequences cited to 0162: "filed for adjudication (ADR 0162)",
+  // "describe-only (ADR 0162)", "describes and queues only, never confirms (ADR 0162".
+  /\b(?:adjudicat\w*|describe-only|describes and queues only)\b[^\n]{0,45}?\(ADR 0162\b/i,
+  // The rule as the sentence that follows a 0162 citation:
+  // "(ADR 0162).** Verdicts are advisory", "The ADR 0162 discipline.** Verdicts are advisory".
+  /\b0162\)?(?: discipline)?\.?\**\s*Verdicts? (?:is|are) advisory/i,
+  // "the same family of error ADR 0162 rules out" — 0162 rules out no verdict-handling.
+  /\bADR 0162 rules out\b/i,
+  // "ADVISORY ONLY, same posture as ADR 0162" / "ADR 0162: advisory only".
+  /\badvisory only\b[^\n]{0,30}\bADR 0162\b|\bADR 0162\b[^\n]{0,30}\badvisory only\b/i,
+  // "it stays advisory in precisely 0162's sense" — the sense is 0158 §2's.
+  /\badvisory in (?:precisely|exactly) (?:ADR )?0162's sense\b/i,
+  // "ADR 0162's "advisory, never self-executing" holding" (a migration comment).
+  /\b0162's\s+["“]?(?:advisory|never self-execut)/i,
+];
+
+// Deliberately NOT corrected, each with its reason. Shrink-only: when one of these is
+// fixed, delete its row — the last test below fails until you do, so a stale exemption
+// cannot outlive the thing it excused.
+const KNOWN_DEFERRED = new Map([
+  // A comment on a HARD-FLOOR gate surface (scripts/gds/gate-review.js HARD_FLOOR_GLOBS
+  // lists `.github/`): even a comment-only edit there escalates to the owner, which a
+  // citation fix does not justify on its own. Correct it with the next real edit.
+  ['.github/workflows/redteam-patrol.yml', 'hard-floor gate surface'],
+  // An applied migration is never edited: its text is part of what was run.
+  ['modules/government/migrations/government_004_board_permissions.sql', 'applied migration'],
+]);
+
+// A session log records what a session believed at the time; rewriting one would
+// falsify history, which is worse than the stale citation it carries.
+const HISTORICAL = /^docs\/session-logs\//;
+// This file quotes every shape it hunts, as examples — so it would flag itself.
+const SELF = 'tests/adr_0162_citation.mjs';
+const TEXT = /\.(?:md|js|mjs|cjs|json|ya?ml|sql|sh|html|txt)$/;
+
+// A line that NAMES the slogan as its subject is discussing it (ADR 0241's own
+// analysis; the task-title list in a relevance audit), not citing by it.
+const DISCUSSES_SLOGAN = /paraphrase|shorthand/i;
+
+// Markdown link targets carry the ADR's filename ("0162-review-gates-…"), which would
+// otherwise sit between a citation and its gloss.
+const stripLinkTargets = (s) => s.replace(/\]\([^)\s]*\)/g, ']');
+// The continuation of a hard-wrapped line, minus its comment/quote/list lead.
+const continuation = (s) => (s || '').replace(/^\s*(?:\/\/+|#+|--|\*|>|-)?\s*/, '');
+
+function offendersIn(rel, text) {
+  const lines = stripLinkTargets(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    const here = lines[i];
+    if (DISCUSSES_SLOGAN.test(here)) continue;
+    // Join the next line so a citation wrapped mid-phrase ("(ADR\n0162)") still reads
+    // as one; only a match that STARTS on this line is this line's.
+    const window = `${here} ${continuation(lines[i + 1])}`;
+    if (!/0162/.test(window)) continue;
+    for (const re of MISATTRIBUTIONS) {
+      const m = re.exec(window);
+      if (m && m.index < here.length) { hits.push(`${rel}:${i + 1}: ${here.trim().slice(0, 140)}`); break; }
+    }
+  }
+  return hits;
+}
+
+function trackedTextFiles() {
+  const r = spawnSync('git', ['ls-files', '-z'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) return null; // a packaged core is not a git checkout
+  return r.stdout.split('\0').filter((f) => f && TEXT.test(f));
+}
+
+test('the premise: the verdict rule is written in ADR 0158 §2, and ADR 0162 never states it', () => {
+  const adr0158 = read(ADR_0158);
+  assert.match(adr0158, /^### 2\. A verdict is advisory and never self-executing$/m,
+    'ADR 0158 §2 is the rule\'s source — if it moved, re-point the citations this test guards');
+  const adr0162 = read(ADR_0162);
+  assert.doesNotMatch(adr0162, /self-execut/i, 'ADR 0162 does not say "self-executing"');
+  assert.doesNotMatch(adr0162, /advisory/i, 'ADR 0162 does not say "advisory"');
+  // What 0162 DOES say, so a citation of it has something true to point at.
+  assert.match(adr0162, /Review requirements on `main` are \*\*retired permanently\*\*/);
+});
+
+test('the detector recognises every shape the sweep corrected, and passes the true citations', () => {
+  const flag = (line) => offendersIn('probe.md', line).length > 0;
+  for (const bad of [
+    '- **Related:** 0157 (Archon is rank and identity only), 0162 (verdicts advisory, never self-executing), 0172',
+    '0016 (authority resolved server-side), 0162 (grader verdicts are advisory, never self-executing), 0175',
+    '- **Related:** [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) (patrol findings are advisory — verdicts never self-execute),',
+    '// doctrine (ADR 0162 — verdicts never self-execute): findings are FILED as',
+    'deliberate. Findings are **advisory** (ADR 0162) — they are filed for',
+    'description: `Weekly deterministic red-team patrol (task 1003128; advisory per ADR 0162 — adjudicate)`',
+    '//     is that: history-wide, time-based, filed for adjudication (ADR 0162).',
+    '- **Read-only, describe-only (ADR 0162).** No confirms, no regrades run by this skill.',
+    '- **Never confirm, never flip, never re-grade (ADR 0162).** Verdicts are advisory and never self-executing here',
+    '**1. The ADR 0162 discipline.** Verdicts are advisory and never self-executing. A gate that',
+    'judgement is finished because a hash moved — the same family of error ADR 0162 rules out for grader',
+    '// HARD CONSTRAINT, same as goal-advisory.js and ADR 0162: advisory only. This',
+    'it stays advisory in precisely 0162\'s sense.',
+    '- **Reconciles:** [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) — review gates retired on `main`; a verdict is advisory and never self-executing',
+    '→ files security reports (advisory, ADR 0162). FIRED BY .github/workflows/redteam-patrol.yml',
+    '-- — which is also ADR 0162\'s "advisory, never self-executing" holding.',
+    'decision 2026-08-18: AI review deferred), and findings are **advisory** (ADR\n0162): they are POSTed to',
+  ]) assert.ok(flag(bad), `should flag: ${bad}`);
+
+  for (const good of [
+    '- **Reconciles:** [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) — review gates retired on `main`, so no human approval sits in the land path',
+    '0016 (authority resolved server-side), 0158 §2 (a verdict is advisory, never self-executing), 0162 (review gates retired — no human approval in the land path), 0175',
+    'deliberate. Findings are **advisory** (ADR 0158 §2) — they are filed for',
+    '- **Related:** ADR 0162 (no new human gates on the ship path)',
+    'No review requirement — gates are CI checks, not human approvals (ADR 0162).',
+    'It never holds a builder\'s ship, which is what keeps it compatible with ADR 0162.',
+    'This matters, because the shorthand it is usually cited by — "a verdict is advisory" (ADR 0162) — is a paraphrase',
+  ]) assert.ok(!flag(good), `should pass: ${good}`);
+});
+
+test('no tracked surface cites ADR 0162 for the verdict rule', (t) => {
+  const files = trackedTextFiles();
+  if (!files) return t.skip('not a git checkout — nothing tracked to scan');
+  const offenders = [];
+  for (const rel of files) {
+    if (rel === SELF || HISTORICAL.test(rel) || KNOWN_DEFERRED.has(rel)) continue;
+    let text;
+    try { text = readFileSync(path.join(ROOT, rel), 'utf8'); } catch { continue; }
+    if (!text.includes('0162')) continue;
+    offenders.push(...offendersIn(rel, text));
+  }
+  assert.deepEqual(offenders, [],
+    'these cite ADR 0162 for "a verdict is advisory, never self-executing" — that rule is ADR 0158 §2. '
+    + 'Cite 0158 §2 for the verdict rule, and 0162 only for what it retired (human approval in the land path).');
+});
+
+test('every deferred exemption still has something to excuse (shrink-only)', (t) => {
+  if (!trackedTextFiles()) return t.skip('not a git checkout');
+  for (const [rel, why] of KNOWN_DEFERRED) {
+    let text = '';
+    try { text = read(rel); } catch { /* deleted: the exemption is stale too */ }
+    assert.ok(offendersIn(rel, text).length > 0,
+      `${rel} (${why}) no longer misattributes the rule — delete its KNOWN_DEFERRED row`);
+  }
+});

package/tests/autobongos_loop.mjs

@@ -654,3 +654,117 @@ test('workerEnv passes Claude auth through, and still refuses the rest', () => {
     assert.equal(env[leak], undefined, `${leak} must never reach a bypassPermissions worker`);
   }
 });
+// --- a derived gauge buys BOUNDED work (task 1004178) -----------------------
+//
+// `derived` retires a reading whose window has reset. That is sound for the
+// five-hour window, which turns over during a night. The SEVEN-day one does
+// not, so its stale reading is dropped and the weekly pace check — what the
+// module's notes call the thing that actually binds a heavy week — does not run
+// at all on a derived reading. The task cap is what stands in for it, so the
+// cap has to work, and it has to survive a restart: the count comes from the
+// run log, not from memory.
+
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const derivedLog = () => {
+  const dir = mkdtempSync(join(tmpdir(), 'autobongos-cap-'));
+  return join(dir, 'runs.jsonl');
+};
+
+test('countWorkedSince counts only worked rows at or after the mark', () => {
+  const p = derivedLog();
+  process.env.AUTOBONGOS_LOG_FILE = p;
+  const at = (s) => new Date(s * 1000).toISOString();
+  writeFileSync(p, [
+    JSON.stringify({ at: at(1000), event: 'worked', task_id: '1' }),   // before the mark
+    JSON.stringify({ at: at(3000), event: 'hold' }),                   // not a worked row
+    JSON.stringify({ at: at(3100), event: 'worked', task_id: '2' }),
+    '{ this line is torn',                                             // costs one row, not the count
+    JSON.stringify({ at: at(3200), event: 'worked', task_id: '3' }),
+  ].join('\n'));
+  assert.equal(runner.countWorkedSince(2000), 2);
+  assert.equal(runner.countWorkedSince(0), 0, 'a zero/absent mark counts nothing rather than everything');
+  delete process.env.AUTOBONGOS_LOG_FILE;
+});
+
+test('countWorkedSince treats an unreadable log as zero, not as a refusal', () => {
+  process.env.AUTOBONGOS_LOG_FILE = join(tmpdir(), 'autobongos-cap-nope', 'missing.jsonl');
+  assert.equal(runner.countWorkedSince(1), 0,
+    'the fence and the gauge are the gates; a bound that bricks the runner when its own log is gone is worse');
+  delete process.env.AUTOBONGOS_LOG_FILE;
+});
+
+test('a derived gauge HOLDS once the cap is reached, and the reason says why', async () => {
+  const p = derivedLog();
+  process.env.AUTOBONGOS_LOG_FILE = p;
+  process.env.AUTOBONGOS_DERIVED_TASK_CAP = '2';
+  const at = (s) => new Date(s * 1000).toISOString();
+  writeFileSync(p, [
+    JSON.stringify({ at: at(5100), event: 'worked', task_id: '1' }),
+    JSON.stringify({ at: at(5200), event: 'worked', task_id: '2' }),
+  ].join('\n'));
+
+  const events = [];
+  await runner.iteration({ goals: [], maxTasks: 1 }, {
+    readFence: async () => ({ raw: { enabled: true, goals: [{ goal_id: 7 }] }, graderBypassed: false }),
+    gauge: () => ({ decision: { go: true, unknown: false, derived: true, derivedSince: 5000, reason: 'derived' } }),
+    pickTask: async () => { throw new Error('CAP BREACHED: reached the picker'); },
+    record: (row) => { events.push(row); return row; },
+    run: async () => { throw new Error('CAP BREACHED: ran a command'); },
+    spawnWorker: async () => { throw new Error('CAP BREACHED: spawned a worker'); },
+  });
+  assert.equal(events[0].event, 'hold');
+  assert.equal(events[0].derived, true);
+  assert.equal(events[0].worked_since_derived, 2);
+  assert.match(events[0].reason, /cap is 2/);
+  delete process.env.AUTOBONGOS_LOG_FILE; delete process.env.AUTOBONGOS_DERIVED_TASK_CAP;
+});
+
+test('a derived gauge still WORKS while under the cap', async () => {
+  const p = derivedLog();
+  process.env.AUTOBONGOS_LOG_FILE = p;
+  process.env.AUTOBONGOS_DERIVED_TASK_CAP = '2';
+  writeFileSync(p, JSON.stringify({ at: new Date(5100 * 1000).toISOString(), event: 'worked', task_id: '1' }));
+  let reachedPicker = false;
+  const events = [];
+  await runner.iteration({ goals: [], maxTasks: 1 }, {
+    readFence: async () => ({ raw: { enabled: true, goals: [{ goal_id: 7 }] }, graderBypassed: false }),
+    gauge: () => ({ decision: { go: true, unknown: false, derived: true, derivedSince: 5000, reason: 'derived' } }),
+    pickTask: async () => { reachedPicker = true; return { none: true, skipped: [] }; },
+    record: (row) => { events.push(row); return row; },
+  });
+  assert.equal(reachedPicker, true, 'one task done against a cap of two must still proceed');
+  delete process.env.AUTOBONGOS_LOG_FILE; delete process.env.AUTOBONGOS_DERIVED_TASK_CAP;
+});
+
+test('countWorkedSince is bounded: a huge log does not mean a huge scan', () => {
+  const p = derivedLog();
+  process.env.AUTOBONGOS_LOG_FILE = p;
+  const at = (s) => new Date(s * 1000).toISOString();
+  // 40k old rows, then the two that matter. A whole-file parse would touch
+  // every one of them on EVERY iteration of a loop that never exits.
+  const old = [];
+  for (let i = 0; i < 40000; i++) old.push(JSON.stringify({ at: at(1000 + i), event: 'worked', task_id: String(i) }));
+  old.push(JSON.stringify({ at: at(900000), event: 'worked', task_id: 'recent-1' }));
+  old.push(JSON.stringify({ at: at(900100), event: 'worked', task_id: 'recent-2' }));
+  writeFileSync(p, old.join('\n'));
+  const t0 = Date.now();
+  assert.equal(runner.countWorkedSince(800000), 2, 'only the rows at or after the mark count');
+  assert.ok(Date.now() - t0 < 500, 'and it must not walk the whole log to say so');
+  delete process.env.AUTOBONGOS_LOG_FILE;
+});
+
+test('countWorkedSince stops at the first row older than the mark', () => {
+  const p = derivedLog();
+  process.env.AUTOBONGOS_LOG_FILE = p;
+  const at = (s) => new Date(s * 1000).toISOString();
+  writeFileSync(p, [
+    JSON.stringify({ at: at(100), event: 'worked', task_id: 'ancient' }),
+    JSON.stringify({ at: at(5000), event: 'worked', task_id: 'before-mark' }),
+    JSON.stringify({ at: at(9000), event: 'worked', task_id: 'after-mark' }),
+  ].join('\n'));
+  assert.equal(runner.countWorkedSince(8000), 1);
+  delete process.env.AUTOBONGOS_LOG_FILE;
+});

package/tests/autonomy_gauge.mjs

@@ -342,3 +342,59 @@ test('evaluate on a missing file is UNKNOWN — the CLI never defaults to go', (
     assert.equal(d.unknown, true);
   });
 });
+
+// --- a reading whose window has RESET is retired, not stale (task 1004178) ---
+//
+// An unattended host cannot refresh the gauge (see modules/autonomy/CLAUDE.md
+// for the evidence). These pin the behaviour that makes it survivable.
+
+test('an aged-out reading whose window has RESET is derived, not unknown', () => {
+  const now = 100000;
+  const g = {
+    written_at: now - 10 * HOUR,
+    five_hour: { used_percentage: 92, resets_at: now - 2 * HOUR, observed_at: now - 10 * HOUR },
+  };
+  const d = decideCapacity({ gauge: g, now });
+  assert.equal(d.go, true, 'the window it described has ended; 92% is no longer a fact about now');
+  assert.equal(d.unknown, false);
+  assert.equal(d.derived, true, 'and it must SAY so — the caller bounds work on a derived reading');
+  assert.equal(d.derivedSince, now - 2 * HOUR, 'the reset it stands on, so the cap has a start');
+});
+
+test('an aged-out reading whose window is STILL RUNNING stays unknown', () => {
+  const now = 100000;
+  const g = {
+    written_at: now - 10 * HOUR,
+    five_hour: { used_percentage: 92, resets_at: now + HOUR, observed_at: now - 10 * HOUR },
+  };
+  const d = decideCapacity({ gauge: g, now });
+  assert.equal(d.go, false, 'usage only GROWS inside a window, so an old 92% is a floor, never headroom');
+  assert.equal(d.unknown, true);
+});
+
+test('a fresh reading is unchanged and is never marked derived', () => {
+  const now = 100000;
+  const g = {
+    written_at: now - 60,
+    five_hour: { used_percentage: 10, resets_at: now + HOUR, observed_at: now - 60 },
+    seven_day: { used_percentage: 5, resets_at: now + 6 * 24 * HOUR, observed_at: now - 60 },
+  };
+  const d = decideCapacity({ gauge: g, now });
+  assert.equal(d.go, true);
+  assert.equal(d.derived, false);
+  assert.equal(d.derivedSince, null);
+});
+
+test('a derived seven-day window is NOT paced against a boundary we invented', () => {
+  const now = 100000;
+  // 90% used and only just past its reset: paced, this would refuse. But the
+  // boundary is inferred, so pacing it measures progress through a week nobody
+  // observed. Skipped rather than faked.
+  const g = {
+    written_at: now - 10 * HOUR,
+    seven_day: { used_percentage: 90, resets_at: now - HOUR, observed_at: now - 10 * HOUR },
+  };
+  const d = decideCapacity({ gauge: g, now });
+  assert.equal(d.derived, true);
+  assert.equal(d.go, true);
+});

package/tests/core_upgrade_runner.mjs

@@ -886,15 +886,26 @@ await t('a paragraph-long summary is bounded — it reaches a DOM', () => {
 // A box that really does hold a core checkout. `repos` maps a directory to what git
 // there answers: `core` (a real core checkout), `notCore` (a git repo of something else),
 // `shallow`, `owned` (git refuses on ownership) or absent (not a git repo).
+//
+// The release notes the core PACKAGE carries (task 1004218) are asked first, and are
+// stubbed here: none unless a test hands some in, so the checkout tests below exercise the
+// fallback — and no test in this file can ever reach the real registry.
 const changeDeps = ({
   shas = { '1.19.900': 'a'.repeat(40), '1.19.949': 'b'.repeat(40) },
   log = LOG, logOk = true, repos = { '/srv/core': 'core' }, env = {}, privileged = false,
+  installedNotes = null, packagedNotes = null,
 } = {}) => {
   const ran = [];
+  const downloaded = [];
   return {
-    ran, env, privileged,
+    ran, downloaded, env, privileged,
     selfInstanceRoot: () => '/srv/core',
     appUser: () => 'appacct',
+    readInstalledNotes: () => (installedNotes ? { notes: installedNotes } : { missing: 'this core carries no release notes' }),
+    readPackagedNotes: (v) => {
+      downloaded.push(v);
+      return packagedNotes ? { notes: packagedNotes } : { missing: `the core ${v} package carries no release notes` };
+    },
     exec: (cmd) => {
       ran.push(cmd);
       const dir = (/git -C (\S+) /.exec(cmd) || [])[1];
@@ -1051,6 +1062,83 @@ await t('a long range is capped, and says how many it did not list', () => {
   assert.equal(r.more, 5, 'the remainder is counted, not silently dropped');
 });
 
+// ---- THE NOTES THE PACKAGE CARRIES, asked first (task 1004218) --------------------
+
+// What the packer writes into release-notes.json: one key per release, what each brought in.
+const NOTES = {
+  '1.19.900': [{ text: 'already live before the move' }],
+  '1.19.901': [{ id: '1004001', text: 'the first thing the move brings' }],
+  '1.19.920': [],
+  '1.19.949': [{ id: '1004003', text: 'the target itself' }, { text: 'a hand-landed ship in the target' }],
+  '1.19.950': [{ text: 'after the target, so not part of this move' }],
+};
+
+await t('THE PACKAGE’S NOTES ANSWER FIRST — on a box with no checkout, and with no git run at all', () => {
+  // A tenant box, which is every box but the one that builds the core: no core history.
+  const d = changeDeps({ packagedNotes: NOTES, repos: {} });
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.equal(r.error, undefined);
+  assert.deepEqual(r.entries.map((e) => e.text),
+    ['the target itself', 'a hand-landed ship in the target', 'the first thing the move brings'], 'newest release first');
+  assert.equal(r.source, 'release-notes');
+  assert.deepEqual(d.ran, [], 'not one git command');
+  assert.deepEqual(d.downloaded, ['1.19.949'], "the TARGET's own package is the one read");
+});
+
+await t('the range is (from, to]: what the box already runs is not listed, what the target carries is', () => {
+  const texts = R.changesBetween('1.19.900', '1.19.949', changeDeps({ packagedNotes: NOTES })).entries.map((e) => e.text);
+  assert.ok(!texts.includes('already live before the move'), '`from` is exclusive');
+  assert.ok(texts.includes('the target itself'), '`to` is inclusive');
+  assert.ok(!texts.includes('after the target, so not part of this move'));
+});
+
+await t('the INSTALLED core’s notes answer alone when they already reach the target — nothing is downloaded', () => {
+  const d = changeDeps({ installedNotes: NOTES });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 3);
+  assert.deepEqual(d.downloaded, [], 'a tenant catching up to where the platform already is costs no download');
+});
+
+await t('installed notes that stop SHORT of the target send it to the target’s package', () => {
+  const d = changeDeps({ installedNotes: { '1.19.900': [], '1.19.901': [{ text: 'x' }] }, packagedNotes: NOTES });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 3);
+  assert.deepEqual(d.downloaded, ['1.19.949']);
+});
+
+await t('notes that BEGIN after the box’s version are not used — the list would look whole and be short', () => {
+  // A bounded file drops its oldest releases. Answering a range that reaches back past
+  // where it begins would silently omit what it no longer holds.
+  const r = R.changesBetween('1.19.850', '1.19.949', changeDeps({ packagedNotes: NOTES, repos: {} }));
+  assert.equal(r.entries, undefined, 'no list at all');
+  assert.match(r.error, /the release notes in the core 1\.19\.949 package begin at core 1\.19\.900, after 1\.19\.850/);
+});
+
+await t('NEITHER SOURCE CAN ANSWER: the error carries both reasons, and is never an empty list', () => {
+  // Every target published before the notes were packaged, on every tenant box.
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ repos: {} }));
+  assert.equal(r.entries, undefined);
+  assert.match(r.error, /the core 1\.19\.949 package carries no release notes/, "the notes' reason");
+  assert.match(r.error, /no core checkout is reachable/, "and the checkout's own precise sentence (task 1004212)");
+});
+
+await t('no notes in the package, but a checkout on the box: the checkout still answers', () => {
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps());
+  assert.equal(r.entries.length, 2);
+  assert.equal(r.source, 'checkout');
+});
+
+await t('a download that fails is named, and the checkout is still tried', () => {
+  const d = changeDeps({ repos: {} });
+  d.readPackagedNotes = () => ({ error: 'could not download the core 1.19.949 package to read its release notes (npm error code E404)' });
+  assert.match(R.changesBetween('1.19.900', '1.19.949', d).error, /could not download the core 1\.19\.949 package.*; no core checkout is reachable/);
+});
+
+await t('a notes answer is capped exactly like a checkout answer', () => {
+  const many = { '1.19.900': [], '1.19.949': Array.from({ length: R.CHANGE_CAP + 3 }, (_, i) => ({ text: `summary ${i}` })) };
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ packagedNotes: many }));
+  assert.equal(r.entries.length, R.CHANGE_CAP);
+  assert.equal(r.more, 3);
+});
+
 await t('the dry run records the list beside the verdict, keyed to where the box IS', async () => {
   // Both answers are about ONE move, so they are stored together — and `from` is stored
   // with them because the list is only true of that starting point.

package/tests/db_backup_nightly.mjs

@@ -18,6 +18,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { macShapedTools } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'db-backup-nightly.sh');
@@ -29,13 +30,15 @@ const ENV = 'gds_backup_'.toUpperCase();
 // A fake pg_dump: a plain-format dump of `rows` rows, closed the way pg_dump closes one
 // (including the \unrestrict line patched servers append) unless it is `cut` short, and
 // exiting `exitCode`.
-// `seed` pre-places dumps in the shared dir as [filename, ageInDays].
-function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [] } = {}) {
+// `seed` pre-places dumps in the shared dir as [filename, ageInDays]; `mac` puts
+// BSD/macOS-shaped stat and wc first on PATH too.
+function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [], mac = false } = {}) {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-'));
   const bin = path.join(tmp, 'bin');
   const dir = path.join(tmp, 'backups');
   fs.mkdirSync(bin);
   fs.mkdirSync(dir);
+  if (mac) macShapedTools(bin);
   for (const [name, ageDays] of seed) {
     const f = path.join(dir, name);
     fs.writeFileSync(f, '');
@@ -50,7 +53,7 @@ function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [] }
     encoding: 'utf8',
     env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, [`${ENV}DB`]: 'smallproj', [`${ENV}DIR`]: dir, ...env },
   });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, dumps: fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')) };
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, dir, dumps: fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')) };
 }
 
 test('a complete dump of a small project is kept, however small', { skip }, () => {
@@ -93,6 +96,21 @@ test('the prune and the count reach only this database\'s own dumps, never a lon
   assert.match(r.stdout, /ok · 1 dump\(s\) retained/, 'the count is this database\'s dumps only');
 });
 
+test('it runs the same on macOS, where stat refuses -c and wc pads its numbers (task 1004170)', { skip }, () => {
+  // Every case above used to die on a Mac with "stat: illegal option -- c" while CI's
+  // Linux passed them, so the red never showed in Actions. This runs the Mac's tools here.
+  const attach = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-attach-'));
+  for (const f of ['a.png', 'b.png']) fs.writeFileSync(path.join(attach, f), 'x');
+  const r = runBackup({ mac: true, seed: [['smallproj-2026-01-01T000000Z.sql.gz', 40]], env: { BUG_ATTACHMENTS_DIR: attach } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.dumps.length, 1, 'the expired dump is pruned and the new one kept');
+  const size = fs.statSync(path.join(r.dir, r.dumps[0])).size;
+  assert.match(r.stdout, new RegExp(`wrote .*\\.sql\\.gz \\(${size} bytes\\)`), 'the byte count is the real size, unpadded');
+  assert.match(r.stdout, /\(2 attachment\(s\)\)/);
+  assert.match(r.stdout, /pruned 1 dump\(s\)/);
+  assert.match(r.stdout, /ok · 1 dump\(s\) retained/);
+});
+
 test('no fixed size floor is baked in for every instance', () => {
   const src = fs.readFileSync(SCRIPT, 'utf8');
   assert.doesNotMatch(src, new RegExp(`${ENV}MIN_BYTES:-[1-9]`), 'a default floor fails every database smaller than it');