# Events Hankweave reports everything that happens during a run as a stream of typed events. Each event records one fact: a codon started, a tool returned a result, a sentinel fired, a rollback completed. Clients receive these events over the WebSocket, journaled categories are appended to disk, and sentinels subscribe to a filtered subset of the same stream. This page is the lookup catalog for that stream. It lists all 36 server event types with their payload fields, explains the four categories that determine where each event goes, shows representative envelope shapes, and covers the boundaries that are easy to get wrong: which events are journaled, which reach sentinels, and why client commands are not events at all. ## Every event type in one table Events record codon execution and agent activity. A **codon** is one agent task; a **rig** prepares its workspace and runs setup commands. A **sentinel** observes the events routed to it. Those three terms appear throughout the payload fields below. | id | category | journaled | sentinelRouted | payloadFields | receipts | | ------------------------ | ---------------- | --------- | -------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | archive.completed | server-state | true | true | codonId, archivedPaths | schemas/event-schemas.ts:668, schemas/event-schemas.ts:977, schemas/event-schemas.ts:1257, hankweave-runtime.ts:5465 | | archive.partial | server-state | true | true | codonId, archivedPaths, failedPaths | schemas/event-schemas.ts:673, schemas/event-schemas.ts:978, schemas/event-schemas.ts:1258, hankweave-runtime.ts:5450 | | assistant.action | agentic-backbone | true | true | codonId, action, content, toolName?, toolInput? | schemas/event-schemas.ts:572, schemas/event-schemas.ts:986, schemas/event-schemas.ts:1237, hankweave-runtime.ts:2777, hankweave-runtime.ts:2789, hankweave-runtime.ts:2824 | | budget.summary | server-state | true | true | ceiling, allocation, rows, totals | schemas/event-schemas.ts:724, schemas/event-schemas.ts:979, schemas/event-schemas.ts:1267, hankweave-runtime.ts:6478 | | checkpoint.list | server-state | true | true | runId, checkpoints, currentBranch | schemas/event-schemas.ts:637, schemas/event-schemas.ts:968, schemas/event-schemas.ts:1250, hankweave-runtime.ts:4255 | | codon.completed | server-state | true | true | codonId, success, cost, duration, exitStatus, failureReason?, failureIgnored?, budgetExceeded? | schemas/event-schemas.ts:560, schemas/event-schemas.ts:961, schemas/event-schemas.ts:1235, hankweave-runtime.ts:1886, hankweave-runtime.ts:2064, hankweave-runtime.ts:2253, hankweave-runtime.ts:3365 | | codon.extended | server-state | true | true | codonId, codonName, extensionNumber, exhaustWithPrompt, cumulativeTokens, cumulativeCost | schemas/event-schemas.ts:565, schemas/event-schemas.ts:962, schemas/event-schemas.ts:1236, hankweave-runtime.ts:2946 | | codon.started | server-state | true | true | codonId, codonName, codonDescription?, sessionId, previousSessionId?, startTime, promptMetadata? | schemas/event-schemas.ts:555, schemas/event-schemas.ts:960, schemas/event-schemas.ts:1234, hankweave-runtime.ts:316 | | error | server-state | true | true | message, codon?, fatal, severity?, context?, code? | schemas/event-schemas.ts:617, schemas/event-schemas.ts:967, schemas/event-schemas.ts:1246, hankweave-runtime.ts:975, hankweave-runtime.ts:995, hankweave-runtime.ts:1019, hankweave-runtime.ts:1062, hankweave-runtime.ts:1090, hankweave-runtime.ts:1116, hankweave-runtime.ts:1814, hankweave-runtime.ts:1867, hankweave-runtime.ts:2045, hankweave-runtime.ts:2236, hankweave-runtime.ts:2609, hankweave-runtime.ts:3981, hankweave-runtime.ts:4177, hankweave-runtime.ts:4273, hankweave-runtime.ts:4349, hankweave-runtime.ts:4512, hankweave-runtime.ts:4536, hankweave-runtime.ts:4599, hankweave-runtime.ts:4769, hankweave-runtime.ts:4804, hankweave-runtime.ts:4896, hankweave-runtime.ts:4918, hankweave-runtime.ts:5016 | | file.updated | agentic-backbone | true | true | path, filename, content, action | schemas/event-schemas.ts:587, schemas/event-schemas.ts:988, schemas/event-schemas.ts:1240, hankweave-runtime.ts:2357, hankweave-runtime.ts:3927 | | filetree.updated | agentic-backbone | true | true | tree | schemas/event-schemas.ts:592, schemas/event-schemas.ts:989, schemas/event-schemas.ts:1241, hankweave-runtime.ts:3954 | | history.batch | connection-state | false | false | events, hasMore | schemas/event-schemas.ts:688, schemas/event-schemas.ts:1012, schemas/event-schemas.ts:1260, hankweave-runtime.ts:1312 | | incomplete.codon | connection-state | false | false | codonId, codonName, message | schemas/event-schemas.ts:622, schemas/event-schemas.ts:1013, schemas/event-schemas.ts:1247 | | info | server-state | true | true | message | schemas/event-schemas.ts:627, schemas/event-schemas.ts:966, schemas/event-schemas.ts:1248, hankweave-runtime.ts:1705, hankweave-runtime.ts:1728, hankweave-runtime.ts:1902, hankweave-runtime.ts:1933, hankweave-runtime.ts:1971, hankweave-runtime.ts:2080, hankweave-runtime.ts:2196, hankweave-runtime.ts:2269, hankweave-runtime.ts:2730, hankweave-runtime.ts:3082, hankweave-runtime.ts:3100, hankweave-runtime.ts:3181, hankweave-runtime.ts:3205, hankweave-runtime.ts:3474, hankweave-runtime.ts:3723, hankweave-runtime.ts:3755, hankweave-runtime.ts:4058, hankweave-runtime.ts:4328, hankweave-runtime.ts:6427 | | loop.iteration.completed | server-state | true | true | loopId, iteration, durationMs, costUsd, tokensUsed, isFinal, terminationReason? | schemas/event-schemas.ts:612, schemas/event-schemas.ts:976, schemas/event-schemas.ts:1245, hankweave-runtime.ts:6035 | | pong | connection-state | false | false | message, timestamp, clientId? | schemas/event-schemas.ts:683, schemas/event-schemas.ts:1011, schemas/event-schemas.ts:1259, hankweave-runtime.ts:1215, hankweave-runtime.ts:1243 | | rig.output | agentic-backbone | true | true | codonId, stream, line, commandIndex | schemas/event-schemas.ts:607, schemas/event-schemas.ts:992, schemas/event-schemas.ts:1244, hankweave-runtime.ts:6109 | | rig.setup.completed | agentic-backbone | true | true | codonId, rigType, commandCount, durationMs, createdCheckpoint | schemas/event-schemas.ts:597, schemas/event-schemas.ts:990, schemas/event-schemas.ts:1242, hankweave-runtime.ts:2160 | | rig.setup.failed | agentic-backbone | true | true | codonId, failureType, exitCode?, commandIndex?, ignored | schemas/event-schemas.ts:602, schemas/event-schemas.ts:991, schemas/event-schemas.ts:1243, hankweave-runtime.ts:1791 | | rollback.archiveRestore | server-state | true | true | codonId, restoredPaths, failedPaths?, status | schemas/event-schemas.ts:678, schemas/event-schemas.ts:974, schemas/event-schemas.ts:1256, hankweave-runtime.ts:5557 | | rollback.codonCheckpoint | server-state | true | true | codonId, codonName, checkpoint, checkpointType, message | schemas/event-schemas.ts:647, schemas/event-schemas.ts:971, schemas/event-schemas.ts:1252, hankweave-runtime.ts:4684, hankweave-runtime.ts:5136, hankweave-runtime.ts:5191 | | rollback.completed | server-state | true | true | fromRun, toRun, checkpoint, codonId, codonName, checkpointType, autoRestart | schemas/event-schemas.ts:662, schemas/event-schemas.ts:972, schemas/event-schemas.ts:1255, hankweave-runtime.ts:4722, hankweave-runtime.ts:5254 | | rollback.progress | server-state | true | true | currentStep, totalSteps, message | schemas/event-schemas.ts:657, schemas/event-schemas.ts:970, schemas/event-schemas.ts:1254, hankweave-runtime.ts:5117, hankweave-runtime.ts:5156 | | rollback.rigCleanup | server-state | true | true | codonId, codonName, directories, status, successfulCleanups?, failedCleanups?, error? | schemas/event-schemas.ts:652, schemas/event-schemas.ts:973, schemas/event-schemas.ts:1253, hankweave-runtime.ts:5624, hankweave-runtime.ts:5662, hankweave-runtime.ts:5678 | | rollback.started | server-state | true | true | fromRun, fromCodon, toCodon, toCheckpoint, checkpointType, codonsToProcess | schemas/event-schemas.ts:642, schemas/event-schemas.ts:969, schemas/event-schemas.ts:1251, hankweave-runtime.ts:4645, hankweave-runtime.ts:5095 | | sentinel.error | sentinel | true | false | sentinelId, codonId, errorType, message, retriable, consecutiveFailureCount | schemas/event-schemas.ts:709, schemas/event-schemas.ts:1001, schemas/event-schemas.ts:1264, sentinels/sentinel.ts:576, sentinels/sentinel.ts:663, sentinels/sentinel.ts:798, sentinels/sentinel.ts:905 | | sentinel.loaded | sentinel | true | false | sentinelId, codonId, model, triggerType, executionStrategy, conversational, source, sourcePath? | schemas/event-schemas.ts:699, schemas/event-schemas.ts:999, schemas/event-schemas.ts:1262, hankweave-runtime.ts:5819 | | sentinel.output | sentinel | true | false | sentinelId, codonId, triggerNumber, outputType, content, cost, tokens, eventCount | schemas/event-schemas.ts:714, schemas/event-schemas.ts:1002, schemas/event-schemas.ts:1265, sentinels/sentinel.ts:538, sentinels/sentinel.ts:635, sentinels/sentinel.ts:762, sentinels/sentinel.ts:877 | | sentinel.triggered | sentinel | true | false | sentinelId, codonId, triggerNumber, strategy, eventCount, queueSize | schemas/event-schemas.ts:719, schemas/event-schemas.ts:1003, schemas/event-schemas.ts:1266, sentinels/sentinel.ts:392 | | sentinel.unloaded | sentinel | true | false | sentinelId, codonId, reason, errorType?, finalCost, llmCallCount | schemas/event-schemas.ts:704, schemas/event-schemas.ts:1000, schemas/event-schemas.ts:1263, sentinels/sentinel-manager.ts:851 | | server.idle | server-state | true | true | reason, message | schemas/event-schemas.ts:632, schemas/event-schemas.ts:964, schemas/event-schemas.ts:1249, hankweave-runtime.ts:941, hankweave-runtime.ts:3621, hankweave-runtime.ts:3791, hankweave-runtime.ts:3812, hankweave-runtime.ts:4072, hankweave-runtime.ts:4743, hankweave-runtime.ts:5279, hankweave-runtime.ts:5291 | | server.ready | connection-state | false | false | serverVersion, executionPath, agentRootPath, dataPath, port, proxyPort?, outputDirectory? | schemas/event-schemas.ts:545, schemas/event-schemas.ts:1010, schemas/event-schemas.ts:1232, hankweave-runtime.ts:916 | | state.snapshot | server-state | true | true | currentCodon?, completedCodons, fileTree, totalCost, totalTime, recentFileAccess?, isRollingBack | schemas/event-schemas.ts:550, schemas/event-schemas.ts:963, schemas/event-schemas.ts:1233, hankweave-runtime.ts:1422 | | state.transition | server-state | true | true | transitionType, runId?, codonId?, transition, resultingState | schemas/event-schemas.ts:693, schemas/event-schemas.ts:975, schemas/event-schemas.ts:1261, hankweave-runtime.ts:394 | | token.usage | server-state | true | true | codonId, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, totalCost, modelId?, modelUsage? | schemas/event-schemas.ts:577, schemas/event-schemas.ts:965, schemas/event-schemas.ts:1238, hankweave-runtime.ts:2646, hankweave-runtime.ts:2660 | | tool.result | agentic-backbone | true | true | codonId, toolUseId, toolName, result, truncated, originalLength, executionTimeMs, isError | schemas/event-schemas.ts:582, schemas/event-schemas.ts:987, schemas/event-schemas.ts:1239, hankweave-runtime.ts:2906 | Read the table as follows. The `id` column is the dot-separated event type literal, the value that appears in the envelope's `type` field. `category` is one of `server-state`, `agentic-backbone`, `sentinel`, or `connection-state`; the next section explains what each category implies. `journaled` and `sentinelRouted` are booleans describing the two routing decisions covered later on this page. In `payloadFields`, a trailing `?` marks an optional Zod field. The `receipts` column points at the schema definitions and emission sites in the 0.10.0 source. Every event envelope has `id`, an ISO 8601 `timestamp`, a literal `type`, and an event-specific `data` object carrying the payload fields listed here. > **VersionNote:** `incomplete.codon` is defined in the event type but has no construction site in hankweave 0.10.0; it is a dead or reserved event type. Per-event introduction markers are not present in this catalog. Adding them requires comparing `serverEventSchema` across tagged releases. ## How events are categorized Category membership is inferred at runtime from set membership, rather than stored as an explicit event field. Compile-time checks require every member of the event union to belong to exactly one category. The category matters because it sets the defaults for journaling and sentinel routing, so it is the first thing to check when an event does not appear where you expected it. **Server-state** events track the execution lifecycle: codon start, completion, and extension; rollback; budgets; state and checkpoints; errors and information; idle state; loop iteration completion; and archive operations. There are 20 types, with category defaults `journaled: true` and `sentinelRouted: true`. **Agentic-backbone** events capture what the agent actually does: assistant actions, tool results, file and filetree updates, rig setup completion or failure, and rig output. There are 7 types, with both category defaults set to `true`. Two volume limits apply here: `rig.output` is throttled to at most one event per second per stream and each line is truncated to 500 characters, and the default `toolResultTruncateLength` for `tool.result` content is 2500 characters. **Sentinel** events cover loaded, triggered, output, error, and unloaded states. There are 5 types. They default to `journaled: true` and `sentinelRouted: false`, so they remain available for audit without being fed back to sentinels. **Connection-state** events are client-specific and ephemeral: `server.ready` for the connecting client after the handshake, `pong` responses to `ping` and `ping.broadcast`, `history.batch` chunks during history synchronization, and the schema-defined `incomplete.codon`. There are 4 types, with both category defaults set to `false`. The generated table above is the lookup for each event's payload fields. Two non-obvious shapes are worth knowing before you write a consumer: `codon.completed.budgetExceeded` may be `{currency, limit, used}`, and `loop.iteration.completed.terminationReason` takes the values `iteration_limit`, `context_exceeded`, `sentinel_skip`, or `failure`. The examples below show one representative envelope per category. Values are placeholders, and optional fields are omitted; the `data` object is where the per-event payload fields from the table live. **Server-state – `state.transition`** ```json { "id": "", "timestamp": "", "type": "state.transition", "data": { "transitionType": "", "runId": "", "codonId": "", "transition": "", "resultingState": "" } } ``` **Agentic-backbone – `assistant.action`** ```json { "id": "", "timestamp": "", "type": "assistant.action", "data": { "codonId": "", "action": "", "content": "" } } ``` **Sentinel – `sentinel.output`** ```json { "id": "", "timestamp": "", "type": "sentinel.output", "data": { "sentinelId": "", "codonId": "", "triggerNumber": "", "outputType": "", "content": "", "cost": "", "tokens": "", "eventCount": "" } } ``` **Connection-state – `pong`** ```json { "id": "", "timestamp": "", "type": "pong", "data": { "message": "", "timestamp": "" } } ``` Note that the sentinel and connection-state envelopes have the same outer shape as the others. The category differences are in routing, not in structure. ## Which events are journaled A journaled event is appended to `/.hankweave/events/events.jsonl` as one JSON object per JSONL line. Appends are serialized in emission order; the journal is not timestamp-sorted. `EventJournal.append()` rejects non-journaled categories. Journal storage, query APIs, storage backends, and the distinction between the journal and the WebSocket log belong to [integrate/event-journal](/0.10.0/files/integrate/event-journal). ```text ## Routing summary (journaled / sentinelRouted) | category | journaled | sentinelRouted | |---|---|---| | server-state | true | true | | agentic-backbone | true | true | | sentinel | true | false | | connection-state | false | false | ``` The summary table shows the category defaults: server-state, agentic-backbone, and sentinel events are journaled; connection-state events are not. Three cases sit outside the plain defaults. An `error` with a target client is sent to that client and bypasses the journal; the broadcast form remains a journaled server-state event. `history.batch` bypasses `emit()` and is sent directly to a client. `incomplete.codon` has no construction site in the 0.10.0 server source. Two journaled events deserve attention when you consume the journal. `state.transition` records every StateManager transition and is the audit trail for state-machine changes; its transition type has 14 values, from `RunStarted` through `SentinelStatesUpdated`. `budget.summary` is emitted at run end before `RunCompleted` or `RunFailed`, so terminal-event watchers receive it first; its payload fields are `ceiling`, `allocation`, `rows`, and `totals`. ## Which events reach sentinels `server-state` and `agentic-backbone` events reach sentinels; `sentinel` and `connection-state` events do not. `setupSentinelEventRouting()` forwards only the first two categories to `sentinelManager.handleEvent`. Sentinel lifecycle events are excluded so a sentinel does not observe its own lifecycle events, and connection-state events are excluded because they are client-specific. The `sentinelRouted` column in the catalog records this filter's result; it describes the sentinel feed, not client delivery. See [Sentinels](/0.10.0/files/concepts/sentinels), [Sentinel configuration](/0.10.0/files/reference/sentinel-config), and [Protocol](/0.10.0/files/integrate/protocol) for the observer and transport contracts. ## Codon lifecycle Many of the server-state events report a codon moving through its lifecycle, so the canonical states are reproduced here from the source. ```ts * * Intent: Track granular progress for better crash recovery and user feedback. */ export type CodonStatus = | "preparing" // Rig setup running (copy files, run commands) | "starting" // Spawning Claude process | "initializing" // Process started, waiting for session ID | "running" // Claude is working (have session ID) | "completing-sentinels" // Completing sentinel work (draining queues) | "completed" // Success - terminal state | "failed" // Failed - terminal state | "skipped"; // User skipped - terminal state ``` The codon lifecycle has eight values: `preparing`, `starting`, `initializing`, `running`, `completing-sentinels`, `completed`, `failed`, and `skipped`. Its normal flow is `preparing → starting → initializing → running → completing-sentinels → completed`. `completing-sentinels` drains sentinel queues after the agent process exits and before the codon is marked terminal. The same spelling uses a hyphen, not the old underscore form `completing_sentinels`. The state can also appear in `failedDuring` when checkpoint creation fails during that phase. `failedDuring` is a snapshot field on a failed codon and has five values: `preparing`, `starting`, `initializing`, `running`, and `completing-sentinels`. Keep the three related concepts distinct: `StateTransition` is a separate event-driven persistence layer with 14 transition types, `CodonStatus` is the codon lifecycle, and `failedDuring` is a snapshot field on a failed codon. See [Codons](/0.10.0/files/concepts/codons), [Execution flow](/0.10.0/files/start/how-a-run-works), and [State file](/0.10.0/files/reference/state-file). ## Commands are not events A client command travels from a client to the server. An event travels from the server to clients. The catalog above has 36 server events; the exported client-command type definition has 13 command types: * `codon.start` * `codon.next` * `codon.skip` * `codon.redo` * `codon.forceStop` * `server.shutdown` * `checkpoint.list` * `rollback.toCheckpoint` * `rollback.toCodon` * `rollback.toLastSuccess` * `ping` * `ping.broadcast` * `history.sync` These commands are documented at [integrate/protocol](/0.10.0/files/integrate/protocol), not in this event catalog. Commands travel from the client to the server over the WebSocket and are never written to the event journal; journaled events are appended to `.hankweave/events/events.jsonl`. One name appears on both sides and causes real confusion. The `checkpoint.list` command requests a list; the `checkpoint.list` server event carries `runId`, `checkpoints`, and `currentBranch` in response. The terminal UI also constructs synthetic local copies for its display; those client-side values are not server events and are excluded from this catalog. > **Pitfall:** Do not confuse the 13 client commands with the 36 server events: commands travel over the WebSocket and are never written to the event journal, while journaled events are appended to `.hankweave/events/events.jsonl`. `server.force_shutdown` is parsed in `command-schemas.ts` and included in the runtime's read-only allowlist, but it is absent from the exported `clientCommandSchema` union. This source contradiction is a release-integrity note, not an additional event row; this page does not infer whether a client may send it. ## Where related topics live * [Event journal](/0.10.0/files/integrate/event-journal) – journal storage and queries. * [Protocol](/0.10.0/files/integrate/protocol) – client commands, connection framing, and event transport. * [Client and exported types](/0.10.0/files/integrate/client-and-exported-types) – client-facing package types. * [Sentinels](/0.10.0/files/concepts/sentinels) – the observer model. * [Execution flow](/0.10.0/files/start/how-a-run-works) – codon lifecycle context. * [State file](/0.10.0/files/reference/state-file) – persisted state shapes. * [Execution directory](/0.10.0/files/reference/execution-directory) – runtime paths. * [Runbook](/0.10.0/files/operate/runbook) – operational recovery and inspection. * [Errors and exit codes](/0.10.0/files/reference/errors-and-exit-codes) – failure classification and process outcomes.