@futurelastic/colab-handbook 1.13.0-rc.22 → 1.13.0-rc.24

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
@@ -1304,6 +1304,17 @@ function auditRepo(target, ctx) {
1304
1304
  }
1305
1305
  }
1306
1306
 
1307
+ // ---- ship-batch-wait (#555) -------------------------------------------------
1308
+ // How long a lone ready candidate waits for a partner (tools/lib/ship-batch.js parseShipBatchWait,
1309
+ // the reading `colab ship --batch` uses). Malformed fails here and in the CI templates' descriptor
1310
+ // check, the #416 pattern — ship fails closed to no wait, silently. A window with no batch to fill
1311
+ // (ship-batch absent or 1) is inert, so it warns. No ceiling: the repo chooses the value.
1312
+ if ("ship-batch-wait" in (cfg || {}) && cfg["ship-batch-wait"] !== null) {
1313
+ const wCfg = shipBatch.parseShipBatchWait(cfg);
1314
+ if (!wCfg.valid) fail(`${wCfg.reason} — see project.schema.md, ship-batch-wait`);
1315
+ else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1316
+ }
1317
+
1307
1318
  // ---- migrations (#383) ----------------------------------------------------
1308
1319
  // Where the repo's migrations live, beyond the two defaults (database/migrations/,
1309
1320
  // prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.22"
36
+ "version": "1.13.0-rc.24"
37
37
  }
@@ -263,23 +263,39 @@ jobs:
263
263
  # green; only a ship dry run noticed. So the value fails HERE, where the person
264
264
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
265
265
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
266
- # cap is 3: project.schema.md, `ship-batch`.
266
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
267
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
267
268
  # ---------------------------------------------------------------------------
268
269
  - name: Descriptor check (.github/project.yml)
269
270
  working-directory: ${{ github.workspace }}
270
271
  run: |
271
272
  [ -f .github/project.yml ] || exit 0
272
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
273
- [ -n "$line" ] || exit 0
274
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
273
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
274
+ field() {
275
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
276
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
275
277
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
276
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
278
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
279
+ }
280
+ v="$(field ship-batch)"
277
281
  case "$v" in
278
282
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
279
283
  *)
280
284
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
281
285
  exit 1 ;;
282
286
  esac
287
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
288
+ w="$(field ship-batch-wait)"
289
+ case "$w" in
290
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
291
+ *)
292
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
293
+ echo "ship-batch-wait: $w — ok"
294
+ else
295
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
296
+ exit 1
297
+ fi ;;
298
+ esac
283
299
 
284
300
  # ---------------------------------------------------------------------------
285
301
  # Toolchain resolution. Precedence, highest first:
@@ -13,7 +13,8 @@
13
13
  # `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
14
14
  #
15
15
  # What it does:
16
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
16
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
17
+ # ship-batch-wait, #555).
17
18
  # 1. Resolve the Node version from declared sources — never a hardcoded default.
18
19
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
19
20
  # 3. Install dependencies with the package manager the lockfile implies.
@@ -257,23 +258,39 @@ jobs:
257
258
  # green; only a ship dry run noticed. So the value fails HERE, where the person
258
259
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
259
260
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
260
- # cap is 3: project.schema.md, `ship-batch`.
261
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
262
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
261
263
  # ---------------------------------------------------------------------------
262
264
  - name: Descriptor check (.github/project.yml)
263
265
  working-directory: ${{ github.workspace }}
264
266
  run: |
265
267
  [ -f .github/project.yml ] || exit 0
266
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
267
- [ -n "$line" ] || exit 0
268
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
268
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
269
+ field() {
270
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
271
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
269
272
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
270
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
273
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
274
+ }
275
+ v="$(field ship-batch)"
271
276
  case "$v" in
272
277
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
273
278
  *)
274
279
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
275
280
  exit 1 ;;
276
281
  esac
282
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
283
+ w="$(field ship-batch-wait)"
284
+ case "$w" in
285
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
286
+ *)
287
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
288
+ echo "ship-batch-wait: $w — ok"
289
+ else
290
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
291
+ exit 1
292
+ fi ;;
293
+ esac
277
294
 
278
295
  # ---------------------------------------------------------------------------
279
296
  # Toolchain resolution. Precedence, highest first:
@@ -27,7 +27,8 @@
27
27
  # NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
28
28
  #
29
29
  # What it does:
30
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
30
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
31
+ # ship-batch-wait, #555).
31
32
  # 1. Resolve the Python version from declared sources — never a hardcoded default.
