@futurelastic/colab-handbook 1.13.0-rc.6 → 1.13.0-rc.8

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
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.13.0-rc.6"
35
+ "version": "1.13.0-rc.8"
36
36
  }
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,
@@ -10024,14 +10025,18 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10024
10025
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
10025
10026
  }
10026
10027
 
10027
- 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]
10028
+ 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]
10028
10029
  colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10029
10030
 
10030
10031
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10031
10032
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
10032
10033
  (project.yml \`integration:\`). Autonomy is granted by the repo's .github/project.yml
10033
10034
  (\`autonomy: auto-trunk\`) — NOT by any flag. Without that grant, ship refuses and a human must run
10034
- Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
10035
+ Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). That human runs ship
10036
+ too, through the HUMAN DOOR (#525): at an interactive terminal (outside an agent shell) ship asks
10037
+ them to confirm; non-interactively, COLAB_HUMAN=1 plus --answered-by <name>. Every other
10038
+ precondition still applies, and the 🚢 comment records that the human door opened the gate.
10039
+ ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
10035
10040
 
10036
10041
  Base and target are ONE decision. A branch cut from a long-lived line and shipped into trunk would
10037
10042
  drag the entire line in behind it, as a single squash commit that reads like a small change — so
@@ -10041,6 +10046,8 @@ promotes is an integration event of the same weight as a promotion, and stays hu
10041
10046
 
10042
10047
  Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
10043
10048
  a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
10049
+ — or a person runs ship through the human door (#525): a confirmed interactive
10050
+ terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
10044
10051
  b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
10045
10052
  human step needed — OR every issue the branch carries holds a valid
10046
10053
  \`colab ci-grant\` over trunk's CURRENT red sha, #105 — see below) · no new
@@ -11682,7 +11689,8 @@ function cmdShipDryJson(opts) {
11682
11689
  }
11683
11690
 
11684
11691
  // ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
11685
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
11692
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
11693
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
11686
11694
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
11687
11695
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
11688
11696
 
@@ -12081,7 +12089,7 @@ function shipEvidenceClose({ repoAbs, st, sess, target, trunk, gh, closeIssues,
12081
12089
  `The deliverable is recorded on this issue (see the comment(s) above), which is what authorised ` +
12082
12090
  `the close — colab closes a zero-diff issue only when it already carries a comment colab did not ` +
12083
12091
  `write. The zero-diff fact was measured from git: ${mode.why}.${shipSess}`;
12084
- const c = git.ghIssueComment(repoAbs, num, body);
12092
+ const c = git.ghIssueComment(repoAbs, num, body + (opts.humanDoorEvidence || '')); // #525
12085
12093
  if (!c.ok) warn(`could not post the evidence-close comment on #${num} — closing anyway`);
12086
12094
  const r = tracker.forRepo(repoAbs).issueClose(num, { reason: 'completed' });
12087
12095
  if (!r.ok) { skipped.push({ num, why: `gh issue close failed: ${(r.stderr || '').split('\n')[0]}` }); continue; }
@@ -12243,7 +12251,8 @@ function cmdShipDirect(opts) {
12243
12251
  // #345: a trunk-direct unit has no branch diff. Its change set is every trunk commit since its
12244
12252
  // earliest claim — by anyone, so the verdict can only err toward refusing (lib/docs-only.js).
12245
12253
  const since = claims.map((c) => c.created).filter(Boolean).sort()[0];
12246
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since));
12254
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since),
12255
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12247
12256
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
12248
12257
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
12249
12258
 
