@futurelastic/colab-handbook 1.13.0-rc.20 → 1.13.0-rc.22
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 +1 -1
- package/templates/release-auto.yml +65 -3
- package/tools/colab +43 -16
- package/tools/lib/git.js +61 -12
package/package.json
CHANGED
|
@@ -20,6 +20,9 @@
|
|
|
20
20
|
# hand-off where
|
|
21
21
|
# the final is a
|
|
22
22
|
# human's)
|
|
23
|
+
# an hourly schedule (#547) — the cut colab release cut --auto, only when main's head
|
|
24
|
+
# only, never promote or finalize has no tag AND the fetched CLI moved in the last
|
|
25
|
+
# RETRY_WINDOW_MINUTES (or a run here was displaced)
|
|
23
26
|
# workflow_dispatch all three, in that order
|
|
24
27
|
# any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
|
|
25
28
|
# project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
|
|
@@ -115,6 +118,23 @@
|
|
|
115
118
|
# pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
|
|
116
119
|
# applies to your deploy workflows exactly as before.
|
|
117
120
|
#
|
|
121
|
+
# A REFUSAL THE HANDBOOK FIXES IS RETRIED WITHIN THE HOUR (#547). A cut can be refused by a defect in
|
|
122
|
+
# the colab CLI rather than in your repo — a false positive in one of its checks. The fix reaches you
|
|
123
|
+
# when HANDBOOK_REF's channel moves, and nothing in your repo changes, so neither trigger above fires:
|
|
124
|
+
# the candidate would wait for your next merge or the next daily run (measured: ~2.5 h until a person
|
|
125
|
+
# dispatched it by hand, ~22 h otherwise). So an hourly run re-tries the CUT, and only the cut, when:
|
|
126
|
+
# - main's head carries no release tag yet (a head that has one has nothing to retry), and
|
|
127
|
+
# - the CLI this run fetched reached HANDBOOK_REF within RETRY_WINDOW_MINUTES — read from the date of
|
|
128
|
+
# the release tag at that commit (when the channel moved onto it), else the commit's own date; or
|
|
129
|
+
# - the newest other run of this workflow at main's head was cancelled. An hourly run shares the
|
|
130
|
+
# `release-auto` concurrency group, and GitHub cancels a PENDING run in a group when a newer one
|
|
131
|
+
# queues — so an hourly run can displace the very run a merge started. It then does that run's cut.
|
|
132
|
+
# Every other hourly run checks those and stops: no cut, no promotion, no finalize, so a held head is
|
|
133
|
+
# not tagged sooner than the daily run would tag it, and a standing refusal is not re-announced every
|
|
134
|
+
# hour. Nothing is stored between runs; the facts are re-read each time. EDIT: the cron string inside
|
|
135
|
+
# RETRY_RUN (release job env) must stay byte-identical to the hourly `cron:` line, or no run is
|
|
136
|
+
# recognised as a retry run — and the hourly run would then promote and finalize every hour.
|
|
137
|
+
#
|
|
118
138
|
# A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
|
|
119
139
|
# failed) is the ordinary output of most runs; it is printed to the run summary as a
|
|
120
140
|
# warning and the job stays green, so a refusal never paints main red for `colab ship`.
|
|
@@ -170,6 +190,9 @@ on:
|
|
|
170
190
|
# EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
|
|
171
191
|
# hour is when scheduled runs queue longest.
|
|
172
192
|
- cron: "17 3 * * *"
|
|
193
|
+
# #547: the hourly RETRY run — cut only, only when the CLI moved or a run was displaced (header,
|
|
194
|
+
# "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (release job env).
|
|
195
|
+
- cron: "47 * * * *"
|
|
173
196
|
workflow_dispatch:
|
|
174
197
|
# #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
|
|
175
198
|
# any ref other than main is dry whether or not this is set; on main it is opt-in.
|
|
@@ -263,6 +286,12 @@ jobs:
|
|
|
263
286
|
# Never on workflow_run or schedule. Every write below is off when it is.
|
|
264
287
|
# EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
|
|
265
288
|
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
|
|
289
|
+
# #547: 'true' on the hourly retry run. EDIT: the cron string here is byte-identical to the hourly
|
|
290
|
+
# `cron:` under `on.schedule`.
|
|
291
|
+
RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
|
|
292
|
+
# EDIT: how recent a move of the CLI still earns a retry. Two hourly runs plus slack, so one
|
|
293
|
+
# scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
|
|
294
|
+
RETRY_WINDOW_MINUTES: "130"
|
|
266
295
|
steps:
|
|
267
296
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
268
297
|
with:
|
|
@@ -334,13 +363,46 @@ jobs:
|
|
|
334
363
|
git config user.name "github-actions[bot]"
|
|
335
364
|
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
|
336
365
|
|
|
366
|
+
# #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
|
|
367
|
+
# THE HANDBOOK FIXES"). Ends green either way; retry=true lets the cut step below run.
|
|
368
|
+
- name: Retry a refused cut once the CLI moved (#547)
|
|
369
|
+
id: retry
|
|
370
|
+
if: env.RETRY_RUN == 'true'
|
|
371
|
+
run: |
|
|
372
|
+
set -uo pipefail
|
|
373
|
+
eval "$RETRY_TRANSIENT"
|
|
374
|
+
decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
|
|
375
|
+
HEAD="$(git rev-parse HEAD)"
|
|
376
|
+
TAGGED="$(git tag --points-at "$HEAD" --list 'v*' | head -n 1)"
|
|
377
|
+
[ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
|
|
378
|
+
# When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
|
|
379
|
+
# tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
|
|
380
|
+
CLI_DIR="${COLAB%/tools/colab}"
|
|
381
|
+
CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
|
|
382
|
+
MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
|
|
383
|
+
[ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
|
|
384
|
+
AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
|
|
385
|
+
if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
|
|
386
|
+
decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
|
|
387
|
+
fi
|
|
388
|
+
# A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
|
|
389
|
+
# An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
|
|
390
|
+
RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
|
|
391
|
+
|| decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
|
|
392
|
+
LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
|
|
393
|
+
case "$LAST" in
|
|
394
|
+
cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
|
|
395
|
+
unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
|
|
396
|
+
esac
|
|
397
|
+
decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
|
|
398
|
+
|
|
337
399
|
# #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
|
|
338
400
|
# into main, then dispatch CI there — its green run fires this workflow again to cut the
|
|
339
401
|
# candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
|
|
340
402
|
# rejected) is a warning; the job stays green.
|
|
341
403
|
- name: Promote unattended (colab promote --auto)
|
|
342
404
|
id: promote
|
|
343
|
-
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
405
|
+
if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
|
|
344
406
|
env:
|
|
345
407
|
# EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
|
|
346
408
|
CI_WORKFLOW: "CI"
|
|
@@ -384,7 +446,7 @@ jobs:
|
|
|
384
446
|
# right after this run promoted: that head has no CI yet — the dispatched run cuts it.
|
|
385
447
|
- name: Cut a candidate (colab release cut --auto)
|
|
386
448
|
id: cut
|
|
387
|
-
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
|
|
449
|
+
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
|
|
388
450
|
run: |
|
|
389
451
|
set -uo pipefail
|
|
390
452
|
eval "$RETRY_TRANSIENT"
|
|
@@ -444,7 +506,7 @@ jobs:
|
|
|
444
506
|
|
|
445
507
|
- name: Finalize the newest clean candidate (colab release finalize --auto)
|
|
446
508
|
id: finalize
|
|
447
|
-
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
509
|
+
if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
|
|
448
510
|
run: |
|
|
449
511
|
set -uo pipefail
|
|
450
512
|
eval "$RETRY_TRANSIENT"
|
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
|
|
526
|
-
*
|
|
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(
|
|
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(
|
|
675
|
-
process.stderr.write(
|
|
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\`
|
|
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
|
|
@@ -5587,23 +5594,30 @@ function cmdWorktreeNew(argv) {
|
|
|
5587
5594
|
// rejected instead of overwriting. With issues to claim, a failed push takes nothing: the worktree
|
|
5588
5595
|
// and the zero-commit branch this invocation just made are removed again, so no half-claim exists
|
|
5589
5596
|
// anywhere. With no issues there is no claim to protect, and a failed push only warns.
|
|
5597
|
+
//
|
|
5598
|
+
// #550: what is pushed is the CLAIM REF `refs/claims/<branch>`, not the branch. A branch push fires
|
|
5599
|
+
// every CI `push` trigger, and at cut the branch IS trunk's commit — so each cut re-ran a suite
|
|
5600
|
+
// trunk had already passed (~27 % of one org's runs). A claim ref triggers nothing, and every
|
|
5601
|
+
// claim reader (`remoteHeads`) lists it beside the branches. The branch itself is first pushed at
|
|
5602
|
+
// code-wrap, when it has commits worth testing. The claim ref is deleted at `worktree rm`.
|
|
5590
5603
|
const pushRemote = git.claimRemote(repoAbs);
|
|
5591
5604
|
let pushed = false;
|
|
5592
5605
|
if (pushRemote) {
|
|
5593
|
-
const
|
|
5606
|
+
const claimRef = git.claimRef(branch);
|
|
5607
|
+
const push = git.pushClaimRef(repoAbs, pushRemote, branch);
|
|
5594
5608
|
if (push.ok) {
|
|
5595
5609
|
pushed = true;
|
|
5596
|
-
print(` pushed ${
|
|
5610
|
+
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
5611
|
} else {
|
|
5598
5612
|
const why = String(push.stderr || '').split('\n').filter(Boolean).slice(-1)[0] || `exit ${push.code}`;
|
|
5599
5613
|
if (issues.length) {
|
|
5600
5614
|
git.git(['worktree', 'remove', '--force', wtPath], repoAbs);
|
|
5601
5615
|
git.git(['branch', '-D', branch], repoAbs);
|
|
5602
|
-
throw new UserError(`git push ${pushRemote} ${
|
|
5603
|
-
'were removed again. The pushed
|
|
5604
|
-
|
|
5616
|
+
throw new UserError(`git push ${pushRemote} ${claimRef} failed (${why}) — claim NOT taken: the worktree and branch ` +
|
|
5617
|
+
'were removed again. The pushed claim ref is the record other machines read (#325, #550); fix the push ' +
|
|
5618
|
+
`(access, network, or a claim ref of that name another machine just created — \`git ls-remote ${pushRemote} ${claimRef}\`) and re-run.`);
|
|
5605
5619
|
}
|
|
5606
|
-
warn(`git push ${pushRemote} ${
|
|
5620
|
+
warn(`git push ${pushRemote} ${claimRef} failed (${why}) — worktree created, no claim ref on the remote`);
|
|
5607
5621
|
}
|
|
5608
5622
|
}
|
|
5609
5623
|
|
|
@@ -5625,14 +5639,14 @@ function cmdWorktreeNew(argv) {
|
|
|
5625
5639
|
}
|
|
5626
5640
|
|
|
5627
5641
|
// 3. allocate ports + record worktree + claims (atomic)
|
|
5628
|
-
// #325: if recording fails after the push above, take the pushed
|
|
5642
|
+
// #325: if recording fails after the push above, take the pushed claim ref back off the remote —
|
|
5629
5643
|
// otherwise it would stand there as a claim record nothing on any machine owns, refusing every
|
|
5630
5644
|
// later claim on these issues. (The local worktree is left as before this change.)
|
|
5631
5645
|
let alloc;
|
|
5632
5646
|
try {
|
|
5633
5647
|
alloc = allocWorktreeRecord();
|
|
5634
5648
|
} catch (e) {
|
|
5635
|
-
if (pushed) git.
|
|
5649
|
+
if (pushed) git.deleteClaimRef(repoAbs, pushRemote, branch);
|
|
5636
5650
|
throw e;
|
|
5637
5651
|
}
|
|
5638
5652
|
function allocWorktreeRecord() { return state.mutate((st) => {
|
|
@@ -5861,6 +5875,19 @@ function cmdWorktreeRm(argv) {
|
|
|
5861
5875
|
|
|
5862
5876
|
print(`✓ Removed worktree "${name}"`);
|
|
5863
5877
|
if (removal.action === 'rm-rf') print(' (directory was a husk from an earlier interrupted removal — cleaned up directly)');
|
|
5878
|
+
// #550: the claim ref `worktree new` pushed is this worktree's claim record on the remote — release
|
|
5879
|
+
// it with the claims, or it would stand there refusing every later claim on these issue numbers from
|
|
5880
|
+
// another machine. Best effort: an absent ref is fine (never pushed, a pre-#550 worktree, or already
|
|
5881
|
+
// gone), a failed delete only warns with the command, and nothing above is undone for it.
|
|
5882
|
+
if (wt.branch) {
|
|
5883
|
+
let claimRemoteName = null;
|
|
5884
|
+
try { claimRemoteName = git.claimRemote(repoAbs); } catch { claimRemoteName = null; }
|
|
5885
|
+
if (claimRemoteName) {
|
|
5886
|
+
const d = git.deleteClaimRef(repoAbs, claimRemoteName, wt.branch);
|
|
5887
|
+
if (d.ok && !d.absent) print(` deleted claim ref ${claimRemoteName} ${git.claimRef(wt.branch)}`);
|
|
5888
|
+
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)}`);
|
|
5889
|
+
}
|
|
5890
|
+
}
|
|
5864
5891
|
// #114: this line used to report `removed.claims` — the LOCAL registry mutation, which cannot
|
|
5865
5892
|
// fail for a network reason and so always read as full success. Report what the tracker actually
|
|
5866
5893
|
// 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
|
|
301
|
-
* local cache)
|
|
302
|
-
* failed ask is NOT "no branches": it returns
|
|
303
|
-
* (fail closed) instead of reading an unreachable
|
|
304
|
-
* `{ ok: true, heads: [{ branch, sha }] }` otherwise, `sha` short
|
|
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', '
|
|
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
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|
-
|
|
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,
|