#24286 cmux NEXT: agents mark the tab where you must act (cmux attention request, tab-attention-v1)

Leo-ask: ask-12231fbe5e

Leo: "idk where things are man i dont see anything other than the current workspace which is you and you have a cmux next github brwoser tab open (we need to have cmux expose this harder if it isn't already/hve better instructions)"

What happened: an agent needed Leo to confirm GitHub sudo in a browser tab it had opened (in a workspace 42 rows down the sidebar) and told him a raw ws_… id he could not see or search.

This is slice A of the "needs you here" surface: the daemon state, CLI and MCP path. The app styling, notification with Show, the "Go to what needs me" palette command and the agent instructions follow in their own PRs.

What changes

• tab.update takes attention: a one-line reason (1-200 characters, no control characters) or null to clear. The daemon stores {reason, at_ms} on the tab record (tab_state.attention_json, an additive column), and every client sees it as the tab's extra.attention. Capability tab-attention-v1.
• CLI: cmux attention request --tab <tab_…> --reason <text> and cmux attention clear --tab <tab_…>. Both send tab.update {attention}, so CLI, MCP (tab_update with attention, generated from the catalog) and the app share one mutation path.
• It never moves focus. A test checks that the active surface stays the same.
• Clearing:
  • the agent's clear;
  • a browser tab whose page goes to a different URL, for both frontend-rendered (WebKit/CEF) and CDP browsers; a title-only change keeps the mark;
  • the tab's close. The mark is dropped when the tab row is tombstoned, so a reopened tab (which keeps its id) does not ask again.
  • Terminal tabs keep the mark until the agent clears it or the tab closes.
• The agent guide (cmux docs, "Show your work…") tells agents to mark the tab and to name workspaces and tabs by their titles, never by a ws_ or tab_ id.

Tests

• state/tab_attention_tests.rs:
  • mark, list, keep across another field, clear;
  • bad values are rejected;
  • focus does not move;
  • navigation clears the mark, a title change or the same URL does not;
  • close plus reopen leaves no mark.
• tab_state_store unit tests: migration, clear on close, reason validation.
• CLI: attention_request_and_clear_send_tab_update, plus the transport-path coverage cases (which check the plan against the catalog).

Not in this PR

App styling (the existing blue needs-you treatment on the tab and its workspace row), the Needs you list entry, the system notification with Show, the palette command, and the MCP server instructions text.

No capture: daemon/CLI only; no native UI changes in this PR.

Agent session: cosmic-gray

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

Agents can now mark the tab where the person must act (confirm, log in, approve, pick), instead of pointing them at an opaque ws_/tab_ id for a tab far down the sidebar.

• tab.update takes attention, a one-line reason or null to clear; the daemon stores it on the tab record and every client sees it as extra.attention under tab-attention-v1. Reasons with control characters, U+2028, or U+2029 are refused.
• New CLI commands cmux attention request --tab <tab_…> --reason <text> and cmux attention clear --tab <tab_…> both send tab.update — the same mutation path CLI, MCP (tab_update), and the app share.
• The mark never moves focus.
• A mark records the page it was set on, so a navigation clears only a mark set on another page, and the clear is decided in its own commit: a mark an agent sets on the new page survives a late or repeated clear for an older page. It clears on the agent's clear, a browser tab's navigation to another URL (a title-only change keeps it), or the tab's close; reopening a closed tab does not re-ask. The CDP event thread detects URL changes over target-info, frame, and same-document navigation alike and always asks on its first event.
• cmux docs now tells agents to mark the tab and to name tabs and workspaces by their titles, never by id.

App styling, the needs-you list entry, system notification with Show, and the palette command follow in later PRs.