@futurelastic/colab-handbook 1.13.0-rc.21 → 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 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.22"
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
@@ -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 push = git.git(['push', '-u', pushRemote, `--force-with-lease=refs/heads/${branch}:`, branch], repoAbs, { timeoutMs: 120_000 });
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 ${branch} → ${pushRemote} (the claim record other machines read)`);
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} ${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.');
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} ${branch} failed (${why}) — worktree created, branch not on the remote yet`);
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 branch back off the remote —
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.git(['push', pushRemote, '--delete', branch], repoAbs, { timeoutMs: 120_000 });
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`, 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,