@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/update-channel.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/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,
+};