Merge main into feat/metaprogramming-guardrails

Author: JerrettDavis

.cargo/audit.toml

@@ -0,0 +1,23 @@
+# cargo-audit configuration for the Rust workspace.
+#
+# Path matters: cargo-audit reads `.cargo/audit.toml`, not a root-level
+# `audit.toml`. A file at the repo root is silently ignored.
+#
+# The `audit` job in .github/workflows/rust.yml is a BLOCKING gate. It runs on
+# every PR touching Rust and nightly on the schedule (the `rust-changes` job
+# reports `rust=true` for `schedule`/`workflow_dispatch`, so a newly-disclosed
+# advisory surfaces without anyone touching Rust code).
+#
+# It was `continue-on-error: true` until the change that added this file, which meant it reported findings
+# nobody saw: RUSTSEC-2026-0258 (h2, unbounded empty DATA frames) sat in a green
+# run. Anything ignored here has to be listed explicitly, with a reason.
+
+[advisories]
+ignore = [
+    # `paste` is unmaintained — an advisory of project status, not a
+    # vulnerability; there is no patched version to move to. It is transitive
+    # and unavoidable at our layer: tokenizers -> paste and rav1e -> paste,
+    # both reached via fastembed. Re-evaluate when tokenizers moves to
+    # `pastey` (the maintained drop-in fork).
+    "RUSTSEC-2024-0436",
+]

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
-    "version": "0.35.0"
+    "version": "0.36.0"
   },
   "plugins": [
     {
       "name": "headroom",
       "source": "./plugins/headroom-agent-hooks",
       "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
-      "version": "0.35.0",
+      "version": "0.36.0",
       "author": {
         "name": "Headroom Contributors",
         "url": "https://github.com/chopratejas/headroom"

.env.example

@@ -1,3 +1,14 @@
-# Copy this file to .env and fill in real values before running in production.
-# IMPORTANT: Change NEO4J_AUTH before deploying — default credentials are insecure.
+# Copy this file to .env and fill in real values before running.
+# docker-compose.yml requires these — it will refuse to start with defaults.
+
+# Neo4j credentials for the graph memory backend (format: user/password).
 NEO4J_AUTH=neo4j/CHANGEME
+# Password only, for library / non-Docker use of the Neo4j memory backend.
+NEO4J_PASSWORD=CHANGEME
+
+# Proxy token — gates the data plane whenever the proxy is not loopback-only.
+# Generate: openssl rand -hex 32
+HEADROOM_PROXY_TOKEN=CHANGEME
+
+# Optional: set to 0.0.0.0 to expose the proxy on the network (requires a token).
+# HEADROOM_BIND_ADDR=127.0.0.1

.github/plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
-    "version": "0.35.0"
+    "version": "0.36.0"
   },
   "plugins": [
     {
       "name": "headroom",
       "source": "./plugins/headroom-agent-hooks",
       "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
-      "version": "0.35.0",
+      "version": "0.36.0",
       "author": {
         "name": "Headroom Contributors",
         "url": "https://github.com/chopratejas/headroom"

.github/workflows/release-metadata-sync.yml

@@ -50,15 +50,26 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
+      # Prefer a short-lived, repo-scoped GitHub App installation token over a
+      # personal PAT. Gated on the repo variable so an unconfigured app simply
+      # falls through to the existing chain instead of breaking the release.
+      - name: Mint installation token
+        id: app-token
+        if: ${{ vars.RELEASE_APP_ID != '' }}
+        continue-on-error: true
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - uses: actions/checkout@v7
         with:
           ref: ${{ github.ref_name }}
-          # PAT (not GITHUB_TOKEN) for the same reason release-please.yml uses one:
-          # a push made with GITHUB_TOKEN does not trigger workflows, so the release
-          # PR's checks would never re-run against the synced commit and would stay
-          # red. Falls back to GITHUB_TOKEN, where the sync still lands and a manual
-          # re-run of the PR's checks picks it up.
-          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          # Do NOT persist the credential into .git/config. The next step runs
+          # scripts/version-sync.py *from the checked-out branch*, and this job
+          # triggers on a push to the unprotected glob release-please--branches--**.
+          # A persisted token would be readable by that script.
+          persist-credentials: false
 
       - uses: actions/setup-python@v6
         with:
@@ -72,6 +83,14 @@ jobs:
         run: python scripts/verify-versions.py
 
       - name: Commit and push if anything changed
+        env:
+          # An app installation token if one was minted, else the existing
+          # chain. A PAT (not GITHUB_TOKEN) is still preferred here for the same
+          # reason release-please.yml wants one: a push made with GITHUB_TOKEN
+          # does not trigger workflows, so the release PR's checks would never
+          # re-run against the synced commit and would stay red. Supplied only
+          # to this step, after the branch-supplied script has already run.
+          SYNC_TOKEN: ${{ steps.app-token.outputs.token || secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
         run: |
           if git diff --quiet; then
             echo "Already in sync — nothing to commit."
@@ -81,7 +100,12 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add -A
           git commit -m "chore: sync generated version metadata"
+          # Push via an explicit remote URL because the checkout no longer
+          # persists credentials. Passed on stdin-free env expansion so the
+          # token is not written to the command line or into .git/config.
           # This push re-triggers this workflow. version-sync.py is idempotent, so
           # the next run finds no diff and exits above without pushing — the loop
           # terminates after one no-op run.
-          git push origin HEAD:"${GITHUB_REF_NAME}"
+          git push \
+            "https://x-access-token:${SYNC_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
+            HEAD:"${GITHUB_REF_NAME}"

.github/workflows/release-please.yml

@@ -42,16 +42,31 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
+      # Prefer a short-lived, repo-scoped GitHub App installation token. A
+      # personal PAT carries the maintainer's whole account — with a classic
+      # `repo` scope that reaches every other repository they can access — and
+      # this credential can tag past branch protection and reaches PyPI, npm and
+      # GHCR through the `release: published` publishes. An installation token is
+      # scoped to this repository and expires in an hour. Gated on the repo
+      # variable so an unconfigured app falls through instead of blocking a
+      # release. See #2955.
+      - name: Mint installation token
+        id: app-token
+        if: ${{ vars.RELEASE_APP_ID != '' }}
+        continue-on-error: true
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - uses: googleapis/release-please-action@v5
         with:
-          # PAT (not GITHUB_TOKEN): a release/tag created by GITHUB_TOKEN does
-          # NOT emit events that trigger other workflows, so release.yml
-          # (PyPI/npm) and docker.yml — which fire on `release: published` —
-          # never ran, and releases had to be cut by hand. A PAT is treated as a
-          # real user, so the release it creates DOES trigger those publishes; it
-          # also lets the bot tag past branch/tag protection. Falls back to
-          # GITHUB_TOKEN when the secret is unset (the release PR still opens; it
-          # just won't trigger the downstream publishes).
-          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          # Neither an app token nor a PAT is GITHUB_TOKEN, and that matters: a
+          # release/tag created by GITHUB_TOKEN does NOT emit events that trigger
+          # other workflows, so release.yml (PyPI/npm) and docker.yml — which fire
+          # on `release: published` — never ran, and releases had to be cut by
+          # hand. Falls back to GITHUB_TOKEN when nothing else is set (the release
+          # PR still opens; it just won't trigger the downstream publishes).
+          token: ${{ steps.app-token.outputs.token || secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
           config-file: .release-please-config.json
           manifest-file: .release-please-manifest.json

.github/workflows/rust.yml

@@ -224,8 +224,12 @@ jobs:
         uses: taiki-e/install-action@v2
         with:
           tool: cargo-audit,cargo-deny
-      - name: cargo audit (soft-fail)
-        continue-on-error: true
+      # Blocking. Soft-failing this made it useless: RUSTSEC-2026-0258 (h2,
+      # unbounded empty DATA frames -> unbounded memory or a panic) was
+      # reported by this job for as long as it existed and never turned a run
+      # red, so nobody acted on it. Accepted advisories go in audit.toml with
+      # a written reason rather than being swallowed wholesale here.
+      - name: cargo audit
         run: cargo audit
       - name: cargo deny check licenses
         continue-on-error: true

.github/workflows/tools-hash-refresh.yml

@@ -0,0 +1,29 @@
+name: tools-hash-refresh
+
+# Enforce that headroom/tools.json SHA-256 pins match the published assets for
+# the currently pinned tool versions. Fails if a version was bumped without
+# refreshing pins (run scripts/refresh_tool_hashes.py locally). See WEB-03.
+
+on:
+  pull_request:
+    paths:
+      - "headroom/tools.json"
+      - "scripts/refresh_tool_hashes.py"
+      - ".github/workflows/tools-hash-refresh.yml"
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  verify-pins:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tool SHA-256 pins
+        run: python scripts/refresh_tool_hashes.py --check

.gitignore

@@ -38,6 +38,7 @@ scripts/*
 !scripts/audit_wheel_glibc_symbols.py
 !scripts/replay_codex_ws_load.py
 !scripts/export_kompress_v2_onnx.py
+!scripts/refresh_tool_hashes.py
 !scripts/record_kompress_fixtures.py
 !scripts/record_code_compressor_fixtures.py
 

.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
         # unconditionally, so installing hooks is not required for enforcement.
         args: [--assume-in-merge]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.22
+    rev: v0.16.2
     hooks:
       - id: ruff
         args: [--fix]