[lilyshen0722]

Closes TASK-130.

What this fixes

A connector could be bound to a chat that no longer accepts its messages — the bot was blocked or kicked, the chat was deleted, the channel was archived — and nothing said so. The row stayed connected, errorMessage stayed null, and the relay kept posting into a chat nobody was reading. Silent at both ends: the human saw a healthy connector, and the agent's replies simply vanished.

After this change one of those permanent refusals marks the connector as needing attention, with a named reason on the Connectors page, and relaying stops until the human reconnects.

Classification happens at the call site, by the chat the send targets

sendMessage / postMessage return the provider's own error (error_code + description, or Slack's error string) and decide nothing. The caller classifies, and only when the send it just made went to the chat the connector is bound to:

Site	What it is
telegramBridgeService.ts (3 sends)	relay / escalation sends to config.chatId
decisionCardReconcileService.ts	the decision card's send to config.chatId
routes/webhooks/telegram.ts bind confirmation	the chat this bind just stored — a permanent failure undoes that bind
installables.ts Slack connect marker	the chat this confirm just stored, same shape (wren 73837)

Permanent means the chat is gone, not that the bot had a bad day. Telegram: any 403, or a 400 whose description is chat not found. Slack: channel_not_found, not_in_channel, is_archived. Everything else is content or transient and never flips — including 401 / invalid_auth / token_revoked, which are the shared app credential and would take every connector down with them, and 429/5xx.

The flip is one update matched on {_id, config.chatId: <the failed chat>}: status: error, a named errorMessage, and config.chatId unset. The match is the race guard — if the connector was re-bound between the send and the classification, nothing matches and no stale failure is written. Unsetting is what allows a reconnect (the connect route 409s while a chat id is present) and what stops the Telegram relay, whose predicate reads the chat id and the pause flag only; the Slack relay also filters status, so there it stops twice over.

The flip writes nothing else. An Activity row was in the ruling and wren withdrew it (73792): V2 renders none, so it would have been written and never read. Its absence is pinned by a named test with a positive control, so a future re-add reddens that test by name rather than passing quietly.

A bind is the only thing that proves a connector works again, so it is the only thing that clears errorMessage — both binds now clear it, or a reconnect would keep naming a reason that is no longer true.

Two escape defects in the same surface (separable commits)

• c256bdbf — four values the Telegram webhook route interpolated into HTML under parse_mode: 'HTML': the pod name, the summary title and content, and the lead username. Vera found the class (73812); the tell was that the route hand-escaped a static literal its own author had typed while interpolating the values that arrive.
• 7685ba15 — the Slack escapes, as their own commit (wren 73822): one home beside chat.postMessage (SlackApi.escapeSlackMrkdwn), String(value ?? '') — ?? rather than ||, so a missing value cannot become the literal string "undefined" and 0/false still render as themselves — with slackBridgeService and decisionCardReconcileService importing it back, both escaping after the slice so an escape can never be cut in half. The connect marker's pod name goes through the same helper.

Both are offered to wren as separable if she would rather they land elsewhere; they are in this PR because they are the same surface this row already touches.

A reason is rendered only when it was written for a person (vera 73848)

Vera's hold, and it was not in the code this PR writes — it was in the field this PR promoted to user-facing copy. Integration.errorMessage has a second, older writer: externalFeedService.ts copies a provider's error_description / error / detail / title, or the raw exception message, into it for x and instagram rows, so connect ECONNREFUSED <addr>:443 reaches the same status === 'error' branch — and those rows are on the page as legacy pod-scoped connectors.

The message was never the problem; the inference was. "The field holds a value" is not the fact the page needs — "this value was written for a person" is. That fact now travels with the value: Integration.errorMessageUserFacing, set in exactly one place (connectorDeliveryFailureService, which owns both the classifier's flip and the reconciler's unreadable-secret reason), and required by the page before it renders anything. A writer that does not set it falls back to the generic sentence, so the failure direction is a hidden message, never a printed one — and the provider's own text stays on the row for whoever debugs the feed.

The reconciler's reason ('Slack connector secret key is unavailable') is ours and is written for a person, so it now comes through that service instead of a second $set that could forget the flag. Both binds clear the flag with the message they clear: the field's two states are a state, not a string. externalFeedService says in place why its text is diagnostic.

