# 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](compaction.md). [`kernel.snapshot` and `kernel.restore`](../src/albedo/harness/kernel.gleam) 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`](../priv/python/albedo_state.py) 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`](../priv/python/albedo_state.py) 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`](../priv/python/albedo_cells.py). ## Unchanged snapshots [`snapshot`](../priv/python/albedo_cells.py) 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`](../src/albedo/daemon/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`](../priv/python/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`](../src/albedo/daemon/state_expiry.gleam) 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`](../src/albedo/daemon/server.gleam) configures retention through `ALBEDO_STATE_EXPIRY_SECONDS`. [`maintenance.expire`](../src/albedo/daemon/maintenance.gleam) 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`](../src/albedo/daemon/session.gleam). 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](../src/albedo/daemon/maintenance.gleam) 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//`. [`maintenance.prune_pastes`](../src/albedo/daemon/maintenance.gleam) runs during the same expiry sweep and uses the same `ALBEDO_STATE_EXPIRY_SECONDS` retention. [`pastes.prune`](../src/albedo/daemon/pastes.gleam) 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. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [The detached kernel](kernel.md) - [Compaction](compaction.md) - [Session attachment](sessions.md) - [Web client](web.md)