# Terminal hosting

spt-core can *own* agent sessions in its own terminal layer: the daemon's
broker holds a real PTY per hosted session, which is what makes sessions
supervisable, attachable from other machines, and immune to self-update.

## What the broker holding the PTY buys

- **spt-hosted startup** — spt-core spawns sessions itself from the
  manifest's `[session.self]` template and binds them (`api bind`), instead
  of waiting inside someone else's process tree.
- **Remote attach** — a byte-stream viewport onto a live session from any
  paired node (compute and files stay on the hosting node). Restart-safe:
  reconnects resume the stream without gaps or duplicates.
- **Input injection** — `send-keys`/`send-line` style injection per the
  adapter's declared `[inject]` methods, respecting activity state (never
  disrupt a working agent).
- **The live digest** — `spt endpoint digest <id>` shows an at-a-glance view of
  what a session is doing now (`--follow` streams changes), **projected from the
  endpoint's normalized session logs** (the digest-record contract over
  `[history]`), never the PTY byte stream. Topology-independent — it works for a
  harness-hosted endpoint with no broker PTY. For scripted, turn-end consumption,
  `--json` adds an incremental cursor (v0.16.0): `--last <N>` reads the last N
  turns; closed-turn transcript entries (`Agent`/`ToolSprint`) carry a stable
  `seq` and each turn its `input_seq` — `Boundary`/`Context` entries never carry
  one, and a `partial` trailing turn's entries carry none until it closes;
  `--after <seq>` cursors over `seq`/`input_seq` and returns only what is
  newer. See the
  [integration checklist](../harness-contract/integration-checklist.md#incremental-digest-consumption--the---json-cursor).
- **Update immunity** — PTYs live in the broker, logic in the brain; a
  self-update swaps the brain while every hosted process and byte stream
  stays intact.

Activity and idleness are always **reported** (`api state busy|idle`), never
inferred from terminal quiescence — quiet terminals lie.


<!-- [doc->REQ-ATTACH-AWAY-ALERTS] -->
## When nobody is watching

An spt-hosted terminal can run for a long time with no controller and no viewer
attached — the agent keeps working, and everything it says goes to a screen
nobody is reading. So spt tells it.

- After **five minutes** with no controller *and* no viewer attached, the owner
  agent receives a notice: proceed, but do not assume the user can see your
  output, and **withhold user-aimed information** until somebody attaches. It is
  told it will be notified when that happens.
- When **anybody** attaches again — a controller or a viewer, from any node — it
  receives a short return notice and the withholding lifts.

Two properties are worth relying on:

- **The return notice only ever follows an away notice.** An agent that was never
  told nobody was watching is never told someone came back — the second message
  is meaningless without the first.
- **The notices cannot wake the agent.** They ride the spool-only hook channel,
  with no live delivery, so they arrive at the agent's next turn boundary — which
  is the only moment it could act on them anyway. A message about nobody watching
  must not itself be the thing that starts a turn.

Only endpoints the broker actually hosts a terminal for are in scope: an endpoint
with no hosted session cannot be attached to, so there is nothing to be away
from.

Shells linked to the endpoint see the same fact from the other side, as
[`attach` frames](../shells/frames.md#attach--who-is-attached-to-the-owners-terminal).

<!-- [doc->REQ-ATTACH-CLIENT-STALE] -->
## Running attach clients after an update

An open attach client keeps running the binary it started with. Updating the
installed binary does not replace that client process, and the broker's version
does not tell you which client code is rendering your terminal.

`ATTACH_CLIENT_STALE` is a client advisory, not a warning about every version
difference. Its release-maintained policy names a minimum recommended client,
the affected platform and attach role, and the concrete function that is
degraded. Controller and read-only viewer roles are evaluated separately.
Unknown client versions do not trigger the advisory.

The notice recommends reopening the client when a sufficient binary is already
installed on the client node; otherwise it recommends updating that client and
then reopening it. It never forces a detach or prescribes a daemon restart for
client-only skew. Unchanged advice is not repeatedly printed.

## Commands

`spt endpoint digest` · the attach surface · [`spt api` injection-adjacent calls](../harness-contract/api.md).

*Deeper tutorial coming with the docs' next tier.*