team brief

team brief rollout delivers TeamCLI's general seat brief — the built-in first text every seat gets, held in this build — to the team's declared seats without a launch. The brief is the general seat brief; a launch writes it into a seat's drop folder itself, as a signed message record, before it types anything, and this command is the same delivery for a team whose seats are already up, or whose briefs were written by an earlier build.

A delivery is a claim and a drop. The claim, in the session's state, names the delivery's incarnation, the runtime epoch, the brief's sha256 and the drop id the record must have; the drop is the signed message record at exactly that id. team brief rollout writes both through the boundary every launch calls, so a seat delivered here and one delivered by team up stand identically. The plan reads both: a seat is current when its claim is this build's brief and the record at the claim's id verifies. current is the delivery's currency, never the seat's read — whether the seat has read the brief is team check's line, and the rollout writes no receipt.

The dry run is the default and writes nothing at all: no state, no drop, no receipt. A seat with no claim, an old build's claim or an earlier text is delivered at the id that delivery will use; a name held by a file that is not this brief's, a link or a folder is left untouched and recovered at the claim's next attempt. A declared seat the state does not record as running is not mailed into its stopped folder: its next launch delivers it, and the plan says so. A human seat is delivered to like any other and is never read.

A live inbox server keeps the parsers of the build it started with: installing a build does not reload a running process, and a server from an older build can refuse a record this build signs before it ever reaches its body. When a due seat's listener marker names another build — or records no build identity at all — the plan reports the seat stale, writes nothing to it, and says that the seat's CLI host must restart for its MCP server to reload the installed build. The check never downgrades a signature: the runtime is refreshed, not the record.

How a delivery travels is the brief-transport policy, read at entity, project and team. file, the default, is exactly the claim and drop above. message writes the same claim and the same signed record, then sends the whole brief through the seat's own delivery legs, with the send command's own walk: the seat gets the whole body — never a pointer — and the send's receipt, history line and outcome are an ordinary send's. memory is an experiment that no runtime in this build proves zero-persistence for: a memory policy delivers nothing, refuses every seat and every team send --brief, and falls back to neither of the other two transports. A launch reads the same policy and delivers the same way.

Synopsis

team brief rollout [--apply] [--seat <seat>] [--session <session>] [--file <path>] [--json]

Flags

FlagValueEffect
--apply—run the plan: write each due seat's claim and signed drop, recover a held name at the claim's next attempt, and report each seat as it ended; without it nothing is written
--seata declared seat nameplan or deliver for that seat alone; the other seats are not planned, written or reported, so a targeted retry leaves the team alone
--sessiona session namethe session to deliver in; the team file's own unless the owner names another
--filea paththe team file to read; the owner's alone
--json—print one team.brief document (format: 1, project, session, apply, seats, counts) instead of the per-seat lines
--help, -h—the usage, and exit 0

rollout is the command's one subcommand, and it is required: team brief alone, another word, or an extra word is an invocation error, as is an unknown flag.

What it reads and writes

Reads the team file — the one the checkout git names, or this folder's own team root — and, from .agents/team.state.json, the session's seat records and each seat's brief claim. It reads the drop folder of every seat the state records as running and of every human seat, at .agents/send-drops/<session>/<seat>/: the record the claim names is verified against the checkout's message key and compared with the claim's seat, session, incarnation and expected id, and a live .inbox-listener beside it is read for the build identity its server records.

--apply writes the claim in the state under the state's lock, then the signed record at exactly the claim's id, and finalizes the claim at the record's own time. A name held by a foreign regular file, a link, a FIFO or a folder is never replaced, removed or followed: the run records the claim's next attempt and posts the drop at that attempt's id instead, leaving the held name byte for byte as it was found. Nothing is typed, no pane is read, and herdr is not called.

Who may run it

The owner reads any team file it names. Everyone else is held to the read gate: a seat whose own placement — name, session and pane — matches the state's record may read its team's plan, and a caller outside every seat is told this team is not yours to read. A caller who is not the owner cannot aim --file or --session: those flags name another team's or another session's records, and the refusal is the owner's.

Output and exit codes

