@bongos/core 1.17.0 → 1.17.2

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/seed-adopt-tasks.js

@@ -19,7 +19,7 @@ const RUNBOOK_TASK = 1981; // goal-35 canonical runbook; A05 depends on it (exte
 const TASKS = [
   { ref: 'A01', kind: 'feature', priority: 4, est: 180, crit: [CRIT], deps: [], extDeps: [],
     title: 'bongos init --adopt: mode skeleton + additive config layering (no clobber)',
-    description: 'Add an `--adopt` mode to `scripts/gds/init.js` (ADR 0121 §Decision 1-2). Instead of the greenfield "stand up a NEW instance" path (which refuses where config/branding.json exists and whose --force OVERWRITES), --adopt LAYERS onto the existing tree: add the pinned @cloudbongos/core dependency + the lean config/ overrides + .claude/ ADDITIVELY. For any pre-existing file (package.json, an existing .claude/, a CI workflow) it MERGES or LEAVES-AND-REPORTS — it never overwrites, and it must NOT reuse the --force code path. Writes only the lean branding.json overrides (rest resolves from *.neutral.json). Serves criterion adopt-existing-repo. deps: none (the ADR-0108 configurable-root substrate is shipped).' },
+    description: 'Add an `--adopt` mode to `scripts/gds/init.js` (ADR 0121 §Decision 1-2). Instead of the greenfield "stand up a NEW instance" path (which refuses where config/branding.json exists and whose --force OVERWRITES), --adopt LAYERS onto the existing tree: add the pinned @bongos/core dependency + the lean config/ overrides + .claude/ ADDITIVELY. For any pre-existing file (package.json, an existing .claude/, a CI workflow) it MERGES or LEAVES-AND-REPORTS — it never overwrites, and it must NOT reuse the --force code path. Writes only the lean branding.json overrides (rest resolves from *.neutral.json). Serves criterion adopt-existing-repo. deps: none (the ADR-0108 configurable-root substrate is shipped).' },
   { ref: 'A02', kind: 'feature', priority: 4, est: 150, crit: [CRIT], deps: [], extDeps: [],
     title: 'bongos init --adopt: detect the existing stack + layout',
     description: 'Before writing anything, --adopt inspects the existing tree — language/runtime, package manager, test + CI setup, directory layout — so the enabled modules, the generated repo-map, and the core<->host fitness boundary (ADR 0062 §1) fit what is already there instead of assuming the reference layout (ADR 0121 §Decision 4). Output: a detected-stack summary consumed by A03 (real-state capture) and A04 (pre-flight). Serves criterion adopt-existing-repo. deps: none.' },

package/scripts/gds/status.js

@@ -19,7 +19,7 @@
 //
 // Exit codes: 0 ok · 1 network/api error · 2 bad invocation · 3 not found.
 
-const { API_BASE, cliClient } = require('./cli-lib');
+const { API_BASE, cliClient, assertInstanceMatch } = require('./cli-lib');
 
 // The active internal version; override with GDS_STATUS_DEFAULT_VERSION (or pass
 // --version). Bumped GDS-V4 → BONGOS-V1 (task 1709, ADR 0103): GDS-V4 was
@@ -319,6 +319,11 @@ async function main() {
     console.log('Usage: node scripts/gds/status.js [--version ID] [Cn] [--json]');
     process.exit(0);
   }
+  // Fail closed if this repo's configured instance != the signed-in session's (task
+  // 2124 / demo-audit C2): fetchProgress uses a raw fetch(API_BASE/…) that bypasses the
+  // apiCall/cliClient guard, so without this `bongos status` would silently print another
+  // instance's progress. Skip only in --hook mode (the automated card path stays fail-open).
+  if (!opts.hook) await assertInstanceMatch();
   const data = await fetchProgress(opts.version);
 
   // Resolve the requested criterion (if any) once — every output mode needs it.

