@futurelastic/colab-handbook 1.13.0-rc.52 → 1.13.0-rc.54

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/audit/audit.mjs CHANGED
@@ -1305,7 +1305,7 @@ function auditRepo(target, ctx) {
1305
1305
  if (prefixRaw !== null && prefixRaw !== "machine") fail(`branchPrefix is ${JSON.stringify(prefixRaw)}, expected "machine" (omit for the unprefixed default)`);
1306
1306
 
1307
1307
  // ---- ship-batch (#373) ------------------------------------------------------
1308
- // Batch landing's opt-in: an integer 1–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
1308
+ // Batch landing's opt-in: an integer 1–MAX_BATCH (tools/lib/ship-batch.js parseShipBatch — the one reading
1309
1309
  // `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
1310
1310
  // to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
1311
1311
  // the CI templates' descriptor check too (#416, held to this same parser by
@@ -1333,6 +1333,17 @@ function auditRepo(target, ctx) {
1333
1333
  else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1334
1334
  }
1335
1335
 
1336
+ // ---- ship-batch-steps (#557) -------------------------------------------------
1337
+ // The sizes an adaptive batch walks through (tools/lib/ship-batch.js parseShipBatchSteps, the
1338
+ // reading `colab ship --batch` uses): ascending whole numbers within ship-batch. Malformed fails
1339
+ // here and in the CI templates' descriptor check, the #416 pattern — ship fails closed to the fixed
1340
+ // size, silently. Steps with no batch to size (ship-batch absent or 1) are inert, so they warn.
1341
+ if (shipBatch.STEPS_KEY in (cfg || {}) && cfg[shipBatch.STEPS_KEY] !== null) {
1342
+ const sCfg = shipBatch.parseShipBatchSteps(cfg);
1343
+ if (!sCfg.valid) fail(`${sCfg.reason} — see project.schema.md, ship-batch-steps`);
1344
+ else if (shipBatch.parseShipBatch(cfg).n <= 1) warn(`${sCfg.reason} is inert without ship-batch > 1 — there is no batch to size`);
1345
+ }
1346
+
1336
1347
  // ---- ci-wait-factor (#559) ----------------------------------------------------
1337
1348
  // The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
1338
1349
  // (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.52"
36
+ "version": "1.13.0-rc.54"
37
37
  }
@@ -508,13 +508,15 @@ jobs:
508
508
 
509
509
  # ---------------------------------------------------------------------------
510
510
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
511
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
511
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
512
512
  # once turned every landing in a busy repo back to serial while this CI stayed
513
513
  # green; only a ship dry run noticed. So the value fails HERE, where the person
514
514
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
515
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
516
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
515
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
516
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
517
517
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
518
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
519
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
518
520
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
519
521
  # ---------------------------------------------------------------------------
520
522
  - name: Descriptor check (.github/project.yml)
@@ -530,11 +532,26 @@ jobs:
530
532
  }
531
533
  v="$(field ship-batch)"
532
534
  case "$v" in
533
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
535
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
534
536
  *)
535
- echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
537
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
536
538
  exit 1 ;;
537
539
  esac
540
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
541
+ s="$(field ship-batch-steps)"
542
+ case "$s" in
543
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
544
+ *)
545
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
546
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
547
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
548
+ && printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
549
+ echo "ship-batch-steps: $list — ok"
550
+ else
551
+ echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
552
+ exit 1
553
+ fi ;;
554
+ esac
538
555
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
539
556
  w="$(field ship-batch-wait)"
540
557
  case "$w" in
@@ -474,13 +474,15 @@ jobs:
474
474
 
475
475
  # ---------------------------------------------------------------------------
476
476
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
477
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
477
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
478
478
  # once turned every landing in a busy repo back to serial while this CI stayed
479
479
  # green; only a ship dry run noticed. So the value fails HERE, where the person
480
480
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
481
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
482
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
481
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
482
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
483
483
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
484
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
485
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
484
486
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
485
487
  # ---------------------------------------------------------------------------
486
488
  - name: Descriptor check (.github/project.yml)
@@ -496,11 +498,26 @@ jobs:
496
498
  }
497
499
  v="$(field ship-batch)"
498
500
  case "$v" in
499
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
501
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
500
502
  *)
501
- echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
503
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
502
504
  exit 1 ;;
503
505
  esac
506
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
507
+ s="$(field ship-batch-steps)"
508
+ case "$s" in
509
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
510
+ *)
511
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
512
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
513
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
514
+ && printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
515
+ echo "ship-batch-steps: $list — ok"
516
+ else
517
+ echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
518
+ exit 1
519
+ fi ;;
520
+ esac
504
521
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
505
522
  w="$(field ship-batch-wait)"
506
523
  case "$w" in
@@ -460,13 +460,15 @@ jobs:
460
460
 
461
461
  # ---------------------------------------------------------------------------
462
462
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
463
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
463
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
464
464
  # once turned every landing in a busy repo back to serial while this CI stayed
465
465
  # green; only a ship dry run noticed. So the value fails HERE, where the person
466
466
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
467
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
468
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
467
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
468
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
469
469
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
470
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
471
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
470
472
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
471
473
  # ---------------------------------------------------------------------------
472
474
  - name: Descriptor check (.github/project.yml)
@@ -482,11 +484,26 @@ jobs:
482
484
  }
483
485
  v="$(field ship-batch)"
484
486
  case "$v" in
485
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
487
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
486
488
  *)
487
- echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
489
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
488
490
  exit 1 ;;
489
491
  esac
492
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
493
+ s="$(field ship-batch-steps)"
494
+ case "$s" in
495
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
496
+ *)
497
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
498
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
499
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
500
+ && printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
501
+ echo "ship-batch-steps: $list — ok"
502
+ else
503
+ echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
504
+ exit 1
505
+ fi ;;
506
+ esac
490
507
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
491
508
  w="$(field ship-batch-wait)"
492
509
  case "$w" in
package/tools/colab CHANGED
@@ -77,6 +77,7 @@ const releaseCut = require('./lib/release-cut');
77
77
  const releaseFinalize = require('./lib/release-finalize');
78
78
  const releaseChannel = require('./lib/release-channel');
79
79
  const shippedBranch = require('./lib/shipped-branch');
80
+ const landedPrs = require('./lib/landed-prs');
80
81
  const shipRoles = require('./lib/ship-roles'); // #372
81
82
  const shipHandoff = require('./lib/ship-handoff'); // #578
82
83
  const refsBrake = require('./lib/refs-brake'); // #385
@@ -4513,7 +4514,8 @@ CI grant merges into a repo whose own test suite is known-failing:
4513
4514
  for the BRANCH's own current head (the same "ask by sha" check \`ship\` itself uses) — a human's
4514
4515
  say-so alone is never enough. \`--evidence-run\` is a RECORDING-ONLY pointer for the audit trail;
4515
4516
  it can never substitute for the measured run. If the branch has no run yet, open a PR for it
4516
- (\`gh pr create\`) and let CI finish, then re-run this command.
4517
+ (\`gh pr create\`) and let CI finish, then re-run this command. You do not need to close that
4518
+ PR afterwards: \`colab ship\` closes it once the branch lands (#584).
4517
4519
  2. NEVER STACKS. Creating a grant refuses outright if trunk is not currently red (nothing to
4518
4520
  exempt), and refuses again if a PRIOR ci-grant already merged something and trunk has been red
4519
4521
  continuously since — a second exemption on a still-broken repo is exactly the failure this gate
@@ -4862,7 +4864,7 @@ function cmdCiGrantCreate(repoAbs, num, opts) {
4862
4864
  throw new UserError(
4863
4865
  `"${opts.branch}" has no completed, successful CI run for its current head (${shortSha(evRun.sha)}) — ` +
4864
4866
  `a CI grant requires MEASURED evidence, never a human's say-so alone. Open a PR for it ` +
4865
- `(\`gh pr create\`) and let CI finish, then re-run this command.`);
4867
+ `(\`gh pr create\`) and let CI finish, then re-run this command — \`colab ship\` closes that PR once the branch lands (#584).`);
4866
4868
  }
4867
4869
  const evidenceSha = evRun.sha;
4868
4870
 
@@ -6329,6 +6331,9 @@ in a cleanup cron.
6329
6331
  reported but never deleted (a label a triage session just created and has not
6330
6332
  applied yet is indistinguishable from one whose members were all transferred
6331
6333
  away — the labels API exposes no creation time, so a human decides).
6334
+ Also lists open PRs whose head commit already landed in trunk (#584) — CI-trigger
6335
+ PRs a squash ship left open. Report-only, --prune included: doctor never closes
6336
+ a PR. A PR whose head is not in the local clone is not judged.
6332
6337
  `;
6333
6338
 
6334
6339
  const EMPTY_SET = new Set();
@@ -6413,7 +6418,7 @@ function cmdDoctor(argv) {
6413
6418
  const report = { deadWorktrees: [], orphanClaims: [], staleClaims: [], stalePlaces: [], unprovablePlaces: [], releasedPlaces: [], orphanPorts: [], brokenRecords: [], prunedPorts: [],
6414
6419
  renamedHostRecords: [], unprovenHostRecords: [],
6415
6420
  mergedFlips: [], mergedSweep: [], mergedDirty: [], mergedHookFail: [], mergedRemoveFail: [], shippedBranches: [], ghostPorts: [],
6416
- spentGroupLabels: [], groupLabelsChecked: !!opts.sync, pruned: !!opts.prune };
6421
+ spentGroupLabels: [], groupLabelsChecked: !!opts.sync, landedPrs: [], landedPrsUnread: [], pruned: !!opts.prune };
6417
6422
 
6418
6423
  // One answer per (repo, branch) — pass 5b asks about the same branch from a worktree and from each
6419
6424
  // of its claims, and every miss costs two `git rev-parse` calls.
@@ -6804,6 +6809,28 @@ function cmdDoctor(argv) {
6804
6809
  }
6805
6810
  }
6806
6811
 
6812
+ // 9b. open PRs whose head already landed (#584) — the CI-trigger PRs a squash ship left open before
6813
+ // ship learned to close them, or that a ship on another machine could not close. Report-only,
6814
+ // --prune included: closing a PR is a write on a shared forge, and a human may still want it.
6815
+ // Behind --sync for the same reason as pass 9 (network). A PR whose head commit is not in this
6816
+ // clone is not judged — the answer would be a guess — so the list is honest, not exhaustive.
6817
+ if (opts.sync && git.ghAvailable()) {
6818
+ const repos = [...new Set([...(config.repos || []), ...knownRepos(config)].map((r) => path.resolve(r)))]
6819
+ .filter((r) => repoLive(r) && git.remoteUrl(r));
6820
+ for (const repo of repos) {
6821
+ const trunk = resolveTrunk(repo, projectDoc(repo));
6822
+ if (!trunk) continue;
6823
+ const listed = git.ghOpenPrs(repo);
6824
+ if (listed.error) { report.landedPrsUnread.push({ repo: shortRepo(repo), error: listed.error }); continue; }
6825
+ for (const pr of listed.prs) {
6826
+ if (!pr.headRefOid || pr.headRefName === trunk) continue;
6827
+ if (!git.git(['cat-file', '-e', `${pr.headRefOid}^{commit}`], repo).ok) continue;
6828
+ if (landed.landedState(repo, trunk, pr.headRefOid).state !== 'landed') continue;
6829
+ report.landedPrs.push({ repo: shortRepo(repo), number: pr.number, url: pr.url || '', branch: pr.headRefName || '', trunk });
6830
+ }
6831
+ }
6832
+ }
6833
+
6807
6834
  // 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
6808
6835
  // the verdict — it is configuration, not state drift. Silent on a machine with no
6809
6836
  // <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
@@ -6953,6 +6980,17 @@ function cmdDoctor(argv) {
6953
6980
  print(' NOT exhaustive: a branch whose work trunk later rewrote can conflict against trunk');
6954
6981
  print(' instead of matching it, and is omitted here rather than risk calling unmerged work spent.');
6955
6982
  }
6983
+ // #584 — after the verdict, not counted: an open PR on a landed branch breaks nothing, it reads as
6984
+ // unmerged work on a tracker. Printed only under --sync.
6985
+ if (report.landedPrs.length) {
6986
+ print('');
6987
+ print(`Open PRs whose branch already landed (${report.landedPrs.length}) — the squash left them open:`);
6988
+ for (const p of report.landedPrs) print(` #${p.number} ${p.branch} [${p.repo}] → in ${p.trunk}${p.url ? ` ${p.url}` : ''}`);
6989
+ print(' `colab ship` closes these itself since #584; these predate that, or a ship could not close them.');
6990
+ print(' doctor never closes a PR, --prune included. To close one:');
6991
+ print(` gh pr close ${report.landedPrs[0].number} --comment "Landed on ${report.landedPrs[0].trunk} by squash." # in ${report.landedPrs[0].repo}`);
6992
+ }
6993
+ for (const u of report.landedPrsUnread) warn(`could not list open PRs in ${u.repo} (${u.error}) — landed-PR check skipped there`);
6956
6994
  // Also after the verdict, and also not drift: a spent group label breaks nothing, it is picker
