Files
kandev/docs/plans/queued-turn-start-state/plan.md
T

7.4 KiB
Raw Blame History

created, status, requirements, system_design, legacy_specs
created status requirements system_design legacy_specs
2026-09-09 complete
REQ-TASKS-RUNTIME-STATE-PUBLICATION-ORDER-001
../../specs/tasks/system-design/runtime-state-publication-order.md

Implementation Plan: Queued turn-start state

Overview

Keep an admitted queued turn running when its start moves the workflow step. One work order repairs the backend lifecycle and verifies the visible result. This is conformance with the existing runtime-state contract, especially AC-TASKS-RUNTIME-STATE-PUBLICATION-ORDER-001.5. Requirements need no change.

Confirmed cause and evidence

The reported task is 9f724e85-e643-4ee8-a60b-24efdb98f01b; the affected session is 8bce4cee-e40c-44f5-817b-c8e5ee48c925. Retained backend evidence was read from /root/.kandev/logs/backend-logs-2026-09-09-000007.log, lines 66351–66417. Times below are UTC on 2026-09-09; retained log timestamps use UTC+01:00.

Time Backend event
08:23:53.227 Send Now claims one queued message.
08:23:53.240 The session is published as RUNNING.
08:23:53.244 Turn 42f8517d-aee0-435e-a22d-b9b5ac5c65f2 starts.
08:23:53.254 The workflow evaluates an on_turn_start transition.
08:23:53.264 Task update publishes the destination step and RUNNING session.
08:23:53.267 The session changes from RUNNING to WAITING_FOR_INPUT.
08:23:53.280 Task state changes to REVIEW, retaining the destination step.
08:23:53.281 The executor sends the queued prompt to the agent.

promptSendNowClaim calls promptTask with an afterClaim callback. Prompt admission first sets the session running and creates its turn. The callback then calls processOnTurnStartViaEngine. applyEngineTransitionWithCommitMode, in transitionLifecycleOnTurnStart mode, unconditionally calls setSessionWaitingForInput after profile preparation. That helper also reconciles the task to Review. Prompt dispatch continues afterward without restoring the admitted session state.

The browser receives and applies these server events. The earlier primary session mismatch briefly delays card updates, but the primary session is correct before the final reversal. No delayed cancellation event is needed to explain the defect. Metadata-only state events (newState=-) are separate.

The existing workflow_e2e_test.go table includes running on_turn_start transitions but omits ExpectState on those rows.

Scope

In scope

  • Preserve current-turn ownership and running state across a successful same-session on_turn_start transition.
  • Verify Send Now and the ordinary queued-dispatch caller of the same hook.
  • Preserve pre-admission transitions, profile preparation, WIP admission, failure cleanup, and legitimate end-of-turn settlement.
  • Prove desktop and mobile receive the same corrected authoritative state.

Out of scope

  • Client-side state overrides, new state values, and changes to grouping.
  • Queue ordering, cancellation policy, schema changes, and Office ownership.
  • Changes to the reported live task or its agent process.

Technical approach

Repair the on_turn_start lifecycle branch in apps/backend/internal/orchestrator/event_handlers_workflow.go. Distinguish a transition for an already-admitted turn from preparation for a future prompt. Preserve the admitted turn when the effective session remains the same. Keep profile-switch and failure behavior explicit; do not remove all waiting-state writes across lifecycle modes.

The implementation uses the session state and effective session ID already available in the lifecycle branch. No new context parameter or turn registry is necessary. The per-session cancellation guard and queue claim order remain unchanged. The hook does not write RUNNING afterward, so it cannot revive a cancelled turn.

The implementation must not depend on a later activity event healing the state. The existing task publication order and client freshness design remain valid.

Tests

Add queue_send_now_workflow_state_test.go with TestSendNowWorkflowTransitionPreservesRunningState. Use the real queue, workflow engine, prompt admission, and repository with a controllable executor. Inspect state synchronously inside the fake provider dispatch, before it returns. Assert session RUNNING, task IN_PROGRESS, the target workflow step, an active turn, and one prompt. Capture lifecycle publications and reject any waiting/review reversal before dispatch returns.

Add paired tests for the pre-admission hook and ordinary FIFO callback. Retain coverage for profile changes, WIP deferral, failed dispatch, explicit cancellation, and genuine turn completion. Strengthen the existing workflow table's on_turn_start rows with state assertions.

These checks cover AC-TASKS-RUNTIME-STATE-PUBLICATION-ORDER-001.1, .2, .5, and .8. Desktop/mobile evidence covers .6.

E2E tests

Extend apps/web/e2e/tests/chat/message-queue.spec.ts with Send Now keeps a workflow transition running. Start from a settled session with a queued slow prompt and a Review-to-In-Progress on_turn_start action. Click Send Now and assert the running composer and State-grouped sidebar before completion, without reloading. Assert legitimate settlement afterward.

Extend apps/web/e2e/tests/chat/mobile-message-queue-management.spec.ts with the same scenario using the existing touch queue control and task switcher. Shared data semantics are the mobile requirement; layout and navigation stay within the existing composition. Reuse the existing queue test fixtures.

Work orders

Verification results

The Send Now and FIFO regressions first failed with WAITING_FOR_INPUT instead of RUNNING at provider dispatch. Both pass after the lifecycle fix. The pre-admission case and strengthened workflow table also pass.

The following targeted orchestrator groups passed with -race -tags fts5:

  • Test.*(SendNow|SendQueuedNow|Queued|Workflow|OnTurnStart|PromptTask|Cancel)
  • Test.*(ApplyEngineTransition|PrepareWorkflowStepSession|SwitchSessionForProfile|WIP|Wip)
  • Test(SwitchSessionForStep|ProcessOnEnter_ProfileSwitch)

Desktop Chromium: two Send Now tests passed. Mobile Chrome: two Send Now tests passed. These include the new workflow regression and existing priority-order coverage on each platform. The new cases verify the running composer, State grouping, authoritative session/task state, and legitimate completion without a reload.

The initial browser failures exposed test-fixture issues: buffered mock text needed a tool boundary, and the mobile filter trigger needed drawer scope. The corrected fixtures pass. Focused ESLint and Prettier checks also pass.

Managed E2E runs used disposable containers and mock agents. The first run built the artifacts. Later runs reused those artifacts with --no-build. The runners removed their containers after each run. The reported live task, session, and runtime were not changed.

Public docs need no change. This fix restores the behavior already described in docs/public/sessions-and-review.md and the runtime-state specification.

Risks

  • The shared hook runs both before and after prompt admission; a blanket change could make a prepared session busy without a dispatched prompt.
  • Profile switching can replace the effective session. Never transfer the old session's running state to an unstarted replacement.
  • WIP deferral and genuine cancellation must still prevent dispatch or settle the correct turn.