@futurelastic/colab-handbook 1.13.0-rc.50 → 1.13.0-rc.51

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.50"
36
+ "version": "1.13.0-rc.51"
37
37
  }
package/tools/colab CHANGED
@@ -10566,6 +10566,11 @@ It never waits: each call reads the remote, takes ONE step and exits —
10566
10566
  One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
10567
10567
  is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
10568
10568
  for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
10569
+ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref at trunk's tip has its
10570
+ combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
10571
+ \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
10572
+ 'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
10573
+ A red batch, or one with no run / not landed past that grace, holds nothing.
10569
10574
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
10570
10575
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
10571
10576
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
@@ -12216,6 +12221,17 @@ function cmdShipDryJson(opts) {
12216
12221
  if (coreReviewJson.verdict === 'pending') mode = 'pr-pending';
12217
12222
  }
12218
12223
 
12224
+ // #581: the same lane read as the prose path's table — a squash into trunk while a batch holds the
12225
+ // lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
12226
+ // Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
12227
+ if (!dryMode.evidenceClose && !opts._batchMember) {
12228
+ const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
12229
+ if (laneJson) {
12230
+ checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
12231
+ detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
12232
+ }
12233
+ }
12234
+
12219
12235
  // #149: the same inherited-closing-keyword scan the prose --dry path runs, mirrored here —
12220
12236
  // following #153's own precedent for this function (its comment above: "a caller reading only
12221
12237
  // checks[]/ok … used to see NO check at all here"). Without this, the ONE caller class this path
@@ -13300,6 +13316,11 @@ function cmdShip(argv) {
13300
13316
  const coreReview = shipCoreReview(repoAbs, gh, target, sess.branch);
13301
13317
  const coreOk = coreReview.verdict !== 'refuse';
13302
13318
  checks.push([coreOk ? (coreReview.verdict === 'pending' ? '⏸' : '✓') : '✗', 'core-path review (#350)', coreReview.detail]);
13319
+
13320
+ // #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
13321
+ // hold is not a failed precondition — it is a pause, taken below once every real one has passed.
13322
+ const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
13323
+ if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
13303
13324
  for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
13304
13325
 
13305
13326
  // #389: the record this ship will write after the push must be writable NOW.
@@ -13534,6 +13555,8 @@ function cmdShip(argv) {
13534
13555
  print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · ' +
13535
13556
  (opts.keepWorktree ? 'keep worktree' : 'worktree rm') + ' (releases claims)');
13536
13557
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
13558
+ } else if (lane && lane.held && coreReview.verdict !== 'pending') {
13559
+ print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
13537
13560
  } else if (coreReview.verdict === 'pending') {
13538
13561
  print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
13539
13562
  'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
@@ -13599,6 +13622,9 @@ function cmdShip(argv) {
13599
13622
  return shipOpenCorePr(repoAbs, coreReview, { target, branch: sess.branch, title, body });
13600
13623
  }
13601
13624
 
13625
+ // ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
13626
+ if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
13627
+
13602
13628
  // ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
13603
13629
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
13604
13630
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
@@ -13744,6 +13770,10 @@ function cmdShip(argv) {
13744
13770
  ciGrantForTrailer = ciResultB1.grantVerdict;
13745
13771
  }
13746
13772
  }
13773
+ // #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
13774
+ // built in that window is exactly as live as one the table saw.
13775
+ const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
13776
+ if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
13747
13777
  // WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
13748
13778
  // (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
13749
13779
  // out onto a long-lived line is the very state that made this axis necessary — everything reading
@@ -14266,6 +14296,46 @@ function shipDryJsonReport(opts) {
14266
14296
  return { ok: code === 0, body: holder.body || null, error: null };
14267
14297
  }
14268
14298
 
14299
+ /**
14300
+ * #581: is a batch in flight at trunk's current tip? Read by every serial door that moves trunk (the
14301
+ * prose ship's table and B1, `--dry --json`), so a lander told about it waits instead of moving trunk
14302
+ * under the batch — which would throw the batch's green combined run away. The rule is
14303
+ * lib/ship-batch.js laneHold; this only reads the remote.
14304
+ *
14305
+ * Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
14306
+ * trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
14307
+ */
14308
+ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14309
+ if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
14310
+ const remote = git.remoteFor(repoAbs);
14311
+ const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
14312
+ if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
14313
+ const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
14314
+ const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
14315
+ const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
14316
+ .filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
14317
+ const batches = atTip.map((x) => {
14318
+ const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
14319
+ let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
14320
+ if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
14321
+ const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
14322
+ return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
14323
+ builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
14324
+ });
14325
+ const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
14326
+ const detail = r.held
14327
+ ? `${r.ref} holds the ${trunk} lane — ${r.why}; landing now would move ${trunk} under it and discard its run`
14328
+ : (r.released.length ? `no batch holds the lane (${r.released.map((x) => `${x.ref}: ${x.why}`).join('; ')})` : `no batch in flight at ${trunk}@${shortSha(trunkNow)}`);
14329
+ return { ...r, trunkNow, detail };
14330
+ }
14331
+
14332
+ /** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
14333
+ function printBatchLanePause(lane, trunk) {
14334
+ print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
14335
+ print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
14336
+ print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
14337
+ }
14338
+
14269
14339
  function cmdShipBatch(opts) {
14270
14340
  for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
14271
14341
  if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
package/tools/lib/git.js CHANGED
@@ -1042,7 +1042,7 @@ function ghInstalled() {
1042
1042
  function ghRunsForRef(repo, ref, sha, limit = 20) {
1043
1043
  if (!sha) return null;
1044
1044
  const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
1045
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
1045
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,attempt'], { cwd: repo });
1046
1046
  if (!r.ok) return null;
1047
1047
  let runs;
1048
1048
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -370,6 +370,66 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
370
370
  return (batchRows || []).length >= a.length;
371
371
  }
372
372
 
373
+ /**
374
+ * #581: the lane reservation. A batch ref at trunk's CURRENT tip whose combined run is in flight (or
375
+ * green and not yet landed) holds the trunk lane: a serial `colab ship` into trunk that landed now
376
+ * would move trunk under it, and the batch's next call would throw the green run away and rebuild —
377
+ * measured five builds in two hours on one repo, every member ready the whole time. The ref itself
378
+ * is the reservation: it already sits on the remote every lander reads, it names its base, and its
379
+ * runs say whether it is alive. No second record to write, expire or keep in sync.
380
+ *
381
+ * Facts in, per batch ref on the remote (`batches`):
382
+ * ref, base7 parseBatchRef
383
+ * verdict combinedVerdict of the runs at its head
384
+ * builtAtMs the batch head's commit time (the build commits it), null = unread
385
+ * settledAtMs the newest `updatedAt` of its runs once green, null = unread
386
+ * plus `trunkNow` (the remote trunk sha), `nowMs`, and `graceSec`.
387
+ *
388
+ * Out: `{ held: true, ref, why }` for the first batch that holds the lane, else `{ held: false,
389
+ * released: [{ ref, why }] }` naming each batch at this base that does NOT hold it, and why.
390
+ * - a batch on an older base holds nothing: trunk already moved past it, it rebuilds anyway;
391
+ * - red (first attempt or after its re-run) → declined, holds nothing;
392
+ * - pending, or a run list that could not be read → held (fail closed: a pause clears itself);
393
+ * - no run yet → held for `graceSec` after it was built, then released (its run never came);
394
+ * - green → held for `graceSec` after it went green — its lander lands it on its next call —
395
+ * then released: a green batch nobody lands is abandoned, and must not hold the lane forever.
396
+ * An unread time (built/settled) is released, never held: a hold has to be provably alive.
397
+ */
398
+ const LANE_GRACE_SEC = 900;
399
+
400
+ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {}) {
401
+ const now = String(trunkNow || '');
402
+ const released = [];
403
+ if (!now) return { held: false, released };
404
+ const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
405
+ const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
406
+ for (const b of (Array.isArray(batches) ? batches : [])) {
407
+ if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
408
+ const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
409
+ if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
410
+ if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
411
+ if (v.state === 'none') {
412
+ if (fresh(b.builtAtMs)) return { held: true, ref: b.ref, why: `built ${mins(b.builtAtMs)}, its combined run has not appeared yet` };
413
+ released.push({ ref: b.ref, why: Number.isFinite(b.builtAtMs)
414
+ ? `no combined run ${mins(b.builtAtMs)} after it was built (grace ${graceSec}s) — treated as abandoned`
415
+ : 'no combined run, and its build time could not be read — not provably alive' });
416
+ continue;
417
+ }
418
+ 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` };
419
+ released.push({ ref: b.ref, why: Number.isFinite(b.settledAtMs)
420
+ ? `combined run green ${mins(b.settledAtMs)} and still not landed (grace ${graceSec}s) — treated as abandoned`
421
+ : 'combined run green, but when it went green could not be read — not provably alive' });
422
+ }
423
+ return { held: false, released };
424
+ }
425
+
426
+ /** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
427
+ function settledAt(rows) {
428
+ const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
429
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
430
+ return t.length ? Math.max(...t) : null;
431
+ }
432
+
373
433
  /**
374
434
  * #415: branches the command line names that a staged batch does not carry, in command-line order.
375
435
  * `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
@@ -430,4 +490,5 @@ module.exports = {
430
490
  droppedTrailer, parseDroppedTrailers, appendTrailers,
431
491
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
432
492
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
493
+ LANE_GRACE_SEC, laneHold, settledAt,
433
494
  };