6957
6995
  // noise on a tracker. Printed only under --sync, so silence here NEVER means "checked, clean" —
6958
6996
  // which is why a --sync run that finds nothing says so explicitly below.
@@ -10315,7 +10353,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10315
10353
  }
10316
10354
 
10317
10355
  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]
10318
- colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10356
+ colab ship --batch <b1,b2[,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10319
10357
 
10320
10358
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10321
10359
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10534,7 +10572,7 @@ Every other precondition is unchanged. No flag, env var or project.yml field wid
10534
10572
 
10535
10573
  TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
10536
10574
  diff changes .github/project.yml ALONE, every changed line inside a tuning key (ship-batch,
10537
- ship-batch-wait, ci-wait-factor, thresholds) and every moved value valid; never with an authority
10575
+ ship-batch-wait, ship-batch-steps, ci-wait-factor, thresholds) and every moved value valid; never with an authority
10538
10576
  key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
10539
10577
  release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
10540
10578
  writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
@@ -10558,7 +10596,7 @@ keeps its claim so a re-run finds it. Cannot be combined with --worktree/--branc
10558
10596
  --delete-branch/--keep-branch/--keep-worktree/--adopt. \`writes: direct\` is not required. --dry and --dry --json
10559
10597
  work as usual (json: \`direct: true\`, \`branch: null\`, \`mode: "evidence-close"\`, \`coreReview\`).
10560
10598
 
10561
- BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–3;
10599
+ BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–${shipBatch.MAX_BATCH};
10562
10600
  absent or 1 declines every --batch call. It tests up to N green candidates as ONE combined head, then
10563
10601
  fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle.
10564
10602
  A batch of ONE is valid (#562): a lone ready member lands the same way, so the combined run — the
@@ -10581,8 +10619,12 @@ It never waits: each call reads the remote, takes ONE step and exits —
10581
10619
  4 declined — nothing landed; the last line is "→ SERIAL: colab ship --branch <b1> · …". Causes:
10582
10620
  not enabled, no auto-trunk, no workflow fires on ship-batch/** (the run could never arrive),
10583
10621
  trunk CI red (the cure/grant doors apply per member, never to a batch), no member can join,
10584
- or the combined run is red — classify it: red:infra → the printed \`gh run rerun\`,
10585
- once; red:finding, or red again after that one re-run → serial
10622
+ or a batch of ONE whose combined run is red — classify it: red:infra → the printed
10623
+ \`gh run rerun\`, once; red:finding, or red again after that one re-run → serial.
10624
+ A red batch of TWO OR MORE never goes serial (#557): red:infra → re-run once; red:finding →
10625
+ the same command plus --split; red again after the re-run → it splits by itself. A split
10626
+ rebuilds the same ship-batch/<trunk-sha7> with the FIRST half of its members (exit 3); the rest
10627
+ wait for the next batch, and a red half splits again
10586
10628
  1 refused (a broken checkout, an unreadable remote) — or the land push was refused while trunk did
10587
10629
  NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
10588
10630
  re-running hits the same refusal until its cause is fixed (#509)
@@ -10603,6 +10645,11 @@ at build, added since) is NOT landed with it — the command names both lists an
10603
10645
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10604
10646
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10605
10647
  Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
10648
+ ADAPTIVE SIZE (#557) — opt-in per repo: \`ship-batch-steps: 2,4,8\` in project.yml, ascending sizes
10649
+ within ship-batch. Absent or malformed: every batch is up to ship-batch, exactly as above. With it,
10650
+ each batch head carries "Ship-Batch-Size: <s>" ("<s> red" on a split half), and the next batch is
10651
+ built at the step above the last landed one's size after a green, the step below after a red, the
10652
+ smallest step when trunk carries none yet.
10606
10653
  PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
10607
10654
  unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10608
10655
  ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
@@ -13130,7 +13177,7 @@ function cmdShip(argv) {
13130
13177
  // repeat (`once`), checked here before any git or GitHub call.
13131
13178
  lists: { '--refs': 'refs' },
13132
13179
  once: true,
13133
- flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '-h': 'help', '--help': 'help' },
13180
+ flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '--split': 'split', '-h': 'help', '--help': 'help' },
13134
13181
  });
13135
13182
  if (opts.help) return print(HELP_SHIP);
13136
13183
  // --json is scoped to --dry only (#77): a machine-readable READ of the preconditions. Reporting
@@ -13140,6 +13187,7 @@ function cmdShip(argv) {
13140
13187
  if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
13141
13188
  // #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
13142
13189
  if (opts.handoff && (opts.batch || opts.direct)) throw new UserError(`--handoff applies to one --branch ship — not to ${opts.batch ? '--batch' : '--direct'} (see \`colab ship --help\`)`);
13190
+ 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');
13143
13191
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
13144
13192
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
13145
13193
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -14085,11 +14133,13 @@ function cmdShip(argv) {
14085
14133
  // a long ship these lines would otherwise scroll off above the `✓ Shipped` line — which is
14086
14134
  // exactly how #304's failure went unnoticed in the first place.
14087
14135
  deferredCollector = [];
14136
+ let reviewPrHandled = null; // #584: the #350 review PR, already closed (or warned about) above
14088
14137
  // #350: the approved PR is spent — its work landed by squash, which the forge cannot see as a merge.
14089
14138
  if (coreReview.verdict === 'approved' && coreReview.pr && gh) {
14090
14139
  const closed = git.ghPrClose(repoAbs, coreReview.pr.number, `Landed on \`${target}\` as ${sha} by \`colab ship\` (#350), approved by ${coreReview.approval.by}.`);
14091
14140
  if (closed.ok) print(` closed PR #${coreReview.pr.number} (landed as ${sha})`);
14092
14141
  else warnDeferred(`could not close PR #${coreReview.pr.number} (${(closed.stderr || '').split('\n')[0]}) — it landed as ${sha}; close it by hand`);
14142
+ reviewPrHandled = coreReview.pr.number; // #584: either way the tail's landed-PR close must not touch it again
14093
14143
  }
14094
14144
  // Only when the target IS the shared checkout. `ephemeralTarget === false` means
14095
14145
  // `targetDir === repoAbs` (see #234's note above); a declared integration line merged in a
@@ -14155,6 +14205,7 @@ function cmdShip(argv) {
14155
14205
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
14156
14206
  // same block, and re-assigning the collector here would silently discard them.
14157
14207
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
14208
+ skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14158
14209
  evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
14159
14210
 
14160
14211
  print('');
@@ -14174,6 +14225,38 @@ function cmdShip(argv) {
14174
14225
  }
14175
14226
 
14176
14227
 
14228
+ /**
14229
+ * #584: close every open PR whose head is the branch this ship just landed — the PR a person or an
14230
+ * automation opened only to obtain branch CI. The forge never sees a squash as a merge of that PR, so
14231
+ * without this it stays open forever, reading as unmerged work. Only a PR whose head commit is the
14232
+ * landed tip (or an ancestor of it) is closed; one carrying commits that did not land is kept and
14233
+ * reported. Best-effort throughout: every failure defers a warning, none fails the ship.
14234
+ */
14235
+ function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
14236
+ const remoteName = git.remoteInfo(repoAbs).name || 'origin';
14237
+ const tipOf = (ref) => { const r = git.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoAbs); return r.ok ? r.stdout.trim() : null; };
14238
+ const tip = tipOf(`refs/heads/${sess.branch}`) || tipOf(`refs/remotes/${remoteName}/${sess.branch}`);
14239
+ const headLanded = (oid) => {
14240
+ if (!tip) return false;
14241
+ if (oid === tip) return true;
14242
+ return git.git(['merge-base', '--is-ancestor', oid, tip], repoAbs).ok;
14243
+ };
14244
+ const res = landedPrs.closeLandedPrs({
14245
+ prs: git.ghOpenPrsForBranch(repoAbs, sess.branch),
14246
+ headLanded,
14247
+ close: (n, comment) => git.ghPrClose(repoAbs, n, comment),
14248
+ comment: landedPrs.landedPrComment({ target, sha, issues }),
14249
+ skip,
14250
+ });
14251
+ if (res.listError) {
14252
+ warnDeferred(`could not list open PRs for ${sess.branch} (${res.listError}) — any PR opened for its CI is still open; close it by hand (it landed as ${sha})`);
14253
+ return;
14254
+ }
14255
+ for (const n of res.closed) print(` closed PR #${n} — its branch ${sess.branch} landed as ${sha} (#584)`);
14256
+ for (const f of res.failed) warnDeferred(`could not close PR #${f.number} (${f.error}) — ${sess.branch} landed as ${sha}; close it by hand`);
14257
+ for (const k of res.kept) warnDeferred(`kept PR #${k.number} open: ${k.reason} (${sess.branch} landed as ${sha}) — it carries work that did not ship`);
14258
+ }
14259
+
14177
14260
  /**
14178
14261
  * The post-merge tail every landed branch gets — cmdShip's B3 through i2, moved here unchanged (#373)
14179
14262
  * so a batch member gets exactly the same steps in the same order: worktree teardown (B3), the claims
@@ -14182,7 +14265,13 @@ function cmdShip(argv) {
14182
14265
  * addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
14183
14266
  * batch member.
14184
14267
  */
14185
- function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '' }) {
14268
+ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
14269
+ // #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
14270
+ // B3 below may delete it, and "did the PR's head land?" is answered against that tip.
14271
+ if (gh && sess.branch) {
14272
+ try { shipCloseLandedPrs(repoAbs, sess, { target, sha, issues: closeIssues, skip: skipPrs }); }
14273
+ catch (e) { warnDeferred(`landed-PR close for ${sess.branch} failed (${e.message}) — the ship landed as ${sha}; close any PR for it by hand`); }
14274
+ }
14186
14275
  const worktreeKept = !!(sess.name && opts.keepWorktree);
14187
14276
  if (sess.name && !opts.keepWorktree) {
14188
14277
  print(`B3: removing worktree ${sess.name} …`);
@@ -14386,13 +14475,27 @@ function cmdShipBatch(opts) {
14386
14475
  const waitCfg = shipBatch.parseShipBatchWait(doc);
14387
14476
  if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
14388
14477
  if (members.length < 1) return serial('--batch names no branch — name every ready candidate');
14389
- if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
14390
14478
 
14391
14479
  const remote = git.remoteFor(repoAbs);
14392
14480
  const fetched = git.git(['fetch', '--prune', remote], repoAbs);
14393
14481
  if (!fetched.ok) throw new UserError(`could not fetch ${remote}: ${git.gitFailureLine(fetched.stderr)} — a batch is never built from stale refs`);
14394
14482
  const trunkRef = `${remote}/${trunk}`;
14395
14483
 
14484
+ // #557: the size this batch is built at — fixed at ship-batch without steps; with them, one step
14485
+ // above the last landed batch's size after a green, one below after a red, read from trunk alone.
14486
+ const stepsCfg = shipBatch.parseShipBatchSteps(doc);
14487
+ if (!stepsCfg.valid) warn(`${stepsCfg.reason} — ignored: every batch is up to ship-batch: ${cfg.n} (fails closed, #557)`);
14488
+ let lastSize = null;
14489
+ if (stepsCfg.steps) {
14490
+ const lg = git.git(['log', '-1', '--first-parent', `--grep=^${shipBatch.SIZE_TRAILER_KEY}: `, '--format=%B', trunkRef], repoAbs);
14491
+ lastSize = lg.ok ? shipBatch.parseSizeTrailer([lg.stdout]) : null;
14492
+ }
14493
+ const size = shipBatch.adaptiveSize({ n: cfg.n, steps: stepsCfg.steps, last: lastSize });
14494
+ const sizeLabel = stepsCfg.steps
14495
+ ? `ship-batch: ${cfg.n} · step ${size} of ${stepsCfg.steps.join(',')}${lastSize ? ` — the last landed batch was ${lastSize.red ? `a split of a red one at ${lastSize.size}` : `green at ${lastSize.size}`}` : ' — no sized batch on trunk yet'}`
14496
+ : `ship-batch: ${cfg.n}`;
14497
+ if (members.length > size) warn(`--batch names ${members.length} branches; ${sizeLabel} caps the batch — the rest wait for the next one`);
14498
+
14396
14499
  // ---- (a) wiring: could the combined run ever arrive? Decided BEFORE anything is pushed. ----
14397
14500
  const fires = workflowsFiringAt(repoAbs, trunkRef, shipBatch.PROBE_REF);
14398
14501
  if (!shipBatch.wiring(fires).wired) {
@@ -14452,7 +14555,8 @@ function cmdShipBatch(opts) {
14452
14555
  if (!foreignStep) {
14453
14556
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
14454
14557
  const matches = heads.length >= 1 && heads.every((m) => m.now && m.now.startsWith(m.sha));
14455
- existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
14558
+ existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches,
14559
+ size: shipBatch.parseSizeTrailer(log.ok ? log.stdout.split('\0') : []) };
14456
14560
  // #415: the command line and the staged batch can name different sets. A requested branch the
14457
14561
  // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
14458
14562
  // along — say so, naming both lists, instead of resuming as if the two were the same.
@@ -14464,7 +14568,10 @@ function cmdShipBatch(opts) {
14464
14568
  }
14465
14569
  }
14466
14570
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14467
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict });
14571
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
14572
+ if (opts.split && !(verdict && verdict.state === 'red')) {
14573
+ 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)`);
14574
+ }
14468
14575
 
14469
14576
  if (step.step === 'rebuild') {
14470
14577
  print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
@@ -14486,6 +14593,24 @@ function cmdShipBatch(opts) {
14486
14593
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
14487
14594
  return 4;
14488
14595
  }
14596
+ if (step.step === 'red-rerun-or-split') {
14597
+ const ids = verdict.runIds.join(', ') || '(id unread)';
14598
+ const cmd = `colab ship --batch ${members.join(',')} --split${opts.repo ? ` --repo ${opts.repo}` : ''}`;
14599
+ print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}; run ${ids}). Nothing landed.`);
14600
+ print(` ${existing.members.length} members — it splits rather than going serial (#557). Classify it first (CONVENTIONS §4, Branch CI):`);
14601
+ for (const id of verdict.runIds) print(` red:infra → gh run rerun ${id} --failed then run this command again (one re-run only)`);
14602
+ print(` red:finding → ${cmd}`);
14603
+ print(' rebuilds this batch with its first half; the rest wait for the next batch');
14604
+ return 4;
14605
+ }
14606
+ let splitHalf = null;
14607
+ if (step.step === 'split') {
14608
+ const { first, held } = shipBatch.splitHalves(existing.members);
14609
+ splitHalf = { first, held, parentSize: existing.size ? existing.size.size : existing.members.length };
14610
+ print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}${verdict.attempt >= 2 ? ', after its one re-run' : ''}). Nothing landed.`);
14611
+ print(` splitting (#557): testing ${first.map((m) => m.branch).join(', ')} on the same base; held for the next batch: ${held.map((m) => m.branch).join(', ')}`);
14612
+ step = { step: 'build' };
14613
+ }
14489
14614
  if (step.step === 'red-serial') {
14490
14615
  print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
14491
14616
  deleteRef(existing.ref);
@@ -14518,13 +14643,21 @@ function cmdShipBatch(opts) {
14518
14643
  // #387: a generated path shared by two members is not an overlap — the build regenerates it (below).
14519
14644
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
14520
14645
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
14521
- const { selected, overflow } = shipBatch.selectMembers(eligible, cfg.n, { isGenerated: (f) => isGeneratedPath(f, generated) });
14522
- print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (ship-batch: ${cfg.n})${opts.dry ? ' [DRY RUN]' : ''}`);
14646
+ // #557: a split builds exactly its first half, in the red batch's order — the pre-sort is not re-run,
14647
+ // or a different subset would be tested and the bisection would not narrow.
14648
+ const { selected, overflow } = splitHalf
14649
+ ? (() => {
14650
+ const want = splitHalf.first.map((m) => m.branch);
14651
+ const sel = want.map((b) => eligible.find((e) => e.branch === b)).filter(Boolean);
14652
+ return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
14653
+ })()
14654
+ : shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
14655
+ 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]' : ''}`);
14523
14656
  print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
14524
- e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14657
+ 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']));
14525
14658
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14526
14659
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14527
- if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0) {
14660
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
14528
14661
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14529
14662
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14530
14663
  const lone = selected[0];
@@ -14616,13 +14749,17 @@ function cmdShipBatch(opts) {
14616
14749
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14617
14750
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14618
14751
  // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
14619
- if (dropped.length && built.length >= 1) {
14752
+ // #557: with steps declared (or on a split), the head also carries the size it was built at, so the
14753
+ // next build reads the lane's last outcome from trunk alone.
14754
+ const sizeLine = splitHalf ? shipBatch.sizeTrailer({ size: splitHalf.parentSize, red: true })
14755
+ : (stepsCfg.steps ? shipBatch.sizeTrailer({ size }) : null);
14756
+ if ((dropped.length || sizeLine) && built.length >= 1) {
14620
14757
  const last = built[built.length - 1];
14621
14758
  const cur = git.git(['log', '-1', '--format=%B'], dir);
14622
- const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
14759
+ const lines = [...dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls })), ...(sizeLine ? [sizeLine] : [])];
14623
14760
  const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
14624
14761
  if (am.ok) last.commit = git.git(['rev-parse', 'HEAD'], dir).stdout;
14625
- else warn(`could not record the dropped member(s) on the batch head: ${git.gitFailureLine(am.stderr)} — the drop is on this terminal only`);
14762
+ else warn(`could not record the dropped member(s)/size on the batch head: ${git.gitFailureLine(am.stderr)} — they are on this terminal only`);
14626
14763
  }
