# How a run works 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: ```bash 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. > **Pitfall:** Running `bunx hankweave@0.10.0` without a hank and data path launches the welcome wizard; pass `hank.json` and the data path explicitly. 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](/0.10.0/files/operate/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: ```text [] [ERROR] Self-test completed: FAILED [] [ERROR] Self-test FAILED: Some checks failed [] [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 `--`, and Hankweave prints the directory as it creates it: ```text Created new execution directory: ~/.hankweave-executions/ New execution: Source → data Exec → ~/.hankweave-executions/ 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](/0.10.0/files/reference/sentinel-config) and the two-line output-path rule in [sentinels](/0.10.0/files/concepts/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`. > **DeepDive:** The checkpoint store is a git repository with metadata at `.hankweave/checkpoints/.hankweavecheckpoints`, rather than the usual `.git` directory. From inside the execution directory, inspect its history with `git --git-dir=.hankweave/checkpoints/.hankweavecheckpoints log`. 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](/0.10.0/files/concepts/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.* ![Figure: inputs enter, execution runs inside the execution directory, outputs and receipts leave, and state supports later entry.](/content-assets/cf45dff5691c48c0/diagrams/start-how-a-run-works/1.svg) Figure: inputs enter, execution runs inside the execution directory, outputs and receipts leave, and state supports later entry.
Diagram as text ```text WHAT ENTERS WHAT RUNS — ~/.hankweave-executions// (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](/0.10.0/files/operate/runbook). With `-o/--output `, 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//`, 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: ```json {"id": "", "timestamp": "", "type": "codon.completed", "data": {"codonId": "summarize-notes", "success": true, "cost":"", "duration":"", "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 ` 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](/0.10.0/files/reference/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](/0.10.0/files/integrate/protocol) documents these commands. Rollback opens a continuation run that re-executes from the selected checkpoint without losing history. A run **replays** with `--replay `. 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](/0.10.0/files/operate/resume-rollback-and-retry); the flag's contract belongs to the [CLI](/0.10.0/files/reference/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](/0.10.0/files/operate/resume-rollback-and-retry). To inspect its files or journal, use [execution directory](/0.10.0/files/reference/execution-directory) and [events](/0.10.0/files/reference/events). For the underlying concepts, continue with [codons](/0.10.0/files/concepts/codons), [checkpoints](/0.10.0/files/concepts/checkpoints), [sentinels](/0.10.0/files/concepts/sentinels), and [budgets](/0.10.0/files/concepts/budgets). Look up `rigSetup` in [rigs](/0.10.0/files/concepts/rigs) and [hank JSON](/0.10.0/files/reference/hank-json), `rigArchive` in [the execution directory](/0.10.0/files/reference/execution-directory), `--no-wipe` and `--replay` in [CLI](/0.10.0/files/reference/cli), and rollback commands in [protocol](/0.10.0/files/integrate/protocol).