@avi2dg/checks 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.47.0
+
+Released 2026-10-19.
+
+### Features
+
+- **testing:** file night-run regressions as GitHub issues instead of gating pull requests [#174](https://github.com/avi2d/checks/pull/174)
+
 ## 0.46.0
 
 Released 2026-10-19.

package/README.md

@@ -193,8 +193,9 @@ These bins run on their own:
 - [`checks-mutation`](docs/gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
 - [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, saves it on a self-hosted runner's disk in place of an artifact, and deletes superseded baselines after a `main` run.
-- [`checks-mutation-scope`](docs/gates/checks-mutation-scope.md) turns a pull request's diff into the files its mutation runs mutate.
+- [`checks-mutation-scope`](docs/gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
+- [`checks-night-run`](docs/gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell and each failing test.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.

package/docs/gates/checks-advisories.md

@@ -102,12 +102,12 @@ A range that leaves `bun.lock` unchanged runs in under a second, and one that ch
 ## Running it on a schedule
 
 A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those.
-A repository schedules it at minute 17 of its tier's 30 minute night window, so repositories do not start together:
+A consuming repository pins advisories between 05:00 and 06:00 UTC at a minute chosen so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "17 22 * * *"
+    - cron: "15 5 * * *"
   workflow_dispatch:
 jobs:
   advisories:

package/docs/gates/checks-mutation-baseline.md

@@ -166,7 +166,7 @@ The saved baseline uses none of the account's Actions storage, which every priva
 That storage accrues by the hour over the month, so an artifact deleted early still counts until the month ends.
 A baseline job on a GitHub-hosted runner uploads the same two files as a `mutation-baseline` artifact with `retention-days: 7` instead, since the restore reads only the newest `main` run.
 
-A full run uploads its report as the `mutation-baseline-full` artifact, which a pull request's scope step reads on any runner.
+A full run uploads its report as the `mutation-baseline-full` artifact, which a branch comparison's scope step reads on any runner.
 It slims the report first, so the artifact holds about 0.5 MB in place of about 100 MB:
 
 ```yaml
@@ -179,9 +179,9 @@ It slims the report first, so the artifact holds about 0.5 MB in place of about
 ```
 
 The full upload keeps 30 days, so the newest full baseline outlives the gap between full runs.
-A pull request's scope step loses its coverage when no full baseline outlives the gap.
+A branch comparison's scope step loses its coverage when no full baseline outlives the gap.
 
-A pull request's scope step restores the full report with `--full`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
+A branch comparison's scope step restores the full report with `--full`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
 
 ```yaml
 - name: Select mutation scope

package/docs/gates/checks-mutation-compare.md

@@ -68,22 +68,23 @@ mutation-compare: REGRESSION (1 mutant(s))
 ## When it runs
 
 Only a CI step the repository writes runs it.
-A repository runs it with `--advisory`, so the comparison stays advisory and never blocks a pull request.
+A person starts that step by hand on a branch, and no pull request triggers it or waits for it.
+[checks-night-run](checks-night-run.md) judges the mutation score of `main` each night and opens an issue for each file whose score fell.
+A repository runs it with `--advisory`, so the comparison stays advisory.
 Its lines land only in the CI log.
-A repository that wants a reviewer to answer each regression line puts the lines in front of that reviewer with its own CI step.
-That step can post them as a pull request comment.
 A full sweep runs in CI and never on a laptop.
 Start a baseline with `gh workflow run mutation` and keep its report as an artifact.
 The shared preset refuses a full `stryker run` outside CI and names that workflow command instead, as [checks-mutation](checks-mutation.md) says.
 
 ## Running it in CI
 
-It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base over the same scope:
+A person starts a workflow named `mutation-compare` on a branch with `gh workflow run mutation-compare --ref <branch>`.
+It compares the head report against a report built at the merge-base with `main` over the same scope:
 
 ```yaml
 name: mutation-compare
 on:
-  pull_request:
+  workflow_dispatch:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
@@ -102,7 +103,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+          base="$(git merge-base HEAD origin/main)"
           echo "BASE_SHA=$base" >> "$GITHUB_ENV"
           bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
           bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
@@ -125,7 +126,7 @@ jobs:
           git worktree prune
 ```
 
-The scope step picks the files the pull request changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
+The scope step picks the files the branch changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
 Neither run mutates a file outside that scope, so the job's time follows the size of the change and not the size of the repository.
 Both runs take the same `--mutate "$SCOPE"`, so the two reports hold the same files.
 A scope file the merge base lacks matches nothing there, and Stryker still writes a report.
@@ -135,7 +136,7 @@ A changed unit test that `main` edited after that baseline widens the scope to e
 Start a full baseline with `gh workflow run mutation`, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
 A run with `--mutate` is scoped, so the preset lets it through without `CI=true`.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
-A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
+A public repository keeps `runs-on: ubuntu-latest`, as [checks-ci-wiring](checks-ci-wiring.md#runners) allows a public repository on every job.
 A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its mutation runs.
 The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
@@ -144,4 +145,5 @@ The job never reads `CI_RUNS_ON`, so an override that moves a repository's other
 
 - [checks-mutation](checks-mutation.md)
 - [checks-mutation-scope](checks-mutation-scope.md)
+- [checks-night-run](checks-night-run.md)
 - [checks-test-layout](checks-test-layout.md)

package/docs/gates/checks-mutation-scope.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-mutation-scope
 
-`checks-mutation-scope` turns a pull request's diff into the files its mutation runs mutate, and prints them as lines for `GITHUB_ENV`.
+`checks-mutation-scope` turns a branch's diff into the files its mutation runs mutate, and prints them as `NAME=a,b` lines a CI step appends to its environment file.
 
 ## What it checks
 
@@ -17,23 +17,23 @@ A `mutate` entry with a mutation range, such as `src/a.ts:1-10`, fails the run,
 A renamed source enters under both names, and a deleted source does not enter.
 
 A unit test is a `.test.ts` or `.test.tsx` file under `tests/unit/`, the files the preset's `unitTestFiles` lists.
-A unit test the pull request adds, edits, deletes or renames is changed.
+A unit test the branch adds, edits, deletes or renames is changed.
 A unit test that reads a changed file under `tests/` is changed too.
 It reads a file when it imports it, directly or through another file under `tests/`.
 An import resolves as Bun resolves it, to the file it names, then with an extension added, and only then to the directory's `index`.
 A unit test also reads a changed fixture under `tests/fixtures/` when it names the fixture's path or a directory above it.
 Bun loads each `[test] preload` in `bunfig.toml` before every test file.
 So every unit test is changed when the preload list differs between the merge base and `HEAD`.
-The same holds when the pull request changes a preload or a file a preload imports, wherever that file lives.
+The same holds when the branch changes a preload or a file a preload imports, wherever that file lives.
 
 Each source whose mutants a changed unit test covers or kills in the full baseline report then enters the scope, when it still exists at `HEAD`.
-So a kill lost through a test change alone still shows in the comparison, in a source the pull request leaves alone.
+So a kill lost through a test change alone still shows in the comparison, in a source the branch leaves alone.
 A changed unit test with no baseline report fails the run rather than reading incomplete coverage.
 Stryker records each test file's source in the report's `testFiles`.
 A changed unit test the merge base holds must have that recorded source match its content at the merge base.
 Otherwise the report ran an older test, so its coverage cannot say what the test covers now.
 The scope then widens to every file at `HEAD` the `mutate` globs match.
-A unit test the pull request adds is new to every report, so it needs no entry.
+A unit test the branch adds is new to every report, so it needs no entry.
 Stryker writes no source without mutants into the report, so a mutated source the report lacks may be newer than it.
 When a unit test changed, each such source that exists at `HEAD` enters the scope.
 A change under `tests/e2e/` changes no unit test, so it needs no baseline report.
@@ -61,7 +61,7 @@ The report must come from a run that restored no state and passed `--disableBail
 checks-mutation-scope <base> [<full-baseline-report>]
 ```
 
-`<base>` is the branch the pull request merges into, such as `origin/main`, or the merge base itself.
+`<base>` is the target branch, such as `origin/main`, or the merge base itself.
 `<full-baseline-report>` is the path the full baseline was restored to, and a path with no file reads as no report.
 
 ## Output
@@ -93,7 +93,7 @@ It also names each stale test that widens the scope.
 
 ## Sample output
 
-A helper change that reaches a source the pull request leaves alone:
+A helper change that reaches a source the branch leaves alone:
 
 ```
 mutation-scope: tests/unit/dashboard/snapshot.test.ts reads tests/lib/session-fixture.ts
@@ -116,20 +116,20 @@ mutation-scope: the baseline report did not run tests/unit/dashboard/snapshot.te
 
 ## When it runs
 
-Only a CI step the repository writes runs it, in the pull request's mutation comparison, before either Stryker run:
+Only a CI step the repository writes runs it, in a branch's mutation comparison, before either Stryker run:
 
 ```yaml
 - name: Select mutation scope
   env:
     GH_TOKEN: ${{ github.token }}
   run: |
-    base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+    base="$(git merge-base HEAD origin/main)"
     echo "BASE_SHA=$base" >> "$GITHUB_ENV"
     bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
     bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
 ```
 
-Each later step reads `$SCOPE` from the environment, and a failed scope step adds nothing to it.
+Each later step reads `SCOPE` from the environment, and a failed scope step adds nothing to it.
 [checks-mutation-compare](checks-mutation-compare.md#running-it-in-ci) shows the whole job.
 The full baseline comes from the `mutation` workflow, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
 

package/docs/gates/checks-mutation.md

@@ -12,7 +12,7 @@ It refuses a full mutation run when `CI` is not `true`.
 A full run is one with no `--mutate <glob>` and no `--incremental` flag.
 A `--mutate` without a glob, `--incrementalFile` alone or `--incremental` with `--force` is still a full run.
 Its refusal names `gh workflow run mutation` as the command that starts the same run in CI.
-A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because pull request comparisons scope to named files.
+A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because a branch comparison scopes to named files.
 An incremental run stays allowed locally only when its incremental report exists, because it reuses the results of mutants that did not change.
 That report is the `incrementalFile` Stryker resolves from the command line and the config file, else `reports/stryker-incremental.json`.
 With no report there, the refusal says to pass `--mutate <glob>`, or to start the full baseline in CI with `gh workflow run mutation`.
@@ -75,7 +75,7 @@ An `--incremental` run with no report stops before instrumenting with the missin
 ## When it runs
 
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
-A repository that picks a pull request scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
+A repository that picks a branch scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
 Run scoped checks locally during development.
 Each baseline costs a full Stryker run.
 
@@ -106,9 +106,9 @@ jobs:
 ```
 
 The run restores no state and passes `--disableBail`, so its report names every test that covers or kills each mutant.
-The upload is the `mutation-baseline-full` artifact that a pull request's scope step restores with `checks-mutation-baseline --full`.
+The upload is the `mutation-baseline-full` artifact that a branch comparison's scope step restores with `checks-mutation-baseline --full`.
 [checks-mutation-scope](checks-mutation-scope.md) reads it to bring in the sources a changed unit test covers or kills.
-The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a pull request reads.
+The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a scope step reads.
 The artifact keeps 30 days, so the newest full baseline outlives the week between full runs.
 The upload holds the report without each mutant's `statusReason`, as [checks-mutation-baseline](checks-mutation-baseline.md#the-saved-baselines) says, since the full report of a large repository passes 100 MB as an artifact.
 

package/docs/gates/checks-night-run.md

@@ -0,0 +1,188 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-night-run
+
+`checks-night-run` turns a night run on `main` into GitHub issues, one for each file whose mutation score fell and one for each failing test.
+
+## What it checks
+
+It scores each file of tonight's Stryker report as Stryker does, the `Killed` and `Timeout` mutants over every mutant but the `Ignored`, `CompileError`, `RuntimeError` and `Pending` ones.
+It compares each file's score with the same file's score from the previous night.
+A file whose score is lower than the previous night's is a finding.
+A file only one night holds is no finding, since it lacks one of the two scores.
+A file with no scored mutant has no score, so it is no finding either.
+An equal score is no finding, even when it counts other mutants.
+Each failing test in a JUnit report is a finding, whatever the previous night holds.
+A file whose test worker crashed is one finding, since Bun reports none of its tests.
+With no previous night it compares no score and still files each failing test.
+With no mutation report it compares and records no score and still files each failing test.
+
+Each finding has a key that stays the same from night to night:
+
+| Finding | Key |
+| --- | --- |
+| a file whose mutation score fell | `mutation:<file>` |
+| a failing test | `test:<file> > <describe> > <name>` |
+| a file whose test worker crashed | `test:<file>` |
+
+## How it files a finding
+
+It creates the `night-run` label when the repository lacks it.
+It reads every open issue labelled `night-run`, and reads the key each one carries in a hidden marker in its body.
+A finding whose key an open issue carries gets one comment on that issue, so a regression that lasts two nights stays one issue.
+Any other finding opens one issue labelled `night-run`.
+The issue and the comment name tonight's run, the file and either the test or the score of both nights.
+The body holds the file, the full test name and the finding key.
+A title longer than GitHub's 256 characters is cut to at most 256 and ends in `…`.
+A night with no finding makes no call to GitHub's issues or labels at all.
+Closing an issue ends it, and the same finding on a later night opens a new one.
+Agents and people fix each issue as a task of its own, so no pull request waits for a night run.
+A run on any ref but `refs/heads/main` files no issue and records no score, and lists each finding in its log only.
+
+## What it reads
+
+It reads tonight's Stryker `mutation.json` report, when the mutation run left one, and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
+It reads the previous night from the `night-run` artifact of the newest successful run of the same workflow on `main`.
+That artifact holds `night-run.json`, the scores the run recorded, and a newest run without it counts as no previous night.
+A run on another branch never becomes the previous night.
+On `main` with a mutation report it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
+It reads the run from `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_RUN_ID`, `GITHUB_WORKFLOW_REF` and `GITHUB_REF`, so it runs only inside a GitHub Actions job.
+It calls `gh` with the job's `GH_TOKEN`, which needs `actions: read` for the previous night and `issues: write` for the issues.
+
+## Arguments
+
+```sh
+checks-night-run [--mutation <mutation-report>] [--tests <junit-report>]...
+```
+
+`--mutation` names tonight's Stryker report and is given at most once.
+`--tests` names one JUnit report and is given once per report.
+At least one report is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | it filed every finding and recorded tonight's scores, it found nothing to file, or the run is off `main` and it listed each finding |
+| 2 | an argument does not parse, a report does not decode, a GitHub Actions variable is unset or a `gh` call fails |
+
+It never exits 1, because a finding becomes an issue rather than a failed run.
+
+## Sample output
+
+```
+checks-night-run: the night run https://github.com/acme/widget/actions/runs/12 compared with the night run https://github.com/acme/widget/actions/runs/11; 2 finding(s)
+  opened #31 for mutation:src/cart.ts
+  commented on #27 for test:tests/unit/cart.test.ts > totals > rounds half to even
+checks-night-run: recorded 42 file score(s) in reports/night-run.json
+```
+
+## When it runs
+
+Only a night workflow the repository writes runs it, after that workflow's full mutation run and its long test tiers.
+
+## Running it at night
+
+A repository runs it from a workflow named `night-run` on a schedule, and starts the same workflow by hand with `gh workflow run night-run`:
+
+```yaml
+name: night-run
+on:
+  schedule:
+    - cron: "7 22 * * *"
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: night-run
+  cancel-in-progress: false
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run-mutation
+          path: reports/mutation/mutation.json
+          retention-days: 1
+  tests:
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: |
+          bunx checks-test --tier=live --junit=reports/night-run-tests/live.xml || true
+          bunx checks-test --tier=pixel --junit=reports/night-run-tests/pixel.xml || true
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run-tests
+          path: reports/night-run-tests/
+          retention-days: 1
+  report:
+    needs: [mutation, tests]
+    if: ${{ !cancelled() && needs.tests.result == 'success' }}
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    permissions:
+      contents: read
+      actions: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - if: needs.mutation.result == 'success'
+        uses: actions/download-artifact@v4
+        with:
+          name: night-run-mutation
+          path: reports/mutation
+      - uses: actions/download-artifact@v4
+        with:
+          name: night-run-tests
+          path: reports/night-run-tests
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: bunx checks-night-run ${{ needs.mutation.result == 'success' && '--mutation reports/mutation/mutation.json' || '' }} --tests reports/night-run-tests/live.xml --tests reports/night-run-tests/pixel.xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run
+          path: reports/night-run.json
+          if-no-files-found: ignore
+          retention-days: 90
+```
+
+The cron starts the run at 22:07 UTC, inside the kit's own night window from 22:00 to 22:30 UTC.
+A repository takes minute 7 of its own tier's 30 minute night window, so repositories do not start together.
+The tests job runs each long tier the repository holds, `live` and `pixel` as [checks-test](checks-test.md#test-tiers) names them, and keeps each JUnit report.
+Each `|| true` lets the job go on to the upload after a failing test, since that test becomes an issue.
+A tier that writes no report fails the report job, because `checks-night-run` cannot read it.
+The report job runs whenever the tests job succeeds, so a failing test that also stops Stryker still becomes an issue.
+It passes `--mutation` only when the mutation job succeeded, and the failed mutation job still fails the run.
+The concurrency group queues a run started by hand behind the scheduled one, so two runs never file the same finding twice.
+A dispatch on a branch runs both jobs and lists its findings in the report job's log, and `if-no-files-found: ignore` lets that run upload no record.
+`issues: write` on the report job is the one permission beyond reading the repository and its runs.
+A public repository keeps `runs-on: ubuntu-latest` on the mutation job.
+A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` on the mutation job, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
+The report job reads `CI_RUNS_ON`, because it runs no mutant.
+A successful run uploads `night-run`, so the next night compares with it, and a failed run uploads nothing a later night reads.
+The artifact keeps 90 days, so a gap of nights still leaves a previous night to compare with.
+
+## Related topics
+
+- [checks-test](checks-test.md)
+- [checks-mutation](checks-mutation.md)
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-ci-wiring](checks-ci-wiring.md)

package/docs/gates/checks-release-notes.md

@@ -140,7 +140,8 @@ jobs:
 ```
 
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
-A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
+A release is a pull request that holds only the version bump and the built changelog.
+[checks-release-pr](checks-release-pr.md) opens it on the daily release's schedule, or on every push to `main` in a package repository.
 When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
 A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
 A tag a person pushes starts the same workflow through its `push` trigger.

package/docs/gates/checks-release-pr.md

@@ -75,19 +75,23 @@ release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d
 ## When it runs
 
 The daily release workflow below runs it once a day on the default branch.
+A package repository runs it on every push to `main` other than a release commit.
 Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
 
 ## Running it in CI
 
 A repository takes the daily release as `.github/workflows/daily-release.yml`.
-A repository schedules it at minute 7 of its tier's 30 minute night window, so repositories do not start together.
+A consuming repository pins daily-release between 03:00 and 04:00 UTC at a minute chosen so repositories do not start together.
+A package repository released on push drops the `schedule` trigger, so every push to `main` but a release commit opens or refreshes the release pull request.
+Its `pull-request` job's `if` reads `"github.event_name != 'push' || !startsWith(github.event.head_commit.message, 'chore: release ')"`.
+The `pull-request` job checks out its branch's tip when it starts, so a run that starts late never rebuilds the release on an older commit.
 The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
 
 ```yaml
 name: daily-release
 on:
   schedule:
-    - cron: "7 22 * * *"
+    - cron: "7 3 * * *"
   workflow_dispatch:
   push:
     branches: [main]
@@ -108,6 +112,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
+          ref: ${{ github.ref }}
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
         with:

package/docs/gates/checks-test.md

@@ -47,7 +47,7 @@ A skipped test or a todo without `skipReason` fails in every environment.
 It does not read a skip list from `package.json`.
 It counts a run as `ci` when `CI` is true and as `local` otherwise.
 
-The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs).
+The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs) and the file `--junit` keeps the report at.
 Use `checks-test --tier=live` or `checks-test --tier=pixel` for a named test tier.
 Use `checks-test --tier=unit` or `checks-test --tier=e2e` to run only one level of the default suite.
 A live or pixel run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
@@ -102,8 +102,10 @@ A timings option waits for Bun to honour timings under random order.
 
 ## Arguments
 
-The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says.
+The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says, and `--junit=<file>`.
 Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too.
+`--junit=<file>` keeps the JUnit report Bun wrote at `<file>`, whether the tests passed or failed, so a night run hands it to [checks-night-run](checks-night-run.md).
+A `package.json` script never takes `--junit`, as [checks-test-layout](checks-test-layout.md) says of `scripts.test`.
 Each option appears at most once.
 It refuses test filters because every test excluded by a filter would look skipped.
 
@@ -138,3 +140,4 @@ A repository that tracks no TypeScript source does not need it, as [checks-test-
 - [checks-test-layout](checks-test-layout.md)
 - [checks-flake](checks-flake.md)
 - [checks-quarantine-clock](checks-quarantine-clock.md)
+- [checks-night-run](checks-night-run.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,8 @@
     "src/testing/mutation-baseline.ts",
     "src/testing/mutation-baseline-saved.ts",
     "src/testing/subsumed-tests.ts",
+    "src/testing/night-run.ts",
+    "src/testing/night-run-findings.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
     "src/delivery/workflow-references.ts",
@@ -156,6 +158,7 @@
     "checks-mutation-baseline": "src/testing/mutation-baseline.ts",
     "checks-mutation-scope": "src/testing/mutation-scope.ts",
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
+    "checks-night-run": "src/testing/night-run.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",
     "checks-comment-gate": "src/quality/comment-gate.ts",
     "checks-css-size": "src/quality/css-size.ts",

package/src/delivery/github.ts

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/process";
-import { collect } from "../core/git.ts";
+import { collect, type Feed } from "../core/git.ts";
 
 export class GitHubFailure extends Schema.TaggedError<GitHubFailure>()("GitHubFailure", {
   message: Schema.String,
@@ -13,17 +13,16 @@ type Decode<A> = (text: string) => Effect.Effect<A, Schema.SchemaError>;
 // gh fills {owner} and {repo} from the checkout's remote, so a workflow names no repository.
 export const REPOSITORY = "repos/{owner}/{repo}";
 
-const gitHub = Effect.fn("gitHub")(function* (method: Method, path: string, body?: unknown) {
-  const failed = (reason: string): GitHubFailure => new GitHubFailure({ message: `gh api ${method} ${path}: ${reason.trim()}` });
-  const input = body === undefined ? [] : ["--input", "-"];
-  const feed = body === undefined ? {} : { input: JSON.stringify(body) };
-  const { stdout, stderr, exitCode } = yield* collect("gh", ["api", "--method", method, path, ...input], undefined, feed).pipe(
-    Effect.mapError((cause) => failed(cause.message)),
-  );
+export const gh = Effect.fn("gh")(function* (args: readonly string[], call = `gh ${args.join(" ")}`, feed: Feed = {}) {
+  const failed = (reason: string): GitHubFailure => new GitHubFailure({ message: `${call}: ${reason.trim()}` });
+  const { stdout, stderr, exitCode } = yield* collect("gh", args, undefined, feed).pipe(Effect.mapError((cause) => failed(cause.message)));
   if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
   return stdout;
 });
 
+const gitHub = (method: Method, path: string, body?: unknown) =>
+  gh(["api", "--method", method, path, ...(body === undefined ? [] : ["--input", "-"])], `gh api ${method} ${path}`, body === undefined ? {} : { input: JSON.stringify(body) });
+
 export function gitHubJson<A>(decode: Decode<A>, method: Method, path: string, body?: unknown): Effect.Effect<A, GitHubFailure, ChildProcessSpawner.ChildProcessSpawner> {
   return gitHub(method, path, body).pipe(
     Effect.flatMap((text) =>

package/src/testing/mutation-compare.ts

@@ -81,7 +81,7 @@ export class ReportError extends Schema.TaggedError<ReportError>()("ReportError"
   message: Schema.String,
 }) {}
 
-const OUTCOME = {
+export const OUTCOME = {
   Killed: "detected",
   Timeout: "detected",
   Survived: "undetected",

package/src/testing/mutation-scope.ts

@@ -186,7 +186,7 @@ export function readersOf(sources: ReadonlyMap<string, string>, changed: readonl
   return new Map([...reached].filter(([file, via]) => file !== via));
 }
 
-// Names what every unit test loads that the pull request changes: the preload list, a preload, or a file a preload imports.
+// Names what every unit test loads that the branch changes: the preload list, a preload, or a file a preload imports.
 export function preloadChange(
   changed: ReadonlySet<string>,
   preloads: { readonly atBase: readonly string[]; readonly atHead: readonly string[] },

package/src/testing/night-run-findings.ts

@@ -0,0 +1,74 @@
+import { Option, Schema } from "effect";
+import { OUTCOME, type ReportFile } from "./mutation-compare.ts";
+import { NAME_SEPARATOR, type TestResult } from "./test-report.ts";
+
+const ScoreSchema = Schema.Struct({ detected: Schema.Int, valid: Schema.Int });
+
+export type Score = typeof ScoreSchema.Type;
+
+export const NightRecordSchema = Schema.Struct({ scores: Schema.Record(Schema.String, ScoreSchema) });
+
+export type NightRecord = typeof NightRecordSchema.Type;
+
+export type TestReport = { readonly results: readonly TestResult[]; readonly crashedFiles: readonly string[] };
+
+export type Tonight = { readonly scores: NightRecord["scores"]; readonly tests: readonly TestReport[] };
+
+export type PreviousNight = { readonly url: string; readonly record: NightRecord };
+
+export type Finding =
+  | { readonly kind: "mutation"; readonly file: string; readonly before: Score; readonly after: Score; readonly since: string }
+  | { readonly kind: "test"; readonly file: string; readonly name: string }
+  | { readonly kind: "crash"; readonly file: string };
+
+function scoreOf(file: ReportFile): Score {
+  let detected = 0;
+  let valid = 0;
+  for (const mutant of file.mutants) {
+    const outcome = OUTCOME[mutant.status];
+    if (outcome === "leaves-score") continue;
+    valid += 1;
+    if (outcome === "detected") detected += 1;
+  }
+  return { detected, valid };
+}
+
+export function scoresOf(files: ReadonlyMap<string, ReportFile>): NightRecord["scores"] {
+  return Object.fromEntries([...files].map(([path, file]) => [path, scoreOf(file)] as const).sort(([one], [other]) => one.localeCompare(other)));
+}
+
+// Cross-multiplied, so two equal scores never differ by how their quotients round.
+function fell(before: Score, after: Score): boolean {
+  return before.valid > 0 && after.valid > 0 && after.detected * before.valid < before.detected * after.valid;
+}
+
+export function keyOf(finding: Finding): string {
+  if (finding.kind === "mutation") return `mutation:${finding.file}`;
+  if (finding.kind === "test") return `test:${finding.file}${NAME_SEPARATOR}${finding.name}`;
+  return `test:${finding.file}`;
+}
+
+function scoreFindings(previous: Option.Option<PreviousNight>, scores: NightRecord["scores"]): readonly Finding[] {
+  if (Option.isNone(previous)) return [];
+  const { url, record } = previous.value;
+  return Object.entries(scores).flatMap(([file, after]): readonly Finding[] => {
+    const before = record.scores[file];
+    return before !== undefined && fell(before, after) ? [{ kind: "mutation", file, before, after, since: url }] : [];
+  });
+}
+
+function testFindings(reports: readonly TestReport[]): readonly Finding[] {
+  const failing = reports.flatMap(({ results, crashedFiles }) => [
+    ...results.filter((result) => result.outcome === "failed").map((result): Finding => ({ kind: "test", file: result.file, name: result.name })),
+    ...crashedFiles.map((file): Finding => ({ kind: "crash", file })),
+  ]);
+  return [...new Map(failing.map((finding) => [keyOf(finding), finding])).values()];
+}
+
+export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight): readonly Finding[] {
+  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests)].sort((one, other) => keyOf(one).localeCompare(keyOf(other)));
+}
+
+export function percent(score: Score): string {
+  return `${((score.detected / score.valid) * 100).toFixed(2)}%`;
+}

package/src/testing/night-run.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env bun
+import { Config, Console, Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { DEFAULT_BRANCH } from "../core/gates.ts";
+import { runMain, Usage } from "../core/main.ts";
+import { gh, type GitHubFailure, gitHubJson, REPOSITORY } from "../delivery/github.ts";
+import { parseReport as parseMutationReport } from "./mutation-compare.ts";
+import { type Finding, findingsOf, keyOf, NightRecordSchema, type NightRecord, percent, type PreviousNight, scoresOf, type TestReport } from "./night-run-findings.ts";
+import { parseReport as parseTestReport } from "./test-report.ts";
+
+const NAME = "checks-night-run";
+const USAGE = `usage: ${NAME} [--mutation <mutation-report>] [--tests <junit-report>]...`;
+export const LABEL = "night-run";
+const LABEL_COLOR = "5319e7";
+const LABEL_DESCRIPTION = "A regression a night run on main found";
+const ARTIFACT = "night-run";
+const RECORD_NAME = "night-run.json";
+export const RECORD = `reports/${RECORD_NAME}`;
+const PAGE_SIZE = 100;
+const GITHUB_TITLE_LIMIT = 256;
+
+class NightRunFailure extends Schema.TaggedError<NightRunFailure>()("NightRunFailure", {
+  message: Schema.String,
+}) {}
+
+export type Options = { readonly mutation: Option.Option<string>; readonly tests: readonly string[] };
+
+export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {
+  const mutation: string[] = [];
+  const tests: string[] = [];
+  for (let at = 0; at < argv.length; at += 2) {
+    const [flag, value] = [argv[at], argv[at + 1]];
+    const into = flag === "--mutation" ? mutation : flag === "--tests" ? tests : undefined;
+    if (into === undefined || value === undefined || value.startsWith("--")) return yield* new Usage({ message: USAGE });
+    into.push(value);
+  }
+  if (mutation.length > 1 || mutation.length + tests.length === 0) return yield* new Usage({ message: USAGE });
+  return { mutation: Option.fromNullishOr(mutation[0]), tests };
+});
+
+export type OpenIssue = { readonly number: number; readonly key: string };
+
+export type Filed = { readonly key: string; readonly issue: number; readonly action: "opened" | "commented on" };
+
+export class Issues extends Context.Service<
+  Issues,
+  {
+    readonly ensureLabel: Effect.Effect<void, GitHubFailure>;
+    readonly open: Effect.Effect<readonly OpenIssue[], GitHubFailure>;
+    readonly create: (title: string, body: string) => Effect.Effect<number, GitHubFailure>;
+    readonly comment: (issue: number, body: string) => Effect.Effect<void, GitHubFailure>;
+  }
+>()("@avi2dg/checks/testing/Issues") {
+  static readonly gh = Layer.effect(
+    Issues,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<ChildProcessSpawner.ChildProcessSpawner>();
+      const provided = <A>(effect: Effect.Effect<A, GitHubFailure, ChildProcessSpawner.ChildProcessSpawner>) => effect.pipe(Effect.provideContext(services));
+      return Issues.of({
+        ensureLabel: provided(ensureLabel),
+        open: provided(openIssues),
+        create: (title, body) => provided(gitHubJson(decodeNumbered, "POST", `${REPOSITORY}/issues`, { title, body, labels: [LABEL] })).pipe(Effect.map(({ number }) => number)),
+        comment: (issue, body) => provided(gitHubJson(decodeAny, "POST", `${REPOSITORY}/issues/${issue}/comments`, { body })).pipe(Effect.asVoid),
+      });
+    }),
+  );
+}
+
+const decodeNumbered = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ number: Schema.Int })));
+const decodeAny = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+const decodeIssues = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Array(Schema.Struct({ number: Schema.Int, body: Schema.NullOr(Schema.String), pull_request: Schema.optionalKey(Schema.Unknown) }))),
+);
+const decodeKey = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.String));
+
+const MARKER = /<!-- checks-night-run ("(?:[^"\\]|\\.)*") -->/;
+
+// The key is JSON with every > escaped, so no key can close the HTML comment early.
+export function marker(key: string): string {
+  return `<!-- checks-night-run ${JSON.stringify(key).replaceAll(">", "\\u003e")} -->`;
+}
+
+export function markedKey(body: string | null): Option.Option<string> {
+  const quoted = body === null ? undefined : MARKER.exec(body)?.[1];
+  return quoted === undefined ? Option.none() : decodeKey(quoted);
+}
+
+const ensureLabel = gh(["label", "create", LABEL, "--color", LABEL_COLOR, "--description", LABEL_DESCRIPTION, "--force"]).pipe(Effect.asVoid);
+
+const openIssues = Effect.gen(function* () {
+  const found: OpenIssue[] = [];
+  for (let page = 1; ; page += 1) {
+    const batch = yield* gitHubJson(decodeIssues, "GET", `${REPOSITORY}/issues?labels=${LABEL}&state=open&per_page=${PAGE_SIZE}&page=${page}`);
+    for (const issue of batch) {
+      const key = markedKey(issue.body);
+      if (issue.pull_request === undefined && Option.isSome(key)) found.push({ number: issue.number, key: key.value });
+    }
+    if (batch.length < PAGE_SIZE) return found;
+  }
+});
+
+function fullTitleOf(finding: Finding): string {
+  if (finding.kind === "mutation") return `Night run: mutation score fell in ${finding.file}`;
+  if (finding.kind === "test") return `Night run: ${finding.file} > ${finding.name} fails`;
+  return `Night run: ${finding.file} crashed its test worker`;
+}
+
+export function titleOf(finding: Finding): string {
+  const title = fullTitleOf(finding);
+  if (title.length <= GITHUB_TITLE_LIMIT) return title;
+  const end = GITHUB_TITLE_LIMIT - 1;
+  const splitsPair = /[\uD800-\uDBFF]/.test(title.charAt(end - 1));
+  return `${title.slice(0, splitsPair ? end - 1 : end)}…`;
+}
+
+export function findingText(finding: Finding, run: string): string {
+  if (finding.kind === "mutation") {
+    const { file, before, after, since } = finding;
+    return [
+      `The night run ${run} scored \`${file}\` lower than the night run ${since}.`,
+      "",
+      "| File | Previous night | Tonight |",
+      "| --- | --- | --- |",
+      `| \`${file}\` | ${percent(before)}, ${before.detected} of ${before.valid} mutants detected | ${percent(after)}, ${after.detected} of ${after.valid} mutants detected |`,
+    ].join("\n");
+  }
+  if (finding.kind === "test") return `The night run ${run} failed \`${finding.name}\` in \`${finding.file}\`.`;
+  return `The night run ${run} lost every result of \`${finding.file}\`, because the worker running it crashed.`;
+}
+
+export function issueBody(finding: Finding, run: string): string {
+  return `${findingText(finding, run)}\n\nFinding key: \`${keyOf(finding)}\`\n\n${marker(keyOf(finding))}\n`;
+}
+
+// Nothing to file means no call at all, so a quiet night never touches the label or the issues.
+export const fileFindings = Effect.fn("fileFindings")(function* (findings: readonly Finding[], run: string) {
+  if (findings.length === 0) return [];
+  const issues = yield* Issues;
+  yield* issues.ensureLabel;
+  const open = new Map((yield* issues.open).map((issue) => [issue.key, issue.number]));
+  const filed: Filed[] = [];
+  for (const finding of findings) {
+    const key = keyOf(finding);
+    const known = open.get(key);
+    if (known === undefined) {
+      const issue = yield* issues.create(titleOf(finding), issueBody(finding, run));
+      open.set(key, issue);
+      filed.push({ key, issue, action: "opened" });
+    } else {
+      yield* issues.comment(known, findingText(finding, run));
+      filed.push({ key, issue: known, action: "commented on" });
+    }
+  }
+  return filed;
+});
+
+const required = (name: string) =>
+  Config.String(name).pipe(Effect.mapError(() => new NightRunFailure({ message: `${name} is unset, so ${NAME} runs only inside a GitHub Actions job` })));
+
+const WORKFLOW_FILE = /\/\.github\/workflows\/([^/@]+)@/;
+
+type Actions = { readonly runs: string; readonly run: string; readonly workflow: string; readonly ref: string };
+
+const actionsRun = Effect.gen(function* () {
+  const runs = `${yield* required("GITHUB_SERVER_URL")}/${yield* required("GITHUB_REPOSITORY")}/actions/runs`;
+  const reference = yield* required("GITHUB_WORKFLOW_REF");
+  const workflow = WORKFLOW_FILE.exec(reference)?.[1];
+  if (workflow === undefined) return yield* new NightRunFailure({ message: `GITHUB_WORKFLOW_REF ${reference} names no workflow file` });
+  return { runs, run: `${runs}/${yield* required("GITHUB_RUN_ID")}`, workflow, ref: yield* required("GITHUB_REF") } satisfies Actions;
+});
+
+const decodeRuns = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.Struct({ databaseId: Schema.Int }))));
+const decodeArtifacts = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ artifacts: Schema.Array(Schema.Struct({ name: Schema.String, expired: Schema.Boolean })) })));
+const decodeRecord = Schema.decodeUnknownEffect(Schema.fromJsonString(NightRecordSchema));
+
+const unreadable = (source: string) => (cause: { readonly message: string }) => new NightRunFailure({ message: `cannot read ${source}: ${cause.message}` });
+
+// Only the newest successful run on main counts, so a branch dispatch never becomes the night a later run compares with.
+const previousNight = Effect.fn("previousNight")(
+  function* ({ runs, workflow }: Actions) {
+    const listed = ["run", "list", "--workflow", workflow, "--branch", DEFAULT_BRANCH, "--status", "success", "--limit", "1", "--json", "databaseId,event,createdAt"];
+    const [newest] = yield* gh(listed).pipe(Effect.flatMap(decodeRuns), Effect.mapError(unreadable(`the runs of ${workflow}`)));
+    if (newest === undefined) return Option.none<PreviousNight>();
+    const run = newest.databaseId;
+    const { artifacts } = yield* gh(["api", `${REPOSITORY}/actions/runs/${run}/artifacts?name=${ARTIFACT}`]).pipe(
+      Effect.flatMap(decodeArtifacts),
+      Effect.mapError(unreadable(`the artifacts of run ${run}`)),
+    );
+    if (!artifacts.some((artifact) => artifact.name === ARTIFACT && !artifact.expired)) return Option.none<PreviousNight>();
+    const fs = yield* FileSystem.FileSystem;
+    const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-night-run-" });
+    yield* gh(["run", "download", String(run), "--name", ARTIFACT, "--dir", dir]);
+    const file = (yield* Path.Path).join(dir, RECORD_NAME);
+    const record = yield* fs.readFileString(file).pipe(Effect.flatMap(decodeRecord), Effect.mapError(unreadable(`the ${ARTIFACT} artifact of run ${run}`)));
+    return Option.some<PreviousNight>({ url: `${runs}/${run}`, record });
+  },
+  Effect.scoped,
+);
+
+const readText = Effect.fn("readText")(function* (file: string) {
+  return yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(Effect.mapError(unreadable(file)));
+});
+
+const testReport = Effect.fn("testReport")(function* (file: string) {
+  return yield* parseTestReport(yield* readText(file)).pipe(Effect.mapError(unreadable(file)));
+});
+
+const writeRecord = Effect.fn("writeRecord")(function* (record: NightRecord) {
+  const fs = yield* FileSystem.FileSystem;
+  yield* fs.makeDirectory((yield* Path.Path).dirname(RECORD), { recursive: true });
+  yield* fs.writeFileString(RECORD, `${JSON.stringify(record, null, 2)}\n`);
+});
+
+const tonightScores = Effect.fn("tonightScores")(function* (file: string) {
+  return scoresOf(yield* parseMutationReport(file, yield* readText(file)));
+});
+
+type Filing = { readonly onMain: true; readonly filed: readonly Filed[] } | { readonly onMain: false; readonly ref: string };
+
+export function report(run: string, scored: Option.Option<number>, previous: Option.Option<PreviousNight>, findings: readonly Finding[], filing: Filing): string {
+  const against = Option.isNone(scored)
+    ? "had no mutation report, so it compared no score"
+    : Option.isSome(previous)
+      ? `compared with the night run ${previous.value.url}`
+      : `found no earlier successful run on ${DEFAULT_BRANCH} holding a ${ARTIFACT} artifact, so it compared no score`;
+  const verdict = findings.length === 0 ? "no finding" : `${findings.length} finding(s)`;
+  const listed = filing.onMain ? filing.filed.map((one) => `  ${one.action} #${one.issue} for ${one.key}`) : findings.map((finding) => `  found ${keyOf(finding)}`);
+  const recorded = !filing.onMain
+    ? `${NAME}: the run is on ${filing.ref}, not ${DEFAULT_BRANCH}, so it filed no issue and recorded no score`
+    : Option.isSome(scored)
+      ? `${NAME}: recorded ${scored.value} file score(s) in ${RECORD}`
+      : `${NAME}: recorded no score, since it had no mutation report`;
+  return [`${NAME}: the night run ${run} ${against}; ${verdict}`, ...listed, recorded].join("\n");
+}
+
+const nightRun = Effect.gen(function* () {
+  const options = yield* parseArgs(process.argv.slice(2));
+  const actions = yield* actionsRun;
+  const scores = Option.isSome(options.mutation) ? Option.some(yield* tonightScores(options.mutation.value)) : Option.none<NightRecord["scores"]>();
+  const tests: TestReport[] = yield* Effect.forEach(options.tests, testReport);
+  const previous = Option.isSome(scores) ? yield* previousNight(actions) : Option.none<PreviousNight>();
+  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests });
+  const filing: Filing = actions.ref === `refs/heads/${DEFAULT_BRANCH}` ? { onMain: true, filed: yield* fileFindings(findings, actions.run) } : { onMain: false, ref: actions.ref };
+  if (filing.onMain && Option.isSome(scores)) yield* writeRecord({ scores: scores.value });
+  yield* Console.log(report(actions.run, Option.map(scores, (tonight) => Object.keys(tonight).length), previous, findings, filing));
+  return true;
+});
+
+export function main(issues: Layer.Layer<Issues, never, ChildProcessSpawner.ChildProcessSpawner>): void {
+  runMain(NAME, nightRun.pipe(Effect.provide(issues)));
+}
+
+if (import.meta.main) main(Issues.gh);

