Repository navigation
docs(fork): the snapshot reset runbook for a snapshot-layout change - #264
Merged
Merged
Conversation
… snapshot layout A release that changes what a snapshot holds or how it is laid out, such as the PATH_MAX-safe snapshot tars, makes every snapshot written before it useless to it and the reverse, and nothing re-takes a golden on a Substrate roll by itself. The runbook resets every golden and session snapshot kagent holds on an installation after such a roll, in either direction, with what the failure looks like, the steps and what does not work instead; the ledger row of the snapshot tars points to it. Signed-off-by: Timo Derstappen <teemow@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The 1.8.0 line carries upstream's PATH_MAX-safe snapshot tars (agent-substrate#2110 and agent-substrate#2111): a snapshot written before them does not resume after them, nor the reverse, and upstream ships no migration (pre-1.0, a security fix). Nothing re-takes a golden on a Substrate roll by itself — kagent keys an ActorTemplate by the Agent's revision, never by the Substrate release — so the roll of such a release leaves every Agent with a golden the new Substrate restores as an empty
/data, and every session likewise. Upstream's rolling upgrade runbook keeps actor state across a roll and does not apply. There was no procedure.Proposed solution
docs/snapshot-reset.md: what breaks and how it shows in both directions, the reset (hold the Agents' Flux re-creation, delete every Agent, let kagent's session sweep and runtime-revision GC delete sessions, actors, templates and goldens, verify Substrate and the store empty, resume), rollback as the same procedure, and what does not work instead. The ledger row of the snapshot tars points to it.Rehearsed in agentlab between 1.7.0 and 1.8.0-rc.6 on the Go ADK and the claude Harness: forward, a 1.7.0 golden on rc.6 restores an empty
/datawith no restore error (the Go ADK:no such table: app_states; claude:Harness runtime execution failed); backward, an rc.6 snapshot on 1.7.0 crashes the actor (restore-state/durable-dir.tar: no such file or directory). After the reset, both Harnesses' Agents are Ready on fresh goldens within 16 s and a session suspends and restores; a 323-level, 5141-character workspace tree commits, suspends and restores on rc.6.Acceptance criteria
Opened by an agent on behalf of Timo Derstappen.