Problem

Every route through the edge middleware returned a 500 while routes outside its matcher stayed healthy. The Sentry build plugin auto-injects a middleware wrapper into the built edge bundle, but the site's webpack config deliberately aliases the Sentry package away in that bundle, so the injected call was undefined at runtime. That path only runs when the Sentry token is present at build time: true on the host, never locally.

Constraint

The failing code path was structurally invisible to local builds. Recovery had to be safe to run from an agent's own shell, which the first attempt, a kill by process name, had taken down with it. And the fix had to be proven, not asserted.

Decision

Do not write a postmortem nobody reruns. Each gap became a command: a version endpoint that returns the deployed sha and presence booleans for every build-time variable, excluded from the middleware matcher so it answers while the middleware is crashing; a declarative probe matrix with disciplined exit codes; a parity build that fills the env manifest with safe dummies so the host-only path runs locally, boots, and probes; PID-file server lifecycle; and a per-PR workflow that runs the parity build and probe with no secrets.

• A postmortem document

  Nobody reruns a document. Each gap is a command in the repository, and the class of failure has a CI gate.

• Kill the server by process name

  It matched the agent's own shell and killed the operator mid-incident. Servers start in their own process group under a PID file and stop by signaling exactly that group.

What shipped

The version endpoint with its matcher-exclusion test, the probe matrix, the parity build, PID-file lifecycle, and the per-PR guardrail, plus the proof: on a pre-fix checkout the gate reproduces the exact 500; on main it is green.

What I'd do differently

The guardrail then failed for its own reasons: the parity build ran out of memory on the CI runner and took six follow-up merges to settle (a heap raise, a warm cache, path gating, serialized static generation, a smaller heap ceiling, no source maps). A gate that is red for the runner's reasons trains people to ignore it, so none of those fixes was optional.

If you ask me about this

Why booleans only in the version endpoint?

A diagnostic that prints a secret is a leak with a nicer name. Presence booleans localize a build-configuration bug in seconds without exposing a value, and the generator is fail-open so a diagnostic can never fail a deploy.

How do you know the gate would have caught it?

I checked out a pre-fix commit in a throwaway worktree and ran the parity build. Same command, same matrix, the exact middleware 500. On main, green.

Evidence

1. fix(auth): stop edge middleware from 500ing the whole site (MIDDLEWARE_INVOCATION_FAILED)

   #1011 · 2026-06-11 · bugfix

2. 🚨 hotfix: prod outage root cause — Sentry middleware wrapper (MIDDLEWARE_INVOCATION_FAILED)

   #1015 · 2026-06-11 · feature

3. feat(ops): ops harness — version endpoint, prod-parity build, probe, serve/stop, CI guardrail

   #1016 · 2026-06-11 · feature

4. ci: raise prod-parity build heap to 6 GB to stop build-and-probe OOMs

   #1460 · 2026-06-20 · infra

5. ci: fix the prod-parity OOM by serializing static generation under CI

   #2255 · 2026-07-27 · bugfix

6. ci(prod-parity): drop source-map work in parity CI so the build fits the runner

   #2269 · 2026-07-28 · infra