@bongos/core 1.20.35 → 1.20.37

package/scripts/gds/module-assess-tests.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// scripts/gds/module-assess-tests.js — the Tests part of a module's assessment:
+// run a published module version's OWN test suite and record the pass rate as a
+// module_assessment_signals row (task 1003791, ADR 0343; table from core_265).
+//
+// Why this cannot reuse the unit gate. run-unit-tests.js discovers
+// modules/<key>/tests/*.mjs but runs them only when isModuleEnabled(key) — and a
+// catalog module ships default:false (ADR 0107 §6), so every store module's tests
+// are skipped there by construction (the trap task 1003630 documented). This runs
+// the tests straight from the published TARBALL, with no enabled/disabled check at
+// all, so what is measured is exactly the build a buyer would install.
+//
+// Outcomes (core_265's vocabulary — a missing part is never a zero):
+//   scored      the module has tests and they ran: score = round(100 × files that
+//               passed / files run), sample_size = files run. The unit is a test
+//               FILE (one process, its exit code), the same unit the core gate uses.
+//   no_data     the module declares no tests — NOT a fail (the task says the two
+//               must not score the same).
+//   not_scored  the tarball could not be read or verified, so nothing could run.
+//
+// Where the tests run. A module's tests reach into the core by relative path
+// (`../../../docs/…`) and resolve packages from the core's node_modules, so the
+// module is unpacked at the same depth modules/<key>/ sits at:
+// <core root>/.module-assess-<run>/<key>/ — node's walk-up resolution then finds
+// the core with no junctions to create (and so none a cleanup could follow; see
+// worktree.js). Each file runs in its own node process, serially, with a timeout
+// and a stripped environment: no DATABASE_URL, tokens or keys are handed to
+// third-party code. That is a floor, not a sandbox: a test process can still read
+// any file the OS user can (the core's own .env sits two directories up) and reach
+// the network.
+//
+// SO A PUBLISHED MODULE'S TESTS RUN ONLY IN A SEPARATE TESTING ENVIRONMENT
+// (owner, 2026-09-30): never on the control plane, where the secrets live. The
+// store path (recordTestsSignal) refuses unless the process declares it is that
+// environment with MODULE_TEST_SANDBOX=1 — set only on the isolated test box, no
+// secrets on disk, which is its own task. `--dir` stays open: it runs a module
+// from your own checkout, i.e. code you already chose to run.
+//
+//   node scripts/gds/module-assess-tests.js <store_module_versions.id>   run + record
+//   node scripts/gds/module-assess-tests.js --dir modules/<key>          dry run on a
+//                                                                        local module
+//                                                                        (prints; no DB)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile } = require('node:child_process');
+const { isCleanTeardownAbort } = require('./run-unit-tests');
+
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+const PER_FILE_TIMEOUT_MS = 90_000; // the unit gate's own per-file cap
+const SANDBOX_PREFIX = '.module-assess-';
+// The only variables a module's test process inherits. PATH to find tools; the
+// Windows ones node needs to start at all; nothing that names a credential.
+const ENV_KEEP = ['PATH', 'Path', 'SystemRoot', 'SYSTEMROOT', 'windir', 'TEMP', 'TMP', 'TMPDIR', 'COMSPEC', 'PATHEXT'];
+
+// The module's test files: tests/*.mjs at the top of tests/, exactly what
+// run-unit-tests.js discovers for a module on disk. `files` is module-relative paths.
+function discoverTestFiles(paths) {
+  return paths.filter((p) => /^tests\/[^/]+\.mjs$/.test(p)).sort();
+}
+
+function testEnv(sandbox) {
+  const env = {};
+  for (const k of ENV_KEEP) if (process.env[k] !== undefined) env[k] = process.env[k];
+  env.NODE_ENV = 'test';
+  env.HOME = sandbox;
+  env.USERPROFILE = sandbox;
+  return env;
+}
+
+// Run one file; resolve { file, passed, timedOut, code, tail }. Never rejects.
+function runFile(file, { cwd, env, timeoutMs, exec = execFile }) {
+  return new Promise((resolve) => {
+    exec(process.execPath, [file], { cwd, env, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => {
+        const out = String(stdout || '');
+        const errText = String(stderr || '');
+        // A suite that passed but aborted in libuv teardown on Windows passed (task 1003845).
+        const passed = !err || isCleanTeardownAbort(out, errText);
+        const timedOut = !!(err && err.killed);
+        // Why it failed: the suite's last stdout lines (its verdict) and the HEAD of
+        // stderr, where node puts the thrown error — its tail is only the stack and version.
+        const lines = (t, n, fromEnd) => { const ls = t.split(/\r?\n/).filter((l) => l.trim()); return (fromEnd ? ls.slice(-n) : ls.slice(0, n)).join('\n'); };
+        const tail = passed ? '' : [lines(out, 3, true), lines(errText, 4, false)].filter(Boolean).join('\n').slice(0, 600);
+        resolve({ passed, timedOut, code: err ? (err.code ?? null) : 0, tail });
+      });
+  });
+}
+
+// Remove a sandbox this file made. It holds only real files written by placeFiles
+// (never a link), and the name check means a bad argument cannot aim this anywhere else.
+function removeSandbox(dir, root) {
+  if (!path.basename(dir).startsWith(SANDBOX_PREFIX) || path.dirname(dir) !== root) {
+    throw new Error(`refusing to remove ${dir}: not a module-assess sandbox`);
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function placeFiles(files, target) {
+  for (const f of files) {
+    const dest = path.join(target, ...f.path.split('/'));
+    if (!dest.startsWith(target + path.sep)) throw new Error(`"${f.path}" would land outside the module`);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.buf);
+  }
+}
+
+// The gate in front of running module code. `trusted` is only for code you
+// already chose to run (a module in your own checkout, `--dir`). Anything else — a
+// published, third-party module — runs only where the process declares itself the
+// separate testing environment (MODULE_TEST_SANDBOX=1) AND nothing secret is
+// visible: no credential-looking variable in the environment, no .env at the core
+// root. The second half is what stops a mis-set flag on a real server from
+// quietly reopening the hole. Returns null (go) or { code, message }.
+const SECRET_ENV_RE = /(^DATABASE_URL$|^PG(PASSWORD|PASSFILE)$|TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|_KEY$)/i;
+function inTestSandbox(env = process.env) {
+  return env.MODULE_TEST_SANDBOX === '1';
+}
+function runRefusal({ trusted = false, env = process.env, root = CORE_ROOT } = {}) {
+  if (trusted) return null;
+  if (!inTestSandbox(env)) {
+    return { code: 'not_in_test_sandbox', message: "refusing to run a published module's tests here: they run only in the separate testing environment (MODULE_TEST_SANDBOX=1), never on a server holding secrets" };
+  }
+  const leaked = Object.keys(env).filter((k) => SECRET_ENV_RE.test(k) && env[k]);
+  if (leaked.length || fs.existsSync(path.join(root, '.env'))) {
+    return { code: 'secrets_present', message: `refusing: MODULE_TEST_SANDBOX=1 is set but secrets are visible here (${leaked.length ? leaked.sort().join(', ') : '.env at the core root'}) — the testing environment must hold none` };
+  }
+  return null;
+}
+
+// Run a module's own tests from its files ([{ path, buf }], module-relative) and
+// return the signal fields: { outcome, score, sample_size, reason, detail }.
+// Pure apart from the sandbox it writes and removes; `exec` is injectable for tests.
+async function assessTests(key, files, { root = CORE_ROOT, timeoutMs = PER_FILE_TIMEOUT_MS, exec, trusted = false, env = process.env } = {}) {
+  // Checked here too, not only in recordTestsSignal, so no caller can reach the
+  // code that runs a module without passing the gate.
+  const refused = runRefusal({ trusted, env, root });
+  if (refused) throw Object.assign(new Error(refused.message), { code: refused.code });
+  const tests = discoverTestFiles(files.map((f) => f.path));
+  if (tests.length === 0) {
+    return { outcome: 'no_data', score: null, sample_size: 0, reason: 'the module declares no tests (no tests/*.mjs)', detail: { files: [] } };
+  }
+  const sandbox = path.join(root, `${SANDBOX_PREFIX}${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  const moduleDir = path.join(sandbox, key);
+  try {
+    placeFiles(files, moduleDir);
+    const env = testEnv(sandbox);
+    const results = [];
+    for (const t of tests) {
+      // Serial on purpose, like the unit gate: tests share the core tree around them.
+      const r = await runFile(path.join(moduleDir, ...t.split('/')), { cwd: moduleDir, env, timeoutMs, exec });
+      results.push({ file: t, ...r });
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.filter((r) => !r.passed);
+    return {
+      outcome: 'scored',
+      score: Math.round((100 * passed) / results.length),
+      sample_size: results.length,
+      reason: failed.length ? `${failed.length} of ${results.length} test file(s) failed` : `all ${results.length} test file(s) passed`,
+      detail: { files: results.map(({ file, passed: ok, timedOut, tail }) => ({ file, passed: ok, ...(timedOut ? { timed_out: true } : {}), ...(tail ? { tail } : {}) })) },
+    };
+  } finally {
+    removeSandbox(sandbox, root);
+  }
+}
+
+// Append one Tests signal row for a store version. Never UPDATEs (core_265 is
+// append-only: the current result is the newest row per (version, part)).
+async function insertSignal(versionId, s, { db }) {
+  const { rows: [row] } = await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'tests', $2, $3, $4, $5, $6)
+     RETURNING id, version_id, part, outcome, score, sample_size, reason, measured_at`,
+    [versionId, s.outcome, s.score, s.sample_size, s.reason, JSON.stringify(s.detail || {})]);
+  return row;
+}
+
+// Read, verify and test one published version, then record the result. A tarball
+// that is missing or fails verification is recorded as not_scored — the part could
+// not be measured, which is not the same as the module failing its tests.
+async function recordTestsSignal(versionId, { db, storeDir, root, timeoutMs, exec, env = process.env } = {}) {
+  const refused = runRefusal({ env, root });
+  if (refused) return { ok: false, ...refused };
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  const { verifyModuleArtifact } = require('./module-artifact');
+  const { rows: [ver] } = await pool.query(
+    'SELECT id, module_key, version, artifact_path FROM store_module_versions WHERE id = $1', [versionId]);
+  if (!ver) return { ok: false, code: 'version_not_found', message: `no store_module_versions row ${versionId}` };
+
+  let signal;
+  try {
+    const file = versionArtifactFile(ver, storeDir ? { dir: storeDir } : {});
+    const tgz = await fs.promises.readFile(file);
+    const v = await verifyModuleArtifact(tgz, { key: ver.module_key, includeFiles: true });
+    signal = v.ok
+      ? await assessTests(ver.module_key, v.files, { root, timeoutMs, exec, env })
+      : { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code}): ${v.message}`, detail: {} };
+  } catch (e) {
+    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tests could not run (${e.code || 'error'})`, detail: {} };
+  }
+  const row = await insertSignal(ver.id, signal, { db: pool });
+  return { ok: true, version: ver, signal: row };
+}
+
+// Local dry run: read modules/<key>/ from disk and print what the signal would be.
+function readModuleDir(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push({ path: r, buf: fs.readFileSync(path.join(dir, r)) });
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function main(argv) {
+  const i = argv.indexOf('--dir');
+  if (i !== -1) {
+    const dir = path.resolve(argv[i + 1] || '');
+    const key = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')).key;
+    const s = await assessTests(key, readModuleDir(dir), { trusted: true });
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/gds/module-assess-tests.js <store_module_versions.id> | --dir modules/<key>');
+    return 2;
+  }
+  const res = await recordTestsSignal(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  const s = res.signal;
+  console.log(`${res.version.module_key} ${res.version.version}: tests ${s.outcome}${s.score !== null ? ` ${s.score}/100` : ''} — ${s.reason} (signal ${s.id})`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.stack || e.message); process.exit(1); });
+}
+
+module.exports = { discoverTestFiles, assessTests, recordTestsSignal, insertSignal, runRefusal, testEnv, SANDBOX_PREFIX };

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

