Session attention markers
Open Settings → Session attention markers in TUI, web or desktop. Choose which statuses add attention to Projects navigation, group tabs and individual session headings in the Projects mosaic and tree:
| Category | Default | Evidence |
|---|---|---|
| Questions from an agent | On | A current native user-question observation |
| Permission requests | On | A current native permission request or an unexpired pending managed MCP approval |
| Idle agents | Off | A current native prompt ready for another task, without a question, pending permission or quota block |
| Quota limits reached | Off | Current official Claude/Codex account usage or an unexpired, identity-matched native session quota recovery record |
Hidden sessions are always excluded from these markers, including the Hidden view itself. Group tabs show a hand when a selected status is present, alongside their normal session total; they do not add a second numeric attention total. Session headings show the same hand before the session name, alongside the lifecycle icon, so a group marker leads directly to the session that needs you. A native permission hand is not duplicated. Projects navigation keeps its selected-status count. Shells and Control Room sessions do not contribute to Projects markers. A session is counted once even if more than one selected reason applies or it has multiple pending approvals.
Unknown, stale and process-only lifecycle observations do not become questions or idle states. Expired or estimated quota data does not become an exhausted quota. Stopped conversations require their own current native quota evidence; an exhausted account alone does not revive every old session. Model-specific provider quotas without a verified session-to-quota correlation remain unknown.
These preferences belong to the authenticated controller user and persist across clients and controller restarts. Changes use a revision check: if another window has saved first, reload before retrying. Hiding remains the existing local Projects presentation setting; this feature does not introduce a global hidden session store.
Markers are independent of attention sound and push notifications. Selecting idle or quota does not add new sound categories. Hiding a session does not silence its canonical input/permission notifications.
The existing five-second metadata poll also updates markers when another screen is open or a terminal is attached. A bounded read-only query carries local hidden IDs in its body rather than in a URL. It returns only an owned aggregate count and its preference revision, plus the existing bounded sound metadata; there are no prompts, transcripts, approval arguments or full history payloads. Older controllers fall back to the already filtered local snapshot for markers while continuing their existing sound feed; an unfiltered legacy count is never substituted for a hidden-aware count.
The same authenticated API is discoverable through controller_operations and
callable with controller_request:
{"operation":"GET /v1/preferences/session-attention"}
{"operation":"PUT /v1/preferences/session-attention","body":{"questions":true,"permissions":true,"idle":false,"quota":false,"revision":0}}
{"operation":"POST /v1/notifications/attention/query","body":{"excludeSessionIds":["opaque-owned-session-id"]}}
Read the actual current revision before writing. The query is read-only: it does not change preferences, hidden sessions, agent state or sound behavior. Existing server authentication and ownership checks apply to all three operations.