Agent execution sessions

What a session is

A session is a durable, auditable record that groups one unit of agent work - the arc from inspecting the environment, through planning, authorizing, and applying a change, to verifying the result:

Agent → Session → Context/Inspect → Plan → Authorization/Approval → Apply → Operation/Deployment → Verify → completion

It is the tracking primitive that lets an agent (or a different agent, after a restart) answer “what work was in flight, what did it touch, and where did it get to?” by reading durable state - without Phelix ever deciding or executing the next step. A session is deliberately not an execution engine (it runs nothing), not an authorization principal (a session id is an identifier, never a credential), and not a second source of truth (it references plans, operations, and deployments by id and never copies their state).

Closing a session (complete / fail / cancel) does not stop a deployment, cancel an operation, or change an application. It ends the tracking workflow, nothing else.

Lifecycle

create                         → activeactive   --checkpoint-------->   active        (record a step and/or link references)active   --complete-------->     completedactive   --fail----------->      failedactive   --cancel--------->      cancelled{completed, failed, cancelled} → (terminal - no transition; never re-activated)

A mutation on a terminal session is refused with SESSION_INVALID_TRANSITION and the record is left exactly as it was. completed means the tracking workflow finished - it is a reported outcome, not a verified statement about runtime health, and a failed operation does not force the session to failed. Establish health independently (phelix operation status, phelix inspect deployment|health).

Schema

A session is stored as one JSON file at <data-dir>/sessions/<session-id>.json (0600), serialized deterministically.

{  "schema_version": "1",  "session_id": "ses_1a2b3c4d5e6f7081",  "status": "active",  "title": "ship billing v3",  "app": "billing",  "actor": { "type": "cli", "id": null, "authenticated": false },  "rev": 3,  "plan_ids": ["pln_…"],  "operation_ids": ["op_…"],  "deployment_ids": ["dep-…"],  "checkpoint": { "step": "deploy", "note": "canary at 10%", "at_ms": 0, "seq": 2 },  "final_result": "shipped v3 to 100%",  "events": [ { "seq": 0, "type": "created", "at_ms": 0, "detail": "session created" } ]}

session_id is ses_ + 16 hex, minted at creation. actor is provenance only (cli, or mcp under phelix mcp serve), derived server-side and never taken from client input. rev is a monotonic revision - the optimistic-concurrency token for --if-rev. events is append-only, honest provenance (not a cryptographically signed audit log). Over-cap input is rejected with INVALID_ARGUMENT, never silently truncated, and all free text passes the shared redactor before persistence.

CLI

Every command accepts --json and emits the standard machine envelope.

phelix session create --title "ship billing v3" --app billing --jsonphelix session show ses_1a2b3c4d5e6f7081 --jsonphelix session list --status active --app billing --limit 20 --jsonphelix session checkpoint ses_… --step deploy --note "canary at 10%" \    --plan pln_… --operation op_… --deployment dep-… --jsonphelix session complete ses_… --result "shipped v3 to 100%" --jsonphelix session fail ses_… --reason "canary regressed; rolled back" --jsonphelix session cancel ses_… --reason "superseded by a newer plan" --json

checkpoint / complete / fail / cancel accept --if-rev N: the change applies only if the session is still at revision N, otherwise it is refused with SESSION_CONFLICT (retryable - re-read and retry). A session is its own ses_ artifact, not an operation, so the success envelope is read-shaped with no operation_id (like plan create). session show adds a resolved block reporting each reference as present, missing, unavailable, or unknown.

Recovery after an interruption

The point of a durable session is that a restarted agent resumes by reading. Phelix never re-runs an interrupted plan or infers that an incomplete operation failed. A new agent should:

1. 1
   session list / show

   Find sessions, then read status, checkpoint, and references.
2. 2
   plan show

   Re-verify each linked plan's current applicability - it may now be stale.
3. 3
   operation status

   Read each linked operation's real status (succeeded / failed / running / indeterminate).
4. 4
   inspect deployment|health

   Check live state, then decide what to do next - Phelix does not decide for it.

Authorization & security

• A session grants nothing. Creating or modifying a session, or linking a plan to it, confers no execution right. The only path that executes is plan apply, through the unchanged authorization boundary; an approval-required plan still returns APPROVAL_REQUIRED after it is referenced by a session.
• No forged identity. The actor is produced by the authenticator, not from tool inputs or flags; there is no --actor. The MCP caller records mcp, the CLI records cli, and the two never merge.
• Fail closed. Missing, malformed, and corrupt records fail with their codes and zero mutation; invalid transitions leave the record untouched.
• No secrets, honest provenance. Free text is redacted before persistence; the event history is append-only and ordered but not tamper-proof. As with approvals, the data directory is the trust boundary - protect ~/.phelix/ at the OS level (see Security).

MCP tools

The MCP adapter exposes six session tools that reuse the exact CLI logic over local stdio: phelix_session_create, _show, _list, _checkpoint, _complete, and _fail. _fail is included so an agent can honestly record a non-success outcome rather than mislabel work completed. Session cancellation and the --if-rev guard are CLI-only. None of these tools executes, authorizes, or mutates a deployment, and an MCP-created session records mcp provenance automatically.