# DS Kanban architecture

DS Kanban is a profile layer with one Host registration and two Web shell contributions. The Host registers the `ds-kanban` settings schema with Harness Settings. It defines no route, transport, scheduler, or task store. The Client registers a sidebar footer action and a full-size `shell.overlay`, both backed by one root-scoped view store. The overlay covers the whole application shell, so its return paths are self-owned: opening moves focus onto the board's back control, and that control or a document-level Escape closes the board and restores focus to the sidebar action. The shell's overlay layer sits below the floating panel toggles and the details/bottom panels, so the board renders through a document-level full-viewport portal (the Settings panel's stacking precedent) and never collects shell icons over its toolbar.

Harness Session summaries own task identity, title, activity, blank state and unread-finish reminders, next-model selection and preset projections, token/context projections, and Session origin. Lightweight Session faces own running, queue, and final agent-error state. Pending Interaction owns waiting state and its presentation discriminator. The optional Goal projection owns the objective, phase, rounds used, and blocker explanation; live continuation activation is absent from that projection. Workspace Controller owns membership and archive state. DS Kanban combines these snapshots into cards and never writes these facts.

DS Kanban owns only versioned view settings: manual Inbox/Ready placement for otherwise blank Sessions, filters, grouping, density, timestamp format, sorting, archive visibility, and the context-warning threshold. Automatic states use the precedence Waiting, Running, execution failure or blocked goal, queued work (Idle), completed goal (Goal complete), nonblank session or unfinished goal (Idle), then manual/default blank placement. A stopped turn and the unread-finish reminder do not establish goal completion. Attention actions navigate to the existing session, where the owning interaction or goal UI supplies the current controls. Unknown settings versions and malformed fields are rejected without mutation.

The Session list, Workspace snapshot, pending-interaction snapshot, settings scope, connection generation, and per-Session faces are observable. Each face callback reads only that session and compares running, error, and queue length. Unchanged values do not publish; changed values replace one entry in an immutable snapshot, retaining the other entry objects. Snapshot copying and whole-board derivation remain linear in the session count. Card projection retains unchanged card objects so memoized cards skip unrelated updates. Filters, groups, and aggregates still cover the complete list. The Runtime source reconciles per-Session subscriptions and replaced face identities when the authoritative list changes and disposes every list and face subscription with the Client plugin scope. The existing connection loop repopulates source services after reconnect; DS Kanban adds no timer or polling loop.

Task creation calls the supported Session create operation with the selected Workspace, optionally selects an Agent Preset, optionally renames the Session, submits the initial prompt, and opens that Session. A single in-flight coordinator coalesces duplicate form submissions. Existing-card navigation calls Session open and never creates a Session.

Visible task cards consume all reachable parent-addressed subagent catalogs, including while their hierarchy is collapsed. A unique-id traversal derives descendant totals and the catalogs to observe; missing, loading, failed, or diagnostic data marks totals incomplete. Running/waiting filters preserve ancestors of matching rows. Each card reconciles catalog interest as descendants change and releases interest on unmount; the board adds no polling. Child rows use catalog activity and durable addresses, never infer completion from inactivity, and navigate through openSubagent. Available session summaries supply optional model, token, context, preset, and goal details. Missing child details are not inherited from the parent. Nested expansion uses catalog hasChildren and guards ancestor cycles. Child rows remain outside top-level filters, totals, and exports.