@futurelastic/colab-handbook 1.18.0-rc.1 → 1.18.0-rc.2

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.18.0-rc.1"
36
+ "version": "1.18.0-rc.2"
37
37
  }
package/tools/colab CHANGED
@@ -6127,7 +6127,12 @@ function cmdWorktreeRm(argv) {
6127
6127
  // Same shape as the uncommitted-work gate above, and deliberately in the CLI rather than in the
6128
6128
  // skills: code-wrap B4 and code-sweep §3 both tear worktrees down on separate code paths, so a
6129
6129
  // skill-level fix would have to be written twice into two files already drifting apart.
6130
- const owned = wt.path && fs.existsSync(wt.path) ? procs.processesInDir(wt.path) : [];
6130
+ // #668: whoever is RUNNING this command (this process, its shell, the agent CLI above it) is never
6131
+ // "owned" — `processesInDir` tags those `caller`. Stopping them was how a `colab ship` run from a
6132
+ // shell inside the worktree SIGTERMed its own caller mid-teardown: merged, never released.
6133
+ const inDir = wt.path && fs.existsSync(wt.path) ? procs.processesInDir(wt.path) : [];
6134
+ const owned = inDir.filter((p) => !p.caller);
6135
+ const callers = inDir.filter((p) => p.caller);
6131
6136
  if (owned.length && !opts.force) {
6132
6137
  warn(`Worktree "${name}" still owns ${owned.length} running process(es):`);
6133
6138
  for (const p of owned) {
@@ -6146,6 +6151,15 @@ function cmdWorktreeRm(argv) {
6146
6151
 
6147
6152
  const attachedIssues = Object.values(st0.claims).filter((c) => c.worktree === name).map((c) => normIssueNum(c.issue));
6148
6153
 
6154
+ // #668: this process's own cwd may be the directory about to go. Leave it first, so every spawn and
6155
+ // `process.cwd()` after the removal (the rest of a `colab ship` tail runs in this same process)
6156
+ // resolves against a directory that still exists.
6157
+ try {
6158
+ if (wt.path && procs.isInside(wt.path, process.cwd())) process.chdir(repoAbs);
6159
+ } catch (_) { /* cwd already gone (an earlier interrupted removal) — chdir to the repo regardless */
6160
+ try { process.chdir(repoAbs); } catch (_) { /* nothing left to do; every call below passes cwd */ }
6161
+ }
6162
+
6149
6163
  // pre-remove hook (abort on failure unless --force)
6150
6164
  const hook = runHook(repoAbs, 'pre-remove', { wtPath: wt.path, name, branch: wt.branch, ports: wt.ports, issues: attachedIssues });
6151
6165
  if (hook.ran && !hook.ok && !opts.force) throw new UserError(`pre-remove hook exited ${hook.code} — aborting (use --force to override)`);
@@ -6248,6 +6262,11 @@ function cmdWorktreeRm(argv) {
6248
6262
  `${gh ? '' : ' (local-only)'}` +
6249
6263
  `${trackerFailed.length ? ` — FAILED on ${trackerFailed.map((n) => '#' + n).join(', ')}: GitHub still shows in-progress there; local claim record KEPT (releasePending) — retry with: colab release <N>` : ''}`);
6250
6264
  if (killed.length) print(` stopped ${killed.filter((k) => k.gone).length}/${killed.length} owned process(es): ${killed.map((k) => k.pid).join(', ')}`);
6265
+ for (const c of callers) {
6266
+ if (String(c.pid) === String(process.pid)) continue; // this process moved out above
6267
+ print(` left running pid ${c.pid} (${c.command}) — it runs this command, so it is not the worktree's to stop (#668);`);
6268
+ print(` its cwd was inside the removed directory: cd ${repoAbs}`);
6269
+ }
6251
6270
 
6252
6271
  // "freed" must mean freed. Reporting a port as free while something still answers on it is what
6253
6272
  // turned a leaked process into a clean bill of health, and it poisons the registry in both
@@ -10893,6 +10912,14 @@ Sequence (each step gated; any failure aborts before the push — the target is
10893
10912
  record; then ask the same of ITS parent. Anything else stays open; an
10894
10913
  unlabelled or unticked-item parent prints as a finding (#371)
10895
10914
 
10915
+ AN INTERRUPTED TAIL IS FINISHED BY RE-RUNNING THE SAME COMMAND (#668). Once B2 pushed, the worktree
10916
+ record reads \`merged\` and names the merge commit; B3 deletes that record. A re-run that finds it
10917
+ still there, with that commit on the remote target, prints "→ RESUME" and runs f–i2 only — no
10918
+ sync, no squash, no push, so no gate or precondition is re-read — and its 🚢 comment says it was a
10919
+ resume. There is no --finish flag: the re-run is the finish. Teardown never stops the process
10920
+ running it, nor that process's ancestors (the shell, the agent CLI): a caller whose cwd was inside
10921
+ the worktree is left running and named, with the \`cd\` it needs.
10922
+
10896
10923
  CLAIMS ARE CROSS-CHECKED AGAINST GIT before anything closes (#87). The set ship would close comes
10897
10924
  from the claim registry, read AT SHIP TIME — so a claim a co-tenant session wrote onto this branch
10898
10925
  minutes ago is indistinguishable from one this session made. Measured: a branch carrying #71 and
@@ -11375,16 +11402,92 @@ function shipRecordRemedy(sess) {
11375
11402
  * here would skip every bookkeeping step after it (#389). The precondition above is what should
11376
11403
  * stop a bad record; this is the belt to that brace.
11377
11404
  */
11378
- function markShipMerged(sess) {
11405
+ function markShipMerged(sess, merged = {}) {
11379
11406
  if (!sess.name) return;
11380
11407
  try {
11381
- state.mutate((st) => { if (st.worktrees[sess.name]) st.worktrees[sess.name].status = 'merged'; });
11408
+ state.mutate((st) => {
11409
+ const rec = st.worktrees[sess.name];
11410
+ if (!rec) return;
11411
+ rec.status = 'merged';
11412
+ // #668: what landed, and where — so a re-run after an interrupted tail can finish it (see
11413
+ // `shipResumeState`) instead of trying to squash the same work a second time.
11414
+ if (merged.sha) { rec.mergedSha = String(merged.sha); rec.mergedTarget = merged.target || null; }
11415
+ });
11382
11416
  } catch (e) {
11383
11417
  warnDeferred(`could not record worktree "${sess.name}" as merged (${String(e.message).split('\n')[0]}) — ` +
11384
11418
  'the merge IS pushed; the rest of the ship continues. Fix the record with `colab doctor`.');
11385
11419
  }
11386
11420
  }
11387
11421
 
11422
+ /**
11423
+ * #668: is this session's merge ALREADY on the target, with its post-merge tail unfinished?
11424
+ *
11425
+ * The record that says so is the worktree's own `status: merged`, which `markShipMerged` writes only
11426
+ * after a gated squash was pushed, and which B3's `worktree rm` deletes. So "record present and
11427
+ * merged" means the tail stopped somewhere at or before teardown — and because B4's 🚢 comments run
11428
+ * AFTER B3, it also means they were not posted yet (the one exception, a `--keep-worktree` ship that
11429
+ * finished, is stamped `shipTailAt` and skips them). Measured: a ship whose teardown killed its own
11430
+ * caller left exactly this state, and re-running ship then failed at B1 with nothing to commit.
11431
+ *
11432
+ * The merge commit is the recorded `mergedSha`; a record written before #668 carries none, so it is
11433
+ * found as the newest commit on `<remote>/<target>` naming one of the session's issues in a
11434
+ * Closes/Refs clause — only when `landed` agrees the branch's content is in the target. Returns
11435
+ * null whenever any of that cannot be shown: the caller then ships exactly as before.
11436
+ */
11437
+ function shipResumeState(repoAbs, st, sess, target) {
11438
+ const rec = sess.name ? st.worktrees[sess.name] : null;
11439
+ if (!rec || rec.status !== 'merged') return null;
11440
+ if (rec.mergedTarget && rec.mergedTarget !== target) return null;
11441
+ const remote = git.remoteFor(repoAbs);
11442
+ git.git(['fetch', '-q', remote, target], repoAbs); // best-effort: a stale ref only makes this answer null
11443
+ const onTarget = `refs/remotes/${remote}/${target}`;
11444
+ let sha = null;
11445
+ let how = '';
11446
+ if (rec.mergedSha) {
11447
+ const full = git.git(['rev-parse', '--verify', '--quiet', `${rec.mergedSha}^{commit}`], repoAbs);
11448
+ if (full.ok && git.git(['merge-base', '--is-ancestor', full.stdout.trim(), onTarget], repoAbs).ok) {
11449
+ sha = full.stdout.trim(); how = 'the merge recorded on the worktree';
11450
+ }
11451
+ } else if (sess.issues.length && landed.landedState(repoAbs, target, sess.branch).state === 'landed') {
11452
+ const greps = sess.issues.map((n) => `--grep=([Cc]loses|[Rr]efs) #${n}([^0-9]|$)`);
11453
+ const found = git.git(['log', '-1', '--format=%H', '-E', ...greps, onTarget], repoAbs);
11454
+ if (found.ok && found.stdout.trim()) { sha = found.stdout.trim(); how = 'the newest commit on the target naming its issues'; }
11455
+ }
11456
+ if (!sha) return null;
11457
+ const body = git.git(['log', '-1', '--format=%B', sha], repoAbs).stdout || '';
11458
+ const named = { closes: new Set(), refs: new Set() };
11459
+ for (const m of body.matchAll(/([Cc]loses|[Rr]efs) #(\d+)/g)) named[/^[Cc]/.test(m[1]) ? 'closes' : 'refs'].add(Number(m[2]));
11460
+ const closeIssues = sess.issues.filter((n) => named.closes.has(Number(n)));
11461
+ const refsIssues = sess.issues.filter((n) => !named.closes.has(Number(n)));
11462
+ const short = git.git(['rev-parse', '--short', sha], repoAbs).stdout.trim() || sha.slice(0, 7);
11463
+ return { sha: short, how, closeIssues, refsIssues, evidencePosted: !!rec.shipTailAt && rec.shipTailAt === sha };
11464
+ }
11465
+
11466
+ /** #668: finish an interrupted post-merge tail — the same `shipLandedTail` a fresh ship runs, no merge. */
11467
+ function shipResumeTail({ repoAbs, sess, target, trunk, integration, opts, resume }) {
11468
+ print(`→ RESUME: ${sess.branch} is already merged into ${target} @ ${resume.sha} (${resume.how}) — its post-merge`);
11469
+ print(' tail did not finish. Finishing it now: no sync, no squash, no push (#668).');
11470
+ if (opts.dry) {
11471
+ print(` --dry: would run B3 teardown${opts.keepWorktree ? ' (kept: --keep-worktree)' : ''}, release, ` +
11472
+ `${resume.evidencePosted ? 'no B4 comments (already posted)' : 'B4 verify + 🚢 comments'}, plan journal, labels, containers.`);
11473
+ return 0;
11474
+ }
11475
+ const gh = isGhUsable(repoAbs);
11476
+ deferredCollector = [];
11477
+ shipLandedTail({ repoAbs, sess, target, trunk, gh, sha: resume.sha,
11478
+ closeIssues: resume.closeIssues, refsIssues: resume.refsIssues, refsSet: new Set(resume.refsIssues),
11479
+ integration, opts, skipEvidence: resume.evidencePosted,
11480
+ evidenceExtra: ' — finished by a re-run of `colab ship` after the first run\'s post-merge tail was interrupted (#668)' });
11481
+ print('');
11482
+ print(`✓ Finished ${sess.branch} → ${target} @ ${resume.sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
11483
+ if (deferredCollector && deferredCollector.length) {
11484
+ print(` ${deferredCollector.length} post-merge write(s) need attention:`);
11485
+ for (const msg of deferredCollector) print(` ! ${msg}`);
11486
+ }
11487
+ deferredCollector = null;
11488
+ return 0;
11489
+ }
11490
+
11388
11491
  function resolveShipSession(st, repoAbs, opts) {
11389
11492
  let name = null, branch = null, wtPath = null;
11390
11493
  let session = '', sessionName = '';
@@ -13943,6 +14046,13 @@ function cmdShip(argv) {
13943
14046
  '`integration:` or finish this merge by hand — ship will not retarget it at trunk for you.');
13944
14047
  }
13945
14048
 
14049
+ // ---- #668: a merge that already landed only needs its tail finished — never a second squash ----
14050
+ // Before the gate and the preconditions on purpose: those authorised the merge that is already on
14051
+ // the target, and a half-removed worktree would fail the dirty check for a reason that is the
14052
+ // interruption itself. Nothing below this branch merges or pushes.
14053
+ const resume = shipResumeState(repoAbs, st, sess, target);
14054
+ if (resume) return shipResumeTail({ repoAbs, sess, target, trunk, integration, opts, resume });
14055
+
13946
14056
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
13947
14057
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
13948
14058
  const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
@@ -14850,7 +14960,7 @@ function cmdShip(argv) {
14850
14960
  // here rather than right after B1 (#322): between the two, the push can still fail and be rolled
14851
14961
  // back, and a `status: merged` record written before that point outlives a merge that never
14852
14962
  // happened — inviting a later sweep to tear down a branch whose work is still only on the branch.
14853
- markShipMerged(sess);
14963
+ markShipMerged(sess, { sha: mergeSha, target });
14854
14964
 
14855
14965
  // ---- (e2) POST-SHIP: the target checkout's installed tree may now be stale (#304) ----
14856
14966
  // The merge has landed and is pushed. Nothing below may fail the ship: there is nothing left to
@@ -14993,7 +15103,7 @@ function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
14993
15103
  * addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
14994
15104
  * batch member.
14995
15105
  */
14996
- function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
15106
+ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [], skipEvidence = false }) {
14997
15107
  // #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
14998
15108
  // B3 below may delete it, and "did the PR's head land?" is answered against that tip.
14999
15109
  if (gh && sess.branch) {
@@ -15026,7 +15136,7 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
15026
15136
  // ---- (g/h) B4 verify + post summary per issue ----
15027
15137
  const groupLabelsCarried = new Set(); // union across every issue this branch carried — for (i) below
15028
15138
  const closedByShip = []; // the issues this ship actually closed — for (i2) below (#371)
15029
- if (gh) {
15139
+ if (gh && !skipEvidence) {
15030
15140
  for (const num of sess.issues) {
15031
15141
  // #647: closed before the hand-off — history the branch name carries, not work this ship did.
15032
15142
  if (sess.handoffRefs && sess.handoffRefs.has(num)) continue;
@@ -15053,6 +15163,14 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
15053
15163
  }
15054
15164
  }
15055
15165
 
15166
+ // #668: a KEPT worktree's record outlives B4, still reading `status: merged` — stamp what was posted,
15167
+ // so a later re-run that resumes this tail (teardown) does not post the 🚢 comments a second time.
15168
+ if (worktreeKept && gh && !skipEvidence && sha) {
15169
+ const full = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`], repoAbs);
15170
+ try { state.mutate((st) => { const r = st.worktrees[sess.name]; if (r) r.shipTailAt = full.ok ? full.stdout.trim() : String(sha); }); }
15171
+ catch (e) { warnDeferred(`could not stamp worktree "${sess.name}" as fully shipped (${String(e.message).split('\n')[0]}) — a later re-run may post its 🚢 comment again`); }
15172
+ }
15173
+
15056
15174
  // ---- (h2) B4: plan-journal + delete the plan file(s) (#94, #115, #193, #201) ----
15057
15175
  // Shared with the evidence-close exit — see `shipJournalPlanFiles`'s own doc comment (above
15058
15176
  // `shipEvidenceClose`) for the #193 hoist and the #201 number-set-membership resolution.
@@ -15951,7 +16069,7 @@ function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opt
15951
16069
  * — its 🚢 comment gains only the combined-run clause.
15952
16070
  */
15953
16071
  function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refsIssues, suffix, opts, gh }) {
15954
- markShipMerged(sess);
16072
+ markShipMerged(sess, { sha, target: trunk });
15955
16073
  pushEvent('ship', {
15956
16074
  repo: repoAbs, worktree: sess.name, session: sess.session,
15957
16075
  issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
@@ -79,20 +79,58 @@ function commandOf(pid) {
79
79
  return cmd.length > 70 ? cmd.slice(0, 69) + '…' : cmd;
80
80
  }
81
81
 
82
+ /** `ps -o ppid=` for one pid, or null when ps cannot say. The default `ppidOf` of `ancestorPids`. */
83
+ function ppidOfPs(pid) {
84
+ const r = run('ps', ['-o', 'ppid=', '-p', String(pid)]);
85
+ if (!r.ok || !r.stdout) return null;
86
+ const ppid = parseInt(r.stdout.trim(), 10);
87
+ return ppid && !Number.isNaN(ppid) ? ppid : null;
88
+ }
89
+
90
+ /**
91
+ * Every ancestor of `of` (default: this process), as a Set of pid STRINGS — the shell that ran this
92
+ * command, the agent CLI that ran the shell, and so on up to (not including) init. #668: these are
93
+ * the processes a teardown must never stop. Bounded by `hops` (a `ppid` cycle from bad `ps` output
94
+ * cannot spin) and never throws: `ps` missing or a pid gone mid-walk ends the walk with what it has.
95
+ * `ppidOf` is injectable so the walk is testable without a real process tree.
96
+ */
97
+ function ancestorPids(of = process.pid, hops = 64, ppidOf = ppidOfPs) {
98
+ const out = new Set();
99
+ let pid = Number(of);
100
+ for (let i = 0; i < hops; i++) {
101
+ if (!pid || Number.isNaN(pid) || pid <= 1) break;
102
+ let ppid = null;
103
+ try { ppid = ppidOf(pid); } catch (_) { ppid = null; }
104
+ ppid = Number(ppid);
105
+ if (!ppid || Number.isNaN(ppid) || ppid <= 1 || out.has(String(ppid))) break;
106
+ out.add(String(ppid));
107
+ pid = ppid;
108
+ }
109
+ return out;
110
+ }
111
+
82
112
  /**
83
113
  * Processes whose cwd is inside `dir`, enriched with command and listening ports.
84
114
  * Returns [] on any platform or environment where lsof cannot answer — never throws.
115
+ *
116
+ * #668: this process and every ancestor of it are tagged `caller: true` rather than left out. They
117
+ * are not processes the directory OWNS — they are whoever is running this command, and a shell
118
+ * whose cwd happens to be inside the worktree it is tearing down matched the cwd test and got
119
+ * SIGTERMed mid-teardown (taking the rest of `colab ship` down with its pipe). Tagged, not dropped,
120
+ * so the caller can still say "your shell is in here — cd out".
85
121
  */
86
- function processesInDir(dir) {
122
+ function processesInDir(dir, { callers } = {}) {
87
123
  if (!dir || process.platform === 'win32') return [];
88
124
  const r = run('lsof', ['-a', '-d', 'cwd', '-F', 'pn']);
89
125
  // lsof exits non-zero when *some* descriptors are unreadable, which is normal for an
90
126
  // unprivileged sweep — so trust the output whenever there is any, not the exit code.
91
127
  if (!r.stdout) return [];
92
- const self = String(process.pid);
93
- return parseLsofCwd(r.stdout, dir)
94
- .filter((p) => p.pid !== self)
95
- .map((p) => ({ ...p, ports: listeningPorts(p.pid), command: commandOf(p.pid) }));
128
+ const found = parseLsofCwd(r.stdout, dir);
129
+ if (!found.length) return [];
130
+ const mine = callers || new Set([String(process.pid), ...ancestorPids()]);
131
+ return found.map((p) => (mine.has(p.pid)
132
+ ? { ...p, caller: true, ports: [], command: commandOf(p.pid) }
133
+ : { ...p, ports: listeningPorts(p.pid), command: commandOf(p.pid) }));
96
134
  }
97
135
 
98
136
  /**
@@ -182,4 +220,4 @@ function isAncestor(candidate, of = process.pid, hops = 10) {
182
220
  return false;
183
221
  }
184
222
 
185
- module.exports = { isInside, parseLsofCwd, listeningPorts, commandOf, cwdOf, processesInDir, listeners, portIsBound, alive, terminate, isAncestor };
223
+ module.exports = { isInside, parseLsofCwd, listeningPorts, commandOf, cwdOf, processesInDir, ancestorPids, listeners, portIsBound, alive, terminate, isAncestor };