URL: https://sabermage.github.io/spt-releases/lifecycle/overview.md
Content-Type: text/markdown
Method: text

---

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

| Square | State | What it means |
|---|---|---|
| green ■ | online · free | bound and message-addressable; you can control it |
| blue ■ | online · controlled | someone is driving it (the detail pane names the controlling node) |
| red ■ | online · unbound | a live session not yet message-bound — attachable with `spt rc`, needs attention |
| amber ▢ | online · harness-only | visible but has no control seat, so it cannot be controlled |
| gray ■ | suspended | cold but its machine is up — wakeable |
| gray ▢ | offline | the machine is down (only ever seen for remote endpoints) |

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