Persist state and hand off cleanly: survive a fresh context: Practical Field Guide

On this page

01Working definition
02Field situation
03Worked example
04Build it, with checkpoints
05Operating context
06Hands-on lab
07Failure clinic
08Production boundary
09Sources and claim limits

Learning objectives

Distinguish durable task state from conversation context, summaries, and informal progress notes
Model pending, in-progress, blocked, implemented, and verified as evidence-backed states
Design a startup and shutdown handoff that aligns state files with Git and environment health
Recover after context reset or crash without duplicating effects or starting unrelated work

Before you start

• The locked task contract, repository map, and verified initializer from Modules 01 through 03
• A Git branch with fixture-only work and permission to interrupt the session during the lab

Working definition

Durable state and handoff

Durable work state is the versioned record of task scope, status, evidence, blockers, decisions, and next action that survives context reset, process failure, and handoff. A conversation summary may help orientation, but it cannot be the authority for completed behavior. State changes require evidence and must stay consistent with Git history and the current environment.

Long-running coding work crosses context windows and human schedules. Without an external ledger, a fresh session guesses what happened, repeats setup, continues half-finished code, or sees a polished interface and declares the whole task complete. Compaction reduces token pressure but can omit the exact constraint or failed check needed next.

A feature ledger and handoff ritual reduce reconstruction. The session begins by verifying the environment, reading recent commits, loading active state, and choosing the highest-priority eligible item. It ends by running checks, committing a coherent change, saving evidence, and naming one next action or blocker.

Field situation

Mid-feature context reset

The session reset, ledger, and incomplete branch are deterministic Release Desk fixtures.

Owner: A second coding-agent session taking over after the first context ends during request-change persistence work.
Decision: What is the current authoritative state, and what single action should the fresh session perform next?
Starting state: The API branch exists and unit tests pass. Browser persistence has not run, the branch contains one uncommitted schema change, and the chat summary says most of the feature is done without naming the failed retry case.
Expected outcome: The new session identifies incomplete persistence and retry evidence, restores a coherent branch, and continues without duplicating the audit effect.

Constraints

• The new session may read repository artifacts and Git but may not receive the old transcript or private human memory
• No new feature starts until health, ledger, branch cleanliness, and incomplete acceptance are reconciled
• Verified status requires the contract's full named pipeline and evidence receipt

Worked example

A summary said done; the ledger said implemented

Evidence status: Named synthetic scenario

The first agent's summary emphasized completed API logic and passing unit tests. The feature ledger remained implemented because browser refresh and retry-after-timeout were pending. Git also showed an uncommitted migration not mentioned in the summary.

The takeover ritual trusted the ledger and Git over the summary. It ran health, preserved the migration diff, linked it to the active feature, executed the missing fixtures, and found duplicate audit insertion after an unknown outcome. The session repaired that path before marking verified.

A final handoff stored the commit, six acceptance receipts, one known limitation, and the next unrelated task. A third fresh session could explain the feature status and evidence without opening the previous chats.

Limits

File-based state works for the course repository. Distributed production systems may need transactional state, leases, event logs, and stronger concurrency controls.

Method

Build it, with checkpoints

Field situation

What is the current authoritative state, and what single action should the fresh session perform next?

01Define guarded transitions
02Start from a verified ritual
03Interrupt at a known checkpoint

Acceptance checks

A session with no transcript can reconstruct current work, preserve an incomplete branch, continue the right case, and leave evidence another session can audit.

Why this visualA guarded state machine makes the difference between implemented, blocked, and verified visible and ties each transition to evidence.

01
Define guarded transitions
Model pending, in-progress, blocked, implemented, and verified. For each transition, specify required contract version, branch condition, check evidence, actor, and reason. Prevent direct jumps from pending to verified.
CHECKPOINT · The schema rejects verified without the full evidence set and rejects unknown transition paths.
02
Start from a verified ritual
Run the initializer, read recent Git history, load the active contract and ledger, compare branch state, then choose one eligible item. Record the session ID and starting evidence before implementation.
CHECKPOINT · The active item, starting commit, environment receipt, and intended next transition agree.
03
Interrupt at a known checkpoint
Stop after a partial implementation and preserve the dirty or committed state honestly. Record completed checks, failed checks, open files, decisions, blocker, and one next action. Do not label the feature verified.
CHECKPOINT · The handoff explains incomplete work without relying on the old conversation or hiding branch state.
04
Resume cold and reconcile
Open the fresh session, follow the startup ritual, and compare its interpretation with the saved state. Complete the missing acceptance path, update state only through valid transitions, and leave a clean commit plus final receipt.
CHECKPOINT · The fresh session selects the correct next action, repeats no completed effect, and reaches verified through named evidence.

Operating context

Beyond the demo

Make verified a guarded state

Keep implementation and verification separate. A feature can be implemented with a commit while still failing browser acceptance or a retry fixture. Only the named verification pipeline may move it to verified. Each transition stores from, to, reason, actor, timestamp, contract version, commit, and evidence IDs.

