Event journal

Every Hankweave run leaves behind a durable, line-by-line record of what happened: which codons started and finished, what the agent did, what files changed, what it cost, and what went wrong. That record is the event journal, a JSONL file inside the execution directory. Because it is plain JSON Lines, we can inspect it with jq during a live run, load it into a script afterward, or parse it with the schemas the published package exports.

This page walks through the journal in the order we would use it: what it captures and what it deliberately leaves out, where to find it on disk, how the storage backend behaves, how to read and filter it, and the pitfalls that matter when we turn raw events into summaries. By the end we will be able to answer questions like "why did this codon fail?" and "what did this run cost?" from the journal alone.

What the journal captures (and what it doesn't)#

The journal is the append-only JSONL file .hankweave/events/events.jsonl inside an execution directory. Hankweave constructs it with file-backed storage after setting up the .hankweave directory, and it initializes the journal before the server starts listening, so the file is ready before the run begins emitting server events.

Not every event the runtime produces ends up in the file. The journal accepts three event categories:

• Server-state events describe execution state and lifecycle, including start and completion events, transitions, errors, budgets, checkpoints (saved execution points), and rollbacks.
• Agentic-backbone events record agent actions, tool results, file changes, setup, and command output.
• Sentinel events record observer lifecycle, triggers, output, and errors. Sentinel configuration and trigger behavior belong to sentinel configuration; the parallel-observer model is explained in sentinels.

Connection-state events are the boundary: server.ready, pong, history.batch, and incomplete.codon are sent to specific WebSocket clients and are not written to the permanent journal. If one is passed to EventJournal.append(), the method throws instead of journaling it. In the 0.10.0 catalog, 32 of 36 event types are journaled: 20 server-state, 7 agentic-backbone, and 5 sentinel types. The four connection-state types are the remaining four.

↗ Enlarge

runtime event category                  destination

server-state (20) ------+
agentic-backbone (7) ---+-- isJournaledEvent --> .hankweave/events/events.jsonl
sentinel (5) -----------+

connection-state (4) ------ direct transport --> WebSocket clients
connection-state (4) ---x journal rejects it (append throws)

The category is inferred from the event type, not stored as a category field. The runtime checks membership in four compile-time-verified type sets; isJournaledEvent(event) is the combined predicate for the three persisted categories. A journal therefore tells you what the runtime recorded, but not every message exchanged with a client.

The file is cumulative for the life of its execution directory. Restarting or resuming with the same execution directory appends to the existing file rather than replacing it. The runtime uses the same file-backed journal on each run; its append queue preserves emission order, so do not use timestamps as a promise of file order.

Finding the journal on disk#

Resolve the path relative to the execution directory, not relative to the project or configuration that supplied it. The {timestamp}-{random}-{hash} text below is a placeholder, not a literal directory name: replace it with the path printed when Hankweave creates the execution (or inspect ls -t "$HOME/.hankweave-executions"), and run commands using .hankweave/... from inside that execution directory. These commands locate the journal and confirm it exists and is non-empty:

EXECUTION="$HOME/.hankweave-executions/{timestamp}-{random}-{hash}"
EVENTS="$EXECUTION/.hankweave/events/events.jsonl"
ls -l "$EVENTS"
test -s "$EVENTS"

The events/ directory is created lazily by file storage. Initialization creates its parent directories and an empty events.jsonl when the file is absent. The shipped .gitignore excludes .hankweave/events/, so the journal is not committed to the project. For the rest of the execution-directory tree, see the execution directory reference.

Once we have the file, its structure is simple: each journal line is one compact JSON object, and every journaled event has the same four top-level fields:

The writer uses JSON.stringify, so each event occupies one dense line, with no wrapper array, trailing comma, or pretty-printing. That shape means standard JSONL tools work directly on the file. This command prints the top-level keys of the first record:

EVENTS="$HOME/.hankweave-executions/{timestamp}-{random}-{hash}/.hankweave/events/events.jsonl"
head -1 "$EVENTS" | jq 'keys'

The jq check reports the alphabetized keys data, id, timestamp, and type. During a run, we can watch newly appended records as they arrive:

tail -f .hankweave/events/events.jsonl | jq '.type'

Two things are worth knowing before reading a journal top to bottom. The first event in the minimal single-provider capture is a state.transition with data.transitionType equal to RunStarted; do not assume that codon.started is the first line. And the file's storage order is emission order, which can differ from timestamp order: the sample below places a token.usage record with an earlier timestamp after file.updated.

The excerpt below is a real nine-record capture used by the published-package schema consumer, from a run whose single codon summarized a meeting-notes file. Read it as a worked example of the categories above: the run opens with a state.transition, the codon's work appears as codon.started, assistant.action, tool.result, and file.updated records, and the run closes with cost and completion records. It is an excerpt, not a complete journal or a per-run volume measurement; a complete journal also includes any other journaled categories and events emitted by that execution.

{"id":"1788337916074-d359hfspa","timestamp":"2026-09-02T08:31:56.074Z","type":"state.transition","data":{"transitionType":"RunStarted","runId":"1788337916070-aqhfn","transition":{"type":"RunStarted","data":{"runId":"1788337916070-aqhfn","runFolder":"~/.hankweave-executions/1788337915373-x194-4a876b/.hankweave/runs/1788337916070-aqhfn","gitBranch":"run-1788337916070-aqhfn","startingConditions":{"type":"fresh"},"serverPid":52624}},"resultingState":{"currentRunId":"1788337916070-aqhfn","runCount":1,"totalCost":0,"currentRunCost":0}}}
{"id":"1788337919229-5vx1pqbn5","timestamp":"2026-09-02T08:31:59.229Z","type":"codon.started","data":{"codonId":"summarize-notes","codonName":"Summarize the notes","sessionId":"83b52eaa-5147-4130-aef4-818c9c663c77","startTime":"2026-09-02T08:31:56.104Z"}}
{"id":"1788337922234-f4o24pmlt","timestamp":"2026-09-02T08:32:02.234Z","type":"assistant.action","data":{"codonId":"summarize-notes","action":"thinking","content":"The user wants me to:\n1. Read `notes.txt` from `read_only_data_source` directory in the current working directory\n2. Write `summary.md` in the current working directory with:\n   - A one-sentence summary of what the meeting decided\n   - Exactly three bullet points: one decision, one owner, one deadline\n   - Nothing else, under 15 lines\n\nLet me start by reading the notes file. I should use the shell to do this, since the user mentions I can use shell commands like `cat`."}}
{"id":"1788337923235-bgt2n27vh","timestamp":"2026-09-02T08:32:03.235Z","type":"tool.result","data":{"codonId":"summarize-notes","toolUseId":"toolu_01J8vWtreamPHhvdybo9n2FG","toolName":"Bash","result":"FICTIONAL TRAINING FIXTURE — invented content for documentation testing.\n\nMeeting notes, Tuesday.\nAttendees: Mara, Devon, Sam.\nWe compared the two vendor quotes for the packaging line refit.\nDecision: go with the Calloway quote (lower total, includes installation).\nDevon owns the purchase order and vendor follow-up.\nDeadline: PO issued by Friday the 12th.\nSam raised spare-parts stocking; parked for next week.","truncated":false,"originalLength":412,"executionTimeMs":1001,"isError":false}}
{"id":"1788337925241-w3x9qrqmz","timestamp":"2026-09-02T08:32:05.241Z","type":"file.updated","data":{"path":"summary.md","filename":"summary.md","content":"# Meeting Summary\n\nThe team selected the Calloway vendor quote for the packaging line refit based on lower total cost and included installation services.\n\n- **Decision:** Go with Calloway quote for packaging line refit (lower cost, includes installation)\n- **Owner:** Devon (purchase order and vendor follow-up)\n- **Deadline:** PO issued by Friday the 12th\n","action":"modified"}}
{"id":"1788337922233-lymp156f6","timestamp":"2026-09-02T08:32:02.233Z","type":"token.usage","data":{"codonId":"summarize-notes","inputTokens":9,"outputTokens":1,"cacheCreationTokens":0,"cacheReadTokens":18715,"totalCost":0.0018854999999999998,"modelId":"claude-haiku-4-5"}}
{"id":"1788337928090-rxcskk0dz","timestamp":"2026-09-02T08:32:08.090Z","type":"codon.completed","data":{"codonId":"summarize-notes","success":true,"cost":0.01050655,"duration":11986,"exitStatus":{"type":"success"}}}
{"id":"1788337930187-b3abvvs5h","timestamp":"2026-09-02T08:32:10.187Z","type":"budget.summary","data":{"ceiling":{},"allocation":"shared","rows":[{"codonId":"summarize-notes","status":"completed","budget":{},"actual":{"dollars":0.01050655,"timeSeconds":11.975,"outputTokens":654}}],"totals":{"actualDollars":0.01050655,"actualTimeSeconds":11.975}}}
{"id":"1788337930188-jrvuw0nlz","timestamp":"2026-09-02T08:32:10.188Z","type":"state.transition","data":{"transitionType":"RunCompleted","runId":"1788337916070-aqhfn","transition":{"type":"RunCompleted","data":{"runId":"1788337916070-aqhfn"}},"resultingState":{"currentRunId":null,"runCount":1,"totalCost":0.01050655,"currentRunCost":0}}}

How events are stored: the two backends#

The runtime does not require you to choose a backend: it always constructs FileEventStorage for the execution journal. That backend writes .hankweave/events/events.jsonl, counts existing non-empty lines when initialized, increments its in-memory count as events are appended, and persists across server restarts. It keeps no separate index or sidecar file. append(event) delegates to appendMany([event]); bulk appends flush in chunks of 10,000 lines, which affects only callers that submit bulk iterables.

MemoryEventStorage is the alternative implementation used when EventJournal is constructed without a storage argument. It keeps at most 100 events in memory. When it exceeds that limit, it drops at least 10% of the limit (or the excess, whichever is larger), so older events can disappear. It has no durable file and loses all events on restart; treat it as a test/development transport rather than the runtime's persistent journal.

An implementation can be substituted through the IEventStorage contract. It must provide initialize(), append(), appendMany(), getRecentEvents(), getTotalEvents(), and createReadStream(). The interface is the extension point; the shipped runtime's persistence behavior comes from FileEventStorage.

Reading events from the journal#

For external consumers, read the JSONL file directly; EventJournal is an internal server class, not the public client API. Its query helpers are still worth knowing, because they define the views the server itself offers and the behavior any reader should expect:

• getMostRecentEvents(limit) returns up to limit events newest first, together with totalEvents and hasMore. A handshake requests this view using handshakeHistoryLimit, whose default is 50.
• getAllEvents() is an async generator that reads one line at a time through readline. Use this for a large journal instead of loading the whole file into memory.
• getTotalEvents() returns the backend's in-memory count. File storage computes it during initialization and increments it on append.
• streamAllEvents() exposes the raw readable stream, which can be piped to another process, gzip, or an HTTP response.

A history.sync WebSocket command uses getAllEvents() and sends the full journal in history.batch responses. Those response messages are connection-state traffic and are not added back to the journal. The runtime also subscribes to emitted events for fire-and-forget CLI telemetry; that subscription is separate from journal storage.

For a small file, the same JSONL shape can be loaded into an array. For a large file, use the streaming form instead:

const events = fs
  .readFileSync('.hankweave/events/events.jsonl', 'utf8')
  .trim()
  .split('\n')
  .map((line) => JSON.parse(line));

The journal is append-only: records are not modified, deleted, or reordered after they are written. The reader does not skip malformed records. If a non-empty line is not valid JSON, JSON.parse in getAllEvents() throws, so validate or repair the file before treating a bulk read as complete.

Filtering events for your task#

Start with the event type, then inspect the type-specific data payload. Most events carry data.codonId, which lets us isolate one codon's activity while iterating the journal. The table below is the full 0.10.0 catalog: which types exist, which category each belongs to, whether it is journaled and sentinel-routed, and the payload fields to filter on. The event reference covers the same catalog with its schemas.

For category-aware TypeScript, import the public classifiers from hankweave/schemas:

  isAgenticBackboneEvent,
  isConnectionStateEvent,
  isSentinelEvent,
  // Event category classifiers
  isServerStateEvent,

The four guards are isServerStateEvent, isAgenticBackboneEvent, isSentinelEvent, and isConnectionStateEvent. The first three identify records suitable for the journal; the fourth identifies client-specific records that are not persisted.

Useful filters include:

• Failed codons: select event.type === "codon.completed" && !event.data.success; the typed event.data.failureReason includes its failure type and retriable flag. See errors and exit codes for the failure taxonomy.
• Errors: select event.type === "error". Its data.fatal field is required; data.severity, when present, is one of fatal, codon, operation, or warning.
• Time windows: compare the ISO 8601 timestamp lexicographically. For example, this streams JSONL records into an array before filtering:

jq -s '[.[] | select(.timestamp > "2026-09-01T12:00:00Z")]' .hankweave/events/events.jsonl

To build a progress view, we can treat codon.started as running and codon.completed as success or failure while recording its cost; an error whose data.codon identifies the codon supplies the failure note. A recent-event view of 100 records is enough for that live display, but it is bounded and can miss older activity.

Treat cost records carefully. Because codon.completed carries codonId but not runId, assign each completion to the enclosing state.transition RunStarted/RunCompleted span, whose records carry runId. For a reported per-codon view, retain the final codon.completed for each (runId, codonId) and do not add token.usage.totalCost or retry totals on top. codon.completed.cost already includes accumulated retry cost. token.usage mixes incremental per-message costs with a final total, and modelUsage can be absent even on that final record; summing it can double-count.

Event journal vs. WebSocket log: which one you want#

Use the event journal for post-run analysis of what the runtime recorded. It contains server-state, agentic-backbone, and sentinel events, but not client commands or connection-state events.

The configuration's default WebSocket-log path is .hankweave/logs/websocket.log. Its intended entry shape has loggedAt, direction (in or out), message, and optional metadata.size. In 0.10.0, however, the writer is reachable only through a deprecated wrapper that has no callers, so no runtime code path writes that file; the path and reader utility are not a usable wire-traffic record for this version. Do not substitute it for the event journal or promise that it contains a replayable WebSocket transcript.

When the journal grows too large#

The event journal has no automatic rotation, archive, or truncation. It grows monotonically for the life of the execution directory. The available captures do not support a general "events per codon" or bytes-per-event estimate, so measure a complete journal from your own workload if you need capacity planning.

Between runs, preserve history by moving or compressing events.jsonl. If the file is absent at the next execution, file-storage initialization recreates an empty one:

EVENTS="$HOME/.hankweave-executions/{timestamp}-{random}-{hash}/.hankweave/events/events.jsonl"
gzip -c "$EVENTS" > "$EVENTS.gz"
mv "$EVENTS" "$EVENTS.previous"

Do this only between runs. During a run, the runtime serializes appends through eventJournalAppendQueue, preserving emission order under concurrent bursts. On clean shutdown it awaits that queue before returning, so the queued file writes have drained before shutdown completes.

Reading from disk with real import paths#

The published library surfaces for event parsing are under hankweave/schemas, not @hankweave/types. Parse each JSONL line with the public union schema:

import { serverEventSchema } from "hankweave/schemas";

const event = serverEventSchema.parse(JSON.parse(line));

For large journals, pair fs.createReadStream with readline, as the server's own reader does:

const rl = readline.createInterface({
  input: fs.createReadStream('.hankweave/events/events.jsonl'),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  const event = serverEventSchema.parse(JSON.parse(line));
  // handle event
}

The same hankweave/schemas export provides per-event schemas such as codonStartedEventSchema, codonCompletedEventSchema, and toolResultEventSchema for targeted parsing. The separate hankweave/types export contains state and branded-ID types for consumers that also read state.json; see client and exported types.

Watch out: duplicate completion events#

A retrying or resumed codon emits codon.completed once for each attempt. The same codonId can therefore appear in multiple completion records. Loop repetitions are different: their runtime codon IDs can be distinct, so they add completion records without being deduplicated by the retry key; a captured three-codon loop produced seven completion events.

When summarizing spend or status, keep run boundaries from state.transition and retain the last completion for each (runId, codonId). Do not sum every completion for a retried codon, and do not add token.usage totals to the completion cost. A codon.extended event is separate: exhaustWithPrompt emits one for each extension and includes its extension number, cumulative tokens, and cumulative cost.

To check a journal for repeated completions, use -s so jq reads the JSONL stream as one array:

jq -s '[.[] | select(.type == "codon.completed")] | length' .hankweave/events/events.jsonl

Compare that count with the runtime codon records for the run. If we find more completion records, retries or loop repetitions explain the difference.