Glossary
60 terms from “State Management and Persistence: Making Long Tasks Survive Interruption.” Hover the first occurrence in the lesson for its definition.
| Term | Definition | Source |
|---|---|---|
| memory | The context you feed the model — answers "what has the model seen?" Can be persisted to disk (like NOTES.md) or still in process memory. | How we built our multi-agent research system — Anthropic Engineering |
| execution state | The running scene the harness process is holding — messages array, turn counters, tokensUsed, the tool call not yet recorded. Lives in process memory by default and is lost when the process exits. | How we built our multi-agent research system — Anthropic Engineering |
| messages | The full conversation history array the harness holds in memory; the only source for restoring context to the model and the largest field in the checkpoint. | How we built our multi-agent research system — Anthropic Engineering |
| turns | Counter tracking how many turns have run, used to judge stopping conditions like maximum-turn caps; must continue from checkpoint value on resume, not restart at zero. | How we built our multi-agent research system — Anthropic Engineering |
| tokensUsed | Cumulative token usage counter; on resume must be carried forward from the checkpoint to support context compaction threshold decisions. | How we built our multi-agent research system — Anthropic Engineering |
| pendingToolUse | Checkpoint field marking a dangling tool call (model named it, result not yet recorded); null or an object like {id, name, input}. | How we built our multi-agent research system — Anthropic Engineering |
| dangling call | A tool_use block the model named but whose result hasn't been pushed back into messages when the process crashes, leaving no paired tool_result. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint | Serializing execution state (messages, turns, tokensUsed, pendingToolUse) to disk so the process can resume after a crash; one of the deterministic safeguards paired with model adaptability. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint.json | The checkpoint file holding version, task, turns, tokensUsed, messages, pendingToolUse — a complete snapshot of the execution scene. | How we built our multi-agent research system — Anthropic Engineering |
| version | Protocol version number in checkpoint.json; lets loadCheckpoint confirm format compatibility and refuse to load mismatched versions. | How we built our multi-agent research system — Anthropic Engineering |
| task | Original user task string stored in checkpoint.json so the restarted harness knows which task this scene belongs to and can report progress. | How we built our multi-agent research system — Anthropic Engineering |
| saveCheckpoint | Function writing current state to disk; correct implementations write to a temp file first, then atomically rename, avoiding half-written corruption. | How we built our multi-agent research system — Anthropic Engineering |
| save point A | First checkpoint within a turn, saved after the model names a tool but before it executes; records pendingToolUse with this turn's tool_use block. | How we built our multi-agent research system — Anthropic Engineering |
| save point B | Second checkpoint within a turn, saved after tool results are pushed into messages; clears pendingToolUse back to null. | How we built our multi-agent research system — Anthropic Engineering |
| temp file | Intermediate file (e.g., checkpoint.json.tmp) written first during atomic checkpoint writes; fully written before being renamed to replace the real file. | How we built our multi-agent research system — Anthropic Engineering |
| fs.renameSync | Atomic rename operation on the same filesystem; directory entry either points fully to the new file or stays at the old one, with no half-renamed intermediate state. | How we built our multi-agent research system — Anthropic Engineering |
| overwrite in place | Directly overwriting the checkpoint file with fs.writeFileSync; not atomic, can leave truncated JSON if the process is killed mid-write. | How we built our multi-agent research system — Anthropic Engineering |
| resume | Restarting the loop from a checkpoint after a crash, reading state back, rebuilding messages, and continuing from where the error occurred instead of restarting from turn 1. | How we built our multi-agent research system — Anthropic Engineering |
| loadCheckpoint | Function reading and parsing the checkpoint file; should validate version field and throw loudly on version mismatch or parse failure, not silently fall back to empty state. | How we built our multi-agent research system — Anthropic Engineering |
| reconcile | Function handling a dangling pendingToolUse on resume; decides by tool nature (read-only vs. high-impact) and ledger state whether to re-run, reuse, or return is_error. | Handle tool calls — Claude API |
| READ_ONLY_TOOLS | Set of tool names (read_file, grep, list_dir, web_search) judged side-effect-free; reconcile safely re-runs tools in this set on resume. | Handle tool calls — Claude API |
| read-only tool | Tool with zero side effects (e.g., reading files, searching); safe to re-run multiple times as the external world remains unchanged. | Handle tool calls — Claude API |
| high-impact tool | Tool that changes external state (send_email, create_ticket, delete_file); must confirm execution before re-running to avoid duplicate side effects. | Handle tool calls — Claude API |
| is_error | Optional tool_result field set to true to indicate tool execution failed or status is unknown, letting the model know and adapt instead of assuming success. | Handle tool calls — Claude API |
| tool_result | Content block returned to the model for each tool_use; protocol requires every tool_use have a paired tool_result, matched by tool_use_id, all in the next user message. | Handle tool calls — Claude API |
| tool_use | Content block in a model response naming a tool to call; contains id, name, input fields. A dangling tool_use has no paired tool_result when the process crashes. | Handle tool calls — Claude API |
| idempotent | An operation producing the same final effect whether run once or many times; judgment is based on effect (final external state), not return value. | How we built our multi-agent research system — Anthropic Engineering |
| effects ledger | Separate disk record keyed by tool_use_id tracking which side effects actually happened, written the instant a tool succeeds, enabling resume to distinguish "ran" from "didn't run." | How we built our multi-agent research system — Anthropic Engineering |
| effects.json | Effects ledger file, keyed by tool_use_id, recording tool name, result, and timestamp; written immediately on tool success, before save point B. | How we built our multi-agent research system — Anthropic Engineering |
| tool_use_id | Unique identifier the model assigns to each tool_use block; doesn't change on replay, making it a natural idempotency key for the effects ledger. | Handle tool calls — Claude API |
| at-least-once | Execution semantics inherent to checkpoint-based resume: a tool may finish but the result not be recorded before a crash, making it impossible to distinguish "didn't run" from "ran but not recorded." | How we built our multi-agent research system — Anthropic Engineering |
| loadEffects | Function reading the effects ledger; returns an empty object on missing or parse-failed files, treating it as "no records yet" rather than blocking resume. | How we built our multi-agent research system — Anthropic Engineering |
| saveEffect | Function writing the effects ledger back to disk using temp-file-then-rename atomic write; must be called only after tool execution succeeds with a real result. | How we built our multi-agent research system — Anthropic Engineering |
| approval gate | Pre-execution check for high-impact tools requiring human confirmation; asks "should this be done?" (distinct from effects ledger's "did this already happen?"). | How we built our multi-agent research system — Anthropic Engineering |
| ensureTicket | Example of redesigning "create" as "ensure exists": checks by title, returns existing if found, creates only if missing; idempotent by design. | How we built our multi-agent research system — Anthropic Engineering |
| append | Cumulative write style (e.g., array.push, log file append); each call genuinely adds one more item, making the final state vary with call count — typically not idempotent. | How we built our multi-agent research system — Anthropic Engineering |
| overwrite | Replacement write style (e.g., setting a line to a fixed value, whole-file write_file); calling once or ten times leaves the same end state — usually idempotent. | How we built our multi-agent research system — Anthropic Engineering |
| runToolUses | Function executing all tool_use blocks in a turn; after integrating effects ledger and approval gate, order becomes: check ledger, then approval, then execute, then record ledger. | How we built our multi-agent research system — Anthropic Engineering |
| rewind | Rolling the decision scene back to an earlier turn to retry when the task went off course (not a crash); rolls back the checkpoint, not external side effects already committed. | Checkpointing — Claude Code Docs |
| fork | Copying two independent timelines off the same checkpoint to explore different routes; each timeline gets its own checkpoint sequence and blank effects ledger. | Checkpointing — Claude Code Docs |
| rewindTo | Function retrieving a specific turn's checkpoint from the per-turn retained sequence; defaults to the last save point written in that turn. | Checkpointing — Claude Code Docs |
| forkFrom | Function copying an independent timeline from a specific turn's checkpoint; new timeline brings its own checkpoint sequence and a blank effects ledger, isolated from the main line. | Checkpointing — Claude Code Docs |
| turn-014-A.json | Per-turn checkpoint sequence naming example, embedding turn number and save point letter in the filename for precise turn and moment identification. | Checkpointing — Claude Code Docs |
| pickLatestPoint | Function finding the last-written save point within a turn; relies on A/B lexicographic sort naturally aligning with "before tool → after result" time order. | Checkpointing — Claude Code Docs |
| decision scene | What checkpoints actually rewind: messages, turns, pendingToolUse and other fields defined into the snapshot — not external-world actions already committed. | Checkpointing — Claude Code Docs |
| dry-run mode | Mode during fork where external actions aren't actually executed, preventing both timelines from triggering the same high-impact tool and causing doubled side effects. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint sequence | Per-turn retained series of checkpoint files rather than overwriting to keep only the latest; prerequisite for rewind and fork; forked timelines each carry their own independent copy. | Checkpointing — Claude Code Docs |
| Git | Version control system managing code's permanent, collaborative history; distinct from checkpoints (minute-scale session recovery) and effects ledger (external side effects record). | Checkpointing — Claude Code Docs |
| CRASH_AFTER | Environment variable controlling simulated crash timing (e.g., CRASH_AFTER=after-effect-write:3 triggers crash after the 3rd ledger write). | How we built our multi-agent research system — Anthropic Engineering |
| SimulatedCrash | Dedicated exception type for simulating process kill; main() catches only this, prints a log, and exits with code 137, making demos read like real kills rather than stack traces. | How we built our multi-agent research system — Anthropic Engineering |
| crashPoint | Environment-variable-controlled simulated crash trigger function; compares current operation label against CRASH_AFTER, throwing SimulatedCrash on match. | How we built our multi-agent research system — Anthropic Engineering |
| --resume | Command-line flag indicating this startup should loadCheckpoint and take the recovery path instead of fresh-starting; without it, main() explicitly cleans old checkpoint/ledger files. | How we built our multi-agent research system — Anthropic Engineering |
| response queue | Verification stub replacing the real model client, returning pre-written responses in fixed order to make task execution deterministic and crash timing reproducible. | How we built our multi-agent research system — Anthropic Engineering |
| makeStubClient | Factory function constructing a stub model client from a response queue, used in verification to replace real client.messages.create calls. | How we built our multi-agent research system — Anthropic Engineering |
| main() | Program entry function making a single judgment: whether --resume is present, then routing to recovery or clean-start paths, and uniformly catching SimulatedCrash to print and exit. | How we built our multi-agent research system — Anthropic Engineering |
| three-way split | reconcile's three branches for dangling calls: ledger hit (reuse), ledger miss + read-only (re-run), ledger miss + side effects (is_error to model). | Handle tool calls — Claude API |
| execute first, record after | Effects ledger discipline: must obtain the tool's real execution result before writing it to the ledger; reversing this order records "done" for things never run. | How we built our multi-agent research system — Anthropic Engineering |
| 137 | Conventional exit code for process killed by SIGKILL; verification demos use it to make simulated crashes read like real kills instead of exceptions. | How we built our multi-agent research system — Anthropic Engineering |
| Verification Harness | Testing method using fixed response queue plus controlled crash points to pin down nondeterministic elements (model responses, crash timing), enabling line-by-line assertions on recovery behavior. | How we built our multi-agent research system — Anthropic Engineering |
| proportion | Principle that checkpoint machinery should be added only when complexity demonstrably improves outcomes; not every short task needs full checkpointing. | Building Effective AI Agents — Anthropic Engineering |