@bongos/core 1.19.307 → 1.19.308

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.307",
-  "core_contract": "1.19.307",
-  "source_commit": "b8d2ed227fd6cb0b948128e23f0daf0070b50bcc",
+  "core_version": "1.19.308",
+  "core_contract": "1.19.308",
+  "source_commit": "73400ffdb3672b797a1dda57f589d9cc43da2ed1",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T20:16:34.186Z",
+  "built_at": "2026-08-23T20:30:08.216Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1418,
+    "functional_verbatim": 1420,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1762,
-  "tree_sha256": "2ce3db5cb1a893df39826469894f19d4acdee021e5729859eaa8d429933be04d",
+  "file_count": 1764,
+  "tree_sha256": "bfea309c25b9ba974096b8f0572e268ea80238aaf00e23d700adeb9e58458d49",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1667,7 +1667,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "100a1bd6bde327c60f37727ce85f75cf5539b007473359692de7ab87876c936b"
+      "sha256": "b42d8b4620355bef0e27480b2ddfaa07140e322de988839f0e102f1a1545ac47"
     },
     {
       "path": "docs/recipes/devbox-app-release.md",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4815e8ce78e80ac2fff7dad9f77bef508e2f0090459c67e59722b65af3e27294"
+      "sha256": "4293f77940579b7c64fa5bc09f5a132c27efb5e4d21ee37a29ee3cf08d60ad88"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bdeee91142d9d7f3930c99134be76d03f28329222adcf293deaa8f8354ab2cd8"
+      "sha256": "254eba7acbbc7ba707abfe41dd50f8e83880cf8f93cbe5daff2c88cf02dd46f1"
     },
     {
       "path": "public-docs/index.html",
@@ -5309,6 +5309,11 @@
       "mode": "0000644",
       "sha256": "75130de4a880fc7d76f5a8d79ed65750238df94847c1ccfdc974188f9300a1e6"
     },
+    {
+      "path": "scripts/gds/go-live.js",
+      "mode": "0000644",
+      "sha256": "05734e21763cc0b0614275efa76b7b68afabee8be93f3f2d797400d6a97e86c1"
+    },
     {
       "path": "scripts/gds/goal.js",
       "mode": "0000644",
@@ -6247,7 +6252,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "90436d6db6e32424c48549f61ad48a3a77f5c7cac1ae16d5559b7db76fee7b4a"
+      "sha256": "87cec9eba20525297a298914c20d89882db138f0cdbc5c1ae4a5ce3d285147db"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7164,6 +7169,11 @@
       "mode": "0000644",
       "sha256": "d0d10628a17717fdef505dcf501915ecfcc31a0c99d9e5d4cf6dc06b47d8c883"
     },
+    {
+      "path": "tests/go_live.mjs",
+      "mode": "0000644",
+      "sha256": "90c8cbfd8bf0b446261f9fd837b9b08b1035210f1cbf1f7ff81998ec535c32f1"
+    },
     {
       "path": "tests/goal_abuse_matrix.mjs",
       "mode": "0000644",

package/docs/recipes/core-release-pipeline.md

@@ -136,6 +136,38 @@ The generic mechanics are [upgrading-the-core](upgrading-the-core.md); this is t
 
 **Cadence: bump once, at session end.** One upgrade covers every release the session landed (publish-on-merge cuts one per merge — you don't chase each). Don't bump per-ship.
 
+### Step 0 — try the one command first (task 1003189)
+
+The whole sequence below is deterministic, so it is also a script. `go-live.js` composes the
+same parts this runbook narrates — `deploy-divergence.js` for the gap, the registry for proof a
+release exists, and `bongos upgrade --registry --commit-pin` for the bump itself — and reports
+once instead of forty times:
+
+```bash
+node scripts/gds/go-live.js
+```
+
+That is **plan-only and read-only**: it prints live-vs-target, checks the registry actually
+carries the target, and names every halt condition it found. Add `--apply` to move the pin.
+
+It **halts rather than guessing** on exactly the things that need judgement — unreleased commits
+on `main`, a registry missing the target, a dirty tree on either end, a failed health check, an
+uncommitted pin. When it halts, fall through to the manual steps below and use your own head;
+that is what the rest of this section is for.
+
+Two flags worth knowing:
+
+- `--verify-marker <path>=<needle>` refuses a target that does not actually contain your change.
+  This is the guard for the trap in Step 1: the carrier sitting on `main` when your fix merged
+  was usually cut *before* it, so deploying "the version main was on" is a textbook-clean go-live
+  that changes nothing — and every downstream check agrees it worked.
+- `--allow-unreleased` downgrades the UNRELEASED halt to a warning. Reach for it only when you
+  have already confirmed *why* main is ahead of its last release.
+
+Host topology (ssh alias, box paths, service names, health URL) lives in a host-owned
+`config/go-live.json`, never in the core — run `node scripts/gds/go-live.js --help` for the
+schema. A core that named one instance's box would not be a core.
+
 ### Step 1 — pick the version (your machine, main checkout)
 
 ```bash

package/package-lock.json

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

package/package.json

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

package/scripts/gds/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,
+};

package/src/module-api.js

@@ -1041,8 +1041,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.305 with no explicit bump. run 32662000590. (task 1002620)
 //   1.19.307 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.306 with no explicit bump. run 32663876767. (task 1002620)
+//   1.19.308 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.307 with no explicit bump. run 32664559221. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.307'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.308'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/go_live.mjs

@@ -0,0 +1,362 @@
+// tests/go_live.mjs
+//
+// task 1003189 — go-live is one command.
+//
+// What is worth pinning here is NOT the happy path (that needs a real box) but the
+// REFUSALS. The whole value of this script is that it stops instead of guessing, and
+// every halt below is a trap this pipeline has actually paid for at least once:
+//
+//   UNRELEASED_ON_MAIN      — the ten-day stale-prod incident (blocker 1000097), and
+//                             the publish push-race that leaves main's code carried by
+//                             no release at all.
+//   MARKER_ABSENT           — "the release current when your fix merges usually does
+//                             NOT contain your fix" (ADR 0161 carriers bump on their
+//                             own cadence). Deploying it is a clean go-live that
+//                             changes nothing, and every downstream check agrees.
+//   ALREADY_LIVE / LIVE_AHEAD — a no-op bump reported as success.
+//   DIRTY_CHECKOUT          — CORE_VERSION read from a dirty tree is not what shipped.
+//
+// The shell-safety tests are the other half. This script composes a command that runs
+// as root over ssh, so a config value carrying `$(...)`, a backtick or a `;` must be
+// REFUSED, not quoted-and-hoped-for (the #681 injection class).
+//
+// Run:  node --test tests/go_live.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const G = require('../scripts/gds/go-live.js');
+
+const okTarget = {
+  ssh: 'my-box',
+  instanceDir: '/home/me/inst',
+  service: 'inst.service',
+  healthUrl: 'http://127.0.0.1:3002/healthz',
+  versionUrl: 'http://127.0.0.1:3002/version',
+  deployTimer: 'inst-deploy.timer',
+};
+
+// A divergence result shaped like deploy-divergence.check() returns.
+const div = (over = {}) => ({
+  ok: true, onMain: '1.19.306', live: { coreVersion: '1.19.305' },
+  hasUnreleased: false, unreleased: { count: 0 }, ...over,
+});
+
+// ---------------------------------------------------------------------------
+// Halt matrix
+// ---------------------------------------------------------------------------
+
+test('a clean gap plans with no halts', () => {
+  const p = G.planGoLive({ div: div(), target: okTarget, targetVersion: '1.19.306' });
+  assert.equal(p.halts.length, 0, JSON.stringify(p.halts));
+  assert.equal(p.from, '1.19.305');
+});
+
+test('unreleased commits on main HALT the go-live', () => {
+  const p = G.planGoLive({
+    div: div({ hasUnreleased: true, unreleased: { count: 7 } }),
+    target: okTarget, targetVersion: '1.19.306',
+  });
+  const h = p.halts.find((x) => x.code === 'UNRELEASED_ON_MAIN');
+  assert.ok(h, 'expected UNRELEASED_ON_MAIN');
+  // The detail must name the push-race, or the reader assumes it is only timing.
+  assert.match(h.detail, /publish/i);
+  assert.match(h.detail, /7 commit/);
+});
+
+test('--allow-unreleased downgrades that halt to a note rather than dropping it', () => {
+  const p = G.planGoLive({
+    div: div({ hasUnreleased: true, unreleased: { count: 7 } }),
+    target: okTarget, targetVersion: '1.19.306', allowUnreleased: true,
+  });
+  assert.equal(p.halts.find((x) => x.code === 'UNRELEASED_ON_MAIN'), undefined);
+  const n = p.notes.find((x) => x.code === 'UNRELEASED_ON_MAIN');
+  assert.ok(n && n.downgraded, 'the condition must still be REPORTED, just not fatal');
+});
+
+test('a no-op bump is a halt, not a success', () => {
+  const p = G.planGoLive({
+    div: div({ live: { coreVersion: '1.19.306' } }), target: okTarget, targetVersion: '1.19.306',
+  });
+  assert.ok(p.halts.find((x) => x.code === 'ALREADY_LIVE'));
+});
+
+test('live ahead of the target halts rather than silently downgrading', () => {
+  const p = G.planGoLive({
+    div: div({ live: { coreVersion: '1.19.310' } }), target: okTarget, targetVersion: '1.19.306',
+  });
+  assert.ok(p.halts.find((x) => x.code === 'LIVE_AHEAD'));
+});
+
+test('a dirty core checkout halts — CORE_VERSION there is not what shipped', () => {
+  const p = G.planGoLive({
+    div: div(), target: okTarget, targetVersion: '1.19.306', dirtyCheckout: ' M src/module-api.js',
+  });
+  assert.ok(p.halts.find((x) => x.code === 'DIRTY_CHECKOUT'));
+});
+
+test('an undetermined divergence halts and does not fall through to a bump', () => {
+  const p = G.planGoLive({
+    div: { undetermined: true, reason: 'could not read /version' }, target: okTarget, targetVersion: '1.19.306',
+  });
+  assert.equal(p.halts.length, 1);
+  assert.equal(p.halts[0].code, 'DIVERGENCE_UNDETERMINED');
+  assert.equal(p.from, null, 'must not invent a from-version');
+});
+
+// ---------------------------------------------------------------------------
+// Shell safety — this builds a command that runs as root over ssh
+// ---------------------------------------------------------------------------
+
+test('config values carrying shell metacharacters are REFUSED', () => {
+  for (const evil of [
+    '$(touch /tmp/pwned)',
+    '`id`',
+    'box; rm -rf /',
+    'box && curl evil.example',
+    'box\nrm -rf /',
+    'box|tee /etc/passwd',
+    "box'quote",
+  ]) {
+    const errs = G.validateTarget('t', { ...okTarget, ssh: evil });
+    assert.ok(errs.length > 0, `expected refusal for ${JSON.stringify(evil)}`);
+    assert.match(errs.join(' '), /unsafe in a shell/);
+  }
+});
+
+test('env values and keys are validated too', () => {
+  assert.ok(G.validateTarget('t', { ...okTarget, env: { PGDATABASE: '$(id)' } }).length > 0);
+  assert.ok(G.validateTarget('t', { ...okTarget, env: { 'BAD KEY': 'x' } }).length > 0);
+  assert.equal(G.validateTarget('t', { ...okTarget, env: { PGDATABASE: 'mydb' } }).length, 0);
+});
+
+test('a typo’d field is reported, never silently ignored', () => {
+  // A misspelled healthUrl that is quietly dropped would DISABLE the health gate —
+  // exactly the quiet failure this pipeline keeps being bitten by.
+  const errs = G.validateTarget('t', { ...okTarget, healthURL: 'http://x/healthz' });
+  assert.match(errs.join(' '), /unknown field "healthURL"/);
+});
+
+test('missing required fields are named individually', () => {
+  const errs = G.validateTarget('t', { ssh: 'box' });
+  for (const f of ['instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer']) {
+    assert.match(errs.join(' '), new RegExp(`missing required field "${f}"`));
+  }
+});
+
+test('a valid target passes clean', () => {
+  assert.deepEqual(G.validateTarget('t', okTarget), []);
+});
+
+test('asOwner composes the documented sudo -u … env … shape', () => {
+  const cmd = G.asOwner({ runAs: 'me', env: { PGDATABASE: 'mydb' } }, 'echo hi');
+  assert.match(cmd, /^sudo -u me -H env PGDATABASE=mydb HOME=\/home\/me echo hi$/);
+  // PGDATABASE is load-bearing: without it migrate targets a stale default and
+  // the upgrade auto-rolls-back. It must survive into the command.
+  assert.ok(cmd.includes('PGDATABASE=mydb'));
+});
+
+test('asOwner with no runAs still carries env', () => {
+  assert.equal(G.asOwner({ env: { A: 'b' } }, 'x'), 'env A=b x');
+  assert.equal(G.asOwner({}, 'x'), 'x');
+});
+
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+
+test('an absent config reports NO_TARGET_CONFIG with a template, not a stack trace', () => {
+  const r = G.loadConfig({ configPath: 'config/definitely-not-here.json', exists: () => false });
+  assert.equal(r.error, 'NO_TARGET_CONFIG');
+  assert.ok(r.template.includes('instanceDir'));
+});
+
+test('a malformed config is reported as malformed, not treated as empty', () => {
+  const r = G.loadConfig({ configPath: 'x.json', exists: () => true, readFile: () => '{ not json' });
+  assert.equal(r.error, 'CONFIG_MALFORMED');
+});
+
+test('a config without targets is malformed rather than a silent no-op', () => {
+  const r = G.loadConfig({ configPath: 'x.json', exists: () => true, readFile: () => '{"defaultTarget":"web"}' });
+  assert.equal(r.error, 'CONFIG_MALFORMED');
+  assert.match(r.detail, /targets/);
+});
+
+test('the shipped template is itself valid config', () => {
+  const r = G.loadConfig({ configPath: 'x.json', exists: () => true, readFile: () => G.CONFIG_TEMPLATE });
+  assert.ok(r.ok, `template did not parse: ${r.detail || ''}`);
+  const sel = G.selectTarget(r.config, undefined);
+  assert.ok(sel.ok, `template target invalid: ${sel.detail || ''}`);
+  assert.equal(sel.name, 'web');
+});
+
+test('an unknown target names what IS available', () => {
+  const r = G.loadConfig({ configPath: 'x.json', exists: () => true, readFile: () => G.CONFIG_TEMPLATE });
+  const sel = G.selectTarget(r.config, 'nope');
+  assert.equal(sel.error, 'UNKNOWN_TARGET');
+  assert.match(sel.detail, /web/);
+});
+
+// ---------------------------------------------------------------------------
+// Markers + version parsing
+// ---------------------------------------------------------------------------
+
+test('parseMarker splits on the FIRST = so a needle may contain one', () => {
+  assert.deepEqual(G.parseMarker('src/a.js=const X = 1'), { path: 'src/a.js', needle: 'const X = 1' });
+});
+
+test('a malformed marker is rejected', () => {
+  assert.ok(G.parseMarker('noequals').error);
+  assert.ok(G.parseMarker('=needle').error);
+  assert.ok(G.parseMarker('path=').error);
+  assert.equal(G.parseMarker(''), null);
+});
+
+test('the version pattern accepts releases and rejects free text', () => {
+  for (const v of ['1.19.306', '1.0.0', '2.3.4-rc.1']) assert.ok(G.SEMVER_RE.test(v), v);
+  for (const v of ['latest', '1.19', 'v1.19.306', '1.19.306; rm -rf /', '']) assert.ok(!G.SEMVER_RE.test(v), v);
+});
+
+// ---------------------------------------------------------------------------
+// Rendering — the report is the product; it must not claim more than it proved
+// ---------------------------------------------------------------------------
+
+test('the plan names every halt it found', () => {
+  const p = G.planGoLive({
+    div: div({ hasUnreleased: true, unreleased: { count: 3 } }),
+    target: okTarget, targetVersion: '1.19.306', dirtyCheckout: ' M x',
+  });
+  const out = G.renderPlan(p, { targetName: 'web' });
+  assert.match(out, /UNRELEASED_ON_MAIN/);
+  assert.match(out, /DIRTY_CHECKOUT/);
+  assert.match(out, /will NOT proceed/);
+});
+
+test('a clean plan tells you the next command', () => {
+  const out = G.renderPlan(G.planGoLive({ div: div(), target: okTarget, targetVersion: '1.19.306' }), { targetName: 'web' });
+  assert.match(out, /--apply/);
+});
+
+test('an uncommitted pin is reported as the durability failure it is', () => {
+  const out = G.renderReport({
+    targetName: 'web', from: '1.19.305', to: '1.19.306', liveVersion: '1.19.306',
+    pinCommitted: false, steps: [],
+  });
+  assert.match(out, /revert this bump/);
+});
+
+// ---------------------------------------------------------------------------
+// The content proof must fail CLOSED
+//
+// This is the bug that got through twice. `grep -c` PRINTS 0 and EXITS 1 on no
+// match, so the obvious `|| echo 0` emitted "0\n0" — which Number() turns into
+// NaN, and NaN === 0 is false, so an ABSENT marker sailed through as no-halt.
+// A content proof that fails open is worse than none: it certifies a release
+// that does not contain the change, and every downstream check agrees.
+// ---------------------------------------------------------------------------
+
+test('a clean count reads as that count', () => {
+  assert.equal(G.parseMarkerHits('3'), 3);
+  assert.equal(G.parseMarkerHits('0'), 0);
+  assert.equal(G.parseMarkerHits(' 12 \n'), 12);
+});
+
+test('a double-printed zero reads as 0 (absent), never NaN', () => {
+  const v = G.parseMarkerHits('0\n0');
+  assert.equal(v, 0);
+  assert.ok(!Number.isNaN(v), 'NaN here is what let an absent marker pass');
+});
+
+test('anything that is not a count is UNCHECKED, never a confident 0', () => {
+  for (const junk of ['', null, undefined, 'PACK_FAILED', 'PACK_FAILED npm error E404', 'tar: not found', 'abc']) {
+    assert.equal(G.parseMarkerHits(junk), 'PACK_FAILED', JSON.stringify(junk));
+  }
+});
+
+test("'could not check' is a distinct halt from 'absent'", () => {
+  // They must never collapse: one says fix your fetch, the other says pick a
+  // later release. Conflating them sends you chasing a version that is not there.
+  assert.ok(G.HALTS.MARKER_UNCHECKED);
+  assert.ok(G.HALTS.MARKER_ABSENT);
+  assert.notEqual(G.HALTS.MARKER_UNCHECKED, G.HALTS.MARKER_ABSENT);
+});
+
+// ---------------------------------------------------------------------------
+// The NPM_TOKEN forwarding trap
+//
+// `bongos upgrade --registry` needs NPM_TOKEN or npm 404s the PRIVATE core and the
+// upgrade auto-rolls-back — which reads as "the release is broken" when it is only
+// "the token never arrived". Sourcing the root-only env file in the OUTER shell is
+// necessary and NOT sufficient: sudo's env_reset drops it, and an explicit
+// `env K=V` list that omits it drops it too. This cost a real failed go-live.
+// ---------------------------------------------------------------------------
+
+test('a forwarded var is passed BY REFERENCE, never by value', () => {
+  const cmd = G.asOwner({ runAs: 'lars', env: { PGDATABASE: 'cb' } }, 'npm install', { forward: ['NPM_TOKEN'] });
+  assert.match(cmd, /NPM_TOKEN="\$NPM_TOKEN"/);
+  // The point of by-reference: the secret's VALUE must never appear in the script text.
+  assert.ok(!cmd.includes('npm_'), 'a token value must never be interpolated here');
+});
+
+test('forwarding is only wired when the target names an env file to source from', () => {
+  // Otherwise K="$K" expands to empty and silently does nothing — a quiet no-op
+  // is worse than not trying.
+  assert.deepEqual(G.npmForward({ npmEnvFile: '/etc/x/npm.env' }), ['NPM_TOKEN']);
+  assert.deepEqual(G.npmForward({}), []);
+});
+
+test('an unvetted variable name is never interpolated', () => {
+  const cmd = G.asOwner({ runAs: 'me' }, 'x', { forward: ['GOOD', 'bad name', '$(id)', '1BAD'] });
+  assert.match(cmd, /GOOD="\$GOOD"/);
+  assert.ok(!cmd.includes('bad name') && !cmd.includes('$(id)') && !cmd.includes('1BAD'));
+});
+
+// ---------------------------------------------------------------------------
+// A failed run must say what the tool said
+// ---------------------------------------------------------------------------
+
+test('the report surfaces the failing tool’s own words', () => {
+  const out = G.renderReport({
+    ok: false, failedAt: 'UPGRADE', targetName: 'web', from: '1.19.305', to: '1.19.306',
+    rolledBack: true, steps: [{ name: 'upgrade', ok: false, detail: 'AUTO-ROLLBACK ran' }],
+    raw: { stdout: 'npm error 404 Not Found - GET https://registry.npmjs.org/@bongos%2fcore\nup to date in 2s', stderr: '' },
+  });
+  assert.match(out, /404 Not Found/, 'the diagnosis must reach the reader');
+  assert.match(out, /not broken/, 'a rollback must be distinguished from an outage');
+});
+
+test('failureExcerpt prefers diagnostic lines over trailing noise', () => {
+  const raw = { stdout: ['ok a', 'ok b', 'npm error code E404', 'up to date in 2s'].join('\n'), stderr: '' };
+  const ex = G.failureExcerpt(raw);
+  assert.ok(ex.some((l) => l.includes('E404')));
+  assert.ok(!ex.some((l) => l === 'ok a'));
+});
+
+test('failureExcerpt is safe on an empty or missing result', () => {
+  assert.deepEqual(G.failureExcerpt(null), []);
+  assert.deepEqual(G.failureExcerpt({ stdout: '', stderr: '' }), []);
+});
+
+// ---------------------------------------------------------------------------
+// A stale origin/main ref silently retargets the whole go-live
+// ---------------------------------------------------------------------------
+
+test('refreshMain reports a failed fetch instead of throwing', () => {
+  const r = G.refreshMain({ run: () => ({ status: 1, stderr: 'fatal: could not read from remote\n' }) });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /could not read from remote/);
+});
+
+test('refreshMain succeeds quietly', () => {
+  assert.deepEqual(G.refreshMain({ run: () => ({ status: 0, stdout: '', stderr: '' }) }), { ok: true });
+});
+
+test('a spawn error is handled, not thrown', () => {
+  const r = G.refreshMain({ run: () => ({ error: new Error('ENOENT'), status: null }) });
+  assert.equal(r.ok, false);
+});