signalbox ios

What this is built

The product is "know when a session needs you without watching terminals". Away from the desk is where it matters most: agents run long, and the amber moment usually lands once you have walked away. This surface is the board in your pocket.

It is a native app. That keeps the hub simple: a browser cannot set headers on an EventSource, so a web board would force cookies, sessions, a login page and CORS onto the hub. URLSession sets an Authorization header freely, so the hub stays a pure API and the phone is another client.

Scope

Read the board, live, across every machine pointed at the hub.
Clear the flag from the phone. Half the value: acking on the phone must quieten the board everywhere.
Ask a machine to jump. The phone cannot jump, but it can ask the laptop to. See below.
No push notifications in v1 later. Wanted, and its own piece of work.

The phone is a remote control

Jumping spawns tmux against a socket on a local filesystem, or raises a local window. A phone has neither, so it cannot jump itself. The laptop can: it is already listening to the hub and already knows how to jump, so the phone asks it to.

The ask is a command on the same bus the board rides. Fire the jump from a card with the arrow or a right-swipe, and the machine that owns that session raises the window. The phone in your hand becomes a jumplist for the laptop on your desk.

Three rules:

Every visible machine row offers it. Rows with a tmux or cursor origin jump as before. A machine row with no usable origin still carries the arrow.
URL-only rows are information. A CI or GitHub row describes remote work, not a window, so it carries no arrow or Jump swipe action.
Success shows only once the phone can see it. The laptop may be asleep or not running the app. The row going quiet when that machine acks is the confirmation, since jump fires seen only once the switch has landed.

Activating Jump on a machine row with no usable origin presents an alert titled Jump not supported with this message: "This session is running in a plain terminal - jump is not supported yet. Submit feedback if you would find this useful." Submit feedback opens https://github.com/dwmkerr/signalbox/issues/67; Cancel dismisses the alert.

origin.kind reserves ssh as a future kind. When it lands, a row on a machine that is not next to you becomes jumpable too.

Rows

Same anatomy and the same words as the jumplist, so the two surfaces never disagree: status mark, agent glyph, name, host, age, and the subtext.

Status marks

● amber - needs your input (act)
● blue - output updated (look)
✕ red - failed (fix)
spinner - working
○ faint ring - read; dealt with, the row keeps its place

A bold name means unread. The amber mark alone means the session is asking for you; there is no extra badge.

Subtext

The line under each name follows the one-line preview rule from agent-markdown.md: take the first paragraph, keep inline styles, and collapse whitespace to one line. While a session works you see your prompt (what it is working on); once it finishes, asks, or fails you see its reply (what came back). Identical rule to the jumplist.

Host

A row shows the machine it lives on when more than one machine is on the board. The machine decides whether a row can be acted on, so it matters most on a shared hub. With one machine every row shows the same host and the state line already says "1 machine", so the chip drops out.

Icons and naming

The glyph comes from the event's agent field, mapped locally to the same per-agent icons the jumplist uses (see the table), with the plain ring as the fallback for anything unknown. Naming priority is label, then title, then the cwd folder name.

Order and filtering

The hub owns the order. GET /state returns rows in display order (most recently engaged first) and the app adopts it verbatim. Do not re-sort client-side: the ordering rules live in the reducer, and a surface that re-derives them will drift.

The search field lives in the navigation bar's drawer: it is hidden until you pull the list down, which keeps the board itself uncluttered. Search filters live over name, prompt, reply and agent. A query starting with # switches to tag mode (#ops shows only sessions carrying that tag, case-insensitive, exact match), matching the jumplist. Hidden rows drop out of the main list (see below); acked rows stay, drawn quiet.

Pinned built

Long-press a card and choose Pin (the Messages / Telegram gesture). The session stays at the top of the board with a small pin mark, regardless of engagement order. Long-press again to unpin.

Pinned rows sort first. Within the pinned group, and within everything below it, the order is still the hub's engagement MRU. The hub owns the order, so pin and unpin are user events like seen and hide: the reducer serializes pinned, and every surface (this app, the jumplist, the menu bar) shows the same partition.

Hiding a pinned session unpins it. Hide is the stronger, more recent intent.

Hidden built

Hidden sessions collapse into a quiet divider at the bottom of the list - the Reminders "Show Completed" pattern. The section holds only sessions that are currently silent and deliberately hidden: a hidden session that speaks again returns to the main list on its own, so the section stays small.

