Processing — wakeup, the reactor, and the question loop

What `bbx wakeup` actually does

Verified against src/cli/commands/wakeup/command.ts (2026-07-04; re-verified 2026-10-07). One full sync-and-process pass, under a per-box cycle lock (a second concurrent wakeup skips rather than waits):

Preprocess inbox items (transcription, etc.).
Housekeeping (sweep stale tmp uploads and abandoned captures, refill the root landmark).
Run on-wakeup scheduled scripts.
Run connectors — pull external data, create job cards in _bookkeeping/jobs/; then clean up stale jobs, split any intake job over 10 items into jobs of 10 (one commit, Phase: intake-split), create intake jobs for unjobbed inbox items (captured notes, etc.; at most 10 items per job), refresh the search index, and, when the refresh succeeded, queue a low-priority contains backfill job if searchable cards lack the field.
Process pending jobs — one reactor cycle unless --max-cycles <n> asks for more (skipping low-priority jobs). A cycle sends only the jobs that fit a 160 KB prompt budget; later cycles take the jobs not yet sent (reactor design).
Push committed changes to the box's git remote (non-fatal).

bbx wakeup --connector X scopes the whole pass to one connector's jobs. Every scheduled wakeup is scoped this way, so a job with no connector: (a question follow-up, scan or capture intake, a job an agent wrote) runs only in a full wakeup. The scheduler pass's job check starts one: about a minute after such a job is committed, if no wakeup is running, with up to three reactor cycles, retrying a job that stays at +1 h, +6 h, then daily, and giving it up after 7 days (../scheduler.md). Wakeup does not "execute commands" (command cards are gone; outbound cards are flushed by bbx finalize inside the reactor), and it does not schedule the next wakeup — recurring runs come from the bbx tick daemon (../scheduler.md) and agent-set timers (../chat/schedules.md).

The reactor is the main loop

runReactor (src/core/reactor/DESIGN.md): sync (bbx wakeup as its step when invoked with --sync) → refresh generated agent docs → find job cards → agent processing → bbx finalize. Two processing paths: batch (all pending non-chat jobs described in one agent session, bbx finish per job) and chat (per-thread sessions resumed across cycles). "Wakeup cycle" remains a fair umbrella name for one full pass; the reactor is its engine.

What "processing" an item means

The intake → triage → handle pipeline is the reference: ../triage.md. Possible outcomes for an item: archive it (_bookkeeping/archive/), trash it (bbx rm → _bookkeeping/trash/), create an outbound card (sent at finalize), ask a question, update or link a resource, spawn a secondary artifact, or leave it batched for later. The decisions come from schema instructions, rules files, category rules on landmark cards, and personality/guide cards (see teaching.md) — not from a hardcoded pipeline.

The question loop

When an agent can't proceed, it creates a question card in _bookkeeping/questions/: prompt, input (select/text/confirm), memo for why it's asking, context refs to the cards being discussed, and a directive — instructions for what to do with the answer. When the user answers (web or bbx answer), the system creates a follow-up job from the directive (src/schemas/question-followup-job.ts); it does not resume the paused session — session-resume is chat's mechanism. The follow-up job has no connector:; the scheduler pass's job check starts the full wakeup that runs it. The question alert and the 7-day nudge are sent from bbx finalize through the box server, which holds the push keys; one that did not go out is not latched, so the next finalize sends it again.

Unresolved design (ruling 12): whether long-running interrupted work should instead resume its original session, and how context-ref roles (subject / related / proposed-action, from the original design) fit — the current schema has flat {ref, text} context entries. Not filled out enough to have a clear answer; evolve it when a use case pushes (triage's low-confidence flow is the named forcing case).

Sessions