UX: the notification badge and the attention status look alike but behave differently — attention-nav (⌃⌥↑/↓) silently skips badge-only sessions

[Brialius]

Summary

agterm shows two different "this session wants you" indicators on a sidebar row, and they're easy to conflate:

Indicator	Set by	Looks like	Attention-nav (⌃⌥↑/↓) stops on it?
Notification badge	OSC 9/777, agtermctl notify	red count pill [1]	No
Agent status	agtermctl session status blocked/completed	colored ●/✓ glyph	Yes

Both sit at the trailing edge of the row and both read as "go look at this session," but only the status glyph is a navigation target. Reaching for ⌃⌥↓ (Next Attention Session) to jump to a session that's showing a red notification badge does nothing, with no feedback — the keystroke is a silent no-op. It's easy to read this as "the shortcut is broken / flaky," especially right after re-focusing agterm from a background notification, when a badge is exactly what's drawing your eye.

Expected vs actual

• Expected: ⌃⌥↑/↓ jumps to a session that has a notification badge armed.
• Actual: ⌃⌥↑/↓ only steps through sessions whose status is blocked/completed and silently skips any session that has only a notification badge.

Steps to reproduce

1. In a window with sessions A and B, select A. Keep B idle (no status glyph).
2. Arm B's notification badge only: agtermctl notify "ping" --target B → B shows a red [1] pill.
3. Press ⌃⌥↓ (or agtermctl session go --to next-attention) → nothing happens; selection stays on A.
4. Now give B a status: agtermctl session status blocked --target B.
5. Press ⌃⌥↓ again → selection jumps to B. Only the status moved it.

This is documented — the ask is about the UX, not a bug

The behavior is intended and documented: the README says a notification is "a one-shot banner and badge with no lasting state," while agent status "powers the attention list, the title-bar bell, and attention navigation (⌃⌥↑/↓)," and the CLI help for session go states "attention = blocked/completed." So this is a request to reduce the confusion between two similar-looking signals, not a defect report.

Possible directions (deferring to your judgment)

1. Fold the badge into attention-nav — make ⌃⌥↑/↓ also stop on sessions with an unseen badge (unseenCount > 0). Matches the intuitive "jump to whatever is flagged" expectation; self-pruning since selecting a session clears its badge. Downside: mixes a low-signal ping with an explicit block.
2. A dedicated "next/prev unseen" navigation — a separate shortcut + session go --to next-unseen, keeping the two signals cleanly distinct.
3. UX/discoverability only — no navigation change; e.g. a subtle cue that the two indicators are different, or clearer naming, so the badge isn't mistaken for an attention target.

Happy to help with whichever direction you'd prefer.

Environment

• agterm 0.15.1
• macOS 26.5.2

[umputun]

the split is deliberate, and it's the same design line I laid out in #236: the notification badge is the OSC 9/777 / notify layer, a "there's something new here" ping that's ephemeral and clears the moment you glance at the session. Per-session status is the durable "this needs you" layer, and that's the one wired to the attention machinery: ⌃⌥↑/↓ nav, the title-bar bell popover, and the ⌃⇧I palette. Keeping the badge out of that set is intentional, and your docs quotes are exactly right.

on the three directions:

1. folding the badge into ⌃⌥↑/↓ is the one thing I want to avoid. It re-mixes the low-signal ping into the attention set, and since the badge clears on visit it'd be a self-erasing, flickery nav target. Status is the promotion path when a ping is worth stopping on: agtermctl session status blocked (leave --autoReset off) drops the session into the attention set and it survives the visit.
2. a separate next-unseen nav has the same problem under a new key, it makes the ephemeral badge navigable either way. I'd rather not grow a second attention-like axis.
3. the discoverability angle is the fair part, the two indicators do read alike. But they're already distinct in the docs (badge = notification layer, status = attention), and I don't want a persistent cue competing with the glyph right next to it, so I'm leaving the visuals as-is for now.

net: badge stays the ephemeral notification layer, status stays the attention target, and session status is the one-keybind promotion when a ping is worth navigating to. Passing on 1 and 2.

[umputun]

to put it plainly: statuses are the mechanism I'd reach for here, they're what agterm is built around for "this session needs me". I don't really use the notification badges myself. The reason they exist at all is to support clients, agents and other tools, that can't be made to set a proper status. When something can drive session status, that's the better signal, and it's the one the whole attention flow is tuned for.

[Brialius]

Thanks for such a clear and detailed answer. No more confusion now, appreciated.