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.
• 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.

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.

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.

Deeper tutorial coming with the docs’ next tier.