Sessions
The durable runtime unit AGH creates, attaches, audits, and governs.
- Audience
- Operators running durable agent work
- Focus
- Sessions guidance shaped for scanability, day-two clarity, and operator context.
A session is the unit AGH actually manages. It binds one agent subprocess to a workspace, permission policy, event store, and attach record under one stable AGH session ID.
Live session events are written to events.db while the session runs. After the session stops,
AGH materializes a read-only forensic JSONL ledger at
$AGH_HOME/sessions/<workspace_id>/<session_id>/ledger.jsonl (or
$AGH_HOME/sessions/_unbound/<session_id>/ledger.jsonl when no workspace is resolved). The ledger
is content-addressed and idempotent on rerun, never accepted as a memory scope, and never read by
the recall pipeline — it is operator-readable history only.
Session-scoped Vault refs use vault:sessions/<session_id>/<name>. They are ordinary encrypted
Vault records filtered by the session prefix, and the session inspector shows only redacted metadata
for those refs.
Use this section when a live run needs supervision or forensic detail: why it started, what state it entered, which events were persisted, whether it can be attached, and which permission checks apply while the agent works. If the problem is choosing an agent definition, use Agents first. If the problem is the daemon or database itself, use Operations after you identify the affected session.
The reading order follows the lifecycle. Start with lifecycle for state names and stop classification, move to events when you need the durable record, then use resume attach and permissions for the two most common operator questions: "can I re-enter this live session?" and "why did AGH ask before acting?"
In this section
Create, activate, stop, and classify sessions
Use this page for the state machine, stop behavior, timeout boundaries, and what AGH persists across the session lifetime.
Session presence, attachability, and wake eligibility
Use this page for metadata-only health, the authority boundary against task-run leases and HEARTBEAT.md, and the session health/status/inspect CLI/API surfaces.
Attach to live sessions and replay stored work
Use this page to understand explicit resume attach, deterministic recap, transcript markers, and replay reconstruction.
Query, stream, and persist session events
Use this page for the event catalog, SSE behavior, SQLite storage, and the difference between persisted streams and prompt streams.
Static modes, workspace boundaries, and approval flow
Use this page to understand what `deny-all`, `approve-reads`, and `approve-all` actually permit and how interactive approvals work.
Session-scoped secret metadata
Use this page when a session needs write-only encrypted refs such as `vault:sessions/<session_id>/<name>`.