Fleet: the contracts of the Task core
Fleet runs agent sessions through Task resources and their controller. A Task is one agent session doing one brief. This file says what each part guarantees and which tests hold it to that. The overall architecture explains the component boundaries. The Task controller guide defines the resource fields, state machine and controller interface.
What is served #
Resource kinds lists every kind, who writes its
spec and who writes its status.
kinds::status_owner is the rule
the store enforces on each status field.
Kinds not built in or registered by a plugin are refused on write as unknown kind "X". A Task spec
accepts the fields below (deny_unknown_fields), and no object may carry
ownerReferences.
The Forge controller is a second
controller over the Task: it follows the changes a worker declared and
relays their feedback into the Task's inbox, a status field with no single
owner, status.inbox, reached only through the typed mutations under
Store, which refuse a duplicate key. fleet send and the Forge
controller append to it and TaskController delivers it. The Forge
controller's one effect, mark-ready, is the only write Fleet makes on a
forge: it takes a declared draft out of draft under a configured ready
policy, and nothing else.
The Plugin controller hosts external
controllers. The store serves their schema-validated
kinds; the manager calls their pure
probes and reconcile calls and bounded observe and perform calls through
the Plugins port's one call. A pure gate admits plans before leased status
writes and atomic verbs. e2e_plugin_controller and plugin_gate exercise the
host.
The CronTask controller creates a Task at each
scheduled time of a CronTask, intent before the create and receipt after,
under a key and a name that the scheduled time fixes. It adopts a Task that
carries its uid and never creates a second one. e2e_cron_task holds it
to that, on the file store with a test clock.
The Gateway controller is three controllers over
the Gateway port in fleet_api::gateway. The fleet-gateway adapter
crate depends on no Fleet crate but fleet-api and fleet-exec, and has a
file-backed fake that models every capabilities combination. The CLI
loads and validates the [gateway] config, and opens its accounts before a
manager run so that the lease outlasts the port's worst case.
ConversationController keeps the mirror,
admits a thread and creates its Task under the workspace precondition.
ListenerController judges an account's listener. GatewayController owns
status.gateway, relays the thread into the inbox under a cursor and a
child's words into its parent's inbox (talking in a
conversation), and plans Post, Open,
Receive, Log and React actions. The manager performs Post, Open,
Log and React through the Gateway port and Receive through the
store, and writes a receipt under each key. e2e_gateway_post,
e2e_gateway_logs and e2e_gateway_reactions hold it to that.
Crates and the allowed graph #
fleet-api pure types and ports
fleet-controllers pure controllers and gate -> api
fleet-exec adapter the one process spawner
fleet-store adapter file store -> api
fleet-runtime adapter exec, fake, term-bridge -> api, exec,
term-stream, otel-env
fleet-forge adapter az, curl, gh, glab, fake -> api, exec
fleet-gateway adapter curl (Slack, Discord), fake -> api, exec
fleet-plugin adapter bounded plugin stdio -> api, exec
fleet-manager orchestration lease, plans, verbs -> api, controllers
fleet-cli edge the `fleet` binary -> api, manager, store,
runtime, forge, gateway, plugin, otel-env
arch-rules tooling the architecture test
fleet-dev tooling `cargo xtask`: gate and release
crates/architecture.toml declares the graph and these rules, and the
architecture test of arch-rules enforces them on every gate run:
- Both the declared and the actual crate graph are acyclic, and every actual edge (normal, build and dev dependencies, renames included) is declared.
- A pure crate reaches no filesystem, process, network, environment, thread or clock, and uses only the external crates its rule lists. Paths are resolved through aliases, globs and re-exports first, across crates.
- No crate reaches another crate it may not depend on through a third crate's re-export.
- Only the crates listed may name a status-writing field manager; the
check is per crate, and fleet-api, which defines them, may name every
one. Only fleet-controllers names
FieldManager::TaskController,FieldManager::ChangeRequestController,FieldManager::ForgeController,FieldManager::GatewayController,FieldManager::ConversationController,FieldManager::ListenerControllerandFieldManager::CronTaskController, only fleet-api and fleet-controllers nameFieldManager::Plugin; only fleet-manager'sresultanddeclareverbs nameFieldManager::Worker, only fleet-manager'ssendandamendverbs (and the store that checks them) nameFieldManager::Cli, the caller of the inbox append and of the amend mutation, and only fleet-manager'sreceiveverb (and the store) namesFieldManager::Listener, the caller of the spool and beat mutations. - The CLI calls no store write, no controller method, no runtime effect and no forge read: it parses, calls a fleet-manager verb, and prints.
- Only fleet-exec reaches
std::process::Command,std::os::unix::process,std::os::windows::processorprocess_wrap. Every program fleet runs is bounded and has its whole process tree killed past its bound or on an early return: a process group on Unix, a job object on Windows. The one program with no bound is the command a bridge runs on a pty (fleet_exec::pty), since its view ends it: it is killed when its handle is dropped. - fleet-forge depends on nothing above the API and the spawner and is depended on by the CLI alone: no forge-specific name appears above the Forge port.
- The Forge port itself, which carries the one forge write, is held only by
fleet-api, fleet-forge, fleet-manager and fleet-cli: no other adapter and
no controller can reach
mark_ready. - fleet-gateway, likewise, depends on nothing above the API and the spawner
and is depended on by the CLI alone, and the Gateway port, which carries
the chat writes
open,postandreact, is held only by fleet-api, fleet-gateway, fleet-manager and fleet-cli. The CLI may not call the port'shistory,capabilities,postorreact. - otel-env, the telemetry crate every program shares, depends on no
other crate of the repository. Only otel-env reaches
opentelemetry_sdkoropentelemetry_otlp: the providers, batching, exporter and shutdown bound are in one crate. The manager and the runtime adapter record through theopentelemetryAPI, a no-op without a provider; the pure crates reach no telemetry at all.
Each rule has a negative fixture that breaks it, and the test requires the
checker to report exactly that rule. The pure crates also carry
compile_fail doc probes for every forbidden edge.
Task #
spec.configRef optional TaskConfig reference
spec.env explicit environment overrides
spec.harness the agent harness, explicit or inherited
spec.host the runtime host (default "local")
spec.model optional; reaches the harness through its model variable
spec.pauseAfterMs optional; pause the session once its agent was idle
this long, over the TaskConfig's
spec.agentTelemetry optional; false keeps the agent's own telemetry off,
over the TaskConfig's
spec.brief the brief, sent once, never changed
spec.amendments append-only additions to the brief, through fleet amend
spec.workspace a list of absolute URLs; the runtime makes them
spec.dispatch nothing spawns while false
spec.outputs optional: the structured outputs a result must carry
spec.forge optional: relay and draft overrides for declared changes
spec.subscriptions optional: the Boards whose new events reach the inbox,
one notice per subscription
The spec is immutable once created, except dispatch, forge and
subscriptions; a
different brief is a different Task. amendments only grows, through the
store's amend mutation (amend_task for fleet amend, a plugin's amends[]
verb through plugin_mutate): update_spec, and so apply and a plugin
patch, refuses any change to it, and apply keeps the stored amendments
when a manifest omits them, and a manifest that creates a Task with
amendments is refused. harness, host and model are non-empty and
may not start with -, since they reach the runtime as arguments; whether
each is present never changes after creation.
spec.workspace names what the session works in. It never says how the
workspace is made. Workspace
defines both forms and their validation.
See execution configuration for reference validation, deterministic precedence and private launch freezing. New configuration kinds have no lifecycle, finalizers or status writers.
Task lifecycle #
TaskController is a pure function from the Task and what the probes saw to a plan: the status to write, the effects to run, and whether to drop the finalizer. The manager performs it in this order:
- Intent first. The status carrying each effect's intent is written (compare-and-swap, under the lease) before the effect runs.
- Effect. Materialize, spawn, brief, release, revive, pause, resume or
clean, each under a deterministic key
(
task/<name>/<uid>/<action>[/<attempt>]). - Receipt after. The outcome is written as the key's receipt. An intent without a receipt is a question the next pass answers by observing the key, never by repeating the effect blindly.
Guarantees, each with its test:
- Workspace once. A Task with a non-empty URL list plans
Materialize, the runtime'sworkspacecall, undermaterialize/<n>before its spawn, with the session key as the workspace key.Spawnedwaits untilstatus.workspaceholds the whole workspace, and the spawn gets it asready. After an unknown outcome the controller asks the runtime again under the same key, which is idempotent: made is adopted, nothing made is retried afterRETRY_DELAY_MS, unreadable waits.MAX_ATTEMPTSrefusals stall the Task withWorkspaceReady=False/MaterializeFailed. A URL the runtime does not handle spends no attempt and waits withWorkspaceUnsupported. After the release, and also when nothing was spawned,CleanWorkspace, the runtime'sstopwithrelease, runs undercleanWorkspace/<n>. The finalizer goes only after aDeletedreceipt. A failed or unknown release is repeated after each wait, and three raiseNeedsAttention/CleanFailedwith the last failure. Past three, each wait doubles, up toRETRY_BACKOFF_MAX_MS(1 hour). A Task deleted while itsworkspacecall is unanswered releases the key without making anything.task_workspaceande2e_workspacecover each case. - Spawn once. The session key is
<name>.<uid>. After an unknown spawn outcome the controller looks the key up: found is adopted, absent is retried, unreadable waits. - Brief once. The brief is sent only to a ready session, under one key
the session stores. An unconfirmed send is asked about: delivered is a
recovered receipt, not delivered is one more send under the same key, and
"cannot tell" is retried after a wait. Three unreadable probes raise
NeedsAttention(BriefUnconfirmed); probes continue so recovery can settle it. A send the runtime only queued, where the agent does not read it, setsBriefed=False/BriefUndeliveredand raisesNeedsAttention; it is never sent again and holds the inbox. - Trust before the brief. The brief is sent only after the runtime
reports that the session's agent trusts its workspace. A known gap sets
WorkspaceTrusted=False, raisesNeedsAttention/WorkspaceUntrustedand is probed again after each wait. Unknown holds the brief, raises nothing and is probed again on the next pass. A held brief spends no send, and no inbox entry goes out before the brief. - Retries. Spawns and brief sends are tried at most
MAX_ATTEMPTS(3) times beforeStalledandNeedsAttention. Failed attempts waitRETRY_DELAY_MS(30 seconds), persisted asstatus.notBeforeacross manager runs. Unreadable delivery probes and failed releases raiseNeedsAttentionafter three attempts but continue after each wait: recovery can confirm delivery or remove the finalizer. A failed release backs off past three attempts: each wait doubles, up toRETRY_BACKOFF_MAX_MS(1 hour). - Unsupported URL. A
workspacecall answeredKnown(Unsupported { url })spends no attempt. The Task stays Pending withWorkspaceReady=FalseandNeedsAttention, both with reasonWorkspaceUnsupported. The call is tried again afterRETRY_DELAY_MS, without limit, under the same effect key. A later answer that is notUnsupportedclears thatNeedsAttention. - Unmapped trust. A spawn answered
Known(TrustUnmapped { harness })spends no attempt. The Task returns to Pending withSpawned=FalseandNeedsAttention, both with reasonTrustUnmapped, and the spawn is tried again afterRETRY_DELAY_MS, without limit, under the same key. A later spawn that does not answerTrustUnmappedclears thatNeedsAttention. - Result.
fleet resultwritesstatus.resultas field managerworker, only once the brief has a receipt, only forstatus.brief.generation, never while an amendment waits to be delivered (unless its delivery was given up), and only when its outputs matchspec.outputsplus the outputs of each amendment at or below that generation. The same result again is a no-op. Within one generation a different result is refused; a result for a newer generation replaces the older one. A result forstatus.brief.generationconcludes the Task. - Label.
fleet label task TASK KEY=VALUE…sets each label on the Task in one compare-and-swap write and changes nothing else: the spec, the generation and the other labels stay. A label only Fleet writes (the Conversation and parent labels, a plugin's creator label) is refused with exit 1.applycannot relabel a Task a Conversation made, since it refuses a manifest that carries those labels;labelkeeps them as they are, and leaves the creator label to the store, which keeps it on every update. - Amend.
fleet amend TASKappends{text, reason?, outputs?, from, at, generation}tospec.amendments, incrementsmetadata.generationand queues an inbox entry withamendsundertask/<name>/<uid>/amend/<generation>, in one compare-and-swap write. It needs no generation from the caller;--if-generation Nis an optional precondition, refused with exit 5. A Stalled or deleting Task, a full inbox, empty text and an output name already declared are refused. The brief's first send carries every amendment so far and records the generation of its intent, so an amendment queued before it is recorded without a send. A later amendment goes out as an inbox entry; a newer one queued behind an unsent one carries both, and the older is recorded without a send. Its receipt setsstatus.briefto its key and generation. A delivered amendment re-opens a Concluded Task to Briefed, withConcluded=False/Amended, and keeps the old result. A plugin'samends[]verb applies the same mutation and checks asplugin/<name>, with a requiredifGeneration: on any other generation the store refuses it, andhost.verbsrecords the refusal. - WorkerGone. A session a readable list no longer shows sets
WorkerGoneandNeedsAttention. An unreadable list is never read as gone. Nothing abandons the Task by itself. - Lost session. A session the runtime still holds without its agent's
window, as after a host reboot, sets
SessionLostand gets nothing sent. A dispatched Task plansReviveunderrevive/<n>, at once and then after eachRETRY_DELAY_MS. Three revives that leave the session lost raiseNeedsAttention/ReviveFailed. When each of them started the agent and its window still went away, its agent cannot resume it, as when the conversation it resumes was never saved:SessionLost=True/CannotResumeandNeedsAttention/CannotResumeare set, and nothing is revived until the window is seen again.fleet attachrefuses such a Task with exit 3 and opens no view on its dead window. Back, a briefed worker that has not concluded is owed one catch-up note undercatchup/<n>, sent before its inbox as an entry is sent. A revived Concluded worker is resumed plainly: nothing is typed into its conversation. In Briefed the note repeats the brief and its generation. A Concluded Task at rest has its session looked at on each recheck, and readsSessionLostwhen it is lost, but it is revived only for a delivery or for a view:fleet attachasks for it throughstatus.wakeRequestedAt, and a request younger thanVIEW_WAIT_MS(60 seconds) makes the recheck due at once and revives the session on its conversation. A concluded worker nobody looks at stays at rest. Unknown revives nothing, and a revive never makes a second session. - Pause. With
spec.pauseAfterMs, or the TaskConfig'spauseAfterMsfrozen instatus.execution, a dispatched Briefed or Concluded Task whose agent the runtime reports Known Idle on every pass forpauseAfterMs, and on the pass that plans it, plansPauseunderpause/<n>. Its harness profile must have a resume argv and its hooks must have reported its conversation, so aider and a program never pause. The session must be observed not stopped and not known lost, its inbox empty, and no brief, entry, catch-up note, revive or resume in flight. Active or Unknown clearsstatus.idleSince; the idle time starts again at the next Idle answer. Activity is what the agent's own hooks report throughfleet signal, never the runtime's; Unknown never pauses, and a runtime that cannot pause never answerspausedKnown false.Paused=True/Idlechanges no phase and raises noWorkerGone,SessionLostor revive.fleet pausesetsstatus.pauseRequestedAt. A request made after the lastPausedtransition and after the laststatus.wakeRequestedAtplansPauseunder the samepause/<n>and the same conditions, withoutpauseAfterMsand without reading the activity, and ends inPaused=True/Requested. A request that cannot be honoured yet waits and raises nothing. A request is acted on once: TaskController records it instatus.pauseRequestAnsweredwhen it plans the pause, so a refused pause (Paused=False/PauseFailed) is not tried again. - Resume. An inbox entry for a paused Task plans one
Resumeunderresume/<n>, and so does astatus.wakeRequestedAtat or after thePaused=Truetransition; entries that arrive meanwhile wait in the inbox. Resumes waitRETRY_DELAY_MSbetween tries; three resumes that leave the session stopped raiseNeedsAttention/ResumeFailed, and resumes continue. Back (Paused=False/Resumed), the agent continues its conversation. Fleet types no note of its own into it: only the inbox is delivered, and a wake with an empty inbox types nothing. A session found stopped by someone else isPaused=True/Externaland is resumed by the next entry. Stalled, held and deleting Tasks are never resumed. A missing or Unknown pause or resume receipt is settled by observing whether the session is stopped, never by a blind repeat. A catch-up note an older record keeps underresume/<n>is still sent under that key; new resume keys continue past it. - Release. The
fleet.dev/releasefinalizer holds a deleted Task until its session is deleted, once the session is proven at rest or gone, or onceRELEASE_GRACE_MS(5 minutes) has passed since itsdeletionTimestampwhile the session is busy or its rest is Unknown. A staleworkingreport therefore cannot hold a delete for ever. The workspace clean still preserves uncommitted work. - Inbox.
fleet send TASK TEXTappends{key, from, text, queuedAt}tostatus.inboxascli/<user>, undertask/<name>/<uid>/send/<n>,nthe resourceVersion appended against. The oldest entry not given up on is delivered as the brief is: to a session observed ready on that pass, under its key as the runtime intent key, one entry per pass, at most three sends. It counts as delivered once the agent's prompt hook reports its digest after the send's intent: a report of the same text before it proves an earlier send, not this one. A lost answer is settled by that report alone, never resent (the runtime's journal decides only for a harness with no prompt hook). A Known receipt moves the entry's receipt intostatus.deliveriesand the entry out ofstatus.inboxin one write, and drops its intent, receipt and attempt records. Three refused sends raiseNeedsAttention/DeliveryFailednaming the entry, which stays while later entries go out; three unreadable journal reads, or a typed entry whose prompt hook reported another prompt since the send and not this one, raiseDeliveryUnconfirmednaming the entry, which is never resent and stays while later entries go out; more than 20 entries still to deliver raiseInboxFull. An entry given up on does not count. Such an entry can never be delivered, so it can never make room. Nothing bounds the entries given up on. Each one given up on raisesNeedsAttention, which names the latest;status.deliveryAttemptsmarks every one as failed. Delivery runs in Spawned (after the brief, and after its proof where the agent has a prompt hook), Briefed and Concluded, which stays terminal and is due while its inbox is nonempty. At rest, a Concluded Task is due once everySESSION_RECHECK_MS(5 minutes), recorded asstatus.sessionCheckedAt, to look its session up and ask whether it is lost; a view's wake request makes it due at once. A readable list without the session there isWorkerGone, never a respawn. Stalled delivers nothing; deletion keeps precedence and refuses new sends. - No churn. A condition keeps its
lastTransitionTimeunless its status changes against what was stored, so a pass that sees nothing new writes nothing and the manager goes idle.
Conditions: HostReachable, WorkspaceReady, Spawned,
WorkspaceTrusted, Briefed, Stalled, WorkerGone, SessionLost,
Paused, Concluded, Released, NeedsAttention.
Following declared changes #
ForgeController is a pure function from the Task, the ChangeRequests its
worker declared, Fleet's login on their hosts and, when asked, whether the
session is at rest, to a plan: the desired status.forge, the inbox
entries to land with it, and the MarkReady effects whose intents it
carries. It has one effect and no finalizer, and never writes a
ChangeRequest. Guarantees, each with its test in forge_controller,
e2e_forge_controller and e2e_mark_ready:
- Declare.
fleet declare TASK --change-request URLparses the URL through the Forge port, ensures one ChangeRequest under the derived name (an existing one is reused after itsstatus.ref, else its own URL, is verified) and appends{kind, url, name}tostatus.declaredasworker, with CAS; a repeated URL, or any URL of the same change, is a no-op.--json OBJECTappends any object with a stringkind. Both need a brief receipt and refuse a deleting Task, and an ineligible Task creates no orphan; a crash between the two steps leaves a ChangeRequest nobody follows, which the nextdeclareof that URL finds. - Join at the present. A declaration whose object is Known with a
refgets an entry with the object'suidandcursor = revision, and one message holding the whole snapshot, undertask/<name>/<uid>/relay/<change uid>/<revision>fromforge/<name>; when the mirror has already dropped notes, the message says older notes exist on the forge. An object without arefyet, or Unknown, waits; readable absence, or an unreadable mirror status, raisesNeedsAttention/ChangeGone. - Relay by cursor. Every note with
seqabove the cursor that passes the filters (never this Task's own marked words; bots only perrelayBots; never a resolved thread or one this Task already answered in) and every transition of state, review decision or passed/failed checks above it become one entry, withaboutnaming the mirror'suid,revisionand head; the cursor advances in the same write, whether or not anything was sent. Another worker's marked note is relayed and labelled with its Task.spec.forge.relay.notesand.checksstop each kind on its own. - Gaps.
droppedBeforeabove the cursor relays a gap notice with the whole retained snapshot, countsgapsand raisesNeedsAttention/RelayGapuntil the next relay that carries something. - Attribution first. An Unknown login on the change's host skips the entry this pass: nothing is relayed that could not be filtered.
- Rebind. A different
uidunder the same name is a new incarnation: the entry takes it, resets its cursor and mark-ready record, and joins again; the delivered-revision guard is per mirroruid, so the new join is not refused as a repeat. - Settled. An entry whose ChangeRequest settled is relayed one last time and read no more; a Concluded Task is still relayed to; a deleted Task leaves every ChangeRequest alone.
- One write. The cursor and the entries land through
record_relay, or not at all: a duplicate key or a stale version refuses the whole write. A mark-ready intent rides in the same write. - Answered once per round. A following entry's
answeredAtmoves up only on a pass in which no unresolved inline thread waits on this Task's worker, and in which every unresolved threadthreads.unresolvedcounts is in the retained notes. It takes the last edit time, else the creation time, of the newest person's note the worker answered, so reopening a thread moves nothing and an answered edit starts a round. A thread told beforeannouncedexisted is caught up without a notice. It never decreases. Tested ine2e_gateway_logs. - Mark ready once. A following entry whose change is a draft that was
never seen ready (
everReadyfalse), whose mirror is fresh (ReachableTrue,observedAtwithin2 × pollMs) and whose selected policy holds,workerDone(ashippedresult forstatus.brief.generation) andworkerIdle(AtRestKnown true) always included, gets one intent undertask/<name>/<uid>/ready/<change uid>/<head>and oneMarkReadyeffect through the Forge port, after the lease is renewed; the receipt lands on the entry. The session is asked only once every predicate the snapshot answers holds. A change opened ready, or put back into draft by a person, is never marked, by this Task or any other following it; Fleet never puts a change back into draft. - Policies. A policy is a named set of
checksPassed(passed, or checkless fornoCheckGraceMssince the head was first seen),botReviewsAddressed,noUnresolvedThreadsandforgeMergeable;spec.forge.draft.policyselects one, elseforge.draftPolicy, andnullselects none. Any other key is refused at config load, a Task naming an undefined policy is refused at apply, and a policy removed from the config afterwards raisesNeedsAttention/PolicyUnknown. A policy that waits on bots relays their blockers whateverrelayBotssays.fleet initwriteschecks,checks-and-botsandstrict. - Moved is not an attempt. The adapter re-reads head and state
immediately before the mutation and answers
Movedwhen either differs, mutating nothing; the record returns tononewithout counting, and that head is not tried again while the mirror still shows it. The window between the fresh read and the mutation is the forge's. - Retries. A Known refusal waits
RETRY_DELAY_MSon the entry's ownnotBefore, holding back no other entry; at mostMAX_ATTEMPTS(3) intents are written against one change, thenNeedsAttention/MarkReadyFailedand no more. - Unknown is a question. An Unknown outcome, or an intent whose receipt
never landed, is answered by the change's next observation made after the
intent: ready is a recovered receipt (
done), still a draft is a failed attempt. The effect is never repeated to find out.
Conditions, under status.forge.conditions: Following, Settled,
NeedsAttention (RelayGap, ChangeGone, MarkReadyFailed,
PolicyUnknown; Multiple when more than one is open, with one line per
entry in the message; False with Resolved once all clear).
ChangeRequest #
spec.url the change's URL, the only forge-specific input
spec.pollMs poll interval while Watching (default 60000)
spec.closedGraceMs how long a closed change stays watched (default
forge.closedGraceMs)
spec.settledTtlMs how long a settled mirror is retained (default
forge.settledTtlMs)
The spec is fixed once created. fleet apply parses the URL through the
adapter of its host (a host not under [forge.hosts] is refused), derives
the name cr-<12 hex of sha256(<kind>/<host>/<project>/<id>)> when the
manifest gives none, and reuses an existing object only when it mirrors the
same change: its status.ref once written, else its own URL parsed. See the
resource,
state machine and
interface.
ChangeRequestController is a pure function from the ChangeRequest and one
observation of its change to a plan: the status to write and, after
retention, whether to delete its own object. It has no effects and no
finalizer. Guarantees, each with its test in change_request_controller and
e2e_forge:
- One complete observation, or Unknown. The adapter answers Known only
when it read every page the forge holds; a timeout, a throttled answer, an
incomplete or unparseable read or a missing login is Unknown with its
reason, leaves the snapshot untouched, and waits one interval or the
forge's
retryAfter. Unknown never means closed, merged, empty or gone. - Numbered on first sight.
revisionmoves only when the snapshot differs; every note first seen, edited or unresolved, and every change of state, head (id, checks or failing) or review decision takes that revision as itsseq. An unchanged poll writesobservedAtandnotBeforeonly. The newest 100 notes are kept;droppedBeforerises to theseqof a stored note rotated out. - Cadence. Watching polls every
pollMs; a closed change is polled ten times more slowly forclosedGraceMs, reopens into Watching with a newstate.seq, or settles (ClosedGraceExpired). Merged settles (Merged); proven absence settles (Gone). A settled object is not polled. - Retention.
settledTtlMsafter settling, the controller plansdelete; the manager performs it byuidandresourceVersionunder the lease (Store::delete_fenced), so a recreated or rewritten object is not removed. A person may delete at any time; nothing on the forge changes. - Host-wide deferral. The sweep visits ChangeRequests by host then name;
a
retryAfterfrom one defers every later one on that host without asking. - Nothing acted on.
mergeableis the forge's own answer, reported as theMergeablecondition and never acted on. The port has no merge method.
Conditions: Reachable, Mergeable, Settled.
The Conversation mirror #
ConversationController is a pure function from the Conversation, the
deliveries the receive verb spooled on it, one read of the thread's
history, the account's capabilities, the Task it is tied to or is creating,
and the Task a Fleet-opened thread's marker names, to a plan: the whole
status, with the spool drained of what it numbered and the intent of every
effect it asks for; at most one Task to create, under the route's
exclusive: {workspace} precondition; the refusal and busy-notice posts;
and after retention whether to delete its own object. It has no finalizer.
Every create and post is a keyed effect under status.effects: the manager
writes the receipt back under the key, a key with a Known receipt is never
performed again, and a missing or Unknown receipt is answered by looking
for the Task, or for the post's marker in the mirror, never by repeating
the effect blindly. Guarantees, each with its test in
conversation_controller, e2e_gateway, e2e_gateway_wildcard,
e2e_gateway_dm and store_contract:
-
Receive.
fleet gateway receive --account NAMEreads one envelope from stdin, refuses averifiedthat is not the account'sinbound, reads the payload through the adapter's pureevent, ignores an event in a channel no route covers (a listed channel id wins over the account's one DM route,"dm:*", for a delivery withdirect, which wins over its one wildcard route,"*"; neither covers the log channel; an edit or removal withoutdirectisdirectwhen its Conversation recordsspec.direct), recordsspec.directon a Conversation the DM entry covers, creates the thread's Conversation underconv-<12 hex of sha256(<account>/<address>)>only for an event that could start a Task, earn a refusal, or is Fleet's own keyed post, and spools the delivery under its delivery id throughreceive_event, aslistener/<account>, without the lease. A redelivery is a no-op, the spool holds at most 100, and the exit codes are 0 (written, duplicate or ignored), 1 (refused: full, deleting, the wrongverified, an account the config lacks), 4 (an unreadable envelope, payload or record) and 5 (a conflict the retries did not resolve). Every envelope refused or unreadable is counted by reason on the account's Listener, created by the verb if the manager has not yet, withlastFaultAtfor the listener's own faults. -
Numbered on first sight. The first pass reads the thread's history (the newest 200) where the account has it, and numbers it with the spooled events in one revision, oldest first by the platform's time: each message's
seqandfirstSeqare that revision andpositionits place. A message seen from the listener and from history is one message. A newer edit movesseqand keepsfirstSeq; an older edit delivered late changes nothing; a removal leaves the mirror. The newest 200 are kept anddroppedBeforerises to a rotated message'sseq; the newest 500 delivery ids numbered are kept so a redelivery after the drain is still a no-op. The spool is numbered even while the history is Unknown; the read is retried after the platform'sretryAfteror onepollMs. -
Backstop. While Tied and active (a message within
activeMs), the history is read again everypollMsafter the newest message; a changed text is an edit. Capabilities are asked once per account per sweep, and a platform without history is never read. -
Tied until readably gone. A Conversation whose
status.tasknames a created Task asks for that Task every pass; readable absence, or another Task under the name, makes it Orphaned withTied/TaskGone, the messages kept. An Unknown Task changes nothing. -
End of life. A thread retires once it had no message for
gateway.retainMs(seven days by default) since the later of its last message, its orphaning and its creation, and is Untied, Orphaned, or Tied to a Task that is Concluded.status.retiringrecords the start (at,revision); a message numbered since, or a Task no longer Concluded, ends it. Its steps, each a keyed effect underconversation/<uid>/retire/<at>/…, run in order and resume after a crash at the first without a settled receipt:DeleteTask(…/task): the store'sretire_conversation_taskdeletes the Task fenced on itsuidand the lease, only when it carries this Conversation's uid label and is Concluded; its finalizer then releases the session, and the thread orphans.RemoveDir(…/dir): only whenstatus.dirrecords the directory the manager made; the manager lists the Tasks first and answersWorkspaceBusy, uncounted and tried again onepollMslater, while one names it, then removes it through the runtime'sremove_dir. ItsDeletedreceipt clearsstatus.dir.delete, byuidandresourceVersionunder the lease.
A refused step is tried again after
RETRY_DELAY_MS, three times, thenNeedsAttention/RetireFailedholds the thread; an Unknown one is performed again onepollMslater, which is harmless. An Unknown Task read waits. A thread whose Task waits for its directory never retires, nor does one whose Task runs; it is looked at again everypollMs. While the tied Task is being deleted, new messages wait to be judged until the thread is Orphaned, so none is lost in a Tied thread. -
One write. The status lands through
record_received, which checks the controller's fields asupdate_statusdoes and letsreceived, which nobody owns, only lose entries, never gain or alter one. -
Admission. Every message numbered above
judgedis judged once, byadmitover the route and the people table, and only a message the listener delivered (viaconnectionorsignature) can start a Task or earn a refusal: one read from history alone is context. A delivery of a message a history read numbered first takes over itsvia, and in an untied thread numbers it again, so it is judged once. Judging waits for the thread's starter where the account has history, for the Task a Fleet-opened thread's marker names, and for the route while it left the config;judgedthen moves to the revision judged. -
Start. In an Untied thread, an admitted message that meets
route.mention(required: it mentions Fleet;top-level: it is the thread's starter), or withspec.directis the thread's starter or mentions Fleet, starts the thread's next Task,<conversation>-<n>, exactly the interface page's JSON (the route'staskConfigand brief, the thread's workspace,dispatchtrue, the three labels), underconversation/<uid>/task/<n>with the tiependingand the trigger kept; in an Orphaned thread any admitted message does. One Task per pass, and never while a tie is pending, busy or created. A thread whose starter carries a marker naming a Task that exists with that uid is tied to it (n0) and starts nothing; one whose Task is readably gone, or whose starter was removed, may; one whose Task is Unknown, or whose starter is Fleet's without a readable marker, ignores mentions. -
Workspace. On a route whose workspace is
{base}, that directory is a base: every Task of one thread gets["file://<base>/<conversation name>"](conversation::thread_dir, computed purely), and the create'sexclusivenames that directory. A URL list is the route's, given to each Task as it is, with no precondition. The manager lists the store's Tasks under the lease immediately before the fenced create and answersWorkspaceBusynaming the Task whose first URL isfile://and names a directory that normalises to the thread's, creating nothing. Otherwise it makes the directory, with its missing parents, through the runtime'screate_diron the Task's host (itshost, else its TaskConfig's, elselocal; an absent TaskConfig is aFailedcreate), then creates the Task: a directory the runtime refuses is aFailedcreate, and one it cannot tell about is Unknown, so no Task names a missing directory. Whencreate_diranswers that it made the directory, the manager records it asstatus.dir(path,host) in the same write as the create's receipt, whatever the create answered; a directory that was there already is not recorded. A crash after the runtime made the directory and before that write leaves it unrecorded, so Fleet keeps it: the failure keeps a directory, never removes one. OnWorkspaceBusythe tie turnsbusy,NeedsAttention/WorkspaceBusyis raised, one notice is posted underconversation/<uid>/busy/<n>, retention is held, and the create is planned again under the same key everypollMs, not counted as an attempt, until it lands. A busy tie whose trigger message left the mirror is withdrawn, and the next Task takes the next number. -
Adopt. A create with no receipt, or an Unknown one, asks for the Task under the name: one carrying this Conversation's uid label is adopted (
Created { adopted }), one with another label is a refusal, readable absence is one more attempt under the same key, and Unknown waits. Three refused creates raiseNeedsAttention/TaskCreateFailedand stop; a refusal waitsRETRY_DELAY_MSfirst. Only the controller's fenced create may set thegateway.fleet.dev/conversationlabels, and nothing changes them afterwards. -
Refuse. A person not on the allowlist who mentions Fleet, or with
spec.directstarts the thread, gets one refusal post per author and thread, the route'srefusalor the default, underconversation/<uid>/refuse/<author id>; past 200 refused authors none is sent. A refused post is tried again under the same key afterRETRY_DELAY_MS, at mostMAX_ATTEMPTStimes, thenNeedsAttention/PostFailed. An Unknown post is found again by its marker in the mirror, or by onesinceread where the platform reads markers back, a complete read without it being one more attempt; where it cannot be found,NeedsAttention/PostUnconfirmedand no repeat. -
Reactions at admission. Where
gateway.reactionsis on and the account's capabilities sayreactions, a create that answersCreatedmarks its triggerworking; one that answersWorkspaceBusymarks its trigger, and each later admitted message the listener delivered while the create waits,queued. The pass that ties the Task marks each queued message working: the working reaction added, the queued one removed; a later pass only removes the queued reaction of a message still marked queued. Admission's working reaction is tried once, never again, and its record is kept while the mark stands. A wait withdrawn, or a queued message that left the mirror, loses the queued reaction; a tie that ends forgets the working marks. The marks arestatus.reactions.marks, and each reaction a keyed effect underconversation/<uid>/react/<message id>/<queued|working>/<on|off>, best effort as GatewayController's: a queued reaction tried at most three times, none looked for, each dropped once settled, given up or made pointless, holding back nothing and raising no condition. Unknown capabilities change no mark. Tested inconversation_controller'sreactionsmodule ande2e_gateway_reactions.
Conditions: Reachable, Tied (TaskKnown, Starting, Waiting,
Untied, TaskGone), NeedsAttention (TaskCreateFailed,
WorkspaceBusy, RouteUnknown, MentionsOnly, PostFailed,
PostUnconfirmed, RetireFailed).
Talking in a conversation #
GatewayController is a pure function from the Task, the Conversation its
labels name and the Tasks whose parent labels name it, to a plan: the
desired status.gateway, the inbox entries to land with it and its post,
open, receive, log and reaction effects. It has no finalizer, and never
writes a Conversation.
Guarantees, each with its test in gateway_controller,
e2e_gateway_controller and store_contract:
- The tie is verified, never assumed. A Task carrying the
gateway.fleet.dev/conversationandconversation-uidlabels iswaitinguntil the Conversation of thatuidrecords a created tie naming this Task'suid, thentied. A Conversation readably absent, recreated under anotheruid, or tied to another Task puts the tie back to none withNeedsAttention/ConversationGoneandTied/ConversationGone; the cursor stays, and the tie returns when the Conversation names the Task again. Unknown changes nothing. - Join at the beginning. The cursor starts at
0, so the first relay carries every retained message, oldest first, undertask/<name>/<uid>/gateway/<conversation uid>/<revision>fromgateway/<conversation>, withaboutnaming the Conversation'suidandrevision; a mirror that already dropped older messages says they remain on the platform. - Relay by cursor, in one write. Every message with
seqabove the cursor goes out as one entry, and the cursor andseenadvance to the revision in the samerecord_relaywrite as the entry and its answers, or not at all. An edited message is relayed again, marked as an edit. - Admission. Fleet's own posts are never relayed. A message from
someone off the route's allowlist is context: it waits, and goes out
first, under a header marking it as content, with the next admitted
message; context alone advances
seenand not the cursor. A route the config no longer has raisesNeedsAttention/RouteUnknownand relays nothing. - Bounds. An entry keeps the newest messages under 64 KiB and counts
the older ones out, as still on the platform. Messages rotated out of
the mirror above the cursor count a gap and raise
NeedsAttention/RelayGapuntil the next relay that carries something. More than 20 entries still to deliver hold the relay without moving the cursor orseen. One pass plans no more appends than the store accepts in turn: the relay first, then each child's items in order; a child's counters stop at the first item left, and the child stays due. - Answers. A relay carries
answersfor each Question posted in the thread, not yet answered, that an admitted message was written after. The store records everyanswersid of any append (fleet send --answers ID, a plugin's append, a relay) instatus.answeredas{key, from, at}in the same write, first answer wins, refuses an id that names no declared Question, and lets no status write change the field. - Children. The parent's controller lists the Tasks whose
gateway.fleet.dev/parentandparent-uidlabels name it, from the sweep's one Task listing, and relays each of a child's Questions, Comments, Drafts and ChangeRequest declarations and each result generation as one entry fromgateway/child/<child>undertask/<name>/<uid>/gateway/child/<child uid>/<index or result/generation>, recording{uid, seen, declared, result}per child. A child tied to its own verified thread is left alone; more than 200 children raiseNeedsAttention/TooManyChildrenand none is relayed. The store accepts the parent labels only when the child is created, only together, only for a parent that exists with thatuidand is not being deleted (an unreadable parent is Unknown, to be retried), and only from a writer that may already append to the parent's inbox: a person, atasks = "any"plugin, or atasks = "own"plugin that created the parent. They never change afterwards. - Reactions are best effort. Each admitted message a relay delivers,
with no mark yet, is marked working and gets the working reaction, where
gateway.reactionsis on and the account's capabilities sayreactions. A message the Conversation marked working at admission, whose working reaction landed there, is marked working with no reaction of the Task's; any other is reacted to as usual. A thread post that lands marks every working message replied: the replied reaction is added and the working one removed. Each reaction is a keyed effect undertask/<name>/<uid>/gateway/react/<message id>/<working|replied>/<on|off>, tried at most three times, never looked for, and dropped once settled or given up. A reaction holds back no relay and no post, and raises no condition. A message that leaves the mirror, a thread that is readably gone and reactions turned off forget the marks. Tested ingateway_controller'sreactionsmodule ande2e_gateway_reactions. - Quiet costs nothing. A tied Task is due only when its Conversation's
revision moved past
seen, itsuidchanged or it left the listing, or when a followed change the sweep holds moved its state or its entry'sansweredAtpast what the thread was told; a parent only when a child'sresourceVersionmoved; a Task with the labels and no verified tie, every pass. A pass that finds nothing new writes nothing.
Conditions, under status.gateway.conditions: Tied (Verified,
Waiting, Opening, Opened, Abandoned, ConversationGone),
NeedsAttention (RelayGap, ConversationGone, RouteUnknown,
TooManyChildren, PostFailed, PostUnconfirmed, RecoveryIncomplete,
DeclarationInvalid, ReceiveFailed).
ListenerController is a pure function from the Listener, the account as
the config has it with its digest, and the platform's whoami and
capabilities, to the three conditions: Accepted (Loaded, or
NoRoute), Resolved (IdentityMatches, IdentityMismatch, or Unknown
Unreachable), and InboundReady (Connected; or NoListener,
Connecting, Closing, ListenerStale, ListenerConfigOld,
DeliveriesRefused), judged from the beats fleet gateway receive --beat
recorded, stamped by the verb's clock, against three gateway.beatMs and
the current digest. The manager creates one Listener per configured
account when it loads the config, the verb creates it when a beat comes
first, and the controller deletes one whose account left the config.
listener_controller and e2e_gateway hold these.
Store #
A data directory holds store.json (format and version), lock, seq,
lease.json, manager.lock, manager.json, children/<pid>@<boot id>/, objects/<Kind>/<name>.json,
boards/<name>/ and tmp/. The default is the
platform data directory ($XDG_DATA_HOME/fleet, ~/.local/share/fleet,
%LOCALAPPDATA%\fleet); a non-empty directory that is not a store is
refused.
- Writes go to a synced temp file, then a hard link (exclusive create) or a rename (replace), then the directory is synced.
- Every write holds the store lock, an OS file lock that a writer waits for,
and checks
resourceVersion. - A write that finds no room on the disk (
ENOSPCorEDQUOT) isFull, with the path. Nothing was written. The manager pauses on it (see runningfleet up). - A missing record is
Known(None); an unreadable, corrupt or misfiled one is Unknown and blocks writes to that name. A list with one bad record is Unknown as a whole. - Each status field has one owner, checked on every write, except
Task.status.inbox,status.answered,status.wakeRequestedAtandstatus.pauseRequestedAt, which have none and which no status write may change. A controller writes only under the current manager lease: an expired or superseded token is refused, and the token only grows. A new lease takes its token fromseq, so the token grows even whenlease.jsonis lost. A serving manager holds the OS lock onmanager.lockfor its life, and a secondfleet upwaits while it is held. A new manager takes over an unexpired lease only when its holder names another boot, or when its holder is gone on this boot and every process group it recorded underchildren/<pid>@<boot id>/is stopped. So no process the dead holder started still runs.fleet reconcile --holderrefuses a name of that shape. status.inboxis reached through three typed mutations, each named by its caller and compare-and-swap under the lock:append_inbox(cli, through the manager'ssendverb, no lease; orforge-controllerorgateway-controller, under the lease) refuses a key already ininboxordeliveries, anabout.revisionat or below the mirror's (about.uid) highest delivered one, an append while more than 20 entries are still to deliver, a deleting Task, a source not under the caller's prefix (cli/,forge/,gateway/), and ananswersid that names no declared Question, and records the entry'sanswersinstatus.answered, first answer wins;record_relay(ForgeController, GatewayController or TaskController, under the lease) replaces the writer's own field,status.forge,status.gatewayorstatus.subscriptions, and appends each listed entry under the same checks (TaskController's source prefix isboard/), in one write that a single refused entry fails whole;record_delivery(TaskController, under the lease) writes the controller's status and, in the same write, the receipt into the newest-100status.deliveriesand the entry out ofinbox, refusing a key no entry holds. None changes another field;store_contractraces appenders against the remover and tears the record.status.wakeRequestedAtis reached through one typed mutation, compare-and-swap under the lock:request_wake(cli, through the manager'swakeverb, no lease) sets it to the time of the request and refuses a deleting Task. It changes no other field.status.pauseRequestedAtis reached through one typed mutation, compare-and-swap under the lock:request_pause(cli, through the manager'spauseverb, no lease) sets it to the time of the request and refuses a deleting Task. It changes no other field.- A Conversation's
status.received, a Listener'sbeats,refusedandbeatRevision, and a Board'sstatus.headandstatus.oldesthave no owner either; only the store's typedappend_eventswrites the Board's two, as the next bullet says.receive_event(the account's listener, no lease) spools one delivery, a duplicate id changing nothing and the hundred-and-first refused;record_received(ConversationController, under the lease) writes the controller's status and lets the spool only lose entries;record_beatandrecord_refusal(the account's listener) replace one instance's beat, evicting the oldest past eight, or count one refusal, each movingbeatRevisionand nothing else. A listener writes only the objects whose spec names its account.createtakesapply, or the account's listener for a Conversation or a Listener, and checks a Task's parent labels under the lock, as talking in a conversation says; a spec update may not change them.create_fenced, under the lease, takes the Conversation's controller for the Task a thread starts, the one create that may carry thegateway.fleet.dev/conversationlabels, which no other create or spec update sets or changes. It also takes the Gateway controller for the Conversation of a thread Fleet opened, andreceive_eventtakes the Gateway controller for Fleet's own opening post there, a delivery whoseverifiedisfleet, and nothing else.create_fencedalso takes the CronTask's controller for the Task a scheduled time starts, the one create that may carry thecrontask.fleet.dev/labels, which no other create or spec update sets or changes.retire_scheduled_task, under the lease, deletes such a Task only with itsuidand its CronTask's uid label, and only once it is Concluded unless the CronTask's policy isReplace. - A Board's log is
boards/<name>/<seq>.jsonlsegments, one event per line, each segment named by its firstseq, and a<seq>.keysfile beside each with the(source, key, seq)of its keyed events.append_eventsis the only writer.clicalls it ascli/<user>, through the manager'spublish_eventverb, with no lease. TaskController calls it as a Task (Source::Task), under the lease, as the next bullet says, and as itself (Source::Controller,controller/task-controller), under the lease, for itsfleet.task.*events on Boardfleet(kinds::may_append_events). Under the lock it checks each event (event::validate_publish_from: the type grammar, thefleet.prefix, refused for every source but a controller, 256 characters forsubject,keyandcorrelation, the Board'smaxDataBytes) and refuses the batch whole when one fails. It then drops, from the oldest, each segment whose events are all older thanretention.maxAgeSeconds: a segment goes when the next segment's first event is that old, and the newest segment when its last event is. A publish whose key the same publisher (Source::same_publisher: a Task by its name and uid, whatever its lineage) used in a kept segment's keys file (or the newest segment itself) appends nothing and answers that event, so a key whose event aged out can be used again. The others get the nextseqs, fromstatus.head + 1with no gap, and the store's time. Each line is appended and fsynced, then its key line; each append cuts a torn last line off the newest segment, rewrites its keys file from it when they differ, and rebuilds a missing or torn keys file of an older segment from that segment. A reader skips a torn line. The log, not the status, decides the nextseq, so an append that crashed before its status write keeps itsseq, and the write that recovers it correctsstatus.headandstatus.oldest, even when it appends nothing. The directories are created0700and the files0600on Unix, and each new directory's parent is fsynced. After the append, retention drops whole segments from the oldest while the log holds more thanretention.maxCountevents, never the newest. Thenstatus.headandstatus.oldestmove, and the dropped files go. Stray files in the directory are ignored. No other writer, and no status write, changes a Board's status. Retention runs only on a publish.read_events(board, after, limit)takes no lock: it answersExpired { oldest }whenafter + 1is below the firstseqthe log holds, and otherwise the events aboveafter, oldest first; a segment that retention drops during the read makes it read again. Creating or deleting a Board removes any log left under its name.store_contracttears a line and a keys file, drops a status write, ages segments out and leaves stray files. - A session's outbox is
event::outbox_fileof its signal file:<signal file>.events, on the same place. Each spawn that getsFLEET_SIGNAL_FILEgets it asFLEET_EVENT_FILE. Inside a session,fleet event publishchecks the line without a store (OutboxLine::encode: the Board's name,event::validate_publishwithout the Board'smaxDataBytes, at mostevent::MAX_OUTBOX_LINEbytes) and appends it in one write. A new outbox is mode 0600 and a new signals directory 0700 on Unix, whoever makes it (FileSignals::open,fleet signal,fleet event publish). A session withFLEET_SIGNAL_FILEand noFLEET_EVENT_FILErefuses, and never falls back tocli/<user>. On each pass, before the Task's controllers, the manager reads the outbox of each Task whosestatus.sessionis set (renewing the lease first when the read goes to another host), unless its session isGone,status.outbox.closedis set and the Task is not being deleted. AConcludedTask that is not being deleted is read only when the manager'sduetest holds for it (itsSESSION_RECHECK_MSrecheck, a view's wake request, a revive under way, or a watched activity). A read of aGonesession that finds every whole line in setsclosed; a read of a session that is notGoneclears it. It reads fromstatus.outbox.offset, at mostevent::MAX_OUTBOX_READbytes: through the signal port on this machine, or through the runtime'sexec(fleet signal-read --from <offset> <file>) on a place. Both reads give each byte that is not valid UTF-8 as NUL, so the bytes cross the runtime as text with every offset kept; JSON takes no raw NUL, so such a line is skipped and counted. Both open the outbox only as a regular file: on Unix without blocking and without following a symlink, so a FIFO or a symlink the session put there reads as Unknown. The pureevent::ingestturns the whole lines into publishes; a last line without its newline waits. A line over 64 KiB is skipped whole: one skipped before its newline setsstatus.outbox.discarding, and the next reads pass over its bytes up to that newline. A file shorter than the offset was made again: it is read from 0 under the nextgeneration. A line without a key getsoutbox-<generation>-<offset>. The source isevent::task_sourceof the Task: its name, uid and parent-label lineage; a line's own fields never name it. Consecutive lines for one board are appended together as TaskController under the lease, at most 256 in oneappend_events: one lock, one lease renewal and one fsync per segment. A batch the store refuses whole (Invalid,NotFound,Forbidden) is appended again one line at a time, so only the refused line is skipped. Only then doesstatus.outbox(TaskController's) move past it, so a crash between the two re-reads lines whose keys dedupe them. A cursor write that conflicts with another writer, such as the worker, re-reads the Task and tries again, up to 5 times. Delivery is at least once: when a crash falls between the appends and the cursor write, and the same appends made retention drop a re-read line's key (aretention.maxCountbelow one read's batch), that line is appended again under a newseq. A line that does not parse, or that the store refuses (Invalid,NotFound,Forbidden), is skipped:status.outbox.skippedcounts it andlastSkippedsays why. A new generation clearslastSkipped, because its offset names a line in a file that is gone. Any other store error stops the pass's ingest at that line. An outbox that cannot be read is Unknown: the offset stays and nothing is concluded. The ingest also answers theoutbox_drainedobservation: Known(true) when every whole line is in (or there is no outbox), Known(false) when the read hit its cap or the status write conflicted, Unknown when the outbox or the store could not tell. After a KnownReleasedreceipt, TaskController keeps the finalizer until it is Known(true):Released=False/OutboxDrainingwith no limit, orUnknown/OutboxUnreadforRELEASE_GRACE_MSfrom its first unread pass (the condition'slastTransitionTimewhile its reason isOutboxUnread; a firstOutboxUnreadis a transition even fromUnknown/Releasing), after which the unread lines are given up (Released=True/OutboxGivenUp). The release stopped the session, so the read after it is the last one; a torn last line then never completes and is left.e2e_event_boarddrives it through the real binary. - A Task's subscriptions are
spec.subscriptions, which a spec update may change likedispatch;subscription::validaterefuses more than 16, an invalid Board name and two with the same Board and filter. The manager'ssubscribeandunsubscribeverbs edit the list, compare-and-swap, asapply. On each pass, after the outbox step and before the Task's controllers, the manager reads the subscriptions of each Task that is not being deleted,ConcludedorReleasing. Per subscription it reads the Board (Unknownkeeps the cursor as it was, and the pass reports it) and places the cursor (SubscriptionCursor::place): the old one while the Board keeps its uid;after, elseevent_head, for a new one;0for a Board made, deleted or made again since. A subscription whose last notice is still instatus.inboxand not given up on is not read, and nor is one when the inbox holds more than 20 entries still to deliver, or one whose Board'sstatus.headis not above the cursor (a Board with nostatus.headyet counts as head 0; a log a crash left ahead of its status is read at the next append, which corrects it). Otherwiseread_eventsreads from the cursor up to the head, at most 10000 events, and the lease is renewed before each page; a lost lease ends the sweep;Expired { oldest }moves the cursor tooldest - 1and marks the notice; a read error keeps the cursor as it was. A read with a match, or an expiry, owes oneevent-notice(subscription::notice_entry): fromboard/<board>, undertask/<name>/<uid>/notice/<n>withnfromstatus.subscriptions.notices, withnotice(board,count,first,last,expiredBefore) and a text that gives thefleet event listcommand, each filter as--flag=value, so a value that starts with a dash stays a value. The cursors and the notices land in onerecord_relayas TaskController under the lease, so a stop between them cannot happen; a conflict leaves both for the next pass. A cursor of a subscription no longer in the spec is dropped.e2e_event_subscriptionsdrives it through the real binary. - TaskController's own events go to Board
fleet(board::FLEET) asSource::Controllercontroller/task-controller, with the Task's name assubject, undertask/<uid>/<series>/<n>(task_event::key): the name is left out so that a 253-character name keeps the key within 256.TaskController::reconcilequeues afleet.task.phaseevent (FleetEvents::queue_phase) instatus.fleetEvents.pendingin the write that changes the phase, under the nextphasesnumber: the intent lands with its cause.pendingkeeps the newest 64.FleetEvents::owedadds onefleet.task.declaredper item ofstatus.declaredpastfleetEvents.declared, and onefleet.task.resultwhenstatus.result's generation is notfleetEvents.result, and gives the record that follows them. An empty record owes nothing and starts,startedset, at what status holds, even with no declaration and no result: a Task queues its first phase change before any brief, and a declaration or a result needs a brief, so only a Task from before Boardfleethas one with a declaration or a result. The manager'spublish_fleet_eventsappends the owed events in oneappend_eventsunder the lease, then writes that record as TaskController, re-reading the Task on a conflict and giving up when itsfleetEventsmoved. It runs at the start of each Task's turn in a pass, and inperform_planright after the status write, before the effects and the finalizer's removal; an error there other than a lost lease is reported and the plan goes on. A batch the Board refuses (Invalid,NotFound,Forbidden) is appended one event at a time, and each refused event is counted infleetEvents.skippedandlastSkipped. Any other error keeps the record and reportsUnknown, so the next pass appends the same events again, and their keys append nothing.e2e_fleet_eventsdrives it through the real binary. - Deleting marks a Task while its finalizer remains; only its controller, holding the lease, removes the finalizer, and only from a deleting Task.
- A controller deletes its own object (
delete_fenced) only with the object'suidand currentresourceVersionand the lease; a ChangeRequest, a Conversation and a Listener have no finalizer, so they go at once.
Runtime contract #
A Session is one running agent (fleet_api::session): the unit every
call below starts, observes, briefs, sends to or releases. A Task owns at
most one, named by status.session (SessionRef: the runtime's id, the
host and Fleet's deterministic key). status.sessionState is what Fleet
last proved about it, folded by SessionState::observe from the Known
answers of find, lost and paused, and the activity the agent's hooks
reported through fleet signal (see signal contract): Gone when a
readable list lacks the Session, else Lost, else Paused, else Idle
or Running by activity, else Running on any proof of presence. Unknown
answers keep the last state. Nothing decides on the state; a view reads it.
fleet_api::runtime::Runtime: host, create_dir, remove_dir,
prepare_execution, env_source, spawn, find, ready, workspace_trust,
brief, brief_delivered, at_rest, release, lost, revive,
paused, pause and resume, each answering Known or Unknown, and
screen, which returns a session's capture text and
title. A runtime reports no activity: the agent's hooks do, and below them
Fleet's screen rules read the screen screen returns
(agent state). revive
and resume take the conversation the hooks last reported, which the
harness profile's resume argv names, and the spawn's launch (harness,
workspace, environment), for a runtime that starts the argv itself; the
manager completes it with the environment it froze and the signal file, as
for a spawn. create_dir makes a directory with its missing parents on a host
and says whether it made it; remove_dir removes one and what it holds, a
directory already gone included. The exec adapter runs each as a bounded
command on the host, through the runtime's exec verb. Each adapter reports its longest single operation
(operation_bound), and fleet reconcile refuses a lease that could not
outlast it.
- exec: every call is one bounded
<program> <verb>of the runtime protocol, the program chosen by the host.spawnisstartof the harness profile's launch argv with the spawn's environment,FLEET_SIGNAL_FILEincluded;reviveandresumearestartof its resume argv. A session's id is its runtime key,<keyPrefix>.<uid>, so a restart keeps it.ready,workspace_trustand a running agent'sat_restread the agent's signals;lostis anexitedprocess.releaseisstopwithrelease: true.briefisinputof the text, and only the agent's prompt hook proves it.pauseis thepauseverb, andpausedis aninspectthat answerspaused, when the runtime'smanifestdeclares the verb; on any other runtimepausedstays Unknown. It passes no model to its harness, so a spawn withspec.modelfails.e2e_runtime_execdrives the realruntime-muxthrough it. - fake: a file-backed host for tests and trials, with injectable faults (lost answers, refusals, delays, hangs). It runs no process: it records the harness profile's launch and resume argv, and plays each agent's prompt hook by appending to its signal file, unless silenced.
The runtime makes every workspace (see
Workspace contract) before the first start: the
spawn's ready names its directories, and the runtime runs the session in
the first and makes nothing at the start. Every adapter keeps these rules:
- Making. The runtime decides how a URL becomes a directory: a worktree, a clone, a copy or a restored snapshot. Branches, bases, source checkouts and credentials are the runtime's. Fleet sends none.
- Whole or nothing. If a
workspacecall stops partway, the runtime rolls its partial state back on the next call under the key. - Cleanup.
releasedeletes the session, andCleanWorkspacereleases its workspace throughstopwithrelease. Fleet never inspects or deletes a workspace itself, with one exception: a Gateway thread's directory that the manager made, which it removes when the thread retires (see the Conversation mirror). Fleet never removes a directory it did not make or a route's base directory. - Refusal. A workspace the runtime cannot make is
Known(Failed), never Unknown. A URL it does not handle isKnown(Unsupported { url }). A runtime can answerKnown(TrustUnmapped { harness })at spawn for a harness it knows no workspace-trust interface for. No shipped runtime answersTrustUnmapped.
The exec adapter starts a session in the first of the workspace's dirs,
and the harness profile adds one --add-dir per other directory. A session
with an empty list starts in the runtime's default directory. A spawn of a
non-empty list whose workspace is not made fails.
Workspace trust #
An agent harness can refuse to load a folder's project settings until a person trusts the folder. This document calls that gate workspace trust. Workspace trust is not a permission policy. It approves no command, edit or tool, and Fleet changes no permission mode or sandbox to obtain it.
The trust root is the directory the agent keys the session's trust on:
- The trust root is the first directory of the workspace the runtime made:
the directory a
file://URL names, or the worktree of agit+URL. - A session with an empty list has no trust root.
- The other directories get no trust. Neither agent loads their project settings.
The harness profile gives each harness its trust at spawn:
| Harness | At spawn |
|---|---|
codex |
The launch argv adds -c projects={"<root>"={trust_level="trusted"}}. This override trusts the root for this session only. |
claude, claude-code |
Nothing. Claude Code has no per-session trust interface. |
pi |
The launch argv adds --approve. pi trusts the project's own resources for this run only. |
| any other | Nothing. |
The exec runtime answers workspace_trust from the agent's signals and
screen, in this order:
- An agent that reported a state other than its start is
Trusted. Hooks run only in a trusted workspace. - Signals that cannot be read are Unknown.
- Before the first report, the runtime reads the screen through
capture. A Codex, Kimi Code, Copilot or Claude Code trust dialog isUntrustedwith the gapUnsupported. Its message asks a person to trust the directory once in the session. - Codex's initial empty composer, with Codex in the foreground, is
Trusted: the launch override trusts the workspace. - Kimi Code's empty composer, with Kimi in the foreground, is
Trusted: Kimi asks its folder trust before it shows the composer. - GitHub Copilot CLI's empty composer, with Copilot in the foreground, is
Trusted: Copilot asks its folder trust before it shows the composer. - Any other screen, or a screen that cannot be read, is Unknown.
The fake runtime answers from each session's trusted flag and its
workspaceTrust fault. The port also defines the gap Mismatch, for a
session that is not the one the runtime would start for its workspace. No
shipped runtime answers it.
These rules hold for every harness:
- The spawn intent records the harness and workspace. The trust that a spawn adds follows from them alone, so a respawn under the same intent adds the same trust.
- Codex's override lives in the session's own arguments. The resume argv keeps it. Fleet writes no Codex configuration file.
- Codex keeps only the last
-c projects=on its command line. A wrapper that passes its ownprojectsoverride therefore loses it to Fleet's, or replaces Fleet's. The[projects]table in Codex'sconfig.tomlmerges with the override, so keep other trusted roots there. - Fleet never sends a key to a dialog. Claude Code's only documented trust
interface persists in
~/.claude.jsonon the host. A person trusts the repository once, by the dialog or that file. The Task's message names the host.
e2e_workspace_trust covers an agent that waits for trust and trust that
cannot be read, on the fake runtime. e2e_runtime_exec covers a Codex Task
on runtime-mux that is briefed before its first turn ends, and a Kimi Code
Task and a Copilot Task that are briefed before their first report.
Agent state #
status.agentState has two sources. The agent's hooks are the first; a
screen rule is the second, lower one. fleet_api::screen::merge is the
rule, pure:
Profile authority |
Hooks reported since the last start | A screen rule matched | agentState from |
activity.source |
|---|---|---|---|---|
full |
yes | any | the hooks | hook |
full |
no | yes | the screen | screen |
partial, session, none |
any | yes | the screen | screen |
partial, session, none |
yes | no | the hooks | hook |
| any | no | no | neither: unknown, never idle |
none |
- The runtime's
screenreturns the screen; Fleet evaluates the rules (fleet_api::screen::Rules::evaluate). The runtime knows no harness. status.activityis{source, rule, at}: the rule is<set>/<rule id>for a screen state, andatis when Fleet first saw this state from this source.- TaskController asks the screen only of a harness with rules, and not while
the last pass took the state from hooks whose authority is
full. Theexecadapter answers one capture per session for 2 s. - A capture that fails keeps a screen state. An unreadable signal file, as on another host, keeps the state unless a screen rule matches.
- A screen state is for a view only. Readiness, rest, a pause and the proof of a delivery read the hooks alone.
Signal contract #
fleet_api::signal::Signals: file names the file a session's hooks
append to, passed as FLEET_SIGNAL_FILE in the spawn's environment, and
read folds it (Reported: the last state, every prompt digest with
when it was last reported, the last conversation id). A file never
written is Known and empty; a file that cannot be read is Unknown.
signal-contract.md owns what fleet signal writes and
reads. The FileSignals adapter keeps the
files under <data dir>/signals for sessions on this machine, and answers
Unknown for any other host: reading a remote file takes the runtime's
exec. TaskController reads the file for every live session, not only one that
may be paused: status.sessionState is Idle once the agent's last report
is idle, and Running while it reports working, blocked or prompt.
status.agentState is the agent's report itself, finer: working for
working and prompt, attention for blocked, idle for idle, and
unknown while the agent has reported nothing since it last started. An
unreadable file keeps the last agentState. A session that reads Lost
or Gone has no agentState: what its agent last said is cleared, since
no agent runs. TaskController is its only writer.
status.activity.source says which source set agentState
(agent state).
e2e_signal covers state, an interactive session and pause,
e2e_delivery_proof the prompt proof, and e2e_harness the profiles' argv
and resume.
Workspace contract #
A Workspace is the set of files one Session works in (fleet_api::workspace).
A Task owns at most one. TaskController records it in status.workspace
as WorkspaceRef: Fleet's key, the host whose runtime made it, and the
dirs the runtime answered, one per URL in the Task's order. The workspace
key is the session key.
The runtime port carries the workspace calls:
workspace(host, key, urls), find_workspace(host, key, urls) and
release_workspace(workspace), each answering Known or Unknown. The exec
runtime maps them onto the protocol (docs/runtime/README.md, "Workspaces"):
- Schemes first. Before any call, Fleet reads the runtime's manifest.
A runtime that lists no
workspaceverb, or not a URL's scheme inworkspace.schemes, answersKnown(Unsupported { url })for it. workspace.Made { dirs, adopted }isMaterialized;Unsupported { url }andFailed { why }are answered as they are. The call is bounded by the runtime'sworkspaceTimeoutMs.- Once per key. The verb is idempotent by key, so
find_workspaceis the same call again: a lost answer adopts the whole workspace and starts no new attempt. - Release.
release_workspaceisstop { key, release: true }. A workspace already gone isDeleted. Repeating it is harmless. - Observed host. The host whose runtime answered is the workspace's. Fleet sends no credential: the host and its runtime hold them.
The runtime keeps the rest: whole or nothing, work kept on release, never
removing what it did not make. fleet runtime check tests a runtime that
declares the verb, and workspace-git is the shipped workspace provider for git URLs.
The fake runtime makes workspaces as records on the fake host: a file://
URL is its directory, and any other URL a directory named after its last
segment under <fake dir>/workspaces/<key>.
e2e_runtime_exec covers a git+file Task on runtime-mux, run in its
worktree and released with its uncommitted work preserved, and a scheme the
runtime does not list.
Forge contract #
fleet_api::forge::Forge: operation_bound, parse, whoami, change
and mark_ready. change answers Known(Some) with a complete
ChangeSnapshot, Known(None) for proven absence, or Unknown with an
Uncertainty and an optional retryAfter. mark_ready takes the expected
head and state and an intent key, reads both afresh, answers Moved when
either differs (nothing mutated), MarkedReady { already } once the change
is out of draft, Failed when the forge said no, and Unknown only when the
mutation's answer could not be read. An adapter whose forge offers no
atomic head-and-state precondition answers Failed without reading or
mutating, and so does an unconfigured host. Adapters live in
fleet-forge, one per [forge.hosts] entry, chosen by the host a URL or
ref names; a <organization>.visualstudio.com host falls back to the
dev.azure.com entry:
- github: bounded
gh api graphql --hostname <host> --includecalls, one query paginated over reviews, comments and review threads; at most six calls per observation, Unknown withIncompletepast that. Mark-ready is one fresh read ofisDraft,stateandheadRefOid, thenmarkPullRequestReadyForReviewwith the intent key asclientMutationId. - gitlab: bounded
glab api --hostname <host> --includecalls: the merge request, its discussions by page, its approvals; a 404 is absence only when the project itself answers. Mark-ready is one fresh read, then the title updated with its draft marker removed. - azure-devops: bounded
az devops invokecalls for hosted Azure DevOps Services. Organization/project/repository identities are checked against the URL. A collection that fills its bounded page is Unknown withIncomplete; no continuation is followed. Mark-ready fails closed because the provider exposes no atomic head-and-state precondition. - bitbucket-cloud: bounded authenticated
curlreads againsthttps://api.bitbucket.org/2.0/forbitbucket.orgonly. The adapter brackets paginated comments, commit statuses and mergeability checks with two pull-request reads, requires every status to link to that exact head, and rejects repository or head movement. Participant votes are not exposed as head-bound reviews. Inline thread counts require explicit resolution evidence. Mark-ready fails closed because Bitbucket'sPUT draft=falsehas no atomic head-and-state precondition. - fake: a file-backed forge for tests and trials, with injectable faults
(lost, timeout, throttle with
retryAfter, incomplete, malformed, absent; for mark-readymoved,failed,lostandlost-applied). It runs no process and records every mark-ready that mutated a change.
Credentials stay with each external client's own configuration; Fleet passes none and stores none. Bitbucket Cloud uses curl configuration or netrc rather than assuming an official provider CLI.
Gateway contract #
fleet_api::gateway::Gateway: operation_bound, parse, event,
whoami, capabilities, history, open, post and react, each
answering Known or Unknown; a refused write is Known(EffectOutcome::Failed), and
open and post answer Opened { conversation, message, at } and
Posted { message, at } with the platform's own time. history answers a
complete History with its starter, Unsupported where bots cannot read
history, or Unknown with an Uncertainty and an optional retryAfter.
An address is <platform>:<chat>[:<thread>], a Conversation is named
conv-<12 hex of sha256(<account>/<address>)> (fleet_manager::conversation_name),
and admit sorts a message into Own, Admitted or Context from a
route and the people table. The [gateway] section is validated at load
as the config page
states, a route directory that equals, contains or lies inside another's
included; a platform this build lacks, an inbound its listener cannot
deliver by, or a fake without a dir is refused when the gateway opens.
Adapters live in fleet-gateway, one per [gateway.accounts] entry:
- fake: a file-backed platform for tests and trials, with injectable
faults (
lost,timeout,throttlewithretryAfter,incomplete,malformed; foropenandpostfailed,lostandlost-applied) and settablecapabilities: history on or off, ametadata,nonceornonemarker,unmentionedandthreads. It runs no process and records every post it landed, in order. - slack: the Web API through one bounded
curlper call, with the operator's curl config named and never read. Posts carry the intent key as message metadata, so the marker ismetadata. - discord: the REST API through one bounded
curlper call, the same way. Posts carry a nonce derived from the intent key withenforce_nonce, so the marker isnonce, and a post with an Unknown outcome is resent under the same key inside the window.
listener_account is what a listener starts from, with its digest over the
account's name, platform, team, bot and inbound method, and a Discord
account's Gateway intents.
The command line #
fleet init|up|apply|get|list|status|send|amend|label|declare|result|delete|reconcile|watch|attach|term-bridge|event|gateway|signal|runtime|integration|doctor|version.
Exit codes:
0 ok, 1 refused, 2 usage, 3 not found, 4 Unknown, 5 conflict, 6 lease, 7 timed out,
78 fleet up refused for a reason no retry can fix (config, store format).
apply, get, list, status and delete take changerequest,
conversation and listener as well as task, taskconfig and
envprovider; status changerequest NAME --json prints the ref and the
whole numbered snapshot, status conversation NAME --json the tie, the
numbered messages and the spool. A Conversation manifest is applied
through the account's adapter, under its derived name; a Listener manifest
is refused, since the config is its only source. fleet gateway receive --account NAME [--beat] is what a listener runs per envelope and per
heartbeat; fleet gateway account NAME --json is what it starts from, and
fleet gateway status shows each account's listener.
fleet watch --json is how a view follows the Tasks: one NDJSON line per
event, until Ctrl-C, or until the first synced with --once. It reads the
store every --poll-ms (500 by default) and takes no lease:
| Event | Fields | Meaning |
|---|---|---|
changed |
revision, object |
the whole Task, written at revision |
deleted |
revision, name, uid |
the Task is gone from the store |
synced |
revision, names |
the first read is reported; names are the Tasks present then |
revision is the store's write counter, the resourceVersion every write
raises. --since N reports only Tasks written after N, so a view resumes
from the last revision it read. A deletion leaves nothing behind to compare,
so a resuming view drops each Task it holds that synced does not name. An
unreadable store reports nothing but a warning on standard error, and the next
read tries again: Unknown never looks like a deletion. The first read that
works after an unreadable one ends with synced again. A list reads each
Task on its own, so one read can hold
a later write and miss an earlier one; a read is reported only once the read
after it is the same. Writes are serialized, so by then every write below the
highest revision reported is in it, and a resume skips none.
fleet event publish [--board B] --type T [--subject S] [--key K] [--correlation C] --data JSON [--wait [--timeout-ms MS]] [--json] appends
one event to a Board, shared by default, through the manager's
publish_event verb, as cli/<user>, and prints it with its seq. A
refused event exits 1 and a missing Board exits 3. --wait changes nothing
there. Inside a session, --wait reads the session key from the outbox's
name (fleet_runtime::events::outbox_session_key, the inverse of
<key>.jsonl and event::outbox_file) and refuses, appending nothing, a
name Fleet did not make. It opens the store as the read-only commands do
(--config, then FLEET_CONFIG, then the per-user config), and before
the append reads, with no lock, the manager's before_append: the Task
whose session_key(name, uid) is that key, its status.outbox
(generation g0, offset o0) and the Board's head (0 for a Board that is
not there). The line starts at the outbox's length before the append. A
line that starts below o0 is in a file made again, which Fleet reads
under g0 + 1; any other line under g0. That generation gives the
line's key when it names none (event::outbox_key). The manager's
wait_ingested then polls every 200 ms for --timeout-ms (60000 by
default), and reads again after a Busy or Unknown read, with a warning
on standard error. It waits until the Task's status.outbox, compared as a
(generation, offset) pair, reaches (that generation, the line's end).
TaskController appends a line's event before it moves the cursor past the
line, so the event is then on the Board, from that Task by name and uid,
under that key. before_append also keeps the Board's uid, read before
and after the head, and reads both again (at most 3 times) when the uid
changed between them. Once the cursor is past the line, a lastSkipped
that names the line's offset in the line's generation answers first: the store refuses a line, such
as one above maxDataBytes, before it looks at its key. While the Board's
uid is the same, the event is first looked for above the head read
before the append, then once from the start up to that head: an event found
there is a key the Task already used, and prints with (already published under this key), as a publish outside a session does. A Board made again
since is searched from its start, and an event found there is new. A line
with no event is not on the Board (skipped, dropped by retention, or in an
outbox made again): the command exits 1 and says so, with lastSkipped's
reason when it names the line's offset (OutboxCursor::skipped_at). The
line's own fields never name the Task. A timeout prints the queued line, as
a publish without --wait does, and exits 7: Fleet has not read the line
in yet, and may still, unless the outbox was made again.
fleet event list [--board B] [--after SEQ] [--type P] [--subject P] [--source S] [--correlation C] [--limit N] [--json] prints the
first N (100 by default, at most 10000) events above SEQ that match,
oldest first, up to the last seq in the log when the list starts: an event
published during the list waits for the next one; --json prints them as
an array. A --type or --subject value that ends in * matches a prefix.
A cursor older than the log exits 5 and names oldest; with --json it
also prints {"expired": {"oldest": N}}. The Board page owns the event fields.
fleet event wait --after SEQ --timeout-ms MS [--poll-ms MS] [--limit N]
and fleet event watch --after SEQ [--poll-ms MS] take the Board and
filters of list and read through the manager's EventCursor, with no
lock. The cursor's after moves past each event a read returns, kept or
not, and stops at the last event answered when --limit cuts the answer,
so the next read repeats no event and passes none over. A read that
expires or fails after some events were kept answers those, and the next
read meets the expiry or the error again. One read takes at most
verbs::MAX_EVENT_PAGES (4) pages of 1000 events, so a reader behind a
Board that grows faster than it reads hands on its matches and checks its
deadline between reads; it reads again at once, with no poll, while its
cursor still moves. A torn last line
is not read until it is whole, and the log gives seqs with no gap, so an
event the log gains under a read is in the next one. wait (the manager's
wait_events) reads every --poll-ms (500 by default, 50 to 10000) until
a read holds a match, prints the matches as list does and exits 0; with
no match by --timeout-ms it prints nothing and exits 7. watch prints
each match, oldest first, and reads again every --poll-ms when a read
holds none. With --json each event is one compact JSON line (NDJSON),
flushed; without it each is one line of list's table. It runs until a
write to stdout fails, so a closed reader ends it at the next event it
prints, with exit 0. For both, a Busy or Unknown read
(verbs::is_transient) is a warning on standard error, and the next poll
reads again, as in fleet watch; wait still ends at its timeout. An
expired cursor exits 5 and names oldest and the cursor the read was at,
with {"expired": {"oldest": N}} on stdout under --json.
fleet event subscribe TASK [--board B] [--type P] [--subject P] [--source S] [--correlation C] [--after SEQ] adds one item to the Task's
spec.subscriptions through the manager's subscribe verb, and refuses
one with the same Board and filter (exit 1). fleet event unsubscribe TASK
with the same Board and filter flags removes it through unsubscribe; no
such item exits 3, and so does a missing Task. The
Board page owns the notices.
fleet apply --create-only creates each object, of every kind it takes, or
refuses one whose name is taken with exit 5 and leaves it as it is; the
store's create is
exclusive, so two clients applying one name at once get one object and one
refusal. A view creates its Tasks this way.
fleet runtime hosts --json prints {"hosts": [...]}: the hosts a Task may
name, local first and then each other place, <runtime>/<place>, or
null when the fake [runtime] serves any. The command keeps its old name
until thurbox reads fleet runtime places. fleet runtime places --json prints
each place with its readiness
(configuration). fleet runtime browse <place> [dir] --json
prints {"dir", "entries"} and fleet runtime branches <place> <repo> --json
prints {"names", "default"}, read through the runtime's browse and
branches verbs. fleet version --json lists the harnesses with a profile of
their own; any other harness name is run as a program. A view checks a
Task against both before it applies it.
fleet doctor [--json] checks this machine. It reads and writes nothing in
the store. Each check has one level: ok, info, warn or fail. A check
that needs a step names it as a hint.
| Area | What it checks | Levels |
|---|---|---|
integration |
each harness with an [install] table, as fleet integration status reports it (installed integrations); each ledger entry that no harness profile with an [install] table names |
warn for outdated and modified; warn for an entry left behind, with fleet integration uninstall <agent> as its hint; info for not-installed, agent-missing and unsupported-platform; fail when the ledger cannot be read |
harness |
each harness's program, found on PATH |
info when it is not there: a user installs only the agents they run |
store |
the free space on the disk of the data directory | warn below 256 MiB, or when the free space is unknown; not checked on Windows |
runtime |
each place of each runtime, by its id <runtime>/<place>: its runtime program answers manifest with protocol 1 or 2 and the required verbs, and reports the place ready; a version 1 runtime serves only local |
fail when a place is not ready, with the runtime's why; fail when it does not answer; fail when no runtime is configured, or when [runtime] is not the fake with its dir |
The exit status is 1 only when a check fails. Warnings alone exit 0.
With --json, it prints {"checks": [...], "failed": N}. Each check has
area, name, level, detail and hint.
fleet attach TASK [--wake] --json prints {"stream": {"argv": [...]}}: the command
that opens the Task's terminal stream,
run where the view runs. A Task being deleted exits 3 and says so, with or
without --wake, and the message suggests no wake. Fleet asks the runtime
serving the session's host for its attach answer. A stream answer is passed through; a tty answer
is wrapped as fleet term-bridge -- <argv>, so a view only ever gets a
stream. A Task with Paused=True exits 3 and says it is paused, unless
--wake is given: then Fleet first sets status.wakeRequestedAt, which
TaskController resumes the session for, and waits up to 60 seconds for
Paused to leave True. A Task still paused after that wait exits 3 and says
it is paused. With --wake, a paused Task that is held or Stalled exits 3 at
once, because Fleet never resumes it. A view that attaches every Task in the
background, as thurbox does, never passes --wake, so it resumes nothing it
paused. A lost session is revived without --wake, Concluded Tasks
included: when the runtime offers no view and reports the session lost,
Fleet sets status.wakeRequestedAt and waits up to VIEW_WAIT_MS (60
seconds) for SessionLost to turn False, then asks again. A lost Task that
is held or Stalled exits 3 at once, and one still lost after the wait exits
3. A Task with no session yet, a
runtime that does not declare attach and a key the runtime holds no
process under exit 3; an Unknown answer exits 4.
Without --json the argv is printed one argument per line.
fleet shell TASK [--json] [--wake] is the same for an interactive shell beside the
Task's session, on its place: Fleet asks the runtime's
shell and answers as fleet attach does.
A runtime that does not declare shell exits 3.
fleet term-bridge -- <argv> is that bridge: it runs the command on a pty of
its own through fleet-exec and relays it as the terminal stream on its stdin
and stdout, until the view detaches or the command exits.
The config file is versioned TOML; relative paths are relative to it, and
configuration owns its
fields. This one runs the fake runtime, and the test
the_contract_examples_apply_as_written applies it with the Task below:
version = 1
[data]
dir = "data"
[runtime]
kind = "fake"
dir = "fake-host"
A real host is served by a runtime program, and a [forge] section names
the forges ChangeRequests are read from:
[runtimes.mux]
program = "runtime-mux" # a path, or a name beside fleet, else on PATH
callTimeoutMs = 15000 # the bound on every call; shorter than the lease
keyPrefix = "fleet" # give a second fleet on the same runtime its own
# no places table: one place, spec.host = "local"
[forge.hosts]
"github.com" = { kind = "github", cli = "gh" }
"bitbucket.org" = { kind = "bitbucket-cloud", cli = "curl" }
[forge.readyPolicies.checks] # selected by spec.forge.draft.policy or
forge.draftPolicy
checksPassed = true
A Task manifest:
[
{
"apiVersion": "fleet/v1alpha1",
"kind": "Task",
"metadata": {"name": "design-305", "labels": {"topic": "fleet-305"}},
"spec": {
"harness": "claude-code",
"host": "local",
"brief": "Write the controller design.",
"workspace": [],
"dispatch": true,
"outputs": {"prUrl": {"type": "string", "required": true}}
}
}
]
fleet reconcile takes the manager lease, runs passes until nothing changes
(or --max-passes), and gives the lease back. Its default lease is 30 s,
raised to twice the longest operation of the runtime, forge, gateway or
plugin port.
fleet init creates the native per-user config offline. A config that
exists is kept, never replaced. It also writes the TaskConfig default, with
pauseAfterMs 1800000, into the config's store when the store holds none
(the default TaskConfig),
and the Boards shared and fleet, each with the default spec, when the
store holds none. The
initialization guide
specifies precedence and paths.
fleet up creates no Task. It retains the manager lease across periodic
sweeps for all due Tasks. The poll interval
must fit inside the lease as well as runtime operations. Ctrl-C/SIGTERM stops
after bounded work and releases the lease; Tasks and sessions survive. Crash
recovery waits for lease expiry. Uncertain runtime observations remain Unknown.
fleet up reads its config file once, when it starts.
e2e_bootstrap covers installed first-run, repeat and concurrent
initialization, a kept customized config, the refused [starter], resident
progress with no starter, exclusive startup and crash/reconnect.
Tests #
The e2e_* suites drive the real fleet binary against an isolated store,
the fake host or runtime-mux, and, for e2e_forge, the fake forge
or a stub copied as az, curl, gh and glab, across process
restarts and injected faults; e2e_inbox covers fleet send and delivery on
the fake host; e2e_event_board covers fleet event publish and list,
the Board fleet init makes, the refusals, the dedupe, the filters, an
expired cursor, and a session's publish through its outbox, as its Task;
e2e_event_subscriptions covers fleet event subscribe and
unsubscribe, the digest notice, its hold while undelivered, an expired
cursor, an unreadable Board and a Board made later on the fake host;
e2e_task_amend covers fleet amend, its delivery to the same session,
its refusals, --if-generation and the result rules on the fake host;
e2e_forge_controller covers fleet declare, the join and the relay
against the fake forge and the fake host.
e2e_mark_ready covers the mark-ready effect against the fake forge and
the fake host, and through the stub az, gh and glab.
e2e_gateway covers the [gateway] section, the receive verb, the
Conversation mirror and the Listener against the fake gateway;
e2e_gateway_controller covers the tie, the join and the relay into the
inbox, fleet send --answers, the parent labels and a child's relay into
its parent, against the fake gateway and the fake host.
e2e_telemetry exports to an in-process OTLP/HTTP collector: the spans and
metrics of a Task's lifecycle and of forge polls arrive with their
identities and outcomes and without a brief, message or environment value;
nothing is sent when export is off; an unreachable collector changes no
command; a caller's TRACEPARENT parents a command's root span.
e2e_bootstrap proves that Ctrl-C on fleet up flushes its sweeps.
e2e_runtime_exec runs a Task through runtime-mux and workspace-git
with one OTEL_EXPORTER_OTLP_ENDPOINT: the spans of all three programs
arrive in the Task's one trace, the key metrics arrive, and the agent's
window inherits no OTEL_* variable or TRACEPARENT. Under fleet up,
and through fleet attach and fleet shell, every runtime VERB,
runtime-mux and workspace-git span has its parent in its own trace.
e2e_runtime_exec runs fleet attach against the reference script, whose
tty answer comes back bridged, and against runtime-mux, whose stream a
test view drives: snapshot, input, output, and a detach that leaves the
agent running. It runs fleet shell against runtime-mux, where a view
types into the shell and finds it in the Task's directory, and against the
reference script, which has no shell; it also drives fleet term-bridge on its own, and reads
fleet runtime hosts, fleet runtime places, fleet runtime browse and
branches (and their refusal when a runtime does not offer the verb), and
the harnesses fleet version lists.
e2e_interactive covers a Task with no brief: its spawn, its inbox and the
refused amendment; and apply --create-only, which never changes a Task
already there.
e2e_watch covers fleet watch: the first read, a resume with --since,
a deletion while the watch runs, and synced again after an unreadable
store.
e2e_workspace covers the workspace calls against the fake runtime: one
workspace call, the ready spawn, the release after the session, a crash
between the call and its receipt, a lost request, an unreadable key, a URL
the runtime does not handle, and the refused shapes before the URL list.
task_controller, task_workspace, change_request_controller, forge_controller,
conversation_controller, listener_controller and gateway_controller
test each controller as a pure function, one transition or Unknown per
case.
store_contract tests the store against races, torn writes, stale leases
and the fenced delete. The architecture suite enforces the graph above.