One prompt, end to end

The board

the whole loop, and where the money is

Everything except one box is a parse, a count, a path check or a set difference. The loop closes on itself: what a merge changes is what the next scan reads.

Every verb

sixty, read off src/cli.js in the order a factory uses them

Each card is one entry in the command table: the name, what it answers, the usage line, and what it does to the world. Two can spend money and only with the flag named on the card. Eleven can change a file a person wrote and only with --apply. The rest read, or write under .bundlebox/.

Aliases the table also answers to: gc and memory for janitor, blackice and audit for auditor, scenarios and corpus for cookbook, board and mb for mainboard, dataframes for frames, cc for console, usage for monitor, sg and switchgear for pipeline, learn and bm for buckmaster, bridgeswap for bridge, scripttag and st for scripts, ctx for context.

Every verb takes --json. A module that fails to load is reported by bb help as broken with the first line of its error, and the rest of the table still answers: one bad import must not take the CLI down with it.

One prompt, end to end

nine hooks, in the order they fire

This is what bb wire --apply installs. Every row runs local code against artefacts already on disk, and the only thing it can spend is the few hundred tokens it chooses to put in the window.

1. SessionStart30sbb hook session-start

   In a workspace that was never inited, this runs bb init inline — detection over the tree, well inside the budget — and detaches the artefact build, which is minutes of scanning and indexing and is not a hook's to spend. The returned line says it is still building rather than implying the environment is ready.

   Then the rot notice: which lines in the memory just loaded no longer resolve. The claim is already in the window, stated with the confidence it earned the day it was true, so the correction arrives beside it.

   Fired again with source: compact, right after a compaction, it is the first observable moment the window can be corrected. The narrative goes back first — the task, the scope, the files already edited, the last commands, the gate still open — read off the record the guards wrote, never off the summary. Then the rules, verbatim. Two caps, because truncating one joined band would cut whichever came second, and neither is the right one to lose.

   → window · ≤600 tok what this box holds, and what no longer exists → after a compaction · ≤1200 + ≤700 tok the record, then the rules

2. UserPromptSubmit15sbb hook prompt

   If the round before was a compaction and no SessionStart answered it, the same two bands go back here. It fires once per compaction, not once per prompt: the marker records which compaction has already been answered, and on which hook.

   Otherwise, when the prompt is a task, the hook runs bb pinpoint rather than suggesting it: measured on this tree at 0.47s against a 15s budget, because every input it reads is a stored artefact. A suggestion was measured too, and it loses to the model's own habit about three times in four. A brief already standing for the same prompt is reused, never rebuilt.

   What enters is the map, about 300 tokens: the files, the symbols, the verdict. The quoted regions stay on disk until a read asks for one.

   → window · ≤1000 tok the located, budgeted brief

3. PreToolUse · Read10sbb hook pre-read

   If pinpoint already located a region in this file, the read is denied and the reason carries the range to read instead. The model needs a read of a file before it will edit it, so blocking the scope blocks the change — and the denial names the read that is allowed.

   Otherwise the file is priced against what the window has left, and an oversized open comes back with an offset and a limit.

   ✕ denied · ≤900 tok read this range, not the file

4. PreToolUse · Grep | Bash10sbb hook pre-search

   A declaration search is the case where the answer is not merely cheaper to look up, it is already written down: symbols-*.md is a name / file / line index rebuilt by fingerprint. The denial hands back the matching rows and the search never runs.

   What is not denied matters as much. A string literal, a call site, a comment, a pattern no declaration index can answer: the tables have no rows for it and the search goes through untouched. And the same words over a different file are a different search: the duplicate key carries the target, because keyed on the words alone it refused a second file as already answered, twice in one afternoon.

   ✕ denied · ≤500 tok the rows, instead of the walk

5. PreToolUse · Write | Edit10sbb hook pre-write

   The one blocking check grapple adds, at the one moment the agent has committed nothing: a write outside the scope list the standing brief declared.

   In observe phase it records the verdict it would have returned and emits nothing — no decision, no bytes — so the session behaves exactly as it did before grapple existed, and those recorded verdicts are the base rate the enforce phase is gated on. A guard nobody measured is a guard nobody can defend turning on.

   ✕ denied · ≤900 tok out of scope — in enforce only

6. PostToolUse15sbb hook post-tool

   bb sieve rewrites an oversized tool result before the window is billed for it twice, keeping the head, the tail and every error-like line, and leaving the full output on disk to grep.

   The command shape is appended for bb lathe — git commit, never the message. Mining that order out of the transcripts took four minutes of wall clock for 4.8 seconds of CPU; this hook is already running on every tool call, so forty bytes here is the cheapest place in the system to learn the same fact. A shape log also cannot carry a secret somebody passed on a command line.

   Markdown the session writes into the tree is slop-checked, advisory only: a document is the only artefact here that charges rent, and a hook that rewrites your sentence unasked is worse than the sentence. And sixty bytes go to grapple's counters, no decision attached: everything bb grapple scores as drift is read back from this row.

   → window · ≤300 tok a shrunk result, and the rule it broke

