fix: an unreadable file must not read as an absent one

[benmfzen]

Path.exists() returns False when the OS denies access — macOS TCC, unix permissions, an unmounted share. Used as a guard before a read, it turns "I may not read this" into "this does not exist", and the caller falls back to defaults with nothing in the output to say so.

Found in the field (2026-07-20). A sibling deployment reported an empty review folder while nine finished videos sat in it: the scan was guarded by exists() and the process had lost Documents access. The reported 0 was indistinguishable from a genuinely empty folder — acting on it would have meant reporting "nothing to schedule" against a full queue.

The same guard sits in front of this repo's own state:

Path	Silent consequence
plan.json	unreadable plan looks like no plan → scheduler books against built-in defaults
damping ledger	unreadable ledger looks like no history → series caps miscount
performance store	unreadable store looks like no data → damped planner sees an empty record
config.json	unreadable config looks like no config → silently runs on defaults

Change

Adds postpeer_pilot/safe_read.py. A read either returns content, returns None because the file genuinely is absent, or raises Unreadable. Callers that want a default now choose it explicitly, so the fallback is a decision in the code rather than an accident of the filesystem.

Applied to plan.active, plan.series_slots, plan.ledger_entries, plan.captions_by_post, perf.latest, the meta-token lookup in perf, config.load and config.api_key.

Tests

Five regression tests covering absent, present and chmod 000 paths — including that an unreadable plan and an unreadable config raise instead of quietly defaulting. Suite: 24 passed.

Behaviour for genuinely absent files is unchanged, so no caller needs updating.

🤖 Generated with Claude Code