team check

One answer to one question: is anything wrong with this team that someone should act on? It reads the team file, the record this machine holds of it, the state, herdr and the registries, and changes nothing except the repairs the owner's --repair makes — the state's two leftovers dropped, the dev-mode mark an agent's registration left cleared, and herdr's drifted sidebar lines set back from the file — no git is needed, so it answers as well in a plain folder as in a repository. Where team status says what the team is, the check says what to act on: the differences alone, each with its repair. It is also the old name of team commits check and team pr check, still read through 0.3.3. A <ref> (a range when it holds .., passed to git as given, otherwise that one commit) runs that older reading, as do --pr <file> (check a pull request's body as well; - reads standard input) and --since <ref> (skip that commit and everything reachable from it). --file is read by both readings; --session is this one's alone, and the older one meets it with team check: unknown option --session and exit 2. --repair is this one's alone too, and the older one meets it with team check: unknown option --repair and exit 2. A run of the older reading says once on stderr which command now holds it, and --pr adds its own line.

The registries answer for the team's place: a team the project registry names in two projects is a difference naming both, repaired by fixing the registry file, and so is a registry that cannot be read. A team whose file sets project_lead: true while another team of the same project sets it too is one as well — the project <name> has <n> lead teams: <names>, repaired with take "project_lead: true" off all but one of them. The two herdr sidebar lines each file seat carries are compared on the same pass: a workspace label or display line that reads as neither the file's own text nor a line the watch may paint is a difference repaired with team register <seat>, which re-applies both lines from the file without a relaunch. A live seat the state holds ready that the team registry's record does not list in its roster is a difference too, repaired with the same team register <seat>: where the registry holds a record of the team, its roster is the record of who its seats are for the permission bridge, and a seat the roster does not list has none. A team the registry holds no record of is not this difference — the bridge reads the file's own declaration then. A seat no source has heard from past the blind threshold — five minutes shipped, tightened through the inheritance's levels and opened again only by a project — reads unknown (blind) in team seats and counts as not working: <seat>: unknown for over <threshold> — blind, and it counts as not working, repaired with the owner's look at the pane.

The entity's model rule (team swap) is read on the same pass: every seat of the team this check runs in whose declared vendor the rule forbids is one difference, naming the rule, the seat's vendor and the swap proposed — or why none is — and repaired with team swap queue <seat>, which the team's lead runs. Breaches in the entity's other teams are not this team's differences: the check answers for the team it runs in. A rule that cannot be read is a note, never an empty rule that would read every seat as in rule.

The general seat brief every launch delivers first is checked on the same pass. A delivery is a claim and a drop: the claim in the state names the delivery's incarnation, runtime epoch, the brief's sha256 and the id the record must have. A seat the session launched — a human's pane too, once the session has launched anything — with no claim, or with one an older build wrote before claims existed, is the difference <seat>: the general seat brief has not been delivered, repaired with team reload <seat> or team up, or with team up alone for a human's pane. A recorded delivery is not taken on trust: the check opens the record at the claim's id and verifies it against this checkout's message key, the claim's incarnation and this build's brief. A record that is missing, unsigned, signed by another key, bound to another lifetime or epoch, or holding another body is <seat>: the general seat brief's delivery record does not verify, with the same repair. When this build's brief is ahead of any seat's claim, the run prints the one rollout hint run team brief rollout --apply to deliver the general seat brief to every live seat, after the per-seat lines and before the summary. The --json document carries the same line as hint.

A CLI seat is then asked for its read. <seat>: the general seat brief has been delivered and not read is repaired by the seat's own next turn; a seat whose record says it has no turn-start reader (watcher absent or none) is told how to read by hand, with team drops --read --seat <seat>, and how to install the launch's hooks, with team reload <seat>. The read receipt must bind the current claim — its id, incarnation, text hash and the epoch it was written under — so a receipt an earlier agent, an earlier text or an earlier runtime left is <seat>: the general seat brief's read receipt is stale (an earlier agent or an earlier text), and a receipt file that does not verify for the claim is <seat>: the general seat brief's read receipt does not verify, whose repair is team brief rollout --apply recovering the delivery at a new id (the file that does not verify is left in place). A delivery whose launch did not reach ready keeps its launch difference and its read is not demanded: the seat reads <seat>: the general seat brief has been delivered; launch not ready, and a read that arrived before readiness is <seat>: a read happened before readiness; the runtime is not confirmed. A human seat is delivery-only and is never asked to read. team check writes none of this: it has no writer mode and no --rollout, and the only act it names is the seat's own read or a delivering command's.

Unread work is named on the same pass. Each seat's drop folder is read the way the watch's unread wake reads it: a message with no signed read receipt past watch.unread_after — ten minutes when the file omits it — is one difference for the seat, <seat>: a message from <from> has been unread for <n> min (id <id>), with ; <m> more unread when other messages are due and the oldest named. The sender is the verified record's own from; a record that does not verify is named an unverified message and keeps its age, its id and its count, never the word beside it — that marker is unsigned and lends no sender, owner or seat. The repair is the seat's next turn, or team drops --read --seat <seat> when the seat's record says no turn-start reader is installed; the watch's unread wake types that same read into an idle seat. The general seat brief keeps its own read difference and is not counted twice. A person's drop is read by a person and is never asked for a receipt. The check writes nothing here either.

A seat held at a prompt is named on the same pass: one line per held seat, read from the pane the state records for it through the watch's own screen reader. A pane that no longer holds the process team launched — back at its shell, or replaced by one the state's stored session does not vouch for — is not read for a prompt: the check's own process line already says what the pane is, and a dialog left in its scrollback is not a seat held at one. The line names the seat, the prompt's kind — a permission prompt, a trust prompt, a quota prompt (a usage limit, with the reset the screen words — resets at 11:00, resets in 47h31m — or the screen names no reset time), a confirm prompt (the CLI's own exit question), or an unrecognised prompt — the command the screen shows when the profile's trace reader finds one, and the age the state's clock gives it: <seat>: stuck at a permission prompt (last active 4m ago): Write(note.txt). The age is the seat's last active moment, the only instant its record carries: the prompt stood up after it, and the line never claims the prompt itself has waited that long. An unrecognised prompt is a screen no profile reads whose safety floor carries a prompt row; the line quotes that row — matched "Do you want to continue?" — and a screen the floor did not catch keeps the watch's blocked line instead. A permission prompt is its lead's to answer; a trust prompt, a quota screen, a confirm prompt or an unrecognised one is the owner's, and a confirm prompt also closes with team down --abandon, a quota screen with the reset it names. The check never answers, types or nudges: the line names the act, and the pane's own reader takes it. Where compare() already printed its plain permission or trust row for the seat (status's wording), the check replaces it with this one line, so a held seat is named once. A temporary seat — one team add --temporary recorded and the file never names — is read the same way, from its record, with its like-seat's CLI.

A watch the machine daemon hosts is read on the same pass, as notes only. The check names the ones a reader would act on: a watch whose last pass failed reads watch: the last cycle failed, with the age the record gives that pass when it holds one (watch: the last cycle failed <age>); a watch standing down for a live pane watch reads watch: standing by; a live pane watch owns this session (<reason>), and it touches nothing in that session; a required watch that stopped or failed reads watch: stopped in the daemon (<reason>) or watch: failed in the daemon (<reason>); and a watch whose outbound effects are closed adds watch: outbound effects blocked (no verified admitted sender is injected); it is not enforcing anything, whatever its phase — it can cycle while those effects are closed, and the check never prints it as enforcing. The rest of the watch is quiet: a watch that is simply cycling, one still starting or stopping, one that has not completed its first pass, and a stopped or failed watch the record does not call required add no phase line, and a route the daemon records no watch for prints nothing at all — a watch exists only where one was started on purpose. A stopped or failed watch is terminal in the record: nothing here restarts it, and the daemon does not bring it back by itself, so it runs again only when it is started again. With more than one watched route, each line ends with its route, … (<root>).

A pane watch the session's state records is read through the same liveness predicate team up plans from, and the same rules keep it quiet: a live process with a fresh heartbeat adds no line. A recorded process that is gone reads watch: the recorded process <pid> is gone; the next team up starts one; a live process behind an old or unreadable heartbeat reads watch: process <pid> is alive but its heartbeat is old; the next team up replaces it; a record with no process or pane reads watch: recorded with no process or pane; the next team up starts one; and, when the daemon reading proves no hosted watch owns the route, no watch at all reads watch: none running; the next team up starts one. A hosted watch that owns the route suppresses the pane reading, and a session that is not running has no watch to expect. When the daemon's health cannot be read, the pane line names that limit instead of a repair up will not make, and a standing-by hosted watch does not claim a live pane watch that its record no longer shows. These notes never enter the total and never change the exit.

The state's leftovers are differences too. A record for a seat the file no longer declares — one an older file named and this one dropped — and a session the file does not name with no seat of the team in it are both named: <seat>: left the team file but its record still claims pane <pane> (its pane named when the record expects one) and the state records the session "<name>", and no seat of the team is in it. The file is the truth: neither record is ever guessed back into the file, and the one repair is team check --repair, the owner's own write, which drops exactly those records from the state. A record for a temporary seat is never one of these — team add --temporary never writes a temporary seat into the file, and its record is the only place it exists. Nor is the session this run reads, the file's own or the one --session names: one is where the team runs, the other is what the run is about, and --repair never drops the record the check is reading. Herdr is not consulted about any of this: a pane herdr no longer lists is still a pane the state claims, and a session herdr runs is still a leftover when no seat of the team is in it. The repair still waits for the live read: a check whose herdr cannot answer refuses with check.herdr, exit 2, and drops nothing.

The owner's --repair is one write over the findings the check can settle from what it already holds — the file is the truth — and nothing more. The state's leftovers above are dropped. A seat an agent registered under dev mode, the record the check counts rather than names while dev mode is on, is recorded again with the caller gate in force: the same write the owner's own team register <seat> makes, with the mark and the caller it named cleared. Each herdr sidebar line that drifted is set back from the file through the same rename and display report team register <seat> makes. Each repair is named in one repaired: line and written to the log; a herdr that will not take a sidebar line says so as team register does, and its difference stands. Everything else keeps its advice — a model drift's relaunch, a blind seat's look at the pane — because those are decisions, not writes the file settles, and --repair never starts, stops or relaunches a seat.

A leftover team file

When the team is in the registry and a .agents/team.yaml is still in the project, the run prints one note — .agents/team.yaml is still in this project, and is no longer read (the team is in the registry): run team migrate to move it to the Trash — and neither refuses nor counts it. A leftover that says something else than the registry is a difference, with team import as the repair.

Synopsis

team check [--session <name>] [--file <path>] [--repair] [--json]

Flags

FlagValueEffect
--session<name>the herdr session to read, instead of team.session; the owner's alone
--file<path>deprecated: a legacy team file to read instead of the team's registry record; the owner's alone
--repair—the owner's repair, one write: drop the state's leftovers (a record for a seat the file no longer declares, a session with no seat of the team in it), re-record a seat an agent registered under dev mode with the caller gate in force, and set herdr's drifted sidebar lines back from the file; the owner's alone
--json—emit the structured team.check JSON document on stdout (schema/check.schema.json)

Who may run it

CallerMay
the owner, from a terminal outside herdrcheck the team; an owner without a terminal is not this caller
a seat of the team being checkedthe same answer, placed in the file's session, on the pane the state records for it
a pane outside the team that the live file names in its delegates entriesthe same gate the changing commands use, minus the command list and the audit line: the check is a read, not an act
anyone elsenothing: the fixed sentence team check: this team is not yours to check, whatever failed underneath

Aimed by a caller that passes the gate but is not the owner, --file, --session and --repair meet the refusal every command gives them and exit 1.

Output and exit codes

Every run prints the declared limitation of a client app key, on stdout in text mode and as the key_isolation field in JSON: key isolation: enforced against team panes (key file still readable by same-user processes).

OutcomeWhat is printedExit
nothing needs acting onteam <project>, session "<session>", any deprecation warning: or note: lines, and no differences0
the owner's --repair repaired what it can (the state's leftovers dropped, dev-mode marks cleared, drifted sidebar lines set back), and nothing else needs acting onteam <project>, session "<session>", one repaired: <what was repaired> line per repair, and no differences0
something needs acting onteam <project>, session "<session>", one difference: block per finding with its repair: and who: lines under it, then <n> difference / <n> differences (and , <m> for the owner when any finding is the owner's)1
a flag the caller may not aimthe refusal every command gives it1
the check can't run (the loader's, the state's or herdr's own text), the invocation can't be read, or the caller may not check this teamteam check: <problem>, or the one fixed sentence2

Example

team config edit
format: 1
project: beacon
entity: lab
operator: claude-keeper

identity:
  humans: [[email protected]]

trust:
  - ~/.config/team/lobbies/lab
  - ~/Code/beacon

workspace:
  mode: shared

seats:
  - role: coordinator
    name: claude-keeper
    leads: true
    label: coordinator
    cli: claude-code
    vendor: anthropic
    model: Claude Opus
    version: "5.5"
    launch: claude --model claude-opus-5-5

  - role: implementer
    name: claude-beacon
    label: implementer
    cli: claude-code
    vendor: anthropic
    model: Claude Opus
    version: "5.5"
    launch: claude --model claude-opus-5-5

  - role: implementer
    name: worker
    label: worker
    cli: claude-code
    vendor: deepseek
    model: DeepSeek Flash
    version: "4.0"
    launch: claude --model deepseek-flash

The team runs as the file and the state say, so there is nothing to act on (the note is the housekeeping of a role word written the 0.3.5/0.4 way):

Terminal
 team check ; echo "exit $?"
team beacon, session "lab-beacon"
key isolation: enforced against team panes (key file still readable by same-user processes)
note: the lead seat "claude-keeper" carries the 0.3.5/0.4 role word "coordinator"; the 0.5 word is "orchestrator" — sends reach it either way, since admission keys on the lead seat, not the role: set `role: orchestrator` on it when convenient
note: watch: the recorded process 4242 is gone; the daemon health cannot say whether a hosted watch owns the route
no differences
exit 0

The entity's rule refuses this lab, and the check names each seat of the team it runs in with the swap the queue would take — the same breach list team swap --rule prints for the entity:

Terminal
 team policy set entity model-rule '*=!anthropic' ; echo "exit $?"
policy: set model-rule=*=!anthropic at entity (lab)
exit 0
 team check ; echo "exit $?"
team beacon, session "lab-beacon"
key isolation: enforced against team panes (key file still readable by same-user processes)
note: the lead seat "claude-keeper" carries the 0.3.5/0.4 role word "coordinator"; the 0.5 word is "orchestrator" — sends reach it either way, since admission keys on the lead seat, not the role: set `role: orchestrator` on it when convenient
note: watch: the recorded process 4242 is gone; the daemon health cannot say whether a hosted watch owns the route
difference: claude-keeper: declares vendor anthropic, which the entity model rule *=!anthropic refuses; a swap to claude-code DeepSeek Flash 4.0 from beacon/worker is proposed
  repair: team swap queue claude-keeper
  who: the team's lead
difference: claude-beacon: declares vendor anthropic, which the entity model rule *=!anthropic refuses; a swap to claude-code DeepSeek Flash 4.0 from beacon/worker is proposed
  repair: team swap queue claude-beacon
  who: the team's lead
2 differences
exit 1