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’s env_overrides. VS Code additionally pins a single install with VSCODE_APPDATA (it has four editions); Cursor IDE has one edition, so it declares no such pin.

  • Remote-URI mapping handles file:// and vscode-remote://… and returns None for non-path URIs (for example untitled:), never raising.

  • Because the cross-host root escapes $HOME, the test harness neutralizes it by default so hermetic find tests 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 in path: 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 the stat calls 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 workspaceStorage over a mounted filesystem is slower than a local scan; the WSL-detection and existence gates keep the cost off non-WSL hosts, and VSCODE_APPDATA narrows a multi-user mount to one install.

  • A monkeypatched $HOME no longer fully sandboxes discovery for this backend. The AGENTGREP_WSL_USERS_ROOT seam 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.