@futurelastic/colab-handbook 1.13.0-rc.43 → 1.13.0-rc.45

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.13.0-rc.43"
36
+ "version": "1.13.0-rc.45"
37
37
  }
@@ -713,6 +713,28 @@ jobs:
713
713
  extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
714
714
  coverage: none
715
715
 
716
+ # Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
717
+ # with composer.lock present. Both halves are load-bearing:
718
+ # - No composer.lock → nothing stable to key on; every run would save a fresh entry.
719
+ # - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
720
+ # jobs; a remote cache on top was measured as a loss, not a saving (#512).
721
+ # Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
722
+ # and its body: `colab ship`'s cure rule matches steps by exact name.
723
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
724
+ # two steps.
725
+ - name: Locate Composer cache
726
+ id: composer-cache
727
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
728
+ run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
729
+
730
+ - name: Restore Composer cache
731
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
732
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
733
+ with:
734
+ path: ${{ steps.composer-cache.outputs.dir }}
735
+ key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
736
+ restore-keys: composer-${{ runner.os }}-
737
+
716
738
  - name: Composer install
717
739
  env:
718
740
  RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
@@ -747,9 +769,15 @@ jobs:
747
769
  # stderr and reports only "Command failed".
748
770
  php artisan wayfinder:generate $WAYFINDER_ARGS
749
771
 
772
+ # npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
773
+ # package-lock.json present (`cache: npm` fails the step without one). The automatic
774
+ # `packageManager` cache is pinned to the same condition so it cannot override it.
775
+ # EDIT: to turn it off everywhere, replace both expressions with '' and false.
750
776
  - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
751
777
  with:
752
778
  node-version: ${{ steps.toolchain.outputs.node-version }}
779
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
780
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
753
781
 
754
782
  - name: Build frontend assets (Vite)
755
783
  run: |
@@ -646,11 +646,26 @@ jobs:
646
646
  echo "Node $NODE_VERSION (resolved from: $SOURCE)"
647
647
  echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
648
648
 
649
+ # Package cache (#571): on only on a GitHub-hosted runner AND with package-lock.json
650
+ # present. Both halves are load-bearing:
651
+ # - No lockfile → setup-node's `cache:` fails the step outright ("Dependencies lock
652
+ # file is not found"), and this template allows a repo without one.
653
+ # - Self-hosted → off. A persistent runner already keeps ~/.npm between jobs; a
654
+ # remote cache on top was measured as a loss, not a saving (#512).
655
+ # npm only: `cache: pnpm` needs pnpm on PATH before this step, and the install step
656
+ # below enables it through corepack afterwards. `package-manager-cache` is pinned to
657
+ # the same condition so setup-node's automatic `packageManager` caching cannot switch
658
+ # it back on where the condition says off.
659
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, replace
660
+ # both expressions with '' and false. If the app is not at the root, point the
661
+ # hashFiles() and a `cache-dependency-path:` at its package-lock.json.
649
662
  - name: Setup Node
650
663
  uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
651
664
  if: hashFiles('package.json') != ''
652
665
  with:
653
666
  node-version: ${{ steps.toolchain.outputs.node-version }}
667
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
668
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
654
669
 
655
670
  - name: Install dependencies
656
671
  if: hashFiles('package.json') != ''
@@ -807,6 +822,9 @@ jobs:
807
822
  # uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
808
823
  # with:
809
824
  # node-version: ${{ needs.build.outputs.node-version }}
825
+ # # Same cache gate as the build job's Setup Node (#571): hosted + lockfile only.
826
+ # cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
827
+ # package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
810
828
  #
811
829
  # - name: Install dependencies
812
830
  # run: |
@@ -636,9 +636,24 @@ jobs:
636
636
  echo "Python $PY_VERSION (resolved from: $SOURCE)"
637
637
  echo "Python **$PY_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
638
638
 
