shard-timings-refresh.yml

# Regenerate scripts/test-shard-timings.json on a timer, and open the PR.
#
# ══════════════════════════════════════════════════════════════════════════════
# WHY THIS EXISTS: THE BALANCING INPUT WAS THE ONLY PART OF THE LOOP WITH NO
# CLOCK ON IT. (#16464)
# ══════════════════════════════════════════════════════════════════════════════
#
# scripts/test-shard-timings.json is the per-package duration dataset the Test
# Core split is binned from. It is GENERATED — scripts/measure-test-shard-
# timings.mjs turns a green run's per-shard turbo summaries into it — but until
# now it was generated only when a person remembered to. It went 13 days without a
# refresh while ~700 test files were added, and the shard it mis-weighted was
# killed by the job wall twelve times in one day and ejected from the merge queue
# twice (#16173).
#
# The rot is one-directional and silent, which is what makes a timer the fix
# rather than more discipline: suites only get slower, the table stays put, and
# the shard that drifted heavy reads as balanced on paper right up to the moment
# it is killed — and a killed shard produces NO measurement while the rollup
# reads green.
#
# WHAT THIS WORKFLOW IS NOT ALLOWED TO DO, AND WHY EACH ONE IS LOAD-BEARING
# ------------------------------------------------------------------------
#   ⛔ It never hand-edits the dataset. Every byte it commits came out of the
#      generator. A hand-touched number wearing a generated file's `provenance`
#      is worse than a stale one: the staleness is at least visible in
#      `measuredAt`.
#   ⛔ It never touches `timeout-minutes`, the shard matrix, MAX_SHARD_OVER_MEAN,
#      MAX_MEASURED_OVER_PREDICTED or FILE_SHARDED_PACKAGES. The partitioner's
#      own header calls raising a bound "the one move that cannot be right", and
#      its pin 3c is built to red on exactly that. If an honest refresh breaches
#      a bound, that breach is the REPORT, not a problem to be tuned away — it is
#      quoted verbatim into the PR body and a human decides. See "THE PINS" below.
#   ⛔ It never opens a PR when the regenerated file is byte-identical. A weekly
#      no-op PR trains everyone to ignore this PR.
#   ⛔ It never moves a suite-duration ceiling (#16468). The dataset also
#      carries `ceilings`, which `Test Core` grades every executed package
#      against (scripts/check-test-suite-ceilings.mjs). The generator writes
#      them in the same pass and HOLDS every ceiling the committed dataset
#      already has; a package gets a new one only when it had none (its slowest
#      executed run in this window x 1.25). A ceiling rises only by a ruling,
#      recorded in that script, so a refresh whose window ran slower REPORTS
#      the gap in the PR body instead of absorbing it. The first refresh after
#      the check landed writes the first table; until it merges the check reads
#      NOT MEASURED.
#
# HOW IT GETS ITS INPUTS, AND WHY IT RUNS HERE RATHER THAN IN AN AGENT WORKTREE
# ----------------------------------------------------------------------------
# The documented refresh path downloads the `test-core-run-summary-N-of-M`
# artifacts of a green run, one per Test Core shard. M is the RUN's own width,
# read from its `Test Core (N/M)` job names, so runs from before and after a
# matrix resize both read (#25376).
# `GET /actions/artifacts/{id}/zip` redirects to
# `productionresultssa*.blob.core.windows.net`, and every agent container's
# egress policy answers 403 to CONNECT for that host — reproduced four ways, on
# two artifacts across two runs, on the pre-signed URL as well as the API one, on
# two separate days and containers (#16222, and again on #16173). So the
# documented path cannot be walked from a dev seat at all.
#
# A GitHub-hosted runner reaches that host natively — it is the same host
# `actions/download-artifact` uses. Running the refresh here is therefore not a
# workaround for the denial, it is the removal of the channel from the loop: the
# regeneration happens where the data already is, on a timer, and no seat needs
# reachability it does not have.
#
# CHOOSING THE RUNS IS THE HARD PART — see scripts/ci/select-shard-timings-run.mjs
# ------------------------------------------------------------------------------
# "The newest run" is wrong three different ways here (cancelled runs, cache
# replays, expired artifacts), and a refresh built on the wrong run is worse than
# no refresh because it stamps a fresh `measuredAt` on numbers nobody measured.
# That script carries the argument and the self-test; this file only drives it.
#
# ⚠ WHICH RUNS: THE SCHEDULED RUN OF ci.yml, NEVER A PUSH RUN (#16467). Hourly
# until #25771 moved it to every 4 hours; the reasoning below is unchanged.
# Its summaries are retained 4 days (1 day on every other event), so the
# window still holds about 24 of them.
# Until #16467 a push to `main` re-ran the FULL Test Core battery, so "a green
# push run on main" and "a measurement of the workspace" were the same thing.
# They are not any more: a push run computes its package set with `--affected`
# against `github.event.before`. Its shards still conclude `success` and
# still upload every run summary, so NOTHING in the eligibility test would have
# noticed — this lane would have kept regenerating the balancing dataset from
# measurements of whatever the last merge happened to touch, and the coverage
# check would not have caught it either (a package the affected set skipped is a
# cache HIT, carried at its old weight, which is a pass). The selector names the
# event, and `select-shard-timings-run.mjs --self-test` drives a schedule-shaped
# and a push-shaped run through it to prove which one comes back.
#
# ⛔ Do NOT make ci.yml's `Save Turbo cache (main only)` step fire on `schedule`
# as well. It is `github.event_name == 'push'` on purpose and that is now
# load-bearing here: if the scheduled run seeded the cache it restores, the next
# scheduled run would replay almost the whole workspace, the generator would
# refuse every replayed task, and this lane would measure nothing — by
# construction, every 4 hours, forever. Affected-only pushes seeding a narrower
# cache is the direction that HELPS: it leaves more real misses for the
# scheduled run to time.
#
# ⚠ AND IT IS "RUNS", PLURAL, WHICH THE DOCUMENTED PROCEDURE DOES NOT SAY.
# Measured on this lane's first live run (34083991141), when the runs it read
# were still push runs: of the seven retained green runs on main, the BEST
# measured 52 of the 71 packages the committed dataset holds, and the others
# measured 2, 3, 13, 18, 22 and 49. All seven were partial cache replays. That
# follows from the cache design rather than from luck — turbo's key is
# namespaced per shard and only main pushes write it, so a package whose inputs
# have not changed is a HIT, and the generator refuses hits rather than
# recording a replayed ~0.1s window as a suite's cost. "Download the shard
# artifacts from any green run" therefore measures a SLICE of the workspace. That number
# should IMPROVE under the hourly run, because a push no longer seeds the whole
# workspace's entries — but it is quoted as it was measured, and the next live
# run is what re-measures it.
#
# So the regeneration step accumulates runs, each under its own `--run <id>`
# group — the grouping #16473 added, which sums a sliced package's slices within
# a run and medians the per-run sums across runs. A package seen in three of the
# accumulated runs gets the median of three observations, which is the property
# the dataset's own merge rule always claimed and could not previously deliver.
#
# ⚠ AND THE ACCUMULATION USED TO STOP AT ONE (#22014). The loop broke at the
# first accumulation that COVERED the workspace — and coverage counts a carried
# weight as covered, so the newest run always covered it. Every refresh since
# the hourly run went live was therefore one run: the dataset on `main` named
# `provenance.runs = ['37262126122']`, and recorded `@objectstack/spec` at
# 1134.86s against 1573-1651s on the executed windows after it. The loop now
# stops only when every package has been EXECUTED by at least the generator's
# MINIMUM_EXECUTED_RUNS (three) of the accumulated runs — executed, not
# replayed: an hourly run replays a different part of the workspace each time,
# so three runs is not three samples of `spec`. Measured over the 20 eligible
# hourly runs retained on 2026-10-06 (17:01 the day before to 15:01): every one
# of the 72 packages was executed by at least three of them, the newest twelve
# already sufficed, and `spec` was the tightest at 7 of 20.
#
# A refresh whose retained runs cannot give some package three executions is
# NOT refused: it is opened PROVISIONAL, with those packages named in the
# dataset's `provisional` list and in the PR body. Refusing would discard every
# other package's measurement over one under-sampled one — the silent-rot
# failure this lane exists to end — while the list keeps the shortfall
# machine-readable for anything that needs a baseline rather than a balancing
# input (a per-package ceiling must refuse a provisional weight).
#
# ⚠ AND ACCUMULATION ALONE STILL FALLS SHORT, so the pass MERGES rather than
# replaces. Measured on the same live runs: the union of all seven retained runs
# reaches 57 of 71 packages and converges there, because 14 packages are cache
# HITs in every one of them. Those are carried at their previous weights through
# `--merge-into`, and the carry is sound for one specific reason — a cache HIT is
# not missing data, it is POSITIVE EVIDENCE that the package's inputs are
# unchanged since the run whose output was replayed, so its last measured weight
# still describes it. Every carried package is named in the dataset's
# `carriedOver` list, and a package absent for any OTHER reason is not carried at
# all: it drops out and the coverage check names it as a refusal. The file's
# invariant is preserved exactly — every number in it is a real measurement of
# code as it stands, never an estimate.
#
# THE PINS, AND THE ONE THING A MACHINE MUST NOT DECIDE
# ----------------------------------------------------
# partition-test-shards.mjs `--self-test` grades the dataset against the
# acceptance bound. On a refresh that makes a package heavier than any split can
# bin, it reds BY DESIGN and names the remedy (raise the slice count — never the
# bound), and its pin 3c additionally demands a decision the day the CLI comes
# back under the bound on its own. Both are judgement, so this workflow REPORTS
# the verdict and never acts on it: the self-test is run on the refreshed file
# and its output — pass or fail, verbatim — goes into the PR body. The PR is
# opened either way, because a refusal to open it would lose the measurement,
# which is the exact silent-rot failure this workflow exists to end.
#
# REGRESSION DETECTION LIVES HERE, AND WHO FILES WHAT (#22949 ruling E)
# ---------------------------------------------------------------------
# The suite-duration ceilings only REPORT (ruling E item 1): a package's wall on
# a shared runner reads the run's load as much as the package. So this lane is
# the regression detector, and every refresh PR's body opens with what
# `measure-test-shard-timings.mjs --diff` reads (items 2 and 3):
#
#   - RISES: every package whose weight is up 1.25x or more against the
#     previous dataset -- the one on `main` before this refresh, read with
#     `git show HEAD:` -- with both numbers, its share of its runs' executed
#     total before and after, its slowest file in the window, and a verdict.
#     Only `finding` is a card.
#   - DENSITY: each run's count of EXECUTED packages (cache replays excluded),
#     which the generator records in the dataset's `density` from the first
#     refresh after the ruling on. A rise is judged only against a window of
#     COMPARABLE density -- mean executed packages per run within 1.25x of
#     each other, a number its self-test pins -- and a rise whose share of its
#     runs' executed total moved by less than 1.25x is density alone, not a
#     finding. The first refresh after this landed meets a previous dataset
#     with no `density`, and its body says the diff is a BASELINE.
#   - DOWNS, in one line.
#   - FILES OVER BUDGET: every test file over 10 s of wall in the window, with
#     its package and its slowest run (#22998). The dataset holds no per-file
#     reading; the window's runs do, in the per-shard `test-core-timings-N-of-M`
#     captures, which a step before the body downloads: the same runs, retained
#     exactly as long as their run summaries.
#
# ⛔ THE BOT FILES NOTHING, AND NONE OF THIS IS EVER A RED BUILD. The seat that
# lands the refresh PR files, after it lands:
#
#   - one card per package the diff marks `finding`, for the owning lane (its
#     `domain:*`, by the package's path in the pm-dispatch domain lane table),
#     with a `Protects:` line naming the package and the numbers -- the body
#     prints each line ready to paste;
#   - for the files over budget, one card per owning package naming its files
#     (#22998: a test file over 10 s of wall is a card for the owning lane);
#   - nothing for a rise marked density only, provisional, no prior share or
#     baseline, and no second card where an open one already names the package
#     or the file: the new numbers go there as a comment.
#
# The body's own "What the seat landing this PR does" section says the same
# with this run's list in it, so the duty is read where the work is.

