@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/update-channel.js

@@ -1,512 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/update-channel.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/update-channel.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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.
-//
-// A second, independent axis says WHICH published versions an instance may take at all (task 1004297,
-// ADR 0360) — its FOLLOW:
-//   released   — only versions at or below the one the registry labels `latest`, i.e. what the owner
-//                has released to other projects. DEFAULT, for every project.
-//   candidates — every published version, the moment it is published. The platform's own hall, and
-//                only it: Bongos runs each version before anyone else is offered it.
-// The channel bounds how FAR a jump may go; the follow bounds which versions exist to jump to. Once
-// merges publish as candidates (task 1004298, ADR 0361), `latest` moves only when the owner presses
-// Release, so the two follows part: the platform hall takes each candidate, everyone else the release.
-//
-// 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';
-const VALID_FOLLOWS = ['released', 'candidates'];
-// Unknown or absent reads as `released`: the follow that takes FEWER versions is the safe default,
-// the way an unknown channel reads as `patch` rather than `minor`.
-const DEFAULT_FOLLOW = 'released';
-const NPM_VIEW_TIMEOUT_MS = 30000;
-// 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');
-
-// Why a roster came back the way it did. The routine reports this EVERY run: an upgrader whose only
-// job is keeping instances current must never be indistinguishable from one that has stopped. Before
-// task 1003158 an absent manifest, a malformed manifest and a deliberately empty roster all produced
-// the same silent `instances: []`, which is exactly how cloudbongos.com sat 36 releases behind for
-// days with nothing complaining (the same failure SHAPE as blocker 1000097 / task 1002521).
-const ROSTER_OK = 'ok';                       // at least one usable entry
-const ROSTER_ABSENT = 'manifest-absent';      // no file at all
-const ROSTER_MALFORMED = 'manifest-malformed';// file present, JSON unparseable
-const ROSTER_EMPTY = 'roster-empty';          // file parsed, nothing subscribable in it
-const ROSTER_REASONS = [ROSTER_OK, ROSTER_ABSENT, ROSTER_MALFORMED, ROSTER_EMPTY];
-
-// How many releases a subscribed instance may fall behind before "the upgrader stopped" is the only
-// remaining explanation. A successful sweep takes the HIGHEST permitted version in one jump, so a
-// healthy roster returns to 0 behind after every run — a backlog that keeps growing means no run is
-// landing. 5 leaves room for a busy publish-on-merge day between two daily sweeps without crying wolf.
-const DEFAULT_STALENESS_THRESHOLD = 5;
-
-// ---- 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.
-// `+build` metadata parses and is dropped: semver gives it no precedence, and npm installs the
-// version underneath it, so a caller asking "is this older?" must see through it (task 1004009).
-function parseSemver(v) {
-  const m = String(v == null ? '' : v).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[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.
-  if (pa.pre && !pb.pre) return -1;
-  if (!pa.pre && pb.pre) return 1;
-  return comparePrerelease(pa.pre, pb.pre);
-}
-
-// Semver §11.4 for two prerelease tags: dot-separated identifiers left to right, numeric ones as
-// numbers and below text ones, and the longer list wins a tie. Auto-targeting never needed this
-// (a prerelease is never a target); `bongos upgrade`'s downgrade guard does — rc.2 → rc.1 is one.
-function comparePrerelease(a, b) {
-  const ia = a ? a.split('.') : [];
-  const ib = b ? b.split('.') : [];
-  for (let i = 0; i < Math.min(ia.length, ib.length); i++) {
-    if (ia[i] === ib[i]) continue;
-    const na = /^\d+$/.test(ia[i]);
-    const nb = /^\d+$/.test(ib[i]);
-    if (na && nb) return +ia[i] < +ib[i] ? -1 : 1;
-    if (na !== nb) return na ? -1 : 1;
-    return ia[i] < ib[i] ? -1 : 1;
-  }
-  return Math.sign(ia.length - ib.length);
-}
-
-function normalizeChannel(channel) {
-  const c = String(channel == null ? '' : channel).trim().toLowerCase();
-  return VALID_CHANNELS.includes(c) ? c : DEFAULT_CHANNEL;
-}
-
-function normalizeFollow(follow) {
-  const f = String(follow == null ? '' : follow).trim().toLowerCase();
-  return VALID_FOLLOWS.includes(f) ? f : DEFAULT_FOLLOW;
-}
-
-// The published versions an instance's FOLLOW admits (task 1004297). PURE. `candidates` admits every
-// one; `released` admits those at or below `released` — the version the registry labels `latest` —
-// and NOTHING when that label is unknown: an instance that follows releases must never take a version
-// because nobody could say whether it was released. Feed the result to resolveChannelTarget.
-function versionsForFollow({ follow, available, released } = {}) {
-  const list = Array.isArray(available) ? available.filter((v) => typeof v === 'string') : [];
-  if (normalizeFollow(follow) === 'candidates') return list;
-  if (!parseSemver(released)) return [];
-  return list.filter((v) => compareSemver(v, released) <= 0);
-}
-
-// The follow a provisioned project takes, from its hosting shape (task 1004298, ADR 0361). The
-// control-plane row IS the platform's own hall, the one project that runs every candidate; every other
-// shape follows releases. Derived, not stored: there is exactly one platform hall, and a column an
-// operator could set on a tenant would be one more way to hand a project an unreleased version.
-function followForShape(hostingShape) {
-  return hostingShape === 'control-plane' ? 'candidates' : DEFAULT_FOLLOW;
-}
-
-// 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? ---------------------
-
-// npmSpawnOpts — what a spawn of `npm` needs on this platform (task 1004631). On Windows `npm` is
-// `npm.cmd`, and Node refuses to spawn a .cmd without a shell (CVE-2024-27980), so a bare
-// spawnSync('npm') fails with ENOENT there. That failure made `bongos upgrade` roll back on every
-// Windows laptop before it wrote the project's .claude/ files — so the project had no permission
-// rules, and Claude Code's safety check refused `npx bongos ship`. A shell is safe here because
-// every argument passed to npm by these callers is a fixed word or a package@version string.
-function npmSpawnOpts(platform = process.platform) {
-  return platform === 'win32' ? { shell: true } : {};
-}
-
-// List published versions of @bongos/core from the registry via `npm view … versions --json`.
-// The package is public (task 1003872), so this needs no credential and no instance-local
-// `.npmrc` — any cwd resolves it. 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. The timeout is a DEFAULT, not an opt-in: a hung registry read
-// would otherwise stall a whole sweep, or an upgrade refusal that only wanted to name a version.
-function listAvailableVersions({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
-  let res;
-  try {
-    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs, ...npmSpawnOpts() });
-  } 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: [] };
-}
-
-// Which version is RELEASED — the one the registry labels `latest` (task 1004297) — via
-// `npm view … dist-tags --json`. A separate read from listAvailableVersions on purpose: that one's
-// output shape is relied on by the deploy door and `bongos upgrade`, and it stays exactly as it is.
-// Fail-SOFT like its sibling: { ok:false, error } on any failure, never a throw. `released` is null
-// unless the label names a stable version.
-function readReleaseTags({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
-  let res;
-  try {
-    res = run('npm', ['view', pkg, 'dist-tags', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs, ...npmSpawnOpts() });
-  } catch (e) {
-    return { ok: false, error: e && e.message ? e.message : String(e), released: null, tags: {} };
-  }
-  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', released: null, tags: {} };
-  }
-  let tags;
-  try { tags = JSON.parse(String(res.stdout || '').trim() || '{}'); } catch (e) {
-    return { ok: false, error: `unparseable npm output: ${e.message}`, released: null, tags: {} };
-  }
-  if (!tags || typeof tags !== 'object' || Array.isArray(tags)) return { ok: false, error: 'unexpected npm view shape', released: null, tags: {} };
-  const latest = typeof tags.latest === 'string' ? tags.latest : null;
-  const released = latest && isStable(latest) ? latest : null;
-  return released
-    ? { ok: true, released, tags }
-    : { ok: false, error: 'the registry names no released (latest) version', released: null, tags };
-}
-
-// ---- 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.
-//
-// Still fails CLOSED, no longer fails QUIET (task 1003158): every return carries a `reason` from
-// ROSTER_REASONS and a `dropped` count of entries that were unusable, so a caller can say WHY it is
-// about to do nothing. Pair it with describeRoster() for the line to print.
-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, dropped: 0, reason: ROSTER_ABSENT }; }
-  let json;
-  try { json = JSON.parse(raw); } catch (e) { return { defaultChannel: DEFAULT_CHANNEL, instances: [], source: abs, present: true, dropped: 0, error: `malformed JSON: ${e.message}`, reason: ROSTER_MALFORMED }; }
-  const defaultChannel = normalizeChannel(json.defaultChannel);
-  const defaultFollow = normalizeFollow(json.defaultFollow);
-  const rows = Array.isArray(json.instances) ? json.instances : [];
-  // An entry without a dir can't be upgraded — drop it, but COUNT the drops. Silently discarding an
-  // operator's malformed row is how an instance believes it is enrolled while nothing ever touches it.
-  const usable = rows.filter((r) => r && typeof r === 'object' && r.dir);
-  const dropped = rows.length - usable.length;
-  const instances = usable
-    .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),
-      // Which versions this instance takes at all (task 1004297): `released` unless the operator
-      // says `candidates` — which only the platform's own hall should.
-      follow: normalizeFollow(r.follow == null ? defaultFollow : r.follow),
-      // Deploy topology (task 1003219). Optional, and only meaningful together: with
-      // versionUrl + deployTimer present the sweep can hand the bump to go-live.js and
-      // inherit its backup, pull-deploy-timer guard and INDEPENDENT box-side version
-      // read-back. Absent, the sweep falls back to calling `bongos upgrade` directly.
-      // Carried through here because a normalizer that silently drops a field makes an
-      // entry look enrolled while the capability it names never engages.
-      versionUrl: r.versionUrl ? String(r.versionUrl) : null,
-      deployTimer: r.deployTimer ? String(r.deployTimer) : null,
-      deployService: r.deployService ? String(r.deployService) : null,
-      backupDb: r.backupDb ? String(r.backupDb) : null,
-      backupDir: r.backupDir ? String(r.backupDir) : null,
-      registryPackage: r.registryPackage ? String(r.registryPackage) : null,
-      // 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, defaultFollow, instances, source: abs, present: true, dropped,
-    reason: instances.length ? ROSTER_OK : ROSTER_EMPTY,
-  };
-}
-
-// ---- the per-project rule set on /deploy (task 1004468, ADR 0357) -----------
-// The owner sets each project's update rule on /deploy, which writes
-// provisioning_instances.update_channel (migration provisioning_029, task 1004445). That column
-// is the rule; the roster's `channel` is only the fallback for an entry no project row matches,
-// or for a sweep that cannot reach the database. Before this, the button followed the column and
-// the sweep followed the roster, so a project set to `minor` on /deploy was still swept as `patch`.
-//
-// Matched by slug — the one stable key the table has (it records no directory). Read over psql,
-// which is how upgrade.js recordLedger reaches a PGDATABASE (a bare name over the unix socket +
-// peer auth, the self-host shape). recordLedger uses the pg driver for DATABASE_URL; this passes
-// the URL to `psql -d` instead, because the sweep is synchronous and pg is not. With no psql the
-// sweep falls back to the roster and says so.
-//
-// A failure's reason is a fixed class, never psql's own text: stderr can name a DB user or host,
-// and the reason is printed into the sweep's log.
-//
-// WHICH DATABASE (task 1004307). UPDATE_CHANNEL_DB names it first. That is the one a control-plane
-// unit should set, NOT PGDATABASE: the sweep hands its own env to every upgrade it spawns
-// ({ ...process.env, ...inst.env }), so a unit-level PGDATABASE would reach any tenant whose roster
-// entry names no database of its own, and that tenant's migrate would run against the control
-// plane's database. UPDATE_CHANNEL_DB means nothing to the upgrade, so it cannot leak that way.
-// It takes a bare db name or a connection string, as psql -d does.
-const CHANNEL_DB_ENV = 'UPDATE_CHANNEL_DB';
-const CHANNEL_SOURCE_DEPLOY = 'deploy';
-const CHANNEL_SOURCE_ROSTER = 'roster';
-const DB_CHANNELS_SQL = 'SELECT slug, update_channel FROM provisioning_instances';
-const DB_CHANNELS_TIMEOUT_MS = 15000;
-
-// PURE. psql's stderr reduced to a class that is safe to log.
-function psqlFailureClass(stderr) {
-  const s = String(stderr || '');
-  if (/relation .*provisioning_instances.* does not exist/i.test(s)) return 'no provisioning_instances table (provisioning module off?)';
-  if (/column .*update_channel.* does not exist/i.test(s)) return 'no update_channel column (migration provisioning_029 not applied)';
-  if (/authentication failed|role .* does not exist|permission denied/i.test(s)) return 'the sweep\'s database login was refused';
-  if (/could not connect|connection refused|no such file or directory|could not translate host/i.test(s)) return 'database unreachable';
-  if (/database .* does not exist/i.test(s)) return 'the named database does not exist';
-  return 'query failed';
-}
-
-// The line a sweep prints for one entry's channel. PURE.
-function channelLine(inst) {
-  return `  • ${inst.slug}: channel ${inst.channel}, ${inst.channelNote}`;
-}
-
-// Read every project's update rule. Never throws: { ok:true, channels: Map<slug, channel> }, or
-// { ok:false, reason } when there is no database to ask, psql is missing, or the table is absent
-// (an instance with the provisioning module off). The caller falls back to the roster and says why.
-function readDbChannels({ env = process.env, run = spawnSync } = {}) {
-  const target = env[CHANNEL_DB_ENV] || env.DATABASE_URL || env.PGDATABASE;
-  if (!target) return { ok: false, reason: `no ${CHANNEL_DB_ENV} (or DATABASE_URL / PGDATABASE) set for the sweep` };
-  const r = run('psql', ['-d', target, '-At', '-F', '\t', '-v', 'ON_ERROR_STOP=1', '--no-psqlrc', '-c', DB_CHANNELS_SQL],
-    { encoding: 'utf8', timeout: DB_CHANNELS_TIMEOUT_MS });
-  if (!r || r.error) {
-    const code = r && r.error && r.error.code;
-    return { ok: false, reason: code === 'ENOENT' ? 'psql not found' : code === 'ETIMEDOUT' ? 'psql timed out' : 'psql could not be started' };
-  }
-  if (r.status !== 0) return { ok: false, reason: `psql exit ${r.status}: ${psqlFailureClass(r.stderr)}` };
-  const channels = new Map();
-  for (const line of String(r.stdout || '').split('\n')) {
-    const [slug, ch] = line.split('\t');
-    if (slug && ch) channels.set(slug.trim(), ch.trim());
-  }
-  return { ok: true, channels };
-}
-
-// PURE. Give each roster entry the channel it is actually under, and say where it came from:
-// `channelSource` is 'deploy' (the project row) or 'roster', `channelNote` the one-line reason a
-// sweep log prints. The roster's own value is kept as `rosterChannel`, so a disagreement stays
-// visible in the log instead of silently vanishing.
-function applyDbChannels(instances, db) {
-  return instances.map((inst) => {
-    if (db && db.ok && db.channels.has(inst.slug)) {
-      const ch = normalizeChannel(db.channels.get(inst.slug));
-      const differs = ch !== inst.channel;
-      return {
-        ...inst, channel: ch, channelSource: CHANNEL_SOURCE_DEPLOY, rosterChannel: inst.channel,
-        channelNote: `set on /deploy${differs ? ` (roster says ${inst.channel}, ignored)` : ''}`,
-      };
-    }
-    const why = db && db.ok ? 'no project row for this slug' : (db && db.reason) || 'database not read';
-    return { ...inst, channelSource: CHANNEL_SOURCE_ROSTER, rosterChannel: inst.channel, channelNote: `from the roster — ${why}` };
-  });
-}
-
-// ---- reporting: make "nothing happened" audible -----------------------------
-
-// Turn a loadSubscriptions() result into the line a routine prints EVERY run, plus a level a caller
-// can act on ('ok' | 'warn' | 'alarm'). The judgement that matters is `controlPlane`: a fresh
-// instance subscribing nothing is the shipped default (ADR 0136 — the manifest ships empty), but a
-// CONTROL PLANE that subscribes nothing has silently stopped doing its only job, and that is an alarm.
-// A malformed manifest is an alarm everywhere — an operator wrote something and it does not parse.
-function describeRoster(roster, { controlPlane = false } = {}) {
-  const r = roster || {};
-  const reason = ROSTER_REASONS.includes(r.reason) ? r.reason : ROSTER_EMPTY;
-  const where = r.source || SUBSCRIPTIONS_REL;
-  const dropped = Number(r.dropped) || 0;
-  const n = Array.isArray(r.instances) ? r.instances.length : 0;
-
-  if (reason === ROSTER_MALFORMED) {
-    return { level: 'alarm', reason, count: n, dropped,
-      message: `update-subscriptions: MALFORMED manifest at ${where} (${r.error || 'unparseable'}) — subscribing NOTHING. No instance will be upgraded until this parses.` };
-  }
-  if (reason === ROSTER_ABSENT) {
-    return { level: controlPlane ? 'alarm' : 'warn', reason, count: n, dropped,
-      message: `update-subscriptions: no manifest at ${where} — subscribing NOTHING.${controlPlane ? ' This is a CONTROL PLANE: it is supposed to keep instances current and currently keeps none.' : ' That is the shipped default; add an instance to enroll it.'}` };
-  }
-  if (reason === ROSTER_EMPTY) {
-    return { level: controlPlane ? 'alarm' : 'warn', reason, count: n, dropped,
-      message: `update-subscriptions: manifest at ${where} lists no upgradable instance${dropped ? ` (${dropped} entr${dropped === 1 ? 'y' : 'ies'} dropped for a missing \`dir\`)` : ''} — subscribing NOTHING.${controlPlane ? ' This is a CONTROL PLANE: it is supposed to keep instances current and currently keeps none.' : ''}` };
-  }
-  // Usable entries — still surface partial loss, which is the quiet half of an enrolled-but-untouched
-  // instance: the sweep looks healthy while the operator's broken row is never upgraded.
-  if (dropped > 0) {
-    return { level: 'warn', reason, count: n, dropped,
-      message: `update-subscriptions: ${n} instance${n === 1 ? '' : 's'} subscribed, but ${dropped} entr${dropped === 1 ? 'y was' : 'ies were'} DROPPED for a missing \`dir\` in ${where} — those instances are NOT being upgraded.` };
-  }
-  return { level: 'ok', reason, count: n, dropped,
-    message: `update-subscriptions: ${n} instance${n === 1 ? '' : 's'} subscribed from ${where}.` };
-}
-
-// ---- watching the watcher ---------------------------------------------------
-
-// How far behind is this instance in releases its OWN channel is entitled to take? Not raw version
-// distance: majors, prereleases and (on the patch channel) minors are releases the subscription is
-// correctly declining, and counting them would alarm on instances that are behaving exactly as
-// configured. `behind` is therefore "stable releases this channel WOULD have taken and has not".
-//
-// This is the check that was missing (task 1003158). deploy-divergence.js detects the SYMPTOM — live
-// is behind main — at ship time, when a human is already looking. Nothing watched whether the
-// upgrader itself was still alive, so its death was only ever discovered by someone noticing stale UI
-// days later. A healthy sweep drives `behind` to 0 every run, so a persistent backlog IS the alarm.
-//
-// A `pinned` instance is never stale: channelAllows declines everything, so behind === 0 by
-// construction. That is correct — a pinned instance is not neglected, it is pinned.
-function subscriptionStaleness({ installed, channel, available, threshold = DEFAULT_STALENESS_THRESHOLD } = {}) {
-  const ch = normalizeChannel(channel);
-  const list = Array.isArray(available) ? available : [];
-  // `installed` is parsed and the channel re-normalized ONCE, not per candidate:
-  // channelAllows re-does both on every element, and this filter is the only place
-  // that calls it in a loop. Cheap either way at registry scale — hoisted because
-  // the invariant genuinely is invariant, not because the arithmetic hurts.
-  const from = parseSemver(installed);
-  const behind = (ch === 'pinned' || !from) ? 0
-    : list.filter((v) => channelAllows(installed, v, ch)).length;
-  const t = Number(threshold);
-  const limit = Number.isFinite(t) && t >= 0 ? t : DEFAULT_STALENESS_THRESHOLD;
-  return {
-    channel: ch,
-    installed: installed == null ? null : String(installed),
-    target: resolveChannelTarget({ installed, channel: ch, available: list }),
-    behind,
-    threshold: limit,
-    stale: behind > limit,
-  };
-}
-
-// The alarm line for one subscribed instance, or null when it is healthy (nothing to say).
-function describeStaleness(st, { slug = 'instance' } = {}) {
-  if (!st || !st.stale) return null;
-  return `update-subscriptions: ${slug} is ${st.behind} ${st.channel} release${st.behind === 1 ? '' : 's'} behind `
-    + `(installed ${st.installed || 'unknown'}, entitled to ${st.target}) — over the ${st.threshold} threshold. `
-    + 'A healthy sweep clears this to zero every run, so the upgrader has most likely stopped.';
-}
-
-module.exports = {
-  npmSpawnOpts,
-  CORE_PKG,
-  VALID_CHANNELS,
-  DEFAULT_CHANNEL,
-  VALID_FOLLOWS,
-  DEFAULT_FOLLOW,
-  normalizeFollow,
-  versionsForFollow,
-  readReleaseTags,
-  followForShape,
-  SUBSCRIPTIONS_REL,
-  parseSemver,
-  isStable,
-  compareSemver,
-  normalizeChannel,
-  channelAllows,
-  resolveChannelTarget,
-  listAvailableVersions,
-  parseNpmViewVersions,
-  loadSubscriptions,
-  readDbChannels,
-  CHANNEL_DB_ENV,
-  applyDbChannels,
-  channelLine,
-  psqlFailureClass,
-  CHANNEL_SOURCE_DEPLOY,
-  CHANNEL_SOURCE_ROSTER,
-  ROSTER_OK,
-  ROSTER_ABSENT,
-  ROSTER_MALFORMED,
-  ROSTER_EMPTY,
-  ROSTER_REASONS,
-  DEFAULT_STALENESS_THRESHOLD,
-  describeRoster,
-  subscriptionStaleness,
-  describeStaleness,
-};
+require('../bongos/forwarder.js').forward(module, 'update-channel.js');