@@ -12,11 +12,29 @@ captures the issue. The test must fail before any fix is applied.
1212
1313# Trace files
1414
15- Trace files are located in ` /tmp/opencode-diff-traces ` . List the directory first to find the most
16- recent file (sorted by modification time). Check its line count with ` wc -l ` before reading. If it
17- is small (under a few hundred lines), read it in full with ` cat ` . If it is large, use ` grep ` to
18- filter by the ` kind ` values relevant to the issue, or read the tail with ` tail -n N ` to focus on
19- the most recent events.
15+ Use a explore sub-agent to find the most recent trace
16+
17+ Trace files are written under Java's temp directory, not necessarily literal ` /tmp ` . The code uses
18+ ` Path.of(System.getProperty("java.io.tmpdir"), "opencode-diff-traces") ` .
19+
20+ On macOS this often resolves to a sandboxed path such as
21+ ` /var/folders/.../T/opencode-diff-traces ` , even though users may describe it as ` /tmp ` . Do not
22+ assume ` /tmp/opencode-diff-traces ` exists before checking how ` java.io.tmpdir ` was resolved for the
23+ running IDE instance.
24+
25+ If the user ran the plugin from Gradle's ` Run Plugin ` configuration, check the sandbox IDE log
26+ first to find the exact trace file path. In this repo that is typically
27+ ` build/idea-sandbox/IU-*/log/idea.log ` . Search for:
28+
29+ - ` JsonlDiffTracer: tracing enabled file= `
30+ - ` failed to create trace directory `
31+ - ` failed to open trace file `
32+
33+ Use that log line to locate the exact JSONL trace file before reading it. Once you know the
34+ directory, list it to find the most recent file (sorted by modification time). Check its line count
35+ with ` wc -l ` before reading. If it is small (under a few hundred lines), read it in full with
36+ ` cat ` . If it is large, use ` grep ` to filter by the ` kind ` values relevant to the issue, or read the
37+ tail with ` tail -n N ` to focus on the most recent events.
2038
2139Each line is a JSON object. Read events in ` seq ` order. Each event has a ` kind ` , a ` sessionId `
2240inside ` fields ` , and additional fields that vary by kind. Read the fields that are present and
@@ -40,6 +58,7 @@ is already available. Use what fits; build what doesn't exist yet.
4058## Test structure
4159
4260Each test must have:
61+
43621 . A block comment stating the ** invariant** being enforced.
44632 . A ** MANUAL VERIFICATION** section: numbered, concrete steps the user can follow in the running
4564 plugin to confirm the fix. Do not start with "Run the plugin". Example:
@@ -56,12 +75,14 @@ The comment must describe the **user-visible invariant** — what the user expec
5675implementation mechanism that enforces it. Code changes; the user expectation does not.
5776
5877** Wrong** (describes implementation):
78+
5979```
6080// Child session liveHunks are keyed by child session ID; the family query must include active
6181// child sessions regardless of whether parentBySessionId has been populated yet.
6282```
6383
6484** Right** (describes user expectation):
85+
6586```
6687// When the AI delegates work to parallel sub-agents, every file touched by any sub-agent must
6788// show a green highlight in the editor. All files must be visible simultaneously.
0 commit comments