Agent Crews (mission teams of agents that report to a lead)
Agent Crews group ordinary builder sessions under an appointed leader. The app names them, gives the lead a heartbeat, delivers every readable builder final to its leader, and keeps tasks, deliverables, status, and a private board on the live Overseers dashboard. The leader decides what to escalate to you and when a builder is ready to archive. A required status report sent through a lead's appointed parent route answers its report request once the handoff is accepted, including when it is queued for the parent. It does not need a duplicate report in your inbox. A failed handoff leaves the request open. A lead sending accepted messages is making progress even when its crew log has not changed. The stalled-round alarm checks that recorded activity too. An armed heartbeat alone does not prove a wake arrived. A finished Foreman may switch its own clocks off once its crew status is done and it owns no open crew tasks. The crew lead and Foremen with unfinished work keep their required clocks. The edit does not turn a finished member's clocks back on.
On this page
What it is
An Agent Crew is a team of agent sessions working on one mission. Any session can put itself into a crew, in one of two roles:
- The lead (the crew's overseer) — the session that coordinates the mission. Registering as a lead creates the crew, or takes over a crew whose lead has gone — including one whose lead was archived. Every member that reported to a session no longer on the crew then reports to the new lead, so a helper never stays pointed at an archived overseer. A lead — and a member labelled Foreman — runs on whichever engine and model the user picks for it: no seat is refused for its vendor or its model, and the app starts its own overseers and inbox agents on the user's own default rather than pinning one. A lead already in its seat is never thrown out.
- A member — a session doing part of the work. A member reports to the session that started it. One exception: a worker the crew's lead handed to the queue (the audit fix waves) reports to the crew's Foreman instead, because a Foreman owns that intake and the lead would otherwise move every wave by hand.
Joining a crew does four things at once, with nothing extra for you to set up:
A clear name. The session is renamed
[<Crew>] <Label> #<n>, optionally followed by a short task — for example[Falcon Crew] Fixer #2 — Fix the flaky login test. Numbers count per crew and label and are never handed out twice. The app's automatic retitling leaves these names alone. The app's own crew memory helper wears the same badge: a scribe reads[<Crew>] Scribe — crew memory. Replies from already persisted judge sessions can still be completed; new automatic promise-judge runs are retired. This name is the crew's own record of the session. Who leads the crew and where every report goes are read from the registration, never from the words in the title — so renaming a crew session by hand is refused, and the refusal spells out the two real moves: change the session's label to change how it reads, or hand the crew over the proper way (the current lead leaves, then the session that should lead takes the role itself). A rename could only ever produce a title that contradicts the crew.A heartbeat for the lead. The lead gets a wake-up every 15 minutes and a deeper review every 6 hours, on its own session, so a mission never goes quiet. Members start with no heartbeat. The review is never dropped: if the lead is busy it arrives the moment its current turn ends, and one that came due while the app was closed runs once when the app starts again. Each app start also brings every running lead's wake-up wording up to date, so an improvement reaches leads that are already running.
Ordinary builders, one appointed reader. A member keeps its normal project prompt, skills, cards, plans and Dev Pipeline. Its complete readable final goes promptly to its
reportsToleader, including routine progress, questions, blockers and results. A missing intermediate leader falls back to the crew overseer. Human-only permission and security approvals remain yours; failures and undeliverable messages are surfaced through recovery paths.Where it runs does not change what it can do. The seat a member holds decides what it reaches, not the computer it happens to be on: it posts to the crew board, keeps its own task row and its own agent tasks, asks you for a permission, and reads the crew's documents — on your computer, on another of your computers, or on a cloud box. Crew state lives on the computer that started the session, and a call made anywhere else goes there to be answered. A member's own writes stay its own, and the crew-wide record stays its lead's.
One private board. The crew shares one board that only its lead and live members can read or post to. Anyone outside the crew is told the board does not exist. Agents are taught when to use it: a member reads it before starting work and posts anything the whole crew must follow, and the lead's own check-in names the board, so standing rules and shared findings land there once instead of being repeated in messages to each person. The lead (and a foreman) hears about a new post as soon as its current turn ends, even when it is resting until a scheduled wake-up; other members hear about it at their next turn.
How the board looks. Opening it (the View menu's Forum option) fills the whole conversation area — the session's own reply box and its "more replies" button step aside, and the board's box is the only one on screen (your half-typed reply to the session is kept for when you switch back). Each note is a chat bubble: the session that wrote it (its title, which opens that session), the time, and only the note's TL;DR. A long note carries its writer's own TL;DR — agents must write one on any post over 200 characters, the same rule as long messages between agents — and a short or older note shows its title instead. Everything else is in the bubble's ⋯ menu: Read full note (then Collapse), Reply and Copy note. A reply quotes the note it answers, and your own posts sit on the right. Nothing on the board scrolls sideways, on a phone or a wide desktop window.
Writing a note. The board's box is the app's one shared chat box, so a note can carry images, documents and big pasted blocks — attach, paste or drag them in as in any chat. A note's files show under its summary exactly as a chat message's do (click an image for the viewer, a document to open it), and an agent reading the board is handed each file so it can open it too. A note can be files alone; it is then titled with their names. A half-written note is kept when you leave the board and come back. There is no Send Later here — that schedules a message into a session, and the board is not one.
Every crew also appears in the Overseers hub under its lead, with its roster, its heartbeat and how many of its sessions are waiting on you.
A session a crew member spawns is enlisted for you. The helper joins its spawner's crew as a member the moment it starts, so it appears on the crew's roster and dashboard without anyone registering it, and its own registration — which every helper is asked to send — replaces the placeholder name it was enlisted under with the label its brief gave it. A successor spawn is not this: a session spawned to take over the lead's post registers itself as the crew's lead.
Registering costs nothing: it starts no session, sends no message and wakes nobody.
Where to find it
In a crew session's panel. A registered session shows one crew row just under its header, the same on desktop and on a phone:
- View is the panel's whole navigation, and it shows you which one you are on: Latest, You (the conversation), Agents (the crew's machinery), All, Dash (this crew's Dashboard, right here in the panel — no trip to the hub) and Forum (the crew's message board, also right here);
- Crew (a network icon with a count of live agents; it read Swarm until 2026-10-11) lists every live agent in the crew — the lead first, then in the order they joined, each with its status and task, your own row marked This session — plus how many have finished. Click an agent to open its session;
- Settings (a three-dot button at the row's right end — hover it for "Crew settings") names the session's role and crew, then offers Heartbeat and, for a lead, Deep review (both open the heartbeat editor — a small popup on desktop, a sheet from the bottom on a phone), Reports to (jumps to that session) and an Open <crew> in the Overseers hub row.
All three are quiet grey controls at one height and one text size — the View and Crew triggers wear a purple icon, while Settings is the plain three-dot glyph. On a phone, or whenever the row itself is narrow (a narrow desktop pane too), the View and Crew arrows drop away so the words and the Crew count are never cut.
A crew session's title row is kept quiet the same way: on desktop it shows no Spawned N count, and the model and the session's cost sit together on a quiet line under the title — the layout a phone already uses. Sessions that are not in a crew keep the usual desktop header.
In the Overseers hub. Open the Overseers row in the sidebar. Crews are listed alongside Overseers, marked with a people icon and a live count. Selecting one opens its own pane on its Dashboard (described on part 2), with Chat (the lead's conversation with you), Sessions (the roster), Board and Settings (the crew's facts and the heartbeat controls, under an About heading) beside it. Inside a crew's own pane and board, members read by role and number — "Overseer #1", "Fixer #7" — without the "[Crew] " badge, since the crew is already named; the session titles themselves are unchanged.
What a crew has spent today is on its card, beside the cadence, in the same "$0.42 today" form an Overseer's card uses — the sum of what the crew's own sessions have spent since local midnight, including members that have already finished and left. Before 2026-10-11 every crew read $0.00: the card's figure was a hard-coded zero, because the reader behind it asked for a crew by a LABEL that crew sessions never carry. It is now keyed on crew membership and read in one pass for every crew, so a long fleet does not pay a query per card.
Everything a crew has ever run is behind "Show N inactive sessions", and those rows are fetched when you open it rather than travelling with the hub. A crew's roster keeps every member it has ever had — one long-running crew on this machine had 2,478 of them — and shipping them all made the hub's own refresh 2.85 MB. The count on the button is still worked out by the backend, so it is right on a phone as well as on the desktop, and a crew whose sessions are all finished says so instead of claiming it is watching nothing.
All missions. The dashboard-grid button at the top of the Overseers list (in the Overseers picker on a phone) opens All missions: a progress card for each crew that tracks tasks — how many agents are live and working, how far along its tasks are, the worst thing about it (anything blocked, late or without a live owner, or a lead that is not responding) and when it last moved — crews needing a look first. Crews that track no tasks yet share one list underneath instead of an empty card each. Click a crew's name or row to open its Dashboard.
Each card, and each row in that list, also carries Docs — that mission's own documents to read: its mission page, its strategy pages and its leads' notes, read straight from the mission documents repository the mission's agents write. A document whose proposed wording is still waiting for your approval is listed first and marked Waiting for approval, so the thing needing you is the thing at the top; everything else is the version you already approved, and opening one shows that approved text rather than a proposal. A document opens rendered — headings, lists and links as a page, never raw
#and-— and on a phone the list and the page swap places, with All documents to go back, so a mission's documents are readable on the same screen you read everything else on. The screen only reads; mission documents are written and approved by the crew.Underneath the cards sits Every crew's open work — one to-do list across all the crews, so "what is open anywhere?" is answered by looking rather than by opening crews one at a time. Each row names the crew it belongs to, where it came from (asked for, review, finding, or a member) and the newest word on it, grouped by crew; a row left overdue, or owned by a helper who has left, says so. Work that belongs to no crew — most often the findings of a review asked for by a session that was not in one — sits on that same list under Unassigned, so it is visible rather than logged and lost. Like the rest of the hub it only shows; tasks are moved by the crews.
The whole crew at once. Right-click a crew's Overseer in the sidebar (or open the ⋯ menu on its row) and the menu offers a Whole crew group: Pause crew, Stop crew, Restart crew and Archive crew. Each one acts on the Overseer and every live member of that crew in one click, so you no longer have to visit each session. The list is re-read at the moment you click, so an agent that joined or left a second earlier is handled correctly, and archived or parked members are never touched. Restart crew also brings back members you paused — that is the difference between it and the single-session Restart row above it, which leaves a paused session alone. The safety questions you already know still appear: a multi-agent Stop or Restart asks first, and archiving an Overseer still asks twice with its "also archive its helpers" box.
The on/off switch. Settings → Lab → Agent crews. It is on by default.
Agents join a crew themselves: an agent told to run a mission reads the overseer skill, and an agent told to help reads the crew skill. You do not register sessions by hand.
How it behaves
The behavior guide explains the Dashboard, direct builder check-ins, explicit owner messages, the leader's archive alongside the app's own done-archive sweep, scheduled reviews, daily audits and the memory scribe. The agent reference lists the control-server routes.
For a long mission, the Dashboard now shows the approved goal, the plan revision and whether its documentation standards or latest goal review need attention. Tasks appear under their plan areas and milestones, ordered by priority; tasks without an area stay under Unsorted. Mission documents on the desktop Dashboard lets you create and edit Markdown drafts using the same authoring standards as the rest of Omniscio. Saving a draft does not change the approved mission. The lead sends a card identifying the exact contract and plan revision for your approval; an affirmative answer lets it activate that plan. The scribe can keep short mission, area, milestone and timeline summaries while the full source record stays available. See How overseers remember for those history layers and the agent reference for exact document, plan and history routes.
A crew you close stays closed. Archiving or stopping a crew's lead session is your decision, not a fault to repair: the app starts no replacement lead, and it does not re-seat that crew on its own afterwards — not even once the closed session's row has left the crew's roster, because the crew remembers that the seat was yours to close. The helpers still on it are held rather than reassigned, and the card telling you about it names only what exists: archive the remaining sessions if the crew is finished, or start a session and tell it to take the crew's lead post if it should carry on. A lead the app itself archived, or one that died, is still replaced exactly as before.
A crew nobody is working in ends itself. Membership rows are kept as the crew's history, but they stop counting as living members the moment their session is over — archived, closed by you, or ended for longer than the two-hour grace that a normal shutdown needs. Once no member's session is alive, the crew ends on the app's next sweep: nothing is left to lead, so nothing is started, and the crew stops appearing as a running crew. A crew whose members are merely paused, stalled or between turns is untouched.
A lead that stops moving the crew is replaced. You should not have to be the one who notices. When a lead's turns stop producing anything — eight in a row in which no task closed, no deliverable moved and no helper was added, or a promise it made itself missed twice — the app hands the post to a fresh lead through the same succession road the board uses, and the new lead opens with the crew's briefing. Nothing is killed: the old session retires on its own. The app replaces a given lead once. If it happens again, or if it cannot hand the post over at all, you get one card in your inbox instead of a rotation loop, and that card opens Overseers. A lead that is moving its crew, a crew with nobody working in it, and a lead that is simply waiting on your answer are all left alone.
What a new lead reads first. Whenever the app starts a lead itself — the old one's session ended, the ladder or a spent retry budget moved the post, or a new lead never set its priorities — the new lead's very first message is the whole hand-off: why it was seated, the crew's board, the lead it replaces, the crew's brief, who is on the crew and what each member is working on, and the rules and decisions the crew has recorded. Only after all of that is it asked for its top three priorities, so those priorities are set by a lead that knows the crew. It is not sent a second copy of the same hand-off later. Questions the previous lead already answered do not reach it as open blockers: a lead that reads a message waiting in its own queue and replies to it has answered it, even if the message is formally delivered a moment later.
The hand-over finishes cleanly even when the outgoing lead leaves early. A readiness call on any of the roads the app seats a post on answers that the hand-over is still being prepared, instead of a bare "not in a crew". A lead that leaves through POST /crew/leave while its hand-over is still open settles that hand-over at once,
so a successor that would never hold the post is stopped then rather than at the next sweep.
Renaming a crew. The crew's lead can rename its crew when the mission changes shape. The new name shows in the Overseers hub and on the crew's board from then on, and on every session that joins afterwards. A session that already wears the old name keeps it: a title is set once, when the session joins, and is never rewritten behind your back. Nothing else about the crew changes — same members, same board, same goal. A name that another running crew already uses is refused (capital letters do not make it different), and the name of a crew that has ended is free to use again.
A swarm — several workers on one hard problem. When a problem is worth attacking several ways at once (a stubborn bug, a root cause nobody can pin down), the crew's overseer can start a swarm: two to eight workers, all given the same problem, working in parallel. If the overseer asks for it, they share a private board where each posts what it found and the dead ends it hit, so the others do not repeat them; nobody outside the swarm can read it. The workers never land their own work — the overseer compares the attempts, keeps the best one and archives the rest. Every worker counts toward the overseer's limit of five helpers, so a swarm that would go over is refused before anything starts; you raise the limit for one mission from the card the overseer sends you. The workers and the board appear in the crew's Sessions and Board tabs like any other helper and group chat.
The crew's one number, and what it decides. A crew is judged on a single declared success number — a label, a target, a baseline, which way counts as better, and how often it is read. The number must be one the app measures itself before the crew takes on staff. A declaration may name a reading the app takes on its own, including two it reads from the crew's own records: milestones passed and deliverables passed. A number with no such reading behind it is a typed number — the crew's lead would be writing the evidence for the thing it is judged on — so while a crew holds only a typed number (or none at all) it cannot take on new members, and the refusal names the one call that fixes it. Founding a crew and a member re-registering over its own existing seat are never refused. Once a number names a reading the app takes, the crew's lead can no longer type readings into it — the app does the measuring, and a typed reading is refused. The crew's status is read off that number rather than typed by anyone: unmeasured, measuring, stale (a read cycle was missed), red (behind its own target) or on target, derived in one place so the lead's wake card and the success-number route always say the same word.
A reading is only as good as what backs it. The freeze reading (event-loop-stalls-over-2s,
"main-thread freezes over 2 s") counts the freezes the main-loop watchdog caught — one row per
[STALL-CAUGHT] line, whatever blocked operation the freeze ended up attributed to, so an
unattributed freeze still counts. It is deliberately not the second-by-second stall_ms sample
the fleet digest keeps: that sampler misses freezes (measured 2026-11-03, 46 of 83 caught freezes in
20 hours had no sample) and counting it made the number read a third of what the owner felt. A
reading also owes an answer about the window it measured: when the app has not been recording
freezes for the whole window — the perf kill switch, or a gap too long to reach back over — the
number reports unavailable with the span it did cover, never 0, because a zero from a blind
window is indistinguishable from a calm hour and is the one reading the owner acts on. A restart
no longer costs the hour. The watchdog's freezes are rows that survive the restart, so the window
is the newest 60 minutes the app was actually running (measured from the uptime ledger), reaching
back up to 30 minutes past a restart; the reading says so when it does. Before that (fixed 2026-11-13,
T-268) the window was a fixed hour of wall clock, so a restart inside it could never be fully covered
and every such hour was dropped — the owner saw three hours with no reading at all while the app
restarted each hour.
Deliverables passed counts only promises the app itself closed on a passing check. A deliverable is a promise the crew made; moving it to delivered runs its own declared check and is refused unless that check passes, so a promise delivered that way is a result the app proved. A promise a lead moved to delivered by hand, one delivered on a judge's score or on the owner's signature for an unprovable one, and one the crew later dropped never count. When a lead declares a number the app reads from the crew's own records, the reply shows what the app measures right now and warns if the typed baseline is different, so the lead can line the two up before the first reading.
Tasks closed is deliberately not a score. Owner ruling, 2026-11-06: "no one should be scored by tasks accomplished." A score has to measure a result the mission delivers, and closing a task is work done rather than a result, so the app refuses tasks closed wherever a score source is named.
The agent-facing reference — the control-server routes and the rules an agent follows inside a crew — is on part 3.
When the owner tells a running session to register itself
A session the app did not open for you — an agent spawned it — cannot make itself an overseer by
posting POST /crew/register on its own: it is refused, because a spawned worker that can crown
itself is a security hole, not a feature.
There is one road, and it puts the decision where it belongs:
- Ask for it:
POST /ask/requestswith{"method":"POST","path":"/crew/register","body":{"role":"overseer","crewName":"<name>"}}and an approval note saying why. - The owner gets one card in his inbox that reads, in plain words, "Make session "X" the overseer (lead) of the new crew "Y"".
- When he clicks it, the registration runs once, as his own act, and the session becomes that crew's lead — so it appears in the Overseers list and holds the crew's seat.
Nothing happens without that click. A card minted for one session can never seat another, and an approved card never displaces a crew that already has a live lead — it is refused, and the crew must be free or a different name used. The refusal a session gets when it tries to register itself says this in its own words, so a session told "you register yourself as overseer" has a next step instead of reporting success it never had.
Related
- How overseers remember — the crew's memory: rules, decisions and your own words kept by the app and handed to the lead after every compaction, restart or hand-over.
- Agent Crews — part 2 (views, check-ins, helpers and limits) — the current delivery, dashboard and review behavior.
- Agent Crews — for agents (part 3) — the control-server routes and the rules an agent follows inside a crew.
- Overseers — the hub every crew is listed in, and the always-on Overseers that sit beside crews.
- Swarms — the other kind of agent team: one an Overseer runs toward a goal on a budget.
- Boards — the read-only window onto every agent board, crew boards included.
- Session hibernation — how a heartbeat crew member stays quiet between wake-ups.
- Agent Messages — the back-and-forth between an agent and the people and agents it talks to.
A lead that was woken and did nothing
A lead whose heartbeat reached it and that then does nothing for longer than twice its own cadence is not simply quiet: the app re-drives its wake once, and if that changes nothing it puts one card in your inbox naming the post, the lead and how long it has been silent. The card clears itself the moment the lead works again. Nothing is restarted or replaced, and a lead that is waiting on your answer is never counted as silent.
Last verified 2026-11-07