Repository navigation
Intents: record whether the announcement actually posted - #121
Conversation
An intent recorded that it was created and that it was decided, and nothing
about whether the card that asks the human ever reached anywhere. Measured on
a live daemon on 2026-09-20: four intents pending for up to 9.2 hours with
channels: ['groupmind'], with no way to tell from the record whether the owner
saw a card and ignored it or whether the card never posted. Those need
opposite reactions.
Each intent now carries an `announcements` map keyed by channel
({channel, status, attemptedAt, postedAt, messageId, error}) plus an
`announceState` summary, exposed through listIntents, getIntent, GET /intents
(with a new ?announce=<state> filter), the MCP list_intents tool and the
built-in HTML queue.
Failures surface rather than retry: the causes seen here (401 rotated key, 402
unpaid invoice, NXDOMAIN host) are not transient, so a retry loop would burn
the same hours and still end silent. The intent stays decidable, the failure is
written onto it, a receipt is appended and a line goes to stderr.
`postedAt` / `messageId` mean the channel ACCEPTED the message. There is
deliberately no deliveredAt and no seenAt: nothing here can observe either.
The announcers also stopped draining a response and resolving regardless of the
status code, so a non-2xx is now a failed announcement instead of a silent
success.
Backward compatibility: an intent with no `announcements` map reads 'unknown',
never 'posted' and never 'failed'.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3b7046ef7b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| { | ||
| name: 'list_intents', | ||
| description: 'List every confirmation intent the server knows about (pending, decided, recent).', | ||
| description: 'List every confirmation intent the server knows about (pending, decided, recent). Each row carries `announceState` plus a per-channel `announcements` map saying whether the asking card was actually POSTED (accepted by the channel), never posted, or failed - so a pending intent nobody was asked about is distinguishable from one waiting on a human. `posted` means the channel accepted the message; it is not evidence anyone saw it. `unknown` means the intent predates this record.', |
There was a problem hiding this comment.
Preserve explicitly requested unavailable channels
When the MCP server uses the in-process fallback, request_confirmation filters args.channels through announcerMap at lines 987-989 before calling createIntent. If only GroupMind is configured and a caller explicitly requests channels: ["codewatch"], the stored channel list and announcement map are both empty, so the newly advertised state is none rather than skipped; the intent then times out without revealing that its requested channel was unavailable. Pass the requested channels through so composeAnnouncers can record the missing channel.
Useful? React with 👍 / 👎.
| const annClass = ann === 'posted' ? 'posted' : (ann === 'failed' || ann === 'partial' ? 'bad' : 'iffy'); | ||
| // "posted", never "delivered" or "seen": the daemon knows the room | ||
| // accepted the message and nothing more than that. | ||
| const annText = ann === 'posted' ? 'card posted' : 'card not posted: ' + ann; |
There was a problem hiding this comment.
Avoid declaring unknown announcements unposted
For a replayed pre-upgrade intent, announceState is deliberately unknown because the card may or may not have posted, but this expression renders card not posted: unknown, making a definitive and potentially false claim. It is likewise inaccurate for partial, where at least one channel did post. Render these states separately so operators are not prompted to resend an announcement that may already exist.
Useful? React with 👍 / 👎.
codexmb's review of #121 found two paths with the same shape as the bug the PR fixes: inferring a DEFINITE answer from an ABSENCE. 1. composeAnnouncers inferred success from silence. An announcer that resolved without reporting anything - an early return, an unanticipated misconfiguration, an announcer written before results were reported - was recorded as 'posted'. 'posted' is now claimed only on evidence the channel accepted the message: an id, a 2xx statusCode, or an explicit posted flag. Anything else is 'unreported'. 2. The registry inferred non-delivery from an unobserved channel. When the announce hook threw as a whole, every unsettled channel was recorded 'failed'. That error says the announce STEP broke; it says nothing about a channel it never reached, or one whose request may already have been accepted. Those channels now read 'unreported' and carry the error, so they stay findable without claiming an observation nobody made. 'failed' still means observed: a per-channel call that rejects is a direct observation of that channel and is still recorded as a failure. An 'unreported' outcome now gets its own receipt and stderr line, because an unknown needs a human to go and look just as much as a failure does. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
codexmb's review covered two things and the first round only fixed the fan-out reconciliation. The three states are worth nothing if the surface a person reads collapses them back into two, and the HTML queue did exactly that: it built its own sentence, "card not posted: <state>", for EVERY non-posted state. An unreported channel was shown to the reader as a definite non-delivery. One sentence, one place: announceSummaryLine() is now the only wording, shipped as `announceSummary` on every intent view so the HTML queue, the /intents payload and the MCP list_intents output cannot word it differently. A mixed result reads "posted to 1 channel, unknown for 1", never "posted to 1 of 2 channels" - the short version tells the reader the second channel did not arrive, which is the one thing nobody here knows. 'failed' and 'not sent' are worded plainly because both were observed; 'unreported' and 'attempting' are always worded as unknown. Two defects the new tests caught on the way: - announceStateOf returned 'attempting' for posted+attempting, hiding the channel that demonstrably landed. Any mix containing a post is 'partial'. - the HTML badge painted 'partial' red. Red now means known not to have reached anyone (failed or skipped); anything unknown is amber, because red on an unknown is the same overclaim in colour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
What prompted it
Measured on a live daemon on 2026-09-20: four intents sat pending for up to
9.2 hours with
channels: ['groupmind']. An intent record was:It records that the intent was created and that it was decided. It recorded
nothing about whether the announcement - the card that asks the human -
actually reached anywhere. So there was no way to tell whether the owner saw
a card and ignored it, or whether the card never posted at all. Those two
situations call for opposite reactions, and the system could not distinguish
them.
This is the house shape: we record that we tried, never whether it landed.
Three distinct states, from the record alone
Every intent now carries
announcements, a map keyed by channel so a newchannel adds a key and no consumer changes:
plus a one-word
announceStatesummary. The three readings that used to beidentical:
statusannounceStatependingskippedpendingfailed(with the error)pendingpostedAlso
partial(some landed, the rest failed or are unknown),attempting(started, never settled),
unreported(no outcome was reported for thatchannel),
none(no channels asked for) andunknown(see below).Exposed everywhere intents are listed:
listIntents,getIntent,GET /intentswith a new?announce=<state>filter, the MCPlist_intentstool,and the built-in HTML queue, which now shows "card posted" or "card not posted:
<state>" on the card itself.
GET /intents?status=pending&announce=failedis the query that answers the question those 9.2 hours could not. An unknown
filter value is a 400, not an empty list, because a filter that quietly matches
nothing is indistinguishable from a healthy queue.
Surface, not retry
Decided in favour of surfacing the failure rather than marking the intent
un-announced and retrying:
key, a 402 from an unpaid invoice, an NXDOMAIN host. A retry loop burns the
same 9.2 hours and still ends silent.
ends in the same question: what do we do when it still has not landed. The
answer is "tell someone", so that is what this does directly.
losing the card is bad, refusing the approval is worse - so the failure is
recorded on the intent instead of failing
createIntent.A failure is written onto the intent, appended as an
intent.announce_failedreceipt with the channel, and written to stderr. An
unreportedoutcome getsthe same treatment through
intent.announce_unreported. Nothing is swallowed,and a failed or unknown announcement never looks like a pending one. Retry can
be layered on top later by a monitor reading
?announce=failed; it does notneed to be invented inside the create path.
The announcers also stopped draining the response and resolving regardless of
the status code. That was the deepest part of the hole: a 401 or a 402
resolved exactly like a successful post, so even a perfect recorder above it
would have recorded a success. Non-2xx now rejects, and an announcer with no
key/room/gate configured returns
{skipped: true, reason}rather than animplicit success.
Why
postedAt, notdeliveredAtorseenAtA 2xx proves the channel accepted the message. It does not prove the
message rendered, that a notification fired, or that the owner saw it. The
fields are named
postedAtandmessageIdfor exactly what they measure, thestrongest state is called
posted, and there is deliberately nodeliveredAtand noseenAt- naming a field for something this processcannot observe is the same overclaim this PR exists to correct. A test asserts
the record has no field and no state matching
/deliver|seen|read/.Backward compatibility
Existing persisted intents have none of these fields. Absent reads as
unknown- never as announced, never as failed. The discriminator is thepresence of the
announcementsobject: a new intent always has one (emptymeans "recorded, nothing attempted yet"), an old record has none. Tested by
replaying a hand-written old JSONL row into a fresh module instance, which is
how such a record actually arrives.
This PR does NOT close #116
#116's persistence findings remain open.
loadPersistedStateis stillreferenced only by
test/persist-intents.test.mjs, and it is still the onlything that sets
statePath, so in the daemonappendStateis a no-op andreplay never runs. Announcement records therefore do not survive a restart,
which limits what these receipts are worth until #116 lands. Nothing here fixes
that, and nothing here should be read as fixing it.
This change does not depend on persistence working - the records live on the
in-memory intent and are written through
persistIntent, so they startsurviving restarts the moment that separate defect is fixed.
Review round: preserving the unknown (codexmb)
The review found two paths with the same shape as the bug this PR fixes -
inferring a definite answer from an absence - and both are fixed:
composeAnnouncersrecordedpostedwhenever an announcer resolved without throwing, so an announcer that
returned nothing, or was misconfigured in a way nobody had anticipated,
announced nothing and recorded a success. That is this PR's own bug one level
up in the composition layer.
postedis now claimed only on evidence that thechannel accepted the message: an id, a 2xx
statusCode, or an explicitposted: true. Anything else isunreported.threw as a whole, every unsettled channel was recorded
failed. That errorsays the announce STEP broke; it says nothing about a channel it never
reached, or one whose request the server may already have accepted. Those
channels now read
unreportedand keep the error, so they stay findablewithout claiming an observation nobody made.
failedstill means observed: a per-channel call that rejects is a directobservation of that channel and is still a failure, proven by its own test.
unreportednow also gets a receipt and a stderr line, because an unknownneeds a human to go and look just as much as a failure does.
Review round 2: the same honesty in the wording a human reads
The review covered two things and round 1 fixed only the fan-out
reconciliation. Three states are worth nothing if the surface collapses them
back into two, and the HTML queue did exactly that - it built its own sentence,
'card not posted: ' + state, for EVERY non-posted state, so anunreportedchannel was shown to the reader as a definite non-delivery.
One sentence, one place.
announceSummaryLine()is now the only wording,shipped as
announceSummaryon every intent view, so the HTML queue, the/intentspayload and the MCPlist_intentsoutput cannot word itdifferently. The UI was made to match the README, not the other way round.
posted to 1 channelposted to 2 channelsposted to 1 channel, unknown for 1posted to 1 channel, failed for 1posted to 1 channel, failed for 1, unknown for 1posted to 1 channel, not sent for 1failed for 1 channelnot sent for 1 channelunknown for 1 channelno channels were askedunknown: this intent predates announcement recordsThe third row is the point. It is deliberately not "posted to 1 of 2
channels": that reads as though the second channel definitely did not arrive,
and when its outcome is
unreportednobody knows whether it did. Longer, andthe only version that is true.
failedandnot sentare worded plainlybecause both were OBSERVED;
unreportedandattemptingare always worded asunknown and never folded into either side.
Also audited: the stderr lines (
... FAILED:only on an observed failure,... UNREPORTED:for an unknown), and thelist_intentstool description,which said announcements were "POSTED, never posted, or failed" and now names
the unknown states and tells the reader not to report them as delivered or as
failed.
Two defects the new tests caught on the way:
announceStateOfreturnedattemptingfor posted+attempting, hiding thechannel that demonstrably landed. Any mix containing a real post is now
partial.partialred. Red now means known not to have reachedanyone (
failedorskipped); anything unknown is amber, because red on anunknown is the same overclaim in colour.
Tests
test/confirmations.test.mjs: 30 -> 46 tests, all passing. Fullnpm test:433 tests, 433 pass, exit 0 (the flaky
gui adapter runs the idle guard before the scriptpassed on every run).New cases: a successful announcement records the message id and a timestamp; the
three readable states; an announcer that throws does not leave the intent
looking normally pending; an announcer that reports nothing reads as
unreported; silence through the fan-out is not a post; a 2xx with no id stillcounts as posted; a wholesale announce failure records unknown, not a definite
non-delivery; a channel whose own call rejects is still
failed; an old intentreads
unknown; the record never claims the human saw anything; a non-2xx is afailed announcement (driven through a real listener, since the swallowing lived
in the response handler); an unconfigured announcer records
skipped; the?announce=filter; the pinned human-visible line for a mixed posted +unreported intent; a table pinning the rendered line for all eleven state
combinations; and the HTML queue rendering the server's wording rather than
its own.
Proven control 1 - the failure must not be swallowed
Broke
composeAnnouncersto log the error the way the old code did instead ofrecording it:
Restored:
Proven control 2 - absent must not read as announced
Broke
announceStateOfto return'posted'when there is noannouncementsmap:
Restored:
Proven control 3 - silence must not read as a post
Removed the evidence guard so any resolution reads
posted, the way the firstround behaved:
Restored:
Proven control 4 - an unobserved channel must not read as a failure
Put
status: 'failed'back on the wholesale-throw reconciliation:Restored:
Proven control 5 - the page must not call an unknown outcome "not posted"
Put the page's own sentence back:
Restored:
Proven control 6 - the confident "1 of 2" wording must not come back
Made the summary count the unknowns as a shortfall:
Restored:
🤖 Generated with Claude Code