14627
14764
  for (const b of built.filter((x) => x.regenerated)) {
14628
14765
  print(` ↻ ${b.branch}: combined despite a generated-file overlap — ${b.regenerated.join(', ')} regenerated by .colab/hooks/pre-ship on the combined head (the combined run is the gate)`);
@@ -14644,7 +14781,7 @@ function cmdShipBatch(opts) {
14644
14781
  cleanup();
14645
14782
  if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
14646
14783
  print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
14647
- if (overflow.length) print(` eligible but over the cap (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
14784
+ if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
14648
14785
  print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
14649
14786
  return 3;
14650
14787
  }
@@ -35,6 +35,7 @@ const DESCRIPTOR = '.github/project.yml';
35
35
  const TUNING = Object.freeze({
36
36
  'ship-batch': (doc) => { const r = shipBatch.parseShipBatch(doc); return r.valid ? null : r.reason; },
37
37
  'ship-batch-wait': (doc) => { const r = shipBatch.parseShipBatchWait(doc); return r.valid ? null : r.reason; },
38
+ [shipBatch.STEPS_KEY]: (doc) => { const r = shipBatch.parseShipBatchSteps(doc); return r.valid ? null : r.reason; },
38
39
  'ci-wait-factor': (doc) => { const r = ciProfile.parseFactor(doc); return r.valid ? null : r.reason; },
39
40
  [thresholds.KEY]: (doc) => { const r = thresholds.parseThresholds(doc); return r.problems.length ? r.problems.join('; ') : null; },
40
41
  });
@@ -49,8 +50,8 @@ const AUTHORITY_KEYS = Object.freeze([
49
50
  'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
50
51
  ]);
51
52
 
52
- /** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`). */
53
- const VALUE_RE = /^[A-Za-z0-9._-]+$/;
53
+ /** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`, `2,4,8`). */
54
+ const VALUE_RE = /^[A-Za-z0-9._,-]+$/;
54
55
 
55
56
  /**
56
57
  * `ship-batch` → `{ top: 'ship-batch', sub: null }`; `thresholds.hot-file-count` → `{ top:
@@ -89,7 +90,7 @@ function replaceValue(line, value) {
89
90
  * old }` (`old` is the previous raw value, or null when the key was absent), or `{ problem }`.
90
91
  */
91
92
  function editText(text, keyPath, value) {
92
- if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ -)` };
93
+ if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ , -)` };
93
94
  const src = String(text);
94
95
  const eol = src.endsWith('\n') ? '' : '\n';
95
96
  const lines = src.split('\n');
package/tools/lib/git.js CHANGED
@@ -691,6 +691,30 @@ function ghPrForBranch(repo, branch) {
691
691
  } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
692
692
  }
693
693
 