32
33
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
33
34
  # 3. Install dependencies from whichever manifest the repo actually has.
@@ -248,23 +249,39 @@ jobs:
248
249
  # green; only a ship dry run noticed. So the value fails HERE, where the person
249
250
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
250
251
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
251
- # cap is 3: project.schema.md, `ship-batch`.
252
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
253
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
252
254
  # ---------------------------------------------------------------------------
253
255
  - name: Descriptor check (.github/project.yml)
254
256
  working-directory: ${{ github.workspace }}
255
257
  run: |
256
258
  [ -f .github/project.yml ] || exit 0
257
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
258
- [ -n "$line" ] || exit 0
259
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
259
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
260
+ field() {
261
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
262
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
260
263
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
261
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
264
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
265
+ }
266
+ v="$(field ship-batch)"
262
267
  case "$v" in
263
268
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
264
269
  *)
265
270
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
266
271
  exit 1 ;;
267
272
  esac
273
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
274
+ w="$(field ship-batch-wait)"
275
+ case "$w" in
276
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
277
+ *)
278
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
279
+ echo "ship-batch-wait: $w — ok"
280
+ else
281
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
282
+ exit 1
283
+ fi ;;
284
+ esac
268
285
 
269
286
  # ---------------------------------------------------------------------------
270
287
  # Toolchain resolution. Precedence, highest first:
package/tools/colab CHANGED
@@ -1851,7 +1851,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
1851
1851
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1852
1852
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
1853
1853
 
1854
- 1. fetches tags, picks the newest open candidate (never a hand-made or off-main one);
1854
+ 1. fetches tags, picks the newest open candidate — or the one --tag names (never a hand-made or
1855
+ off-main one);
1855
1856
  2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
1856
1857
  starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
1857
1858
  3. measures, and ends in exactly one state:
@@ -1884,7 +1885,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1884
1885
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1885
1886
  trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1886
1887
  another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1887
- none red — required only where the final is automatic
1888
+ none red — required only where the final is automatic, or for an older --tag (#548)
1888
1889
 
1889
1890
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1890
1891
  the final equals every declared manifest version, its commit is on main (a shallow
@@ -1906,7 +1907,11 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1906
1907
  never tags: it stops at candidate-ready and posts the one command, number
1907
1908
  pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
1908
1909
  already-final exit 0 (nothing to do yet is the ordinary output)
1909
- --tag <rc> pin the candidate a human reviewed; refused unless it is the newest one
1910
+ --tag <rc> pin the candidate a human reviewed — the newest one, or any OLDER open candidate
1911
+ (#548). An older one is judged on its own clock exactly as --auto judges it: its
1912
+ own test period must have elapsed and trunk-green is read over its own window, on
1913
+ every row; release-hold and regressions as always. Newer candidates stay open
1914
+ for the next version — only versions below the final are closed as superseded
1910
1915
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
1911
1916
  No field, flag or project.yml value lowers it, and it never shortens a test period.
1912
1917
  Where the final is a human act the period is informational anyway, and
@@ -1982,6 +1987,8 @@ function cmdReleaseFinalize(argv) {
1982
1987
  const newest = selection.kind === 'candidate' ? selection.candidate : null;
1983
1988
  // #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
1984
1989
  const walk = opts.auto && policy.effective.final === 'auto' && newest;
1990
+ // #548: --tag naming an older open candidate — judged on its own clock, as the walk judges it.
1991
+ const ownClock = walk || (selection.kind === 'candidate' && !!selection.older);
1985
1992
 
1986
1993
  // ---- the tracking records (one issue read for the whole run) ----
1987
1994
  const issues = readAllIssuesForSwitches(repoAbs);
@@ -2040,7 +2047,7 @@ function cmdReleaseFinalize(argv) {
2040
2047
  return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
2041
2048
  }));
2042
2049
  const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
2043
- periodStart: period.start, periodEnd: walk ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2050
+ periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2044
2051
  });
2045
2052
  const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
2046
2053
  const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
