[nissa-seru]

The notices that tell an agent a channel was opened for it now say what happens next, how servers differ in what an open channel brings, and what won't reopen a channel the agent closed. Two comments in agent.ts now say which reader takes a missing watermark which way.

Problem

Three sentences in channelOpenedNotices (src/framework.ts) left the agent without what it needed to act on them.

• A subscription policy's notice said "This records the admission decision; channel_list shows current transport state." That is the host's view. The notice is written before the host asks the server to open the channels (reconcileChannels, src/mcpl/channel-registry.ts:3354), and the decision stays if that open fails. By our reading, the host asks again when the server next registers the channel: handleRegister (:1468) and a channels/changed that adds it (:1576) both reconcile it. The notice didn't say that, or what channel_list would show.
• "What an open channel delivers to you depends on its server" didn't say how it depends, or where to find out. Servers differ:
  • discord-mcpl "delivers the messages posted in an open channel as they arrive";
  • slack-mcpl delivers mentions and DMs always, and other messages only from a conversation it's subscribed to. subscribe_channel and unsubscribe_channel change that. A mention that is the first message it takes from a conversation subscribes it, with a note saying so, unless the agent unsubscribed from it (server.ts:1703). With SLACK_SUBSCRIBE_MEMBER_CHANNELS, every conversation the bot is in is subscribed, and unsubscribe_channel mutes one.
• "use channel_close; your choice outranks policy" didn't say which policy. A close is recorded as the agent's decision (source agent-tool, :4107). ensureInitialDesiredState lifts only a closed state nobody decided (default-closed, :3023), whether for the subscription policy or for a descriptor's initiallyOpen. So neither reopens a channel the agent closed.

markContextConsumed's comment in src/agent.ts said that "without a watermark nothing is ever treated as unread", and markContextShown's doc said the same of the shown watermark. That is the coalescer's reading. isUnreadStoredMessage and resolvePlacement take a missing consumed watermark as read, and isUnreadStoredMessage takes a missing shown watermark as shown. But deferredWriteReadOrGone and unreadNoticesForPrimary take a missing consumed watermark as unread.

Changes

• A subscription policy's notice reads "The host opens it, and if that fails, tries again when its server next registers it; channel_list shows whether it's open yet." For several channels: "The host opens them, and if one doesn't open, tries again when its server next registers it; channel_list shows whether each is open yet." "Registers" is the verb channel_open's and channel_close's failure texts use for the same retry (laterClause, :722).
• Where the agent's window holds the channel's traffic, a notice reads "What an open channel brings you is up to its server: some send every message in it, and others only what addresses you unless you're subscribed to it; their own tools can change that."
• Where the agent can close the channel, a notice reads "If you don't want it, use channel_close: neither the subscription policy nor its server's own default opens it again." It says nothing about the agent's own messages, since on main a message into a closed channel still opens it.
• The two agent.ts comments say which reader takes a missing watermark which way.
• The notice builder's doc comment, and fix(channels): a channel notice reaches whoever can close the channel, and a released agent's unread ones reach the primary #598's pending fragment (channel-notices-reach-who-can-close.fixed.md), no longer quote the replaced sentences.
• A changelog fragment, channel-opened-notice-words.changed.md.

What each part is for

• Each new sentence replaces one the agent couldn't act on, in the same place and under the same conditions. Nothing decides differently, and no notice is sent where it wasn't.
• The plural form of the policy notice is there because a policy admits a server's channels in one batched notice, and the singular sentence would call them "it".
• The comments cost nothing to keep, and the old ones were a claim a later reader could build on.
• The changelog fragment tells hosts and module authors the words their agents now read, and what they replace, as CONTRIBUTING asks for behaviour a host or downstream consumer would notice. Editing fix(channels): a channel notice reaches whoever can close the channel, and a released agent's unread ones reach the primary #598's pending fragment keeps the same release's notes from quoting a sentence the notice no longer has.
• Left out:
  • Naming the servers in the notice: what a server does is its own to change, so the notice names the two kinds and where to look.
  • The retry's condition: the retry also needs the host still to be allowed to direct that server's channels (reconcileChannels returns early otherwise, :3331). The notice is written only while the host is. Only a grant reduced afterwards makes it untrue, which stops the lifecycle of every channel that server has, and channel_list then shows the channel isn't open.
  • channel_open's and channel_close's descriptions, which say that what an open channel delivers, and what stops reaching you once it's closed, depends on its server: those are tool text, which changes on its own route.

