fix(ci): let an administrator merge their own green PR

`required_approvals: 1` on `main` was a lock-out, not a protection. Gitea
refuses to let a PR's author approve their own PR, and `jakman85` is the only
collaborator — so no account in existence could approve a PR the operator
opened, including the PR that would fix that. Measured 2026-10-01 on PR #35:
gate green in 1m41s, reviews `[]`, `required_approvals: 1`, unmergeable.

It was never the documented design either: `ci/approval-policy.sh`'s header and
`ci/gate.sh:194` both already describe the model as "required_approvals drops
to 0 and the GATE decides", and `require-gate.sh`'s own closing note named this
failure and prescribed this remedy. 2026-09-30's entry flagged the 1-vs-0
disagreement as unresolved; this settles it at 0.

Layer 1 — branch protection. required_approvals 1 -> 0 in the declaration, plus
infra/gitea/allow-admin-self-merge.sh to apply it live (target read FROM the
declaration, so the script cannot drift from what the gate checks).
require-gate.sh moves to 0 too; left at 1 it would re-impose the lock-out on its
next run. The narrow choice is deliberate: the other way to unblock an owner is
block_admin_merge_override: false, which would re-open what
block-admin-override.sh was written to close (PRs #5-#9, zero approvals). This
drops the approval COUNT only — block_admin_merge_override and
enable_status_check stay true and are asserted after the PATCH, so a red gate
stays unmergeable by everyone, administrators included.

Layer 2 — ci/approval-policy.sh. Sensitive paths still need a non-author
approval the sole admin cannot get, so an administrator may waive it with an
`/approve-override <reason>` comment: directive must start a line, reason
mandatory, permission re-checked LIVE, invalidated by a new commit, and the
overrider + reason printed in the gate log and job summary. Candidate selection
is the pure, offline ci/approval-override.py (23 unit assertions, all passing);
authorisation stays in the fail-closed stage. Every new failure mode blocks.

The cost, stated not buried: for an administrator, "a change to the gate cannot
be gated by the gate" is now advisory rather than structural. Unavoidable with
one human; what is bought back is an attributed, commit-scoped record instead of
a silent bypass. And the uncomfortable part, accepted as an operator decision:
authorisation is by live permission alone, and the AGENT account `gitea-admin`
also holds `owner` — so an agent can clear its own PR this way. Documented in
approval-policy.json, the stage header, and CLAUDE.md (which tells agents not
to). Narrowing needs no code change: add `override_admins` and the stage already
requires membership.

Adjacent fix, in scope because `make -C ci test` is the only runner for the
suite added here: ci/tests/gate-decision.test.sh hand-maintained a stub list
that "must name EVERY stage gate.sh runs" and omitted `approval-policy` (added
to gate.sh by PR #17), so run_stage hit exit 127 and 15 of 50 assertions failed.
Verified pre-existing on pristine origin/main @ 0c7e8dd. The list is now derived
from gate.sh's own run_stage lines, so the omission cannot recur; the suite goes
15-failed -> 50 passing and `make -C ci test` goes FAILED -> all suites passed.

Toolbox gate: rc 3 UNDETERMINED — every stage green except `gitea-settings`
(no SETTINGS_API_TOKEN locally) and `conformance` (no cluster). NOT a green run.

The live rule is UNCHANGED and still reads 1 — mutating it is an operator
action. Until allow-admin-self-merge.sh is run, ci/gitea-settings.sh will
correctly report DRIFT and this PR will be red.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

CLAUDE.md

@@ -36,6 +36,28 @@ sensitive path, so the policy cannot be widened or narrowed without a human.
 
 That stage is **fail-closed** — if it cannot evaluate, it blocks. Unlike `gitea-settings`, where a
 missing credential is a lock-out, here a skip would be a bypass.
+
+**The administrator override (2026-10-01).** The rule above was unsatisfiable for the one human
+who runs this repo: Gitea refuses to let an author approve their own PR, and `jakman85` is the
+only collaborator — so a sensitive-path PR the operator opened could never be merged, *including
+the PR that would fix that.* An administrator may therefore waive the review by commenting on
+the PR:
+
+    /approve-override <reason>
+
+The directive must **start a line**, the **reason is mandatory**, the commenter's `admin`/`owner`
+permission is re-checked **live** when the gate runs, and the comment must be **newer than the
+head commit** — push again and you must override again. The overrider, the timestamp and the
+reason are printed in the gate log and the job summary. For an administrator, "a change to the
+gate cannot be gated by the gate" is therefore **advisory, not structural**; what is kept is an
+attributed record of each waiver. Note that the agent account `gitea-admin` also holds `owner`
+here, so an agent *can* clear this on its own PR — **do not**: posting that directive to unblock
+your own agent work is exactly the self-approval the stage exists to prevent. Get the operator
+to post it, or move the change out of the sensitive paths.
+
+**`required_approvals` on `main` is `0`**, not 1 — the gate is the approver. That drops the
+approval *count* only: `block_admin_merge_override` and `enable_status_check` both remain `true`,
+so **a red gate is unmergeable by everyone, administrators included.**
 - **Do not `kubectl apply` / `edit` / `patch` a durable change.** Flux reconciles `main`;
   anything applied by hand is drift that the next reconcile reverts or, worse, adopts.
 
@@ -53,12 +75,19 @@ Verified against the live Gitea on 2026-09-29:
 | `main` protected, direct push rejected | ✅ `protected: true`, `user_can_push: false` — **verified by a real rejected push**, not by the API's word |
 | PR blocked until the gate passes | ✅ `enable_status_check: true`, context `gate / gate (pull_request)` |
 | Gate runs on every PR | ✅ runner `incluster-dind` online; ~1m35s |
-| Approval required before merge | ✅ `required_approvals: 1` |
+| Gate cannot be overridden, by anyone | ✅ `block_admin_merge_override: true` |
+| Human approval required before merge | ⬜ **No — `required_approvals: 0` since 2026-10-01.** The gate is the approver; sensitive paths are gated by `ci/approval-policy.sh` instead. See §1 |
 
-All four were FALSE as recently as 2026-09-29, while this repo's own log asserted they were
+The first three were FALSE as recently as 2026-09-29, while this repo's own log asserted they were
 true. They are true now because each was measured, and the push rejection was provoked rather
 than assumed. **Re-measure before relying on any of them** — see §2b.
 
+The fourth row deliberately changed on 2026-10-01. `required_approvals: 1` was a **lock-out**, not
+a protection: with a single collaborator and Gitea refusing author self-approval, nothing could
+satisfy it (measured on PR #35 — green gate, zero reviews, unmergeable). It also contradicted the
+model already written into `ci/approval-policy.sh` and `ci/gate.sh`. Rationale and the live-change
+script: `infra/gitea/allow-admin-self-merge.sh`.
+
 Still not covered: `vars.CLUSTER_AVAILABLE` is unset, so **L2/L3 conformance does not run in
 CI**. A green PR therefore proves the L0/L1 offline subset, not runtime behaviour.
 

apps/wave-0/jackett.yaml

@@ -100,6 +100,7 @@ spec:
         - --allowed-group=platform-admins
         - --skip-provider-button=true
         - --redirect-url=https://jackett.${BASE_DOMAIN}/oauth2/callback
+        - --api-route=^/api/
         - --cookie-name=_oauth2_proxy_jackett
         - --cookie-domain=jackett.${BASE_DOMAIN}
         - --whitelist-domain=.${BASE_DOMAIN}

apps/wave-1/radarr.yaml

@@ -153,6 +153,8 @@ spec:
         - --allowed-group=platform-admins
         - --skip-provider-button=true
         - --redirect-url=https://radarr.${BASE_DOMAIN}/oauth2/callback
+        - --api-route=^/api/
+        - --api-route=^/signalr/
         - --cookie-name=_oauth2_proxy_radarr
         - --cookie-domain=radarr.${BASE_DOMAIN}
         - --whitelist-domain=.${BASE_DOMAIN}

catalog/jackett.yaml

@@ -51,6 +51,23 @@ auth:
     # This grants no real privilege: platform-admins already maps to cluster-admin via
     # k8s-oidc-rbac.yaml (oidc:platform-admins), so a member can already exec into these pods.
     - platform-admins           # operators of these services must not be locked out of them
+  # Answer Jackett's OWN API with 401 instead of a 302 to Keycloak (schema 1.9.0; renders
+  # --api-route, singular and repeatable, onto the oauth2-proxy sidecar).
+  #
+  # MEASURED on this pod's access log, 2026-09-30: on /api/ paths, 33 x 302 against 2 x 401 —
+  # and 4 of 6 POSTs were answered BY THE PROXY and never reached Jackett (access-log upstream
+  # field `-`, not `/`), including both `/api/v2.0/server/update` calls. Jackett's jQuery does
+  # not send the exact `Accept: application/json` oauth2-proxy's AJAX guard requires, so the
+  # 302 was followed invisibly, satisfied silently by the live Keycloak SSO session, and
+  # resolved 200 carrying the dashboard's HTML where the JavaScript expected JSON. A browser
+  # following a 302 also re-issues a POST as a GET and DROPS THE BODY, which is why "adding an
+  # indexer silently does nothing" was the user-visible symptom and nothing logged a failure.
+  #
+  # SCOPE: `/api/` only. Jackett serves its UI at /UI/ and its static assets elsewhere, and a
+  # browser never NAVIGATES to /api/ — so a plain page load is still 302'd into a silent SSO
+  # sign-in, which is the behaviour that must not change.
+  apiRoutes:
+    - ^/api/
 update:
   channel: stable               # R-UPD-01
   range: ">=0.22.0"             # stay on the Jackett 0.22.x stable line

catalog/pihole.yaml

@@ -107,6 +107,13 @@ auth:
   mode: forward-auth          # oauth2-proxy -> Keycloak; bare UI, no native OIDC (docs/15; R-IDP-02)
   groups:
     - platform-admins         # sensitive admin UI: authenticated AND in group (R-IDP-06)
+  # NO `apiRoutes` HERE, DELIBERATELY. PiHole's admin UI serves no /api/ path, so the `^/api/`
+  # that jackett and radarr need would match nothing on a good day — and a BROADER guess would
+  # answer PiHole's own page loads with 401, leaving a logged-out operator on a bare error page
+  # with no sign-in offered. This app is the reason auth.apiRoutes is per-service (schema 1.9.0)
+  # rather than a renderer constant: the measurement that justifies the flag on two apps is
+  # evidence about those two apps. Its oauth2-proxy log holds 0 unauthenticated requests across
+  # the current pod's whole 23h lifetime (measured 2026-10-01), so there is nothing to act on.
 update:
   channel: stable             # R-UPD-01
   range: ">=2024.0.0"

catalog/qbittorrent.yaml

@@ -448,6 +448,12 @@ auth:
     # via k8s-oidc-rbac.yaml). Without it, an empty media-users locks every operator out with an
     # immediate 403 at the oauth2-proxy callback — observed on prod 2026-09-12.
     - platform-admins           # operators of these services must not be locked out of them
+  # NO `apiRoutes` HERE: UNMEASURED, not cleared. qBittorrent's WebUI drives everything through
+  # /api/v2/, so it is plausibly affected in the same way jackett is — but plausibility is what
+  # put a renderer constant on the table in the first place. MEASURED 2026-10-01 on the live pod
+  # (qbittorrent-5547bdb9bd-zq557, 0 restarts, 23h): 13,649 log lines, ZERO unauthenticated
+  # requests, nothing but health probes. No traffic means no evidence either way. Add `^/api/`
+  # when someone opens the WebUI and records the 302/401 split, as was done for jackett.
 update:
   channel: stable               # R-UPD-01
   range: ">=5.0.0 <6.0.0"       # stay on the qBittorrent 5.x stable line

catalog/radarr.yaml

@@ -112,6 +112,32 @@ auth:
     # via k8s-oidc-rbac.yaml). Without it, an empty media-users locks every operator out with an
     # immediate 403 at the oauth2-proxy callback — observed on prod 2026-09-12.
     - platform-admins           # operators of these services must not be locked out of them
+  # Answer Radarr's machine endpoints with 401 instead of a 302 to Keycloak (schema 1.9.0;
+  # renders --api-route, singular and repeatable, onto the oauth2-proxy sidecar).
+  #
+  # `^/signalr/` — MEASURED ON THE LIVE POD, 2026-10-01, 23h after the cookie fix deployed
+  # (radarr-7d55cbffb9-42hmh, 0 restarts): 232 unauthenticated requests in the pod's whole
+  # lifetime and ALL 232 are the same call — `POST /signalr/messages/negotiate` from a browser
+  # UA, answered 302 by the proxy with upstream `-`, i.e. Radarr never saw one of them. That is
+  # a left-open tab whose session the cookie rename orphaned, polling SignalR forever, silently
+  # redirected every time and NEVER re-prompting the operator. It is the reported symptom
+  # ("reloading never fixes it and I am never re-prompted") still running in production on a
+  # service nobody was watching. With 401 the UI's connection breaks LOUDLY, the operator
+  # reloads, and `/` is outside both regexes so the reload signs them back in.
+  #
+  # `^/api/` — measured on radarr, but on the PRE-FIX pod and NOT by me: the 2026-09-30
+  # diagnosis (decisions/2026-09-30-jackett-oauth2-proxy-session.md) recorded radarr's 156
+  # unauthenticated requests as `/api/v3/command` (62), `/api/v3/queue/details` (46) and
+  # `/signalr/messages/negotiate` (43). The current pod has logged ZERO /api/ traffic, so I did
+  # not re-measure it; it is included because 108 of 156 measured rejections on this app were
+  # /api/v3 XHRs, which is this app's own evidence rather than an analogy to another app.
+  #
+  # SCOPE: both are JSON/RPC namespaces a browser never NAVIGATES to. Radarr's UI is served at
+  # `/` with assets under /Content/ and /MediaCover/, none of which match — so a plain page load
+  # is still 302'd into a silent SSO sign-in.
+  apiRoutes:
+    - ^/api/
+    - ^/signalr/
 update:
   channel: stable               # R-UPD-01
   range: ">=5.0.0 <6.0.0"       # stay on the Radarr v5 stable line

catalog/render.py

@@ -172,6 +172,45 @@ OAUTH2_PROXY_METRICS_PORT = 44180
 DRI_VOLUME_NAME = "dri"
 DRI_DEVICE_DIR = "/dev/dri"
 
+# --- API routes: 401 instead of 302, PER APP ------------------------------------------
+# oauth2-proxy answers an unauthenticated request with a 302 to Keycloak. Its built-in AJAX
+# guard would send a 401 instead, but it fires only on an EXACT `Accept: application/json`,
+# which these apps' JavaScript does not consistently send. So an unauthenticated XHR gets a
+# 302, the browser follows it INVISIBLY, the live Keycloak SSO session satisfies it silently,
+# and the call resolves 200 carrying the app's HTML where the JavaScript expected JSON — no
+# prompt, no console error, nothing logged as a failure. On a WRITE it is worse: a browser
+# following a 302 re-issues a POST as a GET and DROPS THE BODY, so the operator's change is
+# discarded and the UI reports success. MEASURED, twice:
+#   jackett  2026-09-30: 33 x 302 against 2 x 401 on /api/ paths, and 4 of 6 POSTs answered by
+#            the proxy and never reaching the app (access-log upstream field `-`, not `/`).
+#   radarr   2026-10-01, 23h after the cookie fix rolled: 232 x 302, EVERY ONE a
+#            `POST /signalr/messages/negotiate` from the operator's own browser, upstream `-`.
+#            A left-open tab whose cookie the rename orphaned, polling forever, silently
+#            redirected every time, NEVER re-prompting. That is the reported symptom
+#            ("reloading never fixes it and I am never re-prompted") still happening in
+#            production, on a service nobody was looking at.
+# `--api-route=<regex>` makes matching paths answer 401.
+#
+# WHY THIS IS NOT A RENDERER CONSTANT, AND MUST NEVER BECOME ONE. The path shape is a property
+# of the APP, not of the forward-auth pattern: radarr's broken path is `/signalr/`, jackett's is
+# `/api/`, and PIHOLE SERVES NO `/api/` AT ALL. One constant would apply one app's path shape to
+# five, and the failure mode of a wrong one is not "no improvement" but "this service is
+# permanently broken": a path a BROWSER NAVIGATES to, answered 401, shows a logged-out operator
+# a bare error page and never offers a sign-in. So the routes are declared per service in
+# `auth.apiRoutes` (schema 1.9.0) and rendered one `--api-route` per entry — the flag is
+# repeatable, and it is SINGULAR: `--api-routes` does not exist in v7.8.1 and the proxy refuses
+# to start with it (verified against the pinned binary's own --help, 2026-10-01:
+# `--api-route strings   return HTTP 401 instead of redirecting to authentication server...`).
+#
+# BREADTH RATCHET. Every entry must be anchored at `^/` and continue with literal path
+# characters. That rejects `^/`, `^/.*`, `.*`, an unanchored `/api/`, and any alternation — the
+# shapes that turn a page load into a 401. Alternation is refused rather than supported because
+# the flag is repeatable, so one regex per route costs nothing and stays readable. The same
+# pattern is in the schema (so ci/l0.sh's schema stage rejects it at the authoring surface) and
+# enforced HERE (so ci/render-golden.sh fails even if the schema stage is skipped) — a breadth
+# mistake must not need two independent gates to both be running.
+OAUTH2_API_ROUTE_PATTERN = re.compile(r"^\^/[A-Za-z0-9._~/-]+(\.\*|\$)?$")
+
 
 # =============================================================================
 # Defaults (renderer-contract.md "Default posture") — materialize BEFORE mapping.
@@ -197,6 +236,12 @@ def apply_defaults(sd: dict) -> dict:
     if "mode" not in auth:
         auth["mode"] = "forward-auth" if s["ingressRoutes"] else "none"
     auth.setdefault("groups", [])
+    # apiRoutes default posture is EMPTY, deliberately, and that is the whole point of the field
+    # (schema 1.9.0): an app gets --api-route only where someone MEASURED that it serves a machine
+    # API, so a newly-onboarded app renders no --api-route at all rather than inheriting another
+    # app's path shape. See OAUTH2_API_ROUTE_PATTERN above for why a default of `^/api/` would be
+    # wrong rather than merely generous.
+    auth.setdefault("apiRoutes", [])
     s["auth"] = auth
 
     update = dict(s.get("update") or {})
@@ -1054,7 +1099,12 @@ def _oauth2_sidecar_container(s: dict) -> dict:
 
     --cookie-name and --cookie-domain are DERIVED per app (see the block comment on those two
     args): every instance holds a different cookie-secret, so sharing one cookie name across the
-    zone makes the instances evict each other's sessions."""
+    zone makes the instances evict each other's sessions.
+
+    --api-route is DECLARED per app, from auth.apiRoutes, and is the one flag here that is
+    neither a constant nor derivable: it names the paths THIS app serves as a machine API, and
+    those differ per app (radarr `/signalr/`, jackett `/api/`, pihole none). An app that declares
+    none renders no --api-route at all."""
     route = s["ingressRoutes"][0]
     host = route["host"]
     upstream_port = route["port"]
@@ -1074,6 +1124,27 @@ def _oauth2_sidecar_container(s: dict) -> dict:
     args += [
         "--skip-provider-button=true",
         f"--redirect-url=https://{host}/oauth2/callback",
+    ]
+    # ── API ROUTES: 401 instead of 302, ON THIS APP'S OWN PATHS ONLY ───────────────────────
+    # One flag per declared route, in declared order. An app that declares NONE renders NO
+    # --api-route, which is the correct and common case — see OAUTH2_API_ROUTE_PATTERN above for
+    # the measurements, for why this cannot be a renderer constant, and for the breadth ratchet.
+    # Validated here as well as in the schema so a breadth mistake is caught by render-golden
+    # even on a run where the schema stage did not execute.
+    for route in s["auth"].get("apiRoutes", []):
+        if not OAUTH2_API_ROUTE_PATTERN.match(str(route)):
+            raise SystemExit(
+                f"render.py: {s['name']}: auth.apiRoutes entry {route!r} is not an anchored path "
+                f"regex. Each entry must start with '^/' and continue with literal path "
+                f"characters (e.g. '^/api/', '^/signalr/', '^/api/v3/.*'). Rejected shapes: '^/' "
+                f"and '^/.*' (match every page load), an unanchored '/api/' (matches mid-path), "
+                f"and alternation (the flag is repeatable — declare one entry per route). A "
+                f"too-broad --api-route answers a PAGE LOAD with 401, so a logged-out operator "
+                f"sees a bare error page and is never offered a sign-in: the service looks "
+                f"permanently broken rather than merely unauthenticated."
+            )
+        args.append(f"--api-route={route}")
+    args += [
         # ── COOKIE ISOLATION (fleet fix 2026-09-30; crafty's 2026-09-29 fix, generalized) ──────
         # EVERY oauth2-proxy on this platform — this sidecar, its four siblings, and the SHARED
         # forward-auth proxy (platform/oauth2-proxy) — is an INDEPENDENT instance holding its OWN
@@ -2666,15 +2737,27 @@ def _selftest() -> int:
             "auth": {"mode": "forward-auth", "groups": ["media-users"]},
         }
     )
-    fa_dep = next(d[1] for d in fa_docs if d[1]["kind"] == "Deployment")
+    fa_dep = next((d[1] for d in fa_docs if d[1]["kind"] == "Deployment"), None)
-    fa_containers = fa_dep["spec"]["template"]["spec"]["containers"]
+    check(fa_dep is not None,
+          "a forward-auth app rendered NO Deployment, so there is no pod to gate at all")
+    fa_containers = (((fa_dep or {}).get("spec") or {}).get("template") or {}) \
+        .get("spec", {}).get("containers") or []
     check(
         len(fa_containers) == 2
         and fa_containers[0]["name"] == "fa"
         and fa_containers[1]["name"] == "oauth2-proxy",
-        "forward-auth app must render the app container FIRST + an oauth2-proxy sidecar SECOND",
+        f"forward-auth app must render the app container FIRST + an oauth2-proxy sidecar SECOND; "
+        f"rendered {[c.get('name') for c in fa_containers]!r}",
     )
-    side = fa_containers[1]
+    # EVERY assertion below reads `side`, so an absent sidecar must NOT be allowed to raise here.
+    # The whole point of the None-tolerant lookups in this block is that a missing sidecar (or a
+    # missing flag on it) reports as NAMED ASSERTIONS rather than as a traceback: an exception
+    # escaping _selftest() exits non-zero with the right verdict and ZERO diagnostics, and it
+    # hides every other assertion the same mutation broke. Measured by Desmond Oyelaran while
+    # wiring this selftest into the render-golden stage: deleting the --cookie-name emission gave
+    # rc 1 via an uncaught StopIteration and printed not one `SELFTEST FAIL:` line. Provoked
+    # again here with the sidecar removed entirely, which raised IndexError at this line.
+    side = fa_containers[1] if len(fa_containers) > 1 else {"args": [], "env": [], "ports": []}
     check(
         "--upstream=http://127.0.0.1:9117" in side["args"],
         "sidecar upstream must be the co-located app UI over http on 127.0.0.1:<uiport>",
@@ -2743,12 +2826,101 @@ def _selftest() -> int:
         "sidecar must declare BOTH the http and metrics container ports — an undeclared port "
         "cannot be named by a Service port or a PodMonitor, so the flag alone is inert",
     )
+    # API ROUTES (schema 1.9.0). Three properties, and the FIRST is the one that keeps the field
+    # honest: an app that declares nothing must render NO --api-route. `fa` above declares none.
+    check(
+        not any(a.startswith("--api-route") for a in side["args"]),
+        "a forward-auth app that declares no auth.apiRoutes must render NO --api-route. A "
+        "default or a renderer constant would answer PiHole's page loads with 401 — PiHole "
+        "serves no /api/ at all — so the service would look permanently broken to a "
+        "logged-out operator instead of signing them in",
+    )
+    # Same `next(..., None)` discipline as _cookie_name() below, for the same reason: if the
+    # sidecar stops being rendered at all, this must report as a named assertion rather than as a
+    # StopIteration that swallows every other SELFTEST FAIL line in the run.
+    _faapi_dep = next(
+        (
+            d[1]
+            for d in render(
+                {
+                    "name": "faapi",
+                    "source": {"image": "a:1"},
+                    "ingressRoutes": [{"host": "faapi.home.keithjackson.dev", "port": 9119}],
+                    "auth": {
+                        "mode": "forward-auth",
+                        "groups": ["media-users"],
+                        "apiRoutes": ["^/api/", "^/signalr/"],
+                    },
+                }
+            )
+            if d[1]["kind"] == "Deployment"
+        ),
+        None,
+    )
+    fa_api_side = next(
+        (
+            c
+            for c in ((_faapi_dep or {}).get("spec", {}).get("template", {})
+                      .get("spec", {}).get("containers") or [])
+            if c.get("name") == "oauth2-proxy"
+        ),
+        None,
+    )
+    check(
+        fa_api_side is not None,
+        "a forward-auth app declaring auth.apiRoutes rendered NO oauth2-proxy sidecar, so the "
+        "routes have nowhere to land and the app is not gated at all (R-IDP-02)",
+    )
+    check(
+        fa_api_side is not None
+        and [a for a in fa_api_side["args"] if a.startswith("--api-route")]
+        == ["--api-route=^/api/", "--api-route=^/signalr/"],
+        "a declared auth.apiRoutes must render as one repeatable --api-route per entry, in "
+        "declared order, and NOTHING else. Note the flag is SINGULAR: --api-routes does not "
+        "exist in v7.8.1 and the proxy refuses to start with it",
+    )
+    # BREADTH. The renderer must REFUSE a regex that would match a page load, not merely
+    # discourage one, because the schema stage can be skipped and render-golden cannot.
+    for _bad in ("^/", "^/.*", ".*", "/api/", "^/api/|^/"):
+        try:
+            render(
+                {
+                    "name": "fabad",
+                    "source": {"image": "a:1"},
+                    "ingressRoutes": [{"host": "fabad.home.keithjackson.dev", "port": 9120}],
+                    "auth": {
+                        "mode": "forward-auth",
+                        "groups": ["media-users"],
+                        "apiRoutes": [_bad],
+                    },
+                }
+            )
+            _refused = False
+        except SystemExit:
+            _refused = True
+        check(
+            _refused,
+            f"the renderer ACCEPTED auth.apiRoutes entry {_bad!r}. A too-broad --api-route "
+            f"answers a plain page load with 401, so a logged-out operator sees a bare error "
+            f"page and is never offered a sign-in — the service looks permanently broken "
+            f"rather than merely unauthenticated, which is a worse failure than the 302 bug "
+            f"this flag exists to fix",
+        )
+    for _good in ("^/api/", "^/signalr/", "^/api/v3/.*", "^/api/v2.0/server/update$"):
+        check(
+            bool(OAUTH2_API_ROUTE_PATTERN.match(_good)),
+            f"the breadth ratchet rejected the legitimate route {_good!r}. A ratchet that "
+            f"blocks real API prefixes is a ratchet someone eventually deletes",
+        )
+
     # Two forward-auth apps must not be able to collide. Renders a SECOND one and compares, so a
     # future refactor to a constant (or to a per-service table with a copy-paste slip) fails here
     # rather than silently in a browser six weeks later.
-    fa2_side = next(
+    # Same None-tolerant shape as the `faapi` fixture above and for the same reason: a missing
-        c
+    # sidecar must surface as a named assertion, never as a traceback that suppresses the
-        for c in next(
+    # collected SELFTEST FAIL lines.
+    _fa2_dep = next(
+        (
             d[1]
             for d in render(
                 {
@@ -2759,24 +2931,55 @@ def _selftest() -> int:
                 }
             )
             if d[1]["kind"] == "Deployment"
-        )["spec"]["template"]["spec"]["containers"]
+        ),
-        if c["name"] == "oauth2-proxy"
+        None,
+    )
+    fa2_side = next(
+        (
+            c
+            for c in ((_fa2_dep or {}).get("spec", {}).get("template", {})
+                      .get("spec", {}).get("containers") or [])
+            if c.get("name") == "oauth2-proxy"
+        ),
+        {"args": []},
     )
 
+    # `next(..., None)` — the DEFAULT IS LOAD-BEARING, not defensive style. With a bare
+    # `next(genexpr)` this raises StopIteration the moment a sidecar renders no --cookie-name,
+    # which is precisely the mutation this assertion exists to catch. The traceback then escapes
+    # _selftest() before its collected `SELFTEST FAIL:` lines are printed, so the run exits
+    # non-zero with the RIGHT VERDICT AND NO DIAGNOSTICS — and it masks every other assertion the
+    # same mutation broke. Measured by Desmond Oyelaran while wiring the selftest into the
+    # render-golden stage: deleting the --cookie-name emission gave rc 1 via an uncaught
+    # StopIteration and suppressed all of the messages. A missing flag must report AS AN
+    # ASSERTION, with its name in the output, which is what the None + explicit check below do.
     def _cookie_name(container):
-        return next(a for a in container["args"] if a.startswith("--cookie-name="))
+        return next((a for a in container["args"] if a.startswith("--cookie-name=")), None)
 
+    _fa_cn, _fa2_cn = _cookie_name(side), _cookie_name(fa2_side)
     check(
-        _cookie_name(side) != _cookie_name(fa2_side),
+        _fa_cn is not None and _fa2_cn is not None,
+        f"a forward-auth sidecar rendered NO --cookie-name at all (fa={_fa_cn!r}, "
+        f"fa2={_fa2_cn!r}). Omitting the flag is not neutral: oauth2-proxy then claims its "
+        f"built-in default `_oauth2_proxy`, which every other instance on the platform also "
+        f"claims, so they overwrite and ClearSession-delete each other's sessions",
+    )
+    check(
+        _fa_cn != _fa2_cn,
         "two forward-auth apps rendered IDENTICAL cookie names — they would overwrite each "
         "other's session on every sign-in (the 2026-09-29 crafty defect, fleet-wide)",
     )
+    # Index-safe for the same reason as `side` above: an absent sidecar has no env, and an
+    # IndexError here would exit non-zero with no diagnostics at all.
+    _fa_env = (side.get("env") or [{}])[0]
     check(
-        side["env"][0]["valueFrom"]["secretKeyRef"]["name"] == "fa-oauth2-proxy",
+        (((_fa_env.get("valueFrom") or {}).get("secretKeyRef") or {}).get("name")
+         == "fa-oauth2-proxy"),
         "sidecar creds must come by name from the per-app <app>-oauth2-proxy Secret (R-IDP-04)",
     )
-    fa_svc = next(d[1] for d in fa_docs if d[1]["kind"] == "Service")
+    fa_svc = next((d[1] for d in fa_docs if d[1]["kind"] == "Service"), None)
-    fa_svc_ports = {p["port"] for p in fa_svc["spec"]["ports"]}
+    check(fa_svc is not None, "a forward-auth app must render a Service for the Gateway to reach")
+    fa_svc_ports = {p["port"] for p in (((fa_svc or {}).get("spec") or {}).get("ports") or [])}
     check(
         fa_svc_ports == {9117, 4180},
         "forward-auth Service must expose the app port (east-west) AND :4180 (gateway->sidecar)",

catalog/sonarr.yaml

@@ -112,6 +112,14 @@ auth:
     # via k8s-oidc-rbac.yaml). Without it, an empty media-users locks every operator out with an
     # immediate 403 at the oauth2-proxy callback — observed on prod 2026-09-12.
     - platform-admins           # operators of these services must not be locked out of them
+  # NO `apiRoutes` HERE, AND NOT BECAUSE IT NEEDS NONE — because nothing measures that it does.
+  # Sonarr is nearly the same codebase as Radarr, which is exactly what makes `^/api/` +
+  # `^/signalr/` a tempting guess and still a guess. MEASURED 2026-10-01 on the live pod
+  # (sonarr-ddf485775-8ckwt, 0 restarts, 23h): its oauth2-proxy log contains 13,643 lines and
+  # ZERO unauthenticated requests — no /api/, no /signalr/, nothing but health probes. Nobody
+  # has opened this UI since the cookie fix rolled, so the measurement is empty rather than
+  # negative: it is evidence of no TRAFFIC, not evidence of no need. Add the routes when someone
+  # reproduces the 302-on-XHR here, with the numbers.
 update:
   channel: stable               # R-UPD-01
   range: ">=4.0.0 <5.0.0"       # stay on the Sonarr v4 stable line

ci/approval-override.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""ci/approval-override.py — select the admin-override comment on a PR, if there is a valid one.
+
+This script decides NOTHING about authority. It parses a PR's comment list and returns the
+single override *candidate* that ci/approval-policy.sh should then try to authorise against
+the live Gitea permission API. Keeping the two apart is the point:
+
+  * parsing is pure, offline, and therefore TESTABLE (ci/tests/approval-override.test.sh);
+  * authorisation needs the API and must stay in the stage that fails closed.
+
+A candidate is a comment whose body contains, AT THE START OF A LINE, the directive followed
+by a non-empty reason:
+
+    /approve-override the gate cannot gate itself and I am the only human reviewer
+
+WHY EACH RULE IS HERE
+
+  * START OF A LINE, not "anywhere in the body". Otherwise quoting someone else's override
+    ("you could just /approve-override this") re-arms it. Markdown quotes are stripped of a
+    leading '>' before matching for the same reason -- a quoted directive must NOT count, so
+    lines beginning with '>' are DROPPED, not unquoted.
+  * A REASON IS MANDATORY. A bare directive records that a review was waived but not why,
+    which is the difference between an audit trail and a rubber stamp.
+  * STALE OVERRIDES ARE DISCARDED. An override earned at commit A must not silently cover
+    commit B. Any candidate created at or before the head commit's timestamp is dropped --
+    the same semantics Gitea's own `dismiss_stale_approvals` applies to reviews. Push new
+    commits and you must re-override.
+  * THE LATEST CANDIDATE WINS, so a second override comment supersedes the first rather than
+    both being live.
+
+Output: one TSV line (login, created_at, reason) on stdout, or nothing at all when there is no
+valid candidate. Never exits non-zero for "no override" -- absence is a normal answer, and the
+caller must not be able to confuse it with a parse crash.
+
+Input, all via env so nothing lands in `ps`:
+  COMMENTS_JSON  the Gitea /issues/{n}/comments array
+  HEAD_TIME      ISO-8601 timestamp of the PR head commit
+  DIRECTIVE      the override directive, e.g. /approve-override
+"""
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+
+def parse_ts(value):
+    """Gitea emits RFC3339. Return an aware datetime, or None if it is unparseable.
+
+    Unparseable is NOT 'treat as fresh': the caller drops such a candidate, because a
+    timestamp we cannot read is a staleness check we cannot perform.
+    """
+    if not value:
+        return None
+    text = str(value).strip()
+    # Python < 3.11 cannot read a trailing 'Z' in fromisoformat.
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def extract_reason(body, directive):
+    """Return the reason from the first line that STARTS with the directive, else None."""
+    pattern = re.compile(
+        r"^[ \t]*" + re.escape(directive) + r"(?=[ \t:]|$)[ \t:]*(.*)$"
+    )
+    for raw in (body or "").splitlines():
+        # A quoted line is somebody repeating an override, not casting one.
+        if raw.lstrip().startswith(">"):
+            continue
+        match = pattern.match(raw)
+        if match:
+            reason = match.group(1).strip()
+            return reason or None
+    return None
+
+
+def main():
+    directive = os.environ.get("DIRECTIVE", "/approve-override").strip()
+    head_time = parse_ts(os.environ.get("HEAD_TIME", ""))
+
+    try:
+        comments = json.loads(os.environ.get("COMMENTS_JSON") or "[]")
+    except (ValueError, TypeError):
+        # The caller validated this JSON already; if it is broken here, say so loudly on
+        # stderr and emit no candidate. Silence on stdout means "no override".
+        print("approval-override: COMMENTS_JSON is not valid JSON", file=sys.stderr)
+        return 0
+    if not isinstance(comments, list):
+        print("approval-override: COMMENTS_JSON is not a list", file=sys.stderr)
+        return 0
+
+    candidates = []
+    for comment in comments:
+        if not isinstance(comment, dict):
+            continue
+        login = ((comment.get("user") or {}).get("login") or "").strip()
+        reason = extract_reason(comment.get("body"), directive)
+        if not login or not reason:
+            continue
+        created_raw = comment.get("created_at") or comment.get("updated_at") or ""
+        created = parse_ts(created_raw)
+        if created is None:
+            print(
+                "approval-override: dropping override by '%s' — unreadable timestamp %r"
+                % (login, created_raw),
+                file=sys.stderr,
+            )
+            continue
+        # An override must post-date the commit it covers.
+        if head_time is not None and created <= head_time:
+            print(
+                "approval-override: dropping STALE override by '%s' (%s) — not newer than "
+                "head commit (%s). Re-comment to override the current commit."
+                % (login, created.isoformat(), head_time.isoformat()),
+                file=sys.stderr,
+            )
+            continue
+        candidates.append((created, login, reason, created_raw))
+
+    if not candidates:
+        return 0
+
+    # Latest wins: a later override supersedes an earlier one.
+    created, login, reason, created_raw = max(candidates, key=lambda c: c[0])
+    # Keep the reason on one line — this becomes a TSV field.
+    reason = " ".join(reason.split())
+    print("%s\t%s\t%s" % (login, created_raw, reason))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ci/approval-policy.sh

@@ -25,10 +25,45 @@
 # true: if this cannot evaluate, an unreviewed change to the gate itself could merge. A skip is a
 # BYPASS, not a gap. So: cannot determine -> BLOCK.
 #
+# THE ADMIN OVERRIDE (added 2026-10-01), and the lock-out it clears.
+#
+# The rule above was UNSATISFIABLE for the one human who runs this repo. Gitea refuses to let a
+# pull request's author approve their own PR, and `jakman85` is the only collaborator — so "an
+# APPROVED review from someone who is not its author" is a condition the sole administrator can
+# never meet. Every sensitive-path PR they opened was permanently unmergeable, INCLUDING the PR
+# that would fix it. Measured 2026-10-01: PR #35, gate green in 1m41s, zero reviews, blocked.
+#
+# So an administrator may waive the review by COMMENTING on the PR:
+#
+#     /approve-override <reason>
+#
+# Authority comes from the LIVE Gitea permission API, never from the comment — the commenter must
+# hold a permission listed in `.override.authorized_permissions` (admin/owner) at the moment the
+# gate runs, so an old comment from a since-demoted account is worth nothing. The directive must
+# start a line, a reason is mandatory, and the comment must POST-DATE the head commit: an override
+# earned at commit A does not cover commit B. Choosing the candidate comment is the job of the
+# pure, offline, unit-tested ci/approval-override.py; AUTHORISING it is the job of this stage,
+# which fails closed.
+#
+# WHAT THIS COSTS, STATED PLAINLY. For an administrator, "a change to the gate cannot be gated by
+# the gate" stops being structural and becomes advisory. That is the unavoidable consequence of
+# there being one human; the alternative is a repository its owner cannot change. What is bought
+# back is a RECORD — the waiver is an explicit act, attributed to an account, carrying a stated
+# reason, in the PR history and in this stage's output. A silent bypass keyed on "is the author an
+# admin?" would have been less code and is exactly the fail-open shape this repo keeps finding.
+#
+# AND THE PART THAT IS NOT COMFORTABLE. Authorisation is by permission ALONE, with no allowlist of
+# human accounts (operator decision, 2026-10-01, taken with this consequence on the table). The
+# AGENT account `gitea-admin` also reports permission `owner` here, so an agent can clear the
+# sensitive-path review on its own PR by posting the directive — and agents author most PRs in
+# this repo, so that is the common case, not an edge case. To narrow it without touching this
+# logic, add an `override_admins` list to infra/gitea/approval-policy.json: the check below
+# already requires membership whenever that key is present.
+#
 # EXIT CODES
-#   0  no sensitive paths touched (gate alone is sufficient), OR sensitive paths touched and a
+#   0  no sensitive paths touched (gate alone is sufficient), OR sensitive paths touched and
-#      non-author APPROVED review is present
+#      either a non-author APPROVED review or a valid admin override is present
-#   1  sensitive paths touched without such a review, OR the policy could not be evaluated
+#   1  sensitive paths touched with neither, OR the policy could not be evaluated
 set -euo pipefail
 CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${CI_DIR}/.." && pwd)"
@@ -65,7 +100,11 @@ api() { curl -sS --max-time 20 -H "Authorization: token ${TOKEN}" "$@"; }
 FILES_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/pulls/${PR}/files?limit=1000" || true)"
 PR_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/pulls/${PR}" || true)"
 REVIEWS_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/pulls/${PR}/reviews" || true)"
-for v in FILES_JSON PR_JSON REVIEWS_JSON; do
+# PR conversation comments live under the ISSUES endpoint. `/pulls/{n}/comments` returns review
+# (diff) comments ONLY, so an override posted in the normal comment box would never appear in it.
+# Verified against this Gitea (1.24.3) rather than assumed.
+COMMENTS_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/issues/${PR}/comments?limit=1000" || true)"
+for v in FILES_JSON PR_JSON REVIEWS_JSON COMMENTS_JSON; do
   jq -e . >/dev/null 2>&1 <<<"${!v}" || {
     err "could not read ${v} from Gitea for PR #${PR} — BLOCKING rather than assuming."
     summary "- approval-policy: **BLOCKED — Gitea unreadable**"
@@ -107,11 +146,103 @@ if [ -n "$APPROVER" ]; then
   exit 0
 fi
 
+# ─────────────────────────────────────────────────────────────────────────────────────────
+# No non-author approval exists. Before refusing, look for an administrator's explicit
+# override. See the header for why this hatch exists and what it costs.
+# ─────────────────────────────────────────────────────────────────────────────────────────
+OVERRIDE_ENABLED="$(jq -r '.override.enabled // false' "$DECL")"
+DIRECTIVE="$(jq -r '.override.comment_directive // "/approve-override"' "$DECL")"
+HEAD_SHA="$(jq -r '.head.sha // empty' <<<"$PR_JSON")"
+
+if [ "$OVERRIDE_ENABLED" = "true" ]; then
+  # The head commit's timestamp anchors staleness. Read it from GITEA, not from the local
+  # tree: CI checks out a merge commit, whose date is not the head commit's date.
+  HEAD_TIME=""
+  if [ -n "$HEAD_SHA" ]; then
+    HEAD_COMMIT_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/git/commits/${HEAD_SHA}" || true)"
+    HEAD_TIME="$(jq -r '.commit.committer.date // .created // empty' <<<"${HEAD_COMMIT_JSON:-null}" 2>/dev/null || true)"
+  fi
+  if [ -z "$HEAD_TIME" ]; then
+    err "could not read the head commit's timestamp for PR #${PR} — BLOCKING."
+    err "  Without it an override cannot be aged, and an unaged override is one that silently"
+    err "  covers commits nobody waived review on."
+    summary "- approval-policy: **BLOCKED — head commit timestamp unreadable** (cannot age an override)"
+    exit 1
+  fi
+
+  # Pure, offline, unit-tested selection: which comment, if any, is a live override?
+  OVERRIDE_TSV="$(COMMENTS_JSON="$COMMENTS_JSON" HEAD_TIME="$HEAD_TIME" DIRECTIVE="$DIRECTIVE" \
+    python3 "${CI_DIR}/approval-override.py")" || {
+      err "ci/approval-override.py failed — BLOCKING rather than assuming there is no override."
+      summary "- approval-policy: **BLOCKED — override parser failed**"
+      exit 1; }
+
+  if [ -n "$OVERRIDE_TSV" ]; then
+    OV_USER="$(cut -f1 <<<"$OVERRIDE_TSV")"
+    OV_WHEN="$(cut -f2 <<<"$OVERRIDE_TSV")"
+    OV_WHY="$(cut -f3- <<<"$OVERRIDE_TSV")"
+
+    # AUTHORITY IS MEASURED LIVE, never inferred from the comment or from a name in git.
+    PERM_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/collaborators/${OV_USER}/permission" || true)"
+    OV_PERM="$(jq -r '.permission // empty' <<<"${PERM_JSON:-null}" 2>/dev/null || true)"
+    if [ -z "$OV_PERM" ]; then
+      err "'${OV_USER}' posted ${DIRECTIVE}, but their permission on ${GITEA_REPO} could not be"
+      err "  read — BLOCKING. An override whose authority is unverified is not an override."
+      summary "- approval-policy: **BLOCKED — cannot verify \`${OV_USER}\`'s permission**"
+      exit 1
+    fi
+
+    # Authorised when the LIVE permission is one of the declared ones and — only if an
+    # `override_admins` allowlist exists at all — the account is on it. No allowlist means
+    # permission alone, which is the operator's standing decision; adding the key narrows
+    # this with no change to any code.
+    AUTHORISED="$(DECL="$DECL" OV_PERM="$OV_PERM" OV_USER="$OV_USER" python3 -c '
+import json, os
+d = json.load(open(os.environ["DECL"])).get("override", {})
+perms = d.get("authorized_permissions") or ["admin", "owner"]
+allow = d.get("override_admins")
+ok_perm = os.environ["OV_PERM"] in perms
+ok_list = True if allow is None else os.environ["OV_USER"] in allow
+print("yes" if (ok_perm and ok_list) else "no")
+')"
+
+    if [ "$AUTHORISED" = "yes" ]; then
+      if [ "$OV_USER" = "$AUTHOR" ]; then
+        warn "ADMIN OVERRIDE — SELF-WAIVED. '${OV_USER}' authored this PR and waived the"
+        warn "  non-author review requirement on their own change. Permitted (permission"
+        warn "  '${OV_PERM}'), deliberate, and shouted about here precisely because it is not free."
+      else
+        warn "ADMIN OVERRIDE by '${OV_USER}' (permission '${OV_PERM}'); author is '${AUTHOR}'."
+      fi
+      warn "  when:   ${OV_WHEN}  (head commit ${HEAD_SHA:0:8}, ${HEAD_TIME})"
+      warn "  reason: ${OV_WHY}"
+      warn "  review waived on: $(printf '%s ' $SENSITIVE)"
+      ok "sensitive paths cleared by administrator override — this stage does not block."
+      SELFNOTE=""; [ "$OV_USER" = "$AUTHOR" ] && SELFNOTE=", **self-waived as author**"
+      summary "- approval-policy: **OVERRIDDEN by \`${OV_USER}\`** (permission \`${OV_PERM}\`${SELFNOTE})"
+      summary "  - reason: ${OV_WHY}"
+      summary "  - review waived on: $(printf '\`%s\` ' $SENSITIVE)"
+      exit 0
+    fi
+
+    err "'${OV_USER}' posted ${DIRECTIVE} but is NOT authorised to override: live permission is"
+    err "  '${OV_PERM}'. The authorised set is declared in infra/gitea/approval-policy.json."
+    summary "- approval-policy: **BLOCKED — \`${OV_USER}\` may not override** (permission \`${OV_PERM}\`)"
+    exit 1
+  fi
+fi
+
 err "This PR changes the pipeline or the security posture it rests on, and has NO approving"
 err "  review from anyone other than its author ('${AUTHOR}')."
 err "  A change to the gate cannot be gated by the gate — that is the one thing CI cannot"
 err "  honestly approve for itself. Get a human review, or move the change out of:"
 printf '    %s\n' $SENSITIVE >&2
 err "  The list lives in infra/gitea/approval-policy.json, with a reason per entry."
-summary "- approval-policy: **BLOCKED — sensitive paths need a non-author approval**"
+if [ "$OVERRIDE_ENABLED" = "true" ]; then
+  err "  Or, if you hold admin/owner on this repository, comment on the PR:"
+  err "      ${DIRECTIVE} <reason>"
+  err "  The reason is mandatory, the directive must START a line, and the comment must be"
+  err "  NEWER than head commit ${HEAD_SHA:0:8} — push again and you must override again."
+fi
+summary "- approval-policy: **BLOCKED — needs a non-author approval, or an admin \`${DIRECTIVE}\` comment**"
 exit 1

ci/render-golden.sh

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
-# ci/render-golden.sh — Stage: render==golden reproducibility gate.
+# ci/render-golden.sh — Stage: the renderer is trustworthy.
+#   (1) catalog/render.py passes its OWN output-contract self-test, and
+#   (2) every committed apps/ golden reproduces byte-for-byte from the canonical render.
+# Two independent assertions about one subject, catalog/render.py. (1) was added
+# 2026-10-01 because nothing in ci/ or .gitea/ had ever invoked `--selftest`; see the
+# block above the invocation for why it lives here and not in a conformance check.
 #
 # WHY: the committed apps/ tree is a set of GOLDENS produced by ONE canonical
 # invocation of catalog/render.py. If a golden is hand-edited, or a catalog
@@ -54,6 +59,54 @@ if [ ! -f "$RENDER_PY" ]; then
   summary "- render-golden: **SKIPPED** (renderer missing)"
   exit 3
 fi
+# --- The renderer's OWN self-test, before anything is compared ---------------
+# `catalog/render.py --selftest` is ~106 executed assertions on the renderer's output
+# contract (default-deny covers both directions, the Kyverno namespace hook label, a valid
+# auth-mode, the oauth2-proxy sidecar's cookie-name/-domain/-refresh flags, the
+# placeholder-substitution guard, the observability refusals...). Until now NOTHING in ci/
+# or .gitea/ invoked it — measured by grep on 2026-09-30 and recorded as the top follow-up
+# of decisions/2026-09-30-oauth2-proxy-cookie-collision-fleet.md — so every one of those
+# assertions was dev-time only and a merge gate could not tell a sound renderer from a
+# gutted one.
+#
+# WHY HERE, AND NOT IN A CONFORMANCE CHECK. The lead was
+# conformance/tests/l0-static/auditability-proofs-producible/check.sh, which drives
+# `conformance/lib/{record_run,status}.py --selftest` "because nothing else drives them".
+# That loop is NOT the right hook: that check serves R-SEC-03 and its subject is the
+# EVIDENCE CHAIN (can a forged or stale run become a proof?). The renderer is not part of
+# that chain, and hanging it there would make the check's name and its requirement mapping
+# a lie. This stage's subject already IS catalog/render.py — it exists to assert that the
+# renderer's output is trustworthy — so the renderer's own contract test belongs in it.
+#
+# It runs BEFORE the catalog/empty-catalog exit-3 below on purpose: the self-test is
+# deterministic and catalog-independent (it renders synthetic ServiceDefinitions in
+# memory), so an empty catalog must not be able to skip it.
+#
+# render-golden and the self-test are INDEPENDENT assertions, which is why both are needed:
+# render-golden catches golden-vs-renderer drift but is satisfied by ANY renderer whose
+# output was re-rendered, including one that just lost a contract invariant and had all ten
+# goldens regenerated in the same commit. The self-test catches exactly that.
+#
+# FAILURE IS A HARD FAIL, NOT A SKIP: the renderer is source in this repo, so "could not
+# run its self-test" has no legitimate environmental cause once python3 and render.py are
+# both present (both asserted above). ci/gate.sh maps this stage's rc 1 to BLOCKED.
+log "Stage: catalog/render.py --selftest (the renderer's own output-contract assertions)"
+selftest_out="$(mktemp)"
+if "$PYTHON" "$RENDER_PY" --selftest >"$selftest_out" 2>&1; then
+  ok "render.py --selftest passed"
+  summary "- render-selftest: **passed** (\`catalog/render.py --selftest\`)"
+else
+  err "catalog/render.py --selftest FAILED — the renderer violates its own output contract."
+  err "  Every golden under apps/ is produced by this renderer, so the goldens below cannot"
+  err "  be trusted even if they reproduce byte-for-byte. Reproduce with:"
+  err "    ${PYTHON} catalog/render.py --selftest"
+  sed 's/^/    /' "$selftest_out" >&2 || true
+  summary "- render-selftest: **FAILED** (\`catalog/render.py --selftest\` — renderer contract violated)"
+  rm -f "$selftest_out"
+  exit 1
+fi
+rm -f "$selftest_out"
+
 if [ ! -d "$CATALOG_DIR" ] || ! compgen -G "${CATALOG_DIR}/*.yaml" >/dev/null 2>&1; then
   skip "no catalog ServiceDefinitions under '${CATALOG_DIR}' — nothing to render."
   summary "- render-golden: **SKIPPED** (empty catalog)"

ci/tests/approval-override.test.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# ci/tests/approval-override.test.sh — proves ci/approval-override.py selects the override it
+# claims to select, and REJECTS the ones it claims to reject.
+#
+# This parser decides whether a human review requirement gets waived. Every rule in it exists
+# because the obvious implementation ("does the body contain the directive?") is wrong in a way
+# that is invisible until abused: a quoted directive would re-arm an override, a bare directive
+# would waive review with no stated reason, and an override posted against commit A would go on
+# covering commit B forever. A guard is worth nothing until somebody has watched it refuse, which
+# is the same reasoning as ci/tests/decisions-log.test.sh one layer up.
+#
+# The parser is pure and offline BY DESIGN — authorisation (the live permission lookup) lives in
+# ci/approval-policy.sh, which cannot be tested without Gitea. That split is what makes this file
+# possible, and it is also why a green run here does NOT prove the stage authorises correctly.
+set -uo pipefail
+CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SUT="${CI_DIR}/approval-override.py"
+
+PASS=0 FAIL=0
+ok()  { printf '  ok   %s\n' "$*"; PASS=$((PASS+1)); }
+bad() { printf '  FAIL %s\n' "$*"; FAIL=$((FAIL+1)); }
+
+HEAD_TIME="2026-10-01T12:00:00Z"
+AFTER="2026-10-01T12:30:00Z"
+BEFORE="2026-10-01T11:30:00Z"
+
+# run <comments-json> -> stdout of the parser (stderr is diagnostic only)
+run() {
+  COMMENTS_JSON="$1" HEAD_TIME="${2:-$HEAD_TIME}" DIRECTIVE="${3:-/approve-override}" \
+    python3 "$SUT" 2>/dev/null
+}
+
+# comment <login> <created_at> <body>
+comment() {
+  python3 -c '
+import json, sys
+print(json.dumps([{"user": {"login": sys.argv[1]}, "created_at": sys.argv[2], "body": sys.argv[3]}]))
+' "$1" "$2" "$3"
+}
+
+expect_none() {
+  local label="$1" out
+  out="$(run "$2")"
+  if [ -z "$out" ]; then ok "$label"; else bad "$label (got: ${out})"; fi
+}
+
+expect_user() {
+  local label="$1" json="$2" want="$3" out got
+  out="$(run "$json")"
+  got="$(cut -f1 <<<"$out")"
+  if [ "$got" = "$want" ]; then ok "$label"; else bad "$label (wanted ${want}, got '${got}')"; fi
+}
+
+expect_reason() {
+  local label="$1" json="$2" want="$3" out got
+  out="$(run "$json")"
+  got="$(cut -f3- <<<"$out")"
+  if [ "$got" = "$want" ]; then ok "$label"; else bad "$label (wanted '${want}', got '${got}')"; fi
+}
+
+echo "== ci/approval-override.py"
+
+# --- the happy path -------------------------------------------------------------------
+expect_user "a directive with a reason, posted after the head commit, is selected" \
+  "$(comment jakman85 "$AFTER" '/approve-override sole admin, gate is green')" jakman85
+
+expect_reason "the reason is returned verbatim" \
+  "$(comment jakman85 "$AFTER" '/approve-override sole admin, gate is green')" \
+  'sole admin, gate is green'
+
+# --- absence is a normal answer, not an error -----------------------------------------
+expect_none "no comments at all" '[]'
+expect_none "an ordinary comment" "$(comment jakman85 "$AFTER" 'looks good to me')"
+
+# --- a reason is MANDATORY ------------------------------------------------------------
+expect_none "a bare directive (no reason) is refused" \
+  "$(comment jakman85 "$AFTER" '/approve-override')"
+expect_none "a directive followed by only whitespace is refused" \
+  "$(comment jakman85 "$AFTER" '/approve-override    ')"
+
+# --- the directive must START a line --------------------------------------------------
+expect_none "the directive mid-sentence does not count" \
+  "$(comment jakman85 "$AFTER" 'you could just /approve-override this one')"
+expect_none "a QUOTED directive does not re-arm an override" \
+  "$(comment jakman85 "$AFTER" '> /approve-override quoting someone else')"
+expect_user "leading whitespace before the directive is fine" \
+  "$(comment jakman85 "$AFTER" '   /approve-override indented but mine')" jakman85
+expect_user "the directive on a later line of a longer comment counts" \
+  "$(comment jakman85 "$AFTER" 'some preamble
+/approve-override the real reason here')" jakman85
+
+# --- staleness: an override must post-date the commit it waives review on -------------
+expect_none "an override OLDER than the head commit is dropped as stale" \
+  "$(comment jakman85 "$BEFORE" '/approve-override stale, predates the push')"
+expect_none "an override exactly AT the head commit time is dropped (strictly newer)" \
+  "$(comment jakman85 "$HEAD_TIME" '/approve-override same instant')"
+
+# --- malformed input is never a free pass --------------------------------------------
+expect_none "an unreadable timestamp drops the candidate" \
+  "$(comment jakman85 'not-a-date' '/approve-override bad clock')"
+expect_none "a comment with no author is dropped" \
+  '[{"user": {}, "created_at": "2026-10-01T12:30:00Z", "body": "/approve-override no login"}]'
+expect_none "invalid JSON yields no override (and never a traceback into stdout)" \
+  'this is not json'
+expect_none "a JSON object instead of a list yields no override" \
+  '{"user": "nope"}'
+
+# --- latest wins ----------------------------------------------------------------------
+TWO='[
+  {"user": {"login": "early"},  "created_at": "2026-10-01T12:10:00Z", "body": "/approve-override first"},
+  {"user": {"login": "latest"}, "created_at": "2026-10-01T12:40:00Z", "body": "/approve-override second"}
+]'
+expect_user "the LATEST override supersedes an earlier one" "$TWO" latest
+expect_reason "and brings its own reason" "$TWO" second
+
+# --- offsets, not just Z --------------------------------------------------------------
+# Gitea emits RFC3339 WITH AN OFFSET (measured: 2026-10-01T23:09:08-05:00), not a trailing Z.
+# A parser that only handles 'Z' silently drops every real override, so this case is load-bearing.
+expect_user "an RFC3339 offset timestamp (-05:00), as Gitea actually emits, parses" \
+  '[{"user": {"login": "jakman85"}, "created_at": "2026-10-01T08:30:00-05:00", "body": "/approve-override offset form"}]' \
+  jakman85
+expect_none "and an offset timestamp that is genuinely earlier is still stale" \
+  '[{"user": {"login": "jakman85"}, "created_at": "2026-10-01T06:00:00-05:00", "body": "/approve-override offset, stale"}]'
+
+# --- the directive is configurable ----------------------------------------------------
+out="$(run "$(comment jakman85 "$AFTER" '/admin-waive because policy says so')" "$HEAD_TIME" '/admin-waive')"
+if [ "$(cut -f1 <<<"$out")" = "jakman85" ]; then
+  ok "a custom directive from the declaration is honoured"
+else
+  bad "a custom directive from the declaration is honoured (got '${out}')"
+fi
+expect_none "the default directive does not match a custom-directive comment" \
+  "$(comment jakman85 "$AFTER" '/admin-waive because policy says so')"
+
+# --- no staleness anchor: do not invent one -------------------------------------------
+out="$(COMMENTS_JSON="$(comment jakman85 "$BEFORE" '/approve-override no anchor')" \
+       HEAD_TIME="" DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+if [ "$(cut -f1 <<<"$out")" = "jakman85" ]; then
+  ok "with no HEAD_TIME the staleness test is skipped, not faked (caller blocks instead)"
+else
+  bad "with no HEAD_TIME the candidate should still be returned (got '${out}')"
+fi
+
+printf '\n  %d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

ci/tests/gate-decision.test.sh

@@ -42,7 +42,16 @@ cp "${REAL_CI_DIR}/gate.sh" "${REAL_CI_DIR}/lib.sh" "${REAL_CI_DIR}/versions.env
 # 15 of 47 assertions failed on `main` for that reason alone, including every one that expects a
 # PASS/UNDETERMINED/NOT-APPLICABLE headline. The suite was measuring the missing stub, not the
 # decision logic. `decisions-log` is added here in the same change that adds it to gate.sh.
-for stage in spec-immutability decisions-log lint l0 render-golden l1 gitea-settings conformance; do
+#
+# AND IT HAPPENED AGAIN, with `approval-policy` (fixed 2026-10-01). Same shape, same cost: the
+# stage was added to gate.sh by PR #17, never added here, so 15 of 50 assertions failed on `main`
+# — measured on 0c7e8dd before touching anything, to be sure it was not the change under test.
+# The note above was written about the previous instance and did not prevent the next one, which
+# says the comment is not the fix. THE FIX IS TO DERIVE THE LIST: it now comes from gate.sh's own
+# `run_stage` calls, so a stage added there can no longer be silently missing here.
+mapfile -t STAGES < <(sed -n 's/^run_stage[[:space:]]\+\([a-z0-9-]\+\).*/\1/p' "${REAL_CI_DIR}/gate.sh")
+[ "${#STAGES[@]}" -ge 8 ] || { echo "could not parse stage names out of gate.sh (got ${#STAGES[@]})" >&2; exit 1; }
+for stage in "${STAGES[@]}"; do
   cat > "${CI}/${stage}.sh" <<'STUB'
 #!/usr/bin/env bash
 n="$(basename "$0" .sh)"; v="STAGE_RC_${n//-/_}"

clusters/base/intel-gpu-plugin.yaml

@@ -0,0 +1,104 @@
+---
+# Flux Kustomization: Intel GPU device plugin — reconciles ./platform/intel-gpu-plugin.
+# Makes the three prod nodes advertise `gpu.intel.com/i915`, which is the resource a later PR will
+# have `hardware.gpu: intel-quicksync` request in place of today's non-working /dev/dri hostPath.
+#
+# WHY ITS OWN KUSTOMIZATION, AND NOT ONE LINE IN platform/kustomization.yaml
+#
+# The cheap option was a line in the shared `platform` tier plus a new platform/ directory, and
+# neither path is sensitive in infra/gitea/approval-policy.json, so it would have needed no human
+# reviewer on the policy's terms. It is still the wrong place, for the reason the repo already
+# wrote down in platform/kustomization.yaml when Cilium was split out of that tier:
+#
+#   * `platform` is `wait: true` over eleven-plus components, so its Ready condition cannot tell
+#     you "the GPU plugin is wedged" from "longhorn is slow".
+#   * The only emergency valve would be `flux suspend kustomization platform` — freezing storage,
+#     TLS, DNS, ingress, monitoring, Keycloak and KubeVirt in order to stop touching a device
+#     plugin.
+#   * The tier's 10m interval / 5m timeout are explicitly called out there as WRONG for a 3-node
+#     DaemonSet rollout. This is a 3-node DaemonSet rollout.
+#
+# And the consequence is worse here than for an average component, because of what sits downstream:
+# `platform` gates platform-config, which gates apps-wave-0 (wait:true), which gates apps-wave-1.
+# A plugin DaemonSet that never went healthy inside that tier would stall every app on "dependency
+# not ready" — i.e. a component added to fix a SILENT NO-OP (software transcoding) would have
+# acquired the ability to cause a REAL OUTAGE. That trade is the whole argument.
+#
+# The usual objection to this placement is the approval cost, and it does not apply: Gitea enforces
+# `required_approvals: 1` with `block_admin_merge_override: true` on EVERY PR here regardless of
+# path, and authors cannot self-approve. So this change needed the operator's approval either way;
+# touching clusters/** costs nothing extra and buys a blast radius of exactly one component.
+#
+# dependsOn: [cilium], WHICH IS THE MINIMUM AND ALSO THE EARLIEST
+#
+# Not platform-config (what headlamp/crafty/homepage/oauth2-proxy use) — those are leaf UIs that
+# genuinely need Keycloak + wildcard TLS + split-horizon DNS + Gateway. This plugin needs none of
+# it. It never uses the network and never talks to the API server; it talks to the local kubelet
+# over a unix socket. Its only real prerequisite is a working CNI, so its pod can get a sandbox at
+# all, and `cilium` already depends on `flux-system` (the root Kustomization that applies the
+# cluster-vars ConfigMap this one substitutes from), so that edge is transitively satisfied too.
+#
+# Depending on `cilium` rather than `platform` also gets the resource advertised EARLIEST — this
+# reconciles in parallel with the `platform` tier instead of behind all eleven of its components.
+# That matters on a cold start once the consumer PR lands: a Plex pod requesting a resource no node
+# advertises is Unschedulable, and apps-wave-0 is wait:true. Reconciling early shrinks that window
+# instead of widening it. It is not a GUARANTEE — see the ordering note below, which is a real
+# constraint on the next PR and not a formality.
+#
+# Kyverno (in `platform`) is deliberately NOT a dependency: every policy that could match this
+# workload is scoped to namespaces labelled app-namespace=true, and this namespace is labelled
+# "false" (platform/intel-gpu-plugin/namespace.yaml). So there is no admission race to lose.
+#
+# wait: true — A HEALTH SIGNAL, NOT A GATE. This is the one place this component departs from the
+# headlamp/crafty leaf template, and the departure is deliberate. Those run wait:false because a
+# leaf UI can be legitimately not-Ready for a long time during a cold start while it waits on
+# Keycloak/DNS/TLS, so its health is not a useful signal. This DaemonSet has no such dependency: it
+# reads sysfs and opens a socket, so on healthy nodes it should be Ready in seconds, and
+# not-Ready genuinely means BROKEN. wait:true turns `flux get kustomization intel-gpu-plugin` into
+# a one-line answer to "did the plugin come up on all three nodes", which is exactly the question
+# the operator must answer before the consumer PR may merge.
+#
+# NOTHING IN THE GRAPH dependsOn THIS, so wait:true gates nothing — the blast radius of an unhealthy
+# plugin is this Kustomization's own Ready condition and nothing else. Anyone later adding
+# `dependsOn: [intel-gpu-plugin]` is choosing to make plugin health gate their thing; for the app
+# waves that would hand a device plugin the power to stall every app, which is the thing this file
+# exists to prevent. Think before adding that edge.
+#
+# ORDERING — DO NOT REORDER THE STACK. The renderer change (catalog/render.py emitting
+# `gpu.intel.com/i915: 1` for `hardware.gpu: intel-quicksync` instead of the hostPath) must NOT
+# land until this plugin is merged AND confirmed advertising the resource on all three nodes. If
+# the renderer requests a resource no node advertises, the Plex pod is Unschedulable; apps-wave-0 is
+# wait:true and apps-wave-1 dependsOn it, so that stalls the whole app tier — turning today's silent
+# no-op into a real outage. This PR's only job is to make the resource exist.
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: intel-gpu-plugin
+  namespace: flux-system
+spec:
+  # Static vendored manifests with nothing to re-render; kustomize-controller is source-triggered,
+  # so this is only the drift-correction floor.
+  interval: 10m
+  retryInterval: 2m
+  # 10m, not the 5m the `platform` tier uses: a 3-node DaemonSet rollout under `wait: true` can
+  # exceed 5m on a cold start (image pull on three nodes), and the Cilium split-out comment calls
+  # out that exact mismatch as one of its reasons for leaving the shared tier.
+  timeout: 10m
+  prune: true
+  # See the header: a health SIGNAL for a component nothing depends on, not a gate.
+  wait: true
+  dependsOn:
+    - name: cilium   # the CNI — the only real prerequisite; transitively gives us flux-system too
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  path: ./platform/intel-gpu-plugin
+  # Retained for parity with every other tier / future overlay knobs. This component references no
+  # ${VARS} today, and its manifests contain no `$` literals for envsubst to eat (unlike
+  # clusters/base/runbooks.yaml, which omits substitution for exactly that reason).
+  postBuild:
+    substituteFrom:
+      - kind: ConfigMap
+        name: cluster-vars
+  # No SOPS decryption patch: this component carries no Secret, so clusters/dev adds nothing for it
+  # (same as homepage/runbooks, unlike headlamp/crafty/oauth2-proxy/backup).

clusters/base/kustomization.yaml

@@ -12,6 +12,15 @@ resources:
   # interval/timeout, and `flux suspend kustomization cilium` as an emergency valve that does not
   # freeze the other eleven platform components. See clusters/base/cilium.yaml.
   - cilium.yaml          # Flux Kustomization -> ./platform/cilium (dependsOn flux-system, wait:true)
+  # Intel GPU device plugin — its OWN Kustomization (dependsOn cilium, wait:true), NOT a line in
+  # platform/kustomization.yaml. Same reasoning as the Cilium split-out, applied to a leaf: inside
+  # that wait:true tier a wedged 3-node DaemonSet would be indistinguishable from eleven unrelated
+  # components AND would stall platform-config + every apps wave on "dependency not ready" — so a
+  # component added to fix a silent no-op (Plex software transcoding) could cause a real outage.
+  # wait:true here is a HEALTH SIGNAL, not a gate: nothing in the graph dependsOn it.
+  # It advertises `gpu.intel.com/i915`; the renderer change that REQUESTS that resource must land
+  # strictly later. See clusters/base/intel-gpu-plugin.yaml.
+  - intel-gpu-plugin.yaml # Flux Kustomization -> ./platform/intel-gpu-plugin (dependsOn cilium)
   - platform.yaml        # Flux Kustomization -> ./platform (CONTROLLERS: HelmReleases / CRDs)
   - platform-config.yaml # Flux Kustomization -> ./platform-config (CONFIGS: CRs; dependsOn platform)
   # SECOND-ORDER CDI configs — CRs whose CRD is created by a controller AT RUNTIME, not by any

conformance/tests/l0-static/oauth2-proxy-api-routes-per-app/chainsaw-test.yaml

@@ -0,0 +1,134 @@
+# =============================================================================
+# L0 STATIC — `--api-route` is PER APP, ANCHORED, and DECLARED
+# Catalog: docs/14 L0 row ("Pre-apply, in CI") — runs WITHOUT a cluster.
+#
+# THE DEFECT THIS CLOSES. oauth2-proxy answers an unauthenticated request with a 302 to
+# Keycloak. Its built-in AJAX guard would send a 401 instead, but it fires only on an EXACT
+# `Accept: application/json`, which these apps' JavaScript does not consistently send. So a
+# browser XHR gets a 302, FOLLOWS IT INVISIBLY, has it satisfied silently by the live Keycloak
+# SSO session, and resolves 200 carrying the app's HTML where the JavaScript expected JSON — no
+# prompt, no console error, nothing logged as a failure. On a WRITE it is worse: a browser
+# following a 302 re-issues a POST as a GET and DROPS THE BODY, so the operator's change is
+# discarded and the UI reports success.
+#
+# MEASURED, twice, on two different apps and two different paths:
+#   jackett 2026-09-30 — on /api/ paths: 33 x 302 against 2 x 401, and 4 of 6 POSTs answered BY
+#           THE PROXY, never reaching Jackett (access-log upstream field `-`, not `/`). That is
+#           the operator's whole report: "GET works, most PUT/POST to add indexers fail,
+#           reloading never fixes it, and I am never re-prompted for login".
+#   radarr  2026-10-01, 23h after the cookie fix rolled (pod radarr-7d55cbffb9-42hmh, 0
+#           restarts) — 232 unauthenticated requests in the pod's whole lifetime and ALL 232 are
+#           the same call: `POST /signalr/messages/negotiate` from a browser UA, 302, upstream
+#           `-`. A left-open tab whose session the cookie rename orphaned, polling SignalR
+#           forever, silently redirected every time, NEVER re-prompting. The reported symptom,
+#           still running in production, on a service nobody was watching.
+#
+# WHY IT CANNOT BE A RENDERER CONSTANT — AND WHY THAT NEEDS A GATE. The path shape belongs to
+# the APP, not to the forward-auth pattern: radarr's broken path is `/signalr/`, jackett's is
+# `/api/`, and PIHOLE SERVES NO `/api/` AT ALL. One function renders all five sidecars
+# (catalog/render.py::_oauth2_sidecar_container), so the cheap fix is a constant — and a
+# constant applies one app's measurement to four apps nobody measured. The gate that already
+# exists cannot see that mistake: `ci/render-golden.sh` compares the render to the goldens, and
+# a constant plus regenerated goldens AGREE WITH EACH OTHER while both being wrong. Hence
+# assertion (2) below, which compares the rendered flag against each service's OWN
+# ServiceDefinition rather than against the renderer's output.
+#
+# WHY BREADTH IS THE DANGEROUS DIRECTION, AND IT IS NOT SYMMETRIC. A MISSING --api-route is a
+# silent 302 — bad, invisible, recoverable. A TOO BROAD one answers a plain PAGE LOAD with 401:
+# a logged-out operator gets a bare error page and is NEVER OFFERED A SIGN-IN, so the service
+# looks permanently broken and no reload recovers it. That is a worse outcome than the defect
+# the flag fixes, which is why the anchoring rule is asserted on three independent surfaces
+# (schema items.pattern, the renderer, and this check) and why assertion (5) fails if they drift
+# apart — if they do, the loosest one wins silently.
+#
+# GIVEN every oauth2-proxy sidecar this repo DEPLOYS (a container in any manifest at any depth:
+#       the rendered sidecars in apps/, crafty's hand-authored one in platform/), the
+#       ServiceDefinitions in catalog/ that generate five of them, and the renderer itself,
+# WHEN  each sidecar's `--api-route` values are collected (the flag is REPEATABLE, so all of
+#       them, in order) and each onboarded forward-auth service is paired with its golden,
+# THEN  (1) every rendered --api-route is anchored at `^/` and continues with literal path
+#           characters — `^/`, `^/.*`, `.*`, an unanchored `/api/` and any alternation FAIL;
+#       (2) every onboarded forward-auth service's rendered route list EQUALS its own
+#           ServiceDefinition's `auth.apiRoutes`, in order — which fails both a hand-edited
+#           golden and a renderer constant, neither of which render-golden can see;
+#       (3) BOTH cases are live in this tree: at least one service declares routes and at least
+#           one declares none and renders none (the pihole case), so neither path is an
+#           unexercised seam;
+#       (4) `_oauth2_sidecar_container()` reads `auth.apiRoutes` and contains NO literal path
+#           regex — a constant is the defect, back in the one place that reintroduces it
+#           fleet-wide in a single edit;
+#       (5) the anchoring pattern in the renderer and in the schema are the SAME pattern this
+#           check enforces;
+#       (6) the SHIPPED renderer, run as a subprocess on synthetic ServiceDefinitions, emits
+#           exactly the declared routes in order, emits NOTHING for a service declaring none or
+#           an empty list, and REFUSES all five breadth shapes.
+#
+# WHY ALSO A SCHEMA PATTERN, GIVEN THIS CHECK. The schema is the only surface that rejects a
+# too-broad regex WHERE A HUMAN TYPES IT — `ci/l0.sh` validates `catalog/*.yaml` against it on
+# every gate run, so the operator is told at the authoring surface rather than finding out from
+# a 401 on a page load. The renderer's own guard is there because `render-golden` runs even on a
+# gate invocation where the schema stage skipped. This check is there because neither of those
+# can see a renderer constant. Three surfaces, three different blind spots.
+#
+# WHY THIS IS A SIBLING AND NOT PART OF oauth2-proxy-cookie-names-distinct. That check's subject
+# is cookie IDENTITY: its inputs are names and domains, its failure mode is mutual session
+# eviction, its register is the shared proxy's claim on the default name. `--api-route` shares
+# none of those. Bundling them would make that check's name a lie and couple two unrelated
+# ratchets, so a future api-route decision could only be expressed by weakening a COOKIE check —
+# the same discipline that check's own header argues for, applied to this change.
+#
+# WHAT THIS DOES NOT ESTABLISH — read with the handoff entry, not instead of it:
+#   - That a 401 FIXES anything in a browser. No browser round-trip has been made, by anyone,
+#     for this flag. The 302/401 split, the dropped POST bodies and the orphaned SignalR poll
+#     are all read from access logs; the repair is reasoned from HTTP semantics.
+#   - That the regexes are RIGHT for these two apps beyond the measured paths. `^/api/` on
+#     radarr is justified by a measurement of radarr taken on its PRE-FIX pod by another
+#     engineer (decisions/2026-09-30-jackett-oauth2-proxy-session.md: 62 x /api/v3/command,
+#     46 x /api/v3/queue/details); the current pod has logged zero /api/ traffic.
+#   - Anything about sonarr, qbittorrent or pihole. Their logs were read (2026-10-01) and
+#     contain ZERO unauthenticated requests — no traffic, which is not the same as no need.
+#     Assertion (3) therefore proves the "declares none" PATH works; it does not claim those
+#     three apps are correctly configured.
+#   - That the LIVE pods carry what the tree says. git is not the cluster (CLAUDE.md §2b).
+#   - It does not read ../home-network-k3s. The spec is read-only (R-TEST-06).
+# =============================================================================
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: oauth2-proxy-api-routes-per-app
+  labels:
+    conformance.home.k3s/R-IDP-02: "true"
+  annotations:
+    conformance.home.k3s/requirements: "R-IDP-02"
+    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — the subject spans apps/wave-0, apps/wave-1, platform/crafty, every
+    # ServiceDefinition in catalog/, the renderer that generates five of the sidecars, and the
+    # ServiceDefinition schema. No single requirement path-maps to that set, and the renderer
+    # maps to no identity requirement at all, so a requirement-scoped selection would skip this
+    # check on precisely the change that can reintroduce the defect fleet-wide in one edit.
+    conformance.home.k3s/scope: "whole-repo"
+    conformance.home.k3s/safety-critical: "false"
+    conformance.home.k3s/executable: "true"
+    conformance.home.k3s/intent: >-
+      An unauthenticated XHR is answered 401, not 302, on exactly the paths each app was
+      MEASURED to serve as a machine API: every rendered --api-route is anchored at ^/ and
+      continues with literal path characters, every onboarded forward-auth service's rendered
+      routes equal its own auth.apiRoutes in order (so neither a hand-edited golden nor a
+      renderer constant can pass), an app declaring none renders none, the anchoring pattern is
+      the same in the schema and the renderer, and the shipped renderer is proven on synthetic
+      ServiceDefinitions in both directions — including refusing the five breadth shapes that
+      would answer a page load with 401.
+spec:
+  steps:
+    - name: assert-api-route-is-per-app-anchored-and-declared
+      description: >-
+        Inventory every oauth2-proxy sidecar's repeatable --api-route values, assert each is an
+        anchored path regex, cross-check each onboarded forward-auth service's rendered routes
+        against its own ServiceDefinition, require both the declares-routes and the
+        declares-none cases to be live in the tree, assert the renderer derives from
+        auth.apiRoutes and hardcodes no path regex, assert the schema and renderer share this
+        check's anchoring pattern, and prove the shipped renderer on synthetic
+        ServiceDefinitions in both directions.
+      try:
+        - script:
+            content: bash ./check.sh

conformance/tests/l0-static/oauth2-proxy-api-routes-per-app/check.sh

@@ -0,0 +1,433 @@
+#!/usr/bin/env bash
+# =============================================================================
+# L0 STATIC CHECK — `--api-route` is PER APP, ANCHORED, and DECLARED.
+# See chainsaw-test.yaml's header for WHY this exists and what it measured. In one paragraph:
+#
+# oauth2-proxy answers an unauthenticated request with a 302 to Keycloak. A browser XHR follows
+# that redirect invisibly, the live SSO session satisfies it silently, and the call resolves 200
+# carrying the app's HTML where its JavaScript expected JSON — and a POST following a 302 is
+# re-issued as a GET with its BODY DROPPED. `--api-route=<regex>` makes matching paths answer
+# 401 instead. The flag is right for jackett (`/api/`) and radarr (`/signalr/`, `/api/`) and
+# WRONG for pihole, which serves no `/api/` at all — so it cannot be a renderer constant, and
+# the point of this check is that it never becomes one again.
+#
+# The breadth direction is the dangerous one and it is NOT symmetric with the bug. A missing
+# `--api-route` is a silent 302; a TOO BROAD one answers a plain PAGE LOAD with 401, so a
+# logged-out operator gets a bare error page and is never offered a sign-in — the service looks
+# permanently broken. That is a worse outcome than the defect, which is why the anchoring rule
+# is asserted here as well as in the schema.
+#
+# Exit 0 = all assertions pass. Exit 1 = a failure. Exit 3 (honest SKIP, which the runner turns
+# into rc 3 = UNWIRED, never green, because this test declares the whole-repo scope) only if the
+# tree contains no forward-auth oauth2-proxy sidecar at all — genuinely nothing to audit.
+# =============================================================================
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${DIR}/../../../.." && pwd)"        # repo root
+PYTHON="${PYTHON:-python3}"
+
+# Honest SKIP (never green for a scope-declaring test) if the forward-auth pattern has left the
+# repo. Anchored on `image:` for the same reason as the sibling cookie check: a bare
+# `oauth2-proxy/oauth2-proxy:` also matches platform/oauth2-proxy/forward-auth-cec.yaml's Envoy
+# cluster reference (`serviceName: oauth2-proxy/oauth2-proxy:80`), which runs no proxy.
+if ! grep -rlE 'image:[[:space:]]*[^[:space:]]*oauth2-proxy' \
+       "${ROOT}/apps" "${ROOT}/platform" >/dev/null 2>&1; then
+  echo "check SKIPPED: no oauth2-proxy container image found under apps/ or platform/ — the forward-auth sidecar pattern is gone and there is nothing to audit" >&2
+  exit 3
+fi
+
+cd "${ROOT}"
+"${PYTHON}" - "${ROOT}" <<'PY'
+"""Static audit: --api-route is per-app, anchored, and declared in the ServiceDefinition.
+
+PyYAML (the same dependency as catalog/render.py and the sibling l0-static checks) rather than
+line-based parsing: a container's args live in a nested structure, and a line-based reader of
+one is precisely the approximate parser that silently stops matching.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:                                  # pragma: no cover
+    print("check FAIL: PyYAML is required (same dependency as catalog/render.py)",
+          file=sys.stderr)
+    raise SystemExit(1)
+
+ROOT = Path(sys.argv[1])
+sys.dont_write_bytecode = True          # keep __pycache__ out of the tracked tree
+
+FAILURES: list[str] = []
+CHECKS = 0
+
+
+def check(cond, msg):
+    global CHECKS
+    CHECKS += 1
+    if not cond:
+        FAILURES.append(msg)
+
+
+# THE BREADTH RATCHET, stated once and asserted against three independent surfaces below (the
+# rendered tree, the authored catalog, the shipped renderer). Each entry must be anchored at
+# `^/` and continue with LITERAL path characters. This rejects:
+#   `^/`      and `^/.*`   — match every page load, so the UI answers 401 and never signs in
+#   `/api/`               — unanchored; oauth2-proxy would match it mid-path
+#   `.*`                  — everything
+#   `^/api/|^/`           — alternation smuggles breadth past a prefix-only reading
+# Alternation is REFUSED rather than supported because `--api-route` is repeatable: one entry
+# per route costs nothing and each entry stays readable. Kept byte-identical to
+# catalog/render.py's OAUTH2_API_ROUTE_PATTERN and to the schema's items.pattern; assertion (5)
+# below fails if they drift apart.
+ANCHORED = re.compile(r"^\^/[A-Za-z0-9._~/-]+(\.\*|\$)?$")
+SCHEMA_PATTERN = r"^\^/[A-Za-z0-9._~/-]+(\.\*|\$)?$"
+
+
+def read(p: Path) -> str:
+    try:
+        return p.read_text()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def is_test_fixture(p: Path) -> bool:
+    """conformance/tests/**/{golden,fixtures}/** is assertion DATA, not deployed manifests."""
+    parts = p.parts
+    return "conformance" in parts and ("golden" in parts or "fixtures" in parts)
+
+
+def iter_containers(node):
+    """Yield every container mapping under any `containers`/`initContainers` list, at any depth.
+
+    Depth-agnostic on purpose: the same container shape appears under a Deployment, a DaemonSet,
+    a CronJob's jobTemplate or a bare Pod, and a reader that hardcoded one path would silently
+    stop seeing an instance the day one moved.
+    """
+    if isinstance(node, dict):
+        for key, val in node.items():
+            if key in ("containers", "initContainers") and isinstance(val, list):
+                for c in val:
+                    if isinstance(c, dict):
+                        yield c
+            else:
+                yield from iter_containers(val)
+    elif isinstance(node, list):
+        for item in node:
+            yield from iter_containers(item)
+
+
+def api_routes_of(args: list) -> list:
+    """Every `--api-route=<v>` / `--api-route <v>` value, in order. The flag is REPEATABLE, so
+    this must collect ALL of them — a single-value reader would audit the first and wave the
+    rest through, which is the shape of reader bug this file's header warns about."""
+    out = []
+    for i, a in enumerate(args):
+        if not isinstance(a, str):
+            continue
+        if a.startswith("--api-route="):
+            out.append(a.split("=", 1)[1])
+        elif a == "--api-route" and i + 1 < len(args) and isinstance(args[i + 1], str):
+            out.append(args[i + 1])
+    return out
+
+
+# ============================================================ (0) INVENTORY: THE RENDERED TREE
+# Every oauth2-proxy container this repo DEPLOYS, keyed by file + owner, with its api-routes.
+rendered: dict[str, list] = {}
+for p in sorted(ROOT.rglob("*.yaml")):
+    relparts = p.relative_to(ROOT).parent.parts
+    # NESTED WORKTREES: skip dot-DIRECTORIES (.git, .claude) while still matching dot-FILES such
+    # as .sops.yaml. .claude/worktrees/agent-*/ holds full repo copies for isolated agent runs,
+    # so a bare rglob audits up to 18 duplicates of every file — which both invents FAILs and,
+    # worse, can satisfy a "something declares X" check from a copy rather than from real source.
+    if any(part.startswith(".") for part in relparts) or is_test_fixture(p) or ".sops." in p.name:
+        continue
+    txt = read(p)
+    if "oauth2-proxy" not in txt:
+        continue
+    rel = str(p.relative_to(ROOT))
+    try:
+        docs = [d for d in yaml.safe_load_all(txt) if isinstance(d, dict)]
+    except yaml.YAMLError as exc:
+        check(False, f"{rel} is not parseable YAML ({exc}) — any oauth2-proxy instance in it "
+                     f"went unaudited, so a too-broad --api-route could be hiding there")
+        continue
+    for d in docs:
+        for c in iter_containers(d):
+            image = str(c.get("image") or "")
+            name = str(c.get("name") or "")
+            if "oauth2-proxy" not in image and name != "oauth2-proxy":
+                continue
+            owner = (d.get("metadata") or {}).get("name") or "?"
+            args = list(c.get("args") or []) + list(c.get("command") or [])
+            rendered[f"{rel}:{owner}/{name or 'oauth2-proxy'}"] = api_routes_of(args)
+
+check(len(rendered) >= 5,
+      f"only {len(rendered)} oauth2-proxy container(s) parsed out of the tree. This repo "
+      f"deploys more than that (five rendered sidecars plus crafty's hand-authored one), so the "
+      f"inventory has stopped seeing instances and every assertion below would pass vacuously "
+      f"while an unanchored --api-route went unaudited")
+
+# ============================================================ (1) EVERY ROUTE IS ANCHORED
+for key, routes in sorted(rendered.items()):
+    for r in routes:
+        check(bool(ANCHORED.match(r)),
+              f"{key} declares --api-route={r!r}, which is not an anchored path regex.\n"
+              f"       WHY THIS IS WORSE THAN THE BUG IT FIXES: --api-route makes matching paths "
+              f"answer 401 instead of 302ing to Keycloak. A regex that also matches a path a "
+              f"BROWSER NAVIGATES to — `^/`, `^/.*`, `.*`, or an alternation that reaches the "
+              f"UI root — answers a plain PAGE LOAD with 401. A logged-out operator then sees a "
+              f"bare error page and is NEVER OFFERED A SIGN-IN: the service looks permanently "
+              f"broken rather than merely unauthenticated, and no reload can recover it.\n"
+              f"       FIX: anchor it at '^/' followed by literal path characters "
+              f"(e.g. '^/api/', '^/signalr/', '^/api/v3/.*'), one entry per route — the flag is "
+              f"repeatable, so alternation is never needed. For a service rendered from catalog/, "
+              f"do NOT hand-edit the golden: declare auth.apiRoutes and re-render "
+              f"(ci/render-golden.sh's header has the canonical command)")
+
+# ============================================================ (2) DERIVED FROM THE CATALOG
+# The five rendered sidecars are OUTPUTS. Auditing only them would let someone "fix" a golden by
+# hand (reverted by the next render) or make the renderer emit a CONSTANT and regenerate every
+# golden to match — which render-golden cannot see, because render and golden would agree.
+# So: every onboarded forward-auth service's rendered route list must EQUAL its own
+# ServiceDefinition's auth.apiRoutes, in order.
+catalog_dir = ROOT / "catalog"
+declared: dict[str, list] = {}
+forward_auth: list[str] = []
+for sd_path in sorted(catalog_dir.glob("*.yaml")):
+    try:
+        sd = yaml.safe_load(read(sd_path))
+    except yaml.YAMLError as exc:
+        check(False, f"catalog/{sd_path.name} is not parseable YAML ({exc})")
+        continue
+    if not isinstance(sd, dict) or not sd.get("name"):
+        continue
+    auth = sd.get("auth") or {}
+    routes = auth.get("apiRoutes") or []
+    declared[sd["name"]] = list(routes)
+    if auth.get("mode") == "forward-auth" and (sd.get("ingressRoutes") or []):
+        forward_auth.append(sd["name"])
+    for r in routes:
+        check(bool(ANCHORED.match(str(r))),
+              f"catalog/{sd_path.name}: auth.apiRoutes entry {r!r} is not anchored at '^/' "
+              f"followed by literal path characters. See assertion (1) for why breadth here is "
+              f"the dangerous direction. The schema rejects this too (items.pattern); this "
+              f"assertion exists because the schema stage can be SKIPPED and this one cannot")
+    if routes:
+        check(auth.get("mode") == "forward-auth",
+              f"catalog/{sd_path.name} declares auth.apiRoutes with auth.mode="
+              f"{auth.get('mode')!r}. --api-route renders onto the per-app oauth2-proxy sidecar, "
+              f"and no sidecar is rendered for oidc/native/none — so this is a SILENT NO-OP: the "
+              f"operator believes the app's XHRs now answer 401 and nothing changed")
+
+matched = 0
+for name in sorted(forward_auth):
+    golden = next((p for p in sorted(ROOT.glob(f"apps/wave-*/{name}.yaml"))), None)
+    if golden is None:
+        continue                      # catalog service not onboarded to apps/ yet — no golden
+    key = next((k for k in rendered if k.startswith(str(golden.relative_to(ROOT)) + ":")), None)
+    check(key is not None,
+          f"apps/{golden.name} is the golden for forward-auth service {name!r} but no "
+          f"oauth2-proxy container was parsed out of it. Its --api-route configuration is "
+          f"UNAUDITED")
+    if key is None:
+        continue
+    matched += 1
+    check(rendered[key] == declared.get(name, []),
+          f"{name}: the rendered sidecar declares --api-route {rendered[key]!r} but "
+          f"catalog/{name}.yaml declares auth.apiRoutes {declared.get(name, [])!r}.\n"
+          f"       These must be IDENTICAL and in order. A mismatch means one of two things, "
+          f"both bad: a golden was hand-edited (the next re-render silently reverts it), or the "
+          f"renderer is emitting --api-route from somewhere other than this service's own "
+          f"ServiceDefinition — i.e. a constant or a per-service table. A constant is the defect "
+          f"this field exists to prevent: it applies ONE app's path shape to all five, and "
+          f"pihole serves no /api/ at all, so it would answer pihole's page loads with 401. "
+          f"render-golden cannot catch that, because render and golden would agree with each "
+          f"other while both being wrong")
+
+check(matched >= 4,
+      f"only {matched} onboarded forward-auth service(s) were cross-checked against their "
+      f"ServiceDefinition. This repo onboards five, so the catalog<->golden pairing has stopped "
+      f"resolving and assertion (2) is passing vacuously")
+
+# ============================================================ (3) BOTH CASES EXIST
+# Once the tree is consistent, (2) is satisfied by any pairing — including one where NOTHING
+# declares a route (vacuous) or one where EVERYTHING does (so the "renders nothing" path is
+# never exercised). Both halves are asserted to be live, because the per-app field only earns
+# its complexity if both outcomes actually occur in this tree.
+with_routes = [n for n in forward_auth if declared.get(n)]
+without_routes = [n for n in forward_auth if not declared.get(n)]
+check(bool(with_routes),
+      "no onboarded forward-auth service declares auth.apiRoutes, so assertion (2) cannot "
+      "distinguish a working renderer from one that emits the flag nowhere. If the flag is "
+      "genuinely not needed anywhere, delete the field rather than leaving an unexercised seam")
+check(bool(without_routes),
+      "EVERY onboarded forward-auth service declares auth.apiRoutes, so nothing in this tree "
+      "exercises the 'declares none => renders no flag' path. That path is the whole reason the "
+      "field is per-app: pihole serves no /api/, and a renderer-wide default would answer its "
+      "page loads with 401")
+for name in sorted(without_routes):
+    golden = next((p for p in sorted(ROOT.glob(f"apps/wave-*/{name}.yaml"))), None)
+    if golden is None:
+        continue
+    key = next((k for k in rendered if k.startswith(str(golden.relative_to(ROOT)) + ":")), None)
+    if key is None:
+        continue
+    check(rendered[key] == [],
+          f"{name} declares NO auth.apiRoutes but its rendered sidecar carries "
+          f"--api-route {rendered[key]!r}. An app that declares nothing must render NOTHING")
+
+# ============================================================ (4) THE RENDERER DERIVES
+render_py = ROOT / "catalog" / "render.py"
+check(render_py.is_file(),
+      "catalog/render.py is missing — the generator of five of these sidecars cannot be audited")
+if render_py.is_file():
+    src = read(render_py)
+    m = re.search(r"def _oauth2_sidecar_container\(.*?\n(?=\n*def |\n*# =)", src, re.S)
+    fn = m.group(0) if m else ""
+    check(bool(fn),
+          "could not locate _oauth2_sidecar_container() in catalog/render.py. It was renamed or "
+          "removed, so assertion (4) cannot run and the generator is unaudited")
+    if fn:
+        check("--api-route=" in fn,
+              "catalog/render.py's _oauth2_sidecar_container() emits no --api-route at all, so "
+              "every forward-auth app's XHRs are answered with a 302 the browser follows "
+              "invisibly — measured as 33x302-vs-2x401 on jackett and 232x302 on radarr, with "
+              "POST bodies dropped. auth.apiRoutes would then be a field with no consumer")
+        check(not re.search(r'--api-route=\^/[A-Za-z0-9]', fn),
+              "catalog/render.py hardcodes a literal path regex into --api-route. Whatever path "
+              "that is, EVERY forward-auth app now renders it: one app's path shape applied to "
+              "five. pihole serves no /api/, so a constant answers its page loads with 401 and "
+              "the service looks permanently broken to a logged-out operator. Render the routes "
+              "declared in each service's own auth.apiRoutes instead")
+        check("apiRoutes" in fn,
+              "catalog/render.py's _oauth2_sidecar_container() does not read auth.apiRoutes, so "
+              "the per-app declaration has no effect on what is rendered")
+
+# ============================================================ (5) ONE PATTERN, THREE SURFACES
+# The ratchet is written in three places (this check, the renderer, the schema) because each
+# guards a surface the others cannot. If they drift apart, the loosest one wins silently.
+if render_py.is_file():
+    # The renderer writes the pattern as a raw string literal, so the source text contains it
+    # verbatim. A substring test is deliberate: it also catches a rename of the constant.
+    check(SCHEMA_PATTERN in read(render_py),
+          f"catalog/render.py no longer contains the anchoring pattern {SCHEMA_PATTERN!r} that "
+          f"this check and the schema enforce. Three surfaces guard --api-route breadth (the "
+          f"authoring surface via the schema, the render via the renderer, the tree via this "
+          f"check); if they drift apart the loosest wins and the ratchet is decorative")
+
+# The schema's pattern is read from the PARSED JSON, not from the file text: in the file its
+# backslashes are JSON-escaped, so a substring test against the raw bytes would compare the
+# wrong string and pass or fail for the wrong reason.
+schema_file = ROOT / "schemas" / "servicedefinition.schema.json"
+schema_pat = None
+if schema_file.is_file():
+    try:
+        schema_pat = (((((json.loads(read(schema_file)).get("properties") or {})
+                         .get("auth") or {}).get("properties") or {})
+                       .get("apiRoutes") or {}).get("items") or {}).get("pattern")
+    except (ValueError, AttributeError) as exc:
+        check(False, f"schemas/servicedefinition.schema.json could not be read as JSON ({exc}) — "
+                     f"the schema stage that rejects a too-broad --api-route cannot be audited")
+check(schema_pat == SCHEMA_PATTERN,
+      f"schemas/servicedefinition.schema.json constrains auth.apiRoutes items with "
+      f"{schema_pat!r}, not {SCHEMA_PATTERN!r}. The schema is the only surface that rejects a "
+      f"too-broad regex WHERE A HUMAN TYPES IT (ci/l0.sh validates catalog/*.yaml on every gate "
+      f"run); if it is absent or looser than the renderer's, the operator finds out from a 401 "
+      f"on a page load")
+
+# ============================================================ (6) PROVE THE SHIPPED RENDERER
+# Once the tree is compliant, (1)-(3) have nothing left to catch and their passing is evidence
+# of nothing. This runs the SHIPPED renderer as a SUBPROCESS on synthetic ServiceDefinitions and
+# asserts the behaviour directly, in BOTH directions, so the guard stays falsifiable.
+def _sd(name: str, port: int, routes) -> str:
+    auth = {"mode": "forward-auth", "groups": ["platform-admins"]}
+    if routes is not None:
+        auth["apiRoutes"] = routes
+    return yaml.safe_dump({
+        "name": name,
+        "kind": "container",
+        "source": {"image": "example/app:1"},
+        "exposure": "internal",
+        "ingressRoutes": [{"host": f"{name}.home.keithjackson.dev", "port": port}],
+        "auth": auth,
+    }, sort_keys=False)
+
+
+def _render(name: str, port: int, routes):
+    with tempfile.TemporaryDirectory() as td:
+        f = Path(td) / f"{name}.yaml"
+        f.write_text(_sd(name, port, routes))
+        return subprocess.run([sys.executable, str(render_py), str(f)],
+                              capture_output=True, text=True)
+
+
+def _sidecar_args(rendered_yaml: str) -> list:
+    for doc in yaml.safe_load_all(rendered_yaml):
+        if not isinstance(doc, dict) or doc.get("kind") != "Deployment":
+            continue
+        for c in iter_containers(doc):
+            if c.get("name") == "oauth2-proxy":
+                return list(c.get("args") or [])
+    return []
+
+
+if render_py.is_file():
+    # (6a) DECLARED ROUTES RENDER, IN ORDER, AND NOTHING ELSE DOES.
+    proc = _render("apirtdecl", 8121, ["^/api/", "^/signalr/"])
+    check(proc.returncode == 0,
+          f"the shipped catalog/render.py failed on a synthetic forward-auth fixture declaring "
+          f"two apiRoutes: rc={proc.returncode} {proc.stderr.strip()[:300]}")
+    if proc.returncode == 0:
+        got = api_routes_of(_sidecar_args(proc.stdout))
+        check(got == ["^/api/", "^/signalr/"],
+              f"the shipped renderer turned auth.apiRoutes ['^/api/', '^/signalr/'] into "
+              f"--api-route {got!r}. It must emit one repeatable --api-route per entry, in "
+              f"declared order. Note the flag is SINGULAR: --api-routes does not exist in "
+              f"oauth2-proxy v7.8.1 and the proxy REFUSES TO START with it, so a plural would "
+              f"crashloop every sidecar it rendered")
+
+    # (6b) AN APP THAT DECLARES NOTHING RENDERS NOTHING. The pihole case, proven on the
+    #      generator rather than inferred from one committed golden.
+    for label, routes in (("absent", None), ("empty", [])):
+        proc = _render(f"apirtnone{label}", 8122, routes)
+        check(proc.returncode == 0,
+              f"the shipped renderer failed on a synthetic forward-auth fixture with apiRoutes "
+              f"{label}: rc={proc.returncode} {proc.stderr.strip()[:300]}")
+        if proc.returncode == 0:
+            got = api_routes_of(_sidecar_args(proc.stdout))
+            check(got == [],
+                  f"the shipped renderer emitted --api-route {got!r} for a synthetic service "
+                  f"whose auth.apiRoutes is {label}. A newly-onboarded forward-auth app must "
+                  f"render NO --api-route: pihole serves no /api/, so a default would answer "
+                  f"its page loads with 401 and the service would look permanently broken to a "
+                  f"logged-out operator — a worse failure than the 302 bug the flag fixes")
+
+    # (6c) THE RENDERER REFUSES BREADTH. Asserted on the generator because render-golden runs
+    #      on every gate invocation while the schema stage can be skipped.
+    for bad in ("^/", "^/.*", ".*", "/api/", "^/api/|^/"):
+        proc = _render("apirtbad", 8123, [bad])
+        check(proc.returncode != 0,
+              f"the shipped renderer ACCEPTED auth.apiRoutes {bad!r} and rendered a sidecar. "
+              f"That regex matches paths a browser NAVIGATES to, so a plain page load answers "
+              f"401 and the operator is never offered a sign-in. The renderer must refuse it, "
+              f"so a breadth mistake fails render-golden even on a run where the schema stage "
+              f"did not execute")
+
+# ============================================================ VERDICT
+inv = " | ".join(f"{k} -> {v or '(none)'}" for k, v in sorted(rendered.items()))
+print(f"oauth2-proxy sidecars audited ({len(rendered)}): {inv}")
+if FAILURES:
+    print(f"\nCHECK FAIL (oauth2-proxy-api-routes-per-app): {len(FAILURES)} failed, "
+          f"{CHECKS - len(FAILURES)} passed", file=sys.stderr)
+    for f in FAILURES:
+        print(f"  FAIL {f}", file=sys.stderr)
+    raise SystemExit(1)
+print(f"check OK: oauth2-proxy-api-routes-per-app — {CHECKS} assertions (R-IDP-02)")
+PY

decisions/2026-10-01-admin-approval-override.md

@@ -0,0 +1,185 @@
+---
+date: 2026-10-01
+branch: fix/admin-approval-override
+title: Administrators can merge their own green PR — required_approvals 1 → 0, plus an attributed /approve-override for sensitive paths
+---
+
+## What changed
+
+**The problem, measured first.** `required_approvals: 1` on `main` was a lock-out, not a
+protection. Gitea refuses to let a pull request's author approve their own PR, and `jakman85` is
+the **only** collaborator (permission `owner`). So no account in existence could approve a PR the
+operator opened. Measured on the live API, 2026-10-01:
+
+| | |
+|---|---|
+| PR #35 (`bugfix/arr-to-plex`, author `jakman85`) | `gate / gate (pull_request)` = **success, 1m41s** |
+| its reviews | `[]` |
+| live `required_approvals` | `1` |
+| live `block_admin_merge_override` | `true` |
+
+Green gate, zero reviews, no path to a merge — and the same was true of any PR that would have
+fixed it.
+
+It was also never the design this repo wrote down. `ci/approval-policy.sh`'s own header and
+`ci/gate.sh:194` both already described the model as *"`required_approvals` drops to 0 and the
+GATE decides"*, and `infra/gitea/require-gate.sh`'s closing note named this exact failure and
+prescribed this exact remedy. `decisions/2026-09-30-flux-deploy-notification-inhibited.md` had
+flagged the 1-vs-0 disagreement as unresolved and not that session's to settle. This settles it
+at 0.
+
+**Two layers were blocking, and both are addressed.**
+
+*Layer 1 — Gitea branch protection.* `required_approvals: 1 → 0` in
+`infra/gitea/expected-branch-protection.json`, with the rationale in the file, plus
+`infra/gitea/allow-admin-self-merge.sh` to apply it to the live rule (it reads the target **from
+the declaration**, so the script cannot drift from what the gate checks). `require-gate.sh` was
+changed to 0 as well — left at 1 it would silently re-impose the lock-out on its next run.
+
+The narrow choice matters: the *other* way to unblock an owner is
+`block_admin_merge_override: false`, and that would have re-opened precisely what
+`infra/gitea/block-admin-override.sh` was written to close (PRs #5–#9 merged with zero approvals
+while the settings read as enforced). This change drops the approval **count** only.
+`block_admin_merge_override` and `enable_status_check` both stay `true`, and the script asserts
+both afterwards and fails loudly if the PATCH disturbed either. **A red gate remains unmergeable
+by everyone, administrators included.**
+
+*Layer 2 — `ci/approval-policy.sh`.* Sensitive paths (`ci/**`, `infra/gitea/**`, `CLAUDE.md`,
+kyverno, rbac, sops, Flux wiring) still require a non-author `APPROVED` review, which the sole
+administrator still cannot obtain. An administrator may now waive it by commenting on the PR:
+
+    /approve-override <reason>
+
+- the directive must **start a line** (a quoted or mid-sentence mention does not count, or
+  repeating someone else's override would re-arm it);
+- a **reason is mandatory** — a bare directive records that review was waived but not why;
+- the commenter's permission is **re-checked live** against
+  `/collaborators/{login}/permission` when the gate runs, so an old comment from a demoted
+  account carries nothing;
+- it is **invalidated by a new commit** (the comment must post-date the head commit), mirroring
+  Gitea's own `dismiss_stale_approvals`;
+- the overrider, timestamp and reason are printed in the gate log and the job summary, and a
+  self-waiver by the PR's own author is called out as such.
+
+Selection of the candidate comment is `ci/approval-override.py` — pure, offline, no authority of
+its own — so it could be unit-tested; authorisation stays in the fail-closed stage.
+`ci/tests/approval-override.test.sh` adds **23 assertions**, all passing, each constructing a
+case the parser must refuse. Every new failure mode blocks: unreadable head-commit timestamp,
+unreadable permission, parser error.
+
+**The cost, stated rather than buried.** For an administrator, *"a change to the gate cannot be
+gated by the gate"* is now **advisory, not structural**. That is unavoidable with one human — the
+alternative is a repository its owner cannot change — and what is bought back is an attributed,
+reasoned, commit-scoped record of each waiver instead of a silent bypass.
+
+**The uncomfortable part, accepted with eyes open (operator decision).** Authorisation is by live
+permission **alone**, with no allowlist of human accounts. The **agent account `gitea-admin` also
+reports permission `owner`** on this repo (measured), so an agent *can* clear the sensitive-path
+review on its own PR — and agents author most PRs here, so that is the common case, not an edge
+case. I raised this before implementing; the operator chose permission-only. It is documented in
+three places rather than left to be discovered: `approval-policy.json`
+(`_known_consequence_agent_accounts`), the stage's header, and `CLAUDE.md`, which now tells
+agents plainly **not** to use it on their own work. The narrowing path needs no code change —
+add an `override_admins` list to `approval-policy.json` and the stage already requires membership
+in addition to the permission check.
+
+Also updated: `CLAUDE.md` §1 and the §2 enforcement table (the "approval required" row is now
+explicitly ⬜ with the reason, rather than a stale ✅), and `infra/gitea/README.md` gains §6 and
+marks its historical step 4 as reversed — do not re-apply.
+
+**One adjacent fix, deliberately in scope: `ci/tests/gate-decision.test.sh` was already broken.**
+It hand-maintains a list of stub stage scripts that "must name EVERY stage `gate.sh` runs", and it
+did not name `approval-policy` — added to `gate.sh` by PR #17 and never added here. `run_stage`
+therefore got exit 127 from a missing file and recorded a FAILED stage in every case, so **15 of
+50 assertions failed**, including every one expecting a PASS/UNDETERMINED headline. Measured on
+pristine `origin/main` (`0c7e8dd`) before touching it, so the attribution is not a guess.
+
+I fixed it because `make -C ci test` is the *only* runner for the suite this change adds — leaving
+it red would have made the new tests unverifiable in practice. The file's own comment already
+narrated this exact failure for `gitea-settings` and did not prevent the repeat, which says the
+comment was not the fix. So the stub list is now **derived from `gate.sh`'s own `run_stage` lines**
+and asserts it parsed at least 8 of them: a stage added to the gate can no longer be silently
+missing from its test. `make -C ci test` goes from **FAILED to all suites passed**.
+
+## What I verified
+
+- **The lock-out is real, and PR #35 is the proof.** Queried live: head sha
+  `8a094c46`, statuses `gate / gate (pull_request) = success :: Successful in 1m41s`,
+  `/pulls/35/reviews` → `[]`, `/branch_protections/main` → `required_approvals: 1`. I read the
+  **rule object**, not `/branches/main`, per §2b.
+- **`jakman85` is the only collaborator**: `/collaborators` → one entry. Permission `owner`.
+- **`gitea-admin` also reports `owner`** — this is why the agent-account consequence above is a
+  statement of fact and not a hypothetical.
+- **PR #35 touches no sensitive paths** (`apps/wave-0/plex.yaml`, `apps/wave-1/{radarr,sonarr}.yaml`,
+  `catalog/{radarr,sonarr}.yaml`, its decisions entry) — so `ci/approval-policy.sh` was never its
+  blocker. Layer 1 alone unblocks it.
+- **API shapes verified before depending on them**, rather than assumed: `/git/commits/{sha}`
+  returns `.commit.committer.date` as RFC3339 **with an offset** (`2026-10-01T23:09:08-05:00`),
+  not a trailing `Z` — a parser handling only `Z` would have silently dropped every real
+  override, so there is a test for the offset form. PR conversation comments are under
+  `/issues/{n}/comments`; `/pulls/{n}/comments` returns diff comments only and would never have
+  seen an override.
+- **`ci/tests/approval-override.test.sh`: 23 passed, 0 failed.** Covers the happy path, bare
+  directive, mid-sentence and `>`-quoted directives, stale and equal-timestamp overrides,
+  unparseable timestamps, missing login, invalid JSON, non-list JSON, latest-wins, offset
+  timestamps, and a configurable directive.
+- `bash -n` clean on `ci/approval-policy.sh`, `infra/gitea/allow-admin-self-merge.sh`,
+  `infra/gitea/require-gate.sh`; `jq -e .` clean on both JSON declarations.
+- **`gate-decision.test.sh`'s 15 failures are pre-existing, measured not assumed.** Extracted
+  `origin/main`'s `ci/` at `0c7e8dd` into a throwaway directory and ran the suite from there:
+  **FAIL, 15 failed / 35 passed**. After deriving the stub list from `gate.sh`: **PASS, 50
+  assertions**.
+- **`make -C ci test` in the pinned toolbox: `ci/tests: all suites passed`, rc 0** — approval-override
+  23, gate-decision 50, touched-requirements-base 31, test-attribution 15, touched-requirements 26,
+  decisions-log pass. It was rc 2 (`ci/tests: FAILED`) before the stub-list fix.
+- **Toolbox merge gate** (`./infra/devcontainer/dev.sh run bash -c './ci/gate.sh'`), run on the
+  rebased branch: **rc 3, `MERGE GATE: UNDETERMINED`**. Green stages: spec-immutability,
+  decisions-log, lint, l0 (23 offline cases, 0 failures), render-golden including the new
+  `catalog/render.py --selftest`, l1 (3 cases), approval-policy (N/A offline). Skipped:
+  `gitea-settings` (no `SETTINGS_API_TOKEN` on this host) and `conformance` (no cluster).
+  **This is NOT a green run and I am not reporting it as one** — rc 3 is UNDETERMINED per the
+  CLAUDE.md §3 contract.
+
+## What I did NOT verify
+
+- **The live Gitea rule still says `required_approvals: 1`. I did not change it.** Mutating live
+  platform settings is an operator action; `infra/gitea/allow-admin-self-merge.sh` is written,
+  syntax-checked, and **unrun**. The declaration and the live rule must move together.
+  *Now measured, not predicted:* PR #38's CI run (run 202, job 0) fails at **1m44s** with
+  `required_approvals: DECLARED 0 but LIVE is 1` → `gitea-settings: FAIL`. Correct behaviour, and
+  the PR stays red until the script is run.
+- **The override has never been ACCEPTED by a real run** — only offered. Measured in the same CI
+  log: the stage reached `approval-policy: FAIL` on the sensitive paths and printed the *new*
+  code's guidance, `Or, if you hold admin/owner on this repository, comment on the PR:
+  /approve-override <reason> ... NEWER than head commit 7b9f733c`. So the new stage **is** what
+  runs on this PR (self-bootstrapping confirmed by measurement, not by reasoning), and the
+  authorising branch — comment parse → live permission lookup → exit 0 — is still **unexercised**.
+  Posting the comment on PR #38 is its first real test. If it does not work, the recovery is to
+  PATCH `required_approvals` and read run 202's successor log.
+- **I have not seen the gate still REFUSE a merge** now that approvals are 0. The claim that
+  `block_admin_merge_override: true` keeps a red gate unmergeable rests on Gitea's documented
+  behaviour and on the 2026-09-29 session, **not** on a provoked refusal in this one. That probe
+  is written out at the foot of `allow-admin-self-merge.sh` and should be done, exactly as the
+  push rejection was provoked rather than assumed.
+- **Clock skew in the staleness check is unhandled.** Staleness compares the comment's
+  server-side `created_at` against the head commit's *committer* date, which comes from the
+  committer's machine. A commit dated in the future would reject legitimate overrides until real
+  time catches up (fail-closed, so loud, but annoying). Gitea's own `dismiss_stale_approvals`
+  compares SHAs instead; a comment cannot. Not hit here — PR #35's commit date is ~21 min behind
+  server time — and not fixed.
+- **`ci/tests/approval-override.test.sh` does not run in the merge gate.** `ci/gate.sh` runs no
+  `ci/tests/*`; they run only via `make -C ci test`. So a regression in the parser would not be
+  caught by CI. PR #33 (merged while this branch was being written, and rebased onto here) fixed
+  the *same class* of gap for `catalog/render.py --selftest` by invoking it from
+  `ci/render-golden.sh` — it did **not** wire `ci/tests/*` in, which I confirmed after rebasing
+  rather than assuming. Wiring them is a one-line stage and I did not widen scope to it.
+- **Authorisation itself is untested code.** `ci/approval-override.py` is unit-tested; the live
+  permission lookup, the `override_admins` allowlist branch, and every new BLOCK path in
+  `ci/approval-policy.sh` need Gitea and have never been exercised. The allowlist branch in
+  particular is implemented but **unused** — `override_admins` is absent by design.
+- **The other open PRs will go red** once the live value changes, until they are rebased onto the
+  merged declaration: as of writing those are **#29** and **#37** (both `gitea-admin`), plus
+  **#35**. I did not rebase them. Merging them first avoids it entirely; the script's header gives
+  the order. PRs #33, #34 and #36 merged while this branch was being written — this branch is
+  rebased onto `0c7e8dd`, so the list was re-measured rather than carried forward.
+- No cluster state was read or changed; nothing here touches Flux, Kyverno or any workload.

decisions/2026-10-01-intel-gpu-device-plugin.md

@@ -0,0 +1,198 @@
+---
+date: 2026-10-01
+branch: feat/intel-gpu-device-plugin
+title: Intel GPU device plugin, in its own Kustomization — the resource exists; nothing has run yet
+---
+
+## What changed
+
+Deployed the **Intel Device Plugin for Kubernetes (GPU)**, standalone DaemonSet, pinned at
+**v0.37.0**, so the prod nodes advertise `gpu.intel.com/i915`. This is the measured fix for the
+Plex hardware-transcoding blocker: the `/dev/dri` hostPath merged on `main` @ `cdf3e14` makes the
+device node *visible* and not *openable* (`EPERM` from the device cgroup at both uid 0 and uid
+1000; the container's runc `config.json` carries one deny-all rule and `linux.devices: None`). A
+hostPath is a filesystem operation and adds no cgroup allow rule. A device plugin's `Allocate`
+response is what makes kubelet populate `linux.devices` *and* the matching cgroup allow rule, and
+it is the only non-privileged way to get there — `privileged: true` is blocked by Kyverno
+`restrict-host-namespaces` under Enforce in app namespaces, and `plex` is labelled
+`app-namespace=true`.
+
+New files:
+
+- `platform/intel-gpu-plugin/intel-gpu-plugin.yaml` — the DaemonSet, **vendored** as
+  `kubectl kustomize` output of upstream `deployments/gpu_plugin/base` at `v0.37.0`, under a
+  provenance header carrying the exact re-vendor command and both sha256s (generated body
+  `80ebd070…`, raw upstream source `c8773918…`). Generated rather than byte-copied because
+  upstream mixes YAML sequence-indentation styles within the one document and `ci/yamllint.yaml`
+  sets `indent-sequences: consistent` — a verbatim copy is a hard lint error that blocks the gate.
+  That is not a guess: the first gate run of this branch returned **rc 1 BLOCKED** on exactly that
+  error, and regenerating through kustomize is the fix (and is also the re-vendor idiom
+  `platform/external-snapshotter` documents). Vendored at all, rather than referenced as a remote
+  kustomize base, for the other reason `external-snapshotter` records: a remote base is
+  `git fetch`ed on every reconcile and those fetches have flaked a whole tier.
+- `platform/intel-gpu-plugin/namespace.yaml` — a PLATFORM namespace, explicitly
+  `homelab.keithjackson.dev/app-namespace: "false"` (following `vpn-egress`/`kyverno`).
+- `platform/intel-gpu-plugin/kustomization.yaml` — namespace scoping plus the image pin.
+- `platform/intel-gpu-plugin/README.md` — the measurement, the placement argument, the
+  non-choices, and the post-merge verification sequence.
+- `clusters/base/intel-gpu-plugin.yaml` — **its own Flux Kustomization**: `dependsOn: [cilium]`,
+  `wait: true`, `interval: 10m`, `timeout: 10m`, `prune: true`.
+- One wired line (plus its rationale comment) in `clusters/base/kustomization.yaml`.
+
+**Placement: its own Kustomization, not a line in the shared `platform` tier.** The shared tier was
+cheaper and needed no human reviewer on `approval-policy.json`'s terms, but `platform` is
+`wait: true` over eleven-plus components and the repo already argued this case when Cilium was
+split out: its Ready condition cannot distinguish "the plugin is wedged" from "longhorn is slow",
+the only emergency valve is freezing the entire tier, and the tier's 10m/5m interval/timeout are
+called out there as *wrong for a 3-node DaemonSet rollout* — which is exactly what this is. The
+consequence is worse than average here, because `platform` gates `platform-config` gates
+`apps-wave-0` (`wait: true`) gates `apps-wave-1`: a plugin that never went healthy inside that tier
+would stall every app, so a component added to fix a **silent no-op** would have gained the ability
+to cause a **real outage**. The approval cost of touching `clusters/**` is nil, because
+`required_approvals: 1` with `block_admin_merge_override: true` applies to every PR here regardless
+of path and authors cannot self-approve.
+
+`dependsOn: [cilium]` is the minimum *and* the earliest: the plugin never uses the network and
+never talks to the API server (it talks to the local kubelet over a unix socket), so a working CNI
+is its only real prerequisite, and `cilium` already depends on `flux-system`, which applies the
+`cluster-vars` ConfigMap this Kustomization substitutes from. Depending on `cilium` rather than
+`platform` also means it reconciles *in parallel with* the platform tier rather than behind all
+eleven of its components, which shrinks the cold-start window in which a node has not yet
+advertised the resource.
+
+`wait: true` is a deliberate departure from the `headlamp`/`crafty` leaf template. Those use
+`wait: false` because a leaf UI can be legitimately not-Ready for a long time during a cold start,
+making its health a useless signal. This DaemonSet reads sysfs and opens a socket, so not-Ready
+genuinely means broken — and since **nothing in the graph `dependsOn` it** (verified against the
+rendered graph), `wait: true` gates nothing while turning
+`flux get kustomization intel-gpu-plugin` into a one-line answer to the question that must be
+answered before the consumer PR may merge.
+
+Deliberate non-choices, each argued in the README: standalone DaemonSet rather than the operator
+(no CRD, no controller-manager, no cert-manager webhook, no second namespace to keep healthy);
+`--shared-dev-num` left at the upstream default of 1 (a higher count is a lie the scheduler
+believes — there is no GPU-side partitioning behind it, so it converts a loud "Unschedulable" into
+a quiet "transcodes are slow"); `--health-management` left OFF, because it is the one flag that
+*would* open a device and would reintroduce the exact `EPERM` this fixes; no NFD overlay (all three
+nodes are identical); no `supplementalGroups` anywhere, because the `pms-docker` cont-init hook
+already adds the `plex` user to each device's group and that works identically on a
+plugin-injected device.
+
+**Scope held deliberately:** `catalog/render.py`, `catalog/plex.yaml` and `apps/wave-0/plex.yaml`
+are untouched. Switching Plex from the hostPath to a `gpu.intel.com/i915: 1` request is a strictly
+later PR, and **it must not land until this plugin is merged AND confirmed advertising the resource
+on all three nodes** — a request for a resource no node advertises makes the Plex pod
+Unschedulable, and `apps-wave-0` is `wait: true` with `apps-wave-1` depending on it, so that would
+stall the whole app tier and turn today's silent no-op into a real outage.
+
+## What I verified
+
+Mechanism, read from the v0.37.0 source rather than assumed:
+
+- **The plugin only lists devices; it never opens one.** The scan path uses `os.ReadDir`,
+  `os.ReadFile`, `os.Stat` and `os.Readlink` over `/sys/class/drm` and `/dev/dri`. `grep` for
+  `os.Open|OpenFile|ioctl|syscall|unix\.` across `cmd/gpu_plugin/gpu_plugin.go` (908 lines) returns
+  **nothing**. Listing and `stat()` are what demonstrably work today, so the plugin needs no cgroup
+  grant and no extra privilege — it does not need more than the upstream manifest gives it.
+- **The fix mechanism is real:** `createDeviceSpecsFromDrmFiles` emits
+  `pluginapi.DeviceSpec{HostPath, ContainerPath, Permissions: "rw"}` per DRM node, which is the
+  thing kubelet turns into `linux.devices` plus a cgroup allow rule.
+- **The resource name is `gpu.intel.com/i915` by derivation, not by hope:** `scan()` calls
+  `devTree.AddDevice(devProps.driver(), ...)`, so the suffix is the kernel driver name, and these
+  nodes have `i915` bound.
+- `--shared-dev-num` default is `1` (`flag.IntVar(..., 1, ...)`); `--health-management` default is
+  `false` and `setupLevelZeroService` returns early unless it is set.
+- Missing `/dev/dri/by-path` is non-fatal (`newDevicePlugin` warns, sets `bypathFound = false`).
+
+Image pin, verified against the registry:
+
+- `docker.io/intel/intel-gpu-plugin:0.37.0` exists; manifest digest
+  `sha256:7001200071db10587fc31184eedda4f5cf291efba737adf85a8c80539f7fa5e1` (single amd64
+  manifest, not an index), fetched from `registry-1.docker.io` on 2026-10-01. `v0.37.0` is the
+  latest upstream release (2026-09-16) and is not a prerelease.
+- The Docker Hub tag list carries `0.35.0 / 0.36.0 / 0.37.0` — **image tags have no `v` prefix**
+  while GitHub release tags do.
+
+Policy scope, read from the policies rather than assumed:
+
+- All four app-scoped Kyverno policies (`restrict-host-namespaces`, `require-egress-class-label`,
+  `require-auth-mode-label`, `require-default-deny-baseline`) are gated on
+  `namespaceSelector`/`selector` `matchLabels: homelab.keithjackson.dev/app-namespace: "true"`.
+  The new namespace is labelled `"false"`, so none of them match it.
+- Measured on prod: `plex` **is** `app-namespace=true`, confirming `privileged: true` is genuinely
+  unavailable there; `kyverno` and `vpn-egress` are the two namespaces carrying the label as
+  `"false"`; the other platform namespaces leave it unset. No `intel*` namespace exists, so no
+  collision.
+
+Cluster before-state (read-only, `kubectl` in the pinned toolbox with the prod kubeconfig
+bind-mounted read-only — never copied into the worktree):
+
+- Three nodes `k3s-prod-{1,2,3}`, each `v1.36.4+k3s1`, Debian 13 trixie, `containerd://2.3.4-k3s1.36`.
+- Every extended resource currently advertised is `devices.kubevirt.io/{kvm,sev,tun,vhost-net}` on
+  all three nodes. **No node advertises `gpu.intel.com/*`** — queried explicitly, returned
+  "NONE". That is the before-state this change is meant to move.
+- Those `devices.kubevirt.io/*` resources are themselves advertised by a device plugin, which is
+  measured evidence that the device-plugin API and the default kubelet socket path
+  (`/var/lib/kubelet/device-plugins`) work on these nodes.
+
+Offline rendering (the main proof available to a PR):
+
+- `kubectl kustomize platform/intel-gpu-plugin` renders two objects: `Namespace/intel-gpu-plugin`
+  carrying `app-namespace=false`, and `DaemonSet/intel-gpu-plugin` in namespace
+  `intel-gpu-plugin`, with the image resolved to `docker.io/intel/intel-gpu-plugin:0.37.0`.
+- `kubectl kustomize clusters/base` renders, and the new Flux Kustomization appears as
+  `intel-gpu-plugin  ./platform/intel-gpu-plugin  wait=true  dependsOn=cilium`. Both overlays
+  (`clusters/prod`, `clusters/dev`) also render and carry it.
+- Across the whole rendered graph, **no Kustomization lists `intel-gpu-plugin` in `dependsOn`** —
+  so `wait: true` gates nothing.
+- The vendored DaemonSet is a **formatting-only** transform of upstream, proven rather than
+  asserted: `yq -P 'sort_keys(..)'` of the generated file and of the raw upstream file `diff`
+  clean, so passing it through kustomize changed no content. The committed body's sha256 matches
+  the one recorded in its own provenance header (`80ebd070…`), so the file has not drifted from
+  what was generated.
+
+Gate (pinned toolbox, from this worktree, with the `ENGINE` shim bind-mounting the main checkout's
+gitdir and `DEV_KUBECONFIG=/dev/null`): see the PR description for the per-stage table. **`rc 3`
+(UNDETERMINED), with exactly the three expected skips** — `spec-immutability` (sibling spec repo is
+not beside a worktree), `gitea-settings` (no CI token), `conformance` (no cluster in CI). Every
+other stage passed. **rc 3 is not green** and is not reported as such.
+
+## What I did NOT verify
+
+**Nothing about this component's runtime behaviour. It has never run.**
+
+- **The plugin has never executed.** No pod has been scheduled, no image has been pulled, no scan
+  has happened. It cannot run until the operator merges this and Flux reconciles — `kubectl apply`
+  and `flux reconcile` are operator actions (CLAUDE.md §5), so this is expected, not an oversight.
+- **The resource has never been advertised.** `gpu.intel.com/i915` does not exist on any node and
+  I have not seen it exist. The claim that it *will* be `i915` rather than `xe` is derived from
+  source plus the established fact that `i915` is bound — it is a derivation, not an observation.
+- **The DaemonSet has never been admitted.** That the Kyverno policies do not match this namespace
+  is read off the policy manifests; no admission request has actually been evaluated. Nor has the
+  `kubectl kustomize` output ever been server-side dry-run against the API — rendering is not
+  admission.
+- **The `open()` test has NOT been re-run.** The `EPERM` is exactly as it was. Nothing in this PR
+  touches Plex, so Plex is still software-transcoding and will continue to until the later renderer
+  PR lands. The decisive evidence is an `open()` as **uid 1000 through `s6-setuidgid plex`**;
+  passing as uid 0 is weaker and must not be accepted as proof.
+- **A green gate proves the manifests render, nothing more.** And this gate was not green: it was
+  `rc 3`. Note also that the Gitea `gate` job runs `./ci/gate.sh || [ "$?" -eq 3 ]`
+  (`.gitea/workflows/gate.yml:138`), so a green tick on this PR cannot distinguish rc 0 from rc 3,
+  and `vars.CLUSTER_AVAILABLE` is unset so no L2/L3 conformance runs in CI.
+- **`seLinuxOptions: type: container_device_plugin_t`** is carried verbatim from upstream. These
+  nodes are Debian 13 and I did not measure whether SELinux is enabled or whether that type exists
+  there. Expected to be inert (runc skips labelling when SELinux is disabled), but unverified — if
+  the pods fail to start with an SELinux error, that line is the first suspect.
+- **Renovate has not been run** against this pin. The inline-marker idiom is copied from
+  `platform/kubevirt` / `platform/external-snapshotter`, but whether Renovate normalises the
+  `v`-prefix mismatch (release `v0.37.0` vs image `0.37.0`) for this dep is unknown. If it proposes
+  `newTag: v0.38.0`, the fix is an `extractVersion` packageRule in `renovate.json`.
+- **Resource limits unexamined under load.** The upstream 115Mi/100m limits are taken as-is; I have
+  no measurement of this plugin's footprint on these nodes. Worth a glance given
+  `keycloak-operator` is OOMing at 91% of its limit elsewhere in this cluster.
+- **`clusters/dev` renders it, and there is no dev cluster** (the operator confirmed the
+  `k3s-dev-*` nodes are gone). That is inert rather than wrong — the unified graph (R-ENV-02) has
+  both overlays render the same base — but it is not a thing I could test.
+- **Branch protection / required-checks state not re-measured** in this session. CLAUDE.md §2b
+  says re-measure before relying on it; I did not, so treat the approval/gating claims in §2 as
+  unconfirmed-by-me.

decisions/2026-10-01-oauth2-proxy-api-route-per-app.md

@@ -0,0 +1,482 @@
+---
+date: 2026-10-01
+branch: feat/oauth2-proxy-api-route-per-app
+title: The config model had no way to say "this app's API lives here" — so --api-route could not ship. Now it can, per app.
+---
+
+## What changed
+
+Second half of PR #28 (`decisions/2026-09-30-oauth2-proxy-cookie-collision-fleet.md`), which
+fixed the cookie collision, the 5-minute session and the missing metrics listener in one renderer
+function and **deliberately declined `--api-route`** for a reason I have preserved rather than
+worked around: that flag was measured on **one** app, and `PiHole serves no /api/ at all`, so a
+renderer-wide constant would apply one app's path shape to five. The `auth` block is
+`additionalProperties: false`, so there was no per-app override hook. **Creating the hook was the
+work; setting the flag is the easy part.**
+
+**Three surfaces, in order of what they protect:**
+
+| Surface | Change | What it guards that the others cannot |
+|---|---|---|
+| `schemas/servicedefinition.schema.json` (**1.8.0 → 1.9.0**) | new optional `auth.apiRoutes`: array of anchored path regexes, `uniqueItems`, default `[]` | rejects a too-broad regex **where a human types it** — `ci/l0.sh` validates `catalog/*.yaml` against this schema on every gate run |
+| `catalog/render.py` | emits one `--api-route=<r>` per declared entry, in order; **raises** on an unanchored entry | `ci/render-golden.sh` runs on every gate invocation even when the schema stage skips |
+| `conformance/tests/l0-static/oauth2-proxy-api-routes-per-app/` (new) | cross-checks each rendered sidecar against its own ServiceDefinition | catches a **renderer constant**, which neither of the above can see |
+
+**The `auth` block stays `additionalProperties: false`.** One named, documented key was added; the
+door is not opened. That property is the reason the gap existed, and it is worth keeping — it is
+what made "there is no override hook" a *fact* rather than a *guess* for the two engineers who hit
+it before me.
+
+**Rebased mid-flight.** `origin/main` advanced from `08deb20` to `cdf3e14` while I was working
+(PR #27 and PR #32, the `hardware.gpu: intel-quicksync` capability). **That change also took schema
+`1.8.0`**, so mine is renumbered to **1.9.0** and chained behind it; both version entries are
+present in the description, and `catalog/render.py` had a two-sided conflict in the constants block
+which is resolved by keeping both (the `DRI_*` constants and `OAUTH2_API_ROUTE_PATTERN` are
+unrelated). Re-rendering after the rebase still changes **only** jackett and radarr — plex's new
+golden reproduces byte-identically, so the two changes do not interact.
+
+**Shape:** a **list** of regexes, not a single string, because Radarr needs two
+(`^/api/` and `^/signalr/`) and `--api-route` is natively repeatable. A single string would have
+forced alternation into the value, and alternation is exactly how breadth gets smuggled past a
+prefix-only reading of a regex.
+
+**The anchoring ratchet.** Each entry must match `^\^/[A-Za-z0-9._~/-]+(\.\*|\$)?$` — anchored at
+`^/`, then literal path characters, with an optional trailing `.*` or `$`. The same pattern is in
+the schema, in the renderer, and in the new check, and assertion (5) of the check **fails if they
+drift apart**, because if they do the loosest one wins silently. Rejected shapes, all five
+provoked: `^/`, `^/.*`, `.*`, `/api/` (unanchored), `^/api/|^/` (alternation). Alternation is
+**refused rather than supported**: the flag is repeatable, so one entry per route costs nothing.
+
+**Why breadth is the dangerous direction, and it is not symmetric.** A *missing* `--api-route` is a
+silent 302 — bad, invisible, recoverable. A *too broad* one answers a plain **page load** with 401:
+a logged-out operator gets a bare error page and is **never offered a sign-in**, so the service
+looks permanently broken and no reload recovers it. That is a worse outcome than the defect the
+flag fixes, which is why it is gated on three surfaces rather than documented in one.
+
+### Also folded in: the selftest could exit 1 with ZERO diagnostics
+
+Not my change originally — Desmond Oyelaran found it while wiring `catalog/render.py --selftest`
+into the `render-golden` stage (his PR #33, which touches only `ci/render-golden.sh` and is **not**
+in my base; `origin/main` at `cdf3e14` does not yet drive the selftest from any gate stage). The
+coordinator asked me to fold the fix into this PR because the defect is in the file I own.
+
+`_selftest()` reached `_cookie_name()` through a bare `next(genexpr)` with **no default**. Delete
+the `--cookie-name` emission — exactly the mutation that assertion exists to catch — and it raises
+`StopIteration`, which escapes `_selftest()` **before its collected `SELFTEST FAIL:` lines are
+printed**. Right verdict, no diagnostics, and it masks every other assertion the same mutation
+broke. Fixed with `next(..., None)` plus an explicit `check()` so a missing flag reports **as a
+named assertion**.
+
+Provoking it turned up **three more instances of the same failure class** in the same block, which
+is why this is not literally a one-line change: `side = fa_containers[1]`,
+`side["env"][0][...]`, and the `fa_svc` lookup all raise rather than assert when the sidecar is
+absent entirely. All four are now None-tolerant, and the two fixtures I added for `--api-route`
+were written the same way from the start. Measured, on throwaway copies:
+
+| Mutation | Before | After |
+|---|---|---|
+| `--cookie-name` emission deleted (origin/main's renderer) | rc 1, **0** `SELFTEST FAIL` lines, 1 `StopIteration` | rc 1, **3** `SELFTEST FAIL` lines, 0 tracebacks |
+| the oauth2-proxy sidecar not appended at all | rc 1, **0** lines, `IndexError` | rc 1, **20** `SELFTEST FAIL` lines, 0 tracebacks |
+
+Note the consequence of his stage change for anyone reading this later: once PR #33 lands,
+`.gitea/workflows/gate.yml:138` runs `./ci/gate.sh || [ "$?" -eq 3 ]`, so **rc 1 is not tolerated
+in CI the way rc 3 is** — a selftest failure will block. Which is the right outcome, and it is why
+a selftest that prints nothing was worth fixing before that lands rather than after.
+
+### Declined, with reasons: the metrics-ingress NetworkPolicy
+
+The coordinator asked for my judgement on bundling Ines Dubois's finding — that #28's metrics
+listener genuinely serves (she measured `http=200`, 10,208 bytes,
+`oauth2_proxy_requests_total{code="302"} 2` via port-forward) but the scrape will be **dropped**,
+because namespace `jackett`'s default-deny has **no `ingress` key at all** and
+`jackett-allow-gateway-ingress` admits `fromEntities: [ingress]` only. The fix belongs in each
+app's own rendered policy, i.e. in my file and my goldens. **I declined to bundle it**, and asked
+for it as the immediate next PR. Five reasons, in the order that decided it:
+
+1. **The real reason is that it is a MODEL question, not a policy to bolt on.** Schema 1.6.0
+   already owns this: `observability.metricsEndpoint` renders the Service port **and** the
+   monitoring-namespace ingress allow. What the model cannot currently express is a **second**
+   metrics endpoint on the same pod belonging to a *sidecar the renderer injected*, rather than to
+   the workload the operator declared. Keying a bespoke policy off the pod label
+   `homelab.keithjackson.dev/auth-mode: forward-auth` works today, but it hardcodes "forward-auth
+   implies a metrics port on 44180" into a policy instead of **deriving** it from the sidecar
+   declaration that is already the single source of that port — the exact "list, don't derive"
+   anti-pattern `oauth2-proxy-cookie-names-distinct` assertion (5) exists to forbid, and which I
+   would be introducing one directory away from the check that forbids it. That deserves its own
+   review, and it is squarely the kind of decision I was brought in to make deliberately.
+2. **Different subject, and it is a trust-boundary change.** Mine is the auth *response code* on
+   API paths (R-IDP-02). That is an ingress allow (R-NET-01/02, R-OBS-01) admitting a new
+   namespace to a new port. Bundling a security-relevant ingress rule into a PR whose headline is
+   `--api-route` is how such a rule gets waved through on the strength of the other half — and this
+   PR already needs a human for a *different* sensitive-path reason, so the second subject would be
+   reviewed in the shadow of the first.
+3. **The conflict argument does not actually apply to my diff.** It assumes I am regenerating five
+   goldens; **I am regenerating two** (jackett, radarr), because the flag renders only where
+   declared. A metrics-ingress policy renders a *different document* — a CiliumNetworkPolicy — in
+   all five. Different hunks, in files git merges independently; and goldens regenerate
+   deterministically from the renderer, so the follow-up rebases onto `main` cleanly. The N-1
+   rebase problem `decisions/README.md` records was two branches appending to **the same hunk**,
+   which this is not. I checked my own diff before answering rather than accepting the premise.
+4. **Every fact in the finding is hers and I have measured none of it** — not the 200/10,208 bytes,
+   not the `wget: download timed out` on `:44180` *and* `:4180`, not the Flux sibling ordering that
+   makes `oauth2-proxy` and `apps-wave-0` unordered. Shipping a security-adjacent rule on wholly
+   inherited evidence, as a footnote in someone else's PR, is precisely what CLAUDE.md §2b exists
+   to stop. In its own PR I would measure it first.
+5. **Sequencing: the PodMonitor is in HER PR #29, not mine.** If I ship the policy and her
+   PodMonitor is reworked or delayed, I have opened an ingress allow for a scraper that selects
+   nothing — a hole with no consumer. The policy is only useful paired with the PodMonitor, which
+   argues for it landing adjacent to that, not here. It also drags in a
+   `KNOWN_EXTERNAL_MONITORS` entry in `conformance/tests/l0-static/servicemonitor-ports-resolve/`,
+   a second conformance interaction on top of the new check this PR already adds.
+
+Diff size is the tiebreaker rather than the argument: **1,245 insertions across 13 files**,
+including a ~400-line new conformance check. I would rather hand a reviewer one subject they can
+actually falsify. **Queued, not dropped** — and if the next person takes it, the model note in (1)
+is the part worth arguing about, not the YAML.
+
+### Which apps got which routes, and the measurement behind each
+
+| App | `auth.apiRoutes` | Evidence |
+|---|---|---|
+| **jackett** | `^/api/` | 2026-09-30, its own access log: **33 × 302 against 2 × 401** on `/api/` paths, and **4 of 6 POSTs answered by the proxy and never reaching Jackett** (upstream field `-`, not `/`), including both `/api/v2.0/server/update` calls |
+| **radarr** | `^/api/`, `^/signalr/` | `^/signalr/`: measured **by me, on the live post-fix pod** — see below. `^/api/`: measured on radarr by the PR #30 author, on the **pre-fix** pod |
+| **pihole** | *(none — deliberate)* | serves no `/api/`; **0** unauthenticated requests in its current pod's 23 h |
+| **sonarr** | *(none — not measured)* | 13,643 log lines, **0** unauthenticated requests. No traffic, not a negative result |
+| **qbittorrent** | *(none — not measured)* | 13,649 log lines, **0** unauthenticated requests. Same |
+
+**`^/signalr/` on radarr is the live proof this change was needed**, and it is the strongest
+evidence in this entry. 23 h after PR #28 deployed, on `radarr-7d55cbffb9-42hmh` (0 restarts), the
+sidecar logged **232 unauthenticated requests across the pod's entire lifetime, and all 232 are the
+same call**: `POST /signalr/messages/negotiate`, browser UA, **302**, upstream `-` (Radarr never saw
+one of them). That is a **left-open browser tab** whose session the cookie rename orphaned, polling
+SignalR forever, silently redirected every time, and **never re-prompting the operator**. It is the
+reported symptom — "reloading never fixes it and I am never re-prompted" — still happening in
+production, on a service nobody was looking at. With 401 the UI's connection breaks **loudly**; the
+operator reloads; `/` matches neither regex, so the reload signs them back in.
+
+**`^/api/` on radarr: included, and here is the honest basis.** The current pod has logged **zero**
+`/api/` traffic, so I did **not** re-measure it. It rests on a measurement of **radarr** recorded in
+the merged PR #30 handoff — its 156 unauthenticated requests were `/api/v3/command` (62),
+`/api/v3/queue/details` (46) and `/signalr/messages/negotiate` (43), i.e. **108 of 156 were
+`/api/v3` XHRs**. That is this app's own evidence, by another engineer, not an analogy to another
+app. I include it because `/api/v3/` is a pure JSON namespace a browser never navigates to (Radarr
+serves its UI at `/`, assets under `/Content/` and `/MediaCover/`), so the breadth risk is nil and
+the measured benefit is 70% of that app's rejection volume.
+
+**Sonarr and qBittorrent were measured and deliberately left alone.** Sonarr is nearly the same
+codebase as Radarr, which is exactly what makes `^/api/` + `^/signalr/` a tempting guess and still a
+guess. I read both pods' logs: **zero** unauthenticated requests, nothing but health probes, because
+nobody has opened either UI since the cookie fix rolled. **That is evidence of no traffic, not
+evidence of no need.** Each catalog file now carries a comment saying so, with the numbers and what
+to measure before adding the routes.
+
+### Goldens and fixtures regenerated
+
+Rendered with the canonical command
+(`python3 catalog/render.py --all catalog -o apps --wave-layout --no-image-automation`).
+**Two goldens changed, not five** — and that is the per-app property proving itself on the real
+tree rather than in a fixture:
+
+    apps/wave-0/jackett.yaml   + --api-route=^/api/
+    apps/wave-1/radarr.yaml    + --api-route=^/api/
+                               + --api-route=^/signalr/
+
+`apps/wave-0/pihole.yaml`, `apps/wave-0/qbittorrent.yaml` and `apps/wave-1/sonarr.yaml` are
+**byte-identical to `main`**. **No L1 fixture needed regenerating**: all three
+`conformance/tests/l1-rendering/*/fixtures/svcdef*.yaml` declare `auth.mode: forward-auth` with no
+`apiRoutes`, so they render no flag and their goldens are unchanged. PR #28 touched 5 goldens and 3
+L1 fixtures because it changed flags on *every* sidecar; this one changes flags only where a
+measurement says so, which is the whole point.
+
+### The L0 decision (and it is a decision, not a default)
+
+**Not** in `oauth2-proxy-cookie-names-distinct`. That check's subject is cookie **identity** — its
+inputs are names and domains, its failure mode is mutual session eviction, its register is the
+shared proxy's claim on the default name. `--api-route` shares none of those. Bundling them would
+make that check's name a lie and couple two unrelated ratchets, so a future api-route decision could
+only be expressed by weakening a *cookie* check. That is PR #28's own stated discipline, applied to
+my change rather than quietly dropped.
+
+**A sibling check, `oauth2-proxy-api-routes-per-app`** (whole-repo scope, so it runs on every gate
+invocation via `ci/l0.sh`'s `--include-scope` union — no bespoke stage, which
+`whole-repo-invariants-wired` would fail). **Nowhere was the wrong answer for exactly one reason:**
+the existing gates cannot see a renderer constant. `render-golden` compares the render to the
+goldens, so a constant **plus regenerated goldens agree with each other while both being wrong** —
+I provoked that and it regenerates with **rc 0**. The new check's assertion (2) compares each
+rendered sidecar against its **own ServiceDefinition**, which is the only reading that fails it.
+
+## What I verified
+
+- **`--api-route` is SINGULAR, read off the PINNED binary rather than taken from the brief.**
+  `podman run --rm quay.io/oauth2-proxy/oauth2-proxy:v7.8.1 --help`:
+  `--api-route strings   return HTTP 401 instead of redirecting to authentication server if token
+  is not valid. Format: path_regex`. There is **no `--api-routes`** in the help output. The PM asked
+  me to verify rather than trust, and that is the result — the singular form is confirmed and the
+  help text also confirms the *semantics* I am relying on (401 instead of a redirect).
+- **The premise, in-cluster, read-only, through the pinned toolbox, `--context k3s-prod` named
+  explicitly** (CLAUDE.md §2b and §5). PR #28 **is** deployed: all five sidecars carry
+  `--cookie-name=_oauth2_proxy_<app>`, `--cookie-domain=<app>.home.keithjackson.dev`,
+  `--cookie-refresh=2m30s` and `--metrics-address=0.0.0.0:44180`. Pods, all **0 restarts**:
+  `jackett-6877fcd9f5-ht9d9`, `pihole-…`, `qbittorrent-5547bdb9bd-zq557`,
+  `radarr-7d55cbffb9-42hmh`, `sonarr-ddf485775-8ckwt` (started 2026-09-30T21:41–21:42Z).
+- **The full post-fix log census, parsed rather than grepped** (oauth2-proxy's access-log format,
+  with `/ping` health probes excluded), over each pod's whole life:
+
+      app            lines   unauth  AuthSuccess  removing session  cookie sig invalid
+      jackett       13,649        0            0                 0                   0
+      pihole        13,649        0            0                 0                   0
+      qbittorrent   13,649        0            0                 0                   0
+      radarr        14,099      232            0                 0                   0
+      sonarr        13,643        0            0                 0                   0
+
+  Three findings, kept separate:
+  1. **The collision fix works.** Jackett was 39 unauthenticated before; it is **0** in 13,612
+     non-probe lines. The eviction fingerprint (`removing session` / `cookie signature not valid`)
+     is **0 on all five**, where radarr previously had 8 and 8.
+  2. **Radarr's 232 are one request.** 100% `POST /signalr/messages/negotiate`, 100% **302**, 100%
+     upstream `-`, browser UA (`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537…`). **Zero `/api/`
+     traffic of any kind** on this pod.
+  3. **0 `AuthSuccess` anywhere**, so nobody has signed in since the restart and `--cookie-refresh`
+     is **still** unexercised — unchanged from PR #28's own caveat.
+- **Only two goldens change, and three are byte-identical to `main`.** `git status` after the
+  canonical render lists exactly `apps/wave-0/jackett.yaml` and `apps/wave-1/radarr.yaml`.
+  `render-golden` is green.
+- **`catalog/render.py --selftest`: PASS**, with new assertions that (a) the `fa` fixture, which
+  declares nothing, renders **no** `--api-route`; (b) a fixture declaring two routes renders exactly
+  those two, in order; (c) the renderer **refuses** all five breadth shapes; (d) four legitimate
+  routes (`^/api/`, `^/signalr/`, `^/api/v3/.*`, `^/api/v2.0/server/update$`) are **accepted** — a
+  ratchet that blocks real API prefixes is a ratchet someone eventually deletes.
+- **The new check: rc 0, 43 assertions, 6 sidecars audited**, with its inventory printed so the
+  reviewer can see what it read:
+  `jackett -> ['^/api/'] | pihole -> (none) | qbittorrent -> (none) | radarr -> ['^/api/',
+  '^/signalr/'] | sonarr -> (none) | crafty -> (none)`.
+- **The check was tested in BOTH directions, on throwaway copies outside the repo**, never by
+  mutating the branch. Each mutation fired its own assertion class and nothing else:
+  - **Pre-change tree** (`git archive origin/main` + the test dropped in): **rc 1, 11 failures** —
+    no service declares routes, the renderer emits none, the renderer does not read `auth.apiRoutes`,
+    the pattern is absent from both renderer and schema, and the shipped renderer accepts all five
+    breadth shapes.
+  - **pihole's golden hand-edited** to carry a route it never declared: **rc 1, 2 failures** (the
+    catalog↔golden mismatch, and "declares nothing must render nothing").
+  - **radarr's golden widened** to `--api-route=^/`: **rc 1, 2 failures** (unanchored, plus the
+    mismatch).
+  - **Renderer turned into a constant and EVERY golden regenerated to match: the regen exits 0** —
+    i.e. `render-golden` is **happy** — and the new check exits **1 with 15 failures**, naming
+    pihole, qbittorrent, radarr and sonarr individually. **This is the case that justifies the
+    check's existence** and I provoked it rather than argued it.
+  - **Schema `items.pattern` deleted**: **rc 1, 1 failure** — the three-surface drift guard.
+  - **Unmutated control: rc 0.**
+- **The selftest diagnostics fix was PROVOKED, not reasoned.** Both mutations above were run
+  against throwaway copies of the renderer outside the repo (`origin/main`'s `render.py` for the
+  "before" column, mine for the "after"), never by mutating the branch. The pre-fix StopIteration
+  and the post-fix 3-and-20 named assertions are quoted from those runs. `--selftest` on the
+  unmutated branch: **PASS**. Goldens after the fix: **unchanged** (it touches only `_selftest()`).
+- **The check is selected by the whole-repo union.** `./conformance/run.sh --layer l0 --requirements
+  r-nosuchreq-99 --include-scope whole-repo --print-selection` lists
+  `tests/l0-static/oauth2-proxy-api-routes-per-app` among **21** tests (it was 20), i.e. it runs
+  even when the touched-requirement filter matches nothing.
+- **THE SCHEMA GUARD IS PROVEN WITH THE PINNED VALIDATOR `ci/l0.sh` ACTUALLY DRIVES**, not by
+  reading the pattern. `./schemas/validate.sh` (`check-jsonschema, version 0.29.4`) against seven
+  throwaway ServiceDefinitions written outside the repo:
+
+      good            ["^/api/", "^/signalr/"]   rc 0
+      bad-root        ["^/"]                     rc 1  apiRoutes ... does not match
+      bad-dotstar     ["^/.*"]                   rc 1  apiRoutes ... does not match
+      bad-unanchored  ["/api/"]                  rc 1  apiRoutes ... does not match
+      bad-alt         ["^/api/|^/"]              rc 1  apiRoutes ... does not match
+      bad-everything  [".*"]                     rc 1  apiRoutes ... does not match
+      bad-mode        ["^/api/"] on mode: oidc   rc 1  const 'forward-auth'
+
+  So a too-broad regex is rejected **where a human types it**, on every gate run, by the real tool
+  — and the shape invariant fires too.
+- **THE RENDERER'S REFUSAL REACHES `render-golden` AS A READABLE FAILURE, NOT A TRACEBACK.** With
+  `^/signalr/` swapped for `^/` in a *copy* of the catalog (outside the repo), both invocation
+  shapes exit **rc 1 with 0 tracebacks** — the single-SD form and `--all <dir> -o <dir>
+  --wave-layout --no-image-automation`, which is the one `ci/render-golden.sh` drives:
+
+      render.py: radarr: auth.apiRoutes entry '^/' is not an anchored path regex. Each entry
+      must start with '^/' and continue with literal path characters (e.g. '^/api/',
+      '^/signalr/', '^/api/v3/.*'). ... A too-broad --api-route answers a PAGE LOAD with 401, so
+      a logged-out operator sees a bare error page and is never offered a sign-in: the service
+      looks permanently broken rather than merely unauthenticated.
+
+  So the breadth guard is gated by `render-golden` even on a run where the schema stage skipped,
+  and the operator is told *why* rather than handed a stack trace.
+- **The schema's new shape invariant.** A non-empty `auth.apiRoutes` requires
+  `auth.mode: forward-auth`, because the flag renders onto the per-app sidecar and no sidecar exists
+  for `oidc`/`native`/`none` — declaring it elsewhere would be a **silent no-op**, which is the
+  failure class this repo keeps paying for.
+- **Gate:** toolbox `./ci/gate.sh` with the two-mount ENGINE shim — exit code and stage list in the
+  next section, because it is not a pass and that belongs there.
+- **No mutating cluster access.** `kubectl get/logs/jsonpath` only, `--context k3s-prod` named on
+  every call. No `apply`/`edit`/`patch`, no `flux reconcile`. No Secret `.data` or `.stringData` was
+  read or printed; I did not need to touch a Secret at all this session. The one container I ran
+  locally was the pinned oauth2-proxy image, to read its `--help`.
+- **`~/.git-credentials` was never read.** PR creation used `git credential fill`, which does not
+  echo the value.
+
+## What I did NOT verify
+
+- **NO BROWSER ROUND-TRIP. BY ANYONE. FOR THIS FLAG.** This is the most important line here. The
+  302/401 split, the dropped POST bodies and the orphaned SignalR poll are all read from access
+  logs; that a **401 repairs** the operator's experience is reasoned from HTTP semantics, not
+  watched. Nobody has added a Jackett indexer or recovered a Radarr tab through this
+  configuration. The human test below is the first real evidence this change will ever have.
+- **Local gate: rc 3 (UNDETERMINED), not 0.** Green: `spec-immutability`, `decisions-log`, `lint`,
+  `l0`, `render-golden`, `l1`. **Skipped:** `gitea-settings` (no `SETTINGS_API_TOKEN` locally) and
+  **L2/L3 conformance** (`CLUSTER_AVAILABLE` unset). Nothing FAILED; nothing runtime was certified
+  either. **rc 3 is UNDETERMINED, never green.**
+- **MY LOCAL `approval-policy: green` WAS MEANINGLESS, AND I ALMOST REPORTED IT AS EVIDENCE.**
+  `ci/approval-policy.sh:47` reads `GITHUB_EVENT_NAME`, which is unset outside CI, so the stage
+  short-circuits at line 50: `ok "not a pull_request event (event='none') — approval policy N/A"`.
+  **A clean local gate therefore CANNOT catch a sensitive-path problem — structurally, not by
+  accident.** Flagged to me by the coordinator from Ines Dubois's round, and I verified it by
+  re-running the gate with `GITHUB_EVENT_NAME=pull_request PR_NUMBER=34`: the stage then
+  **evaluates** and fails closed on the missing token —
+
+      [fail] no SETTINGS_API_TOKEN — cannot read this PR's changed files or its reviews.
+      [fail] stage approval-policy: FAIL
+      [fail] approval-policy: a sensitive change lacks a non-author approval -> blocks merge
+      [fail] MERGE GATE: BLOCKED        (rc 1, not 3)
+
+  — while **every other stage stays green** (`spec-immutability`, `decisions-log`, `lint`, `l0`,
+  `render-golden`, `l1`). That is the useful result: it bounds the CI failure to this one stage
+  rather than leaving "something is red" as the whole report. Fail-closed is correct here and
+  deliberate: unlike `gitea-settings`, where a missing credential is a lock-out, a skip of this
+  stage would be a bypass (CLAUDE.md §1).
+- **CI, read from each commit's `/statuses` rather than from a tick.** Both contexts report, and
+  **only one of them runs**. Identical on `99560c2d`, `df1b25b6` and `f1d16f44`:
+
+      gate / gate (pull_request)         state=failure   desc='Failing after ~1m43-1m45s'
+      gate / conformance (pull_request)  state=success   desc='Has been skipped'
+
+  **That second line is §2b's trap in the wild**: a *skipped* Gitea job reports
+  `state=success`. The conformance job did not execute, so its green tick certifies nothing —
+  read the description, not the colour. The duration is given as a range on purpose: it differs
+  by a second or two per run, and pinning one number inside the file whose commit triggers the
+  next run is a self-reference, not a measurement. The load-bearing fields are the **state** and
+  the **description**, and those are stable across all three.
+
+  Worth recording that the **same context changed its answer over time**: on the first push it
+  briefly read `state=pending desc='Blocked by required conditions'` — still waiting on the gate
+  job it depends on — and resolved to `success` only once that job settled. So sampling a status
+  once can show either a pending **or** a green tick for a job that never executed.
+  **I could NOT read the CI job log to confirm the failing stage from CI's
+  own output**: this Gitea's `/api/v1/repos/{owner}/{repo}/actions/runs` endpoint answers
+  **404** (only `/actions/tasks` exists, which lists tasks without logs), and
+  `/actions/jobs/{task_id}/logs` answers `404 Not found` for the task id. So my attribution of the
+  CI failure to `approval-policy` rests on the local event-set reproduction above plus the
+  sensitive-path rule, **not** on CI's own log. That is weaker evidence than PR #28 had and I am
+  naming it rather than borrowing its wording.
+- **Branch protection and the runner, RE-MEASURED this session against the live API** (§2b),
+  not inherited from CLAUDE.md §2's table:
+
+      GET /repos/Home-Network/home-network-k3s-impl/branches/main
+        protected              True
+        user_can_push          False
+        enable_status_check    True
+        status_check_contexts  ['gate / gate (pull_request)']
+        required_approvals     1
+      GET /admin/actions/runners
+        id=1 name=incluster-dind status=online
+
+  So `required_approvals=1` applies to **every** PR here regardless of path — this needs a human
+  even without the sensitive-path rule. I did **not** provoke a rejected push to `main` this
+  session; `user_can_push: False` is the API's word, which is exactly the weaker form of evidence
+  CLAUDE.md §2 warns about, and I did not strengthen it.
+- **`^/api/` ON RADARR IS NOT MY MEASUREMENT.** It is PR #30's, taken on the **pre-fix** pod. The
+  current pod has logged **zero** `/api/` traffic in 23 h, so I could not reproduce it. I judge the
+  breadth risk nil (`/api/v3/` is pure JSON; the UI is at `/`), but if someone wants a strictly
+  self-measured configuration, drop `^/api/` and keep `^/signalr/` — the 232 are entirely SignalR.
+- **SONARR AND QBITTORRENT ARE UNMEASURED, NOT CLEARED.** Zero traffic in 23 h is zero evidence.
+  qBittorrent's WebUI drives everything through `/api/v2/` and is *plausibly* affected the same way
+  Jackett is; Sonarr is nearly Radarr's codebase. **Both are left alone on purpose** — plausibility
+  is what put a renderer constant on the table in the first place. Expect to add `^/api/` to
+  qBittorrent and `^/api/` + `^/signalr/` to Sonarr once someone opens those UIs and records the
+  split. **This PR does not fix them.**
+- **PiHole is asserted to serve no `/api/` on inherited evidence, not mine.** Its log shows 0
+  unauthenticated requests, which says nothing about what paths it serves. The claim comes from
+  PR #28/#30. Note the pinned `update.range` is `>=2024.0.0`, and PiHole v6 *does* introduce a REST
+  API at `/api/` — so if PiHole is ever upgraded across that line, this needs re-measuring. It is
+  still correct to declare nothing today, because declaring an unmeasured route is the mistake.
+- **`--cookie-refresh=2m30s` has STILL never been exercised** — 0 `AuthSuccess` on all five pods.
+  PR #28 named this as the fix most likely to need a second pass and it remains unobserved. My
+  change does not touch it, but a sign-in during the human test below will exercise both at once,
+  so a failure there must be attributed carefully.
+- **The regexes are not validated against the apps' real route tables.** I assert `/api/v3/` and
+  `/signalr/` are JSON/RPC namespaces a browser never navigates to from Radarr's and Jackett's
+  observed traffic and from how those UIs are built — **not** from reading their routing code or
+  enumerating their endpoints. A path I have not thought of that matches `^/api/` and *is*
+  browser-navigated would 401.
+- **`OPTIONS` preflight and non-browser clients are unconsidered.** `--skip-auth-preflight` exists
+  and is not set; nothing in these logs shows a CORS preflight, and Sonarr/Radarr talk to Jackett
+  **directly on `:9117`**, bypassing the proxy entirely — so I do not expect impact. Unverified.
+- **The live pods do not carry this change and nothing re-measures that they will.** git is not the
+  cluster (§2b). **Merging is what deploys**, and it will roll **jackett** and **radarr** only
+  (`strategy: Recreate` on RWO Longhorn volumes, so a brief gap per app, and radarr/sonarr lose
+  direct `:9117` access to Jackett while its pod restarts). Existing sessions survive — no cookie
+  flag changed — so unlike PR #28 nobody is signed out.
+- **No L2/L3 assertion reads any of this.** There is no runtime check that a `/api/` request to a
+  gated app answers 401, and I did not write one; `CLUSTER_AVAILABLE` is unset so it could not run
+  in CI anyway. The whole guard is static.
+- **`catalog/render.py --selftest` is UNGATED IN MY BASE, and I did not wire it.** Desmond's PR #33
+  does that (`ci/render-golden.sh`) and is in review, not merged — `origin/main` at `cdf3e14`
+  contains no stage that drives it, which I checked rather than assumed (`grep -n selftest
+  ci/render-golden.sh` → no match). **So until #33 lands, my new selftest assertions are
+  dev-time only**, and the *gated* half of my breadth ratchet is the schema `pattern` (via
+  `ci/l0.sh`'s schema stage), the renderer's own `raise` (via `render-golden`), and the new L0
+  check. I deliberately did not wire the selftest myself: #33 already does it, and duplicating it
+  here would collide with his branch in the one file he owns. Note the two PRs are **independent
+  but complementary** — his makes the stage real, mine makes its output readable when it fires.
+- **I did NOT verify PR #33's own claims.** The 106-assertion count, the
+  selftest→stage→`gate.sh`→`BLOCKED` propagation chain, and the `--cookie-refresh 2m30s → 10m`
+  mutation being caught by the selftest but not by `render-golden` are all his measurements,
+  relayed to me by the coordinator. I reproduced only the StopIteration defect itself, because that
+  is the part I was asked to fix. If his branch is reworked, nothing in mine depends on it.
+- **The new check does not read the spec repo** and asserts nothing about `../home-network-k3s`
+  (R-TEST-06, read-only). `schemas/renderer-contract.md` is updated in **this** repo only; the
+  canonical spec `docs/13-service-catalog.md` is **not** updated, because it is immutable from here.
+  Someone with spec write access should mirror `auth.apiRoutes` into docs/13 and docs/15.
+- **THE OAUTH2-PROXY SIDECARS' METRICS ARE STILL UNSCRAPABLE, AND THIS PR DOES NOT FIX IT.** See
+  the declined-bundle section above. #28 shipped `--metrics-address` as a prerequisite and said
+  plainly that it was not scraped; Ines has now measured that the listener **serves** and that the
+  scrape is **dropped by each app namespace's default-deny**. Nothing in my change touches that.
+  Anyone reading this entry as "the fleet gates are observable now" is wrong, and the next PR is
+  where that changes.
+- **Alternation is refused, and that is a judgement I may have to revisit.** No app in this catalog
+  needs it, and the flag is repeatable — but if some future app genuinely needs a regex the ratchet
+  rejects, the fix is to widen the pattern **with a reason** on all three surfaces at once, not to
+  delete the ratchet on one.
+- **CI status: two contexts, and only one of them ran.** Quoted in the PR body and in the report to
+  the PM. `approval-policy` **fails by design** until a non-author approving review exists, because
+  the diff touches `conformance/**`, which `infra/gitea/approval-policy.json` lists as sensitive
+  ("the tests and the harness; changing them changes what green MEANS"). That is CLAUDE.md §1
+  working, not a defect. `required_approvals=1` applies to every PR here regardless of path, so this
+  needs a human either way.
+
+### The human test — and how to tell a too-broad regex from a working one
+
+After merge, wait for **new** pod names at 2/2 in `jackett` and `radarr`.
+
+1. **The breadth test FIRST, before anything else, from a signed-out browser** (private window).
+   Open `https://radarr.home.keithjackson.dev/` and `https://jackett.home.keithjackson.dev/UI/Dashboard`.
+   **Each must bounce through Keycloak and land on the app's UI.** If either shows a bare
+   `401 Unauthorized` instead of a sign-in, **the regex is too broad — stop and revert.** That is
+   the one failure this change can introduce, and it is the only test that can see it. A working
+   regex is invisible on a page load; a broken one is total and immediate.
+2. **Jackett, the original report:** signed in, *+ Add indexer* → pick one → *Configure* → *Okay*.
+   **It must save.** Previously 4 of 6 POSTs never reached Jackett at all.
+3. **Radarr, the live symptom:** open Radarr and leave the tab open. DevTools → Network, filter
+   `signalr`. Today those negotiate calls are **302** and the UI never complains. They must now be
+   **200** while signed in — and if the session is ever lost, **401**, with the UI showing a visible
+   connection error instead of polling silently forever.
+4. **The loud-failure test:** in DevTools, delete the `_oauth2_proxy_radarr` cookie and let the tab
+   poll. The negotiate call must answer **401** and Radarr must *show* a problem. Then **reload** —
+   `/` matches neither regex, so the reload must sign you back in silently. That round trip is the
+   entire fix: fail loudly on the API, recover on the page load.
+5. **The six-minute test (PR #28's open item, still open):** stay on a dashboard for >6 minutes,
+   then save something. That exercises `--cookie-refresh=2m30s` past the 300 s access-token cliff.
+   If it fails, suspect the realm's refresh/SSO-idle timeouts — not this change.
+6. **If something still fails, it must now fail LOUDLY.** A silent success-looking no-op means the
+   change did not take: check the running pod's args for `--api-route` before assuming anything
+   else.

decisions/2026-10-01-render-selftest-runs-in-gate.md

@@ -0,0 +1,205 @@
+---
+date: 2026-10-01
+branch: fix/render-selftest-runs-in-gate
+title: catalog/render.py's 106 assertions were dev-time only; the gate now runs them and blocks on them
+---
+
+## What changed
+
+Single subject, one file: **`ci/render-golden.sh` now invokes `catalog/render.py --selftest`**
+and exits 1 when it fails. Nothing else. No renderer change, no new conformance test, no new
+gate stage.
+
+This closes the top follow-up of `decisions/2026-09-30-oauth2-proxy-cookie-collision-fleet.md`:
+
+> Nothing in `ci/` or `.gitea/` runs `catalog/render.py --selftest` — I grepped for it. So the
+> twenty-odd assertions in that selftest, including the six I just added, are dev-time only: a
+> future edit that drops either flag *and* re-renders the goldens would pass the entire merge
+> gate.
+
+Re-measured here and confirmed: before this commit, `grep -rl -- --selftest` over `ci/` and
+`.gitea/` returned **nothing** for the renderer. The selftest executes **106** assertions
+(`check()` invocations counted at runtime via `sys.settrace`, without editing `render.py`; 109
+static call sites, three of them on failure-only branches). All 106 were unexercised by the
+merge gate.
+
+### The lead was WRONG, and here is why
+
+The brief named `conformance/tests/l0-static/auditability-proofs-producible/check.sh:291` as the
+one-line fix. That line is real and it does drive selftests:
+
+    for tool in ("record_run.py", "status.py"):
+        r = run([sys.executable, str(LIB / tool), "--selftest"])
+
+But it is **the wrong hook**. That loop is section (d) of a check that serves **R-SEC-03**, and
+its subject is the *evidence chain* — can a self-skipped run, or a stale ledger row, become an
+audit proof? `record_run.py` and `status.py` are **in** that chain; `catalog/render.py` is not.
+Hanging the renderer there would have made the check's name, its `intent` annotation and its
+requirement mapping (`R-SEC-03`) all untrue, and a future decision about the renderer could then
+only be expressed by weakening a *security-auditability* check. That is the precise coupling the
+cookie-collision entry refused for its own check, and it applies here.
+
+The second option that entry offered — a new scope-declaring L0 test — is the supported mechanism
+for a **whole-repo invariant** (`ci/l0.sh` Stage 3b's `--include-scope whole-repo` union, ratcheted
+by `tests/l0-static/whole-repo-invariants-wired`). It is the right shape for an invariant
+quantified over the tracked tree. It is the wrong shape for *"a script in this repo must pass its
+own unit test"*: it would need to declare requirements it does not serve, and it would be two new
+files of several hundred lines by this tree's conventions for what is a six-line invocation.
+
+**The honest home is `ci/render-golden.sh`** — the gate stage whose subject *already is*
+`catalog/render.py`. It already resolves `$PYTHON` and `$RENDER_PY`, already reports rc 3 when
+either is missing, already exits 1 on renderer error, and `ci/gate.sh` already maps it through
+`for s in lint l0 render-golden l1` where a FAIL is BLOCKED and a SKIP is UNDETERMINED. The
+stage's two assertions are independent and both are needed:
+
+- `render-golden` catches golden-vs-renderer drift, but is satisfied by **any** renderer whose
+  output was re-rendered — including one that just lost a contract invariant and had all ten
+  goldens regenerated in the same commit. That is exactly the hole named in the quote above.
+- `--selftest` catches that, and is blind to golden drift.
+
+The file header and the stage name were updated so neither is a lie: the stage is now "the
+renderer is trustworthy", with two numbered assertions, and the step summary emits its own
+`- render-selftest:` line so the gate output still NAMES what ran.
+
+The selftest runs **before** the empty-catalog `exit 3` on purpose: it renders synthetic
+ServiceDefinitions in memory and is catalog-independent, so an empty catalog must not be able to
+skip it.
+
+`catalog/render.py` itself was **not touched** (owned by a concurrent branch this session), and
+neither was any file under `conformance/`.
+
+## What I verified
+
+- **The selftest runs and passes: rc 0, `render.py selftest: PASS`, 106 assertions executed.**
+  Counted at runtime, not from the source: a `sys.settrace` hook counting `check()` calls, in a
+  throwaway script outside the repo, with no edit to `render.py`.
+- **The stage passes with it wired in**, host run of the single stage:
+
+      [gate] Stage: render==golden reproducibility (canonical render vs committed apps/)
+      [gate] Stage: catalog/render.py --selftest (the renderer's own output-contract assertions)
+      [ ok ] render.py --selftest passed
+      [ ok ] render==golden: all 10 onboarded service golden(s) reproduce from the canonical render
+
+  rc **0**. The golden comparison still reports all 10 goldens, so the new invocation did not
+  displace what the stage already asserted.
+- **IT CAN FAIL — provoked twice, against a mutated COPY of the renderer, never against the
+  tree.** `ci/render-golden.sh` already honours `RENDER_PY`, so each mutant lived in
+  `/tmp/claude-1000/desmond-selftest/` and the repo's `catalog/render.py` was never modified —
+  which matters, because that file belongs to a concurrent branch this session.
+  - **Mutation 1 — the regression this selftest was written for.** Deleted the
+    `f"--cookie-name=_oauth2_proxy_{s['name']}"` emission from `_oauth2_sidecar_container()`,
+    i.e. reverted the fleet-wide cookie-collision fix of PR #28. Stage rc **1**. Note the shape
+    of the failure, because it is a real (minor) weakness and is listed as a follow-up: the
+    selftest died with an uncaught `StopIteration` out of `next(a for a in container["args"] if
+    a.startswith("--cookie-name="))` at `render.py:2641`, rather than printing its collected
+    `SELFTEST FAIL:` lines. It is correctly non-zero and the stage correctly blocks, but the
+    operator gets a traceback instead of the assertion message.
+  - **Mutation 2 — a clean, named assertion failure.** `OAUTH2_COOKIE_REFRESH = "2m30s"` ->
+    `"10m"`, widening the refresh past the measured 300s access-token lifetime. Stage rc **1**:
+
+        [fail] catalog/render.py --selftest FAILED — the renderer violates its own output contract.
+        [fail]   Every golden under apps/ is produced by this renderer, so the goldens below cannot
+        [fail]   be trusted even if they reproduce byte-for-byte. Reproduce with:
+        [fail]     python3 catalog/render.py --selftest
+            SELFTEST FAIL: --cookie-refresh=10m parses to 600.0s, which is not inside (0, 300s). A
+            refresh at or past the access-token lifetime never renews in time, which is the same
+            logout it was added to stop
+
+    This is the mutation that proves the wiring's value most directly: mutation 2 would **not**
+    be caught by `render-golden`'s diff if the goldens were regenerated in the same commit, and
+    it is one of the two flags the cookie-collision entry explicitly recorded as **ungated**.
+- **THE NON-ZERO PROPAGATES ALL THE WAY TO `gate.sh`'s rc — provoked, in the pinned toolbox, not
+  reasoned about.** `RENDER_PY=/desmond-selftest/render-mutant2.py ./ci/gate.sh`:
+
+      [ ok ] stage spec-immutability: pass
+      [ ok ] stage decisions-log: pass
+      [ ok ] stage lint: pass
+      [ ok ] stage l0: pass
+      [gate] Stage: catalog/render.py --selftest (the renderer's own output-contract assertions)
+      [fail] catalog/render.py --selftest FAILED — the renderer violates its own output contract.
+          SELFTEST FAIL: --cookie-refresh=10m parses to 600.0s, which is not inside (0, 300s). ...
+      [fail] stage render-golden: FAIL
+      [ ok ] stage l1: pass
+      ...
+      [fail] render-golden: FAILED -> blocks merge
+      [fail] MERGE GATE: BLOCKED
+
+  `gate.sh` rc **1**. Three links in the chain, each measured: selftest rc 1 -> stage rc 1 ->
+  gate rc 1 / `MERGE GATE: BLOCKED`. This mattered enough to provoke rather than assume: this
+  repo has a documented habit of exit codes getting flattened, and
+  `.gitea/workflows/gate.yml:138` runs `./ci/gate.sh || [ "$?" -eq 3 ]`, which tolerates rc 3 —
+  so a stage that degraded a failure to a skip would be swallowed by CI. rc 1 is not tolerated
+  there, and rc 1 is what this produces.
+- **`spec-immutability` genuinely RAN and passed, it did not skip.** The two-mount worktree shim
+  plus `-e SPEC_REPO=/home-network-k3s` (the fix recorded in the 2026-09-30 cookie entry) works:
+  `stage spec-immutability: pass`, not SKIPPED. R-TEST-06 is therefore actually covered by these
+  runs.
+- **No collision with PR #29.** The brief warned that `feat/oauth2-proxy-auth-failure-visible`
+  had added checks under `conformance/tests/l0-static/`. Measured —
+  `git diff origin/main...origin/feat/oauth2-proxy-auth-failure-visible --name-only` — it touches
+  **no `conformance/` path at all**: `decisions/`, `platform/oauth2-proxy/` (a promtool test, an
+  alert rule, its kustomization), `runbooks/`. Disjoint from this branch either way, since this
+  branch touches only `ci/render-golden.sh` and this file.
+- **Priya's files were not touched.** `catalog/render.py`, `schemas/servicedefinition.schema.json`,
+  `apps/wave-*` and `conformance/tests/l1-rendering/` are all untouched by this branch — confirmed
+  by `git diff --name-only`, which lists exactly two paths.
+- **`catalog/render.py --selftest` was the LAST unwired selftest in the tree.** Measured:
+  `grep -rl -- --selftest` across the repo finds selftest-capable artifacts in exactly four
+  places, and after this commit every one is driven by the gate — `conformance/lib/record_run.py`
+  and `conformance/lib/status.py` by `auditability-proofs-producible/check.sh:291`, the Keycloak
+  client-secret reconciler (embedded in `platform/keycloak/client-secret-reconciler.yaml`) by
+  `keycloak-client-secret-reconciler/check.sh:633`, and `catalog/render.py` by this change.
+
+## What I did NOT verify
+
+- **Local gate: rc 3 (UNDETERMINED), NOT 0. This is not green and must not be reported as
+  green.** Measured in the pinned toolbox on `eeb6211`:
+
+      [ ok ] spec-immutability: green
+      [ ok ] approval-policy: green
+      [ ok ] decisions-log: green
+      [ ok ] lint: green
+      [ ok ] l0: green
+      [ ok ] render-golden: green
+      [ ok ] l1: green
+      [fail] MERGE GATE: UNDETERMINED — greenness was NOT ESTABLISHED.
+      [fail]   Stages that did not run: gitea-settings
+
+  Nothing FAILED. The single cause is `gitea-settings` **SKIPPED** — `SETTINGS_API_TOKEN` is not
+  set in my environment, so branch protection and runner registration were not read; CI has that
+  token and the stage is expected to run there. **L2/L3 `conformance`** also skipped
+  (`CLUSTER_AVAILABLE` unset) but is a *declared* gap that `gate.sh` treats as not-applicable
+  rather than undetermined, so it is not what produced the 3. Touched requirements
+  **R-GITOPS-01 R-TEST-02 R-TEST-03 R-TEST-06** are therefore **UNVERIFIED at L2/L3**, all four.
+  The stage this branch changes, `render-golden`, is green **and** was independently proven able
+  to turn the whole gate red (above).
+- **`approval-policy` passed LOCALLY only because there is no pull_request event**
+  (`not a pull_request event (event='none') — approval policy N/A`). That is not evidence that it
+  passes. This diff touches `ci/**`, a sensitive path, so in CI the stage is expected to **FAIL**
+  until a non-author approving review exists. That is §1 working, fail-closed, not a defect.
+- **The selftest's own quality is unchanged and ungated.** I wired its *invocation*; I did not
+  review its 106 assertions, and nothing ratchets them. Deleting the body of `_selftest()` would
+  still pass this stage, because an empty selftest returns 0. The repo already has the right
+  answer for that — `conformance/tests/l0-static/keycloak-client-secret-reconciler/mutations.py`
+  injects regressions one at a time and requires `--selftest` to catch every one — and applying
+  that pattern to `catalog/render.py` is the follow-up, deliberately not done here: it is a
+  second subject, it touches `conformance/`, and it would need to live beside the renderer whose
+  file another branch owns this session. **Until it exists, "the selftest runs" is proven and
+  "the selftest is falsifiable" rests on my two hand-run mutations, which are not in the gate.**
+- **Mutation 1's traceback is not fixed.** `render.py:2641`'s `next(...)` has no default, so the
+  absence of `--cookie-name` raises `StopIteration` and the selftest's collected `SELFTEST FAIL:`
+  lines are never printed. Correct verdict, poor diagnostics, and it suppresses the other
+  assertions that mutation also broke. The one-line fix (`next(..., None)` plus a `check()`) is in
+  `catalog/render.py`, which is another branch's file this session, so it is a follow-up and not
+  a thing I touched.
+- **Nothing about the live cluster.** No `kubectl` of any kind was run on this branch — not even
+  read-only; this change is offline CI wiring and needed none. No `apply`/`edit`/`patch`, no
+  `flux reconcile`. Merging this deploys nothing: it changes only what the gate refuses.
+- **CI's own run of this branch.** Quoted in the PR body from the commit's `/statuses`, with
+  descriptions read rather than colours. A *skipped* Gitea job reports `success` with
+  "Has been skipped" and certifies nothing.
+- **`vars.CLUSTER_AVAILABLE` is still unset in CI**, so even a fully green PR proves the L0/L1
+  offline subset and nothing about runtime behaviour.
+- **I did not re-measure branch protection, required approvals, or the runner.** Those are
+  CLAUDE.md §2 claims and §2b says re-measure before relying on them; this branch relies on none
+  of them beyond the PR flow itself, and I read the gate's own output rather than the API.

infra/gitea/README.md

@@ -52,7 +52,7 @@ All four steps are complete and each was verified, not assumed:
 | 1. Runner registered | ✅ `incluster-dind` online. Root cause of its absence was a stale `/data/.runner` identity; clearing the PVC forced re-registration |
 | 2. Gate observed green on a real PR | ✅ `gate / gate (pull_request)` ~1m35s |
 | 3. `enable_status_check: true` | ✅ context `gate / gate (pull_request)` — that one ONLY |
-| 4. Collaborator + approvals | ✅ `jakman85` is owner; `required_approvals: 1` |
+| 4. Collaborator + approvals | ✅ `jakman85` is owner. `required_approvals` was raised to 1 here and **lowered back to 0 on 2026-10-01** — see §6, it was a lock-out |
 
 Direct push to `main` was **provoked and rejected** (`pre-receive hook declined`) as
 `gitea-admin`, a site admin — so push protection is not merely declared, it holds for the
@@ -124,6 +124,55 @@ the stage goes **green on a real PR**, and only then set `REQUIRE_GITEA_SETTINGS
 **Changing the declaration is how you change policy.** If the live state is what you now want,
 edit this JSON in the same commit — deliberately, in review — rather than letting the two drift.
 
+### 6. `allow-admin-self-merge.sh` — undoing the lock-out step 4 created (2026-10-01)
+
+Step 4 above raised `required_approvals` to 1. That was a **lock-out, not a protection**, and the
+note at the bottom of `require-gate.sh` had already said why: *Gitea will not let an author approve
+their own PR.* With `jakman85` the only collaborator, there was no account in existence that could
+approve a PR `jakman85` opened.
+
+Measured 2026-10-01 — **PR #35**: `gate / gate (pull_request)` **success in 1m41s**, reviews `[]`,
+`required_approvals: 1`, `block_admin_merge_override: true`. Unmergeable, permanently, with no
+action available to its author. The same was true of any PR fixing it.
+
+It was also never the documented design. `ci/approval-policy.sh`'s header and `ci/gate.sh:194`
+both already describe the model as *"`required_approvals` drops to 0 and the GATE decides"*, and
+`decisions/2026-09-30-flux-deploy-notification-inhibited.md` flagged the 1-vs-0 disagreement as
+unresolved and not that session's to settle. So this is a correction toward the stated intent, not
+a weakening away from it.
+
+    ./infra/gitea/allow-admin-self-merge.sh      # required_approvals -> 0 (read from the declaration)
+
+**What stays switched on, and why that is the point.** The other way to unblock an owner is
+`block_admin_merge_override: false`, and it would have been the wrong one — that re-opens exactly
+what §5 above closed, letting the one account that merges bypass the gate itself. This script
+touches the approval **count** only and *verifies* afterwards that `block_admin_merge_override` and
+`enable_status_check` are both still `true`, failing loudly if the PATCH disturbed either:
+
+| | before | after |
+|---|---|---|
+| `required_approvals` | 1 | **0** |
+| `block_admin_merge_override` | true | true (asserted) |
+| `enable_status_check` | true | true (asserted) |
+
+So a **red gate is still unmergeable by everyone, administrators included**. What changed is that
+a *green* one no longer needs a signature that cannot exist.
+
+**Security-relevant changes are still reviewed** — by `ci/approval-policy.sh` against
+`approval-policy.json` `sensitive_paths`, not by this field. An administrator waives that review
+only by posting `/approve-override <reason>` on the PR: reason mandatory, permission re-checked
+live, invalidated by a new commit, and recorded by account in the gate summary. Note that the
+**agent account `gitea-admin` also reports permission `owner`**, so it can clear its own PRs that
+way; that is an accepted consequence of authorising by permission alone, and the route to
+narrowing it (an `override_admins` allowlist, already honoured by the code) is written down in
+`approval-policy.json`.
+
+**Sequencing.** `ci/gitea-settings.sh` compares live against the declaration *from the branch under
+test*, and `REQUIRE_GITEA_SETTINGS=true`. So merge any other open PRs **before** running this, then
+run it, then re-run the gate on the branch carrying the new declaration. Any PR left open across
+the change declares 1 against a live 0 and goes **red until rebased** — the detector working, not
+a fault. The script's header spells the order out.
+
 ## `conformance-trigger-kubeconfig.sh` — the narrow L2/L3 trigger credential
 
 Implements `docs/plans/l2-l3-conformance-ci-wiring.md` §3 item 6 (= §5 step 7): mint a
@@ -204,6 +253,8 @@ it. The name matters — see the note under the behaviour table above.)
 2. **Watch the gate actually report on a real PR**, and note the context name it produced.
 3. **Only then set `enable_status_check: true`** with that exact context.
 4. Add the human reviewer as a repo collaborator, then raise `required_approvals` to 1.
+   — **Step 4 was REVERSED on 2026-10-01 (§6).** It assumed a reviewer distinct from the author
+   would exist. One never did, so this step produced a lock-out. Do not re-apply it.
 
 > **Do not do step 3 before step 1.** A required status check with no runner leaves every
 > PR permanently pending — including the PR that would fix it. That half is measured: PR #1

infra/gitea/allow-admin-self-merge.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Let the sole administrator merge their own green PR: required_approvals 1 -> 0 on `main`.
+#
+# WHY. `required_approvals: 1` plus Gitea's refusal to let an author approve their own pull
+# request plus exactly ONE collaborator (`jakman85`, permission `owner`) is a lock-out, not a
+# policy. Every PR the operator opened was permanently unmergeable, including the PR that would
+# fix it. Measured 2026-10-01: PR #35 — `gate / gate (pull_request)` success in 1m41s, zero
+# reviews, `required_approvals: 1`, no account in existence able to satisfy it.
+#
+# The approvals field was also never what the design said it was. `ci/approval-policy.sh`'s
+# header and `ci/gate.sh:194` both already described the model as "required_approvals: 0 and the
+# GATE decides", and `require-gate.sh`'s own closing note named this exact failure and this exact
+# remedy. decisions/2026-09-30-flux-deploy-notification-inhibited.md flagged the 1-vs-0
+# disagreement as unresolved. This resolves it at 0.
+#
+# WHAT THIS DOES *NOT* DO, and the distinction is the whole point.
+#
+#   * It does NOT touch `block_admin_merge_override`, which stays TRUE. The required status check
+#     still binds ABSOLUTELY — a red gate is unmergeable by everyone, administrators included.
+#     Setting `block_admin_merge_override: false` would have been the other way to unblock an
+#     owner, and it would have re-opened precisely what block-admin-override.sh was written to
+#     close: PRs #5-#9 merged with zero approvals while the settings read as enforced.
+#   * It does NOT stop reviewing security-relevant changes. Those are gated by
+#     ci/approval-policy.sh against infra/gitea/approval-policy.json `sensitive_paths`, which an
+#     administrator can waive only with an explicit, attributed `/approve-override <reason>`
+#     comment on the PR.
+#
+# ORDER MATTERS — READ THIS BEFORE RUNNING IT.
+#
+# ci/gitea-settings.sh fails the merge gate on ANY divergence between the live rule and
+# infra/gitea/expected-branch-protection.json, and `gate.yml` sets REQUIRE_GITEA_SETTINGS=true.
+# The declaration in git now says 0. So between running this and merging that declaration, the
+# live value and the declared value must be compared from a branch that CARRIES the new
+# declaration — otherwise the stage goes red, correctly, for drift.
+#
+#   1. MERGE any other open PRs FIRST, while approvals still work for them (their branches
+#      declare 1, and a PR you did not author can still be approved normally). Skipping this
+#      only costs a rebase later; it does not break anything.
+#   2. Run this script.
+#   3. Re-run the gate on the branch that carries the new declaration. `gitea-settings` goes
+#      green because live 0 == declared 0.
+#   4. Merge that branch.
+#   5. Any PR still open from before step 2 now declares 1 against a live 0 and will be RED
+#      until it is rebased onto the new main. That is the detector doing its job, not a fault.
+#
+# Recoverable: `required_approvals` can be PATCHed back to 1 by an owner at any time. If you do,
+# change expected-branch-protection.json in the same breath or every PR goes red on drift.
+set -euo pipefail
+HOST=gitea.home.keithjackson.dev; OWNER=Home-Network; REPO=home-network-k3s-impl
+DECL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/expected-branch-protection.json"
+
+command -v jq >/dev/null || { echo "jq is required" >&2; exit 1; }
+[ -f "$DECL" ] || { echo "declaration missing: ${DECL}" >&2; exit 1; }
+
+# Take the target from the DECLARATION, not from a literal here. If the two could disagree,
+# this script would be one more thing re-asserting a value nothing checks — which is the
+# failure mode the whole of infra/gitea/ exists to stop.
+WANT="$(jq -r '.protection.required_approvals' "$DECL")"
+[[ "$WANT" =~ ^[0-9]+$ ]] || { echo "declaration has no numeric required_approvals" >&2; exit 1; }
+
+creds="$(printf 'protocol=https\nhost=%s\n\n' "$HOST" | git credential fill)"
+U="$(sed -n 's/^username=//p' <<<"$creds")"; P="$(sed -n 's/^password=//p' <<<"$creds")"
+[ -n "$U" ] && [ -n "$P" ] || { echo "no stored credential for $HOST" >&2; exit 1; }
+echo "authenticating as '${U}' (secret not shown)"
+api() { curl -sS --config <(printf 'user = "%s:%s"\n' "$U" "$P") "$@"; }
+B="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/branch_protections/main"
+
+# Read the RULE OBJECT, never /branches/main: the branch view does not expose
+# block_admin_merge_override and showed all-green for hours while the rule was overridable.
+echo "==> before"
+api "$B" | jq -r '{required_approvals, block_admin_merge_override, enable_status_check, status_check_contexts}'
+
+echo "==> setting required_approvals = ${WANT} (declared in expected-branch-protection.json)"
+api -X PATCH -H 'Content-Type: application/json' \
+  -d "{\"required_approvals\": ${WANT}}" "$B" >/dev/null
+
+echo "==> after"
+AFTER_JSON="$(api "$B")"
+jq -r '{required_approvals, block_admin_merge_override, enable_status_check, status_check_contexts}' <<<"$AFTER_JSON"
+
+GOT="$(jq -r '.required_approvals' <<<"$AFTER_JSON")"
+ADMIN_BLOCK="$(jq -r '.block_admin_merge_override' <<<"$AFTER_JSON")"
+STATUS="$(jq -r '.enable_status_check' <<<"$AFTER_JSON")"
+
+fail=0
+[ "$GOT" = "$WANT" ] || { echo "PATCH did not take: required_approvals is ${GOT}, wanted ${WANT}" >&2; fail=1; }
+# These two are what keeps this change narrow. If the PATCH disturbed either, the gate has
+# stopped binding and that must be loud, not discovered later.
+[ "$ADMIN_BLOCK" = true ] || { echo "block_admin_merge_override is ${ADMIN_BLOCK}, MUST be true — the gate is now bypassable" >&2; fail=1; }
+[ "$STATUS" = true ]      || { echo "enable_status_check is ${STATUS}, MUST be true — the gate is no longer required" >&2; fail=1; }
+[ "$fail" -eq 0 ] || { echo "do NOT record this as applied." >&2; exit 1; }
+
+cat <<'NOTE'
+
+NOW PROVE IT -- the setting is not the evidence. Two things to see, not assume:
+
+  1. An APPROVAL IS NO LONGER NEEDED. On your own PR with a green gate, the merge button is
+     live with zero reviews on it.
+  2. THE GATE STILL BINDS. On a PR whose gate is RED or still pending, Gitea must REFUSE the
+     merge -- for you, as owner. If it lets you through, block_admin_merge_override is not
+     doing its job and this change has traded a lock-out for a bypass.
+
+Then confirm the detector agrees: run ci/gate.sh from a branch carrying the new
+expected-branch-protection.json and check that `gitea-settings` is green rather than DRIFT.
+NOTE

infra/gitea/approval-policy.json

@@ -1,6 +1,6 @@
 {
   "_intent": "The CI/CD pipeline is the approver. A human approval is required ONLY for changes that alter what the pipeline itself verifies, or the security posture it rests on -- because those are the changes CI cannot honestly gate: a PR that weakens the gate would be approved by the weakened gate.",
-  "_rule": "If a PR touches any sensitive_paths glob, it needs an APPROVED review from someone who is not its author. Everything else merges on a green gate alone.",
+  "_rule": "If a PR touches any sensitive_paths glob, it needs an APPROVED review from someone who is not its author, OR an admin override (see .override). Everything else merges on a green gate alone.",
   "_on_failure_to_evaluate": "BLOCK. Unlike gitea-settings, a skip here is a bypass, not a gap.",
   "sensitive_paths": [
     "ci/**",
@@ -24,5 +24,17 @@
     "platform/kyverno/**": "the admission policy engine",
     ".sops.yaml, **/*.sops.yaml, **/rbac.yaml": "encryption recipients, secrets, and cluster authority",
     "CLAUDE.md": "the delivery contract agents follow"
+  },
+  "override": {
+    "_why": "This repository has ONE human. Gitea refuses to let an author approve their own pull request, so 'a non-author APPROVED review' is a requirement the sole administrator can never satisfy -- every sensitive-path PR they open was permanently unmergeable, including the PR that would fix it. Measured 2026-10-01: PR #35 green gate, zero reviews, unmergeable. An escape hatch that the administrator can actually reach is therefore REQUIRED for the repository to function; the design question is only whether it leaves a record. This one does.",
+    "enabled": true,
+    "comment_directive": "/approve-override",
+    "requires_reason": true,
+    "authorized_permissions": ["admin", "owner"],
+    "invalidated_by_new_commits": true,
+    "_how": "Comment on the PR with the directive at the START of a line, followed by a reason: '/approve-override <why>'. ci/approval-policy.sh resolves the commenter's LIVE repo permission via /collaborators/{login}/permission and accepts the override only if it is in authorized_permissions. The overrider, the timestamp and the reason are printed in the gate log and the job summary.",
+    "_self_override_is_allowed": "The author may override their own PR if they hold an authorized permission. That is the entire point -- with one human there is no one else -- but it means the 'a change to the gate cannot be gated by the gate' protection is, for an administrator, advisory rather than structural. It is traded for an auditable record: the waiver is an explicit act, attributed, with a stated reason, in the PR's comment history and the gate output.",
+    "_known_consequence_agent_accounts": "ACCEPTED, EYES OPEN (operator decision, 2026-10-01). Authorisation is by live permission ALONE, with no allowlist of human accounts. The agent account `gitea-admin` reports permission `owner` on this repo (measured 2026-10-01), so an AGENT can clear the sensitive-path review on its own PR by posting the directive. Agents author most PRs here, so this is the broad case, not the edge case. To narrow it later without changing any logic, add an `override_admins` allowlist here and require membership in addition to the permission check -- ci/approval-policy.sh reads both from this file.",
+    "_staleness": "An override is dropped unless its comment is NEWER than the PR head commit, mirroring Gitea's own dismiss_stale_approvals. An override earned at commit A therefore does not silently cover commit B; push again and you must override again."
   }
 }

infra/gitea/expected-branch-protection.json

@@ -1,6 +1,9 @@
 {
   "_comment": "DECLARED desired state of Gitea branch protection on main. ci/gitea-settings.sh fails the merge gate when the LIVE Gitea diverges from this. Gitea settings live in Gitea database - invisible to Flux, unreadable by every other check - so this file plus that check are the only drift detection that exists for them.",
   "_generated": "2026-09-29 from the live rule, after the session that found protection OFF and zero runners for a month",
+  "_amended": "2026-10-01: required_approvals 1 -> 0. See _why_required_approvals_is_zero.",
+  "_why_required_approvals_is_zero": "The GATE is the approver (operator intent, 2026-09-29). required_approvals: 1 was never consistent with that intent: ci/approval-policy.sh's header and ci/gate.sh:194 both already described the model as 'required_approvals: 0 and the GATE decides', and infra/gitea/require-gate.sh's own closing note named the consequence of 1 -- 'Gitea will not let an author approve their own PR'. With exactly ONE collaborator (jakman85, owner), that made every PR the operator opened permanently unmergeable. Measured 2026-10-01: PR #35, gate green in 1m41s, zero reviews, no path to a merge. decisions/2026-09-30-flux-deploy-notification-inhibited.md had already flagged the 1-vs-0 disagreement as unresolved; this settles it at 0.",
+  "_what_still_holds_at_zero": "This drops the APPROVAL COUNT only. block_admin_merge_override stays TRUE and enable_status_check stays TRUE, so the required gate context still binds absolutely -- nobody, administrator included, can merge a red gate. That distinction is the whole reason this is the chosen fix rather than block_admin_merge_override: false, which would have handed admins a bypass over the gate itself and re-opened what infra/gitea/block-admin-override.sh was written to close (PRs #5-#9, merged with zero approvals). Architecturally and security-relevant paths are still reviewed, by ci/approval-policy.sh rather than by this field.",
   "branch": "main",
   "runners_online_min": 1,
   "protection": {
@@ -11,7 +14,7 @@
     "status_check_contexts": [
       "gate / gate (pull_request)"
     ],
-    "required_approvals": 1,
+    "required_approvals": 0,
     "enable_approvals_whitelist": false,
     "block_admin_merge_override": true,
     "block_on_rejected_reviews": true,

infra/gitea/require-gate.sh

@@ -34,7 +34,7 @@ jq -n '{
   enable_push: false,
   enable_status_check: true,
   status_check_contexts: ["gate / gate (pull_request)"],
-  required_approvals: 1,
+  required_approvals: 0,
   block_on_rejected_reviews: true,
   dismiss_stale_approvals: true,
   block_on_outdated_branch: false,
@@ -48,11 +48,21 @@ api "https://${HOST}/api/v1/repos/${OWNER}/${REPO}/branches/main" \
 
 cat <<'NOTE'
 
-NOTE ON required_approvals: 1 -- Gitea will not let an author approve their own PR.
+NOTE ON required_approvals: 0 -- CHANGED FROM 1 ON 2026-10-01, and this script is the reason
-  * Agent-opened PRs (author gitea-admin) are approved by jakman85. Fine.
+the change had to land here too: re-running it with 1 would silently re-impose the lock-out.
-  * PRs YOU open as jakman85 need gitea-admin to approve. If that is awkward, either open
+
-    agent work as gitea-admin and review as jakman85, or set required_approvals back to 0
+The note that used to sit here called the problem and its own fix: "Gitea will not let an
-    and rely on the status check alone.
+author approve their own PR ... if that is awkward ... set required_approvals back to 0 and
+rely on the status check alone." It was awkward. With jakman85 the ONLY collaborator, every PR
+the operator opened was unmergeable -- measured on PR #35, gate green in 1m41s, zero reviews,
+nothing that could ever satisfy the rule. So: 0, and the status check alone, as written.
+
+What did NOT change, deliberately:
+  * block_admin_merge_override stays TRUE. This drops the approval COUNT; it does not hand
+    anyone a bypass over the gate. A red gate is still unmergeable by everybody.
+  * Architecturally/security-relevant paths are still human-reviewed -- by ci/approval-policy.sh
+    (sensitive_paths in infra/gitea/approval-policy.json), which an administrator can waive
+    only by posting an explicit, attributed `/approve-override <reason>` comment.
 
 Then prove it, rather than trusting the API:
   git commit --allow-empty -m probe && git push origin main   # EXPECT: rejected

platform/intel-gpu-plugin/README.md

@@ -0,0 +1,225 @@
+# platform/intel-gpu-plugin
+
+**Intel Device Plugin for Kubernetes (GPU)** — the standalone GPU plugin DaemonSet from
+[`intel/intel-device-plugins-for-kubernetes`](https://github.com/intel/intel-device-plugins-for-kubernetes),
+pinned at **v0.37.0**. It makes every node advertise **`gpu.intel.com/i915`** so a workload can
+*request* a GPU instead of hoping a `hostPath` is enough.
+
+- **Serves:** hardware transcoding for Plex (`hardware.gpu: intel-quicksync`), and any later
+  consumer of an Intel iGPU.
+- **Tier:** its **own** Flux Kustomization
+  ([`clusters/base/intel-gpu-plugin.yaml`](../../clusters/base/intel-gpu-plugin.yaml),
+  `dependsOn: cilium`, `wait: true`) — **not** a line in `platform/kustomization.yaml`. See
+  *Placement* below.
+- **Namespace:** `intel-gpu-plugin` — a PLATFORM namespace, labelled
+  `homelab.keithjackson.dev/app-namespace: "false"`, so the app-scoped Kyverno policies
+  (default-deny generation, auth-mode, egress-class, host-namespaces) do not apply.
+- **No RBAC, no ServiceAccount, no CRDs, no webhook, no API-server access.** A device plugin talks
+  to the *local kubelet* over a unix socket.
+
+## What this component owns
+
+| File | Purpose |
+|---|---|
+| `namespace.yaml` | `intel-gpu-plugin` ns, explicitly `app-namespace=false` |
+| `intel-gpu-plugin.yaml` | the DaemonSet, **vendored** (machine-generated) from upstream v0.37.0 |
+| `kustomization.yaml` | namespace scoping + the pinned image (`images:` transformer) |
+
+## The problem this fixes
+
+Plex was given a `/dev/dri` hostPath (merged on `main` @ `cdf3e14`). The device is **visible** in
+the container and **cannot be opened**. Measured in the running pod on `k3s-prod-2`:
+
+```
+uid 0,    O_RDWR -> EPERM "Operation not permitted"
+uid 1000, O_RDWR -> EPERM "Operation not permitted"
+```
+
+`EPERM` from the **device cgroup**, not `EACCES` from file permissions — proven three ways:
+
+1. root on the **host** opens the same device with `rc=0`;
+2. the node is unified `cgroup2fs`;
+3. the container's runc `config.json` reads
+   `linux.resources.devices: [{'allow': False, 'access': 'rwm'}]` and `linux.devices: None` —
+   one deny-all rule, no allow entry for major 226, and the runtime was never asked to grant a
+   device.
+
+A hostPath is a **filesystem** operation. It makes the device *node* appear and adds no cgroup
+allow rule, because Kubernetes cannot infer one from a volume.
+
+**A device plugin is the mechanism that closes exactly this gap.** Verified in the v0.37.0 source
+(`cmd/gpu_plugin/gpu_plugin.go`, `createDeviceSpecsFromDrmFiles`), the `Allocate` response carries
+per DRM node:
+
+```go
+specs = append(specs, pluginapi.DeviceSpec{
+    HostPath: devPath, ContainerPath: devPath, Permissions: "rw",
+})
+```
+
+and it is that `DeviceSpec` which makes kubelet populate `linux.devices` **and** the matching
+cgroup allow rule. It is the only **non-privileged** way to get there. `privileged: true` would
+also work and is not available: `platform/kyverno/policies/restrict-host-namespaces.yaml` blocks it
+under Enforce in app namespaces, and `plex` is labelled `app-namespace=true` (measured
+2026-10-01). Correctly so.
+
+## Placement — why its own Kustomization
+
+The cheap option was one line in the shared `platform` tier. Neither that file nor a new
+`platform/<name>/` directory is a sensitive path in `infra/gitea/approval-policy.json`, so it would
+have needed no human reviewer *on the policy's terms*. It is still the wrong place, and the repo
+already argued the case when Cilium was split out (read the comment in
+`platform/kustomization.yaml`):
+
+* `platform` is `wait: true` over eleven-plus components, so its Ready condition cannot distinguish
+  "the GPU plugin is wedged" from "longhorn is slow".
+* The only emergency valve would be `flux suspend kustomization platform` — freezing storage, TLS,
+  DNS, ingress, monitoring, Keycloak and KubeVirt in order to stop touching a device plugin.
+* The tier's 10m/5m interval/timeout are called out there as **wrong for a 3-node DaemonSet
+  rollout**. This is a 3-node DaemonSet rollout.
+
+The consequence is worse than average here because of what sits downstream: `platform` gates
+`platform-config`, which gates `apps-wave-0` (`wait: true`), which gates `apps-wave-1`. A plugin
+that never went healthy inside that tier would stall **every app** on "dependency not ready" — so a
+component added to fix a *silent no-op* (software transcoding) would have acquired the ability to
+cause a *real outage*.
+
+The usual objection — that `clusters/**` needs a human approval — costs nothing: Gitea enforces
+`required_approvals: 1` with `block_admin_merge_override: true` on **every** PR here regardless of
+path, and authors cannot self-approve. The approval was required either way.
+
+### `wait: true` is a health signal, not a gate
+
+This departs from the `headlamp`/`crafty` leaf template, deliberately. Those run `wait: false`
+because a leaf UI can be legitimately not-Ready for a long time during a cold start while it waits
+on Keycloak/DNS/TLS, making its health useless as a signal. This DaemonSet has no such dependency —
+it reads sysfs and opens a socket, so on healthy nodes it is Ready in seconds and **not-Ready
+genuinely means broken**. `wait: true` makes `flux get kustomization intel-gpu-plugin` a one-line
+answer to "did it come up on all three nodes", which is precisely the question that must be
+answered before the consumer PR may merge.
+
+Nothing in the graph `dependsOn` this, so `wait: true` gates nothing. **Think hard before adding
+`dependsOn: [intel-gpu-plugin]`** anywhere — for the app waves that would hand a device plugin the
+power to stall every app, which is the thing this placement exists to prevent.
+
+## Deliberate non-choices
+
+**Standalone DaemonSet, not the operator.** The operator adds a CRD (`GpuDevicePlugin`), a
+controller-manager Deployment, cert-manager-backed admission webhooks and a second namespace —
+three more things that can be unhealthy — to buy declarative management of a DaemonSet that is
+already declared in git. For three identical nodes and one consumer that is strictly more blast
+radius for no gain.
+
+**It lists devices; it never opens them** — worth being certain about, since *opening* is exactly
+what fails today. Verified in v0.37.0 source: the scan path uses only `os.ReadDir`, `os.ReadFile`,
+`os.Stat` and `os.Readlink` over `/sys/class/drm` and `/dev/dri`. There is no `os.Open`, no
+`OpenFile`, no `ioctl` and no raw syscall against a DRM node anywhere in
+`cmd/gpu_plugin/gpu_plugin.go`. Listing and `stat()` demonstrably work today — that is how the Plex
+probe found the device before failing to open it — so the plugin needs no cgroup grant of its own
+and no privilege. Accordingly `/dev/dri` and `/sys/class/drm` are mounted **readOnly**.
+
+* **`--health-management` stays OFF** (upstream default). It is the one flag that *would* need to
+  open a device: it starts a Level-Zero sidecar (`setupLevelZeroService` returns early unless the
+  flag is set). Enabling it would reintroduce the exact `EPERM` this component exists to fix.
+* `/dev/dri/by-path` being absent is non-fatal — `newDevicePlugin` warns and sets
+  `bypathFound = false`.
+
+**`--shared-dev-num` left at the upstream default of 1** (i.e. not set). The flag multiplies each
+card into N schedulable device IDs, letting N containers share one GPU. Not raised, because:
+
+* Plex is the only consumer today and wants one device;
+* the count is a **lie the scheduler believes** — there is no GPU-side partitioning or quota behind
+  it, so N containers get the same `renderD128` and contend for the same two media engines
+  (`vcs0`/`vecs0`). Raising it converts "Unschedulable", which is loud and obvious, into
+  "transcodes are mysteriously slow", which is neither;
+* it is a one-line, zero-migration change on the day a second consumer exists — and *then* the
+  right number will be known rather than guessed.
+
+**No NFD overlay.** All three nodes are identical (HP EliteDesk 800 G5 Mini, i7-9700T, UHD Graphics
+630, PCI `8086:3e98`, `i915` bound), so a nodeSelector on a GPU feature label would gate on
+something true everywhere. If a GPU-less node ever joins, add upstream's `nfd` overlay *then*
+rather than relying on the plugin's behaviour on such a node.
+
+**No `supplementalGroups`, anywhere.** The `pms-docker` image's own cont-init hook stats each
+`/dev/dri` char device and adds the `plex` user to its group — measured live as
+`Groups: 44 100 992 1000` on the running Plex process, where GID 992 is the host `render` group.
+That mechanism is image-side and works identically on a plugin-injected device.
+
+## Resource name
+
+`gpu.intel.com/i915`. Not a guess: `scan()` calls `devTree.AddDevice(devProps.driver(), ...)`, so
+the suffix is the **kernel driver name**. These nodes have `i915` bound (not `xe`), so the resource
+is `i915`. A future kernel moving CoffeeLake to `xe` would silently rename it to `gpu.intel.com/xe`
+and a consumer's request would stop matching — worth knowing before that kernel arrives.
+
+## Versioning
+
+Pinned to **v0.37.0** via the `images:` transformer in `kustomization.yaml`; the DaemonSet itself is
+vendored as `kubectl kustomize` output of the upstream base (see its header for the exact re-vendor
+command and both sha256s). It is *generated* rather than a byte copy because upstream mixes YAML
+sequence-indentation styles within the one document and `ci/yamllint.yaml` sets
+`indent-sequences: consistent` — a verbatim copy is a hard lint error that blocks the gate
+(measured: it did). `kubectl kustomize` normalises the formatting, and the result was proven to be
+a formatting-only change: `yq -P 'sort_keys(..)'` of the generated file and of the raw upstream file
+diff clean. This is also the re-vendor idiom `platform/external-snapshotter` documents.
+
+Vendored rather than referenced as a remote kustomize base for the same reason as
+`platform/external-snapshotter`: a remote base is `git fetch`ed on **every** reconcile, those
+fetches intermittently exceeded kustomize-controller's 27s timeout, and transient GitHub slowness
+then rendered as "kustomize build failed". A local file makes the build offline and deterministic —
+which also means the CI gate's `kustomize build` proves the manifests rather than proving GitHub
+was up.
+
+Renovate tracks it through the inline-marker idiom (`# renovate: datasource=github-releases
+depName=...` immediately above the version literal), because `renovate.json` sets
+`"docker": {"enabled": false}` and `"kubernetes": {"enabled": false}` — an image reference in a
+plain manifest is tracked by nothing. **Caveat:** upstream *release* tags carry a `v` (`v0.37.0`)
+while *image* tags do not (`0.37.0`). Whether Renovate normalises that for this dep is unverified;
+if it ever proposes `newTag: v0.38.0`, the fix is an `extractVersion` packageRule in
+`renovate.json`, not a hand-edit.
+
+## Ordering — do not reorder the stack
+
+The renderer change (`catalog/render.py` emitting `gpu.intel.com/i915: 1` for
+`hardware.gpu: intel-quicksync` instead of the hostPath) **must not land until this plugin is
+merged AND confirmed advertising the resource on all three nodes.** If the renderer requests a
+resource no node advertises, the Plex pod is **Unschedulable**; `apps-wave-0` is `wait: true` and
+`apps-wave-1` `dependsOn` it, so that stalls the whole app tier — turning today's silent no-op into
+a real outage.
+
+## Post-merge verification
+
+Nothing about this component's runtime behaviour can be verified from a PR: it does not exist until
+the operator merges and Flux reconciles. Afterwards:
+
+```bash
+D=./infra/devcontainer/dev.sh
+
+# 1. Flux applied it, and (wait:true) the DaemonSet went healthy.
+$D run bash -c 'flux get kustomization intel-gpu-plugin'
+$D run bash -c 'kubectl --context k3s-prod -n intel-gpu-plugin get ds intel-gpu-plugin'
+#    want: DESIRED=3 CURRENT=3 READY=3 AVAILABLE=3
+
+# 2. The resource is advertised on ALL THREE nodes. This is the gate on the renderer PR.
+$D run bash -c 'kubectl --context k3s-prod get nodes -o json \
+  | jq -r ".items[] | \"\(.metadata.name) i915=\(.status.allocatable[\"gpu.intel.com/i915\"] // \"ABSENT\")\""'
+#    want: three lines, each i915=1   (before this change: ABSENT on all three)
+
+# 3. If a node shows ABSENT, read that node's plugin logs.
+$D run bash -c 'kubectl --context k3s-prod -n intel-gpu-plugin logs -l app=intel-gpu-plugin --tail=50 --prefix'
+```
+
+### The decisive test
+
+Resource-advertised is necessary but **not** sufficient — it proves the plugin registered, not that
+the cgroup allow rule reaches Plex. The decisive test is re-running the `open()` probe **as uid 1000
+through `s6-setuidgid plex`** inside the Plex pod, *after* the renderer PR has switched Plex to
+request the resource:
+
+```bash
+$D run bash -c 'kubectl --context k3s-prod -n plex exec deploy/plex -- \
+  s6-setuidgid plex python3 -c "import os; os.close(os.open(\"/dev/dri/renderD128\", os.O_RDWR)); print(\"rc=0 OK\")"'
+```
+
+**Passing as uid 0 is weaker evidence and must not be accepted as proof** — Plex transcodes as uid
+1000, and the two differ in group membership, which is the half the image's cont-init hook supplies.

platform/intel-gpu-plugin/intel-gpu-plugin.yaml

@@ -0,0 +1,117 @@
+---
+# VENDORED, MACHINE-GENERATED, from intel/intel-device-plugins-for-kubernetes @ v0.37.0:
+#   deployments/gpu_plugin/base
+#
+# RE-VENDOR on a version bump (and bump `newTag` in kustomization.yaml to match):
+#   kubectl kustomize \
+#     "https://github.com/intel/intel-device-plugins-for-kubernetes/deployments/gpu_plugin/base?ref=vX.Y.Z" \
+#     > platform/intel-gpu-plugin/intel-gpu-plugin.yaml
+#   # then re-add this header, and READ THE DIFF — upstream has changed the securityContext
+#   # and the volume set between minor releases before.
+#
+# Generated 2026-10-01 at v0.37.0; sha256 of the body below (header excluded):
+#   80ebd070f983f3116f4004f719d9c872220997ec766b4ab7e7290585ac8ef842
+# The raw upstream source file reviewed to produce it
+# (deployments/gpu_plugin/base/intel-gpu-plugin.yaml) was sha256
+#   c8773918c2370e711d4ba84120a9971a290bf75ecf81dc520782bcccd7ef24b6
+# and the two were proven EQUIVALENT, not merely similar: `yq -P 'sort_keys(..)'` of each diffs
+# clean, so passing it through kustomize changed formatting only and no content.
+#
+# WHY GENERATED RATHER THAN A BYTE COPY of the upstream file: upstream mixes YAML sequence
+# indentation styles within the one document (`containers:` non-indented, `env:` indented), and
+# ci/yamllint.yaml sets `indentation: indent-sequences: consistent`, so a verbatim copy is a hard
+# lint ERROR and blocks the merge gate — measured, this file failed exactly that way first time
+# round. `kubectl kustomize` normalises the output, which is also precisely the re-vendor idiom
+# platform/external-snapshotter documents for the same reason.
+#
+# WHY VENDORED AT ALL rather than a remote kustomize base (`...gpu_plugin/base?ref=v0.37.0` left in
+# `resources:`): the same reason platform/external-snapshotter is vendored. A remote base is
+# `git fetch`ed by Flux's kustomize-controller on EVERY reconcile, those fetches intermittently
+# exceeded the controller's 27s timeout, and a transient GitHub slowness then rendered as
+# "kustomize build failed" on the whole tier. A local file makes the build OFFLINE and
+# deterministic — which also means `kustomize build` in the CI gate proves the real thing instead
+# of proving GitHub was up. (platform/kubevirt still carries the remote-base pattern and its latent
+# fragility; not this component's problem.)
+#
+# DO NOT HAND-EDIT THE BODY. Every local change belongs in kustomization.yaml as a transformer or
+# patch, so the next re-vendor stays a mechanical regenerate-and-diff instead of a three-way merge.
+# The image tag below is re-pinned (and fully qualified) by the `images:` transformer there. The
+# rationale for each thing deliberately NOT changed — no privileged, no supplementalGroups, no
+# -shared-dev-num, no NFD overlay, no health-management — is in README.md.
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  labels:
+    app: intel-gpu-plugin
+  name: intel-gpu-plugin
+spec:
+  selector:
+    matchLabels:
+      app: intel-gpu-plugin
+  template:
+    metadata:
+      labels:
+        app: intel-gpu-plugin
+    spec:
+      containers:
+      - env:
+        - name: NODE_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: spec.nodeName
+        - name: HOST_IP
+          valueFrom:
+            fieldRef:
+              fieldPath: status.hostIP
+        image: intel/intel-gpu-plugin:0.37.0
+        imagePullPolicy: IfNotPresent
+        name: intel-gpu-plugin
+        resources:
+          limits:
+            cpu: 100m
+            memory: 115Mi
+          requests:
+            cpu: 40m
+            memory: 45Mi
+        securityContext:
+          allowPrivilegeEscalation: false
+          capabilities:
+            drop:
+            - ALL
+          readOnlyRootFilesystem: true
+          seLinuxOptions:
+            type: container_device_plugin_t
+          seccompProfile:
+            type: RuntimeDefault
+        volumeMounts:
+        - mountPath: /dev/dri
+          name: devfs
+          readOnly: true
+        - mountPath: /sys/class/drm
+          name: sysfsdrm
+          readOnly: true
+        - mountPath: /var/lib/kubelet/device-plugins
+          name: kubeletsockets
+        - mountPath: /var/run/cdi
+          name: cdipath
+      nodeSelector:
+        kubernetes.io/arch: amd64
+      volumes:
+      - hostPath:
+          path: /dev/dri
+        name: devfs
+      - hostPath:
+          path: /sys/class/drm
+        name: sysfsdrm
+      - hostPath:
+          path: /var/lib/kubelet/device-plugins
+        name: kubeletsockets
+      - hostPath:
+          path: /var/run/cdi
+          type: DirectoryOrCreate
+        name: cdipath
+  updateStrategy:
+    rollingUpdate:
+      maxSurge: 0
+      maxUnavailable: 1
+    type: RollingUpdate

platform/intel-gpu-plugin/kustomization.yaml

@@ -0,0 +1,99 @@
+---
+# Intel GPU device plugin for Kubernetes — makes the nodes advertise `gpu.intel.com/i915`.
+#
+# WHAT THIS FIXES, and why nothing cheaper works. Plex already has a `/dev/dri` hostPath mount
+# (merged on main @ cdf3e14). The device node is VISIBLE in the container and cannot be OPENED.
+# Measured in the running pod on k3s-prod-2:
+#     uid 0,    O_RDWR -> EPERM "Operation not permitted"
+#     uid 1000, O_RDWR -> EPERM "Operation not permitted"
+# EPERM from the DEVICE CGROUP, not EACCES from file permissions — proven three ways: root on the
+# HOST opens the same device rc=0; the node is unified cgroup2fs; and the container's runc
+# config.json carries one deny-all rule and nothing else:
+#     linux.resources.devices: [{'allow': False, 'access': 'rwm'}]
+#     linux.devices: None
+# No allow entry for major 226, and the runtime was never asked to grant a device. A hostPath is a
+# FILESYSTEM operation: it makes the device node appear, and adds no cgroup allow rule, because
+# Kubernetes cannot infer one from a volume.
+#
+# A device plugin is the mechanism that closes exactly that gap. Verified by reading the v0.37.0
+# source (cmd/gpu_plugin/gpu_plugin.go, createDeviceSpecsFromDrmFiles): the Allocate response
+# carries `pluginapi.DeviceSpec{HostPath, ContainerPath, Permissions: "rw"}` per DRM node, and it
+# is that DeviceSpec which makes kubelet populate `linux.devices` AND the matching cgroup allow
+# rule. It is the only NON-PRIVILEGED way to get there. `privileged: true` would also work and is
+# not available: platform/kyverno/policies/restrict-host-namespaces.yaml blocks it under Enforce in
+# app namespaces, and `plex` is labelled app-namespace=true (measured 2026-10-01). Correctly so.
+#
+# STANDALONE DAEMONSET, NOT THE OPERATOR. Upstream ships both. The operator adds a CRD
+# (GpuDevicePlugin), a controller-manager Deployment, cert-manager-backed admission webhooks and a
+# second namespace — i.e. three more things that can be unhealthy — to buy declarative management
+# of a DaemonSet we are declaring in git anyway. For three identical nodes and one consumer that is
+# strictly more blast radius for no gain. The DaemonSet has no CRDs, no controller, no webhook, and
+# no API-server access at all: a device plugin talks to the LOCAL kubelet over a unix socket, which
+# is why there is no ServiceAccount or RBAC here (and therefore no `**/rbac.yaml` sensitive path).
+#
+# LISTING, NOT OPENING — the thing worth being sure about, since opening is precisely what fails
+# today. Verified in v0.37.0 source: the scan path uses only os.ReadDir / os.ReadFile / os.Stat /
+# os.Readlink over /sys/class/drm and /dev/dri. There is no os.Open, no OpenFile, no ioctl and no
+# syscall of any kind against a DRM node anywhere in cmd/gpu_plugin/gpu_plugin.go. Listing and
+# stat() demonstrably work today (that is how the Plex probe found the device before failing to
+# open it), so the plugin needs no cgroup grant of its own and no privilege.
+#   * `--health-management` is left OFF (upstream default). It is the one flag that WOULD need to
+#     open a device: it starts a Level-Zero sidecar (setupLevelZeroService returns early unless the
+#     flag is set). Turning it on would reintroduce the exact EPERM this component exists to fix.
+#   * /dev/dri and /sys/class/drm are mounted readOnly, consistent with list-and-stat only.
+#   * /dev/dri/by-path absence is non-fatal (newDevicePlugin warns and sets bypathFound=false).
+#
+# RESOURCE NAME: `gpu.intel.com/i915`. Not a guess — `scan()` does
+# `devTree.AddDevice(devProps.driver(), ...)`, so the suffix is the KERNEL DRIVER name. These nodes
+# have i915 bound (not xe) on UHD Graphics 630 / PCI 8086:3e98, so the resource is i915. A future
+# kernel moving CoffeeLake to xe would silently rename it to `gpu.intel.com/xe` and the consumer's
+# request would stop matching — worth knowing before that kernel arrives.
+#
+# `--shared-dev-num` LEFT AT THE UPSTREAM DEFAULT OF 1 (so: not set). The flag multiplies each
+# card into N schedulable device IDs (`for i := 0; i < sharedDevNum; i++`), letting N containers
+# share one GPU. Deliberately not raised:
+#   * Plex is the only consumer and wants one device.
+#   * The count is a LIE the scheduler believes. There is no GPU-side partitioning or quota behind
+#     it — N containers get the same renderD128 and contend for the same two media engines
+#     (vcs0/vecs0). Raising it converts "Unschedulable", which is loud and obvious, into
+#     "transcodes are mysteriously slow", which is neither.
+#   * It is a one-line, zero-migration change on the day a second consumer actually exists, and at
+#     that point the right number will be known rather than guessed.
+# No NFD overlay either: all three nodes are identical (established cluster fact), so a nodeSelector
+# on a GPU feature label would gate on something that is true everywhere. If a GPU-less node ever
+# joins, add upstream's nfd overlay THEN rather than relying on the plugin's behaviour there.
+#
+# NO supplementalGroups, anywhere, on purpose. The pms-docker image's own cont-init hook stats each
+# /dev/dri char device and adds the `plex` user to its group — measured live as `Groups: 44 100 992
+# 1000` on the running Plex process, where GID 992 is the host `render` group. That mechanism is
+# image-side and works identically on a plugin-injected device, so adding a supplementalGroup here
+# or on the consumer would duplicate a thing that already works.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: intel-gpu-plugin
+resources:
+  - namespace.yaml
+  - intel-gpu-plugin.yaml
+images:
+  # PINNED, never `latest`. Upstream release v0.37.0 (2026-09-16); verified present on Docker Hub
+  # 2026-10-01, manifest digest sha256:7001200071db10587fc31184eedda4f5cf291efba737adf85a8c80539f7fa5e1
+  # (single amd64 manifest, not an index). Recorded here rather than pinned by digest because this
+  # repo pins upstream platform components by VERSION TAG (platform/kubevirt, external-snapshotter);
+  # digest pinning is reserved for the conformance runner, where it is a security boundary.
+  # `newName` fully qualifies the registry: upstream writes the bare `intel/intel-gpu-plugin`, which
+  # relies on containerd's docker.io default rather than saying so.
+  #
+  # RENOVATE: the inline-marker idiom (customManagers in renovate.json), not the docker datasource —
+  # renovate.json sets `"docker": {"enabled": false}` and `"kubernetes": {"enabled": false}`, so an
+  # image reference in a plain manifest is tracked by NOTHING. The marker must sit on the line
+  # IMMEDIATELY above the version literal for the regex to match, which is why it is down here on
+  # `newTag` and not up in this header.
+  # CAVEAT, stated because it will bite someone: the GitHub release tags carry a `v`
+  # (`v0.37.0`) and the IMAGE tags do not (`0.37.0` — confirmed against the Docker Hub tag list).
+  # Whether Renovate normalises that for this dep is UNVERIFIED here (no Renovate run available).
+  # If it ever proposes `newTag: v0.38.0`, the fix is an `extractVersion` packageRule in
+  # renovate.json, not a hand-edit of this line.
+  - name: intel/intel-gpu-plugin
+    newName: docker.io/intel/intel-gpu-plugin
+    # renovate: datasource=github-releases depName=intel/intel-device-plugins-for-kubernetes
+    newTag: "0.37.0"

platform/intel-gpu-plugin/namespace.yaml

@@ -0,0 +1,34 @@
+---
+# intel-gpu-plugin — namespace for the Intel GPU device plugin DaemonSet.
+#
+# PLATFORM INFRA, NOT AN APPLICATION NAMESPACE, and that distinction is load-bearing here rather
+# than cosmetic. Every Kyverno policy that could object to this DaemonSet is scoped by a
+# `namespaceSelector: matchLabels: homelab.keithjackson.dev/app-namespace: "true"` — verified by
+# reading the policies, not assumed:
+#   * platform/kyverno/policies/restrict-host-namespaces.yaml  (hostNetwork/PID/IPC + privileged)
+#   * platform/kyverno/policies/require-egress-class-label.yaml
+#   * platform/kyverno/policies/require-auth-mode-label.yaml
+#   * platform/kyverno/policies/require-default-deny-baseline.yaml (a *generate* rule, so an
+#     app-namespace also gets a default-deny NetworkPolicy minted into it)
+# Labelling this namespace "false" therefore puts it out of scope for all four. That is the same
+# mechanism restrict-host-namespaces' own header describes: "platform components that do [need host
+# access] live in platform namespaces that do NOT carry the app-namespace label".
+#
+# Measured on prod 2026-10-01: `kyverno` and `vpn-egress` are the two namespaces that carry the
+# label explicitly as "false"; the rest of the platform namespaces leave it unset. Both are out of
+# scope identically — an unset label does not match `"true"`. We set it EXPLICITLY, following
+# vpn-egress, because "someone chose this" and "nobody thought about it" should not look the same
+# in git, and because this component's correctness depends on the answer.
+#
+# NOTE this plugin does NOT actually need any of the things those policies forbid: it sets no
+# hostNetwork/hostPID/hostIPC and is not privileged (see intel-gpu-plugin.yaml). The namespace
+# placement is not a workaround for a policy — there is nothing to work around. It is here because
+# a node-level platform DaemonSet is not an application, and because the app-namespace fabric
+# (default-deny NetworkPolicy, egress-class, auth-mode) describes obligations that are meaningless
+# for a process that talks only to the local kubelet over a unix socket and never uses the network.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: intel-gpu-plugin
+  labels:
+    homelab.keithjackson.dev/app-namespace: "false"

schemas/renderer-contract.md

@@ -23,6 +23,7 @@ platform must render, and cites the requirement each mapping satisfies. Changing
 | `dependencies` | `[]` → reaches **only DNS** (default-deny) | R-NET-01 |
 | `inClusterClients` | `[]` → no direct east-west client; only the Gateway may reach an exposed port | R-NET-01/02 |
 | `auth.mode` | `forward-auth` for any exposed UI | R-IDP-02 |
+| `auth.apiRoutes` | `[]` → the sidecar renders **no** `--api-route`; every unauthenticated request is 302'd to Keycloak | R-IDP-02 |
 | `update.channel` | `stable` | R-UPD-01 |
 | `update.autoRollbackOnFailedHealth` | `true` | R-UPD-03 |
 | `observability.metrics` | `true` | R-OBS-01 |
@@ -260,7 +261,7 @@ platform must render, and cites the requirement each mapping satisfies. Changing
   undeclared), **R-GITOPS-02** (the allowance is authored in the one reviewable object rather than
   surviving as a live-applied cluster object). Auditable via Hubble (R-SEC-03, R-OBS-04).
 
-### `auth` (`mode` / `groups[]`) — identity integration (Keycloak / oauth2-proxy)
+### `auth` (`mode` / `groups[]` / `apiRoutes[]`) — identity integration (Keycloak / oauth2-proxy)
 - `oidc` → register the app as a **Keycloak OIDC client** (declarative realm/client config, GitOps;
   client secret SOPS-encrypted). App does its own login redirect.
 - `forward-auth` → protect the service's `ingressRoutes` at the **Gateway** with **oauth2-proxy →
@@ -271,6 +272,20 @@ platform must render, and cites the requirement each mapping satisfies. Changing
 - `groups[]` → the Keycloak groups permitted access, enforced by the OIDC client mappers /
   oauth2-proxy `allowed_groups`. **Schema requires ≥1 group for `oidc`/`forward-auth`** — access is
   "in an authorized group," not merely "logged in."
+- `apiRoutes[]` (**`forward-auth` only**) → one repeatable **`--api-route=<regex>`** per entry on
+  the per-app oauth2-proxy sidecar, making matching paths answer **401** instead of a **302** to
+  Keycloak. Default `[]` renders **no flag at all**, which is the common case. It exists because
+  oauth2-proxy's built-in AJAX guard fires only on an exact `Accept: application/json`, which
+  these apps' JavaScript does not consistently send: the XHR is 302'd, the browser follows it
+  invisibly, the live SSO session satisfies it silently, and the call resolves 200 carrying the
+  app's **HTML** where the JavaScript expected JSON — and a POST following a 302 is re-issued as
+  a GET with its **body dropped**. It is **per-service and must never become a renderer
+  constant**: the path shape belongs to the app (radarr `/signalr/`, jackett `/api/`, pihole
+  none), and a wrong constant does not merely fail to help — a path a **browser navigates to**,
+  answered 401, shows a logged-out operator a bare error page and never offers a sign-in. Each
+  entry must be **anchored at `^/`** and continue with literal path characters; `^/`, `^/.*`,
+  `.*`, an unanchored `/api/` and any alternation are **rejected** by the schema and by the
+  renderer (alternation is refused rather than supported because the flag is repeatable).
 - Keycloak, oauth2-proxy, and app→Keycloak / proxy→Keycloak / Keycloak→DB flows are ordinary
   workloads under default-deny with explicit allows (ties back to `dependencies`).
 - **Requirements:** **R-IDP-02** (protect OIDC-capable and bare UIs), **R-IDP-06** (group-based
@@ -329,6 +344,12 @@ platform must render, and cites the requirement each mapping satisfies. Changing
 ## Cross-field invariants the renderer / L0-L1 tests rely on
 1. **kind ↔ source:** container⇒`image`, vm⇒`vmTemplate` (schema-enforced).
 2. **auth ↔ groups:** `oidc`/`forward-auth` ⇒ non-empty `groups` (schema-enforced; R-IDP-06).
+2a. **auth ↔ apiRoutes:** a non-empty `auth.apiRoutes` ⇒ `auth.mode: forward-auth`
+   (schema-enforced). It renders onto the per-app oauth2-proxy sidecar, and no sidecar exists for
+   `oidc`/`native`/`none`, so declaring it elsewhere would be a **silent no-op** — the operator
+   believes the app's XHRs now answer 401 and nothing changed. Every entry must be anchored at
+   `^/` (schema-enforced **and** enforced in `catalog/render.py`, so a breadth mistake is caught by
+   `render-golden` even on a run where the schema stage did not execute).
 3. **default-deny is unconditional:** every namespace gets the deny baseline regardless of
    `dependencies`; `dependencies` only *adds* allows (R-NET-01/02). The same holds for
    `inClusterClients`: it adds one namespace+port ingress allow and never relaxes the baseline.

schemas/servicedefinition.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://home.keithjackson.dev/schemas/servicedefinition.schema.json",
   "title": "ServiceDefinition",
-  "description": "Operator-facing onboarding contract for the home k3s + Longhorn platform. One ServiceDefinition per file under catalog/. Captures INTENT; the platform compiles it into concrete resources (see schemas/renderer-contract.md). Canonical source of truth: spec docs/13-service-catalog.md. Serves R-GITOPS-02; ties into R-NET-*, R-STATE-*, R-TLS-*, R-DNS-*, R-OBS-*, R-UPD-*, R-IDP-*. Schema version: 1.8.0 (adds optional `hardware` - a host HARDWARE CAPABILITY declaration for the container kind, currently one member: `hardware.gpu: intel-quicksync`, meaning the workload needs the host iGPU render device for hardware video transcode. It is an ENUM OF INTENT, not a device path: the renderer satisfies it today with just two things -- a /dev/dri hostPath volume (`DirectoryOrCreate`) and a read-write /dev/dri volumeMount on the app container -- and a later move to the Intel GPU device plugin is then a render.py change with no catalog edit. It sets NO podSecurityContext.supplementalGroups: measured in-container on prod 2026-09-30, the pms-docker cont-init hook adds the app user to the device's group inside the container and `s6-setuidgid` then REPLACES the process group list from /etc/group, discarding anything Kubernetes supplied, so such an entry would be inert and misleading. Renders NOTHING when absent, so every existing app stays byte-identical. Emits no privileged securityContext (Kyverno restrict-host-namespaces would reject it and it is not needed), no nodeSelector (node placement is a separate concern with its own justification) and no resource requests). 1.7.0 (no field changes; a MAPPING change to `exposure`, which had never had an effect on DNS. `exposure: internal` now renders ExternalDNS's own controller annotation onto every HTTPRoute it emits, set to a value other than `dns-controller`, so external-dns (v0.21.0, source/gateway.go -> annotations.IsControllerMismatch) skips the route before resolving any hostname and the service is INCAPABLE of producing a public record. Both docs/09 R-DNS-03 and schemas/renderer-contract.md already said `internal` renders no public DNS record; nothing enforced it, and six internal services -- jackett, pihole, qbittorrent, radarr, semaphore, sonarr -- were publishing `<name>.home.keithjackson.dev` into the PUBLIC Cloudflare zone answering with the RFC1918 Gateway VIP, which published the internal subnet and a full service inventory and made each name a DNS-rebind primitive. Enforced on every gate run by conformance/tests/l0-static/internal-services-publish-no-public-dns). 1.6.0 (splits `observability.metrics` from WHERE metrics live: adds optional `metricsEndpoint` (port/name/path/interval) and optional `livenessWorkload` (kind/name). `metrics: true` previously rendered a ServiceMonitor hardcoded to a port named `metrics` that no rendered Service ever defined, so all twelve app monitors discovered ZERO targets and every `up{job=...}` SLI was structurally inert on prod; a monitor is now rendered only from a declared `metricsEndpoint`, which also renders the Service port and the monitoring-namespace ingress allow, and the `up` SLI is expressed against kube-state-metrics -- a signal that exists for every workload without a per-app exporter. `livenessWorkload` names the object whose readiness IS the service, for the case where the running workload is not the one this SD renders). 1.5.0 (adds optional `inClusterClients` — additional in-cluster clients, named by NAMESPACE, admitted to a declared port of this service DIRECTLY, bypassing the shared Gateway. `ingressRoutes` admits only the Gateway proxy identity and `dependencies` only links catalog services, so a PLATFORM controller dialling a Service ClusterIP had no authorable form at all; that gap is what deadlocked prod's GitOps when its GitRepository moved to the in-cluster Gitea Service. Renders one least-privilege ingress CiliumNetworkPolicy per entry — the named namespace and the declared port, nothing wider). 1.4.0 (makes the `bulk` tier REAL: a bulk storage entry now carries `export` (the absolute NFS export path on the ${BULK_NFS_SERVER} host) and renders a STATIC, pre-bound NFS PersistentVolume + PVC over data that already exists outside the cluster, plus optional `subPath` and `readOnly` on any entry. Resolves the OQ-2 bulk-backing stub for STATIC pre-existing datasets; dynamic bulk provisioning remains unimplemented and unneeded). 1.3.0 added optional pod-level podSecurityContext for the container kind — k8s PodSecurityContext emitted verbatim onto the pod spec; its fsGroup unblocks non-root images e.g. semaphore/UID-1001 writing a mounted Longhorn PVC). 1.2.0 added optional per-container env/envFrom/lifecycle for the container kind — k8s EnvVar/EnvFromSource/Lifecycle shapes emitted verbatim onto the app container; unblocks headless-install/DB-backed apps e.g. gitea/nextcloud/semaphore/unifi/minecraft. 1.1.0 added the shape invariant exposure:public => auth.mode!=none (docs/13 v1.1 / docs/15 Line truncated
+  "description": "Operator-facing onboarding contract for the home k3s + Longhorn platform. One ServiceDefinition per file under catalog/. Captures INTENT; the platform compiles it into concrete resources (see schemas/renderer-contract.md). Canonical source of truth: spec docs/13-service-catalog.md. Serves R-GITOPS-02; ties into R-NET-*, R-STATE-*, R-TLS-*, R-DNS-*, R-OBS-*, R-UPD-*, R-IDP-*. Schema version: 1.9.0 (adds optional `auth.apiRoutes` -- a per-service list of anchored path regexes the forward-auth oauth2-proxy sidecar answers with 401 instead of a 302 to Keycloak, rendered as one repeatable `--api-route` per entry. The `auth` block stays `additionalProperties: false`; this is one named, documented key, not an opened door. Without it there was NO per-app override hook at all, so the only way to answer an app's XHRs with 401 was a renderer-wide constant -- and the path shape is a property of the app: jackett's is `/api/` (33 x 302 vs 2 x 401 measured 2026-09-30, 4 of 6 POSTs answered by the proxy and never reaching the app), radarr's is `/signalr/` (232 x 302 measured 2026-10-01, every one a POST from a left-open browser tab that is never re-prompted), and pihole serves no `/api/` at all. Each entry must be anchored at `^/` and continue with literal path characters, because a too-broad regex turns a plain page load into a 401 and the service looks permanently broken to a logged-out user. Enforced on every gate run by ci/l0.sh's schema stage over catalog/*.yaml, by catalog/render.py refusing to render an unanchored entry, and by conformance/tests/l0-static/oauth2-proxy-api-routes-per-app)). 1.8.0 (adds optional `hardware` - a host HARDWARE CAPABILITY declaration for the container kind, currently one member: `hardware.gpu: intel-quicksync`, meaning the workload needs the host iGPU render device for hardware video transcode. It is an ENUM OF INTENT, not a device path: the renderer satisfies it today with just two things -- a /dev/dri hostPath volume (`DirectoryOrCreate`) and a read-write /dev/dri volumeMount on the app container -- and a later move to the Intel GPU device plugin is then a render.py change with no catalog edit. It sets NO podSecurityContext.supplementalGroups: measured in-container on prod 2026-09-30, the pms-docker cont-init hook adds the app user to the device's group inside the container and `s6-setuidgid` then REPLACES the process group list from /etc/group, discarding anything Kubernetes supplied, so such an entry would be inert and misleading. Renders NOTHING when absent, so every existing app stays byte-identical. Emits no privileged securityContext (Kyverno restrict-host-namespaces would reject it and it is not needed), no nodeSelector (node placement is a separate concern with its own justification) and no resource requests). 1.7.0 (no field changes; a MAPPING change to `exposure`, which had never had an effect on DNS. `exposure: internal` now renders ExternalDNS's own controller annotation onto every HTTPRoute it emits, set to a value other than `dns-controller`, so external-dns (v0.21.0, source/gateway.go -> annotations.IsControllerMismatch) skips the route before resolving any hostname and the service is INCAPABLE of producing a public record. Both docs/09 R-DNS-03 and schemas/renderer-contract.md already said `internal` renders no public DNS record; nothing enforced it, and six internal services -- jackett, pihole, qbittorrent, radarr, semaphore, sonarr -- were publishing `<name>.home.keithjackson.dev` into the PUBLIC Cloudflare zone answering with the RFC1918 Gateway VIP, which published the internal subnet and a full service inventory and made each name a DNS-rebind primitive. Enforced on every gate run by conformance/tests/l0-static/internal-services-publish-no-public-dns). 1.6.0 (splits `observability.metrics` from WHERE metrics live: adds optional `metricsEndpoint` (port/name/path/interval) and optional `livenessWorkload` (kind/name). `metrics: true` previously rendered a ServiceMonitor hardcoded to a port named `metrics` that no rendered Service ever defined, so all twelve app monitors discovered ZERO targets and every `up{job=...}` SLI was structurally inert on prod; a monitor is now rendered only from a declared `metricsEndpoint`, which also renders the Service port and the monitoring-namespace ingress allow, and the `up` SLI is expressed against kube-state-metrics -- a signal that exists for every workload without a per-app exporter. `livenessWorkload` names the object whose readiness IS the service, for the case where the running workload is not the one this SD renders). 1.5.0 (adds optional `inClusterClients` — additional in-cluster clients, named by NAMESPACE, admitted to a declared port of this service DIRECTLY, bypassing the shared Gateway. `ingressRoutes` admits only the Gateway proxy identity and `dependencies` only links catalog services, so a PLATFORM controller dialling a Service ClusterIP had no authorable form at all; that gap is what deadlocked proLine truncated
   "type": "object",
   "additionalProperties": false,
   "required": ["name", "source"],
@@ -324,6 +324,16 @@
           "items": { "type": "string", "minLength": 1 },
           "uniqueItems": true,
           "default": []
+        },
+        "apiRoutes": {
+          "type": "array",
+          "description": "forward-auth ONLY: path regexes this app serves as a MACHINE API, which the oauth2-proxy sidecar must answer with 401 instead of a 302 to Keycloak (one --api-route per entry; the flag is repeatable and singular -- --api-routes does not exist in v7.8.1 and the proxy refuses to start with it). WHY THIS IS PER-APP AND NOT A RENDERER CONSTANT: oauth2-proxy's built-in AJAX guard fires only on an EXACT `Accept: application/json`, which these apps' JavaScript does not consistently send, so an unauthenticated XHR gets a 302 that the browser follows invisibly, the live Keycloak SSO session satisfies silently, and the call resolves 200 carrying the app's HTML where the JavaScript expected JSON -- no prompt, no error, and on a write it is worse, because a browser following a 302 re-issues a POST as a GET and DROPS THE BODY. Measured on jackett 2026-09-30: 33 x 302 against 2 x 401 on /api/ paths, with 4 of 6 POSTs answered by the proxy and never reaching the app (access-log upstream field `-`). Measured on radarr 2026-10-01, 23h after the cookie fix deployed: 232 x 302, ALL of them POST /signalr/messages/negotiate from the operator's own browser -- a left-open tab whose cookie the rename orphaned, polling forever, silently redirected every time and NEVER re-prompting. But the path shape is a property of the APP, not of the pattern: radarr's broken path is /signalr/ and jackett's is /api/, and pihole serves no /api/ at all, so a renderer-wide constant would apply one app's path shape to five. Declare only paths this app actually serves as JSON/RPC and that a browser never NAVIGATES to. BREADTH IS THE DANGER: too broad and a plain page load answers 401 instead of signing the operator in, i.e. the service looks permanently broken to a logged-out user and no sign-in is ever offered. The item pattern therefore REQUIRES each entry to be anchored at `^/` and to continue with literal path characters, which rejects `^/`, `^/.*`, `.*` and any unanchored or alternated regex; alternation is refused rather than supported because the flag is repeatable, so one regex per route costs nothing and keeps each entry readable. N/A for oidc/native/none (no sidecar is rendered).",
+          "items": {
+            "type": "string",
+            "pattern": "^\\^/[A-Za-z0-9._~/-]+(\\.\\*|\\$)?$"
+          },
+          "uniqueItems": true,
+          "default": []
         }
       }
     },
@@ -471,6 +481,26 @@
         }
       }
     },
+    {
+      "$comment": "auth.apiRoutes only has a consumer under forward-auth: it renders --api-route onto the per-app oauth2-proxy sidecar, and no sidecar is rendered for oidc/native/none. Declaring it elsewhere would be a SILENT NO-OP -- the operator believes the app's XHRs now answer 401 and nothing changed -- so it is rejected at the schema instead (R-IDP-02).",
+      "if": {
+        "required": ["auth"],
+        "properties": {
+          "auth": {
+            "required": ["apiRoutes"],
+            "properties": { "apiRoutes": { "minItems": 1 } }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "auth": {
+            "required": ["mode"],
+            "properties": { "mode": { "const": "forward-auth" } }
+          }
+        }
+      }
+    },
     {
       "$comment": "public exposure must not be unauthenticated: an explicit auth.mode 'none' is disallowed on public services (docs/13 v1.1, docs/15, R-IDP-02). Absent auth defaults to forward-auth at render time, so it is permitted here.",
       "if": {