@futurelastic/colab-handbook 1.13.0-rc.24 → 1.13.0-rc.26

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/audit/audit.mjs CHANGED
@@ -98,6 +98,7 @@ const installRoute = require("../tools/lib/install-route.js");
98
98
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
99
99
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
100
100
  const shipBatch = require("../tools/lib/ship-batch.js");
101
+ const ciProfile = require("../tools/lib/ci-profile.js"); // #559
101
102
  // #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
102
103
  // validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
103
104
  const migrationPaths = require("../tools/lib/migration-paths.js");
@@ -1315,6 +1316,16 @@ function auditRepo(target, ctx) {
1315
1316
  else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1316
1317
  }
1317
1318
 
1319
+ // ---- ci-wait-factor (#559) ----------------------------------------------------
1320
+ // The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
1321
+ // (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
1322
+ // value fails here; the tools fall back to the documented default (2) and say so — never to a
1323
+ // different behaviour. No ceiling: how patient a repo is, is the repo's choice.
1324
+ if (ciProfile.FACTOR_KEY in (cfg || {}) && cfg[ciProfile.FACTOR_KEY] !== null) {
1325
+ const f = ciProfile.parseFactor(cfg);
1326
+ if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
1327
+ }
1328
+
1318
1329
  // ---- migrations (#383) ----------------------------------------------------
1319
1330
  // Where the repo's migrations live, beyond the two defaults (database/migrations/,
1320
1331
  // prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.24"
36
+ "version": "1.13.0-rc.26"
37
37
  }
package/tools/colab CHANGED
@@ -49,6 +49,7 @@ 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
52
53
  const staleBase = require('./lib/stale-base');
53
54
  const dirtyOwner = require('./lib/dirty-owner');
54
55
  const scratchDirs = require('./lib/scratch-dirs');
@@ -63,6 +64,7 @@ const codec = require('./lib/codec');
63
64
  const machine = require('./lib/machine');
64
65
  const targetSync = require('./lib/ship-target-sync');
65
66
  const shipBatch = require('./lib/ship-batch');
67
+ const batchStats = require('./lib/batch-stats');
66
68
  const conflictMarkers = require('./lib/conflict-markers');
67
69
  const docsOnly = require('./lib/docs-only');
68
70
  const cureDiff = require('./lib/cure-diff');
@@ -10884,10 +10886,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10884
10886
  // (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
10885
10887
  // never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
10886
10888
  if (run.status === 'none' && target === trunk) {
10887
- const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
10889
+ // #559: the grace is the repo's measured push→run lag when there is one — read from cache, never fetched here.
10890
+ const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
10888
10891
  if (fresh.fresh) {
10889
10892
  verdict = { ok: false, class: SELF_CLEARING,
10890
- 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)}` };
10893
+ 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)}` };
10891
10894
  }
10892
10895
  }
10893
10896
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -11000,7 +11003,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
11000
11003
  // Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
11001
11004
  // shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
11002
11005
  const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
11003
- const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount });
11006
+ // #559: wedge age and zero-jobs floor follow the repo's measured CI (cached profile; bootstrap = 6h / 2m).
11007
+ const th = ciProfileFor(repoAbs).th;
11008
+ const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount }, { wedgeAgeSec: th.wedgeAgeSec, zeroJobsFloorSec: th.zeroJobsFloorSec });
11004
11009
  if (wedge.wedged) {
11005
11010
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
11006
11011
  }
@@ -14094,9 +14099,9 @@ function cmdShipBatch(opts) {
14094
14099
  // regenerated by .colab/hooks/pre-ship, never hand-merged and never a reason to leave the batch.
14095
14100
  // Only an overlap outside `generated:` (or no hook to regenerate with) drops the member.
14096
14101
  const nonGen = unmerged.filter((f) => !isGeneratedPath(f, generated));
14097
- let why = null;
14098
- if (nonGen.length) why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`;
14099
- 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`;
14102
+ let why = null, cls = null;
14103
+ if (nonGen.length) { why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`; cls = 'conflict'; }
14104
+ 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`; }
14100
14105
  else {
14101
14106
  const hk = runHook(repoAbs, 'pre-ship', {
14102
14107
  wtPath: dir, name: m.branch, branch: m.branch, ports: [], trunk, base: trunk,
@@ -14107,24 +14112,26 @@ function cmdShipBatch(opts) {
14107
14112
  // state, so `left` reads empty — read the staged content itself before trusting it.
14108
14113
  const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
14109
14114
  if (!hk.ran || !hk.ok || left.length) {
14115
+ cls = 'hook-failed';
14110
14116
  why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
14111
14117
  } else if (markers.length) {
14118
+ cls = 'hook-markers';
14112
14119
  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`;
14113
14120
  } else regenerated = unmerged;
14114
14121
  }
14115
14122
  if (why) {
14116
14123
  git.git(['reset', '--hard', 'HEAD'], dir);
14117
- dropped.push({ branch: m.branch, why });
14124
+ dropped.push({ branch: m.branch, sha: m.sha, cls, why });
14118
14125
  continue;
14119
14126
  }
14120
14127
  } else if (!sq.ok) {
14121
14128
  git.git(['reset', '--hard', 'HEAD'], dir);
14122
- dropped.push({ branch: m.branch, why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
14129
+ dropped.push({ branch: m.branch, sha: m.sha, cls: 'squash-failed', why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
14123
14130
  continue;
14124
14131
  }
14125
14132
  if (!git.git(['diff', '--cached', '--name-only'], dir).stdout.trim()) {
14126
14133
  git.git(['reset', '--hard', 'HEAD'], dir);
14127
- dropped.push({ branch: m.branch, why: 'stages nothing on top of the members already in' });
14134
+ dropped.push({ branch: m.branch, sha: m.sha, cls: 'empty', why: 'stages nothing on top of the members already in' });
14128
14135
  continue;
14129
14136
  }
14130
14137
  const closeIssues = m.report.closeIssues || [];
@@ -14136,14 +14143,25 @@ function cmdShipBatch(opts) {
14136
14143
  const inherited = msg && refsIssues.length ? squash.inheritedClosingKeywordConflicts(msg, refsIssues) : [];
14137
14144
  if (!msg || !coverage.ok || inherited.length) {
14138
14145
  git.git(['reset', '--hard', 'HEAD'], dir);
14139
- 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' });
14146
+ 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' });
14140
14147
  continue;
14141
14148
  }
14142
14149
  const c = git.run('git', ['commit', '-q', '-m', msg], { cwd: dir });
14143
- if (!c.ok) { git.git(['reset', '--hard', 'HEAD'], dir); dropped.push({ branch: m.branch, why: `commit failed: ${git.gitFailureLine(c.stderr)}` }); continue; }
14150
+ 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; }
14144
14151
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
14145
14152
  }
14146
14153
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
14154
+ // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14155
+ // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14156
+ // Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
14157
+ if (dropped.length && built.length >= 2) {
14158
+ const last = built[built.length - 1];
14159
+ const cur = git.git(['log', '-1', '--format=%B'], dir);
14160
+ const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
14161
+ const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
14162
+ if (am.ok) last.commit = git.git(['rev-parse', 'HEAD'], dir).stdout;
14163
+ else warn(`could not record the dropped member(s) on the batch head: ${git.gitFailureLine(am.stderr)} — the drop is on this terminal only`);
14164
+ }
14147
14165
  for (const b of built.filter((x) => x.regenerated)) {
14148
14166
  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)`);
14149
14167
  }
@@ -14477,6 +14495,110 @@ function trunkCiCache(repoAbs) {
14477
14495
  };
14478
14496
  }
14479
14497
 
14498
+ // ---- ci-profile (#559) ------------------------------------------------------------------------
14499
+ // Every CI wait bound derives from the repo's own measured CI duration (tools/lib/ci-profile.js).
14500
+ // The profile is cached per checkout in `<git common dir>/colab-ci-profile.json` for a day; the
14501
+ // thresholds are NOT cached — they are recomputed from the cached profile and the CURRENT
14502
+ // `ci-wait-factor`, so editing the factor applies at once with no refetch.
14503
+ const CI_PROFILE_TTL_DEFAULT_SEC = 24 * 3600;
14504
+ const CI_PROFILE_CACHE_V = 1;
14505
+
14506
+ function ciProfileTtlSec() {
14507
+ const env = process.env.COLAB_CI_PROFILE_TTL;
14508
+ return env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : CI_PROFILE_TTL_DEFAULT_SEC;
14509
+ }
14510
+
14511
+ function ciProfileCacheFile(repoAbs) {
14512
+ const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
14513
+ return dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-ci-profile.json') : null;
14514
+ }
14515
+
14516
+ /**
14517
+ * The repo's completed CI runs in the profile window — up to 3 pages of the whole list plus one page
14518
+ * of trunk pushes, so a branch-heavy repo still yields trunk samples. Returns `{ rows, runsRead }`,
14519
+ * or `{ error }` when the list cannot be read (the caller falls back, never fails a wait on it).
14520
+ */
14521
+ function fetchCiProfileRows(repoAbs, trunk, sinceIso) {
14522
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .name, .status, .conclusion, .run_attempt, .created_at, .updated_at, .head_commit.timestamp] | @json';
14523
+ const day = sinceIso.slice(0, 10);
14524
+ const paths = [1, 2, 3].map((n) => `repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&page=${n}`);
14525
+ paths.push(`repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&branch=${encodeURIComponent(trunk)}&event=push`);
14526
+ const seen = new Map();
14527
+ for (let i = 0; i < paths.length; i++) {
14528
+ const r = git.ghApi(repoAbs, [paths[i], '--jq', jq]);
14529
+ if (!r.ok) return { error: git.gitFailureLine(r.stderr) || 'gh api failed' };
14530
+ let n = 0;
14531
+ for (const line of String(r.stdout || '').split('\n')) {
14532
+ if (!line.trim()) continue;
14533
+ let a; try { a = JSON.parse(line); } catch (_) { continue; }
14534
+ n++;
14535
+ seen.set(a[0], {
14536
+ id: a[0], branch: a[1], sha: a[2], event: a[3], workflowName: a[4], status: a[5], conclusion: a[6],
14537
+ attempt: a[7], createdMs: Date.parse(a[8]), updatedMs: Date.parse(a[9]), headCommitMs: a[10] ? Date.parse(a[10]) : null,
14538
+ });
14539
+ }
14540
+ if (i < 3 && n < 100) i = 2; // a short page ends the paged list; the trunk page still runs
14541
+ }
14542
+ return { rows: [...seen.values()], runsRead: seen.size };
14543
+ }
14544
+
14545
+ const ciProfileMemo = new Map();
14546
+
14547
+ /**
14548
+ * The one reader: `{ profile, th, factor, kindTrunk, cache: { state, ageSec, fetchedAt }, notes }`.
14549
+ * `fetch`: 'never' (ship's hot path — never blocks a verdict on a history read) · 'if-stale' ·
14550
+ * 'always'. A stale cache is still used when a refetch fails: old measured data beats bootstrap.
14551
+ * TTL 0 (`COLAB_CI_PROFILE_TTL=0`) means no cache and no fetch — the bootstrap everywhere.
14552
+ */
14553
+ function ciProfileFor(repoAbs, { fetch = 'never' } = {}) {
14554
+ const memoKey = `${repoAbs}\u0000${fetch}`;
14555
+ if (ciProfileMemo.has(memoKey)) return ciProfileMemo.get(memoKey);
14556
+ const doc = projectDoc(repoAbs);
14557
+ const factor = ciProfile.parseFactor(doc);
14558
+ const trunk = resolveTrunk(repoAbs, doc);
14559
+ const notes = [];
14560
+ if (!factor.valid) notes.push(factor.reason);
14561
+ const ttl = ciProfileTtlSec();
14562
+ const file = ttl > 0 ? ciProfileCacheFile(repoAbs) : null;
14563
+ let entry = null;
14564
+ if (file) {
14565
+ try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { entry = null; }
14566
+ if (entry && (entry.v !== CI_PROFILE_CACHE_V || entry.trunk !== trunk || !entry.profile)) entry = null;
14567
+ }
14568
+ const ageSec = entry ? Math.max(0, Math.floor((Date.now() - entry.fetchedAt) / 1000)) : null;
14569
+ let state = entry ? (ageSec < ttl ? 'fresh' : 'stale') : 'none';
14570
+ const want = file && trunk && (fetch === 'always' || (fetch === 'if-stale' && state !== 'fresh'));
14571
+ if (want) {
14572
+ if (!isGhUsable(repoAbs)) notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — CI history not read`);
14573
+ else {
14574
+ const nowMs = Date.now();
14575
+ const sinceMs = nowMs - ciProfile.WINDOW_DAYS * 86_400_000;
14576
+ const got = fetchCiProfileRows(repoAbs, trunk, new Date(sinceMs).toISOString());
14577
+ if (got.error) notes.push(`could not read CI history (${got.error}) — ${entry ? 'using the stale cached profile' : 'using the bootstrap bounds'}`);
14578
+ else {
14579
+ const policy = verifyRuns.parsePolicy(doc);
14580
+ const prof = ciProfile.profile(ciProfile.shaDurations(got.rows, { trunk, policy }), { sinceMs });
14581
+ entry = { v: CI_PROFILE_CACHE_V, trunk, fetchedAt: nowMs, since: new Date(sinceMs).toISOString(), runsRead: got.runsRead, profile: prof };
14582
+ state = 'fetched';
14583
+ try {
14584
+ const tmp = `${file}.${process.pid}.tmp`;
14585
+ fs.writeFileSync(tmp, JSON.stringify(entry));
14586
+ fs.renameSync(tmp, file);
14587
+ } catch (_) { /* no cache, not an error */ }
14588
+ }
14589
+ }
14590
+ }
14591
+ const profile = entry ? entry.profile : null;
14592
+ const out = {
14593
+ trunk, factor, profile, th: ciProfile.thresholds(profile, factor.value),
14594
+ cache: { state, ageSec: state === 'fetched' ? 0 : ageSec, fetchedAt: entry ? new Date(entry.fetchedAt).toISOString() : null,
14595
+ since: entry ? entry.since : null, runsRead: entry ? entry.runsRead : null },
14596
+ notes,
14597
+ };
14598
+ ciProfileMemo.set(memoKey, out);
14599
+ return out;
14600
+ }
14601
+
14480
14602
  // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
14481
14603
  // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
14482
14604
  // requests, a deadline, and a distinct exit code for every way a wait can end.
@@ -14492,9 +14614,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14492
14614
  with no run yet counts as pending until the deadline. An abbreviated sha is
14493
14615
  resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14494
14616
  --branch <b> narrow --sha to runs on that branch
14495
- --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
14617
+ --timeout <d> deadline: 90s, 15m, 1h, or seconds. Default: this repo's CI wait bound, derived
14618
+ from its measured CI duration (\`colab ci-profile\`, #559) — the trunk bound
14619
+ when the target is trunk, the branch bound for any other branch, the larger
14620
+ for a bare run id; 15m while the repo has no CI history. Skills omit it.
14496
14621
 
14497
- Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
14622
+ Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline (a repo whose CI bound is past 15m
14623
+ gets the same schedule stretched in proportion — never a faster one). Every poll after the first is a
14498
14624
  conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14499
14625
  304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14500
14626
  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.
@@ -14509,7 +14635,8 @@ Exit codes — branch on these, never on the text:
14509
14635
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14510
14636
 
14511
14637
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14512
- --json { outcome, exit, target, polls, notModified, forced, waitedSec, detail, status, conclusion, url }`;
14638
+ --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
14639
+ detail, status, conclusion, url }`;
14513
14640
 
14514
14641
  function cmdCiWait(argv) {
14515
14642
  const opts = parseArgs(argv, {
@@ -14522,8 +14649,10 @@ function cmdCiWait(argv) {
14522
14649
  warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
14523
14650
  return ciWait.EXIT.USAGE;
14524
14651
  }
14525
- const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14526
- if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14652
+ let deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14653
+ if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 15m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14654
+ let deadlineBasis = opts.timeout !== undefined ? '--timeout' : 'bootstrap';
14655
+ let schedule = ciWait.DEFAULT_SCHEDULE_SEC;
14527
14656
  const repoAbs = resolveRepo(opts);
14528
14657
  if (opts.sha) {
14529
14658
  // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
@@ -14550,6 +14679,23 @@ function cmdCiWait(argv) {
14550
14679
  return ciWait.EXIT.ALREADY_WAITING;
14551
14680
  }
14552
14681
 
14682
+ // #559: no --timeout → the repo's own bound, one source with every skill (they omit the flag). Read
14683
+ // after the lock, so a refused second waiter never spends a history fetch; a failed read is a note.
14684
+ if (opts.timeout === undefined) {
14685
+ const cp = ciProfileFor(repoAbs, { fetch: 'if-stale' });
14686
+ let onTrunk = null;
14687
+ if (!runId && !opts.branch && cp.trunk) {
14688
+ const remote = git.remoteFor(repoAbs);
14689
+ onTrunk = git.git(['merge-base', '--is-ancestor', opts.sha, `${remote}/${cp.trunk}`], repoAbs).ok;
14690
+ }
14691
+ const kind = ciProfile.kindFor({ branch: opts.branch || null, trunk: cp.trunk, onTrunk });
14692
+ deadlineSec = cp.th.ciWaitDefaultSec[kind];
14693
+ schedule = cp.th.scheduleSec[kind];
14694
+ const b = kind === 'any' ? (cp.th.basis.branchWait === 'measured' || cp.th.basis.trunkWait === 'measured' ? 'measured' : 'bootstrap') : cp.th.basis[`${kind}Wait`];
14695
+ deadlineBasis = `${kind === 'any' ? 'larger' : kind} bound, ${b}`;
14696
+ if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
14697
+ }
14698
+
14553
14699
  const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
14554
14700
  const poll = (etag) => {
14555
14701
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
@@ -14569,11 +14715,11 @@ function cmdCiWait(argv) {
14569
14715
  return { ...r, summary, state: ciWait.runState(summary) };
14570
14716
  };
14571
14717
 
14572
- 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`);
14718
+ 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`);
14573
14719
  let res;
14574
14720
  try {
14575
14721
  res = ciWait.waitLoop({
14576
- poll, sleep: ciWait.sleepSync, deadlineSec,
14722
+ poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
14577
14723
  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`); },
