@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/ship-land.js

@@ -1,1130 +1,6 @@
-// scripts/gds/ship-land.js — the land outcome type and the ci-land paths (local, server-mediated) + their polling.
-//
-// Carved out of scripts/gds/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.
-
+// scripts/gds/ship-land.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/ship-land.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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/gds/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/gds/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/gds/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/gds/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/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,`,
-    `  and the task flips to 'shipped' on its own. Re-run \`node scripts/gds/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/gds/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/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).
-// 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/gds/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/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}`);
-      }
-    }
-    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/gds/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/gds/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/gds/api.js POST /tasks/${taskId}/attest-gate --body '{"head_sha":"<the merge commit on main>"}'`,
-      `    node scripts/gds/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/gds/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/gds/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/gds/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/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, 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,
-};
+require('../bongos/forwarder.js').forward(module, 'ship-land.js');