kandev/docs/plans/session-ceiling-opt-in/task-03-queue-limit-navigation.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
03-queue-limit-navigation	Explain queue limits and link configuration	completed	3	02-settings-surface	plan.md	REQ-TASKS-QUEUED-SESSION-OWNERSHIP-003 REQ-TASKS-WIP-LIMIT-PULL-SYSTEM-001	AC-TASKS-QUEUED-SESSION-OWNERSHIP-003.8 AC-TASKS-QUEUED-SESSION-OWNERSHIP-003.9 AC-TASKS-WIP-LIMIT-PULL-SYSTEM-001.7 AC-TASKS-WIP-LIMIT-PULL-SYSTEM-001.8 AC-TASKS-WIP-LIMIT-PULL-SYSTEM-001.9	../../specs/tasks/system-design/queued-session-ownership.md ../../specs/tasks/system-design/wip-limit-pull-system.md

Task 03: Explain queue limits and link configuration

Summary

Name the actual queue limit and link to its configuration from task details. Verify that saved changes to either limit take effect without restart and that the banner follows the authoritative reason as work passes through each gate.

In scope

• Global banner label, instance scope, sessions count, and direct Settings link.
• WIP detail banner, including tasks without sessions, with workflow/destination identity, task-count units, and the correct workspace's workflow Settings link.
• Stable workflow-card Settings target and reveal after async loading.
• Reuse existing task-level desktop/mobile composition, not the transcript.
• Unknown/inaccessible destinations, stale counts, and read-only configuration.
• Live WIP reconciliation regression tests and queue reason refresh after saves.
• Localized labels, focused tests, public docs, and final package reconciliation.

Out of scope

• New queue storage or admission ordering, queue dashboards, or manual bypass UI.
• Starting/resuming work when a configuration link or browser Back is used.
• A new step-specific deep-link API or a new workflow Settings layout.

Acceptance

1. Global and WIP banners show the correct scope, units, and configuration link on desktop and phone. Missing identity never links to an unrelated workflow.
2. Saving increased/unlimited WIP reconciles eligible tasks through the existing backend event path; global saves use Task 01. Lower limits preserve admitted work.
3. Changing one limit cannot bypass the other. The displayed cause updates from WIP to global capacity when appropriate and clears only on confirmed settlement.

ASCII UI preview

UI-03 excerpt; the full preview defines persistent placement and phone wrapping.

Global:
Automatic launch: Queued
Global session limit (all workspaces)
5 of 5 sessions in use. Checked 11s ago.
[Configure global session limit]

Workflow:
Task queued: Workflow WIP limit
Development / Implement
2 of 2 tasks admitted.
[Configure workflow WIP limit]

Retain destination, queue time, freshness, and retry details from the full preview. On phones the link wraps below the explanation with a 44px target. Reuse the existing dedicated mobile task layout and its scroll/safe-area rules. The Settings links navigate directly; no hover, extra dialog, or launch action. Counts are examples, never fabricated values. Maps to this work order's ACs.

Tests

• Extend launch-queue-status.test.tsx: global scope persists with stale/unknown counts, errors retain their own reason, and href points to the registered target.
• New wip-queue-status.test.tsx: destination differs from feeder/current step, correct workspace/route, unavailable identity, no session, and task count units.
• Extend workflow-card and Settings target tests for reveal after async load.
• Add event_handlers_workflow_queue_test.go with TestWorkflowStepQueueLimitChange: save a larger/zero/lower WIP value through the step update boundary, observe reconciliation, preserve admitted work, and ensure destination entry runs once. Cover the shared HTTP/MCP event contract.
• New tests/workflow/queue-limit-navigation.spec.ts and mobile-queue-limit-navigation.spec.ts: both banners navigate to the correct configuration; save a raised/disabled limit, return passively, and observe queue advancement without restart/reload. Include WIP promotion followed by global deferral, then global disable and exact-once launch. Cover phone link bounds, no horizontal overflow, and returning to a parked predecessor.
• Use controllable mock tasks and isolated worker settings. Capture and restore both global settings and workflow limits in afterEach/finally. Follow causal HTTP/WS events; no fixed sleeps or mutation of the developer instance.

