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

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.
@@ -54,7 +54,7 @@ function releaseComments(sorted) {
54
54
  }
55
55
 
56
56
  /**
57
- * Live claim comments on an issue. Returns [{login, host, machine, session, sessionName, at,
57
+ * Live claim comments on an issue. Returns [{login, host, machine, factory, session, sessionName, at,
58
58
  * branch, worktree, identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
59
59
  * is built from `comps` (claim-identity.js `components()`, #267); the raw fields are returned too
60
60
  * for callers that need `sameClaimant`'s degrade-on-missing comparison.
@@ -92,7 +92,8 @@ function liveClaimComments(comments, comps) {
92
92
  const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
93
93
  const at = c.createdAt;
94
94
  // #578: branch/worktree ride along so a reader can ask WHICH branch a live claim holds.
95
- const entry = { login, host, machine: machineTok, session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
95
+ // #743: the factory too — the same login under another factory is another holder (sameClaimant).
96
+ const entry = { login, host, machine: machineTok, factory: claim.factory || '', session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
96
97
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
97
98
  || (r.login === login && !isNamedWinner(entry, r.winner))));
98
99
  if (!cancelled) live.push({ ...entry, identity: claimIdentity.identityString({ login, host, session }, comps) });
@@ -102,7 +103,7 @@ function liveClaimComments(comments, comps) {
102
103
 
103
104
  /**
104
105
  * Deterministic verdict on the simultaneous-claim race. Given the issue's comments and our own
105
- * identity (`myLogin`/`myHost`/`mySession`/`myMachine`): if a live claim that is NOT us under
106
+ * identity (`myLogin`/`myHost`/`mySession`/`myMachine`/`myFactory` — #743): if a live claim that is NOT us under
106
107
  * `comps` (`sameClaimant`, #267) is EARLIER than our own earliest live claim, by no more than
107
108
  * `RACE_WINDOW_MS` → we lost (returns the winner). Exact-timestamp ties break on identity string
108
109
  * (lexicographically smaller identity wins), so both racers, reading the same comments, reach the
@@ -122,10 +123,10 @@ function liveClaimComments(comments, comps) {
122
123
  * a record posts a SECOND comment from us, and anchoring on the latest of those would let that
123
124
  * correction restart our own priority — costing us a race we had already won.
124
125
  */
125
- function tieBreakVerdict(comments, myLogin, myHost, mySession, comps, myMachine = null) {
126
+ function tieBreakVerdict(comments, myLogin, myHost, mySession, comps, myMachine = null, myFactory = '') {
126
127
  comps = comps || claimIdentity.DEFAULT_COMPONENTS;
127
128
  const live = liveClaimComments(comments, comps);
128
- const me = { login: myLogin, host: myHost, session: mySession || '', machine: myMachine || '' };
129
+ const me = { login: myLogin, host: myHost, session: mySession || '', machine: myMachine || '', factory: myFactory || '' };
129
130
  const mine = live
130
131
  .filter((c) => claimIdentity.sameClaimant(c, me, comps))
131
132
  .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0))[0]; // our EARLIEST live claim
@@ -159,9 +159,25 @@ function machineScheme(id) {
159
159
  return i === -1 ? '' : id.slice(0, i);
160
160
  }
161
161
 