The plan prints one line per declared seat:

  • brief <seat>: current <hash12> <id> — the claim is this build's brief and its record verifies;
  • deliver <seat>: <hash12> -> <id> — the delivery the plan would make, at the claim's lifetime (a seat with no claim has no lifetime yet, so its row shows the id a fresh one would produce, and --apply mints the lifetime it writes and reports the id it used);
  • recover <seat>: the name at <id> is not this brief's; would deliver at <id> — the name at the claim's id is held, and the delivery moves to the claim's next attempt;
  • not running <seat>: delivered at its next launch — not a target this run;
  • stale <seat>: <reason> — the seat's live inbox server runs another build, so the seat is not written to; the reason says which host restart reloads the installed build;
  • human <seat>: delivery only — delivered, never read.

--apply replaces deliver with the same line and recover with recovered <seat>: the name at <id> is not this brief's; delivered at <id>; a seat already current is printed as current, a stale seat is printed as stale and written nothing, and a seat whose delivery failed is failed <seat>: <reason>.

OutcomeWhat is printedExit
the dry run finds every live or human seat currentthe per-seat lines0
--apply leaves every live or human seat currentthe per-seat lines0
the dry run finds delivery, recovery or stale workthe per-seat lines1
--apply leaves a live or human seat stale or failedthe per-seat lines, with the failed seat's reason1
a caller who is not the owner aims --file or --sessionthe owner-only refusal1
the invocation can't be readteam brief: <problem>, with the usage2
a caller who may not read this team asksteam brief: this team is not yours to read2
the team file can't be read or parsedteam brief: <problem>2

The --json document is {"schema": {"name": "team.brief", "version": 1}, "format": 1, "project": …, "session": …, "apply": …, "seats": [{"seat", "action", "hash12", "id", "from", "reason", "current"}], "counts": {"current", "deliver", "recover", "not_running", "human", "stale_listener", "failed"}}. action is current, deliver, recover, recovered, not-running, stale-listener, human or failed; hash12 is the first twelve hex digits of the brief's sha256; from and reason are null unless the row names them. An invocation or team-file error under --json prints the team.error document with its brief.* id instead.

Example

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

identity:
  humans: [[email protected]]

trust:
  - ~/.config/team/lobby
  - ~/Code/beacon

workspace:
  mode: shared

seats:
  - role: orchestrator
    name: claude-keeper
    leads: true
    label: orchestrator
    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: operator
    name: desk
    label: desk
    cli: claude-code
    vendor: anthropic
    model: Claude Opus
    version: "5.5"
    launch: claude
    human: true

Each seat's claim names a lifetime whose record the folder does not hold yet: a launch that wrote the claim was stopped before its drop. The dry run plans the deliveries and writes nothing:

Terminal
 team brief rollout ; echo "exit $?"
deliver claude-keeper: a7257d193b0b -> a41f5f43-2689-5329-9e9c-ce349ba1329d
deliver claude-beacon: a7257d193b0b -> e8886d51-6117-5711-9b0b-a4ca3af7e0f1
human desk: delivery only
exit 1

--apply writes each claim and its signed drop, in the seat folders under .agents/send-drops/beacon/, and reports the same ids:

Terminal
 team brief rollout --apply ; echo "exit $?"
deliver claude-keeper: a7257d193b0b -> a41f5f43-2689-5329-9e9c-ce349ba1329d
deliver claude-beacon: a7257d193b0b -> e8886d51-6117-5711-9b0b-a4ca3af7e0f1
human desk: delivery only
exit 0

Now the claims and their records agree, so the plan finds every seat current; the human seat is still reported as delivery only, because it is never read:

Terminal
 team brief rollout ; echo "exit $?"
brief claude-keeper: current a7257d193b0b a41f5f43-2689-5329-9e9c-ce349ba1329d
brief claude-beacon: current a7257d193b0b e8886d51-6117-5711-9b0b-a4ca3af7e0f1
human desk: delivery only
exit 0

A name that is not this brief's is never replaced. Here another file sits at the implementer's expected id; the plan moves the delivery to the claim's next attempt and says what it found:

.agents/send-drops/beacon/claude-beacon/e8886d51-6117-5711-9b0b-a4ca3af7e0f1
not a message record: another program's file, left where it is
Terminal
 team brief rollout ; echo "exit $?"
brief claude-keeper: current a7257d193b0b a41f5f43-2689-5329-9e9c-ce349ba1329d
recover claude-beacon: the name at e8886d51-6117-5711-9b0b-a4ca3af7e0f1 is not this brief's; would deliver at 9136cf90-9ca5-5ac9-8f0b-d2578ee32cee
human desk: delivery only
exit 1

--apply posts the record at the second attempt's id and leaves the held file exactly as it was:

Terminal
 team brief rollout --apply ; echo "exit $?"
brief claude-keeper: current a7257d193b0b a41f5f43-2689-5329-9e9c-ce349ba1329d
recovered claude-beacon: the name at e8886d51-6117-5711-9b0b-a4ca3af7e0f1 is not this brief's; delivered at 9136cf90-9ca5-5ac9-8f0b-d2578ee32cee
human desk: delivery only
exit 0

--json prints the same plan as one document:

Terminal
 team brief rollout --json ; echo "exit $?"
{
  "schema": {
    "name": "team.brief",
    "version": 1
  },
  "format": 1,
  "project": "beacon",
  "session": "beacon",
  "apply": false,
  "seats": [
    {
      "seat": "claude-keeper",
      "action": "current",
      "hash12": "a7257d193b0b",
      "id": "a41f5f43-2689-5329-9e9c-ce349ba1329d",
      "from": null,
      "reason": null,
      "current": true
    },
    {
      "seat": "claude-beacon",
      "action": "current",
      "hash12": "a7257d193b0b",
      "id": "9136cf90-9ca5-5ac9-8f0b-d2578ee32cee",
      "from": null,
      "reason": null,
      "current": true
    },
    {
      "seat": "desk",
      "action": "human",
      "hash12": "a7257d193b0b",
      "id": "3e114db0-a3d9-576d-b56f-c8cda2b38213",
      "from": null,
      "reason": null,
      "current": true
    }
  ],
  "counts": {
    "current": 2,
    "deliver": 0,
    "recover": 0,
    "not_running": 0,
    "human": 1,
    "stale_listener": 0,
    "failed": 0
  }
}
exit 0

The invocation is checked before anything is read:

Terminal
 team brief ; echo "exit $?"
team brief: a subcommand is required: rollout
Usage: team brief rollout [--apply] [--seat <seat>] [--session <session>] [--file <path>] [--json]

Delivers this build's general seat brief to every declared seat that is live
or human. The plan reads each seat's claim and the signed record the claim
names: a seat with no claim, an old build's claim or an earlier text is
delivered at the id that delivery uses, and a name held by a file that is not
this brief's, or by a link or a folder, is recovered at the claim's next
attempt without touching what is there. A human seat is delivered and never
read. A declared seat that is not running is left for its next launch. A seat
whose live inbox server records another build is reported stale and is not
written to: that server keeps the parsers it started with, and restarting the
seat's CLI host is what reloads the installed build. Without --apply the plan
is printed and nothing is written: no state, no drop, no receipt.

Options:
  --apply    run the plan; each seat is reported as delivered, recovered or
             failed, and a seat already current is reported current
  --seat     one declared seat to plan or deliver for; the others are left
             untouched
  --session  the session to deliver in, the team file's own unless the owner
             names another
  --file     the team file to read, the owner's alone
  --json     one team.brief document ({format, project, session, apply, seats,
             counts}) instead of the per-seat lines

Exits 0 when the dry run finds every live or human seat current (brief.plan)
or --apply leaves every one of them current (brief.current); 1 when the dry
run finds delivery work (brief.stale), --apply leaves a seat stale or failed
(brief.incomplete), or a caller who is not the owner aims --file or --session
(brief.file-owner, brief.session-owner); 2 when the invocation can't be read
(brief.invocation), a caller who may not read this team asks
(brief.not-yours), or the team file can't be read (brief.file,
brief.file-invalid).
exit 2

A caller outside every seat learns nothing of the team, and the plan is not printed:

Terminal
 team brief rollout ; echo "exit $?"
team brief: this team is not yours to read
exit 2