fix: preserve orchestration sessions across restarts

docs-web/architecture/virtual-workers.md

@@ -120,6 +120,10 @@ Docker-backed planning uses a read-only snapshot workspace instead of a mutable
 
 Provider CLI workspace preparation is centralized through `InvocationWorkspacePreparer`. Its shared provider-invocation option builder constructs snapshot checkout, git policy, and fresh/continue lifecycle values for Docker provider calls, while its continuation resolver locates preserved workspaces and their current branches. Fresh Docker invocations in `REMOTE` git mode use explicit remote refs only: planning, project setup, dashboard/chat replies, worker inbox replies, node-flow provider prompts, QA review snapshots, task coding, QA follow-up, CI autofix, and merge-conflict repair all materialize from `origin/<branch>` refs rather than local branches or the host repo's current checkout. Dashboard/chat replies resolve dashboard settings with the project scope before building this policy, so local Git projects keep `LOCAL` snapshot behavior and do not require `origin/<defaultBranch>`. Continuation/restart flows may reuse a preserved workspace for provider-session continuity; if a preserved workspace is missing and a new workspace must be materialized, the same remote-only branch policy applies.
 
+QA reviewers, standalone CI-fix workers, and merge-conflict workers checkpoint their own logical session and workspace before provider execution. Under restart invocation policy `continue`, the replacement invocation reuses that workspace and resumes the provider-native conversation when available. Merge-conflict continuation also recognizes an in-progress Git merge and continues resolving it instead of replaying the merge operation.
+
+CI-fix and merge-conflict repair checkpoints retain the original workspace Git baseline, the finalized repair head, and the host-publication phase. A restart after provider or merge completion exports from that original baseline and resumes publication instead of treating the repair commit as a new baseline, rerunning the provider, or replaying the merge. Merge recovery also recognizes a completed merge commit by its target-branch ancestry when the restart landed immediately before the finalization checkpoint. Host publication commits carry the repair head as a trailer; recovery from `host_publishing` finds that marker and idempotently pushes the existing remote branch before settlement, preventing a second patch application when the process exited after materialization but before the `host_published` checkpoint. For legacy unmarked publications, Code UX derives the effective workspace tree including uncommitted and newly created files and searches matching reachable repair commits even if the branch later advanced. Settlement requires the exact repair tree and subject, baseline ancestry, and the target parent for merge repairs.
+
 Docker-volume artifact export performs Git discovery, staging, binary diffing, and temporary-index cleanup in one helper-container invocation instead of paying four or five Docker control-plane round trips per completed task. Host-side patch transaction files live under Git's administrative directory so materialization stays on the warm project Git helper rather than creating one-shot helpers for external temporary binds. When a LOCAL branch advances while an isolated worker is running, patch materialization applies the diff against its true workspace base and three-way merges the resulting tree onto the current descendant tip. Concurrent work is retained, identical already-landed file additions are de-duplicated, and genuine overlapping edits remain conflicts.
 
 ## Session lifecycle
@@ -174,6 +178,8 @@ The virtual worker can claim and act on these attention item categories:
 
 Repair attention is scheduled before ordinary coding dispatches. Code UX does not lease a coding task while CI-fix or merge-conflict attention is waiting, and capacity is checked against the provider selected by the invocation-specific route rather than the generic virtual-worker provider. The final provider-slot wait is bounded to 30 seconds so sprint finalization cannot wait forever on a saturated or stale route.
 
+Startup recovery releases `ci_fix_required` and `merge_conflict` items claimed by stopped virtual-worker endpoints and returns them to the queue with their repair-session checkpoint intact. Continuing that same interrupted attempt does not spend another guardrail attempt. Retryable interruption preserves the repair workspace; terminal success or exhaustion follows normal cleanup.
+
 Task-scoped CI repair continues the originating coding session, native provider session, effective model, coding-agent instructions, and preserved workspace by default. Settings → AI Models → CI fix can disable this behavior and force the standalone CI Fix route; sprint-level final-merge repair always uses that route. Failed invocations return attention to an unclaimed retryable state while the guardrail budget remains. When the default five-attempt limit is reached, Code UX creates a human handoff containing the last error and attempt count.
 
 Immediately before every Docker provider launch attempt, Code UX reasserts runtime-volume ownership for the container's effective non-root UID/GID. This repairs newly created, stale, or concurrently recreated root-owned provider HOME/cache volumes at the atomic `docker run` boundary, including standalone final-merge CI repair. Workspace seed helpers explicitly trust mounted `/workspace` while initializing Git and then restore the provider UID/GID, so restart recovery does not trip Git's dubious-ownership protection on a correctly non-root-owned volume.

docs-web/content/docs/architecture-virtual-workers.mdx

@@ -120,6 +120,10 @@ Docker-backed planning uses a read-only snapshot workspace instead of a mutable
 
 Provider CLI workspace preparation is centralized through `InvocationWorkspacePreparer`. Its shared provider-invocation option builder constructs snapshot checkout, git policy, and fresh/continue lifecycle values for Docker provider calls, while its continuation resolver locates preserved workspaces and their current branches. Fresh Docker invocations in `REMOTE` git mode use explicit remote refs only: planning, project setup, dashboard/chat replies, worker inbox replies, node-flow provider prompts, QA review snapshots, task coding, QA follow-up, CI autofix, and merge-conflict repair all materialize from `origin/<branch>` refs rather than local branches or the host repo's current checkout. Dashboard/chat replies resolve dashboard settings with the project scope before building this policy, so local Git projects keep `LOCAL` snapshot behavior and do not require `origin/<defaultBranch>`. Continuation/restart flows may reuse a preserved workspace for provider-session continuity; if a preserved workspace is missing and a new workspace must be materialized, the same remote-only branch policy applies.
 
+QA reviewers, standalone CI-fix workers, and merge-conflict workers checkpoint their own logical session and workspace before provider execution. Under restart invocation policy `continue`, the replacement invocation reuses that workspace and resumes the provider-native conversation when available. Merge-conflict continuation also recognizes an in-progress Git merge and continues resolving it instead of replaying the merge operation.
+
+CI-fix and merge-conflict repair checkpoints retain the original workspace Git baseline, the finalized repair head, and the host-publication phase. A restart after provider or merge completion exports from that original baseline and resumes publication instead of treating the repair commit as a new baseline, rerunning the provider, or replaying the merge. Merge recovery also recognizes a completed merge commit by its target-branch ancestry when the restart landed immediately before the finalization checkpoint. Host publication commits carry the repair head as a trailer; recovery from `host_publishing` finds that marker and idempotently pushes the existing remote branch before settlement, preventing a second patch application when the process exited after materialization but before the `host_published` checkpoint. For legacy unmarked publications, Code UX derives the effective workspace tree including uncommitted and newly created files and searches matching reachable repair commits even if the branch later advanced. Settlement requires the exact repair tree and subject, baseline ancestry, and the target parent for merge repairs.
+
 Docker-volume artifact export performs Git discovery, staging, binary diffing, and temporary-index cleanup in one helper-container invocation instead of paying four or five Docker control-plane round trips per completed task. Host-side patch transaction files live under Git's administrative directory so materialization stays on the warm project Git helper rather than creating one-shot helpers for external temporary binds. When a LOCAL branch advances while an isolated worker is running, patch materialization applies the diff against its true workspace base and three-way merges the resulting tree onto the current descendant tip. Concurrent work is retained, identical already-landed file additions are de-duplicated, and genuine overlapping edits remain conflicts.
 
 ## Session lifecycle
@@ -174,6 +178,8 @@ The virtual worker can claim and act on these attention item categories:
 
 Repair attention is scheduled before ordinary coding dispatches. Code UX does not lease a coding task while CI-fix or merge-conflict attention is waiting, and capacity is checked against the provider selected by the invocation-specific route rather than the generic virtual-worker provider. The final provider-slot wait is bounded to 30 seconds so sprint finalization cannot wait forever on a saturated or stale route.
 
+Startup recovery releases `ci_fix_required` and `merge_conflict` items claimed by stopped virtual-worker endpoints and returns them to the queue with their repair-session checkpoint intact. Continuing that same interrupted attempt does not spend another guardrail attempt. Retryable interruption preserves the repair workspace; terminal success or exhaustion follows normal cleanup.
+
 Task-scoped CI repair continues the originating coding session, native provider session, effective model, coding-agent instructions, and preserved workspace by default. Settings → AI Models → CI fix can disable this behavior and force the standalone CI Fix route; sprint-level final-merge repair always uses that route. Failed invocations return attention to an unclaimed retryable state while the guardrail budget remains. When the default five-attempt limit is reached, Code UX creates a human handoff containing the last error and attempt count.
 
 Immediately before every Docker provider launch attempt, Code UX reasserts runtime-volume ownership for the container's effective non-root UID/GID. This repairs newly created, stale, or concurrently recreated root-owned provider HOME/cache volumes at the atomic `docker run` boundary, including standalone final-merge CI repair. Workspace seed helpers explicitly trust mounted `/workspace` while initializing Git and then restore the provider UID/GID, so restart recovery does not trip Git's dubious-ownership protection on a correctly non-root-owned volume.

docs-web/content/docs/settings-restart-behavior.mdx

@@ -15,12 +15,32 @@ Use it when you are configuring a new project, auditing inherited settings, or d
 
 Sprint policy continues, pauses, or cancels active sprints; invocation policy continues, cancels, or restarts interrupted work.
 
+The invocation policy applies to every provider-backed orchestration stage, not only task coding. Under `continue`, Code UX durably resumes task coding, QA review, QA-requested coding follow-up, CI-fix, and merge-conflict work from their recorded logical session and workspace. When the provider exposed a resumable native session, the replacement invocation continues that native conversation as well.
+
 | Control Surface | Runtime Effect | Review Before Saving |
 | --- | --- | --- |
 | Settings card fields | Updates the active Settings scope after you save the page. | Confirm whether you are editing System or Project scope. |
 | Inherited values | Values can flow from system defaults into project and sprint behavior. | Check the source badge before assuming a value is project-specific. |
 | Related runtime paths | The affected service reads the saved settings during planning, dispatch, dashboard rendering, or maintenance work. | Re-run the affected workflow after changing operational settings. |
 
+### Continue-policy recovery contract
+
+When `restartSprintPolicy = continue` and `restartInvocationPolicy = continue`, startup recovery:
+
+- resumes the existing sprint run and watch loop instead of creating a replacement sprint run
+- correlates each interrupted QA reviewer with its exact execution invocation, reviewer preset, logical provider session, and isolated review workspace
+- reuses the QA review workspace and provider conversation for the retry, so a restart does not discard reviewer investigation already completed before the interruption
+- checkpoints every configured reviewer in a multi-reviewer cycle before invoking the first reviewer; recovery keeps completed verdicts, resumes only interrupted reviewers, and fills any reviewer row missing from a legacy partial cycle without spending another QA cycle
+- preserves task-level and sprint-completion `changes_requested` verdicts before starting their coding handoffs; if restart occurs between the verdict and the follow-up invocation, the next cycle resumes that pending handoff instead of leaving QA indefinitely blocked
+- returns an abruptly failed QA coding handoff to `CODING_COMPLETED`/`QA_PENDING` and retries it from the recorded coding session and workspace. A successful or reconciled handoff remains in that verification-ready state until the next QA review starts, preventing the restart window from launching unrelated coding work. Provider failures are bounded to three continuation attempts, while resuming a `running` checkpoint after a runtime restart does not consume another failure allowance; exhaustion then follows the configured QA exhaustion policy instead of redispatching the task as unrelated coding or heartbeating forever.
+- records the original worker-branch baseline before invoking a QA coding follow-up and reuses it after restart, so provider commits made before host-branch publication are still exported and published instead of being mistaken for an empty follow-up
+- reconciles the recovered coding task-run and dispatch after a successful handoff, preventing an earlier transient failure marker from incorrectly failing the sprint during terminal evaluation
+- requeues interrupted worker-owned CI-fix and merge-conflict attention, clearing ownership left by the stopped virtual worker
+- closes the stopped repair attempt's provider-usage row before requeueing it, so a hard restart cannot leave a stale invocation occupying the provider concurrency limit. A durable `workspace_finalized`, `host_publishing`, or `host_published` checkpoint proves that the provider returned successfully, so recovery records that attempt as completed; an attempt interrupted before that boundary is recorded as cancelled.
+- resumes those repair workers with the same logical session, native provider session when available, and preserved workspace, so uncommitted repair progress survives the process boundary
+
+Recovery creates a correlated continuation invocation only when provider work was interrupted. When provider work already completed, recovery continues publication or attention finalization from the durable checkpoint without calling the provider again. A cancelled audit attempt therefore does not mean the logical work was abandoned, while a completed attempt remains visible as completed across the restart.
+
 ## Recommended Configuration
 
 Continue sprints and continue invocations for local development; pause when you want manual review after downtime.
@@ -35,6 +55,8 @@ A practical review flow is:
 
 Restarting interrupted work can duplicate provider effort if the previous CLI run was still externally active.
 
+The continuation guarantee depends on the provider's resumable session support and on the workspace volume still being available. Code UX preserves managed workspace volumes during a normal shutdown and fails closed when it cannot safely recover required Git state; manually deleting Docker volumes or provider-side conversations removes information the runtime cannot reconstruct.
+
 Before applying changes, check:
 
 - Whether the value affects provider credentials, Docker runtime behavior, Git automation, memory retention, or destructive cleanup.
@@ -49,6 +71,8 @@ If the saved setting does not appear to take effect:
 - Check for a project or sprint override that takes precedence over the system value.
 - Refresh the affected dashboard page if the setting controls a rendered surface.
 - Restart the local runtime only when the setting explicitly controls startup, listener, or process-level behavior.
+- For a task parked at `QA_PENDING`, inspect the latest QA row for a pending fix handoff and confirm that a correlated `cli_task_followup` invocation was resumed or already completed.
+- For CI-fix or merge-conflict work, confirm the attention item returned to the queue after startup and that its continuation invocation retained the prior workspace/session identifiers.
 
 ## Related Documentation
 

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

@@ -122,6 +122,8 @@ If a QA agent preset is wired to `qa_review` in routing, completed tasks pass th
 
 Provider or infrastructure errors do not immediately create this handoff. Recovered failed, cancelled, and errored attempts retry within a bounded infrastructure grace, and every terminal attempt counts toward the hard ceiling. A CLI QA fix that produces no new patch is escalated as no progress instead of starting another QA cycle; existing branch commits do not renew the cycle. A coding run that produces no changes must explicitly confirm completion or it is blocked for attention. The sprint watch loop stays alive while worker or human attention is active.
 
+QA review has its own durable session, separate from the coding session that receives fixes. With the restart invocation policy set to `continue`, Code UX resumes an interrupted reviewer in the same isolated review workspace and continues the provider conversation when the provider supports native session resumption. A requested-fix verdict is saved before its coding handoff starts. If restart lands in that gap, the next watch cycle resumes the pending handoff; if the coding follow-up already completed, Code UX advances to verification without repeating it. An abruptly failed coding handoff returns to the saved QA checkpoint and retries the same coding session/workspace up to the bounded continuation limit before applying the configured QA exhaustion policy.
+
 Task and sprint summary badges select one reviewer from the newest QA cycle. Within that cycle, running reviews appear first, followed by requested changes, provider failures (`failed`, `cancelled`, or `errored`), passes, and other states. This keeps a passing reviewer from hiding another reviewer that is still active, has blocked the work, or did not return a usable verdict.
 
 ## Attention items: who handles them
@@ -137,6 +139,8 @@ The eligible attention items per provider:
 
 Humans can claim and resolve items at any time from the dashboard.
 
+Under the restart `continue` policy, an interrupted Code UX-owned CI-fix or merge-conflict item is released from the stopped virtual worker and returned to the worker queue. Its replacement invocation reuses the prior logical session and repair workspace, and resumes the provider-native conversation when available. This preserves partial edits and provider reasoning across a normal runtime restart instead of spending a new guardrail attempt on the same interrupted work.
+
 ## Recommended settings recipes
 
 ### Conservative (recommended starting point)