# Session Model

StarAgent sessions are real tmux sessions. The dashboard never treats config files as source of truth.

## Types

- `agent`: a coding CLI session, such as Codex, Claude, OpenCode, or a shell worker.
- `system`: infrastructure tmux sessions owned by StarAgent or networking helpers.

System sessions are long-running infrastructure processes. They are represented as tmux sessions so they can be inspected, restarted, and managed with the same tmux-first model as coding work.

Current system sessions:

- `staragent-hub`: runs the Hub dashboard on the main machine.
- `staragent-node`: runs the Remote Node API on a worker machine.
- `staragent-tailscaled`: runs userspace Tailscale when the machine has no systemd or TUN device.

System sessions are visible in the dashboard for observability. Chat is disabled because these sessions are not coding agents; use Terminal to inspect logs or interact directly when debugging infrastructure.

## Ownership

- Local session: tmux session on the Hub machine.
- Remote session: tmux session on a Remote Node, reached through the node API.

The browser only talks to the Hub. The Hub either acts on local tmux directly or proxies the request to the owning node.

## Status

Session `status` is a short agent-lifecycle snapshot. It is independent from the browser Terminal connection and from whether tmux currently has an attached client.

Status values:

- `working`: the current agent turn is still running.
- `review`: the agent completed a turn that has not been viewed yet, or it needs visible input/approval.
- `idle`: the agent is ready, has no detectable turn, or its latest completion has already been viewed.

For Codex and Claude Code, StarAgent reads the newest relevant event from the CLI's native JSONL session data. Claude tool-use messages remain `working`; only a terminal turn event such as `end_turn` completes the turn. The status reader scans backward from the end of the file and stops at the first lifecycle event, so detection cost does not grow with the full conversation history. The recent bottom of the live pane is used only for visible approval/input prompts and as a fallback when native lifecycle data is unavailable.

Status precedence is: visible input prompt, active turn, unseen completed turn, then `idle`. Opening a completed Session marks that completion as seen. A visible input or approval prompt remains `review` until it is answered. Legacy `active` and `attached` reports are treated as `idle` because tmux activity is not evidence that an agent is working. Node connectivity is tracked separately at the Node level.

## Lifecycle

Create Session:

- Starts a new tmux session in a selected working directory.
- Runs the selected command, for example `codex --yolo`.
- The new session is an `agent` session.

Adopt Existing Tmux:

- Scans existing tmux panes for supported coding CLIs.
- Stores lightweight adoption metadata in `.staragent/adopted_sessions.json`.
- Keeps the original tmux session as the source of truth.

Stop:

- Stops created `agent` sessions.
- Adopted sessions are treated carefully in the UI because they existed before StarAgent.
- `system` sessions are read-only from Chat.

## Views

Terminal is the live tmux PTY view and accepts direct keyboard input.

Chat is derived from the tmux transcript using CLI-specific parsers. Chat sends messages through tmux, so terminal output remains authoritative.