639
+ # Package cache (#571): pip's wheel cache, on only on a GitHub-hosted runner AND with a
640
+ # dependency manifest present. Both halves are load-bearing:
641
+ # - No requirements*.txt / pyproject.toml → setup-python's `cache: pip` fails the step
642
+ # ("No file ... matched"), and this template allows a repo with neither.
643
+ # - Self-hosted → off. A persistent runner already keeps ~/.cache/pip between jobs; a
644
+ # remote cache on top was measured as a loss, not a saving (#512).
645
+ # The cache holds downloaded wheels, never a resolution: it cannot change which versions
646
+ # install, so a repo without a pinned lockfile is no less reproducible with it on.
647
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, replace the
648
+ # `cache:` expression with ''. Manifests outside the root → widen cache-dependency-path
649
+ # and the hashFiles() to match.
639
650
  - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
640
651
  with:
641
652
  python-version: ${{ steps.toolchain.outputs.python-version }}
653
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('requirements*.txt', 'pyproject.toml') != '' && 'pip' || '' }}
654
+ cache-dependency-path: |
655
+ requirements*.txt
656
+ pyproject.toml
642
657
 
643
658
  - name: Install dependencies
644
659
  run: |
package/tools/colab CHANGED
@@ -78,6 +78,7 @@ const releaseFinalize = require('./lib/release-finalize');
78
78
  const releaseChannel = require('./lib/release-channel');
79
79
  const shippedBranch = require('./lib/shipped-branch');
80
80
  const shipRoles = require('./lib/ship-roles'); // #372
81
+ const shipHandoff = require('./lib/ship-handoff'); // #578
81
82
  const refsBrake = require('./lib/refs-brake'); // #385
82
83
  const localAdopt = require('./lib/local-adopt'); // #393
83
84
  const ownerBranch = require('./lib/owner-branch'); // #394
@@ -10275,7 +10276,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10275
10276
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
10276
10277
  }
10277
10278
 
10278
- 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]
10279
+ const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
10279
10280
  colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10280
10281
 
