cc-explorer: make failure a queryable axis (errors_only + survey_failures)

[coryking]

Closes #57.

Failure was not a queryable axis of the transcript corpus. You could slice by project,
session, agent, role, pattern, and date — but not by "this call failed," even though
11,583 tool results carry is_error: true. The only path to them was guessing the error's
prose and regexing for it.

Two surveyed episodes measured that tax: one agent fired ~30 guessed vocabulary
patterns to approximate "show me failed connections near host X," and another required
its orchestrator to pre-write ~25 literal candidate error strings into the dispatch
prompt before it could start.

What this adds

errors_only on search_projects / grep_session / grep_sessions — narrows hits to
tool results that actually failed. On the issue's own scenario, patterns=["ssh"] over
home-it-services goes from 6,193 hits to 74 actual failures, surfacing
Connection refused / No route to host / Could not resolve hostname with nothing
guessed.

survey_failures — a cross-project rollup. audit_session_tools' error machinery
promoted out of single-session, single-agent scope, plus a 16-kind taxonomy over a
5-value category axis (agent / policy / environment / cascade / unknown). Cascade
errors are suppressed from headline counts by default; unclassified sits third in the
payload because that bucket is where novel breakage lives.

FailureKind / FailureCategory in models.py, sited as a deliberate parallel to the
existing UserOrigin enum, with ToolResultContent.failure as the single classification
entry point. collect_tool_calls — the tool_use↔tool_result pairing walk — was lifted out
of subagents.py so the single-session audit and the corpus survey share one
implementation.

Payload economy

Default output is counts only — roughly 1,180 tokens for a 7-day window. Error text is
opt-in via examples=true. All four list sections are capped by limit (default 10) with
an explicit *_overflow line naming what was dropped; nothing truncates silently. No
existing response model gained a field.

Design decision worth reading

The issue prescribed reusing _result_is_error as the error gate. That was overridden with
measurement: of tool results carrying "not found"/"no matches" in their first 200 chars,
1,095 are not flagged as errors versus 567 that are. Letting prose promote successes to
failures would bury real breakage in the one tool whose entire value is precision. So
is_error is the gate and prose only classifies; the old heuristic survives under its true
name, looks_like_no_match, used only by audit_session_tools, whose question ("did this
come back empty?") is genuinely different.

Review

Three reviewers (correctness, Python, project-standards). Seven correctness fixes, five
design cleanups, and eight new tests targeting the gaps that let the bugs through. The
material ones, all re-verified corpus-wide after fixing:

• ENOTFOUND matched ModuleNotFoundError — no word boundary, re.I. The network
  bucket was 175 entries, 96 of them Python tracebacks. That poisoned the environment
  category the docs point surveyors at. After anchoring: network 175 → 76, Python
  tracebacks 96 → 0.
• collect_tool_calls assumed file order is causal order — JSONL flushes out of order,
  so a tool_result written before its tool_use was silently dropped. 740 of 257,986
  blocks corpus-wide; failures visible to the survey went 11,532 → 11,576. This also had
  the two halves of the feature disagreeing: errors_only found these, the survey did not.
  An equivalence-oracle test now pins them together.
• kinds='cascade' was unreachable — suppression ran before the kinds filter, so it
  always returned zero and the error told you to widen the window. Naming cascade now
  implies include_cascade.
• bad_path's bare does not exist filed 244 Postgres schema errors under category
  agent — the category the triage workflow tells you to filter out.
• errors_only drill-in showed the wrong context — at the default role=user the
  causing assistant turn (median 1 entry back) was structurally never shown, while the
  nearest human turn was a median of 8 away, p90 81, and 24 failed results had no preceding
  human turn at all.
• Whole-text normalization to read a 1,000-char window — 96× slower on a 540 KB result,
  in a package with a 5.5 GB RSS incident in its history.
• short_name collapsed distinct MCP tools — 17 of 153 short names are shared by 2–3
  servers, blending their error rates in a denominator the issue calls load-bearing.

Tests: 480 → 507 passed, 1 xfailed. No existing test weakened.

Known scope limit

Filed #62 separately: Corpus.discover enumerates enc.glob("*.jsonl") — top-level main
transcripts only — so 430 session directories whose parent transcript is gone strand
2,373 subagent files (~32% of transcripts) outside every search path. Pre-existing, not
caused by this work, but it bounds this tool the same way it already silently bounds
search_projects and grep_session.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kor6NdZegwKxn55hdvZiot