Session lifecycle

One Session Durable Object coordinates each session ID. The Worker stores saved exchanges in R2 and searchable metadata in D1. Harness integrations report the lifecycle events used for liveness and finalization.

stateDiagram-v2
    state first_event <>
    [*] --> first_event
    first_event --> Active: heartbeat, turn, or saved exchange
    first_event --> Finalizing: end
    Active --> Disconnected: about 90 seconds silent
    Active --> Finalizing: end event or explicit end
    Disconnected --> Active: accepted activity
    Disconnected --> Finalizing: end, explicit end, or about 10 minutes silent
    Finalizing --> Finalizing: durable write retry
    Finalizing --> Finalized: lifecycle state saved
    Finalized --> Active: new activity with the same ID

Starting

Sessions start when the first event or saved exchange arrives with a session ID. There is no separate start command. Installing Mimir or opening an idle harness does not create a session.

Oh My Pi waits for the first real turn. Hermes waits until direct-provider activity activates its plugin. Other harnesses may send a heartbeat when the session opens.

Finalizing

A session finalizes after:

• an end event from a supported harness;
• about ten minutes without activity; or
• mimir session end <id>.

Finalization writes the session lifecycle state and transcript manifest. Failed writes retry. Repeated end requests are safe.

Reopening

New activity with the same session ID reopens a finalized session and preserves its history. A new harness conversation should use a new ID.

Liveness

Liveness is based on event age:

• active: activity arrived within about 90 seconds;
• disconnected: more than 90 seconds have passed, but finalization has not run;
• finalized: the final lifecycle write completed.

Capture state and work outcome do not affect liveness. See Capture paths for evidence differences and Verify capture for persistence checks.