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 TEST with 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.log stays on the Fleet node.
  • Every event carries the m.thread relation 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.