# Persistent coordinator guide
## Ownership
- `mod.rs` serializes connection admission, grants, snapshots, delivery, and worker settlement. It delegates domain operations to the existing `ServiceCoordinator` and turn manager.
- `entrypoint.rs` exports `PersistentService`; its bounded command loop continues with zero connections. Owner drop cancels/drains workers; connection disconnect does not cancel turns or settings.
- `wire.rs` owns v2 request/control parsing, duplicate-key rejection, safe response correlation, and fixed error projection.
- `operations.rs` owns keyed intent digests and monotonic retention. Never retain raw mutation payloads here.
- `tests.rs` uses isolated stores and injectable normal service workers. Tool tests execute through `AgentSession`, not a second agent loop.
## Invariants
- Queue claim response before later worker events; never replay a prompt or started event on claim.
- Request IDs belong to connections. Internal legacy request IDs are fresh and never used as persistent turn identity.
- Reserve operation capacity before effects. Duplicate intent never re-executes or returns a grant. Settled records expire at 600 seconds, tombstones at 1200; unsettled records never expire.
- Claim reserves generation space for revocation. Never wrap counters. Worker sequence limits reserve terminal space within the session's remaining live range.
- Consume worker output independently of client delivery. Drop only activity; disconnect slow clients on reliable-output overflow.
- Retain the writer lease through persistence and worker exit. Only join finished turn workers during normal progress; cleanup must not block unrelated sessions.
- Persistent claims acquire `Session::try_daemon_writer()` so read-only session lists can identify daemon ownership. The writer lease, not that hint, controls admission. Unowned terminal actors detach only after worker settlement; idle controlled actors keep their lease.
- Persistent sinks ask the normal agent runner to join title-writing workers, even on cancellation. Do not restore print-mode detachment for exclusive-writer turns.
- Publish terminal and settle its operation before delivery. Preserve failed persistence and authoritative accepted text in retained outcomes/snapshots.
- Capture turn settings off the command loop in the single bounded preparation slot; exclude overlapping settings writes. Before commit, revalidate deadline, connection, grant, session, and operation. Keep provider definitions and startup resources fixed.
- Login belongs to its initiating connection, not a session controller. Cancellation shares the protected auth commit lock; committed exchange may win. Disconnect must not affect another connection's login.
- `auth_work.rs` bounds status/readiness/logout to one worker. Accepted logout survives disconnect and waits for Codex cancellation arbitration before removal. Keep those waits off the command loop; login generation capture and protected cancellation also run on bounded workers.
No Unix transport, singleton launch policy, or CLI mode is implemented here. Keep stdio version 1 unchanged. The adapter contract and integration limits are in `docs/features/persistent-service-core.md`.