Skip to content

Work handed over by label, across an organisation (0.3.0) - #5

Merged
cycle-five merged 12 commits into
masterfrom
label-claims
Nov 20, 2026
Merged

cycle-five merged 12 commits into
masterfrom
label-claims

Conversation

@cycle-five

Copy link
Copy Markdown
Member

What this is

A person hands work to an agent by putting a label on it: assigned:<tag> on an issue or pull request, review:<tag> on a pull request, where <tag> belongs to one mailbox. Until now mailroom polled a fixed list of repositories, tagged routed:assigned only when the bot was an assignee, and knew one optional review label per source. With this change the agent learns of the hand-over wherever in the organisation the item lives, hears what happens on it while the label stays, and is told when it is released.

Design: docs/superpowers/specs/2026-11-20-label-claims-design.md. The behaviour was settled with Nyx, whose own poller will switch over to match. Released as 0.3.0. It needs CycleFive/brokers 0.5.0 (the GitHub broker's Feed answers /search/issues), which is already deployed.

Design

A GitHub source gains an optional block, which adds one poll target to it:

"labels": { "org": "your-org", "tag": "claude" }

Each poll of that target (poll_claims, crates/logic/src/claims.rs):

  1. Searches the organisation once for open items carrying either label.
  2. Reads the events of each item that is new or has changed. A label counts only when its newest labeled event is not followed by an unlabeled one and the label is on the item, so a lagging search decides nothing.
  3. Checks who applied it. The labeler is trusted when GitHub reports triage, write, maintain or admin access for them on that repository. An app's bot never is.
  4. Writes one claim record per label event: routed:assigned or routed:review when trusted, untrusted-label when not.
  5. Follows a trusted claim: its comments, reviews, review comments and state events arrive tagged claimed, also in a repository the mailbox does not otherwise watch. In a watched repository the per-repo poll carries that activity, after the claiming poll has read once what was said since the label.
  6. Writes one closing note, tagged released, when the item is closed, loses the label, loses its trusted label, or is gone; only after reading the item itself confirms it. A reopened item that is still labelled is handed over again.

claimed, released and untrusted-label do not start routed:, so they inform without calling for attention. Labels add to assignee and requested-reviewer routing; they do not replace it.

Guards

  • Trust is per label and follows its newest labeled event. A bot's label can neither create a routed hand-over nor keep a claim followed once the trusted label is gone.
  • review_label may not be one of the two label names. The per-repo poll routes review_label without asking who applied it.
  • Nothing is decided on incomplete data. A failed lookup fails the poll and is retried; an item whose events cannot all be read is reported with a gap record and left alone; incomplete_results from the search releases nothing.
  • Bounded cost. One search page of 100, at most 20 items and 20 release checks per poll, and no new item is started once 60 requests have been made. An item that turned out not to be a claim is not read again until it changes.
  • Nothing is mailed twice. Activity uses the per-repo poll's record ids, so the inbox drops a repeat; claim and closing-note ids are unique per hand-over.
  • The Worker no longer indexes repos by target position; targets are resolved by key, and target keys are unique across an agent's sources.

Checked

  • cargo fmt, cargo clippy -D warnings, cargo test --workspace (186 tests; 67 on the claims poller, each safety rule with a mutation check), the wasm32 build, and the door's typecheck and tests.
  • A read-only run of poll_claims against real GitHub for an existing tag: an issue labelled by an admin produced a routed:assigned claim and one follow-up comment tagged claimed; a pull request labelled by an app's bot produced untrusted-label with no lookup and was not followed; the second poll made one request and mailed nothing.
  • Per-task reviews, a whole-feature review covering this and the broker change, a fix wave and a narrow second pass, each re-reviewed.

Not exercised before deploy: the request path through the broker's Feed with an installation token. After deploy, mailbox_info must show no last_error on github:<broker>:labels:<org>.

After merge

Add labels to each mailbox's GitHub source in the mailbox manifest, npm run mailbox -- deploy --mailroom from CycleFive/brokers, deploy the door, verify, tag v0.3.0, release.

🤖 Generated with Claude Code

https://claude.ai/code/session_017zqkE8grD6nh1bNnb2r1X8

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
… and double labels

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…gain

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…d repos (0.3.0)

The labels target is now polled with poll_claims, dispatched on its key before
any repos[index] lookup (which would have panicked out of bounds). Repo polls
read the stored ClaimsState and tag activity on claimed items `claimed`.

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…budgeted paged reads

Trust is decided per label by its newest labeled event (a later unlabeled one
cancels it), label names match in any case, a trusted claim that loses trust is
released and kept untrusted, since follows the trusted label, a cut events list
decides nothing, a newly trusted claim in a watched repo is read once, comments
are paged, a poll stops at 60 requests, a moved item is released as gone, and
claimed_numbers compares repositories in any case. FakeFeed::strict for the
claims tests.

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
… and duplicate targets

GithubSource::target replaces indexing into repos in the worker; an
undecodable stored claims state is logged.

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…ource

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…ead once, reopen not repeated

A label the search does not list is checked on the item; label_events keeps
only labels that count; items read and not stored are remembered in skipped
until they change; the cut-events gap id carries updated_at; a stored reopen
is not mailed as activity; a missing repository_url means the same repository.

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
@cycle-five
cycle-five merged commit 5093cbe into master Nov 20, 2026
2 checks passed
@cycle-five
cycle-five deleted the label-claims branch November 20, 2026 13:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant