[Juliusolsson05]

Refs Juliusolsson05/agent-code#372. App side: Juliusolsson05/agent-code#1332 (pointer bump plus the shared, rotation-safe debug-bundle reader).

Plan: agent-code docs/plans/2026-09-26-codex-proxy-mirror-bound.md.

Problem

ResponsesProxy.emit ran JSON.stringify and then appendFileSync for every event, before the listeners, with no cap and no drop policy.

• A real 3 h Codex session wrote 103.5 MB. response-chunk lines were 91.3% of it.
• Replaying the recorded median chunk 13,890 times through the old path took 1.9 s in total, with a worst single append of 74 ms, all on the Electron main process. Review C's reruns measured maxima of 4.8 ms and 9.5 ms, so a single maximum depends on the machine and its load; the synchronous blocking itself reproduces.
• With about 15 sessions live, proxy/ was at 2.3 GB, and nothing rotated.

Change

src/proxy/eventsMirror.ts, EventsMirror:

• Async and ordered. One fs.WriteStream per file; emit only serialises and queues.
• Synchronous open, once per file. The file is opened with openSync and sized with fstatSync on that fd, so a stream is never pending and a rotation never waits for an open. Earlier, deferring the rotation let a startup burst or a restart at the cap push the file past its cap (review A3).
• An exact per-file bound, decided before any rename. Each write is an optional drop or rotation marker plus the line, and it must fit within eventsFileMaxBytes (default 64 MiB). The rotation marker is deterministic, so fit is measured first, and a line that fits no file never rotates away kept events. When it would not fit, the file is renamed to <name>.1.jsonl and a fresh file starts with {kind:'mirror-rotated', rotatedBytes, rotations, droppedEvents, droppedBytes}. A line that cannot fit even in a fresh file is dropped and counted. A run holds at most two files.
  • Why rotate rather than follow Claude's omit-past-budget: on Codex the chunks are the bulk, and a debug bundle needs the newest ones.
• An aggregate queue bound. Past 16 MiB of unwritten bytes, counted across every open stream and including markers, lines are dropped and counted. A mirror-dropped marker precedes the next written line, or is written at close.
• Per-stream accounting. A rotated-out stream that fails gives back only its own share and never hangs flush() or stop(). Only the current file failing turns the mirror off, and it stays off. The error listener means a failure never crashes the main process.
• stop() closes the mirror after the server teardown. flushMirror() is added. API.md is updated.

Tests

responsesProxy.mirrorBound.test.ts (18 tests), on the recorded Codex 0.157 chunk (testing/fixtures/proxy-mirror/models-chunk-2865.json):

• emit does not write on the emitting call;
• rotation keeps the newest events complete and byte-exact, each file within the cap, and rotatedBytes equals .1's size;
• a start-of-run burst rotates within the cap;
• a restart at the cap rotates on its first event;
• an oversized line is dropped and marked;
• drops are marked mid-run and at close, the close-time marker stays within the queue bound, and a cap smaller than a marker is never exceeded;
• the queue is bounded across a rotation;
• a failing rotated-out stream settles flush() and close(), and gives back only its own share of pending writes;
• a line that fits no file never evicts kept events;
• the rotation marker counts against both the file cap and the queue;
• rotation happens at the 64 MiB default (a sparse pre-sized file, so no 64 MB is written);
• an unwritable path stays off;
• stop() closes (a later event is not written).

responsesProxy.mirror.test.ts is ported to await flushMirror(), with its assertions unchanged.

Review

• Round 1: three Codex reviewers, all FIX-BEFORE-MERGE; every finding fixed in 7575ae3.
• Round 2 (verification): B MERGE-READY. A and C found the fit-order eviction and two test gaps, fixed in 3e7e35e.
• Round 3 (final verification by A and C): every round-2 fix was confirmed. One new minor (the close-time marker over the queue bound) is fixed in ceefb9c, and steering q62's tiny-cap edge in 6b8ca32. Both came after the final pass and are not re-verified.

The dispositions are in the PR comment.

Verification