10281
10282
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
@@ -10371,6 +10372,19 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
10371
10372
  \`Colab-Adopted: origin/<br> @ <sha> on <host> (machine <id>)\` trailer. A LOCAL no-digit branch is
10372
10373
  still a legitimate zero. --adopt never bypasses a branch that names issues.
10373
10374
 
10375
+ A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
10376
+ \`colab ship --branch <br> --handoff <url>\`, where <url> is the executor's hand-off comment
10377
+ (…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
10378
+ name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
10379
+ one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
10380
+ branch that moved after its hand-off needs a new one); and every issue the branch carries has a
10381
+ live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
10382
+ claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
10383
+ the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
10384
+ 🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
10385
+ the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
10386
+ --batch or --direct, and not when this machine already holds a claim on the branch.
10387
+
10374
10388
  UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
10375
10389
  --session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
10376
10390
  (--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
@@ -11897,8 +11911,13 @@ function cmdShipDryJson(opts) {
11897
11911
  const trunk = resolveTrunk(repoAbs, doc);
11898
11912
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
11899
11913
  if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
11914
+ const handoff = applyShipHandoff(repoAbs, sess, opts); // #578 — same resolution as the prose path
11900
11915
 
11901
11916
  const checks = [];
11917
+ if (handoff) {
11918
+ checks.push({ name: 'hand-off verified (#578)', ok: handoff.ok, class: handoff.ok ? null : HUMAN_GATED,
11919
+ detail: handoff.ok ? handoffDetail(handoff) : `${handoff.reason}: ${handoff.detail}` });
11920
+ }
11902
11921
  let target = null;
11903
11922
  // #74/#263: the close-gate split (closeIssues/refsIssues/checklistFindings) is reported
11904
11923
  // ALONGSIDE `checks` AS WELL AS folded into it — `closeIssues`/`refsIssues`/`checklistFindings`
@@ -12968,6 +12987,62 @@ function autonomyGatePayload(gate) {
12968
12987
  }
12969
12988
 
12970
12989
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
12990
+ /**
12991
+ * #578 — `--handoff <comment-url>`: verify the executor's recorded hand-off and, when it holds, take
12992
+ * the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
12993
+ * without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
12994
+ *
12995
+ * Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
12996
+ * this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
12997
+ */
12998
+ function applyShipHandoff(repoAbs, sess, opts) {
12999
+ if (!opts.handoff) return null;
13000
+ if (opts.adopt) throw new UserError('--handoff and --adopt contradict each other: --adopt is for a branch with NO issue, --handoff for one whose claim lives on another machine — drop --adopt');
13001
+ if (sess.issues.length) {
13002
+ throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
13003
+ `for ${sess.branch} — ship it without --handoff`);
13004
+ }
13005
+ const u = shipHandoff.parseHandoffUrl(opts.handoff);
13006
+ let comment = null;
13007
+ if (u) {
13008
+ const r = git.ghApi(repoAbs, [`repos/{owner}/{repo}/issues/comments/${u.commentId}`]);
13009
+ if (r.ok) {
13010
+ try {
13011
+ const j = JSON.parse(r.stdout);
13012
+ comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
13013
+ } catch (_) { comment = null; }
13014
+ }
13015
+ }
13016
+ // The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
13017
+ const remote = git.remoteFor(repoAbs);
13018
+ if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
13019
+ const refs = git.branchRefs(repoAbs, sess.branch, remote);
13020
+ const claimsByIssue = {};
13021
+ if (u && comment) {
13022
+ for (const n of shipguard.branchIssueNumbers(sess.branch)) {
13023
+ const info = git.ghIssueView(repoAbs, n, ['comments']);
13024
+ claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
13025
+ }
13026
+ }
13027
+ const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue });
13028
+ if (!v.ok) return v;
13029
+ sess.issues = v.issues;
13030
+ sess.handoff = v;
13031
+ // #372: the implementer is the executor that handed off — name it, never leave it reading as the shipper.
13032
+ const ex = (claimsByIssue[v.issues[0]] || []).find((c) => c.branch === sess.branch && c.login === v.executor.login);
13033
+ if (ex && (ex.session || ex.sessionName)) sess.holder = { session: ex.session || '', sessionName: ex.sessionName || '' };
13034
+ return v;
13035
+ }
13036
+
13037
+ function handoffDetail(v) {
13038
+ return `${v.url} hands off ${shortSha(v.sha)} = the remote head; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
13039
+ }
13040
+
13041
+ /** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
13042
+ function handoffEvidence(v) {
13043
+ return v ? ` · landed from the executor's hand-off ${v.url} — its claim and worktree stay until it confirms the land` : '';
13044
+ }
13045
+
12971
13046
  function shipRefFor(repoAbs, branch) {
12972
13047
  const r = git.branchRefs(repoAbs, branch);
12973
13048
  return r.localSha || r.remoteSha || branch;
@@ -12975,7 +13050,7 @@ function shipRefFor(repoAbs, branch) {
12975
13050
 
12976
13051
  function cmdShip(argv) {
12977
13052
  const opts = parseArgs(argv, {
12978
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
13053
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
12979
13054
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
12980
13055
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
12981
13056
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -12990,6 +13065,8 @@ function cmdShip(argv) {
12990
13065
  // — refuse the combination rather than silently ignore --json on a real ship.
12991
13066
  if (opts.json && !opts.dry) throw new UserError('--json currently only applies together with --dry — see `colab ship --help`');
12992
13067
  if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
13068
+ // #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
13069
+ if (opts.handoff && (opts.batch || opts.direct)) throw new UserError(`--handoff applies to one --branch ship — not to ${opts.batch ? '--batch' : '--direct'} (see \`colab ship --help\`)`);
12993
13070
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
12994
13071
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
12995
13072
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -13007,6 +13084,17 @@ function cmdShip(argv) {
13007
13084
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
13008
13085
  if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
13009
13086
 
13087
+ // #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
13088
+ // branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
13089
+ // remote-only branch resolve here at all.
13090
+ const handoff = applyShipHandoff(repoAbs, sess, opts);
13091
+ if (handoff && !handoff.ok) {
13092
+ process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
13093
+ `ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
13094
+ process.stderr.write(' Nothing was claimed or taken over here — the executor\'s claim still stands.\n');
13095
+ return 1;
13096
+ }
13097
+
13010
13098
  // ---- the recorded branch must RESOLVE, before anything else is computed ----
13011
13099
  // Everything downstream is keyed to this name: the claim lookup above, the migration diff, the
13012
13100
  // squash. A worktree record holding a role word or a deleted branch fails all three quietly —
@@ -13066,6 +13154,7 @@ function cmdShip(argv) {
13066
13154
  const gh = isGhUsable(repoAbs);
13067
13155
  // #345: the gate that passed is the table's first row, so a reader sees WHICH door opened it.
13068
13156
  const checks = [['✓', 'autonomy granted', autonomyGate.detail]];
13157
+ if (handoff) checks.push(['✓', 'hand-off verified (#578)', handoffDetail(handoff)]);
13069
13158
 
13070
13159
  // Which claimed issues are REFERENCED (Refs #N), not closed — three sources unioned by
13071
13160
  // resolveCloseRefsSplit (#48, #74): --refs, the tracking label, and #74's close gate (an
@@ -13738,7 +13827,7 @@ function cmdShip(argv) {
13738
13827
  (publicOmit ? (m) => print(` ${m}`) : warn)(`Machine trailer ${machineTrailerSummary(trailerDecision)}`);
13739
13828
  }
13740
13829
  const machineLine = trailerDecision.line;
13741
- const ciTrailerLines = [ciTrailer, adoptTrailer, machineLine].filter(Boolean);
13830
+ const ciTrailerLines = [ciTrailer, adoptTrailer, shipHandoff.handoffTrailer(sess.handoff), machineLine].filter(Boolean);
13742
13831
  if (opts.message) {
13743
13832
  // --message overrides the subject/body, but Closes is spliced in as its own paragraph — never
13744
13833
  // concatenated. Appending it welded ` — Closes #N` onto whatever the message ended with, which
@@ -13747,7 +13836,7 @@ function cmdShip(argv) {
13747
13836
  for (const tl of ciTrailerLines) {
13748
13837
  if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
13749
13838
  const lastLine = commitMsg.split('\n').pop().trim();
13750
- commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
13839
+ commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
13751
13840
  }
13752
13841
  } else {
13753
13842
  // Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
@@ -13957,7 +14046,7 @@ function cmdShip(argv) {
13957
14046
  pushEvent('ship', {
13958
14047
  repo: repoAbs, worktree: sess.name, session: sess.session,
13959
14048
  issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
13960
- payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}) },
14049
+ payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}), ...(sess.handoff ? { handoff: { url: sess.handoff.url, sha: sess.handoff.sha } } : {}) },
13961
14050
  });
13962
14051
 
13963
14052
  // Then, PER ISSUE, a merge-completion event (#46 §2, following #45 §2). The ship event above is
@@ -13979,11 +14068,12 @@ function cmdShip(argv) {
13979
14068
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
13980
14069
  // same block, and re-assigning the collector here would silently discard them.
13981
14070
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
13982
- evidenceExtra: opts.humanDoorEvidence || '' }); // #525
14071
+ evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
13983
14072
 
13984
14073
  print('');
13985
14074
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
13986
14075
  if (adoptInfo) print(` adopted from ${adoptInfo.remote || 'origin'}/${adoptInfo.branch} @ ${shortSha(adoptInfo.remoteSha)} — recorded in the Colab-Adopted: trailer (#324)`);
14076
+ if (sess.handoff) print(` landed from the hand-off ${sess.handoff.url} — the executor's claim and worktree stay until it confirms the land (#578)`);
13987
14077
  if (target !== trunk) print(` "${target}" is a declared line: this work is NOT in ${trunk} until a human merges the line.`);
13988
14078
  // #114: everything deferred since the push (e2, #304) lands here, AFTER the success line — not scattered above it
13989
14079
  // where a long ship scrolls it out of view. The merge itself already landed either way; this is
@@ -14025,7 +14115,8 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
14025
14115
  // B3 (cont.) — the shipped branch. Kept by default; --delete-branch opts in. MUST come after the
14026
14116
  // worktree removal above: git refuses to delete a branch checked out in a worktree.
14027
14117
  // #368: a Refs-only ship deletes unless --keep-branch — see tools/lib/shipped-branch.js.
14028
- const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch });
14118
+ // #578: a handed-off branch is the executor's until it confirms the land — never deleted for it.
14119
+ const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch || (!!sess.handoff && !opts.deleteBranch) });
14029
14120
  handleShippedBranch(repoAbs, target, sess.branch, { disposition, worktreeKept, integration });
14030
14121
 
14031
14122
  // ---- (g/h) B4 verify + post summary per issue ----
@@ -55,7 +55,7 @@ function releaseComments(sorted) {
55
55
 
56
56
  /**
57
57
  * Live claim comments on an issue. Returns [{login, host, machine, session, sessionName, at,
58
- * identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
58
+ * branch, worktree, identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
59
59
  * is built from `comps` (claim-identity.js `components()`, #267); the raw fields are returned too
60
60
  * for callers that need `sameClaimant`'s degrade-on-missing comparison.
61
61
  *
@@ -91,7 +91,8 @@ function liveClaimComments(comments, comps) {
91
91
  const { host, session, sessionName } = claim;
92
92
  const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
93
93
  const at = c.createdAt;
94
- const entry = { login, host, machine: machineTok, session, sessionName, at };
94
+ // #578: branch/worktree ride along so a reader can ask WHICH branch a live claim holds.
95
+ const entry = { login, host, machine: machineTok, session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
95
96
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
96
97
  || (r.login === login && !isNamedWinner(entry, r.winner))));
97
98
  if (!cancelled) live.push({ ...entry, identity: claimIdentity.identityString({ login, host, session }, comps) });
@@ -0,0 +1,116 @@
1
+ 'use strict';
2
+ /**
3
+ * #578 — `colab ship --branch <br> --handoff <comment-url>`: land a branch whose claim lives on
4
+ * ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
5
+ *
6
+ * The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
7
+ * A branch built and wrapped on machine A and landed from machine B has its claim in A's registry,
8
+ * so on B ship reads zero claims and refuses (#153 / #324). The only way to write a record on B was
9
+ * `colab claim --force` — a human-only takeover — so an agent lander had no sanctioned path, and
10
+ * every remote-built branch waited for a person even when it had passed review and merged clean.
11
+ *
12
+ * The door. The executor has already said, on the tracker, which branch it handed off and at which
13
+ * head. That comment, checked against git and against the executor's own live claim, is the
14
+ * evidence ship would otherwise get from a local claim. Nothing on B's registry is written and
15
+ * nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
16
+ * (its own `colab worktree rm`, which releases the claim as usual).
17
+ *
18
+ * What a hand-off must prove, in order — the first failure is the verdict:
19
+ * 1. the URL is an issue-comment URL (`…/issues/<N>#issuecomment-<id>`);
20
+ * 2. the comment was read from THIS repo (fetched through `{owner}/{repo}`, so an off-repo id is a
21
+ * 404) and its own html_url names the same issue the URL does;
22
+ * 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
23
+ * issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
24
+ * 4. the body names the branch, as a whole token;
25
+ * 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
26
+ * 6. the body names a sha that is a prefix of the remote branch's CURRENT head — a branch that
27
+ * moved after its hand-off was not handed off at that head, and lands only after a new one;
28
+ * 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
29
+ * the hand-off's author before the hand-off — the claim really does live elsewhere, and the
30
+ * party handing off is the party holding it.
31
+ *
32
+ * Pure: every input is already read. tools/colab does the IO (`gh api`, `git fetch`, issue views).
33
+ */
34
+
35
+ const { branchIssueNumbers } = require('./branch-name');
36
+
37
+ /** `https://github.com/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE). */
38
+ function parseHandoffUrl(url) {
39
+ const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
40
+ if (!m) return null;
41
+ return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
42
+ }
43
+
44
+ function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
45
+
46
+ /** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
47
+ function namesBranch(body, branch) {
48
+ if (!branch) return false;
49
+ return new RegExp(`(^|[^A-Za-z0-9._/-])${escapeRe(branch)}(?![A-Za-z0-9._/-])`).test(String(body || ''));
50
+ }
51
+
52
+ /** Every 7–40 hex token in `body`, lower-cased — the candidate head shas a hand-off names. */
53
+ function namedShas(body) {
54
+ return [...String(body || '').matchAll(/(?<![0-9A-Za-z])([0-9a-fA-F]{7,40})(?![0-9A-Za-z])/g)]
55
+ .map((m) => m[1].toLowerCase());
56
+ }
57
+
58
+ /**
59
+ * The verdict. Inputs:
60
+ * url — the --handoff value
61
+ * comment — { body, login, createdAt, htmlUrl } as read from THIS repo, or null (unreadable)
62
+ * branch — the branch being shipped
63
+ * refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
64
+ * claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
65
+ * or null for an issue whose comments could not be read
66
+ * Returns { ok: true, issues, sha, executor, url } or { ok: false, reason, detail }.
67
+ */
68
+ function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
69
+ const no = (reason, detail) => ({ ok: false, reason, detail });
70
+ const u = parseHandoffUrl(url);
71
+ if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
72
+ if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
73
+ const got = parseHandoffUrl(comment.htmlUrl);
74
+ if (!got || got.commentId !== u.commentId || got.issue !== u.issue ||
75
+ got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
76
+ return no('mismatch', `the URL says ${u.owner}/${u.repo}#${u.issue}, but comment ${u.commentId} is ${comment.htmlUrl || 'somewhere else'}`);
77
+ }
78
+ const issues = branchIssueNumbers(branch);
79
+ if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
80
+ if (!issues.includes(u.issue)) return no('not-this-branch', `the hand-off is on #${u.issue}, which ${branch} does not carry (${issues.map((n) => '#' + n).join(' ')})`);
81
+ if (!namesBranch(comment.body, branch)) return no('branch-not-named', `the hand-off comment does not name the branch ${branch}`);
82
+ if (!refs || !refs.remoteSha) return no('no-remote-branch', `${branch} is not on the remote — a hand-off lands a pushed branch only`);
83
+ // Ship merges the local ref when one exists (shipRefFor), so it must BE the remote head: a stale
84
+ // copy a DWIM checkout made earlier would land a sha the hand-off never named.
85
+ if (refs.localSha && refs.localSha !== refs.remoteSha) {
86
+ return no('local-diverges', refs.localFromRemote
87
+ ? `this machine's ${branch} (${refs.localSha.slice(0, 8)}, created from the remote by an earlier checkout) is behind or apart from the remote's (${refs.remoteSha.slice(0, 8)}) — reset it to the remote's (git branch -f ${branch} <remote>/${branch}, from a checkout not on it) and re-run`
88
+ : `this machine has its own ${branch} (${refs.localSha.slice(0, 8)}) that differs from the remote's (${refs.remoteSha.slice(0, 8)}) — not a remote-built branch here`);
89
+ }
90
+ const head = String(refs.remoteSha).toLowerCase();
91
+ const shas = namedShas(comment.body);
92
+ if (!shas.some((s) => head.startsWith(s))) {
93
+ return no('head-moved', shas.length
94
+ ? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)} — the branch moved after it was handed off; ask its executor for a new hand-off`
95
+ : `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
96
+ }
97
+ let executor = null;
98
+ for (const n of issues) {
99
+ const live = claimsByIssue ? claimsByIssue[n] : null;
100
+ if (!live) return no('claims-unreadable', `#${n}'s comments could not be read — the executor's claim cannot be checked`);
101
+ const match = live.find((c) => c.branch === branch && c.login === comment.login && c.at < comment.createdAt);
102
+ if (!match) {
103
+ return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off — ` +
104
+ 'the hand-off must come from the party holding the claim');
105
+ }
106
+ if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
107
+ }
108
+ return { ok: true, issues, sha: refs.remoteSha, executor, url: String(url).trim() };
109
+ }
110
+
111
+ /** The squash trailer recording the door the issue set came through. */
112
+ function handoffTrailer(v) {
113
+ return v && v.ok ? `Colab-Handoff: ${v.url} @ ${String(v.sha).slice(0, 12)}` : '';
114
+ }
115
+
116
+ module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer };