Found while writing docs/DESIGN.md against the code rather than against the older documents.
The mechanism
Two modules each define item_room(), and they return different strings:
src/agent_harness/coordination.py:59 def item_room(item_id) -> f"item:{item_id}"
src/agent_harness/executor.py:287 ITEM_ROOM_PREFIX = "work:"
src/agent_harness/executor.py:287 def item_room(item_id) -> "work:" + item_id
executor.py writes to work:T1. coordination.py — which owns rooms, and whose rooms() and verify() read them — computes item:T1. Anything asking the coordination plane for an item's room gets a name nothing has ever written to.
Why nothing is failing
Nothing in api.py, __main__.py, runtime.py or session_executor.py constructs a ledger, so Executor.ledger is None in-tree and the write path is never taken. The message ledger, rooms and the oversight actor are built and tested but unwired — which is itself worth knowing, since three documents describe them as "proposed, not implemented" and that is not what the code says.
So this is latent. It becomes live the moment anything wires a ledger up, and the symptom then is not an error: it is an empty room. A reader asks for an item's messages and gets nothing, which is indistinguishable from an item that produced none.
Why it is worth fixing before that
A silent empty result is the worst failure shape available here, and this repository has spent time removing exactly that class — Submitted after one turn with nothing changed, a hold nobody is told about, a fleet with a full queue claiming nothing. Each read as normal.
Two definitions of one name in two modules is also the shape that produced the CLI/executor agent-command divergence: the same idea spelled twice, drifting, with a test written afterwards to assert there is only one.
The fix
One definition, in coordination.py, since it owns rooms. executor.py imports it. Whichever spelling is chosen, nothing persisted uses the other today, so there is no migration — but confirm that before assuming it, because a ledger written outside this tree would disagree.
A test asserting there is exactly one item_room in the source is cheap and is the kind that has already paid for itself here.
Blind spots
- Whether any other pair of same-named helpers disagree across modules has not been checked. This was found by reading, not by a sweep.
- Whether an out-of-tree deployment has ever constructed a ledger and written
work:-prefixed rooms is unknown; if one has, choosing item: is a migration rather than a rename.
Found while writing
docs/DESIGN.mdagainst the code rather than against the older documents.The mechanism
Two modules each define
item_room(), and they return different strings:executor.pywrites towork:T1.coordination.py— which owns rooms, and whoserooms()andverify()read them — computesitem:T1. Anything asking the coordination plane for an item's room gets a name nothing has ever written to.Why nothing is failing
Nothing in
api.py,__main__.py,runtime.pyorsession_executor.pyconstructs a ledger, soExecutor.ledgerisNonein-tree and the write path is never taken. The message ledger, rooms and the oversight actor are built and tested but unwired — which is itself worth knowing, since three documents describe them as "proposed, not implemented" and that is not what the code says.So this is latent. It becomes live the moment anything wires a ledger up, and the symptom then is not an error: it is an empty room. A reader asks for an item's messages and gets nothing, which is indistinguishable from an item that produced none.
Why it is worth fixing before that
A silent empty result is the worst failure shape available here, and this repository has spent time removing exactly that class —
Submittedafter one turn with nothing changed, a hold nobody is told about, a fleet with a full queue claiming nothing. Each read as normal.Two definitions of one name in two modules is also the shape that produced the CLI/executor agent-command divergence: the same idea spelled twice, drifting, with a test written afterwards to assert there is only one.
The fix
One definition, in
coordination.py, since it owns rooms.executor.pyimports it. Whichever spelling is chosen, nothing persisted uses the other today, so there is no migration — but confirm that before assuming it, because a ledger written outside this tree would disagree.A test asserting there is exactly one
item_roomin the source is cheap and is the kind that has already paid for itself here.Blind spots
work:-prefixed rooms is unknown; if one has, choosingitem:is a migration rather than a rename.