Unify session-state precedence, preserve agent exit vs tmux termination, and standardize status colors

[whoisasx]

Summary

AO currently has the right raw ingredients for session state, but it combines and presents them with the wrong precedence:

session.activity      Raw agent runtime activity
session.isTerminated  AO/tmux session lifecycle fact
session.prs           Durable SCM/PR facts
session.status        Display status derived from the facts above

This causes a live agent to remain visually stuck in In review, Needs you, or Ready to merge after it resumes work. It also collapses an agent process exiting into the AO/tmux session being terminated, even though the tmux session can remain alive and inspectable.

The same underlying ambiguity reaches the UI:

• Kanban placement is driven by derived session.status.
• The topbar activity pill is correctly driven by raw session.activity.
• The sidebar dot is currently driven by Kanban/attention status instead of raw agent activity.
• Working and Needs you use adjacent orange/yellow colors that are difficult to distinguish.
• Merged, Terminated, Exited, and Unknown do not yet have a sufficiently clear and consistent semantic treatment.

This issue defines one canonical state-priority model, preserves the distinction between agent exit and tmux termination, aligns all affected frontend surfaces, and establishes a semantic color system for both dark and light themes.

User-facing problem

Active work can remain in the wrong Kanban column

Today, once a session owns an open PR, PR/SCM status is evaluated before activity.active. A session that resumes work can therefore remain:

• In review because the PR is open, draft, or awaiting review
• Needs you because CI failed or changes were requested
• Ready to merge because the PR is approved/mergeable

The board no longer answers the most immediate question: "Which agents are working right now?"

Expected behavior:

For every non-terminal session, active agent work wins. SCM determines board placement only when the agent is not actively working.

Agent exit and tmux termination are conflated

These are different facts:

• activity = exited means the agent process/runtime inside the tmux session exited.
• isTerminated = true means AO considers the managed session terminal.

A terminated tmux/AO session necessarily has no running agent, so termination may normalize activity to exited.

The reverse is not true. An agent can exit while tmux remains alive and leaves an interactive shell behind. That state must remain inspectable and visible as Exited in Needs you.

Status visuals do not communicate a stable semantic language

The current dark-theme tokens use:

Working    #F59F4C  orange
Needs you  #E8C14A  yellow/amber

These hues are too similar in compact dots, badges, and column accents. Merged and Terminated also collapse into passive Done styling, while Exited and Unknown are both muted gray in the activity presentation.

Current implementation and root cause

Backend display priority

backend/internal/service/session/status.go::deriveStatus() currently evaluates:

1. isTerminated -> merged or terminated
2. waiting_input / blocked -> needs_input
3. open PR aggregation
4. any merged PR
5. activity.active -> working
6. missing hook signal -> no_signal
7. idle

Because active comes after open PR and merged-PR checks, it cannot produce working while an open PR exists.

Lifecycle collapse

backend/internal/lifecycle/manager.go::ApplyActivitySignal() currently does this for ActivityExited:

if s.State == domain.ActivityExited {
    next.IsTerminated = true
}

This destroys the valid combination:

activity = exited
isTerminated = false
tmux still alive

The storage model already persists activity_state and is_terminated independently, so no schema change is needed to represent this correctly.

Existing safety behavior

backend/internal/sessionguard/guard.go already refuses both user/API delivery and AO-generated nudges when activity = exited, even if isTerminated = false.

That check must remain. After the agent exits, the pane may contain an interactive shell; automatically pasting an agent prompt into it could execute the prompt as shell commands.

Important lifecycle caveat

In the current code, MarkTerminated updates durable state without necessarily tearing down the external runtime/worktree. Merge and tracker completion can call this flag-only path.

Physical runtime/worktree cleanup is already tracked separately in:

• Merge-triggered termination leaves orphaned worktree: MarkTerminated skips teardown, Kill button vanishes, no auto-cleanup #2811
• fix: merged PR sessions disappear from sidebar AND leak runtime RAM (not torn down) #2834

This issue must not duplicate that cleanup work. It should establish the state contract that an agent-exit hook alone never marks the AO session terminated. Any claim that isTerminated literally proves tmux destruction depends on the teardown issues above being resolved.

Canonical concepts

Agent activity

Raw, persisted activity reported by the agent hook pipeline:

active
idle
waiting_input
blocked
exited

Frontend-only unknown remains a defensive fallback for missing, invalid, or version-skewed data. It is not a backend business state.

Session status

A display status derived by the backend at read time from:

• activity_state
• is_terminated
• PR lifecycle, CI, review, comments, and mergeability facts
• hook-signal capability and first-signal timing

Derived status must not be stored.

Attention zone

The frontend grouping derived from backend session.status:

Working
Needs you
In review
Ready to merge
Done

Idle remains a nested stack at the bottom of Working, not a separate top-level column.

Required priority and board placement

Priority	AO/tmux session	Agent activity	SCM condition	Derived status	Kanban placement
1	Terminated	Exited	Any attributed PR merged	merged	Done
2	Terminated	Exited	No attributed PR merged	terminated	Done
3	Alive	Active	Any non-terminal SCM condition	working	Working
4	Alive	Exited	Any SCM condition	exited	Needs you
5	Alive	Waiting input	Any SCM condition	needs_input	Needs you
6	Alive	Blocked	Any SCM condition	needs_input	Needs you
7	Alive	Idle	CI failing or changes requested	Existing SCM status	Needs you
8	Alive	Idle	PR open, draft, or review pending	Existing SCM status	In review
9	Alive	Idle	Approved or mergeable	Existing SCM status	Ready to merge
10	Alive	Idle	No open PR	idle	Idle stack inside Working

Additional defensive behavior:

• no_signal remains in Needs you.
• Frontend unknown remains visible in Needs you and should produce telemetry/logging.
• A merged PR observed before terminal bookkeeping completes may temporarily derive merged as a defensive fallback, but activity.active still wins while the live agent is working.

Proposed backend derivation

if rec.IsTerminated {
    if anyMerged(prs) {
        return domain.StatusMerged
    }
    return domain.StatusTerminated
}

switch rec.Activity.State {
case domain.ActivityActive:
    return domain.StatusWorking
case domain.ActivityExited:
    return domain.StatusExited
case domain.ActivityWaitingInput, domain.ActivityBlocked:
    return domain.StatusNeedsInput
}

open := openPRs(prs)
if len(open) > 0 {
    return aggregatePRStatus(open)
}

if anyMerged(prs) {
    return domain.StatusMerged
}

if signalCapable && rec.FirstSignalAt.IsZero() &&
    now.Sub(rec.Activity.LastActivityAt) > noSignalGrace {
    return domain.StatusNoSignal
}

return domain.StatusIdle

Transition examples

Agent resumes from In review

Before: activity=idle, PR=review_pending
Status: review_pending
Board: In review

Hook: activity -> active

After: status=working
Board: Working

Agent resumes from Needs you

Before: activity=waiting_input or blocked
Status: needs_input
Board: Needs you

Hook: activity -> active

After: status=working
Board: Working

The same applies when the session was in Needs you because CI failed or changes were requested: active work moves it to Working; once the agent returns to idle, SCM facts determine its column again.

Agent becomes idle after opening a PR

activity=idle
PR=open/draft/review_pending

Status: PR-derived status
Board: In review

Agent becomes idle without a PR

activity=idle
no open PR

Status: idle
Board: nested Idle stack inside Working

Agent exits but tmux remains

activity=exited
isTerminated=false

Status: exited
Board: Needs you
Terminal: remains inspectable
Automated pane delivery: suppressed

AO/tmux session becomes terminal

isTerminated=true

Any PR merged -> merged
Otherwise     -> terminated

Source of truth by frontend surface

Surface	Source	Meaning
Kanban column	Backend-derived session.status	Current workflow/attention placement
Session card badge	Backend-derived session.status	Exact session/SCM display state
Topbar activity pill	Raw session.activity	What the agent runtime is doing now
Inspector activity row	Raw session.activity	Agent runtime activity timeline
Browser working indicator	Raw session.activity	Whether the agent is actively working
Sidebar session dot	Raw session.activity	Compact agent runtime activity

All mappings should remain centralized in frontend/src/renderer/lib/session-presentation.ts. Components must not add independent status/activity switch statements.

Semantic color system

