Module logging 

File logging (spec “Logging”): <home>/logs/serve-<pid>.log and pair-<pair-id>.log, level info (debug on request), a 5 MiB cap that rolls once to .1, and retention. Nothing here ever writes to stdout: stdout is the MCP channel.

Structs

CappedWriter

An append-only file that moves itself to <name>.1 (replacing any earlier one) before a write that would take it past the cap. Whole writes stay whole; there is never a .2.

Group 🔒

LogHandle

Keeps the log alive: dropping it flushes the worker and (Scoped) uninstalls the subscriber.

Enums

Kind 🔒

LogScope

Constants

KEEP_NEWEST

Retention: files beyond the newest 20 of their kind …

LOG_CAP_BYTES

The size at which a log file rolls to .1.

RETAIN_MAX_AGE_MS

… AND older than this.

Functions

classify 🔒

serve-<pid>.log[.1] / pair-<12 hex>.log[.1] -> (kind, id, is_rolled).

create_logs_dir 🔒

init_file_logging

Open path as a non-blocking, ANSI-free file log. Global installs the process subscriber with try_init (a second call returns a handle and leaves the first subscriber in place); Scoped installs a thread-local default whose guard lives in the handle.

mtime_ms 🔒

open_append 🔒

retain

Log retention (spec Logging). A base log and its .1 form one group of their kind (serve-* and pair-* are counted separately); a group is deleted only when it is beyond the newest 20 of its kind AND its newest file is older than 14 days AND its owner is gone: for serve-<pid> the pid is dead, for pair-<id> pair_is_dead(id). Decisions key on the FILE NAME’s id. Returns the files removed.

rolled_name 🔒