@bongos/core 1.20.60 → 1.20.62

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

@@ -0,0 +1,215 @@
+// tests/autonomy_runner_identity.mjs — the runner card says which PC, which Claude
+// account, which code, and whether the runner is live or restarting (task 1004407).
+//
+// Owner ruling, 2026-10-01: showing the code version is good, and showing when it
+// is restarting versus live is better, along with which always-on PC and which
+// Claude account it runs on. These pin each of those from the runner that reports
+// them, through the route and the SQL, to the verdict the hall renders. The rule
+// that holds across all of it: an unknown is shown as nothing, never as a guess,
+// and a secret is never what gets sent.
+//
+// DB-free, no network. Run:  node --test tests/autonomy_runner_identity.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const req = createRequire(import.meta.url);
+const express = req('express');
+const { attachFail } = req(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+const health = req(path.join(ROOT, 'modules/autonomy/runner-health.js'));
+const runner = req(path.join(ROOT, 'scripts/gds/autobongos-run.js'));
+
+const NOW = Date.parse('2026-10-01T12:00:00.000Z');
+const agoS = (s) => new Date(NOW - s * 1000).toISOString();
+const A = 'a'.repeat(40);
+const B = 'b'.repeat(40);
+const hb = (over = {}) => ({ host: 'gmk-always-on', mode: 'full', last_event: 'loop', last_seen_at: agoS(30), ...over });
+
+// ── live or restarting ───────────────────────────────────────────────────────────
+
+test('a runner that just exited to pick up new code reads RESTARTING, not dead', () => {
+  const d = health.describeRunner(hb({ last_event: 'upgrade_exit', last_seen_at: agoS(90) }), { nowMs: NOW });
+  assert.equal(d.state, 'restarting');
+  assert.equal(d.ok, true, 'a restart is not a fault');
+  assert.match(d.detail, /restarting on gmk-always-on to pick up new code/);
+});
+
+test('a restart that never came back is dead, and says it was a restart', () => {
+  const d = health.describeRunner(hb({ last_event: 'upgrade_exit', last_seen_at: agoS(health.RESTART_S + 60) }), { nowMs: NOW });
+  assert.equal(d.state, 'dead');
+  assert.equal(d.ok, false);
+  assert.match(d.detail, /exited on gmk-always-on .* to restart on new code and has not come back/);
+});
+
+test('the restart window ends exactly at RESTART_S', () => {
+  assert.equal(health.describeRunner(hb({ last_event: 'upgrade_exit', last_seen_at: agoS(health.RESTART_S) }), { nowMs: NOW }).state, 'restarting');
+  assert.equal(health.describeRunner(hb({ last_event: 'upgrade_exit', last_seen_at: agoS(health.RESTART_S + 1) }), { nowMs: NOW }).state, 'dead');
+});
+
+test('a live runner says what it last did, in words', () => {
+  assert.match(health.describeRunner(hb({ last_event: 'code_refreshed' }), { nowMs: NOW }).detail, /updated its code in place on gmk-always-on/);
+  assert.match(health.describeRunner(hb({ last_event: 'waiting' }), { nowMs: NOW }).detail, /waiting for work/);
+  assert.match(health.describeRunner(hb({ last_event: 'loop' }), { nowMs: NOW }).detail, /^running on/, 'an event with no words keeps the old wording');
+  assert.match(health.describeRunner(hb({ working_task_id: '4242', last_event: 'worked' }), { nowMs: NOW }).detail, /working task 4242/);
+});
+
+// ── which code ───────────────────────────────────────────────────────────────────
+
+test('the code version is shown short, and flagged when it is behind main', () => {
+  const d = health.describeRunner(hb({ head: A, main_head: B }), { nowMs: NOW });
+  assert.equal(d.code.short, 'aaaaaaaa');
+  assert.equal(d.code.behind, true);
+  assert.equal(d.code.mainShort, 'bbbbbbbb');
+  assert.equal(health.describeRunner(hb({ head: A, main_head: A }), { nowMs: NOW }).code.behind, false);
+});
+
+test('an unknown main is never drawn as "out of date"', () => {
+  const c = health.describeRunner(hb({ head: A }), { nowMs: NOW }).code;
+  assert.equal(c.behind, null);
+  assert.equal(c.mainShort, null);
+});
+
+test('a checkout refreshed in place is current by what is on DISK', () => {
+  // Workers and child processes run what is on disk (task 1004406), so a
+  // refreshed runner whose own process is older is still up to date.
+  const c = health.describeRunner(hb({ head: A, disk_head: B, main_head: B }), { nowMs: NOW }).code;
+  assert.equal(c.behind, false);
+  assert.equal(c.diskShort, 'bbbbbbbb');
+});
+
+test('no head, or a head that is not a commit, shows no code line at all', () => {
+  for (const head of [null, undefined, '', 'abc', 'Z'.repeat(40), A.toUpperCase()]) {
+    assert.equal(health.describeRunner(hb({ head }), { nowMs: NOW }).code, null, String(head));
+  }
+});
+
+// ── which PC and which account ───────────────────────────────────────────────────
+
+test('the PC and the Claude account ride on every state, dead included', () => {
+  for (const [over, state] of [[{}, 'alive'], [{ last_seen_at: agoS(health.LATE_S + 1) }, 'dead'], [{ last_event: 'upgrade_exit' }, 'restarting']]) {
+    const d = health.describeRunner(hb({ claude_account: 'me@example.com', head: A, ...over }), { nowMs: NOW });
+    assert.equal(d.state, state);
+    assert.equal(d.host, 'gmk-always-on');
+    assert.equal(d.account, 'me@example.com', `${state} must still say whose account it spent`);
+    assert.ok(d.code, `${state} must still say which code`);
+  }
+});
+
+test('the account label names a key or a token by its variable, never its value', () => {
+  const secret = 'sk-ant-SECRET-VALUE';
+  const viaKey = runner.claudeAccountLabel({ env: { ANTHROPIC_API_KEY: secret }, readFile: () => { throw new Error('unread'); } });
+  assert.equal(viaKey, 'an API key (ANTHROPIC_API_KEY)');
+  const viaToken = runner.claudeAccountLabel({ env: { CLAUDE_CODE_OAUTH_TOKEN: secret }, readFile: () => { throw new Error('unread'); } });
+  assert.equal(viaToken, 'a Claude token (CLAUDE_CODE_OAUTH_TOKEN)');
+  assert.ok(!viaKey.includes(secret) && !viaToken.includes(secret));
+});
+
+test('otherwise the label is the login Claude Code records, with its organisation', () => {
+  const seen = [];
+  const file = (o) => (p) => { seen.push(p); return JSON.stringify({ oauthAccount: o, primaryApiKey: 'never-read' }); };
+  assert.equal(runner.claudeAccountLabel({ env: { CLAUDE_CONFIG_DIR: '/cfg' }, readFile: file({ emailAddress: 'me@example.com', organizationName: 'Acme' }) }), 'me@example.com · Acme');
+  assert.equal(path.normalize(seen[0]), path.normalize('/cfg/.claude.json'), 'CLAUDE_CONFIG_DIR is where Claude Code keeps it when set');
+  assert.equal(runner.claudeAccountLabel({ env: {}, readFile: file({ emailAddress: 'me@example.com' }) }), 'me@example.com');
+  assert.equal(runner.claudeAccountLabel({ env: {}, readFile: file({}) }), null, 'no login reads as unknown');
+  assert.equal(runner.claudeAccountLabel({ env: {}, readFile: () => 'not json' }), null);
+  assert.equal(runner.claudeAccountLabel({ env: {}, readFile: () => { throw new Error('ENOENT'); } }), null);
+});
+
+// ── the runner sends it ──────────────────────────────────────────────────────────
+
+test('every server check-in carries the code and the account, and the newest main seen', async () => {
+  const bodies = [];
+  const api = { autonomy: { postAutonomyHeartbeat: async ({ body }) => { bodies.push(body); return { ok: true }; } } };
+  const state = runner.newRunnerState();
+  // codeDrifted is what learns main's tip; it must keep it for the heartbeat.
+  await runner.codeDrifted({ loadedHead: async () => A, run: async () => ({ ok: true, stdout: `${B}\trefs/heads/main\n` }), state });
+  assert.equal(state.mainHead, B);
+  await runner.loadedHead({ run: async () => ({ ok: true, stdout: `${A}\n` }) });
+  await runner.postHeartbeat({ last_event: 'loop' }, { api, state, claudeAccountLabel: () => 'me@example.com' });
+  assert.equal(bodies[0].head, A);
+  assert.equal(bodies[0].main_head, B);
+  assert.equal(bodies[0].claude_account, 'me@example.com');
+  assert.equal(bodies[0].last_event, 'loop');
+  assert.equal('disk_head' in bodies[0], false, 'no refresh in place, so no disk_head');
+
+  state.diskHead = B;
+  await runner.postHeartbeat({}, { api, state, claudeAccountLabel: () => null });
+  assert.equal(bodies[1].disk_head, B);
+  assert.equal('claude_account' in bodies[1], false, 'an unknown account is left out, not sent empty');
+});
+
+// ── the route and the SQL ────────────────────────────────────────────────────────
+
+function autonomyRouter() {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const saved = { b: api.requireBuilder, p: api.requirePermission };
+  api.requireBuilder = (r, _s, next) => { r.builder = { id: 3, rank: 'archon' }; next(); };
+  api.requirePermission = () => (_r, _s, next) => next();
+  const routePath = req.resolve(path.join(ROOT, 'modules/autonomy/routes/autonomy.js'));
+  delete req.cache[routePath];
+  try { return req(routePath)(); } finally { api.requireBuilder = saved.b; api.requirePermission = saved.p; }
+}
+
+test('the route stores a commit only if it is one, and the account label as sent', async () => {
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = db.recordRunnerHeartbeat;
+  const seen = [];
+  db.recordRunnerHeartbeat = async (a) => { seen.push(a); return {}; };
+  const app = express(); app.use(express.json()); app.use(attachFail); app.use(autonomyRouter());
+  const server = app.listen(0); await new Promise((r) => server.once('listening', r));
+  const post = (body) => fetch(`http://127.0.0.1:${server.address().port}/autonomy/heartbeat`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  try {
+    let r = await post({ host: 'gmk-always-on', head: A, disk_head: B, main_head: B, claude_account: '  me@example.com  ' });
+    assert.equal(r.status, 200);
+    assert.deepEqual([seen[0].head, seen[0].diskHead, seen[0].mainHead, seen[0].claudeAccount], [A, B, B, 'me@example.com']);
+    r = await post({ host: 'gmk-always-on', head: 'not-a-commit', main_head: A.toUpperCase(), claude_account: '' });
+    assert.equal(r.status, 200, 'a bad version never costs the runner its check-in');
+    assert.deepEqual([seen[1].head, seen[1].mainHead, seen[1].claudeAccount], [null, null, null]);
+    r = await post({ host: 'gmk-always-on', claude_account: 'x'.repeat(201) });
+    assert.equal(r.status, 400, 'the label is capped, so a key pasted into it by mistake is refused, not stored');
+  } finally {
+    server.close();
+    db.recordRunnerHeartbeat = saved;
+  }
+});
+
+test('the heartbeat SQL overwrites the identity every beat and reads it back', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = api.pool.query;
+  const calls = [];
+  api.pool.query = async (sql, params) => { calls.push({ sql, params }); return { rows: [{ head: A }] }; };
+  try {
+    await db.recordRunnerHeartbeat({ builderId: 3, host: 'gmk-always-on', head: A, diskHead: B, mainHead: B, claudeAccount: 'me@example.com' });
+    for (const col of ['head', 'disk_head', 'main_head', 'claude_account']) {
+      assert.match(calls[0].sql, new RegExp(`\\b${col} = EXCLUDED\\.${col}\\b`), `${col} is overwritten, never kept from the last process`);
+    }
+    assert.deepEqual(calls[0].params.slice(9), [A, B, B, 'me@example.com']);
+    await db.readRunnerHeartbeats(3);
+    assert.match(calls[1].sql, /head, disk_head, main_head, claude_account/);
+  } finally {
+    api.pool.query = saved;
+  }
+});
+
+test('the migration adds the four columns, additively', () => {
+  const sql = fs.readFileSync(path.join(ROOT, 'modules/autonomy/migrations/autonomy_004_runner_identity.sql'), 'utf8')
+    .split('\n').filter((l) => !l.trim().startsWith('--')).join('\n');
+  for (const col of ['head', 'disk_head', 'main_head', 'claude_account']) {
+    assert.match(sql, new RegExp(`ADD COLUMN IF NOT EXISTS ${col} text`));
+  }
+  assert.doesNotMatch(sql, /\bDROP\b/i);
+});
+
+test('the gate card draws the PC, the account, the code and the restarting label', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/gate.js'), 'utf8');
+  assert.match(src, /restarting: 'Restarting'/);
+  assert.match(src, /PC <strong>\$\{escapeHtml\(h\.host\)\}<\/strong>/);
+  assert.match(src, /Claude account \$\{escapeHtml\(h\.account\)\}/);
+  assert.match(src, /behind main/);
+});

