fiber

The event stream

What Fiber writes down, what it emits, and what a consumer can rely on. A consumer is anything that reads these lines: a client, or a program reading a session's events.jsonl. This is what is true now, not a plan. It is settled by What is the event stream, and what is durable?; that ticket's resolution holds the rationale and the rejected alternatives.

Vocabulary is GLOSSARY.md. Session, turn, step, action, event and tool call mean what it says there and nothing else.

The rule everything else follows from

The session log is the only state of record for what happened in a session. Anything the loop, the TUI or an extension needs to know about a session after a resume is an event, or a fold of events. Configuration, credentials and an extension's data directories describe no single session. They live in Fiber home (docs/state.md), and a repository's configuration in its .fiber/ directory (docs/configuration.md). Runtime objects may cache and index; none of them is ever a second authority. No file beside the log holds state.

Two consequences that get violated first, so they are stated first:

The envelope

One JSON object per line, one event per line, every line valid on its own.

FieldOnMeaning
kindevery linethe only discriminator a consumer switches on
session_idevery session linethe session this event belongs to
tsevery linemilliseconds since the epoch
schema_versionevery lineevery line must be readable without negotiation
turn_idlines about a turn, or an action in onecorrelation
action_idlines about an actioncorrelation
seqdurable lines onlyposition; contiguous per session, never reset or reused
payloadevery linekind-specific body, nested so it can never collide with the envelope

A durable line, which carries seq, and an ephemeral one, which does not:

{"kind":"turn_started","session_id":"s_4c1d","ts":1759150000000,"schema_version":1,"turn_id":"t_9a02","seq":7,"payload":{"input":[{"command_id":"c_7f3a","content":[{"text":"fix the failing test","type":"text"}],"source":"driver","type":"message"}]}}
{"kind":"assistant_message_delta","session_id":"s_4c1d","ts":1759150000123,"schema_version":1,"turn_id":"t_9a02","action_id":"a_03f7","payload":{"text":"Hel"}}

Kind-specific fields live under payload. A consumer skips any kind it does not recognise and ignores fields it does not know.

The one line that is not an envelope is the fiber_exited a process prints when it fails before any session exists (docs/errors.md, "Before a session exists"). It is not written to any log. It carries kind, schema_version and a payload holding exit_code and error, as fiber_exited does. It has no session_id, ts or seq. A caller reads .payload.exit_code and .payload.error on the last line whatever happened. Apart from the hub's own lines below, only this line may lack a session, and its own type says so, so no other kind can drift into having none. It keeps kind so that fiber ask … | tail -1 reads the verdict whatever happened.

{"kind":"fiber_exited","schema_version":1,"payload":{"error":{"code":"no_model","message":"No model is configured. Set one in a configuration file or pass --model."},"exit_code":1}}

The hub sends nine lines of its own, only on a connection to the hub and never to a log (docs/invocation.md, "The hub"). Each carries kind, ts, schema_version and payload, and no session_id in the envelope, since it is about the hub or names its session in the payload:

The hub's command_accepted and command_rejected for a hub command carry no session_id in the envelope either.

A process extension started outside a session, whose extension_hello has reason call, exchanges lines with no session_id in the envelope. They pass only between Fiber and that process, and no log, hub connection or session reader sees them.

Durable and ephemeral

A line is durable if and only if it carries seq. There is no separate flag, because a flag can disagree with the thing it describes.

The durable lines, in order, are the log. Filter a non-interactive run's stdout to durable lines carrying its own session_id and you have events.jsonl, byte for byte. There is no second format and no replay command: a client catching up reads the file.

A delegate's lines stay on the delegate's own stream; nothing is relayed onto its parent's (docs/delegates.md, "Streams").

The TUI is a separate process that reads the same event stream through the hub (docs/invocation.md, "Processes"), so it holds no private path to state; anything it renders exists in this contract, as an ephemeral event where it is display-only.

Identity and ordering

Payload types

These rules and shapes hold for every kind's payload. Each kind's table below names a shape from this section by its name.

error