14578
14724
  });
14579
14725
  } finally {
@@ -14583,7 +14729,7 @@ function cmdCiWait(argv) {
14583
14729
  const code = ciWait.EXIT[res.outcome];
14584
14730
  const out = {
14585
14731
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14586
- waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14732
+ waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14587
14733
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14588
14734
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14589
14735
  };
@@ -14644,6 +14790,209 @@ function landedBaseTrunk(repoAbs) {
14644
14790
  'gets measured against the wrong one.)');
14645
14791
  }
14646
14792
 
14793
+ const HELP_BATCH_STATS = `colab batch-stats [--repo <path>] [--since <30d | 12h | YYYY-MM-DD>] [--json]
14794
+
14795
+ How batch landing (#373) actually performs in this repo — read-only, derived from GitHub so it
14796
+ answers the same on any machine (#554). It is how a repo tunes its batch knobs: ship-batch: <N>
14797
+ and ship-batch-wait: <duration> have no handbook default (CONVENTIONS §4, Batch landing).
14798
+
14799
+ Sources: trunk's first-parent log since --since (default 30d) — Ship-Batch: trailers mark batch
14800
+ members, Ship-Batch-Dropped: trailers mark members dropped at build, anything else with a
14801
+ Closes #N is a serial landing — and the repo's CI runs in the same window (REST, paginated):
14802
+ ship-batch/** runs are the combined runs, feature-branch runs say when a branch went green at
14803
+ its head, trunk runs say when a landing was pushed and when its trunk-CI cycle ended.
14804
+
14805
+ Reports:
14806
+ batches landed, and their fill · combined-run builds: first-attempt green, green after the
14807
+ one re-run, red, pending
14808
+ red red builds, and how many of their members then landed serially (the fallback)
14809
+ dropped members dropped at build, by class, and the eviction rate
14810
+ serial serial landings, and MISSED PARTNERS — another change, landed later, that was
14811
+ already green when this one landed alone (could have joined) or went green inside
14812
+ this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys)
14813
+ queue wait green-at-head → landing, per landed change
14814
+
14815
+ No batch history in the window is an answer, not an error: it says so, and still reports the
14816
+ serial side — missed partners are the evidence for turning ship-batch on at all. Not the optional
14817
+ machine-local journal: that is off by default and per-machine, so it cannot be the source.
14818
+ --json is the input for an audit; its shape is batch-stats.js derive()'s return value.
14819
+ Exit 0 on a report (empty or not); 1 when trunk's log cannot be read.
14820
+ `;
14821
+
14822
+ /** `--since`: `<N>d` / `<N>h` / `<N>m` back from now, or an ISO date. → epoch ms, or null. */
14823
+ function batchStatsSince(v, nowMs) {
14824
+ const s = String(v || '30d').trim();
14825
+ const rel = /^(\d+)([dhm])$/.exec(s);
14826
+ if (rel) return nowMs - Number(rel[1]) * ({ d: 86400, h: 3600, m: 60 })[rel[2]] * 1000;
14827
+ const t = Date.parse(s);
14828
+ return Number.isFinite(t) ? t : null;
14829
+ }
14830
+
14831
+ function cmdBatchStats(argv) {
14832
+ const opts = parseArgs(argv, {
14833
+ values: { '--repo': 'repo', '--since': 'since' },
14834
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
14835
+ });
14836
+ if (opts.help) return print(HELP_BATCH_STATS);
14837
+ const repoAbs = resolveRepo(opts);
14838
+ if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone`);
14839
+ const doc = projectDoc(repoAbs);
14840
+ const trunk = resolveTrunk(repoAbs, doc);
14841
+ if (!trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab batch-stats` again');
14842
+ const nowMs = Date.now();
14843
+ const sinceMs = batchStatsSince(opts.since, nowMs);
14844
+ if (sinceMs === null) throw new UserError(`--since ${JSON.stringify(opts.since)}: expected 30d, 12h, 90m or an ISO date`);
14845
+ const sinceIso = new Date(sinceMs).toISOString();
14846
+ const notes = [];
14847
+
14848
+ const remote = git.remoteFor(repoAbs);
14849
+ const f = git.git(['fetch', remote, trunk], repoAbs);
14850
+ if (!f.ok) notes.push(`could not fetch ${remote}/${trunk} (${git.gitFailureLine(f.stderr)}) — read from the local copy, which may be behind`);
14851
+ const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs);
14852
+ if (!log.ok) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — run \`git fetch ${remote} ${trunk}\`, then run this again`);
14853
+ const commits = log.stdout.split('\x1e').map((r) => r.replace(/^\n/, '')).filter((r) => r.trim()).map((r) => {
14854
+ const [sha, iso, body] = r.split('\x1f');
14855
+ return { sha: sha.trim(), dateMs: Date.parse(iso), body: body || '' };
14856
+ });
14857
+
14858
+ let runs = [];
14859
+ const builds = {};
14860
+ if (!isGhUsable(repoAbs)) {
14861
+ notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — trunk commits only: no combined runs, no green times, no partner matching`);
14862
+ } else {
14863
+ 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';
14864
+ // One query per UTC day: GitHub answers at most 1000 rows for a filtered run list, and a busy
14865
+ // repo passes that inside a fortnight. A day that still hits the cap is named, never hidden.
14866
+ const days = [];
14867
+ for (let d = Date.parse(sinceIso.slice(0, 10)); d <= nowMs; d += 86_400_000) days.push(new Date(d).toISOString().slice(0, 10));
14868
+ let failed = null;
14869
+ const capped = [];
14870
+ for (const day of days) {
14871
+ const r = git.ghApi(repoAbs, ['--paginate', `repos/{owner}/{repo}/actions/runs?per_page=100&created=${day}`, '--jq', jq]);
14872
+ if (!r.ok) { failed = git.gitFailureLine(r.stderr); break; }
14873
+ let n = 0;
14874
+ for (const line of String(r.stdout || '').split('\n')) {
14875
+ if (!line.trim()) continue;
14876
+ let a; try { a = JSON.parse(line); } catch (_) { continue; }
14877
+ n++;
14878
+ 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] });
14879
+ }
14880
+ if (n >= 1000) capped.push(day);
14881
+ }
14882
+ if (failed) { notes.push(`could not list CI runs (${failed}) — trunk commits only`); runs = []; }
14883
+ else {
14884
+ if (capped.length) notes.push(`GitHub caps a filtered run list at 1000 and ${capped.join(', ')} hit it — those days are incomplete`);
14885
+ // An unlanded combined run's ref is usually gone: read every commit of the build, so a red
14886
+ // batch's members and its drops are known, not just its head commit's.
14887
+ const landedShas = new Set(commits.map((c) => c.sha));
14888
+ const unlanded = [...new Set(runs.filter((x) => String(x.branch || '').startsWith(shipBatch.REF_PREFIX) && !landedShas.has(x.sha)).map((x) => `${x.branch} ${x.sha}`))];
14889
+ for (const k of unlanded) {
14890
+ const [ref, sha] = k.split(' ');
14891
+ const base7 = (shipBatch.parseBatchRef(ref) || {}).base7;
14892
+ if (!base7) continue;
14893
+ const c = git.ghApi(repoAbs, [`repos/{owner}/{repo}/compare/${base7}...${sha}`, '--jq', '[.commits[].commit.message]']);
14894
+ if (c.ok) { try { builds[sha] = JSON.parse(c.stdout); } catch (_) { /* head message only */ } }
14895
+ }
14896
+ }
14897
+ }
14898
+
14899
+ const cfg = shipBatch.parseShipBatch(doc);
14900
+ const waitCfg = shipBatch.parseShipBatchWait(doc);
14901
+ const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec } });
14902
+ rep.repo = shortRepo(repoAbs);
14903
+ rep.since = sinceIso;
14904
+ rep.until = new Date(nowMs).toISOString();
14905
+ rep.notes = [...notes, ...rep.notes];
14906
+ if (opts.json) { print(JSON.stringify(rep, null, 2)); return 0; }
14907
+
14908
+ const pct = (x) => (x === null ? '—' : `${Math.round(x * 100)}%`);
14909
+ const dur = (s) => (s === null ? '—' : ciWait.fmtDuration(s * 1000));
14910
+ const q = (w) => (w.samples ? `p50 ${dur(w.p50Sec)} · p90 ${dur(w.p90Sec)} · max ${dur(w.maxSec)} (${w.samples})` : 'no samples');
14911
+ 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)}` : ''})`);
14912
+ print(` landings ${rep.landings.total} (${rep.landings.batch} batch · ${rep.landings.serial} serial)`);
14913
+ if (!rep.history) print(' batches no batch history in this window — nothing has landed or been built through colab ship --batch');
14914
+ else {
14915
+ const fill = Object.keys(rep.batches.fill).sort().map((k) => `${rep.batches.fill[k]}×${k}`).join(' · ') || '—';
14916
+ 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`);
14917
+ print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedSerially} then landed serially`);
14918
+ const cls = Object.entries(rep.dropped.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
14919
+ print(` dropped ${rep.dropped.count} of ${rep.dropped.attempted} attempted (${pct(rep.dropped.rate)})${cls ? ` — ${cls}` : ''}`);
14920
+ }
14921
+ 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)`);
14922
+ 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)}`);
14923
+ print(` queue wait green-at-head → landing: ${q(rep.queueWait)}`);
14924
+ for (const n of rep.notes) print(` ! ${n}`);
14925
+ return 0;
14926
+ }
14927
+
14928
+ // ci-profile (#559) — the repo's measured CI duration and every wait bound derived from it.
14929
+ const HELP_CI_PROFILE = `colab ci-profile [--repo <path>] [--json] [--refresh]
14930
+
14931
+ This repo's measured CI duration, and every CI wait bound derived from it (#559). One source:
14932
+ \`colab ci-wait\` with no --timeout, and \`colab ship\`'s wedged-run and empty-read verdicts, read
14933
+ these same numbers — no skill hard-codes a wait.
14934
+
14935
+ Measured: per sha, the wall time from the first verifying run's creation to the last one's
14936
+ finish, over clean first-attempt green shas in the last ${ciProfile.WINDOW_DAYS} days — split into branch runs and trunk
14937
+ runs — plus the push → run lag on trunk. A kind with fewer than ${ciProfile.MIN_SAMPLES} samples stays on its
14938
+ bootstrap value, which is today's fleet value exactly (15m waits, 6h wedge, 10m grace, 2m floor).
14939
+
14940
+ Declared: only \`ci-wait-factor: <number ≥ 1>\` in .github/project.yml (default ${ciProfile.DEFAULT_FACTOR}) — how many times
14941
+ the measured p95 a repo will wait. Every bound:
14942
+ branch / trunk wait 2m + factor × p95 of that kind, rounded up to the minute
14943
+ wedged-run age factor × the longer wait, never above 6h
14944
+ empty-read grace factor × push→run p95, never below 2m
14945
+ zero-jobs floor 2m (not measurable from the run list)
14946
+ poll backoff 30/60/120s, stretched in proportion to a wait past 15m — never faster
14947
+
14948
+ The profile is cached per checkout for a day (<git common dir>/colab-ci-profile.json;
14949
+ COLAB_CI_PROFILE_TTL seconds overrides, 0 = no cache and no read: the bootstrap). The bounds are
14950
+ recomputed from it on every read, so a changed ci-wait-factor applies at once.
14951
+
14952
+ --refresh re-read the CI history now, whatever the cache's age
14953
+ --json { repo, trunk, source, factor, cache, measured: { branch, trunk, lag }, thresholds, notes }`;
14954
+
14955
+ function cmdCiProfile(argv) {
14956
+ const opts = parseArgs(argv, {
14957
+ values: { '--repo': 'repo' },
14958
+ flags: { '--json': 'json', '--refresh': 'refresh', '-h': 'help', '--help': 'help' },
14959
+ });
14960
+ if (opts.help) return print(HELP_CI_PROFILE);
14961
+ const repoAbs = resolveRepo(opts);
14962
+ 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`);
14963
+ const cp = ciProfileFor(repoAbs, { fetch: opts.refresh ? 'always' : 'if-stale' });
14964
+ if (!cp.trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab ci-profile` again');
14965
+ const p = cp.profile || ciProfile.profile([]);
14966
+ const th = cp.th;
14967
+ const source = cp.profile ? cp.profile.source : 'bootstrap';
14968
+ if (opts.json) {
14969
+ print(JSON.stringify({
14970
+ repo: shortRepo(repoAbs), trunk: cp.trunk, source, factor: cp.factor, cache: cp.cache,
14971
+ measured: { branch: p.branch, trunk: p.trunk, lag: p.lag }, thresholds: th, notes: cp.notes,
14972
+ }, null, 2));
14973
+ return 0;
14974
+ }
14975
+ const dur = (s) => (s === null || s === undefined ? '—' : ciWait.fmtDuration(s * 1000));
14976
+ const cacheTxt = cp.cache.state === 'fetched' ? 'read now'
14977
+ : cp.cache.state === 'none' ? 'no history read' : `read ${dur(cp.cache.ageSec)} ago (cache${cp.cache.state === 'stale' ? ', stale' : ''})`;
14978
+ 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)`}`);
14979
+ 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`);
14980
+ 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)}` : ''}`);
14981
+ k('branch', p.branch);
14982
+ k('trunk', p.trunk);
14983
+ print(` ${'push→run'.padEnd(11)} ${p.lag.source} · ${p.lag.samples} sample(s)${p.lag.samples ? ` · p95 ${dur(p.lag.p95Sec)}` : ''}`);
14984
+ 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})` : ''}`);
14985
+ row('branch wait', th.branchWaitSec, th.basis.branchWait, `2m + ${th.factor} × p95`, '15m');
14986
+ row('trunk wait', th.trunkWaitSec, th.basis.trunkWait, `2m + ${th.factor} × p95`, '15m');
14987
+ 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)`);
14988
+ row('wedged age', th.wedgeAgeSec, th.basis.wedgeAge, `${th.factor} × the longer wait, ≤ 6h`, '6h');
14989
+ row('empty read', th.emptyReadGraceSec, th.basis.emptyReadGrace, `${th.factor} × push→run p95, ≥ 2m`, '10m');
14990
+ row('zero jobs', th.zeroJobsFloorSec, th.basis.zeroJobsFloor, 'default — not measurable from the run list');
14991
+ print(` ${'backoff'.padEnd(11)} branch ${th.scheduleSec.branch.map((x) => `${x}s`).join('/')} · trunk ${th.scheduleSec.trunk.map((x) => `${x}s`).join('/')}`);
14992
+ for (const n of cp.notes) print(` ! ${n}`);
14993
+ return 0;
14994
+ }
14995
+
14647
14996
  function cmdLanded(argv) {
14648
14997
  const opts = parseArgs(argv, {
14649
14998
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15428,6 +15777,11 @@ Commands:
15428
15777
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
15429
15778
  (the shared rule behind code-sweep's buckets — correct
15430
15779
  across squash merges, where "commits ahead" is not)
15780
+ batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
15781
+ fill, first-attempt green, drops, missed partners, queue
15782
+ wait; how a repo tunes ship-batch / ship-batch-wait (#554)
15783
+ ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
15784
+ derived from it — ci-wait's default deadline (#559)
15431
15785
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15432
15786
  have not landed on the base (filters the raw git-log
15433
15787
  one-liner through \`landed\`'s content classification)
@@ -15512,6 +15866,8 @@ function main(argv) {
15512
15866
  case 'worktrees': return cmdWorktrees(rest);
15513
15867
  case 'ship': return cmdShip(rest);
15514
15868
  case 'landed': return cmdLanded(rest);
15869
+ case 'batch-stats': return cmdBatchStats(rest);
15870
+ case 'ci-profile': return cmdCiProfile(rest);
15515
15871
  case 'trunk-ci': return cmdTrunkCi(rest);
15516
15872
  case 'ci-wait': return cmdCiWait(rest);
15517
15873
  case 'holders': return cmdHolders(rest);
@@ -0,0 +1,273 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/batch-stats.js — how batch landing (#373) actually performs in ONE repo (#554).
4
+ *
5
+ * The batch knobs (`ship-batch: <N>`, `ship-batch-wait: <duration>`) have no handbook default: a repo
6
+ * picks them from its own history. This module is that history, derived from two sources every
7
+ * machine can read — never from the optional machine-local journal, which is off by default and
8
+ * per-machine:
9
+ *
10
+ * commits trunk's first-parent log. A batch member's squash carries `Ship-Batch: <ref>
11
+ * <branch>@<sha>` (ship-batch.js memberTrailer); a member dropped at build is recorded on
12
+ * the batch head as `Ship-Batch-Dropped: <ref> <branch>@<sha> <class>`. A trunk commit
13
+ * with neither is a serial landing, known by its `Closes #N`.
14
+ * runs the repo's CI runs (REST rows). Runs on `ship-batch/**` are the combined runs; runs on
15
+ * a feature branch say when that branch went green at its head; runs on trunk say when a
16
+ * landing was pushed (created) and when its trunk-CI cycle ended (updated).
17
+ *
18
+ * Pure: facts in, a report out — no git, no gh, no clock. `tools/colab`'s `cmdBatchStats` reads.
19
+ *
20
+ * What it measures, per window:
21
+ * batches landed and their fill; every combined-run build, first-attempt green, green after
22
+ * the one re-run, red, still pending
23
+ * red red builds and how many of their members then landed serially (the fallback)
24
+ * dropped members dropped at build, by class, and the eviction rate among attempted members
25
+ * serial serial landings, and MISSED PARTNERS: another candidate that landed later but was
26
+ * already green when this one landed alone (could have joined), or turned green
27
+ * within this landing's trunk-CI cycle (a partner wait of `waitSec` would have caught
28
+ * it — the number `ship-batch-wait` is tuned from)
29
+ * queueWait per landed change, green-at-head → landing
30
+ */
31
+
32
+ const branchName = require('./branch-name');
33
+ const shipBatch = require('./ship-batch');
34
+
35
+ /** `Closes #N` / `Fixes #N` / `Resolves #N` numbers in a commit body (GitHub's own keywords). */
36
+ function closesIssues(body) {
37
+ const out = new Set();
38
+ const re = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b/gi;
39
+ let m;
40
+ while ((m = re.exec(String(body || '')))) out.add(Number(m[1]));
41
+ return [...out];
42
+ }
43
+
44
+ /** Value at the q-th quantile (nearest-rank) of numbers, or null for none. */
45
+ function quantile(values, q) {
46
+ const v = (values || []).filter(Number.isFinite).sort((a, b) => a - b);
47
+ if (!v.length) return null;
48
+ return v[Math.min(v.length - 1, Math.max(0, Math.ceil(q * v.length) - 1))];
49
+ }
50
+
51
+ function summary(values) {
52
+ const v = (values || []).filter(Number.isFinite);
53
+ return { samples: v.length, p50Sec: quantile(v, 0.5), p90Sec: quantile(v, 0.9), maxSec: v.length ? Math.max(...v) : null };
54
+ }
55
+
56
+ const rate = (num, den) => (den > 0 ? Math.round((num / den) * 1000) / 1000 : null);
57
+ const isBatchRef = (b) => String(b || '').startsWith(shipBatch.REF_PREFIX);
58
+
59
+ /**
60
+ * When did `branch` go green at the head it had at time `atMs`? Its runs created before `atMs` are
61
+ * read; the newest sha among them is the head at that moment. Green only when every run at that sha
62
+ * finished success (cancelled aside, as combinedVerdict reads it) by `atMs` → the latest finish.
63
+ * Null when there is no run, or the head was not green yet — unknown, never a guess.
64
+ */
65
+ function greenAt(runsByBranch, branch, atMs, sha = null) {
66
+ const rows = (runsByBranch.get(branch) || []).filter((r) => r.createdMs <= atMs);
67
+ if (!rows.length) return null;
68
+ const headSha = sha
69
+ ? (rows.some((r) => r.sha.startsWith(sha) || sha.startsWith(r.sha)) ? rows.find((r) => r.sha.startsWith(sha) || sha.startsWith(r.sha)).sha : null)
70
+ : rows.reduce((a, b) => (b.createdMs > a.createdMs ? b : a)).sha;
71
+ if (!headSha) return null;
72
+ const at = rows.filter((r) => r.sha === headSha);
73
+ const v = shipBatch.combinedVerdict(at.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt })));
74
+ if (v.state !== 'green') return null;
75
+ const done = Math.max(...at.filter((r) => r.conclusion === 'success').map((r) => r.updatedMs));
76
+ return done <= atMs ? done : null;
77
+ }
78
+
79
+ /** Which feature branch carried a serial landing that closed `issues`, as of `atMs`? Newest run wins. */
80
+ function branchForIssues(runsByBranch, issues, atMs) {
81
+ if (!issues.length) return null;
82
+ let best = null;
83
+ for (const [b, rows] of runsByBranch) {
84
+ const nums = branchName.branchIssueNumbers(b);
85
+ if (!nums.some((n) => issues.includes(n))) continue;
86
+ const before = rows.filter((r) => r.createdMs <= atMs);
87
+ if (!before.length) continue;
88
+ const t = Math.max(...before.map((r) => r.createdMs));
89
+ if (!best || t > best.t) best = { branch: b, t };
90
+ }
91
+ return best ? best.branch : null;
92
+ }
93
+
94
+ /**
95
+ * The report. Inputs:
96
+ * commits [{ sha, dateMs, body }] — trunk first-parent, inside the window, any order
97
+ * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message? }]
98
+ * `message` is the head commit's message, needed only for ship-batch/** rows
99
+ * builds optional { [sha]: [message, …] } — every commit message of an UNLANDED build, when the
100
+ * caller could read them (compare API); a landed build is read from trunk instead
101
+ * trunk trunk branch name
102
+ * config { n, waitSec } — the repo's declared knobs, echoed so the report says what it tunes
103
+ */
104
+ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {} } = {}) {
105
+ const notes = [];
106
+ const runsByBranch = new Map();
107
+ const trunkRuns = new Map(); // sha → rows
108
+ const batchRuns = new Map(); // `${ref} ${sha}` → rows
109
+ for (const r of runs || []) {
110
+ if (!r || !r.branch || !r.sha) continue;
111
+ if (r.branch === trunk) { (trunkRuns.get(r.sha) || trunkRuns.set(r.sha, []).get(r.sha)).push(r); continue; }
112
+ if (isBatchRef(r.branch)) { const k = `${r.branch} ${r.sha}`; (batchRuns.get(k) || batchRuns.set(k, []).get(k)).push(r); continue; }
113
+ (runsByBranch.get(r.branch) || runsByBranch.set(r.branch, []).get(r.branch)).push(r);
114
+ }
115
+ // When a landing reached trunk: its trunk push run was created then. Fallback: the commit date
116
+ // (a fast-forward keeps the build-time date, so it reads early by the combined run's length).
117
+ const landedAt = (sha, fallback) => {
118
+ const rows = trunkRuns.get(sha) || [];
119
+ return rows.length ? Math.min(...rows.map((r) => r.createdMs)) : fallback;
120
+ };
121
+ const cycleEnd = (sha) => {
122
+ const rows = (trunkRuns.get(sha) || []).filter((r) => r.status === 'completed');
123
+ return rows.length ? Math.max(...rows.map((r) => r.updatedMs)) : null;
124
+ };
125
+
126
+ // ---- landings, oldest first ----
127
+ const sorted = [...(commits || [])].sort((a, b) => a.dateMs - b.dateMs);
128
+ const batches = new Map(); // ref → { ref, commits: [], members: [], dropped: [] }
129
+ const landings = []; // { kind, sha, atMs, members: [{ branch, sha }], issues }
130
+ for (const c of sorted) {
131
+ const members = shipBatch.parseMemberTrailers([c.body]);
132
+ if (members.length) {
133
+ const ref = members[0].ref;
134
+ const b = batches.get(ref) || batches.set(ref, { ref, commits: [], members: [], dropped: [] }).get(ref);
135
+ b.commits.push(c);
136
+ b.members.push(...members);
137
+ b.dropped.push(...shipBatch.parseDroppedTrailers([c.body]));
138
+ } else {
139
+ landings.push({ kind: 'serial', sha: c.sha, atMs: landedAt(c.sha, c.dateMs), commitMs: c.dateMs, issues: closesIssues(c.body) });
140
+ }
141
+ }
142
+ for (const b of batches.values()) {
143
+ const head = b.commits[b.commits.length - 1];
144
+ b.headSha = head.sha;
145
+ landings.push({ kind: 'batch', ref: b.ref, sha: head.sha, atMs: landedAt(head.sha, head.dateMs), commitMs: head.dateMs, members: b.members });
146
+ }
147
+ landings.sort((a, b) => a.atMs - b.atMs);
148
+
149
+ // ---- every landed change, with its green-at-head time ----
150
+ const changes = []; // { landing, branch, sha, issues, greenMs, atMs }
151
+ for (const l of landings) {
152
+ if (l.kind === 'batch') {
153
+ for (const m of l.members) {
154
+ changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha), atMs: l.atMs });
155
+ }
156
+ } else {
157
+ const br = branchForIssues(runsByBranch, l.issues, l.atMs);
158
+ l.branch = br;
159
+ changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs) : null, atMs: l.atMs });
160
+ }
161
+ }
162
+
163
+ // ---- combined-run builds ----
164
+ const landedHeads = new Set([...batches.values()].map((b) => b.headSha));
165
+ const buildRows = [];
166
+ for (const [k, rows] of batchRuns) {
167
+ const [ref, sha] = k.split(' ');
168
+ const v = shipBatch.combinedVerdict(rows.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id })));
169
+ const landed = landedHeads.has(sha);
170
+ const messages = landed ? null : (builds[sha] || rows.map((r) => r.message).filter(Boolean).slice(0, 1));
171
+ buildRows.push({ ref, sha, state: v.state, attempt: v.attempt, landed, createdMs: Math.min(...rows.map((r) => r.createdMs)), messages });
172
+ }
173
+ const finished = buildRows.filter((b) => b.state === 'green' || b.state === 'red');
174
+ const firstGreen = buildRows.filter((b) => b.state === 'green' && b.attempt === 1).length;
175
+ const rerunGreen = buildRows.filter((b) => b.state === 'green' && b.attempt > 1).length;
176
+ const redBuilds = buildRows.filter((b) => b.state === 'red');
177
+
178
+ // ---- red builds → did their members then land serially? ----
179
+ const serialChanges = changes.filter((c) => c.landing.kind === 'serial');
180
+ let redMembers = 0, relanded = 0, redMembersUnread = 0;
181
+ for (const b of redBuilds) {
182
+ const members = b.messages && b.messages.length ? shipBatch.parseMemberTrailers(b.messages) : [];
183
+ if (!members.length) { redMembersUnread++; continue; }
184
+ for (const m of members) {
185
+ redMembers++;
186
+ const nums = branchName.branchIssueNumbers(m.branch);
187
+ if (serialChanges.some((c) => c.atMs >= b.createdMs && (c.branch === m.branch || c.issues.some((n) => nums.includes(n))))) relanded++;
188
+ }
189
+ }
190
+ if (redMembersUnread) notes.push(`${redMembersUnread} red build(s) whose members could not be read (the ref is gone and its commits were not readable)`);
191
+
192
+ // ---- dropped members: landed batches from trunk, unlanded builds from their messages ----
193
+ const dropped = [];
194
+ const seenDrop = new Set();
195
+ const addDrop = (d, landed) => {
196
+ const k = `${d.ref} ${d.branch}@${d.sha}`;
197
+ if (seenDrop.has(k)) return;
198
+ seenDrop.add(k);
199
+ dropped.push({ ...d, landed });
200
+ };
201
+ for (const b of batches.values()) for (const d of b.dropped) addDrop(d, true);
202
+ for (const b of buildRows) if (!b.landed && b.messages) for (const d of shipBatch.parseDroppedTrailers(b.messages)) addDrop(d, false);
203
+ const builtMembers = [...batches.values()].reduce((n, b) => n + b.members.length, 0)
204
+ + buildRows.filter((b) => !b.landed && b.messages).reduce((n, b) => n + shipBatch.parseMemberTrailers(b.messages).length, 0);
205
+ const byClass = {};
206
+ for (const d of dropped) byClass[d.cls] = (byClass[d.cls] || 0) + 1;
207
+
208
+ // ---- missed partners: serial landings that landed alone while a partner was (nearly) ready ----
209
+ const pairs = [];
210
+ let withMissed = 0, withNear = 0, cyclesUnread = 0;
211
+ // A partner is judged by ITS state at this landing's moment, never by the head it finally landed
212
+ // with: a serial ship syncs the other branches, so their final heads all post-date it. The cycle
213
+ // ends when this landing's trunk run finishes — or at the next landing, whichever is first (a
214
+ // re-run moves a run's updated_at hours later, and the next landing moves trunk anyway).
215
+ const landingTimes = landings.map((l) => l.atMs).sort((a, b) => a - b);
216
+ for (const c of serialChanges) {
217
+ const next = landingTimes.find((t) => t > c.atMs);
218
+ let end = cycleEnd(c.landing.sha);
219
+ if (end === null) cyclesUnread++;
220
+ else if (next !== undefined) end = Math.min(end, next);
221
+ let missed = false, near = false;
222
+ const label = c.branch || c.landing.sha.slice(0, 7);
223
+ for (const o of changes) {
224
+ if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
225
+ const gNow = greenAt(runsByBranch, o.branch, c.atMs);
226
+ if (gNow !== null) {
227
+ missed = true;
228
+ pairs.push({ kind: 'missed', landed: label, partner: o.branch });
229
+ continue;
230
+ }
231
+ if (end === null) continue;
232
+ const gEnd = greenAt(runsByBranch, o.branch, end);
233
+ if (gEnd !== null && gEnd > c.atMs) {
234
+ near = true;
235
+ const from = c.greenMs !== null ? c.greenMs : c.atMs;
236
+ pairs.push({ kind: 'near', landed: label, partner: o.branch, waitSec: Math.round((gEnd - from) / 1000) });
237
+ }
238
+ }
239
+ if (missed) withMissed++;
240
+ else if (near) withNear++;
241
+ }
242
+ if (cyclesUnread) notes.push(`${cyclesUnread} serial landing(s) with no finished trunk run in the window — near misses not judged for them`);
243
+ const unknownGreen = changes.filter((c) => c.greenMs === null).length;
244
+ if (unknownGreen) notes.push(`${unknownGreen} landed change(s) with no readable green-at-head run — left out of queue wait and partner matching`);
245
+
246
+ const fill = {};
247
+ for (const b of batches.values()) fill[b.members.length] = (fill[b.members.length] || 0) + 1;
248
+ const queueWait = summary(changes.filter((c) => c.greenMs !== null).map((c) => Math.round((c.atMs - c.greenMs) / 1000)));
249
+
250
+ return {
251
+ trunk,
252
+ config: { n: config.n || 1, waitSec: config.waitSec || 0 },
253
+ history: batches.size > 0 || buildRows.length > 0,
254
+ landings: { total: landings.length, batch: batches.size, serial: landings.length - batches.size },
255
+ batches: {
256
+ landed: batches.size, fill,
257
+ builds: buildRows.length, firstAttemptGreen: firstGreen, greenAfterRerun: rerunGreen, red: redBuilds.length,
258
+ pending: buildRows.length - finished.length,
259
+ firstAttemptGreenRate: rate(firstGreen, finished.length),
260
+ },
261
+ red: { builds: redBuilds.length, members: redMembers, relandedSerially: relanded },
262
+ dropped: { count: dropped.length, attempted: builtMembers + dropped.length, rate: rate(dropped.length, builtMembers + dropped.length), byClass, members: dropped },
263
+ serial: {
264
+ landings: serialChanges.length, withMissedPartner: withMissed, withNearMiss: withNear,
265
+ nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
266
+ pairs,
267
+ },
268
+ queueWait,
269
+ notes,
270
+ };
271
+ }
272
+
273
+ module.exports = { derive, closesIssues, quantile, greenAt, branchForIssues };
@@ -0,0 +1,195 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/ci-profile.js — a repo's measured CI duration, and every CI wait bound derived from it (#559).
4
+ *
5
+ * Before this module every CI wait was a fleet-wide constant, and two of them disagreed: the skills
6
+ * passed `--timeout 15m` to `colab ci-wait` everywhere while its own default was 45 minutes, so a
7
+ * caller that omitted the flag silently waited three times as long. Repos' CI ranges from a few
8
+ * minutes to nearly half an hour, so one number was too long for a fast repo and too short for a
9
+ * slow one.
10
+ *
11
+ * The rule (epic #558): a threshold that depends on a repo's nature comes from THAT repo. Here the
12
+ * duration is MEASURED from the repo's own CI history; the only DECLARED part is the multiple of it
13
+ * a repo is willing to wait (`ci-wait-factor`, default 2). Where nothing has been measured yet, each
14
+ * bound is today's value exactly — documented as the bootstrap, never a different behaviour.
15
+ *
16
+ * Pure: run rows in, a profile and thresholds out — no git, no gh, no clock. `tools/colab` fetches
17
+ * (`fetchCiProfileRows`), caches (`ciProfileFor`) and prints (`cmdCiProfile`).
18
+ *
19
+ * What is measured, per sha: the wall time from the first run's creation to the last run's last
20
+ * update, across every run that verifies the code at that sha (verify-runs.js, the same set
21
+ * `ci-wait --sha` waits on). That is exactly the wait a session sits through: "every run at the sha
22
+ * has finished". Only clean first-attempt green shas count — a re-run measures an incident, a red
23
+ * run measures how fast it failed.
24
+ */
25
+
26
+ const ciWait = require('./ci-wait');
27
+ const ciVerdict = require('./ci-verdict');
28
+ const verifyRuns = require('./verify-runs');
29
+ const { quantile } = require('./batch-stats');
30
+
31
+ const FACTOR_KEY = 'ci-wait-factor';
32
+ const DEFAULT_FACTOR = 2;
33
+ /** A kind with fewer clean green shas than this in the window stays on its bootstrap value. */
34
+ const MIN_SAMPLES = 10;
35
+ const WINDOW_DAYS = 30;
36
+
37
+ /**
38
+ * The one platform constant: how long GitHub may take to start a run and materialize its job list
39
+ * (ci-verdict's zero-jobs floor). It floors every derived bound — a 20-second CI must not produce a
40
+ * wait shorter than the time a run can take to appear at all. Not repo-measurable at run-list cost:
41
+ * `run_started_at` equals `created_at` on every row we read, so the list carries no queue signal.
42
+ */
43
+ const PLATFORM_FLOOR_SEC = ciVerdict.ZERO_JOBS_AGE_FLOOR_MINUTES * 60;
44
+
45
+ /**
46
+ * Today's values, exactly — what a repo with no history gets, built from the constants that hold
47
+ * them rather than restated. The 6 h wedge age is also a CAP: it is the hosted-runner job limit, so
48
+ * measurement may only lower it (a safety limit a repo may only tighten, epic #558). Likewise the
49
+ * 30/60/120 s poll schedule is a REST-quota floor — measurement may only stretch it.
50
+ */
51
+ const BOOTSTRAP = Object.freeze({
52
+ branchWaitSec: 15 * 60,
53
+ trunkWaitSec: 15 * 60,
54
+ wedgeAgeSec: ciVerdict.WEDGE_AGE_HOURS * 3600,
55
+ emptyReadGraceSec: ciVerdict.EMPTY_READ_GRACE_MINUTES * 60,
56
+ zeroJobsFloorSec: PLATFORM_FLOOR_SEC,
57
+ scheduleSec: ciWait.DEFAULT_SCHEDULE_SEC,
58
+ });
59
+
60
+ /**
61
+ * `ci-wait-factor: <number ≥ 1>` — absent → 2. A malformed value falls back to the documented
62
+ * default (never to a different behaviour) and is reported; the audit fails it.
63
+ */
64
+ function parseFactor(doc) {
65
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, FACTOR_KEY) && doc[FACTOR_KEY] !== null && doc[FACTOR_KEY] !== undefined;
66
+ if (!has) return { value: DEFAULT_FACTOR, declared: false, valid: true, reason: `${FACTOR_KEY}: ${DEFAULT_FACTOR} (default)` };
67
+ const raw = doc[FACTOR_KEY];
68
+ const n = typeof raw === 'number' ? raw : (typeof raw === 'string' && /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : NaN);
69
+ if (!Number.isFinite(n) || n < 1) {
70
+ return { value: DEFAULT_FACTOR, declared: true, valid: false,
71
+ reason: `${FACTOR_KEY} must be a number ≥ 1 (a multiple of the measured CI duration), got ${JSON.stringify(raw)} — using ${DEFAULT_FACTOR}` };
72
+ }
73
+ return { value: n, declared: true, valid: true, reason: `${FACTOR_KEY}: ${n}` };
74
+ }
75
+
76
+ /**
77
+ * Rows → one wall time per clean green sha. A row: `{ sha, branch, event, workflowName, status,
78
+ * conclusion, attempt, createdMs, updatedMs, headCommitMs }`.
79
+ *
80
+ * A branch group at a sha that is also a trunk sha is dropped: a branch cut moments ago re-runs
81
+ * trunk's content, and those near-instant runs would drag the branch duration down.
82
+ */
83
+ function shaDurations(rows, { trunk, policy = null } = {}) {
84
+ const groups = new Map();
85
+ for (const r of rows || []) {
86
+ if (!r || !r.sha || r.event === 'dynamic') continue;
87
+ const key = `${r.branch || ''}\u0000${r.sha}`;
88
+ if (!groups.has(key)) groups.set(key, []);
89
+ groups.get(key).push(r);
90
+ }
91
+ const trunkShas = new Set([...groups.values()].filter((g) => g[0].branch === trunk).map((g) => g[0].sha));
92
+ const out = [];
93
+ for (const g of groups.values()) {
94
+ const split = verifyRuns.splitVerifying(g, policy);
95
+ const counted = split ? split.counted : g;
96
+ if (!counted.length) continue;
97
+ if (!counted.every((r) => r.status === 'completed')) continue;
98
+ if (!counted.every((r) => ['success', 'skipped', 'neutral'].includes(r.conclusion))) continue;
99
+ if (!counted.some((r) => r.conclusion === 'success')) continue;
100
+ if (counted.some((r) => Number(r.attempt) > 1)) continue;
101
+ const created = Math.min(...counted.map((r) => r.createdMs));
102
+ const ended = Math.max(...counted.map((r) => r.updatedMs));
103
+ if (!Number.isFinite(created) || !Number.isFinite(ended) || ended < created) continue;
104
+ const kind = g[0].branch === trunk ? 'trunk' : 'branch';
105
+ if (kind === 'branch' && trunkShas.has(g[0].sha)) continue;
106
+ let lagSec = null;
107
+ if (kind === 'trunk') {
108
+ const c = Math.min(...counted.map((r) => r.headCommitMs).filter(Number.isFinite));
109
+ if (Number.isFinite(c) && created >= c) lagSec = Math.round((created - c) / 1000);
110
+ }
111
+ out.push({ sha: g[0].sha, kind, sec: Math.round((ended - created) / 1000), lagSec, endMs: ended });
112
+ }
113
+ return out;
114
+ }
115
+
116
+ function stats(values) {
117
+ const v = values.filter(Number.isFinite);
118
+ return {
119
+ source: v.length >= MIN_SAMPLES ? 'measured' : 'bootstrap',
120
+ samples: v.length,
121
+ p50Sec: quantile(v, 0.5),
122
+ p95Sec: quantile(v, 0.95),
123
+ maxSec: v.length ? Math.max(...v) : null,
124
+ };
125
+ }
126
+
127
+ /** Durations → `{ branch, trunk, lag, source }`; only samples ending at or after `sinceMs` count. */
128
+ function profile(durations, { sinceMs = null } = {}) {
129
+ const d = (durations || []).filter((x) => sinceMs === null || x.endMs >= sinceMs);
130
+ const branch = stats(d.filter((x) => x.kind === 'branch').map((x) => x.sec));
131
+ const trunk = stats(d.filter((x) => x.kind === 'trunk').map((x) => x.sec));
132
+ const lagV = d.filter((x) => x.kind === 'trunk' && x.lagSec !== null).map((x) => x.lagSec);
133
+ const lag = { source: lagV.length >= MIN_SAMPLES ? 'measured' : 'bootstrap', samples: lagV.length, p95Sec: quantile(lagV, 0.95) };
134
+ const n = [branch, trunk].filter((k) => k.source === 'measured').length;
135
+ return { branch, trunk, lag, source: n === 2 ? 'measured' : n === 0 ? 'bootstrap' : 'partial' };
136
+ }
137
+
138
+ const ceilMinute = (sec) => Math.ceil(sec / 60) * 60;
139
+
140
+ /** A kind's wait bound: GitHub must start the run, then `factor` times what it takes at p95. */
141
+ function boundFor(k, factor, bootstrapSec) {
142
+ if (!k || k.source !== 'measured' || !Number.isFinite(k.p95Sec)) return { sec: bootstrapSec, basis: 'bootstrap' };
143
+ return { sec: ceilMinute(PLATFORM_FLOOR_SEC + factor * k.p95Sec), basis: 'measured' };
144
+ }
145
+
146
+ /** The schedule for a bound: 30/60/120 s stretched in proportion to a bound past 15 min, never shrunk. */
147
+ function scheduleFor(boundSec) {
148
+ const k = Math.max(1, boundSec / BOOTSTRAP.branchWaitSec);
149
+ return BOOTSTRAP.scheduleSec.map((s) => Math.round(s * k));
150
+ }
151
+
152
+ /**
153
+ * Profile + factor → every threshold, each with the basis it came from. A null profile (nothing
154
+ * read, no cache) is the bootstrap in full.
155
+ */
156
+ function thresholds(prof, factor = DEFAULT_FACTOR) {
157
+ const f = Number.isFinite(factor) && factor >= 1 ? factor : DEFAULT_FACTOR;
158
+ const p = prof || {};
159
+ const branch = boundFor(p.branch, f, BOOTSTRAP.branchWaitSec);
160
+ const trunk = boundFor(p.trunk, f, BOOTSTRAP.trunkWaitSec);
161
+ const anyMeasured = branch.basis === 'measured' || trunk.basis === 'measured';
162
+ const wedgeAgeSec = anyMeasured ? Math.min(BOOTSTRAP.wedgeAgeSec, ceilMinute(f * Math.max(branch.sec, trunk.sec))) : BOOTSTRAP.wedgeAgeSec;
163
+ const lagMeasured = p.lag && p.lag.source === 'measured' && Number.isFinite(p.lag.p95Sec);
164
+ const emptyReadGraceSec = lagMeasured ? Math.max(PLATFORM_FLOOR_SEC, ceilMinute(f * p.lag.p95Sec)) : BOOTSTRAP.emptyReadGraceSec;
165
+ return {
166
+ factor: f,
167
+ branchWaitSec: branch.sec,
168
+ trunkWaitSec: trunk.sec,
169
+ ciWaitDefaultSec: { branch: branch.sec, trunk: trunk.sec, any: Math.max(branch.sec, trunk.sec) },
170
+ wedgeAgeSec,
171
+ emptyReadGraceSec,
172
+ zeroJobsFloorSec: BOOTSTRAP.zeroJobsFloorSec,
173
+ scheduleSec: { branch: scheduleFor(branch.sec), trunk: scheduleFor(trunk.sec), any: scheduleFor(Math.max(branch.sec, trunk.sec)) },
174
+ basis: {
175
+ branchWait: branch.basis,
176
+ trunkWait: trunk.basis,
177
+ wedgeAge: anyMeasured ? 'measured' : 'bootstrap',
178
+ emptyReadGrace: lagMeasured ? 'measured' : 'bootstrap',
179
+ zeroJobsFloor: 'default',
180
+ },
181
+ };
182
+ }
183
+
184
+ /** Which bound a wait uses: trunk when the target is trunk, branch for any other branch, else `any`. */
185
+ function kindFor({ branch = null, trunk = null, onTrunk = null } = {}) {
186
+ if (branch) return branch === trunk ? 'trunk' : 'branch';
187
+ if (onTrunk === true) return 'trunk';
188
+ if (onTrunk === false) return 'branch';
189
+ return 'any';
190
+ }
191
+
192
+ module.exports = {
193
+ FACTOR_KEY, DEFAULT_FACTOR, MIN_SAMPLES, WINDOW_DAYS, PLATFORM_FLOOR_SEC, BOOTSTRAP,
194
+ parseFactor, shaDurations, profile, thresholds, scheduleFor, kindFor,
195
+ };
@@ -72,24 +72,30 @@ function hoursSince(iso, nowMs) {
72
72
  function wedgedVerdict(run, opts = {}) {
73
73
  if (!run || run.status === 'completed' || run.status === 'none') return { wedged: false, reason: null };
74
74
  const age = hoursSince(run.createdAt, opts.nowMs);
75
+ // #559: both bounds may come from the repo's measured CI (tools/lib/ci-profile.js); absent → today's.
76
+ const floorMin = Number.isFinite(opts.zeroJobsFloorSec) ? opts.zeroJobsFloorSec / 60 : ZERO_JOBS_AGE_FLOOR_MINUTES;
77
+ const wedgeHours = Number.isFinite(opts.wedgeAgeSec) ? opts.wedgeAgeSec / 3600 : WEDGE_AGE_HOURS;
75
78
  if (run.jobCount === 0) {
76
79
  // #171: no createdAt (age unknown) never manufactures a positive here, same posture as the age
77
80
  // backstop below when createdAt is missing/unparseable — a missing signal must not wedge on its own.
78
- const floorHours = ZERO_JOBS_AGE_FLOOR_MINUTES / 60;
81
+ const floorHours = floorMin / 60;
79
82
  if (age !== null && age >= floorHours) {
80
83
  return {
81
84
  wedged: true,
82
- reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${ZERO_JOBS_AGE_FLOOR_MINUTES}m floor)`,
85
+ reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${fmtMin(floorMin)} floor)`,
83
86
  };
84
87
  }
85
88
  return { wedged: false, reason: null };
86
89
  }
87
- if (age !== null && age >= WEDGE_AGE_HOURS) {
88
- return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${WEDGE_AGE_HOURS}h backstop)` };
90
+ if (age !== null && age >= wedgeHours) {
91
+ return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${fmtHours(wedgeHours)} backstop)` };
89
92
  }
90
93
  return { wedged: false, reason: null };
91
94
  }
92
95
 
96
+ const fmtMin = (m) => `${Number.isInteger(m) ? m : m.toFixed(1)}m`;
97
+ const fmtHours = (h) => (Number.isInteger(h) ? `${h}h` : `${Math.round(h * 60)}m`);
98
+
93
99
  // #413: how long after a trunk commit "no run at this sha" is still the ordinary state. GitHub
94
100
  // creates a push run seconds after the push, but a ship reading trunk right after another ship
95
101
  // landed it can get there first. Ten minutes covers queueing on a busy account; past it, an empty
@@ -107,7 +113,9 @@ function emptyReadVerdict(committedAtMs, opts = {}) {
107
113
  if (committedAtMs == null || !Number.isFinite(committedAtMs)) return { fresh: false, minutes: null };
108
114
  const now = opts.nowMs != null ? opts.nowMs : Date.now();
109
115
  const minutes = (now - committedAtMs) / 60000;
110
- return { fresh: minutes >= 0 && minutes < EMPTY_READ_GRACE_MINUTES, minutes };
116
+ // #559: the grace may be the repo's measured push→run lag (tools/lib/ci-profile.js); absent → 10 min.
117
+ const graceMinutes = Number.isFinite(opts.graceSec) ? opts.graceSec / 60 : EMPTY_READ_GRACE_MINUTES;
118
+ return { fresh: minutes >= 0 && minutes < graceMinutes, minutes, graceMinutes };
111
119
  }
