Scan execution lifecycle
Scan execution turns an approved scan configuration into a supervised security run. It prepares durable run state, starts a sandbox with the target material and optional proxy or MCP support, drives a root agent with optional child agents, and then preserves enough state for resume while releasing runtime resources.
Execution model
The scan uses one coordinator as the source of truth for the agent tree, agent state, messages, active model streams, and resume data. The root agent owns the scan task. Child agents can run in parallel and report progress or terminal state back to their parent. See Runner lifecycle and scan inputs for the detailed control model and Runtime backends and sessions for runtime selection and session boundaries.
The lifecycle moves through these broad stages:
- Create or reopen the run record and coordinator state.
- Create or reuse the per-scan runtime and make the target workspace available.
- Connect optional run-scoped MCP servers and build the root execution context.
- Start the root agent and supervise agent turns, child work, messages, and limits.
- Settle active agents, persist state, and clean up the runtime when configured to do so.
The following diagram shows how a configured scan moves from start to either resume or cleanup.
flowchart TD
A[Configured scan] --> B[Create or restore run state]
B --> C[Create or reuse runtime session]
C --> D[Attach optional MCP services]
D --> E[Start root agent]
E --> F{Execution event}
F -->|Child work or message| G[Coordinate agent graph]
G --> F
F -->|Transient or recoverable error| H[Repair context or retry turn]
H --> F
F -->|Budget, rate limit, or interruption| I[Record resumable stop state]
F -->|Completion or terminal failure| J[Settle agent work]
I --> J
J --> K[Snapshot and close agent sessions]
K --> L{Cleanup enabled?}
L -->|Yes| M[Release runtime resources]
L -->|No| N[Leave runtime for later reuse or inspection]
References: strix/…/runner.py• L182-243 strix/…/runner.py• L315-324 strix/…/runner.py• L470-588 strix/…/runner.py• L640-659 strix/…/agents.py• L44-67
Run preparation
Run preparation gives each scan a stable identity and a durable place for state. A new scan creates its run and runtime-state directories. A scan with existing agent state becomes a resume operation instead of creating a second root agent. (strix/…/runner.py• L223-235, strix/…/runner.py• L274-313)
The preparation stage resolves the model and scan settings, restores notes and todos, and connects the coordinator to the agent snapshot. These steps make a resumed run continue with its prior work rather than only repeat its original target setup. (strix/…/runner.py• L247-272, strix/…/runner.py• L275-311)
The main durable artifacts have these roles:
| State | Purpose |
|---|---|
| Run directory | Groups files for one scan identity. |
| Agent snapshot | Restores the agent graph, statuses, pending messages, and stop counters. |
| Agent session database | Preserves each agent's model conversation. |
References: strix/…/runner.py• L223-235 strix/…/runner.py• L247-311 strix/…/paths.py• L8-23 strix/…/agents.py• L466-509
Runtime bring-up
Runtime bring-up creates the execution environment that agents use for shell, browser, and proxy-backed work. The session manager selects the named backend, maps local sources or uploads them into /workspace, stages optional files, and starts the sandbox before model work begins. (strix/…/runner.py• L315-324, strix/…/session_manager.py• L258-342)
The backend registry is an explicit boundary between scan orchestration and runtime resources. Docker is the built-in backend, and downstream runtimes can register their own backend with a declared bind-mount capability. An unknown backend name fails at startup instead of silently selecting a different runtime. (strix/…/backends.py• L17-18, strix/…/backends.py• L54-102)
When the Docker backend is selected, the runtime connects to the endpoint chosen by DOCKER_HOST, the active Docker context, or the default socket. Connection errors retain that endpoint source so a failed scan reports which Docker target could not be reached. (strix/…/docker_connection.py• L15-37, strix/…/docker_connection.py• L46-76)
The same scan identity reuses an existing session bundle when execution resumes or when a caller asks for the session again. Caido proxy setup starts during bring-up and is completed when the proxy handle is first needed. This keeps the scan's target workspace and network path tied to one per-scan runtime boundary. (strix/…/session_manager.py• L281-369)
Runtime choice changes how source material reaches the workspace. Local bind-mount backends expose host paths. Managed or remote backends receive manifest entries instead. Extra files use one archive and are unpacked as agent-writable files on either backend. Invalid paths and paths that overlap source trees or earlier extra files are skipped so supplied content cannot escape the workspace or replace source material. (strix/…/backends.py• L20-50, strix/…/backends.py• L79-102, strix/…/session_manager.py• L64-223)
The runner can also attach optional Model Context Protocol (MCP) servers for run-scoped external tools. It records non-secret connection status for interfaces and continues without a server that is missing or cannot connect. (strix/…/runner.py• L380-457)
References: strix/…/runner.py• L206-216 strix/…/runner.py• L315-324 strix/…/runner.py• L380-457 strix/…/session_manager.py• L258-369 strix/…/backends.py• L20-50 strix/…/backends.py• L54-102 strix/…/docker_connection.py• L46-90 tests/test_session_entries.py• L145-215
Agent supervision
Agent supervision keeps execution tied to explicit lifecycle actions rather than treating a model's plain text as completion. The root run starts with the configured task. Child runs use the same sandbox and model settings while keeping their own durable conversation sessions. (strix/…/runner.py• L470-588, strix/…/execution.py• L303-364)
The coordinator tracks a graph of agents and their runtime handles. It wakes agents for messages, can interrupt an active interactive stream, and sends terminal notices to parents so a parent does not wait for a child that can no longer report. (strix/…/agents.py• L246-299, strix/…/agents.py• L362-425, strix/…/execution.py• L924-948)
Interactive and autonomous scans use different supervision goals:
| Mode | Supervision behavior |
|---|---|
| Autonomous | A settled lifecycle action ends the run. A repeated turn without a lifecycle action fails the agent after bounded recovery attempts. A text-only final turn does not count as a completed scan. |
| Interactive | A parked agent waits for a user or peer message. An agent waiting on other agents can receive limited automatic resumes. |
References: strix/…/runner.py• L343-378 strix/…/runner.py• L470-588 strix/…/runner.py• L589-608 strix/…/execution.py• L186-300 strix/…/execution.py• L451-603 strix/…/execution.py• L643-719 strix/…/agents.py• L278-321
Retry and recovery
Recovery aims to preserve scan progress while separating repairable turn errors from scan-ending conditions. Before a turn, the system bounds image history and may compact the agent session. After a failure, it can remove rejected image content, compact an overflowing context, or replay a transient model request with backoff. (strix/…/execution.py• L657-686, strix/…/execution.py• L735-789)
If a model ends a turn without the required lifecycle action, supervision adds a direct prompt and tries again. Autonomous execution fails after its recovery limit. Interactive execution parks the agent and leaves it available for a new message. A failed or stalled child also sends a notice to its parent so the parent can account for unfinished work. (strix/…/execution.py• L465-570, strix/…/execution.py• L832-899)
Retries do not apply to every error. Budget limits stop the scan or its sub-agents. A persistent provider rate limit returns a stopped scan that can be resumed later. Other unrecovered errors mark the agent as failed or crashed and are raised in autonomous mode. (strix/…/execution.py• L719-812, strix/…/execution.py• L832-920, strix/…/runner.py• L589-639)
References: strix/…/execution.py• L122-150 strix/…/execution.py• L735-812 strix/…/execution.py• L832-920 strix/…/runner.py• L589-639
Interruption and resume
An interruption is treated as a pause in the scan's durable work, not as proof that the scan failed. User cancellation or keyboard interruption restores the root status to running, keeps the snapshot and model history available, and lets the next invocation reopen the same scan identity. (strix/…/runner.py• L628-633, strix/…/runner.py• L640-659)
Resume restores the coordinator from the agent snapshot and reopens the shared agent database. It finds the existing root, recreates eligible child runners, and can add a new resume instruction to the root conversation. Interactive agents that were not running are restored in a parked state. (strix/…/runner.py• L275-311, strix/…/runner.py• L530-570, strix/…/execution.py• L367-446)
The runtime session can also be reused by scan identity during this process. Cleanup is therefore a policy choice: cleanup-on-exit releases the runtime, while a retained session supports a later continuation path. (strix/…/runner.py• L315-324, strix/…/runner.py• L655-657, strix/…/session_manager.py• L281-284)
References: strix/…/runner.py• L275-311 strix/…/runner.py• L530-570 strix/…/runner.py• L628-659 strix/…/execution.py• L367-446
Cleanup boundary
Cleanup runs in the runner's final boundary after normal completion, interruption, budget stop, provider stop, or failure. It first stops descendant tasks before closing their model sessions. This order prevents a child from using a closed session while its last turn is still settling. (strix/…/runner.py• L640-649)
The runner then closes run-scoped MCP sessions and snapshots the coordinator before optional runtime teardown. Runtime cleanup removes the cached bundle, closes the proxy handle, deletes the sandbox session, and closes the local client when supported. Cleanup errors are logged rather than allowed to block the next scan. If cleanup is disabled, the runtime remains available for later reuse and may require normal runtime reaping if it is no longer needed. (strix/…/runner.py• L650-658, strix/…/session_manager.py• L381-416)
References: strix/…/runner.py• L640-659 strix/…/agents.py• L374-394 strix/…/session_manager.py• L381-416 tests/test_runner_teardown.py• L60-93
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to scan identity or resume artifacts must stay aligned between run paths, the coordinator snapshot, and the agent session database.
- Changes to agent status or stop behavior must preserve parent notices and the rule that descendant work settles before session closure.
- Changes to backend selection or Docker endpoint resolution must keep source delivery, bind-mount support, and connection diagnostics aligned.
- Changes to cleanup timing must preserve session-cache reuse and the option to retain a runtime for resume.
- Changes to retry classification must keep budget stops and user interruptions distinct from provider or agent failures.
- Changes to run-scoped MCP connections must preserve fail-open startup and non-secret status reporting for interfaces.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Agent state exists but the session database is missing | Resume stops before execution because model history cannot be restored. | Require both the snapshot and database before restoring. |
| A model turn ends without a lifecycle action | The run does not silently finish. The agent receives bounded recovery prompts or parks/fails. | Drive completion through explicit lifecycle actions. |
| A child ends without notifying its parent | The parent can wait for work that will never report. | Send one terminal or stall notice for each child. |
| The configured runtime backend is unknown | Scan startup fails instead of using an unintended runtime. | Require an exact registered backend name. |
| The selected Docker endpoint cannot be reached | Runtime bring-up fails before agent work starts. | Report the endpoint source and root connection cause. |
| Cleanup starts while a child turn is active | The child can fail while using a closed session. | Cancel and await descendants before closing sessions. |
| Runtime cleanup cannot delete the sandbox | A stranded runtime can remain after the scan. | Log the error and rely on later runtime reaping. |
| A persistent model rate limit occurs | The scan stops without a result and needs a later resume. | Mark the root stopped and include the scan identity in the resume hint. |
| An MCP server is absent or cannot connect | The scan starts without that external tool service. | Treat MCP setup as optional and continue with the remaining run. |
Key files
| File | Why to read it |
|---|---|
| strix/…/runner.py | Primary scan lifecycle from run preparation through supervision, optional service attachment, and final cleanup. |
| strix/…/agents.py | Coordinator model for agent state, messages, snapshots, stops, and descendant cancellation. |
| strix/…/execution.py | Agent turn supervision, child startup, retry policy, and failure settlement. |
| strix/…/session_manager.py | Per-scan runtime creation, source delivery, extra-file staging, proxy setup, reuse, and cleanup. |
| strix/…/backends.py | Backend selection, registration, and the contract for local versus managed runtime resources. |
| strix/…/docker_connection.py | Docker endpoint selection and connection errors for the built-in local runtime. |
| strix/…/sessions.py | Durable agent conversation sessions and safe session access during concurrent work. |
| strix/…/paths.py | Stable run and runtime-state locations used by start and resume. |
| docs/…/scan-modes.mdx | User-facing scan modes that shape the configured execution depth. |
| tests/test_runner_interrupt.py | Guarantees that interruption remains resumable while real crashes remain failures. |
| tests/test_runner_teardown.py | Guarantees that live child work settles before scan teardown. |