@futurelastic/colab-handbook 1.13.0-rc.9 → 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>');
@@ -9776,8 +9961,14 @@ function trustAt(repoAbs, ref) {
9776
9961
  * gated by it, and a branch that deletes trunk's declaration is still gated by trunk's.
9777
9962
  */
9778
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) {
9779
9970
  const r = git.git(['diff', '--name-only', `${trunk}...${branch}`], mainRoot);
9780
- if (!r.ok) return [];
9971
+ if (!r.ok) return null;
9781
9972
  const declared = migrationPaths.unionPaths(projectDoc(mainRoot), projectDocAt(mainRoot, trunk), projectDocAt(mainRoot, branch));
9782
9973
  return r.stdout.split('\n').filter(Boolean).filter((f) => migrationPaths.isMigrationPath(f, declared));
9783
9974
  }
@@ -10051,6 +10242,7 @@ promotes is an integration event of the same weight as a promotion, and stays hu
10051
10242
 
10052
10243
  Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
10053
10244
  a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
10245
+ or tuning-only (#561)
10054
10246
  — or a person runs ship through the human door (#525): a confirmed interactive
10055
10247
  terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
10056
10248
  b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
@@ -10227,6 +10419,14 @@ auto-trunk). The row reads "docs-only (N files) — autonomy exception", and --d
10227
10419
  \`autonomyGate: { via, docsOnly }\`. After B0 sync the diff is measured again before the squash.
10228
10420
  Every other precondition is unchanged. No flag, env var or project.yml field widens the list.
10229
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
+
10230
10430
  TRUNK-DIRECT — \`colab ship --direct\` (#302). A unit committed straight to trunk has no branch and
10231
10431
  no worktree, so neither door above can find it, and evidence-close's own detection cannot fire
10232
10432
  (\`landed\` is \`unknown\` when base === branch). --direct is its close path: the claims are this
@@ -10283,6 +10483,12 @@ at build, added since) is NOT landed with it — the command names both lists an
10283
10483
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10284
10484
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10285
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.
10286
10492
 
10287
10493
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10288
10494
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -10754,6 +10960,37 @@ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
10754
10960
  detail: `none — ${at} has no repo-owned workflow (#482), so the branch's own run decides, and ${ownAt} ${why}${excludedRunsNote(r.run)}` };
10755
10961
  }
10756
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
+
10757
10994
  /** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
10758
10995
  function trunkWorkflowFiles(repoAbs, sha) {
10759
10996
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
@@ -10784,7 +11021,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10784
11021
  if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
10785
11022
  // #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
10786
11023
  // aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
10787
- const readOpts = { verifying: verifyRuns.parsePolicy(projectDoc(repoAbs)) };
11024
+ const readOpts = { verifying: verifyingPolicy(repoAbs) };
10788
11025
  let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
10789
11026
  let via = target;
10790
11027
  if (run && run.status === 'none' && target !== trunk) {
@@ -10810,10 +11047,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10810
11047
  // (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
10811
11048
  // never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
10812
11049
  if (run.status === 'none' && target === trunk) {
10813
- 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 });
10814
11052
  if (fresh.fresh) {
10815
11053
  verdict = { ok: false, class: SELF_CLEARING,
10816
- 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)}` };
10817
11055
  }
10818
11056
  }
10819
11057
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -10884,7 +11122,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
10884
11122
  */
10885
11123
  function classifyCiRun(repoAbs, run, at) {
10886
11124
  const v = classifyCiRunRaw(repoAbs, run, at);
10887
- 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) };
10888
11126
  }
10889
11127
 
10890
11128
  /**
@@ -10926,7 +11164,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
10926
11164
  // Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
10927
11165
  // shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
10928
11166
  const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
10929
- 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 });
10930
11170
  if (wedge.wedged) {
10931
11171
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
10932
11172
  }
@@ -11695,7 +11935,8 @@ function cmdShipDryJson(opts) {
11695
11935
 
11696
11936
  // ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
11697
11937
  const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
11698
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
11938
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
11939
+ () => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
11699
11940
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
11700
11941
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
11701
11942
 
@@ -12576,23 +12817,33 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
12576
12817
  * caller asserts nothing. `readDocsOnly` is a thunk, so an auto-trunk repo never pays for the
12577
12818
  * diff read. Every other precondition is untouched — this relaxes the autonomy gate, not the checks.
12578
12819
  *
12579
- * 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 }`.
12580
12826
  */
