Challenge #
Trawler currently falls back to a cwd-relative trawler-graph on macOS and Linux when TRAWLER_GRAPH_DIR is unset. That can create user data inside a checkout and can silently select a different graph when the launch directory changes.
Proposed specifications #
- Adds
graph-location: defines explicit-override precedence, platform-native defaults, compatibility-first legacy handling, fail-closed candidate inspection, startup diagnostics, documentation, and deterministic verification. - No existing specification is modified. The Nix preview contract continues to use its own explicit helper-owned scratch graph.
Project-wide outcome #
The default graph now lives under roaming AppData on Windows, Application Support on macOS, and XDG data storage on Linux. New launches never create a default graph in cwd. A recognized legacy-only graph remains accessible with a warning; distinct native and legacy graphs fail rather than guessing. No graph is copied or moved automatically.
The resolver is lazy and fail-closed: absolute overrides bypass cwd/native probing, unsafe Windows-relative forms and empty overrides are rejected, occupied or unreadable candidates are preserved, interrupted first creation can retry only from narrowly recognized debris, and alias paths to one graph are not mistaken for two. The selected absolute path and source are reported before storage opens.
Verification #
- Strict OpenSpec validation passes; the completed change is archived and
graph-locationis synced into the main specs. - Formatting, full-workspace check, and clippy with warnings denied pass in the pinned Nix development shell.
- All 195 non-ignored workspace tests pass when the existing order-sensitive 2-second Steel wall-clock gate is run separately; the remaining workspace suite passes together. A combined run on this host can time that pre-existing gate out after the long GPUI suite, while the exact gate passes in isolation.
- The isolated real-GPUI preview smoke passes with semantic dumps and a valid 900×600 PNG. Its application log identifies the helper-owned fixture path as an explicit override, and the native graph path remains absent.
- Two adversarial review rounds were resolved; the final audit found no remaining blocking or high-confidence issues.
Links #
- Fixes issue #5
- Source feedback: Ariel M. (
@byarielm.fyi) on UserInput
Agent disclosure #
I am Hollis, an agent working with Graham. I shaped and implemented this change using openai-codex/gpt-5.6-sol with high reasoning in Letta Code. Graham participated in the behavior/spec decisions and approved the OpenSpec contract before implementation; I handled implementation structure, commits, testing, and review independently.