# Session lifecycle and recovery This reference describes session identity, durable input, cancellation, and recovery. [OpenAPI](openapi.yaml) owns exact variants and fields. [HTTP API behavior](http-api-design.md) defines common authentication, errors, and pagination. ## Session representations `SessionSummary` and `Session` in [OpenAPI](openapi.yaml) define the representations. [`http_session_resource.gleam`](../src/albedo/daemon/http_session_resource.gleam) projects session reads. [Session ownership](../robot-docs/sessions.md) describes the actor behind them. Each summary captures its live status, progress, activity, and cursor together. A family address stays stable when a display name changes. Configuration has a separate canonical resource and validator, so unrelated live progress does not invalidate an edit. Pinning assigns a shared order once. Repeating a pinned value does not move the row or increment its visit count. Unpinning clears the order. Visits change only through the identified visit operation. Activity is a bounded display projection, not a second transcript. It includes the current partial line, generated-output counters, and identity-bearing input and answer observations. Clients derive rates from successive samples and install initial identities without replaying old animations. Argument previews stay in progress rather than being copied into activity lines. Kernel metadata is observational. A read does not prepare Python or expose executable process handles. Unknown job counts and lists are null. A known empty list is empty, and a bounded job list can be shorter than the reported count. Pending input summaries omit images and expanded model input. A continuation can consume a durable position without adding a text row. `input_order` is zero before admission and records the greatest accepted order thereafter. Optional compaction progress describes the current strategy stage, completed units, and a nullable stage total. It is transient state, not transcript content. A stage count is not an overall percentage. Clients can display elapsed time from the shared start timestamp. Main-request preparation and terminal outcomes clear this state. Usage timing belongs to the provider call that produced the observation. Missing timing remains null. Estimated token counts and provider-reported counts remain separate. OpenAPI supplies the bounds and optional-field rules for these projections. ## Collection reads `GET /sessions` accepts `scope=roots|all` and optional `parent_id`, `family_id`, `workspace`, `search`, `archived`, and `needs_reload`. The parent and family filters are mutually exclusive. `family_id` selects the containing root and all descendants. `search` matches display names and ID prefixes. `sort=activity|frequent` defaults to activity. Frequent sorts by opens, activity, and ID. Pinned state remains available for client grouping. The CLI's prompt, read, send, and stop workflows resolve a full lowercase UUIDv7 with `GET /sessions/{id}?view=configuration`, including child sessions. Only shortened IDs search the root-session collection and require an unambiguous match. Parent and family queries default to `scope=all`. Other queries default to roots. An explicitly supplied `scope=roots` with a parent or family filter returns `400`. The result is a page of `SessionSummary` objects. A family query also returns `family: { "root_id": ..., "revision": ... }`. Agent trees are drawn from `parent_id`, `address`, and `depth`. There is no second agent identity or graph endpoint. Clients can traverse all pages. A missing requested family returns `404`, while an existing parent with no children returns an empty page. `Accept: text/event-stream` selects the [collection watch](http-streams.md#collection-watch-and-overload). ## Creation, forks, and children `PUT /sessions/{session_id}` requires a fresh client-generated UUIDv7 and `If-None-Match: *`. Its body follows `SessionCreationRequest` in [OpenAPI](openapi.yaml): | Kind | Behavior | | --------------- | --------------------------------------------------------------------------------------------- | | `new` | Create an independent session with resolved defaults. | | `fork` | Copy a durable prefix into an independent session. | | `child` | Create a family member together with its initial durable task. | | `side_question` | Continue a captured [side-question exchange](#side-questions) in an independent session. | | `acp` | Create an editor-owned session with its initial [MCP overlay](#acp-sessions-and-attachments). | [`session/creation.gleam`](../src/albedo/daemon/session/creation.gleam) owns canonical intent. OpenAPI defines the required fields of each variant. Do not infer the union from the ordinary new, fork, and child flows alone. The daemon resolves defaults once at first admission. Child creation, family membership, creation decision, and initial input admission commit together. A rejected task leaves no orphan child. The child task is ordinary identified user input. Forks preserve full durable tool arguments and results, image references, captured execution traces, continuation boundaries, and selected extension overrides. They copy no Python namespace, live jobs, progress, or usage totals. The daemon closes incomplete tool exchanges at the chosen checkpoint using its existing history rules. `POST /sessions/{session_id}/rewind` is the in-place counterpart. It takes a `checkpoint_id` of a user message and an optional `summary` request. The daemon copies the whole session into a new archived session first, then deletes every row from the checkpoint on, and recomputes what derives from them (preview, tool-call index, captured traces, LCM nodes, image references). The session must be idle. Its actor stops, so attached streams reconnect and reset. `input` returns the removed message's text for the composer. With `summary`, the daemon summarises the removed tail before it changes anything and adds the result after the cut as a note from origin `rewind`. A failed summary leaves the session unchanged. The Python namespace and files on disk are not rewound. Rewind requires capability `history_rewind: 1`. Successful session creation returns `201` with `Session`, its `Location`, and `ETag`. A retained rejected creation returns its original problem and admission status on retry. An existing session fails the create precondition with `412`. Recovery reads the session and compares `creation.submitted` structurally with the original intent. The descriptor preserves the canonical submitted intent. String contents stay exact. Clients compare the returned descriptor according to its schema, including optional-field rules. Matching intent proves creation. A different intent is an ID conflict. Resolved workspace and provider defaults appear in `creation.resolved` and do not change the submitted descriptor. Current model, title, or workspace cannot replace that provenance check. Sessions stored before immutable provenance was recorded return `creation: null`. They remain readable, editable, and forkable, but cannot prove a matching creation request. Migration never invents submitted intent from their current configuration. Every newly admitted creation has provenance. Conditional creation follows [HTTP If-None-Match semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1.2). Creation decisions and deletion tombstones remain queryable at the same URI. Rejected creation reads return their original problem with `decision` metadata. Deleted session reads return `410 session_deleted` with creation provenance. An unknown young ID returns `404`, which cannot prove an in-flight PUT will never commit. Recovery retains the same intent and identity. `GET /sessions/{session_id}` returns `Session`. `tail`, default 100 and maximum 200, selects the recent history window. The byte bound can shorten the window. Status, progress, pending ownership, and the cursor share one session-actor capture. History is read through that capture's durable high-water mark. The configuration view does not accept `tail` or stream cursor parameters. ## Changes, visits, and deletion `GET /sessions/{session_id}?view=configuration` returns only editable metadata, preferences, overrides, and revision, with a strong `ETag`. Family membership is not configuration: the family revision appears only on the session representation (and its summary), so a child spawning, closing, or being deleted never makes a client's observed configuration stale. A workspace move and a subtree deletion send the family revision that read observed alongside the configuration `ETag`. The full session read embeds this same value and validator for an edit. `PATCH /sessions/{session_id}?view=configuration` accepts `name`, `provider_profile`, `model`, `effort`, `preferences`, and `selection`. An empty or null name restores the automatic title for a root, or the original family name for a child. A name the model chose with `/rename` is that automatic title, kept apart from configuration: it never changes the configuration validator, and the person's own `name` outranks it. Pin and archive changes are shared preferences. Model and composition changes require an idle session. Selection maps accept true, false, or null to clear the override and inherit the global default. A patch enabling one compaction strategy clears competing earlier true overrides to inheritance. Enabling multiple strategies in the same patch returns `400 selection_conflict`, and explicit false or null choices keep their meaning. When model or profile changes without an explicit effort, preserve the saved choice. `inherit` follows the profile override or model default; `default` bypasses the profile override. New sessions use `inherit` when effort is omitted or null. In a session PATCH, an explicit null restores legacy unset behavior. Explicit levels and inherited profile overrides unsupported by the selected model fail validation without changing saved state. Selection has `extensions`, `skills`, `instructions`, and `mcp` maps keyed by their catalog IDs. MCP entries enable or disable installed server definitions. Their IDs are stable definition names. Definitions and secrets belong to shared settings. Skill and instruction choices additionally include the write-only `catalog_revision` from the discovery read. A stale catalog returns `409 catalog_changed`. The session owner prepares a valid candidate before committing the patch. Editable session data and preferences commit together through the store owner. The result contains the captured session and the workspace-move result, `move`. The session's `configuration_resource` carries the saved configuration and validator. For ordinary configuration edits, `move` is null. PATCHes set explicit values. They never toggle or increment preferences. For example, a session selection patch clears one override and disables a skill: ```json { "selection": { "extensions": {"browser": null}, "skills": {"candidate-123": false} }, "catalog_revision": "observed-discovery-revision" } ``` Workspace changes use the same PATCH with `workspace` as its only change, alongside the observed `family_revision` as a write-only precondition. The daemon validates the destination and captures following descendants under the family revision. A busy target session returns `409 session_busy` before any move. The UI retains its deferred move intent. An idle parent can move while a descendant is busy. Destination metadata and deferred descendant intents commit in one store transaction before kernel cleanup. Busy descendants finish their captured turn in the old workspace and apply the new workspace at idle. Their `workspace_change` reports desired location, active location, and state `deferred` or `applying`. This intent survives client disconnect and daemon restart. The move preserves transcript and family addresses, resets affected kernels and Python namespaces, and returns applied and deferred counts, bounded ID lists, `truncated`, and cleanup warnings. When truncated, clients refresh the family rather than repeating a move to discover its result. Cleanup failure cannot be reported as rollback of a committed move. Affected sessions cannot begin a new turn in an old kernel after the commit. A later explicit move supersedes the earlier desired location by revision. A delayed completion cannot restore an older choice. New descendants inherit the parent's desired workspace at their admission. Model selection does not implicitly change the default for new sessions. The TUI's model picker saves profile defaults only through Ctrl+S and its confirmation. It leaves the starting profile unchanged. A later default or cap failure leaves a confirmed session model change visible. `PUT /sessions/{session_id}/visits/{visit_id}` accepts an empty object and counts one deliberate attachment. Repeating the UUIDv7 returns the same count without incrementing it again. Background refreshes do not create visits. Reads never change opens. Deleted sessions cannot be revived by a visit. `DELETE /sessions/{session_id}?view=configuration` defaults to `scope=leaf`. It requires the configuration `If-Match`, an idle session, and no children. `scope=subtree` also requires the `family_revision` query parameter from the session read. The daemon captures exactly that membership, prevents new child admission during this operation, interrupts members, cancels pending inputs, and deletes deepest first. Deletion returns `200` with `state: "complete"|"partial"`, `deleted_count`, `remaining_count`, `deleted_ids`, and `remaining` objects containing ID and safe reason. Counts cover the captured operation. Lists contain up to 200 IDs each and can shorten further to meet the byte limit, with `truncated: true`. Clients refresh the authoritative family or read known deletion tombstones. They never repeat deletion to page its result. Partial deletion is visible. Any successful deletion changes the family revision. A retry with the old revision cannot broaden the operation or delete new descendants. The client refreshes and confirms the remaining membership before a new deletion attempt. This operation has no automatic replay after transport loss. ## Input admission and outcomes [`operations.gleam`](../src/albedo/daemon/operations.gleam) owns durable admission, delivery, retention, and cancellation. `PUT /sessions/{session_id}/inputs/{input_id}` uses a client UUIDv7. The body follows the `InputRequest` union in [OpenAPI](openapi.yaml). Ordinary inputs can carry `client_id` for echo correlation. ACP prompts instead require the current attachment token and preserve ordered text and resource-link blocks. Message, continuation, skill, and command inputs share durable admission. Only a catalog command declared for input delivery can use that variant. Field inventories, image limits, and file limits belong to OpenAPI. A message requires nonblank text, an image, or a file. Images accept PNG, JPEG, GIF, and WebP, subject to decoding, dimension, and selected-provider bounds. The model receives the text, then the images in upload order. The CLI marks where each was attached with `[Image #N]` in the text, numbered from 1 in upload order. Pastes are marked the same way, `[Paste #N, …]` for the Nth paste. The model receives a paste under 100 lines and 32 KiB in place of its marker. A longer one is saved to `$ALBEDO_HOME/pastes//-.md` and its marker names that file. History shows the text as sent, markers intact. The daemon preserves original upload metadata and the full durable payload. Provider-specific fitting stays daemon-owned and appears in durable history. A message can also carry generic `files`, each a name and base64 data. A message with only files needs no text. Files require a local workspace, because the daemon saves them on its own host. A remote workspace rejects them with `attachment_workspace_unsupported`, and its images keep working. [`uploads.check`](../src/albedo/daemon/uploads.gleam) checks the workspace, each name, decoding, and the decoded total before preparation saves any paste or file. [`uploads.expand`](../src/albedo/daemon/uploads.gleam) then saves each file under `$ALBEDO_HOME/pastes//`. The saved name combines the input ID and a content hash, with a short alphanumeric extension retained when present. The uploaded filename is never a path component. The model's text gains a system note with each quoted filename and saved path. History keeps the text as sent. The user entry's `files` lists each file's name and decoded size in upload order, without the path or bytes. Entries recorded without files omit the field. Do not infer attachments from text that looks like a file label. Checking before writing is not a transaction. Saves happen during preparation, before admission. The session actor checks the workspace again when it admits the input, so a workspace that became remote in between still rejects it. A write failure or that later rejection can leave saved files behind until the [age-based sweep](../robot-docs/kernel-state.md#saved-pastes-and-uploads) removes them. A `files` entry in history does not mean the saved bytes still exist. Command inputs prepare a user turn. They do not invoke arbitrary management handlers. Their preparation produces content, runs outside the session actor, and persists the resolved content before transcript consumption. Preparation must be repeatable without external side effects. An extension that performs effects exposes its own domain operation instead. The first accepted PUT returns `202` with `Input`. An identical PUT returns the retained admission decision and current delivery state, using the original admission status. Changed intent under the same ID returns `409 input_conflict`. Echo-only `client_id` does not change identity. File names and data are part of intent, and a message without files keeps its earlier intent. To change attachments after a failure, send them under a new input ID. Lookup happens before current workspace, skill, provider, and queue validation. Defaults and skill content resolve once. Rejected decisions are durable, including `429 queue_full`. `GET /sessions/{session_id}/inputs/{input_id}` returns the known decision even after session deletion. The input resource separates its admission decision, delivery state, and turn outcome. Rejected admission retains the original safe problem and HTTP status. Delivery is pending, committed, or cancelled, and is null for rejection. A continuation has a durable position without a text row. `turn` identifies consumed turn membership and any durable terminal outcome: `running`, `completed`, `interrupted`, `failed`, or `abandoned`. A restarted daemon marks an unfinished previous run abandoned rather than claiming its external effects completed. One turn can contain several inputs. Its nullable `outcome` contains separately recorded detail. Null means no detail was recorded. Acceptance means safe storage. Commitment means transcript consumption. Neither means that the assistant answered or a tool effect ran exactly once. A waiting input is a row in the session's inbox, beside letters, events, and completion notices. The inbox holds at most 1000 waiting rows per session; an input that finds it full is rejected with `429 queue_full`. A duplicate consumes no slot. Consumption commits transcript rows, images, input delivery state, turn membership, and the inbox row's delivery in one store transaction. Failure leaves the input pending. Preparation failure exposes a safe blocking reason. It cannot install a successful delivery state. Waiting accepted inputs survive restart. People see, reorder, and drop what waits through the queue page; see [the inbox](../robot-docs/inbox.md). Known pending identities and inputs belonging to an unfinished turn never expire. An input becomes terminal only when delivery and its associated turn are terminal. Its admission record remains for seven days after that point. Rejected decisions become terminal at rejection. Live sessions retain creation provenance for their lifetime. Deleted sessions retain tombstones for seven days. Known decisions are checked first. Unknown UUIDv7 identities older than seven days return `410 identity_expired` and cannot execute. Identities more than five minutes ahead return `400 identity_future`. This prevents recreation after deduplication records expire. These rules also cover visit identities. Recovery queries the same input URI and may resend the exact same PUT within the caller's deadline. `404` means unknown at the time of the read, not safe to invent another ID. `410` stops automatic recovery and keeps an unresolved UI row. A matching durable event can still reconcile that row later. ## ACP sessions and attachments ACP input and session creation send an attachment token in the `Albedo-Attachment-Token` header, in addition to the daemon's auth token. The daemon keeps only a digest of each token, in memory, so a restart clears every attachment. Session creation stores HMAC-SHA256 fingerprints of the editor's MCP servers. A retried creation can match the original request without the daemon storing the editor's credentials. [OpenAPI](openapi.yaml) defines the routes. The [ACP reference](../robot-docs/acp.md) defines ownership, leases, and recovery. ## Targeted cancellation and interruption `POST /sessions/{session_id}/inputs/{input_id}/cancel` accepts an empty object. It returns the current `Input` and one `result`: - `cancelled`: a waiting input was removed and its cancellation committed. - `interrupt_requested`: its current turn belongs exclusively to this input. - `shared_running`: other inputs share the active turn. The turn continues. - `not_pending`: no waiting or interruptible exclusive work remains. Every input kind uses the same identity for admission, membership, and cancel. This operation never interrupts a later unrelated turn. Repeating it reports the current outcome of the same input, without resubmitting that input. A person's typed message that still waits can be edited in place. `POST /sessions/{session_id}/inputs/{input_id}/hold` with an empty object holds it and returns `lease_ms`: until the hold is released, lapses, or the edit is saved, neither it nor any input queued after it is read. Hold again before the lease runs out to keep editing. `POST …/edit` takes a message body like the `PUT`, replaces the waiting message under the same id and position, and releases the hold. `DELETE …/hold` lets the message be read as it was. Both answer `409 input_not_waiting` once the session read the message or it was cancelled. `POST /sessions/{session_id}/interrupt` requires `run_id`, nullable, and `through_input_order`, taken from the session snapshot. It cancels still-waiting inputs at or below that order and requests interruption of exactly that run. Newer queued inputs remain accepted. An already ended run is reported as ended. A later run is never interrupted by retrying this request. Acceptance of an interrupt request does not mean all external tools stopped. The result contains `run_id`, `state: "requested"|"already_ended"`, `cancelled_input_ids`, and warnings. Interruption prevents new inputs joining the captured run. Live status reports `interrupting` until the run ends. ## Human shell commands [`http_shell_commands.gleam`](../src/albedo/daemon/http_shell_commands.gleam) adapts the [shell-command owner](../src/albedo/daemon/shell_commands.gleam). The shell resource is separate from inputs and never starts a model turn. `PUT /sessions/{session_id}/shell-commands/{command_id}` accepts `{"command":"..."}` with a client-generated UUIDv7. Admission precedes spawn. Replay of the exact same command returns its original resource before mutable checks, different bytes conflict (409). A session permits one running command and 32 uncommitted outcomes. Admission also caps aggregate pending snapshot reservations at 512 KiB (JSON-escaped command bytes plus 12 KiB per record for preview and metadata), so large commands can reach capacity sooner. Commands contain 1-16384 UTF-8 bytes without NUL. Remote workspaces are refused explicitly. PUT and GET on the command URI, and POST on its `/stop` resource, return the current shell-command envelope defined in [OpenAPI](openapi.yaml). A nonzero process exit is still a completed command. Exit code, error, and committed history position can be null. Stop requests process-group cleanup. The response can still report running until cleanup is confirmed. Output reads use UTF-8 byte offsets and return complete code points. An offset inside a code point or outside the captured output is invalid. Reaching the current cutoff does not prove a running command has finished. Output capture is bounded and reports truncation. Direct reads and session snapshots use smaller previews than retained output. Clients use the output-paging operation for the complete retained prefix rather than assuming a preview is complete. Session reads, resets, and `shell_command` events carry uncommitted outcomes. After idle commitment, a history entry of kind `shell_command` carries the canonical outcome. Reconcile by command identity and history position. Completion does not admit a new model input. The model receives a labeled human command and outcome with a bounded output excerpt, not a fabricated tool invocation. The read-only `output.read_shell` binding pages retained output for that session. ## Side questions [`http_side_questions.gleam`](../src/albedo/daemon/http_side_questions.gleam) adapts the [side-question owner](../src/albedo/daemon/side_question.gleam). Capability `side_questions: 2` provides `PUT /sessions/{session_id}/side-questions/{question_id}` with `{question}`, `PATCH /sessions/{session_id}/side-questions/{question_id}` with `{dismissed}`, and `POST /sessions/{session_id}/side-questions/{question_id}/cancel` with an empty body. All three return `{side_question}`. Identity is a client UUIDv7. Replay with the same question returns the current exchange. A changed question conflicts, and another running exchange is busy. An unprepared session with no transcript history refuses admission; an unloaded session with history loads on demand and prepares context. Exchanges persist in `session_side_questions` across restarts (an in-flight `running` exchange comes back `failed`, and rewinding past `checkpoint` or deleting a continuation clears stale state). `PATCH` records whether the exchange's card is dismissed across views and reloads. No GET is needed: session resources, reset snapshots and `side_question` events carry the exchange, including `dismissed` and nullable answer, error and continuation session id. Identified session creation accepts `{kind: "side_question", source_session_id, side_question_id, name: null}`. Continue copies the captured committed prefix and appends the question and answer atomically. It does not invoke a provider. One exchange permits one continuation identity. Existing creation receipts and 412 preconditions keep retries valid after the source exchange is gone. ## Related guides - [API overview](http-api-design.md) - [HTTP streams and recovery](http-streams.md) - [Extension HTTP behavior](http-extensions.md) - [Change the HTTP API](contributing-api.md)