@futurelastic/colab-handbook 1.13.0-rc.2 → 1.13.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/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
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.13.0-rc.2"
35
+ "version": "1.13.0-rc.4"
36
36
  }
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 String(s).trim();
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
  /**
@@ -5677,7 +5704,8 @@ function cmdWorktreeNew(argv) {
5677
5704
 
5678
5705
  // #488: the scratch dirs (plans, briefs) are hidden in the clone's shared info/exclude — one
5679
5706
  // write covers the main checkout and every worktree, with no per-repo .gitignore diff.
5680
- ensureScratchExcluded(repoAbs);
5707
+ // #527: and the worktree subdir itself, or trunk's `git add -A` stages this worktree as a gitlink.
5708
+ ensureScratchExcluded(repoAbs, config);
5681
5709
 
5682
5710
  // 5. optional repo hook (machine-specific steps plug in here)
5683
5711
  const hook = runHook(repoAbs, 'post-create', { wtPath, name, branch, ports: alloc.chosenPorts, trunk, base, issues });
@@ -8023,13 +8051,17 @@ function gitExcludePath(repoAbs) {
8023
8051
  /**
8024
8052
  * #488: append the scratch-dir exclude lines (scratch-dirs.js `excludeLines`) to the clone's shared
8025
8053
  * info/exclude, idempotently. Best-effort: a failure warns and never blocks the caller.
8054
+ * #527: `config` given → the worktree subdir's line too (`worktreeExcludeLine`), so whatever creates
8055
+ * the default worktree dir also hides it — an adopted repo's `.gitignore` has never heard of it.
8026
8056
  */
8027
- function ensureScratchExcluded(repoAbs) {
8057
+ function ensureScratchExcluded(repoAbs, config = null) {
8028
8058
  const excludeFile = gitExcludePath(repoAbs);
8029
8059
  if (!excludeFile) return [];
8030
8060
  let before = null;
8031
8061
  try { before = fs.readFileSync(excludeFile, 'utf8'); } catch (_) { /* absent */ }
8032
8062
  const lines = scratchDirs.excludeLines();
8063
+ const wtLine = config ? scratchDirs.worktreeExcludeLine(worktreeSubdir(config)) : null;
8064
+ if (wtLine && !lines.includes(wtLine)) lines.push(wtLine);
8033
8065
  const missing = localAdopt.missingExcludeLines(before, lines);
8034
8066
  if (!missing.length) return [];
8035
8067
  try {
@@ -8498,6 +8530,12 @@ async function cmdAdopt(argv) {
8498
8530
  local = adoptLocalPrepare(repoAbs, opts);
8499
8531
  if (local.exit !== undefined) return local.exit;
8500
8532
  }
8533
+ // #527: a repo adopted before `worktree new` hid its own dir gets the same exclude lines here —
8534
+ // machine-local (info/exclude), idempotent, never a committed diff. --local already wrote them.
8535
+ if (!opts.local) {
8536
+ const hidden = ensureScratchExcluded(repoAbs, state.loadConfig());
8537
+ if (hidden.length && !opts.json) print(`✓ hid ${hidden.join(' ')} in .git/info/exclude (machine-local)`);
8538
+ }
8501
8539
  const io = adoptIo(repoAbs);
8502
8540
  const extra = adoptGitExtras(repoAbs, opts);
8503
8541
  if (local) { extra.trunk = local.trunk; extra.trunkSource = 'local-integration'; }
@@ -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
  };
@@ -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
- return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
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
  /**
@@ -81,6 +81,18 @@ function excludeLines(env = process.env) {
81
81
  return out;
82
82
  }
83
83
 
84
+ /**
85
+ * #527: the root-anchored exclude line for the worktree subdir (`colab worktree new` creates
86
+ * worktrees INSIDE the clone, `.worktrees/` by default), or null when the configured subdir is
87
+ * absolute or climbs out of the repo. Deliberately NOT part of `excludeLines`: those are scratch
88
+ * (disposable, filtered out of the uncommitted-work gate by `isScratchPath`); a worktree is live
89
+ * work and must never be filtered — it only has to stay out of the main checkout's `git status`,
90
+ * where one habitual `git add -A` would otherwise commit it as an embedded-repo gitlink.
91
+ */
92
+ function worktreeExcludeLine(worktreeSubdir) {
93
+ return anchoredLine(normalise(worktreeSubdir, '.worktrees'));
94
+ }
95
+
84
96
  /**
85
97
  * Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
86
98
  * keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
@@ -102,5 +114,5 @@ function withoutScratch(porcelainText, env = process.env) {
102
114
  module.exports = {
103
115
  DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
104
116
  plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
105
- excludeLines, isScratchPath, withoutScratch,
117
+ excludeLines, worktreeExcludeLine, isScratchPath, withoutScratch,
106
118
  };