Merge remote-tracking branch 'origin/main' into rust-rewrite

.git-blame-ignore-revs

@@ -0,0 +1,10 @@
+# Revisions listed here are skipped by `git blame --ignore-revs-file`
+# and by GitHub's blame UI. Use for mechanical, repo-wide changes that
+# touch every line of a file but don't change semantics (formatter runs,
+# line-ending normalization, bulk renames applied by codemod, etc.).
+#
+# Configure your local git to auto-pick this up:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+# chore: renormalize line endings to LF
+efd2ac1ca4d88d8f5990259c98b673c603902896

.gitattributes

@@ -1 +1,2 @@
+*.py text eol=lf
 *.sh text eol=lf

.github/actions/headroom-e2e-setup/action.yml

@@ -0,0 +1,68 @@
+name: Headroom e2e setup
+description: >-
+  Checkout-agnostic setup shared by native e2e workflows (init, install, wrap).
+  Installs Python, installs headroom in editable mode, and (optionally) drops
+  a noop shim onto PATH so ``headroom init -g <target>`` can detect a tool
+  that isn't actually installed on the runner.
+inputs:
+  python-version:
+    description: Python version to install
+    required: false
+    default: "3.11"
+  shim-target:
+    description: >-
+      Name of the shim to drop on PATH (e.g. ``claude``, ``codex``). Leave
+      empty to skip shim creation.
+    required: false
+    default: ""
+outputs:
+  shim-dir:
+    description: Absolute path to the directory containing the dropped shim
+    value: ${{ steps.shim.outputs.shim-dir }}
+runs:
+  using: composite
+  steps:
+    - name: Set up Python ${{ inputs.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install headroom (editable, with proxy extras)
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        # ``headroom/cli/__init__.py`` eagerly imports ``proxy.server`` (via
+        # ``cli/proxy.py``), which requires ``fastapi`` even for ``init``.
+        # Install with the ``[proxy]`` extras to match the Docker e2e image.
+        pip install -e ".[proxy]"
+
+    - name: Drop shim (POSIX)
+      if: ${{ inputs.shim-target != '' && runner.os != 'Windows' }}
+      id: shim-posix
+      shell: bash
+      run: |
+        shim_dir="${RUNNER_TEMP}/headroom-e2e-shims"
+        bash e2e/_lib/make_shim.sh "${{ inputs.shim-target }}" "$shim_dir"
+        echo "$shim_dir" >> "$GITHUB_PATH"
+        echo "shim-dir=$shim_dir" >> "$GITHUB_OUTPUT"
+
+    - name: Drop shim (Windows)
+      if: ${{ inputs.shim-target != '' && runner.os == 'Windows' }}
+      id: shim-windows
+      shell: pwsh
+      run: |
+        $shimDir = Join-Path $env:RUNNER_TEMP "headroom-e2e-shims"
+        & pwsh -File e2e/_lib/make_shim.ps1 -Name "${{ inputs.shim-target }}" -Dir $shimDir
+        Add-Content -Path $env:GITHUB_PATH -Value $shimDir
+        "shim-dir=$shimDir" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
+
+    - name: Export shim dir to job output
+      if: ${{ inputs.shim-target != '' }}
+      id: shim
+      shell: bash
+      run: |
+        if [ "${{ runner.os }}" = "Windows" ]; then
+          echo "shim-dir=${{ steps.shim-windows.outputs.shim-dir }}" >> "$GITHUB_OUTPUT"
+        else
+          echo "shim-dir=${{ steps.shim-posix.outputs.shim-dir }}" >> "$GITHUB_OUTPUT"
+        fi

.github/workflows/init-native-e2e.yml

@@ -0,0 +1,132 @@
+name: Init Native E2E
+
+# Cross-platform (linux / macos / windows) smoke tests for the per-subcommand
+# ``headroom init -g <target>`` flows. Each matrix cell drops a noop shim for
+# the target agent onto PATH and asserts ``headroom init -g <target>``
+# succeeds, writes the expected settings file, and (for claude/codex) places
+# hooks in the right place.
+#
+# Deliberately scoped to pull_request + push-to-main + workflow_dispatch to
+# avoid bloating CI minutes on every push to every feature branch. The Docker
+# init-e2e.yml still runs on every PR and provides the deeper functional
+# coverage; this workflow exists to catch platform-specific bugs (Windows
+# path separators, macos keychain prompts, PowerShell-vs-bash hook matchers)
+# that the single-platform Docker suite can miss.
+#
+# Extending to other commands (``headroom install``, ``headroom wrap``) is
+# expected to be a near-copy of this file. The shared composite action at
+# ``.github/actions/headroom-e2e-setup`` absorbs the Python + shim setup so
+# each per-command workflow only supplies its matrix and assertion steps.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "headroom/cli/init.py"
+      - "headroom/install/**"
+      - "e2e/_lib/**"
+      - "e2e/init/**"
+      - ".github/actions/headroom-e2e-setup/**"
+      - ".github/workflows/init-native-e2e.yml"
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  init-native:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        target: [claude, codex, copilot, openclaw]
+        exclude:
+          # openclaw delegates to ``headroom wrap openclaw`` which needs a
+          # running OpenClaw CLI; it can't be shimmed cheaply, so it's
+          # covered by the bundled Docker e2e instead.
+          - target: openclaw
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup (shim=${{ matrix.target }})
+        uses: ./.github/actions/headroom-e2e-setup
+        with:
+          python-version: "3.11"
+          shim-target: ${{ matrix.target }}
+
+      - name: Verify shim is on PATH (POSIX)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          which "${{ matrix.target }}"
+
+      - name: Verify shim is on PATH (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          # On Windows the shim is ``<target>.cmd``; Get-Command resolves via
+          # PATHEXT (same as Python's ``shutil.which`` used by headroom init).
+          # Git Bash's ``which`` cannot find ``.cmd`` shims, so we use pwsh.
+          $cmd = Get-Command "${{ matrix.target }}" -ErrorAction Stop
+          Write-Output $cmd.Source
+
+      - name: Run headroom init -g ${{ matrix.target }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          headroom init -g "${{ matrix.target }}"
+
+      - name: Assert settings file (POSIX)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          set -euo pipefail
+          case "${{ matrix.target }}" in
+            claude)
+              test -f "$HOME/.claude/settings.json"
+              grep -q "ANTHROPIC_BASE_URL" "$HOME/.claude/settings.json"
+              ;;
+            codex)
+              test -f "$HOME/.codex/config.toml"
+              test -f "$HOME/.codex/hooks.json"
+              grep -q "headroom" "$HOME/.codex/config.toml"
+              ;;
+            copilot)
+              test -f "$HOME/.copilot/config.json"
+              grep -q "SessionStart" "$HOME/.copilot/config.json"
+              ;;
+          esac
+
+      - name: Assert settings file (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $home_ = $env:USERPROFILE
+          switch ("${{ matrix.target }}") {
+            "claude" {
+              $p = Join-Path $home_ ".claude\settings.json"
+              if (-not (Test-Path $p)) { throw "Missing $p" }
+              if (-not ((Get-Content $p -Raw) -match "ANTHROPIC_BASE_URL")) {
+                throw "settings.json missing ANTHROPIC_BASE_URL"
+              }
+            }
+            "codex" {
+              $c = Join-Path $home_ ".codex\config.toml"
+              $h = Join-Path $home_ ".codex\hooks.json"
+              if (-not (Test-Path $c)) { throw "Missing $c" }
+              if (-not (Test-Path $h)) { throw "Missing $h" }
+              if (-not ((Get-Content $c -Raw) -match "headroom")) {
+                throw "config.toml missing headroom provider"
+              }
+            }
+            "copilot" {
+              $p = Join-Path $home_ ".copilot\config.json"
+              if (-not (Test-Path $p)) { throw "Missing $p" }
+              if (-not ((Get-Content $p -Raw) -match "SessionStart")) {
+                throw "copilot config missing SessionStart hooks"
+              }
+            }
+          }

CHANGELOG.md

@@ -8,14 +8,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
+- **`Learned: error recovery` section in MEMORY.md no longer bloats with
+  stale or contradictory entries.** The dedup key for error-recovery
+  patterns was the literal rendered bullet text, so near-duplicate
+  recoveries (same intent, different `| tail -N` count, same error path
+  guessed against different successors) each created a new row. There was
+  also no TTL or re-validation, so wrong-today entries lingered. Fixed by:
+  (1) normalizing the hash on recovery intent — Read recoveries key on
+  `(basename(error_path), basename(success_path))`; Bash recoveries strip
+  volatile suffixes and hash only the primary command before the first
+  `|`/`&&`; (2) stamping `first_seen_at` / `last_seen_at` on every pattern
+  and bumping them in `_bump_persisted_evidence` via `json_set`; (3)
+  refining at render time — drop rows not re-observed in 21 days,
+  re-validate Read success paths against the filesystem, collapse
+  same-error_path-with-multiple-targets into one "use Glob/Grep first"
+  bullet, rank by `evidence_count * 0.5 ** (days/5)`, cap the section at
+  15. Other `Learned: …` categories (environment, preference,
+  architecture) are untouched.
+- **`headroom unwrap codex` now actually undoes `headroom wrap codex`** —
+  previously there was no `unwrap codex` subcommand at all, so the injected
+  `model_provider = "headroom"` / `[model_providers.headroom]` block stayed
+  in `~/.codex/config.toml` forever and Codex continued routing through the
+  (potentially stopped) proxy, surfacing as `Missing environment variable:
+  OPENAI_API_KEY`. `wrap codex` now snapshots the pre-wrap
+  `config.toml` to `config.toml.headroom-backup` before its first injection,
+  and `unwrap codex` restores that snapshot byte-for-byte (or, if the
+  backup is missing, strips only the Headroom-managed block and leaves
+  surrounding user content intact). Safe no-op when run without a prior
+  wrap. Reported by @raenaryl in Discord.
 - **`headroom learn` no longer clobbers prior recommendations on re-run** —
   the marker block in `CLAUDE.md` / `MEMORY.md` is now merged with the
   prior block instead of wholesale-replaced. Sections re-surfaced by the
   new run win; sections not re-surfaced are carried forward so learnings
   accumulate across runs instead of disappearing. To fully rebuild the
   block, delete it manually and re-run. (#231)
+- **`headroom learn` no longer emits dangling cross-references when a
+  section is re-surfaced** — the analyzer now includes the project's
+  current `<!-- headroom:learn -->` block (from `CLAUDE.md` and
+  `MEMORY.md`) in the LLM digest as a "Prior Learned Patterns" section,
+  and the system prompt instructs the LLM that re-emitting a section
+  replaces the prior one wholesale. Prevents bullets like "`X` is *also*
+  large — same rule as `Y`, `Z`" from appearing after `Y` and `Z` got
+  dropped during per-section replacement. The writer's section-level
+  carry-forward from #231 remains in place as a safety net for sections
+  the LLM omits entirely. New helper `extract_marker_block` added to
+  `headroom.learn.writer`.
 
 ### Added
+- **`turn_id` linking agent-loop API calls to a single user prompt** — a new
+  `compute_turn_id(model, system, messages)` helper in
+  `headroom/proxy/helpers.py` hashes the message prefix up to and including
+  the last user-text message, yielding an id that is stable across every
+  agent-loop iteration of one prompt but rolls over when the user sends a
+  new prompt (or runs `/compact`, `/clear`). `RequestLog` gained a
+  `turn_id: str | None` field, which is stamped at every log site
+  (anthropic handler bedrock + direct branches, and the streaming handler)
+  and surfaced as `turn_id` in `/transformations/feed`. Lets downstream
+  consumers (e.g. the Headroom Desktop Activity tab) aggregate savings per
+  user prompt rather than per API call.
 - **Live flush of traffic-learned patterns to CLAUDE.md / MEMORY.md** — the
   `TrafficLearner` now writes to agent-native context files continuously
   during proxy operation, not just at shutdown. A new dirty-flag debounced

README.md

@@ -5,6 +5,7 @@
 **Compress everything your AI agent reads. Same answers, fraction of the tokens.**
 
 [![CI](https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg)](https://github.com/chopratejas/headroom/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/chopratejas/headroom/graph/badge.svg)](https://app.codecov.io/gh/chopratejas/headroom)
 [![PyPI](https://img.shields.io/pypi/v/headroom-ai.svg)](https://pypi.org/project/headroom-ai/)
 [![npm](https://img.shields.io/npm/v/headroom-ai.svg)](https://www.npmjs.com/package/headroom-ai)
 [![Model: Kompress-base](https://img.shields.io/badge/model-Kompress--base-yellow.svg)](https://huggingface.co/chopratejas/kompress-base)

docs/package-lock.json

@@ -17,7 +17,7 @@
 				"fumadocs-ui": "16.7.10",
 				"headroom-ai": "file:../sdk/typescript",
 				"lucide-react": "^1.7.0",
-				"next": "16.2.2",
+				"next": "16.2.4",
 				"react": "^19.2.4",
 				"react-dom": "^19.2.4",
 				"recharts": "^3.8.1",
@@ -33,7 +33,7 @@
 				"@types/react-dom": "^19.2.3",
 				"ai": "^6.0.149",
 				"openai": "^6.33.0",
-				"postcss": "^8.5.8",
+				"postcss": "^8.5.10",
 				"tailwindcss": "^4.2.2",
 				"typescript": "^5.9.3"
 			}
@@ -186,6 +186,80 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@emnapi/runtime": {
+			"version": "1.10.0",
+			"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+			"integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@esbuild/aix-ppc64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+			"integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+			"cpu": [
+				"ppc64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"aix"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/android-arm": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+			"integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+			"cpu": [
+				"arm"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"android"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/android-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+			"integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"android"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/android-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+			"integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"android"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
 		"node_modules/@esbuild/darwin-arm64": {
 			"version": "0.27.7",
 			"cpu": [
@@ -200,100 +274,854 @@
 				"node": ">=18"
 			}
 		},
-		"node_modules/@floating-ui/core": {
-			"version": "1.7.5",
+		"node_modules/@esbuild/darwin-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+			"integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+			"cpu": [
+				"x64"
+			],
 			"license": "MIT",
-			"dependencies": {
-				"@floating-ui/utils": "^0.2.11"
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">=18"
 			}
 		},
-		"node_modules/@floating-ui/dom": {
-			"version": "1.7.6",
+		"node_modules/@esbuild/freebsd-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+			"integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+			"cpu": [
+				"arm64"
+			],
 			"license": "MIT",
-			"dependencies": {
-				"@floating-ui/core": "^1.7.5",
-				"@floating-ui/utils": "^0.2.11"
+			"optional": true,
+			"os": [
+				"freebsd"
+			],
+			"engines": {
+				"node": ">=18"
 			}
 		},
-		"node_modules/@floating-ui/react-dom": {
-			"version": "2.1.8",
+		"node_modules/@esbuild/freebsd-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+			"integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+			"cpu": [
+				"x64"
+			],
 			"license": "MIT",
-			"dependencies": {
-				"@floating-ui/dom": "^1.7.6"
-			},
-			"peerDependencies": {
-				"react": ">=16.8.0",
-				"react-dom": ">=16.8.0"
+			"optional": true,
+			"os": [
+				"freebsd"
+			],
+			"engines": {
+				"node": ">=18"
 			}
 		},
-		"node_modules/@floating-ui/utils": {
-			"version": "0.2.11",
-			"license": "MIT"
+		"node_modules/@esbuild/linux-arm": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+			"integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+			"cpu": [
+				"arm"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
 		},
-		"node_modules/@formatjs/fast-memoize": {
-			"version": "3.1.1",
-			"license": "MIT"
+		"node_modules/@esbuild/linux-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+			"integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
 		},
-		"node_modules/@formatjs/intl-localematcher": {
-			"version": "0.8.2",
+		"node_modules/@esbuild/linux-ia32": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+			"integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+			"cpu": [
+				"ia32"
+			],
 			"license": "MIT",
-			"dependencies": {
-				"@formatjs/fast-memoize": "3.1.1"
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
 			}
 		},
-		"node_modules/@fumadocs/tailwind": {
-			"version": "0.0.3",
+		"node_modules/@esbuild/linux-loong64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+			"integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+			"cpu": [
+				"loong64"
+			],
 			"license": "MIT",
-			"dependencies": {
-				"postcss-selector-parser": "^7.1.1"
-			},
-			"peerDependencies": {
-				"tailwindcss": "^4.0.0"
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/linux-mips64el": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+			"integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+			"cpu": [
+				"mips64el"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/linux-ppc64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+			"integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+			"cpu": [
+				"ppc64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/linux-riscv64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+			"integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+			"cpu": [
+				"riscv64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/linux-s390x": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+			"integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+			"cpu": [
+				"s390x"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/linux-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+			"integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/netbsd-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+			"integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"netbsd"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/netbsd-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+			"integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"netbsd"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/openbsd-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+			"integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"openbsd"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/openbsd-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+			"integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"openbsd"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/openharmony-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+			"integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"openharmony"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/sunos-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+			"integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"sunos"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/win32-arm64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+			"integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/win32-ia32": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+			"integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+			"cpu": [
+				"ia32"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@esbuild/win32-x64": {
+			"version": "0.27.7",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+			"integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+			"cpu": [
+				"x64"
+			],
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@floating-ui/core": {
+			"version": "1.7.5",
+			"license": "MIT",
+			"dependencies": {
+				"@floating-ui/utils": "^0.2.11"
+			}
+		},
+		"node_modules/@floating-ui/dom": {
+			"version": "1.7.6",
+			"license": "MIT",
+			"dependencies": {
+				"@floating-ui/core": "^1.7.5",
+				"@floating-ui/utils": "^0.2.11"
+			}
+		},
+		"node_modules/@floating-ui/react-dom": {
+			"version": "2.1.8",
+			"license": "MIT",
+			"dependencies": {
+				"@floating-ui/dom": "^1.7.6"
+			},
+			"peerDependencies": {
+				"react": ">=16.8.0",
+				"react-dom": ">=16.8.0"
+			}
+		},
+		"node_modules/@floating-ui/utils": {
+			"version": "0.2.11",
+			"license": "MIT"
+		},
+		"node_modules/@formatjs/fast-memoize": {
+			"version": "3.1.1",
+			"license": "MIT"
+		},
+		"node_modules/@formatjs/intl-localematcher": {
+			"version": "0.8.2",
+			"license": "MIT",
+			"dependencies": {
+				"@formatjs/fast-memoize": "3.1.1"
+			}
+		},
+		"node_modules/@fumadocs/tailwind": {
+			"version": "0.0.3",
+			"license": "MIT",
+			"dependencies": {
+				"postcss-selector-parser": "^7.1.1"
+			},
+			"peerDependencies": {
+				"tailwindcss": "^4.0.0"
+			},
+			"peerDependenciesMeta": {
+				"tailwindcss": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@img/colour": {
+			"version": "1.1.0",
+			"license": "MIT",
+			"optional": true,
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/@img/sharp-darwin-arm64": {
+			"version": "0.34.5",
+			"cpu": [
+				"arm64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-darwin-arm64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-darwin-x64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+			"integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+			"cpu": [
+				"x64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-darwin-x64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-libvips-darwin-arm64": {
+			"version": "1.2.4",
+			"cpu": [
+				"arm64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-darwin-x64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+			"integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+			"cpu": [
+				"x64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-arm": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+			"integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+			"cpu": [
+				"arm"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-arm64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+			"integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-ppc64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+			"integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+			"cpu": [
+				"ppc64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-riscv64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+			"integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+			"cpu": [
+				"riscv64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-s390x": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+			"integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+			"cpu": [
+				"s390x"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linux-x64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+			"integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+			"cpu": [
+				"x64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+			"integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-libvips-linuxmusl-x64": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+			"integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+			"cpu": [
+				"x64"
+			],
+			"license": "LGPL-3.0-or-later",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			}
+		},
+		"node_modules/@img/sharp-linux-arm": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+			"integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+			"cpu": [
+				"arm"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-arm": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linux-arm64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+			"integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-arm64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linux-ppc64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+			"integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+			"cpu": [
+				"ppc64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-ppc64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linux-riscv64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+			"integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+			"cpu": [
+				"riscv64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-riscv64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linux-s390x": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+			"integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+			"cpu": [
+				"s390x"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-s390x": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linux-x64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+			"integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+			"cpu": [
+				"x64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linux-x64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linuxmusl-arm64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+			"integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-linuxmusl-x64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+			"integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+			"cpu": [
+				"x64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
+			},
+			"optionalDependencies": {
+				"@img/sharp-libvips-linuxmusl-x64": "1.2.4"
+			}
+		},
+		"node_modules/@img/sharp-wasm32": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+			"integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+			"cpu": [
+				"wasm32"
+			],
+			"license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+			"optional": true,
+			"dependencies": {
+				"@emnapi/runtime": "^1.7.0"
+			},
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
 			},
-			"peerDependenciesMeta": {
-				"tailwindcss": {
-					"optional": true
-				}
+			"funding": {
+				"url": "https://opencollective.com/libvips"
 			}
 		},
-		"node_modules/@img/colour": {
-			"version": "1.1.0",
-			"license": "MIT",
+		"node_modules/@img/sharp-win32-arm64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+			"integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "Apache-2.0 AND LGPL-3.0-or-later",
 			"optional": true,
+			"os": [
+				"win32"
+			],
 			"engines": {
-				"node": ">=18"
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/libvips"
 			}
 		},
-		"node_modules/@img/sharp-darwin-arm64": {
+		"node_modules/@img/sharp-win32-ia32": {
 			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+			"integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
 			"cpu": [
-				"arm64"
+				"ia32"
 			],
-			"license": "Apache-2.0",
+			"license": "Apache-2.0 AND LGPL-3.0-or-later",
 			"optional": true,
 			"os": [
-				"darwin"
+				"win32"
 			],
 			"engines": {
 				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
 			},
 			"funding": {
 				"url": "https://opencollective.com/libvips"
-			},
-			"optionalDependencies": {
-				"@img/sharp-libvips-darwin-arm64": "1.2.4"
 			}
 		},
-		"node_modules/@img/sharp-libvips-darwin-arm64": {
-			"version": "1.2.4",
+		"node_modules/@img/sharp-win32-x64": {
+			"version": "0.34.5",
+			"resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+			"integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
 			"cpu": [
-				"arm64"
+				"x64"
 			],
-			"license": "LGPL-3.0-or-later",
+			"license": "Apache-2.0 AND LGPL-3.0-or-later",
 			"optional": true,
 			"os": [
-				"darwin"
+				"win32"
 			],
+			"engines": {
+				"node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+			},
 			"funding": {
 				"url": "https://opencollective.com/libvips"
 			}
@@ -374,11 +1202,15 @@
 			}
 		},
 		"node_modules/@next/env": {
-			"version": "16.2.2",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/env/-/env-16.2.4.tgz",
+			"integrity": "sha512-dKkkOzOSwFYe5RX6y26fZgkSpVAlIOJKQHIiydQcrWH6y/97+RceSOAdjZ14Qa3zLduVUy0TXcn+EiM6t4rPgw==",
 			"license": "MIT"
 		},
 		"node_modules/@next/swc-darwin-arm64": {
-			"version": "16.2.2",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.2.4.tgz",
+			"integrity": "sha512-OXTFFox5EKN1Ym08vfrz+OXxmCcEjT4SFMbNRsWZE99dMqt2Kcusl5MqPXcW232RYkMLQTy0hqgAMEsfEd/l2A==",
 			"cpu": [
 				"arm64"
 			],
@@ -392,12 +1224,13 @@
 			}
 		},
 		"node_modules/@next/swc-darwin-x64": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.2.2.tgz",
-			"integrity": "sha512-7ZwSgNKJNQiwW0CKhNm9B1WS2L1Olc4B2XY0hPYCAL3epFnugMhuw5TMWzMilQ3QCZcCHoYm9NGWTHbr5REFxw==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.2.4.tgz",
+			"integrity": "sha512-XhpVnUfmYWvD3YrXu55XdcAkQtOnvaI6wtQa8fuF5fGoKoxIUZ0kWPtcOfqJEWngFF/lOS9l3+O9CcownhiQxQ==",
 			"cpu": [
 				"x64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"darwin"
@@ -407,12 +1240,13 @@
 			}
 		},
 		"node_modules/@next/swc-linux-arm64-gnu": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.2.2.tgz",
-			"integrity": "sha512-c3m8kBHMziMgo2fICOP/cd/5YlrxDU5YYjAJeQLyFsCqVF8xjOTH/QYG4a2u48CvvZZSj1eHQfBCbyh7kBr30Q==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.2.4.tgz",
+			"integrity": "sha512-Mx/tjlNA3G8kg14QvuGAJ4xBwPk1tUHq56JxZ8CXnZwz1Etz714soCEzGQQzVMz4bEnGPowzkV6Xrp6wAkEWOQ==",
 			"cpu": [
 				"arm64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"linux"
@@ -422,12 +1256,13 @@
 			}
 		},
 		"node_modules/@next/swc-linux-arm64-musl": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.2.2.tgz",
-			"integrity": "sha512-VKLuscm0P/mIfzt+SDdn2+8TNNJ7f0qfEkA+az7OqQbjzKdBxAHs0UvuiVoCtbwX+dqMEL9U54b5wQ/aN3dHeg==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.2.4.tgz",
+			"integrity": "sha512-iVMMp14514u7Nup2umQS03nT/bN9HurK8ufylC3FZNykrwjtx7V1A7+4kvhbDSCeonTVqV3Txnv0Lu+m2oDXNg==",
 			"cpu": [
 				"arm64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"linux"
@@ -437,12 +1272,13 @@
 			}
 		},
 		"node_modules/@next/swc-linux-x64-gnu": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.2.2.tgz",
-			"integrity": "sha512-kU3OPHJq6sBUjOk7wc5zJ7/lipn8yGldMoAv4z67j6ov6Xo/JvzA7L7LCsyzzsXmgLEhk3Qkpwqaq/1+XpNR3g==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.2.4.tgz",
+			"integrity": "sha512-EZOvm1aQWgnI/N/xcWOlnS3RQBk0VtVav5Zo7n4p0A7UKyTDx047k8opDbXgBpHl4CulRqRfbw3QrX2w5UOXMQ==",
 			"cpu": [
 				"x64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"linux"
@@ -452,12 +1288,13 @@
 			}
 		},
 		"node_modules/@next/swc-linux-x64-musl": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.2.2.tgz",
-			"integrity": "sha512-CKXRILyErMtUftp+coGcZ38ZwE/Aqq45VMCcRLr2I4OXKrgxIBDXHnBgeX/UMil0S09i2JXaDL3Q+TN8D/cKmg==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.2.4.tgz",
+			"integrity": "sha512-h9FxsngCm9cTBf71AR4fGznDEDx1hS7+kSEiIRjq5kO1oXWm07DxVGZjCvk0SGx7TSjlUqhI8oOyz7NfwAdPoA==",
 			"cpu": [
 				"x64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"linux"
@@ -467,12 +1304,13 @@
 			}
 		},
 		"node_modules/@next/swc-win32-arm64-msvc": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.2.2.tgz",
-			"integrity": "sha512-sS/jSk5VUoShUqINJFvNjVT7JfR5ORYj/+/ZpOYbbIohv/lQfduWnGAycq2wlknbOql2xOR0DoV0s6Xfcy49+g==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.2.4.tgz",
+			"integrity": "sha512-3NdJV5OXMSOeJYijX+bjaLge3mJBlh4ybydbT4GFoB/2hAojWHtMhl3CYlYoMrjPuodp0nzFVi4Tj2+WaMg+Ow==",
 			"cpu": [
 				"arm64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"win32"
@@ -482,12 +1320,13 @@
 			}
 		},
 		"node_modules/@next/swc-win32-x64-msvc": {
-			"version": "16.2.2",
-			"resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.2.2.tgz",
-			"integrity": "sha512-aHaKceJgdySReT7qeck5oShucxWRiiEuwCGK8HHALe6yZga8uyFpLkPgaRw3kkF04U7ROogL/suYCNt/+CuXGA==",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.2.4.tgz",
+			"integrity": "sha512-kMVGgsqhO5YTYODD9IPGGhA6iprWidQckK3LmPeW08PIFENRmgfb4MjXHO+p//d+ts2rpjvK5gXWzXSMrPl9cw==",
 			"cpu": [
 				"x64"
 			],
+			"license": "MIT",
 			"optional": true,
 			"os": [
 				"win32"
@@ -502,7 +1341,6 @@
 			"integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==",
 			"devOptional": true,
 			"license": "Apache-2.0",
-			"peer": true,
 			"engines": {
 				"node": ">=8.0.0"
 			}
@@ -1421,73 +2259,337 @@
 				"node": ">=20"
 			}
 		},
-		"node_modules/@shikijs/vscode-textmate": {
-			"version": "10.0.2",
-			"license": "MIT"
-		},
-		"node_modules/@standard-schema/spec": {
+		"node_modules/@shikijs/vscode-textmate": {
+			"version": "10.0.2",
+			"license": "MIT"
+		},
+		"node_modules/@standard-schema/spec": {
+			"version": "1.1.0",
+			"license": "MIT"
+		},
+		"node_modules/@standard-schema/utils": {
+			"version": "0.3.0",
+			"resolved": "https://registry.npmjs.org/@standard-schema/utils/-/utils-0.3.0.tgz",
+			"integrity": "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==",
+			"license": "MIT"
+		},
+		"node_modules/@swc/helpers": {
+			"version": "0.5.15",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"tslib": "^2.8.0"
+			}
+		},
+		"node_modules/@tailwindcss/node": {
+			"version": "4.2.2",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@jridgewell/remapping": "^2.3.5",
+				"enhanced-resolve": "^5.19.0",
+				"jiti": "^2.6.1",
+				"lightningcss": "1.32.0",
+				"magic-string": "^0.30.21",
+				"source-map-js": "^1.2.1",
+				"tailwindcss": "4.2.2"
+			}
+		},
+		"node_modules/@tailwindcss/oxide": {
+			"version": "4.2.2",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">= 20"
+			},
+			"optionalDependencies": {
+				"@tailwindcss/oxide-android-arm64": "4.2.2",
+				"@tailwindcss/oxide-darwin-arm64": "4.2.2",
+				"@tailwindcss/oxide-darwin-x64": "4.2.2",
+				"@tailwindcss/oxide-freebsd-x64": "4.2.2",
+				"@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.2",
+				"@tailwindcss/oxide-linux-arm64-gnu": "4.2.2",
+				"@tailwindcss/oxide-linux-arm64-musl": "4.2.2",
+				"@tailwindcss/oxide-linux-x64-gnu": "4.2.2",
+				"@tailwindcss/oxide-linux-x64-musl": "4.2.2",
+				"@tailwindcss/oxide-wasm32-wasi": "4.2.2",
+				"@tailwindcss/oxide-win32-arm64-msvc": "4.2.2",
+				"@tailwindcss/oxide-win32-x64-msvc": "4.2.2"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-android-arm64": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.2.2.tgz",
+			"integrity": "sha512-dXGR1n+P3B6748jZO/SvHZq7qBOqqzQ+yFrXpoOWWALWndF9MoSKAT3Q0fYgAzYzGhxNYOoysRvYlpixRBBoDg==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"android"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-darwin-arm64": {
+			"version": "4.2.2",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-darwin-x64": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.2.2.tgz",
+			"integrity": "sha512-BlR+2c3nzc8f2G639LpL89YY4bdcIdUmiOOkv2GQv4/4M0vJlpXEa0JXNHhCHU7VWOKWT/CjqHdTP8aUuDJkuw==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-freebsd-x64": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.2.2.tgz",
+			"integrity": "sha512-YUqUgrGMSu2CDO82hzlQ5qSb5xmx3RUrke/QgnoEx7KvmRJHQuZHZmZTLSuuHwFf0DJPybFMXMYf+WJdxHy/nQ==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"freebsd"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-linux-arm-gnueabihf": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.2.2.tgz",
+			"integrity": "sha512-FPdhvsW6g06T9BWT0qTwiVZYE2WIFo2dY5aCSpjG/S/u1tby+wXoslXS0kl3/KXnULlLr1E3NPRRw0g7t2kgaQ==",
+			"cpu": [
+				"arm"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-linux-arm64-gnu": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.2.2.tgz",
+			"integrity": "sha512-4og1V+ftEPXGttOO7eCmW7VICmzzJWgMx+QXAJRAhjrSjumCwWqMfkDrNu1LXEQzNAwz28NCUpucgQPrR4S2yw==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-linux-arm64-musl": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.2.2.tgz",
+			"integrity": "sha512-oCfG/mS+/+XRlwNjnsNLVwnMWYH7tn/kYPsNPh+JSOMlnt93mYNCKHYzylRhI51X+TbR+ufNhhKKzm6QkqX8ag==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-linux-x64-gnu": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.2.2.tgz",
+			"integrity": "sha512-rTAGAkDgqbXHNp/xW0iugLVmX62wOp2PoE39BTCGKjv3Iocf6AFbRP/wZT/kuCxC9QBh9Pu8XPkv/zCZB2mcMg==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-linux-x64-musl": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.2.2.tgz",
+			"integrity": "sha512-XW3t3qwbIwiSyRCggeO2zxe3KWaEbM0/kW9e8+0XpBgyKU4ATYzcVSMKteZJ1iukJ3HgHBjbg9P5YPRCVUxlnQ==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi": {
+			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.2.2.tgz",
+			"integrity": "sha512-eKSztKsmEsn1O5lJ4ZAfyn41NfG7vzCg496YiGtMDV86jz1q/irhms5O0VrY6ZwTUkFy/EKG3RfWgxSI3VbZ8Q==",
+			"bundleDependencies": [
+				"@napi-rs/wasm-runtime",
+				"@emnapi/core",
+				"@emnapi/runtime",
+				"@tybys/wasm-util",
+				"@emnapi/wasi-threads",
+				"tslib"
+			],
+			"cpu": [
+				"wasm32"
+			],
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"@emnapi/core": "^1.8.1",
+				"@emnapi/runtime": "^1.8.1",
+				"@emnapi/wasi-threads": "^1.1.0",
+				"@napi-rs/wasm-runtime": "^1.1.1",
+				"@tybys/wasm-util": "^0.10.1",
+				"tslib": "^2.8.1"
+			},
+			"engines": {
+				"node": ">=14.0.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+			"version": "1.8.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"@emnapi/wasi-threads": "1.1.0",
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+			"version": "1.8.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
 			"version": "1.1.0",
-			"license": "MIT"
-		},
-		"node_modules/@standard-schema/utils": {
-			"version": "0.3.0",
-			"resolved": "https://registry.npmjs.org/@standard-schema/utils/-/utils-0.3.0.tgz",
-			"integrity": "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==",
-			"license": "MIT"
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
 		},
-		"node_modules/@swc/helpers": {
-			"version": "0.5.15",
-			"license": "Apache-2.0",
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+			"version": "1.1.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
 			"dependencies": {
-				"tslib": "^2.8.0"
+				"@emnapi/core": "^1.7.1",
+				"@emnapi/runtime": "^1.7.1",
+				"@tybys/wasm-util": "^0.10.1"
+			},
+			"funding": {
+				"type": "github",
+				"url": "https://github.com/sponsors/Brooooooklyn"
 			}
 		},
-		"node_modules/@tailwindcss/node": {
-			"version": "4.2.2",
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+			"version": "0.10.1",
 			"dev": true,
+			"inBundle": true,
 			"license": "MIT",
+			"optional": true,
 			"dependencies": {
-				"@jridgewell/remapping": "^2.3.5",
-				"enhanced-resolve": "^5.19.0",
-				"jiti": "^2.6.1",
-				"lightningcss": "1.32.0",
-				"magic-string": "^0.30.21",
-				"source-map-js": "^1.2.1",
-				"tailwindcss": "4.2.2"
+				"tslib": "^2.4.0"
 			}
 		},
-		"node_modules/@tailwindcss/oxide": {
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+			"version": "2.8.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "0BSD",
+			"optional": true
+		},
+		"node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
 			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.2.2.tgz",
+			"integrity": "sha512-qPmaQM4iKu5mxpsrWZMOZRgZv1tOZpUm+zdhhQP0VhJfyGGO3aUKdbh3gDZc/dPLQwW4eSqWGrrcWNBZWUWaXQ==",
+			"cpu": [
+				"arm64"
+			],
 			"dev": true,
 			"license": "MIT",
+			"optional": true,
+			"os": [
+				"win32"
+			],
 			"engines": {
 				"node": ">= 20"
-			},
-			"optionalDependencies": {
-				"@tailwindcss/oxide-android-arm64": "4.2.2",
-				"@tailwindcss/oxide-darwin-arm64": "4.2.2",
-				"@tailwindcss/oxide-darwin-x64": "4.2.2",
-				"@tailwindcss/oxide-freebsd-x64": "4.2.2",
-				"@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.2",
-				"@tailwindcss/oxide-linux-arm64-gnu": "4.2.2",
-				"@tailwindcss/oxide-linux-arm64-musl": "4.2.2",
-				"@tailwindcss/oxide-linux-x64-gnu": "4.2.2",
-				"@tailwindcss/oxide-linux-x64-musl": "4.2.2",
-				"@tailwindcss/oxide-wasm32-wasi": "4.2.2",
-				"@tailwindcss/oxide-win32-arm64-msvc": "4.2.2",
-				"@tailwindcss/oxide-win32-x64-msvc": "4.2.2"
 			}
 		},
-		"node_modules/@tailwindcss/oxide-darwin-arm64": {
+		"node_modules/@tailwindcss/oxide-win32-x64-msvc": {
 			"version": "4.2.2",
+			"resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.2.2.tgz",
+			"integrity": "sha512-1T/37VvI7WyH66b+vqHj/cLwnCxt7Qt3WFu5Q8hk65aOvlwAhs7rAp1VkulBJw/N4tMirXjVnylTR72uI0HGcA==",
 			"cpu": [
-				"arm64"
+				"x64"
 			],
 			"dev": true,
 			"license": "MIT",
 			"optional": true,
 			"os": [
-				"darwin"
+				"win32"
 			],
 			"engines": {
 				"node": ">= 20"
@@ -1656,15 +2758,13 @@
 		"node_modules/@types/mdast": {
 			"version": "4.0.4",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"@types/unist": "*"
 			}
 		},
 		"node_modules/@types/mdx": {
 			"version": "2.0.13",
-			"license": "MIT",
-			"peer": true
+			"license": "MIT"
 		},
 		"node_modules/@types/ms": {
 			"version": "2.1.0",
@@ -1682,7 +2782,6 @@
 			"version": "19.2.14",
 			"devOptional": true,
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"csstype": "^3.2.2"
 			}
@@ -1691,7 +2790,6 @@
 			"version": "19.2.3",
 			"devOptional": true,
 			"license": "MIT",
-			"peer": true,
 			"peerDependencies": {
 				"@types/react": "^19.2.0"
 			}
@@ -1735,7 +2833,6 @@
 		"node_modules/acorn": {
 			"version": "8.16.0",
 			"license": "MIT",
-			"peer": true,
 			"bin": {
 				"acorn": "bin/acorn"
 			},
@@ -2417,7 +3514,6 @@
 		"node_modules/fumadocs-core": {
 			"version": "16.7.10",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"@formatjs/intl-localematcher": "^0.8.2",
 				"@orama/orama": "^3.1.18",
@@ -2655,7 +3751,6 @@
 		"node_modules/fumadocs-ui": {
 			"version": "16.7.10",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"@fumadocs/tailwind": "0.0.3",
 				"@radix-ui/react-accordion": "^1.2.12",
@@ -3059,6 +4154,27 @@
 				"lightningcss-win32-x64-msvc": "1.32.0"
 			}
 		},
+		"node_modules/lightningcss-android-arm64": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+			"integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"android"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
 		"node_modules/lightningcss-darwin-arm64": {
 			"version": "1.32.0",
 			"cpu": [
@@ -3078,6 +4194,195 @@
 				"url": "https://opencollective.com/parcel"
 			}
 		},
+		"node_modules/lightningcss-darwin-x64": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+			"integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-freebsd-x64": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+			"integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"freebsd"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-linux-arm-gnueabihf": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+			"integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+			"cpu": [
+				"arm"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-linux-arm64-gnu": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+			"integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-linux-arm64-musl": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+			"integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-linux-x64-gnu": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+			"integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-linux-x64-musl": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+			"integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-win32-arm64-msvc": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+			"integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
+		"node_modules/lightningcss-win32-x64-msvc": {
+			"version": "1.32.0",
+			"resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+			"integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MPL-2.0",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">= 12.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/parcel"
+			}
+		},
 		"node_modules/longest-streak": {
 			"version": "3.1.0",
 			"license": "MIT",
@@ -3089,7 +4394,6 @@
 		"node_modules/lucide-react": {
 			"version": "1.7.0",
 			"license": "ISC",
-			"peer": true,
 			"peerDependencies": {
 				"react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
 			}
@@ -4106,11 +5410,12 @@
 			}
 		},
 		"node_modules/next": {
-			"version": "16.2.2",
+			"version": "16.2.4",
+			"resolved": "https://registry.npmjs.org/next/-/next-16.2.4.tgz",
+			"integrity": "sha512-kPvz56wF5frc+FxlHI5qnklCzbq53HTwORaWBGdT0vNoKh1Aya9XC8aPauH4NJxqtzbWsS5mAbctm4cr+EkQ2Q==",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
-				"@next/env": "16.2.2",
+				"@next/env": "16.2.4",
 				"@swc/helpers": "0.5.15",
 				"baseline-browser-mapping": "^2.9.19",
 				"caniuse-lite": "^1.0.30001579",
@@ -4124,14 +5429,14 @@
 				"node": ">=20.9.0"
 			},
 			"optionalDependencies": {
-				"@next/swc-darwin-arm64": "16.2.2",
-				"@next/swc-darwin-x64": "16.2.2",
-				"@next/swc-linux-arm64-gnu": "16.2.2",
-				"@next/swc-linux-arm64-musl": "16.2.2",
-				"@next/swc-linux-x64-gnu": "16.2.2",
-				"@next/swc-linux-x64-musl": "16.2.2",
-				"@next/swc-win32-arm64-msvc": "16.2.2",
-				"@next/swc-win32-x64-msvc": "16.2.2",
+				"@next/swc-darwin-arm64": "16.2.4",
+				"@next/swc-darwin-x64": "16.2.4",
+				"@next/swc-linux-arm64-gnu": "16.2.4",
+				"@next/swc-linux-arm64-musl": "16.2.4",
+				"@next/swc-linux-x64-gnu": "16.2.4",
+				"@next/swc-linux-x64-musl": "16.2.4",
+				"@next/swc-win32-arm64-msvc": "16.2.4",
+				"@next/swc-win32-x64-msvc": "16.2.4",
 				"sharp": "^0.34.5"
 			},
 			"peerDependencies": {
@@ -4305,7 +5610,9 @@
 			}
 		},
 		"node_modules/postcss": {
-			"version": "8.5.8",
+			"version": "8.5.10",
+			"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+			"integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
 			"dev": true,
 			"funding": [
 				{
@@ -4366,7 +5673,6 @@
 		"node_modules/react": {
 			"version": "19.2.4",
 			"license": "MIT",
-			"peer": true,
 			"engines": {
 				"node": ">=0.10.0"
 			}
@@ -4374,7 +5680,6 @@
 		"node_modules/react-dom": {
 			"version": "19.2.4",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"scheduler": "^0.27.0"
 			},
@@ -4408,7 +5713,6 @@
 			"resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
 			"integrity": "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==",
 			"license": "MIT",
-			"peer": true,
 			"dependencies": {
 				"@types/use-sync-external-store": "^0.0.6",
 				"use-sync-external-store": "^1.4.0"
@@ -4594,8 +5898,7 @@
 			"version": "5.0.1",
 			"resolved": "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz",
 			"integrity": "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==",
-			"license": "MIT",
-			"peer": true
+			"license": "MIT"
 		},
 		"node_modules/redux-thunk": {
 			"version": "3.1.0",
@@ -4908,8 +6211,7 @@
 		"node_modules/tailwindcss": {
 			"version": "4.2.2",
 			"devOptional": true,
-			"license": "MIT",
-			"peer": true
+			"license": "MIT"
 		},
 		"node_modules/tapable": {
 			"version": "2.3.2",
@@ -4998,7 +6300,6 @@
 			"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
 			"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
 			"license": "Apache-2.0",
-			"peer": true,
 			"bin": {
 				"tsc": "bin/tsc",
 				"tsserver": "bin/tsserver"
@@ -5240,7 +6541,6 @@
 		"node_modules/zod": {
 			"version": "4.3.6",
 			"license": "MIT",
-			"peer": true,
 			"funding": {
 				"url": "https://github.com/sponsors/colinhacks"
 			}

docs/package.json

@@ -18,7 +18,7 @@
 		"fumadocs-ui": "16.7.10",
 		"headroom-ai": "file:../sdk/typescript",
 		"lucide-react": "^1.7.0",
-		"next": "16.2.2",
+		"next": "16.2.4",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",
 		"recharts": "^3.8.1",
@@ -34,7 +34,7 @@
 		"@types/react-dom": "^19.2.3",
 		"ai": "^6.0.149",
 		"openai": "^6.33.0",
-		"postcss": "^8.5.8",
+		"postcss": "^8.5.10",
 		"tailwindcss": "^4.2.2",
 		"typescript": "^5.9.3"
 	}

e2e/__init__.py

@@ -0,0 +1,7 @@
+"""End-to-end test suites for Headroom CLI commands.
+
+Subpackages:
+    _lib — shared harness and helpers
+    init — ``headroom init`` coverage
+    wrap — ``headroom wrap`` coverage
+"""

e2e/_lib/__init__.py

@@ -0,0 +1,35 @@
+"""Shared helpers for Docker / CI e2e tests.
+
+This package centralizes utilities used by the per-command e2e harnesses
+(`e2e/init/run.py`, future `e2e/install/run.py`, `e2e/wrap/run.py`, ...).
+The goal is that each command test suite is a small declarative file that
+imports from this package, so new commands can be covered with minimal
+duplication.
+"""
+
+from __future__ import annotations
+
+from .assertions import (
+    assert_exit,
+    assert_stderr_contains,
+    assert_stdout_contains,
+    read_agent_settings,
+)
+from .harness import Case, CaseContext, run_case_sequence, run_cases
+from .path_env import with_clean_path
+from .paths import agent_settings_path
+from .shims import make_shim
+
+__all__ = [
+    "Case",
+    "CaseContext",
+    "agent_settings_path",
+    "assert_exit",
+    "assert_stderr_contains",
+    "assert_stdout_contains",
+    "make_shim",
+    "read_agent_settings",
+    "run_case_sequence",
+    "run_cases",
+    "with_clean_path",
+]

e2e/_lib/assertions.py

@@ -0,0 +1,43 @@
+"""Shared assertion helpers for e2e cases.
+
+Assertions raise ``AssertionError`` with a descriptive message. The harness
+catches them and attributes the failure to the owning ``Case``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .paths import Agent, Scope, agent_settings_path
+
+
+def assert_exit(actual: int, expected: int, *, context: str = "") -> None:
+    if actual != expected:
+        suffix = f" ({context})" if context else ""
+        raise AssertionError(f"Expected exit code {expected}, got {actual}{suffix}")
+
+
+def assert_stdout_contains(stdout: str, needle: str) -> None:
+    if needle not in stdout:
+        raise AssertionError(f"stdout missing {needle!r}:\n---\n{stdout}\n---")
+
+
+def assert_stderr_contains(stderr: str, needle: str) -> None:
+    if needle not in stderr:
+        raise AssertionError(f"stderr missing {needle!r}:\n---\n{stderr}\n---")
+
+
+def read_agent_settings(
+    agent: Agent, *, scope: Scope, home: Path, project: Path
+) -> dict[str, Any] | str:
+    """Read an agent's settings file, returning dict for JSON and str for TOML/other."""
+
+    path = agent_settings_path(agent, scope=scope, home=home, project=project)
+    if not path.exists():
+        raise AssertionError(f"Expected settings file at {path}, not found")
+    text = path.read_text(encoding="utf-8")
+    if path.suffix == ".json":
+        return json.loads(text)
+    return text

e2e/_lib/harness.py

@@ -0,0 +1,336 @@
+"""Declarative test-case harness for Docker e2e runners.
+
+Each command gets its own ``run.py`` file that builds a list of ``Case``
+objects and calls ``run_cases(cases)``. The harness handles:
+
+* creating a scratch HOME and project directory per case
+* dropping the requested shims into a dedicated shim dir
+* building a clean PATH that only exposes the shim dir + minimal system dirs
+* invoking the ``headroom`` subprocess with the case's argv
+* running the case's assertions against stdout / stderr / exit code / files
+* reporting pass/fail per case and a final summary
+
+``run_cases`` returns a non-zero exit code if any case fails, so Docker
+containers driving it can fail fast.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .assertions import assert_exit, assert_stderr_contains, assert_stdout_contains
+from .path_env import with_clean_path
+from .shims import ShimBehavior, make_shim
+
+CaseCallback = Callable[["CaseContext"], None]
+
+
+@dataclass
+class CaseContext:
+    """Runtime context passed to assertion callbacks."""
+
+    name: str
+    home: Path
+    project: Path
+    shim_dir: Path
+    shim_log: Path
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+@dataclass
+class Case:
+    """Declarative specification of a single e2e test case.
+
+    Attributes:
+        name: Human-readable identifier, printed on success/failure.
+        argv: Arguments passed to ``headroom`` (e.g. ``["init", "-g", "claude"]``).
+        shims: Mapping of shim name -> behavior to drop into the shim dir.
+        env_extra: Extra env vars layered on top of the clean env.
+        expected_exit: Required exit code (default 0).
+        expected_stdout_contains: Substrings that must appear on stdout.
+        expected_stderr_contains: Substrings that must appear on stderr.
+        expected_files: Paths (relative to home or project) that must exist.
+                        Use ``{home}/...`` or ``{project}/...`` placeholders.
+        extra_assertions: Optional list of callbacks invoked after exit-code /
+                          stdout / stderr / file checks pass. Receives a
+                          ``CaseContext``. Use for JSON-content assertions,
+                          shim-log inspection, etc.
+    """
+
+    name: str
+    argv: list[str]
+    shims: dict[str, ShimBehavior] = field(default_factory=dict)
+    env_extra: dict[str, str] = field(default_factory=dict)
+    expected_exit: int = 0
+    expected_stdout_contains: list[str] = field(default_factory=list)
+    expected_stderr_contains: list[str] = field(default_factory=list)
+    expected_files: list[str] = field(default_factory=list)
+    extra_assertions: list[CaseCallback] = field(default_factory=list)
+
+
+def _log(message: str) -> None:
+    print(f"[e2e] {message}", flush=True)
+
+
+def _resolve_placeholder(spec: str, *, home: Path, project: Path) -> Path:
+    return Path(spec.format(home=str(home), project=str(project)))
+
+
+def _resolve_headroom_bin(name: str) -> str:
+    """Return the absolute path to the headroom binary before PATH is scrubbed.
+
+    ``with_clean_path`` intentionally narrows PATH so agent shims dominate;
+    that would also hide the real ``headroom`` binary (typically at
+    ``/opt/*venv/bin/headroom`` or similar). Resolving up-front lets the
+    subprocess launch even after PATH is cleaned.
+    """
+
+    if os.sep in name or (os.altsep and os.altsep in name):
+        return name
+    import shutil
+
+    resolved = shutil.which(name)
+    if resolved:
+        return resolved
+    # Fall back to the bare name; subprocess will raise a clear
+    # FileNotFoundError that the case output surfaces.
+    return name
+
+
+def _run_single(case: Case, headroom_bin: str = "headroom") -> bool:
+    """Execute one case. Return True on pass, False on fail."""
+
+    with tempfile.TemporaryDirectory(prefix=f"headroom-e2e-{case.name}-") as temp_raw:
+        temp_root = Path(temp_raw)
+        home = temp_root / "home"
+        project = temp_root / "project"
+        shim_dir = temp_root / "bin"
+        shim_log = temp_root / "shim-log.jsonl"
+        home.mkdir(parents=True)
+        project.mkdir(parents=True)
+
+        for shim_name, behavior in case.shims.items():
+            make_shim(shim_name, shim_dir, behavior=behavior)
+
+        # Resolve headroom to its absolute path BEFORE mutating PATH so the
+        # shim dir can dominate PATH without losing the headroom binary.
+        resolved_bin = _resolve_headroom_bin(headroom_bin)
+
+        with with_clean_path([shim_dir]) as env:
+            env["HOME"] = str(home)
+            env["USERPROFILE"] = str(home)
+            env["HEADROOM_E2E_SHIM_LOG"] = str(shim_log)
+            env.update(case.env_extra)
+
+            proc = subprocess.run(
+                [resolved_bin, *case.argv],
+                env=env,
+                cwd=str(project),
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=180,
+            )
+
+        ctx = CaseContext(
+            name=case.name,
+            home=home,
+            project=project,
+            shim_dir=shim_dir,
+            shim_log=shim_log,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            exit_code=proc.returncode,
+        )
+
+        try:
+            assert_exit(proc.returncode, case.expected_exit, context=f"case {case.name}")
+            for needle in case.expected_stdout_contains:
+                assert_stdout_contains(proc.stdout, needle)
+            for needle in case.expected_stderr_contains:
+                assert_stderr_contains(proc.stderr, needle)
+            for spec in case.expected_files:
+                path = _resolve_placeholder(spec, home=home, project=project)
+                if not path.exists():
+                    raise AssertionError(f"Expected file {path} not found")
+            for callback in case.extra_assertions:
+                callback(ctx)
+        except AssertionError as exc:
+            _log(f"FAIL {case.name}: {exc}")
+            if proc.stdout.strip():
+                _log(f"  stdout: {proc.stdout.rstrip()}")
+            if proc.stderr.strip():
+                _log(f"  stderr: {proc.stderr.rstrip()}")
+            return False
+
+        _log(f"PASS {case.name}")
+        return True
+
+
+def _run_in_scratch(
+    case: Case,
+    *,
+    home: Path,
+    project: Path,
+    shim_dir: Path,
+    shim_log: Path,
+    headroom_bin: str,
+) -> bool:
+    """Execute one case inside a pre-existing scratch layout.
+
+    Shims are *added* to ``shim_dir`` (existing shims from prior sequence
+    steps are preserved). This enables sequence cases to build up shim state.
+    """
+
+    for shim_name, behavior in case.shims.items():
+        make_shim(shim_name, shim_dir, behavior=behavior)
+
+    resolved_bin = _resolve_headroom_bin(headroom_bin)
+
+    with with_clean_path([shim_dir]) as env:
+        env["HOME"] = str(home)
+        env["USERPROFILE"] = str(home)
+        env["HEADROOM_E2E_SHIM_LOG"] = str(shim_log)
+        env.update(case.env_extra)
+
+        proc = subprocess.run(
+            [resolved_bin, *case.argv],
+            env=env,
+            cwd=str(project),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=180,
+        )
+
+    ctx = CaseContext(
+        name=case.name,
+        home=home,
+        project=project,
+        shim_dir=shim_dir,
+        shim_log=shim_log,
+        stdout=proc.stdout,
+        stderr=proc.stderr,
+        exit_code=proc.returncode,
+    )
+
+    try:
+        assert_exit(proc.returncode, case.expected_exit, context=f"case {case.name}")
+        for needle in case.expected_stdout_contains:
+            assert_stdout_contains(proc.stdout, needle)
+        for needle in case.expected_stderr_contains:
+            assert_stderr_contains(proc.stderr, needle)
+        for spec in case.expected_files:
+            path = _resolve_placeholder(spec, home=home, project=project)
+            if not path.exists():
+                raise AssertionError(f"Expected file {path} not found")
+        for callback in case.extra_assertions:
+            callback(ctx)
+    except AssertionError as exc:
+        _log(f"FAIL {case.name}: {exc}")
+        if proc.stdout.strip():
+            _log(f"  stdout: {proc.stdout.rstrip()}")
+        if proc.stderr.strip():
+            _log(f"  stderr: {proc.stderr.rstrip()}")
+        return False
+
+    _log(f"PASS {case.name}")
+    return True
+
+
+def run_cases(
+    cases: list[Case],
+    *,
+    headroom_bin: str = "headroom",
+    fail_fast: bool = False,
+) -> int:
+    """Run each case in its own scratch dir. Return exit code (0 = all pass)."""
+
+    passed = 0
+    failed = 0
+    for case in cases:
+        ok = _run_single(case, headroom_bin=headroom_bin)
+        if ok:
+            passed += 1
+        else:
+            failed += 1
+            if fail_fast:
+                break
+
+    _log(f"Summary: {passed} passed, {failed} failed, {len(cases)} total")
+    return 0 if failed == 0 else 1
+
+
+def run_case_sequence(
+    cases: list[Case],
+    *,
+    headroom_bin: str = "headroom",
+    label: str = "sequence",
+    fail_fast: bool = True,
+) -> int:
+    """Run cases sequentially inside a single shared scratch dir.
+
+    Useful when later cases must observe state left by earlier ones (e.g.
+    ``headroom init`` accumulating targets in a shared manifest across
+    successive calls).
+    """
+
+    passed = 0
+    failed = 0
+    with tempfile.TemporaryDirectory(prefix=f"headroom-e2e-{label}-") as temp_raw:
+        temp_root = Path(temp_raw)
+        home = temp_root / "home"
+        project = temp_root / "project"
+        shim_dir = temp_root / "bin"
+        shim_log = temp_root / "shim-log.jsonl"
+        home.mkdir(parents=True)
+        project.mkdir(parents=True)
+
+        for case in cases:
+            ok = _run_in_scratch(
+                case,
+                home=home,
+                project=project,
+                shim_dir=shim_dir,
+                shim_log=shim_log,
+                headroom_bin=headroom_bin,
+            )
+            if ok:
+                passed += 1
+            else:
+                failed += 1
+                if fail_fast:
+                    break
+
+    _log(f"Summary ({label}): {passed} passed, {failed} failed, {len(cases)} total")
+    return 0 if failed == 0 else 1
+
+
+# Allow callers to adopt a different exit strategy (e.g. raising) easily.
+def main_from_cases(cases: list[Case]) -> None:
+    """Convenience entry point for ``run.py`` scripts."""
+
+    code = run_cases(cases)
+    sys.exit(code)
+
+
+__all__ = [
+    "Case",
+    "CaseContext",
+    "main_from_cases",
+    "run_case_sequence",
+    "run_cases",
+]
+
+# Silence unused-import lint for re-exports used by callers.
+_ = os

e2e/_lib/make_shim.ps1

@@ -0,0 +1,24 @@
+# Create a noop executable shim at $Dir\$Name.cmd for use in PATH during
+# native (non-Docker) e2e tests on Windows. Mirrors e2e/_lib/shims.py
+# make_shim(noop).
+#
+# Usage: make_shim.ps1 -Name <name> -Dir <dir>
+
+param(
+    [Parameter(Mandatory = $true)][string]$Name,
+    [Parameter(Mandatory = $true)][string]$Dir
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Test-Path $Dir)) {
+    New-Item -ItemType Directory -Path $Dir -Force | Out-Null
+}
+
+$path = Join-Path $Dir "$Name.cmd"
+$content = @"
+@echo off
+exit /b 0
+"@
+Set-Content -Path $path -Value $content -Encoding ASCII -NoNewline
+Write-Output $path

e2e/_lib/make_shim.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Create a noop executable shim at $2/$1 suitable for use in PATH during
+# native (non-Docker) e2e tests. Mirrors e2e/_lib/shims.py make_shim(noop).
+#
+# Usage: make_shim.sh <name> <dir>
+#
+# Exit codes:
+#   0 on success
+#   2 on usage error
+
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+    echo "usage: $0 <name> <dir>" >&2
+    exit 2
+fi
+
+name="$1"
+dir="$2"
+
+mkdir -p "$dir"
+path="$dir/$name"
+cat >"$path" <<'EOS'
+#!/usr/bin/env bash
+exit 0
+EOS
+chmod +x "$path"
+echo "$path"

e2e/_lib/path_env.py

@@ -0,0 +1,54 @@
+"""PATH environment helpers for e2e test isolation."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+def _minimal_path_dirs() -> list[str]:
+    """Directories always needed so Python / basic shell utilities work."""
+
+    if os.name == "nt":
+        system_root = os.environ.get("SystemRoot", r"C:\Windows")
+        return [
+            rf"{system_root}\System32",
+            system_root,
+            rf"{system_root}\System32\Wbem",
+            rf"{system_root}\System32\WindowsPowerShell\v1.0",
+        ]
+    # POSIX: keep enough for bash, python3, mkdir, chmod, etc.
+    return ["/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]
+
+
+@contextmanager
+def with_clean_path(extra_dirs: list[Path] | None = None) -> Iterator[dict[str, str]]:
+    """Set PATH to a minimal known-good value plus ``extra_dirs``.
+
+    Yields the (already-mutated) environment dict so callers can pass it
+    directly to ``subprocess.run(env=...)``. On exit, the previous PATH is
+    restored.
+    """
+
+    extras = [str(Path(p)) for p in (extra_dirs or [])]
+    new_path = os.pathsep.join(extras + _minimal_path_dirs())
+    env = os.environ.copy()
+    previous = env.get("PATH")
+    env["PATH"] = new_path
+    # Also mutate the real environment so ``shutil.which`` inside this process
+    # sees the clean PATH. Restore on exit.
+    real_previous = os.environ.get("PATH")
+    os.environ["PATH"] = new_path
+    try:
+        yield env
+    finally:
+        if real_previous is None:
+            os.environ.pop("PATH", None)
+        else:
+            os.environ["PATH"] = real_previous
+        if previous is None:
+            env.pop("PATH", None)
+        else:
+            env["PATH"] = previous

e2e/_lib/paths.py

@@ -0,0 +1,47 @@
+"""Per-agent settings-file locators for e2e assertions.
+
+These paths mirror the logic in ``headroom.cli.init`` so e2e tests can
+verify that the right file was written without importing private init
+helpers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+Agent = Literal["claude", "codex", "copilot", "openclaw"]
+Scope = Literal["user", "local"]
+
+
+def agent_settings_path(agent: Agent, *, scope: Scope, home: Path, project: Path) -> Path:
+    """Return the file that ``headroom init`` should have written for ``agent``.
+
+    ``home`` is the test's simulated HOME directory and ``project`` is the cwd
+    used when invoking ``headroom init``. For global (``-g``) invocations only
+    ``home`` matters; for local invocations only ``project`` matters.
+    """
+
+    home = Path(home)
+    project = Path(project)
+
+    if agent == "claude":
+        if scope == "user":
+            return home / ".claude" / "settings.json"
+        return project / ".claude" / "settings.local.json"
+
+    if agent == "codex":
+        if scope == "user":
+            return home / ".codex" / "config.toml"
+        return project / ".codex" / "config.toml"
+
+    if agent == "copilot":
+        # Copilot init requires -g; no local scope.
+        return home / ".copilot" / "config.json"
+
+    if agent == "openclaw":
+        # OpenClaw init is delegated to `headroom wrap openclaw`; it writes
+        # the openclaw json under $HOME.
+        return home / ".openclaw" / "openclaw.json"
+
+    raise ValueError(f"Unknown agent: {agent!r}")

e2e/_lib/shims.py

@@ -0,0 +1,96 @@
+"""Cross-platform agent binary shim factory for e2e tests.
+
+A "shim" is a tiny executable with a given name (e.g. `claude`, `codex`) that
+the harness drops into a temporary directory and prepends to PATH. It lets
+tests drive `headroom init` without requiring a real Claude/Codex install.
+
+Three behaviors are supported:
+
+* ``noop``         — exits 0 with no output. Default.
+* ``fail``         — exits 1 with a short stderr message.
+* ``record-args``  — appends a JSON record of (tool, argv, cwd) to the file at
+                     ``$HEADROOM_E2E_SHIM_LOG``, then exits 0. Useful for
+                     asserting that `init claude` invoked
+                     `claude plugin install` with the right arguments.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Literal
+
+ShimBehavior = Literal["noop", "fail", "record-args"]
+
+_NOOP_SH = """#!/usr/bin/env bash
+exit 0
+"""
+
+_FAIL_SH = """#!/usr/bin/env bash
+echo "${0##*/}: simulated failure" >&2
+exit 1
+"""
+
+_RECORD_SH = """#!/usr/bin/env bash
+tool="${0##*/}"
+log="${HEADROOM_E2E_SHIM_LOG:-/dev/null}"
+mkdir -p "$(dirname "$log")" 2>/dev/null || true
+python3 - "$tool" "$log" "$@" <<'PY'
+import json, os, sys
+tool, log, *argv = sys.argv[1:]
+record = {"tool": tool, "argv": argv, "cwd": os.getcwd()}
+if log != "/dev/null":
+    with open(log, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record) + "\\n")
+print(f"{tool} shim executed")
+PY
+exit 0
+"""
+
+# Windows equivalents. Use `.cmd` so `shutil.which` and PATHEXT find them.
+_NOOP_CMD = "@echo off\r\nexit /b 0\r\n"
+
+_FAIL_CMD = "@echo off\r\necho %~n0: simulated failure 1>&2\r\nexit /b 1\r\n"
+
+_RECORD_CMD = (
+    "@echo off\r\n"
+    "setlocal\r\n"
+    'if "%HEADROOM_E2E_SHIM_LOG%"=="" set HEADROOM_E2E_SHIM_LOG=NUL\r\n'
+    "python -c \"import json,os,sys; name=r'%~n0'; log=os.environ['HEADROOM_E2E_SHIM_LOG']; "
+    "rec={'tool':name,'argv':sys.argv[1:],'cwd':os.getcwd()};\r\n"
+    "open(log,'a',encoding='utf-8').write(json.dumps(rec)+chr(10)) if log!='NUL' else None;\r\n"
+    "print(f'{name} shim executed')\" %*\r\n"
+    "exit /b 0\r\n"
+)
+
+
+def _is_windows() -> bool:
+    return os.name == "nt" or sys.platform == "win32"
+
+
+def make_shim(name: str, dir: Path, behavior: ShimBehavior = "noop") -> Path:
+    """Create an executable shim named ``name`` inside ``dir``.
+
+    Returns the absolute path to the created shim. On POSIX this is a ``.sh``
+    file made executable and named without extension (so ``shutil.which(name)``
+    finds it). On Windows this is a ``.cmd`` file — again, ``shutil.which``
+    honours ``PATHEXT`` and will find it.
+    """
+
+    dir = Path(dir)
+    dir.mkdir(parents=True, exist_ok=True)
+
+    if _is_windows():
+        body = {"noop": _NOOP_CMD, "fail": _FAIL_CMD, "record-args": _RECORD_CMD}[behavior]
+        path = dir / f"{name}.cmd"
+        path.write_text(body, encoding="utf-8")
+        return path
+
+    body = {"noop": _NOOP_SH, "fail": _FAIL_SH, "record-args": _RECORD_SH}[behavior]
+    path = dir / name
+    path.write_text(body, encoding="utf-8")
+    mode = path.stat().st_mode
+    path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return path

e2e/init/Dockerfile

@@ -24,10 +24,15 @@ COPY headroom ./headroom
 COPY .claude-plugin ./.claude-plugin
 COPY .github/plugin ./.github/plugin
 COPY plugins/headroom-agent-hooks ./plugins/headroom-agent-hooks
+# The init e2e harness imports from e2e._lib; both directories must be
+# present and each must contain an __init__.py so Python sees them as
+# packages rooted at /workspace.
+COPY e2e/__init__.py ./e2e/__init__.py
+COPY e2e/_lib ./e2e/_lib
 COPY e2e/init ./e2e/init
 
 RUN python -m venv /opt/headroom-venv && \
-    /opt/headroom-venv/bin/python -m pip install --upgrade pip && \
+    /opt/headroom-venv/bin/python -m pip install --upgrade "pip<25" && \
     /opt/headroom-venv/bin/python -m pip install -e ".[proxy]"
 
 CMD ["python", "e2e/init/run.py"]

e2e/init/run.py

@@ -1,236 +1,336 @@
-from __future__ import annotations
-
-import json
-import os
-import stat
-import subprocess
-import sys
-import tempfile
-import textwrap
-from pathlib import Path
-
-from headroom.cli import init as init_cli
-
-REPO_ROOT = Path("/workspace")
-HEADROOM = "headroom"
-
-
-def log(message: str) -> None:
-    print(f"[init-e2e] {message}", flush=True)
-
-
-def run(
-    cmd: list[str],
-    *,
-    env: dict[str, str],
-    cwd: Path,
-    timeout: int = 180,
-) -> subprocess.CompletedProcess[str]:
-    log(f"$ {' '.join(cmd)}")
-    result = subprocess.run(
-        cmd,
-        env=env,
-        cwd=str(cwd),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        timeout=timeout,
-    )
-    if result.stdout.strip():
-        print(result.stdout.rstrip(), flush=True)
-    if result.stderr.strip():
-        print(result.stderr.rstrip(), file=sys.stderr, flush=True)
-    if result.returncode != 0:
-        raise RuntimeError(f"Command failed with exit code {result.returncode}: {' '.join(cmd)}")
-    return result
-
-
-def assert_true(condition: bool, message: str) -> None:
-    if not condition:
-        raise AssertionError(message)
-
-
-def write_executable(path: Path, content: str) -> None:
-    path.write_text(content, encoding="utf-8")
-    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
-
-
-def read_jsonl(path: Path) -> list[dict[str, object]]:
-    if not path.exists():
-        return []
-    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]
-
-
-def create_agent_shims(shim_dir: Path, log_path: Path) -> None:
-    shim = textwrap.dedent(
-        """\
-        #!/usr/bin/env python3
-        from __future__ import annotations
-
-        import json
-        import os
-        import sys
-        from pathlib import Path
-
-        record = {
-            "tool": Path(sys.argv[0]).name,
-            "argv": sys.argv[1:],
-            "cwd": os.getcwd(),
-        }
-        log_path = Path(os.environ["HEADROOM_INIT_E2E_LOG"])
-        log_path.parent.mkdir(parents=True, exist_ok=True)
-        with log_path.open("a", encoding="utf-8") as handle:
-            handle.write(json.dumps(record) + "\\n")
-        print(f"{record['tool']} shim executed")
-        raise SystemExit(0)
-        """
-    )
-    shim_dir.mkdir(parents=True, exist_ok=True)
-    for name in ("claude", "copilot"):
-        write_executable(shim_dir / name, shim)
-
-
-def expect_hook_command(command: str, profile: str) -> None:
-    assert_true("init hook ensure" in command, f"missing init hook ensure in: {command}")
-    assert_true(f"--profile {profile}" in command, f"missing profile {profile} in: {command}")
-
-
-def read_manifest(home_dir: Path, profile: str) -> dict[str, object]:
-    path = home_dir / ".headroom" / "deploy" / profile / "manifest.json"
-    assert_true(path.exists(), f"Expected manifest at {path}")
-    return json.loads(path.read_text(encoding="utf-8"))
-
-
-def verify_claude_local(home_dir: Path, project_dir: Path, shim_log: Path) -> None:
-    settings = json.loads(
-        (project_dir / ".claude" / "settings.local.json").read_text(encoding="utf-8")
-    )
-    assert_true(
-        settings["env"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9011",
-        "Claude local settings should point at the requested proxy port",
-    )
-    session_start = settings["hooks"]["SessionStart"][0]["hooks"][0]["command"]
-    pre_tool = settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"]
-    profile = init_cli._local_profile(project_dir)
-    expect_hook_command(session_start, profile)
-    expect_hook_command(pre_tool, profile)
-
-    manifest = read_manifest(home_dir, profile)
-    assert_true("claude" in manifest["targets"], "Claude init should register the claude target")
-
-    claude_calls = [record["argv"] for record in read_jsonl(shim_log) if record["tool"] == "claude"]
-    assert_true(
-        claude_calls
-        == [
-            ["plugin", "marketplace", "add", str(REPO_ROOT)],
-            ["plugin", "install", "headroom@headroom-marketplace", "--scope", "local"],
-        ],
-        f"Unexpected Claude install commands: {claude_calls}",
-    )
-
-
-def verify_copilot_global(home_dir: Path, shim_log: Path) -> None:
-    config = json.loads((home_dir / ".copilot" / "config.json").read_text(encoding="utf-8"))
-    assert_true(
-        "SessionStart" in config["hooks"], "Copilot config should include SessionStart hooks"
-    )
-    assert_true("PreToolUse" in config["hooks"], "Copilot config should include PreToolUse hooks")
-    session_start = config["hooks"]["SessionStart"][0]["command"]
-    expect_hook_command(session_start, "init-user")
-
-    for shell_file in (home_dir / ".bashrc", home_dir / ".zshrc", home_dir / ".profile"):
-        content = shell_file.read_text(encoding="utf-8")
-        assert_true(
-            'export COPILOT_PROVIDER_TYPE="openai"' in content,
-            f"{shell_file.name} should contain the Copilot provider type",
-        )
-        assert_true(
-            'export COPILOT_PROVIDER_BASE_URL="http://127.0.0.1:9005/v1"' in content,
-            f"{shell_file.name} should contain the Copilot provider base URL",
-        )
-        assert_true(
-            'export COPILOT_PROVIDER_WIRE_API="completions"' in content,
-            f"{shell_file.name} should contain the Copilot wire API",
-        )
-
-    copilot_calls = [
-        record["argv"] for record in read_jsonl(shim_log) if record["tool"] == "copilot"
-    ]
-    assert_true(
-        copilot_calls
-        == [
-            ["plugin", "marketplace", "add", str(REPO_ROOT)],
-            ["plugin", "install", "headroom@headroom-marketplace"],
-        ],
-        f"Unexpected Copilot install commands: {copilot_calls}",
-    )
-
-
-def verify_codex_local(home_dir: Path, project_dir: Path) -> None:
-    config_path = project_dir / ".codex" / "config.toml"
-    hooks_path = project_dir / ".codex" / "hooks.json"
-    config = config_path.read_text(encoding="utf-8")
-    hooks = json.loads(hooks_path.read_text(encoding="utf-8"))
-    profile = init_cli._local_profile(project_dir)
-
-    assert_true(
-        'base_url = "http://127.0.0.1:9012/v1"' in config,
-        "Codex config should point at the requested proxy port",
-    )
-    assert_true(
-        config.count("[features]") == 1, "Codex config should keep a single [features] table"
-    )
-    assert_true("codex_hooks = true" in config, "Codex config should enable codex_hooks")
-    command = hooks["hooks"]["SessionStart"][0]["hooks"][0]["command"]
-    expect_hook_command(command, profile)
-
-    manifest = read_manifest(home_dir, profile)
-    targets = manifest["targets"]
-    assert_true(set(targets) == {"claude", "codex"}, f"Unexpected merged targets: {targets}")
-
-
-def main() -> None:
-    with tempfile.TemporaryDirectory(prefix="headroom-init-e2e-") as temp_root_raw:
-        temp_root = Path(temp_root_raw)
-        home_dir = temp_root / "home"
-        project_dir = temp_root / "project"
-        shim_dir = temp_root / "bin"
-        shim_log = temp_root / "shim-log.jsonl"
-        home_dir.mkdir(parents=True)
-        project_dir.mkdir(parents=True)
-        create_agent_shims(shim_dir, shim_log)
-
-        env = os.environ.copy()
-        env["HOME"] = str(home_dir)
-        env["USERPROFILE"] = str(home_dir)
-        env["HEADROOM_INIT_E2E_LOG"] = str(shim_log)
-        env["PATH"] = f"{shim_dir}:{env['PATH']}"
-
-        run([HEADROOM, "init", "--port", "9011", "claude"], env=env, cwd=project_dir)
-        verify_claude_local(home_dir, project_dir, shim_log)
-
-        run(
-            [
-                HEADROOM,
-                "init",
-                "-g",
-                "--port",
-                "9005",
-                "--backend",
-                "openai",
-                "copilot",
-            ],
-            env=env,
-            cwd=project_dir,
-        )
-        verify_copilot_global(home_dir, shim_log)
-
-        run([HEADROOM, "init", "--port", "9012", "codex"], env=env, cwd=project_dir)
-        verify_codex_local(home_dir, project_dir)
-
-        log("Init e2e completed successfully")
-
-
-if __name__ == "__main__":
-    main()
+"""Docker e2e cases for ``headroom init``.
+
+Every case is described declaratively with :class:`Case` from
+``e2e/_lib/harness.py``. Three groups run in order:
+
+1. **existing sequence**: preserves the original scenario that exercised
+   ``headroom init claude`` (local) -> ``init -g copilot`` (global) ->
+   ``init codex`` (local), sharing scratch state so manifest-merge is
+   exercised end-to-end.
+2. **bare ``init -g`` detection**: verifies the UX regression from #245
+   stays fixed — both "no shims found" (friendly error, exit 1) and
+   "all shims found" (exit 0, all four agents configured).
+3. **per-subcommand**: one case per ``init -g <agent>`` with only that
+   agent's shim on PATH, so the explicit path is covered independently.
+
+The fourth group covers ``--verbose`` output going to stderr.
+
+Run directly: ``python e2e/init/run.py`` (inside the Docker image built
+from ``e2e/init/Dockerfile``).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+# Add repo root to sys.path so the harness import works whether the file is
+# invoked as ``python e2e/init/run.py`` or ``python -m e2e.init.run``.
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from e2e._lib import (  # noqa: E402
+    Case,
+    CaseContext,
+    run_case_sequence,
+    run_cases,
+)
+from headroom.cli import init as init_cli  # noqa: E402
+
+# ----- helpers reused across cases --------------------------------------------
+
+# Docker image builds the workspace at /workspace; the marketplace source
+# falls back to that repo checkout when a local marketplace manifest is found.
+REPO_ROOT_IN_CONTAINER = Path("/workspace")
+
+
+def _read_jsonl(path: Path) -> list[dict[str, object]]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]
+
+
+def _expect_hook_command(command: str, profile: str) -> None:
+    if "init hook ensure" not in command:
+        raise AssertionError(f"missing 'init hook ensure' in: {command}")
+    if f"--profile {profile}" not in command:
+        raise AssertionError(f"missing '--profile {profile}' in: {command}")
+
+
+def _read_manifest(home: Path, profile: str) -> dict[str, object]:
+    path = home / ".headroom" / "deploy" / profile / "manifest.json"
+    if not path.exists():
+        raise AssertionError(f"Expected manifest at {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+# ----- existing-flow assertions (ported verbatim from the old run.py) ---------
+
+
+def _verify_claude_local(ctx: CaseContext) -> None:
+    settings_path = ctx.project / ".claude" / "settings.local.json"
+    settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    if settings["env"]["ANTHROPIC_BASE_URL"] != "http://127.0.0.1:9011":
+        raise AssertionError(
+            f"Claude local settings should point at port 9011, got "
+            f"{settings['env']['ANTHROPIC_BASE_URL']!r}"
+        )
+    session_start = settings["hooks"]["SessionStart"][0]["hooks"][0]["command"]
+    pre_tool = settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"]
+    profile = init_cli._local_profile(ctx.project)
+    _expect_hook_command(session_start, profile)
+    _expect_hook_command(pre_tool, profile)
+
+    manifest = _read_manifest(ctx.home, profile)
+    if "claude" not in manifest["targets"]:
+        raise AssertionError(
+            f"Claude init should register the claude target, got {manifest['targets']}"
+        )
+
+    claude_calls = [
+        record["argv"] for record in _read_jsonl(ctx.shim_log) if record["tool"] == "claude"
+    ]
+    expected = [
+        ["plugin", "marketplace", "add", str(REPO_ROOT_IN_CONTAINER)],
+        ["plugin", "install", "headroom@headroom-marketplace", "--scope", "local"],
+    ]
+    if claude_calls != expected:
+        raise AssertionError(f"Unexpected Claude install commands: {claude_calls}")
+
+
+def _verify_copilot_global(ctx: CaseContext) -> None:
+    config = json.loads((ctx.home / ".copilot" / "config.json").read_text(encoding="utf-8"))
+    if "SessionStart" not in config["hooks"]:
+        raise AssertionError("Copilot config missing SessionStart hooks")
+    if "PreToolUse" not in config["hooks"]:
+        raise AssertionError("Copilot config missing PreToolUse hooks")
+    session_start = config["hooks"]["SessionStart"][0]["command"]
+    _expect_hook_command(session_start, "init-user")
+
+    for shell_file in (ctx.home / ".bashrc", ctx.home / ".zshrc", ctx.home / ".profile"):
+        content = shell_file.read_text(encoding="utf-8")
+        for literal in (
+            'export COPILOT_PROVIDER_TYPE="openai"',
+            'export COPILOT_PROVIDER_BASE_URL="http://127.0.0.1:9005/v1"',
+            'export COPILOT_PROVIDER_WIRE_API="completions"',
+        ):
+            if literal not in content:
+                raise AssertionError(f"{shell_file.name} missing {literal!r}")
+
+    copilot_calls = [
+        record["argv"] for record in _read_jsonl(ctx.shim_log) if record["tool"] == "copilot"
+    ]
+    expected = [
+        ["plugin", "marketplace", "add", str(REPO_ROOT_IN_CONTAINER)],
+        ["plugin", "install", "headroom@headroom-marketplace"],
+    ]
+    if copilot_calls != expected:
+        raise AssertionError(f"Unexpected Copilot install commands: {copilot_calls}")
+
+
+def _verify_codex_local(ctx: CaseContext) -> None:
+    config = (ctx.project / ".codex" / "config.toml").read_text(encoding="utf-8")
+    hooks = json.loads((ctx.project / ".codex" / "hooks.json").read_text(encoding="utf-8"))
+    profile = init_cli._local_profile(ctx.project)
+
+    if 'base_url = "http://127.0.0.1:9012/v1"' not in config:
+        raise AssertionError("Codex config should point at the requested proxy port (9012)")
+    if config.count("[features]") != 1:
+        raise AssertionError("Codex config should keep a single [features] table")
+    if "codex_hooks = true" not in config:
+        raise AssertionError("Codex config should enable codex_hooks")
+    command = hooks["hooks"]["SessionStart"][0]["hooks"][0]["command"]
+    _expect_hook_command(command, profile)
+
+    manifest = _read_manifest(ctx.home, profile)
+    targets = manifest["targets"]
+    if set(targets) != {"claude", "codex"}:
+        raise AssertionError(f"Unexpected merged targets: {targets}")
+
+
+# ----- new cases (issue #245 fix + per-subcommand coverage) -------------------
+
+
+def _verify_claude_global(ctx: CaseContext) -> None:
+    settings = json.loads((ctx.home / ".claude" / "settings.json").read_text(encoding="utf-8"))
+    if settings["env"]["ANTHROPIC_BASE_URL"] != "http://127.0.0.1:8787":
+        raise AssertionError(
+            f"Claude user settings should default to port 8787, got "
+            f"{settings['env']['ANTHROPIC_BASE_URL']!r}"
+        )
+    _expect_hook_command(
+        settings["hooks"]["SessionStart"][0]["hooks"][0]["command"],
+        init_cli._GLOBAL_PROFILE,
+    )
+
+
+def _verify_codex_global(ctx: CaseContext) -> None:
+    config = (ctx.home / ".codex" / "config.toml").read_text(encoding="utf-8")
+    if 'base_url = "http://127.0.0.1:8787/v1"' not in config:
+        raise AssertionError("Codex user config should point at port 8787 by default")
+    if "codex_hooks = true" not in config:
+        raise AssertionError("Codex user config should enable codex_hooks")
+    hooks = json.loads((ctx.home / ".codex" / "hooks.json").read_text(encoding="utf-8"))
+    _expect_hook_command(
+        hooks["hooks"]["SessionStart"][0]["hooks"][0]["command"],
+        init_cli._GLOBAL_PROFILE,
+    )
+
+
+# ----- case tables ------------------------------------------------------------
+
+
+def existing_sequence_cases() -> list[Case]:
+    """Preserves the original run.py scenario in one shared scratch."""
+
+    return [
+        Case(
+            name="seq_claude_local",
+            argv=["init", "--port", "9011", "claude"],
+            shims={"claude": "record-args", "copilot": "record-args"},
+            expected_exit=0,
+            expected_stdout_contains=["Configured Claude Code (local scope)"],
+            extra_assertions=[_verify_claude_local],
+        ),
+        Case(
+            name="seq_copilot_global",
+            argv=["init", "-g", "--port", "9005", "--backend", "openai", "copilot"],
+            shims={},  # reuse shims from prior case in the sequence
+            expected_exit=0,
+            expected_stdout_contains=["Configured GitHub Copilot CLI (user scope)"],
+            extra_assertions=[_verify_copilot_global],
+        ),
+        Case(
+            name="seq_codex_local",
+            argv=["init", "--port", "9012", "codex"],
+            shims={},
+            expected_exit=0,
+            expected_stdout_contains=["Configured Codex (local scope)"],
+            extra_assertions=[_verify_codex_local],
+        ),
+    ]
+
+
+def bare_init_g_cases() -> list[Case]:
+    """Bare ``headroom init -g`` — the direct coverage of issue #245."""
+
+    return [
+        Case(
+            name="bare_init_g_no_shims",
+            argv=["init", "-g"],
+            shims={},  # nothing on PATH
+            expected_exit=1,
+            expected_stderr_contains=[
+                # every target should be listed so the user knows what was tried
+                "claude",
+                "codex",
+                "copilot",
+                "openclaw",
+                # concrete escape hatch — exactly what the user should type next
+                "headroom init -g claude",
+                # confirm -g itself is still the right flag
+                "-g",
+            ],
+        ),
+        Case(
+            name="bare_init_g_with_all_shims",
+            argv=["init", "-g"],
+            shims={
+                "claude": "record-args",
+                "codex": "noop",
+                "copilot": "record-args",
+                "openclaw": "noop",
+            },
+            expected_exit=0,
+            expected_stdout_contains=[
+                "Configured Claude Code (user scope)",
+                "Configured GitHub Copilot CLI (user scope)",
+                "Configured Codex (user scope)",
+            ],
+        ),
+    ]
+
+
+def per_subcommand_cases() -> list[Case]:
+    """One case per ``headroom init -g <agent>`` with only that agent's shim."""
+
+    return [
+        Case(
+            name="init_g_claude_explicit",
+            argv=["init", "-g", "claude"],
+            shims={"claude": "record-args"},
+            expected_exit=0,
+            expected_stdout_contains=["Configured Claude Code (user scope)"],
+            expected_files=["{home}/.claude/settings.json"],
+            extra_assertions=[_verify_claude_global],
+        ),
+        Case(
+            name="init_g_codex_explicit",
+            argv=["init", "-g", "codex"],
+            shims={"codex": "noop"},
+            expected_exit=0,
+            expected_stdout_contains=["Configured Codex (user scope)"],
+            expected_files=[
+                "{home}/.codex/config.toml",
+                "{home}/.codex/hooks.json",
+            ],
+            extra_assertions=[_verify_codex_global],
+        ),
+        Case(
+            name="init_g_copilot_explicit",
+            argv=["init", "-g", "copilot"],
+            shims={"copilot": "record-args"},
+            expected_exit=0,
+            expected_stdout_contains=["Configured GitHub Copilot CLI (user scope)"],
+            expected_files=["{home}/.copilot/config.json"],
+        ),
+        # openclaw delegates to `headroom wrap openclaw` which has its own
+        # (more expensive) init path and isn't stubbable with a simple shim.
+        # We assert it fails fast with a clear error when not installed, and
+        # rely on the `bare_init_g_with_all_shims` case (which uses a noop
+        # openclaw shim + claude/codex/copilot shims) to cover the success
+        # path alongside the other agents.
+        Case(
+            name="init_g_openclaw_missing",
+            argv=["init", "-g", "openclaw"],
+            shims={},
+            expected_exit=1,
+        ),
+    ]
+
+
+def verbose_cases() -> list[Case]:
+    """Verbose flag smoke tests — debug lines should appear on stderr."""
+
+    return [
+        Case(
+            name="init_verbose_no_shims",
+            argv=["init", "-v", "-g"],
+            shims={},
+            expected_exit=1,
+            expected_stderr_contains=[
+                # A few structural markers from the verbose log. Kept loose so
+                # minor wording tweaks don't break the test.
+                "detect_init_targets",
+                "claude",
+                "global_scope=True",
+            ],
+        ),
+    ]
+
+
+def main() -> None:
+    rc = 0
+    rc |= run_case_sequence(existing_sequence_cases(), label="existing-sequence")
+    rc |= run_cases(bare_init_g_cases())
+    rc |= run_cases(per_subcommand_cases())
+    rc |= run_cases(verbose_cases())
+    if rc != 0:
+        raise SystemExit(rc)
+    print("[e2e] init e2e completed successfully", flush=True)
+
+
+if __name__ == "__main__":
+    main()

headroom/cli/init.py

@@ -1,679 +1,817 @@
-"""Durable agent initialization commands."""
-
-from __future__ import annotations
-
-import json
-import os
-import shlex
-import shutil
-import subprocess
-from hashlib import sha1
-from pathlib import Path
-from typing import Any
-
-import click
-
-from headroom.install.models import ConfigScope, InstallPreset, RuntimeKind, SupervisorKind
-from headroom.install.paths import claude_settings_path, codex_config_path, validate_profile_name
-from headroom.install.planner import build_manifest
-from headroom.install.providers import _apply_unix_env_scope, _apply_windows_env_scope
-from headroom.install.runtime import (
-    resolve_headroom_command,
-    start_detached_agent,
-    start_persistent_docker,
-    stop_runtime,
-    wait_ready,
-)
-from headroom.install.state import load_manifest, save_manifest
-from headroom.install.supervisors import start_supervisor
-
-from .main import main
-
-_GLOBAL_PROFILE = "init-user"
-_CLAUDE_HOOK_MARKER = "headroom-init-claude"
-_COPILOT_HOOK_MARKER = "headroom-init-copilot"
-_CODEX_HOOK_MARKER = "headroom-init-codex"
-_CODEX_PROVIDER_MARKER_START = "# --- Headroom init provider ---"
-_CODEX_PROVIDER_MARKER_END = "# --- end Headroom init provider ---"
-_CODEX_FEATURE_MARKER_START = "# --- Headroom init features ---"
-_CODEX_FEATURE_MARKER_END = "# --- end Headroom init features ---"
-_SUPPORTED_TARGETS = ("claude", "copilot", "codex", "openclaw")
-_LOCAL_TARGETS = {"claude", "codex"}
-_GLOBAL_TARGETS = {"claude", "copilot", "codex", "openclaw"}
-
-
-def _command_string(parts: list[str]) -> str:
-    if os.name == "nt":
-        return subprocess.list2cmdline(parts)
-    return shlex.join(parts)
-
-
-def _hook_command(*parts: str) -> str:
-    return _command_string([*resolve_headroom_command(), "init", "hook", "ensure", *parts])
-
-
-def _powershell_matcher() -> str:
-    return "Bash|PowerShell" if os.name == "nt" else "Bash"
-
-
-def _local_profile(cwd: Path | None = None) -> str:
-    root = (cwd or Path.cwd()).resolve()
-    slug = "".join(ch if ch.isalnum() or ch in "-._" else "-" for ch in root.name.lower()).strip(
-        "-"
-    )
-    digest = sha1(str(root).encode("utf-8")).hexdigest()[:8]
-    return validate_profile_name(f"init-{slug or 'repo'}-{digest}")
-
-
-def _runtime_profile(global_scope: bool, cwd: Path | None = None) -> str:
-    return _GLOBAL_PROFILE if global_scope else _local_profile(cwd)
-
-
-def _copilot_config_path() -> Path:
-    return Path.home() / ".copilot" / "config.json"
-
-
-def _codex_hooks_path(global_scope: bool) -> Path:
-    return (Path.home() if global_scope else Path.cwd()) / ".codex" / "hooks.json"
-
-
-def _claude_scope_path(global_scope: bool) -> Path:
-    if global_scope:
-        return claude_settings_path()
-    return Path.cwd() / ".claude" / "settings.local.json"
-
-
-def _codex_scope_path(global_scope: bool) -> Path:
-    if global_scope:
-        return codex_config_path()
-    return Path.cwd() / ".codex" / "config.toml"
-
-
-def _json_file(path: Path) -> dict[str, Any]:
-    if not path.exists():
-        return {}
-    content = path.read_text(encoding="utf-8").strip()
-    if not content:
-        return {}
-    payload = json.loads(content)
-    return payload if isinstance(payload, dict) else {}
-
-
-def _write_json(path: Path, payload: dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-
-
-def _ensure_claude_hooks(path: Path, profile: str, port: int) -> None:
-    payload = _json_file(path)
-    env_map = dict(payload.get("env") or {}) if isinstance(payload.get("env"), dict) else {}
-    env_map["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"
-    payload["env"] = env_map
-
-    hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
-    command = _hook_command("--profile", profile)
-    for event, matcher in (
-        ("SessionStart", "startup|resume"),
-        ("PreToolUse", _powershell_matcher()),
-    ):
-        entries = list(hooks.get(event) or []) if isinstance(hooks.get(event), list) else []
-        retained: list[dict[str, Any]] = []
-        for entry in entries:
-            if not isinstance(entry, dict):
-                retained.append(entry)
-                continue
-            hook_items = entry.get("hooks")
-            if not isinstance(hook_items, list):
-                retained.append(entry)
-                continue
-            has_headroom = any(
-                isinstance(item, dict)
-                and item.get("command")
-                and _CLAUDE_HOOK_MARKER in str(item.get("command"))
-                for item in hook_items
-            )
-            if not has_headroom:
-                retained.append(entry)
-        retained.append(
-            {
-                "matcher": matcher,
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": f"{command} --marker {_CLAUDE_HOOK_MARKER}",
-                        "timeout": 15,
-                    }
-                ],
-            }
-        )
-        hooks[event] = retained
-    payload["hooks"] = hooks
-    _write_json(path, payload)
-
-
-def _ensure_copilot_hooks(path: Path, profile: str) -> None:
-    payload = _json_file(path)
-    hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
-    command = f"{_hook_command('--profile', profile)} --marker {_COPILOT_HOOK_MARKER}"
-    for event in ("SessionStart", "PreToolUse"):
-        entries = list(hooks.get(event) or []) if isinstance(hooks.get(event), list) else []
-        retained = [
-            entry
-            for entry in entries
-            if not (
-                isinstance(entry, dict) and _COPILOT_HOOK_MARKER in str(entry.get("command", ""))
-            )
-        ]
-        retained.append({"type": "command", "command": command, "cwd": ".", "timeout": 15})
-        hooks[event] = retained
-    payload["hooks"] = hooks
-    _write_json(path, payload)
-
-
-def _replace_marker_block(content: str, marker_start: str, marker_end: str, block: str) -> str:
-    if marker_start in content and marker_end in content:
-        start = content.index(marker_start)
-        end = content.index(marker_end) + len(marker_end)
-        content = content[:start].rstrip() + "\n\n" + content[end:].lstrip()
-    return (content.rstrip() + "\n\n" + block.strip() + "\n").lstrip()
-
-
-def _ensure_codex_provider(path: Path, port: int) -> None:
-    block = (
-        f"{_CODEX_PROVIDER_MARKER_START}\n"
-        'model_provider = "headroom"\n\n'
-        "[model_providers.headroom]\n"
-        'name = "Headroom init proxy"\n'
-        f'base_url = "http://127.0.0.1:{port}/v1"\n'
-        'env_key = "OPENAI_API_KEY"\n'
-        "requires_openai_auth = true\n"
-        "supports_websockets = true\n"
-        f"{_CODEX_PROVIDER_MARKER_END}"
-    )
-    content = path.read_text(encoding="utf-8") if path.exists() else ""
-    content = _replace_marker_block(
-        content, _CODEX_PROVIDER_MARKER_START, _CODEX_PROVIDER_MARKER_END, block
-    )
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content, encoding="utf-8")
-
-
-def _ensure_codex_feature_flag(path: Path) -> None:
-    content = path.read_text(encoding="utf-8") if path.exists() else ""
-    if _CODEX_FEATURE_MARKER_START in content and _CODEX_FEATURE_MARKER_END in content:
-        block = f"{_CODEX_FEATURE_MARKER_START}\ncodex_hooks = true\n{_CODEX_FEATURE_MARKER_END}"
-        content = _replace_marker_block(
-            content,
-            _CODEX_FEATURE_MARKER_START,
-            _CODEX_FEATURE_MARKER_END,
-            block,
-        )
-    elif "[features]" in content:
-        lines = content.splitlines()
-        inserted = False
-        for index, line in enumerate(lines):
-            if line.strip() != "[features]":
-                continue
-            section_end = index + 1
-            while section_end < len(lines) and not (
-                lines[section_end].startswith("[") and lines[section_end].endswith("]")
-            ):
-                if "codex_hooks" in lines[section_end]:
-                    inserted = True
-                    break
-                section_end += 1
-            if not inserted:
-                lines[index + 1 : index + 1] = [
-                    _CODEX_FEATURE_MARKER_START,
-                    "codex_hooks = true",
-                    _CODEX_FEATURE_MARKER_END,
-                ]
-                inserted = True
-            break
-        content = "\n".join(lines).rstrip() + "\n"
-        if not inserted:
-            content = (
-                content.rstrip()
-                + "\n\n[features]\n"
-                + _CODEX_FEATURE_MARKER_START
-                + "\n"
-                + "codex_hooks = true\n"
-                + _CODEX_FEATURE_MARKER_END
-                + "\n"
-            )
-    else:
-        content = (
-            content.rstrip()
-            + "\n\n[features]\n"
-            + _CODEX_FEATURE_MARKER_START
-            + "\n"
-            + "codex_hooks = true\n"
-            + _CODEX_FEATURE_MARKER_END
-            + "\n"
-        ).lstrip()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content, encoding="utf-8")
-
-
-def _ensure_codex_hooks(path: Path, profile: str) -> None:
-    command = f"{_hook_command('--profile', profile)} --marker {_CODEX_HOOK_MARKER}"
-    payload = {
-        "hooks": {
-            "SessionStart": [
-                {
-                    "matcher": "startup|resume",
-                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
-                }
-            ],
-            "PreToolUse": [
-                {
-                    "matcher": "Bash",
-                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
-                }
-            ],
-        }
-    }
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-
-
-def _manifest_changed(
-    existing: Any,
-    *,
-    port: int,
-    backend: str,
-    anyllm_provider: str | None,
-    region: str | None,
-    memory: bool,
-) -> bool:
-    return any(
-        [
-            getattr(existing, "port", port) != port,
-            getattr(existing, "backend", backend) != backend,
-            getattr(existing, "anyllm_provider", anyllm_provider) != anyllm_provider,
-            getattr(existing, "region", region) != region,
-            getattr(existing, "memory_enabled", memory) != memory,
-        ]
-    )
-
-
-def _ensure_runtime_manifest(
-    *,
-    global_scope: bool,
-    targets: list[str],
-    port: int,
-    backend: str,
-    anyllm_provider: str | None,
-    region: str | None,
-    memory: bool,
-) -> str:
-    profile = _runtime_profile(global_scope)
-    existing = load_manifest(profile)
-    merged_targets = sorted(set(existing.targets if existing else []).union(targets))
-    manifest = build_manifest(
-        profile=profile,
-        preset=InstallPreset.PERSISTENT_TASK.value,
-        runtime_kind=RuntimeKind.PYTHON.value,
-        scope=ConfigScope.USER.value,
-        provider_mode="manual",
-        targets=merged_targets,
-        port=port,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-        proxy_mode="token",
-        memory_enabled=memory,
-        telemetry_enabled=True,
-        image="ghcr.io/chopratejas/headroom:latest",
-    )
-    manifest.supervisor_kind = SupervisorKind.NONE.value
-    manifest.artifacts = []
-    manifest.mutations = existing.mutations if existing else []
-    if existing is not None and _manifest_changed(
-        existing,
-        port=port,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-        memory=memory,
-    ):
-        try:
-            stop_runtime(existing)
-        except Exception:
-            pass
-    save_manifest(manifest)
-    return profile
-
-
-def _env_manifest(values: dict[str, str]) -> Any:
-    return build_manifest(
-        profile="init-env",
-        preset=InstallPreset.PERSISTENT_TASK.value,
-        runtime_kind=RuntimeKind.PYTHON.value,
-        scope=ConfigScope.USER.value,
-        provider_mode="manual",
-        targets=["copilot"],
-        port=8787,
-        backend="anthropic",
-        anyllm_provider=None,
-        region=None,
-        proxy_mode="token",
-        memory_enabled=False,
-        telemetry_enabled=True,
-        image="ghcr.io/chopratejas/headroom:latest",
-    )
-
-
-def _apply_user_env(values: dict[str, str]) -> None:
-    manifest = _env_manifest(values)
-    manifest.base_env = {}
-    manifest.tool_envs = {"copilot": values}
-    if os.name == "nt":
-        _apply_windows_env_scope(manifest)
-    else:
-        _apply_unix_env_scope(manifest)
-
-
-def _resolve_copilot_env(port: int, backend: str) -> dict[str, str]:
-    if backend == "anthropic":
-        return {
-            "COPILOT_PROVIDER_TYPE": "anthropic",
-            "COPILOT_PROVIDER_BASE_URL": f"http://127.0.0.1:{port}",
-        }
-    return {
-        "COPILOT_PROVIDER_TYPE": "openai",
-        "COPILOT_PROVIDER_BASE_URL": f"http://127.0.0.1:{port}/v1",
-        "COPILOT_PROVIDER_WIRE_API": "completions",
-    }
-
-
-def _marketplace_source() -> str:
-    override = os.environ.get("HEADROOM_MARKETPLACE_SOURCE")
-    if override:
-        return override
-    repo_root = Path(__file__).resolve().parents[2]
-    if (repo_root / ".claude-plugin" / "marketplace.json").exists():
-        return str(repo_root)
-    return "chopratejas/headroom"
-
-
-def _run_checked(command: list[str], *, action: str) -> None:
-    result = subprocess.run(
-        command,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-    )
-    if result.returncode == 0:
-        return
-    detail = "\n".join(part for part in (result.stderr.strip(), result.stdout.strip()) if part)
-    if "already" in detail.lower() or "exists" in detail.lower():
-        return
-    raise click.ClickException(f"{action} failed: {detail or result.returncode}")
-
-
-def _install_claude_marketplace(scope: str) -> None:
-    claude_bin = shutil.which("claude")
-    if not claude_bin:
-        raise click.ClickException("'claude' not found in PATH. Install Claude Code first.")
-    source = _marketplace_source()
-    _run_checked(
-        [claude_bin, "plugin", "marketplace", "add", source], action="claude marketplace add"
-    )
-    _run_checked(
-        [claude_bin, "plugin", "install", "headroom@headroom-marketplace", "--scope", scope],
-        action="claude plugin install",
-    )
-
-
-def _install_copilot_marketplace() -> None:
-    copilot_bin = shutil.which("copilot")
-    if not copilot_bin:
-        raise click.ClickException("'copilot' not found in PATH. Install GitHub Copilot CLI first.")
-    source = _marketplace_source()
-    _run_checked(
-        [copilot_bin, "plugin", "marketplace", "add", source],
-        action="copilot marketplace add",
-    )
-    _run_checked(
-        [copilot_bin, "plugin", "install", "headroom@headroom-marketplace"],
-        action="copilot plugin install",
-    )
-
-
-def _ensure_profile_running(profile: str) -> None:
-    manifest = load_manifest(profile)
-    if manifest is None:
-        return
-    if wait_ready(manifest, timeout_seconds=1):
-        return
-    try:
-        if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-            start_persistent_docker(manifest)
-        elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:
-            start_supervisor(manifest)
-        else:
-            start_detached_agent(manifest.profile)
-        wait_ready(manifest, timeout_seconds=45)
-    except Exception:
-        return
-
-
-def detect_init_targets(global_scope: bool) -> list[str]:
-    allowed = _GLOBAL_TARGETS if global_scope else _LOCAL_TARGETS
-    detected: list[str] = []
-    for target in _SUPPORTED_TARGETS:
-        if target not in allowed:
-            continue
-        if shutil.which(target):
-            detected.append(target)
-    return detected
-
-
-def _init_claude(*, global_scope: bool, profile: str, port: int) -> None:
-    _ensure_claude_hooks(_claude_scope_path(global_scope), profile, port)
-    _install_claude_marketplace("user" if global_scope else "local")
-    click.echo(f"Configured Claude Code ({'user' if global_scope else 'local'} scope).")
-    click.echo("Restart Claude Code to activate Headroom hooks and provider routing.")
-
-
-def _init_copilot(*, global_scope: bool, profile: str, port: int, backend: str) -> None:
-    if not global_scope:
-        raise click.ClickException(
-            "Copilot durable init currently requires -g (current-user scope)."
-        )
-    _ensure_copilot_hooks(_copilot_config_path(), profile)
-    _apply_user_env(_resolve_copilot_env(port, backend))
-    _install_copilot_marketplace()
-    click.echo("Configured GitHub Copilot CLI (user scope).")
-    click.echo("Restart Copilot CLI to activate Headroom hooks and provider routing.")
-
-
-def _init_codex(*, global_scope: bool, profile: str, port: int) -> None:
-    config_path = _codex_scope_path(global_scope)
-    _ensure_codex_provider(config_path, port)
-    _ensure_codex_feature_flag(config_path)
-    _ensure_codex_hooks(_codex_hooks_path(global_scope), profile)
-    click.echo(f"Configured Codex ({'user' if global_scope else 'local'} scope).")
-    if os.name == "nt":
-        click.echo(
-            "Codex hooks are currently disabled upstream on Windows; provider routing was still installed."
-        )
-    click.echo("Restart Codex to activate Headroom configuration.")
-
-
-def _init_openclaw(*, global_scope: bool, port: int) -> None:
-    if not global_scope:
-        raise click.ClickException(
-            "OpenClaw durable init currently requires -g (current-user scope)."
-        )
-    command = [*resolve_headroom_command(), "wrap", "openclaw", "--proxy-port", str(port)]
-    result = subprocess.run(command)
-    if result.returncode != 0:
-        raise SystemExit(result.returncode)
-
-
-def _run_init_targets(
-    *,
-    targets: list[str],
-    global_scope: bool,
-    port: int,
-    backend: str,
-    anyllm_provider: str | None,
-    region: str | None,
-    memory: bool,
-) -> None:
-    runtime_targets = [target for target in targets if target != "openclaw"]
-    profile = _ensure_runtime_manifest(
-        global_scope=global_scope,
-        targets=runtime_targets,
-        port=port,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-        memory=memory,
-    )
-    for target in targets:
-        if target == "claude":
-            _init_claude(global_scope=global_scope, profile=profile, port=port)
-        elif target == "copilot":
-            _init_copilot(global_scope=global_scope, profile=profile, port=port, backend=backend)
-        elif target == "codex":
-            _init_codex(global_scope=global_scope, profile=profile, port=port)
-        elif target == "openclaw":
-            _init_openclaw(global_scope=global_scope, port=port)
-
-
-@main.group(invoke_without_command=True)
-@click.option("-g", "--global", "global_scope", is_flag=True, help="Install for the current user.")
-@click.option("--port", default=8787, type=int, show_default=True, help="Headroom proxy port.")
-@click.option("--backend", default="anthropic", show_default=True, help="Proxy backend.")
-@click.option("--anyllm-provider", default=None, help="Provider for any-llm backends.")
-@click.option("--region", default=None, help="Cloud region for Bedrock / Vertex style backends.")
-@click.option("--memory", is_flag=True, help="Enable persistent memory in the proxy runtime.")
-@click.pass_context
-def init(
-    ctx: click.Context,
-    global_scope: bool,
-    port: int,
-    backend: str,
-    anyllm_provider: str | None,
-    region: str | None,
-    memory: bool,
-) -> None:
-    """Install durable Headroom integrations for supported agents."""
-    if ctx.invoked_subcommand is not None:
-        ctx.obj = {
-            "global_scope": global_scope,
-            "port": port,
-            "backend": backend,
-            "anyllm_provider": anyllm_provider,
-            "region": region,
-            "memory": memory,
-        }
-        return
-
-    targets = detect_init_targets(global_scope)
-    if not targets:
-        scope_label = "user" if global_scope else "local"
-        raise click.ClickException(
-            f"No supported {scope_label} init targets were auto-detected. Specify one explicitly."
-        )
-    _run_init_targets(
-        targets=targets,
-        global_scope=global_scope,
-        port=port,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-        memory=memory,
-    )
-
-
-def _ctx_value(ctx: click.Context, key: str) -> Any:
-    return (ctx.obj or {}).get(key)
-
-
-@init.command("claude")
-@click.pass_context
-def init_claude(ctx: click.Context) -> None:
-    """Install Claude Code durable hooks and provider routing."""
-    _run_init_targets(
-        targets=["claude"],
-        global_scope=bool(_ctx_value(ctx, "global_scope")),
-        port=int(_ctx_value(ctx, "port") or 8787),
-        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
-        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
-        region=_ctx_value(ctx, "region"),
-        memory=bool(_ctx_value(ctx, "memory")),
-    )
-
-
-@init.command("copilot")
-@click.pass_context
-def init_copilot(ctx: click.Context) -> None:
-    """Install GitHub Copilot CLI durable hooks and provider routing."""
-    _run_init_targets(
-        targets=["copilot"],
-        global_scope=bool(_ctx_value(ctx, "global_scope")),
-        port=int(_ctx_value(ctx, "port") or 8787),
-        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
-        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
-        region=_ctx_value(ctx, "region"),
-        memory=bool(_ctx_value(ctx, "memory")),
-    )
-
-
-@init.command("codex")
-@click.pass_context
-def init_codex(ctx: click.Context) -> None:
-    """Install Codex durable hooks and provider routing."""
-    _run_init_targets(
-        targets=["codex"],
-        global_scope=bool(_ctx_value(ctx, "global_scope")),
-        port=int(_ctx_value(ctx, "port") or 8787),
-        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
-        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
-        region=_ctx_value(ctx, "region"),
-        memory=bool(_ctx_value(ctx, "memory")),
-    )
-
-
-@init.command("openclaw")
-@click.pass_context
-def init_openclaw(ctx: click.Context) -> None:
-    """Install the durable OpenClaw Headroom plugin."""
-    _run_init_targets(
-        targets=["openclaw"],
-        global_scope=bool(_ctx_value(ctx, "global_scope")),
-        port=int(_ctx_value(ctx, "port") or 8787),
-        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
-        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
-        region=_ctx_value(ctx, "region"),
-        memory=bool(_ctx_value(ctx, "memory")),
-    )
-
-
-@init.group("hook", hidden=True)
-def init_hook() -> None:
-    """Internal hook helpers."""
-
-
-@init_hook.command("ensure")
-@click.option("--profile", default=None, help="Explicit deployment profile to ensure.")
-@click.option("--marker", default=None, hidden=True)
-def init_hook_ensure(profile: str | None, marker: str | None) -> None:
-    """Best-effort ensure used by installed agent hooks."""
-    del marker
-    profiles: list[str] = []
-    if profile:
-        profiles.append(profile)
-    else:
-        local_profile = _local_profile()
-        if load_manifest(local_profile) is not None:
-            profiles.append(local_profile)
-        elif load_manifest(_GLOBAL_PROFILE) is not None:
-            profiles.append(_GLOBAL_PROFILE)
-    for name in profiles:
-        _ensure_profile_running(name)
+"""Durable agent initialization commands."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from hashlib import sha1
+from pathlib import Path
+from typing import Any
+
+import click
+
+from headroom.install.models import ConfigScope, InstallPreset, RuntimeKind, SupervisorKind
+from headroom.install.paths import claude_settings_path, codex_config_path, validate_profile_name
+from headroom.install.planner import build_manifest
+from headroom.install.providers import _apply_unix_env_scope, _apply_windows_env_scope
+from headroom.install.runtime import (
+    resolve_headroom_command,
+    start_detached_agent,
+    start_persistent_docker,
+    stop_runtime,
+    wait_ready,
+)
+from headroom.install.state import load_manifest, save_manifest
+from headroom.install.supervisors import start_supervisor
+
+from .main import main
+
+logger = logging.getLogger(__name__)
+
+_VERBOSE_HANDLER_ATTR = "_headroom_init_verbose_handler"
+
+_GLOBAL_PROFILE = "init-user"
+_CLAUDE_HOOK_MARKER = "headroom-init-claude"
+_COPILOT_HOOK_MARKER = "headroom-init-copilot"
+_CODEX_HOOK_MARKER = "headroom-init-codex"
+_CODEX_PROVIDER_MARKER_START = "# --- Headroom init provider ---"
+_CODEX_PROVIDER_MARKER_END = "# --- end Headroom init provider ---"
+_CODEX_FEATURE_MARKER_START = "# --- Headroom init features ---"
+_CODEX_FEATURE_MARKER_END = "# --- end Headroom init features ---"
+_SUPPORTED_TARGETS = ("claude", "copilot", "codex", "openclaw")
+_LOCAL_TARGETS = {"claude", "codex"}
+_GLOBAL_TARGETS = {"claude", "copilot", "codex", "openclaw"}
+
+
+def _command_string(parts: list[str]) -> str:
+    if os.name == "nt":
+        return subprocess.list2cmdline(parts)
+    return shlex.join(parts)
+
+
+def _hook_command(*parts: str) -> str:
+    return _command_string([*resolve_headroom_command(), "init", "hook", "ensure", *parts])
+
+
+def _powershell_matcher() -> str:
+    return "Bash|PowerShell" if os.name == "nt" else "Bash"
+
+
+def _enable_verbose_logging() -> None:
+    """Attach a stderr handler to the init logger at DEBUG level.
+
+    Idempotent: calling this multiple times in one process (e.g. when nested
+    subcommands are invoked) leaves exactly one handler attached. Does NOT
+    mutate stdout; all verbose output goes to stderr so ``headroom init``
+    can still be composed in pipes that consume stdout.
+    """
+
+    if getattr(logger, _VERBOSE_HANDLER_ATTR, None) is not None:
+        return
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(logging.Formatter("[headroom init] %(message)s"))
+    handler.setLevel(logging.DEBUG)
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+    setattr(logger, _VERBOSE_HANDLER_ATTR, handler)
+
+
+def _local_profile(cwd: Path | None = None) -> str:
+    root = (cwd or Path.cwd()).resolve()
+    slug = "".join(ch if ch.isalnum() or ch in "-._" else "-" for ch in root.name.lower()).strip(
+        "-"
+    )
+    digest = sha1(str(root).encode("utf-8")).hexdigest()[:8]
+    return validate_profile_name(f"init-{slug or 'repo'}-{digest}")
+
+
+def _runtime_profile(global_scope: bool, cwd: Path | None = None) -> str:
+    return _GLOBAL_PROFILE if global_scope else _local_profile(cwd)
+
+
+def _copilot_config_path() -> Path:
+    return Path.home() / ".copilot" / "config.json"
+
+
+def _codex_hooks_path(global_scope: bool) -> Path:
+    return (Path.home() if global_scope else Path.cwd()) / ".codex" / "hooks.json"
+
+
+def _claude_scope_path(global_scope: bool) -> Path:
+    if global_scope:
+        return claude_settings_path()
+    return Path.cwd() / ".claude" / "settings.local.json"
+
+
+def _codex_scope_path(global_scope: bool) -> Path:
+    if global_scope:
+        return codex_config_path()
+    return Path.cwd() / ".codex" / "config.toml"
+
+
+def _json_file(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    content = path.read_text(encoding="utf-8").strip()
+    if not content:
+        return {}
+    payload = json.loads(content)
+    return payload if isinstance(payload, dict) else {}
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    logger.debug("write json: %s (keys=%s)", path, sorted(payload.keys()))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _ensure_claude_hooks(path: Path, profile: str, port: int) -> None:
+    logger.debug("ensure claude hooks: %s (profile=%s, port=%s)", path, profile, port)
+    payload = _json_file(path)
+    env_map = dict(payload.get("env") or {}) if isinstance(payload.get("env"), dict) else {}
+    env_map["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"
+    payload["env"] = env_map
+
+    hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
+    command = _hook_command("--profile", profile)
+    for event, matcher in (
+        ("SessionStart", "startup|resume"),
+        ("PreToolUse", _powershell_matcher()),
+    ):
+        entries = list(hooks.get(event) or []) if isinstance(hooks.get(event), list) else []
+        retained: list[dict[str, Any]] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                retained.append(entry)
+                continue
+            hook_items = entry.get("hooks")
+            if not isinstance(hook_items, list):
+                retained.append(entry)
+                continue
+            has_headroom = any(
+                isinstance(item, dict)
+                and item.get("command")
+                and _CLAUDE_HOOK_MARKER in str(item.get("command"))
+                for item in hook_items
+            )
+            if not has_headroom:
+                retained.append(entry)
+        retained.append(
+            {
+                "matcher": matcher,
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f"{command} --marker {_CLAUDE_HOOK_MARKER}",
+                        "timeout": 15,
+                    }
+                ],
+            }
+        )
+        hooks[event] = retained
+    payload["hooks"] = hooks
+    _write_json(path, payload)
+
+
+def _ensure_copilot_hooks(path: Path, profile: str) -> None:
+    logger.debug("ensure copilot hooks: %s (profile=%s)", path, profile)
+    payload = _json_file(path)
+    hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
+    command = f"{_hook_command('--profile', profile)} --marker {_COPILOT_HOOK_MARKER}"
+    for event in ("SessionStart", "PreToolUse"):
+        entries = list(hooks.get(event) or []) if isinstance(hooks.get(event), list) else []
+        retained = [
+            entry
+            for entry in entries
+            if not (
+                isinstance(entry, dict) and _COPILOT_HOOK_MARKER in str(entry.get("command", ""))
+            )
+        ]
+        retained.append({"type": "command", "command": command, "cwd": ".", "timeout": 15})
+        hooks[event] = retained
+    payload["hooks"] = hooks
+    _write_json(path, payload)
+
+
+def _replace_marker_block(content: str, marker_start: str, marker_end: str, block: str) -> str:
+    if marker_start in content and marker_end in content:
+        start = content.index(marker_start)
+        end = content.index(marker_end) + len(marker_end)
+        content = content[:start].rstrip() + "\n\n" + content[end:].lstrip()
+    return (content.rstrip() + "\n\n" + block.strip() + "\n").lstrip()
+
+
+def _ensure_codex_provider(path: Path, port: int) -> None:
+    logger.debug("ensure codex provider block: %s (port=%s)", path, port)
+    block = (
+        f"{_CODEX_PROVIDER_MARKER_START}\n"
+        'model_provider = "headroom"\n\n'
+        "[model_providers.headroom]\n"
+        'name = "Headroom init proxy"\n'
+        f'base_url = "http://127.0.0.1:{port}/v1"\n'
+        'env_key = "OPENAI_API_KEY"\n'
+        "requires_openai_auth = true\n"
+        "supports_websockets = true\n"
+        f"{_CODEX_PROVIDER_MARKER_END}"
+    )
+    content = path.read_text(encoding="utf-8") if path.exists() else ""
+    content = _replace_marker_block(
+        content, _CODEX_PROVIDER_MARKER_START, _CODEX_PROVIDER_MARKER_END, block
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _ensure_codex_feature_flag(path: Path) -> None:
+    content = path.read_text(encoding="utf-8") if path.exists() else ""
+    if _CODEX_FEATURE_MARKER_START in content and _CODEX_FEATURE_MARKER_END in content:
+        block = f"{_CODEX_FEATURE_MARKER_START}\ncodex_hooks = true\n{_CODEX_FEATURE_MARKER_END}"
+        content = _replace_marker_block(
+            content,
+            _CODEX_FEATURE_MARKER_START,
+            _CODEX_FEATURE_MARKER_END,
+            block,
+        )
+    elif "[features]" in content:
+        lines = content.splitlines()
+        inserted = False
+        for index, line in enumerate(lines):
+            if line.strip() != "[features]":
+                continue
+            section_end = index + 1
+            while section_end < len(lines) and not (
+                lines[section_end].startswith("[") and lines[section_end].endswith("]")
+            ):
+                if "codex_hooks" in lines[section_end]:
+                    inserted = True
+                    break
+                section_end += 1
+            if not inserted:
+                lines[index + 1 : index + 1] = [
+                    _CODEX_FEATURE_MARKER_START,
+                    "codex_hooks = true",
+                    _CODEX_FEATURE_MARKER_END,
+                ]
+                inserted = True
+            break
+        content = "\n".join(lines).rstrip() + "\n"
+        if not inserted:
+            content = (
+                content.rstrip()
+                + "\n\n[features]\n"
+                + _CODEX_FEATURE_MARKER_START
+                + "\n"
+                + "codex_hooks = true\n"
+                + _CODEX_FEATURE_MARKER_END
+                + "\n"
+            )
+    else:
+        content = (
+            content.rstrip()
+            + "\n\n[features]\n"
+            + _CODEX_FEATURE_MARKER_START
+            + "\n"
+            + "codex_hooks = true\n"
+            + _CODEX_FEATURE_MARKER_END
+            + "\n"
+        ).lstrip()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _ensure_codex_hooks(path: Path, profile: str) -> None:
+    logger.debug("ensure codex hooks: %s (profile=%s)", path, profile)
+    command = f"{_hook_command('--profile', profile)} --marker {_CODEX_HOOK_MARKER}"
+    payload = {
+        "hooks": {
+            "SessionStart": [
+                {
+                    "matcher": "startup|resume",
+                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
+                }
+            ],
+            "PreToolUse": [
+                {
+                    "matcher": "Bash",
+                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
+                }
+            ],
+        }
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _manifest_changed(
+    existing: Any,
+    *,
+    port: int,
+    backend: str,
+    anyllm_provider: str | None,
+    region: str | None,
+    memory: bool,
+) -> bool:
+    return any(
+        [
+            getattr(existing, "port", port) != port,
+            getattr(existing, "backend", backend) != backend,
+            getattr(existing, "anyllm_provider", anyllm_provider) != anyllm_provider,
+            getattr(existing, "region", region) != region,
+            getattr(existing, "memory_enabled", memory) != memory,
+        ]
+    )
+
+
+def _ensure_runtime_manifest(
+    *,
+    global_scope: bool,
+    targets: list[str],
+    port: int,
+    backend: str,
+    anyllm_provider: str | None,
+    region: str | None,
+    memory: bool,
+) -> str:
+    profile = _runtime_profile(global_scope)
+    existing = load_manifest(profile)
+    merged_targets = sorted(set(existing.targets if existing else []).union(targets))
+    manifest = build_manifest(
+        profile=profile,
+        preset=InstallPreset.PERSISTENT_TASK.value,
+        runtime_kind=RuntimeKind.PYTHON.value,
+        scope=ConfigScope.USER.value,
+        provider_mode="manual",
+        targets=merged_targets,
+        port=port,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+        proxy_mode="token",
+        memory_enabled=memory,
+        telemetry_enabled=True,
+        image="ghcr.io/chopratejas/headroom:latest",
+    )
+    manifest.supervisor_kind = SupervisorKind.NONE.value
+    manifest.artifacts = []
+    manifest.mutations = existing.mutations if existing else []
+    if existing is not None and _manifest_changed(
+        existing,
+        port=port,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+        memory=memory,
+    ):
+        try:
+            stop_runtime(existing)
+        except Exception:
+            pass
+    save_manifest(manifest)
+    return profile
+
+
+def _env_manifest(values: dict[str, str]) -> Any:
+    return build_manifest(
+        profile="init-env",
+        preset=InstallPreset.PERSISTENT_TASK.value,
+        runtime_kind=RuntimeKind.PYTHON.value,
+        scope=ConfigScope.USER.value,
+        provider_mode="manual",
+        targets=["copilot"],
+        port=8787,
+        backend="anthropic",
+        anyllm_provider=None,
+        region=None,
+        proxy_mode="token",
+        memory_enabled=False,
+        telemetry_enabled=True,
+        image="ghcr.io/chopratejas/headroom:latest",
+    )
+
+
+def _apply_user_env(values: dict[str, str]) -> None:
+    manifest = _env_manifest(values)
+    manifest.base_env = {}
+    manifest.tool_envs = {"copilot": values}
+    scope = "windows" if os.name == "nt" else "unix"
+    logger.debug("apply user env scope=%s keys=%s", scope, sorted(values.keys()))
+    if os.name == "nt":
+        _apply_windows_env_scope(manifest)
+    else:
+        _apply_unix_env_scope(manifest)
+
+
+def _resolve_copilot_env(port: int, backend: str) -> dict[str, str]:
+    if backend == "anthropic":
+        return {
+            "COPILOT_PROVIDER_TYPE": "anthropic",
+            "COPILOT_PROVIDER_BASE_URL": f"http://127.0.0.1:{port}",
+        }
+    return {
+        "COPILOT_PROVIDER_TYPE": "openai",
+        "COPILOT_PROVIDER_BASE_URL": f"http://127.0.0.1:{port}/v1",
+        "COPILOT_PROVIDER_WIRE_API": "completions",
+    }
+
+
+def _marketplace_source() -> str:
+    override = os.environ.get("HEADROOM_MARKETPLACE_SOURCE")
+    if override:
+        return override
+    repo_root = Path(__file__).resolve().parents[2]
+    if (repo_root / ".claude-plugin" / "marketplace.json").exists():
+        return str(repo_root)
+    return "chopratejas/headroom"
+
+
+def _run_checked(command: list[str], *, action: str) -> None:
+    logger.debug("subprocess [%s]: %s", action, _command_string(command))
+    result = subprocess.run(
+        command,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    logger.debug(
+        "subprocess [%s] exit=%s stdout=%r stderr=%r",
+        action,
+        result.returncode,
+        result.stdout[:200],
+        result.stderr[:200],
+    )
+    if result.returncode == 0:
+        return
+    detail = "\n".join(part for part in (result.stderr.strip(), result.stdout.strip()) if part)
+    if "already" in detail.lower() or "exists" in detail.lower():
+        logger.debug(
+            "subprocess [%s] non-zero exit tolerated ('already'/'exists' detected)", action
+        )
+        return
+    raise click.ClickException(f"{action} failed: {detail or result.returncode}")
+
+
+def _install_claude_marketplace(scope: str) -> None:
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        raise click.ClickException("'claude' not found in PATH. Install Claude Code first.")
+    source = _marketplace_source()
+    _run_checked(
+        [claude_bin, "plugin", "marketplace", "add", source], action="claude marketplace add"
+    )
+    _run_checked(
+        [claude_bin, "plugin", "install", "headroom@headroom-marketplace", "--scope", scope],
+        action="claude plugin install",
+    )
+
+
+def _install_copilot_marketplace() -> None:
+    copilot_bin = shutil.which("copilot")
+    if not copilot_bin:
+        raise click.ClickException("'copilot' not found in PATH. Install GitHub Copilot CLI first.")
+    source = _marketplace_source()
+    _run_checked(
+        [copilot_bin, "plugin", "marketplace", "add", source],
+        action="copilot marketplace add",
+    )
+    _run_checked(
+        [copilot_bin, "plugin", "install", "headroom@headroom-marketplace"],
+        action="copilot plugin install",
+    )
+
+
+def _ensure_profile_running(profile: str) -> None:
+    manifest = load_manifest(profile)
+    if manifest is None:
+        return
+    if wait_ready(manifest, timeout_seconds=1):
+        return
+    try:
+        if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+            start_persistent_docker(manifest)
+        elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:
+            start_supervisor(manifest)
+        else:
+            start_detached_agent(manifest.profile)
+        wait_ready(manifest, timeout_seconds=45)
+    except Exception:
+        return
+
+
+def _probe_init_targets(global_scope: bool) -> list[tuple[str, str | None]]:
+    """Return ``[(target, which_result)]`` for every in-scope supported target.
+
+    ``which_result`` is the absolute path reported by :func:`shutil.which`, or
+    ``None`` when the binary is not on PATH. Callers use the list both to
+    build an auto-detected target list and to produce a diagnostic error
+    message when nothing was found.
+    """
+
+    allowed = _GLOBAL_TARGETS if global_scope else _LOCAL_TARGETS
+    logger.debug(
+        "detect_init_targets: global_scope=%s allowed=%s",
+        global_scope,
+        sorted(allowed),
+    )
+    probes: list[tuple[str, str | None]] = []
+    for target in _SUPPORTED_TARGETS:
+        if target not in allowed:
+            continue
+        path = shutil.which(target)
+        logger.debug("detect_init_targets: shutil.which(%r) -> %s", target, path or "None")
+        probes.append((target, path))
+    return probes
+
+
+def detect_init_targets(global_scope: bool) -> list[str]:
+    """Return agent names in scope for which a binary was found on PATH."""
+
+    return [name for name, path in _probe_init_targets(global_scope) if path]
+
+
+def _format_empty_detection_error(global_scope: bool) -> str:
+    """Build the error message shown when no in-scope targets were detected.
+
+    Lists every agent that was probed, what ``shutil.which`` returned, and
+    confirms how to proceed explicitly — including that the ``-g`` / ``--global``
+    flag the user tried is still valid.
+    """
+
+    probes = _probe_init_targets(global_scope)
+    scope_flag = "-g" if global_scope else ""
+    scope_label = "user" if global_scope else "local"
+
+    lines: list[str] = [
+        f"No supported {scope_label}-scope agents were found on PATH.",
+        "",
+        "Headroom probed the following agents via shutil.which():",
+    ]
+    for name, path in probes:
+        status = f"found at {path}" if path else "not found"
+        lines.append(f"  - {name}: {status}")
+
+    lines.extend(
+        [
+            "",
+            f"The {scope_flag or '--local (no flag)'} option is still supported; "
+            "headroom init just needs to know which agent to target.",
+            "Install the agent you want first, then re-run with an explicit target:",
+            "",
+        ]
+    )
+    for name, _path in probes:
+        flag = " -g" if global_scope else ""
+        lines.append(f"  headroom init{flag} {name}")
+
+    lines.extend(
+        [
+            "",
+            "Tip: run `headroom init --help` to see all options.",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _init_claude(*, global_scope: bool, profile: str, port: int) -> None:
+    _ensure_claude_hooks(_claude_scope_path(global_scope), profile, port)
+    _install_claude_marketplace("user" if global_scope else "local")
+    click.echo(f"Configured Claude Code ({'user' if global_scope else 'local'} scope).")
+    click.echo("Restart Claude Code to activate Headroom hooks and provider routing.")
+
+
+def _init_copilot(*, global_scope: bool, profile: str, port: int, backend: str) -> None:
+    if not global_scope:
+        raise click.ClickException(
+            "Copilot durable init currently requires -g (current-user scope)."
+        )
+    _ensure_copilot_hooks(_copilot_config_path(), profile)
+    _apply_user_env(_resolve_copilot_env(port, backend))
+    _install_copilot_marketplace()
+    click.echo("Configured GitHub Copilot CLI (user scope).")
+    click.echo("Restart Copilot CLI to activate Headroom hooks and provider routing.")
+
+
+def _init_codex(*, global_scope: bool, profile: str, port: int) -> None:
+    config_path = _codex_scope_path(global_scope)
+    _ensure_codex_provider(config_path, port)
+    _ensure_codex_feature_flag(config_path)
+    _ensure_codex_hooks(_codex_hooks_path(global_scope), profile)
+    click.echo(f"Configured Codex ({'user' if global_scope else 'local'} scope).")
+    if os.name == "nt":
+        click.echo(
+            "Codex hooks are currently disabled upstream on Windows; provider routing was still installed."
+        )
+    click.echo("Restart Codex to activate Headroom configuration.")
+
+
+def _init_openclaw(*, global_scope: bool, port: int) -> None:
+    if not global_scope:
+        raise click.ClickException(
+            "OpenClaw durable init currently requires -g (current-user scope)."
+        )
+    command = [*resolve_headroom_command(), "wrap", "openclaw", "--proxy-port", str(port)]
+    result = subprocess.run(command)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+
+def _run_init_targets(
+    *,
+    targets: list[str],
+    global_scope: bool,
+    port: int,
+    backend: str,
+    anyllm_provider: str | None,
+    region: str | None,
+    memory: bool,
+) -> None:
+    logger.debug(
+        "run_init_targets: targets=%s global_scope=%s port=%s backend=%s memory=%s",
+        targets,
+        global_scope,
+        port,
+        backend,
+        memory,
+    )
+    runtime_targets = [target for target in targets if target != "openclaw"]
+    profile = _ensure_runtime_manifest(
+        global_scope=global_scope,
+        targets=runtime_targets,
+        port=port,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+        memory=memory,
+    )
+    logger.debug("run_init_targets: using profile=%s", profile)
+    for target in targets:
+        logger.debug("run_init_targets: dispatching -> %s", target)
+        if target == "claude":
+            _init_claude(global_scope=global_scope, profile=profile, port=port)
+        elif target == "copilot":
+            _init_copilot(global_scope=global_scope, profile=profile, port=port, backend=backend)
+        elif target == "codex":
+            _init_codex(global_scope=global_scope, profile=profile, port=port)
+        elif target == "openclaw":
+            _init_openclaw(global_scope=global_scope, port=port)
+
+
+@main.group(invoke_without_command=True)
+@click.option("-g", "--global", "global_scope", is_flag=True, help="Install for the current user.")
+@click.option("--port", default=8787, type=int, show_default=True, help="Headroom proxy port.")
+@click.option("--backend", default="anthropic", show_default=True, help="Proxy backend.")
+@click.option("--anyllm-provider", default=None, help="Provider for any-llm backends.")
+@click.option("--region", default=None, help="Cloud region for Bedrock / Vertex style backends.")
+@click.option("--memory", is_flag=True, help="Enable persistent memory in the proxy runtime.")
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Emit debug-level diagnostics to stderr (flag values, shutil.which results, "
+    "file paths touched, subprocess invocations and exit codes).",
+)
+@click.pass_context
+def init(
+    ctx: click.Context,
+    global_scope: bool,
+    port: int,
+    backend: str,
+    anyllm_provider: str | None,
+    region: str | None,
+    memory: bool,
+    verbose: bool,
+) -> None:
+    """Install durable Headroom integrations for supported agents."""
+    if verbose:
+        _enable_verbose_logging()
+    logger.debug(
+        "init: global_scope=%s port=%s backend=%s anyllm_provider=%s region=%s memory=%s "
+        "invoked_subcommand=%s",
+        global_scope,
+        port,
+        backend,
+        anyllm_provider,
+        region,
+        memory,
+        ctx.invoked_subcommand,
+    )
+    if ctx.invoked_subcommand is not None:
+        ctx.obj = {
+            "global_scope": global_scope,
+            "port": port,
+            "backend": backend,
+            "anyllm_provider": anyllm_provider,
+            "region": region,
+            "memory": memory,
+            "verbose": verbose,
+        }
+        return
+
+    targets = detect_init_targets(global_scope)
+    if not targets:
+        logger.debug("init: detect_init_targets returned empty; exiting with guided error")
+        raise click.ClickException(_format_empty_detection_error(global_scope))
+    logger.debug("init: detected targets=%s", targets)
+    _run_init_targets(
+        targets=targets,
+        global_scope=global_scope,
+        port=port,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+        memory=memory,
+    )
+
+
+def _ctx_value(ctx: click.Context, key: str) -> Any:
+    return (ctx.obj or {}).get(key)
+
+
+@init.command("claude")
+@click.pass_context
+def init_claude(ctx: click.Context) -> None:
+    """Install Claude Code durable hooks and provider routing."""
+    _run_init_targets(
+        targets=["claude"],
+        global_scope=bool(_ctx_value(ctx, "global_scope")),
+        port=int(_ctx_value(ctx, "port") or 8787),
+        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
+        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
+        region=_ctx_value(ctx, "region"),
+        memory=bool(_ctx_value(ctx, "memory")),
+    )
+
+
+@init.command("copilot")
+@click.pass_context
+def init_copilot(ctx: click.Context) -> None:
+    """Install GitHub Copilot CLI durable hooks and provider routing."""
+    _run_init_targets(
+        targets=["copilot"],
+        global_scope=bool(_ctx_value(ctx, "global_scope")),
+        port=int(_ctx_value(ctx, "port") or 8787),
+        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
+        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
+        region=_ctx_value(ctx, "region"),
+        memory=bool(_ctx_value(ctx, "memory")),
+    )
+
+
+@init.command("codex")
+@click.pass_context
+def init_codex(ctx: click.Context) -> None:
+    """Install Codex durable hooks and provider routing."""
+    _run_init_targets(
+        targets=["codex"],
+        global_scope=bool(_ctx_value(ctx, "global_scope")),
+        port=int(_ctx_value(ctx, "port") or 8787),
+        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
+        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
+        region=_ctx_value(ctx, "region"),
+        memory=bool(_ctx_value(ctx, "memory")),
+    )
+
+
+@init.command("openclaw")
+@click.pass_context
+def init_openclaw(ctx: click.Context) -> None:
+    """Install the durable OpenClaw Headroom plugin."""
+    _run_init_targets(
+        targets=["openclaw"],
+        global_scope=bool(_ctx_value(ctx, "global_scope")),
+        port=int(_ctx_value(ctx, "port") or 8787),
+        backend=str(_ctx_value(ctx, "backend") or "anthropic"),
+        anyllm_provider=_ctx_value(ctx, "anyllm_provider"),
+        region=_ctx_value(ctx, "region"),
+        memory=bool(_ctx_value(ctx, "memory")),
+    )
+
+
+@init.group("hook", hidden=True)
+def init_hook() -> None:
+    """Internal hook helpers."""
+
+
+@init_hook.command("ensure")
+@click.option("--profile", default=None, help="Explicit deployment profile to ensure.")
+@click.option("--marker", default=None, hidden=True)
+def init_hook_ensure(profile: str | None, marker: str | None) -> None:
+    """Best-effort ensure used by installed agent hooks."""
+    del marker
+    profiles: list[str] = []
+    if profile:
+        profiles.append(profile)
+    else:
+        local_profile = _local_profile()
+        if load_manifest(local_profile) is not None:
+            profiles.append(local_profile)
+        elif load_manifest(_GLOBAL_PROFILE) is not None:
+            profiles.append(_GLOBAL_PROFILE)
+    for name in profiles:
+        _ensure_profile_running(name)

headroom/cli/tools.py

@@ -34,6 +34,10 @@ _PASSTHROUGH_CTX = {
 }
 
 
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
 def _exec_tool(tool: str, argv: Sequence[str]) -> None:
     try:
         path = binaries.resolve(tool)
@@ -58,7 +62,7 @@ def _exec_tool(tool: str, argv: Sequence[str]) -> None:
     # that needs to clean up on shell exit must be handled elsewhere (e.g.
     # the parent `headroom` process, not these thin passthroughs).
     cmd = [str(path), *argv]
-    if os.name == "posix":
+    if not _is_windows():
         os.execv(cmd[0], cmd)  # never returns
     else:
         completed = subprocess.run(cmd, check=False)

headroom/compress.py

@@ -1,347 +1,347 @@
-"""One-function compression API for Headroom.
-
-The simplest way to use Headroom — no proxy, no config, just compress:
-
-    from headroom import compress
-
-    result = compress(messages, model="claude-sonnet-4-5-20250929")
-    result.messages          # Compressed messages (same format, fewer tokens)
-    result.tokens_saved      # Tokens saved
-    result.compression_ratio # e.g., 0.35 means 65% saved
-
-Works with any LLM client, any proxy, any framework. Just compress
-the messages before sending them.
-
-Examples:
-
-    # With Anthropic SDK
-    from anthropic import Anthropic
-    from headroom import compress
-
-    client = Anthropic()
-    messages = [{"role": "user", "content": huge_tool_output}]
-    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
-    response = client.messages.create(
-        model="claude-sonnet-4-5-20250929",
-        messages=compressed.messages,
-    )
-
-    # With OpenAI SDK
-    from openai import OpenAI
-    from headroom import compress
-
-    client = OpenAI()
-    messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]
-    compressed = compress(messages, model="gpt-4o")
-    response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
-
-    # With LiteLLM
-    import litellm
-    from headroom import compress
-
-    messages = [...]
-    compressed = compress(messages, model="bedrock/claude-sonnet")
-    response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)
-
-    # With any HTTP client
-    import httpx
-    from headroom import compress
-
-    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
-    httpx.post("https://api.anthropic.com/v1/messages", json={
-        "model": "claude-sonnet-4-5-20250929",
-        "messages": compressed.messages,
-    })
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from dataclasses import dataclass, field
-from typing import Any
-
-from .observability import get_otel_metrics
-from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers
-from .utils import extract_user_query as _extract_user_query
-
-logger = logging.getLogger(__name__)
-
-
-# Lazy-initialized singleton pipeline
-_pipeline = None
-_pipeline_lock = threading.Lock()
-
-
-@dataclass
-class CompressConfig:
-    """User-facing compression options.
-
-    Controls what gets compressed, how aggressively, and with which model.
-    Pass to ``compress()`` or any integration that uses headroom.
-
-    Examples::
-
-        # Coding agent (default — skip user messages, protect recent)
-        compress(messages, model="gpt-4o")
-
-        # Financial document (compress everything, keep 50%)
-        compress(messages, model="claude-opus-4-20250514",
-            compress_user_messages=True,
-            target_ratio=0.5,
-            protect_recent=0,
-        )
-
-        # Aggressive (logs, search results)
-        compress(messages, model="gpt-4o", target_ratio=0.2)
-    """
-
-    # What to compress
-    compress_user_messages: bool = False
-    """Compress user messages too (default: skip them for coding agents).
-    Set True for document compression, RAG pipelines, or when user messages
-    contain large tool outputs."""
-
-    compress_system_messages: bool = True
-    """Compress system messages (default: True).
-    Set False to preserve system prompts exactly as-is. Useful for voice
-    agents where tool definitions and instructions must not be altered."""
-
-    protect_recent: int = 4
-    """Don't compress the last N messages (they're the active conversation).
-    Set 0 to compress everything."""
-
-    protect_analysis_context: bool = True
-    """Detect 'analyze'/'review' intent and protect code from compression."""
-
-    # How aggressive
-    target_ratio: float | None = None
-    """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).
-    0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).
-    Only affects Kompress (text compression). SmartCrusher (JSON) has its
-    own logic based on array dedup."""
-
-    min_tokens_to_compress: int = 250
-    """Minimum token count for a message to be compressed.
-    Messages shorter than this are left unchanged. Default 250.
-    Set lower for voice agents where turns are short."""
-
-    # Model variant
-    kompress_model: str | None = None
-    """Kompress model ID. None = default (chopratejas/kompress-base).
-    Set to a HuggingFace model ID for domain-specific compression.
-    Set to 'disabled' to skip ML compression entirely
-    (only SmartCrusher + CacheAligner will run)."""
-
-
-@dataclass
-class CompressResult:
-    """Result of compressing messages.
-
-    Attributes:
-        messages: The compressed messages (same format as input).
-        tokens_before: Token count before compression.
-        tokens_after: Token count after compression.
-        tokens_saved: Tokens removed by compression.
-        compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).
-        transforms_applied: List of transforms that were applied.
-    """
-
-    messages: list[dict[str, Any]]
-    tokens_before: int = 0
-    tokens_after: int = 0
-    tokens_saved: int = 0
-    compression_ratio: float = 0.0
-    transforms_applied: list[str] = field(default_factory=list)
-
-
-def compress(
-    messages: list[dict[str, Any]],
-    model: str = "claude-sonnet-4-5-20250929",
-    model_limit: int = 200000,
-    optimize: bool = True,
-    hooks: Any = None,
-    config: CompressConfig | None = None,
-    **kwargs: Any,
-) -> CompressResult:
-    """Compress messages using Headroom's full compression pipeline.
-
-    This is the simplest way to use Headroom. No proxy, no config needed.
-    Just pass messages and get compressed messages back.
-
-    Args:
-        messages: List of messages in Anthropic or OpenAI format.
-        model: Model name (used for token counting and context limit).
-        model_limit: Model's context window size in tokens.
-        optimize: Whether to actually compress (False = passthrough for A/B testing).
-        hooks: Optional CompressionHooks instance for custom behavior.
-        config: Compression options (CompressConfig). Overrides defaults.
-        **kwargs: Shorthand for CompressConfig fields. These override config:
-            compress_user_messages, target_ratio, protect_recent,
-            protect_analysis_context, kompress_model.
-
-    Returns:
-        CompressResult with compressed messages and metrics.
-
-    Examples::
-
-        # Default (coding agent)
-        result = compress(messages, model="gpt-4o")
-
-        # Financial document (keep 50%, compress everything)
-        result = compress(messages, model="claude-opus-4-20250514",
-            compress_user_messages=True,
-            target_ratio=0.5,
-            protect_recent=0,
-        )
-    """
-    if not messages or not optimize:
-        return CompressResult(messages=messages)
-
-    # Build config from explicit config + kwargs
-    cfg = config or CompressConfig()
-    config_fields = {f.name for f in cfg.__dataclass_fields__.values()}
-    for key, value in kwargs.items():
-        if key in config_fields:
-            setattr(cfg, key, value)
-
-    pipeline = _get_pipeline()
-    pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)
-
-    try:
-        # Compute biases from hooks if provided
-        biases = None
-        if hooks:
-            from headroom.hooks import CompressContext
-
-            ctx = CompressContext(model=model)
-            messages = hooks.pre_compress(messages, ctx)
-            biases = hooks.compute_biases(messages, ctx)
-
-        received_event = pipeline_extensions.emit(
-            PipelineStage.INPUT_RECEIVED,
-            operation="compress",
-            model=model,
-            messages=messages,
-        )
-        if received_event.messages is not None:
-            messages = received_event.messages
-
-        # Extract user query from messages so transforms can score by
-        # relevance.  Without this, SmartCrusher selects items by statistics
-        # alone (position, anomaly) and may drop relevant content.
-        context = _extract_user_query(messages)
-
-        result = pipeline.apply(
-            messages=messages,
-            model=model,
-            model_limit=model_limit,
-            context=context,
-            biases=biases,
-            # Pass CompressConfig options through to transforms
-            compress_user_messages=cfg.compress_user_messages,
-            compress_system_messages=cfg.compress_system_messages,
-            target_ratio=cfg.target_ratio,
-            protect_recent=cfg.protect_recent,
-            protect_analysis_context=cfg.protect_analysis_context,
-            min_tokens_to_compress=cfg.min_tokens_to_compress,
-            kompress_model=cfg.kompress_model,
-        )
-
-        tokens_before = result.tokens_before
-        tokens_after = result.tokens_after
-        compressed_messages = result.messages
-
-        routing_markers = summarize_routing_markers(result.transforms_applied)
-        if routing_markers:
-            routed_event = pipeline_extensions.emit(
-                PipelineStage.INPUT_ROUTED,
-                operation="compress",
-                model=model,
-                messages=compressed_messages,
-                metadata={
-                    "routing_markers": routing_markers,
-                    "transforms_applied": result.transforms_applied,
-                },
-            )
-            if routed_event.messages is not None:
-                compressed_messages = routed_event.messages
-
-        compressed_event = pipeline_extensions.emit(
-            PipelineStage.INPUT_COMPRESSED,
-            operation="compress",
-            model=model,
-            messages=compressed_messages,
-            metadata={
-                "tokens_before": tokens_before,
-                "tokens_after": tokens_after,
-                "transforms_applied": result.transforms_applied,
-            },
-        )
-        if compressed_event.messages is not None:
-            compressed_messages = compressed_event.messages
-
-        tokens_saved = tokens_before - tokens_after
-        ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0
-
-        # Post-compress hook
-        if hooks and tokens_saved > 0:
-            from headroom.hooks import CompressEvent
-
-            hooks.post_compress(
-                CompressEvent(
-                    tokens_before=tokens_before,
-                    tokens_after=tokens_after,
-                    tokens_saved=tokens_saved,
-                    compression_ratio=ratio,
-                    transforms_applied=result.transforms_applied,
-                    model=model,
-                )
-            )
-
-        return CompressResult(
-            messages=compressed_messages,
-            tokens_before=tokens_before,
-            tokens_after=tokens_after,
-            tokens_saved=tokens_saved,
-            compression_ratio=ratio,
-            transforms_applied=result.transforms_applied,
-        )
-
-    except Exception as e:
-        get_otel_metrics().record_compression_failure(
-            model=model,
-            operation="compress",
-            error_type=type(e).__name__,
-        )
-        logger.warning("Compression failed, returning original messages: %s", e)
-        return CompressResult(
-            messages=messages,
-            tokens_before=0,
-            tokens_after=0,
-            tokens_saved=0,
-            compression_ratio=0.0,
-        )
-
-
-def _get_pipeline() -> Any:
-    """Get or create the singleton compression pipeline."""
-    global _pipeline
-
-    if _pipeline is not None:
-        return _pipeline
-
-    with _pipeline_lock:
-        if _pipeline is not None:
-            return _pipeline
-
-        from headroom.transforms import TransformPipeline
-
-        # Default pipeline: CacheAligner → ContentRouter → IntelligentContext
-        # CacheAligner: stabilizes prefix for provider KV cache hits
-        # ContentRouter: routes to the right compressor per content type
-        #   (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)
-        # IntelligentContext: enforces token limits with score-based dropping
-        _pipeline = TransformPipeline()
-        logger.debug("Headroom compression pipeline initialized")
-        return _pipeline
+"""One-function compression API for Headroom.
+
+The simplest way to use Headroom — no proxy, no config, just compress:
+
+    from headroom import compress
+
+    result = compress(messages, model="claude-sonnet-4-5-20250929")
+    result.messages          # Compressed messages (same format, fewer tokens)
+    result.tokens_saved      # Tokens saved
+    result.compression_ratio # e.g., 0.35 means 65% saved
+
+Works with any LLM client, any proxy, any framework. Just compress
+the messages before sending them.
+
+Examples:
+
+    # With Anthropic SDK
+    from anthropic import Anthropic
+    from headroom import compress
+
+    client = Anthropic()
+    messages = [{"role": "user", "content": huge_tool_output}]
+    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
+    response = client.messages.create(
+        model="claude-sonnet-4-5-20250929",
+        messages=compressed.messages,
+    )
+
+    # With OpenAI SDK
+    from openai import OpenAI
+    from headroom import compress
+
+    client = OpenAI()
+    messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]
+    compressed = compress(messages, model="gpt-4o")
+    response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
+
+    # With LiteLLM
+    import litellm
+    from headroom import compress
+
+    messages = [...]
+    compressed = compress(messages, model="bedrock/claude-sonnet")
+    response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)
+
+    # With any HTTP client
+    import httpx
+    from headroom import compress
+
+    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
+    httpx.post("https://api.anthropic.com/v1/messages", json={
+        "model": "claude-sonnet-4-5-20250929",
+        "messages": compressed.messages,
+    })
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from .observability import get_otel_metrics
+from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers
+from .utils import extract_user_query as _extract_user_query
+
+logger = logging.getLogger(__name__)
+
+
+# Lazy-initialized singleton pipeline
+_pipeline = None
+_pipeline_lock = threading.Lock()
+
+
+@dataclass
+class CompressConfig:
+    """User-facing compression options.
+
+    Controls what gets compressed, how aggressively, and with which model.
+    Pass to ``compress()`` or any integration that uses headroom.
+
+    Examples::
+
+        # Coding agent (default — skip user messages, protect recent)
+        compress(messages, model="gpt-4o")
+
+        # Financial document (compress everything, keep 50%)
+        compress(messages, model="claude-opus-4-20250514",
+            compress_user_messages=True,
+            target_ratio=0.5,
+            protect_recent=0,
+        )
+
+        # Aggressive (logs, search results)
+        compress(messages, model="gpt-4o", target_ratio=0.2)
+    """
+
+    # What to compress
+    compress_user_messages: bool = False
+    """Compress user messages too (default: skip them for coding agents).
+    Set True for document compression, RAG pipelines, or when user messages
+    contain large tool outputs."""
+
+    compress_system_messages: bool = True
+    """Compress system messages (default: True).
+    Set False to preserve system prompts exactly as-is. Useful for voice
+    agents where tool definitions and instructions must not be altered."""
+
+    protect_recent: int = 4
+    """Don't compress the last N messages (they're the active conversation).
+    Set 0 to compress everything."""
+
+    protect_analysis_context: bool = True
+    """Detect 'analyze'/'review' intent and protect code from compression."""
+
+    # How aggressive
+    target_ratio: float | None = None
+    """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).
+    0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).
+    Only affects Kompress (text compression). SmartCrusher (JSON) has its
+    own logic based on array dedup."""
+
+    min_tokens_to_compress: int = 250
+    """Minimum token count for a message to be compressed.
+    Messages shorter than this are left unchanged. Default 250.
+    Set lower for voice agents where turns are short."""
+
+    # Model variant
+    kompress_model: str | None = None
+    """Kompress model ID. None = default (chopratejas/kompress-base).
+    Set to a HuggingFace model ID for domain-specific compression.
+    Set to 'disabled' to skip ML compression entirely
+    (only SmartCrusher + CacheAligner will run)."""
+
+
+@dataclass
+class CompressResult:
+    """Result of compressing messages.
+
+    Attributes:
+        messages: The compressed messages (same format as input).
+        tokens_before: Token count before compression.
+        tokens_after: Token count after compression.
+        tokens_saved: Tokens removed by compression.
+        compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).
+        transforms_applied: List of transforms that were applied.
+    """
+
+    messages: list[dict[str, Any]]
+    tokens_before: int = 0
+    tokens_after: int = 0
+    tokens_saved: int = 0
+    compression_ratio: float = 0.0
+    transforms_applied: list[str] = field(default_factory=list)
+
+
+def compress(
+    messages: list[dict[str, Any]],
+    model: str = "claude-sonnet-4-5-20250929",
+    model_limit: int = 200000,
+    optimize: bool = True,
+    hooks: Any = None,
+    config: CompressConfig | None = None,
+    **kwargs: Any,
+) -> CompressResult:
+    """Compress messages using Headroom's full compression pipeline.
+
+    This is the simplest way to use Headroom. No proxy, no config needed.
+    Just pass messages and get compressed messages back.
+
+    Args:
+        messages: List of messages in Anthropic or OpenAI format.
+        model: Model name (used for token counting and context limit).
+        model_limit: Model's context window size in tokens.
+        optimize: Whether to actually compress (False = passthrough for A/B testing).
+        hooks: Optional CompressionHooks instance for custom behavior.
+        config: Compression options (CompressConfig). Overrides defaults.
+        **kwargs: Shorthand for CompressConfig fields. These override config:
+            compress_user_messages, target_ratio, protect_recent,
+            protect_analysis_context, kompress_model.
+
+    Returns:
+        CompressResult with compressed messages and metrics.
+
+    Examples::
+
+        # Default (coding agent)
+        result = compress(messages, model="gpt-4o")
+
+        # Financial document (keep 50%, compress everything)
+        result = compress(messages, model="claude-opus-4-20250514",
+            compress_user_messages=True,
+            target_ratio=0.5,
+            protect_recent=0,
+        )
+    """
+    if not messages or not optimize:
+        return CompressResult(messages=messages)
+
+    # Build config from explicit config + kwargs
+    cfg = config or CompressConfig()
+    config_fields = {f.name for f in cfg.__dataclass_fields__.values()}
+    for key, value in kwargs.items():
+        if key in config_fields:
+            setattr(cfg, key, value)
+
+    pipeline = _get_pipeline()
+    pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)
+
+    try:
+        # Compute biases from hooks if provided
+        biases = None
+        if hooks:
+            from headroom.hooks import CompressContext
+
+            ctx = CompressContext(model=model)
+            messages = hooks.pre_compress(messages, ctx)
+            biases = hooks.compute_biases(messages, ctx)
+
+        received_event = pipeline_extensions.emit(
+            PipelineStage.INPUT_RECEIVED,
+            operation="compress",
+            model=model,
+            messages=messages,
+        )
+        if received_event.messages is not None:
+            messages = received_event.messages
+
+        # Extract user query from messages so transforms can score by
+        # relevance.  Without this, SmartCrusher selects items by statistics
+        # alone (position, anomaly) and may drop relevant content.
+        context = _extract_user_query(messages)
+
+        result = pipeline.apply(
+            messages=messages,
+            model=model,
+            model_limit=model_limit,
+            context=context,
+            biases=biases,
+            # Pass CompressConfig options through to transforms
+            compress_user_messages=cfg.compress_user_messages,
+            compress_system_messages=cfg.compress_system_messages,
+            target_ratio=cfg.target_ratio,
+            protect_recent=cfg.protect_recent,
+            protect_analysis_context=cfg.protect_analysis_context,
+            min_tokens_to_compress=cfg.min_tokens_to_compress,
+            kompress_model=cfg.kompress_model,
+        )
+
+        tokens_before = result.tokens_before
+        tokens_after = result.tokens_after
+        compressed_messages = result.messages
+
+        routing_markers = summarize_routing_markers(result.transforms_applied)
+        if routing_markers:
+            routed_event = pipeline_extensions.emit(
+                PipelineStage.INPUT_ROUTED,
+                operation="compress",
+                model=model,
+                messages=compressed_messages,
+                metadata={
+                    "routing_markers": routing_markers,
+                    "transforms_applied": result.transforms_applied,
+                },
+            )
+            if routed_event.messages is not None:
+                compressed_messages = routed_event.messages
+
+        compressed_event = pipeline_extensions.emit(
+            PipelineStage.INPUT_COMPRESSED,
+            operation="compress",
+            model=model,
+            messages=compressed_messages,
+            metadata={
+                "tokens_before": tokens_before,
+                "tokens_after": tokens_after,
+                "transforms_applied": result.transforms_applied,
+            },
+        )
+        if compressed_event.messages is not None:
+            compressed_messages = compressed_event.messages
+
+        tokens_saved = tokens_before - tokens_after
+        ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0
+
+        # Post-compress hook
+        if hooks and tokens_saved > 0:
+            from headroom.hooks import CompressEvent
+
+            hooks.post_compress(
+                CompressEvent(
+                    tokens_before=tokens_before,
+                    tokens_after=tokens_after,
+                    tokens_saved=tokens_saved,
+                    compression_ratio=ratio,
+                    transforms_applied=result.transforms_applied,
+                    model=model,
+                )
+            )
+
+        return CompressResult(
+            messages=compressed_messages,
+            tokens_before=tokens_before,
+            tokens_after=tokens_after,
+            tokens_saved=tokens_saved,
+            compression_ratio=ratio,
+            transforms_applied=result.transforms_applied,
+        )
+
+    except Exception as e:
+        get_otel_metrics().record_compression_failure(
+            model=model,
+            operation="compress",
+            error_type=type(e).__name__,
+        )
+        logger.warning("Compression failed, returning original messages: %s", e)
+        return CompressResult(
+            messages=messages,
+            tokens_before=0,
+            tokens_after=0,
+            tokens_saved=0,
+            compression_ratio=0.0,
+        )
+
+
+def _get_pipeline() -> Any:
+    """Get or create the singleton compression pipeline."""
+    global _pipeline
+
+    if _pipeline is not None:
+        return _pipeline
+
+    with _pipeline_lock:
+        if _pipeline is not None:
+            return _pipeline
+
+        from headroom.transforms import TransformPipeline
+
+        # Default pipeline: CacheAligner → ContentRouter → IntelligentContext
+        # CacheAligner: stabilizes prefix for provider KV cache hits
+        # ContentRouter: routes to the right compressor per content type
+        #   (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)
+        # IntelligentContext: enforces token limits with score-based dropping
+        _pipeline = TransformPipeline()
+        logger.debug("Headroom compression pipeline initialized")
+        return _pipeline

headroom/copilot_auth.py

@@ -1,444 +1,444 @@
-"""GitHub Copilot OAuth discovery and API-token exchange helpers."""
-
-from __future__ import annotations
-
-import asyncio
-import ctypes
-import json
-import logging
-import os
-import subprocess
-import time
-from ctypes import wintypes
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-from urllib import error as urllib_error
-from urllib import request as urllib_request
-from urllib.parse import urlparse
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_API_URL = "https://api.githubcopilot.com"
-DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"
-DEFAULT_GITHUB_HOST = "github.com"
-_TOKEN_EXPIRY_BUFFER_S = 60
-_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"
-_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"
-
-_API_TOKEN_ENV_VARS = (
-    "GITHUB_COPILOT_API_TOKEN",
-    "COPILOT_PROVIDER_BEARER_TOKEN",
-)
-_OAUTH_TOKEN_ENV_VARS = (
-    "GITHUB_COPILOT_GITHUB_TOKEN",
-    "GITHUB_COPILOT_TOKEN",
-    "GITHUB_TOKEN",
-    "COPILOT_GITHUB_TOKEN",
-)
-_OAUTH_TOKEN_KEYS = (
-    "oauth_token",
-    "oauthToken",
-    "token",
-    "access_token",
-    "accessToken",
-)
-_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")
-
-
-@dataclass(frozen=True)
-class CopilotAPIToken:
-    """Short-lived API token exchanged from a GitHub OAuth token."""
-
-    token: str
-    expires_at: float
-    api_url: str = DEFAULT_API_URL
-    refresh_in: int | None = None
-    sku: str | None = None
-
-    @property
-    def is_valid(self) -> bool:
-        return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)
-
-
-def _github_host() -> str:
-    return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()
-
-
-def _token_exchange_url() -> str:
-    return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()
-
-
-def _should_exchange_oauth_token() -> bool:
-    raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()
-    return raw in {"1", "true", "yes", "on"}
-
-
-def _resolve_token_file_paths() -> list[Path]:
-    override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()
-    if override:
-        return [Path(override).expanduser()]
-
-    paths: list[Path] = []
-    local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
-    if local_appdata:
-        base = Path(local_appdata) / "github-copilot"
-        paths.extend([base / "apps.json", base / "hosts.json"])
-
-    config_base = Path.home() / ".config" / "github-copilot"
-    paths.extend([config_base / "apps.json", config_base / "hosts.json"])
-    return paths
-
-
-def _read_gh_cli_oauth_token() -> str | None:
-    gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"
-    command = [gh_bin, "auth", "token"]
-    host = _github_host()
-    if host and host != DEFAULT_GITHUB_HOST:
-        command.extend(["--hostname", host])
-
-    try:
-        result = subprocess.run(
-            command,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            check=False,
-        )
-    except OSError as exc:
-        logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)
-        return None
-
-    if result.returncode != 0:
-        logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)
-        return None
-
-    token = result.stdout.strip()
-    return token or None
-
-
-def _read_windows_copilot_cli_oauth_token() -> str | None:
-    if os.name != "nt":
-        return None
-
-    class FILETIME(ctypes.Structure):
-        _fields_ = [
-            ("dwLowDateTime", wintypes.DWORD),
-            ("dwHighDateTime", wintypes.DWORD),
-        ]
-
-    class CREDENTIAL(ctypes.Structure):
-        _fields_ = [
-            ("Flags", wintypes.DWORD),
-            ("Type", wintypes.DWORD),
-            ("TargetName", wintypes.LPWSTR),
-            ("Comment", wintypes.LPWSTR),
-            ("LastWritten", FILETIME),
-            ("CredentialBlobSize", wintypes.DWORD),
-            ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),
-            ("Persist", wintypes.DWORD),
-            ("AttributeCount", wintypes.DWORD),
-            ("Attributes", wintypes.LPVOID),
-            ("TargetAlias", wintypes.LPWSTR),
-            ("UserName", wintypes.LPWSTR),
-        ]
-
-    cred_ptr = ctypes.POINTER(CREDENTIAL)
-    credentials = ctypes.POINTER(cred_ptr)()
-    count = wintypes.DWORD()
-    win_dll = getattr(ctypes, "WinDLL", None)
-    if win_dll is None:
-        return None
-
-    advapi32 = win_dll("Advapi32.dll")
-    advapi32.CredEnumerateW.argtypes = [
-        wintypes.LPCWSTR,
-        wintypes.DWORD,
-        ctypes.POINTER(wintypes.DWORD),
-        ctypes.POINTER(ctypes.POINTER(cred_ptr)),
-    ]
-    advapi32.CredEnumerateW.restype = wintypes.BOOL
-    advapi32.CredFree.argtypes = [wintypes.LPVOID]
-
-    try:
-        if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):
-            return None
-    except OSError as exc:
-        logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)
-        return None
-
-    host = _github_host().lower()
-    service_prefixes = [f"copilot-cli/{host}:"]
-    if "://" not in host:
-        service_prefixes.append(f"copilot-cli/https://{host}:")
-
-    try:
-        for idx in range(count.value):
-            credential = credentials[idx].contents
-            target = (credential.TargetName or "").strip().lower()
-            if not any(target.startswith(prefix) for prefix in service_prefixes):
-                continue
-            if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:
-                continue
-            blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)
-            token = blob.decode("utf-8", errors="replace").strip()
-            if token:
-                return token
-    finally:
-        if credentials:
-            advapi32.CredFree(credentials)
-
-    return None
-
-
-def _parse_expiry(value: Any) -> float | None:
-    if value in (None, ""):
-        return None
-
-    if isinstance(value, int | float):
-        number = float(value)
-        if number > 10_000_000_000:
-            return number / 1000.0
-        return number
-
-    if isinstance(value, str):
-        raw = value.strip()
-        if not raw:
-            return None
-        if raw.isdigit():
-            return _parse_expiry(int(raw))
-        try:
-            normalized = raw.replace("Z", "+00:00")
-            return datetime.fromisoformat(normalized).timestamp()
-        except ValueError:
-            return None
-
-    return None
-
-
-def _entry_expired(entry: dict[str, Any]) -> bool:
-    for key in _EXPIRY_KEYS:
-        expiry = _parse_expiry(entry.get(key))
-        if expiry is None:
-            continue
-        return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)
-    return False
-
-
-def _extract_oauth_token(entry: dict[str, Any]) -> str | None:
-    if _entry_expired(entry):
-        return None
-
-    for key in _OAUTH_TOKEN_KEYS:
-        value = entry.get(key)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-
-    for value in entry.values():
-        if isinstance(value, dict):
-            nested = _extract_oauth_token(value)
-            if nested:
-                return nested
-
-    return None
-
-
-def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:
-    entries: list[tuple[str, dict[str, Any]]] = []
-    if isinstance(payload, dict):
-        for key, value in payload.items():
-            if isinstance(value, dict):
-                entries.append((str(key), value))
-    elif isinstance(payload, list):
-        for idx, value in enumerate(payload):
-            if isinstance(value, dict):
-                key = str(value.get("host") or value.get("githubHost") or idx)
-                entries.append((key, value))
-    return entries
-
-
-def read_cached_oauth_token() -> str | None:
-    """Return a GitHub OAuth token for Copilot, if one is available."""
-
-    for env_var in _OAUTH_TOKEN_ENV_VARS:
-        token = os.environ.get(env_var, "").strip()
-        if token:
-            return token
-
-    windows_copilot_token = _read_windows_copilot_cli_oauth_token()
-    if windows_copilot_token:
-        return windows_copilot_token
-
-    gh_token = _read_gh_cli_oauth_token()
-    if gh_token:
-        return gh_token
-
-    host = _github_host()
-    for path in _resolve_token_file_paths():
-        try:
-            payload = json.loads(path.read_text(encoding="utf-8"))
-        except FileNotFoundError:
-            continue
-        except Exception as exc:
-            logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)
-            continue
-
-        for key, entry in _iter_file_entries(payload):
-            if host not in key.lower():
-                continue
-            cached_token = _extract_oauth_token(entry)
-            if cached_token:
-                return cached_token
-
-    return None
-
-
-def resolve_client_bearer_token() -> str | None:
-    """Return a bearer token suitable for satisfying Copilot provider auth checks."""
-
-    for env_var in _API_TOKEN_ENV_VARS:
-        token = os.environ.get(env_var, "").strip()
-        if token:
-            return token
-    return read_cached_oauth_token()
-
-
-def has_oauth_auth() -> bool:
-    """Return True when existing Copilot auth can be reused."""
-
-    return resolve_client_bearer_token() is not None
-
-
-def is_copilot_api_url(url: str | None) -> bool:
-    """Return True when the upstream URL points at GitHub Copilot."""
-
-    if not url:
-        return False
-    parsed = urlparse(url)
-    host = parsed.netloc.lower() or parsed.path.lower()
-    return "githubcopilot.com" in host
-
-
-def build_copilot_upstream_url(base_url: str, path: str) -> str:
-    """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""
-
-    normalized_base = base_url.rstrip("/")
-    normalized_path = path if path.startswith("/") else f"/{path}"
-    if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):
-        normalized_path = normalized_path[3:]
-    return f"{normalized_base}{normalized_path}"
-
-
-class CopilotTokenProvider:
-    """Resolve and cache short-lived Copilot API tokens."""
-
-    def __init__(self) -> None:
-        self._lock = asyncio.Lock()
-        self._cached: CopilotAPIToken | None = None
-
-    async def get_api_token(self) -> CopilotAPIToken:
-        explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()
-        if explicit_api_token:
-            return CopilotAPIToken(
-                token=explicit_api_token,
-                expires_at=time.time() + 3600,
-                api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
-                or DEFAULT_API_URL,
-            )
-
-        cached = self._cached
-        if cached is not None and cached.is_valid:
-            return cached
-
-        async with self._lock:
-            cached = self._cached
-            if cached is not None and cached.is_valid:
-                return cached
-
-            oauth_token = read_cached_oauth_token()
-            if not oauth_token:
-                raise RuntimeError("No GitHub Copilot OAuth token is available.")
-
-            if not _should_exchange_oauth_token():
-                direct_token = CopilotAPIToken(
-                    token=oauth_token,
-                    expires_at=time.time() + 3600,
-                    api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
-                    or DEFAULT_API_URL,
-                )
-                self._cached = direct_token
-                return direct_token
-
-            exchanged = await self._exchange_token(oauth_token)
-            self._cached = exchanged
-            return exchanged
-
-    async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:
-        headers = {
-            "Authorization": f"token {oauth_token}",
-            "Accept": "application/json",
-            "Editor-Version": os.environ.get(
-                "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION
-            ),
-            "User-Agent": _DEFAULT_USER_AGENT,
-        }
-        payload = await asyncio.to_thread(self._exchange_token_sync, headers)
-        token = str(payload.get("token") or "").strip()
-        if not token:
-            raise RuntimeError("Copilot token exchange returned an empty token.")
-
-        expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)
-        raw_endpoints = payload.get("endpoints")
-        endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}
-        api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL
-        refresh_in = payload.get("refresh_in")
-        sku = payload.get("sku")
-        return CopilotAPIToken(
-            token=token,
-            expires_at=expires_at,
-            api_url=api_url,
-            refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,
-            sku=str(sku) if isinstance(sku, str) and sku.strip() else None,
-        )
-
-    @staticmethod
-    def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:
-        request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")
-        try:
-            with urllib_request.urlopen(request, timeout=10.0) as response:
-                payload = json.loads(response.read().decode("utf-8"))
-                return payload if isinstance(payload, dict) else {}
-        except urllib_error.HTTPError as exc:
-            body = exc.read().decode("utf-8", errors="replace")
-            raise RuntimeError(
-                f"Copilot token exchange failed with HTTP {exc.code}: {body}"
-            ) from exc
-
-
-_provider: CopilotTokenProvider | None = None
-
-
-def get_copilot_token_provider() -> CopilotTokenProvider:
-    """Return the shared Copilot token provider."""
-
-    global _provider
-    if _provider is None:
-        _provider = CopilotTokenProvider()
-    return _provider
-
-
-async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:
-    """Replace Authorization with a fresh Copilot API token when targeting Copilot."""
-
-    resolved = dict(headers)
-    if not is_copilot_api_url(url):
-        return resolved
-
-    token = await get_copilot_token_provider().get_api_token()
-    for key in list(resolved):
-        if key.lower() == "authorization":
-            resolved.pop(key)
-    resolved["Authorization"] = f"Bearer {token.token}"
-    return resolved
+"""GitHub Copilot OAuth discovery and API-token exchange helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import ctypes
+import json
+import logging
+import os
+import subprocess
+import time
+from ctypes import wintypes
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_API_URL = "https://api.githubcopilot.com"
+DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"
+DEFAULT_GITHUB_HOST = "github.com"
+_TOKEN_EXPIRY_BUFFER_S = 60
+_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"
+_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"
+
+_API_TOKEN_ENV_VARS = (
+    "GITHUB_COPILOT_API_TOKEN",
+    "COPILOT_PROVIDER_BEARER_TOKEN",
+)
+_OAUTH_TOKEN_ENV_VARS = (
+    "GITHUB_COPILOT_GITHUB_TOKEN",
+    "GITHUB_COPILOT_TOKEN",
+    "GITHUB_TOKEN",
+    "COPILOT_GITHUB_TOKEN",
+)
+_OAUTH_TOKEN_KEYS = (
+    "oauth_token",
+    "oauthToken",
+    "token",
+    "access_token",
+    "accessToken",
+)
+_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")
+
+
+@dataclass(frozen=True)
+class CopilotAPIToken:
+    """Short-lived API token exchanged from a GitHub OAuth token."""
+
+    token: str
+    expires_at: float
+    api_url: str = DEFAULT_API_URL
+    refresh_in: int | None = None
+    sku: str | None = None
+
+    @property
+    def is_valid(self) -> bool:
+        return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)
+
+
+def _github_host() -> str:
+    return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()
+
+
+def _token_exchange_url() -> str:
+    return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()
+
+
+def _should_exchange_oauth_token() -> bool:
+    raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def _resolve_token_file_paths() -> list[Path]:
+    override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()
+    if override:
+        return [Path(override).expanduser()]
+
+    paths: list[Path] = []
+    local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
+    if local_appdata:
+        base = Path(local_appdata) / "github-copilot"
+        paths.extend([base / "apps.json", base / "hosts.json"])
+
+    config_base = Path.home() / ".config" / "github-copilot"
+    paths.extend([config_base / "apps.json", config_base / "hosts.json"])
+    return paths
+
+
+def _read_gh_cli_oauth_token() -> str | None:
+    gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"
+    command = [gh_bin, "auth", "token"]
+    host = _github_host()
+    if host and host != DEFAULT_GITHUB_HOST:
+        command.extend(["--hostname", host])
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except OSError as exc:
+        logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)
+        return None
+
+    if result.returncode != 0:
+        logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)
+        return None
+
+    token = result.stdout.strip()
+    return token or None
+
+
+def _read_windows_copilot_cli_oauth_token() -> str | None:
+    if os.name != "nt":
+        return None
+
+    class FILETIME(ctypes.Structure):
+        _fields_ = [
+            ("dwLowDateTime", wintypes.DWORD),
+            ("dwHighDateTime", wintypes.DWORD),
+        ]
+
+    class CREDENTIAL(ctypes.Structure):
+        _fields_ = [
+            ("Flags", wintypes.DWORD),
+            ("Type", wintypes.DWORD),
+            ("TargetName", wintypes.LPWSTR),
+            ("Comment", wintypes.LPWSTR),
+            ("LastWritten", FILETIME),
+            ("CredentialBlobSize", wintypes.DWORD),
+            ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),
+            ("Persist", wintypes.DWORD),
+            ("AttributeCount", wintypes.DWORD),
+            ("Attributes", wintypes.LPVOID),
+            ("TargetAlias", wintypes.LPWSTR),
+            ("UserName", wintypes.LPWSTR),
+        ]
+
+    cred_ptr = ctypes.POINTER(CREDENTIAL)
+    credentials = ctypes.POINTER(cred_ptr)()
+    count = wintypes.DWORD()
+    win_dll = getattr(ctypes, "WinDLL", None)
+    if win_dll is None:
+        return None
+
+    advapi32 = win_dll("Advapi32.dll")
+    advapi32.CredEnumerateW.argtypes = [
+        wintypes.LPCWSTR,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.POINTER(ctypes.POINTER(cred_ptr)),
+    ]
+    advapi32.CredEnumerateW.restype = wintypes.BOOL
+    advapi32.CredFree.argtypes = [wintypes.LPVOID]
+
+    try:
+        if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):
+            return None
+    except OSError as exc:
+        logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)
+        return None
+
+    host = _github_host().lower()
+    service_prefixes = [f"copilot-cli/{host}:"]
+    if "://" not in host:
+        service_prefixes.append(f"copilot-cli/https://{host}:")
+
+    try:
+        for idx in range(count.value):
+            credential = credentials[idx].contents
+            target = (credential.TargetName or "").strip().lower()
+            if not any(target.startswith(prefix) for prefix in service_prefixes):
+                continue
+            if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:
+                continue
+            blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)
+            token = blob.decode("utf-8", errors="replace").strip()
+            if token:
+                return token
+    finally:
+        if credentials:
+            advapi32.CredFree(credentials)
+
+    return None
+
+
+def _parse_expiry(value: Any) -> float | None:
+    if value in (None, ""):
+        return None
+
+    if isinstance(value, int | float):
+        number = float(value)
+        if number > 10_000_000_000:
+            return number / 1000.0
+        return number
+
+    if isinstance(value, str):
+        raw = value.strip()
+        if not raw:
+            return None
+        if raw.isdigit():
+            return _parse_expiry(int(raw))
+        try:
+            normalized = raw.replace("Z", "+00:00")
+            return datetime.fromisoformat(normalized).timestamp()
+        except ValueError:
+            return None
+
+    return None
+
+
+def _entry_expired(entry: dict[str, Any]) -> bool:
+    for key in _EXPIRY_KEYS:
+        expiry = _parse_expiry(entry.get(key))
+        if expiry is None:
+            continue
+        return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)
+    return False
+
+
+def _extract_oauth_token(entry: dict[str, Any]) -> str | None:
+    if _entry_expired(entry):
+        return None
+
+    for key in _OAUTH_TOKEN_KEYS:
+        value = entry.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+
+    for value in entry.values():
+        if isinstance(value, dict):
+            nested = _extract_oauth_token(value)
+            if nested:
+                return nested
+
+    return None
+
+
+def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:
+    entries: list[tuple[str, dict[str, Any]]] = []
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            if isinstance(value, dict):
+                entries.append((str(key), value))
+    elif isinstance(payload, list):
+        for idx, value in enumerate(payload):
+            if isinstance(value, dict):
+                key = str(value.get("host") or value.get("githubHost") or idx)
+                entries.append((key, value))
+    return entries
+
+
+def read_cached_oauth_token() -> str | None:
+    """Return a GitHub OAuth token for Copilot, if one is available."""
+
+    for env_var in _OAUTH_TOKEN_ENV_VARS:
+        token = os.environ.get(env_var, "").strip()
+        if token:
+            return token
+
+    windows_copilot_token = _read_windows_copilot_cli_oauth_token()
+    if windows_copilot_token:
+        return windows_copilot_token
+
+    gh_token = _read_gh_cli_oauth_token()
+    if gh_token:
+        return gh_token
+
+    host = _github_host()
+    for path in _resolve_token_file_paths():
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            continue
+        except Exception as exc:
+            logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)
+            continue
+
+        for key, entry in _iter_file_entries(payload):
+            if host not in key.lower():
+                continue
+            cached_token = _extract_oauth_token(entry)
+            if cached_token:
+                return cached_token
+
+    return None
+
+
+def resolve_client_bearer_token() -> str | None:
+    """Return a bearer token suitable for satisfying Copilot provider auth checks."""
+
+    for env_var in _API_TOKEN_ENV_VARS:
+        token = os.environ.get(env_var, "").strip()
+        if token:
+            return token
+    return read_cached_oauth_token()
+
+
+def has_oauth_auth() -> bool:
+    """Return True when existing Copilot auth can be reused."""
+
+    return resolve_client_bearer_token() is not None
+
+
+def is_copilot_api_url(url: str | None) -> bool:
+    """Return True when the upstream URL points at GitHub Copilot."""
+
+    if not url:
+        return False
+    parsed = urlparse(url)
+    host = parsed.netloc.lower() or parsed.path.lower()
+    return "githubcopilot.com" in host
+
+
+def build_copilot_upstream_url(base_url: str, path: str) -> str:
+    """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""
+
+    normalized_base = base_url.rstrip("/")
+    normalized_path = path if path.startswith("/") else f"/{path}"
+    if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):
+        normalized_path = normalized_path[3:]
+    return f"{normalized_base}{normalized_path}"
+
+
+class CopilotTokenProvider:
+    """Resolve and cache short-lived Copilot API tokens."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._cached: CopilotAPIToken | None = None
+
+    async def get_api_token(self) -> CopilotAPIToken:
+        explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()
+        if explicit_api_token:
+            return CopilotAPIToken(
+                token=explicit_api_token,
+                expires_at=time.time() + 3600,
+                api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
+                or DEFAULT_API_URL,
+            )
+
+        cached = self._cached
+        if cached is not None and cached.is_valid:
+            return cached
+
+        async with self._lock:
+            cached = self._cached
+            if cached is not None and cached.is_valid:
+                return cached
+
+            oauth_token = read_cached_oauth_token()
+            if not oauth_token:
+                raise RuntimeError("No GitHub Copilot OAuth token is available.")
+
+            if not _should_exchange_oauth_token():
+                direct_token = CopilotAPIToken(
+                    token=oauth_token,
+                    expires_at=time.time() + 3600,
+                    api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
+                    or DEFAULT_API_URL,
+                )
+                self._cached = direct_token
+                return direct_token
+
+            exchanged = await self._exchange_token(oauth_token)
+            self._cached = exchanged
+            return exchanged
+
+    async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:
+        headers = {
+            "Authorization": f"token {oauth_token}",
+            "Accept": "application/json",
+            "Editor-Version": os.environ.get(
+                "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION
+            ),
+            "User-Agent": _DEFAULT_USER_AGENT,
+        }
+        payload = await asyncio.to_thread(self._exchange_token_sync, headers)
+        token = str(payload.get("token") or "").strip()
+        if not token:
+            raise RuntimeError("Copilot token exchange returned an empty token.")
+
+        expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)
+        raw_endpoints = payload.get("endpoints")
+        endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}
+        api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL
+        refresh_in = payload.get("refresh_in")
+        sku = payload.get("sku")
+        return CopilotAPIToken(
+            token=token,
+            expires_at=expires_at,
+            api_url=api_url,
+            refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,
+            sku=str(sku) if isinstance(sku, str) and sku.strip() else None,
+        )
+
+    @staticmethod
+    def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:
+        request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")
+        try:
+            with urllib_request.urlopen(request, timeout=10.0) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+                return payload if isinstance(payload, dict) else {}
+        except urllib_error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"Copilot token exchange failed with HTTP {exc.code}: {body}"
+            ) from exc
+
+
+_provider: CopilotTokenProvider | None = None
+
+
+def get_copilot_token_provider() -> CopilotTokenProvider:
+    """Return the shared Copilot token provider."""
+
+    global _provider
+    if _provider is None:
+        _provider = CopilotTokenProvider()
+    return _provider
+
+
+async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:
+    """Replace Authorization with a fresh Copilot API token when targeting Copilot."""
+
+    resolved = dict(headers)
+    if not is_copilot_api_url(url):
+        return resolved
+
+    token = await get_copilot_token_provider().get_api_token()
+    for key in list(resolved):
+        if key.lower() == "authorization":
+            resolved.pop(key)
+    resolved["Authorization"] = f"Bearer {token.token}"
+    return resolved

headroom/install/health.py

@@ -1,28 +1,28 @@
-"""Health helpers for persistent deployments."""
-
-from __future__ import annotations
-
-import json
-import urllib.error
-import urllib.request
-from typing import Any
-
-
-def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
-    """Return a JSON payload from the URL when reachable."""
-
-    try:
-        with urllib.request.urlopen(url, timeout=timeout) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-    except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):
-        return None
-    return payload if isinstance(payload, dict) else None
-
-
-def probe_ready(url: str, timeout: float = 2.0) -> bool:
-    """Return True when the ready endpoint reports readiness."""
-
-    payload = probe_json(url, timeout=timeout)
-    if not isinstance(payload, dict):
-        return False
-    return bool(payload.get("ready", False) or payload.get("status") == "healthy")
+"""Health helpers for persistent deployments."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
+    """Return a JSON payload from the URL when reachable."""
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def probe_ready(url: str, timeout: float = 2.0) -> bool:
+    """Return True when the ready endpoint reports readiness."""
+
+    payload = probe_json(url, timeout=timeout)
+    if not isinstance(payload, dict):
+        return False
+    return bool(payload.get("ready", False) or payload.get("status") == "healthy")

headroom/install/providers.py

@@ -1,174 +1,174 @@
-"""Tool-target configuration for persistent deployments."""
-
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from pathlib import Path
-
-from headroom.providers.install_registry import (
-    apply_provider_scope_mutations,
-    revert_provider_scope_mutation,
-)
-
-from .models import ConfigScope, DeploymentManifest, ManagedMutation
-from .paths import (
-    unix_system_env_targets,
-    unix_user_env_targets,
-)
-
-_ENV_MARKER_START = "# >>> headroom persistent env >>>"
-_ENV_MARKER_END = "# <<< headroom persistent env <<<"
-_ENV_PATTERN = re.compile(
-    re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),
-    re.DOTALL,
-)
-
-
-def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:
-    if file_path.exists():
-        existing = file_path.read_text()
-        if marker in existing:
-            return pattern.sub(block, existing)
-        return existing.rstrip() + "\n\n" + block + "\n"
-    return block + "\n"
-
-
-def _env_block(values: dict[str, str]) -> str:
-    lines = [_ENV_MARKER_START]
-    for name, value in values.items():
-        lines.append(f'export {name}="{value}"')
-    lines.append(_ENV_MARKER_END)
-    return "\n".join(lines)
-
-
-def _powershell_literal(value: str) -> str:
-    return "'" + value.replace("'", "''") + "'"
-
-
-def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:
-    merged = dict(manifest.base_env)
-    for env_map in manifest.tool_envs.values():
-        merged.update(env_map)
-    return merged
-
-
-def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    values = _unix_scope_values(manifest)
-    block = _env_block(values)
-    if manifest.scope == ConfigScope.USER.value:
-        targets = unix_user_env_targets()
-    else:
-        targets = unix_system_env_targets()
-    mutations: list[ManagedMutation] = []
-    for path in targets:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)
-        path.write_text(merged)
-        mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))
-    return mutations
-
-
-def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:
-    for mutation in mutations:
-        if mutation.kind != "shell-block" or not mutation.path:
-            continue
-        path = Path(mutation.path)
-        if not path.exists():
-            continue
-        content = path.read_text()
-        if _ENV_MARKER_START not in content:
-            continue
-        path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")
-
-
-def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"
-    merged = _unix_scope_values(manifest)
-    mutations: list[ManagedMutation] = []
-    for name, value in merged.items():
-        previous = subprocess.run(
-            [
-                "powershell",
-                "-NoProfile",
-                "-Command",
-                f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "
-                "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",
-            ],
-            capture_output=True,
-            text=True,
-            check=True,
-        ).stdout.strip()
-        command = [
-            "powershell",
-            "-NoProfile",
-            "-Command",
-            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",
-        ]
-        subprocess.run(command, check=True)
-        mutations.append(
-            ManagedMutation(
-                target="env",
-                kind="windows-env",
-                data={
-                    "name": name,
-                    "scope": scope_name,
-                    "previous": None if previous == "__HEADROOM_UNSET__" else previous,
-                },
-            )
-        )
-    return mutations
-
-
-def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:
-    for mutation in mutations:
-        if mutation.kind != "windows-env":
-            continue
-        name = mutation.data.get("name")
-        if not isinstance(name, str):
-            raise ValueError("Windows environment mutation is missing a variable name")
-        scope_name = mutation.data.get("scope", "User")
-        if not isinstance(scope_name, str):
-            raise ValueError("Windows environment mutation is missing a valid scope")
-        previous = mutation.data.get("previous")
-        if previous is None:
-            value_literal = "$null"
-        else:
-            value_literal = _powershell_literal(previous)
-        command = [
-            "powershell",
-            "-NoProfile",
-            "-Command",
-            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",
-        ]
-        subprocess.run(command, check=True)
-
-
-def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    """Apply provider/user/system configuration for a deployment."""
-
-    mutations: list[ManagedMutation] = []
-    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
-        if os.name == "nt":
-            mutations.extend(_apply_windows_env_scope(manifest))
-        else:
-            mutations.extend(_apply_unix_env_scope(manifest))
-        mutations.extend(apply_provider_scope_mutations(manifest))
-        return mutations
-
-    return [*mutations, *apply_provider_scope_mutations(manifest)]
-
-
-def revert_mutations(manifest: DeploymentManifest) -> None:
-    """Undo the stored mutations for a deployment."""
-
-    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
-        shell_mutations = [m for m in manifest.mutations if m.target == "env"]
-        if os.name == "nt":
-            _remove_windows_env_scope(shell_mutations)
-        else:
-            _remove_unix_env_scope(shell_mutations)
-
-    for mutation in manifest.mutations:
-        revert_provider_scope_mutation(manifest, mutation)
+"""Tool-target configuration for persistent deployments."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from headroom.providers.install_registry import (
+    apply_provider_scope_mutations,
+    revert_provider_scope_mutation,
+)
+
+from .models import ConfigScope, DeploymentManifest, ManagedMutation
+from .paths import (
+    unix_system_env_targets,
+    unix_user_env_targets,
+)
+
+_ENV_MARKER_START = "# >>> headroom persistent env >>>"
+_ENV_MARKER_END = "# <<< headroom persistent env <<<"
+_ENV_PATTERN = re.compile(
+    re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),
+    re.DOTALL,
+)
+
+
+def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:
+    if file_path.exists():
+        existing = file_path.read_text()
+        if marker in existing:
+            return pattern.sub(block, existing)
+        return existing.rstrip() + "\n\n" + block + "\n"
+    return block + "\n"
+
+
+def _env_block(values: dict[str, str]) -> str:
+    lines = [_ENV_MARKER_START]
+    for name, value in values.items():
+        lines.append(f'export {name}="{value}"')
+    lines.append(_ENV_MARKER_END)
+    return "\n".join(lines)
+
+
+def _powershell_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:
+    merged = dict(manifest.base_env)
+    for env_map in manifest.tool_envs.values():
+        merged.update(env_map)
+    return merged
+
+
+def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    values = _unix_scope_values(manifest)
+    block = _env_block(values)
+    if manifest.scope == ConfigScope.USER.value:
+        targets = unix_user_env_targets()
+    else:
+        targets = unix_system_env_targets()
+    mutations: list[ManagedMutation] = []
+    for path in targets:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)
+        path.write_text(merged)
+        mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))
+    return mutations
+
+
+def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:
+    for mutation in mutations:
+        if mutation.kind != "shell-block" or not mutation.path:
+            continue
+        path = Path(mutation.path)
+        if not path.exists():
+            continue
+        content = path.read_text()
+        if _ENV_MARKER_START not in content:
+            continue
+        path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")
+
+
+def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"
+    merged = _unix_scope_values(manifest)
+    mutations: list[ManagedMutation] = []
+    for name, value in merged.items():
+        previous = subprocess.run(
+            [
+                "powershell",
+                "-NoProfile",
+                "-Command",
+                f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "
+                "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        command = [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",
+        ]
+        subprocess.run(command, check=True)
+        mutations.append(
+            ManagedMutation(
+                target="env",
+                kind="windows-env",
+                data={
+                    "name": name,
+                    "scope": scope_name,
+                    "previous": None if previous == "__HEADROOM_UNSET__" else previous,
+                },
+            )
+        )
+    return mutations
+
+
+def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:
+    for mutation in mutations:
+        if mutation.kind != "windows-env":
+            continue
+        name = mutation.data.get("name")
+        if not isinstance(name, str):
+            raise ValueError("Windows environment mutation is missing a variable name")
+        scope_name = mutation.data.get("scope", "User")
+        if not isinstance(scope_name, str):
+            raise ValueError("Windows environment mutation is missing a valid scope")
+        previous = mutation.data.get("previous")
+        if previous is None:
+            value_literal = "$null"
+        else:
+            value_literal = _powershell_literal(previous)
+        command = [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",
+        ]
+        subprocess.run(command, check=True)
+
+
+def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    """Apply provider/user/system configuration for a deployment."""
+
+    mutations: list[ManagedMutation] = []
+    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
+        if os.name == "nt":
+            mutations.extend(_apply_windows_env_scope(manifest))
+        else:
+            mutations.extend(_apply_unix_env_scope(manifest))
+        mutations.extend(apply_provider_scope_mutations(manifest))
+        return mutations
+
+    return [*mutations, *apply_provider_scope_mutations(manifest)]
+
+
+def revert_mutations(manifest: DeploymentManifest) -> None:
+    """Undo the stored mutations for a deployment."""
+
+    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
+        shell_mutations = [m for m in manifest.mutations if m.target == "env"]
+        if os.name == "nt":
+            _remove_windows_env_scope(shell_mutations)
+        else:
+            _remove_unix_env_scope(shell_mutations)
+
+    for mutation in manifest.mutations:
+        revert_provider_scope_mutation(manifest, mutation)

headroom/install/runtime.py

@@ -1,275 +1,279 @@
-"""Runtime helpers for persistent deployments."""
-
-from __future__ import annotations
-
-import os
-import shutil
-import signal
-import subprocess
-import sys
-import time
-from pathlib import Path
-from typing import Any
-
-from .health import probe_ready
-from .models import DeploymentManifest, InstallPreset, RuntimeKind
-from .paths import log_path, pid_path
-
-PASSTHROUGH_ENV_PREFIXES = (
-    "HEADROOM_",
-    "ANTHROPIC_",
-    "OPENAI_",
-    "GEMINI_",
-    "AWS_",
-    "AZURE_",
-    "VERTEX_",
-    "GOOGLE_",
-    "GOOGLE_CLOUD_",
-    "MISTRAL_",
-    "GROQ_",
-    "OPENROUTER_",
-    "XAI_",
-    "TOGETHER_",
-    "COHERE_",
-    "OLLAMA_",
-    "LITELLM_",
-    "OTEL_",
-    "SUPABASE_",
-    "QDRANT_",
-    "NEO4J_",
-    "LANGSMITH_",
-)
-
-
-def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:
-    return {
-        "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,
-        "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,
-        "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,
-        "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,
-        "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,
-    }
-
-
-def resolve_headroom_command() -> list[str]:
-    """Resolve the most reliable command to invoke headroom."""
-
-    headroom_bin = shutil.which("headroom")
-    if headroom_bin:
-        return [headroom_bin]
-    return [sys.executable, "-m", "headroom.cli"]
-
-
-def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:
-    env = os.environ.copy()
-    env.update(manifest.base_env)
-    env.update(_deployment_env(manifest))
-    return env
-
-
-def _ensure_host_dirs() -> None:
-    for subdir in (".headroom", ".claude", ".codex", ".gemini"):
-        (Path.home() / subdir).mkdir(parents=True, exist_ok=True)
-
-
-def _mount_source(home: str, subdir: str) -> str:
-    if os.name == "nt":
-        return f"{home}\\{subdir}"
-    return f"{home}/{subdir}"
-
-
-def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
-    """Build the raw foreground command that runs the proxy."""
-
-    if manifest.runtime_kind == RuntimeKind.PYTHON.value:
-        return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]
-
-    _ensure_host_dirs()
-    home = str(Path.home())
-    container_home = "/tmp/headroom-home"
-    command = [
-        "docker",
-        "run",
-        "--rm",
-        "--name",
-        manifest.container_name,
-        "-p",
-        f"127.0.0.1:{manifest.port}:{manifest.port}",
-        "--workdir",
-        container_home,
-        "--env",
-        f"HOME={container_home}",
-        "--env",
-        "PYTHONUNBUFFERED=1",
-        # Canonical Headroom filesystem contract (issue #175).
-        "--env",
-        f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",
-        "--env",
-        f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",
-        "--volume",
-        f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",
-        "--volume",
-        f"{_mount_source(home, '.claude')}:{container_home}/.claude",
-        "--volume",
-        f"{_mount_source(home, '.codex')}:{container_home}/.codex",
-        "--volume",
-        f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",
-    ]
-    if os.name != "nt":
-        getuid = getattr(os, "getuid", None)
-        getgid = getattr(os, "getgid", None)
-        if callable(getuid) and callable(getgid):
-            command.extend(["--user", f"{getuid()}:{getgid()}"])
-    runtime_env = {**manifest.base_env, **_deployment_env(manifest)}
-    for name, value in runtime_env.items():
-        command.extend(["--env", f"{name}={value}"])
-    for name in sorted(os.environ):
-        if name.startswith(PASSTHROUGH_ENV_PREFIXES):
-            command.extend(["--env", name])
-    command.extend(
-        [
-            manifest.image,
-            "headroom",
-            "proxy",
-            "--host",
-            "0.0.0.0",
-            *manifest.proxy_args[2:],
-        ]
-    )
-    return command
-
-
-def _write_pid(profile: str, pid: int) -> None:
-    path = pid_path(profile)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(str(pid))
-
-
-def _read_pid(profile: str) -> int | None:
-    path = pid_path(profile)
-    if not path.exists():
-        return None
-    try:
-        return int(path.read_text().strip())
-    except ValueError:
-        return None
-
-
-def _clear_pid(profile: str) -> None:
-    path = pid_path(profile)
-    if path.exists():
-        path.unlink()
-
-
-def run_foreground(manifest: DeploymentManifest) -> int:
-    """Run the raw runtime command in the foreground."""
-
-    command = build_runtime_command(manifest)
-    env = _runtime_env(manifest)
-    log_file_path = log_path(manifest.profile)
-    log_file_path.parent.mkdir(parents=True, exist_ok=True)
-
-    with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:
-        proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)
-        _write_pid(manifest.profile, proc.pid)
-
-        def _cleanup(signum: int | None = None, frame: Any = None) -> None:
-            if proc.poll() is None:
-                proc.terminate()
-                try:
-                    proc.wait(timeout=10)
-                except subprocess.TimeoutExpired:
-                    proc.kill()
-
-        signal.signal(signal.SIGINT, _cleanup)
-        signal.signal(signal.SIGTERM, _cleanup)
-        try:
-            return proc.wait()
-        finally:
-            _clear_pid(manifest.profile)
-
-
-def start_detached_agent(profile: str) -> subprocess.Popen[str]:
-    """Start `headroom install agent run` detached for the given profile."""
-
-    command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]
-    log_file_path = log_path(profile)
-    log_file_path.parent.mkdir(parents=True, exist_ok=True)
-    log_file = open(log_file_path, "a", encoding="utf-8", errors="replace")  # noqa: SIM115
-
-    kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}
-    if os.name == "nt":
-        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
-            subprocess, "CREATE_NEW_PROCESS_GROUP", 0
-        )
-    else:
-        kwargs["start_new_session"] = True
-    return subprocess.Popen(command, **kwargs)
-
-
-def start_persistent_docker(manifest: DeploymentManifest) -> None:
-    """Start a persistent Docker container with restart policy."""
-
-    command = build_runtime_command(manifest)
-    docker_cmd = [
-        "docker",
-        "run",
-        "-d",
-        "--restart",
-        "unless-stopped",
-        "--name",
-        manifest.container_name,
-        *command[5:],  # drop initial `docker run --rm --name ...`
-    ]
-    subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)
-    subprocess.run(docker_cmd, check=True)
-
-
-def stop_runtime(manifest: DeploymentManifest) -> None:
-    """Stop the raw runtime for the deployment."""
-
-    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-        subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)
-        subprocess.run(
-            ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True
-        )
-        return
-
-    pid = _read_pid(manifest.profile)
-    if pid is None:
-        return
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except OSError:
-        pass
-    _clear_pid(manifest.profile)
-
-
-def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:
-    """Wait for the deployment to report ready."""
-
-    for _ in range(timeout_seconds):
-        if probe_ready(manifest.health_url):
-            return True
-        time.sleep(1)
-    return False
-
-
-def runtime_status(manifest: DeploymentManifest) -> str:
-    """Return a short status string for the deployment runtime."""
-
-    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-        result = subprocess.run(
-            ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True
-        )
-        if manifest.container_name in result.stdout.splitlines():
-            return "running"
-        return "stopped"
-    pid = _read_pid(manifest.profile)
-    if pid is None:
-        return "stopped"
-    try:
-        os.kill(pid, 0)
-    except OSError:
-        return "stopped"
-    return "running"
+"""Runtime helpers for persistent deployments."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from .health import probe_ready
+from .models import DeploymentManifest, InstallPreset, RuntimeKind
+from .paths import log_path, pid_path
+
+PASSTHROUGH_ENV_PREFIXES = (
+    "HEADROOM_",
+    "ANTHROPIC_",
+    "OPENAI_",
+    "GEMINI_",
+    "AWS_",
+    "AZURE_",
+    "VERTEX_",
+    "GOOGLE_",
+    "GOOGLE_CLOUD_",
+    "MISTRAL_",
+    "GROQ_",
+    "OPENROUTER_",
+    "XAI_",
+    "TOGETHER_",
+    "COHERE_",
+    "OLLAMA_",
+    "LITELLM_",
+    "OTEL_",
+    "SUPABASE_",
+    "QDRANT_",
+    "NEO4J_",
+    "LANGSMITH_",
+)
+
+
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:
+    return {
+        "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,
+        "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,
+        "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,
+        "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,
+        "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,
+    }
+
+
+def resolve_headroom_command() -> list[str]:
+    """Resolve the most reliable command to invoke headroom."""
+
+    headroom_bin = shutil.which("headroom")
+    if headroom_bin:
+        return [headroom_bin]
+    return [sys.executable, "-m", "headroom.cli"]
+
+
+def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:
+    env = os.environ.copy()
+    env.update(manifest.base_env)
+    env.update(_deployment_env(manifest))
+    return env
+
+
+def _ensure_host_dirs() -> None:
+    for subdir in (".headroom", ".claude", ".codex", ".gemini"):
+        (Path.home() / subdir).mkdir(parents=True, exist_ok=True)
+
+
+def _mount_source(home: str, subdir: str) -> str:
+    if _is_windows():
+        return f"{home}\\{subdir}"
+    return f"{home}/{subdir}"
+
+
+def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
+    """Build the raw foreground command that runs the proxy."""
+
+    if manifest.runtime_kind == RuntimeKind.PYTHON.value:
+        return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]
+
+    _ensure_host_dirs()
+    home = str(Path.home())
+    container_home = "/tmp/headroom-home"
+    command = [
+        "docker",
+        "run",
+        "--rm",
+        "--name",
+        manifest.container_name,
+        "-p",
+        f"127.0.0.1:{manifest.port}:{manifest.port}",
+        "--workdir",
+        container_home,
+        "--env",
+        f"HOME={container_home}",
+        "--env",
+        "PYTHONUNBUFFERED=1",
+        # Canonical Headroom filesystem contract (issue #175).
+        "--env",
+        f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",
+        "--env",
+        f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",
+        "--volume",
+        f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",
+        "--volume",
+        f"{_mount_source(home, '.claude')}:{container_home}/.claude",
+        "--volume",
+        f"{_mount_source(home, '.codex')}:{container_home}/.codex",
+        "--volume",
+        f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",
+    ]
+    if not _is_windows():
+        getuid = getattr(os, "getuid", None)
+        getgid = getattr(os, "getgid", None)
+        if callable(getuid) and callable(getgid):
+            command.extend(["--user", f"{getuid()}:{getgid()}"])
+    runtime_env = {**manifest.base_env, **_deployment_env(manifest)}
+    for name, value in runtime_env.items():
+        command.extend(["--env", f"{name}={value}"])
+    for name in sorted(os.environ):
+        if name.startswith(PASSTHROUGH_ENV_PREFIXES):
+            command.extend(["--env", name])
+    command.extend(
+        [
+            manifest.image,
+            "headroom",
+            "proxy",
+            "--host",
+            "0.0.0.0",
+            *manifest.proxy_args[2:],
+        ]
+    )
+    return command
+
+
+def _write_pid(profile: str, pid: int) -> None:
+    path = pid_path(profile)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(str(pid))
+
+
+def _read_pid(profile: str) -> int | None:
+    path = pid_path(profile)
+    if not path.exists():
+        return None
+    try:
+        return int(path.read_text().strip())
+    except ValueError:
+        return None
+
+
+def _clear_pid(profile: str) -> None:
+    path = pid_path(profile)
+    if path.exists():
+        path.unlink()
+
+
+def run_foreground(manifest: DeploymentManifest) -> int:
+    """Run the raw runtime command in the foreground."""
+
+    command = build_runtime_command(manifest)
+    env = _runtime_env(manifest)
+    log_file_path = log_path(manifest.profile)
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:
+        proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)
+        _write_pid(manifest.profile, proc.pid)
+
+        def _cleanup(signum: int | None = None, frame: Any = None) -> None:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+
+        signal.signal(signal.SIGINT, _cleanup)
+        signal.signal(signal.SIGTERM, _cleanup)
+        try:
+            return proc.wait()
+        finally:
+            _clear_pid(manifest.profile)
+
+
+def start_detached_agent(profile: str) -> subprocess.Popen[str]:
+    """Start `headroom install agent run` detached for the given profile."""
+
+    command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]
+    log_file_path = log_path(profile)
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+    log_file = open(log_file_path, "a", encoding="utf-8", errors="replace")  # noqa: SIM115
+
+    kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}
+    if _is_windows():
+        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+            subprocess, "CREATE_NEW_PROCESS_GROUP", 0
+        )
+    else:
+        kwargs["start_new_session"] = True
+    return subprocess.Popen(command, **kwargs)
+
+
+def start_persistent_docker(manifest: DeploymentManifest) -> None:
+    """Start a persistent Docker container with restart policy."""
+
+    command = build_runtime_command(manifest)
+    docker_cmd = [
+        "docker",
+        "run",
+        "-d",
+        "--restart",
+        "unless-stopped",
+        "--name",
+        manifest.container_name,
+        *command[5:],  # drop initial `docker run --rm --name ...`
+    ]
+    subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)
+    subprocess.run(docker_cmd, check=True)
+
+
+def stop_runtime(manifest: DeploymentManifest) -> None:
+    """Stop the raw runtime for the deployment."""
+
+    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+        subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)
+        subprocess.run(
+            ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True
+        )
+        return
+
+    pid = _read_pid(manifest.profile)
+    if pid is None:
+        return
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        pass
+    _clear_pid(manifest.profile)
+
+
+def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:
+    """Wait for the deployment to report ready."""
+
+    for _ in range(timeout_seconds):
+        if probe_ready(manifest.health_url):
+            return True
+        time.sleep(1)
+    return False
+
+
+def runtime_status(manifest: DeploymentManifest) -> str:
+    """Return a short status string for the deployment runtime."""
+
+    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+        result = subprocess.run(
+            ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True
+        )
+        if manifest.container_name in result.stdout.splitlines():
+            return "running"
+        return "stopped"
+    pid = _read_pid(manifest.profile)
+    if pid is None:
+        return "stopped"
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return "stopped"
+    return "running"