112
120
 
113
121
  module.exports = { WEDGE_AGE_HOURS, ZERO_JOBS_AGE_FLOOR_MINUTES, EMPTY_READ_GRACE_MINUTES, wedgedVerdict, emptyReadVerdict };
@@ -38,7 +38,10 @@ const EXIT = Object.freeze({
38
38
  });
39
39
 
40
40
  const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
41
- const DEFAULT_DEADLINE_SEC = 45 * 60;
41
+ // #559: the bootstrap deadline — the same 15 minutes every skill passed as `--timeout 15m`, so a caller
42
+ // that omits the flag no longer silently waits three times as long (it was 45 min). Once a repo has CI
43
+ // history, `colab ci-wait` derives its deadline from it instead (tools/lib/ci-profile.js).
44
+ const DEFAULT_DEADLINE_SEC = 15 * 60;
42
45
 
43
46
  /** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
44
47
  function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
@@ -141,6 +141,48 @@ function parseMemberTrailers(messages) {
141
141
  return out;
142
142
  }
143
143
 
144
+ /**
145
+ * #554: a member dropped at build used to leave no trace in git — only a `✗ <member>: …` line on
146
+ * one terminal — so eviction rate could not be measured. The batch head now records each drop:
147
+ *
148
+ * Ship-Batch-Dropped: <ref> <branch>@<sha> <class>
149
+ *
150
+ * appended to the LAST built member's message (the head commit), so it reaches trunk with a landed
151
+ * batch and rides the head commit's message of a combined run that went red. `class` is one token
152
+ * from DROP_CLASSES; the human reason stays on the terminal. A branch (already pushed, so already
153
+ * public) and a sha, never a host — the same rule as memberTrailer.
154
+ */
155
+ const DROP_TRAILER_KEY = 'Ship-Batch-Dropped';
156
+ const DROP_CLASSES = ['conflict', 'generated-no-hook', 'hook-failed', 'hook-markers', 'squash-failed', 'empty', 'message', 'commit-failed'];
157
+
158
+ function droppedTrailer({ ref, branch, sha, cls }) {
159
+ const c = DROP_CLASSES.includes(cls) ? cls : 'other';
160
+ return `${DROP_TRAILER_KEY}: ${ref} ${branch}@${String(sha || '').slice(0, 12)} ${c}`;
161
+ }
162
+
163
+ /** Every `Ship-Batch-Dropped:` trailer across commit messages → [{ ref, branch, sha, cls }]. */
164
+ function parseDroppedTrailers(messages) {
165
+ const out = [];
166
+ for (const msg of messages || []) {
167
+ for (const line of String(msg || '').split('\n')) {
168
+ const m = new RegExp(`^${DROP_TRAILER_KEY}:\\s+(\\S+)\\s+(\\S+)@([0-9a-f]{7,40})\\s+([a-z-]+)\\s*$`).exec(line.trim());
169
+ if (m) out.push({ ref: m[1], branch: m[2], sha: m[3], cls: m[4] });
170
+ }
171
+ }
172
+ return out;
173
+ }
174
+
175
+ /**
176
+ * `msg` with `lines` appended to its final trailer block — never as a new paragraph, which would
177
+ * split the block and hide the earlier trailers from `git interpret-trailers`. Lines already
178
+ * present are not repeated (a rebuild re-composes the same message).
179
+ */
180
+ function appendTrailers(msg, lines) {
181
+ const body = String(msg || '').replace(/\s+$/, '');
182
+ const add = (lines || []).filter((l) => l && !body.split('\n').includes(l));
183
+ return add.length ? `${body}\n${add.join('\n')}\n` : `${body}\n`;
184
+ }
185
+
144
186
  /**
145
187
  * A member's OWN head CI, read as a joining class (§4 Branch CI):
146
188
  * green every run at its head finished, all success
@@ -379,8 +421,9 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
379
421
  }
380
422
 
381
423
  module.exports = {
382
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY,
424
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
383
425
  parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
426
+ droppedTrailer, parseDroppedTrailers, appendTrailers,
384
427
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
385
428
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
386
429
  };