Color must be paired with text labels and motion/state treatment. It must not be the only carrier of meaning.

Kanban zones and terminal cards

Visual role	Dark theme	Light theme	Treatment
Working	Teal #36C2B4	Teal #087F75	Live/operational; active indicator may breathe
Needs you	Amber #F2B84B	Amber #946200	Human attention; static
In review	Blue #5B8DEF	Blue #255FC4	External review/waiting
Ready to merge	Light green #75C98D	Green #237A3D	Ready but not completed
Merged	Forest surface #173624, accent #4BAE72	Surface #D9F2E1, accent #176B37	Completed successfully; use readable accent on dark surface
Idle	Gray #8E96A3	Gray #69717D	Quiet nested stack
Terminated	Graphite #6F7680	Graphite #626975	Neutral terminal outcome

Terminated should not use red. Termination can be intentional and is not inherently a failure. Red is reserved for actionable failure states such as Exited and CI failed.

Agent activity pill and sidebar dot

Activity	Dark theme	Light theme	Motion
active	Teal #36C2B4	Teal #087F75	Breathe/pulse
idle	Gray #8E96A3	Gray #69717D	Static
waiting_input	Amber #F2B84B	Amber #946200	Static
blocked	Amber #F2B84B	Amber #946200	Static
exited	Coral red #EE6A6A	Red #B83232	Static
unknown	Violet #A78BFA	Violet #6D46C2	Static

Card-level exceptions inside an attention zone

The column color communicates the high-level attention bucket. The card badge may communicate the exact cause:

• ci_failed and exited: red/coral
• changes_requested and needs_input: amber
• no_signal and unknown: violet
• pr_open, draft, and review_pending: blue
• approved and mergeable: light green
• merged: dark forest-green surface with readable green accent
• terminated: graphite

Introduce role-specific status tokens rather than continuing to overload generic warning/success colors:

--color-status-working
--color-status-needs-you
--color-status-in-review
--color-status-ready
--color-status-merged
--color-status-merged-surface
--color-status-idle
--color-status-exited
--color-status-terminated
--color-status-unknown

Both themes must meet contrast requirements for text, dots, borders, and subtle card surfaces.

Live propagation

No new transport is required. The existing path is sufficient:

Agent hook reports activity
-> lifecycle manager persists activity_state
-> SQLite trigger writes session_updated to change_log
-> daemon SSE stream publishes the CDC event
-> frontend debounces invalidation by 150 ms
-> workspace query refetches sessions
-> backend derives the new status
-> board, topbar, sidebar, and inspector rerender

Normal connected behavior should move a card shortly after the activity hook arrives. The existing 15-second workspace polling interval remains the fallback if SSE is unavailable.

Implementation plan

Backend lifecycle and domain

• Stop setting IsTerminated = true solely because an ActivityExited hook arrived.
• Preserve activity=exited, isTerminated=false while tmux/AO runtime remains available.
• Continue normalizing activity to exited when the AO session is actually marked terminal.
• Clear in-memory tool-flight/permission state when the agent exits.
• Add derived domain.StatusExited.
• Add exited to the session API status enum.
• Reorder deriveStatus() so active wins over all non-terminal SCM/input display states.
• Keep waiting_input and blocked mapped to needs_input whenever the current activity remains paused on the user.
• Keep no_signal behavior unchanged.
• Audit automated reaction entry checks so an exited agent is not repeatedly targeted for pane nudges.
• Preserve the just-in-time session guard refusal for exited agents.
• Prefer a distinct AGENT_EXITED send error over inaccurately reporting an exited-but-live-tmux session as SESSION_TERMINATED.

API contract

• Regenerate the OpenAPI spec and frontend schema with npm run api.
• Commit the generated backend OpenAPI and frontend TypeScript artifacts together.

Frontend presentation

• Add exited to SessionStatus parsing and defensive conversion.
• Map status=exited to the Needs you attention zone.
• Add the Exited card badge.
• Keep board placement driven by backend session.status.
• Keep the topbar, inspector, and browser activity indicators driven by raw session.activity.
• Change the sidebar dot to use the same raw activity presentation as the topbar.
• Keep idle sessions in the nested Idle stack inside Working.
• Add the role-specific status color tokens for dark and light themes.
• Apply the semantic palette consistently to columns, card badges, the merged/terminated Done cards, activity pills, and sidebar dots.
• Ensure only active/working indicators breathe; attention, exited, terminated, and unknown indicators stay static.
• Log or emit telemetry when the frontend falls back to unknown.

