@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/go-live.js

@@ -1,1071 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/go-live.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/go-live.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-// scripts/gds/go-live.js — run a go-live as ONE command instead of forty tool calls.
-//
-// WHY THIS EXISTS (task 1003189). Gate 3 of docs/recipes/core-release-pipeline.md —
-// moving an instance's core pin, the only act that makes shipped work visible to
-// users — is a DETERMINISTIC sequence that was nonetheless re-derived from prose by
-// hand every time. The 2026-08-23 go-live took 101 tool calls / 211 model turns at a
-// mean 143K context (29.7M cache-read tokens, ~69% of the bill). About four of those
-// calls were engineering; the rest were lookups: what is on main, what is live, which
-// PRs are green, what does the runbook say, what did the box just print. Cost here is
-// turns x context, so collapsing the mechanical legs into one call is the whole fix.
-//
-// WHAT IT IS NOT. Not a new deploy mechanism, and not a privileged surface of its own.
-// Every leg is an EXISTING proven part and this file only sequences them and reports:
-//   - deploy-divergence.js check()  — live coreVersion vs main, UNRELEASED vs UNDEPLOYED
-//   - the published registry        — proof a release carrying the work actually exists
-//   - `bongos upgrade --registry --commit-pin` — the pin move, health-gated, auto-rollback ON
-// It is also NOT task 1003159: that gives the OWNER a door onto deploy without a shell
-// (an authenticated control + an ADR settling the authority model). This is the AGENT
-// side — a session that ALREADY holds the shell should spend two calls here, not forty.
-//
-// HALT, DO NOT GUESS. Every condition that needs judgement stops the run and names
-// itself: a red CI check, unreleased commits, a registry missing the target, a dirty
-// tree, a failed health check, an uncommitted pin. Those are exactly the parts worth
-// an agent's attention; this script's job is to make everything AROUND them free.
-//
-// NO HOST TOPOLOGY LIVES HERE. This file ships in the portable core, so the ssh alias,
-// paths, service names and health URLs come from a host-owned config (see --help for
-// the schema) that is NOT publishable — the same shape as config/update-subscriptions.json.
-// A core that named one instance's box would not be a core.
-//
-// Usage:
-//   node scripts/gds/go-live.js                        # PLAN only — read-only, the default
-//   node scripts/gds/go-live.js --apply                # actually move the pin
-//   node scripts/gds/go-live.js --to 1.19.306          # pin a target instead of main's CORE_VERSION
-//   node scripts/gds/go-live.js --verify-marker src/x.js=needle
-//                                                      # refuse a target that lacks the change
-//   node scripts/gds/go-live.js --target web --json
-//
-// Exit codes: 0 plan clean / apply succeeded · 1 halted (reason printed) · 2 bad invocation.
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const { arg, hasFlag, apiCall } = require('./cli-lib');
-const divergence = require('./deploy-divergence.js');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const DEFAULT_CONFIG = 'config/go-live.json';
-
-// ---------------------------------------------------------------------------
-// Validation. Everything below reaches a remote shell that runs as root, so it
-// is checked against a strict allowlist BEFORE interpolation — never quoted and
-// hoped for. A config file is host-owned, but "host-owned" is not "trusted to
-// contain shell metacharacters".
-// ---------------------------------------------------------------------------
-
-const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
-// Deliberately narrow: POSIX-portable path/identifier characters only. No spaces,
-// no quotes, no $ ` \ ; & | < > ( ) newline — i.e. nothing with meaning to a shell.
-//
-// `~` IS allowed, and is the one deliberate exception. It is shell-interpreted, but
-// it cannot start a subshell, chain a command, or redirect — the runbook's backup dir
-// is literally `~/backups`, and under `sudo -u <owner> -H` that expansion to the
-// owner's home is the BEHAVIOUR WE WANT, not a leak. Everything with control meaning
-// stays out.
-const SAFE_TOKEN_RE = /^[A-Za-z0-9._@:/+=~-]+$/;
-const SAFE_ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-
-function isSafeToken(v) {
-  return typeof v === 'string' && v.length > 0 && v.length <= 512 && SAFE_TOKEN_RE.test(v);
-}
-
-// The fields a target must carry, and the ones it may. Unknown keys are reported
-// rather than ignored: a typo'd `healthURL` that silently disables the health gate
-// is precisely the class of quiet failure this pipeline keeps being bitten by.
-// `ssh` is NOT required: a target with no ssh host is LOCAL (the box driving itself).
-//
-// `deployTimer` is NOT required either — that is CO-TENANT MODE (task 1003521). A
-// provisioned instance under /srv/<host>/<slug> has no pull-deploy timer at all (only
-// its <slug>-db-backup.timer), so requiring the field forced an operator to invent a
-// unit name that the script would then try to `systemctl stop`. Absent, the stop and
-// the restart are simply skipped: there is no `reset --hard` to race.
-const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl'];
-const OPTIONAL_FIELDS = ['ssh', 'local', 'deployTimer', 'deployService', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage', 'pinMode'];
-
-// How the bump is made durable — the other half of co-tenant mode (task 1003521).
-//
-// On the PLATFORM instance the repo of record is ours, and a pull-deploy
-// `git reset --hard origin/main` reverts any pin that was not PUSHED (task 1002712 —
-// thirteen releases were lost exactly that way). So the default is `push`.
-//
-// On a provisioned co-tenant the repo of record is the CUSTOMER's own GitHub repo, so
-// that push is both wrong and, in practice, uncredentialed. With no pull-deploy timer
-// nothing will revert the pin, so a local commit is enough to leave the tree clean:
-//   local-commit — commit the pin, do not push it
-//   leave-dirty  — do not commit at all; the bump lives in the working tree by design
-const PIN_MODES = ['push', 'local-commit', 'leave-dirty'];
-const DEFAULT_PIN_MODE = 'push';
-
-function pinModeOf(target) {
-  return (target && target.pinMode) || DEFAULT_PIN_MODE;
-}
-
-function validateTarget(name, t) {
-  const errors = [];
-  if (!t || typeof t !== 'object' || Array.isArray(t)) return [`target "${name}" is not an object`];
-
-  for (const f of REQUIRED_FIELDS) {
-    if (t[f] === undefined) errors.push(`target "${name}" is missing required field "${f}"`);
-  }
-  const known = new Set([...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]);
-  for (const k of Object.keys(t)) {
-    if (!known.has(k)) errors.push(`target "${name}" has unknown field "${k}" (typo? known: ${[...known].sort().join(', ')})`);
-  }
-  for (const [k, v] of Object.entries(t)) {
-    if (k === 'env') {
-      if (typeof v !== 'object' || v === null || Array.isArray(v)) { errors.push(`target "${name}".env must be an object`); continue; }
-      for (const [ek, ev] of Object.entries(v)) {
-        if (!SAFE_ENV_KEY_RE.test(ek)) errors.push(`target "${name}".env key "${ek}" is not a valid environment-variable name`);
-        if (!isSafeToken(String(ev))) errors.push(`target "${name}".env.${ek} contains characters that are unsafe in a shell`);
-      }
-      continue;
-    }
-    if (!known.has(k)) continue;
-    if (k === 'local') { // a flag, never interpolated into a command
-      if (typeof v !== 'boolean') errors.push(`target "${name}".local must be true or false`);
-      continue;
-    }
-    if (k === 'pinMode') { // an enum, never interpolated into a command
-      if (!PIN_MODES.includes(v)) errors.push(`target "${name}".pinMode must be one of ${PIN_MODES.join(', ')} (got ${JSON.stringify(v)})`);
-      continue;
-    }
-    if (!isSafeToken(v)) errors.push(`target "${name}".${k} contains characters that are unsafe in a shell (got ${JSON.stringify(v)})`);
-  }
-  return errors;
-}
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-const CONFIG_TEMPLATE = `{
-  "defaultTarget": "web",
-  "targets": {
-    "web": {
-      "ssh": "my-box",                                  // ssh alias or user@host
-      "instanceDir": "/home/me/my-instance",            // the instance repo (holds the pin)
-      "service": "my-instance.service",                 // systemd unit to restart
-      "healthUrl": "http://127.0.0.1:3002/healthz",     // box-side, NOT the apex
-      "versionUrl": "http://127.0.0.1:3002/version",    // box-side truth read back after
-      "deployTimer": "my-deploy.timer",                 // optional: pull-deploy timer (its reset --hard is the hazard)
-      "deployService": "my-deploy.service",             // optional: forced tick proves the pin stuck
-      "runAs": "me",                                    // optional: unprivileged owner of the instance
-      "backupDb": "mydb",                               // optional: pg_dump before the bump
-      "backupDir": "~/backups",
-      "env": { "PGDATABASE": "mydb" },                  // optional: load-bearing for migrate
-      "registryPackage": "@bongos/core",
-      "pinMode": "push"                                 // optional: push (default) | local-commit | leave-dirty
-    },
-    "a-co-tenant": {
-      // A PROVISIONED instance: no pull-deploy timer to stop, and the repo of record
-      // is the customer's own GitHub repo — so the pin is committed, never pushed.
-      "ssh": "my-box",
-      "instanceDir": "/srv/my-host/their-slug",
-      "service": "their-slug.service",
-      "healthUrl": "http://127.0.0.1:3101/healthz",
-      "versionUrl": "http://127.0.0.1:3101/version",
-      "runAs": "their-slug",
-      "env": { "PGDATABASE": "their_slug" },
-      "pinMode": "local-commit"
-    }
-  }
-}`;
-
-function loadConfig({ configPath, readFile = fs.readFileSync, exists = fs.existsSync } = {}) {
-  const rel = configPath || DEFAULT_CONFIG;
-  const abs = path.isAbsolute(rel) ? rel : path.join(ROOT, rel);
-  if (!exists(abs)) {
-    return { error: 'NO_TARGET_CONFIG', path: rel, template: CONFIG_TEMPLATE };
-  }
-  let raw;
-  try { raw = readFile(abs, 'utf8'); } catch (e) { return { error: 'CONFIG_UNREADABLE', path: rel, detail: e.message }; }
-  let parsed;
-  // Tolerate // comments so the shipped template can stay self-documenting.
-  try { parsed = JSON.parse(raw.replace(/^\s*\/\/.*$/gm, '').replace(/(:\s*"[^"]*"|:\s*[\d.]+|[{[,])\s*\/\/.*$/gm, '$1')); }
-  catch (e) { return { error: 'CONFIG_MALFORMED', path: rel, detail: e.message }; }
-  if (!parsed || typeof parsed !== 'object' || !parsed.targets || typeof parsed.targets !== 'object') {
-    return { error: 'CONFIG_MALFORMED', path: rel, detail: 'expected a top-level "targets" object' };
-  }
-  return { ok: true, path: rel, config: parsed };
-}
-
-function selectTarget(config, name) {
-  const wanted = name || config.defaultTarget || Object.keys(config.targets)[0];
-  if (!wanted) return { error: 'UNKNOWN_TARGET', detail: 'the config declares no targets' };
-  const t = config.targets[wanted];
-  if (!t) {
-    return { error: 'UNKNOWN_TARGET', detail: `no target "${wanted}" (have: ${Object.keys(config.targets).join(', ') || 'none'})` };
-  }
-  const errors = validateTarget(wanted, t);
-  if (errors.length) return { error: 'CONFIG_INVALID', detail: errors.join('; ') };
-  return { ok: true, name: wanted, target: t };
-}
-
-// ---------------------------------------------------------------------------
-// Remote execution. One ssh round-trip per phase, script fed on STDIN so no
-// value is ever interpolated into an ssh ARGUMENT (which would be re-parsed by
-// the remote login shell). Values are validated above; this is the second layer.
-// ---------------------------------------------------------------------------
-
-// Privilege preamble for any phase that touches systemd.
-//
-// Over ssh these phases run as ROOT, so `systemctl stop …` just works — which is what
-// they originally assumed. Run LOCALLY by the nightly lane they run as the instance
-// OWNER, where the same line fails with "Interactive authentication required" and the
-// timer is never stopped: the pull-deploy `git reset --hard` then stays armed for the
-// whole upgrade, which is the exact hazard the stop exists to remove. Deciding at RUN
-// time keeps one script correct for both callers.
-const SUDO_PREAMBLE = 'SUDO=""; [ "$(id -u)" -eq 0 ] || SUDO="sudo -n"';
-
-// A target is LOCAL when it names no ssh host: the phases run through a local shell
-// instead of a remote one. Everything else — the phases, the halts, the reporting —
-// is byte-identical, which is the point: one deployment engine, reachable from a
-// laptop (remote) or from the box itself (local, how the nightly lane uses it).
-// Without this the unattended path would need its own second implementation, and the
-// two would drift — which is exactly how the nightly deploy ended up with weaker
-// checks than the manual one (task 1003219).
-function isLocalTarget(target) {
-  return !target || !target.ssh;
-}
-
-function remote(target, script, { run = spawnSync, timeoutMs = 900000 } = {}) {
-  const [cmd, args] = isLocalTarget(target)
-    ? ['bash', ['-s']]
-    : ['ssh', ['-o', 'ConnectTimeout=20', '-o', 'BatchMode=yes', target.ssh, 'bash', '-s']];
-  const res = run(cmd, args, {
-    input: script, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024,
-  });
-  if (!res || res.error) return { ok: false, status: null, stdout: '', stderr: res && res.error ? res.error.message : 'spawn failed' };
-  return { ok: res.status === 0, status: res.status, stdout: res.stdout || '', stderr: res.stderr || '' };
-}
-
-// `sudo -u <user> -H env K=V … <cmd>` — the shape every runbook entry uses. Returns
-// a string safe to embed because every component was allowlist-validated.
-//
-// `sudo -u <user> -H env K=V … <cmd>` — the shape every runbook entry uses. Returns
-// a string safe to embed because every component was allowlist-validated.
-//
-// Only NON-secret configuration (PGDATABASE, HOME) travels in the plain `env K=V` list —
-// seeing those in a log is useful rather than harmful.
-//
-// This used to take a `needsNpm` option wrapping the command in a preamble that DERIVED an
-// npm credential on the far side, because sudo logs its whole invocation and there was no way
-// to hand a privileged child a secret without journalling it (task 1003218). @bongos/core is
-// public (task 1003872), so the deploy path needs no npm credential at all and the whole
-// hazard is gone rather than mitigated (task 1003878).
-function asOwner(target, cmd) {
-  const inner = cmd;
-  const envPairs = Object.entries(target.env || {}).map(([k, v]) => `${k}=${v}`);
-  if (!target.runAs) {
-    const joined = envPairs.join(' ');
-    return `${joined ? `env ${joined} ` : ''}${inner}`.trim();
-  }
-  const joined = [...envPairs, `HOME=/home/${target.runAs}`].join(' ');
-  return `sudo -u ${target.runAs} -H env ${joined} ${inner}`.trim();
-}
-
-// POSIX single-quote a value for embedding in a shell command.
-function shq(s) {
-  return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-// The content proof, as a shell snippet.
-//
-// TWO bugs live here in the obvious version, and both FAIL OPEN — they report "your
-// change is missing" for a version that has it, which reads exactly like the real
-// ADR-0161 trap and sends you chasing a later release that does not exist:
-//
-//  1. Do NOT derive the tarball name. `npm pack @bongos/core` writes
-//     `bongos-core-<v>.tgz`, and hand-rolled `tr`/`sed` on the package name gets the
-//     leading dashes wrong — so `tar` reads a file that is not there and greps 0 hits.
-//     npm PRINTS the filename it wrote; use that.
-//  2. Pass the path + needle as base64 and match with `grep -F`. Interpolating them
-//     lets a quote break out of the command, and an unescaped regex metacharacter in
-//     the needle silently changes what is being matched.
-//
-// `set -o pipefail` is deliberately absent: `grep -c` exits 1 on zero matches, which
-// is a legitimate answer here, not a failure.
-function markerProbe(pkg, version, marker) {
-  const p64 = Buffer.from(marker.path, 'utf8').toString('base64');
-  const n64 = Buffer.from(marker.needle, 'utf8').toString('base64');
-  return [
-    `set -u`,
-    // Run from a neutral cwd. `npm pack <spec>` behaves differently inside a
-    // project directory, and an earlier section's `cd` used to leak this far —
-    // which made the pack fail and read as "your change is missing".
-    `cd /tmp`,
-    `P=$(echo ${p64} | base64 -d)`,
-    `N=$(echo ${n64} | base64 -d)`,
-    `ERR=$(mktemp)`,
-    `T=$(npm pack ${pkg}@${version} --pack-destination /tmp 2>"$ERR" | tail -1)`,
-    // Say WHY it failed. A bare PACK_FAILED cost four diagnostic round-trips once.
-    `if [ -z "$T" ] || [ ! -f "/tmp/$T" ]; then echo "PACK_FAILED $(tail -2 "$ERR" | tr '\\n' ' ')"; rm -f "$ERR"; exit 0; fi`,
-    `rm -f "$ERR"`,
-    // `grep -c` PRINTS 0 *and* exits 1 on no match, so a bare `|| echo 0` emits TWO
-    // lines ("0\n0") — which parses to NaN and compares equal to nothing, so an
-    // absent marker silently passed. Emit exactly one line.
-    `tar -xzOf "/tmp/$T" "package/$P" 2>/dev/null | grep -c -F -- "$N" | head -1`,
-  ].join('; ');
-}
-
-// Read the marker section back. Fails CLOSED: anything that is not a clean count is
-// 'PACK_FAILED' (could not check), never a 0 that would read as a confident "absent"
-// — and never a NaN that silently compares equal to nothing and lets the run proceed.
-function parseMarkerHits(raw) {
-  const s = String(raw == null ? '' : raw).trim();
-  if (!s || s.includes('PACK_FAILED')) return 'PACK_FAILED';
-  const first = s.split('\n')[0].trim();
-  if (!/^\d+$/.test(first)) return 'PACK_FAILED';
-  return Number(first);
-}
-
-// Does this process sit inside a git repo that knows the given ref?
-function gitRefExists(ref, { run = spawnSync } = {}) {
-  const r = run('git', ['rev-parse', '--verify', '--quiet', ref], { cwd: ROOT, encoding: 'utf8' });
-  return !!r && !r.error && r.status === 0;
-}
-
-// Refresh origin/main before reading anything from it.
-//
-// deploy-divergence reads CORE_VERSION at the local `origin/main` REF, and a ref is
-// only as fresh as the last fetch. A worktree that has sat for an hour resolves a
-// target version that is already superseded — and everything downstream agrees with
-// it, because every check is consistent with the same stale ref. This actually
-// happened mid-build: a parallel session merged twice, the plan targeted the older
-// carrier, and only a manual fetch revealed it. Default ON; --no-fetch opts out.
-//
-// A fetch failure is NOT fatal: a box or a tarball checkout legitimately has no
-// remote, and deploy-divergence already falls back to HEAD there.
-function refreshMain({ run = spawnSync } = {}) {
-  const r = run('git', ['fetch', 'origin', 'main', '--quiet'], { cwd: ROOT, encoding: 'utf8', timeout: 60000 });
-  if (!r || r.error || r.status !== 0) {
-    return { ok: false, reason: (r && (r.stderr || '').trim().split('\n').pop()) || 'fetch failed' };
-  }
-  return { ok: true };
-}
-
-// Ask the LIVE instance about its own artist gate (ADR 0241, task 1003575).
-//
-// The instance answers because it is the only party that can: the policy arrives
-// in its web.env and its board holds the reviews. This script only decides what to
-// do with the answer, and the refusal sentence is composed there rather than here
-// so one wording serves every caller.
-//
-// NEVER THROWS. Every failure — no session, a 401, an instance too old to carry
-// the route, a network error — resolves to { unread: <why> }, which renders as a
-// note. See artistGateEntries for why an unread gate is not a halt.
-// The FULL path, not a bare `/artist-gate`. cli-lib's apiCall composes
-// `${base}${urlPath}` verbatim and `base` is the instance ORIGIN — every other
-// caller in this repo spells `/api/bongos/…` by hand for the same reason. Getting
-// this wrong is silent in the worst way: the request lands on the origin's
-// catch-all, the gate reports itself unread on every instance including the ones
-// that fully support it, and the deploy check never fires. Exported so a test can
-// pin it against the route's REAL mount point in the generated OpenAPI spec.
-const ARTIST_GATE_PATH = '/api/bongos/artist-gate';
-// The levels a real answer can carry — mirrored from src/bongos/artist-gate.js
-// rather than imported, because this script also runs from an INSTALLED core on a
-// box where that path is inside the package, and a require of it here would make
-// the deploy tool depend on the server's own tree. Pinned by the same test that
-// pins the path.
-const ARTIST_GATE_LEVELS = ['off', 'advisory', 'strict'];
-
-async function readArtistGate(call = apiCall) {
-  try {
-    const res = await call('GET', ARTIST_GATE_PATH, null, { allowUnauthenticated: true });
-    if (res.status === 404) return { unread: `this instance does not serve ${ARTIST_GATE_PATH} — it predates ADR 0241` };
-    // A 5xx is a gate that EXISTS and BROKE, which is not the same class of
-    // unknown as "no session" or "too old to have the route". The gate is
-    // fail-closed by design, so the one case where we know it is there and
-    // cannot get an answer from it HALTS rather than degrading to a note —
-    // otherwise a broken read is a quieter way past the gate than the owner's
-    // own override, which is the asymmetry worth refusing.
-    if (res.status >= 500) return { broken: `GET ${ARTIST_GATE_PATH} returned ${res.status}` };
-    if (!res.ok) return { unread: `GET ${ARTIST_GATE_PATH} returned ${res.status}` };
-    const d = res.data || {};
-    // A 200 that is not this route's answer — an SPA index.html served by a
-    // catch-all, a proxy's own page — must read as UNREAD, never as a gate that
-    // holds nothing. "I got a 200 from something" is the one failure that would
-    // wave a deploy through in silence, which is worse than any halt.
-    if (!ARTIST_GATE_LEVELS.includes(d.mode)) {
-      return { unread: `GET ${ARTIST_GATE_PATH} answered ${res.status} but not with a gate — got mode ${JSON.stringify(d.mode)}` };
-    }
-    return { mode: d.mode, since: d.since || null, holds: !!d.holds, reviews: d.reviews || [], halt: d.halt || null };
-  } catch (e) {
-    return { unread: (e && e.message) || 'request failed' };
-  }
-}
-
-// Parse a `key=value` marker into its parts. Kept pure + exported: the marker is
-// the answer to the trap that the release current when your fix merges usually
-// does NOT contain your fix (ADR 0161 carriers bump on their own cadence).
-function parseMarker(spec) {
-  if (!spec) return null;
-  const i = String(spec).indexOf('=');
-  if (i <= 0 || i === spec.length - 1) return { error: 'expected --verify-marker <path>=<needle>' };
-  return { path: spec.slice(0, i), needle: spec.slice(i + 1) };
-}
-
-// ---------------------------------------------------------------------------
-// Planning. Pure given its inputs, so the halt matrix tests without a box.
-// ---------------------------------------------------------------------------
-
-const HALTS = {
-  DIRTY_CHECKOUT: 'the core checkout has uncommitted changes — CORE_VERSION here cannot be trusted to match what was released',
-  DIVERGENCE_UNDETERMINED: 'could not determine what is live',
-  UNRELEASED_ON_MAIN: 'main carries commits past the last CORE_VERSION bump — no pin can reach them',
-  ALREADY_LIVE: 'live is already at the target',
-  REGISTRY_MISSING_TARGET: 'the registry does not carry the target version',
-  MARKER_ABSENT: 'the target version does not contain the change you named',
-  MARKER_UNCHECKED: 'could not inspect the target version — the content proof did not run',
-  BOX_TREE_DIRTY: 'the instance repo on the box has uncommitted changes',
-  LIVE_AHEAD: 'live is AHEAD of the target',
-  ARTIST_REVIEW_UNRESOLVED: 'an unresolved artist review holds this deploy (ADR 0241)',
-  ARTIST_GATE_UNREADABLE: 'the artist gate is there and answering with an error — this deploy cannot tell whether a review holds it',
-};
-
-// The artist gate (ADR 0241, task 1003575). This is the ONE place in the deploy
-// path that the artist's authority touches, and the boundary is the whole point:
-// `strict` may delay a PIN MOVE and nothing else. Nothing in the ship, grade,
-// merge or land path consults this — a builder's work is credited and on `main`
-// long before a go-live runs, which is what lets this gate coexist with ADR 0162
-// instead of recreating the strand it retired.
-//
-// It reads a STATE, not a verdict: the instance reports which artist review tasks
-// are still open, never whether an artist approved anything. See
-// src/bongos/artist-gate.js, which composes the refusal sentence this renders.
-// The halt and/or note one gate read contributes. Shared by planGoLive and by the
-// gitless (on-box, no checkout) path, so a lane that skips the git-derived checks
-// does not also silently skip the gate — the deploy is the same deploy either way.
-// PURE.
-function artistGateEntries(gate) {
-  const halts = [];
-  const notes = [];
-  if (gate && gate.halt) {
-    halts.push({ code: 'ARTIST_REVIEW_UNRESOLVED', message: gate.halt.message, detail: gate.halt.detail });
-  }
-  // A gate that is THERE and BROKEN halts. This is the fail-closed half: we know
-  // the instance has the route, so "it 500s" is a gate we cannot get an answer
-  // from, not a gate that does not apply. Its remedy is the instance's own logs,
-  // and it is named as such rather than as an artist problem.
-  if (gate && gate.broken) {
-    halts.push({
-      code: 'ARTIST_GATE_UNREADABLE',
-      message: HALTS.ARTIST_GATE_UNREADABLE,
-      detail: `${gate.broken}. The route exists, so this is a fault on the instance, not a missing feature — read its logs for the GET /artist-gate failure. Deploying past it would mean moving the pin without knowing whether a review holds it.`,
-    });
-  }
-  // NOT KNOWING is a different thing again, and it must not render as "nothing
-  // holds". It is a note rather than a halt on purpose: a go-live is already
-  // deliberate and reversible, and halting every deploy because there is no CLI
-  // session — or because the instance predates the route entirely — would brick
-  // the pin with no task id to release against, which is the blocked-state-that-
-  // does-not-explain-itself failure ADR 0241 §4 names.
-  if (gate && gate.unread) {
-    notes.push({
-      code: 'ARTIST_GATE_UNREAD',
-      message: `could not read this instance's artist gate (${gate.unread}) — if the project runs artist_gate 'strict', an unresolved artist review may be holding this deploy and this plan cannot see it`,
-    });
-  }
-  return { halts, notes };
-}
-
-function planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased = false, artistGate = null }) {
-  const halts = [];
-  const notes = [];
-
-  // Evaluated FIRST, before the git-derived checks, because it is the halt whose
-  // remedy takes longest: a review someone has to do is not a thing you fix in the
-  // next ten seconds, and finding it out after the other five checks passed is
-  // strictly worse than finding it out now.
-  const gate = artistGateEntries(artistGate);
-  halts.push(...gate.halts);
-  notes.push(...gate.notes);
-
-  if (dirtyCheckout) halts.push({ code: 'DIRTY_CHECKOUT', message: HALTS.DIRTY_CHECKOUT, detail: dirtyCheckout });
-
-  if (!div || div.undetermined) {
-    halts.push({ code: 'DIVERGENCE_UNDETERMINED', message: HALTS.DIVERGENCE_UNDETERMINED, detail: div && div.reason });
-    return { halts, notes, targetVersion, from: null };
-  }
-
-  const from = div.live && div.live.coreVersion;
-
-  // UNRELEASED is not the same failure as UNDEPLOYED and must not be conflated:
-  // no pin, at any version, can reach a commit no release carries. Deploying
-  // anyway is the "textbook-clean go-live that changed nothing" trap.
-  if (div.hasUnreleased) {
-    const c = div.unreleased && div.unreleased.count;
-    const entry = {
-      code: 'UNRELEASED_ON_MAIN',
-      message: HALTS.UNRELEASED_ON_MAIN,
-      detail: `${c} commit(s) on main since the last bump. The publish-on-merge job can also FAIL on a benign push race — check \`gh run list --workflow publish.yml\` for a failure before assuming this is just timing.`,
-    };
-    if (allowUnreleased) notes.push({ ...entry, downgraded: true }); else halts.push(entry);
-  }
-
-  if (from && targetVersion) {
-    const cmp = divergence.cmpSemver(from, targetVersion);
-    if (cmp === 0) halts.push({ code: 'ALREADY_LIVE', message: HALTS.ALREADY_LIVE, detail: `live and target are both ${from}` });
-    else if (cmp > 0) halts.push({ code: 'LIVE_AHEAD', message: HALTS.LIVE_AHEAD, detail: `live ${from} > target ${targetVersion}` });
-  }
-
-  return { halts, notes, from, targetVersion, target };
-}
-
-// ---------------------------------------------------------------------------
-// Rendering
-// ---------------------------------------------------------------------------
-
-const BAR = '  ──────────────────────────────────────────────────────────';
-
-function renderPlan(p, { targetName, configPath } = {}) {
-  const L = [];
-  L.push('');
-  L.push(`  Go-live plan · ${targetName || 'target'}${configPath ? ` · ${configPath}` : ''}`);
-  L.push(BAR);
-  L.push(`  live now      ${p.from || '(unknown)'}`);
-  L.push(`  target        ${p.targetVersion || '(unresolved)'}`);
-  if (p.marker) L.push(`  verify        ${p.marker.path} contains "${p.marker.needle}"`);
-  if (p.registry) L.push(`  registry      ${p.registry.ok ? `carries ${p.targetVersion}` : 'MISSING'}`);
-  // The gate's state is worth a line even when it holds nothing: "artist gate
-  // advisory" is the answer to "why did nothing stop?", and a reader who cannot
-  // see the level has to go and find it.
-  if (p.artistGate && p.artistGate.mode) {
-    const open = (p.artistGate.reviews || []).length;
-    L.push(`  artist gate   ${p.artistGate.mode}${open ? ` · ${open} unresolved review${open === 1 ? '' : 's'}` : ' · nothing open'}`);
-  }
-  L.push('');
-  for (const n of p.notes || []) L.push(`  ⚠ ${n.code} — ${n.message}`);
-  if (!p.halts.length) {
-    L.push('  ✓ no halt conditions — re-run with --apply to move the pin');
-  } else {
-    L.push(`  ✖ ${p.halts.length} halt condition(s) — this go-live will NOT proceed:`);
-    for (const h of p.halts) {
-      L.push(`      ${h.code} — ${h.message}`);
-      if (h.detail) L.push(`        ${h.detail}`);
-    }
-  }
-  L.push('');
-  return L.join('\n');
-}
-
-// Pull the lines a human needs out of a failed phase. A report that says "exit 1"
-// and swallows the tool's own words costs a whole extra round-trip to re-run the
-// command by hand — which is the exact cost this script exists to remove.
-function failureExcerpt(raw, max = 12) {
-  if (!raw) return [];
-  const text = `${raw.stdout || ''}\n${raw.stderr || ''}`;
-  const lines = text.split('\n').map((l) => l.trimEnd()).filter(Boolean);
-  // Prefer the lines that carry a diagnosis over the trailing noise.
-  const signal = lines.filter((l) => /error|fail|✖|✗|denied|not found|404|refus|rollback|↩|!\s/i.test(l));
-  return (signal.length ? signal : lines).slice(-max);
-}
-
-function renderReport(r) {
-  const L = [];
-  L.push('');
-  L.push(`  Go-live · ${r.targetName}`);
-  L.push(BAR);
-  L.push(`  ${r.from} → ${r.to}`);
-  for (const step of r.steps || []) L.push(`  ${step.ok ? (step.warn ? '⚠' : '✓') : '✖'} ${step.name}${step.detail ? ` — ${step.detail}` : ''}`);
-
-  // A refused rehearsal moved nothing, so the pin and read-back lines below would only
-  // alarm: "pin committed NO — the next reset will revert this bump" about a bump that
-  // never started (task 1004306).
-  if (r.failedAt === 'PREFLIGHT') {
-    const ex = failureExcerpt(r.raw);
-    if (ex.length) {
-      L.push('');
-      L.push('  what the upgrade said:');
-      for (const l of ex) L.push(`    ${l}`);
-    }
-    L.push('');
-    L.push(`  Nothing changed — still on ${r.from || 'the current core'}. No timer was stopped and no backup was written.`);
-    L.push('');
-    return L.join('\n');
-  }
-
-  if (!r.ok) {
-    const ex = failureExcerpt(r.raw);
-    if (ex.length) {
-      L.push('');
-      L.push(`  what ${r.failedAt ? r.failedAt.toLowerCase() : 'it'} actually said:`);
-      for (const l of ex) L.push(`    ${l}`);
-    }
-    if (r.rolledBack) {
-      L.push('');
-      L.push('  The instance auto-rolled-back and is serving the PREVIOUS core — it is not broken.');
-    }
-  }
-
-  L.push('');
-  L.push(`  live reads back   ${r.liveVersion || '(unread)'}`);
-  const mode = r.pinMode || DEFAULT_PIN_MODE;
-  if (mode === 'leave-dirty') L.push('  pin               left in the working tree (pinMode leave-dirty)');
-  else if (r.pinCommitted) L.push(`  pin committed     yes${mode === 'local-commit' ? ' (local commit — this target\'s remote is not ours to push)' : ''}`);
-  else L.push('  pin committed     NO — the next pull-deploy reset will revert this bump');
-  L.push('');
-  return L.join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// Phases
-// ---------------------------------------------------------------------------
-
-// Registry proof + optional content proof, in ONE round-trip. The registry is still
-// consulted ON THE BOX — not because auth lives there (the package is public now), but
-// because the box's answer is the one that matters: its network, its resolver, its cache.
-function probeRemote(target, targetVersion, marker, opts = {}) {
-  const pkg = target.registryPackage || '@bongos/core';
-  const script = `
-set -uo pipefail
-echo "##REGISTRY##"
-${asOwner(target, `npm view ${pkg}@${targetVersion} version`)} 2>&1 | tail -1
-echo "##TREE##"
-( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain | head -20 )
-echo "##INSTALLED##"
-${asOwner(target, `node -e "console.log(require('${target.instanceDir}/node_modules/${pkg}/package.json').version)"`)} 2>&1 | tail -1
-${marker ? `echo "##MARKER##"
-${asOwner(target, `sh -c ${shq(markerProbe(pkg, targetVersion, marker))}`)}` : ''}
-echo "##END##"
-`;
-  const res = remote(target, script, opts);
-  const section = (n) => {
-    const m = res.stdout.split(`##${n}##`)[1];
-    return m === undefined ? null : m.split('##')[0].trim();
-  };
-  // `npm view` on a missing version exits non-zero and its last line is a path to a
-  // debug log — useless in a report. Anything that is not a version is reported as
-  // "not published", which is the fact the reader actually needs.
-  const registryRaw = section('REGISTRY');
-  const registryVersion = registryRaw && SEMVER_RE.test(registryRaw) ? registryRaw : null;
-  return {
-    reachable: res.ok || res.stdout.includes('##END##'),
-    raw: res,
-    registry: { ok: registryVersion === targetVersion, reported: registryVersion, raw: registryRaw },
-    boxTreeDirty: (section('TREE') || '') !== '',
-    boxTreeDetail: section('TREE') || '',
-    installed: section('INSTALLED'),
-    // null = not asked · 'PACK_FAILED' = could not check (NOT the same as absent) · a count.
-    markerHits: marker ? parseMarkerHits(section('MARKER')) : null,
-    markerError: marker ? (String(section('MARKER') || '').replace(/^PACK_FAILED\s*/, '').trim() || null) : null,
-  };
-}
-
-// The `bongos upgrade` invocation, as its own function so the pin-mode wiring is
-// assertable without a box.
-//
-// Both non-default modes pass --pin-no-push, which is what tells upgrade.js the repo of
-// record is not ours: `local-commit` pairs it with --commit-pin (commit, no push), and
-// `leave-dirty` sends it alone, which downgrades upgrade.js's "PIN NOT COMMITTED" alarm
-// to a note. That alarm is correct on a pull-deploy instance and misleading here, and an
-// alarm an operator learns to ignore is worse than no alarm.
-function upgradeCommand(target, targetVersion) {
-  const mode = pinModeOf(target);
-  return [
-    `./node_modules/.bin/bongos upgrade`,
-    `--to ${targetVersion}`, '--registry',
-    `--instance ${target.instanceDir}`,
-    `--service ${target.service}`,
-    `--health-url ${target.healthUrl}`,
-    ...(mode === 'leave-dirty' ? [] : ['--commit-pin']),
-    ...(mode === 'push' ? [] : ['--pin-no-push']),
-    '--force',
-  ].join(' ');
-}
-
-// Whether the post-bump pin state is what this target ASKED for. Under `leave-dirty` a
-// modified working tree is the configured outcome, so reporting it as the durability
-// failure it is on a pull-deploy instance would make a correct co-tenant run read as
-// broken — the one place the three modes must not share a verdict.
-function pinStep(mode, pinDirty, head) {
-  if (mode === 'leave-dirty') {
-    return {
-      name: 'pin left in the working tree (pinMode leave-dirty)',
-      ok: true,
-      detail: pinDirty ? 'package.json/-lock MODIFIED by design — this target has no pull-deploy to revert it' : (head || null),
-    };
-  }
-  return {
-    name: mode === 'local-commit' ? 'pin committed locally (not pushed)' : 'pin committed + pushed',
-    ok: !pinDirty,
-    detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (head || null),
-  };
-}
-
-// How many pre-upgrade dumps a backupDir keeps (task 1004306). Nothing pruned them, so
-// the directory grew by one dump per attempt for as long as the lane ran: 37 dumps and
-// 1.7 GB on cloudbongos.com by 2026-09-26, at about ONE attempt a day. The count, not an age,
-// is the bound because the cadence is what varies — ten is ten at daily or at every
-// fifteen minutes. These are the extra copies taken right before a pin move; the
-// nightly backup (db-backup-nightly.sh, 30 days) is the history and is not touched.
-const PRE_UPGRADE_KEEP = 10;
-// Exactly the name Phase A writes: pre-<version>-<YYYYMMDDTHHMMSSZ>.sql.gz. A looser
-// `pre-*` would also take a dump an operator named by hand — the box has a
-// `pre-lane-sweep-<ts>.sql.gz` in that directory, and it is not ours to delete.
-const D8 = '[0-9]'.repeat(8);
-const D6 = '[0-9]'.repeat(6);
-const PRE_UPGRADE_GLOB = `pre-[0-9]*-${D8}T${D6}Z.sql.gz`;
-
-// Delete all but the newest PRE_UPGRADE_KEEP pre-upgrade dumps and print how many went.
-// Newest by mtime, never by name: the name sorts 1.19.99 after 1.19.100. It runs only
-// after a dump succeeded, so a run of failures can never empty the directory, and the
-// dump just written is always the newest and always kept. No `$` anywhere, so the
-// outer shell that feeds this to `bash -c` expands nothing in it.
-function pruneCommand(dir, keep = PRE_UPGRADE_KEEP) {
-  return `bash -c "cd ${dir} && ls -1t -- ${PRE_UPGRADE_GLOB} 2>/dev/null | tail -n +${keep + 1} | xargs -r rm -v -- | wc -l"`;
-}
-
-// Read the prune section back into a step. A prune that could not run is a WARNING,
-// not a failure: the dump it follows is good, and refusing the upgrade over a full
-// cleanup would trade a real deploy for tidiness. It still says so on screen.
-function pruneStep(section, keep = PRE_UPGRADE_KEEP) {
-  const name = `prune old pre-upgrade backups (keep the newest ${keep})`;
-  const s = String(section == null ? '' : section).trim();
-  if (/^\d+$/.test(s)) return { name, ok: true, detail: s === '0' ? 'nothing to remove' : `removed ${s}` };
-  return { name, ok: true, warn: true, detail: `could not prune${s ? ` (${s.split('\n').pop()})` : ''} — the directory will keep growing until this is fixed` };
-}
-
-function applyGoLive(target, targetName, targetVersion, from, opts = {}) {
-  const pkg = target.registryPackage || '@bongos/core';
-  const pinMode = pinModeOf(target);
-  const steps = [];
-  const upgrade = upgradeCommand(target, targetVersion);
-
-  // Phase 0 — ask the upgrade whether it WILL go, before anything is stopped or copied
-  // (task 1004306). `bongos upgrade --dry-run` runs every refusal the real bump has —
-  // the artist gate, module compatibility, the database identity, the downgrade guard —
-  // and returns before it changes anything. Phase A used to come first, so on
-  // cloudbongos.com (2026-09-26 17:10 and 17:15 UTC) each attempt the artist gate
-  // refused had already stopped the deploy timer and written a 65 MB dump: one a day at
-  // the daily cadence, a full disk in about three days at every fifteen minutes.
-  // runGoLive's own gate read did not stop those runs either, and left no trace of what
-  // it saw: on --apply a plan with no halts is never printed, notes included. The bump's
-  // pre-flight asks the instance directly, and it was the first thing to say no.
-  const rehearsal = remote(target, `
-set -uo pipefail
-${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade} --dry-run"`)}
-`, opts);
-  steps.push({
-    name: 'pre-flight (the upgrade, rehearsed with --dry-run)',
-    ok: rehearsal.ok,
-    detail: rehearsal.ok ? null : 'refused — nothing was stopped and nothing was backed up',
-  });
-  if (!rehearsal.ok) return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'PREFLIGHT', refused: true, raw: rehearsal };
-
-  // Phase A — stop the pull-deploy timer, then back up. The timer's `reset --hard`
-  // is the hazard: it would revert an uncommitted pin mid-flight. A co-tenant has no
-  // such timer (see REQUIRED_FIELDS), so there is nothing to stop and no hazard.
-  //
-  // The dump must FAIL when pg_dump fails. `pg_dump | gzip > f` without pipefail
-  // reports gzip's success, leaving a 20-byte file that reads as a backup — harmless
-  // while nothing pruned, but the prune below keeps the newest ten, so a streak of
-  // those would retire every real dump (task 1004306). A failed dump removes its file
-  // and fails the phase, which stops the go-live before the pin moves: a bump with no
-  // backup behind it is not one to make unattended. $TS is expanded once by this
-  // script so the dump and its cleanup name the same file.
-  const backupDir = target.backupDir || '~/backups';
-  const dumpFile = `${backupDir}/pre-${targetVersion}-$TS.sql.gz`;
-  const backup = target.backupDb
-    ? asOwner(target, `bash -c "set -o pipefail; mkdir -p ${backupDir} && { pg_dump ${target.backupDb} | gzip > ${dumpFile} || { rm -f ${dumpFile}; exit 1; }; }"`)
-    : 'echo "(no backupDb configured — skipping)"';
-  // `|| echo`: under `set -e` a failed prune would otherwise fail the whole phase and
-  // stop a deploy whose backup is already safely on disk (see pruneStep).
-  const prune = target.backupDb
-    ? `echo "##PRUNE##"; ${asOwner(target, pruneCommand(backupDir))} || echo "prune exited non-zero"`
-    : '';
-  const phaseA = remote(target, `
-set -euo pipefail
-${SUDO_PREAMBLE}
-echo "##TIMER##"; ${target.deployTimer
-    ? `$SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true`
-    : 'echo "(no deployTimer configured — no pull-deploy to stop)"'}
-TS="$(date -u +%Y%m%dT%H%M%SZ)"
-echo "##BACKUP##"; ${backup}
-${prune}
-echo "##END##"
-`, opts);
-  steps.push({
-    name: target.deployTimer ? `stop ${target.deployTimer} + backup` : 'backup (no pull-deploy timer)',
-    ok: phaseA.ok,
-    detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop(),
-  });
-  if (!phaseA.ok) {
-    // The timer may already be stopped — Phase A stops it before the dump, and a dump
-    // can now fail on its own (above). Put it back, as a failed upgrade does below.
-    if (target.deployTimer) remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
-    return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'PREPARE', raw: phaseA };
-  }
-  if (target.backupDb) {
-    const m = (phaseA.stdout || '').split('##PRUNE##')[1];
-    steps.push(pruneStep(m === undefined ? null : m.split('##')[0]));
-  }
-
-  // Phase B — the upgrade itself. --commit-pin makes the bump durable against the
-  // pull-deploy reset; auto-rollback stays ON (do NOT pass --no-rollback-on-failure).
-  const phaseB = remote(target, `
-set -uo pipefail
-${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`)}
-`, opts);
-  const rolledBack = /rolled back/i.test(phaseB.stdout + phaseB.stderr);
-  steps.push({
-    name: `upgrade ${from} → ${targetVersion}`,
-    ok: phaseB.ok && !rolledBack,
-    detail: rolledBack ? 'AUTO-ROLLBACK ran — the health check failed after restart' : (phaseB.ok ? null : `exit ${phaseB.status}`),
-  });
-  if (!phaseB.ok || rolledBack) {
-    // Restart the timer even on failure — leaving it stopped silently disables
-    // the instance's pull-deploy until someone notices. Nothing was stopped on a
-    // co-tenant, so there is nothing to put back.
-    if (target.deployTimer) remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
-    return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
-  }
-
-  // Phase C — restart the timer, force one tick, and read back the BOX-SIDE truth.
-  // The apex may sit behind basic_auth and its HTML rides a CDN, so the apex is
-  // not evidence; 127.0.0.1 is.
-  const phaseC = remote(target, `
-set -uo pipefail
-${SUDO_PREAMBLE}
-${target.deployTimer ? `echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}` : ''}
-echo "##PIN##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain -- package.json package-lock.json )
-echo "##HEAD##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git log -1 --format='%h %s' )
-${target.deployService ? `echo "##TICK##"; $SUDO systemctl start ${target.deployService} || true; $SUDO journalctl -u ${target.deployService} -n 20 --no-pager | tail -8` : ''}
-echo "##VERSION##"; curl -s --max-time 20 ${target.versionUrl} | head -c 400
-echo ""
-echo "##INSTALLED##"; ${asOwner(target, `node -e "console.log(require('${target.instanceDir}/node_modules/${pkg}/package.json').version)"`)} 2>&1 | tail -1
-echo "##END##"
-`, opts);
-  const section = (n) => {
-    const m = phaseC.stdout.split(`##${n}##`)[1];
-    return m === undefined ? null : m.split('##')[0].trim();
-  };
-  const pinDirty = (section('PIN') || '') !== '';
-  const installed = section('INSTALLED');
-  let liveVersion = null;
-  try { liveVersion = JSON.parse(section('VERSION') || '{}').coreVersion || null; } catch { liveVersion = null; }
-
-  if (target.deployTimer) steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
-  steps.push(pinStep(pinMode, pinDirty, section('HEAD')));
-  steps.push({ name: 'installed package version', ok: installed === targetVersion, detail: installed === targetVersion ? installed : `reports ${installed}, expected ${targetVersion}` });
-  steps.push({ name: 'live reads back (box-side)', ok: liveVersion === targetVersion, detail: liveVersion === targetVersion ? liveVersion : `reports ${liveVersion}, expected ${targetVersion}` });
-
-  const ok = steps.every((s) => s.ok);
-  return { ok, steps, from, to: targetVersion, targetName, pinMode, liveVersion, installed, pinCommitted: !pinDirty, raw: phaseC };
-}
-
-// ---------------------------------------------------------------------------
-// CLI
-// ---------------------------------------------------------------------------
-
-function usage() {
-  console.log(`
-go-live — move an enrolled instance's core pin, as one command.
-
-  node scripts/gds/go-live.js                     PLAN only (read-only, the default)
-  node scripts/gds/go-live.js --apply             move the pin
-  node scripts/gds/go-live.js --to <version>      target a version explicitly
-  node scripts/gds/go-live.js --verify-marker <path>=<needle>
-                                                  refuse a target that lacks the change
-  node scripts/gds/go-live.js --target <name>     pick a target from the config
-  node scripts/gds/go-live.js --config <path>     default: ${DEFAULT_CONFIG}
-  node scripts/gds/go-live.js --allow-unreleased  downgrade UNRELEASED_ON_MAIN to a warning
-  node scripts/gds/go-live.js --no-fetch          skip the origin/main refresh (default: fetch)
-  node scripts/gds/go-live.js --target-json '{…}' pass a target inline instead of a config file
-  node scripts/gds/go-live.js --no-divergence     skip the git-derived checks (needs --to)
-  node scripts/gds/go-live.js --json              machine-readable
-
-CO-TENANT TARGETS. A provisioned instance has no pull-deploy timer and its repo of
-record is the customer's own, so omit "deployTimer" (the stop/restart is skipped) and
-set "pinMode": "local-commit" (the pin is committed, never pushed). "leave-dirty"
-leaves the bump in the working tree; "push" (the default) is the platform instance.
-
-Host topology is NOT baked into the core. ${DEFAULT_CONFIG} (host-owned, not published):
-
-${CONFIG_TEMPLATE}
-`);
-}
-
-async function main() {
-  if (hasFlag('--help') || hasFlag('-h')) { usage(); return 0; }
-
-  const json = hasFlag('--json');
-  const apply = hasFlag('--apply');
-  const allowUnreleased = hasFlag('--allow-unreleased');
-
-  // An inline target lets a CALLER drive this without inventing a second host-owned
-  // config file beside the one it already has. The nightly lane already holds a roster
-  // entry; making it also maintain config/go-live.json would be two sources of truth
-  // for one box, which is how they drift.
-  const inline = arg('--target-json');
-  if (inline) {
-    let parsed;
-    try { parsed = JSON.parse(inline); }
-    catch (e) { console.error(`  go-live: --target-json is not valid JSON — ${e.message}`); return 2; }
-    const errors = validateTarget('inline', parsed);
-    if (errors.length) {
-      if (json) { console.log(JSON.stringify({ ok: false, halt: 'CONFIG_INVALID', detail: errors.join('; ') }, null, 2)); return 1; }
-      console.error(`\n  go-live: CONFIG_INVALID — ${errors.join('; ')}\n`);
-      return 1;
-    }
-    return runGoLive({ target: parsed, targetName: arg('--target') || 'inline', configPath: '--target-json', json, apply, allowUnreleased });
-  }
-
-  const cfg = loadConfig({ configPath: arg('--config') });
-  if (cfg.error) {
-    if (json) { console.log(JSON.stringify({ ok: false, halt: cfg.error, path: cfg.path, detail: cfg.detail }, null, 2)); return 1; }
-    console.error(`\n  go-live: ${cfg.error} — ${cfg.path}${cfg.detail ? `\n  ${cfg.detail}` : ''}`);
-    if (cfg.error === 'NO_TARGET_CONFIG') {
-      console.error(`\n  This file is host-owned and deliberately not shipped in the core.\n  Create it with your box's topology:\n\n${CONFIG_TEMPLATE}\n`);
-    }
-    return 1;
-  }
-
-  const sel = selectTarget(cfg.config, arg('--target'));
-  if (sel.error) {
-    if (json) { console.log(JSON.stringify({ ok: false, halt: sel.error, detail: sel.detail }, null, 2)); return 1; }
-    console.error(`\n  go-live: ${sel.error} — ${sel.detail}\n`);
-    return 1;
-  }
-  const { target, name: targetName } = sel;
-  return runGoLive({ target, targetName, configPath: cfg.path, json, apply, allowUnreleased });
-}
-
-async function runGoLive({ target, targetName, configPath, json, apply, allowUnreleased }) {
-  const marker = parseMarker(arg('--verify-marker'));
-  if (marker && marker.error) { console.error(`  go-live: ${marker.error}`); return 2; }
-
-  // Resolve the target version: an explicit --to, else CORE_VERSION on main.
-  let targetVersion = arg('--to');
-  if (targetVersion && !SEMVER_RE.test(targetVersion)) { console.error(`  go-live: --to "${targetVersion}" is not a version`); return 2; }
-
-  // Is there a core GIT CHECKOUT to reason about at all?
-  //
-  // Every git-derived signal — the target read from origin/main, the UNRELEASED halt,
-  // the dirty-checkout halt — presumes this process is running inside a core repo.
-  // The nightly lane is NOT: it runs on the box, against an installed package, and it
-  // resolves its target from the REGISTRY under a channel policy instead. Running the
-  // git checks there would halt every sweep on a condition that does not apply.
-  //
-  // So the git legs are SKIPPED only when both are true: there is no resolvable
-  // origin/main, AND the caller named the version explicitly. A missing checkout with
-  // no --to is still an error — silently inventing a target is exactly the class of
-  // guess this script exists to refuse.
-  // "Am I in a SOURCE checkout?" is `.git` AT OUR ROOT — not "is there a git repo
-  // somewhere above me". The installed core package lives inside the INSTANCE's repo
-  // and ships its own src/module-api.js, so a naive `git rev-parse HEAD` succeeds
-  // there and CORE_VERSION resolves — against the instance repo's main, which is a
-  // meaningless answer delivered confidently. That is the failure this check avoids.
-  const hasCheckout = fs.existsSync(path.join(ROOT, '.git'));
-  const gitless = (!hasCheckout || hasFlag('--no-divergence')) && !!targetVersion;
-
-  const fetched = (gitless || hasFlag('--no-fetch')) ? { ok: false, skipped: true } : refreshMain();
-  const div = gitless ? null : await divergence.check({ base: arg('--url') });
-  if (!targetVersion) targetVersion = div && div.onMain;
-  if (!targetVersion || !SEMVER_RE.test(targetVersion)) {
-    console.error(`  go-live: could not resolve a target version${hasCheckout ? ` (read ${JSON.stringify(targetVersion)} from main)` : ' — this is not a core source checkout, so pass --to <version>'}`);
-    return 1;
-  }
-
-  const dirtyRes = gitless ? { status: 1 } : spawnSync('git', ['status', '--porcelain'], { cwd: ROOT, encoding: 'utf8' });
-  const dirtyCheckout = dirtyRes.status === 0 && (dirtyRes.stdout || '').trim() ? (dirtyRes.stdout || '').trim().split('\n').slice(0, 5).join(', ') : null;
-
-  // Always read, and deliberately NOT skippable by a flag. ADR 0241 §3 names one
-  // escape hatch — the project OWNER's override-request, rationale required and
-  // audit-logged — and a `--skip` here would be a second authority path that any
-  // builder with the shell could take silently, which is exactly the shape that
-  // ADR rejects. An unread gate already degrades to a note; that is the only
-  // by-pass, and it says so on screen.
-  const artistGate = await readArtistGate();
-
-  const gitlessGate = artistGateEntries(artistGate);
-  const plan = gitless
-    ? {
-      halts: gitlessGate.halts,
-      notes: [
-        { code: 'NO_CORE_CHECKOUT', message: `no core git checkout here — target ${targetVersion} was given explicitly, so the git-derived checks (unreleased-on-main, dirty tree) are skipped` },
-        ...gitlessGate.notes,
-      ],
-      from: null,
-      targetVersion,
-      target,
-    }
-    : planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased, artistGate });
-  plan.artistGate = artistGate;
-  plan.marker = marker;
-  if (!fetched.ok && !fetched.skipped) {
-    // Say so rather than silently planning off a ref of unknown age.
-    plan.notes.push({ code: 'MAIN_NOT_FETCHED', message: `could not refresh origin/main (${fetched.reason}) — the target below is read from a ref of unknown age` });
-  }
-
-  // Probe the box only once the local picture is worth acting on — an ssh
-  // round-trip to confirm a plan that already has a halt is wasted.
-  if (!plan.halts.length) {
-    const probe = probeRemote(target, targetVersion, marker);
-    plan.registry = probe.registry;
-    // With no source checkout there is no git-derived `from`; the installed version on
-    // the box IS the truth, and the probe just read it.
-    if (gitless && probe.installed) {
-      plan.from = probe.installed;
-      if (probe.installed === targetVersion) {
-        plan.halts.push({ code: 'ALREADY_LIVE', message: HALTS.ALREADY_LIVE, detail: `installed and target are both ${targetVersion}` });
-      }
-    }
-    if (!probe.reachable) {
-      plan.halts.push({ code: 'BOX_UNREACHABLE', message: `could not reach ${target.ssh}`, detail: (probe.raw.stderr || '').trim().split('\n').pop() });
-    } else {
-      if (!probe.registry.ok) {
-        plan.halts.push({
-          code: 'REGISTRY_MISSING_TARGET', message: HALTS.REGISTRY_MISSING_TARGET,
-          detail: `npm reports ${probe.registry.reported ? JSON.stringify(probe.registry.reported) : 'not published'} for ${target.registryPackage || '@bongos/core'}@${targetVersion}. A version bumped on main but never published leaves main's code reachable by no pin — check \`gh run list --workflow publish.yml\` for a failed run.`,
-        });
-      }
-      if (probe.boxTreeDirty) {
-        plan.halts.push({ code: 'BOX_TREE_DIRTY', message: HALTS.BOX_TREE_DIRTY, detail: probe.boxTreeDetail.split('\n').slice(0, 5).join(', ') });
-      }
-      if (marker && probe.markerHits === 'PACK_FAILED') {
-        // "Could not check" must never render as "absent" — that reads exactly like
-        // the real trap and sends you chasing a version that does not exist.
-        plan.halts.push({
-          code: 'MARKER_UNCHECKED', message: HALTS.MARKER_UNCHECKED,
-          detail: `could not download ${target.registryPackage || '@bongos/core'}@${targetVersion} to inspect it${probe.markerError ? `: ${probe.markerError}` : ''}. This is NOT evidence the change is missing — fix the fetch, or drop --verify-marker and verify by hand.`,
-        });
-      } else if (marker && probe.markerHits === 0) {
-        plan.halts.push({
-          code: 'MARKER_ABSENT', message: HALTS.MARKER_ABSENT,
-          detail: `${targetVersion} does not contain "${marker.needle}" in ${marker.path}. The carrier sitting on main when your fix merged was usually cut BEFORE it (ADR 0161) — try the next version.`,
-        });
-      }
-    }
-  }
-
-  if (!apply || plan.halts.length) {
-    if (json) { console.log(JSON.stringify({ ok: !plan.halts.length, mode: apply ? 'halted' : 'plan', targetName, ...plan }, null, 2)); }
-    else { console.log(renderPlan(plan, { targetName, configPath })); }
-    return plan.halts.length ? 1 : 0;
-  }
-
-  const result = applyGoLive(target, targetName, targetVersion, plan.from);
-  if (json) console.log(JSON.stringify(result, null, 2));
-  else console.log(renderReport(result));
-  return result.ok ? 0 : 1;
-}
-
-if (require.main === module) {
-  main().then((c) => { process.exitCode = c; }).catch((e) => {
-    console.error(`go-live: fatal — ${e && e.message ? e.message : e}`);
-    process.exitCode = 1;
-  });
-}
-
-module.exports = {
-  loadConfig, selectTarget, validateTarget, planGoLive, artistGateEntries, readArtistGate, ARTIST_GATE_PATH, ARTIST_GATE_LEVELS,
-  parseMarker, parseMarkerHits,
-  renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, refreshMain, isLocalTarget, gitRefExists, SUDO_PREAMBLE,
-  applyGoLive, upgradeCommand, pinStep, pinModeOf, pruneCommand, pruneStep, PRE_UPGRADE_KEEP, PRE_UPGRADE_GLOB,
-  CONFIG_TEMPLATE, HALTS, SEMVER_RE, PIN_MODES, DEFAULT_PIN_MODE,
-};
+require('../bongos/forwarder.js').forward(module, 'go-live.js');