@futurelastic/colab-handbook 1.17.0-rc.3 → 1.17.0-rc.4

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.17.0-rc.3"
36
+ "version": "1.17.0-rc.4"
37
37
  }
package/tools/colab CHANGED
@@ -11104,8 +11104,11 @@ It never waits: each call reads the remote, takes ONE step and exits —
11104
11104
  NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
11105
11105
  re-running hits the same refusal until its cause is fixed (#509)
11106
11106
  One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
11107
- is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
11108
- for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
11107
+ is pending, or green within ${shipBatch.LANE_GRACE_SEC / 60}m of settling (the serial doors' lane grace, below), but a declined one — its
11108
+ combined run red — is deleted and the batch you asked for is built in its place, so the survivors of a
11109
+ decline can batch without landing serially first (#391). A green one still unlanded past that grace lost
11110
+ its lander and is deleted and rebuilt the same way; a green one whose settle time cannot be read is
11111
+ still waited on — only a provably abandoned batch is deleted (#659).
11109
11112
  A call that goes serial on trunk CI not green gives up on its members, so it deletes every batch at
11110
11113
  trunk's tip whose members it ALL names (its run cancelled if still going) — nobody would ever land
11111
11114
  it, and it would hold this base for every later call; a batch also carrying another member stays (#656).
@@ -15483,15 +15486,23 @@ function cmdShipBatch(opts) {
15483
15486
  const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
15484
15487
  const foreign = inBatch.filter((m) => !members.includes(m.branch));
15485
15488
  // #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
15486
- const foreignStep = foreign.length ? shipBatch.foreignBatchStep(shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, atBase.parsed.ref, atBase.sha))) : null;
15489
+ // #659: nor is a green one past the lane grace (laneHold's rule) — its lander is gone.
15490
+ let foreignStep = null;
15491
+ if (foreign.length) {
15492
+ const runs = git.ghRunsForRef(repoAbs, atBase.parsed.ref, atBase.sha);
15493
+ foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
15494
+ }
15487
15495
  if (foreignStep && foreignStep.step === 'wait') {
15488
- print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}.`);
15496
+ print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}${foreignStep.why ? ` (${foreignStep.why})` : ''}.`);
15489
15497
  print(' Wait for it to land or be declined, then run this command again.');
15490
15498
  return 3;
15491
15499
  }
15492
15500
  if (foreignStep) {
15493
- print(` ${atBase.parsed.ref} (${inBatch.map((m) => m.branch).join(', ')}) was declined — its combined run is red (${foreignStep.why}); nothing landed from it. Deleting it and building the requested batch.`);
15494
- if (!opts.dry && !deleteRef(atBase.parsed.ref)) throw new UserError(`could not clear the declined ${atBase.parsed.ref} — delete it by hand, then run this command again`);
15501
+ const carried = inBatch.map((m) => m.branch).join(', ');
15502
+ print(foreignStep.reason === 'abandoned'
15503
+ ? ` ${atBase.parsed.ref} (${carried}) was abandoned — its ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch.`
15504
+ : ` ${atBase.parsed.ref} (${carried}) was declined — its combined run is red (${foreignStep.why}); nothing landed from it. Deleting it and building the requested batch.`);
15505
+ if (!opts.dry && !deleteRef(atBase.parsed.ref)) throw new UserError(`could not clear the ${foreignStep.reason === 'abandoned' ? 'abandoned' : 'declined'} ${atBase.parsed.ref} — delete it by hand (\`git push ${remote} --delete ${atBase.parsed.ref}\`), then run this command again`);
15495
15506
  }
15496
15507
  if (!foreignStep) {
15497
15508
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
@@ -462,12 +462,30 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
462
462
  * for. Is it still in flight, or already declined? Only a pending/green (or not-yet-run) batch is in
463
463
  * flight and may make the new request wait; a red one — first attempt or after its re-run — has
464
464
  * been declined (`red-rerun-or-serial` keeps its ref so the one re-run stays possible), and keeping
465
- * it would block every later batch at this base until trunk moved. So:
466
- * clear its combined run is red → delete the ref, then build the requested batch
467
- * wait anything else (pending, none, green, unreadable) → exit 3, exactly as before
465
+ * it would block every later batch at this base until trunk moved.
466
+ *
467
+ * #659: a GREEN one is in flight only for the grace the serial doors give it (laneHold): its lander
468
+ * lands it on its next call, so a green ref still at trunk's tip `graceSec` after its run settled has
469
+ * lost its lander (died after green, before the fast-forward) and would pause every batch at this
470
+ * base until trunk moved for some other reason — while the serial doors already release it. So:
471
+ * clear red → `reason: 'red'`; green, settled ≥ graceSec ago → `reason: 'abandoned'`
472
+ * → delete the ref, then build the requested batch
473
+ * wait anything else → exit 3: pending, none, green within the grace — and green whose settle
474
+ * time could not be read. That last one deliberately differs from laneHold, which releases
475
+ * it: deleting another caller's green run is not undoable, so the batch door clears only a
476
+ * provably abandoned ref (#391's pinned case, kept on purpose — recorded on #659).
477
+ * `settledAtMs` is settledAt() of the ref's runs; `nowMs` the clock.
468
478
  */
469
- function foreignBatchStep(verdict) {
470
- return verdict && verdict.state === 'red' ? { step: 'clear', why: verdict.why } : { step: 'wait' };
479
+ function foreignBatchStep(verdict, { settledAtMs = null, nowMs = null, graceSec = LANE_GRACE_SEC } = {}) {
480
+ if (verdict && verdict.state === 'red') return { step: 'clear', reason: 'red', why: verdict.why };
481
+ if (verdict && verdict.state === 'green' && Number.isFinite(settledAtMs) && Number.isFinite(nowMs)) {
482
+ const mins = Math.max(0, Math.round((nowMs - settledAtMs) / 60000));
483
+ if ((nowMs - settledAtMs) >= graceSec * 1000) {
484
+ return { step: 'clear', reason: 'abandoned', why: `combined run green ${mins}m ago and still not landed (grace ${graceSec}s) — treated as abandoned` };
485
+ }
486
+ return { step: 'wait', why: `combined run green ${mins}m ago — its lander lands it on its next call; past ${Math.round(graceSec / 60)}m unlanded it is cleared` };
487
+ }
488
+ return { step: 'wait' };
471
489
  }
472
490
 
473
491
  /**
@@ -475,7 +493,8 @@ function foreignBatchStep(verdict) {
475
493
  * green) is giving up on its members — they go to `colab ship --branch`, one at a time. A ref it
476
494
  * staged on an earlier call is then landed by nobody: no caller names that set again, and the ref
477
495
  * still reads "in flight" to the next `--batch` at the same base (foreignBatchStep waits on a green
478
- * ref forever) and to the serial doors (laneHold). Measured: one repo paused 14 h on such a ref.
496
+ * ref for LANE_GRACE_SEC since #659 — forever before it) and to the serial doors (laneHold).
497
+ * Measured: one repo paused 14 h on such a ref.
479
498
  *
480
499
  * Which refs this call abandons: those whose carried members are ALL named by this call. A ref that
481
500
  * also carries a member this call does not name belongs, at least in part, to another caller — it