Safety requirements

• Never paste automated text into a tmux pane after the agent exited; it may execute in the shell.
• Do not infer tmux death from an agent-exit hook.
• Do not infer session death from a failed or unknown runtime probe.
• Do not store derived session.status.
• Do not add parallel/manual CDC emission; existing SQLite triggers remain authoritative.
• Do not force-delete dirty registered worktrees.
• Do not fold the separate merge-triggered runtime/worktree cleanup tracked by Merge-triggered termination leaves orphaned worktree: MarkTerminated skips teardown, Kill button vanishes, no auto-cleanup #2811 and fix: merged PR sessions disappear from sidebar AND leak runtime RAM (not torn down) #2834 into an unreviewed state-presentation change.

Required test matrix

Backend status derivation

• Active + no PR -> working
• Active + PR open -> working
• Active + draft PR -> working
• Active + review pending -> working
• Active + CI failing -> working
• Active + changes requested -> working
• Active + approved/mergeable -> working
• Waiting input + no PR -> needs_input
• Blocked + no PR -> needs_input
• Waiting/blocked -> active transition with a PR -> working
• Idle + PR open/review pending/draft -> corresponding PR status
• Idle + CI failing/changes requested -> corresponding actionable PR status
• Idle + approved/mergeable -> corresponding merge-ready status
• Idle + no PR -> idle
• Exited + non-terminated + any PR state -> exited
• Terminated + merged PR -> merged
• Terminated + no merged PR -> terminated
• Existing multi-PR and stacked-PR worst-wins behavior remains correct when activity is idle

Lifecycle and safety

• Agent-exit hook stores activity=exited without setting isTerminated
• Explicit/runtime termination sets isTerminated=true and activity exited
• Exited agents reject user/API delivery
• Exited agents reject AO-generated nudges
• Exited agents do not accumulate stale tool-flight state
• A later valid active signal can represent an agent relaunched in the still-live tmux session

Frontend

• exited parses as a real session status, not unknown
• Exited card renders in Needs you with an Exited badge
• Active agent with any PR status renders in Working
• Idle agent with PR renders in the correct SCM column
• Idle agent without PR renders in the nested Idle stack
• Merged and Terminated cards have distinct Done treatments
• Topbar activity pill and sidebar dot use the same raw activity mapping
• Dark and light theme status tokens render with readable contrast
• Only active/working indicators animate
• Unknown remains visible, labeled, non-animated, and actionable

Event propagation

• Activity-state changes emit session_updated
• SSE invalidation refetches workspace/session data
• The board moves after the live event without waiting for the 15-second polling fallback

Acceptance criteria

• A session in In review or Needs you moves to Working as soon as its current agent activity becomes active.
• When that agent becomes idle again, SCM facts determine whether it returns to Needs you, In review, or Ready to merge.
• An idle session without an open PR stays in the nested Idle stack.
• An agent exit does not terminate a still-live tmux/AO session.
• An exited agent is visible in Needs you and its terminal remains inspectable.
• A terminal session is shown as Merged when any attributed PR merged; otherwise it is shown as Terminated.
• Board status remains backend-derived and no derived display status is persisted.
• Topbar and sidebar activity indicators consume the same raw activity truth.
• Working and Needs you are visually distinct at a glance.
• Ready to merge and Merged use related but clearly different green treatments.
• Terminated is neutral graphite, not failure red.
• Exited is actionable coral red.
• Unknown is visible violet and emits diagnostics.
• Existing runtime/worktree safety constraints remain intact.

Related issues

