# Agents and sessions Source: https://docs.ideharmony.com/concepts/agents-and-sessions ## A terminal is not an agent This is the first distinction to internalise. A pane can run a plain shell forever and never involve a model. Panes are containers; agents are participants. | Thing | Is it an agent? | |---|---| | A pane running `bash` | No | | A pane running a provider CLI | Yes, while that CLI is driving a model | | The Harmony TUI | Yes | | A detached session with no client attached | Yes — it exists independently of any view | ## What a session is A session is a durable conversation, owned by the daemon. Your terminal or window is a **view** onto it. Because the daemon owns it, a session survives closing the client, closing the terminal, and rebooting. It does not survive being explicitly stopped, and it does not survive past its retention window. ```powershell harmony sessions list ``` ## Attached, detached, stopped | State | Session | Your view | |---|---|---| | Attached | Running | Showing it | | Detached | **Running** | Released | | Stopped | Ended | Gone | Detaching is the normal thing to do when work will take a while. Stopping is a decision to end something. ## Process alive is not working > [!IMPORTANT] > An agent can hold a session open, keep a process alive, print output, and > advance nothing. Liveness is not progress. This is why Harmony reports delivery state from evidence rather than from process existence, and why the honest answer is sometimes `unknown`. See [delivery lifecycle](/docs/a2a/delivery-lifecycle). The reliable signal is task state: ```powershell harmony tasks list ``` ## Principals A session runs as a registered **principal** — an identity the session host knows about. This is what makes it possible to say which agent did something, rather than only that something happened. ## One session, many clients Two clients can watch the same session. Neither writes to it directly; both issue RPCs and the daemon serialises the result. This is why a handoff from the TUI to the desktop loses nothing — the desktop is simply a second view of state that was never in the TUI to begin with. ```text /desktop ``` ## Sessions and providers A session has an execution route: which harness, provider, account, model, and effort it runs with. Changing the route mid-session is possible via `/provider` and `/model`, and it is a real change — later turns can behave differently from earlier ones in the same transcript. See [providers, models, and routes](/docs/concepts/providers-models-and-routes). ## Related - [Session survival](/docs/concepts/session-survival) - [Sessions in the TUI](/docs/tui/sessions) - [Tasks, plans, and runs](/docs/concepts/tasks-plans-and-runs)