@@ -12322,6 +12331,7 @@ function cmdShipDirect(opts) {
12322
12331
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12323
12332
  process.stderr.write(' A human must close this unit. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12324
12333
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12334
+ process.stderr.write(shipHumanDoorRefusal(autonomyGate, '--direct'));
12325
12335
  return 1;
12326
12336
  }
12327
12337
  if (!coreOk && coreReview.corePaths.length) {
@@ -12333,6 +12343,7 @@ function cmdShipDirect(opts) {
12333
12343
  process.stderr.write(' unit\'s reviewed landing, a human closes this issue by hand.\n');
12334
12344
  }
12335
12345
  if (autonomyGate.via === 'docs-only') print(`→ AUTONOMY: ${autonomyGate.detail} (#345) — project.yml autonomy: ${autonomyGate.declared}`);
12346
+ if (autonomyGate.via === 'human') print(`→ AUTONOMY: ${autonomyGate.detail}`);
12336
12347
  print(`→ MODE: evidence-close (trunk-direct — the work is already on ${trunk}; nothing to merge)`);
12337
12348
  if (opts.dry) {
12338
12349
  print(preOk ? '→ READY: preconditions pass. Re-run without --dry to close.' : '→ NOT READY: fix the ✗ rows above.');
@@ -12344,6 +12355,7 @@ function cmdShipDirect(opts) {
12344
12355
  return preOk ? 0 : 1;
12345
12356
  }
12346
12357
  if (!preOk) { process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was closed.\n'); return 1; }
12358
+ if (!shipHumanDoorGo(autonomyGate, opts, `close ${issues.map((n) => '#' + n).join(' ')} on ${trunk} (trunk-direct)`)) return 1;
12347
12359
 
12348
12360
  const tip = shortSha(git.git(['rev-parse', trunk], repoAbs).stdout);
12349
12361
  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}` };
@@ -12561,20 +12573,81 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
12561
12573
  *
12562
12574
  * Returns `{ ok, via: 'auto-trunk'|'docs-only'|null, declared, docsOnly: verdict|null, detail }`.
12563
12575
  */
12564
- function shipAutonomyGate(doc, readDocsOnly) {
12576
+ function shipAutonomyGate(doc, readDocsOnly, door = null) {
12565
12577
  const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
12566
- if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, detail: 'auto-trunk' };
12578
+ if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
12567
12579
  const verdict = readDocsOnly();
12568
12580
  if (verdict.docsOnly) {
12569
- return { ok: true, via: 'docs-only', declared, docsOnly: verdict, detail: `${verdict.reason} — autonomy exception` };
12581
+ return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
12582
+ }
12583
+ // #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
12584
+ // after docs-only, so a docs-only change keeps its own (agent-usable) door and record.
12585
+ if (door && door.open) {
12586
+ return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
12587
+ detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
12588
+ }
12589
+ return { ok: false, via: null, declared, docsOnly: verdict, human: door,
12590
+ detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; human door closed: ${door ? door.why : 'not offered'})` };
12591
+ }
12592
+
12593
+ /** #525: the human-door refusal lines — what a person runs, never just "a human must". */
12594
+ function shipHumanDoorRefusal(gate, selector) {
12595
+ const lines = [];
12596
+ if (gate.human && gate.human.why) lines.push(` The human door (#525) did not open: ${gate.human.why}.`);
12597
+ lines.push(' A person gives the go by running ship themselves — every other precondition still applies:');
12598
+ for (const l of humanDoor.humanDoorCommands(selector)) lines.push(` ${l}`);
12599
+ lines.push(' An agent does not pass this door on its own (CONVENTIONS.md §2, *The human door*).');
12600
+ return lines.join('\n') + '\n';
12601
+ }
12602
+
12603
+ /** #525: the ship selector to paste into the refusal's command line. */
12604
+ function shipSelector(opts, sess) {
12605
+ if (opts.direct) return '--direct';
12606
+ if (opts.worktree) return `--worktree ${opts.worktree}`;
12607
+ if (sess && sess.name) return `--worktree ${sess.name}`;
12608
+ if (opts.branch) return `--branch ${opts.branch}`;
12609
+ return sess && sess.branch ? `--branch ${sess.branch}` : '';
12610
+ }
12611
+
12612
+ /**
12613
+ * #525: confirm the TTY door by a typed answer. Synchronous on purpose — ship is a sync pipeline,
12614
+ * and the prompt sits before any write. Anything but `y`/`yes` is a no; EOF is a no.
12615
+ */
12616
+ function shipConfirmAtTerminal(question) {
12617
+ process.stdout.write(`${question} [y/N] `);
12618
+ const buf = Buffer.alloc(256);
12619
+ let line = '';
12620
+ for (;;) {
12621
+ let n = 0;
12622
+ try { n = fs.readSync(0, buf, 0, buf.length, null); } catch (e) { if (e.code === 'EAGAIN') continue; return false; }
12623
+ if (n <= 0) break;
12624
+ line += buf.toString('utf8', 0, n);
12625
+ if (line.includes('\n')) break;
12570
12626
  }
12571
- return { ok: false, via: null, declared, docsOnly: verdict,
12572
- detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason})` };
12627
+ return /^\s*y(es)?\s*$/i.test(line.split('\n')[0]);
12628
+ }
12629
+
12630
+ /**
12631
+ * #525: the last step before any write when the human door opened the gate. A TTY door asks the
12632
+ * person to confirm; a COLAB_HUMAN door already carries its go (`--answered-by`). Either way the
12633
+ * evidence clause is stashed on `opts` for the comment writers. Returns false on a declined prompt.
12634
+ */
12635
+ function shipHumanDoorGo(gate, opts, what) {
12636
+ if (gate.via !== 'human') return true;
12637
+ if (gate.human.how === 'tty' && !shipConfirmAtTerminal(`Human door (#525): ${what}. This is your go — proceed?`)) {
12638
+ process.stderr.write('✗ Not confirmed at the terminal. Nothing was changed.\n');
12639
+ return false;
12640
+ }
12641
+ opts.humanDoorEvidence = humanDoor.humanDoorEvidence(gate.human);
12642
+ return true;
12573
12643
  }
