@bongos/core 1.23.21 → 1.24.1

package/tests/publish_reconciler_overlap.mjs

@@ -0,0 +1,60 @@
+// tests/publish_reconciler_overlap.mjs
+//
+// task 1004924 — the reconciler's interval tick fired five sweeps every 5 minutes
+// with no check that the previous round had finished, so a slow DB or GitHub call
+// stacked rounds and held several pool connections at once. buildTick now keeps a
+// per-sweep in-flight flag: a sweep still running from the last tick is skipped.
+//
+// Its own file on purpose: tests/publish_reconciler.mjs exits on a fixed 100 ms
+// timer, so a case appended there that waits on a few event-loop turns is cut off
+// before it reports — it neither passes nor fails, it just vanishes.
+//
+// Run:  node tests/publish_reconciler_overlap.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const reconciler = require('../modules/lifecycle/publish-reconciler.js');
+const { test, summary } = makeRunner();
+
+const settle = () => new Promise((r) => setImmediate(r));
+
+await test('buildTick skips a sweep still in flight, and runs it again once it settles', async () => {
+  const calls = { slow: 0, fast: 0, failing: 0 };
+  let releaseSlow;
+  const sweeps = [
+    ['slow', () => { calls.slow++; return new Promise((r) => { releaseSlow = r; }); }],
+    ['fast', async () => { calls.fast++; }],
+    ['failing', async () => { calls.failing++; throw new Error('boom'); }],
+  ];
+  const logs = [];
+  const errs = [];
+  const tick = reconciler.buildTick({ log: (m) => logs.push(m), error: (m) => errs.push(m) }, sweeps);
+
+  tick(); await settle();
+  tick(); await settle();
+  tick(); await settle();
+  assert.equal(calls.slow, 1, 'the slow sweep is never stacked while its first run is pending');
+  assert.equal(calls.fast, 3, 'a slow sweep never starves the others');
+  assert.equal(calls.failing, 3, 'a rejected run clears its flag too');
+  assert.equal(logs.filter((m) => /slow still running/.test(m)).length, 2, 'each skip is logged');
+
+  releaseSlow(); await settle();
+  tick(); await settle();
+  assert.equal(calls.slow, 2, 'once the run settles the next tick runs it again');
+});
+
+await test('the default tick covers all five sweeps', () => {
+  // A sweep left out of the guarded list would simply never run again.
+  const src = require('node:fs').readFileSync(require.resolve('../modules/lifecycle/publish-reconciler.js'), 'utf8');
+  // task 1004965: read the exported list, since an entry may now carry a cadence.
+  const fns = reconciler.SWEEPS.map(([, fn]) => fn);
+  for (const fn of ['runSweep', 'runCostSweep', 'runCriterionSweep', 'runPromotionSweep', 'runCraftAchievementBackfill']) {
+    assert.ok(fns.includes(reconciler[fn]), `${fn} is in the tick`);
+  }
+  assert.match(src, /const tick = buildTick\(deps\);/, 'start() uses the guarded tick');
+});
+
+summary();

package/tests/rank_change_broadcast_port.mjs

