[Juliusolsson05]

Refs #1273. With the default rotation setting, the events file is now bounded. A live run directory still has one unbounded file, sslkeylog.log, filed as #1380, so this PR does not close #1273.

Problem

#1284 / claude-code-headless#62 capped request bodies per events file, but two items stayed open:

• a live Claude session's proxy-events.jsonl still grew for the life of the session (responses, stream chunks, body-less requests);
• debug retention never reclaims a live run.

Change

This PR bumps packages/claude-code-headless to f52fc82, which is claude-code-headless#64 (merged after three reviews, a verification pass and a final round 3):

• Rotation: the mitmproxy addon rotates the events file at 512 MiB (PROXY_EVENTS_ROTATE_BYTES), keeping exactly one previous generation (proxy-events.1.jsonl). A live run holds at most ~2 × 512 MiB. The bound holds under the default setting only: PROXY_EVENTS_ROTATE_BYTES=0 (the forensic override) disables rotation, and the events file then grows without bound.
• Generation headers: every generation created by a rotation starts with a header line, {"kind":"generation","generation":n}, created atomically. Generation 0 has no header: the run's first event creates it. The tail treats a missing header as generation 0 and uses the headers to know exactly which generation it holds.
• The tail (EventsFileTail) holds a FileHandle on its generation, finishes it on rotation, reads an unseen .1 in order, and reports any generation deleted unread as lostGenerations. ProxyServer emits that as a transport-gap event.
  • Package contract (inside claude-code-headless): every event exactly once, or an explicit gap event. It does not extend into the app; see below.
  • Known limitation, stated in feat(command-palette): add command descriptions panel #64: a crash between the rename and the next header is repaired when the addon restarts. If it is never restarted, that generation's unread events are lost without a gap.
• Addon hardening: a write never raises out of a mitmproxy hook; a crashed partial line is terminated at startup; an interrupted rotation is finished at startup.

On the app side:

• Bundle reader: W1's rotation-safe reader (fix(codex): bound the proxy mirror on disk and take it off the main process's synchronous path #1332) is already on main; it reads across .1 and ships raw bytes, where the header is one more JSON line.
• Retention: debugRetention detects a run by proxy-events.jsonl, which the addon now recreates immediately after a rotation.
• No lockfile resync: the app consumes claude-code-headless from source (tsconfig and Vite aliases), not as a file: dependency. Its runtime deps (chokidar, @xterm/headless) are root deps. The bump changes only the package's devDependencies, and npm install --package-lock-only leaves package-lock.json unchanged.
• Gap signal in the app: diagnostic only (review a/b/c; manager decision, steering q87). ClaudeSession now subscribes to the proxy's transport-gap as well as event, and SessionManager records a claude.proxy_transport_gap incident for the session.
  • Transport gaps are recorded as incidents (debug bundle); the live feed and transcript show NO gap marker yet.
  • The user-visible marker is a stated residual, claude feed: show a missing-span marker when the proxy transport reports a gap #1381.
• Retention (review a): a run holding only proxy-events.1.jsonl (a rotation whose next file was never created) is now counted, so it cannot accumulate invisibly.
• Disk bound, stated honestly:
  • events: ~2 × 512 MiB with the default PROXY_EVENTS_ROTATE_BYTES; unbounded if it is set to 0;
  • latest-body sidecar: ≤ 16 MiB raw, ~21.3 MiB on disk, twice that briefly during its atomic replace;
  • sslkeylog.log: unbounded until claude proxy: sslkeylog.log grows unbounded in every live run dir (and holds TLS secrets on disk) #1380.
• Plan: docs/plans/2026-09-26-proxy-events-retention.md.

Verification

• Package: the tests are in feat(command-palette): add command descriptions panel #64 and green in its CI: a real addon plus real tailer, rotation before every await point, kill-restart, the header chain, and the gap report.
• This head: npx tsc -b prints 0 lines.
• New app tests:
  • claudeSession.suspension.test.ts: proxy event forwarding, the gap re-emit, and detach;
  • sessionManager.proxyGap.test.ts: the incident and the re-emit;
  • debugRetention.test.ts: a .1-only run is counted.
• Mutations killed: the session ignoring transport-gap, the session ignoring event, the manager ignoring the gap, retention ignoring .1.
• At 8996d9d3, src/providers/claude, proxyEventsReader and debugRetention passed 245/245.

🤖 Generated with Claude Code

[Juliusolsson05]

Review disposition (round 1: a, b, c codex at 8996d9d3)

#	Finding	Verdict	Disposition
a1 / b1 / c2	The app drops transport-gap; the "exactly once, or an explicit gap" contract stops at the package boundary. Even the event wiring was untested.	valid	Fixed in 0de54245: ClaudeSession subscribes to both channels, and SessionManager records a claude.proxy_transport_gap incident and re-emits it with the session id. Pinned at both layers; all four wiring mutants are red.
a2	A run holding only .1 is invisible to retention	valid	Fixed: collectProxyRunDirs counts it; test plus mutant.
c1	sslkeylog.log in the same run directory grows without bound (and holds TLS secrets), so Fixes #1273 overclaimed	valid	Filed as #1380 (outside this bump: it needs a package change). The PR is narrowed to Refs #1273, and the body states the real disk bound.
c3	The sidecar bound omitted base64 expansion	valid	Fixed in the plan and body: ~21.3 MiB on disk, twice that briefly during the replace.

Verification pass: a/b/c at 0de54245, queued under the reviewer cap.

Steering q87: the gap is diagnostic-only in the app: an always-on incident plus a manager re-emit. Nothing renders a missing-span marker yet, so the user-visible gap is filed as #1381. The body and plan say exactly that (33c046cf).

Focused verification (c, steering q87/q89) — the central diagnostic claim was found accurate. Three minors:

• Body said every generation has a header. Corrected: only generations created by a rotation carry one; generation 0 has none.
• Body stated the disk bound as absolute. Corrected: it holds under the default PROXY_EVENTS_ROTATE_BYTES, and 0 (the forensic override) disables rotation.
• The gap subscription's ownership guard was unpinned. Pinned in the new head: a replaced session's late gap is not recorded against its successor; the mutant is red.

Round 2 (verification, a/b/c codex at 49ee5985):

• a: MERGE-READY. One surviving mutation: stripping {"kind":"generation"} lines from bundled JSONL in proxyEventsReader.ts passes. Accepted, not a defect. The bundle ships raw bytes on purpose; whether a header line appears in a diagnostic bundle changes no behaviour.
• b: MERGE-READY. No survivors.
• c: FIX-BEFORE-MERGE, minor docs/format only. No survivors (all four replayed mutants are red).
  • The plan's Decisions/Tests/Delivery sections still stated the pre-review scope. Fixed in f04837d2: the events file is bounded, the run directory is not (claude proxy: sslkeylog.log grows unbounded in every live run dir (and holds TLS secrets on disk) #1380), and the app wiring and its tests are listed.
  • Extra EOF blank lines in three test files. Fixed in f04837d2; git diff --check origin/main...HEAD is clean.
  • f04837d2 touches no source: one plan doc and three trailing newlines. Both review rounds are spent, so this goes to manager-verify-c.

Manager-verify-c (temp/review-1376/manager-verify-c.md) confirms f04837d2 by inspection: plan docs only, and the src changes are trailing blank lines. merge-gate --member --dry: GATE PASS (f04837d2, 0 behind, checks green). READY.

After batch F (69adefbd): merged origin/main because of a real conflict. The only conflicting path was the claude-code-headless gitlink, and this branch's f52fc82 contains main's 728cb494, so it is kept. The merged tree gives npx tsc -b 0 lines, the focused suites pass 17/17, and CI is green. merge-gate --member --dry: GATE PASS (69adefbd, 0 behind). READY.