prettyplay 0.0.1__tar.gz → 0.0.2__tar.gz

{prettyplay-0.0.1 → prettyplay-0.0.2}/.goga/Dockerfile

@@ -1,4 +1,4 @@
-FROM qarium/goga-python-3.14:1.3
+FROM qarium/goga-python-3.14:2.0
 
 USER root
 
@@ -12,4 +12,7 @@ COPY agents/tester.sh /home/goga/bin/tester-as-claude.sh
 
 RUN chmod +x /home/goga/bin/*.sh
 
+COPY . /tmp/project
+RUN cd /tmp/project && goga install && rm -rf /tmp/project
+
 USER goga

{prettyplay-0.0.1 → prettyplay-0.0.2}/.goga/config.yml

@@ -10,9 +10,8 @@ dockerfile: .goga/Dockerfile
   ANTHROPIC_BASE_URL: "https://api.z.ai/api/anthropic"
 
 build:
-  task_executor:
-    agent: developer
-  review_executor:
+  agent: developer
+  review:
     agent: reviewer
     base_ref: *base-ref
 
@@ -22,6 +21,10 @@ pipeline:
     <<: *claude-env
     ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5.3[1m]"
 
+tools:
+  autonomous: latest
+  basic-build: latest
+
 topics:
   base_ref: *base-ref
 

prettyplay-0.0.2/.goga/history/2026/backoff-for-llm-backend/acceptance.md

@@ -0,0 +1,296 @@
+# Final Acceptance Report
+
+## Summary
+Audited bounded LLM transport retries across five changed cells against their CODEMANIFEST contracts, implementation and consumer usages. Found and fixed one critical supported-SDK incompatibility after explicit file-dialog approval: quota evidence in older SDK response bodies was ignored. Added 36 regression cases, reconciled consumer documentation, and completed local validation. Verdict: ACCEPTED_WITH_NOTES.
+
+## Acceptance Scope
+| Cell | Change types reviewed |
+|---|---|
+| prettyplay/config | CODE, MANIFEST, USAGE, TEST |
+| prettyplay/llm | CODE, MANIFEST, USAGE, TEST |
+| prettyplay/failures | CODE (docstrings), MANIFEST, USAGE |
+| prettyplay/engine | CODE (docstrings), MANIFEST, TEST (integration) |
+| prettyplay/engine/groups | CODE (docstrings), MANIFEST |
+
+Feature baseline: b23929d..21585a1, excluding unrelated workflow/agent edits. The pre-existing relocation of the completed execution plan is not part of this audit's commit.
+
+## CODEMANIFEST Status
+CONSISTENT for the changed feature. Zero manifest edits. goga lint: 11 cells, 0 errors. Contract comparison covered 38 declarations in five cells; generated constructors and inherited/instance members were reconciled with runtime/source evidence. Existing public signatures remain unchanged.
+
+## Usages Status
+CONSISTENT at the scoped cell level after six documentation updates (five modified files, one new file). Both new transport examples execute successfully with the SDK boundary mocked. Shared project-practice inaccuracies were recorded without editing shared practices.
+
+## Test Coverage Assessment
+ADEQUATE. Full suite: 1182 passed, 0 failures/errors/skips. Combined line/branch coverage: 99.47% (lines 99.81%, branches 98.02%). Minimum supported openai 1.30.0 / anthropic 0.28.0: 337 LLM/integration tests passed. Ruff lint and format checks pass; 111 Python files already formatted.
+
+## Critical Findings
+| Source | Finding | Status |
+|---|---|---|
+| Manifest/Test | Older Anthropic SDK exposes quota evidence only in body; HTTP 429 billing_error incorrectly classified as retryable | Fixed: inspect flat/nested body code/type, preserve permanent precedence; 36 regression cases and minimum-SDK validation |
+
+Approval was received in autonomous_execution.q1.answer.json before remediation. The acceptance pipeline resumed only after the critical finding was resolved.
+
+## Warnings
+| Source | Finding | Recommendation |
+|---|---|---|
+| Shared SDK usages | Opening operation counts and direct error-mapping examples predate transport retries | Update shared examples in their owning documentation workflow; current cell usages and explicit contracts are authoritative |
+| Shared Pydantic usage | Automatic env propagation claim omits required loader registries | Clarify shared guidance; this feature includes the required registry entries |
+| Shared Playwright usage | Some examples still use removed flat configuration names | Update shared driver examples separately; unchanged error-shape guidance used here remains applicable |
+
+## Applied Updates
+- prettyplay/llm/_request.py
+- tests/llm/test_request.py
+- prettyplay/llm/.usages/providers.md
+- prettyplay/llm/.usages/transport.md
+- prettyplay/failures/.usages/taxonomy.md
+- prettyplay/engine/.usages/generation.md
+- prettyplay/engine/.usages/healing.md
+- prettyplay/engine/groups/.usages/recovery.md
+- .goga/history/2026/backoff-for-llm-backend/acceptance.md
+
+No project usages or dependency bounds changed. Detailed step reports and raw validation artifacts are retained in the acceptance stage directory; the step reports are reproduced below for a self-contained repository record.
+
+## Risks
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Shared-practice wording may confuse future implementers | Low | Record specific discrepancies; corrected cell consumer guidance accompanies the implementation |
+| Live provider/network behavior is not exercised locally | Low | Real SDK exception classes, current/minimum SDK versions, deterministic external-boundary tests; no claim of live API validation |
+| Current interpreter is Python 3.12 | Low | Python 3.10-compatible source and ruff target retained; older interpreter fallback was not executed |
+
+## Verdict
+ACCEPTED_WITH_NOTES. All five ordered acceptance steps completed; no unresolved critical contract discrepancy or critical changed-API coverage gap. Shared-documentation remarks and validation limits remain recorded above.
+
+---
+
+# Acceptance Scope Report
+
+## Data source
+The build stage context, feature history, and git diff b23929d..21585a1 identify bounded LLM transport retries. The working tree only contains the pre-existing completed-plan relocation; reviewing that relocation alone would omit the built feature. Unrelated agent/workflow changes are excluded.
+
+## Functionality
+Bounded transport retries for both SDK providers, configurable total sends, permanent-first classification, capped exponential pauses, Retry-After handling, safe logging, and engine-budget neutrality.
+
+## Cells for acceptance
+| Cell | Path | Change types |
+|---|---|---|
+| Configuration | prettyplay/config | CODE, MANIFEST, USAGE, TEST |
+| LLM port | prettyplay/llm | CODE, MANIFEST, USAGE, TEST |
+| Failures | prettyplay/failures | CODE (docstring), MANIFEST, USAGE |
+| Engine | prettyplay/engine | CODE (docstrings), MANIFEST, TEST (integration) |
+| Group recovery | prettyplay/engine/groups | CODE (docstrings), MANIFEST |
+
+## Affected dependencies
+| Dependent cell | Dependency type | Impact assessment |
+|---|---|---|
+| prettyplay | DIRECT | Imports configuration and failure types; public root exports must stay unchanged. |
+| prettyplay/cache | DIRECT | Imports Config; default construction remains compatible. |
+| prettyplay/driver | DIRECT | Imports Config; browser settings unchanged. |
+| prettyplay/engine/steering | DIRECT | Imports Config, LLMProvider, engine and failure APIs; receives bounded transport behavior. |
+| prettyplay/engine/polling | TRANSITIVE | Imports driver; no changed settle behavior. |
+
+## Scope summary
+Five changed cells; 26 source/contract/usage/test paths: 12 implementation files (including facade), 5 manifests, 3 cell usage files, and 6 test files. Cross-cell regression checks include the complete test suite. Shared practices and feature documentation are supporting evidence. The pre-existing plan relocation is excluded from acceptance edits.
+
+
+---
+
+# Manifest Review Report
+
+## Linter Results
+| Cell | Linter Status | Errors |
+|---|---|---|
+| config, llm, failures, engine, engine/groups | PASS | 0; project-wide goga lint checks all 11 cells |
+
+## Analysis 1 — Code vs Requirements
+| Cell | Signature Match | Method Coverage | Property Coverage | Facade | Status |
+|---|---|---|---|---|---|
+| config | Runtime/Pydantic match | Complete | Complete | PASS | CONSISTENT |
+| llm | Match | All four operations on both providers | Complete | PASS | CONSISTENT after quota fix |
+| failures | Match including inherited constructors | Complete | Instance fields verified in source | PASS | CONSISTENT for changed behavior |
+| engine | Match | Complete | Complete | PASS | CONSISTENT for changed behavior |
+| engine/groups | Match | Complete | Complete | PASS | CONSISTENT for changed behavior |
+
+The CLI returns comparison evidence, not a semantic pass/fail verdict. Its empty generated constructors and absent instance attributes were reconciled with runtime signatures/Pydantic fields and source. Return labels, Python defaults, and PositiveInt/Literal constraints are compatible differences. All 38 declared types are exported. PrettyConfig is an existing alias of Config, not a new implementation type.
+
+## Analysis 2 — Requirements vs Code
+| Cell | Undocumented Entities | Description Accuracy | Annotation Quality | Status |
+|---|---|---|---|---|
+| config | No new omissions | Request-attempt setting matches | Changed parameters and constraints explicit | CONSISTENT |
+| llm | Five transport exports declared | Classification, pause, retry and SDK wiring match after fix | Changed algorithms explicit | CONSISTENT |
+| failures | No new omissions | Infrastructure error wording matches | Changed guarantees explicit | CONSISTENT |
+| engine | No new omissions | No additional engine retries | Changed guarantee explicit | CONSISTENT |
+| engine/groups | No new omissions | Diagnosis propagation matches | Changed guarantee explicit | CONSISTENT |
+
+## Algorithm Consistency
+Configuration: positive total sends, default 3, file/env/explicit merge. LLM: permanent evidence precedes retryable status; raw quota body now supports older SDKs; timeout before connection; bounded pause; permanent/over-cap/exhaustion order; identical SDK request reused. Failures: existing chained error type. Engine: transport sends occur inside one logical attempt. Groups: infrastructure error escapes the recovery cycle rather than becoming another recovery attempt. All changed algorithms match.
+
+## Operational Flow Consistency
+Both providers construct clients with max_retries=0, route all four operations through send_with_retries, and parse successful content outside that loop. Missing API keys fail before the loop. Config feeds attempts. Failure propagation and the existing quiet verdict skip remain unchanged in engine/groups.
+
+## Guarantee Verification
+Fixed quota precedence for body-only SDK exceptions. Send budget, pause cap, Retry-After termination, chained causes, interruption, no secret-bearing retry records, and no engine budget access are preserved. Minimum supported SDK validation: 337 LLM/integration tests passed with openai 1.30.0 and anthropic 0.28.0.
+
+## Practice Consistency
+Changed implementation uses relative imports, typed functions, private helpers, Pydantic settings, and structured retry logs. Tests use SDK boundary objects and patched sleep. Pre-existing model/style choices outside the transport change were not refactored.
+
+## Baseline Usages/Annotations Audit
+| Cell | Baseline Usages present? | Baseline Annotations present? |
+|---|---|---|
+| config | Yes | Yes |
+| llm | Yes | Yes |
+| failures | Yes | Yes |
+| engine | Yes | Yes |
+| engine/groups | Yes | Yes |
+
+## Findings
+| Cell | Analysis | Finding | Severity | Proposed Action |
+|---|---|---|---|---|
+| llm | Code vs requirements | Anthropic 0.28 lacks parsed type/code attributes; billing_error in body was retried | CRITICAL, fixed | Approved in autonomous_execution.q1.answer.json; inspect flat/nested body code/type and add regression tests |
+| All | Tool interpretation | Static contract output omits generated/inherited members | INFO | Verified runtime facade and source; no manifest change |
+
+## Applied Updates
+| Cell | Updated Section | Previous Value | New Value | Reason |
+|---|---|---|---|---|
+| llm | _request.py permanent evidence | Exception attributes only | Attributes plus flat/nested dictionary body | Supported SDK compatibility |
+| llm tests | test_request.py | No body-only quota cases | 36 parameterized regression cases | Lock quota precedence, malformed-body handling, immediate termination |
+
+No CODEMANIFEST updates. Remediation task: reproduce body-only quota failure, extend evidence extraction without changing contracts or dependency bounds, verify both providers and supported SDK minima. Completed after user approval; before-fix regressions: 18 failed/18 passed; after-fix request module: 142 passed.
+
+## Critical Discrepancies
+None open. The single critical discrepancy above was fixed and revalidated before advancing to usages review.
+
+## Overall Status
+CONSISTENT for the bounded transport retry feature across the five scoped cells. All manifest lint checks pass; no contract relaxation or public signature changes.
+
+
+---
+
+# Usage Review Report
+
+## Cell-level usages
+| Cell | Usage file | Examples valid? | Descriptions accurate? | Names aligned? | Updated? |
+|---|---|---|---|---|---|
+| config | configuration.md | Yes, signatures/config fields reviewed | Yes for request retries | Yes | No |
+| llm | classification.md | Yes, call signature reviewed | Yes | Yes | No |
+| llm | providers.md | Yes, facade/model construction reviewed | Corrected model fallback and operation list | Yes | Yes |
+| llm | transport.md | Both snippets executed with SDK constructor mocked | Yes | Yes | Created |
+| failures | taxonomy.md | API/exception fields reviewed; placeholders remain illustrative | Added over-cap Retry-After termination | Yes | Yes |
+| engine | generation.md | Call signature reviewed | Added logical vs physical send accounting | Yes | Yes |
+| engine | healing.md | Call signature reviewed | Added provider retry termination | Yes | Yes |
+| engine/groups | recovery.md | Call signature reviewed | Added propagation without another cycle | Yes | Yes |
+
+## Project usages — remarks
+| Usage file | Referenced by cells | Remark | Type |
+|---|---|---|---|
+| .goga/usages/cooks/openai.md | llm | Opening says three operations; examples show direct error mapping while later transport section correctly requires bounded retries. Resynchronize examples in a separate shared-practice update. | Inaccurate description, nonblocking |
+| .goga/usages/cooks/anthropic.md | llm | Same older three-operation/direct-send presentation; retry policy section is current. | Inaccurate description, nonblocking |
+| .goga/usages/cooks/pydantic.md | config | Says new settings receive env overrides automatically; implementation requires registry entries, correctly added for this setting. | Inaccurate description, nonblocking |
+| .goga/usages/cooks/playwright.md | failures | Driver examples still use removed flat browser/headless fields. Error-message shapes used by failures remain applicable; browser configuration is outside this feature. | Stale example, nonblocking |
+| .goga/usages/conventions.md | All five | Applied to changed code/tests; no shared-file update. | No new discrepancy |
+| .goga/usages/cooks/json_repair.md | llm | Strict parsing after salvage and failure handling match. | No discrepancy |
+| .goga/usages/prompts/step_generation.md, step_cheatsheet.md, group_framing.md, group_diagnosis.md | engine, engine/groups | Request construction and unchanged prompt responsibilities reviewed; transport wrapper does not rebuild or change prompts. | No new discrepancy |
+
+Project usages remain unchanged, as required by this review skill. Shared-practice remarks do not change the explicit cell contracts.
+
+## Integrity
+| Cell | All Usages have files? | All imported usages exist? | All usages referenced in annotations? |
+|---|---|---|---|
+| config | Yes | Yes | Yes |
+| llm | Yes | Yes; no imported practices | Yes |
+| failures | Yes | Yes; no imported practices | Yes |
+| engine | Yes; classification/compliance practices inline | Yes | Yes |
+| engine/groups | Yes | Yes; no imported practices | Yes |
+
+Validated with goga lint: 11 cells, 0 errors.
+
+## Applied updates
+| Usage file | Change | Reason |
+|---|---|---|
+| prettyplay/llm/.usages/providers.md | All four operations and accurate model fallback | Defaults can use the same model for generation and verdict |
+| prettyplay/llm/.usages/transport.md | Facade examples, SDK compatibility and helper preconditions | Cover all five new transport exports |
+| prettyplay/failures/.usages/taxonomy.md | Excessive Retry-After outcome and reaction | Complete terminal outcome description |
+| prettyplay/engine/.usages/generation.md | Logical attempt accounting and terminal propagation | Distinguish SDK sends from engine attempts |
+| prettyplay/engine/.usages/healing.md | Provider retry termination | Match runtime propagation |
+| prettyplay/engine/groups/.usages/recovery.md | Retry/cycle boundary | Document no extra group cycles |
+
+## Uncovered patterns
+None in the changed transport facade after adding transport.md. Live provider calls were not made; SDK call syntax and operation routing are covered by local tests.
+
+## Overall consistency
+CONSISTENT for scoped cell usages after six documentation updates. Shared project-practice remarks remain advisory and were not edited.
+
+
+---
+
+# Test Assessment Report
+
+## Coverage Points
+| Cell | Coverage Point | Type | Source |
+|---|---|---|---|
+| config | llm_request_attempts field, default 3, positive value, keyword construction | contract/boundary | CODEMANIFEST |
+| config | File/env/explicit layer precedence and actionable parsing errors | integration/branch | CODEMANIFEST, loader.py |
+| llm | Five transport exports and function signatures | contract | CODEMANIFEST |
+| llm | Nine categories, permanent precedence, unknown exception fallback | contract/branch | CODEMANIFEST, _request.py |
+| llm | Raw flat/nested quota bodies without convenience SDK attributes | boundary/integration | _request.py, supported SDK versions |
+| llm | Decimal/malformed Retry-After and zero wait behavior | boundary | CODEMANIFEST |
+| llm | Exponential pause sequence, jitter endpoints, inclusive cap and large budget | boundary/branch | CODEMANIFEST |
+| llm | Success identity, permanent/over-cap/exhaustion ordering, cause chaining | contract/branch | CODEMANIFEST |
+| llm | Interruption, send ceiling, warning fields and payload exclusion | contract/integration | CODEMANIFEST |
+| llm | Both SDK constructors disable retries; all eight operation routes | integration | Provider implementations |
+| llm | Missing API key before retry, response validation after retry | branch | Provider implementations |
+| failures | Infrastructure exception type/message and chained transport cause | contract/integration | CODEMANIFEST |
+| engine | No extra logical attempt, single generation hook and cache write | integration | CODEMANIFEST, generator.py |
+| engine | Compliance retry does not repeat browser action or cache unchecked code | integration/branch | compliance.py, generator.py |
+| engine/groups | Infrastructure propagation; existing group-cycle and healing accounting | contract/integration | CODEMANIFEST, diagnosis.py, recovery.py |
+
+## Existing Tests
+| Test Name / Group | File | Type | What It Verifies | Status |
+|---|---|---|---|---|
+| test_config_llm_request_attempts_field_defaults_and_order; test_config_rejects_llm_request_attempts_below_one | tests/config/test_models.py | CONTRACT | Setting shape/default and 0/-1 rejection | passed |
+| TestLlmRequestAttemptsEnv; test_every_setting_has_an_env_override; override tests | tests/config/test_loader.py | CONTRACT/INTEGRATION | Env registry, decimal parse, actionable error and generic merge logic | passed |
+| TestTransportFailureClassificationContract; TestClassifiersContract; TestFacadeExports | tests/llm/test_request.py | CONTRACT | Model, signatures, root-facade isolation | passed |
+| TestTransportFailureClassification; TestClassifyFailures | tests/llm/test_request.py | CONTRACT | Category truth table, exception mapping, Retry-After | passed |
+| TestQuotaBodyEvidence (36 cases, added in this audit) | tests/llm/test_request.py | CONTRACT/INTEGRATION | Both SDKs; flat/nested code/type; 429/503; malformed bodies; no resend/sleep/log on quota | passed |
+| TestComputeTransportPause | tests/llm/test_request.py | CONTRACT | Sequence, jitter bounds, Retry-After lift, large attempt number | passed |
+| TestSendWithRetries; TestSendWithRetriesTerminal; TestSendWithRetriesEdges | tests/llm/test_request.py | CONTRACT/INTEGRATION | Retry state machine, send budget, terminal precedence, interruption and logging | passed |
+| TestOpenAIProviderTransportWiring | tests/llm/test_openai_provider.py | INTEGRATION | Four routes, both max_retries constructors, recovery, rejection, missing key | passed |
+| TestAnthropicProviderTransportWiring | tests/llm/test_anthropic_provider.py | INTEGRATION | Four mirrored routes and SDK behavior | passed |
+| Failure taxonomy suite | tests/failures/ | CONTRACT | Exception API, inheritance, rendering | passed |
+| test_engine_budgets_untouched_by_transport_retries | tests/test_transport_retries_integration.py | INTEGRATION | Two sends inside one generation attempt and one cache write | passed |
+| test_compliance_retry_does_not_repeat_candidate_or_cache_without_verdict (2 cases) | tests/test_transport_retries_integration.py | INTEGRATION | Recovery/exhaustion after one browser action, cache gated by verdict | passed |
+| Engine and group suites | tests/engine/ | CONTRACT/INTEGRATION | Existing classification, healing and group propagation/accounting | passed |
+
+Full test enumeration and status: stage artifact test_inventory.tsv (1182 cases), with machine-readable tests.xml. Tests use real domain logic and SDK exception classes; SDK network/browser boundaries and sleeps are replaced.
+
+## Coverage Assessment
+| Coverage Point | Covered by Test? | Test | Test Type | Coverage Completeness |
+|---|---|---|---|---|
+| Config field and loading | Yes | Model and loader groups above | CONTRACT/INTEGRATION | Adequate; shared merge tests also exercise scalar precedence |
+| Transport API surface | Yes | Contract/facade groups above | CONTRACT | Complete changed API |
+| Classifiers and SDK compatibility | Yes | Classifier groups + quota regressions, minimum-SDK run | CONTRACT/INTEGRATION | Adequate; fixed uncovered body-only representation |
+| Delay and terminal state machine | Yes | Pause/terminal/edge groups | CONTRACT | Adequate; branches exercised for valid positive budgets |
+| Provider parity and parsing boundary | Yes | Both provider suites | CONTRACT/INTEGRATION | All four operations per provider; validation remains outside loop |
+| Error taxonomy and engine semantics | Yes | Failure/engine/group suites + three transport integration cases | CONTRACT/INTEGRATION | Adequate; generation and compliance covered end to end with fake external boundaries |
+
+Measured combined line/branch coverage: whole project 99.47% (lines 99.81%, branches 98.02%); config models 100%, loader 98.69%; engine and engine/groups scoped modules 100%; failures 100%; _request.py 99.23%; OpenAI provider 98.36%; Anthropic provider 98.55%. Coverage percentages are supporting evidence, not proof of all semantics.
+
+## Test Run Results
+- Current environment, complete suite: 1182 passed, 0 failed, 0 errors, no skips (8.66 seconds).
+- Minimum supported SDK environment: openai 1.30.0, anthropic 0.28.0, httpx below 0.28; LLM and transport integration suites: 337 passed.
+- Regression proof before fix: 18 failing quota cases and 18 passing malformed-body cases. After fix: request module 142 passed.
+- Ruff source/tests lint: passed. Format check: 111 files already formatted. git diff --check: passed.
+- Coverage data and test output are preserved in stage artifacts coverage.json, tests.log, tests.xml and min-sdk-tests.log.
+
+## Coverage Gaps
+| Coverage Point | Gap Type | Description |
+|---|---|---|
+| Supported SDK body-only quota | CRITICAL, resolved | Regression suite added with approved remediation; no open gap |
+| Defensive loop tail | INFO | Unexecuted assertion requires attempts <= 0, outside Config's positive-budget contract |
+| Unchanged SDK client reuse branch and Python 3.10 TOML import | INFO | Not traversed in this Python 3.12 run; unrelated existing paths, not changed transport behavior |
+| Live hosted provider/network/browser behavior | INFO | Deterministic acceptance uses external-boundary fakes; no paid provider or live browser session exercised |
+
+## Proposed Tests
+No outstanding CRITICAL or WARNING test proposal for changed behavior. The approved body-only quota proposal was implemented before acceptance resumed. Future live-service smoke testing is optional and not part of this local audit.
+
+## Overall Coverage Assessment
+ADEQUATE. All new public transport APIs and changed configuration behavior have tests; core retry outcomes and generation/compliance integration are covered. The discovered critical SDK compatibility gap is closed. Remaining observations concern existing branches or external live-service validation, not missing tests for the changed public contract.

prettyplay-0.0.2/.goga/history/2026/backoff-for-llm-backend/adr.md

@@ -0,0 +1,18 @@
+# Bounded backoff for LLM backend requests
+
+Transient LLM backend failures currently terminate operations under an explicit no-retry contract. We will replace that rule with bounded transport retries of the same request, independently of generation and healing budgets, so temporary outages can recover without replaying the task or browser actions. The user confirmed this decision on 2026-10-07.
+
+- Apply the same policy to OpenAI and Anthropic, including custom base URLs, for generation, failure classification, group diagnosis, and compliance checks. Transport retries remain within one logical LLM attempt and consume no additional generation, healing, or group recovery attempts.
+- Retry connection failures, timeouts, HTTP 408/429, and transient 5xx failures. Authentication, authorization, invalid requests, and explicitly exhausted quota fail immediately; explicit permanent causes take precedence over a retryable HTTP status. Invalid content in a successful response remains subject to existing response validation and recovery, not transport backoff.
+- Default to **3 total attempts**, including the initial request. Only the attempt count is configurable, using the existing precedence: explicit test parameters > environment > pyproject. One attempt disables retries; values below one are configuration errors. Disable SDK retries so the configured limit also limits request sends.
+- Fix the minimum and maximum delays at **1 and 10 seconds**. Base delays grow as 1, 2, 4, 8, 10, 10… seconds. Add a random 0–25% of the base delay, then cap the final delay at 10 seconds. With the default attempt count, the two pauses are 1–1.25 and 2–2.5 seconds.
+- Honor a valid `Retry-After` by taking the greater of its indicated wait and the computed delay, provided the indicated wait is at most 10 seconds. If it exceeds 10 seconds, terminate with an actionable error instead of retrying earlier than requested or exceeding the delay cap. Ignore malformed values.
+- Preserve current SDK request timeouts; adding timeout configuration or an overall deadline is outside this change. Cancellation interrupts backoff waiting and prevents another retry.
+- After exhaustion, retain existing `LLMUnavailableError` handling and the original cause. Required operations fail the current test through normal error handling and resource cleanup. Optional terminal-failure classification logs a warning and preserves the original failure; steering likewise preserves its original terminal failure. Retry only the compliance request after browser actions have run, and never cache a candidate without a successful compliance verdict. Preserve modes that make no LLM requests.
+- Log retries with provider, operation, attempt number, error category, and delay. Exclude secrets and request/response contents. Introduce no new public monitoring events.
+
+## Consequences
+
+Transport recovery deliberately replaces the existing immediate-failure rule and must remain distinct from browser polling, which repeats browser code. Central control of retries avoids multiplying SDK and application attempts. Bounded attempts and capped pauses trade outage tolerance for predictable retry counts, but do not provide a total wall-clock bound because request timeouts are unchanged. When a response is lost after server-side processing, retrying may duplicate provider work and increase usage costs; exactly-once provider execution is not guaranteed.
+
+This decision is based on architecture contracts and usage documentation, not an implementation audit. Implementation must reconcile the existing no-retry rules and verify actual SDK retry settings. Cell design, signatures, and contract layout are outside this ADR; no behavioral decision remains open.