[nissa-seru]

What the channel tools and speech tell an agent when they can't do what it asked now says what happened, whether anything took effect, and what works from there, or that calling again won't change it. A server's state is read before its grant is quoted, so a server that is only reconnecting no longer reads as one that refuses.

Problem

channel-registry.ts answered a refusal or a failure in its own words: channels.lifecycle not in "S"'s effective grant (§14.1), Server not found: S, Channel not found: x, Channel id is ambiguous across MCPL servers: x. Include serverId., lifecycle work prevented delivery: …, channel is closed and open failed: …, server "S" reported delivered:false, Failed to close the channel's transport: …. By our reading, an agent reads these in a tool result, in a [discord-send-failed] notice, in the drafts tool's lines or in a >> bounce. Most name a grant or an internal step, not what the agent can do next.

The grant's refusal could also be wrong. By our reading of server-connection.ts, a connection's grant is empty from a transport drop until its next policy exchange ends. Every grant check read that emptiness as a refusal, so while a server was reconnecting, channel_open said channels.lifecycle not in "S"'s effective grant (§14.1), channel_publish said channels.publish not in …, and speech's notice said the same. An agent reading those would take a passing state for a policy.

Changes

• The server's state, before its grant is quoted (serverReach):

  • gone: not registered, or registered, closed and not reconnecting, with nothing connecting it;
  • connecting: a connect or restart of its id in flight, or a registered connection whose transport's policy exchange is still in flight;
  • down: registered, between transports, and reconnecting;
  • up: connected with its exchange ended, granted or not.

  Only an up server is read by its grant, and one without what was asked reads as not permitted, with "if you need it, ask whoever runs this host". Each other state says what helps: try again in a moment, try again later, or ask whoever runs this host. The grant still decides every refusal where it did, and the state only words it.

• serverConnecting, a new optional ChannelRegistryOptions callback, says when the host is connecting to a server. The framework builds it from the connect and restart marks that a tool call's own "connecting" text already reads, and from the policy exchange's marker (mcplPlanesMayOpen) for a registered connection that is connected. A restart reads as connecting for its whole run, through the disconnect of the connection it replaces.

• Lifecycle failures as one class, ChannelLifecycleError, whose message is a clause in the agent's words, which the traces carry too, and whose kind says what the agent can do next. It replaces three error classes, none of them exported. channel_open and channel_close say, in this order:

  • a decision the lifecycle log refused, so nothing changed;
  • a channel no longer registered here, with why it went where the failure says (this host's disconnect or the server's de-listing), or else the server's state where it isn't up, and a request's own words where it failed with them, naming no channel tool, since none can find it;
  • a later decision that came first, and what changes it;
  • a server that isn't up: that the change is recorded, and when it happens, though not a backscroll's history;
  • a change that already holds, with no other work for the channel under way, read as the registry's own checks read it;
  • or what the request met, with whether calling again helps.

  Every promise of a later change names reconciliation's conditions: the server registers the channel again, and this host may open and close its channels then. A refusal for the grant, and an open answered for another channel, say the decision stays recorded. A tuned-out channel's messages are said to go to the subconscious, which channel_open doesn't change.

• fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's failures of an open by speech or a reply are kinds of that class too, since this branch merged main after fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568:

  • overtaken: a decision made during the open's round-trip replaced it;
  • put-back-unrecorded: putting back the decision it replaced couldn't be recorded;
  • selected-again, with by: the channel's descriptor or the subscription policy lifts the default it put back.

  openIfClosedForSend gives the same answers as with fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's classes. Speech's reason for each starts with the open's own clause. overtaken adds that a decision about the channel made while the open was out stands, unless the open's own clause already names that decision. It offers no step, since what helps turns on that decision. The other two add fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's own words about the channel's selection. After a server's own words, which keep their final stop, what follows is a sentence of its own. fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's refusal of an incidental open before anything is written keeps its check, and its words come from the server's state, as every other lifecycle refusal's do. Its mcpl:channel-open-failed trace carries those words too, where it carried Server not found: <server> or the grant's name.

• channel_decline says the decline is recorded, whatever became of its acknowledgment and its close, and a later decision that replaced it while it ran: an open, or a tune-out. It offers posting the acknowledgment again only where another decline would be taken: the decline stands, and the channel is registered and not open. It offers it only where nothing could have been posted, too. Where the request may have reached the server with no answer saying it wasn't posted (no answer, an error answer, or one that didn't say), the acknowledgment may have been posted, so the text says that declining again with it could post it twice, and offers nothing. Its refusal of a channel that's open says to call channel_close if it needs closing, except where the server is up without channels.lifecycle: there it says this host may not close it, and whom to ask. Only acknowledged: true counts as posted, and only false as not posted, as for a publish's receipt.

