Proposal: redefine session activity → status → pill (collapse to a 4-state model, surface no_signal)

[harshitsinghbhandari]

Summary

The per-session status the dashboard shows (the pill, the board column, the sidebar dot) is harder to reason about than it should be. One raw signal (activity.state) is expanded into a 13-value SessionStatus, which is then collapsed again by three independent mappings and rendered across four surfaces, two of which duplicate the same lookup table. Several distinct backend states (a busy agent, a quiet-but-fine agent, and an agent the daemon thinks may be stuck) all render identically.

This proposes collapsing the per-session pill to a 4-state model (Working, Needs input, Ready, Idle), consolidating the mappings into one place, and surfacing the no_signal ("possibly stuck") state the backend already computes but the UI currently throws away. It also lists the open decisions, because there are more than a handful.

This is a design discussion, not a finished spec. The open questions at the bottom need answers before implementation.

---

How it works today

Pipeline (claude-code shown, but the post-hook path is shared by all harnesses):

agent hook (UserPromptSubmit / Stop / Notification / SessionEnd)
  -> ao hooks claude-code <event>                       (CLI)
  -> claudecode.DeriveActivityState                     (event -> ActivityState)
  -> POST /api/v1/sessions/{id}/activity
  -> lifecycle.Manager.ApplyActivitySignal              (writes activity_state)
  -> SQLite + CDC trigger -> SSE /api/v1/events         (nudge)
  -> frontend refetches GET /api/v1/sessions
  -> service/session.deriveStatus                        (activity + PR facts -> SessionStatus)
  -> frontend collapses SessionStatus -> pill / column / dot

Two distinct vocabularies, which is fine and correct in principle:

• domain.ActivityState (stored): active | idle | waiting_input | exited. The raw agent-liveness signal. Only these four are accepted at POST /activity and only these are persisted.
• domain.SessionStatus (never stored, computed every read in deriveStatus): working, pr_open, draft, ci_failed, review_pending, changes_requested, approved, mergeable, merged, needs_input, idle, terminated, no_signal. The display status, which mixes the activity signal with GitHub PR/CI/review facts.

The problem is everything downstream of SessionStatus.

Three parallel mappings off SessionStatus, in frontend/src/renderer/types/workspace.ts

1. workerDisplayStatus() -> WorkerDisplayStatus (working | needs_you | mergeable | ci_failed | done). Drives the pill and the card badge.
2. attentionZone() -> AttentionZone (merge | action | pending | working | done). Drives the kanban columns and the sidebar dot.
3. Ad-hoc predicates: sessionNeedsAttention() (true for needs_input, changes_requested, review_pending, ci_failed), sessionIsActive() (false only for merged/terminated), workerStatusPulses() (true for working, needs_you).

These three do not agree with each other. Example: a ci_failed session is ci_failed to the pill, action to the board, and true to sessionNeedsAttention. A review_pending session is needs_you to the pill but pending to the board. There is no single answer to "what state is this session in."

Four render surfaces

• SessionsBoard.tsx: 4 columns by attentionZone (Working / Needs you / In review / Ready to merge) plus a BADGE map by workerDisplayStatus.
• ShellTopbar.tsx: a STATUS_PILL map by workerDisplayStatus.
• SessionInspector.tsx: a second, separately-defined STATUS_PILL map (same values today, free to drift) plus a special-case so status === "idle" shows "Idle", plus activityDetail().
• Sidebar.tsx: SessionDot, orange+breathing if attentionZone === "working", grey otherwise.

---

Concrete problems

1. Three states render as one. idle, no_signal, and an actively-working working all collapse to "Working" on the board and topbar. A stuck agent, a finished-and-quiet agent, and a busy agent look identical.
2. no_signal is computed and then discarded. The backend spends real machinery on it (FirstSignalAt, a 90s noSignalGrace, a dedicated CDC trigger on first_signal_at, the signalCapable gate) to answer "has this hook-capable agent gone silent and possibly broken?". But the frontend SessionStatus union does not even contain no_signal, so toSessionStatus() falls back to "working". The one state that flags a possibly-stuck agent never reaches a human.
3. "Needs input" is overloaded. It means both "the agent is blocked on you" (waiting_input, a permission or idle prompt) and "a reviewer asked for changes / a PR is awaiting review" (changes_requested, review_pending). Those are very different asks.
4. Two STATUS_PILL definitions (topbar and inspector) plus a third color map in the board. Identical today, but nothing keeps them in sync.
5. Precedence surprise. deriveStatus checks "has an open PR" before "agent is active", so an agent actively coding on top of an open PR shows the PR status, not "Working".

---

Proposed direction: a 4-state pill

Collapse the per-session pill to four glanceable states. Each answers a clear question.

Pill	Meaning	Color
Working	the agent is doing something (or a PR is mid-flight with nothing for you yet)	orange, breathing
Needs input	the agent itself is blocked on you	amber
Ready	there is a PR that wants your eyes (in review, changes requested, approved, mergeable)	green
Idle	nothing is happening (idle, or the work is finished/closed/merged)	grey

Delta from today, applied to the existing SessionStatus values:

SessionStatus	Today's pill	Proposed pill
working (activity active)	Working	Working
ci_failed	CI failed	Working
needs_input (waiting_input)	Needs input	Needs input
changes_requested	Needs input	Ready
review_pending	Needs input	Ready
approved	Ready	Ready
mergeable	Ready	Ready
merged	Done	Idle
terminated	Done	Idle
idle	Idle	Idle
pr_open	Working	open question (#1)
draft	Working	open question (#1)
no_signal	Working (fallback)	open question (#2)

Net effect: "Needs input" becomes exactly "the agent is blocked", and the PR pipeline collapses into a single "Ready" bucket.

---

Open decisions (the actual work of this discussion)

Each needs a call. My recommendation is listed, but these are the points to argue about.

1. Where do pr_open and draft go?
pr_open is "open PR, no review signal yet"; draft is a draft PR. Options: (a) Working, (b) Ready.
Recommendation: Working. A draft means the agent is still iterating; an un-reviewed PR has nothing for you to do yet. "Ready" should mean "ready for your attention".

2. Should no_signal be visible, and how?
Options: (a) give it its own pill state ("No signal" / "Stuck", grey or red, non-breathing); (b) fold into Idle; (c) fold into Working (status quo).
Recommendation: (a), its own visible state. Folding it into Working or Idle defeats the entire FirstSignalAt / grace mechanism. If we are not willing to surface it, we should delete that machinery instead of paying for it invisibly. This is the highest-value fix in the proposal.

3. Precedence: active agent with an open PR.
When activity.state == active AND an open PR exists, show Working or the PR status? Today PR wins (deriveStatus order). Options: (a) keep PR-wins, (b) active-wins (agent busy = Working until it stops).
Recommendation: lean active-wins, but this is a genuine product call. It is a one-line reorder in deriveStatus.

4. Does the kanban board collapse to match the pill, or stay a separate triage axis?
The board (attentionZone, 5 columns) answers "sort my N sessions by what needs me", which is a different question from the per-session pill. Options: (a) keep the board as-is and only change the pill, (b) re-derive the board from the same 4-state model, (c) redesign the board columns to match.
Recommendation: decide explicitly. If we keep both, they must at least be derived from one source so they cannot contradict (see #7).

5. What counts as "needs attention"?
sessionNeedsAttention() currently includes ci_failed, changes_requested, review_pending. If those move to Working/Ready, do they still drive sidebar emphasis / any counters? Options: tie the predicate to the new buckets (e.g. attention = Needs input only, or Needs input + Ready).
Recommendation: attention = Needs input + no_signal (things that are actually blocked), with Ready as a softer "your move" that does not nag.

6. Idle vs Working on the board.
Today idle shows as "Working" on the board and only the inspector distinguishes "Idle". With a real Idle pill, should the board show idle sessions distinctly too?
Recommendation: yes, otherwise Idle is invisible exactly where you scan for it.

7. Single source of truth.
Collapse the duplicated STATUS_PILL maps (topbar + inspector) and the parallel workerDisplayStatus / attentionZone / predicate functions into one module with one input -> one mapping. Recommendation: yes, non-negotiable for this to be maintainable. Whatever the buckets end up being, define them once.

8. Backend no_signal semantics (only if #2 = surface it).
no_signal currently requires signalCapable (true for claude-code and the other hook harnesses) and 90s of silence with FirstSignalAt zero. Confirm the 90s grace and that it should only ever apply to hook-capable harnesses (a hook-less harness must never show "stuck").

---

What stays the same (non-goals)

• The hook -> ActivityState derivation (claudecode/activity.go and siblings). That layer is correct; this is all downstream of it.
• The activity write path, CDC, SSE transport, and the reaper backstop for exited.
• Notifications: NotificationNeedsInput already fires only on the transition into waiting_input, which is consistent with the proposed "Needs input = agent blocked" meaning. ready_to_merge / pr_merged / pr_closed_unmerged are separate and untouched.
• POST /activity validation and the persisted activity_state CHECK set stay at the four ActivityState values.

---

Implementation blast radius

Mostly frontend. no_signal does not need an OpenAPI change (the API status field is already a plain string); it only needs to be added to the frontend SessionStatus union so it stops falling back to "working".

• backend/internal/service/session/status.go — deriveStatus precedence (Tracking: Lifecycle Manager + Session Manager lane #3), only if changed.
• frontend/src/renderer/types/workspace.ts — the core: SessionStatus union + set (add no_signal), toSessionStatus, workerDisplayStatus, attentionZone, sessionNeedsAttention, workerStatusPulses, workerStatusLabel. This is where the consolidation (feat(session): Session Manager — spawn/kill/list/get/send/restore/cleanup #7) lands.
• frontend/src/renderer/components/SessionsBoard.tsx — COLUMNS, BADGE.
• frontend/src/renderer/components/ShellTopbar.tsx — STATUS_PILL.
• frontend/src/renderer/components/SessionInspector.tsx — STATUS_PILL, activityDetail, the idle special-case.
• frontend/src/renderer/components/Sidebar.tsx — SessionDot.
• frontend/src/renderer/types/workspace.test.ts — update expectations.

---

If the direction (4-state pill + surface no_signal + one source of truth) is acceptable, the next step is to lock answers to the eight questions above and turn them into a single mapping table that all surfaces derive from. Feedback welcome on the buckets themselves, not just the edge cases.