@futurelastic/colab-handbook 1.13.0-rc.45 → 1.13.0-rc.47

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.45"
36
+ "version": "1.13.0-rc.47"
37
37
  }
package/tools/colab CHANGED
@@ -10377,7 +10377,7 @@ A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHE
10377
10377
  (…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
10378
10378
  name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
10379
10379
  one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
10380
- branch that moved after its hand-off needs a new one); and every issue the branch carries has a
10380
+ branch that moved after its hand-off needs a new one — except by base-sync merges, #579, below); and every issue the branch carries has a
10381
10381
  live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
10382
10382
  claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
10383
10383
  the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
@@ -10385,6 +10385,13 @@ the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url>
10385
10385
  the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
10386
10386
  --batch or --direct, and not when this machine already holds a claim on the branch.
10387
10387
 
10388
+ A remote-built branch that fell BEHIND its base (#579) is synced by the lander as usual (B0: merge
10389
+ the base in, push) — and the hand-off still verifies, because the commits between the handed-off
10390
+ sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
10391
+ and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
10392
+ conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
10393
+ trailer then reads \`Colab-Handoff: <url> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
10394
+
10388
10395
  UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
10389
10396
  --session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
10390
10397
  (--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
@@ -11911,7 +11918,7 @@ function cmdShipDryJson(opts) {
11911
11918
  const trunk = resolveTrunk(repoAbs, doc);
11912
11919
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
11913
11920
  if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
11914
- const handoff = applyShipHandoff(repoAbs, sess, opts); // #578 — same resolution as the prose path
11921
+ const handoff = applyShipHandoff(repoAbs, sess, opts, trunk); // #578 — same resolution as the prose path
11915
11922
 
11916
11923
  const checks = [];
11917
11924
  if (handoff) {
@@ -12995,7 +13002,7 @@ function autonomyGatePayload(gate) {
12995
13002
  * Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
12996
13003
  * this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
12997
13004
  */
12998
- function applyShipHandoff(repoAbs, sess, opts) {
13005
+ function applyShipHandoff(repoAbs, sess, opts, trunk) {
12999
13006
  if (!opts.handoff) return null;
13000
13007
  if (opts.adopt) throw new UserError('--handoff and --adopt contradict each other: --adopt is for a branch with NO issue, --handoff for one whose claim lives on another machine — drop --adopt');
13001
13008
  if (sess.issues.length) {
@@ -13017,6 +13024,13 @@ function applyShipHandoff(repoAbs, sess, opts) {
13017
13024
  const remote = git.remoteFor(repoAbs);
13018
13025
  if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
13019
13026
  const refs = git.branchRefs(repoAbs, sess.branch, remote);
13027
+ // #579: base-sync merges the lander (B0) stacked on the handed-off head do not void the hand-off.
13028
+ // Read against the base as it is NOW — the merges' second parents must already be on it.
13029
+ let syncChain = [];
13030
+ if (u && comment && refs && refs.remoteSha && trunk) {
13031
+ git.git(['fetch', '--quiet', remote, `+refs/heads/${trunk}:refs/remotes/${remote}/${trunk}`], repoAbs);
13032
+ syncChain = shipHandoff.syncMergeChain((a) => git.git(a, repoAbs), refs.remoteSha, `refs/remotes/${remote}/${trunk}`);
13033
+ }
13020
13034
  const claimsByIssue = {};
13021
13035
  if (u && comment) {
13022
13036
  for (const n of shipguard.branchIssueNumbers(sess.branch)) {
@@ -13024,7 +13038,7 @@ function applyShipHandoff(repoAbs, sess, opts) {
13024
13038
  claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
13025
13039
  }
13026
13040
  }
13027
- const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue });
13041
+ const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain });
13028
13042
  if (!v.ok) return v;
13029
13043
  sess.issues = v.issues;
13030
13044
  sess.handoff = v;
@@ -13035,7 +13049,10 @@ function applyShipHandoff(repoAbs, sess, opts) {
13035
13049
  }
13036
13050
 
13037
13051
  function handoffDetail(v) {
13038
- return `${v.url} hands off ${shortSha(v.sha)} = the remote head; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
13052
+ const head = v.syncMerges
13053
+ ? `${shortSha(v.handedOff)}, under ${v.syncMerges} clean base-sync merge${v.syncMerges === 1 ? '' : 's'} to the remote head ${shortSha(v.sha)} (#579)`
13054
+ : `${shortSha(v.sha)} = the remote head`;
13055
+ return `${v.url} hands off ${head}; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
13039
13056
  }
13040
13057
 
13041
13058
  /** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
@@ -13087,7 +13104,7 @@ function cmdShip(argv) {
13087
13104
  // #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
13088
13105
  // branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
13089
13106
  // remote-only branch resolve here at all.
13090
- const handoff = applyShipHandoff(repoAbs, sess, opts);
13107
+ const handoff = applyShipHandoff(repoAbs, sess, opts, trunk);
13091
13108
  if (handoff && !handoff.ok) {
13092
13109
  process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
13093
13110
  `ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
@@ -24,7 +24,14 @@
24
24
  * 4. the body names the branch, as a whole token;
25
25
  * 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
26
26
  * 6. the body names a sha that is a prefix of the remote branch's CURRENT head — a branch that
