# Session Standup Command Center Design

## Problem

CTM already supports many long-lived sessions, but the operator cost rises when
multiple agents are active at once. Each terminal has its own context, and a new
session does not inherit the hard-won context from an existing one. Reusing
sessions is therefore necessary, but reuse creates a second problem: the user
must remember what every session is doing, whether it is blocked, and what the
next useful instruction should be.

The Standup Command Center is a central dashboard for that operating loop. It is
not a replacement for session terminals. It is a "manager view" over existing
sessions that answers:

- What is every active session doing?
- Which sessions need the user's attention?
- Which sessions are ready to review or finish?
- What should the user do next for each session?
- How can the user quickly deep dive and issue instructions without losing the
  fleet-level view?

## Research Signals

Open-source projects validate the need for a control-plane style UI, but CTM
should borrow the operating patterns rather than replatforming the runtime.

- Mission Control positions itself as an open-source dashboard for agent fleets,
  tasks, costs, workflows, logs, memory, alerts, and quality gates:
  https://github.com/builderz-labs/mission-control
- AutoGen Studio shows that multi-agent debugging benefits from explicit
  sessions, observable messages, metrics, and reusable agent components, but it
  is framed as a prototyping UI rather than a production app:
  https://autogenhub.github.io/autogen/blog/2023/12/01/AutoGenStudio/
- OpenHands exposes a local GUI, REST API, CLI-compatible coding-agent workflow,
  and cloud/enterprise surfaces for scaling coding agents:
  https://github.com/OpenHands/OpenHands
- LangGraph's product framing emphasizes human-in-the-loop checks, persistent
  memory, and streaming as first-class agent UX primitives:
  https://www.langchain.com/langgraph

The design conclusion for CTM: do not add a manager-of-managers orchestration
runtime. CTM already has terminals, stream capture, recent-session history,
worktree state, approval detection, and review panels. The right abstraction is
a reusable dashboard projection over those signals, with deterministic manager
recommendations first and optional LLM annotations later.

## Existing CTM Substrate

The feature should reuse these existing surfaces:

- `lib/session-stream.js`: summary, intent, progress, last prompt, stream status.
- `lib/status-hooks.js`: idle, busy, and waiting-input state transitions.
- `server.js` session payloads: active sessions, provider, cwd, branch, modified
  time, capabilities, and worktree status.
- `/api/recent-sessions`: historical sessions and project filtering.
- `/api/stream/status` and `/api/sessions/:id/summary`: stream health and
  per-session summary.
- Review tab and session deep links: structured transcript and review flows.

## UX Model

The first screen in CTM Sessions should become the operator dashboard when no
terminal is selected. The dashboard is dense, operational, and scannable. It is
closer to a standup board than a marketing landing page.

Primary regions:

1. Fleet header
   - Total active sessions.
   - Counts by lane.
   - Last refresh time.
   - Refresh action.
   - New Session action.

2. Attention ribbon
   - Highest priority sessions needing input or approval.
   - Shows only the action needed and evidence.
   - Lets the user open the session directly.

3. Lanes
   - Running: active output or recent work.
   - Ready Review: worktree changes, completed work, or reviewable artifacts.
   - Needs User: approvals, questions, waiting input, or explicit blockers.
   - Continue Later: idle, stale, or context-preserving sessions.

4. Session card
   - Title and agent/provider.
   - State badge and age.
   - Intent: one-line goal.
   - Progress: one-line latest progress.
   - Manager recommendation: what the user should do next.
   - Evidence chips: waiting input, branch, worktree, last prompt, last activity.
   - Actions: Open, Review when supported, and Send Instruction when a terminal
     target is available.

5. Deep dive behavior
   - Open keeps the user's mental model simple: jump into the session terminal.
   - Review opens the transcript/review panel when the agent supports it.
   - Send Instruction targets the existing prompt/queue mechanism in a later
     phase; the first implementation can focus the session and preserve the
     command center as the resume surface.

## Manager Recommendation Taxonomy

Recommendations must be conservative and explainable. They should be derived
from existing signals and include evidence. They should never claim certainty
from weak heuristics.

Recommended action kinds:

- `approval_needed`: approve, deny, or answer a tool prompt.
- `needs_input`: user instruction appears required.
- `review`: inspect completed work or worktree changes.
- `watch`: session is running; no action needed right now.
- `resume`: session is idle but can continue with more instruction.
- `investigate`: session appears failed or blocked.
- `archive`: work appears complete and inactive.

