@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/ship-land.js

@@ -0,0 +1,1130 @@
+// scripts/bongos/ship-land.js — the land outcome type and the ci-land paths (local, server-mediated) + their polling.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 990-1468 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { cliClient } = require('./cli-lib');
+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, RED_CONCLUSIONS } = require('../../modules/lifecycle/check-rollup.js');
+const { prMergeSentence } = require('../../modules/lifecycle/page-tweak-hold.js');
+
+// ---------- the land outcome (task 1002541, part 1) ----------
+//
+// The land chain used to answer with a bare boolean. Every bail site already
+// computes a precise reason and logs it, but `false` threw that reason away — so
+// the completion card had only the task's STATUS to go on ('confirmed') and
+// printed "Deploy  landing automatically" even when nothing was landing and the
+// builder was, under ADR 0120, unpaid. The failure announced itself as success.
+//
+// "Not shipped" is not one thing, so this is a three-way, not a boolean:
+//   landed()         — merged + deployed; the task flips to shipped.
+//   landPending()    — published and auto-merge armed: it DOES land on its own
+//                      (CI / the server reconciler), so "landing automatically"
+//                      is honest here. A poll timeout is this, not a failure
+//                      (task 1049) — keep it out of the loud path.
+//   landBailed(r, n) — nothing is landing. `r` is the reason already logged,
+//                      `n` the command that recovers it.
+// Only landBailed makes the card say NOT landed. Purely additive: no bail site
+// changes what it DOES, only what it now reports back.
+// ADR 0184: an EMPTY ship has no commit to prove, so it must DECLARE itself.
+// task 1002572 (PART 2): a bail also carries an optional `bailId` — the stable
+// name of WHICH refusal fired, so a caller can route the recoverable ones to the
+// push+PR path instead of stranding. `null` for every un-tagged bail, which keeps
+// them terminal (fail-safe: an untagged bail never gains a silent fallback).
+function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
+function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
+function landBailed(reason, nextStep = null, bailId = null) { return { ok: false, pending: false, reason, nextStep, bailId }; }
+// task 1004322 (ADR 0341 D7): the FOURTH outcome, and only a page tweak reaches it.
+// Its grade passed and its branch and PR are published, but nothing is landing and
+// nothing should: the artist approves the applied page first. Not a bail (nothing
+// failed, and the card must not say "Land it") and not pending (no auto-merge is
+// armed, so it does not land on its own).
+function landHeld({ prUrl = null } = {}) { return { ok: false, pending: false, held: true, reason: null, nextStep: null, prUrl }; }
+
+// ---------- which bails a PR can still land (task 1002572, part 2) ----------
+//
+// A builder in a SINGLE main checkout can never complete a local merge: the tree
+// that would RECEIVE the merge is the very tree holding the feature branch. That
+// is a property of the machine, not of the work — the branch itself is perfectly
+// landable, just not from here. So that one bail must fall back to the push+PR
+// path (ciLand) rather than parking the task at 'confirmed' unpaid (ADR 0120).
+//
+// Everything else stays LOUD. A merge conflict, a red post-merge smoke, a failed
+// push, an unreachable origin: those are real failures, and a PR would carry the
+// same breakage to main. Membership is opt-in by id for exactly that reason —
+// blanket-converting bails into PRs is the way this fix goes wrong.
+const LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH = 'main-checkout-on-branch';
+const LAND_BAIL_NO_TASK_BRANCH = 'no-task-branch';
+const PR_RECOVERABLE_BAILS = new Set([LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH]);
+
+// landBailRecoverableByPr — PURE. Can this bail still be landed by opening a PR?
+// `no-task-branch` is deliberately NOT in the set: standing on main there is no
+// head branch to open a PR FROM, so the PR path has nothing to offer it (its cure
+// is to go back to the task branch and re-ship, which now works).
+function landBailRecoverableByPr(bailId) {
+  return PR_RECOVERABLE_BAILS.has(bailId);
+}
+
+// The short COMMAND form of strandNextStep (which is prose, sized for the log).
+// The card has room for one command, not a sentence.
+function strandCommand(taskId, via) {
+  return via === 'server' ? `node scripts/bongos/ship.js ${taskId}` : '/merge-mode';
+}
+
+// ciLand — dispatch the 'ci' confirmed->shipped land to the local or the
+// server-mediated path. Async because the server path awaits GDS API calls.
+// opts.hold (task 1004322): PUBLISH ONLY — push the branch and open the PR, never
+// arm auto-merge and never poll for a land. A page tweak held for its artist takes
+// it; every other caller passes nothing and gets the unchanged path.
+async function ciLand(taskId, branch, valueSummary, opts = {}) {
+  console.log(opts.hold
+    ? '  held for the artist — publishing the branch and its PR only (no auto-merge, no land)'
+    : '  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
+  if (pushVia() === 'server') {
+    return ciLandServer(taskId, branch, valueSummary, opts);
+  }
+  return await ciLandLocal(taskId, branch, valueSummary, opts);
+}
+
+// task 1001916: render a FAILED POST /tasks/:id/publish-branch for the builder.
+// The server has carried { step, reason } — which git step failed + the
+// credential-scrubbed stderr — since task 1547, but the bail site printed only
+// `data.message || data.error`: "[object Object]" on the ADR 0116 envelope, a
+// bare `publish_failed` on the legacy flat shape. That hid a non-fast-forward
+// rejection (the server had already freshened the branch itself) across several
+// blind retry laps, so that case also gets its specific remedy. Pure + exported
+// for tests/ship_publish_error.mjs (no git, no network).
+const NON_FAST_FORWARD_RE = /fetch first|non-fast-forward/i;
+
+// localHistoryRewritten — the discriminator formatPublishFailure needs (task 1003221).
+// Is the remote-tracking tip an ancestor of HEAD? Yes = we only added commits, so a
+// non-fast-forward means the SERVER moved. No = our history diverged, which is what a
+// rebase or amend does. null = no ref to compare against, and null keeps the original
+// wording so an unknown never invents a diagnosis.
+function localHistoryRewritten(branch) {
+  const remoteRef = `origin/${branch}`;
+  if (!gitArgvOk(['rev-parse', '--verify', '--quiet', remoteRef], { stdio: 'ignore' })) return null;
+  // `merge-base --is-ancestor A B` exits 0 when A is an ancestor of B.
+  return !gitArgvOk(['merge-base', '--is-ancestor', remoteRef, 'HEAD'], { stdio: 'ignore' });
+}
+
+// task 1003221 — a non-fast-forward has TWO causes needing OPPOSITE recoveries. This
+// gave one diagnosis ("the server already moved <branch>") and prescribed `reset`,
+// which is right when the server is ahead and DESTRUCTIVE when the builder rebased or
+// amended an already-published branch — it discards the commits they just made (the
+// real 2026-08-21 case, 163 minutes). Server-mediated publish is APPEND-ONLY, as the
+// learning claim.js prints says. opts.localHistoryRewritten discriminates; null means
+// git could not tell and keeps the original wording rather than guessing.
+function formatPublishFailure(data, status, branch, opts = {}) {
+  const { code, message } = normalizeApiError(data);
+  const envelopeDetails = (data && data.error && typeof data.error === 'object' && data.error.details) || null;
+  const details = envelopeDetails || data || {};
+  const label = message || code || (data && data.message) || `HTTP ${status}`;
+  // Flattened ONLY for the matchers below and the one-line summary. The readable
+  // copy is printed verbatim underneath (task 1003222): the server no longer clips
+  // stderr, and git's useful line is the LAST one, so collapsing a 20-line push
+  // failure into a single run-on sentence hides the very thing that was un-hidden.
+  const reason = details.reason ? String(details.reason).replace(/\s+/g, ' ').trim() : '';
+  const parts = [];
+  if (details.step) parts.push(`step: ${details.step}`);
+  if (details.git_exit_code != null) parts.push(`git exit ${details.git_exit_code}`);
+  if (details.github_status != null) parts.push(`GitHub HTTP ${details.github_status}`);
+  if (details.timed_out) parts.push('TIMED OUT');
+  // The one-line summary stays short and scannable; the full text follows it.
+  if (reason) parts.push(`reason: ${reason.length > 200 ? `${reason.slice(0, 200)}…` : reason}`);
+  let out = parts.length ? `${label} (${parts.join('; ')})` : label;
+
+  // ORDER MATTERS: summary, then the REMEDY, then the verbatim block last. The
+  // remedy is the actionable sentence and must not end up stranded below twenty
+  // lines of git chatter where it reads as a footnote to the quote.
+  if (NON_FAST_FORWARD_RE.test(reason)) {
+    out += opts.localHistoryRewritten === true
+      ? ` — your LOCAL history was rewritten (a rebase or amend), so ${branch} is no longer a `
+        + `descendant of what the server already holds. Server-mediated publish is APPEND-ONLY: run `
+        + `\`git fetch origin && git merge origin/${branch}\`, re-run the generators, commit the merge, `
+        + 'and re-ship. Do NOT reset or re-rebase — that discards the commits you just made.'
+      : ` — the server already moved ${branch}: fetch origin, reset onto origin/${branch}, `
+        + 're-run the generators, and re-ship so the push fast-forwards.';
+  }
+
+  // The untruncated remote message, verbatim and indented so it reads as a quotation
+  // rather than as more ship output. Only when it is multi-line — a single-line
+  // stderr is already fully present in the summary above, and repeating it is noise.
+  const full = details.reason ? String(details.reason).trimEnd() : '';
+  if (full && /\n/.test(full)) {
+    out += `\n\n  --- what the remote actually said ---\n${full.split('\n').map((l) => `  ${l}`).join('\n')}\n  --- end ---`;
+    if (details.reason_bytes != null && details.reason_bytes > full.length) {
+      out += `\n  (${details.reason_bytes} bytes at the server; the middle was omitted here)`;
+    }
+  }
+  return out;
+}
+
+// ciLandServer — the server-mediated path: no GitHub push credential on this
+// machine, so hand the branch to the GDS, which pushes it + opens the PR +
+// auto-merges with the server-side credential. Needs an ordinary cli session.
+async function ciLandServer(taskId, branch, valueSummary, { hold = false } = {}) {
+  console.log('  ci-land: server-mediated publish (this machine has no GitHub push credential)');
+  const headSha = gitOk('git rev-parse HEAD');
+  // Make sure origin/main is current so the THIN bundle's `origin/main..HEAD`
+  // base is resolvable (a read-only fetch — works on a credential-less origin).
+  gitArgvOk(['fetch', 'origin', 'main'], { stdio: 'ignore' });
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-bundle-'));
+  const bundlePath = path.join(tmpDir, 'branch.bundle');
+  try {
+    if (!gitArgvOk(['bundle', 'create', bundlePath, `origin/main..${branch}`], { stdio: 'ignore' })) {
+      console.log(`  ci-land: could not build the branch bundle (nothing new to push, or a git error); task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
+      return landBailed('could not build the branch bundle', strandCommand(taskId, 'server'));
+    }
+    const bundleB64 = fs.readFileSync(bundlePath).toString('base64');
+    const r = await (await cliClient()).tasks.postTasksIdPublishBranch({
+      id: taskId,
+      body: { branch, head_sha: headSha, value_summary: valueSummary, bundle_b64: bundleB64 },
+    });
+    if (r.status === 503) {
+      console.log('  ci-land: server-mediated push is not configured on the server yet (no GitHub App nor GITHUB_PUSH_TOKEN — operator action, ADR 0055). Task stays at confirmed.');
+      return landBailed('server-mediated push is not configured (operator action)', strandCommand(taskId, 'server'));
+    }
+    if (!r.ok) {
+      const e = formatPublishFailure(r.data, r.status, branch, {
+        localHistoryRewritten: localHistoryRewritten(branch),
+      });
+      console.log(`  ci-land: server publish failed — ${e}. Task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
+      return landBailed(`server publish failed — ${e}`, strandCommand(taskId, 'server'));
+    }
+    // task 1004322: the server does not arm a held page tweak (it reads the hold
+    // itself), so do not tell the builder to merge it on GitHub.
+    console.log(hold
+      ? `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge NOT armed: waiting for the artist).`
+      : `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
+    const assigneeLine = prAssigneeLine(r.data.pr_assignee);
+    if (assigneeLine) console.log(assigneeLine);
+    if (hold) return landHeld({ prUrl: r.data.pr_url || null });
+    return pollServerPublish(taskId, branch);
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+  }
+}
+
+// task 1049 (B — async land semantics): classify a CI-land poll outcome so a
+// SUCCESSFUL-but-still-running publish reads as success, not failure. The #1027
+// retrospective: the ship's poll window is shorter than real CI, so a PR that was
+// opened + auto-merge-armed (a SUCCESS) printed "did not merge — task stays at
+// confirmed" and looked like a failure. Outcomes:
+//   'shipped' — merged AND deploy-prod succeeded → flip the task to shipped
+//   'failed'  — PR closed without merging (a check failed / closed manually)
+//   'pending' — PR still open with auto-merge armed (or merged, deploy not yet):
+//               NOT a failure — it lands on its own (the server reconciles the
+//               task to shipped, and a re-run resumes — task 941).
+// Pure + exported for unit tests (no git/network). Accepts the publish-status
+// response shape verbatim — getPublishStatus returns snake_case (pr_state,
+// deploy_status); camelCase aliases are tolerated for test convenience.
+// task 1002472: 'unconfigured' means the repo has no deploy-prod.yml to wait for
+// (ADR 0108 pin-bump publishing), so the merge IS the land. Mirrors
+// github-push.landConfirmed — kept in step by tests/ship_ci_deploy.mjs, since this
+// CLI cannot import the server module.
+function classifyLandOutcome(s) {
+  const merged = !!(s && s.merged);
+  const deployStatus = s && (s.deploy_status ?? s.deployStatus);
+  const prState = s && (s.pr_state ?? s.prState);
+  if (merged && (deployStatus === 'success' || deployStatus === 'unconfigured')) return 'shipped';
+  if (prState === 'closed' && !merged) return 'failed';
+  return 'pending';
+}
+
+// task 1718: PURE — after ciLandLocal tries to arm GitHub auto-merge, decide which
+// poll path lands + watches the PR. Arming auto-merge commonly FAILS when shipping
+// from a worktree (`gh pr merge --auto` runs a git op that trips on `'main' is
+// already used by worktree`) or with branch protection off — but the PR is open and
+// this is NOT a dead-end: the server's merge driver + reconciler still land green
+// PRs. So an enable-failure must NOT strand the builder at 'confirmed' (they'd never
+// see the SHIPPED banner in-session, and the machine-global land-watch breadcrumb
+// would surface it in some OTHER session). Instead:
+//   'ci'     → auto-merge armed: watch GitHub directly (pollCiDeploy).
+//   'server' → auto-merge NOT armed: drive + watch the server land via publish-status
+//              (pollServerPublish) — reading it is reconcile-on-read, so it DRIVES the
+//              merge and observes the flip to 'shipped'.
+// Both paths end at 'shipped' on a real land, so the banner renders in the shipping
+// session and no 'confirmed' breadcrumb is written. Exported for unit tests.
+function landPollAfterAutoMerge(autoMergeArmed) {
+  return autoMergeArmed ? 'ci' : 'server';
+}
+
+// task 1719: PURE — after mergeAndDeploy runs, the completion card + the pending-land
+// breadcrumb must reflect the AUTHORITATIVE post-land status, not the pre-merge one
+// finishShip was handed. If the task actually reached 'shipped' in-session (a laptop
+// sync land, the enable-success poll, or the task-1718 enable-failure server poll),
+// the card renders the SHIPPED banner and printCompletionCard writes NO breadcrumb;
+// otherwise keep the pre-merge status (the async land is still pending → 'confirmed' →
+// the next-turn land-watch breadcrumb is the intended fallback). Exported for tests.
+function reconciledCardStatus(liveStatus, preMergeStatus) {
+  return liveStatus === 'shipped' ? 'shipped' : preMergeStatus;
+}
+
+// task 1052 (E): the machine-appropriate next step when a ship lands the task at
+// 'confirmed' without finishing. A machine with no push credential (pushVia 'server' —
+// no authed gh) CANNOT run /merge-mode (it needs gh + a main checkout), so the old
+// "for /merge-mode" advice was a dead end there (the #1027 retrospective: the agent
+// had to reverse-engineer recovery from source). Point such a machine at the resume
+// instead (task 941); a laptop keeps /merge-mode (with resume as the alternative).
+// Pure + exported for unit tests.
+function strandNextStep(taskId, via) {
+  if (via === 'server') {
+    return `Re-run \`node scripts/bongos/ship.js ${taskId}\` to resume — it picks up exactly where it stopped (task 941). ` +
+      `(/merge-mode is NOT available here — it needs gh + a main checkout this machine doesn't have.)`;
+  }
+  return `Run /merge-mode to land it — or re-run \`node scripts/bongos/ship.js ${taskId}\`, which resumes from here (task 941).`;
+}
+
+// The standard "published — it'll land on its own" success-pending banner
+// (task 1049). Shared by both poll paths so the message is identical and never
+// reads as a failure. The task legitimately stays at 'confirmed' until CI lands
+// it; the server reconciles it to 'shipped' (publish-status reconcile-on-read)
+// and a re-run resumes (task 941).
+//
+// task 1002606 (finding P-3): the banner used to end at "NOT a failure", so when
+// a land DID fail (hand-written conflict, PR closed unmerged, persistent red
+// check) the builder's last signal said everything was fine and the strand sat
+// invisible until they happened to look. The banner now tells the failure story
+// 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.
+//
+// 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, notStarted } = {}) {
+  // task 1004289: CI never RAN (the account cannot run Actions). Not a failure of the
+  // work, and not something waiting fixes either: the checks have to be started again.
+  if (notStarted) {
+    return [
+      '  ci-land: Published, but CI never started on the PR (GitHub ran none of its checks), so it has NOT merged',
+      '  and cannot until they run. The task stays at \'confirmed\'. Nothing in the work needs to change: once the',
+      `  owner restores GitHub Actions, re-run the failed jobs (lines above), then re-run \`node scripts/bongos/ship.js ${taskId}\``,
+      '  to watch the land — it resumes from here (task 941).',
+    ];
+  }
+  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/bongos/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,`,
+    `  and the task flips to 'shipped' on its own. Re-run \`node scripts/bongos/ship.js ${taskId}\` anytime to confirm`,
+    `  it landed — it resumes from here (task 941). The task is at 'confirmed' until the deploy completes.`,
+    `  If it CANNOT land on its own (a hand-written merge conflict, the PR closed without merging, a check`,
+    `  that keeps failing), the server flags the task needs_rebase — /builder-start will warn you and new`,
+    `  claims are gated until you fix + re-land it (re-run the ship after fixing), or release it.`,
+  ];
+}
+function printLandPending(taskId, opts = {}) {
+  console.log('');
+  for (const line of landPendingLines(taskId, opts)) 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), or the
+  // ci_not_started one (task 1004289).
+  if (!opts.red && !opts.notStarted) 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
+// confirmed→shipped flip (reconcile_blocked: the task-1547 land proof missed — a
+// wrong/missing published tip, or the matched PR doesn't reference this task). The
+// optimistic "NOT a failure" banner was a lie here: without proof the auto-land can
+// NEVER finish, and the wave-5 ships sat at 'confirmed' with their last signal
+// saying everything was fine. Name the refusal and the remedy instead. Pure +
+// exported so the wording is pinned by tests/ship_ci_deploy.mjs.
+function reconcileBlockedLines(taskId, reason) {
+  return [
+    `  ci-land: the PR MERGED, but the task did NOT flip to 'shipped' — the server could not prove the land is`,
+    `  THIS task's: ${reason}.`,
+    `  The server reconciler retries the proof every ~5 min, so a late-recorded tip or PR reference still lands`,
+    `  on its own. Re-run \`node scripts/bongos/ship.js ${taskId}\` to re-drive it; if it stays blocked the server`,
+    `  flags the task needs_rebase and /builder-start will show the remedy.`,
+  ];
+}
+
+// task 1003991 — the server opens the PR with ITS credential, so "created by me" on
+// GitHub is empty for the builder; it assigns the PR to them instead, and this says
+// where that makes it findable. Null when the server assigned nobody. Pure + exported.
+function prAssigneeLine(login) {
+  return /^[A-Za-z\d_-]{1,39}$/.test(String(login || ''))
+    ? `  ci-land: the PR is assigned to @${login} — on GitHub it is under Pull requests → Assigned to you (the server opened it, so "Created by you" stays empty).`
+    : null;
+}
+
+// task 1003988 — what to tell a builder while their PR sits RED. The poll used to
+// wait out its nine minutes in silence, so a credential-less checkout learned only that
+// the land was "pending" and pushed the same commit again (PR 922: nine red runs).
+// `md` is publish-status's merge_driver; null means nothing red to report. Pure +
+// exported so the wording is pinned by tests/unit_report_status.mjs.
+function redPrLine(md) {
+  const reason = (md && md.reason) || '';
+  if (md && md.not_started) {
+    const job = (/^ci_not_started:(.+)$/.exec(reason) || [])[1];
+    return `  ci-land: CI NEVER RAN on this PR — GitHub did not start ${job ? `the \`${job}\` job` : 'its checks'} ("The job was not started because …", `
+      + 'an Actions budget or billing stop on the account). Nothing in the work was tested, so there is nothing in it to fix.';
+  }
+  const fix = 'fix it, commit, and re-run the ship — re-pushing unchanged work cannot turn it green.';
+  if (md && md.failing_tests) {
+    return `  ci-land: the PR is RED — ${md.failing_tests}. Reproduce with \`node tests/<name>.mjs\`, ${fix}`;
+  }
+  if (reason === 'failing_check_unreadable') {
+    return '  ci-land: the PR is RED, and this instance cannot see which check failed (the GitHub App lacks '
+      + `\`Checks: read\` — an owner grant, not a fault in your work). Run \`npm test\` locally to find it, ${fix}`;
+  }
+  const named = /^(?:non_required_check_failing|failing_check):(.+)$/.exec(reason);
+  return named ? `  ci-land: the PR is RED — the \`${named[1]}\` check failed; ${fix}` : null;
+}
+
+// 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.
+// task 1003764: the merge trap sits between them. `opts` = { taskId, via } for its wording.
+function redPrLines(md, opts = {}) {
+  const red = redPrLine(md);
+  if (red && md.not_started) return [red, ...notStartedLines(md), ...plainCardLines('ci_not_started')];
+  return red ? [red, ...mergeTrapLines(md, opts), ...plainCardLines((md && md.reason) || 'failing_check')] : [];
+}
+
+// notStartedLines — task 1004289. What to do when CI never ran, instead of the merge trap
+// (there is no failure to reproduce). Re-running is the remedy, not re-pushing: the same
+// commit is fine, it simply was never tested. Pure + exported.
+function notStartedLines(md) {
+  const rerun = md && /^\d+$/.test(String(md.run_id || '')) ? `\`gh run rerun ${md.run_id} --failed\`` : '"Re-run failed jobs" on the PR';
+  return [
+    '  ci-land: this is the repo OWNER\'s to fix, on GitHub: the account\'s Actions budget / spending limit or payment method.',
+    `  ci-land: once Actions can run again, ${rerun} starts the checks on the SAME commit — do not re-push or edit the work.`,
+  ];
+}
+
+// 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/bongos/ship.js ${taskId}\` — the ship`);
+    lines.push('  regenerates every generated file on the merged tree before it pushes (`node scripts/bongos/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).
+// The set itself lives in check-rollup.js, shared with the server's mergeBlockReason (task 1004666).
+
+// 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.
+// task 1004289 — `neverStarted(rawCheck)` answers "did this red job never run at all?"
+// (jobNeverStarted below). When EVERY red check is one, nothing was tested, and the
+// answer is { reason: 'ci_not_started:<name>', not_started: true, run_id } rather than
+// a failing check the builder is told to fix.
+function localMergeDriver(pr, failingTestsFor = () => null, neverStarted = () => false) {
+  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 redRaw = pr.statusCheckRollup.filter((c) => c && RED_CONCLUSIONS.has(String(c.conclusion || c.state || '').toUpperCase()));
+  if (redRaw.length && redRaw.every((c) => neverStarted(c))) {
+    const run = /\/runs\/(\d+)\//.exec(String(redRaw[0].detailsUrl || ''));
+    return { reason: `ci_not_started:${red[0].name}`, not_started: true, failing_tests: null, run_id: run ? run[1] : 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 };
+}
+
+// jobNeverStarted — task 1004289. When the account cannot run Actions (its budget is
+// spent, or a payment failed), GitHub still marks every job FAILED seconds after it was
+// queued, with no steps and no runner, and one annotation saying why: "The job was not
+// started because an Actions budget is preventing further use." (PR 1211, 2026-09-25).
+// Read as an ordinary red check, that told the builder to fix their code — advice that
+// cannot help, where each retry is another failed run. An Actions job's id (the tail of
+// its detailsUrl) is its check-run id, so its annotations are one read away. FAIL-OPEN:
+// anything unreadable is "no", which keeps the ordinary red wording. `gh` is injectable.
+const NOT_STARTED_RE = /^\s*The job was not started because\b/i;
+function jobNeverStarted(check, gh = ghJson) {
+  if (!check || (check.__typename && check.__typename !== 'CheckRun')) return false;
+  const m = /\/job\/(\d+)(?:[/?#]|$)/.exec(String(check.detailsUrl || ''));
+  if (!m) return false;
+  const notes = gh(['api', `repos/{owner}/{repo}/check-runs/${m[1]}/annotations`]);
+  return Array.isArray(notes) && notes.some((a) => a && NOT_STARTED_RE.test(String(a.message || '')));
+}
+
+// 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.
+// GitHub's auto-merge waits for a clean merge as well as for green checks, so a PR
+// whose branch conflicts with main sits open under a fully green rollup and never
+// merges. PR #497 sat like that for ~25 minutes while both polls below said nothing
+// and then printed "auto-merge is armed ... NOT a failure", the banner a land that IS
+// on its way gets. The server already knew (mergeBlockReason -> 'merge_conflict'); the
+// ship never asked. Pure + exported. Takes both shapes it is handed: `gh pr view`'s
+// camelCase (mergeable, mergeStateStatus) and publish-status's snake_case merge_driver
+// (mergeable, merge_state, reason). A read that failed (null) is not a conflict.
+function prConflicting(pr) {
+  if (!pr) return false;
+  const state = pr.mergeStateStatus ?? pr.merge_state;
+  return pr.mergeable === 'CONFLICTING' || state === 'DIRTY' || pr.reason === 'merge_conflict';
+}
+
+// What the poll says the moment it sees the conflict. Pure + exported so the wording
+// is pinned by tests/ship_land_conflict.mjs. The poll keeps waiting afterwards on
+// purpose: a conflict only in generated files is healed by the server's own resolver
+// on its next sweep (ADR 0082), and the PR then merges inside this same window.
+function conflictPrLines(taskId) {
+  return [
+    '  ci-land: the PR CONFLICTS with main, so auto-merge cannot fire until that is resolved, however green its checks are.',
+    '  ci-land: a conflict only in generated files is healed by the server on its next sweep (~5 min), so this keeps waiting.',
+    '  ci-land: anything hand-written waits for you. From this worktree:',
+    '    git fetch -q origin && git merge origin/main   # resolve the conflicts, commit',
+    `    node scripts/bongos/ship.js ${taskId}               # resumes the land; it does not re-grade`,
+    ...plainCardLines('merge_conflict'),
+  ];
+}
+
+// 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 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;
+  const now = prConflicting(pr);
+  if (now && !wasConflicting) for (const line of conflictPrLines(taskId)) console.log(line);
+  return now;
+}
+
+// landConflicted — the verdict when the wait ends with the PR STILL conflicting. It is
+// not landing on its own, so it must not print the "landing automatically" banner or
+// the land_pending card ("Nothing to do. This is normal, not a failure."): task
+// 1002541's rule that a land which is not happening must not announce itself as
+// success. No bailId, so ship-merge never reroutes it: the PR already exists and is
+// the problem. /strand-fix walks the cure (its case C: merge main in, resolve, re-ship).
+function landConflicted(taskId) {
+  console.log('');
+  console.log(`  ci-land: still CONFLICTING when the wait ended, so this will NOT land on its own. The task stays at 'confirmed' until the conflict is resolved (/strand-fix ${taskId} walks it).`);
+  return landBailed('the PR conflicts with main, so it cannot merge until the conflict is resolved', `/strand-fix ${taskId}`);
+}
+
+// One module-scope sleep command shared by both poll loops (task 1093 / C9). A
+// child `node -e setTimeout` is used (not `await new Promise`) so it blocks
+// identically in the SYNCHRONOUS pollCiDeploy and the async pollServerPublish —
+// the loops keep their own structure (sync vs async, 1-stage vs 2-stage); only
+// the ~10s cadence is shared.
+const POLL_SLEEP_CMD = 'node -e "setTimeout(()=>{}, 10000)"';
+
+// pollServerPublish — the server-mediated analogue of pollCiDeploy. Polls the
+// GDS publish-status endpoint (which the server answers from GitHub, and which
+// reconciles the task to shipped when it observes merge+deploy — task 1049) until
+// the PR merges + deploy-prod succeeds. Returns true when prod is confirmed live;
+// a timeout with an armed PR is success-PENDING (the publish worked), not failure.
+// A timeout with a CONFLICTING PR is not (task 1003499): see landConflicted.
+// `deps` exists for tests/ship_land_conflict.mjs; a real ship passes none.
+async function pollServerPublish(taskId, branch, deps = {}) {
+  const TRIES = 54; // ~9 min at 10s — checks + auto-merge + Actions deploy
+  const readStatus = deps.readStatus || (async (q) => (await cliClient()).tasks.getTasksIdPublishStatus(q));
+  const pause = deps.pause || (() => shellOk(POLL_SLEEP_CMD));
+  console.log('  ci-land: waiting for auto-merge + prod deploy (polling the server)...');
+  // task 1002645: GitHub can report merged+deployed while the SERVER refused the
+  // confirmed→shipped flip (reconcile_blocked — the task-1547 land proof missed).
+  // "Prod is live" + exit here was a lie that left the task stranded with no
+  // signal. Say the real reason and keep polling — attest-gate now records the
+  // pushed tip, so the proof usually heals within the window.
+  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, { 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') {
+        if (r.data.reconcile_blocked) {
+          if (r.data.reconcile_blocked !== blockedReason) {
+            blockedReason = r.data.reconcile_blocked;
+            console.log(`  ci-land: merged, but the server did NOT flip the task to shipped: ${blockedReason}. Still polling (the reconciler retries every sweep)...`);
+          }
+        } else {
+          console.log(`  ci-land: merged (${String(r.data.merge_sha || '').slice(0, 8)}) + deploy-prod succeeded. Prod is live.`);
+          return landed();
+        }
+      }
+      if (outcome === 'failed') {
+        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/bongos/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/bongos/ship.js ${taskId}`);
+      }
+    }
+    pause();
+  }
+  if (blockedReason) {
+    console.log('');
+    for (const line of reconcileBlockedLines(taskId, blockedReason)) console.log(line);
+    for (const line of plainCardLines('reconcile_blocked')) console.log(line);
+    return landBailed(`the PR merged but the server could not prove the land is this task's: ${blockedReason}`, `node scripts/bongos/ship.js ${taskId}`);
+  }
+  if (conflicting) return landConflicted(taskId);
+  printLandPending(taskId, { red: stuckRed });
+  return landPending();
+}
+
+// attestGateTrust — task 1169 (ADR 0058). Ask the SERVER to post the trustless
+// gate-author-trust commit status for THIS builder's server-resolved rank on the
+// pushed head SHA. ship.js's local path pushes + opens the PR with the laptop's
+// OWN gh credential, but only the server can forge the rank attestation the
+// ENFORCING gate-review check reads — without it a Metic+ author's gate-surface PR
+// from a laptop is BLOCKED and they can't self-approve it (task 1162 / PR #131).
+// Best-effort + never throws: a non-Metic author, an unconfigured server, or a
+// transient failure just leaves the PR un-attested → it escalates (the safe
+// direction). A non-gate PR is unaffected by the attestation either way.
+//
+// task 1004055 — the endpoint does TWO things, and only one of them was ever
+// reported. Besides the attestation (best-effort, and declining is a legitimate
+// answer) it records claims.published_head_sha, the tip that makes the ship
+// PROVABLE — and that half is load-bearing, not best-effort: without it POST /ship
+// refuses the confirmed→shipped flip. So this returns { recorded, attested, reason }
+// rather than undefined, and callers act on `recorded`. It still never throws.
+async function attestGateTrust(taskId, headSha) {
+  if (!headSha) return { recorded: false, attested: false, reason: 'no head SHA to attest' };
+  let r;
+  try {
+    r = await (await cliClient()).tasks.postTasksIdAttestGate({ id: taskId, body: { head_sha: headSha } });
+  } catch (e) {
+    // task 1004055: a bare `catch (_) {}` here meant a thrown request error left NO
+    // trace at all — the quietest of the failure shapes, and the one that reached
+    // the builder as an unexplained ship_land_not_proven.
+    console.log(`  ci-land: gate attestation request failed (${(e && e.message) || 'unknown error'}).`);
+    return { recorded: false, attested: false, reason: `request failed (${(e && e.message) || 'unknown error'})` };
+  }
+  const recorded = landProofRecorded(r);
+  if (r.ok && r.data) {
+    if (r.data.attested) {
+      console.log('  ci-land: gate-author-trust attested on the head SHA (Metic+) — a gate-surface PR auto-passes the ADR-0058 gatekeeper.');
+    } else {
+      console.log(`  ci-land: gate-author-trust NOT attested (${r.data.reason || 'rank below Metic'}) — a gate-surface PR will need owner approval; a non-gate PR is unaffected.`);
+    }
+    return { recorded, attested: !!r.data.attested, reason: r.data.reason || null };
+  }
+  if (r.status === 503) {
+    console.log('  ci-land: the server has no push credential to post the gate attestation (operator: GITHUB_APP_* / GITHUB_PUSH_TOKEN). A gate-surface PR will need owner approval.');
+    return { recorded, attested: false, reason: 'the server has no push credential' };
+  }
+  console.log(`  ci-land: gate attestation request failed (HTTP ${r.status}); a gate-surface PR may need a manual re-run / owner approval.`);
+  return { recorded, attested: false, reason: `HTTP ${r.status}` };
+}
+
+// landProofRecorded — PURE. Did an attest-gate response actually record
+// claims.published_head_sha (task 1004055)? That row is the durable per-task land
+// proof; without it POST /tasks/:id/ship refuses with ship_land_not_proven and the
+// task strands at 'confirmed' with its work already on main.
+//
+// The server SAYS so in `tip_recorded` — on the 200 body and in the 503's details,
+// because the write deliberately sits BEFORE the credential check. Prefer that.
+// A server that predates the field sends neither, which is the NORMAL state here:
+// an instance runs a PINNED core, so it lags main by however long the pin sits
+// still. For those, fall back to the route's contract — the write is above the
+// credential 503, so 200 and 503 both mean the tip landed and nothing else does.
+// Exported so the truth table is pinned with no server.
+function landProofRecorded(r) {
+  if (!r || typeof r.status !== 'number') return false;
+  const body = r.data || {};
+  const explicit = body.tip_recorded !== undefined
+    ? body.tip_recorded
+    : (body.error && body.error.details ? body.error.details.tip_recorded : undefined);
+  if (explicit !== undefined) return explicit === true;
+  return r.status === 200 || r.status === 503;
+}
+
+// landProofWarningLines — PURE. What to print when the proof did NOT get recorded
+// (task 1004055). Without it POST /ship refuses, the task parks at 'confirmed' —
+// which gates the builder's WHOLE queue — and the publish-reconciler eventually
+// writes strand:land_not_proven, after which nothing heals it. Say it HERE, while
+// the sha is still on screen, and hand over the calls that fix it, rather than
+// letting it surface as an opaque 409 later.
+//
+// `merged` is the tense, and it is the whole difference between the two callers:
+// the local-merge path has ALREADY put the work on main and needs the full
+// two-call recovery now; the PR path has only pushed, so the land may still be
+// minutes away and the same recovery would be premature. Exported so both
+// wordings are pinned.
+function landProofWarningLines(taskId, sha, reason, { merged = true } = {}) {
+  const head = sha || '<the merge commit on main>';
+  const why = `  WARNING: the land proof for task ${taskId} was NOT recorded (${reason || 'unknown'}).`;
+  const fix = `    node scripts/bongos/api.js POST /tasks/${taskId}/attest-gate --body '{"head_sha":"${head}"}'`;
+  if (!merged) {
+    return [
+      '',
+      why,
+      '  Nothing is lost yet — the branch is pushed and the PR still lands normally.',
+      '  But if the ship then refuses with ship_land_not_proven, re-record the tip',
+      '  against the merge commit and re-run the ship:',
+      `    node scripts/bongos/api.js POST /tasks/${taskId}/attest-gate --body '{"head_sha":"<the merge commit on main>"}'`,
+      `    node scripts/bongos/ship.js ${taskId}`,
+    ];
+  }
+  return [
+    '',
+    why,
+    '  The merge IS on main, but the server cannot prove the land is this task\'s, so',
+    '  the confirmed -> shipped flip will be refused (ship_land_not_proven) and the',
+    '  task will park at confirmed — which blocks every new claim you make. Fix it:',
+    fix,
+    `    node scripts/bongos/api.js POST /tasks/${taskId}/ship --body '{}'`,
+  ];
+}
+
+// pickStaleGateReviewRun — PURE. Among `gh run list --json
+// databaseId,headSha,status,conclusion` results for the gate-review workflow,
+// find a run on THIS head SHA that has already COMPLETED without success — the
+// one to re-run after the attestation is posted, because a new commit status does
+// NOT re-trigger a pull_request-triggered check (the task 1162 / PR #131 gotcha).
+// Returns the run's databaseId, or null when there's nothing stale to re-run (no
+// run yet, still in flight, or already green). Exported for unit tests.
+function pickStaleGateReviewRun(runs, headSha) {
+  if (!headSha || !Array.isArray(runs)) return null;
+  const hit = runs.find(
+    (r) => r && r.headSha === headSha && r.status === 'completed' && r.conclusion && r.conclusion !== 'success'
+  );
+  return hit ? (hit.databaseId ?? null) : null;
+}
+
+// rerunGateReviewIfStale — best-effort gh re-run of a stale (completed-non-success)
+// gate-review run on the current head, so it re-reads the freshly-posted
+// gate-author-trust attestation. Only acts when such a run exists: a freshly-opened
+// PR needs NO nudge (gate-review runs once, AFTER the attestation, and passes); the
+// SHA-reuse-after-red resume case (and the rare push-then-attest race) needs one.
+function rerunGateReviewIfStale(branch, headSha) {
+  const runs = ghJson([
+    'run', 'list', '--workflow', 'gate-review.yml', '--branch', branch,
+    '--json', 'databaseId,headSha,status,conclusion', '--limit', '15',
+  ]);
+  const id = pickStaleGateReviewRun(runs, headSha);
+  if (id == null) return false;
+  console.log(`  ci-land: re-running the stale gate-review check (run ${id}) so it re-reads the gate-author-trust attestation...`);
+  return ghArgvOk(['run', 'rerun', String(id)]);
+}
+
+// ---------- why the push failed, and whether retrying can ever help ----------
+//
+// A failed `git push` already parks the task at `confirmed` and opens no PR,
+// which is correct. What was wrong (task 1003293) was the ADVICE: "Fix the push
+// and re-ship" is useless for the most common cause, because re-shipping fails
+// identically every time and the reconciler cannot heal a branch that was never
+// pushed. The task then sits at `confirmed` with its code on one laptop, looking
+// like an ordinary pending land. That happened twice in one session — both times
+// on a commit touching .github/workflows/, both times invisible until someone
+// checked git instead of the log.
+//
+// So the distinction that matters is TERMINAL vs transient. A terminal failure
+// must name the actual remedy; a transient one may honestly say "re-ship".
+// `argvOk` runs the push with stdio:'inherit', so git's own message reaches the
+// log but nothing ever reads it — these patterns read it.
+const PUSH_DIAGNOSES = [
+  {
+    id: 'workflow_scope',
+    // GitHub's wording: "refusing to allow an OAuth App to create or update
+    // workflow `.github/workflows/x.yml` without `workflow` scope".
+    match: /without .{0,3}workflow.{0,3} scope|refusing to allow (?:an?|the) \S+ (?:App|integration)/i,
+    terminal: true,
+    why: 'this branch changes a file under .github/workflows/, and the credential git used has no `workflow` scope — GitHub refuses that push regardless of how often it is retried',
+    fix: 'push over SSH once, then re-run the ship:\n    git push git@github.com:<owner>/<repo>.git <branch>\n  (or re-authenticate the CLI with the `workflow` scope: gh auth refresh -h github.com -s workflow)',
+  },
+  {
+    id: 'protected_branch',
+    match: /GH006|protected branch|required status check/i,
+    terminal: true,
+    why: 'branch protection refused the push outright',
+    fix: 'land through a pull request instead of pushing directly, or have an admin adjust the rule',
+  },
+  {
+    id: 'auth',
+    match: /Authentication failed|could not read Username|Permission denied \(publickey\)|remote: Invalid username or password|403 Forbidden/i,
+    terminal: true,
+    why: 'git could not authenticate to the remote at all',
+    fix: 'restore the credential (gh auth login, or an SSH key the remote accepts), then re-run the ship',
+  },
+  {
+    id: 'stale_branch',
+    match: /non-fast-forward|fetch first|behind its remote counterpart|Updates were rejected/i,
+    terminal: false,
+    why: 'the remote branch has commits this checkout does not',
+    fix: 'git fetch && git rebase origin/<branch>, then re-run the ship',
+  },
+];
+
+// Pure: classify a failed push from git's stderr. Exported + tested.
+// An unrecognised failure is reported as NON-terminal on purpose — "try again"
+// is the safe default when we do not know, and a wrong "this can never work"
+// would send someone hunting a problem that does not exist.
+function pushDiagnosis(stderr) {
+  const text = String(stderr == null ? '' : stderr);
+  for (const d of PUSH_DIAGNOSES) {
+    if (d.match.test(text)) return { id: d.id, terminal: d.terminal, why: d.why, fix: d.fix };
+  }
+  return { id: 'unknown', terminal: false, why: 'the push failed for a reason this lane does not recognise', fix: 'read git\'s message above, resolve it, then re-run the ship' };
+}
+
+// Push, capturing stderr so it can be diagnosed — and echoing it so the log still
+// shows exactly what git said, which stdio:'inherit' gave us for free.
+function pushCapturing(branch, deps = {}) {
+  const exec = deps.execFileSync || require('node:child_process').execFileSync;
+  try {
+    exec('git', ['push', 'origin', branch], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, stderr: '' };
+  } catch (e) {
+    const stderr = [e && e.stderr, e && e.stdout].filter(Boolean).join('\n');
+    if (stderr) process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+    return { ok: false, stderr };
+  }
+}
+
+// ciLandLocal — today's local path: this machine pushes the branch + opens the PR
+// + enables auto-merge via git + gh. async since task 1169 — it asks the server to
+// post the gate-author-trust attestation between the push and the PR open.
+async function ciLandLocal(taskId, branch, valueSummary, { hold = false } = {}) {
+  const headSha = gitOk('git rev-parse HEAD');
+
+  console.log(`  pushing ${branch} to origin...`);
+  const pushed = pushCapturing(branch);
+  if (!pushed.ok) {
+    const d = pushDiagnosis(pushed.stderr);
+    console.log(`  ci-land: push FAILED — ${d.why}.`);
+    console.log(`  ci-land: nothing was pushed and no PR exists; task stays at confirmed.`);
+    if (d.terminal) {
+      // The important line. Re-shipping cannot fix this, and the reconciler
+      // cannot heal a branch that never reached the remote — so do not say
+      // "re-ship" and leave the work stranded on one machine.
+      console.log('  ci-land: RE-SHIPPING WILL FAIL THE SAME WAY. Do this instead:');
+      console.log(`    ${d.fix}`);
+    } else {
+      console.log(`  ci-land: to retry — ${d.fix}`);
+    }
+    for (const line of plainCardLines(`ship:${d.id}`)) console.log(line);
+    return landBailed(
+      `could not push ${branch} to origin (${d.id})`,
+      d.terminal ? d.fix.split('\n')[0] : `node scripts/bongos/ship.js ${taskId}`,
+    );
+  }
+
+  // task 1169 (ADR 0058): attest the author's trust tier on the head SHA BEFORE
+  // opening the PR, so the gate-review check reads it on its first (and only) run
+  // and a Metic+ gate-surface PR auto-passes — race-free for a fresh PR, since the
+  // `gh pr create` below is what fires gate-review and it runs only after this
+  // returns. (A reused open PR is handled by the re-run nudge after auto-merge.)
+  // task 1004055: the same call also records the land proof, so a miss here is not
+  // cosmetic — check it rather than firing and forgetting. Not fatal on this path:
+  // the branch is pushed and the PR lands regardless, so say what to do IF the ship
+  // is later refused, and carry on.
+  const gateProof = await attestGateTrust(taskId, headSha);
+  if (!gateProof.recorded) {
+    for (const line of landProofWarningLines(taskId, headSha, gateProof.reason, { merged: false })) console.log(line);
+  }
+
+  // Ensure exactly one PR for this branch. gh pr create is idempotent-ish: it
+  // errors if a PR already exists, so check first and reuse it.
+  const existing = ghJson(['pr', 'view', branch, '--json', 'number,url,state']);
+  // Reusing an already-open PR means gate-review may have ALREADY run (red, before
+  // the attestation existed) on this same head SHA — nudge a re-run below.
+  const reusingOpenPr = !!(existing && existing.state === 'OPEN');
+  // PR titles + bodies are GitHub-rendered: a bare "#NNN" autolinks into
+  // GitHub's PR/issue number space (dead links for GDS task ids — task 916),
+  // so the task ref is written as "task NNN" and the summary is de-#-ed.
+  const title = `task ${taskId}: ${sanitizeGitHubRefs(valueSummary) || branch}`.slice(0, 240);
+  const deployTargetNote = resolveInstanceBase() || 'the configured instance';
+  const body =
+    `Auto-opened by ship.js (deploy mode: ci) for task ${taskId}.\n\n` +
+    `${sanitizeGitHubRefs(valueSummary) || '(no value summary)'}\n\n` +
+    `Merging this PR triggers .github/workflows/deploy-prod.yml to deploy to ` +
+    `${deployTargetNote}. ${prMergeSentence(hold)}`; // task 1004379: a held round's PR says it waits
+  if (!existing || existing.state === 'CLOSED' || existing.state === 'MERGED') {
+    console.log('  ci-land: opening PR -> main...');
+    if (!ghArgvOk(buildPrCreateArgv(branch, title, body))) {
+      console.log('  ci-land: `gh pr create` failed. Is the GitHub CLI installed + authenticated (`gh auth status`)? Open the PR manually; task stays at confirmed.');
+      return landBailed('`gh pr create` failed (is gh installed + authenticated?)', `node scripts/bongos/ship.js ${taskId}`);
+    }
+  } else {
+    console.log(`  ci-land: reusing open PR ${existing.url}`);
+  }
+
+  // task 1004322: a held page tweak stops here — published, never armed.
+  if (hold) {
+    const pr = ghJson(['pr', 'view', branch, '--json', 'number,url,state']);
+    console.log(`  ci-land: PR ${(pr && pr.url) || 'opened'} — auto-merge NOT armed: waiting for the artist.`);
+    return landHeld({ prUrl: (pr && pr.url) || null });
+  }
+  console.log('  ci-land: enabling auto-merge (lands when required checks pass)...');
+  // task 1718: an enable-failure is NOT a dead-end — the PR is open and the server
+  // still lands green PRs. Don't return false (which stranded the builder at
+  // 'confirmed' with no in-session SHIPPED banner); fall through to the server poll,
+  // which drives + observes the land. See landPollAfterAutoMerge.
+  const autoMergeArmed = ghArgvOk(buildPrMergeArgv(branch));
+  if (!autoMergeArmed) {
+    console.log('  ci-land: GitHub auto-merge could not be armed from here (normal when shipping from a worktree, or with branch protection off). The PR is open; the server lands it — waiting for the land instead of stranding at confirmed...');
+  }
+
+  // task 1169: if we REUSED an open PR, a stale red gate-review run may sit on this
+  // same head SHA from before the attestation existed; a new commit status does not
+  // re-trigger a pull_request check, so re-run it (best-effort). A freshly-opened PR
+  // is left alone — its single gate-review run reads the attestation and passes.
+  if (reusingOpenPr) rerunGateReviewIfStale(branch, headSha);
+
+  // enable-success watches GitHub directly; enable-failure drives + watches the
+  // server land (publish-status reconcile-on-read). Both flip to 'shipped' on a real
+  // land, so the banner renders in-session and no 'confirmed' breadcrumb is written.
+  return landPollAfterAutoMerge(autoMergeArmed) === 'ci'
+    ? pollCiDeploy(taskId, branch, headSha)
+    : pollServerPublish(taskId, branch);
+}
+
+// Confirm the CI land actually reached production. Polls in stages:
+//   1. PR state -> MERGED (checks passing + branch protection satisfied); grabs
+//      the merge commit oid.
+//   2. the deploy-prod workflow run for that commit -> success.
+//   3. public edge healthz -> 200 (belt-and-braces, a different vantage).
+// Times out conservatively; on any timeout the task stays at confirmed with a
+// precise next step rather than a false "shipped".
+// `deps` exists for tests/ship_land_conflict.mjs; a real ship passes none.
+function pollCiDeploy(taskId, branch, headSha, deps = {}) {
+  const MERGE_TRIES = 30; // ~5 min at 10s — checks + auto-merge
+  const DEPLOY_TRIES = 24; // ~4 min at 10s — Actions deploy
+  const readJson = deps.ghJson || ghJson;
+  const pause = deps.pause || (() => shellOk(POLL_SLEEP_CMD));
+
+  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;
+  };
+  // task 1004289: a finished job's annotations never change, so each is read once.
+  let notStarted = false;
+  const startMemo = new Map();
+  const neverStarted = (c) => {
+    const key = String((c && c.detailsUrl) || '');
+    if (!startMemo.has(key)) startMemo.set(key, jobNeverStarted(c, readJson));
+    return startMemo.get(key);
+  };
+  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.
+    // 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;
+      break;
+    }
+    if (pr && pr.state === 'CLOSED') {
+      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/bongos/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/bongos/ship.js ${taskId}`);
+    }
+    if (pr) {
+      const md = localMergeDriver(pr, failingTestsFor, neverStarted);
+      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);
+      notStarted = !!(md && md.not_started);
+    }
+    conflicting = noteConflict(taskId, pr, conflicting);
+    pause();
+  }
+  if (!mergeSha) {
+    // 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, { red: stuckRed, notStarted });
+    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 = readJson([
+      'run', 'list', '--workflow', 'deploy-prod.yml', '--branch', 'main',
+      '--json', 'headSha,status,conclusion', '--limit', '15',
+    ]);
+    if (deployRunSucceeded(runs, mergeSha)) {
+      console.log('  ci-land: deploy-prod workflow succeeded for the merge commit.');
+      // Commit-pin the confirmation against /version (#858) — stronger than a
+      // liveness probe. The deploy run succeeding for OUR mergeSha is already
+      // authoritative, so /version only refines the message (and never turns a
+      // real deploy into a false negative on a transient miss or a concurrent
+      // later deploy).
+      const status = deployedCommitStatus(fetchDeployedVersion(), mergeSha);
+      const instanceBase = resolveInstanceBase();
+      const healthzUrl = instanceBase ? `${instanceBase}/healthz` : null;
+      if (status === 'match') {
+        console.log('  ci-land: /version confirms prod is live on the merge commit (commit-pinned).');
+      } else if (status === 'mismatch') {
+        console.log('  ci-land: deploy run succeeded; /version shows a different commit (a later deploy has since superseded it — fine, our change is in main).');
+      } else if (healthzUrl && shellOk(`curl -fsS --max-time 10 ${healthzUrl} -o /dev/null`)) {
+        console.log(`  ci-land: /version unavailable; ${healthzUrl} 200 — treating the successful deploy run as authoritative.`);
+      } else {
+        console.log('  ci-land: deploy run succeeded but /version + healthz probes both missed (likely transient). Treating the successful deploy run as authoritative.');
+      }
+      return landed();
+    }
+    pause();
+  }
+  // task 1049: merged but the deploy run hasn't confirmed in-window — still
+  // success-pending (it deploys on its own), not a failure.
+  printLandPending(taskId, { merged: true });
+  return landPending();
+}
+
+module.exports = {
+  localHistoryRewritten, // task 1003221 — the append-only discriminator
+  pushDiagnosis, // task 1003293 — a terminal push failure must not advise a retry
+  PUSH_DIAGNOSES,
+  ciLand,
+  classifyLandOutcome,
+  formatPublishFailure,
+  // task 1004055: the land-proof half of attest-gate. attestGateTrust is exported
+  // so the LOCAL-merge path can record a proof it previously never recorded at all;
+  // the two pure halves so the truth table + the wording are pinned without a server.
+  attestGateTrust,
+  landProofRecorded,
+  landProofWarningLines,
+  // task 1002572 (PART 2): the bail ids + the pure "can a PR still land this?"
+  // decision, so the single-checkout fallback is opt-in per bail and unit-tested.
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
+  landBailed,
+  landHeld,
+  landPending,
+  landPendingLines,
+  landPollAfterAutoMerge,
+  landed,
+  pickStaleGateReviewRun,
+  reconcileBlockedLines,
+  prAssigneeLine,
+  redPrLine,
+  redPrLines,
+  // task 1003499: a CONFLICTING PR is named while the land waits, and a wait that
+  // ends conflicting is a bail, not "landing automatically". The polls are exported
+  // with their optional `deps` so the test drives the real loops.
+  prConflicting,
+  conflictPrLines,
+  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,
+  // task 1004289: CI that never ran is said as such, not as a failure to fix.
+  jobNeverStarted,
+  notStartedLines,
+  reconciledCardStatus,
+  strandCommand,
+  strandNextStep,
+};