Live-agent lifecycle

What makes an agent endpoint a persistent being rather than a disposable session: identity that survives resets, a working memory that follows it across machines, and graceful endings that never lose context.

The pieces

• Perch — the durable seat (identity, spool, state). Sessions attach to it (api bind/listen), reset across it (api boundary), and end without destroying it (api session-end).
• Bringup states — spt endpoint run creates the perch, starts the harness session, and the harness calls api bind to bring it online. Between the session starting and that bind the endpoint is unbound: a live, attachable session — spt rc <id> connects to it to watch or clear a bringup prompt before bind — that is not yet message-addressable (a send waits for online). The picker and spt endpoint list show it as a distinct unbound row — see the status-square legend below — not a true offline one. (since v0.14.0)
• The mind, in two tiers — a live tier (who the agent is, what it’s doing) that follows the endpoint everywhere, and a project tier scoped to one project. Both are versioned, tracked storage, synced to paired machines with the same scoping.
• Commune — the agent drops <id>-commune.md into the adapter’s watched directory; spt-core ingests the delta into the right tier. A file-drop, not a command — any harness that can write a file can commune.
• Signoff — the graceful ending: final commune, then teardown (spt endpoint shutdown / api shutdown). The echo-commune fires before teardown, always.
• Echo-commune — sessions that end without a signoff keep their delta: spt-core runs the adapter’s bounded summarizer template over the session history and ingests the result. The echo gate sentinel (armed on idle, cleared by graceful signoff) is what marks the need.
• Psyche — the endpoint’s persistent-context companion, driven as a bounded per-event turn (not a resident process): the daemon runs one [session.psyche_resume] turn per event ([session.psyche_init] is the go-live gate, never spawned).

Rest and wake

Endpoints rest instead of dying: dormant (warm — zero idle compute, instantly wakeable) or suspended (cold), explicitly via spt endpoint suspend or on attention-shift. Resting instances stay addressable; deferred messages are held and released exactly once on wake (spt endpoint wake). Every active→resting edge fires a transition echo so the final context delta lands before the lights go out.

Reading the picker

The spt endpoint run picker (and spt endpoint list) marks each endpoint with a status square. A filled square means you can act now — control it if it is online, or wake it if it is suspended; a hollow square means you cannot (no control seat, or the machine is gone). Endpoints on other machines in the subnet now render with the same square as local ones, so a remote row tells you everything a local row does. (remote parity since v0.17.0)

Commands

spt endpoint shutdown · endpoint suspend · endpoint wake · the api lifecycle calls (reference).

Agents bringing themselves up live read spt how-to live — the in-binary, always-current bringup guidance (the persistent listen relay, the Psyche seam, ready-vs-live).

Deeper tutorial coming with the docs’ next tier; the contract above is complete and current.