Skip to content

Intents: record whether the announcement actually posted - #121

Merged
ThinkOffApp merged 3 commits into
mainfrom
feat/intent-announce-receipt
Sep 20, 2026
Merged

ThinkOffApp merged 3 commits into
mainfrom
feat/intent-announce-receipt

Conversation

@ThinkOffApp

@ThinkOffApp ThinkOffApp commented Sep 20, 2026 •

Copy link
Copy Markdown
Owner

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:

id, prompt, session, channels, status, createdAt, decidedAt, decision, decidedBy, decidedByRole, requiresHuman

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 new
channel adds a key and no consumer changes:

announcements: {
  groupmind: { channel, status, attemptedAt, postedAt, messageId, error }
}

plus a one-word announceState summary. The three readings that used to be
identical:

situation status announceState
nothing was wired to post it pending skipped
the post was attempted and observed failing pending failed (with the error)
the room accepted it, the human has not answered pending posted

Also partial (some landed, the rest failed or are unknown), attempting
(started, never settled), unreported (no outcome was reported for that
channel), none (no channels asked for) and unknown (see below).

Exposed everywhere intents are listed: listIntents, getIntent, GET /intents with a new ?announce=<state> filter, the MCP list_intents tool,
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=failed
is 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:

  • the failures actually seen here are not transient - a 401 from a rotated
    key, a 402 from an unpaid invoice, an NXDOMAIN host. A retry loop burns the
    same 9.2 hours and still ends silent.
  • a retry needs a backoff, a cap and a state machine, and every one of those
    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.
  • the intent must stay decidable. An announce failure never blocks the intent -
    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_failed
receipt with the channel, and written to stderr. An unreported outcome gets
the 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 not
need 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 an
implicit success.

Why postedAt, not deliveredAt or seenAt

A 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 postedAt and messageId for exactly what they measure, the
strongest state is called posted, and there is deliberately no
deliveredAt and no seenAt
- naming a field for something this process
cannot 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 the
presence of the announcements object: a new intent always has one (empty
means "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. loadPersistedState is still
referenced only by test/persist-intents.test.mjs, and it is still the only
thing that sets statePath, so in the daemon appendState is a no-op and
replay 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 start
surviving 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:

  • Success inferred from silence. composeAnnouncers recorded posted
    whenever 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. posted is now claimed only on evidence that the
    channel accepted the message: an id, a 2xx statusCode, or an explicit
    posted: true. Anything else is unreported.
  • Non-delivery inferred 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 the server may already have accepted. Those
    channels now read unreported and keep 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 a failure, proven by its own test.
unreported now also gets a receipt and a stderr line, because an unknown
needs 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 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. The UI was made to match the README, not the other way round.

situation the line a person reads
one channel accepted it posted to 1 channel
two accepted posted to 2 channels
one accepted, one reported nothing posted to 1 channel, unknown for 1
one accepted, one observed failing posted to 1 channel, failed for 1
one accepted, one failed, one silent posted to 1 channel, failed for 1, unknown for 1
one accepted, one had no announcer posted to 1 channel, not sent for 1
the only channel failed failed for 1 channel
nothing configured to send it not sent for 1 channel
no outcome reported / still in flight unknown for 1 channel
no channels asked for no channels were asked
an old record unknown: this intent predates announcement records

The 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 unreported nobody knows whether it did. Longer, and
the only version that is true. failed and not sent are worded plainly
because both were OBSERVED; unreported and attempting are always worded as
unknown and never folded into either side.

Also audited: the stderr lines (... FAILED: only on an observed failure,
... UNREPORTED: for an unknown), and the list_intents tool 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:

  • announceStateOf returned attempting for posted+attempting, hiding the
    channel that demonstrably landed. Any mix containing a real post is now
    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.

Tests

test/confirmations.test.mjs: 30 -> 46 tests, all passing. Full npm test:
433 tests, 433 pass, exit 0 (the flaky gui adapter runs the idle guard before the script passed 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 still
counts as posted; a wholesale announce failure records unknown, not a definite
non-delivery; a channel whose own call rejects is still failed; an old intent
reads unknown; the record never claims the human saw anything; a non-2xx is a
failed 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 composeAnnouncers to log the error the way the old code did instead of
recording it:

CONTROL_A_BROKEN_EXIT=1     tests 39  pass 36  fail 3
✖ three readable states: never announced, announce failed, and posted-and-waiting
✖ a non-2xx from the channel is a failed announcement, not a silent success
✖ GET /intents?announce= separates never-announced from waiting-on-a-human, and rejects unknown values

  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + 'unreported'
  - 'failed'

Restored:

CONTROL_A_RESTORED_EXIT=0
tests 39   pass 39   fail 0

Proven control 2 - absent must not read as announced

Broke announceStateOf to return 'posted' when there is no announcements
map:

CONTROL_B_BROKEN_EXIT=1     tests 39  pass 38  fail 1
✖ an intent from before announcement receipts reads unknown, never announced

  AssertionError [ERR_ASSERTION]: absent reads as unknown
  + 'posted'
  - 'unknown'

Restored:

CONTROL_B_RESTORED_EXIT=0
tests 39   pass 39   fail 0

Proven control 3 - silence must not read as a post

Removed the evidence guard so any resolution reads posted, the way the first
round behaved:

CONTROL_C_BROKEN_EXIT=1     tests 43  pass 42  fail 1
✖ composeAnnouncers does not read silence as a successful post

  AssertionError [ERR_ASSERTION]: silence is not evidence of a post
  actual: 'posted'

Restored:

CONTROL_C_RESTORED_EXIT=0
tests 43   pass 43   fail 0

Proven control 4 - an unobserved channel must not read as a failure

Put status: 'failed' back on the wholesale-throw reconciliation:

CONTROL_D_BROKEN_EXIT=1     tests 43  pass 41  fail 2
✖ an announcer that throws does not leave the intent looking normally pending
✖ a wholesale announce failure records unknown, not a definite non-delivery

  AssertionError [ERR_ASSERTION]: it does not read as a normal pending card either
  + 'failed'
  - 'unreported'

  AssertionError [ERR_ASSERTION]: nothing observed this channel failing
  actual: 'failed'

Restored:

CONTROL_D_RESTORED_EXIT=0
tests 43   pass 43   fail 0

Proven control 5 - the page must not call an unknown outcome "not posted"

Put the page's own sentence back:

CONTROL_E_BROKEN_EXIT=1     tests 46  pass 45  fail 1
✖ the HTML queue renders the server wording, and never calls an unknown outcome "not posted"
  AssertionError: no blanket "not posted" wording for every non-posted state

Restored:

CONTROL_E_RESTORED_EXIT=0
tests 46   pass 46   fail 0

Proven control 6 - the confident "1 of 2" wording must not come back

Made the summary count the unknowns as a shortfall:

CONTROL_F_BROKEN_EXIT=1     tests 46  pass 44  fail 2
✖ the line a human reads names an unknown channel as unknown, not as not-posted
✖ every announcement state has a rendered line, and none of them overclaims
  AssertionError: Expected values to be strictly equal:
  + 'posted to 1 of 2 channels'
  - 'posted to 1 channel, unknown for 1'

Restored:

CONTROL_F_RESTORED_EXIT=0
tests 46   pass 46   fail 0

🤖 Generated with Claude Code

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>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 20, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-20T07:31:38.944057Z 3b7046e PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread src/mcp-server.mjs Outdated
{
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.',

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread src/confirmations.mjs Outdated
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;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Petrus Pennanen and others added 2 commits September 20, 2026 11:23
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>
@ThinkOffApp
ThinkOffApp merged commit cfee57a into main Sep 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant