@bongos/core 1.19.306 → 1.19.308

package/scripts/gds/ship-honesty.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// scripts/gds/ship-honesty.js — a ship must not lose the builder's prose, and
+// must not lie about how far it got (task 1003168 / G04, goal 1000077;
+// criterion guards-ship-cannot-lie).
+//
+// TWO fixes live here because they are one incident. A ship was invoked with
+// handoff notes containing backticks; bash command-substituted them before node
+// ran, truncating the argument list. The task resolved with EMPTY notes, landed
+// at 'completed', and the process died before grading with a bare
+// `fatal: <stack>`. Two failures compounded: the prose was lost (nothing in the
+// ledger about a session that happened), and the status could not say which leg
+// died — 'completed' is ALSO what a grade-failed task looks like.
+//
+// Split out of ship.js, which is ~4600 lines and far over the size ratchet, so
+// adding this there would have regressed excess_lines_total.
+
+'use strict';
+
+const { argText } = require('./cli-lib.js');
+
+// resolveProse(args, specs) — resolve every prose argument for one invocation
+// through cli-lib.argText, refusing the combinations that would silently lose
+// text. Returns a { [bareName]: string } map, or exits 2 having explained why.
+//
+// The extra rule argText cannot enforce alone: stdin can only be consumed ONCE,
+// so two `-file -` arguments in the same command would hand the first reader
+// everything and the second an empty string. Refuse instead — a ship whose notes
+// silently came back empty is the exact incident this whole task is about
+// (learning 1000197).
+function resolveProse(args, specs) {
+  const out = {};
+  const stdinUsers = [];
+  for (const name of specs) {
+    const r = argText(`--${name}`, args);
+    if (r.error) {
+      console.error(r.error);
+      process.exit(2);
+    }
+    if (r.source === 'stdin') stdinUsers.push(`--${name}-file`);
+    out[name] = r.value;
+  }
+  if (stdinUsers.length > 1) {
+    console.error(`${stdinUsers.join(' and ')} both read stdin, which can only be consumed once — `
+      + 'the second would silently come back empty. Put at least one in a real file.');
+    process.exit(2);
+  }
+  return out;
+}
+
+// ---------- The ship must not lie about how far it got (G04, task 1003168) ----
+//
+// THE INCIDENT. A ship died after the claim resolved and before the grade
+// recorded. resolveClaim had already landed the task at 'completed', so the
+// process printed `fatal: <stack>` and exited — and 'completed' is exactly what
+// a task ALSO looks like when its grade ran and failed. The status could not
+// distinguish "the pipeline stopped here" from "the pipeline got further and the
+// grade said no", and the work went unrecovered because nobody could tell.
+//
+// The cure is not more status values: it is that the process which knows where it
+// died must SAY so on the way out. shipProgress records the last leg that
+// completed; fatalRecoveryLines turns it into an instruction.
+let shipProgress = { stage: 'preflight', taskId: null };
+
+// The one writer. Called by ship.js as each leg completes.
+function markShipProgress(stage, taskId) {
+  shipProgress = { stage, taskId };
+}
+
+// Pure so the wording is pinned by a DB-free test (the smokeGateMessages
+// precedent) — a recovery message that drifts out of date is worse than none.
+//
+// WHY EVERY STAGE POINTS AT A PLAIN RE-RUN, never --regrade: shipMain on a task
+// with no active claim routes by the task's CURRENT status (evaluateResumeAction)
+// — 'completed' resumes the grade, 'confirmed' resumes the merge. --regrade only
+// accepts 'completed' and REFUSES a 'confirmed' task with "its grade passed;
+// nothing to re-grade". A builder reading a crash does not know which leg died,
+// which is the entire problem, so the advice must be the command that works from
+// either — and a plain re-run of a 'completed' task calls regradeMain() anyway.
+function fatalRecoveryLines(progress = shipProgress) {
+  const id = progress.taskId;
+  const rerun = id ? `node scripts/gds/ship.js ${id}` : 'node scripts/gds/ship.js <task-id>';
+  const head = 'The ship did NOT finish. Where it stopped, and what recovers it:';
+  switch (progress.stage) {
+    case 'resolved':
+      return [
+        head,
+        `  Task #${id} is at 'completed' — the claim resolved, the grade did NOT record.`,
+        '  No credits awarded. Your commits are safe; nothing was lost but the grade.',
+        `  Resume:  ${rerun}`,
+        "  (A plain re-run resumes the stalled leg. Do NOT reach for --regrade: it only",
+        "   accepts 'completed', so it refuses outright if the ship actually got further.)",
+      ];
+    case 'graded':
+      return [
+        head,
+        `  Task #${id} is at 'confirmed' — it graded and PASSED; the merge/deploy did not finish.`,
+        '  Credits land on the merge, so they have not been awarded yet.',
+        `  Resume:  ${rerun}`,
+        '  (--regrade would refuse this one — its grade already passed.)',
+      ];
+    case 'landed':
+      return [
+        'The ship LANDED; the failure above is in the after-work:',
+        `  Task #${id} reached 'shipped' — the merge landed and credits were awarded.`,
+        '  Broadcast / card / cleanup did not complete, which does not undo the ship.',
+        `  Safe to re-run if you want the after-work retried:  ${rerun}`,
+      ];
+    case 'preflight':
+    default:
+      return [
+        head,
+        '  The claim was NOT resolved — it is still active and the task is unchanged.',
+        `  Fix the error above and re-run:  ${rerun}`,
+      ];
+  }
+}
+
+// task 1002605 (G-18): the pre-resolve smoke gate's two message sets, pure so the
+// wording is pinned by a DB-free unit test (tests/ship_smoke_gate.mjs). A smoke
+// FAIL used to fall silently through into the claim resolve — claim consumed,
+// grading skipped with no message, task parked at 'completed', exit 0 — the
+// choke-point map's likeliest "my task vanished" shape. `abort` is the default
+// (printed BEFORE the resolve; the claim stays active); `parked` is the
+// --allow-smoke-fail continuation (printed where the grader would have run, so
+// the builder knows exactly where the task stopped and how to resume).
+function smokeGateMessages(taskId) {
+  return {
+    abort: [
+      'Ship ABORTED: the production smoke test FAILED — see the FAIL line(s) above.',
+      'No claim resolved, no credits awarded — your claim is still active and nothing changed.',
+      'The smoke suite hits LIVE endpoints (your change is not deployed yet), so this usually means production is briefly degraded — not that your change broke it.',
+      `  - Re-run once it recovers:     node scripts/gds/ship.js ${taskId}`,
+      `  - Ship anyway (deliberate):    node scripts/gds/ship.js ${taskId} --allow-smoke-fail`,
+      `    (parks the task at 'completed' ungraded; a plain re-run resumes it)`,
+    ],
+    parked: [
+      '--allow-smoke-fail: smoke FAILED and the ship deliberately stops here.',
+      `Task #${taskId} is parked at 'completed' — ungraded, unconfirmed, no credits awarded.`,
+      `Resume when production is healthy:  node scripts/gds/ship.js ${taskId}`,
+      '  (A plain re-run routes to whichever leg stalled. --regrade only accepts a task at',
+      "   'completed', so it refuses if the ship got further — task 1003168.)",
+    ],
+  };
+}
+
+module.exports = {
+  resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
+  _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
+  _peekForTest: () => shipProgress,
+};