@@ -0,0 +1,151 @@
+// tests/rank_change_broadcast_port.mjs
+//
+// Task 1004962 — the rank-change Discord announcement posts IN-PROCESS through
+// the discord module's `discord.post` port, never by spawning
+// `node scripts/discord/post.js` (50-100 MB + ~300 ms CPU per rank change, with
+// nothing bounding a burst). Drives the real PATCH /builders/:id/rank route with
+// auth + db stubbed, and pins the three cases the task names:
+//
+//   1. posted       — the port is called once with the #ship-news line, and no
+//                     child process is started.
+//   2. module off   — no `discord.post` provider: the rank change still 200s and
+//                     nothing is posted.
+//   3. post throws  — a provider that throws (sync) or rejects (async) never fails
+//                     the rank change.
+//
+// Run:  node tests/rank_change_broadcast_port.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+delete process.env.CHAT_DRY_RUN; // the dry-run guard would hide the port call
+
+// Record any child process the route starts. Patched BEFORE the router loads, so
+// a destructured `execFile`/`spawn` picks up the recorder.
+const cp = require('node:child_process');
+const spawned = [];
+for (const fn of ['execFile', 'spawn', 'exec', 'fork']) {
+  cp[fn] = (...args) => { spawned.push([fn, args[0], args[1]]); throw new Error(`test: ${fn} must not be called`); };
+}
+
+const authPath = require.resolve('../src/bongos/auth.js');
+require.cache[authPath] = {
+  id: authPath, filename: authPath, loaded: true,
+  exports: {
+    requireBuilder: (req, _res, next) => {
+      req.builder = { id: '1', rank: 'archon', github_login: 'archon1', display_name: 'Archon One' };
+      next();
+    },
+    requireRank: () => (_req, _res, next) => next(),
+    requirePermission: () => (_req, _res, next) => next(),
+  },
+};
+
+const fakeDb = {
+  RANKS: ['xenos', 'thetes', 'metic', 'archon'],
+  setBuilderRank: async ({ builderId, newRank }) => ({
+    builder: { id: builderId, rank: newRank, display_name: 'Ada', github_login: 'ada' },
+    previous_rank: 'thetes',
+    direction: 'promotion',
+    credit_delta: 5,
+  }),
+};
+const dbPath = require.resolve('../src/bongos/db.js');
+require.cache[dbPath] = { id: dbPath, filename: dbPath, loaded: true, exports: fakeDb };
+
+const seams = require('../src/module-seams.js');
+const buildBuildersRouter = require('../src/bongos/routes/builders.js');
+const { fireDiscordBroadcast } = buildBuildersRouter;
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildBuildersRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const { port } = server.address();
+
+function patchRank(id, rank) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify({ rank });
+    const req = http.request({
+      host: '127.0.0.1', port, method: 'PATCH', path: `/api/gds/builders/${id}/rank`,
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(data) },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        let json = null;
+        try { json = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch (_) {}
+        resolve({ status: res.statusCode, json });
+      });
+    });
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 20));
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  seams._reset();
+  spawned.length = 0;
+  try { await fn(); passed++; console.log(`ok   ${name}`); } catch (e) { failed++; console.log(`FAIL ${name}\n     ${e && e.stack}`); }
+}
+
+await t('posted: the route calls discord.post once with the #ship-news line, no child process', async () => {
+  const posts = [];
+  seams.registerProvider('discord.post', async (msg) => { posts.push(msg); return { posted: true, channel: msg.channel }; });
+  const r = await patchRank(7, 'metic');
+  assert.equal(r.status, 200);
+  await settle();
+  assert.equal(posts.length, 1);
+  assert.equal(posts[0].channel, 'ship_news');
+  assert.equal(posts[0].text, r.json.broadcast);
+  assert.match(posts[0].text, /Ada has been raised to the rank of Metic/);
+  assert.deepEqual(spawned, []);
+});
+
+await t('module off: no discord.post provider — the rank change succeeds and nothing is posted', async () => {
+  const r = await patchRank(7, 'metic');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.builder.rank, 'metic');
+  await settle();
+  assert.deepEqual(spawned, []);
+  assert.deepEqual(await fireDiscordBroadcast('hello'), { posted: false, reason: 'no_discord' });
+});
+
+await t('post throws synchronously: the rank change still succeeds', async () => {
+  let calls = 0;
+  seams.registerProvider('discord.post', () => { calls++; throw new Error('webhook exploded'); });
+  const r = await patchRank(7, 'metic');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.builder.rank, 'metic');
+  await settle();
+  assert.equal(calls, 1);
+  assert.deepEqual(await fireDiscordBroadcast('hello'), { posted: false, reason: 'post_failed' });
+});
+
+await t('post rejects: the rank change still succeeds and no rejection escapes', async () => {
+  const unhandled = [];
+  const onUnhandled = (e) => unhandled.push(e);
+  process.on('unhandledRejection', onUnhandled);
+  let calls = 0;
+  seams.registerProvider('discord.post', async () => { calls++; throw new Error('discord 500'); });
+  const r = await patchRank(7, 'metic');
+  assert.equal(r.status, 200);
+  await settle();
+  process.off('unhandledRejection', onUnhandled);
+  assert.equal(calls, 1);
+  assert.deepEqual(unhandled, []);
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/seed_tasks.mjs

@@ -0,0 +1,176 @@
+// tests/seed_tasks.mjs — scripts/bongos/seed-tasks.js, the one data-driven task seeder (task 1004979).
+//
+// The load-bearing case is EQUIVALENCE: the three per-version seed scripts it replaced
+// (seed-bongos-v1-idea-routing-tasks.js, seed-bv1-profiles-tasks.js,
+// seed-bv2-ideator-surface-tasks.js) each became a spec under tests/fixtures/seed-tasks/, and
+// seed-tasks.js must send exactly the writes the old script sent — every POST /tasks body,
+// dependency edge, promotion and follow-up PATCH, in order. The proof ran LIVE first: the first
+// version of this test (task 1004979's first commit) ran each old script and seed-tasks.js
+// against the same fake API and compared both the writes and the resulting task rows.
+// The old scripts are gone now, so OLD_WRITE_HASHES pins what that run recorded: the sha256 of
+// the canonical write log each old script produced. Any change to what seed-tasks.js sends for
+// these specs moves the hash.
+//
+// Run: node tests/seed_tasks.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { startFakeApi, fetchApi, canonical } from './fixtures/seed-tasks/fake-api.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SEEDER = path.join(ROOT, 'scripts/bongos/seed-tasks.js');
+const EXAMPLE = path.join(ROOT, 'scripts/bongos/seed-tasks.example.json');
+const FIX = path.join(ROOT, 'tests/fixtures/seed-tasks');
+const { validateSpec, seedTasks } = require(SEEDER);
+
+// spec fixture -> the old script it replaced, and the sha256 of that script's write log.
+const HISTORICAL = [
+  { spec: 'bongos-v1-idea-routing.json', old: 'seed-bongos-v1-idea-routing-tasks.js', hash: 'f5bc176890077a62754812cf69666bd49ba0da441dafa84702e1883156c302f8' },
+  { spec: 'bv1-profiles.json', old: 'seed-bv1-profiles-tasks.js', hash: 'cf81ee14131a20fe5a07c05b7c5fe3362bc940d5c5592031ad911b709db129a7' },
+  { spec: 'bv2-ideator-surface.json', old: 'seed-bv2-ideator-surface-tasks.js', hash: '5f8ed981593dfa4738b6dd97208ef0b0aec01a4d7e3eca8abc76caa5d8901f5c' },
+];
+
+let passed = 0, failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.stack || err.message}`); }
+}
+const readSpec = (f) => JSON.parse(fs.readFileSync(path.join(FIX, f), 'utf8'));
+const sha = (writes) => crypto.createHash('sha256').update(canonical(writes)).digest('hex');
+const quiet = () => {};
+const noExit = (code) => { throw new Error(`seeder exited ${code}`); };
+
+function run(cmd, args, env) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, { cwd: ROOT, env: { ...process.env, ...env } });
+    let out = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => { out += d; });
+    p.on('close', (code) => resolve({ code, out }));
+  });
+}
+
+async function runNew(spec) {
+  const api = await startFakeApi();
+  try {
+    await seedTasks(spec, { api: fetchApi(api.base), log: quiet, exit: noExit });
+    return { writes: api.writes(), tasks: api.tasks };
+  } finally { await api.close(); }
+}
+
+// ---- equivalence with the three scripts it replaced -------------------------------------
+
+for (const h of HISTORICAL) {
+  await test(`${h.spec} sends exactly the writes ${h.old} sent`, async () => {
+    const spec = readSpec(h.spec);
+    assert.deepEqual(validateSpec(spec), [], 'the historical spec is valid');
+    const next = await runNew(spec);
+    assert.equal(next.tasks.length, spec.tasks.length, 'every task was filed');
+    assert.equal(sha(next.writes), h.hash, 'same writes, same order, as the old script sent');
+  });
+}
+
+// ---- the example spec and the dry run ----------------------------------------------------
+
+await test('the example spec is valid', async () => {
+  assert.deepEqual(validateSpec(JSON.parse(fs.readFileSync(EXAMPLE, 'utf8'))), []);
+});
+
+await test('--dry-run prints the plan and files nothing', async () => {
+  const api = await startFakeApi();
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-dry-'));
+  try {
+    const r = await run(process.execPath, [SEEDER, EXAMPLE, '--dry-run'], { GDS_API_BASE: api.base, BONGOS_API_BASE: api.base, HOME: home, USERPROFILE: home });
+    assert.equal(r.code, 0, r.out);
+    const spec = JSON.parse(fs.readFileSync(EXAMPLE, 'utf8'));
+    for (const t of spec.tasks) assert.ok(r.out.includes(`${t.ref}  `) && r.out.includes(t.title), `plan lists ${t.ref}`);
+    assert.match(r.out, /Nothing was filed\./);
+    assert.equal(api.requests.length, 0, 'not one request reached the API');
+  } finally { await api.close(); fs.rmSync(home, { recursive: true, force: true }); }
+});
+
+await test('an invalid spec is refused before any write', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-bad-'));
+  const file = path.join(dir, 'bad.json');
+  fs.writeFileSync(file, JSON.stringify({ version_id: 'V', goal_id: 1, source_ref_prefix: 'p', tasks: [] }));
+  const r = await run(process.execPath, [SEEDER, file, '--dry-run'], {});
+  fs.rmSync(dir, { recursive: true, force: true });
+  assert.equal(r.code, 1);
+  assert.match(r.out, /tasks must be a non-empty array/);
+});
+
+// ---- validation ---------------------------------------------------------------------------
+
+const base = () => ({
+  version_id: 'V', goal_id: 7, source_ref_prefix: 'p',
+  tasks: [
+    { ref: 'R1', title: 't1', description: 'd', kind: 'feature', discipline: 'engineer', priority: 3, criterion_ids: ['slug-a'] },
+    { ref: 'R2', title: 't2', description: 'd', kind: 'verify', discipline: 'engineer', priority: 3, criterion_ids: ['slug-a'], deps: ['R1'] },
+  ],
+});
+
+await test('validation names each broken thing', async () => {
+  const s = base();
+  s.tasks[1].ref = 'R1';
+  assert.ok(validateSpec(s).some((e) => /duplicate ref/.test(e)));
+  const u = base(); u.tasks[1].deps = ['R9'];
+  assert.ok(validateSpec(u).some((e) => /unknown ref R9/.test(e)));
+  const self = base(); self.tasks[1].deps = ['R2'];
+  assert.ok(validateSpec(self).some((e) => /depends on itself/.test(e)));
+  const p = base(); p.promote = ['R7'];
+  assert.ok(validateSpec(p).some((e) => /promote: unknown ref R7/.test(e)));
+});
+
+await test('a positional "Cn" criterion ref is refused unless the spec opts in (learning 1000188)', async () => {
+  const s = base(); s.tasks[0].criterion_ids = ['C1'];
+  assert.ok(validateSpec(s).some((e) => /positional criterion ref/.test(e)));
+  s.allow_positional_criteria = true;
+  assert.deepEqual(validateSpec(s), []);
+});
+
+// ---- the seeding contract: baseline, replay, verify ---------------------------------------
+
+await test('a re-run replays every task and still verifies (only created links are tallied)', async () => {
+  const api = await startFakeApi({ goalCriteria: { 7: { 'slug-a': 4 } } });
+  try {
+    const first = await seedTasks(base(), { api: fetchApi(api.base), log: quiet, exit: noExit });
+    assert.equal(first.created, 2);
+    const again = await seedTasks(base(), { api: fetchApi(api.base), log: quiet, exit: noExit });
+    assert.equal(again.replayed, 2);
+    assert.equal(api.tasks.length, 2, 'the replay filed nothing new');
+  } finally { await api.close(); }
+});
+
+await test('a criterion link that did not land exits 1', async () => {
+  const api = await startFakeApi();
+  const lying = fetchApi(api.base);
+  // A server that files the task but drops its criterion link: the GET shows zero.
+  const transport = async (m, p, b) => (m === 'GET' ? { status: 200, ok: true, json: { criteria: [] } } : lying(m, p, b));
+  let code = null; const lines = [];
+  try {
+    await seedTasks(base(), { api: transport, log: (l) => lines.push(l), exit: (c) => { code = c; } });
+  } finally { await api.close(); }
+  assert.equal(code, 1);
+  assert.ok(lines.some((l) => /VERIFY FAILED/.test(l)));
+});
+
+await test('a follow-up link waits for the task it names', async () => {
+  const s = base();
+  s.links = [{ method: 'PATCH', path: '/inbox/55', body: { status: 'promoted', promoted_to_task_id: { $task: 'R2' } } }];
+  const api = await startFakeApi();
+  try {
+    await seedTasks(s, { api: fetchApi(api.base), log: quiet, exit: noExit });
+    const patch = api.writes().find((w) => w.method === 'PATCH');
+    assert.deepEqual(patch.body, { status: 'promoted', promoted_to_task_id: Number(api.tasks[1].id) });
+  } finally { await api.close(); }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exitCode = 1;

package/tests/seed_verify_criteria.mjs

@@ -15,7 +15,6 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
 
 const require = createRequire(import.meta.url);
 const {
@@ -225,11 +224,8 @@ test('a fully re-run seed (every create a replay) plans nothing and verifies OK'
   assert.deepEqual(diffCriterionLinks(tallyCreated(responses), [{ criterion_id: 'ours', linked_tasks: 2 }], { baseline: { ours: 2 } }), []);
 });
 
-test('the baselined reference seed skips replays when it tallies', () => {
-  const src = readFileSync(new URL('../scripts/bongos/seed-bv2-ideator-surface-tasks.js', import.meta.url), 'utf8');
-  assert.match(src, /baselineSeedCriteria\(/, 'it takes a baseline');
-  assert.match(src, /if \(!r\.json\.idempotent\) criterionIdListsPerTask\.push\(t\.crit\);/, 'and tallies only created tasks');
-});
+// That the real seeder baselines and skips replays when it tallies is proven by behaviour, not
+// by its source text: tests/seed_tasks.mjs re-runs a spec against a fake API (task 1004979).
 
 await testAsync('baselineSeedCriteria snapshots the goal before any write', async () => {
   const logs = [];

package/tests/session_start_freshness.mjs

@@ -16,10 +16,15 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { requireHostModule } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
-const { decideFreshness } = requireHostModule(require, '../.claude/hooks/session-start.js');
+const {
+  decideFreshness, planFetch, viewNote, staleViewLine, lastMainFetchMs, FETCH_FRESH_MS, FETCH_OLD_NOTE_MS,
+} = requireHostModule(require, '../.claude/hooks/session-start.js');
 
 let passed = 0;
 let failed = 0;
@@ -120,5 +125,65 @@ test('dirty and ahead → still just warn (no pull)', () => {
   assert.equal(d.action, 'warn');
 });
 
+// ---------- the fetch is off the critical path (task 1004928) ----------
+// The hook used to block on `git fetch` (4 s timeout). It now judges against the local
+// origin/main, fetches in the background when that view is old, and says how old it is.
+
+const NOW = Date.parse('2026-10-28T12:00:00Z');
+const MIN = 60000;
+
+test('planFetch: a view fetched under 10 min ago is used as-is, no fetch', () => {
+  const p = planFetch({ lastFetchMs: NOW - 9 * MIN, nowMs: NOW });
+  assert.equal(p.background, false);
+  assert.equal(p.ageMs, 9 * MIN);
+});
+
+test('planFetch: an older view starts a background fetch', () => {
+  assert.equal(planFetch({ lastFetchMs: NOW - FETCH_FRESH_MS, nowMs: NOW }).background, true);
+});
+
+test('planFetch: never fetched (null) → background fetch, age unknown', () => {
+  const p = planFetch({ lastFetchMs: null, nowMs: NOW });
+  assert.equal(p.background, true);
+  assert.equal(p.ageMs, null);
+});
+
+test('viewNote: the behind-count names the age of its origin/main', () => {
+  assert.equal(viewNote({ ageMs: 4 * MIN, background: false }), 'as fetched 4m ago');
+  assert.equal(viewNote({ ageMs: 3 * 60 * MIN, background: true }), 'as fetched 3h ago; a fresh fetch is running in the background');
+  assert.match(viewNote({ ageMs: null, background: true }), /time unknown/);
+});
+
+test('staleViewLine: silent when the view is fresh or merely minutes old', () => {
+  assert.equal(staleViewLine({ ageMs: 2 * MIN, background: false }), null);
+  assert.equal(staleViewLine({ ageMs: 20 * MIN, background: true }), null);
+});
+
+test('staleViewLine: an old or unknown view says "up to date" is unconfirmed instead of staying silent', () => {
+  assert.match(staleViewLine({ ageMs: FETCH_OLD_NOTE_MS, background: true }), /last fetched 1h ago.*unconfirmed/);
+  assert.match(staleViewLine({ ageMs: null, background: true }), /never been fetched/);
+});
+
+test('lastMainFetchMs: the newest FETCH_HEAD across worktrees that recorded main wins', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ss-fetch-'));
+  try {
+    fs.mkdirSync(path.join(dir, 'worktrees', 'a'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'worktrees', 'b'), { recursive: true });
+    const main = "abc\t\tbranch 'main' of https://example.invalid/repo\n";
+    const other = "def\t\tbranch 'feature' of https://example.invalid/repo\n";
+    const put = (rel, body, t) => { const f = path.join(dir, rel); fs.writeFileSync(f, body); fs.utimesSync(f, t / 1000, t / 1000); };
+    put('FETCH_HEAD', main, NOW - 60 * MIN);
+    put(path.join('worktrees', 'a', 'FETCH_HEAD'), main, NOW - 5 * MIN);
+    put(path.join('worktrees', 'b', 'FETCH_HEAD'), other, NOW - 1 * MIN); // newest, but not main
+    assert.equal(Math.round(lastMainFetchMs(dir) / 1000), Math.round((NOW - 5 * MIN) / 1000));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('lastMainFetchMs: no FETCH_HEAD anywhere → null (never fetched)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ss-fetch-'));
+  try { assert.equal(lastMainFetchMs(dir), null); } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  assert.equal(lastMainFetchMs(null), null);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);