boost-skill-cli 1.2.172__tar.gz → 1.2.173__tar.gz

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.172
+Version: 1.2.173
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.172'
-__version_tuple__ = version_tuple = (1, 2, 172)
+__version__ = version = '1.2.173'
+__version_tuple__ = version_tuple = (1, 2, 173)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.172
+Version: 1.2.173
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/boost_skill_cli.egg-info/SOURCES.txt

@@ -355,6 +355,7 @@ docs/roadmap/items/build-provenance-slsa-attestations.md
 docs/roadmap/items/cache-the-catalog-entry-set-across-rag-queries.md
 docs/roadmap/items/cache-writers-that-still-crash-on-a-read-only-cache.md
 docs/roadmap/items/canary-deps-check-skips-in-the-required-job.md
+docs/roadmap/items/cancelled-ci-on-main-is-silent-and-skips-the-release.md
 docs/roadmap/items/capability-manifest-and-least-privilege-policy.md
 docs/roadmap/items/capability-policy-skips-rules-and-workflows.md
 docs/roadmap/items/catalog-categories-beyond-curated.md
@@ -1033,6 +1034,7 @@ tests/unit/test_mcphost.py
 tests/unit/test_measure_registry.py
 tests/unit/test_minisign.py
 tests/unit/test_mutation_hardening.py
+tests/unit/test_mutation_shard_count.py
 tests/unit/test_mutation_shards.py
 tests/unit/test_mutation_subfile_shards.py
 tests/unit/test_mutation_weights_drift.py

boost_skill_cli-1.2.173/docs/roadmap/items/cancelled-ci-on-main-is-silent-and-skips-the-release.md

