@bongos/core 1.19.1033 → 1.19.1034

package/scripts/gds/provision.js

@@ -1308,7 +1308,7 @@ async function cmdRunIntents(deps) {
           await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
         }
         errors++;
-      } else { await provisioning.resolveIntent(db, intent.id, 'done', null); ok++; }
+      } else { await provisioning.resolveIntent(db, intent.id, 'done', (result && result.doneNote) || null); ok++; } // done WITH a note: it landed, and this is what it could not finish (task 1004065)
     } catch (e) {
       await provisioning.resolveIntent(db, intent.id, 'error', e.message).catch(() => {});
       // Surface the failure on the instance too, so a stuck instance is visible.

package/scripts/gds/publish-credential-check.js

@@ -16,6 +16,9 @@
 // vetoes a git-history-proven land). This tells you whether you are relying on that
 // fallback instead of a real deploy gate.
 //
+// For WHETHER each credential is set at all (names only, no network), see its sibling
+// scripts/gds/credential-presence.js and the inventory in docs/credentials.md (task 1002880).
+//
 // Exit codes: 0 = credential can read Actions (gate is real, or the workflow is
 // legitimately absent), 1 = BLIND (remediation printed), 2 = nothing to check.
 

package/scripts/gds/push-main.js

@@ -3,7 +3,7 @@
 //
 // This is the deploy step of the GRADED GDS pipeline: ship.js's auto-merge and
 // /merge-mode call it after a task has passed the grader + the Archon-only
-// confirm gate. It carries the OTB_ALLOW_MAIN_PUSH override so the SEC #863
+// confirm gate. It carries the <PREFIX>_ALLOW_MAIN_PUSH override so the SEC #863
 // pre-push hook lets the legitimate, already-gated pipeline land main while
 // still blocking an ad-hoc `git push origin main` (the Builder 25 move).
 //
@@ -22,11 +22,22 @@
 'use strict';
 
 const { execFileSync } = require('node:child_process');
+const { envPrefix } = require('../../src/instance-config');
+
+// The push's environment: the caller's, plus the override under its CANONICAL
+// spelling for this instance — <PREFIX>_ALLOW_MAIN_PUSH, BONGOS_ on a vanilla
+// instance (task 1001441). The hook reads it through resolveEnv, where the
+// canonical name is tried first; writing the legacy OTB_ spelling instead would
+// still work until the legacy prefixes retire, and would earn a deprecation
+// warning on every deploy push in the meantime.
+function pushEnv(env = process.env) {
+  return { ...env, [`${envPrefix()}_ALLOW_MAIN_PUSH`]: '1' };
+}
 
 function pushMain(extra = []) {
   execFileSync('git', ['push', 'origin', 'main', ...extra], {
     stdio: 'inherit',
-    env: { ...process.env, OTB_ALLOW_MAIN_PUSH: '1' },
+    env: pushEnv(),
     shell: false,
   });
 }
@@ -42,4 +53,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { pushMain };
+module.exports = { pushMain, pushEnv };

package/scripts/gds/push-path-brief.js

@@ -30,7 +30,8 @@
 //   node scripts/gds/push-path-brief.js          # human-readable: which path + why
 //   node scripts/gds/push-path-brief.js --line   # ONE line or nothing; always exit 0
 //
-// Detection override (tests / forcing): OTB_PUSH_VIA_SERVER=1 (server) / =0 (local).
+// Detection override (tests / forcing): <PREFIX>_PUSH_VIA_SERVER=1 (server) / =0 (local)
+// — BONGOS_PUSH_VIA_SERVER on a vanilla instance; the legacy OTB_ spelling is still read.
 
 const { hasFlag } = require('./cli-lib');
 const { plainCardLines } = require('./plain-cards');
@@ -56,7 +57,7 @@ function briefLine(via) {
 // ---- detection ---------------------------------------------------------------
 
 // Lazy require so a broken or partial checkout degrades to silence, not a stack
-// trace injected into the session. pushVia() honors OTB_PUSH_VIA_SERVER, else
+// trace injected into the session. pushVia() honors <PREFIX>_PUSH_VIA_SERVER, else
 // probes for an authenticated gh (absent on every box → 'server' instantly).
 function detectVia() {
   return require('./ship-deploy-target.js').pushVia();

package/scripts/gds/run-routine.js

@@ -15,7 +15,7 @@
 //
 // Each step routes its stdout by `sink: discord|gds|none`. A failed step exits
 // non-zero after a best-effort #ops alert. Runs the steps with
-// OTB_COST_CRON_ROUTINE set so System 1 tags any (hybrid) model spend as
+// <PREFIX>_COST_CRON_ROUTINE set so System 1 tags any (hybrid) model spend as
 // cron:<routine>. Usage: node scripts/gds/run-routine.js <routine-name> [--dry-run]
 
 'use strict';
@@ -23,7 +23,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config');
+const { resolveCoreRoot, resolveInstanceRoot, resolveEnv, envPrefix } = require('../../src/instance-config');
 
 // TWO roots (ADR 0108 configurable-root; task 2138). run-routine.js is a CORE script, so it
 // ships alongside src/, scripts/gds/*, scripts/discord/*, and modules/ — all under
@@ -39,7 +39,20 @@ const TASKS_DIR = path.join(INSTANCE_ROOT, '.claude', 'scheduled-tasks');
 const DISCORD_POST = path.join(CORE_ROOT, 'scripts', 'discord', 'post.js');
 const VALID_MODES = new Set(['deterministic', 'hybrid', 'judgment']);
 const VALID_SINKS = new Set(['discord', 'gds', 'none']);
-const ALERT_CHANNEL = process.env.OTB_ROUTINE_ALERT_CHANNEL || 'ship_feed';
+// The #ops channel a failed step alerts: <PREFIX>_ROUTINE_ALERT_CHANNEL (BONGOS_ on
+// a vanilla instance; the legacy OTB_ spelling is still read), else ship_feed.
+function alertChannel(env = process.env) {
+  return resolveEnv('ROUTINE_ALERT_CHANNEL', { env }) || 'ship_feed';
+}
+const ALERT_CHANNEL = alertChannel();
+
+// The environment a routine step runs with: the caller's, plus the routine's name
+// under the canonical <PREFIX>_COST_CRON_ROUTINE so System 1 tags any model spend
+// as cron:<routine>. session-cost.js reads it back through resolveEnv, which tries
+// the canonical spelling first (task 1001441).
+function stepEnv(routineName, env = process.env) {
+  return { ...env, [`${envPrefix()}_COST_CRON_ROUTINE`]: routineName };
+}
 
 function unquote(s) {
   const t = String(s == null ? '' : s).trim();
@@ -177,7 +190,7 @@ function runStep(step, routineName, { dryRun }) {
   const out = execFileSync(argv[0], argv.slice(1), {
     cwd: INSTANCE_ROOT, // routines run in the instance repo (companions + git-touching steps)
     encoding: 'utf8',
-    env: { ...process.env, OTB_COST_CRON_ROUTINE: routineName },
+    env: stepEnv(routineName),
   });
   routeOutput(step.sink, out, routineName);
   return out;
@@ -241,4 +254,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { parseRoutineFrontmatter, tokenize, resolveStepArgv, isNodeExec, VALID_MODES, VALID_SINKS };
+module.exports = { parseRoutineFrontmatter, tokenize, resolveStepArgv, isNodeExec, VALID_MODES, VALID_SINKS, alertChannel, stepEnv };

package/scripts/gds/run-unit-tests.js

@@ -95,8 +95,11 @@ const INTEGRATION = new Set([
   'asset_version', 'auth_flow_slice1', 'backfill_sessions', 'bfg', 'bfg_write',
   'box_connect_e2e', 'box_onboard', 'boxes', 'cf_tunnel', 'cli_token_reissue',
   // consumer_layout_boot builds the core .tgz, `npm install`s it, and boots a live
-  // platform-server — network + package build + a spawned server, run by its own
-  // .github/workflows/consumer-layout-boot.yml, not this DB-free gate (task 2142).
+  // platform-server (task 2142), then installs the package from its own shipped lockfile,
+  // migrates brand-new EMPTY databases and serves a database-backed route from one (task
+  // 1002863) — network + package build + spawned servers + Postgres. It runs in the
+  // integration job of .github/workflows/integration.yml like the rest of this set; there
+  // never was a dedicated consumer-layout-boot workflow, whatever older notes say.
   'consumer_layout_boot',
   'claim_gate_open_blocker', 'claim_gate_rebase',
   // task 1002709: core_221's re-keyed backstop index against a real Postgres.
@@ -408,11 +411,19 @@ function discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEna
 // scripts/gds/smoke-box.sh still invokes all three by path — deleting the files
 // turned that script into an immediate MODULE_NOT_FOUND. They come out when the
 // module does, in the change that removes it.
+//
+// consumer_layout_boot LEFT THIS LIST under task 1002863. Its "missing core tarball" was
+// package-core's fail-closed leak gate reading the lane's throwaway database password (the
+// word postgres, present in hundreds of core files) as a leaked credential and refusing to
+// build. The harness now withholds database settings from the packager, and it is the only
+// test that proves the PUBLISHED package installs, migrates an empty database and serves
+// from it — parking it again re-opens that gap, which tests/integration_parked_ratchet.mjs
+// now says out loud.
 const INTEGRATION_PARKED = new Set([
   'acclaim_feed_evidence_db',
   'bfg', 'bfg_write', 'box_connect_e2e', 'box_onboard', 'boxes',
   'claim_gate_open_blocker', 'claim_gate_rebase',
-  'clawback_confirmed_backlog', 'consumer_layout_boot', 'copy_desk_flags_db',
+  'clawback_confirmed_backlog', 'copy_desk_flags_db',
   'government_board_membership_db', 'handle_machinery', 'hub_profile_leak',
   'idea_credit_streams_db', 'memory_isolation', 'memory_pull', 'needs_rebase',
   'profile_fields', 'project_visibility_db', 'reward_mode_cost_plus_only',

package/scripts/gds/session-cost.js

@@ -27,6 +27,7 @@ const os = require('os');
 const path = require('path');
 const { cliClient, loadSession, arg } = require('./cli-lib');
 const { priceUsage } = require('../../src/bongos/llm-pricing');
+const { resolveEnv } = require('../../src/instance-config');
 
 
 // Claude Code encodes a project transcript dir by replacing every non-alnum
@@ -256,9 +257,16 @@ function priceSubagents(sessionDir) {
 // into TWO call-site-tagged rows — source='<base>:interactive' (source_ref =
 // sessionId) and '<base>:subagent' (source_ref = sessionId+':sub'), distinct on
 // the (source,source_ref) idempotency index — each carrying its tier split. A
-// cron-launched session sets OTB_COST_CRON_ROUTINE=<name> so base='cron:<name>'
+// cron-launched session sets <PREFIX>_COST_CRON_ROUTINE=<name> so base='cron:<name>'
 // instead of 'session'. The rows' amounts reconcile to the prior single-row
 // figure (priorSingle vs rowsTotal, equal within independent-rounding epsilon).
+// The routine a cron-launched session belongs to, or ''. run-routine.js writes
+// the canonical <PREFIX>_COST_CRON_ROUTINE (stepEnv); a legacy OTB_ spelling set
+// by an older runner is still read, with a deprecation warning (task 1001441).
+function cronRoutineFromEnv(env = process.env) {
+  return (resolveEnv('COST_CRON_ROUTINE', { env }) || '').trim();
+}
+
 function buildCostRows({ sessionId, inter, sub, cronRoutine }) {
   const base = cronRoutine ? `cron:${cronRoutine}` : 'session';
   const id8 = String(sessionId).slice(0, 8);
@@ -350,8 +358,8 @@ async function main() {
     if (!(total > 0)) return;
 
     // task 1344: split into call-site-tagged, tier-carrying rows; cron sessions
-    // are tagged via OTB_COST_CRON_ROUTINE.
-    const cronRoutine = (process.env.OTB_COST_CRON_ROUTINE || '').trim();
+    // are tagged via <PREFIX>_COST_CRON_ROUTINE (see cronRoutineFromEnv).
+    const cronRoutine = cronRoutineFromEnv();
     const built = buildCostRows({ sessionId, inter, sub, cronRoutine });
     const id8 = sessionId.slice(0, 8);
 
@@ -414,6 +422,7 @@ module.exports = {
   newestTranscriptFor,
   // task 1344 — pure tier-split + row-building helpers (unit-tested)
   buildCostRows,
+  cronRoutineFromEnv,
   emptyTiers,
   addComponents,
   addTiers,

package/scripts/gds/ship-deploy-target.js

@@ -12,13 +12,17 @@ const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const { loadSessionSync } = require('./cli-lib');
+// The two env overrides below resolve through the branded prefix — <PREFIX>_DEPLOY_MODE /
+// <PREFIX>_PUSH_VIA_SERVER (BONGOS_ on a vanilla instance) — with the legacy OTB_ spelling
+// still honoured and warned about (task 1001441, R61 follow-up).
+const { resolveEnv } = require('../../src/instance-config');
 const { argvOk, argvOut } = require('./ship-git.js');
 const { REPO_ROOT } = require('./ship-state.js');
 
 // ---------- CI deploy mode (#679, ADR 0042) ----------
 //
 // Two ways the confirmed→shipped land can run, chosen by a SINGLE committed
-// switch (config/deploy.json `mode`, env OTB_DEPLOY_MODE overrides):
+// switch (config/deploy.json `mode`, env <PREFIX>_DEPLOY_MODE overrides):
 //
 //   'laptop' (default) — the operator's machine merges to main locally and, IFF a
 //      deploy target is configured (config/deploy.json "sshTarget" or
@@ -63,7 +67,7 @@ function parseDeployMode(envVal, configRaw) {
 // it must ship via the 'ci' server-mediated publish path instead
 // (pushVia()==='server', ADR 0055), which lets the GDS server push with its own
 // credential. So when the parsed mode is 'laptop' but the machine can't push
-// locally AND the mode was NOT pinned by an explicit OTB_DEPLOY_MODE, fall back to
+// locally AND the mode was NOT pinned by an explicit <PREFIX>_DEPLOY_MODE, fall back to
 // 'ci' rather than strand every ship at merge. This is the scootermack 2026-06-22
 // case: a checkout left at the pre-cutover 'laptop' default that can't pull
 // forward to 'ci', so it kept attempting a push it had no credential for. An
@@ -109,9 +113,10 @@ function mainIsProtected() {
 
 function resolveDeployMode() {
   const configRaw = readDeployConfigRaw();
-  const mode = parseDeployMode(process.env.OTB_DEPLOY_MODE, configRaw);
+  const envMode = resolveEnv('DEPLOY_MODE');
+  const mode = parseDeployMode(envMode, configRaw);
   const envForced = ['ci', 'laptop'].includes(
-    String(process.env.OTB_DEPLOY_MODE || '').trim().toLowerCase()
+    String(envMode || '').trim().toLowerCase()
   );
   // Probe `gh` ONLY when it can change the answer (resolved 'laptop', no env
   // override) — the happy 'ci' path and an env-pinned mode spawn no extra gh,
@@ -313,7 +318,7 @@ function fetchDeployedVersion(url = deployedVersionUrl()) {
 //              credential-less origin). ship uploads a thin branch bundle to the
 //              GDS, which pushes + opens the PR + auto-merges with the SERVER's
 //              credential. The box holds nothing (#919 model preserved).
-// Override with OTB_PUSH_VIA_SERVER=1 (force server) / =0 (force local) for tests.
+// Override with <PREFIX>_PUSH_VIA_SERVER=1 (force server) / =0 (force local) for tests.
 function ghAvailableAndAuthed() {
   try {
     const a = spawnSync('gh', ['auth', 'status'], {
@@ -329,7 +334,7 @@ function ghAvailableAndAuthed() {
 }
 
 function pushVia() {
-  const o = String(process.env.OTB_PUSH_VIA_SERVER || '').trim();
+  const o = String(resolveEnv('PUSH_VIA_SERVER') || '').trim();
   if (o === '1') return 'server';
   if (o === '0') return 'local';
   // No explicit override: a machine that can run an authenticated gh (laptop)

package/scripts/gds/ship-grade-steps.js

@@ -20,6 +20,8 @@ const { plainCardLines } = require('./plain-cards.js');
 // gives, and the two can never drift.
 const { preflightChecks } = require('./preflight.js');
 const { computeRawDiffHash, reconstructPanelIssues, runNoArtifactGrader, runSubagentGrader, shouldReuseGrade } = require('./ship-grade.js');
+// task 1002903: the severity gate's own reading of which low scores had no finding.
+const { unbackedLowScores } = require('../../modules/grading/grader-workers/worker-verdict.js');
 
 // ---------- Shared grade-step helpers (used by shipMain AND regradeMain) ----------
 //
@@ -396,6 +398,37 @@ function formatGradeOutcome(g, taskId, cliFinding = null) {
     return out.join('\n');
   }
 
+  // task 1002903: a reviewer scored below threshold and named NO major/blocker
+  // finding, so the severity gate (task 1002663) downgraded it — the ship parks for
+  // a human rather than hard-failing. The ordinary block below would print "FAIL"
+  // and "Fix the issues above" over an empty list, which is how task 1002721's
+  // builder read a real grade as a broken one. Sits below the outage and
+  // authorization shapes, and steps aside when any finding IS substantive or a
+  // gating worker hard-failed (then the ordinary block and its findings apply).
+  // The record's own list wins; the workers are the fallback for a grade written
+  // before signals.unbacked_scores existed.
+  const gradeThreshold = Number(g.threshold);
+  const unbacked = Array.isArray(g.signals?.unbacked_scores)
+    ? g.signals.unbacked_scores
+    : Number.isFinite(gradeThreshold) ? unbackedLowScores(g.signals?.workers, { threshold: gradeThreshold }) : [];
+  const hasSubstantive = (g.issues || []).some((i) => i && (i.severity === 'blocker' || i.severity === 'major'));
+  if (!g.passed && unbacked.length > 0 && !hasSubstantive && g.signals?.panel_outcome !== 'fail') {
+    out.push('');
+    out.push(`Subagent grade: NOT PASSED — UNBACKED LOW SCORE  ·  a reviewer scored below ${g.threshold ?? '?'} without naming a finding — NOT a findings-backed rejection`);
+    for (const u of unbacked) {
+      out.push(`  ${u.kind}: ${u.axis} ${u.score}/10 — no major or blocker finding stands behind it`);
+    }
+    if (g.notes_md) out.push(g.notes_md.split('\n').map((l) => '  ' + l).join('\n'));
+    out.push('');
+    out.push('There is nothing listed to fix. The severity gate does not let an unbacked score hard-fail a ship, so the task stays at completed for a human instead.');
+    out.push('Re-grade once — an unbacked score often does not repeat:');
+    out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
+    out.push('If it repeats on work you can defend, file an override-request with your evidence (recorded; an Archon decides):');
+    out.push(`  node scripts/gds/api.js POST /api/bongos/tasks/${taskId}/override-request --body-file rationale.json   # {"rationale":"<why the grade is wrong, specifically>"}`);
+    out.push(...plainCardLines('grade_unbacked_score'));
+    return out.join('\n');
+  }
+
   const verdict = g.passed ? 'PASS' : 'FAIL';
   out.push('');
   out.push(`Subagent grade: ${verdict}  ·  blended ${g.score}/10  ·  threshold ${g.threshold} (both axes)`);

package/scripts/gds/ship-land.js

@@ -16,6 +16,9 @@ const { gitArgvOk, gitOk, sanitizeGitHubRefs, shellOk } = require('./ship-git.js
 const { buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded, deployedCommitStatus, fetchDeployedVersion, ghArgvOk, ghJson, pushVia, resolveInstanceBase } = require('./ship-deploy-target.js');
 const { normalizeApiError } = require('./ship-io.js');
 const { plainCardLines } = require('./plain-cards.js');
+// The server's own reader of a PR's check rollup (task 1003988), reused so the laptop
+// poll names a red PR exactly the way publish-status does (task 1003764). Dependency-free.
+const { readCheckRollup, UNIT_REPORT_CONTEXT } = require('../../modules/lifecycle/check-rollup.js');
 
 // ---------- the land outcome (task 1002541, part 1) ----------
 //
@@ -284,7 +287,19 @@ function strandNextStep(taskId, via) {
 // too: the server flags a strand needs_rebase (definitive shapes within a sweep,
 // ambiguous ones at ~30 min), /builder-start warns, and new claims gate on it.
 // Pure + exported so the wording is pinned by tests/ship_ci_deploy.mjs.
-function landPendingLines(taskId, { merged } = {}) {
+//
+// task 1003764: `red` — the PR was RED on the poll's last read. "NOT a failure" is then
+// false: a required check that failed does not pass by waiting, so the banner says the
+// land is stuck on it and defers to the red lines above for the remedy.
+function landPendingLines(taskId, { merged, red } = {}) {
+  if (red) {
+    return [
+      '  ci-land: Published, but the PR is RED (the check named above), so it has NOT merged and will not',
+      '  until that check passes. The task stays at \'confirmed\'. Do what the lines above say, then re-run',
+      `  \`node scripts/gds/ship.js ${taskId}\` — it resumes from here (task 941). If it stays red, the server flags`,
+      '  the task needs_rebase — /builder-start will warn you and new claims are gated until it lands or is released.',
+    ];
+  }
   return [
     `  ci-land: ✓ Published — auto-merge is armed${merged ? ' and the PR has merged' : ''}. This is NOT a failure.`,
     `  CI is still finishing; GitHub will ${merged ? 'deploy' : 'merge + deploy'} automatically once the required checks pass,`,
@@ -298,7 +313,9 @@ function landPendingLines(taskId, { merged } = {}) {
 function printLandPending(taskId, opts = {}) {
   console.log('');
   for (const line of landPendingLines(taskId, opts)) console.log(line);
-  for (const line of plainCardLines('land_pending')) console.log(line);
+  // The land_pending card says there is nothing to do, which a red PR makes untrue; the
+  // red line already printed the failing_check card (task 1003764).
+  if (!opts.red) for (const line of plainCardLines('land_pending')) console.log(line);
 }
 
 // task 1002645 — the honest close-out when the PR MERGED but the server refused the
@@ -349,9 +366,97 @@ function redPrLine(md) {
 // redPrLines — the red line followed by the same reason in plain words (task 1003989).
 // The card is keyed on the merge reason; when the failing tests were readable that
 // reason is `failing_check:<name>`, which resolves to the failing_check card.
-function redPrLines(md) {
+// task 1003764: the merge trap sits between them. `opts` = { taskId, via } for its wording.
+function redPrLines(md, opts = {}) {
   const red = redPrLine(md);
-  return red ? [red, ...plainCardLines((md && md.reason) || 'failing_check')] : [];
+  return red ? [red, ...mergeTrapLines(md, opts), ...plainCardLines((md && md.reason) || 'failing_check')] : [];
+}
+
+// The unit tests that gate GENERATED files — each compares a committed artifact with a
+// fresh build of it. `fitness` holds the combined gate (fitness.js "generated artifacts
+// fresh": copy registry, API docs, file map, nested CLAUDE.md blocks, the §13 snippet).
+// tests/ship_land_red_pr.mjs fails if one of these names stops being a real test file.
+const FRESHNESS_TESTS = new Set(['fitness', 'api_docs', 'api_client', 'file_map', 'repo_map', 'session_index', 'interaction_posture']);
+
+// failingTestNames — "2 failed: a, b" (the unit-report line, run-unit-tests.js
+// describeFailures) → ['a', 'b']. A line cut at the status limit ends in '…'; the cut
+// name is dropped rather than guessed at. Pure.
+function failingTestNames(text) {
+  const m = /^\s*\d+\s+failed:\s*(.*)$/.exec(String(text || ''));
+  if (!m) return [];
+  const names = m[1].split(',').map((s) => s.trim()).filter(Boolean);
+  if (names.length && names[names.length - 1].endsWith('…')) names.pop();
+  return names;
+}
+
+// mergeTrapLines — task 1003764. CI tests the MERGE, not the branch: a pull_request run
+// checks out the PR merged into the CURRENT main, so a branch that was green when pushed
+// goes red when main moves under it, and re-running the test on the branch shows nothing
+// wrong. Task 1003747's land sat "waiting" for ~20 minutes of git archaeology on exactly
+// that — main moved six commits, the copy registry went stale in the merged tree only.
+// Every red PR gets the trap named; a failing freshness gate also gets its healing command,
+// which differs by push path (a credential-less machine cannot merge main locally, and the
+// server heals it for them — publish-reconciler refreshStaleGenerated). Pure + exported.
+function mergeTrapLines(md, { taskId = '<id>', via = 'local' } = {}) {
+  const lines = [
+    '  ci-land: CI tests your branch MERGED with the current main, not the branch alone — if the failure',
+    via === 'server'
+      ? '  does not reproduce on your branch, main moved under the PR after it was pushed.'
+      : '  does not reproduce on your branch, main moved under it: `git fetch origin && git merge origin/main`, then re-run it.',
+  ];
+  const gates = failingTestNames(md && md.failing_tests).filter((n) => FRESHNESS_TESTS.has(n));
+  if (!gates.length) return lines;
+  const named = gates.map((g) => `\`${g}\``).join(', ');
+  lines.push(`  ci-land: ${named} ${gates.length > 1 ? 'are freshness gates' : 'is a freshness gate'}, so "fix it" here means regenerate: a generated file (copy`);
+  lines.push('  registry, API docs, repo map…) is stale in the MERGED tree even though your branch was fresh.');
+  if (via === 'server') {
+    lines.push('  The server regenerates stale generated files on the merged tree itself (every ~5 min, up to 3 tries),');
+    lines.push('  so this usually clears without you; if it stays red the server flags the task needs_rebase.');
+  } else {
+    lines.push(`  Heal it: \`git fetch origin && git merge origin/main\`, then re-run \`node scripts/gds/ship.js ${taskId}\` — the ship`);
+    lines.push('  regenerates every generated file on the merged tree before it pushes (`node scripts/gds/ship-check.js` shows which).');
+  }
+  lines.push('  A busy main can re-stale it while CI re-runs; a repeat is that race, not a new fault.');
+  return lines;
+}
+
+// redBlocksMerge — is this red the kind that stops the merge? A failing REQUIRED check
+// (`failing_check…`) does; a failing optional one does not (GitHub still merges an UNSTABLE
+// PR), so only the first may turn the closing banner red (task 1003764). Pure + exported.
+function redBlocksMerge(md) {
+  return /^failing_check/.test(String((md && md.reason) || ''));
+}
+
+// A check conclusion (CheckRun) or state (status context) that means FAILED. Pending and
+// expected are waiting, not red — reporting them as failures would be the mirror image of
+// the bug this names (a failure dressed as waiting).
+const RED_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
+
+// localMergeDriver — task 1003764. The laptop path watches its PR with the builder's own
+// gh, and read only state + mergeCommit, so a red required check was invisible for the
+// whole wait. This reads `gh pr view --json statusCheckRollup,mergeStateStatus,headRefOid`
+// through the server's parser and answers in publish-status's merge_driver shape, so both
+// poll paths hand redPrLines the same thing. `failingTestsFor(sha)` reads the unit-report
+// status (gh pr view omits a status's description) and is asked only once that status is
+// itself red, i.e. posted. Null when nothing is red. Pure + exported.
+function localMergeDriver(pr, failingTestsFor = () => null) {
+  if (!pr || pr.state !== 'OPEN' || !Array.isArray(pr.statusCheckRollup)) return null;
+  const { checks } = readCheckRollup({ contexts: { nodes: pr.statusCheckRollup } });
+  const red = checks.filter((c) => RED_CONCLUSIONS.has(String(c.conclusion || '').toUpperCase()));
+  if (!red.length) return null;
+  const kind = pr.mergeStateStatus === 'UNSTABLE' ? 'non_required_check_failing' : 'failing_check';
+  const reported = red.some((c) => c.name === UNIT_REPORT_CONTEXT);
+  return { reason: `${kind}:${red[0].name}`, failing_tests: (reported && failingTestsFor(pr.headRefOid)) || null };
+}
+
+// unitReportFor — the failing-test line the `unit` workflow posted on `sha`, read with this
+// machine's gh through the same parser the server uses. Null when unreadable; the red line
+// then names the check instead, as it did before the report existed. `gh` is injectable.
+function unitReportFor(sha, gh = ghJson) {
+  if (!/^[0-9a-f]{7,64}$/i.test(String(sha || ''))) return null;
+  const combined = gh(['api', `repos/{owner}/{repo}/commits/${sha}/status`]);
+  const nodes = ((combined && combined.statuses) || []).map((s) => ({ ...s, __typename: 'StatusContext' }));
+  return readCheckRollup({ contexts: { nodes } }).failing_tests;
 }
 
 // task 1003499 — a CONFLICTING PR is a land that cannot happen, however green it is.
@@ -386,7 +491,7 @@ function conflictPrLines(taskId) {
 
 // noteConflict — one poll's worth of conflict tracking, shared by both loops. Prints
 // the lines above when the PR BECOMES conflicting (not on every 10s poll, and once
-// more if main moves on and undoes a heal), and returns what the PR looks like now.
+// more if main moves on and undoes a heal), and returns whether it conflicts now.
 // A failed read keeps the last answer rather than inventing a new one.
 function noteConflict(taskId, pr, wasConflicting) {
   if (!pr) return wasConflicting;
@@ -434,14 +539,27 @@ async function pollServerPublish(taskId, branch, deps = {}) {
   let blockedReason = null;
   let redLine = null;
   let conflicting = false;
+  let stuckRed = false; // task 1003764: a failing required check on the LAST read turns the closing banner red
+  let readFailure = null;
   for (let i = 0; i < TRIES; i++) {
     const r = await readStatus({ id: taskId, query: { branch } });
+    if (!r.ok) {
+      // task 1003764: a failed status read used to be skipped in silence, so a broken
+      // diagnostic looked exactly like slow CI. Say so once per distinct failure.
+      const { code } = normalizeApiError(r.data);
+      const why = `HTTP ${r.status}${code ? ` ${code}` : ''}`;
+      if (why !== readFailure) {
+        readFailure = why;
+        console.log(`  ci-land: could not read the land status from the server (${why}) — still polling.`);
+      }
+    }
     if (r.ok && r.data) {
       const red = redPrLine(r.data.merge_driver);
       if (red && red !== redLine) {
         redLine = red;
-        for (const line of redPrLines(r.data.merge_driver)) console.log(line);
+        for (const line of redPrLines(r.data.merge_driver, { taskId, via: 'server' })) console.log(line);
       }
+      stuckRed = !!red && redBlocksMerge(r.data.merge_driver);
       conflicting = noteConflict(taskId, r.data.merge_driver, conflicting);
       const outcome = classifyLandOutcome(r.data);
       if (outcome === 'shipped') {
@@ -469,7 +587,7 @@ async function pollServerPublish(taskId, branch, deps = {}) {
     return landBailed(`the PR merged but the server could not prove the land is this task's: ${blockedReason}`, `node scripts/gds/ship.js ${taskId}`);
   }
   if (conflicting) return landConflicted(taskId);
-  printLandPending(taskId);
+  printLandPending(taskId, { red: stuckRed });
   return landPending();
 }
 
@@ -793,11 +911,22 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
   console.log('  ci-land: waiting for auto-merge (checks + branch protection)...');
   let mergeSha = null;
   let conflicting = false;
+  // task 1003764: say WHY it has not merged. This loop read only state + mergeCommit,
+  // so a red required check — the likeliest reason — went unnamed for the whole wait.
+  // The unit-report line (which failing tests) is fetched once per head sha.
+  let redLine = null;
+  let stuckRed = false;
+  let report = { sha: undefined, text: null };
+  const failingTestsFor = (sha) => {
+    if (sha !== report.sha) report = { sha, text: unitReportFor(sha, readJson) };
+    return report.text;
+  };
   for (let i = 0; i < MERGE_TRIES; i++) {
     // task 1003499: mergeable + mergeStateStatus ride the same read, so a conflict is
     // named on the poll it appears; the two-field read is the fallback for a gh that
     // predates those fields, which keeps this no worse than before on any machine.
-    const pr = readJson(['pr', 'view', branch, '--json', 'state,mergeCommit,mergeable,mergeStateStatus'])
+    // task 1003764: so do headRefOid + statusCheckRollup, so a red check is named too.
+    const pr = readJson(['pr', 'view', branch, '--json', 'state,mergeCommit,mergeable,mergeStateStatus,headRefOid,statusCheckRollup'])
       || readJson(['pr', 'view', branch, '--json', 'state,mergeCommit']);
     if (pr && pr.state === 'MERGED') {
       mergeSha = pr.mergeCommit && pr.mergeCommit.oid;
@@ -807,6 +936,15 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
       console.log(`  ci-land: PR was CLOSED without merging (a required check failed, or it was closed manually). Fix it and re-run \`node scripts/gds/ship.js ${taskId}\` to resume. Task stays at 'confirmed'.`);
       return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
     }
+    if (pr) {
+      const md = localMergeDriver(pr, failingTestsFor);
+      const red = redPrLine(md);
+      if (red && red !== redLine) {
+        redLine = red;
+        for (const line of redPrLines(md, { taskId, via: 'local' })) console.log(line);
+      }
+      stuckRed = !!red && redBlocksMerge(md);
+    }
     conflicting = noteConflict(taskId, pr, conflicting);
     pause();
   }
@@ -814,14 +952,15 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
     // task 1049: PR open + auto-merge armed but not merged in-window = the publish
     // SUCCEEDED and is still in CI — success-pending, not a failure. Unless it is
     // CONFLICTING (task 1003499): then nothing is still in CI, and it never merges.
+    // Or RED (task 1003764): then the banner says the land is stuck on that check.
     if (conflicting) return landConflicted(taskId);
-    printLandPending(taskId);
+    printLandPending(taskId, { red: stuckRed });
     return landPending();
   }
   console.log(`  ci-land: merged to main (${mergeSha.slice(0, 8)}). Waiting for the prod deploy...`);
 
   for (let i = 0; i < DEPLOY_TRIES; i++) {
-    const runs = ghJson([
+    const runs = readJson([
       'run', 'list', '--workflow', 'deploy-prod.yml', '--branch', 'main',
       '--json', 'headSha,status,conclusion', '--limit', '15',
     ]);
@@ -846,7 +985,7 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
       }
       return landed();
     }
-    shellOk(POLL_SLEEP_CMD);
+    pause();
   }
   // task 1049: merged but the deploy run hasn't confirmed in-window — still
   // success-pending (it deploys on its own), not a failure.
@@ -890,6 +1029,13 @@ module.exports = {
   landConflicted,
   pollCiDeploy,
   pollServerPublish,
+  // task 1003764: name WHY a published PR has not merged when a check is red.
+  FRESHNESS_TESTS,
+  failingTestNames,
+  mergeTrapLines,
+  redBlocksMerge,
+  localMergeDriver,
+  unitReportFor,
   reconciledCardStatus,
   strandCommand,
   strandNextStep,

package/scripts/gds/ship-merge.js

@@ -32,6 +32,7 @@ const { gateMergeResult } = require('./ship-merge-gate.js');
 const { dbOnlyIgnoredNotice } = require('./ship-honesty.js');
 const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateCopyInventory, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
 const { REPO_ROOT } = require('./ship-state.js');
+const { envPrefix } = require('../../src/instance-config');
 
 // zeroCommitVerdict — dbOnly is deliberately consulted ONLY at zero commits
 // ahead: a branch carrying real commits must be merged, whatever flag was typed.
@@ -287,7 +288,7 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
     console.log('  pushing merged main to origin...');
     // SEC #863: route through push-main.js, which carries the
-    // OTB_ALLOW_MAIN_PUSH override so the pre-push permission gate lets THIS
+    // <PREFIX>_ALLOW_MAIN_PUSH override so the pre-push permission gate lets THIS
     // graded+confirmed pipeline push through while still blocking ad-hoc
     // `git push origin main`. process.execPath (quoted) for the same
     // cross-platform reason as the other node spawns here (#660).
@@ -298,7 +299,7 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
       // the ci PR path before this point; reaching this with protection on
       // means an env-forced 'laptop' or a failed protection probe.
       if (mainIsProtected() === true) {
-        return landBailed('main is branch-protected — the direct push can never land; unset OTB_DEPLOY_MODE (the ci PR path lands it)', `node scripts/gds/ship.js ${taskId}`);
+        return landBailed(`main is branch-protected — the direct push can never land; unset the DEPLOY_MODE env override (${envPrefix()}_DEPLOY_MODE, or the legacy OTB_DEPLOY_MODE) — the ci PR path lands it`, `node scripts/gds/ship.js ${taskId}`);
       }
       return landBailed('could not push the merged main to origin', '/merge-mode');
     }