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

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
@@ -49,6 +49,8 @@ const baseCiVerdict = require('./lib/base-ci-verdict');
49
49
  const treeGreen = require('./lib/tree-green');
50
50
  const verifyRuns = require('./lib/verify-runs');
51
51
  const ciWait = require('./lib/ci-wait'); // #495
52
+ const ciProfile = require('./lib/ci-profile'); // #559
53
+ const thresholdsLib = require('./lib/thresholds'); // #560
52
54
  const staleBase = require('./lib/stale-base');
53
55
  const dirtyOwner = require('./lib/dirty-owner');
54
56
  const scratchDirs = require('./lib/scratch-dirs');
@@ -63,8 +65,10 @@ const codec = require('./lib/codec');
63
65
  const machine = require('./lib/machine');
64
66
  const targetSync = require('./lib/ship-target-sync');
65
67
  const shipBatch = require('./lib/ship-batch');
68
+ const batchStats = require('./lib/batch-stats');
66
69
  const conflictMarkers = require('./lib/conflict-markers');
67
70
  const docsOnly = require('./lib/docs-only');
71
+ const configSet = require('./lib/config-set'); // #561
68
72
  const cureDiff = require('./lib/cure-diff');
69
73
  const codeowners = require('./lib/codeowners');
70
74
  const releasePolicy = require('./lib/release-policy');