• A decision the lifecycle log refuses to append, as on a full disk, now gets an answer from channel_close and channel_decline as well as channel_open: nothing changed, nothing was sent to the server (and for a decline, no acknowledgment was posted), and calling again tries again. The two rejected before, so the agent read the store's error alone, with nothing on whether the close took. What a host can see. By our reading of src/mcpl/tool-lifecycle.ts, a host that watches tool calls through RFC-007 now gets completed with isError as these two calls' terminal there, where it got failed. channel_open's terminal was already completed.

• A decline's record of the invitation it declined, an audit record written once the decline has taken effect and read by nothing, no longer fails the decline when the log refuses it. The [channel-decline] log line says so instead. What a host can see. On that path, by the same reading, the call's RFC-007 terminal is completed, where it was failed.

• A delivery's reason (PublishOutcome.reason) is one clause that reads in every text that composes it, and in the [routeSpeech] log line and the mcpl:speech-route-failed trace; the agent's adds what helps. Words that waited for a channel's lifecycle work say what the wait found:

  • the channel was removed before they went out;
  • a decision to close it came before they went out, true whether or not the close itself took;
  • or it isn't confirmed open, with the failure of the work they waited for, if there was one.

  A close that stands is named whenever it was decided, since one decided before the words began stands as much as one decided while they waited. Words checked against a connection the registry replaced while they waited say so where the replacement would take them, and otherwise describe the replacement as it stands. Speech whose channel id is on more than one server says no server was named for the words, and whom to ask. The open step's own failure names no state of the channel's transport, which can be open after a close that failed.

• The two reasons for speech with no channel to go to keep their words in the log line and the trace, which, by our reading, connectome-host's connectome-doctor reads for "no locus". The agent reads its own words, which name no tool, since whether one it may call could post them isn't known there, and say whom to ask. The code says why the two differ.

• channel_publish and the subconscious's speak_in_channel share speech's refusal for a server's state and grant, framed as Nothing was posted to channel "x": <reason>., and an unconfirmed post as Posting to channel "x" wasn't confirmed: …. speak_in_channel's refusals for a missing or unknown channel point to the tuned-out channels the subconscious reads, since it isn't offered channel_list. channel_publish refuses an empty channelId as empty.

• A channel id on another server, or on several, names them in channel_open's, channel_close's and channel_decline's refusal.

• A server's own error words keep their final period, which a test now pins, and this host's own words, a request's or its store's, lose theirs where a reason composes them. mcpl-request-outcome.test.ts's header says what an error response keeps.

• Pending changelog: publish-waits-for-new-registration.fixed.md no longer quotes the old lifecycle work prevented delivery: … prefix. fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's failed-speech-open-puts-back.fixed.md no longer says speech tells the agent the channel is closed, nor that the reply's notice uses channel_open's own words.

• Left as they are: the inbound-only refusals, which already say what to do, and the >> resolver's texts.

What each part is for

• serverReach. It is the fix for the wrong refusal: without it, a reconnecting server's empty grant reads as a policy. It reads the registry's connection and one callback, and changes no decision.
• serverConnecting and its framework wiring. Without it, a server mid-connect or mid-restart would read as gone, with "ask whoever runs this host", while it was being connected. It adds one optional callback and its few lines in the framework, plus the helper mcplConnectInFlight, which mcplServerAbsentText now shares.
• Reading the exchange's marker, not the grant, for "connecting". An exchange that was refused or went unanswered leaves the grant empty for that whole transport. A grant-based reading would say "still connecting" until the next reconnect, and the marker says "not permitted" once the exchange has ended, unless a connect or restart of the id is still under way. A closed connection's marker isn't read: it has no exchange to wait for.
• ChannelLifecycleError and its kinds. Each kind has its own next step: try again, wait for the server, ask whoever runs this host, or nothing. Traces carry the same clause, so the agent's words and the operator's can't drift apart.
• fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's three kinds. One class carries every lifecycle failure, so speech words fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's failures as it words the rest, and openIfClosedForSend's answers stay as fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568 has them. by is the one field a kind adds, for the reply's notice, and cause keeps the open's own error, as fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's classes did, for whoever inspects or logs the failure.
• afterClause. A server's own words keep their final stop, so a failure's further words after them start a sentence of their own, rather than following a stop with a semicolon.
• lifecycleFailureText's order. A decision the log refused changed nothing, so that comes first. A channel no longer registered comes next, since every other text would name a tool that can't find it. A later decision is what stands, so it comes before the server's state.
• The in-effect reading. A change that already holds is read from the registry as its own checks read it (channel_open's already-open answer, the decline's refusal, delivery): a request that failed leaves the open flag as it was, and the unconfirmed mark counts only while the channel isn't open. A text that read the mark there would tell the agent one thing while the next call did another.
• The store fake's words. channel-decision-log-first's failing store takes the words it throws, so a test pins that a store's own sentence loses its final period where a reason composes it; with one fixed message, no test could tell.
• The decline's refusal of an open channel. It names channel_close as the call that closes the channel, and lets that call's own answer say when, since for a server that isn't up the close waits for the server. Where the server is up without channels.lifecycle, channel_close would only record a close, so the text says this host may not close it and whom to ask.
• The decline's close and a registration that went. The server may have closed the channel before its registration went, so a close cut short by a de-listing or by this host's disconnect isn't said to have failed. The text says the channel isn't registered here any more, or that its registration went and came back.
• laterClause. One phrase for when reconciling applies a recorded decision, with both of its conditions, so no text promises a change that reconciling would skip.
• The registration-gone branch. A registration can go at the server's word or at this host's, so the text names which only where the failure says (a cancellation by this host's disconnect, or the server's de-listing), and otherwise the server's state where it isn't up, a request's own words, and the decision that stands; every other branch would name a tool that can't find the channel. A tune-out is in effect already, so only an open or a close is said to happen later.
• "Doesn't stand" and "didn't go through". A change a later decision replaced, or one refused for the grant, can leave the transport either way, since other work for the channel, or the later decision's own, may hold it; the text says only what became of this call's change, and the later decision's own call says what became of the transport.
• The tuned-out texts. A tune-out sends the channel's messages to the subconscious and keeps its epoch, which a plain open would discard, so channel_open refuses one and points to tune_out's cancel.
• The backscroll clause. Reconciling opens a channel but asks for no history, so a recorded open would otherwise read as bringing the history too.
• The settled check. A decision is said to be in effect only when no other lifecycle work for the channel is under way, since that work may have changed it already, as an open out at the server may have.
• Answering a refused decision write in all three tools. The store's error alone doesn't say whether the close or the decline took, and the agent needs that. channel_open already answered.
• "stays recorded" on a refusal for the grant and on a substituted open. The decision is written before the server is asked, and reconciling applies it later, so "wasn't opened" alone would read as void.
• refusalRemedy. It adds what helps after a refused or unsettled operation: the server state's remedy, whom to ask for a grant, or another try where the channel's target kept changing or the decision couldn't be recorded, with whom to ask if that keeps failing. It goes on the open step's reason, on "the channel isn't confirmed open", and on a joined delivery's failure.
• openFailedReason. The open step's failure is said as an open that didn't complete, with what helps. A refusal from the wait after a successful open passes through whole, since "opening it didn't complete" would be false there.
• waitForOpenChannel's three reasons, and the failure it remembers. "The channel isn't confirmed open" alone can't say why. The failure of the work it waited for says that, when there was one.
• sendRefusal. One refusal for a send, worded from the server's state, so speech, channel_publish and speak_in_channel say the same thing in the same words. Its checked connection keeps the last check from describing a connection that replaced the one whose grant refused: where the replacement would take the words, another try is worth it, and otherwise the refusal is worded as the replacement stands.
• The shared-id reason. Speech can't name a server, so whoever runs this host is the one who can help, and a caller that can name one reads that none was.
• The empty-channelId check. ?? takes an empty channelId as given, so it read as having no channel to default to, when leaving it out would have used the default.
• requestErrorText. One rule for a failed request's words in a composed reason: this host's sentences lose their final period, since every composition adds its own ending, and a server's error answer keeps its words as they came, which publish-outcome's tests pin.
• The other-server clause in resolveToolChannelEntry. A serverId that doesn't have the channel would otherwise read as no such channel, when the channel is on another server, which the clause names.
• The decline's texts. The decline takes effect whatever becomes of its acknowledgment, so each acknowledgment text starts there. Reading the decision once the awaits are done is what tells a decline that stands from one a later open replaced, and only the first can be repeated. The not-sent split, and reading the receipt by fix(mcpl): require explicit final speech delivery receipts #163's rule, keep a retry from posting the acknowledgment twice. The catch around the declined invitation's record keeps a decline that took effect from reading as failed. A representation that isn't a string is none, since the declined invitation's record keeps it as one.
• The logged argument of deliverSpeech's fail. It keeps the two no-locus reasons' operator words where connectome-doctor reads them, and only there.
• channel_publish's new frame. The reason now ends with its remedy, and fix(mcpl): require explicit final speech delivery receipts #163's trailing "Nothing was posted." came after it. The new frame says what happened first and leaves the remedy last.
• speak_in_channel's pointer. The subconscious isn't offered channel_list, so the pointer names where it finds a channel id.

Cut: removing a gone server's lingering channel entries (behaviour, not words), the >> resolver's texts, module-origin close texts that no agent reads, and the tools' descriptions.

Tests

