@bongos/core 1.19.306 → 1.19.308

package/scripts/gds/go-live.js

@@ -0,0 +1,666 @@
+#!/usr/bin/env node
+'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 } = 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.
+const REQUIRED_FIELDS = ['ssh', 'instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer'];
+const OPTIONAL_FIELDS = ['deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage'];
+
+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 (!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",                 // pull-deploy timer (its reset --hard is the hazard)
+      "deployService": "my-deploy.service",             // optional: forced tick proves the pin stuck
+      "npmEnvFile": "/etc/my/npm.env",                  // optional: root-only NPM_TOKEN for a PRIVATE package
+      "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"
+    }
+  }
+}`;
+
+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.
+// ---------------------------------------------------------------------------
+
+function remote(target, script, { run = spawnSync, timeoutMs = 900000 } = {}) {
+  const res = run('ssh', ['-o', 'ConnectTimeout=20', '-o', 'BatchMode=yes', target.ssh, 'bash', '-s'], {
+    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.
+//
+// `forward` names variables to pass through BY REFERENCE (`K="$K"`), for values that
+// exist in the calling root shell but must not appear in this script's text. That is
+// how NPM_TOKEN reaches the upgrade: sudo's env_reset drops it, and an explicit
+// `env K=V` list that omits it drops it too — so `npm install` 404s the PRIVATE
+// package and the upgrade auto-rolls-back, which reads as "the release is broken"
+// when it is only "the token never arrived". Sourcing the env file in the OUTER shell
+// is necessary and NOT sufficient; this is the second half of that trap.
+function asOwner(target, cmd, { forward = [] } = {}) {
+  const envPairs = Object.entries(target.env || {}).map(([k, v]) => `${k}=${v}`);
+  for (const k of forward) {
+    if (!SAFE_ENV_KEY_RE.test(k)) continue; // never interpolate an unvetted name
+    envPairs.push(`${k}="$${k}"`);          // by reference — the VALUE is never written here
+  }
+  const joined = envPairs.join(' ');
+  const prefix = target.runAs ? `sudo -u ${target.runAs} -H env ${joined} HOME=/home/${target.runAs}` : (joined ? `env ${joined}` : '');
+  return `${prefix} ${cmd}`.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);
+}
+
+// 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 };
+}
+
+// Which variables an npm-running command needs forwarded. Only when the target
+// declares an env file to source them from — otherwise `K="$K"` would expand to
+// empty and quietly do nothing.
+function npmForward(target) {
+  return target.npmEnvFile ? ['NPM_TOKEN'] : [];
+}
+
+// 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',
+};
+
+function planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased = false }) {
+  const halts = [];
+  const 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'}`);
+  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.name}${step.detail ? ` — ${step.detail}` : ''}`);
+
+  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)'}`);
+  L.push(`  pin committed     ${r.pinCommitted ? 'yes' : '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
+// consulted ON THE BOX because a PRIVATE package 404s without the root-only
+// NPM_TOKEN, and because the box's answer is the one that matters.
+function probeRemote(target, targetVersion, marker, opts = {}) {
+  const pkg = target.registryPackage || '@bongos/core';
+  const src = target.npmEnvFile ? `set -a; . ${target.npmEnvFile}; set +a` : 'true';
+  const script = `
+set -uo pipefail
+${src}
+echo "##REGISTRY##"
+${asOwner(target, `npm view ${pkg}@${targetVersion} version`, { forward: npmForward(target) })} 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))}`, { forward: npmForward(target) })}` : ''}
+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,
+  };
+}
+
+function applyGoLive(target, targetName, targetVersion, from, opts = {}) {
+  const pkg = target.registryPackage || '@bongos/core';
+  const steps = [];
+  const src = target.npmEnvFile ? `set -a; . ${target.npmEnvFile}; set +a` : 'true';
+
+  // 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.
+  const backup = target.backupDb
+    ? asOwner(target, `bash -c "mkdir -p ${target.backupDir || '~/backups'} && pg_dump ${target.backupDb} | gzip > ${target.backupDir || '~/backups'}/pre-${targetVersion}-$(date -u +%Y%m%dT%H%M%SZ).sql.gz"`)
+    : 'echo "(no backupDb configured — skipping)"';
+  const phaseA = remote(target, `
+set -euo pipefail
+echo "##TIMER##"; systemctl stop ${target.deployTimer} && systemctl is-active ${target.deployTimer} || true
+echo "##BACKUP##"; ${backup}
+echo "##END##"
+`, opts);
+  steps.push({ name: `stop ${target.deployTimer} + backup`, ok: phaseA.ok, detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop() });
+  if (!phaseA.ok) return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'PREPARE', raw: phaseA };
+
+  // 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 upgrade = [
+    `./node_modules/.bin/bongos upgrade`,
+    `--to ${targetVersion}`, '--registry',
+    `--instance ${target.instanceDir}`,
+    `--service ${target.service}`,
+    `--health-url ${target.healthUrl}`,
+    '--commit-pin', '--force',
+  ].join(' ');
+  const phaseB = remote(target, `
+set -uo pipefail
+${src}
+${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { forward: npmForward(target) })}
+`, 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.
+    remote(target, `systemctl start ${target.deployTimer} || true`, opts);
+    return { ok: false, steps, from, to: targetVersion, targetName, 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
+echo "##TIMERSTART##"; systemctl start ${target.deployTimer}; 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##"; systemctl start ${target.deployService} || true; 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; }
+
+  steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
+  steps.push({ name: 'pin committed + pushed', ok: !pinDirty, detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (section('HEAD') || null) });
+  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, 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 --json              machine-readable
+
+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');
+
+  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;
+
+  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; }
+
+  const fetched = hasFlag('--no-fetch') ? { ok: false, skipped: true } : refreshMain();
+  const div = 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 (read ${JSON.stringify(targetVersion)} from main)`);
+    return 1;
+  }
+
+  const dirtyRes = 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;
+
+  const plan = planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased });
+  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;
+    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: cfg.path })); }
+    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, parseMarker, parseMarkerHits,
+  renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, npmForward, refreshMain,
+  CONFIG_TEMPLATE, HALTS, SEMVER_RE,
+};