@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
77
77
 
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
- 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -379,6 +379,56 @@ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } =
379
379
  };
380
380
  }
381
381
 
382
+ // ---- a failed deploy job: a report on a human final, a gate on an automatic one (#565) -------------
383
+
384
+ // A job whose name says it deploys. The release workflow deploys the candidate to staging after it has
385
+ // built, tested and published it; that job's failure is about the deploy target (a host the runner
386
+ // cannot reach, a registry permission, a sibling image that was never built), never about the code.
387
+ const DEPLOY_JOB_RE = /\bdeploy/i;
388
+
389
+ /** Does a job named `name` deploy? Read from the name: GitHub's job read carries no environment. */
390
+ function isDeployJob(name) {
391
+ return DEPLOY_JOB_RE.test(String(name || ''));
392
+ }
393
+
394
+ /**
395
+ * The runs at a candidate's commit that failed ONLY in deploy jobs (#565). `rows` are the run rows
396
+ * (null = unread); `jobsOf(databaseId)` returns that run's jobs (`git.ghRunJobs`, null = unread), asked
397
+ * lazily and only for a completed run that concluded `failure`.
398
+ *
399
+ * A run is deploy-only when its jobs were read, at least one did not pass, and every job that did not
400
+ * pass (anything but success/skipped/neutral — cancelled included) is a deploy job. A job that builds,
401
+ * tests or publishes failing keeps the run a failure; so does a run whose jobs could not be read.
402
+ *
403
+ * Returns { rows, failures } — `rows` a copy of `rows` where each deploy-only run reads `success` and
404
+ * carries `deployFailed` (its failed deploy jobs), `failures` [{ workflowName, databaseId, jobs }] for
405
+ * the report. Measuring this never decides anything: decide() uses the rewritten reading only on a
406
+ * human final, and names the failures either way.
407
+ */
408
+ function deployOnlyFailures(rows, jobsOf) {
409
+ if (!Array.isArray(rows) || typeof jobsOf !== 'function') return { rows, failures: [] };
410
+ const failures = [];
411
+ const out = rows.map((r) => {
412
+ if (!r || r.status !== 'completed' || r.conclusion !== 'failure' || r.databaseId == null) return r;
413
+ const jobs = jobsOf(r.databaseId);
414
+ if (!Array.isArray(jobs) || !jobs.length) return r;
415
+ const bad = jobs.filter((j) => j && !(j.status === 'completed' && NOT_RED.has(j.conclusion)));
416
+ if (!bad.length || !bad.every((j) => isDeployJob(j.name))) return r;
417
+ const named = bad.map((j) => `${j.name} (${j.status === 'completed' ? j.conclusion || 'no conclusion' : j.status || 'unknown'})`);
418
+ failures.push({ workflowName: r.workflowName || '(unnamed workflow)', databaseId: r.databaseId, jobs: named });
419
+ return { ...r, conclusion: 'success', deployFailed: named };
420
+ });
421
+ return { rows: out, failures };
422
+ }
423
+
424
+ /** The `deploy-report` check's detail — what failed, and what it means on this final. */
425
+ function deployReportDetail(failures, { blocking }) {
426
+ const what = failures.map((f) => `${f.workflowName} run ${f.databaseId}: ${f.jobs.join(', ')}`).join('; ');
427
+ return blocking
428
+ ? `a deploy job failed at this candidate (${what}); an automatic final treats it as blocking, so ci-green, full-suite and cut-run read the run as failed`
429
+ : `a deploy job failed at this candidate (${what}); its build, tests and publish passed, so on a human final this is a report, not a gate: ci-green, full-suite and cut-run read that run without its deploy jobs. Check the deploy target before you finalize`;
430
+ }
431
+
382
432
  // ---- the test period ----------------------------------------------------------------------------
383
433
 
