@futurelastic/colab-handbook 1.22.0-rc.3 → 1.22.0-rc.4

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.3"
36
+ "version": "1.22.0-rc.4"
37
37
  }
package/tools/colab CHANGED
@@ -11403,8 +11403,8 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
11403
11403
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
11404
11404
  }
11405
11405
 
11406
- const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
11407
- colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
11406
+ const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <ref>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
11407
+ colab ship --batch <b1,b2[@<handoff-ref>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
11408
11408
 
11409
11409
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
11410
11410
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -11516,19 +11516,23 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
11516
11516
  still a legitimate zero. --adopt never bypasses a branch that names issues.
11517
11517
 
11518
11518
  A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
11519
- \`colab ship --branch <br> --handoff <url>\`, where <url> is the executor's hand-off comment
11520
- (…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
11519
+ \`colab ship --branch <br> --handoff <ref>\`, where <ref> names the executor's hand-off comment
11520
+ forge-neutrally — \`<forge-host>/<owner>/<repo>#<N>@comment:<id>\` (#740) — or by its URL
11521
+ (…/issues/<N>#issuecomment-<id>, kept as an alias). Either is resolved through the repo's tracker
11522
+ adapter: the GitHub tracker, or on a Forgejo remote the forge engine (reads only — colab writes no
11523
+ claim comment there, #678, so the claim below must come from the adopter's tracker layer). With zero claims here, ship takes the issue set from the branch
11521
11524
  name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
11522
11525
  one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
11523
11526
  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
11524
11527
  live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
11525
11528
  claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
11526
- the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
11529
+ the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <ref> @ <sha>\` (always the
11530
+ neutral form, whichever one was given), and each
11527
11531
  🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
11528
11532
  the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt
11529
11533
  or --direct, and not when this machine already holds a claim on the branch.
11530
11534
 
11531
- IN A BATCH (#591) the hand-off rides its member: \`--batch b1,b2@<url>\` (split on the first @).
11535
+ IN A BATCH (#591) the hand-off rides its member: \`--batch b1,b2@<ref>\` (split on the first @).
11532
11536
  That member is verified by this SAME door — same checks, same refusal text, which drops it from
11533
11537
  the batch while the rest build — then joins the combined run with no sync of its own; its squash
11534
11538
  carries the Colab-Handoff trailer, and the land reads the door back from that commit. Repeat the
@@ -11540,7 +11544,7 @@ the base in, push) — and the hand-off still verifies, because the commits betw
11540
11544
  sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
11541
11545
  and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
11542
11546
  conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
11543
- trailer then reads \`Colab-Handoff: <url> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
11547
+ trailer then reads \`Colab-Handoff: <ref> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
11544
11548
 
11545
11549
  UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
11546
11550
  --session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
@@ -13638,7 +13642,7 @@ function cmdShipDryJson(opts) {
13638
13642
  // #591: the verified hand-off (or its refusal), so `ship --batch` puts this member's
13639
13643
  // Colab-Handoff trailer on its squash and words a refusal exactly as the single door does.
13640
13644
  ...(handoff ? { handoff: handoff.ok
13641
- ? { ok: true, url: handoff.url, sha: handoff.sha, handedOff: handoff.handedOff, syncMerges: handoff.syncMerges || 0 }
13645
+ ? { ok: true, url: handoff.url, ref: handoff.ref, sha: handoff.sha, handedOff: handoff.handedOff, syncMerges: handoff.syncMerges || 0 }
13642
13646
  : { ok: false, reason: handoff.reason, detail: handoff.detail } } : {}),
13643
13647
  };
13644
13648
  // #373: `ship --batch` reads each member through this SAME function — handed the body, not stdout.
@@ -14735,7 +14739,7 @@ function autonomyGatePayload(gate) {
14735
14739
 
14736
14740
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
14737
14741
  /**
14738
- * #578 — `--handoff <comment-url>`: verify the executor's recorded hand-off and, when it holds, take
14742
+ * #578 — `--handoff <ref>` (#740: neutral reference or comment URL): verify the executor's recorded hand-off and, when it holds, take
14739
14743
  * the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
14740
14744
  * without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
14741
14745
  *
@@ -14749,17 +14753,12 @@ function applyShipHandoff(repoAbs, sess, opts, trunk) {
14749
14753
  throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
14750
14754
  `for ${sess.branch} — ship it without --handoff`);
14751
14755
  }
14752
- const u = shipHandoff.parseHandoffUrl(opts.handoff);
14753
- let comment = null;
14754
- if (u) {
14755
- const r = git.ghApi(repoAbs, [`repos/{owner}/{repo}/issues/comments/${u.commentId}`]);
14756
- if (r.ok) {
14757
- try {
14758
- const j = JSON.parse(r.stdout);
14759
- comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
14760
- } catch (_) { comment = null; }
14761
- }
14762
- }
14756
+ // #740: a neutral reference (<forge-host>/<owner>/<repo>#<N>@comment:<id>) or the comment's URL, both
14757
+ // resolved through the repo's tracker adapter — the Forgejo forge engine on a forge remote (#678), the
14758
+ // GitHub tracker otherwise — so no read below reaches for one forge's API by hand.
14759
+ const u = shipHandoff.parseHandoffRef(opts.handoff);
14760
+ const reader = forgeCi(repoAbs) || tracker.forRepo(repoAbs);
14761
+ const comment = u ? reader.commentView(u.commentId) : null;
14763
14762
  // The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
14764
14763
  const remote = git.remoteFor(repoAbs);
14765
14764
  if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
@@ -14775,13 +14774,18 @@ function applyShipHandoff(repoAbs, sess, opts, trunk) {
14775
14774
  const issueStates = {}; // #647: an issue closed before the hand-off needs no claim — read state too
14776
14775
  if (u && comment) {
14777
14776
  for (const n of shipguard.branchIssueNumbers(sess.branch)) {
14778
- const info = git.ghIssueView(repoAbs, n, ['comments', 'state', 'closedAt']);
14777
+ const info = reader.issueView(n, ['comments', 'state', 'closedAt']);
14779
14778
  claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
14780
14779
  if (info) issueStates[n] = { state: info.state || '', closedAt: info.closedAt || '' };
14781
14780
  }
14782
14781
  }
14783
14782
  const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain,
14784
14783
  issueStates, refNumbers: refsFlagNumbers(opts.refs) });
14784
+ if (!v.ok && v.reason === 'no-executor-claim' && reader.kind === 'forgejo') {
14785
+ // #740: reads only on a forge (#678) — colab posts no 🔒 claim comment there, so the claim this door
14786
+ // checks exists only where the adopter's own tracker layer writes one in colab's claim format.
14787
+ return { ...v, detail: `${v.detail}. On a ${reader.kind} remote colab writes no claim comment (#678): a hand-off verifies there only where the adopter's tracker layer posts the executor's 🔒 claim in colab's format` };
14788
+ }
14785
14789
  if (!v.ok) return v;
14786
14790
  sess.issues = v.issues;
14787
14791
  sess.handoff = v;
@@ -14870,7 +14874,7 @@ function cmdShip(argv) {
14870
14874
  if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
14871
14875
  // #578: a hand-off names ONE branch; trunk-direct has no branch for it to name. #591: in a batch the
14872
14876
  // hand-off rides its member (`--batch b1,b2@<url>`), so a bare --handoff beside --batch names no one.
14873
- if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-url> (#591, see `colab ship --help`)');
14877
+ if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-ref> (#591, see `colab ship --help`)');
14874
14878
  if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
14875
14879
  if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
14876
14880
  if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
@@ -16331,7 +16335,7 @@ function cmdShipBatch(opts) {
16331
16335
  const batchRead = { verifying: verifyRuns.parsePolicy(doc) };
16332
16336
  const trunk = resolveTrunk(repoAbs, doc);
16333
16337
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
16334
- // #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-url>`.
16338
+ // #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-ref>` (#740).
16335
16339
  const entries = shipHandoff.parseBatchEntries(opts.batch === true ? '' : opts.batch);
16336
16340
  if (entries.errors.length) throw new UserError(`--batch: ${entries.errors.join('; ')}`);
16337
16341
  const members = entries.members;
@@ -10,6 +10,8 @@
10
10
  * runsAtRef — the rows at a batch head (#742): the same status read, ignoring the ref;
11
11
  * issueListAll — a READ of every issue (switch markers, the release hold, an existing tracking
12
12
  * record), in the GitHub adapter's shape; nothing here writes an issue;
13
+ * issueView / commentView — (#740) READS of one issue (its comments and state: the executor's
14
+ * claim a hand-off land checks) and of one comment by id (the hand-off itself);
13
15
  * releaseView / releaseCreate — the release object for a tag (`/releases`).
14
16
  * Plus three reads that are NOT contract (forge-shaped, like the GitHub adapter's raw run lists):
15
17
  * `ciRunsAt` (the status rows at a commit), `ciRunsSince` (rows for every commit on a branch since a
@@ -143,6 +145,16 @@ function issueShape(i) {
143
145
  };
144
146
  }
145
147
 
148
+ /** One comment from Forgejo's comment API → the GitHub adapter's comment shape (`gh issue view --json comments`). Pure. */
149
+ function commentShape(c) {
150
+ return {
151
+ author: { login: (c && c.user && c.user.login) || '' },
152
+ body: c && c.body != null ? String(c.body) : '',
153
+ createdAt: (c && c.created_at) || null,
154
+ url: (c && c.html_url) || null,
155
+ };
156
+ }
157
+
146
158
  function pick(o, fields) {
147
159
  if (!Array.isArray(fields) || !fields.length) return o;
148
160
  const out = {};
@@ -257,6 +269,46 @@ function create(repoAbs, eng) {
257
269
  return result(true, { data: out.slice(0, limit).map((i) => pick(i, fields)) });
258
270
  },
259
271
 
272
+ /**
273
+ * One issue (tracker contract, #740): the GitHub adapter's shape, narrowed to `fields`; null when it
274
+ * could not be read (absent, any failed read). `comments` costs a second, paged
275
+ * read, so it is made only when asked for — and a partial comment list is null, never a short list.
276
+ */
277
+ issueView: (num, fields = null) => {
278
+ const r = httpGet(`${base}/issues/${Number(num)}`, eng.tokenEnv);
279
+ if (r.status !== 200) return null;
280
+ let i;
281
+ try { i = JSON.parse(r.body); } catch (_) { return null; }
282
+ if (!i || typeof i !== 'object' || Array.isArray(i)) return null;
283
+ const out = issueShape(i);
284
+ if (Array.isArray(fields) && fields.includes('comments')) {
285
+ const comments = [];
286
+ for (let page = 1; ; page++) {
287
+ if (page > MAX_PAGES) return null; // more comments than we read: never a partial claim read
288
+ const c = httpGet(`${base}/issues/${Number(num)}/comments?page=${page}&limit=${PAGE_LIMIT}`, eng.tokenEnv);
289
+ if (c.status !== 200) return null;
290
+ let list;
291
+ try { list = JSON.parse(c.body); } catch (_) { return null; }
292
+ if (!Array.isArray(list)) return null;
293
+ for (const x of list) comments.push(commentShape(x));
294
+ if (list.length < PAGE_LIMIT) break;
295
+ }
296
+ out.comments = comments;
297
+ }
298
+ return pick(out, fields);
299
+ },
300
+
301
+ /** One issue comment by id (tracker contract, #740): `{ body, login, createdAt, htmlUrl }`, null when unread. */
302
+ commentView: (id) => {
303
+ if (!/^\d+$/.test(String(id || ''))) return null;
304
+ const r = httpGet(`${base}/issues/comments/${String(id)}`, eng.tokenEnv);
305
+ if (r.status !== 200) return null;
306
+ let c;
307
+ try { c = JSON.parse(r.body); } catch (_) { return null; }
308
+ if (!c || typeof c !== 'object' || Array.isArray(c)) return null;
309
+ return { body: c.body == null ? '' : String(c.body), login: (c.user && c.user.login) || '', createdAt: c.created_at || '', htmlUrl: c.html_url || '' };
310
+ },
311
+
260
312
  /** #681, not contract: the issues blocking issue `num` — `[{ number, state, closedAt }]`, null when unread. */
261
313
  blockedBy: (num) => {
262
314
  const r = httpGet(`${base}/issues/${Number(num)}/dependencies?limit=${PAGE_LIMIT}`, eng.tokenEnv);
@@ -303,4 +355,4 @@ function notGreen(rows) {
303
355
  .map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
304
356
  }
305
357
 
306
- module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, issueShape, PAGE_LIMIT };
358
+ module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, issueShape, commentShape, PAGE_LIMIT };
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
  /**
3
- * #578 — `colab ship --branch <br> --handoff <comment-url>`: land a branch whose claim lives on
3
+ * #578 — `colab ship --branch <br> --handoff <ref>`: land a branch whose claim lives on
4
4
  * ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
5
5
  *
6
6
  * The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
@@ -15,10 +15,17 @@
15
15
  * nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
16
16
  * (its own `colab worktree rm`, which releases the claim as usual).
17
17
  *
18
+ * The reference (#740). A hand-off is named forge-neutrally — `<forge-host>/<owner>/<repo>#<N>@comment:<id>`
19
+ * — and resolved through the repo's tracker adapter (the GitHub tracker, or the Forgejo forge engine:
20
+ * `commentView`), so nothing here parses one forge's web URL to decide what repo a comment is on.
21
+ * The comment URL a browser shows (`https://<host>/<owner>/<repo>/issues/<N>#issuecomment-<id>`) stays
22
+ * accepted as an alias, and either way the squash trailer records the neutral form.
23
+ *
18
24
  * What a hand-off must prove, in order — the first failure is the verdict:
19
- * 1. the URL is an issue-comment URL (`…/issues/<N>#issuecomment-<id>`);
20
- * 2. the comment was read from THIS repo (fetched through `{owner}/{repo}`, so an off-repo id is a
21
- * 404) and its own html_url names the same issue the URL does;
25
+ * 1. the reference is a neutral hand-off reference or an issue-comment URL;
26
+ * 2. the comment was read from THIS repo (fetched through the repo-bound adapter, so an off-repo id
27
+ * is unreadable) and its own web address names the same host, repo, issue and comment id the
28
+ * reference does;
22
29
  * 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
23
30
  * issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
24
31
  * 4. the body names the branch, as a whole token;
@@ -48,13 +55,38 @@
48
55
 
49
56
  const { branchIssueNumbers } = require('./branch-name');
50
57
 
51
- /** `https://github.com/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE). */
58
+ /** `https://<host>/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE, Forgejo). The alias form (#740). */
52
59
  function parseHandoffUrl(url) {
53
60
  const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
54
61
  if (!m) return null;
55
62
  return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
56
63
  }
57
64
 
65
+ /**
66
+ * #740 — `<forge-host>/<owner>/<repo>#<N>@comment:<id>` (the neutral form) or an issue-comment URL
67
+ * (the alias) → `{ host, owner, repo, issue, commentId, form: 'ref' | 'url' }`, or null. Pure. The
68
+ * host is lower-cased (a host name is case-insensitive); owner and repo keep their spelling and are
69
+ * compared case-insensitively by the verdict, as the forges themselves resolve them. No part holds
70
+ * a space, a `/`, a `#` or an `@`, so the batch grammar's first-`@` split (#591) and the trailer's
71
+ * `\S+` read both stay unambiguous.
72
+ */
73
+ function parseHandoffRef(s) {
74
+ const str = String(s || '').trim();
75
+ const m = str.match(/^([^/\s#@]+)\/([^/\s#@]+)\/([^/\s#@]+)#(\d+)@comment:(\d+)$/);
76
+ if (m && !/^[a-z][a-z0-9+.-]*:$/i.test(m[1])) {
77
+ return { host: m[1].toLowerCase(), owner: m[2], repo: m[3], issue: Number(m[4]), commentId: m[5], form: 'ref' };
78
+ }
79
+ const u = parseHandoffUrl(str);
80
+ if (!u) return null;
81
+ const host = str.match(/^https?:\/\/([^/\s]+)/)[1].toLowerCase();
82
+ return { host, ...u, form: 'url' };
83
+ }
84
+
85
+ /** #740 — the neutral reference for `{ host, owner, repo, issue, commentId }`. Pure. */
86
+ function formatHandoffRef(p) {
87
+ return `${String(p.host).toLowerCase()}/${p.owner}/${p.repo}#${p.issue}@comment:${p.commentId}`;
88
+ }
89
+
58
90
  function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
59
91
 
60
92
  /** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
@@ -71,8 +103,9 @@ function namedShas(body) {
71
103
 
72
104
  /**
73
105
  * The verdict. Inputs:
74
- * url — the --handoff value
75
- * comment — { body, login, createdAt, htmlUrl } as read from THIS repo, or null (unreadable)
106
+ * url — the --handoff value: a neutral reference, or the comment's URL (#740)
107
+ * comment — { body, login, createdAt, htmlUrl } as read from THIS repo through the tracker
108
+ * adapter's `commentView`, or null (unreadable)
76
109
  * branch — the branch being shipped
77
110
  * refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
78
111
  * claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
@@ -82,20 +115,23 @@ function namedShas(body) {
82
115
  * issueStates — (#647) { [n]: { state, closedAt } } per issue as read now; a missing entry is
83
116
  * unknown and earns no exemption
84
117
  * refNumbers — (#647) the --refs numbers; used only to say why they do not waive a claim
85
- * Returns { ok: true, issues, refIssues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
118
+ * Returns { ok: true, issues, refIssues, sha, handedOff, syncMerges, executor, url, ref, htmlUrl } or { ok: false, reason, detail }.
119
+ * `url` is the --handoff value as given; `ref` (#740) is the neutral reference, built from the comment's
120
+ * own web address as read back — so a URL-form input records the same `ref` a neutral one does.
86
121
  * `issues` is the whole trailing run; `refIssues` is its closed-before-the-hand-off subset (#647).
87
122
  * `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
88
123
  * unless the head was synced, in which case `syncMerges` counts the merges between them.
89
124
  */
90
125
  function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain, issueStates, refNumbers }) {
91
126
  const no = (reason, detail) => ({ ok: false, reason, detail });
92
- const u = parseHandoffUrl(url);
93
- if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
127
+ const u = parseHandoffRef(url);
128
+ if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not a hand-off reference — write <forge-host>/<owner>/<repo>#<N>@comment:<id> (or the comment's URL, …/issues/<N>#issuecomment-<id>)`);
94
129
  if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
95
- const got = parseHandoffUrl(comment.htmlUrl);
96
- if (!got || got.commentId !== u.commentId || got.issue !== u.issue ||
130
+ // The comment's own web address, as the adapter read it back, is the authority on where it lives.
131
+ const got = parseHandoffRef(comment.htmlUrl);
132
+ if (!got || got.commentId !== u.commentId || got.issue !== u.issue || got.host !== u.host ||
97
133
  got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
98
- return no('mismatch', `the URL says ${u.owner}/${u.repo}#${u.issue}, but comment ${u.commentId} is ${comment.htmlUrl || 'somewhere else'}`);
134
+ return no('mismatch', `the reference says ${formatHandoffRef(u)}, but comment ${u.commentId} is ${got ? formatHandoffRef(got) : (comment.htmlUrl || 'somewhere else')}`);
99
135
  }
100
136
  const issues = branchIssueNumbers(branch);
101
137
  if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
@@ -141,7 +177,8 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain,
141
177
  }
142
178
  if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
143
179
  }
144
- return { ok: true, issues, refIssues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
180
+ return { ok: true, issues, refIssues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim(),
181
+ ref: formatHandoffRef(got), htmlUrl: comment.htmlUrl };
145
182
  }
146
183
 
147
184
  /** #647: was this issue CLOSED strictly before `at` (the hand-off's createdAt)? Unknown ⇒ false. */
@@ -153,14 +190,15 @@ function closedBefore(st, at) {
153
190
  }
154
191
 
155
192
  /**
156
- * The squash trailer recording the door the issue set came through. It names the HANDED-OFF sha —
193
+ * The squash trailer recording the door the issue set came through: the NEUTRAL reference (#740) —
194
+ * never one forge's web URL — and the HANDED-OFF sha —
157
195
  * the one the executor vouched for — and, after a sync (#579), the head that actually landed.
158
196
  */
159
197
  function handoffTrailer(v) {
160
198
  if (!v || !v.ok) return '';
161
199
  const handed = String(v.handedOff || v.sha).slice(0, 12);
162
200
  const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
163
- return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
201
+ return `Colab-Handoff: ${v.ref || v.url} @ ${handed}${synced}`;
164
202
  }
165
203
 
166
204
  /**
@@ -230,7 +268,8 @@ function parseBatchEntries(list) {
230
268
 
231
269
  /**
232
270
  * #591 — read a `Colab-Handoff:` trailer back off a squash commit body (handoffTrailer's inverse):
233
- * `{ url, handedOff }` or null. A batch lands in a second call, so the member's door is read from
271
+ * `{ url, handedOff }` or null. `url` is whichever form the trailer holds: the neutral reference
272
+ * (#740), or the comment URL a squash written before it recorded. A batch lands in a second call, so the member's door is read from
234
273
  * the commit the combined run graded, never re-supplied on the command line.
235
274
  */
236
275
  function parseHandoffTrailer(body) {
@@ -238,4 +277,4 @@ function parseHandoffTrailer(body) {
238
277
  return m ? { url: m[1], handedOff: m[2] } : null;
239
278
  }
240
279
 
241
- module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, closedBefore, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
280
+ module.exports = { parseHandoffUrl, parseHandoffRef, formatHandoffRef, namesBranch, namedShas, handoffVerdict, closedBefore, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
@@ -42,6 +42,13 @@ function create(repoAbs, given = {}) {
42
42
  const runs = clone(given.runs || []);
43
43
  const releases = new Map((given.releases || []).map((r) => [r.tag, clone(r)]));
44
44
  const base = `https://tracker.invalid/${String(repoAbs).replace(/^\/+/, '')}`;
45
+ // #740: comment ids are ONE sequence across the repo, as on a real forge — commentView reads by id alone.
46
+ let lastCommentId = 0;
47
+ const commentOf = (num, c) => {
48
+ const id = c.id === undefined ? ++lastCommentId : Number(c.id);
49
+ lastCommentId = Math.max(lastCommentId, id);
50
+ return { id, issue: num, author: c.author, body: c.body, createdAt: c.createdAt || null };
51
+ };
45
52
 
46
53
  for (const i of given.issues || []) {
47
54
  issues.set(i.number, {
@@ -49,7 +56,7 @@ function create(repoAbs, given = {}) {
49
56
  stateReason: i.stateReason || (i.state === 'CLOSED' ? 'COMPLETED' : ''),
50
57
  createdAt: i.createdAt || null, closedAt: i.closedAt || null,
51
58
  labels: clone(i.labels || []), assignees: clone(i.assignees || []),
52
- comments: (i.comments || []).map((c) => ({ author: c.author, body: c.body })),
59
+ comments: (i.comments || []).map((c) => commentOf(i.number, c)),
53
60
  events: clone(i.events || []),
54
61
  });
55
62
  }
@@ -65,7 +72,7 @@ function create(repoAbs, given = {}) {
65
72
  createdAt: i.createdAt, closedAt: i.closedAt, url: `${base}/issues/${i.number}`,
66
73
  labels: i.labels.map((name) => ({ name })),
67
74
  assignees: i.assignees.map((l) => ({ login: l })),
68
- comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body })),
75
+ comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body, createdAt: c.createdAt, url: `${base}/issues/${i.number}#issuecomment-${c.id}` })),
69
76
  };
70
77
  }
71
78
  function prShape(p) {
@@ -94,6 +101,14 @@ function create(repoAbs, given = {}) {
94
101
  const i = issues.get(Number(num));
95
102
  return offline || !i ? null : pick(issueShape(i), fields);
96
103
  },
104
+ commentView: (id) => {
105
+ if (offline) return null;
106
+ for (const i of issues.values()) {
107
+ const c = i.comments.find((x) => String(x.id) === String(id));
108
+ if (c) return { body: c.body, login: c.author, createdAt: c.createdAt || '', htmlUrl: `${base}/issues/${i.number}#issuecomment-${c.id}` };
109
+ }
110
+ return null;
111
+ },
97
112
  issueListAll: ({ limit, fields } = {}) => withList([...issues.values()]
98
113
  .sort((a, b) => b.number - a.number).slice(0, limit).map((i) => pick(issueShape(i), fields))),
99
114
  issueCreate: ({ title, body }) => {
@@ -108,8 +123,9 @@ function create(repoAbs, given = {}) {
108
123
  const i = issues.get(Number(num));
109
124
  if (offline) return result(false);
110
125
  if (!i) return fail(`issue #${num} not found`);
111
- i.comments.push({ author: login, body });
112
- return result(true, { stdout: `${base}/issues/${num}#issuecomment-${i.comments.length}` });
126
+ const c = commentOf(i.number, { author: login, body, createdAt: new Date().toISOString() });
127
+ i.comments.push(c);
128
+ return result(true, { stdout: `${base}/issues/${num}#issuecomment-${c.id}` });
113
129
  },
114
130
  issueClose: (num, { reason } = {}) => {
115
131
  const i = issues.get(Number(num));
@@ -123,6 +123,14 @@ function create(repoAbs) {
123
123
 
124
124
  // --- issues ------------------------------------------------------------------------------
125
125
  issueView: (num, fields) => git().ghIssueView(repoAbs, num, fields),
126
+ // #740: one comment by id — the read `colab ship --handoff` made with a raw `gh api`, same argv.
127
+ commentView: (id) => {
128
+ if (!/^\d+$/.test(String(id || ''))) return null;
129
+ const r = withData(exec(['api', `repos/{owner}/{repo}/issues/comments/${id}`], at));
130
+ const j = r.data;
131
+ if (!j || typeof j !== 'object' || Array.isArray(j)) return null;
132
+ return { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
133
+ },
126
134
  issueListAll: ({ limit, fields, maxBuffer } = {}) => withData(exec(
127
135
  ['issue', 'list', '--state', 'all', '--limit', String(limit), '--json', fields.join(',')],
128
136
  { ...at, ...(maxBuffer ? { maxBuffer } : {}) })),
@@ -15,7 +15,7 @@
15
15
  "login": "the account the tracker is authenticated as (what currentLogin returns, and the author of anything this tracker writes).",
16
16
  "offline": "true = the tracker cannot be reached: reads return their `could not read` value (null, or `data: null`), writes return ok:false. Never a throw.",
17
17
  "labels": "the label names defined on the repo, in the order labelList returns them.",
18
- "issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{author, body}], events: [{event: \"labeled\", label, actor}]}] — `events` is the label timeline claimHolder reads; the claimer is the actor of the LATEST labeled in-progress event.",
18
+ "issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{id, author, body, createdAt}] (`id` is the comment's repo-wide id, the one commentView reads by — #740), events: [{event: \"labeled\", label, actor}]}] — `events` is the label timeline claimHolder reads; the claimer is the actor of the LATEST labeled in-progress event.",
19
19
  "prs": "[{number, head, base, title, body, state: OPEN|CLOSED|MERGED, author}] — issues and pull requests share ONE number sequence, as on GitHub.",
20
20
  "runs": "[{headBranch, headSha, status, conclusion, event, workflowName, createdAt, databaseId}] — CI runs; runList returns them newest first by createdAt; ciVerdict (#678) summarizes the ones at one sha; runsAtRef (#742) returns the ones on one ref at one sha as rows, with `attempt` and `updatedAt` when seeded.",
21
21
  "releases": "[{tag, prerelease}]"
@@ -43,6 +43,22 @@
43
43
  { "call": "issueView", "args": [99, ["number"]], "expect": null }
44
44
  ]
45
45
  },
46
+ {
47
+ "id": "comment-view",
48
+ "description": "commentView (#740) reads one comment of this repo by its id alone — body, author login, createdAt and the forge's own web address for it, which names the issue it sits on; an id the repo does not have reads as null. issueView with `comments` returns each comment's author as an object and its createdAt — what the executor's-claim read of a hand-off land orders by.",
49
+ "given": {
50
+ "login": "alice",
51
+ "issues": [{ "number": 90, "title": "feat: export", "state": "OPEN",
52
+ "comments": [{ "id": 555, "author": "exec", "body": "wrapped on feat/export-90 (head abcdef01).", "createdAt": "2026-10-08T12:00:00Z" }] }]
53
+ },
54
+ "steps": [
55
+ { "call": "commentView", "args": ["555"],
56
+ "expect": { "body": "wrapped on feat/export-90 (head abcdef01).", "login": "exec", "createdAt": "2026-10-08T12:00:00Z", "htmlUrl": { "$re": "/issues/90#issuecomment-555$" } } },
57
+ { "call": "commentView", "args": ["999"], "expect": null },
58
+ { "call": "issueView", "args": [90, ["state", "closedAt", "comments"]],
59
+ "expect": { "state": "OPEN", "comments": [{ "author": { "login": "exec" }, "body": "wrapped on feat/export-90 (head abcdef01).", "createdAt": "2026-10-08T12:00:00Z" }] } }
60
+ ]
61
+ },
46
62
  {
47
63
  "id": "issue-create",
48
64
  "description": "issueCreate takes the next number in the sequence issues and pull requests share, returns it with the issue's URL, and the new issue is open with nothing on it.",
@@ -15,12 +15,18 @@
15
15
  * "could not read" and never "none"; the read helpers keep their existing null-on-failure
16
16
  * contract.
17
17
  *
18
+ * Comment read (#740): `commentView(id)` reads ONE issue comment of this repo by its numeric id —
19
+ * `{ body, login, createdAt, htmlUrl }`, or null when it could not be read (absent, another repo's,
20
+ * offline). `htmlUrl` is the forge's own web address for it, the one fact a caller may check the
21
+ * comment's issue and repo against (tools/lib/ship-handoff.js, the hand-off reference).
22
+ *
18
23
  * CI verdict (#678): `ciVerdict(sha, { branch })` answers "is this sha green" as ONE summary —
19
24
  * `{ status, conclusion, sha, createdAt, databaseId, runCount, … }` (tools/lib/git.js
20
25
  * `summarizeRunsForCommit`'s shape, the one ship's CI rows and the docs-only row already read), or
21
26
  * null when the read failed. `status: 'none'` is "no run at this sha", never "could not read". A
22
27
  * forge the CLI lands code on and releases on, but never writes issues to, implements
23
- * `FORGE_METHODS` (#681): the CI verdict, a READ of the issue list, and the release object —
28
+ * `FORGE_METHODS` (#681): the CI verdict, READS of the issue list, one issue and one comment (#740),
29
+ * and the release object —
24
30
  * tools/lib/ci-forgejo.js, Forgejo commit statuses and `/releases`. `CI_METHODS` stays the subset
25
31
  * the landing path (#678) needs. Which engine a repo gets is `engineFor` below.
26
32
  *
@@ -41,6 +47,7 @@ const METHODS = Object.freeze([
41
47
  { name: 'currentLogin', kind: 'read', returns: 'login | null' },
42
48
  { name: 'issueView', kind: 'read', returns: 'object | null' },
43
49
  { name: 'issueListAll', kind: 'read', returns: 'result + data: issue[] | null' },
50
+ { name: 'commentView', kind: 'read', returns: '{ body, login, createdAt, htmlUrl } | null' },
44
51
  { name: 'issueCreate', kind: 'write', returns: 'result + number, url' },
45
52
  { name: 'issueComment', kind: 'write', returns: 'result' },
46
53
  { name: 'issueClose', kind: 'write', returns: 'result' },
@@ -66,9 +73,11 @@ const CI_METHODS = Object.freeze(['ciVerdict']);
66
73
  * The methods a forge engine implements (#681): landing (`CI_METHODS`), the batch turn's run read
67
74
  * (#742, `runsAtRef`), plus what a release needs —
68
75
  * the issue list READ (switch markers, the release hold, an existing tracking record) and the release
69
- * object. No issue write is here on purpose: #678's ruling keeps the forge's tracker the adopter's.
76
+ * object — plus (#740) the reads a hand-off land makes: one comment by id (`commentView`) and one
77
+ * issue's comments and state (`issueView`, for the executor's claim). No issue write is here on
78
+ * purpose: #678's ruling keeps the forge's tracker the adopter's.
70
79
  */
71
- const FORGE_METHODS = Object.freeze([...CI_METHODS, 'runsAtRef', 'issueListAll', 'releaseView', 'releaseCreate']);
80
+ const FORGE_METHODS = Object.freeze([...CI_METHODS, 'runsAtRef', 'issueListAll', 'issueView', 'commentView', 'releaseView', 'releaseCreate']);
72
81
 
73
82
  /**
74
83
  * Throw, naming every contract method `impl` lacks. Returns `impl` when it is complete.