@@ -0,0 +1,56 @@
+---
+id: cancelled-ci-on-main-is-silent-and-skips-the-release
+board: code
+section: trust
+status: planned
+category: CI · Bug
+complexity: S
+impact: High
+wow: 4
+note: the alerting that exists to make a red main impossible to miss asks only about 'failure', and the run that skipped a release was 'cancelled'
+order: 365
+owner:
+pr:
+title: "A <code>cancelled</code> <code>ci</code> on main skips the release and alerts nobody, because the alert asks only about <code>failure</code>"
+---
+<b>Two independent gates, both keyed on the wrong half of the same enum.</b>
+<code>publish.yml</code> fires on <code>workflow_run</code> and ships only when
+<code>conclusion == 'success'</code>; <code>ci-failure-alert</code> opens the tracking issue
+only when <code>conclusion == 'failure'</code>. A <code>ci</code> run that concludes
+<code>cancelled</code> satisfies neither. <b>It does not ship and it does not tell anyone</b>
+&mdash; the one conclusion that falls through both.
+
+<b>Observed, on the merge of #1015.</b> <code>mutation-shard (4)</code> hit
+<code>timeout-minutes: 75</code> and was cancelled, the aggregate <code>mutation</code> job
+failed, and the run concluded <code>cancelled</code> rather than <code>failure</code>. No
+release, no issue, no notification. It surfaced the same day, and only because somebody was
+reading per-shard job durations out of the Actions API for an unrelated reason &mdash; nothing
+in the repo would have raised it, and the next one will be found the same way or not at all.
+
+<b>This is the exact blind spot <code>ci-failure-alert</code>'s own header describes.</b> That
+file opens by explaining that <code>demo</code> "failed six runs out of six on main, alerted
+nobody, and was found by a manual audit instead", and concludes that "any workflow that runs on
+main and nobody watches belongs here". The list was then enforced by
+<code>tests/unit/test_failure_alerting_covers_unattended.py</code> so a new workflow cannot
+quietly join the blind spot. <b>The enforcement is over <em>which workflows</em> are watched,
+and the hole here is <em>which conclusions</em> are</b> &mdash; <code>ci</code> is on the list
+and still said nothing.
+
+<b>Why a timeout is not an exotic case.</b> It is the designed behaviour of every
+<code>timeout-minutes</code> in the repo, and <code>mutation-shard</code>'s is reached by an
+ordinary slow runner rather than by a bug: across 169 measured shard jobs the worst was 72.5
+minutes against a 75-minute cap. A job can also be cancelled by the concurrency group, by a
+runner eviction (<code>mutation-shard (4)</code> on #1012 died at 15.1 min with exit 143), or by
+a human pressing the button &mdash; and only the last of those is one anybody already knows
+about.
+
+<b>Shape of the work.</b> Widen the alert's condition from <code>== 'failure'</code> to the set
+of conclusions that mean "main is not green", which is every one except <code>success</code>,
+<code>skipped</code> and <code>neutral</code> &mdash; naming what is <em>excluded</em> rather
+than what is included, so the next conclusion GitHub adds defaults to loud. The issue body
+should say which conclusion it was, because <em>cancelled</em> and <em>failure</em> want
+different first moves. Then pin it: the sibling test already enforces the workflow list, so the
+conclusion set wants the same treatment rather than a comment. Worth checking at the same time
+whether <code>publish.yml</code> should distinguish "CI did not pass" from "CI did not finish"
+&mdash; today both are a silent no-op, and a release that was skipped because a runner was slow
+is recoverable by a rerun that nobody currently knows to start.

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/docs/roadmap/items/shard-weights-do-not-predict-the-job-timeout.md

@@ -2,15 +2,15 @@
 id: shard-weights-do-not-predict-the-job-timeout
 board: code
 section: trust
-status: planned
+status: inflight
 category: CI · Bug
 complexity: M
 impact: High
 wow: 4
 note: the pack is balanced to within 700ms of ideal and a shard still timed out at 75 min, cancelling a release
 order: 364
-owner:
-pr:
+owner: loop/shard-headroom
+pr: 1023
 title: "Mutation shard weights balance perfectly and predict nothing, so a shard can time out and cancel a release"
 ---
 <b>Observed, on the merge of #1015.</b> <code>mutation-shard (4)</code> ran 75 minutes against the
@@ -55,3 +55,40 @@ speedup cap is 6.0x only because <code>store.py</code> is split per function alr
 shards is cheap. Separately, a cancelled <code>ci</code> on main should be loud: it currently
 looks identical to a success from the release path's point of view, because
 <code>publish.yml</code> only asks whether the conclusion was <code>success</code>.
+
+<b>Fixed, and the calibration is measured.</b> Fitted over the Actions job API on 2026-10-01:
+<b>169 successful <code>mutation-shard</code> jobs</b>, of which 26 runs completed all six
+shards. Two numbers come out, and they answer different questions. Per <em>run</em> &mdash; the
+sum over its six shards, which is pack-invariant and so isolates runner speed from packing
+&mdash; observed minutes over committed weight-minutes is min 0.265, <b>median 0.307</b>, max
+0.355: a spread of only <b>1.34x</b>. Per <em>shard</em> against its own median the range is
+1.10x (shard 3) to <b>1.91x</b> (shard 2: median 38.0 min, worst 72.5). <b>So the mean is not
+what fails.</b> A single slow runner inside an otherwise ordinary run is, and a check scored on
+the median would have passed the pack that was cancelled &mdash; its median shard was 37.8
+minutes against a 75-minute cap, half the ceiling.
+
+<b>The 0.307 is not a fudge factor, it is parallelism.</b> Weights are summed per-mutant
+durations &mdash; the work a shard holds laid end to end &mdash; and the runner executes it
+four-way parallel (<code>max_children</code> defaults to <code>os.cpu_count()</code>;
+<code>ubuntu-latest</code> is 4 vCPU). The median inverts to 3.26 effective workers of 4, so what
+is stored is <b>81.4% parallel efficiency</b> and the worker count separately: a runner with more
+vCPUs then moves one constant and contention moves the other, where a single fitted number would
+hide which had happened.
+
+<b>It reproduces the failure it was derived to predict.</b> Six shards at these weights:
+37.8 median minutes &times; 1.91 = a <b>72.3-minute tail</b> against a real worst job of
+<b>72.5</b> &mdash; 96% of the cap. <code>plan --explain --timeout-minutes 75</code> now prints
+that and exits 1. The matrix moved to <b>eight</b>, where the same arithmetic gives 28.4 &times;
+1.91 = <b>54.2 min, 72% of the cap</b>; the largest unit (4,063,161 ms) still fits inside an even
+share (5,543,280 ms), so the speedup cap is a full 8.00x and more shards cost nothing but runner
+slots. <code>tests/unit/test_mutation_shard_count.py</code> pins the shard count across
+<code>ci.yml</code> and <code>mutation-weights-refresh.yml</code> (<code>timeout-minutes</code>
+cannot be read through <code>${{ }}</code>, so agreement is asserted rather than derived), and
+re-runs the headroom check on the committed pack every build &mdash; a pack that would be
+cancelled now fails in the <code>test</code> job in milliseconds.
+
+<b>Not fixed here, and now its own card:</b> a <code>cancelled</code> <code>ci</code> on main is
+still silent. <code>ci-failure-alert</code> gates on
+<code>conclusion == 'failure'</code>, so the run that skipped the release notified nobody either
+&mdash; see <code>cancelled-ci-on-main-is-silent-and-skips-the-release</code>.
+

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/docs/roadmap.html

@@ -143,7 +143,7 @@
       <div class="stat"><b>27</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>75</b><span>Planned</span></div>
-      <div class="stat"><b>521</b><span>Loop finds</span></div>
+      <div class="stat"><b>522</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -7748,7 +7748,7 @@ the walk and the <code>redirected</code> reporting this card inherits.</p>
       </article>
 
       <article class="cap rcard" id="shard-weights-do-not-predict-the-job-timeout">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">CI · Bug</span></div>
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">CI · Bug</span></div>
         <h3>Mutation shard weights balance perfectly and predict nothing, so a shard can time out and cancel a release</h3>
         <p><b>Observed, on the merge of #1015.</b> <code>mutation-shard (4)</code> ran 75 minutes against the
 job's <code>timeout-minutes: 75</code> and was cancelled. The aggregate <code>mutation</code> job
@@ -7791,7 +7791,43 @@ give the heaviest shard headroom &mdash; at eight shards the ideal drops by a qu
 speedup cap is 6.0x only because <code>store.py</code> is split per function already, so more
 shards is cheap. Separately, a cancelled <code>ci</code> on main should be loud: it currently
 looks identical to a success from the release path's point of view, because
-<code>publish.yml</code> only asks whether the conclusion was <code>success</code>.</p>
+<code>publish.yml</code> only asks whether the conclusion was <code>success</code>.
+
+<b>Fixed, and the calibration is measured.</b> Fitted over the Actions job API on 2026-10-01:
+<b>169 successful <code>mutation-shard</code> jobs</b>, of which 26 runs completed all six
+shards. Two numbers come out, and they answer different questions. Per <em>run</em> &mdash; the
+sum over its six shards, which is pack-invariant and so isolates runner speed from packing
+&mdash; observed minutes over committed weight-minutes is min 0.265, <b>median 0.307</b>, max
+0.355: a spread of only <b>1.34x</b>. Per <em>shard</em> against its own median the range is
+1.10x (shard 3) to <b>1.91x</b> (shard 2: median 38.0 min, worst 72.5). <b>So the mean is not
+what fails.</b> A single slow runner inside an otherwise ordinary run is, and a check scored on
+the median would have passed the pack that was cancelled &mdash; its median shard was 37.8
+minutes against a 75-minute cap, half the ceiling.
+
+<b>The 0.307 is not a fudge factor, it is parallelism.</b> Weights are summed per-mutant
+durations &mdash; the work a shard holds laid end to end &mdash; and the runner executes it
+four-way parallel (<code>max_children</code> defaults to <code>os.cpu_count()</code>;
+<code>ubuntu-latest</code> is 4 vCPU). The median inverts to 3.26 effective workers of 4, so what
+is stored is <b>81.4% parallel efficiency</b> and the worker count separately: a runner with more
+vCPUs then moves one constant and contention moves the other, where a single fitted number would
+hide which had happened.
+
+<b>It reproduces the failure it was derived to predict.</b> Six shards at these weights:
+37.8 median minutes &times; 1.91 = a <b>72.3-minute tail</b> against a real worst job of
+<b>72.5</b> &mdash; 96% of the cap. <code>plan --explain --timeout-minutes 75</code> now prints
+that and exits 1. The matrix moved to <b>eight</b>, where the same arithmetic gives 28.4 &times;
+1.91 = <b>54.2 min, 72% of the cap</b>; the largest unit (4,063,161 ms) still fits inside an even
+share (5,543,280 ms), so the speedup cap is a full 8.00x and more shards cost nothing but runner
+slots. <code>tests/unit/test_mutation_shard_count.py</code> pins the shard count across
+<code>ci.yml</code> and <code>mutation-weights-refresh.yml</code> (<code>timeout-minutes</code>
+cannot be read through <code>${{ }}</code>, so agreement is asserted rather than derived), and
+re-runs the headroom check on the committed pack every build &mdash; a pack that would be
+cancelled now fails in the <code>test</code> job in milliseconds.
+
+<b>Not fixed here, and now its own card:</b> a <code>cancelled</code> <code>ci</code> on main is
+still silent. <code>ci-failure-alert</code> gates on
+<code>conclusion == 'failure'</code>, so the run that skipped the release notified nobody either
+&mdash; see <code>cancelled-ci-on-main-is-silent-and-skips-the-release</code>.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>
@@ -7799,6 +7835,58 @@ looks identical to a success from the release path's point of view, because
           <span class="m">the pack is balanced to within 700ms of ideal and a shard still timed out at 75 min, cancelling a release</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="cancelled-ci-on-main-is-silent-and-skips-the-release">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">CI · Bug</span></div>
+        <h3>A <code>cancelled</code> <code>ci</code> on main skips the release and alerts nobody, because the alert asks only about <code>failure</code></h3>
+        <p><b>Two independent gates, both keyed on the wrong half of the same enum.</b>
+<code>publish.yml</code> fires on <code>workflow_run</code> and ships only when
+<code>conclusion == 'success'</code>; <code>ci-failure-alert</code> opens the tracking issue
+only when <code>conclusion == 'failure'</code>. A <code>ci</code> run that concludes
+<code>cancelled</code> satisfies neither. <b>It does not ship and it does not tell anyone</b>
+&mdash; the one conclusion that falls through both.
+
+<b>Observed, on the merge of #1015.</b> <code>mutation-shard (4)</code> hit
+<code>timeout-minutes: 75</code> and was cancelled, the aggregate <code>mutation</code> job
+failed, and the run concluded <code>cancelled</code> rather than <code>failure</code>. No
+release, no issue, no notification. It surfaced the same day, and only because somebody was
+reading per-shard job durations out of the Actions API for an unrelated reason &mdash; nothing
+in the repo would have raised it, and the next one will be found the same way or not at all.
+
+<b>This is the exact blind spot <code>ci-failure-alert</code>'s own header describes.</b> That
+file opens by explaining that <code>demo</code> "failed six runs out of six on main, alerted
+nobody, and was found by a manual audit instead", and concludes that "any workflow that runs on
+main and nobody watches belongs here". The list was then enforced by
+<code>tests/unit/test_failure_alerting_covers_unattended.py</code> so a new workflow cannot
+quietly join the blind spot. <b>The enforcement is over <em>which workflows</em> are watched,
+and the hole here is <em>which conclusions</em> are</b> &mdash; <code>ci</code> is on the list
+and still said nothing.
+
+<b>Why a timeout is not an exotic case.</b> It is the designed behaviour of every
+<code>timeout-minutes</code> in the repo, and <code>mutation-shard</code>'s is reached by an
+ordinary slow runner rather than by a bug: across 169 measured shard jobs the worst was 72.5
+minutes against a 75-minute cap. A job can also be cancelled by the concurrency group, by a
+runner eviction (<code>mutation-shard (4)</code> on #1012 died at 15.1 min with exit 143), or by
+a human pressing the button &mdash; and only the last of those is one anybody already knows
+about.
+
+<b>Shape of the work.</b> Widen the alert's condition from <code>== 'failure'</code> to the set
+of conclusions that mean "main is not green", which is every one except <code>success</code>,
+<code>skipped</code> and <code>neutral</code> &mdash; naming what is <em>excluded</em> rather
+than what is included, so the next conclusion GitHub adds defaults to loud. The issue body
+should say which conclusion it was, because <em>cancelled</em> and <em>failure</em> want
+different first moves. Then pin it: the sibling test already enforces the workflow list, so the
+conclusion set wants the same treatment rather than a comment. Worth checking at the same time
+whether <code>publish.yml</code> should distinguish "CI did not pass" from "CI did not finish"
+&mdash; today both are a silent no-op, and a release that was skipped because a runner was slow
+is recoverable by a rerun that nobody currently knows to start.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">the alerting that exists to make a red main impossible to miss asks only about 'failure', and the run that skipped a release was 'cancelled'</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.2.172 → boost_skill_cli-1.2.173}/scripts/mutation_shards.py

@@ -4,8 +4,9 @@
 """Split the mutation gate across parallel CI shards, and merge the results back.
 
 The gate runs ~10.5k mutants over ``boost_cli/core`` and is the single longest
-job in CI — roughly 26 minutes against ~9 for the next-slowest, so it alone sets
-how long a PR (and therefore a release) waits.
+job in CI — measured at a median 37.5 minutes a shard over 169 real shard jobs,
+against ~9 for the next-slowest job, so it alone sets how long a PR (and
+therefore a release) waits.
 
 mutmut's ``run`` accepts fnmatch patterns over mutant names
 (``boost_cli.core.lockfile.x__skeleton__mutmut_1``), and each source file owns a
@@ -78,14 +79,39 @@ needs no freshness gate — unlike every other generated file in this repo.
 
 The bound worth knowing: the largest *unit* is a floor on the slowest shard.
 That used to be the largest file — ``store.py``, capping the useful speedup at
-about 5.4x — and is now the largest unsplittable file, which lifts the cap to
-about 6.0x at six shards. ``plan --explain`` prints the cap, which files were
-split, and the resulting per-shard loads.
+about 5.4x — and is now the largest unsplittable file, which at the committed
+:data:`SHARDS` still fits inside an even share and so leaves the cap at the
+shard count itself. ``plan --explain`` prints the cap, which files were split,
+and the resulting per-shard loads.
+
+Ratios, and the one question they cannot answer
+-----------------------------------------------
+Everything above is scale-free: the packer needs only that one unit is twice
+another, so the weights can be in any unit that is consistent with itself, and
+they are in summed per-mutant milliseconds. That was fine until it was asked a
+question in a different unit. ``ci.yml`` caps each shard at ``timeout-minutes``;
+a cancelled shard fails the aggregate ``mutation`` job; a ``ci`` run that is
+*cancelled* rather than *failed* does not satisfy ``publish.yml``'s
+``conclusion == 'success'``; so a merge to main stops shipping, quietly. That
+happened on the merge of #1015, with ``plan --explain`` reporting ``7391040``
+against a ceiling written in minutes and nothing anywhere converting between
+them.
+
+:func:`runner_minutes` converts, by dividing the serial weight by the
+parallelism the runner actually delivers — see :data:`RUNNER_EFFICIENCY` and
+:data:`TAIL_MULTIPLIER`, both fitted over the job API rather than assumed.
+``plan --explain --timeout-minutes N`` then answers the question directly and
+exits non-zero when the answer is no;
+``tests/unit/test_mutation_shard_count.py`` asks it of the committed pack on
+every run, so a pack that would be cancelled fails in the ``test`` job in
+milliseconds instead of 75 minutes into the matrix.
 
 Usage
 -----
   mutation_shards.py plan --shards N --index I   # patterns for one shard
   mutation_shards.py plan --shards N --explain   # the whole split + speedup cap
+  mutation_shards.py plan --shards N --explain --timeout-minutes M
+                                                 # ...and does it fit in M minutes?
   mutation_shards.py merge --shards N --into mutants results/*  # rebuild results
   mutation_shards.py weights --source mutants    # refresh the balance hints
   mutation_shards.py drift --candidate new.json # is a refresh worth a PR?
@@ -107,6 +133,82 @@ ROOT = Path(__file__).resolve().parent.parent
 SOURCE = Path("boost_cli/core")
 WEIGHTS = Path("scripts/mutation_weights.json")
 
+#: How many shards the CI matrix runs. Python's copy of a number that is also
+#: spelled in two workflows, pinned against them by
+#: ``tests/unit/test_mutation_shard_count.py`` — ``timeout-minutes`` cannot be
+#: read through ``${{ }}``, so the agreement is asserted rather than derived.
+SHARDS = 8
+
+#: ``mutmut``'s worker count on the runner. It defaults to ``os.cpu_count()``
+#: and ``setup.cfg`` sets no ``max_children``, so on ``ubuntu-latest`` — 4 vCPU
+#: — the mutant set runs four at a time.
+RUNNER_WORKERS = 4
+
+#: The fraction of those four workers the runner actually delivers.
+#:
+#: **This is the number that made the plan predictive, and it is measured, not
+#: assumed.** The weights are summed per-mutant durations, so a shard's weight
+#: is the work it holds *serially* while the job runs it four-way parallel: a
+#: plan in weight-milliseconds was predicting 123 minutes a shard against 27-76
+#: observed, and nothing in the repo could answer "will a shard exceed the
+#: cap?".
+#:
+#: Fitted over the GitHub Actions job API on 2026-10-01: **169 successful
+#: `mutation-shard` jobs**, of which **26 runs completed all six shards**, from
+#: 2026-09-30 to 2026-10-01. Per *run* (the sum over its six shards, which is
+#: pack-invariant and so isolates runner speed from packing) the ratio of
+#: observed minutes to committed weight-minutes was min 0.265, **median
+#: 0.307**, p90 0.347, max 0.355 — a 1.34x spread. The median inverts to 3.26
+#: effective workers of 4, hence 81.4%.
+#:
+#: **Two days, and the window is the weakest part of the fit.** The sample is
+#: large (169 jobs) but short, because the weights it is a ratio *against* were
+#: themselves re-measured on 2026-09-30 — before that the denominator is a
+#: different number and the ratio is not comparable. So 1.34x is how much
+#: runners varied over two days, not over a quarter, and a seasonal effect
+#: would not be in it. That is an argument for re-fitting when the weights
+#: move, which is the same event that already opens a PR
+#: (``mutation-weights-refresh.yml``), not for widening the constant on a
+#: guess.
+#:
+#: Expressed as efficiency rather than as the 0.307 itself so that the two
+#: things that could move it stay separable: a runner with more vCPUs changes
+#: ``RUNNER_WORKERS`` and leaves this alone, where contention changes this and
+#: leaves that alone. A single fitted constant would hide which had happened.
+#:
+#: **The model is linear in the weight because the fixed cost is negligible,
+#: and that was measured too, not assumed.** Extrapolating a constant fitted
+#: at six shards to eight is only sound if per-job overhead — checkout, Python
+#: setup, the pip install, the cache restore — does not survive the split, and
+#: it does: over 41 shard jobs the ``mutate shard`` step is a median 35.6
+#: minutes inside a 36.2-minute job, so everything else is **0.6 min, 1.7%**.
+#: Predicting eight shards by the step alone (35.6 x 6/8 + 0.6 = 27.3 min)
+#: lands 4% under what this model gives (28.4), i.e. the model errs toward
+#: *more* time and therefore toward refusing a pack rather than passing one.
+#: If the cache ever stops hitting, that 0.6 is what grows — re-measure before
+#: trusting the extrapolation again.
+RUNNER_EFFICIENCY = 0.814
+
+#: How much worse the *worst* run of a shard is than that shard's median.
+#:
+#: The mean is not what fails. Per-run totals vary by only 1.34x, but an
+#: individual shard against its own median ranges 1.10x (shard 3) to **1.91x**
+#: (shard 2: median 38.0 min, worst 72.5) — one slow runner inside an otherwise
+#: ordinary run. The cap is reached by that tail, so the headroom check is
+#: scored against it and not against the median.
+#:
+#: It is a *measured* multiplier and it reproduces the observed worst case:
+#: 37.8 predicted median minutes at six shards x 1.91 = 72.2, against a real
+#: worst job of 72.5 — which is 97% of ``timeout-minutes: 75``. That is the
+#: cancellation this constant exists to predict, and at the time it was
+#: observed nothing printed a number anyone could have compared to the cap.
+TAIL_MULTIPLIER = 1.91
+
+#: Fraction of ``timeout-minutes`` the predicted tail may reach before
+#: ``plan --timeout-minutes`` calls the pack unsafe. 0.80 leaves the slowest
+#: shard a fifth of the cap in hand; the pack that was cancelled scored 0.97.
+HEADROOM = 0.80
+
 #: "No override is in force", which is a different state from "the override is
 #: no file at all" — ``None`` has to stay available as a value, because that is
 #: how ``drift`` compares against a checkout with no committed hints.
@@ -596,6 +698,66 @@ def pattern_for(root: Path, path: Path):
     return "%s.x_%s__mutmut_*" % (dotted, unit.symbol)
 
 
+def runner_minutes(weight_ms: float) -> float:
+    """Weight-milliseconds as wall-clock minutes on a CI runner.
+
+    The two units are not the same quantity and the gap is not a fudge: a
+    shard's weight is summed per-mutant durations — the work it holds laid end
+    to end — and the runner executes that work ``RUNNER_WORKERS``-way parallel
+    at ``RUNNER_EFFICIENCY``. Dividing is the whole of the model.
+
+    It is the *only* thing that lets the plan be compared to anything. Weights
+    are self-consistent ratios, which is all the packer needs, so the packer
+    was right to ignore this; but a ratio cannot be held against
+    ``timeout-minutes``, and the question "will this shard be cancelled?" is
+    asked in minutes or not at all.
+    """
+    return weight_ms / 60000.0 / (RUNNER_WORKERS * RUNNER_EFFICIENCY)
+
+
+def tail_minutes(weight_ms: float) -> float:
+    """The slow-runner case for a shard of this weight — what the cap must clear.
+
+    :func:`runner_minutes` gives the median run. Scoring the cap against that
+    would have passed the pack that was cancelled: its median shard was 37.8
+    minutes against a 75-minute cap, a comfortable-looking 50%, while the job
+    that actually died ran 72.5. See :data:`TAIL_MULTIPLIER`.
+    """
+    return runner_minutes(weight_ms) * TAIL_MULTIPLIER
+
+
+def headroom_report(loads: list[int], cap: int) -> tuple[bool, list[str]]:
+    """Does the heaviest shard fit inside ``cap`` minutes, with margin?
+
+    Returns ``(safe, lines)``. The caller decides what a false means, because
+    the two callers want different things: ``plan --explain`` prints the lines
+    and exits non-zero, and the lockstep test asserts on the bool.
+
+    The budget is ``cap * HEADROOM`` rather than ``cap`` itself, and **not**
+    because the prediction is a median — :func:`tail_minutes` has already
+    applied the slow-runner multiplier, so the number being compared is the
+    tail, not the middle. The margin is for the two things the tail estimate
+    does not contain: :data:`TAIL_MULTIPLIER` is a *max over 28 samples per
+    shard*, which is an estimate that only grows as runs accumulate, and the
+    weights it scales drift between refreshes. Twenty percent is what keeps a
+    pack that is merely near the line from being called fine until the day a
+    worse runner than any yet seen turns up.
+    """
+    worst = max(loads)
+    tail = tail_minutes(worst)
+    budget = cap * HEADROOM
+    safe = tail <= budget
+    lines = [
+        "timeout     : %d min (ci.yml), budget %.1f min at %.0f%% headroom"
+        % (cap, budget, HEADROOM * 100),
+        "slowest tail: %.1f min  (%.1f min median x %.2f slow-runner)"
+        % (tail, runner_minutes(worst), TAIL_MULTIPLIER),
+        "headroom    : %s — slowest shard reaches %.0f%% of the cap"
+        % ("OK" if safe else "TOO TIGHT", 100.0 * tail / cap),
+    ]
+    return safe, lines
+
+
 def cmd_plan(args: argparse.Namespace) -> int:
     root = Path(args.root)
     bins = pack(root, args.shards)
@@ -625,15 +787,55 @@ def cmd_plan(args: argparse.Namespace) -> int:
         else:
             unit = "lines"
             print("weights     : lines of code (no %s yet)" % WEIGHTS)
+        # Minutes only where the weights ARE time. On the count and line tiers
+        # the number is a ratio with no runner behind it, and printing "min"
+        # against it would be the same category error this whole calibration
+        # exists to remove — one unit further along.
+        def also_minutes(value: float) -> str:
+            return " (~%.1f min)" % runner_minutes(value) if unit == "ms" else ""
+
         print("total weight: %d %s" % (total, unit))
-        print("ideal shard : %d %s" % (total // args.shards, unit))
+        print("ideal shard : %d %s%s"
+              % (total // args.shards, unit, also_minutes(total / args.shards)))
         heaviest = max(unit_weight(root, u) for b in bins for u in b)
         print("largest unit: %d  (floor on the slowest shard)" % heaviest)
         print("speedup cap : %.2fx" % (total / max(loads)))
         for i, (b, ld) in enumerate(zip(bins, loads, strict=True)):
-            print("  shard %d: weight %5d, %2d units" % (i, ld, len(b)))
-        return 0
+            print("  shard %d: weight %5d, %2d units%s"
+                  % (i, ld, len(b), also_minutes(ld)))
 
+        if args.timeout_minutes is None:
+            return 0
+        if unit != "ms":
+            # Refuse rather than answer. A headroom verdict computed off line
+            # counts would read exactly like one computed off measured time,
+            # and the whole point of the check is that it can be trusted
+            # against the cap.
+            print("headroom    : not checked — weights are %s, not measured time"
+                  % unit)
+            return 0
+        safe, lines = headroom_report(loads, args.timeout_minutes)
+        for line in lines:
+            print(line)
+        return 0 if safe else 1
+
+    if args.timeout_minutes is not None:
+        # Not merely unsupported — actively refused. ci.yml does
+        # PATTERNS="$(plan --shards N --index $SHARD)", so every word this
+        # prints on the --index path becomes an argument to `mutmut run`.
+        #
+        # Checked against mutmut rather than assumed, because the obvious
+        # guess is wrong: it does NOT quietly run an empty set. A filter that
+        # matches nothing trips `assert filtered_mutants, "Filtered for
+        # specific mutants, but nothing matches"`, and a stray word with no
+        # `*` in it goes to `tests_by_mangled_function_name[...]` and raises
+        # KeyError. Both are loud. What is NOT loud is the mixed case — a
+        # stray word alongside real patterns leaves the assert satisfied, and
+        # the word is silently ignored. So the cost is a confusing crash or
+        # nothing at all, and neither is a reason to let prose onto that
+        # stdout. ci.yml's own `[ -z "$PATTERNS" ]` guard catches only the
+        # empty case and would not see any of this.
+        raise SystemExit("mutation_shards plan: --timeout-minutes needs --explain")
     if args.index is None:
         raise SystemExit("mutation_shards plan: --index is required without --explain")
     if not 0 <= args.index < args.shards:
@@ -822,8 +1024,8 @@ def cmd_scope(args: argparse.Namespace) -> int:
 
     Fails SAFE. An empty or unreadable file list means we could not prove the
     score is unchanged, so we say `true` and do the work. The expensive outcome
-    is a wasted 26 minutes; the cheap-looking one is a gate that silently stops
-    gating.
+    is one wasted shard — ~28 minutes at the committed :data:`SHARDS` — and the
+    cheap-looking one is a gate that silently stops gating.
     """
     if args.changed == "-":
         changed = sys.stdin.read().splitlines()
@@ -1257,6 +1459,11 @@ def main() -> int:
     p.add_argument("--shards", type=int, required=True)
     p.add_argument("--index", type=int)
     p.add_argument("--explain", action="store_true", help="print the whole split instead")
+    p.add_argument("--timeout-minutes", type=int,
+                   help="ci.yml's per-shard ceiling; with --explain, exit 1 "
+                        "when the slowest shard's predicted tail reaches it "
+                        "(requires --explain — the --index path's stdout is "
+                        "captured into mutmut's argv and must stay patterns)")
     p.set_defaults(func=cmd_plan)
 
     m = sub.add_parser("merge", help="merge per-shard .meta results for the gate")
@@ -1282,7 +1489,7 @@ def main() -> int:
     d = sub.add_parser("drift", help="is the committed balance hint worth replacing?")
     d.add_argument("--candidate", required=True,
                    help="a freshly measured mutation_weights.json to compare against")
-    d.add_argument("--shards", type=int, default=6)
+    d.add_argument("--shards", type=int, default=SHARDS)
     d.add_argument("--threshold", type=float, default=DRIFT_THRESHOLD,
                    help="slowest-shard cost over the measured best, above which "
                         "a refresh is worth a pull request (default: %(default)s)")