Lane priority:

1. Failed or blocked signals.
2. Waiting input or approval.
3. Reviewable worktree/session output.
4. Running or recently active sessions.
5. Idle or stale sessions.

Each recommendation includes:

- `lane`: where it appears on the board.
- `actionKind`: stable machine-readable action.
- `actionLabel`: short CTA text.
- `recommendation`: short human-readable manager note.
- `confidence`: `high`, `medium`, or `low`.
- `evidence`: short strings tied to concrete signals.

## API Contract

Add `GET /api/sessions/standup`.

Response shape:

```json
{
  "generatedAt": "2026-04-30T12:00:00.000Z",
  "counts": {
    "total": 3,
    "needs_user": 1,
    "ready_review": 1,
    "running": 1,
    "continue_later": 0
  },
  "lanes": [
    {
      "id": "needs_user",
      "title": "Needs User",
      "sessions": []
    }
  ],
  "sessions": [
    {
      "id": "ctm-session-id",
      "agentSessionId": "agent-session-id",
      "title": "Fix build failure",
      "agent": "codex",
      "provider": "openai",
      "cwd": "/repo",
      "branch": "fix-build",
      "status": "waiting_input",
      "lane": "needs_user",
      "actionKind": "approval_needed",
      "actionLabel": "Respond",
      "recommendation": "Approval or input is waiting in the terminal.",
      "confidence": "high",
      "evidence": ["waiting_input", "last activity 2m ago"],
      "intent": "Fix build failure",
      "progress": "Waiting for command approval",
      "lastActivity": "2026-04-30T11:58:00.000Z",
      "worktree": {
        "branch": "fix-build",
        "dirtyFiles": 2,
        "unmergedCommits": 1
      },
      "capabilities": {
        "review": true,
        "resume": true
      }
    }
  ]
}
```

The endpoint should be pure projection logic over active sessions first. Recent
sessions can be added as a later extension once the active-session dashboard is
stable.

### Cache And Refresh Contract

The overview must not block first paint on expensive transcript/timeline work.
`GET /api/sessions/standup` serves a materialized in-process snapshot when one
exists and refreshes it in the background when it is dirty or older than the
short refresh interval. If the process has no materialized snapshot yet, the
endpoint returns a fast bootstrap snapshot that skips timeline projection and
AI attention classification, then schedules a full refresh.

Response metadata:

- `revision`: content revision for incremental clients.
- `incremental`: `true` when the response is a delta against `?since=...`.
- `unchanged`: `true` when the client revision is current.
- `stale`: `true` when the response is known to be dirty or old enough to call
  out as stale.
- `refreshing`: `true` when a background materialized refresh is scheduled or
  running.
- `snapshotSource`: `bootstrap-fast` or `materialized`.

Desktop and mobile clients should render their last complete cached snapshot
immediately, then request `/api/sessions/standup?since=<revision>` in the
background. The user should see existing cards with a `refreshing` indicator,
not an empty `Loading sessions...` board, unless no cached snapshot exists.

## Implementation Phases

Phase 1: Design document

- Commit this design.

Phase 2: Backend projection

- Add a pure `lib/session-standup.js` module.
- Classify sessions into lanes and recommendations.
- Add unit tests for the classifier and snapshot builder.
- Add `GET /api/sessions/standup`.

Phase 3: Dashboard UI

- Replace the empty Sessions welcome panel with the Standup Command Center.
- Fetch `/api/sessions/standup`.
- Render fleet header, attention ribbon, lanes, cards, and actions.
- Keep the UI within the existing CTM visual language: compact, dark,
  terminal-adjacent, and operational.

Phase 4: Verification and polish

- Run focused unit tests.
- Run an isolated CTM dev server on random ports, never the primary 3456/3457.
- Curl the new API.
- Drive the dashboard in a real browser and confirm it renders without layout
  overlap or blank states.

Future phase: Manager annotations

- Add optional LLM-generated manager notes only after deterministic
  recommendations are useful.
- Store annotation provenance and age.
- Do not let the LLM issue autonomous cross-session commands; it can propose
  actions, not execute them.

## Open Questions

- Should historical/recent sessions appear on the same board or in a secondary
  "Resume Later" view?
- Should Send Instruction fan out to multiple sessions, or should the first
  version stay one-session-at-a-time?
- Should manager annotations be cached per session turn, per stream summary, or
  per dashboard refresh?
