@futurelastic/colab-handbook 1.14.0-rc.10 → 1.14.0-rc.12

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
@@ -1497,13 +1497,16 @@ function auditRepoInner(target, ctx) {
1497
1497
  if (!ifl.valid) fail(ifl.reason);
1498
1498
  }
1499
1499
 
1500
- // ---- ci-docs-skip (#570) ----------------------------------------------------
1501
- // Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
1502
- // (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
1503
- // An invalid value fails: the guard reads it as not opted in, so it silently does nothing.
1500
+ // ---- ci-docs-skip (#570, #606) ---------------------------------------------
1501
+ // The docs-only path list (tools/lib/docs-only.js parseCiDocsSkip). ON BY DEFAULT (#606): absent
1502
+ // = on, a list = on with those paths excluded (a change to one is not docs-only), `off` = off.
1503
+ // `colab ship` reads it to decide a docs-only change needs no CI; the CI templates' legacy guard
1504
+ // reads the same list. Reported as the exception list (`[]` when absent), `"off"`, or null when
1505
+ // invalid. An invalid value fails: every reader takes it as "not docs-only", so it silently
1506
+ // opts the repo out.
1504
1507
  {
1505
1508
  const ds = docsOnlyLib.parseCiDocsSkip(cfg);
1506
- info.ciDocsSkip = ds.declared && ds.valid ? ds.exclude : null;
1509
+ info.ciDocsSkip = !ds.valid ? null : ds.on ? ds.exclude : "off";
1507
1510
  if (!ds.valid) fail(ds.reason);
1508
1511
  }
1509
1512
 
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.10"
36
+ "version": "1.14.0-rc.12"
37
37
  }
package/tools/colab CHANGED
@@ -70,6 +70,7 @@ 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 secretScan = require('./lib/secret-scan'); // #606
73
74
  const configSet = require('./lib/config-set'); // #561
74
75
  const cureDiff = require('./lib/cure-diff');
75
76
  const codeowners = require('./lib/codeowners');
@@ -10595,7 +10596,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10595
10596
  }
10596
10597
 
10597
10598
  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]
10598
- colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10599
+ 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]]
10599
10600
 
10600
10601
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10601
10602
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10884,7 +10885,20 @@ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref
10884
10885
  combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
10885
10886
  \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
10886
10887
  'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
10887
- A red batch, or one with no run / not landed past that grace, holds nothing.
10888
+ A red batch, or one with no run / not landed past that grace, holds nothing. A TRUNK RED: cure is never held.
10889
+ SPECULATIVE CHAIN (#605): --onto ship-batch/<sha7> builds the batch on that in-flight batch's HEAD
10890
+ instead of trunk's tip, named ship-batch/<parent-head-sha7> (one batch per base still holds). The chain
10891
+ is read from ls-remote alone: a ref's parent is the ref whose head its name starts with, and it is kept
10892
+ 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,
10893
+ or whose root trunk moved past, is deleted by the next --batch call (its run cancelled if still going).
10894
+ - refused (1): the named ref has no combined run in flight or green, is not rooted at trunk's tip,
10895
+ or is already ${shipBatch.MAX_CHAIN_DEPTH} deep; a member the chain below already carries does not join (✗, the rest go on);
10896
+ - lands in order: green and its parent not landed yet → ⏸ BATCH-CHAINED (exit 3); once trunk's tip IS
10897
+ the parent's head, the same command (with or without --onto) lands it — no second build, no second run;
10898
+ - declined (4): the parent is red, gone, or trunk moved some other way — the child is deleted, → SERIAL.
10899
+ Every ref of a chain rooted at trunk's tip holds the lane, exactly as one batch does.
10900
+ --dry --json: one JSON document on stdout ({ batch: { ref, parentRef, rootSha, base, depth, step, exit,
10901
+ members: [{ branch, sha, eligible, inBatch, why }] } }), the prose on stderr.
10888
10902
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
10889
10903
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
10890
10904
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
@@ -11457,6 +11471,13 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
11457
11471
  via = `${trunk} (by commit — the branch-filtered read was empty)`;
11458
11472
  }
11459
11473
  }
11474
+ // #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
11475
+ // docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
11476
+ // newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
11477
+ if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
11478
+ const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
11479
+ if (door) return door;
11480
+ }
11460
11481
  const at = `${via}@${shortSha(run.sha)}`;
11461
11482
  let verdict = classifyCiRun(repoAbs, run, at);
11462
11483
  // #413: still no run anywhere at a trunk sha committed minutes ago — the run may not exist YET
@@ -11635,6 +11656,75 @@ function baseCiAdvisory(repoAbs, gh, base, branch) {
11635
11656
  };
11636
11657
  }
11637
11658
 
