@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/tools/colab CHANGED
@@ -70,6 +70,8 @@ const shipBatch = require('./lib/ship-batch');
70
70
  const batchStats = require('./lib/batch-stats');
71
71
  const conflictMarkers = require('./lib/conflict-markers');
72
72
  const docsOnly = require('./lib/docs-only');
73
+ const integrationProfile = require('./lib/integration-profile');
74
+ const secretScan = require('./lib/secret-scan'); // #606
73
75
  const configSet = require('./lib/config-set'); // #561
74
76
  const cureDiff = require('./lib/cure-diff');
75
77
  const codeowners = require('./lib/codeowners');
@@ -1709,8 +1711,17 @@ function cmdReleaseCut(argv) {
1709
1711
  }
1710
1712
  }
1711
1713
 
1714
+ // #610: on a final route the heavy lane must be green at this sha. Under --auto (the release
1715
+ // workflow) a missing run is started here, once, and the run no-ops until it is green.
1716
+ let heavy = null;
1717
+ if (fast || library) {
1718
+ const lane = heavyLaneAt(repoAbs, doc, sha);
1719
+ heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
1720
+ if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1721
+ }
1722
+
1712
1723
  const verdict = releaseCut.decide({
1713
- policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
1724
+ policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
1714
1725
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1715
1726
  finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1716
1727
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
@@ -1995,6 +2006,16 @@ function readRegressionEdges(repoAbs, num) {
1995
2006
  }
1996
2007
  }
1997
2008
 
2009
+ /**
2010
+ * #610: the heavy lane at a release candidate, as release-finalize.js decide()'s `heavy` fact. Read
2011
+ * the same way ship's gated landing reads it (heavyLaneAt). Inside the release workflow the heavy
2012
+ * lane is a separate workflow, never the one running, so #425's own-workflow filter does not apply.
2013
+ */
2014
+ function releaseHeavyFact(repoAbs, doc, cand) {
2015
+ const lane = heavyLaneAt(repoAbs, doc, cand.sha);
2016
+ return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
2017
+ }
2018
+
1998
2019
  function cmdReleaseFinalize(argv) {
1999
2020
  const opts = parseArgs(argv, {
2000
2021
  values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
@@ -2137,6 +2158,7 @@ function cmdReleaseFinalize(argv) {
2137
2158
  const verdict = releaseFinalize.decide({
2138
2159
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2139
2160
  ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2161
+ heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
2140
2162
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2141
2163
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2142
2164
  });
@@ -9980,7 +10002,9 @@ What this command will NOT do, by design:
9980
10002
  • It skips the handbook repo itself.
9981
10003
 
9982
10004
  Exit code: 0 when nothing is behind, 1 when anything is behind — the frozen copy included,
9983
- since a stale CLI is as much a thing to act on as a stale workflow. 2 on usage error.
10005
+ since a stale CLI is as much a thing to act on as a stale workflow — except a CI template
10006
+ (\`ci-*\`) copy: CI templates are guidance, so one behind is reported but never exits 1 (#607).
10007
+ 2 on usage error.
9984
10008
  `;
9985
10009
 
9986
10010
  function cmdUpdate(argv) {
@@ -10055,7 +10079,11 @@ function cmdUpdate(argv) {
10055
10079
  skippedRepos: repos.filter((r) => !r.artifacts.length).length,
10056
10080
  refreshable: all.filter((a) => a.state === 'behind' && a.applicable && !a.written).length,
10057
10081
  written: written.length,
10082
+ // #607: a CI template is guidance — a `ci-*` copy behind its template is a suggestion, counted in
10083
+ // `behind` (it can still be refreshed) but never what makes this command exit 1.
10084
+ suggestions: all.filter((a) => a.state === 'behind' && /^ci-/.test(a.template || '')).length,
10058
10085
  };
10086
+ const actionable = summary.behind - summary.suggestions;
10059
10087
 
10060
10088
  if (opts.json) {
10061
10089
  print(JSON.stringify({
@@ -10065,7 +10093,7 @@ function cmdUpdate(argv) {
10065
10093
  applied: !!opts.apply,
10066
10094
  repos, written, failed, frozen, summary,
10067
10095
  }, null, 2));
10068
- return summary.behind > 0 || frozen.state === 'behind' ? 1 : 0;
10096
+ return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
10069
10097
  }
10070
10098
 
10071
10099
  // --- report ------------------------------------------------------------
@@ -10108,6 +10136,9 @@ function cmdUpdate(argv) {
10108
10136
  `${summary.current} current, ${summary.behind} behind, ${summary.diverged} diverged, ` +
10109
10137
  `${summary.unstamped} unstamped, ${summary.na} n-a` +
10110
10138
  (summary.unrelated ? `, ${summary.unrelated} unrelated (name clash only — not ours).` : '.'));
10139
+ if (summary.suggestions) {
10140
+ print(`${summary.suggestions} of the behind copies are CI templates — guidance, adopt what helps; they never fail this command (#607).`);
10141
+ }
10111
10142
  if (summary.skippedRepos) {
10112
10143
  print(`${summary.skippedRepos} repo(s) had nothing to assess (nothing adopted, an audit-only slug, a missing path, or the handbook itself).`);
10113
10144
  }
@@ -10142,7 +10173,7 @@ function cmdUpdate(argv) {
10142
10173
  print(' --apply never touches it: it is the toolchain your always-on services are running.');
10143
10174
  }
10144
10175
 
10145
- return summary.behind > 0 || frozen.state === 'behind' ? 1 : 0;
10176
+ return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
10146
10177
  }
10147
10178
 
10148
10179
  // ---------------------------------------------------------------------------
@@ -10492,7 +10523,12 @@ function migDetail(migrations, grants, target, branch, ctx) {
10492
10523
  * from its base. An empty result is now left empty; the caller decides what to say about it
10493
10524
  * (buildSquashMessage below), rather than this layer inventing a commit to hide it.
10494
10525
  */
10495
- function branchCommits(mainRoot, trunk, branch) {
10526
+ function branchCommits(mainRoot, trunk, branchName) {
10527
+ // #603: read the branch through the ref it resolves to. A hand-off branch (or any --branch with no
10528
+ // local ref) is remote-only on the lander, and a bare name does not DWIM to refs/remotes/<remote>/
10529
+ // — the log failed, the list came back empty, and the squash subject read "(none …)" on a branch
10530
+ // that has commits. shipRefFor is local || remote || the name itself, so a sha passes unchanged.
10531
+ const branch = shipRefFor(mainRoot, branchName);
10496
10532
  const mb = git.git(['merge-base', trunk, branch], mainRoot);
10497
10533
  const base = mb.ok && mb.stdout ? mb.stdout : trunk;
10498
10534
  const logShas = git.git(['log', '--first-parent', `${base}..${branch}`, '--no-merges', '--format=%H'], mainRoot);
@@ -10516,7 +10552,7 @@ function commitFiles(mainRoot, sha) {
10516
10552
 
10517
10553
  /** Files the whole branch changed against its base — the denominator for the same signal. */
10518
10554
  function branchChangedFiles(mainRoot, base, branch) {
10519
- const r = git.git(['diff', '--name-only', `${base}...${branch}`], mainRoot);
10555
+ const r = git.git(['diff', '--name-only', `${base}...${shipRefFor(mainRoot, branch)}`], mainRoot); // #603: same remote-only gap
10520
10556
  return r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : [];
10521
10557
  }
10522
10558
 
@@ -10590,7 +10626,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10590
10626
  }
10591
10627
 
10592
10628
  const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
10593
- colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10629
+ colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
10594
10630
 
10595
10631
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10596
10632
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10635,6 +10671,10 @@ Sequence (each step gated; any failure aborts before the push — the target is
10635
10671
  and worktree untouched. Re-run the same command once an account other than the
10636
10672
  author approved the branch's CURRENT head: it lands by the ordinary squash below
10637
10673
  and closes the PR. Accounts sharing one login cannot approve each other.
10674
+ b5. heavy lane (#610) only with integration-profile: gated, never for a docs-only change:
10675
+ the heavy workflow (heavy-workflow:, default ci-heavy.yml) green at the
10676
+ branch's remote head. None yet → a real ship dispatches it and PAUSES —
10677
+ "⏸ HEAVY-PENDING", exit 3, nothing merged; running → the same pause; red → ✗.
10638
10678
  c. B0 sync merge the target INTO the branch; non-generated conflict → abort (human merge);
10639
10679
  generated-only conflict → repo's .colab/hooks/pre-ship regenerates, else abort
10640
10680
  d. B1 squash re-check CI green, then squash-merge branch → target (Closes every claimed issue,
@@ -10879,7 +10919,20 @@ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref
10879
10919
  combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
10880
10920
  \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
10881
10921
  'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
10882
- A red batch, or one with no run / not landed past that grace, holds nothing.
10922
+ A red batch, or one with no run / not landed past that grace, holds nothing. A TRUNK RED: cure is never held.
10923
+ SPECULATIVE CHAIN (#605): --onto ship-batch/<sha7> builds the batch on that in-flight batch's HEAD
10924
+ instead of trunk's tip, named ship-batch/<parent-head-sha7> (one batch per base still holds). The chain
10925
+ is read from ls-remote alone: a ref's parent is the ref whose head its name starts with, and it is kept
10926
+ while that chain ends at a batch on trunk's tip (at most ${shipBatch.MAX_CHAIN_DEPTH} deep); a ref whose parent is gone or rebuilt,
10927
+ or whose root trunk moved past, is deleted by the next --batch call (its run cancelled if still going).
10928
+ - refused (1): the named ref has no combined run in flight or green, is not rooted at trunk's tip,
10929
+ or is already ${shipBatch.MAX_CHAIN_DEPTH} deep; a member the chain below already carries does not join (✗, the rest go on);
10930
+ - lands in order: green and its parent not landed yet → ⏸ BATCH-CHAINED (exit 3); once trunk's tip IS
10931
+ the parent's head, the same command (with or without --onto) lands it — no second build, no second run;
10932
+ - declined (4): the parent is red, gone, or trunk moved some other way — the child is deleted, → SERIAL.
10933
+ Every ref of a chain rooted at trunk's tip holds the lane, exactly as one batch does.
10934
+ --dry --json: one JSON document on stdout ({ batch: { ref, parentRef, rootSha, base, depth, step, exit,
10935
+ members: [{ branch, sha, eligible, inBatch, why }] } }), the prose on stderr.
10883
10936
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
10884
10937
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
10885
10938
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
@@ -11452,6 +11505,13 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
11452
11505
  via = `${trunk} (by commit — the branch-filtered read was empty)`;
11453
11506
  }
11454
11507
  }
11508
+ // #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
11509
+ // docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
11510
+ // newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
11511
+ if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
11512
+ const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
11513
+ if (door) return door;
11514
+ }
11455
11515
  const at = `${via}@${shortSha(run.sha)}`;
11456
11516
  let verdict = classifyCiRun(repoAbs, run, at);
11457
11517
  // #413: still no run anywhere at a trunk sha committed minutes ago — the run may not exist YET
@@ -11630,6 +11690,75 @@ function baseCiAdvisory(repoAbs, gh, base, branch) {
11630
11690
  };
11631
11691
  }
11632
11692
 
11693
+ /**
11694
+ * #606: trunk's tip is docs-only and has no finished run — read trunk CI at the newest first-parent
11695
+ * ancestor that is NOT docs-only (tools/lib/docs-only.js commitChanges, narrowed by trunk's
11696
+ * `ci-docs-skip`). Returns a readCiVerdict result, or null when the door does not apply: the repo
11697
+ * declared `ci-docs-skip: off` (or an invalid value), the tip is not local or not docs-only, no code
11698
+ * commit within DOCS_TIP_WALK commits, or that commit's runs are unreadable. A null keeps every
11699
+ * existing reading of the tip unchanged — the door only ever answers for a docs-only tip.
11700
+ */
11701
+ const DOCS_TIP_WALK = 50;
11702
+ function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
11703
+ if (!tipSha) return null;
11704
+ const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
11705
+ if (!setting.on) return null;
11706
+ const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
11707
+ if (!list.ok) return null;
11708
+ let skipped = 0;
11709
+ let code = null;
11710
+ for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
11711
+ const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
11712
+ if (!c.docsOnly) { code = sha; break; }
11713
+ skipped++;
11714
+ }
11715
+ if (!code || skipped === 0) return null;
11716
+ const run = git.ghRunForCommitAnyRef(repoAbs, code, undefined, readOpts);
11717
+ if (!run) return null;
11718
+ const at = `${trunk}@${shortSha(code)}`;
11719
+ const v = classifyCiRun(repoAbs, run, at);
11720
+ const note = `docs-only tip (#606): ${trunk}@${shortSha(tipSha)}${skipped > 1 ? ` and ${skipped - 1} commit(s) below it` : ''} change only documentation, so trunk CI is read at the newest code commit — `;
11721
+ const verdict = { ...v, detail: note + v.detail, docsOnlyTip: { tip: tipSha, read: code, skipped } };
11722
+ return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
11723
+ }
11724
+
11725
+ /**
11726
+ * #606: is this branch DOCS-ONLY for CI purposes — so `colab ship` lands it without waiting for CI?
11727
+ * tools/lib/docs-only.js shipDocsOnly (the #345 rule, narrowed by `ci-docs-skip`, off by `off`),
11728
+ * measured on the ref ship would land. When it applies, the secret check runs too
11729
+ * (tools/lib/secret-scan.js) — the suite's own secret scan may never see this change.
11730
+ * Returns `{ applies, files, reason, scan }`; `scan` only when `applies`.
11731
+ */
11732
+ function shipDocsOnlyCi(repoAbs, doc, target, branch) {
11733
+ const ref = shipRefFor(repoAbs, branch);
11734
+ const d = docsOnly.shipDocsOnly(git, repoAbs, target, ref, doc);
11735
+ if (!d.docsOnly) return { applies: false, files: d.files, reason: d.reason, scan: null };
11736
+ return { applies: true, files: d.files, reason: d.reason, scan: secretScan.scanBranch(git, repoAbs, target, ref) };
11737
+ }
11738
+
11739
+ /** #606: the 🚢 comment's evidence clause for a docs-only ship — files, and the trunk sha CI was read at. */
11740
+ function docsOnlyEvidence(dc, ci) {
11741
+ if (!dc || !dc.applies) return '';
11742
+ const tip = ci && ci.docsOnlyTip;
11743
+ const read = tip ? ` — trunk CI read at ${shortSha(tip.read)}, the newest code commit below the docs-only tip ${shortSha(tip.tip)}` : ' — trunk CI read at its tip';
11744
+ return ` — docs-only: CI not required (${dc.files} files)${read}; secret check clean`;
11745
+ }
11746
+
11747
+ /**
11748
+ * #606: the branch-run row for a docs-only branch, in place of #395's stale-base row. CI is not
11749
+ * required, so no run, a run in flight, or a run measured on an older base is fine — but a run that
11750
+ * EXISTS at the pushed head and finished red still refuses: ship never overrides a red verdict.
11751
+ */
11752
+ function docsOnlyBranchRow(dc, stale) {
11753
+ const run = stale && stale.run;
11754
+ const red = !!run && run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
11755
+ if (red) {
11756
+ return { ok: false, class: HUMAN_GATED,
11757
+ detail: `docs-only (${dc.files} files), but the branch's own run at ${shortSha(stale.headSha)} finished ${run.conclusion || 'red'} — CI is not required here, and a red verdict is still never overridden (#606)` };
11758
+ }
11759
+ return { ok: true, class: null, detail: `docs-only: CI not required (${dc.files} files) — the branch's own run is not awaited (#606; ${stale ? stale.verdict : 'unread'})` };
11760
+ }
11761
+
11633
11762
  /**
11634
11763
  * #395: does the branch's CI verdict cover the CURRENT `base`? A PRECONDITION, unlike
11635
11764
  * `baseCiAdvisory` above: serial ship syncs the base in locally (B0) and squashes without the synced
@@ -11658,7 +11787,8 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
11658
11787
  if (contains === false && git.git(['diff', '--quiet', `${baseTip}...${headSha}`], repoAbs).code === 0) contains = 'no-change';
11659
11788
  }
11660
11789
  if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
11661
- return staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh });
11790
+ // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
11791
+ return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh }), run, headSha };
11662
11792
  }
11663
11793
 
11664
11794
  /**
@@ -12463,13 +12593,28 @@ function cmdShipDryJson(opts) {
12463
12593
  // read is exempt: the batch grades the COMBINED head (trunk + every member), which is exactly the
12464
12594
  // re-run this row demands of a serial land, so a member behind trunk is the ordinary case there.
12465
12595
  const staleJson = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
12466
- if (opts._batchMember) {
12596
+ // #606: a docs-only branch needs no CI of its own — its row replaces the stale-base one, and the
12597
+ // secret check stands in for the suite's secret scan. Same producers as the prose path.
12598
+ const docsCiJson = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
12599
+ if (docsCiJson.applies) {
12600
+ const row = docsOnlyBranchRow(docsCiJson, staleJson);
12601
+ checks.push({ name: 'branch CI (docs-only, #606)', ok: row.ok, class: row.class, verdict: staleJson.verdict, detail: row.detail });
12602
+ checks.push({ name: 'docs-only secret check (#606)', ok: docsCiJson.scan.ok, class: docsCiJson.scan.ok ? null : HUMAN_GATED, detail: docsCiJson.scan.reason });
12603
+ } else if (opts._batchMember) {
12467
12604
  checks.push({ name: 'branch run contains current base (#395)', ok: true, class: null, verdict: staleJson.verdict,
12468
12605
  detail: `batch member — the combined run grades it (${staleJson.detail})` });
12469
12606
  } else {
12470
12607
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
12471
12608
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
12472
12609
  }
12610
+ // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
12611
+ // its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
12612
+ const heavyJson = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCiJson.applies, batchMember: !!opts._batchMember });
12613
+ if (heavyJson) {
12614
+ checks.push({ name: 'heavy lane green (integration-profile: gated, #610)', ok: heavyJson.ok,
12615
+ class: heavyJson.ok ? null : (heavyJson.action === 'refuse' ? HUMAN_GATED : SELF_CLEARING),
12616
+ action: heavyJson.action, detail: heavyJson.detail });
12617
+ }
12473
12618
 
12474
12619
  // #350: same single producer as the prose path. 'pending' is not a failure — it is `mode`.
12475
12620
  const coreReviewJson = shipCoreReview(repoAbs, gh, target, sess.branch);
@@ -12555,7 +12700,7 @@ function cmdShipDryJson(opts) {
12555
12700
  // lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
12556
12701
  // Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
12557
12702
  if (!dryMode.evidenceClose && !opts._batchMember) {
12558
- const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
12703
+ const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResultJson);
12559
12704
  if (laneJson) {
12560
12705
  checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
12561
12706
  detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
@@ -13430,7 +13575,7 @@ function shipRefFor(repoAbs, branch) {
13430
13575
 
13431
13576
  function cmdShip(argv) {
13432
13577
  const opts = parseArgs(argv, {
13433
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
13578
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff', '--onto': 'onto' },
13434
13579
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
13435
13580
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
13436
13581
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -13450,6 +13595,9 @@ function cmdShip(argv) {
13450
13595
  if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-url> (#591, see `colab ship --help`)');
13451
13596
  if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
13452
13597
  if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
13598
+ if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
13599
+ if (opts.onto && !shipBatch.parseBatchRef(opts.onto)) throw new UserError(`--onto ${opts.onto}: not a batch ref — expected ship-batch/<sha7> (#605)`);
13600
+ if (opts.batch && opts.json) return cmdShipBatchJson(opts); // #605: the batch's facts as JSON, prose on stderr
13453
13601
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
13454
13602
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
13455
13603
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -13641,7 +13789,24 @@ function cmdShip(argv) {
13641
13789
  // #395: the branch's run must have been measured on a head that contains the base's CURRENT tip —
13642
13790
  // B0 below syncs locally and never re-runs CI, so this is the only place a stale verdict is caught.
13643
13791
  const staleResult = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
13644
- checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13792
+ // #606: a docs-only branch needs no CI of its own — this row replaces the stale-base one (a red
13793
+ // run that exists still refuses), and the secret check stands in for the suite's secret scan.
13794
+ const docsCi = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
13795
+ let docsRowOk = true;
13796
+ if (docsCi.applies) {
13797
+ const row = docsOnlyBranchRow(docsCi, staleResult);
13798
+ checks.push([row.ok ? '✓' : '✗', 'branch CI (docs-only, #606)', row.detail]);
13799
+ checks.push([docsCi.scan.ok ? '✓' : '✗', 'docs-only secret check (#606)', docsCi.scan.reason]);
13800
+ docsRowOk = row.ok && docsCi.scan.ok;
13801
+ } else {
13802
+ checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13803
+ }
13804
+ // #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
13805
+ // heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
13806
+ // heavy lane at all, fails the table.
13807
+ const heavyGate = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCi.applies });
13808
+ if (heavyGate) checks.push([heavyGate.ok ? '✓' : (heavyGate.action === 'refuse' ? '✗' : '⏸'), 'heavy lane green (integration-profile: gated, #610)', heavyGate.detail]);
13809
+ const heavyOk = !heavyGate || heavyGate.action !== 'refuse';
13645
13810
 
13646
13811
  // #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
13647
13812
  // taken below once every real precondition has passed, so it is the ONLY thing between the branch
@@ -13652,7 +13817,7 @@ function cmdShip(argv) {
13652
13817
 
13653
13818
  // #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
13654
13819
  // hold is not a failed precondition — it is a pause, taken below once every real one has passed.
13655
- const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
13820
+ const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult);
13656
13821
  if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
13657
13822
  for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
13658
13823
 
@@ -13667,7 +13832,7 @@ function cmdShip(argv) {
13667
13832
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
13668
13833
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
13669
13834
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
13670
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && staleResult.ok && coreOk && recOk;
13835
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
13671
13836
 
13672
13837
  // ---- report the table ----
13673
13838
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -13890,6 +14055,8 @@ function cmdShip(argv) {
13890
14055
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
13891
14056
  } else if (lane && lane.held && coreReview.verdict !== 'pending') {
13892
14057
  print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
14058
+ } else if (heavyGate && !heavyGate.ok && coreReview.verdict !== 'pending') {
14059
+ print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${heavyGate.action === 'dispatch' ? `a real ship dispatches ${heavyGate.file} at ${shortSha(heavyGate.sha)}` : 'the heavy lane is not green yet'} (integration-profile: gated, #610); run again once it is green`);
13893
14060
  } else if (coreReview.verdict === 'pending') {
13894
14061
  print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
13895
14062
  'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
@@ -13958,6 +14125,14 @@ function cmdShip(argv) {
13958
14125
  // ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
13959
14126
  if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
13960
14127
 
14128
+ // ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
14129
+ if (heavyGate && !heavyGate.ok) {
14130
+ print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
14131
+ if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
14132
+ else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
14133
+ return 3;
14134
+ }
14135
+
13961
14136
  // ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
13962
14137
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
13963
14138
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
@@ -14032,6 +14207,18 @@ function cmdShip(argv) {
14032
14207
  return 1;
14033
14208
  }
14034
14209
  }
14210
+ // #606: the same for the docs-only CI path — B0 may have made the change something CI must see,
14211
+ // or added a line the secret check has not read. Re-measured on the synced branch.
14212
+ if (docsCi.applies) {
14213
+ const again = docsOnly.shipDocsOnly(git, repoAbs, mergeRef, sess.branch, doc);
14214
+ const rescan = again.docsOnly ? secretScan.scanBranch(git, repoAbs, mergeRef, sess.branch) : null;
14215
+ if (!again.docsOnly || !rescan.ok) {
14216
+ cleanupEphemeral();
14217
+ process.stderr.write(`✗ B1: the docs-only CI path (#606) no longer holds after B0 sync — ${again.docsOnly ? rescan.reason : again.reason}. Nothing pushed.\n`);
14218
+ process.stderr.write(` Push the synced branch and re-run once its CI run completes (\`git push origin ${sess.branch}\`, then \`colab ship\` again) — or remove the finding first if the secret check refused.\n`);
14219
+ return 1;
14220
+ }
14221
+ }
14035
14222
  if (autonomyGate.via === 'tuning') {
14036
14223
  const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
14037
14224
  if (!again.tuning) {
@@ -14105,7 +14292,7 @@ function cmdShip(argv) {
14105
14292
  }
14106
14293
  // #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
14107
14294
  // built in that window is exactly as live as one the table saw.
14108
- const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
14295
+ const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciCureForTrailer ? { cureVerdict: ciCureForTrailer } : null) : null;
14109
14296
  if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
14110
14297
  // WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
14111
14298
  // (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
@@ -14468,7 +14655,7 @@ function cmdShip(argv) {
14468
14655
  // same block, and re-assigning the collector here would silently discard them.
14469
14656
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
14470
14657
  skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14471
- evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
14658
+ evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
14472
14659
 
14473
14660
  print('');
14474
14661
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -14679,21 +14866,29 @@ function shipDryJsonReport(opts) {
14679
14866
  * Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
14680
14867
  * trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
14681
14868
  */
14682
- function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14869
+ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
14683
14870
  if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
14871
+ // #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
14872
+ // way out; no batch can land on a red trunk anyway.
14873
+ if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
14874
+ return { held: false, released: [], detail: 'a TRUNK RED: cure is never held by a batch (#605)' };
14875
+ }
14684
14876
  const remote = git.remoteFor(repoAbs);
14685
14877
  const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
14686
14878
  if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
14687
14879
  const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
14688
14880
  const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
14689
- const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
14690
- .filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
14881
+ // #605: the lane holder is the CHAIN rooted at trunk's tip — a batch built --onto another batch's head
14882
+ // reaches trunk only through it, so its run holds the lane exactly as the root's does.
14883
+ const refs = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) })).filter((x) => x.parsed);
14884
+ const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
14885
+ const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
14691
14886
  const batches = atTip.map((x) => {
14692
14887
  const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
14693
14888
  let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
14694
14889
  if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
14695
14890
  const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
14696
- return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
14891
+ return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
14697
14892
  builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
14698
14893
  });
14699
14894
  const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
@@ -14704,14 +14899,90 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14704
14899
  }
14705
14900
 
14706
14901
  /** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
14902
+ /**
14903
+ * #610: the heavy lane at one sha — which workflow it is, whether the tree there has it, and its
14904
+ * verdict. The heavy workflow is named by FILE (`heavy-workflow:`, default ci-heavy.yml); its run
14905
+ * rows carry the workflow's `name:`, so the file at that sha is read to learn which rows are heavy.
14906
+ * `rows: null` (gh unreadable) stays `unread` — never "no heavy run", which would dispatch.
14907
+ */
14908
+ function heavyLaneAt(repoAbs, doc, sha) {
14909
+ const file = integrationProfile.parseHeavyWorkflow(doc).file;
14910
+ const rel = `.github/workflows/${file}`;
14911
+ let present = false, name = rel;
14912
+ if (sha) {
14913
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
14914
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
14915
+ if (show.ok) {
14916
+ present = true;
14917
+ const t = verifyRuns.workflowTriggers(show.stdout);
14918
+ if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
14919
+ }
14920
+ }
14921
+ const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
14922
+ const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
14923
+ return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
14924
+ }
14925
+
14926
+ /**
14927
+ * #610: `integration-profile: gated` — a serial landing waits on a green heavy run at the branch's
14928
+ * remote head. Null under every other profile (ship reads the light lane, as before), for a docs-only
14929
+ * change (no CI wait at all, #606), and for a batch member read (the batch head is graded instead).
14930
+ */
14931
+ function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMember = false } = {}) {
14932
+ const profile = integrationProfile.parseProfile(doc).profile;
14933
+ if (profile !== 'gated' || docsOnlyApplies || batchMember) return null;
14934
+ const refs = git.branchRefs(repoAbs, branch);
14935
+ const sha = refs.remoteSha || null;
14936
+ const at = sha ? `${branch}@${shortSha(sha)}` : branch;
14937
+ if (!sha) return { ok: false, action: 'wait', detail: `integration-profile: gated — ${branch} is not on the remote yet, so the heavy lane cannot run at its head (push it)`, sha: null, file: null };
14938
+ if (refs.localSha && refs.localSha !== sha && !git.git(['merge-base', '--is-ancestor', refs.localSha, sha], repoAbs).ok) {
14939
+ return { ok: false, action: 'wait', detail: `integration-profile: gated — local ${branch} has commits the remote head ${shortSha(sha)} does not; the heavy lane would test the wrong code (push it)`, sha: null, file: null };
14940
+ }
14941
+ const lane = heavyLaneAt(repoAbs, doc, sha);
14942
+ const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
14943
+ return { ...gate, sha, file: lane.file, name: lane.name };
14944
+ }
14945
+
14946
+ /** #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits. */
14947
+ function dispatchHeavyLane(repoAbs, file, ref, sha) {
14948
+ const d = git.ghWorkflowDispatch(repoAbs, file, ref, { ref: sha });
14949
+ if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
14950
+ else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: gh workflow run ${file} --ref ${ref} -f ref=${sha}`);
14951
+ return d.ok;
14952
+ }
14953
+
14707
14954
  function printBatchLanePause(lane, trunk) {
14708
14955
  print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
14709
14956
  print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
14710
14957
  print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
14711
14958
  }
14712
14959
 
14960
+ /**
14961
+ * #605: `colab ship --batch … --dry --json` — the same single step as the prose path (it IS the prose
14962
+ * path, with its prose moved to stderr), plus one JSON document on stdout carrying the facts a caller
14963
+ * keys on: the batch ref, the ref it is chained onto, the trunk sha its chain is rooted at, the step
14964
+ * taken and the exit class, and one row per member. A caller never parses prose for the chain.
14965
+ */
14966
+ function cmdShipBatchJson(opts) {
14967
+ const batch = { trunk: null, trunkSha: null, ref: null, parentRef: null, rootSha: null, base: null, depth: null, step: null, exit: null, error: null, members: [] };
14968
+ const was = PRINT_TO_STDERR;
14969
+ PRINT_TO_STDERR = true;
14970
+ let code;
14971
+ try { code = cmdShipBatch({ ...opts, _json: batch }); }
14972
+ catch (e) {
14973
+ if (!(e instanceof UserError)) throw e;
14974
+ process.stderr.write(`✗ ${e.message}\n`);
14975
+ batch.error = e.message;
14976
+ batch.step = batch.step || 'refused';
14977
+ code = 1;
14978
+ } finally { PRINT_TO_STDERR = was; }
14979
+ batch.exit = code;
14980
+ process.stdout.write(`${JSON.stringify({ batch }, null, 2)}\n`);
14981
+ return code;
14982
+ }
14983
+
14713
14984
  function cmdShipBatch(opts) {
14714
- for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
14985
+ for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ...(opts._json ? [] : [['json', '--json']])]) {
14715
14986
  if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
14716
14987
  }
14717
14988
  const repoAbs = resolveRepo(opts);
@@ -14725,7 +14996,12 @@ function cmdShipBatch(opts) {
14725
14996
  const members = entries.members;
14726
14997
  const handoffs = entries.handoffs;
14727
14998
  if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
14999
+ const J = opts._json || {}; // #605: the --dry --json report, filled as the facts are read
15000
+ J.trunk = trunk;
14728
15001
  const serial = (why, list = members) => {
15002
+ J.step = J.step && J.step !== 'build' ? J.step : 'serial';
15003
+ J.reason = why;
15004
+ if (!J.members || !J.members.length) J.members = list.map((b) => ({ branch: b, sha: null, eligible: null, inBatch: false, why }));
14729
15005
  print(`✗ ship-batch: ${why}`);
14730
15006
  print(shipBatch.serialLine(list));
14731
15007
  return 4;
@@ -14786,6 +15062,7 @@ function cmdShipBatch(opts) {
14786
15062
  const lsTrunk = git.git(['ls-remote', remote, `refs/heads/${trunk}`], repoAbs);
14787
15063
  const trunkNow = lsTrunk.ok ? (lsTrunk.stdout.split('\t')[0] || '').trim() : '';
14788
15064
  if (!trunkNow) throw new UserError(`could not read ${trunk} on ${remote}`);
15065
+ J.trunkSha = trunkNow;
14789
15066
  const lsBatch = git.git(['ls-remote', remote, 'refs/heads/ship-batch/*'], repoAbs);
14790
15067
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
14791
15068
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
@@ -14797,14 +15074,102 @@ function cmdShipBatch(opts) {
14797
15074
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
14798
15075
  return d.ok;
14799
15076
  };
14800
- for (const b of batchRefs.filter((x) => !trunkNow.startsWith(x.parsed.base7))) {
14801
- print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
15077
+ // #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
15078
+ // ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
15079
+ // whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
15080
+ // is exactly the old sweep: every ref not built on trunk's tip goes.
15081
+ const chains = shipBatch.batchChains({ refs: batchRefs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
15082
+ const carriedBy = (ref, from, sha) => {
15083
+ const lg = git.git(['log', '--format=%B%x00', `${from}..${sha}`], repoAbs);
15084
+ return shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === ref).reverse();
15085
+ };
15086
+ const swept = [];
15087
+ for (const b of batchRefs.filter((x) => !chains.get(x.parsed.ref).rooted)) {
15088
+ const c = chains.get(b.parsed.ref);
15089
+ // A ref built on a head trunk never reached (an orphaned chain link) may still have its run going;
15090
+ // nothing can ever land it, so cancel that run. A ref on an OLD trunk tip is today's case, untouched.
15091
+ const baseFull = git.git(['rev-parse', '--verify', '-q', `${b.parsed.base7}^{commit}`], repoAbs);
15092
+ const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
15093
+ if (offTrunk) {
15094
+ print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
15095
+ for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
15096
+ if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
15097
+ const cx = git.ghRunCancel(repoAbs, r.databaseId);
15098
+ if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
15099
+ }
15100
+ } else {
15101
+ print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
15102
+ }
15103
+ swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
14802
15104
  deleteRef(b.parsed.ref);
14803
15105
  }
14804
- const atBase = batchRefs.find((x) => trunkNow.startsWith(x.parsed.base7)) || null;
15106
+ const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
15107
+ // Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
15108
+ const carriedByChain = (sha) => new Map(shipBatch.parseMemberTrailers((() => {
15109
+ const lg = git.git(['log', '--format=%B%x00', `${trunkNow}..${sha}`], repoAbs);
15110
+ return lg.ok ? lg.stdout.split('\0') : [];
15111
+ })()).map((m) => [m.branch, m.ref]));
15112
+
15113
+ // #605: --onto <ship-batch ref> builds on that ref's HEAD instead of trunk's tip. `base` is what the
15114
+ // batch sits on from here on; without --onto it is trunk's tip, and nothing below changes.
15115
+ let base = trunkNow;
15116
+ let parent = null; // { ref, sha, chain, verdict } while the parent has not landed
15117
+ if (opts.onto) {
15118
+ const want = shipBatch.parseBatchRef(opts.onto).ref;
15119
+ const p = batchRefs.find((x) => x.parsed.ref === want) || null;
15120
+ const ours = swept.find((x) => x.members.some((m) => members.includes(m.branch)));
15121
+ if (p && p.sha === trunkNow) {
15122
+ print(` ${want} has landed — ${trunk} is at its head ${shortSha(trunkNow)}; this batch sits on ${trunk}'s tip`);
15123
+ } else if (!p || !chains.get(want).rooted) {
15124
+ if (ours) {
15125
+ print(`✗ ship-batch: ${ours.ref} was built on ${want}, which ${p ? `is no longer rooted at ${trunk}'s tip (${chains.get(want).why})` : `is gone from ${remote}`} — nothing landed; ${ours.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
15126
+ J.step = 'chained-decline';
15127
+ return serial('its parent batch was discarded, or trunk moved some other way — the chain cannot land in order', ours.members.map((m) => m.branch));
15128
+ }
15129
+ // The parent landed and its lander deleted the ref: our batch (if staged) now sits on trunk's tip.
15130
+ const atTip = rooted.find((x) => trunkNow.startsWith(x.parsed.base7));
15131
+ const landedParent = !p && atTip && carriedBy(atTip.parsed.ref, trunkNow, atTip.sha).some((m) => members.includes(m.branch));
15132
+ if (!landedParent && p) {
15133
+ throw new UserError(`--onto ${want}: it is not rooted at ${trunk}'s tip (${chains.get(want).why}) — build on ${trunk} instead (drop --onto)`);
15134
+ }
15135
+ if (!landedParent) {
15136
+ // ls-remote cannot tell "never existed" from "discarded" or "trunk moved some other way" — and
15137
+ // for the last two the issue's rule is a decline. So a missing parent declines: nothing of
15138
+ // this chain can land in order, and the members go back to the queue (#605).
15139
+ J.step = 'chained-decline';
15140
+ print(`✗ ship-batch: --onto ${want}: no such batch ref on ${remote} — it was discarded, landed under other members, or never existed.`);
15141
+ return serial(`nothing to chain onto — build on ${trunk} instead (the same command without --onto)`);
15142
+ }
15143
+ print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
15144
+ } else {
15145
+ const pc = chains.get(want);
15146
+ const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
15147
+ const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
15148
+ if (verdict.state === 'red') {
15149
+ if (child) {
15150
+ const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
15151
+ print(`✗ ship-batch: ${want} is red (${verdict.why}) — it will not land at ${shortSha(p.sha)}, so ${child.parsed.ref} built on it cannot land in order. Nothing landed; ${child.parsed.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto once ${want} is settled.`);
15152
+ deleteRef(child.parsed.ref);
15153
+ J.step = 'chained-decline';
15154
+ return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
15155
+ }
15156
+ throw new UserError(`--onto ${want}: its combined run is red (${verdict.why}) — nothing to chain onto; build on ${trunk} instead (drop --onto)`);
15157
+ }
15158
+ if (verdict.state === 'none' && !child) {
15159
+ throw new UserError(`--onto ${want}: it has no combined run in flight or green yet — wait for its run to start, then run this command again`);
15160
+ }
15161
+ if (!child && pc.depth >= shipBatch.MAX_CHAIN_DEPTH) {
15162
+ throw new UserError(`--onto ${want}: it is already ${pc.depth} deep from ${trunk}'s tip — a chain is at most ${shipBatch.MAX_CHAIN_DEPTH} batches (#605); wait for its root to land`);
15163
+ }
15164
+ base = p.sha;
15165
+ parent = { ref: want, sha: p.sha, chain: pc, verdict };
15166
+ }
15167
+ }
15168
+ Object.assign(J, { base, parentRef: parent ? parent.ref : null, rootSha: trunkNow, depth: parent ? parent.chain.depth + 1 : 1, ref: shipBatch.batchRefName(base) });
15169
+ const atBase = rooted.find((x) => (!parent || x.parsed.ref !== parent.ref) && base.startsWith(x.parsed.base7)) || null;
14805
15170
  let existing = null;
