Runner lifecycle and scan inputs
The runner is the control layer for one Strix scan. It turns verified targets and user instructions into an agent run, keeps root and child agents tied to durable state, and brings the run to a safe end after completion, interruption, or failure. See Scan execution lifecycle for the system-wide view and Runtime backends and sessions for sandbox and runtime resource ownership.
Execution model
Scan orchestration
The scan runner coordinates the whole engagement from run setup to teardown. It prepares a run record and state area, restores prior agent state when needed, starts the runtime session, connects optional MCP services, creates the root agent, and drives the root execution loop. Child agents use the same scan controls while keeping their own task and session.
The normal execution path follows this sequence:
flowchart TD
A[Verified scan inputs] --> B[Run state and logging]
B --> C[Runtime session]
C --> D[Root agent and session]
D --> E[Agent turns and child agents]
E --> F{Lifecycle result}
F -->|finish| G[Persist final report]
F -->|wait or user input| E
F -->|budget, interrupt, or failure| H[Settle state]
G --> I[Cancel descendants and close sessions]
H --> I
I --> J[Release runtime resources]
The root agent is the scan owner. It must use the final scan action to persist the customer-facing report. A child agent instead sends a completion report to its parent. The runner treats a plain text turn as unfinished work so that a scan does not appear complete without an explicit lifecycle action. Optional MCP connections add external tools to the run, but a missing or failed connection does not stop the scan.
References: strix/…/runner.py• L182-217 strix/…/runner.py• L274-323 strix/…/runner.py• L343-482 strix/…/runner.py• L503-588 strix/…/runner.py• L609-659 strix/…/execution.py• L451-570 strix/…/tool.py• L82-106 strix/…/tools.py• L518-636
Scan inputs
Scan inputs define both what the agent may assess and what information it may use. The root task presents repositories, local codebases, web applications, IP addresses, and API specifications as distinct target classes. User-provided workspace files remain read-only context. They do not become targets or instructions.
The input model keeps authority clear:
| Input | Role in the scan |
|---|---|
| Verified target | Defines authorized assessment scope |
| API specification | Defines API operations and can authorize its declared base URLs |
| Working directory mount | Gives the agent a place to work without granting assessment scope |
| Workspace file | Supplies read-only data for the task |
| User instruction | Adds task guidance but cannot expand verified scope |
| Diff scope | Narrows code review work to changed files and gives deleted files context-only status |
| Extra workspace file | Adds run data at a workspace path without changing assessment scope |
The runner builds a separate scope context for the system prompt. This prevents an instruction or a mounted directory from silently changing the authorized target set. A resume keeps the same scan inputs and can add a new resume instruction as a fresh user message. Root-only prompt additions remain subordinate to the verified scope, while child agents receive the standard scan context.
References: strix/…/inputs.py• L39-105 strix/…/inputs.py• L108-190 strix/…/inputs.py• L193-244 strix/…/runner.py• L204-217 strix/…/runner.py• L378-382 strix/…/runner.py• L459-501 strix/…/runner.py• L549-570
Path and workspace handling
Path handling gives each scan a stable local identity and a predictable workspace view. The run name maps to a directory under strix_runs; its state area holds the agent snapshot and session database used for resume. Preparation attaches cloned repositories, local sources, staged API specifications, optional workspace mounts, and extra files to workspace paths before the runtime starts.
The working directory mount has a deliberate boundary. It is available for work but is excluded from authorized targets and diff context. This lets an instruction-driven run operate on a directory without treating every file in that directory as an asset to test.
References: strix/…/paths.py• L8-28 strix/…/scan_setup.py• L164-220 strix/…/scan_setup.py• L239-267 strix/…/runner.py• L223-235 strix/…/runner.py• L315-322 strix/…/runner.py• L328-338
Lifecycle control
Lifecycle state
The coordinator is the single source of truth for agent graph state, runtime handles, mailboxes, errors, and resume snapshots. Each agent has a parent relationship and a state that tells the runner whether it should execute, wait, stop, or report a terminal result.
| State | Meaning |
|---|---|
running | The agent may take another execution turn |
waiting | The agent is paused for a user or another agent |
completed | The agent finished its assigned work |
stopped | The agent ended before completion by limit or control action |
failed | The agent ended with a handled execution error |
crashed | The agent ended with an unexpected error |
budget_paused | An interactive agent waits for the user to extend the budget |
State changes wake relevant runtimes and are written to the coordinator snapshot. The parent receives one terminal notice when a child cannot provide its normal completion report. This prevents a parent from waiting for work that can no longer finish.
References: strix/…/agents.py• L25-65 strix/…/agents.py• L149-169 strix/…/agents.py• L246-299 strix/…/agents.py• L466-530 strix/…/execution.py• L924-985
Hook controls
Run hooks connect each model turn to usage accounting and scan limits. Before a turn, they add warnings as the turn or shared cost budget approaches its limit. After a turn, they record model usage and enforce the applicable limit.
Autonomous scans stop at the shared cost limit. They stop child agents at a reserve threshold so the root agent can still produce its final report. Interactive scans pause at the limit instead. A user message can extend the budget and wake paused agents. The same rules are recomputed when a scan resumes so old state does not grant an incorrect budget.
References: strix/…/hooks.py• L32-57 strix/…/hooks.py• L114-141 strix/…/hooks.py• L142-178 strix/…/hooks.py• L180-223 strix/…/hooks.py• L225-273 strix/…/runner.py• L369-377 strix/…/runner.py• L287-298
Session-bound execution
Each agent is bound to a durable SDK session. The session preserves the agent's conversation and task input, while the coordinator controls when messages enter that session and when an active stream may be interrupted. Root and child sessions share the scan's session database but use separate agent identities.
Messages from users and peers enter a mailbox first. The coordinator drains that mailbox into the target agent's session before the next run cycle. This separates delivery and execution, which lets an interactive user wake a waiting agent or interrupt its current turn without losing the conversation history. A child receives its inherited context and task as one new user message, which keeps the child identity and task distinct from the parent conversation.
References: strix/…/sessions.py• L27-57 strix/…/agents.py• L278-360 strix/…/execution.py• L186-238 strix/…/execution.py• L988-1046 strix/…/inputs.py• L338-373 strix/…/tool.py• L17-114 strix/…/tools.py• L231-404
Recovery behavior
Turn recovery
The execution loop requires an explicit lifecycle tool call to settle a turn. If an agent returns text without such a call, the runner adds a focused continuation request and retries within a bounded recovery count. An autonomous agent that exhausts this count becomes crashed. An interactive agent is parked so a human can send a message to unblock it.
Waiting has two forms. A user wait has no automatic resume because only a user can provide the needed input. A wait for other agents can resume when a message arrives, but repeated idle resumes are capped so a stalled graph does not spend turns forever.
References: strix/…/execution.py• L451-570 strix/…/execution.py• L573-603 strix/…/agents.py• L198-244 strix/…/tool.py• L104-114 strix/…/tools.py• L347-375
Failure recovery
The runner distinguishes recoverable request problems from scan-ending errors. It can retry transient provider or network errors with backoff, remove rejected images from a session, or compact an overflowing context before it tries the turn again. A failed streamed turn is salvaged into the session when possible so a later resume retains the work already produced.
Permanent provider refusals and other unrecoverable errors settle the agent and notify its parent. A user interrupt is different: it leaves the root in running state and re-raises the interruption so the saved run can resume. A real crash marks the root as failed.
References: strix/…/execution.py• L122-174 strix/…/execution.py• L643-815 strix/…/sessions.py• L101-174 strix/…/sessions.py• L177-214 strix/…/runner.py• L610-639 tests/test_runner_interrupt.py• L64-108
Teardown sequence
Teardown protects both active work and runtime resources. The runner first cancels descendant tasks, then closes agent sessions and optional MCP sessions, writes the last coordinator snapshot, and releases the sandbox when cleanup is enabled. This order prevents a child from using a session after the session has closed.
Cleanup runs for normal completion, budget stops, interruptions, and failures. Interactive waiting can keep the scan resumable, while explicit cleanup controls whether the runtime is released at the end of that invocation.
References: strix/…/runner.py• L640-659 strix/…/agents.py• L374-394 strix/…/test_runner_teardown.py• L60-93
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the target task text and scope context aligned. A new target type must appear in both the agent-facing task and the authorization context.
- Preserve the distinction between workspace mounts, workspace files, extra workspace files, and authorized targets when changing input preparation or resume records.
- Keep root instruction overrides subordinate to the verified scope. Do not let extra prompt context replace built-in authorization keys.
- Keep terminal lifecycle tools aligned with runner recovery. A new terminal action must settle state and prevent parents from waiting for a report that will not arrive.
- Keep coordinator snapshot fields compatible with resume logic. State, mailbox, wait reason, and recovery counters affect whether agents restart or remain parked.
- Preserve the ordering of descendant cancellation, session close, snapshot, and runtime cleanup. Reordering these steps can lose history or leave a child using a closed session.
- When changing budget behavior, update both hook decisions and resume-time budget flag reconstruction so interactive and autonomous scans keep their distinct controls.
- Keep optional MCP connection setup fail-open and keep its status output non-secret. Connection status must stay consistent for both live interfaces and resumed run viewers.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A root turn ends without the final lifecycle action | Autonomous execution may exhaust recovery without producing the final report | Require an explicit lifecycle tool and bound continuation attempts |
| A child stops without a completion report | The parent can wait for a message that will never arrive | Send one terminal notice for every terminal child state |
| A mounted working directory or extra file is treated as a target | The agent may assess data outside the verified scope | Keep workspace inputs outside target records and scope authorization |
| A provider rejects the current session input | The same invalid history can fail every retry | Strip rejected images and retry only within the recovery bound |
| A transient provider or network error interrupts a streamed turn | A useful turn can be lost or the scan can fail too early | Retry transient errors with bounded backoff and salvage stream history |
| A child reaches the autonomous budget reserve | The root may lack cost or turns to write its final report | Stop child work before the shared hard limit |
| A user interrupt is recorded as a failure | Resume can be blocked or report the wrong scan state | Preserve running for interruption and use failed for real crashes |
| Descendant sessions close before descendant tasks stop | Active children can crash while writing their last history | Cancel and await descendants before closing sessions |
| An MCP server fails during setup | Optional external tools are unavailable, but the scan must still run | Treat MCP setup as optional and continue without failed connections |
Key files
| File | Why to read it |
|---|---|
| strix/…/runner.py | Primary scan coordinator from run setup through final cleanup |
| strix/…/execution.py | Agent turn lifecycle, child runners, waiting, and recovery policy |
| strix/…/inputs.py | Target task, scope authorization, workspace context, and child input rules |
| strix/…/agents.py | Agent state, parent graph, mailboxes, snapshots, and stop control |
| strix/…/hooks.py | Turn usage, cost limits, warnings, pauses, and budget stops |
| strix/…/sessions.py | Durable per-agent history and safe session rewrites |
| strix/…/scan_setup.py | Target preparation, path mapping, diff scope, and persisted run inputs |
| strix/…/tool.py | Root completion contract and final report handoff |
| strix/…/tools.py | Child creation, completion reports, waiting, and graceful stops |