The divider is always shown once the board has a session, "Hidden (0)" included, faint and small, so it is always clear whether a session is set aside. "Hidden (0)" is inert: no chevron, nothing to expand.
Tap to expand: hidden rows appear dimmed with an eye-slash mark. Swipe offers Unhide (the wire's show user event - clears hidden without waiting for the agent). Tap to collapse again.
Search sees through it. A query that matches a hidden session reveals the section with the match in it. The Gmail rule: search includes the archive.

Empty states

An empty board means three different things, and the app says which - and the board agrees with Settings rather than telling a different story on reload. On a live hub with nothing running it is the quiet moon: No sessions. Fire an agent and it appears here.

A hub that is configured but unreachable is Hub offline, not "not connected": the board is a memory and says so: Can't reach hub at <host>. Some corporate networks will block device to device connections. Deploy a remote hub, or connect via a mobile hotspot (see docs). The message names the likely cause because the failure is otherwise silent - a phone reaches the hub over the LAN, and a corporate/guest network that isolates devices drops the connection with nothing to show. The same message appears on the top banner when the board still has cached cards (not only on the empty-board screen), so tapping Reconnect against an unreachable hub always explains itself. The way back is Reconnect (retry now, skipping the backoff), Scan a New Hub, and a destructive Disconnect behind the same confirm as Settings. A rejected token is its own line - a retry cannot fix it, so it leads with Scan to Re-pair. This is the state a relaunch lands on when the hub is down, and it must match the Offline row in Settings, not fall back to the first-run pitch.

Only a hub the phone was never paired with shows Not connected, pointing at the qrcode.viewfinder button top-right. The words name the desktop app and the CLI - the two ways a power user pairs - and deliberately do not send them to Settings, which only repeats the same scan.

The bottom menu

Tab	What it is for
Sessions	Every session on the hub, in the hub's order, as cards. The one surface: browse, search, ack, and jump.
Settings	The hub and pairing. Machine and session counts live on the Sessions connection line.

Actions

Gesture	Action
Tap a card	Open the session's history as a conversation (see Chat below), and mark it read. Opening the thread is reading it, and a dot that survives being read stops being worth trusting. Mark as Unread is the way back. On a phone you are not at the machine the session runs on, so reading what happened is the useful default and jumping is the deliberate act - which is why jump keeps its own button rather than owning the whole row.
The dot on the trailing edge	Whether this row wants you: amber when it needs your input, blue when output has updated, absent once it is read. It is the row's only mark. What the agent is doing is not a mark: a working session shows a small spinner, the word Working..., and the prompt it is working on, in italic, on its subtext line. The italic is load-bearing: that line quotes you while working and the agent once done, and rendered alike the two cannot be told apart without reading them. Amber was rejected because amber already means "needs your input". which is where messaging apps put activity - WhatsApp and Telegram replace the message preview with "typing...", and none of them keeps a glyph column for it. Idle rows therefore say nothing at all, which is the point: the default posture stays silent. Elapsed time is the age column's job, so the subtext does not repeat it. Information-only rows (CI, GitHub) carry the dot but no jump affordance, which is the clearest proof that wanting you and being actionable are independent.
The arrow, Jump	Shown on every visible machine row. A tmux or cursor origin asks the owning machine to raise its window. With no usable origin, it shows Jump not supported: "This session is running in a plain terminal - jump is not supported yet. Submit feedback if you would find this useful." Submit feedback opens issue 67, and Cancel dismisses the alert. URL-only CI and GitHub rows are information-only and offer no arrow. A successful jump marks the session seen, matching the jumplist. Jump is deliberately not a swipe: it reaches across to another machine and moves a window, which suits a button press rather than a gesture.
Swipe right, Read / Unread	Toggle the read state, the way Messages and Mail put it on the leading edge. A toggle always does something, so unlike a one-way Seen it needs no special case to stay honest on a row that has already been read. Also in the long-press menu, as those apps offer both.
Swipe left, Hide	Fire `hide`. The row leaves the main list for the collapsed Hidden section until the session speaks again, or until unhidden there.
Long-press built	Context menu: Pin / Unpin (see Pinned above) and Mark as Read / Mark as Unread. Chat is the row's tap, so it is not repeated here.
Pull down a little	Reveal the search field.
Pull down further	Force a full `/state` resync. The escape hatch when a stream has gone strange.

Expanding a card does not mark it seen. On the desktop, jumping is the ack because looking at the pane is seeing it. On a phone, reading a breadcrumb is not dealing with the session, so marking seen is always deliberate here.

The board offers no way to remove a session. Removal is destructive and irreversible from the phone.

Chat

Tap a session row to open its history as a conversation.

9:41

‹writing-studio

…older

Update the history reducer and its tests.