A Hankweave run takes a program file and a data directory, executes the program as a sequence of sealed agent tasks, and leaves behind outputs plus a complete record of what happened. This page follows one run through that lifecycle: what goes in, what the runtime does while it works, what it leaves on disk, and how a later invocation can resume, roll back, or replay it. Along the way we introduce each concept – hank, codon, rig, sentinel, checkpoint, budget, loop – at the point where the run first needs it, so the terms arrive with a job to do rather than as a glossary.
By the end you will know where to look when a run misbehaves and which reference pages own the details this page only sketches.
What enters a run#
A run begins with a single command. Use the version-pinned package runner so the command does not assume a globally installed binary:
bunx hankweave@0.10.0 hank.json data/
The command passes the hank path (the path to the program file) and the data path to the installed hankweave launcher. Everything else the run needs arrives through the environment.
A hank is the program: its hank array is the immutable sequence of logic, and the array requires at least one item. Before any work starts, the runtime loads and validates it. An invocation with no hank, data, or flags–for example, bunx hankweave@0.10.0–launches the welcome wizard and exits without running a hank.
The data path becomes the run's workspace input. The workspace is agentRoot/, and data enters it as agentRoot/read_only_data_source. By default that path is a symlink (a filesystem link) to the source data. --copy copies the data instead, and a failed symlink falls back to a copy with a warning. The read_only_data_source/ path is presented as input and is always excluded from checkpoint tracking. Authentication credentials travel separately: they are passed through the process environment, not through the linked data directory.
Self-test behavior belongs to authentication and models, but one failure mode is worth seeing here because it stops the run before anything else happens. When authentication is missing, startup reports:
[<ts>] [ERROR] Self-test completed: FAILED
[<ts>] [ERROR] Self-test FAILED: Some checks failed
[<ts>] [ERROR] - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY)
[ERROR] Server startup failed!
Error message: Self-test failed for 1 model(s):
- Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
• authentication: No authentication found (set ANTHROPIC_API_KEY)
The run never reaches execution in this case: the self-test failure aborts startup and names the missing credential, which is why the error surfaces before any agent session exists.
What happens while it runs#
Once the inputs validate, the run needs somewhere to work and a way to keep its tasks isolated from one another. Execution directories, sealed sessions, and checkpoints provide both: they give us places to inspect the work and return to it. If a codon – one sealed agent task – fails, we can investigate that bounded task using the run's receipts and saved state rather than starting with one agent's entire conversation.
A run first creates an execution directory under ~/.hankweave-executions/. Its name is <timestamp>-<random>-<dataHash6>, and Hankweave prints the directory as it creates it:
Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
Source → data
Exec → ~/.hankweave-executions/<exec-id>
SDKs → Claude node_modules ✓
That directory contains agentRoot/, rigArchive/, and .hankweave/. The last holds state, the event journal, logs, and checkpoints. Startup initializes these pieces in order: the git checkpoint system, the state manager at .hankweave/state.json, the event journal at .hankweave/events/, the sentinel manager, then the lock file (.hankweave/runtime.lock), and finally a WebSocket server on an automatically selected port.
With the directory in place, the hank's sequence begins. A codon is one sealed agent task in that sequence, and codons run in order: the sequence is the execution plan. By default, each codon starts a fresh, sealed agent session (continuationMode: "fresh"); nothing the agent remembers survives that session unless it writes the memory to files. On failure, a codon retries or aborts according to its policy.
Before the agent session starts, a rig (a setup operation) must complete its rigSetup operation successfully; the rig executes first.
Codons do not run unobserved. A sentinel is a parallel observation agent. A sentinel observes the journaled event stream beside the codon and fires reports. Sentinel events are not routed back to sentinels, so they cannot observe themselves in a loop. When the agent finishes, completing-sentinels drains pending sentinel work before the codon closes. To choose where a report lands, see sentinel config and the two-line output-path rule in sentinels.
At each boundary, the run records its state. A checkpoint is sealed state captured at a run boundary. It seals that codon's checkpointedFiles in the dedicated git store at .hankweave/checkpoints/.hankweavecheckpoints, whose git metadata directory is named .hankweavecheckpoints, not .git. Its checkpoint types are start, end, rig-setup, completed, error, and skipped.
Two more mechanisms bound what a codon can do. A configured budget allocates shares. When its cap trips, the agent process stops, and the codon completes or fails according to onExceeded: complete|fail, whose default is complete. The two-party budget rules belong to budgets.
A loop is a repeating plan segment. It iterates lazily: only its first iteration expands up front. After that iteration completes, Hankweave adds the next one; a termination check decides when it terminates.
Throughout all of this, the runtime streams events over the WebSocket. Its journal persists server-state, agentic-backbone, and sentinel events; connection-state events such as server.ready, history.batch, and pong are not journaled. The default interactive mode uses the TUI over that WebSocket; --headless runs without the TUI and autostarts execution.
The figure below gathers the whole lifecycle into one view: inputs enter, execution runs inside the execution directory, outputs and receipts leave, and persisted state supports later entry.
Figure: inputs enter, execution runs inside the execution directory, outputs and receipts leave, and state supports later entry.
Read the diagram as text
WHAT ENTERS WHAT RUNS — ~/.hankweave-executions/<id>/ (the execution directory) WHAT LEAVES
hank.json ───────────────▶ load and validate
data/ ──link─────────────▶ agentRoot/read_only_data_source ──▶ outputs in agentRoot/
keys ──environment────────▶ self-test and codon sessions + optional -o copy
┌──────────────────────────────────────────────┐
│ per codon: rig executes │──▶ receipts:
│ ▶ codon runs — fresh, sealed │ state.json · events.jsonl
│ ▶ checkpoint seals │ server.log · agent logs
│ sentinels observe & fire beside it │ checkpoints (git store)
│ .hankweave/: state·journal·logs·ckpts │
└───────────────────┬──────────────────────────┘
WHAT PERSISTS: resume · rollback · replay
The ASCII figure and its mermaid twin show the same flow. Note the checkpoint seal after each codon run and the .hankweave/ directory collecting state, journal, logs, and checkpoints beside the work – those are the pieces the next two sections rely on.
What a run leaves behind#
When the sequence finishes, two kinds of results remain: the outputs the agent produced and the receipts the runtime kept.
Outputs stay in the execution directory's agentRoot/ unless an output target is configured. There is no default output directory; output-directory mechanics belong to the runbook. With -o/--output <path>, Hankweave copies each codon's outputFiles globs (file patterns) out of the execution directory when that codon completes.
The receipts live on disk alongside the outputs: .hankweave/state.json, the event journal at .hankweave/events/events.jsonl, the server log at .hankweave/logs/server.log, per-run agent logs under .hankweave/runs/<runId>/, and the checkpoint store. One further file, .hankweave/execution-meta.json, records the data and hank hashes, link type, Hankweave version, and host environment for the execution.
A finished headless run has two closing observables: a codon.completed event carrying its cost, then Shutdown: all codons completed (exit code: 0) in the server log. The event excerpt shows the first observable:
{"id": "<id>", "timestamp": "<ts>", "type": "codon.completed", "data": {"codonId": "summarize-notes", "success": true, "cost":"<n>", "duration":"<n>", "exitStatus": {"type": "success"}}}
The success: true field and the recorded cost and duration are what a monitoring client would key on; the matching shutdown line in the server log confirms the run closed cleanly rather than crashing.
What persists between runs#
The receipts above are not just records – they are the entry points for returning to a run. Hankweave supports four ways back in: resume, start-new, rollback, and replay.
A run resumes when you invoke it against an existing execution directory. -e selects that directory, creates it when it does not exist, and resumes it when it has state. On resume, Hankweave verifies the data and hank hashes; --force overrides a mismatch.
Use --start-new when the next run must never resume. For an existing execution directory, select it with -e <execution-dir> and combine --start-new --force: Hankweave backs up existing state as .hankweave.backup-{timestamp} and wipes agentRoot/. Add --no-wipe to preserve that workspace instead. The CLI page owns the full flag contract.
A run rolls back through TUI or other WebSocket client commands–rollback.toCheckpoint, rollback.toCodon, or rollback.toLastSuccess–rather than through a CLI rollback flag. The protocol documents these commands. Rollback opens a continuation run that re-executes from the selected checkpoint without losing history.
A run replays with --replay <execution-dir>. Replay uses the recorded codon logs from a past execution as a test and debug path, without making new model calls. The stages replay runs and skips belong to resume, rollback, and retry; the flag's contract belongs to the CLI page.
Crash detection ties these paths together. On the next Hankweave startup, it detects a crashed run when its process ID is dead or its lock heartbeat has been stale for more than 2 minutes, then marks that run crashed in state.
You do not need the detailed procedures on a first read. When you have a run to operate, use resume, rollback, and retry. To inspect its files or journal, use execution directory and events. For the underlying concepts, continue with codons, checkpoints, sentinels, and budgets. Look up rigSetup in rigs and hank JSON, rigArchive in the execution directory, --no-wipe and --replay in CLI, and rollback commands in protocol.