162
+ /**
163
+ * Could `a` and `b` be the SAME factory (#743)? Two teams may work one repository under one forge
164
+ * login (`.github/factories.yml`, #739), so a login match alone no longer names a holder: a claim
165
+ * that names factory `x` and one that names `y` are two holders, whatever login posted them. Like
166
+ * the session (DEGRADE-ON-MISSING above), the factory decides only when BOTH sides carry one — a
167
+ * comment written before #743, or on a repository with no factories file, names none, and must not
168
+ * turn our own earlier claim into a stranger's. Not behind the claimIdentity knob: the factories
169
+ * file is itself the adopter's declaration that factories are distinct holders.
170
+ */
171
+ function sameFactory(a, b) {
172
+ const af = String((a && a.factory) || '').trim();
173
+ const bf = String((b && b.factory) || '').trim();
174
+ return !af || !bf || af === bf;
175
+ }
176
+
162
177
  /**
163
178
  * Are `a` and `b` the SAME claimant under `comps`? `login` and the machine (`sameHost`, #327) are
164
- * always required to match — they are the baseline every component set includes. `session`
179
+ * always required to match — they are the baseline every component set includes — and so is the
180
+ * factory where both name one (`sameFactory`, #743). `session`
165
181
  * sharpens the match ONLY when `comps` includes it AND both sides carry a non-empty value that is a
166
182
  * real session; either side blank, or either side a planner intent id (#326 — replaced by the real
167
183
  * session at spawn, so it is not a different claimant), degrades that pair back to the coarse
@@ -170,6 +186,7 @@ function machineScheme(id) {
170
186
  function sameClaimant(a, b, comps) {
171
187
  if (!a || !b) return false;
172
188
  if ((a.login || '') !== (b.login || '')) return false;
189
+ if (!sameFactory(a, b)) return false;
173
190
  if (!sameHost(a, b)) return false;
174
191
  if (comps && comps.includes('session') && a.session && b.session
175
192
  && !isIntentSession(a.session) && !isIntentSession(b.session)) {
@@ -227,6 +244,6 @@ const { looksLikeSessionId } = require('./codec/claim'); // one copy of the rule
227
244
  module.exports = {
228
245
  DEFAULT_COMPONENTS, FINE_COMPONENTS,
229
246
  claimIdentityProblem, components, identityString, sameClaimant, mergeClaimRecord,
230
- looksLikeSessionId, isIntentSession, sameHost,
247
+ looksLikeSessionId, isIntentSession, sameHost, sameFactory,
231
248
  shouldDerivePersonSession, derivePersonSession, isPersonSession,
232
249
  };
@@ -0,0 +1,167 @@
1
+ 'use strict';
2
+ /**
3
+ * #744 — `colab claim --force` over ANOTHER FACTORY's claim.
4
+ *
5
+ * Before this, `--force` took over any holder without a human; only a live checkout place-claim
6
+ * asked for `COLAB_HUMAN=1`. Inside one team that is a session clearing a dead colleague's claim.
7
+ * Across factories (`.github/factories.yml`, #739) it is one team taking another team's work, so the
8
+ * takeover needs both of:
9
+ *
10
+ * - the STALE rule — nothing new on the holder's claim for STALE_DAYS (5) days: the newest commit
11
+ * on any remote ref that carries the issue (the claim lock, a legacy claim ref, the claim's
12
+ * branch), or, with no remote ref at all, the newest live claim comment; and
13
+ * - a HUMAN — `COLAB_HUMAN=1` together with `--answered-by <name>`, the bar `colab release
14
+ * finalize` and `colab ship`'s human door already use.
15
+ *
16
+ * WHO IS ANOTHER FACTORY. Read from trunk's committed factories file only (the caller's job, the
17
+ * `trust-humans:` rule). No file → one team, the rule is off and `--force` behaves as before. A file
18
+ * is present → a foreign holder counts as another factory UNLESS it is proven to be this machine's
19
+ * own factory: an unknown holder (a branch with no machine prefix, an agent login, a machine the file
20
+ * does not list) and an invalid file both fail closed, the stance `factories.js` takes everywhere.
21
+ *
22
+ * PURE: decisions over values the caller read. No git, no network, no clock (`nowMs` is passed in).
23
+ */
24
+
25
+ const { machineLabel, parse: parseBranch } = require('./branch-name.js');
26
+ const { sameHostName } = require('./machine.js');
27
+
28
+ const STALE_DAYS = 5;
29
+ const DAY_MS = 24 * 60 * 60 * 1000;
30
+
31
+ function usableDoc(parsed) { return parsed && parsed.valid && parsed.doc ? parsed.doc : null; }
32
+
33
+ /**
34
+ * The factory a machine NAME belongs to, compared as branch-prefix labels on both sides (`Box_A.local`
35
+ * and `box-a` are one machine), or null. A factories file lists machine ids as labels, and a claim
36
+ * lock's `Machine:` trailer is one.
37
+ */
38
+ function factoryOfMachineName(parsed, name) {
39
+ const doc = usableDoc(parsed);
40
+ const want = machineLabel(name || '');
41
+ if (!doc || !want) return null;
42
+ for (const [id, f] of Object.entries(doc.factories)) {
43
+ if (f.machines.some((m) => machineLabel(m) === want)) return id;
44
+ }
45
+ return null;
46
+ }
47
+
48
+ /** The factory a hostname — raw, or the `h:` token a public claim comment carries — belongs to. */
49
+ function factoryOfHost(parsed, host) {
50
+ const doc = usableDoc(parsed);
51
+ if (!doc || !host) return null;
52
+ for (const [id, f] of Object.entries(doc.factories)) {
53
+ if (f.machines.some((m) => sameHostName(m, host))) return id;
54
+ }
55
+ return null;
56
+ }
57
+
58
+ /** The ONE factory every login in `logins` is a declared human of, or null (none, or split). */
59
+ function factoryOfLogins(parsed, logins) {
60
+ const doc = usableDoc(parsed);
61
+ if (!doc || !logins || !logins.length) return null;
62
+ const ids = new Set();
63
+ for (const login of logins) {
64
+ const l = String(login || '').toLowerCase();
65
+ const id = Object.entries(doc.factories).find(([, f]) => f.humans.includes(l));
66
+ if (!id) return null;
67
+ ids.add(id[0]);
68
+ }
69
+ return ids.size === 1 ? [...ids][0] : null;
70
+ }
71
+
72
+ /**
73
+ * The factory holding a conflict, or null when the record does not say. `c` is one entry of the
74
+ * conflict lists `colab claim` builds:
75
+ * kind 'remote' — `{ lock, machine, branch, claimRef }`: a lock names its machine; a branch (or a
76
+ * legacy claim ref) names one only through a `<login>/<machine>/` prefix.
77
+ * kind 'gh' — `{ assignees, otherFactory?, otherMachine?, cotenant? }`: a claim comment names
78
+ * its factory (#743) or, before that, its host; an assignee with no comment is
79
+ * resolved through the file's `humans`.
80
+ * kind 'local' — this machine's own state, so this machine's factory.
81
+ */
82
+ function holderFactory(parsed, kind, c, mine = null) {
83
+ if (!usableDoc(parsed) || !c) return null;
84
+ if (kind === 'local') return mine;
85
+ if (kind === 'remote') {
86
+ if (c.lock) return factoryOfMachineName(parsed, c.machine) || prefixFactory(parsed, c.branch);
87
+ return prefixFactory(parsed, c.branch);
88
+ }
89
+ if (kind === 'gh') {
90
+ const comment = holderComment(c);
91
+ // #743: a live claim comment names its factory outright; the host is the fallback for a comment
92
+ // written before #743. Never the assignee once a comment exists: on `otherFactory` the assignee
93
+ // is OUR OWN login (one login, two teams), and resolving it would name this factory — fail open.
94
+ if (comment) {
95
+ return String(comment.factory || '').trim()
96
+ || factoryOfHost(parsed, comment.host) || factoryOfLogins(parsed, [comment.login]);
97
+ }
98
+ return factoryOfLogins(parsed, c.assignees || []);
99
+ }
100
+ return null;
101
+ }
102
+
103
+ /**
104
+ * The live claim comment a `gh` conflict carries, or null: `otherFactory` (#743 — our own login under
105
+ * another factory, the more specific finding, so first), `otherMachine` (#325), `cotenant` (#327).
106
+ */
107
+ function holderComment(c) {
108
+ return (c && (c.otherFactory || c.otherMachine || c.cotenant)) || null;
109
+ }
110
+
111
+ function prefixFactory(parsed, branch) {
112
+ const p = branch ? parseBranch(branch) : null;
113
+ return p && p.machine ? factoryOfMachineName(parsed, p.machine) : null;
114
+ }
115
+
116
+ /**
117
+ * Is taking over ONE issue a cross-factory takeover? `file` = `{ present, parsed }` read from trunk;
118
+ * `holders` = the factory each record holding the issue resolves to (`holderFactory`), null where a
119
+ * record does not say. One issue is often held by several records of ONE holder — a lock naming its
120
+ * machine, an assignee naming nothing — so a silent record defers to one that speaks.
121
+ * no file → false (one team; nothing here applies)
122
+ * invalid file → true (fail closed: an invalid file trusts nobody)
123
+ * a record proves another factory → true
124
+ * no record proves any factory → true (a holder nothing ties to this team)
125
+ * every proving record says mine → false
126
+ */
127
+ function isCrossFactory(file, mine, holders) {
128
+ if (!file || !file.present) return false;
129
+ if (!usableDoc(file.parsed)) return true;
130
+ const proven = (holders || []).filter(Boolean);
131
+ if (!mine || !proven.length) return true;
132
+ return proven.some((f) => f !== mine);
133
+ }
134
+
135
+ /**
136
+ * The newest activity time (ms) across what a holder left — commit times of its remote refs and the
137
+ * times of its live claim comments — or null when nothing could be read. `times` = numbers or null.
138
+ */
139
+ function lastActivity(times) {
140
+ const known = (times || []).filter((t) => Number.isFinite(t));
141
+ return known.length ? Math.max(...known) : null;
142
+ }
143
+
144
+ /** `{ stale, idleDays }` — unknown activity is never stale (fail closed). */
145
+ function staleness(lastMs, nowMs, days = STALE_DAYS) {
146
+ if (!Number.isFinite(lastMs) || !Number.isFinite(nowMs)) return { stale: false, idleDays: null };
147
+ const idle = nowMs - lastMs;
148
+ return { stale: idle >= days * DAY_MS, idleDays: Math.floor(idle / DAY_MS) };
149
+ }
150
+
151
+ /**
152
+ * The verdict for one cross-factory takeover: `{ ok, missing: [..] }`, `missing` naming each bar
153
+ * not met — 'human' (COLAB_HUMAN=1 with --answered-by) and/or 'stale'. Both are always reported, so
154
+ * one refusal says everything a person has to fix.
155
+ */
156
+ function takeoverVerdict({ colabHuman, answeredBy, stale }) {
157
+ const missing = [];
158
+ if (!(colabHuman && String(answeredBy || '').trim())) missing.push('human');
159
+ if (!stale) missing.push('stale');
160
+ return { ok: missing.length === 0, missing };
161
+ }
162
+
163
+ module.exports = {
164
+ STALE_DAYS, DAY_MS,
165
+ factoryOfMachineName, factoryOfHost, factoryOfLogins, holderComment, holderFactory, isCrossFactory,
166
+ lastActivity, staleness, takeoverVerdict,
167
+ };
@@ -7,6 +7,7 @@ export const RELEASE_MARK: '✅ Released';
7
7
  export const CLAIM_RE: RegExp;
