/insights: large-session facets record a 500-token error that never occurred, misfiling them as unclear_from_transcript

/insights facets for large sessions are being populated with an error that never occurred in the session, causing those sessions to be permanently filed as unclear_from_transcript. Happy to share affected session IDs, the measurement script, and my notes on the likely mechanism privately if that helps triage.

Symptom

Facets for sessions with large transcripts contain a "500 output token maximum" API error and no content:

{
  "outcome": "unclear_from_transcript",
  "friction_detail": "Claude's responses repeatedly exceeded the 500 output token maximum, causing API errors",
  "brief_summary": "The transcript content is not available (only metadata and API errors present)…"
}

The affected sessions contain no such error. The error is being generated somewhere inside facet processing and then consumed downstream as if it were session content — it lands verbatim in friction_detail.

Measurements, 2026-07-18, Claude Code 2.1.161

Counts from ~/.claude/usage-data/facets/ cross-referenced against the session transcripts in ~/.claude/projects/:

• 145 facets total; 12 carry the literal 500-token error marker; 25 are filed outcome: unclear_from_transcript
• 114 of the 145 sessions still have a transcript on disk (retention has removed the rest)
• 8 of the 12 marker-carrying facets have a surviving transcript to check against

Those 8 are all substantial, ordinary sessions. Assistant messages 371–889 (median 549); tool calls 138–427 (median 204).

The error text appears zero times in all 8 transcripts. That is the core defect: the string in friction_detail describes an event that did not occur in the session it is attached to.

It correlates with transcript size

Over the 114 sessions with transcripts (volume = extracted text across user/assistant/tool-result content, sidechains excluded):

| extracted text | poisoned | total | rate |
|---|---|---|---|
| < 150K chars | 0 | 26 | 0% |
| 150K–500K | 1 | 47 | 2% |
| > 500K | 7 | 41 | 17% |

Monotonic with size; nothing below 150K is affected. Because it selects for the largest transcripts, it preferentially eats the highest-effort sessions — which understates the success-rate statistics the report then displays.

It is permanent, and it is in every batch

Facet files are written once per report run and accumulate; they are never re-derived. Grouping the 145 facets by generation date gives four distinct /insights runs:

| run | facets written | of which poisoned |
|---|---|---|
| 2026-06-24 | 45 | 6 |
| 2026-07-05 | 50 | 3 |
| 2026-07-09 | 26 | 2 |
| 2026-07-18 | 24 | 1 |

Two consequences. The defect is present in every run across four weeks, still reproducing on 2.1.161. And because nothing regenerates a facet, a session misfiled once stays misfiled forever — every future report that aggregates these facets inherits the corruption, with no user-facing way to correct it.

Setting CLAUDE_CODE_MAX_OUTPUT_TOKENS does not appear to affect this internal call.

Second-order effect: the report advises the user to work around its own bug

My 2026-07-05 report stated as fact: "Your configuration caps responses at a 500 output-token maximum" — and generated a suggested CLAUDE.md addition instructing me to "Keep responses under the 500 output-token limit."

No such cap was ever configured on my side. The report diagnosed its own internal summarizer as a defect in my setup and proposed I write that fiction into my instruction file.

Suggested fixes (any one)

• Have the summarize step detect the max-tokens stop reason and reject it, rather than accepting the error string as content.
• Return the truncated-but-usable text instead of substituting an error string, at least for non-interactive insights calls.
• Raise the output cap on that internal call.
• Independently: provide a way to invalidate and re-derive a facet, so sessions already misfiled can be recovered after a fix.