+25 −15 lines in src/, comments included.

Tests

The tests that pin the notices' text now pin the new sentences:

• channel-lifecycle-order:
  • "failed policy opening records intent once, with truthful resident text through a retry" fails the first open and checks the notice's words. Then the server registers the channel again: the server's fake receives a second open request, and the channel opens with no second notice. Then the test rebuilds the registry from the same store, and the channel opens again when the server adds it.
  • "the notices say what happened, name the opt-out, and state no rule about later sends" checks each cause's notice, the plural policy notice among them.
  • "the opened notice names channel_close only where the agent it's addressed to can call it, …" checks each reader and cause.
• route-failure-targeting: the primary's by-name notices, which carry the close sentence.
• trunk-channel-routing: "the "Now open" notice leaves what an open channel delivers to its server", over each form an agent can read, the plural policy notice included.

Checks

On Linux, Node 24.22.0, from clean trees:

• The full check: tsc --noEmit and npm run build pass. npm test runs 6,006 tests: 5,962 pass, 44 are skipped, and none fail. It ran on a tree that differs from this head only in one line of the new changelog fragment, which no test reads.
• This head's tests with main's src/framework.ts: 8 of 249 fail in the three files above. They are the eight tests whose expected words this change rewrites (three in channel-lifecycle-order, four in route-failure-targeting, one in trunk-channel-routing), and no other test fails.
• With handleRegister's reconcile removed: the failed-policy test fails, with two other registration tests.

Merge notes

• fix(conversations): a fork's seed leaves out its template's channel and by-name notices #674 (open) rewrites the same doc comment in src/framework.ts, where its fork sentence and this change's retry and opt-out wording meet. Both also edit channel-notices-reach-who-can-close.fixed.md, which git merges cleanly.

Written by Meg-2646 (Claude Opus 5.5). Ada-1017 (Claude Opus 5.5) made the design calls on each sentence, and Pippa-2697 (Claude Opus 5.5) read and approved it. Our internal review read the change, and this head carries the fixes it led to.

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling, and posted from the shared nissa-seru account.

[github-actions]

Automated review

Recommendation: merge. The review found nothing of medium or high severity.

Reviewed commit 314cfcb with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits the project. The PR rewrites the wording of existing channel-opened notices and two comments, with updated tests and a changelog fragment. Nothing decides differently and nothing is added.

5 reasons with sources

This is wording for behavior the project already has, in the place that already owns it.

• It changes only the text of a notice the framework already sends, in the builder that already makes it. The edits replace three strings inside optOut and readerText. The conditions that decide who sees each sentence, holdsChannelTraffic and canCloseChannels, are left as they were. (src/framework.ts (channelOpenedNotices))
• It respects the stated rule that what an open channel delivers is the server's to say. The new sentence says servers differ and that their own tools change what arrives. It doesn't promise any particular traffic or name specific servers, so the boundary between host and server stays where #406 put it. (src/mcpl/channel-registry.ts (onChannelAutoOpened doc, #406))
• It adds a changelog fragment for a change in wording that agents will see, as CONTRIBUTING asks. It adds changelog.d/channel-opened-notice-words.changed.md and updates the pending #598 fragment so that it no longer quotes the replaced sentence. (CONTRIBUTING.md (Changelog; What a PR should contain))
• The tests that pin the notice text are updated, and a retry assertion is added for the new claim that the host tries again. channel-lifecycle-order now checks that handleRegister reissues the open after a failed policy open, which backs up what the new notice text claims. (CONTRIBUTING.md (Tests accompany behavior changes))
• The comment fixes in agent.ts are small and related, and they correct a claim about watermarks rather than change behavior. Only the comments change. They fit the PR's theme of making the stated text match what the code actually does. (src/agent.ts (markContextConsumed / markContextShown))

Findings

No findings of medium or high severity.