@futurelastic/colab-handbook 1.13.0-rc.2 → 1.13.0-rc.21

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/tools/colab CHANGED
@@ -77,6 +77,7 @@ const shipRoles = require('./lib/ship-roles'); // #372
77
77
  const refsBrake = require('./lib/refs-brake'); // #385
78
78
  const localAdopt = require('./lib/local-adopt'); // #393
79
79
  const ownerBranch = require('./lib/owner-branch'); // #394
80
+ const humanDoor = require('./lib/ship-human-door'); // #525
80
81
  const {
81
82
  HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
82
83
  parseArgs, table, shortRepo,
@@ -282,12 +283,40 @@ function commentHost(repoAbs) {
282
283
  function myMachineId() { return machine.localMachine().id || null; }
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
+ * Resolve the session id for this invocation: --session flag > COLAB_SESSION env >
287
+ * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — any stable id for
288
+ * the session (a URL, a uuid…).
289
+ *
290
+ * The derived step exists for a person at a plain terminal, who has no session runtime and so no
291
+ * id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
292
+ * warned three lines every time, and ship evidence read `implemented by: unknown`. It applies only
293
+ * when `COLAB_SESSION` is unset and the shell is not an agent's (`claimIdentity.
294
+ * shouldDerivePersonSession` has why) — an explicit flag or env value always wins.
287
295
  */
288
296
  function resolveSession(opts) {
289
- const s = opts.session || process.env.COLAB_SESSION || '';
290
- return String(s).trim();
297
+ const s = String(opts.session || process.env.COLAB_SESSION || '').trim();
298
+ return s || derivedPersonSession();
299
+ }
300
+
301
+ /**
302
+ * The derived person identity for this invocation, or ''. Memoized — one `git config` spawn, and
303
+ * the "derived" note is printed once per invocation (stderr, so `--json` stdout stays clean).
304
+ */
305
+ let derivedSessionCache = null;
306
+ function derivedPersonSession() {
307
+ if (derivedSessionCache !== null) return derivedSessionCache;
308
+ derivedSessionCache = '';
309
+ if (!claimIdentity.shouldDerivePersonSession(process.env)) return derivedSessionCache;
310
+ const r = spawnSync('git', ['config', '--get', 'user.email'], { encoding: 'utf8' });
311
+ const email = r.status === 0 ? String(r.stdout || '').trim() : '';
312
+ let user = process.env.USER || '';
313
+ if (!user) { try { user = os.userInfo().username; } catch { user = ''; } }
314
+ derivedSessionCache = claimIdentity.derivePersonSession({ email, user, hostToken: machine.hostToken(HOST) });
315
+ if (derivedSessionCache) {
316
+ process.stderr.write(`· session: ${derivedSessionCache} (derived — no --session or COLAB_SESSION given; ` +
317
+ `either one overrides it)\n`);
318
+ }
319
+ return derivedSessionCache;
291
320
  }
292
321
 
293
322
  /**
@@ -362,7 +391,7 @@ function warnWeakIdentity(session, sessionName, what, ref) {
362
391
  warn(`no --session or --session-name given — this ${what} will carry NO holder identity.`);
363
392
  warn(` A live hold's refusal can then only point at its process id, and this acquire will`);
364
393
  warn(` not be recognized as your own on a later re-acquire without one.`);
365
- if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <url>`);
394
+ if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <id>`);
366
395
  return;
367
396
  }
368
397
  // #326: a planner intent id is a deliberate, documented non-URL value — not a mistyped name.
@@ -373,16 +402,16 @@ function warnWeakIdentity(session, sessionName, what, ref) {
373
402
  // refused the caller's own hold when they later presented their REAL url. Warn, never
374
403
  // refuse: `requirePlaceIdentity` promises `<url-or-any-stable-id>`, so a bare stable id is
375
404
  // a blessed value and rejecting it would break that contract and every adopter using one.
376
- warn(`--session "${session}" does not look like a session URL or a session_… id — this ${what}`);
405
+ warn(`--session "${session}" does not look like a session id (a URL, a uuid, a session_… token) — this ${what}`);
377
406
  warn(` will record it verbatim. That is allowed (any stable id works), but if this is your`);
378
407
  warn(` session NAME you probably meant --session-name: a later 'colab place release'`);
379
- warn(` presenting your real URL will NOT match this value and will be refused (#306).`);
408
+ warn(` presenting your real id will NOT match this value and will be refused (#306).`);
380
409
  return;
381
410
  }
382
411
  if (!sessionName || session) return;
