@bongos/core 1.19.1033 → 1.19.1034

package/tests/integration_parked_ratchet.mjs

@@ -41,7 +41,18 @@ const { INTEGRATION, INTEGRATION_PARKED, KNOWN_FAILING } = require('../scripts/g
 // Two later readings — 2/2 locally on a clean database, and the first CI run after
 // the parking landed — showed the pass was the anomaly. No new breakage was parked
 // here; one straggler joined the cohort it always belonged to.
-const MAX_PARKED = 24;
+//
+// LOWERED 24 → 23 by task 1002863: consumer_layout_boot was fixed and un-parked, and the
+// ceiling follows it down so the freed slot cannot quietly be spent on a new failure.
+const MAX_PARKED = 23;
+
+// The one test that proves the PUBLISHED package works end to end: packaged, installed into
+// a consumer, installed again from its own shipped lockfile, migrated onto EMPTY databases,
+// and serving a database-backed route (tasks 2142 + 1002863 — "PROVE PUBLISH"). Every other
+// test runs the source tree; none installs the package and runs it. So while this one is
+// parked or unselected that guarantee silently does not exist — which is exactly how it sat,
+// parked, from task 1004034 until task 1002863 found out why it failed.
+const PUBLISH_PROOF = 'consumer_layout_boot';
 
 test('every parked entry names a test file that exists', () => {
   const ghosts = [...INTEGRATION_PARKED]
@@ -71,6 +82,18 @@ test('no test is parked in both INTEGRATION_PARKED and KNOWN_FAILING', () => {
     'parked in two places at once — pick the mechanism that owns each test.');
 });
 
+test('the packaged-core proof is selected by the integration lane and parked nowhere', () => {
+  assert.ok(fs.existsSync(path.join(TESTS_DIR, `${PUBLISH_PROOF}.mjs`)),
+    `tests/${PUBLISH_PROOF}.mjs is gone — nothing proves the published package installs, migrates and serves any more.`);
+  assert.ok(INTEGRATION.has(PUBLISH_PROOF),
+    `${PUBLISH_PROOF} is not in the INTEGRATION set, so either the DB-free unit gate would try to run it `
+    + '(it needs npm, a network and a Postgres) or no lane selects it at all.');
+  assert.ok(!INTEGRATION_PARKED.has(PUBLISH_PROOF) && !KNOWN_FAILING.has(PUBLISH_PROOF),
+    `${PUBLISH_PROOF} is parked. It is the only proof that the PUBLISHED core installs, migrates an `
+    + 'empty database and serves from it; parking it re-opens that gap without a single red check. '
+    + 'Fix the failure instead — or, if parking is truly the call, make it deliberately by editing this guard.');
+});
+
 test('the parked count is ratcheted and cannot grow silently', () => {
   const n = INTEGRATION_PARKED.size;
   assert.ok(n <= MAX_PARKED,

package/tests/provisioning_public_refusal.mjs

@@ -0,0 +1,195 @@
+// tests/provisioning_public_refusal.mjs — a refusal reaches the person as its own sentence,
+// and nothing else ever does (task 1004126).
+//
+// THE BUG. The control-plane guard refuses a destructive action on the platform's own row
+// with a code, a 409 and a sentence written for the owner. Every catch in the provisioning
+// module answered a blanket 500 "internal error" instead, so an owner who pressed Take
+// offline or Disconnect on that row read "internal error" while the real sentence went only
+// to the journal. Task 1004125 fixed ONE catch by duck-typing three fields; twenty-three more
+// had the same shape.
+//
+// WHAT THESE PIN.
+//   • failFrom forwards a declared PublicRefusal, and ONLY that: a look-alike carrying the
+//     same three fields and a Postgres error naming a table both get the opaque 500.
+//   • the guard throws a PublicRefusal, so there is one definition of "public", not one per catch.
+//   • the three routes that can reach the guard today (owner teardown, force-teardown,
+//     disconnect) answer 409 with the guard's sentence, driven through the REAL router, the
+//     REAL enqueue helper and the REAL guard; an unexpected error on the same routes still
+//     answers 500 and leaks nothing.
+//   • the ratchet: no catch in the module answers a 5xx except through failFrom.
+//
+// DB-free: the shared pool's query is stubbed and auth is faked. No network.
+//
+// Run:  node --test tests/provisioning_public_refusal.mjs
+
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import http from 'node:http';
+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 { PublicRefusal, isPublicRefusal, failFrom } = require('../modules/provisioning/public-refusal.js');
+const guard = require('../modules/provisioning/control-plane-guard.js');
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+// A res that records what failFrom answered, through the same envelope a route uses.
+function recorder() {
+  const out = {};
+  return { out, fail: (code, opts) => { Object.assign(out, { code, ...opts }); } };
+}
+const selfRowDb = { query: async () => ({ rows: [{ hosting_shape: 'control-plane' }] }) };
+const guardRefusal = () => guard.assertIntentAllowed(selfRowDb, 1, 'teardown').then(() => null, (e) => e);
+
+// ---- the helper -----------------------------------------------------------------
+
+test('failFrom forwards a PublicRefusal as its own code, status and PUBLIC sentence', () => {
+  const r = recorder();
+  failFrom(r, new PublicRefusal({ code: 'nope', status: 409, publicMessage: 'You cannot do that here.', message: 'journal: row 7 is special' }), 'x_failed');
+  assert.deepEqual(r.out, { code: 'nope', status: 409, message: 'You cannot do that here.' }, 'the journal sentence stays in the journal');
+});
+
+test('a look-alike with the same three fields is NOT public — only a declared refusal is', () => {
+  // Task 1004125's catch duck-typed on code && status && publicMessage. Anything can carry
+  // those; only the class says it was written for a person.
+  const r = recorder();
+  failFrom(r, Object.assign(new Error('x'), { code: 'lookalike', status: 409, publicMessage: 'leaked' }), 'x_failed');
+  assert.deepEqual(r.out, { code: 'x_failed', status: 500, message: 'internal error' });
+});
+
+test('an unexpected error is opaque — a Postgres error naming a table never reaches the client', () => {
+  const r = recorder();
+  const pg = Object.assign(new Error('relation "provisioning_intents" does not exist'), { code: '42P01', status: 500 });
+  failFrom(r, pg, 'teardown_failed');
+  assert.deepEqual(r.out, { code: 'teardown_failed', status: 500, message: 'internal error' });
+  assert.equal(isPublicRefusal(pg), false);
+});
+
+test('a refusal is never an outage: PublicRefusal will not carry a non-4xx status', () => {
+  assert.throws(() => new PublicRefusal({ code: 'boom', status: 500, publicMessage: 'x' }), /4xx/);
+  assert.throws(() => new PublicRefusal({ code: 'boom', status: 409 }), /publicMessage/);
+});
+
+test('the control-plane guard throws a PublicRefusal: the owner sentence public, the journal one not', async () => {
+  const err = await guardRefusal();
+  assert.ok(isPublicRefusal(err), 'the guard declares its refusal public');
+  assert.equal(err.code, 'control_plane_protected');
+  assert.equal(err.status, 409);
+  assert.match(err.publicMessage, /cannot be aimed at the machine the platform itself runs on/);
+  assert.match(err.message, /'teardown' cannot be aimed at the control plane/, 'the journal keeps the action it refused');
+  assert.equal(await guard.assertIntentAllowed(selfRowDb, 1, 'restart'), undefined, 'an allowed action is still allowed');
+});
+
+// ---- the routes, through the real router, enqueue helper and guard --------------
+
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner', rank: 'archon' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+const selfRow = { id: 1, slug: 'platform', owner_builder_id: 7, status: 'active', hosting_shape: 'control-plane' };
+provisioning.getInstanceById = async () => ({ ...selfRow });
+provisioning.recordEvent = async () => {};
+
+// The shared pool: the guard's shape lookup answers 'control-plane'; every other read and
+// the teardown's supersede UPDATE answer nothing. `fault` makes every query throw instead.
+let fault = null;
+api.pool.query = async (sql) => {
+  if (fault) throw fault;
+  if (/SELECT hosting_shape FROM provisioning_instances/.test(sql)) return { rows: [{ hosting_shape: 'control-plane' }] };
+  return { rows: [] };
+};
+
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/bongos', require('../modules/provisioning/routes/provisioning.js')());
+app.use('/api/bongos', require('../modules/provisioning/routes/disconnect.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+after(() => server.close());
+
+function post(p, body = {}) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`http://127.0.0.1:${server.address().port}/api/bongos${p}`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(d), raw: d }));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+const REACHABLE = [
+  ['owner teardown', '/provisioning/instances/1/teardown', {}, 'teardown_failed'],
+  ['force-teardown', '/provisioning/instances/1/force-teardown', {}, 'teardown_failed'],
+  ['disconnect', '/provisioning/instances/1/disconnect', { confirm_slug: 'platform' }, 'disconnect_failed'],
+];
+
+for (const [name, p, body, fallback] of REACHABLE) {
+  test(`${name} on the platform's own row answers 409 with the guard's sentence, not "internal error"`, async () => {
+    fault = null;
+    const r = await post(p, body);
+    assert.equal(r.status, 409, r.raw);
+    assert.equal(r.body.error.code, 'control_plane_protected');
+    assert.equal(r.body.error.message, (await guardRefusal()).publicMessage);
+  });
+
+  test(`${name}: an unexpected failure is still an opaque 500 (${fallback}) that leaks nothing`, async () => {
+    fault = new Error('relation "provisioning_intents" does not exist');
+    const r = await post(p, body);
+    fault = null;
+    assert.equal(r.status, 500, r.raw);
+    assert.deepEqual(r.body.error, { code: fallback, message: 'internal error' });
+  });
+}
+
+// ---- the ratchet ------------------------------------------------------------------
+
+// Every `catch (e) { … }` / `catch { … }` body in a file, with the line it opens on. A
+// promise's `.catch(() => …)` is not a catch block and is not matched.
+function catchBodies(src) {
+  const out = [];
+  const re = /\bcatch\s*(?:\(\s*\w*\s*\))?\s*\{/g;
+  for (let m = re.exec(src); m; m = re.exec(src)) {
+    let depth = 1;
+    let i = re.lastIndex;
+    for (; i < src.length && depth; i++) depth += src[i] === '{' ? 1 : src[i] === '}' ? -1 : 0;
+    out.push({ line: src.slice(0, m.index).split('\n').length, body: src.slice(re.lastIndex, i - 1) });
+  }
+  return out;
+}
+
+test('no catch in the provisioning module answers a 5xx except through failFrom', () => {
+  const dir = path.join(ROOT, 'modules', 'provisioning');
+  const files = fs.readdirSync(dir, { recursive: true }).map(String)
+    .filter((f) => f.endsWith('.js') && !f.split(path.sep).includes('tests'));
+  const HAND_ROLLED_5XX = /res\.fail\([^;]*?(status:\s*5\d\d|,\s*5\d\d\s*[,)])/;
+  const offenders = [];
+  let viaHelper = 0;
+  for (const f of files) {
+    for (const c of catchBodies(fs.readFileSync(path.join(dir, f), 'utf8'))) {
+      if (HAND_ROLLED_5XX.test(c.body)) offenders.push(`${f}:${c.line}`);
+      if (/\bfailFrom\(res, /.test(c.body)) viaHelper++;
+    }
+  }
+  assert.deepEqual(offenders, [], 'answer with failFrom(res, err, <code>) so a declared refusal can reach the person');
+  assert.ok(viaHelper >= 20, `the scan must reach the converted catches (24 at task 1004126), saw ${viaHelper}`);
+});
+
+test('the ratchet reads a hand-rolled 500 in a catch, and not one outside a catch', () => {
+  const src = "try { a(); } catch (err) {\n  log.error('x', err);\n  res.fail('x_failed', { status: 500, message: 'internal error' });\n}\nres.fail('config_unset', { status: 500, message: 'no origin' });\n"
+    + "p.catch(() => {});\ntry { b(); } catch { res.fail('y_failed', 500); }";
+  const bodies = catchBodies(src);
+  assert.equal(bodies.length, 2, 'a catch with no binding counts; a promise .catch does not');
+  assert.match(bodies[1].body, /y_failed/);
+  assert.match(bodies[0].body, /x_failed/);
+  assert.doesNotMatch(bodies[0].body, /config_unset/, 'a config refusal outside a catch is a real sentence, not a swallowed error');
+});

package/tests/publish_status_branch.mjs

@@ -0,0 +1,128 @@
+// tests/publish_status_branch.mjs — GET /tasks/:id/publish-status finds the task's
+// branch itself when the caller names none (task 1003764, gap 1).
+//
+// WHY. This route is the diagnostic every agent is told to use INSTEAD of raw git
+// probes (push-path-brief.js, the stuck-strike nudge), and it required ?branch=. Called
+// the way those briefs spell it — no query — it answered 400 bad_branch for task
+// 1003747 while origin carried its live, server-pushed branch and PR 673 sat open. The
+// sanctioned diagnostic was the one thing that could not diagnose a live publish.
+//
+// Drives the real route handler with fake req/res and stubbed github-push reads: no
+// DB, no server, no network. Run:  node tests/publish_status_branch.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const gp = require('../modules/lifecycle/github-push.js');
+const buildTasksRouter = require('../modules/lifecycle/routes/tasks.js');
+
+let pass = 0;
+let fail = 0;
+const t = async (name, fn) => {
+  try { await fn(); pass++; console.log(`PASS  ${name}`); }
+  catch (e) { fail++; console.log(`FAIL  ${name}\n      ${e.stack || e.message}`); }
+};
+
+const CRED_KEYS = ['GITHUB_PUSH_TOKEN', 'GITHUB_APP_ID', 'GITHUB_APP_INSTALLATION_ID', 'GITHUB_APP_PRIVATE_KEY'];
+
+// Stub the github-push reads the route makes, run the handler once, restore everything.
+// `calls` records what the route asked GitHub for, so a test can prove what it did NOT do.
+async function callRoute(query, stubs = {}) {
+  const saved = {};
+  for (const k of ['findTaskPullRequest', 'getPublishStatus', 'mergeIfGreen']) saved[k] = gp[k];
+  const savedEnv = CRED_KEYS.map((k) => [k, process.env[k]]);
+  const calls = { findTaskPullRequest: [], getPublishStatus: [], mergeIfGreen: [] };
+  gp.findTaskPullRequest = async (a) => { calls.findTaskPullRequest.push(a); return stubs.taskPr === undefined ? null : stubs.taskPr; };
+  gp.getPublishStatus = async (a) => {
+    calls.getPublishStatus.push(a);
+    return stubs.status || { pr_state: 'open', merged: false, merge_sha: null, deploy_status: 'pending', pr_url: 'https://github.test/pr/673', pr_number: 673 };
+  };
+  gp.mergeIfGreen = async (a) => { calls.mergeIfGreen.push(a); return stubs.mergeDriver || { reason: 'failing_check:unit', failing_tests: '1 failed: fitness' }; };
+  for (const k of CRED_KEYS) delete process.env[k];
+  process.env.GITHUB_PUSH_TOKEN = 'ghp_fake_for_isConfigured';
+  try {
+    const router = buildTasksRouter();
+    const layer = router.stack.find((l) => l.route && l.route.path === '/tasks/:id/publish-status' && l.route.methods.get);
+    const handler = layer.route.stack[layer.route.stack.length - 1].handle;
+    const out = { failCode: null, failOpts: null, body: null };
+    const res = {
+      status() { return this; },
+      json(b) { out.body = b; return this; },
+      fail(code, opts) { out.failCode = code; out.failOpts = opts; return this; },
+    };
+    // rank archon → gateTaskOwnership passes without a DB lookup, keeping this hermetic.
+    await handler({ params: { id: '1003747' }, query, builder: { id: 25, rank: 'archon' } }, res);
+    return { ...out, calls };
+  } finally {
+    Object.assign(gp, saved);
+    for (const [k, v] of savedEnv) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+  }
+}
+
+await t('no ?branch= → the route finds the task\'s own PR branch instead of answering 400 (the task 1003747 repro)', async () => {
+  const r = await callRoute({}, { taskPr: { branch: 'task-1003747', pr_number: 673, pr_state: 'open', merged: false } });
+  assert.equal(r.failCode, null, `must not refuse — got ${r.failCode}`);
+  assert.equal(r.body.ok, true);
+  assert.equal(r.body.branch, 'task-1003747', 'reports which branch it answered about');
+  assert.equal(r.body.branch_source, 'task_pr', 'and how it found it');
+  assert.deepEqual(r.calls.findTaskPullRequest, [{ taskId: 1003747 }], 'looked the PR up by THIS task id');
+  assert.deepEqual(r.calls.getPublishStatus, [{ branch: 'task-1003747' }]);
+  assert.equal(r.body.pr_number, 673);
+  // The whole point: the red check is now one call away, not twenty minutes of git.
+  assert.equal(r.body.merge_driver.failing_tests, '1 failed: fitness');
+  assert.deepEqual(r.calls.mergeIfGreen, [{ branch: 'task-1003747' }]);
+});
+
+await t('no ?branch= and no PR for the task → 200 "none" with a hint, never a 400, and nothing else is probed', async () => {
+  const r = await callRoute({}, { taskPr: null });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.ok, true);
+  assert.equal(r.body.pr_state, 'none');
+  assert.equal(r.body.merged, false);
+  assert.equal(r.body.branch, null);
+  assert.equal(r.body.branch_source, null);
+  assert.match(r.body.branch_hint, /\?branch=/, 'says how to ask about a specific branch');
+  assert.equal(r.body.reconciled, false);
+  assert.equal(r.body.merge_driver, null);
+  assert.deepEqual(r.calls.getPublishStatus, [], 'no branch → no branch-status read');
+  assert.deepEqual(r.calls.mergeIfGreen, [], 'no PR → the merge driver never runs');
+});
+
+await t('an empty ?branch= is treated as absent, not as a bad branch', async () => {
+  const r = await callRoute({ branch: '' }, { taskPr: { branch: 'task-1003747', pr_number: 673 } });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.branch_source, 'task_pr');
+});
+
+await t('an explicit ?branch= still wins, and the task-PR lookup is skipped', async () => {
+  const r = await callRoute({ branch: 'claude/some-worktree' });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.branch, 'claude/some-worktree');
+  assert.equal(r.body.branch_source, 'query');
+  assert.deepEqual(r.calls.findTaskPullRequest, [], 'the caller named the branch; nothing to look up');
+  assert.deepEqual(r.calls.getPublishStatus, [{ branch: 'claude/some-worktree' }]);
+});
+
+await t('a fully-qualified refs/heads/<branch> names the same branch and is accepted', async () => {
+  const r = await callRoute({ branch: 'refs/heads/task-1003747' });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.branch, 'task-1003747');
+  assert.deepEqual(r.calls.getPublishStatus, [{ branch: 'task-1003747' }]);
+});
+
+await t('a genuinely unsafe branch is still refused 400 — in a sentence, before any GitHub call', async () => {
+  for (const branch of ['-rf', 'a/../../etc', 'refs/tags/x', ['a', 'b']]) {
+    const r = await callRoute({ branch });
+    assert.equal(r.failCode, 'bad_branch', `${JSON.stringify(branch)} must be refused`);
+    assert.equal(r.failOpts.status, 400);
+    assert.match(r.failOpts.message, /left out/, 'the refusal says the branch can simply be omitted');
+    assert.deepEqual(r.calls.findTaskPullRequest, []);
+    assert.deepEqual(r.calls.getPublishStatus, []);
+  }
+});
+
+console.log(`\npublish-status branch resolution (task 1003764): ${pass} passed, ${fail} failed`);
+process.exitCode = fail > 0 ? 1 : 0;

package/tests/ship_land_red_pr.mjs

@@ -0,0 +1,236 @@
+// tests/ship_land_red_pr.mjs — a stalled land names its red check (task 1003764, gap 2).
+//
+// WHY. Task 1003747's ship sat at "waiting for auto-merge + prod deploy" while a
+// required check was red, and ended on "This is NOT a failure". The cause — CI tests
+// the branch MERGED with main, and main had moved six commits, staling the copy
+// registry in the merged tree only — took ~20 minutes of git archaeology to find,
+// though it was one API call away. The laptop poll (pollCiDeploy) never looked at
+// checks at all; the server poll named them but not the merge trap, and not how a
+// freshness gate heals. These drive both polls with fake gh / server reads (no
+// network, no sleeping) and pin the pure pieces they are built from.
+//
+// Run:  node tests/ship_land_red_pr.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import {
+  FRESHNESS_TESTS, failingTestNames, landPendingLines, localMergeDriver, mergeTrapLines,
+  pollCiDeploy, pollServerPublish, redBlocksMerge, redPrLines, unitReportFor,
+} from '../scripts/gds/ship-land.js';
+
+const require = createRequire(import.meta.url);
+const githubPush = require('../modules/lifecycle/github-push.js');
+const { CARDS } = require('../scripts/gds/plain-cards.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// Run fn with console.log captured; returns { result, out }.
+async function capture(fn) {
+  const lines = [];
+  const orig = console.log;
+  console.log = (...a) => { lines.push(a.join(' ')); };
+  try { return { result: await fn(), out: lines.join('\n'), lines }; }
+  finally { console.log = orig; }
+}
+
+const SHA = 'a'.repeat(40);
+// What `gh pr view --json state,mergeCommit,mergeStateStatus,headRefOid,statusCheckRollup`
+// really returns (shape taken from a live PR on this repo): check runs, then statuses.
+const run = (name, conclusion, status = 'COMPLETED') => ({ __typename: 'CheckRun', name, conclusion, status, workflowName: 'unit' });
+const ctx = (context, state) => ({ __typename: 'StatusContext', context, state, targetUrl: '' });
+const openPr = (rollup, mergeStateStatus = 'BLOCKED') => ({ state: 'OPEN', mergeCommit: null, mergeStateStatus, headRefOid: SHA, statusCheckRollup: rollup });
+const RED_ROLLUP = [run('unit', 'FAILURE'), run('report', 'SUCCESS'), ctx('gate-author-trust', 'SUCCESS'), ctx('unit-report', 'FAILURE')];
+const COMBINED_STATUS = { state: 'failure', statuses: [
+  { context: 'gate-author-trust', state: 'success', description: 'Metic+ author' },
+  { context: 'unit-report', state: 'failure', description: '1 failed: fitness' },
+] };
+
+// ---- localMergeDriver: the laptop's view of a red PR, in publish-status's shape ----
+
+await test('localMergeDriver names the failing required check and asks for the tests once the report is posted', async () => {
+  const asked = [];
+  const md = localMergeDriver(openPr(RED_ROLLUP), (sha) => { asked.push(sha); return '1 failed: fitness'; });
+  assert.deepEqual(md, { reason: 'failing_check:unit', failing_tests: '1 failed: fitness' });
+  assert.deepEqual(asked, [SHA], 'the unit-report is read for the PR head sha');
+});
+
+await test('localMergeDriver does not ask for tests before the unit-report status exists', async () => {
+  let asked = 0;
+  const md = localMergeDriver(openPr([run('unit', 'FAILURE')]), () => { asked++; return 'x'; });
+  assert.deepEqual(md, { reason: 'failing_check:unit', failing_tests: null });
+  assert.equal(asked, 0);
+});
+
+await test('localMergeDriver: pending, expected and in-progress are waiting, not red', async () => {
+  for (const rollup of [
+    [run('unit', '', 'IN_PROGRESS')],
+    [ctx('unit-report', 'PENDING')],
+    [ctx('some-required-status', 'EXPECTED')],
+    [run('unit', 'SUCCESS'), run('lint', 'NEUTRAL'), run('docs', 'SKIPPED'), ctx('unit-report', 'SUCCESS')],
+  ]) assert.equal(localMergeDriver(openPr(rollup)), null, JSON.stringify(rollup));
+});
+
+await test('localMergeDriver: an UNSTABLE PR means the failing check is optional', async () => {
+  assert.equal(localMergeDriver(openPr([run('lint', 'FAILURE')], 'UNSTABLE')).reason, 'non_required_check_failing:lint');
+});
+
+await test('localMergeDriver: nothing to say for a merged/closed PR, or a gh that returned no rollup', async () => {
+  assert.equal(localMergeDriver(null), null);
+  assert.equal(localMergeDriver({ ...openPr(RED_ROLLUP), state: 'MERGED' }), null);
+  assert.equal(localMergeDriver({ state: 'OPEN', mergeCommit: null }), null, 'the legacy two-field read has no rollup');
+});
+
+await test('localMergeDriver agrees with the server\'s mergeBlockReason on a red required check', async () => {
+  const server = githubPush.mergeBlockReason({
+    merged: false, pr_state: 'open', mergeable: 'MERGEABLE', merge_state: 'BLOCKED', review_decision: null,
+    rollup_state: 'FAILURE', checks: [{ name: 'unit', conclusion: 'FAILURE', status: 'COMPLETED' }], checks_unreadable: false,
+  });
+  assert.equal(localMergeDriver(openPr([run('unit', 'FAILURE')])).reason, server);
+});
+
+// ---- unitReportFor: the failing-test line, via the same parser the server uses ----
+
+await test('unitReportFor reads the unit-report status for the sha', async () => {
+  const calls = [];
+  const text = unitReportFor(SHA, (args) => { calls.push(args); return COMBINED_STATUS; });
+  assert.equal(text, '1 failed: fitness');
+  assert.deepEqual(calls, [['api', `repos/{owner}/{repo}/commits/${SHA}/status`]]);
+});
+
+await test('unitReportFor: a green report, an unreadable one, or a bad sha → null (and a bad sha never reaches gh)', async () => {
+  assert.equal(unitReportFor(SHA, () => ({ statuses: [{ context: 'unit-report', state: 'success', description: 'all unit tests passed' }] })), null);
+  assert.equal(unitReportFor(SHA, () => null), null);
+  assert.equal(unitReportFor('HEAD; rm -rf /', () => { throw new Error('must not call gh'); }), null);
+});
+
+// ---- the merge trap + the freshness heal ----
+
+await test('failingTestNames parses the unit-report line and drops a name the status limit cut', async () => {
+  assert.deepEqual(failingTestNames('1 failed: fitness'), ['fitness']);
+  assert.deepEqual(failingTestNames('3 failed: api_docs, fitness, security'), ['api_docs', 'fitness', 'security']);
+  assert.deepEqual(failingTestNames('40 failed: a_test, b_test, some_lo…'), ['a_test', 'b_test']);
+  assert.deepEqual(failingTestNames(null), []);
+  assert.deepEqual(failingTestNames('all unit tests passed'), []);
+});
+
+await test('every name in FRESHNESS_TESTS is a real test file', async () => {
+  for (const name of FRESHNESS_TESTS) {
+    assert.ok(fs.existsSync(new URL(`./${name}.mjs`, import.meta.url)), `tests/${name}.mjs does not exist`);
+  }
+});
+
+await test('every red PR names the trap: CI tests the MERGE, not the branch', async () => {
+  const local = mergeTrapLines({ reason: 'failing_check:unit' }, { taskId: 42, via: 'local' }).join('\n');
+  assert.match(local, /MERGED with the current main, not the branch alone/);
+  assert.match(local, /git fetch origin && git merge origin\/main/, 'the laptop can reproduce on the merge');
+  const server = mergeTrapLines({ reason: 'failing_check:unit' }, { taskId: 42, via: 'server' }).join('\n');
+  assert.match(server, /MERGED with the current main/);
+  assert.ok(!/git merge origin\/main/.test(server), 'a credential-less machine cannot merge main locally — never tell it to');
+});
+
+await test('a failing freshness gate gets its healing command, per push path', async () => {
+  const md = { reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' };
+  const local = mergeTrapLines(md, { taskId: 42, via: 'local' }).join('\n');
+  assert.match(local, /`fitness` is a freshness gate/);
+  assert.match(local, /stale in the MERGED tree/);
+  assert.match(local, /node scripts\/gds\/ship\.js 42/, 'names the re-ship for THIS task');
+  assert.match(local, /ship-check\.js/);
+  const server = mergeTrapLines(md, { taskId: 42, via: 'server' }).join('\n');
+  assert.match(server, /The server regenerates stale generated files/);
+  const plain = mergeTrapLines({ reason: 'failing_check:unit-report', failing_tests: '1 failed: security' }, { taskId: 42 }).join('\n');
+  assert.ok(!/freshness gate/.test(plain), 'an ordinary failing test gets no regenerate advice');
+});
+
+await test('redPrLines: the red line first, then the trap, then the plain-words card', async () => {
+  const lines = redPrLines({ reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' }, { taskId: 42, via: 'local' });
+  assert.match(lines[0], /the PR is RED — 1 failed: fitness/);
+  assert.match(lines[1], /MERGED with the current main/);
+  const at = lines.findIndex((l) => l.includes('[otb-plain]'));
+  assert.ok(at > 2, 'the card still follows');
+  assert.ok(lines.slice(at).join('\n').includes(CARDS.failing_check.happened));
+  assert.deepEqual(redPrLines({ reason: 'review_required' }), [], 'nothing red → nothing printed');
+});
+
+await test('redBlocksMerge: only a failing REQUIRED check stops the merge', async () => {
+  assert.equal(redBlocksMerge({ reason: 'failing_check:unit' }), true);
+  assert.equal(redBlocksMerge({ reason: 'failing_check_unreadable' }), true);
+  assert.equal(redBlocksMerge({ reason: 'non_required_check_failing:lint' }), false, 'GitHub still merges an UNSTABLE PR');
+  assert.equal(redBlocksMerge(null), false);
+});
+
+await test('landPendingLines: a RED PR never gets "NOT a failure"; a green-but-slow one keeps it', async () => {
+  const red = landPendingLines(42, { red: true }).join('\n');
+  assert.ok(!/NOT a failure/.test(red), 'a failing required check does not pass by waiting');
+  assert.match(red, /RED/);
+  assert.match(red, /node scripts\/gds\/ship\.js 42/);
+  assert.match(landPendingLines(42).join('\n'), /This is NOT a failure/);
+});
+
+// ---- the two poll loops, end to end with fakes ----
+
+await test('pollCiDeploy (laptop): a red PR is named once, the trap and heal are printed, and the banner is red', async () => {
+  const seen = { prView: 0, status: 0 };
+  const gh = (args) => {
+    if (args[0] === 'pr' && args[1] === 'view') { seen.prView++; return openPr(RED_ROLLUP); }
+    if (args[0] === 'api') { seen.status++; return COMBINED_STATUS; }
+    throw new Error(`unexpected gh call: ${args.join(' ')}`);
+  };
+  const { result, out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.equal(result.pending, true, 'still a pending land — the check can yet pass');
+  assert.equal(seen.prView, 30, 'polled the whole window');
+  assert.equal(seen.status, 1, 'the unit-report is read once per head sha, not once per poll');
+  assert.equal(out.split('the PR is RED — 1 failed: fitness').length - 1, 1, 'named once, not thirty times');
+  assert.match(out, /MERGED with the current main/);
+  assert.match(out, /`fitness` is a freshness gate/);
+  assert.match(out, /node scripts\/gds\/ship\.js 42/);
+  assert.ok(!/This is NOT a failure/.test(out), 'the closing banner must not contradict the red line');
+  assert.ok(!out.includes(CARDS.land_pending.happened), 'nor the "nothing to do" card');
+});
+
+await test('pollCiDeploy: a gh that rejects the new fields falls back to the old read and still sees the merge', async () => {
+  const gh = (args) => {
+    if (args[0] === 'pr' && args.includes('state,mergeCommit')) return { state: 'MERGED', mergeCommit: { oid: 'b'.repeat(40) } };
+    if (args[0] === 'pr') return null; // unknown JSON field → gh exits non-zero → ghJson null
+    if (args[0] === 'run') return [];
+    throw new Error(`unexpected gh call: ${args.join(' ')}`);
+  };
+  const { result, out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.match(out, /merged to main \(bbbbbbbb\)/);
+  assert.equal(result.pending, true);
+});
+
+await test('pollCiDeploy: a green PR that is merely slow keeps the reassuring banner', async () => {
+  const gh = (args) => (args[0] === 'pr' ? openPr([run('unit', '', 'IN_PROGRESS')]) : null);
+  const { out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.ok(!/RED/.test(out));
+  assert.match(out, /This is NOT a failure/);
+});
+
+await test('pollServerPublish (credential-less): a failing status read is said once; a red PR gets the server-path heal', async () => {
+  let n = 0;
+  const readStatus = async () => {
+    n++;
+    if (n <= 3) return { ok: false, status: 502, data: { error: { code: 'status_failed', message: 'x' } } };
+    return { ok: true, status: 200, data: {
+      pr_state: 'open', merged: false, deploy_status: 'pending', reconcile_blocked: null,
+      merge_driver: { reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' },
+    } };
+  };
+  const { result, out } = await capture(() => pollServerPublish(42, 'task-42', { readStatus, pause: () => {} }));
+  assert.equal(result.pending, true);
+  assert.equal(out.split('could not read the land status from the server (HTTP 502 status_failed)').length - 1, 1,
+    'three identical failures are reported once');
+  assert.equal(out.split('the PR is RED — 1 failed: fitness').length - 1, 1);
+  assert.match(out, /The server regenerates stale generated files/);
+  assert.ok(!/git merge origin\/main/.test(out), 'never tells a credential-less machine to merge main');
+  assert.ok(!/This is NOT a failure/.test(out));
+});
+
+console.log(`\nship-land red PR (task 1003764) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;