11659
+ /**
11660
+ * #606: trunk's tip is docs-only and has no finished run — read trunk CI at the newest first-parent
11661
+ * ancestor that is NOT docs-only (tools/lib/docs-only.js commitChanges, narrowed by trunk's
11662
+ * `ci-docs-skip`). Returns a readCiVerdict result, or null when the door does not apply: the repo
11663
+ * declared `ci-docs-skip: off` (or an invalid value), the tip is not local or not docs-only, no code
11664
+ * commit within DOCS_TIP_WALK commits, or that commit's runs are unreadable. A null keeps every
11665
+ * existing reading of the tip unchanged — the door only ever answers for a docs-only tip.
11666
+ */
11667
+ const DOCS_TIP_WALK = 50;
11668
+ function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
11669
+ if (!tipSha) return null;
11670
+ const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
11671
+ if (!setting.on) return null;
11672
+ const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
11673
+ if (!list.ok) return null;
11674
+ let skipped = 0;
11675
+ let code = null;
11676
+ for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
11677
+ const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
11678
+ if (!c.docsOnly) { code = sha; break; }
11679
+ skipped++;
11680
+ }
11681
+ if (!code || skipped === 0) return null;
11682
+ const run = git.ghRunForCommitAnyRef(repoAbs, code, undefined, readOpts);
11683
+ if (!run) return null;
11684
+ const at = `${trunk}@${shortSha(code)}`;
11685
+ const v = classifyCiRun(repoAbs, run, at);
11686
+ 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 — `;
11687
+ const verdict = { ...v, detail: note + v.detail, docsOnlyTip: { tip: tipSha, read: code, skipped } };
11688
+ return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
11689
+ }
11690
+
11691
+ /**
11692
+ * #606: is this branch DOCS-ONLY for CI purposes — so `colab ship` lands it without waiting for CI?
11693
+ * tools/lib/docs-only.js shipDocsOnly (the #345 rule, narrowed by `ci-docs-skip`, off by `off`),
11694
+ * measured on the ref ship would land. When it applies, the secret check runs too
11695
+ * (tools/lib/secret-scan.js) — the suite's own secret scan may never see this change.
11696
+ * Returns `{ applies, files, reason, scan }`; `scan` only when `applies`.
11697
+ */
11698
+ function shipDocsOnlyCi(repoAbs, doc, target, branch) {
11699
+ const ref = shipRefFor(repoAbs, branch);
11700
+ const d = docsOnly.shipDocsOnly(git, repoAbs, target, ref, doc);
11701
+ if (!d.docsOnly) return { applies: false, files: d.files, reason: d.reason, scan: null };
11702
+ return { applies: true, files: d.files, reason: d.reason, scan: secretScan.scanBranch(git, repoAbs, target, ref) };
11703
+ }
11704
+
11705
+ /** #606: the 🚢 comment's evidence clause for a docs-only ship — files, and the trunk sha CI was read at. */
11706
+ function docsOnlyEvidence(dc, ci) {
11707
+ if (!dc || !dc.applies) return '';
11708
+ const tip = ci && ci.docsOnlyTip;
11709
+ 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';
11710
+ return ` — docs-only: CI not required (${dc.files} files)${read}; secret check clean`;
11711
+ }
11712
+
11713
+ /**
11714
+ * #606: the branch-run row for a docs-only branch, in place of #395's stale-base row. CI is not
11715
+ * required, so no run, a run in flight, or a run measured on an older base is fine — but a run that
11716
+ * EXISTS at the pushed head and finished red still refuses: ship never overrides a red verdict.
11717
+ */
11718
+ function docsOnlyBranchRow(dc, stale) {
11719
+ const run = stale && stale.run;
11720
+ const red = !!run && run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
11721
+ if (red) {
11722
+ return { ok: false, class: HUMAN_GATED,
11723
+ 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)` };
11724
+ }
11725
+ 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'})` };
11726
+ }
11727
+
11638
11728
  /**
11639
11729
  * #395: does the branch's CI verdict cover the CURRENT `base`? A PRECONDITION, unlike
11640
11730
  * `baseCiAdvisory` above: serial ship syncs the base in locally (B0) and squashes without the synced
@@ -11663,7 +11753,8 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
11663
11753
  if (contains === false && git.git(['diff', '--quiet', `${baseTip}...${headSha}`], repoAbs).code === 0) contains = 'no-change';
11664
11754
  }
11665
11755
  if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
11666
- return staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh });
11756
+ // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
11757
+ return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh }), run, headSha };
11667
11758
  }
11668
11759
 
11669
11760
  /**
@@ -12468,7 +12559,14 @@ function cmdShipDryJson(opts) {
12468
12559
  // read is exempt: the batch grades the COMBINED head (trunk + every member), which is exactly the
12469
12560
  // re-run this row demands of a serial land, so a member behind trunk is the ordinary case there.
12470
12561
  const staleJson = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
12471
- if (opts._batchMember) {
12562
+ // #606: a docs-only branch needs no CI of its own — its row replaces the stale-base one, and the
12563
+ // secret check stands in for the suite's secret scan. Same producers as the prose path.
12564
+ const docsCiJson = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
12565
+ if (docsCiJson.applies) {
12566
+ const row = docsOnlyBranchRow(docsCiJson, staleJson);
12567
+ checks.push({ name: 'branch CI (docs-only, #606)', ok: row.ok, class: row.class, verdict: staleJson.verdict, detail: row.detail });
12568
+ checks.push({ name: 'docs-only secret check (#606)', ok: docsCiJson.scan.ok, class: docsCiJson.scan.ok ? null : HUMAN_GATED, detail: docsCiJson.scan.reason });
12569
+ } else if (opts._batchMember) {
12472
12570
  checks.push({ name: 'branch run contains current base (#395)', ok: true, class: null, verdict: staleJson.verdict,
12473
12571
  detail: `batch member — the combined run grades it (${staleJson.detail})` });
12474
12572
  } else {
@@ -12560,7 +12658,7 @@ function cmdShipDryJson(opts) {
12560
12658
  // lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
12561
12659
  // Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
12562
12660
  if (!dryMode.evidenceClose && !opts._batchMember) {
12563
- const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
12661
+ const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResultJson);
12564
12662
  if (laneJson) {
12565
12663
  checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
12566
12664
  detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
@@ -13435,7 +13533,7 @@ function shipRefFor(repoAbs, branch) {
13435
13533
 
13436
13534
  function cmdShip(argv) {
13437
13535
  const opts = parseArgs(argv, {
13438
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
13536
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff', '--onto': 'onto' },
13439
13537
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
13440
13538
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
13441
13539
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -13455,6 +13553,9 @@ function cmdShip(argv) {
13455
13553
  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`)');
13456
13554
  if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
13457
13555
  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');
13556
+ if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
13557
+ if (opts.onto && !shipBatch.parseBatchRef(opts.onto)) throw new UserError(`--onto ${opts.onto}: not a batch ref — expected ship-batch/<sha7> (#605)`);
13558
+ if (opts.batch && opts.json) return cmdShipBatchJson(opts); // #605: the batch's facts as JSON, prose on stderr
13458
13559
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
13459
13560
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
13460
13561
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -13646,7 +13747,18 @@ function cmdShip(argv) {
13646
13747
  // #395: the branch's run must have been measured on a head that contains the base's CURRENT tip —
13647
13748
  // B0 below syncs locally and never re-runs CI, so this is the only place a stale verdict is caught.
13648
13749
  const staleResult = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
13649
- checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13750
+ // #606: a docs-only branch needs no CI of its own — this row replaces the stale-base one (a red
13751
+ // run that exists still refuses), and the secret check stands in for the suite's secret scan.
13752
+ const docsCi = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
13753
+ let docsRowOk = true;
13754
+ if (docsCi.applies) {
13755
+ const row = docsOnlyBranchRow(docsCi, staleResult);
13756
+ checks.push([row.ok ? '✓' : '✗', 'branch CI (docs-only, #606)', row.detail]);
13757
+ checks.push([docsCi.scan.ok ? '✓' : '✗', 'docs-only secret check (#606)', docsCi.scan.reason]);
13758
+ docsRowOk = row.ok && docsCi.scan.ok;
13759
+ } else {
13760
+ checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13761
+ }
13650
13762
 
13651
13763
  // #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
13652
13764
  // taken below once every real precondition has passed, so it is the ONLY thing between the branch
@@ -13657,7 +13769,7 @@ function cmdShip(argv) {
13657
13769
 
13658
13770
  // #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
13659
13771
  // hold is not a failed precondition — it is a pause, taken below once every real one has passed.
13660
- const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
13772
+ const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult);
13661
13773
  if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
13662
13774
  for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
13663
13775
 
@@ -13672,7 +13784,7 @@ function cmdShip(argv) {
13672
13784
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
13673
13785
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
13674
13786
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
13675
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && staleResult.ok && coreOk && recOk;
13787
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk;
13676
13788
 
13677
13789
  // ---- report the table ----
13678
13790
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -14037,6 +14149,18 @@ function cmdShip(argv) {
14037
14149
  return 1;
14038
14150
  }
14039
14151
  }
14152
+ // #606: the same for the docs-only CI path — B0 may have made the change something CI must see,
14153
+ // or added a line the secret check has not read. Re-measured on the synced branch.
14154
+ if (docsCi.applies) {
14155
+ const again = docsOnly.shipDocsOnly(git, repoAbs, mergeRef, sess.branch, doc);
14156
+ const rescan = again.docsOnly ? secretScan.scanBranch(git, repoAbs, mergeRef, sess.branch) : null;
14157
+ if (!again.docsOnly || !rescan.ok) {
14158
+ cleanupEphemeral();
14159
+ 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`);
14160
+ 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`);
14161
+ return 1;
14162
+ }
14163
+ }
14040
14164
  if (autonomyGate.via === 'tuning') {
14041
14165
  const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
14042
14166
  if (!again.tuning) {
@@ -14110,7 +14234,7 @@ function cmdShip(argv) {
14110
14234
  }
14111
14235
  // #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
14112
14236
  // built in that window is exactly as live as one the table saw.
14113
- const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
14237
+ const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciCureForTrailer ? { cureVerdict: ciCureForTrailer } : null) : null;
14114
14238
  if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
14115
14239
  // WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
14116
14240
  // (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
@@ -14473,7 +14597,7 @@ function cmdShip(argv) {
14473
14597
  // same block, and re-assigning the collector here would silently discard them.
14474
14598
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
14475
14599
  skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14476
- evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
14600
+ evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
14477
14601
 
14478
14602
  print('');
14479
14603
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -14684,21 +14808,29 @@ function shipDryJsonReport(opts) {
14684
14808
  * Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
14685
14809
  * trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
14686
14810
  */
