Planarian: Managing Agent State with Statepoints

1 Introduction

• Reconstructing state after failure can require costly or impossible tool calls, while users may need to reverse unwanted local or remote changes.Explicit state management also supports trying alternative actions without repeating successful work or carrying unwanted effects forward.Source: §1 · p. 1
• Safe state management must coordinate local and remote state, integrate with tool dispatch and agent context, and keep repeated snapshots and restores efficient.Restoring environment state without updating tool-call context can mislead an agent, while discarding history loses evidence of unsuccessful actions.Source: §1 · p. 1
• Planarian’s statepoints capture local files and processes with remote state changed through MCP, and its snapshot, rollback, and fork primitives support recovery and alternative execution.Statepoints remain restorable even when remote services cannot checkpoint, and carry descriptions and prior execution outcomes.Source: §1 · p. 2
• 15× the No-snapshot score in Mario, 10× faster snapshots, and 1%–3% completion-time overhead show improved task quality with little state-management overhead.The overhead applies across system and database administration tasks; the snapshot comparison is against full process and filesystem checkpoints.Source: §1 · p. 2
• Incremental copy-on-write filesystem snapshots and CRIU process checkpoints reduce local recopying, while MCP proxies record compensating actions to reverse remote changes.Planarian re-establishes restored checkpoints as baselines for later memory changes; a database proxy can retain original row values and affected keys.Source: §1 · p. 2

2.1 Agent execution

• Harnesses coordinate LLM and tool calls in an agent loop, while the resulting environment state includes local files and processes as well as external service state.Tools can access remote services through MCP; local execution may be confined to a sandbox.Source: §2.1 · pp. 2–3

2.2 Managing environment state

• Exploration and safety require branching plans without interference and rolling back unintended side effects, with recovery and exploration available to users, harnesses, and agents.State management must coordinate local and remote state with agent context and avoid degrading execution performance.Source: §2.2 · p. 3

2.3 Existing state management approaches

• Framework checkpoints preserve workflow progress but do not restore complete environment state, while sandbox checkpoints cover local files and processes but exclude remote service state.Consequently, restoring local files alone can leave them inconsistent with remote database updates.Source: §2.3 · pp. 3–4
• Workflow-recovery approaches handle some tool effects but exclude running process state, and compensation depends on suitable undo operations and retained recovery information.The compared prior approaches do not achieve all four dimensions; Planarian combines local and remote restoration, context consistency, and shared primitives for users, harnesses, and agents.Source: §2.3 · p. 4

3.1 Concept

• A statepoint groups local and remote state into one consistent, restorable point-in-time version of the agent’s environment, with evidence describing it.Local state covers sandbox files and processes; remote state covers supported service operations, without requiring a service checkpoint.Source: §3.1 · p. 4
• State evidence records a state description and outcomes of executions from that statepoint, helping callers choose a restore point without erasing unsuccessful-attempt knowledge.The evidence is metadata separate from the captured environment and agent context; adding it does not change the recorded environment version.Source: §3.1 · p. 5

3.2 Primitives

• Snapshot captures local and remote state at a chosen boundary between tool calls, and rollback restores a previously captured statepoint across both state domains.A snapshot need not follow every tool call; rollback preserves earlier state while undoing later changes.Source: §3.2 · p. 5
• Fork creates an isolated branch from a captured statepoint while preserving the source branch, but remote isolation requires the service to support independent branches.State evidence describes the common starting point and prior attempts to help callers choose alternative actions.Source: §3.2 · p. 5

4 Planarian Design

• The design organizes state management around a runtime that realizes the paper’s statepoint abstraction and primitives.The design section describes the overall runtime before detailing local, remote, consistency, and context-management components.Source: §4 · p. 5

4.1 Overview

• Snapshot records a statepoint, rollback restores its sandbox and remote state, and local fork creates another sandbox from the statepoint’s local state.The sandbox handle identifies the local execution environment; the statepoint has local and remote parts, with capture and compensate hooks connecting remote recovery to sandbox operations.Source: §4.1 · pp. 5–6

