@open-everywhere/provider-discord 0.5.0 → 0.7.0

package/agent/approvals/discord-card.ts

@@ -6,8 +6,8 @@
 //
 // Discord's card idiom differs from Slack's in three load-bearing ways, all handled here:
 //   - No blocks: the card body is one Markdown `content` string; buttons ride a components
-//     ACTION_ROW. (Discord caps `content` at 2000 chars — summary lines are short
-//     code-rendered fragments, far under it.)
+//     ACTION_ROW. (Discord caps `content` at 2000 chars — a card is a few short lines
+//     of short code-rendered text, far under it.)
 //   - No per-button `value` slot: Slack carries the org in the button's `value`; Discord's
 //     ONLY payload carrier is the `custom_id`, so the org rides there too (same frozen-org
 //     doctrine, different envelope). custom_id is capped at 100 chars — enforced below.
@@ -19,7 +19,16 @@
 // that already ran, carrying the one "This should not have run" button and never a decision one.
 
 import type { CardOptionTone, PendingActionRow } from "@open-everywhere/core/agent/adapter-api.js";
-import { approvalLabel, pendingCardLayout, plainSummaryForRow } from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  cardFooter,
+  decidedCardLine,
+  footerRequester,
+  JUDGE_LIFT_BUTTON,
+  judgeLiftLines,
+  optionsWithoutConfirm,
+  pendingCardLayout,
+  pendingCardLines,
+} from "@open-everywhere/core/agent/adapter-api.js";
 
 /**
  * Every approval button custom_id this feature owns starts with this. Deliberately distinct
@@ -111,21 +120,19 @@ export function parseDiscordApprovalCustomId(customId: string): { id: string; de
   return { id, decision: decision as DiscordApprovalDecision, org };
 }
 
-/** The shared card body: the plain sentence first (OPE-2434), then the `Approval requested: <kind>` label, the summary and the provenance. `<@id>` is Discord's user-mention syntax too, so the requester line reads identically to the Slack card. The sentence went through core's `plainValue`, so it carries no markdown of its own. */
-function cardBody(row: PendingActionRow, summaryLines: readonly string[], footer: string): string {
-  return [`**${plainSummaryForRow(row)}**`, `-# ${approvalLabel(row.kind)}`, ...summaryLines, footer].join("\n");
-}
-
 const OPTION_STYLE: Record<CardOptionTone, number> = { primary: BUTTON_STYLE_SUCCESS, danger: BUTTON_STYLE_DANGER, neutral: BUTTON_STYLE_SECONDARY };
 
 /**
- * The card for a still-pending action: the plain sentence, the summary, "requested by / expires", and one button per layout option, each carrying the pending id + org in its custom_id (see the file header for why the org rides the custom_id on Discord). Mirrors card.ts's pendingCardBlocks.
- * The OPTIONS come from core's card layout (OPE-53, OPE-2363: only a ROUTINE's card gets the middle grant button), so Slack, Teams and Discord can never disagree, and OPE-2456's extra option lands here with no change.
+ * The card for a still-pending action (OPE-2481): the headline in bold, at most one consequence line, a warning when the proposal was tainted, the small footer, and one button per layout option, each carrying the pending id + org in its custom_id (see the file header for why the org rides the custom_id on Discord). The kind never appears: Discord has no hidden metadata slot, so the kind lives on the row the custom_id names. Mirrors card.ts's pendingCardBlocks.
+ * The OPTIONS come from core's card layout (OPE-53, OPE-2363: only a ROUTINE's card gets the middle grant button), so Slack, Teams and Discord can never disagree. OPE-2456's rule option needs a confirmation before the click, which a Discord button cannot show, so it is left out.
+ * The headline and the consequence went through core's `plainValue`, so they carry no markdown of their own. `<@id>` is Discord's user-mention syntax too, so the footer reads as the Slack card's does.
  */
 export function pendingDiscordCard(row: PendingActionRow, summaryLines: readonly string[]): DiscordCardMessage {
   const layout = pendingCardLayout(row, summaryLines);
-  const content = cardBody(row, summaryLines, `-# Requested by <@${layout.requestedBy}> · ${layout.expiry}`);
-  const buttons: DiscordComponent[] = layout.options.map((o) => ({
+  const [headline, ...rest] = pendingCardLines(layout);
+  const content = [`**${headline}**`, ...rest, `-# ${cardFooter(footerRequester(row, "discord"), layout.expiry)}`].join("\n");
+  // A Discord button sends its click with no confirmation first, so the rule option (OPE-2456) is left out here.
+  const buttons: DiscordComponent[] = optionsWithoutConfirm(layout.options).map((o) => ({
     type: COMPONENT_BUTTON,
     style: OPTION_STYLE[o.tone],
     label: o.label,
@@ -145,18 +152,18 @@ export function pendingDiscordCard(row: PendingActionRow, summaryLines: readonly
  * `approval.judge.contradicted` row the contradiction breaker counts.
  *
  * NOT AN APPROVAL CARD, and the render says so: no Approve, no Reject, no expiry line. The act is
- * already done, so this is a review surface, not a decision surface. It deliberately does NOT reuse
- * `cardBody` — that helper's header reads "Approval requested", which is the one thing this message
- * must never say.
+ * already done, so this is a review surface, not a decision surface.
  *
- * THE COPY IS THE SLACK COPY, word for word (the header, the ⚡ line, the button label). Two rooms
- * on two platforms must not be told different things about the same mechanism; only the envelope
- * differs — Markdown `content` + a components row, rather than blocks.
+ * THE COPY IS THE SLACK COPY, word for word (core's `judgeLiftHeadline`, `judgeLiftOutcome` and
+ * `JUDGE_LIFT_BUTTON`). Two rooms on two platforms must not be told different things about the same
+ * mechanism; only the envelope differs — Markdown `content` + a components row, rather than blocks.
+ * Two lines and the button (OPE-2481): the headline names the act in plain words, never its kind.
  */
-export function judgeLiftNoticeDiscordCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): DiscordCardMessage {
-  const context = `-# ⚡ Auto-approved by the approval judge — no card was posted and this has already run · ${outcomeLine}`;
+export function judgeLiftNoticeDiscordCard(row: PendingActionRow, _summaryLines: readonly string[], outcomeLine: string): DiscordCardMessage {
   return {
-    content: [`**Ran without asking: ${row.kind}**`, ...summaryLines, context].join("\n"),
+    content: judgeLiftLines(row, outcomeLine)
+      .map((line, i, all) => (i === 0 ? `**${line}**` : i === all.length - 1 ? `-# ${line}` : line))
+      .join("\n"),
     components: [
       {
         type: COMPONENT_ACTION_ROW,
@@ -164,7 +171,7 @@ export function judgeLiftNoticeDiscordCard(row: PendingActionRow, summaryLines:
           {
             type: COMPONENT_BUTTON,
             style: BUTTON_STYLE_DANGER,
-            label: "This should not have run",
+            label: JUDGE_LIFT_BUTTON,
             custom_id: buildDiscordApprovalCustomId(row, "contradict"),
           },
         ],
@@ -174,25 +181,13 @@ export function judgeLiftNoticeDiscordCard(row: PendingActionRow, summaryLines:
 }
 
 /**
- * The card once a decision has landed: SAME summary, buttons GONE (`components: []` — the
- * type-7 UPDATE_MESSAGE response replaces the whole message, so an empty row strips them),
- * plus a context line naming who decided + the outcome. Renders whatever the caller already
- * CAS-decided — this function never decides anything (mirrors card.ts's decidedCardBlocks,
- * including the same three status lines).
+ * The card once a decision has landed: ONE line (OPE-2481), buttons GONE (`components: []` — the
+ * type-7 UPDATE_MESSAGE response replaces the whole message, so an empty row strips them). The line is
+ * core's `decidedCardLine`, so it reads exactly as the Slack card's does, including a durable
+ * decline's line. Renders whatever the caller already CAS-decided — this function never decides anything.
  */
-export function decidedDiscordCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): DiscordCardMessage {
-  const decidedContext =
-    row.status === "approved"
-      ? `✅ Approved by <@${row.decidedBy}> · ${outcomeLine}`
-      : row.status === "rejected"
-        ? // A kind whose DECLINE is itself durable returns a line saying what the decline recorded
-          // (approvals/types.ts ActionKind.declined). Every other kind's reject passes the literal
-          // "rejected" and renders byte-for-byte what it always did. Kept in step with card.ts's
-          // decidedCardBlocks by hand, exactly like the three status lines above it — a Discord card
-          // that dropped the line would leave a clicker believing a decline was remembered.
-          `❌ Rejected by <@${row.decidedBy}>${outcomeLine === "rejected" ? "" : ` · ${outcomeLine}`}`
-        : "⏰ Expired";
-  return { content: cardBody(row, summaryLines, decidedContext), components: [] };
+export function decidedDiscordCard(row: PendingActionRow, _summaryLines: readonly string[], outcomeLine: string): DiscordCardMessage {
+  return { content: decidedCardLine(row, outcomeLine, `<@${row.decidedBy}>`), components: [] };
 }
 
 /** Discord's ADMINISTRATOR permission bit (0x8). https://discord.com/developers/docs/topics/permissions */

package/agent/channels/discord-channel-info.ts

@@ -1,16 +1,18 @@
-// Shared Discord channel-info lookup — `GET /channels/{id}` (and `GET /guilds/{id}`)
-// via the bot token, cached per id. ONE impl + ONE cache for the two consumers that
+// Shared Discord channel-info lookup — `GET /channels/{id}` (and `GET /guilds/{id}`, `GET /users/{id}`)
+// via the bot token, cached per id. ONE impl + ONE cache for the three consumers that
 // need the same facts:
 //   - approvals/scope-label.ts — friendly card labels ("#parent · thread \"…\"");
 //   - channels/discord-gateway.ts — thread→parent grain resolution (backlog item 22):
 //     a Discord thread is its OWN channel id, so domain/spend grain must resolve the
-//     PARENT channel or a thread silently falls out of its channel's domain and cap.
+//     PARENT channel or a thread silently falls out of its channel's domain and cap;
+//   - channels/discord-friendly-names.ts — the friendly-names guard's resolver (OPE-2482): a raw
+//     snowflake in text a person reads renders as a channel, server or person name.
 //
 // FAIL-OPEN BY CONTRACT: every failure (no token, non-ok status, network error,
 // malformed body) resolves `undefined` — the caller degrades (raw key on a card,
 // thread-grain accounting on the gateway), never blocks or throws. The bot token is a
-// SECRET — header only, never logged. Verdicts (including some failures — see the
-// cache note) are cached in-process; a serverless instance pays each lookup once.
+// SECRET — header only, never logged. Definitive verdicts are cached in-process (see the
+// cache note); a transient failure is asked again.
 
 /** The channel facts both consumers read. `parentId` is set ONLY for threads. */
 export interface DiscordChannelInfo {
@@ -22,6 +24,8 @@ export interface DiscordChannelInfo {
    *  Read by the declared-target resolver (OPE-2419) to confirm a configured `discord/<guild>/<channel>`
    *  names a channel that really is in that guild. */
   readonly guildId?: string;
+  /** A USER lookup's `username`: the handle Discord keeps unique (OPE-2482). Absent for a channel or guild. */
+  readonly handle?: string;
 }
 
 /** Injectable seams (tests swap both; live callers pass nothing). */
@@ -30,12 +34,14 @@ export interface DiscordInfoDeps {
   readonly token?: string;
 }
 
-// Promise-cached per `kind:id` — concurrent callers share one in-flight request, and a
-// settled result (including `undefined` from a hard failure) is kept for the instance's
-// life: names/parents change on admin edits, not per message, and the pre-extraction
-// scope-label cache behaved exactly this way (a card propose + its decided re-render
-// must not pay twice).
+// Promise-cached per `kind:id` — concurrent callers share one in-flight request. A DEFINITIVE
+// settled result (a name, a 404, no token) is kept, up to INFO_CACHE_MAX ids, because
+// names/parents change on admin edits, not per message (a card propose + its decided
+// re-render must not pay twice). A TRANSIENT failure (429, 5xx, a network error) is dropped
+// once it settles, so the next caller asks again.
 const infoCache = new Map<string, Promise<DiscordChannelInfo | undefined>>();
+/** The most verdicts the cache holds; the oldest goes first. */
+const INFO_CACHE_MAX = 2000;
 
 /** Test hook: drop every cached verdict (unit suites re-run lookups with fresh fakes). */
 export function clearDiscordInfoCacheForTest(): void {
@@ -43,13 +49,18 @@ export function clearDiscordInfoCacheForTest(): void {
 }
 
 export function fetchDiscordInfo(
-  kind: "channels" | "guilds",
+  kind: "channels" | "guilds" | "users",
   id: string,
   deps: DiscordInfoDeps = {},
 ): Promise<DiscordChannelInfo | undefined> {
   const key = `${kind}:${id}`;
   let p = infoCache.get(key);
   if (!p) {
+    // A TRANSIENT failure (a 429, a 5xx, a network error) is NOT kept (OPE-2482): the friendly-names
+    // resolver now looks ids up on the post path, and a cached rate-limit miss would otherwise drop a
+    // thread out of its parent's grain for the instance's life. A definitive answer — a found name, a
+    // 404, no token — is kept.
+    let transient = false;
     p = (async () => {
       const token = deps.token ?? process.env.DISCORD_BOT_TOKEN;
       if (!token) return undefined;
@@ -58,21 +69,38 @@ export function fetchDiscordInfo(
         const res = await doFetch(`https://discord.com/api/v10/${kind}/${id}`, {
           headers: { authorization: `Bot ${token}` },
         });
-        if (!res.ok) return undefined;
-        const body = (await res.json()) as { name?: unknown; parent_id?: unknown; type?: unknown; guild_id?: unknown };
-        const name = typeof body.name === "string" && body.name.trim() ? body.name.trim() : undefined;
+        if (!res.ok) {
+          transient = res.status === 429 || res.status >= 500;
+          return undefined;
+        }
+        const body = (await res.json()) as { name?: unknown; parent_id?: unknown; type?: unknown; guild_id?: unknown; global_name?: unknown; username?: unknown };
+        // A user carries no `name`: its display name is `global_name`, else its `username` (OPE-2482).
+        const pick = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+        const name = kind === "users" ? (pick(body.global_name) ?? pick(body.username)) : pick(body.name);
         const isThread = body.type === 10 || body.type === 11 || body.type === 12;
         const parentId = isThread && typeof body.parent_id === "string" && body.parent_id ? body.parent_id : undefined;
         // A nameless channel resolves undefined wholesale — kept from the original
         // scope-label impl (its callers require the name), and harmless for the grain
         // consumer: every real guild channel/thread carries a name.
         const guildId = kind === "channels" && typeof body.guild_id === "string" && body.guild_id ? body.guild_id : undefined;
-        return name ? { name, parentId, isThread, ...(guildId ? { guildId } : {}) } : undefined;
+        const handle = kind === "users" ? pick(body.username) : undefined;
+        return name ? { name, parentId, isThread, ...(guildId ? { guildId } : {}), ...(handle ? { handle } : {}) } : undefined;
       } catch {
+        transient = true;
         return undefined;
       }
     })();
+    const settled = p;
+    void settled.then(() => {
+      if (transient && infoCache.get(key) === settled) infoCache.delete(key);
+    });
     infoCache.set(key, p);
+    // Bounded: the oldest verdict goes first once the cache holds INFO_CACHE_MAX ids.
+    while (infoCache.size > INFO_CACHE_MAX) {
+      const oldest = infoCache.keys().next().value;
+      if (oldest === undefined) break;
+      infoCache.delete(oldest);
+    }
   }
   return p;
 }

package/agent/channels/discord-friendly-names.ts

@@ -0,0 +1,28 @@
+// discord-friendly-names — the Discord name resolver for the friendly-names guard (OPE-2482).
+//
+// A Discord id is a bare snowflake: the same 17-to-20-digit shape names a channel, a server and a
+// person, so the text alone cannot say which. This resolver asks in that order — `GET /channels/{id}`,
+// then `GET /guilds/{id}`, then `GET /users/{id}` — through the one cached lookup
+// (`discord-channel-info.ts`), and the first that answers names the id. A channel answers `#name`, which
+// the guard uses only off Discord: on Discord a channel renders as the native `<#id>` mention. Every
+// failure answers undefined, and the id then renders as plain words, never as itself.
+
+import type { FriendlyNameResolver } from "@open-everywhere/core/agent/adapter-api.js";
+import { fetchDiscordInfo, type DiscordChannelInfo } from "./discord-channel-info.js";
+
+/** The lookup the resolver uses. Live code passes none; a test injects it. */
+export type DiscordInfoLookup = (kind: "channels" | "guilds" | "users", id: string) => Promise<DiscordChannelInfo | undefined>;
+
+/** Build the Discord resolver. */
+export function discordFriendlyNameResolver(lookup: DiscordInfoLookup = (kind, id) => fetchDiscordInfo(kind, id)): FriendlyNameResolver {
+  return async (id) => {
+    if (!/^\d{17,20}$/.test(id)) return undefined;
+    const channel = await lookup("channels", id);
+    if (channel?.name) return { label: `#${channel.name}`, kind: "channel" };
+    const guild = await lookup("guilds", id);
+    if (guild?.name) return { label: guild.name, kind: "server" };
+    const user = await lookup("users", id);
+    if (user?.name) return { label: user.name, kind: "person" };
+    return undefined;
+  };
+}

package/agent/channels/discord-front.ts

@@ -33,7 +33,7 @@ import { POST, type Channel, type HttpRouteDefinition, type RouteHandlerArgs } f
 import { verifyDiscordSignature } from "eve/channels/discord";
 import { OE_DISCORD_APPROVAL_PREFIX } from "../approvals/discord-card.js";
 import { handleDiscordApprovalInteraction, type DiscordInteractionResponse } from "../approvals/discord-flow.js";
-import { LINK_CONSENT_CLICK_PREFIX, OE_GRANT_ACTION_PREFIX } from "@open-everywhere/core/agent/adapter-api.js";
+import { LINK_CONSENT_CLICK_PREFIX, OE_GRANT_ACTION_PREFIX, friendlyDiscordBody } from "@open-everywhere/core/agent/adapter-api.js";
 import { handleDiscordLinkConsentInteraction } from "../identity/discord-link-consent.js";
 import { handleDiscordGrantCardInteraction } from "../access/discord-grant-click.js";
 import { oeCommandName, type AttachSessionForCancel } from "@open-everywhere/core/agent/adapter-api.js";
@@ -205,8 +205,12 @@ export interface DiscordFrontOptions {
   readonly handleOeCommand?: (raw: unknown, attachSession?: AttachSessionForCancel) => Promise<DiscordInteractionResponse | null>;
 }
 
-function interactionJson(body: DiscordInteractionResponse): Response {
-  return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+/** An interaction answer. It renders through the friendly-names guard (OPE-2482): a click's reply and
+ *  a card's re-render are text a person reads, and they leave this host here, not through `discordFetch`.
+ *  It renders with NO name lookup: Discord drops an answer that misses its three-second window, and a
+ *  click has already spent part of it, so the answer takes channel mentions and plain words. */
+async function interactionJson(body: DiscordInteractionResponse): Promise<Response> {
+  return new Response(JSON.stringify(await friendlyDiscordBody(body, { lookup: false })), { status: 200, headers: { "content-type": "application/json" } });
 }
 
 /**

package/agent/channels/discord-gateway.ts

@@ -54,7 +54,7 @@ import { threadParentChannelId } from "./discord-channel-info.js";
 import { splitForDiscord } from "./discord-post.js";
 import { discordFetch, type DiscordFetchDeps } from "./discord-rest.js";
 import { RateLimitExhaustedError, type RetryPolicy } from "@open-everywhere/core/agent/adapter-api.js";
-import { withEndsTurnFinalChannel } from "@open-everywhere/core/agent/adapter-api.js";
+import { TURN_FAILED_TEXT, withEndsTurnFinalChannel } from "@open-everywhere/core/agent/adapter-api.js";
 import {
   finalMessageAction,
   nameDropPattern,
@@ -3114,10 +3114,8 @@ export default withEndsTurnFinalChannel(defineChannel<DiscordGatewayState, Disco
       openTypingGate(channel.channelId); // turn over — never leak a closed gate into the next
       const detail = (data as { error?: { message?: string } } | undefined)?.error?.message;
       log(`turn failed (channel ${channel.channelId || "?"})${detail ? `: ${detail}` : ""}`);
-      await postDiscordReply(
-        channel.channelId,
-        "⚠️ I hit an error while handling that and couldn't finish. Please try again — and if it keeps failing, check the deployment logs.",
-      );
+      // OPE-2486 — the person reads one plain line; the error detail stays in the log line above.
+      await postDiscordReply(channel.channelId, `⚠️ ${TURN_FAILED_TEXT}`);
     },
     // Deliver the turn's final reply back to Discord AND reconcile the 👀→✅ swap (auto-threaded
     // mentions only). finalMessageAction (the shared, unit-tested decision slack-events.ts owns)

package/agent/channels/discord-rest.ts

@@ -29,7 +29,38 @@
 // `POST /channels/{id}/messages`) that rides the NAMED `RateLimitExhaustedError`; keep ids out of it,
 // so every field on that error stays safe to log.
 
-import { withRetryAfter, type RetryPolicy } from "@open-everywhere/core/agent/adapter-api.js";
+import { friendlyDiscordBody, withRetryAfter, type RetryPolicy } from "@open-everywhere/core/agent/adapter-api.js";
+
+/**
+ * THE FRIENDLY-NAMES GUARD (OPE-2482). A message write (create, edit, webhook or interaction follow-up)
+ * renders every raw id in its content, embeds and component labels as a mention, a name or plain words
+ * before it leaves. A JSON string body and a multipart `payload_json` are both covered; any other
+ * operation, and a body this cannot parse, goes out unchanged.
+ */
+async function friendlyDiscordInit(operation: string, init: RequestInit): Promise<RequestInit> {
+  if (!/^(?:POST|PATCH) /.test(operation) || !/\/messages\b|\/callback\b|^POST \/webhooks\//.test(operation)) return init;
+  const render = async (json: string): Promise<string | undefined> => {
+    try {
+      return JSON.stringify(await friendlyDiscordBody(JSON.parse(json) as unknown));
+    } catch {
+      return undefined;
+    }
+  };
+  if (typeof init.body === "string") {
+    const body = await render(init.body);
+    return body === undefined ? init : { ...init, body };
+  }
+  if (init.body instanceof FormData) {
+    const payload = init.body.get("payload_json");
+    if (typeof payload !== "string") return init;
+    const body = await render(payload);
+    if (body === undefined) return init;
+    const form = new FormData();
+    for (const [k, v] of init.body.entries()) form.append(k, k === "payload_json" ? body : v);
+    return { ...init, body: form };
+  }
+  return init;
+}
 
 /** The provider surface name on the NAMED rate-limit failure. */
 export const DISCORD_SURFACE = "discord";
@@ -75,7 +106,9 @@ export async function discordBodyRetryAfterMs(res: Response): Promise<number | u
  * applied).
  */
 export function discordFetch(operation: string, url: string, init: RequestInit, deps: DiscordFetchDeps = {}): Promise<Response> {
-  const send = (): Promise<Response> => (deps.fetch ?? (globalThis.fetch as DiscordFetchLike))(url, init);
+  // The guarded body is computed once and re-sent unchanged by every retry.
+  const guarded = friendlyDiscordInit(operation, init);
+  const send = async (): Promise<Response> => (deps.fetch ?? (globalThis.fetch as DiscordFetchLike))(url, await guarded);
   return withRetryAfter(send, {
     surface: DISCORD_SURFACE,
     operation,

package/agent/commands/discord-commands.ts

@@ -26,6 +26,7 @@
 // channels/discord-front.ts's classifyDiscordInteraction.
 
 import {
+  commandFailureText,
   bindFrom,
   MODEL_AB_RATING_MAX,
   MODEL_AB_RATING_MIN,
@@ -124,7 +125,7 @@ export function parseDiscordOeCommandOptions(rawOptions: unknown): OeCommand {
     if (score === undefined || !Number.isInteger(score) || score < MODEL_AB_RATING_MIN || score > MODEL_AB_RATING_MAX) {
       return {
         kind: "error",
-        message: `"${oeSlash("rate")}" needs a whole "score" from ${MODEL_AB_RATING_MIN} to ${MODEL_AB_RATING_MAX} (got ${JSON.stringify(scoreOpt?.value)}).`,
+        message: `Rate with a whole number from ${MODEL_AB_RATING_MIN} to ${MODEL_AB_RATING_MAX}, for example \`${oeSlash("rate 4")}\`.`,
       };
     }
     return { kind: "rate", score };
@@ -140,14 +141,14 @@ export function parseDiscordOeCommandOptions(rawOptions: unknown): OeCommand {
       if (usd === undefined || usd <= 0) {
         return {
           kind: "error",
-          message: `"${oeSlash("budget raise")}" needs a positive "usd" amount (got ${JSON.stringify(usdOpt?.value)}).`,
+          message: `Add an amount in dollars, for example \`${oeSlash("budget raise 25")}\`.`,
         };
       }
       return { kind: "budget-raise", usd };
     }
-    return { kind: "error", message: `Unknown "budget" subcommand "${subName}".` };
+    return { kind: "error", message: `I don't know "${subName}". Try \`${oeSlash("budget")}\`, \`${oeSlash("budget raise 25")}\` or \`${oeSlash("budget clear")}\`.` };
   }
-  return { kind: "error", message: `Unknown "${oeSlash()}" subcommand "${name ?? "?"}" — try "${oeSlash("help")}".` };
+  return { kind: "error", message: `I don't know "${name ?? "that"}". Try \`${oeSlash("help")}\` to see what I can do.` };
 }
 
 interface ParsedOeInvocation {
@@ -174,11 +175,11 @@ export function parseOeCommandInteraction(raw: unknown): ParsedOeInvocation | {
   const userId = (memberUser ? str(memberUser["id"]) : undefined) ?? (user ? str(user["id"]) : undefined);
   const isBot = memberUser?.["bot"] === true || user?.["bot"] === true;
   if (!userId || isBot) {
-    return { error: "Couldn't identify who invoked this — commands can't be run by a bot." };
+    return { error: "Only a person can use this command." };
   }
   const channelId = str(raw["channel_id"]);
   if (!channelId) {
-    return { error: "Couldn't resolve this channel's id — try again from a real channel or DM." };
+    return { error: "I can't do that here. Try it in a channel or a direct message." };
   }
   const guildId = str(raw["guild_id"]);
   const channelType = channelTypeFromRaw(raw);
@@ -212,12 +213,11 @@ export async function handleDiscordOeCommandInteraction(
     const text = await runOeCommand(parsed.command, binding, attachSession ? { attachSession } : {});
     return ephemeral(text);
   } catch (err) {
-    // runOeCommand's budget-raise/clear branches can throw a user-facing validation error
-    // (e.g. "propose from a DM needs an explicit scope") — surface it verbatim; anything else
-    // (a genuinely unexpected store/network failure) gets a generic fail-soft note. Either way,
-    // never throw out of this function.
+    // A PersonFacingError renders as-is; anything else (a store or network failure, a planner's
+    // model-facing refusal) renders the generic line, and its message goes to the log only
+    // (OPE-2486). Either way, never throw out of this function.
     console.error(`[open-everywhere:discord-commands] "${oeSlash()}" command failed softly: ${String(err)}`);
-    return ephemeral(`Couldn't complete that: ${err instanceof Error ? err.message : String(err)}`);
+    return ephemeral(commandFailureText(err));
   }
 }