Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(proxy): astgrep disk verify truncation (#3192)

slxng17581fb4cbaea0dc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 50352055d..b8750120f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -709,6 +709,43 @@ jobs:
- name: Run native installer wrapper tests
run: pytest tests/test_install/test_native_installers.py -q
+ # Runtime coverage for pure-Python proxy logic on Windows, kept separate
+ # from windows-native-wrapper (above), which is deliberately
+ # dependency-minimal and gated on native-installer changes only. Installs
+ # the latest published wheel from PyPI (real precompiled _core.pyd, no
+ # cargo/maturin build needed) so this branch's local ./headroom source
+ # tree can shadow it -- same shadowing the Linux `test` job relies on,
+ # just without needing our own freshly-built wheel, since none of the
+ # covered test files import headroom._core.
+ #
+ # Covers the full disk-verify session-token path, not just the
+ # interceptor: OpenCode config/launch-env building, the wrap opencode
+ # CLI command, and workspace-root registration through the real HTTP
+ # middleware -- so this gate actually exercises the OpenCode path, not
+ # only its final consumer.
+ windows-tool-result-interceptors:
+ needs: changes
+ if: needs.changes.outputs.code == 'true'
+ runs-on: windows-latest
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v6
+ with:
+ python-version: ${{ env.PY_VERSION }}
+ - name: Install headroom-ai[dev] (published wheel; local source shadows it)
+ run: |
+ python -m pip install --upgrade pip
+ pip install torch --index-url https://download.pytorch.org/whl/cpu
+ pip install "headroom-ai[dev]"
+ - name: Run disk-verify session-token path tests
+ shell: bash
+ run: |
+ pytest tests/test_tool_result_interceptors.py \
+ tests/test_providers_opencode_config.py \
+ tests/test_cli/test_wrap_opencode.py \
+ tests/test_proxy_workspace_registration_middleware.py -q
+
macos-native-wrapper:
needs: changes
if: needs.changes.outputs.native == 'true'
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 1c819c5a5..6146bde17 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -27,6 +27,7 @@ import io
import json
import os
import re
+import secrets
import shutil
import signal
import socket
@@ -3362,6 +3363,24 @@ def _apply_project_header_env(env: dict[str, str]) -> None:
)
+# Read by proxy's workspace_registry.resolve_registered_cwd() to look up
+# this session's registered cwd.
+_SESSION_TOKEN_HEADER_NAME = "X-Headroom-Session-Token"
+
+
+def _apply_session_token_header_env(env: dict[str, str], session_token: str) -> None:
+ """Inject X-Headroom-Session-Token into ``ANTHROPIC_CUSTOM_HEADERS``.
+
+ Mirrors :func:`_apply_project_header_env`. No "user override wins" case
+ here -- the token is wrap-generated, not user-supplied.
+ """
+ if not session_token:
+ return
+ header_line = f"{_SESSION_TOKEN_HEADER_NAME}: {session_token}"
+ existing = env.get("ANTHROPIC_CUSTOM_HEADERS")
+ env["ANTHROPIC_CUSTOM_HEADERS"] = f"{existing}\n{header_line}" if existing else header_line
+
+
# Codex's own built-in providers plus Headroom's injected one — never treated
# as a "custom upstream to preserve" by _detect_custom_codex_upstream_base_url.
_CODEX_BUILTIN_PROVIDER_NAMES = frozenset({"openai", "anthropic", "azure", "headroom"})
@@ -5279,11 +5298,19 @@ def _ensure_proxy(
def _client_marker_path(port: int) -> Path:
- """Path to this process's wrap-client marker for ``port``."""
+ """Path to this process's wrap-client marker for ``port``.
+
+ Mode 0700: markers carry ``cwd``/``session_token`` the proxy treats as
+ an authoritative binding, so only the invoking OS user may read them.
+ """
from headroom import paths as _paths
d = _paths.proxy_clients_dir(port)
d.mkdir(parents=True, exist_ok=True)
+ try:
+ os.chmod(d, 0o700)
+ except OSError:
+ pass
return d / f"{os.getpid()}.json"
@@ -5297,14 +5324,25 @@ def _proc_identity(pid: int) -> tuple[str, float] | None:
return proc_identity(pid)
-def _register_proxy_client(port: int) -> None:
+def _register_proxy_client(port: int, *, session_token: str | None = None) -> None:
"""Register this wrap process as a live client of the shared proxy.
- Best-effort: a failed write just means our marker is missing, and the
- liveness pruning in :func:`_live_proxy_clients` is the real safety net.
+ Also records ``cwd`` (wrap is the coding-agent CLI's real blocking
+ parent, so this is authoritative) and, if given, ``session_token`` --
+ also injected into the wrapped CLI's headers so the proxy can resolve
+ which registered cwd a request belongs to.
+
+ Best-effort: a failed write just means our marker is missing, and
+ :func:`_live_proxy_clients`'s liveness pruning is the real safety net.
"""
try:
- payload: dict[str, Any] = {"pid": os.getpid(), "started_at": time.time()}
+ payload: dict[str, Any] = {
+ "pid": os.getpid(),
+ "started_at": time.time(),
+ "cwd": os.getcwd(),
+ }
+ if session_token:
+ payload["session_token"] = session_token
ident = _proc_identity(os.getpid())
if ident is not None:
payload["start_src"], payload["start_time"] = ident
@@ -6097,7 +6135,10 @@ def claude(
upstream_for_proxy = foundry_upstream or custom_upstream
- _register_proxy_client(port)
+ # One token for the whole session -- written into the marker below
+ # and, further down, into the header the wrapped CLI sends.
+ _session_token = secrets.token_urlsafe(32)
+ _register_proxy_client(port, session_token=_session_token)
proxy_holder[0], actual_port = _ensure_proxy(
port,
no_proxy,
@@ -6113,7 +6154,7 @@ def claude(
)
if actual_port != port:
_unregister_proxy_client(port)
- _register_proxy_client(actual_port)
+ _register_proxy_client(actual_port, session_token=_session_token)
port_holder[0] = actual_port
_push_runtime_env(actual_port, no_proxy)
@@ -6251,6 +6292,8 @@ def claude(
# Per-project savings attribution: tag every request with the launch
# directory's name via X-Headroom-Project (user override wins).
_apply_project_header_env(env)
+ # Same token written into the marker above.
+ _apply_session_token_header_env(env, _session_token)
# Issue #746: keep Claude Code's on-demand tool loading on through the
# proxy so tool schemas are not eagerly materialized into local context.
@@ -8530,7 +8573,11 @@ def opencode(
# Register our proxy client marker BEFORE _ensure_proxy so that another
# wrapper's cleanup sees us as an active client and doesn't terminate a
# shared proxy during the startup gap.
- _register_proxy_client(port)
+ #
+ # Mirrors claude()'s token minting; only reaches OpenCode when the
+ # plugin layer is loaded (see build_launch_env).
+ _session_token = secrets.token_urlsafe(32)
+ _register_proxy_client(port, session_token=_session_token)
# Resolve port before config injection so the provider block and MCP
# URL both point at the port the proxy will actually be on.
@@ -8563,7 +8610,7 @@ def opencode(
# cleanup tracking stays accurate and update MCP config.
if actual_port != port:
_unregister_proxy_client(port)
- _register_proxy_client(actual_port)
+ _register_proxy_client(actual_port, session_token=_session_token)
if not no_mcp:
from headroom.mcp_registry import OpencodeRegistrar
@@ -8573,7 +8620,11 @@ def opencode(
if subscription_resolution is not None:
_scrub_copilot_subscription_launch_env(launch_environ)
env, env_vars_display = _build_opencode_launch_env(
- actual_port, launch_environ, project=_project_name_from_cwd(), include_mcp=not no_mcp
+ actual_port,
+ launch_environ,
+ project=_project_name_from_cwd(),
+ include_mcp=not no_mcp,
+ session_token=_session_token,
)
# Inject Headroom provider into OpenCode config so traffic routes through proxy.
diff --git a/headroom/providers/opencode/_dist/index.js b/headroom/providers/opencode/_dist/index.js
index ba470e58d..94d427074 100644
--- a/headroom/providers/opencode/_dist/index.js
+++ b/headroom/providers/opencode/_dist/index.js
@@ -12493,6 +12493,7 @@ var fs = nodeRequire("node:fs");
var BASE_URL_HEADER = "x-headroom-base-url";
var ORIGINAL_PATH_HEADER = "x-headroom-original-path";
var PROJECT_HEADER = "x-headroom-project";
+var SESSION_TOKEN_HEADER = "x-headroom-session-token";
var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
var EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport");
@@ -12684,7 +12685,7 @@ function requestUrl(input) {
}
return new URL(String(input));
}
-function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0) {
+function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0, sessionToken = void 0) {
const headers = new Headers(input instanceof Request ? input.headers : void 0);
if (init?.headers) {
new Headers(init.headers).forEach((value, key) => headers.set(key, value));
@@ -12699,9 +12700,12 @@ function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
return headers;
}
-function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
+function withRoutedFetchInput(input, init, proxy, project, excludeHosts, sessionToken) {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
return [input, init];
@@ -12709,7 +12713,7 @@ function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
- headers: mergeFetchHeaders(input, init, upstream, originalPath, project)
+ headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken)
};
if (input instanceof Request) {
return [new Request(nextUrl, input), nextInit];
@@ -12755,7 +12759,7 @@ function urlFromRequestOptions(options) {
return void 0;
}
}
-function headersForNodeRequest(options, upstream, originalPath, project) {
+function headersForNodeRequest(options, upstream, originalPath, project, sessionToken) {
const headers = new Headers(options.headers);
headers.set(BASE_URL_HEADER, upstream.origin);
if (originalPath) {
@@ -12764,6 +12768,9 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
headers.delete("host");
const result = {};
headers.forEach((value, key) => {
@@ -12771,7 +12778,7 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
});
return result;
}
-function routedNodeOptions(parts, proxy, project, excludeHosts) {
+function routedNodeOptions(parts, proxy, project, excludeHosts, sessionToken) {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return void 0;
}
@@ -12802,7 +12809,7 @@ function routedNodeOptions(parts, proxy, project, excludeHosts) {
hostname: nextUrl.hostname,
port: nextUrl.port || void 0,
path: `${nextUrl.pathname}${nextUrl.search}`,
- headers: headersForNodeRequest(parts.options, parts.url, originalPath, project)
+ headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken)
};
}
function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) {
@@ -12813,7 +12820,7 @@ function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest)
}
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
- const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
+ const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -12843,6 +12850,7 @@ function installHeadroomTransport(options) {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
+ existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -12852,6 +12860,7 @@ function installHeadroomTransport(options) {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
+ sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -12871,7 +12880,7 @@ function installHeadroomTransport(options) {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
- const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
+ const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest);
@@ -12919,6 +12928,9 @@ function resolveProxyUrl(options) {
options?.proxyUrl ?? process.env.HEADROOM_PROXY_URL ?? process.env.HEADROOM_BASE_URL ?? getDefaultProxyUrl()
);
}
+function resolveSessionToken(options) {
+ return options?.sessionToken ?? process.env.HEADROOM_OPENCODE_SESSION_TOKEN;
+}
function resolveExcludeHosts(options) {
return normalizeExcludeHosts(options?.excludeHosts ?? process.env[EXCLUDE_HOSTS_ENV] ?? "");
}
@@ -12938,7 +12950,7 @@ function openAiWireSuffix(pkg) {
if (pkg.endsWith("-responses") || pkg.endsWith("/responses")) return "/responses";
return void 0;
}
-function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts) {
+function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken) {
for (const model of models.list()) {
const providerID = String(model.providerID);
const modelID = String(model.id);
@@ -12954,7 +12966,8 @@ function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts) {
...draft.headers,
[BASE_URL_HEADER]: upstream.origin,
[ORIGINAL_PATH_HEADER]: `${trimTrailingSlashes(upstream.pathname)}${suffix}`,
- [PROJECT_HEADER]: project
+ [PROJECT_HEADER]: project,
+ ...sessionToken ? { [SESSION_TOKEN_HEADER]: sessionToken } : {}
};
});
}
@@ -12968,7 +12981,8 @@ var HeadroomPlugin = async (input, options = {}) => {
proxyUrl,
project,
excludeHosts: pluginOptions.excludeHosts,
- debug: pluginOptions.debug
+ debug: pluginOptions.debug,
+ sessionToken: resolveSessionToken(pluginOptions)
});
return {
dispose: async () => {
@@ -12996,15 +13010,17 @@ var headroomSetup = async (ctx) => {
const project = pluginOptions.project ?? ctx.location.project.id ?? ctx.location.directory;
const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
const excludeHosts = resolveExcludeHosts(pluginOptions);
+ const sessionToken = resolveSessionToken(pluginOptions);
const uninstallTransport = installHeadroomTransport({
proxyUrl,
project,
excludeHosts,
- debug: pluginOptions.debug
+ debug: pluginOptions.debug,
+ sessionToken
});
try {
await ctx.model.transform((models) => {
- routeModelsThroughProxy(models, proxyUrl, project, excludeHosts);
+ routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken);
});
await ctx.tool.transform((editor) => {
editor.add({
diff --git a/headroom/providers/opencode/hook-shim/handler.js b/headroom/providers/opencode/hook-shim/handler.js
index 19103e201..bee370b59 100644
--- a/headroom/providers/opencode/hook-shim/handler.js
+++ b/headroom/providers/opencode/hook-shim/handler.js
@@ -9,6 +9,7 @@ var fs = nodeRequire("node:fs");
var BASE_URL_HEADER = "x-headroom-base-url";
var ORIGINAL_PATH_HEADER = "x-headroom-original-path";
var PROJECT_HEADER = "x-headroom-project";
+var SESSION_TOKEN_HEADER = "x-headroom-session-token";
var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
var EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport");
@@ -193,7 +194,7 @@ function requestUrl(input) {
}
return new URL(String(input));
}
-function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0) {
+function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0, sessionToken = void 0) {
const headers = new Headers(input instanceof Request ? input.headers : void 0);
if (init?.headers) {
new Headers(init.headers).forEach((value, key) => headers.set(key, value));
@@ -208,9 +209,12 @@ function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
return headers;
}
-function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
+function withRoutedFetchInput(input, init, proxy, project, excludeHosts, sessionToken) {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
return [input, init];
@@ -218,7 +222,7 @@ function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
- headers: mergeFetchHeaders(input, init, upstream, originalPath, project)
+ headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken)
};
if (input instanceof Request) {
return [new Request(nextUrl, input), nextInit];
@@ -264,7 +268,7 @@ function urlFromRequestOptions(options) {
return void 0;
}
}
-function headersForNodeRequest(options, upstream, originalPath, project) {
+function headersForNodeRequest(options, upstream, originalPath, project, sessionToken) {
const headers = new Headers(options.headers);
headers.set(BASE_URL_HEADER, upstream.origin);
if (originalPath) {
@@ -273,6 +277,9 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
headers.delete("host");
const result = {};
headers.forEach((value, key) => {
@@ -280,7 +287,7 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
});
return result;
}
-function routedNodeOptions(parts, proxy, project, excludeHosts) {
+function routedNodeOptions(parts, proxy, project, excludeHosts, sessionToken) {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return void 0;
}
@@ -311,7 +318,7 @@ function routedNodeOptions(parts, proxy, project, excludeHosts) {
hostname: nextUrl.hostname,
port: nextUrl.port || void 0,
path: `${nextUrl.pathname}${nextUrl.search}`,
- headers: headersForNodeRequest(parts.options, parts.url, originalPath, project)
+ headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken)
};
}
function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) {
@@ -322,7 +329,7 @@ function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest)
}
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
- const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
+ const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -352,6 +359,7 @@ function installHeadroomTransport(options) {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
+ existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -361,6 +369,7 @@ function installHeadroomTransport(options) {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
+ sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -380,7 +389,7 @@ function installHeadroomTransport(options) {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
- const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
+ const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest);
diff --git a/headroom/providers/opencode/runtime.py b/headroom/providers/opencode/runtime.py
index c6db61e2d..85511e38a 100644
--- a/headroom/providers/opencode/runtime.py
+++ b/headroom/providers/opencode/runtime.py
@@ -217,6 +217,7 @@ def build_launch_env(
*,
include_mcp: bool = True,
include_plugin: bool = True,
+ session_token: str | None = None,
) -> tuple[dict[str, str], list[str]]:
"""Build environment variables for launching OpenCode through Headroom.
@@ -224,6 +225,11 @@ def build_launch_env(
Existing provider/base URL environment variables are preserved. When the
transport plugin is loaded, ``HEADROOM_PROXY_URL`` tells it which proxy to
route to.
+
+ ``session_token`` reaches the plugin (as
+ ``HEADROOM_OPENCODE_SESSION_TOKEN``) only when it's loaded -- the only
+ layer able to send a header. Without it, disk-verify stays ``UNKNOWN``,
+ same as Cursor.
"""
env = dict(environ or os.environ)
@@ -237,6 +243,8 @@ def build_launch_env(
display = ["OPENCODE_CONFIG_CONTENT={provider: headroom}"]
if "plugin" in config_content:
env["HEADROOM_PROXY_URL"] = f"http://127.0.0.1:{port}"
+ if session_token:
+ env["HEADROOM_OPENCODE_SESSION_TOKEN"] = session_token
display.append(f"plugin={HEADROOM_OPENCODE_PLUGIN}")
if project and "HEADROOM_PROJECT" not in env:
diff --git a/headroom/proxy/interceptors/astgrep.py b/headroom/proxy/interceptors/astgrep.py
index 460192892..b8130ab44 100644
--- a/headroom/proxy/interceptors/astgrep.py
+++ b/headroom/proxy/interceptors/astgrep.py
@@ -10,18 +10,23 @@ than three definitions to outline.
from __future__ import annotations
+import asyncio
import json
import logging
import os
+import re
import shutil
+import stat
import subprocess
import tempfile
+from enum import Enum
from pathlib import Path
from typing import Any
from headroom import binaries
from headroom._subprocess import run
from headroom.proxy import runtime_env
+from headroom.proxy.project_context import get_registered_cwd
from . import base
@@ -88,6 +93,220 @@ _PATTERNS: dict[str, list[str]] = {
OUTLINE_MARKER = " # ... (body elided by Headroom; Read a specific line range to see it)\n"
+# Per-client banner signatures -- add an entry only once a client's exact
+# banner text is confirmed, never a generic keyword match.
+_TRUNCATION_SIGNATURES: tuple[re.Pattern[str], ...] = (
+ # Claude Code: "[Truncated: PARTIAL view -- <path>: showing lines A-B of
+ # T total (...). Call Read with offset=N to see more.]"
+ re.compile(
+ r"\[\s*truncated\s*:\s*partial\s+view\b"
+ r"[^\[\]]*?"
+ r"showing\s+lines?\s+(?P<start_line>\d+)\s*[-–]\s*(?P<end_line>\d+)"
+ r"\s+of\s+(?P<total_lines>\d+)\s+total"
+ r"[^\[\]]*\]",
+ re.IGNORECASE,
+ ),
+)
+
+
+def _is_plausible_truncation_range(
+ start_line: int, end_line: int, total_lines: int, source_line_count: int
+) -> bool:
+ # end_line == total_lines means the whole file was shown, not truncated.
+ if start_line < 1 or end_line < start_line or end_line >= total_lines:
+ return False
+ return end_line <= source_line_count
+
+
+def _detect_truncation(source: str) -> tuple[int, int] | None:
+ """Return (end_line, total_lines) if `source` carries a recognized,
+ internally-consistent upstream truncation banner, else None."""
+ source_line_count = len(source.splitlines())
+ for pattern in _TRUNCATION_SIGNATURES:
+ for m in pattern.finditer(source):
+ start_line = int(m.group("start_line"))
+ end_line = int(m.group("end_line"))
+ total_lines = int(m.group("total_lines"))
+ if _is_plausible_truncation_range(start_line, end_line, total_lines, source_line_count):
+ return end_line, total_lines
+ return None
+
+
+class ReadVerificationResult(Enum):
+ """Client-independent fallback for `_detect_truncation`'s banner regex:
+ compares tool_output against the real file on disk instead of parsing
+ client-specific prose. Only used when the banner regex finds nothing.
+
+ Always UNKNOWN on Windows (no O_NOFOLLOW/dir_fd) -- never falls back to
+ a less-safe read."""
+
+ COMPLETE = "complete"
+ TRUNCATED = "truncated"
+ # Unresolvable path, unreadable file, or mismatched content — never guess.
+ UNKNOWN = "unknown"
+
+
+def _verify_truncation_on_disk_enabled() -> bool:
+ # Live read (not a module constant), matching _min_chars_to_rewrite()'s
+ # hot-reload behavior.
+ return runtime_env.getenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "").lower() in (
+ "1",
+ "true",
+ "yes",
+ )
+
+
+def _max_disk_verify_bytes() -> int:
+ # Live read, same hot-reload pattern as _min_chars_to_rewrite(). 5 MB
+ # comfortably covers real source files while bounding worst-case read
+ # time/memory for the disk-verify fallback.
+ try:
+ return int(runtime_env.getenv("HEADROOM_VERIFY_TRUNCATION_MAX_BYTES", "5000000"))
+ except (TypeError, ValueError):
+ return 5_000_000
+
+
+def _dir_fd_walk_supported() -> bool:
+ # hasattr, not bare os.O_NOFOLLOW/os.O_DIRECTORY refs -- missing on
+ # Windows, would AttributeError at import time otherwise.
+ return (
+ hasattr(os, "O_NOFOLLOW") and hasattr(os, "O_DIRECTORY") and os.open in os.supports_dir_fd
+ )
+
+
+def _on_event_loop_thread() -> bool:
+ """True only on a thread with a running asyncio loop (the request
+ coroutine) -- false on a plain ThreadPoolExecutor worker. Lets the
+ blocking read refuse itself if ever reached directly from the loop."""
+ try:
+ asyncio.get_running_loop()
+ except RuntimeError:
+ return False
+ return True
+
+
+def _open_regular_file_under_root(
+ file_path: str, resolved_root: Path, max_bytes: int
+) -> str | None:
+ """Race-safe read of `file_path` confined under `resolved_root`.
+
+ Walks from an fd opened on `resolved_root` using dir_fd-relative,
+ O_NOFOLLOW opens at every hop -- no full path is ever resolved then
+ reopened, so there's no TOCTOU window for a symlink swap to exploit.
+ Refuses if called on the event-loop thread or if this platform lacks
+ dir_fd support (notably Windows) -- no less-safe fallback either way.
+ """
+ if _on_event_loop_thread() or not _dir_fd_walk_supported():
+ return None
+
+ # Pure string math -- no I/O, can't itself be raced.
+ candidate = (
+ file_path if os.path.isabs(file_path) else os.path.join(str(resolved_root), file_path)
+ )
+ rel = os.path.relpath(os.path.normpath(candidate), str(resolved_root))
+ if rel == os.curdir:
+ return None # the root itself, not a file within it
+ if rel == os.pardir or rel.startswith(os.pardir + os.sep) or os.path.isabs(rel):
+ return None # escapes resolved_root
+ segments = [s for s in rel.split(os.sep) if s]
+ if not segments or any(s in (os.curdir, os.pardir) for s in segments):
+ return None
+
+ try:
+ # resolved_root already went through resolve(strict=True) in the
+ # caller, so it's symlink-free at that instant -- O_NOFOLLOW here
+ # closes the residual window where the anchor itself gets swapped
+ # for a symlink between that resolve() and this open().
+ current_fd = os.open(str(resolved_root), os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+ except OSError:
+ return None
+
+ file_fd = -1
+ try:
+ for segment in segments[:-1]:
+ try:
+ next_fd = os.open(
+ segment, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=current_fd
+ )
+ except OSError:
+ return None
+ os.close(current_fd)
+ current_fd = next_fd
+
+ final = segments[-1]
+ try:
+ # O_NONBLOCK: a FIFO with no writer returns immediately instead
+ # of blocking -- no effect once fstat confirms a regular file.
+ file_fd = os.open(
+ final,
+ os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW,
+ dir_fd=current_fd,
+ )
+ except OSError:
+ return None
+
+ try:
+ st = os.fstat(file_fd)
+ if not stat.S_ISREG(st.st_mode) or st.st_size > max_bytes:
+ return None
+ with os.fdopen(file_fd, "rb") as f:
+ file_fd = -1 # ownership transferred to the file object
+ data = f.read(max_bytes + 1)
+ # fstat can go stale by read time -- a regular file can grow
+ # between the two. Bound the read itself rather than trust the
+ # earlier size check; one byte past the cap is enough to detect
+ # an overflow without ever reading an unbounded amount.
+ if len(data) > max_bytes:
+ return None
+ return data.decode("utf-8")
+ except (OSError, UnicodeDecodeError):
+ return None
+ finally:
+ if file_fd >= 0:
+ os.close(file_fd)
+ if current_fd >= 0:
+ os.close(current_fd)
+
+
+def _verify_read_against_disk(
+ file_path: str | None,
+ received_content: str,
+ registered_cwd: str | None,
+) -> tuple[ReadVerificationResult, tuple[int, int] | None]:
+ """Compare `received_content` against the real file at `file_path`.
+
+ `registered_cwd` is `project_context.get_registered_cwd()`, not a raw
+ header -- non-None only when a session token matched a workspace root
+ `wrap` itself registered (see workspace_registry.py). Its presence is
+ the trust signal; there's no separate boolean to check.
+
+ TRUNCATED requires an exact-prefix match with strictly more on disk —
+ a weaker match means the file diverged since the client read it, not
+ a provable truncation, so it's UNKNOWN. Returns `(visible_lines,
+ total_lines)` alongside TRUNCATED so the header can cite real numbers
+ without a second, potentially racy, read.
+ """
+ if not file_path:
+ return ReadVerificationResult.UNKNOWN, None
+ if not registered_cwd or not os.path.isabs(registered_cwd):
+ return ReadVerificationResult.UNKNOWN, None
+ try:
+ resolved_root = Path(registered_cwd).resolve(strict=True)
+ except OSError:
+ return ReadVerificationResult.UNKNOWN, None
+ if not resolved_root.is_dir():
+ return ReadVerificationResult.UNKNOWN, None
+ disk_content = _open_regular_file_under_root(file_path, resolved_root, _max_disk_verify_bytes())
+ if disk_content is None:
+ return ReadVerificationResult.UNKNOWN, None
+ if disk_content == received_content:
+ return ReadVerificationResult.COMPLETE, None
+ if disk_content.startswith(received_content) and len(disk_content) > len(received_content):
+ visible_lines = len(received_content.splitlines())
+ total_lines = len(disk_content.splitlines())
+ return ReadVerificationResult.TRUNCATED, (visible_lines, total_lines)
+ return ReadVerificationResult.UNKNOWN, None
+
class AstGrepReadOutline:
"""Interceptor that outlines verbose code-file Read outputs."""
@@ -131,7 +350,17 @@ class AstGrepReadOutline:
if not matches:
return None
- outline = _build_outline(matches, tool_output)
+ # Banner (cheap, no I/O) wins; disk verification is the opt-in fallback.
+ truncation = _detect_truncation(tool_output)
+ if truncation is None and _verify_truncation_on_disk_enabled():
+ verdict, disk_truncation = _verify_read_against_disk(
+ _path_from_input(tool_input),
+ tool_output,
+ get_registered_cwd(),
+ )
+ if verdict is ReadVerificationResult.TRUNCATED:
+ truncation = disk_truncation
+ outline = _build_outline(matches, tool_output, truncation)
return outline if outline else None
def progressive_disclosure_key(
@@ -258,12 +487,21 @@ def _run_ast_grep(
return all_matches
-def _build_outline(matches: list[dict[str, Any]], source: str) -> str | None:
+def _build_outline(
+ matches: list[dict[str, Any]],
+ source: str,
+ truncation: tuple[int, int] | None = None,
+) -> str | None:
"""Build a compact outline from ast-grep matches.
Emits each definition's signature line + docstring (if next line is a
string literal) + an elision marker. Matches are sorted by byte offset
so the outline tracks the original file order.
+
+ `truncation`, if given, is (end_line, total_lines) from an upstream
+ truncation banner already present in `source` (e.g. a client's own Read
+ token-cap notice). When set, the header states that the input was a
+ partial view instead of implying `source` is the whole file.
"""
lines = source.splitlines(keepends=True)
outline_chunks: list[str] = []
@@ -292,11 +530,21 @@ def _build_outline(matches: list[dict[str, Any]], source: str) -> str | None:
if not outline_chunks:
return None
- header = (
- "[headroom: outlined by ast-grep — "
- f"{len(seen_starts)} definition(s); "
- "bodies elided. Re-read the file with a line range to see a specific body.]\n"
- )
+
+ if truncation:
+ end_line, total_lines = truncation
+ header = (
+ "[headroom: outlined by ast-grep — "
+ f"{len(seen_starts)} definition(s) in the visible portion; "
+ f"input was truncated upstream (showing through line {end_line} of {total_lines} total). "
+ "Bodies elided. Re-read remaining lines to see more.]\n"
+ )
+ else:
+ header = (
+ "[headroom: outlined by ast-grep — "
+ f"{len(seen_starts)} definition(s); "
+ "bodies elided. Re-read the file with a line range to see a specific body.]\n"
+ )
return header + "".join(outline_chunks)
diff --git a/headroom/proxy/project_context.py b/headroom/proxy/project_context.py
index d6a446c68..5210f8377 100644
--- a/headroom/proxy/project_context.py
+++ b/headroom/proxy/project_context.py
@@ -11,6 +11,13 @@ savings to a project without threading a parameter through every handler.
The value is sanitized (printable characters only, length-capped) before it
is stored; an absent or unusable header simply leaves attribution off for
that request, matching pre-feature behavior.
+
+A second contextvar, ``_current_registered_cwd``, is what disk verification
+trusts as a workspace root. It is never a raw header value — it's the
+result of ``workspace_registry.resolve_registered_cwd()``, which matches a
+session token against a workspace root ``headroom wrap`` itself registered
+over a trusted local channel (a 0700 marker file). A request can only
+*reference* a pre-established root this way, never assert an arbitrary one.
"""
from __future__ import annotations
@@ -31,6 +38,11 @@ from headroom.proxy.savings_tracker import sanitize_project_name
_current_project: ContextVar[str | None] = ContextVar("headroom_current_project", default=None)
+# Server-verified, not header-derived -- see module docstring.
+_current_registered_cwd: ContextVar[str | None] = ContextVar(
+ "headroom_current_registered_cwd", default=None
+)
+
def set_current_project(project: str | None) -> None:
"""Bind the active request's project for downstream outcome recording."""
@@ -42,6 +54,16 @@ def get_current_project() -> str | None:
return _current_project.get()
+def set_registered_cwd(cwd: str | None) -> None:
+ """Bind the server-verified workspace root resolved for this request."""
+ _current_registered_cwd.set(cwd)
+
+
+def get_registered_cwd() -> str | None:
+ """Server-verified workspace root for the current request, or ``None``."""
+ return _current_registered_cwd.get()
+
+
def strip_project_path_prefix(scope: MutableMapping[str, Any]) -> str | None:
"""Strip a ``/p/<name>`` prefix from an ASGI scope, returning the name.
@@ -59,7 +81,9 @@ __all__ = [
"PROJECT_PATH_PREFIX",
"classify_project",
"get_current_project",
+ "get_registered_cwd",
"set_current_project",
+ "set_registered_cwd",
"split_project_path",
"strip_project_path_prefix",
"with_project_prefix",
diff --git a/headroom/proxy/runtime_env.py b/headroom/proxy/runtime_env.py
index 500c236b1..a3415042e 100644
--- a/headroom/proxy/runtime_env.py
+++ b/headroom/proxy/runtime_env.py
@@ -73,6 +73,17 @@ RUNTIME_ENV_KNOBS: tuple[Knob, ...] = (
"int",
"Min tool-output chars before the ast-grep read rewrite.",
),
+ Knob(
+ "HEADROOM_VERIFY_TRUNCATION_ON_DISK",
+ "bool",
+ "Verify ast-grep Read truncation against disk when no client banner is found. "
+ "Always UNKNOWN on Windows (no dir_fd/O_NOFOLLOW support).",
+ ),
+ Knob(
+ "HEADROOM_VERIFY_TRUNCATION_MAX_BYTES",
+ "int",
+ "Max on-disk file size (bytes) the disk-verify fallback will read.",
+ ),
)
_KNOBS_BY_ENV: dict[str, Knob] = {k.env: k for k in RUNTIME_ENV_KNOBS}
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index efbcc389c..a30213761 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -183,6 +183,7 @@ from headroom.proxy.probe_recorder import probe_recorder_from_env
from headroom.proxy.project_context import (
classify_project,
set_current_project,
+ set_registered_cwd,
strip_project_path_prefix,
)
from headroom.proxy.prometheus_metrics import PrometheusMetrics # noqa: F401
@@ -200,6 +201,7 @@ from headroom.proxy.tcp_keepalive import install_tcp_keepalive
from headroom.proxy.tool_schema_savings_policy import tool_schema_saved_from_tags
from headroom.proxy.upstream_pinning import install_upstream_pinning
from headroom.proxy.warmup import WarmupRegistry
+from headroom.proxy.workspace_registry import resolve_registered_cwd
from headroom.proxy.ws_session_registry import WebSocketSessionRegistry
from headroom.subscription.base import get_quota_registry, reset_quota_registry
from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state
@@ -1791,7 +1793,12 @@ class HeadroomProxy(
remaining,
)
- future = loop.run_in_executor(self._compression_executor, _wrapped)
+ # run_in_executor doesn't copy contextvars into the worker thread
+ # (unlike asyncio.to_thread) -- without this, get_registered_cwd()
+ # etc. would silently see the ContextVar default, not what the
+ # request middleware bound.
+ ctx = contextvars.copy_context()
+ future = loop.run_in_executor(self._compression_executor, ctx.run, _wrapped)
try:
return await asyncio.wait_for(future, timeout=timeout)
except asyncio.TimeoutError:
@@ -1816,7 +1823,9 @@ class HeadroomProxy(
Runs on the dedicated single-thread background executor.
"""
loop = asyncio.get_running_loop()
- return await loop.run_in_executor(self._background_compression_executor, fn)
+ # Same context-propagation fix as _run_compression_in_executor above.
+ ctx = contextvars.copy_context()
+ return await loop.run_in_executor(self._background_compression_executor, ctx.run, fn)
# How often the lazy TTL sweep in `_get_compression_cache` may run.
_COMPRESSION_CACHE_CLEANUP_INTERVAL_SECONDS = 60.0
@@ -3985,6 +3994,12 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
query = request.url.query
headers = dict(request.headers.items())
set_current_project(classify_project(headers) or prefix_project)
+ # Non-None only if a live wrap session registered this exact token
+ # (workspace_registry.py) -- the caller-supplied x-headroom-cwd
+ # header is never itself sufficient authority.
+ set_registered_cwd(
+ resolve_registered_cwd(config.port, headers.get("x-headroom-session-token"))
+ )
# Path-based Codex identification: stamp X-Client: codex on the
# Responses endpoint for callers that don't otherwise classify (e.g.
# Codex Desktop, whose User-Agent isn't a known codex UA). Without it
diff --git a/headroom/proxy/workspace_registry.py b/headroom/proxy/workspace_registry.py
new file mode 100644
index 000000000..f0c60b8a7
--- /dev/null
+++ b/headroom/proxy/workspace_registry.py
@@ -0,0 +1,61 @@
+"""Server-side lookup of a wrap session's real workspace root.
+
+``headroom wrap`` is the true, blocking parent of the coding-agent CLI it
+launches, so its own ``os.getcwd()`` at launch time is authoritative for
+that session. It records ``(session_token, cwd)`` into the same per-PID
+marker file it already writes for proxy-client liveness tracking
+(``paths.proxy_clients_dir(port)``), hardened to mode ``0700`` -- only the
+invoking OS user can read or write there.
+
+That's what makes ``session_token`` meaningfully different from the
+``x-headroom-cwd`` header (PR #3192's review rejected trusting it directly):
+the header's value was fully caller-chosen, so any loopback/SSRF-capable
+caller could assert an arbitrary directory. A token only lets a caller
+*reference* a root ``wrap`` already established over a channel an
+HTTP-only attacker can't write to.
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+
+from headroom import fsutil, paths
+from headroom.proxy_client_liveness import marker_pid_reused, pid_alive
+
+
+def resolve_registered_cwd(port: int, session_token: str | None) -> str | None:
+ """Return the real cwd registered for `session_token` on `port`, or `None`.
+
+ `None` if the token is missing/blank, no marker matches it, or the
+ matching marker's process is no longer live -- never a guess. Read-only:
+ doesn't prune stale markers itself, that's wrap.py's job.
+ """
+ if not session_token:
+ return None
+ token_bytes = session_token.encode("utf-8", "replace")
+ d = paths.proxy_clients_dir(port)
+ if not d.exists():
+ return None
+ for marker in d.glob("*.json"):
+ try:
+ pid = int(marker.stem)
+ except ValueError:
+ continue
+ try:
+ payload = json.loads(fsutil.read_text(marker))
+ except (OSError, ValueError):
+ continue
+ if not isinstance(payload, dict):
+ continue
+ candidate = payload.get("session_token")
+ if not isinstance(candidate, str):
+ continue
+ # Constant-time compare, same precedent as HEADROOM_PROXY_TOKEN.
+ if not hmac.compare_digest(candidate.encode("utf-8", "replace"), token_bytes):
+ continue
+ if not pid_alive(pid) or marker_pid_reused(marker, pid):
+ return None # matched but stale -- never guess
+ cwd = payload.get("cwd")
+ return cwd if isinstance(cwd, str) and cwd else None
+ return None
diff --git a/headroom/proxy_client_liveness.py b/headroom/proxy_client_liveness.py
new file mode 100644
index 000000000..dd1f8e7be
--- /dev/null
+++ b/headroom/proxy_client_liveness.py
@@ -0,0 +1,77 @@
+"""Shared PID-liveness/identity primitives for wrap-client marker files.
+
+Both wrap.py (tearing down a shared proxy) and the proxy itself (resolving
+a registered workspace root) need to answer "is the process that wrote this
+marker still alive?" -- kept here once, importable from both, instead of
+duplicated. No CLI dependencies, so the proxy can import it directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from headroom import fsutil
+from headroom._subprocess import pid_alive
+
+__all__ = ["identity_mismatch", "marker_pid_reused", "pid_alive", "proc_identity"]
+
+
+def proc_identity(pid: int) -> tuple[str, float] | None:
+ """Best-effort ``(source, start_time)`` identity for a PID.
+
+ Used to defeat PID reuse: a marker is only trusted while the live PID is
+ *the same process* that wrote it. Returns ``None`` when start time can't be
+ determined (e.g. macOS without psutil), in which case callers fall back to
+ existence-only liveness -- no regression, just no reuse protection there.
+
+ The ``source`` tag ("psutil" vs "proc") guards against comparing values in
+ different units; we only compare like-for-like.
+ """
+ try:
+ import psutil # type: ignore[import-untyped] # optional dependency; portable when present
+
+ return ("psutil", psutil.Process(pid).create_time())
+ except Exception:
+ pass
+ # Linux fallback: field 22 of /proc/<pid>/stat is starttime in clock ticks
+ # since boot -- a stable per-process value. `comm` (field 2) may contain
+ # spaces/parens, so split after the final ')'.
+ try:
+ with open(f"/proc/{pid}/stat", "rb") as fh:
+ fields = fh.read().rpartition(b")")[2].split()
+ return ("proc", float(fields[19]))
+ except (OSError, IndexError, ValueError):
+ return None
+
+
+def identity_mismatch(src: Any, recorded: Any, pid: int) -> bool:
+ """True only if ``pid``'s current identity *provably* differs from the
+ recorded ``(src, recorded)`` identity (i.e. the PID was recycled).
+
+ Conservative by design: any uncertainty (unknown/legacy identity, unknown
+ start time, mismatched source) returns ``False`` -- never claim a mismatch
+ without proof, since callers use this to decide whether to trust or
+ discard state tied to a live PID.
+ """
+ if not isinstance(src, str) or not isinstance(recorded, int | float):
+ return False # legacy / identity-less record -- can't tell
+ ident = proc_identity(pid)
+ if ident is None or ident[0] != src:
+ return False # can't compare like-for-like -- don't claim mismatch
+ # Start times are stable per process; >1s apart means a different process.
+ return abs(ident[1] - float(recorded)) > 1.0
+
+
+def marker_pid_reused(marker: Path, pid: int) -> bool:
+ """True only if the live ``pid`` is *provably* a different process than the
+ one that wrote ``marker`` (i.e. the PID was recycled after a crash)."""
+ import json
+
+ try:
+ rec = json.loads(fsutil.read_text(marker))
+ except (OSError, ValueError):
+ return False
+ if not isinstance(rec, dict):
+ return False
+ return identity_mismatch(rec.get("start_src"), rec.get("start_time"), pid)
diff --git a/plugins/opencode/src/plugin.test.ts b/plugins/opencode/src/plugin.test.ts
index a6e6d412c..58be2500d 100644
--- a/plugins/opencode/src/plugin.test.ts
+++ b/plugins/opencode/src/plugin.test.ts
@@ -489,3 +489,25 @@ describe("default export", () => {
});
});
});
+
+
+describe("OpenCode 2.x workspace session identity", () => {
+ it.each([undefined, "explicit-session"])("carries the resolved session token through both routes (%s)", async (sessionToken) => {
+ vi.stubEnv("HEADROOM_OPENCODE_SESSION_TOKEN", "environment-session");
+ const models: FakeModel[] = [{
+ id: "custom", providerID: "gateway",
+ package: "@opencode/ai/providers/openai-compatible",
+ settings: { baseURL: "https://gateway.example/v1" },
+ }];
+ const { context } = pluginContextV2({ sessionToken }, { models });
+ const cleanup = await headroomSetup(context);
+ try {
+ const expected = sessionToken ?? "environment-session";
+ expect(models[0].headers?.["x-headroom-session-token"]).toBe(expected);
+ expect((globalThis as Record<symbol, { sessionToken?: string }>)[TRANSPORT_STATE]?.sessionToken).toBe(expected);
+ } finally {
+ await cleanup?.();
+ vi.unstubAllEnvs();
+ }
+ });
+});
diff --git a/plugins/opencode/src/plugin.ts b/plugins/opencode/src/plugin.ts
index da922aeae..8abda4f5d 100644
--- a/plugins/opencode/src/plugin.ts
+++ b/plugins/opencode/src/plugin.ts
@@ -13,6 +13,7 @@ import {
EXCLUDE_HOSTS_ENV,
ORIGINAL_PATH_HEADER,
PROJECT_HEADER,
+ SESSION_TOKEN_HEADER,
installHeadroomTransport,
modelBaseRoutesThroughProxy,
normalizeExcludeHosts,
@@ -24,6 +25,7 @@ export interface HeadroomOpenCodePluginOptions {
excludeHosts?: string[];
backend?: string;
debug?: boolean;
+ sessionToken?: string;
}
export const HEADROOM_PLUGIN_ID = "headroom";
@@ -41,6 +43,13 @@ function resolveProxyUrl(options?: HeadroomOpenCodePluginOptions): string {
);
}
+// Read by workspace_registry.resolve_registered_cwd() on the proxy side --
+// mirrors wrap.py's _apply_session_token_header_env for claude.
+function resolveSessionToken(options?: HeadroomOpenCodePluginOptions): string | undefined {
+ return options?.sessionToken ?? process.env.HEADROOM_OPENCODE_SESSION_TOKEN;
+}
+
+
// The exclusion list governs both the transport patch and the 2.x model
// rewrite, so resolve it once: option over environment variable, normalized
// the same way the transport does.
@@ -86,6 +95,7 @@ function routeModelsThroughProxy(
proxyUrl: string,
project: string,
excludeHosts: string[],
+ sessionToken?: string,
): void {
for (const model of models.list()) {
// DeepMutable turns the branded ID strings into object types.
@@ -104,6 +114,7 @@ function routeModelsThroughProxy(
[BASE_URL_HEADER]: upstream.origin,
[ORIGINAL_PATH_HEADER]: `${trimTrailingSlashes(upstream.pathname)}${suffix}`,
[PROJECT_HEADER]: project,
+ ...(sessionToken ? { [SESSION_TOKEN_HEADER]: sessionToken } : {}),
};
});
}
@@ -123,6 +134,7 @@ export const HeadroomPlugin: Plugin = async (input, options = {}) => {
project,
excludeHosts: pluginOptions.excludeHosts,
debug: pluginOptions.debug,
+ sessionToken: resolveSessionToken(pluginOptions),
});
return {
@@ -158,16 +170,18 @@ export const headroomSetup: PluginV2.Plugin["setup"] = async (ctx) => {
pluginOptions.project ?? ctx.location.project.id ?? ctx.location.directory;
const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
const excludeHosts = resolveExcludeHosts(pluginOptions);
+ const sessionToken = resolveSessionToken(pluginOptions);
const uninstallTransport = installHeadroomTransport({
proxyUrl,
project,
excludeHosts,
debug: pluginOptions.debug,
+ sessionToken,
});
try {
await ctx.model.transform((models) => {
- routeModelsThroughProxy(models, proxyUrl, project, excludeHosts);
+ routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken);
});
await ctx.tool.transform((editor) => {
editor.add({
diff --git a/plugins/opencode/src/transport.test.ts b/plugins/opencode/src/transport.test.ts
index 16c47b29d..16459062d 100644
--- a/plugins/opencode/src/transport.test.ts
+++ b/plugins/opencode/src/transport.test.ts
@@ -930,4 +930,114 @@ describe("Headroom OpenCode transport", () => {
expect(http.request).toBe(originalHttpRequest);
expect(https.request).toBe(originalHttpsRequest);
});
+
+ it("sends x-headroom-session-token header on routed fetch calls when sessionToken is set", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "tok-abc" });
+
+ await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
+
+ const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
+ expect(headers.get("x-headroom-session-token")).toBe("tok-abc");
+
+ globalThis.fetch = originalFetch;
+ });
+
+ it("omits x-headroom-session-token header when sessionToken is not set", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
+
+ const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
+ expect(headers.get("x-headroom-session-token")).toBeNull();
+
+ globalThis.fetch = originalFetch;
+ });
+
+ it("omits x-headroom-session-token header when sessionToken is an empty string", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "" });
+
+ await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
+
+ const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
+ expect(headers.get("x-headroom-session-token")).toBeNull();
+
+ globalThis.fetch = originalFetch;
+ });
+
+ it("sends x-headroom-session-token header on routed Node https.request calls when sessionToken is set", async () => {
+ const proxy = await proxyServer();
+ installHeadroomTransport({ proxyUrl: proxy.url, sessionToken: "tok-abc" });
+
+ await new Promise<void>((resolve, reject) => {
+ const req = https.request(
+ "https://api.anthropic.com/v1/messages",
+ { method: "POST" },
+ (res) => {
+ res.resume();
+ res.on("end", resolve);
+ },
+ );
+ req.on("error", reject);
+ req.end("{}");
+ });
+
+ expect(proxy.seen[0].headers["x-headroom-session-token"]).toBe("tok-abc");
+
+ await proxy.close();
+ });
+
+ it("updates the session token on reinstall rather than keeping the first value", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ const firstDispose = installHeadroomTransport({
+ proxyUrl: "http://127.0.0.1:8787/v1",
+ sessionToken: "tok-A",
+ });
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "tok-B" });
+
+ await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
+
+ const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
+ expect(headers.get("x-headroom-session-token")).toBe("tok-B");
+
+ firstDispose();
+ globalThis.fetch = originalFetch;
+ });
+
+ it("clears the session token on reinstall when the new options omit it", async () => {
+ // Deliberate: reinstall is last-write-wins for every InstallOptions
+ // field (proxyUrl, project, debug already work this way) -- an install
+ // without a token must not leave a stale one active.
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ const firstDispose = installHeadroomTransport({
+ proxyUrl: "http://127.0.0.1:8787/v1",
+ sessionToken: "tok-A",
+ });
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
+
+ const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
+ expect(headers.get("x-headroom-session-token")).toBeNull();
+
+ firstDispose();
+ globalThis.fetch = originalFetch;
+ });
});
diff --git a/plugins/opencode/src/transport.ts b/plugins/opencode/src/transport.ts
index 355da0028..135fa3820 100644
--- a/plugins/opencode/src/transport.ts
+++ b/plugins/opencode/src/transport.ts
@@ -10,6 +10,7 @@ const fs = nodeRequire("node:fs") as typeof import("node:fs");
export const BASE_URL_HEADER = "x-headroom-base-url";
export const ORIGINAL_PATH_HEADER = "x-headroom-original-path";
export const PROJECT_HEADER = "x-headroom-project";
+export const SESSION_TOKEN_HEADER = "x-headroom-session-token";
const PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
export const EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
const STATE_KEY = Symbol.for("headroom.opencode.transport");
@@ -30,6 +31,7 @@ interface InstallOptions {
project?: string;
excludeHosts?: string[];
debug?: boolean;
+ sessionToken?: string;
}
interface TransportState {
@@ -38,6 +40,7 @@ interface TransportState {
project: string | undefined;
excludeHosts: string[];
debug: boolean;
+ sessionToken: string | undefined;
originalFetch: typeof fetch;
originalHttpRequest: HttpRequest;
originalHttpGet: HttpGet;
@@ -325,6 +328,7 @@ function mergeFetchHeaders(
upstream: URL | undefined,
originalPath: string | undefined = undefined,
project: string | undefined = undefined,
+ sessionToken: string | undefined = undefined,
): Headers {
const headers = new Headers(input instanceof Request ? input.headers : undefined);
if (init?.headers) {
@@ -340,6 +344,9 @@ function mergeFetchHeaders(
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
return headers;
}
@@ -349,6 +356,7 @@ function withRoutedFetchInput(
proxy: URL,
project: string | undefined,
excludeHosts: string[],
+ sessionToken: string | undefined,
): FetchArgs {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
@@ -358,7 +366,7 @@ function withRoutedFetchInput(
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
- headers: mergeFetchHeaders(input, init, upstream, originalPath, project),
+ headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken),
};
if (input instanceof Request) {
@@ -416,6 +424,7 @@ function headersForNodeRequest(
upstream: URL,
originalPath: string | undefined,
project: string | undefined,
+ sessionToken: string | undefined,
): Record<string, string> {
const headers = new Headers(options.headers as HeadersInit | undefined);
headers.set(BASE_URL_HEADER, upstream.origin);
@@ -425,6 +434,9 @@ function headersForNodeRequest(
if (project) {
headers.set(PROJECT_HEADER, project);
}
+ if (sessionToken) {
+ headers.set(SESSION_TOKEN_HEADER, sessionToken);
+ }
headers.delete("host");
const result: Record<string, string> = {};
@@ -439,6 +451,7 @@ function routedNodeOptions(
proxy: URL,
project: string | undefined,
excludeHosts: string[],
+ sessionToken: string | undefined,
): Record<string, unknown> | undefined {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return undefined;
@@ -472,7 +485,7 @@ function routedNodeOptions(
hostname: nextUrl.hostname,
port: nextUrl.port || undefined,
path: `${nextUrl.pathname}${nextUrl.search}`,
- headers: headersForNodeRequest(parts.options, parts.url, originalPath, project),
+ headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken),
};
}
@@ -489,7 +502,7 @@ function wrapRequest(
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
- const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
+ const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -527,6 +540,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
+ existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -537,6 +551,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
+ sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -557,7 +572,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
- const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
+ const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
diff --git a/tests/test_cli/test_wrap_claude_base_url.py b/tests/test_cli/test_wrap_claude_base_url.py
index 591ba9c1d..0d376bf9b 100644
--- a/tests/test_cli/test_wrap_claude_base_url.py
+++ b/tests/test_cli/test_wrap_claude_base_url.py
@@ -8,6 +8,7 @@ from pathlib import Path
import click
import pytest
+from headroom import proxy_client_liveness
from headroom.cli import wrap as wrap_cli
@@ -300,10 +301,16 @@ def test_wrap_marker_is_not_stale_for_live_pid(tmp_path: Path) -> None:
def test_wrap_marker_is_stale_when_pid_reused(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
- # Inject a deterministic PID identity: _proc_identity returns None on
+ # Inject a deterministic PID identity: proc_identity returns None on
# macOS without psutil, where reuse detection is deliberately best-effort
- # and this scenario would be undetectable.
- monkeypatch.setattr(wrap_cli, "_proc_identity", lambda pid: ("test", 50_000.0))
+ # and this scenario would be undetectable. Two targets needed: the write
+ # path (_write_wrap_marker) calls wrap_cli's own _proc_identity name
+ # directly; the later staleness check (_wrap_marker_is_stale ->
+ # _identity_mismatch) resolves proc_identity from proxy_client_liveness's
+ # own globals -- patching only one leaves the other on the real impl.
+ identity = lambda pid: ("test", 50_000.0) # noqa: E731
+ monkeypatch.setattr(wrap_cli, "_proc_identity", identity)
+ monkeypatch.setattr(proxy_client_liveness, "proc_identity", identity)
path = _settings(tmp_path)
wrap_cli._write_claude_wrap_base_url("http://127.0.0.1:8787", settings_path=path, port=8787)
marker = json.loads(_marker(tmp_path).read_text(encoding="utf-8"))
diff --git a/tests/test_cli/test_wrap_claude_finally_unbound.py b/tests/test_cli/test_wrap_claude_finally_unbound.py
index c51f8bed8..be0673a8e 100644
--- a/tests/test_cli/test_wrap_claude_finally_unbound.py
+++ b/tests/test_cli/test_wrap_claude_finally_unbound.py
@@ -32,7 +32,7 @@ def test_finally_survives_early_proxy_start_failure(
monkeypatch.delenv(key, raising=False)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
- monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port: None)
+ monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port, session_token=None: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *_a, **_k: None)
monkeypatch.setattr(wrap_mod, "_push_runtime_env", lambda *_a, **_k: None)
monkeypatch.setattr(wrap_mod, "_setup_coding_compressor", lambda *_a, **_k: None)
diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
index 7d7825e60..10dab084f 100644
--- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
+++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
@@ -66,7 +66,7 @@ def _invoke_wrap_claude(
_clear_claude_mode_env(monkeypatch)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
- monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port: None)
+ monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port, session_token=None: None)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda _holder, _port: lambda: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *_args, **_kwargs: None)
monkeypatch.setattr(wrap_mod, "_push_runtime_env", lambda *_args, **_kwargs: None)
@@ -163,7 +163,11 @@ def test_wrap_claude_rejects_conflicting_auth_before_proxy_mutation(
monkeypatch.setattr(wrap_mod, "claude_user_settings_path", lambda: user_settings)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
proxy_calls: list[int] = []
- monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda port: proxy_calls.append(port))
+ monkeypatch.setattr(
+ wrap_mod,
+ "_register_proxy_client",
+ lambda port, session_token=None: proxy_calls.append(port),
+ )
result = runner.invoke(
main,
diff --git a/tests/test_cli/test_wrap_opencode.py b/tests/test_cli/test_wrap_opencode.py
index d7912a0cc..cd0e0c610 100644
--- a/tests/test_cli/test_wrap_opencode.py
+++ b/tests/test_cli/test_wrap_opencode.py
@@ -1716,3 +1716,40 @@ def test_wrap_source_has_no_raw_control_bytes() -> None:
# tell the escape from a raw 0x08 byte typed into the file. Check the bytes.
source = Path(wrap_mod.__file__).read_bytes().decode("utf-8")
assert _has_control_chars(source.replace("\r", "")) == []
+
+
+def test_wrap_opencode_session_token_matches_registration(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Same token must reach both proxy registration and the child env --
+ two independent presence checks could each pass with mismatched values."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ captured: dict[str, object] = {}
+ register_calls: list[dict[str, object]] = []
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ def spying_register(port, **kwargs): # noqa: ANN001, ANN003
+ register_calls.append(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_register_proxy_client", side_effect=spying_register):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ assert register_calls, "expected _register_proxy_client to be called"
+ registered_token = register_calls[0].get("session_token")
+ assert registered_token, "expected a non-empty session_token to be registered"
+
+ env = captured["env"]
+ assert isinstance(env, dict)
+ # Assumes the plugin resolves (packaged bundle ships in this checkout);
+ # see test_build_launch_env_omits_session_token_when_plugin_absent.
+ assert env.get("HEADROOM_OPENCODE_SESSION_TOKEN") == registered_token
diff --git a/tests/test_cli/test_wrap_workspace_registration.py b/tests/test_cli/test_wrap_workspace_registration.py
new file mode 100644
index 000000000..6ec8044b0
--- /dev/null
+++ b/tests/test_cli/test_wrap_workspace_registration.py
@@ -0,0 +1,89 @@
+"""Tests for wrap.py's workspace-root registration: marker cwd/session_token
+fields, the 0700 hardening, and session-token header injection."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+
+import pytest
+
+from headroom import paths
+from headroom.cli import wrap as wrap_cli
+
+
+def _marker_payload(port: int, pid: int) -> dict:
+ path = paths.proxy_clients_dir(port) / f"{pid}.json"
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def test_register_proxy_client_records_real_cwd(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "myproject"
+ project_dir.mkdir()
+ monkeypatch.chdir(project_dir)
+ try:
+ wrap_cli._register_proxy_client(8787)
+ payload = _marker_payload(8787, os.getpid())
+ # os.getcwd() resolves symlinks (e.g. macOS /tmp -> /private/tmp);
+ # compare against the same resolution, not the raw tmp_path string.
+ assert payload["cwd"] == os.getcwd()
+ assert "session_token" not in payload # no token passed -- optional
+ finally:
+ wrap_cli._unregister_proxy_client(8787)
+
+
+def test_register_proxy_client_records_session_token_when_given(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ try:
+ wrap_cli._register_proxy_client(8788, session_token="tok-xyz")
+ payload = _marker_payload(8788, os.getpid())
+ assert payload["session_token"] == "tok-xyz"
+ finally:
+ wrap_cli._unregister_proxy_client(8788)
+
+
[email protected](sys.platform == "win32", reason="POSIX file mode bits")
+def test_client_marker_directory_is_hardened_to_0700(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ try:
+ wrap_cli._register_proxy_client(8789)
+ mode = stat.S_IMODE(paths.proxy_clients_dir(8789).stat().st_mode)
+ assert mode == 0o700
+ finally:
+ wrap_cli._unregister_proxy_client(8789)
+
+
+def test_apply_session_token_header_env_sets_fresh_header():
+ env: dict[str, str] = {}
+ wrap_cli._apply_session_token_header_env(env, "tok-123")
+ assert env["ANTHROPIC_CUSTOM_HEADERS"] == "X-Headroom-Session-Token: tok-123"
+
+
+def test_apply_session_token_header_env_appends_to_existing_headers():
+ env = {"ANTHROPIC_CUSTOM_HEADERS": "X-Some-Other: value"}
+ wrap_cli._apply_session_token_header_env(env, "tok-123")
+ assert env["ANTHROPIC_CUSTOM_HEADERS"] == (
+ "X-Some-Other: value\nX-Headroom-Session-Token: tok-123"
+ )
+
+
+def test_apply_session_token_header_env_noop_for_blank_token():
+ env: dict[str, str] = {}
+ wrap_cli._apply_session_token_header_env(env, "")
+ assert "ANTHROPIC_CUSTOM_HEADERS" not in env
+
+
+def test_claude_launch_uses_one_token_for_marker_and_header():
+ """Same token must reach both the marker and the header, or lookups
+ never match."""
+ import secrets as _secrets
+
+ token = _secrets.token_urlsafe(32)
+ env: dict[str, str] = {}
+ wrap_cli._apply_session_token_header_env(env, token)
+ header_line = env["ANTHROPIC_CUSTOM_HEADERS"]
+ assert token in header_line
+ assert header_line.startswith(f"{wrap_cli._SESSION_TOKEN_HEADER_NAME}:")
diff --git a/tests/test_providers_opencode_config.py b/tests/test_providers_opencode_config.py
index 212809a5a..dcbc21573 100644
--- a/tests/test_providers_opencode_config.py
+++ b/tests/test_providers_opencode_config.py
@@ -596,6 +596,42 @@ def test_build_launch_env_with_project(monkeypatch: pytest.MonkeyPatch, tmp_path
assert "ANTHROPIC_BASE_URL" not in env
+def test_build_launch_env_forwards_session_token_when_plugin_present(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ """Token reaches OpenCode only via the transport plugin -- the only
+ header-capable layer (native baseURL is header-blind, like Cursor)."""
+ from headroom.providers.opencode.runtime import build_launch_env
+
+ plugin = tmp_path / "entry.opencode.js"
+ plugin.write_text("export default () => {}", encoding="utf-8")
+ monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))
+
+ env, _display = build_launch_env(
+ port=8787,
+ include_mcp=False,
+ session_token="tok-abc",
+ )
+ assert env["HEADROOM_OPENCODE_SESSION_TOKEN"] == "tok-abc"
+
+
+def test_build_launch_env_omits_session_token_when_plugin_absent(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ """No plugin -> no header surface -> token must not be forwarded,
+ same as Cursor's UNKNOWN."""
+ from headroom.providers.opencode.runtime import build_launch_env
+
+ monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))
+
+ env, _display = build_launch_env(
+ port=8787,
+ include_mcp=False,
+ session_token="tok-abc",
+ )
+ assert "HEADROOM_OPENCODE_SESSION_TOKEN" not in env
+
+
def test_build_launch_env_with_custom_environ() -> None:
from headroom.providers.opencode.runtime import build_launch_env
diff --git a/tests/test_proxy_client_liveness.py b/tests/test_proxy_client_liveness.py
new file mode 100644
index 000000000..b599a90ac
--- /dev/null
+++ b/tests/test_proxy_client_liveness.py
@@ -0,0 +1,72 @@
+"""Tests for headroom.proxy_client_liveness -- extracted from wrap.py so both
+the CLI and the proxy (workspace_registry.py) share one liveness/identity
+source of truth rather than two independently-decaying ones.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from headroom import proxy_client_liveness as liveness
+
+
+def test_pid_alive_true_for_current_process():
+ assert liveness.pid_alive(os.getpid()) is True
+
+
+def test_pid_alive_false_for_pid_zero_or_negative():
+ assert liveness.pid_alive(0) is False
+ assert liveness.pid_alive(-1) is False
+
+
+def test_identity_mismatch_conservative_false_for_legacy_record():
+ """No start_src/start_time recorded (pre-identity marker format) -- must
+ not claim a mismatch without proof."""
+ assert liveness.identity_mismatch(None, None, os.getpid()) is False
+
+
+def test_identity_mismatch_conservative_false_for_wrong_types():
+ assert liveness.identity_mismatch(123, "not-a-number", os.getpid()) is False
+ assert liveness.identity_mismatch("psutil", "not-a-number", os.getpid()) is False
+
+
+def test_identity_mismatch_false_when_identity_matches_self():
+ ident = liveness.proc_identity(os.getpid())
+ if ident is None:
+ return # platform can't determine identity -- nothing to assert
+ src, start_time = ident
+ assert liveness.identity_mismatch(src, start_time, os.getpid()) is False
+
+
+def test_marker_pid_reused_false_for_malformed_marker(tmp_path):
+ marker = tmp_path / "123.json"
+ marker.write_text("{not valid json", encoding="utf-8")
+ assert liveness.marker_pid_reused(marker, os.getpid()) is False
+
+
+def test_marker_pid_reused_false_for_missing_marker(tmp_path):
+ marker = tmp_path / "does-not-exist.json"
+ assert liveness.marker_pid_reused(marker, os.getpid()) is False
+
+
+def test_marker_pid_reused_false_for_non_object_json(tmp_path):
+ """Valid JSON that isn't an object (e.g. a bare list) must not crash via
+ AttributeError on .get() -- same bug class as the malformed-syntax case,
+ just a step further past json.loads succeeding."""
+ marker = tmp_path / "123.json"
+ marker.write_text("[1, 2, 3]", encoding="utf-8")
+ assert liveness.marker_pid_reused(marker, os.getpid()) is False
+
+
+def test_marker_pid_reused_false_when_recorded_identity_matches_self(tmp_path):
+ ident = liveness.proc_identity(os.getpid())
+ if ident is None:
+ return
+ src, start_time = ident
+ marker = tmp_path / f"{os.getpid()}.json"
+ marker.write_text(
+ json.dumps({"pid": os.getpid(), "start_src": src, "start_time": start_time}),
+ encoding="utf-8",
+ )
+ assert liveness.marker_pid_reused(marker, os.getpid()) is False
diff --git a/tests/test_proxy_compression_executor.py b/tests/test_proxy_compression_executor.py
index 7659c4eeb..4d34475f9 100644
--- a/tests/test_proxy_compression_executor.py
+++ b/tests/test_proxy_compression_executor.py
@@ -145,6 +145,62 @@ def test_in_flight_gauge_tracks_running_compressions() -> None:
assert proxy._compression_in_flight == 0
+def test_contextvars_set_before_submission_are_visible_inside_the_worker() -> None:
+ """`run_in_executor` doesn't copy contextvars into the worker thread by
+ default (unlike `asyncio.to_thread`) -- without the fix, code reading
+ `get_registered_cwd()` there would silently see the default, not what
+ request middleware bound. Locks the fix with a generic ContextVar and
+ the real one astgrep.py's disk-verify depends on."""
+ import contextvars
+
+ from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
+
+ proxy = _make_proxy(compression_max_workers=2)
+ probe: contextvars.ContextVar[str | None] = contextvars.ContextVar("test_probe", default=None)
+ observed: dict[str, object] = {}
+
+ def _read_contextvars_on_worker_thread():
+ observed["probe"] = probe.get()
+ observed["registered_cwd"] = get_registered_cwd()
+ return "done"
+
+ async def _drive():
+ probe.set("set-on-calling-coroutine")
+ set_registered_cwd("/some/registered/project")
+ return await proxy._run_compression_in_executor(
+ _read_contextvars_on_worker_thread, timeout=5.0
+ )
+
+ result = asyncio.run(_drive())
+ assert result == "done"
+ assert observed["probe"] == "set-on-calling-coroutine"
+ assert observed["registered_cwd"] == "/some/registered/project"
+
+
+def test_contextvars_propagate_through_background_executor_too() -> None:
+ """Same fix, same bug class, but the *other* submission point --
+ `_run_compression_background` (no timeout, no leaked-thread accounting)
+ -- has its own `contextvars.copy_context()` call, not shared code with
+ `_run_compression_in_executor`. Covered separately since a fix at one
+ call site doesn't imply the other was fixed too."""
+ from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
+
+ proxy = _make_proxy(compression_max_workers=1)
+ observed: dict[str, object] = {}
+
+ def _read_registered_cwd_on_worker_thread():
+ observed["registered_cwd"] = get_registered_cwd()
+ return "done"
+
+ async def _drive():
+ set_registered_cwd("/some/other/registered/project")
+ return await proxy._run_compression_background(_read_registered_cwd_on_worker_thread)
+
+ result = asyncio.run(_drive())
+ assert result == "done"
+ assert observed["registered_cwd"] == "/some/other/registered/project"
+
+
def test_high_water_mark_persists_after_completion() -> None:
"""``_compression_in_flight_max`` is monotonic — never decreases."""
proxy = _make_proxy(compression_max_workers=8)
diff --git a/tests/test_proxy_workspace_registration_middleware.py b/tests/test_proxy_workspace_registration_middleware.py
new file mode 100644
index 000000000..642b397a3
--- /dev/null
+++ b/tests/test_proxy_workspace_registration_middleware.py
@@ -0,0 +1,142 @@
+"""End-to-end test of workspace-root registration through the real HTTP
+middleware, including isolation between concurrent sessions on one proxy."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from headroom import paths
+from headroom.proxy.server import ProxyConfig, create_app
+
+_TEST_PORT = 18787
+
+
+def _make_app() -> FastAPI:
+ return create_app(
+ ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ port=_TEST_PORT,
+ )
+ )
+
+
+def _app_with_registered_cwd_probe() -> FastAPI:
+ """Test-only route reading get_registered_cwd() after the middleware runs."""
+ from headroom.proxy.project_context import get_registered_cwd
+
+ app = _make_app()
+
+ @app.get("/__test/registered-cwd")
+ def _probe() -> dict[str, str | None]:
+ return {"registered_cwd": get_registered_cwd()}
+
+ # A catch-all passthrough route registered by create_app() would
+ # otherwise shadow this path -- Starlette matches routes in
+ # registration order, not by specificity.
+ app.router.routes.insert(0, app.router.routes.pop())
+ return app
+
+
+def _write_marker(pid: int, session_token: str, cwd: str) -> None:
+ d = paths.proxy_clients_dir(_TEST_PORT)
+ d.mkdir(parents=True, exist_ok=True)
+ (d / f"{pid}.json").write_text(
+ json.dumps({"pid": pid, "session_token": session_token, "cwd": cwd}),
+ encoding="utf-8",
+ )
+
+
+def test_valid_session_token_resolves_registered_cwd(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ _write_marker(os.getpid(), "tok-real", str(project_dir))
+
+ client = TestClient(_app_with_registered_cwd_probe())
+ resp = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-real"})
+ assert resp.json() == {"registered_cwd": str(project_dir)}
+
+
+def test_opencode_registration_marker_resolves_through_real_middleware(tmp_path, monkeypatch):
+ """Closes the seam the reviewer flagged: proves there's no schema drift
+ between what opencode()'s wrap command actually writes
+ (wrap._register_proxy_client -- the same function claude() calls, not
+ a hand-rolled test marker) and what resolve_registered_cwd() reads,
+ using the lowercase header casing the OpenCode transport plugin sends
+ (vs. claude's title-case) over the real HTTP middleware."""
+ from headroom.cli import wrap as wrap_mod
+
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "opencode-project"
+ project_dir.mkdir()
+ monkeypatch.chdir(project_dir)
+ wrap_mod._register_proxy_client(_TEST_PORT, session_token="tok-opencode")
+
+ client = TestClient(_app_with_registered_cwd_probe())
+ resp = client.get(
+ "/__test/registered-cwd", headers={"x-headroom-session-token": "tok-opencode"}
+ )
+ assert resp.json() == {"registered_cwd": str(project_dir)}
+
+
+def test_missing_or_wrong_token_resolves_to_none(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ _write_marker(os.getpid(), "tok-real", str(project_dir))
+
+ client = TestClient(_app_with_registered_cwd_probe())
+ no_token = client.get("/__test/registered-cwd")
+ assert no_token.json() == {"registered_cwd": None}
+
+ wrong_token = client.get(
+ "/__test/registered-cwd", headers={"x-headroom-session-token": "tok-guessed"}
+ )
+ assert wrong_token.json() == {"registered_cwd": None}
+
+
+def test_spoofed_cwd_header_alone_never_resolves_anything(tmp_path, monkeypatch):
+ """A spoofed x-headroom-cwd with no matching registration must never
+ surface as the registered root."""
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ client = TestClient(_app_with_registered_cwd_probe())
+ resp = client.get("/__test/registered-cwd", headers={"x-headroom-cwd": "/etc"})
+ assert resp.json() == {"registered_cwd": None}
+
+
+def test_two_concurrent_sessions_on_one_shared_proxy_stay_isolated(tmp_path, monkeypatch):
+ """Token A must resolve only project A's cwd, never project B's."""
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_a = tmp_path / "project-a"
+ project_b = tmp_path / "project-b"
+ project_a.mkdir()
+ project_b.mkdir()
+
+ import subprocess
+ import sys
+
+ child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
+ try:
+ _write_marker(os.getpid(), "tok-a", str(project_a))
+ _write_marker(child.pid, "tok-b", str(project_b))
+
+ client = TestClient(_app_with_registered_cwd_probe())
+ resp_a = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-a"})
+ resp_b = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-b"})
+ assert resp_a.json() == {"registered_cwd": str(project_a)}
+ assert resp_b.json() == {"registered_cwd": str(project_b)}
+ finally:
+ child.kill()
+ child.wait()
diff --git a/tests/test_tool_result_interceptors.py b/tests/test_tool_result_interceptors.py
index 432c2c51b..4fe419355 100644
--- a/tests/test_tool_result_interceptors.py
+++ b/tests/test_tool_result_interceptors.py
@@ -2,7 +2,11 @@
from __future__ import annotations
+import asyncio
+import os
+import sys
import textwrap
+from types import SimpleNamespace
import pytest
@@ -14,8 +18,14 @@ from headroom.proxy.interceptors import (
interceptor_failure_counts,
register,
)
-from headroom.proxy.interceptors.astgrep import AstGrepReadOutline
+from headroom.proxy.interceptors.astgrep import (
+ AstGrepReadOutline,
+ ReadVerificationResult,
+ _open_regular_file_under_root,
+ _verify_read_against_disk,
+)
from headroom.proxy.interceptors.base import reset_interceptor_failure_counts
+from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
from headroom.tokenizer import Tokenizer
@@ -211,6 +221,561 @@ def test_astgrep_outlines_large_python_read(tokenizer):
assert "def apply_promo" in new_content
# Bodies should NOT leak through unchanged.
assert "total += item.price * item.qty" not in new_content
+ # Complete-file control: no truncation banner in the input -> no truncation marker.
+ assert "truncated upstream" not in new_content
+
+
+def test_astgrep_flags_truncated_read(tokenizer):
+ truncated_source = (
+ _PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
+ "showing lines 1-42 of 90 total (26031 tokens, cap 25000). "
+ "Call Read with offset=43 to see more.]\n"
+ )
+ messages = [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "abc",
+ "name": "Read",
+ "input": {"file_path": "/repo/payments.py"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "abc", "content": truncated_source}],
+ },
+ ]
+ result = apply_to_messages(messages, tokenizer)
+ assert len(result.spans) == 1
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" in new_content
+ assert "showing through line 42 of 90 total" in new_content
+ # Still lists the definitions actually present in the visible portion.
+ assert "def process_payment" in new_content
+ assert "def apply_promo" in new_content
+
+
+def _read_result_messages(content: str, file_path: str = "/repo/payments.py"):
+ return [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "abc",
+ "name": "Read",
+ "input": {"file_path": file_path},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "abc", "content": content}],
+ },
+ ]
+
+
+def test_astgrep_flags_truncated_read_wording_variants(tokenizer):
+ """The signature tolerates wording/casing/dash variation, but only inside
+ the recognized envelope — not as a synonym match over arbitrary prose."""
+ truncated_source = (
+ _PY_FIXTURE + "\n\n[TRUNCATED: PARTIAL VIEW — /repo/payments.py: "
+ "SHOWING LINES 1–42 of 90 TOTAL. Call Read with offset=43 to see more.]\n"
+ )
+ messages = _read_result_messages(truncated_source)
+ result = apply_to_messages(messages, tokenizer)
+ assert len(result.spans) == 1
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" in new_content
+ assert "showing through line 42 of 90 total" in new_content
+
+
+def test_astgrep_ignores_truncation_phrase_in_comment(tokenizer):
+ """A count-shaped phrase in a plain comment, with no bracketed envelope,
+ must not be read as an upstream truncation claim."""
+ source_with_comment = (
+ _PY_FIXTURE + "\n\n# API pagination showing lines 10-20 of 30 total records\n"
+ )
+ messages = _read_result_messages(source_with_comment)
+ result = apply_to_messages(messages, tokenizer)
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" not in new_content
+
+
+def test_astgrep_ignores_bracketed_phrase_without_signature(tokenizer):
+ """Brackets plus a count-shaped phrase aren't enough on their own — the
+ exact recognized signature phrase must also be present."""
+ source_with_bracket = (
+ _PY_FIXTURE + "\n\n[Truncation happened; showing lines 1-42 of 90 total]\n"
+ )
+ messages = _read_result_messages(source_with_bracket)
+ result = apply_to_messages(messages, tokenizer)
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" not in new_content
+
+
+ "banner_numbers",
+ [
+ pytest.param("50-90 of 90", id="end_equals_total"),
+ pytest.param("42-10 of 90", id="end_less_than_start"),
+ pytest.param("0-42 of 90", id="start_is_zero"),
+ pytest.param("1-5000 of 9000", id="end_exceeds_visible_payload"),
+ ],
+)
+def test_astgrep_ignores_malformed_truncation_counts(tokenizer, banner_numbers):
+ truncated_source = (
+ _PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
+ f"showing lines {banner_numbers} total (26031 tokens, cap 25000). "
+ "Call Read with offset=43 to see more.]\n"
+ )
+ messages = _read_result_messages(truncated_source)
+ result = apply_to_messages(messages, tokenizer)
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "outlined by ast-grep" in new_content
+ assert "truncated upstream" not in new_content
+
+
+def test_astgrep_accepts_truncation_at_start_equals_end(tokenizer):
+ """`end >= start` is inclusive — a single-line visible window is valid."""
+ truncated_source = (
+ _PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
+ "showing lines 42-42 of 90 total (26031 tokens, cap 25000). "
+ "Call Read with offset=43 to see more.]\n"
+ )
+ messages = _read_result_messages(truncated_source)
+ result = apply_to_messages(messages, tokenizer)
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" in new_content
+
+
+# -------- Disk verification: client-independent truncation fallback ----- #
+
+
+def test_set_get_registered_cwd_round_trips():
+ set_registered_cwd("/repo/project")
+ try:
+ assert get_registered_cwd() == "/repo/project"
+ finally:
+ set_registered_cwd(None)
+
+
+class TestVerifyReadAgainstDisk:
+ def test_missing_file_path_is_unknown(self):
+ verdict, info = _verify_read_against_disk(None, "abc", "/repo")
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_no_registered_cwd_is_unknown(self):
+ verdict, info = _verify_read_against_disk("payments.py", "abc", None)
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_untrusted_request_never_touches_disk(self, tmp_path, monkeypatch):
+ """A valid file/content combo must short-circuit to UNKNOWN -- and
+ never call os.open -- when no root is registered."""
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ opened: list[object] = []
+ real_open = os.open
+
+ def _tracking_open(*args, **kwargs):
+ opened.append(args)
+ return real_open(*args, **kwargs)
+
+ monkeypatch.setattr(os, "open", _tracking_open)
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, None)
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+ assert opened == []
+
+ def test_missing_file_under_workspace_root_is_unknown(self, tmp_path):
+ verdict, info = _verify_read_against_disk(
+ str(tmp_path / "missing.py"), "abc", str(tmp_path)
+ )
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ @pytest.mark.skipif(
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
+ )
+ def test_exact_match_is_complete(self, tmp_path):
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
+ assert verdict is ReadVerificationResult.COMPLETE
+ assert info is None
+
+ @pytest.mark.skipif(
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
+ )
+ def test_strict_prefix_is_truncated(self, tmp_path):
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ partial = _PY_FIXTURE[:200]
+ verdict, info = _verify_read_against_disk(str(f), partial, str(tmp_path))
+ assert verdict is ReadVerificationResult.TRUNCATED
+ assert info == (len(partial.splitlines()), len(_PY_FIXTURE.splitlines()))
+
+ @pytest.mark.skipif(
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
+ )
+ def test_relative_path_resolves_against_registered_cwd(self, tmp_path):
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ partial = _PY_FIXTURE[:200]
+ verdict, info = _verify_read_against_disk("payments.py", partial, str(tmp_path))
+ assert verdict is ReadVerificationResult.TRUNCATED
+ assert info is not None
+
+ def test_content_mismatch_is_unknown_not_truncated(self, tmp_path):
+ # File diverged since the client read it -- not a clean prefix.
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE.replace("compute_subtotal", "compute_total"), encoding="utf-8")
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_absolute_path_outside_workspace_root_is_unknown(self, tmp_path):
+ root = tmp_path / "project"
+ root.mkdir()
+ sibling = tmp_path / "other"
+ sibling.mkdir()
+ f = sibling / "secret.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(root))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_relative_traversal_escapes_workspace_is_unknown(self, tmp_path):
+ root = tmp_path / "project"
+ root.mkdir()
+ f = tmp_path / "secret.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ verdict, info = _verify_read_against_disk("../secret.py", _PY_FIXTURE, str(root))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_sibling_directory_sharing_string_prefix_is_not_inside_workspace(self, tmp_path):
+ """Containment is a path-segment check (relpath/segment split), not
+ a string-prefix check -- a target that merely starts with the
+ root's string must not be treated as inside it."""
+ root = tmp_path / "project"
+ root.mkdir()
+ other = tmp_path / "project-other"
+ other.mkdir()
+ f = other / "secret.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(root))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_directory_passed_as_file_path_is_unknown(self, tmp_path):
+ root = tmp_path / "project"
+ subdir = root / "subdir"
+ subdir.mkdir(parents=True)
+ verdict, info = _verify_read_against_disk("subdir", "abc", str(root))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+ def test_oversized_file_exceeding_byte_cap_is_unknown(self, tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_MAX_BYTES", "10")
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ assert len(_PY_FIXTURE.encode("utf-8")) > 10
+ # Content matches exactly -- would be COMPLETE without the cap.
+ verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
+ assert verdict is ReadVerificationResult.UNKNOWN
+ assert info is None
+
+
+# -------- _open_regular_file_under_root: race-safety + off-loop (review round 2) --------- #
+
+
[email protected](sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
+def test_open_regular_file_under_root_rejects_symlinked_final_file(tmp_path):
+ """A symlinked leaf file must be rejected by O_NOFOLLOW, not followed.
+
+ A static symlink is sufficient race evidence here: O_NOFOLLOW rejects it
+ the same way whether it's always been there or appeared 2ms ago -- a
+ concurrent-race harness would prove nothing more and would be flaky.
+ """
+ root = tmp_path / "project"
+ root.mkdir()
+ outside = tmp_path / "outside.py"
+ outside.write_text(_PY_FIXTURE, encoding="utf-8")
+ link = root / "link.py"
+ link.symlink_to(outside)
+ assert _open_regular_file_under_root("link.py", root, 10_000) is None
+
+
[email protected](sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
+def test_open_regular_file_under_root_rejects_symlinked_intermediate_directory(tmp_path):
+ """A symlinked directory component must be rejected at that hop, not
+ walked into."""
+ root = tmp_path / "project"
+ root.mkdir()
+ real_dir = tmp_path / "realdir"
+ real_dir.mkdir()
+ (real_dir / "secret.py").write_text(_PY_FIXTURE, encoding="utf-8")
+ link_dir = root / "linkdir"
+ link_dir.symlink_to(real_dir)
+ assert _open_regular_file_under_root("linkdir/secret.py", root, 10_000) is None
+
+
[email protected](sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
+def test_open_regular_file_under_root_rejects_symlinked_root_anchor(tmp_path):
+ """The root anchor itself must be opened O_NOFOLLOW too, not just the
+ segments below it -- otherwise a symlink swapped in at the resolved root
+ path would be followed, the exact TOCTOU shape review round 2 flagged,
+ just moved from the leaf to the anchor."""
+ real_root = tmp_path / "real-project"
+ real_root.mkdir()
+ (real_root / "x.py").write_text("content", encoding="utf-8")
+ root_link = tmp_path / "project-link"
+ root_link.symlink_to(real_root)
+ assert _open_regular_file_under_root("x.py", root_link, 10_000) is None
+
+
+def test_open_regular_file_under_root_refuses_on_event_loop_thread(tmp_path):
+ """Calling from inside a running event loop must refuse immediately
+ rather than perform the read."""
+ f = tmp_path / "x.py"
+ f.write_text("content", encoding="utf-8")
+
+ async def _call_from_loop():
+ return _open_regular_file_under_root(str(f), tmp_path, 10_000)
+
+ assert asyncio.run(_call_from_loop()) is None
+
+
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
+)
+def test_open_regular_file_under_root_proceeds_from_plain_sync_context(tmp_path):
+ """Sanity check: with no running loop, the read must still succeed."""
+ f = tmp_path / "x.py"
+ f.write_text("content", encoding="utf-8")
+ assert _open_regular_file_under_root(str(f), tmp_path, 10_000) == "content"
+
+
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
+)
+def test_open_regular_file_under_root_rejects_growth_between_stat_and_read(tmp_path, monkeypatch):
+ """A file that grows past max_bytes between the fstat check and the
+ read must fail closed to None, not return the oversized content -- the
+ fstat result can go stale by the time the read actually runs. The file
+ genuinely contains >max_bytes on disk; only the fstat result lies, so a
+ passing test proves the read itself is bounded, not that fstat was
+ merely re-checked."""
+ f = tmp_path / "x.py"
+ f.write_bytes(b"x" * 1_000_001)
+
+ real_fstat = os.fstat
+
+ def lying_fstat(fd):
+ real_st = real_fstat(fd)
+ return SimpleNamespace(st_mode=real_st.st_mode, st_size=1)
+
+ monkeypatch.setattr(os, "fstat", lying_fstat)
+ assert _open_regular_file_under_root("x.py", tmp_path, max_bytes=8) is None
+
+
+def test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported(
+ tmp_path, monkeypatch
+):
+ """Fails closed (None) rather than falling back to a less-safe pattern
+ when dir_fd-relative opens aren't supported (notably Windows)."""
+ import headroom.proxy.interceptors.astgrep as astgrep_module
+
+ f = tmp_path / "x.py"
+ f.write_text("content", encoding="utf-8")
+ monkeypatch.setattr(astgrep_module, "_dir_fd_walk_supported", lambda: False)
+ assert _open_regular_file_under_root(str(f), tmp_path, 10_000) is None
+
+
+def test_open_regular_file_under_root_directory_passed_as_target_is_unknown(tmp_path):
+ """A directory at the leaf position must be rejected -- the target must
+ be a file."""
+ (tmp_path / "subdir").mkdir()
+ assert _open_regular_file_under_root("subdir", tmp_path, 10_000) is None
+
+
[email protected](sys.platform == "win32", reason="os.mkfifo unavailable on Windows")
+def test_open_regular_file_under_root_rejects_fifo_without_hanging(tmp_path):
+ """A FIFO must be rejected by the S_ISREG check, and -- because the open
+ uses O_NONBLOCK -- must return promptly rather than blocking on a
+ writer that will never arrive. If this test hangs, O_NONBLOCK regressed."""
+ fifo_path = tmp_path / "pipe"
+ os.mkfifo(fifo_path)
+ assert _open_regular_file_under_root("pipe", tmp_path, 10_000) is None
+
+
+# -------- End-to-end: apply_to_messages, real registered_cwd --------- #
+
+
+def _disk_verification_messages(partial: str) -> list[dict]:
+ return [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "abc",
+ "name": "Read",
+ "input": {"file_path": "payments.py"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "abc", "content": partial}],
+ },
+ ]
+
+
+ sys.platform == "win32",
+ reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
+ " (see test_astgrep_disk_verification_stays_unknown_when_dir_fd_unsupported)",
+)
+def test_astgrep_disk_verification_flags_truncation_when_no_banner(
+ tokenizer, tmp_path, monkeypatch
+):
+ """Opted in, root registered, real on-disk prefix, no banner -- disk
+ verification alone qualifies the header."""
+ monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
+ monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ marker = "\n\ndef format_receipt"
+ partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)] # no banner text anywhere
+ assert "truncated" not in partial.lower()
+
+ set_registered_cwd(str(tmp_path))
+ try:
+ result = apply_to_messages(_disk_verification_messages(partial), tokenizer)
+ finally:
+ set_registered_cwd(None)
+
+ assert len(result.spans) == 1
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" in new_content
+ visible_lines = len(partial.splitlines())
+ total_lines = len(_PY_FIXTURE.splitlines())
+ assert f"showing through line {visible_lines} of {total_lines} total" in new_content
+ assert "def compute_subtotal" in new_content
+ assert "def apply_promo" in new_content
+ assert "def format_receipt" not in new_content
+
+
+def test_astgrep_disk_verification_stays_unknown_when_dir_fd_unsupported(
+ tokenizer, tmp_path, monkeypatch
+):
+ """Fail-closed contract, simulated cross-platform: dir_fd unsupported ->
+ UNKNOWN -> no false "truncated upstream" claim. Stands in for the real
+ Windows behavior the skipif'd tests above can't exercise here."""
+ import headroom.proxy.interceptors.astgrep as astgrep_module
+
+ monkeypatch.setattr(astgrep_module, "_dir_fd_walk_supported", lambda: False)
+ monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
+ monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ marker = "\n\ndef format_receipt"
+ partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)] # no banner text anywhere
+ assert "truncated" not in partial.lower()
+
+ set_registered_cwd(str(tmp_path))
+ try:
+ result = apply_to_messages(_disk_verification_messages(partial), tokenizer)
+ finally:
+ set_registered_cwd(None)
+
+ # The outline rewrite is independent of the disk-verify verdict.
+ assert len(result.spans) == 1
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" not in new_content
+
+
+def test_astgrep_disk_verification_skips_when_no_root_registered(tokenizer, tmp_path, monkeypatch):
+ """No registered root at all (the default) -- opted in, real on-disk
+ prefix, but never flags. Spoofed-header-doesn't-work is covered
+ end-to-end in test_proxy_workspace_registration_middleware.py."""
+ monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
+ monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
+ f = tmp_path / "payments.py"
+ f.write_text(_PY_FIXTURE, encoding="utf-8")
+ marker = "\n\ndef format_receipt"
+ partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)]
+
+ messages = [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "abc",
+ "name": "Read",
+ "input": {"file_path": "payments.py"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "abc", "content": partial}],
+ },
+ ]
+ result = apply_to_messages(messages, tokenizer)
+
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "truncated upstream" not in new_content
+
+
+def test_astgrep_banner_detection_takes_priority_over_disk_verification(tokenizer, monkeypatch):
+ """When a banner is already present, disk verification must not run at
+ all (no cwd bound here -- if it ran, resolution would fail anyway), and
+ the banner's own numbers must be what the header reports."""
+ monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
+ truncated_source = (
+ _PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
+ "showing lines 1-42 of 90 total (26031 tokens, cap 25000). "
+ "Call Read with offset=43 to see more.]\n"
+ )
+ messages = [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "abc",
+ "name": "Read",
+ "input": {"file_path": "/repo/payments.py"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "abc", "content": truncated_source}],
+ },
+ ]
+ result = apply_to_messages(messages, tokenizer)
+ new_content = result.messages[1]["content"][0]["content"]
+ assert "showing through line 42 of 90 total" in new_content
def test_astgrep_skips_small_files(tokenizer):
diff --git a/tests/test_workspace_registry.py b/tests/test_workspace_registry.py
new file mode 100644
index 000000000..8732e24a1
--- /dev/null
+++ b/tests/test_workspace_registry.py
@@ -0,0 +1,128 @@
+"""Tests for headroom.proxy.workspace_registry.resolve_registered_cwd."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+from headroom import paths
+from headroom.proxy.workspace_registry import resolve_registered_cwd
+
+
+def _write_marker(port: int, pid: int, payload: dict) -> None:
+ d = paths.proxy_clients_dir(port)
+ d.mkdir(parents=True, exist_ok=True)
+ (d / f"{pid}.json").write_text(json.dumps(payload), encoding="utf-8")
+
+
+def _spawn_and_reap() -> int:
+ """Return a PID that is guaranteed dead (spawned, then waited on)."""
+ proc = subprocess.Popen([sys.executable, "-c", "pass"])
+ proc.wait()
+ return proc.pid
+
+
+def test_no_token_is_none(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ assert resolve_registered_cwd(8787, None) is None
+ assert resolve_registered_cwd(8787, "") is None
+
+
+def test_no_marker_directory_is_none(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ assert resolve_registered_cwd(8787, "some-token") is None
+
+
+def test_matching_token_live_pid_returns_cwd(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ _write_marker(
+ 8787,
+ os.getpid(), # this test process -- always live
+ {"pid": os.getpid(), "session_token": "tok-A", "cwd": str(project_dir)},
+ )
+ assert resolve_registered_cwd(8787, "tok-A") == str(project_dir)
+
+
+def test_wrong_token_is_none_even_with_a_live_marker_present(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ _write_marker(
+ 8787,
+ os.getpid(),
+ {"pid": os.getpid(), "session_token": "tok-A", "cwd": str(project_dir)},
+ )
+ assert resolve_registered_cwd(8787, "tok-B-guessed") is None
+
+
+def test_stale_marker_dead_pid_is_none_not_the_cwd(tmp_path, monkeypatch):
+ """A crashed/killed session's marker must not be trusted."""
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ dead_pid = _spawn_and_reap()
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ _write_marker(
+ 8787,
+ dead_pid,
+ {"pid": dead_pid, "session_token": "tok-dead", "cwd": str(project_dir)},
+ )
+ assert resolve_registered_cwd(8787, "tok-dead") is None
+
+
+def test_multi_session_isolation_token_resolves_only_its_own_cwd(tmp_path, monkeypatch):
+ """One proxy can serve N concurrent sessions -- token A must never
+ resolve project B's cwd."""
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ project_a = tmp_path / "project-a"
+ project_b = tmp_path / "project-b"
+ project_a.mkdir()
+ project_b.mkdir()
+ # Two distinct *live* PIDs: this test process and a spawned-but-blocked
+ # child (killed at teardown) so both are genuinely alive at lookup time.
+ child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
+ try:
+ _write_marker(
+ 8787,
+ os.getpid(),
+ {"pid": os.getpid(), "session_token": "tok-a", "cwd": str(project_a)},
+ )
+ _write_marker(
+ 8787,
+ child.pid,
+ {"pid": child.pid, "session_token": "tok-b", "cwd": str(project_b)},
+ )
+ assert resolve_registered_cwd(8787, "tok-a") == str(project_a)
+ assert resolve_registered_cwd(8787, "tok-b") == str(project_b)
+ finally:
+ child.kill()
+ child.wait()
+
+
+def test_non_string_cwd_in_marker_is_none(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ _write_marker(8787, os.getpid(), {"pid": os.getpid(), "session_token": "tok-A", "cwd": 12345})
+ assert resolve_registered_cwd(8787, "tok-A") is None
+
+
+def test_malformed_marker_json_is_skipped_not_raised(tmp_path, monkeypatch):
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ d = paths.proxy_clients_dir(8787)
+ d.mkdir(parents=True, exist_ok=True)
+ (d / f"{os.getpid()}.json").write_text("{not valid json", encoding="utf-8")
+ assert resolve_registered_cwd(8787, "tok-A") is None
+
+
+def test_non_object_marker_json_is_skipped_not_raised(tmp_path, monkeypatch):
+ """Syntactically valid JSON that isn't an object (e.g. a bare list) must
+ not crash resolution via AttributeError on .get() -- this function runs
+ on every request through the middleware, so one bad marker must not take
+ down the whole proxy."""
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
+ d = paths.proxy_clients_dir(8787)
+ d.mkdir(parents=True, exist_ok=True)
+ (d / f"{os.getpid()}.json").write_text("[1, 2, 3]", encoding="utf-8")
+ assert resolve_registered_cwd(8787, "tok-A") is None