Work
The work page, at /work, is a kanban of every ticket in your channels: one column per stage,
one card per ticket. Cards move to their new column as soon as fleet sees the event. You do not
have to reload the page.
- A card shows the title, the type, the priority, the agent on it with its state dot and its latest line, and how long the ticket has been in this stage. A Live card also shows its release and its push-to-live minutes, for example "3.2 min push to live".
- In a column, cards with priority now come first, then next, then later.
- The top line counts the tickets being built, the tickets waiting to merge, and the tickets that went live today. It also shows "push to live today: median X min (n)": the median push-to-live minutes of the n tickets that went live today (UTC date), in every channel. It is absent when none did.
- A Waiting card shows how long it has waited ("waiting 4m"). The top line also shows "wait to merge today: median X min (n)": the median of the stays in Waiting that ended today (UTC date).
Trunk repos
A repo whose .fleet/ship.yaml says merge.mode: trunk has no merge train. Workers run
fleet land; a Landed <sha> on <base> by fleet land comment is the merge, like the train's
Merged comment. The Waiting column is never used for it. When the trunk guard reverts a landing
it comments Sent back: reverted <sha> ...: the card moves to Sent back and the worker's next land
is a new round. A ready message to the train of a trunk repo is answered "this repo is
trunk-based: run fleet land" and is not queued. The top of the page shows main's state from
GET /v1/trunk/<project>: "red since ", with "bisecting of landings" while the guard
looks for the culprit; else "checking " while a check of main runs; else "green at " (the
last green). "(observe)" follows when the guard only watches. A repo with no guard, or a guard that
is off, shows nothing.
fleet merges ready branches itself
In a repo on the train (merge.mode: train), a worker that finishes sends ready t/<n> <sha> to
the merge-train agent (merge-train...). A trunk repo (swarm-lab) has no train: the worker runs
fleet land, and a ready is answered "this repo is trunk-based: run fleet land".
fleet serve takes that message itself; the agent gets no turn for it:
-
Green and on top of main: when the sha's own checks (lint, test and build) are green and main fast-forwards to it, fleet pushes it to main at once and comments
Merged <sha>on the issue. -
Green but behind main: fleet rebases it on main with no help. Every such branch goes on one
train/<date>-<n>branch, which is checked once. A green train fast-forwards main with all of them. A red train is halved until the one bad branch is found; only that one is sent back. -
Ready while a train is checked: the branch does not wait for that check. Fleet rebases it on the running train's tip and pushes that as a train of its own, so its full check starts at once. When the train under it is green and on main, it goes on main at the sha that was checked. When the train under it is red, it goes by a new train on main, with a new check.
-
A rebase conflict where both sides only added lines (a new test at the end of a file, a new entry in a list): fleet keeps main's lines, then the branch's, and the branch goes on the train as usual, so the full gate still checks the result. The
Mergedcomment names the files. -
A rebase conflict where both sides changed the same line (a list both branches extended, a docstring's ticket list, a renamed constant), when serve.yaml turns on
merger.resolver: fleet makes one cheap model call with the conflict hunks and both commit messages, and puts the answer in place of the hunks only. The issue gets amerge conflict resolved by fleet: <files>comment with each hunk and its resolution, and the branch goes on the train, so the full gate judges the result. If that train is red, the branch goes back to its worker, and the message names the resolver's diff. fleet never does this for a contract file (api/openapi.yaml,mcp-tools.json,ledger-v1.json, the SQL migrations,states.go,driver.go,backend.go,registry.go,runner/hooks.go), a line that one side deleted, a model answer that keeps a conflict marker or repeats the lines around a hunk, a decline, a second conflicting commit of the same branch, or a call past the daily cap: those go back as below.merger: resolver: on: false # off by default profile: <id> # an api_key profile (driver claude); never a subscription login model: claude-haiku-5-5 per_day: 20 # model calls per UTC day -
Any other rebase conflict: the branch goes back to its worker at once, with the conflicting files named, as a message and as a
Sent back by fleet:comment on the issue. -
Failed checks, or a head that moved after ready: sent back the same way. A branch is merged only at the sha its worker reported ready.
-
What fleet cannot do by itself (no check ran on the sha in 15 minutes, a git error) goes on to the merge-train agent, with the reason.
Main moves only by fast-forward, never by force, and only to a sha whose own checks are green.
The clones live in the server's state directory (merger/). FLEET_MERGER=off in the server's
environment turns this off, and the messages go to the agent again.
Push to live
Push to live is the time from the push of a ticket's code to the time it runs on the servers:
- The push is the committer time of the newest commit on the main branch that names the ticket. The merge train fast-forwards, so this is when the code that shipped was last pushed.
- Live is when continuous deploy finished putting the first release that holds that commit on
the servers. Continuous deploy adds a line
live: <RFC3339 UTC time>to the body of the Forgejo release for that tag. The page reads the newest 50 releases. - A release with no
live:line uses its creation time instead. The release workflow runs a few seconds after the tag is pushed. The card then shows~before the minutes. The median counts these estimated values too. - A tag with no Forgejo release has no live time, so its cards show no minutes.
- Needs attention shows first, with a red edge, only the tickets that wait on you: Blocked (a
worker is blocked or asks you a question), Ruling only when the keeper handed the ticket to you (an
ask-first item, "Owner ruling needed:"), and Sent back with no worker on it or none active in
the last 15 minutes. A sent-back ticket whose worker is working or was active in the last 15
minutes stays in Building with the note "fixing: checks failed". Its Forgejo label is still
stage:sent-back. An opentype:incidentticket is in Needs attention too, with the note "incident", until a worker is active on it (#368). A Parked column shows when a ticket is on hold. - Open shows the Live column for today, and every open ticket that is Live (#581). Live shows only the Live column. All also shows
Closed. The channel buttons pick one channel. Open reads a smaller board: no closed cards and
no closed card that went Live more than 24 h ago (every open ticket stays; an open ticket whose
commits are Live shows "live, issue still open: close it or finish the rest") (
GET /v1/work;?all=1gives every card). Live and All read every card, so moving between Open and them loads the page again (#379). - Under the title is a line that lists the columns in order, left to right. Ruling comes after it on its own: a card does not move there from Live. Each column header has a small i. Tap it, or focus it and press Enter, to open a note: what the column means, what moves a card in and out, the typical time in the column, and whether you have to do anything. Press Escape or tap i again to close it. Only Needs attention asks for you.
- The typical time is the median of the stays that ended in the last 7 days. Fleet reads it from
the history of the
stage:*labels on each issue, which Forgejo stamps when the server puts a label on and takes it off (GET /v1/work, fieldtypical). A stay that has not ended is not counted. Needs attention counts Blocked and Sent back together. History starts on the day the server began to keep the labels; a column with no finished stay says so. - Worker opens the agent's chat. Ticket opens the issue in Forgejo.
Type, priority and stage labels
Each ticket has one type and one priority, set when it is filed, as Forgejo labels:
- type:
type:feature,type:bug,type:spike(an investigation with a time limit that ends in a report),type:chore(cleanup and upkeep),type:incident(production broke or got stuck). - priority:
prio:now,prio:next,prio:later. Workers and the board takenowfirst.
The server keeps one stage:* label on each issue, the same as the card's column:
stage:filed, stage:building, stage:checking, stage:waiting, stage:merged, stage:live,
stage:sent-back, stage:blocked, stage:decision. It sets the label at each Forgejo event and every 2 minutes,
so a Forgejo filter by label matches the board. It makes the labels that a repo does not have.
A person sets stage:parked to put a ticket on hold, and the server does not remove it. A
ticket parked only by the label held (a pause, below) gets no stage:parked, so a resume
unparks it.
The stages
| Stage | What it means | How fleet knows |
|---|---|---|
| Filed | The ticket is open and nobody works on it. | The issue is open and no agent is on it. |
| Building | An agent works on it now. | An agent started with the ticket is queued, working or retrying, and no check runs on its branch head. A paused or stopped agent does not make a ticket Building. |
| Checking | Checks run on the latest push, or on the merge train's run that holds it. | A check runs or waits on the newest head of the ticket's branches (t/<n>, t/<n>-*, t/<n>/*), whatever its agent does; or a train/* branch whose checks run has a commit that names the ticket. The card links the run (checks). |
| Waiting to merge | The checks passed, or the agent finished and handed the branch to the merge train (fleet merges it itself, see above). | The check status is success, or the agent is done and no check runs or failed (the train rebases and runs them again). |
| Merged | It is on the main branch, not in the running release yet. | A commit on main names the ticket at the start of a bracket, (#n), (#n, #m), (Refs #n), (Fixes #n), (#n, slice a), or at the head of its subject, podcasts #n: ...; or the head of its branch is on main. A ticket branch with a commit that is not on main (by subject, since the merge train rebases) is in flight, not Merged. A mention such as "recommend #n over x", another tracker's number such as (Renovate #n), and a commit older than the issue are not a merge. |
| Live in rc.N | It runs in production. rc.N is the first release that holds it. | The first release tag that holds the merge, and the running release holds that tag. A project whose .fleet/ship.yaml names a live observer, or that has a live rule (below), goes Live by it instead, and its card says "live by" the observation. |
| Sent back | The checks failed, or the merge train sent it back. | A failed check status, or a ticket comment that starts with "Sent back" and is newer than the last push. |
| Blocked | The agent is blocked or waits for an answer, or the dispatcher gave up on it. | The agent's state, blocked or needs input, or the label dispatch:blocked. A blocked report alone is not enough: a worker that reported blocked and then works again is Building. While any agent of the ticket works, it is never Blocked. |
| Ruling | A spike's report, or a design, merged; the keeper rules it (Ruling (keeper): ...). It shows in Needs attention only when the keeper posted Owner ruling needed: ... (an ask-first item). |
The issue has type:spike, or a comment that starts with "Deliverable 1" or says "docs only"; it is open, and no comment that starts with "Ruling", "Rulings", "Decision" or "'s ruling" is newer than its first merge. After a ruling it is Filed ("ruled: build not started") or Building until the build merges, then Merged and Live as usual. Closed, it leaves the board. A report alone is never Live. |
| Parked | On hold on purpose. | A person set the label stage:parked or held, or pressed Pause on the card (which sets held; the card says "paused by" who). Nothing moves a parked ticket until a person removes the label or presses Resume. |
| Closed | The ticket was closed with no merge. | The issue is closed and no merge is found. Closed wins over a green or failed branch, a merge-train run and the worker's state: a closed issue is never Waiting, Checking, Building, Sent back or Blocked (#476). A closed issue that merged is Merged or Live. |
The self-check
Every 15 minutes the server reads every repo again (past its cache) and every agent, builds each card again, and checks what its stage promises against the sources:
- Building: an agent of the ticket is queued, working or retrying.
- Blocked: no agent of the ticket works, and one waits on a person.
- Live: Forgejo's compare says the deployed release holds the merge commit, or the project's
observer (ship.yaml
live, or its live rule) says what runs now holds it. - Merged: the merge commit is on the main branch, and the deployed release does not hold it yet.
- Waiting to merge: the branch head's checks are green, or its agent is done.
- Checking: a check runs on the branch head, or on the merge-train run that holds the ticket. Building: none runs on the branch head.
- Filed: no agent of the ticket works. Closed: the issue is closed.
A card it cannot confirm, or whose source it cannot read, shows a muted "unverified since
", the last time the stage was confirmed; the reason is in the tooltip. The server logs
each one (work: self-check: card unverified), and a card the page shows in another stage than
the fresh read (the cached card is stale), which also makes the page read again.
The page reads Forgejo through the server's token. Each Forgejo webhook (a push, an issue or
label change, a comment, a release, a commit status) changes the kept data at once. A full read
of each repo reconciles what a webhook missed: every 5 minutes, or every 20 minutes while
webhooks arrive. The page gets each change over a stream (GET /v1/work/events).
How the server spares Forgejo (#443):
- One reader for commit statuses serves the page, its check loop, its self-check and the merge train. A finished status (every job done) is read once. A running one is read first after 8 seconds; each read that finds the same answer doubles the wait, up to 1 minute, and a changed answer (a job ended) sets it back to 8 seconds. So a card leaves Checking within about a minute of its CI ending. A merge train waiting on its own run reads it every 15 seconds. For a repo whose status webhooks arrive, a running status is read every 2 minutes and each webhook reads its commit at once.
- Issue and comment lists are read whole once an hour. The reads between ask Forgejo only for
what changed since the last read (
since=). - An issue's timeline (for the typical time per stage) is read at most every 30 minutes, and only the events since the last read.
- A ticket branch's commits off the default branch (Forgejo compare) are read once per branch head. They are kept for an hour while the default branch moves, and through a restart. "Is this merge in release tag X" is asked once per merge and tag.
- Forgejo 15 has no commit-status webhook event, so status webhooks arrive only from a Forgejo that sends them.
The server needs forgejo_url in its config and FORGEJO_TOKEN in its environment. The labels
need a token that can write issues. Without forgejo_url, the page says so.
How a project goes live
Live is observed, not claimed: a ticket is Live when what runs now holds its merge (shipping
standard §1 step 5). Each repo says how fleet observes it in live of its .fleet/ship.yaml
(read from the default branch at each full read):
live.by |
Live when |
|---|---|
version-url |
GET url answers a sha (plain text, or JSON {"sha": "..."}, 7 to 40 hex characters) that is on the default branch and holds the merge. Fleet reads the URL at most once a minute per repo, with no token. "Live since" is the first time fleet saw a sha that holds the merge. |
deploy-commit |
The newest deploy: <app>@<short-sha> commit in repo (the default branch of that repo) holds the merge. match is "deploy: <app>@{short_sha}". |
workflow |
The newest succeeded run of deploy.workflow (or live.workflow) on the default branch holds the merge. |
release |
The release-tag rule: the deployed fleet release holds a tag that holds the merge. |
branch |
Merged is Live (a tool installed from the branch head). "Live since" is the merge. |
live:
by: version-url
url: https://app.example/version
fallback: {by: deploy-commit, repo: owner/infra, match: "deploy: app@{short_sha}"}
While the version URL cannot be read (an error, a status other than 200, or no sha in the
answer, such as a Cloudflare challenge page), the last sha read stands. fallback never makes a
card Live: a deploy commit is written before the rollout ends, so it is not proof that the site
runs the sha. A merged card whose merge only the fallback holds stays Merged with the note
unverified: deploy: app@<sha>, version URL: <why>, and goes Live when the URL answers a sha that
holds it.
What runs now is the newest observation. If it does not hold a merge, the card leaves Live: a rollback to an older sha takes the newer tickets back to Merged (ruling Q10). "Live since" is when the oldest of the unbroken run of observations that hold the merge was seen, so a later deploy does not move it. The page keeps the version URL's history in memory, so after a server restart "live since" starts again from the first read.
A repo with no .fleet/ship.yaml, or one with no live, can have a live rule in serve.yaml,
by repo name (ruling Q9: this is the fallback):
live_rules:
my-app:
workflow: build-deploy.yaml # a Forgejo Actions job name or workflow file that succeeded on the default branch
deploy_app: app # a commit "deploy: app@<sha>" in deploy_repo
deploy_repo: owner/infra
A merged ticket is Live when the newest succeeded run of the workflow, or the newest deploy
commit, names a commit that holds the merge. deploy_repo is the repo that holds the deploy
commits; deploy_app needs it. With no ship.yaml and no rule, the release-tag rule applies.
Every merged ticket is worked out again at each read, so tickets that went live before the rule
existed move to Live; the Live column still shows today's. A project whose release is manual,
with no workflow and no deploy commit, has no rule: its tickets stay Merged.
The dispatcher
With dispatch: in its config, the server starts a worker on each ticket that waits for one,
every minute. It is on for the projects listed, and off with none. The ruling of 2026-11-11 turns
it on for swarm-lab only.
- It takes the open tickets that are Filed, or Sent back with no worker on it. Parked tickets, tickets with a running worker and tickets whose worker a person stopped get no worker.
- It takes
prio:nowfirst, thenprio:next, oldest first. A ticket withprio:lateror no priority gets no worker, and its card says why. - Each worker is unpinned, on branch
t/<n>, with the worker brief (brief_file, the cos template) and the ticket text. The model is Sonnet, or Opus fortype:incidentand for a ticket whose text names a contract file. - The limit is machine load (#559), not a fixed count. Each pass it starts one worker for each
node with room: its 15-minute load per vCPU under
max_load_per_cpu(a fixed node, default 0.8) orrent_load_per_cpu(a rented one, default autoscale's--rent-load-per-cpu, 2), more thanmin_mem_available_pct(20) of its memory free, a free turn slot, and the node takes work. Its own workers still queued use that room first. When no node has room and autoscale may rent another machine under its--max-spend, it starts one worker, which makes autoscale rent. - It also needs an inference profile with room: when every profile the workers could use is
limited (on any window) or at its
max_concurrent, pace or usage threshold, the tickets wait. max_workers(default 40) is only a hard safety ceiling. A ticket that waits stays Filed, and its card says why: the ceiling, the nodes' numbers, or the profiles.- The server logs each pass that has tickets waiting:
dispatch: load room=N rent=... nodes=...with each node's 15-minute load per vCPU, free memory and turns. - It never starts a second worker on a ticket. A ticket that came back more than twice (sent
back, or its worker ended) gets no more workers: the server puts
dispatch:blockedon it and comments on the issue, and the card is Blocked for the chief. - Its workers' cards say "dispatched by fleet". The switch at the top of the page pauses and resumes it (admins only, kept across restarts); the workers that run keep running.
- An Urgent ticket (
prio:now) may start one worker over the limit when the limit is full: one at a time, the oldest Urgent ticket first. A second Urgent ticket waits for room. - It starts nothing for the projects of a paused channel (below); their cards say
waits: channel <name> is paused by <login>.
dispatch:
projects: [swarm-lab]
as: octocat # whose usage the workers spend; default the first admin
# max_workers: 40 # the hard safety ceiling (default 40)
# max_load_per_cpu: 0.8 # a fixed node has room under this 15-minute load per vCPU
# rent_load_per_cpu: 2 # a rented node's (default autoscale's --rent-load-per-cpu)
# min_mem_available_pct: 20 # a node needs more memory free than this
# limit_by: max_workers # max_workers alone, no load rule (the rule before #559)
# incident_hold: 5m # an incident gets no worker until it has been open this long
# close_grace: 10m # a worker whose ticket closed is told, then stopped after this
brief_file: /etc/fleet/worker-brief.md
Pause, resume and priority
Pause is a hold, not a stop. A held agent's running turn ends at once (on a node, at its next
heartbeat, within about 10 seconds), and the agent is paused with the reason
held: paused by <login> (ticket <project>#<n>) or (channel <name>). Its conversation and its
worktree stay. Resume queues it again, and its next turn continues the same conversation. Live
chats and chiefs are never held: a person is typing in them. Only an agent that runs a turn or is about to
(queued, working, retrying, lost) is held; a blocked agent or one that waits for an answer runs
nothing and stays as it is.
- A ticket. Each open card has a Pause button. Pause puts the label
heldon the issue (the card goes to Parked and the dispatcher skips it) and holds every live agent on the ticket (by its--ticket, or at/<n>branch in the project). Resume takesheldoff and releases the agents that a ticket pause held. An agent held for another reason (a channel pause, no progress) stays held. CLI:fleet ticket pause swarm-lab#558,fleet ticket resume swarm-lab#558. - A channel. Each channel on the Work page has a Pause channel button, and a banner "Paused by X
since Y" while it is paused; the chat list greys the channel and shows the same banner. Pause
stops the dispatcher for the channel's projects, holds every live worker in the channel (its own
conversation's channel, its parent's, else its project's channel), and holds a worker spawned
into the channel while it is paused at its spawn. Resume releases exactly the agents held with
the pause's reason and dispatches again. CLI:
fleet channel pause Fleet,fleet channel resume Fleet. - Priority. Each open card has an Urgent / Normal / Later selector:
prio:now,prio:next,prio:later. A change rewrites the issue'sprio:*label. Urgent goes first in the dispatcher's queue and may go one over its limit (above); Later is never dispatched. CLI:fleet ticket prio swarm-lab#558 urgent.
Who: a person with a write token who is a member of the project (or any project with no
members; admins any) pauses, resumes and prioritises its tickets. A channel's pause needs the
same as changing the channel (a person, not an agent token). Each change is a ledger event with
who did it: ticket.pause, ticket.resume, ticket.priority, channel.pause (with the ids it
held), channel.resume (with the ids it released).
Branch previews
A ticket whose branch changes a page file (fleet/internal/web/**, fleet/internal/ui/**) or
has the label preview gets a preview once CI has built its head commit. The Work card shows a
preview link and the ticket gets one comment with the link; the comment is edited on each push.
Previews need preview.user (a unix user other than the server's, which cannot read the state directory) and preview.origin (their own host, never the main one) in serve.yaml. Without them the server logs a refusal and starts none. On the preview's origin you sign in again: it does not share the main page's token.
Open the link, sign in as you do on the page. The link sets a cookie, and your browser then gets
the page files (HTML, CSS, JS) from the branch's build. Every API call still goes to the
production server with your login, so the data is the production data and the preview adds no
write: only GET and HEAD of page files reach it. /preview/off clears the cookie. A branch that
adds an API endpoint shows that endpoint as missing, because the API is production's.
It stops when the branch merges or is deleted, when the ticket closes, and after 4 hours with no
visit (preview.idle). At most 3 run at once (preview.max). Turn it on in serve.yaml with
preview: {enabled: true}; the server needs CI's cache (preview.cache_dir) on its own disk.