fix: keep orchestration alive through retry guardrails

docs-web/content/docs/user-automation-and-ci.mdx

@@ -114,12 +114,14 @@ The `merge_indicator` field on a subtask documents the merge state:
 
 ## QA gate (enabled by default)
 
-If a QA agent preset is wired to `qa_review` in routing, completed tasks pass through a QA review *before* the merge protocol greenlights them. A failed review:
+If a QA agent preset is wired to `qa_review` in routing, completed tasks pass through a QA review *before* the merge protocol greenlights them. A non-passing review that exhausts its configured guardrail:
 
 - Sets task status to `QA_REVIEW_FAILED`.
 - Creates an attention item with the QA agent's findings.
 - Pauses the task until rectified.
 
+Provider or infrastructure errors do not immediately create this handoff. They retry automatically until the applicable QA run cap is reached, and the sprint watch loop stays alive while worker or human attention is active.
+
 ## Attention items: who handles them
 
 Anything not auto-handled becomes an attention item. The dashboard's **Live Session** page surfaces them.

docs-web/content/docs/user-dashboard-chat.mdx

@@ -11,6 +11,8 @@ The **Chat** page (`/chat`) is a thread-based conversation surface that lets you
   - **Invocations** — A historical log of server-created execution invocations, including provider-backed agent runs and MCP `CallTool` activity.
 - **Main panel** — The active thread (or invocation), rendered as a chat transcript with user, assistant, and tool messages. Markdown is rendered with `marked`, including code blocks.
 
+Markdown links use the dashboard's theme-aware signal colors across thread messages, invocation transcripts, truncated system messages, and 3D Chat. In dark mode they render in high-contrast mint with a brighter jade hover/focus state instead of a fixed dark blue; provider-branded badges retain their own readable semantic colors.
+
 3D chat and agent avatar surfaces use the standard WebGL avatar with studio lighting and pointer-aware head movement. The removed flashlight beam, target glow, low-battery flicker, and emissive shell boost are no longer part of the chat layout; reduced-motion settings or WebGL fallback mode continue to use the static SVG avatar.
 
 ## No-project assistant

docs-web/content/docs/user-sprint-orchestration.mdx

@@ -117,7 +117,9 @@ When a worker resolves a merge conflict, Code UX clears the task's stale `MERGE_
 
 CLI tasks that complete with a worker branch but no PR use a branch-only merge path in both LOCAL and REMOTE git modes; REMOTE mode then pushes the sprint feature branch. If the task snapshot lost the worker branch, Code UX recovers it from the completed task run before checking merge readiness. For CLI-backed runs, branch-only classification and protocol merge-required attention wait for the git-finalize event (`cli_git_pushed` or `cli_git_no_changes`) so provider/session completion cannot race ahead of branch materialization. Task QA reviews run from an isolated snapshot of that selected branch in both Docker and host execution, so a visible default-branch checkout cannot create a false missing-file rejection. That merge runs in a temporary worktree through the containerized Git helper so the visible checkout and `.code-ux/` runtime files do not interfere with task settlement. When several clean LOCAL worker branches are ready in one cycle, they share that worktree while each successful merge is committed and published to the feature branch independently. Code UX normalizes temporary worktree gitdir metadata after creation so later helper-container Git calls resolve the same repository. Once the task is settled as merged, stale task-run worker branch evidence is suppressed from live status so old branches do not keep re-entering merge scans.
 
-Sprint-completion QA stays fail-closed. If its provider terminates without a verdict and the sprint has not changed, or the non-passing review cycle reaches its retry cap, Code UX raises one sprint-scoped human handoff with the attempt count and latest provider error instead of leaving the sprint silently running. After the provider or review result is corrected, resolving that handoff resets only sprint-completion QA and permits one fresh review cycle.
+Sprint-completion QA stays fail-closed. If its provider terminates without a verdict, Code UX retries on the next watch cycle even when the sprint has not changed. Only after the configured sprint-QA retry cap is reached does Code UX raise one sprint-scoped human handoff with the attempt count and latest provider error. The sprint remains active while waiting for that handoff, so resolving it resets only sprint-completion QA and permits one fresh review cycle without manually resuming the sprint.
+
+Provider diagnostics are derived from real provider error events. In particular, Codex tool output or repository fixtures that merely mention authentication, quota, or rate limits do not get reported as provider authentication failures.
 
 Worker-owned merge-conflict repair and LOCAL task-branch merges resolve `.code-ux/**` conflicts to the target branch side before deciding whether a provider is needed. A conflict only in Code UX runtime artifacts does not dispatch a provider, and invalid Docker repair workspaces are reseeded before provider execution. Real source conflicts outside `.code-ux/` still fail closed and remain visible as merge-conflict work.
 