Blocked is a useful state when it names the missing authority or external condition. It should not become a parking label for uncertainty. Record what was attempted, the last healthy checkpoint, the exact question, who can resolve it, and which work remains safe while waiting.

Align handoff with repository truth

At session start, compare the ledger with Git and the health receipt. If the ledger says verified but the commit is absent, or the branch is dirty from an undocumented change, stop and reconcile before starting a new feature. At session end, leave either a clean committed state or an explicit incomplete record with preserved evidence.

Do not turn the progress log into a transcript. Save decisions, tests, failures, and next action. Raw conversation is noisy and can contain stale hypotheses. A new session needs the current contract and evidence, plus enough history to avoid repeating a known failure.

Hands-on lab

Interrupt a session and resume from repository state

Create the feature ledger and handoff files, begin a bounded implementation, interrupt after the third checkpoint, then start a fresh session with no transcript. Measure orientation time, wrong assumptions, repeated work, and evidence recovery.

Prepare

• Commit the initializer and task contract, then confirm the baseline environment is healthy
• Prepare a separate fresh session that receives only the repository path and the standard startup instruction

Deliverable

A machine-readable feature ledger, concise progress log, clean handoff record, interrupted-run evidence, and a fresh-session resume receipt.

Starter kit: Feature ledger

JSON

{
  "contractVersion": "1.0.0",
  "features": [{
    "id": "RD-REQUEST-CHANGES",
    "status": "pending",
    "eligibleNext": true,
    "commit": null,
    "evidence": [],
    "blocker": null,
    "nextAction": "implement authorized transition"
  }]
}

Downloadable artifacts

Feature ledger

feature-list.json · JSON

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-04-receipt.json · JSON

A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.

Acceptance command

npm run harness:handoff -- --ledger .harness/feature-list.json --fresh-session

Expected receipt

PASS he-04 fresh-session-handoff
transcriptShared=false repeatedEffects=0
state=verified git=clean evidence=complete

Expected result

A session with no transcript can reconstruct current work, preserve an incomplete branch, continue the right case, and leave evidence another session can audit.

Carry forward

The feature ledger becomes the state input for tool feedback, mechanical enforcement, verification, recovery, and the later work graph. Keep all transitions linked to contract and evidence IDs.

Acceptance checks

01State transitions are explicit and verified cannot be reached without the required evidence set
02Startup reconciles contract, ledger, Git, branch cleanliness, environment health, and priority
03Interrupted work records exact progress, failures, blocker ownership, and one safe next action
04Fresh resume uses no old transcript, repeats no completed side effect, and produces a clean final handoff

What breaks

Failure clinic

F1A fresh session starts a new feature while the branch contains undocumented broken work.

Inspect: Compare Git status, recent commits, health result, ledger state, progress log, and eligible-next calculation.
Likely cause: Startup trusted a summary or priority list without reconciling repository state.
Repair: Stop new work, preserve the diff, attach it to the active item, and restore a healthy coherent checkpoint.
Prevent next time: Make Git, health, and ledger reconciliation a required startup gate.

F2Features move to verified after a unit command while browser or retry checks remain absent.

Inspect: Inspect transition evidence requirements and the stored receipt IDs for that feature version.
Likely cause: Implemented and verified collapsed into one status controlled by agent confidence.
Repair: Restore implemented, run the missing pipeline, and allow only the verifier to create verified.
Prevent next time: Enforce transition guards in schema validation and CI.

F3The progress file grows into a long transcript that a new session cannot use.

Inspect: Separate decisions, state changes, evidence, blockers, and next action from raw dialogue and abandoned hypotheses.
Likely cause: The team persisted conversation volume instead of current task truth.
Repair: Rewrite the handoff around state and evidence, preserving only history needed to avoid repeated failure.
Prevent next time: Limit the handoff schema to operational fields and archive optional narrative elsewhere.

Beyond the demo

Production boundary

01Durable state survives context reset and has a stronger authority than a conversation summary
02Pending, in-progress, blocked, implemented, and verified have valid guarded transitions
03Every state change records actor, reason, contract, commit, timestamp, and evidence identifiers
04Startup reconciles state with Git, environment health, branch cleanliness, and current priority
05Blocked state names the exact missing condition, resolution owner, last checkpoint, and safe next work
06Session shutdown leaves a clean commit or an explicit incomplete state that another session can recover

Evidence status

Sources and claim limits

Sources support the named claims; they do not guarantee the same result in another system.

[1]
Effective harnesses for long-running agents
Anthropic · Published research · 2026-08-26
initializer pattern · feature ledger · session handoff · end-to-end verification
[2]
Harness engineering: leveraging Codex in an agent-first world
OpenAI · Public case · 2026-08-26
repository knowledge · agent legibility · mechanical enforcement · entropy management
[3]
Learn Harness Engineering
Walking Labs · Public case · 2026-08-26
project-based sequence · five harness subsystems · loop engineering · graph engineering
[4]
Harness Engineering Guide
Nexu · Public case · 2026-08-26
runtime boundary · tool systems · sandboxing · recovery patterns
[5]
Harness Engineering learning guide
deusyu · Public case · 2026-08-26
repository as record · mechanical rules · agent readability · continuous cleanup