Files
headroom/tests/test_memory_storage_router.py
Mansurshakh JaparovandJD Davis 0f3b0d8a21 fix(memory): resolve pi cwd before injecting project tools (#4618)
## Description

Closes #4442.

pi's system `<cwd>` block now resolves the memory project. If project
scope is still unresolved with the `empty` fallback, the Anthropic
handler no longer advertises unusable memory tools, including tools
recorded earlier in the session.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Parse pi cwd only in system text. Keep main's line parser, header/CLI
precedence and limited user-message fallback.
- Reuse `is_project_unresolved` for context and sticky-tool replay.
Client tools and global/user storage behavior stay intact.
- Add initialized-handler scope regressions, replace
source-inspection/forwarding-only checks, and document project scope in
the published memory page.

## Testing

- [x] Unit tests pass (`pytest`) — related suite and the normal critical
gate, not the entire Python suite locally.
- [x] Linting passes (`ruff check .`) — hosted lint passed on 5ace63e2;
local filesystem limitation below.
- [x] Type checking passes (`mypy headroom`) — normal full hook with its
existing `--ignore-missing-imports` setting.
- [x] New tests added for the scope regression
- [x] Manual testing performed

### Test Output

```text
# 16 related test files
329 passed, 12 skipped, 1 warning in 43.07s

# ordinary pre-push: make ci-precheck
178 passed, 5 skipped, 1 warning in 10.87s
✅ ci-precheck PASSED — safe to push.

uv run ruff format --check .
1860 files already formatted
```

Normal commit hooks (Ruff, formatter, full mypy, commitlint) and the
complete pre-push path passed: Rust fmt/clippy/workspace tests, native
build/import verification, critical Python tests and commitlint. The
existing Starlette test-client warning was not filtered.

Local whole-tree Ruff reports EXE002 on five **unchanged** OAuth plugin
files: my `fuseblk` checkout exposes them as executable despite Git
modes `100644`; `chmod` returns zero without changing the mode. The
uncached check agrees. I did not change those files, add shebangs or
ignore the rule. Hosted Ruff, formatting and full mypy passed on
5ace63e2; the local filesystem limitation remains.

The first full CI caught a missing scope predicate on the existing
lifecycle test double. Fixed in
[5ace63e2](https://github.com/headroomlabs-ai/headroom/commit/5ace63e2cbd2295f9594d1e0442a679aad99979c);
its complete file passes (`5 passed, 1 warning in 13.01s`). This
follow-up changes no production code or assertions and adds no runtime
fallback. The behavior proof below ran on 7aeb83cf with the same
production source; that qualification is historical; current-head checks
are recorded below.

### Author follow-up: 80453a03

Moved the project-scope guidance out of the unpublished wiki and into
`docs/content/docs/memory.mdx`; this commit changes no production code
or tests. Viewed the actual Next.js `/docs/memory#proxy-project-scope`
page and its table-of-contents entry; no browser errors.

The existing router/scope tests pass: 65 passed, with four SQLite
ResourceWarnings. All seven pi-parser lines and all six branch edges are
covered, so I did not add duplicate tests for the old Codecov
percentage.

Normal commit and pre-push hooks passed, including Rust checks, native
build/import, 180 critical Python tests (5 skipped, 1
tokenizer-approximation warning), and commitlint. My first push timed
out with the wrong local ONNX path; the next found missing pip in the
fresh uv environment. Both setup issues were fixed without bypassing
checks. Current-head hosted CI is not yet qualified.

## Real Behavior Proof

- Environment: Linux x86-64, Python 3.13.14, freshly built native core,
real TCP/Uvicorn proxy and SQLite/ONNX memory backend. Only the upstream
is a local Anthropic-shaped HTTP server; no provider charges.
- Exact command / steps: after `uv sync --locked --extra dev --extra
proxy --extra memory` and `make verify-rust-core`, run this from the
checkout. It prints the actual loaded native module/hash and leaves a
disposable `.headroom-4442-*` directory for inspecting SQLite. Both HTTP
listeners shut down before exit.

<details>
<summary>Standalone HTTP/SQLite reproduction</summary>

```bash
./.venv/bin/python - <<'PY'
import hashlib,http.client,json,os,socket,tempfile,threading,time
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from pathlib import Path
import uvicorn
import headroom._core as core
assert Path(core.__file__).resolve().parent == Path.cwd().resolve()/"headroom"
native_sha=hashlib.sha256(Path(core.__file__).read_bytes()).hexdigest()
from headroom.memory.storage_router import ProjectResolver,RequestContext,extract_system_prompt
from headroom.proxy.server import ProxyConfig,create_app
from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
from headroom.proxy.helpers import get_session_tool_tracker
root=Path(tempfile.mkdtemp(prefix=".headroom-4442-",dir=Path.cwd()))
project_a=root/"pi%2Fproject-a";project_b=root/"project-b"
project_a.mkdir(exist_ok=True);project_b.mkdir(exist_ok=True)
os.environ["HEADROOM_WORKSPACE_DIR"]=str(root/"workspace")
os.environ["HEADROOM_BEACON"]="off"
os.environ["HEADROOM_TELEMETRY"]="off"
os.environ["NO_PROXY"]="127.0.0.1,localhost"
forwarded=[]
class Gateway(BaseHTTPRequestHandler):
    def do_POST(self):
        body=json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        forwarded.append({"path":self.path,"body":body})
        payload=json.dumps({"id":"msg_local_scope","type":"message","role":"assistant","model":"claude-haiku-4-5","content":[{"type":"text","text":"ok"}],"stop_reason":"end_turn","stop_sequence":None,"usage":{"input_tokens":10,"output_tokens":1}}).encode()
        self.send_response(200);self.send_header("Content-Type","application/json");self.send_header("Content-Length",str(len(payload)));self.end_headers();self.wfile.write(payload)
    def log_message(self,*args):pass
upstream=ThreadingHTTPServer(("127.0.0.1",0),Gateway)
ut=threading.Thread(target=upstream.serve_forever,daemon=True);ut.start()
config=ProxyConfig(mode="cache",anthropic_api_url=f"http://127.0.0.1:{upstream.server_port}",memory_enabled=True,memory_db_path=str(root/"legacy.db"),traffic_learning_enabled=True,subscription_tracking_enabled=False,cost_tracking_enabled=False,cache_enabled=False,rate_limit_enabled=False,log_requests=False,image_optimize=False,ccr_inject_tool=False,ccr_handle_responses=False,ccr_context_tracking=False,anthropic_pre_upstream_memory_context_timeout_seconds=30.0)
app=create_app(config)
sock=socket.socket();sock.bind(("127.0.0.1",0));sock.listen(128)
port=sock.getsockname()[1]
server=uvicorn.Server(uvicorn.Config(app,log_level="warning",lifespan="on",timeout_graceful_shutdown=3))
st=threading.Thread(target=server.run,kwargs={"sockets":[sock]},daemon=True);st.start()
try:
    deadline=time.monotonic()+180
    while not server.started:
        if not st.is_alive() or time.monotonic()>deadline:raise RuntimeError("real proxy startup failed")
        time.sleep(.02)
    session="headroom4442-native-project-scope"
    common={"Content-Type":"application/json","x-api-key":"local-unbilled-key","anthropic-version":"2023-06-01","x-headroom-user-id":"native-scope-user","x-headroom-session-id":session}
    client_tools=[{"name":"get_weather","description":"Weather","input_schema":{"type":"object","properties":{}}}]
    rows=[]
    cases=[("fresh_unresolved","You are helpful.",{},False),("pi_cwd",f"<cwd>\n{project_a}\n</cwd>",{},True),("warm_unresolved","You are helpful.",{},False),("pi_cwd_restored",f"<cwd>\n{project_a}\n</cwd>",{},True),("explicit_header_wins",f"<cwd>\n{project_b}\n</cwd>",{"x-headroom-project-id":"explicit-project"},True),("ordinary_user_cwd_ignored","You are helpful.",{},False)]
    for label,system,extra,expected in cases:
        body={"model":"claude-haiku-4-5","max_tokens":16,"system":system,"messages":[{"role":"user","content":f"cwd:\n<cwd>\n{project_b}\n</cwd>" if label=="ordinary_user_cwd_ignored" else "hello scope"}],"tools":client_tools}
        before=len(forwarded)
        conn=http.client.HTTPConnection("127.0.0.1",port,timeout=90)
        conn.request("POST","/v1/messages",body=json.dumps(body).encode(),headers={**common,**extra})
        response=conn.getresponse();payload=response.read();conn.close()
        assert response.status==200,(label,response.status,payload.decode())
        assert len(forwarded)==before+1,(label,"unexpected upstream request count")
        actual=forwarded[-1]["body"]
        names={tool.get("name") for tool in actual.get("tools",[])}
        assert names==({"get_weather"}|MEMORY_TOOL_NAMES if expected else {"get_weather"}),(label,names)
        scope=ProjectResolver().resolve(RequestContext(headers={**common,**extra},system_prompt=extract_system_prompt(body),base_user_id="native-scope-user"))
        rows.append({"case":label,"status":response.status,"memoryTools":sorted(names & MEMORY_TOOL_NAMES),"project":scope,"gatewayPath":forwarded[-1]["path"]})
    assert forwarded[1]["body"]["tools"]==forwarded[3]["body"]["tools"],"restored definitions changed"
    tracker=get_session_tool_tracker()
    assert tracker.should_inject("anthropic",session),"probe did not exercise an actual recorded sticky session"
    from urllib.parse import quote
    key_a=ProjectResolver().resolve(RequestContext(headers={"x-headroom-cwd":quote(str(project_a),safe="/")},system_prompt="",base_user_id="native-scope-user"))[0]
    assert rows[1]["project"][0]==key_a
    assert rows[4]["project"][1]=="explicit-project"
    router=app.state.proxy.memory_handler._router
    assert router is not None,"real memory backend never initialized"
    opened=router.open_backends()
    project_db=root/"memories"/"projects"/key_a/"memory.db"
    assert project_db in opened and project_db.is_file(),("real pi project database not opened",[str(x) for x in opened])
    print(json.dumps({"mode":config.mode,"realHttpListener":f"http://127.0.0.1:{port}","localGateway":f"http://127.0.0.1:{upstream.server_port}","rows":rows,"realStickyGoldenSession":True,"realPiProjectDatabase":str(project_db),"openedDatabases":[str(x) for x in opened],"nativeModule":core.__file__,"nativeSha256":native_sha,"noLivePiOrPaidProvider":True},indent=2))
finally:
    server.should_exit=True;st.join(20)
    upstream.shutdown();upstream.server_close();ut.join(5);sock.close()
    assert not st.is_alive() and not ut.is_alive(),"native proof leaked a server"


PY
```

</details>

- Observed result: unchanged `main` fc1ba891 fails at the first
unresolved request: five proxy memory tools reach upstream. With the
fix, all six requests return HTTP 200:

| Same-session request | Proxy memory tools |
| --- | ---: |
| Fresh, no cwd | 0 |
| pi system cwd | 5 |
| Cwd absent again | 0 |
| Same pi cwd restored | 5 |
| Explicit project header, different system cwd | 5 |
| Cwd block only in ordinary user text | 0 |

The client weather tool stays present. Restored definitions are
structurally equal to the first resolved turn; the explicit header wins.
The literal-percent cwd agrees with its encoded-header form, and the
actual project SQLite database opens at the expected key.

- Not tested: live pi/Caveman, paid-provider cache accounting/billing,
Windows, or other provider protocols. This does not claim to fix Caveman
header forwarding.

## Runtime Rollout Safety

- Rollout-managed feature(s): none added; existing Anthropic memory
injection.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: pi cwd resolves; unresolved
project/empty scope no longer adds unusable proxy memory tools.
- Kill switch / disable path: existing `--no-memory`; explicit
project/cwd headers still work.
- Unsafe override required: no.
- Qualification impact: no storage migration or new dependency; scoped
HTTP/SQLite behavior checked.
- Rollback path: revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes — related
suite and critical gate, not a whole-suite claim
- [x] I did **not** edit `CHANGELOG.md` — release-please owns it

## Screenshots (if applicable)

N/A; the observable surface is the HTTP payload and project database.

## Additional Notes

AI-assisted; no subagents. OpenAI injection policy is unchanged. Keeping
this draft until the current hosted checks are qualified.

One earlier post-build probe completed the requests and closed both
listeners but hit its whole-process shutdown deadline. The same program
and native artifact later exited normally with faulthandler enabled; its
diagnostic abort timer did not fire. I have not identified the
intermittent cause and am not claiming a shutdown fix. No production
timeout or feature flag was changed to get that result.


The two npm audits now pass on 5ace63e2, along with the other Security
jobs. The earlier [unchanged-base
failure](https://github.com/headroomlabs-ai/headroom/actions/runs/41399323584)
is historical evidence, not a current blocker. This PR changes no
dependency manifests, lockfiles, workflow or audit exceptions.


### Maintainer current-main requalification

Exact head `60597623e00967153d947a46bf197950250f310e`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Clean mechanical update from current upstream main, preserving the pi
system-cwd resolver, request-scoped project guard, main's cache-mode
search skip/logging, and client-tool preservation. Ordinary user cwd
blocks still do not enable the pi fallback; unresolved project scope
still blocks both context injection and replayed memory tools. No
contributor production logic was rewritten and no new production finding
remains in this reviewed scope.

The initial combined tree dropped main's memory-invariant file and two
stream/timeout regression cases. Maintainer test-only repairs restore
those tests rather than reducing coverage: the invariant file is
byte-identical to main, every main assertion in the four
restored/updated test files is preserved by AST comparison, and three
fixtures now supply the handler protocol methods needed for resolved
scope and beta headers. The lifecycle main control passes without that
fixture extension; no claim is made that this particular fixture failure
independently fails main. All 222 affected
scope/invariant/stream/timeout/lifecycle/backpressure/cache-stability/system-prompt
tests pass with one skip. Ten shared Gemini request-fixture cases also
pass after the separate test-only repair for independently verified main
failures. All 12 main-relative changed Python files pass Ruff/format;
whitespace checks pass.

The author's existing real TCP/SQLite/ONNX reproduction and explicit
limits were read and remain in the body. These fresh Windows checks
qualify the combined request-scope regressions; they are not a claim of
rerunning that Linux proof, live pi/client/provider behavior, or a fresh
native build. An existing binary was supplied solely for test startup.
Draft status is preserved; readiness remains the author's decision and
nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `60e01cf7c25e90abb9f5cb66fa221da83e7c5177`, upstream main
`ea59ac3eef3a3dc02076e9fe4bb30d572ca9c1a9`.

Clean integration with upstream/main
ea59ac3eef. Re-reviewed project-scoping
delta against intervening memory/backend/stream changes: pi cwd remains
limited to system context; ordinary user cwd blocks do not enable
fallback; unresolved projects skip context/tool injection and sticky
tool replay while retaining client tools and main cache-mode no-search
behavior.232
scope/invariant/stream/timeout/lifecycle/backpressure/cache/system-prompt/Gemini
tests pass,1optional skip; touched-source Ruff and whitespace pass. No
contributor production policy rewritten. Earlier author TCP/SQLite/ONNX
evidence remains scoped, with no fresh native build or live-pi/provider
claim. Existing draft preserved; final approval awaits exact-head hosted
qualification. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `e93ceb35df7f78bfa2dcc0611609131cf2b08b0a`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Final post-Dependabot requalification against upstream/main
c01cf07d94. All six Dependabot updates are
now merged. Relative to this branch's freshly tested prepared tree, the
final main sync changes only the three intended Cargo.lock records;
Python/source/test inputs are unchanged. Re-reviewed the integration and
confirmed complete native source/lock/toolchain objects match the tested
combined build and exact fresh native DLL used for this branch's local
tests.

Focused fresh-native qualification: 232 passed, 1 skipped, 1 warning in
47.62s. Selected real dependency overlays and native DLL paths are
recorded in final4618-fresh-native-tests.log; the DLL provenance/input
hashes are in final-native-artifact-proof.json. No redundant rerun is
implied after this Cargo-only merge. Whitespace passes. Prior source
review and scoped real-behavior evidence remain applicable to unchanged
contributor inputs.

No new source finding in the reviewed scope. Final formal approval
awaits exact-head hosted qualification. Project resolution and
unresolved-scope injection/replay gates remain unchanged. Existing draft
status is preserved.

Maintainers handle hosted checks; no external-provider claim,
contributor semantic rewrite or non-Dependabot merge.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `d693dd2b6e33fd47ff853f7e28d938fc1dbc30ac`, upstream main
`2b0315b2d4b0d54947050bbdad2de9e89df06378`.

Current-main requalification
against2b0315b2d4b0d54947050bbdad2de9e89df06378. Clean source
integration preserves pi systemcwd resolution and unresolved-scope
context/tool/sticky-replay gates.70integration patches exactly matchmain
delta;Anthropic exception patch differs only byclosing-parenthesis diff
alignment and its exception AST equalsmain. Broad
memory/router/projectscope/continuation/backpressure/cache/lifecycle/doctor/nativeops
run:405passed,1skipped,one newmain fake-handler fixture failed
missingis_project_unresolved. Maintainer adds only that fake method
returningFalse,respecting resolvedfixture scope;all39backpressure tests
nowpass,including unchanged
injectedSQLiteexception,HTTP200andsemaphorerelease assertions. No
production logic changed.33changedPythonlint/format,offline
lock/whitespacepass;fixedtestlint/formatrechecked.
Existingpr3982nativeDLLverified fullinputhashes/checksum;no
freshbuildclaimed. Currentauthor/Devin discussion checked,inline
endpoint empty;prior scoped realbehavior evidence remains applicable to
unchanged contributor inputs. No new sourcefinding;no
realprovider/agentlaunch claim. Draftpreserved.
Exactnewheadhostedqualification pending;maintainers
handlechecks,nothingmerged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `0da0b5a01958eaaac1d625227cb4bdb9477c5d3b`, upstream main
`0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c`.

Clean integration with upstream/main
0ddaa56c21. All 17 integration patches
exactly match the prior-reviewed-main delta after diff-location
normalization. Contributor pi system-cwd resolution and
unresolved-project memory context/tool/sticky-replay gates are
unchanged. Fresh
memory-router/project-scope/streaming/continuation/backpressure/cache/lifecycle
and incoming Vertex/backend/CLI tests: 381 passed, 12 skipped, 1
warning. Twelve changed Python files pass Ruff lint/format; offline lock
and whitespace pass.

Static production/test scope and security review considered user versus
system cwd inputs, malformed/empty cwd, missing scope and stale tool
replay: tests keep pi cwd tags in ordinary user content from resolving
project scope, and unresolved scope blocks replay. No unrelated
executable, workflow, dependency or setup changes. Flagged inherited
workflow-validation job is excluded by unchanged workflow paths. Author
discussion checked; collected inline endpoint has no findings. Prior
scoped behavior evidence applies to unchanged contributor inputs; no new
real agent/provider launch claimed. Native DLL reused only after
complete tracked input-set/hash and artifact checksum verification, no
fresh build claimed. Draft preserved. Formal approval awaits exact
published-head hosted qualification. Maintainers handle checks; nothing
merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-10 22:28:01 -06:00

763 lines
27 KiB
Python

"""Unit tests for the per-project memory storage router (GH #462)."""
from __future__ import annotations
import os
from pathlib import Path
import pytest
from headroom.memory.backends.local import LocalBackendConfig
from headroom.memory.storage_router import (
BackendRouter,
BackendRouterConfig,
MemoryStorageMode,
ProjectResolver,
RequestContext,
extract_system_prompt,
)
# ---------------------------------------------------------------------------
# Resolver tier-order tests
# ---------------------------------------------------------------------------
def _ctx(
*,
headers: dict[str, str] | None = None,
system_prompt: str = "",
base_user_id: str = "alice",
project_root_override: str | None = None,
) -> RequestContext:
return RequestContext(
headers=headers or {},
system_prompt=system_prompt,
base_user_id=base_user_id,
project_root_override=project_root_override,
)
def test_resolver_tier1_explicit_project_id_wins() -> None:
r = ProjectResolver()
# An explicit project id beats everything else.
out = r.resolve(
_ctx(
headers={"x-headroom-project-id": "billing-svc"},
system_prompt="Primary working directory: /Users/foo/code/other\n",
project_root_override="/also/ignored",
)
)
assert out is not None
key, display = out
# The sanitized id stays as a human-readable prefix; a sha256 digest is
# appended so distinct ids that sanitize alike cannot collide.
assert key.startswith("billing-svc-")
assert len(key.split("-")[-1]) == 16
assert display == "billing-svc"
def test_resolver_tier1_distinct_ids_that_sanitize_alike_dont_collide() -> None:
r = ProjectResolver()
# "acme/api" and "acme api" both sanitize to "acme-api"; without the digest
# they would share one project store (cross-project memory leak).
k1, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme/api"})) # type: ignore[misc]
k2, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme api"})) # type: ignore[misc]
assert k1 != k2
# Same id resolves to a stable key across calls.
k1b, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme/api"})) # type: ignore[misc]
assert k1 == k1b
def test_resolver_tier2_explicit_cwd_header() -> None:
r = ProjectResolver()
out = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/project-b"}))
assert out is not None
key, display = out
assert display == "project-b"
assert key.startswith("project-b-")
assert len(key.split("-")[-1]) == 16 # sha256 prefix length
def test_resolver_project_label_alone_fails_closed() -> None:
r = ProjectResolver()
# X-Headroom-Project is a display/savings label, not a trusted identity.
assert r.resolve(_ctx(headers={"X-Headroom-Project": "wrapped-project"})) is None
def test_resolver_project_label_does_not_collapse_distinct_cwds() -> None:
r = ProjectResolver()
out_a = r.resolve(
_ctx(
headers={
"X-Headroom-Project": "api",
"X-Headroom-Cwd": "/work/acme/api",
}
)
)
out_b = r.resolve(
_ctx(
headers={
"X-Headroom-Project": "api",
"X-Headroom-Cwd": "/work/other/api",
}
)
)
assert out_a is not None and out_b is not None
assert out_a[0] != out_b[0]
assert out_a[1] == out_b[1] == "api"
def test_resolver_tier3_cli_override() -> None:
r = ProjectResolver()
out = r.resolve(_ctx(project_root_override="/Users/foo/code/project-c"))
assert out is not None
_, display = out
assert display == "project-c"
def test_resolver_tier4_env_block_primary_working_directory() -> None:
r = ProjectResolver()
prompt = (
"You have been invoked in the following environment:\n"
" - Primary working directory: /Users/foo/code/headroom\n"
" - Is a git repo: yes\n"
)
out = r.resolve(_ctx(system_prompt=prompt))
assert out is not None
_, display = out
assert display == "headroom"
def test_resolver_tier4_env_block_older_working_directory_format() -> None:
r = ProjectResolver()
prompt = "Working directory: /Users/foo/code/legacy-project\n"
out = r.resolve(_ctx(system_prompt=prompt))
assert out is not None
_, display = out
assert display == "legacy-project"
def test_resolver_tier4_env_block_cwd_format() -> None:
r = ProjectResolver()
prompt = " cwd: /Users/foo/code/cwd-style\n"
out = r.resolve(_ctx(system_prompt=prompt))
assert out is not None
_, display = out
assert display == "cwd-style"
def test_resolver_tier4_env_block_bulleted_cwd_format() -> None:
r = ProjectResolver()
prompt = "- cwd: /Users/foo/code/bulleted-cwd\n"
out = r.resolve(_ctx(system_prompt=prompt))
assert out is not None
_, display = out
assert display == "bulleted-cwd"
def test_extract_cwd_prefers_primary_working_directory_over_earlier_cwd() -> None:
prompt = "cwd: /work/old\nPrimary working directory: /work/current\n"
assert ProjectResolver._extract_cwd_from_system_prompt(prompt) == "/work/current"
def test_extract_cwd_preserves_vertical_tab_inside_path() -> None:
cwd = "/work/a\vpart"
assert ProjectResolver._extract_cwd_from_system_prompt(f"cwd: {cwd}\n") == cwd
def test_extract_cwd_supports_crlf_line_endings() -> None:
prompt = "cwd: /work/current\r\n"
assert ProjectResolver._extract_cwd_from_system_prompt(prompt) == "/work/current"
def test_resolver_ignores_incidental_cwd_prose() -> None:
r = ProjectResolver()
assert (
r.resolve(_ctx(system_prompt="When describing cwd: use the actual environment path."))
is None
)
@pytest.mark.parametrize(
("cwd", "prompt"),
[
("/Users/foo/code/pi", "<cwd>\n/Users/foo/code/pi\n</cwd>"),
("/work/pi", "Before\n<cwd>/work/pi</cwd>\nAfter"),
("/work/acme%2Fapi", "<cwd>\r\n/work/acme%2Fapi\r\n</cwd>"),
("/work/cwd:repo", "<cwd>\n/work/cwd:repo\n</cwd>"),
],
)
def test_resolver_pi_cwd_uses_the_same_project_as_explicit_header(cwd: str, prompt: str) -> None:
from urllib.parse import quote
resolver = ProjectResolver()
expected = resolver.resolve(_ctx(headers={"x-headroom-cwd": quote(cwd, safe="/")}))
assert resolver.resolve(_ctx(system_prompt=prompt)) == expected
def test_pi_system_cwd_wins_over_user_cwd_fallback() -> None:
body = {
"system": "<cwd>\n/trusted/project\n</cwd>",
"messages": [{"role": "user", "content": "cwd: /different/project"}],
}
resolver = ProjectResolver()
expected = resolver.resolve(_ctx(headers={"x-headroom-cwd": "/trusted/project"}))
assert resolver.resolve(_ctx(system_prompt=extract_system_prompt(body))) == expected
@pytest.mark.parametrize(
"content",
[
"<cwd>\n/untrusted/project\n</cwd>",
"cwd:\n<cwd>/untrusted/project</cwd>",
"<cwd>\n/untrusted/cwd:\n</cwd>",
],
)
def test_pi_cwd_in_ordinary_user_content_does_not_resolve_a_project(content: str) -> None:
body = {"system": "You are helpful.", "messages": [{"role": "user", "content": content}]}
assert ProjectResolver().resolve(_ctx(system_prompt=extract_system_prompt(body))) is None
@pytest.mark.parametrize(
"content",
[
"cwd: /legacy/project\n<cwd>/untrusted/project</cwd>",
"<cwd>/untrusted/project</cwd>\ncwd: /legacy/project",
],
)
def test_pi_tags_do_not_override_legacy_user_cwd(content: str) -> None:
body = {"system": "You are helpful.", "messages": [{"role": "user", "content": content}]}
resolver = ProjectResolver()
expected = resolver.resolve(_ctx(headers={"x-headroom-cwd": "/legacy/project"}))
assert resolver.resolve(_ctx(system_prompt=extract_system_prompt(body))) == expected
@pytest.mark.parametrize("prompt", ["<cwd>/work/pi", "<cwd>\n \n</cwd>"])
def test_incomplete_or_empty_pi_cwd_does_not_resolve_a_project(prompt: str) -> None:
assert ProjectResolver().resolve(_ctx(system_prompt=prompt)) is None
def test_resolver_returns_none_when_nothing_resolves() -> None:
r = ProjectResolver()
out = r.resolve(_ctx(system_prompt="A generic system prompt with no env block."))
assert out is None
def test_resolver_unencodable_system_prompt_cwd_does_not_raise() -> None:
# Issue #4162: a JSON-decoded ``\ud800`` escape leaves an unpaired
# surrogate in the cwd. It has no UTF-8 form, so it is not a usable
# identity: resolve to "no project" instead of raising.
r = ProjectResolver()
prompt = "Primary working directory: /work/" + chr(0xD800)
assert r.resolve(_ctx(system_prompt=prompt)) is None
def test_resolver_unencodable_cli_override_falls_through_to_system_prompt() -> None:
# An unusable cwd in one tier must not block a usable one in a later tier.
r = ProjectResolver()
out = r.resolve(
_ctx(
project_root_override="/work/" + chr(0xDC80),
system_prompt="Primary working directory: /Users/foo/code/headroom\n",
)
)
assert out is not None
_, display = out
assert display == "headroom"
@pytest.mark.skipif(os.name != "posix", reason="POSIX undecodable byte filenames and symlinks only")
def test_resolver_symlink_to_undecodable_name_does_not_raise(tmp_path: Path) -> None:
# The cwd itself is plain UTF-8, but realpath follows the symlink to a
# non-UTF-8 filename and returns it as a ``\udcXX`` surrogate escape.
# Creating that fixture is a filesystem capability, not product behavior:
# skip if it is unavailable (e.g. macOS APFS rejects non-UTF-8 names).
# test_resolver_realpath_returning_surrogate_does_not_raise covers the
# same path on every platform.
base = os.fsencode(tmp_path)
try:
os.mkdir(base + b"/\xff-target")
os.symlink(base + b"/\xff-target", base + b"/link")
except (OSError, UnicodeError) as exc:
pytest.skip(f"cannot create a non-UTF-8 symlink fixture here: {exc}")
prompt = f"Primary working directory: {tmp_path}/link\n"
assert ProjectResolver().resolve(_ctx(system_prompt=prompt)) is None
def test_resolver_realpath_returning_surrogate_does_not_raise(
monkeypatch: pytest.MonkeyPatch,
) -> None:
# Same case as above on any OS: realpath yields what Linux returns for a
# symlink to a non-UTF-8 filename.
monkeypatch.setattr(os.path, "realpath", lambda _p: "/work/\udcff-target")
prompt = "Primary working directory: /work/link\n"
assert ProjectResolver().resolve(_ctx(system_prompt=prompt)) is None
def test_resolver_valid_non_ascii_cwd_still_resolves() -> None:
r = ProjectResolver()
out = r.resolve(_ctx(system_prompt="Primary working directory: /Users/foo/code/café\n"))
assert out is not None
key, display = out
assert display == "café"
assert key.startswith("caf")
def test_router_project_mode_unencodable_cwd_fails_closed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
router = _make_router(tmp_path, MemoryStorageMode.PROJECT, monkeypatch)
_, scope = router.backend_for(
_ctx(system_prompt="Primary working directory: /work/" + chr(0xD800))
)
assert scope.mode is MemoryStorageMode.PROJECT
assert scope.project_key is None
def test_resolver_same_cwd_yields_stable_key_across_calls() -> None:
r = ProjectResolver()
k1, _ = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/x"})) # type: ignore[misc]
k2, _ = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/x"})) # type: ignore[misc]
assert k1 == k2
def test_resolver_distinct_cwds_yield_distinct_keys() -> None:
r = ProjectResolver()
k1, _ = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/a"})) # type: ignore[misc]
k2, _ = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/b"})) # type: ignore[misc]
assert k1 != k2
def test_resolver_sanitises_unsafe_basename_chars() -> None:
r = ProjectResolver()
out = r.resolve(_ctx(headers={"x-headroom-project-id": "../etc/passwd; rm -rf /"}))
assert out is not None
key, _ = out
# Path-separators and shell-metas must be neutralised.
assert "/" not in key
assert ";" not in key
assert " " not in key
def test_extract_system_prompt_anthropic_string() -> None:
assert extract_system_prompt({"system": "hello"}) == "hello"
def test_extract_system_prompt_anthropic_blocks() -> None:
body = {"system": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}]}
assert extract_system_prompt(body) == "a\nb"
def test_extract_system_prompt_openai_messages() -> None:
body = {
"messages": [
{"role": "system", "content": "you are helpful"},
{"role": "user", "content": "hi"},
]
}
assert extract_system_prompt(body) == "you are helpful"
def test_extract_system_prompt_missing_returns_empty() -> None:
assert extract_system_prompt({"messages": []}) == ""
def test_extract_system_prompt_user_reminder_with_cwd_reaches_resolver() -> None:
body = {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": (
"<system-reminder>\n\n"
"The maximum number of terminals is 5.\n\n"
"<available_terminal>\n"
"- terminal_id: 9\n"
"- cwd: S:\\workspace-zhuangxiu\\decorate-offer-api\n"
"</available_terminal>\n\n"
"</system-reminder>"
),
}
],
}
]
}
prompt = extract_system_prompt(body)
assert "cwd:" in prompt
resolved = ProjectResolver().resolve(_ctx(system_prompt=prompt))
assert resolved is not None
_, display = resolved
assert "decorate-offer-api" in display
def test_extract_system_prompt_ordinary_user_text_returns_empty() -> None:
body = {"messages": [{"role": "user", "content": "Hello, can you help me refactor this?"}]}
assert extract_system_prompt(body) == ""
def test_extract_system_prompt_system_message_beats_user_cwd_fallback() -> None:
body = {
"messages": [
{"role": "system", "content": "Working directory: /system/project"},
{"role": "user", "content": "cwd: /user/project\nDo the thing."},
]
}
prompt = extract_system_prompt(body)
resolved = ProjectResolver().resolve(_ctx(system_prompt=prompt))
assert prompt == "Working directory: /system/project"
assert resolved is not None
_, display = resolved
assert display == "project"
def test_extract_system_prompt_ignores_incidental_cwd_prose_for_fallback() -> None:
body = {
"system": "When describing cwd: use the actual environment path.",
"messages": [
{
"role": "user",
"content": "<env>\nPrimary working directory: /work/project-alpha\n</env>",
}
],
}
prompt = extract_system_prompt(body)
resolved = ProjectResolver().resolve(_ctx(system_prompt=prompt))
assert "Primary working directory: /work/project-alpha" in prompt
assert resolved is not None
_, display = resolved
assert display == "project-alpha"
def test_extract_system_prompt_cwd_in_non_user_message_returns_empty() -> None:
body = {"messages": [{"role": "assistant", "content": "cwd: /spoof/project"}]}
assert extract_system_prompt(body) == ""
# ---------------------------------------------------------------------------
# BackendRouter path-layout tests (no real backend I/O — we stub the class).
# ---------------------------------------------------------------------------
class _FakeBackend:
def __init__(self, cfg: LocalBackendConfig) -> None:
self.cfg = cfg
async def _ensure_initialized(self) -> None:
return
def _make_router(
tmp_path: Path,
mode: MemoryStorageMode,
monkeypatch: pytest.MonkeyPatch,
) -> BackendRouter:
# Patch out the real LocalBackend constructor so the router test
# doesn't try to load embedders or open SQLite files.
monkeypatch.setattr(
"headroom.memory.storage_router.LocalBackend",
_FakeBackend,
)
cfg = BackendRouterConfig(
mode=mode,
root_dir=tmp_path / "memories",
global_db_path=tmp_path / "memory.db",
max_open_backends=4,
backend_config_template=LocalBackendConfig(db_path=str(tmp_path / "memory.db")),
)
return BackendRouter(cfg)
def test_router_project_mode_two_cwds_two_paths(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
router = _make_router(tmp_path, MemoryStorageMode.PROJECT, monkeypatch)
ctx_a = _ctx(headers={"x-headroom-cwd": "/code/a"})
ctx_b = _ctx(headers={"x-headroom-cwd": "/code/b"})
_, scope_a = router.backend_for(ctx_a)
_, scope_b = router.backend_for(ctx_b)
assert scope_a.mode is MemoryStorageMode.PROJECT
assert scope_b.mode is MemoryStorageMode.PROJECT
assert scope_a.db_path != scope_b.db_path
assert scope_a.display_name == "a"
assert scope_b.display_name == "b"
def test_router_project_mode_unresolved_fails_closed_by_default(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Default `unresolved_project_fallback='empty'` → fail-closed signal, NOT GLOBAL pool.
Updated 2026-05-26 from the prior GLOBAL-fallback assertion. The
silent GLOBAL pooling was the root cause of the TAM-550
"implémente X" cross-thread instruction misread (a memory from a
prior unrelated session ended up in the live user turn and got
treated as a new command). The new default is fail-closed: the
router still returns a ResolvedScope (so callers don't need to
handle None), but signals "no project" via
``mode=PROJECT & project_key=None``. The memory handler reads
that sentinel and skips injection entirely.
"""
router = _make_router(tmp_path, MemoryStorageMode.PROJECT, monkeypatch)
backend, scope = router.backend_for(_ctx(system_prompt="no env block"))
# Fail-closed signal: PROJECT mode preserved, project_key is None.
assert scope.mode is MemoryStorageMode.PROJECT
assert scope.project_key is None
assert scope.db_path is None
assert scope.display_name == "unresolved (no memory)"
assert backend is None
assert router.open_backends() == []
def test_router_project_mode_unresolved_global_fallback_when_opted_in(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Legacy GLOBAL pooling is reachable via opt-in config."""
monkeypatch.setattr(
"headroom.memory.storage_router.LocalBackend",
_FakeBackend,
)
cfg = BackendRouterConfig(
mode=MemoryStorageMode.PROJECT,
root_dir=tmp_path / "memories",
global_db_path=tmp_path / "memory.db",
max_open_backends=4,
backend_config_template=LocalBackendConfig(db_path=str(tmp_path / "memory.db")),
unresolved_project_fallback="global",
)
router = BackendRouter(cfg)
_, scope = router.backend_for(_ctx(system_prompt="no env block"))
assert scope.mode is MemoryStorageMode.GLOBAL
assert scope.db_path == tmp_path / "memory.db"
assert scope.display_name == "global (unresolved)"
def test_router_invalid_unresolved_fallback_raises(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Unknown values of `unresolved_project_fallback` fail loud, not silently."""
monkeypatch.setattr(
"headroom.memory.storage_router.LocalBackend",
_FakeBackend,
)
cfg = BackendRouterConfig(
mode=MemoryStorageMode.PROJECT,
root_dir=tmp_path / "memories",
global_db_path=tmp_path / "memory.db",
max_open_backends=4,
backend_config_template=LocalBackendConfig(db_path=str(tmp_path / "memory.db")),
unresolved_project_fallback="nonsense_value",
)
router = BackendRouter(cfg)
with pytest.raises(ValueError, match="not a recognised value"):
router.backend_for(_ctx(system_prompt="no env block"))
def test_router_user_mode_partitions_by_user(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
router = _make_router(tmp_path, MemoryStorageMode.USER, monkeypatch)
_, scope_a = router.backend_for(_ctx(base_user_id="alice"))
_, scope_b = router.backend_for(_ctx(base_user_id="bob"))
assert scope_a.mode is MemoryStorageMode.USER
assert scope_b.mode is MemoryStorageMode.USER
assert scope_a.db_path != scope_b.db_path
assert scope_a.display_name == "alice"
assert scope_b.display_name == "bob"
def test_router_user_mode_distinct_ids_that_sanitize_alike_dont_collide(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# "alice/qa" and "alice qa" both sanitize to "alice-qa"; without the digest
# they would share one users/alice-qa/memory.db — a cross-user leak, the one
# thing USER mode exists to prevent.
router = _make_router(tmp_path, MemoryStorageMode.USER, monkeypatch)
_, scope_a = router.backend_for(_ctx(base_user_id="alice/qa"))
_, scope_b = router.backend_for(_ctx(base_user_id="alice qa"))
assert scope_a.db_path != scope_b.db_path
def test_router_global_mode_reuses_legacy_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
router = _make_router(tmp_path, MemoryStorageMode.GLOBAL, monkeypatch)
_, scope = router.backend_for(_ctx(headers={"x-headroom-cwd": "/code/anything"}))
assert scope.mode is MemoryStorageMode.GLOBAL
# GLOBAL mode hits the legacy DB regardless of cwd signals.
assert scope.db_path == tmp_path / "memory.db"
def test_router_backend_cache_returns_same_instance(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
router = _make_router(tmp_path, MemoryStorageMode.PROJECT, monkeypatch)
ctx = _ctx(headers={"x-headroom-cwd": "/code/sticky"})
b1, _ = router.backend_for(ctx)
b2, _ = router.backend_for(ctx)
assert b1 is b2
def test_router_lru_eviction_drops_oldest(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
# max_open_backends=4 in _make_router. Opening 5 different projects
# should evict the first.
router = _make_router(tmp_path, MemoryStorageMode.PROJECT, monkeypatch)
for i in range(5):
router.backend_for(_ctx(headers={"x-headroom-cwd": f"/code/p{i}"}))
assert len(router.open_backends()) == 4
# ---------------------------------------------------------------------------
# Percent-decoding is a header-boundary concern only (#3597 review round 2)
# ---------------------------------------------------------------------------
def test_resolver_literal_percent_path_distinct_via_cli_override() -> None:
"""A literal ``%2F`` directory must not collapse onto the decoded path.
Only ``x-headroom-cwd`` is percent-encoded by the wrapper. The CLI
override carries a literal filesystem path, so decoding it would make
``/work/acme%2Fapi`` and ``/work/acme/api`` share one memory store.
"""
r = ProjectResolver()
literal = r.resolve(_ctx(project_root_override="/work/acme%2Fapi"))
decoded = r.resolve(_ctx(project_root_override="/work/acme/api"))
assert literal is not None and decoded is not None
assert literal[0] != decoded[0]
def test_resolver_literal_percent_path_distinct_via_system_prompt() -> None:
"""Same guarantee for the ``cwd:`` system-prompt tier."""
r = ProjectResolver()
literal = r.resolve(_ctx(system_prompt="Primary working directory: /work/acme%2Fapi"))
decoded = r.resolve(_ctx(system_prompt="Primary working directory: /work/acme/api"))
assert literal is not None and decoded is not None
assert literal[0] != decoded[0]
def test_resolver_literal_percent_space_path_distinct_from_space() -> None:
"""``%20`` in a real directory name stays distinct from a real space."""
r = ProjectResolver()
literal = r.resolve(_ctx(project_root_override="/work/my%20proj"))
spaced = r.resolve(_ctx(project_root_override="/work/my proj"))
assert literal is not None and spaced is not None
assert literal[0] != spaced[0]
def test_resolver_encoded_cwd_header_matches_literal_cwd_identity() -> None:
"""The wrapper's encoded header still resolves to the literal cwd identity.
This is the behaviour the encoding exists for, and it must survive the
boundary-only decode: ``quote(path)`` in the header and ``path`` from the
CLI override have to land on the same project key.
"""
from urllib.parse import quote
path = "/work/acme/día-api"
r = ProjectResolver()
via_header = r.resolve(_ctx(headers={"x-headroom-cwd": quote(path, safe="/:._-~()")}))
via_override = r.resolve(_ctx(project_root_override=path))
assert via_header is not None and via_override is not None
assert via_header[0] == via_override[0]
assert via_header[1] == via_override[1] == "día-api"
# Claude Code 2.x sends the env block as an isMeta user message (#3595)
# ---------------------------------------------------------------------------
def test_extract_system_prompt_finds_cwd_in_user_msg_despite_system_string() -> None:
"""A non-empty ``system`` must not hide the ``cwd:`` in a user message.
Claude Code 2.x always sends a system prompt *and* puts its ``<env>``
block in an ``isMeta`` user message. The old first-match-wins early
return made that block unreachable, so resolution fell through to the
fail-closed fallback for every 2.x request.
"""
body = {
"system": "You are Claude Code.",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "<env>\nPrimary working directory: /work/myproj\n</env>",
}
],
},
],
}
prompt = extract_system_prompt(body)
resolved = ProjectResolver().resolve(_ctx(system_prompt=prompt))
assert "You are Claude Code." in prompt
assert resolved is not None
assert resolved[1] == "myproj"
def test_extract_system_prompt_finds_cwd_in_user_msg_despite_system_blocks() -> None:
"""Same when ``system`` is a block list rather than a string."""
body = {
"system": [{"type": "text", "text": "You are Claude Code."}],
"messages": [
{"role": "user", "content": "Primary working directory: /work/other\nhi"},
],
}
resolved = ProjectResolver().resolve(_ctx(system_prompt=extract_system_prompt(body)))
assert resolved is not None
assert resolved[1] == "other"
def test_extract_system_prompt_user_cwd_cannot_override_system_field_cwd() -> None:
"""A user turn must not redirect resolution away from the system cwd.
User content is client-controlled, so it stays a fallback only. This is
the top-level-``system`` counterpart of the ``role="system"`` precedence
already covered above.
"""
body = {
"system": "Primary working directory: /system/project",
"messages": [
{"role": "user", "content": "Primary working directory: /spoofed/evil"},
],
}
prompt = extract_system_prompt(body)
resolved = ProjectResolver().resolve(_ctx(system_prompt=prompt))
assert "spoofed" not in prompt
assert resolved is not None
assert resolved[1] == "project"