package/tests/update_channel_db.mjs

@@ -46,8 +46,8 @@ test('DB pinned: the sweep skips it even when the roster says minor', () => {
   const [inst] = uc.applyDbChannels([entry({ channel: 'minor' })], dbOf({ cloudbongos: 'pinned' }));
   assert.equal(inst.channel, 'pinned');
   assert.equal(targetFor(inst), null);
-  // subscribe.js skips on exactly this value, and decides it AFTER the DB rule is applied.
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+  // update-sweep.js skips on exactly this value, and decides it AFTER the DB rule is applied.
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   const applied = src.indexOf('channel.applyDbChannels(');
   const skip = src.indexOf("inst.channel === 'pinned'");
   assert.ok(applied > 0 && skip > applied, 'the pinned skip must read the channel after the /deploy rule is applied');
@@ -69,10 +69,17 @@ test('readDbChannels: no database named → not read, with the reason, and psql
   let spawned = false;
   const r = uc.readDbChannels({ env: {}, run: () => { spawned = true; } });
   assert.equal(r.ok, false);
-  assert.match(r.reason, /no DATABASE_URL or PGDATABASE/);
+  assert.match(r.reason, /no UPDATE_CHANNEL_DB \(or DATABASE_URL \/ PGDATABASE\)/);
   assert.equal(spawned, false);
 });
 
+test('readDbChannels: UPDATE_CHANNEL_DB wins, so a unit need not set PGDATABASE (which leaks into tenant upgrades)', () => {
+  let target;
+  uc.readDbChannels({ env: { UPDATE_CHANNEL_DB: 'cloudbongos', DATABASE_URL: 'postgres://other', PGDATABASE: 'tenant' }, run: (_c, a) => { target = a[1]; return { status: 0, stdout: '' }; } });
+  assert.equal(target, 'cloudbongos');
+  assert.equal(uc.CHANNEL_DB_ENV, 'UPDATE_CHANNEL_DB');
+});
+
 test('readDbChannels: parses psql -At tab output into slug → channel, from the sweep env only', () => {
   let args;
   const run = (cmd, a) => { args = [cmd, ...a]; return { status: 0, stdout: 'cloudbongos\tminor\ncharter\tpatch\n\n', stderr: '' }; };
@@ -112,12 +119,12 @@ test('channelLine: the sweep log names the channel and where it came from', () =
     [entry(), entry({ slug: 'charter', channel: 'patch' })], dbOf({ cloudbongos: 'minor' }));
   assert.equal(uc.channelLine(fromDeploy), '  • cloudbongos: channel minor, set on /deploy (roster says patch, ignored)');
   assert.equal(uc.channelLine(fromRoster), '  • charter: channel patch, from the roster — no project row for this slug');
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   assert.match(src, /console\.log\(channel\.channelLine\(inst\)\)/);
 });
 
-test('subscribe.js reads the DB from its own env, never an entry env (which names that instance\'s DB)', () => {
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+test('update-sweep.js reads the DB from its own env, never an entry env (which names that instance\'s DB)', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   assert.match(src, /channel\.readDbChannels\(\{ env: process\.env \}\)/);
   // A core too old to carry the reader must keep the roster rather than crash the sweep.
   assert.match(src, /typeof channel\.readDbChannels === 'function'/);

package/tests/update_subscription_engine.mjs

@@ -334,7 +334,7 @@ test('the heal branch is reachable only when the dirty files ARE the pin', () =>
 // ---------------------------------------------------------------------------
 
 test('every commitPin call site in the lane decides about push', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   // Every CALL, excluding the definition (which is `function commitPin({ ... push = true })` —
   // its default is what these sites must not silently inherit).
   const calls = [];
@@ -358,7 +358,7 @@ test('every commitPin call site in the lane decides about push', () => {
 });
 
 test('the direct-upgrade fallback asks pinFlagsFor rather than deciding inline', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   // The fourth version of this assertion. It used to pin the inline `if` verbatim, which froze
   // the bug of task 1004122 in place: the line was correct about NOT pushing a co-tenant pin and
   // wrong about how, and a test that quotes an expression can only ever confirm it is still there.
@@ -610,7 +610,7 @@ test('preflightFlagsFor has the precedent it claims — go-live.js really does s
 });
 
 test('the direct-upgrade fallback asks preflightFlagsFor rather than deciding inline', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   assert.match(src, /upArgs\.push\(\.\.\.preflightFlagsFor\(pinMode\)\)/,
     'the clean-tree policy is a pin-mode decision and must go through the named function');
 });
@@ -618,7 +618,7 @@ test('the direct-upgrade fallback asks preflightFlagsFor rather than deciding in
 test('every commitPin call site in the lane also decides what the upgrade generated', () => {
   // The sibling of the push assertion in section 8, and for the same reason: a site that inherits
   // the `generated = []` default silently reverts to the two-bucket guard that wedged the lane.
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   const calls = [];
   const re = /commitPin\(\{/g;
   let m;
@@ -756,7 +756,7 @@ test('the post-upgrade net re-probes, rather than reusing the set from before th
   // A skill the NEW core adds is absent from the pre-upgrade answer, so reusing it would drop that
   // file into `other` and wedge the lane one release later — this defect again, wearing the next
   // version number. The heal, which runs BEFORE the bump, must keep using the pre-bump set.
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   const afterSpawn = src.split('const generatedAfter = laneGeneratedPaths(inst.dir);')[1];
   assert.ok(afterSpawn, 'the post-upgrade re-probe is gone');
   assert.equal((afterSpawn.match(/generated: generatedAfter,/g) || []).length, 2,

package/tests/update_sweep_home.mjs

@@ -0,0 +1,100 @@
+// tests/update_sweep_home.mjs — the update sweep lives in the core package and runs from it
+// (task 1004307).
+//
+// WHY. The sweep used to live only under .claude/scheduled-tasks/, which the core package never
+// ships, so cloudbongos.com's sweep ran a checkout frozen at 2026-08-25 and every later lane fix was
+// inert there. It now lives at scripts/gds/update-sweep.js. These pin the three things that keep it
+// runnable from node_modules/@bongos/core: it publishes, it needs nothing the package lacks (the
+// .claude/hooks resolver is topology-excluded), and it reads the roster from where it is told,
+// not from where its own file sits.
+//
+// Run:  node --test tests/update_sweep_home.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SWEEP = path.join(ROOT, 'scripts', 'gds', 'update-sweep.js');
+const sweep = require(SWEEP);
+const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+
+test('the sweep and every core file it requires are in the published package', () => {
+  for (const f of ['scripts/gds/update-sweep.js', 'scripts/gds/update-channel.js', 'scripts/gds/upgrade.js', 'src/module-api.js']) {
+    assert.equal(isPublishable(f), true, `${f} must publish, or the installed sweep cannot run`);
+  }
+  // The reason it moved: the old home never ships.
+  assert.equal(isPublishable('.claude/scheduled-tasks/core-update-subscription/subscribe.js'), false);
+});
+
+test('the sweep requires nothing the package lacks (no .claude/ path, no hook resolver)', () => {
+  const src = readFileSync(SWEEP, 'utf8');
+  const requires = [...src.matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]);
+  for (const r of requires) {
+    assert.ok(!r.includes('.claude') && !r.includes('_core-resolve'), `update-sweep.js requires ${r}, which the core package does not ship`);
+    if (r.startsWith('.')) assert.equal(isPublishable(path.posix.join('scripts/gds', r).replace(/\\/g, '/')), true, `${r} must publish`);
+  }
+});
+
+test('its target-instance resolver searches the same packages, in the same order, as _core-resolve.js', () => {
+  const hook = readFileSync(path.join(ROOT, '.claude', 'hooks', '_core-resolve.js'), 'utf8');
+  const m = hook.match(/const CORE_PKG_NAMES = (\[[^\]]*\]);/);
+  assert.ok(m, '_core-resolve.js CORE_PKG_NAMES not found');
+  assert.deepEqual(sweep.CORE_PKG_NAMES, JSON.parse(m[1].replace(/'/g, '"')));
+});
+
+test('coreModulePathFrom finds a target instance\'s INSTALLED core, root first', () => {
+  const inst = mkdtempSync(path.join(tmpdir(), 'sweep-home-'));
+  const pkg = path.join(inst, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(path.join(pkg, 'upgrade.js'), '');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/upgrade.js'), path.join(pkg, 'upgrade.js'));
+  mkdirSync(path.join(inst, 'scripts', 'gds'), { recursive: true });
+  writeFileSync(path.join(inst, 'scripts', 'gds', 'upgrade.js'), '');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/upgrade.js'), path.join(inst, 'scripts', 'gds', 'upgrade.js'), 'a monolith root wins, as in _core-resolve.js');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/absent.js'), null);
+});
+
+test('run from elsewhere, it reads the roster named by --instance and says which core is sweeping', () => {
+  const rosterRoot = mkdtempSync(path.join(tmpdir(), 'sweep-roster-'));
+  mkdirSync(path.join(rosterRoot, 'config'));
+  writeFileSync(path.join(rosterRoot, 'config', 'update-subscriptions.json'),
+    JSON.stringify({ instances: [{ slug: 'held', dir: path.join(rosterRoot, 'nowhere'), channel: 'pinned' }] }));
+  const cwd = mkdtempSync(path.join(tmpdir(), 'sweep-cwd-'));
+  const r = spawnSync(process.execPath, [SWEEP, '--instance', rosterRoot], { cwd, encoding: 'utf8', env: { ...process.env, DATABASE_URL: '', PGDATABASE: '' } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, new RegExp(`update-sweep · running from .+ \\(core \\d+\\.\\d+\\.\\d+\\) · roster ${rosterRoot.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')}`));
+  assert.match(r.stdout, /1 subscribed instance/);
+  assert.match(r.stdout, /held: pinned — skipped/);
+});
+
+test('without --instance it reads the roster in its working directory (the unit\'s WorkingDirectory)', () => {
+  const cwd = mkdtempSync(path.join(tmpdir(), 'sweep-cwd-'));
+  const r = spawnSync(process.execPath, [SWEEP], { cwd, encoding: 'utf8', env: { ...process.env, DATABASE_URL: '', PGDATABASE: '' } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /no roster file — nothing subscribed/);
+  assert.ok(r.stdout.includes(`roster ${cwd}`) || r.stdout.includes(`roster ${path.resolve(cwd)}`), r.stdout);
+});
+
+test('the subscribe.js shim runs the same body, with its instance root as the default roster root', () => {
+  const shim = require('../.claude/scheduled-tasks/core-update-subscription/subscribe.js');
+  assert.equal(shim, sweep, 'the shim re-exports the core body, so tests and callers see one sweep');
+  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  assert.match(src, /requireCore\('scripts\/gds\/update-sweep\.js'\)/);
+  assert.match(src, /sweep\.main\(\{ instanceRoot: INSTANCE_ROOT \}\)/);
+});
+
+test('the recipe\'s drop-in names the file that really ships, and the safe database setting', () => {
+  const recipe = readFileSync(path.join(ROOT, 'docs', 'recipes', 'upgrading-the-core.md'), 'utf8');
+  const execs = [...recipe.matchAll(/node_modules\/@bongos\/core\/(scripts\/gds\/[\w-]+\.js)/g)].map((m) => m[1]);
+  assert.ok(execs.length >= 2, 'the drop-in and its dry run both name the installed sweep');
+  for (const rel of execs) assert.equal(rel, 'scripts/gds/update-sweep.js');
+  assert.match(recipe, /Environment=UPDATE_CHANNEL_DB=/);
+  assert.doesNotMatch(recipe, /Environment=PGDATABASE=/, 'a unit-level PGDATABASE leaks into tenant upgrades');
+});