@@ -2119,7 +2126,7 @@ function cmdReleaseFinalize(argv) {
2119
2126
  const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2120
2127
  if (!opts.dry) {
2121
2128
  if (verdict.state === 'finalized') {
2122
- const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}`;
2129
+ const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2123
2130
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2124
2131
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2125
2132
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2143,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
2143
2150
  const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2144
2151
  comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
2145
2152
  ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — no test period on this repo (\`release.test-period: 0d\`, #549): the human's finalize is the test.`
2146
- : walk
2153
+ : ownClock
2147
2154
  ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its own test period runs ${pNew.start} → ${pNew.endsAt}. A newer candidate does not restart an older one's clock: the newest candidate clean for its own period is finalized (\`--auto\`).`
2148
2155
  : `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
2149
2156
  }
@@ -2160,12 +2167,14 @@ function cmdReleaseFinalize(argv) {
2160
2167
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2161
2168
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2162
2169
  if (tagged) announced = announceRelease(cand.version, cand.sha);
2163
- // Superseded records. Without --auto: every other open, unheld, non-final version (the newest one
2164
- // is the only one ever finalized). With --auto: only versions BELOW one just tagged — a newer
2165
- // version's candidates are still on their own clocks.
2166
- if (cand && (!walk || tagged)) {
2170
+ // Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
2171
+ // without --auto closed every other open version at once, because only the newest candidate could
2172
+ // ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
2173
+ // to stay open until a final above it exists — closing it earlier refuses that --tag ("closed but
2174
+ // not final"). A newer version's candidates are still on their own clocks either way.
2175
+ if (cand && tagged) {
2167
2176
  for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
2168
- && (!walk || releaseFinalize.compareVersions(x.version, cand.version) < 0))) {
2177
+ && releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
2169
2178
  comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
2170
2179
  close(r.number);
2171
2180
  }
@@ -10342,6 +10351,12 @@ at build, added since) is NOT landed with it — the command names both lists an
10342
10351
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10343
10352
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10344
10353
  Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
10354
+ PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
10355
+ unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10356
+ ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10357
+ since the member became ready (its head CI's last update, else its head commit's date) — then the same
10358
+ call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10359
+ --batch with all of them. A single named branch is accepted only when the field is set.
10345
10360
 
10346
10361
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10347
10362
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -13900,7 +13915,10 @@ function cmdShipBatch(opts) {
13900
13915
  if (String(doc.autonomy || '') !== 'auto-trunk') {
13901
13916
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
13902
13917
  }
13903
- if (members.length < 2) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
13918
+ // #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
13919
+ const waitCfg = shipBatch.parseShipBatchWait(doc);
13920
+ if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
13921
+ if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
13904
13922
  if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
13905
13923
 
13906
13924
  const remote = git.remoteFor(repoAbs);
@@ -14039,6 +14057,22 @@ function cmdShipBatch(opts) {
14039
14057
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14040
14058
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14041
14059
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14060
+ if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14061
+ // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14062
+ // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14063
+ const lone = selected[0];
14064
+ const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
14065
+ const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
14066
+ const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
14067
+ if (pw.wait) {
14068
+ print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
14069
+ print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14070
+ print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
14071
+ return 3;
14072
+ }
14073
+ const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
14074
+ return serial(`1 member can join and no partner arrived — ${why}`);
14075
+ }
14042
14076
  if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
14043
14077
 
14044
14078
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
@@ -94,6 +94,8 @@ function restRow(x) {
94
94
  return {
95
95
  headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
96
96
  createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
97
+ // #555: a finished run's last update is its completion — when a lone batch member became ready.
98
+ updatedAt: x.updated_at || null,
97
99
  event: x.event || null, url: x.html_url || null,
98
100
  // #510: the workflow FILE's id — the cure rule's same-workflow test, which a display name cannot answer.
99
101
  workflowId: x.workflow_id ?? null,
package/tools/lib/git.js CHANGED
@@ -960,7 +960,8 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
960
960
  // does not own) before it computes a verdict, and can only do that if the row says so.
961
961
  // workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
962
962
  // id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
963
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
963
+ // updatedAt is additive (#555): a finished run's completion time, the lone-member wait's anchor.
964
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
964
965
  if (!r.ok) return null;
965
966
  let runs;
966
967
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -39,6 +39,12 @@
39
39
  * On a route whose final is a human act (`deploy-tag`) --auto never tags: it stops at
40
40
  * candidate-ready and posts the one command, number pre-filled.
41
41
  *
42
+ * `--tag` (#548) may name ANY open candidate, not only the newest, so a human can release what
43
+ * finished testing without trunk freezing for a whole period. An older one is held to the same rule
44
+ * --auto applies to it: its own test period and its own trunk window are required on every row
45
+ * (selectCandidate marks it `older`; decide() reads that). Newer candidates stay open, and a
46
+ * version's record closes as superseded only once a final ABOVE it is tagged.
47
+ *
42
48
  * Before ANY final, the three #424 pre-tag checks (release-tag.js preTagChecks) are required:
43
49
  * manifest-version, on-trunk, outranks-final.
44
50
  *
@@ -134,6 +140,8 @@ function trackingBody({ version, row, final, testPeriodDays }) {
134
140
  * { kind: 'already-final', version, detail }
135
141
  * { kind: 'refused', detail }
136
142
  * { kind: 'candidate', candidate: { tag, version, n, sha, cutAt }, superseded: [version], detail }
143
+ * { kind: 'candidate', older: true, newest: <tag>, … } #548: `pin` names an open candidate that
144
+ * is not the newest — decide() then requires its own test period and trunk window, as --auto does
137
145
  */
138
146
  function selectCandidate(tags, pin, remote = 'origin') {
139
147
  const all = tags || [];
@@ -159,16 +167,32 @@ function selectCandidate(tags, pin, remote = 'origin') {
159
167
  const newest = open[open.length - 1];
160
168
  const superseded = [...new Set(open.map((x) => x.p.version).filter((v) => v !== newest.p.version))];
161
169
 
162
- if (pin && pin !== newest.t.name) {
163
- return { kind: 'refused', detail: `--tag ${pin} is not the newest candidate (${newest.t.name}) — a final names the candidate that was actually tested last` };
164
- }
165
- const t = newest.t;
170
+ // #548: --tag may name an OLDER open candidate. It is then judged on its own clock, exactly as
171
+ // --auto judges it (decide() makes test-period and trunk-green over its own window required), so a
172
+ // human can release what finished testing while trunk keeps merging; the newer candidates stay open.
173
+ const chosen = pin ? open.find((x) => x.t.name === pin) : newest;
174
+ if (!chosen) return { kind: 'refused', detail: `--tag ${pin} is not an open candidate` };
175
+ const older = chosen !== newest;
176
+ const t = chosen.t;
166
177
  if (!t.annotated || !String(t.subject || '').endsWith(CUT_SUBJECT_SUFFIX)) {
167
178
  return { kind: 'refused', detail: `${t.name} was not made by \`colab release cut\` (not an annotated tag whose message ends "${CUT_SUBJECT_SUFFIX}") — a candidate cut by hand is never finalized (CONVENTIONS.md §6)` };
168
179
  }