14806
15171
  if (atBase) {
14807
- const log = git.git(['log', '--format=%B%x00', `${trunkNow}..${atBase.sha}`], repoAbs);
15172
+ const log = git.git(['log', '--format=%B%x00', `${base}..${atBase.sha}`], repoAbs);
14808
15173
  const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
14809
15174
  const foreign = inBatch.filter((m) => !members.includes(m.branch));
14810
15175
  // #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
@@ -14833,8 +15198,24 @@ function cmdShipBatch(opts) {
14833
15198
  }
14834
15199
  }
14835
15200
  }
14836
- const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14837
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
15201
+ let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15202
+ // #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
15203
+ // heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
15204
+ // the same re-run / split path a light red does, and the split walks toward the culprit.
15205
+ let heavyWave = null;
15206
+ if (verdict && integrationProfile.parseProfile(doc).profile === 'gated') {
15207
+ heavyWave = heavyLaneAt(repoAbs, doc, existing.sha);
15208
+ if (!heavyWave.present) {
15209
+ print(`✗ ship-batch: integration-profile: gated, but no .github/workflows/${heavyWave.file} at ${existing.ref}@${shortSha(existing.sha)} — a wave lands only on a green heavy run, and there is no heavy lane to run. Nothing landed.`);
15210
+ print(' Add one: `colab template ci-<stack>-heavy --dest .github/workflows/ci-heavy.yml` (or name yours with heavy-workflow:), land it, then re-run once it is on trunk.');
15211
+ return 4;
15212
+ }
15213
+ verdict = integrationProfile.waveVerdict(verdict, heavyWave.verdict);
15214
+ }
15215
+ // #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
15216
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
15217
+ J.step = step.step;
15218
+ if (existing) J.members = existing.members.map((m) => ({ branch: m.branch, sha: m.sha, eligible: true, inBatch: true, why: `staged in ${existing.ref}` }));
14838
15219
  if (opts.split && !(verdict && verdict.state === 'red')) {
14839
15220
  print(` --split ignored: ${existing ? `${existing.ref} is not red (${verdict ? verdict.state : 'members changed'})` : 'no batch is staged at this base'} — only a red combined run splits (#557)`);
14840
15221
  }
