Merge remote-tracking branch 'upstream/main' into maintain/pr-623

# Conflicts:
#	headroom/proxy/server.py

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.34.0"
+    "version": "0.36.1"
   },
   "plugins": [
     {
       "name": "headroom",
       "source": "./plugins/headroom-agent-hooks",
       "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
-      "version": "0.34.0",
+      "version": "0.36.1",
       "author": {
         "name": "Headroom Contributors",
         "url": "https://github.com/chopratejas/headroom"

.commitlintrc.json

@@ -1,7 +1,7 @@
 {
   "extends": ["@commitlint/config-conventional"],
   "rules": {
-    "body-max-line-length": [2, "always", 200],
+    "body-max-line-length": [0],
     "footer-leading-blank": [0],
     "subject-case": [0],
     "type-enum": [
@@ -12,6 +12,7 @@
         "chore",
         "ci",
         "docs",
+        "deps",
         "feat",
         "fix",
         "parity",
@@ -23,4 +24,4 @@
       ]
     ]
   }
-}
+}

.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/PULL_REQUEST_TEMPLATE.md

@@ -40,6 +40,16 @@ Closes #
 - Observed result:
 - Not tested:
 
+## Runtime Rollout Safety
+
+- Rollout-managed feature(s):
+- Minimum rollout channel:
+- Stable/default behavior changed:
+- Kill switch / disable path:
+- Unsafe override required:
+- Qualification impact:
+- Rollback path:
+
 ## Review Readiness
 
 - [ ] I have performed a self-review

.github/act/pr-governance-valid.json

@@ -1,19 +1,13 @@
-{
-  "action": "ready_for_review",
-  "number": 42,
-  "pull_request": {
-    "number": 42,
-    "draft": false,
-    "title": "feat: add PR governance",
-    "body": "## Description\n\nAdd a required PR governance check and commit-msg enforcement.\n\nCloses #123\n\n## Type of Change\n\n- [x] New feature (non-breaking change that adds functionality)\n\n## Changes Made\n\n- Added workflow validation for PR template completeness.\n- Added a commit-msg hook that runs commitlint locally.\n\n## Testing\n\n- [x] Unit tests pass (`pytest`)\n- [x] Manual testing performed\n\n### Test Output\n\n```text\npytest scripts/tests/test_pr_governance.py -q\n```\n\n## Real Behavior Proof\n\n- Environment: Ubuntu runner, Python 3.12\n- Exact command / steps: Opened a PR with an incomplete template, then fixed the body.\n- Observed result: The governance check failed until the template and readiness boxes were complete.\n- Not tested: Repository-level automatic Copilot rulesets.\n\n## Review Readiness\n\n- [x] I have performed a self-review\n- [x] This PR is ready for human review\n",
-    "user": {
-      "login": "octocat"
-    },
-    "base": {
-      "sha": "dff6a199"
-    }
-  },
-  "repository": {
-    "full_name": "JerrettDavis/headroom"
-  }
-}
+{
+  "action": "ready_for_review",
+  "number": 42,
+  "pull_request": {
+    "number": 42,
+    "draft": false,
+    "title": "feat: add PR governance",
+    "body": "## Description\n\nAdd a required PR governance check and commit-msg enforcement.\n\n## Type of Change\n\n- [x] New feature (non-breaking change that adds functionality)\n\n## Changes Made\n\n- Added workflow validation for PR template completeness.\n\n## Testing\n\n- [x] Unit tests pass (`pytest`)\n\n### Test Output\n\n```text\npytest scripts/tests/test_pr_governance.py -q\n```\n\n## Real Behavior Proof\n\n- Environment: Ubuntu runner, Python 3.12\n- Exact command / steps: Opened a PR and ran governance.\n- Observed result: The check passed with complete facts.\n- Not tested: Repository settings.\n\n## Runtime Rollout Safety\n\n- Rollout-managed feature(s): None.\n- Minimum rollout channel: Stable.\n- Stable/default behavior changed: No.\n- Kill switch / disable path: Not applicable.\n- Unsafe override required: No.\n- Qualification impact: None.\n- Rollback path: Revert the workflow and script changes.\n\n## Review Readiness\n\n- [x] I have performed a self-review\n- [x] This PR is ready for human review\n",
+    "user": {"login": "octocat"},
+    "base": {"sha": "dff6a199"}
+  },
+  "repository": {"full_name": "JerrettDavis/headroom"}
+}

.github/plugin/marketplace.json

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

.github/pr-images/issue-2552-windows-fallback-verification.png

@@ -204,10 +204,10 @@ jobs:
       - name: Upload digest marker
         uses: actions/upload-artifact@v7
         with:
-          # Variant + arch in the artifact name so the manifest job can
-          # download with `pattern: digests-<variant>-*` to gather all
-          # arches for one variant. `root` substitutes the empty-string
-          # variant since GHA artifact names can't end in a hyphen.
+          # Variant + arch uniquely identify the marker. The manifest job
+          # downloads both architecture artifacts by exact name; a glob such
+          # as `digests-code-*` would also match code-nonroot/code-slim.
+          # `root` substitutes the empty-string variant.
           name: digests-${{ matrix.variant.name || 'root' }}-${{ matrix.arch.name }}
           path: ${{ runner.temp }}/digests/*
           if-no-files-found: error
@@ -273,12 +273,17 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Download per-arch digests for this variant
+      - name: Download amd64 digest for this variant
         uses: actions/download-artifact@v8
         with:
-          pattern: digests-${{ matrix.variant.name || 'root' }}-*
+          name: digests-${{ matrix.variant.name || 'root' }}-amd64
+          path: ${{ runner.temp }}/digests
+
+      - name: Download arm64 digest for this variant
+        uses: actions/download-artifact@v8
+        with:
+          name: digests-${{ matrix.variant.name || 'root' }}-arm64
           path: ${{ runner.temp }}/digests
-          merge-multiple: true
 
       # Same tag rules as the pre-fan-out workflow — preserve every
       # tag flavor (semver, ref, sha-prefixed, version-suffixed,
@@ -288,6 +293,18 @@ jobs:
         uses: docker/metadata-action@v6
         with:
           images: ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}
+          # `latest=false` is load-bearing (#3150). The action defaults to
+          # `latest=auto`, which appends a bare `latest` for any semver
+          # release — and it logs `suffixLatest=false`, so the per-tag
+          # `suffix=` below never reaches it. Every one of the 8 variant
+          # cells therefore pushed `ghcr.io/.../headroom:latest`, and the
+          # last cell to finish won. At 0.36.0 that was `code-slim`, so
+          # `:latest` resolved to the distroless build, whose
+          # `import onnxruntime` segfaults on arm64 — `headroom deploy`
+          # crash-looped on Apple Silicon. `:latest` has exactly one
+          # writer: the root-cell promotion step at the end of this job.
+          flavor: |
+            latest=false
           tags: |
             type=ref,event=branch,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant.name != '' && format('-{0}', matrix.variant.name) || '' }}
             type=ref,event=pr,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant.name != '' && format('-{0}', matrix.variant.name) || '' }}
@@ -306,6 +323,9 @@ jobs:
         env:
           IMAGE: ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}
           DIGEST_DIR: ${{ runner.temp }}/digests
+          # Read by the bare-`latest` guard below. Via `env:` rather than
+          # inline `${{ }}` so the value is never spliced into the script.
+          VARIANT_NAME: ${{ matrix.variant.name }}
         run: |
           # Reconstruct full image references from the digest marker
           # filenames (each file is named after the bare hex digest
@@ -325,6 +345,16 @@ jobs:
             digest_refs+=("${IMAGE}@sha256:${digest}")
           done
 
+          # Belt-and-braces for #3150: only the root cell may ever carry a
+          # bare `latest`. A suffixed variant reaching this point with one
+          # means the tag rules regressed, and shipping it would repoint
+          # `:latest` at a non-default image. Fail instead of publishing.
+          if [ -n "${VARIANT_NAME}" ] && jq -e '.tags[]? | select(endswith(":latest"))' \
+               <<< "${DOCKER_METADATA_OUTPUT_JSON}" >/dev/null 2>&1; then
+            echo "::error::variant '${VARIANT_NAME}' would publish a bare :latest tag" >&2
+            exit 1
+          fi
+
           # Build `--tag` args from the metadata-action JSON output.
           # Empty tags array is valid (PR builds without ref-tags
           # enabled emit nothing); skip manifest creation in that case.

.github/workflows/docker.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}"