@bongos/core 1.19.871 → 1.19.873

package/tests/autobongos_verify.mjs

@@ -0,0 +1,325 @@
+// tests/autobongos_verify.mjs — completion is read from the ledger (task 1003903).
+//
+// The claim under test is narrow and load-bearing: a worker saying "shipped" is
+// not evidence, and every way the ledger can disagree with it has a NAME and a
+// remedy. Several of these guard incidents that already happened once — a task
+// credited with no artifact on any branch (1002459), a claim left held by a
+// session that had exited, and a link filed in the wrong order so the task went
+// straight back into the pool.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const verify = require('../scripts/gds/autobongos-verify.js');
+const { classifyLedger, blockerFor, probeArtifact, verifyShip } = verify;
+const strandWatch = require('../scripts/gds/strand-watch.js');
+
+const NOW = Date.parse('2026-09-18T12:00:00.000Z');
+const task = (over = {}) => ({ id: '1003903', title: 'A task', status: 'shipped', updated_at: '2026-09-18T11:59:00.000Z', ...over });
+const onMain = { checked: true, onMain: true, sha: 'abcdef1234567890', subject: 'feat: the thing (task 1003903)' };
+const notOnMain = { checked: true, onMain: false, sha: null, subject: null };
+
+// ── the happy path is the ONLY verified one ────────────────────────────────────
+
+test('shipped with a commit on main is the one verified shape', () => {
+  const v = classifyLedger({ task: task(), artifact: onMain, nowMs: NOW });
+  assert.equal(v.shape, 'shipped');
+  assert.equal(v.verified, true);
+  assert.equal(v.releaseClaim, false);
+  assert.equal(v.fileBlocker, false);
+  assert.equal(v.halt, false);
+});
+
+test('every shape that is not `shipped` is unverified', () => {
+  for (const status of ['confirmed', 'completed', 'active', 'ready', 'backlog', 'blocked', 'abandoned', 'planning']) {
+    const v = classifyLedger({ task: task({ status }), nowMs: NOW });
+    assert.equal(v.verified, false, `'${status}' must not read as a delivery`);
+    assert.ok(v.shape && v.shape !== 'shipped', `'${status}' needs a name of its own, got ${v.shape}`);
+  }
+});
+
+// ── the shapes, by name ────────────────────────────────────────────────────────
+
+test('each known strand shape is detected by name', () => {
+  const cases = [
+    // [ledger row, expected shape]
+    [task({ status: 'confirmed', needs_rebase: true, needs_rebase_reason: 'strand:land_not_proven' }), 'unprovable'],
+    [task({ status: 'confirmed' }), 'unlanded'],
+    [task({ status: 'completed' }), 'ungraded'],
+    [task({ status: 'active' }), 'still_held'],
+    [task({ status: 'ready' }), 'not_started'],
+    [task({ status: 'backlog' }), 'not_started'],
+    [task({ status: 'blocked' }), 'blocked'],
+    [task({ status: 'abandoned' }), 'abandoned'],
+    [task({ status: 'shipped' }), 'shipped'],
+  ];
+  for (const [row, shape] of cases) {
+    assert.equal(classifyLedger({ task: row, nowMs: NOW }).shape, shape, `status '${row.status}' → ${shape}`);
+  }
+});
+
+test('the three mid-ship names are strand-watch’s, not new ones', () => {
+  // One condition must not have two names: /strand-fix routes on these strings,
+  // so a rename here without a rename there sends a builder to the wrong remedy.
+  for (const [row, shape] of [
+    [task({ status: 'confirmed', needs_rebase: true, needs_rebase_reason: 'strand:land_not_proven' }), 'unprovable'],
+    [task({ status: 'confirmed' }), 'unlanded'],
+    [task({ status: 'completed' }), 'ungraded'],
+  ]) {
+    const mine = classifyLedger({ task: row, nowMs: NOW });
+    // strand-watch only names it once it is old enough; the shape must match.
+    const theirs = strandWatch.classifyStrand(row, { nowMs: NOW + 40 * 3600_000 });
+    assert.equal(mine.shape, shape);
+    assert.equal(theirs.shape, shape, 'the two classifiers disagree about what to call this');
+    assert.equal(mine.remedy, theirs.remedy, 'same condition, same remedy');
+  }
+});
+
+test('this classifier is stricter than the board check, never quieter', () => {
+  // strand-watch waits an hour on `confirmed` because a slow CI queue is not a
+  // strand. Here the session that was supposed to finish has already exited, so
+  // the wait cannot change the verdict — a one-second-old confirm is a strand.
+  const fresh = task({ status: 'confirmed', updated_at: new Date(NOW - 1000).toISOString() });
+  assert.equal(strandWatch.classifyStrand(fresh, { nowMs: NOW }), null, 'the board check is right to stay quiet');
+  assert.equal(classifyLedger({ task: fresh, nowMs: NOW }).shape, 'unlanded');
+});
+
+test('an unparseable updated_at still gets a shape — quiet is the wrong failure here', () => {
+  // classifyStrand fails QUIET on bad dates, correctly: its line is injected into
+  // every session and a false alarm trains people to scroll past. Quiet HERE would
+  // mean the loop reads a strand as a success.
+  for (const [status, shape] of [['confirmed', 'unlanded'], ['completed', 'ungraded']]) {
+    const bad = task({ status, updated_at: 'not a date' });
+    assert.equal(strandWatch.classifyStrand(bad, { nowMs: NOW }), null);
+    const v = classifyLedger({ task: bad, nowMs: NOW });
+    assert.equal(v.shape, shape);
+    assert.equal(v.fileBlocker, true);
+  }
+});
+
+// ── the incident this exists for ───────────────────────────────────────────────
+
+test('shipped with nothing on main is called out, not celebrated', () => {
+  const v = classifyLedger({ task: task(), artifact: notOnMain, nowMs: NOW });
+  assert.equal(v.shape, 'shipped_no_artifact');
+  assert.equal(v.verified, false);
+  assert.equal(v.fileBlocker, true);
+  // Shipped is shipped: credits are paid and parking it helps nobody.
+  assert.equal(v.releaseClaim, false);
+  assert.equal(v.linkBlocker, false);
+});
+
+test('a probe that could not run is NOT evidence the artifact is missing', () => {
+  for (const artifact of [null, { checked: false, reason: 'git fetch failed: no network' }]) {
+    const v = classifyLedger({ task: task(), artifact, nowMs: NOW });
+    assert.equal(v.shape, 'shipped', 'not looking must never manufacture a missing artifact');
+    assert.equal(v.verified, true);
+  }
+});
+
+// ── what each shape makes the supervisor DO ────────────────────────────────────
+
+test('only a still-held claim is released — the ledger decides, not the worker', () => {
+  const released = ['active', 'claimed', 'in_progress'];
+  for (const status of [...released, 'ready', 'backlog', 'blocked', 'confirmed', 'completed', 'shipped', 'abandoned']) {
+    const v = classifyLedger({ task: task({ status }), artifact: onMain, nowMs: NOW });
+    assert.equal(v.releaseClaim, released.includes(status), `release on '${status}' should be ${released.includes(status)}`);
+  }
+});
+
+test('a task the loop could pick straight back up gets linked; one it cannot, does not', () => {
+  // The link is what parks the task at `blocked` and removes it from
+  // claimable_tasks. It only bites on `ready` (LINK_BLOCKABLE_STATUSES), so it is
+  // asked for exactly where the task would otherwise return to the pool.
+  for (const status of ['active', 'ready', 'backlog']) {
+    assert.equal(classifyLedger({ task: task({ status }), nowMs: NOW }).linkBlocker, true, status);
+  }
+  for (const status of ['confirmed', 'completed', 'shipped', 'abandoned', 'blocked']) {
+    assert.equal(classifyLedger({ task: task({ status }), artifact: onMain, nowMs: NOW }).linkBlocker, false, status);
+  }
+});
+
+test('an already-blocked task does not collect a second blocker', () => {
+  const v = classifyLedger({ task: task({ status: 'blocked' }), nowMs: NOW });
+  assert.equal(v.fileBlocker, false);
+  assert.equal(v.releaseClaim, false);
+});
+
+test('an unreadable ledger halts the run and touches nothing', () => {
+  const v = classifyLedger({ task: null, nowMs: NOW });
+  assert.equal(v.shape, 'undetermined');
+  assert.equal(v.halt, true);
+  assert.equal(v.releaseClaim, false, 'releasing a claim on a guess is how work gets stranded');
+  assert.equal(v.fileBlocker, false);
+});
+
+test('an abandoned task halts the run — cutting work is not a worker’s call', () => {
+  const v = classifyLedger({ task: task({ status: 'abandoned' }), nowMs: NOW });
+  assert.equal(v.shape, 'abandoned');
+  assert.equal(v.halt, true);
+  assert.equal(v.fileBlocker, true);
+});
+
+// ── the blocker row ────────────────────────────────────────────────────────────
+
+test('the blocker names the shape, the ledger status, and what the worker claimed', () => {
+  const v = classifyLedger({ task: task({ status: 'active' }), nowMs: NOW });
+  const row = blockerFor(v, { taskId: '1003903', taskTitle: 'A task', worker: { outcome: 'claims_shipped', reason: 'I shipped it' } });
+  assert.match(row.title, /1003903/);
+  assert.match(row.title, /still_held/);
+  assert.ok(row.title.length <= 200, 'the title column caps at 200 chars');
+  assert.match(row.body_md, /still_held/);
+  assert.match(row.body_md, /active/);
+  assert.match(row.body_md, /claims_shipped/, 'the worker’s own story belongs in the record');
+  assert.match(row.body_md, /I shipped it/);
+});
+
+test('the dedupe key is per task AND per shape', () => {
+  // POST /blockers has ON CONFLICT (source, source_ref) DO NOTHING. Re-failing the
+  // same way must not pile up rows; failing a NEW way must still be said out loud.
+  const held = blockerFor(classifyLedger({ task: task({ status: 'active' }), nowMs: NOW }), { taskId: '1003903' });
+  const held2 = blockerFor(classifyLedger({ task: task({ status: 'active' }), nowMs: NOW }), { taskId: '1003903' });
+  const graded = blockerFor(classifyLedger({ task: task({ status: 'completed' }), nowMs: NOW }), { taskId: '1003903' });
+  assert.equal(held.source, 'autobongos');
+  assert.equal(held.source_ref, held2.source_ref);
+  assert.notEqual(held.source_ref, graded.source_ref);
+});
+
+test('a reconciler-recorded strand reason reaches the blocker body', () => {
+  const v = classifyLedger({ task: task({ status: 'confirmed', needs_rebase: true, needs_rebase_reason: 'strand:land_not_proven' }), nowMs: NOW });
+  assert.match(blockerFor(v, { taskId: '1003903' }).body_md, /strand:land_not_proven/);
+});
+
+// ── the artifact probe ─────────────────────────────────────────────────────────
+
+test('the artifact probe reads main, fixed-string, for the ship-commit convention', async () => {
+  const calls = [];
+  const git = async (args) => {
+    calls.push(args);
+    if (args[0] === 'fetch') return { ok: true, stdout: '', stderr: '' };
+    return { ok: true, stdout: 'deadbeefcafe1234 feat: the thing (task 42)\n', stderr: '' };
+  };
+  const r = await probeArtifact(42, { git });
+  assert.deepEqual(r, { checked: true, onMain: true, sha: 'deadbeefcafe1234', subject: 'feat: the thing (task 42)' });
+  assert.deepEqual(calls[0], ['fetch', '-q', 'origin', 'main']);
+  assert.ok(calls[1].includes('-F'), 'the pattern is a fixed string, not a regex');
+  assert.ok(calls[1].includes('--grep=(task 42)'));
+  assert.ok(calls[1].includes('FETCH_HEAD'), 'read what was just fetched, not a stale local ref');
+});
+
+test('a failed fetch reports `checked: false`, never `onMain: false`', async () => {
+  const git = async (args) => (args[0] === 'fetch'
+    ? { ok: false, stdout: '', stderr: 'fatal: could not read from remote' }
+    : { ok: true, stdout: '', stderr: '' });
+  const r = await probeArtifact(42, { git });
+  assert.equal(r.checked, false);
+  assert.equal(r.onMain, undefined);
+  assert.match(r.reason, /could not read from remote/);
+});
+
+test('an empty log is a real answer: no trace on main', async () => {
+  const git = async () => ({ ok: true, stdout: '\n', stderr: '' });
+  assert.deepEqual(await probeArtifact(42, { git }), { checked: true, onMain: false, sha: null, subject: null });
+});
+
+test('a task id that is not a plain number is never interpolated into a git flag', async () => {
+  let called = false;
+  const r = await probeArtifact('42 --output=/tmp/pwned', { git: async () => { called = true; return { ok: true, stdout: '' }; } });
+  assert.equal(r.checked, false);
+  assert.equal(called, false);
+});
+
+// ── the order of operations ────────────────────────────────────────────────────
+
+const fakeApi = () => ({ tasks: { getTasksId: async () => ({ ok: false }) }, blockers: {} });
+
+test('release happens BEFORE the link, or the task goes straight back in the pool', async () => {
+  // linkBlockerToTask() parks the task only when it is at `ready`, and releasing is
+  // what puts it there. Link first and you get a row that changes nothing, then a
+  // release that hands the task back to the loop to fail the same way.
+  const order = [];
+  const out = await verifyShip({ taskId: 42 }, {
+    api: fakeApi(),
+    task: task({ id: '42', status: 'active' }),
+    release: async () => { order.push('release'); return { ok: true }; },
+    fileBlocker: async (_api, _row, opts) => { order.push(`file(link=${opts.link})`); return { filed: true, blockerId: 7, linked: true, parked: true }; },
+  });
+  assert.deepEqual(order, ['release', 'file(link=true)']);
+  assert.equal(out.released, true);
+  assert.equal(out.blocker.parked, true, 'the task must actually have moved, not just been linked');
+});
+
+test('a release that fails does not get reported as a release', async () => {
+  const out = await verifyShip({ taskId: 42 }, {
+    api: fakeApi(),
+    task: task({ id: '42', status: 'active' }),
+    release: async () => ({ ok: false, stderr: 'Only the original session can release it.' }),
+    fileBlocker: async (_a, _r, opts) => ({ filed: true, blockerId: 7, linked: opts.link }),
+  });
+  assert.equal(out.released, false);
+  assert.match(out.release_error, /original session/);
+  // The link is not attempted when the task never made it back to `ready` — it
+  // would write a row that parks nothing and muddies the blocker board.
+  assert.equal(out.blocker.linked, false);
+});
+
+test('the artifact probe only runs when the ledger claims success', async () => {
+  let probes = 0;
+  const probeArtifactSpy = async () => { probes += 1; return notOnMain; };
+  await verifyShip({ taskId: 42 }, { api: fakeApi(), task: task({ status: 'completed' }), probeArtifact: probeArtifactSpy, act: false });
+  assert.equal(probes, 0, 'what is on main cannot make a `completed` task shipped');
+  await verifyShip({ taskId: 42 }, { api: fakeApi(), task: task({ status: 'shipped' }), probeArtifact: probeArtifactSpy, act: false });
+  assert.equal(probes, 1);
+});
+
+test('read-only mode changes nothing', async () => {
+  let touched = false;
+  const out = await verifyShip({ taskId: 42 }, {
+    api: fakeApi(), task: task({ status: 'active' }), act: false,
+    release: async () => { touched = true; return { ok: true }; },
+    fileBlocker: async () => { touched = true; return { filed: true }; },
+  });
+  assert.equal(touched, false);
+  assert.equal(out.shape, 'still_held');
+  assert.equal(out.releaseClaim, true, 'it still SAYS what should happen');
+  assert.equal(out.released, false);
+});
+
+test('an unreadable task means an undetermined halt, with no writes attempted', async () => {
+  let touched = false;
+  const out = await verifyShip({ taskId: 42 }, {
+    api: fakeApi(), task: null,
+    release: async () => { touched = true; return { ok: true }; },
+    fileBlocker: async () => { touched = true; return { filed: true }; },
+  });
+  assert.equal(out.shape, 'undetermined');
+  assert.equal(out.halt, true);
+  assert.equal(touched, false);
+});
+
+test('a missing release function is reported, never read as "no release needed"', async () => {
+  const out = await verifyShip({ taskId: 42 }, {
+    api: fakeApi(), task: task({ status: 'active' }),
+    fileBlocker: async () => ({ filed: true, blockerId: 7 }),
+    // release deliberately absent
+  });
+  assert.equal(out.released, false);
+  assert.match(out.release_error, /no release function/, 'silently skipping the write that unlocks a task is the bug this step exists to catch');
+});
+
+test('an unreadable ledger keeps WHY it was unreadable', async () => {
+  const api = { tasks: { getTasksId: async () => ({ ok: false, status: 401 }) }, blockers: {} };
+  const out = await verifyShip({ taskId: 42 }, { api });
+  assert.equal(out.shape, 'undetermined');
+  assert.match(out.read_error, /401/, '"undetermined" alone cannot tell an expired session from an unreachable instance');
+});
+
+test('a thrown client error is a read failure, not a crash', async () => {
+  const api = { tasks: { getTasksId: async () => { throw new Error('fetch failed'); } }, blockers: {} };
+  const out = await verifyShip({ taskId: 42 }, { api });
+  assert.equal(out.shape, 'undetermined');
+  assert.equal(out.halt, true);
+  assert.match(out.read_error, /fetch failed/);
+});