383
- warn(`session name "${sessionName}" recorded with NO session URL — this ${what} will read as owned`);
384
- warn(` but cannot be traced to a session. The name is display text; the URL is the join key.`);
385
- if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <url>`);
412
+ warn(`session name "${sessionName}" recorded with NO session id — this ${what} will read as owned`);
413
+ warn(` but cannot be traced to a session. The name is display text; the id is the join key.`);
414
+ if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <id>`);
386
415
  }
387
416
 
388
417
  /**
@@ -441,8 +470,8 @@ function identityCell(sessionName, session) {
441
470
  /** Print the `(!)` legend under a table, only when at least one row carries a half-identity. */
442
471
  function identityLegend(entries) {
443
472
  if (!entries.some((e) => e && e.sessionName && !e.session)) return;
444
- print(' (!) session NAME with no session URL — reads as owned, links to nothing.');
445
- print(' Repair: colab worktree tag <worktree> --session <url>');
473
+ print(' (!) session NAME with no session id — reads as owned, links to nothing.');
474
+ print(' Repair: colab worktree tag <worktree> --session <id>');
446
475
  }
447
476
 
448
477
  /**
@@ -890,7 +919,8 @@ Options:
890
919
  --branch <name> branch these claims are worked on. Default: none (null) — a claim held on
891
920
  the trunk checkout has no branch. Never the word "trunk": that is a role,
892
921
  and a record holding it resolves to no ref (refused, exit 1)
893
- --session <url> Claude session URL recorded on the claim + comment (default: COLAB_SESSION env).
922
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the claim + comment
923
+ (default: COLAB_SESSION env).
894
924
  MANDATORY when no --worktree is given (#242): a claim with no worktree takes
895
925
  the trunk-checkout place-claim, and a blank session can never be recognized
896
926
  as its own later re-acquire — refused (exit 1) before anything is read/written.
@@ -1871,7 +1901,9 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1871
1901
  already-final exit 0 (nothing to do yet is the ordinary output)
1872
1902
  --tag <rc> pin the candidate a human reviewed; refused unless it is the newest one
1873
1903
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
1874
- No field, flag or project.yml value lowers it, and it never shortens a test period
1904
+ No field, flag or project.yml value lowers it, and it never shortens a test period.
1905
+ Where the final is a human act the period is informational anyway, and
1906
+ release.test-period: 0d declares none at all (#549)
1875
1907
  --dry measure and report; open, post, tag and close nothing
1876
1908
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
1877
1909
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
@@ -2102,7 +2134,9 @@ function cmdReleaseFinalize(argv) {
2102
2134
  const tNew = version0 ? trackings.get(version0) : null;
2103
2135
  if (newest && tNew && tNew.number) {
2104
2136
  const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2105
- comment(tNew.number, { candidate: newest.tag }, walk
2137
+ comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
2138
+ ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — no test period on this repo (\`release.test-period: 0d\`, #549): the human's finalize is the test.`
2139
+ : walk
2106
2140
  ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its own test period runs ${pNew.start} → ${pNew.endsAt}. A newer candidate does not restart an older one's clock: the newest candidate clean for its own period is finalized (\`--auto\`).`
2107
2141
  : `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
2108
2142
  }
@@ -2770,7 +2804,7 @@ function cmdGateHermetic(argv) {
2770
2804
  // neither, so there is nothing else in state.json a second solo attempt could collide with.
2771
2805
  // ---------------------------------------------------------------------------
2772
2806
 
2773
- const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <url>] [--session-name <name>]
2807
+ const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <id>] [--session-name <name>]
2774
2808
  colab solo --done [--repo <path>]
2775
2809
 
2776
2810
  Entry gate for solo flow (CONVENTIONS.md, Solo flow) — requires BOTH: this repo does not declare
@@ -3045,7 +3079,7 @@ function cmdSoloDone(repoAbs, doc) {
3045
3079
  // exactly `writes: isolated` — see writes-authority.js's `trunkDirectVetoed`)
3046
3080
  // ---------------------------------------------------------------------------
3047
3081
 
3048
- const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session URL] [--session-name N] [--force]
3082
+ const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session ID] [--session-name N] [--force]
3049
3083
 
3050
3084
  Path-scoped, machine-local hold on ONE checkout (CONVENTIONS.md, Place-claims) — what a shared
3051
3085
  trunk checkout needs on any repo that does not declare \`writes: isolated\` (the veto), and a
@@ -5207,7 +5241,8 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5207
5241
  <type>/, prefix or not; else the branch after its first '/')
5208
5242
  --trunk <name> override trunk branch
5209
5243
  --repo <path> repo root (default: git root of cwd)
5210
- --session <url> Claude session URL recorded on the worktree + its claims (env COLAB_SESSION)
5244
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the worktree +
5245
+ its claims (env COLAB_SESSION)
5211
5246
  --session-name <s> short human label for tables/messages (env COLAB_SESSION_NAME)
5212
5247
  --pid <n|none> the new worktree's place-claim liveness anchor (#288) — same meaning as
5213
5248
  \`colab claim\`'s --pid; default: auto-detect (env COLAB_PLACE_PID too)
@@ -5234,7 +5269,7 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5234
5269
  and state record in place for a retry, unless --force. Refuses if there are
5235
5270
  uncommitted TRACKED changes unless --force.
5236
5271
 
5237
- colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]
5272
+ colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]
5238
5273
  REPAIR session identity, and/or the recorded branch, on a worktree that already
5239
5274
  exists — and on every claim attached to it (claims hold their own copy of each
5240
5275
  field, and claims are what \`doctor\` reports and what \`ship\` unions by). Pass any
@@ -5677,7 +5712,8 @@ function cmdWorktreeNew(argv) {
5677
5712
 
5678
5713
  // #488: the scratch dirs (plans, briefs) are hidden in the clone's shared info/exclude — one
5679
5714
  // write covers the main checkout and every worktree, with no per-repo .gitignore diff.
5680
- ensureScratchExcluded(repoAbs);
5715
+ // #527: and the worktree subdir itself, or trunk's `git add -A` stages this worktree as a gitlink.
5716
+ ensureScratchExcluded(repoAbs, config);
5681
5717
 
5682
5718
  // 5. optional repo hook (machine-specific steps plug in here)
5683
5719
  const hook = runHook(repoAbs, 'post-create', { wtPath, name, branch, ports: alloc.chosenPorts, trunk, base, issues });
@@ -5857,7 +5893,7 @@ function cmdWorktreeRm(argv) {
5857
5893
  }
5858
5894
 
5859
5895
  /**
5860
- * `colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]` — repair
5896
+ * `colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]` — repair
5861
5897
  * session identity, and/or the recorded branch, on an ALREADY-created worktree. Before this, the
5862
5898
  * only fix was hand-editing ~/.colab/state.json.
5863
5899
  *
@@ -5891,7 +5927,7 @@ function cmdWorktreeTag(argv) {
5891
5927
  const sessionName = String(opts.sessionName || '').trim();
5892
5928
  const branch = String(opts.branch || '').trim();
5893
5929
  if (!session && !sessionName && !branch) {
5894
- throw new UserError('Nothing to tag — pass --session <url>, --session-name <s>, and/or --branch <b>');
5930
+ throw new UserError('Nothing to tag — pass --session <id>, --session-name <s>, and/or --branch <b>');
5895
5931
  }
5896
5932
  if (!state.loadState().worktrees[name]) {
5897
5933
  throw new UserError(`No worktree "${name}" in state (list them with: colab worktrees)`);
@@ -7569,7 +7605,7 @@ function cmdLabels(argv) {
7569
7605
  // config (show / manage the aggregation inputs)
7570
7606
  // ---------------------------------------------------------------------------
7571
7607
 
7572
- const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|set <key> <value>]
7608
+ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|add-notify-url <url>|rm-notify-url <url>|set <key> <value>]
7573
7609
 
7574
7610
  show print resolved config, file paths, and the aggregated reserved set
7575
7611
  add-repo <path> add a repo root to scan for .github/project.yml reserved ports
@@ -7577,6 +7613,9 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
7577
7613
  add-reserved-file <path> add a machine-local reserved-ports file (~ is expanded); its ports join
7578
7614
  the reserved set (lenient parse: whitespace ints per line, # comments)
7579
7615
  rm-reserved-file <path> remove a reserved-ports file
7616
+ add-notify-url <url> add one more event receiver to notifyUrl (a second local observer) —
7617
+ existing entries are kept; one URL stays stored as a plain string
7618
+ rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
7580
7619
  set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
7581
7620
  claimIdentity
7582
7621
 
@@ -7585,6 +7624,9 @@ an http(s) endpoint and claim / release / ship / worktree new / worktree rm each
7585
7624
  best-effort JSON event as they succeed — fire-and-forget, never retried, never able to fail or slow
7586
7625
  the command that triggered it. Observers already poll this state file; the push only sharpens the
7587
7626
  timestamp. Unset it again with: colab config set notifyUrl ""
7627
+ notifyUrl may hold SEVERAL receivers (#546) — every event goes to each, through its own detached
7628
+ child, so one dead receiver never costs another its event. \`set notifyUrl <url>\` replaces the
7629
+ whole value with one URL; add-notify-url / rm-notify-url change one entry and leave the rest alone.
7588
7630
 
7589
7631
  journal is OPTIONAL and off by default: unset, colab writes no journal file at all. Set it and every
7590
7632
  state transition and every invocation is appended to ~/.colab/journal.jsonl — one JSON object per
@@ -7641,6 +7683,25 @@ function cmdConfig(argv) {
7641
7683
  cfg.reservedFiles = (cfg.reservedFiles || []).filter((f) => f !== argv[1]);
7642
7684
  state.saveConfig(cfg); print(`reservedFiles: ${cfg.reservedFiles.join(', ') || '(none)'}`); return 0;
7643
7685
  }
7686
+ if (sub === 'add-notify-url' || sub === 'rm-notify-url') {
7687
+ // #546: notifyUrl is a string or a list. These change ONE entry and leave every other exactly as
7688
+ // it was, so a second observer is added without hand-editing JSON and without rewriting the first.
7689
+ const u = (argv[1] || '').trim();
7690
+ if (!u) throw new UserError(`${sub} needs a URL — try: colab config ${sub} http://127.0.0.1:<port>/api/events`);
7691
+ const urls = notify.configuredUrls(cfg);
7692
+ if (sub === 'add-notify-url') {
7693
+ if (!/^https?:\/\//i.test(u)) throw new UserError(`notifyUrl must be an http(s) URL — try: colab config add-notify-url http://${u.replace(/^[a-z]+:\/\//i, '')}`);
7694
+ if (!urls.includes(u)) urls.push(u);
7695
+ } else {
7696
+ if (!urls.includes(u)) throw new UserError(`notifyUrl has no entry ${u} — see the entries with: colab config show`);
7697
+ urls.splice(urls.indexOf(u), 1);
7698
+ }
7699
+ const v = notify.storedNotifyUrl(urls);
7700
+ if (v === undefined) delete cfg.notifyUrl; else cfg.notifyUrl = v;
7701
+ state.saveConfig(cfg);
7702
+ print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
7703
+ return 0;
7704
+ }
7644
7705
  if (sub === 'set') {
7645
7706
  const [k, v] = [argv[1], argv[2]];
7646
7707
  if (!k || v === undefined) throw new UserError('set needs <key> <value>');
@@ -8023,13 +8084,17 @@ function gitExcludePath(repoAbs) {
8023
8084
  /**
8024
8085
  * #488: append the scratch-dir exclude lines (scratch-dirs.js `excludeLines`) to the clone's shared
8025
8086
  * info/exclude, idempotently. Best-effort: a failure warns and never blocks the caller.
8087
+ * #527: `config` given → the worktree subdir's line too (`worktreeExcludeLine`), so whatever creates
8088
+ * the default worktree dir also hides it — an adopted repo's `.gitignore` has never heard of it.
8026
8089
  */