KeyTypeRequiredMeaning
codestringyesa stable label from docs/errors.md, "Registry"; an open set, and an unknown code is a generic failure
messagestringyesFiber's own sentence, saying what to do when there is a fix
retry_after_msintegernoon a failed model call, the wait the provider asked for, in milliseconds
providerobjectnoon a failed model call, or a Lua provider's credential() that failed at startup: name (string), status (integer, the HTTP status; absent when an extension provider's credential() or sign() failed) and message (string, the provider's own message)

process

KeyTypeRequiredMeaning
exit_codeintegernothe exit code, when the process exited
signalstringnothe signal's name, such as SIGKILL, when a signal ended the process
timed_outbooleanyeswhether Fiber stopped it at its timeout

A consumer keys on whether process is present, never on the tool's name.

Content parts

content is an array of parts, in order. type is an open set, and a consumer shows an unknown part as a placeholder.

typeKeysMeaning
texttext (string)text
imagepath (string), mime_type (string), width (integer), height (integer)the processed image file in the session's artifacts/ (docs/model-routing.md, "Image limits"), its type, such as image/png, and its size in pixels, so a client lays it out without decoding it
pdfpath (string), page_count (integer), pages (image parts, optional)the PDF in the session's artifacts/, the number of pages sent, and the pages rendered as image parts, absent when they could not be rendered (docs/tools.md, "read")

The log never holds an image's bytes. A tool's image and a pasted image are both written to artifacts/ and named by path.

Declared effects

Five keys, on tool_call_started, permission_requested and, for a reviewed call's decision that has no request, permission_resolved, in the vocabulary of docs/permissions.md, "Effects" and "Confinement":

KeyTypeRequiredMeaning
effectsarray of stringsyeseach of reads, writes, executes and network that applies, a closed set; empty when the call declared none
reversiblebooleanyeswhether the call is reversible
pathsarray of stringsnothe paths the call touches, where the tool declared them
always_reviewedbooleannotrue when the tool declared the call always reviewed (docs/permissions.md, "Effects"); omitted when false
confinedbooleannothe call runs only inside the sandbox; if the sandbox can't be applied at spawn, the call fails and nothing runs

Event order is unchanged: tool_call_started remains before execution and carries confined: true for a call Fiber will run only inside the sandbox. Read that as "every command this call ran, ran confined". It holds on spawn failure too, because nothing ran. If applying the sandbox fails at spawn, the call ends through the normal tool_call_* end event with an error naming the cause; a failed confined call is never rerun unconfined.

tokens

KeyTypeRequiredMeaning
inputintegeryesinput tokens neither read from nor written to the cache
cache_readintegeryesinput tokens read from the cache
cache_writeobjectyesinput tokens written to the cache, keyed by cache-write billing class ("5m", "1h"), not the vendor lifetime (OpenAI's 30-minute cache reports under "5m"); {} when nothing was written
outputintegeryesoutput tokens, reasoning included

usage

Totals over some set of model calls, folded from their usage_recorded lines. They are output, never a source.

KeyTypeRequiredMeaning
tokenstokensyesthe calls' tokens, summed
costnumber or nullyesUS dollars billed per token, summed over the calls without subscription whose cost is known; 0 when there were none; null when there were some and none had a known cost
subscription_costnumberyesUS dollars at API prices for the calls with subscription; 0 when there were none

questions

An array of ask_user questions as the model called them: header, question, optional options (absent on a free-text question; each a label and an optional description) and an optional multiSelect (docs/tools.md, "The call").

Where a message came from

KeyTypeRequiredMeaning
sourcestringyesdriver, a client's command; extension, an extension's host.drive, or a message a turn_end hook returned; session, another session's session_message (docs/tools.md, "Messaging other sessions"); or fiber, Fiber's own message, such as the ending notice (docs/tools.md, "Background jobs"); a closed set
extensionstringnothe extension's name, when source is extension
from_session_idstringnothe sending session's id, when source is session
command_idstringnothe id of the prompt, steer or message command that sent it; present unless source is fiber or a turn_end hook returned the message (docs/extensions.md, "The hook points")

changed_by

An array of the names of the extensions whose hooks changed the line's content, in the order they ran. Absent when no hook changed it.

ran_by

An inner call's anchor: the extension that ran it with host.tool, and the outer call or command it ran inside (docs/extensions.md, "Running a tool"). Exactly one of outer_action_id and command_id is present.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
outer_action_idstringnothe action_id of the extension's tool call the inner call ran inside
command_idstringnothe id of the command driver command whose invocation the inner call ran inside

Kinds

Fiber's loop emits the kinds below. On a crash takeover the keeper writes keeper_started and keeper_bound (docs/tools.md, "The keeper"). MCP elicitation and ask_user add no kind of their own. MCP elicitation, and ask_user in a session a person drives, raise interactions ("Interactions") that every driver answers with reply. In a session a program drives, ask_user ends the turn with questions on turn_completed.

Each kind's table lists the keys of its payload. The envelope's fields, turn_id and action_id included, are never repeated in it.

Process boundary

fiber_started

Durable. The first line a process writes when it resumes a session; in a new session it follows session_started, which is always the log's first line. The schema version is the envelope's schema_version.

KeyTypeRequiredMeaning
versionstringyesthe Fiber version, such as 0.0.1
resumedbooleanyesfalse for a new session, true for a resumed one

fiber_exited

Durable. The last line a process writes for a session.

KeyTypeRequiredMeaning
exit_codeintegeryesthe process's exit code (docs/invocation.md, "Lifecycle")
usageusageyesthis process's model calls for the session, its delegates included (docs/loop.md, "Spending budget"); a cost that settles after exit is missing from it; absent only on the line a process prints when it fails before any session exists ("The envelope")
final_action_idstringnothe action_id of the final assistant message, when there is one
textstringnothat message's text: its text_completed parts joined in order; present exactly when final_action_id is
errorerrornowhy the process failed (docs/errors.md, "What a caller gets")
suspended_onstringnothe request_id of the pending approval, question or repository offer the process exited on; with an offer and an approval or question both pending, the approval or question (docs/invocation.md, "Lifecycle")
questionsquestionsnocopied from the last turn_completed, when its turn ended on questions

A process is the unit these two lines bound (GLOSSARY.md, "Process"). They are durable for one reason: a fiber_started with no matching fiber_exited is the only record that a process died rather than finished. A session that was rewound ends with rewound instead, and a session that moved workspace ends with moved instead, each closing the boundary the same way ("Rewind", "Change workspace"). That is the same trick tool calls use below.

fiber_exited copies the final message's text as well as pointing at it, so a one-shot caller reads the last line and is done:

answer=$(fiber ask "$prompt" | tail -1 | jq -r .payload.text)

That copy is output, never a source. Fiber never reads it back, no fold consults it, and if it ever disagrees with the action it points at, the action wins. This is the one place a line restates content another line already carries, and it is safe for a specific reason: it is written once, at exit, from the message it copies, so it cannot drift while a session is running. Every other duplicate is the bug this page exists to prevent — a stored fold that is read back and goes stale.

The alternative was making callers filter the stream for the last assistant_message_completed, which a one-shot caller should not have to know about.

Session and turn

session_started

Durable. The first line of every session's log. The session's creation time is the envelope's ts.

KeyTypeRequiredMeaning
workspacestringyesthe workspace root
variablesobjectyesthe environment variables the session runs commands with, without their values: path (string, the PATH), names (array of strings, the other variables' names, sorted) and source, login_shell when the hub's login-shell capture succeeded, or inherited when it failed or for a session fiber ask started; a delegate carries its parent's (docs/invocation.md, "A session's environment")
parentobjectnofor a delegate: session_id, its parent session, and delegate_id, the delegate's job_id there (docs/delegates.md)
forked_fromobjectnofor a fork, a rewind, or a workspace move: session_id and seq, the parent session and the point it continues from; project (string, optional), the parent's project key when it differs from this session's (docs/state.md, "Projects"; docs/delegates.md, "Forks"; "Rewind" and "Change workspace" below)
rewindobjectnofor a rewind: summary (string, optional) and note (string)
worktreeobjectnowhen the session runs in a worktree Fiber created for it, or for the session a rewind, a fork, or a start continues continues: path and branch (strings), and repository (string), the absolute path of the repository's git common directory, which a resume recreates a removed worktree from; path is also workspace (docs/invocation.md, "Isolation")
supervisedbooleannotrue when a program drives the session (docs/permissions.md, "Supervised sessions"): fixed at start, kept across a resume; absent means false

rewound

Durable. The last line of a session that was rewound ("Rewind" below).

KeyTypeRequiredMeaning
new_session_idstringyesthe session that continues this one
seqintegeryesthe point
from_session_idstringnothe session whose log seq counts in, when it is not this one: a session on this session's forked_from chain
summarystringnothe old session's summary of the path after the point

moved

Durable. The last line of a session that moved workspace ("Change workspace" below). Its payload has no summary or from_session_id.

KeyTypeRequiredMeaning
new_session_idstringyesthe session that continues this one
seqintegeryesthe last durable line before moved; the child's forked_from.seq is this value
workspacestringyesthe resolved absolute workspace of the new session

turn_started

Durable. Its envelope carries the new turn_id.

KeyTypeRequiredMeaning
inputarrayyeseverything that started the turn, in arrival order, as items below

Each item has a type, an open set; a consumer skips an item it does not know.

typeKeysMeaning
messagecontent (content parts), the keys of "Where a message came from", changed_bya message from a driver, an extension, another session or Fiber
shell_commandseq (integer)a shell_command line since the last turn, named by its seq
jobsjob_ids (array of strings)jobs whose news started the turn; their job_completed and job_line lines follow at the first step boundary
compactioncommand_id (string)a compact command sent between turns, which is a turn of its own (docs/invocation.md)
rewindcommand_id (string)a rewind command that asked for a summary: the summary's turn on the old session, between turns (docs/events.md, "Rewind")

step_started

Durable. The payload is {}; the envelope's turn_id is all it carries. It opens a step (below).

turn_completed

Durable.

KeyTypeRequiredMeaning
outcomestringyescompleted, interrupted or failed; a closed set
errorerrornoon failed (docs/errors.md, "What ends a turn")
questionsquestionsnowhen an ask_user call ended the turn for a driver that is a program (docs/tools.md, "Asking the person")

steering_applied

Durable. A steering message a running turn received at a step boundary.

KeyTypeRequiredMeaning
contentcontent partsyesthe message as the turn received it
sourcestringyesas in "Where a message came from"
extensionstringnoas in "Where a message came from"
from_session_idstringnoas in "Where a message came from"
command_idstringnoas in "Where a message came from"
changed_bychanged_bynowhen a hook rewrote the message

steering_queue

Ephemeral. Written whenever the queue changes; the latest wins.

KeyTypeRequiredMeaning
messagesarrayyesevery steering message still queued, oldest first, each with content and the keys of "Where a message came from"; empty when the queue is

shell_command

Durable. A command the person ran with send true (docs/invocation.md, shell), written when the command ends. It joins the next turn's input. Its shell_command_started comes before it in the log, with the same command_id; a command that could not start ends here too, with the failure as output.

KeyTypeRequiredMeaning
command_idstringnothe driver command's id, pairing the end with its shell_command_started; absent on a line written before that kind existed
commandstringyesthe command as typed
outputstringyesits output, cut as a shell call's result is (docs/tools.md, "Result and output"); for a command that could not start, <code>: <message>, the error as the sender was answered
artifactstringnothe full output's path, when cut
processprocessyeshow it ended; a command that could not start has neither exit_code nor signal

shell_command_started

Durable. A command the person ran with send true, written when the loop takes its start, before the command starts, so before any of its shell_command_delta lines and before its shell_command. It is written while a turn runs too, at the next point the loop reads its inbox: while a tool call runs, at a step boundary, and when a model response ends if one is streaming. Fsynced before the command starts (the third exception in "Writing"). It renders nothing to the model: only shell_command joins the next turn's input.

KeyTypeRequiredMeaning
command_idstringyesthe driver command's id
commandstringyesthe command as typed

A client folds it as a live row for command_id: the command, then its output so far from the deltas, then no ending until shell_command with the same command_id replaces the row. A client that attaches mid-run reads this line and every delta after it attaches, and the full output when shell_command lands; output that streamed before it attached is not replayed. A command run with send false writes neither line.

shell_command_delta

Ephemeral. Output a running command added, paced as job_delta is. With send true it goes to every attached client; with send false it goes only to the client that sent the command, and is never logged.

KeyTypeRequiredMeaning
command_idstringyesthe driver command's id
textstringyesoutput added since the last delta, at most the newest 64 KiB of it, starting at a character boundary; the whole output is in shell_command's output or, for send false, in the command's answer

session_named

Durable. The latest is the session's name (docs/tools.md, "Naming the session").

KeyTypeRequiredMeaning
namestring or nullyesthe name; null when the person cleared theirs
bystringyesperson, from the name command, which pins the name, or model, from name_session; a closed set

archived

Durable. The payload is {}. The hub appends it to an exited session's log while it holds the session's lock, with the next seq, when a client archives the session (docs/invocation.md, "Archiving"). The session is archived while this line comes after its last fiber_started; resuming it unarchives it.

directory_added

Durable. Written when the session accepts an add_directory driver command (docs/invocation.md, "Driver commands") for a folder outside the current boundary, and by a delegate at spawn for each of its parent's added folders that its folded history does not already hold (docs/delegates.md, "Forks"). An add_directory command for a folder already inside the workspace or an added folder is accepted with no event written.

KeyTypeRequiredMeaning
pathstringyesthe added folder's resolved path
inheritedbooleannotrue when a fresh spawn records the root before its opening; the opening lists it, so it adds no separate message; absent or false for a normal folder-added message, including a folder added after a fork's point

The fold adds each resolved path at its first directory_added event and keeps it in that position. A later event for the same canonical path does not move it: B, A, B folds to B, A. A resume rebuilds the same order from the log. The opening message rebuilt at a compaction lists the folders in that order (docs/system-prompt.md, "After a compaction"). A fork or a rewind from a point after the event keeps it, and one from a point before it does not. For a fresh delegate spawn, the opening lists inherited folders, so their seed events add no separate folder-added messages. A later addition to a running fork does render its normal message.

clients

Ephemeral. Written whenever a full connection attaches or leaves (docs/invocation.md, "Driver commands", subscribe).

KeyTypeRequiredMeaning
countintegeryesthe full connections attached to the session, the receiving client included; summary connections are not counted

session_status

Ephemeral. The session's own summary of itself, for a client that is not showing it: a session list, a rail, a delegate card. Written when any field changes. For output_at and tool_output_at, a change counts only once it has moved at least 10 seconds from the value last written, so a streaming reply does not write a status per delta. The latest wins, and a client that subscribes, at either level, is sent the latest.

KeyTypeRequiredMeaning
namestringyesthe session's name, or its first prompt when it has none
namedbooleannotrue when name came from session_named; absent means false
workspacestringyesthe workspace path
projectstringyesthe project's key (docs/state.md, "Projects")
parentstringnoon a delegate, the parent's session_id
supervisedbooleannotrue when a program drives the session (docs/permissions.md, "Supervised sessions"): fixed at start, kept across a resume; absent means false
modelstringyesthe model reference in use
thinkingstringnothe thinking level in use, as on preamble_built; absent when there is none
statestringyesstreaming, tool, retrying, waiting, jobs (no turn running, jobs running) or idle (nothing in flight); a closed set
closingbooleannotrue once the session has accepted close; absent otherwise
toolstringnowith tool, the running tool's name
waitingobjectnowith waiting: request_id (string), kind (approval, question or offer, a repository's offer: "Repository code") and summary (string, one line)
sinceintegeryeswhen this state began, as ts
output_atintegernowith streaming or retrying: when the model last sent output for the current request (text, reasoning or tool arguments), as ts; absent before the request's first output
tool_output_atintegernowith tool: when the running tool last wrote output (tool_call_delta), as ts; absent before its first output
startedintegeryeswhen the session started, as ts
callsintegeryestool calls the session has made so far
repeatsintegernohow many tool calls in a row, ending with the latest, had the same name and the same arguments; absent when it is 1
turnsintegernoturns the session has started so far, the running one included; the usage view and the side panel show it (docs/tui.md); a client draws no turn count when it is absent
stepstringnoafter the first tool call: the latest call's tool name, then a space and its subject, such as "read app.rs"; the name alone when the subject is empty or the call has none (docs/permissions.md, "What a rule matches")
gitobjectnopresent in a git repository: branch, a string, or null when HEAD is detached
contextobjectnoafter the first request: tokens, the context's size in tokens at the latest request that reported its input tokens, and window, the model's context window (integers)
cache_expiresintegernoafter the first model request: when the session's prompt cache expires, as ts: the end of its latest model request, a warming refresh included, plus its cache lifetime (docs/prompt-cache.md, "Cache lifetime")
spendusageyesthe session's spend so far, delegates included, from the usage fold
delegatesintegeryesdelegates running
jobsintegeryesjobs running, delegates excluded
clientsintegeryesthe full connections attached, as the latest clients line counts them; summary connections are not counted

context_added

Durable.

KeyTypeRequiredMeaning
textstringyesthe text a hook added to the conversation
extensionstringyesthe hook's extension
hookstringyesthe hook point, such as turn_start (docs/extensions.md, "The hook points")

A steering message — input sent while a turn is running — joins that turn at its next step boundary, and steering_applied is how the log shows what the turn actually received. The loop drains its inbox once more before a turn completes (docs/loop.md, "Ending a turn"), so only a message that arrives after that becomes the next turn's input, and it appears on the next turn_started instead. The threading this rests on is the concurrency section of docs/architecture.md; the driver commands that send and withdraw one, steer and steer_drop, are docs/invocation.md.

clients lets a client know whether it is the only one attached, which the terminal asks before quitting (docs/tui.md, "Quit"). The latest wins, and a client that attaches is sent the latest. session_status carries the same count, so a client holding only a summary connection, such as the hub's feed, reads it there.

steering_queue lets every attached client show and edit the queue, not only the client that sent a message. It is ephemeral because steering_applied makes each entry obsolete. The latest wins, and a client that attaches is sent the latest, as with extension_ui.

turn_completed means settled. Retries and compactions happen inside the turn and appear as actions, so there is never a second "really finished" event.

A step is one round-trip to the model, and step_started opens it. It is written before anything else in the step: the steering_applied and job_line lines the step takes in, and any compaction it runs before calling the model. A step ends where the next step_started or the turn_completed is, so there is no closing line. A step's number is the count of step_started lines in its turn. The boundary is not derived from the actions, because a retry and a compaction's note request are each a model call inside one step: counting assistant_message_started gives attempts, never steps.

Actions

Every line carries the envelope's action_id. Deltas are ephemeral; everything else is durable.

assistant_message_started

Durable. The payload is {}. Every model call the loop makes for the conversation opens with one, the note request included, written before the request is sent ("Writing").

assistant_message_delta

Ephemeral.

KeyTypeRequiredMeaning
textstringyesthe text added since the last delta

assistant_message_completed

Durable.

KeyTypeRequiredMeaning
outcomestringyescompleted or failed; a closed set
errorerrornoon failed, with retry_after_ms and provider where they apply (docs/errors.md, "A failed model call")

text_completed

Durable. One text part of the reply. A reply with several text parts has one line for each, even when two parts hold the same text. The lines carry the assistant message's action_id. They record no effect: assistant_message_completed makes them durable.

KeyTypeRequiredMeaning
textstringyesthe part's text; "" for a part the provider sent with only opaque data
provider_itemany JSONnothe provider's own form of the part, with its thought signature or other opaque data, sent back unchanged only to the model that produced it (docs/loop.md, "What the model is sent"); absent when the part carries none

A reply's items are logged in the order the model produced them: its text_completed, reasoning_completed and tool_call_requested lines follow its assistant_message_started in that order, and its assistant_message_completed closes it. Replay rebuilds the reply from them in that order.

tool_call_arguments_delta

Ephemeral. A tool call the model is still emitting, under the assistant message's action_id. The arguments are parsed once, when the call finishes (docs/loop.md, "One step"); tool_call_requested then carries them.

KeyTypeRequiredMeaning
indexintegeryesthe call's position within the message, from 0
namestringnothe tool's name, once the provider has sent it
textstringyesthe raw argument text added since the last delta

reasoning_started

Durable. The payload is {}.

reasoning_delta

Ephemeral.

KeyTypeRequiredMeaning
textstringyesthe readable reasoning added since the last delta

reasoning_completed

Durable.

KeyTypeRequiredMeaning
textstringyesthe readable reasoning; "" when the provider sent none
provider_itemany JSONnothe provider's reasoning item exactly as it arrived (docs/loop.md, "What the model is sent"); absent when the provider sent none

tool_call_requested

Durable. The model finished emitting the call, or an extension ran an inner call with host.tool. A line with ran_by is an inner call: it is never part of the history a provider is sent, and its outcome reaches the model only through the outer call's result.

KeyTypeRequiredMeaning
namestringyesthe tool's name as the model called it
argumentsany JSONyesthe arguments as the model sent them: an object, or a string holding the raw text when it was not JSON
provider_idstringnothe provider's own id for the call ("Identity and ordering"); absent when the reply carried none
repairedobjectnothe arguments after repair (docs/tools.md, "Before a call runs"); absent when nothing was repaired
repairsarraynowith repaired, one object per fix: path (string, a JSON Pointer into arguments) and fix, one of null_dropped, string_to_number, string_to_boolean or string_parsed
ran_byran_bynoon an inner call, its extension and anchor; absent on the model's calls
provider_itemany JSONnoon a call the provider ran itself, such as a hosted web search, the provider's call block exactly as it arrived, sent back unchanged only to the model that produced it (docs/tools.md, "Hosted by the provider"); absent on a call Fiber runs

tool_call_started

Durable. Execution began, wherever it runs, including a provider-hosted tool the provider reports as in progress.

KeyTypeRequiredMeaning
effectsarray of stringsyesas in "Declared effects"
reversiblebooleanyesas in "Declared effects"
pathsarray of stringsnoas in "Declared effects"
always_reviewedbooleannoas in "Declared effects"
confinedbooleannoas in "Declared effects"
argumentsobjectnothe arguments that ran, when a before_tool hook rewrote them
changed_bychanged_bynowith arguments

tool_call_delta

Ephemeral. Streamed output and progress, paced as docs/tools.md, "Progress", says.

KeyTypeRequiredMeaning
textstringnooutput added since the last delta, at most the newest 64 KiB of it, starting at a character boundary; after a burst, the older bytes are only in the result and its artifact
detailsany JSONnoprogress for clients, shaped as the tool chooses; a client that does not recognise it ignores it

tool_call_completed

Durable. The call's outcome.

KeyTypeRequiredMeaning
statusstringyescompleted, failed, denied or cancelled; a closed set
reasonstringnoon denied, why; an open set, and an unknown reason is a generic denial
errorerrornoon failed
processprocessnoon any call that ran a process
contentcontent partsyesexactly what the model is sent, except a tool_search result, rendered from loaded (docs/tools.md, "What a result carries")
detailsany JSONnodata for clients, such as an edit's diff; never sent to the model. File tools also carry the reserved file_seen object here (below)
artifactstringnothe full output's path, when the result was cut or a hook returned text for it
keptarraynowhen the result was cut, the byte ranges of the full output that content holds, each [start, end] (integers, end exclusive), in order (docs/tools.md, "Bounded results")
changesarraynoon a call that changed files, one object per file: path (string) and added and removed (integers, lines)
controlobjectnoinstructions to the loop: compact (string), a compaction note (docs/compaction.md); questions (questions); name (string), a session name (docs/tools.md, "What a result carries"); skill (an object holding name and path, both strings), a skill the call loaded (docs/tools.md, "Skills")
changed_bychanged_bynowhen an after_tool hook rewrote the result
provider_itemany JSONnoon a call the provider ran, its result block exactly as it arrived, sent back unchanged only to the model that produced it (docs/tools.md, "Hosted by the provider"); absent on a call Fiber runs
hosts_surfacedarray of stringsnothe hosts the result surfaced, as URLs, which become known in the session (docs/tools.md, "What a result carries"); absent when empty
loadedarray of stringsnothe tools a search loaded, by name, best first, ties by name; [] when it matched nothing; absent on every other result, and when an after_tool hook failed (docs/tools.md, "Tool search")
protected_pathsobjectnoon a confined shell call that changed a protected path: restored (array of strings, workspace-relative paths restored to the recorded baseline) and failed (array of path and message objects); each failed path is workspace-relative. There is one entry per restore that did not succeed; absent when nothing changed (docs/sandbox.md, "Protected paths")

On a successful read, edit or write, details carries the reserved file_seen object beside the tool's own fields: path, the file's resolved path as a string, and hash, the whole file's content hash as an integer. read logs the hash of the bytes it read; edit and write log the hash of the bytes they stored. A failed call carries no file_seen. The history fold reads only this object (docs/tools.md, "Stale files"): a resume, a fork or a rewind rebuilds what the model's context has seen from it, and only a completed compaction clears it.

A failed model call is an assistant message that completed with a failed outcome and an error; the retry is a new action. Its codes are docs/errors.md, "A failed model call". There is no separate error channel, so no failure is ever reported twice.

On tool_call_completed, error.code lets a consumer treat timeout differently from invalid_arguments or unknown_tool without parsing English. A nonzero exit is failed with code nonzero_exit. Every error code is listed in docs/errors.md. changes is the one tool-neutral account of a change: any tool may set it, so a client shows the counts without knowing which tool ran (docs/tools.md, "What a result carries").

On a confined shell call that changed a protected path, tool_call_completed carries protected_paths, and an adopted shell call's job_completed carries the same object. The terminal folds the warning lines from the field — one row beneath the call, or under the open job's output — and the model receives them through the result text or the completion notice. Resume replays the same lines from the same field, so what the person saw never depends on who rewrote the text (docs/sandbox.md, "Protected paths").

A line whose content a hook changed carries changed_by, naming the extensions that took attribution for the change. A change no extension took attribution for carries no changed_by key. It appears on tool_call_started for rewritten arguments, on permission_requested for the arguments under review, on permission_resolved for a reviewed call's decision that has no request and whose arguments a before_tool hook rewrote, on tool_call_completed for a rewritten result, on job_line for changed delivery lines, on delegate_finished for a changed final message, on job_completed for a changed completion notice, and on a turn_started message and steering_applied for a rewritten message. The line holds what the hook returned; the original is never logged (docs/extensions.md, "Hooks").

A call stopped by Fiber or the user is cancelled, not a signal failure. An interrupt is not a crash.

Approval

permission_requested

Durable. The envelope's action_id is the tool call.

KeyTypeRequiredMeaning
request_idstringyesthe id a reply names
effectsarray of stringsyesas in "Declared effects"
reversiblebooleanyesas in "Declared effects"
pathsarray of stringsnoas in "Declared effects"
always_reviewedbooleannoas in "Declared effects"
confinedbooleannoas in "Declared effects"
stepstringyeswhich step of docs/permissions.md, "The order a call is judged in", raised it: standing_ask (3) or review (7); a closed set
standing_ruleobjectnoon standing_ask, the rule that asked: scope (global or project) and prefix (string)
escalationobjectnoon review, why the reviewer handed the call to a person: cause, which is consecutive_blocks, session_blocks or reviewer_failed, a closed set; reason (string), the reviewer's reason for blocking this call, on the two block causes; error (error), on reviewer_failed
ruleobjectnoon review, the rule an allow can remember: subject (string), the call's primary argument as its tool reads it, and prefix (string), the widening the tool offers, which subject starts with (docs/permissions.md, "What a rule matches"). Absent when no rule can match the call
argumentsobjectnothe arguments under review, when a before_tool hook rewrote them
changed_bychanged_bynowith arguments

permission_resolved

Durable. The envelope's action_id is the tool call.

KeyTypeRequiredMeaning
request_idstringnothe request it answers; absent when the decision raised none
decisionstringyesallow or deny; a closed set
decided_bystringyescredential_deny, person, standing_rule, session_grant, reviewer, no_reviewer, a reviewed call denied when no reviewer could be set up, such as with no reviewer model (no_model; docs/permissions.md, "How it runs"), and no person could answer, budget, a call that needed review once the spend reached budget.usd, denied without another reviewer request (docs/loop.md, "Spending budget"), hook, a call whose request was pending when the session exited, refused by a before_tool hook on resume, stopped by that hook's failure, or stopped because the arguments it rewrote no longer fit the tool, before permission was decided again; reason names the extension, or cancel, the turn cancelled (docs/architecture.md, "Cancellation"), the session closing on close (docs/invocation.md) or a resumed session with nobody to answer, while the request was pending, with reason saying which; a closed set
reasonstringnowhy, in words, such as the reviewer's reason
feedbackstringnowhat the person typed with a denial, which the model receives
grantobjectnoon a person's allow that added a session grant: tool and prefix (strings), the later calls it allows (docs/permissions.md, "What a rule matches")
ruleobjectnoon a person's allow that added a standing rule to the project's rules file: tool and prefix (strings)
reviewerobjectnopresent whenever decided_by is reviewer: model (string, a model reference) and stage (integer, 1 or 2), the stage that decided or, on a reviewer failure, the stage that failed
effectsarray of stringsnoas in "Declared effects", on a reviewed call's decision that has no request_id
reversiblebooleannoas in "Declared effects", with the keys above
pathsarray of stringsnoas in "Declared effects", with the keys above
hostsarray of stringsnoon an allow decided by person or reviewer, the hosts the allowed call declared, which become known in the session (docs/tools.md, "Web fetch and web search", "Effects")
always_reviewedbooleannoas in "Declared effects", with the keys above
confinedbooleannoas in "Declared effects", with the keys above
argumentsobjectnothe arguments the reviewer judged, when a before_tool hook rewrote them, with the keys above
changed_bychanged_bynowith arguments, with the keys above

Both are durable so that a driver reconnecting to an unattended session learns it is blocked on a human rather than hanging on silence, and so that a session that exited on a pending approval can raise it again on resume. request_id is minted like any other id; a reply naming a request that is no longer pending is rejected and does nothing, so a late approval can never authorise a different action.

The full shape of approvals, and what happens with no human present, is docs/permissions.md.

Interactions

interaction_requested

Durable. The envelope carries no action_id; the payload names the calls.

KeyTypeRequiredMeaning
request_idstringyesthe id a reply names
kindstringyesconfirm, select, multi_select, text_input or form; a closed set
action_idsarray of stringsnothe tool calls that raised it: one, or for an MCP elicitation with several calls in flight on its server, each of them (docs/mcp.md, "Elicitation, sampling and roots"); absent when no tool call raised it
extensionstringnothe extension that raised it with host.ask
promptstringnothe question, on every kind but form
optionsarraynoon select and multi_select: each a label (string) and an optional description (string)
fieldsquestionsnoon form, one per question
resumesbooleannotrue when the process may exit with this request pending, and resuming runs the call that raised it again, which raises it again with the same request_id (docs/tools.md, "When a person can answer"); absent otherwise

interaction_resolved

Durable. It carries exactly one answer: declined: true, or the answer keys for its kind, and no others. When a tool call raises an interaction that no one can answer, Fiber writes no interaction_requested, and the interaction_resolved with by fiber and declined: true names a request that was never raised.

KindAnswer keys
confirmconfirmed
selectlabels, one label
multi_selectlabels, possibly empty
text_inputtext
formanswers, and note when the person wrote one
KeyTypeRequiredMeaning
request_idstringyesthe request it answers
bystringyesperson, a client's reply, or fiber, which declines when no answer is possible or the turn was cancelled; a closed set
declinedbooleannotrue when declined
confirmedbooleannothe answer to confirm
labelsarray of stringsnothe chosen options' labels, on select (one) and multi_select
textstringnothe typed answer, on text_input
answersarraynoon form, one per field in field order: { "skipped": true }, or labels (array of strings, possibly empty) with text (string) when the person typed any
notestringnoon form, the person's note on the whole form

These carry every interaction except approval, which keeps permission_requested and permission_resolved because docs/permissions.md fixes their payloads. In a session a person drives, ask_user raises one form per call (docs/tools.md, "Asking the person"). MCP elicitation raises one interaction per field (docs/mcp.md, "Elicitation, sampling and roots"). They are durable for the reasons approvals are, and a reply naming a request that is no longer pending is rejected in the same way. An offer of a repository's code has its own pair too ("Repository code").

Repository code

repository_code_offered

Durable. The offer of everything a repository declares that has no approval for this project and this content, raised before the session's first model request (docs/extensions.md, "Code a repository ships").

KeyTypeRequiredMeaning
request_idstringyesthe id a reply names
itemsarrayyesone per item offered, each: kind (string: extension, hook or mcp_server), name (string), hash (string, the content hash an approval records), required (boolean), summary (string, what an install shows), files (array of strings, sorted workspace-relative paths, possibly empty; absent on older offers), version (string, for an extension), and diff (string, against the newest copy approved before that is still kept, when the content changed since an approval)

repository_code_resolved

Durable. One decision per item, in the offer's order.

KeyTypeRequiredMeaning
request_idstringyesthe offer it answers
decisionsarray of stringsyesper item: approve, skip (for this session) or never; a closed set

Only a person answers an offer, through a client's reply. A model never does, and an extension never does: host.drive sends no answer to an offer, as it sends none to an approval. A session with no client that can answer raises no offer and skips or fails each item instead (docs/extensions.md, "Code a repository ships"). The pair is durable so that a session that exited on a pending offer raises it again, with the same request_id, on resume.

While an offer waits for its answer, the session is waiting: session_status names the offer with kind offer and a summary such as "3 items from the repository", and a process that exits on it names it in fiber_exited.suspended_on. A process stops waiting on an offer at its repository_code_resolved, or at its preamble_built when it went on without an answer after a close.

Usage and notices

usage_recorded

Durable. One per model call, whatever started it. The envelope's action_id is the action the call belongs to; a reviewer's or an extension's call belongs to none.

KeyTypeRequiredMeaning
generation_idstringyesthe provider's id for the generation, on bedrock-converse the response's x-amzn-RequestId (docs/model-routing.md, "Bedrock Converse wire facts"), or an id Fiber mints, starting fiber-, when the provider named none
modelstringyesthe model reference, provider/model
tokenstokensyesthe call's tokens
input_bytesintegeryesthe size in bytes of the request body Fiber sent for the call: the system prompt, tool definitions and messages as serialised for the provider, with the request's settings
input_mediabooleannotrue when the request carried, or tried to carry, an image or a PDF part (an image that could not be read still counts); absent means none
web_searchesintegernohosted web searches, where the provider reports them
costnumber or nullyesin US dollars: the vendor's own figure where it reports one, otherwise the model's declared prices applied to tokens (docs/model-routing.md, "Cost"); null when neither exists; null for an id Fiber minted
subscriptionbooleannotrue when a subscription login covered the call, so cost is an API-price estimate, not money billed; absent means billed per token
extensionstringnothe extension whose host.model made the call
origin_session_idstringnoon a copy, the session whose call it was (docs/delegates.md, "Streams"); absent on the session's own calls
warmingbooleannotrue on a cache-warming refresh (docs/prompt-cache.md, "Warming while idle"); absent on every other call
reviewerobjectnoon a call the reviewer made: purpose (string, a closed set: stage_1, the one-word allow or check request; stage_2, the reasoning pass on a call answered check (docs/permissions.md, "How it runs"); or compaction, the compaction selection) and action_id (string, the tool call under review; absent on compaction); absent on every other call. Present on every call the reviewer makes; the envelope's action_id stays absent, so an action's usage fold doesn't count the review as the call's own spend

quota_noticed

Durable.

KeyTypeRequiredMeaning
providerstringyesthe provider's name
credentialstringyesthe credential label whose quota crossed (docs/model-routing.md, "Credentials")
windowstringyesthe window's name, as the provider reports it, or credit for a credit
percent_usednumberyesthe percent used when the notice was given
resets_atintegernowhen the window resets, where the provider reports it
notice_atnumberyesthe threshold it crossed, quota.notice_at

quota_rearmed

Durable. A window, or a credit as the window credit, that gave a quota_noticed read below quota.notice_at, so its next crossing gives a notice again (docs/tools.md, "The notice"). It is written once per re-arm; a window re-armed by its reset time writes none.

KeyTypeRequiredMeaning
providerstringyesthe provider's name
credentialstringyesthe credential label (docs/model-routing.md, "Credentials")
windowstringyesthe window's name, as the provider reports it, or credit for a credit
percent_usednumberyesthe percent used at the reading below the threshold
notice_atnumberyesthe threshold, quota.notice_at

retry_scheduled

Ephemeral. The envelope's action_id is the failed assistant message.

KeyTypeRequiredMeaning
codestringyesthe failed call's error.code
attemptintegeryesthe attempt about to be made
last_attemptintegeryesthe last attempt the retry policy allows, 1 + retry.attempts
delay_msintegeryesthe wait before it

notice

Ephemeral. A failure outside any action, or a login a person must finish (login_url).

KeyTypeRequiredMeaning
codestringyesan open set (docs/errors.md, "Registry"); a consumer shows the message for an unknown code
messagestringyesFiber's own sentence
extensionstringnothe extension it concerns; absent when a notice groups items from more than one extension

One usage_recorded per model call, whatever started it, however it ended. A call that is cancelled, fails or closes early writes its usage_recorded at once, with the tokens it saw and cost as for any call without the vendor's figure, or null when Fiber minted its id (docs/model-routing.md, "Cost"). A cost that settles late, from the provider's cost(), is a second usage_recorded with the same generation_id, replacing the first. A parent writes a copy of each usage_recorded it receives from a delegate, with the same payload and origin_session_id added, so a session's log holds its whole tree's spend. The fold counts one line per generation_id, the latest, so a copy of a copy is still one call. A late correction in a delegate's log is copied like any other line, so in the parent's log too the correction comes after the copy it replaces, and the latest wins in both. Consumers sum; resume rebuilds the ledger by folding. No pending queue, no watermarks, no reconciliation file.

On 20 completed calls to z-ai/glm-5.3-flash through OpenRouter, streaming and not, cost came inline and equalled the generation lookup, watched through 120 seconds. A completed call carried its final cost inline, so it did not need the second record. One stream closed early carried no cost; the lookup returned one by 30 seconds, and until then the record has cost null.

Preamble

Behaviour is docs/prompt-cache.md.

preamble_built

Durable.

KeyTypeRequiredMeaning
reasonstringyesstart, resume, reload, switch or sandbox; a closed set
modelstringyesthe model reference
context_windowintegeryesthe model's context window, in tokens
trigger_atintegernothe context size, in tokens, at which an automatic compaction runs (docs/compaction.md, "Automatic"); absent when automatic compaction is off
budgetnumbernothe session's budget.usd in US dollars, after every configuration layer and -c (docs/loop.md, "Spending budget"); absent when none is set
thinkingstringnothe thinking level, where the model takes one (docs/model-routing.md, "Thinking")
tool_choicestringyesthe tool choice as sent
cache_lifetimestringyes5m or 1h
credentialstringnothe credential label every later request uses (docs/model-routing.md, "Which credential a session uses"); absent when the provider takes no credential
system_promptstringyesthe system prompt text as sent
toolsarrayyeseach tool as sent: name (string), registered_by (string: builtin for Fiber's own tools, otherwise the name of the extension or MCP server that registered it), deferred (boolean) and definition (object, the definition in the protocol's own shape)
replacedarraynoeach tool registered under a name already taken: name (string), from (string, the registered_by of the tool replaced) and to (string, the registered_by of the tool that replaced it); absent when no tool was replaced

model_changed

Durable.

KeyTypeRequiredMeaning
beforeobjectyesmodel, thinking, cache_lifetime and credential before the switch, as on preamble_built
afterobjectyesthe same keys after it
sourcestringyeswho asked for it: driver or extension, as in "Where a message came from"
extensionstringnothe extension's name, when source is extension

A switch of credential label, by /credential, the credential driver command or --credential on a resume, is a model_changed whose credential differs.

preamble_built follows session_started or fiber_started, reloaded, or model_changed, before the next model request. A fork or a rewind sends the latest preamble_built before its point. preamble_built with reason sandbox follows a /sandbox toggle that changed the setting, with the shell tool's new description; a toggle that changes nothing builds nothing.

Opening message

Behaviour is docs/system-prompt.md.

opening_message

Durable.

KeyTypeRequiredMeaning
environmentobjectyesas below
instruction_filesarrayyeseach file sent, in order: path and content (strings)
extension_sectionsarraynoeach extension section sent, in order, each entry as below; absent when empty
skillsarrayyesthe skills listing, each entry as below
added_directoriesarraynothe session's added folders, resolved, in log order; absent when empty
environment keyTypeRequiredMeaning
datestringyesthe date, YYYY-MM-DD
osstringyesthe operating system, such as linux or macos
archstringyesthe architecture, such as x86_64 or aarch64
shellstringyesthe shell
workspacestringyesthe workspace
gitobjectnopresent in a git repository: branch, a string, or null when HEAD is detached
session_logstringyesthe session log's path
skills entry keyTypeRequiredMeaning
namestringyesthe skill's name
descriptionstringyesits description
pathstringyesthe path of its SKILL.md
sourcestringyesrepository, personal, extension or builtin; a closed set (docs/system-prompt.md, "Skills")
extension_sections entry keyTypeRequiredMeaning
extensionstringyesthe section's extension
filesarrayyeseach section file sent, in order: path and content (strings)
budget_bytesnumbernothe section's byte budget, when the manifest gives one

instruction_file

Durable.

KeyTypeRequiredMeaning
pathstringyesthe file's path
reasonstringyessubdirectory, created, changed, deleted or own_edit; a closed set
extensionstringnothe section's extension, when the file is a section file; absent for an instruction file
contentstringnothe file's content now; absent when deleted
sentstringyeswhat the model was sent: full, diff, deleted, none or stub; a closed set
sizenumbernothe raw byte length read when the line was emitted, present on stub lines for replay; absent on every other line

date_changed

Durable.

KeyTypeRequiredMeaning
datestringyesthe new date, YYYY-MM-DD

skills_changed

Durable. Skills added or removed since the listing was last given, sent at a turn start (docs/system-prompt.md, "Added and removed skills").

KeyTypeRequiredMeaning
addedarrayyeseach skill added, as a skills entry of opening_message
removedarray of stringsyesthe names of the skills removed

skills_resent

Durable. Written after compaction_completed and before the new opening_message when the previous context had loaded skills (docs/compaction.md, "What the model sees after a compaction").

KeyTypeRequiredMeaning
skillsarrayyeseach skill sent again, in the order it was first loaded: name, path and content (strings), the body read from disk at the compaction

opening_message is written at session start and after each completed compaction. Each extension_sections entry records one extension's section with its extension, files and budget. instruction_file with own_edit records the content after the session's own call changed the file, and sends nothing. A diff is rendered from content and the content the model last had, both in the log. The texts are rendered from these payloads.

Compaction

Behaviour is docs/compaction.md.

compaction_started

Durable. Written before the note request. A tool-started compaction makes no note request and writes none.

KeyTypeRequiredMeaning
triggerstringyesauto, person or overflow; a closed set

compaction_completed

Durable.

KeyTypeRequiredMeaning
outcomestringyescompleted, failed or cancelled; a closed set
errorerrornoon failed
notearray of stringsnothe action_ids of the actions carrying the note, in call order
note_textstringnoa note a before_compaction hook wrote, in place of note
extensionstringnowith note_text, the hook's extension
tokens_beforeintegeryesthe context size before the compaction, in tokens
instructionsstringnothe person's instructions, when there were any

context_nudged

Durable.

KeyTypeRequiredMeaning
tokensintegeryesthe context size when the nudge was given
trigger_atintegeryesthe context size at which an automatic compaction runs

The note request is an ordinary assistant message action with its own usage_recorded. compaction_completed points at the note and never copies its text ("Writing"), except a note a hook wrote, which appears on no earlier line. context_nudged is durable because the model saw it; the nudge's text is generated from its payload.

reviewer_kept

Durable. The person's messages the reviewer keeps across a compaction, each with the reply it answered. The agent's new context gets the same messages, without the replies (docs/compaction.md, "What the model sees after a compaction").

KeyTypeRequiredMeaning
keptarrayyesthe kept messages, oldest first, after the window cap: {seq, item} naming the turn_started or steering_applied line holding each message
failedbooleannotrue when the selection request failed, so every earlier person message was kept

Written after a completed compaction when the session has a reviewer (docs/permissions.md, "At a compaction").

A compaction that fails or is cancelled leaves the model's context as it was. A cancelled compaction means the turn was cancelled, by a person or a shutdown, and the turn completes interrupted.

MCP servers

Behaviour is docs/mcp.md.

mcp_server_failed

Durable.

KeyTypeRequiredMeaning
serverstringyesthe server's name
reasonstringyesstart_failed, deadline (missed its startup deadline), not_logged_in or died; a closed set
will_restartbooleanyeswhether Fiber will restart it
errorerroryeswith code mcp_server_unavailable (docs/errors.md, "The shape")

mcp_server_ready

Durable. A server that died is running again after its restart, so a client clears the failure it showed.

KeyTypeRequiredMeaning
serverstringyesthe server's name

reloaded

Durable.

KeyTypeRequiredMeaning
serversobjectyeskept, restarted, started and stopped, each an array of server names
extensionsarray of stringsyesthe extensions reloaded
failedarraynoeach server that failed: server, reason and error, as on mcp_server_failed
extension_failuresarraynoone entry per failing registration: provider, optional extension (present exactly when the mirrored notice names one) and error; the old list stands

reloaded is written once the new tool set is declared, and preamble_built follows it. The next model request misses the prompt cache. A reload that changes the effective sandbox setting writes one notice saying which way it went (Sandbox on after /reload. or Sandbox off after /reload.), after reloaded and before the rebuilt preamble_built.

Extensions

Behaviour is docs/extensions.md.

extensions_loaded

Durable. The full set of extensions the session loaded. Written at each process start, a resume included, before the first model request; again before the process's first preamble_built when its offer approved an extension, which then loads in that process, with no reloaded (docs/extensions.md, "Code a repository ships"); and again after every reload, following reloaded. It always carries the whole set, never a difference; the latest wins, and a summary connection is sent the latest. A client half reads it to decide whether it draws for this session (docs/extensions.md, "Client halves"). It lists a lazy extension from session start, with its version and replaces, whether or not its VM has started.

KeyTypeRequiredMeaning
extensionsarrayyesone object per loaded extension: name (string), version (string) and replaces (array of strings, absent when empty): the built-in tools and commands its manifest lists in replaces, in manifest order, as declared (docs/extensions.md, 'What an extension is')

extension_state_set

Durable.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
keystringyesthe state key
valueany JSONyesthe key's whole new value, at most 64 KiB
on_forkstringyesat_point, latest or fresh; a closed set

extension_state_unset

Durable.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
keystringyesthe state key removed

An unset carries no on_fork. The key keeps the rule of its last extension_state_set: when that rule reads the key after the unset, the new session gets no key.

extension_ui

Ephemeral. One line is one of two variants: extension with status, or extension with widget and lines; never both. The latest status, and the latest of each widget, wins, and a client that attaches is sent them.

Status lines and widgets are data for a client to show or ignore, not interactions (docs/architecture.md, "Asking a human"): they ask nothing and take no reply.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
statusstringnoits status line; "" clears it
widgetstringnoa widget's id
linesarray of stringsnowith widget, its lines; empty removes it

extension_message

Ephemeral.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
dataany JSONyeswhat its session half sent its own TUI extension with host.emit

extension_log

Ephemeral. A line an extension wrote with host.log. The session also records it in its diagnostic log (docs/state.md, "What each part holds"); it is never saved in the session log.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
messagestringyesthe line, as the extension wrote it

extension_exec

Durable. A program an extension ran outside a tool call.

KeyTypeRequiredMeaning
extensionstringyesthe extension's name
programstringyesthe program
argsarray of stringsyesits arguments
cwdstringyesits working directory
processprocessyeshow it ended

extension_hello

Ephemeral. The first line Fiber sends a process extension, with the session's identity, why it started, its workspace, the extension's data directories and its folded state. Sent again after a restart, with the state as it stands in the session. Behaviour is docs/extensions.md ("Process extensions").

KeyTypeRequiredMeaning
session_idstringunless reason is callthe session's id
reasonstringyeswhy the session started: new, resume, fork, rewind, compaction, or call for a provider call outside a session; a closed set
workspacestringyesthe workspace root
data_dirsobjectyesthe paths host.data_dir returns: machine and project path strings
stateobjectyesthe extension's folded state, as state.get reads it

extension_request

Ephemeral. One callback Fiber asks a process extension to run, answered with a driver reply naming its request_id. Stream items, meaning hooks, watcher deliveries and commands, are sent one at a time, each after the reply to the last one; tool calls are sent as they arrive, so several can be outstanding. A reply to a request that is no longer pending is rejected stale_request and changes nothing. Behaviour is docs/extensions.md ("Process extensions").

KeyTypeRequiredMeaning
request_idstringyesthe request the extension answers
registrationstringyesthe registering call command's id
keystringyesthe function's key, or its 1-based position as a string for a positional argument
argsarrayyesthe arguments the Lua function receives, as a JSON array

Extension state is a fold: the latest extension_state_set or extension_state_unset for each extension and key, up to the point being read. A write made inside a hook is written just before the line that hook changed, and is not written at all if the hook fails. Any other write is written at the loop's next drain of its inbox ("One inbox" in docs/architecture.md), so a crash before then loses it.

A fork or a rewind folds its parent's log. For each key, the on_fork of its last write up to the point decides what the new session gets:

on_forkThe new session gets
at_pointthe value as of the point
latestthe value at the end of the parent's log when the new session starts. For a delegate's fork, the end of the parent's log is the fork's point, forked_from.seq, so the first run and every resume get the same values.
freshnothing

Jobs

Behaviour is docs/tools.md ("Background jobs"); delegates are docs/delegates.md.

job_started

Durable. The envelope's action_id is the tool call that started the job; absent when an extension started it.

KeyTypeRequiredMeaning
job_idstringyesthe job's id
toolstringnothe name of the tool that started it
extensionstringnothe extension that started it with host.delegate
descriptionstringyesa short description
output_pathstringyesthe job's output file
pgidintegernothe process group id, when known
start_timeintegernothe leader's opaque process start-time identity, when known
kindstringnojob or detached; absent only on pre-upgrade rows

A detached entry writes job_started with kind: detached. Its pgid records the process group; start_time identifies the leader for same-session stop checks. When it ends, the registry updates its in-memory row, but the loop writes no job_completed line and starts no turn.

delegate_started

Durable. Written after job_started, for each run.

KeyTypeRequiredMeaning
job_idstringyesthe delegate's job
delegate_session_idstringyesthe delegate's session_id; on another harness, the harness's own session id, which Fiber sets before it starts
harnessstringyesthe harness, such as fiber
modelstringyesthe model reference, with any role resolved
workspacestringyesthe delegate's workspace
worktreeobjectnowhen isolated: path and branch (strings)
forked_fromobjectnofor a fork: session_id and seq

job_delta

Ephemeral. Progress for clients, paced as tool_call_delta is.

KeyTypeRequiredMeaning
job_idstringyesthe job
textstringnooutput added since the last delta, at most the newest 64 KiB of it, as on tool_call_delta; the older bytes are in the job's output file
detailsany JSONnoprogress, as on tool_call_delta

job_line

Durable. What a monitor delivered to the model.

KeyTypeRequiredMeaning
job_idstringyesthe monitor's job
linesstringyesthe batch of lines delivered, cut as docs/tools.md, "Background jobs", says
suppressedintegernodeliveries suppressed since the last one, when any were
changed_bychanged_bynowhen a hook changed the delivered lines, and named itself

delegate_finished

Durable. Written just before job_completed, except for a delegate that ended while its parent was gone, whose job_completed the keeper wrote (docs/delegates.md, "Events").

KeyTypeRequiredMeaning
job_idstringyesthe delegate's job
textstringyesthe final message, bounded as docs/tools.md, "Bounded results", says
artifactstringnothe file holding the final message, relative to the session directory that owns it: artifacts/final.md in the delegate's own directory, except when a hook returned artifact text for the finish, then that hook's artifacts/<job_id>.txt in the parent's; absent when no file was written or the harness is not Fiber
artifact_absolutestringnothe final-message file's absolute path, which the wake and jobs wait name; the file holds the final message after the delegate delivery hooks, and on a line a jobs wait, stop or write claimed, text is the message as the delegate wrote it, so it can differ from the file when a hook changed it; absent when the file was not written or the harness is not Fiber; the jobs wait result names the path whenever the claim path attempted the write, so it can name a file that failed to write
questionsquestionsnowhen the delegate's turn ended on ask_user
usageusageyesthe run's totals
changed_bychanged_bynowhen a hook changed the final message, and named itself
worktreeobjectnowhen isolated: path and branch (strings) and dirty (boolean)

job_completed

Durable.

KeyTypeRequiredMeaning
job_idstringyesthe job
statusstringyescompleted, failed or cancelled; a closed set
errorerrornoon failed
processprocessnofor a job that ran a process
output_tailstringnothe tail of its output, capped; absent when a hook changed the completion notice (notice holds what the model was sent)
noticestringnothe text the model was sent, when a hook changed or withheld the completion notice
changed_bychanged_bynowhen a hook changed the completion notice, and named itself
protected_pathsobjectnoon an adopted shell call that changed a protected path: restored (array of workspace-relative paths) and failed (array of path and message objects). Each failed path is workspace-relative, with one entry per restore that did not succeed, as on tool_call_completed; absent when nothing changed (docs/sandbox.md, "Protected paths")

jobs_pending_notified

Durable.

KeyTypeRequiredMeaning
job_idsarray of stringsyesthe jobs named in the notice
reasonstringyesending, the ending notice (docs/tools.md, "Background jobs"), or unattended, the jobs check (docs/invocation.md, "Lifecycle"); a closed set

Either notice starts a turn whose input is one message item with source fiber, carrying the notice's text. The request is built from that text. jobs_pending_notified is the first line after that turn's first step_started, and it adds nothing to the request.

A delegate's session_id is on delegate_started, and delegate_finished is keyed by job_id, as job_line is (docs/delegates.md, "Events"). There is no job-kind field: tool identity is an opaque name (docs/tools.md).

job_line is durable because the model saw it, and resume must rebuild what the model saw.

job_completed has no denied: the starting call is what gets denied. error.code values defined here are nonzero_exit and timeout (as on tool_call_completed), signal (a process killed by a signal Fiber did not send), indeterminate, orphaned, keeper_timeout, flooded, and output_cap. The output tail is the first time those bytes enter the log, unless a hook changed the notice.

Only the loop thread writes durable events, and it drains its inbox at step boundaries (docs/architecture.md, "One inbox"), so job_completed and job_line are written at the step boundary where the model receives them. Their position in the log is the delivery point. The exception is a job_completed the keeper writes while its session is gone, which carries no output_tail, notice or changed_by: its delivery point is the next turn's turn_started (docs/tools.md, "The keeper"). The keeper also appends keeper_started when its takeover opens the log and keeper_bound once bind and listen succeed, only on a crash takeover, never on the normal path.

keeper_started

Durable. The payload is {}. The keeper appends it when its takeover opens the session's log, before it binds; only on a crash takeover, never on the normal path (docs/tools.md, "The keeper").

keeper_bound

Durable. The payload is {}. The keeper appends it once bind and listen succeed on its socket; only on a crash takeover, never on the normal path (docs/tools.md, "The keeper").

Command acknowledgements

Every driver command is answered with exactly one of these, echoing its id (docs/invocation.md, "Driver commands"). Both are ephemeral.

command_accepted

KeyTypeRequiredMeaning
command_idstringyesthe command's id
resultobjectnoon the commands in the table below; absent for every other command
Commandresult keys
rewindnew_session_id (string), the session that continues this one
change_workspacenew_session_id (string), the session that continues this one
toolstools, an array with one object per declared tool: name (string), source (builtin, extension or mcp), server or extension (string, the tool's server or extension, when not built in), tool (string, the server's own name for the tool, when the source is mcp), state (full, deferred or loaded), bytes (integer) and tokens (integer, estimated, absent before the first request) (docs/tools.md, "Seeing the tools")
hookshooks, an array with one object per hook and watcher the session registered, hooks first in hook-point table order and run order, then watchers in registration order: for a hook extension (string, hooks for a declared entry), entry (string, only for a declared entry), point (string), on_failure (blocking or non-blocking) and phase (string, only when declared), with kind hook; for a watcher extension (string, hooks for a declared entry), entry (string, only for a declared entry) and kinds (array of strings), with kind watcher (docs/invocation.md, "What each command does")
mcp_serversservers, an array with one object per configured server: name (string), layer (string: global, project or repository), state (string: not-started, ready, failed or needs-login), reason (string, the failure's sentence, empty when the server did not fail), tools (integer, its tool count, absent while not-started), approved (boolean, false only on a repository's server nobody approved) and auth_url (string, the login URL, only while a login waits) (docs/mcp.md, "Servers, their state and the per-server commands")
commandscommands, an array with one object per /name the session runs: name (string), description (string), argument_hint (string, the skill's argument-hint or an MCP prompt's arguments, absent when it has none) and tag (string: skill, template, the extension's name, or the MCP server's name) and extension (boolean, true on an extension's command, absent otherwise) (docs/invocation.md, "What each command does")
skillsskills, an array with one object per skill discovery found, switched-off and shadowed ones included: name (string), description (string), path (string, its SKILL.md), source (repository, personal, extension or builtin), extension (string, the extension's name, only when source is extension), model_invocable (boolean, false for a skill with disable-model-invocation and for one in an extension's prompts/), disabled (boolean, true when skills.disabled names it), shadows (array of strings, the SKILL.md paths of the skills it shadows) and shadowed_by (string, the winning skill's SKILL.md path, only on a shadowed skill) (docs/invocation.md, "What each command does")
quotaquota, an array ordered by provider name, then credential label, and notice_at (number, the session's quota.notice_at). Each object has provider and credential (strings), and either windows (a non-empty array in vendor order: name and either percent_used (number) or reset: true, with optional resets_at (integer, milliseconds since the epoch) where the provider reports a reset time), credit (remaining (number) and optional limit (number)), or neither when unreachable. unreachable: true marks a failed fetch with its last value, or a failed credential read or provider start with no value. Labels that report no quota or have no cached value yet are absent. No age is shown (docs/tools.md, "Fetching").
credentialsprovider (string), the provider a credential command would switch now; credentials, an array of its credential labels, sorted; credential (string, optional), the label it uses now, absent for a scripted session or a provider the session has not used
credentialprovider (string), the provider the switch applies to (docs/invocation.md)
subscribeat full, last_seq (integer), the seq of the last line the fold sends before the stream goes live; result is absent on an empty log or at summary; workspace_gone (string), the missing workspace or repository path, present only when the hub replays the log of a session whose workspace is gone and cannot be made again (docs/invocation.md, "Lifecycle")
historylines, an array of the session's durable lines in the range asked for, each a whole line as the log holds it, in seq order
artifact_pagetext (string), the page, whole lines from offset; lines (array of integers), the byte offset in the file where each line of text starts; next (integer), the byte offset after the page, absent at the end of the file; and size (integer), the file's size in bytes
offered_filetext (string), the file's full UTF-8 text
importimported (object with mcp_servers, skills, commands and instructions, arrays of the names the import copied) and left_behind (array with one object per item not copied: item and reason strings) (docs/configuration.md, "Importing")
shellwith send false, output (string), artifact (string, when cut) and process (process), as on shell_command; with send true, result is absent
propose_notesevidence (array: kind, text, and on session prefix, count, here, and on allows subject, count, here), proposed (array: text, cites), error (error, optional)
startsession_id (string), the session the hub started, over the hub (docs/invocation.md, "The hub")
pairing_codecode (string), a new single-use pairing code, over the hub (docs/invocation.md, "Remote clients")
pairdevice (string), the paired device's name, and token (string), its device token, over the hub's port (docs/invocation.md, "Remote clients")
devicesdevices, an array sorted by name, with one object per paired device: name (string), paired_at and last_connected_at (integers, milliseconds since the epoch; absent when the record lacks them), over the hub (docs/invocation.md, "Remote clients")
recentsessions, an array of recent.jsonl rows, newest first, at most 50, delegates skipped (docs/state.md, "What each part holds"), and total (integer), the number of rows the pages list for project (every project when absent), whatever before and the page hold, over the hub (docs/invocation.md, "The hub")
sessionslive, an array with one object per running top-level session: session_id (string) and status, its latest session_status payload; and exited, an array of recent.jsonl rows, newest first, delegates and running sessions left out (docs/state.md, "What each part holds"), over the hub (docs/invocation.md, "The hub")
prompt_historyprompts, an array of prompt history lines, newest first, each a whole line as history.jsonl holds it (docs/state.md, "What each part holds"), at most 256; and before (integer), the byte offset where the oldest returned line starts, present only when older lines remain, sent back to read the next page, over the hub (docs/invocation.md, "The hub")
read_filedata (string), the file's bytes in standard base64, and mime_type (string), its media type from the file name's extension, application/octet-stream when Fiber does not know it, over the hub (docs/invocation.md, "A session's files")
configurethe operation's result from docs/invocation.md, "What the hub speaks"; absent for set_reviewer, switch_tool and switch_skill
read_configtext (string), the configuration file's UTF-8 text, and version (string), its content version, over the hub (docs/invocation.md, "What the hub speaks")
read_workspace_filetext (string), the workspace file's UTF-8 text, and version (string), its content version, over the hub (docs/invocation.md, "What the hub speaks")
search_filesrows (array of at most 50 strings) or error (string), the file panel's result on the hub's machine (docs/invocation.md, "What the hub speaks")
device_loginurl and code (strings), the provider's device-code step on the hub (docs/invocation.md, "What the hub speaks")
device_login_resultpath (string), the stored credential relative to the hub's Fiber home (docs/invocation.md, "What the hub speaks")
directoriesdirectories, an array of strings, the names of the subdirectories the path holds, sorted, and path (string), the absolute path listed, ~/ expanded, over the hub (docs/invocation.md, "The hub")
statusrunning (boolean, always true), fiber_version (string), clients (integer, the open connections, the asker included) and variables (object, as session_started carries it: the environment sessions the hub starts now get), over the hub (docs/invocation.md, "The hub")
stopsessions_stopped (integer, the sessions that confirmed closed) and keepers_stopped (integer, the keepers that confirmed stopped; absent on old hubs and read as zero), with sessions true; result is absent without sessions, over the hub (docs/invocation.md, "The hub")
stop_keeperskeepers_stopped (integer, the keepers that confirmed stopped), over the hub (docs/invocation.md, "What the hub speaks")
placeholder_envvalues (object, the hub's captured value by requested placeholder name, absent names omitted, never logged), over the hub (docs/invocation.md, "What the hub speaks")
callvalue (any JSON value, absent when the call returns nothing), what the Lua call returns (docs/extensions.md, "Process extensions")

command_rejected

KeyTypeRequiredMeaning
command_idstringnothe command's id; absent when the line was malformed and carried none that could be read
codestringyesthe rejection code (docs/invocation.md, "Driver commands")
messagestringyesFiber's own sentence
heldarray of stringsnoonly on a hub delete refusal with code: session_held: every session in the confirmed set whose lock another process holds, in check order; other session_held refusals omit this field. The refusal's message keeps its existing single-session wording (docs/invocation.md, "Deleting and pruning").

A workspace move to the folder the session is already in answers:

{"kind":"command_rejected","session_id":"s_aaaaaaaaaaaaaaaa","ts":0,"schema_version":1,"payload":{"command_id":"c_cd","code":"invalid_arguments","message":"already in that folder"}}

Hub feed

keepers

Ephemeral. The hub feed's keeper set, for a client that counts the keepers of gone sessions: every keeper-held run/ entry the hub's probe confirms, in id order, empty when none. Written when the set changes, and once to every new feed subscriber; the latest wins.

KeyTypeRequiredMeaning
keepersarray of stringsyesthe keeper-held session ids, in id order; empty when none

Resume

A session is reconstructed from the log and its configuration, nothing else.

Open scans the file into an offset table, reading each line's kind and seq and refusing a complete line that is not JSON. It fully parses only the latest-wins kinds, the pending offer's repository_code_offered and repository_code_resolved, and the lines the rate fold reads. Only the window a consumer actually needs is otherwise parsed. The model's context, the TUI's viewport and any search are three residency policies over one primitive: a range read by seq. A compaction shortening what the model sees must not shorten what a person can scroll back to.

What the reader can tell about work that was in flight, from the log alone:

What the log showsWhat it means
tool_call_requested, no tool_call_startedprovably never ran; safe to run or discard
tool_call_requested with provider_itemthe provider ran it; Fiber never reviews, runs or answers it on resume
shell_command_started, no shell_commandthe session ended before the run's end was written: the process died, or the run outlived the shutdown's last drain; Fiber never re-runs it, and nothing from it joins the next turn's input
tool_call_started, no tool_call_completeduncertain; Fiber never re-runs it, and the model is told its outcome is unknown, unless a fiber_exited with suspended_on names an interaction_requested with resumes: true that call raised: the call was waiting on the person, and resuming runs it again, with no second tool_call_started, so it raises the request again
tool_call_completedran, with its outcome
non-detached job_started, no job_completed, no keeper answersthe job's keeper died, or the session had none; on open Fiber writes job_completed with status: failed and error.code: orphaned, except for a Fiber delegate whose own log's latest run holds fiber_exited, which is settled from it
non-detached job_started, no job_completed, the keeper answersthe job is still running under the keeper; the resumed session takes it back (docs/tools.md, "The keeper")
detached job_started, no later job_completedFiber restores a live process group with a recorded process-group ID before exposing tools. A contradicted identity, missing ID or dead group is dropped silently; a missing or unreadable leader identity stays listed and requires review to stop. Detached jobs are not orphan-completed, and their in-memory end writes no synthetic job_completed or completion notice (docs/tools.md, "Background jobs")
job_completed written while the session was gonethe keeper wrote it; the model is sent it with the next turn
turn_started, no turn_completedthe turn was cut short; render what was logged and say so, unless a fiber_exited with suspended_on follows, in which case the turn resumes with the request raised again
fiber_started, no fiber_exited, rewound or moved after itthat process died rather than exited
rewound or moved lastthe session continued elsewhere
compaction_started, no compaction_completedthe process died during a compaction; the compaction did not take effect, and the model's context is what it was before it

A resume takes the log back from the keeper before it opens the log (docs/tools.md, "The keeper"), so a non-detached job the keeper ran is either completed in the log or still running. On open, Fiber writes orphaned only for a non-detached job no keeper accounts for, and does not touch any process: with no keeper, Fiber cannot know whether the job finished or still runs, and the status is not cancelled. Detached rows are selected separately by their kind and re-probed; Fiber never writes an orphan completion for them.

Fiber re-runs no call a crash left without a result, even one that only reads. The turn it belonged to ended with the crash, so a re-run would answer the earlier call with a later result, and a call that only reads, such as a search across a large repository, can still be slow. The model is sent that the outcome is unknown (docs/loop.md, "What the model is sent") and may make the call again.

Partial assistant text from an interrupted response is gone, because deltas are ephemeral. The log does not pay to store text a completion would supersede.

An attempt count is derived by counting assistant_message_started lines, never from a stored counter, so it cannot drift from the record. A client that shows which attempt a model call is, such as the terminal's "attempt 2 of 4", counts the assistant_message_started lines of the request's retries in that step. The count starts again at each step_started, each compaction_started, whose note request is its own, and each assistant_message_completed whose outcome is completed.

Rewind

A session is a line. seq is its only position: there is no tree, no leaf and no event that moves a position. The evidence is research/rewind.

A rewind starts a new session that continues an existing one from an earlier point. A person starts one from the terminal, a driver with the rewind command (docs/invocation.md).

The model does not rewind. For planned speculative work it uses delegate_fork, with isolation: worktree where files matter. For an unplanned dead end it compacts: it restarts its own context from a note it writes. How a compaction works is docs/compaction.md.

Change workspace

A session moves to another folder by starting a new session that continues it there. A person moves with /cd <path> in the terminal, a driver with the change_workspace command (docs/invocation.md).

Writing

Fsync the record of a side effect after it happens and before causing the next one. Three exceptions, all because the effect costs money or touches the world: tool_call_started is fsynced before the tool runs, assistant_message_started before the model request is sent, and shell_command_started before the command starts. Two fsyncs bracket each effect, so a quiet text turn costs two. step_started records no effect and is flushed with the step's first fsync.

No line restates the content of an earlier line in the same turn. This is part of the durability rule, not an optimisation. A per-step line that carries steps 1..N makes the log quadratic in tool calls within a turn; measured on the Zig implementation, a 429-call turn wrote 412 MB and peaked at 2.1 GiB RSS, where per-action lines carry the same information written once each. Any future line that summarises the turn so far reintroduces this, so it needs this decision overturned first. The one restatement in the contract, the final text on fiber_exited, sits outside any turn and is never read back.

extension_state_set writes a key's whole value each time, so an extension that rewrites a growing value on every step would bring the quadratic log back within its own key. The 64 KiB cap bounds each line, and a value that grows with the session, such as one record per turn or per delegate, belongs under one key per record (docs/extensions.md, "Extension state").

A torn tail is discarded. A reader stops at the last complete line and a writer truncates a partial line before appending, so a power cut cannot make a session unopenable.

One writer at a time, enforced by a lock file. The writer is the session process, or its keeper while the session is gone (docs/tools.md, "The keeper"), and the lock passes between them only by the keeper's handover. A second Fiber process opening the same session refuses and names the holder, plainly, rather than hanging or corrupting the log; one that finds the session's keeper holding the lock takes the handover instead. Readers need no lock at all: append-only plus "stop at the last complete line" is the whole protocol.

The session directory

~/.fiber/projects/<key>/sessions/<session_id>/
  events.jsonl     the log
  session.lock     one writer
  artifacts/       bytes too large to inline

Nothing else. A directory is a session when its log parses and begins with session_started; no marker file can outlive the thing it marks. Listing sessions reads the logs — 601 session files' first lines took 39 ms warm on macOS arm64, so there is nothing for an index to save yet. Fiber writes no derived database; where the directory lives and how projects are keyed is Fiber home. Any future derived store is derived from the logs, rebuildable, and never the truth.

Versioning

One integer schema_version on every line, shared by durable and ephemeral, never negotiated at startup — a line read by a client of another Fiber build has to be readable on its own. It stays 1 until the first release: before then there are no readers to break, so the rules below apply from that release on.

Before 1.0 there are no migrations: a session written against an older version may fail to open, because there is no installed base to strand. From the first release, every breaking bump ships a migration that upgrades an older log when Fiber opens it, plus its test. Fiber then reads exactly one version, so reader branches never accumulate.

Testing

A test asserts on what a consumer sees: the lines and the file left behind. A test that reaches inside Fiber to check an emitter was called proves nothing about the stream, and the central invariant — durable output equals the log, byte for byte — is not even expressible from in there.

The numbers quoted on this page were measured on the archived Zig implementation. They justify the rules; they are not Fiber's budgets. Fiber measures its own, on Linux (docs/performance.md), because the fsync cost that drove the write path is 25–53% of turn wall time there and under 3% on macOS.