JSONL is easy to underestimate. One object per line sounds like a format you can parse with a short loop. A live coding-agent transcript adds the cases that make that loop unsafe: a partial final append, an unusually large record, duplicate events, provider-specific envelopes, and old completion markers that later activity has invalidated.
Here is the defensive design we use before inferring session state.
Do not read an unbounded transcript into one string. Use a streaming reader and a documented line policy. Agent Island v1.7.1 currently uses different released safeguards on each platform: the macOS Claude reader has a 64 MiB backstop, while the Windows reader skips a line above 1,000,000 characters before parsing.
Those are not one shared limit. They are platform-specific policies with the same goal: one malformed or pathological record should not take down the rest of the scan.
Broad deserialization creates accidental dependencies on unrelated payloads. A monitor needs a smaller provider-aware projection.
For Claude, useful fields include type
, uuid
, timestamp
, message.stop_reason
, isSidechain
, isApiErrorMessage
, and toolEndsTurn
. For Codex, released readers inspect fields such as type
, payload.type
, payload.turn_id
, role
, timestamp
, completed_at
, and started_at
.
read bounded line
-> parse JSON
-> project provider-specific fields
-> attach identity and semantic time
-> reduce ordered events into state
A completion-shaped event belongs to one turn. A later user message or start event means the session moved on. The reducer must compare semantic order and allow later activity to supersede the older completion.
This is also why file modification time is not enough. One file can contain several turns, and the newest event may contradict an earlier stop marker.
A syntactically valid line can still be semantically wrong for a foreground alert.
Run provider-specific guards before the generic completion reducer.
Agent Island watches JSONL files for changes and keeps polling as a fallback. Event-driven observation reduces delay; polling recovers from a missed watcher notification. A partial line skipped now can be reconsidered after the next append.
Caching unchanged files by path, size, and modification time is useful, but the cache must invalidate when the source changes. Caching is an optimization, not permission to freeze an old state.
Safe JSONL parsing is bounded I/O plus provider-aware semantics, ordering, deduplication, and refresh behavior. The complete implementation notes and current scope are in the canonical guide.