14687
- function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14811
+ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
14688
14812
  if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
14813
+ // #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
14814
+ // way out; no batch can land on a red trunk anyway.
14815
+ if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
14816
+ return { held: false, released: [], detail: 'a TRUNK RED: cure is never held by a batch (#605)' };
14817
+ }
14689
14818
  const remote = git.remoteFor(repoAbs);
14690
14819
  const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
14691
14820
  if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
14692
14821
  const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
14693
14822
  const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
14694
- const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
14695
- .filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
14823
+ // #605: the lane holder is the CHAIN rooted at trunk's tip — a batch built --onto another batch's head
14824
+ // reaches trunk only through it, so its run holds the lane exactly as the root's does.
14825
+ const refs = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) })).filter((x) => x.parsed);
14826
+ const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
14827
+ const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
14696
14828
  const batches = atTip.map((x) => {
14697
14829
  const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
14698
14830
  let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
14699
14831
  if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
14700
14832
  const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
14701
- return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
14833
+ return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
14702
14834
  builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
14703
14835
  });
14704
14836
  const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
@@ -14715,8 +14847,32 @@ function printBatchLanePause(lane, trunk) {
14715
14847
  print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
14716
14848
  }
14717
14849
 
14850
+ /**
14851
+ * #605: `colab ship --batch … --dry --json` — the same single step as the prose path (it IS the prose
14852
+ * path, with its prose moved to stderr), plus one JSON document on stdout carrying the facts a caller
14853
+ * keys on: the batch ref, the ref it is chained onto, the trunk sha its chain is rooted at, the step
14854
+ * taken and the exit class, and one row per member. A caller never parses prose for the chain.
14855
+ */
14856
+ function cmdShipBatchJson(opts) {
14857
+ const batch = { trunk: null, trunkSha: null, ref: null, parentRef: null, rootSha: null, base: null, depth: null, step: null, exit: null, error: null, members: [] };
14858
+ const was = PRINT_TO_STDERR;
14859
+ PRINT_TO_STDERR = true;
14860
+ let code;
14861
+ try { code = cmdShipBatch({ ...opts, _json: batch }); }
14862
+ catch (e) {
14863
+ if (!(e instanceof UserError)) throw e;
14864
+ process.stderr.write(`✗ ${e.message}\n`);
14865
+ batch.error = e.message;
14866
+ batch.step = batch.step || 'refused';
14867
+ code = 1;
14868
+ } finally { PRINT_TO_STDERR = was; }
14869
+ batch.exit = code;
14870
+ process.stdout.write(`${JSON.stringify({ batch }, null, 2)}\n`);
14871
+ return code;
14872
+ }
14873
+
14718
14874
  function cmdShipBatch(opts) {
14719
- for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
14875
+ for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ...(opts._json ? [] : [['json', '--json']])]) {
14720
14876
  if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
14721
14877
  }
14722
14878
  const repoAbs = resolveRepo(opts);
