@bongos/core 1.19.650 → 1.19.651

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.650",
-  "core_contract": "1.19.650",
-  "source_commit": "5616186b29fea16f71cec70846cda88fe124c8c7",
+  "core_version": "1.19.651",
+  "core_contract": "1.19.651",
+  "source_commit": "c13a88d638588dedd2454579a62cb76e4415656a",
   "source_ref": "HEAD",
-  "built_at": "2026-09-10T20:01:10.390Z",
+  "built_at": "2026-09-10T20:32:32.558Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 471,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2604,
-  "tree_sha256": "39e08e82e8577f3b084821c1496216c5420ba3297223ffd477c047ea6f1a8e39",
+  "tree_sha256": "3e626f458ea19a08ab773ec27d6efe07ab6901a906091aa433ac27aa7789173e",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -2777,7 +2777,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "6d296bf6c8df69fc9ec84f3a6548039ef304b369a93d7ac2c4c80bc2ba86842f"
+      "sha256": "b19f014bb424a4974164c08f892cb0103af216bebd411615b1d997f01d6054a7"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7732,12 +7732,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8ac99c68b8d148e7e3a53cbcb94d2e2bd10f6d95e87bd173b2fc6b9497e7fe8e"
+      "sha256": "e70fe3cda6fcf43f7416f03c0232be6be8ff84fca2aaac504dac9268b33d8f69"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "8dc1331a5f582689d16c699861f729674dfcb8d02485a285ff71c46428a6d010"
+      "sha256": "17a361e96b81d29aaddc6b2f73d2d3cdf007914df8e14d6f3fcd0ea7c12378c8"
     },
     {
       "path": "public-docs/index.html",
@@ -8902,7 +8902,7 @@
     {
       "path": "scripts/gds/ship-land.js",
       "mode": "0000644",
-      "sha256": "72efd4268060fb5ddf8a176d91baf01353dc1e82594d70feef029c45f748d8f9"
+      "sha256": "d8cd184816230b7b246ec7afaa2ea285b7ba0e24bb8f47f79d2bc7fa5b423429"
     },
     {
       "path": "scripts/gds/ship-memory-sync.js",
@@ -8912,7 +8912,7 @@
     {
       "path": "scripts/gds/ship-merge.js",
       "mode": "0000644",
-      "sha256": "7c5751c146bcddc9cbf88c6177925e049413d0d275ddb174d5d92b38e75ecab8"
+      "sha256": "b602b4cf8f0e66610991237e1cb7ade9cd5c14659b155ce3512268d40ae670eb"
     },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
@@ -8952,7 +8952,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "a612a450145476ea8d6705d7a45b8a84e2dc861ad8cb5be8c6aa69252b5c54c5"
+      "sha256": "6fd0329b8ad7d45fbb93deda02142c2b766c9e01b669d2d94eeafcb1caa225b0"
     },
     {
       "path": "scripts/gds/skill-lint.js",
@@ -9492,7 +9492,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1d0148cf06b94938cb6f7e6a9e6666ab5393092309530ce5efa6afbd363323b5"
+      "sha256": "de52ed5ea35350aff9ade88ecc06393252ef5294ea7b76aca8222f956367472a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12552,7 +12552,7 @@
     {
       "path": "tests/ship_ci_deploy.mjs",
       "mode": "0000644",
-      "sha256": "e236bc3d6882bc6ddf5d389371a92a96aec62769f14c37bbca31810bcbea0d61"
+      "sha256": "83f8bfb0979b8950a8895eae7710981c19e30878b89fe648eb2dc2e8098c9de1"
     },
     {
       "path": "tests/ship_error_shape.mjs",

package/docs/module-api-changelog.md

@@ -1749,5 +1749,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.648 with no explicit bump. run 34523111338. (task 1002620)
   1.19.650 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.649 with no explicit bump. run 34523753119. (task 1002620)
+  1.19.651 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.650 with no explicit bump. run 34526936330. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.650",
+  "version": "1.19.651",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.650",
+      "version": "1.19.651",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.650",
+  "version": "1.19.651",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/ship-land.js

@@ -35,9 +35,37 @@ const { normalizeApiError } = require('./ship-io.js');
 // 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) { return { ok: false, pending: false, reason, nextStep }; }
+function landBailed(reason, nextStep = null, bailId = null) { return { ok: false, pending: false, reason, nextStep, bailId }; }
+
+// ---------- 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.
@@ -639,6 +667,11 @@ module.exports = {
   ciLand,
   classifyLandOutcome,
   formatPublishFailure,
+  // 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,
   landPending,
   landPendingLines,

package/scripts/gds/ship-merge.js

@@ -1,10 +1,14 @@
 // scripts/gds/ship-merge.js — autoMerge — the merge/regen/push/land chain that puts the branch on main.
 //
 // 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 2307-2579 unchanged. ship.js remains the facade that
-// re-exports every name and owns the CLI entry point, so the ship contract and
+// 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';
 
@@ -13,7 +17,14 @@ const { cleanupMacFinderDupRefs } = require('../../modules/lifecycle/ship-prefli
 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 { ciLand, landBailed, landed } = require('./ship-land.js');
+const {
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  ciLand,
+  landBailRecoverableByPr,
+  landBailed,
+  landed,
+} = require('./ship-land.js');
 const { runSmoke } = require('./ship-grade.js');
 const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
 const { REPO_ROOT } = require('./ship-state.js');
@@ -23,7 +34,49 @@ function zeroCommitVerdict(commitsAhead, dbOnly) {
   return dbOnly ? 'db-only' : 'refuse';
 }
 
-async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
+// 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/gds/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);
+}
+
+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
@@ -40,8 +93,15 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
     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.
-    return landBailed(`nothing to merge — this checkout is on ${branch}, not a task branch`, '/merge-mode');
+    // 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
@@ -153,14 +213,17 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
     // 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; task stays at confirmed`);
+      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.
-      // Name the cure, not just the symptom — this is the bail that used to be
-      // invisible behind "landing automatically".
+      // 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.
       return landBailed(
         `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`,
         '/merge-mode',
+        LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
       );
     }
 
@@ -293,5 +356,8 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
 
 module.exports = {
   autoMerge,
+  // 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/gds/ship.js

@@ -105,6 +105,9 @@ const {
 const {
   classifyLandOutcome,
   formatPublishFailure,
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
   landBailed,
   landPending,
   landPendingLines,
@@ -140,7 +143,7 @@ const {
   isLinkifiableDocPath,
   parseDeletedUpstreamPaths,
 } = require('./ship-preflight-steps.js');
-const { zeroCommitVerdict } = require('./ship-merge.js');
+const { onMainNextStep, zeroCommitVerdict } = require('./ship-merge.js');
 const {
   buildGradePayload,
   buildPriorRoundContext,
@@ -303,6 +306,15 @@ module.exports = {
   // ship unless --db-only is explicitly passed. Exported pure so the gate is
   // unit-tested (has-commits / db-only / refuse) without git.
   zeroCommitVerdict,
+  // task 1002572 (PART 2): the single-checkout land fallback, pure halves only.
+  // landBailRecoverableByPr is the whole decision — which auto-merge bail a PR can
+  // still land (the main checkout holding the branch) versus which are REAL
+  // failures a PR would only carry to main. onMainNextStep is the recovery command
+  // for the other half of the catch-22, where no head branch exists to PR from.
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
+  onMainNextStep,
   // touches[] cleanup [3/8] (task 878): folder-tag derivation, now over the
   // committed diff — exported pure so the regression test can assert it.
   deriveTagsFromPaths,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.650'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.651'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/ship_ci_deploy.mjs

@@ -44,7 +44,7 @@ function test(name, fn) {
   }
 }
 
-const { parseDeployMode, effectiveDeployMode, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded, shouldBailOnFetchFailure, classifyLandOutcome, strandNextStep, pickStaleGateReviewRun, landPollAfterAutoMerge, reconciledCardStatus, landed, landPending, landBailed, strandCommand, landPendingLines } = ship;
+const { parseDeployMode, effectiveDeployMode, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded, shouldBailOnFetchFailure, classifyLandOutcome, strandNextStep, pickStaleGateReviewRun, landPollAfterAutoMerge, reconciledCardStatus, landed, landPending, landBailed, strandCommand, landPendingLines, landBailRecoverableByPr, onMainNextStep, LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH, LAND_BAIL_NO_TASK_BRANCH } = ship;
 
 // ---- 1. parseDeployMode precedence + safe default ----
 
@@ -628,6 +628,111 @@ test('1002645 reconcileBlockedLines: never reads as success (no "NOT a failure",
   assert.ok(!/Prod is live/.test(lines), 'nor the success line');
 });
 
+// ---- task 1002572 (PART 2): the single-checkout land fallback ----
+// A builder with ONE checkout can never complete a local merge — the tree that
+// would RECEIVE the merge is the tree holding the feature branch. That used to
+// park the task at 'confirmed', unpaid under ADR 0120, with nothing landing. The
+// branch itself is landable, so that bail now falls back to the push+PR path.
+// What must NOT happen is a blanket conversion: a merge conflict, a red
+// post-merge smoke or a failed push are real failures, and a PR would carry the
+// same breakage to main. The decision is therefore opt-in PER BAIL, and these
+// tests pin both halves of it.
+
+test('1002572 landBailed: carries the bail id, and defaults to none', () => {
+  assert.equal(landBailed('r', 'n', LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH).bailId, LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH);
+  // Fail-safe: every pre-existing bail site passes no id, so it stays terminal.
+  assert.equal(landBailed('r', 'n').bailId, null);
+  // Still a bail — the fallback must not have turned it into a success.
+  assert.equal(landBailed('r', 'n', LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH).ok, false);
+  assert.equal(landBailed('r', 'n', LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH).pending, false);
+});
+
+test('1002572 landBailRecoverableByPr: only the main-checkout-holds-the-branch bail falls back', () => {
+  assert.equal(landBailRecoverableByPr(LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH), true);
+  // On main there is no head branch, so a PR has nothing to open FROM.
+  assert.equal(landBailRecoverableByPr(LAND_BAIL_NO_TASK_BRANCH), false);
+});
+
+test('1002572 landBailRecoverableByPr: an untagged bail is terminal (no blanket conversion)', () => {
+  // The real failures — conflict, red smoke, failed push, unreachable origin —
+  // all reach the caller as untagged bails. Each must stay loud.
+  for (const v of [null, undefined, '', 'merge-conflict', 'post-merge-smoke-failed', 'push-failed', 'fetch-failed']) {
+    assert.equal(landBailRecoverableByPr(v), false, `${JSON.stringify(v)} must not be PR-recoverable`);
+  }
+});
+
+test('1002572 onMainNextStep: names the task branch to re-ship from when it exists', () => {
+  const step = onMainNextStep(1002572, true);
+  assert.match(step, /task-1002572/, 'names the branch to go back to');
+  assert.match(step, /node scripts\/gds\/ship\.js 1002572/, 'and the re-ship command for THIS task');
+  // The old advice pointed back at the same dead end; that is the regression.
+  assert.notEqual(step, '/merge-mode');
+});
+
+test('1002572 onMainNextStep: falls back to /merge-mode rather than inventing a branch', () => {
+  assert.equal(onMainNextStep(1002572, false), '/merge-mode');
+});
+
+// The ROUTING — the actual deliverable. Driven through autoMerge with the merge
+// chain and the PR land stubbed (a real mergeLocally needs a second checkout and
+// an authed gh), so this proves behaviour rather than matching the source.
+const shipMerge = require('../scripts/gds/ship-merge.js');
+
+function driveAutoMerge(mergeOutcome) {
+  const calls = [];
+  const deps = {
+    mergeLocally: async () => mergeOutcome,
+    ciLand: async (taskId, branch, summary) => {
+      calls.push({ taskId, branch, summary });
+      return landPending();
+    },
+    currentBranch: () => 'task-1002572',
+  };
+  return shipMerge.autoMerge(1002572, 'a summary', {}, deps).then((outcome) => ({ outcome, calls }));
+}
+
+await (async () => {
+  const recoverable = await driveAutoMerge(landBailed('main checkout is on a branch', '/merge-mode', LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH));
+  test('1002572 routing: the single-checkout bail lands via the PR path instead of stranding', () => {
+    assert.equal(recoverable.calls.length, 1, 'ciLand was called exactly once');
+    assert.deepEqual(recoverable.calls[0], { taskId: 1002572, branch: 'task-1002572', summary: 'a summary' });
+    // Pending, not bailed: the card may honestly say "landing automatically" now.
+    assert.equal(recoverable.outcome.pending, true);
+    assert.equal(recoverable.outcome.reason, null);
+  });
+
+  const terminal = await driveAutoMerge(landBailed('merging task-1002572 into main failed (conflicts?)', '/merge-mode'));
+  test('1002572 routing: a real failure stays loud — no PR is opened for a conflict', () => {
+    assert.equal(terminal.calls.length, 0, 'a conflict must NOT be converted into a PR');
+    assert.equal(terminal.outcome.pending, false);
+    assert.match(terminal.outcome.reason, /conflicts/);
+  });
+
+  const onMain = await driveAutoMerge(landBailed('nothing to merge — this checkout is on main, not a task branch', onMainNextStep(1002572, true), LAND_BAIL_NO_TASK_BRANCH));
+  test('1002572 routing: standing on main opens no PR (there is no head branch), but names the cure', () => {
+    assert.equal(onMain.calls.length, 0);
+    assert.match(onMain.outcome.nextStep, /task-1002572/);
+  });
+
+  const success = await driveAutoMerge(landed());
+  test('1002572 routing: a successful local merge is untouched (the worktree path does not regress)', () => {
+    assert.equal(success.calls.length, 0, 'a clean local merge must not also open a PR');
+    assert.equal(success.outcome.ok, true);
+  });
+})();
+
+// Only the two documented catch-22 bails may carry an id. Behaviour can't see
+// this — a third tagged bail would silently gain a fallback it was never granted.
+test('1002572 wiring: exactly the two catch-22 bails are tagged', () => {
+  const src = fs.readFileSync(path.join(__dirname, '..', 'scripts', 'gds', 'ship-merge.js'), 'utf8');
+  // Each id appears exactly twice: the require destructure, and its ONE bail site.
+  for (const id of [LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH, LAND_BAIL_NO_TASK_BRANCH]) {
+    const name = `LAND_BAIL_${id.toUpperCase().replace(/-/g, '_')}`;
+    const hits = src.split(name).length - 1;
+    assert.equal(hits, 2, `${name}: imported once + used at exactly one bail site (saw ${hits})`);
+  }
+});
+
 console.log('');
 console.log(`ship_ci_deploy: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);