The shape of a run
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
A swarm run is a set of agent roles working one mission: a coordinator that holds the plan and routes work, builders that change code, scouts that investigate, and reviewers that check. Each role that changes code gets its own git worktree for the run, so roles cannot overwrite one another mid-edit.
Those run worktrees are distinct from the interactive seats a workspace pane owns. Same isolation, different lifetime: a seat belongs to a pane you opened, a run worktree belongs to a run and a role within it.
The auditor gate — exactly what it does
When a builder, scout or reviewer reports that it is done, the run resolves that role's worktree, lists the files it changed, and scans them before the work reaches a human. The scan looks for three classes of problem: committed secrets, unsafe code patterns, and content-security-policy problems. Findings are graded high, medium or low.
A clean result is displayed, briefly and explicitly, rather than being represented by silence — so you can tell the difference between a gate that ran and found nothing and a gate that did not run. A scan that throws is reported as an error in the same prominent styling as a finding; it never falls through to a pass.
And exactly what it does not do
It does not block. The gate is advisory by design: it fires after routing has already been decided and never interrupts the handoff. A high-severity finding is pushed onto the run's error banner as well as the gate strip so it cannot be missed with the panel closed — but the decision is the operator's or the coordinator's.
The reason is structural rather than a matter of policy: a true refusal needs a merge step to hook, and the swarm has no in-app merge action to hook. The count of high-severity findings is computed and shown, so that when there is one, turning it into a real block is a small change. Until then, read the banner.
If you want something that can actually refuse a change, use the repository's pre-commit hook. In this repository it runs a dependency-lockfile sync check and a whole-project type check, and a failure means the commit does not happen.
Scans are throttled and scoped
- Only roles that produce changes are scanned — a coordinator has no worktree of its own to vet.
- Repeat scans for the same role inside a short window are skipped, so a chatty agent cannot turn the gate into a scan storm.
- A workspace with no changed files is a quiet no-op, not an error: there is nothing to vet, and reporting that as a failure would train you to ignore the gate.
- Deleted files are dropped from the scan list. There is nothing on disk to read.
Working alongside other agents
A workspace publishes which pane is working on what, so an agent about to start a task can see that another pane already owns it and stop instead of duplicating the work. Treat that board as context rather than instruction, and read it before starting, not after.
The practical rule that follows: overlap is resolved by naming the pane that already owns the task and stopping. Two agents solving the same problem in two worktrees is not redundancy, it is a merge conflict you scheduled in advance.