Module queen 

The queen: the rare, budgeted escalation to a human engineer (PLAN.md “Expertise and the queen”; internal evaluation “expertise” §2, L4, not published).

At the Stop checkpoint, after the conscience decided, the drone’s plan goes to the queen only if all four hold:

1. High consequence: a plan sentence makes an irreversible change, an external mutation, a public API/schema change or a cross-repo/cross-team decision (classify, deterministic, 0 tokens).
2. The collective cannot resolve it: either the conscience asked nothing and the collective’s lessons carrying this decision key are absent or disagree, or the lessons the conscience selected contradict each other on this decision (same situations, different consequences: conflicts).
3. The inputs do not answer it: the engineer’s prompts in this session do not already state it.
4. Budget: at most one queen message (≤ MAX_QUESTIONS questions) per engineer per BUDGET_SESSIONS sessions, counted in the collective’s own store.

An asked question goes to <store>/queen/queue.jsonl; the drone is told once which default it proceeds with and is never held up. A decision (its key, or a reworded near-duplicate of an asked question or a queen lesson) is asked at most once, ever. borg queen answer turns the engineer’s answer into a lesson of the collective, so later drones get it from the conscience (L1) instead of the queen.

Off by default: the queen test (internal evaluation “queen-test”, rounds 1–3, not published) failed its pre-registered bar, so the Stop hook asks the queen only with BORG_QUEEN=on. borg queen (list, answer) works either way.

Answering the queue: borg queen numbers the open questions (asking order) for the terminal, --json gives drones a stable schema (Question), dismiss closes a question without a lesson, skip holds it back for SKIP_MS, and a near-duplicate of a queued question of the same repo is never queued (duplicate; dedupe cleans old queues). The prompt hook delivers at most one question per session, only of the session’s own repos (deliver, render_delivery; BORG_QUEEN_ASK=off disables it), and newly queued questions get one desktop notification (notify.rs).

Fails open: any error means the drone proceeds untouched.

Structs

Checkpoint

One Stop checkpoint as the queen sees it.

Decision

A high-consequence move of the plan: its kind and the sentence that makes it.

Entry

One queen question (a line of queue.jsonl). Answering appends the same id with the answer set; the latest line per id wins.

Mark

A question marked in a session: a skip (a line of skips.jsonl; session “cli” from the terminal) or a delivery by the prompt hook (a line of delivered.jsonl).

Question

One open question for a drone or a script: borg queen --json (an array) and the prompt hook. The schema is stable: id, n (its number in borg queen), repo, kind (snake_case Kind), question, options, default, evidence, ms (asked, epoch ms) and three exact shell commands: answer_cmd (replace <answer> inside its single quotes), skip_cmd and dismiss_cmd (a reason may follow).

Seen

A session the queen saw a checkpoint of (a line of sessions.jsonl), in first-seen order.

Visit

A session the delivery saw a prompt of while its repos had open questions (a line of visits.jsonl), in first-seen order: what “3 more sessions” counts.

Enums

Kind

Known

What the collective knows about one decision key (criterion 2).

Constants

BUDGET_SESSIONS

At most one queen message per engineer per this many sessions. Guard: the engineer’s attention, not money; a queen that finds something in every session cannot interrupt every session. Design-chosen, not tuned (escalation.rs measures what the messages yield).

DUPLICATE

Two questions of one repo whose significant words overlap this much (Jaccard) are one question. Method: a dedupe threshold, design-chosen.

MAX_QUESTIONS

At most this many questions in one message (one message per checkpoint). Guard: as BUDGET_SESSIONS, one message stays short enough to answer.

QUOTE_CHARS

Display: the characters of the text a queen question quotes (a plan’s sentence here, a lesson’s question in reach.rs, an invariant in veto.rs): one sentence whole in nearly every case, short enough that the question still reads as one on the queen’s screen and in borg web’s queue.

REOFFER_SESSIONS

A question delivered but neither answered nor skipped is offered again only once more than this many sessions (with open questions of their repos) began after the delivering one. Guard: an ignored question does not come back at every session.

SKIP_MS

A skipped question is not delivered again for this long (3 days). Guard: a skip is respected, and the question still comes back while its decision may matter. Derived from clock.rs DAY_MS.

Functions

answer

Record the engineer’s answer to id and add it to the collective’s lessons.

ask_enabled

Whether the prompt hook delivers queen questions: BORG_QUEEN_ASK is not “off” (default on).

ask_loop

borg queen ask over any input: each open question with one evidence line and numbered options. An option’s number or letter answers with that option, a lone number or letter naming no option asks again, other text is the answer; “s” skips, “d” dismisses, “q” or the end of input quits, an empty line asks again.

ask_on

ask_enabled for a given BORG_QUEEN_ASK value.

budget_allows

Criterion 4, pure: asked every question so far, seen every session in first-seen order. An engineer’s emails under aliases share one budget; open decisions imported from documents, reach questions and proposed constraints use none.

classify

Criterion 1: every high-consequence move the plan makes (not ones it rules out, suggests or says it left unchanged), one per sentence (its earliest move), first occurrence of each decision key.

clip

text trimmed and cut to max characters, an ellipsis marking the cut.

conflict_pairs

Pairs (i < j, indices into selected) of lessons that contradict each other: their situations mostly agree (≥ STATED of the shorter one’s words) and their consequences mostly do not.

conflicts

Lessons among selected that contradict another one (conflict_pairs). Ids in selection order.

consider

