Source Atlas

Reading Contract: Use this atlas after the narrative is clear. Open pinned links to verify owners, boundaries, and evidence classes, not to reconstruct the story from scratch.

This atlas is the book’s source-audit index. All Codex links point to public GitHub code pinned to commit 569ff6a1c400bd514ff79f5f1050a684dc3afde3. The chapters should be readable without opening these links; the atlas exists so a reader can verify the book’s claims without hunting through the repository.

Audit rule: use an anchor to classify a claim. Direct type, function, constant, workflow, or test behavior counts as verified source. A boundary that emerges from several anchors counts as surrounding contract inference and should stay abstract in prose and figures. Anything that depends on private service internals is not visible and is intentionally absent from this atlas.

Chapter Anchors

Chapter 1: The Architectural Bet: Agent as a Bounded Operating System

• Runtime vocabulary: codex-rs/protocol/src/protocol.rs
• Operation enum: codex-rs/protocol/src/protocol.rs
• Event stream: codex-rs/protocol/src/protocol.rs
• Session facade: codex-rs/core/src/session/mod.rs

Chapter 2: From Distribution Wrapper to Rust Router

• npm launch wrapper: codex-cli/bin/codex.js
• Rust command router: codex-rs/cli/src/main.rs
• App command boundary: codex-rs/cli/src/app_cmd.rs
• App-server daemon commands: codex-rs/cli/src/main.rs

Chapter 3: Configuration, Authentication, and Managed Requirements

• Resolved permissions: codex-rs/core/src/config/mod.rs
• Permission compilation: codex-rs/core/src/config/permissions.rs
• Managed feature gates: codex-rs/core/src/config/managed_features.rs
• Public permission profile: codex-rs/app-server-protocol/src/protocol/v2/permissions.rs

Chapter 4: The Protocol Boundary

• Core submissions and events: codex-rs/protocol/src/protocol.rs
• App-server JSON-RPC envelope: codex-rs/app-server-protocol/src/jsonrpc_lite.rs
• V2 protocol families: codex-rs/app-server-protocol/src/protocol/v2/mod.rs
• Event-to-item mapping: codex-rs/app-server-protocol/src/protocol/event_mapping.rs
• Schema export: codex-rs/app-server-protocol/src/export.rs

Chapter 5: Threads, Sessions, and Durable State

• Thread manager boundary: codex-rs/core/src/thread_manager.rs
• Client-facing thread handle: codex-rs/core/src/codex_thread.rs
• Queue-pair runtime facade: codex-rs/core/src/session/mod.rs
• Model-visible history: codex-rs/core/src/context_manager/history.rs
• Accepted prompt recording: codex-rs/core/src/session/mod.rs

Chapter 6: The Turn Loop: Where the Agent Becomes an Agent

• Turn loop implementation: codex-rs/core/src/session/turn.rs
• Prompt hook ordering: codex-rs/core/src/session/turn.rs
• Accepted prompt recording: codex-rs/core/src/session/turn.rs
• Model client session: codex-rs/core/src/client.rs
• Context manager: codex-rs/core/src/context_manager/history.rs

Chapter 7: Model Providers, Streaming, and Backend Tasks

• Model client: codex-rs/core/src/client.rs
• Provider prompt shape: codex-rs/core/src/client_common.rs
• Model client session: codex-rs/core/src/client.rs
• WebSocket behavior tests: codex-rs/core/tests/suite/agent_websocket.rs
• Backend task API contrast: codex-rs/cloud-tasks-client/src/api.rs

Chapter 8: Observability: Capture Facts Before You Interpret Them

• Trace session model: codex-rs/rollout-trace/src/model/session.rs
• Codex turn trace model: codex-rs/rollout-trace/src/model/session.rs
• Runtime trace payloads: codex-rs/rollout-trace/src/protocol_event.rs
• Core event mapping: codex-rs/core/src/event_mapping.rs

Chapter 9: Tool Specifications, Routing, and Dispatch

• Tool spec enum: codex-rs/tools/src/tool_spec.rs
• Public planning entry: codex-rs/core/src/tools/spec.rs
• Tool spec planner: codex-rs/core/src/tools/spec_plan.rs
• Deferred MCP handler registration: codex-rs/core/src/tools/spec_plan.rs
• Tool router: codex-rs/core/src/tools/router.rs
• Tool payloads and outputs: codex-rs/core/src/tools/context.rs
• Tool registry: codex-rs/core/src/tools/registry.rs
• Parallel dispatch rules: codex-rs/core/src/tools/parallel.rs
• Dispatch trace adapter: codex-rs/core/src/tools/tool_dispatch_trace.rs