package/tests/autonomy_gauge.mjs

@@ -0,0 +1,344 @@
+// tests/autonomy_gauge.mjs — the Autobongos usage gauge (task 1003901, goal 1000119).
+//
+// The two assertions the task's done-when names are 1) and 2) below; everything
+// else guards the ways this could quietly decide "plenty left" when it does not
+// know. That direction is the only dangerous one: a gauge that holds too often
+// wastes a window, a gauge that GOES when it should hold spends one it does not
+// have and kills a worker mid-task.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { decideCapacity, readGauge, reserveFor, weeklyPace, whenPaceAllows, cfg } =
+  require('../modules/autonomy/gauge.js');
+const statusline = require('../scripts/gds/autonomy-gauge-statusline.js');
+const cli = require('../scripts/gds/autonomy-gauge.js');
+
+// Run fn with env vars set, always restoring them.
+function withEnv(vars, fn) {
+  const prev = {};
+  for (const [k, v] of Object.entries(vars)) { prev[k] = process.env[k]; if (v === undefined) delete process.env[k]; else process.env[k] = String(v); }
+  try { return fn(); } finally {
+    for (const [k, v] of Object.entries(prev)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+  }
+}
+function inTempGauge(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gauge-'));
+  const target = path.join(dir, 'autobongos-gauge.json');
+  try { return withEnv({ AUTOBONGOS_GAUGE_FILE: target }, () => fn(target)); }
+  finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+const NOW = 1_800_000_000;                 // a fixed clock; nothing here reads the real one
+const HOUR = 3600;
+const gaugeAt = (agoS, over = {}) => ({
+  written_at: NOW - agoS,
+  five_hour: { used_percentage: 10, resets_at: NOW + 2 * HOUR },
+  seven_day: { used_percentage: 10, resets_at: NOW + 6 * 24 * HOUR },
+  ...over,
+});
+// 3am in New York — squarely outside the owner's hours, so the reserve is the
+// overnight one and the five-hour ceiling is effectively the whole window.
+const NIGHT = Math.floor(Date.parse('2027-01-15T08:00:00Z') / 1000);
+const DAY = Math.floor(Date.parse('2027-01-15T17:00:00Z') / 1000);   // noon in New York
+
+// ── 1) done-when: a stale gauge is UNKNOWN, never headroom ──────────────────────
+test('a stale gauge file is unknown, not headroom', () => {
+  const d = decideCapacity({ gauge: gaugeAt(4 * HOUR), now: NOW });
+  assert.equal(d.go, false, 'a four-hour-old reading must never authorise new work');
+  assert.equal(d.unknown, true);
+  assert.match(d.reason, /stale|unknown/i);
+});
+
+test('every unreadable shape decides the same way — unknown, hold', () => {
+  for (const [label, g] of [
+    ['missing file', null],
+    ['not an object', 'nonsense'],
+    ['no written_at', { five_hour: { used_percentage: 1, resets_at: NOW + HOUR } }],
+    ['neither window', { written_at: NOW }],
+    ['unparseable numbers', { written_at: NOW, five_hour: { used_percentage: 'lots', resets_at: 'soon' } }],
+    ['dated in the future', { ...gaugeAt(0), written_at: NOW + 600 }],
+  ]) {
+    const d = decideCapacity({ gauge: g, now: NOW });
+    assert.equal(d.go, false, `${label} must hold`);
+    assert.equal(d.unknown, true, `${label} must read as unknown`);
+    assert.ok(d.reason && d.reason.length > 0, `${label} must say why`);
+  }
+});
+
+test('a fresh gauge with headroom goes', () => {
+  const d = decideCapacity({ gauge: gaugeAt(30), now: NOW });
+  assert.equal(d.go, true);
+  assert.equal(d.sleepUntil, null);
+});
+
+// ── 2) done-when: the reserve line sends it to sleep until the REAL reset ───────
+test('crossing the five-hour reserve sleeps to that window\'s exact reset', () => {
+  const resetsAt = NOW + 77 * 60;            // a deliberately un-round time
+  const g = gaugeAt(30, { five_hour: { used_percentage: 99, resets_at: resetsAt } });
+  const d = decideCapacity({ gauge: g, now: NOW, config: { reserve: { working: 25, overnight: 2 } } });
+  assert.equal(d.go, false);
+  assert.equal(d.unknown, false);
+  assert.equal(d.window, 'five_hour');
+  assert.equal(d.sleepUntil, resetsAt, 'wake time must be the reported reset second, not a rounded guess');
+});
+
+test('the reserve is what decides it — same burn, two verdicts', () => {
+  const used = 90;
+  const g = gaugeAt(30, { five_hour: { used_percentage: used, resets_at: NOW + HOUR } });
+  const cfg = { timezone: 'America/New_York', ownerHours: { start: 8, end: 20 }, reserve: { working: 25, overnight: 2 } };
+
+  const working = decideCapacity({ gauge: { ...g, written_at: DAY }, now: DAY, config: cfg });
+  assert.equal(working.go, false, '90% with a 25-point working reserve is over the ceiling');
+
+  const overnight = decideCapacity({ gauge: { ...g, written_at: NIGHT }, now: NIGHT, config: cfg });
+  assert.equal(overnight.go, true, 'the same 90% overnight is capacity the owner is not using');
+});
+
+test('reserveFor names the window it picked and why', () => {
+  const cfg = { timezone: 'America/New_York', ownerHours: { start: 8, end: 20 }, reserve: { working: 25, overnight: 2 } };
+  assert.equal(reserveFor(DAY, cfg).window, 'working');
+  assert.equal(reserveFor(NIGHT, cfg).window, 'overnight');
+  assert.ok(reserveFor(DAY, cfg).why.includes('America/New_York'));
+});
+
+test('an unresolvable timezone takes the CAUTIOUS reserve, and does not throw', () => {
+  const r = reserveFor(NOW, { timezone: 'Not/AZone' });
+  assert.equal(r.window, 'working', 'guessing "overnight" wrongly is what throttles the owner');
+});
+
+// ── the seven-day window is the binding one ─────────────────────────────────────
+test('a burn ahead of the weekly pace holds, and wakes when the pace catches up', () => {
+  // One day into the week, 60% already spent: far ahead of an even burn.
+  const sevenDay = { used_percentage: 60, resets_at: NOW + 6 * 24 * HOUR };
+  const g = gaugeAt(30, { seven_day: sevenDay });
+  const d = decideCapacity({ gauge: g, now: NOW, config: { weeklySlack: 15 } });
+  assert.equal(d.go, false, 'maxing every five-hour window is how a week goes dark on Wednesday');
+  assert.equal(d.window, 'seven_day');
+  assert.ok(d.sleepUntil > NOW, 'must name a future wake');
+  assert.ok(d.sleepUntil < sevenDay.resets_at, 'pace catches up before the week resets — do not sleep the whole week');
+  assert.equal(d.sleepUntil, whenPaceAllows({ used: 60, resetsAt: sevenDay.resets_at }, { weeklySlack: 15 }));
+});
+
+test('a burn within slack of the pace still goes', () => {
+  const g = gaugeAt(30, { seven_day: { used_percentage: 20, resets_at: NOW + 6 * 24 * HOUR } });
+  assert.equal(decideCapacity({ gauge: g, now: NOW, config: { weeklySlack: 15 } }).go, true);
+});
+
+test('a fully spent week sleeps to the weekly reset, not the five-hour one', () => {
+  const weekReset = NOW + 3 * 24 * HOUR;
+  const g = gaugeAt(30, {
+    five_hour: { used_percentage: 0, resets_at: NOW + HOUR },
+    seven_day: { used_percentage: 100, resets_at: weekReset },
+  });
+  const d = decideCapacity({ gauge: g, now: NOW });
+  assert.equal(d.window, 'seven_day', 'an empty five-hour window means nothing if the week is gone');
+  assert.equal(d.sleepUntil, weekReset);
+});
+
+test('every HOLD names a wake that is in the future and not past its own reset', () => {
+  // Swept rather than hand-picked: a wake time in the past is a spin loop, and
+  // one past the reset sleeps through capacity that already came back. The first
+  // draft of this test tried to force the clamp with a single crafted row and
+  // could not — the pace branch only fires when (used-slack)/100 exceeds the
+  // elapsed fraction, which is exactly the condition that puts the catch-up time
+  // in the future. So the clamp in decideCapacity is defensive, and what is
+  // actually worth pinning is the invariant it defends.
+  let holds = 0;
+  for (const used5 of [0, 40, 80, 95, 100]) {
+    for (const used7 of [0, 25, 50, 75, 99, 100]) {
+      for (const weekRemainingD of [6.9, 5, 3.5, 1, 0.01]) {
+        for (const slack of [0, 15, 40]) {
+          const fiveReset = NOW + 37 * 60;
+          const weekReset = NOW + Math.round(weekRemainingD * 24 * HOUR);
+          const d = decideCapacity({
+            gauge: gaugeAt(30, {
+              five_hour: { used_percentage: used5, resets_at: fiveReset },
+              seven_day: { used_percentage: used7, resets_at: weekReset },
+            }),
+            now: NOW,
+            config: { weeklySlack: slack },
+          });
+          if (d.go || d.unknown) continue;
+          holds += 1;
+          const label = `5h=${used5} 7d=${used7} rem=${weekRemainingD}d slack=${slack}`;
+          assert.ok(d.sleepUntil > NOW, `${label}: wake must be in the future`);
+          const ownReset = d.window === 'five_hour' ? fiveReset : weekReset;
+          assert.ok(d.sleepUntil <= ownReset, `${label}: must not sleep past its own reset`);
+        }
+      }
+    }
+  }
+  assert.ok(holds > 20, `the sweep must actually produce holds to assert on (got ${holds})`);
+});
+
+test('whenPaceAllows is monotonic in what has been spent', () => {
+  const resetsAt = NOW + 5 * 24 * HOUR;
+  const at = (used) => whenPaceAllows({ used, resetsAt }, { weeklySlack: 0 });
+  assert.ok(at(80) > at(50), 'spending more must push the catch-up later, never earlier');
+  assert.ok(at(50) > at(20));
+});
+
+test('weeklyPace reads elapsed time from resets_at, needing no stored week-start', () => {
+  const half = weeklyPace({ used: 0, resetsAt: NOW + 3.5 * 24 * HOUR }, NOW, { weeklySlack: 0 });
+  assert.ok(Math.abs(half.elapsedFraction - 0.5) < 0.01);
+  assert.ok(Math.abs(half.allowedPct - 50) < 1);
+});
+
+// ── the writer ──────────────────────────────────────────────────────────────────
+test('the writer never invents a gauge it was not given', () => {
+  assert.match(statusline.main(JSON.stringify({ model: { id: 'x' } })), /not reported/i,
+    'a render before the first API response must not overwrite a real reading with an empty one');
+  assert.match(statusline.main('not json at all'), /no status json/i);
+});
+
+test('the writer persists both windows and reports them', () => {
+  // Redirect via AUTOBONGOS_GAUGE_FILE, NOT XDG_CONFIG_HOME: instance-config's
+  // configPath does not read XDG, so the first version of this test believed it
+  // was isolated while writing into the real ~/.config/cloudbongos.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gauge-'));
+  const target = path.join(dir, 'autobongos-gauge.json');
+  const prev = process.env.AUTOBONGOS_GAUGE_FILE;
+  process.env.AUTOBONGOS_GAUGE_FILE = target;
+  try {
+    const line = statusline.main(JSON.stringify({
+      rate_limits: {
+        five_hour: { used_percentage: 42.4, resets_at: NOW + HOUR },
+        seven_day: { used_percentage: 71.2, resets_at: NOW + 5 * 24 * HOUR },
+      },
+    }));
+    assert.match(line, /5h 42%/);
+    assert.match(line, /7d 71%/);
+    // and it must land where it was told, not in the real config dir
+    assert.ok(fs.existsSync(target), 'the writer must honour AUTOBONGOS_GAUGE_FILE');
+    const onDisk = JSON.parse(fs.readFileSync(target, 'utf8'));
+    assert.equal(onDisk.five_hour.used_percentage, 42.4, 'persisted value must be exact, not the rounded display one');
+    assert.ok(Number.isFinite(onDisk.written_at));
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_GAUGE_FILE; else process.env.AUTOBONGOS_GAUGE_FILE = prev;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── the round trip ──────────────────────────────────────────────────────────────
+test('a file the writer produced is one the reader accepts', () => {
+  const now = Math.floor(Date.now() / 1000);
+  const written = { written_at: now, source: 'statusline',
+    five_hour: { used_percentage: 5, resets_at: now + HOUR },
+    seven_day: { used_percentage: 5, resets_at: now + 6 * 24 * HOUR } };
+  const round = JSON.parse(JSON.stringify(written));        // through disk, as JSON
+  const d = decideCapacity({ gauge: round, now });
+  assert.equal(d.go, true, 'the two halves must agree on the file format');
+  assert.equal(readGauge(round, now).known, true);
+});
+
+// ── grader finding (major): a render must not destroy the window it did not report ──
+test('a render reporting only five_hour CARRIES FORWARD the known seven_day', () => {
+  inTempGauge((target) => {
+    const now = Math.floor(Date.now() / 1000);
+    statusline.main(JSON.stringify({ rate_limits: {
+      five_hour: { used_percentage: 10, resets_at: now + HOUR },
+      seven_day: { used_percentage: 64, resets_at: now + 4 * 24 * HOUR },
+    } }));
+    const first = JSON.parse(fs.readFileSync(target, 'utf8'));
+    assert.equal(first.seven_day.used_percentage, 64);
+
+    // The next render omits seven_day — transient, and the half the weekly
+    // pacing depends on. Rebuilding from scratch used to drop it silently.
+    statusline.main(JSON.stringify({ rate_limits: { five_hour: { used_percentage: 20, resets_at: now + HOUR } } }));
+    const second = JSON.parse(fs.readFileSync(target, 'utf8'));
+    assert.ok(second.seven_day, 'the seven-day reading must survive a render that did not mention it');
+    assert.equal(second.seven_day.used_percentage, 64);
+    assert.equal(second.five_hour.used_percentage, 20, 'the reported half must still update');
+    assert.equal(second.seven_day.observed_at, first.seven_day.observed_at,
+      'a carried window keeps its ORIGINAL observed_at, or it would read as fresh forever');
+  });
+});
+
+test('a carried-forward window ages out on its own, even in a freshly written file', () => {
+  const now = 1_900_000_000;
+  const raw = {
+    written_at: now,                                   // the FILE is fresh…
+    five_hour: { used_percentage: 5, resets_at: now + HOUR, observed_at: now },
+    seven_day: { used_percentage: 99, resets_at: now + 3 * 24 * HOUR, observed_at: now - 6 * HOUR },
+  };
+  const g = readGauge(raw, now, { staleAfterS: 1800 });
+  assert.equal(g.known, true, 'the fresh five-hour half is still usable');
+  assert.equal(g.sevenDay, null, '…but a six-hour-old seven-day reading is not evidence');
+  // And therefore the 99% must NOT hold it — that number is no longer known.
+  assert.equal(decideCapacity({ gauge: raw, now, config: { staleAfterS: 1800 } }).go, true);
+});
+
+test('when every window has aged out the verdict is unknown, not headroom', () => {
+  const now = 1_900_000_000;
+  const raw = { written_at: now,
+    five_hour: { used_percentage: 5, resets_at: now + HOUR, observed_at: now - 6 * HOUR },
+    seven_day: { used_percentage: 5, resets_at: now + 3 * 24 * HOUR, observed_at: now - 6 * HOUR } };
+  const d = decideCapacity({ gauge: raw, now, config: { staleAfterS: 1800 } });
+  assert.equal(d.go, false);
+  assert.equal(d.unknown, true);
+});
+
+test('a file written before observed_at existed still reads (falls back to written_at)', () => {
+  const now = 1_900_000_000;
+  const legacy = { written_at: now - 60,
+    five_hour: { used_percentage: 5, resets_at: now + HOUR },
+    seven_day: { used_percentage: 5, resets_at: now + 3 * 24 * HOUR } };
+  assert.equal(readGauge(legacy, now).known, true);
+  assert.equal(decideCapacity({ gauge: legacy, now }).go, true);
+});
+
+// ── grader finding (major): the CLI's own env parsing and file resolution ───────
+test('readConfig reads every knob, and ignores unparseable values', () => {
+  withEnv({
+    AUTOBONGOS_TIMEZONE: 'Europe/Oslo', AUTOBONGOS_STALE_AFTER_S: '900',
+    AUTOBONGOS_WEEKLY_SLACK: '5', AUTOBONGOS_RESERVE_WORKING: '30',
+    AUTOBONGOS_RESERVE_OVERNIGHT: '1', AUTOBONGOS_HOURS_START: '7', AUTOBONGOS_HOURS_END: '19',
+  }, () => {
+    const c = cli.readConfig();
+    assert.equal(c.timezone, 'Europe/Oslo');
+    assert.equal(c.staleAfterS, 900);
+    assert.equal(c.weeklySlack, 5);
+    assert.deepEqual(c.reserve, { working: 30, overnight: 1 });
+    assert.deepEqual(c.ownerHours, { start: 7, end: 19 });
+  });
+  withEnv({
+    AUTOBONGOS_TIMEZONE: undefined, AUTOBONGOS_STALE_AFTER_S: 'soon',
+    AUTOBONGOS_WEEKLY_SLACK: undefined, AUTOBONGOS_RESERVE_WORKING: undefined,
+    AUTOBONGOS_RESERVE_OVERNIGHT: undefined, AUTOBONGOS_HOURS_START: undefined, AUTOBONGOS_HOURS_END: undefined,
+  }, () => {
+    const c = cli.readConfig();
+    assert.equal(c.staleAfterS, undefined, 'an unparseable value must fall through to the default, not become NaN');
+    assert.equal(c.timezone, undefined);
+  });
+});
+
+test('gaugePath honours the redirect, and evaluate reads the file the writer wrote', () => {
+  inTempGauge((target) => {
+    assert.equal(cli.gaugePath(), target);
+    assert.equal(cli.loadGauge(target), null, 'no file yet');
+
+    const now = Math.floor(Date.now() / 1000);
+    statusline.main(JSON.stringify({ rate_limits: {
+      five_hour: { used_percentage: 3, resets_at: now + HOUR },
+      seven_day: { used_percentage: 3, resets_at: now + 6 * 24 * HOUR },
+    } }));
+
+    const { path: p, decision } = cli.evaluate(now);
+    assert.equal(p, target);
+    assert.equal(decision.go, true, 'the CLI must reach the same verdict as the pure core');
+  });
+});
+
+test('evaluate on a missing file is UNKNOWN — the CLI never defaults to go', () => {
+  inTempGauge(() => {
+    const d = cli.evaluate(Math.floor(Date.now() / 1000)).decision;
+    assert.equal(d.go, false);
+    assert.equal(d.unknown, true);
+  });
+});