694
+ /**
695
+ * #584: EVERY open pull request whose head is `branch` — not just the first, as ghPrForBranch
696
+ * returns — so `colab ship` can close each CI-trigger PR its squash left behind. `{ prs }` on
697
+ * success (possibly empty), `{ error }` when the read failed; never conflate the two.
698
+ */
699
+ function ghOpenPrsForBranch(repo, branch) {
700
+ const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
701
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
702
+ try {
703
+ const list = JSON.parse(r.stdout || '[]');
704
+ return { prs: Array.isArray(list) ? list : [] };
705
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
706
+ }
707
+
708
+ /** #584: every open pull request in the repo, for `colab doctor --sync`'s landed-PR listing. */
709
+ function ghOpenPrs(repo) {
710
+ const r = gh(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
711
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
712
+ try {
713
+ const list = JSON.parse(r.stdout || '[]');
714
+ return { prs: Array.isArray(list) ? list : [] };
715
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
716
+ }
717
+
694
718
  /**
695
719
  * #367: the forge's visibility for this repo — "PUBLIC" | "PRIVATE" | "INTERNAL" — or null when it
696
720
  * could not be read (no gh, no GitHub remote, offline). Null is "could not read", never "private":
@@ -1401,5 +1425,5 @@ module.exports = {
1401
1425
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1402
1426
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1403
1427
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1404
- ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,
1428
+ ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
1405
1429
  };
@@ -0,0 +1,58 @@
1
+ 'use strict';
2
+ /**
3
+ * #584: a pull request opened only to obtain branch CI stays open forever once `colab ship`
4
+ * squash-lands its branch — the squash is a NEW commit, so the forge never sees the PR's head land,
5
+ * and nothing else closes it. Measured 2026-10-10: five such PRs open on two repos, all landed, the
6
+ * oldest 15 days old, each reading as unmerged work waiting for review.
7
+ *
8
+ * Pure rules only — tools/colab owns the gh calls. Two rules:
9
+ *
10
+ * 1. Close a PR only when its head commit LANDED: the PR head is the landed branch tip, or an
11
+ * ancestor of it. A PR head carrying commits the ship did NOT include (pushed to the remote
12
+ * branch after the local tip was cut, or from another machine) is KEPT, with a warning — closing
13
+ * it would hide work that is not on trunk.
14
+ * 2. Best-effort. A failed list or close is a warning, never a failed ship: the merge already landed
15
+ * and is pushed, so a non-zero exit here would read as "ship failed" and invite a re-merge.
16
+ */
17
+
18
+ /** The comment a closed PR carries — the same shape as #350's close: where it landed, and why. */
19
+ function landedPrComment({ target, sha, issues }) {
20
+ const nums = (issues || []).map((n) => `#${n}`).join(' ');
21
+ return `Landed on \`${target}\` as ${sha} by \`colab ship\`${nums ? ` (${nums})` : ''}. ` +
22
+ 'The branch was squash-merged, which the forge cannot see as a merge of this PR, so ship closes it (#584).';
23
+ }
24
+
25
+ /**
26
+ * Decide and act on every open PR whose head is the landed branch.
27
+ *
28
+ * prs — the open PRs listed for the branch, as git.ghOpenPrsForBranch returns them:
29
+ * { prs: [{ number, headRefOid, url }] } or { error }
30
+ * headLanded — (oid) => true when that commit is in what landed (tip or ancestor); false otherwise
31
+ * close — (number, comment) => { ok, stderr }
32
+ * comment — the closing comment (landedPrComment)
33
+ * skip — PR numbers already handled by another path (#350's approved review PR)
34
+ *
35
+ * Returns { closed: [n], kept: [{ number, reason }], failed: [{ number, error }], listError }.
36
+ */
37
+ function closeLandedPrs({ prs, headLanded, close, comment, skip = [] }) {
38
+ const out = { closed: [], kept: [], failed: [], listError: null };
39
+ if (!prs || prs.error || !Array.isArray(prs.prs)) { out.listError = (prs && prs.error) || 'could not list open PRs'; return out; }
40
+ const skipSet = new Set(skip.map(Number));
41
+ for (const pr of prs.prs) {
42
+ const number = Number(pr.number);
43
+ if (!Number.isFinite(number) || skipSet.has(number)) continue;
44
+ let landed = false;
45
+ try { landed = !!(pr.headRefOid && headLanded(pr.headRefOid)); } catch (_) { landed = false; }
46
+ if (!landed) {
47
+ out.kept.push({ number, reason: `its head ${String(pr.headRefOid || '?').slice(0, 12)} is not in what landed` });
48
+ continue;
49
+ }
50
+ let r;
51
+ try { r = close(number, comment); } catch (e) { r = { ok: false, stderr: e.message }; }
52
+ if (r && r.ok) out.closed.push(number);
53
+ else out.failed.push({ number, error: ((r && r.stderr) || 'gh pr close failed').split('\n')[0] });
54
+ }
55
+ return out;
56
+ }
57
+
58
+ module.exports = { landedPrComment, closeLandedPrs };
@@ -18,7 +18,11 @@
18
18
  * semantic conflicts need no shared file. The combined run is the gate.
19
19
  */
20
20
 
21
- const MAX_BATCH = 3;
21
+ // The SAFETY ceiling (#557): what any repo may declare, never what it gets. 3 until a red batch had
22
+ // a cheaper exit than N serial cycles; split-and-retry (nextStep's `split`) is that exit, so the
23
+ // ceiling is now 8 — the size from which bisection beats a serial fallback. A repo's own
24
+ // `ship-batch: <N>` is its ceiling; `ship-batch-steps` makes the size adapt below it.
25
+ const MAX_BATCH = 8;
22
26
  const REF_PREFIX = 'ship-batch/';
23
27
  // A concrete ref a `branches:` filter is tested against. Any 7-hex tail works: GitHub's filters see
24
28
  // the literal ref name, and the question is only whether `ship-batch/**` (or a wider glob) admits it.
@@ -26,7 +30,7 @@ const PROBE_REF = `${REF_PREFIX}0000000`;
26
30
  const TRAILER_KEY = 'Ship-Batch';
27
31
 
28
32
  /**
29
- * `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..3 → that
33
+ * `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..MAX_BATCH → that
30
34
  * (a single-digit string reads the same). Anything else — 0, 4, 2.5, true, a word — FAILS CLOSED to
31
35
  * serial, with the reason: a malformed opt-in must never widen what ship does. The audit fails the
32
36
  * same values.
@@ -39,13 +43,105 @@ function parseShipBatch(doc) {
39
43
  const v = doc['ship-batch'];
40
44
  // A digit string is accepted too: the audit's flat reader keeps every scalar a string, and the two
41
45
  // readers must agree on what is valid — a value one accepts and the other refuses is drift.
42
- const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9]$/.test(v.trim()) ? Number(v.trim()) : NaN);
46
+ const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9][0-9]*$/.test(v.trim()) ? Number(v.trim()) : NaN);
43
47
  if (Number.isInteger(n) && n >= 1 && n <= MAX_BATCH) {
44
48
  return { n, declared: true, valid: true, reason: `ship-batch: ${n}` };
45
49
  }
46
50
  return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
47
51
  }
48
52
 
53
+ const STEPS_KEY = 'ship-batch-steps';
54
+
55
+ /**
56
+ * #557: `ship-batch-steps:` from project.yml — the sizes an ADAPTIVE batch walks through, smallest
57
+ * first: grow one step after a green batch, shrink one after a red one. Written `2,4,8` (a YAML flow
58
+ * list `[2, 4, 8]` reads the same). Strictly ascending whole numbers within 1..`ship-batch` — the
59
+ * repo's own ceiling, which stays the largest a batch may ever be.
60
+ *
61
+ * Absent → `steps: null`: the size is fixed at `ship-batch`, today's behaviour exactly. The handbook
62
+ * gives NO default steps — the repo chooses them from its own `colab batch-stats`. Anything malformed
63
+ * FAILS CLOSED to `steps: null`, with the reason: the fixed size the repo already declared, never
64
+ * wider. The audit and the CI templates' descriptor check fail the same values.
65
+ */
66
+ function parseShipBatchSteps(doc) {
67
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, STEPS_KEY);
68
+ if (!has || doc[STEPS_KEY] === null || doc[STEPS_KEY] === undefined) {
69
+ return { steps: null, declared: false, valid: true, reason: `${STEPS_KEY} absent` };
70
+ }
71
+ const v = doc[STEPS_KEY];
72
+ const n = parseShipBatch(doc).n;
73
+ const bad = (why) => ({ steps: null, declared: true, valid: false, reason: `${STEPS_KEY} is ${JSON.stringify(v)}, ${why} (omit for a fixed size)` });
74
+ let parts;
75
+ if (Array.isArray(v)) parts = v.map((x) => String(x).trim());
76
+ else if (typeof v === 'number') parts = [String(v)];
77
+ else if (typeof v === 'string') parts = v.trim().replace(/^\[(.*)\]$/, '$1').split(',').map((x) => x.trim());
78
+ else return bad('expected ascending whole numbers like 2,4,8');
79
+ if (!parts.length || parts.some((x) => !/^[1-9][0-9]*$/.test(x))) return bad('expected ascending whole numbers like 2,4,8');
80
+ const steps = parts.map(Number);
81
+ if (steps.some((x, i) => i > 0 && x <= steps[i - 1])) return bad('expected strictly ascending sizes like 2,4,8');
82
+ if (steps[steps.length - 1] > n) return bad(`expected every size within ship-batch: ${n}, the repo's own ceiling`);
83
+ return { steps, declared: true, valid: true, reason: `${STEPS_KEY}: ${steps.join(',')}` };
84
+ }
85
+
86
+ /**
87
+ * #557: the trailer every batch head carries where steps are declared — the size the build TARGETED
88
+ * (not its fill), plus ` red` when the build is a split half of a red batch:
89
+ *
90
+ * Ship-Batch-Size: <s> built at step s
91
+ * Ship-Batch-Size: <s> red a split half; its parent batch, built at step s, went red
92
+ *
93
+ * It reaches trunk with a landed batch, so the next build reads the lane's last outcome from trunk
94
+ * alone — no batch state in ~/.colab, the same posture as memberTrailer.
95
+ */
96
+ const SIZE_TRAILER_KEY = 'Ship-Batch-Size';
97
+
98
+ function sizeTrailer({ size, red = false }) {
99
+ return `${SIZE_TRAILER_KEY}: ${size}${red ? ' red' : ''}`;
100
+ }
101
+
102
+ /** The LAST `Ship-Batch-Size:` trailer across commit messages → `{ size, red }`, else null. */
103
+ function parseSizeTrailer(messages) {
104
+ let out = null;
105
+ for (const msg of messages || []) {
106
+ for (const line of String(msg || '').split('\n')) {
107
+ const m = new RegExp(`^${SIZE_TRAILER_KEY}:\\s+([1-9][0-9]*)(\\s+red)?\\s*$`).exec(line.trim());
108
+ if (m) out = { size: Number(m[1]), red: !!m[2] };
109
+ }
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /**
115
+ * #557: the size the NEXT batch is built at.
116
+ * steps null (absent or malformed) → n, fixed — today's behaviour
117
+ * no trailer on trunk yet → the smallest step: a lane starts small and earns its width
118
+ * last landed batch green → the smallest step ABOVE its size (the largest step if none)
119
+ * last landed batch a red's half → the largest step BELOW its parent's size (the smallest if none)
120
+ * Never above n: parseShipBatchSteps already refuses a step above it.
121
+ */
122
+ function adaptiveSize({ n, steps, last }) {
123
+ if (!Array.isArray(steps) || !steps.length) return n;
124
+ if (!last || !Number.isFinite(last.size)) return steps[0];
125
+ if (last.red) {
126
+ const below = steps.filter((s) => s < last.size);
127
+ return below.length ? below[below.length - 1] : steps[0];
128
+ }
129
+ const above = steps.filter((s) => s > last.size);
130
+ return above.length ? above[0] : steps[steps.length - 1];
131
+ }
132
+
133
+ /**
134
+ * #557: split a red batch — the members (batch order) that form the FIRST half, tested next on the
135
+ * same base; the rest wait for the next batch. Sequential halves keep one batch per base, so the lane
136
+ * hold, the foreign-batch rule and the rebuild rule all hold unchanged; worst case for one culprit is
137
+ * about 2·log2(k)+1 cycles against 1+k for the serial fallback it replaces.
138
+ */
139
+ function splitHalves(members) {
140
+ const list = Array.isArray(members) ? members : [];
141
+ const cut = Math.ceil(list.length / 2);
142
+ return { first: list.slice(0, cut), held: list.slice(cut) };
143
+ }
144
+
49
145
  const WAIT_KEY = 'ship-batch-wait';
50
146
  const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
147
 
@@ -313,12 +409,19 @@ function combinedVerdict(rows) {
313
409
  * no longer the ones asked for → delete it, then build afresh
314
410
  * build build + push the batch ref (exit 3)
315
411
  * wait-run the combined run is pending or has not appeared (exit 3)
316
- * red-rerun-or-serial combined run red on its FIRST attempt — the caller classifies it (§4): a
317
- * red:infra is re-run once, a red:finding goes serial (exit 4, ref kept)
318
- * red-serial red again after the one re-run — land nothing, serial (exit 4, ref deleted)
412
+ * red-rerun-or-split combined run red on its FIRST attempt, k > 1 members — the caller classifies
413
+ * it (§4): a red:infra is re-run once, a red:finding re-runs this command with
414
+ * `--split` (exit 4, ref kept) (#557)
415
+ * split red after the one re-run, or `--split` on a first-attempt red, k > 1 → rebuild
416
+ * the same ref with the first half of its members (splitHalves); the rest wait
417
+ * for the next batch (exit 3) (#557)
418
+ * red-rerun-or-serial a red batch of ONE on its first attempt: re-run once, or that member goes
419
+ * serial — it cannot split (exit 4, ref kept)
420
+ * red-serial a batch of one red after the re-run (or `--split`) — land nothing, serial
421
+ * (exit 4, ref deleted); that member returns to its implementer
319
422
  * land green → fast-forward trunk if it has not moved
320
423
  */
321
- function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null }) {
424
+ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null, split = false }) {
322
425
  if (!enabled) return { step: 'serial', reason: 'not-enabled' };
323
426
  if (!wired) return { step: 'serial', reason: 'unwired' };
324
427
  if (trunkCi === 'red') return { step: 'serial', reason: 'trunk-red' };
@@ -327,7 +430,13 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
327
430
  if (!trunkNow || !String(trunkNow).startsWith(existing.base7)) return { step: 'rebuild', reason: 'trunk-moved' };
328
431
  if (!existing.matches) return { step: 'rebuild', reason: 'members-changed' };
329
432
  if (!verdict || verdict.state === 'pending' || verdict.state === 'none') return { step: 'wait-run' };
330
- if (verdict.state === 'red') return verdict.attempt >= 2 ? { step: 'red-serial' } : { step: 'red-rerun-or-serial' };
433
+ if (verdict.state === 'red') {
434
+ // #557: a red batch of k > 1 splits instead of going serial. After its one re-run, it splits by
435
+ // itself; on the first attempt the caller has classified it (red:finding → `--split`).
436
+ const k = Array.isArray(existing.members) ? existing.members.length : 1;
437
+ if (verdict.attempt >= 2 || split) return k > 1 ? { step: 'split' } : { step: 'red-serial' };
438
+ return k > 1 ? { step: 'red-rerun-or-split' } : { step: 'red-rerun-or-serial' };
439
+ }
331
440
  return { step: 'land' };
332
441
  }
333
442
  // #562: a batch of ONE is a batch — a lone ready member still lands through the combined run, so
@@ -485,8 +594,8 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
485
594
  }
486
595
 
487
596
  module.exports = {
488
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
489
- parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
597
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, STEPS_KEY, SIZE_TRAILER_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
598
+ parseShipBatch, parseShipBatchWait, parseShipBatchSteps, sizeTrailer, parseSizeTrailer, adaptiveSize, splitHalves, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
490
599
  droppedTrailer, parseDroppedTrailers, appendTrailers,
491
600
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
492
601
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,