Chapter 10: Shell, Exec Server, and Filesystem Tools

• Shell handler request shaping: codex-rs/core/src/tools/handlers/shell/shell_handler.rs
• Shared shell execution path: codex-rs/core/src/tools/handlers/shell.rs
• Exec policy approval conversion: codex-rs/core/src/exec_policy.rs
• Unmatched command fallback: codex-rs/core/src/exec_policy.rs
• Tool orchestrator approval and attempt flow: codex-rs/core/src/tools/orchestrator.rs
• Sandbox denial retry branch: codex-rs/core/src/tools/orchestrator.rs
• Sandbox attempt transform: codex-rs/core/src/tools/sandboxing.rs
• Unified exec handler request binding: codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs
• Unified exec request shape: codex-rs/core/src/unified_exec/mod.rs
• Unified exec process manager: codex-rs/core/src/unified_exec/process_manager.rs
• Unified exec runtime adapter: codex-rs/core/src/tools/runtimes/unified_exec.rs
• Exec-server protocol methods and process output: codex-rs/exec-server/src/protocol.rs
• Exec-server client calls: codex-rs/exec-server/src/client.rs
• Remote process adapter: codex-rs/exec-server/src/remote_process.rs
• Executor filesystem handler: codex-rs/exec-server/src/server/file_system_handler.rs
• Remote filesystem sandbox forwarding: codex-rs/exec-server/src/remote_file_system.rs

Chapter 11: Patches as a First-Class Editing Protocol

• Patch handler struct and tool surface: ApplyPatchHandler, ToolHandler impl
• Handler verification and orchestration: ApplyPatchHandler::handle
• Shell interception path: intercept_apply_patch
• Patch grammar and hunk model: codex-rs/apply-patch/src/parser.rs
• Invocation verifier: maybe_parse_apply_patch_verified
• Patch safety assessment: assess_patch_safety
• Patch runtime: ApplyPatchRuntime::run
• Hunk application and committed delta: apply_hunks_to_files
• Turn diff tracker: codex-rs/core/src/turn_diff_tracker.rs

Chapter 12: Hooks and Human Approval

Hook Surfaces

• Legacy hook payload contrast: codex-rs/hooks/src/types.rs
• Protocol hook event names and run summaries: codex-rs/protocol/src/protocol.rs
• Hook list vs runnable handler model: codex-rs/hooks/src/engine/mod.rs
• Discovery, normalized hashes, and trust filtering: codex-rs/hooks/src/engine/discovery.rs

Runtime Hook Outcomes

• Pre-tool hook request, preview, block, and context recording: codex-rs/core/src/hook_runtime.rs
• Pre-tool outcome parser for block/context: codex-rs/hooks/src/events/pre_tool_use.rs
• User-prompt hook and additional-context recording: codex-rs/core/src/hook_runtime.rs
• Permission-request hook contract and decision fold: codex-rs/hooks/src/events/permission_request.rs

Approval, Sandbox, and Guardian Boundaries

• Approval protocol inputs and requests: UserInput, EventMsg
• Approval policy and decision enum: AskForApproval, ReviewDecision
• Permission hook before Guardian/user approval: ToolOrchestrator::request_approval
• Approval requirement before first sandbox attempt: ToolOrchestrator::run
• Sandbox-denial retry branch: ToolOrchestrator::run
• Guardian routing, fail-closed review, and constrained review session: codex-rs/core/src/guardian/review.rs

Chapter 13: Sandboxes, Network Policy, and Platform Boundaries

• Built-in and custom permission profile compilation: codex-rs/core/src/config/permissions.rs, compile_permission_profile
• Runtime filesystem and network policy vocabulary: codex-rs/protocol/src/permissions.rs
• Additional permissions and effective profile merge: codex-rs/sandboxing/src/policy_transforms.rs, effective_permission_profile
• Sandbox attempt handoff into transform: codex-rs/core/src/tools/sandboxing.rs
• Sandbox type selection and platform choice: codex-rs/sandboxing/src/manager.rs, select_initial
• Platform command transform: SandboxManager::transform
• macOS Seatbelt generation and restricted managed-network policy: codex-rs/sandboxing/src/seatbelt.rs, create_seatbelt_command_args
• Linux bwrap/seccomp execution and proxy routing: codex-rs/linux-sandbox/src/linux_run_main.rs, proxy_routing.rs
• Windows elevated setup, legacy limitation, and runner backend: setup.rs, legacy.rs, elevated.rs
• Windows identity, ACL, firewall, and WFP enforcement anchors: spawn_prep.rs, acl.rs, firewall.rs, wfp_setup.rs, wfp.rs, filter_specs.rs
• Network proxy environment, domain rules, and limited methods: proxy.rs, policy.rs, limited methods