package/scripts/gds/task.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// scripts/gds/task.js — `bongos task` : create + show a Bongos task from the terminal.
+//
+// task 2123 (demo-audit fix C1). The bongos CLI had start/claim/ship/status/… but no
+// way to CREATE a task — so seeding the first task (a new owner's opening move) meant
+// hand-driving POST /api/bongos/tasks through `bongos exec scripts/gds/api.js`. This is
+// the first-class front door.
+//
+// Usage:
+//   bongos task new --title "…" --description "…" [--kind feature] [--discipline engineer]
+//                   [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]
+//                   [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]
+//   bongos task show <id> [--json]
+//
+// Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
+// CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
+
+const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
+
+// Valid enums (mirrors the server's task-classifier vocab; a friendly client-side check
+// so an obvious typo fails before the round-trip — the server stays authoritative).
+const VALID_KINDS = ['feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture', 'cleanup', 'decision', 'blocker-resolution', 'verify'];
+const VALID_DISCIPLINES = ['engineer', 'artist', 'ideator', 'ui'];
+
+function csv(v) {
+  return String(v || '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+// PURE argv → { body, criteria, errors } — exported for the unit test (no network).
+// `args` is the argv slice AFTER the `new` subcommand.
+function buildTaskBody(args) {
+  const errors = [];
+  const title = arg('--title', args);
+  const description = arg('--description', args);
+  if (!title) errors.push('--title is required');
+  if (!description) errors.push('--description is required');
+
+  const kind = arg('--kind', args) || 'feature';
+  if (!VALID_KINDS.includes(kind)) errors.push(`--kind must be one of: ${VALID_KINDS.join(', ')}`);
+  const discipline = arg('--discipline', args) || 'engineer';
+  if (!VALID_DISCIPLINES.includes(discipline)) errors.push(`--discipline must be one of: ${VALID_DISCIPLINES.join(', ')}`);
+
+  const num = (flag) => { const v = arg(flag, args); return v == null ? undefined : Number(v); };
+  const priority = num('--priority');
+  if (priority !== undefined && (!Number.isInteger(priority) || priority < 1 || priority > 5)) {
+    errors.push('--priority must be an integer 1–5');
+  }
+  const goalRaw = arg('--goal', args);
+  const goalId = goalRaw == null ? undefined : Number(goalRaw);
+  if (goalRaw != null && (!Number.isInteger(goalId) || goalId <= 0)) errors.push('--goal must be a positive integer task-goal id');
+
+  const body = {
+    title,
+    description,
+    kind,
+    discipline,
+    status: hasFlag('--ready', args) ? 'ready' : 'backlog',
+    source: 'bongos-task-cli',
+  };
+  const version = arg('--version', args);
+  if (version) body.version_id = version;
+  if (goalId !== undefined) body.goal_id = goalId;
+  if (priority !== undefined) body.priority = priority;
+  const est = num('--est-minutes'); if (est !== undefined) body.est_minutes = est;
+  const md = num('--manual-degree'); if (md !== undefined) body.manual_degree = md;
+  const credits = num('--credits'); if (credits !== undefined) body.credits_reward = credits;
+  const touches = csv(arg('--touches', args)); if (touches.length) body.touches = touches;
+  const criteria = csv(arg('--criteria', args));
+  if (criteria.length) body.criterion_ids = criteria;
+
+  return { body, criteria, errors };
+}
+
+function usage() {
+  console.error('usage:');
+  console.error('  bongos task new --title "…" --description "…" [--kind feature] [--discipline engineer]');
+  console.error('                  [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]');
+  console.error('                  [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]');
+  console.error('  bongos task show <id> [--json]');
+  console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
+  console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
+}
+
+function hallLink(base, id) {
+  try { return `${new URL(base).origin}/builders#/task/${id}`; } catch { return `task #${id}`; }
+}
+
+// The version_id a task defaults to when --version is omitted: the most-recent
+// BUILDING version (the capture.js precedent, so idea-capture and task-create agree).
+// Returns null when none is building — the caller then requires an explicit --version.
+async function resolveDefaultVersion(api) {
+  const r = await api.versions.getVersions();
+  if (!r.ok) return null;
+  const building = (r.data?.versions ?? []).filter((v) => v.status === 'building');
+  if (building.length === 0) return null;
+  building.sort((a, b) => {
+    const ta = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const tb = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return tb - ta;
+  });
+  return building[0].id;
+}
+
+async function cmdNew(args) {
+  const { body, errors } = buildTaskBody(args);
+  if (errors.length) { console.error('task new: ' + errors.join('; ') + '\n'); usage(); process.exit(2); }
+  const api = await cliClient();
+  // version_id is required by the API; default to the active (building) version so a
+  // new owner never has to know the id, but keep --version as the explicit override.
+  if (!body.version_id) {
+    body.version_id = await resolveDefaultVersion(api);
+    if (!body.version_id) {
+      console.error('task new: could not resolve an active version — pass --version <id> (see `bongos status`).');
+      process.exit(2);
+    }
+  }
+  const r = await api.tasks.postTasks({ body });
+  if (r.status === 403) {
+    console.error('Creating a task is Archon-gated (creating work shapes scope). Your rank is lower, so the server declined.');
+    console.error('To propose it instead, capture an idea for triage:');
+    console.error('  bongos exec scripts/gds/capture.js "<your idea>"');
+    process.exit(1);
+  }
+  if (r.status !== 201 || !r.data?.task) {
+    console.error(`task new failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  const task = r.data.task;
+  if (hasFlag('--json', args)) { console.log(JSON.stringify(task, null, 2)); return; }
+  const { API_BASE } = require('./cli-lib');
+  console.log(`✓ Created task #${task.id} [${task.status}] — ${task.title}`);
+  console.log(`  kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}`);
+  console.log(`  ${hallLink(API_BASE, task.id)}`);
+  if (task.status !== 'ready') console.log(`  (status '${task.status}' — pass --ready to make it claimable now, deps permitting)`);
+  console.log(`  next: bongos claim ${task.id}`);
+}
+
+async function cmdShow(args) {
+  const id = Number(args[0]);
+  if (!Number.isInteger(id) || id <= 0) { console.error('usage: bongos task show <id>'); process.exit(2); }
+  const api = await cliClient();
+  const r = await api.tasks.getTasksId({ id });
+  if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+  if (r.status !== 200 || !r.data?.task) { console.error(`task show failed (${r.status}):`, r.data); process.exit(1); }
+  const task = r.data.task;
+  if (hasFlag('--json', args)) { console.log(JSON.stringify(task, null, 2)); return; }
+  console.log(`#${task.id} [${task.status}] — ${task.title}`);
+  console.log(`kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}${task.version_id ? ` · ${task.version_id}` : ''}`);
+  if (task.description) console.log(`\n${task.description}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const sub = args[0];
+  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') { usage(); process.exit(sub ? 0 : 2); }
+  await requireSession();
+  if (sub === 'new') return cmdNew(args.slice(1));
+  if (sub === 'show') return cmdShow(args.slice(1));
+  console.error(`task: unknown subcommand "${sub}"\n`); usage(); process.exit(2);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error('fatal:', err); process.exit(1); });
+}
+
+module.exports = { buildTaskBody, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };

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,
+};