@futurelastic/colab-handbook 1.13.0-rc.25 → 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.25"
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');
@@ -10885,10 +10886,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10885
10886
  // (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
10886
10887
  // never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
10887
10888
  if (run.status === 'none' && target === trunk) {
10888
- 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 });
10889
10891
  if (fresh.fresh) {
10890
10892
  verdict = { ok: false, class: SELF_CLEARING,
10891
- 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)}` };
10892
10894
  }
10893
10895
  }
10894
10896
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -11001,7 +11003,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
11001
11003
  // Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
11002
11004
  // shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
11003
11005
  const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
11004
- 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 });
11005
11009
  if (wedge.wedged) {
11006
11010
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
11007
11011
  }
@@ -14491,6 +14495,110 @@ function trunkCiCache(repoAbs) {
14491
14495
  };
14492
14496
  }
14493
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
+
14494
14602
  // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
14495
14603
  // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
14496
14604
  // requests, a deadline, and a distinct exit code for every way a wait can end.
@@ -14506,9 +14614,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14506
14614
  with no run yet counts as pending until the deadline. An abbreviated sha is
14507
14615
  resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14508
14616
  --branch <b> narrow --sha to runs on that branch
14509
- --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.
14510
14621
 
14511
- 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
14512
14624
  conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14513
14625
  304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14514
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.
@@ -14523,7 +14635,8 @@ Exit codes — branch on these, never on the text:
14523
14635
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14524
14636
 
14525
14637
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14526
- --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 }`;
14527
14640
 
14528
14641
  function cmdCiWait(argv) {
14529
14642
  const opts = parseArgs(argv, {
@@ -14536,8 +14649,10 @@ function cmdCiWait(argv) {
14536
14649
  warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
14537
14650
  return ciWait.EXIT.USAGE;
14538
14651
  }
14539
- const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14540
- 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;
14541
14656
  const repoAbs = resolveRepo(opts);
14542
14657
  if (opts.sha) {
14543
14658
  // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
@@ -14564,6 +14679,23 @@ function cmdCiWait(argv) {
14564
14679
  return ciWait.EXIT.ALREADY_WAITING;
14565
14680
  }
14566
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
+
14567
14699
  const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
14568
14700
  const poll = (etag) => {
14569
14701
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
@@ -14583,11 +14715,11 @@ function cmdCiWait(argv) {
14583
14715
  return { ...r, summary, state: ciWait.runState(summary) };
14584
14716
  };
14585
14717
 
14586
- 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`);
14587
14719
  let res;
14588
14720
  try {
14589
14721
  res = ciWait.waitLoop({
14590
- poll, sleep: ciWait.sleepSync, deadlineSec,
14722
+ poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
14591
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`); },
14592
14724
  });
14593
14725
  } finally {
@@ -14597,7 +14729,7 @@ function cmdCiWait(argv) {
14597
14729
  const code = ciWait.EXIT[res.outcome];
14598
14730
  const out = {
14599
14731
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14600
- waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14732
+ waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14601
14733
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14602
14734
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14603
14735
  };
@@ -14793,6 +14925,74 @@ function cmdBatchStats(argv) {
14793
14925
  return 0;
14794
14926
  }
14795
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
+
14796
14996
  function cmdLanded(argv) {
14797
14997
  const opts = parseArgs(argv, {
14798
14998
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15580,6 +15780,8 @@ Commands:
15580
15780
  batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
15581
15781
  fill, first-attempt green, drops, missed partners, queue
15582
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)
15583
15785
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15584
15786
  have not landed on the base (filters the raw git-log
15585
15787
  one-liner through \`landed\`'s content classification)
@@ -15665,6 +15867,7 @@ function main(argv) {
15665
15867
  case 'ship': return cmdShip(rest);
15666
15868
  case 'landed': return cmdLanded(rest);
15667
15869
  case 'batch-stats': return cmdBatchStats(rest);
15870
+ case 'ci-profile': return cmdCiProfile(rest);
15668
15871
  case 'trunk-ci': return cmdTrunkCi(rest);
15669
15872
  case 'ci-wait': return cmdCiWait(rest);
15670
15873
  case 'holders': return cmdHolders(rest);
@@ -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) {