feat: add detached mode capabilities

docs/content/docs/configuration.mdx

@@ -331,6 +331,7 @@ headroom proxy --learn --min-evidence 3
 | `HEADROOM_BUDGET` | Daily budget limit in USD | -- |
 | `HEADROOM_TELEMETRY` | Set to `on` for **local-only** usage stats (powers your own `/stats` and dashboard; nothing is sent externally) | `off` |
 | `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` |
+| `HEADROOM_DETACHED_PROFILE` | Detached-mode capability policy: `strict`, `lenient`, or `silent` | `lenient` |
 | `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- |
 | `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` |
 | `HEADROOM_API_KEY` | Optional API key for authenticated Headroom endpoints (TypeScript SDK) | -- |
@@ -462,6 +463,11 @@ page for the full bucket table, plugin-author guidance, and the Docker
 naming overlap note (`HEADROOM_WORKSPACE` is *not* the same as
 `HEADROOM_WORKSPACE_DIR`).
 
+For deployments where the workspace root is intentionally unavailable or
+read-only, see [Detached Mode](/docs/detached-mode). It exposes the exact
+capability matrix through `/capabilities`, `/health`, `/stats`, and
+`headroom_feature_enabled` Prometheus gauges.
+
 ## Custom Model Configuration
 
 Configure context limits and pricing for new or custom models:

docs/content/docs/detached-mode.mdx

@@ -0,0 +1,57 @@
+---
+title: Detached Mode
+description: Run Headroom in containers, CI, serverless, or read-only deployments with explicit capability degradation.
+---
+
+Detached mode is Headroom's contract for deployments where local writable state is absent or intentionally disabled.
+
+Use it for stateless containers, read-only filesystems, ephemeral CI runners, serverless processes, and load-balanced fleets where local process state should not be treated as durable.
+
+## Enable detached mode
+
+```bash
+HEADROOM_STATELESS=true headroom proxy
+```
+
+or:
+
+```bash
+headroom proxy --stateless
+```
+
+`--stateless` disables avoidable filesystem writes such as proxy file logging, local TOIN persistence, memory, learning, and telemetry beacon lock files. Request handling and compression continue to run.
+
+## Profiles
+
+Set `HEADROOM_DETACHED_PROFILE` or pass `--detached-profile`:
+
+| Profile | Behavior |
+|---|---|
+| `lenient` | Default. Start the proxy and log the capability matrix when detached. |
+| `strict` | Refuse startup when an explicitly enabled required local-state feature would degrade, such as `--memory` without available local state or a remote backend. |
+| `silent` | Start the proxy without startup degradation logs. `/capabilities`, `/stats`, `/health`, and `/metrics` still expose the matrix. |
+
+```bash
+HEADROOM_STATELESS=true \
+HEADROOM_DETACHED_PROFILE=strict \
+headroom proxy
+```
+
+## Capability endpoint
+
+```bash
+curl http://localhost:8787/capabilities
+```
+
+The response includes `detached`, `profile`, local-state availability, every feature's local-state dependency, current state, degradation mode, and strict-mode violations.
+
+## Metrics
+
+The Prometheus endpoint exposes one gauge per feature:
+
+```text
+headroom_feature_enabled{feature="compression",state="full",degradation="full",dependency="none"} 1
+headroom_feature_enabled{feature="session_aggregation",state="disabled",degradation="disabled",dependency="required"} 0
+```
+
+Use this to alert on degraded or disabled capabilities in managed deployments.

docs/content/docs/meta.json

@@ -24,6 +24,7 @@
     "failure-learning",
     "---Proxy Server---",
     "proxy",
+    "detached-mode",
     "local-llm-prefill",
     "---Integrations---",
     "vercel-ai-sdk",

docs/content/docs/metrics.mdx

@@ -86,8 +86,13 @@ headroom_latency_seconds_bucket{le="0.1"} 1150
 
 # HELP headroom_cache_hits_total Cache hit counter
 headroom_cache_hits_total 456
+
+# HELP headroom_feature_enabled Feature availability after detached-mode capability resolution
+headroom_feature_enabled{feature="compression",state="full",degradation="full",dependency="none"} 1
 ```
 
+`headroom_feature_enabled` mirrors the `/capabilities` payload. Use it to alert when an expected feature is degraded or disabled in detached/stateless deployments.
+
 ### OpenTelemetry (OTLP) Export
 
 The proxy can also push its counters to any OTLP/HTTP endpoint. Install the extra and set four variables:

docs/content/docs/proxy.mdx

