fiber

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

BudgetCeilingGated onBasisRecorded fast ceilingRecorded middle ceilingRecorded slow ceilingFast toleranceSlow tolerance
Session, idle, headless14,336 KiB peak RSSLinux x86_64picked—————
Terminal, idle20,088 KiB peak RSSLinux x86_64measured—————
Session, busy or resumed46,720 KiB peak RSSLinux x86_64measured—————
Keeper, one running job13,760 KiB peak RSSLinux x86_64measured—————
web_fetch converting a 10 MiB HTML page, the download capwithin the busy session's 46,720 KiB peak RSSLinux x86_64measured—————
Idle CPU, session and terminalzero context switches in the idle window, on every threadLinux x86_64exact—————
Threads, idle headless session5, plus 2 per client, plus 1 per Lua extension in useLinux x86_64exact—————
fsyncs2 per model request, 2 per tool callLinux x86_64exact—————
Log bytes, 429-call turnthe turn's content plus 2 KiB per tool callLinux x86_64exact—————
Session start, the internal session command to its first line, no hub20 msLinux x86_64picked16 ms12 ms13 ms55 %9 %
Terminal to its first frame, new session50 msLinux x86_64picked7 ms8 ms11 ms18 %8 %
Terminal to its first frame, attaching50 msLinux x86_64picked50 ms50 ms50 ms18 %21 %
Terminal attaching, to the end of the opening pass841 ms (1 MiB); 5,570 ms (10 MiB)Linux x86_64measured—————
Terminal attaching, fold per MiB of session log138 ms per MiBLinux x86_64measured——138 ms—69 %
Terminal, attaching a 10 MiB session45,512 KiB peak RSSLinux x86_64measured—————
Session, memory kept after the busy turn16,176 KiB RssAnonLinux x86_64measured—————
Session, memory kept after 10 busy turns, each followed by its compactionthe memory kept after the first, plus 1 MiB RssAnonLinux x86_64picked—————
Terminal, memory kept after attaching a 10 MiB session12,048 KiB RssAnonLinux x86_64measured—————
Listing 1,000 sessions in one project, warm cache50 msLinux x86_64picked72 ms34 ms109 ms82 %74 %
session_list, waiting for every running session's status2 s for the whole call, up to 1,000 running sessionsLinux x86_64picked1 ms1 ms72 ms0 %0 %
Sandbox setup for one confined shell call3 msLinux x86_64measured—————
paging jig, its session at scale 1 and 160 by 4817,592 KiB peak RSSLinux x86_64measured—————
paging jig, open pass and first frame1,347 msLinux x86_64measured725 ms828 ms1049 ms11 %4 %
paging jig, slowest frame that loaded pages7 msLinux x86_64measured8 ms5 ms10 ms16 %4 %
paging jig, slowest jump frame11 msLinux x86_64measured9 ms9 ms13 ms11 %5 %
paging jig, slowest re-count at a new width123 msLinux x86_64measured67 ms77 ms106 ms16 %8 %
paging jig, slowest append frame3 msLinux x86_64measured7 ms4 ms6 ms56 %32 %
paging jig at scale 16, slowest re-count at a new width24 times the same run's scale-1 re-countLinux x86_64picked—————
paging jig at scale 16, a search of the whole session with no match24 times the same run's scale-1 searchLinux x86_64picked—————
Terminal, wheel to frame, the paging jig's session at scale 1, 160 by 4816 msLinux x86_64picked7 ms6 ms9 ms21 %12 %
Terminal, wheel to frame, one turn with an opened read of 300 lines, 160 by 4816 msLinux x86_64picked5 ms4 ms7 ms40 %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:

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:

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.