#[non_exhaustive]pub struct Session {Show 37 fields
pub session_id: String,
pub path: String,
pub status: SessionStatus,
pub active_turn_id: Option<String>,
pub created_at: String,
pub updated_at: String,
pub workspace_root: Option<String>,
pub provider_id: Option<String>,
pub model_id: Option<String>,
pub approval_mode: Option<EffectiveApprovalModeState>,
pub permission_state: Option<EffectivePermissionState>,
pub attention: Option<Vec<AttentionFlag>>,
pub needs_input_reasons: Option<Vec<NeedsInputReason>>,
pub last_activity_at: Option<String>,
pub turn_count: u64,
pub forked_from: Option<ForkProvenance>,
pub side_from: Option<SideProvenance>,
pub name: Option<String>,
pub name_origin: Option<SessionNameOrigin>,
pub generated_name: Option<String>,
pub title: Option<String>,
pub first_user_prompt: Option<String>,
pub branch: Option<String>,
pub probe_degraded_reason: Option<ProbeDegradedReason>,
pub kind: Option<SessionKind>,
pub parent_session_id: Option<String>,
pub created_by_client: Option<ClientInfo>,
pub resumed_by_client: Option<ClientInfo>,
pub spawned_by: Option<SessionSpawnedBy>,
pub drive_holder: Option<ClientInfo>,
pub external_wait: Option<ExternalWaitView>,
pub worktree: Option<SessionWorktree>,
pub current_limits: Option<SessionLimits>,
pub running_elsewhere: Option<RunningElsewhere>,
pub quiescent: Option<bool>,
pub item_count: Option<u64>,
pub log_bytes: Option<u64>,
}Expand description
The session object every lifecycle method returns or lists.
Additive-optional evolution applies: clients must ignore unknown fields.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.session_id: StringThe session identity.
path: StringAbsolute path of the session’s durable log; non-nullable. Under the ephemeral session profile it is the empty string, meaning “no durable log exists” — the one value a client must not hand to a filesystem call.
status: SessionStatusLoad state as this host knows it; session/list reports notLoaded for
sessions loaded by other hosts.
active_turn_id: Option<String>The turnId of the current foreground turn when a turn is in flight
(parked under needsInput included), and null otherwise.
Required-nullable. Every served Session carries the member: null
when no turn is in flight or the session is not loaded, the turn id
when one is. An optional-absent shape would publish it as plain
string and reject every idle Session frame the host sends.
created_at: StringRFC3339. For a fork this is the fork session id’s UUIDv7 mint instant.
updated_at: StringRFC3339; never precedes createdAt.
workspace_root: Option<String>The winning metadata fold’s workspace root; null when that record
omits it — absent is never fabricated.
provider_id: Option<String>The winning metadata fold’s provider; null when that record omits it.
model_id: Option<String>The winning metadata fold’s model; null when that record omits it.
approval_mode: Option<EffectiveApprovalModeState>The folded effective approval mode. Additive-optional: a Session
object that omits it means the host has not folded a mode, which is why
the index-derived session/list entry may legitimately omit it.
permission_state: Option<EffectivePermissionState>The folded effective permission state. Additive-optional: a
"notLoaded" row omits it (no live evidence, matching the attention
precedent) and an older host omits it everywhere; absent is unknown,
never active. approvalMode stays the effective-mode answer; this never
restates it.
attention: Option<Vec<AttentionFlag>>Attention flags. Additive-optional, present only when at least one
flag is set; absence is a NON-assertion (nothing pending, or the loaded
session’s pending source declined to answer). Loaded sessions only: a
notLoaded row omits it even while its durable pending set is
non-empty.
needs_input_reasons: Option<Vec<NeedsInputReason>>Why the session’s input is needed. Additive-optional, present only
when non-empty; status is needsInput exactly when this set is
non-empty (loaded sessions). Absence is a NON-assertion, on the
attention discipline. Loaded sessions only: a notLoaded row omits it
even while its durable pending set is non-empty. Experimental:
stripped per-connection for unopted callers.
last_activity_at: Option<String>Content-activity recency, RFC3339. Additive-optional: omitted when
no content record exists. Never advanced by lifecycle bookkeeping (the
resume marker, re-stamps) or a fork’s copied seed-replay records, and
never precedes createdAt.
turn_count: u64Completed-turn count from the session view fold.
forked_from: Option<ForkProvenance>null for root sessions; fork provenance otherwise.
side_from: Option<SideProvenance>null for root sessions and forks; side provenance otherwise. A session
carries at most one of forkedFrom and sideFrom.
name: Option<String>The durable allocated session name. Additive-optional: present when
the serving path holds an allocated name, omitted otherwise — absent is
never fabricated. Authoritative and renameable via session/rename.
name_origin: Option<SessionNameOrigin>How the served name was set. Additive-optional, fold-only: the
snapshot fold (session/read, the resume/start/fork-ack snapshot)
derives and carries it from the log; session/list rows never carry it.
Absent — and any value the client does not recognize — reads as unknown,
never fabricated.
generated_name: Option<String>The served generated short title. Additive-optional, fold-only:
the snapshot fold derives the latest retained generated pair’s short
title from the log; session/list rows never carry it. Omitted when no
pair was ever published — absent reads as unpublished, never fabricated,
never inferred from the name text. name stays the canonical name it
always was.
title: Option<String>Derived display title: a heuristic that may evolve — its carriage, not its derivation, is the contract. Additive-optional, omitted when underivable.
first_user_prompt: Option<String>Derived first-user-prompt preview. Additive-optional, omitted when underivable.
branch: Option<String>Derived workspace branch — the index’s last derived value; the
live-change signal stays session/branchChanged. Additive-optional,
omitted when underivable.
probe_degraded_reason: Option<ProbeDegradedReason>Why the workspace status probe produced no fresh reading — the index’s
last derived value, like branch, so the TUI can show WHY status is
unavailable instead of a generic unavailable. Additive-optional,
omitted when the latest probed observation carries no reason or none
exists. Open enum: a client treats an unknown-but-present reason and
renders it, never rejecting the row.
kind: Option<SessionKind>What kind of session this is. Open enum, v1 values "root" and
"subagent"; a client treats an unknown value as an unknown-but-present
kind and renders it, never rejecting the row. Additive-optional:
absence asserts nothing — the host could not determine the home shape,
or the value is not yet available to serve.
parent_session_id: Option<String>The containing session’s id when kind is "subagent" — the id of the
TOP-LEVEL session whose home holds this child, which is not
necessarily the session that spawned it: native-child homes are
physical siblings under the outer session’s subagent/ directory, so a
subagent spawned by another subagent resolves to the outer session, not
to its spawner. A client building a tree from this field gets one level,
not a chain. Flat rather than nested: there is exactly one fact to
carry, unlike forkedFrom’s structured ForkProvenance.
Additive-optional; a root carries none.
created_by_client: Option<ClientInfo>The handshake ClientInfo recorded when the session was opened, echoed
verbatim — provenance, never an interpretation, and never a visibility
gate. Additive-optional; absence has four indistinguishable causes:
an in-process open; an earlier record; a half stamp where only one of
name/version was recorded and ClientInfo requires both; and a session
with no admitting handshake of its own — a fork child or a subagent —
which never carries a stamp to begin with.
resumed_by_client: Option<ClientInfo>The handshake ClientInfo of the connection whose wire session/resume
most recently loaded this session: stamped on the durable
session.resumed marker, folded into the session index, and served from
that column by every carrier; while the session is loaded, the stamp the
loading resume wrote replaces the column on every carrier (the ack,
session/read, session/list, session/listChanged), and after the
next fold the column serves it. Additive-optional and provenance
only; a resume with no admitting handshake (TUI, exec) stamps nothing,
a warm attach to an already-loaded session writes no marker, and a half
stamp serves nothing, so absence asserts nothing. createdByClient
never follows a resume.
spawned_by: Option<SessionSpawnedBy>The session that opened this one, recorded once in this session’s
creation record and served from the session index. Unlike the containing
session parentSessionId names above, its parentSessionId is the
exact spawner, except that any muse started in a later pane of the
worker’s tmux session or Herdr workspace names the worker’s manager and
carries the worker’s project/thread labels; project and thread
are opaque labels the spawner may name beside it. Additive-optional
and provenance only: never a visibility or authority gate. Absence
asserts nothing — no recorded spawner, a later session of the spawned
process, a row folded before the member existed, or a session the index
has not folded yet.
drive_holder: Option<ClientInfo>The handshake ClientInfo of the connection that currently holds this
session’s drive grant, served on session/read only, as name and
version (the handshake’s display title is never served, the
createdByClient rule). Additive-optional, loaded-only, live:
present exactly when a live connection holds the grant and its handshake
is known; absent on notLoaded rows, once the holder’s connection drops
(its orphaned turn included), and for a holder with no handshake stamp.
Provenance only: whether a client may drive is answered by
session/resume / turn/start (sessionInUse), never by this member.
external_wait: Option<ExternalWaitView>The live host-declared external wait for this session, served on
session/read only.
Additive-optional, loaded-only, live: present exactly while
a declaration is live for the loaded session; absent on
notLoaded rows, once the declaration is cleared, once the next
user input clears it, and after a restart or resume, which lose
it. Presence is the declaration — a client must never infer one
from any other member.
worktree: Option<SessionWorktree>The worktree this session runs in — path and origin only (the branch
stays in branch). Experimental (Session.worktree; stripped
per-connection for unopted callers). Omitted when the session runs in no
worktree.
current_limits: Option<SessionLimits>This session’s effective limits: the clamp output — each axis the
session chose clamps its durable stored choice (the clamp input) to the
live ceiling, and an axis it never chose reads the daemon default:
untrusted unless the daemon serves trusted by default, and the daemon’s
own posture on the sandbox axes, except that a resume over a sandbox-off
posture can keep a recorded sandbox on, and a session/fork or
session/sideChat child starts with its parent’s recorded shell, write
and sandbox limits and its parent’s chosen trust, clamped to the live
ceiling. A sandbox kept on this way over a sandbox-off posture runs its
recorded network, or restricted when none was recorded, while a
tracked change is open. These are the limits the session runs with.
Experimental, same-user socket only (Session.currentLimits;
stripped per-connection for unopted callers). Loaded sessions only
(notLoaded rows and hosts with no limits regime omit it) — absent is
never fabricated.
running_elsewhere: Option<RunningElsewhere>That another live process on this machine runs this session, and which
kind of process when the host can tell. Experimental
(Session.runningElsewhere; stripped per-connection for unopted
callers), on session/list rows and the session/listChanged frames
built from the same row. No frame is pushed when only this member
changes; a client sees the change on its next session/list or on a
frame sent for another reason. Present exactly when the answering host
does not hold the session loaded and another live process on this
machine does (it holds the session’s writer lease, or a live local
session registry record names the session), so only notLoaded rows
carry it. Absence asserts only that the host saw no other holder when it
built the row. Provenance only: whether a client may drive is answered
by session/resume / turn/start (sessionInUse), never by this
member.
quiescent: Option<bool>Whether the answering host holds no live work for this loaded session:
the held predicate the host’s idle unload and upgrade drain use, over
the pending answer attention reads. true when it finds no run in
flight or finishing its post-run work, no owned background task or live
background process, no background completion waiting to wake the
session, no session-name or goal-recovery work, and no pending approval,
user-input or admission request; false while any is held or a read
cannot prove it absent. Experimental (Session.quiescent; stripped
per-connection for unopted callers) and loaded-only: carried by
session/read, session/list rows, the session/resume result and the
session/listChanged frames built from the same row. A run or a pending
request starting pushes a frame carrying false; other held work
(session-name maintenance, a leave in progress) shows on the next read.
A session served false is rechecked about once a second and its frame
is pushed once it reads true. Absent on notLoaded rows, on a host
whose session_quiescent_witness gate is off, and for a session with no
live pending-request source: absence asserts nothing.
item_count: Option<u64>The published head’s ordinal (kt-dvw5): the head reference’s own
ordinal — the count of head slots in its sequence, including any
reserved ones — as of the probe that served this row. A sizing
hint for a first view/page, so the Console can size its page
without folding the log. Additive-optional, present only on
metadata reads (session/read with excludeItems), where the
client has no items to count; full reads carry the items
themselves and omit it. Absent when no head is published (unknown),
never fabricated. May lag a live log: the head is a snapshot, and
appends after its publication are not counted.
log_bytes: Option<u64>The durable log’s byte length at read time (kt-dvw5): the size hint
paired with itemCount, so the Console can size its first page
without folding the log. Additive-optional, present only on
metadata reads (session/read with excludeItems); full reads omit
it. Absent when the log’s length is not known (unknown), never
fabricated. A live log grows after the read; the value is a snapshot.