@bongos/core 1.17.1 → 1.17.2

package/tests/provisioning_github_app_routes.mjs

@@ -71,6 +71,21 @@ console.log('POST /provisioning/instances/:id/github-app (mint the one-click lin
   t('the attempt row was persisted with the minted state', !!(stored && stored.instanceId === 42 && stored.state === j.state && stored.requestedBy === 7));
 }
 
+console.log('\nprovisioningOrigin override (task 2101 — customer App carries the PLATFORM brand, not the game domain):');
+{
+  // A control plane that co-hosts a game (OTB = customer 0) has a GAME-branded publicOrigin.
+  // provisioningOrigin is the dedicated front door the customer's GitHub App must point at,
+  // so mothershipOrigin() must prefer it over publicOrigin. mothershipOrigin() calls
+  // api.branding() (module-api captured the fn ref at require-time), so override THAT.
+  const prevBranding = api.branding;
+  api.branding = () => ({ ...realBranding(), identity: { productName: 'Cloud Bongos' }, domains: { publicOrigin: 'https://amazonprimea.com', provisioningOrigin: 'https://get.cloudbongos.com' } });
+  const res = await fetch(`${base}/provisioning/instances/42/github-app`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
+  const j = await res.json();
+  t('redirect_url uses provisioningOrigin, not the game publicOrigin', j.manifest && j.manifest.redirect_url === 'https://get.cloudbongos.com/api/bongos/provisioning/github-app/callback', j.manifest && j.manifest.redirect_url);
+  t('webhook hook_attributes.url also uses provisioningOrigin', j.manifest && j.manifest.hook_attributes && j.manifest.hook_attributes.url === 'https://get.cloudbongos.com/api/bongos/provisioning/github-app/webhook', j.manifest && j.manifest.hook_attributes && j.manifest.hook_attributes.url);
+  api.branding = prevBranding;
+}
+
 console.log('\nGET /provisioning/github-app/callback (the public GitHub redirect):');
 {
   const res = await fetch(`${base}/provisioning/github-app/callback?code=GHCODE123&state=GOODSTATE`);

package/tests/publish_manifest.mjs

@@ -44,13 +44,13 @@ const PUBLISH = [
   'scripts/gds/ship.js',                   // the ship/grade pipeline publishes (sans secrets)
   'scripts/gds/publish-manifest.js',
   'scripts/migrate.sh',
-  'server.js',
   'migrations/182_some_change.sql',
   'tests/publish_manifest.mjs',
   'modules/lifecycle/db.js',
   'modules/grading/grader.js',
   'modules/hall-ui/public/work.js',
   'modules/dev-box/boxes.js',
+  'modules/provisioning/provisioning.js',  // instance-hosting control plane — CORE like its sibling dev-box (task 2135)
   // served-at-runtime surfaces a standalone must carry (task 2078) — their absence
   // from the packaged core 404'd the hall UI + /docs on demo.cloudbongos.com
   'clients/bongos-client/bongos-client.global.js', // /lib/bongos-client.js (window.BongosClient)
@@ -91,8 +91,19 @@ const EXCLUDE = [
   'src/world/terrain.js',
   'src/rooms/WorldRoom.js',
   'src/preview-server.js',
+  'server.js',                             // repo-root game+platform entry (top-level require('colyseus')); the core boots via src/platform-server.js (task 2134)
   'scripts/art/orchestrate.js',            // art-feature tooling under scripts/ (legacy location)
+  'scripts/gds/art-stage.js',              // art sandbox-staging CLI (requires modules/art-pipeline); excluded with the art feature (task 2135)
   'scripts/tile-add.js',
+  // host-feature tests that statically import an excluded module's source: shipped in the
+  // core package they'd MODULE_NOT_FOUND; excluded with the feature they cover (task 2147)
+  'tests/walkability.mjs',
+  'tests/terrain_picker.mjs',
+  'tests/snapshot_picker.mjs',
+  'tests/sprite_facing.mjs',
+  'tests/turn_in_place.mjs',
+  'tests/day_cycle.mjs',
+  'tests/art_key.mjs',
   // instance identity + history
   'config/branding.json',
   'config/modules.json',
@@ -106,6 +117,7 @@ const EXCLUDE = [
   'blockers/blockers.md',
   'limitations/v1-shipped.md',
   'generative-ideas.md',
+  'migrations/instance/018_pms_v3_planning_seed.sql',   // instance seed migrations = host scope-truth (ADR 0105, task 2140)
   '.env.local',
   // topology / deploy / CI / local gate hooks / secrets — read-sensitive docs
   'infra/Caddyfile',
@@ -180,5 +192,44 @@ t('allowlist + denylist are non-empty arrays of strings', () => {
   for (const g of [...PUBLISH_ALLOWLIST, ...PUBLISH_DENYLIST]) assert.equal(typeof g, 'string');
 });
 
+// ── R89 split guard: no PUBLISHABLE test may statically import an EXCLUDED module ─────
+// tests/ is allowlisted, but a test that imports host-module source (game / art-pipeline)
+// would ship inside the @bongos/core package WITHOUT that module → MODULE_NOT_FOUND when a
+// core CI/consumer runs it, and the cutover would delete OTB's own host tests. Every such
+// test must be host-excluded (see CONTENT_EXCLUDE). This DERIVES the set from disk so a NEW
+// host-module test can't slip in unlisted (the enumerated assertions above would miss it).
+// Static relative-literal imports only — temp-dir fixtures (modules/alpha, …) use path.join,
+// so they never match; a module name appearing only as string DATA (this file's own arrays)
+// isn't in a require()/import statement, so it never matches either. (task 2147)
+t('no publishable test statically imports an excluded module (R89 boundary)', () => {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const { fileURLToPath } = require('node:url');
+  const testsDir = path.dirname(fileURLToPath(import.meta.url));
+  const IMPORT_RE = /(?:require|import)\s*\(\s*["'](\.\.?\/[^"']*?)modules\/([a-z0-9][a-z0-9-]*)\/[^"']*["']|from\s+["'](\.\.?\/[^"']*?)modules\/([a-z0-9][a-z0-9-]*)\/[^"']*["']/g;
+  const detected = [];   // test files that import ANY excluded module (non-vacuous check)
+  const offenders = [];  // …and are still publishable (the actual failure)
+  for (const name of fs.readdirSync(testsDir)) {
+    if (!/\.(mjs|js|cjs)$/.test(name)) continue;
+    const rel = `tests/${name}`;
+    const bad = new Set();
+    let m; IMPORT_RE.lastIndex = 0;
+    const src = fs.readFileSync(path.join(testsDir, name), 'utf8');
+    while ((m = IMPORT_RE.exec(src))) {
+      const key = m[2] || m[4];
+      if (key && !isPublishable(`modules/${key}/module.json`)) bad.add(key);
+    }
+    if (bad.size === 0) continue;
+    detected.push(rel);
+    if (isPublishable(rel)) {
+      offenders.push(`${rel} imports excluded module(s) [${[...bad].sort().join(', ')}] but is still PUBLISHABLE — add it to CONTENT_EXCLUDE (task 2147)`);
+    }
+  }
+  // non-vacuous: the scan must actually SEE the known host tests (a broken regex that
+  // matched nothing would otherwise pass silently). The 7 game/art tests are the floor.
+  assert.ok(detected.length >= 7, `expected ≥7 host-module tests detected, saw ${detected.length} — the import scan may be broken`);
+  assert.equal(offenders.length, 0, '\n        ' + offenders.join('\n        '));
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/run_routine.mjs

@@ -4,8 +4,9 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 const require = createRequire(import.meta.url);
-const { parseRoutineFrontmatter, tokenize } = require('../scripts/gds/run-routine.js');
+const { parseRoutineFrontmatter, tokenize, resolveStepArgv } = require('../scripts/gds/run-routine.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -65,5 +66,29 @@ test('tokenize splits argv and honors quotes', () => {
   assert.deepEqual(tokenize(''), []);
 });
 
+// resolveStepArgv — two-root step resolution (ADR 0108; task 2138). Explicit roots (pure).
+const ROOTS = { coreRoot: '/core', instanceRoot: '/inst' };
+
+test('resolveStepArgv: `bongos exec <rel>` resolves under the CORE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['bongos', 'exec', 'scripts/gds/box.js', 'sweep-idle', '--apply'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/box.js'), 'sweep-idle', '--apply']);
+});
+
+test('resolveStepArgv: `node scripts/...` → CORE root; `node .claude/...` companion → INSTANCE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['node', 'scripts/gds/x.js', '--flag'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/x.js'), '--flag']);
+  assert.deepEqual(
+    resolveStepArgv(['node', '.claude/scheduled-tasks/demo/run.js'], ROOTS),
+    [process.execPath, path.join('/inst', '.claude/scheduled-tasks/demo/run.js')]);
+});
+
+test('resolveStepArgv: absolute paths + non-node commands + empty pass through untouched', () => {
+  assert.deepEqual(resolveStepArgv(['node', '/abs/x.js'], ROOTS), ['node', '/abs/x.js']);
+  assert.deepEqual(resolveStepArgv(['bash', 'x.sh'], ROOTS), ['bash', 'x.sh']);
+  assert.deepEqual(resolveStepArgv([], ROOTS), []);
+});
+
 console.log(`\nrun_routine: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/run_routine_two_root.mjs

@@ -0,0 +1,77 @@
+// tests/run_routine_two_root.mjs — task 2138 (ADR 0108 configurable-root).
+//
+// Proves the deterministic cron dispatcher works in a real CONSUMER layout: it FINDS a routine
+// under resolveInstanceRoot() (the host repo — NOT the core root) and RUNS its companion step,
+// whose core require() resolves into node_modules/@bongos/core via the materialized
+// _core-resolve.js sibling. This is task 2138's "a consumer-layout dispatch finds + runs the
+// routines" done-when, exercised in a synthetic two-root tree.
+//
+// Counterfactual built in: the routine exists ONLY under the synthetic instance root, so against
+// the pre-2138 dispatcher (TASKS_DIR hardcoded to __dirname/../..) run-routine would look in THIS
+// repo, not find `demo`, and exit 2 — reddening this test. And the companion asserts its core lib
+// resolved from node_modules/@bongos/core (not the instance root), so a single-root resolve fails it.
+//
+// DB-free, no model. Run: node tests/run_routine_two_root.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(__dirname, '..'); // the core root (this repo), fixed by resolveCoreRoot()
+const RUN_ROUTINE = path.join(REPO, 'scripts', 'gds', 'run-routine.js');
+const CORE_RESOLVE = path.join(REPO, '.claude', 'hooks', '_core-resolve.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// Build a synthetic CONSUMER tree: instance content (.claude/) at its OWN root; the core installed
+// under node_modules/@bongos/core carrying just the one lib the companion needs.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rr-two-root-'));
+const inst = path.join(tmp, 'instance');
+try {
+  const coreLibDir = path.join(inst, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+  fs.mkdirSync(coreLibDir, { recursive: true });
+  fs.writeFileSync(path.join(coreLibDir, 'fake-core-lib.js'), 'module.exports = { ping: () => "CORE_OK" };\n');
+
+  // the materialized _core-resolve.js sibling (the real one — its resolution is what we exercise)
+  const hooksDir = path.join(inst, '.claude', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.copyFileSync(CORE_RESOLVE, path.join(hooksDir, '_core-resolve.js'));
+
+  // a materialized deterministic routine + its instance-path companion
+  const rtDir = path.join(inst, '.claude', 'scheduled-tasks', 'demo');
+  fs.mkdirSync(rtDir, { recursive: true });
+  fs.writeFileSync(path.join(rtDir, 'SKILL.md'),
+    ['---', 'name: demo', 'mode: deterministic', 'steps:',
+      '  - command: node .claude/scheduled-tasks/demo/run.js', '    sink: none', '---', 'body', ''].join('\n'));
+  fs.writeFileSync(path.join(rtDir, 'run.js'),
+    "const { requireCore, coreModulePath } = require('../../hooks/_core-resolve.js');\n" +
+    "const { ping } = requireCore('scripts/gds/fake-core-lib.js');\n" +
+    "console.log('RESOLVED=' + coreModulePath('scripts/gds/fake-core-lib.js'));\n" +
+    "console.log(ping());\n");
+
+  test('dispatch finds the routine under resolveInstanceRoot() and runs it; companion resolves core from node_modules', () => {
+    const out = execFileSync(process.execPath, [RUN_ROUTINE, 'demo'], {
+      encoding: 'utf8',
+      // Diverge the roots: OTB_INSTANCE_ROOT points resolveInstanceRoot() at the synthetic tree
+      // (OTB_ is an accepted legacy prefix; ADR 0108 §1); resolveCoreRoot() stays this repo.
+      // CLAUDE_PROJECT_DIR pins _core-resolve's own instance root to the synthetic tree too.
+      env: { ...process.env, OTB_INSTANCE_ROOT: inst, CLAUDE_PROJECT_DIR: inst },
+    });
+    assert.match(out, /CORE_OK/, 'companion step should have run and printed its core lib output');
+    assert.match(out, /RESOLVED=.*node_modules[/\\]@bongos[/\\]core[/\\]scripts[/\\]gds[/\\]fake-core-lib\.js/,
+      'the core lib must resolve from node_modules/@bongos/core, proving two-root (not single-root) resolution');
+  });
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\nrun_routine_two_root: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/scrubber_corpus.mjs

@@ -242,6 +242,23 @@ test('collectEnvSecrets: gathers secret-shaped env VALUES, skips benign & short'
   assert.ok(!out.includes(env.MAC_INSTALLER_CERT_P12) && !out.includes(env.APPLE_API_ISSUER_ID), 'env literals scrubbed');
 });
 
+test('collectEnvSecrets: benign shell PWD/OLDPWD are skipped, real *_PWD password vars still collected (task 2130)', () => {
+  // Regression: PWD/OLDPWD contain "pwd" (the password alternative in ENV_SECRET_KEY_RE)
+  // and hold a directory PATH ≥ 8 chars, so pre-fix they were collected as "secrets" — then
+  // the package-core no-leak gate aborted a legit publish whenever that path appeared verbatim
+  // in a functional file (a /Users/<name> anti-pattern comment), passing or failing purely on
+  // the operator's last `cd`. Exact-match exclusion, so genuine password vars still match.
+  const env = {
+    PWD: '/Users/larskristensen/dev/Claude-OTB',
+    OLDPWD: '/Users/larskristensen',
+    MYSQL_PWD: randStr(20, 40, B64URL), // a real password var — MUST still be collected
+  };
+  const got = collectEnvSecrets(env);
+  assert.ok(!got.includes(env.PWD), 'PWD (a directory path) must not be collected');
+  assert.ok(!got.includes(env.OLDPWD), 'OLDPWD (a directory path) must not be collected');
+  assert.ok(got.includes(env.MYSQL_PWD), 'MYSQL_PWD (a real password var) must still be collected');
+});
+
 test('self-reference `key = key` (SQL SET col = col) survives — zero recall loss', () => {
   // task 1688: the core packager redacts live SQL, so a `_token` COLUMN self-increment
   // must NOT be corrupted — while a real `key = <secret>` assignment is STILL redacted.

package/tests/update_channel.mjs

@@ -0,0 +1,186 @@
+// tests/update_channel.mjs
+//
+// task 2150 / ADR 0136 — the update-subscription policy core (scripts/gds/update-channel.js).
+// Pins the channel math + manifest loading the `core-update-subscription` routine relies on:
+//   1. semver — parse (incl. prerelease), compare precedence.
+//   2. channelAllows — the pinned/patch/minor blast-radius matrix; majors + prereleases never auto.
+//   3. resolveChannelTarget — highest permitted target, or null (pinned / nothing newer / unknown).
+//   4. parseNpmViewVersions — the array / bare-string / empty shapes npm view emits.
+//   5. listAvailableVersions — ok + fail-soft with an injected runner.
+//   6. loadSubscriptions — missing/malformed → empty; channel default + validate; env kept; dropless.
+//
+// DB-free + network-free (every external is injected). Run:  node tests/update_channel.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const uc = require('../scripts/gds/update-channel.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- semver ----------------------------------------------------------------
+
+t('parseSemver: plain, v-prefixed, prerelease, junk', () => {
+  assert.deepEqual(uc.parseSemver('1.17.2'), { major: 1, minor: 17, patch: 2, pre: '' });
+  assert.deepEqual(uc.parseSemver('v2.0.0'), { major: 2, minor: 0, patch: 0, pre: '' });
+  assert.deepEqual(uc.parseSemver('1.17.2-rc.1'), { major: 1, minor: 17, patch: 2, pre: 'rc.1' });
+  assert.equal(uc.parseSemver('1.17'), null);
+  assert.equal(uc.parseSemver('latest'), null);
+  assert.equal(uc.parseSemver(''), null);
+});
+
+t('compareSemver: numeric precedence + prerelease below stable', () => {
+  assert.equal(uc.compareSemver('1.17.2', '1.17.1'), 1);
+  assert.equal(uc.compareSemver('1.17.1', '1.18.0'), -1);
+  assert.equal(uc.compareSemver('1.17.1', '2.0.0'), -1);
+  assert.equal(uc.compareSemver('1.17.2', '1.17.2'), 0);
+  assert.equal(uc.compareSemver('1.17.2-rc.1', '1.17.2'), -1); // prerelease < stable
+  assert.equal(uc.compareSemver('bogus', '1.0.0'), -1);        // unparseable sorts lowest
+});
+
+t('normalizeChannel: valid pass through, unknown/blank → patch default', () => {
+  assert.equal(uc.normalizeChannel('pinned'), 'pinned');
+  assert.equal(uc.normalizeChannel('MINOR'), 'minor');
+  assert.equal(uc.normalizeChannel('major'), 'patch'); // major is not a valid auto-channel
+  assert.equal(uc.normalizeChannel(''), 'patch');
+  assert.equal(uc.normalizeChannel(undefined), 'patch');
+});
+
+// ---- channelAllows ---------------------------------------------------------
+
+t('channelAllows: patch stays within x.y', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.10', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'patch'), false); // minor bump not allowed on patch
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'patch'), false);
+});
+
+t('channelAllows: minor allows higher minor within the major, not a major', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.5', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'minor'), false); // major never automatic
+});
+
+t('channelAllows: pinned never; not-newer never; prerelease never; unknown installed never', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.99.99', 'pinned'), false);
+  assert.equal(uc.channelAllows('1.17.2', '1.17.1', 'patch'), false); // older
+  assert.equal(uc.channelAllows('1.17.1', '1.17.1', 'patch'), false); // same
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2-rc.1', 'patch'), false); // prerelease target
+  assert.equal(uc.channelAllows(null, '1.17.2', 'patch'), false);     // unknown installed
+  assert.equal(uc.channelAllows('1.17.1', 'garbage', 'patch'), false);
+});
+
+// ---- resolveChannelTarget --------------------------------------------------
+
+const AVAIL = ['1.16.9', '1.17.0', '1.17.1', '1.17.2', '1.17.3', '1.18.0', '1.18.1', '2.0.0', '1.17.4-rc.1'];
+
+t('resolveChannelTarget: patch → highest patch on the same minor', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: AVAIL }), '1.17.3');
+});
+
+t('resolveChannelTarget: minor → highest minor within the major (not 2.0.0)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'minor', available: AVAIL }), '1.18.1');
+});
+
+t('resolveChannelTarget: pinned → null', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'pinned', available: AVAIL }), null);
+});
+
+t('resolveChannelTarget: already newest → null; prerelease never chosen', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'patch', available: AVAIL }), null);
+  // A prerelease ahead (1.17.4-rc.1) is NOT a target even though it's numerically newer.
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'minor', available: ['1.17.4-rc.1'] }), null);
+});
+
+t('resolveChannelTarget: unknown installed / empty list → null (never guesses)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: null, channel: 'patch', available: AVAIL }), null);
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: [] }), null);
+  assert.equal(uc.resolveChannelTarget({}), null);
+});
+
+// ---- parseNpmViewVersions --------------------------------------------------
+
+t('parseNpmViewVersions: array, bare string, empty, malformed', () => {
+  assert.deepEqual(uc.parseNpmViewVersions('["1.0.0","1.1.0"]'), { ok: true, versions: ['1.0.0', '1.1.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('"1.0.0"'), { ok: true, versions: ['1.0.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('   '), { ok: true, versions: [] });
+  const bad = uc.parseNpmViewVersions('not json');
+  assert.equal(bad.ok, false);
+});
+
+// ---- listAvailableVersions (injected runner) -------------------------------
+
+t('listAvailableVersions: ok path parses stdout; non-zero exit is fail-soft', () => {
+  const ok = uc.listAvailableVersions({ run: () => ({ status: 0, stdout: '["1.17.1","1.17.2"]' }) });
+  assert.deepEqual(ok, { ok: true, versions: ['1.17.1', '1.17.2'] });
+
+  const fail = uc.listAvailableVersions({ run: () => ({ status: 1, stderr: 'E404 Not Found' }) });
+  assert.equal(fail.ok, false);
+  assert.match(fail.error, /E404/);
+
+  const threw = uc.listAvailableVersions({ run: () => { throw new Error('spawn ENOENT'); } });
+  assert.equal(threw.ok, false);
+  assert.match(threw.error, /ENOENT/);
+});
+
+// ---- loadSubscriptions -----------------------------------------------------
+
+function scratchWith(obj) {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-'));
+  const cfgDir = join(dir, 'config');
+  require('node:fs').mkdirSync(cfgDir, { recursive: true });
+  writeFileSync(join(cfgDir, 'update-subscriptions.json'), typeof obj === 'string' ? obj : JSON.stringify(obj));
+  return dir;
+}
+
+t('loadSubscriptions: missing file → empty roster, present:false, no throw', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-none-'));
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.equal(r.present, false);
+  assert.equal(r.defaultChannel, 'patch');
+});
+
+t('loadSubscriptions: malformed JSON → empty + error, no throw', () => {
+  const dir = scratchWith('{ not valid');
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.match(r.error, /malformed JSON/);
+});
+
+t('loadSubscriptions: normalizes channel, keeps env, defaults from defaultChannel', () => {
+  const dir = scratchWith({
+    defaultChannel: 'minor',
+    instances: [
+      { slug: 'demo', dir: '/srv/demo', service: 'demo.service', healthUrl: 'https://demo/healthz', env: { PGDATABASE: 'demo', BAD: 5 } },
+      { slug: 'pinnedone', dir: '/srv/p', channel: 'PINNED' },
+      { slug: 'nochan', dir: '/srv/n' },
+    ],
+  });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.defaultChannel, 'minor');
+  assert.equal(r.instances.length, 3);
+  const demo = r.instances.find((i) => i.slug === 'demo');
+  assert.equal(demo.channel, 'minor');            // inherited from defaultChannel
+  assert.deepEqual(demo.env, { PGDATABASE: 'demo' }); // non-string env value dropped
+  assert.equal(r.instances.find((i) => i.slug === 'pinnedone').channel, 'pinned');
+  assert.equal(r.instances.find((i) => i.slug === 'nochan').channel, 'minor');
+});
+
+t('loadSubscriptions: an entry without a dir is dropped (cannot be upgraded)', () => {
+  const dir = scratchWith({ instances: [{ slug: 'ghost' }, { slug: 'real', dir: '/srv/real' }] });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.instances.length, 1);
+  assert.equal(r.instances[0].slug, 'real');
+});
+
+console.log(`\nupdate_channel: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/upgrade.mjs

@@ -416,6 +416,137 @@ t('runUpgrade --registry (full): pins the exact version + writes the env-fed .np
   assert.ok(!calls.some((c) => /vendor/.test(c)), 'did not vendor a tarball');
 });
 
