Shared execution controller orchestrating CLI adapter lifecycles, sessions, and events.
Remarks
Lifecycle & Architecture Contract
Provider Resolution & Policy Governance: Dynamically resolves the active CLI backend
via resolveBackend (Codex, agy / Gemini CLI, or Claude Code). A model the governance
policy prices as expensive, unknown or approximate (consentFor), requested or the
backend's default, runs only after the user approves it through ConsentPrompt;
without one the turn fails with POLICY_DENIED.
Price Limit (AX-002): output_price_below is checked for the concrete model, separately
from consent, before the user is asked and again right before the session is acquired;
a model without a verified price below the limit fails with PRICE_LIMIT, never
replaced by another. Without a named model, routing and selection choose one that meets it.
Turn Mutual Exclusion & Lease Tokens: Sessions are acquired with unique turn tokens
(acquireAndResolveSession). A single session handle cannot execute concurrent turns; attempts
receive SESSION_BUSY.
Streaming Events & Best-Effort Archive: Emits normalized AdapterEvent updates to an append-only
HistoryWriter flushed periodically every 250ms and finalized on turn_finished.
Progress Heartbeats: Reports granular activity updates (onProgress).
If no events arrive within 10 seconds, background heartbeats notify the orchestrator with
elapsed seconds and active phase.
Defensive Protocol Validation: Validates adapter terminal results (TerminalExecutionResult).
Contradictory or missing results fail safely as PROTOCOL_ERROR, discarding untrusted output.
State Envelope Gate Enforcement: Evaluates review-only reported verdicts
via evaluateStateEnvelopeGate, returning structured review evaluation in TaskExecutionResult.
The review handler supplies completeness, snapshot identity and check requirements;
this does not independently prove a model's PASS claim or release artifact hashes.
Timing Scope: Single monotonic execution budget wraps the complete task lifecycle
(Git collection, preparation, consent, session acquisition, CLI execution, and teardown).
The adapter receives the monotonic remaining time, not a static process timeout.
Shared execution controller orchestrating CLI adapter lifecycles, sessions, and events.
Remarks
Lifecycle & Architecture Contract
resolveBackend(Codex, agy / Gemini CLI, or Claude Code). A model the governance policy prices as expensive, unknown or approximate (consentFor), requested or the backend's default, runs only after the user approves it through ConsentPrompt; without one the turn fails withPOLICY_DENIED.AX-002):output_price_belowis checked for the concrete model, separately from consent, before the user is asked and again right before the session is acquired; a model without a verified price below the limit fails withPRICE_LIMIT, never replaced by another. Without a named model, routing and selection choose one that meets it.acquireAndResolveSession). A single session handle cannot execute concurrent turns; attempts receiveSESSION_BUSY.AdapterEventupdates to an append-onlyHistoryWriterflushed periodically every 250ms and finalized onturn_finished.onProgress). If no events arrive within 10 seconds, background heartbeats notify the orchestrator with elapsed seconds and active phase.TerminalExecutionResult). Contradictory or missing results fail safely asPROTOCOL_ERROR, discarding untrusted output.