Handbook
Repo-task Element protocol
Dual-wiki for agentic_dev_worker: operator · system.
Updated
Executive capsule
Operator-visible chat for Roadrunner repo tasks: !agent task → !approve → Fleet agentic dev rail → confirm → code_review_worker → merge. One task is one Element thread rooted at the operator's command message. Everything an operator needs to test or decide is in that thread; nothing requires SSH, a laptop checkout of the agent's work, or the Fleet UI.
Who this is for
Operators starting repo tasks from Element, forgeadmins who approve them, and anyone implementing or testing the Roadrunner broker.
Problem
Chat is a poor place for secrets, long logs, and ambiguous approvals. This protocol fixes a small event vocabulary, exact approval and decision grammar, and a git-only test block so that a thread is sufficient to supervise a task without widening what the agent may do.
Room and identity
| Item | Value |
|---|---|
| Command room | the configured cursor room (MATRIX_CURSOR_ROOM), plaintext only |
| Approval room | MATRIX_APPROVAL_ROOM_ID; !approve lines are accepted only here (or in-thread approve when ROADRUNNER_THREAD_APPROVE=1) |
| Bot | @roadrunner (container forge-agents-roadrunner on a Fleet node) |
| Who may start tasks | MATRIX_ALLOWED_USERS |
| Who may approve | MATRIX_APPROVERS (forgeadmin); never the requester, never the bot |
Who may confirm / reject |
MATRIX_ALLOWED_USERS |
Command grammar
!agent task [model=<id>] [base=<ref>] [verify="<cmd>"]... <owner/repo> | <goal>
<owner/repo> is a GitHub repository in ROADRUNNER_REPO_ALLOWLIST (default autowww/*); filesystem paths are rejected. Up to ten verify commands run inside the agent container and again, independently, at review.
How it works — event table
| Event | When | Required fields | Posted by |
|---|---|---|---|
ACK |
command accepted and ledger row created | task id, repo, branch, base, model, verify, !approve <request_id> <digest> line, expiry |
bot |
START |
receipt recorded; Fleet accepted the task | approver, Fleet job id, node, status | bot |
LIVE |
credential attached / container running | node, clone target | bot (once per transition) |
PUSHED |
branch pushed | branch, head sha12, base sha12, changed files | bot |
VERIFY |
agent-side verify summary | each command and exit code | bot |
READY FOR TEST |
PR open, waiting for the operator | git-only test block, PR link, confirm / reject prompt |
bot |
REVIEW |
confirm received; review job queued |
Fleet job id, head sha12 | bot |
MERGED |
reviewer squash-merged | merge sha12, PR link | bot |
HELD |
guard or review stopped the task | hold_reason, offending paths / conflicts / critical check ids; !approve <task>:merge <digest> when forgeadmin may release |
bot |
FAILED |
clone, cursor, push, Fleet, or review failure; approval expiry | reason | bot |
REJECTED |
operator rejected, or command invalid | sender, reason | bot |
How to use — operator commands
| Reply | Where | Effect |
|---|---|---|
!approve <request_id> <digest> |
approval room | records the receipt that lets Fleet run exactly this envelope; the digest is printed in ACK |
approve |
in the task thread, approvers only, ROADRUNNER_THREAD_APPROVE=1 |
same receipt; digest comes from the ledger, not the message |
confirm |
in the task thread after READY FOR TEST |
starts the independent review and, on pass, the merge. Not an execution approval |
reject <reason> |
in the task thread | closes the task; nothing merges; branch is garbage-collected after 14 days |
!approve <task_id>:merge <digest> |
approval room, forgeadmin | releases a HELD critical review for merge of the same head SHA |
Formatting rules
- SHAs, branches, task ids, repo names in monospace; SHAs shortened to 12 characters.
- Exactly one fenced code block per
READY FOR TESTwith copy-pasteable, git-only test instructions. - No credentials, tokens, environment dumps, or raw log tails longer than a few lines. Long logs are summarized; the full
steps.logstays on the Fleet node. - Every event carries the
m.threadrelation to the command message.
READY FOR TEST template
READY FOR TEST · <repo> · <branch>
PR: <url>
git fetch origin <branch> && git checkout <branch> # head <sha12>
<verify command 1> # expected: exit 0 (agent run: exit 0)
Reply in this thread: confirm | reject <reason>
Example thread
lev !agent task verify="pytest -q" autowww/forge-calc-canary | Add subtract(a, b) to src/calc.py with a test
roadrunner ACK · autowww/forge-calc-canary · task req_task_3f9a01c2
branch agent/roadrunner/req_task_3f9a01c2-add-subtract-a-b-to-src-calc-py from main · model composer-2.5 · verify: pytest -q
Approve in the approval room with exactly:
!approve req_task_3f9a01c2 7d1c…e4a0
Expires 2026-10-27T14:12:00+00:00. Nothing runs until a receipt exists for this request and digest.
forgeadmin (approval room) !approve req_task_3f9a01c2 7d1c…e4a0
roadrunner START · approved by @forgeadmin · Fleet job 9b2… on local · status queued_waiting_credential
roadrunner LIVE · waiting for the localhost courier to attach the Cursor key
roadrunner LIVE · container running on local · clone autowww/forge-calc-canary@main → agent/roadrunner/req_task_3f9a01c2-…
roadrunner PUSHED · agent/roadrunner/req_task_3f9a01c2-… → 5a7e1c90b2d4 (base 1f0c…) · files: src/calc.py, tests/test_calc.py
roadrunner VERIFY · agent-side: pytest -q → exit 0 (independent re-verify happens at REVIEW)
roadrunner READY FOR TEST · autowww/forge-calc-canary · agent/roadrunner/req_task_3f9a01c2-…
PR: https://github.com/autowww/forge-calc-canary/pull/12
git fetch origin agent/roadrunner/req_task_3f9a01c2-… && git checkout agent/roadrunner/req_task_3f9a01c2-… # head 5a7e1c90b2d4
pytest -q # expected: exit 0 (agent run: exit 0)
Reply in this thread: confirm | reject <reason>
lev confirm
roadrunner REVIEW · independent review queued as Fleet job c41… · re-verifying 5a7e1c90b2d4 in a fresh container
roadrunner MERGED · squash-merged by reviewer · 9d02a7f31c6e · https://github.com/autowww/forge-calc-canary/pull/12
How it fits the ecosystem
Roadrunner (forge-agents) owns the thread and the ledger; Fleet owns execution and the review container; forge-workcells wraps the reviewer as code_review_worker; this page and the approval model are the platform contract the three repos implement. Lenses remains the system of record for ForgeRun approvals outside this lane.
Evidence
Grammar, renderers, receipt denials, and the full happy path and HELD paths are pinned by forge-agents/packages/cursor_bridge/tests/test_repo_task_broker.py (13 tests) and test_courier.py. The example thread below is synthetic; the first real thread will be recorded by the R12 canary in the program page evidence log.
Trust boundary
Humans: start tasks, paste the receipt, test, confirm / reject, release a critical hold. Bot: posts events, never approves, never merges, never widens paths. Reviewer: merges on pass only. Nothing in the thread can carry a credential or alter the approved envelope.
State → event mapping (system view)
| Ledger state | Entered on | Event |
|---|---|---|
PENDING |
!agent task |
ACK |
RECEIPTED |
receipt recorded | — (submit follows immediately) |
SUBMITTED |
Fleet 202 | START |
RUNNING |
Fleet running |
LIVE |
READY_FOR_TEST |
Fleet completed |
PUSHED, VERIFY, READY FOR TEST |
CONFIRMED → REVIEWING |
confirm + review 202 |
REVIEW |
MERGED |
review merged: true |
MERGED |
HELD |
guard / critical / merge blocked | HELD (+ merge approve line when critical) |
MERGE_APPROVED → REVIEWING |
forgeadmin merge receipt | REVIEW ("merge release") |
FAILED, REJECTED, EXPIRED |
terminal | FAILED / REJECTED |
Sources: forge-agents/packages/cursor_bridge/src/forge_cursor_bridge/broker/, matrix_adapter/formatting.py, Fleet fleet_server/agentic_dev_job.py, deploy/agentic-dev/run_review.py.