@bongos/core 1.19.347 → 1.19.349

package/modules/lifecycle/github-push.js

@@ -130,6 +130,23 @@ function scrubCredential(s) {
     .replace(/(ghs_|ghp_|github_pat_)[A-Za-z0-9_]+/g, '$1***');
 }
 
+// How much scrubbed stderr travels with a failure (task 1003222). Sized to hold a
+// real git failure whole — the 'remote:' lines that name the cause arrive LAST, so a
+// short cap deletes precisely the part worth reading. It is a payload bound, nothing
+// more; when it bites, truncateLoudly says so rather than ending mid-word.
+const STDERR_MAX = 8000;
+
+// Truncate in a way the reader can SEE. A silent clip is worse than no message: it
+// looks like the complete text, which is how 'error: failed' got mistaken for the
+// whole story. Keeps the TAIL as well as the head, because git's useful line is last.
+function truncateLoudly(text, max = STDERR_MAX) {
+  const s = String(text || '');
+  if (s.length <= max) return s;
+  const head = Math.floor(max * 0.4);
+  const tail = max - head;
+  return `${s.slice(0, head)}\n\n…[${s.length - max} characters omitted — full text in the server log]…\n\n${s.slice(-tail)}`;
+}
+
 // Default git seam: execFile arg-array, shell:false, stdout captured. On failure
 // throws GIT_FAILED. We never echo the (possibly credentialed) argv, but DO attach
 // the credential-scrubbed stderr + the caller's step label (task 1547) so a real
@@ -149,9 +166,30 @@ async function defaultExec(args, opts = {}) {
     return stdout;
   } catch (e) {
     // Identify the failing step by the caller's label, never by echoing argv.
-    // Surface the scrubbed stderr (truncated) so the cause is loud in the log.
-    const stderr = scrubCredential(e && (e.stderr || e.message)).trim().slice(0, 500);
-    throw err('GIT_FAILED', { git_step: step || (args && args[0]) || null, stderr });
+    //
+    // THE STDERR IS NOT CLIPPED SHORT ANY MORE (task 1003222). It used to be cut at
+    // 500 chars here and again at 200 on the way to the client, so a builder saw
+    // 'error: failed' — clipped mid-word, naming neither cause nor remedy — while the
+    // line that mattered ('remote: fatal error in commit_refs') and the exit code
+    // existed only server-side. That cost hours on the blocker-1000117 outage AND
+    // produced a WRONG first diagnosis, because the real message was never in the
+    // room. git puts the useful line LAST (the 'remote:' lines follow the progress
+    // chatter), which is exactly what a head-truncation throws away.
+    //
+    // The cap is a payload guard, not an editorial decision: generous enough that a
+    // real push failure fits whole, and when it does bite the text SAYS SO instead of
+    // ending mid-word and reading like the whole message.
+    const raw = scrubCredential(e && (e.stderr || e.message)).trim();
+    const stderr = truncateLoudly(raw, STDERR_MAX);
+    throw err('GIT_FAILED', {
+      git_step: step || (args && args[0]) || null,
+      stderr,
+      stderr_bytes: raw.length,
+      // The exit code distinguishes failure SHAPES that read identically in prose —
+      // 128 (git said no) vs 1 (a ref was rejected) vs null (killed by the timeout).
+      exit_code: (e && typeof e.code === 'number') ? e.code : null,
+      timed_out: !!(e && e.killed),
+    });
   }
 }
 
@@ -456,7 +494,14 @@ async function openOrFindPullRequest({ branch, title, body }, deps = {}) {
   });
   if (!createRes.ok) {
     const detail = await createRes.text().catch(() => '');
-    throw err('PR_CREATE_FAILED', { status: createRes.status, detail: detail.slice(0, 300) });
+    // Same reasoning as GIT_FAILED's stderr (task 1003222): GitHub's refusal body
+    // names the actual rule that refused ('No commits between main and X', a
+    // protected-branch rule, a validation error naming the field) and a 300-char
+    // clip regularly cut it off. Scrubbed, because a body can echo a request header.
+    throw err('PR_CREATE_FAILED', {
+      status: createRes.status,
+      detail: truncateLoudly(scrubCredential(detail), STDERR_MAX),
+    });
   }
   const pr = await createRes.json();
   return { number: pr.number, url: pr.html_url, node_id: pr.node_id };
