How it works
A state boundary is a persistence contract. It identifies which parts of an agent run survive a transition and which parts are discarded. The transition might be a tool call, model invocation, session restart, worker handoff, checkpoint, retry, or recovery after failure.
A useful boundary specifies four things:
- State classes. Separate authoritative workflow facts, derived working data, conversational context, credentials, and diagnostic traces.
- Persistence scope. Decide whether each value lasts for one invocation, one run, one session, or across sessions.
- Transfer rules. Define what may cross into a new worker, model context, or recovery attempt, including its provenance and version.
- Invalidation rules. State when data expires, becomes stale, or must be recomputed from an authoritative source.
The harness should serialize only the state required to continue correctly. On recovery, it reconstructs execution from that durable state rather than treating an old transcript as the system of record. Temporary reasoning, cached retrieval results, and tool responses may help within a run, but they should not become durable merely because they are available.
The core design question is not simply where data is stored. It is which information is allowed to influence future action after the conditions that produced it have changed.
Why it matters in an agent harness
Agent systems accumulate state quickly. A model response becomes a plan. A tool result becomes a fact. A partial action becomes evidence of completion. Without explicit boundaries, these different kinds of information collapse into one context stream. The next invocation cannot reliably distinguish an authoritative record from a convenient observation.
That ambiguity weakens recovery. Suppose an agent creates an external resource, times out before recording the result, and then retries. If the durable state contains only an intended action, the harness may repeat the side effect. If it contains a verified operation identifier and outcome, the harness can reconcile before acting. The state boundary determines whether recovery is a controlled continuation or an improvised replay.
Boundaries also contain contamination. A retrieved claim, injected instruction, or mistaken intermediate conclusion should not automatically enter cross-session memory. Promotion into durable state should require a defined write path, provenance, validation, and an appropriate authority level. This makes memory less convenient, but it prevents transient model context from quietly becoming policy or fact.
Observability depends on the same separation. Operators need to know what the system believed, what it attempted, what actually changed, and which record governs the next step. Those are distinct state categories. When they are stored as an undifferentiated transcript, audits become interpretive and rollback becomes uncertain.
A strict state boundary also reduces accidental authority transfer during handoffs. A worker may need a task identifier, approved parameters, and current checkpoint. It usually does not need every prior message, credential, or speculative branch. Passing less state narrows the receiving worker's influence surface and makes its inputs easier to inspect.
The tradeoff is additional schema and lifecycle work. State must be typed, versioned, validated, and migrated. That cost is justified wherever retries, long-running workflows, external side effects, or cross-session memory make implicit persistence dangerous.
State Boundary vs Trust Boundary
A state boundary controls persistence and propagation. A trust boundary controls where data or commands move between parties, components, or authority levels with different security assumptions. They often intersect, but they answer different design questions.
| Boundary | Primary question | Typical control |
|---|---|---|
| State boundary | What survives this transition and may influence later execution? | Schemas, retention scopes, checkpoints, invalidation, provenance |
| Trust boundary | What may cross between differently trusted components? | Validation, authentication, authorization, isolation |
A value can remain inside one trust domain yet still cross a dangerous state boundary, such as when unverified retrieval output is written into durable memory. Conversely, a short-lived tool request may cross a trust boundary without becoming persistent state. Treating the two boundaries separately prevents security checks from standing in for lifecycle controls.
The Rifty take
We treat durable state as a deliberately small control surface, not a transcript archive. We accept the cost of explicit schemas and promotion rules because recovery should begin from verified workflow facts. If a value cannot explain its origin, authority, lifetime, and invalidation condition, it should not steer a later run.
Common failure modes
- Persisting the entire conversation and assuming the next model invocation can identify which statements remain valid.
- Using a transcript, plan, or completion message as authoritative proof that an external side effect occurred.
- Retrying from an old checkpoint without reconciling actions that may have completed after the checkpoint was written.
- Allowing retrieved content or tool output to enter cross-session memory without provenance and validation.
- Passing credentials, unrelated history, or speculative branches through worker handoffs because they already exist in context.
- Mixing intended, attempted, observed, and verified state in one field or status value.
- Omitting schema versions, leaving resumed workers unable to distinguish old state from malformed current state.
- Retaining derived values after their source record changes, without invalidation or recomputation.
- Giving multiple workers unrestricted write access to the same durable record without merge or single-writer rules.
- Recording checkpoints that cannot reconstruct the next safe action or determine whether reconciliation is required.
Frequently asked questions
What state should persist across agent sessions?
Persist only the information required to resume or govern the workflow correctly: authoritative inputs, approved decisions, verified side effects, checkpoint position, and relevant provenance. Temporary reasoning, speculative plans, stale retrievals, and broad transcripts should expire unless a deliberate promotion rule validates and scopes them for later use.
Is a checkpoint the same as a state boundary?
No. A checkpoint is a recorded recovery position, while a state boundary defines what information may survive into that checkpoint and later execution. A checkpoint can still be unsafe or incomplete if it preserves stale context, omits verified side effects, or cannot distinguish intended work from completed work.
How should a harness handle state after an unknown tool outcome?
Record the operation as unresolved and reconcile it against an authoritative external source before retrying. Do not mark success without verification or assume failure from a timeout. The state boundary should preserve identifiers and attempt metadata needed to investigate the outcome without carrying unnecessary transient context into recovery.
Should an agent transcript be stored as durable state?
A transcript may be retained as diagnostic evidence, but it should not automatically govern resumed execution. Durable workflow state should be extracted into typed, validated records with clear provenance. Keeping the transcript separately preserves observability while preventing conversational claims, discarded plans, or injected content from becoming authoritative by persistence.