Repository navigation
Agent work-claim coordination: agents announce and reserve the scope they are working on #15946
Description
Problem
Several AutoBot agents can work the same project at the same time. Nothing today tells
agent B that agent A is already editing a file, rewriting a KB collection, or driving a
device. a2a/task_manager.py tracks tasks, agents/agent_orchestration/coordinator.py
routes requests, and neither records which resource an agent is currently holding.
Two agents given overlapping work silently overwrite each other; the loser's work is lost
with no error anywhere.
Goal
A coordination channel with three properties:
- Announce — an agent declares the scope it is about to touch, with its identity,
its task, and a human-readable intent. - Reserve — an overlapping declaration is refused, and the refusal names the holder
so the second agent can wait, queue, ask for a handoff, or pick different work. - Expire — a crashed agent never blocks the project. Claims are TTL'd and renewed by
heartbeat; a dead holder's scope frees itself.
Design
Substrate. autobot_shared/coordination/shared_runtime_bag.py already gives Redis-backed
cross-worker state with CAS and pub/sub (#6630). The claim registry is a sibling in the same
package, not a new store and not a second bus.
Scope grammar. <kind>:<segment>/<segment>/... — kinds file, dir, kb, device,
project, config. Two scopes overlap when the kinds match and one path is a
segment-aligned prefix of the other, so dir:autobot-backend/llc conflicts with
file:autobot-backend/llc/budget.py.
Modes. EXCLUSIVE (write intent) and SHARED (read intent). SHARED×SHARED coexists;
everything else conflicts. Re-acquiring a scope you already hold, as the same
(agent_id, task_id), is an idempotent renew — an agent must never deadlock against itself.
Authority. Redis is the system of record for agent_work_claims, declared in
autobot_shared/store_authority.py. Claims are ephemeral by design: the durable record of
work is the a2a Task, and a claim is rebuilt by the agent re-acquiring on its next step.
Event layer. docs/developer/EVENT_STATE_DOCTRINE.md lists agent-to-agent coordination
semantics as an anti-goal of the event layer — so the semantics live in
autobot_shared/coordination/, and only the user-visible projection ("agent X holds
scope Y") is published, on the existing bus, over the existing agent:{id} and global
channels. No new WebSocket route, and a REST snapshot so a reconnecting client recovers
state it missed.
Anti-goals
- Not a distributed transaction manager, and not a substitute for DB constraints.
- Not a new event bus, and not a new WebSocket endpoint.
- Not a lock that can outlive its holder — every claim has a TTL.
Tasks
Wave 1
- Task 1:
work_claimsregistry primitive + store-authority concept + doctrine doc — work_claims: Redis-backed claim registry for agent work scopes #15947 (PR feat(coordination): work_claims — agents announce and reserve the scope they hold (#15947) #15958, merged50956309a, closed on verified evidence)
Wave 2 (both depend on #15947)
- Task 2: Conflict payload, waitlist, and yield/handoff negotiation over a2a — Work-claim conflict protocol: waitlist, yield request over a2a, and arbitration #15948 (PR feat(coordination): queue behind a held scope, ask the holder to yield, arbitrate (#15948) #15992, merged 2026-09-08, closed on verified evidence)
- Task 3: Event projection +
GET /api/coordination/claimsstate snapshot — Project work claims onto the event bus and expose GET /api/coordination/claims #15949 (PR feat(coordination): project work claims onto the bus and expose the claim table (#15949) #16085, merged7fbc7fbd21, closed on per-criterion evidence read from merged base)
Wave 3 (depends on #15947, #15948)
- Task 4: Enforcement — task executor and base agent acquire declared scopes — Enforce work claims: task executor and base agent acquire declared scopes #15950 (PR feat(agents): agents hold the scopes they declare, and a guard makes them declare (#15950) #16175, merged
5f4477250; extraction refactor(agents): extract the exchanged data types so base_agent clears its ceiling (#15950) #16106. Closed on per-criterion evidence, with two criteria deliberately unticked → NPUCodeSearchAgent cannot declare its write scopes: its file is at the size ceiling #16173, Cancelling an A2A task does not stop its executor, so claims can only lapse rather than release #16174)
Wave 4 (depends on #15949)
- Task 5: Frontend "who is working where" panel + i18n (11 locales) — Agent presence panel: who is working where #15951
Activity
mrveiss commentedon Sep 7, 2026
Grammar correction from implementing wave 1 — the umbrella's Design section says kinds
file,dir,kb,device,project,configwith overlap requiring the same kind, and then gives a cross-kind example (dir:…/llcconflicting withfile:…/llc/budget.py). Those contradict. Resolved in #15958 by droppingdir: kinds arepath,kb,device,project,config, and a claim covers its subtree, so the worked example holds within one kind. Rationale and the preserved false-positive case are on #15947; #15948-#15951 should readpath:wherever they sayfile:ordir:.fix(coordination): register the claim TTL, pin the two overlap rules …
fix(coordination): one claim key per holder, so SHARED actually coexi…
fix(coordination): define _require_holder, which my own edit had dele…
8 remaining items
mrveiss commentedon Sep 8, 2026
Live motivation from tonight: three collisions in one session, all from one root cause
Recording these as observed events rather than as argument, because the umbrella has been reasoned about more than it has been evidenced.
The shared
mrveissidentity made one session misread ownership twice in twenty minutes, in opposite directions.Duplicate diagnosis and duplicate fix. Two sessions independently diagnosed the same red on PR fix(redis): name the Stack unit everywhere it is operated (#16071) #16072 —
check_git_toplevel_env_scrubbed_test.pyfailing on a baregit ls-files— and both wrote the same fix, minutes apart. Neither had any signal the other was working it. One discovered the collision only by tripping over the other's pushed commit.A guard claimed by the wrong session. In the same exchange, that session described
repo_tests/redis_unit_is_the_stack_unit_16071_test.pyas "my new redis naming: five more sites name a unit the fleet does not have (#16060 follow-up) #16071 guard". It was not theirs — it was written hours earlier by a different session under redis naming: five more sites name a unit the fleet does not have (#16060 follow-up) #16071. They had readauthor=mrveisson the branch and concluded it was their own work.An issue claimed by the wrong session. Within the same window, the same two sessions both reported PR fix(hooks): a non-deny permissionDecision must exit 0 to be read (#15956) #15996 as their remaining red, with identical failure lists. It had been held all session by one of them, who wrote the guard, fixed both halves of the
deny()/stderr gap and carried the local commits. Resolving it required a coordinator ruling on history, because nothing in the repository distinguished them:author=mrveiss, and the branch had no worktree.Why the second one is the serious one
The duplicated effort in (1) is recoverable — two correct fixes, one wasted hour, no damage. The other two are not the same kind of event. Being confidently wrong about who owns a file is the precondition for editing it, and the only reason (2) cost nothing is that the misattribution was to a file the session had merely diagnosed rather than one it went on to change.
All three share a single mechanism: the branch name is the only ownership signal, and it is not attached to anything.
author=mrveissis shared by every session; a worktree is transient and was absent in case (3); and a branch with no live tree carries no owner at all.That is the state #15987's branch-keyed lock is designed to make legible, and these are three concrete instances of it failing within one session rather than a hypothetical.
One adjacent finding worth carrying into the design
A session with a finished worktree held it through several exchanges without noticing, while two peers were cap-blocked. The obvious check argued against releasing it:
git merge-base --is-ancestor <branch> origin/Dev_new_guireports NO for a squash-merged branch by construction, so a landed branch reads as unfinished.Any reaping or expiry logic built on this umbrella must therefore key on the merge commit's ancestry plus file presence on base, never on branch ancestry — otherwise the mechanism intended to free scarce slots will systematically conclude that finished work is still in progress.
feat(coordination): unlanded changes keep a scope spoken for, and ste…
mrveiss commentedon Sep 13, 2026
Owner direction, 2026-09-13: session and agent coordination on by default. Mapped against
origin/main. The primitives mostly exist; what's missing is wiring and a few extensions. New children, each extending existing machinery:#15950 Enforce work claims: task executor and base agent acquire declared sco
#15951 Agent presence panel: who is working where
#16269 Declared work scopes are held only on the agent_client path: workflow_
#16646 feat(coordination): claim events never fire — hold_scopes calls try_ac
#16647 feat(coordination): the conflict protocol is built but unused — wire w
#16648 feat(coordination): scoped holds/freezes with a reason and an expiry —
#16649 feat(coordination): one queryable view of who is doing what, in which
#16650 feat(events): subscribe to events on the scopes I hold — channels are
#16651 bug(llc): work-item checkout never expires — a crashed run keeps an it
#16652 feat(coordination): one writer per external source — a poller lease vi
#16653 test(coordination): no guard stops a third claim registry — pin 'one c
Closed with every AC unticked: #15948, #15949 and #15987 each shipped their primitive with tests, but none has a production caller today. Their ACs are library-level, so the wiring is tracked in the new children, not by reopening them. A closure audit should still verify and tick their ACs with evidence.
Reference design: our own multi-session development tooling now runs this exact pattern: claims with TTL, verdicts tied to a head, scoped holds, a filtered event stream, and a single poller per source.