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 hollow UNBOUND row, distinct from 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 process, spawned/resumed from the adapter’s psyche_init/psyche_resume templates.

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.

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.