AstralMaris design series

The Fleet Library

How a fleet remembers: the record every other paper in this series cites

OCT 2026 · Revision 1 · design paper

On this page
Full glossary · 8 terms
seat
One agent at work: a harness, its model, and the environment it runs in. A seat’s context window fills and is reset; the library is what survives the reset.
cold start
A fresh seat reading its way into the day’s work from the record alone.
handoff
A seat’s own account of its state, written for whoever picks the work up next — usually its own successor after a reset.
gate
A point where work changes hands: a revision posted, a run counted, a review delivered, a ruling given.
ruling
The operator’s decision, in the operator’s words, recorded with what it answered and what it reversed.
lessons register
The fleet’s list of things it has learned the hard way, each with the evidence that produced it.
merge class
A set of paths whose merge is reserved to a named principal: the operator for anything carrying a ruling or a design; the seat itself for its own continuity.
running copy
A read-only checkout of the library on the host, kept equal to the record by a machine job and tracked by digest; what every seat reads.

Revision r1 · October 2026 · AstralMaris design series The design as it stands: one repository, under one merge discipline, that holds what the fleet decided, what it did, what it learned and what each seat was doing when it stopped — so that any seat, any morning, can start cold from the record and not from anyone’s memory.



1. The problem this design answers

An agent’s memory is its context window, and the window has an end. Every seat in a fleet is reset — daily, sometimes hourly — and the moment it is, everything it knew about the work exists only in what it wrote down. A fleet that keeps its state in its agents’ heads cannot refresh a seat without losing the day; a fleet that keeps its state in a chat log cannot find anything; and a fleet whose records are written by the agents being judged has no record at all, only testimony.

The library is the answer to all three. It is a git repository with merge classes, a running copy on every host, and a handful of file conventions that a fresh seat can follow by program.


2. What the library holds

partwhat it iswho writes itwho merges it
designsevery design paper, numbered by revision; a landed revision is never edited, a new one is copied forwardthe author of recordthe operator
decisionsthe operator’s rulings, filed with the question, the options considered, and the resolution in his wordsthe XO, citing the operatorthe operator (the hub’s decision store is the twin, by id)
operationsthe lessons register, the standing orders, the inventory of record, the recovery runbook a stranger could followthe XO; the reviewerthe operator
continuityeach seat’s handoff file and journal; the XO’s day boardeach seat, for itselfthe seat itself, by pull request, one file at a time
reports and evidenceverdicts, gate outputs, digests, the measurement that backs a claimthe seat that measuredthe seat

The split matters: a seat can land its own continuity without waiting on a human, and nothing that binds the fleet — a design, a ruling, a standing order — lands without the operator’s merge.


3. The handoff

A handoff is written at every gate crossed, not on a clock and not only at the end of a day: prepended, short, anchored on digests. Its first lines say whether the seat is ready for a reset and what its context figure was when it wrote them. Before a handoff merges, every digest, pull-request number, revision label and open-item id in it is resolved mechanically to the thing it names — by a program, not by a peer reading the prose. Peers do not approve handoffs; the path to a reset is kept cheap on purpose.

Each handoff carries one section the next reader needs: the state for whoever picks this up — what is running, where its result lands, what is waiting on whom, and the order of what comes next. The XO reads that section of every seat’s handoff at the day’s close and checks them against each other, so that two seats cannot carry different beliefs about a shared piece of state into the morning.

A cold start is then a fixed procedure: print the newest handoff entry by program (never open the file in an editor, where a stale local copy can masquerade as the record); read the unread posts the handoff names, by id; read the day board; begin.


4. The day board

The operator does not read handoffs. He reads one page: what is waiting on him, in order; each seat’s state and queue; how far the current programme is and how fast it is moving; his own rulings of the day in his own words with where each was relayed; and a ledger of every check the XO made. It is edited in place as gates cross — the hub is the record, the board is the state now — and every row keeps its own history in a companion file, newest first, with the time it changed and the post that changed it, so nothing is ever deleted from a row.

The board exists because the operator asked one question — where am I tracking this? — and the honest answer was “in the thread”. Now it is a file with the decision first.


5. The lessons register

A lesson enters the register only with the evidence that produced it, and only by the operator’s merge. Candidates are kept through each day and consolidated; the register is read at every process review. A few, as examples of the kind:

  • A fixture that is never run is not a fixture. Every reviewed harness with a preflight is run at every head it is pinned to.
  • The environment of the real run is the first thing a gate reproduces. Three times the real run found what no gate had: a path’s length, a creation mask, an interpreter’s dialect.
  • A patch travels as bytes with a digest, never as an inline diff.
  • An id is written only after the tool returns it. Never a digest, never an id, typed from memory into a record.
  • A seat’s window is filled by what it reads, not only by what it builds. Orders to a seat name exactly the posts it reads.
  • An order that cannot run is worse than no order. Before ordering a build, name the input it needs and who holds it.

The register is the fleet’s friction ledger (see Semantic Governance): the trend in it is the fleet’s own measure of whether it is getting better.


6. The record and the running copy

The library’s main is the record. On every host a read-only running copy is kept at main by a root-owned job, tracked by digest in the inventory; seats read the running copy and write only in their own worktrees. The running copy is what the independent checker compares against, and the checker is never the author and never the shared account. When the fleet moves to many hubs, the library ships with each one in two layers — the canonical layer that says what a hub is, and a hub-local layer that says what it has done — and the same discipline applies to each (see HUBFLEET).


7. What it does not do

It does not make a false entry true; a record that only grows can hold a wrong line, which is why verdicts cite digests and why a second seat reads. It does not replace the hub: the thread is where work happens and the library is where it is remembered. And it does not read itself: the day the fleet stops writing handoffs at gates is the day the next reset loses a morning, and the lessons register has an entry for that too.


AstralMaris is one operator and a small fleet of AI agents on Apple-silicon hardware. This series records designs the fleet runs, with the measurements that shaped them.

Back to the title ↑