@@ -136,7 +138,7 @@ Override via `maxFailures` in settings or `JULES_API_MAX_FAILS` in the environme
 Two distinct retry surfaces:
 
 1. **Task-level retry** — `retryFailed: true` (default). Failed sessions get a fresh worker session next cycle. The original failure stays attached for diagnosis.
-2. **CI autofix retry** — If a PR's CI is failing and `waitForJulesCiAutofix: true`, Code UX dispatches a CI fix worker. Up to `julesCiAutofixMaxRetries` (legacy mirror default `5`, max `20`) attempts before creating a human handoff.
+2. **CI autofix retry** — If a PR's CI is failing and automatic repair is enabled, Code UX dispatches a CI fix worker and keeps the sprint active while it runs. Failures requeue the same attention item until the `ci_fix` guardrail is reached; only then is a human handoff created.
 
 ## Action-required automation
 

docs-web/user/automation-and-ci.md

@@ -114,12 +114,14 @@ The `merge_indicator` field on a subtask documents the merge state:
 
 ## QA gate (enabled by default)
 
-If a QA agent preset is wired to `qa_review` in routing, completed tasks pass through a QA review *before* the merge protocol greenlights them. A failed review:
+If a QA agent preset is wired to `qa_review` in routing, completed tasks pass through a QA review *before* the merge protocol greenlights them. A non-passing review that exhausts its configured guardrail:
 
 - Sets task status to `QA_REVIEW_FAILED`.
 - Creates an attention item with the QA agent's findings.
 - Pauses the task until rectified.
 
+Provider or infrastructure errors do not immediately create this handoff. They retry automatically until the applicable QA run cap is reached, and the sprint watch loop stays alive while worker or human attention is active.
+
 ## Attention items: who handles them
 
 Anything not auto-handled becomes an attention item. The dashboard's **Live Session** page surfaces them.

docs-web/user/sprint-orchestration.md

@@ -117,7 +117,9 @@ When a worker resolves a merge conflict, Code UX clears the task's stale `MERGE_
 
 CLI tasks that complete with a worker branch but no PR use a branch-only merge path in both LOCAL and REMOTE git modes; REMOTE mode then pushes the sprint feature branch. If the task snapshot lost the worker branch, Code UX recovers it from the completed task run before checking merge readiness. For CLI-backed runs, branch-only classification and protocol merge-required attention wait for the git-finalize event (`cli_git_pushed` or `cli_git_no_changes`) so provider/session completion cannot race ahead of branch materialization. Task QA reviews run from an isolated snapshot of that selected branch in both Docker and host execution, so a visible default-branch checkout cannot create a false missing-file rejection. That merge runs in a temporary worktree through the containerized Git helper so the visible checkout and `.code-ux/` runtime files do not interfere with task settlement. When several clean LOCAL worker branches are ready in one cycle, they share that worktree while each successful merge is committed and published to the feature branch independently. Code UX normalizes temporary worktree gitdir metadata after creation so later helper-container Git calls resolve the same repository. Once the task is settled as merged, stale task-run worker branch evidence is suppressed from live status so old branches do not keep re-entering merge scans.
 
-Sprint-completion QA stays fail-closed. If its provider terminates without a verdict and the sprint has not changed, or the non-passing review cycle reaches its retry cap, Code UX raises one sprint-scoped human handoff with the attempt count and latest provider error instead of leaving the sprint silently running. After the provider or review result is corrected, resolving that handoff resets only sprint-completion QA and permits one fresh review cycle.
+Sprint-completion QA stays fail-closed. If its provider terminates without a verdict, Code UX retries on the next watch cycle even when the sprint has not changed. Only after the configured sprint-QA retry cap is reached does Code UX raise one sprint-scoped human handoff with the attempt count and latest provider error. The sprint remains active while waiting for that handoff, so resolving it resets only sprint-completion QA and permits one fresh review cycle without manually resuming the sprint.
+
+Provider diagnostics are derived from real provider error events. In particular, Codex tool output or repository fixtures that merely mention authentication, quota, or rate limits do not get reported as provider authentication failures.
 
 Worker-owned merge-conflict repair and LOCAL task-branch merges resolve `.code-ux/**` conflicts to the target branch side before deciding whether a provider is needed. A conflict only in Code UX runtime artifacts does not dispatch a provider, and invalid Docker repair workspaces are reseeded before provider execution. Real source conflicts outside `.code-ux/` still fail closed and remain visible as merge-conflict work.
 
