---
title: "Behavioral spec: runtime/launch.rs"
---
import RepoFile from '../../../../components/RepoFile.astro'

**Status**: Open — Phase 1, no confirmation needed

## Problem

<RepoFile path="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 <RepoFile path="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

<RepoFile path="src/runtime/launch.rs" /> — specifically the `load_agent_with` helper.
