# Application service agent guide
Local frontend protocols expose session attachments/replay, streamed turns, authentication, and configuration. Contracts: `../../docs/features/application-service.md`, `../../docs/features/unix-daemon.md`, and `../../docs/features/application-resources.md`.
## Where to look
| Envelopes, identities, limits, encoding | `protocol.rs` |
| Initialization, capabilities, readiness, request guards | `dispatcher.rs` |
| Routing, worker queue, turn lifecycle | `coordinator.rs` |
| Connections, grants, snapshots, operation retention | `persistent/` |
| Resource contracts, registry, source capture, evidence | `application.rs`, `application_registry.rs`, `application_source.rs`, `application_evidence.rs` |
| JSONL framing and shutdown drain | `stdio.rs` |
| Unix endpoint security, launch/stop | `unix.rs`, `unix/connect.rs` |
| Startup resources and settings reload | `runtime.rs` |
| Turn admission, ordered sinks, terminal persistence | `turns.rs` |
| Allowlisted activity DTOs and bounded summaries | `activity.rs` |
| Explicit/implicit attachments and close | `sessions.rs` |
| Login coordination and logout | `auth.rs` |
| Catalog projections and scoped writes | `configuration.rs` |
## Protocol and execution contracts
- Adapters own framing/output; `ServiceCoordinator` owns routing and execution. Unix control handshakes never register persistent clients. Preserve atomic idle stop, peer UID checks at both ends, lifetime lock inodes, and explicit launch context; timeout is not stale-cleanup authority.
- Stdio retains each `ServiceOutbound` through encoding, write, and flush, then calls `finish_worker_output` after the attempt. Persistent coordination instead settles finished workers before terminal delivery.
- Encode an entire batch before writing. Encoding failure must not emit a replacement response or lose correlation; physical writes may still fail partway.
- Preserve acceptance → `turn.started` at sequence 0 → interleaved assistant/activity → exactly one `turn.terminal`. Main/child activity share the sequence lock. Stamp before enqueue, count activity drops, and close admission before terminal stamping; a cancellation response is not completion.
- Validate accumulated assistant text against the encoded terminal envelope before accepting a delta; never silently truncate. Reserve sequence/counter overhead. Terminal `assistant_text` is authoritative.
- Activity is nonblocking, lossy, and not replayed. Gaps and terminal `activity_dropped` report enqueue failures. `activity.rs` hashes identities and omits arguments/results, arbitrary labels, child previews, and raw metadata; preserve nullable status and parent correlation.
- Reasoning summaries require `provider_reasoning_summary` and verified provider-summary provenance, not generic thinking events. Preserve UTF-8 bounds and redacted/truncated flags without promising perfect secret removal.
- Explicit attachments survive turns; implicit/closing attachments release after terminal handling and worker cleanup. Both sinks must wait for title workers before releasing the writer lease. Active close returns `closing` and cancels; idle close is idempotent and never deletes history or releases another process's lease.
- Delegate list/replay to `../sessions/frontend.rs`; replay is read-only and needs no attachment. Preserve page/scan/attachment limits, stale-prefix resync, gap reporting, and encoded payload bounds. Durable cursors are not live event ids.
- For parseable malformed records, check safe request ids for duplicates before decoder errors; rejecting a duplicate must not release the original reservation.
## Auth, configuration, and adapters
- Initialized `status` reloads effective selection and checks current auth readiness without refresh, writes, or network. Provider definitions remain the startup snapshot; failures use fixed sanitized errors.
- Auth has one login flow, protected-cancellation worker, bounded progress queue, and transient manual callback. OAuth remains in `../login.rs`; protected commits/generations remain in `../config/`. Authorization URLs are transient; never echo callback input or underlying provider errors. Logout only removes local credentials.
- Serialize all five catalog/config routes through one configuration worker and retain its request guard through output. Cache reads are allowlisted/bounded; only explicit `catalog.refresh` discovers models.
- Scoped writes delegate to `config::update_settings_checked`, validate fresh catalog choices, and preserve unknown fields, project pins, and global-only fast mode. Do not expose arbitrary settings writes.
- Stdio workers reload selection, reasoning, and fast settings; running turns retain their snapshot. Persistent admission captures settings separately; see `persistent/AGENTS.md`. Neither path rebuilds startup instructions/skills or provider definitions per turn.
- Unix-only `application_resources_v1` is the sole resource profile. Registration pins bounded source snapshots and revision authorizations; keep proofs and paths out of history/provider payloads. Accepted manifests are immutable across claim/terminal/lookup; ordinary v2 omits them. Admission and workers share `protocol::persistent_assistant_budget`; call evidence has its own budget.
- Stdio stdout is JSONL only. EOF cancels turns/login and drains workers; output failure continues cleanup without more writes. Persistent disconnect and owner shutdown have different lifetimes, described in the child guide.
- Keep turns on the normal agent path. Capabilities exclude approvals, steering, MCP server lifecycle, raw tool output, and activity replay.
- Extend existing lifecycle, ordering, privacy, lease, framing, and payload-limit tests. Unix process coverage is in `../../tests/unix_daemon_process.rs` and `unix/survival_tests.rs`; synthetic survival does not establish Linux cgroup survival or cross-UID behavior.