package/scripts/gds/ship.js

@@ -12,6 +12,7 @@
 // the task stays at 'confirmed' for /merge-mode to land later.
 //
 // Usage:
+//   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
 //   node scripts/gds/ship.js <task-id> --notes "handoff markdown" --summary "value-summary line"
 //   node scripts/gds/ship.js <task-id> --no-merge      # stop after confirm; skip auto-merge
 //   node scripts/gds/ship.js <task-id> --db-only       # deliberate zero-commit / direct-SQL ship (task 391):
@@ -62,6 +63,8 @@ const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const { cliClient, requireSession, loadSession, loadSessionSync, printOnboardingNudge, arg, rewardPolicy } = require('./cli-lib');
+// task 1003168 (G04): how a ship reports prose + an unfinished run — see that file.
+const { resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages } = require('./ship-honesty.js');
 
 // The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
 // task 1002469). Cached module-level because the credits print + the completion
@@ -2235,32 +2238,6 @@ function runSmokeAsync() {
   });
 }
 
-// task 1002605 (G-18): the pre-resolve smoke gate's two message sets, pure so the
-// wording is pinned by a DB-free unit test (tests/ship_smoke_gate.mjs). A smoke
-// FAIL used to fall silently through into the claim resolve — claim consumed,
-// grading skipped with no message, task parked at 'completed', exit 0 — the
-// choke-point map's likeliest "my task vanished" shape. `abort` is the default
-// (printed BEFORE the resolve; the claim stays active); `parked` is the
-// --allow-smoke-fail continuation (printed where the grader would have run, so
-// the builder knows exactly where the task stopped and how to resume).
-function smokeGateMessages(taskId) {
-  return {
-    abort: [
-      'Ship ABORTED: the production smoke test FAILED — see the FAIL line(s) above.',
-      'No claim resolved, no credits awarded — your claim is still active and nothing changed.',
-      'The smoke suite hits LIVE endpoints (your change is not deployed yet), so this usually means production is briefly degraded — not that your change broke it.',
-      `  - Re-run once it recovers:     node scripts/gds/ship.js ${taskId}`,
-      `  - Ship anyway (deliberate):    node scripts/gds/ship.js ${taskId} --allow-smoke-fail`,
-      `    (parks the task at 'completed' ungraded; resume later with --regrade)`,
-    ],
-    parked: [
-      '--allow-smoke-fail: smoke FAILED and the ship deliberately stops here.',
-      `Task #${taskId} is parked at 'completed' — ungraded, unconfirmed, no credits awarded.`,
-      `Resume when production is healthy:  node scripts/gds/ship.js ${taskId} --regrade`,
-    ],
-  };
-}
-
 // ---------- Step 3: merge + deploy chain ----------
 
 function currentBranch() {
@@ -3696,11 +3673,14 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --notes "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
     process.exit(2);
   }
