Session list

HAPI's Web session list combines live session state, project grouping, search, and local display filters. The list is designed to keep sessions that need attention easy to find while still allowing older sessions to be searched.

Ordering and grouping

The default order follows your most recent input, not the agent's most recent output. Sending a new message moves a session forward once. Streaming, tool/Todo updates, waiting for approval, completion, and reconnects do not reorder ordinary rows. Status and unread indicators still update live.

1. Globally pinned sessions.
2. Project-pinned sessions.
3. lastUserMessageAt descending (or createdAt before any user input).
4. Creation time descending, then session ID for deterministic ties.

The Web app groups sessions by machine and project directory. Within a project, pins come first, followed by the same user-input order. Project and machine groups use their pinned state and newest member's ordering key, not live activity. There is no fixed-order preference to configure.

The Hub persists the original user-message timestamp, including local CLI input. Historical imports and duplicate/echoed messages do not acquire a fresh ordering timestamp. Deletion or rewind does not rewind this monotonic clock. An unattended session's new output is indicated as unread rather than moving it ahead of conversations you have interacted with more recently.

The detailed API contract is documented in REST — sessions and SSE — keep-alive noise.

updatedAt remains the session activity clock used by timestamps and the date filter, not the ordering key. It is different from activeAt: activeAt is the CLI connection keep-alive clock and does not, by itself, move a session in the list. A connected session can therefore be idle; see active is transport liveness, not agent health.

When enabled in Settings → Display, the optional in-progress layout moves active sessions into Working, Pending, Active, and Idle sections. Global and project pins remain distinct from these sections. This optional layout still moves rows between sections as their status changes, but orders rows within each section by user input rather than ongoing output.

Text search

The search field on the Web session list searches session metadata, including:

• the displayed title (name, summary, path, or ID fallback);
• worktree labels and paths;
• summary text;
• agent flavor and machine label; and
• the session ID.

Plain-text matching is case-insensitive and supports partial substrings. A multi-word query uses AND semantics: every term must match at least one searchable field. Queries containing * or ? use wildcard matching, where * matches any sequence and ? matches one character.

Search results are ranked by relevance rather than by date alone. Title and worktree matches are more prominent than summary, machine, path, or ID-only matches; token-boundary matches and exact/contiguous title phrases receive additional preference. When relevance is tied, the stable user-input order is used as the tie-breaker. This means an older session with a distinctive title can appear above a newer session that only matches a common path segment.

Search preserves the session-list structure: pinned rows remain contiguous and project groups remain visible. Matching project groups open automatically, but the preview limit still applies within an open group. Search does not apply a relevance cutoff; use the group's batch reveal controls to show additional matching rows.

Filters and display settings

• Date range filters by the local calendar date of updatedAt. The end date includes the whole local day.
• Unread only is a transient view filter. The currently open session stays visible, and the filter is cleared when the page is reloaded.
• Machine filters can be applied when more than one machine is present. The selection is remembered locally in the browser and falls back to All when that machine is no longer available.
• Active sessions only hides inactive sessions but keeps the selected session visible.
• Session preview limit controls how many rows are initially visible within each project group. Sessions with pending requests and the selected session can remain visible; a project can reveal more rows in batches.
• Session-list status controls whether rows show the standard or detailed attention/status presentation.

Empty, inactive session stubs without conversation, an agent identity, or an explicit title signal are not shown in the normal sidebar. Duplicate rows representing the same underlying agent session are collapsed, with the live, selected, pinned, or most recent row preferred as appropriate.

Other Web session pickers

The other Web surfaces intentionally use related but different policies:

Share-target picker

The /share picker snapshots the session list when it opens so live SSE updates do not reshuffle the rows under the user's finger.

• With no query or date range, it shows recent active sessions, sorted by updatedAt and capped by the session preview limit.
• With a text query or date range, it searches all matching sessions, including inactive sessions, and keeps updatedAt descending order.
• It reuses the session metadata matching fields, but it does not apply the main sidebar's relevance ranking.

@ session suggestions

Composer @ suggestions only include sessions with conversation content. With an empty query they prefer active and recent sessions; after typing, they use a separate title/ID/active/recency ranking. Names, directories, and machine labels affect matching, but an empty stub is never a mention target.