From fc77ef834f6c613bcba278d41051f61d9ee78da5 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 10:13:44 +0800
Subject: [PATCH 01/44] 1.4.0: the month ubuntu-latest is two operating systems

GitHub is re-pointing ubuntu-latest from Ubuntu 24.04 to 26.04 between
2026-10-19 and 2026-11-19 (actions/runner-images#14748). For that month the
label means either image depending on which runner a job lands on, and nothing
in the lock file can tell you which one you got.

MIGRATIONS in src/labels.mjs holds the announced windows, keyed by floating
label, separate from DEADLINES because a deadline retires a concrete label and
offers destinations you pick between, while a migration is a floating label
being re-pointed on dates you do not. One entry today; windows-latest and
macos-latest are a data addition.

- plan --from ubuntu-latest resolves the pair and diffs the two images, kernel
  and systemd included, instead of refusing the label.
- guard --fail-on-migration <days> classifies the window against the ImageOS
  the runner exported: pending, moved-early, not-yet-migrated, ambiguous,
  migrated, settled, stale, unexpected. Off by default. fail-on,
  fail-on-retirement and fail-on-deprecation are untouched.
- Drift that the announced move explains says so, from the table, with no flag
  and no extra request.
- --as-of <date> moves every countdown, so the month can be rehearsed now.
- All four output formats carry it: text, annotations on the runs-on: line,
  step summary, --json.

319 tests pass, and the same 319 pass with fetch replaced by a throw.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |  32 +
 CHANGELOG.md                                  |  85 +++
 README.md                                     | 141 ++++-
 action.yml                                    |   8 +-
 package.json                                  |   4 +-
 src/cli.mjs                                   | 230 ++++++--
 src/detect.mjs                                |  37 +-
 src/http.mjs                                  |   2 +-
 src/index.mjs                                 |  16 +
 src/labels.mjs                                | 171 +++++-
 src/manifest.mjs                              |  64 +-
 src/migration.mjs                             | 105 ++++
 src/report.mjs                                | 172 +++++-
 test/cli.test.mjs                             |  45 +-
 .../Ubuntu2404-Readme-20260907.300.1.md       | 333 +++++++++++
 .../Ubuntu2604-Readme-20260907.131.1.md       | 316 ++++++++++
 test/fixtures/workflows-migration/latest.yml  |  18 +
 test/helpers.mjs                              |  19 +-
 test/migration.test.mjs                       | 558 ++++++++++++++++++
 19 files changed, 2261 insertions(+), 95 deletions(-)
 create mode 100644 src/migration.mjs
 create mode 100644 test/fixtures/Ubuntu2404-Readme-20260907.300.1.md
 create mode 100644 test/fixtures/Ubuntu2604-Readme-20260907.131.1.md
 create mode 100644 test/fixtures/workflows-migration/latest.yml
 create mode 100644 test/migration.test.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 18efae7..9f79336 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -134,6 +134,38 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
 
+  migration:
+    # Deliberately floating. Every other job here pins its image; this one is the
+    # lane's subject, and reading ImageOS off a runner that GitHub is in the
+    # middle of re-pointing is the half no test can reach.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - name: plan the announced ubuntu-latest move against the live manifests
+        run: node src/cli.mjs plan --from ubuntu-latest
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      # The exit code is deliberately not asserted: it is 1 while the window is
+      # ahead of this runner and 0 once the move has reached it, so pinning it
+      # would turn the rollout itself into a red build. What must hold on every
+      # run is that the lane resolved the label and named its source.
+      - name: guard --fail-on-migration on a real floating runner
+        run: |
+          set -uo pipefail
+          out="$(node src/cli.mjs guard --tools node --fail-on-migration 30 --no-update-lock 2>&1)"
+          code=$?
+          printf '%s\n' "$out"
+          echo "exit $code"
+          grep -q 'ubuntu-latest' <<<"$out" || { echo 'the migration lane said nothing'; exit 1; }
+          grep -q 'actions/runner-images#14748' <<<"$out" || { echo 'no source named'; exit 1; }
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
   runners:
     runs-on: ubuntu-24.04
     steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ecb700c..639ca51 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,91 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] — 2026-09-20
+
+### Added
+
+- **The `ubuntu-latest` migration lane.** GitHub's changelog of 2026-09-17: *"The
+  ubuntu-latest label will migrate from Ubuntu 24.04 to Ubuntu 26.04. This
+  migration will roll out gradually between October 19 and November 19, 2026."*
+  ([actions/runner-images#14748](https://github.com/actions/runner-images/issues/14748)).
+
+  For that month `ubuntu-latest` is two different operating systems depending on
+  which runner the job lands on, and no workflow file changes. The kernel goes
+  `6.17.0-1022-azure` -> `7.0.0-1012-azure` and systemd `255.4-1ubuntu8.17` ->
+  `259.5-0ubuntu3.4`, while Docker Buildx, the AWS and Azure CLIs, Rust and Java
+  17 are the same on both images. That is exactly the kind of change this tool
+  exists to show you before it lands.
+
+  `MIGRATIONS` in `src/labels.mjs` records the announced moves: the floating
+  label, the two concrete labels it moves between, the window and the source
+  issue. It sits beside the retirement `DEADLINES` table rather than inside it,
+  and shares no keys with it: a retirement is an end date for one image, a
+  migration is a dated window between two live ones. Today it has one entry.
+  `windows-latest` and `macos-latest` are a data addition when GitHub announces
+  them.
+
+- **`plan --from <floating label>`** no longer refuses. Where `MIGRATIONS` names
+  both ends, `plan` resolves them and diffs the two concrete images, so the
+  output is the kernel and systemd deltas rather than a bare warning:
+
+  ```
+  $ runner-drift plan --from ubuntu-latest
+  ubuntu-latest moves from ubuntu-24.04 to ubuntu-26.04. The rollout starts 2026-10-19 (18 days) and finishes 2026-11-19 (49 days).
+  announced 2026-09-17; source actions/runner-images#14748 https://github.com/actions/runner-images/issues/14748
+  ubuntu-24.04 -> ubuntu-26.04 (images 20260907.300.1 -> 20260907.131.1)
+
+  OS 24.04.5 LTS -> 26.04.1 LTS  MAJOR
+  Kernel 6.17.0-1022-azure -> 7.0.0-1012-azure  MAJOR
+  Systemd 255.4-1ubuntu8.17 -> 259.5-0ubuntu3.4  MAJOR
+  ```
+
+  A floating `--to`, or a floating `--from` with no announced migration, is
+  refused exactly as before. `plan` also gained the three image-header rows (OS,
+  kernel, systemd) for every comparison, not just this one, since they were being
+  parsed already and dropped.
+
+- **`guard --fail-on-migration <days>`**, and the matching `fail-on-migration`
+  action input. Off by default, like `fail-on-retirement`: without it `guard`
+  does not fetch the two manifests at all. With it, each floating `runs-on:` line
+  is annotated according to where today sits in the window and which `ImageOS`
+  the runner exported: pending, this runner has not moved yet, the migration has
+  reached this runner, done, or, past the window on the old image, an anomaly.
+  The anomaly fails whatever the threshold, the same rule a label already past
+  its retirement date follows.
+
+  When the observed image explains the tool drift `guard` just found, the report
+  says so, rather than leaving a page of major bumps looking unexplained. That
+  line needs no input: a lock recorded on one side of an announced move and a
+  runner on the other is a table lookup, not a check to opt into.
+
+  ```
+  Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04 (2026-10-19 to 2026-11-19); the tool versions below moved with the image.
+  ```
+
+  `--fail-on`, `--fail-on-retirement` and `--fail-on-deprecation` are untouched,
+  and so are all four output formats' existing contents: the migration is a new
+  annotation group, a new step-summary table (Label, Phase, Move, Window, This
+  runner, Source) and a new `migration` key in `--json`.
+
+- **`--as-of <date>`** on every command. It moves the clock every countdown is
+  measured from and nothing else, so `plan --from ubuntu-latest --as-of
+  2026-10-19` answers what the report will say on the first day of the rollout
+  without pretending the run happened then. It is also what makes the migration
+  tests deterministic.
+
+- `init` refusing a floating label now points at the migration when there is one,
+  instead of only saying "pass a concrete label".
+
+### Changed
+
+- `resolveManifestVersions` moved from `src/cli.mjs` to `src/manifest.mjs`, where
+  the rest of the manifest reading lives, and is re-exported from `cli.mjs` so
+  the public surface is unchanged. The migration lane needed it and importing it
+  from the CLI would have made a cycle.
+
+[1.4.0]: https://github.com/Booyaka101/runner-drift/releases/tag/v1.4.0
+
 ## [1.3.0] — 2026-09-13
 
 ### Added
diff --git a/README.md b/README.md
index 77974b6..ea9d709 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ rolling: you have 30 days from each `actions/runner` release to install it, or
 [the Actions service stops queueing jobs to your runner](https://docs.github.com/en/actions/reference/runners/self-hosted-runners).
 `runner-drift runners` reads the dates straight from GitHub's API and names the
 runners that are about to go quiet. See
-[Self-hosted agent versions](#5-runner-drift-runners--self-hosted-agent-versions).
+[Self-hosted agent versions](#6-runner-drift-runners--self-hosted-agent-versions).
 
 Since 1.3.0 it watches a third clock, and this one is nearly out. GitHub
 [removes Node 20 from the hosted runner images on 2026-09-23](https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/),
@@ -56,7 +56,16 @@ looks like a pin, and it is `node20`. So is `actions/upload-artifact@v4`.
 `runner-drift actions` resolves every `uses:` to the runtime the action really
 declares, follows composites and reusable workflows into whatever they call, and
 names the step that breaks rather than the line you wrote. See
-[which `uses:` survive](#6-runner-drift-actions--which-uses-survive-the-node-20-removal).
+[which `uses:` survive](#7-runner-drift-actions--which-uses-survive-the-node-20-removal).
+
+Since 1.4.0 it also covers the case where the label does not change but the image
+does. GitHub is moving `ubuntu-latest` from Ubuntu 24.04 to Ubuntu 26.04, rolling
+out [between 2026-10-19 and 2026-11-19](https://github.com/actions/runner-images/issues/14748).
+For that month `ubuntu-latest` is two different operating systems depending on
+which runner your job lands on, and nothing in your workflow file changes. `plan`
+resolves the floating label to the two concrete images GitHub named and diffs
+them, so you get the kernel and systemd deltas before the rollout reaches you.
+See [when a floating label moves](#5-when-a-floating-label-moves-under-you).
 
 - No account, no hosted service, no paid tier. Two endpoints only:
   `raw.githubusercontent.com` and `api.github.com`.
@@ -153,8 +162,13 @@ not move, so it is not in the table.
 runner-drift plan --from ubuntu-22.04 --to ubuntu-24.04
 runner-drift plan --from macos-14 --to macos-15 --tools python,node,dotnet
 runner-drift plan --from ubuntu-22.04 --to ubuntu-26.04 --json
+runner-drift plan --from ubuntu-latest          # resolved from the MIGRATIONS table
 ```
 
+`--to` is required except for a floating label with an announced migration, where
+GitHub has already named both ends. See
+[when a floating label moves](#5-when-a-floating-label-moves-under-you).
+
 ### 4. Fail before the brownout
 
 Deprecated images get scheduled brownouts before removal: `macos-14` jobs fail
@@ -191,11 +205,93 @@ When only a brownout falls inside the threshold the annotation is a `::warning`
 dates your builds break. The step summary gets a table (Label, Where, Next
 brownout, Fully unsupported, Migrate to, Source), `--json` gets a `retirement`
 block, and a label already past its date always fails, whatever the threshold.
-`ubuntu-latest` and friends float past retirements, so they are never flagged;
-neither is `self-hosted`. `runs-on: ${{ matrix.os }}` is resolved from the
+`ubuntu-latest` and friends float past retirements, so this lane never flags
+them; they get their own lane, [below](#5-when-a-floating-label-moves-under-you).
+`self-hosted` is never flagged at all. `runs-on: ${{ matrix.os }}` is resolved from the
 matrix values in the same file.
 
-### 5. `runner-drift runners` — self-hosted agent versions
+### 5. When a floating label moves under you
+
+`runs-on: ubuntu-latest` is not a pin, and once a year that matters. GitHub
+announced on 2026-09-17 that the label
+[migrates from Ubuntu 24.04 to Ubuntu 26.04 between 2026-10-19 and 2026-11-19](https://github.com/actions/runner-images/issues/14748).
+During the rollout the label means whichever image your job happens to land on,
+so a build can pass and fail on the same commit with nothing to diff.
+
+`src/labels.mjs` carries the announced moves in a `MIGRATIONS` table, keyed by
+floating label, holding the two concrete labels, the window and the source issue.
+That is enough for `plan` to stop refusing the floating label and diff the two
+real images instead:
+
+```
+$ npx runner-drift plan --from ubuntu-latest
+ubuntu-latest moves from ubuntu-24.04 to ubuntu-26.04. The rollout starts 2026-10-19 (18 days) and finishes 2026-11-19 (49 days).
+announced 2026-09-17; source actions/runner-images#14748 https://github.com/actions/runner-images/issues/14748
+ubuntu-24.04 -> ubuntu-26.04 (images 20260907.300.1 -> 20260907.131.1)
+ubuntu-24.04 has no announced deprecation deadline in runner-drift's table.
+
+OS 24.04.5 LTS -> 26.04.1 LTS  MAJOR
+Kernel 6.17.0-1022-azure -> 7.0.0-1012-azure  MAJOR
+Systemd 255.4-1ubuntu8.17 -> 259.5-0ubuntu3.4  MAJOR
+
+CMake 3.31.6 -> 4.4.3  MAJOR
+Node.js 22.23.2 -> 24.20.0  MAJOR
+Python 3.12.3 -> 3.14.4  MINOR
+
+3 of 3 detected tool(s) change
+```
+
+(Real output against the live manifests, run with `--as-of 2026-10-01` for the
+countdown and the fixture workflow in `test/fixtures/workflows-migration`.)
+
+In CI, `guard --fail-on-migration <days>` scans the `runs-on:` lines for floating
+labels with an announced move and fails while the window is still ahead of you:
+
+```yaml
+  runner-migration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: Booyaka101/runner-drift@v1
+        with:
+          fail-on-migration: 30   # or: npx runner-drift guard --fail-on-migration 30
+```
+
+It is opt-in, like `fail-on-retirement`: without the input, `guard` does not fetch
+the two manifests at all. What it reports depends on where today sits in the
+window, and on the `ImageOS` the runner exported:
+
+| Phase | `ImageOS` | Reported as |
+| --- | --- | --- |
+| Before the window | — | `::notice`, the window and the countdown |
+| In the window | the old image | `::warning`, this runner has not moved yet and the diff is still ahead of you |
+| In the window | the new image | `::notice`, the migration has reached this runner |
+| In the window | absent | `::warning`, which of the two this job got cannot be told |
+| After the window | the new image | `::notice`, the move is done |
+| After the window | the old image | `::error`, an anomaly rather than drift |
+
+The last row is the one worth having. A runner still serving Ubuntu 24.04 in
+December, when the label is supposed to mean 26.04 everywhere, is not a version
+bump you should record in the lock file.
+
+One part of this needs no input at all. When `guard` finds real tool drift and the
+jump from the lock's image to the runner's image is exactly an announced move, it
+says so, because that is a table lookup rather than a check you have to opt into:
+
+```
+ubuntu-26.04 image 20260907.300.1 -> 20260907.131.1
+Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04 (2026-10-19 to 2026-11-19); the tool versions below moved with the image.
+  CMake 3.31.6 -> 4.4.3  MAJOR  [20260907.131.1] https://github.com/actions/runner-images/commit/90ebb6f508835349239c3823c663eba7af98f23d
+```
+
+Exit codes and the `--fail-on` thresholds are untouched by any of this. An
+anomaly fails whatever the threshold, the same rule `--fail-on-retirement` uses
+for a label already past its date. `--json` gains a `migration` block, and the
+step summary gains a table (Label, Phase, Move, Window, This runner, Source).
+Adding `windows-latest` or `macos-latest` later is a data change in `MIGRATIONS`,
+nothing else.
+
+### 6. `runner-drift runners` — self-hosted agent versions
 
 Two clocks run on a self-hosted runner. The image one does not apply, since you
 built the machine. The **agent** one does. GitHub requires each new
@@ -353,7 +449,7 @@ listing and reports that runner's own dates in the summary table and `--json`.
 Without a token, or without the permission, it prints the same `::notice` it
 printed in 1.1.0 and exits 0. That is the common case, not an error path.
 
-### 6. `runner-drift actions` — which `uses:` survive the Node 20 removal
+### 7. `runner-drift actions` — which `uses:` survive the Node 20 removal
 
 GitHub switched the hosted runners' default action runtime to Node 24 on
 2026-06-16 and [removes Node 20 from the images on 2026-09-23](https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/).
@@ -451,9 +547,10 @@ summary table, and sets a `will-fail-count` output.
 | `--lock-file <path>` | `init`, `guard` | `runner-lock.json` | Lock file location |
 | `--tools <a,b,c>` | all | detected | Override detection. Aliases (`python`, `npx`, `clang++`, `g++`, `javac`, …) resolve to manifest names; anything else is matched against the manifest case-insensitively, so `--tools Terraform,Kotlin` works |
 | `--label <label>` | `init` | detected | Explicit runner label |
-| `--from` / `--to` | `plan` | — | Runner labels to compare (required) |
+| `--from` / `--to` | `plan` | — | Runner labels to compare. `--to` is required unless `--from` is a floating label with an announced migration |
 | `--fail-on <level>` | `guard` | never fail | `major`, `minor` or `any` |
 | `--fail-on-retirement <days>` | `guard` | off | Fail when a pinned label retires or browns out within N days |
+| `--fail-on-migration <days>` | `guard` | off | Fail when a floating label's announced migration starts within N days, or this runner is on the wrong side of it |
 | `--org <name>` | `runners` | — | Organization to survey. Mutually exclusive with `--repo` |
 | `--repo <owner/repo>` | `runners` | `$GITHUB_REPOSITORY` | Repository to survey |
 | `--fail-on-deprecation <days>` | `runners`, `guard` | report only, window 30 | Set the window **and** fail when a runner version's support ends inside it |
@@ -462,10 +559,12 @@ summary table, and sets a `will-fail-count` output.
 | `--json` | all | off | Machine-readable output |
 | `--no-summary` | `guard`, `runners`, `actions` | on | Skip the `$GITHUB_STEP_SUMMARY` write |
 | `--no-update-lock` | `guard` | on | Report drift but leave the lock file untouched |
+| `--as-of <date>` | `guard`, `plan`, `runners`, `actions` | today | Measure every countdown from this date instead. Nothing else is faked, so it answers "what will this say on the 19th?" |
 
 Exit codes: `0` success (including "drift found" without `--fail-on`, a refused
 permission, and an empty fleet), `1` drift at or above the `--fail-on` threshold,
-a label inside the `--fail-on-retirement` window, a runner version inside the
+a label inside the `--fail-on-retirement` window, a floating label inside the
+`--fail-on-migration` window, a runner version inside the
 `--fail-on-deprecation` window, an `EXPIRED` runner version at any threshold, or
 an action reference that stops working when Node 20 is removed (`actions`, unless
 `--warn-only`), an unresolved reference under `--fail-on-unknown`, `2` usage /
@@ -478,13 +577,14 @@ configuration error.
 | `mode` | `guard` | Which command the action runs: `guard`, `actions` or `runners` |
 | `fail-on` | `''` | `major`, `minor`, `any`; empty means report only |
 | `fail-on-retirement` | `''` | Days ahead to fail on a label retirement or brownout; empty disables |
+| `fail-on-migration` | `''` | Days ahead to fail on an announced floating-label migration; empty disables |
 | `fail-on-deprecation` | `''` | Days ahead to fail on this self-hosted runner's own agent version; empty disables. Needs `github-token` to carry administration read |
 | `warn-only` | `false` | `mode: actions` only. Annotate and summarise every failing reference, but never fail the job |
 | `fail-on-unknown` | `false` | `mode: actions` only. Treat a reference that could not be resolved as a failure |
 | `tools` | `''` | Comma-separated override |
 | `lock-file` | `runner-lock.json` | Lock file path |
 | `workflows` | `.github/workflows` | Scanned when there is no lock yet |
-| `version` | `1.3.0` | npm version of `runner-drift` to run |
+| `version` | `1.4.0` | npm version of `runner-drift` to run |
 | `package` | `''` | Override the npm spec, e.g. a `.tgz` built in the same job. Only useful for testing the action before the version it requests is published |
 | `github-token` | `${{ github.token }}` | Rate limit, plus the runner listing for `fail-on-deprecation` (which the default token cannot read) |
 
@@ -679,12 +779,27 @@ large/xlarge labels have no public manifest, so they get the retirement
 countdown and `--fail-on-retirement`, not the tool diff. Every other label
 diffs fine, it just has no countdown.
 
+Migration data covers the floating labels GitHub has announced a move for:
+`ubuntu-latest` (`ubuntu-24.04` -> `ubuntu-26.04`, 2026-10-19 to 2026-11-19,
+[#14748](https://github.com/actions/runner-images/issues/14748)). That issue covers
+the x64 label only, so `ubuntu-latest-arm` has no entry and is left alone. `MIGRATIONS` in
+`src/labels.mjs` is separate from the retirement `DEADLINES` table, because a
+migration is a dated window between two live images and a retirement is an end
+date for one.
+
 ## Limitations
 
-- **Floating labels are refused, on purpose.** `ubuntu-latest` / `macos-latest`
-  are re-pointed by GitHub without notice, so `plan` will not guess what they
-  mean — pass the concrete label. `guard` does not need to guess: it reads the
-  real label from the runner's `ImageOS` env var at run time.
+- **Floating labels are refused, on purpose, except where GitHub said otherwise.**
+  `ubuntu-latest` / `macos-latest` are re-pointed by GitHub without notice, so
+  `plan` will not guess what they mean — pass the concrete label. The exception is
+  a label in `MIGRATIONS`, where GitHub has published both ends and the dates;
+  there `plan --from ubuntu-latest` diffs the two images it named, and still
+  refuses a floating `--to`. `guard` does not need to guess either way: it reads
+  the real label from the runner's `ImageOS` env var at run time.
+- **Migration windows are a hardcoded table too, and only cover announced moves.**
+  GitHub publishes no feed for these, so `MIGRATIONS` needs a release when a new
+  move is announced. A floating label with no entry behaves exactly as it did
+  before 1.4.0.
 - **Image deadlines are a hardcoded table; runner-version deadlines are not.**
   The `runs-on` label dates in `src/labels.mjs` are transcribed from
   [#14254](https://github.com/actions/runner-images/issues/14254) and
diff --git a/action.yml b/action.yml
index cbe3583..e13f621 100644
--- a/action.yml
+++ b/action.yml
@@ -20,6 +20,10 @@ inputs:
     description: 'Fail if a pinned runs-on label browns out or retires within this many days. Empty disables the check.'
     required: false
     default: ''
+  fail-on-migration:
+    description: 'Report, and fail on, an announced migration of a floating runs-on label (ubuntu-latest) starting within this many days. Empty disables the check.'
+    required: false
+    default: ''
   fail-on-deprecation:
     description: 'Fail if this self-hosted runner version loses support within this many days. Needs a token with administration read; empty disables.'
     required: false
@@ -39,7 +43,7 @@ inputs:
   version:
     description: 'npm version of runner-drift to run.'
     required: false
-    default: '1.3.0'
+    default: '1.4.0'
   package:
     description: 'Override the npm spec, e.g. a local .tgz built in the same job. Mainly for testing this action before the version it requests exists on npm.'
     required: false
@@ -77,6 +81,7 @@ runs:
         RD_FAIL_ON_UNKNOWN: ${{ inputs.fail-on-unknown }}
         RD_FAIL_ON: ${{ inputs.fail-on }}
         RD_FAIL_ON_RETIREMENT: ${{ inputs.fail-on-retirement }}
+        RD_FAIL_ON_MIGRATION: ${{ inputs.fail-on-migration }}
         RD_FAIL_ON_DEPRECATION: ${{ inputs.fail-on-deprecation }}
         RD_TOOLS: ${{ inputs.tools }}
         RD_LOCK_FILE: ${{ inputs.lock-file }}
@@ -98,6 +103,7 @@ runs:
             args=(guard --lock-file "$LOCK_ABS" --workflows "$WF_ABS")
             if [ -n "$RD_FAIL_ON" ]; then args+=(--fail-on "$RD_FAIL_ON"); fi
             if [ -n "$RD_FAIL_ON_RETIREMENT" ]; then args+=(--fail-on-retirement "$RD_FAIL_ON_RETIREMENT"); fi
+            if [ -n "$RD_FAIL_ON_MIGRATION" ]; then args+=(--fail-on-migration "$RD_FAIL_ON_MIGRATION"); fi
             if [ -n "$RD_FAIL_ON_DEPRECATION" ]; then args+=(--fail-on-deprecation "$RD_FAIL_ON_DEPRECATION"); fi
             if [ -n "$RD_TOOLS" ]; then args+=(--tools "$RD_TOOLS"); fi
             printf 'lock-file=%s\n' "$RD_LOCK_FILE" >> "$GITHUB_OUTPUT"
diff --git a/package.json b/package.json
index f2267c2..1cfdd84 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "runner-drift",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Detect and attribute GitHub Actions runner-image tool drift: lock the tool versions your CI actually uses, diff them on every image bump, and plan a runner label migration before the deprecation deadline.",
   "type": "module",
   "bin": {
@@ -32,6 +32,8 @@
     "runner-images",
     "deprecation",
     "ubuntu-22.04",
+    "ubuntu-latest",
+    "ubuntu-26.04",
     "drift",
     "migration",
     "actions"
diff --git a/src/cli.mjs b/src/cli.mjs
index f641846..7212c7c 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -15,12 +15,18 @@ import {
   deadlineFor,
   isFloating,
   knownLabels,
+  migratingLabels,
+  migrationFails,
+  migrationBetween,
+  migrationFor,
+  migrationStatus,
   normaliseLabel,
 } from './labels.mjs';
-import { loadManifest, lookupTool } from './manifest.mjs';
+import { loadManifest, resolveManifestVersions } from './manifest.mjs';
+import { imageDiffs, surveyMigration } from './migration.mjs';
 import { attribute, commitWindow, attributeChanges, listManifestCommits, manifestAtSha } from './history.mjs';
 import { detect, SELF_HOSTED } from './detect.mjs';
-import { canonicalTool, manifestCandidates, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
+import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
 import { readLock, writeLock, DEFAULT_LOCK_FILE, toolsEntry, toVersionMap } from './lock.mjs';
@@ -32,6 +38,10 @@ import {
   retirementFindings,
   retirementAnnotations,
   retirementSummaryMarkdown,
+  migrationAnnotations,
+  migrationMessage,
+  migrationReport,
+  migrationSummaryMarkdown,
   runnersReport,
   runnersAnnotations,
   runnersSummaryMarkdown,
@@ -50,6 +60,8 @@ import {
   surveyRunners,
 } from './runners.mjs';
 
+export { resolveManifestVersions };
+
 export const EXIT_OK = 0;
 export const EXIT_DRIFT = 1;
 export const EXIT_USAGE = 2;
@@ -61,7 +73,7 @@ async function version() {
     const pkg = JSON.parse(await readFile(path.join(HERE, '..', 'package.json'), 'utf8'));
     return pkg.version;
   } catch {
-    return '1.3.0';
+    return '1.4.0';
   }
 }
 
@@ -71,6 +83,8 @@ Usage:
   runner-drift init  [options]                 Record a baseline runner-lock.json
   runner-drift guard [options]                 (in-workflow) diff live runner vs the lock
   runner-drift plan  --from <label> --to <label>   Preview a runner label migration
+  runner-drift plan  --from <floating label>   Preview the move GitHub has announced
+                                               for that label (e.g. ubuntu-latest)
   runner-drift runners [--org <name> | --repo <owner/repo>]
                                                Self-hosted runner agent versions vs
                                                GitHub's end-of-support dates
@@ -86,12 +100,16 @@ Options:
   --to <label>          target runner label           (plan)
   --fail-on <level>     major | minor | any           (guard, default: never fail)
   --fail-on-retirement <days>   fail if a pinned label retires within N days (guard)
+  --fail-on-migration <days>    report, and fail on, an announced floating-label
+                                migration starting within N days (guard)
   --org <name>          organization to survey             (runners)
   --repo <owner/repo>   repository to survey               (runners, default: $GITHUB_REPOSITORY)
   --fail-on-deprecation <days>  fail if a runner version's support ends within N days
                                 (runners, guard; default window ${DEFAULT_DEPRECATION_WINDOW_DAYS})
   --warn-only           report but always exit 0             (actions)
   --fail-on-unknown     fail when a uses: cannot be resolved (actions)
+  --as-of <date>        evaluate every countdown as if it were this date, e.g.
+                        --as-of 2026-10-19 (guard, plan, runners, actions)
   --json                machine-readable output
   --no-summary          do not write $GITHUB_STEP_SUMMARY (guard, runners, actions)
   --no-update-lock      do not rewrite the lock file  (guard)
@@ -113,7 +131,9 @@ export const OPTIONS = {
   to: { type: 'string' },
   'fail-on': { type: 'string' },
   'fail-on-retirement': { type: 'string' },
+  'fail-on-migration': { type: 'string' },
   'fail-on-deprecation': { type: 'string' },
+  'as-of': { type: 'string' },
   org: { type: 'string' },
   repo: { type: 'string' },
   'warn-only': { type: 'boolean', default: false },
@@ -153,18 +173,6 @@ function parseToolList(csv) {
   return [...new Set(list)];
 }
 
-/** Resolve canonical tool names against a parsed manifest. */
-export function resolveManifestVersions(manifest, tools) {
-  const map = {};
-  const missing = [];
-  for (const t of tools) {
-    const hit = lookupTool(manifest, manifestCandidates(t));
-    if (hit) map[t] = hit.versions;
-    else missing.push(t);
-  }
-  return { map, missing };
-}
-
 /**
  * Reduce a raw `runs-on` label set to the hosted-image labels worth resolving.
  * Self-hosted runners carry arbitrary extra tags (`linux`, `gpu`, `x64`), so
@@ -186,6 +194,23 @@ function out(stream, line) {
   stream.write(`${line}\n`);
 }
 
+/**
+ * `--as-of`: the date every countdown is measured from. Nothing here is
+ * inferred from it, so it answers "what will this say on the 19th?" without
+ * pretending the run happened then.
+ * @returns {{now?:Date}|null} null once the error is reported
+ */
+function asOf(opts, io) {
+  if (opts['as-of'] === undefined) return {};
+  const raw = String(opts['as-of']);
+  const at = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(raw) ? `${raw}T00:00:00Z` : raw);
+  if (!Number.isFinite(at)) {
+    out(io.stderr, `--as-of needs a date such as 2026-10-19 (got "${raw}")`);
+    return null;
+  }
+  return { now: new Date(at) };
+}
+
 /** A `--fail-on-*` threshold in whole days, or null once the error is reported. */
 function wholeDays(value, flag, io) {
   const raw = String(value);
@@ -207,6 +232,19 @@ function summarise(io, items, keyOf, lineOf) {
   }
 }
 
+/**
+ * The workflow scan the two lint lanes start from, or null when there is no
+ * workflow directory — which is a notice on both streams, not an error.
+ */
+async function scanForLane(opts, io, nothingToCheck) {
+  const scanned = await detect(opts.workflows ?? path.join('.github', 'workflows'));
+  if (!scanned.missing) return scanned;
+  const msg = `No workflow directory at ${scanned.dir} — ${nothingToCheck}.`;
+  out(io.stdout, notice(msg));
+  out(io.stdout, msg);
+  return null;
+}
+
 /**
  * `--fail-on-retirement`: every pinned label that retires or browns out inside
  * the window. Reads the workflow files alone, so it works in a lint job with no
@@ -215,13 +253,9 @@ function summarise(io, items, keyOf, lineOf) {
 async function checkRetirement(opts, io, now) {
   const days = wholeDays(opts['fail-on-retirement'], '--fail-on-retirement', io);
   if (days === null) return null;
-  const scanned = await detect(opts.workflows ?? path.join('.github', 'workflows'));
-  if (scanned.missing) {
-    const msg = `No workflow directory at ${scanned.dir} — no pinned labels to check for retirement.`;
-    out(io.stdout, notice(msg));
-    out(io.stdout, msg);
-    return { days, findings: [] };
-  }
+  const scanned = await scanForLane(opts, io, 'no pinned labels to check for retirement');
+  if (!scanned) return { days, findings: [] };
+
   const findings = retirementFindings(scanned.labelSites, { now, days });
   for (const line of retirementAnnotations(findings)) out(io.stdout, line);
   if (findings.length && opts.summary) {
@@ -243,6 +277,51 @@ function reportRetirement(io, { days, findings }) {
   );
 }
 
+/**
+ * `--fail-on-migration`: every floating label in the workflows that GitHub has
+ * announced a move for, classified against its window and diffed across the two
+ * images it names. Opt-in like the retirement gate, and like it, useful in a
+ * plain lint job with no runner and no lock file.
+ */
+async function checkMigration(opts, io, now, imageOS, deps) {
+  const days = wholeDays(opts['fail-on-migration'], '--fail-on-migration', io);
+  if (days === null) return null;
+  const scanned = await scanForLane(opts, io, 'no floating labels to check for migration');
+  if (!scanned) return { days, surveys: [] };
+
+  const byLabel = new Map();
+  for (const site of scanned.floatingSites) {
+    if (!migrationFor(site.label)) continue;
+    if (!byLabel.has(site.label)) byLabel.set(site.label, []);
+    byLabel.get(site.label).push(site);
+  }
+  const tools = parseToolList(opts.tools) ?? scanned.tools;
+  const load = deps.loadManifest ?? loadManifest;
+  const surveys = await Promise.all(
+    [...byLabel].map(([label, sites]) =>
+      surveyMigration({ label, now, imageOS, tools, sites, load }),
+    ),
+  );
+
+  for (const line of migrationAnnotations(surveys)) out(io.stdout, line);
+  if (surveys.length && opts.summary) {
+    await writeStepSummary(migrationSummaryMarkdown(surveys));
+  }
+  return { days, surveys };
+}
+
+/** One stderr line per floating label whose migration fails the gate. */
+function reportMigration(io, { days, surveys }) {
+  summarise(
+    io,
+    surveys.filter((s) => migrationFails(s, days)),
+    (s) => s.label,
+    (s) =>
+      `runner-drift: ${migrationMessage(s)}` +
+      (s.anomaly ? '' : ` --fail-on-migration ${days} is set.`),
+  );
+}
+
 /** The same, one line per runner version whose support window has closed. */
 function reportDeprecation(io, survey) {
   summarise(
@@ -326,6 +405,12 @@ export async function runInit(opts, io = process) {
         out(io.stderr, 'Either pass the concrete label:  runner-drift init --label ubuntu-24.04');
         out(io.stderr, 'or just add the guard step to your workflow — `runner-drift guard` reads the real');
         out(io.stderr, 'label from the runner\'s ImageOS env var and writes the baseline itself.');
+        const migrating = floating.filter((l) => migrationFor(l));
+        if (migrating.length) {
+          out(io.stderr, '');
+          out(io.stderr, `Note: ${migrating.join(', ')} has an announced migration. Preview what changes:`);
+          out(io.stderr, `  runner-drift plan --from ${migrating[0]}`);
+        }
         return EXIT_USAGE;
       }
       out(io.stderr, `No runner label found in ${detected.dir}. Pass --label <label>.`);
@@ -449,6 +534,21 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   const imageVersion = env.ImageVersion ?? env.IMAGE_VERSION ?? null;
   const imageOS = env.ImageOS ?? env.IMAGE_OS ?? null;
 
+  // Migration needs only the workflow files too, but it does want ImageOS: on a
+  // hosted runner mid-window that is the difference between "the same label is
+  // two images right now" and "this job ran on the new one".
+  let migration = null;
+  if (opts['fail-on-migration'] !== undefined) {
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, deps);
+    if (!migration) return EXIT_USAGE;
+    if (!opts.json && migration.surveys.length) {
+      out(io.stdout, migrationReport(migration.surveys));
+    }
+  }
+  const migrating = migration?.surveys.some((s) => migrationFails(s, migration.days))
+    ? migration
+    : null;
+
   // A GitHub-hosted runner has no agent version of its own to check, so the flag
   // does nothing here. Say so: the action passes it to every job, and a flag that
   // silently no-ops reads as a broken flag.
@@ -472,14 +572,17 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     // version with a date on it. Without a token this is a no-op and the skip
     // above is the whole output, exactly as in 1.1.0.
     const own = await checkOwnRunner(opts, io, env, deps, window);
-    if (opts.json && own) {
-      const payload = { runners: own };
+    if (opts.json && (own || migration)) {
+      const payload = {};
+      if (own) payload.runners = own;
       if (retirement) payload.retirement = retirement;
+      if (migration) payload.migration = migration;
       out(io.stdout, JSON.stringify(payload, null, 2));
     }
     if (retiring) reportRetirement(io, retiring);
+    if (migrating) reportMigration(io, migrating);
     if (own?.failing) reportDeprecation(io, own);
-    return retiring || own?.failing ? EXIT_DRIFT : EXIT_OK;
+    return retiring || migrating || own?.failing ? EXIT_DRIFT : EXIT_OK;
   }
 
   const lock = await readLock(lockFile);
@@ -493,11 +596,9 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     const msg = `Unknown runner label (ImageOS="${imageOS ?? '(unset)'}") — skipping. Known: ${knownLabels().join(', ')}`;
     out(io.stdout, `::warning title=runner-drift::${msg}`);
     out(io.stdout, msg);
-    if (retiring) {
-      reportRetirement(io, retiring);
-      return EXIT_DRIFT;
-    }
-    return EXIT_OK;
+    if (retiring) reportRetirement(io, retiring);
+    if (migrating) reportMigration(io, migrating);
+    return retiring || migrating ? EXIT_DRIFT : EXIT_OK;
   }
 
   // Which tools to watch.
@@ -583,7 +684,12 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       out(
         io.stdout,
         JSON.stringify(
-          retirement ? { baseline: true, lock: written, retirement } : { baseline: true, lock: written },
+          {
+            baseline: true,
+            lock: written,
+            ...(retirement ? { retirement } : {}),
+            ...(migration ? { migration } : {}),
+          },
           null,
           2,
         ),
@@ -595,11 +701,9 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       for (const [t, v] of manifestOnly) out(io.stdout, `  ${t}: ${v.versions.join(', ')} (from manifest)`);
       out(io.stdout, `Wrote ${lockFile}. Commit it so the next image bump can be diffed.`);
     }
-    if (retiring) {
-      reportRetirement(io, retiring);
-      return EXIT_DRIFT;
-    }
-    return EXIT_OK;
+    if (retiring) reportRetirement(io, retiring);
+    if (migrating) reportMigration(io, migrating);
+    return retiring || migrating ? EXIT_DRIFT : EXIT_OK;
   }
 
   // Diff against the lock.
@@ -640,6 +744,16 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     }
   }
 
+  // Not unexplained drift: the lock was taken on the image the window moves
+  // away from, and this runner served the one it moves to. The table lookup is
+  // the fallback for a run without --fail-on-migration, where the lane never
+  // built a survey. The exit code is still --fail-on's to decide; this only
+  // names the cause.
+  const explained =
+    migration?.surveys.find(
+      (s) => s.done && s.observed === s.to && lock.label === s.from && label === s.to,
+    ) ?? migrationBetween(lock.label, label);
+
   const summary = stepSummaryMarkdown({
     label,
     fromImage: lock.imageVersion ?? '(unknown)',
@@ -663,11 +777,19 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   if (opts.json) {
     const payload = { label, from: lock.imageVersion, to: imageVersion, approximate, diffs, attribution: attributionMap };
     if (retirement) payload.retirement = retirement;
+    if (migration) payload.migration = { ...migration, explains: explained?.label ?? null };
     out(io.stdout, JSON.stringify(payload, null, 2));
   } else if (!changed.length) {
     out(io.stdout, `No drift — ${label} image ${lock.imageVersion} -> ${imageVersion}, ${diffs.length} tool(s) unchanged.`);
   } else {
     out(io.stdout, `${label} image ${lock.imageVersion} -> ${imageVersion}${approximate ? ' (attribution approximate)' : ''}`);
+    if (explained) {
+      out(
+        io.stdout,
+        `Explained by the scheduled ${explained.label} migration ${explained.from} -> ${explained.to}` +
+          ` (${explained.starts} to ${explained.ends}); the tool versions below moved with the image.`,
+      );
+    }
     for (const d of changed) {
       const a = attributionMap[d.tool];
       out(
@@ -683,7 +805,8 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     out(io.stderr, `runner-drift: ${maxSeverity(diffs).toUpperCase()} drift detected and --fail-on ${failOn} is set.`);
   }
   if (retiring) reportRetirement(io, retiring);
-  return driftFail || retiring ? EXIT_DRIFT : EXIT_OK;
+  if (migrating) reportMigration(io, migrating);
+  return driftFail || retiring || migrating ? EXIT_DRIFT : EXIT_OK;
 }
 
 /* -------------------------------------------------------------------- plan */
@@ -692,17 +815,31 @@ export async function runPlan(opts, io = process, deps = {}) {
   const load = deps.loadManifest ?? loadManifest;
   const now = deps.now ?? new Date();
 
-  const from = normaliseLabel(opts.from ?? '');
-  const to = normaliseLabel(opts.to ?? '');
+  let from = normaliseLabel(opts.from ?? '');
+  let to = normaliseLabel(opts.to ?? '');
+
+  // A floating --from on its own is the announced migration: resolve it to the
+  // two concrete labels the window names. With an explicit --to the user has
+  // already said what to compare, so the refusal below still applies.
+  const migration = from && !to ? migrationStatus(from, { now }) : null;
+  if (migration) {
+    from = migration.from;
+    to = migration.to;
+  }
+
   if (!from || !to) {
     out(io.stderr, 'plan needs both --from <label> and --to <label>.');
     out(io.stderr, 'e.g. runner-drift plan --from ubuntu-22.04 --to ubuntu-24.04');
+    out(io.stderr, `Floating labels with an announced migration need only --from: ${migratingLabels().join(', ')}`);
     return EXIT_USAGE;
   }
   for (const [flag, label] of [['--from', from], ['--to', to]]) {
     if (isFloating(label)) {
       out(io.stderr, `${flag} ${label} is a floating label — GitHub re-points it without notice.`);
       out(io.stderr, 'Pass the concrete label you want to compare, e.g. ubuntu-24.04 or ubuntu-26.04.');
+      if (migrationFor(label)) {
+        out(io.stderr, `Or drop --to: runner-drift plan --from ${label} diffs the two images GitHub announced.`);
+      }
       return EXIT_USAGE;
     }
   }
@@ -750,7 +887,9 @@ export async function runPlan(opts, io = process, deps = {}) {
           fromImage: a.imageVersion,
           toImage: b.imageVersion,
           deadline: deadlineFor(from),
+          migration,
           tools,
+          image: imageDiffs(a, b).filter((d) => d.changed),
           diffs: diffs.filter((d) => d.changed),
           unchanged: diffs.filter((d) => !d.changed).map((d) => d.tool),
           notOnManifest: missingBoth,
@@ -770,6 +909,8 @@ export async function runPlan(opts, io = process, deps = {}) {
       fromImage: a.imageVersion,
       toImage: b.imageVersion,
       diffs,
+      image: imageDiffs(a, b),
+      migration,
       detected: { missingFromManifest: missingBoth },
       now,
     }),
@@ -886,18 +1027,21 @@ export async function main(argv = process.argv.slice(2), io = process) {
     return opts.help ? EXIT_OK : EXIT_USAGE;
   }
 
+  const deps = asOf(opts, io);
+  if (!deps) return EXIT_USAGE;
+
   try {
     switch (command) {
       case 'init':
         return await runInit(opts, io);
       case 'guard':
-        return await runGuard(opts, io);
+        return await runGuard(opts, io, process.env, deps);
       case 'plan':
-        return await runPlan(opts, io);
+        return await runPlan(opts, io, deps);
       case 'runners':
-        return await runRunners(opts, io);
+        return await runRunners(opts, io, process.env, deps);
       case 'actions':
-        return await runActions(opts, io, { root: parsed.positionals[0] });
+        return await runActions(opts, io, { ...deps, root: parsed.positionals[0] });
       case 'help':
         out(io.stdout, USAGE);
         return EXIT_OK;
diff --git a/src/detect.mjs b/src/detect.mjs
index cd9a23d..2c142fc 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -225,16 +225,16 @@ export function extractLabels(text) {
 /**
  * Where each `runs-on` label sits: `{label, file, line, col}` per occurrence,
  * 1-indexed, `col` on the label text so a `file=,line=,col=` annotation lands
- * on it. Self-hosted and floating labels are skipped, having no fixed date to
- * retire on.
+ * on it. `keep` decides which labels are worth a site, because the two lanes
+ * that want one want disjoint halves of the same walk.
  */
-export function extractLabelSites(text, file = null) {
+function labelSitesWhere(text, file, keep) {
   const lines = String(text ?? '').split(/\r?\n/);
   const { found, expression } = scanRunsOn(lines);
   const seen = new Set();
   const sites = [];
   for (const { label, line, col } of expression ? [...found, ...matrixLabels(lines)] : found) {
-    if (label === SELF_HOSTED || isFloating(label)) continue;
+    if (!keep(label)) continue;
     const key = `${label}@${line}:${col}`;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -243,6 +243,16 @@ export function extractLabelSites(text, file = null) {
   return sites;
 }
 
+/** Pinned image labels: what the retirement lane dates. */
+export function extractLabelSites(text, file = null) {
+  return labelSitesWhere(text, file, (l) => l !== SELF_HOSTED && !isFloating(l));
+}
+
+/** Floating labels: what the migration lane dates, and nothing else can. */
+export function extractFloatingSites(text, file = null) {
+  return labelSitesWhere(text, file, isFloating);
+}
+
 /**
  * One entry per `runs-on:`, with its label SET intact: `{labels, file, line, col}`.
  *
@@ -354,6 +364,7 @@ export function extractSetupActions(text) {
 export function analyseWorkflow(text, file = null) {
   const labels = extractLabels(text);
   const labelSites = extractLabelSites(text, file);
+  const floatingSites = extractFloatingSites(text, file);
   const runsOnTargets = extractRunsOnTargets(text, file);
   const uses = extractUses(text, file);
   const commands = new Set();
@@ -362,7 +373,16 @@ export function analyseWorkflow(text, file = null) {
   }
   const tools = new Set([...commands].map((c) => canonicalTool(c)));
   for (const t of setupTools(uses)) tools.add(t);
-  return { file, labels, labelSites, runsOnTargets, uses, commands: [...commands].sort(), tools: [...tools].sort() };
+  return {
+    file,
+    labels,
+    labelSites,
+    floatingSites,
+    runsOnTargets,
+    uses,
+    commands: [...commands].sort(),
+    tools: [...tools].sort(),
+  };
 }
 
 async function listWorkflowFiles(dir) {
@@ -382,7 +402,8 @@ async function listWorkflowFiles(dir) {
 /**
  * Scan a directory of workflows (or a single workflow file).
  * @returns {{dir:string, files:string[], labels:string[], labelSites:object[],
- *            tools:string[], perFile:object[], missing:boolean}}
+ *            floatingSites:object[], tools:string[], perFile:object[],
+ *            missing:boolean}}
  */
 export async function detect(workflowsPath) {
   const target = workflowsPath || path.join('.github', 'workflows');
@@ -403,6 +424,7 @@ export async function detect(workflowsPath) {
         files: [],
         labels: [],
         labelSites: [],
+        floatingSites: [],
         runsOnTargets: [],
         uses: [],
         tools: [],
@@ -415,6 +437,7 @@ export async function detect(workflowsPath) {
   const perFile = [];
   const labels = new Set();
   const labelSites = [];
+  const floatingSites = [];
   const runsOnTargets = [];
   const uses = [];
   const tools = new Set();
@@ -424,6 +447,7 @@ export async function detect(workflowsPath) {
     perFile.push(r);
     for (const l of r.labels) labels.add(l);
     labelSites.push(...r.labelSites);
+    floatingSites.push(...r.floatingSites);
     runsOnTargets.push(...r.runsOnTargets);
     uses.push(...r.uses);
     for (const t of r.tools) tools.add(t);
@@ -434,6 +458,7 @@ export async function detect(workflowsPath) {
     files,
     labels: [...labels].sort(),
     labelSites,
+    floatingSites,
     runsOnTargets,
     uses,
     tools: [...tools].sort(),
diff --git a/src/http.mjs b/src/http.mjs
index 1814602..208b633 100644
--- a/src/http.mjs
+++ b/src/http.mjs
@@ -43,7 +43,7 @@ function authHeaders() {
   const token =
     process.env.GITHUB_TOKEN || process.env.GH_TOKEN || process.env.INPUT_GITHUB_TOKEN || '';
   const headers = {
-    'user-agent': 'runner-drift/1.3.0 (+https://github.com/Booyaka101/runner-drift)',
+    'user-agent': 'runner-drift/1.4.0 (+https://github.com/Booyaka101/runner-drift)',
     accept: 'application/vnd.github+json',
   };
   if (token) headers.authorization = `Bearer ${token}`;
diff --git a/src/index.mjs b/src/index.mjs
index ca87ec7..5066629 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -2,6 +2,7 @@
 
 export { main, runInit, runGuard, runPlan, runRunners, runActions, resolveManifestVersions, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from './cli.mjs';
 export { parseManifest, loadManifest, manifestUrl, lookupTool } from './manifest.mjs';
+export { IMAGE_FIELDS, imageDiffs, surveyMigration } from './migration.mjs';
 export {
   listManifestCommits,
   findCommitForImageVersion,
@@ -17,6 +18,7 @@ export {
   analyseWorkflow,
   extractLabels,
   extractLabelSites,
+  extractFloatingSites,
   extractRunsOnTargets,
   extractRunScripts,
   extractUses,
@@ -43,6 +45,12 @@ export {
   retirementFindings,
   retirementAnnotations,
   retirementSummaryMarkdown,
+  migrationMessage,
+  migrationHeader,
+  migrationLines,
+  migrationReport,
+  migrationAnnotations,
+  migrationSummaryMarkdown,
   runnerGroupDetail,
   runnersReport,
   runnersAnnotations,
@@ -98,12 +106,20 @@ export {
 export {
   LABEL_PATHS,
   DEADLINES,
+  MIGRATIONS,
+  MIGRATION_PHASE,
+  MIGRATION_STATE,
   IMAGE_OS_TO_LABEL,
   API_BASE,
   RAW_HOST,
   knownLabels,
   deadlineFor,
   isFloating,
+  migratingLabels,
+  migrationBetween,
+  migrationFails,
+  migrationFor,
+  migrationStatus,
   nextBrownout,
   retirementStatus,
 } from './labels.mjs';
diff --git a/src/labels.mjs b/src/labels.mjs
index 42caa46..5030006 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -33,8 +33,9 @@ export const LABEL_PATHS = {
 
 /**
  * Floating labels cannot be resolved offline — GitHub moves them without
- * changing the label. `plan` refuses them; `guard` resolves them from the
- * ImageOS env var that the real runner exports.
+ * changing the label. `guard` resolves them from the ImageOS env var that the
+ * real runner exports; `plan` refuses one as a diff endpoint, except where
+ * MIGRATIONS below names the two concrete labels a move goes between.
  */
 export const FLOATING_LABELS = new Set(['ubuntu-latest', 'windows-latest', 'macos-latest']);
 
@@ -178,3 +179,169 @@ export function retirementStatus(label, now = new Date()) {
     sourceRef: dl.sourceRef,
   };
 }
+
+/* ------------------------------------------------- floating-label migrations */
+
+/**
+ * Scheduled migrations of a floating label, transcribed from the changelog.
+ *
+ * Deliberately not part of DEADLINES. A deadline retires a concrete label and
+ * offers destinations you choose between (`migrateTo`); a migration is GitHub
+ * re-pointing a floating label from one image to another on dates you do not
+ * get to pick, and the label itself never changes. Nothing in DEADLINES can say
+ * that, which is why `starts`/`ends` are new fields rather than an overload.
+ *
+ * Verified 2026-09-20 against the changelog and actions/runner-images#14748.
+ * Adding windows-latest or macos-latest later is a pure data addition.
+ */
+export const MIGRATIONS = {
+  'ubuntu-latest': {
+    from: 'ubuntu-24.04',
+    to: 'ubuntu-26.04',
+    starts: '2026-10-19',
+    ends: '2026-11-19',
+    announced: '2026-09-17',
+    source: 'https://github.com/actions/runner-images/issues/14748',
+    sourceRef: 'actions/runner-images#14748',
+    changelog:
+      'https://github.blog/changelog/2026-09-17-ubuntu-26-generally-available-and-latest-migration/',
+  },
+};
+
+/** Where today sits relative to the rollout window. */
+export const MIGRATION_PHASE = {
+  PENDING: 'pending',
+  IN_WINDOW: 'in-window',
+  SETTLED: 'settled',
+};
+
+/** The window crossed with the image this runner actually served. */
+export const MIGRATION_STATE = {
+  PENDING: 'pending',
+  MOVED_EARLY: 'moved-early',
+  NOT_YET_MIGRATED: 'not-yet-migrated',
+  AMBIGUOUS: 'ambiguous',
+  MIGRATED: 'migrated',
+  SETTLED: 'settled',
+  STALE: 'stale',
+  UNEXPECTED: 'unexpected',
+};
+
+/**
+ * phase x observed image -> state. A table rather than a chain of conditionals:
+ * every cell is a different sentence in the report, and a missing one would be
+ * a silent fallthrough.
+ */
+const STATE_BY_PHASE = {
+  [MIGRATION_PHASE.PENDING]: {
+    none: MIGRATION_STATE.PENDING,
+    from: MIGRATION_STATE.PENDING,
+    to: MIGRATION_STATE.MOVED_EARLY,
+  },
+  [MIGRATION_PHASE.IN_WINDOW]: {
+    none: MIGRATION_STATE.AMBIGUOUS,
+    from: MIGRATION_STATE.NOT_YET_MIGRATED,
+    to: MIGRATION_STATE.MIGRATED,
+  },
+  [MIGRATION_PHASE.SETTLED]: {
+    none: MIGRATION_STATE.SETTLED,
+    from: MIGRATION_STATE.STALE,
+    to: MIGRATION_STATE.MIGRATED,
+  },
+};
+
+/** The announced migration of a floating label, or null when there is none. */
+export function migrationFor(label) {
+  return MIGRATIONS[label] ?? null;
+}
+
+/**
+ * The announced migration that moves between these two concrete labels, or null.
+ *
+ * Pure table lookup, no dates and no network, so `guard` can name the cause of a
+ * lock-to-runner jump even when the migration lane itself was not asked for.
+ */
+export function migrationBetween(from, to) {
+  for (const [label, m] of Object.entries(MIGRATIONS)) {
+    if (m.from === from && m.to === to) return { label, ...m };
+  }
+  return null;
+}
+
+/** Floating labels runner-drift has a migration window for. */
+export function migratingLabels() {
+  return Object.keys(MIGRATIONS);
+}
+
+/**
+ * Classify a floating label against its migration window.
+ *
+ * `imageOS` is the env var a real runner exports, so on a hosted runner the
+ * calendar answer is checked against the image that actually turned up. Without
+ * it the calendar alone still decides pending and settled; only inside the
+ * window is the answer genuinely unknowable, since that is the month where the
+ * same label is two operating systems.
+ *
+ * @returns {object|null} null when the label has no announced migration
+ */
+export function migrationStatus(label, { now = new Date(), imageOS = null } = {}) {
+  const m = MIGRATIONS[label];
+  if (!m) return null;
+
+  // The changelog states calendar dates, so both ends are inside the window.
+  // Phase therefore turns on the same whole-day countdown the report prints:
+  // when the output says "starts 2026-10-19 (0 days)", it is in the window.
+  const daysToStart = daysUntilDate(m.starts, now);
+  const daysToEnd = daysUntilDate(m.ends, now);
+  const phase =
+    daysToStart > 0
+      ? MIGRATION_PHASE.PENDING
+      : daysToEnd >= 0
+        ? MIGRATION_PHASE.IN_WINDOW
+        : MIGRATION_PHASE.SETTLED;
+
+  // An ImageOS this build does not recognise reads as no observation at all:
+  // guard already reports an unknown ImageOS on its own, and guessing here
+  // would turn a new image name into a fake anomaly.
+  const observed = imageOS ? (IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null) : null;
+  const seen = observed === null ? 'none' : observed === m.to ? 'to' : observed === m.from ? 'from' : 'other';
+  const state = seen === 'other' ? MIGRATION_STATE.UNEXPECTED : STATE_BY_PHASE[phase][seen];
+
+  return {
+    label,
+    from: m.from,
+    to: m.to,
+    starts: m.starts,
+    ends: m.ends,
+    announced: m.announced,
+    phase,
+    state,
+    daysToStart,
+    daysToEnd,
+    imageOS: imageOS ?? null,
+    observed,
+    anomaly: state === MIGRATION_STATE.STALE || state === MIGRATION_STATE.UNEXPECTED,
+    done:
+      state === MIGRATION_STATE.MIGRATED ||
+      state === MIGRATION_STATE.MOVED_EARLY ||
+      state === MIGRATION_STATE.SETTLED,
+    source: m.source,
+    sourceRef: m.sourceRef,
+    changelog: m.changelog,
+  };
+}
+
+/**
+ * Should `--fail-on-migration <days>` fail on this status?
+ *
+ * An anomaly always fires, whatever the threshold, the same rule the retirement
+ * lane uses for an already-retired label: a label serving an image the window
+ * says it should have left is not a countdown, it is a fault.
+ */
+export function migrationFails(status, days) {
+  if (!status) return false;
+  if (status.anomaly) return true;
+  if (status.done) return false;
+  if (status.phase === MIGRATION_PHASE.IN_WINDOW) return true;
+  return Number.isFinite(days) && status.daysToStart !== null && status.daysToStart <= days;
+}
diff --git a/src/manifest.mjs b/src/manifest.mjs
index ef205cc..103a1f1 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -20,14 +20,23 @@
 
 import { fetchText, NotFoundError, DriftError } from './http.mjs';
 import { RAW_BASE, pathForLabel } from './labels.mjs';
+import { manifestCandidates } from './tools.mjs';
 
-const HEADER_KEYS = new Set([
-  'os version',
-  'image version',
-  'kernel version',
-  'systemd version',
-  'image release',
-]);
+/**
+ * The bullets at the top that describe the image itself rather than something
+ * installed on it. Kernel and systemd are here because they are exactly what
+ * changes when a floating label is re-pointed at a new OS, and nothing else in
+ * the manifest records the OS swap.
+ */
+const HEADER_FIELDS = {
+  'os version': 'osVersion',
+  'image version': 'imageVersion',
+  'kernel version': 'kernelVersion',
+  'systemd version': 'systemdVersion',
+};
+
+/** `image release` has no field of its own; it is only ever suppressed. */
+const HEADER_KEYS = new Set([...Object.keys(HEADER_FIELDS), 'image release']);
 
 /** Sections whose tables list SDK sub-packages rather than host tools. */
 const SKIP_TABLE_SECTIONS = new Set(['android']);
@@ -131,15 +140,15 @@ function isSeparatorRow(cells) {
 /**
  * Parse a manifest markdown document.
  * @returns {{label:string|null, title:string|null, osVersion:string|null,
- *            imageVersion:string|null, tools:Record<string,string[]>,
+ *            imageVersion:string|null, kernelVersion:string|null,
+ *            systemdVersion:string|null, tools:Record<string,string[]>,
  *            toolSections:Record<string,string>}}
  */
 export function parseManifest(markdown, label = null) {
   const lines = String(markdown ?? '').split(/\r?\n/);
   const tools = Object.create(null);
   const toolSections = Object.create(null);
-  let osVersion = null;
-  let imageVersion = null;
+  const header = { osVersion: null, imageVersion: null, kernelVersion: null, systemdVersion: null };
   let title = null;
   let section = '';
   let subsection = '';
@@ -199,15 +208,15 @@ export function parseManifest(markdown, label = null) {
       continue;
     }
 
-    const osM = line.match(/^[ \t]*-[ \t]+OS Version:[ \t]*([^\r\n]+)/i);
-    if (osM) {
-      osVersion ??= osM[1].trim();
-      continue;
-    }
-    const ivM = line.match(/^[ \t]*-[ \t]+Image Version:[ \t]*([^\r\n]+)/i);
-    if (ivM) {
-      imageVersion ??= ivM[1].trim();
-      continue;
+    // `[^:\r\n]+` up to the colon and no `$` at the end: the key cannot run past
+    // its own delimiter and there is no failure condition to backtrack over.
+    const headerM = line.match(/^[ \t]*-[ \t]+([^:\r\n]+):[ \t]*([^\r\n]+)/);
+    if (headerM) {
+      const field = HEADER_FIELDS[headerM[1].trim().toLowerCase()];
+      if (field) {
+        header[field] ??= headerM[2].trim();
+        continue;
+      }
     }
 
     if (/^\s*-\s+/.test(line)) {
@@ -275,7 +284,7 @@ export function parseManifest(markdown, label = null) {
   }
 
   // Plain objects out (the accumulators are null-prototype to stay collision-free).
-  return { label, title, osVersion, imageVersion, tools: { ...tools }, toolSections: { ...toolSections } };
+  return { label, title, ...header, tools: { ...tools }, toolSections: { ...toolSections } };
 }
 
 /** Build the raw URL for a label's manifest at a given git ref. */
@@ -334,3 +343,18 @@ export function lookupTool(manifest, candidates) {
   }
   return null;
 }
+
+/**
+ * Resolve canonical tool names against a parsed manifest.
+ * @returns {{map:Record<string,string[]>, missing:string[]}}
+ */
+export function resolveManifestVersions(manifest, tools) {
+  const map = {};
+  const missing = [];
+  for (const t of tools) {
+    const hit = lookupTool(manifest, manifestCandidates(t));
+    if (hit) map[t] = hit.versions;
+    else missing.push(t);
+  }
+  return { map, missing };
+}
diff --git a/src/migration.mjs b/src/migration.mjs
new file mode 100644
index 0000000..5af6d0e
--- /dev/null
+++ b/src/migration.mjs
@@ -0,0 +1,105 @@
+/**
+ * The floating-label migration lane.
+ *
+ * labels.mjs answers the calendar half from the MIGRATIONS table — where today
+ * sits in the window, and which image the runner actually served. This module
+ * answers the other half from the live manifests: what is different between the
+ * image the label means today and the one it will mean when the window closes.
+ *
+ * The diff is the whole point. A warning that says "ubuntu-latest moves to
+ * Ubuntu 26.04 next month" is a calendar entry; "your kernel goes 6.17 -> 7.0
+ * and Node.js 22 -> 24" is something you can act on before it happens.
+ */
+
+import { migrationStatus } from './labels.mjs';
+import { loadManifest, resolveManifestVersions } from './manifest.mjs';
+import { diffTool } from './diff.mjs';
+import { DriftError } from './http.mjs';
+
+/**
+ * Image-level facts that are not installed tools but change with the OS. They
+ * live in the manifest header, so nothing in the tool table records them.
+ */
+export const IMAGE_FIELDS = [
+  ['OS', 'osVersion'],
+  ['Kernel', 'kernelVersion'],
+  ['Systemd', 'systemdVersion'],
+];
+
+const one = (v) => (v ? [v] : null);
+
+/**
+ * Diff the manifest headers of two images. A field missing from both — macOS
+ * manifests carry no kernel or systemd line — diffs to `missing` and is
+ * dropped by the `changed` filter, so no caller has to special-case it.
+ */
+export function imageDiffs(from, to) {
+  return IMAGE_FIELDS.map(([name, field]) => diffTool(name, one(from?.[field]), one(to?.[field])));
+}
+
+/**
+ * One floating label, classified and (where it helps) diffed.
+ *
+ * `plan` calls this for the label the user named; `guard` calls it for every
+ * floating label its workflows actually use. Both get the same object, so the
+ * report renderers do not need to know which lane they are serving.
+ *
+ * Network failures and 404s land in `notes` rather than throwing: the notice is
+ * worth printing even when the manifests cannot be read, which is exactly the
+ * degraded case the brief calls for.
+ *
+ * @returns {Promise<object|null>} null when the label has no announced migration
+ */
+export async function surveyMigration({
+  label,
+  now = new Date(),
+  imageOS = null,
+  tools = [],
+  sites = [],
+  load = loadManifest,
+} = {}) {
+  const status = migrationStatus(label, { now, imageOS });
+  if (!status) return null;
+
+  const survey = {
+    ...status,
+    sites,
+    images: null,
+    image: [],
+    toolDiffs: [],
+    notOnManifest: [],
+    notes: [],
+  };
+
+  // Once the label already means `to`, the lock diff in `guard` is the real
+  // before/after and this one would only restate it from the manifests.
+  if (status.done) return survey;
+
+  let a;
+  let b;
+  try {
+    [a, b] = await Promise.all([load(status.from), load(status.to)]);
+  } catch (err) {
+    survey.notes.push(
+      err instanceof DriftError ? `${err.message}${err.hint ? ` ${err.hint}` : ''}` : String(err),
+    );
+    return survey;
+  }
+  for (const m of [a, b]) {
+    if (m.skipped) survey.notes.push(m.reason);
+  }
+  if (a.skipped || b.skipped) return survey;
+
+  survey.images = { from: a.imageVersion, to: b.imageVersion };
+  survey.image = imageDiffs(a, b).filter((d) => d.changed);
+
+  const ra = resolveManifestVersions(a, tools);
+  const rb = resolveManifestVersions(b, tools);
+  survey.notOnManifest = tools.filter((t) => ra.missing.includes(t) && rb.missing.includes(t));
+  survey.toolDiffs = tools
+    .filter((t) => !survey.notOnManifest.includes(t))
+    .map((t) => diffTool(t, ra.map[t] ?? null, rb.map[t] ?? null))
+    .filter((d) => d.changed);
+
+  return survey;
+}
diff --git a/src/report.mjs b/src/report.mjs
index 34f4af9..54638a3 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -12,7 +12,12 @@ import { appendFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { daysUntil } from './dates.mjs';
-import { deadlineFor, retirementStatus } from './labels.mjs';
+import {
+  MIGRATION_PHASE,
+  MIGRATION_STATE,
+  deadlineFor,
+  retirementStatus,
+} from './labels.mjs';
 import { REF_STATUS } from './runtimes.mjs';
 import {
   MINIMUM_REGISTRATION_VERSION,
@@ -82,17 +87,37 @@ export function deadlineLines(label, now = new Date()) {
 }
 
 /**
- * Full `plan` report.
+ * Full `plan` report. `image` is the manifest-header diff (OS, kernel, systemd)
+ * and `migration` the survey that resolved a floating label, both optional.
  * @returns {string}
  */
-export function planReport({ from, to, fromImage, toImage, diffs, detected, now = new Date() }) {
+export function planReport({
+  from,
+  to,
+  fromImage,
+  toImage,
+  diffs,
+  image = [],
+  migration = null,
+  detected,
+  now = new Date(),
+}) {
   const out = [];
+  // The migration headline first: when `plan` resolved a floating label, it is
+  // the reason these two concrete labels are being compared at all.
+  if (migration) out.push(...migrationHeader(migration));
   out.push(`${from} -> ${to} (images ${fromImage} -> ${toImage})`);
   const dl = deadlineLines(from, now);
   if (dl) out.push(...dl);
   else out.push(`${from} has no announced deprecation deadline in runner-drift's table.`);
   out.push('');
 
+  const imageChanged = image.filter((d) => d.changed);
+  if (imageChanged.length) {
+    for (const d of imageChanged) out.push(planRow(d));
+    out.push('');
+  }
+
   const changed = diffs.filter((d) => d.changed);
   if (!changed.length) {
     out.push(`No change to any of the ${diffs.length} tool(s) your workflows use.`);
@@ -316,6 +341,147 @@ export function retirementSummaryMarkdown(findings) {
   return `${lines.join('\n')}\n`;
 }
 
+/* ------------------------------------------------ floating-label migration */
+
+/**
+ * One sentence per state. Wording is the point of this lane: the same window
+ * means something different depending on whether the runner has moved yet, and
+ * a single generic warning would hide exactly that.
+ */
+const MIGRATION_SENTENCE = {
+  [MIGRATION_STATE.PENDING]: (s) =>
+    `${s.label} moves from ${s.from} to ${s.to}. The rollout starts ${dateWithCountdown(s.starts, s.daysToStart)} and finishes ${dateWithCountdown(s.ends, s.daysToEnd)}.`,
+  [MIGRATION_STATE.MOVED_EARLY]: (s) =>
+    `${s.label} already served ${s.to}, ahead of the announced rollout starting ${dateWithCountdown(s.starts, s.daysToStart)}.`,
+  [MIGRATION_STATE.NOT_YET_MIGRATED]: (s) =>
+    `${s.label} is migrating from ${s.from} to ${s.to} and this runner served ${s.from}. The rollout finishes ${dateWithCountdown(s.ends, s.daysToEnd)}; until then the same label is either image.`,
+  [MIGRATION_STATE.MIGRATED]: (s) =>
+    `The scheduled ${s.label} migration has reached this runner: ${s.from} -> ${s.to}, rollout ${s.starts} to ${s.ends}.`,
+  [MIGRATION_STATE.AMBIGUOUS]: (s) =>
+    `${s.label} is mid-rollout from ${s.from} to ${s.to}, finishing ${dateWithCountdown(s.ends, s.daysToEnd)}. No ImageOS was observed, so which of the two this job ran on is unknown.`,
+  [MIGRATION_STATE.SETTLED]: (s) =>
+    `${s.label} finished migrating from ${s.from} to ${s.to} on ${dateWithCountdown(s.ends, s.daysToEnd)}; it now means ${s.to}.`,
+  [MIGRATION_STATE.STALE]: (s) =>
+    `${s.label} served ${s.from}, but its migration to ${s.to} closed on ${dateWithCountdown(s.ends, s.daysToEnd)}. A runner still on the retired image after the window is an anomaly, not drift.`,
+  [MIGRATION_STATE.UNEXPECTED]: (s) =>
+    `${s.label} served ImageOS="${s.imageOS}", which is neither ${s.from} nor ${s.to}. runner-drift's migration window (${s.starts} to ${s.ends}) may be out of date.`,
+};
+
+const MIGRATION_KIND = {
+  [MIGRATION_STATE.PENDING]: 'notice',
+  [MIGRATION_STATE.MOVED_EARLY]: 'notice',
+  [MIGRATION_STATE.NOT_YET_MIGRATED]: 'warning',
+  [MIGRATION_STATE.MIGRATED]: 'notice',
+  [MIGRATION_STATE.AMBIGUOUS]: 'warning',
+  [MIGRATION_STATE.SETTLED]: 'notice',
+  [MIGRATION_STATE.STALE]: 'error',
+  [MIGRATION_STATE.UNEXPECTED]: 'error',
+};
+
+const MIGRATION_TITLE = {
+  [MIGRATION_STATE.PENDING]: (s) => `${s.label} becomes ${s.to} in ${s.daysToStart} days`,
+  [MIGRATION_STATE.MOVED_EARLY]: (s) => `${s.label} is already ${s.to}`,
+  [MIGRATION_STATE.NOT_YET_MIGRATED]: (s) => `${s.label} migration under way`,
+  [MIGRATION_STATE.MIGRATED]: (s) => `${s.label} is now ${s.to}`,
+  [MIGRATION_STATE.AMBIGUOUS]: (s) => `${s.label} migration under way`,
+  [MIGRATION_STATE.SETTLED]: (s) => `${s.label} is now ${s.to}`,
+  [MIGRATION_STATE.STALE]: (s) => `${s.label} still serving ${s.from}`,
+  [MIGRATION_STATE.UNEXPECTED]: (s) => `unrecognised image on ${s.label}`,
+};
+
+const MIGRATION_BADGE = {
+  [MIGRATION_PHASE.PENDING]: '🗓 pending',
+  [MIGRATION_PHASE.IN_WINDOW]: '🟠 in window',
+  [MIGRATION_PHASE.SETTLED]: '✅ settled',
+};
+
+/** The one sentence that describes a survey. No source link; callers add it. */
+export function migrationMessage(survey) {
+  return MIGRATION_SENTENCE[survey.state](survey);
+}
+
+/** The sentence and its source: the two lines every format leads with. */
+export function migrationHeader(survey) {
+  return [
+    migrationMessage(survey),
+    `announced ${survey.announced}; source ${survey.sourceRef} ${survey.source}`,
+  ];
+}
+
+/**
+ * Plain-text block for one survey: the sentence, the source, and whatever the
+ * manifests could tell us about the difference between the two images.
+ */
+export function migrationLines(survey) {
+  const lines = migrationHeader(survey);
+  const rows = [...survey.image, ...survey.toolDiffs];
+  if (rows.length) {
+    lines.push(`${survey.from} -> ${survey.to}:`);
+    for (const d of rows) lines.push(`  ${planRow(d)}`);
+  }
+  if (survey.notOnManifest.length) {
+    lines.push(`Not listed on either image manifest (skipped): ${survey.notOnManifest.join(', ')}`);
+  }
+  for (const n of survey.notes) lines.push(`Manifest diff unavailable: ${n}`);
+  return lines;
+}
+
+/** The whole `guard` migration block, one paragraph per floating label. */
+export function migrationReport(surveys) {
+  return surveys.flatMap((s, i) => (i ? ['', ...migrationLines(s)] : migrationLines(s))).join('\n');
+}
+
+/**
+ * `::notice`/`::warning`/`::error` per `runs-on:` site, so the message lands on
+ * the line that owns the floating label. A survey with no site on disk (guard
+ * reading the label from ImageOS with no workflow checkout) still gets one
+ * step-level annotation rather than none.
+ */
+export function migrationAnnotations(surveys) {
+  return surveys.flatMap((s) => {
+    const kind = MIGRATION_KIND[s.state];
+    const title = `runner-drift: ${MIGRATION_TITLE[s.state](s)}`;
+    const message = `${migrationMessage(s)} See ${s.source}`;
+    const sites = s.sites.length ? s.sites : [null];
+    return sites.map((site) => annotation(kind, title, message, site));
+  });
+}
+
+/** Step-summary table for migration surveys, with the image diff underneath. */
+export function migrationSummaryMarkdown(surveys) {
+  const rows = surveys.map((s) => [
+    `\`${s.label}\``,
+    MIGRATION_BADGE[s.phase],
+    `\`${s.from}\` → \`${s.to}\``,
+    `${dateWithCountdown(s.starts, s.daysToStart)} → ${dateWithCountdown(s.ends, s.daysToEnd)}`,
+    s.observed ? `\`${s.observed}\`` : '—',
+    `[${s.sourceRef}](${s.source})`,
+  ]);
+  const lines = [
+    '## runner-drift — floating label migration',
+    '',
+    ...markdownTable(['Label', 'Phase', 'Move', 'Window', 'This runner', 'Source'], rows),
+  ];
+  for (const s of surveys) {
+    lines.push('', migrationMessage(s));
+    const diffRows = [...s.image, ...s.toolDiffs];
+    if (!diffRows.length) continue;
+    lines.push(
+      '',
+      ...markdownTable(
+        [`\`${s.from}\` → \`${s.to}\``, 'From', 'To', 'Change'],
+        diffRows.map((d) => [
+          d.tool,
+          d.from.join(', ') || '(absent)',
+          d.to.join(', ') || '(absent)',
+          SEVERITY_BADGE[d.severity] ?? d.severity,
+        ]),
+      ),
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
 /** Append markdown to $GITHUB_STEP_SUMMARY when running inside Actions. */
 export async function writeStepSummary(markdown) {
   return appendToEnvFile('GITHUB_STEP_SUMMARY', `${markdown}\n`);
diff --git a/test/cli.test.mjs b/test/cli.test.mjs
index 451d99a..a1245ac 100644
--- a/test/cli.test.mjs
+++ b/test/cli.test.mjs
@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFile } from 'node:fs/promises';
-import { main, EXIT_OK, EXIT_USAGE } from '../src/cli.mjs';
+import { main, OPTIONS, EXIT_OK, EXIT_USAGE } from '../src/cli.mjs';
 import { captureIO } from './helpers.mjs';
 
 async function run(argv) {
@@ -129,3 +129,46 @@ test('guard on a machine with no ImageVersion skips cleanly through main()', asy
     if (saved !== undefined) process.env.ImageVersion = saved;
   }
 });
+
+test("every fail-on-* input the action declares is forwarded and known to the CLI", async () => {
+  const yml = await readFile(new URL('../action.yml', import.meta.url), 'utf8');
+  const declared = [...yml.matchAll(/^ {2}(fail-on[a-z-]*):$/gm)].map((m) => m[1]);
+  assert.ok(declared.includes('fail-on-migration'), 'the migration gate is an input');
+  for (const name of declared) {
+    assert.ok(name in OPTIONS, `${name} is a CLI flag`);
+    // A value flag reads `args+=(--flag "$RD_X")`, a boolean one `args+=(--flag)`.
+    const passed =
+      yml.includes(`args+=(--${name} `) || yml.includes(`args+=(--${name})`);
+    assert.ok(passed, `action.yml passes --${name} through to the CLI`);
+  }
+});
+
+test('--as-of rejects anything that is not a date', async () => {
+  for (const bad of ['tomorrow', '2026-13-45', '']) {
+    const r = await run(['plan', '--from', 'ubuntu-latest', '--as-of', bad]);
+    assert.equal(r.code, EXIT_USAGE, `"${bad}" rejected`);
+    assert.match(r.stderr, /--as-of needs a date such as 2026-10-19/);
+  }
+});
+
+test('--as-of moves every countdown, without a network call', async () => {
+  const saved = process.env.ImageVersion;
+  delete process.env.ImageVersion;
+  try {
+    const r = await run([
+      'guard',
+      '--tools',
+      'node',
+      '--workflows',
+      'test/fixtures/workflows-retirement',
+      '--fail-on-retirement',
+      '100',
+      '--as-of',
+      '2026-08-12',
+      '--no-summary',
+    ]);
+    assert.match(r.stdout, /macos-14 retires in 82 days/);
+  } finally {
+    if (saved !== undefined) process.env.ImageVersion = saved;
+  }
+});
diff --git a/test/fixtures/Ubuntu2404-Readme-20260907.300.1.md b/test/fixtures/Ubuntu2404-Readme-20260907.300.1.md
new file mode 100644
index 0000000..225893e
--- /dev/null
+++ b/test/fixtures/Ubuntu2404-Readme-20260907.300.1.md
@@ -0,0 +1,333 @@
+| Announcements |
+|-|
+| [[Ubuntu] PostgreSQL is now available on the Ubuntu Arm64 images](https://github.com/actions/runner-images/issues/14651) |
+| [[Ubuntu] Podman will be downgraded on Ubuntu 22.04 and 24.04 runner images](https://github.com/actions/runner-images/issues/14642) |
+| [[Ubuntu] The Ubuntu 22 based runner images will begin deprecation on September 17th and will be fully unsupported by April 17th for GitHub Actions and Azure DevOps](https://github.com/actions/runner-images/issues/14254) |
+| [[Ubuntu] Ubuntu 26.04 and Ubuntu 26.04 Arm is now available as a public preview](https://github.com/actions/runner-images/issues/14226) |
+***
+# Ubuntu 24.04
+- OS Version: 24.04.5 LTS
+- Kernel Version: 6.17.0-1022-azure
+- Image Version: 20260907.300.1
+- Systemd version: 255.4-1ubuntu8.17
+
+## Installed Software
+
+### Language and Runtime
+- Bash 5.2.21(1)-release
+- Clang: 16.0.6, 17.0.6, 18.1.3
+- Clang-format: 16.0.6, 17.0.6, 18.1.3
+- Clang-tidy: 16.0.6, 17.0.6, 18.1.3
+- Dash 0.5.12-6ubuntu5
+- GNU C++: 12.4.0, 13.3.0, 14.2.0
+- GNU Fortran: 12.4.0, 13.3.0, 14.2.0
+- Julia 1.12.7
+- Kotlin 2.4.20
+- Node.js 22.23.2
+- Perl 5.38.2
+- Python 3.12.3
+- Ruby 3.2.3
+- Swift 6.3.3
+
+### Package Management
+- cpan 1.64
+- Helm 3.21.4
+- Homebrew 6.0.22
+- Miniconda 26.7.1
+- Npm 10.9.8
+- Pip 24.0
+- Pip3 24.0
+- Pipx 1.16.7
+- RubyGems 3.4.20
+- Vcpkg (build from commit 04a9d8e521)
+- Yarn 1.22.22
+
+#### Environment variables
+| Name                    | Value                  |
+| ----------------------- | ---------------------- |
+| CONDA                   | /usr/share/miniconda   |
+| VCPKG_INSTALLATION_ROOT | /usr/local/share/vcpkg |
+
+#### Homebrew note
+```
+Location: /home/linuxbrew
+Note: Homebrew is pre-installed on image but not added to PATH.
+run the eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" command
+to accomplish this.
+```
+
+### Project Management
+- Ant 1.10.14
+- Gradle 9.7.1
+- Lerna 10.0.1
+- Maven 3.9.16
+
+### Tools
+- Ansible 2.21.3
+- AzCopy 10.32.7 - available by `azcopy` and `azcopy10` aliases
+- Bazel 9.2.0
+- Bazelisk 1.28.1
+- Bicep 0.46.1
+- Buildah 1.33.7
+- CMake 3.31.6
+- CodeQL Action Bundle 2.26.4
+- Docker Amazon ECR Credential Helper 0.12.0
+- Docker Compose 2.38.2
+- Docker-Buildx 0.37.0
+- Docker Client 28.0.4
+- Docker Server 28.0.4
+- Fastlane 2.239.0
+- Git 2.55.0
+- Git LFS 3.8.0
+- Git-ftp 1.6.0
+- Haveged 1.9.14
+- jq 1.7
+- Kind 0.33.0
+- Kubectl 1.37.0
+- Kustomize 5.8.1
+- MediaInfo 24.01
+- Mercurial 6.7.2
+- Minikube 1.39.0
+- n 10.2.0
+- Newman 6.2.2
+- nvm 0.40.7
+- OpenSSL 3.0.13-0ubuntu3.15
+- Packer 1.16.0
+- Parcel 2.16.4
+- Podman 4.9.3
+- Pulumi 3.261.0
+- Skopeo 1.13.3
+- Sphinx Open Source Search Server 2.2.11
+- yamllint 1.38.0
+- yq 4.53.6
+- zstd 1.5.7
+- Ninja 1.13.2
+
+### CLI Tools
+- AWS CLI 2.36.40
+- AWS CLI Session Manager Plugin 1.2.835.0
+- AWS SAM CLI 1.166.1
+- Azure CLI 2.90.0
+- Azure CLI (azure-devops) 1.0.8
+- GitHub CLI 2.100.0
+- Google Cloud CLI 583.0.0
+
+### Java
+| Version             | Environment Variable |
+| ------------------- | -------------------- |
+| 8.0.504+1           | JAVA_HOME_8_X64      |
+| 11.0.32+9           | JAVA_HOME_11_X64     |
+| 17.0.20+1 (default) | JAVA_HOME_17_X64     |
+| 21.0.12+1           | JAVA_HOME_21_X64     |
+| 25.0.4+1            | JAVA_HOME_25_X64     |
+
+### PHP Tools
+- PHP: 8.3.6
+- Composer 2.10.3
+- PHPUnit 8.5.54
+```
+Both Xdebug and PCOV extensions are installed, but only Xdebug is enabled.
+```
+
+### Haskell Tools
+- Cabal 3.18.1.0
+- GHC 9.14.1
+- GHCup 0.2.6.2
+- Stack 3.11.1
+
+### Rust Tools
+- Cargo 1.98.1
+- Rust 1.98.1
+- Rustdoc 1.98.1
+- Rustup 1.29.1
+
+#### Packages
+- Rustfmt 1.9.0
+
+### Browsers and Drivers
+- Google Chrome 152.0.7977.82
+- ChromeDriver 152.0.7977.82
+- Chromium 152.0.7977.0
+- Microsoft Edge 152.0.4191.66
+- Microsoft Edge WebDriver 152.0.4191.66
+- Selenium server 4.48.0
+- Mozilla Firefox 155.0
+- Geckodriver 0.37.1
+
+#### Environment variables
+| Name              | Value                                 |
+| ----------------- | ------------------------------------- |
+| CHROMEWEBDRIVER   | /usr/local/share/chromedriver-linux64 |
+| EDGEWEBDRIVER     | /usr/local/share/edge_driver          |
+| GECKOWEBDRIVER    | /usr/local/share/gecko_driver         |
+| SELENIUM_JAR_PATH | /usr/share/java/selenium-server.jar   |
+
+### .NET Tools
+- .NET Core SDK: 8.0.130, 8.0.206, 8.0.319, 8.0.424, 9.0.120, 9.0.205, 9.0.317, 10.0.111, 10.0.204, 10.0.303, 10.0.400
+- nbgv 3.10.94+dea9a6c17c
+
+### Databases
+- sqlite3 3.45.1
+
+#### PostgreSQL
+- PostgreSQL 16.15
+```
+User: postgres
+PostgreSQL service is disabled by default.
+Use the following command as a part of your job to start the service: 'sudo systemctl start postgresql.service'
+```
+
+#### MySQL
+- MySQL 8.0.46-0ubuntu0.24.04.4
+```
+User: root
+Password: root
+MySQL service is disabled by default.
+Use the following command as a part of your job to start the service: 'sudo systemctl start mysql.service'
+```
+
+### Cached Tools
+
+#### Go
+- 1.24.13
+- 1.25.14
+- 1.26.8
+
+#### Node.js
+- 22.23.2
+- 24.20.0
+
+#### Python
+- 3.10.21
+- 3.11.16
+- 3.12.14
+- 3.13.15
+- 3.14.7
+
+#### PyPy
+- 3.9.19 [PyPy 7.3.16]
+- 3.10.16 [PyPy 7.3.19]
+- 3.11.15 [PyPy 7.3.23]
+
+#### Ruby
+- 3.2.11
+- 3.3.12
+- 3.4.10
+- 4.0.6
+
+### PowerShell Tools
+- PowerShell 7.6.5
+
+#### PowerShell Modules
+- Az: 15.6.1
+- Microsoft.Graph: 2.39.0
+- Pester: 5.9.0
+- PSScriptAnalyzer: 1.25.0
+
+### Web Servers
+| Name    | Version | ConfigFile                | ServiceStatus | ListenPort |
+| ------- | ------- | ------------------------- | ------------- | ---------- |
+| apache2 | 2.4.58  | /etc/apache2/apache2.conf | inactive      | 80         |
+| nginx   | 1.24.0  | /etc/nginx/nginx.conf     | inactive      | 80         |
+
+### Android
+| Package Name               | Version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Android Command Line Tools | 12.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Android SDK Build-tools    | 37.0.0<br>36.0.0 36.1.0<br>35.0.0 35.0.1<br>34.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Android SDK Platform-Tools | 37.0.1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Android SDK Platforms      | android-37.2-beta3 (rev 3)<br>android-37.2-beta2 (rev 2)<br>android-37.2-beta1 (rev 1)<br>android-37.2 (rev 1)<br>android-37.1 (rev 1)<br>android-37.0 (rev 2)<br>android-36.1 (rev 1)<br>android-36-ext19 (rev 1)<br>android-36-ext18 (rev 1)<br>android-36 (rev 2)<br>android-35-ext15 (rev 1)<br>android-35-ext14 (rev 1)<br>android-35 (rev 2)<br>android-34-ext8 (rev 1)<br>android-34-ext12 (rev 1)<br>android-34-ext11 (rev 1)<br>android-34-ext10 (rev 1)<br>android-34 (rev 3) |
+| Android Support Repository | 47.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| CMake                      | 3.31.5<br>4.1.2                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Google Play services       | 49                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Google Repository          | 58                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| NDK                        | 27.3.13750724 (default)<br>28.2.13676358<br>29.0.14206865                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+#### Environment variables
+| Name                    | Value                                        |
+| ----------------------- | -------------------------------------------- |
+| ANDROID_HOME            | /usr/local/lib/android/sdk                   |
+| ANDROID_NDK             | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_NDK_HOME        | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_NDK_LATEST_HOME | /usr/local/lib/android/sdk/ndk/29.0.14206865 |
+| ANDROID_NDK_ROOT        | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_SDK_ROOT        | /usr/local/lib/android/sdk                   |
+
+### Installed apt packages
+| Name                   | Version                      |
+| ---------------------- | ---------------------------- |
+| acl                    | 2.3.2-1build1.1              |
+| aria2                  | 1.37.0+debian-1build3        |
+| autoconf               | 2.71-3                       |
+| automake               | 1:1.16.5-1.3ubuntu1          |
+| binutils               | 2.42-4ubuntu2.10             |
+| bison                  | 2:3.8.2+dfsg-1build2         |
+| brotli                 | 1.1.0-2build2                |
+| bzip2                  | 1.0.8-5.1ubuntu0.1           |
+| coreutils              | 9.4-3ubuntu6.3               |
+| curl                   | 8.5.0-2ubuntu10.13           |
+| dbus                   | 1.14.10-4ubuntu4.1           |
+| dnsutils               | 1:9.18.39-0ubuntu0.24.04.7   |
+| dpkg                   | 1.22.6ubuntu6.6              |
+| dpkg-dev               | 1.22.6ubuntu6.6              |
+| fakeroot               | 1.33-1                       |
+| file                   | 1:5.45-3build1               |
+| findutils              | 4.9.0-5build1                |
+| flex                   | 2.6.4-8.2build1              |
+| fonts-noto-color-emoji | 2.047-0ubuntu0.24.04.1       |
+| ftp                    | 20230507-2build3             |
+| g++                    | 4:13.2.0-7ubuntu1            |
+| gcc                    | 4:13.2.0-7ubuntu1            |
+| gnupg2                 | 2.4.4-2ubuntu17.6            |
+| haveged                | 1.9.14-1ubuntu2              |
+| iproute2               | 6.1.0-1ubuntu6.4             |
+| iputils-ping           | 3:20240117-1ubuntu0.1        |
+| jq                     | 1.7.1-3ubuntu0.24.04.2       |
+| libicu-dev             | 74.2-1ubuntu3.1              |
+| libnss3-tools          | 2:3.98-1ubuntu0.2            |
+| libsqlite3-dev         | 3.45.1-1ubuntu2.7            |
+| libssl-dev             | 3.0.13-0ubuntu3.15           |
+| libtool                | 2.4.7-7build1                |
+| libyaml-dev            | 0.2.5-1build1                |
+| locales                | 2.39-0ubuntu8.8              |
+| lz4                    | 1.9.4-1build1.1              |
+| m4                     | 1.4.19-4build1               |
+| make                   | 4.3-4.1build2                |
+| mediainfo              | 24.01.1-1build2              |
+| mercurial              | 6.7.2-1ubuntu2.2             |
+| net-tools              | 2.10-0.1ubuntu4.4            |
+| netcat                 | 1.226-1ubuntu2               |
+| openssh-client         | 1:9.6p1-3ubuntu13.19         |
+| p7zip-full             | 16.02+transitional.1         |
+| p7zip-rar              | 16.02+transitional.1         |
+| parallel               | 20231122+ds-1                |
+| patchelf               | 0.18.0-1.1build1             |
+| pigz                   | 2.8-1                        |
+| pkg-config             | 1.8.1-2build1                |
+| pollinate              | 4.33-3.1ubuntu1.3            |
+| python-is-python3      | 3.11.4-1                     |
+| rpm                    | 4.18.2+dfsg-2.1build2        |
+| rsync                  | 3.2.7-1ubuntu1.5             |
+| shellcheck             | 0.9.0-1                      |
+| sphinxsearch           | 2.2.11-8build1               |
+| sqlite3                | 3.45.1-1ubuntu2.7            |
+| ssh                    | 1:9.6p1-3ubuntu13.19         |
+| sshpass                | 1.09-1                       |
+| sudo                   | 1.9.15p5-3ubuntu5.24.04.2    |
+| swig                   | 4.2.0-2ubuntu1               |
+| systemd-coredump       | 255.4-1ubuntu8.17            |
+| tar                    | 1.35+dfsg-3ubuntu0.4         |
+| telnet                 | 0.17+2.5-3ubuntu4.2          |
+| texinfo                | 7.1-3build2                  |
+| time                   | 1.9-0.2build1                |
+| tk                     | 8.6.14build1                 |
+| tree                   | 2.1.1-2ubuntu3.24.04.2       |
+| tzdata                 | 2026c-0ubuntu0.24.04.1       |
+| unzip                  | 6.0-28ubuntu4.1              |
+| upx                    | 4.2.2-3                      |
+| wget                   | 1.21.4-1ubuntu4.5            |
+| xvfb                   | 2:21.1.12-1ubuntu1.6         |
+| xz-utils               | 5.6.1+really5.4.5-1ubuntu0.3 |
+| zip                    | 3.0-13ubuntu0.2              |
+| zsync                  | 0.6.2-5build1                |
+
diff --git a/test/fixtures/Ubuntu2604-Readme-20260907.131.1.md b/test/fixtures/Ubuntu2604-Readme-20260907.131.1.md
new file mode 100644
index 0000000..69803b6
--- /dev/null
+++ b/test/fixtures/Ubuntu2604-Readme-20260907.131.1.md
@@ -0,0 +1,316 @@
+| Announcements |
+|-|
+| [[Ubuntu] PostgreSQL is now available on the Ubuntu Arm64 images](https://github.com/actions/runner-images/issues/14651) |
+| [[Ubuntu] Podman will be downgraded on Ubuntu 22.04 and 24.04 runner images](https://github.com/actions/runner-images/issues/14642) |
+| [[Ubuntu] The Ubuntu 22 based runner images will begin deprecation on September 17th and will be fully unsupported by April 17th for GitHub Actions and Azure DevOps](https://github.com/actions/runner-images/issues/14254) |
+| [[Ubuntu] Ubuntu 26.04 and Ubuntu 26.04 Arm is now available as a public preview](https://github.com/actions/runner-images/issues/14226) |
+***
+# Ubuntu 26.04
+- OS Version: 26.04.1 LTS
+- Kernel Version: 7.0.0-1012-azure
+- Image Version: 20260907.131.1
+- Systemd version: 259.5-0ubuntu3.4
+
+## Installed Software
+
+### Language and Runtime
+- Bash 5.3.9(1)-release
+- Clang: 20.1.8, 21.1.8, 22.1.2
+- Clang-format: 20.1.8, 21.1.8, 22.1.2
+- Clang-tidy: 20.1.8, 21.1.8, 22.1.2
+- Dash 0.5.12-12ubuntu3
+- GNU C++: 13.4.0, 14.3.0, 15.2.0
+- GNU Fortran: 13.4.0, 14.3.0, 15.2.0
+- Kotlin 2.4.20
+- Node.js 24.20.0
+- Perl 5.40.1
+- Python 3.14.4
+- Ruby 3.3.8
+
+### Package Management
+- cpan 1.64
+- Helm 4.2.4
+- Homebrew 6.0.22
+- Npm 11.19.0
+- Pip 25.1.1
+- Pip3 25.1.1
+- Pipx 1.17.2
+- RubyGems 3.6.7
+- Vcpkg (build from commit 04a9d8e521)
+- Yarn 1.22.22
+
+#### Environment variables
+| Name                    | Value                  |
+| ----------------------- | ---------------------- |
+| CONDA                   |                        |
+| VCPKG_INSTALLATION_ROOT | /usr/local/share/vcpkg |
+
+#### Homebrew note
+```
+Location: /home/linuxbrew
+Note: Homebrew is pre-installed on image but not added to PATH.
+run the eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" command
+to accomplish this.
+```
+
+### Project Management
+- Ant 1.10.15
+- Gradle 9.7.1
+- Maven 3.9.15
+
+### Tools
+- Ansible 2.21.3
+- AzCopy 10.32.7 - available by `azcopy` and `azcopy10` aliases
+- Bazel 9.2.0
+- Bazelisk 1.28.1
+- Bicep 0.46.1
+- Buildah 1.42.1
+- CMake 4.4.3
+- CodeQL Action Bundle 2.26.4
+- Docker Amazon ECR Credential Helper 0.12.0
+- Docker Compose 5.1.3
+- Docker-Buildx 0.37.0
+- Docker Client 29.4.2
+- Docker Server 29.4.2
+- Git 2.55.0
+- Git LFS 3.8.0
+- Git-ftp 1.6.0
+- jq 1.8.1
+- Kind 0.33.0
+- Kubectl 1.37.0
+- Kustomize 5.8.1
+- Minikube 1.39.0
+- n 10.2.0
+- nvm 0.40.7
+- OpenSSL 3.5.5-1ubuntu3.5
+- Packer 1.16.0
+- Podman 5.7.0
+- Skopeo 1.21.0-dev
+- yamllint 1.38.0
+- yq 4.53.6
+- zstd 1.5.7
+- Ninja 1.13.2
+
+### CLI Tools
+- AWS CLI 2.36.40
+- AWS CLI Session Manager Plugin 1.2.835.0
+- AWS SAM CLI 1.166.1
+- Azure CLI 2.90.0
+- Azure CLI (azure-devops) 1.0.8
+- GitHub CLI 2.100.0
+- Google Cloud CLI 583.0.0
+
+### Java
+| Version            | Environment Variable |
+| ------------------ | -------------------- |
+| 11.0.32+9          | JAVA_HOME_11_X64     |
+| 17.0.20+1          | JAVA_HOME_17_X64     |
+| 21.0.12+1          | JAVA_HOME_21_X64     |
+| 25.0.4+1 (default) | JAVA_HOME_25_X64     |
+
+### PHP Tools
+- PHP: 8.5.4
+- Composer 2.10.3
+- PHPUnit 8.5.54
+```
+Both Xdebug and PCOV extensions are installed, but only Xdebug is enabled.
+```
+
+### Haskell Tools
+- Cabal 3.18.1.0
+- GHC 9.14.1
+- GHCup 0.2.6.2
+- Stack 3.11.1
+
+### Rust Tools
+- Cargo 1.98.1
+- Rust 1.98.1
+- Rustdoc 1.98.1
+- Rustup 1.29.1
+
+#### Packages
+- Rustfmt 1.9.0
+
+### Browsers and Drivers
+- Google Chrome 152.0.7977.82
+- ChromeDriver 152.0.7977.82
+- Chromium 152.0.7977.0
+- Microsoft Edge 152.0.4191.66
+- Microsoft Edge WebDriver 152.0.4191.66
+- Selenium server 4.48.0
+- Mozilla Firefox 155.0
+- Geckodriver 0.37.1
+
+#### Environment variables
+| Name              | Value                                 |
+| ----------------- | ------------------------------------- |
+| CHROMEWEBDRIVER   | /usr/local/share/chromedriver-linux64 |
+| EDGEWEBDRIVER     | /usr/local/share/edge_driver          |
+| GECKOWEBDRIVER    | /usr/local/share/gecko_driver         |
+| SELENIUM_JAR_PATH | /usr/share/java/selenium-server.jar   |
+
+### .NET Tools
+- .NET Core SDK: 8.0.130, 8.0.206, 8.0.319, 8.0.424, 9.0.120, 9.0.205, 9.0.317, 10.0.111, 10.0.204, 10.0.303, 10.0.400
+- nbgv 3.10.94+dea9a6c17c
+
+### Databases
+- sqlite3 3.46.1
+
+#### PostgreSQL
+- PostgreSQL 18.6
+```
+User: postgres
+PostgreSQL service is disabled by default.
+Use the following command as a part of your job to start the service: 'sudo systemctl start postgresql.service'
+```
+
+#### MySQL
+- MySQL 8.4.11-0ubuntu0.26.04.1
+```
+User: root
+Password: root
+MySQL service is disabled by default.
+Use the following command as a part of your job to start the service: 'sudo systemctl start mysql.service'
+```
+
+### Cached Tools
+
+#### Go
+- 1.24.13
+- 1.25.14
+- 1.26.8
+
+#### Node.js
+- 22.23.2
+- 24.20.0
+
+#### Python
+- 3.10.21
+- 3.11.16
+- 3.12.14
+- 3.13.15
+- 3.14.7
+
+#### PyPy
+- 3.9.19 [PyPy 7.3.16]
+- 3.10.16 [PyPy 7.3.19]
+- 3.11.15 [PyPy 7.3.23]
+
+#### Ruby
+- 3.2.11
+- 3.3.12
+- 3.4.10
+- 4.0.6
+
+### PowerShell Tools
+- PowerShell 7.6.5
+
+#### PowerShell Modules
+- Az: 15.6.1
+- Microsoft.Graph: 2.39.0
+- Pester: 5.9.0
+- PSScriptAnalyzer: 1.25.0
+
+### Web Servers
+| Name    | Version | ConfigFile                | ServiceStatus | ListenPort |
+| ------- | ------- | ------------------------- | ------------- | ---------- |
+| apache2 | 2.4.66  | /etc/apache2/apache2.conf | inactive      | 80         |
+| nginx   | 1.28.3  | /etc/nginx/nginx.conf     | inactive      | 80         |
+
+### Android
+| Package Name               | Version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Android Command Line Tools | 20.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Android SDK Build-tools    | 37.0.0<br>36.0.0 36.1.0<br>35.0.0 35.0.1<br>34.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Android SDK Platform-Tools | 37.0.1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Android SDK Platforms      | android-37.2-beta3 (rev 3)<br>android-37.2-beta2 (rev 2)<br>android-37.2-beta1 (rev 1)<br>android-37.2 (rev 1)<br>android-37.1 (rev 1)<br>android-37.0 (rev 2)<br>android-36.1 (rev 1)<br>android-36-ext19 (rev 1)<br>android-36-ext18 (rev 1)<br>android-36 (rev 2)<br>android-35-ext15 (rev 1)<br>android-35-ext14 (rev 1)<br>android-35 (rev 2)<br>android-34-ext8 (rev 1)<br>android-34-ext12 (rev 1)<br>android-34-ext11 (rev 1)<br>android-34-ext10 (rev 1)<br>android-34 (rev 3) |
+| Android Support Repository | 47.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| CMake                      | 3.31.5<br>4.1.2                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Google Play services       | 49                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Google Repository          | 58                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| NDK                        | 27.3.13750724 (default)<br>28.2.13676358<br>29.0.14206865                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+#### Environment variables
+| Name                    | Value                                        |
+| ----------------------- | -------------------------------------------- |
+| ANDROID_HOME            | /usr/local/lib/android/sdk                   |
+| ANDROID_NDK             | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_NDK_HOME        | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_NDK_LATEST_HOME | /usr/local/lib/android/sdk/ndk/29.0.14206865 |
+| ANDROID_NDK_ROOT        | /usr/local/lib/android/sdk/ndk/27.3.13750724 |
+| ANDROID_SDK_ROOT        | /usr/local/lib/android/sdk                   |
+
+### Installed apt packages
+| Name                   | Version                      |
+| ---------------------- | ---------------------------- |
+| 7zip                   | 26.00+dfsg-1                 |
+| 7zip-rar               | 26.00+ds-1                   |
+| acl                    | 2.3.2-2                      |
+| aria2                  | 1.37.0+debian-4              |
+| autoconf               | 2.72-3.1ubuntu2              |
+| automake               | 1:1.18.1-3build1             |
+| bind9-dnsutils         | 1:9.20.24-1ubuntu0.3         |
+| binutils               | 2.46-3ubuntu2                |
+| bison                  | 2:3.8.2+dfsg-1build4         |
+| brotli                 | 1.2.0-3build1                |
+| bzip2                  | 1.0.8-6ubuntu0.1             |
+| coreutils              | 9.5-1ubuntu2+0.0.0\~ubuntu25 |
+| curl                   | 8.18.0-1ubuntu2.4            |
+| dbus                   | 1.16.2-2ubuntu4              |
+| dpkg                   | 1.23.7ubuntu1                |
+| dpkg-dev               | 1.23.7ubuntu1                |
+| fakeroot               | 1.37.2-1                     |
+| file                   | 1:5.46-5build2               |
+| findutils              | 4.10.0-3build2               |
+| flex                   | 2.6.4-8.2build2              |
+| fonts-noto-color-emoji | 2.051-1build1                |
+| ftp                    | 20260211-1                   |
+| g++                    | 4:15.2.0-5ubuntu1            |
+| gcc                    | 4:15.2.0-5ubuntu1            |
+| gnupg2                 | 2.4.8-4ubuntu3.1             |
+| iproute2               | 6.19.0-1ubuntu1.1            |
+| iputils-ping           | 3:20250605-1ubuntu1          |
+| jq                     | 1.8.1-4ubuntu2               |
+| libicu-dev             | 78.2-2ubuntu1                |
+| libnss3-tools          | 2:3.120-1ubuntu2.1           |
+| libsqlite3-dev         | 3.46.1-9ubuntu0.2            |
+| libssl-dev             | 3.5.5-1ubuntu3.5             |
+| libtool                | 2.5.4-9                      |
+| libyaml-dev            | 0.2.5-2build3                |
+| locales                | 2.43-2ubuntu2.3              |
+| lz4                    | 1.10.0-8                     |
+| m4                     | 1.4.21-1                     |
+| make                   | 4.4.1-3                      |
+| net-tools              | 2.10-2ubuntu1                |
+| netcat                 | 1.234-1                      |
+| openssh-client         | 1:10.2p1-2ubuntu3.6          |
+| parallel               | 20240222+ds-3                |
+| patchelf               | 0.18.0-1.4build1             |
+| pigz                   | 2.8-1build1                  |
+| pkg-config             | 2.5.1-4                      |
+| pollinate              | 4.33-4ubuntu6                |
+| python-is-python3      | 3.13.3-1+build1              |
+| rpm                    | 6.0.1-1build1                |
+| rsync                  | 3.4.1+ds1-7ubuntu0.3         |
+| shellcheck             | 0.11.0-2                     |
+| sqlite3                | 3.46.1-9ubuntu0.2            |
+| ssh                    | 1:10.2p1-2ubuntu3.6          |
+| sshpass                | 1.10-0.1build1               |
+| sudo                   | 1.9.17p2-1ubuntu3            |
+| swig                   | 4.4.0-1                      |
+| systemd-coredump       | 259.5-0ubuntu3.4             |
+| tar                    | 1.35+dfsg-4ubuntu0.4         |
+| telnet                 | 0.17+2.7-2ubuntu1.1          |
+| texinfo                | 7.2-5ubuntu2                 |
+| time                   | 1.9-0.4                      |
+| tk                     | 8.6.16build1                 |
+| tree                   | 2.3.1-1                      |
+| tzdata                 | 2026c-0ubuntu0.26.04.1       |
+| unzip                  | 6.0-29ubuntu1                |
+| upx                    | 4.2.4-1.1build1              |
+| wget                   | 1.25.0-2ubuntu4.4            |
+| xvfb                   | 2:21.1.22-1ubuntu1           |
+| xz-utils               | 5.8.3-1                      |
+| zip                    | 3.0-15ubuntu3                |
+| zsync                  | 0.6.2-9                      |
+
diff --git a/test/fixtures/workflows-migration/latest.yml b/test/fixtures/workflows-migration/latest.yml
new file mode 100644
index 0000000..f8c5502
--- /dev/null
+++ b/test/fixtures/workflows-migration/latest.yml
@@ -0,0 +1,18 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+      - run: cmake --version
+      - run: python --version
+
+  pinned:
+    runs-on: ubuntu-24.04
+    steps:
+      - run: node --version
diff --git a/test/helpers.mjs b/test/helpers.mjs
index 91c36bd..9abeb06 100644
--- a/test/helpers.mjs
+++ b/test/helpers.mjs
@@ -10,6 +10,8 @@ export const SNAPSHOTS = {
   'ubuntu-22.04': 'Ubuntu2204-Readme-20260720.234.2.md',
   'ubuntu-22.04@old': 'Ubuntu2204-Readme-20260623.199.1.md',
   'ubuntu-24.04': 'Ubuntu2404-Readme-20260720.247.2.md',
+  'ubuntu-24.04@2026-09': 'Ubuntu2404-Readme-20260907.300.1.md',
+  'ubuntu-26.04': 'Ubuntu2604-Readme-20260907.131.1.md',
   'macos-15': 'macos-15-Readme-20260720.0353.1.md',
 };
 
@@ -18,14 +20,23 @@ export async function readFixture(key) {
   return readFile(path.join(FIXTURES, name), 'utf8');
 }
 
-export async function loadFixtureManifest(label) {
-  if (!SNAPSHOTS[label]) {
+export async function loadFixtureManifest(label, key = label) {
+  if (!SNAPSHOTS[key]) {
     return { skipped: true, label, reason: `no fixture for ${label}` };
   }
-  const text = await readFixture(label);
-  return { ...parseManifest(text, label), skipped: false, url: `fixture:${label}`, ref: 'fixture' };
+  const text = await readFixture(key);
+  return { ...parseManifest(text, label), skipped: false, url: `fixture:${key}`, ref: 'fixture' };
 }
 
+/**
+ * A `loadManifest` stand-in that pins a label to one dated snapshot, so a test
+ * can diff two images that really did exist at the same moment.
+ */
+export const fixtureLoader =
+  (aliases = {}) =>
+  (label) =>
+    loadFixtureManifest(label, aliases[label] ?? label);
+
 const RUNNER_FIXTURES = path.join(FIXTURES, 'runners');
 
 /** Recorded live responses from the runner-deprecations endpoint. */
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
new file mode 100644
index 0000000..35b1a85
--- /dev/null
+++ b/test/migration.test.mjs
@@ -0,0 +1,558 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm } from 'node:fs/promises';
+import {
+  MIGRATIONS,
+  MIGRATION_PHASE,
+  MIGRATION_STATE,
+  migrationBetween,
+  migrationFails,
+  migrationFor,
+  migrationStatus,
+} from '../src/labels.mjs';
+import { imageDiffs, surveyMigration } from '../src/migration.mjs';
+import { migrationAnnotations, migrationLines, migrationSummaryMarkdown } from '../src/report.mjs';
+import { detect, extractFloatingSites } from '../src/detect.mjs';
+import { writeLock } from '../src/lock.mjs';
+import { runGuard, runPlan, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
+import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
+
+const WORKFLOWS = path.join(FIXTURES, 'workflows-migration');
+
+// The clock is injected everywhere below, never read from the host: these
+// assertions have to mean the same thing after the window has passed.
+const BEFORE = new Date('2026-10-01T00:00:00Z');
+const DURING = new Date('2026-10-25T00:00:00Z');
+const AFTER = new Date('2026-11-25T00:00:00Z');
+
+// ubuntu-24.04 has several snapshots; the migration wants the one that was
+// current alongside the Ubuntu 26.04 image, or the kernel delta is fiction.
+const LOAD = fixtureLoader({ 'ubuntu-24.04': 'ubuntu-24.04@2026-09' });
+
+const TOOLS = ['CMake', 'Node.js', 'Python', 'Rust'];
+
+async function survey(now, imageOS = null, opts = {}) {
+  return surveyMigration({
+    label: 'ubuntu-latest',
+    now,
+    imageOS,
+    tools: TOOLS,
+    load: LOAD,
+    ...opts,
+  });
+}
+
+/* -------------------------------------------------------------- the table */
+
+test('MIGRATIONS transcribes the changelog window and cites its source', () => {
+  const m = MIGRATIONS['ubuntu-latest'];
+  assert.deepEqual(
+    { from: m.from, to: m.to, starts: m.starts, ends: m.ends, announced: m.announced },
+    {
+      from: 'ubuntu-24.04',
+      to: 'ubuntu-26.04',
+      starts: '2026-10-19',
+      ends: '2026-11-19',
+      announced: '2026-09-17',
+    },
+  );
+  assert.equal(m.sourceRef, 'actions/runner-images#14748');
+  assert.equal(m.source, 'https://github.com/actions/runner-images/issues/14748');
+});
+
+test('MIGRATIONS does not reuse the DEADLINES vocabulary', () => {
+  for (const m of Object.values(MIGRATIONS)) {
+    assert.equal(m.migrateTo, undefined, 'migrateTo means something else in DEADLINES');
+    assert.equal(m.fullyUnsupported, undefined);
+  }
+});
+
+/* -------------------------------------------------------- migrationStatus */
+
+test('pending: the window has not opened, countdown is whole days', () => {
+  const s = migrationStatus('ubuntu-latest', { now: BEFORE });
+  assert.equal(s.phase, MIGRATION_PHASE.PENDING);
+  assert.equal(s.state, MIGRATION_STATE.PENDING);
+  assert.equal(s.daysToStart, 18);
+  assert.equal(s.daysToEnd, 49);
+  assert.equal(s.anomaly, false);
+  assert.equal(s.done, false);
+});
+
+test('in-window on the from-image: not yet migrated, not an anomaly', () => {
+  const s = migrationStatus('ubuntu-latest', { now: DURING, imageOS: 'ubuntu24' });
+  assert.equal(s.phase, MIGRATION_PHASE.IN_WINDOW);
+  assert.equal(s.state, MIGRATION_STATE.NOT_YET_MIGRATED);
+  assert.equal(s.observed, 'ubuntu-24.04');
+  assert.equal(s.anomaly, false);
+  assert.equal(s.daysToEnd, 25);
+});
+
+test('in-window on the to-image: the migration reached this runner', () => {
+  const s = migrationStatus('ubuntu-latest', { now: DURING, imageOS: 'ubuntu26' });
+  assert.equal(s.state, MIGRATION_STATE.MIGRATED);
+  assert.equal(s.observed, 'ubuntu-26.04');
+  assert.equal(s.done, true);
+  assert.equal(s.anomaly, false);
+});
+
+test('settled and correct: the label now means the new image', () => {
+  assert.equal(
+    migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu26' }).state,
+    MIGRATION_STATE.MIGRATED,
+  );
+  const blind = migrationStatus('ubuntu-latest', { now: AFTER });
+  assert.equal(blind.phase, MIGRATION_PHASE.SETTLED);
+  assert.equal(blind.state, MIGRATION_STATE.SETTLED);
+  assert.equal(blind.done, true);
+  assert.equal(blind.daysToEnd, -6);
+});
+
+test('settled on the old image is an anomaly, not drift', () => {
+  const s = migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu24' });
+  assert.equal(s.state, MIGRATION_STATE.STALE);
+  assert.equal(s.anomaly, true);
+  assert.equal(s.done, false);
+});
+
+test('missing ImageOS: the calendar alone still decides pending and settled', () => {
+  assert.equal(migrationStatus('ubuntu-latest', { now: BEFORE }).state, MIGRATION_STATE.PENDING);
+  assert.equal(migrationStatus('ubuntu-latest', { now: AFTER }).state, MIGRATION_STATE.SETTLED);
+  const mid = migrationStatus('ubuntu-latest', { now: DURING });
+  assert.equal(mid.state, MIGRATION_STATE.AMBIGUOUS);
+  assert.equal(mid.observed, null);
+  assert.equal(mid.anomaly, false, 'not knowing is not a fault');
+});
+
+test('an image that arrived before the window opened reads as early, not wrong', () => {
+  const s = migrationStatus('ubuntu-latest', { now: BEFORE, imageOS: 'ubuntu26' });
+  assert.equal(s.state, MIGRATION_STATE.MOVED_EARLY);
+  assert.equal(s.done, true);
+});
+
+test('a known image that is neither end of the window is an anomaly', () => {
+  const s = migrationStatus('ubuntu-latest', { now: DURING, imageOS: 'ubuntu22' });
+  assert.equal(s.state, MIGRATION_STATE.UNEXPECTED);
+  assert.equal(s.observed, 'ubuntu-22.04');
+  assert.equal(s.anomaly, true);
+});
+
+test('an ImageOS this build has never heard of reads as no observation', () => {
+  // guard already warns about an unknown ImageOS on its own. Guessing here
+  // would turn every future image name into a fake anomaly.
+  const s = migrationStatus('ubuntu-latest', { now: DURING, imageOS: 'ubuntu28' });
+  assert.equal(s.state, MIGRATION_STATE.AMBIGUOUS);
+  assert.equal(s.observed, null);
+  assert.equal(s.anomaly, false);
+});
+
+test('no migration configured behaves exactly as before: null', () => {
+  assert.equal(migrationFor('windows-latest'), null);
+  assert.equal(migrationStatus('windows-latest', { now: DURING }), null);
+  assert.equal(migrationStatus('macos-latest', { now: DURING }), null);
+});
+
+test('a pinned concrete label is never treated as migrating', () => {
+  for (const label of ['ubuntu-24.04', 'ubuntu-26.04', 'ubuntu-22.04', 'macos-15']) {
+    assert.equal(migrationStatus(label, { now: DURING, imageOS: 'ubuntu24' }), null, label);
+  }
+});
+
+test('a date outside every window still classifies, never throws', () => {
+  for (const when of ['2020-01-01', '2099-01-01']) {
+    const s = migrationStatus('ubuntu-latest', { now: new Date(`${when}T00:00:00Z`) });
+    assert.ok(Object.values(MIGRATION_STATE).includes(s.state));
+  }
+});
+
+test('the window boundaries belong to the window', () => {
+  const on = (d) => migrationStatus('ubuntu-latest', { now: new Date(`${d}T00:00:00Z`) }).phase;
+  assert.equal(on('2026-10-18'), MIGRATION_PHASE.PENDING);
+  assert.equal(on('2026-10-19'), MIGRATION_PHASE.IN_WINDOW);
+  assert.equal(on('2026-11-19'), MIGRATION_PHASE.IN_WINDOW);
+  assert.equal(on('2026-11-20'), MIGRATION_PHASE.SETTLED);
+});
+
+/* --------------------------------------------------------- migrationFails */
+
+test('the gate fires inside the threshold, in the window, and on an anomaly', () => {
+  const pending = migrationStatus('ubuntu-latest', { now: BEFORE });
+  assert.equal(migrationFails(pending, 10), false, '18 days out, threshold 10');
+  assert.equal(migrationFails(pending, 18), true, 'threshold meets the countdown');
+
+  assert.equal(migrationFails(migrationStatus('ubuntu-latest', { now: DURING }), 0), true);
+  assert.equal(
+    migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu24' }), 0),
+    true,
+    'an anomaly fires whatever the threshold',
+  );
+  assert.equal(
+    migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu26' }), 10000),
+    false,
+    'a completed migration is not a failure',
+  );
+  assert.equal(migrationFails(null, 0), false);
+});
+
+/* -------------------------------------------------------- surveyMigration */
+
+test('pending: the manifest diff is the kernel and systemd move, from real snapshots', async () => {
+  const s = await survey(BEFORE);
+  assert.equal(s.state, MIGRATION_STATE.PENDING);
+  assert.deepEqual(s.images, { from: '20260907.300.1', to: '20260907.131.1' });
+  assert.deepEqual(
+    s.image.map((d) => [d.tool, d.from[0], d.to[0]]),
+    [
+      ['OS', '24.04.5 LTS', '26.04.1 LTS'],
+      ['Kernel', '6.17.0-1022-azure', '7.0.0-1012-azure'],
+      ['Systemd', '255.4-1ubuntu8.17', '259.5-0ubuntu3.4'],
+    ],
+  );
+});
+
+test('only tools that actually move are listed', async () => {
+  const s = await survey(BEFORE);
+  assert.deepEqual(
+    s.toolDiffs.map((d) => `${d.tool} ${d.from[0]} -> ${d.to[0]}`),
+    ['CMake 3.31.6 -> 4.4.3', 'Node.js 22.23.2 -> 24.20.0', 'Python 3.12.3 -> 3.14.4'],
+  );
+  assert.ok(!s.toolDiffs.some((d) => d.tool === 'Rust'), 'Rust 1.98.1 is the same on both images');
+});
+
+test('a settled migration skips the manifest fetch entirely', async () => {
+  const calls = [];
+  const s = await survey(AFTER, 'ubuntu26', {
+    load: (label) => {
+      calls.push(label);
+      return LOAD(label);
+    },
+  });
+  assert.equal(s.state, MIGRATION_STATE.MIGRATED);
+  assert.deepEqual(calls, [], 'the lock diff is the before/after once the label has moved');
+  assert.deepEqual(s.image, []);
+});
+
+test('a 404 degrades to the notice instead of losing it', async () => {
+  const s = await survey(BEFORE, null, {
+    load: async (label) => ({ skipped: true, label, reason: `No manifest at ${label} (404).` }),
+  });
+  assert.equal(s.state, MIGRATION_STATE.PENDING);
+  assert.equal(s.images, null);
+  assert.deepEqual(s.image, []);
+  assert.equal(s.notes.length, 2);
+  assert.match(s.notes[0], /No manifest at ubuntu-24\.04 \(404\)/);
+  assert.match(migrationLines(s).join('\n'), /Manifest diff unavailable: No manifest/);
+});
+
+test('a network failure degrades the same way', async () => {
+  const s = await survey(BEFORE, null, {
+    load: async () => {
+      throw new TypeError('fetch failed');
+    },
+  });
+  assert.equal(s.state, MIGRATION_STATE.PENDING);
+  assert.match(s.notes[0], /fetch failed/);
+  assert.match(migrationLines(s).join('\n'), /rollout starts 2026-10-19 \(18 days\)/);
+});
+
+test('a tool on neither image is skipped, not diffed to nothing', async () => {
+  const s = await survey(BEFORE, null, { tools: [...TOOLS, 'Xcode'] });
+  assert.deepEqual(s.notOnManifest, ['Xcode'], 'Xcode is a macOS tool, absent from both');
+  assert.ok(!s.toolDiffs.some((d) => d.tool === 'Xcode'));
+});
+
+test('surveying a label with no migration is null, not an empty survey', async () => {
+  assert.equal(await survey(BEFORE, null, { label: 'windows-latest' }), null);
+  assert.equal(await survey(BEFORE, null, { label: 'ubuntu-24.04' }), null);
+});
+
+test('imageDiffs tolerates a manifest with no kernel or systemd line', () => {
+  const rows = imageDiffs({ osVersion: '15.6' }, { osVersion: '26.0' });
+  assert.equal(rows.length, 3);
+  assert.deepEqual(
+    rows.filter((d) => d.changed).map((d) => d.tool),
+    ['OS'],
+  );
+});
+
+/* ----------------------------------------------------------------- report */
+
+test('each state gets its own sentence, and the anomaly says so', async () => {
+  const sentence = (now, imageOS) =>
+    migrationLines({
+      ...migrationStatus('ubuntu-latest', { now, imageOS }),
+      sites: [],
+      image: [],
+      toolDiffs: [],
+      notOnManifest: [],
+      notes: [],
+    })[0];
+  assert.match(
+    sentence(BEFORE, null),
+    /moves from ubuntu-24\.04 to ubuntu-26\.04.*starts 2026-10-19 \(18 days\)/,
+  );
+  assert.match(sentence(DURING, 'ubuntu24'), /this runner served ubuntu-24\.04/);
+  assert.match(sentence(DURING, 'ubuntu26'), /has reached this runner/);
+  assert.match(sentence(DURING, null), /No ImageOS was observed/);
+  assert.match(sentence(AFTER, null), /finished migrating/);
+  assert.match(sentence(AFTER, 'ubuntu24'), /anomaly, not drift/);
+  assert.match(sentence(AFTER, 'ubuntu22'), /neither ubuntu-24\.04 nor ubuntu-26\.04/);
+});
+
+test('annotations land on the runs-on line and pick the right severity', async () => {
+  const sites = (await detect(WORKFLOWS)).floatingSites;
+  const at = async (now, imageOS) => migrationAnnotations([await survey(now, imageOS, { sites })])[0];
+
+  assert.match(await at(BEFORE, null), /^::notice file=[^,]*latest\.yml,line=6,col=14,/);
+  assert.match(
+    await at(BEFORE, null),
+    /title=runner-drift: ubuntu-latest becomes ubuntu-26\.04 in 18 days::/,
+  );
+  assert.match(await at(DURING, 'ubuntu24'), /^::warning file=/);
+  assert.match(await at(DURING, 'ubuntu26'), /^::notice file=/);
+  assert.match(await at(AFTER, 'ubuntu24'), /^::error file=/);
+  assert.match(
+    await at(AFTER, 'ubuntu24'),
+    /See https:\/\/github\.com\/actions\/runner-images\/issues\/14748/,
+  );
+});
+
+test('a survey with no site on disk still gets one step-level annotation', async () => {
+  const [line] = migrationAnnotations([await survey(BEFORE)]);
+  assert.ok(!line.includes('file='));
+  assert.match(line, /^::notice title=runner-drift: /);
+});
+
+test('the step summary names the window, the phase and the image diff', async () => {
+  const md = migrationSummaryMarkdown([await survey(BEFORE)]);
+  assert.match(md, /^## runner-drift — floating label migration/);
+  assert.match(md, /\| Label \| Phase \| Move \| Window \| This runner \| Source \|/);
+  assert.match(
+    md,
+    /\| `ubuntu-latest` \| 🗓 pending \| `ubuntu-24\.04` → `ubuntu-26\.04` \| 2026-10-19 \(18 days\) → 2026-11-19 \(49 days\) \| — \| \[actions\/runner-images#14748\]/,
+  );
+  assert.match(md, /\| Kernel \| 6\.17\.0-1022-azure \| 7\.0\.0-1012-azure \| 🔴 MAJOR \|/);
+});
+
+test('a floating label inside a matrix is a site like any other', () => {
+  const y = [
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-22.04, ubuntu-latest]',
+    '    runs-on: ${{ matrix.os }}',
+  ].join('\n');
+  assert.deepEqual(extractFloatingSites(y, 'ci.yml'), [
+    { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28 },
+  ]);
+});
+
+/* ------------------------------------------------------------------- plan */
+
+async function plan(opts, now = BEFORE) {
+  const cap = captureIO();
+  const code = await runPlan({ workflows: WORKFLOWS, ...opts }, cap.io, { loadManifest: LOAD, now });
+  return { code, stdout: cap.stdout, stderr: cap.stderr };
+}
+
+test('plan --from ubuntu-latest resolves the window and diffs the two images', async () => {
+  const r = await plan({ from: 'ubuntu-latest' });
+  assert.equal(r.code, EXIT_OK);
+  const lines = r.stdout.trimEnd().split('\n');
+  assert.equal(
+    lines[0],
+    'ubuntu-latest moves from ubuntu-24.04 to ubuntu-26.04. The rollout starts 2026-10-19 (18 days) and finishes 2026-11-19 (49 days).',
+  );
+  assert.equal(
+    lines[1],
+    'announced 2026-09-17; source actions/runner-images#14748 https://github.com/actions/runner-images/issues/14748',
+  );
+  assert.equal(lines[2], 'ubuntu-24.04 -> ubuntu-26.04 (images 20260907.300.1 -> 20260907.131.1)');
+  assert.ok(r.stdout.includes('Kernel 6.17.0-1022-azure -> 7.0.0-1012-azure  MAJOR'));
+  assert.ok(r.stdout.includes('Systemd 255.4-1ubuntu8.17 -> 259.5-0ubuntu3.4  MAJOR'));
+});
+
+test('an explicit --to still refuses a floating label, and says to drop it', async () => {
+  const r = await plan({ from: 'ubuntu-latest', to: 'ubuntu-26.04' });
+  assert.equal(r.code, EXIT_USAGE);
+  assert.match(r.stderr, /floating label/);
+  assert.match(r.stderr, /Or drop --to: runner-drift plan --from ubuntu-latest/);
+});
+
+test('a floating --to with no migration of its own gets no such hint', async () => {
+  const r = await plan({ from: 'ubuntu-24.04', to: 'windows-latest' });
+  assert.equal(r.code, EXIT_USAGE);
+  assert.match(r.stderr, /--to windows-latest is a floating label/);
+  assert.doesNotMatch(r.stderr, /Or drop --to/);
+});
+
+test('a floating label with no migration is still a usage error that says so', async () => {
+  const r = await plan({ from: 'windows-latest' });
+  assert.equal(r.code, EXIT_USAGE);
+  assert.match(r.stderr, /plan needs both --from <label> and --to <label>/);
+  assert.match(r.stderr, /need only --from: ubuntu-latest/);
+});
+
+test('plan --json carries the migration and the image diff', async () => {
+  const r = await plan({ from: 'ubuntu-latest', json: true });
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.from, 'ubuntu-24.04');
+  assert.equal(j.to, 'ubuntu-26.04');
+  assert.equal(j.migration.state, 'pending');
+  assert.equal(j.migration.daysToStart, 18);
+  assert.deepEqual(
+    j.image.map((d) => d.tool),
+    ['OS', 'Kernel', 'Systemd'],
+  );
+});
+
+/* ------------------------------------------------------------------ guard */
+
+async function guard(opts, env = {}, now = BEFORE) {
+  const cap = captureIO();
+  const code = await runGuard(
+    { summary: false, 'update-lock': true, workflows: WORKFLOWS, ...opts },
+    cap.io,
+    env,
+    { now, loadManifest: LOAD },
+  );
+  return { code, stdout: cap.stdout, stderr: cap.stderr };
+}
+
+test('guard is unchanged without the flag: no migration output at all', async () => {
+  const r = await guard({ tools: 'node' });
+  assert.equal(r.code, EXIT_OK);
+  assert.ok(!r.stdout.includes('ubuntu-latest'));
+  assert.equal(r.stderr, '');
+});
+
+test('guard --fail-on-migration reports the pending window and the diff', async () => {
+  const r = await guard({ tools: 'node', 'fail-on-migration': '30' });
+  assert.equal(r.code, EXIT_DRIFT);
+  assert.match(r.stdout, /^::notice file=.*latest\.yml,line=6,col=14,/m);
+  assert.match(r.stdout, /rollout starts 2026-10-19 \(18 days\)/);
+  assert.match(r.stdout, /Kernel 6\.17\.0-1022-azure -> 7\.0\.0-1012-azure/);
+  assert.match(r.stderr, /--fail-on-migration 30 is set\./);
+});
+
+test('below the threshold it reports and exits 0', async () => {
+  const r = await guard({ tools: 'node', 'fail-on-migration': '10' });
+  assert.equal(r.code, EXIT_OK);
+  assert.match(r.stdout, /rollout starts 2026-10-19/);
+  assert.equal(r.stderr, '');
+});
+
+test('a stale runner after the window fails whatever the threshold', async () => {
+  const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, { ImageOS: 'ubuntu24' }, AFTER);
+  assert.equal(r.code, EXIT_DRIFT);
+  assert.match(r.stdout, /^::error file=/m);
+  assert.match(r.stderr, /anomaly, not drift/);
+  assert.ok(!r.stderr.includes('--fail-on-migration 0 is set'), 'an anomaly is not a countdown');
+});
+
+test('a workflow with no floating label produces nothing and exits 0', async () => {
+  const r = await guard({
+    tools: 'node',
+    'fail-on-migration': '365',
+    workflows: path.join(FIXTURES, 'workflows'),
+  });
+  assert.equal(r.code, EXIT_OK);
+  assert.ok(!r.stdout.includes('ubuntu-latest'));
+  assert.equal(r.stderr, '');
+});
+
+test('a missing workflow directory is a notice, not an error', async () => {
+  const r = await guard({
+    tools: 'node',
+    'fail-on-migration': '30',
+    workflows: path.join(FIXTURES, 'definitely-not-here'),
+  });
+  assert.equal(r.code, EXIT_OK);
+  assert.match(r.stdout, /::notice title=runner-drift::No workflow directory/);
+  assert.match(r.stdout, /no floating labels to check for migration/);
+});
+
+test('a bad --fail-on-migration value is a usage error', async () => {
+  for (const bad of ['soon', '-5', '2.5', '']) {
+    const r = await guard({ tools: 'node', 'fail-on-migration': bad });
+    assert.equal(r.code, EXIT_USAGE, `"${bad}" rejected`);
+    assert.match(r.stderr, /--fail-on-migration needs a whole number of days >= 0/);
+  }
+});
+
+test('the migration ride-along appears in guard --json', async () => {
+  const r = await guard({ tools: 'node', 'fail-on-migration': '30', json: true });
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.equal(j.migration.days, 30);
+  assert.equal(j.migration.surveys.length, 1);
+  assert.equal(j.migration.surveys[0].state, 'pending');
+  assert.equal(j.migration.surveys[0].sites[0].line, 6);
+});
+
+/**
+ * Guard against a lock recorded on the pre-migration image, with the runner
+ * serving the post-migration one: the drift a real user sees mid-rollout.
+ */
+async function guardAcrossTheMove(opts, now, locked = { label: 'ubuntu-24.04', imageOS: 'ubuntu24' }) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'runner-drift-migration-'));
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const IMAGE = '20260907.131.1';
+  try {
+    await writeLock(
+      {
+        ...locked,
+        imageVersion: IMAGE,
+        tools: { 'Node.js': { versions: ['22.23.2'], source: 'probe' } },
+      },
+      lockFile,
+    );
+    return await guard(
+      { tools: 'node', 'lock-file': lockFile, 'update-lock': false, ...opts },
+      { ImageVersion: IMAGE, ImageOS: 'ubuntu26' },
+      now,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test('drift caused by the migration is named as such, not left unexplained', async () => {
+  const r = await guardAcrossTheMove({ 'fail-on-migration': '30' }, DURING);
+  assert.equal(r.code, EXIT_OK, 'a completed migration is not a failure');
+  assert.match(
+    r.stdout,
+    /Explained by the scheduled ubuntu-latest migration ubuntu-24\.04 -> ubuntu-26\.04/,
+  );
+  assert.match(r.stdout, /\(2026-10-19 to 2026-11-19\)/);
+  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /);
+  assert.equal(r.stderr, '');
+});
+
+test('the explanation needs no flag: the two labels alone identify the move', async () => {
+  const r = await guardAcrossTheMove({}, DURING);
+  assert.equal(r.code, EXIT_OK);
+  assert.match(
+    r.stdout,
+    /Explained by the scheduled ubuntu-latest migration ubuntu-24\.04 -> ubuntu-26\.04/,
+  );
+  // Without --fail-on-migration the lane itself stays quiet: no window, no diff.
+  assert.ok(!r.stdout.includes('rollout'), 'no migration report without the flag');
+  assert.equal(r.stderr, '');
+});
+
+test('a jump the migration table does not describe is left unexplained', async () => {
+  const r = await guardAcrossTheMove({}, DURING, {
+    label: 'ubuntu-22.04',
+    imageOS: 'ubuntu22',
+  });
+  assert.ok(!r.stdout.includes('Explained by'), 'no announced move goes 22.04 -> 26.04');
+});
+
+test('migrationBetween matches only the announced pair', async () => {
+  assert.equal(migrationBetween('ubuntu-24.04', 'ubuntu-26.04').label, 'ubuntu-latest');
+  assert.equal(migrationBetween('ubuntu-26.04', 'ubuntu-24.04'), null, 'not backwards');
+  assert.equal(migrationBetween('ubuntu-22.04', 'ubuntu-26.04'), null);
+});

From 0b11e4a872bce8c102d6366f83e4b13e8e1bfad8 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 10:19:00 +0800
Subject: [PATCH 02/44] guard --no-update-lock now writes nothing on the first
 run either

Found reviewing 1.4.0: with no lock file yet, the baseline branch wrote one
regardless of the flag, so a lint job that asked for a report got a file to
decide whether to commit. The README already said the flag leaves the lock
untouched.

writeLock's normalising body becomes lockPayload so the no-write path can report
the same shape in --json, which gains a `written` boolean beside `baseline`. The
DriftError message-plus-hint line was written out three times; it is errorText in
http.mjs now.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md        |  8 ++++++++
 src/cli.mjs         | 24 +++++++++++++++---------
 src/http.mjs        |  6 ++++++
 src/index.mjs       |  4 ++--
 src/lock.mjs        |  9 +++++++--
 src/migration.mjs   |  6 ++----
 test/guard.test.mjs | 14 ++++++++++++++
 7 files changed, 54 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 639ca51..544cfb6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -87,6 +87,14 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   the public surface is unchanged. The migration lane needed it and importing it
   from the CLI would have made a cycle.
 
+### Fixed
+
+- `guard --no-update-lock` wrote the lock file anyway on the very first run, when
+  there was nothing to update yet. The README said the flag leaves the lock file
+  untouched, so a lint job that asked for a report got a file to decide about.
+  It now writes nothing, says so, and still reports the baseline it observed;
+  `--json` gained a `written` boolean beside `baseline`.
+
 [1.4.0]: https://github.com/Booyaka101/runner-drift/releases/tag/v1.4.0
 
 ## [1.3.0] — 2026-09-13
diff --git a/src/cli.mjs b/src/cli.mjs
index 7212c7c..f667985 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -9,7 +9,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { DriftError } from './http.mjs';
+import { DriftError, errorText } from './http.mjs';
 import {
   IMAGE_OS_TO_LABEL,
   deadlineFor,
@@ -29,7 +29,7 @@ import { detect, SELF_HOSTED } from './detect.mjs';
 import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
-import { readLock, writeLock, DEFAULT_LOCK_FILE, toolsEntry, toVersionMap } from './lock.mjs';
+import { readLock, writeLock, lockPayload, DEFAULT_LOCK_FILE, toolsEntry, toVersionMap } from './lock.mjs';
 import {
   planReport,
   stepSummaryMarkdown,
@@ -647,7 +647,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         manifest = m.skipped ? null : m;
       }
     } catch (err) {
-      infraWarnings.push(err instanceof DriftError ? `${err.message}${err.hint ? ` ${err.hint}` : ''}` : String(err));
+      infraWarnings.push(errorText(err));
     }
     if (manifest) {
       const { map, missing } = resolveManifestVersions(manifest, needManifest);
@@ -668,10 +668,10 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
 
   // First run: record the baseline and stop.
   if (!lock) {
-    const written = await writeLock(
-      { label, imageOS, imageVersion, tools: observed, updatedAt: new Date().toISOString() },
-      lockFile,
-    );
+    const baseline = { label, imageOS, imageVersion, tools: observed, updatedAt: new Date().toISOString() };
+    // --no-update-lock covers the first run too. A job that asked for a report
+    // and got a file it then has to decide whether to commit is a surprise.
+    const written = opts['update-lock'] ? await writeLock(baseline, lockFile) : lockPayload(baseline);
     const summary = stepSummaryMarkdown({
       label,
       toImage: imageVersion,
@@ -686,6 +686,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         JSON.stringify(
           {
             baseline: true,
+            written: opts['update-lock'],
             lock: written,
             ...(retirement ? { retirement } : {}),
             ...(migration ? { migration } : {}),
@@ -699,7 +700,12 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       for (const n of probeNotes) out(io.stdout, `  ${n}`);
       const manifestOnly = Object.entries(observed).filter(([, v]) => v.source === 'manifest');
       for (const [t, v] of manifestOnly) out(io.stdout, `  ${t}: ${v.versions.join(', ')} (from manifest)`);
-      out(io.stdout, `Wrote ${lockFile}. Commit it so the next image bump can be diffed.`);
+      out(
+        io.stdout,
+        opts['update-lock']
+          ? `Wrote ${lockFile}. Commit it so the next image bump can be diffed.`
+          : `Nothing written: --no-update-lock is set. Drop it to record ${lockFile} as the baseline.`,
+      );
     }
     if (retiring) reportRetirement(io, retiring);
     if (migrating) reportMigration(io, migrating);
@@ -739,7 +745,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         });
       }
     } catch (err) {
-      const msg = err instanceof DriftError ? `${err.message}${err.hint ? ` ${err.hint}` : ''}` : String(err);
+      const msg = errorText(err);
       out(io.stdout, `::warning title=runner-drift::Attribution unavailable — ${msg}`);
     }
   }
diff --git a/src/http.mjs b/src/http.mjs
index 208b633..816d7df 100644
--- a/src/http.mjs
+++ b/src/http.mjs
@@ -16,6 +16,12 @@ export class DriftError extends Error {
   }
 }
 
+/** One line for a caught failure: a DriftError's hint belongs with its message. */
+export function errorText(err) {
+  if (!(err instanceof DriftError)) return String(err);
+  return err.hint ? `${err.message} ${err.hint}` : err.message;
+}
+
 export class NotFoundError extends DriftError {
   constructor(message) {
     super(message, { code: 'NOT_FOUND' });
diff --git a/src/index.mjs b/src/index.mjs
index 5066629..9f27a84 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -29,7 +29,7 @@ export {
 } from './detect.mjs';
 export { probeTool, probeTools, isProbeable, PROBES } from './probe.mjs';
 export { diffTool, diffToolMaps, shouldFail, maxSeverity, severityBetween, compareVersions, compareDottedNumbers } from './diff.mjs';
-export { readLock, writeLock, emptyLock, toVersionMap, SCHEMA_VERSION, DEFAULT_LOCK_FILE } from './lock.mjs';
+export { readLock, writeLock, lockPayload, emptyLock, toVersionMap, SCHEMA_VERSION, DEFAULT_LOCK_FILE } from './lock.mjs';
 export {
   planReport,
   stepSummaryMarkdown,
@@ -125,4 +125,4 @@ export {
 } from './labels.mjs';
 export { MS_PER_DAY, daysFromMs, isPast } from './dates.mjs';
 export { COMMAND_ALIASES, MANIFEST_CANDIDATES, canonicalTool, knownTools } from './tools.mjs';
-export { DriftError, NotFoundError } from './http.mjs';
+export { DriftError, NotFoundError, errorText } from './http.mjs';
diff --git a/src/lock.mjs b/src/lock.mjs
index 988dee0..2c7c65a 100644
--- a/src/lock.mjs
+++ b/src/lock.mjs
@@ -60,8 +60,9 @@ export async function readLock(file = DEFAULT_LOCK_FILE) {
   return json;
 }
 
-export async function writeLock(lock, file = DEFAULT_LOCK_FILE) {
-  const out = {
+/** The lock file's on-disk shape, built without writing it. */
+export function lockPayload(lock) {
+  return {
     schemaVersion: SCHEMA_VERSION,
     label: lock.label ?? null,
     imageOS: lock.imageOS ?? null,
@@ -69,6 +70,10 @@ export async function writeLock(lock, file = DEFAULT_LOCK_FILE) {
     tools: lock.tools ?? {},
     updatedAt: lock.updatedAt ?? new Date().toISOString(),
   };
+}
+
+export async function writeLock(lock, file = DEFAULT_LOCK_FILE) {
+  const out = lockPayload(lock);
   try {
     await writeFile(file, `${JSON.stringify(out, null, 2)}\n`, 'utf8');
   } catch (err) {
diff --git a/src/migration.mjs b/src/migration.mjs
index 5af6d0e..5ceb387 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -14,7 +14,7 @@
 import { migrationStatus } from './labels.mjs';
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
-import { DriftError } from './http.mjs';
+import { errorText } from './http.mjs';
 
 /**
  * Image-level facts that are not installed tools but change with the OS. They
@@ -80,9 +80,7 @@ export async function surveyMigration({
   try {
     [a, b] = await Promise.all([load(status.from), load(status.to)]);
   } catch (err) {
-    survey.notes.push(
-      err instanceof DriftError ? `${err.message}${err.hint ? ` ${err.hint}` : ''}` : String(err),
-    );
+    survey.notes.push(errorText(err));
     return survey;
   }
   for (const m of [a, b]) {
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index abf5038..47b1ca1 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -219,6 +219,20 @@ test('without --fail-on-retirement, retiring labels change nothing', async () =>
   }
 });
 
+test('--no-update-lock writes no lock on the first run either', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  try {
+    const r = await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false });
+    assert.equal(r.code, EXIT_OK);
+    assert.match(r.stdout, /baseline recorded/);
+    assert.match(r.stdout, /Nothing written: --no-update-lock is set/);
+    await assert.rejects(() => readFile(lockFile, 'utf8'), /ENOENT/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('--no-update-lock leaves the lock alone', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');

From 6c5c98a1a542fe764f63076daec77a235c3e6963 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 11:07:59 +0800
Subject: [PATCH 03/44] Attribute ImageOS to the job that asked for the label

guard read the runner's ImageOS as evidence about every floating label in the
repo. A lint step pinned to ubuntu-22.04 therefore reported ubuntu-latest as
serving an unrecognised image: an anomaly, which fails whatever the threshold.

Label sites now carry the job they belong to, and GITHUB_JOB plus
GITHUB_WORKFLOW_REF say which job this runner is serving. A matrix leg, or a run
with no GITHUB_JOB, still attributes the two images the window names, since
those are evidence the runner did come from the floating label.

The "Explained by the scheduled migration" line is gated the same way, so a
hand-bumped pin from ubuntu-24.04 to ubuntu-26.04 is no longer credited to
GitHub.

Countdowns are whole calendar days from today rather than rounded hours, so the
printed date and the number beside it agree: some runners countdowns move by one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                 |  23 ++++-
 README.md                                    |  29 ++++--
 src/cli.mjs                                  |  48 ++++++---
 src/dates.mjs                                |  12 ++-
 src/detect.mjs                               |  72 +++++++++++--
 src/index.mjs                                |   4 +-
 src/migration.mjs                            |  49 ++++++++-
 src/report.mjs                               |   4 +-
 test/detect.test.mjs                         |  14 +--
 test/fixtures/workflows-migration/latest.yml |   5 +
 test/migration.test.mjs                      | 103 ++++++++++++++++++-
 test/runners.test.mjs                        |  24 ++---
 12 files changed, 324 insertions(+), 63 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 544cfb6..f983f3b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,10 +57,22 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   The anomaly fails whatever the threshold, the same rule a label already past
   its retirement date follows.
 
+  `ImageOS` describes one runner, and that runner is serving one job, so it is
+  read as evidence about a floating label only when the job it is running asked
+  for that label: `GITHUB_JOB` and `GITHUB_WORKFLOW_REF` say which job, and the
+  scan already knows which job each `runs-on:` belongs to. A lint step pinned to
+  `ubuntu-22.04` in a repo that uses `ubuntu-latest` elsewhere reports the window
+  from the calendar alone and says why, instead of announcing that
+  `ubuntu-latest` has gone somewhere unrecognised. Where the label is reached
+  through a matrix, or the check runs with no `GITHUB_JOB` at all, the image is
+  still attributed if it is one of the two the window names.
+
   When the observed image explains the tool drift `guard` just found, the report
   says so, rather than leaving a page of major bumps looking unexplained. That
-  line needs no input: a lock recorded on one side of an announced move and a
-  runner on the other is a table lookup, not a check to opt into.
+  line needs no input, only the job that was actually moved: a lock recorded on
+  one side of an announced move, a runner on the other, and a workflow that asked
+  for the floating label. A repo that bumps a pinned `ubuntu-24.04` to
+  `ubuntu-26.04` by hand is not told GitHub did it.
 
   ```
   Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04 (2026-10-19 to 2026-11-19); the tool versions below moved with the image.
@@ -82,6 +94,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
+- Every countdown is now whole calendar days from today, not hours divided by 24
+  and rounded. A deadline dated 2026-11-19 reads "0 days" for the whole of the
+  19th rather than flipping to "1 day ago" at midday, and the printed date and
+  the number beside it can no longer disagree. Some `runners` countdowns move by
+  a day: `2.335.1 runtime ends 2026-09-24` was "(16 days)" on 2026-09-09 and is
+  now "(15 days)", which is the number of days you can actually still run it.
+
 - `resolveManifestVersions` moved from `src/cli.mjs` to `src/manifest.mjs`, where
   the rest of the manifest reading lives, and is re-exported from `cli.mjs` so
   the public surface is unchanged. The migration lane needed it and importing it
diff --git a/README.md b/README.md
index ea9d709..a15b8cd 100644
--- a/README.md
+++ b/README.md
@@ -266,7 +266,7 @@ window, and on the `ImageOS` the runner exported:
 | Before the window | — | `::notice`, the window and the countdown |
 | In the window | the old image | `::warning`, this runner has not moved yet and the diff is still ahead of you |
 | In the window | the new image | `::notice`, the migration has reached this runner |
-| In the window | absent | `::warning`, which of the two this job got cannot be told |
+| In the window | absent, or from another job | `::warning`, which of the two this job got cannot be told |
 | After the window | the new image | `::notice`, the move is done |
 | After the window | the old image | `::error`, an anomaly rather than drift |
 
@@ -274,9 +274,22 @@ The last row is the one worth having. A runner still serving Ubuntu 24.04 in
 December, when the label is supposed to mean 26.04 everywhere, is not a version
 bump you should record in the lock file.
 
-One part of this needs no input at all. When `guard` finds real tool drift and the
-jump from the lock's image to the runner's image is exactly an announced move, it
-says so, because that is a table lookup rather than a check you have to opt into:
+`ImageOS` describes the runner the step is on, and that runner is serving one
+job, so it counts as evidence about `ubuntu-latest` only when that job asked for
+`ubuntu-latest`. The step above did. A lint job pinned to `ubuntu-22.04` in the
+same repo gets the window from the calendar and a line saying its own image was
+not treated as evidence, rather than a claim that `ubuntu-latest` has gone
+somewhere unrecognised. `GITHUB_JOB` and `GITHUB_WORKFLOW_REF` are what tie the
+runner to a `runs-on:` line, and Actions sets both for you. Where the label is
+reached through a matrix, or the command runs with no `GITHUB_JOB` at all, the
+image is still attributed if it is one of the two the window names.
+
+One part of this needs no input at all. When `guard` finds real tool drift, the
+jump from the lock's image to the runner's image is exactly an announced move,
+and the job was scheduled from the floating label, it says so, because that is a
+table lookup rather than a check you have to opt into. Bump a pinned label from
+`ubuntu-24.04` to `ubuntu-26.04` yourself and you get the drift report without
+the explanation, which is the honest answer: that upgrade was yours.
 
 ```
 ubuntu-26.04 image 20260907.300.1 -> 20260907.131.1
@@ -319,7 +332,7 @@ live API returned that day, and they will have moved since:
 $ runner-drift runners --org acme --fail-on-deprecation 30
 self-hosted runners — acme (3 runners, 2 versions)
   RUNTIME-DUE   2.335.1  x2  arc-linux-1, arc-linux-2
-                runtime support ends 2026-09-24 (16 days) — jobs stop being queued
+                runtime support ends 2026-09-24 (15 days) — jobs stop being queued
                 update to 2.337.0, published 2026-08-26 — the newest stable actions/runner release
                 ephemeral runners — change the actions-runner-controller image tag, not the host
   OK            2.337.0  x1  build-mac-1  (published 2026-08-26)
@@ -328,7 +341,7 @@ note: self-hosted runners auto-update by default — at risk are the ones regist
 note: enforcement covers github.com and GitHub Enterprise Cloud, not GitHub Enterprise Server
 source: GET /orgs/acme/actions/runners/deprecations/2.335.1
 source: GET /orgs/acme/actions/runners/deprecations/2.337.0
-runner-drift: 2 self-hosted runner(s) on 2.335.1 lose runtime support on 2026-09-24 (16 days) and --fail-on-deprecation 30 is set.
+runner-drift: 2 self-hosted runner(s) on 2.335.1 lose runtime support on 2026-09-24 (15 days) and --fail-on-deprecation 30 is set.
 ```
 
 That last line goes to stderr and the run exits 1, with an `::error` annotation
@@ -381,7 +394,7 @@ happens to sit next to a GPU box on the same version.
 
 ```
   RUNTIME-DUE   2.335.1  x2  arc-linux-1, arc-linux-2
-                runtime support ends 2026-09-24 (16 days) — jobs stop being queued
+                runtime support ends 2026-09-24 (15 days) — jobs stop being queued
                 update to 2.337.0, published 2026-08-26 — the newest stable actions/runner release
                 serves .github/workflows/bench.yml:9 (runs-on: self-hosted, linux, gpu) — arc-linux-1, arc-linux-2
                 ephemeral runners — change the actions-runner-controller image tag, not the host
@@ -630,7 +643,7 @@ refusal `groups` is empty and `message` / `hint` carry the reason; on success
       "ephemeral": true,
       "labels": ["self-hosted", "Linux", "X64", "gpu"],
       "status": "RUNTIME-DUE",
-      "runtime": { "at": "2026-09-24T15:30:55Z", "date": "2026-09-24", "days": 16, "past": false },
+      "runtime": { "at": "2026-09-24T15:30:55Z", "date": "2026-09-24", "days": 15, "past": false },
       "registration": null,
       "unknownVersion": false,
       "unparsedDates": [],
diff --git a/src/cli.mjs b/src/cli.mjs
index f667985..69087fd 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -25,7 +25,7 @@ import {
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { imageDiffs, surveyMigration } from './migration.mjs';
 import { attribute, commitWindow, attributeChanges, listManifestCommits, manifestAtSha } from './history.mjs';
-import { detect, SELF_HOSTED } from './detect.mjs';
+import { detect, runningJob, siteInJob, SELF_HOSTED } from './detect.mjs';
 import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
@@ -283,7 +283,7 @@ function reportRetirement(io, { days, findings }) {
  * images it names. Opt-in like the retirement gate, and like it, useful in a
  * plain lint job with no runner and no lock file.
  */
-async function checkMigration(opts, io, now, imageOS, deps) {
+async function checkMigration(opts, io, now, imageOS, env, deps) {
   const days = wholeDays(opts['fail-on-migration'], '--fail-on-migration', io);
   if (days === null) return null;
   const scanned = await scanForLane(opts, io, 'no floating labels to check for migration');
@@ -297,9 +297,10 @@ async function checkMigration(opts, io, now, imageOS, deps) {
   }
   const tools = parseToolList(opts.tools) ?? scanned.tools;
   const load = deps.loadManifest ?? loadManifest;
+  const here = runningJob(env);
   const surveys = await Promise.all(
     [...byLabel].map(([label, sites]) =>
-      surveyMigration({ label, now, imageOS, tools, sites, load }),
+      surveyMigration({ label, now, imageOS, tools, sites, here, load }),
     ),
   );
 
@@ -310,6 +311,35 @@ async function checkMigration(opts, io, now, imageOS, deps) {
   return { days, surveys };
 }
 
+/**
+ * The announced migration that explains a lock-to-runner jump, or null.
+ *
+ * Only a job scheduled from the floating label can have been moved by the
+ * window: a repo that pins its runner and bumps the pin by hand did its own
+ * upgrade, and being told GitHub did it is worse than being told nothing. With
+ * no `GITHUB_JOB` to match on, the label appearing anywhere in the workflows is
+ * taken as enough.
+ *
+ * The scan only happens for a jump the table already recognises, which is rare,
+ * so the common path still reads no workflow files it did not need.
+ */
+async function explainDrift({ migration, lock, label, opts, env }) {
+  const survey = migration?.surveys.find(
+    (s) => s.done && s.observed === s.to && lock.label === s.from && label === s.to,
+  );
+  if (survey) return survey;
+
+  const m = migrationBetween(lock.label, label);
+  if (!m) return null;
+  const sites = migration
+    ? migration.surveys.flatMap((s) => s.sites)
+    : (await detect(opts.workflows ?? path.join('.github', 'workflows'))).floatingSites;
+  const ours = sites.filter((site) => site.label === m.label);
+  const here = runningJob(env);
+  const used = here ? ours.some((site) => siteInJob(site, here)) : ours.length > 0;
+  return used ? m : null;
+}
+
 /** One stderr line per floating label whose migration fails the gate. */
 function reportMigration(io, { days, surveys }) {
   summarise(
@@ -539,7 +569,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // two images right now" and "this job ran on the new one".
   let migration = null;
   if (opts['fail-on-migration'] !== undefined) {
-    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, deps);
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, deps);
     if (!migration) return EXIT_USAGE;
     if (!opts.json && migration.surveys.length) {
       out(io.stdout, migrationReport(migration.surveys));
@@ -750,15 +780,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     }
   }
 
-  // Not unexplained drift: the lock was taken on the image the window moves
-  // away from, and this runner served the one it moves to. The table lookup is
-  // the fallback for a run without --fail-on-migration, where the lane never
-  // built a survey. The exit code is still --fail-on's to decide; this only
-  // names the cause.
-  const explained =
-    migration?.surveys.find(
-      (s) => s.done && s.observed === s.to && lock.label === s.from && label === s.to,
-    ) ?? migrationBetween(lock.label, label);
+  const explained = await explainDrift({ migration, lock, label, opts, env });
 
   const summary = stepSummaryMarkdown({
     label,
diff --git a/src/dates.mjs b/src/dates.mjs
index 72fd329..c0d83cb 100644
--- a/src/dates.mjs
+++ b/src/dates.mjs
@@ -21,10 +21,18 @@ export function daysUntil(date, now = new Date()) {
   return daysFromMs(Date.parse(normalise(date)), now);
 }
 
-/** The same rounding, for a timestamp already in milliseconds. */
+/**
+ * The same count, for a timestamp already in milliseconds.
+ *
+ * Counted from the start of `now`'s UTC day, so a deadline dated 2026-11-19 is
+ * "0 days" for the whole of the 19th rather than flipping to "1 day ago" at
+ * midday. GitHub announces calendar dates; a countdown that changes at noon
+ * both reads as a bug and moves a window boundary half a day early.
+ */
 export function daysFromMs(target, now = new Date()) {
   if (!Number.isFinite(target)) return null;
-  return Math.round((target - now.getTime()) / MS_PER_DAY);
+  const today = Math.floor(now.getTime() / MS_PER_DAY) * MS_PER_DAY;
+  return Math.floor((target - today) / MS_PER_DAY);
 }
 
 /** True when the date is strictly in the past. Never rounded: a boundary matters. */
diff --git a/src/detect.mjs b/src/detect.mjs
index 2c142fc..9e37a90 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -223,22 +223,62 @@ export function extractLabels(text) {
 }
 
 /**
- * Where each `runs-on` label sits: `{label, file, line, col}` per occurrence,
- * 1-indexed, `col` on the label text so a `file=,line=,col=` annotation lands
- * on it. `keep` decides which labels are worth a site, because the two lanes
- * that want one want disjoint halves of the same walk.
+ * The job id every line belongs to, 0-indexed to match `lines`.
+ *
+ * `guard` reads one runner's image, and that image says something about a label
+ * only if the job it is running asked for that label. The job id is the one
+ * thing in the file that ties a `runs-on:` to the `GITHUB_JOB` a runner exports.
+ */
+function jobKeys(lines) {
+  const at = new Array(lines.length).fill(null);
+  let jobsIndent = null;
+  let jobIndent = null;
+  let current = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^([ \t]*)([^-\s#][^:\r\n]*):/);
+    if (m) {
+      const indent = m[1].length;
+      const key = m[2].trim();
+      if (jobsIndent === null) {
+        if (key === 'jobs') jobsIndent = indent;
+      } else if (indent <= jobsIndent) {
+        current = null;
+      } else if (jobIndent === null || indent === jobIndent) {
+        jobIndent = indent;
+        current = key;
+      }
+    }
+    at[i] = current;
+  }
+  return at;
+}
+
+/**
+ * Where each `runs-on` label sits: `{label, file, line, col, job}` per
+ * occurrence, 1-indexed, `col` on the label text so a `file=,line=,col=`
+ * annotation lands on it. `keep` decides which labels are worth a site, because
+ * the two lanes that want one want disjoint halves of the same walk.
+ *
+ * `viaMatrix` marks a label read out of a matrix rather than off a `runs-on:`
+ * line. Its job is right, but which leg of the matrix any one runner is serving
+ * is not written anywhere in the file.
  */
 function labelSitesWhere(text, file, keep) {
   const lines = String(text ?? '').split(/\r?\n/);
   const { found, expression } = scanRunsOn(lines);
+  const jobs = jobKeys(lines);
   const seen = new Set();
   const sites = [];
-  for (const { label, line, col } of expression ? [...found, ...matrixLabels(lines)] : found) {
+  const all = expression
+    ? [...found, ...matrixLabels(lines).map((m) => ({ ...m, viaMatrix: true }))]
+    : found;
+  for (const { label, line, col, viaMatrix } of all) {
     if (!keep(label)) continue;
     const key = `${label}@${line}:${col}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    sites.push({ label, file, line, col });
+    const site = { label, file, line, col, job: jobs[line - 1] ?? null };
+    sites.push(viaMatrix ? { ...site, viaMatrix } : site);
   }
   return sites;
 }
@@ -253,6 +293,26 @@ export function extractFloatingSites(text, file = null) {
   return labelSitesWhere(text, file, isFloating);
 }
 
+/**
+ * The workflow file and job id of the job this process is running in, or null
+ * outside Actions. `GITHUB_WORKFLOW_REF` is
+ * `owner/repo/.github/workflows/ci.yml@refs/heads/main`; only the file name is
+ * kept, since the scan may have been pointed at a copy of the directory.
+ */
+export function runningJob(env = process.env) {
+  const job = env.GITHUB_JOB || null;
+  if (!job) return null;
+  const ref = env.GITHUB_WORKFLOW_REF || '';
+  return { job, file: ref ? path.basename(ref.split('@')[0]) : null };
+}
+
+/** Is this `runs-on:` site the one the running job was scheduled from? */
+export function siteInJob(site, here) {
+  if (!here || !site?.job || site.job !== here.job) return false;
+  if (!here.file || !site.file) return true;
+  return path.basename(site.file).toLowerCase() === here.file.toLowerCase();
+}
+
 /**
  * One entry per `runs-on:`, with its label SET intact: `{labels, file, line, col}`.
  *
diff --git a/src/index.mjs b/src/index.mjs
index 9f27a84..df61408 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -2,7 +2,7 @@
 
 export { main, runInit, runGuard, runPlan, runRunners, runActions, resolveManifestVersions, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from './cli.mjs';
 export { parseManifest, loadManifest, manifestUrl, lookupTool } from './manifest.mjs';
-export { IMAGE_FIELDS, imageDiffs, surveyMigration } from './migration.mjs';
+export { IMAGE_FIELDS, attributeImageOS, imageDiffs, surveyMigration } from './migration.mjs';
 export {
   listManifestCommits,
   findCommitForImageVersion,
@@ -20,6 +20,8 @@ export {
   extractLabelSites,
   extractFloatingSites,
   extractRunsOnTargets,
+  runningJob,
+  siteInJob,
   extractRunScripts,
   extractUses,
   setupTools,
diff --git a/src/migration.mjs b/src/migration.mjs
index 5ceb387..dff285b 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -11,7 +11,8 @@
  * and Node.js 22 -> 24" is something you can act on before it happens.
  */
 
-import { migrationStatus } from './labels.mjs';
+import { IMAGE_OS_TO_LABEL, migrationFor, migrationStatus } from './labels.mjs';
+import { siteInJob } from './detect.mjs';
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
 import { errorText } from './http.mjs';
@@ -37,6 +38,42 @@ export function imageDiffs(from, to) {
   return IMAGE_FIELDS.map(([name, field]) => diffTool(name, one(from?.[field]), one(to?.[field])));
 }
 
+/**
+ * Whether this runner's `ImageOS` says anything about this label, and why not.
+ *
+ * One runner serves one job. Its image is evidence about `ubuntu-latest` only if
+ * the job it is running asked for `ubuntu-latest`; a lint job pinned to
+ * `ubuntu-22.04` that happens to scan a repo using the floating label would
+ * otherwise report the whole migration as having gone somewhere unexpected.
+ *
+ * Two weaker cases attribute anyway, but only when the image is one of the two
+ * the window names, which is evidence the runner did come from this label: a
+ * matrix leg (the file cannot say which leg this runner is), and a run with no
+ * `GITHUB_JOB` to match against (`guard` invoked outside a workflow job).
+ */
+export function attributeImageOS({ label, imageOS, sites = [], here = null }) {
+  if (!imageOS) return { imageOS: null, note: null };
+  const m = migrationFor(label);
+  const observed = IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null;
+  const endpoint = observed === m?.from || observed === m?.to;
+  const mine = sites.filter((site) => siteInJob(site, here));
+
+  if (mine.some((site) => !site.viaMatrix)) return { imageOS, note: null };
+  if (endpoint) return { imageOS, note: null };
+  if (mine.length) {
+    return {
+      imageOS: null,
+      note: `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
+        + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
+    };
+  }
+  const who = here ? `The job that ran this check ("${here.job}")` : 'This check';
+  return {
+    imageOS: null,
+    note: `${who} did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+  };
+}
+
 /**
  * One floating label, classified and (where it helps) diffed.
  *
@@ -56,9 +93,11 @@ export async function surveyMigration({
   imageOS = null,
   tools = [],
   sites = [],
+  here = null,
   load = loadManifest,
 } = {}) {
-  const status = migrationStatus(label, { now, imageOS });
+  const attributed = attributeImageOS({ label, imageOS, sites, here });
+  const status = migrationStatus(label, { now, imageOS: attributed.imageOS });
   if (!status) return null;
 
   const survey = {
@@ -68,7 +107,7 @@ export async function surveyMigration({
     image: [],
     toolDiffs: [],
     notOnManifest: [],
-    notes: [],
+    notes: attributed.note ? [attributed.note] : [],
   };
 
   // Once the label already means `to`, the lock diff in `guard` is the real
@@ -80,11 +119,11 @@ export async function surveyMigration({
   try {
     [a, b] = await Promise.all([load(status.from), load(status.to)]);
   } catch (err) {
-    survey.notes.push(errorText(err));
+    survey.notes.push(`Manifest diff unavailable: ${errorText(err)}`);
     return survey;
   }
   for (const m of [a, b]) {
-    if (m.skipped) survey.notes.push(m.reason);
+    if (m.skipped) survey.notes.push(`Manifest diff unavailable: ${m.reason}`);
   }
   if (a.skipped || b.skipped) return survey;
 
diff --git a/src/report.mjs b/src/report.mjs
index 54638a3..f130efe 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -358,7 +358,7 @@ const MIGRATION_SENTENCE = {
   [MIGRATION_STATE.MIGRATED]: (s) =>
     `The scheduled ${s.label} migration has reached this runner: ${s.from} -> ${s.to}, rollout ${s.starts} to ${s.ends}.`,
   [MIGRATION_STATE.AMBIGUOUS]: (s) =>
-    `${s.label} is mid-rollout from ${s.from} to ${s.to}, finishing ${dateWithCountdown(s.ends, s.daysToEnd)}. No ImageOS was observed, so which of the two this job ran on is unknown.`,
+    `${s.label} is mid-rollout from ${s.from} to ${s.to}, finishing ${dateWithCountdown(s.ends, s.daysToEnd)}. Which of the two this job ran on is not known here.`,
   [MIGRATION_STATE.SETTLED]: (s) =>
     `${s.label} finished migrating from ${s.from} to ${s.to} on ${dateWithCountdown(s.ends, s.daysToEnd)}; it now means ${s.to}.`,
   [MIGRATION_STATE.STALE]: (s) =>
@@ -422,7 +422,7 @@ export function migrationLines(survey) {
   if (survey.notOnManifest.length) {
     lines.push(`Not listed on either image manifest (skipped): ${survey.notOnManifest.join(', ')}`);
   }
-  for (const n of survey.notes) lines.push(`Manifest diff unavailable: ${n}`);
+  for (const n of survey.notes) lines.push(n);
   return lines;
 }
 
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 9398736..33f8b3e 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -122,25 +122,25 @@ test('an empty or non-workflow document yields nothing', () => {
 
 test('labelSites: an inline scalar points at the label text, 1-indexed', () => {
   const sites = extractLabelSites('jobs:\n  a:\n    runs-on: ubuntu-22.04\n');
-  assert.deepEqual(sites, [{ label: 'ubuntu-22.04', file: null, line: 3, col: 14 }]);
+  assert.deepEqual(sites, [{ label: 'ubuntu-22.04', file: null, line: 3, col: 14, job: 'a' }]);
 });
 
 test('labelSites: a quoted scalar points inside the quotes', () => {
   const sites = extractLabelSites("jobs:\n  a:\n    runs-on: 'macos-14'\n");
-  assert.deepEqual(sites, [{ label: 'macos-14', file: null, line: 3, col: 15 }]);
+  assert.deepEqual(sites, [{ label: 'macos-14', file: null, line: 3, col: 15, job: 'a' }]);
 });
 
 test('labelSites: flow-sequence items get their own columns, self-hosted none', () => {
   const sites = extractLabelSites('    runs-on: [self-hosted, linux, x64]\n');
   assert.deepEqual(sites, [
-    { label: 'linux', file: null, line: 1, col: 28 },
-    { label: 'x64', file: null, line: 1, col: 35 },
+    { label: 'linux', file: null, line: 1, col: 28, job: null },
+    { label: 'x64', file: null, line: 1, col: 35, job: null },
   ]);
 });
 
 test('labelSites: block-sequence items carry their own line and column', () => {
   const y = 'jobs:\n  a:\n    runs-on:\n      - self-hosted\n      - macos-14\n    steps: []\n';
-  assert.deepEqual(extractLabelSites(y), [{ label: 'macos-14', file: null, line: 5, col: 9 }]);
+  assert.deepEqual(extractLabelSites(y), [{ label: 'macos-14', file: null, line: 5, col: 9, job: 'a' }]);
 });
 
 test('labelSites: ${{ matrix.os }} resolves to the matrix value positions', () => {
@@ -153,8 +153,8 @@ test('labelSites: ${{ matrix.os }} resolves to the matrix value positions', () =
     '    runs-on: ${{ matrix.os }}',
   ].join('\n');
   assert.deepEqual(extractLabelSites(y), [
-    { label: 'ubuntu-22.04', file: null, line: 5, col: 14 },
-    { label: 'macos-14', file: null, line: 5, col: 28 },
+    { label: 'ubuntu-22.04', file: null, line: 5, col: 14, job: 'a', viaMatrix: true },
+    { label: 'macos-14', file: null, line: 5, col: 28, job: 'a', viaMatrix: true },
   ]);
 });
 
diff --git a/test/fixtures/workflows-migration/latest.yml b/test/fixtures/workflows-migration/latest.yml
index f8c5502..c096fc6 100644
--- a/test/fixtures/workflows-migration/latest.yml
+++ b/test/fixtures/workflows-migration/latest.yml
@@ -16,3 +16,8 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - run: node --version
+
+  lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - run: echo lint
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 35b1a85..e8b6ab3 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -12,7 +12,7 @@ import {
   migrationFor,
   migrationStatus,
 } from '../src/labels.mjs';
-import { imageDiffs, surveyMigration } from '../src/migration.mjs';
+import { attributeImageOS, imageDiffs, surveyMigration } from '../src/migration.mjs';
 import { migrationAnnotations, migrationLines, migrationSummaryMarkdown } from '../src/report.mjs';
 import { detect, extractFloatingSites } from '../src/detect.mjs';
 import { writeLock } from '../src/lock.mjs';
@@ -175,6 +175,17 @@ test('the window boundaries belong to the window', () => {
   assert.equal(on('2026-11-20'), MIGRATION_PHASE.SETTLED);
 });
 
+test('the phase holds all day, at every hour of a boundary date', () => {
+  for (const hour of ['00:00', '11:59', '12:00', '13:00', '23:59']) {
+    const at = (d) => migrationStatus('ubuntu-latest', { now: new Date(`${d}T${hour}:00Z`) });
+    assert.equal(at('2026-10-18').phase, MIGRATION_PHASE.PENDING, `2026-10-18 ${hour}`);
+    assert.equal(at('2026-10-19').phase, MIGRATION_PHASE.IN_WINDOW, `2026-10-19 ${hour}`);
+    assert.equal(at('2026-11-19').phase, MIGRATION_PHASE.IN_WINDOW, `2026-11-19 ${hour}`);
+    assert.equal(at('2026-11-19').daysToEnd, 0, `countdown on the last day, ${hour}`);
+    assert.equal(at('2026-11-20').phase, MIGRATION_PHASE.SETTLED, `2026-11-20 ${hour}`);
+  }
+});
+
 /* --------------------------------------------------------- migrationFails */
 
 test('the gate fires inside the threshold, in the window, and on an anomaly', () => {
@@ -295,7 +306,7 @@ test('each state gets its own sentence, and the anomaly says so', async () => {
   );
   assert.match(sentence(DURING, 'ubuntu24'), /this runner served ubuntu-24\.04/);
   assert.match(sentence(DURING, 'ubuntu26'), /has reached this runner/);
-  assert.match(sentence(DURING, null), /No ImageOS was observed/);
+  assert.match(sentence(DURING, null), /not known here/);
   assert.match(sentence(AFTER, null), /finished migrating/);
   assert.match(sentence(AFTER, 'ubuntu24'), /anomaly, not drift/);
   assert.match(sentence(AFTER, 'ubuntu22'), /neither ubuntu-24\.04 nor ubuntu-26\.04/);
@@ -346,7 +357,7 @@ test('a floating label inside a matrix is a site like any other', () => {
     '    runs-on: ${{ matrix.os }}',
   ].join('\n');
   assert.deepEqual(extractFloatingSites(y, 'ci.yml'), [
-    { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28 },
+    { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28, job: 'a', viaMatrix: true },
   ]);
 });
 
@@ -492,6 +503,72 @@ test('the migration ride-along appears in guard --json', async () => {
   assert.equal(j.migration.surveys[0].sites[0].line, 6);
 });
 
+/* ------------------------------------------------ whose image is this? */
+
+// The fixture has three jobs: build on ubuntu-latest, pinned on ubuntu-24.04,
+// lint on ubuntu-22.04. A runner exports these two for the job it is serving.
+const inJob = (job) => ({
+  GITHUB_JOB: job,
+  GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/latest.yml@refs/heads/main',
+});
+
+test('a guard step on an unrelated image says nothing about the floating label', async () => {
+  const r = await guard(
+    { tools: 'node', 'fail-on-migration': '0', json: true },
+    { ImageOS: 'ubuntu22', ...inJob('lint') },
+    BEFORE,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const s = j.migration.surveys[0];
+  assert.equal(s.state, MIGRATION_STATE.PENDING, 'the lint runner is not evidence');
+  assert.equal(s.observed, null);
+  assert.match(s.notes[0], /did not run on ubuntu-latest/);
+  assert.equal(r.code, EXIT_OK, 'another job image is not an anomaly');
+  assert.ok(!r.stdout.includes('::error'), 'nothing to raise');
+});
+
+test('the job that does ask for the label owns the image it ran on', async () => {
+  const r = await guard(
+    { tools: 'node', 'fail-on-migration': '0', json: true },
+    { ImageOS: 'ubuntu22', ...inJob('build') },
+    BEFORE,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.UNEXPECTED);
+  assert.deepEqual(j.migration.surveys[0].notes, []);
+  assert.equal(r.code, EXIT_DRIFT, 'ubuntu-latest serving 22.04 is a real anomaly');
+});
+
+test('mid-window, the job on the floating label still reads as migrated', async () => {
+  const r = await guard(
+    { tools: 'node', 'fail-on-migration': '30', json: true },
+    { ImageOS: 'ubuntu26', ...inJob('build') },
+    DURING,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.MIGRATED);
+  assert.equal(j.migration.surveys[0].observed, 'ubuntu-26.04');
+});
+
+test('a matrix leg is trusted for the two images in the window and no others', () => {
+  const site = { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28, job: 'a', viaMatrix: true };
+  const here = { job: 'a', file: 'ci.yml' };
+  assert.equal(attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu26', sites: [site], here }).imageOS, 'ubuntu26');
+  const off = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu22', sites: [site], here });
+  assert.equal(off.imageOS, null, 'this runner is serving another leg');
+  assert.match(off.note, /through a matrix/);
+});
+
+test('with no GITHUB_JOB the window images are still attributed', () => {
+  const sites = [{ label: 'ubuntu-latest', file: 'ci.yml', line: 6, col: 14, job: 'build' }];
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu24', sites, here: null });
+  assert.equal(a.imageOS, 'ubuntu24');
+  assert.equal(a.note, null);
+  const b = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu22', sites, here: null });
+  assert.equal(b.imageOS, null);
+  assert.match(b.note, /This check did not run on ubuntu-latest/);
+});
+
 /**
  * Guard against a lock recorded on the pre-migration image, with the runner
  * serving the post-migration one: the drift a real user sees mid-rollout.
@@ -509,9 +586,10 @@ async function guardAcrossTheMove(opts, now, locked = { label: 'ubuntu-24.04', i
       },
       lockFile,
     );
+    const { env = {}, ...rest } = opts;
     return await guard(
-      { tools: 'node', 'lock-file': lockFile, 'update-lock': false, ...opts },
-      { ImageVersion: IMAGE, ImageOS: 'ubuntu26' },
+      { tools: 'node', 'lock-file': lockFile, 'update-lock': false, ...rest },
+      { ImageVersion: IMAGE, ImageOS: 'ubuntu26', ...env },
       now,
     );
   } finally {
@@ -543,6 +621,21 @@ test('the explanation needs no flag: the two labels alone identify the move', as
   assert.equal(r.stderr, '');
 });
 
+test('a repo that pins its runners is not told GitHub moved it', async () => {
+  // The same 24.04 -> 26.04 jump, in a repo whose workflows never say
+  // ubuntu-latest: someone bumped the pin by hand and owns the upgrade.
+  const r = await guardAcrossTheMove({ workflows: path.join(FIXTURES, 'workflows') }, DURING);
+  assert.ok(!r.stdout.includes('Explained by'), 'no floating label, no migration to blame');
+  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+});
+
+test('the explanation follows the job, not the repo, when Actions says which job', async () => {
+  const mine = await guardAcrossTheMove({ env: inJob('build') }, DURING);
+  assert.match(mine.stdout, /Explained by the scheduled ubuntu-latest migration/);
+  const theirs = await guardAcrossTheMove({ env: inJob('pinned') }, DURING);
+  assert.ok(!theirs.stdout.includes('Explained by'), 'the pinned job was not moved by the window');
+});
+
 test('a jump the migration table does not describe is left unexplained', async () => {
   const r = await guardAcrossTheMove({}, DURING, {
     label: 'ubuntu-22.04',
diff --git a/test/runners.test.mjs b/test/runners.test.mjs
index fc90d5c..9aaa1cb 100644
--- a/test/runners.test.mjs
+++ b/test/runners.test.mjs
@@ -39,7 +39,7 @@ import { captureIO, readRunnerFixtures, runnerRoutes, stubApi, FIXTURES } from '
 /**
  * Every date below comes from the recorded live responses in
  * test/fixtures/runners/deprecations-recorded.json. At this instant:
- *   2.335.1 runtime ends 2026-09-24 -> 16 days  (RUNTIME-DUE inside 30)
+ *   2.335.1 runtime ends 2026-09-24 -> 15 days  (RUNTIME-DUE inside 30)
  *   2.336.0 runtime ends 2026-11-05 -> 57 days  (OK)
  *   2.337.0 runtime null                        (OK, current)
  *   2.325.0 runtime ended 2025-09-11            (EXPIRED)
@@ -226,7 +226,7 @@ test('runtime inside the window is RUNTIME-DUE', () => {
     now: NOW,
   });
   assert.equal(c.status, RUNNER_STATUS.RUNTIME_DUE);
-  assert.equal(c.runtime.days, 16);
+  assert.equal(c.runtime.days, 15);
   assert.equal(c.runtime.date, '2026-09-24');
   assert.equal(c.runtime.past, false);
 });
@@ -314,7 +314,7 @@ test('the worked example: two image-pinned runners due, one current', async () =
   assert.equal(due.count, 2);
   assert.equal(due.imagePinned, true);
   assert.equal(due.runtime.date, '2026-09-24');
-  assert.equal(due.runtime.days, 16);
+  assert.equal(due.runtime.days, 15);
   assert.equal(due.source, 'GET /orgs/acme/actions/runners/deprecations/2.335.1');
 
   assert.equal(ok.status, RUNNER_STATUS.OK);
@@ -678,7 +678,7 @@ test('the report reproduces the worked example', async () => {
   const lines = text.split('\n');
   assert.equal(lines[0], 'self-hosted runners — acme (3 runners, 2 versions)');
   assert.match(lines[1], /^ {2}RUNTIME-DUE {3}2\.335\.1 {2}x2 {2}arc-linux-1, arc-linux-2$/);
-  assert.match(text, /runtime support ends 2026-09-24 \(16 days\) — jobs stop being queued/);
+  assert.match(text, /runtime support ends 2026-09-24 \(15 days\) — jobs stop being queued/);
   assert.match(text, /ephemeral runners — change the actions-runner-controller image tag, not the host/);
   assert.match(text, /^ {2}OK {12}2\.337\.0 {2}x1 {2}build-mac-1 {2}\(published 2026-08-26\)$/m);
   assert.match(text, /^note: self-hosted runners auto-update by default/m);
@@ -735,7 +735,7 @@ test('an expired runner reads in the past tense', async () => {
   const s = await survey(fleets.expired, { days: 30, failOn: false });
   const text = runnersReport(s);
   assert.match(text, /EXPIRED/);
-  assert.match(text, /runtime support ended 2025-09-11 \(362 days ago\) — jobs are no longer queued to it/);
+  assert.match(text, /runtime support ended 2025-09-11 \(363 days ago\) — jobs are no longer queued to it/);
 });
 
 test('the unknown-version report echoes the version and the 2.329.0 floor', () => {
@@ -821,7 +821,7 @@ test('the step summary tables the fleet, with the notes and citation underneath'
   );
   assert.equal(
     md.split('\n').find((l) => l.startsWith('| `2.335.1`')),
-    '| `2.335.1` | x2 arc-linux-1, arc-linux-2 | 🟠 RUNTIME-DUE | 2026-09-24 (16 days) | — | `2.337.0` |',
+    '| `2.335.1` | x2 arc-linux-1, arc-linux-2 | 🟠 RUNTIME-DUE | 2026-09-24 (15 days) | — | `2.337.0` |',
   );
   assert.equal(
     md.split('\n').find((l) => l.startsWith('| `2.337.0`')),
@@ -849,7 +849,7 @@ test('runners exits 1 on the due fleet with --fail-on-deprecation 30', async ()
   assert.match(r.stdout, /RUNTIME-DUE {3}2\.335\.1/);
   assert.match(
     r.stderr,
-    /^runner-drift: 2 self-hosted runner\(s\) on 2\.335\.1 lose runtime support on 2026-09-24 \(16 days\) and --fail-on-deprecation 30 is set\.$/m,
+    /^runner-drift: 2 self-hosted runner\(s\) on 2\.335\.1 lose runtime support on 2026-09-24 \(15 days\) and --fail-on-deprecation 30 is set\.$/m,
   );
 });
 
@@ -867,7 +867,7 @@ test('runners exits 0 on the current fleet, and on the due fleet without the fla
 test('runners exits 1 on an expired runner even without the flag', async () => {
   const r = await runners({ org: 'acme' }, {}, fleets.expired);
   assert.equal(r.code, EXIT_DRIFT);
-  assert.match(r.stderr, /lost runtime support on 2025-09-11 \(362 days ago\) — jobs are no longer queued/);
+  assert.match(r.stderr, /lost runtime support on 2025-09-11 \(363 days ago\) — jobs are no longer queued/);
 });
 
 test('runners exits 2 when --repo and --org are both given', async () => {
@@ -938,7 +938,7 @@ test('runners --json shapes the whole survey', async () => {
   assert.equal(parsed.groups[0].status, 'RUNTIME-DUE');
   // --json keeps the full timestamp; the text report trims it to a date.
   assert.equal(parsed.groups[0].runtime.at, '2026-09-24T15:30:55Z');
-  assert.equal(parsed.groups[0].runtime.days, 16);
+  assert.equal(parsed.groups[0].runtime.days, 15);
   // Fleet health rides along for automation even though the text report only
   // surfaces the offline count.
   assert.equal(parsed.groups[0].online, 2);
@@ -1015,7 +1015,7 @@ test('guard with a token reports this runner\'s own dates after the skip', async
   assert.match(r.stdout, /::warning title=runner-drift: runner 2\.335\.1 RUNTIME-DUE::/);
   assert.match(r.stdout, /^self-hosted runners — acme \(1 runner, 1 version\)$/m);
   assert.match(r.stdout, /RUNTIME-DUE {3}2\.335\.1 {2}x1 {2}arc-linux-1/);
-  assert.match(r.stdout, /runtime support ends 2026-09-24 \(16 days\)/);
+  assert.match(r.stdout, /runtime support ends 2026-09-24 \(15 days\)/);
   // Only this runner was looked up, not the whole fleet's other version.
   const lookups = r.calls.filter((u) => u.includes('/deprecations/'));
   assert.deepEqual(lookups.map((u) => u.split('/deprecations/')[1]), ['2.335.1']);
@@ -1028,7 +1028,7 @@ test('guard --fail-on-deprecation fails on its own runner', async () => {
   );
   assert.equal(r.code, EXIT_DRIFT);
   assert.match(r.stdout, /::error title=runner-drift: runner 2\.335\.1 RUNTIME-DUE::/);
-  assert.match(r.stderr, /1 self-hosted runner\(s\) on 2\.335\.1 lose runtime support on 2026-09-24 \(16 days\)/);
+  assert.match(r.stderr, /1 self-hosted runner\(s\) on 2\.335\.1 lose runtime support on 2026-09-24 \(15 days\)/);
 });
 
 test('guard on a current self-hosted runner passes', async () => {
@@ -1170,7 +1170,7 @@ test('a due group names the jobs it serves, and annotates the runs-on line', asy
   assert.match(onFile[0], /serve this job \(arc-linux-1, arc-linux-2\)/);
   // The annotation is already on that line, so it does not repeat it.
   assert.ok(!onFile[0].includes('serves '), 'no redundant location in the message');
-  assert.match(onFile[0], /runtime support ends 2026-09-24 \(16 days\)/);
+  assert.match(onFile[0], /runtime support ends 2026-09-24 \(15 days\)/);
 });
 
 /**

From e503430e19d3d514f2b108359b1a27e429bdd552 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 11:17:30 +0800
Subject: [PATCH 04/44] A pinned job is not the floating label running late
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

attributeImageOS checked "is this one of the window's two images" before "did
this job ask for the label", so a job pinned to ubuntu-24.04 after the window
closed reported ubuntu-latest as stale: an error, and an exit 1. The endpoint
rule is only there to rescue the two cases where the job cannot be matched, so
it now lives inside them.

The CI migration lane ran under GitHub's default bash -e, so guard exiting 1
while the window is ahead killed the step before the assertions the comment
above it describes. set +e, the idiom the runners lane in the same file uses.

The step summary now carries the survey notes, which is where "This runner: —"
gets explained, and the changelog no longer claims --as-of on every command.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml |  2 +-
 CHANGELOG.md             |  2 +-
 src/migration.mjs        | 13 ++++++++++---
 src/report.mjs           |  3 +++
 test/migration.test.mjs  | 24 ++++++++++++++++++++++++
 5 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9f79336..a8e3c0f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -156,7 +156,7 @@ jobs:
       # run is that the lane resolved the label and named its source.
       - name: guard --fail-on-migration on a real floating runner
         run: |
-          set -uo pipefail
+          set +e
           out="$(node src/cli.mjs guard --tools node --fail-on-migration 30 --no-update-lock 2>&1)"
           code=$?
           printf '%s\n' "$out"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f983f3b..094a6aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,7 +83,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   annotation group, a new step-summary table (Label, Phase, Move, Window, This
   runner, Source) and a new `migration` key in `--json`.
 
-- **`--as-of <date>`** on every command. It moves the clock every countdown is
+- **`--as-of <date>`** on every command that counts down to something (`guard`, `plan`, `runners`, `actions`). It moves the clock every countdown is
   measured from and nothing else, so `plan --from ubuntu-latest --as-of
   2026-10-19` answers what the report will say on the first day of the rollout
   without pretending the run happened then. It is also what makes the migration
diff --git a/src/migration.mjs b/src/migration.mjs
index dff285b..837c561 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -59,18 +59,25 @@ export function attributeImageOS({ label, imageOS, sites = [], here = null }) {
   const mine = sites.filter((site) => siteInJob(site, here));
 
   if (mine.some((site) => !site.viaMatrix)) return { imageOS, note: null };
-  if (endpoint) return { imageOS, note: null };
   if (mine.length) {
+    if (endpoint) return { imageOS, note: null };
     return {
       imageOS: null,
       note: `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
         + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
     };
   }
-  const who = here ? `The job that ran this check ("${here.job}")` : 'This check';
+  if (!here) {
+    if (endpoint) return { imageOS, note: null };
+    return {
+      imageOS: null,
+      note: `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+    };
+  }
   return {
     imageOS: null,
-    note: `${who} did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+    note: `The job that ran this check ("${here.job}") did not run on ${label}, `
+      + 'so its ImageOS is not evidence about the migration.',
   };
 }
 
diff --git a/src/report.mjs b/src/report.mjs
index f130efe..e2ff50b 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -464,6 +464,9 @@ export function migrationSummaryMarkdown(surveys) {
   ];
   for (const s of surveys) {
     lines.push('', migrationMessage(s));
+    // The "This runner" cell is a dash whenever the image could not be read or
+    // could not be attributed, and the note is the difference between the two.
+    for (const n of s.notes) lines.push('', n);
     const diffRows = [...s.image, ...s.toolDiffs];
     if (!diffRows.length) continue;
     lines.push(
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index e8b6ab3..8d556e4 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -539,6 +539,30 @@ test('the job that does ask for the label owns the image it ran on', async () =>
   assert.equal(r.code, EXIT_DRIFT, 'ubuntu-latest serving 22.04 is a real anomaly');
 });
 
+test('a job pinned to the old image is not the floating label running late', async () => {
+  // ubuntu-24.04 is a window endpoint, so this is the case where "the image is
+  // one of the two" must not override "this job never asked for the label".
+  const r = await guard(
+    { tools: 'node', 'fail-on-migration': '0', json: true },
+    { ImageOS: 'ubuntu24', ...inJob('pinned') },
+    AFTER,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.SETTLED);
+  assert.equal(r.code, EXIT_OK, 'a pinned job is not a stale floating runner');
+  assert.ok(!r.stdout.includes('::error'), 'nothing to raise');
+});
+
+test('the step summary says why This runner is a dash', async () => {
+  const s = await survey(DURING, 'ubuntu22', {
+    sites: [{ label: 'ubuntu-latest', file: 'ci.yml', line: 6, col: 14, job: 'build' }],
+    here: { job: 'lint', file: 'ci.yml' },
+  });
+  const md = migrationSummaryMarkdown([s]);
+  assert.match(md, /\| — \|/, 'no image attributed');
+  assert.match(md, /Job that ran this check|did not run on ubuntu-latest/);
+});
+
 test('mid-window, the job on the floating label still reads as migrated', async () => {
   const r = await guard(
     { tools: 'node', 'fail-on-migration': '30', json: true },

From dd5f9c8b9e81b66f26d617a38e245df786888459 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 11:27:21 +0800
Subject: [PATCH 05/44] Scope the matrix label scan to matrix blocks

A file with one expression runs-on had every label-shaped word in it treated as
a runner the workflow asks for. A comment saying the repo left ubuntu-latest
years ago became a migration site, annotated on the comment line, and mid-window
it handed the runner's ImageOS to a label the repo never uses.

Also from the review: the first-run step summary no longer says tools were
locked in a file that --no-update-lock stopped it writing, runGuard defaults to
writing the lock for callers who never saw the flag main() resolves, and the
"Explained by the scheduled migration" line now has its explains key in --json
without --fail-on-migration, which is where the README already said it was free.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 10 +++++++++-
 README.md               |  2 ++
 src/cli.mjs             | 13 +++++++++----
 src/detect.mjs          | 24 ++++++++++++++++++++++--
 src/report.mjs          | 12 ++++++++++--
 test/detect.test.mjs    | 20 ++++++++++++++++++++
 test/guard.test.mjs     | 35 +++++++++++++++++++++++++++++++++++
 test/migration.test.mjs |  7 +++++++
 8 files changed, 114 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 094a6aa..8ddd806 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -112,7 +112,15 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   there was nothing to update yet. The README said the flag leaves the lock file
   untouched, so a lint job that asked for a report got a file to decide about.
   It now writes nothing, says so, and still reports the baseline it observed;
-  `--json` gained a `written` boolean beside `baseline`.
+  `--json` gained a `written` boolean beside `baseline`, and the step summary no
+  longer says the tools were "locked in" a file that does not exist.
+
+- A workflow whose `runs-on:` is a matrix expression had every label-shaped word
+  in the file read as a runner it asks for, including the ones in comments and
+  in `run:` lines. That put retirement and migration annotations on lines nobody
+  can act on, and, once the migration lane existed, could attribute a runner's
+  image to a label the repo never uses. The scan is now scoped to the file's
+  `matrix:` blocks, with comments dropped.
 
 [1.4.0]: https://github.com/Booyaka101/runner-drift/releases/tag/v1.4.0
 
diff --git a/README.md b/README.md
index a15b8cd..02b5637 100644
--- a/README.md
+++ b/README.md
@@ -301,6 +301,8 @@ Exit codes and the `--fail-on` thresholds are untouched by any of this. An
 anomaly fails whatever the threshold, the same rule `--fail-on-retirement` uses
 for a label already past its date. `--json` gains a `migration` block, and the
 step summary gains a table (Label, Phase, Move, Window, This runner, Source).
+The explanation above has its own `explains` key next to `diffs`, which is there
+with or without the flag, and is `null` when nothing announced explains the jump.
 Adding `windows-latest` or `macos-latest` later is a data change in `MIGRATIONS`,
 nothing else.
 
diff --git a/src/cli.mjs b/src/cli.mjs
index 69087fd..4ac149c 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -541,6 +541,9 @@ async function checkOwnRunner(opts, io, env, deps, window) {
 
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
+  // Writing the lock is the default; `main` resolves --no-update-lock into it,
+  // but runGuard is exported and a caller building options by hand has neither.
+  const updateLock = opts['update-lock'] !== false;
   const failOn = (opts['fail-on'] ?? 'none').toLowerCase();
   if (!['none', 'major', 'minor', 'any'].includes(failOn)) {
     out(io.stderr, `--fail-on must be one of: major, minor, any (got "${opts['fail-on']}")`);
@@ -701,12 +704,13 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     const baseline = { label, imageOS, imageVersion, tools: observed, updatedAt: new Date().toISOString() };
     // --no-update-lock covers the first run too. A job that asked for a report
     // and got a file it then has to decide whether to commit is a surprise.
-    const written = opts['update-lock'] ? await writeLock(baseline, lockFile) : lockPayload(baseline);
+    const written = updateLock ? await writeLock(baseline, lockFile) : lockPayload(baseline);
     const summary = stepSummaryMarkdown({
       label,
       toImage: imageVersion,
       diffs: Object.keys(observed),
       baseline: true,
+      written: updateLock,
       lockFile,
     });
     if (opts.summary) await writeStepSummary(summary);
@@ -716,7 +720,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         JSON.stringify(
           {
             baseline: true,
-            written: opts['update-lock'],
+            written: updateLock,
             lock: written,
             ...(retirement ? { retirement } : {}),
             ...(migration ? { migration } : {}),
@@ -732,7 +736,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       for (const [t, v] of manifestOnly) out(io.stdout, `  ${t}: ${v.versions.join(', ')} (from manifest)`);
       out(
         io.stdout,
-        opts['update-lock']
+        updateLock
           ? `Wrote ${lockFile}. Commit it so the next image bump can be diffed.`
           : `Nothing written: --no-update-lock is set. Drop it to record ${lockFile} as the baseline.`,
       );
@@ -795,7 +799,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
 
   for (const line of annotations(diffs, attributionMap, label)) out(io.stdout, line);
 
-  if (opts['update-lock']) {
+  if (updateLock) {
     await writeLock(
       { label, imageOS, imageVersion, tools: observed, updatedAt: new Date().toISOString() },
       lockFile,
@@ -804,6 +808,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
 
   if (opts.json) {
     const payload = { label, from: lock.imageVersion, to: imageVersion, approximate, diffs, attribution: attributionMap };
+    payload.explains = explained?.label ?? null;
     if (retirement) payload.retirement = retirement;
     if (migration) payload.migration = { ...migration, explains: explained?.label ?? null };
     out(io.stdout, JSON.stringify(payload, null, 2));
diff --git a/src/detect.mjs b/src/detect.mjs
index 9e37a90..f3da866 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -193,11 +193,31 @@ function scanRunsOn(lines) {
   return { found, targets, expression };
 }
 
-/** `runs-on: ${{ matrix.os }}` -> the label-shaped scalars elsewhere in the file. */
+/**
+ * `runs-on: ${{ matrix.os }}` -> the label-shaped scalars in the file's
+ * `matrix:` blocks.
+ *
+ * Scoped to those blocks, and comments dropped: a label named in a comment or a
+ * `run:` line is not a runner this workflow asks for, and an annotation has to
+ * land on a line someone can act on.
+ */
 function matrixLabels(lines) {
   const found = [];
+  let block = null;
   for (let i = 0; i < lines.length; i++) {
-    for (const tok of lines[i].matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
+    const open = lines[i].match(/^([ \t]*)matrix:[ \t]*(#[^\r\n]*)?$/);
+    if (open) {
+      block = open[1].length;
+      continue;
+    }
+    if (block === null) continue;
+    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+    if (!text.trim()) continue;
+    if (indentOf(text) <= block) {
+      block = null;
+      continue;
+    }
+    for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
       if (LABEL_SHAPE.test(tok[0])) {
         found.push({ label: tok[0].toLowerCase(), line: i + 1, col: tok.index + 1 });
       }
diff --git a/src/report.mjs b/src/report.mjs
index e2ff50b..0f346bb 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -154,17 +154,25 @@ export function stepSummaryMarkdown({
   attribution = {},
   approximate = false,
   baseline = false,
+  written = true,
   lockFile,
 }) {
   const lines = [];
   lines.push('## runner-drift');
   lines.push('');
   if (baseline) {
+    const count = Object.keys(diffs).length || diffs.length;
     lines.push(
-      `Baseline recorded for \`${label}\` at image \`${toImage}\` — ${Object.keys(diffs).length || diffs.length} tool(s) locked in \`${lockFile}\`.`,
+      written
+        ? `Baseline recorded for \`${label}\` at image \`${toImage}\` — ${count} tool(s) locked in \`${lockFile}\`.`
+        : `Baseline observed for \`${label}\` at image \`${toImage}\` — ${count} tool(s). Nothing written: \`--no-update-lock\` is set.`,
     );
     lines.push('');
-    lines.push('The next run on a bumped image will diff against this baseline.');
+    lines.push(
+      written
+        ? 'The next run on a bumped image will diff against this baseline.'
+        : `Drop the flag to record \`${lockFile}\`, and the next run on a bumped image has something to diff against.`,
+    );
     return `${lines.join('\n')}\n`;
   }
 
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 33f8b3e..2fed094 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -6,6 +6,7 @@ import {
   analyseWorkflow,
   extractLabels,
   extractLabelSites,
+  extractFloatingSites,
   extractRunsOnTargets,
   extractRunScripts,
   commandsInScript,
@@ -158,6 +159,25 @@ test('labelSites: ${{ matrix.os }} resolves to the matrix value positions', () =
   ]);
 });
 
+test('labelSites: a matrix does not make every mention of a label a site', () => {
+  const y = [
+    '# this repo moved off ubuntu-latest years ago',
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-24.04]   # not ubuntu-latest',
+    '    runs-on: ${{ matrix.os }}',
+    '    steps:',
+    '      - run: echo ubuntu-latest',
+  ].join('\n');
+  assert.deepEqual(extractFloatingSites(y), [], 'a comment is not a runs-on');
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.line]),
+    [['ubuntu-24.04', 6]],
+  );
+});
+
 test('labelSites: floating labels are never a site', () => {
   assert.deepEqual(extractLabelSites('    runs-on: ubuntu-latest\n'), []);
 });
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 47b1ca1..675df34 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -233,6 +233,41 @@ test('--no-update-lock writes no lock on the first run either', async () => {
   }
 });
 
+test('the first-run summary does not claim a lock file that was not written', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const summaryFile = path.join(dir, 'summary.md');
+  await writeFile(summaryFile, '', 'utf8');
+  const prev = process.env.GITHUB_STEP_SUMMARY;
+  process.env.GITHUB_STEP_SUMMARY = summaryFile;
+  try {
+    await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false });
+    const md = await readFile(summaryFile, 'utf8');
+    assert.match(md, /Nothing written/);
+    assert.ok(!md.includes('locked in'), 'there is no file to lock anything in');
+    assert.ok(!md.includes('diff against this baseline'), 'nothing was kept to diff against');
+  } finally {
+    if (prev === undefined) delete process.env.GITHUB_STEP_SUMMARY;
+    else process.env.GITHUB_STEP_SUMMARY = prev;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('runGuard writes the lock by default, with no update-lock key at all', async () => {
+  // --no-update-lock is resolved into `update-lock` by main(). A caller of the
+  // exported runGuard builds its own options and has neither key.
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const cap = captureIO();
+  try {
+    const code = await runGuard({ tools: 'node', 'lock-file': lockFile, summary: false }, cap.io, ENV);
+    assert.equal(code, EXIT_OK);
+    assert.equal((await readLock(lockFile)).label, 'ubuntu-22.04');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('--no-update-lock leaves the lock alone', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 8d556e4..545be5a 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -645,6 +645,13 @@ test('the explanation needs no flag: the two labels alone identify the move', as
   assert.equal(r.stderr, '');
 });
 
+test('--json names the explanation without --fail-on-migration too', async () => {
+  const r = await guardAcrossTheMove({ json: true }, DURING);
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.equal(j.explains, 'ubuntu-latest');
+  assert.equal(j.migration, undefined, 'the lane itself still needs the flag');
+});
+
 test('a repo that pins its runners is not told GitHub moved it', async () => {
   // The same 24.04 -> 26.04 jump, in a repo whose workflows never say
   // ubuntu-latest: someone bumped the pin by hand and owns the upgrade.

From 66c6495b048f01f4a0616fac68dc0ef01fe643d1 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 11:39:09 +0800
Subject: [PATCH 06/44] A flow-mapping matrix is a matrix too

Scoping the matrix scan to block-style matrix: keys dropped
matrix: {os: [ubuntu-latest, ubuntu-22.04]} on the floor, which took the labels
out of every extractor. The matrix: line is now scanned itself and still opens
the block, since the mapping can run on.

Also from the review: guard --json with no ImageVersion printed annotations and
no document when only the retirement lane had run; a manifest bullet named
constructor resolved to Object.prototype instead of being read as a tool; and
stdout said "baseline recorded" where --no-update-lock had just stopped it
recording anything.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/cli.mjs            |  4 ++--
 src/detect.mjs         | 20 +++++++++++++-------
 src/manifest.mjs       |  3 ++-
 test/detect.test.mjs   | 15 +++++++++++++++
 test/guard.test.mjs    | 17 ++++++++++++++++-
 test/manifest.test.mjs |  9 +++++++++
 6 files changed, 57 insertions(+), 11 deletions(-)

diff --git a/src/cli.mjs b/src/cli.mjs
index 4ac149c..34392a7 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -605,7 +605,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     // version with a date on it. Without a token this is a no-op and the skip
     // above is the whole output, exactly as in 1.1.0.
     const own = await checkOwnRunner(opts, io, env, deps, window);
-    if (opts.json && (own || migration)) {
+    if (opts.json && (own || migration || retirement)) {
       const payload = {};
       if (own) payload.runners = own;
       if (retirement) payload.retirement = retirement;
@@ -730,7 +730,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         ),
       );
     } else {
-      out(io.stdout, `baseline recorded — ${label} image ${imageVersion}`);
+      out(io.stdout, `baseline ${updateLock ? 'recorded' : 'observed'} — ${label} image ${imageVersion}`);
       for (const n of probeNotes) out(io.stdout, `  ${n}`);
       const manifestOnly = Object.entries(observed).filter(([, v]) => v.source === 'manifest');
       for (const [t, v] of manifestOnly) out(io.stdout, `  ${t}: ${v.versions.join(', ')} (from manifest)`);
diff --git a/src/detect.mjs b/src/detect.mjs
index f3da866..c85f611 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -203,25 +203,31 @@ function scanRunsOn(lines) {
  */
 function matrixLabels(lines) {
   const found = [];
+  const collect = (text, i) => {
+    for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
+      if (LABEL_SHAPE.test(tok[0])) {
+        found.push({ label: tok[0].toLowerCase(), line: i + 1, col: tok.index + 1 });
+      }
+    }
+  };
   let block = null;
   for (let i = 0; i < lines.length; i++) {
-    const open = lines[i].match(/^([ \t]*)matrix:[ \t]*(#[^\r\n]*)?$/);
+    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+    const open = text.match(/^([ \t]*)matrix:/);
     if (open) {
+      // A flow mapping puts the labels on the `matrix:` line itself; the block
+      // stays open either way, since the mapping may run onto further lines.
       block = open[1].length;
+      collect(text, i);
       continue;
     }
     if (block === null) continue;
-    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
     if (!text.trim()) continue;
     if (indentOf(text) <= block) {
       block = null;
       continue;
     }
-    for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
-      if (LABEL_SHAPE.test(tok[0])) {
-        found.push({ label: tok[0].toLowerCase(), line: i + 1, col: tok.index + 1 });
-      }
-    }
+    collect(text, i);
   }
   return found;
 }
diff --git a/src/manifest.mjs b/src/manifest.mjs
index 103a1f1..62d5c94 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -212,7 +212,8 @@ export function parseManifest(markdown, label = null) {
     // its own delimiter and there is no failure condition to backtrack over.
     const headerM = line.match(/^[ \t]*-[ \t]+([^:\r\n]+):[ \t]*([^\r\n]+)/);
     if (headerM) {
-      const field = HEADER_FIELDS[headerM[1].trim().toLowerCase()];
+      const key = headerM[1].trim().toLowerCase();
+      const field = Object.hasOwn(HEADER_FIELDS, key) ? HEADER_FIELDS[key] : null;
       if (field) {
         header[field] ??= headerM[2].trim();
         continue;
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 2fed094..f53d56a 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -159,6 +159,21 @@ test('labelSites: ${{ matrix.os }} resolves to the matrix value positions', () =
   ]);
 });
 
+test('a flow-mapping matrix is read like a block one', () => {
+  const y = [
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix: {os: [ubuntu-latest, ubuntu-22.04]}',
+    '    runs-on: ${{ matrix.os }}',
+  ].join('\n');
+  assert.deepEqual(extractLabels(y).sort(), ['ubuntu-22.04', 'ubuntu-latest']);
+  assert.deepEqual(
+    extractFloatingSites(y).map((s) => [s.label, s.line, s.job]),
+    [['ubuntu-latest', 4, 'a']],
+  );
+});
+
 test('labelSites: a matrix does not make every mention of a label a site', () => {
   const y = [
     '# this repo moved off ubuntu-latest years ago',
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 675df34..6301400 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -173,6 +173,20 @@ test('zero tools and no lock tells the user to pass --tools', async () => {
   }
 });
 
+test('--json off a hosted runner still prints the retirement document', async () => {
+  const r = await guard(
+    {
+      tools: 'node',
+      json: true,
+      'fail-on-retirement': '365',
+      workflows: path.join(FIXTURES, 'workflows-retirement'),
+    },
+    {},
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.ok(j.retirement.findings.length, 'the lane ran, so its findings are in the document');
+});
+
 test('guard writes a markdown table to $GITHUB_STEP_SUMMARY', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
@@ -225,7 +239,8 @@ test('--no-update-lock writes no lock on the first run either', async () => {
   try {
     const r = await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false });
     assert.equal(r.code, EXIT_OK);
-    assert.match(r.stdout, /baseline recorded/);
+    assert.match(r.stdout, /baseline observed/);
+    assert.ok(!r.stdout.includes('baseline recorded'), 'nothing was recorded anywhere');
     assert.match(r.stdout, /Nothing written: --no-update-lock is set/);
     await assert.rejects(() => readFile(lockFile, 'utf8'), /ENOENT/);
   } finally {
diff --git a/test/manifest.test.mjs b/test/manifest.test.mjs
index 59d7fd0..7e31306 100644
--- a/test/manifest.test.mjs
+++ b/test/manifest.test.mjs
@@ -11,6 +11,15 @@ test('parses the header of a real Ubuntu 22.04 manifest', async () => {
   assert.equal(m.title, 'Ubuntu 22.04');
 });
 
+test('a bullet named after an Object member is a tool, not a prototype lookup', () => {
+  const m = parseManifest(
+    ['# Ubuntu', '', '## Installed Software', '', '- constructor: 1.2.3', ''].join('\n'),
+  );
+  assert.deepEqual(m.tools.constructor, ['1.2.3']);
+  assert.equal(m.osVersion, null);
+  assert.equal(m.kernelVersion, null);
+});
+
 test('parses both installed-software line styles', async () => {
   const m = parseManifest(await readFixture('ubuntu-22.04'));
   // "- CMake 3.31.6"  (name + single version)

From 777176d608e294a12cfc0d528280165061d5e0ed Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 11:54:05 +0800
Subject: [PATCH 07/44] An expression runs-on reads the whole file again, minus
 the prose

Scoping the scan to matrix: blocks fixed comments and shell lines by dropping
everything else with them: workflow_call input defaults and env: values are
where plenty of real workflows keep the label. It walks the file again, skipping
comments, block scalars and the keys that hold prose or shell rather than a
value.

Three more from the review. jobKeys latched onto the first key called jobs at
any depth, so an input named jobs voided every job id in the file and with it
all attribution: the jobs map is a top-level key. A matrix that lists both
ubuntu-latest and ubuntu-24.04 no longer reads a 24.04 runner as the floating
label running late, since the same matrix asks for that image by name. And a run
from a file the scan never saw, which is what a reusable workflow reports, falls
back to matching on the job id alone.

guard also scans the workflow directory once per run now instead of up to five
times for the same answer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/cli.mjs             | 44 +++++++++++++++---------
 src/detect.mjs          | 75 +++++++++++++++++++++++++++--------------
 src/index.mjs           |  1 +
 src/migration.mjs       | 32 +++++++++++++-----
 test/detect.test.mjs    | 56 ++++++++++++++++++++++++++++++
 test/migration.test.mjs | 35 ++++++++++++++++++-
 6 files changed, 192 insertions(+), 51 deletions(-)

diff --git a/src/cli.mjs b/src/cli.mjs
index 34392a7..cdad87e 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -25,7 +25,7 @@ import {
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { imageDiffs, surveyMigration } from './migration.mjs';
 import { attribute, commitWindow, attributeChanges, listManifestCommits, manifestAtSha } from './history.mjs';
-import { detect, runningJob, siteInJob, SELF_HOSTED } from './detect.mjs';
+import { detect, jobMatcher, runningJob, SELF_HOSTED } from './detect.mjs';
 import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
@@ -232,12 +232,23 @@ function summarise(io, items, keyOf, lineOf) {
   }
 }
 
+/**
+ * One workflow scan per `guard` run. Both lint lanes, the tool fallback, the
+ * label fallback and the drift explanation want the same directory, and reading
+ * it five times to get the same answer is five times the IO for nothing.
+ */
+function scanner(opts) {
+  const dir = opts.workflows ?? path.join('.github', 'workflows');
+  let pending = null;
+  return () => (pending ??= detect(dir));
+}
+
 /**
  * The workflow scan the two lint lanes start from, or null when there is no
  * workflow directory — which is a notice on both streams, not an error.
  */
-async function scanForLane(opts, io, nothingToCheck) {
-  const scanned = await detect(opts.workflows ?? path.join('.github', 'workflows'));
+async function scanForLane(scan, io, nothingToCheck) {
+  const scanned = await scan();
   if (!scanned.missing) return scanned;
   const msg = `No workflow directory at ${scanned.dir} — ${nothingToCheck}.`;
   out(io.stdout, notice(msg));
@@ -250,10 +261,10 @@ async function scanForLane(opts, io, nothingToCheck) {
  * the window. Reads the workflow files alone, so it works in a lint job with no
  * lock file and no hosted runner. Returns null on a bad value, already reported.
  */
-async function checkRetirement(opts, io, now) {
+async function checkRetirement(opts, io, now, scan) {
   const days = wholeDays(opts['fail-on-retirement'], '--fail-on-retirement', io);
   if (days === null) return null;
-  const scanned = await scanForLane(opts, io, 'no pinned labels to check for retirement');
+  const scanned = await scanForLane(scan, io, 'no pinned labels to check for retirement');
   if (!scanned) return { days, findings: [] };
 
   const findings = retirementFindings(scanned.labelSites, { now, days });
@@ -283,10 +294,10 @@ function reportRetirement(io, { days, findings }) {
  * images it names. Opt-in like the retirement gate, and like it, useful in a
  * plain lint job with no runner and no lock file.
  */
-async function checkMigration(opts, io, now, imageOS, env, deps) {
+async function checkMigration(opts, io, now, imageOS, env, scan, deps) {
   const days = wholeDays(opts['fail-on-migration'], '--fail-on-migration', io);
   if (days === null) return null;
-  const scanned = await scanForLane(opts, io, 'no floating labels to check for migration');
+  const scanned = await scanForLane(scan, io, 'no floating labels to check for migration');
   if (!scanned) return { days, surveys: [] };
 
   const byLabel = new Map();
@@ -300,7 +311,7 @@ async function checkMigration(opts, io, now, imageOS, env, deps) {
   const here = runningJob(env);
   const surveys = await Promise.all(
     [...byLabel].map(([label, sites]) =>
-      surveyMigration({ label, now, imageOS, tools, sites, here, load }),
+      surveyMigration({ label, now, imageOS, tools, sites, others: scanned.labelSites, here, load }),
     ),
   );
 
@@ -323,7 +334,7 @@ async function checkMigration(opts, io, now, imageOS, env, deps) {
  * The scan only happens for a jump the table already recognises, which is rare,
  * so the common path still reads no workflow files it did not need.
  */
-async function explainDrift({ migration, lock, label, opts, env }) {
+async function explainDrift({ migration, lock, label, scan, env }) {
   const survey = migration?.surveys.find(
     (s) => s.done && s.observed === s.to && lock.label === s.from && label === s.to,
   );
@@ -333,10 +344,10 @@ async function explainDrift({ migration, lock, label, opts, env }) {
   if (!m) return null;
   const sites = migration
     ? migration.surveys.flatMap((s) => s.sites)
-    : (await detect(opts.workflows ?? path.join('.github', 'workflows'))).floatingSites;
+    : (await scan()).floatingSites;
   const ours = sites.filter((site) => site.label === m.label);
   const here = runningJob(env);
-  const used = here ? ours.some((site) => siteInJob(site, here)) : ours.length > 0;
+  const used = here ? ours.some(jobMatcher(here, sites)) : ours.length > 0;
   return used ? m : null;
 }
 
@@ -541,6 +552,7 @@ async function checkOwnRunner(opts, io, env, deps, window) {
 
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
+  const scan = scanner(opts);
   // Writing the lock is the default; `main` resolves --no-update-lock into it,
   // but runGuard is exported and a caller building options by hand has neither.
   const updateLock = opts['update-lock'] !== false;
@@ -559,7 +571,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // so a lint job on any runner gets the deadline warning.
   let retirement = null;
   if (opts['fail-on-retirement'] !== undefined) {
-    retirement = await checkRetirement(opts, io, deps.now ?? new Date());
+    retirement = await checkRetirement(opts, io, deps.now ?? new Date(), scan);
     if (!retirement) return EXIT_USAGE;
   }
   const retiring = retirement?.findings.length ? retirement : null;
@@ -572,7 +584,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // two images right now" and "this job ran on the new one".
   let migration = null;
   if (opts['fail-on-migration'] !== undefined) {
-    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, deps);
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, deps);
     if (!migration) return EXIT_USAGE;
     if (!opts.json && migration.surveys.length) {
       out(io.stdout, migrationReport(migration.surveys));
@@ -622,7 +634,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   let label = (imageOS && IMAGE_OS_TO_LABEL[imageOS.toLowerCase()]) || lock?.label || null;
 
   if (!label) {
-    const detected = await detect(opts.workflows ?? path.join('.github', 'workflows'));
+    const detected = await scan();
     label = concreteLabels(detected.labels)[0] ?? null;
   }
   if (!label) {
@@ -640,7 +652,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     tools = Object.keys(lock.tools);
   }
   if (!tools?.length) {
-    const detected = await detect(opts.workflows ?? path.join('.github', 'workflows'));
+    const detected = await scan();
     tools = detected.tools;
   }
   if (!tools.length) {
@@ -784,7 +796,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     }
   }
 
-  const explained = await explainDrift({ migration, lock, label, opts, env });
+  const explained = await explainDrift({ migration, lock, label, scan, env });
 
   const summary = stepSummaryMarkdown({
     label,
diff --git a/src/detect.mjs b/src/detect.mjs
index c85f611..a33e0d2 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -194,40 +194,42 @@ function scanRunsOn(lines) {
 }
 
 /**
- * `runs-on: ${{ matrix.os }}` -> the label-shaped scalars in the file's
- * `matrix:` blocks.
+ * An expression `runs-on:` -> the label-shaped scalars elsewhere in the file.
  *
- * Scoped to those blocks, and comments dropped: a label named in a comment or a
- * `run:` line is not a runner this workflow asks for, and an annotation has to
- * land on a line someone can act on.
+ * Which one a given runner serves is not decidable from the file, so this is
+ * deliberately broad: `${{ matrix.os }}`, `${{ inputs.runner }}` and
+ * `${{ env.RUNNER }}` all resolve to values written somewhere above.
+ *
+ * Broad, but not everything. Comments, block scalars and the keys that hold
+ * prose or shell rather than a value (`run:`, `name:`, `if:`) are skipped: a
+ * label named there is not a runner the workflow asks for, and an annotation
+ * has to land on a line someone can act on.
  */
+const PROSE_KEYS = new Set(['run', 'name', 'if']);
+
 function matrixLabels(lines) {
   const found = [];
-  const collect = (text, i) => {
+  let scalar = null;
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+    if (scalar !== null) {
+      if (!text.trim() || indentOf(text) > scalar) continue;
+      scalar = null;
+    }
+    const key = text.match(/^([ \t]*)(?:-[ \t]+)?([^:\r\n]*):([^\r\n]*)$/);
+    if (key) {
+      // `run: |` and friends: the body below is shell or prose, not YAML values.
+      if (/^[|>]/.test(key[3].trim())) {
+        scalar = key[1].length;
+        continue;
+      }
+      if (PROSE_KEYS.has(key[2].trim().toLowerCase())) continue;
+    }
     for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
       if (LABEL_SHAPE.test(tok[0])) {
         found.push({ label: tok[0].toLowerCase(), line: i + 1, col: tok.index + 1 });
       }
     }
-  };
-  let block = null;
-  for (let i = 0; i < lines.length; i++) {
-    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
-    const open = text.match(/^([ \t]*)matrix:/);
-    if (open) {
-      // A flow mapping puts the labels on the `matrix:` line itself; the block
-      // stays open either way, since the mapping may run onto further lines.
-      block = open[1].length;
-      collect(text, i);
-      continue;
-    }
-    if (block === null) continue;
-    if (!text.trim()) continue;
-    if (indentOf(text) <= block) {
-      block = null;
-      continue;
-    }
-    collect(text, i);
   }
   return found;
 }
@@ -266,7 +268,8 @@ function jobKeys(lines) {
       const indent = m[1].length;
       const key = m[2].trim();
       if (jobsIndent === null) {
-        if (key === 'jobs') jobsIndent = indent;
+        // Top level only: `on.workflow_dispatch.inputs.jobs` is not the map.
+        if (key === 'jobs' && indent === 0) jobsIndent = indent;
       } else if (indent <= jobsIndent) {
         current = null;
       } else if (jobIndent === null || indent === jobIndent) {
@@ -332,6 +335,26 @@ export function runningJob(env = process.env) {
   return { job, file: ref ? path.basename(ref.split('@')[0]) : null };
 }
 
+/**
+ * A predicate for "this site is one the running job was scheduled from", over
+ * the sites a scan actually produced.
+ *
+ * The file name is dropped from the comparison when none of the scanned files
+ * is the one this run came from: a job inside a reusable workflow reports the
+ * caller's file in `GITHUB_WORKFLOW_REF`, and a scan pointed at a copy of the
+ * directory need not match it either. The job id still has to agree.
+ */
+export function jobMatcher(here, sites = []) {
+  if (!here) return () => false;
+  const known =
+    here.file
+    && sites.some(
+      (s) => s.file && path.basename(s.file).toLowerCase() === here.file.toLowerCase(),
+    );
+  const at = known ? here : { ...here, file: null };
+  return (site) => siteInJob(site, at);
+}
+
 /** Is this `runs-on:` site the one the running job was scheduled from? */
 export function siteInJob(site, here) {
   if (!here || !site?.job || site.job !== here.job) return false;
diff --git a/src/index.mjs b/src/index.mjs
index df61408..84de542 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -20,6 +20,7 @@ export {
   extractLabelSites,
   extractFloatingSites,
   extractRunsOnTargets,
+  jobMatcher,
   runningJob,
   siteInJob,
   extractRunScripts,
diff --git a/src/migration.mjs b/src/migration.mjs
index 837c561..c61c386 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -12,7 +12,7 @@
  */
 
 import { IMAGE_OS_TO_LABEL, migrationFor, migrationStatus } from './labels.mjs';
-import { siteInJob } from './detect.mjs';
+import { jobMatcher } from './detect.mjs';
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
 import { errorText } from './http.mjs';
@@ -51,27 +51,42 @@ export function imageDiffs(from, to) {
  * matrix leg (the file cannot say which leg this runner is), and a run with no
  * `GITHUB_JOB` to match against (`guard` invoked outside a workflow job).
  */
-export function attributeImageOS({ label, imageOS, sites = [], here = null }) {
+export function attributeImageOS({ label, imageOS, sites = [], others = [], here = null }) {
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
   const observed = IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null;
-  const endpoint = observed === m?.from || observed === m?.to;
-  const mine = sites.filter((site) => siteInJob(site, here));
+  const belongs = jobMatcher(here, [...sites, ...others]);
+  const mine = sites.filter(belongs);
 
   if (mine.some((site) => !site.viaMatrix)) return { imageOS, note: null };
+
+  // A matrix that lists the observed label itself: this runner is at least as
+  // likely to be serving that leg as the floating one, so neither is evidence.
+  const rival =
+    observed !== null
+    && others.some(
+      (site) => site.viaMatrix && site.label === observed && (here ? belongs(site) : true),
+    );
+  const endpoint = !rival && (observed === m?.from || observed === m?.to);
+
   if (mine.length) {
     if (endpoint) return { imageOS, note: null };
     return {
       imageOS: null,
-      note: `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
-        + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
+      note: rival
+        ? `Job "${here.job}" reaches ${label} through a matrix that also asks for ${observed} `
+          + 'by name, so this runner may be serving that leg instead.'
+        : `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
+          + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
     };
   }
   if (!here) {
     if (endpoint) return { imageOS, note: null };
     return {
       imageOS: null,
-      note: `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+      note: rival
+        ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
+        : `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
     };
   }
   return {
@@ -100,10 +115,11 @@ export async function surveyMigration({
   imageOS = null,
   tools = [],
   sites = [],
+  others = [],
   here = null,
   load = loadManifest,
 } = {}) {
-  const attributed = attributeImageOS({ label, imageOS, sites, here });
+  const attributed = attributeImageOS({ label, imageOS, sites, others, here });
   const status = migrationStatus(label, { now, imageOS: attributed.imageOS });
   if (!status) return null;
 
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index f53d56a..6dbba31 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -174,6 +174,62 @@ test('a flow-mapping matrix is read like a block one', () => {
   );
 });
 
+test('an expression runs-on resolves a workflow_call input default', () => {
+  const y = [
+    'on:',
+    '  workflow_call:',
+    '    inputs:',
+    '      runner:',
+    '        default: ubuntu-22.04',
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ inputs.runner }}',
+  ].join('\n');
+  assert.deepEqual(extractLabels(y), ['ubuntu-22.04']);
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.line]),
+    [['ubuntu-22.04', 5]],
+  );
+});
+
+test('an input named jobs does not become the jobs map', () => {
+  const y = [
+    'on:',
+    '  workflow_dispatch:',
+    '    inputs:',
+    '      jobs:',
+    '        default: all',
+    'jobs:',
+    '  build:',
+    '    runs-on: ubuntu-22.04',
+  ].join('\n');
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.job]),
+    [['ubuntu-22.04', 'build']],
+  );
+});
+
+test('a step name and a run: script are not places a runner is asked for', () => {
+  const y = [
+    'jobs:',
+    '  build:',
+    '    strategy:',
+    '      matrix: {os: [ubuntu-24.04]}',
+    '    runs-on: ${{ matrix.os }}',
+    '    steps:',
+    '      - name: build on ubuntu-latest',
+    '        if: contains(matrix.os, "ubuntu-latest")',
+    '        run: |',
+    '          echo ubuntu-latest > /tmp/ubuntu-22.04',
+    '      - run: echo ubuntu-latest',
+  ].join('\n');
+  assert.deepEqual(extractFloatingSites(y), []);
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.line]),
+    [['ubuntu-24.04', 4]],
+  );
+});
+
 test('labelSites: a matrix does not make every mention of a label a site', () => {
   const y = [
     '# this repo moved off ubuntu-latest years ago',
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 545be5a..f43cfd2 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -14,7 +14,7 @@ import {
 } from '../src/labels.mjs';
 import { attributeImageOS, imageDiffs, surveyMigration } from '../src/migration.mjs';
 import { migrationAnnotations, migrationLines, migrationSummaryMarkdown } from '../src/report.mjs';
-import { detect, extractFloatingSites } from '../src/detect.mjs';
+import { detect, extractFloatingSites, extractLabelSites, jobMatcher } from '../src/detect.mjs';
 import { writeLock } from '../src/lock.mjs';
 import { runGuard, runPlan, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
 import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
@@ -574,6 +574,39 @@ test('mid-window, the job on the floating label still reads as migrated', async
   assert.equal(j.migration.surveys[0].observed, 'ubuntu-26.04');
 });
 
+test('a matrix that also asks for the old image by name settles nothing', () => {
+  // [ubuntu-latest, ubuntu-24.04] after the window: a runner on 24.04 is far
+  // more likely to be the pinned leg than the floating label running late.
+  const y = [
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-latest, ubuntu-24.04]',
+    '    runs-on: ${{ matrix.os }}',
+  ].join('\n');
+  const sites = extractFloatingSites(y, 'ci.yml');
+  const others = extractLabelSites(y, 'ci.yml');
+  const here = { job: 'a', file: 'ci.yml' };
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu24', sites, others, here });
+  assert.equal(a.imageOS, null);
+  assert.match(a.note, /also asks for ubuntu-24\.04 by name/);
+  assert.equal(
+    migrationStatus('ubuntu-latest', { now: AFTER, imageOS: a.imageOS }).state,
+    MIGRATION_STATE.SETTLED,
+    'not STALE, which would fail whatever the threshold',
+  );
+});
+
+test('the job id alone decides when the run came from a file the scan never saw', () => {
+  // A reusable workflow reports the caller in GITHUB_WORKFLOW_REF.
+  const sites = [{ label: 'ubuntu-latest', file: 'reusable.yml', line: 6, col: 14, job: 'build' }];
+  const belongs = jobMatcher({ job: 'build', file: 'caller.yml' }, sites);
+  assert.equal(belongs(sites[0]), true);
+  const strict = jobMatcher({ job: 'build', file: 'reusable.yml' }, sites);
+  assert.equal(strict({ ...sites[0], file: 'other.yml' }), false, 'a scanned file still has to match');
+});
+
 test('a matrix leg is trusted for the two images in the window and no others', () => {
   const site = { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28, job: 'a', viaMatrix: true };
   const here = { job: 'a', file: 'ci.yml' };

From 17dcddc93e2a7e20e89635ee53139d521ccb01ba Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 12:10:37 +0800
Subject: [PATCH 08/44] Keep the job rule, the lock's tools and trailing
 comments straight

Five things the sixth review round found, all in the migration lane's
edges.

A trailing comment on a runs-on: line was part of the label, so
`runs-on: ubuntu-latest  # floating on purpose` was not a floating site
at all. Both scanners strip it now.

The drift step summary claimed the lock file was updated under
--no-update-lock. It says what actually happened.

The line that credits the migration for the drift matched on label and
job id, so a matrix leg naming the new image itself read as GitHub
moving you. It now applies the same rival-leg rule the annotations do.

The migration lane diffed the tools the workflows mention even when the
lock file listed others; the retirement lane has always preferred the
lock. The lock is read once at the top of runGuard and both lanes use
it.

Tests for all four, plus the scan is now memoised so a guard run with
both lanes on reads .github/workflows once.
---
 CHANGELOG.md                          | 31 ++++++++++++++++++++----
 README.md                             |  5 +++-
 src/cli.mjs                           | 30 +++++++++++++++--------
 src/detect.mjs                        | 14 +++++++----
 src/report.mjs                        |  6 ++++-
 test/detect.test.mjs                  | 22 +++++++++++++++++
 test/fixtures/workflows-matrix/ci.yml | 11 +++++++++
 test/guard.test.mjs                   | 28 ++++++++++++++++++++++
 test/migration.test.mjs               | 34 +++++++++++++++++++++++++++
 9 files changed, 160 insertions(+), 21 deletions(-)
 create mode 100644 test/fixtures/workflows-matrix/ci.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ddd806..7734201 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -116,11 +116,32 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   longer says the tools were "locked in" a file that does not exist.
 
 - A workflow whose `runs-on:` is a matrix expression had every label-shaped word
-  in the file read as a runner it asks for, including the ones in comments and
-  in `run:` lines. That put retirement and migration annotations on lines nobody
-  can act on, and, once the migration lane existed, could attribute a runner's
-  image to a label the repo never uses. The scan is now scoped to the file's
-  `matrix:` blocks, with comments dropped.
+  in the file read as a runner it asks for, including the ones in comments, in
+  `run:` scripts and in step names. That put retirement and migration
+  annotations on lines nobody can act on, and, once the migration lane existed,
+  could attribute a runner's image to a label the repo never uses. Comments,
+  block scalars and the prose keys (`run`, `name`, `if`) are now skipped. The
+  rest of the file is still read, because a label reaches `runs-on:` through a
+  `workflow_call` input default or an `env:` value as well as through `matrix:`.
+
+- A trailing comment on a `runs-on:` line was part of the label:
+  `runs-on: ubuntu-latest  # floating on purpose` parsed as the whole string, so
+  the line was not a floating site and the migration lane had nothing to say
+  about it. Both scanners strip the comment first.
+
+- The step summary on a drift run said "Lock file `x` updated to image `y`"
+  under `--no-update-lock`, which had left the file alone. It now says the file
+  was left where it was, and why.
+
+- The line that credits the migration for the tool drift followed the same job
+  rule as the annotations only by label. A matrix leg that names the new image
+  itself, next to the floating label, was GitHub moving you; now it is your own
+  pin, and the line is withheld.
+
+- `guard --fail-on-migration` diffed the tools named in the workflow files even
+  when the lock file listed a different set. The retirement lane has always
+  preferred the lock. Both lanes now read `--tools`, then the lock, then the
+  scan.
 
 [1.4.0]: https://github.com/Booyaka101/runner-drift/releases/tag/v1.4.0
 
diff --git a/README.md b/README.md
index 02b5637..3ad52e9 100644
--- a/README.md
+++ b/README.md
@@ -836,7 +836,10 @@ date for one.
 - **Detection is a targeted line scan**, not a full YAML parse (the package has zero
   dependencies). It handles inline, flow-sequence and block-sequence `runs-on:`, and
   resolves `runs-on: ${{ matrix.os }}` by harvesting label-shaped values from the same
-  file. If it misses something, `--tools` and `--label` override it completely.
+  file, skipping comments, block scalars and the keys that hold prose (`run`,
+  `name`, `if`). If it misses something, `--tools` and `--label` override it
+  completely. Which tools get diffed is `--tools` first, then the ones the lock
+  file already records, then the scan.
 - **Resolving `uses:` needs the network, and says so when it cannot.** Each unique
   remote reference is one `raw.githubusercontent.com` read of that exact ref's
   `action.yml`, plus, for the failing ones only, one `api.github.com` release
diff --git a/src/cli.mjs b/src/cli.mjs
index cdad87e..f438c0f 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -294,7 +294,7 @@ function reportRetirement(io, { days, findings }) {
  * images it names. Opt-in like the retirement gate, and like it, useful in a
  * plain lint job with no runner and no lock file.
  */
-async function checkMigration(opts, io, now, imageOS, env, scan, deps) {
+async function checkMigration(opts, io, now, imageOS, env, scan, lock, deps) {
   const days = wholeDays(opts['fail-on-migration'], '--fail-on-migration', io);
   if (days === null) return null;
   const scanned = await scanForLane(scan, io, 'no floating labels to check for migration');
@@ -306,7 +306,8 @@ async function checkMigration(opts, io, now, imageOS, env, scan, deps) {
     if (!byLabel.has(site.label)) byLabel.set(site.label, []);
     byLabel.get(site.label).push(site);
   }
-  const tools = parseToolList(opts.tools) ?? scanned.tools;
+  const locked = lock?.tools ? Object.keys(lock.tools) : null;
+  const tools = parseToolList(opts.tools) ?? (locked?.length ? locked : scanned.tools);
   const load = deps.loadManifest ?? loadManifest;
   const here = runningJob(env);
   const surveys = await Promise.all(
@@ -342,13 +343,19 @@ async function explainDrift({ migration, lock, label, scan, env }) {
 
   const m = migrationBetween(lock.label, label);
   if (!m) return null;
-  const sites = migration
-    ? migration.surveys.flatMap((s) => s.sites)
-    : (await scan()).floatingSites;
-  const ours = sites.filter((site) => site.label === m.label);
+  const scanned = await scan();
+  const sites = scanned.floatingSites;
+  const others = scanned.labelSites;
   const here = runningJob(env);
-  const used = here ? ours.some(jobMatcher(here, sites)) : ours.length > 0;
-  return used ? m : null;
+  const belongs = here ? jobMatcher(here, [...sites, ...others]) : null;
+  const ours = sites.filter((site) => site.label === m.label && (!belongs || belongs(site)));
+
+  // A matrix that asks for this runner's own label by name: the job may simply
+  // have been scheduled onto that leg, and then nothing moved.
+  const rival = others.some(
+    (site) => site.viaMatrix && site.label === label && (!belongs || belongs(site)),
+  );
+  return ours.some((site) => !site.viaMatrix) || (ours.length > 0 && !rival) ? m : null;
 }
 
 /** One stderr line per floating label whose migration fails the gate. */
@@ -553,6 +560,9 @@ async function checkOwnRunner(opts, io, env, deps, window) {
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
   const scan = scanner(opts);
+  // Read before the lanes run: the migration lane diffs the tools the lock
+  // watches, which is not always what the workflow files mention.
+  const lock = await readLock(lockFile);
   // Writing the lock is the default; `main` resolves --no-update-lock into it,
   // but runGuard is exported and a caller building options by hand has neither.
   const updateLock = opts['update-lock'] !== false;
@@ -584,7 +594,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // two images right now" and "this job ran on the new one".
   let migration = null;
   if (opts['fail-on-migration'] !== undefined) {
-    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, deps);
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, lock, deps);
     if (!migration) return EXIT_USAGE;
     if (!opts.json && migration.surveys.length) {
       out(io.stdout, migrationReport(migration.surveys));
@@ -630,7 +640,6 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     return retiring || migrating || own?.failing ? EXIT_DRIFT : EXIT_OK;
   }
 
-  const lock = await readLock(lockFile);
   let label = (imageOS && IMAGE_OS_TO_LABEL[imageOS.toLowerCase()]) || lock?.label || null;
 
   if (!label) {
@@ -805,6 +814,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     diffs,
     attribution: attributionMap,
     approximate,
+    written: updateLock,
     lockFile,
   });
   if (opts.summary) await writeStepSummary(summary);
diff --git a/src/detect.mjs b/src/detect.mjs
index a33e0d2..e20a5f1 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -119,6 +119,11 @@ export function commandsInScript(script) {
 }
 
 /** 1-indexed column of the label inside a raw scalar that may be padded or quoted. */
+/** A YAML inline comment: a `#` at the start of the line or after a space. */
+function stripComment(text) {
+  return text.replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+}
+
 function labelColumn(start, raw) {
   const lead = raw.length - raw.trimStart().length;
   return start + lead + (/^['"]/.test(raw.trim()) ? 1 : 0) + 1;
@@ -158,7 +163,8 @@ function scanRunsOn(lines) {
     const m = lines[i].match(/^([ \t]*)runs-on:[ \t]*([^\r\n]*)/);
     if (!m) continue;
     const baseIndent = m[1].length;
-    const value = m[2].trim();
+    const raw = stripComment(m[2]);
+    const value = raw.trim();
     const valueStart = lines[i].length - m[2].length;
 
     // Anchored on the `runs-on:` line itself: the set is the target, so pointing
@@ -172,7 +178,7 @@ function scanRunsOn(lines) {
         if (l.trim() === '') continue;
         if (indentOf(l) <= baseIndent) break;
         const dash = l.match(/^([ \t]*-[ \t]*)([^\r\n]*)/);
-        const item = dash ? dash[2] : l.trim();
+        const item = stripComment(dash ? dash[2] : l.trim()).trim();
         if (item.includes('${{')) expression = target.expression = true;
         else push(item, j + 1, labelColumn(dash ? dash[1].length : indentOf(l), item));
         i = j;
@@ -187,7 +193,7 @@ function scanRunsOn(lines) {
     } else if (value.includes('${{')) {
       expression = target.expression = true;
     } else {
-      push(value, i + 1, labelColumn(valueStart, m[2]));
+      push(value, i + 1, labelColumn(valueStart, raw));
     }
   }
   return { found, targets, expression };
@@ -211,7 +217,7 @@ function matrixLabels(lines) {
   const found = [];
   let scalar = null;
   for (let i = 0; i < lines.length; i++) {
-    const text = lines[i].replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+    const text = stripComment(lines[i]);
     if (scalar !== null) {
       if (!text.trim() || indentOf(text) > scalar) continue;
       scalar = null;
diff --git a/src/report.mjs b/src/report.mjs
index 0f346bb..fb27549 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -201,7 +201,11 @@ export function stepSummaryMarkdown({
   });
   lines.push(...markdownTable(['Tool', 'Locked', 'Now', 'Change', 'Shipped by'], rows));
   lines.push('');
-  lines.push(`Lock file \`${lockFile}\` updated to image \`${toImage}\`.`);
+  lines.push(
+    written
+      ? `Lock file \`${lockFile}\` updated to image \`${toImage}\`.`
+      : `Lock file \`${lockFile}\` left at image \`${fromImage}\`: \`--no-update-lock\` is set.`,
+  );
   return `${lines.join('\n')}\n`;
 }
 
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 6dbba31..d4061eb 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -249,6 +249,28 @@ test('labelSites: a matrix does not make every mention of a label a site', () =>
   );
 });
 
+test('a trailing comment is not part of the label', () => {
+  const y = [
+    'jobs:',
+    '  a:',
+    '    runs-on: ubuntu-latest  # floating on purpose',
+    '  b:',
+    '    runs-on: [self-hosted, linux]  # the fleet',
+    '  c:',
+    '    runs-on:',
+    '      - macos-14   # the mac leg',
+  ].join('\n');
+  assert.deepEqual(
+    extractFloatingSites(y).map((s) => [s.label, s.line, s.col]),
+    [['ubuntu-latest', 3, 14]],
+  );
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => s.label),
+    ['linux', 'macos-14'],
+  );
+  assert.deepEqual(extractRunsOnTargets(y)[1].labels, [SELF_HOSTED, 'linux']);
+});
+
 test('labelSites: floating labels are never a site', () => {
   assert.deepEqual(extractLabelSites('    runs-on: ubuntu-latest\n'), []);
 });
diff --git a/test/fixtures/workflows-matrix/ci.yml b/test/fixtures/workflows-matrix/ci.yml
new file mode 100644
index 0000000..ec7f98a
--- /dev/null
+++ b/test/fixtures/workflows-matrix/ci.yml
@@ -0,0 +1,11 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, ubuntu-26.04]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - run: node --version
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 6301400..bef04f1 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -283,6 +283,34 @@ test('runGuard writes the lock by default, with no update-lock key at all', asyn
   }
 });
 
+test('the drift summary does not claim a lock update that --no-update-lock stopped', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const summaryFile = path.join(dir, 'summary.md');
+  await writeFile(summaryFile, '', 'utf8');
+  const prev = process.env.GITHUB_STEP_SUMMARY;
+  process.env.GITHUB_STEP_SUMMARY = summaryFile;
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-22.04',
+        imageOS: 'ubuntu22',
+        imageVersion: '20260623.199.1',
+        tools: { 'Node.js': { versions: ['18.0.0'], source: 'probe' } },
+      },
+      lockFile,
+    );
+    await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false });
+    const md = await readFile(summaryFile, 'utf8');
+    assert.match(md, /left at image `20260623\.199\.1`/);
+    assert.ok(!md.includes('updated to image'), 'nothing was updated');
+  } finally {
+    if (prev === undefined) delete process.env.GITHUB_STEP_SUMMARY;
+    else process.env.GITHUB_STEP_SUMMARY = prev;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('--no-update-lock leaves the lock alone', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index f43cfd2..91ff260 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -685,6 +685,40 @@ test('--json names the explanation without --fail-on-migration too', async () =>
   assert.equal(j.migration, undefined, 'the lane itself still needs the flag');
 });
 
+test('a matrix leg pinned to the new image is not the migration arriving', async () => {
+  // matrix: [ubuntu-latest, ubuntu-26.04]. This runner is on 26.04, which the
+  // job asks for by name, so the jump from the lock is not GitHub's doing.
+  const r = await guardAcrossTheMove(
+    { workflows: path.join(FIXTURES, 'workflows-matrix') },
+    DURING,
+  );
+  assert.ok(!r.stdout.includes('Explained by'), 'the pinned leg asks for 26.04 itself');
+  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+});
+
+test('the migration lane diffs the tools the lock watches', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'runner-drift-migration-'));
+  const lockFile = path.join(dir, 'runner-lock.json');
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-24.04',
+        imageOS: 'ubuntu24',
+        imageVersion: '20260907.300.1',
+        tools: { Python: { versions: ['3.12.3'], source: 'probe' } },
+      },
+      lockFile,
+    );
+    const r = await guard({ 'fail-on-migration': '30', 'lock-file': lockFile, json: true });
+    const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+    const tools = j.migration.surveys[0].toolDiffs.map((d) => d.tool);
+    assert.ok(tools.includes('Python'), 'the locked tool is in the diff');
+    assert.ok(!tools.includes('Node.js'), 'and the ones only the workflows mention are not');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('a repo that pins its runners is not told GitHub moved it', async () => {
   // The same 24.04 -> 26.04 jump, in a repo whose workflows never say
   // ubuntu-latest: someone bumped the pin by hand and owns the upgrade.

From 51fcaf71cd8cd95138a5c07787473d1c684f5720 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 12:25:59 +0800
Subject: [PATCH 09/44] One attribution rule, read from one place

The seventh review round found the lock read I hoisted last commit now
runs before the "not a GitHub-hosted runner" skip, so a lock this
version cannot parse turned a clean skip into exit 2 and stopped the
retirement and migration lanes from running at all. The read is lazy
again: the migration lane takes what it can get, the drift lane is the
one that cannot work without the file and is still where the error
surfaces.

jobKeys kept the raw YAML key, so `"build":` never matched the bare
GITHUB_JOB Actions exports. Quoted ids are unquoted, like labels.

explainDrift and attributeImageOS had grown into the same job rule
written twice: scope the sites to the running job, is there a direct
one, is there a matrix leg naming the runner's own label instead.
That rule is now labelOwnership in detect.mjs and both callers read it.
Behaviour is unchanged; the two differ in what they do with the answer,
which is all that is left in each.

Also moves labelColumn's doc comment back onto labelColumn.
---
 CHANGELOG.md                                  |  3 ++
 src/cli.mjs                                   | 45 ++++++++++---------
 src/detect.mjs                                | 27 ++++++++++-
 src/index.mjs                                 |  1 +
 src/migration.mjs                             | 32 +++++--------
 test/detect.test.mjs                          |  9 ++++
 test/fixtures/workflows-quoted-job/latest.yml | 10 +++++
 test/guard.test.mjs                           | 19 ++++++++
 test/migration.test.mjs                       | 18 ++++++++
 9 files changed, 121 insertions(+), 43 deletions(-)
 create mode 100644 test/fixtures/workflows-quoted-job/latest.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7734201..d734978 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -100,6 +100,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   the number beside it can no longer disagree. Some `runners` countdowns move by
   a day: `2.335.1 runtime ends 2026-09-24` was "(16 days)" on 2026-09-09 and is
   now "(15 days)", which is the number of days you can actually still run it.
+  `--fail-on-deprecation` and `--fail-on-retirement` compare against that same
+  number, so a threshold sitting exactly on a boundary can fire a day later than
+  it did in 1.3.0.
 
 - `resolveManifestVersions` moved from `src/cli.mjs` to `src/manifest.mjs`, where
   the rest of the manifest reading lives, and is re-exported from `cli.mjs` so
diff --git a/src/cli.mjs b/src/cli.mjs
index f438c0f..6dd26c0 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -25,7 +25,7 @@ import {
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { imageDiffs, surveyMigration } from './migration.mjs';
 import { attribute, commitWindow, attributeChanges, listManifestCommits, manifestAtSha } from './history.mjs';
-import { detect, jobMatcher, runningJob, SELF_HOSTED } from './detect.mjs';
+import { detect, labelOwnership, runningJob, SELF_HOSTED } from './detect.mjs';
 import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
@@ -237,10 +237,10 @@ function summarise(io, items, keyOf, lineOf) {
  * label fallback and the drift explanation want the same directory, and reading
  * it five times to get the same answer is five times the IO for nothing.
  */
-function scanner(opts) {
-  const dir = opts.workflows ?? path.join('.github', 'workflows');
+/** Run `fn` at most once, however many lanes ask for its answer. */
+function once(fn) {
   let pending = null;
-  return () => (pending ??= detect(dir));
+  return () => (pending ??= fn());
 }
 
 /**
@@ -344,18 +344,16 @@ async function explainDrift({ migration, lock, label, scan, env }) {
   const m = migrationBetween(lock.label, label);
   if (!m) return null;
   const scanned = await scan();
-  const sites = scanned.floatingSites;
-  const others = scanned.labelSites;
-  const here = runningJob(env);
-  const belongs = here ? jobMatcher(here, [...sites, ...others]) : null;
-  const ours = sites.filter((site) => site.label === m.label && (!belongs || belongs(site)));
-
-  // A matrix that asks for this runner's own label by name: the job may simply
-  // have been scheduled onto that leg, and then nothing moved.
-  const rival = others.some(
-    (site) => site.viaMatrix && site.label === label && (!belongs || belongs(site)),
-  );
-  return ours.some((site) => !site.viaMatrix) || (ours.length > 0 && !rival) ? m : null;
+  // `label` is this runner's own: a matrix leg naming it is a pin the repo
+  // chose, not the window moving the job, so the explanation is withheld.
+  const { direct, asked, rival } = labelOwnership({
+    label: m.label,
+    observed: label,
+    sites: scanned.floatingSites,
+    others: scanned.labelSites,
+    here: runningJob(env),
+  });
+  return direct || (asked && !rival) ? m : null;
 }
 
 /** One stderr line per floating label whose migration fails the gate. */
@@ -559,10 +557,13 @@ async function checkOwnRunner(opts, io, env, deps, window) {
 
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
-  const scan = scanner(opts);
-  // Read before the lanes run: the migration lane diffs the tools the lock
-  // watches, which is not always what the workflow files mention.
-  const lock = await readLock(lockFile);
+  const scan = once(() => detect(opts.workflows ?? path.join('.github', 'workflows')));
+  // The migration lane diffs the tools the lock watches, which is not always
+  // what the workflow files mention. It reads the lock leniently: a lock this
+  // version cannot parse is an error for the drift lane below, which is the
+  // only lane that cannot work without it, and only once there is an image to
+  // diff at all.
+  const getLock = once(() => readLock(lockFile));
   // Writing the lock is the default; `main` resolves --no-update-lock into it,
   // but runGuard is exported and a caller building options by hand has neither.
   const updateLock = opts['update-lock'] !== false;
@@ -594,7 +595,8 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // two images right now" and "this job ran on the new one".
   let migration = null;
   if (opts['fail-on-migration'] !== undefined) {
-    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, lock, deps);
+    const known = await getLock().catch(() => null);
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, known, deps);
     if (!migration) return EXIT_USAGE;
     if (!opts.json && migration.surveys.length) {
       out(io.stdout, migrationReport(migration.surveys));
@@ -640,6 +642,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     return retiring || migrating || own?.failing ? EXIT_DRIFT : EXIT_OK;
   }
 
+  const lock = await getLock();
   let label = (imageOS && IMAGE_OS_TO_LABEL[imageOS.toLowerCase()]) || lock?.label || null;
 
   if (!label) {
diff --git a/src/detect.mjs b/src/detect.mjs
index e20a5f1..2123a58 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -118,12 +118,12 @@ export function commandsInScript(script) {
   return [...found];
 }
 
-/** 1-indexed column of the label inside a raw scalar that may be padded or quoted. */
 /** A YAML inline comment: a `#` at the start of the line or after a space. */
 function stripComment(text) {
   return text.replace(/(^|[ \t])#[^\r\n]*$/, '$1');
 }
 
+/** 1-indexed column of the label inside a raw scalar that may be padded or quoted. */
 function labelColumn(start, raw) {
   const lead = raw.length - raw.trimStart().length;
   return start + lead + (/^['"]/.test(raw.trim()) ? 1 : 0) + 1;
@@ -272,7 +272,7 @@ function jobKeys(lines) {
     const m = lines[i].match(/^([ \t]*)([^-\s#][^:\r\n]*):/);
     if (m) {
       const indent = m[1].length;
-      const key = m[2].trim();
+      const key = m[2].trim().replace(/^(['"])(.*)\1$/, '$2');
       if (jobsIndent === null) {
         // Top level only: `on.workflow_dispatch.inputs.jobs` is not the map.
         if (key === 'jobs' && indent === 0) jobsIndent = indent;
@@ -361,6 +361,29 @@ export function jobMatcher(here, sites = []) {
   return (site) => siteInJob(site, at);
 }
 
+/**
+ * Who asked for `label` here, and whether a matrix leg asks for `observed` too.
+ *
+ * `scoped` is whether a running job was identified at all; without one every
+ * site in the repository is in scope and the caller has to decide how much that
+ * is worth. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
+ * the label through a matrix, and `rival` is a matrix leg naming `observed`,
+ * which the runner is as likely to be serving as the floating one.
+ */
+export function labelOwnership({ label, observed = null, sites = [], others = [], here = null }) {
+  const belongs = jobMatcher(here, [...sites, ...others]);
+  const inScope = here ? belongs : () => true;
+  const mine = sites.filter((site) => site.label === label && inScope(site));
+  return {
+    scoped: Boolean(here),
+    direct: mine.some((site) => !site.viaMatrix),
+    asked: mine.length > 0,
+    rival:
+      observed !== null
+      && others.some((site) => site.viaMatrix && site.label === observed && inScope(site)),
+  };
+}
+
 /** Is this `runs-on:` site the one the running job was scheduled from? */
 export function siteInJob(site, here) {
   if (!here || !site?.job || site.job !== here.job) return false;
diff --git a/src/index.mjs b/src/index.mjs
index 84de542..fd4b9e9 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -21,6 +21,7 @@ export {
   extractFloatingSites,
   extractRunsOnTargets,
   jobMatcher,
+  labelOwnership,
   runningJob,
   siteInJob,
   extractRunScripts,
diff --git a/src/migration.mjs b/src/migration.mjs
index c61c386..f621639 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -12,7 +12,7 @@
  */
 
 import { IMAGE_OS_TO_LABEL, migrationFor, migrationStatus } from './labels.mjs';
-import { jobMatcher } from './detect.mjs';
+import { labelOwnership } from './detect.mjs';
 import { loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
 import { errorText } from './http.mjs';
@@ -55,38 +55,30 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
   const observed = IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null;
-  const belongs = jobMatcher(here, [...sites, ...others]);
-  const mine = sites.filter(belongs);
+  const { direct, asked, rival } = labelOwnership({ label, observed, sites, others, here });
 
-  if (mine.some((site) => !site.viaMatrix)) return { imageOS, note: null };
-
-  // A matrix that lists the observed label itself: this runner is at least as
-  // likely to be serving that leg as the floating one, so neither is evidence.
-  const rival =
-    observed !== null
-    && others.some(
-      (site) => site.viaMatrix && site.label === observed && (here ? belongs(site) : true),
-    );
+  if (here && direct) return { imageOS, note: null };
   const endpoint = !rival && (observed === m?.from || observed === m?.to);
 
-  if (mine.length) {
+  if (!here) {
     if (endpoint) return { imageOS, note: null };
     return {
       imageOS: null,
       note: rival
-        ? `Job "${here.job}" reaches ${label} through a matrix that also asks for ${observed} `
-          + 'by name, so this runner may be serving that leg instead.'
-        : `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
-          + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
+        ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
+        : `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
     };
   }
-  if (!here) {
+
+  if (asked) {
     if (endpoint) return { imageOS, note: null };
     return {
       imageOS: null,
       note: rival
-        ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
-        : `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+        ? `Job "${here.job}" reaches ${label} through a matrix that also asks for ${observed} `
+          + 'by name, so this runner may be serving that leg instead.'
+        : `Job "${here.job}" reaches ${label} through a matrix and ran on ${observed ?? imageOS}, `
+          + 'which is neither image in the window, so this runner is treated as a different matrix leg.',
     };
   }
   return {
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index d4061eb..36aca5f 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -249,6 +249,15 @@ test('labelSites: a matrix does not make every mention of a label a site', () =>
   );
 });
 
+test('a quoted job id is recorded without its quotes', () => {
+  const y = [
+    'jobs:',
+    '  "build":',
+    '    runs-on: ubuntu-latest',
+  ].join('\n');
+  assert.equal(extractFloatingSites(y)[0].job, 'build');
+});
+
 test('a trailing comment is not part of the label', () => {
   const y = [
     'jobs:',
diff --git a/test/fixtures/workflows-quoted-job/latest.yml b/test/fixtures/workflows-quoted-job/latest.yml
new file mode 100644
index 0000000..59582b2
--- /dev/null
+++ b/test/fixtures/workflows-quoted-job/latest.yml
@@ -0,0 +1,10 @@
+name: ci
+on: [push]
+
+jobs:
+  "build":
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index bef04f1..a6290cd 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -311,6 +311,25 @@ test('the drift summary does not claim a lock update that --no-update-lock stopp
   }
 });
 
+test('a lock this version cannot read does not swallow the self-hosted skip', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  try {
+    await writeFile(lockFile, JSON.stringify({ schemaVersion: 99, label: 'ubuntu-24.04' }), 'utf8');
+    const r = await guard({
+      tools: 'node',
+      'lock-file': lockFile,
+      'fail-on-migration': '0',
+      'as-of': '2026-09-20',
+      workflows: path.join(FIXTURES, 'workflows-migration'),
+    }, {});
+    assert.equal(r.code, EXIT_OK, 'no ImageVersion is a skip, not a lock error');
+    assert.match(r.stdout, /not a GitHub-hosted runner/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('--no-update-lock leaves the lock alone', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 91ff260..8decf88 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -685,6 +685,24 @@ test('--json names the explanation without --fail-on-migration too', async () =>
   assert.equal(j.migration, undefined, 'the lane itself still needs the flag');
 });
 
+test('a quoted job id is the same job GITHUB_JOB names', async () => {
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '0',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-quoted-job'),
+    },
+    { ImageOS: 'ubuntu26', ...inJob('build') },
+    DURING,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const s = j.migration.surveys[0];
+  assert.equal(s.observed, 'ubuntu-26.04', 'the runner is attributed to "build"');
+  assert.equal(s.state, MIGRATION_STATE.MIGRATED);
+  assert.deepEqual(s.notes, []);
+});
+
 test('a matrix leg pinned to the new image is not the migration arriving', async () => {
   // matrix: [ubuntu-latest, ubuntu-26.04]. This runner is on 26.04, which the
   // job asks for by name, so the jump from the lock is not GitHub's doing.

From 52450bd2de68d288f1f0df178df6d98b7a0d4e67 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 12:39:42 +0800
Subject: [PATCH 10/44] Keep the two new line scanners linear, and let a step
 keep its keys

Both regexes added on this branch let an indent run and the text after
it claim the same spaces with a mandatory `:` between them, which is the
js/polynomial-redos shape this repo fixed in 1.2.0 and wrote a linearity
test for. 16k spaces on one line cost 81ms in the matrix scan and 332ms
in the manifest header, so a long enough line hangs the scan. Both keys
now have to start with a non-space, and both inputs join the existing
pathological-input cases.

The block-scalar skip measured the indent before the `- `, so a step
written `- run: |` swallowed its own env: and with: keys. It measures
the key's own column now.
---
 src/detect.mjs         | 13 +++++++++----
 src/manifest.mjs       |  7 ++++---
 test/detect.test.mjs   | 22 ++++++++++++++++++++++
 test/manifest.test.mjs |  1 +
 4 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/src/detect.mjs b/src/detect.mjs
index 2123a58..52a7203 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -222,14 +222,19 @@ function matrixLabels(lines) {
       if (!text.trim() || indentOf(text) > scalar) continue;
       scalar = null;
     }
-    const key = text.match(/^([ \t]*)(?:-[ \t]+)?([^:\r\n]*):([^\r\n]*)$/);
+    // The key cannot start with a space: nothing mandatory separates it from the
+    // indent, and both matching whitespace is how a line of spaces with no colon
+    // went quadratic in 1.2.0.
+    const key = text.match(/^([ \t]*)(-[ \t]+)?([^:\s][^:\r\n]*)?:([^\r\n]*)$/);
     if (key) {
       // `run: |` and friends: the body below is shell or prose, not YAML values.
-      if (/^[|>]/.test(key[3].trim())) {
-        scalar = key[1].length;
+      // A dashed key owns the column the dash sits in, so the step's own
+      // siblings (`env:`, `with:`) are not read as part of the script.
+      if (/^[|>]/.test(key[4].trim())) {
+        scalar = key[1].length + (key[2]?.length ?? 0);
         continue;
       }
-      if (PROSE_KEYS.has(key[2].trim().toLowerCase())) continue;
+      if (PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase())) continue;
     }
     for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
       if (LABEL_SHAPE.test(tok[0])) {
diff --git a/src/manifest.mjs b/src/manifest.mjs
index 62d5c94..96ce1fa 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -208,9 +208,10 @@ export function parseManifest(markdown, label = null) {
       continue;
     }
 
-    // `[^:\r\n]+` up to the colon and no `$` at the end: the key cannot run past
-    // its own delimiter and there is no failure condition to backtrack over.
-    const headerM = line.match(/^[ \t]*-[ \t]+([^:\r\n]+):[ \t]*([^\r\n]+)/);
+    // The key starts with a non-space, so the indent run and the key cannot both
+    // claim the same spaces: without that, a dashed bullet whose colon never
+    // arrives makes the engine try every split of a long whitespace run.
+    const headerM = line.match(/^[ \t]*-[ \t]+([^:\s][^:\r\n]*):[ \t]*([^\r\n]+)/);
     if (headerM) {
       const key = headerM[1].trim().toLowerCase();
       const field = Object.hasOwn(HEADER_FIELDS, key) ? HEADER_FIELDS[key] : null;
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 36aca5f..ba40141 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -249,6 +249,26 @@ test('labelSites: a matrix does not make every mention of a label a site', () =>
   );
 });
 
+test('a dashed run: block does not swallow the step keys under it', () => {
+  const y = [
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ matrix.os }}',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-22.04]',
+    '    steps:',
+    '      - run: |',
+    '          echo ubuntu-20.04',
+    '        env:',
+    '          FALLBACK: ubuntu-18.04',
+  ].join('\n');
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => s.label),
+    ['ubuntu-22.04', 'ubuntu-18.04'],
+  );
+});
+
 test('a quoted job id is recorded without its quotes', () => {
   const y = [
     'jobs:',
@@ -336,6 +356,8 @@ test('the line scanners stay linear on pathological input', () => {
     ['extractLabels', () => extractLabels(`runs-on:${pad}${CR}x`)],
     ['extractLabelSites', () => extractLabelSites(`runs-on:${pad}${CR}x`)],
     ['commandsInScript after sudo', () => commandsInScript(`sudo${pad}x`)],
+    ['a matrix scan over an indent with no colon', () => extractLabelSites(`runs-on: \${{ matrix.os }}\n${pad}x`)],
+    ['a matrix scan over a dashed indent', () => extractLabelSites(`runs-on: \${{ matrix.os }}\n${pad}-${pad}x`)],
   ];
 
   for (const [label, fn] of cases) {
diff --git a/test/manifest.test.mjs b/test/manifest.test.mjs
index 7e31306..6c47cc4 100644
--- a/test/manifest.test.mjs
+++ b/test/manifest.test.mjs
@@ -118,6 +118,7 @@ test('parseManifest stays linear on pathological input', () => {
     ['a parenthesis that is never closed', `- Tool 1.0 (${pad}x`],
     ['spaces then an unclosed (default', `- Tool 1.0${pad}(default`],
     ['a bullet body with no version', `- ${'a'.repeat(240_000)}:${pad}`],
+    ['a dashed bullet whose colon never arrives', `- ${pad}x`],
     ['an OS Version line with a stray CR', `- OS Version:${pad}${CR}`],
     ['an Image Version line with a stray CR', `- Image Version:${pad}${CR}`],
     ['a table cell full of open parens', `| Name | V |\n|---|---|\n| a${'('.repeat(60_000)} | 1.0 |`],

From 7ecf9c88ed925452fa7d8362ee395fbcee0ef72c Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 12:56:00 +0800
Subject: [PATCH 11/44] The step summary names the cause too, and one manifest
 diff serves both lanes

The explanation of drift caused by an announced move was in stdout and in
--json but not in the step summary, which is where most people read a
guard run. It sits above the drift table now.

runsOnTargetsFor walked .github/workflows itself, so guard on a
self-hosted runner scanned twice. It takes the memoised scan, and
runners builds one of its own.

The two lanes that compare two labels' manifests had the same
resolve/split/diff block written twice. diffManifestTools in manifest.mjs
is that block, and plan and the migration lane share it. The
missing-on-both rule now changes in one place.

Changelog: the plan transcript was missing the deprecation-deadline line
the command always prints, and the tools bullet named the retirement lane
where it meant the drift lane.
---
 CHANGELOG.md            |  7 ++++---
 README.md               |  2 ++
 src/cli.mjs             | 28 +++++++++++++++-------------
 src/index.mjs           |  2 +-
 src/manifest.mjs        | 17 +++++++++++++++++
 src/migration.mjs       | 12 ++++--------
 src/report.mjs          |  9 +++++++++
 test/migration.test.mjs | 20 +++++++++++++++++++-
 8 files changed, 71 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d734978..b91161c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   ubuntu-latest moves from ubuntu-24.04 to ubuntu-26.04. The rollout starts 2026-10-19 (18 days) and finishes 2026-11-19 (49 days).
   announced 2026-09-17; source actions/runner-images#14748 https://github.com/actions/runner-images/issues/14748
   ubuntu-24.04 -> ubuntu-26.04 (images 20260907.300.1 -> 20260907.131.1)
+  ubuntu-24.04 has no announced deprecation deadline in runner-drift's table.
 
   OS 24.04.5 LTS -> 26.04.1 LTS  MAJOR
   Kernel 6.17.0-1022-azure -> 7.0.0-1012-azure  MAJOR
@@ -142,9 +143,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   pin, and the line is withheld.
 
 - `guard --fail-on-migration` diffed the tools named in the workflow files even
-  when the lock file listed a different set. The retirement lane has always
-  preferred the lock. Both lanes now read `--tools`, then the lock, then the
-  scan.
+  when the lock file listed a different set. The drift lane has always preferred
+  the lock, since that is the list it is about to compare. Both lanes now read
+  `--tools`, then the lock, then the scan.
 
 [1.4.0]: https://github.com/Booyaka101/runner-drift/releases/tag/v1.4.0
 
diff --git a/README.md b/README.md
index 3ad52e9..24cf908 100644
--- a/README.md
+++ b/README.md
@@ -297,6 +297,8 @@ Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04
   CMake 3.31.6 -> 4.4.3  MAJOR  [20260907.131.1] https://github.com/actions/runner-images/commit/90ebb6f508835349239c3823c663eba7af98f23d
 ```
 
+The step summary carries the same line, above the drift table.
+
 Exit codes and the `--fail-on` thresholds are untouched by any of this. An
 anomaly fails whatever the threshold, the same rule `--fail-on-retirement` uses
 for a label already past its date. `--json` gains a `migration` block, and the
diff --git a/src/cli.mjs b/src/cli.mjs
index 6dd26c0..d8362d7 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -22,7 +22,7 @@ import {
   migrationStatus,
   normaliseLabel,
 } from './labels.mjs';
-import { loadManifest, resolveManifestVersions } from './manifest.mjs';
+import { diffManifestTools, loadManifest, resolveManifestVersions } from './manifest.mjs';
 import { imageDiffs, surveyMigration } from './migration.mjs';
 import { attribute, commitWindow, attributeChanges, listManifestCommits, manifestAtSha } from './history.mjs';
 import { detect, labelOwnership, runningJob, SELF_HOSTED } from './detect.mjs';
@@ -243,6 +243,11 @@ function once(fn) {
   return () => (pending ??= fn());
 }
 
+/** One workflow scan per command, shared by every lane that wants it. */
+function scanner(opts) {
+  return once(() => detect(opts.workflows ?? path.join('.github', 'workflows')));
+}
+
 /**
  * The workflow scan the two lint lanes start from, or null when there is no
  * workflow directory — which is a notice on both streams, not an error.
@@ -396,8 +401,8 @@ function reportDeprecation(io, survey) {
  * at-risk runner actually serves. Absent workflows are silent: `runners` is
  * documented as needing no repository checkout.
  */
-async function runsOnTargetsFor(opts) {
-  const scanned = await detect(opts.workflows ?? path.join('.github', 'workflows'));
+async function runsOnTargetsFor(scan) {
+  const scanned = await scan();
   return scanned.missing ? [] : scanned.runsOnTargets;
 }
 
@@ -530,7 +535,7 @@ export async function runInit(opts, io = process) {
  * no token. That is the common case, not an error path, and the caller then
  * behaves exactly as it did before this lane existed.
  */
-async function checkOwnRunner(opts, io, env, deps, window) {
+async function checkOwnRunner(opts, io, env, deps, window, scan) {
   const name = env.RUNNER_NAME;
   const token = env.GITHUB_TOKEN || env.GH_TOKEN || env.INPUT_GITHUB_TOKEN;
   if (!name || !token) return null;
@@ -541,7 +546,7 @@ async function checkOwnRunner(opts, io, env, deps, window) {
     ...window,
     now: deps.now ?? new Date(),
     onlyRunnerName: name,
-    runsOnTargets: await runsOnTargetsFor(opts),
+    runsOnTargets: await runsOnTargetsFor(scan),
     fetch: deps.fetchJson,
   });
   if (survey.status === SURVEY_STATUS.OK && !survey.groups.length) {
@@ -557,7 +562,7 @@ async function checkOwnRunner(opts, io, env, deps, window) {
 
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
-  const scan = once(() => detect(opts.workflows ?? path.join('.github', 'workflows')));
+  const scan = scanner(opts);
   // The migration lane diffs the tools the lock watches, which is not always
   // what the workflow files mention. It reads the lock leniently: a lock this
   // version cannot parse is an error for the drift lane below, which is the
@@ -628,7 +633,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     // No hosted image to diff, but a self-hosted runner still has an agent
     // version with a date on it. Without a token this is a no-op and the skip
     // above is the whole output, exactly as in 1.1.0.
-    const own = await checkOwnRunner(opts, io, env, deps, window);
+    const own = await checkOwnRunner(opts, io, env, deps, window, scan);
     if (opts.json && (own || migration || retirement)) {
       const payload = {};
       if (own) payload.runners = own;
@@ -812,6 +817,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
 
   const summary = stepSummaryMarkdown({
     label,
+    explains: explained,
     fromImage: lock.imageVersion ?? '(unknown)',
     toImage: imageVersion,
     diffs,
@@ -929,11 +935,7 @@ export async function runPlan(opts, io = process, deps = {}) {
     }
   }
 
-  const ra = resolveManifestVersions(a, tools);
-  const rb = resolveManifestVersions(b, tools);
-  const missingBoth = tools.filter((t) => ra.missing.includes(t) && rb.missing.includes(t));
-  const comparable = tools.filter((t) => !missingBoth.includes(t));
-  const diffs = comparable.map((t) => diffTool(t, ra.map[t] ?? null, rb.map[t] ?? null));
+  const { diffs, notOnManifest: missingBoth } = diffManifestTools(a, b, tools);
 
   if (opts.json) {
     out(
@@ -996,7 +998,7 @@ export async function runRunners(opts, io = process, env = process.env, deps = {
   const survey = await surveyRunners(resolved.scope, {
     ...window,
     now: deps.now ?? new Date(),
-    runsOnTargets: await runsOnTargetsFor(opts),
+    runsOnTargets: await runsOnTargetsFor(scanner(opts)),
     fetch: deps.fetchJson,
   });
 
diff --git a/src/index.mjs b/src/index.mjs
index fd4b9e9..d0ff612 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -1,7 +1,7 @@
 /** Programmatic entry point. The CLI is `src/cli.mjs`. */
 
 export { main, runInit, runGuard, runPlan, runRunners, runActions, resolveManifestVersions, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from './cli.mjs';
-export { parseManifest, loadManifest, manifestUrl, lookupTool } from './manifest.mjs';
+export { parseManifest, loadManifest, manifestUrl, lookupTool, diffManifestTools } from './manifest.mjs';
 export { IMAGE_FIELDS, attributeImageOS, imageDiffs, surveyMigration } from './migration.mjs';
 export {
   listManifestCommits,
diff --git a/src/manifest.mjs b/src/manifest.mjs
index 96ce1fa..7ed31c3 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -18,6 +18,7 @@
  * Android SDK tables are skipped outright for the same reason.
  */
 
+import { diffToolMaps } from './diff.mjs';
 import { fetchText, NotFoundError, DriftError } from './http.mjs';
 import { RAW_BASE, pathForLabel } from './labels.mjs';
 import { manifestCandidates } from './tools.mjs';
@@ -346,6 +347,22 @@ export function lookupTool(manifest, candidates) {
   return null;
 }
 
+/**
+ * Both sides of a label-to-label tool comparison, from two parsed manifests.
+ *
+ * A tool neither manifest lists is not a diff of two absences: it is a tool the
+ * comparison cannot speak for at all, so it comes back separately and `plan` and
+ * the migration lane each say so in their own words.
+ * \returns {{diffs:object[], notOnManifest:string[]}}
+ */
+export function diffManifestTools(from, to, tools) {
+  const a = resolveManifestVersions(from, tools);
+  const b = resolveManifestVersions(to, tools);
+  const notOnManifest = tools.filter((t) => a.missing.includes(t) && b.missing.includes(t));
+  const comparable = tools.filter((t) => !notOnManifest.includes(t));
+  return { diffs: diffToolMaps(comparable, a.map, b.map), notOnManifest };
+}
+
 /**
  * Resolve canonical tool names against a parsed manifest.
  * @returns {{map:Record<string,string[]>, missing:string[]}}
diff --git a/src/migration.mjs b/src/migration.mjs
index f621639..d744b7a 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -13,7 +13,7 @@
 
 import { IMAGE_OS_TO_LABEL, migrationFor, migrationStatus } from './labels.mjs';
 import { labelOwnership } from './detect.mjs';
-import { loadManifest, resolveManifestVersions } from './manifest.mjs';
+import { diffManifestTools, loadManifest } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
 import { errorText } from './http.mjs';
 
@@ -145,13 +145,9 @@ export async function surveyMigration({
   survey.images = { from: a.imageVersion, to: b.imageVersion };
   survey.image = imageDiffs(a, b).filter((d) => d.changed);
 
-  const ra = resolveManifestVersions(a, tools);
-  const rb = resolveManifestVersions(b, tools);
-  survey.notOnManifest = tools.filter((t) => ra.missing.includes(t) && rb.missing.includes(t));
-  survey.toolDiffs = tools
-    .filter((t) => !survey.notOnManifest.includes(t))
-    .map((t) => diffTool(t, ra.map[t] ?? null, rb.map[t] ?? null))
-    .filter((d) => d.changed);
+  const compared = diffManifestTools(a, b, tools);
+  survey.notOnManifest = compared.notOnManifest;
+  survey.toolDiffs = compared.diffs.filter((d) => d.changed);
 
   return survey;
 }
diff --git a/src/report.mjs b/src/report.mjs
index fb27549..25296f0 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -155,6 +155,7 @@ export function stepSummaryMarkdown({
   approximate = false,
   baseline = false,
   written = true,
+  explains = null,
   lockFile,
 }) {
   const lines = [];
@@ -190,6 +191,14 @@ export function stepSummaryMarkdown({
     return `${lines.join('\n')}\n`;
   }
 
+  if (explains) {
+    lines.push(
+      `> 📅 Explained by the scheduled \`${explains.label}\` migration \`${explains.from}\` → ` +
+        `\`${explains.to}\` (${explains.starts} to ${explains.ends}). The tools below moved with the image.`,
+    );
+    lines.push('');
+  }
+
   const rows = changed.map((d) => {
     const a = attribution[d.tool];
     const shipped = a
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 8decf88..f9dc5a7 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import os from 'node:os';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import {
   MIGRATIONS,
   MIGRATION_PHASE,
@@ -678,6 +678,24 @@ test('the explanation needs no flag: the two labels alone identify the move', as
   assert.equal(r.stderr, '');
 });
 
+test('the step summary names the explanation the way stdout does', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'runner-drift-summary-'));
+  const summaryFile = path.join(dir, 'summary.md');
+  await writeFile(summaryFile, '', 'utf8');
+  const prev = process.env.GITHUB_STEP_SUMMARY;
+  process.env.GITHUB_STEP_SUMMARY = summaryFile;
+  try {
+    await guardAcrossTheMove({ summary: true }, DURING);
+    const md = await readFile(summaryFile, 'utf8');
+    assert.match(md, /Explained by the scheduled `ubuntu-latest` migration/);
+    assert.match(md, /\(2026-10-19 to 2026-11-19\)/);
+  } finally {
+    if (prev === undefined) delete process.env.GITHUB_STEP_SUMMARY;
+    else process.env.GITHUB_STEP_SUMMARY = prev;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('--json names the explanation without --fail-on-migration too', async () => {
   const r = await guardAcrossTheMove({ json: true }, DURING);
   const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));

From 643405ffe4189ab495865d452ac35875e51239a2 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 13:12:30 +0800
Subject: [PATCH 12/44] stripComment searches for the comment instead of
 matching to the anchor

`[^\r\n]*$` cannot reach the anchor on a line that still holds a bare CR,
so every ` #` on it rescans to the CR: 200k characters of ` #` took 10.1s
through the matrix scan, which runs stripComment on every line of a file
with an expression runs-on:. Same fix readScalar already uses, and the
input joins the linearity test that should have caught it.
---
 src/detect.mjs       | 13 +++++++++++--
 test/detect.test.mjs |  4 ++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/detect.mjs b/src/detect.mjs
index 52a7203..a08113f 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -118,9 +118,18 @@ export function commandsInScript(script) {
   return [...found];
 }
 
-/** A YAML inline comment: a `#` at the start of the line or after a space. */
+/**
+ * Drop a YAML inline comment: a `#` at the start of the line or after a space.
+ *
+ * Found by searching rather than matching to the end of the line, for the same
+ * reason `readScalar` does: `[^\r\n]*$` before an anchor is the quadratic shape,
+ * and a line holding a stray CR makes every `#` rescan to it (LESSONS
+ * 2026-09-09).
+ */
 function stripComment(text) {
-  return text.replace(/(^|[ \t])#[^\r\n]*$/, '$1');
+  if (text.startsWith('#')) return '';
+  const at = text.search(/[ \t]#/);
+  return at === -1 ? text : text.slice(0, at + 1);
 }
 
 /** 1-indexed column of the label inside a raw scalar that may be padded or quoted. */
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index ba40141..f366341 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -358,6 +358,10 @@ test('the line scanners stay linear on pathological input', () => {
     ['commandsInScript after sudo', () => commandsInScript(`sudo${pad}x`)],
     ['a matrix scan over an indent with no colon', () => extractLabelSites(`runs-on: \${{ matrix.os }}\n${pad}x`)],
     ['a matrix scan over a dashed indent', () => extractLabelSites(`runs-on: \${{ matrix.os }}\n${pad}-${pad}x`)],
+    [
+      'comment starts before a stray CR',
+      () => extractLabelSites(`runs-on: \${{ matrix.os }}\n${' #'.repeat(100_000)}${CR}`),
+    ],
   ];
 
   for (const [label, fn] of cases) {

From b8dc15e70fa986a69742edb5acbddcadcccb5b24 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 13:29:43 +0800
Subject: [PATCH 13/44] Three small consistency gaps around the migration lane

--json on a drift run now carries the same `written` boolean the baseline
payload has, so a reader can tell a report from a recorded run without
inspecting the lock file.

An empty --tools list (`--tools ,`) counted as an explicit list in the
migration lane and skipped the fallback the drift lane does; both check
the length now.

README's phase table was missing the row for a runner already on the new
image before the window opens, which the code reports as a notice.
---
 CHANGELOG.md            |  5 +++--
 README.md               |  1 +
 src/cli.mjs             |  5 +++--
 test/guard.test.mjs     | 22 ++++++++++++++++++++++
 test/migration.test.mjs |  9 +++++++++
 5 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b91161c..1190dd4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -116,8 +116,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   there was nothing to update yet. The README said the flag leaves the lock file
   untouched, so a lint job that asked for a report got a file to decide about.
   It now writes nothing, says so, and still reports the baseline it observed;
-  `--json` gained a `written` boolean beside `baseline`, and the step summary no
-  longer says the tools were "locked in" a file that does not exist.
+  `--json` gained a `written` boolean, on the drift payload as well as the
+  baseline one, so a reader can tell a report from a recorded run, and the step
+  summary no longer says the tools were "locked in" a file that does not exist.
 
 - A workflow whose `runs-on:` is a matrix expression had every label-shaped word
   in the file read as a runner it asks for, including the ones in comments, in
diff --git a/README.md b/README.md
index 24cf908..0fd4339 100644
--- a/README.md
+++ b/README.md
@@ -264,6 +264,7 @@ window, and on the `ImageOS` the runner exported:
 | Phase | `ImageOS` | Reported as |
 | --- | --- | --- |
 | Before the window | — | `::notice`, the window and the countdown |
+| Before the window | the new image | `::notice`, this runner moved ahead of the announced window |
 | In the window | the old image | `::warning`, this runner has not moved yet and the diff is still ahead of you |
 | In the window | the new image | `::notice`, the migration has reached this runner |
 | In the window | absent, or from another job | `::warning`, which of the two this job got cannot be told |
diff --git a/src/cli.mjs b/src/cli.mjs
index d8362d7..27c60e4 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -312,7 +312,8 @@ async function checkMigration(opts, io, now, imageOS, env, scan, lock, deps) {
     byLabel.get(site.label).push(site);
   }
   const locked = lock?.tools ? Object.keys(lock.tools) : null;
-  const tools = parseToolList(opts.tools) ?? (locked?.length ? locked : scanned.tools);
+  const asked = parseToolList(opts.tools);
+  const tools = asked?.length ? asked : (locked?.length ? locked : scanned.tools);
   const load = deps.loadManifest ?? loadManifest;
   const here = runningJob(env);
   const surveys = await Promise.all(
@@ -838,7 +839,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   }
 
   if (opts.json) {
-    const payload = { label, from: lock.imageVersion, to: imageVersion, approximate, diffs, attribution: attributionMap };
+    const payload = { label, from: lock.imageVersion, to: imageVersion, approximate, written: updateLock, diffs, attribution: attributionMap };
     payload.explains = explained?.label ?? null;
     if (retirement) payload.retirement = retirement;
     if (migration) payload.migration = { ...migration, explains: explained?.label ?? null };
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index a6290cd..7625f1c 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -311,6 +311,28 @@ test('the drift summary does not claim a lock update that --no-update-lock stopp
   }
 });
 
+test('--json says whether the lock was written', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-22.04',
+        imageOS: 'ubuntu22',
+        imageVersion: '20260623.199.1',
+        tools: { 'Node.js': { versions: ['18.0.0'], source: 'probe' } },
+      },
+      lockFile,
+    );
+    const off = await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false, json: true });
+    assert.equal(JSON.parse(off.stdout.slice(off.stdout.indexOf('{'))).written, false);
+    const on = await guard({ tools: 'node', 'lock-file': lockFile, json: true });
+    assert.equal(JSON.parse(on.stdout.slice(on.stdout.indexOf('{'))).written, true);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('a lock this version cannot read does not swallow the self-hosted skip', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index f9dc5a7..46258ca 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -721,6 +721,15 @@ test('a quoted job id is the same job GITHUB_JOB names', async () => {
   assert.deepEqual(s.notes, []);
 });
 
+test('an empty --tools list falls back like no list at all', async () => {
+  const r = await guard({ tools: ',', 'fail-on-migration': '30', json: true }, {}, BEFORE);
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  assert.ok(
+    j.migration.surveys[0].toolDiffs.length > 0,
+    'the workflows are still scanned for tools',
+  );
+});
+
 test('a matrix leg pinned to the new image is not the migration arriving', async () => {
   // matrix: [ubuntu-latest, ubuntu-26.04]. This runner is on 26.04, which the
   // job asks for by name, so the jump from the lock is not GitHub's doing.

From a5f020908ed757ff75870ee8ae187a077afd3a70 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 13:31:50 +0800
Subject: [PATCH 14/44] The mid-window sentence has to read right in plan too

`plan --from ubuntu-latest` during the rollout reaches the same sentence
guard does, and it said "which of the two this job ran on is not known
here" on a command that runs on no job at all. It now says what is true
in both places: the label means either image until the window closes,
and which one a job gets depends on the runner it lands on.
---
 src/report.mjs          | 2 +-
 test/migration.test.mjs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/report.mjs b/src/report.mjs
index 25296f0..1bfbf14 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -379,7 +379,7 @@ const MIGRATION_SENTENCE = {
   [MIGRATION_STATE.MIGRATED]: (s) =>
     `The scheduled ${s.label} migration has reached this runner: ${s.from} -> ${s.to}, rollout ${s.starts} to ${s.ends}.`,
   [MIGRATION_STATE.AMBIGUOUS]: (s) =>
-    `${s.label} is mid-rollout from ${s.from} to ${s.to}, finishing ${dateWithCountdown(s.ends, s.daysToEnd)}. Which of the two this job ran on is not known here.`,
+    `${s.label} is mid-rollout from ${s.from} to ${s.to}, finishing ${dateWithCountdown(s.ends, s.daysToEnd)}. Until then the label means either image, and which one a job gets depends on the runner it lands on.`,
   [MIGRATION_STATE.SETTLED]: (s) =>
     `${s.label} finished migrating from ${s.from} to ${s.to} on ${dateWithCountdown(s.ends, s.daysToEnd)}; it now means ${s.to}.`,
   [MIGRATION_STATE.STALE]: (s) =>
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 46258ca..4559c8b 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -306,7 +306,7 @@ test('each state gets its own sentence, and the anomaly says so', async () => {
   );
   assert.match(sentence(DURING, 'ubuntu24'), /this runner served ubuntu-24\.04/);
   assert.match(sentence(DURING, 'ubuntu26'), /has reached this runner/);
-  assert.match(sentence(DURING, null), /not known here/);
+  assert.match(sentence(DURING, null), /the label means either image/);
   assert.match(sentence(AFTER, null), /finished migrating/);
   assert.match(sentence(AFTER, 'ubuntu24'), /anomaly, not drift/);
   assert.match(sentence(AFTER, 'ubuntu22'), /neither ubuntu-24\.04 nor ubuntu-26\.04/);

From fc40382b05d6608b0a55cb4294ea2373308f176b Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 13:48:52 +0800
Subject: [PATCH 15/44] Make the lock-schema guard test deterministic and
 offline

It passed --as-of in runGuard's opts, which only main() reads, so the
test ran against the real clock and fetched the two manifests for real.
It takes deps.now and a fixture loader, like every other timed guard
test. Also puts the scan docstring back over scanner().
---
 src/cli.mjs         | 12 ++++++------
 test/guard.test.mjs | 23 +++++++++++++----------
 2 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/src/cli.mjs b/src/cli.mjs
index 27c60e4..5296411 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -232,18 +232,18 @@ function summarise(io, items, keyOf, lineOf) {
   }
 }
 
-/**
- * One workflow scan per `guard` run. Both lint lanes, the tool fallback, the
- * label fallback and the drift explanation want the same directory, and reading
- * it five times to get the same answer is five times the IO for nothing.
- */
 /** Run `fn` at most once, however many lanes ask for its answer. */
 function once(fn) {
   let pending = null;
   return () => (pending ??= fn());
 }
 
-/** One workflow scan per command, shared by every lane that wants it. */
+/**
+ * One workflow scan per command. Both lint lanes, the tool fallback, the label
+ * fallback, the drift explanation and the runner lane want the same directory,
+ * and reading it five times to get the same answer is five times the IO for
+ * nothing.
+ */
 function scanner(opts) {
   return once(() => detect(opts.workflows ?? path.join('.github', 'workflows')));
 }
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 7625f1c..4badbb2 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -5,7 +5,7 @@ import os from 'node:os';
 import { mkdtemp, rm, readFile, writeFile } from 'node:fs/promises';
 import { runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
 import { readLock, writeLock, SCHEMA_VERSION } from '../src/lock.mjs';
-import { captureIO, FIXTURES } from './helpers.mjs';
+import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
 
 async function tmp() {
   return mkdtemp(path.join(os.tmpdir(), 'runner-drift-test-'));
@@ -18,9 +18,9 @@ async function tmp() {
 const IMAGE = '20260720.234.2';
 const ENV = { ImageVersion: IMAGE, ImageOS: 'ubuntu22' };
 
-async function guard(opts, env = ENV) {
+async function guard(opts, env = ENV, deps = {}) {
   const cap = captureIO();
-  const code = await runGuard({ summary: true, 'update-lock': true, ...opts }, cap.io, env);
+  const code = await runGuard({ summary: true, 'update-lock': true, ...opts }, cap.io, env, deps);
   return { code, stdout: cap.stdout, stderr: cap.stderr };
 }
 
@@ -338,13 +338,16 @@ test('a lock this version cannot read does not swallow the self-hosted skip', as
   const lockFile = path.join(dir, 'runner-lock.json');
   try {
     await writeFile(lockFile, JSON.stringify({ schemaVersion: 99, label: 'ubuntu-24.04' }), 'utf8');
-    const r = await guard({
-      tools: 'node',
-      'lock-file': lockFile,
-      'fail-on-migration': '0',
-      'as-of': '2026-09-20',
-      workflows: path.join(FIXTURES, 'workflows-migration'),
-    }, {});
+    const r = await guard(
+      {
+        tools: 'node',
+        'lock-file': lockFile,
+        'fail-on-migration': '0',
+        workflows: path.join(FIXTURES, 'workflows-migration'),
+      },
+      {},
+      { now: new Date('2026-09-20T00:00:00Z'), loadManifest: fixtureLoader({ 'ubuntu-24.04': 'ubuntu-24.04@2026-09' }) },
+    );
     assert.equal(r.code, EXIT_OK, 'no ImageVersion is a skip, not a lock error');
     assert.match(r.stdout, /not a GitHub-hosted runner/);
   } finally {

From c04bde62e28f4d8dfb3a603ab5be372d61f408c8 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 14:06:54 +0800
Subject: [PATCH 16/44] One walk per file, one manifest read per label, and
 --json on every path

guard --json printed nothing at all on the unknown-runner-label branch,
the same hole this branch already fixed next door for the self-hosted
skip. Both branches now build the document from one helper, so a run that
never reaches the drift diff still emits whatever the lanes found.

analyseWorkflow was calling scanRunsOn three times and jobKeys and the
matrix scan twice per file to produce two halves of the same walk. It
walks once and splits, with the matrix and job passes lazy for the
callers that do not want them. detect() output over every fixture
directory and the repo's own workflows is byte-identical before and
after.

Mid-window the migration lane and the drift diff both want the old
image's manifest, which is a 300KB read done twice. One loader per
guard run, keyed on label and ref.

README: the lane reads the workflow files, so it needs the checkout.
---
 README.md           |  5 +++-
 src/cli.mjs         | 44 ++++++++++++++++++++++++-------
 src/detect.mjs      | 64 ++++++++++++++++++++++++++++++++-------------
 test/guard.test.mjs | 22 ++++++++++++++++
 4 files changed, 107 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 0fd4339..98e1952 100644
--- a/README.md
+++ b/README.md
@@ -258,7 +258,10 @@ labels with an announced move and fails while the window is still ahead of you:
 ```
 
 It is opt-in, like `fail-on-retirement`: without the input, `guard` does not fetch
-the two manifests at all. What it reports depends on where today sits in the
+the two manifests at all. It reads the workflow files to know which floating
+labels you actually ask for, so it needs the checkout above; without one it says
+there is no workflow directory and reports nothing, rather than guessing from the
+image alone. What it reports depends on where today sits in the
 window, and on the `ImageOS` the runner exported:
 
 | Phase | `ImageOS` | Reported as |
diff --git a/src/cli.mjs b/src/cli.mjs
index 5296411..c07993d 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -248,6 +248,31 @@ function scanner(opts) {
   return once(() => detect(opts.workflows ?? path.join('.github', 'workflows')));
 }
 
+/**
+ * One manifest read per label per run. Mid-window the migration lane and the
+ * drift diff both want the old image's manifest, which is a 300KB read.
+ */
+function loaderFor(load) {
+  const seen = new Map();
+  return (label, opts) => {
+    const key = `${label}\${opts?.ref ?? 'main'}`;
+    if (!seen.has(key)) seen.set(key, load(label, opts));
+    return seen.get(key);
+  };
+}
+
+/**
+ * The `--json` document for a run that never reached the drift diff: whatever
+ * the lanes that do not need a lock file found, and nothing invented.
+ */
+function laneDocument({ runners = null, retirement = null, migration = null }) {
+  const payload = {};
+  if (runners) payload.runners = runners;
+  if (retirement) payload.retirement = retirement;
+  if (migration) payload.migration = migration;
+  return payload;
+}
+
 /**
  * The workflow scan the two lint lanes start from, or null when there is no
  * workflow directory — which is a notice on both streams, not an error.
@@ -564,6 +589,7 @@ async function checkOwnRunner(opts, io, env, deps, window, scan) {
 export async function runGuard(opts, io = process, env = process.env, deps = {}) {
   const lockFile = opts['lock-file'] ?? DEFAULT_LOCK_FILE;
   const scan = scanner(opts);
+  const load = loaderFor(deps.loadManifest ?? loadManifest);
   // The migration lane diffs the tools the lock watches, which is not always
   // what the workflow files mention. It reads the lock leniently: a lock this
   // version cannot parse is an error for the drift lane below, which is the
@@ -602,7 +628,10 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   let migration = null;
   if (opts['fail-on-migration'] !== undefined) {
     const known = await getLock().catch(() => null);
-    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, known, deps);
+    migration = await checkMigration(opts, io, deps.now ?? new Date(), imageOS, env, scan, known, {
+      ...deps,
+      loadManifest: load,
+    });
     if (!migration) return EXIT_USAGE;
     if (!opts.json && migration.surveys.length) {
       out(io.stdout, migrationReport(migration.surveys));
@@ -635,13 +664,8 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     // version with a date on it. Without a token this is a no-op and the skip
     // above is the whole output, exactly as in 1.1.0.
     const own = await checkOwnRunner(opts, io, env, deps, window, scan);
-    if (opts.json && (own || migration || retirement)) {
-      const payload = {};
-      if (own) payload.runners = own;
-      if (retirement) payload.retirement = retirement;
-      if (migration) payload.migration = migration;
-      out(io.stdout, JSON.stringify(payload, null, 2));
-    }
+    const doc = laneDocument({ runners: own, retirement, migration });
+    if (opts.json && Object.keys(doc).length) out(io.stdout, JSON.stringify(doc, null, 2));
     if (retiring) reportRetirement(io, retiring);
     if (migrating) reportMigration(io, migrating);
     if (own?.failing) reportDeprecation(io, own);
@@ -659,6 +683,8 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
     const msg = `Unknown runner label (ImageOS="${imageOS ?? '(unset)'}") — skipping. Known: ${knownLabels().join(', ')}`;
     out(io.stdout, `::warning title=runner-drift::${msg}`);
     out(io.stdout, msg);
+    const doc = laneDocument({ retirement, migration });
+    if (opts.json && Object.keys(doc).length) out(io.stdout, JSON.stringify(doc, null, 2));
     if (retiring) reportRetirement(io, retiring);
     if (migrating) reportMigration(io, migrating);
     return retiring || migrating ? EXIT_DRIFT : EXIT_OK;
@@ -706,7 +732,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         manifest = await manifestAtSha(label, attribution0.commit.sha);
       }
       if (!manifest) {
-        const m = await loadManifest(label);
+        const m = await load(label);
         manifest = m.skipped ? null : m;
       }
     } catch (err) {
diff --git a/src/detect.mjs b/src/detect.mjs
index a08113f..06700f5 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -254,13 +254,39 @@ function matrixLabels(lines) {
   return found;
 }
 
+/**
+ * One pass over a document for everything the label scanners want: the
+ * positioned `runs-on:` values, the sets they came in, the matrix fallback and
+ * the job id per line. The last two are lazy because only some callers want
+ * them, and `analyseWorkflow` hands one walk to all four rather than repeating
+ * it per extractor.
+ */
+function walkLabels(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  const scan = scanRunsOn(lines);
+  let matrix = null;
+  let jobs = null;
+  return {
+    ...scan,
+    lines,
+    get matrix() {
+      return (matrix ??= scan.expression ? matrixLabels(lines) : []);
+    },
+    get jobs() {
+      return (jobs ??= jobKeys(lines));
+    },
+  };
+}
+
 /** Pull `runs-on:` labels (inline scalar, inline flow list, block list, matrix refs). */
 export function extractLabels(text) {
-  const lines = String(text ?? '').split(/\r?\n/);
-  const { found, expression } = scanRunsOn(lines);
+  return labelsIn(walkLabels(text));
+}
+
+function labelsIn({ lines, found, expression, matrix }) {
   const labels = new Set(found.map((f) => f.label));
   if (expression) {
-    for (const { label } of matrixLabels(lines)) labels.add(label);
+    for (const { label } of matrix) labels.add(label);
     for (const line of lines) {
       if (/(^|\s)self-hosted(\s|$|,|\]|')/.test(line) && /runs-on|matrix|os:|- /.test(line)) {
         labels.add(SELF_HOSTED);
@@ -312,15 +338,11 @@ function jobKeys(lines) {
  * line. Its job is right, but which leg of the matrix any one runner is serving
  * is not written anywhere in the file.
  */
-function labelSitesWhere(text, file, keep) {
-  const lines = String(text ?? '').split(/\r?\n/);
-  const { found, expression } = scanRunsOn(lines);
-  const jobs = jobKeys(lines);
+function labelSitesWhere(walk, file, keep) {
+  const { found, expression, matrix, jobs } = walk;
   const seen = new Set();
   const sites = [];
-  const all = expression
-    ? [...found, ...matrixLabels(lines).map((m) => ({ ...m, viaMatrix: true }))]
-    : found;
+  const all = expression ? [...found, ...matrix.map((m) => ({ ...m, viaMatrix: true }))] : found;
   for (const { label, line, col, viaMatrix } of all) {
     if (!keep(label)) continue;
     const key = `${label}@${line}:${col}`;
@@ -332,14 +354,16 @@ function labelSitesWhere(text, file, keep) {
   return sites;
 }
 
+const isPinned = (label) => label !== SELF_HOSTED && !isFloating(label);
+
 /** Pinned image labels: what the retirement lane dates. */
 export function extractLabelSites(text, file = null) {
-  return labelSitesWhere(text, file, (l) => l !== SELF_HOSTED && !isFloating(l));
+  return labelSitesWhere(walkLabels(text), file, isPinned);
 }
 
 /** Floating labels: what the migration lane dates, and nothing else can. */
 export function extractFloatingSites(text, file = null) {
-  return labelSitesWhere(text, file, isFloating);
+  return labelSitesWhere(walkLabels(text), file, isFloating);
 }
 
 /**
@@ -414,8 +438,10 @@ export function siteInJob(site, here) {
  * and no labels, since which runner serves them is not decidable from the file.
  */
 export function extractRunsOnTargets(text, file = null) {
-  const lines = String(text ?? '').split(/\r?\n/);
-  const { targets } = scanRunsOn(lines);
+  return targetsIn(walkLabels(text), file);
+}
+
+function targetsIn({ targets }, file) {
   return targets.map((t) => ({
     labels: [...new Set(t.labels)],
     expression: t.expression,
@@ -514,10 +540,12 @@ export function extractSetupActions(text) {
 
 /** Analyse one workflow document. */
 export function analyseWorkflow(text, file = null) {
-  const labels = extractLabels(text);
-  const labelSites = extractLabelSites(text, file);
-  const floatingSites = extractFloatingSites(text, file);
-  const runsOnTargets = extractRunsOnTargets(text, file);
+  const walk = walkLabels(text);
+  const labels = labelsIn(walk);
+  const sites = labelSitesWhere(walk, file, () => true);
+  const labelSites = sites.filter((s) => isPinned(s.label));
+  const floatingSites = sites.filter((s) => isFloating(s.label));
+  const runsOnTargets = targetsIn(walk, file);
   const uses = extractUses(text, file);
   const commands = new Set();
   for (const script of extractRunScripts(text)) {
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 4badbb2..5ba7621 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -46,6 +46,28 @@ test('an unknown ImageOS is a warning and a skip, not a crash', async () => {
   }
 });
 
+test('--json off an unknown image still prints what the lanes found', async () => {
+  const dir = await tmp();
+  try {
+    const r = await guard(
+      {
+        tools: 'node',
+        json: true,
+        'lock-file': path.join(dir, 'runner-lock.json'),
+        'fail-on-migration': '0',
+        workflows: path.join(FIXTURES, 'workflows-quoted-job'),
+      },
+      { ImageVersion: IMAGE, ImageOS: 'plan9' },
+      { now: new Date('2026-09-20T00:00:00Z'), loadManifest: fixtureLoader({ 'ubuntu-24.04': 'ubuntu-24.04@2026-09' }) },
+    );
+    assert.match(r.stdout, /Unknown runner label/);
+    const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+    assert.equal(j.migration.surveys[0].label, 'ubuntu-latest');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('first run with no lock creates one and exits 0 with "baseline recorded"', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');

From a9192e00f33039e534f5a785d0cc239ee1b20933 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 14:28:47 +0800
Subject: [PATCH 17/44] The job id decides, and a pinned sibling outranks a
 coincidence

Three attribution bugs in the migration lane, all about whose runner this is.

A job inside a reusable workflow reports the caller in GITHUB_WORKFLOW_REF
while GITHUB_JOB is the id in the callee. The matcher trusted the file name
whenever the caller was a file it had scanned, which is exactly the reusable
case, so the real runs-on: line was rejected and a valid ImageOS thrown away.
The job id decides now; the file only breaks a tie.

With no GITHUB_JOB at all, the image was attributed whenever it was one of the
window's two labels, and only a matrix leg could outrank that. A sibling job
with a plain runs-on: ubuntu-26.04 explains the same image just as well, so a
repo with a compat job reported ubuntu-latest as migrated two weeks early.
Inside one job the only rival is still a matrix leg; unscoped, every site is.

The note on that path asserted "this check did not run on ubuntu-latest", which
is the one thing nothing in that case knows. It now names the missing GITHUB_JOB.

Also: the manifest memo key had an escaped $, so the ref never reached the key.
No caller passes one yet, which is why the suite stayed green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 15 +++++++++++
 README.md               | 13 +++++++---
 src/cli.mjs             |  2 +-
 src/detect.mjs          | 27 ++++++++++---------
 src/migration.mjs       |  9 ++++++-
 test/migration.test.mjs | 57 +++++++++++++++++++++++++++++++++++++++--
 6 files changed, 102 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1190dd4..5c2f330 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -143,6 +143,21 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   itself, next to the floating label, was GitHub moving you; now it is your own
   pin, and the line is withheld.
 
+- A job running inside a reusable workflow had its image discarded. Actions
+  reports the *calling* workflow in `GITHUB_WORKFLOW_REF` while `GITHUB_JOB` is
+  the id inside the callee, and the scan matched the file first, so the real
+  `runs-on:` line was rejected as somebody else's job. The job id now decides,
+  and the file is only used to break a tie when the caller has a job of the same
+  name.
+
+- With no `GITHUB_JOB` to scope to, a runner's image was read as evidence about
+  the floating label whenever it was one of the two the window names, even
+  though a sibling job pinned to that exact image explains it just as well. A
+  repo with a `compat:` job on `ubuntu-26.04` could report `ubuntu-latest` as
+  migrated a fortnight early. Any `runs-on:` naming the observed image now takes
+  the evidence away, and the note that used to assert "this check did not run on
+  ubuntu-latest", which nothing in that case knew, says what is actually missing.
+
 - `guard --fail-on-migration` diffed the tools named in the workflow files even
   when the lock file listed a different set. The drift lane has always preferred
   the lock, since that is the list it is about to compare. Both lanes now read
diff --git a/README.md b/README.md
index 98e1952..8f9f44a 100644
--- a/README.md
+++ b/README.md
@@ -284,9 +284,16 @@ job, so it counts as evidence about `ubuntu-latest` only when that job asked for
 same repo gets the window from the calendar and a line saying its own image was
 not treated as evidence, rather than a claim that `ubuntu-latest` has gone
 somewhere unrecognised. `GITHUB_JOB` and `GITHUB_WORKFLOW_REF` are what tie the
-runner to a `runs-on:` line, and Actions sets both for you. Where the label is
-reached through a matrix, or the command runs with no `GITHUB_JOB` at all, the
-image is still attributed if it is one of the two the window names.
+runner to a `runs-on:` line, and Actions sets both for you. Inside a reusable
+workflow the ref names the calling file while the job id lives in the callee, so
+the job id decides unless the caller has a job of that name too.
+
+Where the label is reached through a matrix, or the command runs with no
+`GITHUB_JOB` at all, the image is still attributed if it is one of the two the
+window names. Both of those give way to a nearer explanation: a matrix leg that
+names the observed image, and, with no job id to scope to, any job in the repo
+pinned to it. Then you get the calendar and a line saying why the image was not
+treated as evidence.
 
 One part of this needs no input at all. When `guard` finds real tool drift, the
 jump from the lock's image to the runner's image is exactly an announced move,
diff --git a/src/cli.mjs b/src/cli.mjs
index c07993d..9e2cedb 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -255,7 +255,7 @@ function scanner(opts) {
 function loaderFor(load) {
   const seen = new Map();
   return (label, opts) => {
-    const key = `${label}\${opts?.ref ?? 'main'}`;
+    const key = `${label}@${opts?.ref ?? 'main'}`;
     if (!seen.has(key)) seen.set(key, load(label, opts));
     return seen.get(key);
   };
diff --git a/src/detect.mjs b/src/detect.mjs
index 06700f5..a4d5030 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -383,42 +383,41 @@ export function runningJob(env = process.env) {
  * A predicate for "this site is one the running job was scheduled from", over
  * the sites a scan actually produced.
  *
- * The file name is dropped from the comparison when none of the scanned files
- * is the one this run came from: a job inside a reusable workflow reports the
- * caller's file in `GITHUB_WORKFLOW_REF`, and a scan pointed at a copy of the
- * directory need not match it either. The job id still has to agree.
+ * The file name is dropped from the comparison when no scanned site carries
+ * this job id in the file the run reports: a job inside a reusable workflow
+ * reports the calling file in `GITHUB_WORKFLOW_REF` while its id lives in the
+ * callee, and a scan pointed at a copy of the directory need not match either.
+ * The job id still has to agree.
  */
 export function jobMatcher(here, sites = []) {
   if (!here) return () => false;
-  const known =
-    here.file
-    && sites.some(
-      (s) => s.file && path.basename(s.file).toLowerCase() === here.file.toLowerCase(),
-    );
+  const known = Boolean(here.file) && sites.some((site) => siteInJob(site, here));
   const at = known ? here : { ...here, file: null };
   return (site) => siteInJob(site, at);
 }
 
 /**
- * Who asked for `label` here, and whether a matrix leg asks for `observed` too.
+ * Who asked for `label` here, and whether anything else asks for `observed` too.
  *
  * `scoped` is whether a running job was identified at all; without one every
  * site in the repository is in scope and the caller has to decide how much that
  * is worth. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
- * the label through a matrix, and `rival` is a matrix leg naming `observed`,
+ * the label through a matrix, and `rival` is another site naming `observed`,
  * which the runner is as likely to be serving as the floating one.
+ *
+ * Inside one job the only rival is a matrix leg, since a job has one `runs-on:`.
+ * With no job to scope to, every `runs-on: <observed>` in the repo is one.
  */
 export function labelOwnership({ label, observed = null, sites = [], others = [], here = null }) {
   const belongs = jobMatcher(here, [...sites, ...others]);
   const inScope = here ? belongs : () => true;
   const mine = sites.filter((site) => site.label === label && inScope(site));
+  const rivals = others.filter((site) => site.label === observed && inScope(site));
   return {
     scoped: Boolean(here),
     direct: mine.some((site) => !site.viaMatrix),
     asked: mine.length > 0,
-    rival:
-      observed !== null
-      && others.some((site) => site.viaMatrix && site.label === observed && inScope(site)),
+    rival: observed !== null && (here ? rivals.some((site) => site.viaMatrix) : rivals.length > 0),
   };
 }
 
diff --git a/src/migration.mjs b/src/migration.mjs
index d744b7a..984b8c3 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -50,6 +50,12 @@ export function imageDiffs(from, to) {
  * the window names, which is evidence the runner did come from this label: a
  * matrix leg (the file cannot say which leg this runner is), and a run with no
  * `GITHUB_JOB` to match against (`guard` invoked outside a workflow job).
+ *
+ * Neither weak case can report an image from outside the window, so the
+ * `unexpected` anomaly needs a job id. That is deliberate: with no job to scope
+ * to, an unscanned workflow or a `runs-on:` built from an expression would put
+ * an image on this runner that no site in the scan accounts for, and calling
+ * that a broken migration would be an error raised at the wrong repository.
  */
 export function attributeImageOS({ label, imageOS, sites = [], others = [], here = null }) {
   if (!imageOS) return { imageOS: null, note: null };
@@ -66,7 +72,8 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
       imageOS: null,
       note: rival
         ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
-        : `This check did not run on ${label}, so its ImageOS is not evidence about the migration.`,
+        : `No GITHUB_JOB says which job this check ran in, and ${observed ?? imageOS} is neither `
+          + `image in the ${label} window, so this runner is not evidence about it.`,
     };
   }
 
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 4559c8b..eb0878c 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -457,13 +457,23 @@ test('below the threshold it reports and exits 0', async () => {
 });
 
 test('a stale runner after the window fails whatever the threshold', async () => {
-  const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, { ImageOS: 'ubuntu24' }, AFTER);
+  const env = { ImageOS: 'ubuntu24', GITHUB_JOB: 'build' };
+  const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, env, AFTER);
   assert.equal(r.code, EXIT_DRIFT);
   assert.match(r.stdout, /^::error file=/m);
   assert.match(r.stderr, /anomaly, not drift/);
   assert.ok(!r.stderr.includes('--fail-on-migration 0 is set'), 'an anomaly is not a countdown');
 });
 
+test('without GITHUB_JOB the pinned sibling job holds the anomaly back', async () => {
+  // The same fixture has a job on ubuntu-24.04. With nothing saying which job
+  // this is, that job explains the image as well as a stalled migration does.
+  const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, { ImageOS: 'ubuntu24' }, AFTER);
+  assert.equal(r.code, EXIT_OK);
+  assert.doesNotMatch(r.stdout, /^::error file=/m);
+  assert.match(r.stdout, /ask for ubuntu-24\.04 by name/);
+});
+
 test('a workflow with no floating label produces nothing and exits 0', async () => {
   const r = await guard({
     tools: 'node',
@@ -623,7 +633,50 @@ test('with no GITHUB_JOB the window images are still attributed', () => {
   assert.equal(a.note, null);
   const b = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu22', sites, here: null });
   assert.equal(b.imageOS, null);
-  assert.match(b.note, /This check did not run on ubuntu-latest/);
+  assert.match(b.note, /No GITHUB_JOB says which job this check ran in/);
+});
+
+test('with no GITHUB_JOB a job pinned to the new image is the likelier runner', () => {
+  // Nothing says which job this check is in, so a plain `runs-on: ubuntu-26.04`
+  // elsewhere explains the image as well as the migration having landed does.
+  const y = [
+    'jobs:',
+    '  build:',
+    '    runs-on: ubuntu-latest',
+    '  compat:',
+    '    runs-on: ubuntu-26.04',
+  ].join('\n');
+  const sites = extractFloatingSites(y, 'ci.yml');
+  const others = extractLabelSites(y, 'ci.yml');
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu26', sites, others, here: null });
+  assert.equal(a.imageOS, null);
+  assert.match(a.note, /ask for ubuntu-26\.04 by name/);
+  assert.notEqual(
+    migrationStatus('ubuntu-latest', { now: DURING, imageOS: a.imageOS }).state,
+    MIGRATION_STATE.MIGRATED,
+  );
+  const scoped = attributeImageOS({
+    label: 'ubuntu-latest', imageOS: 'ubuntu26', sites, others, here: { job: 'build', file: 'ci.yml' },
+  });
+  assert.equal(scoped.imageOS, 'ubuntu26', 'the job id settles it');
+});
+
+test('a job id the calling workflow does not use is looked up in the callee', () => {
+  // A reusable workflow reports the caller in GITHUB_WORKFLOW_REF, and the
+  // caller is a scanned file: the job id still has to decide which site is ours.
+  const callee = [{ label: 'ubuntu-latest', file: 'build.yml', line: 6, col: 14, job: 'build' }];
+  const caller = [{ label: 'ubuntu-22.04', file: 'release.yml', line: 4, col: 14, job: 'publish' }];
+  const here = { job: 'build', file: 'release.yml' };
+  assert.equal(jobMatcher(here, [...callee, ...caller])(callee[0]), true);
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu24', sites: callee, others: caller, here });
+  assert.equal(a.imageOS, 'ubuntu24');
+  assert.equal(a.note, null);
+  const shadowed = [{ ...caller[0], job: 'build' }];
+  assert.equal(
+    jobMatcher(here, [...callee, ...shadowed])(callee[0]),
+    false,
+    'the caller has a job of that id, so the file decides again',
+  );
 });
 
 /**

From c67f5f9728b232164675ce5964410376fa854960 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 14:43:02 +0800
Subject: [PATCH 18/44] Read the file as YAML at the edges: folded prose, the
 end of jobs, a hostile ImageOS

A prose key with no block marker still folds over the lines below it, so a step
written as `- name:` with the title on the next line put every label-shaped word
in that title back into the scan. Under `if:` the same shape could turn
--fail-on-retirement into an ::error on a line nobody can act on. Prose keys now
own their indented block whether or not someone typed the `|`.

The jobs map ended for `current` but not for the walk, so the first key at the
job indent under a later top-level block was adopted as a job id. `x-templates:`
with a `build:` under it invents the same id a real job has, and a job id is
what ties GITHUB_JOB to a runs-on: line.

ImageOS is an environment variable and the ImageOS -> label table was indexed
with it directly, so `__proto__` came back truthy and the lane reported an image
nobody announced. One labelForImageOS() with an own-key check now serves all
three call sites. manifest.mjs already did this; the lane did not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 17 ++++++++++++++++-
 src/cli.mjs             |  3 ++-
 src/detect.mjs          | 12 +++++++++---
 src/index.mjs           |  1 +
 src/labels.mjs          | 14 +++++++++++++-
 src/migration.mjs       |  4 ++--
 test/detect.test.mjs    | 41 +++++++++++++++++++++++++++++++++++++++++
 test/migration.test.mjs | 11 +++++++++++
 8 files changed, 95 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c2f330..dda8559 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -125,7 +125,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   `run:` scripts and in step names. That put retirement and migration
   annotations on lines nobody can act on, and, once the migration lane existed,
   could attribute a runner's image to a label the repo never uses. Comments,
-  block scalars and the prose keys (`run`, `name`, `if`) are now skipped. The
+  block scalars and the prose keys (`run`, `name`, `if`) are now skipped, and a
+  prose key takes the indented lines below it with it, since a plain scalar
+  wraps onto them as readily as a `|` block does. The
   rest of the file is still read, because a label reaches `runs-on:` through a
   `workflow_call` input default or an `env:` value as well as through `matrix:`.
 
@@ -143,6 +145,19 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   itself, next to the floating label, was GitHub moving you; now it is your own
   pin, and the line is withheld.
 
+- A key at the job indent under a *later* top-level block was recorded as a job
+  id. `x-templates:` after the jobs map, with a `build:` under it, produced
+  `runs-on:` sites labelled as job `build`, which is a real job id in the same
+  file. A fabricated id can match `GITHUB_JOB`, so it could have pointed the
+  migration lane at the wrong `runs-on:` line. The map now ends where YAML ends
+  it, at the next top-level key.
+
+- `ImageOS=__proto__` resolved to a label. The env value indexed the
+  `ImageOS` -> label table directly, so any property of `Object.prototype` came
+  back truthy, and the migration lane called it an image nobody announced:
+  `::error`, exit 1, and a summary cell containing a function body. The lookup
+  is an own-key check now, in one place both lanes use.
+
 - A job running inside a reusable workflow had its image discarded. Actions
   reports the *calling* workflow in `GITHUB_WORKFLOW_REF` while `GITHUB_JOB` is
   the id inside the callee, and the scan matched the file first, so the real
diff --git a/src/cli.mjs b/src/cli.mjs
index 9e2cedb..2d81201 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -15,6 +15,7 @@ import {
   deadlineFor,
   isFloating,
   knownLabels,
+  labelForImageOS,
   migratingLabels,
   migrationFails,
   migrationBetween,
@@ -673,7 +674,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   }
 
   const lock = await getLock();
-  let label = (imageOS && IMAGE_OS_TO_LABEL[imageOS.toLowerCase()]) || lock?.label || null;
+  let label = labelForImageOS(imageOS) || lock?.label || null;
 
   if (!label) {
     const detected = await scan();
diff --git a/src/detect.mjs b/src/detect.mjs
index a4d5030..f736725 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -237,13 +237,14 @@ function matrixLabels(lines) {
     const key = text.match(/^([ \t]*)(-[ \t]+)?([^:\s][^:\r\n]*)?:([^\r\n]*)$/);
     if (key) {
       // `run: |` and friends: the body below is shell or prose, not YAML values.
+      // A prose key owns its indented lines the same way whether or not it was
+      // written with a block marker, since a plain scalar folds over them too.
       // A dashed key owns the column the dash sits in, so the step's own
       // siblings (`env:`, `with:`) are not read as part of the script.
-      if (/^[|>]/.test(key[4].trim())) {
+      if (/^[|>]/.test(key[4].trim()) || PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase())) {
         scalar = key[1].length + (key[2]?.length ?? 0);
         continue;
       }
-      if (PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase())) continue;
     }
     for (const tok of text.matchAll(/[A-Za-z][A-Za-z0-9.-]*/g)) {
       if (LABEL_SHAPE.test(tok[0])) {
@@ -308,8 +309,9 @@ function jobKeys(lines) {
   let jobsIndent = null;
   let jobIndent = null;
   let current = null;
+  let ended = false;
   for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/^([ \t]*)([^-\s#][^:\r\n]*):/);
+    const m = ended ? null : lines[i].match(/^([ \t]*)([^-\s#][^:\r\n]*):/);
     if (m) {
       const indent = m[1].length;
       const key = m[2].trim().replace(/^(['"])(.*)\1$/, '$2');
@@ -317,7 +319,11 @@ function jobKeys(lines) {
         // Top level only: `on.workflow_dispatch.inputs.jobs` is not the map.
         if (key === 'jobs' && indent === 0) jobsIndent = indent;
       } else if (indent <= jobsIndent) {
+        // The next top-level key closes the map. A key further down at the job
+        // indent belongs to that key, and inventing a job id for it can put a
+        // runner's image on a job that GITHUB_JOB names somewhere else.
         current = null;
+        ended = true;
       } else if (jobIndent === null || indent === jobIndent) {
         jobIndent = indent;
         current = key;
diff --git a/src/index.mjs b/src/index.mjs
index d0ff612..2db5653 100644
--- a/src/index.mjs
+++ b/src/index.mjs
@@ -119,6 +119,7 @@ export {
   knownLabels,
   deadlineFor,
   isFloating,
+  labelForImageOS,
   migratingLabels,
   migrationBetween,
   migrationFails,
diff --git a/src/labels.mjs b/src/labels.mjs
index 5030006..2ca193f 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -51,6 +51,18 @@ export const IMAGE_OS_TO_LABEL = {
   macos26: 'macos-26',
 };
 
+/**
+ * The concrete label an `ImageOS` names, or null for anything else.
+ *
+ * `ImageOS` comes from the environment, so the table is read as data: a plain
+ * property lookup answers `__proto__` and `constructor` with something truthy,
+ * and the migration lane would report that as an image nobody announced.
+ */
+export function labelForImageOS(imageOS) {
+  const key = imageOS ? String(imageOS).toLowerCase() : '';
+  return Object.hasOwn(IMAGE_OS_TO_LABEL, key) ? IMAGE_OS_TO_LABEL[key] : null;
+}
+
 const MACOS_14_BROWNOUTS = [
   '2026-10-05',
   '2026-10-12',
@@ -303,7 +315,7 @@ export function migrationStatus(label, { now = new Date(), imageOS = null } = {}
   // An ImageOS this build does not recognise reads as no observation at all:
   // guard already reports an unknown ImageOS on its own, and guessing here
   // would turn a new image name into a fake anomaly.
-  const observed = imageOS ? (IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null) : null;
+  const observed = labelForImageOS(imageOS);
   const seen = observed === null ? 'none' : observed === m.to ? 'to' : observed === m.from ? 'from' : 'other';
   const state = seen === 'other' ? MIGRATION_STATE.UNEXPECTED : STATE_BY_PHASE[phase][seen];
 
diff --git a/src/migration.mjs b/src/migration.mjs
index 984b8c3..fcbc919 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -11,7 +11,7 @@
  * and Node.js 22 -> 24" is something you can act on before it happens.
  */
 
-import { IMAGE_OS_TO_LABEL, migrationFor, migrationStatus } from './labels.mjs';
+import { labelForImageOS, migrationFor, migrationStatus } from './labels.mjs';
 import { labelOwnership } from './detect.mjs';
 import { diffManifestTools, loadManifest } from './manifest.mjs';
 import { diffTool } from './diff.mjs';
@@ -60,7 +60,7 @@ export function imageDiffs(from, to) {
 export function attributeImageOS({ label, imageOS, sites = [], others = [], here = null }) {
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
-  const observed = IMAGE_OS_TO_LABEL[String(imageOS).toLowerCase()] ?? null;
+  const observed = labelForImageOS(imageOS);
   const { direct, asked, rival } = labelOwnership({ label, observed, sites, others, here });
 
   if (here && direct) return { imageOS, note: null };
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index f366341..232026e 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -300,6 +300,47 @@ test('a trailing comment is not part of the label', () => {
   assert.deepEqual(extractRunsOnTargets(y)[1].labels, [SELF_HOSTED, 'linux']);
 });
 
+test('a label written in a step name or a condition is not a runner', () => {
+  // The prose keys hold a plain scalar as often as a block one, and a plain
+  // scalar folds over the lines below it just the same.
+  const y = [
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-24.04]',
+    '    runs-on: ${{ matrix.os }}',
+    '    steps:',
+    '      - name:',
+    '          build on ubuntu-latest',
+    '        run: make',
+    '      - if: >',
+    '          github.repository != "acme/ubuntu-22.04"',
+    '        run: echo skipped',
+  ].join('\n');
+  assert.deepEqual(extractFloatingSites(y), []);
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => s.label),
+    ['ubuntu-24.04'],
+  );
+  assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
+});
+
+test('a key under the block that follows the jobs map is not a job id', () => {
+  // `x-` template blocks are a real shape, and the id can collide with a job's.
+  const y = [
+    'jobs:',
+    '  build:',
+    '    runs-on: ubuntu-latest',
+    '',
+    'x-templates:',
+    '  build:',
+    '    runs-on: ubuntu-22.04',
+  ].join('\n');
+  assert.equal(extractFloatingSites(y)[0].job, 'build');
+  assert.equal(extractLabelSites(y)[0].job, null);
+});
+
 test('labelSites: floating labels are never a site', () => {
   assert.deepEqual(extractLabelSites('    runs-on: ubuntu-latest\n'), []);
 });
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index eb0878c..fe8761b 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -7,6 +7,7 @@ import {
   MIGRATIONS,
   MIGRATION_PHASE,
   MIGRATION_STATE,
+  labelForImageOS,
   migrationBetween,
   migrationFails,
   migrationFor,
@@ -626,6 +627,16 @@ test('a matrix leg is trusted for the two images in the window and no others', (
   assert.match(off.note, /through a matrix/);
 });
 
+test('an ImageOS that names a property of Object is not an image', () => {
+  // ImageOS is an environment variable, so the table has to be read as data.
+  assert.equal(labelForImageOS('__proto__'), null);
+  assert.equal(labelForImageOS('constructor'), null);
+  const s = migrationStatus('ubuntu-latest', { now: DURING, imageOS: '__proto__' });
+  assert.equal(s.observed, null);
+  assert.equal(s.state, MIGRATION_STATE.AMBIGUOUS);
+  assert.equal(s.anomaly, false);
+});
+
 test('with no GITHUB_JOB the window images are still attributed', () => {
   const sites = [{ label: 'ubuntu-latest', file: 'ci.yml', line: 6, col: 14, job: 'build' }];
   const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu24', sites, here: null });

From a42f466f83b14f302fda6dbd3ad1a3548a52810e Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 14:57:10 +0800
Subject: [PATCH 19/44] A slipped rollout is not your build's fault

--fail-on-migration failed the build on any anomaly whatever the threshold, and
"still serving the old image after the window" is an anomaly. GitHub ran both
previous latest moves late. On the day it slips again, every repo with the input
set goes red over a runner that works, with no value of the threshold that turns
it off. It stays an ::error annotation and a reported anomaly, because the
announced date has passed, but it no longer decides the exit code. An image that
is neither end of the window still fails at any threshold: that one is the label
meaning something nobody announced.

--as-of forced UTC for a bare date only, so a time with no zone went through
Date.parse in local time while every countdown counts UTC days. On this box
(UTC+8) --as-of 2026-10-19 reports the window open and 2026-10-19T00:00:00
reports it a day away. Same calendar day, different annotation.

And the same own-key check labelForImageOS just got, for the three tables keyed
by a label that came out of a workflow file or argv.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 17 +++++++++++++----
 README.md               | 17 +++++++++++------
 src/cli.mjs             | 14 +++++++++++++-
 src/labels.mjs          | 40 ++++++++++++++++++++++++++--------------
 test/cli.test.mjs       | 23 +++++++++++++++++++++++
 test/migration.test.mjs | 36 ++++++++++++++++++++++++++++++++----
 6 files changed, 118 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dda8559..8ee44b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,8 +55,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   is annotated according to where today sits in the window and which `ImageOS`
   the runner exported: pending, this runner has not moved yet, the migration has
   reached this runner, done, or, past the window on the old image, an anomaly.
-  The anomaly fails whatever the threshold, the same rule a label already past
-  its retirement date follows.
+  A rollout running past its announced end is annotated `::error` and reported,
+  and does not fail the build: GitHub ran both previous `latest` moves late, and
+  a failure no threshold turns off is one people remove the check over. An image
+  that is neither end of the window does fail whatever the threshold, because
+  that is the label meaning something nobody announced.
 
   `ImageOS` describes one runner, and that runner is serving one job, so it is
   read as evidence about a floating label only when the job it is running asked
@@ -87,8 +90,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **`--as-of <date>`** on every command that counts down to something (`guard`, `plan`, `runners`, `actions`). It moves the clock every countdown is
   measured from and nothing else, so `plan --from ubuntu-latest --as-of
   2026-10-19` answers what the report will say on the first day of the rollout
-  without pretending the run happened then. It is also what makes the migration
-  tests deterministic.
+  without pretending the run happened then. A date, or a time with no zone, is
+  read as UTC, which is the calendar the countdowns themselves use. It is also
+  what makes the migration tests deterministic.
 
 - `init` refusing a floating label now points at the migration when there is one,
   instead of only saying "pass a concrete label".
@@ -152,6 +156,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   migration lane at the wrong `runs-on:` line. The map now ends where YAML ends
   it, at the next top-level key.
 
+- Every table keyed by a runner label answered `__proto__` and `constructor`
+  with something truthy, so `plan --from constructor` took the resolved-migration
+  branch and then reported that `--from` was missing. `deadlineFor`,
+  `pathForLabel` and `migrationFor` all read their tables as data now.
+
 - `ImageOS=__proto__` resolved to a label. The env value indexed the
   `ImageOS` -> label table directly, so any property of `Object.prototype` came
   back truthy, and the migration lane called it an image nobody announced:
diff --git a/README.md b/README.md
index 8f9f44a..d212290 100644
--- a/README.md
+++ b/README.md
@@ -273,10 +273,16 @@ window, and on the `ImageOS` the runner exported:
 | In the window | absent, or from another job | `::warning`, which of the two this job got cannot be told |
 | After the window | the new image | `::notice`, the move is done |
 | After the window | the old image | `::error`, an anomaly rather than drift |
+| Any phase | an image from neither end | `::error`, and the build fails |
 
-The last row is the one worth having. A runner still serving Ubuntu 24.04 in
-December, when the label is supposed to mean 26.04 everywhere, is not a version
-bump you should record in the lock file.
+The last two rows are the ones worth having. A runner still serving Ubuntu 24.04
+in December, when the label is supposed to mean 26.04 everywhere, is not a
+version bump you should record in the lock file. It does not fail the build
+either: GitHub ran both previous `latest` moves late, nothing in your repo is
+broken while it does, and a red build with no threshold that turns it off is one
+people fix by deleting the check. An image that is neither end of the window is
+different. That is the label meaning something nobody announced, so it fails
+whatever the threshold says.
 
 `ImageOS` describes the runner the step is on, and that runner is serving one
 job, so it counts as evidence about `ubuntu-latest` only when that job asked for
@@ -310,9 +316,8 @@ Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04
 
 The step summary carries the same line, above the drift table.
 
-Exit codes and the `--fail-on` thresholds are untouched by any of this. An
-anomaly fails whatever the threshold, the same rule `--fail-on-retirement` uses
-for a label already past its date. `--json` gains a `migration` block, and the
+Exit codes and the `--fail-on` thresholds are untouched by any of this.
+`--json` gains a `migration` block, and the
 step summary gains a table (Label, Phase, Move, Window, This runner, Source).
 The explanation above has its own `explains` key next to `diffs`, which is there
 with or without the flag, and is `null` when nothing announced explains the jump.
diff --git a/src/cli.mjs b/src/cli.mjs
index 2d81201..b6d2bbc 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -195,6 +195,18 @@ function out(stream, line) {
   stream.write(`${line}\n`);
 }
 
+/**
+ * A date or a zone-less time reads as UTC, which is the calendar every
+ * countdown in the output is measured in. Left to `Date.parse`, a naive time is
+ * local, so `--as-of 2026-10-19T00:00:00` lands on the 18th west of Greenwich
+ * and reports the window as a day away rather than open.
+ */
+function utcWhenNaive(raw) {
+  if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) return `${raw}T00:00:00Z`;
+  if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(raw)) return `${raw.replace(' ', 'T')}Z`;
+  return raw;
+}
+
 /**
  * `--as-of`: the date every countdown is measured from. Nothing here is
  * inferred from it, so it answers "what will this say on the 19th?" without
@@ -204,7 +216,7 @@ function out(stream, line) {
 function asOf(opts, io) {
   if (opts['as-of'] === undefined) return {};
   const raw = String(opts['as-of']);
-  const at = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(raw) ? `${raw}T00:00:00Z` : raw);
+  const at = Date.parse(utcWhenNaive(raw));
   if (!Number.isFinite(at)) {
     out(io.stderr, `--as-of needs a date such as 2026-10-19 (got "${raw}")`);
     return null;
diff --git a/src/labels.mjs b/src/labels.mjs
index 2ca193f..a0ad0d3 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -52,15 +52,12 @@ export const IMAGE_OS_TO_LABEL = {
 };
 
 /**
- * The concrete label an `ImageOS` names, or null for anything else.
- *
- * `ImageOS` comes from the environment, so the table is read as data: a plain
- * property lookup answers `__proto__` and `constructor` with something truthy,
- * and the migration lane would report that as an image nobody announced.
+ * The concrete label an `ImageOS` names, or null for anything else. An
+ * unrecognised value reads as no observation at all, which is what the
+ * migration lane wants: a new image name is not an anomaly.
  */
 export function labelForImageOS(imageOS) {
-  const key = imageOS ? String(imageOS).toLowerCase() : '';
-  return Object.hasOwn(IMAGE_OS_TO_LABEL, key) ? IMAGE_OS_TO_LABEL[key] : null;
+  return imageOS ? lookup(IMAGE_OS_TO_LABEL, String(imageOS).toLowerCase()) : null;
 }
 
 const MACOS_14_BROWNOUTS = [
@@ -141,12 +138,21 @@ export function knownLabels() {
   return Object.keys(LABEL_PATHS);
 }
 
+/**
+ * Read a table with a key that came from a workflow file, an env var or argv.
+ * Own keys only: `__proto__` and `constructor` are labels nobody has, and every
+ * one of these tables answering them with something truthy is a wrong answer.
+ */
+function lookup(table, key) {
+  return typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : null;
+}
+
 export function pathForLabel(label) {
-  return LABEL_PATHS[label] ?? null;
+  return lookup(LABEL_PATHS, label);
 }
 
 export function deadlineFor(label) {
-  return DEADLINES[label] ?? null;
+  return lookup(DEADLINES, label);
 }
 
 export function isFloating(label) {
@@ -264,7 +270,7 @@ const STATE_BY_PHASE = {
 
 /** The announced migration of a floating label, or null when there is none. */
 export function migrationFor(label) {
-  return MIGRATIONS[label] ?? null;
+  return lookup(MIGRATIONS, label);
 }
 
 /**
@@ -346,13 +352,19 @@ export function migrationStatus(label, { now = new Date(), imageOS = null } = {}
 /**
  * Should `--fail-on-migration <days>` fail on this status?
  *
- * An anomaly always fires, whatever the threshold, the same rule the retirement
- * lane uses for an already-retired label: a label serving an image the window
- * says it should have left is not a countdown, it is a fault.
+ * A label serving an image that is neither end of its window fires whatever the
+ * threshold: that is not a countdown, it is a fault, and no date makes it fine.
+ *
+ * A rollout that has not finished by the announced end does not. Both previous
+ * `latest` moves ran late, the runners keep working when they do, and a build
+ * that goes red over GitHub's schedule with no threshold that turns it off is a
+ * build people fix by deleting the check. It is still reported as an anomaly,
+ * with an `::error` annotation, because the announced date has passed.
  */
 export function migrationFails(status, days) {
   if (!status) return false;
-  if (status.anomaly) return true;
+  if (status.state === MIGRATION_STATE.UNEXPECTED) return true;
+  if (status.state === MIGRATION_STATE.STALE) return false;
   if (status.done) return false;
   if (status.phase === MIGRATION_PHASE.IN_WINDOW) return true;
   return Number.isFinite(days) && status.daysToStart !== null && status.daysToStart <= days;
diff --git a/test/cli.test.mjs b/test/cli.test.mjs
index a1245ac..28a3ee1 100644
--- a/test/cli.test.mjs
+++ b/test/cli.test.mjs
@@ -151,6 +151,29 @@ test('--as-of rejects anything that is not a date', async () => {
   }
 });
 
+test('--as-of reads a time with no zone in UTC, like the countdowns it moves', async () => {
+  // Left to Date.parse a naive time is local, so the same calendar day lands on
+  // either side of midnight UTC depending on where the runner is.
+  const saved = process.env.ImageVersion;
+  delete process.env.ImageVersion;
+  const at = (asof) =>
+    run([
+      'guard', '--tools', 'node',
+      '--workflows', 'test/fixtures/workflows-retirement',
+      '--fail-on-retirement', '100',
+      '--as-of', asof,
+      '--no-summary',
+    ]);
+  try {
+    for (const form of ['2026-08-12', '2026-08-12T00:00:00', '2026-08-12 00:00', '2026-08-12T00:00:00Z']) {
+      const r = await at(form);
+      assert.match(r.stdout, /macos-14 retires in 82 days/, form);
+    }
+  } finally {
+    if (saved !== undefined) process.env.ImageVersion = saved;
+  }
+});
+
 test('--as-of moves every countdown, without a network call', async () => {
   const saved = process.env.ImageVersion;
   delete process.env.ImageVersion;
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index fe8761b..2b103f5 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -7,11 +7,13 @@ import {
   MIGRATIONS,
   MIGRATION_PHASE,
   MIGRATION_STATE,
+  deadlineFor,
   labelForImageOS,
   migrationBetween,
   migrationFails,
   migrationFor,
   migrationStatus,
+  pathForLabel,
 } from '../src/labels.mjs';
 import { attributeImageOS, imageDiffs, surveyMigration } from '../src/migration.mjs';
 import { migrationAnnotations, migrationLines, migrationSummaryMarkdown } from '../src/report.mjs';
@@ -196,9 +198,14 @@ test('the gate fires inside the threshold, in the window, and on an anomaly', ()
 
   assert.equal(migrationFails(migrationStatus('ubuntu-latest', { now: DURING }), 0), true);
   assert.equal(
-    migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu24' }), 0),
+    migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu22' }), 0),
     true,
-    'an anomaly fires whatever the threshold',
+    'an image from outside the window fires whatever the threshold',
+  );
+  assert.equal(
+    migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu24' }), 10000),
+    false,
+    'a rollout running late is reported, not failed',
   );
   assert.equal(
     migrationFails(migrationStatus('ubuntu-latest', { now: AFTER, imageOS: 'ubuntu26' }), 10000),
@@ -457,12 +464,24 @@ test('below the threshold it reports and exits 0', async () => {
   assert.equal(r.stderr, '');
 });
 
-test('a stale runner after the window fails whatever the threshold', async () => {
+test('a rollout still running late is an error annotation, not a red build', async () => {
+  // GitHub has slipped both previous `latest` moves. Nothing here is broken by
+  // that, and a threshold that cannot turn the failure off is one people fix by
+  // deleting the check.
   const env = { ImageOS: 'ubuntu24', GITHUB_JOB: 'build' };
   const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, env, AFTER);
+  assert.equal(r.code, EXIT_OK);
+  assert.match(r.stdout, /^::error file=/m);
+  assert.match(r.stdout, /still serving ubuntu-24\.04/);
+  assert.equal(r.stderr, '');
+});
+
+test('an image from outside the window fails whatever the threshold', async () => {
+  const env = { ImageOS: 'ubuntu22', GITHUB_JOB: 'build' };
+  const r = await guard({ tools: 'node', 'fail-on-migration': '0' }, env, AFTER);
   assert.equal(r.code, EXIT_DRIFT);
   assert.match(r.stdout, /^::error file=/m);
-  assert.match(r.stderr, /anomaly, not drift/);
+  assert.match(r.stderr, /which is neither ubuntu-24\.04 nor ubuntu-26\.04/);
   assert.ok(!r.stderr.includes('--fail-on-migration 0 is set'), 'an anomaly is not a countdown');
 });
 
@@ -627,6 +646,15 @@ test('a matrix leg is trusted for the two images in the window and no others', (
   assert.match(off.note, /through a matrix/);
 });
 
+test('a label that names a property of Object is in none of the tables', () => {
+  // Labels come out of workflow files, so every table keyed by one is data.
+  for (const key of ['__proto__', 'constructor', 'toString']) {
+    assert.equal(migrationFor(key), null, key);
+    assert.equal(deadlineFor(key), null, key);
+    assert.equal(pathForLabel(key), null, key);
+  }
+});
+
 test('an ImageOS that names a property of Object is not an image', () => {
   // ImageOS is an environment variable, so the table has to be read as data.
   assert.equal(labelForImageOS('__proto__'), null);

From 6abcb0d198f97afe9d879c5d51959cefb32ae381 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 15:15:14 +0800
Subject: [PATCH 20/44] Do not remember a manifest read that failed

The memo kept the promise, rejection and all, so the second lane to ask for the
same manifest was handed the first lane's 502 with no request of its own. The
migration lane degrades to a note when a manifest is unreachable; the drift lane
cannot, and a null manifest there reads as every locked tool having been removed.
Only a read that worked is kept now.

migrationStatus still indexed MIGRATIONS directly, so migrationStatus and
surveyMigration answered '__proto__' with a window made of undefined. Both are
public exports, even though the CLI filters with migrationFor first.

And the phase table in the README now says which rows fail the job, since the
threshold decides only the countdown before the window opens.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  7 +++++++
 README.md               | 26 ++++++++++++++++----------
 src/cli.mjs             | 15 +++++++++++++--
 src/labels.mjs          |  2 +-
 test/guard.test.mjs     | 17 ++++++++++++++++-
 test/migration.test.mjs | 13 ++++++++++++-
 6 files changed, 65 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ee44b2..cfae35c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -156,6 +156,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   migration lane at the wrong `runs-on:` line. The map now ends where YAML ends
   it, at the next top-level key.
 
+- A manifest read that failed was remembered as failed. The run reads each
+  manifest once, and the memo held the rejected promise, so the lane that asked
+  second got the first one's network error without a request of its own. A 502
+  in the migration lane could have left the drift lane with no manifest at all,
+  which reads as every locked tool having been removed. Only a read that worked
+  is kept.
+
 - Every table keyed by a runner label answered `__proto__` and `constructor`
   with something truthy, so `plan --from constructor` took the resolved-migration
   branch and then reported that `--from` was missing. `deadlineFor`,
diff --git a/README.md b/README.md
index d212290..dc0520b 100644
--- a/README.md
+++ b/README.md
@@ -264,16 +264,22 @@ there is no workflow directory and reports nothing, rather than guessing from th
 image alone. What it reports depends on where today sits in the
 window, and on the `ImageOS` the runner exported:
 
-| Phase | `ImageOS` | Reported as |
-| --- | --- | --- |
-| Before the window | — | `::notice`, the window and the countdown |
-| Before the window | the new image | `::notice`, this runner moved ahead of the announced window |
-| In the window | the old image | `::warning`, this runner has not moved yet and the diff is still ahead of you |
-| In the window | the new image | `::notice`, the migration has reached this runner |
-| In the window | absent, or from another job | `::warning`, which of the two this job got cannot be told |
-| After the window | the new image | `::notice`, the move is done |
-| After the window | the old image | `::error`, an anomaly rather than drift |
-| Any phase | an image from neither end | `::error`, and the build fails |
+| Phase | `ImageOS` | Reported as | Fails the job? |
+| --- | --- | --- | --- |
+| Before the window | — | `::notice`, the window and the countdown | within the threshold |
+| Before the window | the new image | `::notice`, this runner moved ahead of the announced window | never |
+| In the window | the old image | `::warning`, this runner has not moved yet and the diff is still ahead of you | yes |
+| In the window | the new image | `::notice`, the migration has reached this runner | never |
+| In the window | absent, or from another job | `::warning`, which of the two this job got cannot be told | yes |
+| After the window | the new image | `::notice`, the move is done | never |
+| After the window | the old image | `::error`, an anomaly rather than drift | no |
+| Any phase | an image from neither end | `::error`, the label means something nobody announced | always |
+
+The threshold counts the days to the *start* of the window, so it decides the
+first row only. Once the window is open the change is no longer a countdown, and
+the rows that fail are the ones where it is still ahead of this runner. A runner
+that has already moved is green, which is what makes pinning the label, or
+letting it land, the way out rather than deleting the input.
 
 The last two rows are the ones worth having. A runner still serving Ubuntu 24.04
 in December, when the label is supposed to mean 26.04 everywhere, is not a
diff --git a/src/cli.mjs b/src/cli.mjs
index b6d2bbc..a76abf6 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -265,11 +265,22 @@ function scanner(opts) {
  * One manifest read per label per run. Mid-window the migration lane and the
  * drift diff both want the old image's manifest, which is a 300KB read.
  */
-function loaderFor(load) {
+export function loaderFor(load) {
   const seen = new Map();
   return (label, opts) => {
     const key = `${label}@${opts?.ref ?? 'main'}`;
-    if (!seen.has(key)) seen.set(key, load(label, opts));
+    if (!seen.has(key)) {
+      // A failed read is not kept. The lane that asked second would replay the
+      // rejection with no request of its own, and a manifest that was merely
+      // unreachable for a moment reads as every locked tool having been removed.
+      const read = Promise.resolve()
+        .then(() => load(label, opts))
+        .catch((err) => {
+          seen.delete(key);
+          throw err;
+        });
+      seen.set(key, read);
+    }
     return seen.get(key);
   };
 }
diff --git a/src/labels.mjs b/src/labels.mjs
index a0ad0d3..7e8f4a6 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -303,7 +303,7 @@ export function migratingLabels() {
  * @returns {object|null} null when the label has no announced migration
  */
 export function migrationStatus(label, { now = new Date(), imageOS = null } = {}) {
-  const m = MIGRATIONS[label];
+  const m = migrationFor(label);
   if (!m) return null;
 
   // The changelog states calendar dates, so both ends are inside the window.
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 5ba7621..c009ee3 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import path from 'node:path';
 import os from 'node:os';
 import { mkdtemp, rm, readFile, writeFile } from 'node:fs/promises';
-import { runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
+import { loaderFor, runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
 import { readLock, writeLock, SCHEMA_VERSION } from '../src/lock.mjs';
 import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
 
@@ -305,6 +305,21 @@ test('runGuard writes the lock by default, with no update-lock key at all', asyn
   }
 });
 
+test('a manifest read that failed is retried, not replayed from the memo', async () => {
+  // Both lanes want the same manifest mid-window, and the second one asking
+  // must not be handed the first one's network error with no request of its own.
+  let calls = 0;
+  const load = loaderFor(async (label) => {
+    calls += 1;
+    if (calls === 1) throw new Error('502 from raw.githubusercontent.com');
+    return { label, call: calls };
+  });
+  await assert.rejects(load('ubuntu-24.04'), /502/);
+  assert.deepEqual(await load('ubuntu-24.04'), { label: 'ubuntu-24.04', call: 2 });
+  assert.deepEqual(await load('ubuntu-24.04'), { label: 'ubuntu-24.04', call: 2 }, 'one read once it works');
+  assert.equal(calls, 2);
+});
+
 test('the drift summary does not claim a lock update that --no-update-lock stopped', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 2b103f5..1fba974 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -464,6 +464,15 @@ test('below the threshold it reports and exits 0', async () => {
   assert.equal(r.stderr, '');
 });
 
+test('in the window the exit turns on whether this runner has moved', async () => {
+  const at = (ImageOS) =>
+    guard({ tools: 'node', 'fail-on-migration': '0' }, { ImageOS, GITHUB_JOB: 'build' }, DURING);
+  assert.equal((await at('ubuntu24')).code, EXIT_DRIFT, 'the change is still ahead of this runner');
+  assert.equal((await at('ubuntu26')).code, EXIT_OK, 'this runner already has it');
+  const blind = await guard({ tools: 'node', 'fail-on-migration': '0' }, {}, DURING);
+  assert.equal(blind.code, EXIT_DRIFT, 'which of the two this job got cannot be told');
+});
+
 test('a rollout still running late is an error annotation, not a red build', async () => {
   // GitHub has slipped both previous `latest` moves. Nothing here is broken by
   // that, and a threshold that cannot turn the failure off is one people fix by
@@ -646,12 +655,14 @@ test('a matrix leg is trusted for the two images in the window and no others', (
   assert.match(off.note, /through a matrix/);
 });
 
-test('a label that names a property of Object is in none of the tables', () => {
+test('a label that names a property of Object is in none of the tables', async () => {
   // Labels come out of workflow files, so every table keyed by one is data.
   for (const key of ['__proto__', 'constructor', 'toString']) {
     assert.equal(migrationFor(key), null, key);
     assert.equal(deadlineFor(key), null, key);
     assert.equal(pathForLabel(key), null, key);
+    assert.equal(migrationStatus(key, { now: DURING }), null, key);
+    assert.equal(await surveyMigration({ label: key, now: DURING }), null, key);
   }
 });
 

From ae587febc0d97842af9ff11307bd234cdd593ebf Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 15:30:31 +0800
Subject: [PATCH 21/44] Scope the drift explanation the way attribution is
 scoped

Without GITHUB_JOB, `direct` says only that some job in the repo asks for
ubuntu-latest, and the runner in front of you might be the sibling job someone
pinned to ubuntu-26.04 by hand. attributeImageOS gates the same signal with
`here && direct`; explainDrift did not, so it credited GitHub for an upgrade the
repo did itself. New fixture with both jobs covers all three cases: no job id,
the floating job, the pinned one.

Also the countdown suffix: "(1 days)" on the last day before every date this
tool prints.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  8 ++++++++
 src/cli.mjs                                   |  7 +++++--
 src/report.mjs                                |  6 +++---
 test/fixtures/workflows-pinned-sibling/ci.yml | 13 +++++++++++++
 test/migration.test.mjs                       | 14 ++++++++++++++
 test/report.test.mjs                          | 19 ++++++++++++++++++-
 6 files changed, 61 insertions(+), 6 deletions(-)
 create mode 100644 test/fixtures/workflows-pinned-sibling/ci.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cfae35c..c48aecf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -156,6 +156,14 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   migration lane at the wrong `runs-on:` line. The map now ends where YAML ends
   it, at the next top-level key.
 
+- The line that credits the migration for tool drift read `direct` without a job
+  id, so a repo with one job on `ubuntu-latest` and another pinned to
+  `ubuntu-26.04` was told GitHub moved it when the pinned job was the one that
+  ran. With no `GITHUB_JOB` either job explains the image, and the lane that
+  attributes `ImageOS` has always said so. Now both do.
+
+- Every countdown said "(1 days)" on the last day before the date it counts to.
+
 - A manifest read that failed was remembered as failed. The run reads each
   manifest once, and the memo held the rejected promise, so the lane that asked
   second got the first one's network error without a request of its own. A 502
diff --git a/src/cli.mjs b/src/cli.mjs
index a76abf6..37b39b7 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -399,6 +399,7 @@ async function explainDrift({ migration, lock, label, scan, env }) {
   const m = migrationBetween(lock.label, label);
   if (!m) return null;
   const scanned = await scan();
+  const here = runningJob(env);
   // `label` is this runner's own: a matrix leg naming it is a pin the repo
   // chose, not the window moving the job, so the explanation is withheld.
   const { direct, asked, rival } = labelOwnership({
@@ -406,9 +407,11 @@ async function explainDrift({ migration, lock, label, scan, env }) {
     observed: label,
     sites: scanned.floatingSites,
     others: scanned.labelSites,
-    here: runningJob(env),
+    here,
   });
-  return direct || (asked && !rival) ? m : null;
+  // `direct` without a job id says only that some job in the repo asks for the
+  // label, which is not this one. attributeImageOS scopes it the same way.
+  return (here && direct) || (asked && !rival) ? m : null;
 }
 
 /** One stderr line per floating label whose migration fails the gate. */
diff --git a/src/report.mjs b/src/report.mjs
index 1bfbf14..f5a8c0d 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -30,10 +30,12 @@ import {
 
 export { daysUntil };
 
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
 /** `(82 days)` / `(60 days ago)` — the countdown suffix both lanes print. */
 export function countdown(days) {
   if (days === null || days === undefined) return '';
-  return days < 0 ? `(${Math.abs(days)} days ago)` : `(${days} days)`;
+  return days < 0 ? `(${plural(Math.abs(days), 'day')} ago)` : `(${plural(days, 'day')})`;
 }
 
 /** `2026-11-02 (82 days)`. A full ISO date-time is trimmed to its date. */
@@ -544,8 +546,6 @@ const RUNNER_BADGE = {
   [RUNNER_STATUS.OK]: '⚪ OK',
 };
 
-const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
-
 /**
  * `x2` / `x2 (1 offline)`. Whether the group is in service changes how urgent it
  * is — an EXPIRED version on a runner still reporting online is the case that
diff --git a/test/fixtures/workflows-pinned-sibling/ci.yml b/test/fixtures/workflows-pinned-sibling/ci.yml
new file mode 100644
index 0000000..1d4bbb4
--- /dev/null
+++ b/test/fixtures/workflows-pinned-sibling/ci.yml
@@ -0,0 +1,13 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: node --version
+
+  compat:
+    runs-on: ubuntu-26.04
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 1fba974..140e201 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -875,6 +875,20 @@ test('a repo that pins its runners is not told GitHub moved it', async () => {
   assert.match(r.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
 });
 
+test('with no job id, a sibling pinned to the new image withholds the explanation', async () => {
+  // build: ubuntu-latest, compat: ubuntu-26.04. This runner is on 26.04 and
+  // nothing says which of the two jobs it is, so the move is not attributable.
+  const where = { workflows: path.join(FIXTURES, 'workflows-pinned-sibling') };
+  const blind = await guardAcrossTheMove(where, DURING);
+  assert.ok(!blind.stdout.includes('Explained by'), 'either job explains this image');
+  assert.match(blind.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+
+  const mine = await guardAcrossTheMove({ ...where, env: inJob('build') }, DURING);
+  assert.match(mine.stdout, /Explained by the scheduled ubuntu-latest migration/);
+  const theirs = await guardAcrossTheMove({ ...where, env: inJob('compat') }, DURING);
+  assert.ok(!theirs.stdout.includes('Explained by'), 'compat asks for 26.04 by name');
+});
+
 test('the explanation follows the job, not the repo, when Actions says which job', async () => {
   const mine = await guardAcrossTheMove({ env: inJob('build') }, DURING);
   assert.match(mine.stdout, /Explained by the scheduled ubuntu-latest migration/);
diff --git a/test/report.test.mjs b/test/report.test.mjs
index 6b50d6f..264a0cd 100644
--- a/test/report.test.mjs
+++ b/test/report.test.mjs
@@ -1,6 +1,14 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { deadlineLines, daysUntil, annotations, stepSummaryMarkdown, planRow } from '../src/report.mjs';
+import {
+  countdown,
+  dateWithCountdown,
+  deadlineLines,
+  daysUntil,
+  annotations,
+  stepSummaryMarkdown,
+  planRow,
+} from '../src/report.mjs';
 import { diffTool } from '../src/diff.mjs';
 
 const NOW = new Date('2026-08-05T00:00:00Z');
@@ -34,6 +42,15 @@ test('a label with no announced deadline returns null', () => {
   assert.equal(deadlineLines('ubuntu-24.04', NOW), null);
 });
 
+test('the countdown says one day, not 1 days', () => {
+  assert.equal(countdown(1), '(1 day)');
+  assert.equal(countdown(-1), '(1 day ago)');
+  assert.equal(countdown(0), '(0 days)');
+  assert.equal(countdown(2), '(2 days)');
+  assert.equal(countdown(null), '');
+  assert.equal(dateWithCountdown('2026-10-19T00:00:00Z', 1), '2026-10-19 (1 day)');
+});
+
 test('daysUntil counts down and then up', () => {
   assert.equal(daysUntil('2026-08-15', NOW), 10);
   assert.equal(daysUntil('2026-07-26', NOW), -10);

From 788b7b410cf4acfecc137575b70cbfa0e0cb944f Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 15:47:03 +0800
Subject: [PATCH 22/44] One place to read a table keyed by a string we did not
 choose

Three copies of the own-key check had grown (labels, manifest headers, and the
one I missed: the tool tables). src/tables.mjs holds it now, and tools.mjs uses
it, which fixes `--tools constructor` crashing the manifest resolver with
"candidates is not iterable" instead of treating it as a tool nobody has.

Also finishes the pluralisation: the annotation title still read "becomes
ubuntu-26.04 in 1 days", and so did the retirement lane's "1 days left".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  8 +++++++-
 src/labels.mjs          | 10 +---------
 src/manifest.mjs        |  3 ++-
 src/report.mjs          |  6 +++---
 src/tables.mjs          | 16 ++++++++++++++++
 src/tools.mjs           |  8 +++++---
 test/detect.test.mjs    | 11 ++++++++++-
 test/migration.test.mjs |  7 +++++++
 8 files changed, 51 insertions(+), 18 deletions(-)
 create mode 100644 src/tables.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c48aecf..8497b05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -162,7 +162,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   ran. With no `GITHUB_JOB` either job explains the image, and the lane that
   attributes `ImageOS` has always said so. Now both do.
 
-- Every countdown said "(1 days)" on the last day before the date it counts to.
+- Every countdown said "(1 days)" on the last day before the date it counts to,
+  including the annotation titles and the retirement lane's "1 days left".
+
+- `--tools constructor`, or a lock file with a tool of that name, crashed in the
+  manifest resolver: the candidate-names table answered with a function, and a
+  function is not a list of names. The three tables keyed by a tool or a command
+  read as data now, like the label ones.
 
 - A manifest read that failed was remembered as failed. The run reads each
   manifest once, and the memo held the rejected promise, so the lane that asked
diff --git a/src/labels.mjs b/src/labels.mjs
index 7e8f4a6..8add80f 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -7,6 +7,7 @@
  */
 
 import { daysUntil as daysUntilDate } from './dates.mjs';
+import { lookup } from './tables.mjs';
 
 export const RUNNER_IMAGES_REPO = 'actions/runner-images';
 export const RAW_HOST = 'https://raw.githubusercontent.com';
@@ -138,15 +139,6 @@ export function knownLabels() {
   return Object.keys(LABEL_PATHS);
 }
 
-/**
- * Read a table with a key that came from a workflow file, an env var or argv.
- * Own keys only: `__proto__` and `constructor` are labels nobody has, and every
- * one of these tables answering them with something truthy is a wrong answer.
- */
-function lookup(table, key) {
-  return typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : null;
-}
-
 export function pathForLabel(label) {
   return lookup(LABEL_PATHS, label);
 }
diff --git a/src/manifest.mjs b/src/manifest.mjs
index 7ed31c3..5729704 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -19,6 +19,7 @@
  */
 
 import { diffToolMaps } from './diff.mjs';
+import { lookup } from './tables.mjs';
 import { fetchText, NotFoundError, DriftError } from './http.mjs';
 import { RAW_BASE, pathForLabel } from './labels.mjs';
 import { manifestCandidates } from './tools.mjs';
@@ -215,7 +216,7 @@ export function parseManifest(markdown, label = null) {
     const headerM = line.match(/^[ \t]*-[ \t]+([^:\s][^:\r\n]*):[ \t]*([^\r\n]+)/);
     if (headerM) {
       const key = headerM[1].trim().toLowerCase();
-      const field = Object.hasOwn(HEADER_FIELDS, key) ? HEADER_FIELDS[key] : null;
+      const field = lookup(HEADER_FIELDS, key);
       if (field) {
         header[field] ??= headerM[2].trim();
         continue;
diff --git a/src/report.mjs b/src/report.mjs
index f5a8c0d..b08bb47 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -74,8 +74,8 @@ export function deadlineLines(label, now = new Date()) {
     left === null
       ? null
       : left > 0
-        ? `${left} days left${untilBrownout !== null && untilBrownout > 0 ? ` (${untilBrownout} until the first brownout)` : ''}`
-        : `retired ${Math.abs(left)} days ago`;
+        ? `${plural(left, 'day')} left${untilBrownout !== null && untilBrownout > 0 ? ` (${untilBrownout} until the first brownout)` : ''}`
+        : `retired ${plural(Math.abs(left), 'day')} ago`;
   if (countdownLine) {
     lines.push(`${countdownLine} — deprecation began ${dl.deprecationStart}; see ${dl.source}`);
   }
@@ -402,7 +402,7 @@ const MIGRATION_KIND = {
 };
 
 const MIGRATION_TITLE = {
-  [MIGRATION_STATE.PENDING]: (s) => `${s.label} becomes ${s.to} in ${s.daysToStart} days`,
+  [MIGRATION_STATE.PENDING]: (s) => `${s.label} becomes ${s.to} in ${plural(s.daysToStart, 'day')}`,
   [MIGRATION_STATE.MOVED_EARLY]: (s) => `${s.label} is already ${s.to}`,
   [MIGRATION_STATE.NOT_YET_MIGRATED]: (s) => `${s.label} migration under way`,
   [MIGRATION_STATE.MIGRATED]: (s) => `${s.label} is now ${s.to}`,
diff --git a/src/tables.mjs b/src/tables.mjs
new file mode 100644
index 0000000..db850ae
--- /dev/null
+++ b/src/tables.mjs
@@ -0,0 +1,16 @@
+/**
+ * Lookups in the tables this tool keys by a string it did not choose: a runner
+ * label out of a workflow file, a tool name off the command line, an `ImageOS`
+ * out of the environment.
+ */
+
+/**
+ * The value at `key`, or null when the table has no such key of its own.
+ *
+ * A plain index answers `__proto__`, `constructor` and `toString` with
+ * something truthy, which has every caller here reporting a label or a tool
+ * that does not exist, or crashing on a function where a list was expected.
+ */
+export function lookup(table, key) {
+  return typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : null;
+}
diff --git a/src/tools.mjs b/src/tools.mjs
index f51d6a3..04da345 100644
--- a/src/tools.mjs
+++ b/src/tools.mjs
@@ -1,3 +1,5 @@
+import { lookup } from './tables.mjs';
+
 /**
  * The alias table: shell command -> canonical tool name, and canonical tool
  * name -> the names that tool goes by in runner-images manifests.
@@ -60,8 +62,8 @@ export const MANIFEST_CANDIDATES = {
 export function canonicalTool(name) {
   if (!name) return null;
   const key = String(name).trim();
-  if (MANIFEST_CANDIDATES[key]) return key;
-  const alias = COMMAND_ALIASES[key.toLowerCase()];
+  if (lookup(MANIFEST_CANDIDATES, key)) return key;
+  const alias = lookup(COMMAND_ALIASES, key.toLowerCase());
   if (alias) return alias;
   // Case-insensitive match against canonical names.
   const hit = Object.keys(MANIFEST_CANDIDATES).find((k) => k.toLowerCase() === key.toLowerCase());
@@ -69,7 +71,7 @@ export function canonicalTool(name) {
 }
 
 export function manifestCandidates(tool) {
-  return MANIFEST_CANDIDATES[tool] ?? [tool];
+  return lookup(MANIFEST_CANDIDATES, tool) ?? [tool];
 }
 
 export function knownTools() {
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 232026e..f60a63c 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -13,7 +13,7 @@ import {
   detect,
   SELF_HOSTED,
 } from '../src/detect.mjs';
-import { canonicalTool } from '../src/tools.mjs';
+import { canonicalTool, manifestCandidates } from '../src/tools.mjs';
 import { FIXTURES } from './helpers.mjs';
 
 test('extracts an inline runs-on label', () => {
@@ -76,6 +76,15 @@ test('maps commands to the canonical manifest tool', () => {
   assert.equal(canonicalTool('dotnet'), '.NET Core SDK');
 });
 
+test('a tool named after a property of Object is just an unknown tool', () => {
+  // `--tools constructor` used to hand a function to the manifest resolver,
+  // which asked it for a list of candidate names and crashed.
+  for (const name of ['constructor', 'toString', '__proto__']) {
+    assert.equal(typeof canonicalTool(name), 'string', name);
+    assert.deepEqual(manifestCandidates(name), [name], name);
+  }
+});
+
 test('actions/setup-* counts as using the tool', () => {
   const r = analyseWorkflow(
     'jobs:\n  a:\n    runs-on: ubuntu-24.04\n    steps:\n      - uses: actions/setup-go@v5\n',
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 140e201..0f158fe 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -666,6 +666,13 @@ test('a label that names a property of Object is in none of the tables', async (
   }
 });
 
+test('the day before the window opens, everything says one day', () => {
+  const s = migrationStatus('ubuntu-latest', { now: new Date('2026-10-18T00:00:00Z') });
+  const [a] = migrationAnnotations([{ ...s, sites: [{ file: 'ci.yml', line: 6, col: 14 }] }]);
+  assert.match(a, /title=runner-drift: ubuntu-latest becomes ubuntu-26\.04 in 1 day:/);
+  assert.match(a, /The rollout starts 2026-10-19 \(1 day\)/);
+});
+
 test('an ImageOS that names a property of Object is not an image', () => {
   // ImageOS is an environment variable, so the table has to be read as data.
   assert.equal(labelForImageOS('__proto__'), null);

From 7d8b89fb2722068228100f312ee7c66b724b7d3a Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 16:01:30 +0800
Subject: [PATCH 23/44] A job id is unique in a file, not in a repo

The ownership rule drops the file check when no site in the scan it was given
sits in the file this run came from. The migration lane gave it the pinned sites
plus one floating label's, so a run from a job named `build` in release.yml,
with another `build` in ci.yml, lost the file check and claimed the other job's
label. On windows-latest that reads as ubuntu-latest serving an image from
outside the window: ::error, exit 1, nothing actually wrong.

`others` is now every other site in the scan, which is what the rule's own
docstring assumed. explainDrift already passed the union.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  7 ++++++
 src/cli.mjs                                   |  9 ++++++-
 src/detect.mjs                                |  4 ++++
 test/fixtures/workflows-two-builds/ci.yml     |  8 +++++++
 .../fixtures/workflows-two-builds/release.yml |  9 +++++++
 test/migration.test.mjs                       | 24 +++++++++++++++++++
 6 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 test/fixtures/workflows-two-builds/ci.yml
 create mode 100644 test/fixtures/workflows-two-builds/release.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8497b05..500fb2a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -188,6 +188,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   `::error`, exit 1, and a summary cell containing a function body. The lookup
   is an own-key check now, in one place both lanes use.
 
+- A job id that two workflow files both use was told apart by the file only when
+  the scan happened to hold a pinned site in the file this run came from. The
+  migration lane handed the ownership rule the pinned sites and one floating
+  label's, so a `build` job on `windows-latest` in `release.yml` could claim the
+  `build` job on `ubuntu-latest` in `ci.yml`, and report an image from outside
+  the window: an `::error` and a failed build, in a repo where nothing was wrong.
+
 - A job running inside a reusable workflow had its image discarded. Actions
   reports the *calling* workflow in `GITHUB_WORKFLOW_REF` while `GITHUB_JOB` is
   the id inside the callee, and the scan matched the file first, so the real
diff --git a/src/cli.mjs b/src/cli.mjs
index 37b39b7..19bd9cc 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -365,9 +365,16 @@ async function checkMigration(opts, io, now, imageOS, env, scan, lock, deps) {
   const tools = asked?.length ? asked : (locked?.length ? locked : scanned.tools);
   const load = deps.loadManifest ?? loadManifest;
   const here = runningJob(env);
+  // Every other site in the scan, not just the pinned ones: the job this run
+  // came from may be on a different floating label, and the ownership rule
+  // needs the whole scan to tell one job id from the same id in another file.
+  const elsewhere = (label) => [
+    ...scanned.floatingSites.filter((site) => site.label !== label),
+    ...scanned.labelSites,
+  ];
   const surveys = await Promise.all(
     [...byLabel].map(([label, sites]) =>
-      surveyMigration({ label, now, imageOS, tools, sites, others: scanned.labelSites, here, load }),
+      surveyMigration({ label, now, imageOS, tools, sites, others: elsewhere(label), here, load }),
     ),
   );
 
diff --git a/src/detect.mjs b/src/detect.mjs
index f736725..0365d1b 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -405,6 +405,10 @@ export function jobMatcher(here, sites = []) {
 /**
  * Who asked for `label` here, and whether anything else asks for `observed` too.
  *
+ * `sites` are this label's, `others` is every other site the scan found. Both
+ * are needed to place the running job: a job id is unique within a file, not
+ * across a repository, so the file has to decide when two files use the same id.
+ *
  * `scoped` is whether a running job was identified at all; without one every
  * site in the repository is in scope and the caller has to decide how much that
  * is worth. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
diff --git a/test/fixtures/workflows-two-builds/ci.yml b/test/fixtures/workflows-two-builds/ci.yml
new file mode 100644
index 0000000..e4b3414
--- /dev/null
+++ b/test/fixtures/workflows-two-builds/ci.yml
@@ -0,0 +1,8 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: node --version
diff --git a/test/fixtures/workflows-two-builds/release.yml b/test/fixtures/workflows-two-builds/release.yml
new file mode 100644
index 0000000..39af55b
--- /dev/null
+++ b/test/fixtures/workflows-two-builds/release.yml
@@ -0,0 +1,9 @@
+name: release
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 0f158fe..74c7bc4 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -551,6 +551,30 @@ const inJob = (job) => ({
   GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/latest.yml@refs/heads/main',
 });
 
+test('a job id shared by two workflow files is told apart by the file', async () => {
+  // ci.yml and release.yml both have a job called build. This run is the
+  // Windows one, so its ImageOS says nothing about ubuntu-latest.
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '0',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-two-builds'),
+    },
+    {
+      ImageOS: 'win25',
+      GITHUB_JOB: 'build',
+      GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/release.yml@refs/heads/main',
+    },
+    DURING,
+  );
+  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const s = j.migration.surveys[0];
+  assert.equal(s.observed, null, 'the windows job is not evidence about ubuntu-latest');
+  assert.notEqual(s.state, MIGRATION_STATE.UNEXPECTED);
+  assert.match(s.notes.join(' '), /did not run on ubuntu-latest/);
+});
+
 test('a guard step on an unrelated image says nothing about the floating label', async () => {
   const r = await guard(
     { tools: 'node', 'fail-on-migration': '0', json: true },

From 0c71c4eb4ec2f05baefb6114c935328fcf405a48 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 16:19:56 +0800
Subject: [PATCH 24/44] Finish the own-key sweep: five tables were still read
 as prototypes

The 1.4.0 hardening converted the tables it went looking for and missed the
ones reached from the scanner, the prober and the retirement lane.

`run: constructor build .` (conda ships that CLI) became a detected tool, and
`isProbeable` then handed `probeTool` the Object constructor instead of a list
of recipes: "recipes is not iterable", exit 2, report-this-bug. `uses:
constructor@v1` put the function itself into the tool set. And `runs-on:
constructor` with --fail-on-retirement produced a status with no migrateTo, so
the annotation crashed on join.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md             | 12 +++++++++---
 src/detect.mjs           |  5 +++--
 src/labels.mjs           |  4 ++--
 src/probe.mjs            |  6 ++++--
 test/detect.test.mjs     | 20 ++++++++++++++++++++
 test/retirement.test.mjs | 10 ++++++++++
 6 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 500fb2a..32efc93 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -167,8 +167,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - `--tools constructor`, or a lock file with a tool of that name, crashed in the
   manifest resolver: the candidate-names table answered with a function, and a
-  function is not a list of names. The three tables keyed by a tool or a command
-  read as data now, like the label ones.
+  function is not a list of names. Every table keyed by a tool or a command reads
+  as data now, like the label ones. That includes the three the scanner and the
+  prober use, so a `run:` step calling conda's `constructor` CLI, or a
+  `uses: constructor@v1`, no longer becomes a detected tool whose probe recipe
+  is a function.
 
 - A manifest read that failed was remembered as failed. The run reads each
   manifest once, and the memo held the rejected promise, so the lane that asked
@@ -180,7 +183,10 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Every table keyed by a runner label answered `__proto__` and `constructor`
   with something truthy, so `plan --from constructor` took the resolved-migration
   branch and then reported that `--from` was missing. `deadlineFor`,
-  `pathForLabel` and `migrationFor` all read their tables as data now.
+  `pathForLabel`, `migrationFor`, `nextBrownout` and `retirementStatus` all read
+  their tables as data now. The last two returned a deadline with no migration
+  targets, and `guard --fail-on-retirement` crashed writing the annotation that
+  tells you where to move.
 
 - `ImageOS=__proto__` resolved to a label. The env value indexed the
   `ImageOS` -> label table directly, so any property of `Object.prototype` came
diff --git a/src/detect.mjs b/src/detect.mjs
index 0365d1b..96df9a7 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -10,6 +10,7 @@ import { readdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { COMMAND_ALIASES, SETUP_ACTION_ALIASES, canonicalTool } from './tools.mjs';
 import { isFloating, normaliseLabel } from './labels.mjs';
+import { lookup } from './tables.mjs';
 
 const WORKFLOW_EXT = /\.ya?ml$/i;
 const LABEL_SHAPE = /^(ubuntu|windows|macos)-[a-z0-9.-]+$/i;
@@ -113,7 +114,7 @@ export function commandsInScript(script) {
     const token = s.split(/\s+/)[0];
     if (!token) continue;
     const base = token.split(/[\\/]/).pop().replace(/\.(exe|cmd|bat)$/i, '');
-    if (COMMAND_ALIASES[base.toLowerCase()]) found.add(base.toLowerCase());
+    if (lookup(COMMAND_ALIASES, base.toLowerCase())) found.add(base.toLowerCase());
   }
   return [...found];
 }
@@ -536,7 +537,7 @@ function actionSlug(ref) {
 export function setupTools(usesSites) {
   const tools = new Set();
   for (const { ref } of usesSites) {
-    const tool = SETUP_ACTION_ALIASES[actionSlug(ref)];
+    const tool = lookup(SETUP_ACTION_ALIASES, actionSlug(ref));
     if (tool) tools.add(tool);
   }
   return [...tools];
diff --git a/src/labels.mjs b/src/labels.mjs
index 8add80f..81029ce 100644
--- a/src/labels.mjs
+++ b/src/labels.mjs
@@ -160,7 +160,7 @@ export function normaliseLabel(raw) {
 
 /** First brownout date on or after `now`, else null. */
 export function nextBrownout(label, now = new Date()) {
-  const dl = DEADLINES[label];
+  const dl = deadlineFor(label);
   if (!dl) return null;
   for (const b of dl.brownouts ?? []) {
     const d = daysUntilDate(b, now);
@@ -171,7 +171,7 @@ export function nextBrownout(label, now = new Date()) {
 
 /** Retirement countdown for a label, or null when it has no announced deadline. */
 export function retirementStatus(label, now = new Date()) {
-  const dl = DEADLINES[label];
+  const dl = deadlineFor(label);
   if (!dl) return null;
   const daysToUnsupported = daysUntilDate(dl.fullyUnsupported, now);
   const brownout = nextBrownout(label, now);
diff --git a/src/probe.mjs b/src/probe.mjs
index adc2709..a6ed405 100644
--- a/src/probe.mjs
+++ b/src/probe.mjs
@@ -9,6 +9,8 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { lookup } from './tables.mjs';
+
 const IS_WINDOWS = process.platform === 'win32';
 
 /** canonical tool -> probe recipe(s), tried in order */
@@ -32,7 +34,7 @@ export const PROBES = {
 };
 
 export function isProbeable(tool) {
-  return Boolean(PROBES[tool]);
+  return Boolean(lookup(PROBES, tool));
 }
 
 function runOne(recipe, timeoutMs) {
@@ -58,7 +60,7 @@ function runOne(recipe, timeoutMs) {
  *           {tool, ok:false, reason:string}}
  */
 export function probeTool(tool, { timeoutMs = 15000 } = {}) {
-  const recipes = PROBES[tool];
+  const recipes = lookup(PROBES, tool);
   if (!recipes) return { tool, ok: false, reason: 'no probe recipe' };
   for (const r of recipes) {
     let hit = null;
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index f60a63c..6ecec55 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -14,6 +14,7 @@ import {
   SELF_HOSTED,
 } from '../src/detect.mjs';
 import { canonicalTool, manifestCandidates } from '../src/tools.mjs';
+import { isProbeable, probeTool } from '../src/probe.mjs';
 import { FIXTURES } from './helpers.mjs';
 
 test('extracts an inline runs-on label', () => {
@@ -82,6 +83,25 @@ test('a tool named after a property of Object is just an unknown tool', () => {
   for (const name of ['constructor', 'toString', '__proto__']) {
     assert.equal(typeof canonicalTool(name), 'string', name);
     assert.deepEqual(manifestCandidates(name), [name], name);
+    assert.equal(isProbeable(name), false, name);
+    assert.equal(probeTool(name).reason, 'no probe recipe', name);
+  }
+});
+
+test('a step that runs a command named after Object is not a detected tool', () => {
+  // conda ships a real `constructor` CLI, so this reaches the scanner from a
+  // plain workflow. Inherited, it used to become a tool with no probe recipe.
+  for (const name of ['constructor', 'toString', 'valueOf']) {
+    assert.deepEqual(commandsInScript(`${name} --build .`), [], name);
+    const r = analyseWorkflow(
+      `jobs:
+  a:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: ${name}@v1
+`,
+    );
+    assert.deepEqual(r.tools, [], name);
   }
 });
 
diff --git a/test/retirement.test.mjs b/test/retirement.test.mjs
index aa21aa7..b3c5092 100644
--- a/test/retirement.test.mjs
+++ b/test/retirement.test.mjs
@@ -36,6 +36,16 @@ test('nextBrownout is null for unknown labels', () => {
   assert.equal(nextBrownout('not-a-label', NOW), null);
 });
 
+test('a runs-on named after a property of Object has no deadline', () => {
+  // The bogus status that Object.prototype handed back had no migrateTo, and
+  // the annotation that follows a finding joins that list into a sentence.
+  for (const name of ['constructor', 'toString', 'valueOf']) {
+    assert.equal(nextBrownout(name, NOW), null, name);
+    assert.equal(retirementStatus(name, NOW), null, name);
+    assert.deepEqual(retirementFindings([{ label: name, file: 'ci.yml', line: 5, col: 14 }], { now: NOW, days: 90 }), [], name);
+  }
+});
+
 /* -------------------------------------------------------- retirementStatus */
 
 test('retirementStatus before deprecation starts', () => {

From 089a819f1b8b7a20e8ebd8206cea71591d6de511 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 16:40:44 +0800
Subject: [PATCH 25/44] Tool names reach the diff from a lock file, so the maps
 need no prototype

`'constructor' in lockedMap` is true on a plain object, so a lock file with a
tool of that name handed diffTool a function: "(to ?? []).filter is not a
function", exit 2. The attribution map was the next crash, and `__proto__` was
quietly dropped on the way in rather than compared.

The maps the diff and the attribution are built from are Object.create(null)
now, and the two that arrive as arguments to an exported function are read
through lookup(). Also documents the runGuard --update-lock default, which
this branch changed on the drift path without saying so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md         | 18 ++++++++++++++++++
 src/cli.mjs          | 13 +++++++------
 src/diff.mjs         |  4 +++-
 src/history.mjs      |  5 +++--
 src/lock.mjs         |  4 ++--
 src/manifest.mjs     |  2 +-
 src/probe.mjs        |  2 +-
 src/report.mjs       |  5 +++--
 test/guard.test.mjs  | 25 +++++++++++++++++++++++++
 test/lock.test.mjs   | 12 ++++++------
 test/report.test.mjs |  9 +++++++++
 11 files changed, 78 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 32efc93..93190b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -109,6 +109,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   number, so a threshold sitting exactly on a boundary can fire a day later than
   it did in 1.3.0.
 
+- The exported `runGuard` now writes the lock file unless the caller passes
+  `{ 'update-lock': false }`, on the drift path as well as the first run. It used
+  to write on a first run and stay silent on a drift run, because the drift path
+  read the key as a plain boolean and a caller building options by hand has
+  neither the flag nor the parser default. The CLI is unaffected: it sets the key
+  either way.
+
 - `resolveManifestVersions` moved from `src/cli.mjs` to `src/manifest.mjs`, where
   the rest of the manifest reading lives, and is re-exported from `cli.mjs` so
   the public surface is unchanged. The migration lane needed it and importing it
@@ -180,6 +187,17 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   which reads as every locked tool having been removed. Only a read that worked
   is kept.
 
+- A tool named after a property of `Object` crashed the drift diff. The maps the
+  diff is built from are keyed by tool name, which comes from the lock file,
+  `--tools` or the scanner, and they were plain objects: `'constructor' in
+  lockedMap` was true, `diffTool` got a function where a version list belongs,
+  and guard exited 2 with a report-this-bug prompt. The attribution map had the
+  same hole and was the next line to crash. Those maps have no prototype now,
+  and the two that arrive as arguments to a public function are read as data,
+  so such a tool diffs like any other. `__proto__` was worse than a crash: the
+  entry was silently dropped on the way in, so a locked tool of that name was
+  never compared at all.
+
 - Every table keyed by a runner label answered `__proto__` and `constructor`
   with something truthy, so `plan --from constructor` took the resolved-migration
   branch and then reported that `--from` was missing. `deadlineFor`,
diff --git a/src/cli.mjs b/src/cli.mjs
index 19bd9cc..b0fd387 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -30,6 +30,7 @@ import { detect, labelOwnership, runningJob, SELF_HOSTED } from './detect.mjs';
 import { canonicalTool, knownTools, MANIFEST_CANDIDATES } from './tools.mjs';
 import { probeTool, isProbeable } from './probe.mjs';
 import { diffTool, shouldFail, maxSeverity } from './diff.mjs';
+import { lookup } from './tables.mjs';
 import { readLock, writeLock, lockPayload, DEFAULT_LOCK_FILE, toolsEntry, toVersionMap } from './lock.mjs';
 import {
   planReport,
@@ -548,7 +549,7 @@ export async function runInit(opts, io = process) {
   }
 
   const { map, missing } = resolveManifestVersions(manifest, tools);
-  const lockTools = {};
+  const lockTools = Object.create(null);
   for (const [t, versions] of Object.entries(map)) {
     lockTools[t] = toolsEntry(versions, 'manifest');
   }
@@ -740,7 +741,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   }
 
   // Observe the live runner: probe first, manifest as the fallback.
-  const observed = {};
+  const observed = Object.create(null);
   const probeNotes = [];
   const needManifest = [];
   for (const t of tools) {
@@ -839,12 +840,12 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // Diff against the lock.
   const lockedMap = toVersionMap(lock.tools);
   const observedMap = toVersionMap(observed);
-  const watched = tools.filter((t) => t in lockedMap || t in observedMap);
-  const diffs = watched.map((t) => diffTool(t, lockedMap[t] ?? null, observedMap[t] ?? null));
+  const watched = tools.filter((t) => Object.hasOwn(lockedMap, t) || Object.hasOwn(observedMap, t));
+  const diffs = watched.map((t) => diffTool(t, lookup(lockedMap, t), lookup(observedMap, t)));
   const changed = diffs.filter((d) => d.changed);
 
   // Attribute each change to the runner-images commit that shipped it.
-  let attributionMap = {};
+  let attributionMap = Object.create(null);
   if (changed.length && lock.imageVersion && lock.imageVersion !== imageVersion) {
     try {
       const commits = await listManifestCommits(label);
@@ -916,7 +917,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       );
     }
     for (const d of changed) {
-      const a = attributionMap[d.tool];
+      const a = lookup(attributionMap, d.tool);
       out(
         io.stdout,
         `  ${d.tool} ${d.from.join(',') || '(absent)'} -> ${d.to.join(',') || '(absent)'}  ${d.detail}` +
diff --git a/src/diff.mjs b/src/diff.mjs
index 9955e75..56c1265 100644
--- a/src/diff.mjs
+++ b/src/diff.mjs
@@ -7,6 +7,8 @@
  * to see — a naive first-element compare hides two thirds of it.
  */
 
+import { lookup } from './tables.mjs';
+
 export const SEVERITY_ORDER = ['none', 'patch', 'minor', 'major'];
 
 export function parseVersion(v) {
@@ -120,7 +122,7 @@ function mk(tool, from, to, kind, severity, added, removed, detail, changed) {
  * canonical name to the manifest's own key is done by the caller.
  */
 export function diffToolMaps(tools, fromMap, toMap) {
-  return tools.map((t) => diffTool(t, fromMap[t] ?? null, toMap[t] ?? null));
+  return tools.map((t) => diffTool(t, lookup(fromMap, t), lookup(toMap, t)));
 }
 
 /** Highest severity across a list of diffs. */
diff --git a/src/history.mjs b/src/history.mjs
index 1cb47dd..d1772b5 100644
--- a/src/history.mjs
+++ b/src/history.mjs
@@ -11,6 +11,7 @@ import { fetchJson, fetchText, DriftError } from './http.mjs';
 import { compareDottedNumbers as compareImageVersions } from './diff.mjs';
 import { API_BASE, RAW_BASE, RUNNER_IMAGES_REPO, pathForLabel } from './labels.mjs';
 import { parseManifest } from './manifest.mjs';
+import { lookup } from './tables.mjs';
 
 const VERSION_RE = /version\s+(\d{8}\.[\d.]+)/i;
 
@@ -116,7 +117,7 @@ export function commitWindow(commits, fromVersion, toVersion) {
  */
 export async function attributeChanges(label, diffs, window, { maxFetch = 8, candidates = null } = {}) {
   const changed = diffs.filter((d) => d.changed);
-  const out = {};
+  const out = Object.create(null);
   if (!window.length || !changed.length) return out;
 
   const newest = window.at(-1);
@@ -164,7 +165,7 @@ function sameSet(a, b) {
 }
 
 function resolveVersions(manifest, tool, candidates) {
-  const names = candidates?.[tool] ?? [tool];
+  const names = (candidates ? lookup(candidates, tool) : null) ?? [tool];
   const index = new Map(Object.keys(manifest.tools ?? {}).map((k) => [k.toLowerCase(), k]));
   for (const n of names) {
     const hit = index.get(String(n).toLowerCase());
diff --git a/src/lock.mjs b/src/lock.mjs
index 2c7c65a..f8e1b91 100644
--- a/src/lock.mjs
+++ b/src/lock.mjs
@@ -90,9 +90,9 @@ export function toolsEntry(versions, source, extra = {}) {
   return { versions: [...versions], source, ...extra };
 }
 
-/** `{Tool: {versions, source}}` -> `{Tool: versions[]}` */
+/** `{Tool: {versions, source}}` -> `{Tool: versions[]}`, keyed without a prototype. */
 export function toVersionMap(tools) {
-  const out = {};
+  const out = Object.create(null);
   for (const [k, v] of Object.entries(tools ?? {})) {
     out[k] = Array.isArray(v) ? v : (v?.versions ?? []);
   }
diff --git a/src/manifest.mjs b/src/manifest.mjs
index 5729704..b6fe7ad 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -369,7 +369,7 @@ export function diffManifestTools(from, to, tools) {
  * @returns {{map:Record<string,string[]>, missing:string[]}}
  */
 export function resolveManifestVersions(manifest, tools) {
-  const map = {};
+  const map = Object.create(null);
   const missing = [];
   for (const t of tools) {
     const hit = lookupTool(manifest, manifestCandidates(t));
diff --git a/src/probe.mjs b/src/probe.mjs
index a6ed405..3aedfbb 100644
--- a/src/probe.mjs
+++ b/src/probe.mjs
@@ -78,7 +78,7 @@ export function probeTool(tool, { timeoutMs = 15000 } = {}) {
 
 /** Probe many tools. Never throws. */
 export function probeTools(tools, opts = {}) {
-  const out = {};
+  const out = Object.create(null);
   for (const t of tools) out[t] = probeTool(t, opts);
   return out;
 }
diff --git a/src/report.mjs b/src/report.mjs
index b08bb47..168820b 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -19,6 +19,7 @@ import {
   retirementStatus,
 } from './labels.mjs';
 import { REF_STATUS } from './runtimes.mjs';
+import { lookup } from './tables.mjs';
 import {
   MINIMUM_REGISTRATION_VERSION,
   RUNNER_STATUS,
@@ -202,7 +203,7 @@ export function stepSummaryMarkdown({
   }
 
   const rows = changed.map((d) => {
-    const a = attribution[d.tool];
+    const a = lookup(attribution, d.tool);
     const shipped = a
       ? `[${a.imageVersion ?? a.sha.slice(0, 7)}](${a.url})${a.exact ? '' : ' _(approx)_'}`
       : '—';
@@ -264,7 +265,7 @@ export function annotations(diffs, attribution = {}, label = '') {
   return diffs
     .filter((d) => d.changed)
     .map((d) => {
-      const a = attribution[d.tool];
+      const a = lookup(attribution, d.tool);
       const where = a ? ` — shipped by ${a.imageVersion ?? a.sha.slice(0, 7)} ${a.url}` : '';
       const sev = d.severity.toUpperCase();
       const detail = d.detail === sev ? sev : `${sev}: ${d.detail}`;
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index c009ee3..284771a 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -123,6 +123,31 @@ test('drift is reported with a ::warning and exits 0 by default', async () => {
   }
 });
 
+test('a lock file naming a tool after a property of Object diffs like any other', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  try {
+    // Written as text: a `__proto__` key survives JSON.parse as an own property,
+    // but an object literal would set the prototype instead.
+    await writeFile(
+      lockFile,
+      `{"schemaVersion":${SCHEMA_VERSION},"label":"ubuntu-22.04","imageOS":"ubuntu22",`
+        + `"imageVersion":"${IMAGE}","tools":{`
+        + `"constructor":{"versions":["1.0.0"],"source":"manifest"},`
+        + `"__proto__":{"versions":["2.0.0"],"source":"manifest"}}}`,
+      'utf8',
+    );
+    const r = await guard({ 'lock-file': lockFile, 'update-lock': false }, ENV, {
+      loadManifest: fixtureLoader(),
+    });
+    assert.equal(r.code, EXIT_OK);
+    assert.match(r.stdout, /constructor 1\.0\.0 -> \(absent\)/);
+    assert.match(r.stdout, /__proto__ 2\.0\.0 -> \(absent\)/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('exit code 1 only under --fail-on major (and above)', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
diff --git a/test/lock.test.mjs b/test/lock.test.mjs
index db9418e..31908c4 100644
--- a/test/lock.test.mjs
+++ b/test/lock.test.mjs
@@ -84,10 +84,10 @@ test('writing to an unwritable path gives an actionable message', async () => {
   );
 });
 
-test('toVersionMap accepts both entry shapes', () => {
-  assert.deepEqual(
-    toVersionMap({ A: { versions: ['1.0.0'], source: 'probe' }, B: ['2.0.0'] }),
-    { A: ['1.0.0'], B: ['2.0.0'] },
-  );
-  assert.deepEqual(toVersionMap(undefined), {});
+test('toVersionMap accepts both entry shapes, and answers only for its own keys', () => {
+  const map = toVersionMap({ A: { versions: ['1.0.0'], source: 'probe' }, B: ['2.0.0'] });
+  assert.deepEqual({ ...map }, { A: ['1.0.0'], B: ['2.0.0'] });
+  assert.equal(Object.getPrototypeOf(map), null, 'a tool named `constructor` is data, not a function');
+  assert.equal('constructor' in map, false);
+  assert.deepEqual({ ...toVersionMap(undefined) }, {});
 });
diff --git a/test/report.test.mjs b/test/report.test.mjs
index 264a0cd..d83a9ec 100644
--- a/test/report.test.mjs
+++ b/test/report.test.mjs
@@ -86,6 +86,15 @@ test('annotations name the tool, the change and the shipping commit', () => {
   assert.match(line, /shipped by 20260720\.234\.2/);
 });
 
+test('a tool named after a property of Object has no attribution, not a fake one', () => {
+  const diffs = [diffTool('constructor', ['1.0.0'], ['2.0.0'])];
+  const [line] = annotations(diffs, {}, 'ubuntu-22.04');
+  assert.match(line, /constructor drifted on ubuntu-22\.04: 1\.0\.0 -> 2\.0\.0/);
+  assert.doesNotMatch(line, /shipped by/);
+  const md = stepSummaryMarkdown({ label: 'ubuntu-22.04', imageVersion: '20260720.234.2', diffs });
+  assert.match(md, /`constructor`/);
+});
+
 test('unchanged tools produce no annotations', () => {
   assert.deepEqual(annotations([diffTool('CMake', ['3.31.6'], ['3.31.6'])]), []);
 });

From 4c0f07d69070ad806f882deaf76f1301cbf260b0 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 16:57:53 +0800
Subject: [PATCH 26/44] A lock from the other side of a migration is not this
 image's history

With a lock on ubuntu-24.04 and a runner on ubuntu-26.04, guard searched the
26.04 commit list for a 24.04 image version, missed, and stamped every moved
tool with the nearest 26.04 commit instead. The header printed a 24.04 version
under the 26.04 label. explainDrift right below already knew the label moved.

A run whose label moved now names both labels and attributes nothing.

The guard suite also claimed to be offline and was not: one test held a lock
version the env did not, which reached GitHub for attribution and, once rate
limited, put `${{ github.token }}` in front of the --json document that a test
was slicing at the first brace. Both fixed, and the brace slice is now one
helper that finds the line the document opens on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md             | 10 +++++++++
 src/cli.mjs              | 18 ++++++++++++----
 src/report.mjs           |  7 ++++++-
 test/guard.test.mjs      | 45 ++++++++++++++++++++++++++++++++++------
 test/helpers.mjs         | 12 +++++++++++
 test/migration.test.mjs  | 22 ++++++++++----------
 test/retirement.test.mjs |  5 ++---
 test/runners.test.mjs    |  6 +++---
 8 files changed, 97 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93190b2..11f2839 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -187,6 +187,16 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   which reads as every locked tool having been removed. Only a read that worked
   is kept.
 
+- Mid-migration, the drift lane attributed the change to the wrong image's
+  history. A lock recorded on `ubuntu-24.04` and a runner on `ubuntu-26.04` are
+  two operating systems, but guard looked the locked image version up in the
+  26.04 commit list, found nothing, and fell back to the nearest 26.04 commit,
+  so every moved tool was stamped with a commit that did not ship it. The header
+  had the same shape: `ubuntu-26.04 image 20260720.247.2 -> 20260907.131.1`,
+  where the first version is a 24.04 image. A run whose label moved names both
+  labels now and attributes nothing, in the log, the step summary and `--json`,
+  which gained `fromLabel`.
+
 - A tool named after a property of `Object` crashed the drift diff. The maps the
   diff is built from are keyed by tool name, which comes from the lock file,
   `--tools` or the scanner, and they were plain objects: `'constructor' in
diff --git a/src/cli.mjs b/src/cli.mjs
index b0fd387..1b37b57 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -844,9 +844,18 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   const diffs = watched.map((t) => diffTool(t, lookup(lockedMap, t), lookup(observedMap, t)));
   const changed = diffs.filter((d) => d.changed);
 
+  // A lock recorded on another label is a different operating system, not an
+  // image bump: the version in it was never a version of this label, and no
+  // commit in this label's history shipped the difference. During the
+  // `ubuntu-latest` migration that is the ordinary case, not an edge one.
+  const movedLabel = Boolean(lock.label) && lock.label !== label;
+  const imageRange = movedLabel
+    ? `${lock.label} image ${lock.imageVersion} -> ${label} image ${imageVersion}`
+    : `${label} image ${lock.imageVersion} -> ${imageVersion}`;
+
   // Attribute each change to the runner-images commit that shipped it.
   let attributionMap = Object.create(null);
-  if (changed.length && lock.imageVersion && lock.imageVersion !== imageVersion) {
+  if (changed.length && !movedLabel && lock.imageVersion && lock.imageVersion !== imageVersion) {
     try {
       const commits = await listManifestCommits(label);
       const window = commitWindow(commits, lock.imageVersion, imageVersion);
@@ -880,6 +889,7 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   const summary = stepSummaryMarkdown({
     label,
     explains: explained,
+    fromLabel: movedLabel ? lock.label : null,
     fromImage: lock.imageVersion ?? '(unknown)',
     toImage: imageVersion,
     diffs,
@@ -900,15 +910,15 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   }
 
   if (opts.json) {
-    const payload = { label, from: lock.imageVersion, to: imageVersion, approximate, written: updateLock, diffs, attribution: attributionMap };
+    const payload = { label, fromLabel: lock.label ?? null, from: lock.imageVersion, to: imageVersion, approximate, written: updateLock, diffs, attribution: attributionMap };
     payload.explains = explained?.label ?? null;
     if (retirement) payload.retirement = retirement;
     if (migration) payload.migration = { ...migration, explains: explained?.label ?? null };
     out(io.stdout, JSON.stringify(payload, null, 2));
   } else if (!changed.length) {
-    out(io.stdout, `No drift — ${label} image ${lock.imageVersion} -> ${imageVersion}, ${diffs.length} tool(s) unchanged.`);
+    out(io.stdout, `No drift — ${imageRange}, ${diffs.length} tool(s) unchanged.`);
   } else {
-    out(io.stdout, `${label} image ${lock.imageVersion} -> ${imageVersion}${approximate ? ' (attribution approximate)' : ''}`);
+    out(io.stdout, `${imageRange}${approximate ? ' (attribution approximate)' : ''}`);
     if (explained) {
       out(
         io.stdout,
diff --git a/src/report.mjs b/src/report.mjs
index 168820b..ab53015 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -151,6 +151,7 @@ const SEVERITY_BADGE = {
 /** GitHub step-summary markdown for a `guard` run. */
 export function stepSummaryMarkdown({
   label,
+  fromLabel = null,
   fromImage,
   toImage,
   diffs,
@@ -181,7 +182,11 @@ export function stepSummaryMarkdown({
   }
 
   const changed = diffs.filter((d) => d.changed);
-  lines.push(`\`${label}\` image \`${fromImage}\` → \`${toImage}\``);
+  lines.push(
+    fromLabel && fromLabel !== label
+      ? `\`${fromLabel}\` image \`${fromImage}\` → \`${label}\` image \`${toImage}\``
+      : `\`${label}\` image \`${fromImage}\` → \`${toImage}\``,
+  );
   if (approximate) {
     lines.push('');
     lines.push(
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 284771a..9a0de84 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -5,7 +5,7 @@ import os from 'node:os';
 import { mkdtemp, rm, readFile, writeFile } from 'node:fs/promises';
 import { loaderFor, runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
 import { readLock, writeLock, SCHEMA_VERSION } from '../src/lock.mjs';
-import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
+import { captureIO, fixtureLoader, FIXTURES, jsonOf, stubApi } from './helpers.mjs';
 
 async function tmp() {
   return mkdtemp(path.join(os.tmpdir(), 'runner-drift-test-'));
@@ -61,7 +61,7 @@ test('--json off an unknown image still prints what the lanes found', async () =
       { now: new Date('2026-09-20T00:00:00Z'), loadManifest: fixtureLoader({ 'ubuntu-24.04': 'ubuntu-24.04@2026-09' }) },
     );
     assert.match(r.stdout, /Unknown runner label/);
-    const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+    const j = jsonOf(r.stdout);
     assert.equal(j.migration.surveys[0].label, 'ubuntu-latest');
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -148,6 +148,39 @@ test('a lock file naming a tool after a property of Object diffs like any other'
   }
 });
 
+test('a lock from the other side of a migration is not attributed to this image history', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const api = stubApi(() => ({ status: 200, body: [] }));
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-24.04',
+        imageOS: 'ubuntu24',
+        imageVersion: '20260720.247.2',
+        tools: { 'Node.js': { versions: ['18.0.0'], source: 'probe' } },
+      },
+      lockFile,
+    );
+    const r = await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false }, {
+      ImageVersion: '20260907.131.1',
+      ImageOS: 'ubuntu26',
+    });
+    assert.equal(r.code, EXIT_OK);
+    assert.match(
+      r.stdout,
+      /ubuntu-24\.04 image 20260720\.247\.2 -> ubuntu-26\.04 image 20260907\.131\.1/,
+      'both labels named, because the two images are different operating systems',
+    );
+    assert.deepEqual(api.calls, [], 'no commit in the 26.04 history shipped a 24.04 difference');
+    assert.doesNotMatch(r.stdout, /Attribution unavailable/);
+    assert.doesNotMatch(r.stdout, /shipped by/);
+  } finally {
+    api.restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('exit code 1 only under --fail-on major (and above)', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
@@ -230,7 +263,7 @@ test('--json off a hosted runner still prints the retirement document', async ()
     },
     {},
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.ok(j.retirement.findings.length, 'the lane ran, so its findings are in the document');
 });
 
@@ -381,15 +414,15 @@ test('--json says whether the lock was written', async () => {
       {
         label: 'ubuntu-22.04',
         imageOS: 'ubuntu22',
-        imageVersion: '20260623.199.1',
+        imageVersion: IMAGE,
         tools: { 'Node.js': { versions: ['18.0.0'], source: 'probe' } },
       },
       lockFile,
     );
     const off = await guard({ tools: 'node', 'lock-file': lockFile, 'update-lock': false, json: true });
-    assert.equal(JSON.parse(off.stdout.slice(off.stdout.indexOf('{'))).written, false);
+    assert.equal(jsonOf(off.stdout).written, false);
     const on = await guard({ tools: 'node', 'lock-file': lockFile, json: true });
-    assert.equal(JSON.parse(on.stdout.slice(on.stdout.indexOf('{'))).written, true);
+    assert.equal(jsonOf(on.stdout).written, true);
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
diff --git a/test/helpers.mjs b/test/helpers.mjs
index 9abeb06..9ea361f 100644
--- a/test/helpers.mjs
+++ b/test/helpers.mjs
@@ -103,6 +103,18 @@ export function runnerRoutes({ scopePath, fleet, recorded, releases, listing = n
 }
 
 /** Capture stdout/stderr from a command function. */
+/**
+ * The `--json` document a run printed, past the annotation lines above it.
+ * Found by the line the document opens on: an annotation can contain a brace of
+ * its own, and the rate-limit hint spells out `${{ github.token }}`.
+ */
+export function jsonOf(stdout) {
+  const at = stdout.search(/^\{$/m);
+  if (at < 0) throw new Error(`no JSON document in:
+${stdout}`);
+  return JSON.parse(stdout.slice(at));
+}
+
 export function captureIO() {
   const outChunks = [];
   const errChunks = [];
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 74c7bc4..6f7cac6 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -20,7 +20,7 @@ import { migrationAnnotations, migrationLines, migrationSummaryMarkdown } from '
 import { detect, extractFloatingSites, extractLabelSites, jobMatcher } from '../src/detect.mjs';
 import { writeLock } from '../src/lock.mjs';
 import { runGuard, runPlan, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
-import { captureIO, fixtureLoader, FIXTURES } from './helpers.mjs';
+import { captureIO, fixtureLoader, FIXTURES, jsonOf } from './helpers.mjs';
 
 const WORKFLOWS = path.join(FIXTURES, 'workflows-migration');
 
@@ -535,7 +535,7 @@ test('a bad --fail-on-migration value is a usage error', async () => {
 
 test('the migration ride-along appears in guard --json', async () => {
   const r = await guard({ tools: 'node', 'fail-on-migration': '30', json: true });
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.equal(j.migration.days, 30);
   assert.equal(j.migration.surveys.length, 1);
   assert.equal(j.migration.surveys[0].state, 'pending');
@@ -568,7 +568,7 @@ test('a job id shared by two workflow files is told apart by the file', async ()
     },
     DURING,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   const s = j.migration.surveys[0];
   assert.equal(s.observed, null, 'the windows job is not evidence about ubuntu-latest');
   assert.notEqual(s.state, MIGRATION_STATE.UNEXPECTED);
@@ -581,7 +581,7 @@ test('a guard step on an unrelated image says nothing about the floating label',
     { ImageOS: 'ubuntu22', ...inJob('lint') },
     BEFORE,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   const s = j.migration.surveys[0];
   assert.equal(s.state, MIGRATION_STATE.PENDING, 'the lint runner is not evidence');
   assert.equal(s.observed, null);
@@ -596,7 +596,7 @@ test('the job that does ask for the label owns the image it ran on', async () =>
     { ImageOS: 'ubuntu22', ...inJob('build') },
     BEFORE,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.UNEXPECTED);
   assert.deepEqual(j.migration.surveys[0].notes, []);
   assert.equal(r.code, EXIT_DRIFT, 'ubuntu-latest serving 22.04 is a real anomaly');
@@ -610,7 +610,7 @@ test('a job pinned to the old image is not the floating label running late', asy
     { ImageOS: 'ubuntu24', ...inJob('pinned') },
     AFTER,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.SETTLED);
   assert.equal(r.code, EXIT_OK, 'a pinned job is not a stale floating runner');
   assert.ok(!r.stdout.includes('::error'), 'nothing to raise');
@@ -632,7 +632,7 @@ test('mid-window, the job on the floating label still reads as migrated', async
     { ImageOS: 'ubuntu26', ...inJob('build') },
     DURING,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.equal(j.migration.surveys[0].state, MIGRATION_STATE.MIGRATED);
   assert.equal(j.migration.surveys[0].observed, 'ubuntu-26.04');
 });
@@ -832,7 +832,7 @@ test('the step summary names the explanation the way stdout does', async () => {
 
 test('--json names the explanation without --fail-on-migration too', async () => {
   const r = await guardAcrossTheMove({ json: true }, DURING);
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.equal(j.explains, 'ubuntu-latest');
   assert.equal(j.migration, undefined, 'the lane itself still needs the flag');
 });
@@ -848,7 +848,7 @@ test('a quoted job id is the same job GITHUB_JOB names', async () => {
     { ImageOS: 'ubuntu26', ...inJob('build') },
     DURING,
   );
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   const s = j.migration.surveys[0];
   assert.equal(s.observed, 'ubuntu-26.04', 'the runner is attributed to "build"');
   assert.equal(s.state, MIGRATION_STATE.MIGRATED);
@@ -857,7 +857,7 @@ test('a quoted job id is the same job GITHUB_JOB names', async () => {
 
 test('an empty --tools list falls back like no list at all', async () => {
   const r = await guard({ tools: ',', 'fail-on-migration': '30', json: true }, {}, BEFORE);
-  const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const j = jsonOf(r.stdout);
   assert.ok(
     j.migration.surveys[0].toolDiffs.length > 0,
     'the workflows are still scanned for tools',
@@ -889,7 +889,7 @@ test('the migration lane diffs the tools the lock watches', async () => {
       lockFile,
     );
     const r = await guard({ 'fail-on-migration': '30', 'lock-file': lockFile, json: true });
-    const j = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+    const j = jsonOf(r.stdout);
     const tools = j.migration.surveys[0].toolDiffs.map((d) => d.tool);
     assert.ok(tools.includes('Python'), 'the locked tool is in the diff');
     assert.ok(!tools.includes('Node.js'), 'and the ones only the workflows mention are not');
diff --git a/test/retirement.test.mjs b/test/retirement.test.mjs
index b3c5092..5ed6193 100644
--- a/test/retirement.test.mjs
+++ b/test/retirement.test.mjs
@@ -9,7 +9,7 @@ import {
 } from '../src/report.mjs';
 import { detect } from '../src/detect.mjs';
 import { runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
-import { captureIO, FIXTURES } from './helpers.mjs';
+import { captureIO, FIXTURES, jsonOf } from './helpers.mjs';
 
 // At this date macos-14 browns out in 54 days and retires in 82;
 // ubuntu-22.04 is 223 and 248 days out.
@@ -288,8 +288,7 @@ test('retirement rides along with the normal guard flow and its JSON', async ()
       { ImageVersion: '20260720.234.2', ImageOS: 'ubuntu22' },
     );
     assert.equal(r.code, EXIT_DRIFT);
-    const jsonStart = r.stdout.indexOf('{');
-    const parsed = JSON.parse(r.stdout.slice(jsonStart));
+    const parsed = jsonOf(r.stdout);
     assert.equal(parsed.baseline, true);
     assert.equal(parsed.retirement.days, 60);
     assert.equal(parsed.retirement.findings.length, 1);
diff --git a/test/runners.test.mjs b/test/runners.test.mjs
index 9aaa1cb..5a74356 100644
--- a/test/runners.test.mjs
+++ b/test/runners.test.mjs
@@ -34,7 +34,7 @@ import {
 } from '../src/report.mjs';
 import { detect } from '../src/detect.mjs';
 import { runRunners, runGuard, EXIT_OK, EXIT_DRIFT, EXIT_USAGE } from '../src/cli.mjs';
-import { captureIO, readRunnerFixtures, runnerRoutes, stubApi, FIXTURES } from './helpers.mjs';
+import { captureIO, FIXTURES, jsonOf, readRunnerFixtures, runnerRoutes, stubApi } from './helpers.mjs';
 
 /**
  * Every date below comes from the recorded live responses in
@@ -930,7 +930,7 @@ test('runners --repo defaults to $GITHUB_REPOSITORY', async () => {
 test('runners --json shapes the whole survey', async () => {
   const r = await runners({ org: 'acme', 'fail-on-deprecation': '30', json: true });
   assert.equal(r.code, EXIT_DRIFT);
-  const parsed = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const parsed = jsonOf(r.stdout);
   assert.equal(parsed.status, 'OK');
   assert.equal(parsed.scope.name, 'acme');
   assert.equal(parsed.windowDays, 30);
@@ -1069,7 +1069,7 @@ test('guard --json carries the runners block on the self-hosted path', async ()
     { org: 'acme', 'fail-on-deprecation': '30', json: true },
   );
   assert.equal(r.code, EXIT_DRIFT);
-  const parsed = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
+  const parsed = jsonOf(r.stdout);
   assert.equal(parsed.runners.groups[0].version, '2.335.1');
   assert.equal(parsed.runners.groups[0].status, 'RUNTIME-DUE');
   assert.equal(parsed.runners.totalCount, 1);

From b3a07bee303c1aeff5a10411114b1a6fb2359e30 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 17:13:58 +0800
Subject: [PATCH 27/44] A job id alone is unique in a file, so it cannot
 outvote another file

Inside a reusable workflow the run reports the caller in GITHUB_WORKFLOW_REF
and the job id lives in the callee, so the file drops out of the match. Only a
matrix leg counted as a rival after that, and a plain `runs-on: ubuntu-26.04`
under the same job id in another file could not veto attribution: the survey
reported ubuntu-latest MIGRATED off a runner that may have been the pinned job.

jobMatcher now goes through jobScope, which also says whether the id placed the
run in one file. Unplaced, the rival rule is the unscoped one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 10 ++++
 src/cli.mjs                                   |  9 +--
 src/detect.mjs                                | 35 +++++++----
 src/migration.mjs                             | 14 ++++-
 .../fixtures/workflows-shared-build-id/ci.yml |  8 +++
 .../workflows-shared-build-id/release.yml     |  9 +++
 test/migration.test.mjs                       | 58 +++++++++++++++++++
 7 files changed, 125 insertions(+), 18 deletions(-)
 create mode 100644 test/fixtures/workflows-shared-build-id/ci.yml
 create mode 100644 test/fixtures/workflows-shared-build-id/release.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11f2839..147fd2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -187,6 +187,16 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   which reads as every locked tool having been removed. Only a read that worked
   is kept.
 
+- A job id the run could not be placed by let one workflow file speak for
+  another. Inside a reusable workflow `GITHUB_WORKFLOW_REF` names the caller,
+  so the job is matched on its id alone, and an id is unique in a file rather
+  than in a repository. A `build` job pinned to `ubuntu-26.04` in `release.yml`
+  could not veto the `build` job on `ubuntu-latest` in `ci.yml`, because only a
+  matrix leg counted as a rival explanation. A run that cannot be placed in one
+  file now treats any job of that id pinned to the observed image as the nearer
+  explanation, exactly as it does when there is no job id at all, and says so
+  rather than reporting the label as migrated.
+
 - Mid-migration, the drift lane attributed the change to the wrong image's
   history. A lock recorded on `ubuntu-24.04` and a runner on `ubuntu-26.04` are
   two operating systems, but guard looked the locked image version up in the
diff --git a/src/cli.mjs b/src/cli.mjs
index 1b37b57..ebbaedd 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -410,16 +410,17 @@ async function explainDrift({ migration, lock, label, scan, env }) {
   const here = runningJob(env);
   // `label` is this runner's own: a matrix leg naming it is a pin the repo
   // chose, not the window moving the job, so the explanation is withheld.
-  const { direct, asked, rival } = labelOwnership({
+  const { asked, rival } = labelOwnership({
     label: m.label,
     observed: label,
     sites: scanned.floatingSites,
     others: scanned.labelSites,
     here,
   });
-  // `direct` without a job id says only that some job in the repo asks for the
-  // label, which is not this one. attributeImageOS scopes it the same way.
-  return (here && direct) || (asked && !rival) ? m : null;
+  // A pin to this runner's own label under the same job id is as good an
+  // explanation as the window, whether it is a matrix leg of the job this run
+  // came from or a job of that id in a file the run cannot be placed in.
+  return asked && !rival ? m : null;
 }
 
 /** One stderr line per floating label whose migration fails the gate. */
diff --git a/src/detect.mjs b/src/detect.mjs
index 96df9a7..fa4f89b 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -387,20 +387,27 @@ export function runningJob(env = process.env) {
 }
 
 /**
- * A predicate for "this site is one the running job was scheduled from", over
- * the sites a scan actually produced.
+ * Where the running job sits in a scan: what to match sites against, and
+ * whether that identity picks out one job.
  *
  * The file name is dropped from the comparison when no scanned site carries
  * this job id in the file the run reports: a job inside a reusable workflow
  * reports the calling file in `GITHUB_WORKFLOW_REF` while its id lives in the
  * callee, and a scan pointed at a copy of the directory need not match either.
- * The job id still has to agree.
+ * The job id still has to agree, but on its own it is only unique within a
+ * file, so `pinned` is false and the caller is looking at every job in the
+ * repository that shares the id.
  */
+export function jobScope(here, sites = []) {
+  if (!here) return { at: null, pinned: false, match: () => false };
+  const pinned = Boolean(here.file) && sites.some((site) => siteInJob(site, here));
+  const at = pinned ? here : { ...here, file: null };
+  return { at, pinned, match: (site) => siteInJob(site, at) };
+}
+
+/** A predicate for "this site is one the running job was scheduled from". */
 export function jobMatcher(here, sites = []) {
-  if (!here) return () => false;
-  const known = Boolean(here.file) && sites.some((site) => siteInJob(site, here));
-  const at = known ? here : { ...here, file: null };
-  return (site) => siteInJob(site, at);
+  return jobScope(here, sites).match;
 }
 
 /**
@@ -412,23 +419,27 @@ export function jobMatcher(here, sites = []) {
  *
  * `scoped` is whether a running job was identified at all; without one every
  * site in the repository is in scope and the caller has to decide how much that
- * is worth. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
+ * is worth. `placed` is the stronger claim that the job id picked out one job. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
  * the label through a matrix, and `rival` is another site naming `observed`,
  * which the runner is as likely to be serving as the floating one.
  *
  * Inside one job the only rival is a matrix leg, since a job has one `runs-on:`.
- * With no job to scope to, every `runs-on: <observed>` in the repo is one.
+ * That needs the job to be pinned to a file. A job id alone can name a job in
+ * every file that uses it, and then a plain `runs-on: <observed>` under the
+ * same id is as good an explanation as this label, exactly as it is when there
+ * is no job id at all.
  */
 export function labelOwnership({ label, observed = null, sites = [], others = [], here = null }) {
-  const belongs = jobMatcher(here, [...sites, ...others]);
-  const inScope = here ? belongs : () => true;
+  const { match, pinned } = jobScope(here, [...sites, ...others]);
+  const inScope = here ? match : () => true;
   const mine = sites.filter((site) => site.label === label && inScope(site));
   const rivals = others.filter((site) => site.label === observed && inScope(site));
   return {
     scoped: Boolean(here),
+    placed: pinned,
     direct: mine.some((site) => !site.viaMatrix),
     asked: mine.length > 0,
-    rival: observed !== null && (here ? rivals.some((site) => site.viaMatrix) : rivals.length > 0),
+    rival: observed !== null && (pinned ? rivals.some((site) => site.viaMatrix) : rivals.length > 0),
   };
 }
 
diff --git a/src/migration.mjs b/src/migration.mjs
index fcbc919..c0994aa 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -61,9 +61,12 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
   const observed = labelForImageOS(imageOS);
-  const { direct, asked, rival } = labelOwnership({ label, observed, sites, others, here });
+  const { direct, asked, rival, placed } = labelOwnership({ label, observed, sites, others, here });
 
-  if (here && direct) return { imageOS, note: null };
+  // A plain `runs-on:` in the job this run came from settles it, as long as the
+  // job id picked out one job. A job a reusable workflow reports is matched on
+  // the id alone, and an id is unique in a file, not in a repository.
+  if (here && direct && !rival) return { imageOS, note: null };
   const endpoint = !rival && (observed === m?.from || observed === m?.to);
 
   if (!here) {
@@ -79,6 +82,13 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
 
   if (asked) {
     if (endpoint) return { imageOS, note: null };
+    if (rival && !placed) {
+      return {
+        imageOS: null,
+        note: `More than one workflow has a job called "${here.job}", and one of them asks for `
+          + `${observed} by name, so this runner may be that job instead.`,
+      };
+    }
     return {
       imageOS: null,
       note: rival
diff --git a/test/fixtures/workflows-shared-build-id/ci.yml b/test/fixtures/workflows-shared-build-id/ci.yml
new file mode 100644
index 0000000..e4b3414
--- /dev/null
+++ b/test/fixtures/workflows-shared-build-id/ci.yml
@@ -0,0 +1,8 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: node --version
diff --git a/test/fixtures/workflows-shared-build-id/release.yml b/test/fixtures/workflows-shared-build-id/release.yml
new file mode 100644
index 0000000..bc8c41f
--- /dev/null
+++ b/test/fixtures/workflows-shared-build-id/release.yml
@@ -0,0 +1,9 @@
+name: release
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-26.04
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 6f7cac6..04e794d 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -575,6 +575,46 @@ test('a job id shared by two workflow files is told apart by the file', async ()
   assert.match(s.notes.join(' '), /did not run on ubuntu-latest/);
 });
 
+test('a run from a file the scan never saw cannot claim a shared job id', async () => {
+  // ci.yml and release.yml both have a job called build, and the run reports a
+  // caller the scan does not hold, so only the id is left to match on. One of
+  // the two is pinned to the image this runner is on.
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '0',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-shared-build-id'),
+    },
+    {
+      ImageOS: 'ubuntu26',
+      GITHUB_JOB: 'build',
+      GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/caller.yml@refs/heads/main',
+    },
+    DURING,
+  );
+  const j = jsonOf(r.stdout);
+  const s = j.migration.surveys.find((x) => x.label === 'ubuntu-latest');
+  assert.equal(s.observed, null, 'the runner may be the job pinned to ubuntu-26.04');
+  assert.notEqual(s.state, MIGRATION_STATE.MIGRATED);
+  assert.match(s.notes.join(' '), /More than one workflow has a job called "build"/);
+});
+
+test('the same shared job id withholds the drift explanation', async () => {
+  const r = await guardAcrossTheMove(
+    {
+      workflows: path.join(FIXTURES, 'workflows-shared-build-id'),
+      env: {
+        GITHUB_JOB: 'build',
+        GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/caller.yml@refs/heads/main',
+      },
+    },
+    DURING,
+  );
+  assert.equal(r.code, EXIT_OK);
+  assert.doesNotMatch(r.stdout, /Explained by the scheduled/);
+});
+
 test('a guard step on an unrelated image says nothing about the floating label', async () => {
   const r = await guard(
     { tools: 'node', 'fail-on-migration': '0', json: true },
@@ -670,6 +710,24 @@ test('the job id alone decides when the run came from a file the scan never saw'
   assert.equal(strict({ ...sites[0], file: 'other.yml' }), false, 'a scanned file still has to match');
 });
 
+test('a job id the run cannot be placed by does not speak for another file', () => {
+  // The run came from a reusable workflow, so GITHUB_WORKFLOW_REF names a file
+  // the scan does not hold and only the job id is left to match on. Two files
+  // use that id, and one of them is pinned to the image this runner is on.
+  const sites = [{ label: 'ubuntu-latest', file: 'ci.yml', line: 6, col: 14, job: 'build' }];
+  const others = [{ label: 'ubuntu-26.04', file: 'release.yml', line: 6, col: 14, job: 'build' }];
+  const here = { job: 'build', file: 'caller.yml' };
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu26', sites, others, here });
+  assert.equal(a.imageOS, null, 'release.yml pins a build job to the image this runner is on');
+  assert.match(a.note, /More than one workflow has a job called "build"/);
+  assert.notEqual(
+    migrationStatus('ubuntu-latest', { now: DURING, imageOS: a.imageOS }).state,
+    MIGRATION_STATE.MIGRATED,
+  );
+  const alone = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu26', sites, others: [], here });
+  assert.equal(alone.imageOS, 'ubuntu26', 'one file uses the id, so the callee is found');
+});
+
 test('a matrix leg is trusted for the two images in the window and no others', () => {
   const site = { label: 'ubuntu-latest', file: 'ci.yml', line: 5, col: 28, job: 'a', viaMatrix: true };
   const here = { job: 'a', file: 'ci.yml' };

From 805aebbf08d229ef8267ab95badd904eaba82338 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 17:14:59 +0800
Subject: [PATCH 28/44] A rate limit is not a reason to report every tool as
 removed

attribute() and the readme fallback shared one try block, so a 403 on the
commit lookup skipped the manifest read as well. Every manifest-only tool then
had no observed version, the diff called each one REMOVED, and --fail-on major
turned a rate limit into a red build. The fallback is its own read now.

Also corrects the README's drift-explanation example, which still showed a
same-label header and a commit link. A run whose label moved prints both
labels and attributes nothing, as of the previous commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md        |  8 ++++++++
 README.md           | 11 +++++++++--
 src/cli.mjs         | 15 ++++++++++++---
 test/guard.test.mjs | 28 ++++++++++++++++++++++++++++
 4 files changed, 57 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 147fd2f..1930b23 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -187,6 +187,14 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   which reads as every locked tool having been removed. Only a read that worked
   is kept.
 
+- A refused or rate-limited attribution lookup took the manifest read down with
+  it. Pinning the manifest to the commit that shipped this exact image version
+  is an improvement on the label's current readme, not a prerequisite, but both
+  sat in one `try`, so a 403 left every manifest-only tool unobserved and the
+  diff reported each of them as REMOVED, which is MAJOR. `--fail-on major` red
+  the build over a rate limit. The readme fallback now runs whatever the API
+  did.
+
 - A job id the run could not be placed by let one workflow file speak for
   another. Inside a reusable workflow `GITHUB_WORKFLOW_REF` names the caller,
   so the job is matched on its id alone, and an id is unique in a file rather
diff --git a/README.md b/README.md
index dc0520b..faeaa6e 100644
--- a/README.md
+++ b/README.md
@@ -315,11 +315,18 @@ table lookup rather than a check you have to opt into. Bump a pinned label from
 the explanation, which is the honest answer: that upgrade was yours.
 
 ```
-ubuntu-26.04 image 20260907.300.1 -> 20260907.131.1
+ubuntu-24.04 image 20260907.300.1 -> ubuntu-26.04 image 20260907.131.1
 Explained by the scheduled ubuntu-latest migration ubuntu-24.04 -> ubuntu-26.04 (2026-10-19 to 2026-11-19); the tool versions below moved with the image.
-  CMake 3.31.6 -> 4.4.3  MAJOR  [20260907.131.1] https://github.com/actions/runner-images/commit/90ebb6f508835349239c3823c663eba7af98f23d
+  CMake 3.31.6 -> 4.4.3  MAJOR
 ```
 
+Both labels are named because both images are real, and the version in the lock
+was never a version of the one you are on now. There is no commit link beside
+the tool for the same reason: no commit to `ubuntu-26.04` shipped a difference
+against `ubuntu-24.04`, so a run whose label moved attributes nothing rather
+than picking the nearest commit and calling it the cause. A bump within one
+label still gets the commit that shipped it.
+
 The step summary carries the same line, above the drift table.
 
 Exit codes and the `--fail-on` thresholds are untouched by any of this.
diff --git a/src/cli.mjs b/src/cli.mjs
index ebbaedd..3bb4b9f 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -761,18 +761,27 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   const infraWarnings = [];
 
   if (needManifest.length) {
+    // Pinning the manifest to the commit that shipped this image version is an
+    // improvement on the label's current readme, not a prerequisite for it. A
+    // rate limit here used to abort the fallback too, and a tool that went
+    // unobserved is reported as REMOVED, which --fail-on major reds the build
+    // over.
     try {
       attribution0 = await attribute(label, imageVersion);
       if (attribution0?.commit) {
         approximate = attribution0.approximate;
         manifest = await manifestAtSha(label, attribution0.commit.sha);
       }
-      if (!manifest) {
+    } catch (err) {
+      infraWarnings.push(errorText(err));
+    }
+    if (!manifest) {
+      try {
         const m = await load(label);
         manifest = m.skipped ? null : m;
+      } catch (err) {
+        infraWarnings.push(errorText(err));
       }
-    } catch (err) {
-      infraWarnings.push(errorText(err));
     }
     if (manifest) {
       const { map, missing } = resolveManifestVersions(manifest, needManifest);
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 9a0de84..d6e41b5 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -181,6 +181,34 @@ test('a lock from the other side of a migration is not attributed to this image
   }
 });
 
+test('a rate-limited attribution lookup does not cost the manifest read', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  // Every API call refused, so pinning the manifest to the commit that shipped
+  // this image cannot happen. The label's own readme is still readable.
+  const api = stubApi(() => ({ status: 403, body: '', headers: { 'x-ratelimit-remaining': '0' } }));
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-22.04',
+        imageOS: 'ubuntu22',
+        imageVersion: '20260623.199.1',
+        tools: { Bazel: { versions: ['9.1.0'], source: 'manifest' } },
+      },
+      lockFile,
+    );
+    const r = await guard({ tools: 'Bazel', 'lock-file': lockFile, 'update-lock': false }, ENV, {
+      loadManifest: fixtureLoader(),
+    });
+    assert.equal(r.code, EXIT_OK);
+    assert.match(r.stdout, /Bazel 9\.1\.0 -> 9\.2\.0/, 'read off the readme, not reported as removed');
+    assert.doesNotMatch(r.stdout, /REMOVED/);
+  } finally {
+    api.restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('exit code 1 only under --fail-on major (and above)', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');

From 9ad005be32463f3f9f92746fc3a6e558aedaff81 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 17:36:25 +0800
Subject: [PATCH 29/44] Place a runs-on: an expression resolves outside the
 jobs map, and count one day as one

A workflow_call input default or a top-level env value sits above the jobs
map, so the site carried no job id and a scoped run threw away a migrated
runner's ImageOS. Attribute such a label to every job whose runs-on: is an
expression.

Wire plural() through the retirement and self-hosted lanes, which still said
"1 days" in the annotation titles, the summary table and the failure line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  9 +++++++
 src/cli.mjs                                   | 13 ++++-----
 src/detect.mjs                                | 25 ++++++++++++-----
 src/report.mjs                                | 12 ++++-----
 test/detect.test.mjs                          | 27 +++++++++++++++++--
 .../workflows-input-default/build.yml         | 13 +++++++++
 test/migration.test.mjs                       | 24 +++++++++++++++++
 test/retirement.test.mjs                      | 27 +++++++++++++++++--
 8 files changed, 128 insertions(+), 22 deletions(-)
 create mode 100644 test/fixtures/workflows-input-default/build.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1930b23..f5a52ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,15 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A `runs-on:` taken from an expression resolved outside the jobs map lost its
+  job. A `workflow_call` input default and a top-level `env:` value both sit
+  above `jobs:`, so the line the label was read from carried no job id, and with
+  `GITHUB_JOB` set the runner's image was discarded with the note that the job
+  had not run on the floating label. On a reusable build workflow that had
+  already migrated, `--fail-on-migration` reddened the build for the whole
+  rollout month, and only when run inside a job, which read as flakiness. Such a
+  label now belongs to every job whose `runs-on:` is an expression.
+
 - Mid-migration, the drift lane attributed the change to the wrong image's
   history. A lock recorded on `ubuntu-24.04` and a runner on `ubuntu-26.04` are
   two operating systems, but guard looked the locked image version up in the
diff --git a/src/cli.mjs b/src/cli.mjs
index 3bb4b9f..571ec5b 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -37,6 +37,7 @@ import {
   stepSummaryMarkdown,
   annotations,
   notice,
+  plural,
   retirementFindings,
   retirementAnnotations,
   retirementSummaryMarkdown,
@@ -338,8 +339,8 @@ function reportRetirement(io, { days, findings }) {
     (f) => f.status.label,
     ({ status: s }) =>
       s.retired
-        ? `runner-drift: ${s.label} has been fully unsupported since ${s.fullyUnsupported} (retired ${Math.abs(s.daysToUnsupported)} days ago) and --fail-on-retirement ${days} is set.`
-        : `runner-drift: ${s.label} is fully unsupported on ${s.fullyUnsupported} (${s.daysToUnsupported} days) and --fail-on-retirement ${days} is set.`,
+        ? `runner-drift: ${s.label} has been fully unsupported since ${s.fullyUnsupported} (retired ${plural(Math.abs(s.daysToUnsupported), 'day')} ago) and --fail-on-retirement ${days} is set.`
+        : `runner-drift: ${s.label} is fully unsupported on ${s.fullyUnsupported} (${plural(s.daysToUnsupported, 'day')}) and --fail-on-retirement ${days} is set.`,
   );
 }
 
@@ -448,12 +449,12 @@ function reportDeprecation(io, survey) {
         : '';
       if (g.runtime) {
         return g.runtime.past
-          ? `runner-drift: ${fleet} lost runtime support on ${g.runtime.date} (${Math.abs(g.runtime.days)} days ago) — jobs are no longer queued to them.`
-          : `runner-drift: ${fleet} lose runtime support on ${g.runtime.date} (${g.runtime.days} days)${because}.`;
+          ? `runner-drift: ${fleet} lost runtime support on ${g.runtime.date} (${plural(Math.abs(g.runtime.days), 'day')} ago) — jobs are no longer queued to them.`
+          : `runner-drift: ${fleet} lose runtime support on ${g.runtime.date} (${plural(g.runtime.days, 'day')})${because}.`;
       }
       return g.registration.past
-        ? `runner-drift: ${fleet} lost registration on ${g.registration.date} (${Math.abs(g.registration.days)} days ago) — they cannot reregister.`
-        : `runner-drift: ${fleet} lose registration on ${g.registration.date} (${g.registration.days} days)${because}.`;
+        ? `runner-drift: ${fleet} lost registration on ${g.registration.date} (${plural(Math.abs(g.registration.days), 'day')} ago) — they cannot reregister.`
+        : `runner-drift: ${fleet} lose registration on ${g.registration.date} (${plural(g.registration.days, 'day')})${because}.`;
     },
   );
 }
diff --git a/src/detect.mjs b/src/detect.mjs
index fa4f89b..f1abd91 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -346,17 +346,30 @@ function jobKeys(lines) {
  * is not written anywhere in the file.
  */
 function labelSitesWhere(walk, file, keep) {
-  const { found, expression, matrix, jobs } = walk;
+  const { found, expression, matrix, targets, jobs } = walk;
+  const jobOf = (line) => jobs[line - 1] ?? null;
+
+  // A label an expression resolves to need not sit in the jobs map at all: a
+  // `workflow_call` input default and a top-level `env:` value both live above
+  // it. The jobs it can serve are the ones whose `runs-on:` is an expression.
+  const viaExpression = expression
+    ? [...new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))]
+    : [];
+
   const seen = new Set();
   const sites = [];
   const all = expression ? [...found, ...matrix.map((m) => ({ ...m, viaMatrix: true }))] : found;
   for (const { label, line, col, viaMatrix } of all) {
     if (!keep(label)) continue;
-    const key = `${label}@${line}:${col}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    const site = { label, file, line, col, job: jobs[line - 1] ?? null };
-    sites.push(viaMatrix ? { ...site, viaMatrix } : site);
+    const own = jobOf(line);
+    const owners = viaMatrix && own === null && viaExpression.length ? viaExpression : [own];
+    for (const job of owners) {
+      const key = `${label}@${line}:${col}@${job}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const site = { label, file, line, col, job };
+      sites.push(viaMatrix ? { ...site, viaMatrix } : site);
+    }
   }
   return sites;
 }
diff --git a/src/report.mjs b/src/report.mjs
index ab53015..854e9d7 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -31,7 +31,7 @@ import {
 
 export { daysUntil };
 
-const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+export const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 
 /** `(82 days)` / `(60 days ago)` — the countdown suffix both lanes print. */
 export function countdown(days) {
@@ -317,7 +317,7 @@ export function retirementFindings(labelSites, { now = new Date(), days } = {})
 function retirementMessage(s) {
   const migrate = `Migrate to ${s.migrateTo.join(', ')}.`;
   if (s.retired) {
-    return `${s.label} retired ${Math.abs(s.daysToUnsupported)} days ago — fully unsupported since ${s.fullyUnsupported}. ${migrate} See ${s.source}`;
+    return `${s.label} retired ${plural(Math.abs(s.daysToUnsupported), 'day')} ago — fully unsupported since ${s.fullyUnsupported}. ${migrate} See ${s.source}`;
   }
   const brownout = s.nextBrownout
     ? `; next brownout ${dateWithCountdown(s.nextBrownout, s.daysToBrownout)}`
@@ -333,9 +333,9 @@ export function retirementAnnotations(findings) {
   return findings.map((f) => {
     const s = f.status;
     let kind = 'error';
-    let title = `runner-drift: ${s.label} retires in ${s.daysToUnsupported} days`;
+    let title = `runner-drift: ${s.label} retires in ${plural(s.daysToUnsupported, 'day')}`;
     if (s.retired) {
-      title = `runner-drift: ${s.label} retired ${Math.abs(s.daysToUnsupported)} days ago`;
+      title = `runner-drift: ${s.label} retired ${plural(Math.abs(s.daysToUnsupported), 'day')} ago`;
     } else if (f.trigger === 'brownout') {
       kind = 'warning';
       title = `runner-drift: ${s.label} deprecation`;
@@ -353,7 +353,7 @@ export function retirementSummaryMarkdown(findings) {
       `\`${annotationPath(f.file)}:${f.line}\``,
       s.nextBrownout ? dateWithCountdown(s.nextBrownout, s.daysToBrownout) : '—',
       s.retired
-        ? `${s.fullyUnsupported} (retired ${Math.abs(s.daysToUnsupported)} days ago)`
+        ? `${s.fullyUnsupported} (retired ${plural(Math.abs(s.daysToUnsupported), 'day')} ago)`
         : dateWithCountdown(s.fullyUnsupported, s.daysToUnsupported),
       s.migrateTo.map((m) => `\`${m}\``).join(', '),
       `[${s.sourceRef}](${s.source})`,
@@ -788,7 +788,7 @@ export function runnersSummaryMarkdown(survey) {
     return `${lines.join('\n')}\n`;
   }
   lines.push(
-    `\`${survey.scope.name}\` — ${plural(survey.surveyedCount, 'runner')} on ${plural(survey.groups.length, 'version')}, window ${survey.windowDays} days.`,
+    `\`${survey.scope.name}\` — ${plural(survey.surveyedCount, 'runner')} on ${plural(survey.groups.length, 'version')}, window ${plural(survey.windowDays, 'day')}.`,
   );
   for (const c of caveats) lines.push('', c);
   lines.push('');
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 6ecec55..544638a 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -216,8 +216,31 @@ test('an expression runs-on resolves a workflow_call input default', () => {
   ].join('\n');
   assert.deepEqual(extractLabels(y), ['ubuntu-22.04']);
   assert.deepEqual(
-    extractLabelSites(y).map((s) => [s.label, s.line]),
-    [['ubuntu-22.04', 5]],
+    extractLabelSites(y).map((s) => [s.label, s.line, s.job]),
+    [['ubuntu-22.04', 5, 'a']],
+    'the default sits above the jobs map, but it is job a that runs on it',
+  );
+});
+
+test('a label an expression reaches from top-level env still belongs to the jobs', () => {
+  const y = [
+    'env:',
+    '  RUNNER: ubuntu-latest',
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ env.RUNNER }}',
+    '  b:',
+    '    runs-on: ubuntu-22.04',
+    '  c:',
+    '    runs-on: ${{ env.RUNNER }}',
+  ].join('\n');
+  assert.deepEqual(
+    extractFloatingSites(y).map((s) => [s.label, s.line, s.job]),
+    [
+      ['ubuntu-latest', 2, 'a'],
+      ['ubuntu-latest', 2, 'c'],
+    ],
+    'both expression jobs can be the one this label serves; the pinned job cannot',
   );
 });
 
diff --git a/test/fixtures/workflows-input-default/build.yml b/test/fixtures/workflows-input-default/build.yml
new file mode 100644
index 0000000..10e2279
--- /dev/null
+++ b/test/fixtures/workflows-input-default/build.yml
@@ -0,0 +1,13 @@
+name: build
+on:
+  workflow_call:
+    inputs:
+      runner:
+        default: ubuntu-latest
+        type: string
+
+jobs:
+  build:
+    runs-on: ${{ inputs.runner }}
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 04e794d..7ae76e6 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -600,6 +600,30 @@ test('a run from a file the scan never saw cannot claim a shared job id', async
   assert.match(s.notes.join(' '), /More than one workflow has a job called "build"/);
 });
 
+test('a runs-on taken from an input default still belongs to its job', async () => {
+  // The label resolves above the jobs map, so the site's own line carries no job
+  // id. The job whose runs-on is that expression is the one it serves.
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '30',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-input-default'),
+    },
+    {
+      ImageOS: 'ubuntu26',
+      GITHUB_JOB: 'build',
+      GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/build.yml@refs/heads/main',
+    },
+    DURING,
+  );
+  const s = jsonOf(r.stdout).migration.surveys[0];
+  assert.equal(s.observed, 'ubuntu-26.04');
+  assert.equal(s.state, MIGRATION_STATE.MIGRATED);
+  assert.deepEqual(s.notes, [], 'the job did run on ubuntu-latest');
+  assert.equal(r.code, EXIT_OK, 'a migrated runner does not red the build');
+});
+
 test('the same shared job id withholds the drift explanation', async () => {
   const r = await guardAcrossTheMove(
     {
diff --git a/test/retirement.test.mjs b/test/retirement.test.mjs
index 5ed6193..63b195a 100644
--- a/test/retirement.test.mjs
+++ b/test/retirement.test.mjs
@@ -192,6 +192,19 @@ test('a retired label reads "retired N days ago"', () => {
   assert.match(line, /retired 60 days ago — fully unsupported since 2026-11-02/);
 });
 
+test('the last day before retirement reads "1 day", not "1 days"', () => {
+  const eve = retirementFindings(SITES, { now: new Date('2026-11-01T00:00:00Z'), days: 5 });
+  const [soon] = retirementAnnotations(eve);
+  assert.match(soon, /title=runner-drift: macos-14 retires in 1 day::/);
+  assert.match(retirementSummaryMarkdown(eve), /2026-11-02 \(1 day\)/);
+
+  const morning = retirementFindings(SITES, { now: new Date('2026-11-03T00:00:00Z'), days: 0 });
+  const [gone] = retirementAnnotations(morning);
+  assert.match(gone, /title=runner-drift: macos-14 retired 1 day ago::/);
+  assert.match(gone, /retired 1 day ago . fully unsupported since 2026-11-02/);
+  assert.match(retirementSummaryMarkdown(morning), /2026-11-02 \(retired 1 day ago\)/);
+});
+
 /* ------------------------------------------------ retirementSummaryMarkdown */
 
 test('summary markdown has the six columns, one row per site', () => {
@@ -205,13 +218,13 @@ test('summary markdown has the six columns, one row per site', () => {
 
 /* ---------------------------------------------------------------- runGuard */
 
-async function guard(opts, env = {}) {
+async function guard(opts, env = {}, now = NOW) {
   const cap = captureIO();
   const code = await runGuard(
     { summary: true, 'update-lock': true, ...opts },
     cap.io,
     env,
-    { now: NOW },
+    { now },
   );
   return { code, stdout: cap.stdout, stderr: cap.stderr };
 }
@@ -227,6 +240,16 @@ test('guard --fail-on-retirement=60 fails a plain lint job on the macos-14 site'
   assert.match(r.stderr, /runner-drift: macos-14 is fully unsupported on 2026-11-02 \(82 days\) and --fail-on-retirement 60 is set\./);
 });
 
+test('the failure line counts a single day in the singular too', async () => {
+  const r = await guard(
+    { workflows: WORKFLOWS, 'fail-on-retirement': '5' },
+    {},
+    new Date('2026-11-01T00:00:00Z'),
+  );
+  assert.equal(r.code, EXIT_DRIFT);
+  assert.match(r.stderr, /macos-14 is fully unsupported on 2026-11-02 \(1 day\) and --fail-on-retirement 5 is set\./);
+});
+
 test('guard --fail-on-retirement=10 exits 0 with no annotations', async () => {
   const r = await guard({ workflows: WORKFLOWS, 'fail-on-retirement': '10' });
   assert.equal(r.code, EXIT_OK);

From 9a18dcd88e2c86914325851cf9ec158ff884eb6e Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 17:50:56 +0800
Subject: [PATCH 30/44] Read a map under an empty prose key, and badge the
 migration outcome not the phase

The prose-key skip added in 1.4.0 swallowed a workflow_call input named
"name", losing its default and every label the file asked for. An empty prose
key now only owns a body that is not itself a map.

The step-summary badge was keyed by phase, so a stale runner read as settled
next to its own ::error. Key it by state and head the column Status.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 13 +++++++++++++
 README.md               |  2 +-
 src/detect.mjs          | 22 ++++++++++++++++++++--
 src/report.mjs          | 19 +++++++++++++------
 test/detect.test.mjs    | 20 ++++++++++++++++++++
 test/helpers.mjs        |  2 +-
 test/migration.test.mjs | 14 ++++++++++++--
 7 files changed, 80 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5a52ee..e718686 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,19 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A label written under a key named `name`, `run` or `if` was dropped even when
+  that key held a map rather than prose. 1.4.0 taught the matrix fallback to skip
+  the keys that hold shell and titles, and an empty one swallowed everything
+  indented under it, so a `workflow_call` input called `name` took its `default:`
+  with it and both `--fail-on-retirement` and `--fail-on-migration` went silent
+  for that file. An empty prose key now only owns a body that is not itself a
+  map.
+
+- The migration step-summary table badged the phase, not the outcome, so a runner
+  still serving the old image after the window closed showed `✅ settled` in the
+  row beside its own `::error`. The column is headed Status now and names the
+  state: moved early, not yet, in window, migrated, settled, stale, unexpected.
+
 - A `runs-on:` taken from an expression resolved outside the jobs map lost its
   job. A `workflow_call` input default and a top-level `env:` value both sit
   above `jobs:`, so the line the label was read from carried no job id, and with
diff --git a/README.md b/README.md
index faeaa6e..54b2cf2 100644
--- a/README.md
+++ b/README.md
@@ -331,7 +331,7 @@ The step summary carries the same line, above the drift table.
 
 Exit codes and the `--fail-on` thresholds are untouched by any of this.
 `--json` gains a `migration` block, and the
-step summary gains a table (Label, Phase, Move, Window, This runner, Source).
+step summary gains a table (Label, Status, Move, Window, This runner, Source).
 The explanation above has its own `explains` key next to `diffs`, which is there
 with or without the flag, and is `null` when nothing announced explains the jump.
 Adding `windows-latest` or `macos-latest` later is a data change in `MIGRATIONS`,
diff --git a/src/detect.mjs b/src/detect.mjs
index f1abd91..8036062 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -223,6 +223,21 @@ function scanRunsOn(lines) {
  */
 const PROSE_KEYS = new Set(['run', 'name', 'if']);
 
+/**
+ * Whether the lines under an empty prose key are its body rather than a map.
+ * `inputs.name.default` is a value a `runs-on:` expression can resolve to; the
+ * indented text under a step's `name:` is the title continued.
+ */
+function foldsOver(lines, i, indent) {
+  for (let j = i + 1; j < lines.length; j++) {
+    const text = stripComment(lines[j]);
+    if (!text.trim()) continue;
+    if (indentOf(text) <= indent) return false;
+    return !/^[ \t]*(-[ \t]+)?[^:\s][^:\r\n]*:([ \t]|$)/.test(text);
+  }
+  return false;
+}
+
 function matrixLabels(lines) {
   const found = [];
   let scalar = null;
@@ -242,8 +257,11 @@ function matrixLabels(lines) {
       // written with a block marker, since a plain scalar folds over them too.
       // A dashed key owns the column the dash sits in, so the step's own
       // siblings (`env:`, `with:`) are not read as part of the script.
-      if (/^[|>]/.test(key[4].trim()) || PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase())) {
-        scalar = key[1].length + (key[2]?.length ?? 0);
+      const value = key[4].trim();
+      const owns = key[1].length + (key[2]?.length ?? 0);
+      const prose = PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase());
+      if (/^[|>]/.test(value) || (prose && (value || foldsOver(lines, i, owns)))) {
+        scalar = owns;
         continue;
       }
     }
diff --git a/src/report.mjs b/src/report.mjs
index 854e9d7..ab9c863 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -13,7 +13,6 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { daysUntil } from './dates.mjs';
 import {
-  MIGRATION_PHASE,
   MIGRATION_STATE,
   deadlineFor,
   retirementStatus,
@@ -418,10 +417,18 @@ const MIGRATION_TITLE = {
   [MIGRATION_STATE.UNEXPECTED]: (s) => `unrecognised image on ${s.label}`,
 };
 
+// Keyed by state, not by phase: after the window a runner still on the old
+// image is the anomaly this lane exists to catch, and the calendar alone would
+// badge it settled next to its own ::error.
 const MIGRATION_BADGE = {
-  [MIGRATION_PHASE.PENDING]: '🗓 pending',
-  [MIGRATION_PHASE.IN_WINDOW]: '🟠 in window',
-  [MIGRATION_PHASE.SETTLED]: '✅ settled',
+  [MIGRATION_STATE.PENDING]: '🗓 pending',
+  [MIGRATION_STATE.MOVED_EARLY]: '🟠 moved early',
+  [MIGRATION_STATE.NOT_YET_MIGRATED]: '🟠 not yet',
+  [MIGRATION_STATE.AMBIGUOUS]: '🟠 in window',
+  [MIGRATION_STATE.MIGRATED]: '✅ migrated',
+  [MIGRATION_STATE.SETTLED]: '✅ settled',
+  [MIGRATION_STATE.STALE]: '🔴 stale',
+  [MIGRATION_STATE.UNEXPECTED]: '🔴 unexpected',
 };
 
 /** The one sentence that describes a survey. No source link; callers add it. */
@@ -480,7 +487,7 @@ export function migrationAnnotations(surveys) {
 export function migrationSummaryMarkdown(surveys) {
   const rows = surveys.map((s) => [
     `\`${s.label}\``,
-    MIGRATION_BADGE[s.phase],
+    MIGRATION_BADGE[s.state],
     `\`${s.from}\` → \`${s.to}\``,
     `${dateWithCountdown(s.starts, s.daysToStart)} → ${dateWithCountdown(s.ends, s.daysToEnd)}`,
     s.observed ? `\`${s.observed}\`` : '—',
@@ -489,7 +496,7 @@ export function migrationSummaryMarkdown(surveys) {
   const lines = [
     '## runner-drift — floating label migration',
     '',
-    ...markdownTable(['Label', 'Phase', 'Move', 'Window', 'This runner', 'Source'], rows),
+    ...markdownTable(['Label', 'Status', 'Move', 'Window', 'This runner', 'Source'], rows),
   ];
   for (const s of surveys) {
     lines.push('', migrationMessage(s));
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 544638a..56078a0 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -378,6 +378,26 @@ test('a label written in a step name or a condition is not a runner', () => {
   assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
 });
 
+test('an empty prose key that holds a map is read, not skipped', () => {
+  // `name:` is a prose key, but `inputs.name` is an input whose default a
+  // `runs-on:` expression resolves to.
+  const y = [
+    'on:',
+    '  workflow_call:',
+    '    inputs:',
+    '      name:',
+    '        default: ubuntu-22.04',
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ inputs.name }}',
+  ].join('\n');
+  assert.deepEqual(extractLabels(y), ['ubuntu-22.04']);
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.line, s.job]),
+    [['ubuntu-22.04', 5, 'a']],
+  );
+});
+
 test('a key under the block that follows the jobs map is not a job id', () => {
   // `x-` template blocks are a real shape, and the id can collide with a job's.
   const y = [
diff --git a/test/helpers.mjs b/test/helpers.mjs
index 9ea361f..bb01eb3 100644
--- a/test/helpers.mjs
+++ b/test/helpers.mjs
@@ -102,7 +102,6 @@ export function runnerRoutes({ scopePath, fleet, recorded, releases, listing = n
   };
 }
 
-/** Capture stdout/stderr from a command function. */
 /**
  * The `--json` document a run printed, past the annotation lines above it.
  * Found by the line the document opens on: an annotation can contain a brace of
@@ -115,6 +114,7 @@ ${stdout}`);
   return JSON.parse(stdout.slice(at));
 }
 
+/** Capture stdout/stderr from a command function. */
 export function captureIO() {
   const outChunks = [];
   const errChunks = [];
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 7ae76e6..0dafafb 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -344,10 +344,10 @@ test('a survey with no site on disk still gets one step-level annotation', async
   assert.match(line, /^::notice title=runner-drift: /);
 });
 
-test('the step summary names the window, the phase and the image diff', async () => {
+test('the step summary names the window, the status and the image diff', async () => {
   const md = migrationSummaryMarkdown([await survey(BEFORE)]);
   assert.match(md, /^## runner-drift — floating label migration/);
-  assert.match(md, /\| Label \| Phase \| Move \| Window \| This runner \| Source \|/);
+  assert.match(md, /\| Label \| Status \| Move \| Window \| This runner \| Source \|/);
   assert.match(
     md,
     /\| `ubuntu-latest` \| 🗓 pending \| `ubuntu-24\.04` → `ubuntu-26\.04` \| 2026-10-19 \(18 days\) → 2026-11-19 \(49 days\) \| — \| \[actions\/runner-images#14748\]/,
@@ -355,6 +355,16 @@ test('the step summary names the window, the phase and the image diff', async ()
   assert.match(md, /\| Kernel \| 6\.17\.0-1022-azure \| 7\.0\.0-1012-azure \| 🔴 MAJOR \|/);
 });
 
+test('a runner left on the old image is badged stale, not settled', async () => {
+  // The row sits beside this survey's own ::error, so the calendar-only badge
+  // read as a clean bill of health.
+  const s = await survey(AFTER, 'ubuntu24');
+  assert.equal(s.state, MIGRATION_STATE.STALE);
+  const md = migrationSummaryMarkdown([s]);
+  assert.match(md, /\| `ubuntu-latest` \| 🔴 stale \|/);
+  assert.doesNotMatch(md, /settled/);
+});
+
 test('a floating label inside a matrix is a site like any other', () => {
   const y = [
     'jobs:',

From 278e1351cbdbb3546ba8bc2e3a5c9510f14ca758 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 18:04:40 +0800
Subject: [PATCH 31/44] Do not call a job's own matrix leg a second workflow
 with the same job id

placed is false for any run the scan cannot pin to a file, which includes a
run with no GITHUB_WORKFLOW_REF and any run inside a reusable workflow, so a
single matrix job was explained as a namesake in another file. Require the
rival to be a plain runs-on: before naming it one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  7 +++++++
 src/detect.mjs          | 10 +++++++---
 src/migration.mjs       |  7 +++++--
 test/migration.test.mjs | 20 ++++++++++++++++++++
 4 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e718686..f9a05ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -227,6 +227,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   rollout month, and only when run inside a job, which read as flakiness. Such a
   label now belongs to every job whose `runs-on:` is an expression.
 
+- A job that reaches the floating label through its own matrix was explained as
+  two workflows sharing a job id whenever the run could not be placed in a file,
+  which is every run with no `GITHUB_WORKFLOW_REF` and every run inside a
+  reusable workflow. Withholding the image was right, the sentence was not: a
+  namesake job now has to ask for the observed label with a plain `runs-on:`
+  before it is named as one.
+
 - Mid-migration, the drift lane attributed the change to the wrong image's
   history. A lock recorded on `ubuntu-24.04` and a runner on `ubuntu-26.04` are
   two operating systems, but guard looked the locked image version up in the
diff --git a/src/detect.mjs b/src/detect.mjs
index 8036062..1966eb7 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -450,9 +450,12 @@ export function jobMatcher(here, sites = []) {
  *
  * `scoped` is whether a running job was identified at all; without one every
  * site in the repository is in scope and the caller has to decide how much that
- * is worth. `placed` is the stronger claim that the job id picked out one job. `direct` is a plain `runs-on: <label>`, `asked` includes reaching
- * the label through a matrix, and `rival` is another site naming `observed`,
- * which the runner is as likely to be serving as the floating one.
+ * is worth. `placed` is the stronger claim that the job id picked out one job.
+ * `direct` is a plain `runs-on: <label>`, `asked` includes reaching the label
+ * through a matrix, and `rival` is another site naming `observed`, which the
+ * runner is as likely to be serving as the floating one. `named` says that
+ * rival is a plain `runs-on:` rather than a matrix leg, which is the difference
+ * between two jobs sharing an id and one job with two legs.
  *
  * Inside one job the only rival is a matrix leg, since a job has one `runs-on:`.
  * That needs the job to be pinned to a file. A job id alone can name a job in
@@ -471,6 +474,7 @@ export function labelOwnership({ label, observed = null, sites = [], others = []
     direct: mine.some((site) => !site.viaMatrix),
     asked: mine.length > 0,
     rival: observed !== null && (pinned ? rivals.some((site) => site.viaMatrix) : rivals.length > 0),
+    named: observed !== null && rivals.some((site) => !site.viaMatrix),
   };
 }
 
diff --git a/src/migration.mjs b/src/migration.mjs
index c0994aa..f775998 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -61,7 +61,7 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
   const observed = labelForImageOS(imageOS);
-  const { direct, asked, rival, placed } = labelOwnership({ label, observed, sites, others, here });
+  const { direct, asked, rival, placed, named } = labelOwnership({ label, observed, sites, others, here });
 
   // A plain `runs-on:` in the job this run came from settles it, as long as the
   // job id picked out one job. A job a reusable workflow reports is matched on
@@ -82,7 +82,10 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
 
   if (asked) {
     if (endpoint) return { imageOS, note: null };
-    if (rival && !placed) {
+    // Two jobs sharing an id, rather than one job with two legs: only a plain
+    // `runs-on:` rules out a matrix, and only an unplaceable run can be in
+    // another file at all.
+    if (rival && named && !placed) {
       return {
         imageOS: null,
         note: `More than one workflow has a job called "${here.job}", and one of them asks for `
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index 0dafafb..cdc036b 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -744,6 +744,26 @@ test('the job id alone decides when the run came from a file the scan never saw'
   assert.equal(strict({ ...sites[0], file: 'other.yml' }), false, 'a scanned file still has to match');
 });
 
+test('one matrix job is not reported as two workflows sharing a job id', () => {
+  // The same withholding, but the repository has one file and one job in it:
+  // the rival is the other leg of this job's own matrix, not a namesake.
+  const y = [
+    'jobs:',
+    '  build:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-latest, ubuntu-24.04]',
+    '    runs-on: ${{ matrix.os }}',
+  ].join(String.fromCharCode(10));
+  const sites = extractFloatingSites(y, 'reusable.yml');
+  const others = extractLabelSites(y, 'reusable.yml');
+  const here = { job: 'build', file: 'caller.yml' };
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu24', sites, others, here });
+  assert.equal(a.imageOS, null, 'the runner may be the 24.04 leg');
+  assert.doesNotMatch(a.note, /More than one workflow/);
+  assert.match(a.note, /reaches ubuntu-latest through a matrix/);
+});
+
 test('a job id the run cannot be placed by does not speak for another file', () => {
   // The run came from a reusable workflow, so GITHUB_WORKFLOW_REF names a file
   // the scan does not hold and only the job id is left to match on. Two files

From 1edcb5fb4e6d0d346c07c139612381bca19147c1 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 18:18:43 +0800
Subject: [PATCH 32/44] One site per label line, read matrix axes named like
 prose keys, and keep --as-of in UTC

The expression fan-out emitted a site per job, so three jobs sharing an input
default meant three identical annotations on one line. Carry the ids on the
site as jobs instead.

A matrix axis called name, run or if was skipped as prose, losing every label
under it. The prose keys only hold prose outside a matrix.

--as-of fell through to Date.parse for anything non-ISO and read it in local
time, the off-by-a-day it exists to prevent. Refuse it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md         | 10 +++++++
 README.md            |  2 +-
 src/cli.mjs          | 23 +++++++++-------
 src/detect.mjs       | 36 ++++++++++++++++---------
 test/cli.test.mjs    |  4 ++-
 test/detect.test.mjs | 63 +++++++++++++++++++++++++++++++++++++-------
 6 files changed, 104 insertions(+), 34 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9a05ca..dbae635 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A matrix axis called `name`, `run` or `if` was read as prose and dropped, so a
+  `runs-on: ${{ matrix.name }}` over image labels found nothing. Under `matrix:`
+  every key is a dimension the job varies over, and the prose keys only hold
+  prose outside it.
+
 - A label written under a key named `name`, `run` or `if` was dropped even when
   that key held a map rather than prose. 1.4.0 taught the matrix fallback to skip
   the keys that hold shell and titles, and an empty one swallowed everything
@@ -213,6 +218,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   for that file. An empty prose key now only owns a body that is not itself a
   map.
 
+- `--as-of` accepted a date `Date.parse` reads in local time, which is the
+  off-by-a-day the flag normalises to UTC to avoid: `--as-of "Oct 19 2026"`
+  measured from the 18th east of Greenwich. It takes ISO dates and date-times
+  now, with or without a zone, and refuses the rest.
+
 - The migration step-summary table badged the phase, not the outcome, so a runner
   still serving the old image after the window closed showed `✅ settled` in the
   row beside its own `::error`. The column is headed Status now and names the
diff --git a/README.md b/README.md
index 54b2cf2..6f91909 100644
--- a/README.md
+++ b/README.md
@@ -605,7 +605,7 @@ summary table, and sets a `will-fail-count` output.
 | `--json` | all | off | Machine-readable output |
 | `--no-summary` | `guard`, `runners`, `actions` | on | Skip the `$GITHUB_STEP_SUMMARY` write |
 | `--no-update-lock` | `guard` | on | Report drift but leave the lock file untouched |
-| `--as-of <date>` | `guard`, `plan`, `runners`, `actions` | today | Measure every countdown from this date instead. Nothing else is faked, so it answers "what will this say on the 19th?" |
+| `--as-of <date>` | `guard`, `plan`, `runners`, `actions` | today | Measure every countdown from this date instead. Nothing else is faked, so it answers "what will this say on the 19th?" ISO only (`2026-10-19`, `2026-10-19T09:00`), read as UTC when no zone is given. |
 
 Exit codes: `0` success (including "drift found" without `--fail-on`, a refused
 permission, and an empty fleet), `1` drift at or above the `--fail-on` threshold,
diff --git a/src/cli.mjs b/src/cli.mjs
index 571ec5b..2af957b 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -197,16 +197,21 @@ function out(stream, line) {
   stream.write(`${line}\n`);
 }
 
+const ISO_WHEN = /^(\d{4}-\d{2}-\d{2})(?:[T ](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)(Z|[+-]\d{2}:?\d{2})?)?$/;
+
 /**
- * A date or a zone-less time reads as UTC, which is the calendar every
- * countdown in the output is measured in. Left to `Date.parse`, a naive time is
- * local, so `--as-of 2026-10-19T00:00:00` lands on the 18th west of Greenwich
- * and reports the window as a day away rather than open.
+ * An ISO instant, reading a date or a zone-less time as UTC, or NaN.
+ *
+ * UTC is the calendar every countdown in the output is measured in. Left to
+ * `Date.parse`, a naive time is local, so `--as-of 2026-10-19T00:00:00` lands
+ * on the 18th west of Greenwich and reports the window as a day away rather
+ * than open. Anything `Date.parse` would read in local time is refused for the
+ * same reason, rather than silently landing a day out.
  */
-function utcWhenNaive(raw) {
-  if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) return `${raw}T00:00:00Z`;
-  if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(raw)) return `${raw.replace(' ', 'T')}Z`;
-  return raw;
+function isoInstant(raw) {
+  const m = raw.match(ISO_WHEN);
+  if (!m) return NaN;
+  return Date.parse(m[2] ? `${m[1]}T${m[2]}${m[3] ?? 'Z'}` : `${m[1]}T00:00:00Z`);
 }
 
 /**
@@ -218,7 +223,7 @@ function utcWhenNaive(raw) {
 function asOf(opts, io) {
   if (opts['as-of'] === undefined) return {};
   const raw = String(opts['as-of']);
-  const at = Date.parse(utcWhenNaive(raw));
+  const at = isoInstant(raw);
   if (!Number.isFinite(at)) {
     out(io.stderr, `--as-of needs a date such as 2026-10-19 (got "${raw}")`);
     return null;
diff --git a/src/detect.mjs b/src/detect.mjs
index 1966eb7..a751e19 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -241,6 +241,7 @@ function foldsOver(lines, i, indent) {
 function matrixLabels(lines) {
   const found = [];
   let scalar = null;
+  let matrixAt = null;
   for (let i = 0; i < lines.length; i++) {
     const text = stripComment(lines[i]);
     if (scalar !== null) {
@@ -259,7 +260,12 @@ function matrixLabels(lines) {
       // siblings (`env:`, `with:`) are not read as part of the script.
       const value = key[4].trim();
       const owns = key[1].length + (key[2]?.length ?? 0);
-      const prose = PROSE_KEYS.has((key[3] ?? '').trim().toLowerCase());
+      const name = (key[3] ?? '').trim().toLowerCase();
+      // Under `matrix:` every key is a dimension the job varies over, so a
+      // `matrix.name` of image labels is values, not a step title.
+      if (matrixAt !== null && key[1].length <= matrixAt) matrixAt = null;
+      const prose = matrixAt === null && PROSE_KEYS.has(name);
+      if (name === 'matrix') matrixAt = key[1].length;
       if (/^[|>]/.test(value) || (prose && (value || foldsOver(lines, i, owns)))) {
         scalar = owns;
         continue;
@@ -361,7 +367,9 @@ function jobKeys(lines) {
  *
  * `viaMatrix` marks a label read out of a matrix rather than off a `runs-on:`
  * line. Its job is right, but which leg of the matrix any one runner is serving
- * is not written anywhere in the file.
+ * is not written anywhere in the file. A `workflow_call` input default and a
+ * top-level `env:` value sit above the jobs map and so have no job of their own;
+ * they carry `jobs`, the ids whose `runs-on:` is an expression, instead.
  */
 function labelSitesWhere(walk, file, keep) {
   const { found, expression, matrix, targets, jobs } = walk;
@@ -371,7 +379,7 @@ function labelSitesWhere(walk, file, keep) {
   // `workflow_call` input default and a top-level `env:` value both live above
   // it. The jobs it can serve are the ones whose `runs-on:` is an expression.
   const viaExpression = expression
-    ? [...new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))]
+    ? [...new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))].filter(Boolean)
     : [];
 
   const seen = new Set();
@@ -379,15 +387,16 @@ function labelSitesWhere(walk, file, keep) {
   const all = expression ? [...found, ...matrix.map((m) => ({ ...m, viaMatrix: true }))] : found;
   for (const { label, line, col, viaMatrix } of all) {
     if (!keep(label)) continue;
-    const own = jobOf(line);
-    const owners = viaMatrix && own === null && viaExpression.length ? viaExpression : [own];
-    for (const job of owners) {
-      const key = `${label}@${line}:${col}@${job}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      const site = { label, file, line, col, job };
-      sites.push(viaMatrix ? { ...site, viaMatrix } : site);
-    }
+    const key = `${label}@${line}:${col}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const job = jobOf(line);
+    const site = { label, file, line, col, job };
+    if (viaMatrix) site.viaMatrix = true;
+    // One annotation per position, so the jobs a label off the map can serve
+    // travel with it rather than becoming a site each.
+    if (viaMatrix && job === null && viaExpression.length) site.jobs = viaExpression;
+    sites.push(site);
   }
   return sites;
 }
@@ -480,7 +489,8 @@ export function labelOwnership({ label, observed = null, sites = [], others = []
 
 /** Is this `runs-on:` site the one the running job was scheduled from? */
 export function siteInJob(site, here) {
-  if (!here || !site?.job || site.job !== here.job) return false;
+  const owns = site?.job ? site.job === here?.job : Boolean(site?.jobs?.includes(here?.job));
+  if (!here || !owns) return false;
   if (!here.file || !site.file) return true;
   return path.basename(site.file).toLowerCase() === here.file.toLowerCase();
 }
diff --git a/test/cli.test.mjs b/test/cli.test.mjs
index 28a3ee1..1995ceb 100644
--- a/test/cli.test.mjs
+++ b/test/cli.test.mjs
@@ -144,7 +144,9 @@ test("every fail-on-* input the action declares is forwarded and known to the CL
 });
 
 test('--as-of rejects anything that is not a date', async () => {
-  for (const bad of ['tomorrow', '2026-13-45', '']) {
+  // A format Date.parse reads in local time is refused rather than landing a
+  // day out, which is the whole reason the flag normalises to UTC.
+  for (const bad of ['tomorrow', '2026-13-45', '', 'Oct 19 2026', '10/19/2026', '2026-10-19T00:00:00 EST']) {
     const r = await run(['plan', '--from', 'ubuntu-latest', '--as-of', bad]);
     assert.equal(r.code, EXIT_USAGE, `"${bad}" rejected`);
     assert.match(r.stderr, /--as-of needs a date such as 2026-10-19/);
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 56078a0..33e0e43 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -216,8 +216,8 @@ test('an expression runs-on resolves a workflow_call input default', () => {
   ].join('\n');
   assert.deepEqual(extractLabels(y), ['ubuntu-22.04']);
   assert.deepEqual(
-    extractLabelSites(y).map((s) => [s.label, s.line, s.job]),
-    [['ubuntu-22.04', 5, 'a']],
+    extractLabelSites(y).map((s) => [s.label, s.line, s.job, s.jobs]),
+    [['ubuntu-22.04', 5, null, ['a']]],
     'the default sits above the jobs map, but it is job a that runs on it',
   );
 });
@@ -235,12 +235,9 @@ test('a label an expression reaches from top-level env still belongs to the jobs
     '    runs-on: ${{ env.RUNNER }}',
   ].join('\n');
   assert.deepEqual(
-    extractFloatingSites(y).map((s) => [s.label, s.line, s.job]),
-    [
-      ['ubuntu-latest', 2, 'a'],
-      ['ubuntu-latest', 2, 'c'],
-    ],
-    'both expression jobs can be the one this label serves; the pinned job cannot',
+    extractFloatingSites(y).map((s) => [s.label, s.line, s.jobs]),
+    [['ubuntu-latest', 2, ['a', 'c']]],
+    'one annotation, naming both jobs it can serve; the pinned job is not one',
   );
 });
 
@@ -378,6 +375,52 @@ test('a label written in a step name or a condition is not a runner', () => {
   assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
 });
 
+test('a matrix dimension named after a prose key is still values', () => {
+  // `name` is a step title under `steps:` and a matrix axis under `matrix:`.
+  const y = [
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        name: [ubuntu-22.04, macos-14]',
+    '    runs-on: ${{ matrix.name }}',
+    '    steps:',
+    '      - name: build on ubuntu-latest',
+    '        run: make',
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(extractLabels(y).sort(), ['macos-14', 'ubuntu-22.04']);
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.line, s.job]),
+    [
+      ['ubuntu-22.04', 5, 'a'],
+      ['macos-14', 5, 'a'],
+    ],
+  );
+  assert.deepEqual(extractFloatingSites(y), [], 'the step title is still prose');
+});
+
+test('one label line is one site, however many jobs the expression serves', () => {
+  // Three jobs sharing an input default used to mean three identical
+  // annotations on the same line.
+  const y = [
+    'on:',
+    '  workflow_call:',
+    '    inputs:',
+    '      runner:',
+    '        default: ubuntu-latest',
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ inputs.runner }}',
+    '  b:',
+    '    runs-on: ${{ inputs.runner }}',
+    '  c:',
+    '    runs-on: ${{ inputs.runner }}',
+  ].join(String.fromCharCode(10));
+  const sites = extractFloatingSites(y);
+  assert.equal(sites.length, 1);
+  assert.deepEqual(sites[0].jobs, ['a', 'b', 'c']);
+});
+
 test('an empty prose key that holds a map is read, not skipped', () => {
   // `name:` is a prose key, but `inputs.name` is an input whose default a
   // `runs-on:` expression resolves to.
@@ -393,8 +436,8 @@ test('an empty prose key that holds a map is read, not skipped', () => {
   ].join('\n');
   assert.deepEqual(extractLabels(y), ['ubuntu-22.04']);
   assert.deepEqual(
-    extractLabelSites(y).map((s) => [s.label, s.line, s.job]),
-    [['ubuntu-22.04', 5, 'a']],
+    extractLabelSites(y).map((s) => [s.label, s.line, s.jobs]),
+    [['ubuntu-22.04', 5, ['a']]],
   );
 });
 

From 8feeb3a8eeef038280cf5372a6f50ebf8e116a0f Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 18:32:16 +0800
Subject: [PATCH 33/44] Keep the matrix token scan out of jobs that name their
 runner outright

A job whose runs-on: is a plain label is scheduled by that label, so an env:
value under it that happens to look like an image is not a runner it asks for.
It was becoming a rival matrix leg, which threw away the runner's own ImageOS
and failed --fail-on-migration on a runner that had already migrated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  9 +++++++
 src/detect.mjs                                | 15 ++++++++---
 test/detect.test.mjs                          | 26 +++++++++++++++++++
 test/fixtures/workflows-matrix-sibling/ci.yml | 14 ++++++++++
 test/migration.test.mjs                       | 25 ++++++++++++++++++
 5 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 test/fixtures/workflows-matrix-sibling/ci.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dbae635..fdbb021 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,15 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- One matrix job let every label-shaped value in the file speak for the job it
+  sat in. The fallback is a token scan, so a sibling job pinned to
+  `runs-on: ubuntu-latest` with an `env:` naming `ubuntu-26.04` looked like a job
+  reaching the floating label through a matrix with a rival leg: the runner's own
+  image was discarded and `--fail-on-migration` failed a runner that had already
+  moved. A job whose `runs-on:` is a plain label is scheduled by that label and
+  takes nothing from the fallback. The retirement lane stops annotating those
+  `env:` values as pinned images too.
+
 - A matrix axis called `name`, `run` or `if` was read as prose and dropped, so a
   `runs-on: ${{ matrix.name }}` over image labels found nothing. Under `matrix:`
   every key is a dimension the job varies over, and the prose keys only hold
diff --git a/src/detect.mjs b/src/detect.mjs
index a751e19..bd438e5 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -375,12 +375,18 @@ function labelSitesWhere(walk, file, keep) {
   const { found, expression, matrix, targets, jobs } = walk;
   const jobOf = (line) => jobs[line - 1] ?? null;
 
+  // The matrix fallback is a whole-file token scan, so it only says which job a
+  // label sits in, not which job could be scheduled by it. A job whose own
+  // `runs-on:` is a plain label is scheduled by that label and nothing else, and
+  // a label-shaped `env:` value under it is not a runner it asks for.
+  const asks = expression
+    ? new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))
+    : new Set();
+
   // A label an expression resolves to need not sit in the jobs map at all: a
   // `workflow_call` input default and a top-level `env:` value both live above
   // it. The jobs it can serve are the ones whose `runs-on:` is an expression.
-  const viaExpression = expression
-    ? [...new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))].filter(Boolean)
-    : [];
+  const viaExpression = [...asks].filter(Boolean);
 
   const seen = new Set();
   const sites = [];
@@ -389,8 +395,9 @@ function labelSitesWhere(walk, file, keep) {
     if (!keep(label)) continue;
     const key = `${label}@${line}:${col}`;
     if (seen.has(key)) continue;
-    seen.add(key);
     const job = jobOf(line);
+    if (viaMatrix && job !== null && !asks.has(job)) continue;
+    seen.add(key);
     const site = { label, file, line, col, job };
     if (viaMatrix) site.viaMatrix = true;
     // One annotation per position, so the jobs a label off the map can serve
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 33e0e43..56b1552 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -399,6 +399,32 @@ test('a matrix dimension named after a prose key is still values', () => {
   assert.deepEqual(extractFloatingSites(y), [], 'the step title is still prose');
 });
 
+test('a job with a plain runs-on gets no labels from the matrix fallback', () => {
+  // The fallback is a token scan over the whole file, so one matrix job used to
+  // turn every label-shaped value in every other job into a runner it asks for.
+  const y = [
+    'jobs:',
+    '  test:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-22.04]',
+    '    runs-on: ${{ matrix.os }}',
+    '  guard:',
+    '    runs-on: ubuntu-latest',
+    '    env:',
+    '      TARGET_IMAGE: ubuntu-26.04',
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.job]),
+    [['ubuntu-22.04', 'test']],
+    'the env value is not a runner the guard job asks for',
+  );
+  assert.deepEqual(
+    extractFloatingSites(y).map((s) => [s.label, s.job, s.viaMatrix]),
+    [['ubuntu-latest', 'guard', undefined]],
+  );
+});
+
 test('one label line is one site, however many jobs the expression serves', () => {
   // Three jobs sharing an input default used to mean three identical
   // annotations on the same line.
diff --git a/test/fixtures/workflows-matrix-sibling/ci.yml b/test/fixtures/workflows-matrix-sibling/ci.yml
new file mode 100644
index 0000000..abbd42b
--- /dev/null
+++ b/test/fixtures/workflows-matrix-sibling/ci.yml
@@ -0,0 +1,14 @@
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - run: node --version
+  guard:
+    runs-on: ubuntu-latest
+    env:
+      TARGET_IMAGE: ubuntu-26.04
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index cdc036b..baf391d 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -744,6 +744,31 @@ test('the job id alone decides when the run came from a file the scan never saw'
   assert.equal(strict({ ...sites[0], file: 'other.yml' }), false, 'a scanned file still has to match');
 });
 
+test('a matrix in a sibling job does not overrule this one plain runs-on', async () => {
+  // ci.yml has a matrix job and a guard job pinned to ubuntu-latest whose env
+  // names ubuntu-26.04. The token scan used to read that env value as a runner
+  // the guard job asks for, and treat this runner as that leg.
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '30',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-matrix-sibling'),
+    },
+    {
+      ImageOS: 'ubuntu26',
+      GITHUB_JOB: 'guard',
+      GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/ci.yml@refs/heads/main',
+    },
+    DURING,
+  );
+  const s = jsonOf(r.stdout).migration.surveys[0];
+  assert.equal(s.observed, 'ubuntu-26.04');
+  assert.equal(s.state, MIGRATION_STATE.MIGRATED);
+  assert.deepEqual(s.notes, []);
+  assert.equal(r.code, EXIT_OK, 'a runner that has already moved is green');
+});
+
 test('one matrix job is not reported as two workflows sharing a job id', () => {
   // The same withholding, but the repository has one file and one job in it:
   // the rival is the other leg of this job's own matrix, not a namesake.

From bfd437cb008cb1fa81a69036e1ed452e920ff671 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 18:47:42 +0800
Subject: [PATCH 34/44] A uses: job keeps the label it passes on, and a
 namesake is described as one

A job with no runs-on: of its own is a reusable-workflow call; the label it
hands the callee in with: is still a runner this file asks for, and the new
token-scan filter was dropping it.

The matrix wording was also reaching a run whose own job pins the floating
label, where both halves of the sentence are false.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md            | 13 ++++++++++++-
 src/detect.mjs          |  7 +++++--
 src/migration.mjs       | 13 +++++++------
 test/detect.test.mjs    | 24 ++++++++++++++++++++++++
 test/migration.test.mjs | 21 +++++++++++++++++++++
 5 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fdbb021..cd31b38 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -84,7 +84,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
   `--fail-on`, `--fail-on-retirement` and `--fail-on-deprecation` are untouched,
   and so are all four output formats' existing contents: the migration is a new
-  annotation group, a new step-summary table (Label, Phase, Move, Window, This
+  annotation group, a new step-summary table (Label, Status, Move, Window, This
   runner, Source) and a new `migration` key in `--json`.
 
 - **`--as-of <date>`** on every command that counts down to something (`guard`, `plan`, `runners`, `actions`). It moves the clock every countdown is
@@ -205,6 +205,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A `uses:` job passing a runner label to a reusable workflow lost it whenever
+  the file also had a matrix job. Such a job has no `runs-on:` of its own, so the
+  `with:` value is the only record of the runner the file asks for, and the
+  retirement lane stopped naming it.
+
 - One matrix job let every label-shaped value in the file speak for the job it
   sat in. The fallback is a token scan, so a sibling job pinned to
   `runs-on: ubuntu-latest` with an `env:` naming `ubuntu-26.04` looked like a job
@@ -246,6 +251,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   rollout month, and only when run inside a job, which read as flakiness. Such a
   label now belongs to every job whose `runs-on:` is an expression.
 
+- The same sentence was used when this run's own job asks for the floating label
+  outright and the namesake job reaches the observed image through a matrix. It
+  claimed a matrix this job does not have and a pin the other one does not have.
+  A namesake is now described by what it can be scheduled onto when it is not a
+  plain pin.
+
 - A job that reaches the floating label through its own matrix was explained as
   two workflows sharing a job id whenever the run could not be placed in a file,
   which is every run with no `GITHUB_WORKFLOW_REF` and every run inside a
diff --git a/src/detect.mjs b/src/detect.mjs
index bd438e5..0b47e1b 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -378,10 +378,13 @@ function labelSitesWhere(walk, file, keep) {
   // The matrix fallback is a whole-file token scan, so it only says which job a
   // label sits in, not which job could be scheduled by it. A job whose own
   // `runs-on:` is a plain label is scheduled by that label and nothing else, and
-  // a label-shaped `env:` value under it is not a runner it asks for.
+  // a label-shaped `env:` value under it is not a runner it asks for. A job with
+  // no `runs-on:` at all is a `uses:` call, and the label it hands the callee in
+  // `with:` is still a runner this file asks for.
   const asks = expression
     ? new Set(targets.filter((t) => t.expression).map((t) => jobOf(t.line)))
     : new Set();
+  const names = new Set(targets.map((t) => jobOf(t.line)));
 
   // A label an expression resolves to need not sit in the jobs map at all: a
   // `workflow_call` input default and a top-level `env:` value both live above
@@ -396,7 +399,7 @@ function labelSitesWhere(walk, file, keep) {
     const key = `${label}@${line}:${col}`;
     if (seen.has(key)) continue;
     const job = jobOf(line);
-    if (viaMatrix && job !== null && !asks.has(job)) continue;
+    if (viaMatrix && job !== null && names.has(job) && !asks.has(job)) continue;
     seen.add(key);
     const site = { label, file, line, col, job };
     if (viaMatrix) site.viaMatrix = true;
diff --git a/src/migration.mjs b/src/migration.mjs
index f775998..e75aba5 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -82,14 +82,15 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
 
   if (asked) {
     if (endpoint) return { imageOS, note: null };
-    // Two jobs sharing an id, rather than one job with two legs: only a plain
-    // `runs-on:` rules out a matrix, and only an unplaceable run can be in
-    // another file at all.
-    if (rival && named && !placed) {
+    // Two jobs sharing an id, rather than one job with two legs: only an
+    // unplaceable run can be in another file at all, and this job's own
+    // `runs-on:` rules the matrix wording out whenever it is a plain label.
+    if (rival && !placed && (named || direct)) {
+      const how = named ? `asks for ${observed} by name` : `can be scheduled onto ${observed}`;
       return {
         imageOS: null,
-        note: `More than one workflow has a job called "${here.job}", and one of them asks for `
-          + `${observed} by name, so this runner may be that job instead.`,
+        note: `More than one workflow has a job called "${here.job}", and one of them ${how}, `
+          + 'so this runner may be that job instead.',
       };
     }
     return {
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 56b1552..8a17ba1 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -425,6 +425,30 @@ test('a job with a plain runs-on gets no labels from the matrix fallback', () =>
   );
 });
 
+test('a job with no runs-on still hands a label to the workflow it calls', () => {
+  // A `uses:` job has no runs-on of its own, so the label it passes in `with:`
+  // is the only record of the runner this file asks for.
+  const y = [
+    'jobs:',
+    '  test:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-24.04]',
+    '    runs-on: ${{ matrix.os }}',
+    '  call:',
+    '    uses: ./.github/workflows/build.yml',
+    '    with:',
+    '      runner: ubuntu-22.04',
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(
+    extractLabelSites(y).map((s) => [s.label, s.job]),
+    [
+      ['ubuntu-24.04', 'test'],
+      ['ubuntu-22.04', 'call'],
+    ],
+  );
+});
+
 test('one label line is one site, however many jobs the expression serves', () => {
   // Three jobs sharing an input default used to mean three identical
   // annotations on the same line.
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index baf391d..f18bb4d 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -769,6 +769,27 @@ test('a matrix in a sibling job does not overrule this one plain runs-on', async
   assert.equal(r.code, EXIT_OK, 'a runner that has already moved is green');
 });
 
+test('a namesake job that matrixes onto the image is named as one, not as a leg', () => {
+  // This run's own job asks for the floating label outright, so the rival can
+  // only be the other file's job of the same id.
+  const mine = ['jobs:', '  build:', '    runs-on: ubuntu-latest'].join(String.fromCharCode(10));
+  const theirs = [
+    'jobs:',
+    '  build:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-26.04]',
+    '    runs-on: ${{ matrix.os }}',
+  ].join(String.fromCharCode(10));
+  const sites = [...extractFloatingSites(mine, 'ci.yml'), ...extractFloatingSites(theirs, 'release.yml')];
+  const others = [...extractLabelSites(mine, 'ci.yml'), ...extractLabelSites(theirs, 'release.yml')];
+  const here = { job: 'build', file: 'caller.yml' };
+  const a = attributeImageOS({ label: 'ubuntu-latest', imageOS: 'ubuntu26', sites, others, here });
+  assert.equal(a.imageOS, null);
+  assert.doesNotMatch(a.note, /through a matrix/, 'this job has no matrix');
+  assert.match(a.note, /More than one workflow has a job called "build", and one of them can be scheduled onto ubuntu-26.04/);
+});
+
 test('one matrix job is not reported as two workflows sharing a job id', () => {
   // The same withholding, but the repository has one file and one job in it:
   // the rival is the other leg of this job's own matrix, not a namesake.

From a7a4adaee2556549e6bb23b5efb603da0474fc6f Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 19:02:04 +0800
Subject: [PATCH 35/44] A job id that runs somewhere else too cannot speak for
 this label

An unplaceable run matched on the job id alone, so a plain runs-on:
ubuntu-latest in another file attributed a Windows runner's image to the
floating label and raised an unrecognised-image error on a workflow the run
never touched. Require every file holding a job of that id to ask for the
label before a direct site settles it.

Also: with no GITHUB_JOB, a matrix leg was described as a workflow asking for
the image by name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 12 +++++
 src/detect.mjs                                | 10 ++++-
 src/manifest.mjs                              |  2 +-
 src/migration.mjs                             | 31 ++++++++++---
 .../fixtures/workflows-build-elsewhere/ci.yml |  8 ++++
 .../workflows-build-elsewhere/release.yml     |  8 ++++
 test/migration.test.mjs                       | 45 +++++++++++++++++++
 7 files changed, 107 insertions(+), 9 deletions(-)
 create mode 100644 test/fixtures/workflows-build-elsewhere/ci.yml
 create mode 100644 test/fixtures/workflows-build-elsewhere/release.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd31b38..9eee7c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,18 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A run that could not be placed in a file took a plain `runs-on: ubuntu-latest`
+  from any file with a job of the same id. Two `build` jobs, one on
+  `ubuntu-latest` and one on `windows-latest`, and a run reporting a caller the
+  scan does not hold: the Windows runner's image was attributed to
+  `ubuntu-latest` and reported as an image nobody announced, an `::error` that
+  fails at any threshold, annotated on a workflow the run never touched. A job id
+  that names jobs in files which do not all ask for the label now settles
+  nothing, and the run says so.
+
+- With no `GITHUB_JOB`, a matrix leg that can be scheduled onto the observed
+  image was reported as a workflow asking for it by name.
+
 - A `uses:` job passing a runner label to a reusable workflow lost it whenever
   the file also had a matrix job. Such a job has no `runs-on:` of its own, so the
   `with:` value is the only record of the runner the file asks for, and the
diff --git a/src/detect.mjs b/src/detect.mjs
index 0b47e1b..2e7aeba 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -474,7 +474,10 @@ export function jobMatcher(here, sites = []) {
  * through a matrix, and `rival` is another site naming `observed`, which the
  * runner is as likely to be serving as the floating one. `named` says that
  * rival is a plain `runs-on:` rather than a matrix leg, which is the difference
- * between two jobs sharing an id and one job with two legs.
+ * between two jobs sharing an id and one job with two legs. `alone` is whether
+ * every file holding a job of this id asks for `label` in it, which is what an
+ * unplaced `direct` is worth: one of two `build` jobs runs on Windows, and the
+ * run cannot say which one it is.
  *
  * Inside one job the only rival is a matrix leg, since a job has one `runs-on:`.
  * That needs the job to be pinned to a file. A job id alone can name a job in
@@ -487,6 +490,10 @@ export function labelOwnership({ label, observed = null, sites = [], others = []
   const inScope = here ? match : () => true;
   const mine = sites.filter((site) => site.label === label && inScope(site));
   const rivals = others.filter((site) => site.label === observed && inScope(site));
+  const asking = new Set(mine.map((site) => site.file));
+  const alone = [...sites, ...others]
+    .filter((site) => inScope(site))
+    .every((site) => asking.has(site.file));
   return {
     scoped: Boolean(here),
     placed: pinned,
@@ -494,6 +501,7 @@ export function labelOwnership({ label, observed = null, sites = [], others = []
     asked: mine.length > 0,
     rival: observed !== null && (pinned ? rivals.some((site) => site.viaMatrix) : rivals.length > 0),
     named: observed !== null && rivals.some((site) => !site.viaMatrix),
+    alone: pinned || alone,
   };
 }
 
diff --git a/src/manifest.mjs b/src/manifest.mjs
index b6fe7ad..7208030 100644
--- a/src/manifest.mjs
+++ b/src/manifest.mjs
@@ -354,7 +354,7 @@ export function lookupTool(manifest, candidates) {
  * A tool neither manifest lists is not a diff of two absences: it is a tool the
  * comparison cannot speak for at all, so it comes back separately and `plan` and
  * the migration lane each say so in their own words.
- * \returns {{diffs:object[], notOnManifest:string[]}}
+ * @returns {{diffs:object[], notOnManifest:string[]}}
  */
 export function diffManifestTools(from, to, tools) {
   const a = resolveManifestVersions(from, tools);
diff --git a/src/migration.mjs b/src/migration.mjs
index e75aba5..c54a6d0 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -61,22 +61,32 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
   if (!imageOS) return { imageOS: null, note: null };
   const m = migrationFor(label);
   const observed = labelForImageOS(imageOS);
-  const { direct, asked, rival, placed, named } = labelOwnership({ label, observed, sites, others, here });
+  const { direct, asked, rival, placed, named, alone } = labelOwnership({
+    label, observed, sites, others, here,
+  });
 
   // A plain `runs-on:` in the job this run came from settles it, as long as the
   // job id picked out one job. A job a reusable workflow reports is matched on
-  // the id alone, and an id is unique in a file, not in a repository.
-  if (here && direct && !rival) return { imageOS, note: null };
+  // the id alone, and an id is unique in a file, not in a repository, so a
+  // second file whose job of that id runs somewhere else takes the claim back.
+  if (here && direct && !rival && alone) return { imageOS, note: null };
   const endpoint = !rival && (observed === m?.from || observed === m?.to);
 
   if (!here) {
     if (endpoint) return { imageOS, note: null };
+    if (rival) {
+      return {
+        imageOS: null,
+        note: named
+          ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
+          : `A matrix in these workflows can be scheduled onto ${observed}, so this runner is not `
+            + `evidence about ${label}.`,
+      };
+    }
     return {
       imageOS: null,
-      note: rival
-        ? `These workflows ask for ${observed} by name, so this runner is not evidence about ${label}.`
-        : `No GITHUB_JOB says which job this check ran in, and ${observed ?? imageOS} is neither `
-          + `image in the ${label} window, so this runner is not evidence about it.`,
+      note: `No GITHUB_JOB says which job this check ran in, and ${observed ?? imageOS} is neither `
+        + `image in the ${label} window, so this runner is not evidence about it.`,
     };
   }
 
@@ -93,6 +103,13 @@ export function attributeImageOS({ label, imageOS, sites = [], others = [], here
           + 'so this runner may be that job instead.',
       };
     }
+    if (!alone) {
+      return {
+        imageOS: null,
+        note: `More than one workflow has a job called "${here.job}" and they do not all run on `
+          + `${label}, so this runner may be one of the others.`,
+      };
+    }
     return {
       imageOS: null,
       note: rival
diff --git a/test/fixtures/workflows-build-elsewhere/ci.yml b/test/fixtures/workflows-build-elsewhere/ci.yml
new file mode 100644
index 0000000..e4b3414
--- /dev/null
+++ b/test/fixtures/workflows-build-elsewhere/ci.yml
@@ -0,0 +1,8 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: node --version
diff --git a/test/fixtures/workflows-build-elsewhere/release.yml b/test/fixtures/workflows-build-elsewhere/release.yml
new file mode 100644
index 0000000..cb63e42
--- /dev/null
+++ b/test/fixtures/workflows-build-elsewhere/release.yml
@@ -0,0 +1,8 @@
+name: release
+on: [workflow_dispatch]
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - run: node --version
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index f18bb4d..ef92648 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -769,6 +769,51 @@ test('a matrix in a sibling job does not overrule this one plain runs-on', async
   assert.equal(r.code, EXIT_OK, 'a runner that has already moved is green');
 });
 
+test('an unplaceable run does not hand another file\'s Windows image to the label', async () => {
+  // ci.yml's build is on ubuntu-latest and release.yml's is on windows-latest.
+  // The run reports a caller the scan does not hold, so the id alone is left to
+  // match on, and a plain runs-on: in the wrong file used to settle it.
+  const r = await guard(
+    {
+      tools: 'node',
+      'fail-on-migration': '30',
+      json: true,
+      workflows: path.join(FIXTURES, 'workflows-build-elsewhere'),
+    },
+    {
+      ImageOS: 'win25',
+      GITHUB_JOB: 'build',
+      GITHUB_WORKFLOW_REF: 'o/r/.github/workflows/caller.yml@refs/heads/main',
+    },
+    DURING,
+  );
+  const s = jsonOf(r.stdout).migration.surveys[0];
+  assert.equal(s.observed, null, 'a Windows runner says nothing about ubuntu-latest');
+  assert.notEqual(s.state, MIGRATION_STATE.UNEXPECTED, 'not an error raised at the wrong repo');
+  assert.match(s.notes.join(' '), /they do not all run on ubuntu-latest/);
+});
+
+test('with no job at all, a matrix leg is not described as a pin', async () => {
+  const y = await readFile(path.join(FIXTURES, 'workflows-matrix', 'ci.yml'), 'utf8');
+  const a = attributeImageOS({
+    label: 'ubuntu-latest',
+    imageOS: 'ubuntu22',
+    sites: extractFloatingSites(y, 'ci.yml'),
+    others: extractLabelSites(y, 'ci.yml'),
+    here: null,
+  });
+  assert.equal(a.imageOS, null);
+  const b = attributeImageOS({
+    label: 'ubuntu-latest',
+    imageOS: 'ubuntu26',
+    sites: extractFloatingSites(y, 'ci.yml'),
+    others: extractLabelSites(y, 'ci.yml'),
+    here: null,
+  });
+  assert.doesNotMatch(b.note, /ask for ubuntu-26.04 by name/, 'the only site is a matrix leg');
+  assert.match(b.note, /A matrix in these workflows can be scheduled onto ubuntu-26.04/);
+});
+
 test('a namesake job that matrixes onto the image is named as one, not as a leg', () => {
   // This run's own job asks for the floating label outright, so the rival can
   // only be the other file's job of the same id.

From 28f22cf9fd9db65bc14db6603336c86fcd21db84 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 19:17:59 +0800
Subject: [PATCH 36/44] Let the label gates report and decide when there are no
 tools to watch

guard returned EXIT_USAGE before reportRetirement and reportMigration ran, so
a repo with no detectable tools got the annotation without the reason line and
exit 2 instead of exit 1.

Also stop imageDiffs calling a header field the other OS does not publish a
removal.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                            | 10 ++++++++
 runner-lock.json                        |  4 ++--
 src/cli.mjs                             |  8 ++++++-
 src/migration.mjs                       | 12 ++++++----
 test/fixtures/workflows-no-tools/ci.yml |  8 +++++++
 test/migration.test.mjs                 | 32 +++++++++++++++++++++++++
 6 files changed, 67 insertions(+), 7 deletions(-)
 create mode 100644 test/fixtures/workflows-no-tools/ci.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9eee7c0..49c24b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -205,6 +205,16 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   explanation, exactly as it does when there is no job id at all, and says so
   rather than reporting the label as migrated.
 
+- A repo with no tools to watch exited 2 from `guard` before the retirement and
+  migration gates could report, so the annotation was printed, the reason line
+  was not, and CI saw a usage error instead of a failed check. Both gates read
+  the workflow files rather than the tool list, so they now report and decide the
+  exit code; the advice about `--tools` is still printed.
+
+- A manifest header field one side does not publish was reported as a removal.
+  `plan --from ubuntu-24.04 --to windows-2025` said the kernel and systemd had
+  gone, in MAJOR red, when Windows manifests simply have no such line.
+
 - A run that could not be placed in a file took a plain `runs-on: ubuntu-latest`
   from any file with a job of the same id. Two `build` jobs, one on
   `ubuntu-latest` and one on `windows-latest`, and a run reporting a caller the
diff --git a/runner-lock.json b/runner-lock.json
index a8ebabe..b3bc845 100644
--- a/runner-lock.json
+++ b/runner-lock.json
@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "label": "ubuntu-24.04",
   "imageOS": "ubuntu24",
-  "imageVersion": "20260720.247.2",
+  "imageVersion": "20260907.300.1",
   "tools": {
     "Node.js": {
       "versions": [
@@ -12,5 +12,5 @@
       "command": "node --version"
     }
   },
-  "updatedAt": "2026-08-05T05:13:56.107Z"
+  "updatedAt": "2026-09-20T11:17:35.354Z"
 }
diff --git a/src/cli.mjs b/src/cli.mjs
index 2af957b..769d9ed 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -744,7 +744,13 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   if (!tools.length) {
     out(io.stderr, 'No tools detected in your workflows and none in the lock file.');
     out(io.stderr, 'Pass them explicitly: runner-drift guard --tools python,cmake,clang');
-    return EXIT_USAGE;
+    // The two label gates read the workflow files, not the tool list, so they
+    // have already found whatever they were going to find.
+    const doc = laneDocument({ retirement, migration });
+    if (opts.json && Object.keys(doc).length) out(io.stdout, JSON.stringify(doc, null, 2));
+    if (retiring) reportRetirement(io, retiring);
+    if (migrating) reportMigration(io, migrating);
+    return retiring || migrating ? EXIT_DRIFT : EXIT_USAGE;
   }
 
   // Observe the live runner: probe first, manifest as the fallback.
diff --git a/src/migration.mjs b/src/migration.mjs
index c54a6d0..d1ca7ff 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -30,12 +30,16 @@ export const IMAGE_FIELDS = [
 const one = (v) => (v ? [v] : null);
 
 /**
- * Diff the manifest headers of two images. A field missing from both — macOS
- * manifests carry no kernel or systemd line — diffs to `missing` and is
- * dropped by the `changed` filter, so no caller has to special-case it.
+ * Diff the manifest headers of two images. A field one side does not publish —
+ * macOS and Windows manifests carry no kernel or systemd line — is not a
+ * removal, so it diffs to `missing` and the `changed` filter drops it.
  */
 export function imageDiffs(from, to) {
-  return IMAGE_FIELDS.map(([name, field]) => diffTool(name, one(from?.[field]), one(to?.[field])));
+  return IMAGE_FIELDS.map(([name, field]) => {
+    const a = from?.[field];
+    const b = to?.[field];
+    return a && b ? diffTool(name, one(a), one(b)) : diffTool(name, null, null);
+  });
 }
 
 /**
diff --git a/test/fixtures/workflows-no-tools/ci.yml b/test/fixtures/workflows-no-tools/ci.yml
new file mode 100644
index 0000000..f2b55a2
--- /dev/null
+++ b/test/fixtures/workflows-no-tools/ci.yml
@@ -0,0 +1,8 @@
+name: ci
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index ef92648..eb32807 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -296,6 +296,19 @@ test('imageDiffs tolerates a manifest with no kernel or systemd line', () => {
   );
 });
 
+test('a header field one side does not publish is not a removal', () => {
+  // `plan --from ubuntu-24.04 --to windows-2025` is a legal comparison, and
+  // Windows manifests carry no kernel or systemd line.
+  const rows = imageDiffs(
+    { osVersion: '24.04.5 LTS', kernelVersion: '6.17.0-1022-azure', systemdVersion: '255.4' },
+    { osVersion: 'Windows Server 2025' },
+  );
+  assert.deepEqual(
+    rows.filter((d) => d.changed).map((d) => d.tool),
+    ['OS'],
+  );
+});
+
 /* ----------------------------------------------------------------- report */
 
 test('each state gets its own sentence, and the anomaly says so', async () => {
@@ -814,6 +827,25 @@ test('with no job at all, a matrix leg is not described as a pin', async () => {
   assert.match(b.note, /A matrix in these workflows can be scheduled onto ubuntu-26.04/);
 });
 
+test('a repo with no tools still gets the migration gate, and its exit code', async () => {
+  // The gate reads the workflow files, not the tool list, so the annotation was
+  // printed while the run exited 2 with no reason line.
+  const r = await guard(
+    {
+      'fail-on-migration': '30',
+      workflows: path.join(FIXTURES, 'workflows-no-tools'),
+      'lock-file': path.join(FIXTURES, 'workflows-no-tools', 'no-such-lock.json'),
+      'update-lock': false,
+    },
+    { ImageOS: 'ubuntu24', ImageVersion: '20260907.300.1' },
+    BEFORE,
+  );
+  assert.equal(r.code, EXIT_DRIFT, 'the gate decides the exit code, not the empty tool list');
+  assert.match(r.stdout, /ubuntu-latest becomes ubuntu-26.04 in 18 days/);
+  assert.match(r.stderr, /--fail-on-migration 30 is set\./);
+  assert.match(r.stderr, /No tools detected/, 'the usage advice is still printed');
+});
+
 test('a namesake job that matrixes onto the image is named as one, not as a leg', () => {
   // This run's own job asks for the floating label outright, so the rival can
   // only be the other file's job of the same id.

From d75033d13547ded49e529cce6c673d2c5787a957 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 19:36:23 +0800
Subject: [PATCH 37/44] A tool the manifest could not be read for is
 unobserved, not removed

---
 CHANGELOG.md        |  7 +++++++
 src/cli.mjs         | 20 +++++++++++++++++---
 test/guard.test.mjs | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49c24b3..759776a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -195,6 +195,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   the build over a rate limit. The readme fallback now runs whatever the API
   did.
 
+- A tool nothing could observe was still diffed as REMOVED. When both manifest
+  reads fail, every manifest-only tool in the lock was warned about as skipped
+  and then reported as removed in the same run, so `--fail-on major` red the
+  build over an `ECONNRESET` even with the readme fallback in place. Unobserved
+  is not removed: those tools are left out of the diff, and they keep the entry
+  the lock already has so the next run does not read them as added either.
+
 - A job id the run could not be placed by let one workflow file speak for
   another. Inside a reusable workflow `GITHUB_WORKFLOW_REF` names the caller,
   so the job is matched on its id alone, and an id is unique in a file rather
diff --git a/src/cli.mjs b/src/cli.mjs
index 769d9ed..9e7260a 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -771,6 +771,10 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   let attribution0 = null;
   let approximate = false;
   const infraWarnings = [];
+  // Tools nothing could observe this run. Unobserved is not removed: a rate
+  // limit must not diff as REMOVED, nor drop the tool from the lock so that the
+  // next run reads it as ADDED.
+  const unobserved = new Set();
 
   if (needManifest.length) {
     // Pinning the manifest to the commit that shipped this image version is an
@@ -805,7 +809,10 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
       }
     } else {
       for (const t of needManifest) {
-        infraWarnings.push(`${t}: not probeable here and the ${label} manifest could not be fetched — skipped.`);
+        unobserved.add(t);
+        infraWarnings.push(
+          `${t}: not probeable here and the ${label} manifest could not be fetched — not compared.`,
+        );
       }
     }
   }
@@ -862,7 +869,9 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   // Diff against the lock.
   const lockedMap = toVersionMap(lock.tools);
   const observedMap = toVersionMap(observed);
-  const watched = tools.filter((t) => Object.hasOwn(lockedMap, t) || Object.hasOwn(observedMap, t));
+  const watched = tools.filter(
+    (t) => !unobserved.has(t) && (Object.hasOwn(lockedMap, t) || Object.hasOwn(observedMap, t)),
+  );
   const diffs = watched.map((t) => diffTool(t, lookup(lockedMap, t), lookup(observedMap, t)));
   const changed = diffs.filter((d) => d.changed);
 
@@ -925,8 +934,13 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
   for (const line of annotations(diffs, attributionMap, label)) out(io.stdout, line);
 
   if (updateLock) {
+    const kept = Object.create(null);
+    for (const t of unobserved) {
+      const entry = lookup(lock.tools ?? {}, t);
+      if (entry) kept[t] = entry;
+    }
     await writeLock(
-      { label, imageOS, imageVersion, tools: observed, updatedAt: new Date().toISOString() },
+      { label, imageOS, imageVersion, tools: { ...observed, ...kept }, updatedAt: new Date().toISOString() },
       lockFile,
     );
   }
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index d6e41b5..087d214 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -209,6 +209,38 @@ test('a rate-limited attribution lookup does not cost the manifest read', async
   }
 });
 
+test('a manifest that cannot be read at all is not every locked tool removed', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  // Both reads refused: the pinned commit lookup by the API, the label's own
+  // readme by a dropped connection.
+  const api = stubApi(() => ({ status: 403, body: '', headers: { 'x-ratelimit-remaining': '0' } }));
+  try {
+    await writeLock(
+      {
+        label: 'ubuntu-22.04',
+        imageOS: 'ubuntu22',
+        imageVersion: IMAGE,
+        tools: { Bazel: { versions: ['9.1.0'], source: 'manifest' } },
+      },
+      lockFile,
+    );
+    const r = await guard({ tools: 'Bazel', 'lock-file': lockFile, 'fail-on': 'major', summary: false }, ENV, {
+      loadManifest: async () => {
+        throw new Error('fetch failed (ECONNRESET)');
+      },
+    });
+    assert.equal(r.code, EXIT_OK, 'an unreadable manifest is not drift');
+    assert.match(r.stdout, /Bazel: .*could not be fetched/);
+    assert.doesNotMatch(r.stdout, /REMOVED/);
+    const after = await readLock(lockFile);
+    assert.deepEqual(after.tools.Bazel.versions, ['9.1.0'], 'kept, or the next run calls it ADDED');
+  } finally {
+    api.restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('exit code 1 only under --fail-on major (and above)', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');

From 6322308e3739b05889d099061e3810343d128cef Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 19:37:07 +0800
Subject: [PATCH 38/44] Say which manifests really omit which header field

---
 src/migration.mjs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/migration.mjs b/src/migration.mjs
index d1ca7ff..006c871 100644
--- a/src/migration.mjs
+++ b/src/migration.mjs
@@ -30,9 +30,9 @@ export const IMAGE_FIELDS = [
 const one = (v) => (v ? [v] : null);
 
 /**
- * Diff the manifest headers of two images. A field one side does not publish —
- * macOS and Windows manifests carry no kernel or systemd line — is not a
- * removal, so it diffs to `missing` and the `changed` filter drops it.
+ * Diff the manifest headers of two images. A field either side does not publish
+ * (Windows manifests carry no kernel line, and only Linux publishes systemd) is
+ * not a removal, so it diffs to `missing` and the `changed` filter drops it.
  */
 export function imageDiffs(from, to) {
   return IMAGE_FIELDS.map(([name, field]) => {

From ebb7934b000a1356bd1e9642b62aa315ac822ad7 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 19:53:44 +0800
Subject: [PATCH 39/44] An unlisted tool with no probe recipe is not a removal
 either

---
 CHANGELOG.md        |  9 +++++++++
 README.md           | 10 ++++++++++
 src/cli.mjs         | 17 ++++++++++++++++-
 test/guard.test.mjs | 46 +++++++++++++++++++++++++++++++++++++++++----
 4 files changed, 77 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 759776a..c6b7c3d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -202,6 +202,15 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   is not removed: those tools are left out of the diff, and they keep the entry
   the lock already has so the next run does not read them as added either.
 
+  A tool the manifest did answer for, by not listing it, is the same case when
+  nothing else could have seen it: with no probe recipe the readme is its only
+  observer, and the readme is a curated page whose headings get renamed. Those
+  are left out of the diff too. A tool that does have a probe recipe was looked
+  for on the machine and not found, so a manifest that does not list it either
+  is still reported as REMOVED. `--json` names everything left out under
+  `notCompared`, since the `diffs` array would otherwise be quietly shorter than
+  the lock with the reason only on stdout.
+
 - A job id the run could not be placed by let one workflow file speak for
   another. Inside a reusable workflow `GITHUB_WORKFLOW_REF` names the caller,
   so the job is matched on its id alone, and an id is unique in a file rather
diff --git a/README.md b/README.md
index 6f91909..6ea5bd9 100644
--- a/README.md
+++ b/README.md
@@ -814,6 +814,16 @@ will actually **execute**. Tools with no probe recipe fall back to the manifest
 that exact image version, and the source is recorded so a source change is never
 mistaken for a version change.
 
+A tool the manifest cannot answer for is left out of the diff rather than
+reported as removed: a rate limit is not a tool being deleted. That covers both
+an unreadable manifest and a tool with no probe recipe that the readme does not
+list, since the readme is a curated page whose headings get renamed. Those names
+go in `--json` under `notCompared`, the reason is a `::warning` in the log, and
+they keep the entry the lock already had so the next run does not read them as
+added. A tool that does have a probe recipe is treated differently: the probe
+looked for it on this machine and did not find it, so a manifest that does not
+list it either is reported as removed.
+
 ## Supported labels
 
 `ubuntu-22.04`, `ubuntu-24.04`, `ubuntu-26.04` (+ `-arm`), `windows-2022`,
diff --git a/src/cli.mjs b/src/cli.mjs
index 9e7260a..360dfc7 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -805,7 +805,19 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
         observed[t] = toolsEntry(versions, 'manifest');
       }
       for (const t of missing) {
-        infraWarnings.push(`${t}: not probeable here and not listed on the ${label} manifest — skipped.`);
+        // A tool with a probe recipe was looked for on this machine and not
+        // found, so a manifest that does not list it either is evidence it has
+        // gone. A tool with no recipe had the manifest as its only observer,
+        // and the readme is a curated list under headings that get renamed, so
+        // absence from it is not a removal worth reddening a build over.
+        if (isProbeable(t)) {
+          infraWarnings.push(`${t}: not found on this runner and not listed on the ${label} manifest.`);
+        } else {
+          unobserved.add(t);
+          infraWarnings.push(
+            `${t}: no probe recipe here and not listed on the ${label} manifest — not compared.`,
+          );
+        }
       }
     } else {
       for (const t of needManifest) {
@@ -947,6 +959,9 @@ export async function runGuard(opts, io = process, env = process.env, deps = {})
 
   if (opts.json) {
     const payload = { label, fromLabel: lock.label ?? null, from: lock.imageVersion, to: imageVersion, approximate, written: updateLock, diffs, attribution: attributionMap };
+    // The tools missing from `diffs` and why, or a consumer reading the document
+    // sees a shorter list than the lock holds with the reason only on stdout.
+    if (unobserved.size) payload.notCompared = [...unobserved];
     payload.explains = explained?.label ?? null;
     if (retirement) payload.retirement = retirement;
     if (migration) payload.migration = { ...migration, explains: explained?.label ?? null };
diff --git a/test/guard.test.mjs b/test/guard.test.mjs
index 087d214..03f3e6b 100644
--- a/test/guard.test.mjs
+++ b/test/guard.test.mjs
@@ -123,7 +123,7 @@ test('drift is reported with a ::warning and exits 0 by default', async () => {
   }
 });
 
-test('a lock file naming a tool after a property of Object diffs like any other', async () => {
+test('a lock file naming a tool after a property of Object is handled like any other', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');
   try {
@@ -137,12 +137,17 @@ test('a lock file naming a tool after a property of Object diffs like any other'
         + `"__proto__":{"versions":["2.0.0"],"source":"manifest"}}}`,
       'utf8',
     );
-    const r = await guard({ 'lock-file': lockFile, 'update-lock': false }, ENV, {
+    const r = await guard({ 'lock-file': lockFile, json: true }, ENV, {
       loadManifest: fixtureLoader(),
     });
     assert.equal(r.code, EXIT_OK);
-    assert.match(r.stdout, /constructor 1\.0\.0 -> \(absent\)/);
-    assert.match(r.stdout, /__proto__ 2\.0\.0 -> \(absent\)/);
+    assert.match(r.stdout, /constructor: no probe recipe here/);
+    assert.match(r.stdout, /__proto__: no probe recipe here/);
+    assert.deepEqual(jsonOf(r.stdout).notCompared.sort(), ['__proto__', 'constructor']);
+    // Carried into the rewritten lock as their own keys, not onto a prototype.
+    const after = JSON.parse(await readFile(lockFile, 'utf8'));
+    assert.ok(Object.hasOwn(after.tools, '__proto__'));
+    assert.deepEqual(after.tools.constructor.versions, ['1.0.0']);
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
@@ -241,6 +246,39 @@ test('a manifest that cannot be read at all is not every locked tool removed', a
   }
 });
 
+test('a tool the readme does not list is not removed unless the machine agrees', async () => {
+  const dir = await tmp();
+  const lockFile = path.join(dir, 'runner-lock.json');
+  const api = stubApi(() => ({ status: 403, body: '', headers: { 'x-ratelimit-remaining': '0' } }));
+  try {
+    // Fortran has no probe recipe, so the readme was its only observer and a
+    // heading it does not appear under says nothing about the image.
+    await writeLock(
+      {
+        label: 'ubuntu-22.04',
+        imageOS: 'ubuntu22',
+        imageVersion: IMAGE,
+        tools: { Fortran: { versions: ['13.2.0'], source: 'manifest' } },
+      },
+      lockFile,
+    );
+    const r = await guard(
+      { tools: 'Fortran', 'lock-file': lockFile, 'fail-on': 'major', json: true, summary: false },
+      ENV,
+      { loadManifest: fixtureLoader() },
+    );
+    assert.equal(r.code, EXIT_OK);
+    assert.match(r.stdout, /Fortran: no probe recipe here and not listed/);
+    assert.doesNotMatch(r.stdout, /REMOVED/);
+    assert.deepEqual(jsonOf(r.stdout).notCompared, ['Fortran'], 'named in the document, not only on stdout');
+    const after = await readLock(lockFile);
+    assert.deepEqual(after.tools.Fortran.versions, ['13.2.0']);
+  } finally {
+    api.restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test('exit code 1 only under --fail-on major (and above)', async () => {
   const dir = await tmp();
   const lockFile = path.join(dir, 'runner-lock.json');

From fd16bc651dbbe58133b5fa476708b246853e44d1 Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 20:15:53 +0800
Subject: [PATCH 40/44] Say days in the brownout countdown, and drop a flag
 nothing reads

---
 README.md          | 2 +-
 src/detect.mjs     | 7 +++----
 src/report.mjs     | 8 ++++----
 test/plan.test.mjs | 2 +-
 4 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 6ea5bd9..3176854 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ brownouts starting 2027-03-23](https://github.com/actions/runner-images/issues/1
 $ npx runner-drift plan --from ubuntu-22.04 --to ubuntu-24.04
 ubuntu-22.04 -> ubuntu-24.04 (images 20260720.234.2 -> 20260720.247.2)
 ubuntu-22.04 is fully unsupported on 2027-04-17; brownouts begin 2027-03-23 (source: actions/runner-images#14254)
-255 days left (230 until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254
+255 days left (230 days until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254
 brownout windows (14:00-00:00 UTC): 2027-03-23, 2027-03-30, 2027-04-06, 2027-04-13
 announced migration targets: ubuntu-24.04, ubuntu-26.04, ubuntu-latest
 
diff --git a/src/detect.mjs b/src/detect.mjs
index 2e7aeba..eaff35d 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -467,9 +467,9 @@ export function jobMatcher(here, sites = []) {
  * are needed to place the running job: a job id is unique within a file, not
  * across a repository, so the file has to decide when two files use the same id.
  *
- * `scoped` is whether a running job was identified at all; without one every
- * site in the repository is in scope and the caller has to decide how much that
- * is worth. `placed` is the stronger claim that the job id picked out one job.
+ * Without a running job every site in the repository is in scope, and the
+ * caller has to decide how much that is worth. `placed` is the stronger claim
+ * that the job id picked out one job.
  * `direct` is a plain `runs-on: <label>`, `asked` includes reaching the label
  * through a matrix, and `rival` is another site naming `observed`, which the
  * runner is as likely to be serving as the floating one. `named` says that
@@ -495,7 +495,6 @@ export function labelOwnership({ label, observed = null, sites = [], others = []
     .filter((site) => inScope(site))
     .every((site) => asking.has(site.file));
   return {
-    scoped: Boolean(here),
     placed: pinned,
     direct: mine.some((site) => !site.viaMatrix),
     asked: mine.length > 0,
diff --git a/src/report.mjs b/src/report.mjs
index ab9c863..300bf09 100644
--- a/src/report.mjs
+++ b/src/report.mjs
@@ -74,7 +74,7 @@ export function deadlineLines(label, now = new Date()) {
     left === null
       ? null
       : left > 0
-        ? `${plural(left, 'day')} left${untilBrownout !== null && untilBrownout > 0 ? ` (${untilBrownout} until the first brownout)` : ''}`
+        ? `${plural(left, 'day')} left${untilBrownout !== null && untilBrownout > 0 ? ` (${plural(untilBrownout, 'day')} until the first brownout)` : ''}`
         : `retired ${plural(Math.abs(left), 'day')} ago`;
   if (countdownLine) {
     lines.push(`${countdownLine} — deprecation began ${dl.deprecationStart}; see ${dl.source}`);
@@ -469,9 +469,9 @@ export function migrationReport(surveys) {
 
 /**
  * `::notice`/`::warning`/`::error` per `runs-on:` site, so the message lands on
- * the line that owns the floating label. A survey with no site on disk (guard
- * reading the label from ImageOS with no workflow checkout) still gets one
- * step-level annotation rather than none.
+ * the line that owns the floating label. A survey built without a scan behind
+ * it has no line to point at and gets one step-level annotation instead; in
+ * `guard` that cannot happen, since the scan is what finds the label at all.
  */
 export function migrationAnnotations(surveys) {
   return surveys.flatMap((s) => {
diff --git a/test/plan.test.mjs b/test/plan.test.mjs
index 4be246d..92ce750 100644
--- a/test/plan.test.mjs
+++ b/test/plan.test.mjs
@@ -32,7 +32,7 @@ test('golden: ubuntu-22.04 -> ubuntu-24.04 for a python/cmake/clang workflow', a
   );
   assert.equal(
     lines[2],
-    '255 days left (230 until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254',
+    '255 days left (230 days until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254',
   );
 
   const rows = lines.filter((l) => /^(Python|Clang|CMake|Node\.js|Git|Go) /.test(l));

From 83ac2321745bdd416e018ae8f7a5c0052ab0cb3d Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 20:32:14 +0800
Subject: [PATCH 41/44] A run-name or an input description is prose, not a
 runner

---
 CHANGELOG.md         |  6 ++++++
 src/detect.mjs       |  8 ++++----
 test/detect.test.mjs | 31 +++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6b7c3d..eba2554 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -262,6 +262,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   every key is a dimension the job varies over, and the prose keys only hold
   prose outside it.
 
+- A workflow title mentioning a label was read as a runner the workflow asks
+  for. `run-name: nightly build on ubuntu-22.04` annotated the title line with a
+  retirement `::error` for an image the file never uses, as did an input's
+  `description:`. Both are prose keys now, alongside `run`, `name` and `if`.
+  This one predates 1.4.0: the unfiltered scan read them the same way.
+
 - A label written under a key named `name`, `run` or `if` was dropped even when
   that key held a map rather than prose. 1.4.0 taught the matrix fallback to skip
   the keys that hold shell and titles, and an empty one swallowed everything
diff --git a/src/detect.mjs b/src/detect.mjs
index eaff35d..16b627b 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -217,11 +217,11 @@ function scanRunsOn(lines) {
  * `${{ env.RUNNER }}` all resolve to values written somewhere above.
  *
  * Broad, but not everything. Comments, block scalars and the keys that hold
- * prose or shell rather than a value (`run:`, `name:`, `if:`) are skipped: a
- * label named there is not a runner the workflow asks for, and an annotation
- * has to land on a line someone can act on.
+ * prose or shell rather than a value (`run:`, `name:`, `run-name:`, `if:`,
+ * `description:`) are skipped: a label named there is not a runner the workflow
+ * asks for, and an annotation has to land on a line someone can act on.
  */
-const PROSE_KEYS = new Set(['run', 'name', 'if']);
+const PROSE_KEYS = new Set(['run', 'name', 'run-name', 'if', 'description']);
 
 /**
  * Whether the lines under an empty prose key are its body rather than a map.
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 8a17ba1..7844377 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -375,6 +375,37 @@ test('a label written in a step name or a condition is not a runner', () => {
   assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
 });
 
+test('a run-name is a title, not a runner the workflow asks for', () => {
+  const y = [
+    'run-name: nightly build on ubuntu-22.04 by ${{ github.actor }}',
+    'jobs:',
+    '  a:',
+    '    strategy:',
+    '      matrix:',
+    '        os: [ubuntu-24.04]',
+    '    runs-on: ${{ matrix.os }}',
+    '    steps:',
+    "      - run: make",
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
+  assert.deepEqual(extractFloatingSites(y), []);
+});
+
+test('an input description is prose too', () => {
+  const y = [
+    'on:',
+    '  workflow_call:',
+    '    inputs:',
+    '      runner:',
+    '        description: which runner to use, e.g. ubuntu-22.04',
+    '        default: ubuntu-24.04',
+    'jobs:',
+    '  a:',
+    '    runs-on: ${{ inputs.runner }}',
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
+});
+
 test('a matrix dimension named after a prose key is still values', () => {
   // `name` is a step title under `steps:` and a matrix axis under `matrix:`.
   const y = [

From 118abf32882039d83d140861ff597438cfab987d Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 20:47:35 +0800
Subject: [PATCH 42/44] Only strategy.matrix is a matrix, and one missing
 directory is one notice

---
 CHANGELOG.md            |  7 +++++++
 src/cli.mjs             | 12 +++++++++---
 src/detect.mjs          |  9 ++++++++-
 test/detect.test.mjs    | 12 ++++++++++++
 test/migration.test.mjs | 11 +++++++++++
 5 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eba2554..91a363e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -262,6 +262,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   every key is a dimension the job varies over, and the prose keys only hold
   prose outside it.
 
+- A job called `matrix` turned off the prose keys for its whole body, since the
+  scan matched the key name anywhere. Only `strategy.matrix` is a matrix now, so
+  a step title in that job is prose like any other.
+
+- Running both lint lanes with no workflow directory reported the one missing
+  directory twice. The scan is memoized for the run, and the notice is too.
+
 - A workflow title mentioning a label was read as a runner the workflow asks
   for. `run-name: nightly build on ubuntu-22.04` annotated the title line with a
   retirement `::error` for an image the file never uses, as did an input's
diff --git a/src/cli.mjs b/src/cli.mjs
index 360dfc7..f883220 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -311,9 +311,15 @@ function laneDocument({ runners = null, retirement = null, migration = null }) {
 async function scanForLane(scan, io, nothingToCheck) {
   const scanned = await scan();
   if (!scanned.missing) return scanned;
-  const msg = `No workflow directory at ${scanned.dir} — ${nothingToCheck}.`;
-  out(io.stdout, notice(msg));
-  out(io.stdout, msg);
+  // The scan is memoized for the run, so the second lane to ask about the same
+  // missing directory carries the first one's mark and says nothing. One
+  // condition, one notice.
+  if (!scanned.said) {
+    scanned.said = true;
+    const msg = `No workflow directory at ${scanned.dir} — ${nothingToCheck}.`;
+    out(io.stdout, notice(msg));
+    out(io.stdout, msg);
+  }
   return null;
 }
 
diff --git a/src/detect.mjs b/src/detect.mjs
index 16b627b..2fa5b53 100644
--- a/src/detect.mjs
+++ b/src/detect.mjs
@@ -242,6 +242,7 @@ function matrixLabels(lines) {
   const found = [];
   let scalar = null;
   let matrixAt = null;
+  let strategyAt = null;
   for (let i = 0; i < lines.length; i++) {
     const text = stripComment(lines[i]);
     if (scalar !== null) {
@@ -264,8 +265,14 @@ function matrixLabels(lines) {
       // Under `matrix:` every key is a dimension the job varies over, so a
       // `matrix.name` of image labels is values, not a step title.
       if (matrixAt !== null && key[1].length <= matrixAt) matrixAt = null;
+      if (strategyAt !== null && key[1].length <= strategyAt) strategyAt = null;
       const prose = matrixAt === null && PROSE_KEYS.has(name);
-      if (name === 'matrix') matrixAt = key[1].length;
+      // Only `strategy.matrix` is one. A job may be called `matrix`, and its
+      // steps still have titles.
+      if (name === 'matrix' && strategyAt !== null && key[1].length > strategyAt) {
+        matrixAt = key[1].length;
+      }
+      if (name === 'strategy') strategyAt = key[1].length;
       if (/^[|>]/.test(value) || (prose && (value || foldsOver(lines, i, owns)))) {
         scalar = owns;
         continue;
diff --git a/test/detect.test.mjs b/test/detect.test.mjs
index 7844377..bf38b03 100644
--- a/test/detect.test.mjs
+++ b/test/detect.test.mjs
@@ -375,6 +375,18 @@ test('a label written in a step name or a condition is not a runner', () => {
   assert.deepEqual(extractLabels(y), ['ubuntu-24.04']);
 });
 
+test('a job called matrix is not a matrix block', () => {
+  const y = [
+    'jobs:',
+    '  matrix:',
+    '    runs-on: ${{ inputs.runner }}',
+    '    steps:',
+    '      - name: drop macos-14 from the support table',
+    '        run: make',
+  ].join(String.fromCharCode(10));
+  assert.deepEqual(extractLabels(y), [], 'the step title is prose in any job');
+});
+
 test('a run-name is a title, not a runner the workflow asks for', () => {
   const y = [
     'run-name: nightly build on ubuntu-22.04 by ${{ github.actor }}',
diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index eb32807..c6a8595 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -548,6 +548,17 @@ test('a missing workflow directory is a notice, not an error', async () => {
   assert.match(r.stdout, /no floating labels to check for migration/);
 });
 
+test('both lint lanes with no workflow directory say so once', async () => {
+  const r = await guard({
+    tools: 'node',
+    'fail-on-migration': '30',
+    'fail-on-retirement': '60',
+    workflows: path.join(FIXTURES, 'definitely-not-here'),
+  });
+  assert.equal(r.code, EXIT_OK);
+  assert.equal(r.stdout.match(/No workflow directory/g).length, 2, 'the annotation and its log line');
+});
+
 test('a bad --fail-on-migration value is a usage error', async () => {
   for (const bad of ['soon', '-5', '2.5', '']) {
     const r = await guard({ tools: 'node', 'fail-on-migration': bad });

From a6f73864e6d8b734385d43311ab51e98621859ff Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 21:07:10 +0800
Subject: [PATCH 43/44] Refresh the headline plan example, which predates the
 image-header rows

---
 README.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3176854..76665fd 100644
--- a/README.md
+++ b/README.md
@@ -24,19 +24,24 @@ brownouts starting 2027-03-23](https://github.com/actions/runner-images/issues/1
 
 ```
 $ npx runner-drift plan --from ubuntu-22.04 --to ubuntu-24.04
-ubuntu-22.04 -> ubuntu-24.04 (images 20260720.234.2 -> 20260720.247.2)
+ubuntu-22.04 -> ubuntu-24.04 (images 20260907.292.1 -> 20260907.300.1)
 ubuntu-22.04 is fully unsupported on 2027-04-17; brownouts begin 2027-03-23 (source: actions/runner-images#14254)
-255 days left (230 days until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254
+209 days left (184 days until the first brownout) — deprecation began 2026-09-17; see https://github.com/actions/runner-images/issues/14254
 brownout windows (14:00-00:00 UTC): 2027-03-23, 2027-03-30, 2027-04-06, 2027-04-13
 announced migration targets: ubuntu-24.04, ubuntu-26.04, ubuntu-latest
 
+OS 22.04.5 LTS -> 24.04.5 LTS  MAJOR
+Kernel 6.8.0-1064-azure -> 6.17.0-1022-azure  MINOR
+Systemd 249.11-0ubuntu3.22 -> 255.4-1ubuntu8.17  MAJOR
+
 Clang 13.0.1,14.0.0,15.0.7 -> 16.0.6,17.0.6,18.1.3  REMOVED: 13.0.1, 14.0.0, 15.0.7 / ADDED: 16.0.6, 17.0.6, 18.1.3
 Python 3.10.12 -> 3.12.3  MINOR
 
 2 of 3 detected tool(s) change; 1 unchanged (not shown)
 ```
 
-That is real output against the live manifests. Note what is **not** there: CMake.
+That is real output against the live manifests, run on 2026-09-20. Note what is
+**not** there: CMake.
 It is 3.31.6 on both images, so it is suppressed — the report is only the rows that
 affect you, picked by scanning your own workflows for the tools your steps invoke.
 
@@ -92,7 +97,7 @@ npm i -g runner-drift          # or globally
 ```bash
 $ runner-drift init
 Scanned 2 workflow file(s) in .github/workflows
-Runner label: ubuntu-22.04 (image 20260720.234.2, 22.04.5 LTS)
+Runner label: ubuntu-22.04 (image 20260907.292.1, 22.04.5 LTS)
 Locked 3 tool(s): CMake, Clang, Python
 Wrote runner-lock.json
 Heads up: ubuntu-22.04 is fully unsupported on 2027-04-17 (https://github.com/actions/runner-images/issues/14254)

From bb0c5316805659bf1448257ce49d27d51fa63a1e Mon Sep 17 00:00:00 2001
From: Booyaka101 <cbosch101@gmail.com>
Date: Sun, 20 Sep 2026 21:18:16 +0800
Subject: [PATCH 44/44] Derive the locked Node version instead of pinning one
 CI ships

guardAcrossTheMove locked Node.js at 22.23.2 and every assertion under it
depended on the machine disagreeing. setup-node's node-version: '22' now
resolves to exactly 22.23.2, so on all three CI legs the probe matched the
lock, there was no drift, and the seven tests about how drift is attributed
passed or failed for reasons that had nothing to do with attribution.

Derive it from process.versions.node one major down, the way the PATCH-only
test next door already derives its version. The probe reports the interpreter
running the test and engines floors this package at 22, so the two can never
meet again.

Reproduced locally by pinning LOCKED_NODE to process.versions.node: the same
seven tests fail, 395/402, which is what CI printed.
---
 test/migration.test.mjs | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/test/migration.test.mjs b/test/migration.test.mjs
index c6a8595..ae9d92b 100644
--- a/test/migration.test.mjs
+++ b/test/migration.test.mjs
@@ -1006,6 +1006,12 @@ test('a job id the calling workflow does not use is looked up in the callee', ()
   );
 });
 
+// The probe reads the interpreter running this test, so a literal version in the
+// lock below is drift only until a runner ships that exact Node. Derive one the
+// probe cannot report: `engines` floors this package at 22.
+const LOCKED_NODE = `${Number(process.versions.node.split('.')[0]) - 1}.0.0`;
+const LOCKED_NODE_DRIFT = new RegExp(`Node\\.js ${LOCKED_NODE.replaceAll('.', String.raw`\.`)} -> `);
+
 /**
  * Guard against a lock recorded on the pre-migration image, with the runner
  * serving the post-migration one: the drift a real user sees mid-rollout.
@@ -1019,7 +1025,7 @@ async function guardAcrossTheMove(opts, now, locked = { label: 'ubuntu-24.04', i
       {
         ...locked,
         imageVersion: IMAGE,
-        tools: { 'Node.js': { versions: ['22.23.2'], source: 'probe' } },
+        tools: { 'Node.js': { versions: [LOCKED_NODE], source: 'probe' } },
       },
       lockFile,
     );
@@ -1042,7 +1048,7 @@ test('drift caused by the migration is named as such, not left unexplained', asy
     /Explained by the scheduled ubuntu-latest migration ubuntu-24\.04 -> ubuntu-26\.04/,
   );
   assert.match(r.stdout, /\(2026-10-19 to 2026-11-19\)/);
-  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /);
+  assert.match(r.stdout, LOCKED_NODE_DRIFT);
   assert.equal(r.stderr, '');
 });
 
@@ -1118,7 +1124,7 @@ test('a matrix leg pinned to the new image is not the migration arriving', async
     DURING,
   );
   assert.ok(!r.stdout.includes('Explained by'), 'the pinned leg asks for 26.04 itself');
-  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+  assert.match(r.stdout, LOCKED_NODE_DRIFT, 'the drift is still reported');
 });
 
 test('the migration lane diffs the tools the lock watches', async () => {
@@ -1149,7 +1155,7 @@ test('a repo that pins its runners is not told GitHub moved it', async () => {
   // ubuntu-latest: someone bumped the pin by hand and owns the upgrade.
   const r = await guardAcrossTheMove({ workflows: path.join(FIXTURES, 'workflows') }, DURING);
   assert.ok(!r.stdout.includes('Explained by'), 'no floating label, no migration to blame');
-  assert.match(r.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+  assert.match(r.stdout, LOCKED_NODE_DRIFT, 'the drift is still reported');
 });
 
 test('with no job id, a sibling pinned to the new image withholds the explanation', async () => {
@@ -1158,7 +1164,7 @@ test('with no job id, a sibling pinned to the new image withholds the explanatio
   const where = { workflows: path.join(FIXTURES, 'workflows-pinned-sibling') };
   const blind = await guardAcrossTheMove(where, DURING);
   assert.ok(!blind.stdout.includes('Explained by'), 'either job explains this image');
-  assert.match(blind.stdout, /Node\.js 22\.23\.2 -> /, 'the drift is still reported');
+  assert.match(blind.stdout, LOCKED_NODE_DRIFT, 'the drift is still reported');
 
   const mine = await guardAcrossTheMove({ ...where, env: inJob('build') }, DURING);
   assert.match(mine.stdout, /Explained by the scheduled ubuntu-latest migration/);