• tsc --noEmit is clean.
• src/proxy: 59 tests. tsc --noEmit is clean. The mutant setting the default to 65 MiB is killed. The full package suite is run in the background at each head; src/transcript/* tests time out only under heavy machine load. Those files are untouched here, and they pass on CI.
• Boundary: no app launch.

Residual

• Codex re-fetches /v1/models (about 523 KB, every ~6.5 min). Rotation bounds it, but it shortens the kept window.
• The latest prompt body can fall outside a 5 MiB bundle tail: agent-code#1336.

🤖 Generated with Claude Code

[Juliusolsson05]

Review disposition (final head 6b8ca32)

Two rounds with three Codex reviewers. Round 1 was FIX-BEFORE-MERGE from all three. Round-2 verification: B MERGE-READY; A and C raised fit-order and test gaps, all fixed. Round 3 was the final verification by A and C: both confirmed every round-2 fix and found one new minor, fixed below after the final pass, so it is not re-verified. That is the review cap.

Round 1, all fixed in 7575ae3

• A1, major (a rotated-out stream's error zeroed the shared counter, so flush()/stop() hung): per-stream accounting.
• A2, major (the queue bound was per stream): the bound is now on the aggregate unwritten bytes.
• A3 / A4 / B2 / C2 (the cap leaked through a pending async open, uncounted markers, and oversized lines): a synchronous fd open sized from that fd, and every write is marker plus line and must fit.
• B1 / C1 (drops at the end of a run left no marker): close() writes it.
• B3 / B4 (the default cap, stop-closes, rotatedBytes, and fail-stays-off were unpinned): tests added.

Round 2

• C1, major (rejected lines rotated away kept events): fixed in 3e7e35e. The rotation marker is deterministic, so fit is decided before any rename, and a line that fits no file is dropped without rotating. The test uses the reviewer's one-line-cap sequence.
• A2, minor (the rotation marker bypassed the queue check): fixed. The marker counts against the queue.
• A1 and A3, test gaps: fixed. Per-stream accounting is pinned with the failure delivered synchronously while the live write is pending, and the marker-in-cap boundary is pinned. Both reviewer mutants are killed.
• Error handler as a no-op, surviving mutant: accepted as defense in depth. Node settles a destroyed stream's pending write callbacks itself, so the handler matters only for making the current file's failure turn the mirror off, which the unwritable-path test covers through the synchronous open. Kept.
• close() without flush(), surviving mutant: equivalent, per reviewer C: endStream drains before close. The flush is kept for clarity.
• B, declined to judge (the final drop marker can sit 65 bytes over the queue budget at close): accepted. It is at most one marker line, written once at teardown.
• src/transcript/* timeouts: seen locally at load average ~140, in code this PR does not touch. The package CI, on a clean runner, passes them.

Round 3 (final pass: A and C)

• A and C, the same minor (the close-time drop marker skipped the queue check, since a marker-only write has no line bytes, so one marker could sit over the bound): fixed in ceefb9c. close() drains the queue before writing the marker; a test pins the peak queue at close. Red on 3e7e35e. Not re-verified, because the step-7 cap was reached.
• Test design fix: the 64 MiB default test wrote about 70 MB and timed out once under load. It now pre-sizes the file sparsely to just under the default, and checks that one recorded event rotates it and one event less does not. The mutant setting the default to 65 MiB is killed.
• Surviving mutants restated by A and C: the error handler as a no-op (defense in depth; Node settles a destroyed stream's pending callbacks) and close() without its first flush() (equivalent, since endStream drains). Both accepted.

Steering q62 (after round 3)

• A marker-only write skipped the queue check (bytes === 0), so a configured cap smaller than one marker line was still exceeded: fixed in 6b8ca32. Every write, markers included, now fits the queue or is not written, and the drops stay counted in stats(). Pinned with a 1-byte cap; the mutant restoring the bytes > 0 exception is killed. Not re-verified by the reviewers (cap reached); the narrow arithmetic and test are listed here for the manager's inspection.

🤖 Generated with Claude Code

[Juliusolsson05]

Final addendum (manager). Round 3 was the last review pass. Reviewers A and C each found one minor issue: the close-time drop marker could exceed maxQueuedBytes. Fixed in ceefb9c (close drains before the marker). Steering q62 then found that a cap smaller than a marker line could still be exceeded; fixed in 6b8ca329: a marker that does not fit is not written, the drop stays counted in stats(), and the test pins maxQueuedBytes: 1. Under the final-pass cap, the manager verified this arithmetic by inspection, as q62 allows. Exact-head CI at 6b8ca329 is green. Merging.