Python kernel state #
A kernel snapshot carries serializable namespace values and selected kernel
state into a replacement. It is separate from the conversation projection
described in compaction.
kernel.snapshot and kernel.restore
take a path and timeout and return a Saved report. A busy kernel answers
Busy. A missing state file returns an Invalid error.
Saved namespace #
save_state excludes names beginning with _
and injected names. It records module import names, serializes other values with
dill when available or pickle otherwise, and stores captured definition
source separately. The snapshot also records the working directory and added
sys.path entries. It writes a temporary file and replaces the destination.
The serialized values have a 64 MiB total limit and an 8 MiB per-value limit. Definition source has a 256 KiB total limit and a 32 KiB per-definition limit. The report lists saved names, skipped names and reasons, the engine, definitions, and up to five large values. These limits apply to the listed components, not a promise about the total file size.
Restore and trust #
load_state restores path entries and
modules, kernel state, serialized values, and definition source. It retries
values deferred by an AttributeError after replaying definitions. It reports
failures and prior skips. If the saved working directory still exists, restore
changes to it.
Loading uses pickle and executes saved definition source. A state file therefore
belongs to the session's trust domain and must not be treated as safe untrusted
input. A successful restore does not imply every name survived. The Saved
report also includes output_lost when the saved kernel state reports lost
output or job-book channels. See
restore_kernel.
Unchanged snapshots #
snapshot reuses its previous report without
writing when the path and kernel change counter match and the file's
modification time and size still match. This is an optimization, not a content
integrity check. The kernel refuses a snapshot while cells are active or queued.
Idle resting sessions also checkpoint their kernel namespace in the background
checkpoint_idle_ms (2 s) after a turn settles (CheckpointKernel in
session.gleam), reusing the unchanged
snapshot check above. While a checkpoint is in flight (checkpointing), new
turns, AcquireKernel, and releases park behind it so the driver never rejects
a cell with Busy. Note that this writes the state file on every settled rest
whose namespace changed, and if a later turn crashes mid-cell before settling, a
restarted kernel restores from that previous rest's checkpoint rather than the
unsettled cells.
Because nearly every kernel now saves, its first checkpoint is part of its
steady-state memory. A kernel forked from the zygote holds about 200 KB more
anonymous memory once it has checkpointed.
albedo_state.py imports pickle at module
load, so the zygote loads it and forks share its pages. Do not move that import
back into the save path. Imported at the first save, it cost each forked kernel
another 200 KB of private memory.
State expiry #
state_expiry.expired selects
sessions whose last assistant activity has passed retention, with no observed
live kernel or running session. A missing activity timestamp does not qualify.
server.main configures retention through
ALBEDO_STATE_EXPIRY_SECONDS.
maintenance.expire protects captured
owners whose status observation failed. An uncertain observation must not
authorize deletion. Loaded sessions delete their own expired state through
session.expire_state. Keep that decision
inside the session actor, where kernel boots start. The actor rechecks for a
kernel or work that uses one because the sweep's earlier report can become
stale.
The state file reclaimer handles expired unloaded sessions and a separate orphan policy. Orphans are state files for IDs absent from the known-session list, with a file modification time at least one day old. This policy is distinct from session activity retention. Successful state-file deletion also removes its jobs sidecar.
Saved pastes and uploads #
Long pastes and uploaded chat files live under $ALBEDO_HOME/pastes/<session>/.
maintenance.prune_pastes runs during
the same expiry sweep and uses the same ALBEDO_STATE_EXPIRY_SECONDS retention.
pastes.prune deletes each regular file
whose modification time is older than the retention, then removes empty session
folders.
This policy uses file age, not session activity. An active conversation does not keep an old upload. A transcript can still name a file that has been deleted, so retained history does not mean the bytes are available. Deleting a session does not itself delete these files. They remain until the age-based sweep removes them.