-  const notes = arg('--notes', args) || '';
-  const summary = arg('--summary', args) || '';
+  // G04: prose from a FILE or inline, never shell-mangled in silence.
+  const prose = resolveProse(args, ['notes', 'summary']);
+  const notes = prose.notes;
+  const summary = prose.summary;
   const skipMerge = args.includes('--no-merge');
   const force = args.includes('--force');
   // task 391 (idea #37): a deliberate zero-commit / direct-SQL ship. Without it,
@@ -4114,6 +4094,8 @@ async function shipMain() {
 
   const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
   console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+  // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
+  markShipProgress('resolved', taskId);
 
   // ---- Step 2: subagent quality grader ----
   // Runs when local verification passed AND resolveClaim landed at completed.
@@ -4241,6 +4223,10 @@ async function shipMain() {
   // ---- Step 3: confirmed→shipped tail (merge + deploy → memory/session sync →
   // Done → onboarding nudge → completion card), shared with regradeMain via
   // finishShip (#1093/C9). ----
+  // Graded. If it passed, only the merge remains — a different crash story.
+  if (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped') {
+    markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
+  }
   await finishShip({
     taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
     // task 1270: data for the deterministic completion card.
@@ -4283,14 +4269,15 @@ async function regradeMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary "..."] [--response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
-  const summaryArg = arg('--summary', args) || '';
+  const regradeProse = resolveProse(args, ['summary', 'response']);
+  const summaryArg = regradeProse.summary;
   // task 1002662: the builder's response to the prior round's findings — how
   // each was fixed, tracked (a task ref), or why it's out of scope. Rides to
   // the panel fenced, under the delta re-grade policy.
-  const responseArg = arg('--response', args) || '';
+  const responseArg = regradeProse.response;
   const skipMerge = args.includes('--no-merge');
   const force = args.includes('--force');
   // task 1002422: honor --base on regrade/resume too, so `--regrade --base <ref>`
@@ -4609,6 +4596,7 @@ module.exports = {
   // / non-ci → false) is unit-tested with no gh/network (env-driven via
   // OTB_DEPLOY_MODE + OTB_PUSH_VIA_SERVER).
   broadcastHandledByServer,
+  fatalRecoveryLines, // G04 re-export (definition in ship-honesty.js)
 };
 
 if (require.main === module) {
@@ -4617,6 +4605,9 @@ if (require.main === module) {
   const main = process.argv.slice(2).includes('--regrade') ? regradeMain : shipMain;
   main().catch((err) => {
     console.error('fatal:', err);
+    // G04: never exit on a stack trace alone — say which leg died.
+    console.error('');
+    for (const line of fatalRecoveryLines()) console.error(line);
     process.exit(1);
   });
 }

package/src/module-api.js

@@ -1039,8 +1039,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.304 with no explicit bump. run 32660902666. (task 1002620)
 //   1.19.306 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.306'; // 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);
+});