• test/channel-agent-words.test.ts is new. It covers:
  • each state's clause on channel_open, channel_close, channel_decline, channel_publish, speak_in_channel and speech, a server this host is restarting included, reconnecting or not;
  • a backscroll whose server isn't up, and a refusal for the grant;
  • a channel no longer registered while its open or close was out, at the server's word or at this host's, with the request's own words and the server's state;
  • a later decision that came first, for an open, a close and a tune-out, and with the server dropped meanwhile;
  • a change that already holds, with and without the grant, a close that isn't in effect while an open is out, and an open after a close that failed, said as channel_open's already-open answer reads it;
  • speech that has to open its channel, refused for the grant or the state, words that waited for lifecycle work the server dropped during, words that met a close behind later work after their own open completed, and words checked against a connection the registry replaced, by one that would take them, one without the grant and one still connecting;
  • each acknowledgment outcome and answer of a decline, including an error answer and answers that don't say whether it was posted;
  • a decline whose close a later open overtook, and one a later open or tune-out replaced while its acknowledgment was out, after each of four acknowledgment outcomes;
  • a decline whose channel the server stopped listing while its acknowledgment was out, and one whose channel stopped being registered while its close was out, at the server's word and at this host's, and one whose registration came back;
  • a decline's refusal of a channel that's open, where the server is up with the grant, up without it, and down;
  • an acknowledgment refused for the grant, whose text still says so when the server drops during the decline's close;
  • the framework's own connect of an unregistered id, a restart's claim on a registered id and an unregistered one, and a closed connection left with a marker;
  • a registered server's policy exchange read through its marker, including a marker an earlier transport left and an exchange that ended without a grant;
  • that a granted server is refused nothing while the host is connecting to its id.
• The tests that pinned the old texts take the new ones. That's in channel-lifecycle-order, channel-registry-routing, publish-outcome, channel-open-substitution, refusals-are-error-results, route-failure-targeting, channel-decision-log-first and mcpl-gate-roundtrip. In channel-decision-log-first, the close and the decline whose decision fails to append now get an answer, where they asserted a rejection, a decline whose declined invitation can't be recorded still declines, and speech whose open can't record its decision says what helps. In channel-registry-routing, the no-locus test also reads the [routeSpeech] line connectome-doctor reads. In channel-lifecycle-order, fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's tests of speech's reasons, of the open-failed trace for a gone server and of channel_open's refusal without the grant take the new words, and its tests of openIfClosedForSend's answers pass unchanged. New cases there cover an overtaken open whose own clause already names the later close, a selected-again failure after a server's words that end in a stop, and the subscription policy's clause in the open-failed trace.

At ef4ea120, which holds this branch's merge of main 63835621, on Linux, with Node 24.22.0, tsc --noEmit and the build are clean, and the whole suite passes: 5428 tests, 5401 pass and 27 skipped, none failing. Merged with today's main (f63bbfa8), it typechecks and the whole suite passes too: 5507 tests, none failing.

Red-first, with this branch's tests on main's source (63835621): 88 of the 10 touched files' 347 tests fail, among them 21 of channel-agent-words' 22 and 28 of channel-lifecycle-order's 129. The twenty-second, that a granted server is refused nothing while the host is connecting to its id, passes there too, since it pins what the change keeps. mcpl-request-outcome's change is its header comment alone.

Removals at ef4ea120, each part above taken away alone: 74 pieces, each run against the test files that should catch it, and each fails a test there. #568's own 50 removals, with the anchors that named its classes or its words moved to the kinds, each fail a test there too.

Not verified

• macOS and Node 20, except through CI.
• A live server's reconnect or restart, through the framework end to end. The marker's reading and the restart's claim are tested with a stub connection on the framework's own registry.

---

• Changelog fragment added: changelog.d/channel-agent-words.changed.md, and fix(mcpl): publish() publishes only into a registration confirmed open, under the grant as it is then #569's changelog.d/publish-waits-for-new-registration.fixed.md and fix(mcpl): an open by speech or a reply that fails puts back the decision it replaced #568's changelog.d/failed-speech-open-puts-back.fixed.md updated

Written by Cordelia-2434 (Claude Opus 5.5), contributing through nissa-seru, to design calls by Ada-1017 (Claude Opus 5.5), and read by Desmond-2579 (Claude Opus 5.5). Petra-1012 (Claude Opus 5.5), who wrote #568, read #568's side of this branch's merge of main. Our internal review read the change before it opened, and read the merge too.

Description checked and posted by Fiona-2757 (Claude Opus 5.5).

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

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

This PR makes channel failures explain what happened, what remains recorded, and what the agent can do next.

• Channel refusals tell agents whether a server is ready.
• Channel changes explain what took effect and what can happen next.
• Speech and channel sends explain why delivery failed or remains uncertain.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): the channel tools and speech ..." · Reviewed by Greptile}