• Sidebar dot + kanban badge locked to PR status — agent working/idle state invisible once PR exists #2944 - Narrow reproduction of active agents remaining visually locked to PR status. This issue establishes the broader canonical model and implementation contract.
• bug(session activity): waiting_input masks PR-derived status after worker opens a PR #2174 - Proposes PR status overriding waiting_input. The priority in this issue should supersede/re-evaluate that expectation: current active work wins, while a genuinely current waiting/blocked state remains Needs you.
• Centralize frontend session state presentation and align dashboard status visuals #2751 - Completed centralization of frontend presentation helpers. This issue should extend that module rather than reintroducing component-local interpretation.
• Sync session topbar status to agent activity #2540 - Completed topbar switch to raw agent activity.
• feat(web): simplify sidebar dot colors to a 5-bucket scheme centered on human action #1985 - Earlier sidebar color simplification proposal. This issue provides the revised semantic palette and raw-activity source for the sidebar dot.
• Session detail page should treat exited activity as restorable #1225 - Exited/restorable UX. Under this model, exited with live tmux is not the same as a terminated restorable session and should be re-evaluated accordingly.
• Merge-triggered termination leaves orphaned worktree: MarkTerminated skips teardown, Kill button vanishes, no auto-cleanup #2811 - Merge-triggered MarkTerminated skips runtime/worktree teardown.
• fix: merged PR sessions disappear from sidebar AND leak runtime RAM (not torn down) #2834 - Merged sessions disappear while runtime resources remain.
• bug(lifecycle/scm): merge-triggered termination races the still-working agent — PRs opened after termination are never attributed or enriched #2879 - Merge-triggered termination can race an agent that is still working.

Non-goals

• Redesigning the full Kanban layout
• Creating a separate top-level Idle column
• Changing SCM polling or observation behavior
• Replacing SSE/CDC transport
• Storing derived session status
• Solving merge-triggered worktree/runtime cleanup already tracked in Merge-triggered termination leaves orphaned worktree: MarkTerminated skips teardown, Kill button vanishes, no auto-cleanup #2811 and fix: merged PR sessions disappear from sidebar AND leak runtime RAM (not torn down) #2834
• Adding a full agent-relaunch workflow for exited agents; this issue only preserves the correct state and safe, inspectable UI

[whoisasx]

Implementation update

The consolidated implementation is complete on codex/issue-2950-session-state. This branch covers the canonical state model from this issue and also incorporates the overlapping board, merged-session lifecycle, and PR activity work that had been developed in separate PRs.

1. Canonical backend status precedence

Session display status continues to be derived at read time from durable facts; it is not stored independently.

The implemented precedence is:

1. A terminated AO runtime resolves to merged when an attributed PR merged, otherwise terminated.
2. For a live runtime, activity=active resolves to working, regardless of open/draft/review/CI/mergeability state.
3. A live runtime with activity=exited resolves to exited without marking the AO/tmux session terminated.
4. waiting_input and blocked resolve to needs_input.
5. When the agent is idle, open PR facts determine CI failure, changes requested, draft, review, open, approved, or mergeable status.
6. A merged PR resolves to merged when no higher-priority live activity applies.
7. No PR falls back to idle, while the existing no_signal protection remains intact.

The existing multi-PR/stacked-PR worst-wins aggregation remains in place.

2. Agent exit is separate from runtime termination

• Lifecycle no longer converts an agent exited signal into isTerminated=true.
• Exited agents remain visible and their terminal remains inspectable.
• Session guard blocks AO/user prompt delivery into an exited agent pane because it may now contain a shell.
• Runtime termination still normalizes activity to exited and remains the only terminal lifecycle fact.
• Tool-flight and permission state is cleared when the agent process exits.

Codex now has end-to-end exit detection even though it does not expose a reliable session-end hook:

• Codex opts into AO's generic process supervisor.
• Every supervised launch receives a persisted launch ID so stale exit reports from an older process cannot affect a newer launch.
• The supervisor emits a fenced process-exited activity event when Codex ends.
• tmux and ConPTY expose supervised-process liveness for reaper reconciliation when the event is missed.
• Daemon startup runs the same conservative reconciliation to recover exits that happened while AO was stopped.
• Exiting Codex still falls through to the existing interactive keep-alive shell, so the tmux session remains usable for commands such as cd, ls, and relaunching the agent.
• Failed or unknown runtime probes are not treated as proof of death.

3. Frontend state presentation is centralized