package/tests/autobongos_loop.mjs

@@ -1084,6 +1084,211 @@ test('a runner that just started will NOT upgrade-exit, so a failed fetch cannot
   assert.equal(askedForDrift, false, 'and not even ask — the check costs a network call');
 });
 
+// --- pull always, restart rarely (task 1004406) -----------------------------
+//
+// Owner-approved 2026-09-30: restart only when the supervisor's OWN code changes.
+// Every worker is a fresh process in its own tree, so it runs whatever is on disk
+// already; the only code a restart refreshes is what THIS process has loaded.
+// So on drift the checkout is updated in place, and the process exits for the
+// wrapper only when a change touches a file it holds in memory.
+
+const loopDeps = (over = {}) => ({
+  iteration: async () => ({ event: 'hold', reason: 'test' }),
+  reconcileLeftoverClaims: async () => ({ event: 'boot_reconcile', ok: true }),
+  waitOrJump: async () => ({ waited: 0, jumped: false }),
+  writeHeartbeat: () => true,
+  postHeartbeat: async () => true,
+  emit: () => {},
+  loadedHead: async () => 'a'.repeat(40),
+  now: () => Date.now() + runner.MIN_UPTIME_BEFORE_UPGRADE_MS + 1000,
+  codeDrifted: async () => ({ from: 'aaaaaaaa', to: 'cccccccc' }),
+  loadedFiles: () => ['scripts/gds/autobongos-run.js', 'scripts/gds/sequence.js'],
+  state: runner.newRunnerState(),
+  ...over,
+});
+
+test('main moving with none of the supervisor\'s code refreshes the checkout IN PLACE and does not restart', async () => {
+  const rows = [];
+  let refreshed = 0;
+  const d = loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => { refreshed += 1; return { ok: true, to: 'c'.repeat(40), changed: ['docs/recipes/x.md', 'src/bongos/routes/tasks.js'] }; },
+  });
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, d);
+  assert.equal(code, 0, 'no restart for code the supervisor does not run');
+  assert.ok(refreshed >= 1, 'the checkout is brought current, so workers run the new code');
+  assert.ok(rows.some((r) => r.event === 'code_refreshed'), 'and the refresh is logged');
+  assert.ok(!rows.some((r) => r.event === 'upgrade_exit'));
+  assert.equal(d.state.diskHead, 'c'.repeat(40), 'the on-disk commit is remembered apart from the loaded one');
+});
+
+test('a change to a file the supervisor has LOADED restarts, and says which file', async () => {
+  const rows = [];
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => ({ ok: true, to: 'c'.repeat(40), changed: ['docs/x.md', 'scripts/gds/sequence.js'] }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+  const exit = rows.find((r) => r.event === 'upgrade_exit');
+  assert.match(exit.reason, /scripts\/gds\/sequence\.js/);
+  assert.ok(!/docs\/x\.md/.test(exit.reason), 'only the files that force the restart are named');
+});
+
+test('a change under the supervisor\'s own paths restarts even before that file was loaded', async () => {
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => r,
+    loadedFiles: () => [],
+    refreshCheckout: async () => ({ ok: true, to: 'c'.repeat(40), changed: ['modules/autonomy/cadence.js'] }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+});
+
+test('an in-place refresh that fails falls back to the restart, which re-runs the wrapper\'s refresh', async () => {
+  const rows = [];
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => ({ ok: false, reason: 'fetch failed' }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+  assert.match(rows.find((r) => r.event === 'upgrade_exit').reason, /fetch failed/);
+});
+
+test('the real --forever entry point is the one place that arms the in-place refresh', () => {
+  // main() is the production call shape and is not driven by these tests (it
+  // would run the real loop), so its one line is pinned by source. Without it the
+  // refresh is dead code and every merge to main restarts the runner again.
+  const src = readFileSync(new URL('../scripts/gds/autobongos-run.js', import.meta.url), 'utf8');
+  const line = src.split('\n').find((l) => l.includes('if (opts.forever) return forever('));
+  assert.ok(line, 'main() must still hand --forever to forever()');
+  assert.ok(line.includes('refreshInPlace: true'), `and arm the refresh there: ${line}`);
+});
+
+test('without refreshInPlace, forever never touches the checkout — tests and one-shot runs stay safe', async () => {
+  // refreshCheckout runs `git reset --hard`. A suite that reached it would wipe
+  // the tree it is testing, in CI or on a laptop, so only main() arms it.
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2 }, loopDeps({
+    record: (r) => r,
+    refreshCheckout: async () => { throw new Error('refreshed a checkout it was never told it owns'); },
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+});
+
+test('after a refresh, drift is measured from the REFRESHED commit, so it does not refresh every loop', async () => {
+  const tip = 'c'.repeat(40);
+  const run = async () => ({ ok: true, stdout: `${tip}\trefs/heads/main\n` });
+  assert.equal(await runner.codeDrifted({ run, loadedHead: async () => 'a'.repeat(40), state: { diskHead: tip } }), false);
+  const moved = await runner.codeDrifted({ run, loadedHead: async () => 'a'.repeat(40), state: { diskHead: 'b'.repeat(40) } });
+  assert.deepEqual(moved, { from: 'bbbbbbbb', to: 'cccccccc' });
+});
+
+test('supervisorTouched: loaded files and the supervisor\'s own paths count; nothing else does', () => {
+  const loaded = ['scripts/gds/sequence.js'];
+  assert.deepEqual(runner.supervisorTouched(['docs/a.md', 'src/x.js'], loaded), []);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/sequence.js'], loaded), ['scripts/gds/sequence.js']);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/autobongos-verify.js'], []), ['scripts/gds/autobongos-verify.js']);
+  assert.deepEqual(runner.supervisorTouched(['modules/autonomy/fence.js'], []), ['modules/autonomy/fence.js']);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/claim.js'], loaded), [], 'claim.js runs as a child process, so it is always fresh');
+});
+
+test('loadedFiles lists this process\'s own repo modules, repo-relative with forward slashes', () => {
+  const files = runner.loadedFiles();
+  assert.ok(files.includes('scripts/gds/autobongos-run.js'));
+  assert.ok(files.every((f) => !f.includes('\\') && !f.startsWith('/') && !f.includes('node_modules/')));
+});
+
+test('refreshCheckout refuses to reset anything but the MAIN checkout', async () => {
+  const calls = [];
+  // Everything else answers as a healthy main checkout would, so the ONLY thing
+  // that can stop the reset is the worktree check itself.
+  const run = async (bin, args) => {
+    calls.push(args.join(' '));
+    if (args[1] === '--git-dir') return { ok: true, stdout: '/repo/.git/worktrees/some-claim\n' };
+    if (args[1] === '--git-common-dir') return { ok: true, stdout: '/repo/.git\n' };
+    if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: `${'c'.repeat(40)}\n` };
+    if (args[0] === 'diff') return { ok: true, stdout: 'docs/a.md\n' };
+    return { ok: true, stdout: '' };
+  };
+  const r = await runner.refreshCheckout({ run, loadedHead: async () => 'a'.repeat(40) });
+  assert.equal(r.ok, false);
+  assert.ok(!calls.some((c) => c.startsWith('reset')), 'a linked worktree is somebody\'s claim — never reset it');
+});
+
+test('refreshCheckout in the main checkout fetches, diffs from the LOADED commit, then resets', async () => {
+  const calls = [];
+  const tip = 'c'.repeat(40);
+  const run = async (bin, args) => {
+    calls.push(args.join(' '));
+    if (args[1] === '--git-dir' || args[1] === '--git-common-dir') return { ok: true, stdout: '.git\n' };
+    if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: `${tip}\n` };
+    if (args[0] === 'diff') return { ok: true, stdout: 'docs/a.md\r\nscripts/gds/sequence.js\n' };
+    return { ok: true, stdout: '' };
+  };
+  const r = await runner.refreshCheckout({ run, loadedHead: async () => 'a'.repeat(40) });
+  assert.deepEqual(r, { ok: true, to: tip, changed: ['docs/a.md', 'scripts/gds/sequence.js'] });
+  const order = ['fetch', 'diff', 'reset'].map((v) => calls.findIndex((c) => c.startsWith(v)));
+  assert.ok(order.every((i) => i >= 0) && order[0] < order[1] && order[1] < order[2], `fetch → diff → reset, got ${calls.join(' | ')}`);
+  assert.ok(calls.find((c) => c.startsWith('diff')).includes('a'.repeat(40)), 'the diff is from what the process LOADED, so a change that landed several refreshes ago still counts');
+});
+
+// Each way the refresh can bail must bail BEFORE the reset: a half-done refresh
+// that resets to an unread or undiffed commit would lose the restart decision.
+for (const [name, failAt] of [
+  ['the running commit is unknown', 'loaded'],
+  ['fetch failed', 'fetch'],
+  ['could not read the fetched commit', 'FETCH_HEAD'],
+  ['could not diff the running commit against main', 'diff'],
+]) {
+  test(`refreshCheckout bails without resetting when: ${name}`, async () => {
+    const calls = [];
+    const run = async (bin, args) => {
+      calls.push(args.join(' '));
+      if (args[1] === '--git-dir' || args[1] === '--git-common-dir') return { ok: true, stdout: '.git\n' };
+      if (args[0] === 'fetch') return { ok: failAt !== 'fetch', stdout: '' };
+      if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: failAt === 'FETCH_HEAD' ? 'not-a-sha\n' : `${'c'.repeat(40)}\n` };
+      if (args[0] === 'diff') return { ok: failAt !== 'diff', stdout: 'docs/a.md\n' };
+      return { ok: true, stdout: '' };
+    };
+    const r = await runner.refreshCheckout({ run, loadedHead: async () => (failAt === 'loaded' ? null : 'a'.repeat(40)) });
+    assert.deepEqual(r, { ok: false, reason: name });
+    assert.ok(!calls.some((c) => c.startsWith('reset')), `no reset after "${name}"`);
+  });
+}
+
+test('a refresh in place reaches the heartbeat FILE through the real beat — disk_head end to end', async () => {
+  // The grader's catch: every forever() test stubbed writeHeartbeat, so the
+  // state never had to travel from the refresh to the file. This one does not.
+  const dir = mkdtempSync(join(tmpdir(), 'ab-diskhead-e2e-'));
+  const prev = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  process.env.AUTOBONGOS_HEARTBEAT_FILE = join(dir, 'beat.json');
+  try {
+    const d = loopDeps({
+      record: (r) => r,
+      refreshCheckout: async () => ({ ok: true, to: 'e'.repeat(40), changed: ['docs/a.md'] }),
+    });
+    delete d.writeHeartbeat;
+    await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, d);
+    const beat = JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8'));
+    assert.equal(beat.disk_head, 'e'.repeat(40));
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_HEARTBEAT_FILE; else process.env.AUTOBONGOS_HEARTBEAT_FILE = prev;
+  }
+});
+
+test('the heartbeat file names the on-disk commit when it differs from the running one', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ab-diskhead-'));
+  const prev = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  process.env.AUTOBONGOS_HEARTBEAT_FILE = join(dir, 'beat.json');
+  try {
+    runner.writeHeartbeat(Date.now(), { diskHead: 'd'.repeat(40) });
+    const beat = JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8'));
+    assert.equal(beat.disk_head, 'd'.repeat(40), '"up to date on disk, old supervisor" must be visible');
+    runner.writeHeartbeat(Date.now(), { diskHead: null });
+    assert.equal(JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8')).disk_head, undefined);
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_HEARTBEAT_FILE; else process.env.AUTOBONGOS_HEARTBEAT_FILE = prev;
+  }
+});
+
 test('past the uptime floor, a drift still exits', async () => {
   const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2 }, {
     iteration: async () => ({ event: 'hold', reason: 'test' }),

package/tests/core_upgrade_door.mjs

@@ -431,7 +431,7 @@ await t('schema_pending passes through as a count, and UNKNOWN stays null rather
 await t('an open intent is surfaced with its target, so the page can say what is already running', () => {
   const p = CU.previewFromSnapshot(previewInst, { served_version: '1.19.758', available: [], recommended: null },
     { action: 'core-upgrade', state: 'running', target_version: '1.19.762' });
-  assert.deepEqual(p.open_intent, { action: 'core-upgrade', state: 'running', target_version: '1.19.762', not_before: null, last_error: null });
+  assert.deepEqual(p.open_intent, { action: 'core-upgrade', state: 'running', target_version: '1.19.762', not_before: null, last_error: null, failure: null });
 });
 
 console.log('\nthe deploy page is gated on the same atom as its routes:');
@@ -1007,5 +1007,12 @@ await t('the preview says when a waiting move will try again, and why it is wait
     'an ordinary pending intent shows no error');
 });
 
+await t('a waiting move says what KIND of failure it is waiting out; a plain pending one says none (task 1004450)', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, null, waiting({ failure_class: 'known_wedge', failure_reason: 'dirty_tree' }), null);
+  assert.deepEqual(p.open_intent.failure, { class: 'known_wedge', reason: 'dirty_tree' });
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, waiting({ not_before: null, failure_class: 'transient' }), null).open_intent.failure, null);
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, waiting(), null).open_intent.failure, null, 'a row from before the columns');
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);