# 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](../harness-contract/api.md#session-lifecycle)).

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