12574
12644
 
12575
12645
  /** #345: the additive `autonomyGate` field of the `--dry --json` output. */
12576
12646
  function autonomyGatePayload(gate) {
12577
- return { via: gate.via, docsOnly: gate.docsOnly };
12647
+ // #525: `human` is additive and present only when the human door was consulted, so an
12648
+ // auto-trunk / docs-only payload stays byte-identical to before.
12649
+ return gate.human ? { via: gate.via, docsOnly: gate.docsOnly, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } }
12650
+ : { via: gate.via, docsOnly: gate.docsOnly };
12578
12651
  }
12579
12652
 
12580
12653
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
@@ -12585,7 +12658,7 @@ function shipRefFor(repoAbs, branch) {
12585
12658
 
12586
12659
  function cmdShip(argv) {
12587
12660
  const opts = parseArgs(argv, {
12588
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch' },
12661
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
12589
12662
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
12590
12663
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
12591
12664
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -12660,11 +12733,13 @@ function cmdShip(argv) {
12660
12733
 
12661
12734
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
12662
12735
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
12663
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
12736
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
12737
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12664
12738
  if (!autonomyGate.ok) {
12665
12739
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12666
12740
  process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12667
12741
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12742
+ process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
12668
12743
  return 1;
12669
12744
  }
12670
12745
 
@@ -13057,6 +13132,9 @@ function cmdShip(argv) {
13057
13132
  }
13058
13133
  process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was pushed.\n'); return 1;
13059
13134
  }
13135
+ if (!shipHumanDoorGo(autonomyGate, opts, mode.evidenceClose
13136
+ ? `evidence-close ${sess.issues.map((n) => '#' + n).join(' ')} (${sess.branch} has nothing to merge)`
13137
+ : `squash-merge ${sess.branch} into ${target}`)) return 1;
13060
13138
 
13061
13139
  // ---- (b3) evidence-close: the whole B0–B2 sequence is skipped, because there is nothing to merge ----
13062
13140
  if (mode.evidenceClose) return shipEvidenceClose({
@@ -13573,7 +13651,8 @@ function cmdShip(argv) {
13573
13651
  // last — see warnDeferred's own comment for why this is scoped to exactly this window. The
13574
13652
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
13575
13653
  // same block, and re-assigning the collector here would silently discard them.
13576
- shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts });
13654
+ shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
13655
+ evidenceExtra: opts.humanDoorEvidence || '' }); // #525
13577
13656
 
13578
13657
  print('');
13579
13658
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -169,6 +169,11 @@
169
169
  * this entry, plus the matching `code-triage` verdict, is what makes those readings
170
170
  * reconcilable instead of silently contradictory.
171
171
  *
172
+ * `priority:now` / `priority:high` joined the set in #537: the upward rank beside `low-priority`
173
+ * (CONVENTIONS.md §5, *Priority*). Fixed values, not a prefix kind — they decode as plain
174
+ * `convention` labels. Same malignant-absence reason: a rank only the owner may set must be
175
+ * appliable the moment the owner says so, which a label the repo never created is not.
176
+ *
172
177
  * `deferred:date` / `deferred:measurement` / `deferred:external-party` joined the set in
173
178
  * #279: `deps-checked` was being asked to carry two orthogonal facts at once — "has a
174
179
  * reasoning session evaluated this?" (process state, monotonic — the label's own
@@ -222,6 +227,8 @@ const CONVENTION_LABELS = [
222
227
  { name: 'needs-migration-grant', color: 'D4C5F9', description: 'Agent-flagged: deliverable is a schema migration; surfaces the grant request for a human to Accept' },
223
228
  { name: 'ci-granted', color: 'D73A4A', description: "A human granted this branch a one-shot exemption from ship's trunk-CI-green gate" },
224
229
  { name: 'low-priority', color: 'C2E0C6', description: 'Throttle, not a veto — startable, but code-triage ranks it behind every other ready group' },
230
+ { name: 'priority:now', color: 'B60205', description: "Rank first among ready work — the owner's order; never skips a gate or overrides a file hold" },
231
+ { name: 'priority:high', color: 'D93F0B', description: 'Rank ahead of default among ready work — owner or coordinator; never skips a gate' },
225
232
  { name: 'delivery:code', color: '1D76DB', description: 'Delivery is a code commit — the ordinary code pipeline applies' },
226
233
  { name: 'delivery:content', color: 'FEF2C0', description: 'Delivery is a content push, not a code commit — route, do not start in the code pipeline' },
227
234
  { name: 'delivery:ops', color: 'D4C5F9', description: 'Delivery is an ops/production check, not a code commit — route, do not start in the code pipeline' },
@@ -81,6 +81,22 @@
81
81
  "known": true
82
82
  }
83
83
  },
84
+ {
85
+ "wire": "priority:now",
86
+ "decoded": {
87
+ "kind": "convention",
88
+ "value": "priority:now",
89
+ "known": true
90
+ }
91
+ },
92
+ {
93
+ "wire": "priority:high",
94
+ "decoded": {
95
+ "kind": "convention",
96
+ "value": "priority:high",
97
+ "known": true
98
+ }
99
+ },
84
100
  {
85
101
  "wire": "release-hold",
86
102
  "decoded": {
@@ -0,0 +1,76 @@
1
+ 'use strict';
2
+ /**
3
+ * #525 — the human door on `colab ship`'s autonomy gate.
4
+ *
5
+ * Without `autonomy: auto-trunk` the gate used to have two answers: docs-only (#345) or refuse.
6
+ * The refusal said "a human must trigger Phase B", but refused that human too, so on the default
7
+ * (`manual`) repo the person meant to give the go had no tool to give it with. Ruling on #525
8
+ * (option 1): a person running `colab ship` IS the go, measured on the bar the CLI already applies
9
+ * to human-only acts (`colab adopt --autonomy`, `colab release finalize`):
10
+ *
11
+ * - an interactive terminal (stdin AND stdout a TTY) outside an agent shell, confirmed by typing
12
+ * at the prompt — `how: 'tty'`; or
13
+ * - `COLAB_HUMAN=1` AND `--answered-by <name>` — `how: 'colab-human'`.
14
+ *
15
+ * An agent never passes on its own: an agent shell (`CLAUDECODE=1` / `AI_AGENT`, the signals
16
+ * `lib/place.js` already reads) does not count as a terminal, and setting `COLAB_HUMAN=1` is
17
+ * governed by the handbook's existing rule — never on the agent's own say-so.
18
+ *
19
+ * Pure: every input is passed in, so the TTY branch is unit-testable without a pty.
20
+ */
21
+
22
+ /** Is this process running inside an agent's shell? Same signals as lib/place.js rule 3. */
23
+ function isAgentShell(env) {
24
+ return env.CLAUDECODE === '1' || !!env.AI_AGENT;
25
+ }
26
+
27
+ /**
28
+ * @returns {{ open: boolean, how: 'tty'|'colab-human'|null, why: string }}
29
+ */
30
+ function humanDoorVerdict({ isTTY, colabHuman, answeredBy, agentShell }) {
31
+ if (colabHuman && answeredBy) {
32
+ return { open: true, how: 'colab-human', why: `COLAB_HUMAN=1, answered by ${answeredBy}` };
33
+ }
34
+ if (colabHuman && !answeredBy) {
35
+ return { open: false, how: null, why: 'COLAB_HUMAN=1 also needs --answered-by "<name>"' };
36
+ }
37
+ if (isTTY && !agentShell) {
38
+ return { open: true, how: 'tty', why: 'a person at an interactive terminal' };
39
+ }
40
+ if (isTTY && agentShell) {
41
+ return { open: false, how: null, why: 'an agent shell is not a person at a terminal' };
42
+ }
43
+ return { open: false, how: null, why: 'unattended (no interactive terminal, no COLAB_HUMAN=1)' };
44
+ }
45
+
46
+ /** Read the door's inputs from a real process. */
47
+ function humanDoorFromProcess(proc, answeredBy) {
48
+ return humanDoorVerdict({
49
+ isTTY: !!(proc.stdin.isTTY && proc.stdout.isTTY),
50
+ colabHuman: proc.env.COLAB_HUMAN === '1',
51
+ answeredBy: answeredBy || null,
52
+ agentShell: isAgentShell(proc.env),
53
+ });
54
+ }
55
+
56
+ /**
57
+ * The exact commands a human runs, for the refusal. `target` is the ship selector the caller
58
+ * used (`--worktree x`, `--branch y`, `--direct`), so the line can be pasted as it stands.
59
+ */
60
+ function humanDoorCommands(selector) {
61
+ const sel = selector ? ` ${selector}` : '';
62
+ return [
63
+ `at your own terminal: colab ship${sel} (asks you to confirm)`,
64
+ `or, non-interactive: COLAB_HUMAN=1 colab ship${sel} --answered-by "<your name>"`,
65
+ ];
66
+ }
67
+
68
+ /** The clause the 🚢 / ✅ evidence comment carries when the human door opened the gate. */
69
+ function humanDoorEvidence(door) {
70
+ if (!door || !door.open) return '';
71
+ return door.how === 'tty'
72
+ ? ' · merged through the human door (#525): a person confirmed at an interactive terminal'
73
+ : ` · merged through the human door (#525): ${door.why}`;
74
+ }
75
+
76
+ module.exports = { isAgentShell, humanDoorVerdict, humanDoorFromProcess, humanDoorCommands, humanDoorEvidence };