144 lines
6.5 KiB
Markdown
144 lines
6.5 KiB
Markdown
---
|
|
spec: docs/specs/tasks/requirements/runtime-state-publication-order.md
|
|
created: 2026-07-30
|
|
status: complete
|
|
---
|
|
|
|
# Implementation Plan: Runtime Task-State Publication Order
|
|
|
|
## Overview
|
|
|
|
Close the confirmed event-ordering window without changing task-state meaning
|
|
or frontend grouping. The orchestrator will reconcile a successfully
|
|
transitioned session's owning task inside the existing pre-publication hook,
|
|
then publish the running session event. Focused Go tests will prove the event
|
|
order, persistence result, race guards, and no-redundant-write behavior.
|
|
|
|
The confirmed root cause is that `setSessionRunningForExecution` currently
|
|
publishes `session.state_changed(RUNNING)` from `updateTaskSessionState` and only
|
|
then calls `reconcileTaskStateForRuntimeLocked`. The sidebar immediately paints
|
|
the running session indicator while Group by State still reads persisted
|
|
`tasks.state = REVIEW`.
|
|
|
|
The remote-delivery path also requires the gateway to preserve this ordering:
|
|
task and session lifecycle notifications share one NATS-style subscription so
|
|
separate callback scheduling cannot reintroduce the race before WebSocket
|
|
delivery.
|
|
|
|
## Backend
|
|
|
|
### Runtime transition ordering
|
|
|
|
- Update `setSessionRunningForExecution` in
|
|
`apps/backend/internal/orchestrator/event_handlers_streaming.go` to use
|
|
`updateTaskSessionStateWithHook`.
|
|
- Run `reconcileTaskStateForRuntimeLocked` from the hook after the session
|
|
compare-and-set succeeds but before `publishTaskSessionStateChanged`.
|
|
- Capture and log reconciliation errors without rolling back or suppressing the
|
|
truthful session transition.
|
|
- Remove the post-publication reconciliation call for the changed-state path.
|
|
- Preserve the `wasAlreadyRunning` fast path so repeated tool/stream events do
|
|
not perform task-state reads or writes.
|
|
- Keep `writeTaskInProgressForRuntime` and the executor-success callback as the
|
|
eventual healing path.
|
|
|
|
### Gateway delivery ordering
|
|
|
|
- Subscribe the WebSocket task broadcaster to one NATS-style wildcard for task
|
|
and session state events, resolving the WebSocket action from `event.Type`.
|
|
- Keep all other event subscriptions and routing behavior unchanged.
|
|
- Ensure the in-memory event bus implements the same `>` wildcard semantics so
|
|
local development and regression tests exercise the production contract.
|
|
|
|
### Event and persistence contract
|
|
|
|
- Continue using `UpdateTaskStateIfSessionState` so the session state, archive
|
|
status, terminal transitions, clarification/cancellation races, and Office
|
|
exclusion remain guarded by existing code.
|
|
- Do not add a schema, API field, WebSocket event, frontend-derived task state,
|
|
or new in-memory lifecycle cache.
|
|
|
|
## Frontend
|
|
|
|
No frontend production change is planned. Group by State must continue to use
|
|
persisted `task.state`, while the shared desktop/mobile task row continues to
|
|
render live session activity. Correct backend event order makes those existing
|
|
contracts converge.
|
|
|
|
Mobile parity is state-only: the desktop sidebar and phone task drawer use the
|
|
same sidebar task aggregation and `TaskItem` rendering. There is no composition,
|
|
navigation, scroll, safe-area, pointer, or touch-target change.
|
|
|
|
## Tests
|
|
|
|
- **What:** a real `WAITING_FOR_INPUT -> RUNNING` transition persists
|
|
`tasks.state = IN_PROGRESS` before observers receive the running session
|
|
event.
|
|
**File:**
|
|
`apps/backend/internal/orchestrator/event_handlers_streaming_test.go`.
|
|
**How:** use the SQLite test repository, the real task service, and one
|
|
recording/memory event bus; subscribe to task/session state events and assert
|
|
both durable state and event order.
|
|
- **What:** the regression test fails on the current implementation because
|
|
`session.state_changed(RUNNING)` is observed while the task is still
|
|
`REVIEW`.
|
|
**File:**
|
|
`apps/backend/internal/orchestrator/event_handlers_streaming_test.go`.
|
|
**How:** record task and session state events through the real task service
|
|
rather than relying on sleeps or browser rendering.
|
|
- **What:** same-state stream churn remains deduplicated.
|
|
**File:**
|
|
`apps/backend/internal/orchestrator/event_handlers_streaming_test.go`.
|
|
**How:** retain and run `TestSetSessionRunning_NoRedundantTaskWrites`; extend
|
|
it only if needed to assert no state event.
|
|
- **What:** clarification/cancellation and archive races cannot be overwritten.
|
|
**Files:**
|
|
`apps/backend/internal/orchestrator/event_handlers_runtime_state_race_test.go`
|
|
and `apps/backend/internal/task/repository/sqlite/task_state_cas_test.go`.
|
|
**How:** run the existing guarded-CAS regression tests alongside the new
|
|
ordering test, including `-race`.
|
|
- **What:** gateway delivery keeps task-state notification ahead of the
|
|
running-session notification for a shared wildcard subscription.
|
|
**Files:** `apps/backend/internal/gateway/websocket/task_notifications.go`,
|
|
`apps/backend/internal/gateway/websocket/task_notifications_test.go`, and
|
|
`apps/backend/internal/events/bus/memory_test.go`.
|
|
**How:** assert lifecycle subjects use one wildcard, publish both events
|
|
through the in-memory NATS-compatible bus, and assert WebSocket action order.
|
|
|
|
## E2E Tests
|
|
|
|
No permanent browser test is planned. The repaired behavior is the absence of
|
|
an intermediate render between two WebSocket events; a Playwright
|
|
`MutationObserver` or polling assertion would be scheduler-dependent and could
|
|
pass on the broken implementation when React batches both events. The
|
|
producer-level integration test deterministically observes the same contract
|
|
at the event boundary.
|
|
|
|
Existing frontend tests already pin the unchanged display semantics:
|
|
|
|
- `apps/web/lib/sidebar/apply-view.test.ts` proves State grouping uses persisted
|
|
task state.
|
|
- `apps/web/components/task/task-item.test.tsx` proves running session activity
|
|
selects the spinner.
|
|
- `apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts`
|
|
proves the phone drawer uses the shared task-row status rendering.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1:
|
|
|
|
- [ ] [Task 01: Order runtime state publication](task-01-order-runtime-state-publication.md)
|
|
|
|
The task is sequential because production ordering and its regression test
|
|
touch the same orchestrator lifecycle seam. No subagent authorization is
|
|
implied.
|
|
|
|
## Risks
|
|
|
|
- Publishing task state first changes event order for clients that observe both
|
|
subjects. Payloads and final states are unchanged.
|
|
- Reconciliation errors must not suppress a truthful running-session event.
|
|
- The pre-publication hook runs while the task runtime-state mutex is held;
|
|
implementation must call the existing locked reconciliation helper and must
|
|
not reacquire that mutex.
|