• Board placement and card badges consume backend-derived session.status.
• Topbar activity pill and sidebar session dot both consume raw session.activity through the same presentation helper.
• Active, idle, waiting input, blocked, exited, and unknown activity now have one shared mapping.
• unknown remains a visible frontend-only defensive fallback and emits diagnostics instead of silently becoming another state.
• A merged-but-live session is treated as active until isTerminated=true, so it remains navigable and can still be terminated manually.

This removes the original mismatch where the topbar could say Idle while the sidebar showed a working/attention-colored animated dot.

4. Board, lane, archive, and color behavior

• The first lane is now Idle / Working.
• Idle sessions are visible in the primary upper region.
• The Working region appears below only when active work exists, with independent counts and dots.
• Needs you and In review remain separate attention lanes; pending/draft/open PR states stay under In review when the agent is idle.
• Ready to merge and Merged now share a split Ready to merge / Merged lane with visually distinct green treatments.
• Live merged sessions remain in the Merged region until they are actually terminated.
• Terminated sessions and terminated merged sessions move into Archive.
• Archive supports grid and row layouts, persists the user's choice, defaults to grid, and uses a compact restore action.
• Working, Needs you, In review, Ready, Merged, Idle, Exited, Terminated, and Unknown now use role-specific dark/light theme tokens.
• Terminated is neutral graphite rather than failure red; Exited/CI failure retain the actionable failure treatment.

5. Merged-session lifecycle controls

• A per-session terminateOnPrMerge preference is persisted and exposed through the API.
• The Summary inspector contains the opt-in toggle.
• When enabled, SCM merge completion routes through Session Manager's normal kill path so runtime/workspace teardown completes before terminal facts are recorded.
• When disabled, merging a PR does not remove the live session from the sidebar or terminate its runtime.
• A merged live session can be terminated manually from the Summary inspector or its Merged board card.
• The shared termination hook now owns transport, telemetry, cache invalidation, and errors for all termination surfaces.

6. PR activity and workspace UX included in the consolidated branch

• PR summaries persist and expose stateChangedAt.
• Draft/open/merged activity timeline entries show their actual transition time and link to the PR.
• Session pages open with the Summary inspector alongside the terminal by default.
• The collapsed sidebar uses a hover preview from its toggle, overlays content instead of shifting it, and keeps native titlebar controls aligned with smooth transitions.
• Dashboard, board, sidebar, session card, and Summary spacing were tightened; PR state labels were made more compact.

7. Final cleanup

• Removed an unused agent exit-detection enum value.
• Removed a redundant merged-card style override.
• Consolidated the topbar kill request into the shared termination hook.
• Hardened termination error handling for transport failures without an HTTP response.
• Removed the stale assumption that all merged sessions are inactive.

Related and superseded work

• Sidebar dot + kanban badge locked to PR status — agent working/idle state invisible once PR exists #2944 is the narrower reproduction of the active-agent/PR-precedence bug and is covered by this implementation.
• fix(board): make idle-first work lane clearer #2924 implements the overlapping Idle/Working lane concept. Its final behavior is incorporated and extended here, so the consolidated PR should supersede that duplicate PR.
• fix: terminate merged PR sessions through lifecycle #2840 contains the earlier merged-session teardown work. This branch incorporates it with the final opt-in policy, manual termination actions, and state-precedence guarantees.
• fix: expose PR activity timing #2841 contains the earlier PR activity timing work. Its persistence/API/timeline behavior is incorporated here.
• Current main worker-idle delivery work from fix(lifecycle): durably deliver worker-idle completions to the orchestrator #2836 was merged into this branch; both that behavior and this issue's exit/termination behavior are preserved.

Validation completed

• go test -p 1 ./... passed across all backend packages after merging current main.
• Focused post-merge tests also passed for Codex, daemon wiring, lifecycle, session manager, session guard, SQLite migrations/store, tmux, and ConPTY.
• Frontend TypeScript typecheck passed.
• npm test -- --run --maxWorkers=1 passed all 886 frontend tests across 73 files.
• Focused session-state/presentation/topbar, command-palette, and prior full-suite timeout reruns also passed.
• git diff --check passed.

The consolidated implementation is now available in #2980. It closes #2950 and supersedes the overlapping open PRs above. Visual evidence will be attached to that PR separately.