@@ -14730,7 +14886,12 @@ function cmdShipBatch(opts) {
14730
14886
  const members = entries.members;
14731
14887
  const handoffs = entries.handoffs;
14732
14888
  if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
14889
+ const J = opts._json || {}; // #605: the --dry --json report, filled as the facts are read
14890
+ J.trunk = trunk;
14733
14891
  const serial = (why, list = members) => {
14892
+ J.step = J.step && J.step !== 'build' ? J.step : 'serial';
14893
+ J.reason = why;
14894
+ if (!J.members || !J.members.length) J.members = list.map((b) => ({ branch: b, sha: null, eligible: null, inBatch: false, why }));
14734
14895
  print(`✗ ship-batch: ${why}`);
14735
14896
  print(shipBatch.serialLine(list));
14736
14897
  return 4;
@@ -14791,6 +14952,7 @@ function cmdShipBatch(opts) {
14791
14952
  const lsTrunk = git.git(['ls-remote', remote, `refs/heads/${trunk}`], repoAbs);
14792
14953
  const trunkNow = lsTrunk.ok ? (lsTrunk.stdout.split('\t')[0] || '').trim() : '';
14793
14954
  if (!trunkNow) throw new UserError(`could not read ${trunk} on ${remote}`);
14955
+ J.trunkSha = trunkNow;
14794
14956
  const lsBatch = git.git(['ls-remote', remote, 'refs/heads/ship-batch/*'], repoAbs);
14795
14957
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
14796
14958
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
@@ -14802,14 +14964,102 @@ function cmdShipBatch(opts) {
14802
14964
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
14803
14965
  return d.ok;
14804
14966
  };
14805
- for (const b of batchRefs.filter((x) => !trunkNow.startsWith(x.parsed.base7))) {
14806
- print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
14967
+ // #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
14968
+ // ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
14969
+ // whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
14970
+ // is exactly the old sweep: every ref not built on trunk's tip goes.
14971
+ const chains = shipBatch.batchChains({ refs: batchRefs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
14972
+ const carriedBy = (ref, from, sha) => {
14973
+ const lg = git.git(['log', '--format=%B%x00', `${from}..${sha}`], repoAbs);
14974
+ return shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === ref).reverse();
14975
+ };
14976
+ const swept = [];
14977
+ for (const b of batchRefs.filter((x) => !chains.get(x.parsed.ref).rooted)) {
14978
+ const c = chains.get(b.parsed.ref);
14979
+ // A ref built on a head trunk never reached (an orphaned chain link) may still have its run going;
14980
+ // nothing can ever land it, so cancel that run. A ref on an OLD trunk tip is today's case, untouched.
14981
+ const baseFull = git.git(['rev-parse', '--verify', '-q', `${b.parsed.base7}^{commit}`], repoAbs);
14982
+ const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
14983
+ if (offTrunk) {
14984
+ print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
14985
+ for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
14986
+ if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
14987
+ const cx = git.ghRunCancel(repoAbs, r.databaseId);
14988
+ if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
14989
+ }
14990
+ } else {
14991
+ print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
14992
+ }
14993
+ swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
14807
14994
  deleteRef(b.parsed.ref);
14808
14995
  }
14809
- const atBase = batchRefs.find((x) => trunkNow.startsWith(x.parsed.base7)) || null;
14996
+ const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
14997
+ // Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
14998
+ const carriedByChain = (sha) => new Map(shipBatch.parseMemberTrailers((() => {
14999
+ const lg = git.git(['log', '--format=%B%x00', `${trunkNow}..${sha}`], repoAbs);
15000
+ return lg.ok ? lg.stdout.split('\0') : [];
15001
+ })()).map((m) => [m.branch, m.ref]));
15002
+
15003
+ // #605: --onto <ship-batch ref> builds on that ref's HEAD instead of trunk's tip. `base` is what the
15004
+ // batch sits on from here on; without --onto it is trunk's tip, and nothing below changes.
15005
+ let base = trunkNow;
15006
+ let parent = null; // { ref, sha, chain, verdict } while the parent has not landed
15007
+ if (opts.onto) {
15008
+ const want = shipBatch.parseBatchRef(opts.onto).ref;
15009
+ const p = batchRefs.find((x) => x.parsed.ref === want) || null;
15010
+ const ours = swept.find((x) => x.members.some((m) => members.includes(m.branch)));
15011
+ if (p && p.sha === trunkNow) {
15012
+ print(` ${want} has landed — ${trunk} is at its head ${shortSha(trunkNow)}; this batch sits on ${trunk}'s tip`);
15013
+ } else if (!p || !chains.get(want).rooted) {
15014
+ if (ours) {
15015
+ 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.`);
15016
+ J.step = 'chained-decline';
15017
+ 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));
15018
+ }
15019
+ // The parent landed and its lander deleted the ref: our batch (if staged) now sits on trunk's tip.
15020
+ const atTip = rooted.find((x) => trunkNow.startsWith(x.parsed.base7));
15021
+ const landedParent = !p && atTip && carriedBy(atTip.parsed.ref, trunkNow, atTip.sha).some((m) => members.includes(m.branch));
15022
+ if (!landedParent && p) {
15023
+ throw new UserError(`--onto ${want}: it is not rooted at ${trunk}'s tip (${chains.get(want).why}) — build on ${trunk} instead (drop --onto)`);
15024
+ }
15025
+ if (!landedParent) {
15026
+ // ls-remote cannot tell "never existed" from "discarded" or "trunk moved some other way" — and
15027
+ // for the last two the issue's rule is a decline. So a missing parent declines: nothing of
15028
+ // this chain can land in order, and the members go back to the queue (#605).
15029
+ J.step = 'chained-decline';
15030
+ print(`✗ ship-batch: --onto ${want}: no such batch ref on ${remote} — it was discarded, landed under other members, or never existed.`);
15031
+ return serial(`nothing to chain onto — build on ${trunk} instead (the same command without --onto)`);
15032
+ }
15033
+ print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
15034
+ } else {
15035
+ const pc = chains.get(want);
15036
+ const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
15037
+ const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
15038
+ if (verdict.state === 'red') {
15039
+ if (child) {
15040
+ const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
15041
+ 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.`);
15042
+ deleteRef(child.parsed.ref);
15043
+ J.step = 'chained-decline';
15044
+ return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
15045
+ }
15046
+ throw new UserError(`--onto ${want}: its combined run is red (${verdict.why}) — nothing to chain onto; build on ${trunk} instead (drop --onto)`);
15047
+ }
15048
+ if (verdict.state === 'none' && !child) {
15049
+ 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`);
15050
+ }
15051
+ if (!child && pc.depth >= shipBatch.MAX_CHAIN_DEPTH) {
15052
+ 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`);
15053
+ }
15054
+ base = p.sha;
15055
+ parent = { ref: want, sha: p.sha, chain: pc, verdict };
15056
+ }
15057
+ }
15058
+ Object.assign(J, { base, parentRef: parent ? parent.ref : null, rootSha: trunkNow, depth: parent ? parent.chain.depth + 1 : 1, ref: shipBatch.batchRefName(base) });
15059
+ const atBase = rooted.find((x) => (!parent || x.parsed.ref !== parent.ref) && base.startsWith(x.parsed.base7)) || null;
14810
15060
  let existing = null;
14811
15061
  if (atBase) {
14812
- const log = git.git(['log', '--format=%B%x00', `${trunkNow}..${atBase.sha}`], repoAbs);
15062
+ const log = git.git(['log', '--format=%B%x00', `${base}..${atBase.sha}`], repoAbs);
14813
15063
  const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
14814
15064
  const foreign = inBatch.filter((m) => !members.includes(m.branch));
14815
15065
  // #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
@@ -14839,7 +15089,10 @@ function cmdShipBatch(opts) {
14839
15089
  }
14840
15090
  }
14841
15091
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14842
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
15092
+ // #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
15093
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
15094
+ J.step = step.step;
15095
+ if (existing) J.members = existing.members.map((m) => ({ branch: m.branch, sha: m.sha, eligible: true, inBatch: true, why: `staged in ${existing.ref}` }));
14843
15096
  if (opts.split && !(verdict && verdict.state === 'red')) {
14844
15097
  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)`);
14845
15098
  }
@@ -14888,15 +15141,33 @@ function cmdShipBatch(opts) {
14888
15141
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
14889
15142
  return 4;
14890
15143
  }
15144
+ if (step.step === 'land' && parent) {
15145
+ // #605: land in order — only once trunk's tip IS the parent's head. Until then the parent is in
15146
+ // flight (wait, exit 3); a parent that is red will never land at that sha (delete, exit 4).
15147
+ const ls = shipBatch.chainedLandStep({ parent: parent.chain, parentVerdict: parent.verdict });
15148
+ J.step = ls.step === 'wait' ? 'chained-wait' : 'chained-decline';
15149
+ J.reason = ls.why;
15150
+ if (ls.step === 'wait') {
15151
+ print(`⏸ BATCH-CHAINED ${existing.ref}@${shortSha(existing.sha)} — combined run green; it lands after ${parent.ref}: ${ls.why}. Nothing landed.`);
15152
+ print(` Wait for ${parent.ref} to land (bounded, B1a), then run this command again — it lands with no second run.`);
15153
+ return 3;
15154
+ }
15155
+ 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.`);
15156
+ deleteRef(existing.ref);
15157
+ return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
15158
+ }
14891
15159
  if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
14892
15160
 
14893
15161
  // ---- (d) pick the members — each through its OWN ship gates ----
14894
15162
  const st = state.loadState();
14895
15163
  const evaluated = [];
15164
+ // #605: a member the chain below already carries lands with that batch — it never joins a second one.
15165
+ const inChain = parent ? carriedByChain(parent.sha) : new Map();
14896
15166
  for (const b of members) {
14897
15167
  const refs = git.branchRefs(repoAbs, b, remote);
14898
15168
  let why = null, report = null, ciClass = null, files = [];
14899
15169
  if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
15170
+ else if (inChain.has(b)) why = `already in ${inChain.get(b)} — it lands with that batch, not this one`;
14900
15171
  else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
14901
15172
  if (!why) {
14902
15173
  // #591: a hand-off member is read through the SAME door a single --handoff ship uses
@@ -14929,12 +15200,13 @@ function cmdShipBatch(opts) {
14929
15200
  return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
14930
15201
  })()
14931
15202
  : shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
14932
- 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]' : ''}`);
15203
+ 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]' : ''}`);
14933
15204
  print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
14934
15205
  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']));
14935
15206
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
15207
+ J.members = evaluated.map((e) => ({ branch: e.branch, sha: e.sha || null, eligible: e.ok, inBatch: selected.includes(e), why: e.why }));
14936
15208
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14937
- if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
15209
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf && !parent) {
14938
15210
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14939
15211
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14940
15212
  const lone = selected[0];
@@ -14953,10 +15225,11 @@ function cmdShipBatch(opts) {
14953
15225
  if (step.step === 'serial') return serial('no member can join — each one above says why');
14954
15226
 
14955
15227
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14956
- const ref = shipBatch.batchRefName(trunkNow);
15228
+ // #605: on a chain, the batch is built on the parent's head and named after it — one batch per base.
15229
+ const ref = shipBatch.batchRefName(base);
14957
15230
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-ship-batch-'));
14958
- const add = git.git(['worktree', 'add', '--detach', dir, trunkNow], repoAbs);
14959
- 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)}`); }
15231
+ const add = git.git(['worktree', 'add', '--detach', dir, base], repoAbs);
15232
+ 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)}`); }
14960
15233
  const cleanup = () => git.git(['worktree', 'remove', '--force', dir], repoAbs);
14961
15234
  const machineLine = shipMachineTrailerDecision(repoAbs, doc).line;
14962
15235
  const built = [];
@@ -15024,6 +15297,8 @@ function cmdShipBatch(opts) {
15024
15297
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
15025
15298
  }
15026
15299
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
15300
+ for (const d of dropped) Object.assign(J.members.find((r) => r.branch === d.branch) || {}, { inBatch: false, why: d.why });
15301
+ J.step = 'build';
15027
15302
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
15028
15303
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
15029
15304
  // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
@@ -15049,8 +15324,10 @@ function cmdShipBatch(opts) {
15049
15324
  }
15050
15325
  if (opts.dry) {
15051
15326
  cleanup();
15052
- print(`→ READY: would push ${ref} = ${shortSha(trunkNow)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15053
- print(' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15327
+ print(`→ READY: would push ${ref} = ${shortSha(base)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15328
+ print(parent
15329
+ ? ` then wait on ONE combined run, and fast-forward trunk to it only once ${parent.ref} has landed at ${shortSha(parent.sha)} (#605).`
15330
+ : ' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15054
15331
  if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
15055
15332
  return 0;
15056
15333
  }
@@ -15058,7 +15335,7 @@ function cmdShipBatch(opts) {
15058
15335
  const push = git.run('git', ['push', '--force', remote, `${head}:refs/heads/${ref}`], { cwd: repoAbs });
15059
15336
  cleanup();
15060
15337
  if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
15061
- print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
15338
+ 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` : ''}`);
15062
15339
  if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
15063
15340
  print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
15064
15341
  return 3;
@@ -16854,7 +17131,9 @@ re-running install.sh; \`colab update\` reports it when it is behind. \`colab --
16854
17131
  which of the two you are talking to.
16855
17132
  `;
16856
17133
 
16857
- function print(s) { process.stdout.write(s.endsWith('\n') ? s : s + '\n'); return 0; }
17134
+ // #605: `ship --batch --dry --json` keeps stdout for its one JSON document; the prose goes to stderr.
17135
+ let PRINT_TO_STDERR = false;
17136
+ function print(s) { (PRINT_TO_STDERR ? process.stderr : process.stdout).write(s.endsWith('\n') ? s : s + '\n'); return 0; }
16858
17137
  function warn(s) { process.stderr.write(`! ${s}\n`); }
16859
17138
  /**
16860
17139
  * `colab ship` sets this to an array while it runs B3 (worktree teardown) through B4 (per-issue
@@ -8,15 +8,33 @@
8
8
  * caller. Nothing here takes a list, a flag, an env var or a project.yml field. The allowlist and the
9
9
  * exclusions below are constants, so widening them is a handbook change reviewed in a commit.
10
10
  *
11
- * Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary, a
12
- * symlink, a submodule pointer. A false "no" costs a human click. A false "yes" merges code nobody
13
- * approved.
11
+ * Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary (other
12
+ * than a design artifact under `docs/`, below), a symlink, a submodule pointer. A false "no" costs a
13
+ * human click. A false "yes" merges code nobody approved.
14
+ *
15
+ * #606: the same rule also decides when `colab ship` lands a change WITHOUT WAITING FOR CI
16
+ * (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
17
+ * widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
18
+ * `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
14
19
  */
15
20
 
16
21
  /** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
17
22
  const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
18
23
  /** A path under this top-level directory counts as documentation whatever its extension. */
19
24
  const DOCS_DIR = 'docs/';
25
+ /**
26
+ * #606: a BINARY under `docs/` with one of these extensions is a design artifact (a mockup, a
27
+ * diagram, a printed spec) and counts as documentation. Case-insensitive (`Mock.PNG` matches). Any
28
+ * other binary under `docs/`, and every binary outside it, is still not docs-only.
29
+ */
30
+ const DOCS_BINARY_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.pdf']);
31
+ function docsBinaryOk(p) {
32
+ const s = String(p);
33
+ if (!s.startsWith(DOCS_DIR)) return false;
34
+ const base = s.slice(s.lastIndexOf('/') + 1);
35
+ const dot = base.lastIndexOf('.');
36
+ return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
37
+ }
20
38
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
21
39
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
22
40
  /**
@@ -77,15 +95,18 @@ function pathReason(p) {
77
95
  * Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
78
96
  * `reason` is one line for a human, set on both outcomes.
79
97
  */
80
- function classify(entries) {
98
+ function classify(entries, { exclude = [] } = {}) {
81
99
  const paths = new Map();
82
100
  for (const e of entries || []) {
83
101
  const why = [];
84
102
  const nameWhy = pathReason(e.path);
85
103
  if (nameWhy) why.push(nameWhy);
104
+ // #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
105
+ const listed = excludedBy(e.path, exclude);
106
+ if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
86
107
  if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
87
108
  if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
88
- if (e.binary) why.push('binary change');
109
+ if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
89
110
  const prev = paths.get(e.path) || [];
90
111
  paths.set(e.path, [...new Set([...prev, ...why])]);
91
112
  }
@@ -101,6 +122,12 @@ function classify(entries) {
101
122
  return { docsOnly: true, files, offenders: [], reason: `docs-only (${files} files)` };
102
123
  }
103
124
 
125
+ /** The `ci-docs-skip` member `p` is, or sits under — a path prefix, never a string prefix. */
126
+ function excludedBy(p, exclude) {
127
+ const s = String(p);
128
+ return (exclude || []).find((x) => s === x || s.startsWith(`${x}/`)) || null;
129
+ }
130
+
104
131
  /**
105
132
  * Parse `git diff --raw -z --no-renames --no-abbrev` output into
106
133
  * `[{ path, oldMode, newMode, oldSha, newSha, status }]`. The sha/status fields are additive
@@ -151,10 +178,30 @@ function readEntries(git, repo, cmd, range) {
151
178
  * The branch shape: what `branch` changes relative to its merge base with `base` — the same three-dot
152
179
  * diff the squash would land.
153
180
  */
154
- function branchChanges(git, repo, base, branch) {
181
+ function branchChanges(git, repo, base, branch, opts = {}) {
155
182
  const entries = readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
156
183
  if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read the diff ${base}...${branch}` };
157
- return classify(entries);
184
+ return classify(entries, opts);
185
+ }
186
+
187
+ /** One commit's own change (against its parent(s), `diff-tree -m`) — the shape a trunk squash has. */
188
+ function commitChanges(git, repo, sha, opts = {}) {
189
+ const entries = readEntries(git, repo, 'diff-tree', [sha]);
190
+ if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read commit ${String(sha).slice(0, 7)}` };
191
+ return classify(entries, opts);
192
+ }
193
+
194
+ /**
195
+ * #606: does `colab ship` treat this branch as needing no CI? The SAME classification as the
196
+ * autonomy exception (#345), narrowed by the repo's `ci-docs-skip` list — a path the suite reads is
197
+ * documentation but still needs CI — and switched off entirely by `ci-docs-skip: off`. An invalid
198
+ * value reads as off (every reader takes doubt as "CI required"); the audit fails it.
199
+ * Returns the classify() shape plus `{ setting }` (parseCiDocsSkip's verdict).
200
+ */
201
+ function shipDocsOnly(git, repo, base, branch, doc) {
202
+ const setting = parseCiDocsSkip(doc);
203
+ if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
204
+ return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
158
205
  }
159
206
 
160
207
  /**
@@ -179,24 +226,32 @@ function directChanges(git, repo, trunk, since) {
179
226
  }
180
227
 
181
228
  /**
182
- * #570: `ci-docs-skip:` in project.yml — the opt-in to the CI templates' docs-only mode. Absent (or
183
- * null) = off. A list = on; each member is a repo path whose changes always run the suite even though
184
- * this module calls them documentation (`docs/api/` feeding a generator). `[]` = on, nothing excluded.
229
+ * #570/#606: `ci-docs-skip:` in project.yml — which changes `colab ship` may land without waiting for
230
+ * CI (#606), and the paths the CI templates' legacy guard (#570) excludes. ON BY DEFAULT for ship:
231
+ * absent = on, nothing excluded. A list = on, and each member is a repo path whose changes always run
232
+ * the suite even though this module calls them documentation (`docs/api/` feeding a generator, a
233
+ * README a link checker reads). `[]` = on, nothing excluded. `off` = the one opt-out, for a repo whose
234
+ * suite reads most of its docs (YAML 1.1 readers turn a bare `off` into boolean false; both spell it).
185
235
  *
186
- * The CI guard parses the same shape in shell and reads anything else as "not opted in" — the
187
- * stricter direction — so an invalid value here is a finding: a declaration that silently does
188
- * nothing. Members are plain paths (the guard matches `p == x` or `p` under `x/`): no glob, no `..`
189
- * or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
236
+ * The legacy CI guard parses the same list in shell, but stays opt-in until its follow-up removes it:
237
+ * there `off` and absent both mean "run the full suite". Both readers take anything else — an empty
238
+ * `ci-docs-skip:` included — as "CI required", the stricter direction. So an invalid value here is a finding:
239
+ * a declaration that silently opts the repo out. Members are plain paths (the guard matches `p == x`
240
+ * or `p` under `x/`): no glob, no `..` or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
190
241
  */
191
242
  const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
192
243
  function parseCiDocsSkip(doc) {
193
244
  const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
194
- const v = has ? doc[CI_DOCS_SKIP_KEY] : null;
195
- if (v === null || v === undefined) {
196
- return { declared: false, valid: true, on: false, exclude: null, reason: 'ci-docs-skip absent — a docs-only change runs the full CI suite (#570)' };
245
+ if (!has) {
246
+ return { declared: false, valid: true, on: true, exclude: [], reason: 'ci-docs-skip absent — on by default (#606): colab ship lands a docs-only change without waiting for CI' };
247
+ }
248
+ const v = doc[CI_DOCS_SKIP_KEY];
249
+ if (v === 'off' || v === false) {
250
+ return { declared: true, valid: true, on: false, exclude: null, reason: 'ci-docs-skip: off — colab ship requires CI for every change' };
197
251
  }
198
252
  const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
199
- reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none); the CI guard reads anything else as not opted in, so docs-only changes run the full suite` });
253
+ reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none) or \`off\`; every reader takes anything else as "CI required", so the declaration silently opts this repo out of the docs-only path` });
254
+ if (v === null || v === undefined) return bad('is empty');
200
255
  if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
201
256
  const exclude = [];
202
257
  for (const m of v) {
@@ -207,11 +262,11 @@ function parseCiDocsSkip(doc) {
207
262
  exclude.push(s);
208
263
  }
209
264
  return { declared: true, valid: true, on: true, exclude,
210
- reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change skips the CI suite' };
265
+ reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — colab ship lands a docs-only change without waiting for CI' };
211
266
  }
212
267
 
213
268
  module.exports = {
214
- DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
269
+ DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
215
270
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
216
- CI_DOCS_SKIP_KEY, parseCiDocsSkip,
271
+ CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
217
272
  };
package/tools/lib/git.js CHANGED
@@ -755,6 +755,11 @@ function ghPrClose(repo, num, comment) {
755
755
  return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
756
756
  }
757
757
 
758
+ /** #605: cancel one workflow run (a deleted batch ref's run still in flight). The run result, ok or not. */
759
+ function ghRunCancel(repo, id) {
760
+ return gh(['run', 'cancel', String(id)], { cwd: repo });
761
+ }
762
+
758
763
  function ghIssueComment(repo, issueNum, body) {
759
764
  const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
760
765
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
@@ -1441,5 +1446,5 @@ module.exports = {
1441
1446
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1442
1447
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1443
1448
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1444
- ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
1449
+ ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility, ghRunCancel,
1445
1450
  };
@@ -0,0 +1,132 @@
1
+ 'use strict';
2
+ /**
3
+ * #606 — the secret check `colab ship` runs on a DOCS-ONLY change before it merges.
4
+ *
5
+ * A docs-only change lands without waiting for CI (tools/lib/docs-only.js shipDocsOnly), so the CI
6
+ * suite's own secret scan (gitleaks in the templates) may never see it. This is the cheap stand-in:
7
+ * the lines the change ADDS — `git diff -U0 <base>...<branch>`, text files only (git prints no lines
8
+ * for a binary) — matched against generic credential shapes, plus the repo's own forbidden terms
9
+ * when it keeps a file at TERMS_PATH. Seconds, no dependency, no network.
10
+ *
11
+ * A finding is reported as `file:line (rule)`, never with the matched text: the refusal is printed
12
+ * to a terminal and may be pasted onto an Issue, and a public repo's Issues are public.
13
+ *
14
+ * It is a backstop, not gitleaks: generic shapes only, added lines only. A shape it misses is
15
+ * missed; nothing here claims the change is clean beyond these rules.
16
+ */
17
+
18
+ /** The repo-local forbidden-terms file (project.schema.md "ci-docs-skip"), read at the TARGET's tip. */
19
+ const TERMS_PATH = '.github/secret-scan-terms';
20
+
21
+ /** Generic credential shapes. `test` gets one added line. */
22
+ const RULES = Object.freeze([
23
+ { rule: 'private key', re: /-----BEGIN ([A-Z0-9]+ )*PRIVATE KEY( BLOCK)?-----/ },
24
+ { rule: 'AWS access key', re: /(^|[^A-Z0-9])(AKIA|ASIA)[A-Z0-9]{16}([^A-Z0-9]|$)/ },
25
+ { rule: 'GitHub token', re: /(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,})/ },
26
+ { rule: 'Slack token', re: /xox[abposr]-[A-Za-z0-9-]{10,}/ },
27
+ { rule: 'Google API key', re: /AIza[0-9A-Za-z_-]{35}/ },
28
+ { rule: 'Stripe live key', re: /(sk|rk)_live_[0-9A-Za-z]{20,}/ },
29
+ { rule: 'LLM API key', re: /sk-(ant|proj)-[A-Za-z0-9_-]{20,}/ },
30
+ ]);
31
+
32
+ /**
33
+ * `password=…` and its kin. The value must hold a lower-case letter AND a digit, so a documented
34
+ * placeholder (`YOUR_API_KEY`, `changeme`, `$PASSWORD`, `<secret>`, `${{ secrets.X }}`) is not a
35
+ * finding while `password=hunter22` is.
36
+ */
37
+ const ASSIGN = /(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)["']?\s*[:=]\s*["']?([^"'\s<>{}$]{8,})/i;
38
+ function assignment(line) {
39
+ const m = ASSIGN.exec(line);
40
+ return !!m && /[0-9]/.test(m[2]) && /[a-z]/.test(m[2]);
41
+ }
42
+
43
+ /**
44
+ * Parse a forbidden-terms file — the format of templates/identity-vocabulary.example: one term per
45
+ * line, trimmed; blank and `#` lines are comments; a plain term matches case-insensitively as a
46
+ * substring; `re:<ERE>` is a regular expression matched against the lower-cased line; a term
47
+ * shorter than 3 characters is refused as a mistake. Returns `{ terms: [{line, test}], problems }`.
48
+ */
49
+ function parseTerms(text) {
50
+ const terms = [];
51
+ const problems = [];
52
+ String(text || '').split(/\r?\n/).forEach((raw, i) => {
53
+ const t = raw.trim();
54
+ if (!t || t.startsWith('#')) return;
55
+ const line = i + 1;
56
+ if (t.startsWith('re:')) {
57
+ try {
58
+ const re = new RegExp(t.slice(3));
59
+ terms.push({ line, test: (s) => re.test(s.toLowerCase()) });
60
+ } catch (_) {
61
+ problems.push(`${TERMS_PATH} line ${line} is not a valid regular expression`);
62
+ }
63
+ return;
64
+ }
65
+ if (t.length < 3) { problems.push(`${TERMS_PATH} line ${line} is shorter than 3 characters`); return; }
66
+ const want = t.toLowerCase();
67
+ terms.push({ line, test: (s) => s.toLowerCase().includes(want) });
68
+ });
69
+ return { terms, problems };
70
+ }
71
+
72
+ /**
73
+ * The added lines of a `git diff -U0 --no-renames --no-color` patch: `[{ file, line, text }]`.
74
+ * `line` is the line number in the new file.
75
+ */
76
+ function addedLines(patch) {
77
+ const out = [];
78
+ let file = null;
79
+ let ln = 0;
80
+ let inHunk = false;
81
+ for (const l of String(patch || '').split('\n')) {
82
+ // A file header only outside a hunk: an added line `++ x` prints as `+++ x` inside one.
83
+ if (l.startsWith('diff --git ')) { inHunk = false; file = null; continue; }
84
+ if (!inHunk && l.startsWith('+++ ')) { const f = l.slice(4); file = f === '/dev/null' ? null : f.replace(/^b\//, ''); continue; }
85
+ const h = /^@@ -\S+ \+(\d+)(?:,\d+)? @@/.exec(l);
86
+ if (h) { ln = Number(h[1]); inHunk = true; continue; }
87
+ if (inHunk && l.startsWith('+') && file) { out.push({ file, line: ln, text: l.slice(1) }); ln++; }
88
+ }
89
+ return out;
90
+ }
91
+
92
+ /** Pure: findings `[{ file, line, rule }]` over added lines, against RULES + assignment + `terms`. */
93
+ function scanLines(lines, terms = []) {
94
+ const findings = [];
95
+ for (const { file, line, text } of lines) {
96
+ for (const r of RULES) if (r.re.test(text)) findings.push({ file, line, rule: r.rule });
97
+ if (assignment(text)) findings.push({ file, line, rule: 'credential assignment' });
98
+ for (const t of terms) if (t.test(text)) findings.push({ file, line, rule: `forbidden term, line ${t.line} of ${TERMS_PATH}` });
99
+ }
100
+ return findings;
101
+ }
102
+
103
+ /**
104
+ * Scan what `branch` adds relative to its merge base with `base`, with the forbidden terms read from
105
+ * `base`'s tree (the branch cannot edit them and stay docs-only: `.github/` is never documentation).
106
+ * Returns `{ ok, findings, files, reason }`; `ok: false` with no findings means the scan could not
107
+ * run — a caller refuses on that too, it never reads it as clean.
108
+ */
109
+ function scanBranch(git, repo, base, branch) {
110
+ const d = git.git(['diff', '-U0', '--no-renames', '--no-color', '--no-ext-diff', `${base}...${branch}`, '--'], repo);
111
+ if (!d.ok) return { ok: false, findings: [], reason: `could not read the diff ${base}...${branch}` };
112
+ let terms = [];
113
+ if (git.git(['cat-file', '-e', `${base}:${TERMS_PATH}`], repo).ok) {
114
+ const t = git.git(['show', `${base}:${TERMS_PATH}`], repo);
115
+ if (!t.ok) return { ok: false, findings: [], reason: `could not read ${TERMS_PATH} at ${base}` };
116
+ const parsed = parseTerms(t.stdout);
117
+ if (parsed.problems.length) return { ok: false, findings: [], reason: parsed.problems.join('; ') };
118
+ terms = parsed.terms;
119
+ }
120
+ const lines = addedLines(d.stdout);
121
+ const findings = scanLines(lines, terms);
122
+ const files = new Set(lines.map((l) => l.file)).size;
123
+ const extra = terms.length ? ` and ${terms.length} forbidden term(s)` : '';
124
+ if (findings.length) {
125
+ const shown = findings.slice(0, 5).map((f) => `${f.file}:${f.line} (${f.rule})`).join('; ');
126
+ const more = findings.length > 5 ? `; +${findings.length - 5} more` : '';
127
+ return { ok: false, findings, files, reason: `${findings.length} finding(s): ${shown}${more}` };
128
+ }
129
+ return { ok: true, findings, files, reason: `${lines.length} added line(s) in ${files} file(s) clean against the credential shapes${extra}` };
130
+ }
131
+
132
+ module.exports = { TERMS_PATH, RULES, parseTerms, addedLines, scanLines, scanBranch, assignment };
@@ -513,7 +513,10 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
513
513
  const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
514
514
  const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
515
515
  for (const b of (Array.isArray(batches) ? batches : [])) {
516
- if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
516
+ // #605: a chained batch (`rooted`, from batchChains) is part of the one holder its root is —
517
+ // built on another batch's head, so it reaches trunk only through that chain. Without the flag,
518
+ // only a batch built on trunk's tip counts, exactly as before.
519
+ if (!b || !b.base7 || !(b.rooted === undefined ? now.startsWith(b.base7) : b.rooted)) continue;
517
520
  const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
518
521
  if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
519
522
  if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
@@ -532,6 +535,72 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
532
535
  return { held: false, released };
533
536
  }
534
537
 
538
+ /**
539
+ * #605: speculative chains. A batch built with `--onto <ship-batch ref>` sits on that ref's HEAD, and
540
+ * its name already says so: `ship-batch/<parent-head-sha7>`. So the whole chain is read from
541
+ * `ls-remote` alone — a ref's parent is the ref whose head sha starts with its base7, and a ref is
542
+ * ROOTED when following parents ends at a ref built on trunk's tip. No chain state is kept anywhere.
543
+ *
544
+ * In: refs `[{ ref, base7, sha }]` (every ship-batch/* on the remote), `trunkNow`.
545
+ * Out: Map ref → `{ ref, base7, sha, parentRef, rootRef, rootSha, depth, rooted, why }`:
546
+ * - parentRef null for a batch built on trunk's tip, else the ref it was built on (null too
547
+ * when that ref is gone — then `rooted` is false);
548
+ * - rootSha trunk's tip when rooted, else null;
549
+ * - depth 1 at trunk's tip, 2 for its child, …;
550
+ * - why for an unrooted ref, the reason it is (the sweep deletes it, and says this).
551
+ * A chain deeper than MAX_CHAIN_DEPTH is not rooted: every link pins trunk for one more combined run,
552
+ * and a wrong guess low in the chain throws away every run above it.
553
+ */
554
+ const MAX_CHAIN_DEPTH = 3;
555
+
556
+ function batchChains({ refs, trunkNow } = {}) {
557
+ const now = String(trunkNow || '');
558
+ const all = (Array.isArray(refs) ? refs : []).filter((r) => r && r.ref && r.base7 && r.sha);
559
+ const parentOf = (r) => all.find((p) => p !== r && String(p.sha).startsWith(r.base7)) || null;
560
+ const out = new Map();
561
+ for (const r of all) {
562
+ const atTip = !!now && now.startsWith(r.base7);
563
+ const parent = atTip ? null : parentOf(r);
564
+ let cur = r, depth = 1, why = null, root = null;
565
+ const seen = new Set([r.ref]);
566
+ while (true) {
567
+ if (now && now.startsWith(cur.base7)) { root = cur; break; }
568
+ const p = parentOf(cur);
569
+ if (!p) {
570
+ why = cur === r ? `its base ${r.base7} is neither trunk's tip nor the head of another batch ref — trunk moved, or its parent was rebuilt or deleted`
571
+ : `its chain breaks at ${cur.ref}, whose base ${cur.base7} is neither trunk's tip nor another batch's head`;
572
+ break;
573
+ }
574
+ if (seen.has(p.ref)) { why = `its chain loops at ${p.ref}`; break; }
575
+ seen.add(p.ref);
576
+ cur = p;
577
+ depth += 1;
578
+ if (depth > MAX_CHAIN_DEPTH) { why = `its chain is deeper than ${MAX_CHAIN_DEPTH}`; break; }
579
+ }
580
+ out.set(r.ref, {
581
+ ref: r.ref, base7: r.base7, sha: r.sha, parentRef: parent ? parent.ref : null,
582
+ rootRef: root ? root.ref : null, rootSha: root ? now : null, depth, rooted: !!root, why,
583
+ });
584
+ }
585
+ return out;
586
+ }
587
+
588
+ /**
589
+ * #605: what a chained batch (built `--onto` a parent) does when it is ready to land but its parent
590
+ * has not landed yet — trunk's tip is not its base. Facts: the parent's chain entry (null = gone)
591
+ * and the parent's combined verdict.
592
+ * wait the parent is rooted and its run is in flight, not yet run, or green → exit 3
593
+ * decline the parent is gone, unrooted, or red → nothing of this chain can land in order: delete
594
+ * this batch and decline it (exit 4)
595
+ */
596
+ function chainedLandStep({ parent, parentVerdict } = {}) {
597
+ if (!parent) return { step: 'decline', why: 'its parent batch is gone — discarded, or rebuilt on another head' };
598
+ if (!parent.rooted) return { step: 'decline', why: `its parent ${parent.ref} is no longer rooted at trunk's tip (${parent.why})` };
599
+ const v = parentVerdict || { state: 'pending', why: 'the run list could not be read' };
600
+ if (v.state === 'red') return { step: 'decline', why: `its parent ${parent.ref} is red (${v.why}) — it will not land at the sha this batch was built on` };
601
+ return { step: 'wait', why: `its parent ${parent.ref} has not landed yet (${v.state === 'green' ? 'green, waiting for its lander' : (v.why || v.state)})` };
602
+ }
603
+
535
604
  /** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
536
605
  function settledAt(rows) {
537
606
  const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
@@ -599,5 +668,5 @@ module.exports = {
599
668
  droppedTrailer, parseDroppedTrailers, appendTrailers,
600
669
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
601
670
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
602
- LANE_GRACE_SEC, laneHold, settledAt,
671
+ LANE_GRACE_SEC, laneHold, settledAt, MAX_CHAIN_DEPTH, batchChains, chainedLandStep,
603
672
  };