Nothing on this station is started by a person sitting at a keyboard. Work is an event that arrives, a rule that turns it into a todo on a named queue, an agent that owns that queue, and a result that closes the todo with a link to what landed. That loop is the whole system; every other page in this manual is a part of it.
1. Something happens
Four kinds of thing can start the loop.
- The forge. The private gitea sends a webhook for every event on every repo it hosts: an issue opened, a pull request opened or reviewed, a CI run finished.
- Cairn. Every artifact created on the station's Cairn sends an event. Almost all are dropped; the one that matters is an artifact tagged handoff, which is how one agent gives another a job.
- The phone. A small poller, tg-bridge, long-polls one Telegram bot and turns every message from the operator's chat into a delivery. This is the only way a person reaches an agent directly.
- A shell.
sbpushposts one delivery from the command line. Sweeps use it to file what they found; an attended session uses it to hand an agent a job it should do itself.
2. Switchboard turns it into a todo
Switchboard is the queue. It runs on this box (loopback port 8090, Postgres behind it, reachable on the tailnet as switchboard.sublayer.space) and it is the record: a todo exists there or it does not exist at all. The doorbell an agent hears is a hint; the queue is the truth, and an agent that assumes an empty queue from a quiet doorbell has skipped a step.
Each agent is a Switchboard endpoint with a vended bearer token, an MCP URL of its own, and a grant over one or more queues. Each webhook is owned by one endpoint and delivers to a target queue, optionally fanning out to other endpoints, and carries an ordered list of routing rules: the first rule whose expression matches decides where the delivery goes, or drops it. A delivery no rule matches lands on the webhook's own target queue.
The rules as they stand, in evaluation order. The gitea webhook is zathras's and fans out to ivanova and franklin.
| event | goes to |
|---|---|
| CI run failed on master | zathras (fix it) and franklin (a specimen) |
| CI run failed anywhere else | franklin (a specimen) |
| any other workflow event | dropped |
| push, create, delete, fork, release, and the rest of the plumbing | dropped |
| label, assign, milestone and edit churn | dropped |
| pull request opened, reopened, or review requested | ivanova, on reviews |
| a review verdict or review comment | ivanova, on reviews |
| everything else the forge sends, which is mostly issues | zathras, on inbox |
| a Cairn artifact tagged handoff | zathras, on inbox |
| any other Cairn event | dropped |
| anything from the phone or from sbpush | zathras, on inbox |
Franklin also has a generic ingest of his own, which sbpush -to franklin uses; the medlab sweep files its findings there.
3. The agent works it
A todo rings the endpoint's channel. The agent then:
- claims it, which takes a five-minute lease that it extends with a heartbeat while it works, so no other worker duplicates it;
- does the work, in a checkout under
~/agents/repos/<name>on a branch, never in a throwaway clone; - completes it with a result that says what landed and where, or fails it with a real sentence. A failed todo is retried while attempts remain and dead-lettered when they run out.
A todo left unclaimed is not finished. It stays pending forever and nobody else picks it up.
4. What "done" is
- A change is done when it is a pull request and the todo's result carries its link. On gitea,
forge pr create; when the issue lives on GitHub, a pull request there as the cybrahms user. - A report, a log or a finding is done when it is a Cairn artifact and the todo's result carries its link. Cairn is the station's pastebin (loopback port 8091, bodies in MinIO); links expire, so the result is the durable pointer.
- A diff in a Cairn artifact is not a finished todo. A patch nobody can merge is a job that was not finished; see the rules page.
- A todo that needed nothing is still completed, with a result saying why.
5. Review, merge, deploy
A pull request opened on gitea rings ivanova on the reviews queue. She reads the diff, trusts the CI run rather than re-running it, and posts a verdict. Approval is the bar, and the bar merges: if she approves and CI is green, she merges it herself. Nobody is waiting behind her to click the button.
Merging to master is what deploys anything. gitea's own runner runs the repo's suite on master and, only if it is green, the repo's deploy target. Nothing else restarts a live service, and no agent deploys by hand.
6. When it breaks
A CI run that fails rings franklin with the run as a specimen. His job is not the fix; it is the class of failure. He reads the run, finds the first real error, builds the control that would have caught it earlier, and writes it up as a case in medlab. A failure on master also rings zathras, whose job is the fix.
Once a week a scheduled sweep looks for fixes that shipped with no case behind them and hands each one to franklin as a todo. Once a week another sweep checks the services, the agents, the queue, the certificates and the backups, and files what it finds with zathras.
7. The phone
A message to the Telegram bot becomes a todo on zathras's inbox with the text in its payload. Zathras answers with the iris-telegram tool, plain text, short, and completes the todo. He sends on his own initiative only for a question he cannot proceed without or a result the operator asked to hear about. No other agent has a line to the phone: a question only a person can answer goes in a failed todo's result, or in a Cairn artifact tagged handoff so that zathras can raise it.