Repository navigation
v0.14.0 “Megingjörð”: a run is held by its driver and repaired by a record, a quarantined run releases its worktree, and a provider's rate limit is a cool-down the run waits out
Megingjörð is Thor's belt of strength, worn with Járngreipr, the iron
gloves 0.13 was named for. This release is about what holds a run
together under strain:
- A driver holds its run. A run is held by its driver's lock, and
nothing but an operator's annotation is written after it ends. - A broken run is mended by a record. It is repaired by a record and
never by an edit, and a quarantined run's worktree is released once
every writer is proven ended. - A provider's rate limit is a cool-down. The run waits it out and
probes the provider, instead of parking.
It also adds:
- a deadline floor for shared local hardware, and a sweep of the seat
trees Brokkr made; - retirement of a historical evidence root;
- typed run endings in every listing;
brokkr analyticsread from the journal's own rows.
It includes the changes merged since
v0.13.1.
This release breaks scripts that stop or conclude a run without a
cause, refuses a second driver on a run another process drives, migrates
the journal's queue storage to version 6 on its first writing open, and
moves the MSRV to Rust 1.89. Read
Upgrade and compatibility before you install
it over a working setup.
What changed
- A run is held by its driver, and a broken run is repaired by a record
(decision 0108; #440).- Nothing but an annotation follows a terminal event
(#1078).- The store refuses any other append to a run that has ended, inside
the append's own transaction, asStoreError::AfterTerminal. It
writes no event, no cool-down row and no projection. - A late driver ends typed,
EngineError::ConcludedBeneath, and
writes nothing. stop,retryand a member retry on a concluded run print why and
journal nothing.classifyandsupersedestill land.
- The store refuses any other append to a run that has ended, inside
- A run is held by its driver's lock
(#1080).- Every driving entry (run, rerun, a queue claim, dispatch and
resume) takes an exclusive, non-blockingflockon
<journal>.runs/<run-id>.lockbefore its first append. - A second driver refuses at once: "run '…' is driven by pid P on this
host since T (engine V)". brokkr concludetries the lock first, and refuses a run its driver
holds before writing anything.operator stopandretrytake no lock and stay lawful on a live
run.
- Every driving entry (run, rerun, a queue claim, dispatch and
brokkr operator repair --run <id> --reason <text>
(#1085).
It names the late tail after a run's terminal event. The fold then
reads that tail as late: kept and shown, never applied. The run reads
as its terminal status, with "a late tail of N events, repaired by
". Nothing is edited or deleted, and the hash chain is
untouched.- The record: an
operator/commandedannotation whose args are the
newoperator-repair.v1. - The reserved words (
repair,settle,classify,
supersede) are refused at the Looper bridge before anything is
journaled. The bridge answers with a rejected receipt and keeps
applying the commands behind it, so the channel never wedges.
- The record: an
brokkr operator settle --run <id> --reason <text>: a
quarantined run releases its worktree
(#1100).- The release is proven, never assumed. Each driver records its
process group, and the release asks every recorded group. It refuses
with a typed reason if a group is live or a cleanup is unresolved. - The settle record: an
operator/commandedannotation under the
newoperator-settle.v1, read by type and never by its word.
- The release is proven, never assumed. Each driver records its
- No broker write makes a reservation that is gone.
- Six paths reseal: every path that reads a reservation as
standing and writes it again (a run's later attempt, adoption,
recovery, the operator's release, an MCP server's extension, and the
crashed probe's release) now reseals it. - One atomic exchange:
renameat2(RENAME_EXCHANGE)on Linux,
renameatx_np(RENAME_SWAP)on macOS. A record removed in the window
stays removed. - One path creates: only a run's first admission, which read no
record.
- Six paths reseal: every path that reads a reservation as
- Nothing but an annotation follows a terminal event
- A provider's rate limit is a cool-down the run waits out (decision
0103; #430).- The host declares the bounds, in
forge.host/v2'scooldowns
block (#1007):default_secondsandmax_seconds, each 1–7200 s;- overrides per provider and per route.
- A single seat waits, probes, then retries, all inside decision
0006's attempt cap
(#1026):- a seat refused by a rate limit before its session records the
site's cool-down and waits in-process, honouring an operator stop; - it then probes the cooled route with one turn of the refused
candidate's own adapter, and retries only after the probe answers; - the wait is recorded under the new
provider-wait.v1.
- a seat refused by a rate limit before its session records the
- Panels and sequences wait out each refused member's or step's own
cool-down, and probe each one
(#1046,
#1049). - Cool-downs are rows in queue storage v4, written in the terminal
event's own transaction
(#1070,
#1074). - The engine waits the aggregate
(#1081):- that is the latest unexpired end for the provider and route across
every run; - a probe refused again extends the wait without spending an attempt;
- a refusal past the maximum parks, naming the cool-down.
- that is the latest unexpired end for the provider and route across
- Admission holds a queued entry while its provider's route is
cooling down (cooling_down), and the claim's fence rechecks it
(#1095). - A quota or usage limit is a rate limit with its own reset, for
Codex, dsh and Claude
(#1058).
- The host declares the bounds, in
- Shared local hardware sets a deadline floor, and the host sweeps the
seat trees Brokkr made (decision 0104;
#430).- The deadline floor. A shared-local route in the new
forge.host/v3may declaretimeout_floor_seconds, at most 7200. It
raises the deadline of an attempt on that route and never shortens an
authored one
(#1039). - Seat trees are recorded. Each run-local seat scratch tree is
recorded in queue storage v5'sseat_treesbefore it is made
(#1073). Each
complete removal goes in v6'stree_sweeps, made by one walk that
follows no link and crosses no filesystem
(#1079). brokkr sweep [--dry-run]removes the seat scratch trees the
journal proves free, under the dispatch lock
(#1096).- Every tree it keeps is named, with its reason.
- A dry run reads the same verdicts and writes nothing.
brokkr doctornames each directory under a recorded root that no
open row records, and removes nothing.
- The deadline floor. A shared-local route in the new
- An operator retires a historical evidence root, with a record
(decision 0105;
#1020).brokkr evidence listlists every historical root.brokkr evidence retire --root <dir> --reason <text>retires one,
under the admission lock, with exactly one of:--archived-to <dir>, which writes the newevidence-archive.v1
inventory last;--discarded, which removes the root by a walk that follows no
link.
- A historical root no longer keeps every unboxed writer on the host
refused forever
(#1047,
#1064,
#1069).
- A run says how it ended, in every listing (decision 0064, slices E3
to E6; #317).stopandconcludename the ending.brokkr operator stopand
brokkr concludetake--cause, one of the six operator-owned
endings, recorded underoperator-ending.v1
(#1006).- Every row carries it. A run's summary row carries its typed
ending, its citation and whether aclassifystood over an earlier
ending, on/api/runs,/api/view,inspect --jsonand
brokkr runs(#1014). brokkr runspaints it
(#1015):- each row by its ending's tone, with a one-character gutter for what
it waits on:!for a ruling,>for an action; - a heading of who must act, and a closing endings tally;
- new filters:
--ending <word>,--needs-operatorand
--hide-settled.
- each row by its ending's tone, with a one-character gutter for what
- Every comparison counts the work by its ending, and says what it
excluded (#1016).
brokkr analyticsreads a migrated journal's rows, not every run
(decision 0089, slice 4;
#753).- The rows. The store keeps each checkpoint's and each seat's dated
facts, and finds a window's runs, parks, spends and sites through
indexes, one row at a time
(#1009,
#1024,
#1028,
#1041,
#1042). - The figures are accumulators: each grouped figure holds at most 64
groups plus an "N more" count, and medians are selected in passes
(#1029). - When the rows are used. A migrated, ready hearth is read from its
rows alone, with no fleet read
(#1057,
#1061,
#1068).
Any other hearth, and any run the store leaves whole, keeps the whole
read, and every figure equals the whole read's. - The probes are bounded. A store-kept set of the runs whose seat
rows lag bounds the fallback, and the readiness probe reads only the
unreadable rows
(#1072,
#1075). - The run view's paged reads count and rank a participant's
checkpoints by key, so the read no longer grows with the run's history
(#1022).
- The rows. The store keeps each checkpoint's and each seat's dated
- dsh hands and route overlays
(#1052).- dsh 0.2.2-rc.1 is a measured hands release, with its own composed
row set (#1056,
#1063,
#1083).- A hands launch reads its release once.
- The composed tree's sandbox mode is judged against the seat's.
- A route declares its overlay once. A dsh adapter's route may
declare{egress, overlay: {file, sha256}}. Every seat on that route
gets the overlay as one--patch, bound by path and digest
(#1065). - A local route's endpoint. The route-overlay grammar admits an
http://endpoint only when its host is a single DNS label, and
refuses every IP-literalhttphost
(#1053).
- dsh 0.2.2-rc.1 is a measured hands release, with its own composed
- Journal backups bound what a restore reads
(#945). - Decisions accepted:
Fixed
- A masked refusal's words are bounded again, by a pure truncation
after masking. This was 0.13.1's known issue: a long secret name could
make a refusal unreadable
(#1005,
#991). - A gone descendant ends its attempt. A same-identity zombie counts as
ended (#1021,
#970). - The fleet reads the newest behind runs first, so a TUI no longer
hides running lanes behind never-folded rows
(#1019,
#1017). - Dependencies:
- CI and tests:
- brokkr-cli's lib tests can no longer hang on a shrunken pipe
(#1013,
#1003); - a test binary past its bound fails its shard by name, at 2,400 s, and
the shard runner ends a group whose stuck member it cannot trace
(#1027,
#1033,
#1060,
#1067,
#1087); - the fleet bench's journals are generated outside Valgrind, so the CPU
budgets finish inside their hour
(#1031); - GitHub-hosted Linux jobs are pinned to ubuntu-24.04, macOS test
machines get 60 minutes, and the pinned release tools come from the
cache
(#1051,
#1055,
#1034); - the flake's digests match v0.13.1
(#1010).
- brokkr-cli's lib tests can no longer hang on a shrunken pipe
Upgrade and compatibility
brokkr operator stop and brokkr conclude require --cause.
- The causes are the six operator-owned endings:
superseded, which requires--by-runand takes--by-realm;infrastructure;delivered-elsewhere, which requires--by-ref;withdrawn;exhausted;operator-stopped.
- Without a cause, the command fails as a usage error (exit 2) before
any journal is opened. Add--causeto every script that stops or
concludes a run (#1006).
A run is held by its driver.
- A second driver refuses. A second process driving a run refuses at
once, andbrokkr concluderefuses a run its driver holds. Stop the
driver first, withbrokkr operator stop. - The lock files stand in
<journal>.runs/, a directory of mode 0700. - Where the lock holds. It is a
flockand holds on Linux and macOS. A
filesystem whereflockdoes not exclude is outside the guarantee. - An engine older than 0.14 takes no run lock, so 0.14 cannot see it.
Finish a 0.13 run with 0.13
(#1080).
After a run ends, only an annotation is written.
- Late writes refuse. A late driver, or a stop after a conclusion, now
refuses instead of leaving the run unfoldable
(#1078). - A run that is already broken is repaired with
brokkr operator repair
(#1085).
A rate-limited run waits instead of parking, once the host declares
bounds.
- Declaring them. Declare
cooldownsinforge.host/v2or v3. With
no declaration, decision 0006's path is kept, and the cap's reason names
the absent declaration. - Past the maximum. A wait past
max_secondsstill parks, naming the
cool-down
(#1007,
#1026).
The host file reads more strictly.
- Versions: one reader reads
forge.host/v1, v2 and v3. - A present
nullrefuses, in every version, v1 included. It is never
read as an absent key. - Numbers are read exactly.
10.0and1e1read as 10, and1.5
refuses (#1007).
The journal migrates itself.
- Queue storage moves from version 3 to version 6 at the first writing
open: - The additive repairs and backfills run at the same open, one run per
transaction:- a checkpoint's dated facts and turn;
- a seat's facts;
- a participant's stream ordinal;
- the run summary's head trigger;
- the stale-seat set and the readiness index;
- the terminal-event index;
- the late-tail column.
- A read-only open migrates nothing.
- An older binary. The queue storage is additive. A 0.13 binary still
reads a migrated journal, and only its queue verbs refuse a queue
version it does not know, as 0.13.1's own storage rule states. Upgrade
every binary that runs queue verbs on a journal together. - Schema versions:
database_schema,event_schemaand
driver_protocolall stay 1. The view version moves from 28 to 30: 29
for the typed ending, 30 for the late tail.
New contracts, each additive:
forge.host/v2andforge.host/v3;provider-wait.v1;operator-repair.v1;evidence-archive.v1;operator-settle.v1.
Drivers of your own.
- A
rate_limitrefusal underdriver-refusal.v1now starts a
cool-down and a probe: one turn on the refused candidate's own adapter
and launch path. - A quota or usage limit is read as a rate limit with its own reset
(#1026,
#1058). - The probe. Every shipped model adapter (claude, codex, dsh and
lanetally) advertisescapabilities.probe. The exec adapter, which has
no model turn, does not.
Building from source and the crates.
- The MSRV is Rust 1.89
(#1044). - brokkr-protocol now depends on brokkr-core
(#1025). - brokkr-runtime's public API grows, and
evidence::retirementis
removed (#1047).
The snapshots inquality/public-api/name every item.
Finish or conclude 0.13 runs with 0.13. Bundle digests cover the
engine version, so a pinned resume of a run started under 0.13 refuses.
brokkr conclude --cause … closes one from its journal alone.
Accepted, not yet in this build
- Decision 0106: a park names its cause, a long reset is a held wait an
operator can lift, and a declared retry budget
(#1035).
Its first slice, the typed park cause, is in progress. - Decision 0107: a scoped gate grant
(#1052). - Decision 0068's dispatcher pass (#430 slice 6). The queue, its
claims and its cool-down hold are here. - Decision 0089's remaining units: Muninn's queue and the store rows'
last heap budgets
(#753).
Still proposed: decision 0109 (a gate's re-visit reads what changed,
#1088).
Known issues
- A provider's reset past the declared maximum parks the run. This
happens with a quota that resets days away.- A retry after that park starts a new effect at the cooled link, so a
model chain does not step down to its next link on its own. - Retry the run once the reset passes, or move it to another crew.
- Decision 0106's held wait and lift are the fix
(#1035).
- A retry after that park starts a new effect at the cooled link, so a
route_overlay_driver's tests fail intermittently on hosted macOS
merge-group runners
(#1082).- Settle's LOW follow-ups.
- A boxed dsh hands seat has still not run end to end through
brokkr driveron a measured route
(#953). - The known issues listed in v0.13.0 that
this release does not address still apply.