@@ -24,6 +24,12 @@ headroom proxy \
 
 Telemetry is **local-only and off by default**. `HEADROOM_TELEMETRY=on` (or `--telemetry`) turns on in-process usage stats that power your own `/stats`, `/metrics`, and dashboard — **nothing is sent to Headroom Labs**. (The anonymous aggregate beacon that older versions shipped has been removed from the code.)
 
+For read-only, container, CI, serverless, or load-balanced deployments, use [Detached Mode](/docs/detached-mode) to make local-state degradation explicit:
+
+```bash
+headroom proxy --stateless --detached-profile lenient
+```
+
 ## CLI options
 
 ### Core
@@ -53,6 +59,7 @@ Telemetry is **local-only and off by default**. `HEADROOM_TELEMETRY=on` (or `--t
 | `--telemetry` | `false` | Enable local, in-process usage stats (for your own `/stats` and dashboard; nothing leaves the machine) |
 | `--no-telemetry` | `false` | Force local telemetry off (already the default) |
 | `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |
+| `--detached-profile` | `lenient` | Capability policy for detached/stateless deployments: `strict`, `lenient`, or `silent` |
 
 Use `--http-proxy` or `HEADROOM_HTTP_PROXY` when only provider API traffic should go through a proxy:
 
@@ -340,6 +347,14 @@ Live session statistics plus durable `persistent_savings` totals. Stored at `~/.
 curl http://localhost:8787/stats
 ```
 
+### `GET /capabilities`
+
+Resolved detached-mode capability matrix for operators and deployment automation.
+
+```bash
+curl http://localhost:8787/capabilities
+```
+
 ### `GET /stats-history`
 
 Durable history with hourly, daily, weekly, and monthly rollups. Powers the `/dashboard` view.

e2e/wrap/run.py

@@ -725,7 +725,10 @@ def verify_cursor_wrap(base_env: dict[str, str], project_dir: Path) -> None:
         errors="replace",
     )
     try:
-        output = wait_for_output(proc, "Press Ctrl+C to stop the proxy.", timeout=30)
+        # _start_proxy waits up to 45s before surfacing proxy log context. Keep
+        # this parent-process wait longer so slow container startup is not
+        # mistaken for a Cursor wrap failure.
+        output = wait_for_output(proc, "Press Ctrl+C to stop the proxy.", timeout=75)
         # Cursor setup lines embed the /p/<name> per-project prefix.
         cursor_prefix = f"/p/{quote(project_dir.name, safe='')}"
         assert_true(

headroom/cli/proxy.py

@@ -977,6 +977,17 @@ def dashboard(port: int, no_open: bool) -> None:
     "For containerized / read-only / load-balanced deployments. "
     "(env: HEADROOM_STATELESS=true)",
 )
+@click.option(
+    "--detached-profile",
+    type=click.Choice(["strict", "lenient", "silent"], case_sensitive=False),
+    default=None,
+    envvar="HEADROOM_DETACHED_PROFILE",
+    help=(
+        "Detached-mode capability policy. strict refuses degraded explicitly "
+        "enabled local-state features; lenient logs degradations; silent only "
+        "exposes them through API/metrics. Env: HEADROOM_DETACHED_PROFILE."
+    ),
+)
 @click.option(
     "--embedding-server/--no-embedding-server",
     default=False,
@@ -1096,6 +1107,7 @@ def proxy(
     telemetry: bool,
     no_telemetry: bool,
     stateless: bool,
+    detached_profile: str | None,
     embedding_server: bool,
     embedding_server_socket: str | None,
 ) -> None:
@@ -1449,6 +1461,10 @@ def proxy(
         license_key=license_key,
         # Stateless mode: disable all filesystem writes
         stateless=is_stateless,
+        detached_profile=cast(
+            Literal["strict", "lenient", "silent"],
+            (detached_profile or os.environ.get("HEADROOM_DETACHED_PROFILE") or "lenient").lower(),
+        ),
         # Unit 4: bounded pre-upstream concurrency on the Anthropic HTTP
         # path. ``None`` -> HeadroomProxy computes ``max(2, min(8,
         # os.cpu_count() or 4))``; ``<= 0`` -> disabled (unbounded).
@@ -1648,6 +1664,7 @@ def proxy(
   GET  /livez      Process liveness
   GET  /readyz     Traffic readiness
   GET  /health     Aggregate health
+  GET  /capabilities Detached-mode capability matrix
   GET  /stats      Detailed statistics
   GET  /stats-history Durable compression history + display session
   GET  /metrics    Prometheus metrics