Background
PR #916 introduced per-session `session.log` files at
`~/.netclaw/logs/sessions/{sanitized-session-id}/session.log`. The dispatcher
redesign in #918 made the actor the single writer to each file, but the file
itself has no size cap.
Problem
The daemon-global rolling log rolls at 10 MB
(`RollingFileLoggerProvider.MaxFileSizeBytes`) by writing to a date-stamped
file and rotating once the size threshold is crossed. `session.log` does not.
A long-lived session that emits high-volume diagnostics — for example a
streaming-token-heavy thread with debug logging enabled, or a model that emits
large `Thinking delta:` payloads on every token — can grow `session.log`
unbounded. Most lines are already truncated to 1000 chars via
`TextTruncation.EllipsisAppend` in `SessionLogActor`, but there is no
overall ceiling.
This is not a fire — disk usage is bounded by per-line truncation, session
lifetime, and idle eviction of the writer actor. But operators have no way to
predict the worst case, and a misbehaving session in a long-running thread
could fill disk over weeks.
Proposal
Add a size-based rotation policy to `SessionLogActor` analogous to the daemon
log rolling behavior:
- When `session.log` exceeds a configurable threshold (default 10 MB), rename
it to `session.{n}.log` (smallest available `n`) and start a fresh
`session.log`.
- Keep at most a configurable number of historical files per session
(default 5) to bound total disk per session.
- Optionally surface the rotation as a marker line in the new file
(`Session log rotated from session.{n}.log`) so operators reading the
current file see a back-reference.
Acceptance criteria
- `session.log` cannot exceed the configured threshold.
- Rotation count is bounded; oldest files are evicted when the cap is reached.
- Behavior is covered by a unit test that pumps enough output through the
dispatcher to trigger rotation and asserts the resulting file layout.
- Configuration surface is documented in `docs/spec/configuration.md` and
the `netclaw-operations` skill.
Reference
Background
PR #916 introduced per-session `session.log` files at
`~/.netclaw/logs/sessions/{sanitized-session-id}/session.log`. The dispatcher
redesign in #918 made the actor the single writer to each file, but the file
itself has no size cap.
Problem
The daemon-global rolling log rolls at 10 MB
(`RollingFileLoggerProvider.MaxFileSizeBytes`) by writing to a date-stamped
file and rotating once the size threshold is crossed. `session.log` does not.
A long-lived session that emits high-volume diagnostics — for example a
streaming-token-heavy thread with debug logging enabled, or a model that emits
large `Thinking delta:` payloads on every token — can grow `session.log`
unbounded. Most lines are already truncated to 1000 chars via
`TextTruncation.EllipsisAppend` in `SessionLogActor`, but there is no
overall ceiling.
This is not a fire — disk usage is bounded by per-line truncation, session
lifetime, and idle eviction of the writer actor. But operators have no way to
predict the worst case, and a misbehaving session in a long-running thread
could fill disk over weeks.
Proposal
Add a size-based rotation policy to `SessionLogActor` analogous to the daemon
log rolling behavior:
it to `session.{n}.log` (smallest available `n`) and start a fresh
`session.log`.
(default 5) to bound total disk per session.
(`Session log rotated from session.{n}.log`) so operators reading the
current file see a back-reference.
Acceptance criteria
dispatcher to trigger rotation and asserts the resulting file layout.
the `netclaw-operations` skill.
Reference