name: Shard Timings Refresh

on:
  schedule:
    # Monday 05:30 UTC. After the nightly lanes, and early enough in the week
    # that the PR is in front of someone before the week's merge volume builds.
    - cron: '30 5 * * 1'
  workflow_dispatch:
  # Changes to this lane get exercised before they merge — the same posture
  # half-state-patrol.yml and fleet-patrols.yml's required-set-patrol keep, and the reason a
  # scheduled-only lane is not an option: `dispatch-gates.mjs` reds when a gate
  # family is reachable ONLY on a schedule, because a family no PR-time event
  # reaches appears on no card's gate list and is therefore graded by nobody
  # until the next sweep.
  #
  # On a `pull_request` run everything executes — selection, download,
  # regeneration, the coverage check, the byte comparison, the partitioner's
  # verdict, and the write step's own script with the write step's own `env:`,
  # up to and including the local commit — so the transport, the flags and the
  # write step's variables are proven on a real runner rather than argued
  # about. Only the acts that leave the runner are switched off, behind the one
  # `DRY_RUN` switch in that step: no branch is pushed, no PR is opened, no
  # label is written, and the body that would have been posted is rendered to
  # the run's step summary instead.
  pull_request:
    paths:
      - '.github/workflows/shard-timings-refresh.yml'
      - 'scripts/ci/select-shard-timings-run.mjs'
      - 'scripts/measure-test-shard-timings.mjs'

# Read-only at the top level; the one job widens to exactly what it writes.
permissions:
  contents: read

# One refresh at a time. A second run while the first is mid-push would race on
# the same bot branch; the newer inputs are the better ones, so the in-flight run
# yields.
concurrency:
  # Scoped BY REF, not one global group. Two scheduled refreshes cannot overlap
  # (they would race on the same bot branch, and the newer inputs are the better
  # ones, so the in-flight run yields) — but two PRs touching this lane are
  # unrelated runs, and a single global group would have each cancel the other's
  # dry run and report a cancellation as though the lane were busy.
  group: shard-timings-refresh-${{ github.ref }}
  cancel-in-progress: true