@@ -1360,6 +1405,8 @@ module.exports = {
   prReferencesTask,
   findTaskPullRequest,
   scrubCredential,
+  truncateLoudly,   // task 1003222 — exported so its behaviour is testable, not just its effect
+  STDERR_MAX,
   isAncestorOfDefaultBranch,
   resolveToken,
   getInstallationToken,

package/modules/lifecycle/routes/tasks.js

@@ -979,7 +979,12 @@ module.exports = function buildTasksRouter() {
       if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
       if (e.code === 'PUSH_UNCONFIGURED') return res.fail('push_unconfigured', { status: 503, message: PUSH_UNCONFIGURED_MSG });
       if (e.code === 'APP_NOT_INSTALLED') return res.fail('push_unconfigured', { status: 503, message: appNotInstalledMessage(e) });
-      if (e.code === 'PR_CREATE_FAILED') return res.fail('pr_create_failed', 502, { detail: e.detail });
+      // The GitHub HTTP status travels WITH the body (task 1003222). 422 ('no commits
+      // between'), 403 (a protected-branch rule) and 404 (the App cannot see the repo)
+      // are three different remedies, and the body alone does not always separate them.
+      if (e.code === 'PR_CREATE_FAILED') {
+        return res.fail('pr_create_failed', 502, { detail: e.detail, github_status: e.status ?? null });
+      }
       // task 1547: GIT_FAILED now carries WHICH git step failed + the credential-
       // scrubbed stderr (github-push.defaultExec). Log both so the next push outage
       // is a one-line diagnosis, not a multi-hour opaque-`publish_failed` mystery
@@ -990,7 +995,22 @@ module.exports = function buildTasksRouter() {
         e.git_step ? `step=${e.git_step}` : '',
         e.stderr ? `stderr=${e.stderr}` : ''
       );
-      return res.fail('publish_failed', 500, { ...(e.git_step ? { step: e.git_step } : {}), ...(e.stderr ? { reason: String(e.stderr).slice(0, 200) } : {}) });
+      // NO SECOND TRUNCATION (task 1003222). This line used to clip the already-
+      // shortened stderr to 200 chars, so the builder got 'error: failed' — cut
+      // mid-word, naming neither cause nor remedy — while the real remote message sat
+      // in a log they could not reach. A publish failure must be diagnosable from
+      // where the builder is STANDING; that is the whole point of the task.
+      //
+      // `reason` keeps its name and position so existing readers (ship.js prints it)
+      // keep working; it is simply no longer amputated. Everything here is already
+      // credential-scrubbed at the throw site by github-push.scrubCredential.
+      return res.fail('publish_failed', 500, {
+        ...(e.git_step ? { step: e.git_step } : {}),
+        ...(e.stderr ? { reason: e.stderr } : {}),
+        ...(e.stderr_bytes != null ? { reason_bytes: e.stderr_bytes } : {}),
+        ...(e.exit_code != null ? { git_exit_code: e.exit_code } : {}),
+        ...(e.timed_out ? { timed_out: true } : {}),
+      });
     } finally {
       try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
     }

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.347",
+  "version": "1.19.349",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.347",
+      "version": "1.19.349",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.347",
+  "version": "1.19.349",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/client-baseurl-guard.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// scripts/gds/client-baseurl-guard.js — a web page must not send its API calls to
+// the site root (task 1003263).
+//
+// THE BUG THIS EXISTS TO STOP. The generated client (clients/bongos-client) exposes
+// two call styles, and mixing them is silent and fatal:
+//
+//   NAMESPACED   api.inbox.getInboxTemplate({})   → path template '/inbox/template',
+//                                                   API-RELATIVE, needs the API base
+//   ESCAPE HATCH api.request('GET', `${API}/me`)  → caller supplies the FULL path
+//
+// createClient documents `baseUrl: ''` as "paths are already absolute" and passes
+// them through unchanged. So a page that sets baseUrl:'' AND calls a namespaced
+// method requests '/inbox/template' — the SITE ROOT, where nothing is mounted — and
+// 404s on every call. The router mounts at '/api/bongos/v1' (api-prefix.js
+// VERSIONED_API_PREFIX), which is exactly the client's own default.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. Three pages shipped this defect — ideas.js and
+// idea.js were dead in production from the day they shipped, and collab.js was caught
+// in review one commit before it would have been. Every page test stubs the client
+// method directly, so URL construction is never exercised; tests/idea_hall_composer.mjs
+// even asserted with a regex against the source text, which passes happily on a broken
+// URL. 54 green tests over pages that 404 on every call. The defect is invisible to the
+// test style this repo uses for hall pages, so it needs a guard at a different altitude.
+//
+// STATIC AND CONSERVATIVE. It flags only the unambiguous combination — an explicit
+// empty baseUrl in a createClient call, in a file that also makes a namespaced call.
+// A page using the escape hatch with baseUrl:'' is CORRECT and stays silent (work.js,
+// copy-desk.js, goal-inbox.js and most of the hall do exactly that).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a web page sends its API calls to the API, not the site root (task 1003263)';
+
+// createClient({ ... baseUrl: '' ... }) — an EXPLICIT empty base. Omitting baseUrl is
+// the correct fix and must not match; only the literal empty string is the defect.
+const EMPTY_BASEURL = /createClient\(\s*\{[^}]*baseUrl\s*:\s*(''|""|`\s*`)/;
+
+// api.<namespace>.<method>( — the generated namespaced style. `api.request(` is the
+// escape hatch and is deliberately NOT matched: with it, baseUrl:'' is correct.
+const NAMESPACED_CALL = /\bapi\s*\.\s*(?!request\b)[A-Za-z_$][\w$]*\s*\.\s*[A-Za-z_$][\w$]*\s*\(/;
+
+// Every tracked browser-served script. Server code never calls createClient this way.
+function trackedPageScripts() {
+  try {
+    const out = execFileSync('git', ['ls-files', 'modules/*/public/*.js', 'public/*.js'],
+      { cwd: REPO_ROOT, encoding: 'utf8' });
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function scanPages(files, read) {
+  const violations = [];
+  let scanned = 0;
+  let usingClient = 0;
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    scanned += 1;
+    if (!/createClient\(/.test(src)) continue;
+    usingClient += 1;
+    if (!EMPTY_BASEURL.test(src)) continue;
+    if (!NAMESPACED_CALL.test(src)) continue; // escape-hatch page — baseUrl:'' is right
+    const m = NAMESPACED_CALL.exec(src);
+    violations.push(
+      `${rel} sets baseUrl:'' AND calls the generated client (${m[0].replace(/\s+/g, '')}…). `
+      + "Those paths are API-relative, so baseUrl:'' sends them to the site root and every "
+      + 'call 404s. Drop the baseUrl override, or switch every call to '
+      + "api.request('METHOD', `${API}/…`) with a full path.",
+    );
+  }
+  return { violations, scanned, usingClient };
+}
+
+function checkClientBaseUrl({ files, read } = {}) {
+  const list = files || trackedPageScripts();
+  if (!list.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked page scripts; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of browser-served scripts for a root-bound API client.',
+    };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned, usingClient } = scanPages(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} browser-served script(s) scanned, ${usingClient} building a client: none may combine `
+      + "baseUrl:'' with a generated namespaced call (api.<ns>.<method>()) — that pairing 404s every request. "
+      + "baseUrl:'' with api.request() and a full path is the correct escape-hatch style and is not flagged.",
+  };
+}
+
+function main() {
+  const r = checkClientBaseUrl();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkClientBaseUrl, scanPages, trackedPageScripts, EMPTY_BASEURL, NAMESPACED_CALL };

package/scripts/gds/deploy-divergence.js

@@ -160,6 +160,28 @@ async function fetchLive(base, timeoutMs = DEFAULT_TIMEOUT_MS) {
   }
 }
 
+// Is the automation that should have PREVENTED this divergence itself alive? (task 1003158)
+//
+// This script detects the SYMPTOM — live is behind main — and only ever at a moment a human is
+// already looking. What went unwatched is the auto-upgrade subscription itself: when it stopped,
+// nothing said so, and cloudbongos.com sat 36 releases behind for days. Reading the roster here means
+// a dead upgrader is reported in the same breath as the staleness it was supposed to prevent.
+//
+// Speaks ONLY when a subscription manifest is actually present. An ordinary core checkout has none by
+// design (ADR 0136 — it ships empty), and alarming about that every session is exactly the noise that
+// gets a real warning scrolled past. Present-but-broken, or present-and-subscribing-nothing, is the
+// signal worth having: someone meant to enroll instances here and none are being upgraded.
+function subscriptionHealth(dir = REPO_ROOT) {
+  try {
+    const uc = require('./update-channel');
+    const roster = uc.loadSubscriptions({ instanceDir: dir });
+    if (!roster.present) return null;
+    return uc.describeRoster(roster, { controlPlane: true });
+  } catch {
+    return null; // never let the health probe break the divergence check it rides along with
+  }
+}
+
 async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const target = base || arg('--url') || API_BASE;
   const local = coreVersionAt(null);
@@ -173,7 +195,9 @@ async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const unreleased = unreleasedSince(mainRef);
   const live = await fetchLive(target, timeoutMs);
 
-  if (live.error) return { ok: false, undetermined: true, reason: `could not read ${live.url}: ${live.error}`, target, local, onMain, unreleased };
+  const subscriptions = subscriptionHealth();
+
+  if (live.error) return { ok: false, undetermined: true, reason: `could not read ${live.url}: ${live.error}`, target, local, onMain, unreleased, subscriptions };
 
   const behind = cmpSemver(live.coreVersion, onMain) < 0;
   const ahead = cmpSemver(live.coreVersion, onMain) > 0;
@@ -181,7 +205,7 @@ async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
 
   return {
     ok: !behind && !hasUnreleased,
-    target, local, onMain, mainRef, unreleased, live, behind, ahead, hasUnreleased,
+    target, local, onMain, mainRef, unreleased, live, behind, ahead, hasUnreleased, subscriptions,
   };
 }
 
@@ -232,6 +256,13 @@ function report(r, { quiet = false } = {}) {
   if (r.ahead) {
     say(`  note: live (${r.live.coreVersion}) is AHEAD of ${r.mainRef} (${r.onMain}) — this checkout is stale; fetch.`);
   }
+  // The watcher's watcher: if this checkout carries a subscription roster and that roster is not
+  // healthy, the unattended upgrade is not going to close the gap above on its own.
+  if (r.subscriptions && r.subscriptions.level !== 'ok') {
+    say('');
+    say(`  ${r.subscriptions.level === 'alarm' ? '⚠ AUTO-UPGRADE' : 'note: auto-upgrade'} — ${r.subscriptions.message}`);
+    if (r.behind) say('    So the gap above will NOT close by itself.');
+  }
   say('');
   say('  Merging to main deploys nothing by design. "shipped" means "merged" —');
   say('  it does not mean users can see it.');
@@ -317,4 +348,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { check, report, line, coreVersionAt, unreleasedSince, cmpSemver };
+module.exports = { check, report, line, coreVersionAt, unreleasedSince, cmpSemver, subscriptionHealth };

package/scripts/gds/fitness.js

@@ -1307,6 +1307,7 @@ const CHECKS = [
   require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
   require('./routine-schedule.js').checkRoutineCadencesScheduled, // Check 25 — task 1003209: a routine that declares a cadence must have a scheduler firing it AT that period (ADR 0188)
   require('./baseline-staleness.js').checkBaselineFloors, // Check 26 — task 1003210: a shrink-only baseline that never shrinks is unmanaged debt; a floor exempting one must say why
+  require('./client-baseurl-guard.js').checkClientBaseUrl, // Check 27 — task 1003263: a page must not combine baseUrl:'' with a generated namespaced call (that pairing 404s every request; three pages shipped it, two of them dead in prod)
 ];
 
 function runAll() {

package/scripts/gds/ship-land.js

@@ -89,12 +89,23 @@ function formatPublishFailure(data, status, branch, opts = {}) {
   const envelopeDetails = (data && data.error && typeof data.error === 'object' && data.error.details) || null;
   const details = envelopeDetails || data || {};
   const label = message || code || (data && data.message) || `HTTP ${status}`;
-  // git stderr is multi-line; this is embedded mid-sentence in one log line.
+  // Flattened ONLY for the matchers below and the one-line summary. The readable
+  // copy is printed verbatim underneath (task 1003222): the server no longer clips
+  // stderr, and git's useful line is the LAST one, so collapsing a 20-line push
+  // failure into a single run-on sentence hides the very thing that was un-hidden.
   const reason = details.reason ? String(details.reason).replace(/\s+/g, ' ').trim() : '';
   const parts = [];
   if (details.step) parts.push(`step: ${details.step}`);
-  if (reason) parts.push(`reason: ${reason}`);
+  if (details.git_exit_code != null) parts.push(`git exit ${details.git_exit_code}`);
+  if (details.github_status != null) parts.push(`GitHub HTTP ${details.github_status}`);
+  if (details.timed_out) parts.push('TIMED OUT');
+  // The one-line summary stays short and scannable; the full text follows it.
+  if (reason) parts.push(`reason: ${reason.length > 200 ? `${reason.slice(0, 200)}…` : reason}`);
   let out = parts.length ? `${label} (${parts.join('; ')})` : label;
+
+  // ORDER MATTERS: summary, then the REMEDY, then the verbatim block last. The
+  // remedy is the actionable sentence and must not end up stranded below twenty
+  // lines of git chatter where it reads as a footnote to the quote.
   if (NON_FAST_FORWARD_RE.test(reason)) {
     out += opts.localHistoryRewritten === true
       ? ` — your LOCAL history was rewritten (a rebase or amend), so ${branch} is no longer a `
@@ -104,6 +115,17 @@ function formatPublishFailure(data, status, branch, opts = {}) {
       : ` — the server already moved ${branch}: fetch origin, reset onto origin/${branch}, `
         + 're-run the generators, and re-ship so the push fast-forwards.';
   }
+
+  // The untruncated remote message, verbatim and indented so it reads as a quotation
+  // rather than as more ship output. Only when it is multi-line — a single-line
+  // stderr is already fully present in the summary above, and repeating it is noise.
+  const full = details.reason ? String(details.reason).trimEnd() : '';
+  if (full && /\n/.test(full)) {
+    out += `\n\n  --- what the remote actually said ---\n${full.split('\n').map((l) => `  ${l}`).join('\n')}\n  --- end ---`;
+    if (details.reason_bytes != null && details.reason_bytes > full.length) {
+      out += `\n  (${details.reason_bytes} bytes at the server; the middle was omitted here)`;
+    }
+  }
   return out;
 }
 

package/scripts/gds/update-channel.js

@@ -32,6 +32,23 @@ const DEFAULT_CHANNEL = 'patch';
 // 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.
@@ -143,16 +160,23 @@ function parseNpmViewVersions(stdout) {
 // 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 }; }
+  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, error: `malformed JSON: ${e.message}` }; }
+  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 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
+  // 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),
@@ -178,7 +202,90 @@ function loadSubscriptions({ instanceDir = process.cwd(), fsImpl = fs, file = SU
         ? Object.fromEntries(Object.entries(r.env).filter(([, v]) => typeof v === 'string'))
         : {},
     }));
-  return { defaultChannel, instances, source: abs, present: true };
+  return {
+    defaultChannel, instances, source: abs, present: true, dropped,
+    reason: instances.length ? ROSTER_OK : ROSTER_EMPTY,
+  };
+}
+
+// ---- 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 = {
@@ -195,4 +302,13 @@ module.exports = {
   listAvailableVersions,
   parseNpmViewVersions,
   loadSubscriptions,
+  ROSTER_OK,
+  ROSTER_ABSENT,
+  ROSTER_MALFORMED,
+  ROSTER_EMPTY,
+  ROSTER_REASONS,
+  DEFAULT_STALENESS_THRESHOLD,
+  describeRoster,
+  subscriptionStaleness,
+  describeStaleness,
 };

package/src/module-api.js

@@ -1124,8 +1124,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.345 with no explicit bump. run 32801147433. (task 1002620)
 //   1.19.347 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.346 with no explicit bump. run 32802265337. (task 1002620)
+//   1.19.348 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.347 with no explicit bump. run 32802746363. (task 1002620)
+//   1.19.349 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.348 with no explicit bump. run 32803276871. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.347'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.349'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');