# Runtime source agent guide
## Ownership and navigation
`lib.rs` declares runtime boundaries and intentional public exports; `bin/magi-code.rs` delegates to its entrypoint. Keep export changes explicit and extracted implementations behind their owning facade.
| Launch selection and validation | `cli/`, `commands/` |
| Turn provider selection and construction | `agent/runner/preparation.rs`, `providers/factory.rs` |
| Cargo updates, version checks, process bounds and restart | `updates.rs`, `updates/`; idle handoff: `tui/controller/app/updates.rs` |
| Frontend protocol and persistent coordination | `service/` |
| Title-provider orchestration versus durable recording | `session_titles.rs` versus `sessions/` |
| Summary provider work and separate checkpoint log | `summarizer.rs`, `summarizer/`; display: `tui/state/summary.rs` |
| Diff snapshots, comments and opt-in comments-only context | `diff_review.rs`, `diff_review/`; display: `tui/diff.rs`, `tui/diff/` |
| Display events versus projection | `output/` versus `rendering/`, `tui/` |
| Shared protected file access | `persistence.rs` |
| Neutral cancellation and lexical-path helpers | `cancellation.rs`, `path_utils.rs` |
- `PersistentService` is an intentional transport-independent public adapter. It owns the persistent coordinator thread; `service/unix.rs` adds the private Unix daemon adapter. Adapters supply transport capabilities and write outbound messages; reservation lifetimes belong to the service guide.
- Keep title-provider work outside session storage. Do not move durable or security-sensitive behavior into display modules.
- Reuse `persistence::open_regular_file` and `read_regular_file_bounded`: handle checks reject final symlinks and Unix FIFOs, but callers still own parent-path containment and byte limits. Lock renewal verifies ownership and updates time through the same handle.
- Shared cancellation/path helpers must not depend back on individual subsystems. CLI routing must not become a second provider, auth, tool, or session policy engine.
## Instruction loading
`instructions/mod.rs` owns startup source order and budgets; `instructions/subdir.rs` owns touched-path discovery. Both contain discovery tests.
- Load user `AGENTS.md`, explicit project-root `AGENTS.md`, then configured Markdown paths in listed order. Do not scan arbitrary ancestors or automatically load `CLAUDE.md`.
- Configured entries must be absolute `.md` paths; errors retain the indexed setting name. Startup limits are 256 KiB per file and 1 MiB combined. Missing optional guides are ignored; other startup read failures propagate.
- Touched-path discovery walks nearest-first, excluding the root guide and already-loaded canonical paths. Canonicalize root, touched path and candidates; an in-root link is allowed only when its target stays inside the root. Do not substitute the stricter skill/profile symlink policy.
- Local guides have a 256 KiB file cap. Return read/discovery diagnostics with successfully loaded guides. Preserve source kind, path and order; discovery only loads text, never executes it or writes memory files.
## Skill discovery
`skills/mod.rs` discovers descriptors; selected skill/reference reads belong to `tools/skill.rs`. Discovery tests cover precedence, shallow traversal, frontmatter, duplicates, enablement and unsafe sources.
- Scan `SKILL.md` in a skill directory or one grouping directory below the root, not arbitrarily deep. Collision priority is repository `.agents/skills`, configured additional roots, `$MC_HOME/skills`, then legacy `~/.agents/skills`.
- Additional roots must be absolute and are processed in listed order; later additional roots replace earlier same-name discoveries. Sort paths, diagnose within-root duplicates and retain deterministic `BTreeMap` output. Names come from containing directories, not frontmatter `name`.
- Reject non-regular descriptors, including symlinked `SKILL.md`; do not recurse through symlink directory entries. Descriptor reads have a 1 MiB cap; failures remain per-path diagnostics rather than aborting all roots.
- Frontmatter is flat key/value parsing, not general YAML. Preserve CRLF, scalar quoting and malformed-marker diagnostics. `filter_enabled_skills` removes disabled names; discovery is not an opt-in list.
- Discovery is separate from reference loading and execution; discovery never relaxes tool-level reference containment.
## Offline tool-output measurement
`tool_output_measurement.rs` owns reports, limits and aggregation. Private `tool_output_measurement/scanner.rs` owns discovery and held-handle stability checks; `tool_output_measurement/codecs.rs` owns extraction, projections and candidate selection. Keep their tests beside the implementations.
- Discover active primary and direct subagent sessions only. Distinguish discovery exclusions from selected files later unreadable or unstable.
- Open relative to held directory handles without following symlinks. Select using opened-handle identity/size; preserve discovery/open and scan-time signature checks rather than reopening paths.
- Select deterministically by newest modification time, then path. Enforce file-count, total-byte, per-file and per-line limits.
- Parse stored records with the session event schema. Tool results need valid identity/success fields and exactly one text field: `content` or legacy `output`.
- Compare baseline and candidates in the same Codex Responses-style tool-result item, preserving call identity and framing. Estimates are local token counts, not provider billing.
- JSON minification removes whitespace outside strings without reserializing values. Preserve number spelling, escapes and structure; validate complete JSON before and after transformation.
- Select only a unique candidate strictly smaller than baseline. Best ties or no improvement keep the original. Applicability, rejected/capped candidates and scan outcomes are not savings.
- These helpers are neither a public API nor a live compression path.