12581
- function shipAutonomyGate(doc, readDocsOnly, door = null) {
12827
+ function shipAutonomyGate(doc, readDocsOnly, door = null, readTuning = null) {
12582
12828
  const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
12583
- 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' };
12584
12830
  const verdict = readDocsOnly();
12585
12831
  if (verdict.docsOnly) {
12586
- 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)` };
12587
12837
  }
12588
12838
  // #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
12589
- // 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.
12590
12840
  if (door && door.open) {
12591
- return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
12841
+ return { ok: true, via: 'human', declared, docsOnly: verdict, tuning, human: door,
12592
12842
  detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
12593
12843
  }
12594
- return { ok: false, via: null, declared, docsOnly: verdict, human: door,
12595
- 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'})` };
12596
12847
  }
12597
12848
 
12598
12849
  /** #525: the human-door refusal lines — what a person runs, never just "a human must". */
@@ -12651,8 +12902,10 @@ function shipHumanDoorGo(gate, opts, what) {
12651
12902
  function autonomyGatePayload(gate) {
12652
12903
  // #525: `human` is additive and present only when the human door was consulted, so an
12653
12904
  // auto-trunk / docs-only payload stays byte-identical to before.
12654
- return gate.human ? { via: gate.via, docsOnly: gate.docsOnly, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } }
12655
- : { 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;
12656
12909
  }
12657
12910
 
12658
12911
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
@@ -12739,11 +12992,13 @@ function cmdShip(argv) {
12739
12992
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
12740
12993
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
12741
12994
  const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
12742
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12995
+ humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
12996
+ () => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
12743
12997
  if (!autonomyGate.ok) {
12744
12998
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12745
12999
  process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12746
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`);
12747
13002
  process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
12748
13003
  return 1;
12749
13004
  }
@@ -13236,6 +13491,14 @@ function cmdShip(argv) {
13236
13491
  return 1;
13237
13492
  }
13238
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
+ }
13239
13502
 
13240
13503
  // #350: B0 may have brought in paths (a pre-ship hook's regenerated files). The approval covered
13241
13504
  // the core paths the table listed; a core path it did not list was never reviewed.
@@ -13841,7 +14104,10 @@ function cmdShipBatch(opts) {
13841
14104
  if (String(doc.autonomy || '') !== 'auto-trunk') {
13842
14105
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
13843
14106
  }
13844
- 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`);
13845
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`);
13846
14112
 
13847
14113
  const remote = git.remoteFor(repoAbs);
@@ -13980,6 +14246,22 @@ function cmdShipBatch(opts) {
13980
14246
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
13981
14247
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
13982
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
+ }
13983
14265
  if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
13984
14266
 
13985
14267
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
@@ -14001,9 +14283,9 @@ function cmdShipBatch(opts) {
14001
14283
  // regenerated by .colab/hooks/pre-ship, never hand-merged and never a reason to leave the batch.
14002
14284
  // Only an overlap outside `generated:` (or no hook to regenerate with) drops the member.
14003
14285
  const nonGen = unmerged.filter((f) => !isGeneratedPath(f, generated));
14004
- let why = null;
14005
- if (nonGen.length) why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`;
14006
- 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`; }
14007
14289
  else {
14008
14290
  const hk = runHook(repoAbs, 'pre-ship', {
14009
14291
  wtPath: dir, name: m.branch, branch: m.branch, ports: [], trunk, base: trunk,
@@ -14014,24 +14296,26 @@ function cmdShipBatch(opts) {
14014
14296
  // state, so `left` reads empty — read the staged content itself before trusting it.
14015
14297
  const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
14016
14298
  if (!hk.ran || !hk.ok || left.length) {
14299
+ cls = 'hook-failed';
14017
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`;
14018
14301
  } else if (markers.length) {
14302
+ cls = 'hook-markers';
14019
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`;
14020
14304
  } else regenerated = unmerged;
14021
14305
  }
14022
14306
  if (why) {
14023
14307
  git.git(['reset', '--hard', 'HEAD'], dir);
14024
- dropped.push({ branch: m.branch, why });
14308
+ dropped.push({ branch: m.branch, sha: m.sha, cls, why });
14025
14309
  continue;
14026
14310
  }
14027
14311
  } else if (!sq.ok) {
14028
14312
  git.git(['reset', '--hard', 'HEAD'], dir);
14029
- 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)}` });
14030
14314
  continue;
14031
14315
  }
14032
14316
  if (!git.git(['diff', '--cached', '--name-only'], dir).stdout.trim()) {
14033
14317
  git.git(['reset', '--hard', 'HEAD'], dir);
14034
- 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' });
14035
14319
  continue;
14036
14320
  }
14037
14321
  const closeIssues = m.report.closeIssues || [];