jobs:
  refresh:
    name: Regenerate the shard-timings dataset
    runs-on: ubuntu-latest
    timeout-minutes: 30
    # Reads only. The push, the PR and its label go out on the fleet App token
    # the write step mints (see "WHOSE IDENTITY OPENS THE PR" at that step),
    # never on this run's own `GITHUB_TOKEN`.
    permissions:
      contents: read # the checkout, and `git show HEAD:` of the committed dataset
      actions: read # list runs, read jobs, download run-summary artifacts
    steps:
      # No persisted credential: the one push goes out on the fleet token
      # (`gh auth setup-git` in the write step), never on `GITHUB_TOKEN`.
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      # Restore-only: scheduled runs read main's store cache; the per-push
      # workflows own saving it. Same shape as test-nightly-tiers.yml.
      - name: Setup workspace
        uses: ./.github/actions/setup-workspace
        with:
          save-store: 'false'

      # Verify the instruments BEFORE trusting their output. Both scripts carry a
      # battery floor, so this also catches the case where their assertions
      # stopped running — which would otherwise let a wrong dataset through a
      # green-looking pipeline.
      - name: Self-test the generator and the run selector
        run: |
          # A COLLECTOR, not a bare sequence. Under `bash -e` the first non-zero
          # exit aborts the step, so a plain `a && b` list leaves the second
          # self-test neither green nor red -- and this step exists precisely to
          # say which instrument is broken before the dataset is trusted.
          # ⛔ Never let the collector swallow the exit code: a green step over a
          # red self-test looks identical to success.
          failed=""
          run_self_test() {
            echo "-- $*"
            if "$@"; then
              echo "PASS  $*"
            else
              echo "FAIL  $*"
              failed="${failed}  $*"$'\n'
            fi
            return 0
          }
          run_self_test node scripts/measure-test-shard-timings.mjs --self-test
          run_self_test node scripts/ci/select-shard-timings-run.mjs --self-test
          if [ -n "$failed" ]; then
            echo ""
            echo "Shard-timings instrument self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi
          echo "Shard-timings instrument self-tests — both ran and passed"

      # The package list the coverage check judges against. `turbo ls` is
      # experimental, so the reader asserts its payload loudly rather than
      # defaulting around it (an empty list would make every package look deleted
      # and every coverage check pass).
      - name: List the workspace
        run: pnpm exec turbo ls --output=json > "$RUNNER_TEMP/turbo-ls.json"

      - name: Choose a green, uncensored, un-replayed run
        id: select
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          # 24, not 15 (#16467). The window that matters is the artifact
          # retention window of the scheduled runs — 4 days at one run every
          # 4 hours since #25771, 1 day at one an hour before it — so 24 is
          # "everything still downloadable" rather than an arbitrary depth. Coverage and sample depth are both
          # ACCUMULATED across runs (see the next step), so examining fewer
          # than the window holds is samples left on the table; the cost is two
          # API reads per run examined, and the loop below stops at the first
          # accumulation in which every package has been executed by the
          # minimum number of runs (#22014).
          #
          # ⭐ THREE EXITS, THREE READINGS (#16467). The selector answers 0, 1
          # or 3, and this step must not flatten them:
          #
          #   0  eligible runs on stdout — carry on.
          #   1  candidates existed and every one was censored, failed or lost
          #      its artifacts. A FINDING. The job goes red, as it always did.
          #   3  EXIT_PREREQUISITE_NOT_MET — the API held NO completed
          #      `schedule` run of ci.yml at all. NOTHING was measured. The
          #      dataset is untouched, which is the correct outcome, so the job
          #      must not go red for it.
          #
          # Measured, which is why this branch exists: on the pull request that
          # landed the hourly run, this lane ran with `event=schedule` before
          # that trigger existed on main, printed "NO ELIGIBLE RUN among the 0"
          # and named three causes none of which had occurred. It also does not
          # clear at merge — there is a bootstrap window of up to 4 hours
          # before the first scheduled run finishes.
          #
          # `|| SELECT_EXIT=$?` and not a bare call: this step runs under
          # `bash -e`, where the non-zero would kill it before the code could
          # be read at all.
          #
          # stderr goes to a FILE and is echoed back immediately: the log keeps
          # every line it had, and the refusal text becomes quotable into the
          # step summary below, where somebody reading a green job will see it.
          SELECT_EXIT=0
          node scripts/ci/select-shard-timings-run.mjs --candidates --limit 24 \
            > "$RUNNER_TEMP/candidates.json" 2> "$RUNNER_TEMP/select-stderr.txt" || SELECT_EXIT=$?
          cat "$RUNNER_TEMP/select-stderr.txt"
          echo "select_exit=$SELECT_EXIT" >> "$GITHUB_OUTPUT"
          if [ "$SELECT_EXIT" -eq 3 ]; then
            # ⛔ NEVER QUIET. A 3 that scrolls past in a green job is how this
            # lane ends up passing because it never looked — the shape that has
            # already cost this repo two cards. It is an annotation, a step
            # summary section and a job-level notice, and every one of them says
            # that a PERSISTENT 3 is a defect rather than a steady state.
            echo "not_measured=true" >> "$GITHUB_OUTPUT"
            echo "::warning::Shard timings NOT MEASURED: no completed \`schedule\` run of ci.yml exists on main yet. The dataset was left untouched. If this repeats once the scheduled full run has been live for a day, the trigger is gone or every scheduled run is being cancelled — file it."
            {
              echo "### Shard timings: NOT MEASURED (exit 3) — nothing was regenerated, and nothing failed"
              echo
              echo "\`select-shard-timings-run --candidates\` found **no completed \`schedule\` run of"
              echo "\`ci.yml\` on \`main\` at all**. That is not \"every candidate was rejected\": there were"
              echo "no candidates, so no run was censored, none failed and none lost its artifacts."
              echo "\`scripts/test-shard-timings.json\` is untouched, which is the correct outcome for this"
              echo "reading, and this job is green because nothing went wrong — not because anything passed."
              echo
              echo "Expected exactly once: while the scheduled full run bootstraps. The trigger has to be on"
              echo "\`main\` and one run has to finish, and run-summary artifacts live 4 days on a scheduled run."
              echo
              echo "⛔ **A PERSISTENT NOT MEASURED IS A DEFECT, NOT A STEADY STATE.** If this section is"
              echo "still here after the scheduled run has been live for a day, the \`schedule\` trigger"
              echo "has been removed from \`ci.yml\` or every scheduled run is being cancelled — and the"
              echo "balancing dataset is quietly ageing out while this job reports green. File a card."
              echo
              echo "The selector's own refusal text, verbatim:"
              echo
              echo '```'
              cat "$RUNNER_TEMP/select-stderr.txt" 2>/dev/null || echo '(the refusal text is in this job log)'
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi
          if [ "$SELECT_EXIT" -ne 0 ]; then
            echo "::error::select-shard-timings-run refused with exit $SELECT_EXIT — candidates existed and none was eligible. Nothing was regenerated."
            exit "$SELECT_EXIT"
          fi
          echo "Eligible runs, newest first:"
          node -e '
            const runs = JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/candidates.json", "utf8"));
            for (const r of runs) console.log(`  ${r.run_id}  ${r.created_at}  ${r.head_sha.slice(0, 10)}`);
          '

      # ACCUMULATE runs until the workspace is covered — do not look for one run
      # that covers it, because there is no such run.
      #
      # MEASURED on the first live run of this lane (run 34083991141), when the
      # runs read were still push runs, and it is the fact that shapes this
      # step: of the seven retained green runs on main, the BEST measured 52 of
      # the 71 packages the committed dataset holds, and the rest measured 2, 3,
      # 13, 18, 22 and 49. Every one of them was a partial cache replay. That is
      # not bad luck, it is the cache design: turbo's key is namespaced per shard
      # and only main pushes write it, so a package whose inputs have not changed
      # is a HIT — and the generator refuses hits rather than recording a
      # replayed ~0.1s window as a suite's cost. "Download the shard artifacts
      # from any green run" therefore measures a SLICE of the workspace, never all of it.
      # Since #16467 the runs read here are the `schedule` runs (every 4 hours since #25771), which are
      # the full battery; the accumulation stays because the cache argument above
      # is unchanged by which event ran the suite.
      #
      # So runs are accumulated. Each contributes its shards' summaries under its
      # own `--run <id>` group, which is exactly the grouping #16473 added: slices are
      # summed within a run and the per-run sums are medianed across runs, so a
      # package measured by three of these runs gets a median of three
      # observations rather than whichever run happened to be read last. Feeding
      # several runs WITHOUT that grouping is refused by the generator by name.
      #
      # WHEN IT STOPS (#22014). Not at the first accumulation that covers the
      # workspace: coverage counts a carried weight as covered, so the newest
      # run alone always passed it and every refresh was one run deep. The loop
      # stops at the first accumulation that BOTH covers the workspace AND
      # leaves the dataset's `provisional` list empty — every package executed
      # by at least the generator's MINIMUM_EXECUTED_RUNS of the runs fed.
      # When the candidates run out first, the last covering accumulation is
      # kept and opened PROVISIONAL, its short packages named; only a coverage
      # shortfall is still a refusal.
      - name: Regenerate the dataset, accumulating runs until every package is measured enough times
        id: generate
        # Skipped on the NOT MEASURED reading: there is nothing to download.
        # Every step after `compare` is already gated on
        # `steps.compare.outputs.changed`, which is the empty string when
        # `compare` itself is skipped — so guarding these two guards the tail.
        if: steps.select.outputs.not_measured != 'true'
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          WORK="$RUNNER_TEMP/refresh"
          mkdir -p "$WORK"
          # Both judged on the LAST accumulation the generator accepted, which
          # is the one `refreshed.json` holds: a run the generator refuses is
          # dropped and leaves the previous accumulation's file in place.
          COVERED=''
          SHORT=''
          ACCEPTED=()

          RUN_COUNT=$(node -e 'console.log(JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/candidates.json", "utf8")).length)')
          for i in $(seq 0 $((RUN_COUNT - 1))); do
            RUN_ID=$(node -e 'const r=JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP+"/candidates.json","utf8"))[Number(process.argv[1])];console.log(r.run_id)' "$i")
            echo "::group::Candidate run $RUN_ID"
            SUMDIR="$WORK/$RUN_ID"
            rm -rf "$SUMDIR"; mkdir -p "$SUMDIR"

            OK=1
            # One summary per shard the selector found: it admits a run only when
            # every shard OF THAT RUN concluded success with its artifact
            # retained, at the run's own width (select-shard-timings-run.mjs,
            # runShardWidth), so these keys ARE that run's roster. A count
            # spelled here would break the first refresh after a resize (#25376).
            SHARD_NS=$(node -e 'const r=JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP+"/candidates.json","utf8"))[Number(process.argv[1])];console.log(Object.keys(r.artifact_ids).map(Number).sort((a,b)=>a-b).join(" "))' "$i")
            for N in $SHARD_NS; do
              ART=$(node -e 'const r=JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP+"/candidates.json","utf8"))[Number(process.argv[1])];console.log(r.artifact_ids[process.argv[2]])' "$i" "$N")
              # curl drops the Authorization header across the redirect to the
              # blob host, which is correct: that URL is pre-signed and the
              # header would be rejected.
              if ! curl -sSL --fail -H "Authorization: Bearer $GITHUB_TOKEN" \
                   -H "Accept: application/vnd.github+json" \
                   "https://api.github.com/repos/$GITHUB_REPOSITORY/actions/artifacts/$ART/zip" \
                   -o "$SUMDIR/$N.zip"; then
                echo "::warning::Could not download artifact $ART (shard $N) of run $RUN_ID; skipping this run."
                OK=0; break
              fi
              unzip -qo "$SUMDIR/$N.zip" -d "$SUMDIR/$N"
            done
            if [ "$OK" -ne 1 ]; then echo "::endgroup::"; continue; fi

            # `find` rather than a fixed-depth glob: `upload-artifact` with
            # `path: .turbo/runs/` puts the summaries at the artifact root, but a
            # shape assumption here would silently collect NOTHING and hand the
            # generator an empty argument list, which reads like a refusal for
            # the wrong reason.
            find "$SUMDIR" -name '*.json' -type f > "$SUMDIR/summaries.txt"
            SUMMARY_COUNT=$(wc -l < "$SUMDIR/summaries.txt")
            echo "Collected $SUMMARY_COUNT run summary file(s) from run $RUN_ID."
            if [ "$SUMMARY_COUNT" -eq 0 ]; then
              echo "::warning::Run $RUN_ID's artifacts contained no run-summary JSON; skipping this run."
              echo "::endgroup::"; continue
            fi

            ACCEPTED+=("$RUN_ID")

            # The argument list is REBUILT from the accepted set every round
            # rather than appended to, so a run the generator refuses can be
            # dropped cleanly instead of poisoning every later attempt. Each run
            # is fenced by its own `--run <id>`; an array, not `xargs`, because a
            # split invocation would run the generator twice and the second would
            # overwrite the first's output with a partial dataset.
            ARGS=()
            for R in "${ACCEPTED[@]}"; do
              ARGS+=( --run "$R" )
              mapfile -t RUN_FILES < "$WORK/$R/summaries.txt"
              ARGS+=( "${RUN_FILES[@]}" )
            done

            # `--merge-into` the committed dataset, because no retained run set
            # measures the whole workspace (see the header). A package this pass
            # did not measure keeps its previous weight ONLY when a turbo cache
            # HIT witnesses that its inputs are unchanged; anything else is left
            # out for the coverage check below to name. The workflow still writes
            # no byte the generator did not emit — the merge happens inside it.
            # `--spread-out`: every package's executed-run count and
            # min/median/max, for the PR body. Written beside the dataset,
            # never into it — nothing machine-reads a spread.
            if ! node scripts/measure-test-shard-timings.mjs "${ARGS[@]}" \
                 --merge-into scripts/test-shard-timings.json \
                 --out "$WORK/refreshed.json" \
                 --spread-out "$WORK/spread.md"; then
              echo "::warning::The generator refused the set including run $RUN_ID; dropping that run and continuing."
              unset 'ACCEPTED[-1]'
              echo "::endgroup::"; continue
            fi

            echo "Accumulated ${#ACCEPTED[@]} run(s): ${ACCEPTED[*]}"
            if node scripts/ci/select-shard-timings-run.mjs --check-coverage \
                 --committed scripts/test-shard-timings.json \
                 --refreshed "$WORK/refreshed.json" \
                 --workspace "$RUNNER_TEMP/turbo-ls.json" \
                 --exclude @objectstack/dogfood; then
              COVERED=1
            else
              COVERED=''
            fi
            # How many weights still rest on fewer than the minimum executed
            # runs. Read from the generator's own `provisional` list rather than
            # recounted here, and an absent list is an error, not a zero: a
            # zero read from nothing would end the loop at one run again.
            SHORT=$(node -e '
              const d = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
              if (!Array.isArray(d.provisional)) throw new Error(process.argv[1] + " carries no `provisional` list");
              console.log(d.provisional.length);
            ' "$WORK/refreshed.json")
            if [ -n "$COVERED" ] && [ "$SHORT" -eq 0 ]; then
              echo "Every package is covered and executed by at least the minimum number of these runs; stopping."
              echo "::endgroup::"
              break
            fi
            if [ -n "$COVERED" ]; then
              echo "Covered, but $SHORT package weight(s) rest on fewer than the minimum executed runs; adding the next older run."
            fi
            echo "::endgroup::"
          done

          if [ -z "$COVERED" ]; then
            echo "::error::The ${#ACCEPTED[@]} eligible run(s) on main, accumulated and merged with the committed dataset, still leave a package that HAD a measured weight with neither a fresh measurement nor a turbo cache HIT to witness that it is unchanged — the shortfall above names them. Each would drop to the test-file-count ESTIMATE, which is the silent degradation this lane exists to prevent. NOTHING was regenerated and no PR was opened: this is a refusal, not a quiet success. A package that merely went unmeasured is NOT this error — that case is carried on its cache-hit witness — so a shortfall here means a suite failed, a package was renamed or removed, or its slices could not be assembled in any run."
            exit 1
          fi
          # PROVISIONAL, not refused (#22014): the candidates ran out before
          # every package reached the minimum. The measurement is kept, the
          # short packages are named in the dataset and the PR body, and this
          # annotation makes the reading visible on a green job.
          if [ "$SHORT" -gt 0 ]; then
            echo "::warning::Shard timings PROVISIONAL: $SHORT package weight(s) rest on fewer than the minimum executed runs across all ${#ACCEPTED[@]} retained run(s). They are named in the dataset's \`provisional\` list; read them as balancing inputs, not baselines."
          fi
          # Candidates arrive newest-first, so ACCEPTED[0] is the most recent run
          # in the set and its commit is the one the refresh is dated from. The
          # full list travels alongside it: every run in it contributed
          # measurements, and the PR body names them all rather than implying one.
          NEWEST="${ACCEPTED[0]}"
          echo "run_id=$NEWEST" >> "$GITHUB_OUTPUT"
          echo "runs=${ACCEPTED[*]}" >> "$GITHUB_OUTPUT"
          echo "run_count=${#ACCEPTED[@]}" >> "$GITHUB_OUTPUT"
          echo "head_sha=$(node -e 'const rs=JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP+"/candidates.json","utf8"));console.log(rs.find(r=>String(r.run_id)===process.argv[1]).head_sha)' "$NEWEST")" >> "$GITHUB_OUTPUT"

      # Byte comparison, and it decides everything downstream. `cmp -s` rather
      # than a diff of parsed JSON: the committed artefact is the file, so the
      # file is what has to differ for a PR to be worth anyone's attention.
      - name: Compare against the committed dataset
        id: compare
        if: steps.select.outputs.not_measured != 'true'
        run: |
          if cmp -s scripts/test-shard-timings.json "$RUNNER_TEMP/refresh/refreshed.json"; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
            echo "The regenerated dataset is BYTE-IDENTICAL to the committed one; no PR." | tee -a "$GITHUB_STEP_SUMMARY"
          else
            echo "changed=true" >> "$GITHUB_OUTPUT"
          fi

      # The before/after halves of ruling 3, taken from the partitioner's OWN
      # verdict line rather than recomputed here — a second implementation of the
      # binning would be a second answer to grade against.
      #
      # ⛔ The AFTER leg's non-zero exit is CAPTURED, not propagated, and that is
      # not leniency: a red there is the partitioner refusing an honest
      # measurement, which is information the PR must carry rather than a reason
      # to withhold the PR. `set +e` around that one command, with `$?` read
      # immediately and before any pipe, is what keeps the verdict readable
      # without letting the step's own status swallow it; the text goes into the
      # body either way and the PR's own lint job grades it again.
      - name: Predicted bins, before and after
        id: bins
        if: steps.compare.outputs.changed == 'true'
        run: |
          node scripts/partition-test-shards.mjs --self-test > "$RUNNER_TEMP/bins-before.txt" 2>&1 || true
          cp "$RUNNER_TEMP/refresh/refreshed.json" scripts/test-shard-timings.json
          set +e
          node scripts/partition-test-shards.mjs --self-test > "$RUNNER_TEMP/bins-after.txt" 2>&1
          echo "partitioner_exit=$?" >> "$GITHUB_OUTPUT"
          set -e
          echo "BEFORE: $(cat "$RUNNER_TEMP/bins-before.txt")"
          echo "AFTER:  $(cat "$RUNNER_TEMP/bins-after.txt")"

      # The per-file half of the regression readings (#22949 ruling E, item 3).
      # The dataset holds no per-file durations; the window's runs do, in the
      # per-shard captures `report-test-timings.mjs --capture` uploads as
      # `test-core-timings-N-of-M`, retained like the run summaries the
      # generator read. The selector listed their ids beside the summaries'
      # (`timing_artifact_ids`), so this is a read of the SAME runs, never a new
      # measurement, and it feeds the PR body alone.
      #
      # ⛔ It cannot fail the job: a capture that did not arrive is a warning
      # here and a named run in the PR body, never a lost refresh -- the capture
      # step in ci.yml is report-only, so a run can be a complete measurement
      # without one. Every fallible command is an `if` condition, which `bash -e`
      # does not abort on.
      - name: Download the window's per-file timing captures for the pull request body
        if: steps.compare.outputs.changed == 'true'
        env:
          GITHUB_TOKEN: ${{ github.token }}
          RUNS: ${{ steps.generate.outputs.runs }}
        run: |
          FILES="$RUNNER_TEMP/refresh-files"
          mkdir -p "$FILES"
          for R in $RUNS; do
            mkdir -p "$FILES/$R"
            # One "SHARD ARTIFACT_ID" line per retained capture of run R.
            if ! node -e '
              const rs = JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/candidates.json", "utf8"));
              const r = rs.find((x) => String(x.run_id) === process.argv[1]);
              for (const [n, id] of Object.entries((r && r.timing_artifact_ids) || {})) console.log(n + " " + id);
            ' "$R" > "$FILES/$R.ids"; then
              echo "::warning::Could not read run $R's per-file capture ids; its files are not in the over-budget list."
              continue
            fi
            if [ ! -s "$FILES/$R.ids" ]; then
              echo "::warning::Run $R retained no per-file timing capture; its files are not in the over-budget list."
              continue
            fi
            while read -r N ART; do
              if curl -sSL --fail -H "Authorization: Bearer $GITHUB_TOKEN" \
                   -H "Accept: application/vnd.github+json" \
                   "https://api.github.com/repos/$GITHUB_REPOSITORY/actions/artifacts/$ART/zip" \
                   -o "$FILES/$R/$N.zip" \
                 && unzip -qo "$FILES/$R/$N.zip" -d "$FILES/$R/$N"; then
                rm -f "$FILES/$R/$N.zip"
              else
                echo "::warning::Could not download per-file capture $ART (shard $N) of run $R; its files are not in the over-budget list."
              fi
            done < "$FILES/$R.ids"
          done
          echo "Per-file captures read for the PR body:"
          find "$FILES" -name '*.json' -type f | sort

      # Composition is separated from the WRITE on purpose: a `pull_request` run
      # of this lane must exercise the body-building — the shard durations, the
      # bins, the conditional blocks — without pushing anything. The write step
      # below consumes this file on every event: as the PR body when it writes,
      # and as the step summary on a `pull_request` dry run.
      - name: Compose the pull request body
        if: steps.compare.outputs.changed == 'true'
        env:
          RUN_ID: ${{ steps.generate.outputs.run_id }}
          RUNS: ${{ steps.generate.outputs.runs }}
          RUN_COUNT: ${{ steps.generate.outputs.run_count }}
          HEAD_SHA: ${{ steps.generate.outputs.head_sha }}
          PARTITIONER_EXIT: ${{ steps.bins.outputs.partitioner_exit }}
        run: |
          set -euo pipefail

          # Read out of the generated dataset itself rather than recomputed, so the
          # sentence in the PR cannot drift from the file it describes.
          CARRY_LINE=$(node -e '
            const d = JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/refresh/refreshed.json", "utf8"));
            const carried = d.carriedOver ?? [];
            const total = Object.keys(d.packages).length;
            const fresh = total - carried.length;
            if (carried.length === 0) {
              console.log(`All ${total} package weights were measured in these runs; nothing was carried.`);
            } else {
              console.log(
                `${total} package weights: ${fresh} measured in these runs, and ${carried.length} carried ` +
                `forward at their previous values because a turbo cache HIT witnessed that their inputs are ` +
                `unchanged (so the old number still describes them). Carried: ${carried.join(", ")}.`
              );
            }
          ')

          # Sample depth (#22014), read out of the dataset like the carry line
          # above. An absent list is an error rather than "none provisional".
          DEPTH_LINE=$(node -e '
            const d = JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/refresh/refreshed.json", "utf8"));
            if (!Array.isArray(d.provisional)) throw new Error("the refreshed dataset carries no `provisional` list");
            const min = d.provenance.minimumRuns;
            const total = Object.keys(d.packages).length;
            if (d.provisional.length === 0) {
              console.log(`Every one of the ${total} weights rests on at least ${min} executed runs; none is provisional.`);
            } else {
              console.log(
                `⚠️ PROVISIONAL: ${d.provisional.length} of the ${total} weights rest on fewer than ${min} executed ` +
                `runs, because the retained runs replayed them more often than they executed them. They are ` +
                `named in the dataset \`provisional\` list and are fit to balance on, NOT to set a per-package ` +
                `ceiling from: ${d.provisional.join(", ")}.`
              );
            }
          ')

          # The suite-duration ceilings (#16468), read out of the dataset like the
          # two lines above. The prior table is the COMMITTED dataset, read from
          # git because the bins step has already copied the refreshed file over
          # it. A refresh never moves a held ceiling, so the line counts what is
          # new and what is uncapped, and the spread table below marks every
          # held ceiling this window would have set differently -- and every one
          # a run of this window already went over.
          CEILING_LINE=$(node -e '
            const fs = require("fs");
            const { execFileSync } = require("child_process");
            const d = JSON.parse(fs.readFileSync(process.env.RUNNER_TEMP + "/refresh/refreshed.json", "utf8"));
            if (!d.ceilings || typeof d.ceilings !== "object" || !d.uncapped || typeof d.uncapped !== "object") {
              throw new Error("the refreshed dataset carries no `ceilings` / `uncapped`");
            }
            const prior = JSON.parse(execFileSync("git", ["show", "HEAD:scripts/test-shard-timings.json"], { encoding: "utf8" }));
            const held = prior.ceilings && typeof prior.ceilings === "object" ? prior.ceilings : null;
            const names = Object.keys(d.ceilings);
            const fresh = held === null ? names : names.filter((n) => !Object.hasOwn(held, n));
            const uncapped = Object.entries(d.uncapped).map(([n, why]) => n + " (" + why + ")");
            const h = d.provenance.ceilingHeadroom;
            const over = (fs.readFileSync(process.env.RUNNER_TEMP + "/refresh/spread.md", "utf8").match(/OVER its held ceiling/g) || []).length;
            const lines = [];
            if (held === null) {
              lines.push(
                "⚠️ This refresh writes the FIRST suite-duration ceiling table: " + names.length + " package(s) get a " +
                "ceiling, each its slowest executed run in this window x " + h + ". From the merge of this PR the `Test Core` " +
                "check (scripts/check-test-suite-ceilings.mjs) grades every executed package against it -- until then it " +
                "reads NOT MEASURED. Every later refresh HOLDS these numbers and a ceiling rises only by a ruling, so " +
                "review the ceiling column below before merging."
              );
            } else {
              lines.push(
                "Suite-duration ceilings: " + (names.length - fresh.length) + " held unchanged (a refresh never moves one; " +
                "a raise is a ruling), " + fresh.length + " new" + (fresh.length ? " (" + fresh.join(", ") + ")" : "") +
                ", each new one its slowest executed run in this window x " + h + "."
              );
            }
            lines.push(uncapped.length ? "No ceiling: " + uncapped.join(", ") + "." : "Every package carries a ceiling.");
            if (over > 0) {
              lines.push(
                "⚠️ " + over + " package(s) ran OVER their held ceiling in this window (marked in the table): a reading, " +
                "not a red -- under #22949 ruling E the ceiling reports on every event, and a regression is judged by " +
                "the diff at the top of this body. This refresh does not raise them; that takes a ruling."
              );
            }
            console.log(lines.join("\n\n"));
          ')

          # The regression readings (#22949 ruling E): this window diffed against
          # the previous dataset -- read from git, like the ceiling line above,
          # because the bins step has already copied the refreshed file over the
          # working copy -- plus the per-file budget from the captures the step
          # above downloaded. A refusal here (a malformed generated field) must
          # not cost the measurement, so its text goes into the body in place of
          # the section and the PR still opens. A less-than character is spelled
          # out first: GitHub's body sanitizer can eat everything after one.
          git show HEAD:scripts/test-shard-timings.json > "$RUNNER_TEMP/refresh/previous.json"
          DIFF_EXIT=0
          node scripts/measure-test-shard-timings.mjs --diff \
            --prior "$RUNNER_TEMP/refresh/previous.json" \
            --refreshed "$RUNNER_TEMP/refresh/refreshed.json" \
            --captures "$RUNNER_TEMP/refresh-files" \
            --out "$RUNNER_TEMP/refresh/diff.md" 2> "$RUNNER_TEMP/refresh/diff-stderr.txt" || DIFF_EXIT=$?
          cat "$RUNNER_TEMP/refresh/diff-stderr.txt"
          if [ "$DIFF_EXIT" -ne 0 ]; then
            echo "::warning::The refresh diff refused (exit $DIFF_EXIT); the PR body carries its text in place of the regression readings."
            {
              echo "## Regression readings: NOT MEASURED -- the diff refused (exit $DIFF_EXIT)"
              echo
              echo '```'
              sed 's/</\&lt;/g' "$RUNNER_TEMP/refresh/diff-stderr.txt"
              echo '```'
              echo
              echo "## What the seat landing this PR does"
              echo
              echo "File nothing from this refresh's readings: no rise and no file was judged. The refusal above"
              echo "is a defect in this lane, and that is the one card to file."
            } > "$RUNNER_TEMP/refresh/diff.md"
          fi

          SHARDS=$(node -e '
            const rs = JSON.parse(require("fs").readFileSync(process.env.RUNNER_TEMP + "/candidates.json", "utf8"));
            const r = rs.find((x) => String(x.run_id) === process.env.RUN_ID);
            const s = r.shard_seconds ?? {};
            const ns = Object.keys(r.artifact_ids ?? {}).map(Number).sort((a, b) => a - b);
            console.log(ns.map((n) => (s[n] == null ? "?" : `${n}: ${s[n]}s`)).join("  |  "));
          ')

          {
            echo "Refreshes \`scripts/test-shard-timings.json\`, the balancing input for the Test Core"
            echo "shard split. Opened automatically by \`.github/workflows/shard-timings-refresh.yml\`."
            echo "Every byte came out of \`scripts/measure-test-shard-timings.mjs\`; nothing here was"
            echo "hand-edited, and no bound, timeout or matrix entry was touched."
            echo
            cat "$RUNNER_TEMP/refresh/diff.md"
            echo
            echo "## Source"
            echo
            echo "Measured across $RUN_COUNT accumulated run(s) of the 4-hourly \`schedule\` run of CI on"
            echo "\`main\` — the full-battery run (#16467). A \`push\` run on \`main\` is affected-only and"
            echo "is not a measurement of the workspace, so no push run feeds this file."
            echo
            echo "No single green run measures the whole workspace either — turbo's cache is namespaced"
            echo "per shard and only main pushes write it, so a"
            echo "package whose inputs have not changed is a HIT and the generator refuses hits rather"
            echo "than recording a replay as a duration. Runs are therefore accumulated, each fenced by"
            echo "its own \`--run\` group, until every package has been EXECUTED by at least the"
            echo "generator's minimum number of them, and each weight is the median of those executions."
            echo
            for R in $RUNS; do
              echo "- https://github.com/$GITHUB_REPOSITORY/actions/runs/$R"
            done
            echo
            echo "- Newest run in the set: \`$RUN_ID\`, commit \`$HEAD_SHA\` — the date this refresh carries."
            echo "- Every run above had every \`Test Core (N/M)\` shard job conclude \`success\` with its"
            echo "  run-summary artifact still retained; runs that were cancelled, failed or had lost"
            echo "  their artifacts were rejected by name in the log before any of these were used."
            echo
            echo "$CARRY_LINE"
            echo
            echo "⚠️ This PR references #16173 and #16222 but does NOT carry a closing keyword for them,"
            echo "because a weekly lane cannot know which cards a given run ought to retire. If this is"
            echo "the first refresh to land, retire those two by hand as part of merging it."
            echo
            echo "## Sample depth, run-to-run spread and suite-duration ceilings"
            echo
            echo "$DEPTH_LINE"
            echo
            echo "$CEILING_LINE"
            echo
            cat "$RUNNER_TEMP/refresh/spread.md"
            echo
            echo "## Measured per-shard suite time on the newest run in the set"
            echo
            echo "\`\`\`"
            echo "$SHARDS"
            echo "\`\`\`"
            echo
            echo "## Predicted bins, before and after"
            echo
            echo "\`\`\`"
            echo "BEFORE  $(cat "$RUNNER_TEMP/bins-before.txt")"
            echo "AFTER   $(cat "$RUNNER_TEMP/bins-after.txt")"
            echo "\`\`\`"
            echo
            if [ "${PARTITIONER_EXIT:-0}" != "0" ]; then
              echo "## The partitioner's own pins RED on this refresh — read this before merging"
              echo
              echo "This is the designed behaviour, not a defect in the refresh: the acceptance bound is"
              echo "a ratio, and a package that has grown past what the Test Core split can bin makes the"
              echo "pins fail with the arithmetic in the message. The remedy the partitioner names is to"
              echo "raise the file-level slice count for that package — ⛔ never to raise the bound, and"
              echo "⛔ never to hand-edit this dataset. This workflow deliberately does neither: it"
              echo "reports and stops, because both are decisions."
              echo
            fi
            echo "Pushed and opened as the fleet App (\`objectstack-fleet[bot]\`, #25936), so this PR's"
            echo "own events start CI: no push or reopen is needed to get its checks."
            echo
            # ⛔ No closing keyword is emitted here, in any form. GitHub's
            # parser matches `fixes`/`closes`/`resolves` plus a number and
            # ignores every negation around them, so even a sentence saying a
            # card is NOT closed would close it. This PR is the workflow's
            # OUTPUT; the cards about the workflow are referenced only.
            echo "Refs #16464, #16173, #16222."
          } > "$RUNNER_TEMP/pr-body.md"
          echo "Composed a $(wc -l < "$RUNNER_TEMP/pr-body.md")-line pull request body."

      # WHOSE IDENTITY OPENS THE PR (#25936)
      # ------------------------------------
      # GitHub starts no workflow run for an event raised by a run's own
      # `GITHUB_TOKEN` (its recursion guard). This lane used to push and open
      # with that token whenever no PAT was configured, and none was: every
      # refresh PR arrived with no CI and sat until a seat pushed to it (#24467,
      # 2026-10-19, ten days; #25960, 2026-10-26, started only by a relay
      # `pr_update_branch`). A refresh can move pin 3c's slice count, so a PR
      # nobody's CI reads is exactly the one that needs reading.
      #
      # So the acts that leave the runner are done as the fleet App
      # (`objectstack-fleet[bot]`), whose events DO start workflows: the two
      # steps below mint a token from the organization variable
      # `OS_FLEET_APP_ID` and secret `OS_FLEET_PRIVATE_KEY` with
      # `actions/create-github-app-token`, the pair and action
      # fleet-write.yml mints with, and the one ui/'s refresh already took
      # (objectui#13362). The token is narrowed to this repository and to
      # contents (push the bot branch) + pull-requests (open the PR, add its
      # label), exists only in the write step's `env:`, and is revoked by the
      # action's post step. No `workflows` grant: the branch is cut from the
      # checked-out `main` and adds one commit that touches only the dataset,
      # so the push carries no workflow-file change.
      #
      #   ⛔ No fallback to `GITHUB_TOKEN` and no PAT. A missing credential is a
      #      red run that names it, never a quiet return to a PR with no CI.
      #   ⛔ A `pull_request` run mints nothing and never reads the App secret:
      #      its write step is the dry run, and nothing it does leaves the
      #      runner.
      - name: Check the fleet App credential is visible to this repository
        id: credential
        if: steps.compare.outputs.changed == 'true' && github.event_name != 'pull_request'
        env:
          HAS_APP_ID: ${{ vars.OS_FLEET_APP_ID != '' }}
          HAS_PRIVATE_KEY: ${{ secrets.OS_FLEET_PRIVATE_KEY != '' }}
        run: |
          # Read as booleans, never printed: a red that names the missing half
          # beats create-github-app-token's own error, which does not.
          if [ "$HAS_APP_ID" != 'true' ] || [ "$HAS_PRIVATE_KEY" != 'true' ]; then
            echo "::error title=Shard timings refresh::The fleet App credential is not visible to this repository (OS_FLEET_APP_ID set: $HAS_APP_ID; OS_FLEET_PRIVATE_KEY set: $HAS_PRIVATE_KEY). Nothing was pushed (#25936)."
            exit 1
          fi
          # The token's one repository, by name: the action takes names
          # without the owner, and an empty list would widen it to every
          # repository the installation covers.
          echo "repository=${GITHUB_REPOSITORY#*/}" >> "$GITHUB_OUTPUT"

      - name: Mint the fleet App token, narrowed to this repository
        id: fleet
        if: steps.compare.outputs.changed == 'true' && github.event_name != 'pull_request'
        uses: actions/create-github-app-token@v3
        with:
          app-id: ${{ vars.OS_FLEET_APP_ID }}
          private-key: ${{ secrets.OS_FLEET_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}
          repositories: ${{ steps.credential.outputs.repository }}
          permission-contents: write # push the bot branch
          permission-pull-requests: write # open the PR and add its label

      # The WRITE — and, on a `pull_request` run of this lane, its rehearsal.
      #
      # ONE STEP, ONE `env:`, ONE SCRIPT, ON EVERY EVENT (#18341). The write and
      # its dry run used to be two steps behind mutually exclusive `if:`s
      # (`github.event_name != 'pull_request'` and `== 'pull_request'`), so no
      # pull request ever executed the script that writes. Its first execution
      # was scheduled run 34810389734: the dataset was computed, and the step
      # then died at `git commit` with `RUN_COUNT: unbound variable`, because
      # this step's `env:` exported three of the five variables its script
      # expands. Under `set -u` a key missing from `env:` blows up only on the
      # leg that runs, and the rehearsal ran the other leg.
      #
      # So a `pull_request` run now executes THIS script with THIS `env:`. The
      # branch, the `git add` and the commit — whose message expands every
      # provenance variable — happen for real on the runner, with the repo's own
      # commit hook, so a variable missing from the block below reds the pull
      # request that dropped it. Only the acts that leave the runner are
      # switched, and all of them are switched in ONE place: `outward`, which on
      # a dry run prints the command instead of running it. The shell expands a
      # command's arguments before `outward` is entered, so `set -u` judges every
      # argument on both legs alike.
      #
      # ⛔ Never call `git push`, `gh` or any other network act outside
      # `outward`, and never split this step back into an event-gated pair:
      # either one reopens a leg that no pull request can exercise.
      - name: Push the refresh branch and open the pull request (dry run on pull_request)
        if: steps.compare.outputs.changed == 'true'
        env:
          # The switch: 'true' on a `pull_request` run and only there. The script
          # refuses any other spelling, and refuses 'false' on a `pull_request`
          # run, so no edit to this line can make a pull request push.
          DRY_RUN: ${{ github.event_name == 'pull_request' }}
          # The fleet App token on every live run. A dry run mints none, so it
          # holds the run's own read-only token as a stand-in that `outward`
          # never hands to a network act; a live run with no minted token is
          # empty here and the guard below reds it.
          GH_TOKEN: ${{ github.event_name == 'pull_request' && github.token || steps.fleet.outputs.token }}
          # Every variable the script expands that the runner does not provide.
          # The commit message is the dataset's provenance and names all four:
          # ⛔ never drop one from the message to get a green run.
          RUN_ID: ${{ steps.generate.outputs.run_id }}
          RUNS: ${{ steps.generate.outputs.runs }}
          RUN_COUNT: ${{ steps.generate.outputs.run_count }}
          HEAD_SHA: ${{ steps.generate.outputs.head_sha }}
        run: |
          set -euo pipefail

          case "$DRY_RUN" in
            true) DRY_TAG='(dry run, not executed) ' ;;
            false) DRY_TAG='' ;;
            *)
              echo "::error::DRY_RUN must be 'true' or 'false', got '$DRY_RUN'. Nothing was pushed."
              exit 1
              ;;
          esac
          if [ "$GITHUB_EVENT_NAME" = 'pull_request' ] && [ "$DRY_RUN" != 'true' ]; then
            echo "::error::DRY_RUN is '$DRY_RUN' on a pull_request run. A pull_request run of this lane never pushes a branch, opens a PR or writes a label. Nothing was pushed."
            exit 1
          fi
          # `gh` reads GH_TOKEN from the environment, not from an argument, so no
          # expansion below would notice it missing and a dry run never starts
          # `gh`. Named here, it is judged on both legs like every other key.
          : "${GH_TOKEN:?is not set; gh would run unauthenticated. Nothing was pushed.}"

          # outward [--stand-in TEXT] COMMAND...
          # The one dry-run switch. Live, it runs COMMAND. Dry, it prints COMMAND
          # to the log instead, and prints TEXT on stdout where the live call's
          # output would have been, so every line after it runs on a value of
          # the same shape.
          outward() {
            local stand_in=''
            if [ "$1" = '--stand-in' ]; then
              stand_in="$2"
              shift 2
            fi
            if [ "$DRY_RUN" = 'true' ]; then
              { printf 'DRY RUN, not executed:'; printf ' %q' "$@"; printf '\n'; } >&2
              if [ -n "$stand_in" ]; then printf '%s\n' "$stand_in"; fi
              return 0
            fi
            "$@"
          }

          BRANCH="claude/shard-timings-refresh-$RUN_ID"
          # The checkout persisted no credential; this points git's helper at
          # GH_TOKEN, the fleet token, for the one push below.
          outward gh auth setup-git
          git config user.name 'objectstack-fleet[bot]'
          git config user.email '332303061+objectstack-fleet[bot]@users.noreply.github.com'
          git switch -c "$BRANCH"
          git add scripts/test-shard-timings.json
          # Separate -m flags rather than one embedded newline: a YAML-indented
          # heredoc would carry its own leading whitespace into the message body.
          git commit \
            -m "chore(ci): refresh the Test Core shard-timings dataset" \
            -m "Regenerated by .github/workflows/shard-timings-refresh.yml from the test-core-run-summary artifacts of $RUN_COUNT accumulated run(s) ($RUNS), newest $RUN_ID at $HEAD_SHA. Generated, never hand-edited."
          outward git push origin "$BRANCH"

          PR_URL=$(outward --stand-in "https://github.com/$GITHUB_REPOSITORY/pull/0" \
            gh pr create --base main --head "$BRANCH" \
            --title "chore(ci): refresh the Test Core shard-timings dataset" \
            --body-file "$RUNNER_TEMP/pr-body.md")
          echo "${DRY_TAG}Opened $PR_URL" | tee -a "$GITHUB_STEP_SUMMARY"

          # ADDITIVE label write only. A whole-set PUT replaces the PR's labels
          # and destroys any that land in between — measured on this repo, one
          # second wide (see pr-automation.yml's header). POST names only what it
          # adds, so no interleaving can lose another writer's label.
          PR_NUMBER=$(outward --stand-in 0 gh pr view "$PR_URL" --json number --jq .number)
          outward gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" \
            -f "labels[]=skip-changeset" > /dev/null

          # Read back, because an additive write is necessary and not sufficient:
          # a concurrent whole-set PUT from another workflow can still strip the
          # label after a successful POST. `skip-changeset` is this PR's exemption
          # from the changeset gate — it publishes nothing — so losing it turns
          # the gate red on a PR that legitimately has no changeset.
          if outward --stand-in skip-changeset gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" --jq '.[].name' \
             | grep -qxF 'skip-changeset'; then
            echo "${DRY_TAG}skip-changeset confirmed on PR #$PR_NUMBER."
          else
            echo "::warning::skip-changeset did not survive the write on PR #$PR_NUMBER (a concurrent whole-set label PUT strips it). Re-applying once."
            outward gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" \
              -f "labels[]=skip-changeset" > /dev/null
            outward gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" --jq '.[].name' \
              | grep -qxF 'skip-changeset' \
              || echo "::error::skip-changeset is still absent from PR #$PR_NUMBER; the changeset gate will demand a changeset this PR legitimately has none of. Apply the label by hand."
          fi

          # The dry-run half of the `pull_request` posture: render the body that
          # WOULD have been posted, so a reviewer of a change to this lane sees the
          # actual output rather than the diff of the code that produces it.
          if [ "$DRY_RUN" = 'true' ]; then
            {
              echo "### Shard timings: dry run (no branch pushed, no PR opened, no label written)"
              echo
              echo "This is a \`pull_request\` run of the refresh lane itself. The run selection, the"
              echo "artifact download, the regeneration, the coverage check, the partitioner's verdict"
              echo "and the write step's own script, up to and including its local commit, all"
              echo "executed for real; only the push, the PR and the label write were skipped. The body"
              echo "below is what a scheduled run would have posted."
              echo
              echo "---"
              echo
              cat "$RUNNER_TEMP/pr-body.md"
            } >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Say what happened when nothing changed
        if: steps.compare.outputs.changed == 'false'
        run: |
          {
            echo "### Shard timings: byte-identical, no PR"
            echo
            echo "Run \`${{ steps.generate.outputs.run_id }}\` (\`${{ steps.generate.outputs.head_sha }}\`)"
            echo "regenerated \`scripts/test-shard-timings.json\` byte-for-byte identically to the"
            echo "committed file, so there is nothing to open a pull request about. The dataset is"
            echo "current, and this is the loop working rather than the loop skipping."
          } >> "$GITHUB_STEP_SUMMARY"