Resume the work, not the mistake

The session stops just after an edit starts. If you already operate coding agents, the dangerous response is automatic replay: you do not yet know whether the write failed, completed, or was persisted without a response.

First, open the file and inspect the durable session record. The missing response tells you what you do not know; it does not tell you the write failed. Recovery is a state-classification problem, not a restart command.

Prerequisites

Use the workbench from lesson 10 and keep docs/workflow.md unchanged for now. The complete ZIP includes the checkpoint and local recovery examples. You can finish the decision exercise without running Harness.

What you will build

You will record enough evidence to continue a session and choose a safe response to three states: a tool never started, a tool's outcome is unknown, or its result is recorded. Conversation history, tool completion, and the current filesystem are separate facts.

Practice: make a checkpoint worth keeping

In your existing read-only workbench session, ask DSH to inspect docs/workflow.md and state its two structural failures. Wait for the response to finish. Fill in checkpoint.md: the workspace, session identifier, preset, configured route, completed inspection, and next safe action. Leave unknown fields explicitly unknown. Do not include credentials.

For an optional persistence check, stop the local Harness server cleanly only after all work is idle. Restart it with the same profile, home, and launch options, then reopen that conversation from the session list. Do not change its storage location or begin a new conversation and call that a resume. UI labels vary across this preview; record the actual steps your version offers.

Ask:

Continue this review without editing. What finding did we already establish?
Read checkpoint.md and inspect docs/workflow.md again.
Distinguish remembered conversation from current file evidence.
Tell me the next safe action and what has not been verified.

Compare the response with the file yourself. If the conversation cannot be reopened, preserve the identifier and current evidence. A new session using that handoff is a recovery route, but it is not proof of durable-session restoration.

The SDK documents durable conversations addressed by session ID; repeated harness.run(..., session_id="docs-lab-01") calls can continue one. That API does not make a filesystem write reversible. A resumed session also retains its recorded preset composition rather than silently switching to your new default. Preset lifecycle.

Open full-size diagram

Break and recover

Run the local exercise:

node recovery.mjs
node --test recovery.test.mjs

The demo prints three course checkpoint records. The tests cover all 18 combinations in its deliberately small decision table. These are authored teaching records, not imported Harness events or a test of its persistence engine.

For each record, answer before reading the printed action:

1. A write was requested but never started. Is its scope still valid? Recheck before making a new call.
2. A write started, but no result was recorded. Inspect the target before deciding anything.
3. That inspection finds the intended change already present. Verify the existing change rather than repeating it.

In the upstream repair implementation, an unmatched tool request can become TOOL_NOT_STARTED; a started call without a durable result can become TOOL_OUTCOME_UNKNOWN. The distinction depends on the event history. A live interruption does not guarantee one particular error, and neither error is a filesystem rollback.

To practice the uncertain-write case without killing a live process, imagine the reference repair has already landed. Inspect reference/docs/workflow.md, then write down the check you would run before accepting it. Use node check-docs.mjs --reference to test that answer. It should exit 0, but you still need to read the command and recovery advice.

Make it yours

Add one project-specific field to your checkpoint: a migration ID, a browser reproduction, or a generated file's expected location. Keep the record small enough to update after a meaningful step. For operations outside a local file, inspection must happen in the actual affected system before a retry; this toy decision aid cannot verify that state.

Completion check

• You distinguish a reopened conversation from a fresh session with a handoff.
• You recorded which continuity check actually ran and which did not.
• You can explain not-started, outcome-unknown, and completed work.
• You inspect and verify an uncertain write before asking to repeat it.
• Another reader can identify the next safe action from your checkpoint.

Write the recovery state machine

Use explicit states for the operation you are recovering:

planned -> requested -> started -> completed
                         |             |
                         v             v
                      failed        verified
                         |
                     unknown

The unknown state is intentionally separate from failed. A failed operation has an observed error. An unknown operation may have written a file, sent a request, or changed a process before its result disappeared. The next action for unknown is inspection and reconciliation. It is not an automatic retry.

Give every mutating request an idempotency key and a checkpoint that names the intended target, expected precondition, and postcondition. On recovery, read the target and compare it with those conditions. If the postcondition already holds, record “already applied” and move to verification. If the precondition still holds, a retry may be safe. If neither holds, stop for a person to resolve the divergence.

The checkpoint should also name the last safe read, the active workspace revision, the policy in force, and the next action that requires approval. A session transcript can explain intent, but a checkpoint should let another operator make a safe decision without reading every turn. Test the worksheet with a simulated lost result and with a result that arrives after the operator has started recovery.

Next, build a useful tool that exposes a small, testable document check to the agent.