@futurelastic/colab-handbook 1.22.0-rc.5 → 1.22.0-rc.6

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.22.0-rc.5"
36
+ "version": "1.22.0-rc.6"
37
37
  }
package/tools/colab CHANGED
@@ -738,23 +738,64 @@ function takeClaimLocksFor(repoAbs, check, nums, { branch = null, session = '',
738
738
  * a failure warns with the command and undoes nothing. An adopted lock (an orchestrator's) is
739
739
  * released too — release is unconditional (CONVENTIONS.md §5), and a lock left behind would refuse
740
740
  * every other machine on that issue.
741
+ *
742
+ * #746 — a record with NO `lock` field is not skipped: its issue's lock is looked up on the remote and
743
+ * released, leased on the sha just read, when `claimIdentity.lockReleasableBy` proves it is this
744
+ * claim's; otherwise it is left and the exact delete command is printed. Such a record is written
745
+ * when the lock came from somewhere else: an orchestrator takes the lock at spawn and the session's
746
+ * claim is then recorded by a colab older than #741 (the served CLI lagging trunk — measured on #746
747
+ * itself), or `doctor --sync` re-creates the record from the tracker. Callers pass every released
748
+ * record — `{ issue, lock?, session?, branch? }` — not only the ones with a lock.
741
749
  */
742
750
  function releaseClaimLocksOf(repoAbs, claims) {
743
- const held = (claims || []).filter((c) => c && c.lock && c.lock.sha);
744
- if (!held.length) return;
751
+ const list = (claims || []).filter((c) => c && c.issue);
752
+ if (!list.length) return;
745
753
  let remote = null;
746
754
  try { remote = git.claimRemote(repoAbs); } catch { remote = null; }
747
755
  if (!remote) return;
748
- for (const c of held) {
756
+ for (const c of list) {
749
757
  const num = normIssueNum(c.issue);
750
758
  const ref = git.claimLockRef(num);
751
- const r = git.releaseClaimLock(repoAbs, remote, num, c.lock.sha);
759
+ let sha = c.lock && c.lock.sha ? String(c.lock.sha) : '';
760
+ if (!sha) {
761
+ sha = locklessClaimLockSha(repoAbs, remote, num, c);
762
+ if (!sha) continue;
763
+ }
764
+ const r = git.releaseClaimLock(repoAbs, remote, num, sha);
752
765
  if (r.ok && r.moved) print(` claim lock ${remote} ${ref} now points at ${r.now} — someone else's; left in place`);
753
- else if (r.ok && !r.absent) print(` released claim lock ${remote} ${ref}`);
766
+ else if (r.ok && !r.absent) print(` released claim lock ${remote} ${ref}${c.lock && c.lock.sha ? '' : ' (the claim record named no lock; this one names #' + num + ' and this claimer)'}`);
754
767
  else if (!r.ok) warnDeferred(`could not release claim lock ${remote} ${ref} (${String(r.stderr || '').split('\n')[0]}) — delete it by hand: git push ${remote} --delete ${ref}`);
755
768
  }
756
769
  }
757
770
 
771
+ /**
772
+ * #746 — the sha to lease the release on for a claim record carrying no `lock`: the lock on the remote
773
+ * for `num`, when it names that issue and this claimer. '' when there is none, or when it is not
774
+ * provably this claim's (then the delete command is printed, never run).
775
+ */
776
+ function locklessClaimLockSha(repoAbs, remote, num, rec) {
777
+ const ref = git.claimLockRef(num);
778
+ const at = git.remoteClaimLock(repoAbs, remote, num);
779
+ if (!at.ok) {
780
+ warnDeferred(`could not look up claim lock ${remote} ${ref} for #${num} (${String(at.stderr || '').split('\n')[0]}) — if it is still there and yours, delete it: git push ${remote} --delete ${ref}`);
781
+ return '';
782
+ }
783
+ if (!at.sha) return '';
784
+ const del = `git push ${remote} --force-with-lease=${ref}:${at.sha} --delete ${ref}`;
785
+ const read = git.readClaimLock(repoAbs, remote, num, at.sha);
786
+ if (!read.ok) {
787
+ warnDeferred(`claim lock ${remote} ${ref} @ ${at.sha.slice(0, 7)} could not be read (${String(read.stderr || '').split('\n')[0]}) — left in place; if it is this claim's, delete it: ${del}`);
788
+ return '';
789
+ }
790
+ const verdict = claimIdentity.lockReleasableBy(read.trailers, rec,
791
+ { num, hostLabel: HOST, machineTok: machine.machineToken(myMachineId()) || '' });
792
+ if (!verdict.ok) {
793
+ warnDeferred(`claim lock ${remote} ${ref} @ ${at.sha.slice(0, 7)} is not provably this claim's (${verdict.why}) — left in place; if it is stale, delete it: ${del}`);
794
+ return '';
795
+ }
796
+ return at.sha;
797
+ }
798
+
758
799
  /** The refusal/stale lines for a foreign lock (#741). */
759
800
  function lockHolderText(c) {
760
801
  const who = [c.branch ? `branch ${c.branch}` : null, c.machine ? `machine ${c.machine}` : null, c.writer && c.writer !== 'colab' ? `written by ${c.writer}` : null].filter(Boolean).join(' · ');
@@ -2962,7 +3003,8 @@ function releaseFoundClaim(num, found, opts = {}) {
2962
3003
  c.releasePending = true;
2963
3004
  c.releaseNote = `GitHub release failed (${nowISO()}) — retry with: colab release ${num}`;
2964
3005
  } else {
2965
- if (c.lock) releasedLock = { issue: c.issue, lock: c.lock };
3006
+ // #746: released with or without a recorded lock — a lock-less record's lock is looked up.
3007
+ releasedLock = { issue: c.issue, lock: c.lock || null, session: c.session || null, branch: c.branch || null };
2966
3008
  delete st.claims[found.key];
2967
3009
  if (wtName) remaining = Object.values(st.claims).filter((cl) => cl.worktree === wtName).length;
2968
3010
  // #305: a claim with NO worktree took a checkout place-claim at `cmdClaim` (`takingPlace`),
@@ -6856,7 +6898,8 @@ function cmdWorktreeRm(argv) {
6856
6898
  c.releaseNote = `GitHub release failed at worktree rm (${nowISO()}) — retry with: colab release ${normIssueNum(c.issue)}`;
6857
6899
  continue;
6858
6900
  }
6859
- if (c.lock) releasedLocks.push({ issue: c.issue, lock: c.lock });
6901
+ // #746: every released claim, not only one recording a lock — a lock-less record's lock is looked up.
6902
+ releasedLocks.push({ issue: c.issue, lock: c.lock || null, session: c.session || null, branch: c.branch || null });
6860
6903
  delete st.claims[k];
6861
6904
  deleted++;
6862
6905
  }
@@ -35,6 +35,7 @@
35
35
  */
36
36
 
37
37
  const machine = require('./machine');
38
+ const { machineLabel } = require('./branch-name');
38
39
 
39
40
  const DEFAULT_COMPONENTS = Object.freeze(['login', 'host']);
40
41
  const FINE_COMPONENTS = Object.freeze(['login', 'host', 'session']);
@@ -239,11 +240,52 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
239
240
  * False for '' / null: absence is `warnWeakIdentity`'s and `requirePlaceIdentity`'s subject
240
241
  * (#11/#242), never this predicate's — callers test blankness first.
241
242
  */
243
+ /**
244
+ * #746 — may a claim record that carries NO `lock` field release the claim lock found on the remote
245
+ * for its issue? Pure. `trailers` is `git.parseClaimLockMessage` of the lock commit, `rec` the claim
246
+ * record being released, `here` = `{ num, hostLabel, machineTok }` (this machine's `machineLabel` and
247
+ * public machine token). `{ ok: true }` or `{ ok: false, why }` — a refusal leaves the lock in place
248
+ * and the caller prints the delete command, so this errs toward "not provably ours".
249
+ *
250
+ * A record is lock-less when the lock was written by something other than the colab that wrote the
251
+ * record: an orchestrator takes the lock at spawn and the session's claim is then recorded by a colab
252
+ * that predates #741 (measured on #746 itself — the served CLI lagged trunk), or `doctor --sync`
253
+ * re-creates the record from the tracker. So the rule mirrors adoption in `remoteClaimConflicts`:
254
+ * - the lock must name this issue in its subject (`claim: #N …`);
255
+ * - a lock colab wrote (`Claimed-By: colab`) is this claim's only when its `Session:` equals the
256
+ * record's (both non-empty) AND it names this machine — two colab homes on one host share the
257
+ * hardware, so the machine alone never proves it;
258
+ * - a lock another tool wrote is this claim's when it names this machine — the same test that let
259
+ * the session adopt it — unless a `Session:`/`Branch:` it does carry contradicts the record.
260
+ */
261
+ function lockReleasableBy(trailers, rec, { num, hostLabel = '', machineTok = '' } = {}) {
262
+ const tr = trailers || {};
263
+ const r = rec || {};
264
+ const issues = Array.isArray(tr.issues) ? tr.issues : [];
265
+ if (!issues.includes(Number(num))) {
266
+ return { ok: false, why: issues.length ? `the lock commit names ${issues.map((n) => `#${n}`).join(' ')}, not #${num}` : `the lock commit names no issue` };
267
+ }
268
+ const trMachine = tr.machine ? machineLabel(tr.machine) : '';
269
+ const onThisMachine = (tr.machineId && machineTok) ? tr.machineId === machineTok : (!!trMachine && trMachine === machineLabel(hostLabel));
270
+ if (tr.colab) {
271
+ if (!r.session || !tr.session || r.session !== tr.session) {
272
+ return { ok: false, why: `colab wrote it for session ${tr.session || '(none)'}, this claim is session ${r.session || '(none)'}` };
273
+ }
274
+ if (!onThisMachine) return { ok: false, why: `colab wrote it on machine ${tr.machine || tr.machineId || '(none)'}` };
275
+ return { ok: true };
276
+ }
277
+ const writer = tr.author || 'another tool';
278
+ if (!onThisMachine) return { ok: false, why: `${writer} wrote it for machine ${tr.machine || '(none)'}, not this one` };
279
+ if (tr.session && r.session && tr.session !== r.session) return { ok: false, why: `${writer} wrote it for session ${tr.session}, this claim is session ${r.session}` };
280
+ if (tr.branch && r.branch && tr.branch !== r.branch) return { ok: false, why: `${writer} wrote it for branch ${tr.branch}, this claim is on ${r.branch}` };
281
+ return { ok: true };
282
+ }
283
+
242
284
  const { looksLikeSessionId } = require('./codec/claim'); // one copy of the rule, in the codec (#497)
243
285
 
244
286
  module.exports = {
245
287
  DEFAULT_COMPONENTS, FINE_COMPONENTS,
246
288
  claimIdentityProblem, components, identityString, sameClaimant, mergeClaimRecord,
247
289
  looksLikeSessionId, isIntentSession, sameHost, sameFactory,
248
- shouldDerivePersonSession, derivePersonSession, isPersonSession,
290
+ shouldDerivePersonSession, derivePersonSession, isPersonSession, lockReleasableBy,
249
291
  };
package/tools/lib/git.js CHANGED
@@ -458,6 +458,12 @@ function parseClaimLockMessage(text) {
458
458
  if (k && out[k] === undefined) out[k] = m[2].trim();
459
459
  }
460
460
  out.colab = out.claimedBy === CLAIM_LOCK_WRITER;
461
+ // #746: the issues the subject names (`claim: #12 #13`) — both writers use this subject. A release
462
+ // that has no recorded lock sha to lease on checks the lock names its issue before deleting it.
463
+ // A `git cat-file commit` body carries headers first; the message starts after the first blank line.
464
+ const message = /^tree [0-9a-f]+$/m.test(s.split('\n')[0]) ? s.slice(s.indexOf('\n\n') + 2) : s;
465
+ const sm = (/^claim:\s*(.*)$/.exec(message.split('\n')[0].trim()) || [])[1];
466
+ out.issues = sm ? [...sm.matchAll(/#(\d+)/g)].map((m) => Number(m[1])).filter((n) => Number.isInteger(n) && n > 0) : [];
461
467
  return out;
462
468
  }
463
469
 
@@ -527,6 +533,17 @@ function releaseClaimLock(repo, remote, num, sha) {
527
533
  return { ok: r.ok, stderr: r.stderr };
528
534
  }
529
535
 
536
+ /**
537
+ * #746 — where `refs/heads/claim/<num>` points on `remote` right now. `{ ok, sha }` (full sha, or
538
+ * `null` when there is no lock) or `{ ok: false, stderr }` when the remote could not be asked.
539
+ */
540
+ function remoteClaimLock(repo, remote, num) {
541
+ const ls = git(['ls-remote', remote, claimLockRef(num)], repo, { timeoutMs: 60_000 });
542
+ if (!ls.ok) return { ok: false, stderr: ls.stderr || (ls.timedOut ? 'ls-remote timed out' : `exit ${ls.code}`) };
543
+ const sha = (String(ls.stdout || '').split(/\s+/)[0] || '').trim();
544
+ return { ok: true, sha: sha || null };
545
+ }
546
+
530
547
  /**
531
548
  * Read who holds a lock: the commit at `fullSha`, fetched from `remote` when this clone lacks it.
532
549
  * `{ ok, trailers }` (`parseClaimLockMessage`) or `{ ok: false, stderr }` — a failed read is the
@@ -1881,7 +1898,7 @@ module.exports = {
1881
1898
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1882
1899
  claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
1883
1900
  CLAIM_LOCK_PREFIX, claimLockRef, parseClaimLocks, claimLockMessage, parseClaimLockMessage, makeClaimLockCommit,
1884
- takeClaimLocks, releaseClaimLock, readClaimLock, remoteRefCommitTime,
1901
+ takeClaimLocks, releaseClaimLock, readClaimLock, remoteClaimLock, remoteRefCommitTime,
1885
1902
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1886
1903
  dirtyTracked, dirtyUntracked, dirtyAny,
1887
1904
  ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghRunsAtShaUnfiltered, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,