@bongos/core 1.17.1 → 1.17.3

package/scripts/gds/publish-manifest.js

@@ -44,7 +44,9 @@ const PUBLISH_ALLOWLIST = [
   'src/',                 // platform engine + GDS core (the game residue is denied below)
   'scripts/',             // build + methodology tooling (deploy is denied below)
   'bin/',                 // the `cloudbongos`/`bongos` CLI entrypoint
-  'server.js',            // the single-process app entry
+  // NB: repo-root server.js is the GAME+platform entry (top-level require('colyseus'),
+  // a pruned core dep) — HOST-excluded in CONTENT_EXCLUDE below; the core boots
+  // game-less via src/platform-server.js (package-core sets that as `main`). task 2134.
   // --- the build system's shared schema + its tests ---
   'migrations/',
   'tests/',
@@ -63,6 +65,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/status-ui/',
   'modules/dev-box/',
   'modules/discord/',
+  'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
   'config/branding.neutral.json',
   'config/modules.neutral.json',
@@ -77,7 +80,7 @@ const PUBLISH_ALLOWLIST = [
   'CONTRIBUTING.md',
   'CODE_OF_CONDUCT.md',
   'docs/adr/',                       // sanitized — ADR 0065 §4 "docs/ADRs (sanitized)"
-  'docs/recipes/',
+  'docs/recipes/',                   // portable METHODOLOGY recipes only; project-specific ones (art/staging/load-test/standup/decouple) are denied below — task 2153
   'docs/design/',
   'docs/research/',
   'docs/architecture.md',
@@ -85,6 +88,11 @@ const PUBLISH_ALLOWLIST = [
   // renders broken onboarding + API-reference pages (task 2078). Redacted like the
   // rest of this docs section; the diagrams' .png/.svg regenerate on the box.
   'docs/onboarding/',                // primer.md + drachmae-and-karma.md + diagram sources (/builders/primer · /drachmae · /diagrams)
+  // API artifacts (classification settled, task 2141): CORE-shipped STARTERS so a fresh
+  // hall/docs render before first regen — but per-instance GENERATED. init + `bongos
+  // upgrade` regenerate them INTO the instance; the instance-root fitness gate
+  // (gen-api-docs --check) + tests/api_client.mjs guard drift. They ship; they are not a
+  // monolith-only artifact.
   'docs/api/openapi.json',           // the generated OpenAPI 3.1 spec served at /docs/openapi.json
   'docs/api-reference.md',           // the markdown API reference
   'docs/modules-contract.md',
@@ -161,12 +169,33 @@ const CONTENT_EXCLUDE = [
   'src/world/',
   'src/rooms/',
   'src/preview-server.js',
+  'server.js',               // repo-root game+platform entry: top-level require('colyseus') (a pruned core dep) → un-runnable in the game-less package; the core boots via src/platform-server.js. Mirrors src/preview-server.js. (task 2134)
   // the art feature's CLI tooling lives under scripts/ (legacy top-level) but belongs
   // to the excluded art module — exclude it with the feature it serves.
   'scripts/art/',
+  'scripts/gds/art-stage.js', // art sandbox-staging CLI: requires modules/art-pipeline's build_tilesheet.py; excluded with the art feature it serves so a core file never requires an excluded module (task 2135)
   'scripts/tile-add.js',
   'scripts/tile-find.js',
   'scripts/tile-recommend.js',
+  // The art pipeline's operational RECIPE — belongs to the excluded art module; exclude it
+  // with the feature it serves (mirrors scripts/art/ above). docs/recipes/ is allowlisted
+  // wholesale, so this deny is what keeps the game-art recipe out of a non-art core. (task 2153)
+  'docs/recipes/pixel-art-pipeline.md',
+  // Host-feature TESTS that statically import an EXCLUDED module's source. tests/ is
+  // allowlisted (the platform/methodology suite is core), but these cover the game/art
+  // HOST modules and import their source directly — so package-core (which selects via
+  // isPublishable) would ship them WITHOUT the module they need → MODULE_NOT_FOUND when a
+  // core CI/consumer runs them, and the R89 cutover would DELETE OTB's own game/art tests
+  // (they cover kept host modules; they cannot live in core). Exclude each with the feature
+  // it serves — mirrors scripts/gds/art-stage.js above. The guard in tests/publish_manifest.mjs
+  // derives this set from disk and fails if a new host-module test is added but not listed. (task 2147)
+  'tests/walkability.mjs',     // → modules/game/world
+  'tests/terrain_picker.mjs',  // → modules/game/public/game/world
+  'tests/snapshot_picker.mjs', // → modules/game/public/game/world
+  'tests/sprite_facing.mjs',   // → modules/game/public/game/player
+  'tests/turn_in_place.mjs',   // → modules/game/public/game/player
+  'tests/day_cycle.mjs',       // → modules/game/public/game/fx
+  'tests/art_key.mjs',         // → modules/art-pipeline
 ];
 
 // (4) INSTANCE IDENTITY + HISTORY — this host's literals, ops config, build history, and
@@ -178,6 +207,11 @@ const INSTANCE_EXCLUDE = [
   'config/devbox-app.json',
   'config/hierarchy.json',
   'CODEOWNERS',              // names the owner (a protected surface, excluded as identity)
+  // instance SEED migrations — this host's scope-truth SQL (planning seeds, world data).
+  // ADR 0105: a consumer's core must not carry them; migrate.sh reads instance seeds from
+  // resolveInstanceRoot() (SEED_INSTANCE), so the consumer repo owns them. Core migrations
+  // (migrations/core_NNN_*.sql + bare legacy migrations/NNN_*.sql) still publish. (task 2140)
+  'migrations/instance/',
   // instance-specific docs + project history
   'docs/project-context.md',
   'docs/lore/',
@@ -192,6 +226,30 @@ const INSTANCE_EXCLUDE = [
   'docs/graphics-stress-test-plan.md',
   'docs/security-baseline.md',
   'docs/routes-permissions.md',
+  // instance-specific OPERATIONAL recipes — this host's staging + load-test artifacts, its
+  // specific control-plane / vanity-door standups, and its one-time monolith-decouple runbook.
+  // docs/recipes/ is allowlisted wholesale for the PORTABLE methodology recipes; these teach
+  // nothing a different instance would use, so they stay in this repo and never ship in the
+  // core (mirrors migrations/instance above). Redaction only de-brands them — this stops the
+  // irrelevant-noise at the source. The module-owned RECIPE redesign is deferred (idea 536). (task 2153)
+  'docs/recipes/staging-data.md',
+  'docs/recipes/parallel-load-test.md',
+  'docs/recipes/parallel-load-results-2026-05-30.md',
+  'docs/recipes/claude-gemini-bongos-doors.md',
+  'docs/recipes/cloudbongos-standup.md',
+  'docs/recipes/cloudbongos-staging-gate.md',
+  'docs/recipes/amazonprimea-decouple-r89.md',
+  'docs/recipes/amazonprimea-decouple-rollback-r89.md',
+  // instance-specific GAME-DESIGN specs — this host's pixel-art / level briefs (the container
+  // buildings, its palette, the world-map scroll). docs/design/ is allowlisted wholesale for the
+  // PORTABLE design docs (modular-architecture/*, the vanilla-hall-ui redesign scope); these four
+  // describe THIS instance's game and genericize to nothing, so they stay in this repo and never
+  // ship in the core. Redaction only de-brands NAMES — the world-narrative prose in them is not a
+  // name and survives redaction, so exclude at the source (mirrors the recipe carve-out above). (task 2155)
+  'docs/design/container-exterior.md',
+  'docs/design/container-exterior-tiles.md',
+  'docs/design/container-interior.md',
+  'docs/design/world-map-scroll.md',
   'blockers/',
   'limitations/',
   'generative-ideas.md',

package/scripts/gds/run-routine.js

@@ -23,9 +23,20 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const TASKS_DIR = path.join(REPO_ROOT, '.claude', 'scheduled-tasks');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config');
+
+// TWO roots (ADR 0108 configurable-root; task 2138). run-routine.js is a CORE script, so it
+// ships alongside src/, scripts/gds/*, scripts/discord/*, and modules/ — all under
+// resolveCoreRoot(), which is where core step scripts + the grader resolve from. The ROUTINES
+// themselves are TOPOLOGY: `bongos init/upgrade` materializes .claude/scheduled-tasks/ INTO the
+// instance (claude-materialize.js), so they're found under resolveInstanceRoot(). Today both
+// roots are the one checkout — BYTE-IDENTICAL to the old `path.resolve(__dirname,'..','..')`;
+// post-split TASKS_DIR points at the instance repo while core scripts resolve inside
+// node_modules/@bongos/core. (Do NOT reintroduce a hardcoded __dirname/../.. — see scripts/gds/CLAUDE.md.)
+const CORE_ROOT = resolveCoreRoot();
+const INSTANCE_ROOT = resolveInstanceRoot();
+const TASKS_DIR = path.join(INSTANCE_ROOT, '.claude', 'scheduled-tasks');
+const DISCORD_POST = path.join(CORE_ROOT, 'scripts', 'discord', 'post.js');
 const VALID_MODES = new Set(['deterministic', 'hybrid', 'judgment']);
 const VALID_SINKS = new Set(['discord', 'gds', 'none']);
 const ALERT_CHANNEL = process.env.OTB_ROUTINE_ALERT_CHANNEL || 'ship_feed';
@@ -104,10 +115,36 @@ function tokenize(cmd) {
   return out;
 }
 
+function isNodeExec(a) {
+  const base = path.basename(String(a || '')).toLowerCase();
+  return a === process.execPath || base === 'node' || base === 'node.exe';
+}
+
+// Pure: resolve a routine step's argv so it runs in BOTH layouts (ADR 0108; task 2138).
+//   • `bongos exec <rel> [args]` (the materialized invocation form) → run <rel> under the CORE
+//     root, exactly like `bongos exec` itself does (bin/bongos.js resolveExecTarget).
+//   • `node <path> [args]` → resolve <path>: a `scripts/...` core path under coreRoot; any other
+//     relative path (notably the `.claude/scheduled-tasks/<name>/<x>.js` companions) under the
+//     instance root. Absolute paths and non-node commands pass through untouched.
+// Commands come from committed SKILL.md (trusted), so this is path resolution, not sandboxing.
+// Today coreRoot === instanceRoot (single checkout) so this is byte-identical to the old run;
+// only after the split do the two roots diverge. Exported + unit-tested.
+function resolveStepArgv(argv, { coreRoot = CORE_ROOT, instanceRoot = INSTANCE_ROOT } = {}) {
+  if (!argv || !argv.length) return argv || [];
+  if (argv[0] === 'bongos' && argv[1] === 'exec' && argv[2]) {
+    return [process.execPath, path.join(coreRoot, argv[2]), ...argv.slice(3)];
+  }
+  if (isNodeExec(argv[0]) && argv[1] && !path.isAbsolute(argv[1])) {
+    const base = argv[1].startsWith('scripts/') ? coreRoot : instanceRoot;
+    return [process.execPath, path.join(base, argv[1]), ...argv.slice(2)];
+  }
+  return argv;
+}
+
 function opsAlert(message) {
   try {
-    execFileSync(process.execPath, [path.join('scripts', 'discord', 'post.js'), '--channel', ALERT_CHANNEL, String(message).slice(0, 1800)],
-      { cwd: REPO_ROOT, stdio: 'ignore' });
+    execFileSync(process.execPath, [DISCORD_POST, '--channel', ALERT_CHANNEL, String(message).slice(0, 1800)],
+      { cwd: INSTANCE_ROOT, stdio: 'ignore' });
   } catch (_) { /* best-effort: the alert must never mask the real failure */ }
 }
 
@@ -116,19 +153,20 @@ function routeOutput(sink, stdout, routineName) {
   if (text) console.log(text);
   if (sink === 'discord' && text) {
     try {
-      execFileSync(process.execPath, [path.join('scripts', 'discord', 'post.js'), '--channel', ALERT_CHANNEL, `[${routineName}] ${text}`.slice(0, 1800)],
-        { cwd: REPO_ROOT, stdio: 'ignore' });
+      execFileSync(process.execPath, [DISCORD_POST, '--channel', ALERT_CHANNEL, `[${routineName}] ${text}`.slice(0, 1800)],
+        { cwd: INSTANCE_ROOT, stdio: 'ignore' });
     } catch (_) { /* best-effort */ }
   }
   // sink 'gds' / 'none': the step's command performed its own GDS side effects.
 }
 
 function runStep(step, routineName, { dryRun }) {
-  const argv = tokenize(step.command);
-  if (!argv.length) return '';
+  const tokens = tokenize(step.command);
+  if (!tokens.length) return '';
   if (dryRun) { console.log(`[dry-run] would run (${step.sink}): ${step.command}`); return ''; }
+  const argv = resolveStepArgv(tokens);
   const out = execFileSync(argv[0], argv.slice(1), {
-    cwd: REPO_ROOT,
+    cwd: INSTANCE_ROOT, // routines run in the instance repo (companions + git-touching steps)
     encoding: 'utf8',
     env: { ...process.env, OTB_COST_CRON_ROUTINE: routineName },
   });
@@ -140,7 +178,7 @@ function runJudgment(routineName, skillBody, { dryRun }) {
   if (dryRun) { console.log(`[dry-run] judgment mode → would spawn claude -p over ${routineName}/SKILL.md`); return; }
   // Status quo: a wrapped session reading the SKILL body. Reuse the shared spawn.
   const grader = require('../../modules/grading/grader');
-  return grader.runSubagent({ prompt: skillBody, opts: { cwd: REPO_ROOT } });
+  return grader.runSubagent({ prompt: skillBody, opts: { cwd: INSTANCE_ROOT } });
 }
 
 async function main() {
@@ -176,7 +214,7 @@ async function main() {
           try { const j = JSON.parse(String(out).trim().split('\n').pop() || '{}'); if (j && j.needs_judgment) payload = j.needs_judgment; } catch (_) {}
           if (payload) {
             const grader = require('../../modules/grading/grader');
-            await grader.runSubagent({ prompt: String(payload), opts: { cwd: REPO_ROOT } });
+            await grader.runSubagent({ prompt: String(payload), opts: { cwd: INSTANCE_ROOT } });
           }
         }
       }
@@ -194,4 +232,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { parseRoutineFrontmatter, tokenize, VALID_MODES, VALID_SINKS };
+module.exports = { parseRoutineFrontmatter, tokenize, resolveStepArgv, isNodeExec, VALID_MODES, VALID_SINKS };

package/scripts/gds/run-unit-tests.js

@@ -65,6 +65,10 @@ const SUPPORT_MODULES = new Set(['helpers']);
 const INTEGRATION = new Set([
   'asset_version', 'auth_flow_slice1', 'backfill_sessions', 'bfg', 'bfg_write',
   'box_connect_e2e', 'box_onboard', 'boxes', 'cf_tunnel', 'cli_token_reissue',
+  // consumer_layout_boot builds the core .tgz, `npm install`s it, and boots a live
+  // platform-server — network + package build + a spawned server, run by its own
+  // .github/workflows/consumer-layout-boot.yml, not this DB-free gate (task 2142).
+  'consumer_layout_boot',
   'discord_autojoin', 'discord_oauth', 'linkify_refs', 'memory_isolation',
   'memory_pull', 'parallel-load', 'session_records', 'setup_smoke',
   'status-probe', 'subdomain_auth',

package/scripts/gds/update-channel.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/update-channel.js — the update-subscription POLICY core (task 2150, ADR 0136).
+//
+// "How does a consumer instance subscribe to regular @bongos/core updates?" The owner-chosen
+// answer (2026-07-09): **patch-only by default, health-gated, auto-rollback, opt-in, autonomy-gated.**
+// This module is the PURE, testable heart of that policy — the semver + channel math + the
+// subscription-manifest loader. It launches nothing and mutates nothing; the scheduled routine
+// (.claude/scheduled-tasks/core-update-subscription/subscribe.js) drives the actual `bongos upgrade`
+// per subscribed instance using what this module resolves.
+//
+// A per-instance UPDATE CHANNEL bounds how far an unattended upgrade may jump:
+//   pinned — never auto-upgrade (manual `bongos upgrade` only).
+//   patch  — take a higher PATCH within the same major.minor (1.17.1 → 1.17.4, never 1.18.0). DEFAULT.
+//   minor  — take a higher MINOR within the same major (1.17.1 → 1.18.0, never 2.0.0).
+// A MAJOR bump is NEVER automatic under any channel — a major is a breaking change that wants a human.
+// Prereleases (1.17.2-rc.1) are never auto-target either — only stable releases.
+//
+// WHY the registry as the source (not vendored tarballs): a subscription needs a LIVE source of
+// truth for "what's the newest published core?" — that's `npm view @bongos/core versions` against the
+// private registry (ADR 0134, task 2090). The vendored path is for a one-off manual bump.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const CORE_PKG = '@bongos/core';
+const VALID_CHANNELS = ['pinned', 'patch', 'minor'];
+const DEFAULT_CHANNEL = 'patch';
+// The subscription manifest an operator edits to opt instances in. Ships EMPTY (instances: []) in the
+// core template — a fresh instance subscribes nothing until the operator lists a target here.
+const SUBSCRIPTIONS_REL = path.join('config', 'update-subscriptions.json');
+
+// ---- semver (stable x.y.z, optional prerelease tag) -------------------------
+// A deliberately small parser — the repo avoids an npm-semver dependency in the CLI path (see
+// upgrade.js versionFromDep). We only need compare + the major/minor/patch fields.
+
+// Parse "1.17.2" / "v1.17.2" / "1.17.2-rc.1" → { major, minor, patch, pre } or null. `pre` is the
+// prerelease tag ('' for a plain stable release), used only to EXCLUDE prereleases from auto-targets.
+function parseSemver(v) {
+  const m = String(v == null ? '' : v).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] || '' };
+}
+
+function isStable(v) {
+  const p = parseSemver(v);
+  return !!p && p.pre === '';
+}
+
+// Compare two version strings by (major, minor, patch). Returns -1 / 0 / 1. A stable release sorts
+// ABOVE its own prereleases (1.17.2 > 1.17.2-rc.1), matching semver precedence — enough for "is this
+// candidate newer than what's installed?" Unparseable inputs sort as -Infinity (never a target).
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+  }
+  // Same x.y.z: a prerelease is LOWER than the stable release. (Two prereleases: not ordered
+  // precisely here — we never auto-target a prerelease, so their relative order is immaterial.)
+  if (pa.pre && !pb.pre) return -1;
+  if (!pa.pre && pb.pre) return 1;
+  return 0;
+}
+
+function normalizeChannel(channel) {
+  const c = String(channel == null ? '' : channel).trim().toLowerCase();
+  return VALID_CHANNELS.includes(c) ? c : DEFAULT_CHANNEL;
+}
+
+// Would `channel` permit an unattended jump from `installed` to `candidate`? True only when candidate
+// is a STABLE release strictly newer than installed AND within the channel's blast radius. Any invalid
+// input, an unknown installed version, a prerelease candidate, or a major bump ⇒ false (fail-closed).
+function channelAllows(installed, candidate, channel) {
+  const ch = normalizeChannel(channel);
+  if (ch === 'pinned') return false;
+  const from = parseSemver(installed);
+  const to = parseSemver(candidate);
+  if (!from || !to) return false;
+  if (to.pre) return false;                       // never auto-target a prerelease
+  if (compareSemver(candidate, installed) <= 0) return false; // must be strictly newer
+  if (to.major !== from.major) return false;      // a major bump is never automatic
+  if (ch === 'patch' && to.minor !== from.minor) return false; // patch stays on the same minor
+  return true;                                    // 'minor' allows any higher minor within the major
+}
+
+// The highest version in `available` that `channel` permits from `installed`, or null if none
+// (nothing newer, pinned, only prereleases/majors ahead, or an unknown installed version). This is
+// the one function the routine asks: "given where this instance is and what it subscribes to, what —
+// if anything — should I upgrade it to right now?"
+function resolveChannelTarget({ installed, channel, available } = {}) {
+  const list = Array.isArray(available) ? available : [];
+  let best = null;
+  for (const v of list) {
+    if (!channelAllows(installed, v, channel)) continue;
+    if (best === null || compareSemver(v, best) > 0) best = v;
+  }
+  return best;
+}
+
+// ---- registry: what versions of the core are published? ---------------------
+
+// List published versions of @bongos/core from the registry via `npm view … versions --json`
+// (ADR 0134 — the private scoped package resolves through the instance's env-fed .npmrc, so run this
+// with cwd inside an instance that has one + NPM_TOKEN in env). Fail-SOFT: any error returns
+// { ok:false } so the routine skips that instance rather than crashing the whole sweep. `run` +
+// `pkg` are injectable for tests.
+function listAvailableVersions({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env } = {}) {
+  let res;
+  try {
+    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8' });
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e), versions: [] };
+  }
+  if (!res || res.status !== 0) {
+    const reason = (res && (res.stderr || res.error && res.error.message)) || `exit ${res && res.status}`;
+    return { ok: false, error: String(reason).trim().split('\n')[0] || 'npm view failed', versions: [] };
+  }
+  return parseNpmViewVersions(res.stdout);
+}
+
+// Parse `npm view … versions --json` stdout. npm prints a JSON ARRAY for a multi-version package, a
+// bare JSON STRING for a single-version one, and nothing for an unpublished name. Normalizes all
+// three to { ok:true, versions:[…] }. Exported + unit-tested (the shape has bitten callers before).
+function parseNpmViewVersions(stdout) {
+  const s = String(stdout == null ? '' : stdout).trim();
+  if (!s) return { ok: true, versions: [] };
+  let parsed;
+  try { parsed = JSON.parse(s); } catch (e) { return { ok: false, error: `unparseable npm output: ${e.message}`, versions: [] }; }
+  if (Array.isArray(parsed)) return { ok: true, versions: parsed.map(String) };
+  if (typeof parsed === 'string') return { ok: true, versions: [parsed] };
+  return { ok: false, error: 'unexpected npm view shape', versions: [] };
+}
+
+// ---- subscription manifest --------------------------------------------------
+
+// Read + normalize config/update-subscriptions.json — the operator-edited opt-in list of instances
+// this control plane keeps up to date. Never throws: a missing/malformed file ⇒ an empty roster
+// (subscribe nothing), because an unreadable manifest must not upgrade anything. Each entry is
+// normalized to { slug, dir, service, healthUrl, channel } with the channel validated + defaulted.
+function loadSubscriptions({ instanceDir = process.cwd(), fsImpl = fs, file = SUBSCRIPTIONS_REL } = {}) {
+  const abs = path.isAbsolute(file) ? file : path.join(instanceDir, file);
+  let raw;
+  try { raw = fsImpl.readFileSync(abs, 'utf8'); } catch (_) { return { defaultChannel: DEFAULT_CHANNEL, instances: [], source: abs, present: false }; }
+  let json;
+  try { json = JSON.parse(raw); } catch (e) { return { defaultChannel: DEFAULT_CHANNEL, instances: [], source: abs, present: true, error: `malformed JSON: ${e.message}` }; }
+  const defaultChannel = normalizeChannel(json.defaultChannel);
+  const rows = Array.isArray(json.instances) ? json.instances : [];
+  const instances = rows
+    .filter((r) => r && typeof r === 'object' && r.dir) // an entry without a dir can't be upgraded — drop it
+    .map((r) => ({
+      slug: String(r.slug || r.dir),
+      dir: String(r.dir),
+      service: r.service ? String(r.service) : null,
+      healthUrl: r.healthUrl ? String(r.healthUrl) : null,
+      channel: normalizeChannel(r.channel == null ? defaultChannel : r.channel),
+      // Per-instance env merged into the `bongos upgrade` child (e.g. PGDATABASE so the migrate step
+      // hits THIS instance's DB, not the control plane's — see the live-op learnings for demo). Only
+      // string values are kept; anything else is ignored.
+      env: (r.env && typeof r.env === 'object' && !Array.isArray(r.env))
+        ? Object.fromEntries(Object.entries(r.env).filter(([, v]) => typeof v === 'string'))
+        : {},
+    }));
+  return { defaultChannel, instances, source: abs, present: true };
+}
+
+module.exports = {
+  CORE_PKG,
+  VALID_CHANNELS,
+  DEFAULT_CHANNEL,
+  SUBSCRIPTIONS_REL,
+  parseSemver,
+  isStable,
+  compareSemver,
+  normalizeChannel,
+  channelAllows,
+  resolveChannelTarget,
+  listAvailableVersions,
+  parseNpmViewVersions,
+  loadSubscriptions,
+};

package/scripts/gds/upgrade.js

@@ -100,6 +100,21 @@ function writeRegistryPin(instanceDir, version, fsImpl = fs) {
   return prev;
 }
 
+// Restore the consumer package.json's @bongos/core pin to an EXACT previous dep string,
+// VERBATIM — whether that was a `file:` tarball path (vendored) or a bare registry semver.
+// The inverse of writePin/writeRegistryPin used by the auto-rollback path (task 2149), which
+// snapshots the returned prev-dep before the bump. Returns the dep string it overwrote.
+function restorePin(instanceDir, depString, fsImpl = fs) {
+  const pkgPath = path.join(instanceDir, 'package.json');
+  const pkg = readJson(pkgPath, fsImpl);
+  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
+  pkg.dependencies = pkg.dependencies || {};
+  const prev = pkg.dependencies[CORE_PKG];
+  pkg.dependencies[CORE_PKG] = depString;
+  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  return prev;
+}
+
 // ---- steps (each injectable for tests) --------------------------------------
 
 function gitTreeClean(instanceDir, run = spawnSync) {
@@ -154,10 +169,11 @@ function runMigrate(instanceDir, run = spawnSync) {
 
 // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
 // client) from the NEW core's routes — the claude-materialize sibling (task 2051).
-// WHY: the routes + generators ship WITH core, but the generated spec/docs/client are
-// EXCLUDED from the package (per-instance artifacts), so a bump changes the served API
-// while the instance's committed spec/client lag until the next ship's fitness gate.
-// This closes that gap on upgrade. We SPAWN the new core's generators (a fresh child
+// WHY: the routes + generators ship WITH core, and the generated spec/docs/client also
+// ship as CORE STARTERS (task 2078 — a fresh hall/docs must render before first regen),
+// but they are per-instance GENERATED, so a bump changes the served API while the
+// instance's committed spec/client lag until regenerated (the classification settled in
+// task 2141; init does the same at standup). We SPAWN the new core's generators (a fresh child
 // captures its output root from the env below) with <FALLBACK_PREFIX>_INSTANCE_ROOT set
 // so resolveDocsRoot() writes INTO the instance repo, not node_modules. docs first — the
 // client reads the spec it produces. Best-effort: a hiccup warns, never fails the bump
@@ -279,6 +295,64 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
+// error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
+// snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
+// in the ledger. The DB is deliberately NOT rolled back: core migrations are additive +
+// forward-safe (the core migration rule), so any already-applied migration is left in place —
+// only the code PIN moves back. Best-effort + fail-soft: every sub-step logs but never throws,
+// so a rollback attempt can't itself crash the upgrader on top of the original failure.
+async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts }, reason, deps = {}) {
+  const log = deps.log || console.log;
+  const err = deps.err || console.error;
+  const run = deps.run || spawnSync;
+  const fsImpl = deps.fs || fs;
+  const restore = deps.restorePin || restorePin;
+
+  err(`  ↩ rolling back: ${reason} — reverting ${CORE_PKG} ${toVersion} → ${snapshot.prevVersion || snapshot.prevPin}`);
+  const result = { rolledBack: true, reason, restoredPin: snapshot.prevPin, restoredVersion: snapshot.prevVersion };
+
+  // 1. revert the pin to the exact previous dep string.
+  try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
+  catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
+
+  // 2. reinstall the previous core.
+  const inst = npmInstall(instanceDir, run);
+  result.reinstallOk = !!inst.ok;
+  if (inst.ok) log('  ✓ reinstalled previous core');
+  else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
+
+  // 3. restart back onto the previous core.
+  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
+  if (rs.skipped) log('  • restart: no --service/--restart-cmd — restart the instance service manually to load the reverted core.');
+  else if (!rs.ok) err(`  ! restart after rollback failed (exit ${rs.code}) — restart the service manually.`);
+  else log(`  ✓ restarted ${opts.service || 'service'} on the previous core`);
+  result.restartOk = rs.ok;
+
+  // 4. re-verify: installed == previous, optional health recovery.
+  const installedNow = readInstalledCoreVersion(instanceDir, fsImpl);
+  result.installedAfter = installedNow;
+  log(`  ${installedNow === snapshot.prevVersion ? '✓' : '!'} installed core after rollback: ${installedNow || '(unknown)'}`);
+  if (opts.healthUrl) {
+    const h = await pollHealth(opts.healthUrl, deps);
+    result.healthOk = h.ok;
+    if (h.ok) log(`  ✓ health recovered ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (after ${h.attempts} tries)` : ''}`);
+    else err(`  ! health STILL failing after rollback (${h.error || 'status ' + h.status}) — manual intervention needed`);
+  }
+
+  // 5. record the reversal in the ledger via the always-present `note` column (no schema
+  //    dependency — so it records even when a FAILED migrate means a newer column wouldn't exist).
+  const note = `rolled_back: ${reason} (attempted ${fromVersion || '(none)'} → ${toVersion}, restored ${snapshot.prevVersion || 'previous'})`;
+  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note }, deps);
+  if (ledger.ok) log('  ✓ recorded rollback in core_upgrades ledger');
+  else if (ledger.skipped) log(`  • rollback ledger skipped (${ledger.reason})`);
+  else err(`  ! rollback ledger insert failed (${ledger.reason}) — record it manually`);
+  result.ledger = ledger.ok;
+
+  err(`  ↩ rollback complete — instance restored to core ${snapshot.prevVersion || snapshot.prevPin}.`);
+  return result;
+}
+
 // ---- orchestration ----------------------------------------------------------
 
 async function runUpgrade(opts, deps = {}) {
@@ -291,9 +365,16 @@ async function runUpgrade(opts, deps = {}) {
   const instanceDir = path.resolve(opts.instance || process.cwd());
   const targetVersion = opts.to;
   const dryRun = !!opts.dryRun;
+  // Auto-rollback is ON by default (task 2149); `--no-rollback-on-failure` opts out (e.g. an
+  // interactive run that wants to inspect a broken state). Programmatic callers pass false.
+  const rollbackOnFailure = opts.rollbackOnFailure !== false;
+  // Pre-upgrade snapshot { prevPin, prevVersion } — captured the instant the pin is moved, so a
+  // failure AFTER that point (install / migrate / health) can revert. null until then = nothing to undo.
+  let snapshot = null;
   if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
 
   const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || readPinnedCoreVersion(instanceDir, fsImpl);
+  const doRollback = (reason) => rollback({ instanceDir, snapshot, fromVersion, toVersion: targetVersion, opts }, reason, deps);
   log(`bongos upgrade — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
   log(`  instance: ${instanceDir}${dryRun ? '   [DRY RUN — no changes]' : ''}`);
   if (fromVersion === targetVersion && !opts.force) {
@@ -317,7 +398,7 @@ async function runUpgrade(opts, deps = {}) {
     if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
     if (!hasNpmToken()) log('  ! no NPM_TOKEN in env — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
     const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
-    if (!dryRun) writeNpmrc(instanceDir, { fsImpl, overwrite: false, log });
+    if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
   } else {
     let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
@@ -330,6 +411,7 @@ async function runUpgrade(opts, deps = {}) {
       return { ok: false, error: `no core tarball at ${vendorRel} — pass --from <path-to-.tgz> to vendor it (or --registry to pull from the npm registry)` };
     }
     const prevPin = dryRun ? null : writePin(instanceDir, vendorRel, fsImpl);
+    if (!dryRun) snapshot = { prevPin, prevVersion: fromVersion };
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
   }
 
@@ -337,13 +419,27 @@ async function runUpgrade(opts, deps = {}) {
 
   // 3. npm install.
   const inst = npmInstall(instanceDir, run);
-  if (!inst.ok) return { ok: false, error: `npm install failed (${inst.reason || 'exit ' + inst.code})`, fromVersion };
+  if (!inst.ok) {
+    const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
+    if (rollbackOnFailure && snapshot) {
+      const rb = await doRollback('npm install failed');
+      return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+    }
+    return { ok: false, error, fromVersion };
+  }
   log('  ✓ npm install');
 
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
     const mig = runMigrate(instanceDir, run);
-    if (!mig.ok) return { ok: false, error: `migrate failed (${mig.reason || 'exit ' + mig.code})`, fromVersion };
+    if (!mig.ok) {
+      const error = `migrate failed (${mig.reason || 'exit ' + mig.code})`;
+      if (rollbackOnFailure && snapshot) {
+        const rb = await doRollback('migrate failed');
+        return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+      }
+      return { ok: false, error, fromVersion };
+    }
     log('  ✓ migrate');
   } else log('  • migrate skipped (--skip-migrate)');
 
@@ -383,6 +479,14 @@ async function runUpgrade(opts, deps = {}) {
     else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
   }
 
+  // A failed post-restart health check means the new core is serving broken — auto-revert (task
+  // 2149) instead of recording an "upgraded" row + leaving the instance down. The rollback writes
+  // its OWN rolled_back ledger row, so skip the normal insert below.
+  if (healthOk === false && rollbackOnFailure && snapshot) {
+    const rb = await doRollback('health check failed after restart');
+    return { ok: false, error: `health check failed after restart — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk: false, rolledBack: true, rollback: rb };
+  }
+
   const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note }, deps);
   if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
   else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
@@ -410,6 +514,7 @@ function parseArgs(argv) {
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+    rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
   };
 }
 
@@ -432,10 +537,12 @@ async function main(argv = process.argv.slice(2)) {
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
+      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/migrate/health check (default: auto-rollback ON)',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
       'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
+      'On a failure after the pin moves (install/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -450,8 +557,8 @@ async function main(argv = process.argv.slice(2)) {
 }
 
 module.exports = {
-  runUpgrade, parseArgs, main,
-  versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin,
+  runUpgrade, parseArgs, main, rollback,
+  versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
   CORE_PKG, ARTIFACT,
 };