8
8
  export const SESSION_RE: RegExp;
9
9
  export const MACHINE_RE: RegExp;
10
+ export const FACTORY_RE: RegExp;
10
11
  export const YIELD_RE: RegExp;
11
12
 
12
13
  export function looksLikeSessionId(v: unknown): boolean;
@@ -30,6 +31,8 @@ export interface DecodedClaim extends SessionField {
30
31
  at: string;
31
32
  /** `m:` digest (#327), or '' on a legacy comment. */
32
33
  machine: string;
34
+ /** The claiming factory's id (#743, `.github/factories.yml`), or '' where none was named. */
35
+ factory: string;
33
36
  }
34
37
  export function encodeClaim(claim?: Partial<DecodedClaim>): string;
35
38
  export function decodeClaim(body: string | null | undefined): DecodedClaim | null;
@@ -30,6 +30,11 @@ const SESSION_RE = /· session (.+)$/;
30
30
  // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
31
31
  // comment (no such field) simply has no machine and is compared by host.
32
32
  const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
33
+ // #743: the claiming FACTORY (`.github/factories.yml`, #739) — written after the machine and BEFORE
34
+ // the session suffix, for the same reason the machine field sits there: CLAIM_RE's four groups and
35
+ // SESSION_RE's end anchor read a new comment exactly as they read a legacy one, so an older colab
36
+ // parses it unchanged and simply ignores the field. The id grammar is factories.js FACTORY_ID_RE.
37
+ const FACTORY_RE = /· factory `([a-z0-9][a-z0-9-]{0,38})`/;
33
38
  // A yield: the loser of a race releases, naming the winner by its identity string
34
39
  // (`claimIdentity.identityString` — `login@host`, or `login@host#session` under the fine setting).
35
40
  const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
@@ -102,14 +107,15 @@ function parseIdentity(s) {
102
107
  * (#327, the field is then omitted); `host` is the raw hostname or its `h:` token, whichever the
103
108
  * destination allows (#369 — deciding that is the caller's job, not the codec's).
104
109
  */
105
- function encodeClaim({ worktree, branch, host, at, machine, session, sessionName } = {}) {
110
+ function encodeClaim({ worktree, branch, host, at, machine, factory, session, sessionName } = {}) {
106
111
  const base = `${CLAIM_MARK} — worktree \`${worktree || '-'}\` · branch \`${branch || '-'}\` · host \`${host}\` · ${at}`;
107
112
  const mach = machine ? ` · machine \`${machine}\`` : '';
108
- return base + mach + encodeSessionField(session, sessionName);
113
+ const fac = factory ? ` · factory \`${factory}\`` : ''; // #743 — omitted where no factories file names one
114
+ return base + mach + fac + encodeSessionField(session, sessionName);
109
115
  }
110
116
 
111
117
  /**
112
- * A claim comment body → { worktree, branch, host, at, machine, session, sessionName }, or null when
118
+ * A claim comment body → { worktree, branch, host, at, machine, factory, session, sessionName }, or null when
113
119
  * the body carries no claim. Lenient exactly where the readers always were (CLAIM_RE is unanchored,
114
120
  * a legacy comment simply lacks machine/session), and lossless on what `encodeClaim` writes:
115
121
  * `worktree`/`branch` keep a literal `-` rather than mapping it to empty, so the pair round-trips.
@@ -119,8 +125,12 @@ function decodeClaim(body) {
119
125
  const m = str.match(CLAIM_RE);
120
126
  if (!m) return null;
121
127
  const mm = str.match(MACHINE_RE);
128
+ // #743: the factory is read only BEFORE the session tail — a session name is free text and could
129
+ // itself spell `· factory \`x\``; the writer never puts the field after it.
130
+ const tail = str.match(SESSION_RE);
131
+ const fm = (tail ? str.slice(0, tail.index) : str).match(FACTORY_RE);
122
132
  const { session, sessionName } = parseSessionField(str);
123
- return { worktree: m[1], branch: m[2], host: m[3], at: m[4], machine: mm ? mm[1] : '', session, sessionName };
133
+ return { worktree: m[1], branch: m[2], host: m[3], at: m[4], machine: mm ? mm[1] : '', factory: fm ? fm[1] : '', session, sessionName };
124
134
  }
125
135
 
126
136
  /**
@@ -147,7 +157,7 @@ function decodeRelease(body) {
147
157
  }
148
158
 
149
159
  module.exports = {
150
- CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE,
160
+ CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, FACTORY_RE, YIELD_RE,
151
161
  looksLikeSessionId,
152
162
  encodeSessionField, parseSessionField,
153
163
  encodeIdentity, parseIdentity,
@@ -262,6 +262,7 @@
262
262
  "host": "h:ee4bcb5b2678",
263
263
  "at": "2026-10-05T03:16:29.738Z",
264
264
  "machine": "m:a873b2982c1d",
265
+ "factory": "",
265
266
  "session": "https://claude.ai/code/session_02EXAMPLE00000000000000",
266
267
  "sessionName": "colab-handbook-482"
267
268
  }
@@ -274,6 +275,7 @@
274
275
  "host": "h:ee4bcb5b2678",
275
276
  "at": "2026-10-04T11:53:58.625Z",
276
277
  "machine": "m:a873b2982c1d",
278
+ "factory": "",
277
279
  "session": "https://claude.ai/code/session_03EXAMPLE00000000000000",
278
280
  "sessionName": "colab-handbook-467"
279
281
  }
@@ -286,6 +288,7 @@
286
288
  "host": "h:ee4bcb5b2678",
287
289
  "at": "2026-10-05T11:02:52.482Z",
288
290
  "machine": "m:a873b2982c1d",
291
+ "factory": "",
289
292
  "session": "",
290
293
  "sessionName": "colab-handbook-495"
291
294
  }
@@ -298,6 +301,7 @@
298
301
  "host": "h:48773651d08a",
299
302
  "at": "2026-08-25T02:05:46.075Z",
300
303
  "machine": "",
304
+ "factory": "",
301
305
  "session": "https://claude.ai/code/session_76EXAMPLE00000000000000",
302
306
  "sessionName": ""
303
307
  }
@@ -310,6 +314,7 @@
310
314
  "host": "h:ca0012aa6308",
311
315
  "at": "2026-09-01T11:02:03.931Z",
312
316
  "machine": "",
317
+ "factory": "",
313
318
  "session": "",
314
319
  "sessionName": ""
315
320
  }
@@ -322,6 +327,7 @@
322
327
  "host": "h:ee4bcb5b2678",
323
328
  "at": "2026-09-25T10:48:18.652Z",
324
329
  "machine": "m:a873b2982c1d",
330
+ "factory": "",
325
331
  "session": "https://claude.ai/code/session_14EXAMPLE00000000000000",
326
332
  "sessionName": "colab-handbook-297💻"
327
333
  }
@@ -334,9 +340,24 @@
334
340
  "host": "h:ee4bcb5b2678",
335
341
  "at": "2026-09-13T16:11:15.694Z",
336
342
  "machine": "",
343
+ "factory": "",
337
344
  "session": "https://claude.ai/code/session_40EXAMPLE00000000000000",
338
345
  "sessionName": "colab-handbook-325-326-327"
339
346
  }
347
+ },
348
+ {
349
+ "note": "synthetic (#743): the first claim shape carrying a factory, written in this format before any tracker held one; the factory id is the factories.yml example's",
350
+ "wire": "🔒 Claimed — worktree `claim-factory-743` · branch `feat/claim-factory-743` · host `h:ee4bcb5b2678` · 2026-11-14T10:41:07.512Z · machine `m:a873b2982c1d` · factory `core` · session [colab-handbook-743](https://claude.ai/code/session_05EXAMPLE00000000000000)",
351
+ "decoded": {
352
+ "worktree": "claim-factory-743",
353
+ "branch": "feat/claim-factory-743",
354
+ "host": "h:ee4bcb5b2678",
355
+ "at": "2026-11-14T10:41:07.512Z",
356
+ "machine": "m:a873b2982c1d",
357
+ "factory": "core",
358
+ "session": "https://claude.ai/code/session_05EXAMPLE00000000000000",
359
+ "sessionName": "colab-handbook-743"
360
+ }
340
361
  }
341
362
  ],
342
363
  "releases": [
@@ -55,7 +55,9 @@ const SSH_KEY_RE = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-e
55
55
 
56
56
  // ── the shared vocabulary (CONVENTIONS.md §5, *Factories*) ──────────────────────────────────
57
57
  // Prose is the source; these are the machine copy. Not in tools/lib/codec yet — that is a closed
58
- // public surface, and nothing writes these strings yet; the first writer (#743) moves what it writes.
58
+ // public surface, and nothing writes these strings yet. #743 writes a factory FIELD on claim comments
59
+ // (codec/claim.js FACTORY_RE), not the `factory:<id>` label, so none of these moved; the first command
60
+ // that writes one of them moves it.
59
61
  const FACTORY_LABEL_PREFIX = 'factory:';
60
62
  const SLICE_LABEL_PREFIX = 'slice:';
61
63
  const QUEUE_READY_LABEL = 'queue:ready';
package/tools/lib/git.js CHANGED
@@ -543,6 +543,28 @@ function readClaimLock(repo, remote, num, fullSha) {
543
543
  return { ok: true, trailers: parseClaimLockMessage(body.stdout) };
544
544
  }
545
545
 
546
+ /**
547
+ * #744 — the committer time (ms) of the commit a remote ref points at, or null when it cannot be read.
548
+ * `ref` is the full remote ref (`refs/heads/<b>`, `refs/claims/<b>`, `refs/heads/claim/<N>`); `sha`
549
+ * (short or full) is what `ls-remote` saw. Read locally when this clone has the commit, else fetched
550
+ * by ref name. A null is the caller's to treat as "recent" (fail closed: an unreadable holder is
551
+ * never proven stale).
552
+ */
553
+ function remoteRefCommitTime(repo, remote, ref, sha) {
554
+ const at = (rev) => {
555
+ const r = git(['log', '-1', '--format=%ct', rev, '--'], repo);
556
+ const n = r.ok ? Number(String(r.stdout).trim()) : NaN;
557
+ return Number.isFinite(n) && n > 0 ? n * 1000 : null;
558
+ };
559
+ if (sha) {
560
+ const local = git(['cat-file', '-e', `${sha}^{commit}`], repo);
561
+ if (local.ok) return at(sha);
562
+ }
563
+ const f = git(['fetch', '--quiet', '--no-tags', remote, ref], repo, { timeoutMs: 60_000 });
564
+ if (!f.ok) return null;
565
+ return at('FETCH_HEAD');
566
+ }
567
+
546
568
  /** List worktree paths registered in a repo (porcelain). */
547
569
  function worktreeList(repo) {
548
570
  const r = git(['worktree', 'list', '--porcelain'], repo);
@@ -1859,7 +1881,7 @@ module.exports = {
1859
1881
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1860
1882
  claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
1861
1883
  CLAIM_LOCK_PREFIX, claimLockRef, parseClaimLocks, claimLockMessage, parseClaimLockMessage, makeClaimLockCommit,
1862
- takeClaimLocks, releaseClaimLock, readClaimLock,
1884
+ takeClaimLocks, releaseClaimLock, readClaimLock, remoteRefCommitTime,
1863
1885
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1864
1886
  dirtyTracked, dirtyUntracked, dirtyAny,
1865
1887
  ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghRunsAtShaUnfiltered, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,