claude-code: a session asks the operator on Telegram and reads the answer by a key (issue 589, hq ADR 0332) #258
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: novox/mesh-catalog#258
Reference in New Issue
Block a user
Fixes issue 589 (an agent session cannot ask the operator a question on Telegram and get the chosen answer back). Implements hq ADR 0332 (accepted: the knowledge base approved it and the operator approved it on 2026-10-12).
What. Two tools of the claude-code module:
claude_code_ask: headline (at most 60 characters), context in plain words, 2 to 4 options (label, what it means, exactly onerecommended),why,on_expiry,by(who@node),expires_minutes(5 to 1430, 60 when absent). Kept in the newquestionsstate (keyq-<hex>) and published as an ask under this module's name onoperator-channel. Every option is at the level approve and binds the digest of the question and of itself, so only a channel that proves who answered (Telegram) carries it. Waits a few seconds for the router's word, then answers with the key or the router's refusal (the content rule).claude_code_answer: by key, says waiting / chosen (option, who, channel, when) / ended (expired, refused, cancelled, replaced) / not proven. Read from the router's own record and held to the kept question (asks.Warrant.For+Option.Performs).wait_secondswaits up to 60 s within one call.At most two questions open at once (mesh-wide, counted in the
questionsbucket against the router's record), so one of the router's three open asks per asker is always left for a proposed instruction section (ADR 0274). The router's refusal on the decided subject is kept on the question, since a refused ask leaves no router record. The answer authorises nothing.Second commit: a flake fixed in proposals.go.
TestTheRoutersRefusalIsSaidAndDiscardsfailed on the build agent at the first head (decided ""):HeardEndtold the waitingProposeabout the refusal before it wrote the discard, so a read right after found nothing. It now tells only after the write. The question path keeps the same order.Why here, not a verb on
operator-channel. A seat verb reached through a tool runner cannot tell which module or session called it; under this module's name the bus proves the asker, and the router stays the judge (ADR 0332 Considered Options).Files. New
questions.go,questions_test.go;proposal_tools.goregisters the tools and routes the router's word on aq-ask to the questions;proposals.go(the order fix);module.jsonadds thequestionsstate and the two tools; README.main.gois untouched (open #152 touches it; #178 touches proposals.go and README).Tested.
go test -racein modules/claude-code.MESH_CHECK_MODULES=claude-code MESH_GATE=<controller from mesh-controller main> sh merge-check.shpasses. Both required checks are green ate4e0ce7.Design limits I chose (in the ADR): at most two questions open; expiry 5 to 1430 minutes, 60 by default; context at most 1500 bytes; one read waits at most 60 s.
Design home: novox/hq#334.
Delivery
novox/mesh-catalog@c4eebce598cb— delivered since 2026-10-12T21:33:38ZDelivery plan — builds claude-code → ace, g14, novox, shanks; no bus step
Machines
Transitions
The commit's note under
refs/notes/mesh-plankeeps every transition:git log --notes=mesh-plan.Merge check at
9446bec2Judged: head
9446bec2f969merged into trunk9c9a76d220f8; read beside it: mesh-controller2f157148c6c8, mesh-controller-main2f157148c6c8, mesh-hostd8e785bb4b4b, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: claude-code)mesh/repo-check: FAIL — its merge-check.sh failed: --- FAIL: TestTheRoutersRefusalIsSaidAndDiscards (0.08s)Delivery plan — builds claude-code → ace, g14, novox, shanks; no bus step
Run by the build seat on shanks as
build-1791837914312821856(builds --log build-1791837914312821856).Merge check at
e4e0ce76Judged: head
e4e0ce761901merged into trunk9c9a76d220f8; read beside it: mesh-controller2f157148c6c8, mesh-controller-main2f157148c6c8, mesh-hostd8e785bb4b4b, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: claude-code)mesh/repo-check: PASS — its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)Delivery plan — builds claude-code → ace, g14, novox, shanks; no bus step
Run by the build seat on shanks as
build-1791838311699019646(builds --log build-1791838311699019646).Verdict: request changes at
e4e0ce7619Independent review against ADR 0332 (accepted, version 8), issue 589.
WHAT I RAN (clone at this head, GOTMPDIR=/var/tmp)
CLAUSE BY CLAUSE
1 holds: published on asks.AskSubject(Module), no seat verb added. 2 holds: headline <= 60 runes, 2-4 options, exactly one recommended with why, on-expiry, 5 min to ProposalLasts (24 h - 10 min), 60 min default, who@node with the node checked against the runner's own. 3 holds as written (the router judges; a refusal is said in words). 4 holds: every option Approve, Binds = ActDigest of the whole question and the option. 5 holds: key after at most RouterAnswersWithin (8 s); waiting / chosen (id, label, who, channel, when) / ended / not proven; one call clamped to 60 s. 6 holds: warrant checked with asks.Warrant.For (same asker, same ask id, same ask digest, offered option, same level, warrant time not after expiry) and Option.Performs; tests cover a question rewritten after asking, another ask's digest, and a choice after expiry. 7, 9, 10 hold.
WHAT TO CHANGE
SMALLER (fix now or open a follow-up issue)
3. The two-question cap is check-then-create, so it is not atomic across nodes: two sessions on two nodes asking at the same moment can both pass and open three questions, which takes the ask clause 8 keeps for a proposal. openQuestions also returns nil when store.Keys fails, so the cap fails open. Fail closed on a Keys error at least.
4. A question whose refusal was missed on the decided subject (the node was off) has no router record and counts as open until it expires, which can be up to 24 h minus 10 min; it holds a slot for that long.
5. Wording that the ADR's review removed has come back. The README says "a session reads a question at most once a minute" as a fact; ADR 0332 section 5 says nothing enforces that. The MostQuestions comment says "so a proposal always finds room"; the ADR says one ask is left for a proposal while two questions are open. The tool description says "Answers at once", where the code waits up to 8 s for the router.
6. by is optional in the schema and becomes "unnamed". ADR section 2 says a question carries the session's name. Mark by as required, or say in the description that a missing name is shown as unnamed.
7. Tests that are still missing: a warrant naming another asker or ask id, a warrant for an option that was not offered, and the exact edges (a 60 vs 61 character headline, expires_minutes 1430 vs 1431).
Nothing here is a reason to doubt the warrant checking; items 1 and 2 are what I would want before merging.
Merge check at
14999f1dJudged: head
14999f1d3ecbmerged into trunk9c9a76d220f8; read beside it: mesh-controller2f157148c6c8, mesh-controller-main2f157148c6c8, mesh-host8e95c1d9ed2d, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: claude-code)mesh/repo-check: PASS — its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)Delivery plan — builds claude-code → ace, g14, novox, shanks; no bus step
Run by the build seat on shanks as
build-1791839725811336259(builds --log build-1791839725811336259).Verdict: request changes at
14999f1d3eRe-review against my review 105.
WHAT I RAN
RESOLVED FROM REVIEW 105
5 and 6. The wording is fixed, and by is required.
SLOT LEAKS: none found. A slot is reclaimed whenever its question is missing or unreadable, was not asked, has ended, has expired, is closed in the router's record, or (see below) has no router record after two minutes. So no slot outlives its question's expiry (at most 24 h minus 10 min). An unparseable slot value is reclaimed by compare-and-set. The one way questions stop is a persistent read error on the bus. It refuses every question, as intended, and recovers when reads work again.
WHAT TO CHANGE
(a) ReadAnswer says "ended ... nothing waits for the operator's answer". The session then does its on-expiry action. Later the router takes the ask, the operator is shown it on Telegram, and may answer a question the session has already given up on.
(b) takeSlot frees the slot, so a third question can be asked. Once the router catches up it holds three questions of this module, and a proposal is refused. That breaks clause 8 (one ask always left for a proposal).
Suggested fix: before releasing an unrecorded question, publish a cancel for it on asks.CancelSubject(Module). The router drops a cancel for an ask it does not know, but a cancel queued behind the ask closes it as cancelled when the router catches up. Then tombstone the question as "cancelled: the router had not recorded it two minutes after it was asked", so ReadAnswer's "ended" is true. Confirm that an ask and its cancel come off the same queue in order; if they do not, keep the slot and say "waiting: not yet recorded by the router" until the question expires. Add a test: a question with no record after two minutes is cancelled on the bus before its slot is taken.
Not blocking: in TestTheCapHoldsAcrossNodesAskingAtOnce, see the deterministic compare-and-set test suggested above.
Merge check at
c4eebce5Judged: head
c4eebce598cbmerged into trunk9c9a76d220f8; read beside it: mesh-controller961f2e82ea1c, mesh-controller-main961f2e82ea1c, mesh-host8e95c1d9ed2d, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: claude-code)mesh/repo-check: PASS — its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)Delivery plan — builds claude-code → ace, g14, novox, shanks; no bus step
Run by the build seat on g14 as
build-1791840311319059620(builds --log build-1791840311319059620).Verdict: approve at
c4eebce598Re-review against my review 107.
I checked both claims in the code.
The tests fail when the code is broken. Putting back a 2-minute release fails TestAQuestionTheRouterHasNotRecordedHoldsItsSlotUntilItExpires. Replacing the compare-and-set with a plain write fails TestASlotIsTakenOnlyAtTheRevisionRead, whether only the Update or both Create and Update are replaced. That cross-node test is now deterministic.
go vet clean; go test -race ok; gofmt clean. merge-check.sh with MESH_CHECK_MODULES=claude-code and MESH_GATE built from mesh-controller main (2f15714): exit 0, the count of resources without health stays at 67. Statuses on this head: mesh/merge-gate success (claude-code to ace, g14, novox, shanks), mesh/repo-check success, mesh/delivery success.
Not blocking: if the clock on the node that asked runs ahead of the router's, a slot is freed a few seconds before the router would refuse the ask. In that window a third question could be asked, and that is all the gap allows. Also, the
entry == nilin the following case of ReadAnswer's switch can no longer be reached and could be dropped.