# Persistent coordinator guide
## Ownership
- `mod.rs` serializes admission, grants, snapshots, delivery, and settlement, delegating execution to `ServiceCoordinator` and the turn manager.
- `entrypoint.rs` exports `PersistentService`; its bounded loop continues with zero connections. Owner drop cancels/drains workers; disconnect does not cancel turns or settings.
- `wire.rs` owns v2 parsing, duplicate-key rejection, safe correlation, and fixed errors. `operations.rs` owns keyed intent digests and monotonic retention, never raw mutation payloads.
- `../application.rs` shares a bounded state lock with callback workers. `mod.rs` routes negotiated `application_resources_v1` methods and drains reliable executor events; ordinary v2 connections do not receive them. Normal agent persistence records dispatch identity before the callback.
- `source_capture.rs` owns the single source-registration preparation slot; `auth_work.rs` owns bounded auth status/readiness/logout work.
- `tests.rs` uses isolated stores and injectable service workers. Tool tests execute through `AgentSession`, not another agent loop. `application_profile_tests.rs` checks profile negotiation and rejection of retired tokens.
## Local contracts
- Queue claim response before later worker events; claiming never replays a prompt or started event. Request ids belong to connections; fresh internal legacy ids are not persistent turn identities.
- Reserve operation capacity before effects. Duplicate intent neither re-executes nor returns a grant. Settled records expire at 600 seconds and tombstones at 1200; unsettled records do not expire.
- Claims reserve generation space for revocation. Never wrap counters; worker sequence limits reserve terminal space in the session's remaining live range.
- Consume worker output independently of delivery. Drop only activity; reliable-output overflow disconnects slow clients.
- Claims use `Session::try_daemon_writer()` to expose daemon ownership to read-only lists; the lease, not the hint, governs admission. Unowned terminal actors detach after settlement; idle controlled actors retain their lease.
- Publish terminal and settle its operation before delivery. Retain persistence failures and authoritative accepted text in outcomes/snapshots. Join only finished workers during ordinary progress so cleanup cannot block unrelated sessions.
- Capture turn settings off-loop in one bounded preparation slot, excluding concurrent settings writes. Revalidate deadline, connection, grant, session, and operation before commit; workers use captured settings, not a fresh reload.
- Source capture has a separate single slot and 128 KiB staging reservation. Block other registrations, not listing/removal/Stop. Revalidate controller, operation, deadline, and registry before publication. Disconnect discards staged work; shutdown removes the slot before draining and joins without publication.
- `application_resources_v1` requires Unix transport. Reject retired `application_callbacks_inline_v1` and `application_callbacks_session_v1` tokens, including mixtures with the supported profile; reject retired inline turn contracts.
- Executor rotation retains one candidate verifier for 60 seconds. Old-proof resume cancels it; new-proof confirmation/resume promotes it.
- Login belongs to its initiating connection, not a session controller. Cancellation shares the protected commit lock and a committed exchange may win; disconnect must not affect another connection's login.
- Auth status/readiness/logout share one worker. Accepted logout survives disconnect and waits off-loop for Codex cancellation arbitration. Login generation capture and protected cancellation also stay on bounded workers.
Transport/security policy belongs in `../unix.rs`, not this core. The core contract is `../../../docs/features/persistent-service-core.md`; stdio framing remains in `../stdio.rs`.