Decide whether to ask the queen and, if so, queue the questions. Returns the asked entries (empty: nothing asked). Errors only on I/O; the caller fails open. Cheap checks first: the lessons file is read only when a candidate decision survives them and the budget. A question that near-duplicates one already queued for its repo (duplicate) is not queued again. Newly queued questions get one desktop notification (notify.rs).

constraint_key

The key of a constraint proposed from a veto: its repo and normalised invariant.

covers

A lesson is about a move when its question, situations and consequence name most (STATED) of the move’s significant words (“force push main”).

decide

The queen’s decision at one checkpoint, without I/O (consider is this plus the store; the replay eval calls it directly): asked is every question asked so far, budget criterion 4 and lessons the collective’s lessons as raw JSON, both evaluated only once a candidate survives criteria 1-3. cp.store is not read.

decision_key

The decision key: the kind, the repo and the normalised move, so a reworded sentence making the same move in the same repo is the same decision.

dedupe

borg queen dedupe: the duplicates; with apply, each dismissed as “duplicate of ”.

deliver

The prompt hook’s call (0 model calls): the one question to ask in session, whose work is in repos (computed only once the session has none delivered and the queue has open questions), recorded as delivered (delivered.jsonl). Its commands end with scope. None when nothing is eligible (eligible) or the store cannot record it: fails open. BORG_QUEEN_ASK is the caller’s.

deliveries

dir

dismiss

Dismiss id: no longer open, never delivered, no lesson written. The latest queue line wins.

duplicate

Two questions are one: the same repo and DUPLICATE of their words (gist) shared.

duplicates

Open questions that near-duplicate an earlier, not dismissed question of their repo (duplicate): (later id, earlier id) in asking order. A duplicate found here is never the earlier side.

eligible

The question to deliver in session, pure. None once delivered has one for this session (one per session). Else an open question of one of repos (never another repo’s), not skipped within SKIP_MS, and, if delivered before, only once more than REOFFER_SESSIONS sessions of visits (first-seen order) began since. The engineer’s decisions about the work come first: a 0.3.0 hive task’s question (legacy_hive) only when none of them is eligible. Then never-delivered questions first, then asking order. The index is into open.

enabled

Whether the Stop hook asks the queen: only with BORG_QUEEN=on (off by default since the queen test).

entries

Every question ever asked of this collective, latest version per id, in asking order.

gist

What a question is compared and summarised by: a checkpoint question’s quoted plan sentence (its frame is the same for every move), else the question itself.

jaccard

Jaccard similarity of the significant words of a and b (0 when both have none).

known

label

At most five words of an option, up to its first ‘:’ or ‘,’: its label in a dialog.

lesson

The lesson an answer becomes: the decision question with the engineer’s answer, keyed by the decision so the queen is never asked it again. It supersedes only the disagreeing lessons the answer overrules (their consequence differs from it, as known compares), never the side it confirms, and takes the area most of the disagreeing lessons (lessons, latest lines) share.

main

borg queen: list, show, ask, answer, dismiss, skip, dedupe (see usage). --dir DIR (default: the current directory) or --collective NAME picks the collective.

open

Questions still waiting for an answer (neither answered nor dismissed), in asking order: borg queen numbers them 1.. in this order.

open_decision_key

The key of an open decision found in a team document: its source repo and normalised question.

option_answer

An answer as typed: exactly an option’s letter (“a”, “b”) or number (“1”, “2”) stands for that option’s text; a lone letter or number that names no option is refused (a typo, never recorded as a lesson) when the question has options; anything else is the answer itself.

questions

The open questions as borg queen --json lists them, only only’s repo when given.

render

What the drone is told, once: whom was asked what, and which default it proceeds with.

render_delivery

What the prompt hook adds to the drone’s context for q. A harness with a question dialog (dialog, harness Caps::question_dialog: Claude Code’s AskUserQuestion) asks with it; omp and opencode, which have none, ask at the start of their reply.

render_list

borg queen: the open questions (only only’s repo when given) numbered in asking order, grouped by repo (repos in order of their first question), each line cut to width characters; ANSI colors when color.

render_show

borg queen show: everything about one question; n its listing number when open.

repo

The repo a question is about: the one recorded when it was queued, else repo_name of the directory it was asked (or imported) in.

repo_name

The repo of a directory as the hooks name it: its git root’s base name, a worktree folded onto its repo (borg_trace::repo_key); the directory’s own name outside git.

resolve

key as borg queen takes it: a listing number n (1-based, into open in asking order), else the id of any question in all.

seed

Queue e (an imported open decision) unless its decision, or a near-duplicate question of its repo (duplicate), was ever queued in this collective. Returns whether it was added.

sh_quote

s single-quoted for a POSIX shell.

skip

Skip id in session: it stays open but is not delivered again for SKIP_MS.

skipped

id was skipped less than SKIP_MS before now.

skips

stated

Criterion 3: the engineer’s inputs (their prompts, not the drone’s own tool calls) already state this decision: they name the same move (a move of its kind with most of its words: “force-push” states “force push main”, “wipe the cache” does not), or contain most of the sentence’s words.

stop

The Stop hook’s single call, after the conscience decided. plan reads the drone’s last message (harness::plan), only once the queen is on; prompts the engineer’s prompts this session, selected the lessons the conscience asked. Some(block once) when the queen was asked; its reason then carries the conscience’s questions too.

within_budget

Criterion 4: the engineer was never asked, or at least BUDGET_SESSIONS of their sessions began since the session in which they were last asked (that one counted as the first).

Type Aliases

Asked

What borg queen ask did: (answered, skipped, dismissed).