[davyd9]

Problem

ProoflineClient and AsyncProoflineClient expose get_agent_session_prompt, start_agent_session, and get_agent_session, but callers that start a coding-agent session from a finding currently lack a bounded wait helper analogous to wait_for_review. Hand-rolled polling loops around get_agent_session face three failure modes:

1. Treating status == "FINISHED" as terminal before session.done is True, which races Proofline's follow-up verification (such as confirming whether a vendor-opened pull request belongs to the target repository or whether the pull request head moved).
2. Accepting unvalidated primitive fields from the generated AgentSession.from_dict parser (which does not enforce runtime bool/int/str types or verify that session.id matches the requested session_id), or leaking untrusted_vendor_summary into logs and exception tracebacks via repr().
3. Polling without binding _transport.DEADLINE, allowing DNS resolution, streaming reads, or Retry-After delays to exceed the caller's wait budget.

Architectural Solution

• proofline/outcomes.py: Added AgentSessionStatus, AgentSessionOutcome (frozen dataclass with session marked repr=False so untrusted_vendor_summary and vendor URLs never appear in repr diagnostics), _validate_agent_session, and agent_session_outcome.
• Follow-state & identity invariants: agent_session_outcome treats session.done is True as the sole completion signal. Active sessions (done=False, even when status == "FINISHED") continue polling. Terminal sessions map to FINISHED, FAILED, REFUSED, HEAD_MOVED, or UNKNOWN (with explicit reason strings when a session ends in an active or unrecognized status), and TIMED_OUT retains the last validated AgentSession when available.
• proofline/client.py: Added wait_for_agent_session(organization_id, session_id, *, timeout=300) to both ProoflineClient and AsyncProoflineClient, sharing _transport.DEADLINE and exponential backoff (5s doubling to 60s) with wait_for_review.
• Public exports & contracts: Exported AgentSessionOutcome and AgentSessionStatus in proofline/__init__.py, registered wait_for_agent_session in scripts/contracts.py, and documented usage in README.md.

Benchmarks/Tests

• Added @MODES (sync and async) test suites in tests/test_http.py (test_wait_for_agent_session_follows_done_and_redacts_untrusted_summary and test_wait_for_agent_session_timeout_and_invalid_shapes) and agent_session fixture in tests/fixtures.py.
• Verified polling across REQUESTED -> FINISHED (done=False) -> FINISHED (done=True), all terminal statuses (FAILED, REFUSED, HEAD_MOVED, UNKNOWN), settled active/future status fallbacks, timeout=0 and multi-poll deadline expiration, Retry-After bounding on 503, immediate propagation on 403, repr() redaction of untrusted_vendor_summary, and urn:proofline:sdk:invalid-response on malformed session/target shapes.
• Ran python scripts/check.py end-to-end: generate.py --check, contracts.py, ruff check, ruff format --check, mypy proofline scripts, pytest -q (90 passed), wheel/sdist build, and install_smoke.py.

Trade-offs

• Default timeout (300s): Matches wait_for_review in this SDK for consistent Python caller ergonomics while allowing callers to pass a longer timeout for slower coding-agent runs.
• Strict runtime validation in outcomes.py: Rather than modifying the generated AgentSession.from_dict template across all endpoints, runtime type and identity checks live in _validate_agent_session alongside _validate for reviews, keeping generated code untouched and failing closed with urn:proofline:sdk:invalid-response.