ADR 0009: Cross-host discovery and remote-workspace path mapping¶
Status¶
Accepted.
Context¶
Every agentgrep backend before VS Code resolves its stores from a single
filesystem rooted at the user’s home directory. Discovery functions take a
home path and either expand ~-anchored platform_paths or append
home_subpath segments to it. Tests rely on this: they point $HOME (or the
passed home) at a temporary directory and trust that no discovery escapes it.
VS Code’s GitHub Copilot Chat breaks that single-root assumption in two ways.
First, the chat client stores transcripts wherever the VS Code UI process
runs, which is not always where the project lives. On WSL, the common setup
is a Windows-host VS Code editing a Linux project over a
vscode-remote://wsl+<distro>/… remote. The UI is a Windows process, so it
writes chat under the Windows profile —
C:\Users\<user>\AppData\Roaming\Code\User — which a WSL distro sees at
/mnt/c/Users/<user>/AppData/Roaming/Code/User. The Linux home directory holds
no chat at all. A home-rooted discovery function finds nothing.
Second, once a transcript is found, its on-disk location is an opaque
workspaceStorage/<md5>/ hash. The human-meaningful project directory is
recorded separately, in the sibling workspace.json, as a URI — and for the
WSL case that URI is a vscode-remote:// remote, not a local path. Without
mapping it, results cannot report which project a chat belonged to, and
path: predicates cannot match the project the user thinks in.
No existing backend needed either capability: rg 'wsl|/mnt/c|vscode-remote'
over src/agentgrep was empty before this work, and sys.platform reports
linux inside WSL, so nothing distinguished it from native Linux.
Decision¶
agentgrep discovers agent stores across the host boundary, and maps remote workspace URIs back to local paths. On WSL, the Windows-side VS Code and Cursor IDE chat, each Windows profile’s Claude Code, Codex, and Cursor homes, and the Claude desktop app directory join discovery; every other root stays home-based.
Discovery roots are computed, not just declared¶
discover_vscode_sources resolves a tuple of candidate User/ directories
across editions (Code, Code - Insiders, VSCodium, Code - OSS) and
operating systems, then injects them into the catalogue’s declarative
DiscoverySpec rows through named discovery roots (vscode_workspace,
vscode_global). This keeps the catalogue’s globs and adapters declarative
while letting discovery contribute roots the catalogue cannot name statically.
The WSL bridge is auto-detected and bounded¶
When discovery detects WSL — /proc/version contains microsoft — it also
probes the Windows users mount (/mnt/c/Users/*/AppData/Roaming/<edition>/User)
for chat written host-side. The probe is gated on WSL detection and directory
existence, so native Linux and macOS pay nothing. Native Windows host runs are
out of scope; WSL is the supported cross-host case.
The cross-host root is an explicit, overridable seam¶
The Windows users mount is read from AGENTGREP_WSL_USERS_ROOT (default
/mnt/c/Users) so non-default drive letters and unusual mounts are reachable,
and VSCODE_APPDATA pins a single Roaming directory when one install should
be targeted. Because this root is independent of $HOME, it is the one
discovery input a temporary $HOME does not neutralize, so the test suite
points it at a nonexistent path by default and overrides it only where the
bridge is under test.
Remote workspace URIs map to local paths¶
A transcript’s project directory is resolved from its sibling workspace.json
folder URI: file:// URIs are unquoted, and
vscode-remote://wsl+<distro>/<path> (and other remotes, best-effort) reduce
to their path component. The result is attached as the record’s cwd metadata
so a WSL-remote chat reports /home/you/work/proj rather than a storage hash.
Windows-side homes join discovery¶
Claude desktop runs Claude Code on Windows for sessions outside a WSL distro,
and Codex desktop and Cursor keep their homes in the Windows profile. On WSL,
each profile’s .claude, .codex, and Cursor home is added as an extra root
beside the Linux one, and %APPDATA%/Claude is probed for Cowork sessions and
the Code-tab session index. agentgrep.wsl owns the host model:
WSLHostPath, a pathlib.PosixPath whose str(), os.fspath(),
equality, and hash stay the real path, plus the profile and app-data role
objects. It imports no other agentgrep module, so every layer can use it
(ADR 0010), and a test keeps it that way.
Chromium web storage is read without the app’s lock¶
ChatGPT desktop on Windows keeps no message text on disk, but its Chromium
Local Storage caches the conversation list, which agentgrep searches by title
(chatgpt.conversation_list). The store is a LevelDB directory the running app
holds open, so agentgrep reads its log and table files directly in pure Python
(Snappy blocks included) instead of opening it with a LevelDB library, which
would take the app’s lock. Only the conversation-list keys are decoded; the
store’s session data and secrets are never read. The app’s HTTP cache, in
Chromium’s blockfile format, is read the same way (chatgpt.http_cache): its
index, entry blocks, and external files are parsed directly, only the
conversation-list and scheduled-task responses are read past their URL, and
their Brotli bodies are decoded with the brotli package, imported only when
such a body is read.
Windows paths never name the account¶
A path inside a Windows profile displays as %USERPROFILE%/…, %APPDATA%/…,
or %LOCALAPPDATA%/…, and an account name inside an encoded project folder as
%USERNAME%. path: queries and MCP refs map a display form back to every
profile, and refs and fingerprints carry an opaque per-profile key, so two
profiles’ copies of one file stay distinct.
Walks over the 9p mount are pruned, overlapped, and cancellable¶
Each stat over the Windows mount is a round trip, measured at about 1.7 ms.
Discovery skips Windows copies of local transcripts before stat’ing them,
resolves the desktop roots only when an admitted row reads them, overlaps
stat calls on one shared 16-thread pool, and stops once the search engine
abandons the pass (discovery_stop()): no new stat
starts, and a running listing ends. The engine then reports the pass abandoned
instead of returning it partial; a library caller using discovery_stop
directly reads the yielded state’s stopped flag.
Scope¶
This ADR governs cross-host store discovery and remote-workspace path mapping. It applies to the VS Code and Cursor IDE backends (both VS Code-style, persisting WSL-remote chat client-side on the Windows host), to the Windows-side Claude Code, Codex, and Cursor CLI homes and the Claude desktop app directory on WSL, and to any future backend whose UI and project live on different filesystems. It does not change the execution engine (ADR 0004), introduce native code (ADR 0003), or alter the catalogue schema — the catalogue stays declarative; only the discovery function computes roots.
Requirements¶
Cross-host discovery activates only on detected WSL and only for existing directories; other platforms incur no extra filesystem probes.
The cross-host root is overridable via
AGENTGREP_WSL_USERS_ROOT, declared in every bridged catalogue row’senv_overrides. VS Code additionally pins a single install withVSCODE_APPDATA(it has four editions); Cursor IDE has one edition, so it declares no such pin.Remote-URI mapping handles
file://andvscode-remote://…and returnsNonefor non-path URIs (for exampleuntitled:), never raising.Because the cross-host root escapes
$HOME, the test harness neutralizes it by default so hermeticfindtests never read the developer’s real chat history; a dedicated test exercises the bridge against a synthetic mount.No output names a Windows account: Windows-side paths display through
agentgrep.wsl, and a displayed path still resolves inpath:queries and MCP refs.A Windows-side copy of a local transcript is read once.
Discovery over the Windows mount honours
discovery_stop, so an abandoned search makes no further round trips beyond thestatcalls in flight.An app-owned store such as Chromium Local Storage is read without a lock and without writes, decoding only the keys an adapter needs.
Consequences¶
Positive¶
VS Code Copilot Chat written by a Windows host is searchable from inside WSL, with results that name the real Linux project directory.
The catalogue stays declarative; only one discovery function holds the cross-host knowledge, so other backends are unaffected.
The override seam doubles as test isolation and as a real knob for non-default mounts.
Tradeoffs and risks¶
Globbing
workspaceStorageover a mounted filesystem is slower than a local scan; the WSL-detection and existence gates keep the cost off non-WSL hosts, andVSCODE_APPDATAnarrows a multi-user mount to one install.A monkeypatched
$HOMEno longer fully sandboxes discovery for this backend. TheAGENTGREP_WSL_USERS_ROOTseam restores isolation, but it is a second thing a test must control; the autouse default makes that the norm rather than per-test boilerplate.
Relationship to other ADRs¶
ADR 0001 owns version detection and the privacy rule that auth material is
documented but never enumerated; the VS Code inline-history adapter reads only
the inline-chat-history key and leaves the secret://… keys in the same
database untouched. ADR 0003 owns the native boundary, which this ADR does not
touch — discovery stays pure Python. ADR 0004 owns planning and execution,
which are unchanged: cross-host roots are resolved during discovery and flow
through the existing source/handle pipeline, and the engine’s cancellation
reaches discovery through discovery_stop. ADR 0010 owns module layering;
agentgrep.wsl sits at its leaves.
Final position¶
agentgrep keeps home-rooted single-filesystem discovery as the default and adds a bounded, auto-detected, overridable bridge for the cases that need it — WSL editing where the chat lives on the Windows host, and agents whose homes live in the Windows profile — together with the remote-URI mapping that makes those results name a real project directory and a display form that never names the Windows account.