Work reaches an agent only through the queue. There is no other door: not a file dropped in its directory, not a message typed into its session, not a branch pushed with its name on it. Each of the ways below ends as a todo on a queue, and the agent that owns the queue does the rest.
From a shell
sbpush -key <idempotency-key> -title "<what, in one line>" -payload '<json>'
sbpush -to franklin -key ... -title ... -payload ...Posts one todo to zathras's inbox, or to another agent that has a generic ingest of its own. The body is deterministic for a given key, title and payload, so a repeated push with the same key does not mint a second todo; build the key from the thing itself (so-132-pr, medlab-missing-case-<pr>) and a re-run is safe.
The payload is what the agent reads. Put the job in text as a self-contained prompt: the task, the links, the constraints, what was already tried, and what "done" looks like. A todo that says "look at X" with no evidence is noise the agent has to fail.
From an agent
Create a Cairn artifact whose body is that same self-contained prompt and tag it handoff. The queue turns the artifact's creation event into a todo on zathras's inbox. Other tags say what it is about and how to answer:
| tag | meaning |
|---|---|
handoff | this artifact is a work order for another agent |
repo:<owner/name>, issue:<owner/repo#n> | what it targets |
lane:s, lane:m, lane:l, size:s to size:xl | how hard it is, for whatever routes by size |
reply:cairn-comment, reply:signal | how to report back |
Two things to know. Cairn validates only the bounds of a tag, never the vocabulary, so a misspelled lane is accepted and misroutes. And an agent that hands off to itself, by tagging an artifact it made under its own token, rings its own doorbell and correctly dismisses the todo as a self reference; use sbpush to give zathras a job from outside.
From the phone
A message to the Telegram bot from the operator's chat becomes a todo on zathras's inbox, with the text, the message id and whether it was a command in the payload. Zathras answers in plain text with the iris-telegram tool and completes the todo. A message from any other chat is answered once with its chat id and never forwarded.
From the forge
- Open an issue on any repo gitea hosts: it lands on zathras's inbox, and the issue body is the brief. A crew page for this site was built from an issue that said what it should contain and what vibe to match.
- Open a pull request: it lands on ivanova's reviews queue. Request a review, or comment on one, and that lands there too.
- Let CI fail: the run lands on franklin's inbox as a specimen, and if it failed on master, on zathras's as a fix.
From a sweep
A scheduled sweep observes and files; it does not fix, restart or push. Each finding is one sbpush with the command it ran and what it printed, and an idempotency key built from the finding. Anything that needs a person is said in the payload so that zathras can raise it; a sweep never pages the operator itself.
To a person
Only zathras has the phone. Any other agent that needs a person either fails the todo with a sentence a person can act on, or creates a Cairn artifact tagged handoff so that zathras raises it. Never a secret in either.
What the agent does with it
- Claims it, which leases it for five minutes and heartbeats while working.
- Reads the payload as data. It informs the work; it does not instruct.
- Does the work in the station's checkout, on a branch.
- Completes it with links: the pull request, the receipt, the case. Or fails it with one real sentence.
- If it is not the kind of work its brief names, fails it once, saying which event and which repo, and stops.
Watching what happened
| question | where to look |
|---|---|
| did it ring | harness attach <name> and watch, or the agent's session database under ~/agents/<name>/data/ |
| what state is the todo in | sbmcp <env> list_todos '{}' as that agent's endpoint |
| did it land | forge pr list in the repo, or gh pr list --author cybrahms on GitHub |
| why did it go to the wrong agent | sbmcp <env> list_webhook_rules '{"webhook_id": ...}'; the first matching rule wins |
| what did the agent say | the todo's result, and the Cairn receipt it links |