@@ -136,7 +138,7 @@ Override via `maxFailures` in settings or `JULES_API_MAX_FAILS` in the environme
 Two distinct retry surfaces:
 
 1. **Task-level retry** — `retryFailed: true` (default). Failed sessions get a fresh worker session next cycle. The original failure stays attached for diagnosis.
-2. **CI autofix retry** — If a PR's CI is failing and `waitForJulesCiAutofix: true`, Code UX dispatches a CI fix worker. Up to `julesCiAutofixMaxRetries` (legacy mirror default `5`, max `20`) attempts before creating a human handoff.
+2. **CI autofix retry** — If a PR's CI is failing and automatic repair is enabled, Code UX dispatches a CI fix worker and keeps the sprint active while it runs. Failures requeue the same attention item until the `ci_fix` guardrail is reached; only then is a human handoff created.
 
 ## Action-required automation
 

docs/architecture/quality-assurance-agent.md

@@ -158,6 +158,8 @@ Task-level prompt scope:
 
 If task QA is still pending, running, or has failed without exhausting `maxTaskReviewRuns`, Code UX marks the task merge state as `QA_PENDING` and keeps the sprint active instead of auto-merging. If QA is exhausted and configured to `ESCALATE_TO_HUMAN`, the task is held in `QA_REVIEW_FAILED` and will not be merged or marked complete until a human resolves it.
 
+Provider/infrastructure failures in sprint-completion QA are also retryable without requiring task changes. Code UX starts the next review cycle until `maxSprintReviewRuns` is reached, opens the sprint-scoped human handoff only at that cap, and leaves the sprint run active so it can observe resolution and continue automatically.
+
 Recovery guarantees:
 
 - task QA no longer depends only on catching a single in-cycle transition edge; if a task is already code-complete and still has no successful QA run, Code UX will enqueue the missing review on the next orchestration cycle instead of leaving the task parked in `QA_PENDING`
@@ -187,7 +189,7 @@ This separation keeps repository writes, provider calls, task status mutations,
 
 - whether a task QA attempt is still within budget or should require human attention
 - whether a normalized task review means pass, changes requested, retryable failure, or fatal failure
-- whether a sprint completion review should run, stay blocked, or be skipped because it already passed or exhausted its retry budget
+- whether a sprint completion review should run, retry a provider failure, stay blocked, or be skipped because it already passed or exhausted its retry budget
 - whether a `running` QA review row is still legitimately active or should be recovered as a failed stale run
 
 - the initial completed task review always counts as run `1`

docs/sprint-loop/atomic-loop.md

@@ -168,9 +168,9 @@ When `action=orchestrate`, `wait` is true, and `watchLoop` is enabled:
 - Provider load for start-ready admission combines running provider invocations with active task runs that have not yet produced terminal provider evidence. This prevents wide DAG cycles from creating a large queue of running Docker dispatches that all wait inside the provider-slot gate before their provider invocation rows exist. Provider-slot wait logs are also throttled per provider across concurrent waiters.
 - Loop exits when:
   - all tasks reach their terminal state (e.g., `COMPLETED` + merged, or `FAILED`) and the final merge is settled: remote-git mode requires GitHub to report the completion PR as merged, while local-git mode requires the sprint feature branch to merge into the configured local default branch, or
-  - no runnable tasks remain, or
+  - no runnable tasks remain and no sprint-scoped worker or human handoff is still active, or
   - merge-required tasks are detected that need manual intervention.
