chore: import upstream snapshot with attribution

docker/differential-network-capture/Dockerfile.runner

@@ -0,0 +1,14 @@
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl git python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG CLAUDE_CODE_PACKAGE=@anthropic-ai/claude-code
+RUN npm install -g "${CLAUDE_CODE_PACKAGE}"
+
+WORKDIR /workspace
+COPY run-claude-lane.sh /usr/local/bin/run-claude-lane
+RUN chmod +x /usr/local/bin/run-claude-lane
+
+ENTRYPOINT ["run-claude-lane"]

docker/differential-network-capture/docker-compose.yml

@@ -0,0 +1,142 @@
+name: headroom-network-diff
+
+services:
+  mitm-direct:
+    image: mitmproxy/mitmproxy:12
+    command:
+      - mitmdump
+      - --mode
+      - regular
+      - --listen-host
+      - 0.0.0.0
+      - --listen-port
+      - "8080"
+      - --set
+      - confdir=/mitmproxy
+      - -s
+      - /capture/mitm_capture.py
+    environment:
+      CAPTURE_LANE: direct
+      CAPTURE_OUTPUT: /captures/direct.jsonl
+      CAPTURE_INCLUDE_HOSTS: ${CAPTURE_INCLUDE_HOSTS:-api.anthropic.com}
+      CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
+    volumes:
+      - ./mitm_capture.py:/capture/mitm_capture.py:ro
+      - ./captures:/captures
+      - mitm_direct_ca:/mitmproxy
+    ports:
+      - "${DIRECT_MITM_PORT:-18080}:8080"
+
+  mitm-headroom-client:
+    image: mitmproxy/mitmproxy:12
+    command:
+      - mitmdump
+      - --mode
+      - reverse:http://headroom-proxy:8787
+      - --listen-host
+      - 0.0.0.0
+      - --listen-port
+      - "8080"
+      - -s
+      - /capture/mitm_capture.py
+    environment:
+      CAPTURE_LANE: headroom-client
+      CAPTURE_OUTPUT: /captures/headroom-client.jsonl
+      CAPTURE_INCLUDE_HOSTS: ${CAPTURE_CLIENT_INCLUDE_HOSTS:-mitm-headroom-client,headroom-proxy,api.anthropic.com}
+      CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
+    volumes:
+      - ./mitm_capture.py:/capture/mitm_capture.py:ro
+      - ./captures:/captures
+    ports:
+      - "${HEADROOM_CLIENT_MITM_PORT:-18082}:8080"
+    depends_on:
+      - headroom-proxy
+
+  mitm-headroom-upstream:
+    image: mitmproxy/mitmproxy:12
+    command:
+      - mitmdump
+      - --mode
+      - regular
+      - --listen-host
+      - 0.0.0.0
+      - --listen-port
+      - "8080"
+      - --set
+      - confdir=/mitmproxy
+      - -s
+      - /capture/mitm_capture.py
+    environment:
+      CAPTURE_LANE: headroom-upstream
+      CAPTURE_OUTPUT: /captures/headroom-upstream.jsonl
+      CAPTURE_INCLUDE_HOSTS: ${CAPTURE_INCLUDE_HOSTS:-api.anthropic.com}
+      CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
+    volumes:
+      - ./mitm_capture.py:/capture/mitm_capture.py:ro
+      - ./captures:/captures
+      - mitm_headroom_ca:/mitmproxy
+    ports:
+      - "${HEADROOM_MITM_PORT:-18081}:8080"
+
+  headroom-proxy:
+    build:
+      context: ../..
+      dockerfile: Dockerfile
+    command: ["--host", "0.0.0.0", "--port", "8787", "--backend", "anthropic"]
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
+      ANTHROPIC_TARGET_API_URL: ${ANTHROPIC_TARGET_API_URL:-https://api.anthropic.com}
+      HTTPS_PROXY: http://mitm-headroom-upstream:8080
+      HTTP_PROXY: http://mitm-headroom-upstream:8080
+      NO_PROXY: 127.0.0.1,localhost,headroom-proxy
+      REQUESTS_CA_BUNDLE: /mitmproxy/mitmproxy-ca-cert.pem
+      SSL_CERT_FILE: /mitmproxy/mitmproxy-ca-cert.pem
+    volumes:
+      - mitm_headroom_ca:/mitmproxy:ro
+    depends_on:
+      - mitm-headroom-upstream
+
+  claude-direct:
+    build:
+      context: .
+      dockerfile: Dockerfile.runner
+      args:
+        CLAUDE_CODE_PACKAGE: ${CLAUDE_CODE_PACKAGE:-@anthropic-ai/claude-code}
+    profiles: ["run"]
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
+      HTTPS_PROXY: http://mitm-direct:8080
+      HTTP_PROXY: http://mitm-direct:8080
+      NO_PROXY: 127.0.0.1,localhost
+      NODE_EXTRA_CA_CERTS: /mitmproxy/mitmproxy-ca-cert.pem
+      SSL_CERT_FILE: /mitmproxy/mitmproxy-ca-cert.pem
+      CLAUDE_LANE: direct
+      CLAUDE_PROMPT: ${CLAUDE_PROMPT:-Summarize this repository in one sentence.}
+      CLAUDE_ARGS: ${CLAUDE_DIRECT_ARGS:-}
+    volumes:
+      - ../..:/workspace:ro
+      - mitm_direct_ca:/mitmproxy:ro
+    depends_on:
+      - mitm-direct
+
+  claude-headroom:
+    build:
+      context: .
+      dockerfile: Dockerfile.runner
+      args:
+        CLAUDE_CODE_PACKAGE: ${CLAUDE_CODE_PACKAGE:-@anthropic-ai/claude-code}
+    profiles: ["run"]
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
+      ANTHROPIC_BASE_URL: http://mitm-headroom-client:8080
+      CLAUDE_LANE: headroom
+      CLAUDE_PROMPT: ${CLAUDE_PROMPT:-Summarize this repository in one sentence.}
+      CLAUDE_ARGS: ${CLAUDE_HEADROOM_ARGS:-}
+    volumes:
+      - ../..:/workspace:ro
+    depends_on:
+      - mitm-headroom-client
+
+volumes:
+  mitm_direct_ca:
+  mitm_headroom_ca:

docker/differential-network-capture/mitm_capture.py

@@ -0,0 +1,89 @@
+"""mitmproxy addon that writes sanitized HTTP exchanges as JSONL."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from mitmproxy import http
+
+LANE = os.environ.get("CAPTURE_LANE", "unknown")
+OUTPUT = Path(os.environ.get("CAPTURE_OUTPUT", f"/captures/{LANE}.jsonl"))
+INCLUDE_HOSTS = {
+    host.strip().lower()
+    for host in os.environ.get("CAPTURE_INCLUDE_HOSTS", "api.anthropic.com").split(",")
+    if host.strip()
+}
+BODY_BYTES = int(os.environ.get("CAPTURE_BODY_BYTES", "262144"))
+SENSITIVE_HEADER_PARTS = ("authorization", "api-key", "apikey", "token", "secret", "cookie")
+SENSITIVE_QUERY_PARTS = ("key", "token", "secret", "signature", "code")
+_sequence = 0
+
+
+def _redact_headers(headers: http.Headers) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key, value in headers.items(multi=True):
+        if any(part in key.lower() for part in SENSITIVE_HEADER_PARTS):
+            result[key] = "<redacted>"
+        else:
+            result[key] = value
+    return result
+
+
+def _sanitize_url(url: str) -> str:
+    parsed = urlsplit(url)
+    pairs = []
+    for key, value in parse_qsl(parsed.query, keep_blank_values=True):
+        if any(part in key.lower() for part in SENSITIVE_QUERY_PARTS):
+            pairs.append((key, "<redacted>"))
+        else:
+            pairs.append((key, value))
+    return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode(pairs), ""))
+
+
+def _request_json(content: bytes) -> object | None:
+    try:
+        return json.loads(content.decode("utf-8"))
+    except Exception:
+        return None
+
+
+def response(flow: http.HTTPFlow) -> None:
+    global _sequence
+    host = flow.request.pretty_host.lower()
+    if INCLUDE_HOSTS and host not in INCLUDE_HOSTS:
+        return
+
+    _sequence += 1
+    request_body = flow.request.raw_content or b""
+    response_body = flow.response.raw_content if flow.response else b""
+    record = {
+        "lane": LANE,
+        "sequence": _sequence,
+        "timestamp": time.time(),
+        "method": flow.request.method,
+        "url": _sanitize_url(flow.request.pretty_url),
+        "host": flow.request.pretty_host,
+        "request_headers": _redact_headers(flow.request.headers),
+        "request_body_size": len(request_body),
+        "request_body_sha256": hashlib.sha256(request_body).hexdigest() if request_body else None,
+        "request_body_b64": base64.b64encode(request_body[:BODY_BYTES]).decode("ascii"),
+        "request_body_truncated": len(request_body) > BODY_BYTES,
+        "request_json": _request_json(request_body),
+        "response_status": flow.response.status_code if flow.response else None,
+        "response_headers": _redact_headers(flow.response.headers) if flow.response else {},
+        "response_body_size": len(response_body),
+        "response_body_sha256": hashlib.sha256(response_body).hexdigest()
+        if response_body
+        else None,
+    }
+
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    with OUTPUT.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, separators=(",", ":"), sort_keys=True))
+        fh.write("\n")

docker/differential-network-capture/run-claude-lane.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+set -eu
+
+echo "running Claude Code lane: ${CLAUDE_LANE:-unknown}" >&2
+
+if [ -n "${NODE_EXTRA_CA_CERTS:-}" ]; then
+  i=0
+  while [ ! -f "$NODE_EXTRA_CA_CERTS" ] && [ "$i" -lt 100 ]; do
+    i=$((i + 1))
+    sleep 0.1
+  done
+fi
+
+if [ -n "${CLAUDE_COMMAND:-}" ]; then
+  sh -lc "$CLAUDE_COMMAND"
+  exit $?
+fi
+
+if [ -n "${CLAUDE_ARGS:-}" ]; then
+  # shellcheck disable=SC2086
+  claude ${CLAUDE_ARGS} -p "${CLAUDE_PROMPT:-Summarize this repository in one sentence.}"
+else
+  claude -p "${CLAUDE_PROMPT:-Summarize this repository in one sentence.}"
+fi

docker/docker-compose.native.yml

@@ -0,0 +1,48 @@
+services:
+  cli:
+    image: ${HEADROOM_IMAGE:-ghcr.io/chopratejas/headroom:latest}
+    entrypoint: ["headroom"]
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+    environment:
+      HOME: /tmp/headroom-home
+      # Canonical Headroom filesystem contract (issue #175). Forwarded into
+      # the container so the proxy resolves state/config to the bind-mounted
+      # /tmp/headroom-home/.headroom path. HEADROOM_WORKSPACE (above) remains
+      # the Docker bind-mount source and is intentionally different.
+      HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
+      HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
+      # CLI-filtering dashboard figures require the `rtk` binary inside this
+      # container; it is not installed by this image. See docs/content/docs/docker-install.mdx.
+    volumes:
+      - ${HEADROOM_WORKSPACE:-.}:/workspace
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
+    command: ["--help"]
+
+  proxy:
+    image: ${HEADROOM_IMAGE:-ghcr.io/chopratejas/headroom:latest}
+    entrypoint: ["headroom", "proxy"]
+    working_dir: /workspace
+    restart: unless-stopped
+    environment:
+      HOME: /tmp/headroom-home
+      HEADROOM_HOST: 0.0.0.0
+      # Canonical Headroom filesystem contract (issue #175). See `cli` service
+      # above for rationale.
+      HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
+      HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
+      # CLI-filtering dashboard figures require the `rtk` binary inside this
+      # container; it is not installed by this image. See docs/content/docs/docker-install.mdx.
+    ports:
+      - "${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
+    volumes:
+      - ${HEADROOM_WORKSPACE:-.}:/workspace
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
+      - ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
+    command: ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]