384
434
  /**
@@ -534,7 +584,8 @@ function handoffCommand(tag) {
534
584
  * `facts`:
535
585
  * policy release-policy.js evaluateRelease(doc)
536
586
  * selection selectCandidate(...)
537
- * tracking { number|null, createdAt|null, held, wouldCreate } | { error }
587
+ * tracking { number|null, title|null, createdAt|null, held, wouldCreate } | { error } — `title` is the
588
+ * matched issue's own, shown so a record that is not `release: vX.Y.Z` is visible (#575)
538
589
  * supersededHeld [issue numbers]
539
590
  * period periodVerdict(...) (when there is a candidate)
540
591
  * trunk trunkGreenVerdict(...)
@@ -586,7 +637,7 @@ function decide(facts) {
586
637
 
587
638
  const t = f.tracking || {};
588
639
  if (t.error) { add('tracking-issue', false, t.error); return out('refused'); }
589
- add('tracking-issue', true, t.number ? `#${t.number} (${trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
640
+ add('tracking-issue', true, t.number ? `#${t.number} (${t.title ? JSON.stringify(t.title) : trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
590
641
 
591
642
  const held = [...(t.held && t.number ? [t.number] : []), ...(f.supersededHeld || [])];
592
643
  add('release-hold', !held.length, held.length
@@ -616,7 +667,17 @@ function decide(facts) {
616
667
  add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
617
668
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
618
669
  add('trunk-green', tr.ok, tr.detail, ownClock);
619
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
670
+ // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
671
+ // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
672
+ // those runs counted as passed; it is absent when no such run exists.
673
+ const dr = f.deployReport && Array.isArray(f.deployReport.failures) && f.deployReport.failures.length ? f.deployReport : null;
674
+ const lenient = !!dr && !auto;
675
+ const pick = (strict, relaxed) => (lenient && relaxed ? relaxed : strict);
676
+ for (const [condition, v] of [['ci-green', pick(f.ci, dr && dr.ci)], ['full-suite', pick(f.suite, dr && dr.suite)], ['cut-run', pick(f.cutRun, dr && dr.cutRun)]]) {
677
+ add(condition, v && v.ok, v ? v.detail : 'not measured');
678
+ }
679
+ if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
680
+ for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
620
681
  add(condition, v && v.ok, v ? v.detail : 'not measured');
621
682
  }
622
683
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -698,7 +759,7 @@ module.exports = {
698
759
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
699
760
  parseVersion, compareVersions, parseCandidate,
700
761
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
701
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
762
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
702
763
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
703
764
  carriedIssues, previousFinal, releasedEvent, releasedComment,
704
765
  };
@@ -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,19 +43,111 @@ 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
 
52
148
  /**
53
149
  * #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
54
- * before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
150
+ * before it lands alone (as a batch of one, #562). A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
55
151
  * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
152
  *
57
153
  * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
@@ -74,7 +170,8 @@ function parseShipBatchWait(doc) {
74
170
  }
75
171
 
76
172
  /**
77
- * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
173
+ * #555: does a batch call with ONE eligible member wait for a partner, or build now? (Past the window
174
+ * it lands alone — through the batch path, as a batch of one, #562 — never serially.)
78
175
  * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
176
  * already in flight — the lane is otherwise idle by then):
80
177
  * n parseShipBatch(doc).n
@@ -305,18 +402,26 @@ function combinedVerdict(rows) {
305
402
  /**
306
403
  * The one decision per `colab ship --batch` call. The command is RE-ENTRANT: it reads remote state,
307
404
  * takes one step, and exits — the caller waits (bounded, code-ship B1a) and calls again.
308
- * serial(reason) land nothing; hand the members back as a serial list (exit 4)
405
+ * serial(reason) land nothing; hand the members back as a serial list (exit 4) — never for
406
+ * a lone ready member: one member is a valid batch (#562)
309
407
  * wait-trunk trunk's own run is still in flight (exit 3)
310
408
  * rebuild a batch ref exists on a base trunk has moved past, or its members/heads are
311
409
  * no longer the ones asked for → delete it, then build afresh
312
410
  * build build + push the batch ref (exit 3)
313
411
  * wait-run the combined run is pending or has not appeared (exit 3)
314
- * red-rerun-or-serial combined run red on its FIRST attempt — the caller classifies it (§4): a
315
- * red:infra is re-run once, a red:finding goes serial (exit 4, ref kept)
316
- * 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
317
422
  * land green → fast-forward trunk if it has not moved
318
423
  */
