Stabilize ACA session admission and results

[Laveesh Rohra (larohra)]

Stack

Stack layer 2/5, based on parent PR #194 (larohra/aca-region-contract).

Isolated contract

• preserves the committed management handle when journal launch acknowledgement is indeterminate
• surfaces typed, redacted activation/provider failures consistently across submit, status, result, events, and cancel
• keeps transient result materialization retryable and structured
• enforces the shared 300-second result hold across terminal adoption, rearm, eviction, and reclaim
• makes bounded reconciliation fail closed for off-page run rows and exact-checks persisted backing before reclaim

This replaces the runtime-reliability portion of draft PR #169 without modifying or closing it. Qualification fixtures, deployment/attestation scripts, generated constraints, templates, and pipeline gating remain in later stack layers.

Validation

• python -m ruff check src tests
• python -m mypy src
• targeted controller/readiness/reconciler/execution/state-store/app tests: 479 passed
• git diff --check

[Copilot]

🟡 Changes recommended

Critical idle-reclaim safety and committed-handle preservation issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Stabilizes ACA session admission, provider failures, result retention, and bounded reconciliation safety.

Changes:

• Preserves management handles for indeterminate launches.
• Adds typed, redacted provider failure handling.
• Enforces a shared 300-second result hold.
• Adds safer bounded reconciliation and backing checks.

Required fixes:

• Critical: Exact-read persisted sandbox backing before completing idle reclaim.
• Moderate: Distinguish pre-launch from post-launch indeterminate failures so committed handles are preserved.

File summaries

File	Description
tests/test_session_state_store_errors.py	Tests atomic expiry extension.
tests/test_execution_aca_sandbox.py	Tests admission, provider errors, cancellation, and retention.
tests/test_controller_reconciler.py	Tests retention and bounded reconciliation.
tests/test_controller_readiness.py	Tests deadlines and rearm retention.
tests/test_controller_http.py	Tests committed indeterminate responses.
tests/test_app.py	Tests reconciliation deadline propagation.
tests/doubles/fake_session_runtime.py	Updates the session-runtime test double.
src/azure_functions_agents/session_state/store.py	Extends expiry during terminal adoption.
src/azure_functions_agents/sandbox_runtime_limits.py	Defines the shared result hold.
src/azure_functions_agents/execution/backend.py	Defines the indeterminate-admission error.
src/azure_functions_agents/execution/aca_sandbox.py	Handles launch ambiguity, transport errors, and result retention.
src/azure_functions_agents/execution/__init__.py	Exports the new error type.
src/azure_functions_agents/controller/reconciler.py	Adds result-aware reclaim and backing checks.
src/azure_functions_agents/controller/readiness.py	Preserves retention during lifecycle rearm.
src/azure_functions_agents/controller/http.py	Returns committed 202 responses.
docs/frds/0008-aca-sandbox-session-runtime.md	Records the updated design decision.
docs/architecture.md	Updates runtime boundary documentation.
docs/aca-sandbox-session-runtime.md	Documents public reliability behavior.

Review details

Suppressed comments (1)

src/azure_functions_agents/execution/aca_sandbox.py:567

• The durable conversion is only applied by _submit_admitted_run. Idempotent replays call _resume_journal_submission directly, so if the same journal read or launch remains indeterminate, start_run() leaks RunSubmissionIndeterminateError instead of returning the committed handle. Apply the same durable projection on the replay path, preferably through a shared helper.

            raise DurableAdmissionIndeterminateError(
                handle=_run_handle(run, phase="executing"),
            ) from exc

• Files reviewed: 18/18 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.