Fiber home
The one directory where Fiber keeps everything it writes outside a repository.
Default ~/.fiber on macOS and Linux; FIBER_HOME relocates all of it.
~/.fiber/ Fiber home
config.json global configuration (docs/configuration.md)
config/<extension>.json an extension's global settings
rules global standing rules
AGENTS.md global instruction file (docs/system-prompt.md)
SYSTEM.md replaces Fiber's system prompt text
APPEND_SYSTEM.md appended to the system prompt
projects/<key>/ one per project
sessions/<id>/ events.jsonl, session.lock, artifacts/
history.jsonl prompt history, append-only
rules this project's standing rules
SYSTEM.md, APPEND_SYSTEM.md this project's system prompt files
config.json this project's configuration
config/<extension>.json an extension's settings for this project
worktrees/<id>/ one git worktree per session that asked for one
worktrees/<id>.lock its lock file, held while a process runs in it
protected-paths/ the protected-path baseline and its two locks (docs/sandbox.md)
approvals/<content-hash> one file per extension or hook approval or never
servers/<content-hash> one record per MCP server copy this project approved
data/<extension>/ an extension's data for this project
extensions/<name>/ installed extensions, one directory each
docs/ Fiber's docs for the installed version (docs/releasing.md)
docs/skills/<name>/ a built-in skill (docs/system-prompt.md)
themes/<name>.json a theme (docs/tui.md, "Themes")
pinned/<content-hash>/ approved copies of code a repository ships
pinned.json size, modification time and hash of each declared path
data/<extension>/ an extension's data for this machine
approvals/<content-hash> one file per MCP server approval or never
credentials/<name>/<label> one file per stored provider credential, mode 0600
credentials/<name> one file per extension secret, mode 0600
credentials/hubs/<name> one device token per hub this client paired with, mode 0600
credentials/mcp/<url-hash> one OAuth token per remote MCP server URL, mode 0600
hub/devices/<device> one record per device paired with this hub: name, when, token hash
run/<session_id> one local socket per running session
run/hub the hub's local socket
recent.jsonl recently exited sessions, a rebuildable index
cache/models/<provider>.json discovered model list
cache/mcp/<server>.json an MCP server's last tool and prompt lists, and whether it offers resources
cache/images/<session>-<file> an image the terminal opened in the system viewer (docs/tui.md, "Images")
crashes/<id>-<ms>.txt one report per panic (docs/code-quality.md)
logs/hub.log, logs/hub.log.1 the hub's diagnostic log and its previous file
logs/<kind>-<id>.log one other process's diagnostic log
detached/d_<pid>_<n>.log one output log per detached shell command, mode 0600, kept until the person deletes it (docs/tools.md, "Background jobs")
Override
One environment variable, FIBER_HOME, relocates all of Fiber home. It must
be an absolute path. An empty or relative value is a startup error, code usage,
naming the variable; Fiber never falls back to ~/.fiber. A supervisor that meant to
isolate a run and passed an empty value by mistake would otherwise silently
share the person's real sessions and credentials.
A missing directory is created, mode 0700. Two Fiber processes share state only by being given the same Fiber home. There is no second, narrower override.
Fiber home is one root under the home directory: no XDG split, no
~/Library.
One person owns one Fiber home. There are no group permissions and no multi-user sharing.
Projects
A project is a git repository, identified by git's shared directory (the common dir). Every worktree of a repository is one project; a separate clone is a different project. Outside a git repository, the launch directory is the project.
~/work and ~/work/fiber and ~/work/lens are three projects.
~/work/fiber and its worktree ~/work/fiber-wt1 are one project. Two clones
~/work/fiber-clone1 and ~/work/fiber-clone2 are two projects.
Clones are never unified. Fiber does not key by remote URL: a clone can have no remote, several, or a changed one. Sessions, prompt history and per-project standing rules are kept per project.
The key is a readable slug of the project's identity path — git's shared
directory, or the launch directory outside git — after resolving symlinks.
Every / becomes -. Git shared directory /Users/alice/work/fiber/.git
becomes -Users-alice-work-fiber-.git. Launch directory /Users/alice/work
becomes -Users-alice-work.
A slug can collide (/a-b and /a/b both become -a-b). That is harmless:
the key is only a name for humans. session_started records the exact
workspace, and the worktree's repository when Fiber made one, and lookup
checks the repository when recorded and the workspace otherwise. The log stays the truth
(ADR 0001).
Sessions and resume
Launched anywhere inside a repository — any subdirectory, any worktree —
Fiber finds that repository's project by asking git for its shared directory,
so resuming from docs/ or from another worktree just works. Outside git,
only the exact launch directory counts.
A resumed session keeps the workspace recorded on its session_started.
Resuming from elsewhere never moves or narrows it. A moved repository or
directory leaves its old sessions under the old key.
The session directory is unchanged from docs/events.md:
~/.fiber/projects/<key>/sessions/<session_id>/
events.jsonl the log
session.lock one writer
artifacts/ bytes too large to inline
The full output behind a bounded tool result goes in that session's
artifacts/.
A fork's, rewind's or workspace move's history follows forked_from on the
child's session_started (docs/delegates.md, "Forks"; docs/events.md,
"Rewind" and "Change workspace"). When forked_from.project is present, it
names the parent's project key and the reader opens
projects/<project>/sessions/<session_id>/ directly. When it is absent, the
parent is in the child's project. A missing parent fails closed; readers do
not scan other projects.
Deleting a session a fork, rewind or workspace move points at is refused
unless the person asks for those sessions to be deleted too
(docs/invocation.md, "Deleting and pruning"). For a cross-project move,
delete and prune read the parent's final moved event: workspace resolves
the child's project key, and new_session_id names the child. Nothing deletes
a session on its own, except a session that never got a prompt, which
deletes its own directory as it exits (docs/invocation.md, "Lifecycle").
What each part holds
Standing rules. A global file at the top level of Fiber home and the
project's rules file. Per-project rules live in Fiber home, never in the
repository, so cloning a repository can never grant it permissions — the same
reason docs/model-routing.md refuses project config that declares a
provider.
Extensions. Installed extensions live at extensions/<name>/, one
directory each. The <name> is the extension's short name when it has one
(docs/extensions.md, "Names"), so the memory extension lives at
extensions/memory/. Any other extension's <name> is its git address or
local path, slugged the same way as project keys. The two never collide: a
slugged git address keeps its host's dot (github.com-…), a slugged local
path starts with -, and a short name has neither. Installing or updating writes a fresh directory
and renames it into place; a running session keeps what it already loaded.
Docs. docs/ holds Fiber's documentation for the installed version:
docs/user/ for a person using Fiber, and the rest for how Fiber works,
including the extension API and the built-in skills in docs/skills/
(docs/system-prompt.md, "Skills"). install.sh and fiber update write it from
the release's docs archive, so it always matches the binary
(docs/releasing.md). Nothing else writes it. The system prompt names this
path (docs/system-prompt.md).
Extension data. Each extension has two data directories: data/<name>/
at the top of Fiber home for what it keeps per machine, and
projects/<key>/data/<name>/ for what it keeps per project. <name> is
the extension's directory name in extensions/, so the memory extension's
store is data/memory/. Fiber hands both paths to the extension and
creates each the first time the extension writes there. A memory system or
an index lives here. A write of Markdown files here takes the permission
fast path (docs/permissions.md, "Fast paths"). Nothing in them is session state, so a rewind or fork
never touches them (ADR 0001).
fiber extension remove deletes an extension's data directories too, asking first in a
terminal.
Pinned copies. When a person approves code a repository ships, Fiber
copies it to pinned/<content-hash>/: an extension's whole package, with its
dependencies and what its install step built, or the files a hook or an MCP
server declaration names. Sessions run the copy, never the repository's files.
Approving a server declaration also writes a project record at
projects/<key>/servers/<content-hash>, naming this project as one that
approved that copy. Every approved version is kept until no worktree's files match it, when
fiber sessions prune removes it (docs/extensions.md, "Code a repository
ships"; docs/invocation.md, "Deleting and pruning"). pinned.json records each declared path's size, modification time
and hash, so a session hashes a file again only when one of the first two
changed. It is an index: deleting it costs a re-hash and nothing else.
Import receipts. import-claude-code.json and import-codex.json at
the top of Fiber home record one completed import each: the source, the time
and the counts (docs/configuration.md, "Importing"). Deleting one means
the next fiber import for that source runs again.
Approvals. One file per decision about code a repository ships, named by
the content's hash; it says whether the decision is approve or never.
Deleting it withdraws the decision, and the next session offers the code
again. An extension's or a hook's is per project, at
projects/<key>/approvals/<content-hash>, as its install is. An MCP server's
is per machine, at approvals/<content-hash>, so a declaration approved in one
repository is not asked about again in another (docs/mcp.md, "A repository's
servers"), and each approving project also holds a record at
projects/<key>/servers/<content-hash>, written when the approval is. A never
writes no project record, and removes one an earlier approval left. Only a
changed declaration or files, or a deleted record, offers approved content
again, so a server copy approved before the project record existed has no
record, and stays until a new approval writes one. A repository can neither write nor read them.
Credentials. One file per stored provider credential at
credentials/<name>/<label>, one per credential label, and one file per
extension secret at credentials/<name>, and one file per remote MCP
server's OAuth token at credentials/mcp/<url-hash>, named by a SHA-256 of the
server's canonical URL and recording that URL,
each mode 0600,
in 0700 directories. There is no OS keychain. OAuth refresh takes a
lock on the credential file (docs/model-routing.md). Every tool call
touching credentials/ is refused
(docs/permissions.md).
Cache. cache/ holds only what is always safe to delete;
rm -rf ~/.fiber/cache is a documented safe reset. Today it holds each
provider's discovered model list, one file per provider at
cache/models/<provider>.json, fetched and replaced whole, and each MCP
server's last tool and prompt lists and whether it offers resources at cache/mcp/<server>.json, keyed by a hash
of the server's declaration (docs/mcp.md, "Starting servers"). A writer replaces
a file by rename, so two sessions refreshing one list leave one whole file.
Crash reports. crashes/<session_id>-<ms>.txt holds one panic's
message, thread name and backtrace, named by the process id instead when the
process has no session id, written by the panic hook before the
process aborts (docs/code-quality.md, "Panics"). A report describes a bug
in Fiber, not a session, so nothing reads one to decide anything, and
deleting them is always safe. fiber doctor names the newest one, and
fiber feedback copies a session's reports into its report with the panic
message left out ("What feedback reads" below). They are pruned with the diagnostic
logs.
Diagnostic logs. logs/ records what happens outside any session, where
no session log could hold it. It is always on, because the failures it exists
for, such as a startup error, happen before anyone would think to turn a log
on. Each process writes its own file, so every file has one writer, as a
session log does: the hub writes logs/hub.log, and any other process that
has something to record writes logs/<kind>-<id>.log, where <kind> is
session, ask, tui or cli and <id> its session id once its session log
exists, or its process id until then, except a signal before Fiber starts writing fiber_started, which stays pid-named with no session_id. A cli process, a Fiber command that runs once with no session such as fiber mcp login, is always named by its process id, and its lines carry no session_id.
Each line is one JSON object: ts, level (error, warn, info or
debug), process (hub, session, ask, tui or cli), session_id when one
is known, code and message, one sentence, and on a debug line data,
an object of named values. For a failure, code is its code from
docs/errors.md. For one of the hub's operations it is the operation's name.
This shape is a contract: a program that forwards these lines elsewhere reads
these fields.
diagnostics.level (docs/configuration.md, "Keys") sets how much is
recorded. At "info", the default, a process writes only the error, warn
and info lines below. At "debug" it also writes debug lines; error,
warn and info lines keep their shape and carry no data. A process reads
the level when it starts, so a changed value reaches new processes only. A
debug line holds no credential, token, header value, prompt, model text, tool
argument or configuration value. A websocket connection to a hub is not a
request and writes no http_request line.
What is recorded:
- At
debug, model-list lifecycle stages:models_read_donewhen atui-modelsread returns,models_appliedwhen the event loop applies its result, andmodels_ask_startedwhen a queued read starts. Theirdataholds only the askkind(cachedorstale), the successful read'slistscount, or the appliedcatalogue_size; a failed read has no list count. They never hold provider names, model ids or configuration values. - Failures with no session to hold them: a startup error such as
config_invalid, a signal that arrives beforefiber_started, a shutdown that reaches its kill point (docs/invocation.md, "Shutdown"), and a background refresh, such as a quota or model list, that fails while no session is running. - An extension's
host.loglines: each is a line in the session's file withprocesssessionorask,codeextension_log, the extension's name and the message as the extension wrote it. - The hub's operations:
hub_startedandhub_stopped;environment_built,infowhen the login-shell capture succeeded andwarnwith the reason it failed (docs/invocation.md, "A session's environment");client_connected,client_disconnectedandclient_unauthenticated;;device_pairedanddevice_revoked, naming the device and the client that acted;session_startedandsession_resumed, naming the session and the device that asked. - At
debug, a native model call's request: onehttp_requestline when the call ends, withpurposemodel_call.dataholdsprovider,model,host(the authority without userinfo),path(no query string or fragment, percent-decoded),statuswhen a response came,attemptfrom 1,request_bytesas posted,response_bytesas read, andheaders_ms,first_token_msandtotal_ms, whole milliseconds from the send. A retried call writes one line per attempt; a request never sent writes none. - At
debug, a Lua provider's HTTP requests: onehttp_requestline when the request ends, withpurposemodel_listformodels(),quotaforquota(),token_refreshforcredential(), andcostforcost().dataholdsprovider, the provider's registered name,statuswhen a response came,attempt(always 1: a Lua invocation makes no retry),request_bytesas posted,response_bytesas read, andheaders_msandtotal_ms, whole milliseconds from the send. A body read that fails keeps the status, the headers and the bytes read before the failure. A request that validation rejects before sending writes no line; one that fails after writes one withoutstatusorheaders_msand with zero response bytes. No other field is recorded, and never a host, path, model, URL, query string, credential, header value, body or token, as for every line inlogs/. - At
debug, any other Luahost.httpcall: the rule is where the call is made. Inside a provider function the request records that function's purpose, as above; anywhere else — a hook, command, timer, tool, watcher, search, effects or delegate target, or the entry script — it records onehttp_requestline withpurposeextensionand the extension's registered name inextension, with the same attempt, timing and byte rules and nohostorpath. The rule applies to process extensions alike: a process extension'shost.httpis treated as made inside that request's callback, so it records the callback's purpose.sign()makes no request and writes none. - At
debug, whatweb_fetchfetched: onehttp_requestline per actual HTTP request, each redirect hop included, withpurposeweb_fetch.dataholdsstatuswhen a response came,attempt(always 1),request_bytes0,response_bytesas consumed, andheaders_msandtotal_ms, whole milliseconds from that request's send. A refusal or a body read that fails keeps the status and the bytes consumed; a failure after the send but before a response head writes one line withoutstatusorheaders_msand with zero response bytes; a request never sent writes none. - At
debug, every HTTP request the MCP client makes: onehttp_requestline per POST the transport sends, and one per GET or DELETE it sends, withpurposemcp— the streamable transport, login, discovery and token refresh alike.dataholdsstatuswhen a response came,attempt(always 1),request_bytesas posted,response_bytesas consumed, andheaders_msandtotal_ms, whole milliseconds from the send. A failure after the send writes one line withoutstatusorheaders_msand with zero response bytes; a request never sent writes none. No other field is recorded, and never a provider, model, host, path, URL, server name, credential, header value or token, as for every line inlogs/. - At
debug, an extension release check: onehttp_requestline per actual HTTP request, including each redirect hop, for tag lookups, checksums and binary downloads, withpurposeextension_release.dataholdshost(the authority without userinfo) andpath(no query string or fragment, percent-decoded), a release path holding a tag and an asset name and no secret, plusstatuswhen a response came,attempt(always 1),request_bytes0,response_bytesas read, andheaders_msandtotal_ms, whole milliseconds from the send. A manifest-declared binary URL omitspathand keepshost, because its path may identify a private asset. Post-send failure and body-read rules are the Lua provider's. - At
debug, the hub's memory and disk I/O: aresourcesline just before eachhub_stopped.dataholdspeak_kibandcurrent_kib, peak and current memory, anddisk_read_bytesanddisk_write_bytes, storage the process has read and written since it started:VmHWMandVmRSSfrom/proc/self/statusplusread_bytesandwrite_bytesfrom/proc/self/ioon Linux, and the matchingproc_pid_rusagefields on macOS. All four fields are written together or not at all: a sample any source of which cannot be read writes no line. - At
debug, a session or ask process's memory and disk I/O: aresourcesline after each turn'sturn_completedand one more at the process's orderly end, measured the same way. A sample any source of which cannot be read writes no line. - At
debug, how long a timed operation takes: oneop_timingline when it ends, written by the one timer every timed place goes through (log::diag::timed).dataholdsop, the operation's name, andms, whole milliseconds; a tool's timers addtool, the tool's name, and a job's timers addjob, the job id. In analloc-statsbuild, and only when the timer ends on the thread that started it, the line also carriesalloc_bytes, bytes allocated during the operation,allocs, the allocation count during the operation, andlive_delta_bytes, signed end-minus-start live bytes, negative when the operation freed more than it allocated; a realloc contributes one allocation of the new size toallocsandalloc_bytesand adjusts live by the signed size difference. Otherwise the three fields are absent, never zero, and a default build writes none. No other field is recorded, and never an argument, a path or any content, as for every line inlogs/. Atinfothe cost is one check of the level, except the monotonic reads taken before the configuration is read, when the level is not yet known: one to timestartup.config, and two for each worktree created or recreated then. Those are the only extra costs there, and they write no line atinfo. A new module or top-level operation lands with its timer in the same pull request. Installed so far isnet.connect: one scope around an actual connector attempt group for a native observed request, from the first socket attempt through socket admission. It excludes DNS before entry, TLS, CONNECT negotiation and the response body, as well as pre-stopped and empty groups and already-built tunnels. Also installed ispicture.run: one scope per entered image-child invocation, from spawning it to its validated answer, kept through spawn failures, errors and cancellation after entry, while a call cancelled before entry starts none. A PDF count/cut call owns one scope, and each rendered page's own child owns its own; the renderer itself and file inspection stay untimed. Itsdataholds onlyopandms. Installed for the loop arestartup.preamble,turn.request,turn.model_callandturn.compaction.startup.preamblecovers building and installing the preamble after the approved-code load, before the opening message, once per session start: a same-session rebuild writes no line.turn.requestcovers assembling the history plus the request, ending before the budget, window and hook checks.turn.model_callcovers one admitted attempt, from entering the model call until its stream ends; a cancel observed before admission writes none, and a retry's backoff stays outside.turn.compactioncovers one compaction end to end, from its first record through the restart. Installed for one tool call aretool.permission,tool.reviewer,tool.hooksandtool.run, each withtoolnaming the registered tool.tool.permissioncovers the permission order from admission to the decision, holding the reviewer's stages and a person's wait; a suspended approval's fresh segment after resume is a new line, never the old process's downtime.tool.reviewercovers one entered judgement stage, a re-ask inside it included; a stage never run, and the person's wait after an escalation, write none.tool.hookscovers one actualbefore_toolorcheck_tooldispatch, or one actualafter_tooldispatch on ordinary, spilled or unsaved output; a call with no hooks, or a dispatch a shutdown suppresses, writes none.tool.runcovers one entered execution on its worker, not the wait for its ordered completion. The scopes nest instead of adding up: a requested compaction holds its note's request and model scopes; a compaction whose note a hook writes has neither, andhttp_request's network share sits insideturn.model_call. Warming refreshes and reviewer judgements run through the same factories but write no turn scope. Also installed are the six hook chains other than the tool hooks:hook.session_start,hook.turn_start,hook.before_message,hook.before_model_call,hook.turn_endandhook.before_compaction, one scope around each entered public dispatch, however it returns, empty chains included. Tool hooks take no scope:tool.hookscovers those chains. Other plain agent clients stay unobserved. Installed too ismcp.connect: one scope around one actual server connection attempt, from starting or dialing it until its tool list is in hand. It covers stdio and remote servers, eager and required starts, lazy first use, restarts, renewals and post-approval starts, with the remote server's actual connector work timed asnet.connectbeside it. It excludes cache-only declarations, prompt discovery and tool execution. Installed for startup and routing arestartup.config, from the one pre-load read through opening the writer;startup.extensions, loading the installed provider packages and extensions;startup.routing, from adding the Lua providers through choosing the model, reading its credential, connecting and choosing the reviewer, with unloading excluded; androuting.switch, one entered switch preparation, rejections included, with applying it excluded: the three startup lines are written before the session attaches, so they sit in the pid file with nosession_id. Installed for the hub arehub.session_start,hub.resumeandhub.subscribe_replay, and for listing,sessions.list.hub.session_startcovers a start from the request until the session's socket accepts, excluding the summary handshake for a first prompt; a rejected start measures through its failure.hub.resumecovers one reach for the session, including gate contention, retries and failures.hub.subscribe_replaycovers one actual kept-subscription replay, from its write through the matching acknowledgement, or through its failure, cancellation or disconnect before it. Installed for the door isstartup.socket: socket preparation until the bound listener is ready, on new and resumed sessions alike. Installed for listing issessions.list: one listing attempt from entry through feed settlement, snapshot and row reads, including invalid arguments. Installed for the session log arelog.appendandlog.fsync: one scope per actualevents.jsonlwrite attempt and one per actual sync, separate and never nested, stamped at completion and written after the session lock is released. Directory, lock and artifact syncs stay untimed. Installed for searching issession_search.scan: one scope per tool search request from its entry, including empty, cancelled and problem-only scans;fiber sessions searchwrites no line. Theirdataholds onlyopandms. Installed for jobs isjobs.start: one scope per background job or delegate run that starts, until it runs: a command started withrun_in_background,ttyormonitor, and a new or resumed delegate, from just before its spawn; a foreground command that moves, from the move alone, never its earlier run. It ends once the job is recorded and its own thread runs, before the receipt is built. A refused call, a spawn or registration failure, and a call cancelled before its job starts write none, and the job's later life adds nothing. Itsdataholds onlyopandms. Also installed for jobs arejobs.receiveandjobs.deliver: a receive line when the parent's job watcher receives an exit, and a deliver line when the runner delivers it to the loop. Watcher-received exits form ordered pairs byjob, the job id, with receive preceding delivery. A deliver without a receive records a missed watcher exit (including exits found by the stdout fallback or a reap that wins the race). Theirdataholdsop,msandjob. Installed for worktrees isworktree.createandworktree.remove.worktree.createcovers the onegit worktree adda new or resumed session runs to make its worktree, stamped before the configuration is read and written once the writer opens, so itstsis the writer's open time and itsmsthe stamped duration; a creation rollback stays inside that duration and writes no second line.worktree.removecovers the one real removal after the writer opens, whatever its result, excluding the exclusive take, the user scans, the inspection, the lock-file unlink and every kept path; a kept or shared worktree writes none. A failed creation or recreation, a recreation that finds the path present, andfiber sessions prunewrite none. Theirdataholds onlyopandms. Installed for the terminal aretui.extensions,tui.first_render,tui.attached_frame,tui.log_read,tui.transcript,tui.frame,tui.attach_summary,tui.tail_wait,tui.preview_fold,tui.tail_install,tui.attach_setup,tui.attach_wait,tui.attach_tail,tui.attach_prepare,tui.attach_drawandtui.startup.tui.extensionscovers extension loading before the first draw; when a loader exists it writes once per process, and without one it writes none (docs/tui.md, "How a TUI extension runs").tui.first_rendercovers entry through the first draw and writes at most once per process; a setup failure before the draw discards it and writes none.tui.attached_framecovers the same entry through the first draw that holds the attached session's history, written once per process; an attach with no stream, or one that ends before that draw, writes none.tui.log_readcovers the first attach's first fetched page, the firstpage_inhub.fetchattempt, to completion whatever its outcome, andtui.transcriptcovers the first successfulapp.loadfolding that page; each is written at most once per process, a failed fetch leaves the transcript latch unset, and an attach with no stream writes neither.tui.framecovers one frame over its 16 ms budget; a frame within budget writes none, so the log stays small while scrolling. Theirdataholds onlyopandms. The terminal's file stays pid-named across the attach.tui.attach_summarycovers the summary subscribe from before its send until acceptance queues the session's commands line.tui.tail_waitcovers the pre-frame tail-history fetch from the initialtail_nextthrough completion, whatever its outcome.tui.preview_foldcovers the first history answer's fold fromapp.tail_linesentry through completion, not the empty seed fold or installation.tui.tail_installcovers the preview installation fromapp.install_tailentry through completion after the pre-frame tail-history fetch.tui.attach_setupcoversrun_withentry through the initial unattached draw,tui.attach_waitcovers that draw through the first due tail read,tui.attach_tailcovers the first due tail attempt through the install it reaches, across false-returning attempts,tui.attach_preparecovers the install return through immediately before the attached-history draw, andtui.attach_drawcovers that draw through its completion. The five write once, together withtui.attached_frame, only when the first attached-history draw succeeds; an attach whose parent timer is discarded writes none. Theirdataholds onlyopandms.tui.startupcovers from after the diagnostic writer opens throughrun_withentry, stamped once the level is known so info starts pay only the level check; it writes once per process at debug and none at info. Itsdataholds onlyopandms. Each is written at most once per process on the first attach; an attach with no stream writes none. Theirdataholds onlyopandms. Request, model, hook and network timings may overlap as nested measurements, never additive phases. - A session close that stopped waiting for a running command: one
warnline with codetimeoutin the session's file, written once for each connection it stopped waiting for (docs/invocation.md, "What the hub speaks").
An event inside a running session is recorded in that session's log and
nowhere else, with one exception: a session or ask process's own diagnostic
lines, its extension_log, http_request, resources and op_timing
lines, are recorded in logs/<kind>-<id>.log beside the session log, never
in it; a hook that fails in a session, for example, is a notice or
hook_failed there (docs/extensions.md, "When a hook fails"). Nothing in
logs/ holds a credential or token, prompt or model text, a tool's arguments
or a configuration value, with one exception: an extension_log line is the
extension's own text, and Fiber records it as given. A failed hook is named
with its code, never its content.
Detached logs. detached/ holds one output log per detached shell
command (docs/tools.md, "Background jobs"), named d_<pid>_<n>.log from
0 up in a directory mode 0700, each file mode 0600. The person owns
deleting them: Fiber never removes a log, and a session's deletion or
pruning never touches them.
What feedback reads. fiber feedback and /feedback copy content-free
lines from logs/ and crashes/ into the Diagnostics section of the report
file, on the person's machine; the issue link never carries them. For the
selected session they read logs/session-<id>.log, logs/ask-<id>.log and
logs/tui-<id>.log, in that order, never a file named by process id or a
delegate's, and logs/hub.log.1 then logs/hub.log. A line is copied only
when it is one JSON object with an integer ts, a level of error, warn,
info or debug, the process of its file, and string code and message;
a session file's line also names the selected session, and a hub line names it
or names no session. Every extension_log line is left out, and so is any
line that does not meet this. A hub line also needs a ts no later than now,
and unless it names the selected session, no more than 24 hours old. Without a
selected session, the report holds hub lines with no session id only.
A report holds the newest 500 hub lines and the newest 2,000 session lines,
oldest first, equal times in the order above. The session cap keeps every
error and warn line before any other, and if those alone pass 2,000 it
keeps their newest 2,000; the report then says how many earlier lines it left
out, counting only lines that would otherwise have been copied. Both numbers
were chosen, not measured. Each crash report named for the session is copied
without a cap, as its first line, which names the thread and the source
location, and the text after its last stack backtrace: line: the panic
message is dropped, because it can hold anything. A report with no such line
keeps only its first line. A session with no lines on this machine, such as
one on a remote hub, still gets its id, how to export its log privately
(docs/invocation.md, "Deleting and pruning") and the hub lines, with a notice
that the machine has no diagnostic lines for it.
Bounds. logs/hub.log is renamed to logs/hub.log.1 when it passes
10 MiB, replacing any older one; its single writer makes the rename safe.
Files in logs/ and crashes/ older than 30 days, and all but the newest 100
in each, are deleted by fiber sessions prune and when the hub starts. These
numbers were chosen, not measured. Fiber sends nothing from logs/ anywhere
(ADR 0010);
fiber doctor and fiber feedback read it (docs/invocation.md, "Commands and
flags").
Worktrees. Per project, worktrees/<id>/: the git worktree of a delegate
started with isolation: worktree, of fiber ask --worktree or of the
terminal's new-worktree switch (docs/invocation.md, "Isolation"). When one
is removed or kept is docs/delegates.md ("Worktrees"). A kept worktree is
removed only by fiber sessions prune (docs/invocation.md, "Deleting and
pruning"). A worktree's lock file coordinates a resume's recreation, an end-of-run removal and fiber sessions prune against the processes running in the worktree. Every process that runs in a worktree it did not just create holds the file shared; a delegate's parent holds it shared before creation until the child records session_started after acquiring its own share; a recreation holds it exclusively while it checks and makes the worktree again, and a removal takes it exclusively without waiting, keeping the worktree when another process holds it. The file stays whenever its worktree stays, and goes only after a whole removal, not when only the directory is removed and the branch is kept.
Sockets. run/<session_id> is the local socket of a running session
(docs/invocation.md, "Processes"), mode 0600 in a 0700 directory. The hub, a
delegate's parent and session messages connect to it; every other client
reaches it through the hub. run/hub is the hub's own socket, which local
clients connect to; the hub that binds it removes a stale one first. The process
holding that session's session.lock owns the session socket while it holds
the lock: no other process unlinks it. Before binding, bind in
crates/doors/src/socket.rs connects first: a socket the connect reaches is
live, and binding fails with session_held. A failed connect removes the path
only when replaceable in the same file agrees: a refusal or a missing path is
replaceable at once, so a dangling symlink, or one pointing at a stale socket,
can be removed by bind; otherwise only a regular file is. When the connect
error is neither a refusal nor a missing path, a symlink, or a path whose type
cannot be read, may lead to a live session, so the path stays and bind fails
with io_failed. Two failure paths unlink after binding: when
setting the socket to mode 0600 fails, bind attempts the unlink and returns
the error, and the unlink itself can fail; and when the stdout-printer thread
fails to start, open_in in crates/doors/src/session.rs unlinks the
just-bound socket and returns the io_failed error. At exit,
Session::close in the same file unlinks the socket while still holding
session.lock, so a held lock does not imply a socket exists. Removing a
socket path is implemented twice: remove_socket in
crates/doors/src/socket.rs and a separate private remove_socket in
crates/hub/src/listen.rs for the hub's own socket. It sits at the top of Fiber home
because macOS limits a socket's path to 103 bytes (sun_path[104] in
sys/un.h; binding at 104 fails, probed on Darwin 25.6.0), and a path under
projects/<key>/sessions/<id>/ exceeds that. Linux allows 107 (unix(7), not
measured here). A FIBER_HOME long enough to break the limit is a startup
error naming the variable.
Paired devices. hub/devices/<device> holds one record per device
paired with this machine's hub: its name, when it was paired, when it last
connected, and a SHA-256 hash of its device token, never the token
(docs/invocation.md, "Remote clients"). Revoking a device deletes its
record. On a client, credentials/hubs/<name> holds the device token for
each hub it paired with, mode 0600, under the same credential deny as every
other file in credentials/ (docs/permissions.md, "Credentials").
Recently exited sessions. recent.jsonl at the top of Fiber home: one
JSON line per session that exited, appended by the session itself as it
exits. Its keys are session_id, ts, project (the project's key), workspace,
name, how, status, the session's last session_status, which says
what it stopped on and carries parent for a delegate, and archived, true on
an archived session's row and absent otherwise. A session whose
process died cannot append, so the hub appends its row when it sees the
crash (docs/invocation.md, "The hub"). Archiving a session appends its
row again with archived true, and its next exit appends one without it; a
session's newest row is its state (docs/invocation.md, "Archiving"). A session
appends whether or not a hub is running, and nothing rewrites it, so an
append is never lost to a rewrite. Deleting a session leaves its row, and
every reader skips a row whose session directory is gone. The hub reads its tail at start and keeps
the newest 100. It grows by about 400 to 600 bytes per exited session: 10,000
sessions is about 5 MB. It is a derived index, rebuildable from the logs, and never the
truth (ADR 0001).
Prompt history. Per project, history.jsonl: one JSON line per prompt,
append-only. The session appends each prompt a person sends it, in a session
the hub started, so every client shares one history; a fiber ask prompt is
not appended. Each line holds ts (integer, wall-clock milliseconds),
session_id and content, the prompt's content parts as the session
accepted them. Up-arrow recalls prompts typed anywhere in that project.
Fiber writes no derived database in v0.0.1. Listing sessions asks the hub,
which answers with each running session's latest session_status and the
exited sessions' recent.jsonl rows (docs/invocation.md, "The hub"). Any
future database is derived from the logs, rebuildable, never the truth.
Concurrent access
Every whole-file write is a temporary file renamed over the old one, so a
reader sees the old file or the new one, never half. A file that is read,
changed and written back — the config default, standing rules — takes a lock
file first. Appends (history.jsonl, events.jsonl) are one line per single
write. Readers never lock.
A write that fails before its rename leaves the old file; one that fails after it, while syncing the directory, returns an error with the new file already in place, because every reader already sees it.
One writer at a time per session, via session.lock, is docs/events.md.
Upgrades and versioning
There is no layout version marker. Coordination files that are created on demand and carry no data, such as a worktree's .lock file, do not change the layout, and binaries that do not know one skip it. The first change to this layout adds a
file layout at the top of Fiber home containing 2; a missing file means
layout 1. fiber update changes only the Fiber binary, extensions/ and docs/;
it never touches sessions, config, rules, approvals, pinned copies, credentials
or extension data. It replaces the binary by renaming a new file over it, so a running
session keeps the file it launched from. How the binary is fetched and
replaced is docs/releasing.md.