@futurelastic/colab-handbook 1.13.0-rc.21 → 1.13.0-rc.23

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.21"
36
+ "version": "1.13.0-rc.23"
37
37
  }
package/tools/colab CHANGED
@@ -522,8 +522,9 @@ function localClaimConflicts(st, repoAbs, nums, wtName) {
522
522
 
523
523
  /**
524
524
  * #325 — the claim record every machine can read, whatever the tracker: a branch on the remote whose
525
- * name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run; `code-start`
526
- * pushes the branch the moment it is cut). Asked of the remote directly (`ls-remote`, no fetch), so a
525
+ * name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run), or — since
526
+ * #550 — the claim ref `refs/claims/<branch>` that `colab worktree new` pushes the moment it cuts
527
+ * (a ref no CI trigger watches; the branch itself follows at code-wrap). Asked of the remote directly (`ls-remote`, no fetch), so a
527
528
  * clone that has never fetched sees exactly what a fresh one would.
528
529
  *
529
530
  * `mode`:
@@ -558,7 +559,7 @@ function remoteClaimConflicts(st, repoAbs, nums) {
558
559
  for (const h of heads.heads) {
559
560
  const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
560
561
  if (!carried.length || ours(h.branch)) continue;
561
- for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
562
+ for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha, claimRef: !!h.claimRef });
562
563
  }
563
564
  return { mode: 'ok', remote, conflicts };
564
565
  }
@@ -667,13 +668,18 @@ function ghClaimConflicts(repoAbs, nums, myLogin, myHost, mySession, comps, myMa
667
668
  function printRefusal(localConf, ghConf, remoteConf = []) {
668
669
  process.stderr.write('✗ Refusing — one or more issues are already claimed:\n');
669
670
  for (const c of remoteConf) {
670
- process.stderr.write(` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
671
+ process.stderr.write(c.claimRef
672
+ ? ` #${c.num} remote: claim ref ${c.remote} ${git.claimRef(c.branch)} @ ${c.sha} carries it (branch not pushed yet), and it is not this machine's (#325, #550)\n`
673
+ : ` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
671
674
  }
672
675
  if (remoteConf.length) {
673
676
  const c = remoteConf[0];
674
- process.stderr.write(' That branch IS the claim — continue it rather than open a second one:\n');
675
- process.stderr.write(` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
677
+ process.stderr.write(` That ${c.claimRef ? 'claim ref' : 'branch'} IS the claim — continue it rather than open a second one:\n`);
678
+ process.stderr.write(c.claimRef
679
+ ? ` git fetch ${c.remote} ${git.claimRef(c.branch)}:refs/heads/${c.branch} && git worktree add <path> ${c.branch}\n`
680
+ : ` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
676
681
  process.stderr.write(` colab claim ${c.num} --worktree <name> --branch ${c.branch} --session <id> --force\n`);
682
+ if (c.claimRef) process.stderr.write(` A claim ref whose session is gone is stale — delete it: git push ${c.remote} --delete ${git.claimRef(c.branch)}\n`);
677
683
  }
678
684
  for (const c of localConf) {
679
685
  const h = c.holder;
@@ -710,7 +716,7 @@ function halfClaimText(c) {
710
716
  /** Announce exactly what --force overrides (a takeover is visible, never silent). */
711
717
  function printTakeover(localConf, ghConf, remoteConf = []) {
712
718
  for (const c of remoteConf) {
713
- print(` --force: taking over #${c.num} although branch ${c.remote}/${c.branch} @ ${c.sha} carries it (not this machine's)`);
719
+ print(` --force: taking over #${c.num} although ${c.claimRef ? `claim ref ${c.remote} ${git.claimRef(c.branch)}` : `branch ${c.remote}/${c.branch}`} @ ${c.sha} carries it (not this machine's)`);
714
720
  }
715
721
  for (const c of localConf) {
716
722
  const h = c.holder;
@@ -877,7 +883,8 @@ const HELP_CLAIM = `colab claim <issue> [<issue> ...] [options]
877
883
 
878
884
  Claim one or more GitHub issues so parallel sessions/agents don't collide.
879
885
  The claim RECORD every machine reads is a branch on the git remote carrying the issue number
880
- (\`colab worktree new\` pushes it the moment it is cut, #325). Also writes local state (fast path)
886
+ (\`colab worktree new\` records it the moment it is cut as the claim ref refs/claims/<branch>,
887
+ which no CI trigger watches — #325, #550). Also writes local state (fast path)
881
888
  and the tracker (the copy people read):
882
889
  gh issue edit N --add-assignee @me --add-label in-progress
883
890
  Remote unreachable → REFUSED (fail closed). Tracker unreachable → the claim stands and its tracker
@@ -1844,7 +1851,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
1844
1851
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1845
1852
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
1846
1853
 
1847
- 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);
1848
1856
  2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
1849
1857
  starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
1850
1858
  3. measures, and ends in exactly one state:
@@ -1877,7 +1885,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1877
1885
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1878
1886
  trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1879
1887
  another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1880
- 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)
1881
1889
 
1882
1890
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1883
1891
  the final equals every declared manifest version, its commit is on main (a shallow
@@ -1899,7 +1907,11 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1899
1907
  never tags: it stops at candidate-ready and posts the one command, number
1900
1908
  pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
1901
1909
  already-final exit 0 (nothing to do yet is the ordinary output)
1902
- --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
1903
1915
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
1904
1916
  No field, flag or project.yml value lowers it, and it never shortens a test period.
1905
1917
  Where the final is a human act the period is informational anyway, and
@@ -1975,6 +1987,8 @@ function cmdReleaseFinalize(argv) {
1975
1987
  const newest = selection.kind === 'candidate' ? selection.candidate : null;
1976
1988
  // #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
1977
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);
1978
1992
 
1979
1993
  // ---- the tracking records (one issue read for the whole run) ----
1980
1994
  const issues = readAllIssuesForSwitches(repoAbs);
@@ -2033,7 +2047,7 @@ function cmdReleaseFinalize(argv) {
2033
2047
  return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
2034
2048
  }));
2035
2049
  const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
2036
- 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,
2037
2051
  });
2038
2052
  const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
2039
2053
  const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
@@ -2112,7 +2126,7 @@ function cmdReleaseFinalize(argv) {
2112
2126
  const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2113
2127
  if (!opts.dry) {
2114
2128
  if (verdict.state === 'finalized') {
2115
- 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})` : ''}`;
2116
2130
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2117
2131
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2118
2132
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2136,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
2136
2150
  const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2137
2151
  comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
2138
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.`
2139
- : walk
2153
+ : ownClock
2140
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\`).`
2141
2155
  : `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
2142
2156
  }
@@ -2153,12 +2167,14 @@ function cmdReleaseFinalize(argv) {
2153
2167
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2154
2168
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2155
2169
  if (tagged) announced = announceRelease(cand.version, cand.sha);
2156
- // Superseded records. Without --auto: every other open, unheld, non-final version (the newest one
2157
- // is the only one ever finalized). With --auto: only versions BELOW one just tagged — a newer
2158
- // version's candidates are still on their own clocks.
2159
- 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) {
2160
2176
  for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
2161
- && (!walk || releaseFinalize.compareVersions(x.version, cand.version) < 0))) {
2177
+ && releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
2162
2178
  comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
2163
2179
  close(r.number);
2164
2180
  }
@@ -5587,23 +5603,30 @@ function cmdWorktreeNew(argv) {
5587
5603
  // rejected instead of overwriting. With issues to claim, a failed push takes nothing: the worktree
5588
5604
  // and the zero-commit branch this invocation just made are removed again, so no half-claim exists
5589
5605
  // anywhere. With no issues there is no claim to protect, and a failed push only warns.
5606
+ //
5607
+ // #550: what is pushed is the CLAIM REF `refs/claims/<branch>`, not the branch. A branch push fires
5608
+ // every CI `push` trigger, and at cut the branch IS trunk's commit — so each cut re-ran a suite
5609
+ // trunk had already passed (~27 % of one org's runs). A claim ref triggers nothing, and every
5610
+ // claim reader (`remoteHeads`) lists it beside the branches. The branch itself is first pushed at
5611
+ // code-wrap, when it has commits worth testing. The claim ref is deleted at `worktree rm`.
5590
5612
  const pushRemote = git.claimRemote(repoAbs);
5591
5613
  let pushed = false;
5592
5614
  if (pushRemote) {
5593
- const push = git.git(['push', '-u', pushRemote, `--force-with-lease=refs/heads/${branch}:`, branch], repoAbs, { timeoutMs: 120_000 });
5615
+ const claimRef = git.claimRef(branch);
5616
+ const push = git.pushClaimRef(repoAbs, pushRemote, branch);
5594
5617
  if (push.ok) {
5595
5618
  pushed = true;
5596
- print(` pushed ${branch} → ${pushRemote} (the claim record other machines read)`);
5619
+ print(` pushed ${claimRef} → ${pushRemote} (the claim record other machines read; not a branch, so no CI runs — the branch is pushed at code-wrap)`);
5597
5620
  } else {
5598
5621
  const why = String(push.stderr || '').split('\n').filter(Boolean).slice(-1)[0] || `exit ${push.code}`;
5599
5622
  if (issues.length) {
5600
5623
  git.git(['worktree', 'remove', '--force', wtPath], repoAbs);
5601
5624
  git.git(['branch', '-D', branch], repoAbs);
5602
- throw new UserError(`git push ${pushRemote} ${branch} failed (${why}) — claim NOT taken: the worktree and branch ` +
5603
- 'were removed again. The pushed branch is the claim record other machines read (#325); fix the push ' +
5604
- '(access, network, or a branch of that name another machine just created) and re-run.');
5625
+ throw new UserError(`git push ${pushRemote} ${claimRef} failed (${why}) — claim NOT taken: the worktree and branch ` +
5626
+ 'were removed again. The pushed claim ref is the record other machines read (#325, #550); fix the push ' +
5627
+ `(access, network, or a claim ref of that name another machine just created — \`git ls-remote ${pushRemote} ${claimRef}\`) and re-run.`);
5605
5628
  }
5606
- warn(`git push ${pushRemote} ${branch} failed (${why}) — worktree created, branch not on the remote yet`);
5629
+ warn(`git push ${pushRemote} ${claimRef} failed (${why}) — worktree created, no claim ref on the remote`);
5607
5630
  }