@@ -283,8 +287,9 @@ function commentHost(repoAbs) {
283
287
  function myMachineId() { return machine.localMachine().id || null; }
284
288
 
285
289
  /**
286
- * Resolve the Claude session URL for this invocation: --session flag > COLAB_SESSION env >
287
- * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — typically a session URL.
290
+ * Resolve the session id for this invocation: --session flag > COLAB_SESSION env >
291
+ * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — any stable id for
292
+ * the session (a URL, a uuid…).
288
293
  *
289
294
  * The derived step exists for a person at a plain terminal, who has no session runtime and so no
290
295
  * id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
@@ -390,7 +395,7 @@ function warnWeakIdentity(session, sessionName, what, ref) {
390
395
  warn(`no --session or --session-name given — this ${what} will carry NO holder identity.`);
391
396
  warn(` A live hold's refusal can then only point at its process id, and this acquire will`);
392
397
  warn(` not be recognized as your own on a later re-acquire without one.`);
393
- if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <url>`);
398
+ if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <id>`);
394
399
  return;
395
400
  }
396
401
  // #326: a planner intent id is a deliberate, documented non-URL value — not a mistyped name.
@@ -401,16 +406,16 @@ function warnWeakIdentity(session, sessionName, what, ref) {
401
406
  // refused the caller's own hold when they later presented their REAL url. Warn, never
402
407
  // refuse: `requirePlaceIdentity` promises `<url-or-any-stable-id>`, so a bare stable id is
403
408
  // a blessed value and rejecting it would break that contract and every adopter using one.
404
- warn(`--session "${session}" does not look like a session URL or a session_… id — this ${what}`);
409
+ warn(`--session "${session}" does not look like a session id (a URL, a uuid, a session_… token) — this ${what}`);
405
410
  warn(` will record it verbatim. That is allowed (any stable id works), but if this is your`);
406
411
  warn(` session NAME you probably meant --session-name: a later 'colab place release'`);
407
- warn(` presenting your real URL will NOT match this value and will be refused (#306).`);
412
+ warn(` presenting your real id will NOT match this value and will be refused (#306).`);
408
413
  return;
409
414
  }
410
415
  if (!sessionName || session) return;
411
- warn(`session name "${sessionName}" recorded with NO session URL — this ${what} will read as owned`);
412
- warn(` but cannot be traced to a session. The name is display text; the URL is the join key.`);
413
- if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <url>`);
416
+ warn(`session name "${sessionName}" recorded with NO session id — this ${what} will read as owned`);
417
+ warn(` but cannot be traced to a session. The name is display text; the id is the join key.`);
418
+ if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <id>`);
414
419
  }
415
420
 
416
421
  /**
@@ -469,8 +474,8 @@ function identityCell(sessionName, session) {
469
474
  /** Print the `(!)` legend under a table, only when at least one row carries a half-identity. */
470
475
  function identityLegend(entries) {
471
476
  if (!entries.some((e) => e && e.sessionName && !e.session)) return;
472
- print(' (!) session NAME with no session URL — reads as owned, links to nothing.');
473
- print(' Repair: colab worktree tag <worktree> --session <url>');
477
+ print(' (!) session NAME with no session id — reads as owned, links to nothing.');
478
+ print(' Repair: colab worktree tag <worktree> --session <id>');
474
479
  }
475
480
 
476
481
  /**
@@ -521,8 +526,9 @@ function localClaimConflicts(st, repoAbs, nums, wtName) {
521
526
 
522
527
  /**
523
528
  * #325 — the claim record every machine can read, whatever the tracker: a branch on the remote whose
524
- * name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run; `code-start`
525
- * pushes the branch the moment it is cut). Asked of the remote directly (`ls-remote`, no fetch), so a
529
+ * name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run), or — since
530
+ * #550 — the claim ref `refs/claims/<branch>` that `colab worktree new` pushes the moment it cuts
531
+ * (a ref no CI trigger watches; the branch itself follows at code-wrap). Asked of the remote directly (`ls-remote`, no fetch), so a
526
532
  * clone that has never fetched sees exactly what a fresh one would.
527
533
  *
528
534
  * `mode`:
@@ -557,7 +563,7 @@ function remoteClaimConflicts(st, repoAbs, nums) {
557
563
  for (const h of heads.heads) {
558
564
  const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
559
565
  if (!carried.length || ours(h.branch)) continue;
560
- for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
566
+ for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha, claimRef: !!h.claimRef });
561
567
  }
562
568
  return { mode: 'ok', remote, conflicts };
563
569
  }
@@ -666,13 +672,18 @@ function ghClaimConflicts(repoAbs, nums, myLogin, myHost, mySession, comps, myMa
666
672
  function printRefusal(localConf, ghConf, remoteConf = []) {
667
673
  process.stderr.write('✗ Refusing — one or more issues are already claimed:\n');
668
674
  for (const c of remoteConf) {
669
- process.stderr.write(` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
675
+ process.stderr.write(c.claimRef
676
+ ? ` #${c.num} remote: claim ref ${c.remote} ${git.claimRef(c.branch)} @ ${c.sha} carries it (branch not pushed yet), and it is not this machine's (#325, #550)\n`
677
+ : ` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
670
678
  }
671
679
  if (remoteConf.length) {
672
680
  const c = remoteConf[0];
673
- process.stderr.write(' That branch IS the claim — continue it rather than open a second one:\n');
674
- process.stderr.write(` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
681
+ process.stderr.write(` That ${c.claimRef ? 'claim ref' : 'branch'} IS the claim — continue it rather than open a second one:\n`);
682
+ process.stderr.write(c.claimRef
683
+ ? ` git fetch ${c.remote} ${git.claimRef(c.branch)}:refs/heads/${c.branch} && git worktree add <path> ${c.branch}\n`
684
+ : ` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
675
685
  process.stderr.write(` colab claim ${c.num} --worktree <name> --branch ${c.branch} --session <id> --force\n`);
686
+ if (c.claimRef) process.stderr.write(` A claim ref whose session is gone is stale — delete it: git push ${c.remote} --delete ${git.claimRef(c.branch)}\n`);
676
687
  }
677
688
  for (const c of localConf) {
678
689
  const h = c.holder;
@@ -709,7 +720,7 @@ function halfClaimText(c) {
709
720
  /** Announce exactly what --force overrides (a takeover is visible, never silent). */
710
721
  function printTakeover(localConf, ghConf, remoteConf = []) {
711
722
  for (const c of remoteConf) {
712
- print(` --force: taking over #${c.num} although branch ${c.remote}/${c.branch} @ ${c.sha} carries it (not this machine's)`);
723
+ print(` --force: taking over #${c.num} although ${c.claimRef ? `claim ref ${c.remote} ${git.claimRef(c.branch)}` : `branch ${c.remote}/${c.branch}`} @ ${c.sha} carries it (not this machine's)`);
713
724
  }
714
725
  for (const c of localConf) {
715
726
  const h = c.holder;
@@ -876,7 +887,8 @@ const HELP_CLAIM = `colab claim <issue> [<issue> ...] [options]
876
887
 
877
888
  Claim one or more GitHub issues so parallel sessions/agents don't collide.
878
889
  The claim RECORD every machine reads is a branch on the git remote carrying the issue number
879
- (\`colab worktree new\` pushes it the moment it is cut, #325). Also writes local state (fast path)
890
+ (\`colab worktree new\` records it the moment it is cut as the claim ref refs/claims/<branch>,
891
+ which no CI trigger watches — #325, #550). Also writes local state (fast path)
880
892
  and the tracker (the copy people read):
881
893
  gh issue edit N --add-assignee @me --add-label in-progress
882
894
  Remote unreachable → REFUSED (fail closed). Tracker unreachable → the claim stands and its tracker
@@ -918,7 +930,8 @@ Options:
918
930
  --branch <name> branch these claims are worked on. Default: none (null) — a claim held on
919
931
  the trunk checkout has no branch. Never the word "trunk": that is a role,
920
932
  and a record holding it resolves to no ref (refused, exit 1)
921
- --session <url> Claude session URL recorded on the claim + comment (default: COLAB_SESSION env).
933
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the claim + comment
934
+ (default: COLAB_SESSION env).
922
935
  MANDATORY when no --worktree is given (#242): a claim with no worktree takes
923
936
  the trunk-checkout place-claim, and a blank session can never be recognized
924
937
  as its own later re-acquire — refused (exit 1) before anything is read/written.
@@ -1842,7 +1855,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
1842
1855
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1843
1856
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
1844
1857
 
1845
- 1. fetches tags, picks the newest open candidate (never a hand-made or off-main one);
1858
+ 1. fetches tags, picks the newest open candidate — or the one --tag names (never a hand-made or
1859
+ off-main one);
1846
1860
  2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
1847
1861
  starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
1848
1862
  3. measures, and ends in exactly one state:
@@ -1868,14 +1882,17 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1868
1882
 
1869
1883
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
1870
1884
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
1871
- ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
1885
+ ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant human
1872
1886
 
1873
1887
  regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
1874
1888
  began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
1875
1889
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1890
+ cut-run the run that cut the candidate (in progress at the tag's date) concluded success — a
1891
+ cancelled publish refuses; an earlier green run at the commit that cut nothing never
1892
+ vouches for it (#566)
1876
1893
  trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1877
1894
  another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1878
- none red — required only where the final is automatic
1895
+ none red — required only where the final is automatic, or for an older --tag (#548)
1879
1896
 
1880
1897
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1881
1898
  the final equals every declared manifest version, its commit is on main (a shallow
@@ -1897,9 +1914,15 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1897
1914
  never tags: it stops at candidate-ready and posts the one command, number
1898
1915
  pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
1899
1916
  already-final exit 0 (nothing to do yet is the ordinary output)
1900
- --tag <rc> pin the candidate a human reviewed; refused unless it is the newest one
1917
+ --tag <rc> pin the candidate a human reviewed — the newest one, or any OLDER open candidate
1918
+ (#548). An older one is judged on its own clock exactly as --auto judges it: its
1919
+ own test period must have elapsed and trunk-green is read over its own window, on
1920
+ every row; release-hold and regressions as always. Newer candidates stay open
1921
+ for the next version — only versions below the final are closed as superseded
1901
1922
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
1902
- No field, flag or project.yml value lowers it, and it never shortens a test period
1923
+ No field, flag or project.yml value lowers it, and it never shortens a test period.
1924
+ Where the final is a human act the period is informational anyway, and
1925
+ release.test-period: 0d declares none at all (#549)
1903
1926
  --dry measure and report; open, post, tag and close nothing
1904
1927
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
1905
1928
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
@@ -1971,6 +1994,8 @@ function cmdReleaseFinalize(argv) {
1971
1994
  const newest = selection.kind === 'candidate' ? selection.candidate : null;
1972
1995
  // #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
1973
1996
  const walk = opts.auto && policy.effective.final === 'auto' && newest;
1997
+ // #548: --tag naming an older open candidate — judged on its own clock, as the walk judges it.
1998
+ const ownClock = walk || (selection.kind === 'candidate' && !!selection.older);
1974
1999
 
1975
2000
  // ---- the tracking records (one issue read for the whole run) ----
1976
2001
  const issues = readAllIssuesForSwitches(repoAbs);
@@ -2013,14 +2038,20 @@ function cmdReleaseFinalize(argv) {
2013
2038
  if (!trackings.has(cand.version)) trackings.set(cand.version, trackingFor(cand.version, { isCandidate: true }));
2014
2039
  const tracking = trackings.get(cand.version);
2015
2040
  const supersededHeld = records.filter((r) => r.state === 'OPEN' && r.held && r.version !== cand.version && !finals.has(r.version)).map((r) => r.number);
2016
- let rows;
2041
+ let rows; let rawRows;
2017
2042
  const conditions = measureCandidateConditions(repoAbs, {
2018
2043
  sha: cand.sha,
2019
2044
  lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }),
2020
2045
  at: `${cand.tag}@${shortSha(cand.sha)}`,
2021
- readRuns: () => { rows = releaseCut.withoutOwnWorkflow(git.ghRunsAtCommit(repoAbs, cand.sha)); return rows; }, // #425
2046
+ readRuns: () => { rawRows = git.ghRunsAtCommit(repoAbs, cand.sha); rows = releaseCut.withoutOwnWorkflow(rawRows); return rows; }, // #425
2022
2047
  issues,
2023
2048
  });
2049
+ // #566: only the run that CUT the candidate vouches for what it published — read from the rows
2050
+ // BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
2051
+ const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
2052
+ tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
2053
+ jobCount: (id) => git.ghRunJobCount(repoAbs, id),
2054
+ });
2024
2055
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
2025
2056
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2026
2057
  // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
@@ -2029,7 +2060,7 @@ function cmdReleaseFinalize(argv) {
2029
2060
  return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
2030
2061
  }));
2031
2062
  const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
2032
- periodStart: period.start, periodEnd: walk ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2063
+ periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2033
2064
  });
2034
2065
  const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
2035
2066
  const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
@@ -2044,7 +2075,7 @@ function cmdReleaseFinalize(argv) {
2044
2075
  }
2045
2076
  const verdict = releaseFinalize.decide({
2046
2077
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2047
- ci: conditions.ci, suite: conditions.suite, schema: conditions.schema, switches: conditions.switches,
2078
+ ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
2048
2079
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2049
2080
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2050
2081
  });
@@ -2108,7 +2139,7 @@ function cmdReleaseFinalize(argv) {
2108
2139
  const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2109
2140
  if (!opts.dry) {
2110
2141
  if (verdict.state === 'finalized') {
2111
- const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}`;
2142
+ const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2112
2143
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2113
2144
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2114
2145
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2130,7 +2161,9 @@ function cmdReleaseFinalize(argv) {
2130
2161
  const tNew = version0 ? trackings.get(version0) : null;
2131
2162
  if (newest && tNew && tNew.number) {
2132
2163
  const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2133
- comment(tNew.number, { candidate: newest.tag }, walk
2164
+ comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
2165
+ ? `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.`
2166
+ : ownClock
2134
2167
  ? `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\`).`
2135
2168
  : `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
2136
2169
  }
@@ -2147,12 +2180,14 @@ function cmdReleaseFinalize(argv) {
2147
2180
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2148
2181
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2149
2182
  if (tagged) announced = announceRelease(cand.version, cand.sha);
2150
- // Superseded records. Without --auto: every other open, unheld, non-final version (the newest one
2151
- // is the only one ever finalized). With --auto: only versions BELOW one just tagged — a newer
2152
- // version's candidates are still on their own clocks.
2153
- if (cand && (!walk || tagged)) {
2183
+ // Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
2184
+ // without --auto closed every other open version at once, because only the newest candidate could
2185
+ // ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
2186
+ // to stay open until a final above it exists — closing it earlier refuses that --tag ("closed but
2187
+ // not final"). A newer version's candidates are still on their own clocks either way.
2188
+ if (cand && tagged) {
2154
2189
  for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
2155
- && (!walk || releaseFinalize.compareVersions(x.version, cand.version) < 0))) {
2190
+ && releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
2156
2191
  comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
2157
2192
  close(r.number);
2158
2193
  }
@@ -2798,7 +2833,7 @@ function cmdGateHermetic(argv) {
2798
2833
  // neither, so there is nothing else in state.json a second solo attempt could collide with.
2799
2834
  // ---------------------------------------------------------------------------
2800
2835
 
2801
- const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <url>] [--session-name <name>]
2836
+ const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <id>] [--session-name <name>]
2802
2837
  colab solo --done [--repo <path>]
2803
2838
 
2804
2839
  Entry gate for solo flow (CONVENTIONS.md, Solo flow) — requires BOTH: this repo does not declare
@@ -3073,7 +3108,7 @@ function cmdSoloDone(repoAbs, doc) {
3073
3108
  // exactly `writes: isolated` — see writes-authority.js's `trunkDirectVetoed`)
3074
3109
  // ---------------------------------------------------------------------------
3075
3110
 
3076
- const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session URL] [--session-name N] [--force]
3111
+ const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session ID] [--session-name N] [--force]
3077
3112
 
3078
3113
  Path-scoped, machine-local hold on ONE checkout (CONVENTIONS.md, Place-claims) — what a shared
3079
3114
  trunk checkout needs on any repo that does not declare \`writes: isolated\` (the veto), and a
@@ -3891,12 +3926,26 @@ function migrationGrantReviewRecord(repoAbs, opts) {
3891
3926
  // #508: bind what was reviewed — the branch's migration files at the tip, by content. Same path
3892
3927
  // rule the ship gate fires on (newMigrations), against origin's trunk. A branch with no migration
3893
3928
  // to review gets no id and stays HEAD-bound.
3929
+ //
3930
+ // #563: and never silently fall back to HEAD binding. A grant posted without `migrations:` for a
3931
+ // branch that HAS migrations is voided by the very trunk sync ship demands — the cost #508 removed.
3932
+ // So every way this can fail to answer refuses instead: no trunk to diff against, a diff git
3933
+ // cannot compute (base or tip object missing here), or a tree it cannot read at the tip.
3894
3934
  const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
3935
+ if (!trunk) {
3936
+ throw new UserError("cannot resolve this repo's trunk from project.yml — a reviewer grant binds the branch's migration content against trunk, so nothing was posted. Declare `trunk:` in .github/project.yml, then re-run `colab migration-grant`");
3937
+ }
3895
3938
  const remote = git.remoteInfo(repoAbs).name || 'origin';
3896
- let base = trunk ? `${remote}/${trunk}` : null;
3897
- if (base && !git.git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], repoAbs).ok) base = trunk;
3898
- const migrations = base ? newMigrations(repoAbs, base, tip) : [];
3939
+ let base = `${remote}/${trunk}`;
3940
+ if (!git.git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], repoAbs).ok) base = trunk;
3941
+ const migrations = newMigrationsOrNull(repoAbs, base, tip);
3942
+ if (migrations === null) {
3943
+ throw new UserError(`cannot list "${opts.branch}"'s files against ${base} (git diff ${base}...${tip.slice(0, 12)} failed) — without that list the grant could not bind the migration content and would be voided by the next trunk sync; nothing was posted. Run \`git fetch ${remote} ${trunk} ${opts.branch}\`, then re-run \`colab migration-grant\``);
3944
+ }
3899
3945
  const contentId = migrationContentAt(repoAbs, migrations, tip);
3946
+ if (migrations.length > 0 && !contentId) {
3947
+ throw new UserError(`"${opts.branch}" carries ${migrations.length} migration file(s) (${migrations.join(', ')}) but their content id could not be computed at ${tip.slice(0, 12)} (git ls-tree failed) — a grant without it binds the HEAD alone and the next trunk sync voids it; nothing was posted. Run \`git fetch ${remote} ${opts.branch}\`, then re-run \`colab migration-grant\``);
3948
+ }
3900
3949
 
3901
3950
  const rec = {
3902
3951
  v: '1', role, reviewer: opts.reviewer, head: tip,
@@ -5235,7 +5284,8 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5235
5284
  <type>/, prefix or not; else the branch after its first '/')
5236
5285
  --trunk <name> override trunk branch
5237
5286
  --repo <path> repo root (default: git root of cwd)
5238
- --session <url> Claude session URL recorded on the worktree + its claims (env COLAB_SESSION)
5287
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the worktree +
5288
+ its claims (env COLAB_SESSION)
5239
5289
  --session-name <s> short human label for tables/messages (env COLAB_SESSION_NAME)
5240
5290
  --pid <n|none> the new worktree's place-claim liveness anchor (#288) — same meaning as
5241
5291
  \`colab claim\`'s --pid; default: auto-detect (env COLAB_PLACE_PID too)
@@ -5262,7 +5312,7 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5262
5312
  and state record in place for a retry, unless --force. Refuses if there are
5263
5313
  uncommitted TRACKED changes unless --force.
5264
5314
 
5265
- colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]
5315
+ colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]
5266
5316
  REPAIR session identity, and/or the recorded branch, on a worktree that already
5267
5317
  exists — and on every claim attached to it (claims hold their own copy of each
5268
5318
  field, and claims are what \`doctor\` reports and what \`ship\` unions by). Pass any
@@ -5580,23 +5630,30 @@ function cmdWorktreeNew(argv) {
5580
5630
  // rejected instead of overwriting. With issues to claim, a failed push takes nothing: the worktree
5581
5631
  // and the zero-commit branch this invocation just made are removed again, so no half-claim exists
5582
5632
  // anywhere. With no issues there is no claim to protect, and a failed push only warns.
5633
+ //
5634
+ // #550: what is pushed is the CLAIM REF `refs/claims/<branch>`, not the branch. A branch push fires
5635
+ // every CI `push` trigger, and at cut the branch IS trunk's commit — so each cut re-ran a suite
5636
+ // trunk had already passed (~27 % of one org's runs). A claim ref triggers nothing, and every
5637
+ // claim reader (`remoteHeads`) lists it beside the branches. The branch itself is first pushed at
5638
+ // code-wrap, when it has commits worth testing. The claim ref is deleted at `worktree rm`.
5583
5639
  const pushRemote = git.claimRemote(repoAbs);
5584
5640
  let pushed = false;
5585
5641
  if (pushRemote) {
5586
- const push = git.git(['push', '-u', pushRemote, `--force-with-lease=refs/heads/${branch}:`, branch], repoAbs, { timeoutMs: 120_000 });
5642
+ const claimRef = git.claimRef(branch);
5643
+ const push = git.pushClaimRef(repoAbs, pushRemote, branch);
5587
5644
  if (push.ok) {
5588
5645
  pushed = true;
5589
- print(` pushed ${branch} → ${pushRemote} (the claim record other machines read)`);
5646
+ print(` pushed ${claimRef} → ${pushRemote} (the claim record other machines read; not a branch, so no CI runs — the branch is pushed at code-wrap)`);
5590
5647
  } else {
5591
5648
  const why = String(push.stderr || '').split('\n').filter(Boolean).slice(-1)[0] || `exit ${push.code}`;
5592
5649
  if (issues.length) {
5593
5650
  git.git(['worktree', 'remove', '--force', wtPath], repoAbs);
5594
5651
  git.git(['branch', '-D', branch], repoAbs);
5595
- throw new UserError(`git push ${pushRemote} ${branch} failed (${why}) — claim NOT taken: the worktree and branch ` +
5596
- 'were removed again. The pushed branch is the claim record other machines read (#325); fix the push ' +
5597
- '(access, network, or a branch of that name another machine just created) and re-run.');
5652
+ throw new UserError(`git push ${pushRemote} ${claimRef} failed (${why}) — claim NOT taken: the worktree and branch ` +
5653
+ 'were removed again. The pushed claim ref is the record other machines read (#325, #550); fix the push ' +
5654
+ `(access, network, or a claim ref of that name another machine just created — \`git ls-remote ${pushRemote} ${claimRef}\`) and re-run.`);
5598
5655
  }
5599
- warn(`git push ${pushRemote} ${branch} failed (${why}) — worktree created, branch not on the remote yet`);
5656
+ warn(`git push ${pushRemote} ${claimRef} failed (${why}) — worktree created, no claim ref on the remote`);
5600
5657
  }
5601
5658
  }
5602
5659
 
@@ -5618,14 +5675,14 @@ function cmdWorktreeNew(argv) {
5618
5675
  }
5619
5676
 
5620
5677
  // 3. allocate ports + record worktree + claims (atomic)
5621
- // #325: if recording fails after the push above, take the pushed branch back off the remote —
5678
+ // #325: if recording fails after the push above, take the pushed claim ref back off the remote —
5622
5679
  // otherwise it would stand there as a claim record nothing on any machine owns, refusing every
5623
5680
  // later claim on these issues. (The local worktree is left as before this change.)
5624
5681
  let alloc;
5625
5682
  try {
5626
5683
  alloc = allocWorktreeRecord();
5627
5684
  } catch (e) {
5628
- if (pushed) git.git(['push', pushRemote, '--delete', branch], repoAbs, { timeoutMs: 120_000 });
5685
+ if (pushed) git.deleteClaimRef(repoAbs, pushRemote, branch);
5629
5686
  throw e;
5630
5687
  }
5631
5688
  function allocWorktreeRecord() { return state.mutate((st) => {
@@ -5854,6 +5911,19 @@ function cmdWorktreeRm(argv) {
5854
5911
 
5855
5912
  print(`✓ Removed worktree "${name}"`);
5856
5913
  if (removal.action === 'rm-rf') print(' (directory was a husk from an earlier interrupted removal — cleaned up directly)');
5914
+ // #550: the claim ref `worktree new` pushed is this worktree's claim record on the remote — release
5915
+ // it with the claims, or it would stand there refusing every later claim on these issue numbers from
5916
+ // another machine. Best effort: an absent ref is fine (never pushed, a pre-#550 worktree, or already
5917
+ // gone), a failed delete only warns with the command, and nothing above is undone for it.
5918
+ if (wt.branch) {
5919
+ let claimRemoteName = null;
5920
+ try { claimRemoteName = git.claimRemote(repoAbs); } catch { claimRemoteName = null; }
5921
+ if (claimRemoteName) {
5922
+ const d = git.deleteClaimRef(repoAbs, claimRemoteName, wt.branch);
5923
+ if (d.ok && !d.absent) print(` deleted claim ref ${claimRemoteName} ${git.claimRef(wt.branch)}`);
5924
+ else if (!d.ok) warnDeferred(`could not delete claim ref ${claimRemoteName} ${git.claimRef(wt.branch)} (${String(d.stderr || '').split('\n')[0]}) — delete it by hand: git push ${claimRemoteName} --delete ${git.claimRef(wt.branch)}`);
5925
+ }
5926
+ }
5857
5927
  // #114: this line used to report `removed.claims` — the LOCAL registry mutation, which cannot
5858
5928
  // fail for a network reason and so always read as full success. Report what the tracker actually
5859
5929
  // did instead, and name what it didn't.
@@ -5886,7 +5956,7 @@ function cmdWorktreeRm(argv) {
5886
5956
  }
5887
5957
 
5888
5958
  /**
5889
- * `colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]` — repair
5959
+ * `colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]` — repair
5890
5960
  * session identity, and/or the recorded branch, on an ALREADY-created worktree. Before this, the
5891
5961
  * only fix was hand-editing ~/.colab/state.json.
5892
5962
  *
@@ -5920,7 +5990,7 @@ function cmdWorktreeTag(argv) {
5920
5990
  const sessionName = String(opts.sessionName || '').trim();
5921
5991
  const branch = String(opts.branch || '').trim();
5922
5992
  if (!session && !sessionName && !branch) {
5923
- throw new UserError('Nothing to tag — pass --session <url>, --session-name <s>, and/or --branch <b>');
5993
+ throw new UserError('Nothing to tag — pass --session <id>, --session-name <s>, and/or --branch <b>');
5924
5994
  }
5925
5995
  if (!state.loadState().worktrees[name]) {
5926
5996
  throw new UserError(`No worktree "${name}" in state (list them with: colab worktrees)`);
@@ -7598,7 +7668,7 @@ function cmdLabels(argv) {
7598
7668
  // config (show / manage the aggregation inputs)
7599
7669
  // ---------------------------------------------------------------------------
7600
7670
 
7601
- const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|set <key> <value>]
7671
+ 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>]
7602
7672
 
7603
7673
  show print resolved config, file paths, and the aggregated reserved set
7604
7674
  add-repo <path> add a repo root to scan for .github/project.yml reserved ports
@@ -7606,14 +7676,24 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
7606
7676
  add-reserved-file <path> add a machine-local reserved-ports file (~ is expanded); its ports join
7607
7677
  the reserved set (lenient parse: whitespace ints per line, # comments)
7608
7678
  rm-reserved-file <path> remove a reserved-ports file
7679
+ add-notify-url <url> add one more event receiver to notifyUrl (a second local observer) —
7680
+ existing entries are kept; one URL stays stored as a plain string
7681
+ rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
7609
7682
  set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
7610
7683
  claimIdentity
7684
+ set <tuning-key> <value> --evidence "<why>"
7685
+ a kebab-case key is this REPO's .github/project.yml, not this machine (#561):
7686
+ one tuning value, committed on a short branch, shippable with no issue —
7687
+ see: colab config set ship-batch --help
7611
7688
 
7612
7689
  notifyUrl is OPTIONAL and off by default: unset, colab makes no network call of its own. Set it to
7613
7690
  an http(s) endpoint and claim / release / ship / worktree new / worktree rm each push one small
7614
7691
  best-effort JSON event as they succeed — fire-and-forget, never retried, never able to fail or slow
7615
7692
  the command that triggered it. Observers already poll this state file; the push only sharpens the
7616
7693
  timestamp. Unset it again with: colab config set notifyUrl ""
7694
+ notifyUrl may hold SEVERAL receivers (#546) — every event goes to each, through its own detached
7695
+ child, so one dead receiver never costs another its event. \`set notifyUrl <url>\` replaces the
7696
+ whole value with one URL; add-notify-url / rm-notify-url change one entry and leave the rest alone.
7617
7697
 
7618
7698
  journal is OPTIONAL and off by default: unset, colab writes no journal file at all. Set it and every
7619
7699
  state transition and every invocation is appended to ~/.colab/journal.jsonl — one JSON object per
@@ -7632,6 +7712,91 @@ changes on resume makes that session's own earlier claim comment read as a diffe
7632
7712
  it will yield to itself. Unset it again with: colab config set claimIdentity ""
7633
7713
  `;
7634
7714
 
7715
+ // config set <tuning-key> (#561) — one TUNING value of this repo's .github/project.yml, committed on
7716
+ // a short branch without touching any checkout, shippable by `colab ship` with no issue.
7717
+ const HELP_CONFIG_SET_DESCRIPTOR = `colab config set <tuning-key> <value> --evidence "<why>" [--repo <path>] [--no-push] [--dry]
7718
+
7719
+ Change ONE tuning value of this repo's .github/project.yml (#561). Tuning keys:
7720
+ ${configSet.TUNING_KEYS.filter((k) => k !== 'thresholds').join(', ')}, thresholds.<name>
7721
+
7722
+ The value is validated by the parser every reader of that key uses (the same verdict \`colab ship\`
7723
+ computes), then committed on top of a freshly fetched <remote>/<trunk> as branch
7724
+ chore/tune-<key> — with no checkout touched and no issue. The subject is
7725
+ \`chore(project): <key> <old> → <new>\`; --evidence (required) goes in the body, which the squash
7726
+ carries, so the reason for the number lives in trunk's history.
7727
+
7728
+ Then: wait for the branch's CI (\`colab ci-wait --sha <sha> --branch <branch>\`) and
7729
+ \`colab ship --branch <branch>\`. Ship computes the TUNING-ONLY class from the diff — it is never
7730
+ asserted — and, like docs-only (#345), it opens the autonomy gate on a repo without auto-trunk.
7731
+ Every other precondition still applies.
7732
+
7733
+ Never on this path (they grant authority or change what deploys): ${configSet.AUTHORITY_KEYS.join(', ')}.
7734
+
7735
+ --evidence <text> the measurement behind the number (required)
7736
+ --no-push create the branch locally only
7737
+ --dry print the edit and the verdict; create nothing`;
7738
+
7739
+ function cmdConfigSetDescriptor(argv) {
7740
+ const opts = parseArgs(argv, {
7741
+ values: { '--repo': 'repo', '--evidence': 'evidence' },
7742
+ flags: { '--no-push': 'noPush', '--dry': 'dry', '-h': 'help', '--help': 'help' },
7743
+ });
7744
+ if (opts.help) return print(HELP_CONFIG_SET_DESCRIPTOR);
7745
+ const [key, value] = opts._ || [];
7746
+ if (!key || value === undefined) throw new UserError('config set needs <tuning-key> <value> — see: colab config set ship-batch --help');
7747
+ const kp = configSet.parseKeyPath(key);
7748
+ if (kp.problem) throw new UserError(kp.problem);
7749
+ if (!opts.dry && !String(opts.evidence || '').trim()) {
7750
+ throw new UserError('--evidence "<why>" is required — the measurement behind the number goes in the commit body (#561); re-run with --evidence "<what you measured>"');
7751
+ }
7752
+ const repoAbs = resolveRepo(opts);
7753
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
7754
+ if (!trunk) throw new UserError('could not determine trunk — add `trunk:` to .github/project.yml (or run `colab adopt`), then re-run');
7755
+ const remote = git.remoteFor(repoAbs);
7756
+ const f = git.git(['fetch', remote, trunk], repoAbs);
7757
+ if (!f.ok) throw new UserError(`could not fetch ${remote}/${trunk} — nothing created (${f.stderr.split('\n')[0]}); re-run once \`git fetch ${remote} ${trunk}\` succeeds`);
7758
+ const baseRef = `${remote}/${trunk}`;
7759
+ const baseSha = (git.git(['rev-parse', `refs/remotes/${baseRef}`], repoAbs).stdout || '').trim();
7760
+ if (!baseSha) throw new UserError(`${baseRef} does not resolve after the fetch — check \`git ls-remote ${remote} ${trunk}\` and re-run`);
7761
+ const text = configSet.descriptorAt(repoAbs, baseSha);
7762
+ if (text === null) throw new UserError(`could not read ${configSet.DESCRIPTOR} at ${baseRef} — see why with \`git show ${baseRef}:${configSet.DESCRIPTOR}\``);
7763
+ if (text === '') throw new UserError(`${baseRef} has no ${configSet.DESCRIPTOR} — adopt the handbook first: \`colab adopt\``);
7764
+ const edit = configSet.editText(text, kp, value);
7765
+ if (edit.problem) throw new UserError(edit.problem);
7766
+ const name = [kp.top, kp.sub].filter(Boolean).join('.');
7767
+ if (edit.text === text) { print(`${name} is already ${value} on ${baseRef} — nothing to change`); return 0; }
7768
+ // The SAME verdict ship will compute on this diff — so a value ship would refuse is refused here.
7769
+ const verdict = configSet.classify({
7770
+ entries: [{ path: configSet.DESCRIPTOR, oldMode: '100644', newMode: '100644', binary: false }],
7771
+ baseText: text, headText: edit.text,
7772
+ });
7773
+ if (!verdict.tuning) throw new UserError(`refused: ${verdict.reason} — pick a valid value (\`colab config set ${name} --help\`)`);
7774
+ const branch = configSet.branchName(kp);
7775
+ if (git.branchExists(repoAbs, branch, remote)) {
7776
+ throw new UserError(`branch ${branch} already exists — ship it with \`colab ship --branch ${branch}\`, or delete it with \`git push ${remote} --delete ${branch}\` and \`git branch -D ${branch}\``);
7777
+ }
7778
+ const message = configSet.commitMessage(kp, edit.old, value, opts.evidence || '(dry run)');
7779
+ print(`config set ${shortRepo(repoAbs)} · ${name}: ${edit.old === null ? '(unset)' : edit.old} → ${value}`);
7780
+ print(` verdict: ${verdict.reason}`);
7781
+ print(` branch: ${branch} (base ${baseRef} @ ${shortSha(baseSha)})`);
7782
+ if (opts.dry) { print(' [DRY RUN] nothing created.'); return 0; }
7783
+ const c = configSet.commitOnBranch(repoAbs, { baseSha, text: edit.text, message, branch });
7784
+ if (!c.ok) throw new UserError(`could not create the commit: ${c.error} — nothing was created; a human must read the git error above before re-running`);
7785
+ print(` commit: ${shortSha(c.sha)} ${message.split('\n')[0]}`);
7786
+ if (opts.noPush) {
7787
+ print(` not pushed (--no-push). Push it, wait for CI, then: colab ship --branch ${branch}`);
7788
+ return 0;
7789
+ }
7790
+ const p = git.git(['push', remote, `refs/heads/${branch}:refs/heads/${branch}`], repoAbs);
7791
+ if (!p.ok) {
7792
+ warn(`push failed — the branch exists locally only: ${p.stderr.split('\n')[0]}`);
7793
+ return 1;
7794
+ }
7795
+ print(` pushed: ${remote}/${branch}`);
7796
+ print(`Next: colab ci-wait --sha ${c.sha} --branch ${branch} && colab ship --branch ${branch}`);
7797
+ return 0;
7798
+ }
7799
+
7635
7800
  function cmdConfig(argv) {
7636
7801
  const sub = argv[0];
7637
7802
  const cfg = state.loadConfig();
@@ -7670,6 +7835,26 @@ function cmdConfig(argv) {
7670
7835
  cfg.reservedFiles = (cfg.reservedFiles || []).filter((f) => f !== argv[1]);
7671
7836
  state.saveConfig(cfg); print(`reservedFiles: ${cfg.reservedFiles.join(', ') || '(none)'}`); return 0;
7672
7837
  }
7838
+ if (sub === 'add-notify-url' || sub === 'rm-notify-url') {
7839
+ // #546: notifyUrl is a string or a list. These change ONE entry and leave every other exactly as
7840
+ // it was, so a second observer is added without hand-editing JSON and without rewriting the first.
7841
+ const u = (argv[1] || '').trim();
7842
+ if (!u) throw new UserError(`${sub} needs a URL — try: colab config ${sub} http://127.0.0.1:<port>/api/events`);
7843
+ const urls = notify.configuredUrls(cfg);
7844
+ if (sub === 'add-notify-url') {
7845
+ 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, '')}`);
7846
+ if (!urls.includes(u)) urls.push(u);
7847
+ } else {
7848
+ if (!urls.includes(u)) throw new UserError(`notifyUrl has no entry ${u} — see the entries with: colab config show`);
7849
+ urls.splice(urls.indexOf(u), 1);
7850
+ }
7851
+ const v = notify.storedNotifyUrl(urls);
7852
+ if (v === undefined) delete cfg.notifyUrl; else cfg.notifyUrl = v;
7853
+ state.saveConfig(cfg);
7854
+ print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
7855
+ return 0;
7856
+ }
7857
+ if (sub === 'set' && argv[1] && configSet.isDescriptorKey(argv[1])) return cmdConfigSetDescriptor(argv.slice(1)); // #561
7673
7858
  if (sub === 'set') {
7674
7859
  const [k, v] = [argv[1], argv[2]];
7675
7860
  if (!k || v === undefined) throw new UserError('set needs <key> <value>');
@@ -8381,7 +8566,9 @@ async function askMenu(rl, axis, promptFn) {
8381
8566
  if (resolved.ok) return resolved;
8382
8567
  process.stdout.write(` ${resolved.message}\n`);
8383
8568
  }
8384
- throw new UserError(`${axis}: no valid answer after one re-prompt`);
8569
+ throw new UserError(`${axis}: no valid answer after one re-prompt — nothing was written. Run \`colab adopt --axis ${axis}\` ` +
8570
+ `to be asked again, or pass the value directly: \`colab adopt ${axis === 'tier' ? '--deploy' : `--${axis}`} <value>\` ` +
8571
+ `(\`colab adopt --help\` lists them).`);
8385
8572
  }
8386
8573
 
8387
8574
  /**
@@ -8441,7 +8628,10 @@ async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
8441
8628
  if (!problem) { chosen = resolved; break; }
8442
8629
  process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
8443
8630
  }
8444
- if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
8631
+ // #532: this refusal comes after a long interaction, so it names the way through, not just the stop.
8632
+ if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt — nothing was written. ' +
8633
+ 'Each "✗" above says why its value was refused. Run `colab adopt --axis exposure` and pick a value it accepts, ' +
8634
+ 'or `colab adopt --exposure <value>` non-interactively; choosing "skip" leaves exposure unanswered for now.');
8445
8635
  if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
8446
8636
  answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
8447
8637
  } else {
@@ -9771,8 +9961,14 @@ function trustAt(repoAbs, ref) {
9771
9961
  * gated by it, and a branch that deletes trunk's declaration is still gated by trunk's.
9772
9962
  */
9773
9963
  function newMigrations(mainRoot, trunk, branch) {
9964
+ return newMigrationsOrNull(mainRoot, trunk, branch) || [];
9965
+ }
9966
+
9967
+ /** newMigrations, but null — not [] — when git cannot compute the diff (#563): the grant write path
9968
+ * must tell "no migrations" from "could not look", and refuses on the second. */
9969
+ function newMigrationsOrNull(mainRoot, trunk, branch) {
9774
9970
  const r = git.git(['diff', '--name-only', `${trunk}...${branch}`], mainRoot);
9775
- if (!r.ok) return [];
9971
+ if (!r.ok) return null;
9776
9972
  const declared = migrationPaths.unionPaths(projectDoc(mainRoot), projectDocAt(mainRoot, trunk), projectDocAt(mainRoot, branch));
9777
9973
  return r.stdout.split('\n').filter(Boolean).filter((f) => migrationPaths.isMigrationPath(f, declared));
9778
9974
  }
@@ -10046,6 +10242,7 @@ promotes is an integration event of the same weight as a promotion, and stays hu
10046
10242
 
10047
10243
  Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
10048
10244
  a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
10245
+ or tuning-only (#561)
10049
10246
  — or a person runs ship through the human door (#525): a confirmed interactive
10050
10247
  terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
10051
10248
  b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
@@ -10222,6 +10419,14 @@ auto-trunk). The row reads "docs-only (N files) — autonomy exception", and --d
10222
10419
  \`autonomyGate: { via, docsOnly }\`. After B0 sync the diff is measured again before the squash.
10223
10420
  Every other precondition is unchanged. No flag, env var or project.yml field widens the list.
10224
10421
 
10422
+ TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
10423
+ diff changes .github/project.yml ALONE, every changed line inside a tuning key (ship-batch,
10424
+ ship-batch-wait, ci-wait-factor, thresholds) and every moved value valid; never with an authority
10425
+ key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
10426
+ release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
10427
+ writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
10428
+ adds \`autonomyGate.tuning\`. Re-measured after B0 sync like docs-only.
10429
+
10225
10430
  TRUNK-DIRECT — \`colab ship --direct\` (#302). A unit committed straight to trunk has no branch and
10226
10431
  no worktree, so neither door above can find it, and evidence-close's own detection cannot fire
10227
10432
  (\`landed\` is \`unknown\` when base === branch). --direct is its close path: the claims are this
@@ -10278,6 +10483,12 @@ at build, added since) is NOT landed with it — the command names both lists an
10278
10483
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10279
10484
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10280
10485
  Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
10486
+ PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
10487
+ unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10488
+ ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10489
+ since the member became ready (its head CI's last update, else its head commit's date) — then the same
10490
+ call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10491
+ --batch with all of them. A single named branch is accepted only when the field is set.
10281
10492
 
10282
10493
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10283
10494
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -10749,6 +10960,37 @@ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
10749
10960
  detail: `none — ${at} has no repo-owned workflow (#482), so the branch's own run decides, and ${ownAt} ${why}${excludedRunsNote(r.run)}` };
10750
10961
  }
10751
10962
 
10963
+ /**
10964
+ * The verifying-runs policy every CI read uses (#503), plus the lost-push rescue's resolver (#567):
10965
+ * the names of the workflows whose definition AT THAT SHA is triggered by a branch push or a pull
10966
+ * request. Lazy — called only when a `workflow_dispatch` run has no push sibling — and fail-closed:
10967
+ * a sha that is not local, or a tree that cannot be read, yields null and the run stays set aside.
10968
+ */
10969
+ function verifyingPolicy(repoAbs) {
10970
+ return { ...verifyRuns.parsePolicy(projectDoc(repoAbs)), dispatchVerifies: (sha) => pushVerifiedWorkflowsAt(repoAbs, sha) };
10971
+ }
10972
+
10973
+ function pushVerifiedWorkflowsAt(repoAbs, sha) {
10974
+ if (!sha) return null;
10975
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
10976
+ // Not local yet (another machine landed it): one fetch of that commit, then fail closed.
10977
+ git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
10978
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
10979
+ }
10980
+ const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
10981
+ if (!ls.ok) return null;
10982
+ const names = [];
10983
+ for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
10984
+ const rel = `.github/workflows/${f}`;
10985
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
10986
+ if (!show.ok) continue;
10987
+ const t = verifyRuns.workflowTriggers(show.stdout);
10988
+ // GitHub names a workflow with no `name:` by its file path.
10989
+ if (t && t.verifiesBranches) names.push(t.name || rel);
10990
+ }
10991
+ return names;
10992
+ }
10993
+
10752
10994
  /** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
10753
10995
  function trunkWorkflowFiles(repoAbs, sha) {
10754
10996
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
@@ -10779,7 +11021,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10779
11021
  if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
10780
11022
  // #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
10781
11023
  // aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
10782
- const readOpts = { verifying: verifyRuns.parsePolicy(projectDoc(repoAbs)) };
11024
+ const readOpts = { verifying: verifyingPolicy(repoAbs) };
10783
11025
  let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
10784
11026
  let via = target;
10785
11027
  if (run && run.status === 'none' && target !== trunk) {
@@ -10805,10 +11047,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10805
11047
  // (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
10806
11048
  // never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
10807
11049
  if (run.status === 'none' && target === trunk) {
10808
- const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
11050
+ // #559: the grace is the repo's measured push→run lag when there is one — read from cache, never fetched here.
11051
+ const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
10809
11052
  if (fresh.fresh) {
10810
11053
  verdict = { ok: false, class: SELF_CLEARING,
10811
- detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
11054
+ detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${Math.round(fresh.graceMinutes * 10) / 10}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
10812
11055
  }
10813
11056
  }
10814
11057
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -10879,7 +11122,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
10879
11122
  */
10880
11123
  function classifyCiRun(repoAbs, run, at) {
10881
11124
  const v = classifyCiRunRaw(repoAbs, run, at);
10882
- return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) };
11125
+ return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) };
10883
11126
  }
10884
11127
 
10885
11128
  /**
@@ -10921,7 +11164,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
10921
11164
  // Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
10922
11165
  // shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
10923
11166
  const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
10924
- const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount });
11167
+ // #559: wedge age and zero-jobs floor follow the repo's measured CI (cached profile; bootstrap = 6h / 2m).
11168
+ const th = ciProfileFor(repoAbs).th;
11169
+ const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount }, { wedgeAgeSec: th.wedgeAgeSec, zeroJobsFloorSec: th.zeroJobsFloorSec });
10925
11170
  if (wedge.wedged) {
10926
11171
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
10927
11172
  }
@@ -11690,7 +11935,8 @@ function cmdShipDryJson(opts) {
11690
11935
 
11691
11936
  // ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
11692
11937
  const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
11693
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
11938
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
11939
+ () => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
11694
11940
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
11695
11941
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
11696
11942
 
@@ -12571,23 +12817,33 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
12571
12817
  * caller asserts nothing. `readDocsOnly` is a thunk, so an auto-trunk repo never pays for the
12572
12818
  * diff read. Every other precondition is untouched — this relaxes the autonomy gate, not the checks.
12573
12819
  *
12574
- * Returns `{ ok, via: 'auto-trunk'|'docs-only'|null, declared, docsOnly: verdict|null, detail }`.
12820
+ * #561 adds the TUNING-ONLY class beside it: a diff `lib/config-set.js` classifies as one or more
12821
+ * tuning keys of .github/project.yml with valid values, and nothing else. `readTuning` is a thunk
12822
+ * too, consulted only when the change is not docs-only; a branchless (trunk-direct) door passes none.
12823
+ *
12824
+ * Returns `{ ok, via: 'auto-trunk'|'docs-only'|'tuning'|'human'|null, declared, docsOnly: verdict|null,
12825
+ * tuning: verdict|null, detail }`.
12575
12826
  */
12576
- function shipAutonomyGate(doc, readDocsOnly, door = null) {
12827
+ function shipAutonomyGate(doc, readDocsOnly, door = null, readTuning = null) {
12577
12828
  const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
12578
- if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
12829
+ if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, tuning: null, human: null, detail: 'auto-trunk' };
12579
12830
  const verdict = readDocsOnly();
12580
12831
  if (verdict.docsOnly) {
12581
- return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
12832
+ return { ok: true, via: 'docs-only', declared, docsOnly: verdict, tuning: null, human: null, detail: `${verdict.reason} — autonomy exception` };
12833
+ }
12834
+ const tuning = readTuning ? readTuning() : null;
12835
+ if (tuning && tuning.tuning) {
12836
+ return { ok: true, via: 'tuning', declared, docsOnly: verdict, tuning, human: null, detail: `${tuning.reason} — autonomy exception (#561)` };
12582
12837
  }
12583
12838
  // #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.
12839
+ // after docs-only and tuning, so either keeps its own (agent-usable) door and record.
12585
12840
  if (door && door.open) {
12586
- return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
12841
+ return { ok: true, via: 'human', declared, docsOnly: verdict, tuning, human: door,
12587
12842
  detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
12588
12843
  }
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'})` };
12844
+ return { ok: false, via: null, declared, docsOnly: verdict, tuning, human: door,
12845
+ detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; ` +
12846
+ `${tuning ? `not tuning-only: ${tuning.reason}; ` : ''}human door closed: ${door ? door.why : 'not offered'})` };
12591
12847
  }
12592
12848
 
12593
12849
  /** #525: the human-door refusal lines — what a person runs, never just "a human must". */
@@ -12646,8 +12902,10 @@ function shipHumanDoorGo(gate, opts, what) {
12646
12902
  function autonomyGatePayload(gate) {
12647
12903
  // #525: `human` is additive and present only when the human door was consulted, so an
12648
12904
  // 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 };
12905
+ // #561: `tuning` likewise — present only when the tuning class was consulted.
12906
+ const base = { via: gate.via, docsOnly: gate.docsOnly };
12907
+ if (gate.tuning) base.tuning = gate.tuning;
12908
+ return gate.human ? { ...base, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } } : base;
12651
12909
  }
12652
12910
 
12653
12911
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
@@ -12734,11 +12992,13 @@ function cmdShip(argv) {
12734
12992
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
12735
12993
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
12736
12994
  const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
12737
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12995
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
12996
+ () => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
12738
12997
  if (!autonomyGate.ok) {
12739
12998
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12740
12999
  process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12741
13000
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
13001
+ if (autonomyGate.tuning) process.stderr.write(` Nor the tuning-only class (#561): ${autonomyGate.tuning.reason}.\n`);
12742
13002
  process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
12743
13003
  return 1;
12744
13004
  }
@@ -13231,6 +13491,14 @@ function cmdShip(argv) {
13231
13491
  return 1;
13232
13492
  }
13233
13493
  }
13494
+ if (autonomyGate.via === 'tuning') {
13495
+ const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
13496
+ if (!again.tuning) {
13497
+ cleanupEphemeral();
13498
+ process.stderr.write(`✗ B1: the tuning-only class (#561) no longer holds after B0 sync — ${again.reason}. A human must trigger Phase B. Nothing pushed.\n`);
13499
+ return 1;
13500
+ }
13501
+ }
13234
13502
 
13235
13503
  // #350: B0 may have brought in paths (a pre-ship hook's regenerated files). The approval covered
13236
13504
  // the core paths the table listed; a core path it did not list was never reviewed.
@@ -13836,7 +14104,10 @@ function cmdShipBatch(opts) {
13836
14104
  if (String(doc.autonomy || '') !== 'auto-trunk') {
13837
14105
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
13838
14106
  }
13839
- if (members.length < 2) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
14107
+ // #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
14108
+ const waitCfg = shipBatch.parseShipBatchWait(doc);
14109
+ if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
14110
+ if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
13840
14111
  if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
13841
14112
 
13842
14113
  const remote = git.remoteFor(repoAbs);
@@ -13975,6 +14246,22 @@ function cmdShipBatch(opts) {
13975
14246
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
13976
14247
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
13977
14248
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14249
+ if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14250
+ // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14251
+ // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14252
+ const lone = selected[0];
14253
+ const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
14254
+ const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
14255
+ const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
14256
+ if (pw.wait) {
14257
+ print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
14258
+ print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14259
+ print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
14260
+ return 3;
14261
+ }
14262
+ const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
14263
+ return serial(`1 member can join and no partner arrived — ${why}`);
14264
+ }
13978
14265
  if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
13979
14266
 
13980
14267
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
@@ -13996,9 +14283,9 @@ function cmdShipBatch(opts) {
13996
14283
  // regenerated by .colab/hooks/pre-ship, never hand-merged and never a reason to leave the batch.
13997
14284
  // Only an overlap outside `generated:` (or no hook to regenerate with) drops the member.
13998
14285
  const nonGen = unmerged.filter((f) => !isGeneratedPath(f, generated));
13999
- let why = null;
14000
- if (nonGen.length) why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`;
14001
- else if (!hasPreShip) why = `conflicts with the members already in only in generated file(s) (${unmerged.join(', ')}), but there is no .colab/hooks/pre-ship to regenerate them — next batch`;
14286
+ let why = null, cls = null;
14287
+ if (nonGen.length) { why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`; cls = 'conflict'; }
14288
+ else if (!hasPreShip) { cls = 'generated-no-hook'; why = `conflicts with the members already in only in generated file(s) (${unmerged.join(', ')}), but there is no .colab/hooks/pre-ship to regenerate them — next batch`; }
14002
14289
  else {
14003
14290
  const hk = runHook(repoAbs, 'pre-ship', {
14004
14291
  wtPath: dir, name: m.branch, branch: m.branch, ports: [], trunk, base: trunk,
@@ -14009,24 +14296,26 @@ function cmdShipBatch(opts) {
14009
14296
  // state, so `left` reads empty — read the staged content itself before trusting it.
14010
14297
  const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
14011
14298
  if (!hk.ran || !hk.ok || left.length) {
14299
+ cls = 'hook-failed';
14012
14300
  why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
14013
14301
  } else if (markers.length) {
14302
+ cls = 'hook-markers';
14014
14303
  why = `.colab/hooks/pre-ship exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} on the combined head — treated as a failing hook, next batch`;
14015
14304
  } else regenerated = unmerged;
14016
14305
  }
14017
14306
  if (why) {
14018
14307
  git.git(['reset', '--hard', 'HEAD'], dir);
14019
- dropped.push({ branch: m.branch, why });
14308
+ dropped.push({ branch: m.branch, sha: m.sha, cls, why });
14020
14309
  continue;
14021
14310
  }
14022
14311
  } else if (!sq.ok) {
14023
14312
  git.git(['reset', '--hard', 'HEAD'], dir);
14024
- dropped.push({ branch: m.branch, why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
14313
+ dropped.push({ branch: m.branch, sha: m.sha, cls: 'squash-failed', why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
14025
14314
  continue;
14026
14315
  }
14027
14316
  if (!git.git(['diff', '--cached', '--name-only'], dir).stdout.trim()) {
14028
14317
  git.git(['reset', '--hard', 'HEAD'], dir);
14029
- dropped.push({ branch: m.branch, why: 'stages nothing on top of the members already in' });
14318
+ dropped.push({ branch: m.branch, sha: m.sha, cls: 'empty', why: 'stages nothing on top of the members already in' });
14030
14319
  continue;
14031
14320
  }
14032
14321
  const closeIssues = m.report.closeIssues || [];
@@ -14038,14 +14327,25 @@ function cmdShipBatch(opts) {
14038
14327
  const inherited = msg && refsIssues.length ? squash.inheritedClosingKeywordConflicts(msg, refsIssues) : [];
14039
14328
  if (!msg || !coverage.ok || inherited.length) {
14040
14329
  git.git(['reset', '--hard', 'HEAD'], dir);
14041
- dropped.push({ branch: m.branch, why: !msg ? 'no commit of its own to take a squash subject from' : 'its composed message does not close exactly what it claims — ship it alone to see why' });
14330
+ dropped.push({ branch: m.branch, sha: m.sha, cls: 'message', why: !msg ? 'no commit of its own to take a squash subject from' : 'its composed message does not close exactly what it claims — ship it alone to see why' });
14042
14331
  continue;
14043
14332
  }
14044
14333
  const c = git.run('git', ['commit', '-q', '-m', msg], { cwd: dir });
14045
- if (!c.ok) { git.git(['reset', '--hard', 'HEAD'], dir); dropped.push({ branch: m.branch, why: `commit failed: ${git.gitFailureLine(c.stderr)}` }); continue; }
14334
+ if (!c.ok) { git.git(['reset', '--hard', 'HEAD'], dir); dropped.push({ branch: m.branch, sha: m.sha, cls: 'commit-failed', why: `commit failed: ${git.gitFailureLine(c.stderr)}` }); continue; }
14046
14335
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
14047
14336
  }
14048
14337
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
14338
+ // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14339
+ // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14340
+ // Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
14341
+ if (dropped.length && built.length >= 2) {
14342
+ const last = built[built.length - 1];
14343
+ const cur = git.git(['log', '-1', '--format=%B'], dir);
14344
+ const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
14345
+ const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
14346
+ if (am.ok) last.commit = git.git(['rev-parse', 'HEAD'], dir).stdout;
14347
+ else warn(`could not record the dropped member(s) on the batch head: ${git.gitFailureLine(am.stderr)} — the drop is on this terminal only`);
14348
+ }
14049
14349
  for (const b of built.filter((x) => x.regenerated)) {
14050
14350
  print(` ↻ ${b.branch}: combined despite a generated-file overlap — ${b.regenerated.join(', ')} regenerated by .colab/hooks/pre-ship on the combined head (the combined run is the gate)`);
14051
14351
  }
@@ -14325,7 +14625,8 @@ function cmdTrunkCi(argv) {
14325
14625
  if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
14326
14626
  out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
14327
14627
  ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
14328
- ...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}) };
14628
+ ...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}),
14629
+ ...(r.run && Array.isArray(r.run.dispatchCounted) && r.run.dispatchCounted.length ? { dispatchCounted: r.run.dispatchCounted } : {}) };
14329
14630
  if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
14330
14631
  }
14331
14632
  if (opts.json) {
@@ -14379,6 +14680,110 @@ function trunkCiCache(repoAbs) {
14379
14680
  };
14380
14681
  }
14381
14682
 
14683
+ // ---- ci-profile (#559) ------------------------------------------------------------------------
14684
+ // Every CI wait bound derives from the repo's own measured CI duration (tools/lib/ci-profile.js).
14685
+ // The profile is cached per checkout in `<git common dir>/colab-ci-profile.json` for a day; the
14686
+ // thresholds are NOT cached — they are recomputed from the cached profile and the CURRENT
14687
+ // `ci-wait-factor`, so editing the factor applies at once with no refetch.
14688
+ const CI_PROFILE_TTL_DEFAULT_SEC = 24 * 3600;
14689
+ const CI_PROFILE_CACHE_V = 1;
14690
+
14691
+ function ciProfileTtlSec() {
14692
+ const env = process.env.COLAB_CI_PROFILE_TTL;
14693
+ return env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : CI_PROFILE_TTL_DEFAULT_SEC;
14694
+ }
14695
+
14696
+ function ciProfileCacheFile(repoAbs) {
14697
+ const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
14698
+ return dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-ci-profile.json') : null;
14699
+ }
14700
+
14701
+ /**
14702
+ * The repo's completed CI runs in the profile window — up to 3 pages of the whole list plus one page
14703
+ * of trunk pushes, so a branch-heavy repo still yields trunk samples. Returns `{ rows, runsRead }`,
14704
+ * or `{ error }` when the list cannot be read (the caller falls back, never fails a wait on it).
14705
+ */
14706
+ function fetchCiProfileRows(repoAbs, trunk, sinceIso) {
14707
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .name, .status, .conclusion, .run_attempt, .created_at, .updated_at, .head_commit.timestamp] | @json';
14708
+ const day = sinceIso.slice(0, 10);
14709
+ const paths = [1, 2, 3].map((n) => `repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&page=${n}`);
14710
+ paths.push(`repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&branch=${encodeURIComponent(trunk)}&event=push`);
14711
+ const seen = new Map();
14712
+ for (let i = 0; i < paths.length; i++) {
14713
+ const r = git.ghApi(repoAbs, [paths[i], '--jq', jq]);
14714
+ if (!r.ok) return { error: git.gitFailureLine(r.stderr) || 'gh api failed' };
14715
+ let n = 0;
14716
+ for (const line of String(r.stdout || '').split('\n')) {
14717
+ if (!line.trim()) continue;
14718
+ let a; try { a = JSON.parse(line); } catch (_) { continue; }
14719
+ n++;
14720
+ seen.set(a[0], {
14721
+ id: a[0], branch: a[1], sha: a[2], event: a[3], workflowName: a[4], status: a[5], conclusion: a[6],
14722
+ attempt: a[7], createdMs: Date.parse(a[8]), updatedMs: Date.parse(a[9]), headCommitMs: a[10] ? Date.parse(a[10]) : null,
14723
+ });
14724
+ }
14725
+ if (i < 3 && n < 100) i = 2; // a short page ends the paged list; the trunk page still runs
14726
+ }
14727
+ return { rows: [...seen.values()], runsRead: seen.size };
14728
+ }
14729
+
14730
+ const ciProfileMemo = new Map();
14731
+
14732
+ /**
14733
+ * The one reader: `{ profile, th, factor, kindTrunk, cache: { state, ageSec, fetchedAt }, notes }`.
14734
+ * `fetch`: 'never' (ship's hot path — never blocks a verdict on a history read) · 'if-stale' ·
14735
+ * 'always'. A stale cache is still used when a refetch fails: old measured data beats bootstrap.
14736
+ * TTL 0 (`COLAB_CI_PROFILE_TTL=0`) means no cache and no fetch — the bootstrap everywhere.
14737
+ */
14738
+ function ciProfileFor(repoAbs, { fetch = 'never' } = {}) {
14739
+ const memoKey = `${repoAbs}\u0000${fetch}`;
14740
+ if (ciProfileMemo.has(memoKey)) return ciProfileMemo.get(memoKey);
14741
+ const doc = projectDoc(repoAbs);
14742
+ const factor = ciProfile.parseFactor(doc);
14743
+ const trunk = resolveTrunk(repoAbs, doc);
14744
+ const notes = [];
14745
+ if (!factor.valid) notes.push(factor.reason);
14746
+ const ttl = ciProfileTtlSec();
14747
+ const file = ttl > 0 ? ciProfileCacheFile(repoAbs) : null;
14748
+ let entry = null;
14749
+ if (file) {
14750
+ try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { entry = null; }
14751
+ if (entry && (entry.v !== CI_PROFILE_CACHE_V || entry.trunk !== trunk || !entry.profile)) entry = null;
14752
+ }
14753
+ const ageSec = entry ? Math.max(0, Math.floor((Date.now() - entry.fetchedAt) / 1000)) : null;
14754
+ let state = entry ? (ageSec < ttl ? 'fresh' : 'stale') : 'none';
14755
+ const want = file && trunk && (fetch === 'always' || (fetch === 'if-stale' && state !== 'fresh'));
14756
+ if (want) {
14757
+ if (!isGhUsable(repoAbs)) notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — CI history not read`);
14758
+ else {
14759
+ const nowMs = Date.now();
14760
+ const sinceMs = nowMs - ciProfile.WINDOW_DAYS * 86_400_000;
14761
+ const got = fetchCiProfileRows(repoAbs, trunk, new Date(sinceMs).toISOString());
14762
+ if (got.error) notes.push(`could not read CI history (${got.error}) — ${entry ? 'using the stale cached profile' : 'using the bootstrap bounds'}`);
14763
+ else {
14764
+ const policy = verifyRuns.parsePolicy(doc);
14765
+ const prof = ciProfile.profile(ciProfile.shaDurations(got.rows, { trunk, policy }), { sinceMs });
14766
+ entry = { v: CI_PROFILE_CACHE_V, trunk, fetchedAt: nowMs, since: new Date(sinceMs).toISOString(), runsRead: got.runsRead, profile: prof };
14767
+ state = 'fetched';
14768
+ try {
14769
+ const tmp = `${file}.${process.pid}.tmp`;
14770
+ fs.writeFileSync(tmp, JSON.stringify(entry));
14771
+ fs.renameSync(tmp, file);
14772
+ } catch (_) { /* no cache, not an error */ }
14773
+ }
14774
+ }
14775
+ }
14776
+ const profile = entry ? entry.profile : null;
14777
+ const out = {
14778
+ trunk, factor, profile, th: ciProfile.thresholds(profile, factor.value),
14779
+ cache: { state, ageSec: state === 'fetched' ? 0 : ageSec, fetchedAt: entry ? new Date(entry.fetchedAt).toISOString() : null,
14780
+ since: entry ? entry.since : null, runsRead: entry ? entry.runsRead : null },
14781
+ notes,
14782
+ };
14783
+ ciProfileMemo.set(memoKey, out);
14784
+ return out;
14785
+ }
14786
+
14382
14787
  // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
14383
14788
  // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
14384
14789
  // requests, a deadline, and a distinct exit code for every way a wait can end.
@@ -14394,9 +14799,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14394
14799
  with no run yet counts as pending until the deadline. An abbreviated sha is
14395
14800
  resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14396
14801
  --branch <b> narrow --sha to runs on that branch
14397
- --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
14802
+ --timeout <d> deadline: 90s, 15m, 1h, or seconds. Default: this repo's CI wait bound, derived
14803
+ from its measured CI duration (\`colab ci-profile\`, #559) — the trunk bound
14804
+ when the target is trunk, the branch bound for any other branch, the larger
14805
+ for a bare run id; 15m while the repo has no CI history. Skills omit it.
14398
14806
 
14399
- Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
14807
+ Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline (a repo whose CI bound is past 15m
14808
+ gets the same schedule stretched in proportion — never a faster one). Every poll after the first is a
14400
14809
  conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14401
14810
  304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14402
14811
  can cost one paid call, never the whole wait (#505). A 15-minute run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
@@ -14411,7 +14820,8 @@ Exit codes — branch on these, never on the text:
14411
14820
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14412
14821
 
14413
14822
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14414
- --json { outcome, exit, target, polls, notModified, forced, waitedSec, detail, status, conclusion, url }`;
14823
+ --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
14824
+ detail, status, conclusion, url }`;
14415
14825
 
14416
14826
  function cmdCiWait(argv) {
14417
14827
  const opts = parseArgs(argv, {
@@ -14424,8 +14834,10 @@ function cmdCiWait(argv) {
14424
14834
  warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
14425
14835
  return ciWait.EXIT.USAGE;
14426
14836
  }
14427
- const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14428
- if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14837
+ let deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14838
+ if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 15m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14839
+ let deadlineBasis = opts.timeout !== undefined ? '--timeout' : 'bootstrap';
14840
+ let schedule = ciWait.DEFAULT_SCHEDULE_SEC;
14429
14841
  const repoAbs = resolveRepo(opts);
14430
14842
  if (opts.sha) {
14431
14843
  // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
@@ -14452,7 +14864,24 @@ function cmdCiWait(argv) {
14452
14864
  return ciWait.EXIT.ALREADY_WAITING;
14453
14865
  }
14454
14866
 
14455
- const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
14867
+ // #559: no --timeout → the repo's own bound, one source with every skill (they omit the flag). Read
14868
+ // after the lock, so a refused second waiter never spends a history fetch; a failed read is a note.
14869
+ if (opts.timeout === undefined) {
14870
+ const cp = ciProfileFor(repoAbs, { fetch: 'if-stale' });
14871
+ let onTrunk = null;
14872
+ if (!runId && !opts.branch && cp.trunk) {
14873
+ const remote = git.remoteFor(repoAbs);
14874
+ onTrunk = git.git(['merge-base', '--is-ancestor', opts.sha, `${remote}/${cp.trunk}`], repoAbs).ok;
14875
+ }
14876
+ const kind = ciProfile.kindFor({ branch: opts.branch || null, trunk: cp.trunk, onTrunk });
14877
+ deadlineSec = cp.th.ciWaitDefaultSec[kind];
14878
+ schedule = cp.th.scheduleSec[kind];
14879
+ const b = kind === 'any' ? (cp.th.basis.branchWait === 'measured' || cp.th.basis.trunkWait === 'measured' ? 'measured' : 'bootstrap') : cp.th.basis[`${kind}Wait`];
14880
+ deadlineBasis = `${kind === 'any' ? 'larger' : kind} bound, ${b}`;
14881
+ if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
14882
+ }
14883
+
14884
+ const verifyPolicy = verifyingPolicy(repoAbs);
14456
14885
  const poll = (etag) => {
14457
14886
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
14458
14887
  if (r.kind !== 'ok') return r;
@@ -14471,11 +14900,11 @@ function cmdCiWait(argv) {
14471
14900
  return { ...r, summary, state: ciWait.runState(summary) };
14472
14901
  };
14473
14902
 
14474
- if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s, +30s, +60s, then every 120s)\n`);
14903
+ if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}, ${deadlineBasis}; polls at +0s, +${schedule[0]}s, +${schedule[1]}s, then every ${schedule[2]}s)\n`);
14475
14904
  let res;
14476
14905
  try {
14477
14906
  res = ciWait.waitLoop({
14478
- poll, sleep: ciWait.sleepSync, deadlineSec,
14907
+ poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
14479
14908
  onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}${p.forced ? ' (unconditional re-read — #505)' : ''}\n`); },
