# 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`).
- **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)).

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