Behavioral spec: runtime/launch.rs

Status: Open — Phase 1, no confirmation needed

Problem

src/runtime/launch.rs is the jackin load critical path — now 7575L total (was ~5494L at original analysis — 38% growth). It is targeted for a structural split. Without a behavioral spec, there is no oracle to verify that a refactor preserved the launch pipeline, auth checks, workspace materialization, and post-attach cleanup rules.

The file has grown significantly due to: instance identity support, Kimi agent runtime, expanded error reporting with mode traces, and additional test coverage.

Verified invariants

INV	Description	Verify by
INV-1	Trust confirmation still happens before the image build — an untrusted third-party agent may be cloned/resolved, but not built or launched until confirmed	confirm_agent_trust closure runs before build_agent_image in load_agent_with
INV-2	Token mode still fails fast before auth state preparation and runtime startup — missing CLAUDE_CODE_OAUTH_TOKEN aborts before DinD/network launch	verify_token_env_present runs before AgentState::prepare / launch_agent_runtime
INV-3	Container slot claim happens before the launch summary is printed so the operator-visible container name is the final locked name	claim_container_name runs before build_config_rows and the claimed name flows through launch_agent_runtime
INV-4	Foreground attach finalization still runs before teardown classification — isolated worktrees are finalized before deciding whether to preserve or clean the container	finalize_foreground_session happens before the inspect_container_state(...) cleanup match
INV-5	Cleanup classification still preserves restartable sessions and tears down clean exits	Running / crash paths disarm cleanup; clean exit runs cleanup
INV-6	render_exit still runs on both success and error exits from load_agent_with	both Ok(_) and Err(error) arms call render_exit

Pipeline overview

load_agent (public API) → load_agent_with (current pipeline):

1. Resolve source + trust — resolve repo state, then confirm untrusted agents
2. Resolve/claim instance — resolve restore candidates, then claim the final container name/slot
3. Resolve launch inputs — print the launch summary with the claimed name, then resolve manifest env, operator env, auth mode, and diagnostics
4. Build + prepare state — build the image, prepare auth state, isolated mounts, cache/state dirs
5. Launch + finalize — start runtime, attach, finalize worktrees, classify teardown/preservation

Steps

1. Create docs/src/content/docs/internal/specs/runtime-launch.mdx (once Developer Reference setup exists).
2. Frontmatter: title: "runtime/launch.rs — Behavioral Spec", spec_type: behavioral, subsystem: runtime.
3. Sections: Purpose, pipeline overview, behavioral invariants (INV-1 through INV-6), testing notes.
4. Note the current test seams: LoadOptions.op_runner, LoadOptions.host_env, and the injected confirm_trust closure passed into load_agent_with.

Why this must come before the split

The spec is the verification oracle. If src/runtime/launch.rs is split before the spec exists, there is no contract against which to verify the split preserved all invariants. At 7575L, this file is the single most error-prone split in the entire roadmap.

Key file

src/runtime/launch.rs — specifically the load_agent_with helper.