@bongos/core 1.20.61 → 1.20.62

package/scripts/gds/update-sweep.js

@@ -0,0 +1,717 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/update-sweep.js — the update-subscription sweep (task 2150, ADR 0136).
+//
+// WHERE IT LIVES (task 1004307). This was .claude/scheduled-tasks/core-update-subscription/subscribe.js,
+// and the core package ships no .claude/scheduled-tasks/. So a control plane ran whatever copy its
+// own checkout held: cloudbongos.com's sweep ran a checkout frozen at 2026-08-25, and every lane fix
+// after that never ran there. Under scripts/gds/ it ships in every release. A unit runs it straight
+// from the INSTALLED core (node <instance>/node_modules/@bongos/core/scripts/gds/update-sweep.js
+// --apply --instance <roster root>), and each upgrade it performs brings the next run current code.
+// It therefore requires its core siblings by relative path, which is right in both layouts. The one
+// thing it still resolves across layouts is the TARGET instance's own core (coreModulePathFrom below).
+// subscribe.js remains as a shim, so the routine's step and a hand run keep working.
+//
+// For each instance the operator has opted into config/update-subscriptions.json, ask the registry
+// what @bongos/core versions are published, resolve the newest one this instance's UPDATE CHANNEL
+// permits (patch-only by default; a major is never automatic), and — if that's newer than what's
+// installed — run `bongos upgrade --to <v> --registry` for it. Auto-rollback is ON by default (task
+// 2149), so a patch that fails install/migrate/health reverts itself before this returns.
+//
+// DRY-RUN by default (the box-sweep convention): it prints the plan and changes nothing. The
+// scheduled step passes --apply to actually upgrade. Double-gated in production: the routine is
+// requiresAutonomy:true + default OFF (config/scheduled-routines.json) AND the roster ships empty, so
+// nothing upgrades until an operator both arms autonomy and lists a target.
+//
+// This is the body of a `mode: deterministic` routine — it runs as plain node with NO model session.
+//
+// ── THE PIN (task 1003212) ───────────────────────────────────────────────────────────────────────
+// A successful upgrade rewrites package.json + package-lock.json. If those are left UNCOMMITTED the
+// lane sabotages itself two ways, and did so from the day it was armed:
+//   1. upgrade.js's clean-tree preflight is a bare `git status --porcelain`, so the NEXT sweep dies
+//      "✖ working tree not clean" and exits 1 — a systemd failure nobody watches. Net effect: the
+//      lane applies AT MOST ONE upgrade per manual pin commit.
+//   2. a pull-deploy `git reset --hard origin/main` REVERTS the bump and npm ci reinstalls the older
+//      core. Live silently goes backwards, and every health check still passes.
+// Passing --commit-pin is necessary but NOT sufficient: this routine used to spawn the CONTROL
+// PLANE's vendored upgrade.js, which can be many releases behind (it was on core 1.19.2, ~305 back)
+// and whose parseArgs is a pure allowlist that SILENTLY IGNORES an unknown flag. Adding the flag
+// there would have changed nothing and still reported success — the same silent shape as the bug.
+// So this file now: (a) spawns the TARGET INSTANCE's own upgrade.js, which is by definition current,
+// (b) DETECTS --commit-pin support instead of assuming it, and (c) VERIFIES the end state and heals
+// it, because the only trustworthy signal is a clean tree — not an exit code.
+//
+// ── WHAT THE LANE ITSELF WROTE (task 1003968) ────────────────────────────────────────────────────
+// Every bump also re-materializes .claude/ and regenerates the API artifacts into the instance tree.
+// The guard below used to sort a dirty worktree two ways — "the pin" and "a human's work, halt" — and
+// the lane's own output has never been either. So on any run that does not commit it (pinMode
+// leave-dirty, whose whole premise is that the tree may stay dirty; or a core too old for the flags
+// that commit it) the sweep halted on its own exhaust, and halted there forever. pinState now sorts
+// THREE ways, and the third bucket is not a glob of paths that look generated: it is what the
+// instance's OWN core says this upgrade rewrites (laneGeneratedPaths). Anything outside that set is
+// still a human's, and still stops us.
+//
+// Usage:
+//   node scripts/gds/update-sweep.js            # dry-run (plan only)
+//   node scripts/gds/update-sweep.js --apply    # actually upgrade
+//   …--only <slug>       limit to one subscribed instance
+//   …--instance <dir>    where to read config/update-subscriptions.json (default: the working directory)
+//
+// Exit codes: 0 = clean (upgraded, or nothing to do), 1 = at least one instance's upgrade failed OR
+// ended with an uncommitted pin (an unhealed pin is a FAILURE — it wedges the next run).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const channel = require('./update-channel.js');
+const { readInstalledCoreVersion } = require('./upgrade.js');
+
+// Where a core file lives for a given instance: at its root (a monolith checkout), else inside each
+// installed core package. The same order and names as .claude/hooks/_core-resolve.js, which the core
+// package does not ship (it is topology-excluded), so this file cannot require it.
+// tests/update_sweep_home.mjs holds the two lists equal.
+const CORE_PKG_NAMES = ['@cloudbongos/core', '@bongos/core', 'cloudbongos'];
+function coreModulePathFrom(instanceRoot, relpath) {
+  const bases = [instanceRoot, ...CORE_PKG_NAMES.map((n) => path.join(instanceRoot, 'node_modules', ...n.split('/')))];
+  for (const base of bases) {
+    try { return require.resolve(path.join(base, relpath)); } catch (_) { /* not in this base */ }
+  }
+  return null;
+}
+
+// Tiny argv helpers — kept inline so this cron companion pulls in no heavier CLI surface than it needs.
+const argv = process.argv.slice(2);
+const hasFlag = (name) => argv.includes(name);
+const argOf = (name) => { const i = argv.indexOf(name); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null; };
+
+// The two files a core bump rewrites. Nothing else may be auto-committed by this lane — a sweep that
+// commits whatever it happens to find is far more dangerous than one that stalls.
+const PIN_FILES = ['package.json', 'package-lock.json'];
+
+// ── pin plumbing ─────────────────────────────────────────────────────────────────────────────────
+
+function git(dir, args, run = spawnSync) {
+  const r = run('git', ['-C', dir, ...args], { encoding: 'utf8' });
+  const ok = !!r && !r.error && r.status === 0;
+  return { ok, stdout: (r && r.stdout) || '', stderr: (r && r.stderr) || '', status: r ? r.status : null };
+}
+
+// The instance-relative paths THIS upgrade writes into the instance's own tree — the provenance
+// answer pinState's third bucket is sorted by.
+//
+// Asked of the TARGET INSTANCE's core, never the control plane's, for the reason resolveUpgradeScript
+// documents: the instance being upgraded is current by definition, while the control plane's vendored
+// copy is the plane nobody bumps (it sat ~305 releases behind, and that staleness is what silently
+// disabled --commit-pin for the whole lane). Two sources, each already the core's own answer to "what
+// does a bump rewrite here":
+//   • upgrade.js API_ARTIFACT_FILES — the OpenAPI spec + typed client regenerated from the new core's
+//     routes (task 1003926).
+//   • claude-materialize.js materializeWillRewrite — a DRY RUN of the materialize step, so the set is
+//     derived from the core actually installed here rather than guessed from a glob (task 1004122).
+//     It is the same function upgrade.js's own clean-tree pre-flight waives dirt by, so the lane and
+//     the bump it spawns agree on what "this upgrade rewrote" means.
+//
+// FAIL-SOFT, and the direction is deliberate. An instance whose core predates either export, or whose
+// materialize throws, yields nothing here: every dirty path stays in `other` and the guard is exactly
+// as strict as it was before this function existed. The failure mode is "still wedged", never
+// "committed a stranger's work".
+function laneGeneratedPaths(instDir, { resolveFrom = coreModulePathFrom, load = require } = {}) {
+  const out = new Set();
+  try {
+    const p = resolveFrom(instDir, 'scripts/gds/upgrade.js');
+    if (p) for (const files of Object.values(load(p).API_ARTIFACT_FILES || {})) for (const f of files) out.add(f);
+  } catch (_) { /* an older core, or one that will not load here — stay strict */ }
+  try {
+    const p = resolveFrom(instDir, 'scripts/gds/claude-materialize.js');
+    const willRewrite = p && load(p).materializeWillRewrite;
+    if (willRewrite) {
+      // coreRoot is derived from where the module RESOLVED (<core>/scripts/gds/x.js → <core>), not
+      // from a package-name guess: an instance may carry the core under any of its published names,
+      // and in the monolith layout the core root IS the instance root (where materialize no-ops).
+      const coreRoot = path.resolve(path.dirname(p), '..', '..');
+      for (const f of willRewrite({ instanceDir: instDir, coreRoot }, () => {}) || []) out.add(f);
+    }
+  } catch (_) { /* same — a set we could not derive is an empty one, never a guessed one */ }
+  return [...out];
+}
+
+// Split a dirty worktree into "the pin", "what this upgrade generated", and "everything else". The
+// distinction is the whole safety story, and it is THREE-way for a reason (task 1003968).
+//
+// Two buckets could not express what a bump actually leaves behind. Every upgrade re-materializes
+// .claude/ and regenerates the API artifacts, so on any run that does not commit them the lane's OWN
+// output landed in `other` — and `other` means "a human's work, halt". That wedged pinMode
+// leave-dirty against its own definition (a mode whose point is that the tree may stay dirty, stopped
+// by dirt), and wedged any instance on a core too old for the flags that commit it.
+//
+// `generated` is not an allow-list of paths that LOOK generated; it is what the instance's own core
+// says this upgrade rewrites. A path outside that set — an owner's edit, a hand-written skill, a
+// half-finished migration — is still `other` and still stops us, which is the property task 1003957
+// pinned and this must not spend.
+function pinState(dir, run = spawnSync, generated = []) {
+  // -uall, not the default -unormal. A wholly-untracked DIRECTORY is collapsed to one entry —
+  // '?? .claude/skills/new-in-785/' — so a skill the new core adds would never match a path in
+  // `generated`, would land in `other`, and would wedge the lane in exactly the way this sorting
+  // exists to prevent. Listing untracked files individually is what makes the buckets comparable.
+  const r = git(dir, ['status', '--porcelain', '-uall'], run);
+  if (!r.ok) return { repo: false };
+  const ours = new Set(generated);
+  const entries = r.stdout.split('\n').map((l) => l.trim()).filter(Boolean)
+    .map((l) => ({ raw: l, file: l.slice(2).trim() }));
+  const pin = entries.filter((e) => PIN_FILES.includes(e.file));
+  const rest = entries.filter((e) => !PIN_FILES.includes(e.file));
+  return {
+    repo: true,
+    clean: entries.length === 0,
+    pin,
+    generated: rest.filter((e) => ours.has(e.file)),
+    other: rest.filter((e) => !ours.has(e.file)),
+  };
+}
+
+// Commit + push ONLY the pin files. Returns a verdict rather than throwing: a sweep must survive one
+// instance's git trouble and keep going, but it must never call the result clean.
+//
+// `push: false` commits and STOPS — go-live's `local-commit` pin mode (task 1003521). On a
+// provisioned co-tenant the remote is the CUSTOMER's own repo: pushing there is wrong, and in
+// practice uncredentialed. Nothing reverts the pin either, because a co-tenant has no
+// pull-deploy timer, so a local commit is durable on its own.
+//
+// `generated` (task 1003968) is the paths THIS upgrade wrote — laneGeneratedPaths' answer. They are
+// committed alongside the pin and are NOT grounds to refuse: the upgrade overwrites them
+// unconditionally on every bump, so refusing on them protects nothing and stops every future sweep.
+// The refusal itself stays exactly where it was, keyed on everything else.
+function commitPin({ dir, message, remote = 'origin', push = true, generated = [] }, run = spawnSync, log = console.log, err = console.error) {
+  const st = pinState(dir, run, generated);
+  if (!st.repo) return { ok: true, action: 'not-a-repo' };
+  if (st.other.length) {
+    return {
+      ok: false, action: 'refused',
+      reason: `worktree carries changes that are neither the pin nor this upgrade's own output (${st.other.slice(0, 5).map((e) => e.file).join(', ')}) — refusing to auto-commit a human's work`,
+    };
+  }
+  if (!st.pin.length && !st.generated.length) return { ok: true, action: 'already-clean' };
+
+  // Stage the pin plus whatever of the upgrade's OWN output is dirty — never "everything dirty".
+  // The refusal above is the guard that keeps an owner's edit out of an unattended commit, and it
+  // stays keyed on a set the instance's core produced rather than on one this file invented.
+  const add = git(dir, ['add', '--', ...PIN_FILES, ...st.generated.map((e) => e.file)], run);
+  if (!add.ok) return { ok: false, action: 'add-failed', reason: add.stderr.trim().split('\n').pop() };
+
+  const commit = git(dir, ['commit', '-m', message], run);
+  if (!commit.ok) return { ok: false, action: 'commit-failed', reason: commit.stderr.trim().split('\n').pop() };
+
+  const branch = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD'], run);
+  const target = branch.ok ? branch.stdout.trim() : 'main';
+
+  if (!push) {
+    log('    ✓ pin committed locally, not pushed (pinMode local-commit — the remote is not ours)');
+    return { ok: true, action: 'committed-local', committed: true, branch: target };
+  }
+
+  const pushed = git(dir, ['push', remote, `HEAD:${target}`], run);
+  if (!pushed.ok) {
+    // Committed but not pushed is STILL doomed — deploy.sh resets to the REMOTE.
+    return { ok: false, action: 'push-failed', reason: pushed.stderr.trim().split('\n').pop(), committed: true };
+  }
+  log(`    ✓ pin committed + pushed to ${remote}/${target} — a pull-deploy reset can no longer revert it`);
+  return { ok: true, action: 'committed', committed: true, branch: target };
+}
+
+// ── the deploy engine: go-live.js when the instance can support it ───────────────────────────────
+
+// Fields go-live.js REQUIRES to build a valid target. `ssh` is deliberately absent: the
+// routine runs ON the box, so the target is LOCAL and go-live drives a local shell.
+// `runAs` is absent too — this routine already runs as the instance owner, so no sudo
+// hop is needed and no secret has to be handed across a privilege boundary.
+// This list MIRRORS go-live.js's own REQUIRED_FIELDS — a second copy of someone else's
+// contract, so it drifts silently when that contract moves. It did: co-tenant mode
+// (task 1003521) made `deployTimer` optional there, and this copy kept requiring it, so
+// every provisioned co-tenant was told its roster entry "lacks deployTimer" and dropped to
+// the weaker direct-upgrade path forever.
+const GO_LIVE_REQUIRED = ['instanceDir', 'service', 'healthUrl', 'versionUrl'];
+
+// Read the roster entry STRAIGHT FROM DISK for the deploy-topology fields.
+//
+// loadSubscriptions() normalizes entries, and it comes from the CONTROL PLANE's core —
+// which is a separate plane nobody bumps (it sat on 1.19.2, ~305 releases behind). A
+// normalizer that predates a field silently drops it, so an instance can name
+// versionUrl + deployTimer and still be told "roster entry lacks versionUrl +
+// deployTimer" forever. That is the same stale-vendored-core trap that disabled
+// --commit-pin (task 1003212), wearing a different hat: do not let the oldest thing on
+// the box decide which features the newest thing may use.
+//
+// So the topology is read directly. Everything ELSE still comes from the normalizer —
+// this is a targeted supplement, not a second parser.
+function rawTopologyFor(instanceRoot, slug, { readFile = fs.readFileSync } = {}) {
+  try {
+    const raw = JSON.parse(readFile(path.join(instanceRoot, 'config', 'update-subscriptions.json'), 'utf8'));
+    const row = (raw.instances || []).find((r) => r && (r.slug === slug || r.dir === slug));
+    if (!row) return {};
+    const out = {};
+    for (const k of ['versionUrl', 'deployTimer', 'deployService', 'backupDb', 'backupDir', 'registryPackage', 'pinMode']) {
+      if (typeof row[k] === 'string' && row[k]) out[k] = row[k];
+    }
+    return out;
+  } catch (_) { return {}; }
+}
+
+// Map a roster entry onto a go-live target. Returns what is MISSING rather than a
+// half-built target: an invalid target would be rejected by go-live anyway, and the
+// point of checking here is to fall back cleanly instead of failing the sweep.
+function goLiveTargetFor(inst, extra = {}) {
+  const e = { ...inst, ...extra };
+  const t = {
+    instanceDir: inst.dir,
+    service: inst.service,
+    healthUrl: inst.healthUrl,
+    versionUrl: e.versionUrl,
+  };
+  // deployTimer belongs HERE, not above. The normalizer yields `null` for an absent field,
+  // and an explicit `"deployTimer": null` survives JSON.stringify into --target-json, where
+  // go-live's validateTarget runs isSafeToken(null) on it and rejects the whole target. The
+  // optional loop drops falsy values, so a co-tenant simply omits the key — which is what
+  // "no pull-deploy timer to stop" actually means.
+  for (const [k, v] of Object.entries({
+    deployTimer: e.deployTimer,
+    deployService: e.deployService,
+    backupDb: e.backupDb,
+    backupDir: e.backupDir,
+    registryPackage: e.registryPackage,
+    pinMode: e.pinMode,
+    env: e.env,
+  })) if (v) t[k] = v;
+
+  const missing = GO_LIVE_REQUIRED.filter((k) => !t[k]);
+  return missing.length ? { ok: false, missing } : { ok: true, target: t };
+}
+
+// Does this target need CO-TENANT support from go-live.js? Two shapes do, and both are
+// rejected outright by a go-live.js predating task 1003521: a target with no `deployTimer`
+// fails its REQUIRED_FIELDS check, and one naming `pinMode` fails its unknown-field check.
+// Either way the run dies on a validation error instead of falling back — the failure mode
+// resolveGoLive exists to prevent.
+function needsCoTenantMode(target) {
+  return !!target && (!target.deployTimer || !!target.pinMode);
+}
+
+// go-live's PIN_MODES, mirrored for the same reason GO_LIVE_REQUIRED is — the lane acts on the pin
+// both BEFORE go-live is called and AFTER it returns, so an absent or unknown mode has to mean the
+// same thing on both sides of that boundary.
+const PIN_MODES = ['push', 'local-commit', 'leave-dirty'];
+const DEFAULT_PIN_MODE = 'push';
+
+// The pin policy is read from the ROSTER ENTRY, which is the operator's DECLARED INTENT — it does
+// not change with which engine happens to run. Deriving it from the go-live target instead would
+// silently revert a co-tenant to `push` on exactly the runs that fall back to a direct upgrade,
+// which is the customer's own repo and the one place a push must never land.
+function pinModeOf(source) {
+  const mode = (source && source.pinMode) || DEFAULT_PIN_MODE;
+  return { mode, valid: PIN_MODES.includes(mode) };
+}
+
+// What to do about a dirty pin found BEFORE the upgrade runs.
+//
+// Extracted because this is the THIRD place the lane writes the instance's pin, and all three were
+// wrong in the same way: each decided whether to push without asking what mode it was in. A named
+// decision can be tested; an `if` inline in a 250-line loop cannot, which is why this one shipped
+// broken past a green suite.
+//
+//   halt      — dirty with changes that are neither the pin nor this upgrade's own output: a
+//               human's work, never guess
+//   by-design — `leave-dirty`, where an uncommitted pin IS the steady state, not a leftover
+//   commit    — an actual leftover; `push` says whether it may leave this machine
+//
+// The order — dirt BEFORE mode — is deliberate and stays that way (task 1003968). A human's edit must
+// halt even under `leave-dirty`, which licenses the LANE's dirt, not a stranger's. What made
+// `by-design` unreachable was never this order: it was `other` swallowing the lane's own output, so
+// every mode saw a human's work after every upgrade. pinState's third bucket is the fix, and with it
+// this reads the way it always claimed to.
+function healDecision(pre, pinMode) {
+  if (!pre || !pre.repo || pre.clean) return { action: 'nothing' };
+  if (pre.other && pre.other.length) return { action: 'halt' };
+  if (pinMode === 'leave-dirty') return { action: 'by-design' };
+  return { action: 'commit', push: pinMode !== 'local-commit' };
+}
+
+// Resolve go-live.js the same way upgrade.js is resolved — the INSTANCE's own core
+// first, because that one is current by definition. go-live.js only exists from core
+// 1.19.310, so its ABSENCE is normal on an older instance and must fall back rather
+// than break the lane (the fail-closed detection rule from task 1003212).
+function resolveGoLive(instDir, { resolveFrom = coreModulePathFrom, readFile = fs.readFileSync, needsCoTenant = false } = {}) {
+  let p = null;
+  try { p = resolveFrom(instDir, 'scripts/gds/go-live.js'); } catch (_) { return null; }
+  if (!p) return null;
+  // EXISTING IS NOT ENOUGH. go-live.js arrived in 1.19.310 but could only drive a
+  // REMOTE box over ssh; the local mode this routine needs (--target-json + a target
+  // with no ssh host) came later. Calling the older one from here would fail on an
+  // unrecognised flag — so check for the capability, not the file. Same fail-closed
+  // rule as supportsCommitPin, for the same reason.
+  //
+  // Co-tenant mode is a SECOND capability on the same file, arriving later still (task
+  // 1003521), and it is probed ONLY when the target actually needs it — so an instance on a
+  // mid-generation core keeps the go-live path it already has for ordinary targets.
+  let src;
+  try { src = readFile(p, 'utf8'); } catch (_) { return null; }
+  if (!src.includes('--target-json')) return null;
+  if (needsCoTenant && !src.includes('pinMode')) return null;
+  return p;
+}
+
+// Pick the deploy engine for ONE instance, and say why when it is not go-live.
+//
+// Both callers — the dry run and the apply path — must agree, or the preview promises an
+// engine the real sweep will not use. They each re-derived it; the co-tenant probe gave them
+// a third thing to keep in step, so the decision lives here once. `raw` is returned because
+// the fallback branch reads the roster's versionUrl straight from it.
+function goLiveEngineFor(inst, instanceRoot, opts = {}) {
+  const raw = rawTopologyFor(instanceRoot, inst.slug);
+  const mapped = goLiveTargetFor(inst, raw);
+  if (!mapped.ok) return { script: null, raw, mapped, coTenant: false, why: `roster entry lacks ${mapped.missing.join(' + ')}` };
+  const coTenant = needsCoTenantMode(mapped.target);
+  const script = resolveGoLive(inst.dir, { ...opts, needsCoTenant: coTenant });
+  if (script) return { script, raw, mapped, coTenant, why: null };
+  return {
+    script: null, raw, mapped, coTenant,
+    why: coTenant
+      ? "this instance's core has no go-live.js with co-tenant support yet"
+      : "this instance's core has no go-live.js with local-target support yet",
+  };
+}
+
+// ── which upgrade.js to run ──────────────────────────────────────────────────────────────────────
+
+// Prefer the TARGET INSTANCE's own core over this control plane's vendored copy.
+//
+// The instance being upgraded always carries a current core (that is what "upgrade" means), whereas
+// the control plane's own pin is a separate plane that nobody bumps — it sat 305 releases behind and
+// that staleness silently disabled --commit-pin for the whole lane. Running the instance's own script
+// is also exactly what the manual runbook and scripts/gds/go-live.js do, so all three paths agree.
+function resolveUpgradeScript(instDir, { resolveFrom = coreModulePathFrom, fallback = null } = {}) {
+  let own = null;
+  try { own = resolveFrom(instDir, 'scripts/gds/upgrade.js'); } catch (_) { own = null; }
+  if (own) return { script: own, source: 'instance' };
+  if (fallback) return { script: fallback, source: 'control-plane' };
+  return { script: null, source: 'none' };
+}
+
+// Detect the flag rather than assuming it. An unsupported flag is SILENTLY IGNORED here (parseArgs is
+// an allowlist reader), and "silently ignored" is precisely the failure being fixed — so assuming
+// support would reintroduce the bug on any instance whose core predates the flag.
+function supportsCommitPin(scriptPath, readFile = fs.readFileSync) {
+  if (!scriptPath) return false;
+  try { return readFile(scriptPath, 'utf8').includes('--commit-pin'); }
+  catch (_) { return false; }
+}
+
+// The SECOND capability on the same file, probed separately and for a sharper reason than
+// supportsCommitPin's. On a co-tenant `--commit-pin` alone means commit AND PUSH, and the push
+// lands in the CUSTOMER's own repo — so a core old enough to have `--commit-pin` but not
+// `--pin-no-push` must not be handed the pair. An unsupported flag is silently ignored by
+// parseArgs, which would turn "commit locally" into exactly the push this mode forbids.
+function supportsPinNoPush(scriptPath, readFile = fs.readFileSync) {
+  if (!scriptPath) return false;
+  try { return readFile(scriptPath, 'utf8').includes('--pin-no-push'); }
+  catch (_) { return false; }
+}
+
+// Which pin flags the direct-upgrade fallback hands `bongos upgrade` — the THIRD place the lane
+// decides its pin policy, named for the same reason healDecision is: an `if` inline in a 250-line
+// loop cannot be tested, and this one shipped broken past a green suite.
+//
+// THE BUG IT WAS (task 1004122). The branch withheld --commit-pin on every mode but `push`, on the
+// reasoning that --commit-pin also PUSHES and a co-tenant's remote is the customer's own repo. But
+// `--pin-no-push` is exactly the "commit, do not push" it wanted, go-live's upgradeCommand() had
+// been sending that pair for `local-commit` all along, and the comment here already CLAIMED parity
+// with go-live. Withholding the flag left the `.claude/` that upgrade.js materializes on every bump
+// uncommitted, and the lane's own net can stage nothing but PIN_FILES — so its post-upgrade
+// commitPin() refused the tree as "a human's work" and every later sweep halted on the same files.
+//
+// Mirrors go-live.js upgradeCommand() mode for mode; tests/update_subscription_engine.mjs pins the
+// two against each other. `--pin-no-push` is PROBED, never assumed: parseArgs silently ignores an
+// unknown flag, so handing the pair to a core that predates it would turn "commit locally" into the
+// one push this mode exists to forbid.
+function pinFlagsFor({ pinMode, canCommitPin, canPinNoPush }) {
+  const noPush = pinMode !== 'push';
+  // Both non-default modes turn on --pin-no-push, and a core that would silently ignore it must
+  // be handed NOTHING — the pair degrades to a bare --commit-pin, which is the push into the
+  // customer's repo this whole function exists to prevent.
+  if (noPush && !canPinNoPush) return [];
+  return [
+    // leave-dirty commits nothing; --pin-no-push alone is what downgrades upgrade.js's
+    // "PIN NOT COMMITTED" alarm to a note, which is go-live's reason for sending it there.
+    ...(canCommitPin && pinMode !== 'leave-dirty' ? ['--commit-pin'] : []),
+    ...(noPush ? ['--pin-no-push'] : []),
+  ];
+}
+
+// The direct-upgrade fallback's CLEAN-TREE policy, which is a pin-mode decision like the flags above.
+//
+// Under `leave-dirty` the pin is left in the working tree BY DESIGN, so the second bump meets
+// upgrade.js's clean-tree pre-flight reading the first bump's own package.json as uncommitted work,
+// and refuses — the one-upgrade wedge again, from the other end of the lane. (The materialize waiver
+// that pre-flight gained in task 1004122 does not cover the pin files, and cannot: on every other
+// mode a dirty pin really is the thing that must stop a bump.) go-live.js's upgradeCommand() passes
+// --force on every mode for exactly this reason; the direct path needs it only where a dirty tree is
+// the operator's declared steady state, so that is the only place it goes.
+//
+// --force waives the clean-tree check and NOTHING else — module compatibility, the DB-identity
+// pre-check, the mandatory health check and auto-rollback all still run. The human-work guard is
+// upstream of this anyway: healDecision halts the instance before an upgrade is ever spawned when the
+// dirt is not the lane's.
+//
+// NOT probed, unlike --commit-pin and --pin-no-push, and the asymmetry is the point. parseArgs
+// silently ignores an unknown flag, so what matters is which way that silence fails: ignoring
+// --pin-no-push turns "commit locally" into a push into the customer's repo (a wrong ACTION, so it
+// must be probed), while ignoring --force leaves the bump refusing a dirty tree (a REFUSAL — loud,
+// and no worse than the status quo). Fail-closed means checking the flags whose absence would do
+// something, not every flag.
+function preflightFlagsFor(pinMode) {
+  return pinMode === 'leave-dirty' ? ['--force'] : [];
+}
+
+// ── the sweep ────────────────────────────────────────────────────────────────────────────────────
+
+// `instanceRoot` is the default roster root when no --instance is given: the subscribe.js shim passes
+// its own instance root; run directly, it is the working directory.
+function main({ instanceRoot: defaultRoot = process.cwd() } = {}) {
+  const apply = hasFlag('--apply');
+  const only = argOf('--only');
+  const instanceRoot = path.resolve(argOf('--instance') || defaultRoot);
+  const sweepingCoreUpgradeScript = path.join(__dirname, 'upgrade.js'); // fallback only: the upgrade.js of the core running this sweep
+  // Says which core is doing the sweeping, every run, so "is the box running current code?" is
+  // one journal line instead of an archaeology session (the gap task 1004307 was filed for).
+  let selfVersion = 'unknown';
+  try { selfVersion = require(path.join(__dirname, '..', '..', 'src', 'module-api.js')).CORE_VERSION || selfVersion; } catch (_) { /* a core without the doorway */ }
+  console.log(`update-sweep · running from ${path.resolve(__dirname, '..', '..')} (core ${selfVersion}) · roster ${instanceRoot}`);
+
+  const loaded = channel.loadSubscriptions({ instanceDir: instanceRoot });
+  const { source, present, error } = loaded;
+  if (error) console.error(`  ! ${path.relative(instanceRoot, source) || source}: ${error} — treating roster as empty.`);
+
+  // The rule set on /deploy wins over the roster's `channel` (task 1004468, ADR 0357). Read from the
+  // CONTROL PLANE's database — this process's own env, never an entry's `env`, which points at that
+  // instance's database. A core too old to carry the reader keeps the roster, as before.
+  const db = typeof channel.readDbChannels === 'function' ? channel.readDbChannels({ env: process.env }) : null;
+  const instances = db ? channel.applyDbChannels(loaded.instances, db) : loaded.instances;
+  if (db && !db.ok && instances.length) console.log(`  • update rules: read from the roster — ${db.reason}`);
+
+  const roster = only ? instances.filter((i) => i.slug === only || i.dir === only) : instances;
+  const mode = apply ? 'apply' : 'dry-run';
+  console.log(`core-update-subscription (${mode}) — ${roster.length} subscribed instance(s)${present ? '' : ' [no roster file — nothing subscribed]'}`);
+  for (const inst of roster) if (inst.channelNote) console.log(channel.channelLine(inst));
+  if (only && roster.length === 0) console.error(`  ! --only ${only} matched no subscribed instance`);
+
+  let upgraded = 0, skipped = 0, failed = 0, upToDate = 0, healed = 0;
+
+  for (const inst of roster) {
+    const label = inst.slug;
+    if (inst.channel === 'pinned') { console.log(`  • ${label}: pinned — skipped`); skipped++; continue; }
+
+    const installed = readInstalledCoreVersion(inst.dir);
+    if (!installed) { console.log(`  • ${label}: installed core version unknown (no node_modules/@bongos/core at ${inst.dir}) — skipped`); skipped++; continue; }
+
+    // Resolve the engine and the pin policy BEFORE anything touches the pin. Both are cheap and
+    // pure (a disk read of the roster plus a source probe), and the HEAL step below is itself a
+    // write to the instance's repo — so it has to know the policy it is writing under.
+    const engine = goLiveEngineFor(inst, instanceRoot);
+    const rawTopo = engine.raw;
+    const pin = pinModeOf(rawTopo);
+    if (!pin.valid) {
+      console.error(`  ! ${label}: roster entry names an unknown pinMode ${JSON.stringify(pin.mode)} (expected ${PIN_MODES.join(' | ')}) — skipped`);
+      console.error('      Refusing rather than defaulting: every unknown value would fall through to the PUSH branch, and on a co-tenant that push lands in the customer\'s own repo.');
+      skipped++; continue;
+    }
+    const pinMode = pin.mode;
+
+    // HEAL FIRST. A pin left uncommitted by an earlier sweep would make upgrade.js's clean-tree
+    // preflight abort this instance forever. Committing it here is what turns a permanent wedge into
+    // a self-correcting lane. Anything OTHER than the pin dirty is a human's work — halt, don't guess.
+    //
+    // EXCEPT under `leave-dirty`, where a dirty pin is not a leftover at all: it is the STEADY STATE
+    // this mode asks for. Healing it would commit and push the customer's own repo on the sweep after
+    // every successful upgrade — reliably, not just after a crash. go-live's dirty-checkout halt reads
+    // the CORE checkout, not the instance, so leaving it dirty wedges nothing.
+    //
+    // What THIS upgrade rewrites in this instance's tree, resolved once and threaded through every
+    // pin decision below — the guard, the heal and the post-upgrade net must not disagree about which
+    // paths the lane produced, which is exactly how they disagreed before (task 1003968).
+    const generated = laneGeneratedPaths(inst.dir);
+    const pre = pinState(inst.dir, spawnSync, generated);
+    const heal = healDecision(pre, pinMode);
+    if (heal.action === 'halt') {
+      console.error(`  ! ${label}: worktree not clean, and the changes are neither the pin nor this upgrade's own output (${pre.other.slice(0, 3).map((e) => e.file).join(', ')}) — skipped, a human needs to look`);
+      skipped++; continue;
+    }
+    if (heal.action === 'by-design') {
+      console.log(`  • ${label}: pin is uncommitted by design (pinMode leave-dirty) — nothing to heal`);
+    } else if (heal.action === 'commit') {
+      if (!apply) {
+        const leftover = [...pre.pin, ...pre.generated].map((e) => e.file);
+        console.log(`  → ${label}: would first commit a leftover uncommitted pin (${leftover.slice(0, 4).join(', ')}${leftover.length > 4 ? `, +${leftover.length - 4} more` : ''})`);
+      } else {
+        const r = commitPin({
+          dir: inst.dir,
+          message: `pin @bongos/core ${installed} (committed by the update lane — leftover from an earlier sweep)`,
+          push: heal.push,
+          generated,
+        });
+        if (!r.ok) {
+          console.error(`  ✖ ${label}: could not commit the leftover pin (${r.action}: ${r.reason}) — skipped; the next sweep will stall here too`);
+          failed++; continue;
+        }
+        if (r.committed) { healed++; console.log(`  ↺ ${label}: healed a leftover uncommitted pin from an earlier sweep`); }
+      }
+    }
+
+    // Ask the registry. NO CREDENTIAL IS INVOLVED: @bongos/core is public (ADR 0283), and
+    // fcea51ca deleted the env-fed .npmrc this line used to describe. Do not reintroduce one —
+    // the private era is exactly how this sweep died silently on 2026-08-25, reporting failed=0
+    // for three weeks because the unit passed no NPM_TOKEN, the .npmrc expanded to empty, and a
+    // skip is not a failure in the accounting below. Still run from the instance dir, which now
+    // only decides which registry config applies. Fail-soft: a registry error skips this
+    // instance, not the sweep.
+    const listed = channel.listAvailableVersions({ cwd: inst.dir, env: { ...process.env, ...inst.env } });
+    if (!listed.ok) { console.error(`  ! ${label}: could not list registry versions (${listed.error}) — skipped`); skipped++; continue; }
+
+    const target = channel.resolveChannelTarget({ installed, channel: inst.channel, available: listed.versions });
+    if (!target) { console.log(`  ✓ ${label}: up to date on ${installed} (channel: ${inst.channel})`); upToDate++; continue; }
+
+    const { script: upgradeScript, source: scriptSource } = resolveUpgradeScript(inst.dir, { fallback: sweepingCoreUpgradeScript });
+    if (!upgradeScript) { console.error(`  ! ${label}: no upgrade.js resolvable for this instance — skipped`); skipped++; continue; }
+    const canCommitPin = supportsCommitPin(upgradeScript);
+    const canPinNoPush = supportsPinNoPush(upgradeScript);
+
+    if (!apply) {
+      const dryEngine = engine.script
+        ? `go-live.js (backup + ${engine.coTenant ? 'co-tenant pin mode' : 'deploy-timer guard'} + box-side read-back)`
+        : `direct bongos upgrade — ${engine.why}`;
+      // The pin flags come from the SAME function the apply path spreads, so the preview cannot
+      // promise a policy the real sweep will not use (task 1004122). It read `canCommitPin` alone
+      // before, and so said "--commit-pin" for a co-tenant that was never going to get it.
+      const dryPinFlags = [...pinFlagsFor({ pinMode, canCommitPin, canPinNoPush }), ...preflightFlagsFor(pinMode)];
+      console.log(`  → ${label}: would upgrade ${installed} → ${target} (channel: ${inst.channel}, registry, via the ${scriptSource} core${dryPinFlags.length ? `, ${dryPinFlags.join(' ')}` : ''})`);
+      console.log(`      engine: ${dryEngine}`);
+      continue;
+    }
+
+    console.log(`  ↑ ${label}: upgrading ${installed} → ${target} (channel: ${inst.channel}) …`);
+
+    // PREFER go-live.js. Running `bongos upgrade` directly gets the bump but none of the
+    // surrounding rigour: no pg_dump and no guard around the pull-deploy timer (which fires
+    // every ~2 min doing `git reset --hard` and can revert a pin mid-flight). The machine
+    // deploying unattended every night should not have weaker checks than a human deploying
+    // by hand.
+    //   The read-back gap is CLOSED as of task 1002884: upgrade.js no longer treats a failed
+    // restart as a warning, and it reads the live process's coreVersion back from /version
+    // rather than trusting a health poll that the still-running OLD core would also answer
+    // (idea 1000682). go-live is still preferred for the backup + timer guard.
+    //
+    // The CHANNEL decision stays here: go-live is told exactly which version to take, so
+    // the patch-only policy still bounds what may be applied.
+    let res;
+    if (engine.script) {
+      const glArgs = [engine.script, '--target-json', JSON.stringify(engine.mapped.target), '--to', target, '--apply', '--no-divergence'];
+      res = spawnSync(process.execPath, glArgs, { stdio: 'inherit', env: { ...process.env, ...inst.env } });
+    } else {
+      console.log(`    • falling back to a direct upgrade — ${engine.why}. No backup and no deploy-timer guard (the served-version read-back does run — task 1002884).`);
+      const upArgs = [upgradeScript, '--to', target, '--registry', '--instance', inst.dir, '--note', `auto-subscription (${inst.channel})`];
+      if (inst.service) upArgs.push('--service', inst.service);
+      if (inst.healthUrl) upArgs.push('--health-url', inst.healthUrl);
+      // task 1002884: hand the bump the same independent read-back go-live uses. upgrade.js now
+      // derives /version from the health URL on its own, but the roster already carries the exact
+      // endpoint — passing it makes the check STRICT (an unreadable endpoint fails the bump rather
+      // than warning), which is the right posture for a lane nobody is watching.
+      //   Read it from rawTopo, NOT from the normalized `inst`. This branch is reached precisely
+      // WHEN the normalizer came up short (`mapped.ok === false`, often for versionUrl itself), so
+      // trusting `inst.versionUrl` here would drop strict mode in exactly the stale-control-plane
+      // case the comment above rawTopologyFor() documents — the silent degradation this task exists
+      // to remove. `inst` is kept as a fallback for a roster whose entry is keyed unusually.
+      const versionUrl = rawTopo.versionUrl || inst.versionUrl;
+      if (versionUrl) upArgs.push('--version-url', versionUrl);
+      upArgs.push(...pinFlagsFor({ pinMode, canCommitPin, canPinNoPush }));
+      // …and the clean-tree half of the same wiring: under leave-dirty the previous bump's pin is
+      // still in the tree by design, and without this the second bump is refused by upgrade.js's
+      // pre-flight. go-live.js sends --force on every mode; here it goes only where dirt is declared.
+      upArgs.push(...preflightFlagsFor(pinMode));
+      // Auto-rollback stays ON (do NOT pass --no-rollback-on-failure): a bad patch reverts itself.
+      res = spawnSync(process.execPath, upArgs, { stdio: 'inherit', env: { ...process.env, ...inst.env } });
+    }
+
+    // RE-PROBE, rather than reusing the set from before the bump. The pre-upgrade answer came from
+    // the core that was installed THEN, so a skill the NEW core adds — or one it withdraws — is absent
+    // from it, would land in `other`, and would wedge the lane on the very next sweep: the same defect
+    // one release later. After the bump the instance carries the core that actually wrote these files,
+    // which is the only thing that can name them. (On a rolled-back bump the OLD core is back, and its
+    // answer is the right one for the tree a rollback leaves.)
+    //
+    // What re-probing gives is the FILE SET, which materializeClaude walks off coreRoot at call time
+    // — so this really is the newly-installed core's `.claude/`. What it does not give is the new
+    // core's materialize CODE: node caches a module by resolved path, and the path did not change.
+    // A materialize algorithm that changed shape mid-lane is a second-order gap, and closing it would
+    // mean either a half-purged module graph (new file, old transitive deps) or a child process per
+    // instance per sweep. The primary path is upgrade.js's own --commit-pin, which uses the real
+    // post-install materialize result; this is the backstop under it.
+    const generatedAfter = laneGeneratedPaths(inst.dir);
+
+    if (res.status !== 0) {
+      console.error(`  ✖ ${label}: upgrade to ${target} exited ${res.status == null ? '(signal)' : res.status} — see output above (auto-rollback runs on install/migrate/health failure)`);
+      // A rollback restores the OLD pin, which can itself leave the tree dirty. Tidy it so one bad
+      // patch does not wedge every future sweep.
+      const after = pinState(inst.dir, spawnSync, generatedAfter);
+      if (after.repo && !after.clean && !after.other.length && pinMode !== 'leave-dirty') {
+        commitPin({
+          dir: inst.dir,
+          message: `pin @bongos/core ${installed} (restored after a failed auto-upgrade to ${target})`,
+          push: pinMode !== 'local-commit',
+          generated: generatedAfter,
+        });
+      }
+      failed++; continue;
+    }
+
+    // VERIFY THE END STATE. The exit code says the upgrade ran; only a clean tree says the bump will
+    // SURVIVE. If --commit-pin did its job this is a no-op; if it silently did not, this is the net.
+    //
+    // But the net must not FIGHT the target's own pin policy (task 1003843). `leave-dirty` means the
+    // bump lives in the working tree by design, and committing it here would be the net undoing the
+    // very thing pinMode was added to express; `local-commit` means the pin may be committed but must
+    // never reach the customer's own remote. Only the default `push` mode wants the full treatment —
+    // and it is the only one with a pull-deploy timer waiting to revert an unpushed pin.
+    if (pinMode === 'leave-dirty') {
+      console.log(`  ✓ ${label}: upgraded to ${target} (pin left in the working tree — pinMode leave-dirty)`);
+      upgraded++; continue;
+    }
+
+    const post = commitPin({
+      dir: inst.dir,
+      message: `pin @bongos/core ${target} (was ${installed})`,
+      push: pinMode !== 'local-commit',
+      generated: generatedAfter,
+    });
+    if (!post.ok) {
+      console.error(`  ✖ ${label}: upgraded to ${target} BUT THE PIN IS NOT DURABLE (${post.action}: ${post.reason}).`);
+      if (pinMode === 'local-commit') {
+        console.error('      The bump lives only in this instance\'s working tree, and the next sweep will stall on it.');
+        console.error(`      Fix by hand: git -C ${inst.dir} add ${PIN_FILES.join(' ')} && git -C ${inst.dir} commit -m "pin @bongos/core ${target}"`);
+      } else {
+        console.error('      The next pull-deploy reset will revert this bump, and the next sweep will stall on the dirty tree.');
+        console.error(`      Fix by hand: git -C ${inst.dir} add ${PIN_FILES.join(' ')} && git -C ${inst.dir} commit -m "pin @bongos/core ${target}" && git -C ${inst.dir} push`);
+      }
+      failed++; continue;
+    }
+
+    console.log(`  ✓ ${label}: upgraded to ${target}${post.committed ? ' (pin committed by the lane)' : ''}`);
+    upgraded++;
+  }
+
+  console.log(`\ncore-update-subscription: upgraded=${upgraded} up-to-date=${upToDate} skipped=${skipped} failed=${failed}${healed ? ` healed=${healed}` : ''} (${mode})`);
+  return failed > 0 ? 1 : 0;
+}
+
+if (require.main === module) {
+  try { process.exit(main()); }
+  catch (e) { console.error(`core-update-subscription: fatal — ${e && e.message ? e.message : e}`); process.exit(1); }
+}
+
+module.exports = { main, coreModulePathFrom, CORE_PKG_NAMES, pinState, laneGeneratedPaths, commitPin, preflightFlagsFor, resolveUpgradeScript, supportsCommitPin, supportsPinNoPush, pinFlagsFor, goLiveTargetFor, resolveGoLive, goLiveEngineFor, needsCoTenantMode, pinModeOf, healDecision, rawTopologyFor, PIN_FILES, PIN_MODES, GO_LIVE_REQUIRED };