Verification

From repository root, after Task 02's dependency installation. Apply TDD for new reason/navigation logic and the live WIP regression. Managed E2E rebuilds assets.

(cd apps/backend && go test ./internal/orchestrator ./internal/task/service ./internal/workflow/handlers ./internal/mcp/handlers -run 'WorkflowStepQueue|WIP|Wip|WorkflowStep.*Parity|Step.*Event' -count=1)
(cd apps/web && pnpm exec vitest run components/task/launch-queue-status.test.tsx components/task/wip-queue-status.test.tsx components/settings/workflow-card.test.tsx components/settings/settings-target-surfaces.test.tsx lib/settings-discovery/target.test.ts)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm run i18n:check)
(cd apps/web && pnpm e2e:run --project chromium tests/workflow/queue-limit-navigation.spec.ts tests/workflow/queued-session-ownership.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/workflow/mobile-queue-limit-navigation.spec.ts tests/workflow/mobile-queued-session-ownership.spec.ts)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check

Verify that every named suite is discovered. Add or adapt workflow-card.test.tsx as necessary for the new target behavior. Run focused ESLint on the actual changed TS/TSX files before marking done. Use the existing Traditional Chinese generator after adding English/Portuguese/Simplified Chinese copy. Record rendered desktop/phone evidence against UI-03.

Files likely touched

• apps/web/components/task/launch-queue-status.tsx, its tests, and new wip-queue-status.tsx / wip-queue-status.test.tsx.
• Task-detail composition, including task-chat-panel.tsx, mobile/session-mobile-layout.tsx, and the no-session detail surface.
• apps/web/components/settings/workflow-card.tsx and target tests.
• apps/web/lib/kanban/wip-queue.ts only if shared destination context is needed.
• Task/summary types and projection only where required to supply authorized destination identity or complete admitted counts; prefer existing data.
• apps/backend/internal/orchestrator/event_handlers_workflow_queue_test.go (new).
• apps/backend/internal/orchestrator/event_handlers_workflow_queue.go and task-service WIP paths only if the regression exposes a live-update gap.
• New desktop/phone queue-limit-navigation E2E and shared helper.
• apps/web/src/locales/*/task.json, workflow/settings locale keys as needed.
• docs/public/tasks-and-workflows.md and the linked plan/spec status/results.

Dependencies

Task 02 supplies the global Settings target; Task 01 supplies live global updates. Existing WorkflowStepUpdated events already invoke queue reconciliation.

Risks

Workflow WIP counts tasks before destination entry; global capacity counts sessions after selection. Never show one record as the other or use a feeder's limit as the destination's. A settings save schedules reconciliation but cannot promise immediate agent output. Unknown observations and permissions must remain visible without inventing settings links or skipping backend checks.

Parallelism

sequential

Inputs

• Task-owned specs: Limit scope and configuration navigation; Limit updates and queue explanations. Agent-owned design remains the global settings authority.
• /mobile-parity, /e2e, scoped web/backend guidance, existing queue and mobile workflow Settings examples.

Results

Implemented separate global session-capacity and workflow WIP banners with scope-specific copy, units, configuration links, async workflow-card targets, and desktop/mobile placement. Added live WIP reconciliation coverage through the existing WorkflowStepUpdated event path.

• The focused WIP view-model and banner tests passed with the frontend suite.
• The workflow queue reconciliation regression passed with the orchestrator tests, and the global/WIP navigation scenarios passed in managed Chromium and mobile Chromium runs.
• Existing queued-session ownership desktop and mobile regressions passed with explicit environment capacity setup.
• Public documentation, settings catalog, specification catalog, full spec lint, and whitespace checks passed.