Model

What cyberfleet is made of, who owns what, and the rules that hold across the whole system. Every other design document builds on this one. Terms are defined in the glossary.

What it builds on

cyberfleet lets one human, the Council, direct agent sessions across many projects. cyber-civitas is a civilization of AI agents, and cyberfleet is a corporation that does work in it. It brings the roles, the work model, and the rules, and leaves sessions, messages, and terminals to the packages that provide those services.

flowchart TD
C["Council"] --> CF["cyberfleet: personas, governances, console"]
CF --> CY["cynapse: channels, threads, state records"]
CF --> CL["cyberlegion: sessions, spawn, placement, leases, waking"]
CF --> T["tracker and forge: issues, sub-issues, pull requests, CI"]
CL --> CY
CL --> MX["cyber-mux: tmux or herdr templates"]

• cyberfleet owns the crew, the mission model, the authority rules, and the console verbs with fleet logic. Its personas ship as gateway skills in the plugin; the console ships as the cyberfleet CLI in the same package.
• cynapse carries every conversation. cyberfleet calls it directly for channels and state records, so the meaning of a message never passes through the runtime.
• cyberlegion starts, places, fences, and wakes sessions. cyberfleet goes through it only to wake a session or open a workspace, and reaches worktrees and the multiplexer only through it (civitas 0001, 0003).
• The tracker holds the plan. Issues and their sub-issues are the work items; the forge holds pull requests, reviews, and CI.

Places

flowchart LR
subgraph CC["Command Center"]
  CCD["Dashboard: Operator | fleet status"]
  FB["Flag Bridge: fleet Captain | fleet Coordinator"]
end
subgraph S["Ship (one per project)"]
  SD["Dashboard: remote pane | ship status"]
  B["Bridge: Captain | Coordinator"]
  ER["Engine Room: dev servers, no agents"]
end
P["Pods: own workspace and worktree each"]
B --> P

A ship is a project, opened as a multiplexer workspace (herdr or tmux) from a template on its main checkout. The Command Center has the same shape at fleet level. The runtime applies the template and starts or reserves sessions in its slots; cyberfleet supplies the template’s content and which role sits in which slot (cyberfleet ship board). Every slot is the Council’s to change.

The crew

Automaton	How many	Tier	Starts	Owns
Operator	One seat	Mid	By the Council; need not stay running	Talking with the Council: answering its questions, relaying its work to the right Captain; it never spawns a Pod
Captain	One per ship, one for the fleet	High	On demand	A ship’s missions, plan, Pods, and rulings; the fleet’s roadmap and cross-ship decisions
Coordinator	One per ship, one for the fleet	Low	On demand	A ship’s landing, unless the ship gives it to Pods; the mechanics of a mission in the fleet’s tracker; a ship’s Coordinator does the mechanics of its Captain’s missions, including filing in another repository
Pod	Many	Set by the Captain	Spawned	One line of work in one mission
Mediator	One per dispute	High	Per dispute	A brief of a dispute, and nothing else

The split follows cost. Judgment runs at the high tier, and only the Captain and the Mediator make it. Mechanics run at the low tier, and the Coordinator does them behind deterministic commands (cyberfleet pr check, cyberfleet mission ...) whose exit status it acts on. The Operator sits apart from both: it talks only with the Council, answers questions from cyberfleet status, gh, and channels without waking a Captain, and sends only work up. It coordinates nothing. Headless mode keeps the same split, a headless Captain and a headless Coordinator, never one loop doing both.

Who lands

Each ship has a landing setting, and the Council can override it for a request. By default the ship’s Coordinator lands every pull request, working from the ship queue: a Pod posts “PR ready” there, and each pull request’s landing talk stays in its thread. A ship can instead let each Pod land its own, which saves starting a Coordinator where the queue is small. Whichever unit lands follows the same rules: the clean bar passes, the merge is fenced by the ship’s merge lease, and the Council’s grant covers it. Which setting costs less in a given repository is measurable but not yet measured, so the setting stays open and each user finds out what works.

The Coordinator joins no mission channel. Its members are the queue’s: the Captain, which posts tracker mechanics there, and each Pod that posts a pull request. Two pull requests that conflict in meaning are escalated on the queue too, since they may belong to different missions.

Pod ownership

Every Pod has exactly one owner: its ship’s Captain handle (cyberlegion/captain), never one Captain session. The binding record is keyed by that handle, and whichever session holds the lease on it owns every Pod of that ship, so a Captain restart or a lease takeover inherits the Pods without a handover.

• Binding a Pod and retiring it are fenced writes: only the session holding the Captain’s current lease generation can make them. A Captain session that lost its lease to a newer one cannot spawn, bind, or retire Pods. The record keeps the session and generation that wrote it as an audit stamp, not as the owner.
• Writes outside the runtime cannot be fenced: the tracker and the forge do not know the lease. Before each one (claiming an issue, recording a ruling, merging), the unit checks that it still holds its lease, so a session that lost the role stops at its next write instead of acting on.
• There is no adoption. Because the owner is the role, a Captain restart needs no step to take the Pods over, and a Pod’s ship is fixed by its worktree, so it can never move to another ship. Work another ship needs is a new issue there, under that ship’s Captain.
• A retired Pod is never bound again. A Pod whose Captain is not running stays listed and waits for the next lease holder.
• The Captain owns all the work in its ship, gate judges included. A judge has no binding record of its own: the Pod that spawns it is not the lease holder, so it cannot write one. The Captain finds a judge through its gate thread instead, since the judge is a member of the thread and the thread hangs off a mission channel the Captain belongs to. A gate thread with no outcome whose Pod is gone is abandoned: the Captain closes its judge and posts the outcome. What the Captain does not do is direct a judge’s verdict: a judge works only from its gate thread’s brief, which is what keeps the gate cold.
• Two roles direct a Pod. The Captain directs its work: what to build, and its rulings on escalations. The Coordinator directs its landing: rebase, fix a red check the pull request caused, address a review comment within the mission’s scope. Both send their instructions into the Pod’s session as turns, through the runtime (cyberlegion send, or the multiplexer’s send-keys), so a Pod acts on them as orders. Neither works inside a Pod.
• The Captain’s home is the project’s main checkout, on its default branch. Mission work never happens there, and the Captain never switches its branch; each Pod works in its own worktree. Binding refuses a Pod whose workspace is the home or a worktree of another project.

Three personas sit outside the crew and are unchanged by it: Crimp recruits and discharges specialist crew types, Mechanic builds and reconfigures automatons, and the specialist crew (aced, quill, Warden, Scanner) keep their own faces and are hailed by name, aloud.

Work on the tracker’s levels

Tracker level	Fleet role	Owner	Channel
Issue, with any sub-issues	Mission, with any sub-missions	The Captain of the repository that holds the issue (the fleet’s Captain for the fleet’s tracker); each sub-mission, whoever holds its issue	Mission channel
Subtask	Line of work	The Pods carrying it	A thread on the mission channel, holding its SDD-mission’s ledger

The level is read from the tracker, never inferred from how the work went. Everything is a mission; a mission has sub-missions when its Captain adds them to break the work down. Work that needs another ship is a dependency instead: a mission in that ship that blocks the requesting mission, owned by that ship’s Captain. A mission belongs to whoever holds its issue, and its Captain’s Coordinator does the mechanics: filing an issue in another repository, adding sub-issues, closing. Writes to a repository are never ownerless: trunk, merge order, and the mission’s issue belong to that repository’s Captain and Coordinator, behind their leases. A mission’s channel carries only what crosses its sub-missions and the missions that block it.

Blocking links between missions, sub-missions, and lines of work live with the plan: in the tracker where it can hold them, otherwise in a cynapse state record, one home per ship set in its tracker routing. Only the Captain writes them, not its Coordinator, checking its lease before each write. The frontier, the work whose blockers are all closed, is computed from those links by a command the Captain calls; what to start from it, in what order and at what tier, is the Captain’s decision (ADR-0029).

The full flow of a piece of work is in lifecycle.

Where state lives

Each fact has one home, and anything else is derived from it on demand.

