feat: restore worker recycle limit via Caddyfile max_requests (default 500)

The removed runtime/frankenphp-symfony package force-restarted the
worker after FRANKENPHP_LOOP_MAX requests (default 500) - memory-leak
paranoia the built-in 8.1 runner intentionally doesn't reimplement.

Restore the behavior natively so the upgrade is a no-op operationally:
- Caddyfile: global frankenphp block with max_requests {$MAX_REQUESTS}
  - per-thread graceful restarts, other threads keep serving
- Dockerfile: ARG/ENV MAX_REQUESTS=500 bakes the same default the old
  package had, overridable at docker build or runtime (-e, 0 disables)
- Stock FRANKENPHP_CONFIG env var remains the full-config escape hatch
- Documented in readme env table, docs/example.env, CHANGELOG, and the
  upgrade plan (phase-4 staging note now checks thread recycling)

docs/example.env

@@ -24,6 +24,14 @@
 # once blocked, do we respond with "I'm a teapot", false to use "Too many requests"
 #TEAPOT=true                # default enabled, boolean
 
+# --- server / worker options ---
+
+# (container/deployment only) restart each FrankenPHP worker thread after
+# this many requests, containing memory growth across long uptime;
+# matching the default from the old runtime/frankenphp-symfony package.
+# 0 disables restarts. consumed by the Caddyfile, not the PHP app.
+#MAX_REQUESTS=500           # default 500
+
 # --- remote-user header ---
 # Controls the value sent in the Remote-User header on successful auth.
 # session: the session id (default, backward-compatible)

docs/symfony-8.1-upgrade-plan.md

@@ -1,12 +1,29 @@
 # Upgrade Plan: Symfony 7.4 → 8.1
 
-**Status:** Planning
+**Status:** ✅ Implemented on branch `feat/symfony-8.1-upgrade-plan`
+(Phases 0–3 & state audit complete; Phases 4–5 = staging + release)
 **Target:** Symfony `8.1.*` (all symfony components)
-**Current:** Symfony `7.4.*`
+**Was:** Symfony `7.4.*` → **resolved 8.1.2–8.1.6**
 **Prepared:** 2026-09-07
 
 ---
 
+## Implementation results
+
+| Phase | Result |
+|-------|--------|
+| 0 Deprecation sweep | ✅ Clean — suite runs with `failOnDeprecation=true`, zero hits on 7.4; the 8.x jump needed **no app code changes**. |
+| 1 Composer bump | ✅ `runtime/frankenphp-symfony` removed, `extra.runtime` deleted, all `symfony/*` at `8.1.*` (framework-bundle 8.1.6, twig-bundle 8.1.2); ride-alongs PHPUnit 13.3.2, Twig 3.28, otphp 11.5. Boots on **v8.1.6**. |
+| 2 Config refresh | ✅ `config/reference.php` is gitignored, auto-regenerated by Flex. Prod `cache:clear`+`cache:warmup`, `lint:container`/`lint:yaml`/`lint:twig` all pass. |
+| 3 Tests | ✅ **295 tests / 612 assertions green** on 8.1; php-cs-fixer 0 fixable files. |
+| State audit | ✅ All `src/` services are `final readonly` with ctor-injected deps — no mutable state, kernel reuse under `FrankenPhpWorkerRunner` is safe. |
+| Loop-max parity | ✅ `Caddyfile` sets `max_requests {$MAX_REQUESTS}`; default **500** baked into the image via Docker build arg (matches old package default), runtime-overridable. See §2 note. |
+
+Phases 4–5 (staging smoke + release) are pending — everything else in
+this document describes what was planned **and is now done**.
+
+---
+
 ## 1. Why we can leapfrog 8.0
 
 Symfony 7.4 and 8.0 were released simultaneously (Nov 2025) and are
@@ -191,7 +208,7 @@ twig-bundle, uid, yaml) and tick each item against this codebase.
 | 1 | **composer bump**: branch `feat/symfony-8.1`; edit composer.json per §3–§4; `composer remove runtime/frankenphp-symfony`; `composer update`; re-sync recipes. | Installs clean on PHP 8.5; `bin/console about` shows 8.1.x. |
 | 2 | **Config refresh**: regenerate `config/reference.php`; review framework/twig/rate-limiter defaults; commit config changes. | `cache:clear` + warmup pass in dev & prod envs. |
 | 3 | **Tests**: full phpunit suite + php-cs-fixer; fix failures (expected: minor — event/type related). | Suite green in CI. |
-| 4 | **Staging smoke**: build image, run under FrankenPHP worker mode; verify TOTP login flow, backup codes, rate limiting (burst + teapot mode), public paths, central-auth subdomain flow; watch memory across >500 requests (old loop_max default no longer applies — see §2 note). | No state leaks across worker requests; healthcheck passes. |
+| 4 | **Staging smoke**: build image, run under FrankenPHP worker mode; verify TOTP login flow, backup codes, rate limiting (burst + teapot mode), public paths, central-auth subdomain flow; watch memory across >500 requests to confirm threads recycle via the Caddyfile `max_requests` setting (see §2 note). | No state leaks across worker requests; worker threads recycle at the configured request count; healthcheck passes. |
 | 5 | **Docs + release**: update readme/DESIGN_CONSIDERATIONS ("symfony 8.1, built-in FrankenPHP runtime"); tag a minor release per CHANGELOG conventions. | Release published; image rebuilt & pushed. |
 
 **Rollback:** the upgrade is a single composer.lock + config diff.