169
180
  if (!t.onMain) return { kind: 'refused', detail: `${t.name} (${String(t.sha).slice(0, 7)}) is not on ${remote}/main — candidates are cut from main` };
170
181
  if (!t.date || Number.isNaN(Date.parse(t.date))) return { kind: 'refused', detail: `${t.name} has no readable tagger date — the test period cannot be placed` };
171
182
 
183
+ if (older) {
184
+ // Only versions BELOW the pinned one are superseded by it; a newer version's candidates stay open.
185
+ const below = [...new Set(open.map((x) => x.p.version).filter((v) => compareVersions(v, chosen.p.version) < 0))];
186
+ const newer = open.filter((x) => compareVersions(x.p.version, chosen.p.version) > 0 || (x.p.version === chosen.p.version && x.p.n > chosen.p.n)).map((x) => x.t.name);
187
+ return {
188
+ kind: 'candidate',
189
+ older: true,
190
+ newest: newest.t.name,
191
+ candidate: { tag: t.name, version: chosen.p.version, n: chosen.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
192
+ superseded: below,
193
+ detail: `${t.name} at ${String(t.sha).slice(0, 7)}, cut ${new Date(t.date).toISOString()} — an older candidate, judged on its own clock (newer, still open: ${newer.join(', ')})${below.length ? `; supersedes ${below.join(', ')}` : ''}`,
194
+ };
195
+ }
172
196
  return {
173
197
  kind: 'candidate',
174
198
  candidate: { tag: t.name, version: newest.p.version, n: newest.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
@@ -523,10 +547,14 @@ function decide(facts) {
523
547
  }
524
548
  const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
525
549
  add('regressions', reg.ok, reg.detail);
550
+ // #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
551
+ // --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
552
+ // no longer explains why THIS one, and its own clean period is what does.
553
+ const ownClock = auto || !!s.older;
526
554
  const per = f.period || { elapsed: false, detail: 'not measured' };
527
- add('test-period', per.elapsed, per.detail, auto);
555
+ 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);
528
556
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
529
- add('trunk-green', tr.ok, tr.detail, auto);
557
+ add('trunk-green', tr.ok, tr.detail, ownClock);
530
558
  for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
531
559
  add(condition, v && v.ok, v ? v.detail : 'not measured');
532
560
  }
@@ -539,14 +567,14 @@ function decide(facts) {
539
567
  }
540
568
 
541
569
  if (held.length) return out('held');
542
- if ((reg.permanent) || (auto && tr.permanent)) return out('needs-new-candidate');
570
+ if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
543
571
  const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
544
572
  if (blocking.length) return out('refused');
545
- if (auto) {
573
+ if (ownClock) {
546
574
  if (!tr.ok && !tr.pending) return out('refused');
547
575
  if (!per.elapsed || tr.pending) return out('testing');
548
- return out('finalized', { finalTag: cand.version, grant: grantUsed });
549
576
  }
577
+ if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
550
578
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
551
579
  return out('finalized', { finalTag: cand.version });
552
580
  }
@@ -46,6 +46,70 @@ function parseShipBatch(doc) {
46
46
  return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
47
47
  }
48
48
 
49
+ const WAIT_KEY = 'ship-batch-wait';
50
+ const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
+
52
+ /**
53
+ * #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
55
+ * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
+ *
57
+ * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
58
+ * (owner, 2026-10-07: "Should not set any hard code number") — the repo chooses, from its own
59
+ * history. Anything malformed FAILS CLOSED to no wait, with the reason: a bad value must never delay
60
+ * a landing. The audit and the CI templates' descriptor check fail the same values.
61
+ */
62
+ function parseShipBatchWait(doc) {
63
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, WAIT_KEY);
64
+ if (!has || doc[WAIT_KEY] === null || doc[WAIT_KEY] === undefined) {
65
+ return { sec: 0, declared: false, valid: true, reason: `${WAIT_KEY} absent` };
66
+ }
67
+ const v = doc[WAIT_KEY];
68
+ const m = typeof v === 'string' ? /^(\d+)([smh])$/.exec(v.trim()) : null;
69
+ if (m) {
70
+ const sec = Number(m[1]) * WAIT_UNITS[m[2]];
71
+ if (Number.isSafeInteger(sec)) return { sec, declared: true, valid: true, reason: `${WAIT_KEY}: ${v.trim()}` };
72
+ }
73
+ return { sec: 0, declared: true, valid: false, reason: `${WAIT_KEY} is ${JSON.stringify(v)}, expected a whole number with a unit — 90s, 6m, 1h (omit for no wait)` };
74
+ }
75
+
76
+ /**
77
+ * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
78
+ * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
+ * already in flight — the lane is otherwise idle by then):
80
+ * n parseShipBatch(doc).n
81
+ * waitSec parseShipBatchWait(doc).sec (0 = absent, zero, or malformed)
82
+ * eligibleCount members that passed their own gates
83
+ * readySinceMs when the lone member became ready — its head CI's last update, else its head
84
+ * commit's date; null = unreadable
85
+ * nowMs the clock
86
+ * Out: `{ wait: true, leftSec }` or `{ wait: false, reason }`. The window is counted from the member's
87
+ * own ready time, not from this call, so the command stays stateless and re-entrant: every call
88
+ * re-derives how much is left, on any machine, and the window can never restart.
89
+ */
90
+ function partnerWait({ n, waitSec, eligibleCount, readySinceMs, nowMs }) {
91
+ if (!(n > 1)) return { wait: false, reason: 'not-enabled' };
92
+ if (!(waitSec > 0)) return { wait: false, reason: 'no-window' };
93
+ if (eligibleCount !== 1) return { wait: false, reason: eligibleCount > 1 ? 'has-partner' : 'none-ready' };
94
+ if (!Number.isFinite(readySinceMs) || !Number.isFinite(nowMs)) return { wait: false, reason: 'ready-time-unread' };
95
+ const leftSec = Math.ceil(waitSec - Math.max(0, nowMs - readySinceMs) / 1000);
96
+ if (leftSec <= 0) return { wait: false, reason: 'window-elapsed' };
97
+ return { wait: true, leftSec };
98
+ }
99
+
100
+ /**
101
+ * When did a member become ready? The newest `updatedAt` among its finished head runs (a run's last
102
+ * update is its completion), else — no run, because none can arrive — its head commit's date.
103
+ * Null when neither reads; the caller then does not wait.
104
+ */
105
+ function readySince(rows, commitIso) {
106
+ const done = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
107
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
108
+ if (done.length) return Math.max(...done);
109
+ const c = Date.parse(commitIso || '');
110
+ return Number.isFinite(c) ? c : null;
111
+ }
112
+
49
113
  function batchRefName(baseSha) {
50
114
  return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
51
115
  }
@@ -315,8 +379,8 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
315
379
  }
316
380
 
317
381
  module.exports = {
318
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
319
- parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
382
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY,
383
+ parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
320
384
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
321
385
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
322
386
  };