validate-actions-lock prescribes a cure that can re-legitimise a blocked action version

[hyperpolymath]

The defect

When a workflow uses: ref is absent from actions.lock, the gate emits:

[validate-actions-lock] ERROR: not in actions.lock: github/codeql-action/upload-sarif@1c5b675...
    Regenerate with the LOCKFILE ONLY, and verify the *.yml diff is empty:
      gh actions-lock <workflow paths> --no-migrate-local-actions --no-narrow

A lock/workflow drift has two possible stale sides, and this message picks one blindly. It always assumes the workflow is right and the lock is behind.

Hit live today (#977 → #978). The lock correctly carried codeql-action@b96794f (v4.38.0); three workflows had been reverted to 1c5b675 (v4.38.1) — a version under an explicit estate hold because it startup-kills workflows (nexia-list#100). Following the prescribed cure verbatim would have written 1c5b675 back into the lockfile, re-legitimising the exact version the #973 incident fix was escaping, and converted a loud gate failure into a silent estate-wide outage.

The correct cure there was the opposite: update the workflows to the SHA the lock already held, and leave actions.lock untouched.

Why it matters beyond this instance

• The gate blocks commits repo-wide until resolved, so there is pressure to apply the suggested command quickly and without analysis.
• The suggested command is the plausible-looking one; the failure mode is silent.
• This is the same class as actions-lock gate's remedy text names a repo-relative path that exists in no consumer repo #930 (a gate naming a repo-relative path that does not resolve in consumers) and Dependabot bumps uses: without regenerating actions.lock — every remediated repo is newly exposed #670 (Dependabot bumping uses: without regenerating the lock).

Acceptance criteria

1. On a missing-ref error, the gate reports which side is stale rather than assuming — e.g. when the lockfile already holds a different SHA for the same owner/repo, say so explicitly and name both SHAs.
2. In that case the message must not recommend regeneration as the first cure; it should recommend reconciling the workflow ref to the locked SHA, or state that a deliberate upgrade requires changing both.
3. A regression test covering the two-sided case: lock holds SHA-A for owner/repo, workflow references SHA-B → the gate's output names both SHAs and does not prescribe bare regeneration. Mutating the message back to the current text must fail that test.
4. No change to the single-sided case (genuinely new action added, lock simply behind), which keeps the existing guidance.

Related

• fix(ci): re-pin codeql-action to v4.38.0 SHA (#977 reverted the #973 incident fix) #978 — the fix for the live instance
• fix(ci): codeql-action v4.38.1 -> v4.38.0 SHA pin + dependabot hold (estate-wide startup_failure) #973, chore(deps): bump the actions group with 3 updates #977 — the incident and its silent revert
• actions-lock gate's remedy text names a repo-relative path that exists in no consumer repo #930 — gate error text naming a path that does not resolve in consumers
• Dependabot bumps uses: without regenerating actions.lock — every remediated repo is newly exposed #670 — Dependabot bumping uses: without regenerating the lock
• nexia-list#100, policy: Guix primary + sealed-container escape; retire Nix-mirror-everywhere #101, docs(pkg): canonical Nix-retirement inventory worklist (Wave 0) #104 — the v4.38.1 startup failure and the ignore-bypass history

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo