qdaxb · Aug 20, 2026 · Aug 19, 2026 · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026
diff --git a/docs/en/architecture/README.md b/docs/en/architecture/README.md
@@ -6,22 +6,23 @@ sidebar_position: 1
 
 Before changing a flow below, update its connection graph, sequence diagram, code ownership, and essential invariants, confirm that the path is complete, and only then change code. Keep one independently maintained file per topic; add one file and one catalog row for a new governed flow.
 
-| Logic                                              | Architecture file                                                            | Change scope                                                                                                  |
-| -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Board automation and Wegent execution              | [board-automation.md](board-automation.md)                                   | Assignment, execution truth, runtime activation, continuation, cancellation, terminal projection              |
-| Custom AI manager comment continuation             | [automation-manager-continuation.md](automation-manager-continuation.md)     | Comment identity, execution binding, runtime-session continuation, task-state isolation                       |
-| Embedded-browser navigation and tabs               | [embedded-browser.md](embedded-browser.md)                                   | Bridge routing, pending open, WebView lifecycle, navigation completion, multi-tab E2E                         |
-| Issue, task, and workflow orchestration            | [issue-task-workflow.md](issue-task-workflow.md)                             | Issue aggregation, task binding, workspace inheritance, DAG readiness, status aggregation                     |
-| Issue Runtime status, delivery, and UI projection  | [issue-runtime-delivery-projection.md](issue-runtime-delivery-projection.md) | Runtime terminal persistence, stage aggregation, Delivery fulfillment, invalidation, Issue-detail consistency |
-| Workflow stage deliverables and dependency context | [workflow-stage-deliverables.md](workflow-stage-deliverables.md)             | Structured requirements, manual and automated gates, code evidence, successor input snapshots                 |
-| Workflow stage execution routing                   | [workflow-stage-execution-routing.md](workflow-stage-execution-routing.md)   | Human start, cloud dispatch, local/cloud device routing, unified stage execution contract                     |
-| Project-space Agent capability                     | [project-space-agent-capability.md](project-space-agent-capability.md)       | Local Gateway, ContextGrant, Codex Plugin, offline provider, MCP lifecycle                                    |
-| Project execution state and Runtime capacity       | [project-execution-state.md](project-execution-state.md)                     | Claim, event ordering, cancellation, retry, lease, concurrency capacity, UI projection                        |
-| Git Worktree execution                             | [git-worktree-execution.md](git-worktree-execution.md)                       | Device routing, capability, preflight, queued creation, lifecycle, persistence, UI projection                 |
-| Text-model vision delegation                       | [model-vision-delegation.md](model-vision-delegation.md)                     | Explicit model reference, catalog capability, sidecar configuration, image replacement, failure isolation     |
-| Wework host plugin runtime                         | [workbench-plugin-runtime.md](workbench-plugin-runtime.md)                   | Profile composition, services and UI slots, dynamic modules, sidecars, teardown, and recovery                 |
-| Smart apps (DeepSeek Harness runtime)              | [deepseek-harness-apps.md](deepseek-harness-apps.md)                         | Application-type navigation, package validation, version binding, model proxying, instances, tabs, and cleanup |
-| IM private-chat runtime streaming                  | [im-runtime-streaming.md](im-runtime-streaming.md)                           | Callback key, `runtime:event` envelope, relay and IM forwarding, terminal event, failure isolation            |
-| Codex notification isolation                       | [codex-notification-routing.md](codex-notification-routing.md)               | Shared app-server, thread routing, burst isolation, process exit, terminal projection                         |
+| Logic                                              | Architecture file                                                                    | Change scope                                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Board automation and Wegent execution              | [board-automation.md](board-automation.md)                                           | Assignment, execution truth, runtime activation, continuation, cancellation, terminal projection              |
+| Custom AI manager comment continuation             | [automation-manager-continuation.md](automation-manager-continuation.md)             | Comment identity, execution binding, runtime-session continuation, task-state isolation                       |
+| Embedded-browser navigation and tabs               | [embedded-browser.md](embedded-browser.md)                                           | Bridge routing, pending open, WebView lifecycle, navigation completion, multi-tab E2E                         |
+| Issue, task, and workflow orchestration            | [issue-task-workflow.md](issue-task-workflow.md)                                     | Issue aggregation, task binding, workspace inheritance, DAG readiness, status aggregation                     |
+| Issue Runtime status, delivery, and UI projection  | [issue-runtime-delivery-projection.md](issue-runtime-delivery-projection.md)         | Runtime terminal persistence, stage aggregation, Delivery fulfillment, invalidation, Issue-detail consistency |
+| Workflow stage deliverables and dependency context | [workflow-stage-deliverables.md](workflow-stage-deliverables.md)                     | Structured requirements, manual and automated gates, code evidence, successor input snapshots                 |
+| Workflow stage execution routing                   | [workflow-stage-execution-routing.md](workflow-stage-execution-routing.md)           | Human start, cloud dispatch, local/cloud device routing, unified stage execution contract                     |
+| Project-space Agent capability                     | [project-space-agent-capability.md](project-space-agent-capability.md)               | Local Gateway, ContextGrant, Codex Plugin, offline provider, MCP lifecycle                                    |
+| Project execution state and Runtime capacity       | [project-execution-state.md](project-execution-state.md)                             | Claim, event ordering, cancellation, retry, lease, concurrency capacity, UI projection                        |
+| Git Worktree execution                             | [git-worktree-execution.md](git-worktree-execution.md)                               | Device routing, capability, preflight, queued creation, lifecycle, persistence, UI projection                 |
+| Text-model vision delegation                       | [model-vision-delegation.md](model-vision-delegation.md)                             | Explicit model reference, catalog capability, sidecar configuration, image replacement, failure isolation     |
+| Wework host plugin runtime                         | [workbench-plugin-runtime.md](workbench-plugin-runtime.md)                           | Profile composition, services and UI slots, dynamic modules, sidecars, teardown, and recovery                 |
+| Smart apps (DeepSeek Harness runtime)              | [deepseek-harness-apps.md](deepseek-harness-apps.md)                                 | Application-type navigation, package validation, version binding, model proxying, instances, tabs, and cleanup |
+| IM private-chat runtime streaming                  | [im-runtime-streaming.md](im-runtime-streaming.md)                                   | Callback key, `runtime:event` envelope, relay and IM forwarding, terminal event, failure isolation            |
+| Codex notification isolation                       | [codex-notification-routing.md](codex-notification-routing.md)                       | Shared app-server, thread routing, burst isolation, process exit, terminal projection                         |
+| Runtime task lifecycle reconciliation              | [runtime-task-lifecycle-reconciliation.md](runtime-task-lifecycle-reconciliation.md) | Event stream, lag detection, anomaly reconciliation, terminal projection, transcript-read boundary            |
 
 Detailed product prose remains in the existing developer guides. This directory contains only reviewable architecture truth.