+// ---- 9. auto-rollback on failure (task 2149) --------------------------------
+
+// A pin-aware spawn shim: `npm install` installs whatever the CURRENT pin resolves to, so the
+// forward install lands the target and a post-rollback install restores the previous core.
+// Knobs simulate a failing target install or a failing migrate.
+function pinAwareRun(calls, { dir, failMigrate = false, failInstallForVersion = null } = {}) {
+  return (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: '' };
+    if (cmd === 'npm' && args[0] === 'install') {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      const dep = pkg.dependencies['@bongos/core'];
+      const v = u.versionFromTgzPath(dep) || u.versionFromDep(dep);
+      if (failInstallForVersion && v === failInstallForVersion) return { status: 1 };
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'),
+        JSON.stringify({ name: '@bongos/core', version: v }) + '\n');
+      return { status: 0 };
+    }
+    if (cmd === 'npm' && args[0] === 'run' && args[1] === 'migrate') return { status: failMigrate ? 1 : 0 };
+    return { status: 0 }; // systemctl / restart-cmd / anything else
+  };
+}
+
+// A fake pg that records every ledger INSERT's params (params[3] = note).
+function recordingPg(queries) {
+  return { Pool: class { async query(sql, params) { queries.push({ sql, params }); } async end() {} } };
+}
+
+t('rollback on health failure: reverts pin, restarts again, re-checks health, writes ONE rolled_back ledger row', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  let fetchN = 0;
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      // forward health fails (1st fetch); the post-rollback re-check recovers (2nd fetch)
+      fetch: async () => { fetchN++; return fetchN === 1 ? { ok: false, status: 503 } : { ok: true, status: 200 }; },
+      sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false, 'a failed health check is not a success');
+  assert.equal(res.rolledBack, true, 'the upgrade rolled back');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted to the previous core');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(res.rollback.healthOk, true, 'health recovered after the rollback restart');
+  assert.equal(calls.filter((c) => c === 'systemctl restart demo.service').length, 2, 'restarted twice: forward + rollback');
+  assert.equal(queries.length, 1, 'only the rolled_back row is written (no phantom upgraded row)');
+  assert.equal(queries[0].params[1], '1.15.0', 'to_version = the attempted target');
+  assert.match(queries[0].params[3], /^rolled_back:/, 'note marks the reversal');
+});
+
+t('rollback on migrate failure: reverts pin + reinstalls previous core + rolled_back ledger', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failMigrate: true }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.match(res.rollback.reason, /migrate failed/);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(queries.length, 1);
+  assert.match(queries[0].params[3], /^rolled_back: migrate failed/);
+});
+
+t('rollback on npm-install failure: reverts pin + reinstalls previous core', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failInstallForVersion: '1.15.0' }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted after the failed install');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.match(queries[0].params[3], /^rolled_back: npm install failed/);
+});
+
+t('--no-rollback-on-failure: a failed health check does NOT revert (records the attempt, leaves the new pin)', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz', rollbackOnFailure: false },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun([], { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      fetch: async () => ({ ok: false, status: 503 }), sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(!res.rolledBack, 'no rollback when opted out');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.15.0', 'the new pin is left in place for inspection');
+  assert.equal(queries.length, 1, 'the attempt is still recorded');
+  assert.ok(!/^rolled_back/.test(queries[0].params[3] || ''), 'not marked as a rollback');
+});
+
+t('restorePin: writes a previous dep string back verbatim (file: or registry)', () => {
+  const dir = scratchConsumer({ pinned: '1.15.0' });
+  u.restorePin(dir, 'file:vendor/bongos-core-1.14.1.tgz');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1');
+  u.restorePin(dir, '^1.16.0');
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '^1.16.0');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);