Chapter 14: The App-Server Contract

• JSON-RPC-lite envelope and request/notification/response/error decoding: jsonrpc_lite.rs
• Transport mode parsing and connection normalization: transport/mod.rs, stdio.rs
• Generated client request scopes and serialization_scope(): common.rs
• Request conversion, initialize gate, experimental gate, and scoped dispatch: message_processor.rs
• Queue key mapping, FIFO draining, and shared-read batching: request_serialization.rs
• Thread state, listener commands, and server-request resolution command routing: thread_state.rs
• Listener task select loop and event tracking before projection: thread_lifecycle.rs
• Running-thread resume order, optional history/token replay, pending request replay, and conditional goal continuation: thread_lifecycle.rs
• Stateless event-to-notification projection boundary and representative item event cases: event_mapping.rs, event cases
• Generated server requests and typed response constructors, including dynamic tool call requests: common.rs, server request definitions
• Outgoing sender pending callbacks, response matching, unresolved request replay, and thread cancellation cleanup: outgoing_message.rs, send_request_to_connections, pending_requests_for_thread, cancel_requests_for_thread

Chapter 15: SDKs, Daemons, and Remote Control

Use this group as a surface map, not as proof that every client exposes the same contract. Transport, Python SDK, TypeScript process wrapper, daemon lifecycle, and remote control each own a different edge of the app-server boundary.

• Transport modes, listen URL parsing, transport events, and connection origin: transport/mod.rs
• Python SDK public facade, initialize metadata normalization, and generated thread_start: api.py
• Python SDK one-reader routing, response waiters, turn queues, pending turn replay, and fail_all: _message_router.py
• Python SDK run-result projection from stream notifications: _run.py
• TypeScript SDK Codex public API: codex.ts
• TypeScript SDK event parsing and run() collection: thread.ts
• TypeScript SDK process wrapper, resume, stdin input, stdout lines, and exit errors: exec.ts
• Daemon constants, lifecycle commands, start/restart/stop/version, bootstrap, readiness polling, and operation lock: app-server-daemon/src/lib.rs
• Daemon control-socket probe and app-server version extraction: client.rs
• PID backend reservation lock, process start, pid-file state reads, stale cleanup, and reservation lock acquisition: backend/pid.rs
• Remote-control start config, handle, initial status, and websocket runner: remote_control/mod.rs
• Remote-control client/server envelopes, chunk events, ack cursor, and URL normalization: protocol.rs
• Remote-control client tracker, stream-id fallback, remote-control connection origin, and outbound task: client_tracker.rs
• Remote-control websocket state, outbound buffer, connect/reconnect, writer replay, sequence assignment, chunk splitting, and sequence/segment ack handling: websocket.rs
• Remote-control segment limits, reassembly, out-of-order rejection, and invalid chunk drops: segment.rs

Chapter 16: The TUI as an Event Renderer

• TUI ownership surface for app state, select loop, terminal event handling, draw/resize, cursor, and external-editor handoff: app.rs, App::run, handle_tui_event
• Internal routing surface for app event bus, dispatcher, and runtime command boundary: app_event.rs, event_dispatch.rs, app_command.rs
• Runtime crossing surface for app-server session facade, turn start/steer, active-thread command routing, and request resolution: app_server_session.rs, turn_start, thread_routing.rs
• Conversation projection surface for chat widget ownership, protocol notification projection, outbound command submission, and assistant streaming: chatwidget.rs, chatwidget/protocol.rs, submit_op, flush_answer_stream_with_separator
• Focus and decision surface for bottom pane focus model, active views, and approval overlay: bottom_pane/mod.rs, as_renderable, approval_overlay.rs
• Pending request and scrollback surface for app-server request ledger, server-event routing, source-backed message consolidation, and resize reflow: app_server_requests.rs, app_server_events.rs, agent_message_consolidation.rs, resize_reflow.rs
• Rendering and consolidation tests: status_and_layout.rs, exec_flow.rs

Chapter 17: MCP: External Tools Without Runtime Entanglement

• MCP configuration: codex-rs/codex-mcp/src/mcp/mod.rs
• Connection manager: codex-rs/codex-mcp/src/connection_manager.rs
• MCP tool info: codex-rs/codex-mcp/src/tools.rs
• Core tool exposure: codex-rs/core/src/mcp_tool_exposure.rs
• Outbound Codex MCP server: codex-rs/mcp-server/src/message_processor.rs