7. PreCompact30sbb hook pre-compact

   Emits nothing, deliberately. Whether this hook's stdout reaches the window after the summary is written cannot be observed from here, and a mitigation built on a guess silently does nothing.

   What it does instead is freeze the record: the narrative is written now, so what goes back after the summary describes the same moment the summary does and not a later one. Then the marker, and the next observable event — SessionStart with source: compact, or the next prompt — does the work.

   · silent a frozen page and a marker on disk

8. Stop30sbb hook stop

   The fourth verification layer, and the only one that is not the work reviewing itself. It executes nothing. What it can say is whether the ledger this work declared is still sitting there with gates unmet — the one question a session about to report "done" cannot answer about itself. Silent where no ledger was declared, because a workspace that never set a bar has not failed to meet one.

   ✕ not done the gates still open

9. SessionEnd120sbb hook session-end

   The transcript is folded into the ledger and the session is priced: tokens billed and turns taken, measured, against what the local path displaced. Saved is reported as two different things — cache reads and wire trims are measured, displaced turns are counted per episode and multiplied out, and the line says which is which.

   Then sleep-time compute. None of it reaches a window — the session is over — and the session that paid for the turns should not pay for learning from them.

   • grapple observethe open questions, the labels it can attach, and the drift score
   • lathe learnthe habits, off the shapes the post-tool hook recorded rather than the transcripts — 1.4s measured. Writing into scripts/ stays behind its own flag: a hook that adds files to somebody's repository unasked is a hook they turn off
   • echosspin, oscillate, drift, converge, over the sessions on disk. It files findings, so the next session opens with them in bb findings
   • janitor buildthe memory heap recompiled for whoever opens next. A failed refresh costs the next session a fresher heap, never the session that is ending

   → you tokens used · tokens saved · turns · peak window

The caps are per emission, not per session. Every band declared in src/wire/hooks.js added together is 6,100 tokens, and the two largest fire once per compaction — against reads and searches it routinely denies for more than that on their own. bb wire status reads the hook log for events the bb on PATH did not recognise, because an installed guard that an older binary silently ignores looks exactly like one that is working.

What the hooks read

every answer is already on disk

No hook computes anything expensive. Each one serves a file that a gear built earlier, which is why a 15-second budget is never close to spent.

The three on their own clock

janitor · auditor · snapgen

Three things here are not stages in the tick. Each has its own trigger, writes its own artefact, and is read back somewhere else entirely — which is the part that is easy to lose.

The gears running underneath

a declared pipeline, as data

A gear is an ordered list of verbs with a gate in front of each stage. Every built-in gear is free and local: run and bridge are refused inside one, checked when the crontab line is written rather than assumed. factory chains five of them, every 30 minutes, and stops at lanes.

full runs on the slower line, every 6 hours, ungated: situation → ops → intake → orient → scenarios → watch → buckmaster. It is the one that needs a service up, so the recom gate — which answers from the tree, the config and the head commit — would not see it coming.

What fires what

five triggers · three of them wired

Sixty verbs. Nobody types most of them. Five things can fire a verb, and two of the five are declared in the source and read by nothing.

A hook fires it, inside a session

Cron fires it

Both under one flock, so they never overlap. Neither can reach run or bridge: unsafeVerbs() walks the chain and refuses to write the crontab line, rather than trusting that a gear stayed free. The gate runs 48 times a day so that the pipeline does not.

The agent fires it

Nine MCP tools, and the model decides when: bb_pinpoint, bb_context, bb_snapgen, bb_findings, bb_scan, bb_oversight_brief, bb_explain, bb_tokens_estimate, bb_session.

Nothing fires it

Twenty-six verbs wait to be typed. Most should: wire, unwire, kernel, update, cron and init change the box, and a box that reconfigures itself on a timer is worse than one that does not. The ones worth noticing are the free ones nobody is reminded of — env, context, gates, uptake, simulate, dotty, designlabs, scripts, proxy, headroom, agents, explain, findings.

A trigger name that nothing dispatches on is a schedule somebody believes in. The factory already learned this once — situation, ops and scenarios declared cron for months while no chain reached them, which is why the reachability check at cron.js:100 exists. It checks one of the five names.

Is the box ready for any of this

bb pipeline · eleven stages, each with an exit criterion

A stage is not done because it ran once. It is done when its output exists, is fresh against its inputs, and asserts something. Every stage before agent is free.

Stage 10 is the only one that asks about the work rather than the artefacts. Every stage above it checks that something was derived and is still fresh; none of them checks whether the sessions are converging.