The reason on the Connectors page (UI hold)

V2ConnectorsPage's error row rendered a fixed sentence; it now renders the server's errorMessage when there is one and keeps that sentence as the fallback.

Evidence from a real browser, 390 and 1200, pairing main against this branch:

• docs/design/evidence/row-d-connector-error-reason-390-{before,after}.png
• docs/design/evidence/row-d-connector-error-reason-1200-{before,after}.png
• the refused-authorize state this row also covers is the existing pair docs/design/evidence/slack-authorize-409/slack-authorize-409-{390,1200}.png (from fix(slack): judge a Slack bind by its secret reference, not an object that is always there #1875)

The three rows in the frame are the two connectors carrying errorMessageUserFacing: true — what a flip writes — and, in the same pod, an x connector in the error state holding connect ECONNREFUSED 10.4.4.7:443 with no flag. That third row is the point: it is what the guard is for, and a frame showing only the happy path would not evidence it.

The innerText diff is exactly the three reason lines at both widths, and nothing else moves:

-The connection dropped.
+Telegram stopped delivering: the bot was blocked or removed from this chat.
-The connection dropped.
+Slack stopped delivering: this channel no longer exists.
-The connection dropped.
+Telegram stopped delivering: the bot was blocked or removed from this chat.

Counted across the same two frames: before 4 × the generic sentence and 0 named reasons; after 1 × generic and 3 × named — the single generic line being that X row, still rendering exactly what it rendered before, with ECONNREFUSED appearing in neither frame at either width.

The viewer is a local reproduction account that owns the pod the two connectors belong to; the errored rows are seeded directly in the dev database (status: error carrying the reason a permanent failure writes), which is the state the flip produces and the API refuses to create. Both frontends talk to the same backend, so the pair differs in the frontend revision only.

That last check is the one the runbook asks for, and the first pass of this pair failed it: cut against 0e142135 it also dropped reconnect to resume and the GitHub row's second line at 390, because this branch predated #1874 restoring those to the phone layout. The artifact was in the base, not in the change — the branch is now cut from f5ded480 and the diff is clean.

Verification

• backend: 432 suites / 4036 tests / 0 failures at an earlier head of this branch (Node 20), re-run in full at this one; lint:ts 0 errors / 1211 warnings — the pre-existing baseline, unchanged
• frontend: V2ConnectorsPage.test.tsx 43/43 (the guard witness is new)
• mutation ledger, each aimed at the path its claim actually takes, each reddening exactly its own witness by name: the Telegram classification and flip (4), the escape class (4), the two closing-line sites re-aimed after the first probe turned out to be mis-aimed (2), the Slack escape and its signature (4), the retired Activity row's positive control (1), the Slack connect marker and the errorMessage: null it clears (2), and the guard's four — the flip stops marking its reason, the reconciler writer stops marking it, the page ignores the flag, and the Telegram bind clears the message but not the flag
• nine test harnesses that stubbed telegramService / slackApi whole now spread jest.requireActual: the network is stubbed, the behaviour stays real. That class was collateral from this branch — a bare stub left the escape undefined, the caller's try/catch swallowed the send, and the failure read "sendMessage was never called"

Two smaller things from vera's 73849, both taken: escapeHtml now takes String(raw ?? ''), matching Slack's escaper, with a witness that an absent value renders as nothing rather than as the literal undefined (unreachable today — every call site pre-guards). And the classifier's docstring now records the one direction it fails in — errorCode/description are read off the axios throw, so a Telegram reply that arrives HTTP 200 with ok: false classifies as null: a missed flip, never a wrong one.

Found while fixing, not folded — row candidate for @connector-ops

The same class sits one field over, in code this PR does not touch: the page's catalog half (V2ConnectorsPage.tsx:814) renders InstallableInstallation.errorMessage, and installableInstallationService.ts:340 writes error.message into it — a raw exception message — beside the reconciler's and the admin pause's constants. Nothing here changes that line, so it belongs in its own row rather than widening this PR.

Gate

Vera is the single gate for this PR (73713) and is asked as such. The frontend half is under a UI hold: connector-ops's look at the frames, then Sam's, before the enqueue. No cli / mcp version slot is needed — nothing published moves.