kandev/docs/decisions/2026-08-01-separate-task-summary-session-stream-traffic.md

# ADR-2026-08-01-separate-task-summary-session-stream-traffic: Separate Task Summary and Session Stream Traffic

**Status:** accepted
**Date:** 2026-08-01
**Area:** backend, frontend, protocol

## Context

Task switchers need a small set of facts for every visible task: runtime state,
pending user input, recoverable agent errors, aggregate Git changes, and pull
request status. Those facts currently come from several stores. In particular,
the desktop sidebar subscribes to every task's primary session to obtain live
Git status, while desktop and mobile also inspect loaded session messages and
metadata to derive pending and error indicators.

A captured reload with 27 sessions produced 700 WebSocket frames (3.23 MB) in
five seconds, including 74 `session.subscribe` and 47 `session.unsubscribe`
requests. Switching tasks rebuilds the subscription set. Each session
subscription can replay the full session snapshot and then carry messages,
shell activity, model configuration, MCP status, and other data that a task row
does not use.

The WebSocket client currently puts correlated responses and unsolicited
notifications on one bounded FIFO queue. When that queue is full, a frame can
be dropped without closing the socket. This makes a fast, persisted
`message.add` operation appear to time out, and delayed model snapshots can
temporarily remove the model selector. Increasing the message timeout would
hide the symptom without removing the fan-out or the ambiguous response loss.

## Decision

Kandev will maintain a bounded, rebuildable `TaskStatusSummary` read model for
task-level surfaces. It is carried on task snapshots and updated through the
existing workspace-scoped task event path. The summary contains only the facts
needed to classify and decorate a task row; transcripts, file paths, diffs,
shell output, model configuration, and MCP payloads remain session-owned and
are never copied into it.

Session, message, Git, and pull-request domains remain authoritative. The
summary projector consumes their semantic changes, persists the latest compact
projection with a monotonic per-task revision, and emits an update only when
the projected value changes. A missing projection is rebuilt from authoritative
state and never causes the browser to subscribe to background sessions.

Task switchers consume task snapshots plus task-summary deltas. They do not
subscribe to session streams. Full session streams are limited to sessions
explicitly opened in an active detail surface. Repeated subscription and focus
requests are idempotent: only a new subscription receives a full initial
snapshot, and focus changes polling priority without replaying session data.
Targeted refresh operations use targeted actions rather than `session.focus`.

Git-summary freshness is tied to runtime ownership rather than browser
interest. A live execution keeps a slow monitoring baseline, active focus may
upgrade it to fast monitoring, and settled tasks use the latest persisted
snapshot. Removing a browser's background subscriptions therefore cannot pause
the source that feeds task-level Git status.

Correlated WebSocket responses and errors use a reserved, prioritized delivery
path separate from best-effort notifications. A response must be queued or the
connection must fail explicitly; it must not be silently discarded behind
session notification traffic. User message submission also carries a stable
client-generated message ID. Retrying that ID returns the accepted message
without rerunning turn-start hooks or dispatching the prompt twice.

## Consequences

Workspace traffic scales with task-summary changes and explicitly opened
sessions rather than with every task's full session activity. Switching tasks
has constant subscription work and no longer tears down and recreates an
all-task subscription fan-out. Desktop and mobile task switchers read the same
status contract and preserve their existing icon precedence.

The summary is eventually consistent by design. Revisions prevent stale
deltas from overwriting newer task state, and reconnect/task-list hydration
repairs missed updates. Projection failures leave the last valid summary in
place and are observable; detailed domain data remains available on demand.

The implementation adds a compact persistence model and projection wiring
across several domains. It also requires explicit queue semantics in the
WebSocket gateway and an idempotency contract for `message.add`. These are more
moving parts than a frontend-only optimization, but they remove the coupling
that caused the traffic amplification and protect every request type from the
same queue-pressure failure mode.

## Alternatives Considered

- **Keep all session subscriptions but reduce individual payloads.** Rejected
  because task switching would still perform O(number of tasks) subscription
  churn and task rows would remain coupled to session-internal events.
- **Derive one task aggregate entirely in the frontend.** Rejected because the
  browser would still need every authoritative stream, every client would
  duplicate precedence rules, and a suspended browser could not repair the
  aggregate without replaying those streams.
- **Copy full session, Git, or PR records onto the task row.** Rejected because
  it would create competing sources of truth and make a bounded list payload
  grow with transcripts, repositories, or pull requests.
- **Poll task details from REST.** Rejected because polling introduces stale
  badges and repeated full-list reads while the workspace task event channel
  already provides an appropriate bounded delivery path.
- **Only enlarge the WebSocket queue or message timeout.** Rejected because
  queue pressure would remain proportional to background sessions and a full
  queue could still make accepted writes ambiguous.