319
- 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 }) {
320
425
  if (!enabled) return { step: 'serial', reason: 'not-enabled' };
321
426
  if (!wired) return { step: 'serial', reason: 'unwired' };
322
427
  if (trunkCi === 'red') return { step: 'serial', reason: 'trunk-red' };
@@ -325,10 +430,18 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
325
430
  if (!trunkNow || !String(trunkNow).startsWith(existing.base7)) return { step: 'rebuild', reason: 'trunk-moved' };
326
431
  if (!existing.matches) return { step: 'rebuild', reason: 'members-changed' };
327
432
  if (!verdict || verdict.state === 'pending' || verdict.state === 'none') return { step: 'wait-run' };
328
- 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
+ }
329
440
  return { step: 'land' };
330
441
  }
331
- if (eligibleCount < 2) return { step: 'serial', reason: 'too-few' };
442
+ // #562: a batch of ONE is a batch — a lone ready member still lands through the combined run, so
443
+ // the setups a repo runs only on ship-batch/** and trunk gate it before trunk moves.
444
+ if (eligibleCount < 1) return { step: 'serial', reason: 'none-ready' };
332
445
  return { step: 'build' };
333
446
  }
334
447
 
@@ -366,6 +479,66 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
366
479
  return (batchRows || []).length >= a.length;
367
480
  }
368
481
 
482
+ /**
483
+ * #581: the lane reservation. A batch ref at trunk's CURRENT tip whose combined run is in flight (or
484
+ * green and not yet landed) holds the trunk lane: a serial `colab ship` into trunk that landed now
485
+ * would move trunk under it, and the batch's next call would throw the green run away and rebuild —
486
+ * measured five builds in two hours on one repo, every member ready the whole time. The ref itself
487
+ * is the reservation: it already sits on the remote every lander reads, it names its base, and its
488
+ * runs say whether it is alive. No second record to write, expire or keep in sync.
489
+ *
490
+ * Facts in, per batch ref on the remote (`batches`):
491
+ * ref, base7 parseBatchRef
492
+ * verdict combinedVerdict of the runs at its head
493
+ * builtAtMs the batch head's commit time (the build commits it), null = unread
494
+ * settledAtMs the newest `updatedAt` of its runs once green, null = unread
495
+ * plus `trunkNow` (the remote trunk sha), `nowMs`, and `graceSec`.
496
+ *
497
+ * Out: `{ held: true, ref, why }` for the first batch that holds the lane, else `{ held: false,
498
+ * released: [{ ref, why }] }` naming each batch at this base that does NOT hold it, and why.
499
+ * - a batch on an older base holds nothing: trunk already moved past it, it rebuilds anyway;
500
+ * - red (first attempt or after its re-run) → declined, holds nothing;
501
+ * - pending, or a run list that could not be read → held (fail closed: a pause clears itself);
502
+ * - no run yet → held for `graceSec` after it was built, then released (its run never came);
503
+ * - green → held for `graceSec` after it went green — its lander lands it on its next call —
504
+ * then released: a green batch nobody lands is abandoned, and must not hold the lane forever.
505
+ * An unread time (built/settled) is released, never held: a hold has to be provably alive.
506
+ */
507
+ const LANE_GRACE_SEC = 900;
508
+
509
+ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {}) {
510
+ const now = String(trunkNow || '');
511
+ const released = [];
512
+ if (!now) return { held: false, released };
513
+ const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
514
+ const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
515
+ for (const b of (Array.isArray(batches) ? batches : [])) {
516
+ if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
517
+ const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
518
+ if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
519
+ if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
520
+ if (v.state === 'none') {
521
+ if (fresh(b.builtAtMs)) return { held: true, ref: b.ref, why: `built ${mins(b.builtAtMs)}, its combined run has not appeared yet` };
522
+ released.push({ ref: b.ref, why: Number.isFinite(b.builtAtMs)
523
+ ? `no combined run ${mins(b.builtAtMs)} after it was built (grace ${graceSec}s) — treated as abandoned`
524
+ : 'no combined run, and its build time could not be read — not provably alive' });
525
+ continue;
526
+ }
527
+ if (fresh(b.settledAtMs)) return { held: true, ref: b.ref, why: `combined run green ${mins(b.settledAtMs)} — its lander lands it on its next call` };
528
+ released.push({ ref: b.ref, why: Number.isFinite(b.settledAtMs)
529
+ ? `combined run green ${mins(b.settledAtMs)} and still not landed (grace ${graceSec}s) — treated as abandoned`
530
+ : 'combined run green, but when it went green could not be read — not provably alive' });
531
+ }
532
+ return { held: false, released };
533
+ }
534
+
535
+ /** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
536
+ function settledAt(rows) {
537
+ const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
538
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
539
+ return t.length ? Math.max(...t) : null;
540
+ }
541
+
369
542
  /**
370
543
  * #415: branches the command line names that a staged batch does not carry, in command-line order.
371
544
  * `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
@@ -421,9 +594,10 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
421
594
  }
422
595
 
423
596
  module.exports = {
424
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
425
- 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,
426
599
  droppedTrailer, parseDroppedTrailers, appendTrailers,
427
600
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
428
601
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
602
+ LANE_GRACE_SEC, laneHold, settledAt,
429
603
  };
@@ -0,0 +1,174 @@
1
+ 'use strict';
2
+ /**
3
+ * #578 — `colab ship --branch <br> --handoff <comment-url>`: land a branch whose claim lives on
4
+ * ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
5
+ *
6
+ * The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
7
+ * A branch built and wrapped on machine A and landed from machine B has its claim in A's registry,
8
+ * so on B ship reads zero claims and refuses (#153 / #324). The only way to write a record on B was
9
+ * `colab claim --force` — a human-only takeover — so an agent lander had no sanctioned path, and
10
+ * every remote-built branch waited for a person even when it had passed review and merged clean.
11
+ *
12
+ * The door. The executor has already said, on the tracker, which branch it handed off and at which
13
+ * head. That comment, checked against git and against the executor's own live claim, is the
14
+ * evidence ship would otherwise get from a local claim. Nothing on B's registry is written and
15
+ * nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
16
+ * (its own `colab worktree rm`, which releases the claim as usual).
17
+ *
18
+ * What a hand-off must prove, in order — the first failure is the verdict:
19
+ * 1. the URL is an issue-comment URL (`…/issues/<N>#issuecomment-<id>`);
20
+ * 2. the comment was read from THIS repo (fetched through `{owner}/{repo}`, so an off-repo id is a
21
+ * 404) and its own html_url names the same issue the URL does;
22
+ * 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
23
+ * issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
24
+ * 4. the body names the branch, as a whole token;
25
+ * 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
26
+ * 6. the body names a sha that is a prefix of the remote branch's CURRENT head — a branch that
27
+ * moved after its hand-off was not handed off at that head, and lands only after a new one.
28
+ * ONE movement is not "moved" (#579): base-sync merges stacked on the handed-off head. The
29
+ * stale-base gate (#395) sends every behind-trunk branch through B0's sync, and the sync moves
30
+ * the head; without this a remote-built branch that fell behind could land only after its
31
+ * executor — whose session has usually ended — posted again. A sync merge is accepted only
32
+ * when it adds nothing of its own (syncMergeChain, below): two parents, the second already on
33
+ * the base, and a tree equal to git's own clean merge of the two. Any other commit after the
34
+ * handed-off sha — a fix-up, a rebase, a hand-resolved conflict — is still `head-moved`;
35
+ * 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
36
+ * the hand-off's author before the hand-off — the claim really does live elsewhere, and the
37
+ * party handing off is the party holding it.
38
+ *
39
+ * Pure: every input is already read. tools/colab does the IO (`gh api`, `git fetch`, issue views).
40
+ */
41
+
42
+ const { branchIssueNumbers } = require('./branch-name');
43
+
44
+ /** `https://github.com/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE). */
45
+ function parseHandoffUrl(url) {
46
+ const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
47
+ if (!m) return null;
48
+ return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
49
+ }
50
+
51
+ function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
52
+
53
+ /** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
54
+ function namesBranch(body, branch) {
55
+ if (!branch) return false;
56
+ return new RegExp(`(^|[^A-Za-z0-9._/-])${escapeRe(branch)}(?![A-Za-z0-9._/-])`).test(String(body || ''));
57
+ }
58
+
59
+ /** Every 7–40 hex token in `body`, lower-cased — the candidate head shas a hand-off names. */
60
+ function namedShas(body) {
61
+ return [...String(body || '').matchAll(/(?<![0-9A-Za-z])([0-9a-fA-F]{7,40})(?![0-9A-Za-z])/g)]
62
+ .map((m) => m[1].toLowerCase());
63
+ }
64
+
65
+ /**
66
+ * The verdict. Inputs:
67
+ * url — the --handoff value
68
+ * comment — { body, login, createdAt, htmlUrl } as read from THIS repo, or null (unreadable)
69
+ * branch — the branch being shipped
70
+ * refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
71
+ * claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
72
+ * or null for an issue whose comments could not be read
73
+ * syncChain — (#579) the first-parent ancestors of the remote head reached through pure
74
+ * base-sync merges only, nearest first (syncMergeChain's output); [] or absent = none
75
+ * Returns { ok: true, issues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
76
+ * `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
77
+ * unless the head was synced, in which case `syncMerges` counts the merges between them.
78
+ */
79
+ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }) {
80
+ const no = (reason, detail) => ({ ok: false, reason, detail });
81
+ const u = parseHandoffUrl(url);
82
+ if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
83
+ if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
84
+ const got = parseHandoffUrl(comment.htmlUrl);
85
+ if (!got || got.commentId !== u.commentId || got.issue !== u.issue ||
86
+ got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
87
+ return no('mismatch', `the URL says ${u.owner}/${u.repo}#${u.issue}, but comment ${u.commentId} is ${comment.htmlUrl || 'somewhere else'}`);
88
+ }
89
+ const issues = branchIssueNumbers(branch);
90
+ if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
91
+ if (!issues.includes(u.issue)) return no('not-this-branch', `the hand-off is on #${u.issue}, which ${branch} does not carry (${issues.map((n) => '#' + n).join(' ')})`);
92
+ if (!namesBranch(comment.body, branch)) return no('branch-not-named', `the hand-off comment does not name the branch ${branch}`);
93
+ if (!refs || !refs.remoteSha) return no('no-remote-branch', `${branch} is not on the remote — a hand-off lands a pushed branch only`);
94
+ // Ship merges the local ref when one exists (shipRefFor), so it must BE the remote head: a stale
95
+ // copy a DWIM checkout made earlier would land a sha the hand-off never named.
96
+ if (refs.localSha && refs.localSha !== refs.remoteSha) {
97
+ return no('local-diverges', refs.localFromRemote
98
+ ? `this machine's ${branch} (${refs.localSha.slice(0, 8)}, created from the remote by an earlier checkout) is behind or apart from the remote's (${refs.remoteSha.slice(0, 8)}) — reset it to the remote's (git branch -f ${branch} <remote>/${branch}, from a checkout not on it) and re-run`
99
+ : `this machine has its own ${branch} (${refs.localSha.slice(0, 8)}) that differs from the remote's (${refs.remoteSha.slice(0, 8)}) — not a remote-built branch here`);
100
+ }
101
+ const head = String(refs.remoteSha).toLowerCase();
102
+ const shas = namedShas(comment.body);
103
+ // #579: the head itself first, then each sha a pure base-sync merge sits on, nearest first.
104
+ const lineage = [head, ...(Array.isArray(syncChain) ? syncChain : []).map((x) => String(x).toLowerCase())];
105
+ const at = lineage.findIndex((l) => shas.some((s) => l.startsWith(s)));
106
+ if (at < 0) {
107
+ const synced = lineage.length > 1 ? ` (nor ${lineage.length - 1 === 1 ? 'the sha' : 'any of the ' + (lineage.length - 1) + ' shas'} its base-sync merges sit on)` : '';
108
+ return no('head-moved', shas.length
109
+ ? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)}${synced} — the branch moved after it was handed off by more than a clean merge of its base; ask its executor for a new hand-off`
110
+ : `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
111
+ }
112
+ let executor = null;
113
+ for (const n of issues) {
114
+ const live = claimsByIssue ? claimsByIssue[n] : null;
115
+ if (!live) return no('claims-unreadable', `#${n}'s comments could not be read — the executor's claim cannot be checked`);
116
+ const match = live.find((c) => c.branch === branch && c.login === comment.login && c.at < comment.createdAt);
117
+ if (!match) {
118
+ return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off — ` +
119
+ 'the hand-off must come from the party holding the claim');
120
+ }
121
+ if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
122
+ }
123
+ return { ok: true, issues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
124
+ }
125
+
126
+ /**
127
+ * The squash trailer recording the door the issue set came through. It names the HANDED-OFF sha —
128
+ * the one the executor vouched for — and, after a sync (#579), the head that actually landed.
129
+ */
130
+ function handoffTrailer(v) {
131
+ if (!v || !v.ok) return '';
132
+ const handed = String(v.handedOff || v.sha).slice(0, 12);
133
+ const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
134
+ return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
135
+ }
136
+
137
+ /**
138
+ * #579 — walk the remote head's first-parent line while each commit is a PURE base-sync merge, and
139
+ * return the shas it sits on, nearest first. A commit qualifies only when all three hold:
140
+ * - exactly two parents (a squash, a rebase, a cherry-pick or a fix-up has one);
141
+ * - its second parent is already on the base (`merge-base --is-ancestor p2 <baseRef>`) — it
142
+ * brought in landed base content, not a side branch;
143
+ * - its tree equals `git merge-tree --write-tree p1 p2`'s — git's own conflict-free merge of the
144
+ * two. A conflict (exit 1) or a hand-edited result (a different tree) is NOT pure: someone wrote
145
+ * content into it, and only the executor can vouch for content.
146
+ * The walk stops at the first commit that fails, so a sync merge stacked on a fix-up yields only
147
+ * the fix-up's sha — which a hand-off naming the commit before the fix-up does not match.
148
+ *
149
+ * `run(args)` is git in the repo, returning { ok, code, stdout } (tools/lib/git.js `git`). A git
150
+ * too old for `merge-tree --write-tree` (< 2.38) proves nothing, so the chain is just empty there:
151
+ * the hand-off then needs the exact head, exactly as before #579.
152
+ */
153
+ function syncMergeChain(run, head, baseRef, maxDepth = 50) {
154
+ const chain = [];
155
+ let cur = String(head || '');
156
+ for (let i = 0; cur && i < maxDepth; i++) {
157
+ const p = run(['rev-list', '--parents', '-n', '1', cur]);
158
+ if (!p.ok) break;
159
+ const parts = String(p.stdout).trim().split(/\s+/);
160
+ if (parts.length !== 3) break;
161
+ const [, p1, p2] = parts;
162
+ if (run(['merge-base', '--is-ancestor', p2, baseRef]).code !== 0) break;
163
+ const mt = run(['merge-tree', '--write-tree', p1, p2]);
164
+ if (mt.code !== 0) break;
165
+ const merged = String(mt.stdout).split('\n')[0].trim();
166
+ const tree = run(['rev-parse', `${cur}^{tree}`]);
167
+ if (!tree.ok || !/^[0-9a-f]{40,64}$/.test(merged) || merged !== String(tree.stdout).trim()) break;
168
+ chain.push(p1.toLowerCase());
169
+ cur = p1;
170
+ }
171
+ return chain;
172
+ }
173
+
174
+ module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain };
@@ -642,7 +642,7 @@ function sameContent(a, b) {
642
642
  * so divergence is undecidable and the classification stops at current/behind.
643
643
  */
644
644
  function classifyStamped(opts) {
645
- const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames } = opts;
645
+ const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames, render = null } = opts;
646
646
 
647
647
  if (hb.untagged || !hb.hasGit) {
648
648
  return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion, to: hb.version };
@@ -675,7 +675,11 @@ function classifyStamped(opts) {
675
675
  return { state: 'n-a', reason: `cannot read templates/${templateName} at ${stampVersion} — cannot tell pristine from edited`, from: stampVersion, to: hb.version };
676
676
  }
677
677
  const expected = stampLine(templateName, stampVersion) + pristine;
678
- if (sameContent(localText, expected)) {
678
+ // #526: `colab template` writes a CI copy with the repo's own refs. `render` (when given) is
679
+ // that rendering, so such a copy still reads as pristine; the raw body still counts too (a copy
680
+ // made before #526, or in a repo whose descriptor changed since).
681
+ const rendered = typeof render === 'function' ? stampLine(templateName, stampVersion) + render(pristine) : null;
682
+ if (sameContent(localText, expected) || (rendered !== null && sameContent(localText, rendered))) {
679
683
  return { state: 'behind', reason: 'pristine copy, template changed since this stamp', from: stampVersion, to: hb.version };
680
684
  }
681
685
  return { state: 'diverged', reason: `hand-edited since it was copied @ ${stampVersion} — copy-and-own, review by hand`, from: stampVersion, to: hb.version };