@futurelastic/colab-handbook 1.13.0-rc.3 → 1.13.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.
- package/README.md +5 -0
- package/README.vi.md +6 -0
- package/package.json +1 -1
- package/tools/colab +87 -8
- package/tools/lib/claim-identity.js +38 -0
- package/tools/lib/codec/claim.js +3 -1
package/README.md
CHANGED
|
@@ -113,6 +113,11 @@ Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
|
|
|
113
113
|
handbook), and `migration-review` (review a branch's migrations, for whoever a
|
|
114
114
|
repo binds to that role).
|
|
115
115
|
|
|
116
|
+
**Running the loop by hand at a terminal?** With no `--session`, `colab` names
|
|
117
|
+
you `person:<git user.email>/<host token>`, so claims and ship evidence say who
|
|
118
|
+
you are. If you work on several units at once from separate shells, give each
|
|
119
|
+
shell its own `COLAB_SESSION=<any stable id>` so their holds stay apart.
|
|
120
|
+
|
|
116
121
|
**Words you will meet:**
|
|
117
122
|
|
|
118
123
|
- **Trunk** — the branch sessions merge into (`trunk:` in `project.yml`).
|
package/README.vi.md
CHANGED
|
@@ -112,6 +112,12 @@ Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó,
|
|
|
112
112
|
nhất), và `migration-review` (review migration của một nhánh, cho người/agent
|
|
113
113
|
được repo gán vai đó).
|
|
114
114
|
|
|
115
|
+
**Tự chạy vòng này bằng tay ở terminal?** Không có `--session` thì `colab` đặt
|
|
116
|
+
tên bạn là `person:<git user.email>/<host token>`, nên claim và bằng chứng ship
|
|
117
|
+
đều ghi rõ ai làm. Nếu làm nhiều đơn vị việc cùng lúc ở các shell khác nhau,
|
|
118
|
+
đặt cho mỗi shell một `COLAB_SESSION=<id ổn định bất kỳ>` để các hold không lẫn
|
|
119
|
+
vào nhau.
|
|
120
|
+
|
|
115
121
|
**Mấy từ sẽ gặp:**
|
|
116
122
|
|
|
117
123
|
- **Trunk** — nhánh các phiên merge vào (`trunk:` trong `project.yml`).
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -283,11 +283,38 @@ function myMachineId() { return machine.localMachine().id || null; }
|
|
|
283
283
|
|
|
284
284
|
/**
|
|
285
285
|
* Resolve the Claude session URL for this invocation: --session flag > COLAB_SESSION env >
|
|
286
|
-
* '' (absent, never an error). Free-form — typically a session URL.
|
|
286
|
+
* a DERIVED person identity (#528) > '' (absent, never an error). Free-form — typically a session URL.
|
|
287
|
+
*
|
|
288
|
+
* The derived step exists for a person at a plain terminal, who has no session runtime and so no
|
|
289
|
+
* id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
|
|
290
|
+
* warned three lines every time, and ship evidence read `implemented by: unknown`. It applies only
|
|
291
|
+
* when `COLAB_SESSION` is unset and the shell is not an agent's (`claimIdentity.
|
|
292
|
+
* shouldDerivePersonSession` has why) — an explicit flag or env value always wins.
|
|
287
293
|
*/
|
|
288
294
|
function resolveSession(opts) {
|
|
289
|
-
const s = opts.session || process.env.COLAB_SESSION || '';
|
|
290
|
-
return
|
|
295
|
+
const s = String(opts.session || process.env.COLAB_SESSION || '').trim();
|
|
296
|
+
return s || derivedPersonSession();
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* The derived person identity for this invocation, or ''. Memoized — one `git config` spawn, and
|
|
301
|
+
* the "derived" note is printed once per invocation (stderr, so `--json` stdout stays clean).
|
|
302
|
+
*/
|
|
303
|
+
let derivedSessionCache = null;
|
|
304
|
+
function derivedPersonSession() {
|
|
305
|
+
if (derivedSessionCache !== null) return derivedSessionCache;
|
|
306
|
+
derivedSessionCache = '';
|
|
307
|
+
if (!claimIdentity.shouldDerivePersonSession(process.env)) return derivedSessionCache;
|
|
308
|
+
const r = spawnSync('git', ['config', '--get', 'user.email'], { encoding: 'utf8' });
|
|
309
|
+
const email = r.status === 0 ? String(r.stdout || '').trim() : '';
|
|
310
|
+
let user = process.env.USER || '';
|
|
311
|
+
if (!user) { try { user = os.userInfo().username; } catch { user = ''; } }
|
|
312
|
+
derivedSessionCache = claimIdentity.derivePersonSession({ email, user, hostToken: machine.hostToken(HOST) });
|
|
313
|
+
if (derivedSessionCache) {
|
|
314
|
+
process.stderr.write(`· session: ${derivedSessionCache} (derived — no --session or COLAB_SESSION given; ` +
|
|
315
|
+
`either one overrides it)\n`);
|
|
316
|
+
}
|
|
317
|
+
return derivedSessionCache;
|
|
291
318
|
}
|
|
292
319
|
|
|
293
320
|
/**
|
|
@@ -11060,7 +11087,7 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
|
|
|
11060
11087
|
return {
|
|
11061
11088
|
name: raw.name, ok: true, class: null,
|
|
11062
11089
|
detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via}${viaDry} (raw: ${raw.detail})`,
|
|
11063
|
-
grantVerdict: null, cureVerdict,
|
|
11090
|
+
grantVerdict: null, cureVerdict, redSha,
|
|
11064
11091
|
};
|
|
11065
11092
|
}
|
|
11066
11093
|
|
|
@@ -11075,10 +11102,45 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
|
|
|
11075
11102
|
return {
|
|
11076
11103
|
name: raw.name, ok: true, class: null,
|
|
11077
11104
|
detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
|
|
11078
|
-
grantVerdict, cureVerdict,
|
|
11105
|
+
grantVerdict, cureVerdict, redSha,
|
|
11079
11106
|
};
|
|
11080
11107
|
}
|
|
11081
|
-
|
|
11108
|
+
// #534: both doors were consulted and both refused — say WHY on the row itself, so the prose table,
|
|
11109
|
+
// `--dry`, and B1's abort line all tell "needs a grant" from "missing evidence" from "stacked". The
|
|
11110
|
+
// JSON payload already carried `ciCure.reason`; the prose detail used to end at the raw trunk read.
|
|
11111
|
+
return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict)}`, grantVerdict, cureVerdict, redSha };
|
|
11112
|
+
}
|
|
11113
|
+
|
|
11114
|
+
/**
|
|
11115
|
+
* Which red-trunk door let a trunk-CI row pass — `'cure rule'`, `'ci-grant'`, or null for a row that
|
|
11116
|
+
* passed on its own (green) or did not pass (#538: B1 re-measures only a door the table relied on).
|
|
11117
|
+
*/
|
|
11118
|
+
function doorThatAdmitted(ciResult) {
|
|
11119
|
+
if (!ciResult || !ciResult.ok) return null;
|
|
11120
|
+
if (ciResult.cureVerdict && ciResult.cureVerdict.ok) return 'cure rule';
|
|
11121
|
+
if (ciResult.grantVerdict && ciResult.grantVerdict.ok) return 'ci-grant';
|
|
11122
|
+
return null;
|
|
11123
|
+
}
|
|
11124
|
+
|
|
11125
|
+
/** #538: the pause before B1's one re-measure — long enough for a transient `gh` failure to clear. */
|
|
11126
|
+
const B1_REMEASURE_MS = Number.isFinite(Number(process.env.COLAB_B1_REMEASURE_MS))
|
|
11127
|
+
&& process.env.COLAB_B1_REMEASURE_MS !== '' ? Number(process.env.COLAB_B1_REMEASURE_MS) : 3000;
|
|
11128
|
+
|
|
11129
|
+
/**
|
|
11130
|
+
* The " — cure rule (#281): …; ci-grant (#105): …" suffix of a refused trunk-CI row (#534). Empty
|
|
11131
|
+
* when neither door was consulted. One clause per door, each its own refusal reason verbatim — the
|
|
11132
|
+
* cure's `reason`, the grant's per-issue `missing[].reason` — never a re-wording, so the prose and
|
|
11133
|
+
* the `--dry --json` fields cannot read differently.
|
|
11134
|
+
*/
|
|
11135
|
+
function doorRefusalNote(cureVerdict, grantVerdict) {
|
|
11136
|
+
const parts = [];
|
|
11137
|
+
if (cureVerdict && !cureVerdict.ok && cureVerdict.reason) parts.push(`cure rule (#281): ${cureVerdict.reason}`);
|
|
11138
|
+
if (grantVerdict && !grantVerdict.ok) {
|
|
11139
|
+
const why = (grantVerdict.missing || []).map((m) => (m.issue ? `#${m.issue}: ` : '') + m.reason)
|
|
11140
|
+
.map((s) => s.replace(/^(#\d+): \1/, '$1')).join('; ');
|
|
11141
|
+
if (why) parts.push(`ci-grant (#105): ${why}`);
|
|
11142
|
+
}
|
|
11143
|
+
return parts.length ? ` — ${parts.join(' · ')}` : '';
|
|
11082
11144
|
}
|
|
11083
11145
|
|
|
11084
11146
|
/**
|
|
@@ -13119,12 +13181,29 @@ function cmdShip(argv) {
|
|
|
13119
13181
|
let ciGrantForTrailer = null; // #105: set below when B1 shipped UNDER a grant — read at commit-message time
|
|
13120
13182
|
let ciCureForTrailer = null; // #281: set below when B1 shipped UNDER the cure rule — read at commit-message time
|
|
13121
13183
|
if (gh) {
|
|
13122
|
-
const
|
|
13184
|
+
const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
|
|
13123
13185
|
(redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
|
|
13124
13186
|
(redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
|
|
13187
|
+
let ciResultB1 = measureB1();
|
|
13188
|
+
// #538: the table admitted this branch through a door (cure or grant) at red sha X, and B1 —
|
|
13189
|
+
// seconds later, at the SAME red sha — refused. Nothing the door judges moved (trunk's head is
|
|
13190
|
+
// X in both reads), so the likeliest cause is one of the ~10 `gh` reads a door makes failing
|
|
13191
|
+
// once, which every door reads as a refusal (fail closed). Measured: `--dry` said READY and the
|
|
13192
|
+
// real ship aborted here with only the raw "conclusion=failure". Re-measure ONCE, in full —
|
|
13193
|
+
// never reuse the table's verdict (B1 exists to catch a change) — and if it refuses again, abort
|
|
13194
|
+
// saying it was the door, with the door's own reason.
|
|
13195
|
+
const tableDoor = doorThatAdmitted(ciResult);
|
|
13196
|
+
if (!ciResultB1.ok && tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha) {
|
|
13197
|
+
warn(` B1: the ${tableDoor} admitted this branch in the table at ${target}@${shortSha(ciResult.redSha)} but refused on the re-check at the same sha — re-measuring once (a failed read refuses).`);
|
|
13198
|
+
ciWait.sleepSync(B1_REMEASURE_MS);
|
|
13199
|
+
ciResultB1 = measureB1();
|
|
13200
|
+
}
|
|
13125
13201
|
if (!ciResultB1.ok) {
|
|
13126
13202
|
cleanupEphemeral();
|
|
13127
|
-
|
|
13203
|
+
const sameRed = tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha;
|
|
13204
|
+
process.stderr.write(sameRed
|
|
13205
|
+
? `✗ B1: the ${tableDoor} admitted this branch in the precondition table, then refused twice on the re-check at the same ${target}@${shortSha(ciResult.redSha)} — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`
|
|
13206
|
+
: `✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
|
|
13128
13207
|
return 1;
|
|
13129
13208
|
}
|
|
13130
13209
|
if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
|
|
@@ -95,6 +95,43 @@ function isIntentSession(s) {
|
|
|
95
95
|
return /^intent:\S/.test(String(s == null ? '' : s).trim());
|
|
96
96
|
}
|
|
97
97
|
|
|
98
|
+
/**
|
|
99
|
+
* Should a blank session be DERIVED for a person at a plain terminal (#528)? Only when nothing was
|
|
100
|
+
* said at all: `COLAB_SESSION` is UNSET (an explicit `COLAB_SESSION=''` is a deliberate "present no
|
|
101
|
+
* identity" and is honoured as one), and the shell is not an agent's (`CLAUDECODE=1` / `AI_AGENT`,
|
|
102
|
+
* the same signal `place.resolveAnchor` reads). An agent keeps #242's refusal: two concurrent agent
|
|
103
|
+
* sessions on one machine would derive the SAME person id, and `place.conflict`'s same-holder
|
|
104
|
+
* exemption would then read one session's hold as the other's — the collision #242 exists to stop.
|
|
105
|
+
* A person running several units at once from separate shells has the same problem, which is why
|
|
106
|
+
* the README tells them to give each shell its own `COLAB_SESSION`.
|
|
107
|
+
*/
|
|
108
|
+
function shouldDerivePersonSession(env) {
|
|
109
|
+
const e = env || {};
|
|
110
|
+
if (Object.prototype.hasOwnProperty.call(e, 'COLAB_SESSION')) return false;
|
|
111
|
+
if (e.CLAUDECODE === '1' || e.AI_AGENT) return false;
|
|
112
|
+
return true;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The derived identity for a person (#528): `person:<who>/<hostToken>`, where `<who>` is git's
|
|
117
|
+
* `user.email`, else the OS user. The host is the opaque `h:` token (`machine.hostToken`), never
|
|
118
|
+
* the raw name: this value is written verbatim into claim comments, and a public tracker must not
|
|
119
|
+
* learn a machine's name from it (#369). Stable across invocations — the same person on the same
|
|
120
|
+
* machine always derives the same value, which is what a re-acquire needs. '' when no `<who>` or
|
|
121
|
+
* no host is available: then nothing is derived and the blank-session paths apply unchanged.
|
|
122
|
+
*/
|
|
123
|
+
function derivePersonSession({ email, user, hostToken } = {}) {
|
|
124
|
+
const who = String(email || '').trim() || String(user || '').trim();
|
|
125
|
+
const host = String(hostToken || '').trim();
|
|
126
|
+
if (!who || !host || /\s/.test(who)) return '';
|
|
127
|
+
return `person:${who}/${host}`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Is `s` a derived person identity (#528)? */
|
|
131
|
+
function isPersonSession(s) {
|
|
132
|
+
return /^person:\S+$/.test(String(s == null ? '' : s).trim());
|
|
133
|
+
}
|
|
134
|
+
|
|
98
135
|
/**
|
|
99
136
|
* Are `a` and `b` on the SAME machine (#327)? Both carry a `machine` → compare those (a raw id or
|
|
100
137
|
* the `m:` digest a claim comment carries — `machineToken` makes the two comparable); raw ids of
|
|
@@ -189,4 +226,5 @@ module.exports = {
|
|
|
189
226
|
DEFAULT_COMPONENTS, FINE_COMPONENTS,
|
|
190
227
|
claimIdentityProblem, components, identityString, sameClaimant, mergeClaimRecord,
|
|
191
228
|
looksLikeSessionId, isIntentSession, sameHost,
|
|
229
|
+
shouldDerivePersonSession, derivePersonSession, isPersonSession,
|
|
192
230
|
};
|
package/tools/lib/codec/claim.js
CHANGED
|
@@ -41,7 +41,9 @@ const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
|
|
|
41
41
|
function looksLikeSessionId(v) {
|
|
42
42
|
const s = String(v == null ? '' : v).trim();
|
|
43
43
|
if (!s) return false;
|
|
44
|
-
|
|
44
|
+
// #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
|
|
45
|
+
// too — a stable join key, not a display name — so it reads back as one from a claim comment.
|
|
46
|
+
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s);
|
|
45
47
|
}
|
|
46
48
|
|
|
47
49
|
/**
|