Put the coordination bus in the index agents read before probing blindly - #746
Merged
Merged
Conversation
GET /api/v1/routes advertises itself as what an agent calls to discover the main endpoints before guessing. Every one of the 15 Epic 39/40 coordination-bus routes was absent from it - channel posts, handoffs, claims and advisory file locks, the whole surface. That omission is legal by the module's own contract (a curated index, not the API surface, which is the OpenAPI spec) and it is still the wrong call here, for the same reason the admin routes earn coverage. This is the mechanism a session is TOLD to reach for when it hands work to another machine. An agent that cannot find it does not degrade politely to the OpenAPI spec - it does the work twice, or drops it. That is precisely the failure the bus exists to prevent, so hiding the bus from discovery undoes the feature rather than inconveniencing it. Found while verifying #744 against production: the deployed router serves GET /api/v1/channel/claims and the curated index listed no channel route at all, so the read I had just shipped to make claim state discoverable was itself undiscoverable. A coverage test now pins the set the way the /admin one does, matching on (method, path) rather than path alone so a route that gains a verb is caught too. It earned its keep on the first run: it found two more I had missed by hand, the operator quarantine pair (GET /channel/posts/quarantined, POST /channel/posts/:id/release). Like the /admin test it asserts its own filter matched something, so a future change to route shapes cannot quietly turn it into a test of nothing. Descriptions carry the hazards an agent needs at the point of choosing, not just the route: that channel post bodies are untrusted data authored by peers, that a soft lock is advisory and blocks nobody, that a release is scoped to your AGENT and not your session, and that the claim 409 must be branched on by error.code.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The gap
GET /api/v1/routessays of itself that agents call it "to discover the main endpointsbefore probing blindly". Every one of the 15 Epic 39/40 coordination-bus routes was
missing from it — channel posts, handoffs, claims, advisory file locks, the whole
surface.
Strictly, omission is legal: the module's own docstring says this is a curated index and
the authoritative surface is the OpenAPI spec, and the coverage test only enforces
/api/v1/admin. It is still the wrong call here, for the same reason/adminearnscoverage. The bus is the mechanism a session is told to reach for when handing work to
another machine. An agent that can't find it doesn't degrade politely to reading OpenAPI —
it does the work twice or drops it, which is the exact failure the bus exists to prevent.
Found while verifying #744 against production. The deployed router serves
GET /api/v1/channel/claims; the curated index listed no channel route at all. The read Ihad just shipped to make claim state discoverable was itself undiscoverable.
The fix
All 15 routes added, with the hazards an agent needs at the point of choosing rather
than just the path: channel post bodies are untrusted data authored by peers; a soft lock
is advisory and blocks nobody; a release is scoped to your AGENT, not your session; the
claim 409 must be branched on by
error.code.A coverage test pins the set the way the
/adminone does, matching on(method, path)rather than path alone so a route that gains a verb is caught too. Like
/adminitasserts its own filter matched something, so a future change to route shapes can't quietly
turn it into a test of nothing.
It earned its keep on the first run: it found two more I'd missed by hand — the
operator quarantine pair,
GET /channel/posts/quarantinedandPOST /channel/posts/:id/release.Verification
Full gate green through the pre-commit hook: 7827 tests, 0 failures (86 excluded),
credo
--strictclean, dialyzer clean. The existing phantom test independently confirmsevery added path is one the router actually serves.
Review
Reviewed inline against correctness and this repo's conventions. A data-list addition whose
every entry is mechanically verified against the router in both directions (no phantom
entries, no missing members) — a multi-agent panel would not have earned its tokens here,
and the new test is the durable guard.