diff --git a/docs/en/architecture/runtime-task-lifecycle-reconciliation.md b/docs/en/architecture/runtime-task-lifecycle-reconciliation.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 8
+---
+
+# Runtime task lifecycle reconciliation
+
+## Scope
+
+Governs how Wework consumes Runtime task events, detects a potentially stale local projection, and recovers authoritative task state without polling transcripts.
+
+## Connection graph
+
+```mermaid
+flowchart LR
+    EXEC[Executor task state] --> STREAM[Runtime event stream]
+    STREAM --> STORE[Lifecycle Store]
+    STORE --> UI[Running-state UI projection]
+    STREAM --> TERMINAL[Terminal event]
+    TERMINAL --> STORE
+    STREAM --> SIGNAL[Lag or transport replacement]
+    SIGNAL --> LIST[runtime.tasks.list]
+    LIST --> STORE
+    TRANSCRIPT[runtime.tasks.transcript] -. User opens chat or requests message sync .-> UI
+```
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+    participant E as Executor
+    participant S as Runtime event stream
+    participant C as Lifecycle Coordinator
+    participant L as Lifecycle Store
+
+    E-->>S: task/turn events
+    S-->>L: Incremental projection
+    alt No terminal or anomaly signal
+        Note over C: No state polling
+    else terminal event
+        S-->>C: response.completed / failed / incomplete
+        C->>L: turnSettled
+    else executor.event_lagged or runtime transport replacement
+        S-->>C: Projection may be stale
+        C->>E: runtime.tasks.list
+        E-->>C: Persisted task snapshot
+        C->>L: syncRuntimeWork
+    end
+```
+
+## Code ownership
+
+| Responsibility                                | Code                                                                                           |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Local Executor event bridge and service reuse | `wework/src/api/local/localServices.ts`, `wework/src/api/runtime/runtimeChatStream.ts`         |
+| Hybrid stream handler routing                 | `wework/src/api/hybrid/hybridServices.ts`                                                      |
+| Event-driven reconciliation coordinator       | `wework/src/features/workbench/runtimeTaskLifecycle/RuntimeTaskLifecycleStreamCoordinator.tsx` |
+| Lifecycle truth projection                    | `wework/src/features/workbench/runtimeTaskLifecycle/RuntimeTaskLifecycleStore.ts`              |
+| Executor task list and transcript             | `executor/src/runtime_work/handler/queries.rs`                                                 |
+
+## Essential invariants
+
+- The normal lifecycle consumes only the event stream and never reads task lists or transcripts on a timer.
+- The same underlying local Executor transport must reuse one Runtime event stream. Preference refreshes or equivalent identity objects must not rebuild its native listener, which would accumulate listeners and create a terminal-event gap while subscriptions move.
+- A terminal event directly settles the shared lifecycle store by `deviceId + taskId`. The resident coordinator must not depend on a mounted pane or overwrite that terminal signal with a task list read immediately after the event, because the Executor and provider list projections may still be finishing the same turn.
+- `executor.event_lagged` and runtime transport replacement also trigger reconciliation because they explicitly indicate that the local projection may be stale.
+- Concurrent anomaly signals share one in-flight reconciliation request; new signals during that request coalesce into at most one serial trailing reconciliation and never create a concurrent request burst or timed retry loop.
+- Terminal task state is projected from Executor persistence fields, never inferred from transcripts, turn items, or rollout JSONL.
+- Transcript reads serve only user-visible chat loading or explicit message synchronization; they are not lifecycle heartbeats.
diff --git a/docs/en/wegent/developer-guide/runtime-local-work.md b/docs/en/wegent/developer-guide/runtime-local-work.md
@@ -138,6 +138,8 @@ Task summaries from `runtime.tasks.list`, task creation responses, stream events
 
 The completion flow is therefore singular: an executor/Backend task snapshot or terminal stream event enters the shared lifecycle store, the projection converges to idle, and every UI consumer removes its running state from the same store update.
 
+Wework must not periodically read transcripts for running tasks to detect a missed terminal event. The normal lifecycle consumes only the stream. The resident coordinator settles the shared lifecycle store directly from a terminal event's `deviceId + taskId`, so completion does not depend on a mounted task pane and cannot be overwritten by a task-list read that arrives while the Executor and provider are still finishing the same turn. Only explicit stale-projection signals such as `executor.event_lagged` and runtime transport replacement trigger one `runtime.tasks.list` reconciliation. Concurrent anomaly signals share one in-flight request, and signals received while it is in flight coalesce into at most one serial trailing reconciliation. Reconciliation uses the executor's persisted `running`, `status`, `completedAt`, `threadStatus`, and `turnStatus` fields directly; it must not derive task completion from transcripts, turn items, or rollout JSONL.
+
 Every continuation request must carry the current model selection. The Wework model selector is the source of truth for the turn being sent: whichever model the user selects for that turn becomes the `modelId`, `modelType`, and model options in `runtime.tasks.send`. The executor must not restore a model from a previous request and must not cache model selection. If a request has neither a full `executionRequest` nor a `modelId`, the executor must return `bad_request` instead of falling back to a default model. Local IPC and remote WebSocket only transport the same canonical model selection; local devices invoking remote models and remote devices invoking remote models both enter the same executor backend execution logic. Task creation and continuation must reuse that single model selection path.
 
 If the current LocalTask is still replying, Wework queues new user input locally instead of sending concurrent `runtime.tasks.send` calls. Users can remove queued messages, or choose to stop the current reply and send the queued message from the queue panel. That first calls: