session.hud: allow arbitrary placement, not just vertical

[pistoganza]

What I'm trying to do

Keep a small, always-visible recap panel over each session — the task in one line and the current state in another — so that walking into any of a dozen agent sessions answers "what is this about and where does it stand" at a glance.

session hud is very close to the right primitive for this. It is passive (the session keeps first responder and stays typable), it updates in place without blinking, and it does not consume the split. That combination is exactly what a status panel needs, and nothing else in the API offers it.

The gap

--position accepts only top, center and bottom. A panel meant to sit there permanently has to live in the reading path: center covers the conversation, top sits directly over the newest output, which is where the eye is.

The natural home for a persistent status panel is a corner — out of the text flow, present without competing for attention.

What would help

Horizontal placement alongside the existing vertical one, e.g. --position top-right / top-left / bottom-right / bottom-left, matching the anchor vocabulary session background --position already uses. Reusing that exact set would keep the two consistent.

What I tried instead, and why it did not work

• session background text — behind the terminal, so it does not steal input and can be corner-anchored, but it is a watermark rather than a panel: no frame, no separation from the text above it.
• A narrow right split running a renderer — gives a real corner panel, but the focus lands in it: session split on moves focus to the new pane and returning it is a separate call, so there is a window in which typing goes to the panel. With the panel re-asserted on every agent turn, that window is hit often enough to be disruptive.
• A floating overlay — no placement control, and while it is open the main pane reads visible=false, active=false, so it is unusable for anything persistent.

So session hud is the only mechanism with the right behaviour; placement is the one thing keeping it from the job.

Notes

Text colour inside the panel is not settable either. It is workable via --background-color (a light panel on a light theme keeps the text readable), so this is a footnote rather than part of the request — mentioning it only in case the two are worth considering together.

agterm 0.21.0, macOS 26.

[umputun]

the placement ask makes sense on its own and it's cheap. --position already takes top-right for session background, so session hud refusing it is just an inconsistency between two spellings of the same flag. I'll add the four corners.

one caveat on the always-visible part. session hud was designed for transient use, a message posted over a session while something is being prepared, so a resident panel runs into limits that placement doesn't change:

• overlay.open closes a live HUD and proceeds. The bundled show-image.sh opens an overlay, so anything showing an image takes the panel with it
• the slot holds one occupant. While a caller's program is in it, hud.open is refused, so the panel can't be re-posted until that overlay closes
• HUD state isn't persisted, so it's gone after a restart
• none of that emits an event. HUD state is poll-only, so a renderer only finds out by polling tree

if your renderer already polls tree and re-posts, none of that is fatal, it just means the panel isn't guaranteed to be up at any given moment. Worth knowing before building on it.

one thing a corner won't fix either: the panel is opaque and takes 10-80% of the pane width, so top-right is still where wide output and TUI chrome sit. It relocates the occlusion rather than removing it.

also worth checking whether you need the panel at all for this. session rename covers "what is this about", and session status active|blocked|completed plus session flag and the unseen badge cover "where does it stand". Both persist and cost no process. dashboard --mru (⌘⇧D) puts up to nine sessions' live output in one grid. If none of those fit what you're after, the HUD route is fine, just with the limits above.

the text color footnote is fair, noted separately.

[umputun]

merged in #386, on master and in the next release.

it went wider than the four corners: --position now takes all nine anchors of the grid, top-left,
top-center, top-right, center-left, center, center-right, bottom-left, bottom-center,
bottom-right. Once the panel can move horizontally at all, the middle column costs the same arithmetic as
the edges. They are spelled exactly as session background spells them, which was your point about keeping
the two consistent, and every anchor off center holds a fixed margin off that pane edge on its own.

top and bottom still work, resolving to top-center and bottom-center. Worth knowing if you parse the
read-back: tree reports the canonical anchor, so sending top reads back top-center.

the text color footnote is in as --text-color, and it differs from --background-color in a way that
turned out useful. The background is read once when the panel is created, but the text color rides the
panel's body file, so hud update --text-color recolors a live panel with no re-spawn. A status panel
going amber to green to red works without tearing anything down.

the caveats from my earlier reply are unchanged, none of them being about placement. overlay.open still
closes a live HUD, hud.open is still refused while a program holds that slot, HUD state is still not
persisted across a restart, and none of it emits an event.

[iatsiuk]

@umputun follow-up to the placement work here, one level down

nine anchors reoslve against the whole session rect, not the caller's pane. in a split, this looks untidy and plainly misaligned: an agent in the left pane asks for bottom-right, and the panel lands over the right pane, on top of whatever is running there. the same happens in reverse and on both split axes. --size-percent is measred the same way, so a longer message can cross the divider.

none of this is wrong once you know the panel goes through the session-wide overlay slot, but until then it looks like a drawing bug rather than a deliberate anchor. is there a reason anchors could not resolve against the caller's pane, opt-in, say --pane on hud open?

[umputun]

merged in #536, which carries the detail.

what I decided: placement can now be pane-relative if you ask for it, but the panel did not become
per-pane, and nothing changes for a caller who does not pass the new flags. A HUD is a message
about a session and there is one slot for it, so the latest writer still owns the panel, where it sits
included. Two agents in a split share one panel and the second post moves it.

what shipped: hud open and hud update take --pane and --pane-id, spelled as session restore
spells them. The anchor, --size-percent, the 80% cap and the edge margin all measure that pane now, so
the panel cannot cross the divider. Omitting both keeps the session-wide behaviour. Open refuses a pane
the deck is not rendering. If the target stops being laid out, which is what hiding a split does to the
pane without focus, the HUD stays alive but unmounted and comes back when the pane does. Closing the
target pane closes the HUD, and tree reports the target's current role as hud.pane.

for a long-running agent use --pane-id "$AGTERM_PANE_ID" rather than --pane "$AGTERM_PANE". The id is
stable and resolves the pane's live slot, while AGTERM_PANE is the shell's spawn role and goes stale
after a promotion or a session swap.

a resident panel per agent is a separate feature rather than a later increment of this one.

[iatsiuk]

@umputun thanks, tried fix and the pane-scoped anchor is offset by the pane's window origin.

agterm 0.26.3 (7eb1c1e), macOS 15.7.9, with a visible sidebar and a side-by-side split. from the left pane: agtermctl session hud open "x" --position bottom-center --pane-id "$AGTERM_PANE_ID" --target "$AGTERM_SESSION_ID". tree correctly reports hud.pane: "left".

the pane center is x=663, but the hud center is x=908, a 245-246 pt shift equal to the sidebar plus divider. the expected bottom margin is 100 pt, but the actual margin is 51 pt, a 49 pt shift equal to the titlebar plus hairline. the width is correct at 29% of the pane.

the pane probe is in deckPane (WindowContentView+Detail.swift:231-240), inside the HSplitView arranged subviews (173-176), while the named coordinate space is declared outside it (122). the emitted rect carries the detail column's window origin, behaving like a global frame; overlayPanel (256-263) and .position (297) then apply that origin again. paneMetrics (ControlServer+Hud.swift:114-140) reads only width and height, so it can affect sizing but not this translation. non-split sessions work because deckPane is outside HSplitView; the ui tests verify pane read-back, not rendered geometry.

[umputun]

merged in #545, on master and in the next release.

your diagnosis is the cause. HSplitView hosts its arranged subviews across an AppKit bridge that a SwiftUI named coordinate space does not cross, so inside a split frame(in: .named(...)) returned window coordinates and .position applied the detail column's origin a second time. A lone pane sits outside the split, which is why it worked there.

the fix drops the named space and carries the pane bounds as Anchor<CGRect>. An anchor has no space of its own, so the overlay layer resolves it in its own GeometryReader and the panel comes out in session-detail coordinates on either split axis. HudPaneFrame and what paneMetrics reads are unchanged.

two hosted tests mount the panes behind a sidebar and a titlebar, and putting the leak back fails them by exactly those offsets. There is still no test of where the panel actually draws, which is how this got through: the HUD is a Metal surface with no XCUIElement, so that needs a screenshot comparison and is separate work.