--- name: agents description: "Use when supervising bro-managed agents — respawn a lost worker, stop one, or check the agent plane across orchestrator connectors. Thin wrapper over `bro fleet agents` — mechanics live in the CLI." --- # /agents (bro) **All mechanics live in the `bro` CLI.** This skill is policy only. Prereq: `bro` on PATH or `npx -y @broject/bro@0` (major-pinned), plus `bd` — `up ` claims and renders prompts through the shared beads store. `bro fleet agents` is the supervisor surface over the orchestrator connectors (native detached processes, gascity, tmux, docker, …). The agentId registry in the git common dir makes an agent's identity survive its process — a respawn reuses the dead agent's id, worktree, and stored prompt. The `docker` connector runs each worker in a container — the image comes from `agents.docker.image` or the repo's devcontainer (see `agents.docker.*` in configuration docs). Worktree, git common dir and beads store mount at their host paths, so the same registry/claims/exit contract holds; an unreachable docker daemon degrades the view, never a stale 'lost' verdict. The `copilot` connector dispatches GitHub Copilot coding-agent tasks — hosted remote workers that open pull requests. The step is claimed into the shared beads store _before_ dispatch (the remote runner can't reach it), the registry pins `{taskId, pr}`, and `down` best-effort cancels the backing Actions run — a surviving session is reported, never hidden. `agents.copilot.maxSessions`/`maxWorkers` count remote live tasks via a cached count that fails closed when stale. ## Commands | Command | What it does | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bro fleet agents status [] [--json] [--connector ]` | The agent plane across every backend; an arg prints one agent's detail. Degraded backends warn — never a hard failure of the view, but a targeted miss exits non-zero when a backend is degraded ('gone' is only claimed on a healthy read) | | `bro fleet agents up [] [--connector ]` | No arg: the backend's supervisor up (a `supervisor:'none'` backend like native is a reported no-op). With ``: spawn the step's agent — a `lost`/`exited` agent is respawned on the same agentId (the beads claim rebinds), a live one is a SpawnError | | `bro agents run […] [--prompt-file ] [--for ]` | Ad-hoc spawn — mints a phantom `adhoc-` step, sends the prompt through the same registry/worktree/quota path as `up`, and answers `status`/`log`/`down` under the minted id. `--for ` binds the spawn to the bead's claim instead (live agent or foreign claim refuses; no prompt → the bead's own text). Either way a live agent/session in this repo with a near-identical prompt earns a stderr warning — advisory, the spawn still lands | | `bro fleet agents down [] [--connector ]` | No arg: supervisor down. With a target: stop that one agent — a gone agent exits 0 on a healthy read (`stopped `); a miss beside a degraded backend reports unverified (exit 1), not 'gone'; a worker that survives the stop signal (TERM-resistant) or whose death the backend cannot confirm also exits 1 and never prints `stopped` (spec `specs/bro-l8c4f.3.md`) | | `bro fleet agents log [--follow] [--lines ]` | Tail the agent's recorded `.log` — the surface for "is it actually working?" `status` prints the path; `log` reads it. `--follow` is `tail -F`: janitor truncation and remove/respawn-reopen are reported, never silently skipped. stdout is log bytes only — the context header rides stderr | `--connector ` scopes these subcommands to one backend. Useful flags on `up`: `--worktree ` (overrides the recorded/conventional `--` lookup), `--prompt-file ` (overrides the stored prompt / bead text), `--beads-dir `. With no worktree to resolve, `up` mints the conventional sibling on branch `work/` inside the spawn transition — enter, claim, and spawn land as one step under the registry lock, so a refusal leaves no half-entered tree (the remote-only copilot backend skips this). ## Policy - **Fleet first, agents second.** `bro fleet` is the read-only view — `lost — respawn?` rows are the decision surface; `bro fleet agents up ` is the action behind it. - **Respawn preserves identity.** Same agentId, same worktree, same stored prompt — a respawned fixer keeps its custom instructions. The claim in the shared beads store moves to the respawning actor. - **Claims are the coordination plane.** A step claimed by a live agent refuses a second spawn; a claim held by another actor (or no agent at all) refuses a rebind — release the stale claim first, don't force it. - **Two caps, different axes.** `fleet.maxConcurrent` counts bro's own registry agents; `agents..maxSessions` caps host-wide sessions through a registered session plane — the plane counts live sessions of its kind (its own lock/detect files, deduped by pid), interactive sessions included, so a spawn can refuse while the fleet looks empty. `agents..maxWorkers` splits the count: only spawned workers fill it (a `BRO_AGENT_ID` environ badge or a non-terminal stdin), so interactive TTYs stop starving rigs. A spawn counts into a kind when a registered plane detects the resolved command's CLI or the backend sets `agents..sessionKind`; a declared kind with no registered plane refuses loudly. A host-local count misses sessions the kind's cloud side may hold — a plane reports only what the host can verify.