@bongos/core 1.19.876 → 1.19.878

package/tests/autobongos_cadence.mjs

@@ -0,0 +1,602 @@
+// tests/autobongos_cadence.mjs — the runner has no terminal stop (task 1003904).
+//
+// The done-when is three physical faults: pulling the network, expiring the
+// token, and cutting power mid-task must each leave NO LOCKED CLAIM and must each
+// resume by themselves once the cause clears. None of those can be staged in a
+// unit test, so each is reduced to the shape it presents to this code — a failing
+// read, a 401 in a reason string, a claim held by a session that no longer exists
+// — and the three are driven end to end through the real loop below.
+//
+// The property underneath all of them: NOTHING returns. A machine nobody is
+// watching must never be able to look idle while it is dead.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// POINT THE HEARTBEAT FILE AT A THROWAWAY PATH before requiring the runner.
+// anotherRunnerIsAlive() reads a file on disk, so without this the suite's verdict
+// depends on what happens to be in the real ~/.config path — a heartbeat left by a
+// previous run, or by the developer's own runner, makes reconciliation tests pass
+// or fail by luck. Set here rather than per-test because the failure mode is a
+// test that reads it BEFORE anyone remembered to.
+process.env.AUTOBONGOS_HEARTBEAT_FILE = require('node:path').join(
+  require('node:fs').mkdtempSync(require('node:path').join(require('node:os').tmpdir(), 'ab-cadence-')),
+  'beat.json',
+);
+
+const cadence = require('../modules/autonomy/cadence.js');
+const runner = require('../scripts/gds/autobongos-run.js');
+
+const { classifyEvent, nextCadence, START, DEFAULTS, signalFingerprint, shouldJumpWait } = cadence;
+
+// Drive a sequence of classes through the machine and return every state.
+const walk = (classes, cfg) => {
+  let s = { ...START };
+  return classes.map((c) => { s = nextCadence(s, typeof c === 'string' ? { class: c } : c, cfg); return s; });
+};
+
+// ── classification ──────────────────────────────────────────────────────────────
+
+test('a worked task counts as progress only when the LEDGER agreed', () => {
+  assert.equal(classifyEvent({ event: 'worked', verified: true }).class, 'progress');
+  // A worker's claim the ledger never saw is not progress; counting it would hold
+  // a broken runner at full speed indefinitely.
+  assert.equal(classifyEvent({ event: 'worked', verified: false, ledger_shape: 'still_held' }).class, 'quiet');
+  assert.equal(classifyEvent({ event: 'worked', verified: false, ledger_shape: 'undetermined' }).class, 'transient');
+});
+
+test('an empty queue and a queue where everything halts are different facts', () => {
+  assert.equal(classifyEvent({ event: 'nothing_claimable', skipped: [] }).class, 'quiet');
+  const blocked = classifyEvent({ event: 'nothing_claimable', skipped: [{ id: 1, reasons: ['needs_migration'] }, { id: 2, reasons: ['deps_unmet'] }] });
+  assert.equal(blocked.class, 'unworkable_queue');
+  assert.match(blocked.detail, /every one of them halted/);
+});
+
+test('an unworkable queue is never reported as breakage', () => {
+  // The machine is healthy and there is nothing for it to do. Escalating this
+  // through the failure ladder is how a working runner gets "fixed" into a broken one.
+  const states = walk(Array(5).fill({ class: 'unworkable_queue' }));
+  for (const s of states) {
+    assert.equal(s.mode, 'full');
+    assert.equal(s.consecutiveFailures, 0);
+    assert.equal(s.waitS, DEFAULTS.unworkableS);
+  }
+});
+
+test('the kill switch is a speed, not an exit', () => {
+  const c = classifyEvent({ event: 'fenced', code: 'kill_switch', reason: 'owner stopped it' });
+  assert.equal(c.class, 'stopped');
+  const s = nextCadence(START, c);
+  assert.equal(s.takeWork, false, 'a stopped runner claims nothing');
+  assert.ok(s.waitS > 0, 'but it keeps asking, so flipping the switch back on is enough');
+  assert.equal(s.consecutiveFailures, 0, 'being told to stop is not a failure');
+});
+
+test('a grader outage and an unreadable fence are transient; a closed allowlist is not', () => {
+  assert.equal(classifyEvent({ event: 'fenced', code: 'grader_unavailable' }).class, 'transient');
+  assert.equal(classifyEvent({ event: 'fenced', code: 'fence_unreadable' }).class, 'transient');
+  assert.equal(classifyEvent({ event: 'fenced', code: 'no_allowlist' }).class, 'quiet');
+  assert.equal(classifyEvent({ event: 'fenced', code: 'protected_path' }).class, 'quiet');
+});
+
+test('an expired token reads as systemic; an unreachable instance as transient', () => {
+  const token = classifyEvent({ event: 'claim_failed', reason: 'claim failed (401): unauthorized' });
+  assert.equal(token.class, 'systemic', 'waiting will not renew a token');
+  const net = classifyEvent({ event: 'pick_failed', reason: 'goal 1000119: fetch failed ECONNREFUSED' });
+  assert.equal(net.class, 'transient');
+  assert.equal(classifyEvent({ event: 'worktree_failed', reason: 'ENOSPC: no space left on device' }).class, 'systemic');
+});
+
+test('an unrecognised event is a failure, never silence', () => {
+  // An unknown failure that read as "nothing to do" would let a broken runner
+  // look idle forever — the exact thing this file exists against.
+  for (const event of ['', 'something_new', undefined]) {
+    assert.equal(classifyEvent({ event }).class, 'transient', String(event));
+  }
+  assert.equal(classifyEvent({}).class, 'transient');
+});
+
+// ── the state machine ───────────────────────────────────────────────────────────
+
+test('three straight failures drop to probing, and not two', () => {
+  const s = walk(['transient', 'transient', 'transient']);
+  assert.equal(s[0].mode, 'full');
+  assert.equal(s[1].mode, 'full');
+  assert.equal(s[2].mode, 'probing');
+  assert.equal(s[2].takeWork, false, 'probing takes no new work');
+  assert.equal(s[2].probeOnly, true);
+});
+
+test('the wait grows while probing, and stops growing at the cap', () => {
+  const s = walk(Array(12).fill('transient'));
+  const waits = s.slice(2).map((x) => x.waitS);
+  assert.deepEqual(waits.slice(0, DEFAULTS.backoffS.length), DEFAULTS.backoffS);
+  for (const w of waits) assert.ok(w <= DEFAULTS.backoffS[DEFAULTS.backoffS.length - 1]);
+  assert.equal(waits[waits.length - 1], DEFAULTS.backoffS[DEFAULTS.backoffS.length - 1], 'a broken runner still asks twice an hour');
+});
+
+test('one success returns it to full speed from anywhere', () => {
+  let s = { ...START };
+  for (const c of Array(9).fill('transient')) s = nextCadence(s, { class: c });
+  assert.equal(s.mode, 'probing');
+  s = nextCadence(s, { class: 'progress' });
+  assert.deepEqual(
+    { mode: s.mode, consecutiveFailures: s.consecutiveFailures, backoffStep: s.backoffStep, waitS: s.waitS, takeWork: s.takeWork },
+    { mode: 'full', consecutiveFailures: 0, backoffStep: 0, waitS: 0, takeWork: true },
+  );
+});
+
+test('quiet neither trips nor forgives the failure count', () => {
+  // Three idle nights must not leave it probing on the morning work appears...
+  const idle = walk(Array(6).fill('quiet'));
+  for (const s of idle) assert.equal(s.mode, 'full');
+  // ...and an idle window between failures must not reset the count either, or a
+  // runner that fails every other iteration would never back off at all.
+  const mixed = walk(['transient', 'quiet', 'transient', 'quiet', 'transient']);
+  assert.equal(mixed[mixed.length - 1].mode, 'probing');
+});
+
+test('every class produces a decision — no input leaves the runner without one', () => {
+  for (const cls of [...cadence.CLASSES, 'nonsense', undefined]) {
+    const s = nextCadence(START, { class: cls });
+    assert.ok(['full', 'probing'].includes(s.mode), String(cls));
+    assert.ok(Number.isFinite(s.waitS) && s.waitS >= 0, `${cls} must name a wait`);
+    assert.ok(typeof s.why === 'string' && s.why.length, `${cls} must say why`);
+  }
+});
+
+// ── jumping the wait ────────────────────────────────────────────────────────────
+
+test('a new signal jumps the wait; an unchanged world does not', () => {
+  const a = signalFingerprint({ head: 'abc123def456', fenceUpdatedAt: 't1', claimableCount: 3 });
+  assert.equal(shouldJumpWait(a, a), false);
+  for (const moved of [
+    { head: 'fff000111222', fenceUpdatedAt: 't1', claimableCount: 3 },   // main moved
+    { head: 'abc123def456', fenceUpdatedAt: 't2', claimableCount: 3 },   // the allowlist changed
+    { head: 'abc123def456', fenceUpdatedAt: 't1', claimableCount: 4 },   // a blocker resolved
+  ]) {
+    assert.equal(shouldJumpWait(a, signalFingerprint(moved)), true, JSON.stringify(moved));
+  }
+});
+
+test('a FAILED probe is not a signal', () => {
+  // Otherwise an unreachable instance turns the backoff into a busy loop
+  // hammering it — the exact opposite of backing off.
+  const known = signalFingerprint({ head: 'abc123def456', fenceUpdatedAt: 't1', claimableCount: 3 });
+  const blind = signalFingerprint({});
+  assert.equal(shouldJumpWait(known, blind), false);
+  assert.equal(shouldJumpWait(blind, known), false);
+  assert.equal(shouldJumpWait(blind, blind), false);
+});
+
+// ── boot recovery: no locked claim survives a run ───────────────────────────────
+
+const meWith = (claims) => ({ me: { getMe: async () => ({ ok: true, data: { active_claims: claims } }) } });
+
+test('a claim left by a previous run is reconciled before any new work', async () => {
+  const verified = [];
+  const row = await runner.reconcileLeftoverClaims({
+    anotherRunnerIsAlive: () => false,   // this test is about reconciling, not about the guard
+    api: meWith([{ task_id: '4242', worktree_name: 'autobongos-4242-abc123', title: 'T' }]),
+    record: (r) => r,
+    run: async () => ({ ok: true, code: 0, stdout: '', stderr: '' }),
+    verifyShip: async (what, o) => {
+      verified.push(what.taskId);
+      assert.equal(typeof o.release, 'function', 'reconciliation must be able to release');
+      return { shape: 'still_held', released: true, blocker: { blockerId: 7 } };
+    },
+  });
+  assert.equal(row.event, 'boot_reconcile');
+  assert.equal(row.ok, true);
+  assert.equal(row.leftover, 1);
+  assert.deepEqual(verified, ['4242']);
+  assert.equal(row.resolved[0].released, true);
+});
+
+test('reconciliation touches ONLY trees the runner itself made', async () => {
+  // FOUND THE HARD WAY, twice. A loose `autobongos-` prefix reads as "ours" and is
+  // not: a person naming a worktree `autobongos-resume-1003904-d29f25` while
+  // building this very feature matched it, and reconciliation released their live
+  // claim out from under them — during this task, to this task.
+  const verified = [];
+  const row = await runner.reconcileLeftoverClaims({
+    anotherRunnerIsAlive: () => false,
+    api: meWith([
+      { task_id: '1', worktree_name: 'autobongos-1-aaa111' },              // the generator's shape
+      { task_id: '2', worktree_name: 'goal-1000086-completion-6a672f' },   // a session tree
+      { task_id: '3', worktree_name: 'my-hand-made-tree' },                // a person's
+      { task_id: '4', worktree_name: 'autobongos-resume-1003904-d29f25' }, // the one that bit us
+      { task_id: '5', worktree_name: 'autobongos-fence-1003908-12cef3' },  // and its sibling
+    ]),
+    record: (r) => r,
+    run: async () => ({ ok: true }),
+    verifyShip: async (w) => { verified.push(w.taskId); return { shape: 'shipped' }; },
+  });
+  assert.deepEqual(verified, ['1']);
+  assert.equal(row.leftover, 1);
+});
+
+test('the tree matcher tracks the generator, so the two cannot drift apart', () => {
+  // If worktreeName's format changes and this regex does not, reconciliation
+  // silently matches NOTHING and every crashed claim stays locked forever — a
+  // failure with no symptom, which is the whole class this task exists against.
+  for (let i = 0; i < 20; i++) {
+    const name = runner.worktreeName(1000000 + i);
+    assert.equal(runner.isRunnerTree(name), true, `worktreeName produced ${name}, which the matcher rejects`);
+  }
+  for (const nope of ['autobongos-', 'autobongos-42', 'autobongos-42-ABC123', 'autobongos-x-abc123', 'xautobongos-42-abc123', '']) {
+    assert.equal(runner.isRunnerTree(nope), false, nope);
+  }
+});
+
+test('an unreadable /me is NOT "nothing to reconcile"', async () => {
+  // Starting work on top of an unknown lock is how a claim gets held forever.
+  for (const api of [
+    { me: { getMe: async () => ({ ok: false, status: 401 }) } },
+    { me: { getMe: async () => { throw new Error('ECONNREFUSED'); } } },
+  ]) {
+    const row = await runner.reconcileLeftoverClaims({ anotherRunnerIsAlive: () => false, api, record: (r) => r, run: async () => ({ ok: true }) });
+    assert.equal(row.event, 'boot_reconcile');
+    assert.equal(row.ok, false, 'an unreadable ledger must not read as a clean boot');
+    assert.ok(row.reason);
+  }
+});
+
+// ── the three physical faults, driven through the real loop ─────────────────────
+
+// A forever-loop harness: no clock, no network, no worker.
+function loopHarness({ rows, maxLoops = 6 }) {
+  const emitted = [];
+  const recorded = [];
+  let i = 0;
+  const deps = {
+    reconcileLeftoverClaims: async () => ({ event: 'boot_reconcile', ok: true, leftover: 0 }),
+    iteration: async () => rows[Math.min(i++, rows.length - 1)],
+    waitOrJump: async (waitS) => { emitted.push({ waitS }); return { waited: waitS, jumped: false }; },
+    record: (r) => { recorded.push(r); return r; },
+    emit: () => {},
+    // BOTH HEARTBEAT HALVES, or these tests hit the NETWORK. forever() beats at
+    // boot, per loop and around every worker; an uninjected postHeartbeat falls
+    // through to the real one, which builds a CLI client and makes an HTTP request
+    // per beat. That was fast enough on a laptop with a session to notice, and in
+    // CI — no session, no route — the suite ran for minutes and was killed, taking
+    // an unrelated pull request's `unit` check down with it (2026-09-19).
+    //
+    // The rule this encodes: when forever() gains a new outward call, the harness
+    // gains its stub in the SAME change. A DB-free unit suite that quietly makes a
+    // network call is not a unit suite, it is a flake waiting for a slow day.
+    writeHeartbeat: () => true,
+    postHeartbeat: async () => true,
+  };
+  return { deps, waits: emitted, recorded, opts: { goals: [], maxTasks: 3, maxLoops } };
+}
+
+test('PULLING THE NETWORK: the loop backs off and never returns', async () => {
+  const h = loopHarness({ rows: [{ event: 'pick_failed', reason: 'fetch failed ECONNREFUSED' }] });
+  await runner.forever(h.opts, h.deps);
+  const modes = h.recorded.filter((r) => r.event === 'cadence').map((r) => r.mode);
+  assert.ok(modes.includes('probing'), 'it must reach probing');
+  assert.ok(h.waits.some((w) => w.waitS > 0), 'and actually wait');
+  assert.ok(h.waits.length >= 5, 'and keep going — the loop does not exit on failure');
+});
+
+test('EXPIRING THE TOKEN: reported as systemic, and still probing rather than dead', async () => {
+  const h = loopHarness({ rows: [{ event: 'claim_failed', reason: 'claim failed (401): unauthorized' }] });
+  await runner.forever(h.opts, h.deps);
+  const cad = h.recorded.filter((r) => r.event === 'cadence');
+  assert.ok(cad.some((r) => r.class === 'systemic'), 'a person needs to know waiting will not fix this');
+  assert.equal(cad[cad.length - 1].mode, 'probing');
+  // Cheap probing means it resumes the moment someone re-authenticates.
+  assert.ok(cad[cad.length - 1].wait_s >= DEFAULTS.backoffS[0]);
+});
+
+test('CUTTING POWER MID-TASK: the next boot reconciles the claim before doing anything', async () => {
+  const order = [];
+  const h = loopHarness({ rows: [{ event: 'nothing_claimable', skipped: [] }], maxLoops: 1 });
+  h.deps.reconcileLeftoverClaims = async () => { order.push('reconcile'); return { event: 'boot_reconcile', ok: true, leftover: 1 }; };
+  const iterate = h.deps.iteration;
+  h.deps.iteration = async (...a) => { order.push('iterate'); return iterate(...a); };
+  await runner.forever(h.opts, h.deps);
+  assert.deepEqual(order, ['reconcile', 'iterate'], 'a leftover claim is resolved BEFORE new work is taken');
+});
+
+test('recovery: once the cause clears, it returns to full speed by itself', async () => {
+  // Three failures, then the world heals. Nobody restarts anything.
+  const h = loopHarness({
+    rows: [
+      { event: 'pick_failed', reason: 'ECONNREFUSED' },
+      { event: 'pick_failed', reason: 'ECONNREFUSED' },
+      { event: 'pick_failed', reason: 'ECONNREFUSED' },
+      { event: 'worked', verified: true, task_id: 1 },
+      { event: 'worked', verified: true, task_id: 2 },
+    ],
+    maxLoops: 5,
+  });
+  await runner.forever(h.opts, h.deps);
+  const cad = h.recorded.filter((r) => r.event === 'cadence');
+  assert.equal(cad[2].mode, 'probing');
+  assert.equal(cad[cad.length - 1].mode, 'full', 'a success returns it to full speed with no intervention');
+  assert.equal(cad[cad.length - 1].wait_s, 0);
+});
+
+test('the loop never returns early, whatever it is fed', async () => {
+  // The single property the owner asked for: "there is no loop to reboot once we
+  // stop and hit the failures."
+  for (const row of [
+    { event: 'fenced', code: 'kill_switch', reason: 'stopped' },
+    { event: 'claim_failed', reason: '401 unauthorized' },
+    { event: 'verify_halt' },
+    { event: 'nothing_claimable', skipped: [{ id: 1, reasons: ['needs_migration'] }] },
+    { event: 'wat' },
+  ]) {
+    const h = loopHarness({ rows: [row], maxLoops: 4 });
+    await runner.forever(h.opts, h.deps);
+    assert.equal(h.waits.length, 4, `${row.event}/${row.code || ''} must run every loop, not exit`);
+  }
+});
+
+test('a probing run takes exactly one task per wake, not a burst', async () => {
+  const h = loopHarness({ rows: [{ event: 'pick_failed', reason: 'boom' }], maxLoops: 6 });
+  let iterations = 0;
+  const iterate = h.deps.iteration;
+  h.deps.iteration = async (...a) => { iterations += 1; return iterate(...a); };
+  await runner.forever(h.opts, h.deps);
+  // maxTasks is 3, but a failure ends the burst immediately and probing caps the
+  // budget at 1 — so six loops is six iterations, never eighteen.
+  assert.equal(iterations, 6);
+});
+
+test('a full-speed burst continues only while work is landing', async () => {
+  const h = loopHarness({ rows: [{ event: 'worked', verified: true }], maxLoops: 1 });
+  let iterations = 0;
+  const iterate = h.deps.iteration;
+  h.deps.iteration = async (...a) => { iterations += 1; return iterate(...a); };
+  await runner.forever(h.opts, h.deps);
+  assert.equal(iterations, 3, 'maxTasks bounds the burst');
+});
+
+// ── waitOrJump ──────────────────────────────────────────────────────────────────
+
+test('waitOrJump wakes early when the world moved, and sleeps through when it did not', async () => {
+  const slept = [];
+  const sleep = async (ms) => { slept.push(ms); };
+  let n = 0;
+
+  const still = await runner.waitOrJump(300, { sleep, pollSignals: async () => 'same|t1|3' }, { pollEveryS: 60 });
+  assert.equal(still.jumped, false);
+  assert.equal(still.waited, 300);
+
+  slept.length = 0;
+  const moved = await runner.waitOrJump(1800, {
+    sleep,
+    pollSignals: async () => (++n > 2 ? 'NEW|t1|3' : 'same|t1|3'),
+  }, { pollEveryS: 60 });
+  assert.equal(moved.jumped, true);
+  assert.ok(moved.waited < 1800, 'it must not sit out the rest of a half-hour backoff');
+});
+
+test('a zero wait returns immediately without polling', async () => {
+  let polled = 0;
+  const r = await runner.waitOrJump(0, { sleep: async () => {}, pollSignals: async () => { polled += 1; return 'x'; } });
+  assert.deepEqual(r, { waited: 0, jumped: false });
+  assert.equal(polled, 0);
+});
+
+test('a PARTIALLY failed probe does not jump either — the flaky-field trap', () => {
+  // The bug a whole-string comparison has and this does not: the three probes fail
+  // independently, so a flaky `git ls-remote` flips the fingerprint between
+  // `abc|t1|3` and `-|t1|3` on alternate polls. Every one of those reads as a
+  // change, and a half-hour backoff becomes a busy loop hammering the instance it
+  // is backing off from — worst exactly when things are already broken.
+  const full = signalFingerprint({ head: 'abc123def456', fenceUpdatedAt: 't1', claimableCount: 3 });
+  const noHead = signalFingerprint({ fenceUpdatedAt: 't1', claimableCount: 3 });
+  assert.equal(shouldJumpWait(full, noHead), false);
+  assert.equal(shouldJumpWait(noHead, full), false);
+
+  // But a field that BOTH sides can see, and that moved, still jumps even when
+  // another field went blind.
+  const noHeadMoved = signalFingerprint({ fenceUpdatedAt: 't2', claimableCount: 3 });
+  assert.equal(shouldJumpWait(full, noHeadMoved), true);
+});
+
+// ── the heartbeat: a reconciler must not release a LIVE claim ───────────────────
+//
+// FOUND BY RUNNING IT, not by reading it. The first live run of
+// reconcileLeftoverClaims released the claim held by the very session writing the
+// code — right by its own rules (an `autobongos-` tree, a task at `active`), and
+// that is the point: the LEDGER CANNOT TELL A LIVE RUN FROM A DEAD ONE. Guessing
+// wrong one way leaves a task locked forever; the other way yanks a claim out
+// from under a worker mid-build and strands what it committed.
+
+test('reconciliation refuses while another runner is beating', async () => {
+  let looked = false;
+  const row = await runner.reconcileLeftoverClaims({
+    anotherRunnerIsAlive: () => true,
+    api: { me: { getMe: async () => { looked = true; return { ok: true, data: { active_claims: [] } }; } } },
+    record: (r) => r,
+  });
+  assert.equal(row.skipped, 'another runner is alive');
+  assert.equal(looked, false, 'it must not even ask — a live claim is not a leftover');
+});
+
+test('a STALE heartbeat does not veto recovery forever', () => {
+  // A power cut leaves a heartbeat file behind. If that vetoed reconciliation,
+  // the crash this whole mechanism exists to recover from would be unrecoverable.
+  const now = Date.parse('2026-09-19T12:00:00Z');
+  const stale = { pid: process.pid + 1, at: now - runner.HEARTBEAT_STALE_MS - 1000 };
+  assert.equal(runner.anotherRunnerIsAlive({ now, hb: stale }), false);
+});
+
+test('a heartbeat whose process is gone is litter, not a veto', () => {
+  const now = Date.now();
+  // A pid that cannot exist: fresh timestamp, dead process.
+  assert.equal(runner.anotherRunnerIsAlive({ now, hb: { pid: 2147483646, at: now } }), false);
+});
+
+test('our OWN heartbeat never vetoes us', () => {
+  const now = Date.now();
+  assert.equal(runner.anotherRunnerIsAlive({ now, hb: { pid: process.pid, at: now } }), false);
+});
+
+test('a fresh heartbeat from a live OTHER process does veto', () => {
+  const now = Date.now();
+  // process.ppid is a real, live process that is not us.
+  assert.equal(runner.pidAlive(process.ppid), true);
+  assert.equal(runner.anotherRunnerIsAlive({ now, hb: { pid: process.ppid, at: now } }), true);
+});
+
+test('no heartbeat at all is the common case and never vetoes', () => {
+  for (const hb of [null, undefined, {}, { pid: 1 }, { at: Date.now() }, 'nonsense']) {
+    assert.equal(runner.anotherRunnerIsAlive({ now: Date.now(), hb }), false, JSON.stringify(hb));
+  }
+});
+
+test('the forever loop claims the machine BEFORE it reconciles', async () => {
+  const order = [];
+  const h = loopHarness({ rows: [{ event: 'nothing_claimable', skipped: [] }], maxLoops: 1 });
+  h.deps.writeHeartbeat = () => { order.push('beat'); return true; };
+  h.deps.reconcileLeftoverClaims = async () => { order.push('reconcile'); return { event: 'boot_reconcile', ok: true }; };
+  await runner.forever(h.opts, h.deps);
+  assert.equal(order[0], 'beat', 'a second runner starting a moment later must see this one alive');
+  assert.equal(order[1], 'reconcile');
+});
+
+test('the heartbeat is rewritten at least once a loop, so a crash goes stale on its own', async () => {
+  const loops = 4;
+  let beats = 0;
+  const h = loopHarness({ rows: [{ event: 'nothing_claimable', skipped: [] }], maxLoops: loops });
+  h.deps.writeHeartbeat = () => { beats += 1; return true; };
+  h.deps.postHeartbeat = async () => true;
+  await runner.forever(h.opts, h.deps);
+  // A count, not an exact number: the runner beats at boot, per loop and around
+  // each worker, and pinning the arithmetic makes the test fail every time the
+  // loop gains an honest beat. The property is that it never goes a loop silent.
+  assert.ok(beats >= loops + 1, `expected at least one beat per loop plus boot, got ${beats}`);
+});
+
+test('writeHeartbeat honours AUTOBONGOS_HEARTBEAT_FILE and never throws', async () => {
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const p = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ab-hb-')), 'nested', 'beat.json');
+  const prev = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  process.env.AUTOBONGOS_HEARTBEAT_FILE = p;
+  try {
+    assert.equal(runner.heartbeatPath(), p, 'the env knob must actually be read');
+    assert.equal(runner.writeHeartbeat(), true);
+    const hb = runner.readHeartbeat();
+    assert.equal(hb.pid, process.pid);
+    assert.ok(Number.isFinite(hb.at));
+    // An unwritable path loses the guard, never the run.
+    //
+    // NOT /proc/... — that is what hung CI for every PR (task 1004052). writeHeartbeat
+    // does mkdirSync(dir, { recursive: true }), and on LINUX that call never returns
+    // under /proc: measured 10s+ with no result, where the same call throws EACCES
+    // instantly under /sys or /, and the non-recursive form throws ENOENT instantly
+    // under /proc itself. macOS has no /proc at all, so it failed fast there and the
+    // suite was green on every machine anyone tested it on while dying at the 90s
+    // per-test budget on the Ubuntu runner — with zero output, because node:test
+    // buffers a file's report until it finishes.
+    //
+    // A regular file as the PARENT is the portable way to be unwritable: mkdir under
+    // it is ENOTDIR immediately, on every platform, and it does not depend on
+    // permissions (so it still holds when the tests run as root, where a chmod 0o500
+    // directory would not).
+    const notADir = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ab-hb-file-')), 'iam-a-file');
+    fs.writeFileSync(notADir, 'not a directory');
+    process.env.AUTOBONGOS_HEARTBEAT_FILE = path.join(notADir, 'nested', 'beat.json');
+    assert.equal(runner.writeHeartbeat(), false);
+    assert.equal(runner.readHeartbeat(), null);
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_HEARTBEAT_FILE;
+    else process.env.AUTOBONGOS_HEARTBEAT_FILE = prev;
+  }
+});
+
+// ── the server heartbeat: a dead runner is visible, not silent (task 1003905) ────
+
+test('the runner tells the SERVER it is alive at boot, per loop, and around work', async () => {
+  const posts = [];
+  const h = loopHarness({ rows: [{ event: 'worked', verified: true, task_id: 4242 }], maxLoops: 2 });
+  h.deps.writeHeartbeat = () => true;
+  h.deps.postHeartbeat = async (fields) => { posts.push(fields); return true; };
+  await runner.forever(h.opts, h.deps);
+
+  assert.equal(posts[0].last_event, 'boot', 'the first thing it does is say it is up');
+  assert.ok(posts.some((p) => p.last_event === 'loop'));
+  // The task id is what lets the hall tell "quiet because it is building" from
+  // "quiet because it is dead" — a worker may hold the loop for ninety minutes.
+  const working = posts.find((p) => p.working_task_id === 4242);
+  assert.ok(working, 'a beat around a worker must carry the task it is building');
+});
+
+test('a failed heartbeat never takes down the runner it is watching', async () => {
+  // Letting the watching mechanism break the watched thing is strictly worse than
+  // a gap in the log — and the gap reports itself, because silence is the signal.
+  const h = loopHarness({ rows: [{ event: 'nothing_claimable', skipped: [] }], maxLoops: 3 });
+  h.deps.writeHeartbeat = () => false;
+  h.deps.postHeartbeat = async () => { throw new Error('instance unreachable'); };
+  await assert.doesNotReject(() => runner.forever(h.opts, h.deps));
+});
+
+test('postHeartbeat swallows an unreachable instance rather than throwing', async () => {
+  const api = { autonomy: { postAutonomyHeartbeat: async () => { throw new Error('ECONNREFUSED'); } } };
+  assert.equal(await runner.postHeartbeat({ last_event: 'loop' }, { api }), false);
+});
+
+test('postHeartbeat sends the host, the pid and a stable start time', async () => {
+  const sent = [];
+  const api = { autonomy: { postAutonomyHeartbeat: async (a) => { sent.push(a.body); return { ok: true }; } } };
+  assert.equal(await runner.postHeartbeat({ last_event: 'loop', mode: 'full' }, { api }), true);
+  assert.equal(sent[0].pid, process.pid);
+  assert.ok(sent[0].host && typeof sent[0].host === 'string');
+  assert.equal(sent[0].started_at, runner.RUNNER_STARTED_AT);
+  assert.equal(sent[0].last_event, 'loop');
+  // A second beat carries the SAME start time, so a restart loop shows up in the
+  // hall as a start time that keeps moving rather than one that never does.
+  await runner.postHeartbeat({ last_event: 'loop' }, { api });
+  assert.equal(sent[1].started_at, sent[0].started_at);
+});
+
+test('a long wait still beats, so backing off does not look like dying', async () => {
+  const beats = [];
+  await runner.waitOrJump(300, {
+    sleep: async () => {},
+    pollSignals: async () => 'same|t1|3',
+    beat: async (f) => { beats.push(f); },
+  }, { pollEveryS: 60 });
+  assert.ok(beats.length >= 4, 'a thirty-minute backoff is the runner working, not a corpse');
+  assert.equal(beats[0].last_event, 'waiting');
+});
+
+// ── the harness must not reach the network (2026-09-19) ─────────────────────────
+
+test('loopHarness stubs every outward call forever() makes', () => {
+  // THE INCIDENT. Task 1003905 gave forever() a server heartbeat — at boot, per
+  // loop and around every worker — and stubbed it only in the NEW tests. The older
+  // forever() tests fell through to the real postHeartbeat, which builds a CLI
+  // client and makes an HTTP request per beat. On a laptop with a session that was
+  // merely slow (6-7s for this file); in CI, with no session and no route, the
+  // suite ran until it was killed and took an unrelated pull request's `unit`
+  // check down with it. A DB-free unit suite that quietly makes a network call is
+  // not a unit suite, it is a flake waiting for a slow day.
+  //
+  // This asserts the stubs exist rather than trusting the next editor to remember.
+  // It cannot prove no network call happens — that would need a socket hook — but
+  // it does fail the moment someone deletes a default, which is how the gap opened.
+  const { deps } = loopHarness({ rows: [{ event: 'nothing_claimable', skipped: [] }] });
+  for (const outward of ['reconcileLeftoverClaims', 'iteration', 'waitOrJump', 'writeHeartbeat', 'postHeartbeat']) {
+    assert.equal(typeof deps[outward], 'function', `loopHarness must stub ${outward} — forever() calls it, and unstubbed it goes to the network`);
+  }
+});
+
+test('the suite never reads the real heartbeat file', () => {
+  // anotherRunnerIsAlive() reads a path on disk, so without the override at the top
+  // of this file the reconciliation tests pass or fail by whatever happens to be in
+  // the developer's own ~/.config — including a heartbeat their own runner is
+  // writing right now.
+  assert.match(runner.heartbeatPath(), /ab-cadence-/, 'the suite must point at a throwaway path, not the real one');
+});