headroom/install/supervisors.py

@@ -23,6 +23,10 @@ from .paths import (
 from .runtime import resolve_headroom_command
 
 
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
 def _command_for_script(*parts: str) -> list[str]:
     return [*resolve_headroom_command(), *parts]
 
@@ -60,7 +64,7 @@ def _render_windows_runner(
 def render_runner_scripts(manifest: DeploymentManifest) -> list[ArtifactRecord]:
     """Render runner/watchdog scripts for the deployment profile."""
 
-    if os.name == "nt":
+    if _is_windows():
         records = []
         records.extend(
             _render_windows_runner(
@@ -230,7 +234,7 @@ def install_supervisor(manifest: DeploymentManifest) -> list[ArtifactRecord]:
         records.append(ArtifactRecord(kind="plist", path=str(plist_path)))
         return records
 
-    if os.name == "nt" and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
+    if _is_windows() and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
         service_bin = f'cmd.exe /c "{windows_run_cmd_path(manifest.profile)}"'
         subprocess.run(
             ["sc.exe", "create", manifest.service_name, f"binPath= {service_bin}", "start= auto"],
@@ -243,7 +247,7 @@ def install_supervisor(manifest: DeploymentManifest) -> list[ArtifactRecord]:
         records.append(ArtifactRecord(kind="windows-service", path=manifest.service_name))
         return records
 
-    if os.name == "nt" and manifest.supervisor_kind == SupervisorKind.TASK.value:
+    if _is_windows() and manifest.supervisor_kind == SupervisorKind.TASK.value:
         startup_name = f"{manifest.service_name}-startup"
         health_name = f"{manifest.service_name}-health"
         startup_cmd = str(windows_ensure_cmd_path(manifest.profile))
@@ -308,7 +312,7 @@ def start_supervisor(manifest: DeploymentManifest) -> None:
         )
         subprocess.run(["launchctl", "kickstart", "-k", f"{domain}/{label}"], check=True)
         return
-    if os.name == "nt" and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
+    if _is_windows() and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
         subprocess.run(["sc.exe", "start", manifest.service_name], check=True)
 
 
@@ -331,7 +335,7 @@ def stop_supervisor(manifest: DeploymentManifest) -> None:
         )
         subprocess.run(["launchctl", "bootout", f"{domain}/{label}"], check=True)
         return
-    if os.name == "nt" and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
+    if _is_windows() and manifest.supervisor_kind == SupervisorKind.SERVICE.value:
         subprocess.run(["sc.exe", "stop", manifest.service_name], check=True)
 
 
@@ -392,7 +396,7 @@ def remove_supervisor(manifest: DeploymentManifest) -> None:
             plist_path.unlink()
         return
 
-    if os.name == "nt":
+    if _is_windows():
         if manifest.supervisor_kind == SupervisorKind.SERVICE.value:
             subprocess.run(
                 ["sc.exe", "stop", manifest.service_name], capture_output=True, text=True

headroom/learn/analyzer.py

@@ -29,6 +29,7 @@ from .models import (
     SessionEvent,
     ToolCall,
 )
+from .writer import extract_marker_block
 
 logger = logging.getLogger(__name__)
 
@@ -147,11 +148,51 @@ class SessionAnalyzer:
 # =============================================================================
 
 
+def _build_prior_patterns_section(project: ProjectInfo) -> str:
+    """Format the current marker blocks from CLAUDE.md / MEMORY.md for the LLM.
+
+    Returns "" when neither file exists nor contains a marker block. When at
+    least one file has a block, returns a header + labeled raw blocks so the
+    LLM can treat them as the starting baseline. See the "Prior Learned
+    Patterns" rule in _SYSTEM_PROMPT for the contract with the model.
+    """
+    parts: list[tuple[str, str]] = []  # (label, block)
+    candidates = (
+        ("CLAUDE.md (CONTEXT_FILE, project-level stable facts)", project.context_file),
+        ("MEMORY.md (MEMORY_FILE, session-level evolving preferences)", project.memory_file),
+    )
+    for label, path in candidates:
+        if path is None or not path.exists():
+            continue
+        block = extract_marker_block(path.read_text())
+        if block:
+            parts.append((label, block))
+
+    if not parts:
+        return ""
+
+    lines = [
+        "=== Prior Learned Patterns ===",
+        (
+            f"These patterns are currently written to {project.name}'s context "
+            f"files. They are your starting baseline — see the 'Prior Learned "
+            f"Patterns' rule in the system prompt for how to integrate them."
+        ),
+        "",
+    ]
+    for label, block in parts:
+        lines.append(f"--- From {label} ---")
+        lines.append(block)
+        lines.append("")
+    return "\n".join(lines)
+
+
 def _build_digest(project: ProjectInfo, sessions: list[SessionData]) -> str:
     """Build a token-efficient text digest of all session events.
 
     The digest includes:
     - Project context
+    - Prior learned patterns (if any) from CLAUDE.md / MEMORY.md
     - Per-session summaries with condensed event streams
     - Error outputs (truncated), success indicators, user messages
     """
@@ -173,6 +214,12 @@ def _build_digest(project: ProjectInfo, sessions: list[SessionData]) -> str:
         lines.append(f"Tokens used: {total_tokens_in:,} in / {total_tokens_out:,} out")
     lines.append("")
 
+    # Prior learned patterns (if any) — gives the LLM the current baseline so
+    # it can produce complete updated sections instead of condensed deltas.
+    prior_section = _build_prior_patterns_section(project)
+    if prior_section:
+        lines.append(prior_section)
+
     # Budget tracking — stop adding events when we approach the limit
     # Rough estimate: 4 chars per token
     char_budget = _MAX_DIGEST_TOKENS * 4
@@ -289,6 +336,24 @@ Rules:
 - Do NOT produce tautological rules (e.g., "use python3 not python3")
 - Do NOT produce rules about things that only happened once (transient errors)
 
+Prior Learned Patterns:
+- The input may contain a "Prior Learned Patterns" section showing what is
+  already written to the project's CLAUDE.md / MEMORY.md. Treat those as the
+  starting baseline for your analysis.
+- When you re-emit a section heading that appears in the prior block, your
+  output REPLACES that prior section wholesale — so your section must be the
+  COMPLETE updated version:
+    * Preserve prior bullets that remain accurate (copy them forward)
+    * Revise bullets when new evidence refines them (merge, don't duplicate)
+    * Drop a prior bullet only when contradicted by clear new evidence
+- Sections from prior runs that you do NOT re-emit are preserved automatically
+  by the writer, so focus only on sections where you have something to add or
+  change. Do NOT re-emit a prior section just to echo it verbatim — that wastes
+  output tokens without changing the outcome.
+- Do NOT write bullets that reference prior siblings you are about to drop
+  (e.g., "X is ALSO large — same rule as Y, Z") unless Y and Z are also present
+  in your current output or preserved in the prior block.
+
 Return ONLY valid JSON matching this schema — no other text:
 {
   "context_file_rules": [

headroom/learn/writer.py

@@ -91,6 +91,17 @@ def _build_section(recommendations: list[Recommendation]) -> str:
 _TOKENS_ANNOTATION_PATTERN = re.compile(r"\*~([\d,]+) tokens/session saved\*\n?")
 
 
+def extract_marker_block(file_content: str) -> str | None:
+    """Return the raw text of the headroom:learn marker block, or None.
+
+    Unlike _parse_prior_recommendations, this returns the block verbatim
+    (including the start/end markers) so it can be fed back to an LLM as
+    context without losing formatting. Returns None if no block is present.
+    """
+    match = _MARKER_PATTERN.search(file_content)
+    return match.group(0) if match else None
+
+
 def _parse_prior_recommendations(existing: str) -> list[Recommendation]:
     """Parse recommendations out of a prior marker block.
 

headroom/memory/adapters/embedders.py

@@ -14,7 +14,7 @@ import asyncio
 import logging
 import os
 from functools import cached_property
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
 
@@ -290,6 +290,7 @@ class OnnxLocalEmbedder:
     DEFAULT_DIMENSION = 384
     DEFAULT_MAX_TOKENS = 256
     ONNX_REPO = "Qdrant/all-MiniLM-L6-v2-onnx"
+    MAX_BATCH_SIZE = 2
 
     def __init__(self, max_length: int = 256) -> None:
         self._max_length = max_length
@@ -330,17 +331,12 @@ class OnnxLocalEmbedder:
 
         logger.info("ONNX embedding model loaded (384-dim, no torch)")
 
-    def _embed_single(self, text: str) -> np.ndarray:
-        """Embed a single text string."""
-        assert self._session is not None
-        assert self._tokenizer is not None
-
-        if not text or not text.strip():
-            return np.zeros(self.DEFAULT_DIMENSION, dtype=np.float32)
-
-        encoded = self._tokenizer.encode(text)
-        input_ids = np.array([encoded.ids], dtype=np.int64)
-        attention_mask = np.array([encoded.attention_mask], dtype=np.int64)
+    def _build_feeds(
+        self,
+        input_ids: np.ndarray,
+        attention_mask: np.ndarray,
+    ) -> dict[str, np.ndarray]:
+        """Build ONNX feeds for a token batch."""
         token_type_ids = np.zeros_like(input_ids, dtype=np.int64)
 
         feeds: dict[str, np.ndarray] = {}
@@ -352,16 +348,37 @@ class OnnxLocalEmbedder:
             elif "token_type_ids" in name:
                 feeds[name] = token_type_ids
 
-        outputs = self._session.run(None, feeds)
-        token_embeddings = outputs[0]  # (1, seq_len, 384)
+        return feeds
+
+    def _embed_many(self, texts: list[str]) -> np.ndarray:
+        """Embed multiple non-empty text strings in one ONNX pass."""
+        assert self._session is not None
+        assert self._tokenizer is not None
+
+        encodings = self._tokenizer.encode_batch(texts)
+        input_ids = np.array([encoding.ids for encoding in encodings], dtype=np.int64)
+        attention_mask = np.array(
+            [encoding.attention_mask for encoding in encodings], dtype=np.int64
+        )
+
+        outputs = self._session.run(None, self._build_feeds(input_ids, attention_mask))
+        token_embeddings = outputs[0]  # (batch, seq_len, 384)
 
         # Mean pooling over non-padding tokens
         mask_expanded = attention_mask[:, :, np.newaxis].astype(np.float32)
         summed = np.sum(token_embeddings * mask_expanded, axis=1)
         counts = np.clip(mask_expanded.sum(axis=1), a_min=1e-9, a_max=None)
-        embedding = summed / counts
+        embeddings = summed / counts
+
+        return _normalize_embeddings_batch(embeddings)
+
+    def _embed_single(self, text: str) -> np.ndarray:
+        """Embed a single text string."""
+        if not text or not text.strip():
+            return np.zeros(self.DEFAULT_DIMENSION, dtype=np.float32)
 
-        return _normalize_embedding(embedding[0])
+        embedding = self._embed_many([text])[0]
+        return cast(np.ndarray, embedding)
 
     async def embed(self, text: str) -> np.ndarray:
         """Generate an embedding for a single text."""
@@ -369,18 +386,40 @@ class OnnxLocalEmbedder:
             if self._session is None:
                 await asyncio.get_event_loop().run_in_executor(None, self._load_model)
 
-        return await asyncio.get_event_loop().run_in_executor(None, self._embed_single, text)
+        loop = asyncio.get_event_loop()
+        embedding = await loop.run_in_executor(None, self._embed_single, text)
+        return cast(np.ndarray, embedding)
 
     async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
         """Generate embeddings for multiple texts."""
+        if not texts:
+            return []
+
         async with self._lock:
             if self._session is None:
                 await asyncio.get_event_loop().run_in_executor(None, self._load_model)
 
-        results = []
-        for text in texts:
-            emb = await asyncio.get_event_loop().run_in_executor(None, self._embed_single, text)
-            results.append(emb)
+        non_empty_indices: list[int] = []
+        non_empty_texts: list[str] = []
+        for i, text in enumerate(texts):
+            if text and text.strip():
+                non_empty_indices.append(i)
+                non_empty_texts.append(text)
+
+        results: list[np.ndarray] = [
+            np.zeros(self.dimension, dtype=np.float32) for _ in range(len(texts))
+        ]
+        if not non_empty_texts:
+            return results
+
+        loop = asyncio.get_event_loop()
+        for start in range(0, len(non_empty_texts), self.MAX_BATCH_SIZE):
+            batch_texts = non_empty_texts[start : start + self.MAX_BATCH_SIZE]
+            batch_indices = non_empty_indices[start : start + self.MAX_BATCH_SIZE]
+            embeddings = await loop.run_in_executor(None, self._embed_many, batch_texts)
+            for idx, embedding in zip(batch_indices, embeddings):
+                results[idx] = embedding
+
         return results
 
     @property

headroom/memory/adapters/sqlite_vector.py

@@ -24,8 +24,8 @@ import struct
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from threading import RLock
-from typing import TYPE_CHECKING, Any
+from threading import RLock, get_ident
+from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
 
@@ -37,6 +37,8 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+_SQLITE_QUERY_CHUNK_SIZE = 500
+
 # sqlite-vec availability check
 _SQLITE_VEC_AVAILABLE: bool | None = None
 _sqlite_vec_module: Any = None
@@ -226,11 +228,12 @@ class SQLiteVectorIndex:
         self._db_path = Path(db_path)
         self._page_cache_size_kb = page_cache_size_kb
         self._lock = RLock()
+        self._connections: dict[int, sqlite3.Connection] = {}
 
         self._init_db()
 
-    def _get_conn(self) -> sqlite3.Connection:
-        """Get a database connection with sqlite-vec loaded."""
+    def _create_conn(self) -> sqlite3.Connection:
+        """Create a SQLite connection with sqlite-vec loaded."""
         conn = sqlite3.connect(str(self._db_path))
         conn.row_factory = sqlite3.Row
 
@@ -245,6 +248,98 @@ class SQLiteVectorIndex:
 
         return conn
 
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a cached per-thread SQLite connection with sqlite-vec loaded."""
+        thread_id = get_ident()
+        conn = self._connections.get(thread_id)
+        if conn is None:
+            conn = self._create_conn()
+            self._connections[thread_id] = conn
+        return conn
+
+    def _close_cached_connections(self) -> None:
+        """Close all cached SQLite connections."""
+        for conn in self._connections.values():
+            try:
+                conn.close()
+            except sqlite3.Error:
+                logger.debug("Failed to close cached sqlite-vec connection", exc_info=True)
+        self._connections.clear()
+
+    @staticmethod
+    def _chunked(items: list[Any], chunk_size: int = _SQLITE_QUERY_CHUNK_SIZE) -> list[list[Any]]:
+        """Split a list into SQLite-friendly chunks."""
+        return [items[i : i + chunk_size] for i in range(0, len(items), chunk_size)]
+
+    def _select_rowids_by_memory_ids(
+        self,
+        conn: sqlite3.Connection,
+        memory_ids: list[str],
+    ) -> dict[str, int]:
+        """Fetch rowids for the given memory IDs."""
+        rowids: dict[str, int] = {}
+        for chunk in self._chunked(memory_ids):
+            placeholders = ", ".join("?" for _ in chunk)
+            rows = conn.execute(
+                f"SELECT rowid, memory_id FROM vec_metadata WHERE memory_id IN ({placeholders})",
+                chunk,
+            ).fetchall()
+            for row in rows:
+                rowids[str(row["memory_id"])] = int(row["rowid"])
+        return rowids
+
+    def _prepare_memory_for_index(self, memory: Memory) -> tuple[np.ndarray, VectorMetadata]:
+        """Validate a memory and prepare it for indexing."""
+        if memory.embedding is None:
+            raise ValueError(f"Memory {memory.id} has no embedding")
+
+        embedding = np.asarray(memory.embedding, dtype=np.float32)
+        if embedding.shape[0] != self._dimension:
+            raise ValueError(
+                f"Embedding dimension {embedding.shape[0]} does not match "
+                f"index dimension {self._dimension}"
+            )
+
+        return embedding, VectorMetadata.from_memory(memory)
+
+    def _metadata_insert_params(self, memory_id: str, metadata: VectorMetadata) -> tuple[Any, ...]:
+        """Build INSERT parameters for vector metadata."""
+        return (
+            memory_id,
+            metadata.user_id,
+            metadata.session_id,
+            metadata.agent_id,
+            metadata.importance,
+            metadata.created_at.isoformat(),
+            metadata.valid_until.isoformat() if metadata.valid_until else None,
+            json.dumps(metadata.entity_refs),
+            metadata.content,
+            json.dumps(metadata.metadata or {}),
+        )
+
+    def _metadata_update_params(self, metadata: VectorMetadata, rowid: int) -> tuple[Any, ...]:
+        """Build UPDATE parameters for vector metadata."""
+        return (
+            metadata.user_id,
+            metadata.session_id,
+            metadata.agent_id,
+            metadata.importance,
+            metadata.created_at.isoformat(),
+            metadata.valid_until.isoformat() if metadata.valid_until else None,
+            json.dumps(metadata.entity_refs),
+            metadata.content,
+            json.dumps(metadata.metadata or {}),
+            rowid,
+        )
+
+    @staticmethod
+    def _cursor_lastrowid(cursor: sqlite3.Cursor) -> int:
+        """Return a non-null SQLite cursor lastrowid."""
+        rowid = cursor.lastrowid
+        if rowid is None:
+            raise RuntimeError("sqlite-vec insert did not produce a rowid")
+        return cast(int, rowid)
+
     def _init_db(self) -> None:
         """Initialize the database schema."""
         with self._get_conn() as conn:
@@ -320,37 +415,21 @@ class SQLiteVectorIndex:
         Raises:
             ValueError: If memory has no embedding or wrong dimension.
         """
-        if memory.embedding is None:
-            raise ValueError(f"Memory {memory.id} has no embedding")
-
-        embedding = np.asarray(memory.embedding, dtype=np.float32)
-        if embedding.shape[0] != self._dimension:
-            raise ValueError(
-                f"Embedding dimension {embedding.shape[0]} does not match "
-                f"index dimension {self._dimension}"
-            )
-
-        metadata = VectorMetadata.from_memory(memory)
+        embedding, metadata = self._prepare_memory_for_index(memory)
 
         with self._lock:
             with self._get_conn() as conn:
-                # Check if already exists
                 existing = conn.execute(
                     "SELECT rowid FROM vec_metadata WHERE memory_id = ?",
                     (memory.id,),
                 ).fetchone()
 
                 if existing:
-                    # Update existing entry
-                    rowid = existing[0]
-
-                    # Update vector
+                    rowid = int(existing[0])
                     conn.execute(
                         "UPDATE vec_embeddings SET embedding = ? WHERE rowid = ?",
                         (self._serialize_f32(embedding), rowid),
                     )
-
-                    # Update metadata
                     conn.execute(
                         """
                         UPDATE vec_metadata SET
@@ -359,22 +438,9 @@ class SQLiteVectorIndex:
                             entity_refs = ?, content = ?, metadata_json = ?
                         WHERE rowid = ?
                         """,
-                        (
-                            metadata.user_id,
-                            metadata.session_id,
-                            metadata.agent_id,
-                            metadata.importance,
-                            metadata.created_at.isoformat(),
-                            metadata.valid_until.isoformat() if metadata.valid_until else None,
-                            json.dumps(metadata.entity_refs),
-                            metadata.content,
-                            json.dumps(metadata.metadata or {}),
-                            rowid,
-                        ),
+                        self._metadata_update_params(metadata, rowid),
                     )
                 else:
-                    # Insert new entry
-                    # First insert metadata to get rowid
                     cursor = conn.execute(
                         """
                         INSERT INTO vec_metadata (
@@ -383,22 +449,9 @@ class SQLiteVectorIndex:
                             entity_refs, content, metadata_json
                         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                         """,
-                        (
-                            memory.id,
-                            metadata.user_id,
-                            metadata.session_id,
-                            metadata.agent_id,
-                            metadata.importance,
-                            metadata.created_at.isoformat(),
-                            metadata.valid_until.isoformat() if metadata.valid_until else None,
-                            json.dumps(metadata.entity_refs),
-                            metadata.content,
-                            json.dumps(metadata.metadata or {}),
-                        ),
+                        self._metadata_insert_params(memory.id, metadata),
                     )
-                    rowid = cursor.lastrowid
-
-                    # Insert vector with matching rowid
+                    rowid = self._cursor_lastrowid(cursor)
                     conn.execute(
                         "INSERT INTO vec_embeddings (rowid, embedding) VALUES (?, ?)",
                         (rowid, self._serialize_f32(embedding)),
@@ -415,15 +468,120 @@ class SQLiteVectorIndex:
         Returns:
             Number of memories indexed.
         """
-        indexed = 0
+        prepared: list[tuple[str, np.ndarray, VectorMetadata]] = []
         for memory in memories:
-            if memory.embedding is not None:
-                try:
-                    await self.index(memory)
-                    indexed += 1
-                except ValueError:
-                    pass
-        return indexed
+            try:
+                embedding, metadata = self._prepare_memory_for_index(memory)
+            except ValueError:
+                continue
+            prepared.append((memory.id, embedding, metadata))
+
+        if not prepared:
+            return 0
+
+        memory_ids = [memory_id for memory_id, _, _ in prepared]
+
+        with self._lock:
+            with self._get_conn() as conn:
+                if len(set(memory_ids)) != len(memory_ids):
+                    existing_rowids = self._select_rowids_by_memory_ids(
+                        conn, list(dict.fromkeys(memory_ids))
+                    )
+                    for memory_id, embedding, metadata in prepared:
+                        rowid = existing_rowids.get(memory_id)
+                        if rowid is None:
+                            cursor = conn.execute(
+                                """
+                                INSERT INTO vec_metadata (
+                                    memory_id, user_id, session_id, agent_id,
+                                    importance, created_at, valid_until,
+                                    entity_refs, content, metadata_json
+                                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                                """,
+                                self._metadata_insert_params(memory_id, metadata),
+                            )
+                            rowid = self._cursor_lastrowid(cursor)
+                            existing_rowids[memory_id] = rowid
+                            conn.execute(
+                                "INSERT INTO vec_embeddings (rowid, embedding) VALUES (?, ?)",
+                                (rowid, self._serialize_f32(embedding)),
+                            )
+                        else:
+                            conn.execute(
+                                "UPDATE vec_embeddings SET embedding = ? WHERE rowid = ?",
+                                (self._serialize_f32(embedding), rowid),
+                            )
+                            conn.execute(
+                                """
+                                UPDATE vec_metadata SET
+                                    user_id = ?, session_id = ?, agent_id = ?,
+                                    importance = ?, created_at = ?, valid_until = ?,
+                                    entity_refs = ?, content = ?, metadata_json = ?
+                                WHERE rowid = ?
+                                """,
+                                self._metadata_update_params(metadata, rowid),
+                            )
+
+                    conn.commit()
+                    return len(prepared)
+
+                existing_rowids = self._select_rowids_by_memory_ids(conn, memory_ids)
+                metadata_updates: list[tuple[Any, ...]] = []
+                vector_updates: list[tuple[bytes, int]] = []
+                metadata_inserts: list[tuple[Any, ...]] = []
+                new_memory_ids: list[str] = []
+                new_vectors: list[tuple[str, bytes]] = []
+
+                for memory_id, embedding, metadata in prepared:
+                    rowid = existing_rowids.get(memory_id)
+                    serialized = self._serialize_f32(embedding)
+                    if rowid is None:
+                        metadata_inserts.append(self._metadata_insert_params(memory_id, metadata))
+                        new_memory_ids.append(memory_id)
+                        new_vectors.append((memory_id, serialized))
+                    else:
+                        vector_updates.append((serialized, rowid))
+                        metadata_updates.append(self._metadata_update_params(metadata, rowid))
+
+                if vector_updates:
+                    conn.executemany(
+                        "UPDATE vec_embeddings SET embedding = ? WHERE rowid = ?",
+                        vector_updates,
+                    )
+                if metadata_updates:
+                    conn.executemany(
+                        """
+                        UPDATE vec_metadata SET
+                            user_id = ?, session_id = ?, agent_id = ?,
+                            importance = ?, created_at = ?, valid_until = ?,
+                            entity_refs = ?, content = ?, metadata_json = ?
+                        WHERE rowid = ?
+                        """,
+                        metadata_updates,
+                    )
+                if metadata_inserts:
+                    conn.executemany(
+                        """
+                        INSERT INTO vec_metadata (
+                            memory_id, user_id, session_id, agent_id,
+                            importance, created_at, valid_until,
+                            entity_refs, content, metadata_json
+                        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        """,
+                        metadata_inserts,
+                    )
+                    inserted_rowids = self._select_rowids_by_memory_ids(conn, new_memory_ids)
+                    conn.executemany(
+                        "INSERT INTO vec_embeddings (rowid, embedding) VALUES (?, ?)",
+                        [
+                            (inserted_rowids[memory_id], serialized)
+                            for memory_id, serialized in new_vectors
+                        ],
+                    )
+
+                conn.commit()
+
+        return len(prepared)
 
     async def remove(self, memory_id: str) -> bool:
         """Remove a memory from the index.
@@ -463,11 +621,30 @@ class SQLiteVectorIndex:
         Returns:
             Number removed.
         """
-        removed = 0
-        for memory_id in memory_ids:
-            if await self.remove(memory_id):
-                removed += 1
-        return removed
+        unique_ids = list(dict.fromkeys(memory_ids))
+        if not unique_ids:
+            return 0
+
+        with self._lock:
+            with self._get_conn() as conn:
+                rowids_by_memory_id = self._select_rowids_by_memory_ids(conn, unique_ids)
+                rowids = list(rowids_by_memory_id.values())
+                if not rowids:
+                    return 0
+
+                for rowid_chunk in self._chunked(rowids):
+                    placeholders = ", ".join("?" for _ in rowid_chunk)
+                    conn.execute(
+                        f"DELETE FROM vec_embeddings WHERE rowid IN ({placeholders})",
+                        rowid_chunk,
+                    )
+                    conn.execute(
+                        f"DELETE FROM vec_metadata WHERE rowid IN ({placeholders})",
+                        rowid_chunk,
+                    )
+
+                conn.commit()
+                return len(rowids)
 
     async def search(self, filter: VectorFilter) -> list[VectorSearchResult]:
         """Search for similar vectors.
@@ -746,4 +923,5 @@ class SQLiteVectorIndex:
 
     async def close(self) -> None:
         """Close the index (cleanup)."""
-        pass  # Connection-per-request pattern, nothing to close
+        with self._lock:
+            self._close_cached_connections()

headroom/memory/mcp_server.py

@@ -135,14 +135,16 @@ async def _warm_up_backend(backend: LocalBackend, user_id: str) -> None:
     if not all_memories:
         return
 
-    indexed = 0
-    for mem in all_memories:
-        if mem.embedding is None:
-            mem.embedding = await hm._embedder.embed(mem.content)
-            await hm._store.save(mem)
-        await hm._vector_index.index(mem)
-        indexed += 1
+    memories_missing_embeddings = [mem for mem in all_memories if mem.embedding is None]
+    if memories_missing_embeddings:
+        embeddings = await hm._embedder.embed_batch(
+            [mem.content for mem in memories_missing_embeddings]
+        )
+        for mem, embedding in zip(memories_missing_embeddings, embeddings):
+            mem.embedding = embedding
+        await hm._store.save_batch(memories_missing_embeddings)
 
+    indexed = await hm._vector_index.index_batch(all_memories)
     logger.info(f"Memory MCP: indexed {indexed} memories into vector store")
 
 

headroom/memory/traffic_learner.py

@@ -22,10 +22,12 @@ import asyncio
 import hashlib
 import json
 import logging
+import os
 import re
 import sqlite3
 import time
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -45,6 +47,20 @@ FLUSH_DEBOUNCE_SECONDS = 10.0
 # Matches POSIX paths (starts with /) and common Windows drive paths.
 _ABS_PATH_RE = re.compile(r"(?:[A-Za-z]:[\\/]|/)[\w./\\\-]+")
 
+# Error-recovery refinement: the Learned: error recovery section is capped,
+# decayed, and re-validated at render time. Other categories are untouched.
+_ERROR_RECOVERY_SECTION_CAP = 15
+_ERROR_RECOVERY_HALF_LIFE_DAYS = 5.0
+_ERROR_RECOVERY_HARD_FLOOR_DAYS = 21
+
+# Suffixes that vary between otherwise-identical Bash recoveries. Stripping
+# them before hashing collapses near-duplicates.
+_BASH_VOLATILE_SUFFIX_RE = re.compile(
+    r"(?:\s*\|\s*(?:head|tail)\s+-n?\s*\d+"
+    r"|\s+-A\s*\d+|\s+-B\s*\d+|\s+-C\s*\d+"
+    r"|\s+2>&1|\s+2>/dev/null)+\s*$"
+)
+
 
 # =============================================================================
 # Pattern Categories
@@ -87,10 +103,60 @@ class ExtractedPattern:
     entity_refs: list[str] = field(default_factory=list)
     metadata: dict[str, Any] = field(default_factory=dict)
     content_hash: str = ""
+    first_seen_at: datetime | None = None
+    last_seen_at: datetime | None = None
 
     def __post_init__(self) -> None:
         if not self.content_hash:
-            self.content_hash = hashlib.sha256(self.content.encode()).hexdigest()[:16]
+            key = _normalize_hash_key(self.category, self.content, self.metadata)
+            self.content_hash = hashlib.sha256(key.encode()).hexdigest()[:16]
+
+
+def _normalize_hash_key(
+    category: PatternCategory,
+    content: str,
+    metadata: dict[str, Any],
+) -> str:
+    """Build the string that feeds the content hash.
+
+    Error-recovery rows are collapsed on recovery intent, not literal text:
+    trivial invocation differences (tail counts, pipe suffixes, full paths
+    that share a basename) hash to the same key. Other categories hash the
+    raw content for backwards compatibility.
+    """
+    if category is not PatternCategory.ERROR_RECOVERY:
+        return content
+
+    tool = metadata.get("tool")
+    if tool == "Read":
+        error_path = metadata.get("error_path", "")
+        success_path = metadata.get("success_path", "")
+        return (
+            f"error_recovery|Read|{os.path.basename(error_path)}|{os.path.basename(success_path)}"
+        )
+    if tool == "Bash":
+        failed = metadata.get("failed_cmd", "")
+        success = metadata.get("success_cmd", "")
+        return (
+            f"error_recovery|Bash|"
+            f"{_normalize_bash_for_hash(failed)}|{_normalize_bash_for_hash(success)}"
+        )
+    return content
+
+
+def _normalize_bash_for_hash(cmd: str) -> str:
+    """Strip volatile suffixes and truncate at the first pipe/chain boundary."""
+    if not cmd:
+        return ""
+    # Drop paging, line-context flags, and redirections that vary between runs.
+    trimmed = _BASH_VOLATILE_SUFFIX_RE.sub("", cmd).strip()
+    # Cut at the first pipe or && so we hash the primary command, not the tail.
+    for sep in (" | ", " && "):
+        idx = trimmed.find(sep)
+        if idx != -1:
+            trimmed = trimmed[:idx].rstrip()
+            break
+    return trimmed
 
 
 # =============================================================================
@@ -389,6 +455,7 @@ class TrafficLearner:
         Evidence counts are summed across duplicates.
         """
         by_hash: dict[str, ExtractedPattern] = {}
+        now = datetime.now(timezone.utc)
 
         # Persisted rows from memory.db
         db_path = _resolve_backend_db_path(self._backend)
@@ -404,11 +471,15 @@ class TrafficLearner:
                 else:
                     by_hash[p.content_hash] = p
 
-        # In-memory accumulator (patterns not yet persisted)
+        # In-memory accumulator (patterns not yet persisted). Re-sightings in
+        # this session bump last_seen_at to "now" on top of the persisted
+        # timestamp so recency ranking reflects live activity.
         for pattern, count in self._pattern_counts.values():
             h = pattern.content_hash
             if h in by_hash:
-                by_hash[h].evidence_count += count
+                existing = by_hash[h]
+                existing.evidence_count += count
+                existing.last_seen_at = now
             else:
                 by_hash[h] = ExtractedPattern(
                     category=pattern.category,
@@ -418,6 +489,8 @@ class TrafficLearner:
                     entity_refs=list(pattern.entity_refs),
                     metadata=dict(pattern.metadata),
                     content_hash=pattern.content_hash,
+                    first_seen_at=now,
+                    last_seen_at=now,
                 )
 
         return list(by_hash.values())
@@ -578,7 +651,12 @@ class TrafficLearner:
                     content=content,
                     importance=0.7,
                     entity_refs=[success_path],
-                    metadata={"error_category": error_cat},
+                    metadata={
+                        "error_category": error_cat,
+                        "tool": "Read",
+                        "error_path": error_path,
+                        "success_path": success_path,
+                    },
                 )
         elif tool in ("Grep", "Glob"):
             error_pattern = error_entry["input"].get("pattern", "")
@@ -635,7 +713,12 @@ class TrafficLearner:
             content=content,
             importance=importance,
             entity_refs=entities,
-            metadata={"error_category": error_cat, "failed_cmd": failed_short},
+            metadata={
+                "error_category": error_cat,
+                "tool": "Bash",
+                "failed_cmd": failed_short,
+                "success_cmd": success_short,
+            },
         )
 
     def _extract_environment(self, entry: dict[str, Any]) -> list[ExtractedPattern]:
@@ -762,6 +845,7 @@ class TrafficLearner:
                 if self._backend is None:
                     continue
 
+                now_iso = datetime.now(timezone.utc).isoformat()
                 memory = await self._backend.save_memory(
                     content=pattern.content,
                     user_id=self._user_id,
@@ -770,6 +854,8 @@ class TrafficLearner:
                         "source": "traffic_learner",
                         "category": pattern.category.value,
                         "evidence_count": pattern.evidence_count,
+                        "first_seen_at": now_iso,
+                        "last_seen_at": now_iso,
                         **pattern.metadata,
                     },
                 )
@@ -796,7 +882,7 @@ class TrafficLearner:
         if db_path is None or not db_path.exists():
             return
 
-        def _read() -> list[tuple[str, str]]:
+        def _read() -> list[tuple[str, str, str]]:
             uri = f"file:{db_path}?mode=ro"
             try:
                 conn = sqlite3.connect(uri, uri=True)
@@ -804,7 +890,7 @@ class TrafficLearner:
                 return []
             try:
                 rows = conn.execute(
-                    "SELECT id, content FROM memories "
+                    "SELECT id, content, metadata FROM memories "
                     "WHERE json_extract(metadata, '$.source') = 'traffic_learner'"
                 ).fetchall()
             except sqlite3.DatabaseError:
@@ -814,7 +900,7 @@ class TrafficLearner:
                     conn.close()
                 except Exception:
                     pass
-            return [(row[0], row[1] or "") for row in rows]
+            return [(row[0], row[1] or "", row[2] or "{}") for row in rows]
 
         try:
             rows = await asyncio.to_thread(_read)
@@ -822,10 +908,24 @@ class TrafficLearner:
             logger.debug("Traffic learner hydrate failed: %s", e)
             return
 
-        for memory_id, content in rows:
+        for memory_id, content, metadata_json in rows:
             if not content:
                 continue
-            h = hashlib.sha256(content.encode()).hexdigest()[:16]
+            try:
+                metadata = json.loads(metadata_json) if metadata_json else {}
+            except json.JSONDecodeError:
+                metadata = {}
+            category_value = metadata.get("category")
+            try:
+                category = PatternCategory(category_value) if category_value else None
+            except ValueError:
+                category = None
+            if category is None:
+                # Legacy row without category — fall back to literal hash.
+                key = content
+            else:
+                key = _normalize_hash_key(category, content, metadata)
+            h = hashlib.sha256(key.encode()).hexdigest()[:16]
             self._saved_hashes.add(h)
             # If multiple rows share the same content (legacy duplicates),
             # last-wins — we only need one id to target the bump.
@@ -837,15 +937,18 @@ class TrafficLearner:
         if db_path is None or not db_path.exists():
             return
 
+        now_iso = datetime.now(timezone.utc).isoformat()
+
         def _bump() -> None:
             conn = sqlite3.connect(str(db_path))
             try:
                 conn.execute(
                     "UPDATE memories SET metadata = json_set("
                     "metadata, '$.evidence_count', "
-                    "COALESCE(json_extract(metadata, '$.evidence_count'), 0) + 1"
+                    "COALESCE(json_extract(metadata, '$.evidence_count'), 0) + 1, "
+                    "'$.last_seen_at', ?"
                     ") WHERE id = ?",
-                    (memory_id,),
+                    (now_iso, memory_id),
                 )
                 conn.commit()
             finally:
@@ -1007,7 +1110,7 @@ def _load_persisted_patterns_from_sqlite(db_path: Path) -> list[ExtractedPattern
     try:
         conn.row_factory = sqlite3.Row
         rows = conn.execute(
-            "SELECT content, metadata, entity_refs, importance "
+            "SELECT content, metadata, entity_refs, importance, created_at "
             "FROM memories "
             "WHERE json_extract(metadata, '$.source') = 'traffic_learner'"
         ).fetchall()
@@ -1045,12 +1148,24 @@ def _load_persisted_patterns_from_sqlite(db_path: Path) -> list[ExtractedPattern
         except (TypeError, ValueError):
             importance = 0.5
 
-        h = hashlib.sha256(content.encode()).hexdigest()[:16]
+        first_seen = _parse_iso_timestamp(meta.get("first_seen_at")) or _parse_iso_timestamp(
+            row["created_at"]
+        )
+        last_seen = _parse_iso_timestamp(meta.get("last_seen_at")) or first_seen
+
+        key = _normalize_hash_key(category, content, meta)
+        h = hashlib.sha256(key.encode()).hexdigest()[:16]
         if h in patterns:
             existing = patterns[h]
             existing.evidence_count += evidence
             if importance > existing.importance:
                 existing.importance = importance
+            if last_seen and (existing.last_seen_at is None or last_seen > existing.last_seen_at):
+                existing.last_seen_at = last_seen
+            if first_seen and (
+                existing.first_seen_at is None or first_seen < existing.first_seen_at
+            ):
+                existing.first_seen_at = first_seen
         else:
             patterns[h] = ExtractedPattern(
                 category=category,
@@ -1060,11 +1175,26 @@ def _load_persisted_patterns_from_sqlite(db_path: Path) -> list[ExtractedPattern
                 entity_refs=list(entity_refs),
                 metadata=meta,
                 content_hash=h,
+                first_seen_at=first_seen,
+                last_seen_at=last_seen,
             )
 
     return list(patterns.values())
 
 
+def _parse_iso_timestamp(value: Any) -> datetime | None:
+    """Parse an ISO-8601 timestamp stored as TEXT. Returns None on any failure."""
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
 def _patterns_to_recommendations(patterns: list[ExtractedPattern]) -> list:
     """Group patterns by category into one Recommendation per category.
 
@@ -1086,8 +1216,13 @@ def _patterns_to_recommendations(patterns: list[ExtractedPattern]) -> list:
             if target_str == "context_file"
             else RecommendationTarget.MEMORY_FILE
         )
-        # Sort by evidence_count desc so the most-supported rules appear first.
-        items.sort(key=lambda p: p.evidence_count, reverse=True)
+        if category is PatternCategory.ERROR_RECOVERY:
+            items = _refine_error_recovery(items)
+        else:
+            # Sort by evidence_count desc so the most-supported rules appear first.
+            items.sort(key=lambda p: p.evidence_count, reverse=True)
+        if not items:
+            continue
         bullets = "\n".join(f"- {p.content}" for p in items)
         recs.append(
             Recommendation(
@@ -1099,3 +1234,99 @@ def _patterns_to_recommendations(patterns: list[ExtractedPattern]) -> list:
             )
         )
     return recs
+
+
+def _refine_error_recovery(patterns: list[ExtractedPattern]) -> list[ExtractedPattern]:
+    """Apply the render-time pipeline for error_recovery patterns.
+
+    Pipeline: hard-floor drop by last_seen_at, re-validate Read success
+    paths against the filesystem, collapse ambiguous error_paths into a
+    single "search first" hint, rank by recency-weighted evidence, and
+    cap the section at _ERROR_RECOVERY_SECTION_CAP bullets.
+    """
+    now = datetime.now(timezone.utc)
+
+    # 1. Hard floor — drop rows not re-observed in the last N days.
+    alive: list[ExtractedPattern] = []
+    for p in patterns:
+        last_seen = p.last_seen_at or p.first_seen_at
+        if last_seen is None:
+            # No timestamp — treat as just-seen so it survives one render.
+            alive.append(p)
+            continue
+        age_days = (now - last_seen).total_seconds() / 86400.0
+        if age_days <= _ERROR_RECOVERY_HARD_FLOOR_DAYS:
+            alive.append(p)
+
+    # 2. Re-validate Read recoveries — drop if success_path no longer exists.
+    validated: list[ExtractedPattern] = []
+    for p in alive:
+        if p.metadata.get("tool") == "Read":
+            success_path = p.metadata.get("success_path")
+            if success_path:
+                try:
+                    if not Path(success_path).exists():
+                        continue
+                except OSError:
+                    # Path check failed (permissions, etc.) — keep the row
+                    # rather than drop on a transient error.
+                    pass
+        validated.append(p)
+
+    # 3. Collision-collapse — same error_path with >=2 distinct success_paths
+    #    is an ambiguity signal, not N separate lessons. Replace the group
+    #    with one synthesized "search first" bullet.
+    read_groups: dict[str, list[ExtractedPattern]] = {}
+    others: list[ExtractedPattern] = []
+    for p in validated:
+        if p.metadata.get("tool") == "Read" and p.metadata.get("error_path"):
+            read_groups.setdefault(p.metadata["error_path"], []).append(p)
+        else:
+            others.append(p)
+
+    collapsed: list[ExtractedPattern] = list(others)
+    for error_path, group in read_groups.items():
+        distinct_targets = {g.metadata.get("success_path") for g in group}
+        distinct_targets.discard(None)
+        if len(group) >= 2 and len(distinct_targets) >= 2:
+            basename = os.path.basename(error_path) or error_path
+            synth_content = (
+                f"Path `{basename}` has been guessed wrong repeatedly — "
+                f"use Glob/Grep to locate before reading."
+            )
+            max_last_seen = max(
+                (g.last_seen_at for g in group if g.last_seen_at),
+                default=now,
+            )
+            collapsed.append(
+                ExtractedPattern(
+                    category=PatternCategory.ERROR_RECOVERY,
+                    content=synth_content,
+                    importance=max(g.importance for g in group),
+                    evidence_count=sum(g.evidence_count for g in group),
+                    metadata={
+                        "tool": "Read",
+                        "error_path": error_path,
+                        "collapsed": True,
+                    },
+                    last_seen_at=max_last_seen,
+                    first_seen_at=min(
+                        (g.first_seen_at for g in group if g.first_seen_at),
+                        default=max_last_seen,
+                    ),
+                )
+            )
+        else:
+            collapsed.extend(group)
+
+    # 4. Recency-weighted score.
+    def _score(p: ExtractedPattern) -> float:
+        last_seen = p.last_seen_at or p.first_seen_at or now
+        age_days = max(0.0, (now - last_seen).total_seconds() / 86400.0)
+        decay = float(0.5 ** (age_days / _ERROR_RECOVERY_HALF_LIFE_DAYS))
+        return float(p.evidence_count) * decay
+
+    collapsed.sort(key=_score, reverse=True)
+
+    # 5. Cap the section.
+    return collapsed[:_ERROR_RECOVERY_SECTION_CAP]

headroom/providers/aider/install.py

@@ -1,12 +1,12 @@
-"""Aider install-time helpers."""
-
-from __future__ import annotations
-
-from .runtime import build_launch_env
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Aider."""
-    del backend
-    env, _lines = build_launch_env(port=port, environ={})
-    return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}
+"""Aider install-time helpers."""
+
+from __future__ import annotations
+
+from .runtime import build_launch_env
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Aider."""
+    del backend
+    env, _lines = build_launch_env(port=port, environ={})
+    return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}

headroom/providers/claude/install.py

@@ -1,63 +1,63 @@
-"""Claude install-time helpers."""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import claude_settings_path
-
-from .runtime import proxy_base_url
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Claude."""
-    del backend
-    return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
-    """Apply Claude provider-scope configuration when requested."""
-    if manifest.scope != ConfigScope.PROVIDER.value:
-        return None
-
-    path = claude_settings_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    payload: dict[str, object] = {}
-    if path.exists():
-        payload = json.loads(path.read_text())
-    env = payload.get("env")
-    env_map = dict(env) if isinstance(env, dict) else {}
-    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
-    previous = {name: env_map.get(name) for name in values}
-    env_map.update(values)
-    payload["env"] = env_map
-    path.write_text(json.dumps(payload, indent=2) + "\n")
-    return ManagedMutation(
-        target=ToolTarget.CLAUDE.value,
-        kind="json-env",
-        path=str(path),
-        data={"previous": previous},
-    )
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Revert Claude provider-scope configuration."""
-    if not mutation.path:
-        return
-    path = Path(mutation.path)
-    if not path.exists():
-        return
-    payload = json.loads(path.read_text())
-    env = payload.get("env")
-    env_map = dict(env) if isinstance(env, dict) else {}
-    previous: dict[str, object] = mutation.data.get("previous", {})
-    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
-    for name in values:
-        if previous.get(name) is None:
-            env_map.pop(name, None)
-        else:
-            env_map[name] = previous[name]
-    payload["env"] = env_map
-    path.write_text(json.dumps(payload, indent=2) + "\n")
+"""Claude install-time helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import claude_settings_path
+
+from .runtime import proxy_base_url
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Claude."""
+    del backend
+    return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
+    """Apply Claude provider-scope configuration when requested."""
+    if manifest.scope != ConfigScope.PROVIDER.value:
+        return None
+
+    path = claude_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, object] = {}
+    if path.exists():
+        payload = json.loads(path.read_text())
+    env = payload.get("env")
+    env_map = dict(env) if isinstance(env, dict) else {}
+    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
+    previous = {name: env_map.get(name) for name in values}
+    env_map.update(values)
+    payload["env"] = env_map
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+    return ManagedMutation(
+        target=ToolTarget.CLAUDE.value,
+        kind="json-env",
+        path=str(path),
+        data={"previous": previous},
+    )
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Revert Claude provider-scope configuration."""
+    if not mutation.path:
+        return
+    path = Path(mutation.path)
+    if not path.exists():
+        return
+    payload = json.loads(path.read_text())
+    env = payload.get("env")
+    env_map = dict(env) if isinstance(env, dict) else {}
+    previous: dict[str, object] = mutation.data.get("previous", {})
+    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
+    for name in values:
+        if previous.get(name) is None:
+            env_map.pop(name, None)
+        else:
+            env_map[name] = previous[name]
+    payload["env"] = env_map
+    path.write_text(json.dumps(payload, indent=2) + "\n")

headroom/providers/codex/install.py

@@ -1,68 +1,68 @@
-"""Codex install-time helpers."""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import codex_config_path
-
-from .runtime import proxy_base_url
-
-_CODEX_MARKER_START = "# --- Headroom persistent provider ---"
-_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"
-_CODEX_PATTERN = re.compile(
-    re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),
-    re.DOTALL,
-)
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Codex."""
-    del backend
-    return {"OPENAI_BASE_URL": proxy_base_url(port)}
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
-    """Apply Codex provider-scope configuration when requested."""
-    if manifest.scope != ConfigScope.PROVIDER.value:
-        return None
-
-    path = codex_config_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    section = (
-        f"{_CODEX_MARKER_START}\n"
-        'model_provider = "headroom"\n\n'
-        "[model_providers.headroom]\n"
-        'name = "Headroom persistent proxy"\n'
-        f'base_url = "{proxy_base_url(manifest.port)}"\n'
-        'env_key = "OPENAI_API_KEY"\n'
-        "requires_openai_auth = true\n"
-        "supports_websockets = true\n"
-        f"{_CODEX_MARKER_END}\n"
-    )
-    if path.exists():
-        existing = path.read_text()
-        if _CODEX_MARKER_START in existing:
-            merged = _CODEX_PATTERN.sub(section, existing)
-        else:
-            merged = existing.rstrip() + "\n\n" + section + "\n"
-    else:
-        merged = section + "\n"
-    path.write_text(merged)
-    return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Revert Codex provider-scope configuration."""
-    del manifest
-    if not mutation.path:
-        return
-    path = Path(mutation.path)
-    if not path.exists():
-        return
-    content = path.read_text()
-    if _CODEX_MARKER_START not in content:
-        return
-    path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")
+"""Codex install-time helpers."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import codex_config_path
+
+from .runtime import proxy_base_url
+
+_CODEX_MARKER_START = "# --- Headroom persistent provider ---"
+_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"
+_CODEX_PATTERN = re.compile(
+    re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),
+    re.DOTALL,
+)
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Codex."""
+    del backend
+    return {"OPENAI_BASE_URL": proxy_base_url(port)}
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
+    """Apply Codex provider-scope configuration when requested."""
+    if manifest.scope != ConfigScope.PROVIDER.value:
+        return None
+
+    path = codex_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    section = (
+        f"{_CODEX_MARKER_START}\n"
+        'model_provider = "headroom"\n\n'
+        "[model_providers.headroom]\n"
+        'name = "Headroom persistent proxy"\n'
+        f'base_url = "{proxy_base_url(manifest.port)}"\n'
+        'env_key = "OPENAI_API_KEY"\n'
+        "requires_openai_auth = true\n"
+        "supports_websockets = true\n"
+        f"{_CODEX_MARKER_END}\n"
+    )
+    if path.exists():
+        existing = path.read_text()
+        if _CODEX_MARKER_START in existing:
+            merged = _CODEX_PATTERN.sub(section, existing)
+        else:
+            merged = existing.rstrip() + "\n\n" + section + "\n"
+    else:
+        merged = section + "\n"
+    path.write_text(merged)
+    return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Revert Codex provider-scope configuration."""
+    del manifest
+    if not mutation.path:
+        return
+    path = Path(mutation.path)
+    if not path.exists():
+        return
+    content = path.read_text()
+    if _CODEX_MARKER_START not in content:
+        return
+    path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")

headroom/providers/copilot/install.py

@@ -1,25 +1,25 @@
-"""Copilot install-time helpers."""
-
-from __future__ import annotations
-
-from .wrap import build_launch_env, resolve_provider_type
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Copilot."""
-    provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})
-    env, _lines = build_launch_env(
-        port=port,
-        provider_type=provider_type,
-        wire_api=None,
-        environ={},
-    )
-    return {
-        key: env[key]
-        for key in (
-            "COPILOT_PROVIDER_TYPE",
-            "COPILOT_PROVIDER_BASE_URL",
-            "COPILOT_PROVIDER_WIRE_API",
-        )
-        if key in env
-    }
+"""Copilot install-time helpers."""
+
+from __future__ import annotations
+
+from .wrap import build_launch_env, resolve_provider_type
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Copilot."""
+    provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})
+    env, _lines = build_launch_env(
+        port=port,
+        provider_type=provider_type,
+        wire_api=None,
+        environ={},
+    )
+    return {
+        key: env[key]
+        for key in (
+            "COPILOT_PROVIDER_TYPE",
+            "COPILOT_PROVIDER_BASE_URL",
+            "COPILOT_PROVIDER_WIRE_API",
+        )
+        if key in env
+    }

headroom/providers/cursor/install.py

@@ -1,15 +1,15 @@
-"""Cursor install-time helpers."""
-
-from __future__ import annotations
-
-from .runtime import build_proxy_targets
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Cursor."""
-    del backend
-    targets = build_proxy_targets(port)
-    return {
-        "OPENAI_BASE_URL": targets.openai_base_url,
-        "ANTHROPIC_BASE_URL": targets.anthropic_base_url,
-    }
+"""Cursor install-time helpers."""
+
+from __future__ import annotations
+
+from .runtime import build_proxy_targets
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Cursor."""
+    del backend
+    targets = build_proxy_targets(port)
+    return {
+        "OPENAI_BASE_URL": targets.openai_base_url,
+        "ANTHROPIC_BASE_URL": targets.anthropic_base_url,
+    }

headroom/providers/install_registry.py

@@ -1,86 +1,86 @@
-"""Install-time provider registry helpers."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-
-from headroom.install.models import DeploymentManifest, ManagedMutation
-from headroom.providers.aider.install import build_install_env as _build_aider_install_env
-from headroom.providers.claude.install import (
-    apply_provider_scope as _apply_claude_provider_scope,
-)
-from headroom.providers.claude.install import (
-    build_install_env as _build_claude_install_env,
-)
-from headroom.providers.claude.install import (
-    revert_provider_scope as _revert_claude_provider_scope,
-)
-from headroom.providers.codex.install import (
-    apply_provider_scope as _apply_codex_provider_scope,
-)
-from headroom.providers.codex.install import build_install_env as _build_codex_install_env
-from headroom.providers.codex.install import (
-    revert_provider_scope as _revert_codex_provider_scope,
-)
-from headroom.providers.copilot.install import (
-    build_install_env as _build_copilot_install_env,
-)
-from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env
-from headroom.providers.openclaw.install import (
-    apply_provider_scope as _apply_openclaw_provider_scope,
-)
-from headroom.providers.openclaw.install import (
-    revert_provider_scope as _revert_openclaw_provider_scope,
-)
-
-_InstallEnvBuilder = Callable[..., dict[str, str]]
-_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
-_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]
-
-_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
-    "claude": _build_claude_install_env,
-    "copilot": _build_copilot_install_env,
-    "codex": _build_codex_install_env,
-    "aider": _build_aider_install_env,
-    "cursor": _build_cursor_install_env,
-}
-
-_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {
-    "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),
-    "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),
-    "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),
-}
-
-
-def build_install_target_envs(
-    port: int, backend: str, targets: list[str]
-) -> dict[str, dict[str, str]]:
-    """Build per-target install environment values via provider slices."""
-    target_envs: dict[str, dict[str, str]] = {}
-    for target in targets:
-        builder = _ENV_BUILDERS.get(target)
-        if builder is None:
-            continue
-        target_envs[target] = builder(port=port, backend=backend)
-    return target_envs
-
-
-def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    """Apply provider-scope mutations owned by provider slices."""
-    mutations: list[ManagedMutation] = []
-    for target in manifest.targets:
-        handlers = _PROVIDER_SCOPE_HANDLERS.get(target)
-        if handlers is None:
-            continue
-        mutation = handlers[0](manifest)
-        if mutation is not None:
-            mutations.append(mutation)
-    return mutations
-
-
-def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:
-    """Revert a provider-scope mutation via the owning provider slice."""
-    handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)
-    if handlers is None:
-        return
-    handlers[1](mutation, manifest)
+"""Install-time provider registry helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from headroom.install.models import DeploymentManifest, ManagedMutation
+from headroom.providers.aider.install import build_install_env as _build_aider_install_env
+from headroom.providers.claude.install import (
+    apply_provider_scope as _apply_claude_provider_scope,
+)
+from headroom.providers.claude.install import (
+    build_install_env as _build_claude_install_env,
+)
+from headroom.providers.claude.install import (
+    revert_provider_scope as _revert_claude_provider_scope,
+)
+from headroom.providers.codex.install import (
+    apply_provider_scope as _apply_codex_provider_scope,
+)
+from headroom.providers.codex.install import build_install_env as _build_codex_install_env
+from headroom.providers.codex.install import (
+    revert_provider_scope as _revert_codex_provider_scope,
+)
+from headroom.providers.copilot.install import (
+    build_install_env as _build_copilot_install_env,
+)
+from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env
+from headroom.providers.openclaw.install import (
+    apply_provider_scope as _apply_openclaw_provider_scope,
+)
+from headroom.providers.openclaw.install import (
+    revert_provider_scope as _revert_openclaw_provider_scope,
+)
+
+_InstallEnvBuilder = Callable[..., dict[str, str]]
+_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
+_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]
+
+_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
+    "claude": _build_claude_install_env,
+    "copilot": _build_copilot_install_env,
+    "codex": _build_codex_install_env,
+    "aider": _build_aider_install_env,
+    "cursor": _build_cursor_install_env,
+}
+
+_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {
+    "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),
+    "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),
+    "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),
+}
+
+
+def build_install_target_envs(
+    port: int, backend: str, targets: list[str]
+) -> dict[str, dict[str, str]]:
+    """Build per-target install environment values via provider slices."""
+    target_envs: dict[str, dict[str, str]] = {}
+    for target in targets:
+        builder = _ENV_BUILDERS.get(target)
+        if builder is None:
+            continue
+        target_envs[target] = builder(port=port, backend=backend)
+    return target_envs
+
+
+def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    """Apply provider-scope mutations owned by provider slices."""
+    mutations: list[ManagedMutation] = []
+    for target in manifest.targets:
+        handlers = _PROVIDER_SCOPE_HANDLERS.get(target)
+        if handlers is None:
+            continue
+        mutation = handlers[0](manifest)
+        if mutation is not None:
+            mutations.append(mutation)
+    return mutations
+
+
+def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:
+    """Revert a provider-scope mutation via the owning provider slice."""
+    handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)
+    if handlers is None:
+        return
+    handlers[1](mutation, manifest)

headroom/providers/openclaw/install.py

@@ -1,50 +1,50 @@
-"""OpenClaw install-time helpers."""
-
-from __future__ import annotations
-
-import click
-
-from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import openclaw_config_path
-from headroom.install.runtime import resolve_headroom_command
-
-
-def shutil_which(name: str) -> str | None:
-    from shutil import which
-
-    return which(name)
-
-
-def _invoke_openclaw(command: list[str]) -> None:
-    import subprocess
-
-    subprocess.run(command, check=True)
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:
-    """Configure OpenClaw to route through the persistent proxy."""
-    if not shutil_which("openclaw"):
-        raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")
-    command = [
-        *resolve_headroom_command(),
-        "wrap",
-        "openclaw",
-        "--no-auto-start",
-        "--proxy-port",
-        str(manifest.port),
-    ]
-    _invoke_openclaw(command)
-    return ManagedMutation(
-        target=ToolTarget.OPENCLAW.value,
-        kind="openclaw-wrap",
-        path=str(openclaw_config_path()),
-    )
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Undo OpenClaw persistent proxy configuration."""
-    del mutation, manifest
-    if not shutil_which("openclaw"):
-        return
-    command = [*resolve_headroom_command(), "unwrap", "openclaw"]
-    _invoke_openclaw(command)
+"""OpenClaw install-time helpers."""
+
+from __future__ import annotations
+
+import click
+
+from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import openclaw_config_path
+from headroom.install.runtime import resolve_headroom_command
+
+
+def shutil_which(name: str) -> str | None:
+    from shutil import which
+
+    return which(name)
+
+
+def _invoke_openclaw(command: list[str]) -> None:
+    import subprocess
+
+    subprocess.run(command, check=True)
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:
+    """Configure OpenClaw to route through the persistent proxy."""
+    if not shutil_which("openclaw"):
+        raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")
+    command = [
+        *resolve_headroom_command(),
+        "wrap",
+        "openclaw",
+        "--no-auto-start",
+        "--proxy-port",
+        str(manifest.port),
+    ]
+    _invoke_openclaw(command)
+    return ManagedMutation(
+        target=ToolTarget.OPENCLAW.value,
+        kind="openclaw-wrap",
+        path=str(openclaw_config_path()),
+    )
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Undo OpenClaw persistent proxy configuration."""
+    del mutation, manifest
+    if not shutil_which("openclaw"):
+        return
+    command = [*resolve_headroom_command(), "unwrap", "openclaw"]
+    _invoke_openclaw(command)

headroom/proxy/handlers/anthropic.py

@@ -315,6 +315,7 @@ class AnthropicHandlerMixin:
             MAX_REQUEST_BODY_SIZE,
             _get_image_compressor,
             _read_request_json,
+            compute_turn_id,
         )
         from headroom.proxy.models import RequestLog
         from headroom.proxy.modes import is_cache_mode, is_token_mode
@@ -1348,6 +1349,9 @@ class AnthropicHandlerMixin:
                                     request_messages=body.get("messages")
                                     if self.config.log_full_messages
                                     else None,
+                                    turn_id=compute_turn_id(
+                                        model, body.get("system"), body.get("messages")
+                                    ),
                                 )
                             )
 
@@ -1818,6 +1822,9 @@ class AnthropicHandlerMixin:
                                 request_messages=messages
                                 if self.config.log_full_messages
                                 else None,
+                                turn_id=compute_turn_id(
+                                    model, body.get("system"), body.get("messages")
+                                ),
                             )
                         )
 

headroom/proxy/handlers/streaming.py

@@ -13,7 +13,7 @@ import time
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
-from headroom.proxy.helpers import jitter_delay_ms
+from headroom.proxy.helpers import compute_turn_id, jitter_delay_ms
 
 if TYPE_CHECKING:
     from fastapi.responses import Response, StreamingResponse
@@ -1044,6 +1044,9 @@ class StreamingMixin:
                             request_messages=body.get("messages")
                             if self.config.log_full_messages
                             else None,
+                            turn_id=compute_turn_id(
+                                model, body.get("system"), body.get("messages")
+                            ),
                         )
                     )
 

headroom/proxy/helpers.py

@@ -8,6 +8,7 @@ Extracted from server.py for maintainability.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import logging
 import random
@@ -278,3 +279,86 @@ async def _read_request_json(request: Request) -> dict[str, Any]:
     if not isinstance(result, dict):
         raise ValueError("Request body must be a JSON object, not " + type(result).__name__)
     return result
+
+
+def _strip_per_call_annotations(obj: Any) -> Any:
+    """Remove annotations that clients mutate between calls in one agent loop.
+
+    ``cache_control`` is the main offender: clients (notably Claude Code)
+    move the cache breakpoint to the newest message on each call, which
+    means the exact same user-text message carries ``cache_control`` on
+    call 1 and not on call 2. Hashing the raw message dicts therefore
+    produces a different turn_id for every iteration of a single agent
+    loop, collapsing ``turn_id`` to effectively ``request_id`` and
+    breaking prompt-level aggregation downstream.
+    """
+    if isinstance(obj, dict):
+        return {k: _strip_per_call_annotations(v) for k, v in obj.items() if k != "cache_control"}
+    if isinstance(obj, list):
+        return [_strip_per_call_annotations(item) for item in obj]
+    return obj
+
+
+def compute_turn_id(
+    model: str,
+    system: Any,
+    messages: list[dict[str, Any]] | None,
+) -> str | None:
+    """Group all agent-loop API calls triggered by a single user prompt.
+
+    A turn spans the user's text prompt plus every assistant tool-use and
+    user tool-result message the agent appends while executing that prompt.
+    Hashing the prefix up to and including the last user *text* message yields
+    an id that is stable across the turn but rolls over when the user sends a
+    new prompt.
+
+    Returns None when no user-text message is present (nothing to identify).
+    """
+    if not messages:
+        return None
+
+    last_text_user_idx: int | None = None
+    for i in range(len(messages) - 1, -1, -1):
+        msg = messages[i]
+        if not isinstance(msg, dict) or msg.get("role") != "user":
+            continue
+        content = msg.get("content")
+        if isinstance(content, str) and content:
+            last_text_user_idx = i
+            break
+        if isinstance(content, list):
+            has_text = any(
+                isinstance(block, dict) and block.get("type") == "text" for block in content
+            )
+            has_tool_result = any(
+                isinstance(block, dict) and block.get("type") == "tool_result" for block in content
+            )
+            # An agent-loop continuation carries tool_result blocks; only a
+            # fresh user turn is text-only.
+            if has_text and not has_tool_result:
+                last_text_user_idx = i
+                break
+
+    if last_text_user_idx is None:
+        return None
+
+    prefix = _strip_per_call_annotations(messages[: last_text_user_idx + 1])
+    try:
+        prefix_json = json.dumps(prefix, sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        return None
+
+    h = hashlib.sha256()
+    h.update(model.encode("utf-8", errors="replace"))
+    h.update(b"\0")
+    if isinstance(system, str):
+        h.update(system.encode("utf-8", errors="replace"))
+    elif system is not None:
+        try:
+            normalized_system = _strip_per_call_annotations(system)
+            h.update(json.dumps(normalized_system, sort_keys=True, default=str).encode("utf-8"))
+        except (TypeError, ValueError):
+            pass
+    h.update(b"\0")
+    h.update(prefix_json.encode("utf-8", errors="replace"))
+    return h.hexdigest()[:16]

headroom/proxy/models.py

@@ -50,6 +50,11 @@ class RequestLog:
     response_content: str | None = None
     error: str | None = None
 
+    # Groups every agent-loop API call from one user prompt into a single turn.
+    # See ``headroom.proxy.helpers.compute_turn_id`` for the derivation. None
+    # when no user-text message is present in the request.
+    turn_id: str | None = None
+
     # NOTE (Unit 2 follow-up): stage timings and session_id were briefly
     # added here but are now emitted exclusively through
     # ``emit_stage_timings_log`` (structured log line) and Prometheus.

headroom/release_version.py

@@ -1,310 +1,310 @@
-"""Release version helpers for the GitHub Actions release workflow."""
-
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from collections.abc import Sequence
-from dataclasses import dataclass, replace
-from pathlib import Path
-
-SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
-RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")
-CONVENTIONAL_COMMIT_RE = re.compile(
-    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
-)
-BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
-FIELD_SEP = "\x1f"
-RECORD_SEP = "\x1e"
-GIT_LOG_FORMAT = "%s%x1f%b%x1e"
-BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}
-
-
-@dataclass(frozen=True, order=True)
-class SemVer:
-    """Semantic version tuple with simple bump helpers."""
-
-    major: int
-    minor: int
-    patch: int
-
-    @classmethod
-    def parse(cls, value: str) -> SemVer:
-        match = SEMVER_RE.match(value)
-        if not match:
-            raise ValueError(f"Invalid semantic version: {value}")
-        return cls(*(int(part) for part in match.groups()))
-
-    def bump(self, level: str) -> SemVer:
-        if level == "major":
-            return SemVer(self.major + 1, 0, 0)
-        if level == "minor":
-            return SemVer(self.major, self.minor + 1, 0)
-        if level == "patch":
-            return SemVer(self.major, self.minor, self.patch + 1)
-        raise ValueError(f"Unsupported bump level: {level}")
-
-    def __str__(self) -> str:
-        return f"{self.major}.{self.minor}.{self.patch}"
-
-
-@dataclass(frozen=True)
-class ReleaseVersionInfo:
-    """Workflow outputs for release version calculation."""
-
-    version: str
-    npm_version: str
-    canonical: str
-    height: str
-    bump: str
-    previous_tag: str
-
-    def as_outputs(self) -> dict[str, str]:
-        return {
-            "version": self.version,
-            "npm_version": self.npm_version,
-            "canonical": self.canonical,
-            "height": self.height,
-            "bump": self.bump,
-            "previous_tag": self.previous_tag,
-        }
-
-
-@dataclass(frozen=True, order=True)
-class ReleaseTag:
-    """Parsed release tag metadata used for sorting and normalization."""
-
-    version: SemVer
-    legacy_height: int = -1
-    raw: str = ""
-
-
-@dataclass(frozen=True)
-class CommitInfo:
-    """Commit subject/body pair used for bump detection."""
-
-    subject: str
-    body: str = ""
-
-
-def parse_release_tag(tag: str) -> ReleaseTag:
-    """Parse a release tag, preserving legacy fourth-component ordering."""
-
-    match = RELEASE_TAG_RE.match(tag)
-    if not match:
-        raise ValueError(f"Invalid release tag: {tag}")
-    major, minor, patch, extra = match.groups()
-    return ReleaseTag(
-        version=SemVer(int(major), int(minor), int(patch)),
-        legacy_height=int(extra) if extra is not None else -1,
-        raw=tag,
-    )
-
-
-def normalize_release_tag(tag: str) -> SemVer:
-    """Collapse historic 4-part release tags into their base semantic version."""
-
-    return parse_release_tag(tag).version
-
-
-def find_latest_release_tag(tags: Sequence[str]) -> str | None:
-    """Return the latest release tag after normalizing legacy 4-part tags."""
-
-    candidates: list[ReleaseTag] = []
-    for tag in tags:
-        if RELEASE_TAG_RE.match(tag):
-            candidates.append(parse_release_tag(tag))
-    if not candidates:
-        return None
-    candidates.sort(reverse=True)
-    return candidates[0].raw
-
-
-def _merge_summary(subject: str, body: str) -> str:
-    """Return the first meaningful body line for merge commits."""
-
-    if not subject.startswith("Merge "):
-        return ""
-    for line in body.splitlines():
-        stripped = line.strip()
-        if stripped:
-            return stripped
-    return ""
-
-
-def classify_commit_bump(commit: CommitInfo) -> str:
-    """Classify one commit using conventional commit semantics."""
-
-    merge_summary = _merge_summary(commit.subject, commit.body)
-    candidates = [commit.subject]
-    if merge_summary:
-        candidates.insert(0, merge_summary)
-
-    has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))
-    for candidate in candidates:
-        match = CONVENTIONAL_COMMIT_RE.match(candidate)
-        if not match:
-            continue
-        if has_breaking_change or bool(match.group(3)):
-            return "major"
-        if match.group(1) == "feat":
-            return "minor"
-        return "patch"
-
-    if has_breaking_change:
-        return "major"
-    return "patch"
-
-
-def determine_bump_level(commits: Sequence[CommitInfo]) -> str:
-    """Return the highest required bump across a commit range."""
-
-    level = "patch"
-    for commit in commits:
-        candidate = classify_commit_bump(commit)
-        if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:
-            level = candidate
-    return level
-
-
-def compute_release_version(
-    canonical_version: str,
-    level: str,
-    tags: Sequence[str],
-    manual_version: str = "",
-) -> ReleaseVersionInfo:
-    """Compute the next release version from the canonical version and existing tags."""
-
-    if manual_version:
-        manual = str(SemVer.parse(manual_version))
-        return ReleaseVersionInfo(
-            version=manual,
-            npm_version=manual,
-            canonical=canonical_version,
-            height="0",
-            bump="manual",
-            previous_tag="",
-        )
-
-    canonical = SemVer.parse(canonical_version)
-    previous_tag = find_latest_release_tag(tags)
-    current = canonical
-    if previous_tag is not None:
-        current = max(current, normalize_release_tag(previous_tag))
-
-    next_version = str(current.bump(level))
-    return ReleaseVersionInfo(
-        version=next_version,
-        npm_version=next_version,
-        canonical=canonical_version,
-        height="0",
-        bump=level,
-        previous_tag=previous_tag or "",
-    )
-
-
-def get_canonical_version(root: Path) -> str:
-    """Read the canonical project version from pyproject.toml."""
-
-    try:
-        import tomllib
-    except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
-        import tomli as tomllib
-
-    with open(root / "pyproject.toml", "rb") as file:
-        project = tomllib.load(file)["project"]
-    return str(project["version"])
-
-
-def list_release_tags(root: Path) -> list[str]:
-    """List release tags from the local Git checkout."""
-
-    result = subprocess.run(
-        ["git", "tag", "-l", "v*"],
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]
-
-
-def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:
-    """List commit subject/body pairs since the previous release tag."""
-
-    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
-    if previous_tag:
-        cmd.append(f"{previous_tag}..HEAD")
-    else:
-        cmd.append("HEAD")
-
-    result = subprocess.run(
-        cmd,
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-
-    commits: list[CommitInfo] = []
-    for raw_entry in result.stdout.split(RECORD_SEP):
-        if not raw_entry or FIELD_SEP not in raw_entry:
-            continue
-        subject, body = raw_entry.split(FIELD_SEP, 1)
-        commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))
-    return commits
-
-
-def commit_height_since(root: Path, previous_tag: str) -> str:
-    """Count commits since the previous release tag for changelog/debug outputs."""
-
-    if not previous_tag:
-        return "0"
-
-    result = subprocess.run(
-        ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return result.stdout.strip() or "0"
-
-
-def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:
-    """Append workflow outputs to the GitHub Actions output file."""
-
-    with open(output_path, "a", encoding="utf-8") as output_file:
-        for key, value in info.as_outputs().items():
-            output_file.write(f"{key}={value}\n")
-
-
-def main() -> None:
-    root = Path.cwd()
-    manual_version = os.environ.get("MANUAL_VER", "").strip()
-    tags = list_release_tags(root)
-    previous_tag = find_latest_release_tag(tags) or ""
-    level = os.environ.get("LEVEL", "").strip()
-    if not level:
-        level = determine_bump_level(list_release_commits(root, previous_tag))
-
-    info = compute_release_version(
-        canonical_version=get_canonical_version(root),
-        level=level,
-        tags=tags,
-        manual_version=manual_version,
-    )
-    info = replace(info, height=commit_height_since(root, info.previous_tag))
-
-    output_path = os.environ.get("GITHUB_OUTPUT", "").strip()
-    if output_path:
-        write_github_outputs(info, output_path)
-        return
-
-    for key, value in info.as_outputs().items():
-        print(f"{key}={value}")
-
-
-if __name__ == "__main__":
-    main()
+"""Release version helpers for the GitHub Actions release workflow."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")
+CONVENTIONAL_COMMIT_RE = re.compile(
+    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
+)
+BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+GIT_LOG_FORMAT = "%s%x1f%b%x1e"
+BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}
+
+
+@dataclass(frozen=True, order=True)
+class SemVer:
+    """Semantic version tuple with simple bump helpers."""
+
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, value: str) -> SemVer:
+        match = SEMVER_RE.match(value)
+        if not match:
+            raise ValueError(f"Invalid semantic version: {value}")
+        return cls(*(int(part) for part in match.groups()))
+
+    def bump(self, level: str) -> SemVer:
+        if level == "major":
+            return SemVer(self.major + 1, 0, 0)
+        if level == "minor":
+            return SemVer(self.major, self.minor + 1, 0)
+        if level == "patch":
+            return SemVer(self.major, self.minor, self.patch + 1)
+        raise ValueError(f"Unsupported bump level: {level}")
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+@dataclass(frozen=True)
+class ReleaseVersionInfo:
+    """Workflow outputs for release version calculation."""
+
+    version: str
+    npm_version: str
+    canonical: str
+    height: str
+    bump: str
+    previous_tag: str
+
+    def as_outputs(self) -> dict[str, str]:
+        return {
+            "version": self.version,
+            "npm_version": self.npm_version,
+            "canonical": self.canonical,
+            "height": self.height,
+            "bump": self.bump,
+            "previous_tag": self.previous_tag,
+        }
+
+
+@dataclass(frozen=True, order=True)
+class ReleaseTag:
+    """Parsed release tag metadata used for sorting and normalization."""
+
+    version: SemVer
+    legacy_height: int = -1
+    raw: str = ""
+
+
+@dataclass(frozen=True)
+class CommitInfo:
+    """Commit subject/body pair used for bump detection."""
+
+    subject: str
+    body: str = ""
+
+
+def parse_release_tag(tag: str) -> ReleaseTag:
+    """Parse a release tag, preserving legacy fourth-component ordering."""
+
+    match = RELEASE_TAG_RE.match(tag)
+    if not match:
+        raise ValueError(f"Invalid release tag: {tag}")
+    major, minor, patch, extra = match.groups()
+    return ReleaseTag(
+        version=SemVer(int(major), int(minor), int(patch)),
+        legacy_height=int(extra) if extra is not None else -1,
+        raw=tag,
+    )
+
+
+def normalize_release_tag(tag: str) -> SemVer:
+    """Collapse historic 4-part release tags into their base semantic version."""
+
+    return parse_release_tag(tag).version
+
+
+def find_latest_release_tag(tags: Sequence[str]) -> str | None:
+    """Return the latest release tag after normalizing legacy 4-part tags."""
+
+    candidates: list[ReleaseTag] = []
+    for tag in tags:
+        if RELEASE_TAG_RE.match(tag):
+            candidates.append(parse_release_tag(tag))
+    if not candidates:
+        return None
+    candidates.sort(reverse=True)
+    return candidates[0].raw
+
+
+def _merge_summary(subject: str, body: str) -> str:
+    """Return the first meaningful body line for merge commits."""
+
+    if not subject.startswith("Merge "):
+        return ""
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def classify_commit_bump(commit: CommitInfo) -> str:
+    """Classify one commit using conventional commit semantics."""
+
+    merge_summary = _merge_summary(commit.subject, commit.body)
+    candidates = [commit.subject]
+    if merge_summary:
+        candidates.insert(0, merge_summary)
+
+    has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))
+    for candidate in candidates:
+        match = CONVENTIONAL_COMMIT_RE.match(candidate)
+        if not match:
+            continue
+        if has_breaking_change or bool(match.group(3)):
+            return "major"
+        if match.group(1) == "feat":
+            return "minor"
+        return "patch"
+
+    if has_breaking_change:
+        return "major"
+    return "patch"
+
+
+def determine_bump_level(commits: Sequence[CommitInfo]) -> str:
+    """Return the highest required bump across a commit range."""
+
+    level = "patch"
+    for commit in commits:
+        candidate = classify_commit_bump(commit)
+        if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:
+            level = candidate
+    return level
+
+
+def compute_release_version(
+    canonical_version: str,
+    level: str,
+    tags: Sequence[str],
+    manual_version: str = "",
+) -> ReleaseVersionInfo:
+    """Compute the next release version from the canonical version and existing tags."""
+
+    if manual_version:
+        manual = str(SemVer.parse(manual_version))
+        return ReleaseVersionInfo(
+            version=manual,
+            npm_version=manual,
+            canonical=canonical_version,
+            height="0",
+            bump="manual",
+            previous_tag="",
+        )
+
+    canonical = SemVer.parse(canonical_version)
+    previous_tag = find_latest_release_tag(tags)
+    current = canonical
+    if previous_tag is not None:
+        current = max(current, normalize_release_tag(previous_tag))
+
+    next_version = str(current.bump(level))
+    return ReleaseVersionInfo(
+        version=next_version,
+        npm_version=next_version,
+        canonical=canonical_version,
+        height="0",
+        bump=level,
+        previous_tag=previous_tag or "",
+    )
+
+
+def get_canonical_version(root: Path) -> str:
+    """Read the canonical project version from pyproject.toml."""
+
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
+        import tomli as tomllib
+
+    with open(root / "pyproject.toml", "rb") as file:
+        project = tomllib.load(file)["project"]
+    return str(project["version"])
+
+
+def list_release_tags(root: Path) -> list[str]:
+    """List release tags from the local Git checkout."""
+
+    result = subprocess.run(
+        ["git", "tag", "-l", "v*"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]
+
+
+def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:
+    """List commit subject/body pairs since the previous release tag."""
+
+    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
+    if previous_tag:
+        cmd.append(f"{previous_tag}..HEAD")
+    else:
+        cmd.append("HEAD")
+
+    result = subprocess.run(
+        cmd,
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    commits: list[CommitInfo] = []
+    for raw_entry in result.stdout.split(RECORD_SEP):
+        if not raw_entry or FIELD_SEP not in raw_entry:
+            continue
+        subject, body = raw_entry.split(FIELD_SEP, 1)
+        commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))
+    return commits
+
+
+def commit_height_since(root: Path, previous_tag: str) -> str:
+    """Count commits since the previous release tag for changelog/debug outputs."""
+
+    if not previous_tag:
+        return "0"
+
+    result = subprocess.run(
+        ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() or "0"
+
+
+def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:
+    """Append workflow outputs to the GitHub Actions output file."""
+
+    with open(output_path, "a", encoding="utf-8") as output_file:
+        for key, value in info.as_outputs().items():
+            output_file.write(f"{key}={value}\n")
+
+
+def main() -> None:
+    root = Path.cwd()
+    manual_version = os.environ.get("MANUAL_VER", "").strip()
+    tags = list_release_tags(root)
+    previous_tag = find_latest_release_tag(tags) or ""
+    level = os.environ.get("LEVEL", "").strip()
+    if not level:
+        level = determine_bump_level(list_release_commits(root, previous_tag))
+
+    info = compute_release_version(
+        canonical_version=get_canonical_version(root),
+        level=level,
+        tags=tags,
+        manual_version=manual_version,
+    )
+    info = replace(info, height=commit_height_since(root, info.previous_tag))
+
+    output_path = os.environ.get("GITHUB_OUTPUT", "").strip()
+    if output_path:
+        write_github_outputs(info, output_path)
+        return
+
+    for key, value in info.as_outputs().items():
+        print(f"{key}={value}")
+
+
+if __name__ == "__main__":
+    main()

headroom/subscription/__init__.py

@@ -1,72 +1,72 @@
-"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""
-
-from headroom.subscription.base import (
-    QuotaTracker,
-    QuotaTrackerRegistry,
-    get_quota_registry,
-    reset_quota_registry,
-)
-from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token
-from headroom.subscription.codex_rate_limits import (
-    CodexCreditsSnapshot,
-    CodexRateLimitSnapshot,
-    CodexRateLimitState,
-    CodexRateLimitWindow,
-    get_codex_rate_limit_state,
-    parse_codex_rate_limits,
-)
-from headroom.subscription.copilot_quota import (
-    CopilotQuotaCategory,
-    CopilotQuotaSnapshot,
-    CopilotQuotaState,
-    discover_github_token,
-    get_copilot_quota_tracker,
-    parse_copilot_quota,
-)
-from headroom.subscription.models import (
-    ExtraUsage,
-    HeadroomContribution,
-    RateLimitWindow,
-    SubscriptionSnapshot,
-    SubscriptionState,
-    WindowDiscrepancy,
-    WindowTokens,
-)
-from headroom.subscription.tracker import (
-    SubscriptionTracker,
-    configure_subscription_tracker,
-    get_subscription_tracker,
-    shutdown_subscription_tracker,
-)
-
-__all__ = [
-    "CodexCreditsSnapshot",
-    "CodexRateLimitSnapshot",
-    "CodexRateLimitState",
-    "CodexRateLimitWindow",
-    "CopilotQuotaCategory",
-    "CopilotQuotaSnapshot",
-    "CopilotQuotaState",
-    "ExtraUsage",
-    "HeadroomContribution",
-    "QuotaTracker",
-    "QuotaTrackerRegistry",
-    "RateLimitWindow",
-    "SubscriptionClient",
-    "SubscriptionSnapshot",
-    "SubscriptionState",
-    "SubscriptionTracker",
-    "WindowDiscrepancy",
-    "WindowTokens",
-    "configure_subscription_tracker",
-    "discover_github_token",
-    "get_codex_rate_limit_state",
-    "get_copilot_quota_tracker",
-    "get_quota_registry",
-    "get_subscription_tracker",
-    "parse_codex_rate_limits",
-    "parse_copilot_quota",
-    "read_cached_oauth_token",
-    "reset_quota_registry",
-    "shutdown_subscription_tracker",
-]
+"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""
+
+from headroom.subscription.base import (
+    QuotaTracker,
+    QuotaTrackerRegistry,
+    get_quota_registry,
+    reset_quota_registry,
+)
+from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token
+from headroom.subscription.codex_rate_limits import (
+    CodexCreditsSnapshot,
+    CodexRateLimitSnapshot,
+    CodexRateLimitState,
+    CodexRateLimitWindow,
+    get_codex_rate_limit_state,
+    parse_codex_rate_limits,
+)
+from headroom.subscription.copilot_quota import (
+    CopilotQuotaCategory,
+    CopilotQuotaSnapshot,
+    CopilotQuotaState,
+    discover_github_token,
+    get_copilot_quota_tracker,
+    parse_copilot_quota,
+)
+from headroom.subscription.models import (
+    ExtraUsage,
+    HeadroomContribution,
+    RateLimitWindow,
+    SubscriptionSnapshot,
+    SubscriptionState,
+    WindowDiscrepancy,
+    WindowTokens,
+)
+from headroom.subscription.tracker import (
+    SubscriptionTracker,
+    configure_subscription_tracker,
+    get_subscription_tracker,
+    shutdown_subscription_tracker,
+)
+
+__all__ = [
+    "CodexCreditsSnapshot",
+    "CodexRateLimitSnapshot",
+    "CodexRateLimitState",
+    "CodexRateLimitWindow",
+    "CopilotQuotaCategory",
+    "CopilotQuotaSnapshot",
+    "CopilotQuotaState",
+    "ExtraUsage",
+    "HeadroomContribution",
+    "QuotaTracker",
+    "QuotaTrackerRegistry",
+    "RateLimitWindow",
+    "SubscriptionClient",
+    "SubscriptionSnapshot",
+    "SubscriptionState",
+    "SubscriptionTracker",
+    "WindowDiscrepancy",
+    "WindowTokens",
+    "configure_subscription_tracker",
+    "discover_github_token",
+    "get_codex_rate_limit_state",
+    "get_copilot_quota_tracker",
+    "get_quota_registry",
+    "get_subscription_tracker",
+    "parse_codex_rate_limits",
+    "parse_copilot_quota",
+    "read_cached_oauth_token",
+    "reset_quota_registry",
+    "shutdown_subscription_tracker",
+]

headroom/subscription/base.py

@@ -1,230 +1,230 @@
-"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.
-
-Every provider tracker (Anthropic, Codex, Copilot, …) inherits from
-:class:`QuotaTracker` and is registered with the process-global
-:class:`QuotaTrackerRegistry`.  ``server.py`` only interacts with the
-registry — adding a new provider requires *zero* changes to the server.
-
-Quick-start for a new provider::
-
-    from headroom.subscription.base import QuotaTracker, get_quota_registry
-
-    class GeminiQuotaTracker(QuotaTracker):
-        key   = "gemini_quota"
-        label = "Google Gemini"
-
-        def is_available(self) -> bool:
-            return bool(os.environ.get("GOOGLE_API_KEY"))
-
-        async def start(self) -> None: ...   # launch background poll
-        async def stop(self)  -> None: ...   # cancel poll task
-
-        def get_stats(self) -> dict | None:
-            return ...  # serialisable dict or None if no data yet
-
-    get_quota_registry().register(GeminiQuotaTracker())
-"""
-
-from __future__ import annotations
-
-import abc
-import logging
-from threading import Lock
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-class QuotaTracker(abc.ABC):
-    """Abstract base for a single AI-tool quota / rate-limit tracker.
-
-    Subclasses must define :attr:`key`, :attr:`label`, and
-    :meth:`get_stats`.  All other methods have sensible defaults.
-    """
-
-    # ------------------------------------------------------------------ #
-    # Class-level identity — subclasses should override as class attributes
-    # ------------------------------------------------------------------ #
-
-    @property
-    @abc.abstractmethod
-    def key(self) -> str:
-        """Stats key used in ``/stats`` and the dashboard.
-
-        Must be unique across all registered trackers.
-        Examples: ``"subscription_window"``, ``"codex_rate_limits"``.
-        """
-
-    @property
-    @abc.abstractmethod
-    def label(self) -> str:
-        """Human-readable name for log messages.
-
-        Example: ``"Anthropic Claude Code"``.
-        """
-
-    # ------------------------------------------------------------------ #
-    # Availability gate
-    # ------------------------------------------------------------------ #
-
-    def is_available(self) -> bool:
-        """Return ``True`` if this tracker should be activated.
-
-        Override to gate on environment variables, config flags, etc.
-        The registry calls this before :meth:`start` and skips trackers
-        that return ``False``.  Default: always available.
-        """
-        return True
-
-    # ------------------------------------------------------------------ #
-    # Lifecycle — default no-ops (suitable for passive/header-based trackers)
-    # ------------------------------------------------------------------ #
-
-    async def start(self) -> None:  # noqa: B027
-        """Start background polling.  No-op for passive trackers."""
-
-    async def stop(self) -> None:  # noqa: B027
-        """Stop background polling.  No-op for passive trackers."""
-
-    # ------------------------------------------------------------------ #
-    # Stats
-    # ------------------------------------------------------------------ #
-
-    @abc.abstractmethod
-    def get_stats(self) -> dict[str, Any] | None:
-        """Return the current snapshot as a serialisable dict, or ``None``.
-
-        ``None`` means "no data yet" and causes the key to be omitted from
-        ``/stats`` rather than appearing as ``null``.
-        """
-
-
-# --------------------------------------------------------------------------- #
-# Registry
-# --------------------------------------------------------------------------- #
-
-
-class QuotaTrackerRegistry:
-    """Process-global registry of all :class:`QuotaTracker` instances.
-
-    Typical usage::
-
-        registry = get_quota_registry()
-        registry.register(SubscriptionTracker(...))
-        registry.register(get_codex_rate_limit_state())
-        registry.register(get_copilot_quota_tracker())
-
-        # server startup
-        await registry.start_all()
-
-        # /stats assembly
-        stats.update(registry.get_all_stats())
-
-        # server shutdown
-        await registry.stop_all()
-    """
-
-    def __init__(self) -> None:
-        self._trackers: list[QuotaTracker] = []
-        self._lock = Lock()
-
-    # ------------------------------------------------------------------ #
-    # Registration
-    # ------------------------------------------------------------------ #
-
-    def register(self, tracker: QuotaTracker) -> None:
-        """Register a tracker.  Duplicate keys are rejected."""
-        with self._lock:
-            existing_keys = {t.key for t in self._trackers}
-            if tracker.key in existing_keys:
-                raise ValueError(
-                    f"A tracker with key '{tracker.key}' is already registered. "
-                    "Each tracker must have a unique key."
-                )
-            self._trackers.append(tracker)
-
-    def get(self, key: str) -> QuotaTracker | None:
-        """Return the registered tracker for *key*, or ``None``."""
-        with self._lock:
-            for t in self._trackers:
-                if t.key == key:
-                    return t
-        return None
-
-    @property
-    def trackers(self) -> list[QuotaTracker]:
-        """Read-only snapshot of the registered tracker list."""
-        with self._lock:
-            return list(self._trackers)
-
-    # ------------------------------------------------------------------ #
-    # Lifecycle
-    # ------------------------------------------------------------------ #
-
-    async def start_all(self) -> None:
-        """Start every available tracker and log its status."""
-        for tracker in self.trackers:
-            if tracker.is_available():
-                await tracker.start()
-                logger.info("%s quota tracking: ENABLED", tracker.label)
-            else:
-                logger.info("%s quota tracking: DISABLED (not available)", tracker.label)
-
-    async def stop_all(self) -> None:
-        """Stop all registered trackers (regardless of availability)."""
-        for tracker in self.trackers:
-            try:
-                await tracker.stop()
-            except Exception as exc:  # noqa: BLE001
-                logger.warning("Error stopping %s tracker: %s", tracker.label, exc)
-
-    # ------------------------------------------------------------------ #
-    # Stats
-    # ------------------------------------------------------------------ #
-
-    def get_all_stats(self) -> dict[str, dict[str, Any] | None]:
-        """Return ``{key: stats_dict}`` for every available tracker.
-
-        Trackers that are unavailable or return ``None`` are excluded.
-        """
-        result: dict[str, dict[str, Any] | None] = {}
-        for tracker in self.trackers:
-            if not tracker.is_available():
-                continue
-            stats = tracker.get_stats()
-            if stats is not None:
-                result[tracker.key] = stats
-        return result
-
-    def get_stats(self, key: str) -> dict[str, Any] | None:
-        """Return stats for a single tracker by key, or ``None``."""
-        tracker = self.get(key)
-        return tracker.get_stats() if tracker is not None else None
-
-
-# --------------------------------------------------------------------------- #
-# Process-global singleton
-# --------------------------------------------------------------------------- #
-
-_registry: QuotaTrackerRegistry | None = None
-_registry_lock = Lock()
-
-
-def get_quota_registry() -> QuotaTrackerRegistry:
-    """Return the process-global :class:`QuotaTrackerRegistry` singleton."""
-    global _registry
-    if _registry is None:
-        with _registry_lock:
-            if _registry is None:
-                _registry = QuotaTrackerRegistry()
-    return _registry
-
-
-def reset_quota_registry() -> None:
-    """Replace the global registry with a fresh empty instance.
-
-    Intended for use in tests only.
-    """
-    global _registry
-    with _registry_lock:
-        _registry = QuotaTrackerRegistry()
+"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.
+
+Every provider tracker (Anthropic, Codex, Copilot, …) inherits from
+:class:`QuotaTracker` and is registered with the process-global
+:class:`QuotaTrackerRegistry`.  ``server.py`` only interacts with the
+registry — adding a new provider requires *zero* changes to the server.
+
+Quick-start for a new provider::
+
+    from headroom.subscription.base import QuotaTracker, get_quota_registry
+
+    class GeminiQuotaTracker(QuotaTracker):
+        key   = "gemini_quota"
+        label = "Google Gemini"
+
+        def is_available(self) -> bool:
+            return bool(os.environ.get("GOOGLE_API_KEY"))
+
+        async def start(self) -> None: ...   # launch background poll
+        async def stop(self)  -> None: ...   # cancel poll task
+
+        def get_stats(self) -> dict | None:
+            return ...  # serialisable dict or None if no data yet
+
+    get_quota_registry().register(GeminiQuotaTracker())
+"""
+
+from __future__ import annotations
+
+import abc
+import logging
+from threading import Lock
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class QuotaTracker(abc.ABC):
+    """Abstract base for a single AI-tool quota / rate-limit tracker.
+
+    Subclasses must define :attr:`key`, :attr:`label`, and
+    :meth:`get_stats`.  All other methods have sensible defaults.
+    """
+
+    # ------------------------------------------------------------------ #
+    # Class-level identity — subclasses should override as class attributes
+    # ------------------------------------------------------------------ #
+
+    @property
+    @abc.abstractmethod
+    def key(self) -> str:
+        """Stats key used in ``/stats`` and the dashboard.
+
+        Must be unique across all registered trackers.
+        Examples: ``"subscription_window"``, ``"codex_rate_limits"``.
+        """
+
+    @property
+    @abc.abstractmethod
+    def label(self) -> str:
+        """Human-readable name for log messages.
+
+        Example: ``"Anthropic Claude Code"``.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Availability gate
+    # ------------------------------------------------------------------ #
+
+    def is_available(self) -> bool:
+        """Return ``True`` if this tracker should be activated.
+
+        Override to gate on environment variables, config flags, etc.
+        The registry calls this before :meth:`start` and skips trackers
+        that return ``False``.  Default: always available.
+        """
+        return True
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle — default no-ops (suitable for passive/header-based trackers)
+    # ------------------------------------------------------------------ #
+
+    async def start(self) -> None:  # noqa: B027
+        """Start background polling.  No-op for passive trackers."""
+
+    async def stop(self) -> None:  # noqa: B027
+        """Stop background polling.  No-op for passive trackers."""
+
+    # ------------------------------------------------------------------ #
+    # Stats
+    # ------------------------------------------------------------------ #
+
+    @abc.abstractmethod
+    def get_stats(self) -> dict[str, Any] | None:
+        """Return the current snapshot as a serialisable dict, or ``None``.
+
+        ``None`` means "no data yet" and causes the key to be omitted from
+        ``/stats`` rather than appearing as ``null``.
+        """
+
+
+# --------------------------------------------------------------------------- #
+# Registry
+# --------------------------------------------------------------------------- #
+
+
+class QuotaTrackerRegistry:
+    """Process-global registry of all :class:`QuotaTracker` instances.
+
+    Typical usage::
+
+        registry = get_quota_registry()
+        registry.register(SubscriptionTracker(...))
+        registry.register(get_codex_rate_limit_state())
+        registry.register(get_copilot_quota_tracker())
+
+        # server startup
+        await registry.start_all()
+
+        # /stats assembly
+        stats.update(registry.get_all_stats())
+
+        # server shutdown
+        await registry.stop_all()
+    """
+
+    def __init__(self) -> None:
+        self._trackers: list[QuotaTracker] = []
+        self._lock = Lock()
+
+    # ------------------------------------------------------------------ #
+    # Registration
+    # ------------------------------------------------------------------ #
+
+    def register(self, tracker: QuotaTracker) -> None:
+        """Register a tracker.  Duplicate keys are rejected."""
+        with self._lock:
+            existing_keys = {t.key for t in self._trackers}
+            if tracker.key in existing_keys:
+                raise ValueError(
+                    f"A tracker with key '{tracker.key}' is already registered. "
+                    "Each tracker must have a unique key."
+                )
+            self._trackers.append(tracker)
+
+    def get(self, key: str) -> QuotaTracker | None:
+        """Return the registered tracker for *key*, or ``None``."""
+        with self._lock:
+            for t in self._trackers:
+                if t.key == key:
+                    return t
+        return None
+
+    @property
+    def trackers(self) -> list[QuotaTracker]:
+        """Read-only snapshot of the registered tracker list."""
+        with self._lock:
+            return list(self._trackers)
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+
+    async def start_all(self) -> None:
+        """Start every available tracker and log its status."""
+        for tracker in self.trackers:
+            if tracker.is_available():
+                await tracker.start()
+                logger.info("%s quota tracking: ENABLED", tracker.label)
+            else:
+                logger.info("%s quota tracking: DISABLED (not available)", tracker.label)
+
+    async def stop_all(self) -> None:
+        """Stop all registered trackers (regardless of availability)."""
+        for tracker in self.trackers:
+            try:
+                await tracker.stop()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Error stopping %s tracker: %s", tracker.label, exc)
+
+    # ------------------------------------------------------------------ #
+    # Stats
+    # ------------------------------------------------------------------ #
+
+    def get_all_stats(self) -> dict[str, dict[str, Any] | None]:
+        """Return ``{key: stats_dict}`` for every available tracker.
+
+        Trackers that are unavailable or return ``None`` are excluded.
+        """
+        result: dict[str, dict[str, Any] | None] = {}
+        for tracker in self.trackers:
+            if not tracker.is_available():
+                continue
+            stats = tracker.get_stats()
+            if stats is not None:
+                result[tracker.key] = stats
+        return result
+
+    def get_stats(self, key: str) -> dict[str, Any] | None:
+        """Return stats for a single tracker by key, or ``None``."""
+        tracker = self.get(key)
+        return tracker.get_stats() if tracker is not None else None
+
+
+# --------------------------------------------------------------------------- #
+# Process-global singleton
+# --------------------------------------------------------------------------- #
+
+_registry: QuotaTrackerRegistry | None = None
+_registry_lock = Lock()
+
+
+def get_quota_registry() -> QuotaTrackerRegistry:
+    """Return the process-global :class:`QuotaTrackerRegistry` singleton."""
+    global _registry
+    if _registry is None:
+        with _registry_lock:
+            if _registry is None:
+                _registry = QuotaTrackerRegistry()
+    return _registry
+
+
+def reset_quota_registry() -> None:
+    """Replace the global registry with a fresh empty instance.
+
+    Intended for use in tests only.
+    """
+    global _registry
+    with _registry_lock:
+        _registry = QuotaTrackerRegistry()