-- The checkpoint window triggers internal reports and lease renewals without stopping the run. The run pauses for human handoff (such as `CREATE_PR` mode for main-branch merges) or cancels if aborted.
+- The checkpoint window triggers internal reports and lease renewals without stopping the run. Task/QA guardrail handoffs keep the run alive so it can observe their resolution; explicit dashboard control and final main-merge policies such as `CREATE_PR` may still pause the run. Cancellation remains terminal.
 - In local-git mode, the final sprint feature-branch merge runs in a temporary Git worktree and force-updates the configured default branch after the merge succeeds. The visible project checkout is not switched between branches, so user-facing local workspaces stay on the branch the operator had checked out.
 - If that visible checkout has user-created dirty work at finalization time, Code UX first preserves that work on a `dirty-ref-<uuid>` branch, completes the clean sprint merge, and then copies the preserved dirty commit back into the visible checkout with `cherry-pick --no-commit` followed by an unstage step. Non-conflicting dirty files therefore return as ordinary uncommitted working-tree changes, not as a merge commit. If the restore conflicts or cannot be applied cleanly, Code UX aborts the restore, leaves the dirty branch intact, and opens a dashboard attention item naming the branch and affected paths. Dirty files under the repo-local `.code-ux/` directory are ignored by this preservation check so Code UX runtime artifacts do not block or alter local merges. When the checked-out target branch is the one being updated, the working tree is refreshed to match the merged commit before dirty work is restored.
 - The watch loop uses the same `task-transition-state.ts` helper as the cycle
@@ -214,7 +214,9 @@ For `action=status`:
 - Starting or resuming orchestration resolves stale sprint-level `manual_attention` escalations from prior runs. The new run recomputes current blockers, while task-specific human attention remains open until explicitly handled.
 - Before task QA gates are evaluated, the sprint cycle reconciles running task QA invocations with provider runtime state. Missing provider linkage or a missing Docker session container makes the stale QA row retryable instead of blocking the task indefinitely at `QA_PENDING`.
 - Sprint-completion QA also uses the sprint trigger's `agentPresetIds` list, or one default fallback reviewer when the list is empty. Completion is allowed only after the latest sprint QA cycle has all reviewers passed; any running, failed, or changes-requested reviewer blocks completion and a changes-requested review may route one follow-up task/session repair using the existing sprint QA follow-up logic.
-- A terminal sprint-completion QA provider failure with no changed task snapshot, or a non-passing cycle at the sprint QA retry cap, opens one sprint-scoped `human_escalation_required` handoff instead of leaving a healthy watch loop to heartbeat forever. The handoff records the attempt count, cap, reason, and latest provider error, remains deduplicated across runtime restarts, and continues to block completion. Explicitly resolving it clears only the sprint-completion QA history so the current sprint can run one fresh review cycle; task QA history and guardrail ledgers remain intact.
+- Sprint-completion QA provider/infrastructure failures retry on the next watch cycle even when the task snapshot is unchanged. Each failed cycle advances the configured `maxSprintReviewRuns` guardrail; only a non-passing cycle at that cap opens one sprint-scoped `human_escalation_required` handoff. The handoff records the attempt count, cap, reason, and latest provider error, remains deduplicated across runtime restarts, and keeps the sprint run alive while blocking completion. Explicitly resolving it clears only the sprint-completion QA history so the current sprint can run one fresh review cycle; task QA history and guardrail ledgers remain intact.
+- Codex error classification reads structured `error`/`turn.failed` events plus stderr, not ordinary JSON event payloads. Agent prose, repository fixtures, and tool output that mention authentication, quota, or rate limits therefore cannot be mistaken for the provider's failure reason.
+- Main-merge CI-fix attention records carry explicit source and target branches. A worker-owned CI repair opened during finalization is recognized in that same cycle, so the watch loop waits and keeps heartbeating until the worker succeeds or exhausts the `ci_fix` guardrail instead of pausing beside an active invocation.
 - Sprint orchestration resolves LOCAL vs REMOTE git behavior from the effective project/sprint settings (`settings.git.githubMode`). Local-git projects therefore use the local worker-to-feature merge path consistently during both single-cycle and watch-loop runs.
 - Sprint orchestration resolves providers from exact provider-config ids in effective settings. A route value such as `mockup-cli` or `gemini-fast` must correspond to a configured provider instance with that exact id; provider-type aliases no longer select arbitrary same-type instances. Sprint/project overrides that explicitly add a provider instance are preserved before route validation so isolated mockup runs cannot fall back to inherited live providers.
 - Invocation-route provider maps are replace-on-write at project and sprint scope. If a scoped setting declares `task_coding.providers`, `merge_conflict.providers`, or `qa_review.providers`, that route uses the declared provider-config ids only instead of deep-merging inherited route providers.