package/src/testing/test.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { TEST_ENTRY_POINT } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
@@ -26,7 +26,7 @@ export type TestOptions = {
 };
 
 const NAME = TEST_ENTRY_POINT.bin;
-const USAGE = `usage: ${NAME} [--tier=live | --tier=pixel | --tier=unit | --tier=e2e] [--parallel=<workers>], and it refuses test filters`;
+const USAGE = `usage: ${NAME} [--tier=live | --tier=pixel | --tier=unit | --tier=e2e] [--parallel=<workers>] [--junit=<file>], and it refuses test filters`;
 const TIERS = new Map<string, TestTier>([
   ["--tier=live", "live"],
   ["--tier=pixel", "pixel"],
@@ -34,6 +34,7 @@ const TIERS = new Map<string, TestTier>([
   ["--tier=e2e", "e2e"],
 ]);
 const PARALLEL = /^--parallel=([1-9][0-9]*)$/;
+const JUNIT = /^--junit=(.+)$/;
 
 function optionOf(arg: string): TestOptions | undefined {
   const tier = TIERS.get(arg);
@@ -52,6 +53,16 @@ export function testOptions(args: readonly string[]): TestOptions | undefined {
   return options;
 }
 
+export type EntryOptions = { readonly options: TestOptions; readonly junit: Option.Option<string> };
+
+// Kept out of testOptions, so checks-test-layout still holds a package.json test script to --parallel alone.
+export function entryOptions(args: readonly string[]): EntryOptions | undefined {
+  const junit = args.flatMap((arg) => JUNIT.exec(arg)?.[1] ?? []);
+  const options = testOptions(args.filter((arg) => !JUNIT.test(arg)));
+  if (options === undefined || junit.length > 1) return undefined;
+  return { options, junit: Option.fromNullishOr(junit[0]) };
+}
+
 const TEST_SCRIPTS: readonly string[] = [NAME, `bun src/${TEST_ENTRY_POINT.script}`];
 
 export function scriptOptions(script: unknown): TestOptions | undefined {
@@ -169,15 +180,22 @@ const runSuite = Effect.fn("runSuite")(function* (outfile: string, { tier, worke
 });
 
 const testEntry = Effect.gen(function* () {
-  const options = testOptions(process.argv.slice(2));
-  if (options === undefined) return yield* new Usage({ message: USAGE });
+  const entry = entryOptions(process.argv.slice(2));
+  if (entry === undefined) return yield* new Usage({ message: USAGE });
+  const { options, junit } = entry;
   const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   const declarations = yield* readSkipDeclarations(process.cwd(), options.tier);
   const environment = yield* environmentOf;
 
-  const outfile = (yield* Path.Path).join(yield* fs.makeTempDirectoryScoped({ prefix: "checks-test-" }), "junit.xml");
+  const outfile = path.join(yield* fs.makeTempDirectoryScoped({ prefix: "checks-test-" }), "junit.xml");
   const suitePassed = (yield* runSuite(outfile, options)) === ChildProcessSpawner.ExitCode(0);
-  if (!(yield* fs.exists(outfile))) {
+  const written = yield* fs.exists(outfile);
+  if (written && Option.isSome(junit)) {
+    yield* fs.makeDirectory(path.dirname(junit.value), { recursive: true });
+    yield* fs.copyFile(outfile, junit.value);
+  }
+  if (!written) {
     if (!suitePassed) {
       yield* Console.error(`${NAME}: bun test failed before it wrote a report, so no skip was judged`);
       return false;