Chapter 18: Skills, Plugins, Connectors, and Typed Extensions

• Skills manager: codex-rs/core-skills/src/manager.rs
• Skill metadata model: codex-rs/core-skills/src/model.rs
• Plugin manifest: codex-rs/core-plugins/src/manifest.rs
• Plugin manager: codex-rs/core-plugins/src/manager.rs
• Connector directory model: codex-rs/connectors/src/lib.rs
• Typed prompt extension API: codex-rs/ext/extension-api/src/contributors/prompt.rs

Chapter 19: External Migration and Backward Compatibility

• External config model: codex-rs/app-server/src/config/external_agent_config.rs
• Migration request processor: codex-rs/app-server/src/request_processors/external_agent_config_processor.rs
• TUI migration startup: codex-rs/tui/src/external_agent_config_migration_startup.rs
• Protocol compatibility surface: codex-rs/app-server-protocol/src/protocol/mod.rs
• Thread store: codex-rs/thread-store/src

Chapter 20: Multi-Agent Coordination

• Graph edge status: codex-rs/agent-graph-store/src/types.rs
• Local graph store: codex-rs/agent-graph-store/src/local.rs
• Agent trace reducer: codex-rs/rollout-trace/src/reducer/tool/agents.rs
• Session multi-agent integration: codex-rs/core/src/session/multi_agents.rs
• Multi-agent tool handlers: codex-rs/core/src/tools/handlers/multi_agents.rs

Chapter 21: Cloud Tasks, Identity, and Remote Work

• Cloud task API: codex-rs/cloud-tasks-client/src/api.rs
• HTTP backend client: codex-rs/cloud-tasks-client/src/http.rs
• Mock backend: codex-rs/cloud-tasks-mock-client/src/mock.rs
• Agent identity material: codex-rs/agent-identity/src/lib.rs
• Local diff discipline: codex-rs/core/src/turn_diff_tracker.rs

Chapter 22: Memories and User-Level State

• Memory usage kinds: codex-rs/memories/read/src/usage.rs
• Citation parser: codex-rs/memories/read/src/citations.rs
• Read-only MCP memory service: codex-rs/memories/mcp/src
• Stage 1 extraction: codex-rs/memories/write/src/phase1.rs
• Stage 2 consolidation: codex-rs/memories/write/src/phase2.rs

Chapter 23: Build Systems and Generated Contracts

• Cargo workspace: codex-rs/Cargo.toml
• Bazel module: MODULE.bazel
• Bazel crate macros: defs.bzl
• Bazel release-build verification: .github/workflows/bazel.yml
• App-server schema export: codex-rs/app-server-protocol/src/bin/export.rs

Chapter 24: Packaging, Release, and Native Dependencies

• npm wrapper package: codex-cli/package.json
• npm package builder: codex-cli/scripts/build_npm_package.py
• Native dependency installer: codex-cli/scripts/install_native_deps.py
• Cargo release build workflow: .github/workflows/rust-release.yml
• Release artifact staging: .github/workflows/rust-release.yml
• npm package staging: .github/workflows/rust-release.yml
• V8 dependency release surface: third_party/v8/README.md

Chapter 25: CI, Policy, and Architectural Governance

• Main CI workflow: .github/workflows/rust-ci.yml
• Full CI matrix: .github/workflows/rust-ci-full.yml
• Bazel verification workflow: .github/workflows/bazel.yml
• Blob-size policy: scripts/check_blob_size.py
• TUI/core boundary check: .github/scripts/verify_tui_core_boundary.py
• Cargo workspace governance: .github/scripts/verify_cargo_workspace_manifests.py

Epilogue: What to Steal

• protocol: protocol
• core session runtime: core session runtime
• app-server: app-server
• tool execution: tool execution
• rollout trace: rollout trace
• repository governance: repository governance

Reading Order

If you only have one hour for source audit, read in this order:

1. Submission, Op, Event, and EventMsg to learn the runtime vocabulary.
2. Codex, CodexThread, and ThreadManager to understand ownership.
3. session/turn.rs to see the turn loop, hook ordering, sampling, continuation, and completion.
4. Tool planning, routing, registry, and orchestration to see why tools are governed side effects rather than callbacks.
5. App-server message processing and TUI rendering to see how clients share the runtime.
6. Sandbox management, cloud tasks, memory write phases, and release workflows for the advanced subsystems.

Audit Rule

When a chapter and this atlas disagree, treat it as a book bug. The atlas is not a replacement for chapter narrative; it is the compact map that lets the narrative remain source-grounded without turning every chapter into a file listing.