@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/go-live.js

@@ -0,0 +1,1071 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/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/bongos/go-live.js                        # PLAN only — read-only, the default
+//   node scripts/bongos/go-live.js --apply                # actually move the pin
+//   node scripts/bongos/go-live.js --to 1.19.306          # pin a target instead of main's CORE_VERSION
+//   node scripts/bongos/go-live.js --verify-marker src/x.js=needle
+//                                                      # refuse a target that lacks the change
+//   node scripts/bongos/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/bongos/go-live.js                     PLAN only (read-only, the default)
+  node scripts/bongos/go-live.js --apply             move the pin
+  node scripts/bongos/go-live.js --to <version>      target a version explicitly
+  node scripts/bongos/go-live.js --verify-marker <path>=<needle>
+                                                  refuse a target that lacks the change
+  node scripts/bongos/go-live.js --target <name>     pick a target from the config
+  node scripts/bongos/go-live.js --config <path>     default: ${DEFAULT_CONFIG}
+  node scripts/bongos/go-live.js --allow-unreleased  downgrade UNRELEASED_ON_MAIN to a warning
+  node scripts/bongos/go-live.js --no-fetch          skip the origin/main refresh (default: fetch)
+  node scripts/bongos/go-live.js --target-json '{…}' pass a target inline instead of a config file
+  node scripts/bongos/go-live.js --no-divergence     skip the git-derived checks (needs --to)
+  node scripts/bongos/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,
+};