@hybridlabor-api/bdb-synapse 1.0.0

package/internal/server/analyze_test.go

@@ -0,0 +1,297 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/judge"
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+type stubJudge struct {
+	output string
+	err    error
+}
+
+func (s stubJudge) Run(ctx context.Context, prompt, input string) (judge.RunResult, error) {
+	return judge.RunResult{Text: s.output, Model: "stub-model"}, s.err
+}
+
+func (s stubJudge) Name() string { return "stub" }
+
+const stubJudgeOutput = `{"task_summary":"demo","dimensions":[
+{"name":"exploration","findings":[{"claim":"读了再改","severity":"info","evidence_seqs":[0]}]},
+{"name":"scope","findings":[]},
+{"name":"wandering","findings":[]},
+{"name":"verification","findings":[{"claim":"改后未验证","severity":"warning","evidence_seqs":[0]}]}],
+"notable_moments":[],"narrative":"ok"}`
+
+func TestAnalyzeEndpointRunsJudgeAndServesReport(t *testing.T) {
+	claudeDir := t.TempDir()
+	writeServerSession(t, filepath.Join(claudeDir, "eval.jsonl"),
+		`{"type":"user","timestamp":"2026-07-09T00:00:00Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":"do the thing"}}`,
+		`{"type":"assistant","timestamp":"2026-07-09T00:00:01Z","sessionId":"eval","cwd":"/tmp","message":{"role":"assistant","content":[{"type":"tool_use","id":"r1","name":"Read","input":{"file_path":"/tmp/a.go"}}]}}`,
+		`{"type":"user","timestamp":"2026-07-09T00:00:02Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"r1","content":"ok","is_error":false}]}}`,
+	)
+	s := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	s.analyze.runner = stubJudge{output: stubJudgeOutput}
+	s.reportCache.Dir = t.TempDir()
+
+	// before any run: state none, judge reported available via the stub
+	getResp := httptest.NewRecorder()
+	s.handleSessionResource(getResp, httptest.NewRequest(http.MethodGet, "/api/sessions/eval/report", nil))
+	if getResp.Code != http.StatusOK {
+		t.Fatalf("report status = %d body=%s", getResp.Code, getResp.Body.String())
+	}
+	var status reportStatus
+	if err := json.Unmarshal(getResp.Body.Bytes(), &status); err != nil {
+		t.Fatal(err)
+	}
+	if status.State != "none" || !status.JudgeAvailable || status.JudgeCLI != "stub" {
+		t.Fatalf("status = %+v", status)
+	}
+
+	postResp := httptest.NewRecorder()
+	s.handleSessionResource(postResp, httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", nil))
+	if postResp.Code != http.StatusAccepted {
+		t.Fatalf("analyze status = %d body=%s", postResp.Code, postResp.Body.String())
+	}
+
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		resp := httptest.NewRecorder()
+		s.handleSessionResource(resp, httptest.NewRequest(http.MethodGet, "/api/sessions/eval/report", nil))
+		if err := json.Unmarshal(resp.Body.Bytes(), &status); err != nil {
+			t.Fatal(err)
+		}
+		if status.State == "done" || status.State == "failed" {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job never finished: %+v", status)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if status.State != "done" || status.Stale || status.Report == nil {
+		t.Fatalf("status = %+v", status)
+	}
+	verdicts := map[string]string{}
+	for _, dim := range status.Report.Dimensions {
+		verdicts[dim.Name] = dim.Verdict
+	}
+	if verdicts["verification"] != model.VerdictWarning || verdicts["exploration"] != model.VerdictGood {
+		t.Fatalf("verdicts = %#v", verdicts)
+	}
+
+	// the report must survive a server restart via the disk cache
+	restarted := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	restarted.analyze.runner = stubJudge{output: stubJudgeOutput}
+	restarted.reportCache.Dir = s.reportCache.Dir
+	resp := httptest.NewRecorder()
+	restarted.handleSessionResource(resp, httptest.NewRequest(http.MethodGet, "/api/sessions/eval/report", nil))
+	if err := json.Unmarshal(resp.Body.Bytes(), &status); err != nil {
+		t.Fatal(err)
+	}
+	if status.State != "done" || status.Report == nil {
+		t.Fatalf("restarted status = %+v", status)
+	}
+}
+
+func TestAnalyzeEndpointReportsJudgeFailure(t *testing.T) {
+	claudeDir := t.TempDir()
+	writeServerSession(t, filepath.Join(claudeDir, "fail.jsonl"),
+		`{"type":"user","timestamp":"2026-07-09T00:00:00Z","sessionId":"fail","cwd":"/tmp","message":{"role":"user","content":"x"}}`,
+		`{"type":"assistant","timestamp":"2026-07-09T00:00:01Z","sessionId":"fail","cwd":"/tmp","message":{"role":"assistant","content":[{"type":"tool_use","id":"r1","name":"Read","input":{"file_path":"/tmp/a.go"}}]}}`,
+		`{"type":"user","timestamp":"2026-07-09T00:00:02Z","sessionId":"fail","cwd":"/tmp","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"r1","content":"ok","is_error":false}]}}`,
+	)
+	s := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	s.analyze.runner = stubJudge{output: "garbage, not json"}
+	s.reportCache.Dir = t.TempDir()
+
+	postResp := httptest.NewRecorder()
+	s.handleSessionResource(postResp, httptest.NewRequest(http.MethodPost, "/api/sessions/fail/analyze", nil))
+	if postResp.Code != http.StatusAccepted {
+		t.Fatalf("analyze status = %d", postResp.Code)
+	}
+	deadline := time.Now().Add(5 * time.Second)
+	var status reportStatus
+	for {
+		resp := httptest.NewRecorder()
+		s.handleSessionResource(resp, httptest.NewRequest(http.MethodGet, "/api/sessions/fail/report", nil))
+		if err := json.Unmarshal(resp.Body.Bytes(), &status); err != nil {
+			t.Fatal(err)
+		}
+		if status.State == "failed" || status.State == "done" {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job never finished: %+v", status)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if status.State != "failed" || status.Error == "" {
+		t.Fatalf("status = %+v", status)
+	}
+}
+
+// gateJudge blocks every call until released, so tests can observe the
+// running state deterministically.
+type gateJudge struct {
+	release chan struct{}
+	output  string
+}
+
+func (g gateJudge) Run(ctx context.Context, prompt, input string) (judge.RunResult, error) {
+	select {
+	case <-g.release:
+	case <-ctx.Done():
+		return judge.RunResult{}, ctx.Err()
+	}
+	return judge.RunResult{Text: g.output, Model: "stub-model"}, nil
+}
+
+func (g gateJudge) Name() string { return "stub" }
+
+func TestAnalyzeRubricFalseBypassesReportCache(t *testing.T) {
+	claudeDir := t.TempDir()
+	writeServerSession(t, filepath.Join(claudeDir, "eval.jsonl"),
+		`{"type":"user","timestamp":"2026-07-09T00:00:00Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":"do the thing"}}`,
+		`{"type":"assistant","timestamp":"2026-07-09T00:00:01Z","sessionId":"eval","cwd":"/tmp","message":{"role":"assistant","content":[{"type":"tool_use","id":"r1","name":"Read","input":{"file_path":"/tmp/a.go"}}]}}`,
+		`{"type":"user","timestamp":"2026-07-09T00:00:02Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"r1","content":"ok","is_error":false}]}}`,
+	)
+	s := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	s.analyze.runner = stubJudge{output: stubJudgeOutput}
+	s.reportCache.Dir = t.TempDir()
+
+	meta, err := s.findSession("eval")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// A richer, rubric-ful report already sits in the cache; a rubric:false
+	// run must not downgrade it.
+	rich := &model.Report{
+		Version:    1,
+		Session:    model.ReportSession{ID: "eval", EventCount: 1},
+		Judge:      model.ReportJudge{CLI: "stub", PromptVersion: judge.PromptVersion, RubricPromptVersion: judge.RubricPromptVersion},
+		Dimensions: []model.ReportDimension{{Name: "exploration", Verdict: model.VerdictGood, Findings: []model.ReportFinding{}}},
+		Rubric:     &model.Rubric{Status: model.RubricStatusScored},
+	}
+	if err := s.reportCache.Store(meta.Key, rich); err != nil {
+		t.Fatal(err)
+	}
+
+	postResp := httptest.NewRecorder()
+	s.handleSessionResource(postResp, httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", strings.NewReader(`{"rubric":false}`)))
+	if postResp.Code != http.StatusAccepted {
+		t.Fatalf("analyze status = %d body=%s", postResp.Code, postResp.Body.String())
+	}
+	deadline := time.Now().Add(5 * time.Second)
+	var status reportStatus
+	for {
+		resp := httptest.NewRecorder()
+		s.handleSessionResource(resp, httptest.NewRequest(http.MethodGet, "/api/sessions/eval/report", nil))
+		if err := json.Unmarshal(resp.Body.Bytes(), &status); err != nil {
+			t.Fatal(err)
+		}
+		if status.State == "done" || status.State == "failed" {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job never finished: %+v", status)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	// The requester gets their dimensions-only result…
+	if status.State != "done" || status.Report == nil || status.Report.Rubric != nil {
+		t.Fatalf("status = %+v", status)
+	}
+	// …and the richer cached report survives untouched on disk.
+	if cached := s.reportCache.Load(meta.Key); cached == nil || cached.Rubric == nil {
+		t.Fatalf("rubric:false overwrote the richer cache: %#v", cached)
+	}
+}
+
+func TestAnalyzeConflictingConfigRejected(t *testing.T) {
+	claudeDir := t.TempDir()
+	writeServerSession(t, filepath.Join(claudeDir, "eval.jsonl"),
+		`{"type":"user","timestamp":"2026-07-09T00:00:00Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":"do the thing"}}`,
+		`{"type":"assistant","timestamp":"2026-07-09T00:00:01Z","sessionId":"eval","cwd":"/tmp","message":{"role":"assistant","content":[{"type":"tool_use","id":"r1","name":"Read","input":{"file_path":"/tmp/a.go"}}]}}`,
+		`{"type":"user","timestamp":"2026-07-09T00:00:02Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"r1","content":"ok","is_error":false}]}}`,
+	)
+	s := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	gate := gateJudge{release: make(chan struct{}), output: stubJudgeOutput}
+	s.analyze.runner = gate
+	s.reportCache.Dir = t.TempDir()
+
+	first := httptest.NewRecorder()
+	s.handleSessionResource(first, httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", nil))
+	if first.Code != http.StatusAccepted {
+		t.Fatalf("first analyze = %d", first.Code)
+	}
+	// Same session, different configuration: the API must refuse rather than
+	// pretend the in-flight run covers it.
+	conflict := httptest.NewRecorder()
+	s.handleSessionResource(conflict, httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", strings.NewReader(`{"rubric":false}`)))
+	if conflict.Code != http.StatusConflict {
+		t.Fatalf("conflicting config = %d, want 409", conflict.Code)
+	}
+	// Same configuration deduplicates as before.
+	same := httptest.NewRecorder()
+	s.handleSessionResource(same, httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", nil))
+	if same.Code != http.StatusAccepted {
+		t.Fatalf("same config = %d, want 202", same.Code)
+	}
+	close(gate.release)
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		resp := httptest.NewRecorder()
+		var status reportStatus
+		s.handleSessionResource(resp, httptest.NewRequest(http.MethodGet, "/api/sessions/eval/report", nil))
+		if err := json.Unmarshal(resp.Body.Bytes(), &status); err != nil {
+			t.Fatal(err)
+		}
+		if status.State == "done" || status.State == "failed" {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("job never finished after release")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+func TestAnalyzeEndpointRejectsBadBodies(t *testing.T) {
+	claudeDir := t.TempDir()
+	writeServerSession(t, filepath.Join(claudeDir, "eval.jsonl"),
+		`{"type":"user","timestamp":"2026-07-14T00:00:00Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":"do the thing"}}`,
+		`{"type":"assistant","timestamp":"2026-07-14T00:00:01Z","sessionId":"eval","cwd":"/tmp","message":{"role":"assistant","content":[{"type":"tool_use","id":"r1","name":"Read","input":{"file_path":"/tmp/a.go"}}]}}`,
+		`{"type":"user","timestamp":"2026-07-14T00:00:02Z","sessionId":"eval","cwd":"/tmp","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"r1","content":"ok","is_error":false}]}}`,
+	)
+	s := New(Config{ClaudeDir: claudeDir, CodexDir: filepath.Join(t.TempDir(), "codex")})
+	s.analyze.runner = stubJudge{output: stubJudgeOutput}
+	s.reportCache.Dir = t.TempDir()
+
+	// This POST starts an expensive run: garbled JSON and trailing garbage
+	// must both be rejected, not silently run with defaults.
+	for _, body := range []string{`{bad`, `{"cli":"stub"} trailing`} {
+		resp := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", strings.NewReader(body))
+		s.handleSessionResource(resp, req)
+		if resp.Code != http.StatusBadRequest {
+			t.Fatalf("body %q -> %d, want 400", body, resp.Code)
+		}
+	}
+
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/sessions/eval/analyze", strings.NewReader(`{"cli":"gemini"}`))
+	s.handleSessionResource(resp, req)
+	if resp.Code != http.StatusBadRequest {
+		t.Fatalf("unknown cli -> %d, want 400", resp.Code)
+	}
+}

package/internal/server/codex_index_test.go

@@ -0,0 +1,40 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// A Codex thread rename only touches session_index.jsonl, never the session
+// file. The summary cache must treat the index as a summary input, or the
+// rename stays invisible for the life of the serve process.
+func TestFreshScanPicksUpCodexTitleIndexChange(t *testing.T) {
+	base := t.TempDir()
+	codexDir := filepath.Join(base, "sessions")
+	if err := os.MkdirAll(codexDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeServerJSONL(t, filepath.Join(codexDir, "s1.jsonl"), map[string]any{
+		"timestamp": "2026-07-09T00:00:00Z",
+		"type":      "session_meta",
+		"payload":   map[string]any{"id": "codex-title", "cwd": "/tmp"},
+	})
+	writeIndex := func(title string) {
+		writeServerJSONL(t, filepath.Join(base, "session_index.jsonl"),
+			map[string]any{"id": "codex-title", "thread_name": title})
+	}
+	writeIndex("Title One")
+
+	s := New(Config{ClaudeDir: filepath.Join(t.TempDir(), "claude"), CodexDir: codexDir, PiDir: filepath.Join(t.TempDir(), "pi")})
+	initial := requestSessions(t, s, "/api/sessions")
+	if len(initial) != 1 || initial[0].Title != "Title One" {
+		t.Fatalf("initial sessions = %#v", initial)
+	}
+
+	writeIndex("Title Two Updated")
+	fresh := requestSessions(t, s, "/api/sessions?fresh=1")
+	if len(fresh) != 1 || fresh[0].Title != "Title Two Updated" {
+		t.Fatalf("index change not picked up: %#v", fresh)
+	}
+}

package/internal/server/hardening_test.go

@@ -0,0 +1,147 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+func TestHandlerRejectsNonLocalHost(t *testing.T) {
+	s := New(Config{})
+	handler := s.handler()
+
+	// A stray bracket must not normalize into an allowed host.
+	for _, host := range []string{"evil.example:8765", "localhost]", "localhost]:8765", "[localhost:8765"} {
+		req := httptest.NewRequest(http.MethodGet, "/api/repomap", nil)
+		req.Host = host
+		resp := httptest.NewRecorder()
+		handler.ServeHTTP(resp, req)
+		if resp.Code != http.StatusForbidden {
+			t.Fatalf("Host %q status = %d, want 403", host, resp.Code)
+		}
+	}
+
+	// Host names are case-insensitive.
+	for _, host := range []string{"127.0.0.1:8765", "localhost:8765", "LOCALHOST:8765", "[::1]:8765"} {
+		req := httptest.NewRequest(http.MethodGet, "/api/repomap", nil)
+		req.Host = host
+		resp := httptest.NewRecorder()
+		handler.ServeHTTP(resp, req)
+		if resp.Code == http.StatusForbidden {
+			t.Fatalf("local Host %q rejected", host)
+		}
+	}
+}
+
+func TestAnalyzeRejectsCrossSiteRequests(t *testing.T) {
+	s := New(Config{})
+	handler := s.handler()
+	post := func(origin, fetchSite string) int {
+		req := httptest.NewRequest(http.MethodPost, "/api/sessions/nope/analyze", nil)
+		req.Host = "127.0.0.1:8765"
+		if origin != "" {
+			req.Header.Set("Origin", origin)
+		}
+		if fetchSite != "" {
+			req.Header.Set("Sec-Fetch-Site", fetchSite)
+		}
+		resp := httptest.NewRecorder()
+		handler.ServeHTTP(resp, req)
+		return resp.Code
+	}
+
+	rejected := []struct{ origin, fetchSite string }{
+		{"https://evil.example", ""},
+		{"null", ""},
+		{"", "cross-site"},
+		{"", "same-site"},
+		{"http://127.0.0.1:8765", "cross-site"},
+		// Loopback is not same-origin: another local server's page — a
+		// different host name, port, or scheme — must not pass.
+		{"http://localhost:9999", ""},
+		{"http://127.0.0.1:9999", ""},
+		{"http://localhost:8765", ""},
+		{"https://127.0.0.1:8765", ""},
+	}
+	for _, c := range rejected {
+		if code := post(c.origin, c.fetchSite); code != http.StatusForbidden {
+			t.Fatalf("origin=%q fetchSite=%q status = %d, want 403", c.origin, c.fetchSite, code)
+		}
+	}
+
+	// Same-origin browser requests and non-browser clients (no Origin) must
+	// pass the middleware; 404 here means the handler ran and found no session.
+	allowed := []struct{ origin, fetchSite string }{
+		{"", ""},
+		{"http://127.0.0.1:8765", ""},
+		{"http://127.0.0.1:8765", "same-origin"},
+		{"", "none"},
+	}
+	for _, c := range allowed {
+		if code := post(c.origin, c.fetchSite); code == http.StatusForbidden {
+			t.Fatalf("origin=%q fetchSite=%q rejected by middleware", c.origin, c.fetchSite)
+		}
+	}
+}
+
+// Cross-site GETs stay readable-by-middleware (CORS already blocks the
+// response); only non-GET methods carry the Origin gate.
+func TestCrossSiteGetPassesMiddleware(t *testing.T) {
+	s := New(Config{})
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	req.Host = "127.0.0.1:8765"
+	req.Header.Set("Origin", "https://evil.example")
+	req.Header.Set("Sec-Fetch-Site", "cross-site")
+	resp := httptest.NewRecorder()
+	s.handler().ServeHTTP(resp, req)
+	if resp.Code == http.StatusForbidden {
+		t.Fatal("cross-site GET rejected; reads are CORS-protected, not middleware-gated")
+	}
+}
+
+func TestRepoMapUsesInjectedBuilder(t *testing.T) {
+	repoRoot := t.TempDir()
+	if err := os.WriteFile(filepath.Join(repoRoot, "a.go"), []byte("package demo\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	s := New(Config{})
+	calls := 0
+	s.buildCityMap = func(repo string, trace *model.Trace) (*model.CityMap, error) {
+		calls++
+		return emptyCityMap(repo), nil
+	}
+	if _, err := s.repoCityMap(repoRoot); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("injected builder calls = %d, want 1", calls)
+	}
+}
+
+func TestAgentGraphCacheIsBounded(t *testing.T) {
+	s := New(Config{})
+	s.mu.Lock()
+	base := time.Now()
+	for i := 0; i < agentGraphMaxEntries+5; i++ {
+		s.agentGraphs[string(rune('a'+i))] = agentGraphCacheEntry{
+			graph: &model.AgentGraph{},
+			used:  base.Add(time.Duration(i) * time.Second),
+		}
+	}
+	s.evictAgentGraphsLocked()
+	n := len(s.agentGraphs)
+	_, newestKept := s.agentGraphs[string(rune('a'+agentGraphMaxEntries+4))]
+	_, oldestKept := s.agentGraphs["a"]
+	s.mu.Unlock()
+	if n != agentGraphMaxEntries {
+		t.Fatalf("agent graph cache size = %d, want %d", n, agentGraphMaxEntries)
+	}
+	if !newestKept || oldestKept {
+		t.Fatalf("eviction order wrong: newestKept=%v oldestKept=%v", newestKept, oldestKept)
+	}
+}

package/internal/server/reportindex.go

@@ -0,0 +1,91 @@
+package server
+
+import (
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/judge"
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+// reportIndexTTL bounds how stale the directory listing may get. The reports
+// directory is also written by the CLI, so the listing cannot be trusted for
+// long; 5s matches the session-list polling cadence.
+const reportIndexTTL = 5 * time.Second
+
+// reportIndex keeps the session list's report lookups off the disk hot path.
+// Most sessions have no report: one ReadDir per TTL answers "which sessions
+// have a report at all" instead of a stat per session per request, and
+// per-key loads are memoized against the report file's fingerprint so a
+// report is re-read only when it changed. Same-process writers must call
+// markPresent after storing a report — the TTL only covers writers this
+// server cannot see.
+type reportIndex struct {
+	mu      sync.Mutex
+	scanned time.Time
+	present map[string]bool
+	loaded  map[string]reportMemo
+}
+
+type reportMemo struct {
+	fingerprint fileFingerprint
+	report      *model.Report
+}
+
+// load returns the cached report for key, or nil when none exists. The cache
+// is passed per call so a Dir override after construction is observed.
+func (ri *reportIndex) load(cache judge.Cache, key string) *model.Report {
+	if cache.Dir == "" || key == "" {
+		return nil
+	}
+	ri.mu.Lock()
+	defer ri.mu.Unlock()
+	if time.Since(ri.scanned) >= reportIndexTTL {
+		ri.present = map[string]bool{}
+		if entries, err := os.ReadDir(cache.Dir); err == nil {
+			for _, entry := range entries {
+				if name, ok := strings.CutSuffix(entry.Name(), ".json"); ok {
+					ri.present[name] = true
+				}
+			}
+		}
+		for key := range ri.loaded {
+			if !ri.present[key] {
+				delete(ri.loaded, key)
+			}
+		}
+		ri.scanned = time.Now()
+	}
+	if !ri.present[key] {
+		return nil
+	}
+	fingerprint, err := fingerprintFile(cache.Path(key))
+	if err != nil {
+		delete(ri.loaded, key)
+		return nil
+	}
+	if memo, ok := ri.loaded[key]; ok && memo.fingerprint.equal(fingerprint) {
+		return memo.report
+	}
+	report := cache.Load(key)
+	if ri.loaded == nil {
+		ri.loaded = map[string]reportMemo{}
+	}
+	ri.loaded[key] = reportMemo{fingerprint: fingerprint, report: report}
+	return report
+}
+
+// markPresent records that a report for key now exists on disk, so a load
+// within the listing TTL finds it. Without this, a poll landing right after
+// the server persisted a report — and after the job entry was dropped —
+// would read "no report" until the next directory scan.
+func (ri *reportIndex) markPresent(key string) {
+	ri.mu.Lock()
+	defer ri.mu.Unlock()
+	if ri.present == nil {
+		ri.present = map[string]bool{}
+	}
+	ri.present[key] = true
+}