4.2 Local state management

• Local tool calls must run in a sandbox, and callers choose snapshot frequency, including after each call or after several calls.Podman-based sandboxes combine incremental process checkpointing with zero-copy filesystem snapshots; snapshot and fork can overlap LLM inference.Source: §4.2 · p. 6

4.3 Remote state management

• For remote services without native versioning, the state proxy records compensating actions for supported mutations and rejects requests it cannot make compensable.On rollback, it identifies calls after the saved position and applies their compensating actions in reverse order.Source: §4.3 · p. 6

4.4 State consistency

• The statepoint manager freezes the sandbox while capturing local state and the remote-call position, then resumes it; rollback compensates remote changes and restores the local snapshot.A snapshot waits for in-flight commands and MCP calls to finish and blocks new calls until capture completes.Source: §4.4 · p. 6
• A local fork preserves the original sandbox, but extending a branch to remote state requires service-side branching; compensation-only services prevent the fork from using the state proxy.Source: §4.4 · p. 6

4.5 Agent context management

• The context library records state descriptions and subsequent execution outcomes so users, harnesses, and agents can choose a rollback point and receive restore context.The harness adds the selected state’s description and prior outcomes after rollback, without removing existing context.Source: §4.5 · pp. 6–7

5 Local state management

• Planarian combines Podman sandboxing, CRIU process checkpoints, and ZFS filesystem snapshots, with a protocol that keeps CRIU checkpoints incremental across restores.The runtime is harness-agnostic and routes tool calls through Planarian APIs.Source: §5 · p. 7

5.1 Sandbox management

• Podman provides the sandbox boundary for local state, isolating agent commands and managing the container’s ZFS-backed root filesystem.The sandbox manager uses Podman’s isolation primitives so untrusted or erroneous commands cannot escape the sandbox.Source: §5.1 · p. 7

5.2 Sandbox snapshot and the local state

• A local statepoint combines a CRIU checkpoint of the container’s process tree with a zero-copy ZFS snapshot of its root filesystem.Together, these artifacts restore the sandbox’s processes and files to the captured state.Source: §5.2 · p. 7

5.3 Continuous incremental checkpointing

• CRIU’s first checkpoint after a restore must be full, making frequent snapshot-and-restore workloads costly.After restore, changed-address-space soft-dirty tracking is lost, and CRIU’s checkpoint-creation-time safeguard also prevents incremental checkpoints.Source: §5.3 · p. 7
• Planarian enables incremental CRIU checkpointing across restores without changing CRIU or the kernel by clearing restored processes’ soft-dirty bits and adjusting the parent checkpoint time.For a fork, it writes a per-sandbox copy of the restored image rather than modifying a shared image in place.Source: §5.3 · p. 8

6 Remote state management and consistency

• Planarian manages heterogeneous local and remote state through statepoints and supports asynchronous snapshot and fork operations that can hide overhead under LLM latency.Source: §6 · p. 8

6.1 Remote state proxy

• The state proxy makes supported remote operations compensable, recording the information needed to undo them; its SQL prototype captures pre-image data and affected-row keys in an atomic transaction.Requests that cannot be compensated are rejected before execution, and successful compensations are logged for reverse-order application.Source: §6.1 · pp. 8–9

6.2 Statepoint manager and registry

• The statepoint manager freezes container processes while capturing the process checkpoint, filesystem snapshot, and remote state, and commits a statepoint only when all captures succeed.For services that cannot be quiesced, snapshots occur between tool calls; consistency across the sandbox and services assumes tenant isolation of agent-readable and agent-mutable state.Source: §6.2 · p. 9

6.3 Orchestrating snapshot and execution

• Snapshot and rollback take an exclusive sandbox lock, while fork uses a shared source lock and an exclusive fork lock, allowing snapshot and fork to overlap LLM inference.Forking is restricted when remote state supports compensation but not branching: the forked sandbox cannot use the state proxy.Source: §6.3 · p. 9, §6.2 · p. 9

7.2 Agentic exploration with state management

• 15×, 1.4×, and 1.4× the No-snapshot scores in Mario, Flappy Bird, and Minecraft, respectively, were achieved within 100 steps with Planarian.The agent rolled back from bad states and explored alternatives; the evaluation used selected difficulty levels for progress within each game's step limit.Source: Figure 6 · p. 10, Figure 7 · p. 10, §7.2 · p. 10

7.1 Experimental setup

• The evaluation integrates Planarian with coding, personal-assistant, exploration, and gaming agents and tests four workloads: DevOps-Gym, Terminal-Bench, Bird-interact-lite, and GameWorld.Baselines were No-snapshot and Full-snapshot; workloads include 704 DevOps tasks, 89 Terminal-Bench tasks, 300 database tasks, and 34 games.Source: §7.1 · p. 10

7.2 Agentic exploration with state management

• 10× snapshot overhead and 2× fork overhead made Full-snapshot 9% slower end-to-end than Planarian on nine Terminal-Bench system-administration tasks.The end-to-end gap was smaller than the primitive gap because long LLM calls hid much of Full-snapshot's overhead.Source: Figure 8 · p. 10, §7.2 · p. 11

7.3 Safe execution with state management

• 1% overhead over No-snapshot, versus 20% for Full-snapshot, was measured for Terminal-Bench rollback; Planarian reduced raw snapshot/rollback times by 89%.Most tasks were not filesystem-heavy, so copy-on-write added no significant overhead.Source: Figure 9 · p. 11, §7.3 · p. 11
• Less than 3% extra task-completion time versus No-snapshot was measured on 16 DevOps-Gym build/configuration tasks, while Full-snapshot added 59%.Full-snapshot sandbox snapshot/rollback time was about 24× Planarian's, making it harder to hide behind LLM inference.Source: Figure 10 · p. 11, §7.3 · p. 12

7.4 Overhead of consistent state management

• 3% end-to-end overhead was measured while consistently snapshotting and rolling back sandbox and PostgreSQL state across 50 Bird-interact-lite tasks.Planarian took 1.3× the MCP round-trip time of No-snapshot; request amplification added less than 0.3% to end-to-end time.Source: Figure 11 · p. 11, §7.4 · p. 12

7.5 State management primitives

• 74× and 231× snapshot speedups over Full-snapshot were measured for 8 GB memory and filesystem workloads, respectively; post-rollback memory snapshots were 11× faster than CRIU-inc.Planarian's continuous incremental checkpoint protocol continues incremental capture after restore.Source: Figure 12 · p. 11, §7.5 · p. 12
• On 8 GB workloads, rollback was 4× faster for memory and 67× for filesystem state, while fork was 4× and 61× faster, respectively, than Full-snapshot.Filesystem restoration was faster than memory restoration because reconstructing a large process is costly.Source: Figure 13 · p. 11, Figure 14 · p. 11, §7.5 · p. 12

• AgentFS checkpoints and ports filesystem state only, while Daytona, E2B, and Agent Sandbox focus on sandbox state rather than remote state.Planarian targets local deployment and can integrate with Agent Sandbox for recoverable remotely deployed sandboxes.Source: §8 · p. 12
• Dolt and Neon branch database state, and their services can integrate with Planarian hooks for consistent rollback and branching across local and remote state.SWE-search explores Git-based software tasks; Planarian extends tree search to arbitrary terminal tasks, and can integrate with ExACT for GUI backtracking.Source: §8 · p. 12
• CRIU checkpoints process trees and ZFS provides block-level copy-on-write snapshots; Planarian uses them for process and filesystem checkpointing, respectively.DMTCP, Btrfs, and dm-snapshot are also described as alternatives for process or persistent-state snapshots.Source: §8 · p. 13

• Planarian manages local and remote state through consistent, restorable statepoints and provides snapshot, rollback, and fork for recovery and exploration.A context library keeps agents informed of restored state and past outcomes; the evaluation reports improved task quality and little recovery overhead.Source: §9 · p. 13