@@ -14043,14 +14327,25 @@ function cmdShipBatch(opts) {
14043
14327
  const inherited = msg && refsIssues.length ? squash.inheritedClosingKeywordConflicts(msg, refsIssues) : [];
14044
14328
  if (!msg || !coverage.ok || inherited.length) {
14045
14329
  git.git(['reset', '--hard', 'HEAD'], dir);
14046
- 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' });
14047
14331
  continue;
14048
14332
  }
14049
14333
  const c = git.run('git', ['commit', '-q', '-m', msg], { cwd: dir });
14050
- 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; }
14051
14335
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
14052
14336
  }
14053
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
+ }
14054
14349
  for (const b of built.filter((x) => x.regenerated)) {
14055
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)`);
14056
14351
  }
@@ -14330,7 +14625,8 @@ function cmdTrunkCi(argv) {
14330
14625
  if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
14331
14626
  out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
14332
14627
  ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
14333
- ...(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 } : {}) };
14334
14630
  if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
14335
14631
  }
14336
14632
  if (opts.json) {
@@ -14384,6 +14680,110 @@ function trunkCiCache(repoAbs) {
14384
14680
  };
14385
14681
  }
14386
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
+
14387
14787
  // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
14388
14788
  // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
14389
14789
  // requests, a deadline, and a distinct exit code for every way a wait can end.
@@ -14399,9 +14799,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14399
14799
  with no run yet counts as pending until the deadline. An abbreviated sha is
14400
14800
  resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14401
14801
  --branch <b> narrow --sha to runs on that branch
14402
- --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.
14403
14806
 
14404
- 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
14405
14809
  conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14406
14810
  304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14407
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.
@@ -14416,7 +14820,8 @@ Exit codes — branch on these, never on the text:
14416
14820
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14417
14821
 
14418
14822
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14419
- --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 }`;
14420
14825
 
14421
14826
  function cmdCiWait(argv) {
14422
14827
  const opts = parseArgs(argv, {
@@ -14429,8 +14834,10 @@ function cmdCiWait(argv) {
14429
14834
  warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
14430
14835
  return ciWait.EXIT.USAGE;
14431
14836
  }
14432
- const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14433
- 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;
14434
14841
  const repoAbs = resolveRepo(opts);
14435
14842
  if (opts.sha) {
14436
14843
  // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
@@ -14457,7 +14864,24 @@ function cmdCiWait(argv) {
14457
14864
  return ciWait.EXIT.ALREADY_WAITING;
14458
14865
  }
14459
14866
 
14460
- 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);
14461
14885
  const poll = (etag) => {
14462
14886
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
14463
14887
  if (r.kind !== 'ok') return r;
@@ -14476,11 +14900,11 @@ function cmdCiWait(argv) {
14476
14900
  return { ...r, summary, state: ciWait.runState(summary) };
14477
14901
  };
14478
14902
 
14479
- 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`);
14480
14904
  let res;
14481
14905
  try {
14482
14906
  res = ciWait.waitLoop({
14483
- poll, sleep: ciWait.sleepSync, deadlineSec,
14907
+ poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
14484
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`); },
14485
14909
  });
14486
14910
  } finally {
@@ -14490,14 +14914,15 @@ function cmdCiWait(argv) {
14490
14914
  const code = ciWait.EXIT[res.outcome];
14491
14915
  const out = {
14492
14916
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14493
- waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14917
+ waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14494
14918
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14495
14919
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14920
+ ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
14496
14921
  };
14497
14922
  if (opts.json) print(JSON.stringify(out, null, 2));
14498
14923
  else {
14499
14924
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
14500
- `${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)}`);
14501
14926
  }
14502
14927
  return code;
14503
14928
  }
@@ -14551,6 +14976,264 @@ function landedBaseTrunk(repoAbs) {
14551
14976
  'gets measured against the wrong one.)');
14552
14977
  }
14553
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
+
14554
15237
  function cmdLanded(argv) {
14555
15238
  const opts = parseArgs(argv, {
14556
15239
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15335,6 +16018,13 @@ Commands:
15335
16018
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
15336
16019
  (the shared rule behind code-sweep's buckets — correct
15337
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)
15338
16028
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15339
16029
  have not landed on the base (filters the raw git-log
15340
16030
  one-liner through \`landed\`'s content classification)
@@ -15419,6 +16109,9 @@ function main(argv) {
15419
16109
  case 'worktrees': return cmdWorktrees(rest);
15420
16110
  case 'ship': return cmdShip(rest);
15421
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);
15422
16115
  case 'trunk-ci': return cmdTrunkCi(rest);
15423
16116
  case 'ci-wait': return cmdCiWait(rest);
15424
16117
  case 'holders': return cmdHolders(rest);