8027
- function ensureScratchExcluded(repoAbs) {
8090
+ function ensureScratchExcluded(repoAbs, config = null) {
8028
8091
  const excludeFile = gitExcludePath(repoAbs);
8029
8092
  if (!excludeFile) return [];
8030
8093
  let before = null;
8031
8094
  try { before = fs.readFileSync(excludeFile, 'utf8'); } catch (_) { /* absent */ }
8032
8095
  const lines = scratchDirs.excludeLines();
8096
+ const wtLine = config ? scratchDirs.worktreeExcludeLine(worktreeSubdir(config)) : null;
8097
+ if (wtLine && !lines.includes(wtLine)) lines.push(wtLine);
8033
8098
  const missing = localAdopt.missingExcludeLines(before, lines);
8034
8099
  if (!missing.length) return [];
8035
8100
  try {
@@ -8348,7 +8413,9 @@ async function askMenu(rl, axis, promptFn) {
8348
8413
  if (resolved.ok) return resolved;
8349
8414
  process.stdout.write(` ${resolved.message}\n`);
8350
8415
  }
8351
- throw new UserError(`${axis}: no valid answer after one re-prompt`);
8416
+ throw new UserError(`${axis}: no valid answer after one re-prompt — nothing was written. Run \`colab adopt --axis ${axis}\` ` +
8417
+ `to be asked again, or pass the value directly: \`colab adopt ${axis === 'tier' ? '--deploy' : `--${axis}`} <value>\` ` +
8418
+ `(\`colab adopt --help\` lists them).`);
8352
8419
  }
8353
8420
 
8354
8421
  /**
@@ -8408,7 +8475,10 @@ async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
8408
8475
  if (!problem) { chosen = resolved; break; }
8409
8476
  process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
8410
8477
  }
8411
- if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
8478
+ // #532: this refusal comes after a long interaction, so it names the way through, not just the stop.
8479
+ if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt — nothing was written. ' +
8480
+ 'Each "✗" above says why its value was refused. Run `colab adopt --axis exposure` and pick a value it accepts, ' +
8481
+ 'or `colab adopt --exposure <value>` non-interactively; choosing "skip" leaves exposure unanswered for now.');
8412
8482
  if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
8413
8483
  answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
8414
8484
  } else {
@@ -8498,6 +8568,12 @@ async function cmdAdopt(argv) {
8498
8568
  local = adoptLocalPrepare(repoAbs, opts);
8499
8569
  if (local.exit !== undefined) return local.exit;
8500
8570
  }
8571
+ // #527: a repo adopted before `worktree new` hid its own dir gets the same exclude lines here —
8572
+ // machine-local (info/exclude), idempotent, never a committed diff. --local already wrote them.
8573
+ if (!opts.local) {
8574
+ const hidden = ensureScratchExcluded(repoAbs, state.loadConfig());
8575
+ if (hidden.length && !opts.json) print(`✓ hid ${hidden.join(' ')} in .git/info/exclude (machine-local)`);
8576
+ }
8501
8577
  const io = adoptIo(repoAbs);
8502
8578
  const extra = adoptGitExtras(repoAbs, opts);
8503
8579
  if (local) { extra.trunk = local.trunk; extra.trunkSource = 'local-integration'; }
@@ -9986,14 +10062,18 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
9986
10062
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
9987
10063
  }
9988
10064
 
9989
- const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--session <id>] [--session-name <s>] [--dry] [--json]
10065
+ const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
9990
10066
  colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
9991
10067
 
9992
10068
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
9993
10069
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
9994
10070
  (project.yml \`integration:\`). Autonomy is granted by the repo's .github/project.yml
9995
10071
  (\`autonomy: auto-trunk\`) — NOT by any flag. Without that grant, ship refuses and a human must run
9996
- Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
10072
+ Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). That human runs ship
10073
+ too, through the HUMAN DOOR (#525): at an interactive terminal (outside an agent shell) ship asks
10074
+ them to confirm; non-interactively, COLAB_HUMAN=1 plus --answered-by <name>. Every other
10075
+ precondition still applies, and the 🚢 comment records that the human door opened the gate.
10076
+ ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
9997
10077
 
9998
10078
  Base and target are ONE decision. A branch cut from a long-lived line and shipped into trunk would
9999
10079
  drag the entire line in behind it, as a single squash commit that reads like a small change — so
@@ -10003,6 +10083,8 @@ promotes is an integration event of the same weight as a promotion, and stays hu
10003
10083
 
10004
10084
  Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
10005
10085
  a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
10086
+ — or a person runs ship through the human door (#525): a confirmed interactive
10087
+ terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
10006
10088
  b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
10007
10089
  human step needed — OR every issue the branch carries holds a valid
10008
10090
  \`colab ci-grant\` over trunk's CURRENT red sha, #105 — see below) · no new
@@ -11049,7 +11131,7 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
11049
11131
  return {
11050
11132
  name: raw.name, ok: true, class: null,
11051
11133
  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})`,
11052
- grantVerdict: null, cureVerdict,
11134
+ grantVerdict: null, cureVerdict, redSha,
11053
11135
  };
11054
11136
  }
11055
11137
 
@@ -11064,10 +11146,45 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
11064
11146
  return {
11065
11147
  name: raw.name, ok: true, class: null,
11066
11148
  detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
11067
- grantVerdict, cureVerdict,
11149
+ grantVerdict, cureVerdict, redSha,
11068
11150
  };
11069
11151
  }
11070
- return { ...raw, grantVerdict, cureVerdict };
11152
+ // #534: both doors were consulted and both refused — say WHY on the row itself, so the prose table,
11153
+ // `--dry`, and B1's abort line all tell "needs a grant" from "missing evidence" from "stacked". The
11154
+ // JSON payload already carried `ciCure.reason`; the prose detail used to end at the raw trunk read.
11155
+ return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict)}`, grantVerdict, cureVerdict, redSha };
11156
+ }
11157
+
11158
+ /**
11159
+ * Which red-trunk door let a trunk-CI row pass — `'cure rule'`, `'ci-grant'`, or null for a row that
11160
+ * passed on its own (green) or did not pass (#538: B1 re-measures only a door the table relied on).
11161
+ */
11162
+ function doorThatAdmitted(ciResult) {
11163
+ if (!ciResult || !ciResult.ok) return null;
11164
+ if (ciResult.cureVerdict && ciResult.cureVerdict.ok) return 'cure rule';
11165
+ if (ciResult.grantVerdict && ciResult.grantVerdict.ok) return 'ci-grant';
11166
+ return null;
11167
+ }
11168
+
11169
+ /** #538: the pause before B1's one re-measure — long enough for a transient `gh` failure to clear. */
11170
+ const B1_REMEASURE_MS = Number.isFinite(Number(process.env.COLAB_B1_REMEASURE_MS))
11171
+ && process.env.COLAB_B1_REMEASURE_MS !== '' ? Number(process.env.COLAB_B1_REMEASURE_MS) : 3000;
11172
+
11173
+ /**
11174
+ * The " — cure rule (#281): …; ci-grant (#105): …" suffix of a refused trunk-CI row (#534). Empty
11175
+ * when neither door was consulted. One clause per door, each its own refusal reason verbatim — the
11176
+ * cure's `reason`, the grant's per-issue `missing[].reason` — never a re-wording, so the prose and
11177
+ * the `--dry --json` fields cannot read differently.
11178
+ */
11179
+ function doorRefusalNote(cureVerdict, grantVerdict) {
11180
+ const parts = [];
11181
+ if (cureVerdict && !cureVerdict.ok && cureVerdict.reason) parts.push(`cure rule (#281): ${cureVerdict.reason}`);
11182
+ if (grantVerdict && !grantVerdict.ok) {
11183
+ const why = (grantVerdict.missing || []).map((m) => (m.issue ? `#${m.issue}: ` : '') + m.reason)
11184
+ .map((s) => s.replace(/^(#\d+): \1/, '$1')).join('; ');
11185
+ if (why) parts.push(`ci-grant (#105): ${why}`);
11186
+ }
11187
+ return parts.length ? ` — ${parts.join(' · ')}` : '';
11071
11188
  }
11072
11189
 
11073
11190
  /**
@@ -11609,7 +11726,8 @@ function cmdShipDryJson(opts) {
11609
11726
  }
11610
11727
 
11611
11728
  // ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
11612
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
11729
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
11730
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
11613
11731
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
11614
11732
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
11615
11733
 
@@ -12008,7 +12126,7 @@ function shipEvidenceClose({ repoAbs, st, sess, target, trunk, gh, closeIssues,
12008
12126
  `The deliverable is recorded on this issue (see the comment(s) above), which is what authorised ` +
12009
12127
  `the close — colab closes a zero-diff issue only when it already carries a comment colab did not ` +
12010
12128
  `write. The zero-diff fact was measured from git: ${mode.why}.${shipSess}`;
12011
- const c = git.ghIssueComment(repoAbs, num, body);
12129
+ const c = git.ghIssueComment(repoAbs, num, body + (opts.humanDoorEvidence || '')); // #525
12012
12130
  if (!c.ok) warn(`could not post the evidence-close comment on #${num} — closing anyway`);
12013
12131
  const r = tracker.forRepo(repoAbs).issueClose(num, { reason: 'completed' });
12014
12132
  if (!r.ok) { skipped.push({ num, why: `gh issue close failed: ${(r.stderr || '').split('\n')[0]}` }); continue; }
@@ -12170,7 +12288,8 @@ function cmdShipDirect(opts) {
12170
12288
  // #345: a trunk-direct unit has no branch diff. Its change set is every trunk commit since its
12171
12289
  // earliest claim — by anyone, so the verdict can only err toward refusing (lib/docs-only.js).
12172
12290
  const since = claims.map((c) => c.created).filter(Boolean).sort()[0];
12173
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since));
12291
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since),
12292
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12174
12293
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
12175
12294
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
12176
12295
 
@@ -12249,6 +12368,7 @@ function cmdShipDirect(opts) {
12249
12368
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12250
12369
  process.stderr.write(' A human must close this unit. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12251
12370
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12371
+ process.stderr.write(shipHumanDoorRefusal(autonomyGate, '--direct'));
12252
12372
  return 1;
12253
12373
  }
12254
12374
  if (!coreOk && coreReview.corePaths.length) {
@@ -12260,6 +12380,7 @@ function cmdShipDirect(opts) {
12260
12380
  process.stderr.write(' unit\'s reviewed landing, a human closes this issue by hand.\n');
12261
12381
  }
12262
12382
  if (autonomyGate.via === 'docs-only') print(`→ AUTONOMY: ${autonomyGate.detail} (#345) — project.yml autonomy: ${autonomyGate.declared}`);
12383
+ if (autonomyGate.via === 'human') print(`→ AUTONOMY: ${autonomyGate.detail}`);
12263
12384
  print(`→ MODE: evidence-close (trunk-direct — the work is already on ${trunk}; nothing to merge)`);
12264
12385
  if (opts.dry) {
12265
12386
  print(preOk ? '→ READY: preconditions pass. Re-run without --dry to close.' : '→ NOT READY: fix the ✗ rows above.');
@@ -12271,6 +12392,7 @@ function cmdShipDirect(opts) {
12271
12392
  return preOk ? 0 : 1;
12272
12393
  }
12273
12394
  if (!preOk) { process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was closed.\n'); return 1; }
12395
+ if (!shipHumanDoorGo(autonomyGate, opts, `close ${issues.map((n) => '#' + n).join(' ')} on ${trunk} (trunk-direct)`)) return 1;
12274
12396
 
12275
12397
  const tip = shortSha(git.git(['rev-parse', trunk], repoAbs).stdout);
12276
12398
  const mode = { evidenceClose: true, direct: true, why: `trunk-direct unit — ${trunk}@${tip} is checked out clean and published to ${git.remoteInfo(repoAbs).name || 'origin'}/${trunk}` };
@@ -12488,20 +12610,81 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
12488
12610
  *
12489
12611
  * Returns `{ ok, via: 'auto-trunk'|'docs-only'|null, declared, docsOnly: verdict|null, detail }`.
12490
12612
  */
12491
- function shipAutonomyGate(doc, readDocsOnly) {
12613
+ function shipAutonomyGate(doc, readDocsOnly, door = null) {
12492
12614
  const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
12493
- if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, detail: 'auto-trunk' };
12615
+ if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
12494
12616
  const verdict = readDocsOnly();
12495
12617
  if (verdict.docsOnly) {
12496
- return { ok: true, via: 'docs-only', declared, docsOnly: verdict, detail: `${verdict.reason} — autonomy exception` };
12618
+ return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
12497
12619
  }
12498
- return { ok: false, via: null, declared, docsOnly: verdict,
12499
- detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason})` };
12620
+ // #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
12621
+ // after docs-only, so a docs-only change keeps its own (agent-usable) door and record.
12622
+ if (door && door.open) {
12623
+ return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
12624
+ detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
12625
+ }
12626
+ return { ok: false, via: null, declared, docsOnly: verdict, human: door,
12627
+ detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; human door closed: ${door ? door.why : 'not offered'})` };
12628
+ }
12629
+
12630
+ /** #525: the human-door refusal lines — what a person runs, never just "a human must". */
12631
+ function shipHumanDoorRefusal(gate, selector) {
12632
+ const lines = [];
12633
+ if (gate.human && gate.human.why) lines.push(` The human door (#525) did not open: ${gate.human.why}.`);
12634
+ lines.push(' A person gives the go by running ship themselves — every other precondition still applies:');
12635
+ for (const l of humanDoor.humanDoorCommands(selector)) lines.push(` ${l}`);
12636
+ lines.push(' An agent does not pass this door on its own (CONVENTIONS.md §2, *The human door*).');
12637
+ return lines.join('\n') + '\n';
12638
+ }
12639
+
12640
+ /** #525: the ship selector to paste into the refusal's command line. */
12641
+ function shipSelector(opts, sess) {
12642
+ if (opts.direct) return '--direct';
12643
+ if (opts.worktree) return `--worktree ${opts.worktree}`;
12644
+ if (sess && sess.name) return `--worktree ${sess.name}`;
12645
+ if (opts.branch) return `--branch ${opts.branch}`;
12646
+ return sess && sess.branch ? `--branch ${sess.branch}` : '';
12647
+ }
12648
+
12649
+ /**
12650
+ * #525: confirm the TTY door by a typed answer. Synchronous on purpose — ship is a sync pipeline,
12651
+ * and the prompt sits before any write. Anything but `y`/`yes` is a no; EOF is a no.
12652
+ */
12653
+ function shipConfirmAtTerminal(question) {
12654
+ process.stdout.write(`${question} [y/N] `);
12655
+ const buf = Buffer.alloc(256);
12656
+ let line = '';
12657
+ for (;;) {
12658
+ let n = 0;
12659
+ try { n = fs.readSync(0, buf, 0, buf.length, null); } catch (e) { if (e.code === 'EAGAIN') continue; return false; }
12660
+ if (n <= 0) break;
12661
+ line += buf.toString('utf8', 0, n);
12662
+ if (line.includes('\n')) break;
12663
+ }
12664
+ return /^\s*y(es)?\s*$/i.test(line.split('\n')[0]);
12665
+ }
12666
+
12667
+ /**
12668
+ * #525: the last step before any write when the human door opened the gate. A TTY door asks the
12669
+ * person to confirm; a COLAB_HUMAN door already carries its go (`--answered-by`). Either way the
12670
+ * evidence clause is stashed on `opts` for the comment writers. Returns false on a declined prompt.
12671
+ */
12672
+ function shipHumanDoorGo(gate, opts, what) {
12673
+ if (gate.via !== 'human') return true;
12674
+ if (gate.human.how === 'tty' && !shipConfirmAtTerminal(`Human door (#525): ${what}. This is your go — proceed?`)) {
12675
+ process.stderr.write('✗ Not confirmed at the terminal. Nothing was changed.\n');
12676
+ return false;
12677
+ }
12678
+ opts.humanDoorEvidence = humanDoor.humanDoorEvidence(gate.human);
12679
+ return true;
12500
12680
  }
12501
12681
 
12502
12682
  /** #345: the additive `autonomyGate` field of the `--dry --json` output. */
12503
12683
  function autonomyGatePayload(gate) {
12504
- return { via: gate.via, docsOnly: gate.docsOnly };
12684
+ // #525: `human` is additive and present only when the human door was consulted, so an
12685
+ // auto-trunk / docs-only payload stays byte-identical to before.
12686
+ return gate.human ? { via: gate.via, docsOnly: gate.docsOnly, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } }
12687
+ : { via: gate.via, docsOnly: gate.docsOnly };
12505
12688
  }
12506
12689
 
12507
12690
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
@@ -12512,7 +12695,7 @@ function shipRefFor(repoAbs, branch) {
12512
12695
 
12513
12696
  function cmdShip(argv) {
12514
12697
  const opts = parseArgs(argv, {
12515
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch' },
12698
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
12516
12699
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
12517
12700
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
12518
12701
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -12587,11 +12770,13 @@ function cmdShip(argv) {
12587
12770
 
12588
12771
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
12589
12772
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
12590
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
12773
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
12774
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12591
12775
  if (!autonomyGate.ok) {
12592
12776
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12593
12777
  process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12594
12778
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12779
+ process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
12595
12780
  return 1;
12596
12781
  }
12597
12782
 
@@ -12984,6 +13169,9 @@ function cmdShip(argv) {
12984
13169
  }
12985
13170
  process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was pushed.\n'); return 1;
12986
13171
  }
13172
+ if (!shipHumanDoorGo(autonomyGate, opts, mode.evidenceClose
13173
+ ? `evidence-close ${sess.issues.map((n) => '#' + n).join(' ')} (${sess.branch} has nothing to merge)`
13174
+ : `squash-merge ${sess.branch} into ${target}`)) return 1;
12987
13175
 
12988
13176
  // ---- (b3) evidence-close: the whole B0–B2 sequence is skipped, because there is nothing to merge ----
12989
13177
  if (mode.evidenceClose) return shipEvidenceClose({
@@ -13108,12 +13296,29 @@ function cmdShip(argv) {
13108
13296
  let ciGrantForTrailer = null; // #105: set below when B1 shipped UNDER a grant — read at commit-message time
13109
13297
  let ciCureForTrailer = null; // #281: set below when B1 shipped UNDER the cure rule — read at commit-message time
13110
13298
  if (gh) {
13111
- const ciResultB1 = shipCiCheck(repoAbs, gh, target, trunk,
13299
+ const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
13112
13300
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
13113
13301
  (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
13302
+ let ciResultB1 = measureB1();
13303
+ // #538: the table admitted this branch through a door (cure or grant) at red sha X, and B1 —
13304
+ // seconds later, at the SAME red sha — refused. Nothing the door judges moved (trunk's head is
13305
+ // X in both reads), so the likeliest cause is one of the ~10 `gh` reads a door makes failing
13306
+ // once, which every door reads as a refusal (fail closed). Measured: `--dry` said READY and the
13307
+ // real ship aborted here with only the raw "conclusion=failure". Re-measure ONCE, in full —
13308
+ // never reuse the table's verdict (B1 exists to catch a change) — and if it refuses again, abort
13309
+ // saying it was the door, with the door's own reason.
13310
+ const tableDoor = doorThatAdmitted(ciResult);
13311
+ if (!ciResultB1.ok && tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha) {
13312
+ 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).`);
13313
+ ciWait.sleepSync(B1_REMEASURE_MS);
13314
+ ciResultB1 = measureB1();
13315
+ }
13114
13316
  if (!ciResultB1.ok) {
13115
13317
  cleanupEphemeral();
13116
- process.stderr.write(`✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
13318
+ const sameRed = tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha;
13319
+ process.stderr.write(sameRed
13320
+ ? `✗ 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`
13321
+ : `✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
13117
13322
  return 1;
13118
13323
  }
13119
13324
  if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
@@ -13483,7 +13688,8 @@ function cmdShip(argv) {
13483
13688
  // last — see warnDeferred's own comment for why this is scoped to exactly this window. The
13484
13689
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
13485
13690
  // same block, and re-assigning the collector here would silently discard them.
13486
- shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts });
13691
+ shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
13692
+ evidenceExtra: opts.humanDoorEvidence || '' }); // #525
13487
13693
 
13488
13694
  print('');
13489
13695
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);