@@ -14847,6 +15228,7 @@ function cmdShipBatch(opts) {
14847
15228
  }
14848
15229
  if (step.step === 'wait-run') {
14849
15230
  print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
15231
+ if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
14850
15232
  print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
14851
15233
  return 3;
14852
15234
  }
@@ -14883,15 +15265,33 @@ function cmdShipBatch(opts) {
14883
15265
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
14884
15266
  return 4;
14885
15267
  }
15268
+ if (step.step === 'land' && parent) {
15269
+ // #605: land in order — only once trunk's tip IS the parent's head. Until then the parent is in
15270
+ // flight (wait, exit 3); a parent that is red will never land at that sha (delete, exit 4).
15271
+ const ls = shipBatch.chainedLandStep({ parent: parent.chain, parentVerdict: parent.verdict });
15272
+ J.step = ls.step === 'wait' ? 'chained-wait' : 'chained-decline';
15273
+ J.reason = ls.why;
15274
+ if (ls.step === 'wait') {
15275
+ print(`⏸ BATCH-CHAINED ${existing.ref}@${shortSha(existing.sha)} — combined run green; it lands after ${parent.ref}: ${ls.why}. Nothing landed.`);
15276
+ print(` Wait for ${parent.ref} to land (bounded, B1a), then run this command again — it lands with no second run.`);
15277
+ return 3;
15278
+ }
15279
+ print(`✗ ship-batch: ${existing.ref} cannot land in order — ${ls.why}. Nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
15280
+ deleteRef(existing.ref);
15281
+ return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
15282
+ }
14886
15283
  if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
14887
15284
 
14888
15285
  // ---- (d) pick the members — each through its OWN ship gates ----
14889
15286
  const st = state.loadState();
14890
15287
  const evaluated = [];
15288
+ // #605: a member the chain below already carries lands with that batch — it never joins a second one.
15289
+ const inChain = parent ? carriedByChain(parent.sha) : new Map();
14891
15290
  for (const b of members) {
14892
15291
  const refs = git.branchRefs(repoAbs, b, remote);
14893
15292
  let why = null, report = null, ciClass = null, files = [];
14894
15293
  if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
15294
+ else if (inChain.has(b)) why = `already in ${inChain.get(b)} — it lands with that batch, not this one`;
14895
15295
  else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
14896
15296
  if (!why) {
14897
15297
  // #591: a hand-off member is read through the SAME door a single --handoff ship uses
@@ -14924,12 +15324,13 @@ function cmdShipBatch(opts) {
14924
15324
  return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
14925
15325
  })()
14926
15326
  : shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
14927
- print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
15327
+ print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)}${parent ? ` · onto ${parent.ref}@${shortSha(parent.sha)} (depth ${parent.chain.depth + 1}, lands after it)` : ''} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
14928
15328
  print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
14929
15329
  e.ok && !selected.includes(e) ? (splitHalf ? 'eligible — held by the split for the next batch' : `eligible — waits for the next batch (cap ${size})`) : e.why]), ['', 'MEMBER', 'DETAIL']));
14930
15330
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
15331
+ J.members = evaluated.map((e) => ({ branch: e.branch, sha: e.sha || null, eligible: e.ok, inBatch: selected.includes(e), why: e.why }));
14931
15332
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14932
- if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
15333
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf && !parent) {
14933
15334
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14934
15335
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14935
15336
  const lone = selected[0];
@@ -14948,10 +15349,11 @@ function cmdShipBatch(opts) {
14948
15349
  if (step.step === 'serial') return serial('no member can join — each one above says why');
14949
15350
 
14950
15351
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14951
- const ref = shipBatch.batchRefName(trunkNow);
15352
+ // #605: on a chain, the batch is built on the parent's head and named after it — one batch per base.
15353
+ const ref = shipBatch.batchRefName(base);
14952
15354
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-ship-batch-'));
14953
- const add = git.git(['worktree', 'add', '--detach', dir, trunkNow], repoAbs);
14954
- if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(trunkNow)} to build the batch: ${git.gitFailureLine(add.stderr)}`); }
15355
+ const add = git.git(['worktree', 'add', '--detach', dir, base], repoAbs);
15356
+ if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(base)} to build the batch: ${git.gitFailureLine(add.stderr)}`); }
14955
15357
  const cleanup = () => git.git(['worktree', 'remove', '--force', dir], repoAbs);
14956
15358
  const machineLine = shipMachineTrailerDecision(repoAbs, doc).line;
14957
15359
  const built = [];
@@ -15019,6 +15421,8 @@ function cmdShipBatch(opts) {
15019
15421
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
15020
15422
  }
15021
15423
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
15424
+ for (const d of dropped) Object.assign(J.members.find((r) => r.branch === d.branch) || {}, { inBatch: false, why: d.why });
15425
+ J.step = 'build';
15022
15426
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
15023
15427
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
15024
15428
  // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
@@ -15044,8 +15448,10 @@ function cmdShipBatch(opts) {
15044
15448
  }
15045
15449
  if (opts.dry) {
15046
15450
  cleanup();
15047
- print(`→ READY: would push ${ref} = ${shortSha(trunkNow)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15048
- print(' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15451
+ print(`→ READY: would push ${ref} = ${shortSha(base)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15452
+ print(parent
15453
+ ? ` then wait on ONE combined run, and fast-forward trunk to it only once ${parent.ref} has landed at ${shortSha(parent.sha)} (#605).`
15454
+ : ' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15049
15455
  if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
15050
15456
  return 0;
15051
15457
  }
@@ -15053,7 +15459,7 @@ function cmdShipBatch(opts) {
15053
15459
  const push = git.run('git', ['push', '--force', remote, `${head}:refs/heads/${ref}`], { cwd: repoAbs });
15054
15460
  cleanup();
15055
15461
  if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
15056
- print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
15462
+ print(` pushed ${ref} = ${shortSha(base)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})${parent ? ` — chained onto ${parent.ref}; it lands after it` : ''}`);
15057
15463
  if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
15058
15464
  print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
15059
15465
  return 3;
@@ -16576,6 +16982,23 @@ function cmdPromote(argv) {
16576
16982
  else checks.push(['✗', 'trunk CI green', `${trunk}@${shortSha(run.sha)}: status=${run.status} conclusion=${run.conclusion || 'none'} (fail-to-start counts as not green)`]);
16577
16983
  }
16578
16984
 
16985
+ // #610: integration-profile: promote — the heavy lane gates the promotion: green at the exact sha
16986
+ // being promoted (origin's trunk tip). Never dispatched from here: promotion is a human act, and
16987
+ // the command to start the heavy lane is printed instead.
16988
+ let heavyOk = true;
16989
+ if (integrationProfile.parseProfile(doc).profile === 'promote') {
16990
+ const tipR = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16991
+ const tip = tipR.ok ? tipR.stdout : null;
16992
+ const lane = tip ? heavyLaneAt(repoAbs, doc, tip) : null;
16993
+ const at = tip ? `${trunk}@${shortSha(tip)}` : trunk;
16994
+ let detail;
16995
+ if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
16996
+ else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
16997
+ else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
16998
+ else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: gh workflow run ${lane.file} --ref ${trunk} -f ref=${tip}` : ''}`; }
16999
+ checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
17000
+ }
17001
+
16579
17002
  const localTrunk = git.git(['rev-parse', trunk], repoAbs);
16580
17003
  const originTrunk = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16581
17004
  const trunkSyncOk = localTrunk.ok && originTrunk.ok && localTrunk.stdout === originTrunk.stdout;
@@ -16605,7 +17028,7 @@ function cmdPromote(argv) {
16605
17028
  ahead > 0 ? `${ahead} commit(s) to promote` : `could not count ${remote}/${MAIN}..${remote}/${trunk}`]);
16606
17029
  }
16607
17030
 
16608
- const preOk = ciOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
17031
+ const preOk = ciOk && heavyOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
16609
17032
 
16610
17033
  // ---- report ----
16611
17034
  say(`promote ${shortRepo(repoAbs)} · ${trunk} → ${MAIN}` + (opts.dry ? ' [DRY RUN]' : ''));
@@ -16849,7 +17272,9 @@ re-running install.sh; \`colab update\` reports it when it is behind. \`colab --
16849
17272
  which of the two you are talking to.
16850
17273
  `;
16851
17274
 
16852
- function print(s) { process.stdout.write(s.endsWith('\n') ? s : s + '\n'); return 0; }
17275
+ // #605: `ship --batch --dry --json` keeps stdout for its one JSON document; the prose goes to stderr.
17276
+ let PRINT_TO_STDERR = false;
17277
+ function print(s) { (PRINT_TO_STDERR ? process.stderr : process.stdout).write(s.endsWith('\n') ? s : s + '\n'); return 0; }
16853
17278
  function warn(s) { process.stderr.write(`! ${s}\n`); }
16854
17279
  /**
16855
17280
  * `colab ship` sets this to an array while it runs B3 (worktree teardown) through B4 (per-issue