@bongos/core 1.19.318 → 1.19.320

package/scripts/gds/ship-land.js

@@ -0,0 +1,539 @@
+// 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.
+
+'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');
+
+// ---------- 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.
+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) { return { ok: false, pending: false, reason, nextStep }; }
+
+// 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.
+async function ciLand(taskId, branch, valueSummary) {
+  console.log('  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
+  if (pushVia() === 'server') {
+    return ciLandServer(taskId, branch, valueSummary);
+  }
+  return await ciLandLocal(taskId, branch, valueSummary);
+}
+
+// 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}`;
+  // git stderr is multi-line; this is embedded mid-sentence in one log line.
+  const reason = details.reason ? String(details.reason).replace(/\s+/g, ' ').trim() : '';
+  const parts = [];
+  if (details.step) parts.push(`step: ${details.step}`);
+  if (reason) parts.push(`reason: ${reason}`);
+  let out = parts.length ? `${label} (${parts.join('; ')})` : label;
+  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.';
+  }
+  return out;
+}
+
+// ciLandServer — the dev-box 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. Requires a RE-AUTHED (non-box) cli session — a
+// box-scoped session is 403'd by the endpoint (it must `/builder-reauth` first).
+async function ciLandServer(taskId, branch, valueSummary) {
+  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');
+    // allowBoxScope: handle the box_scope 403 locally (graceful "stays at
+    // confirmed, re-auth + re-ship") instead of cli-lib's central exit — task
+    // 1050. (In practice unreachable: a box session can't have claimed/confirmed
+    // to get here. Kept as a defensive, graceful path.)
+    const r = await (await cliClient({ allowBoxScope: true })).tasks.postTasksIdPublishBranch({
+      id: taskId,
+      body: { branch, head_sha: headSha, value_summary: valueSummary, bundle_b64: bundleB64 },
+    });
+    if (r.status === 403 && normalizeApiError(r.data).code === 'box_scope') {
+      console.log('  ci-land: this session is BOX-SCOPED — run /builder-reauth (browser, no terminal) to mint a real session, then re-ship. Task stays at confirmed.');
+      return landBailed('this CLI session is box-scoped', '/builder-reauth');
+    }
+    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'));
+    }
+    console.log(`  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
+    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 box-appropriate next step when a ship lands the task at
+// 'confirmed' without finishing. A dev box (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 ON A BOX (the #1027 retrospective: the agent
+// had to reverse-engineer recovery from source). Point a box 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.
+function landPendingLines(taskId, { merged } = {}) {
+  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);
+}
+
+// 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.`,
+  ];
+}
+
+// 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.
+async function pollServerPublish(taskId, branch) {
+  const TRIES = 54; // ~9 min at 10s — checks + auto-merge + Actions deploy
+  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;
+  for (let i = 0; i < TRIES; i++) {
+    const r = await (await cliClient()).tasks.getTasksIdPublishStatus({ id: taskId, query: { branch } });
+    if (r.ok && r.data) {
+      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}`);
+      }
+    }
+    shellOk(POLL_SLEEP_CMD);
+  }
+  if (blockedReason) {
+    console.log('');
+    for (const line of reconcileBlockedLines(taskId, blockedReason)) 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}`);
+  }
+  printLandPending(taskId);
+  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.
+async function attestGateTrust(taskId, headSha) {
+  if (!headSha) return;
+  try {
+    const r = await (await cliClient()).tasks.postTasksIdAttestGate({ id: taskId, body: { head_sha: headSha } });
+    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.`);
+      }
+    } else 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.');
+    } else {
+      console.log(`  ci-land: gate attestation request failed (HTTP ${r.status}); a gate-surface PR may need a manual re-run / owner approval.`);
+    }
+  } catch (_) {
+    /* best-effort — never block the ship on the attestation */
+  }
+}
+
+// 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)]);
+}
+
+// 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) {
+  const headSha = gitOk('git rev-parse HEAD');
+
+  console.log(`  pushing ${branch} to origin...`);
+  if (!gitArgvOk(['push', 'origin', branch])) {
+    console.log('  ci-land: push failed; task stays at confirmed. Fix the push and re-ship.');
+    return landBailed(`could not push ${branch} to origin`, `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.)
+  await attestGateTrust(taskId, headSha);
+
+  // 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}. Auto-merge is enabled — GitHub lands it once the ` +
+    `required checks pass.`;
+  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}`);
+  }
+
+  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".
+function pollCiDeploy(taskId, branch, headSha) {
+  const MERGE_TRIES = 30; // ~5 min at 10s — checks + auto-merge
+  const DEPLOY_TRIES = 24; // ~4 min at 10s — Actions deploy
+
+  console.log('  ci-land: waiting for auto-merge (checks + branch protection)...');
+  let mergeSha = null;
+  for (let i = 0; i < MERGE_TRIES; i++) {
+    const pr = ghJson(['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}`);
+    }
+    shellOk(POLL_SLEEP_CMD);
+  }
+  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.
+    printLandPending(taskId);
+    return landPending();
+  }
+  console.log(`  ci-land: merged to main (${mergeSha.slice(0, 8)}). Waiting for the prod deploy...`);
+
+  for (let i = 0; i < DEPLOY_TRIES; i++) {
+    const runs = ghJson([
+      '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();
+    }
+    shellOk(POLL_SLEEP_CMD);
+  }
+  // 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
+  ciLand,
+  classifyLandOutcome,
+  formatPublishFailure,
+  landBailed,
+  landPending,
+  landPendingLines,
+  landPollAfterAutoMerge,
+  landed,
+  pickStaleGateReviewRun,
+  reconcileBlockedLines,
+  reconciledCardStatus,
+  strandCommand,
+  strandNextStep,
+};