@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/ship-merge.js

@@ -0,0 +1,466 @@
+// scripts/bongos/ship-merge.js — autoMerge — the merge/regen/push/land chain that puts the branch on main.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite. 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.
+//
+// task 1002572 (PART 2) split the entry point in two: `mergeLocally` is the original
+// merge/regen/push/deploy chain, and `autoMerge` is a thin wrapper that routes the one
+// bail a PR can still land — a single checkout whose main worktree holds the feature
+// branch — into the push+PR path instead of stranding the task at 'confirmed'.
+
+'use strict';
+
+const path = require('node:path');
+const { cleanupMacFinderDupRefs } = require('../../modules/lifecycle/ship-preflight');
+const mergeLock = require('../../modules/lifecycle/merge-lock');
+const { buildMergeArgv, gitArgvOk, gitOk, shellOk } = require('./ship-git.js');
+const { mainIsProtected, pushVia, readDeployConfigRaw, resolveDeployMode, resolveDeployTarget, safeBranding, shouldBailOnFetchFailure } = require('./ship-deploy-target.js');
+const {
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  attestGateTrust,
+  ciLand,
+  landBailRecoverableByPr,
+  landBailed,
+  landProofWarningLines,
+  landed,
+} = require('./ship-land.js');
+const { runSmoke } = require('./ship-grade.js');
+const { gateMergeResult } = require('./ship-merge-gate.js');
+const { dbOnlyIgnoredNotice } = require('./ship-honesty.js');
+const { currentBranch, mainWorktreeBusy, regenerateApiDocs, regenerateCopyInventory, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
+const { MAIN_CHECKED_OUT, REPO_ROOT } = require('./ship-state.js');
+const { envPrefix } = require('../../src/instance-config');
+
+// zeroCommitVerdict — dbOnly is deliberately consulted ONLY at zero commits
+// ahead: a branch carrying real commits must be merged, whatever flag was typed.
+// That asymmetry is correct and is not a bug — but it means an explicitly-passed
+// --db-only can be DROPPED, so mergeLocally pairs this with dbOnlyIgnoredNotice
+// (task 1003959) rather than letting the drop happen in silence.
+function zeroCommitVerdict(commitsAhead, dbOnly) {
+  if (commitsAhead !== '0') return 'has-commits';
+  return dbOnly ? 'db-only' : 'refuse';
+}
+
+// onMainNextStep — PURE. The recovery command for the other half of the
+// single-checkout catch-22 (task 1002572): the builder is standing ON main, so
+// there is no head branch to merge FROM and none to open a PR from either. Since
+// mergeLocally's sibling bail now falls back to the PR path, shipping from the
+// task branch WORKS even in a single checkout — so the cure is "go back to the
+// branch and re-ship", not the circular /merge-mode this used to advise. Only
+// name the branch when it actually exists locally; otherwise fall back to
+// /merge-mode rather than inventing a checkout target.
+function onMainNextStep(taskId, taskBranchExists) {
+  return taskBranchExists
+    ? `git checkout task-${taskId} && node scripts/bongos/ship.js ${taskId}`
+    : '/merge-mode';
+}
+
+// localTaskBranchExists — does this checkout still hold the task's own branch? The
+// discriminator onMainNextStep needs, so the advice only names a branch that is
+// really there (a builder who deleted it gets /merge-mode, not a failing checkout).
+function localTaskBranchExists(taskId) {
+  return gitArgvOk(['rev-parse', '--verify', '--quiet', `refs/heads/task-${taskId}`], { stdio: 'ignore' });
+}
+
+// autoMerge — the land entry point. Runs the local merge chain, then (task 1002572
+// PART 2) routes the ONE bail a PR can still land into the push+PR path instead of
+// leaving the task at 'confirmed'. The fallback deliberately sits OUTSIDE
+// mergeLocally: its `finally` releases the shared merge lock and normalizes the main
+// worktree, and the PR poll that follows can run for minutes — holding the lock
+// across it would wedge every other ship on this machine.
+// `deps` is a test seam ONLY — the routing is the whole deliverable and it cannot
+// be reached from a unit test otherwise (mergeLocally needs a real second checkout
+// and an authed gh). Callers pass nothing; the defaults are the real functions.
+async function autoMerge(taskId, valueSummary, opts = {}, deps = {}) {
+  const merge = deps.mergeLocally || mergeLocally;
+  const land = deps.ciLand || ciLand;
+  const branchOf = deps.currentBranch || currentBranch;
+  const outcome = await merge(taskId, valueSummary, opts);
+  if (!landBailRecoverableByPr(outcome && outcome.bailId)) return outcome;
+  const branch = branchOf();
+  console.log('  auto-merge: a local merge is impossible from this checkout, but the branch is still landable —');
+  console.log('  falling back to the push+PR land path. Nothing is stranded; the server lands the PR.');
+  return await land(taskId, branch, valueSummary);
+}
+
+// regenerateShipArtifacts — every generated artifact a branch must carry fresh,
+// in the order the land has always refreshed them. Moved out of mergeLocally
+// unchanged (task 1004322) so the held publish below carries the same set.
+function regenerateShipArtifacts() {
+  regenerateDiagrams();
+  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
+  regenerateRepoMap();
+  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
+  regenerateSessionIndex();
+  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
+  regenerateFileMap();
+  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
+  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
+  // the ship path regenerated it, so the PR was born stale and CI said so.
+  regenerateCopyInventory();
+  // Refresh the committed API pointer stub (task 1918). The spec, reference and typed
+  // client are gitignored and rebuilt by their consumers (task 1004866), so nothing here
+  // regenerates or commits them any more.
+  regenerateApiDocs();
+}
+
+// publishHeld — the held pass's whole "land" (task 1004322, ADR 0341 D7). A page
+// tweak whose grade passed waits at completed for its artist, and the Approval
+// queue shows the APPLIED BRANCH, so the branch and its PR must exist now: a
+// grade-parked ship otherwise never publishes, and the later approve would strand
+// at no_branch_no_tip. This publishes, in every deploy mode, through the PR path
+// (never a local merge to main) and stops: no auto-merge, no poll, no land.
+// `deps` is a test seam only.
+async function publishHeld(taskId, valueSummary, deps = {}) {
+  const branch = (deps.currentBranch || currentBranch)();
+  if (!branch || branch === 'main' || branch === 'HEAD') {
+    return landBailed(
+      `nothing to publish — this checkout is on ${branch}, not the task branch`,
+      onMainNextStep(taskId, (deps.localTaskBranchExists || localTaskBranchExists)(taskId)),
+    ); // untagged on purpose: only autoMerge routes by bail id
+  }
+  (deps.regenerate || regenerateShipArtifacts)();
+  return await (deps.ciLand || ciLand)(taskId, branch, valueSummary, { hold: true });
+}
+
+async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
+  const branch = currentBranch();
+  if (!branch || branch === 'main' || branch === 'HEAD') {
+    // task 1002723: an --allow-empty / --db-only ship legitimately runs FROM the
+    // main checkout (nothing was ever committed), but this bail fired BEFORE the
+    // deliberate-empty landing below could — the task parked at confirmed with no
+    // branch and no published tip, a shape the server sweep can never prove (the
+    // task-1002716 strand). Land it here iff the checkout has zero commits ahead
+    // of origin/main; anything else keeps the safe bail.
+    if (dbOnly && shellOk('git fetch origin main')
+        && zeroCommitVerdict(gitOk('git rev-list origin/main..HEAD --count'), true) === 'db-only') {
+      console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) from the main checkout - nothing to merge; advancing to shipped without merge/deploy.');
+      return landed({ noArtifact: true, noArtifactReason: 'empty ship from the main checkout — no commits to merge' });
+    }
+    console.log(`  auto-merge: skipped (current branch is ${branch})`);
+    // The merge source IS the current branch, so on main there is nothing to
+    // merge. Half of the single-checkout catch-22 this task documents: the other
+    // half is the "main worktree is on <branch>, not main" bail below, which now
+    // falls back to a PR. This half CANNOT — a PR needs a head branch and there
+    // is none here — so it stays a bail, but with a next step that actually
+    // recovers instead of pointing back at the same dead end (task 1002572).
+    return landBailed(
+      `nothing to merge — this checkout is on ${branch}, not a task branch`,
+      onMainNextStep(taskId, localTaskBranchExists(taskId)),
+      LAND_BAIL_NO_TASK_BRANCH,
+    );
+  }
+
+  // Refresh the data-driven diagrams before computing commits-ahead, so a
+  // diagram-only refresh still counts as something to deploy.
+  regenerateShipArtifacts();
+
+  // Resolve the deploy mode ONCE (task 1093 / C9) — it reads config/deploy.json;
+  // reused at the fetch-bail check + the ci-land branch below.
+  const deployMode = resolveDeployMode();
+
+  // DB-only / no-op ship detection (task #219). Some legitimate ships have
+  // no commits to merge — e.g. a task whose work was a direct SQL write to
+  // the production DB. The change is already live; the merge step has
+  // nothing to push, merge, or deploy. Short-circuit so the caller's POST
+  // /tasks/:id/ship still flips status to shipped instead of stranding the
+  // task at confirmed forever.
+  // A credential-less checkout can't `git fetch origin main` (private origin, no
+  // creds — ADR 0053), but that's only fatal OFF the server-publish path: the
+  // ADR-0055 path bundles against its LOCAL origin/main and the server tops
+  // up main. Without this, such a checkout dead-ends here and strands every ship at
+  // confirmed (task 1027). The `!fetchedMain &&` short-circuit keeps the gh-probe
+  // (pushVia) off the happy laptop path, so laptop behavior is byte-for-byte.
+  const fetchedMain = shellOk('git fetch origin main');
+  if (!fetchedMain && shouldBailOnFetchFailure(fetchedMain, deployMode, pushVia())) {
+    console.log('  auto-merge: fetch failed; task stays at confirmed for /merge-mode');
+    return landBailed('could not fetch origin/main', '/merge-mode');
+  }
+  const commitsAhead = gitOk('git rev-list origin/main..HEAD --count');
+  const verdict = zeroCommitVerdict(commitsAhead, dbOnly);
+  // task 1003959: the verdict above drops an explicitly-passed --db-only when the
+  // branch has commits. Say so HERE — before the push, the merge and the deploy —
+  // so the operator learns their flag did not apply while the run can still be
+  // stopped, not from a PR that landed differently than they expected.
+  for (const line of dbOnlyIgnoredNotice(taskId, { dbOnly, commitsAhead, branch, deployMode })) console.log(line);
+  if (verdict === 'refuse') {
+    // task 391 (idea #37): the old code short-circuited ANY zero-commit branch
+    // straight to shipped — silently advancing a claim with empty/wrong touches[]
+    // or simply uncommitted work, awarding credit for no change. Now a zero-commit
+    // ship must be DELIBERATELY declared with --db-only. Fail-safe: the claim is
+    // already resolved by this point, so the task stays at confirmed and a plain
+    // re-run resumes the merge leg (task 941) once they commit or pass --db-only.
+    console.error('');
+    console.error('  Ship refused: no commits ahead of main, and --db-only was not passed.');
+    console.error('  A zero-commit ship is almost always a mistake (uncommitted work, wrong branch, or empty/incorrect touches[]).');
+    console.error('   • If you have local changes, commit them, then re-ship.');
+    console.error('   • If this is a DELIBERATE direct-SQL / DB-only ship (the work was a write straight to the prod');
+    console.error('     DB — nothing to merge or deploy), re-run with --db-only:');
+    console.error(`       node scripts/bongos/ship.js ${taskId} --db-only`);
+    console.error('  The task stays at confirmed; nothing was merged or deployed.');
+    return landBailed('no commits ahead of main, and --db-only was not passed', `node scripts/bongos/ship.js ${taskId} --db-only`);
+  }
+  if (verdict === 'db-only') {
+    console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) - no commits ahead of main; advancing to shipped without merge/deploy.');
+    return landed({ noArtifact: true, noArtifactReason: 'empty ship — no commits ahead of main' });
+  }
+
+  // #679 / ADR 0042: in 'ci' deploy mode the operator's machine never merges or
+  // SSHes the droplet — ship lands via PR auto-merge and CI deploys. The laptop
+  // block below stays the default ('laptop' mode) so this is inert until the
+  // deliberate cutover. The DB-only short-circuit above is shared by both modes.
+  if (deployMode === 'ci') {
+    return await ciLand(taskId, branch, valueSummary);
+  }
+
+  console.log(`  pushing ${branch} to origin...`);
+  if (!gitArgvOk(['push', 'origin', branch])) {
+    console.log('  auto-merge: push failed; task stays at confirmed for /merge-mode');
+    return landBailed(`could not push ${branch} to origin`, '/merge-mode');
+  }
+
+  // Serialize the shared-main-worktree merge (#462 C4; #269 C6). Concurrent
+  // ships AND manual /merge-mode runs queue on this one lock; if a live holder
+  // is still merging past the wait window we bail cleanly to /merge-mode rather
+  // than racing its working tree.
+  if (!mergeLock.acquire(REPO_ROOT)) {
+    console.log('  auto-merge: another active ship or /merge-mode run holds the merge lock; task stays at confirmed for /merge-mode');
+    return landBailed('another ship or /merge-mode run holds the merge lock', '/merge-mode');
+  }
+  let mergedClean = false;
+  try {
+    // Never touch REPO_ROOT if a parallel session left it mid-merge or dirty —
+    // this is the exact collision that previously bailed with the misleading
+    // "main is ahead of origin somehow" (#462).
+    const busy = mainWorktreeBusy();
+    if (busy) {
+      console.log(`  auto-merge: main worktree busy (${busy}); task stays at confirmed for /merge-mode`);
+      return landBailed(`the main worktree is busy (${busy})`, '/merge-mode');
+    }
+
+    console.log(`  switching to main worktree (${REPO_ROOT}) for merge...`);
+    // Same cleanup as preflight: drop macOS Finder/iCloud `* 2` ref duplicates
+    // before fetching, otherwise `git fetch origin` fails with "bad object
+    // refs/heads/<name> 2" and the auto-merge bails. Was a recurring 2026-05-10
+    // failure mode — every ship of the day hit this and required /merge-mode.
+    const dupRefs = cleanupMacFinderDupRefs(REPO_ROOT);
+    if (dupRefs.length > 0) {
+      console.log(`  auto-merge: removed ${dupRefs.length} stray refs (macOS Finder duplicates)`);
+    }
+    if (!shellOk(`git fetch origin`, { cwd: REPO_ROOT })) {
+      console.log('  auto-merge: fetch failed; task stays at confirmed for /merge-mode');
+      return landBailed('could not fetch origin in the main worktree', '/merge-mode');
+    }
+
+    // The main worktree must currently have main checked out.
+    const onMain = gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT });
+    if (onMain !== 'main') {
+      console.log(`  auto-merge: main worktree is on ${onMain}, not main — a local merge is impossible here`);
+      // The other half of the single-checkout catch-22: the merge target tree is
+      // the one holding the feature branch, so there is nowhere to merge INTO.
+      // task 1002572 (PART 2): this is a property of the MACHINE, not of the work
+      // — the branch lands fine via a PR. Tagged PR-recoverable so autoMerge falls
+      // back instead of parking the task at 'confirmed' unpaid. The reason +
+      // nextStep are kept for the case where the fallback itself bails.
+      // task 1004584: when NO worktree holds main at all, say exactly that and
+      // how to fix it — REPO_ROOT is then the primary checkout by fallback, and
+      // "work in your own worktree" is advice the builder already followed.
+      return landBailed(
+        MAIN_CHECKED_OUT
+          ? `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`
+          : `no worktree of this repo has main checked out (the main checkout ${REPO_ROOT} is on ${onMain}) — run \`git checkout main\` there, then re-ship`,
+        MAIN_CHECKED_OUT ? '/merge-mode' : `git -C "${REPO_ROOT}" checkout main && node scripts/bongos/ship.js ${taskId}`,
+        LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+      );
+    }
+
+    if (!gitArgvOk(['merge', '--ff-only', 'origin/main'], { cwd: REPO_ROOT })) {
+      console.log('  auto-merge: main is ahead of origin somehow; task stays at confirmed');
+      return landBailed('the local main is ahead of origin/main', '/merge-mode');
+    }
+
+    // The tree the merge result will be compared against (task 1004032). The
+    // ff-only step above has just proved local main IS origin/main, so this is
+    // main as the rest of the world currently sees it — read before the branch
+    // is merged in, because afterwards the commit is no longer reachable by name.
+    const baseSha = gitOk('git rev-parse HEAD', { cwd: REPO_ROOT });
+
+    // #681: build the merge argv and run it WITHOUT a shell. valueSummary is
+    // DB-sourced (untrusted) — passing it as a literal argv element means
+    // `$(...)`/backticks in it can never be interpreted as a command.
+    if (!gitArgvOk(buildMergeArgv(branch, valueSummary), { cwd: REPO_ROOT })) {
+      console.log('  auto-merge: merge failed (conflicts?); task stays at confirmed for manual /merge-mode');
+      return landBailed(`merging ${branch} into main failed (conflicts?)`, '/merge-mode');
+    }
+
+    console.log('  smoke against post-merge state...');
+    if (!runSmoke().clean) {
+      console.log('  auto-merge: post-merge smoke failed; task stays at confirmed; investigate');
+      return landBailed('post-merge smoke tests failed', '/merge-mode');
+    }
+
+    // task 1004032: the merge result is about to BECOME main by a direct push,
+    // which no required status check gates. Run the same fitness gate CI would
+    // have run on a PR, and refuse the push when this branch is what turns main
+    // red. A failure already present on the pre-merge base is reported and
+    // waved through — see scripts/bongos/ship-merge-gate.js for why.
+    const fitnessVerdict = gateMergeResult({ repoRoot: REPO_ROOT, baseSha });
+    if (fitnessVerdict.block) {
+      return landBailed(
+        fitnessVerdict.reason === 'regression'
+          ? 'fitness fails on the merge result and passes on the pre-merge main — this branch would turn main red'
+          : 'fitness fails on the merge result and the pre-merge main could not be measured',
+        'node scripts/bongos/fitness.js',
+      );
+    }
+
+    console.log('  pushing merged main to origin...');
+    // SEC #863: route through push-main.js, which carries the
+    // <PREFIX>_ALLOW_MAIN_PUSH override so the pre-push permission gate lets THIS
+    // graded+confirmed pipeline push through while still blocking ad-hoc
+    // `git push origin main`. process.execPath (quoted) for the same
+    // cross-platform reason as the other node spawns here (#660).
+    if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'push-main.js'))}`, { cwd: REPO_ROOT })) {
+      console.log('  auto-merge: push failed; task stays at confirmed');
+      // task 1002629: a branch-protected main refuses EVERY direct push, so
+      // retrying here can never work — resolveDeployMode normally reroutes to
+      // the ci PR path before this point; reaching this with protection on
+      // means an env-forced 'laptop' or a failed protection probe.
+      if (mainIsProtected() === true) {
+        return landBailed(`main is branch-protected — the direct push can never land; unset the DEPLOY_MODE env override (${envPrefix()}_DEPLOY_MODE, or the legacy OTB_DEPLOY_MODE) — the ci PR path lands it`, `node scripts/bongos/ship.js ${taskId}`);
+      }
+      return landBailed('could not push the merged main to origin', '/merge-mode');
+    }
+
+    // task 1004055: RECORD THE LAND PROOF — the step this path never had.
+    //
+    // The two OTHER land paths each tell the server which commit is this task's:
+    // ciLandLocal posts attest-gate after its push, ciLandServer gets it from
+    // publish-branch. This path merges and pushes main ITSELF, so nothing ever did,
+    // and claims.published_head_sha stayed NULL. It also opens no PR and deletes the
+    // branch below, so getPublishStatus can find nothing by head ref either — which
+    // left deriveShipAssurance with neither of its two proofs and made the POST /ship
+    // three lines later refuse with ship_land_not_proven, EVERY time, with the work
+    // already merged. The task then parked at 'confirmed', gating its builder's whole
+    // queue, until someone ran the recovery by hand (five consecutive ships,
+    // 2026-09-19; twelve refusals in one day's audit log).
+    //
+    // The merge commit is the sha to record: the push above just put it on main, so
+    // the ancestry check cannot fail, and it is what the hand-recovery always used.
+    // It goes HERE, immediately after the push and BEFORE both the deploy step (which
+    // can bail) and the branch deletion (which destroys the only other evidence) —
+    // the proof must exist from the first moment the work is on main.
+    const mergeSha = gitOk('git rev-parse HEAD', { cwd: REPO_ROOT });
+    const proof = await attestGateTrust(taskId, mergeSha);
+    if (proof.recorded) {
+      console.log(`  auto-merge: land proof recorded (merge ${String(mergeSha).slice(0, 8)} on main).`);
+    } else {
+      for (const line of landProofWarningLines(taskId, mergeSha, proof.reason)) console.log(line);
+    }
+
+    // Deploy step. The core carries NO deploy target of its own — under the
+    // standalone model a core change reaches a live instance via package-core +
+    // `bongos upgrade` (pin-bump), NOT an SSH deploy (ADR 0108). So unless an
+    // instance whose own checkout IS its live server has configured a target
+    // (config/deploy.json "sshTarget" or <PREFIX>_DEPLOY_SSH_TARGET), the land is
+    // complete at "merged + pushed to main" and the SSH deploy is skipped. (This
+    // used to SSH a hardcoded target — the founder instance's old game box, i.e. the
+    // WRONG server post-migration. task 1002202.)
+    const { sshTarget, healthzUrl } = resolveDeployTarget({
+      configRaw: readDeployConfigRaw(),
+      branding: safeBranding(),
+    });
+    if (!sshTarget) {
+      console.log('  merged + pushed to main. No deploy target configured, so no SSH deploy —');
+      console.log('  expected for the core. To publish to a live instance run the standalone release');
+      console.log('  flow: package-core → bongos upgrade (pin-bump), per ADR 0108. (Not an SSH deploy.)');
+    } else {
+      console.log(`  triggering deploy on ${sshTarget}...`);
+      // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it before ssh
+      // transmits the command; with the quotes ssh sends the literal `~/deploy.sh`
+      // and the REMOTE shell expands it. (Matches /merge-mode SKILL.md:81.)
+      if (!shellOk(`ssh -o ConnectTimeout=10 ${sshTarget} "~/deploy.sh"`)) {
+        // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
+        // service-restart window (Node not yet bound) and exit non-zero even though
+        // the deploy succeeded — which used to false-fail the ship and force a
+        // needless /merge-mode. Before concluding failure, re-probe the CONFIGURED
+        // /healthz with backoff (curl's own --retry; cross-platform, no sleep) —
+        // never a hardcoded host. --retry-all-errors retries connection-refused
+        // during the bind window; -f makes a non-200 an error so a 502/503 also
+        // retries. If it comes up within the window the deploy really succeeded.
+        if (healthzUrl) {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
+          if (shellOk(`curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors ${JSON.stringify(healthzUrl)} -o /dev/null`)) {
+            console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
+          } else {
+            console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
+            return landBailed('merged to main, but the deploy failed (/healthz never returned 200)', '/merge-mode');
+          }
+        } else {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero and no healthzUrl configured to re-probe; task stays at confirmed');
+          return landBailed('merged to main, but ~/deploy.sh returned non-zero (no healthz to re-probe)', '/merge-mode');
+        }
+      }
+    }
+
+    // Merged + deployed — the feature branch is permanently in main's history
+    // (--no-ff merge commit) and no longer needed on origin. Deleting it keeps
+    // GitHub's "Create PR" affordance from offering empty PRs against zero-diff
+    // branches and prevents builder confusion about whether a branch landed.
+    // Local refs/heads ref stays so the worktree on the Mac isn't disturbed
+    // (cleanup of stale local refs happens next `git fetch --prune`).
+    // Non-blocking: a deploy that succeeded shouldn't be marked failed just
+    // because the cleanup push fails (e.g. branch already deleted manually,
+    // permission glitch, network blip).
+    console.log(`  cleaning up: deleting ${branch} on origin...`);
+    if (!gitArgvOk(['push', 'origin', '--delete', branch], { cwd: REPO_ROOT })) {
+      console.log(`  warn: could not delete origin/${branch} — may already be gone (non-blocking)`);
+    }
+
+    console.log('  flipping task to shipped...');
+    mergedClean = true;
+    return landed();
+  } finally {
+    // Leave REPO_ROOT clean for the NEXT ship/merge no matter how we exited.
+    // A failed merge here wedges everyone else: a conflict leaves the tree
+    // mid-merge (MERGE_HEAD + conflicted index → mainWorktreeBusy() rejects all
+    // future ships), and a failure AFTER the local merge commit but BEFORE push
+    // (post-merge smoke/push/deploy) leaves main ahead-but-unpushed (the next
+    // `git merge --ff-only origin/main` then fails with the misleading "main is
+    // ahead of origin somehow"). Only normalize on the failure path — on the
+    // success path we already pushed, so touching the tree is needless risk.
+    // Best-effort: cleanup must never mask the real outcome. This is the
+    // clean-failure twin of merge-lock.recoverWorktree() (which handles the
+    // crash/stale-reclaim case where we never reach this finally at all).
+    if (!mergedClean) {
+      try {
+        if (gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT })) {
+          shellOk('git merge --abort', { cwd: REPO_ROOT });
+        }
+        if (gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT }) === 'main') {
+          shellOk('git reset --hard origin/main', { cwd: REPO_ROOT });
+        }
+      } catch (_) {
+        /* best-effort cleanup; the lock release below is what matters most */
+      }
+    }
+    mergeLock.release(REPO_ROOT);
+  }
+}
+
+module.exports = {
+  autoMerge,
+  // task 1004584: the local merge leg on its own, so the vendored-instance
+  // regression test can read a bail's reason without the PR fallback (which
+  // needs an authed gh) swallowing it.
+  mergeLocally,
+  // task 1004322: the held page tweak's publish-only path.
+  publishHeld,
+  // task 1002572 (PART 2): the pure recovery command for a ship run from main —
+  // exported so the "don't point back at the dead end" wording is pinned.
+  onMainNextStep,
+  zeroCommitVerdict,
+};

package/scripts/bongos/ship-mode-ask.js

@@ -0,0 +1,138 @@
+// scripts/bongos/ship-mode-ask.js — the first-ship ship-mode question (task 1004630, ADR 0369).
+//
+// WHY. Ship mode says who starts a ship: Auto (the AI ships on its own) or Manual
+// (a person approves each ship). The creation wizard asks for it (task 1004629),
+// but a project made before that step, or by `bongos init`, never answered. Such a
+// project quietly runs on the default, so its owner never learns there was a choice.
+// This asks ONCE, at the next ship, and saves the answer. Once saved the mode reads
+// as chosen and the question never comes back.
+//
+// HOW. The ship stops BEFORE anything resolves (the claim stays active) and prints
+// an ask the AI turns into a two-option question for the person. The AI re-runs the
+// same ship with `--ship-mode auto|manual`; that saves the answer and the ship goes on.
+//
+// It never blocks a ship it cannot get an answer for. The ship goes on with the
+// default, and nobody is asked, when:
+//   - the mode could not be read (the resolver's own posture: a ship is never
+//     blocked by a settings read);
+//   - the caller cannot change project settings (only an owner-side builder can
+//     answer, so asking a teammate would stop every ship of theirs for nothing);
+//   - nobody is there to answer (an Autobongos worker or a subagent).
+//
+// The decision is pure (shipModeAskVerdict) so tests prove it with no network.
+
+'use strict';
+
+// The ship exits with this code when it stops to ask. Distinct from 1 (failure)
+// and 2 (usage), and from the grade cap's 6, so a wrapper can tell "a question is
+// waiting" from "something broke".
+const ASK_EXIT = 5;
+
+const ASK_MARKER = '[otb-ask-ship-mode]';
+
+// unattended(env) — true when no person is there to answer.
+// OTB_SUBAGENT is set on every Autobongos worker (scripts/bongos/autobongos-run.js
+// workerEnv); AUTOBONGOS_GRADE_LEDGER is set only by that supervisor.
+function unattended(env = process.env) {
+  return env.OTB_SUBAGENT === '1' || Boolean(env.AUTOBONGOS_GRADE_LEDGER);
+}
+
+// shipModeFlag(args) — the --ship-mode answer, or null when absent.
+// { mode } for auto|manual, { bad } for any other value (the ship refuses it).
+function shipModeFlag(args) {
+  const i = args.indexOf('--ship-mode');
+  if (i === -1) return null;
+  const raw = String(args[i + 1] || '').trim().toLowerCase();
+  if (raw === 'auto' || raw === 'manual') return { mode: raw };
+  return { bad: raw || '(missing)' };
+}
+
+// shipModeAskVerdict({ shipMode, flag, unattended }) →
+//   { action: 'proceed', why }   — nothing to ask; ship on
+//   { action: 'save', mode }     — the person answered; save it, then ship on
+//   { action: 'ask' }            — stop and ask
+// shipMode is the GET /project-settings/ship-mode body, or null when unreadable.
+// can_change is absent on a server older than this task; absent means "unknown",
+// and unknown asks (a refused save then lets the ship go on, see saveFailureLines).
+function shipModeAskVerdict({ shipMode, flag, unattended: alone }) {
+  if (!shipMode) return { action: 'proceed', why: 'unreadable' };
+  if (shipMode.chosen) return { action: 'proceed', why: 'chosen' };
+  if (flag && flag.mode) return { action: 'save', mode: flag.mode };
+  if (shipMode.can_change === false) return { action: 'proceed', why: 'cannot_change' };
+  if (alone) return { action: 'proceed', why: 'unattended' };
+  return { action: 'ask' };
+}
+
+// askLines(shipMode, argv) — what the ship prints when it stops to ask. The first
+// lines are for the AI; the choices are the server's own words, so the question a
+// person sees matches the settings page.
+function askLines(shipMode, argv) {
+  const choices = (shipMode && Array.isArray(shipMode.choices) && shipMode.choices.length)
+    ? shipMode.choices
+    : [
+      { mode: 'auto', label: 'Auto (recommended)', sentence: 'When the AI finishes a task it ships and lands it. Nobody has to type a command.' },
+      { mode: 'manual', label: 'Manual', sentence: 'The AI stops before each ship and asks a person to approve it.' },
+    ];
+  const rerun = ['node', 'scripts/bongos/ship.js', ...argv.filter((a, i) => a !== '--ship-mode' && argv[i - 1] !== '--ship-mode')]
+    .map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return [
+    `${ASK_MARKER} This project has never chosen a ship mode, so this first ship asks once.`,
+    'Ask the person this question with two options, Auto first, then re-run this ship with their answer:',
+    '',
+    '  How should finished work ship on this project?',
+    ...choices.map((c) => `    - ${c.label}: ${c.sentence}`),
+    '',
+    `  Re-run:  ${rerun} --ship-mode auto|manual`,
+    '',
+    'Nothing was resolved: the claim is still active. The answer is saved for the',
+    'whole project and can be changed later on the project settings page.',
+  ];
+}
+
+// saveFailureLines(status) — a refused or failed save never blocks the ship. The
+// default (Auto) applies, and the person learns who can set it.
+function saveFailureLines(status) {
+  const who = status === 403
+    ? 'Only the project owner (or someone with project settings access) can set the ship mode,'
+    : `The ship mode could not be saved (${status || 'no response'}),`;
+  return [
+    `${who} so this ship goes on with the default, Auto.`,
+    'It can be set later on the project settings page, or with: node scripts/bongos/shipping-mode.js auto|manual',
+  ];
+}
+
+// runFirstShipAsk({ args, getShipMode, saveShipMode, env, log }) — the side-effect
+// half shipMain calls once it knows this is a real ship. Returns
+// { stop: true, lines } when the ship must stop and ask, else { stop: false }.
+// getShipMode() → body or null; saveShipMode(mode) → { ok, status, data }.
+async function runFirstShipAsk({ args, getShipMode, saveShipMode, env = process.env, log = console.log }) {
+  const flag = shipModeFlag(args);
+  if (flag && flag.bad) {
+    return { stop: true, exit: 2, lines: [`--ship-mode must be auto or manual (got ${flag.bad}). Nothing was resolved: the claim is still active.`] };
+  }
+  let shipMode = null;
+  try { shipMode = await getShipMode(); } catch (_) { shipMode = null; }
+  const verdict = shipModeAskVerdict({ shipMode, flag, unattended: unattended(env) });
+  if (verdict.action === 'ask') return { stop: true, exit: ASK_EXIT, lines: askLines(shipMode, args) };
+  if (verdict.action === 'save') {
+    let r = null;
+    try { r = await saveShipMode(verdict.mode); } catch (_) { r = null; }
+    if (r && r.ok) {
+      log(`Ship mode saved: ${verdict.mode}. ${(r.data && r.data.sentence) || ''}`.trim());
+    } else {
+      for (const line of saveFailureLines(r && r.status)) log(line);
+    }
+  }
+  return { stop: false };
+}
+
+module.exports = {
+  ASK_EXIT,
+  ASK_MARKER,
+  unattended,
+  shipModeFlag,
+  shipModeAskVerdict,
+  askLines,
+  saveFailureLines,
+  runFirstShipAsk,
+};