5608
5631
  }
5609
5632
 
@@ -5625,14 +5648,14 @@ function cmdWorktreeNew(argv) {
5625
5648
  }
5626
5649
 
5627
5650
  // 3. allocate ports + record worktree + claims (atomic)
5628
- // #325: if recording fails after the push above, take the pushed branch back off the remote —
5651
+ // #325: if recording fails after the push above, take the pushed claim ref back off the remote —
5629
5652
  // otherwise it would stand there as a claim record nothing on any machine owns, refusing every
5630
5653
  // later claim on these issues. (The local worktree is left as before this change.)
5631
5654
  let alloc;
5632
5655
  try {
5633
5656
  alloc = allocWorktreeRecord();
5634
5657
  } catch (e) {
5635
- if (pushed) git.git(['push', pushRemote, '--delete', branch], repoAbs, { timeoutMs: 120_000 });
5658
+ if (pushed) git.deleteClaimRef(repoAbs, pushRemote, branch);
5636
5659
  throw e;
5637
5660
  }
5638
5661
  function allocWorktreeRecord() { return state.mutate((st) => {
@@ -5861,6 +5884,19 @@ function cmdWorktreeRm(argv) {
5861
5884
 
5862
5885
  print(`✓ Removed worktree "${name}"`);
5863
5886
  if (removal.action === 'rm-rf') print(' (directory was a husk from an earlier interrupted removal — cleaned up directly)');
5887
+ // #550: the claim ref `worktree new` pushed is this worktree's claim record on the remote — release
5888
+ // it with the claims, or it would stand there refusing every later claim on these issue numbers from
5889
+ // another machine. Best effort: an absent ref is fine (never pushed, a pre-#550 worktree, or already
5890
+ // gone), a failed delete only warns with the command, and nothing above is undone for it.
5891
+ if (wt.branch) {
5892
+ let claimRemoteName = null;
5893
+ try { claimRemoteName = git.claimRemote(repoAbs); } catch { claimRemoteName = null; }
5894
+ if (claimRemoteName) {
5895
+ const d = git.deleteClaimRef(repoAbs, claimRemoteName, wt.branch);
5896
+ if (d.ok && !d.absent) print(` deleted claim ref ${claimRemoteName} ${git.claimRef(wt.branch)}`);
5897
+ else if (!d.ok) warnDeferred(`could not delete claim ref ${claimRemoteName} ${git.claimRef(wt.branch)} (${String(d.stderr || '').split('\n')[0]}) — delete it by hand: git push ${claimRemoteName} --delete ${git.claimRef(wt.branch)}`);
5898
+ }
5899
+ }
5864
5900
  // #114: this line used to report `removed.claims` — the LOCAL registry mutation, which cannot
5865
5901
  // fail for a network reason and so always read as full success. Report what the tracker actually
5866
5902
  // did instead, and name what it didn't.
package/tools/lib/git.js CHANGED
@@ -297,21 +297,70 @@ function claimRemote(repo) {
297
297
  }
298
298
 
299
299
  /**
300
- * Every branch head on `remoteName`, asked of the remote directly (`ls-remote --heads`, no fetch, no
301
- * local cache) — the claim record another machine can read (#325). Unlike `existingBranchRef`, a
302
- * failed ask is NOT "no branches": it returns `{ ok: false, stderr }` so the caller can refuse
303
- * (fail closed) instead of reading an unreachable remote as clear ground.
304
- * `{ ok: true, heads: [{ branch, sha }] }` otherwise, `sha` short (7).
300
+ * Every branch head on `remoteName` — plus every claim ref (`refs/claims/<branch>`, #550) — asked
301
+ * of the remote directly (`ls-remote`, no fetch, no local cache): the claim record another machine
302
+ * can read (#325). Unlike `existingBranchRef`, a failed ask is NOT "no branches": it returns
303
+ * `{ ok: false, stderr }` so the caller can refuse (fail closed) instead of reading an unreachable
304
+ * remote as clear ground. `{ ok: true, heads: [{ branch, sha, claimRef? }] }` otherwise, `sha` short
305
+ * (7) — `parseRemoteHeads`.
305
306
  */
306
307
  function remoteHeads(repo, remoteName) {
307
- const r = git(['ls-remote', '--heads', remoteName], repo, { timeoutMs: 60_000 });
308
+ const r = git(['ls-remote', remoteName, 'refs/heads/*', `${CLAIM_REF_PREFIX}*`], repo, { timeoutMs: 60_000 });
308
309
  if (!r.ok) return { ok: false, stderr: r.stderr || (r.timedOut ? 'ls-remote timed out' : `exit ${r.code}`) };
309
- const heads = [];
310
- for (const line of String(r.stdout || '').split('\n')) {
311
- const m = line.match(/^([0-9a-f]{7,})\s+refs\/heads\/(.+)$/);
312
- if (m) heads.push({ branch: m[2], sha: m[1].slice(0, 7) });
310
+ return { ok: true, heads: parseRemoteHeads(r.stdout) };
311
+ }
312
+
313
+ /**
314
+ * #550 — where `colab worktree new` records a claim at cut: `refs/claims/<branch>`, NOT the branch.
315
+ * A push to `refs/heads/<branch>` fires every CI `push` trigger, and at cut the branch is identical
316
+ * to trunk, so each claim re-ran the full suite on a commit trunk had already tested (measured: ~209
317
+ * of 230 duplicate runs in one org over 3 days, one sha run 8 times). GitHub fires `push` workflows
318
+ * for branches and tags only, so a ref outside both namespaces is a claim record every machine can
319
+ * still `ls-remote`, at zero CI cost (probed live 2026-10-07: a refs/claims push started no run).
320
+ * The branch itself reaches the remote at its first real push (code-wrap), where CI is wanted.
321
+ */
322
+ const CLAIM_REF_PREFIX = 'refs/claims/';
323
+ function claimRef(branch) { return `${CLAIM_REF_PREFIX}${branch}`; }
324
+
325
+ /**
326
+ * `ls-remote` output → `[{ branch, sha, claimRef? }]`, short sha. A `refs/claims/<b>` entry reads as
327
+ * branch `<b>` with `claimRef: true`; when the same name is ALSO a real branch, only the branch row is
328
+ * kept (it is the stronger record — it carries commits). Pure, for tests.
329
+ */
330
+ function parseRemoteHeads(stdout) {
331
+ const heads = new Map();
332
+ const claims = new Map();
333
+ for (const line of String(stdout || '').split('\n')) {
334
+ const m = line.match(/^([0-9a-f]{7,})\s+refs\/(heads|claims)\/(.+)$/);
335
+ if (!m) continue;
336
+ if (m[2] === 'heads') heads.set(m[3], { branch: m[3], sha: m[1].slice(0, 7) });
337
+ else claims.set(m[3], { branch: m[3], sha: m[1].slice(0, 7), claimRef: true });
313
338
  }
314
- return { ok: true, heads };
339
+ for (const [b, c] of claims) if (!heads.has(b)) heads.set(b, c);
340
+ return [...heads.values()];
341
+ }
342
+
343
+ /**
344
+ * Push the claim record for `branch` (#550): `<branch>:refs/claims/<branch>`, CREATE-ONLY
345
+ * (`--force-with-lease=<ref>:` with an empty expect), so two machines cutting one name still race on
346
+ * a real compare-and-swap and the loser is rejected. No `-u`: there is no remote branch to track yet.
347
+ */
348
+ function pushClaimRef(repo, remote, branch) {
349
+ const ref = claimRef(branch);
350
+ return git(['push', remote, `--force-with-lease=${ref}:`, `refs/heads/${branch}:${ref}`], repo, { timeoutMs: 120_000 });
351
+ }
352
+
353
+ /**
354
+ * Delete the claim record for `branch` from `remote` (#550). Idempotent: an absent ref is success
355
+ * (nothing to release), so teardown never fails on a claim that was never pushed or already gone.
356
+ */
357
+ function deleteClaimRef(repo, remote, branch) {
358
+ const ref = claimRef(branch);
359
+ const ls = git(['ls-remote', remote, ref], repo, { timeoutMs: 60_000 });
360
+ if (!ls.ok) return { ok: false, stderr: ls.stderr || `exit ${ls.code}` };
361
+ if (!String(ls.stdout || '').trim()) return { ok: true, absent: true };
362
+ const r = git(['push', remote, '--delete', ref], repo, { timeoutMs: 120_000 });
363
+ return { ok: r.ok, stderr: r.stderr };
315
364
  }
316
365
 
317
366
  /** List worktree paths registered in a repo (porcelain). */
@@ -1329,7 +1378,7 @@ module.exports = {
1329
1378
  ghCommitCheckRuns, ghCheckRunAnnotations,
1330
1379
  run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1331
1380
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1332
- claimRemote, remoteHeads,
1381
+ claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
1333
1382
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1334
1383
  dirtyTracked, dirtyUntracked, dirtyAny,
1335
1384
  ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
@@ -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
  }