14480
14909
  });
14481
14910
  } finally {
@@ -14485,14 +14914,15 @@ function cmdCiWait(argv) {
14485
14914
  const code = ciWait.EXIT[res.outcome];
14486
14915
  const out = {
14487
14916
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14488
- waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14917
+ waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14489
14918
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14490
14919
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14920
+ ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
14491
14921
  };
14492
14922
  if (opts.json) print(JSON.stringify(out, null, 2));
14493
14923
  else {
14494
14924
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
14495
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}`);
14925
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}`);
14496
14926
  }
14497
14927
  return code;
14498
14928
  }
@@ -14546,6 +14976,264 @@ function landedBaseTrunk(repoAbs) {
14546
14976
  'gets measured against the wrong one.)');
14547
14977
  }
14548
14978
 
14979
+ const HELP_BATCH_STATS = `colab batch-stats [--repo <path>] [--since <30d | 12h | YYYY-MM-DD>] [--json]
14980
+
14981
+ How batch landing (#373) actually performs in this repo — read-only, derived from GitHub so it
14982
+ answers the same on any machine (#554). It is how a repo tunes its batch knobs: ship-batch: <N>
14983
+ and ship-batch-wait: <duration> have no handbook default (CONVENTIONS §4, Batch landing).
14984
+
14985
+ Sources: trunk's first-parent log since --since (default 30d) — Ship-Batch: trailers mark batch
14986
+ members, Ship-Batch-Dropped: trailers mark members dropped at build, anything else with a
14987
+ Closes #N is a serial landing — and the repo's CI runs in the same window (REST, paginated):
14988
+ ship-batch/** runs are the combined runs, feature-branch runs say when a branch went green at
14989
+ its head, trunk runs say when a landing was pushed and when its trunk-CI cycle ended.
14990
+
14991
+ Reports:
14992
+ batches landed, and their fill · combined-run builds: first-attempt green, green after the
14993
+ one re-run, red, pending
14994
+ red red builds, and how many of their members then landed serially (the fallback)
14995
+ dropped members dropped at build, by class, and the eviction rate
14996
+ serial serial landings, and MISSED PARTNERS — another change, landed later, that was
14997
+ already green when this one landed alone (could have joined) or went green inside
14998
+ this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys)
14999
+ queue wait green-at-head → landing, per landed change
15000
+
15001
+ No batch history in the window is an answer, not an error: it says so, and still reports the
15002
+ serial side — missed partners are the evidence for turning ship-batch on at all. Not the optional
15003
+ machine-local journal: that is off by default and per-machine, so it cannot be the source.
15004
+ --json is the input for an audit; its shape is batch-stats.js derive()'s return value.
15005
+ Exit 0 on a report (empty or not); 1 when trunk's log cannot be read.
15006
+ `;
15007
+
15008
+ /** `--since`: `<N>d` / `<N>h` / `<N>m` back from now, or an ISO date. → epoch ms, or null. */
15009
+ function batchStatsSince(v, nowMs) {
15010
+ const s = String(v || '30d').trim();
15011
+ const rel = /^(\d+)([dhm])$/.exec(s);
15012
+ if (rel) return nowMs - Number(rel[1]) * ({ d: 86400, h: 3600, m: 60 })[rel[2]] * 1000;
15013
+ const t = Date.parse(s);
15014
+ return Number.isFinite(t) ? t : null;
15015
+ }
15016
+
15017
+ function cmdBatchStats(argv) {
15018
+ const opts = parseArgs(argv, {
15019
+ values: { '--repo': 'repo', '--since': 'since' },
15020
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
15021
+ });
15022
+ if (opts.help) return print(HELP_BATCH_STATS);
15023
+ const repoAbs = resolveRepo(opts);
15024
+ if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone`);
15025
+ const doc = projectDoc(repoAbs);
15026
+ const trunk = resolveTrunk(repoAbs, doc);
15027
+ if (!trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab batch-stats` again');
15028
+ const nowMs = Date.now();
15029
+ const sinceMs = batchStatsSince(opts.since, nowMs);
15030
+ if (sinceMs === null) throw new UserError(`--since ${JSON.stringify(opts.since)}: expected 30d, 12h, 90m or an ISO date`);
15031
+ const sinceIso = new Date(sinceMs).toISOString();
15032
+ const notes = [];
15033
+
15034
+ const remote = git.remoteFor(repoAbs);
15035
+ const f = git.git(['fetch', remote, trunk], repoAbs);
15036
+ if (!f.ok) notes.push(`could not fetch ${remote}/${trunk} (${git.gitFailureLine(f.stderr)}) — read from the local copy, which may be behind`);
15037
+ const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs);
15038
+ if (!log.ok) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — run \`git fetch ${remote} ${trunk}\`, then run this again`);
15039
+ const commits = log.stdout.split('\x1e').map((r) => r.replace(/^\n/, '')).filter((r) => r.trim()).map((r) => {
15040
+ const [sha, iso, body] = r.split('\x1f');
15041
+ return { sha: sha.trim(), dateMs: Date.parse(iso), body: body || '' };
15042
+ });
15043
+
15044
+ let runs = [];
15045
+ const builds = {};
15046
+ if (!isGhUsable(repoAbs)) {
15047
+ notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — trunk commits only: no combined runs, no green times, no partner matching`);
15048
+ } else {
15049
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end)] | @json';
15050
+ // One query per UTC day: GitHub answers at most 1000 rows for a filtered run list, and a busy
15051
+ // repo passes that inside a fortnight. A day that still hits the cap is named, never hidden.
15052
+ const days = [];
15053
+ for (let d = Date.parse(sinceIso.slice(0, 10)); d <= nowMs; d += 86_400_000) days.push(new Date(d).toISOString().slice(0, 10));
15054
+ let failed = null;
15055
+ const capped = [];
15056
+ for (const day of days) {
15057
+ const r = git.ghApi(repoAbs, ['--paginate', `repos/{owner}/{repo}/actions/runs?per_page=100&created=${day}`, '--jq', jq]);
15058
+ if (!r.ok) { failed = git.gitFailureLine(r.stderr); break; }
15059
+ let n = 0;
15060
+ for (const line of String(r.stdout || '').split('\n')) {
15061
+ if (!line.trim()) continue;
15062
+ let a; try { a = JSON.parse(line); } catch (_) { continue; }
15063
+ n++;
15064
+ runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9] });
15065
+ }
15066
+ if (n >= 1000) capped.push(day);
15067
+ }
15068
+ if (failed) { notes.push(`could not list CI runs (${failed}) — trunk commits only`); runs = []; }
15069
+ else {
15070
+ if (capped.length) notes.push(`GitHub caps a filtered run list at 1000 and ${capped.join(', ')} hit it — those days are incomplete`);
15071
+ // An unlanded combined run's ref is usually gone: read every commit of the build, so a red
15072
+ // batch's members and its drops are known, not just its head commit's.
15073
+ const landedShas = new Set(commits.map((c) => c.sha));
15074
+ const unlanded = [...new Set(runs.filter((x) => String(x.branch || '').startsWith(shipBatch.REF_PREFIX) && !landedShas.has(x.sha)).map((x) => `${x.branch} ${x.sha}`))];
15075
+ for (const k of unlanded) {
15076
+ const [ref, sha] = k.split(' ');
15077
+ const base7 = (shipBatch.parseBatchRef(ref) || {}).base7;
15078
+ if (!base7) continue;
15079
+ const c = git.ghApi(repoAbs, [`repos/{owner}/{repo}/compare/${base7}...${sha}`, '--jq', '[.commits[].commit.message]']);
15080
+ if (c.ok) { try { builds[sha] = JSON.parse(c.stdout); } catch (_) { /* head message only */ } }
15081
+ }
15082
+ }
15083
+ }
15084
+
15085
+ const cfg = shipBatch.parseShipBatch(doc);
15086
+ const waitCfg = shipBatch.parseShipBatchWait(doc);
15087
+ const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec } });
15088
+ rep.repo = shortRepo(repoAbs);
15089
+ rep.since = sinceIso;
15090
+ rep.until = new Date(nowMs).toISOString();
15091
+ rep.notes = [...notes, ...rep.notes];
15092
+ if (opts.json) { print(JSON.stringify(rep, null, 2)); return 0; }
15093
+
15094
+ const pct = (x) => (x === null ? '—' : `${Math.round(x * 100)}%`);
15095
+ const dur = (s) => (s === null ? '—' : ciWait.fmtDuration(s * 1000));
15096
+ const q = (w) => (w.samples ? `p50 ${dur(w.p50Sec)} · p90 ${dur(w.p90Sec)} · max ${dur(w.maxSec)} (${w.samples})` : 'no samples');
15097
+ print(`batch-stats ${rep.repo} → ${trunk} ${rep.since.slice(0, 10)} … ${rep.until.slice(0, 10)} (ship-batch: ${cfg.n}${waitCfg.sec ? ` · ship-batch-wait: ${dur(waitCfg.sec)}` : ''})`);
15098
+ print(` landings ${rep.landings.total} (${rep.landings.batch} batch · ${rep.landings.serial} serial)`);
15099
+ if (!rep.history) print(' batches no batch history in this window — nothing has landed or been built through colab ship --batch');
15100
+ else {
15101
+ const fill = Object.keys(rep.batches.fill).sort().map((k) => `${rep.batches.fill[k]}×${k}`).join(' · ') || '—';
15102
+ print(` batches ${rep.batches.landed} landed (fill ${fill}) · ${rep.batches.builds} combined-run build(s): ${rep.batches.firstAttemptGreen} first-attempt green (${pct(rep.batches.firstAttemptGreenRate)}), ${rep.batches.greenAfterRerun} after a re-run, ${rep.batches.red} red, ${rep.batches.pending} pending`);
15103
+ print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedSerially} then landed serially`);
15104
+ const cls = Object.entries(rep.dropped.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
15105
+ print(` dropped ${rep.dropped.count} of ${rep.dropped.attempted} attempted (${pct(rep.dropped.rate)})${cls ? ` — ${cls}` : ''}`);
15106
+ }
15107
+ print(` serial ${rep.serial.landings} landed alone · ${rep.serial.withMissedPartner} with a missed partner (already green) · ${rep.serial.withNearMiss} more with a near miss (green within its trunk-CI cycle)`);
15108
+ if (rep.serial.nearMissWait.samples) print(` near misses per pair, the wait from the lone change's own green that would have caught its partner: ${q(rep.serial.nearMissWait)}`);
15109
+ print(` queue wait green-at-head → landing: ${q(rep.queueWait)}`);
15110
+ for (const n of rep.notes) print(` ! ${n}`);
15111
+ return 0;
15112
+ }
15113
+
15114
+ // ci-profile (#559) — the repo's measured CI duration and every wait bound derived from it.
15115
+ const HELP_CI_PROFILE = `colab ci-profile [--repo <path>] [--json] [--refresh]
15116
+
15117
+ This repo's measured CI duration, and every CI wait bound derived from it (#559). One source:
15118
+ \`colab ci-wait\` with no --timeout, and \`colab ship\`'s wedged-run and empty-read verdicts, read
15119
+ these same numbers — no skill hard-codes a wait.
15120
+
15121
+ Measured: per sha, the wall time from the first verifying run's creation to the last one's
15122
+ finish, over clean first-attempt green shas in the last ${ciProfile.WINDOW_DAYS} days — split into branch runs and trunk
15123
+ runs — plus the push → run lag on trunk. A kind with fewer than ${ciProfile.MIN_SAMPLES} samples stays on its
15124
+ bootstrap value, which is today's fleet value exactly (15m waits, 6h wedge, 10m grace, 2m floor).
15125
+
15126
+ Declared: only \`ci-wait-factor: <number ≥ 1>\` in .github/project.yml (default ${ciProfile.DEFAULT_FACTOR}) — how many times
15127
+ the measured p95 a repo will wait. Every bound:
15128
+ branch / trunk wait 2m + factor × p95 of that kind, rounded up to the minute
15129
+ wedged-run age factor × the longer wait, never above 6h
15130
+ empty-read grace factor × push→run p95, never below 2m
15131
+ zero-jobs floor 2m (not measurable from the run list)
15132
+ poll backoff 30/60/120s, stretched in proportion to a wait past 15m — never faster
15133
+
15134
+ The profile is cached per checkout for a day (<git common dir>/colab-ci-profile.json;
15135
+ COLAB_CI_PROFILE_TTL seconds overrides, 0 = no cache and no read: the bootstrap). The bounds are
15136
+ recomputed from it on every read, so a changed ci-wait-factor applies at once.
15137
+
15138
+ --refresh re-read the CI history now, whatever the cache's age
15139
+ --json { repo, trunk, source, factor, cache, measured: { branch, trunk, lag }, thresholds, notes }`;
15140
+
15141
+ function cmdCiProfile(argv) {
15142
+ const opts = parseArgs(argv, {
15143
+ values: { '--repo': 'repo' },
15144
+ flags: { '--json': 'json', '--refresh': 'refresh', '-h': 'help', '--help': 'help' },
15145
+ });
15146
+ if (opts.help) return print(HELP_CI_PROFILE);
15147
+ const repoAbs = resolveRepo(opts);
15148
+ if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone, then run \`colab ci-profile\` again`);
15149
+ const cp = ciProfileFor(repoAbs, { fetch: opts.refresh ? 'always' : 'if-stale' });
15150
+ if (!cp.trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab ci-profile` again');
15151
+ const p = cp.profile || ciProfile.profile([]);
15152
+ const th = cp.th;
15153
+ const source = cp.profile ? cp.profile.source : 'bootstrap';
15154
+ if (opts.json) {
15155
+ print(JSON.stringify({
15156
+ repo: shortRepo(repoAbs), trunk: cp.trunk, source, factor: cp.factor, cache: cp.cache,
15157
+ measured: { branch: p.branch, trunk: p.trunk, lag: p.lag }, thresholds: th, notes: cp.notes,
15158
+ }, null, 2));
15159
+ return 0;
15160
+ }
15161
+ const dur = (s) => (s === null || s === undefined ? '—' : ciWait.fmtDuration(s * 1000));
15162
+ const cacheTxt = cp.cache.state === 'fetched' ? 'read now'
15163
+ : cp.cache.state === 'none' ? 'no history read' : `read ${dur(cp.cache.ageSec)} ago (cache${cp.cache.state === 'stale' ? ', stale' : ''})`;
15164
+ print(`ci-profile ${shortRepo(repoAbs)} → ${cp.trunk} ${source.toUpperCase()} · ${cacheTxt} · ${cp.factor.valid ? cp.factor.reason : `${ciProfile.FACTOR_KEY}: ${ciProfile.DEFAULT_FACTOR} (declared value invalid)`}`);
15165
+ if (source !== 'measured') print(` ${source === 'bootstrap' ? 'every bound is' : 'unmeasured bounds are'} the bootstrap — fewer than ${ciProfile.MIN_SAMPLES} clean green shas per kind in ${ciProfile.WINDOW_DAYS}d`);
15166
+ const k = (name, x) => print(` ${name.padEnd(11)} ${x.source} · ${x.samples} sha(s)${x.samples ? ` · p50 ${dur(x.p50Sec)} · p95 ${dur(x.p95Sec)} · max ${dur(x.maxSec)}` : ''}`);
15167
+ k('branch', p.branch);
15168
+ k('trunk', p.trunk);
15169
+ print(` ${'push→run'.padEnd(11)} ${p.lag.source} · ${p.lag.samples} sample(s)${p.lag.samples ? ` · p95 ${dur(p.lag.p95Sec)}` : ''}`);
15170
+ const row = (name, sec, basis, how, boot) => print(` ${name.padEnd(11)} ${dur(sec).padEnd(7)} ${basis === 'measured' ? how : basis === 'default' ? how : 'bootstrap'}${basis === 'measured' && boot ? ` (bootstrap ${boot})` : ''}`);
15171
+ row('branch wait', th.branchWaitSec, th.basis.branchWait, `2m + ${th.factor} × p95`, '15m');
15172
+ row('trunk wait', th.trunkWaitSec, th.basis.trunkWait, `2m + ${th.factor} × p95`, '15m');
15173
+ print(` ${'ci-wait'.padEnd(11)} ${dur(th.ciWaitDefaultSec.branch)} branch · ${dur(th.ciWaitDefaultSec.trunk)} trunk · ${dur(th.ciWaitDefaultSec.any)} run id (its default with no --timeout)`);
15174
+ row('wedged age', th.wedgeAgeSec, th.basis.wedgeAge, `${th.factor} × the longer wait, ≤ 6h`, '6h');
15175
+ row('empty read', th.emptyReadGraceSec, th.basis.emptyReadGrace, `${th.factor} × push→run p95, ≥ 2m`, '10m');
15176
+ row('zero jobs', th.zeroJobsFloorSec, th.basis.zeroJobsFloor, 'default — not measurable from the run list');
15177
+ print(` ${'backoff'.padEnd(11)} branch ${th.scheduleSec.branch.map((x) => `${x}s`).join('/')} · trunk ${th.scheduleSec.trunk.map((x) => `${x}s`).join('/')}`);
15178
+ for (const n of cp.notes) print(` ! ${n}`);
15179
+ return 0;
15180
+ }
15181
+
15182
+ // thresholds (#560) — the advisory thresholds this repo applies: its declared values, else the defaults.
15183
+ const HELP_THRESHOLDS = `colab thresholds [--repo <path>] [--json] [<name>]
15184
+
15185
+ The advisory thresholds this repo applies (#560): the value of each, and whether it is this
15186
+ repo's declared value or the handbook default. A repo overrides one in .github/project.yml:
15187
+
15188
+ thresholds:
15189
+ hot-file-count: 4
15190
+
15191
+ Nothing changes for a repo that declares nothing. Skills cite these by name — code-triage's
15192
+ hot-file count and dependents band, code-wrap's gate.smoke target — and read them here, so no
15193
+ skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
15194
+ and is listed under problems; the audit and the CI templates' descriptor check fail it.
15195
+
15196
+ The batch-* names (#556) have NO default: undeclared, they read "—" and the audit's
15197
+ --batch-history shows the measurement without judging it. Percents are bounded at 100.
15198
+
15199
+ <name> print only that threshold's value (a bare number, for a script or a skill;
15200
+ an empty line for an undeclared no-default name)
15201
+ --json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
15202
+
15203
+ function cmdThresholds(argv) {
15204
+ const opts = parseArgs(argv, {
15205
+ values: { '--repo': 'repo' },
15206
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
15207
+ });
15208
+ if (opts.help) return print(HELP_THRESHOLDS);
15209
+ const repoAbs = resolveRepo(opts);
15210
+ const r = thresholdsLib.parseThresholds(projectDoc(repoAbs));
15211
+ const name = opts._ && opts._[0];
15212
+ if (name !== undefined) {
15213
+ if (!thresholdsLib.SPEC[name]) throw new UserError(`unknown threshold ${name} — expected one of: ${Object.keys(thresholdsLib.SPEC).join(', ')} (run \`colab thresholds\` to list them)`);
15214
+ for (const p of r.problems) process.stderr.write(`! ${p}\n`);
15215
+ print(r.values[name] === null ? '' : String(r.values[name])); // #556: empty = undeclared, no default
15216
+ return 0;
15217
+ }
15218
+ const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
15219
+ value: r.values[k], default: s.def, declared: !!r.declared[k], what: s.what, where: s.where,
15220
+ }]));
15221
+ if (opts.json) {
15222
+ print(JSON.stringify({ repo: shortRepo(repoAbs), thresholds: rows, problems: r.problems }, null, 2));
15223
+ return 0;
15224
+ }
15225
+ print(`thresholds ${shortRepo(repoAbs)}`);
15226
+ const w = Math.max(...Object.keys(rows).map((k) => k.length));
15227
+ for (const [k, row] of Object.entries(rows)) {
15228
+ // #556: a no-default key (batch-*) shows `—` and "not declared" — nothing judges it until it is.
15229
+ const shown = row.value === null ? '—' : String(row.value);
15230
+ const src = row.declared ? `declared (default ${row.default === null ? 'none' : row.default})` : (row.default === null ? 'not declared' : 'default');
15231
+ print(` ${k.padEnd(w)} ${shown.padStart(5)} ${src.padEnd(20)} ${row.what}`);
15232
+ }
15233
+ for (const p of r.problems) print(` ! ${p}`);
15234
+ return 0;
15235
+ }
15236
+
14549
15237
  function cmdLanded(argv) {
14550
15238
  const opts = parseArgs(argv, {
14551
15239
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15330,6 +16018,13 @@ Commands:
15330
16018
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
15331
16019
  (the shared rule behind code-sweep's buckets — correct
15332
16020
  across squash merges, where "commits ahead" is not)
16021
+ batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
16022
+ fill, first-attempt green, drops, missed partners, queue
16023
+ wait; how a repo tunes ship-batch / ship-batch-wait (#554)
16024
+ ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
16025
+ derived from it — ci-wait's default deadline (#559)
16026
+ thresholds [<name>] [--json] the advisory thresholds this repo applies — declared in
16027
+ project.yml thresholds:, else the default (#560)
15333
16028
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15334
16029
  have not landed on the base (filters the raw git-log
15335
16030
  one-liner through \`landed\`'s content classification)
@@ -15414,6 +16109,9 @@ function main(argv) {
15414
16109
  case 'worktrees': return cmdWorktrees(rest);
15415
16110
  case 'ship': return cmdShip(rest);
15416
16111
  case 'landed': return cmdLanded(rest);
16112
+ case 'batch-stats': return cmdBatchStats(rest);
16113
+ case 'ci-profile': return cmdCiProfile(rest);
16114
+ case 'thresholds': return cmdThresholds(rest);
15417
16115
  case 'trunk-ci': return cmdTrunkCi(rest);
15418
16116
  case 'ci-wait': return cmdCiWait(rest);
15419
16117
  case 'holders': return cmdHolders(rest);