Skip to content

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

Choose a tag to compare

@github-actions github-actions released this 16 Nov 16:02
· 79 commits to main since this release
v0.14.0
88d15e2

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 analytics read 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, as StoreError::AfterTerminal. It
        writes no event, no cool-down row and no projection.
      • A late driver ends typed, EngineError::ConcludedBeneath, and
        writes nothing.
      • stop, retry and a member retry on a concluded run print why and
        journal nothing. classify and supersede still land.
    • 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-blocking flock on
        <journal>.runs/<run-id>.lock before its first append.
      • A second driver refuses at once: "run '…' is driven by pid P on this
        host since T (engine V)".
      • brokkr conclude tries the lock first, and refuses a run its driver
        holds before writing anything.
      • operator stop and retry take no lock and stay lawful on a live
        run.
    • 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/commanded annotation whose args are the
        new operator-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.
    • 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/commanded annotation under the
        new operator-settle.v1, read by type and never by its word.
    • 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.
  • 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's cooldowns
      block (#1007):
      • default_seconds and max_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.
    • 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.
    • 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).
  • 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/v3 may declare timeout_floor_seconds, at most 7200. It
      raises the deadline of an attempt on that route and never shortens an
      authored one
      (#1039).
      • A panel's and a sequence's words name a raised deadline and an
        unreadable host
        (#1066,
        #1071).
      • An unreadable host file keeps the seat's own limit, and says so.
    • Seat trees are recorded. Each run-local seat scratch tree is
      recorded in queue storage v5's seat_trees before it is made
      (#1073). Each
      complete removal goes in v6's tree_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 doctor names each directory under a recorded root that no
        open row records, and removes nothing.
  • An operator retires a historical evidence root, with a record
    (decision 0105;
    #1020).
    • brokkr evidence list lists 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 new evidence-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).
    • stop and conclude name the ending. brokkr operator stop and
      brokkr conclude take --cause, one of the six operator-owned
      endings, recorded under operator-ending.v1
      (#1006).
    • Every row carries it. A run's summary row carries its typed
      ending, its citation and whether a classify stood over an earlier
      ending, on /api/runs, /api/view, inspect --json and
      brokkr runs (#1014).
    • brokkr runs paints 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-operator and
        --hide-settled.
    • Every comparison counts the work by its ending, and says what it
      excluded (#1016).
  • brokkr analytics reads 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).
  • 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-literal http host
      (#1053).
  • Journal backups bound what a restore reads
    (#945).
    • The copy. A restore's copy reads at most its inventory's byte
      count, so a journal.db linked to /dev/zero refuses
      (#1062).
    • The inventory. It is read under one 16 MiB bound on both ends, and
      only from a regular file, so a FIFO cannot block a restore
      (#1097).
  • Decisions accepted:
    • 0104, shared local hardware
      (#1018);
    • 0105, retiring an evidence root
      (#1023);
    • 0106, a park names its cause, a long reset is a held wait, and a retry
      budget (#1098);
    • 0107, a scoped gate grant
      (#1059);
    • 0108, a run held by its driver
      (#1077).

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:
    • rusqlite 0.41.1, which bundles SQLite 3.54.1, for RUSTSEC-2026-0459
      (#1044);
    • rustix 1.1.6, past RUSTSEC-2026-0486
      (#1076).
  • 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).

Upgrade and compatibility

brokkr operator stop and brokkr conclude require --cause.

  • The causes are the six operator-owned endings:
    • superseded, which requires --by-run and 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 --cause to 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, and brokkr conclude refuses a run its driver holds. Stop the
    driver first, with brokkr operator stop.
  • The lock files stand in <journal>.runs/, a directory of mode 0700.
  • Where the lock holds. It is a flock and holds on Linux and macOS. A
    filesystem where flock does 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 cooldowns in forge.host/v2 or 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_seconds still 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 null refuses, in every version, v1 included. It is never
    read as an absent key.
  • Numbers are read exactly. 10.0 and 1e1 read as 10, and 1.5
    refuses (#1007).

The journal migrates itself.

  • Queue storage moves from version 3 to version 6 at the first writing
    open:
    • v4 adds provider_cooldowns
      (#1070);
    • v5 adds seat_trees
      (#1073);
    • v6 adds tree_sweeps
      (#1079).
  • 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_schema and
    driver_protocol all 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/v2 and forge.host/v3;
  • provider-wait.v1;
  • operator-repair.v1;
  • evidence-archive.v1;
  • operator-settle.v1.

Drivers of your own.

  • A rate_limit refusal under driver-refusal.v1 now 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) advertises capabilities.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::retirement is
    removed
    (#1047).
    The snapshots in quality/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).
  • route_overlay_driver's tests fail intermittently on hosted macOS
    merge-group runners
    (#1082).
  • Settle's LOW follow-ups.
    • A reseal refused with Unsealed can leave its own successor standing
      as the record. Nothing removed comes back, and no name that was gone
      is made.
    • Two field clauses are untested
      (#1099).
    • A durable unproven marker is owed
      (#1086).
  • A boxed dsh hands seat has still not run end to end through
    brokkr driver on a measured route
    (#953).
  • The known issues listed in v0.13.0 that
    this release does not address still apply.