Performance
The budgets Fiber holds, how each is measured, and what happens when one is exceeded. This is what is true now, not a plan. It is settled by Performance budgets: what Fiber holds, and how it is measured; that ticket's resolution holds the rationale and the rejected alternatives.
Which CI job runs the gate, and on which runner, is
docs/ci.md. How memory is measured
is docs/dependencies.md, "Measuring memory".
What a budget covers
A budget covers one process: a session, the keeper or the terminal. MCP servers,
process extensions, shell commands, delegates, image children and the hub
are processes of their own and are not counted. A delegate is a session
process and holds the same budgets as any session. The hub's own budgets,
idle memory, idle CPU, threads and time to first response with N sessions,
are not set yet (Control center). The image child's memory is its
own process's, not the session's. Peak over an empty program is 68,076 KiB
on Linux x86_64, 67,604 KiB on Linux arm64 and 67,825 KiB on macOS arm64;
an 81-megapixel PNG, which the 50-megapixel cap refuses, peaks at 308,372 KiB
(research/image-limits/README.md).
Every workload runs a fresh install's default load: the first-party provider
extension the session uses and the compiled-in tools. It runs no MCP server,
no process extension, no TUI extension and no other child process. An extension a person adds
costs what it costs (about 150 KiB and one thread for a Lua extension,
research/extension-runtime/pass2/RESULTS.md); that cost is its author's.
A session in a repository that declares code also checks each declared path
against pinned.json before its first request, hashing only a file whose size
or modification time changed (docs/extensions.md, "Code a repository
ships"). Measured on macOS arm64, in one process, with
cargo run -p extensions --example pin_check: one MCP server naming 200
files of 4 KiB each (819,200 bytes) takes about 9 ms with no pinned.json,
and about 4 ms with every size and modification time unchanged; a release
build takes about 8 ms and 2.5 ms. Both include resolving each path and
reading the index. No Linux figure is measured.
Two rows hold work to the size of what it covers. Memory kept after 10 busy
turns, each followed by its compaction, stays within 1 MiB of the memory kept after one, so state that grows
with every tool call the session has ever made fails it. The paging jig's
scale-16 session is about 75 MiB, the size of the owner's longest sessions;
its re-count and search may take at most 24 times their scale-1 time in the same run, so the ratio, not the machine, decides. The page count is 16 times; the rest allows for cache capacity, which grows the time per page at 75 MiB while the work per page stays flat (#2187), and for runner noise: readings run about 20 to 20.6 times (#2640).
The paging rows measure the tui crate's paging jig (docs/testing.md,
"Jigs"), a process that runs the terminal's paging over a generated session
it holds in memory, standing in for the hub's log; its memory row covers that
copy. It runs no provider extension and no compiled-in tool: it measures the
terminal's paging and drawing alone, so the fresh-install load above does not
apply to it.
The keeper row measures the keeper process while its one shell job runs: the job is the workload the budget covers, so the fresh-install load above does not apply to it.
Memory follows the context window, not the transcript. After a compaction the
session holds the compaction note and what came after it, and a resumed session
reads from its last compaction (docs/compaction.md). A 2-million-token session and
a 20-thousand-token one fit the same ceiling.
Budgets
| Budget | Ceiling | Gated on | Basis | Recorded fast ceiling | Recorded middle ceiling | Recorded slow ceiling | Fast tolerance | Slow tolerance |
|---|---|---|---|---|---|---|---|---|
| Session, idle, headless | 14,336 KiB peak RSS | Linux x86_64 | picked | — | — | — | — | — |
| Terminal, idle | 20,088 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
| Session, busy or resumed | 46,720 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
| Keeper, one running job | 13,760 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
web_fetch converting a 10 MiB HTML page, the download cap | within the busy session's 46,720 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
| Idle CPU, session and terminal | zero context switches in the idle window, on every thread | Linux x86_64 | exact | — | — | — | — | — |
| Threads, idle headless session | 5, plus 2 per client, plus 1 per Lua extension in use | Linux x86_64 | exact | — | — | — | — | — |
| fsyncs | 2 per model request, 2 per tool call | Linux x86_64 | exact | — | — | — | — | — |
| Log bytes, 429-call turn | the turn's content plus 2 KiB per tool call | Linux x86_64 | exact | — | — | — | — | — |
| Session start, the internal session command to its first line, no hub | 20 ms | Linux x86_64 | picked | 16 ms | 12 ms | 13 ms | 55 % | 9 % |
| Terminal to its first frame, new session | 50 ms | Linux x86_64 | picked | 7 ms | 8 ms | 11 ms | 18 % | 8 % |
| Terminal to its first frame, attaching | 50 ms | Linux x86_64 | picked | 50 ms | 50 ms | 50 ms | 18 % | 21 % |
| Terminal attaching, to the end of the opening pass | 841 ms (1 MiB); 5,570 ms (10 MiB) | Linux x86_64 | measured | — | — | — | — | — |
| Terminal attaching, fold per MiB of session log | 138 ms per MiB | Linux x86_64 | measured | — | — | 138 ms | — | 69 % |
| Terminal, attaching a 10 MiB session | 45,512 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
| Session, memory kept after the busy turn | 16,176 KiB RssAnon | Linux x86_64 | measured | — | — | — | — | — |
| Session, memory kept after 10 busy turns, each followed by its compaction | the memory kept after the first, plus 1 MiB RssAnon | Linux x86_64 | picked | — | — | — | — | — |
| Terminal, memory kept after attaching a 10 MiB session | 12,048 KiB RssAnon | Linux x86_64 | measured | — | — | — | — | — |
| Listing 1,000 sessions in one project, warm cache | 50 ms | Linux x86_64 | picked | 72 ms | 34 ms | 109 ms | 82 % | 74 % |
session_list, waiting for every running session's status | 2 s for the whole call, up to 1,000 running sessions | Linux x86_64 | picked | 1 ms | 1 ms | 72 ms | 0 % | 0 % |
| Sandbox setup for one confined shell call | 3 ms | Linux x86_64 | measured | — | — | — | — | — |
paging jig, its session at scale 1 and 160 by 48 | 17,592 KiB peak RSS | Linux x86_64 | measured | — | — | — | — | — |
paging jig, open pass and first frame | 1,347 ms | Linux x86_64 | measured | 725 ms | 828 ms | 1049 ms | 11 % | 4 % |
paging jig, slowest frame that loaded pages | 7 ms | Linux x86_64 | measured | 8 ms | 5 ms | 10 ms | 16 % | 4 % |
paging jig, slowest jump frame | 11 ms | Linux x86_64 | measured | 9 ms | 9 ms | 13 ms | 11 % | 5 % |
paging jig, slowest re-count at a new width | 123 ms | Linux x86_64 | measured | 67 ms | 77 ms | 106 ms | 16 % | 8 % |
paging jig, slowest append frame | 3 ms | Linux x86_64 | measured | 7 ms | 4 ms | 6 ms | 56 % | 32 % |
paging jig at scale 16, slowest re-count at a new width | 24 times the same run's scale-1 re-count | Linux x86_64 | picked | — | — | — | — | — |
paging jig at scale 16, a search of the whole session with no match | 24 times the same run's scale-1 search | Linux x86_64 | picked | — | — | — | — | — |
Terminal, wheel to frame, the paging jig's session at scale 1, 160 by 48 | 16 ms | Linux x86_64 | picked | 7 ms | 6 ms | 9 ms | 21 % | 12 % |
Terminal, wheel to frame, one turn with an opened read of 300 lines, 160 by 48 | 16 ms | Linux x86_64 | picked | 5 ms | 4 ms | 7 ms | 40 % | 23 % |
The idle headless ceiling is 14 MiB of peak RSS. CI medians on main run 13,144 KiB, of which 3,220 KiB is RssAnon and the rest file-backed code pages (run 39924100235). The growth over 12 MiB is file-backed code pages; RssAnon is unchanged. Credential queries require an admitted-model tracker and reader callbacks even before the first query, so they can answer for a previously queued model switch. Label enumeration is on demand; no picker or additional reader thread runs in a headless session.
The keeper ceiling is 13,760 KiB of peak RSS with one running job. The benchmark has never run on main, so the figure is the median of its five runs on the pull request that added it, 6,880 KiB, doubled per Basis below (run 42137584416, which failed elsewhere with its benchmark job green).
Basis says where a number came from:
- From components is the sum of measured parts, times two. Idle terminal: ratatui's two screen buffers and
crossterm, with room for the visible part of the transcript (8 MiB), then 856 KiB,
twice pulldown-cmark's 428 KiB on Linux x86_64, for rendering replies as
markdown (
docs/dependencies.md, "Runtime dependencies"), then 896 KiB, twice the 448 KiB the system root store costs when the TLS connector loads it (crates/net; Linux x86_64, release run 38052645277). The terminal's syntax highlighting is its own code and admits no crate. Admitting a crate for the terminal raises its ceiling by twice the crate's measured cost in the same pull request; its idle CPU and first frame budgets do not move. Busy session: a 300,000-token context is about 1.2 MB of text, and a 2 MiB conversation added about 3 MiB inresearch/delegate-memory/. - Exact follows from a rule, so the gate checks an equality, not a
ceiling. The five threads every session runs are the loop, signals, accept,
status and the printer for its stdout. Each client adds its reader and its
writer (
docs/architecture.md, "The threads"). A pull request that adds a thread changes this count and says why. Two fsyncs bracket each effect, and no line restates an earlier line in the same turn (docs/events.md, "Writing"). - Picked was chosen with no measurement behind it. The idle session's
12 MiB is held as a placeholder: every runtime crate linked together costs
7.4 MiB over an empty program on Linux x86_64 (
docs/dependencies.md, "Measuring memory"), and twice that is 15 MiB, so a first measured run above 12 MiB sets this ceiling. - Measured is a Fiber measurement times two. The first build that runs a benchmark replaces a "from components" or "picked" number with its measured one only where the measurement exceeds that number. Every other ceiling stays as it is, and a ceiling the measurement does not exceed keeps its basis. A ceiling given as a formula stays picked. Attaching's first-frame ceiling stays at the approved flat 50 ms for both own-log fixtures.
The class columns hold the timing gates per runner speed class, keyed by CPU
model strings matched case-insensitively. A model's class is the slowest
cluster its stored runs reach. The fast class is AMD EPYC 9V45 96-Core Processor, which gates; the middle class is Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz, which stays advisory; the slow class is
AMD EPYC 7763 64-Core Processor, which gates, and AMD EPYC 9V74 80-Core Processor, which stays advisory. INTEL(R) XEON(R) PLATINUM 8573C
has no class, and any other model, an empty string or a missing
CPU is unknown: all stay advisory, and the comment says why. A model gates
only with at least 5 stored files; turning another model on later is a pull
request that adds its rows. Rows that are not absolute timings carry — in these
columns, and the ordinary Ceiling cell stays as advisory reference data. A new timing row's class cells carry — until a model has at least 5 stored files carrying its metric. A row whose ceiling the owner ruled as a flat number carries that number in every class cell from the start, and its tolerance cells carry — until the same 5 files exist.
Except for owner-ruled flat ceilings, each class ceiling is the maximum stored
sample for that metric across every model in the class, rounded up to the next whole
millisecond, so it covers every stored sample as well as every per-file
median. Each tolerance is 100 * (maximum per-file median / minimum per-file median - 1) for the gated model and row, rounded upward to a whole percent:
fast uses 9V45, slow uses 7763 only, so the advisory 9V74 never widens 7763's
tolerance. A per-file median under the 1 ms quantum counts as 1 ms,
so a zero median never divides the tolerance. Middle has no tolerance because no middle model gates.
The class cells are recorded ceilings; a row whose recorded ceiling is under 2 ms is judged as
"When a budget is exceeded" says. The fast
session_list ceiling and tolerance are pinned by a test against the
plain-number samples of the fast class's stored files
(xtask/tests/class_data/9v45-session-list.json). The listing fast and slow
cells and their tolerances are pinned by a test against the full-precision
samples of the class's stored files
(xtask/tests/class_data/9v45-sessions-list.json and
xtask/tests/class_data/slow-sessions-list.json); each entry carries the
run's CPU model string as cpu, and the slow tolerance uses the 7763-cpu
medians only, so the advisory 9V74 never widens it. scripts/class-data
regenerates these files from the benchmarks-<sha> artifacts of main
runs; entries whose artifacts have expired, and entries from non-main runs,
stay in the committed files by hand. The attaching first-frame row's two tolerance cells are not pinned by a test. They were measured on 2026-11-03 from the stored main artifacts of the window since #3572 (2026-10-30 07:47 UTC) up to 715eef36c, over the 26 9V45 and 51 7763 stored files carrying terminal_attach_ms, and #4061 records the run ids and the arithmetic.
The busy-or-resumed ceiling holds on three workloads:
- a turn of 429 tool calls with the context window full to the compaction point
- resuming a 20,000-token session
- resuming a 2,000,000-token session that has compacted 7 times
web_fetch holds at most one whole copy of the 10 MiB page: an HTML page
streams into its artifact and its converter in 64 KiB pieces, so only its
markdown (5.4 MiB) is held whole, and a text page is held once, as the
result, when it is valid UTF-8. The fetch alone peaks at a 21,664 KiB
footprint on macOS arm64, and the session's peak RSS on Linux x86_64 is
17,428 KiB (35,376 KiB before the page was streamed).
429 tool calls is the p99 of tool calls per user turn, measured on real sessions in the archived Zig tree. That tree's session peaked at 2.1 GiB on this turn.
Listing is one sessions command to the hub: it copies each running
session's latest session_status from the feed and reads recent.jsonl once
(docs/invocation.md, "The hub"). It opens no session log. docs/state.md
rules out a derived database, and the ruling stands while this budget holds.
Measuring
Each number is the median of 5 runs, except a pull request's timing-only
workloads and the paging jig, which are the median of 3; when a gated timing row's median is over its ceiling and over its base tolerance, that row is measured 4 more times on each side in the same job and the budget is judged on the median of all 7. The terminal attach row, which already takes 5 samples, and session_list_ms, which no row maps for a remeasure, never remeasure. Every results file records the runner's CPU model.
Memory is peak RSS on Linux and peak
footprint on macOS, by the method in docs/dependencies.md. The retained rows
read RssAnon from /proc/<pid>/status 10 s after the work ends, once freed
pages have settled: 10 s after the 429-call turn completes, and 10 s after the
attached terminal shows the session's last reply. Their ceilings gate RssAnon,
not peak RSS. Idle CPU is the
voluntary and involuntary context switch counts in
/proc/<pid>/task/*/status, read before and after the idle window: 10
seconds on a pull request, the "Release build and size" job included, and 60
in the release workflow (docs/releasing.md). A truly idle process switches
zero times in either. The idle-session and idle-terminal benchmarks also report
RssAnon and RssFile from /proc/<pid>/status at the end of the idle window, as
diagnostics; the budget stays on peak RSS. fsyncs are the session's fdatasync calls, counted
with strace in one more run of the busy turn, which is never a timing or
memory sample, and log bytes are the size of events.jsonl, so both are
exact.
Linux x86_64 gates every pull request, and the backstop on main measures
the same benchmarks. On a pull request the head and base binaries run only
the rows the diff selects (docs/ci.md, "Selection"), alternating head and
base timings in one harness process, by sample for every timing row; a row
the diff does not select runs on neither side, and the budgets it feeds
read skipped. The skipped budgets are the row's timing budgets and the
memory budgets that ride on a skipped row and cannot be measured alone:
Terminal, attaching a 10 MiB session and Terminal, memory kept after attaching a 10 MiB session on the terminal attach row, and the paging
jig's peak RSS budget on the paging row. Memory and exact rows no
skipped row feeds still run on the head and compare against the backstop's
stored results for the base commit (docs/ci.md, "On every pull request
that changes code"). The backstop on main and the release workflow run
every gating row, so a break in an unselected row fails there after the
merge, not on the pull request. Linux arm64 and macOS arm64 are
measured at each release and reported, never gated: timings differ by about
20 times between macOS and Linux on I/O, and macOS memory counts system
frameworks Fiber does not control. Listing with a cold cache is reported,
never gated. Listing is timed from spawning fiber sessions --json in a git
repository whose project holds 1,000 exited sessions to its output closing,
with the hub running and one listing before the timed ones. Attaching is timed
twice from spawning fiber resume <id> in a pseudo-terminal, for a live, idle session whose log is 1 MiB and one whose log
is 10 MiB, with the hub running: to the session's last
reply on screen, which is the first frame, and to the scroll bar, which is the
pass end. The same run records the attaching terminal's
peak RSS and its RssAnon 10 s after the last reply appears, for the 10 MiB
session; the busy turn records its session's RssAnon 10 s after the turn
completes. The same run splits each attach into stages, reported as attach_stage_ms:
the fold stage feeds the fold-per-MiB budget above, and every other stage
is diagnostic, never gating. The terminal stage measures the resume
binary from spawning fiber resume <id> to the last reply on screen;
hub_replay runs a raw hub-socket client without the terminal and measures a
subscribe at full from send to acknowledgement. parse, fold
and frames_1, frames_4096 and frames_64 run in the release-built paging
jig over the session's events.jsonl: parsing each line, folding lines into
the app in batches of up to 4,096, and drawing one frame, one frame per 4,096
lines and one per 64 lines.
The live attach_span_ms rows come from debug runs of the resume binary.
tui.attach_setup measures from run_with entry through the initial
unattached draw. tui.attach_wait measures from that draw through the first
due tail attempt. tui.attach_tail measures from the first due attempt
through the tail install it reaches, across false-returning attempts.
tui.attach_prepare measures from the tail install's return to immediately
before the attached-history draw. tui.attach_draw measures that draw from
start through completion.
The resume binary's tui.attached_frame operation measures from run_with
entry through the first completed draw holding attached-session history.
The derived tui.attached_frame_remainder subtracts the five tui.attach_*
spans from that parent in each diagnostic sample. The parent contains those children,
so do not subtract them again. These live spans and the remainder are
diagnostic; they add no budget, limits entry or bench entry.
Subtract tui.attached_frame once from terminal_attach_ms to get the
unattributed residual. It includes process start, home setup and the gap
between internal draw completion and the external PTY reader's observation.
The paging jig's hub_replay, parse, fold and frame timings remain
comparators, not summands.
The harness also runs each timing workload and each busy workload once more,
in a home of its own whose diagnostics.level is "debug", on the head
binary and only with --only all. It does not rerun the fsyncs pass, and this
run is never a timing or memory sample. It records, per workload, the run's
wall-clock time, each op_timing operation in the run's logs/ files with its
count and total ms, and http_request's count and total total_ms
(docs/state.md), as op_breakdown. The bench-report
comment shows it under "Debug run"; it is reported, never gated.
No test asserts a timing (docs/testing.md). The budgets are a benchmark job,
separate from the tests. The harness, cargo run -p bench --example bench,
measures a fiber binary and writes its results to a file, and
cargo xtask bench-report judges that file against the table above. The
paging rows run the jig at scale 1 and 160 by 48, built in the release
profile for the target that ships, and read its peak RSS from GNU time.
The two scale-16 paging rows run the same jig at scale 16 and 160 by
48 in the same run, right after scale 1, so every scale-16 re-count and
absent search pairs with the same run's scale-1 sample. The gate takes
the median of the paired ratios, not the ratio of independent medians:
the ratio, not the machine, decides, and a base that is over its own
ratio never waives a head that is over.
The wheel rows burst 30 wheel-up reports, 8 ms apart, against fiber resume
in a pseudo-terminal at 160 by 48, in the paging jig's session at scale 1
and in one turn with a reply of 150 list items preceding an opened read
of 300 lines, of which Fiber draws the first 20 lines, and time each report
from its write to the frame showing the scrolled rows; each row holds the
slowest report's ms.
Two opt-in profiling builds report memory per operation, and neither
number is a budget. cargo build --features alloc-stats counts every
allocation through a wrapper around System, and each op_timing line
whose timer ends on its starting thread gains alloc_bytes, bytes
allocated, allocs, the allocation count, and live_delta_bytes, signed
end-minus-start live bytes (docs/state.md, "What each part holds").
cargo build --features dhat-heap profiles the whole run's heap instead,
writing dhat-heap.json at orderly exit with a backtrace for every
allocation site, viewable with DHAT's dh_view; the two features cannot
be combined, because each sets the global allocator. Allocation stats
include diagnostic timer overhead on boxed timing paths:
Diag::timings() boxes each Timer after start_timer returns, so that
box's allocation and live bytes fall inside the measured operation.
When a budget is exceeded
An exact or memory budget fails the pull request from its first run. Its
author may raise the ceiling in the same pull request by editing the table
above with the new measurement and the reason. A budget the base commit
already fails, in the backstop's stored results for it, does not fail the
pull request: the
comment marks the row over at the base and names the base, and the backstop
on main fails on it, which makes the fix a backstop ticket.
A timing row gates per runner speed class when its runner's CPU model is
eligible, and stays advisory otherwise. The two scale-16
paging growth-ratio rows are the exception: like an exact or memory
budget, a paired ratio over 24 times its same run's scale-1 sample
fails the pull request on Linux x86_64, however the base compares.
GitHub's Linux x86_64 runners fall into three speed classes, whose
frames_64 medians across 26 stored results (October 11 to 13, 2026; 19 from
gated models) run about 1.49 to 1.65 times from the fast extremes to the slow
cluster: fast 302.150569 to 324.314527 ms, middle 446.141956 to 448.120506 ms
and the slow cluster 481.640278 to 497.654993 ms. The 9V74 fast VM at
384.165851 ms belongs to the slow class but stands outside the slow cluster's
range: a model's class is the slowest cluster its stored runs reach. Within
a model the frames_64 medians span 1.77% on 7763 and 7.34% on 9V45; the 9V74
fast VM is 22.80% faster than its own slowest VM (29.54% slower by the
opposite denominator). Across the 11 absolute timing rows the gated models'
max/min median spreads range from 3.22% to 81.05%: session start spans 8.47%
on 7763 and 54.37% on 9V45, listing spans 73.30% and 81.05% respectively, so
each row carries its own tolerance in the table. Budgeted numeric memory-row
medians across these files vary by about 1.0% to 7.0% depending on workload:
busy peak RSS spans 1.31% and web_fetch peak RSS 6.98%. An ordinary timing gate fails
only when the median is over its class's ceiling and over the base commit's
median from the same job by more than that tolerance, measured in the same
job on the same runner, and its author may raise the ceiling as
above. A row whose recorded class ceiling is under 2 ms is judged on a ceiling of 2 ms and on 1 ms
over the base median in place of its tolerance: it fails only when the median is over 2 ms and more than
1 ms over the base median. Every other row is judged on its recorded ceiling and tolerance. A model
with fewer than 5 stored runs, an unknown CPU model and any row without a comparable same-job base timing stay
advisory, and the comment says why. Attaching's warm first-frame row is
judged on eligible fast and slow models against a 50 ms ceiling. Each 1 MiB
and 10 MiB own-log fixture fails only when its median is over 50 ms and more
than the row's tolerance over the comparable base median from the same job,
or more than 10 % over it while the tolerance cell is —. The report names
every median over 50 ms, whether it fails or not. When there is no base, the
base failed, a base metric is missing or malformed, or the base ran on a
different CPU, the 50 ms bound holds on its own.
Middle, unknown and few-run models stay advisory. The opening-pass-end row
stays advisory reference data, with no timing gate. Each over-ceiling fixture
produces one named failure; malformed attach data fails without duplicating errors.
A numeric first-frame tolerance also fails a fixture whose median exceeds its
comparable base median by that tolerance, even below 50 ms. Either breach
fails the fixture once; — disables only this relative comparison. Without
a usable comparable base, only the absolute bound can fail the fixture.
A benchmark's own self-check failing is a failed run, not a slow sample.
At each release, every ceiling more than twice its measured value drops to measured times two. Ceilings never rise at release; only a pull request raises one.
Comparisons with other tools, and the owner's usage, behind this area's rules: research/reference-comparisons/README.md.