27
- * moved after its hand-off was not handed off at that head, and lands only after a new one;
27
+ * moved after its hand-off was not handed off at that head, and lands only after a new one.
28
+ * ONE movement is not "moved" (#579): base-sync merges stacked on the handed-off head. The
29
+ * stale-base gate (#395) sends every behind-trunk branch through B0's sync, and the sync moves
30
+ * the head; without this a remote-built branch that fell behind could land only after its
31
+ * executor — whose session has usually ended — posted again. A sync merge is accepted only
32
+ * when it adds nothing of its own (syncMergeChain, below): two parents, the second already on
33
+ * the base, and a tree equal to git's own clean merge of the two. Any other commit after the
34
+ * handed-off sha — a fix-up, a rebase, a hand-resolved conflict — is still `head-moved`;
28
35
  * 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
29
36
  * the hand-off's author before the hand-off — the claim really does live elsewhere, and the
30
37
  * party handing off is the party holding it.
@@ -63,9 +70,13 @@ function namedShas(body) {
63
70
  * refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
64
71
  * claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
65
72
  * or null for an issue whose comments could not be read
66
- * Returns { ok: true, issues, sha, executor, url } or { ok: false, reason, detail }.
73
+ * syncChain — (#579) the first-parent ancestors of the remote head reached through pure
74
+ * base-sync merges only, nearest first (syncMergeChain's output); [] or absent = none
75
+ * Returns { ok: true, issues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
76
+ * `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
77
+ * unless the head was synced, in which case `syncMerges` counts the merges between them.
67
78
  */
68
- function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
79
+ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }) {
69
80
  const no = (reason, detail) => ({ ok: false, reason, detail });
70
81
  const u = parseHandoffUrl(url);
71
82
  if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
@@ -89,9 +100,13 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
89
100
  }
90
101
  const head = String(refs.remoteSha).toLowerCase();
91
102
  const shas = namedShas(comment.body);
92
- if (!shas.some((s) => head.startsWith(s))) {
103
+ // #579: the head itself first, then each sha a pure base-sync merge sits on, nearest first.
104
+ const lineage = [head, ...(Array.isArray(syncChain) ? syncChain : []).map((x) => String(x).toLowerCase())];
105
+ const at = lineage.findIndex((l) => shas.some((s) => l.startsWith(s)));
106
+ if (at < 0) {
107
+ const synced = lineage.length > 1 ? ` (nor ${lineage.length - 1 === 1 ? 'the sha' : 'any of the ' + (lineage.length - 1) + ' shas'} its base-sync merges sit on)` : '';
93
108
  return no('head-moved', shas.length
94
- ? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)} — the branch moved after it was handed off; ask its executor for a new hand-off`
109
+ ? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)}${synced} — the branch moved after it was handed off by more than a clean merge of its base; ask its executor for a new hand-off`
95
110
  : `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
96
111
  }
97
112
  let executor = null;
@@ -105,12 +120,55 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
105
120
  }
106
121
  if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
107
122
  }
108
- return { ok: true, issues, sha: refs.remoteSha, executor, url: String(url).trim() };
123
+ return { ok: true, issues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
109
124
  }
110
125
 
111
- /** The squash trailer recording the door the issue set came through. */
126
+ /**
127
+ * The squash trailer recording the door the issue set came through. It names the HANDED-OFF sha —
128
+ * the one the executor vouched for — and, after a sync (#579), the head that actually landed.
129
+ */
112
130
  function handoffTrailer(v) {
113
- return v && v.ok ? `Colab-Handoff: ${v.url} @ ${String(v.sha).slice(0, 12)}` : '';
131
+ if (!v || !v.ok) return '';
132
+ const handed = String(v.handedOff || v.sha).slice(0, 12);
133
+ const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
134
+ return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
135
+ }
136
+
137
+ /**
138
+ * #579 — walk the remote head's first-parent line while each commit is a PURE base-sync merge, and
139
+ * return the shas it sits on, nearest first. A commit qualifies only when all three hold:
140
+ * - exactly two parents (a squash, a rebase, a cherry-pick or a fix-up has one);
141
+ * - its second parent is already on the base (`merge-base --is-ancestor p2 <baseRef>`) — it
142
+ * brought in landed base content, not a side branch;
143
+ * - its tree equals `git merge-tree --write-tree p1 p2`'s — git's own conflict-free merge of the
144
+ * two. A conflict (exit 1) or a hand-edited result (a different tree) is NOT pure: someone wrote
145
+ * content into it, and only the executor can vouch for content.
146
+ * The walk stops at the first commit that fails, so a sync merge stacked on a fix-up yields only
147
+ * the fix-up's sha — which a hand-off naming the commit before the fix-up does not match.
148
+ *
149
+ * `run(args)` is git in the repo, returning { ok, code, stdout } (tools/lib/git.js `git`). A git
150
+ * too old for `merge-tree --write-tree` (< 2.38) proves nothing, so the chain is just empty there:
151
+ * the hand-off then needs the exact head, exactly as before #579.
152
+ */
153
+ function syncMergeChain(run, head, baseRef, maxDepth = 50) {
154
+ const chain = [];
155
+ let cur = String(head || '');
156
+ for (let i = 0; cur && i < maxDepth; i++) {
157
+ const p = run(['rev-list', '--parents', '-n', '1', cur]);
158
+ if (!p.ok) break;
159
+ const parts = String(p.stdout).trim().split(/\s+/);
160
+ if (parts.length !== 3) break;
161
+ const [, p1, p2] = parts;
162
+ if (run(['merge-base', '--is-ancestor', p2, baseRef]).code !== 0) break;
163
+ const mt = run(['merge-tree', '--write-tree', p1, p2]);
164
+ if (mt.code !== 0) break;
165
+ const merged = String(mt.stdout).split('\n')[0].trim();
166
+ const tree = run(['rev-parse', `${cur}^{tree}`]);
167
+ if (!tree.ok || !/^[0-9a-f]{40,64}$/.test(merged) || merged !== String(tree.stdout).trim()) break;
168
+ chain.push(p1.toLowerCase());
169
+ cur = p1;
170
+ }
171
+ return chain;
114
172
  }
115
173
 
116
- module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer };
174
+ module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain };