Summary

• Problem: After the on-disk session-file repair pass runs against a transcript that already accumulated null-role JSONL corruption, the post-repair file (and its .bak-* backup) still contains the corrupt entries — the report in Session corruption: prefill error cascades into provider cooldown + repair makes it worse #77228 saw "935+ entries with null roles (complete structural JSONL corruption)" surviving the repair, with the next provider call failing on a now-different shape error (400 messages: at least one message is required once enough valid entries had been displaced). The reporter's debug line [session-init] session file repair: rewrote 1 assistant message(s), dropped 1 blank user message(s) confirms the repair pass did run on the file but left the null-role entries in place.

• Root Cause: src/agents/session-file-repair.ts:repairSessionFileIfNeeded (:160-295) iterates persisted JSONL lines, applies two narrow rewrites (isAssistantEntryWithEmptyContent rewrite at :36-58/60-68, repairUserEntryWithBlankTextContent at :75-136), and otherwise pushes the parsed entry to entries[] as-is (:219). The two rewrites only fire on a non-null assistant/user role; a type:"message" envelope whose message.role is null, undefined, or a blank string does not match either rewrite predicate and falls through to the as-is push. The repair then atomically rewrites the file to disk, persisting the null-role entries unchanged. There is no provider router downstream that can do anything useful with a role: null message — every classifier in src/agents/session-transcript-repair.ts, src/agents/cli-runner/session-history.ts, and the provider-runtime replay sanitizers branches on message.role ("user"/"assistant"/"toolResult"/"compactionSummary"); a null-role entry is unconditionally dead weight on the wire.

• Fix: Add a structural-validity predicate isStructurallyInvalidMessageEntry and consult it inside the parse loop before the rewrite predicates run. When a type:"message" envelope has no message object, has a non-object message, or its message.role is missing, null, or a whitespace-only string, treat the line the same way the existing JSON.parse failure branch treats an unparseable line: increment droppedLines and skip the push to entries[]. The repair output is therefore guaranteed not to contain a null-role type:"message" entry, regardless of what the input file accumulated. Entries of other envelope types (type:"session", type:"summary", type:"custom", anything not "message") are not subject to this check and pass through unchanged — only the message envelope contract is enforced.

• What changed:

  • src/agents/session-file-repair.ts — add the isStructurallyInvalidMessageEntry helper and wire it into the parse loop ahead of isAssistantEntryWithEmptyContent so the drop decision is made before either rewrite predicate runs. Doc comment records why preservation through repair is wrong and which downstream code branches on message.role.
  • src/agents/session-file-repair.test.ts — add three new tests: (1) drops role: null / missing-role / blank-role type:"message" entries and counts them toward droppedLines, asserting the post-repair file no longer contains "role":null; (2) drops type:"message" envelopes whose message field is missing or non-object; (3) preserves non-"message" envelope types (type:"summary", type:"custom") untouched so the structural check does not over-reach.
  • CHANGELOG.md — single Fixes line under Unreleased referencing the issue with non-closing Refs syntax.

• What did NOT change (scope boundary):

  • No changes to the existing rewrite predicates (isAssistantEntryWithEmptyContent, repairUserEntryWithBlankTextContent) or to BLANK_USER_FALLBACK_TEXT / STREAM_ERROR_FALLBACK_TEXT. Existing test cases continue to assert the same rewrite behavior — the new structural check runs before those predicates and on different inputs (null-role), so it cannot change the verdict for any input the existing tests exercise.
  • No changes to file-write / atomic-rename / backup logic (:246-258). The repair still writes a .bak-* backup of the original and atomically renames the cleaned file in place.
  • No source-of-null-role investigation or fix. The producer of the null-role entries (suspected to be a write-side path or an external mutation; the reporter observed null roles in both the active .jsonl and the older .reset.<iso> archive, suggesting the corruption pre-dates the repair pass) is out of scope for this PR. Defending the repair output from preserving the corruption is the narrowly-scoped, surgically defensible fix; locating the producer can land in a separate follow-up.
  • No changes to the cascading auth-profile cooldown that this corrupted session can trigger upstream of the repair pass, and no changes to the trailing prefill-placeholder shape that originally tripped the provider 400. Each is a separate failure mode in the same issue and gets its own narrowly-scoped PR.

Reproduction

1. Construct (or copy from a real-world reproducer) a session JSONL whose tail contains one or more type:"message" entries shaped like {"type":"message","id":"...","timestamp":"...","message":{"role":null,"content":"..."}}. The report's reproducer happens organically after a series of failures cascading off a prefill 400; for a deterministic reproducer in unit-test space, write the entries directly with JSON.stringify.
2. Add a session header line as the first entry ({"type":"session","id":"...","version":7,"timestamp":"...","cwd":"..."}) and a normal role:"user" message somewhere in the body so the repair pass cannot bail on the entries.length === 0 / invalid session header early-returns.
3. Call repairSessionFileIfNeeded({ sessionFile }).
4. Without this fix: the post-repair file still contains every null-role entry, just re-serialized through JSON.stringify. result.droppedLines reflects only unparseable JSON lines; the null-role count is hidden, and the cleaned transcript is structurally identical (modulo the rewrite passes) to the original — including the corruption.
5. With this fix: each null-role entry counts toward result.droppedLines and is absent from the post-repair file. The structural check fires before the rewrite predicates, so the existing rewrite paths are unaffected for any non-null-role input.

Risk / Mitigation

• Risk 1 — over-broad role validation: Could the new check reject a legitimate envelope type whose top-level shape is also type:"message" but whose role lives somewhere else? No. The check only fires when entry.type === "message". Other envelope types ("session", "summary", "custom", "model-snapshot", etc.) skip the check entirely. The "preserves non-message envelope types" test locks this boundary, including a type:"custom" model-snapshot entry shape that is observed in production replay history.
  Mitigation: explicit positive test for type:"summary" and type:"custom"; explicit negative tests for role: null, missing role, and blank-string role; result.droppedLines is incremented in lock-step so any drop is observable through the existing repair report and debug log.
• Risk 2 — losing recoverable data: Could a null-role entry have carried information worth keeping? No: every provider router branches on message.role and would silently drop the entry on the wire anyway. The only "value" of preserving null-role entries is keeping the original byte payload around for debugging — and the existing .bak-* backup written by the repair pass already preserves that byte payload verbatim before any drop decisions are made.
  Mitigation: the existing backup-then-rewrite atomic-rename flow at :246-258 is unchanged; original bytes remain available off-line under the .bak-* file for postmortem.
• Risk 3 — interaction with the existing rewrite predicates: Could the new check race with the empty-assistant-error rewrite or the blank-user rewrite and produce a different verdict? No. The new check fires first in the parse loop. A null-role entry never reaches isAssistantEntryWithEmptyContent (which bails immediately because message.role !== "assistant") nor repairUserEntryWithBlankTextContent (which is gated on message.role === "user" at the call site :206). For any non-null-role entry, the new check is a no-op and the existing predicates run unchanged.
  Mitigation: existing rewrite tests at :101-281 continue to pass without modification.
• Risk 4 — entries.length === 0 after the drop: If the repair drops all message entries (only the session header survives), the existing entries.length === 0 check at :225-227 already returns repaired: false with reason: "empty session file" — this is correct behavior and matches the existing contract: an empty transcript is reported, the original file is left untouched. The fix does not introduce a new "successfully wrote an empty transcript" failure mode.
  Mitigation: covered by existing assertions on the early-return branches.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Agents (session-file-repair on-disk pass)
• Tests (session-file-repair.test.ts)
• Changelog (Unreleased Fixes entry)

Linked Issue/PR

Refs #77228 — addresses the auto-repair amplifier only (the repair pass no longer preserves null-role JSONL corruption from the input). The cascading auth-profile cooldown amplifier (a single format 400 currently poisons the whole auth profile across sessions) and the trailing prefill-placeholder root cause (the stream-error sentinel ends up as the trailing message and triggers a prefill-strict 400) are independent failure modes in the same issue and are out of scope here so each can ship as its own narrowly-scoped PR.