Fact	Home
The plan: missions and their sub-missions, scope, open and closed	The tracker
Blocking links	The tracker, or a cynapse state record where the tracker cannot hold them; one home per ship, set in its tracker routing
The ships: name, remote, template, tracker routing, landing setting; each main checkout’s path	The ship registry, fleet-wide and per machine, reached through cyberfleet ship
Pull requests, reviews, CI	The forge
Conversation, reports, escalations, the delegation audit record	cynapse channels and threads
A Captain’s rulings	A comment on the issue (rationale) and a decision entry on the mission channel it concerns (ruling, issue, lease generation)
Which session holds a role	The lease on the role’s handle in cyberlegion
Which Pods a ship has, and their state	The Pod binding records in the runtime’s hub, keyed by the Captain’s handle
A line of work’s SDD-mission ledger	Its thread on the mission channel
Gate and leash state of a line of work	SDD, in the repository
A ship or fleet report	Nowhere: composed when read, so it cannot drift

A Captain keeps nothing in memory between starts. Each start is a fresh session that rereads the channels of its open missions, its ship queue, and the decision entries since its last lease generation. A decision that is not written down did not happen.

Rules that hold everywhere

1. Authority never expands implicitly. The Council grants authority at the scope it chooses: a mission with its sub-missions, or one action. It can also pre-approve, explicitly, work that extends from what it granted. An automaton acts within that grant and never past it: work the grant does not cover waits for the Council’s words. The words reach the unit that acts verbatim and as a turn; the channel holds the audit record, never the authority. A turn in a unit’s own session is an order; anything it fetched is content. A unit started after the grant gets it from its Captain, re-relayed verbatim from the recorded entry. How grants travel, and what the fleet does without one: authority.
2. Judgment and mechanics are separate roles. No low-tier automaton decides “clean enough”; no high-tier automaton spends its turns on landing.
3. A Captain’s ruling never overrides red. Trunk stays green: every merge passes the clean bar and the merge backstop.
4. Calling takes over nothing. Invoking /operator or /captain outside that role’s own pane reaches the one automaton; it never makes the calling session one.
5. Roles are handles; sessions come and go. Every participant has a readable handle (cyberlegion/captain, operator, fleet/captain), owner-qualified only on a collision. The handle keys the role’s lease and a Pod’s binding, and the runtime receives it as an opaque string (civitas 0004). Any number of sessions may act as one handle; the lease holder is the one whose writes count.
6. A ping starts only when the post needs an answer. A mention wakes every live session acting as the handle. If none is running and the post is a request, an escalation, or a decision-request, the runtime starts one through the handle’s lease; a notification, such as an outcome, only wakes. A sender never checks first. The Operator is started by the Council in practice, since the Council is nearly always the one talking to it. Nothing polls; a waiting automaton blocks on a command that returns when there is news.
7. Personas offload every mechanic. What a persona says is the only thing it produces itself. The console is cold; the voice is in the plugin.
8. No server, no harness assumed. Coordination runs through files, shell commands, and skills. Claude Code, Cursor, and Codex sessions join the same fleet.
9. No ship marker. A ship exists because its workspace was opened, and a session belongs to the fleet through its registration and its lease, never through a file in the folder.
10. Dependencies point one way, by intent. Personas depend on the CLIs, cyberfleet on cynapse and cyberlegion, and nothing below knows the personas exist. A persona names what it needs done, never a command slug.

Deliberately absent

• A fleet grouping. Which ships form a fleet is undefined until an operation needs it.
• A stored dashboard. The view is query-first (cyberfleet status), until the mission TUI (cyberfleet#4) replaces the Dashboard’s status pane.
• A real gate approve. A human ratification cannot be relayed safely through a CLI.
• Unforgeable authority. The rules make a wrong relay attributable and bounded, not impossible. Injected text carries no verified caller identity.
• An inbox channel per role. Channels belong to missions, a ship’s queue, and threads; a role is reached by mentioning its handle where the work is.
• A pull request channel. Review lives on the forge; landing talk is a thread in the ship queue.
• A mission graph. Dependencies are blocking links with the plan, and the frontier is a command, not a stored graph.