@open-everywhere/provider-discord 0.6.0 → 0.8.0

package/agent/approvals/discord-admin.ts

@@ -225,3 +225,124 @@ export async function discordAuthorRoles(guildId: string, userId: string, deps:
 export function _resetDiscordAuthorRolesCache(): void {
   roleEvidenceCache.clear();
 }
+
+// --- CAN THIS PERSON READ THIS CHANNEL? (OPE-2534, out-of-office cover) --------------------------------------------
+//
+// The cover recap shows a question only where the covered person could already read it. A relay message carries no
+// permission data, so the answer is Discord's own permission rule over three REST reads: the channel (its overwrites,
+// and its parent for a thread), the guild (its owner and role table) and the member (their roles). FAIL-CLOSED like
+// every check in this file: any failure is "cannot read", so the recap counts the question and shows nothing of it.
+
+/** Discord's `VIEW_CHANNEL` and `ADMINISTRATOR` permission bits. */
+const VIEW_CHANNEL = 1n << 10n;
+const ADMINISTRATOR = 1n << 3n;
+/** A public thread (10 announcement, 11 public) reads as its parent channel. A private thread (12) does not. */
+const PUBLIC_THREAD_TYPES: ReadonlySet<number> = new Set([10, 11]);
+const PRIVATE_THREAD_TYPE = 12;
+
+/** One permission overwrite on a channel. `type` 0 is a role (the @everyone role's id is the guild id), 1 a member. */
+export interface DiscordOverwrite {
+  readonly id: string;
+  readonly type: number;
+  readonly allow: string;
+  readonly deny: string;
+}
+
+/** The facts Discord's permission rule reads. */
+export interface DiscordViewFacts {
+  readonly guildId: string;
+  readonly ownerId?: string;
+  /** Role id → permission bits, as the guild's role table spells them (a decimal string). */
+  readonly rolePermissions: ReadonlyMap<string, string>;
+  readonly userId: string;
+  readonly memberRoleIds: readonly string[];
+  readonly overwrites: readonly DiscordOverwrite[];
+}
+
+function permissionBits(v: string | undefined): bigint {
+  return v !== undefined && /^\d+$/.test(v) ? BigInt(v) : 0n;
+}
+
+/**
+ * Discord's documented permission rule for VIEW_CHANNEL (developer docs, "Permissions" → "Permission Overwrites"),
+ * in its order. The owner and ADMINISTRATOR see everything. Else the base is the @everyone role's bits OR the
+ * member's roles' bits. Then the @everyone overwrite, then the member's role overwrites together, then the member's
+ * own overwrite, each as "deny, then allow". Pure.
+ */
+export function discordCanView(f: DiscordViewFacts): boolean {
+  if (f.ownerId !== undefined && f.ownerId === f.userId) return true;
+  let base = permissionBits(f.rolePermissions.get(f.guildId));
+  for (const r of f.memberRoleIds) base |= permissionBits(f.rolePermissions.get(r));
+  if ((base & ADMINISTRATOR) !== 0n) return true;
+  const everyone = f.overwrites.find((o) => o.type === 0 && o.id === f.guildId);
+  if (everyone) base = (base & ~permissionBits(everyone.deny)) | permissionBits(everyone.allow);
+  let allow = 0n;
+  let deny = 0n;
+  for (const o of f.overwrites) {
+    if (o.type === 0 && o.id !== f.guildId && f.memberRoleIds.includes(o.id)) {
+      allow |= permissionBits(o.allow);
+      deny |= permissionBits(o.deny);
+    }
+  }
+  base = (base & ~deny) | allow;
+  const own = f.overwrites.find((o) => o.type === 1 && o.id === f.userId);
+  if (own) base = (base & ~permissionBits(own.deny)) | permissionBits(own.allow);
+  return (base & VIEW_CHANNEL) !== 0n;
+}
+
+function overwritesOf(channel: Record<string, unknown>): DiscordOverwrite[] {
+  const raw = Array.isArray(channel["permission_overwrites"]) ? (channel["permission_overwrites"] as unknown[]) : [];
+  return raw.flatMap((o) =>
+    isObject(o) && typeof o["id"] === "string" && typeof o["type"] === "number"
+      ? [{ id: o["id"], type: o["type"], allow: String(o["allow"] ?? "0"), deny: String(o["deny"] ?? "0") }]
+      : [],
+  );
+}
+
+/**
+ * Can `userId` read `channelId` in `guildId`, per Discord's own rule ({@link discordCanView})? A public thread reads
+ * as its parent channel. Each of these answers FALSE: a private thread, a channel in another guild, a person who is
+ * not a member (404), a bot account (cover is for people), and every failure. NEVER throws. Not cached: cover asks
+ * only about a person with live cover.
+ */
+export async function discordMemberCanViewChannel(guildId: string, channelId: string, userId: string, deps: DiscordAdminDeps = {}): Promise<boolean> {
+  const token = deps.token ?? process.env.DISCORD_BOT_TOKEN;
+  if (!token || !guildId || !channelId || !userId) return false;
+  const doFetch = deps.fetchFn ?? fetch;
+  const headers = { authorization: `Bot ${token}` };
+  const read = async (path: string): Promise<Record<string, unknown> | undefined> => {
+    const res = await doFetch(`https://discord.com/api/v10/${path}`, { headers });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as unknown;
+    return isObject(body) ? body : undefined;
+  };
+  try {
+    let channel = await read(`channels/${encodeURIComponent(channelId)}`);
+    if (!channel || channel["guild_id"] !== guildId || channel["type"] === PRIVATE_THREAD_TYPE) return false;
+    if (typeof channel["type"] === "number" && PUBLIC_THREAD_TYPES.has(channel["type"])) {
+      const parentId = channel["parent_id"];
+      channel = typeof parentId === "string" ? await read(`channels/${encodeURIComponent(parentId)}`) : undefined;
+      if (!channel || channel["guild_id"] !== guildId) return false;
+    }
+    const guild = await read(`guilds/${encodeURIComponent(guildId)}`);
+    if (!guild) return false;
+    const member = await read(`guilds/${encodeURIComponent(guildId)}/members/${encodeURIComponent(userId)}`);
+    const user = member?.["user"];
+    if (!member || !isObject(user) || user["id"] !== userId || user["bot"] === true) return false;
+    const rolePermissions = new Map<string, string>();
+    for (const r of Array.isArray(guild["roles"]) ? (guild["roles"] as unknown[]) : []) {
+      if (isObject(r) && typeof r["id"] === "string") rolePermissions.set(r["id"], String(r["permissions"] ?? "0"));
+    }
+    return discordCanView({
+      guildId,
+      ...(typeof guild["owner_id"] === "string" ? { ownerId: guild["owner_id"] } : {}),
+      rolePermissions,
+      userId,
+      memberRoleIds: Array.isArray(member["roles"]) ? (member["roles"] as unknown[]).filter((r): r is string => typeof r === "string") : [],
+      overwrites: overwritesOf(channel),
+    });
+  } catch (err) {
+    log(`view check error for guild ${guildId}: ${(err as Error)?.message ?? String(err)}`);
+    return false;
+  }
+}

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, optionsWithoutConfirm, 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,20 +120,17 @@ 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 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 [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,
@@ -146,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,
@@ -165,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"),
           },
         ],
@@ -175,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/approvals/discord-flow.ts

@@ -66,6 +66,7 @@ import {
   type DecisionWakeDeps,
   type ApprovalOutcome,
   type PendingActionRow,
+  CLICK_NOTICE,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import {
   OE_DISCORD_APPROVAL_PREFIX,
@@ -277,7 +278,7 @@ export interface DiscordApprovalDeps {
 export function discordResponseFor(res: ApprovalClickResolution): DiscordInteractionResponse {
   switch (res.outcome) {
     case "unknown":
-      return ephemeral("This approval request is no longer known (it may have already been decided or has aged out).");
+      return ephemeral(CLICK_NOTICE.unknown);
     case "not-pending":
     case "expired-race":
     case "unregistered-kind":
@@ -288,7 +289,7 @@ export function discordResponseFor(res: ApprovalClickResolution): DiscordInterac
       return { type: RESPONSE_UPDATE_MESSAGE, data: { content: card.content, components: card.components } };
     }
     case "denied":
-      return ephemeral("Only a domain/org admin — or a server administrator, for this server's own scopes — can decide this request.");
+      return ephemeral(CLICK_NOTICE.deniedDiscord);
     case "clicker-denied":
       // The clicker gate (OPE-185, core approvals/clicker-floor.ts) — same UX as `denied`: an
       // ephemeral to the clicker alone, card untouched, row still pending.
@@ -357,7 +358,7 @@ export async function handleDiscordApprovalInteraction(raw: unknown, deps: Disco
     if (!click.clickerId) {
       // It WAS ours; fail soft on the click rather than forward a half-understood payload.
       console.error(`[open-everywhere:discord-approvals] component click "${click.customId}" carries no user id — ignoring the click`);
-      return ephemeral("Couldn't read who clicked — this decision was not applied.");
+      return ephemeral(CLICK_NOTICE.noClicker);
     }
     const clickerId = click.clickerId;
 
@@ -395,8 +396,11 @@ export async function handleDiscordApprovalInteraction(raw: unknown, deps: Disco
         return rowGuild ? isGuildAdminViaRest(rowGuild, clickerId) : false;
       },
     });
-    // Decision FEEDBACK (task #106 — Slack click-path parity): a fresh notice beside the card (the
-    // UPDATE_MESSAGE response is an EDIT, invisible to backscroll) + the cross-thread window wake.
+    // Decision FEEDBACK (task #106 — Slack click-path parity): the cross-thread window wake, and a
+    // fresh notice beside the card that states the outcome only when no seat took the wake or a thread
+    // seat or a worker owns the card's channel (the UPDATE_MESSAGE response is an EDIT, invisible to
+    // backscroll; the room never reads the decided line twice, OPE-2473). Otherwise only an asker whom
+    // somebody else answered, or whose request expired, gets one short line (OPE-2490).
     // The wake's guild id comes from the SIGNED interaction (Slack's team.id analogue — the frozen
     // scopeKey can name a different workspace under an explicit-scope override). A DM-context
     // interaction has none, so the core takes the card's mint-frozen DM `postedTo` as the DM seat's
@@ -419,6 +423,10 @@ export async function handleDiscordApprovalInteraction(raw: unknown, deps: Disco
             outcomeLine: "expired",
             executed: "none",
             target: discordDecisionWakeTarget(res.row, click.guildId),
+            // The interaction answer (UPDATE_MESSAGE) edits the card to its decided line.
+            cardShowsOutcome: true,
+            // The notice posts into the card's own channel; a Discord thread IS its channel id.
+            noticeThread: discordDecisionWakeTarget(res.row, click.guildId)?.origin ?? null,
             postNotice: (text) => (deps.postNotice ?? postDiscordDecisionNotice)(res.row, text),
           },
           deps.decisionWake,
@@ -434,6 +442,10 @@ export async function handleDiscordApprovalInteraction(raw: unknown, deps: Disco
             executed: res.executed,
             clickerId,
             target: discordDecisionWakeTarget(res.row, click.guildId),
+            // The interaction answer (UPDATE_MESSAGE) edits the card to its decided line.
+            cardShowsOutcome: true,
+            // The notice posts into the card's own channel; a Discord thread IS its channel id.
+            noticeThread: discordDecisionWakeTarget(res.row, click.guildId)?.origin ?? null,
             postNotice: (text) => (deps.postNotice ?? postDiscordDecisionNotice)(res.row, text),
           },
           deps.decisionWake,
@@ -465,6 +477,6 @@ export async function handleDiscordApprovalInteraction(raw: unknown, deps: Disco
     // Genuinely unexpected (store outage, …) after we'd established this WAS our click —
     // fail soft with an honest ephemeral note; never throw out of the interactions path.
     console.error(`[open-everywhere:discord-approvals] click handling failed softly for "${click.customId}": ${String(err)}`);
-    return ephemeral("Something went wrong handling this click — the decision was not applied.");
+    return ephemeral(CLICK_NOTICE.failed);
   }
 }

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-dispatch-target.ts

@@ -12,13 +12,14 @@
 import type {
   Routine,
   DispatchTarget,
+  RoutineTestRunArm,
   DeclaredTargetResolution,
   DeclaredTargetSpec,
   SessionMode,
   UnifiedWakeOrigin,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import discord from "./discord.js";
-import { discordOpenDmChannel } from "./discord-post.js";
+import { discordOpenDmChannel, discordPostMessage } from "./discord-post.js";
 import { fetchDiscordInfo } from "./discord-channel-info.js";
 
 /** One stored-target field as a non-empty string, or undefined (never a coerced non-string — the
@@ -162,3 +163,37 @@ export async function resolveDiscordDeclaredTarget(
   }
   return { ok: true, facts: { surfaceKey: `discord/${spec.principalId}/${channelId}`, target: { channelId, channelType: "1" } } };
 }
+
+/** The channel a resolved Discord target posts into, or undefined. */
+function targetChannelId(dest: DispatchTarget): string | undefined {
+  const v = (dest.target as { channelId?: unknown }).channelId;
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * THE DISCORD TEST-RUN ARM (OPE-2540, core routines/test-run.ts). A test needs a session of its own,
+ * and Discord has no thread ts to key one on. eve's Discord channel keys a session on
+ * `(channelId, conversationId)` (`discordContinuationToken`), and a proactive fire with no
+ * `conversationId` keys on the channel alone, which is the room's own session. So the arm posts the
+ * test's opening message and fires with that message's id as the `conversationId`: a session of its
+ * own, in the routine's own channel.
+ *
+ * The opening post, the run's answer and the summary all land in the routine's channel. The summary is
+ * a Discord REPLY to the opening post (`message_reference`), so it shows which test it closes.
+ * The fire's bag is unchanged, so the test binds to the routine's own channel and guild.
+ *
+ * Not a Discord thread: a thread is its own channel id, and bindDiscord would then bind the test to a
+ * different surface than the routine's.
+ */
+export const discordTestRunArm: RoutineTestRunArm = {
+  post: async (dest, text, anchor) => {
+    const channelId = targetChannelId(dest);
+    if (channelId === undefined) return undefined;
+    try {
+      return await discordPostMessage(channelId, text, anchor !== undefined ? { replyToMessageId: anchor } : undefined);
+    } catch {
+      return undefined;
+    }
+  },
+  target: (dest, anchor) => ({ channelId: targetChannelId(dest) ?? "", conversationId: anchor }),
+};

package/agent/channels/discord-events.ts

@@ -30,6 +30,7 @@
 import { POST, type Channel, type RouteHandlerArgs } from "eve/channels";
 import { verifyDiscordInteraction } from "./discord-front.js";
 import { appendAudit, deploymentOrg } from "@open-everywhere/core/agent/adapter-api.js";
+import type { AuditDetail } from "@open-everywhere/core/agent/adapter-api.js";
 
 /** The public URL to paste into the app's developer-portal **Webhooks** page (NOT the
  *  Interactions Endpoint URL, which stays {@link PUBLIC_DISCORD_ROUTE}). */
@@ -48,7 +49,7 @@ function elog(msg: string): void {
  *  all of which still get Discord's required 204. */
 export type DiscordEventDecision =
   | { readonly kind: "ack"; readonly reason: string }
-  | { readonly kind: "audit"; readonly action: string; readonly workspace: string; readonly principalId?: string; readonly detail: Record<string, unknown> };
+  | { readonly kind: "audit"; readonly action: string; readonly workspace: string; readonly principalId?: string; readonly detail: AuditDetail };
 
 function str(v: unknown): string | undefined {
   return typeof v === "string" && v.length > 0 ? v : undefined;
@@ -118,7 +119,7 @@ export interface DiscordEventsOptions {
   readonly publicKey?: string;
   readonly now?: () => number;
   /** Audit writer (defaults to the real appendAudit under the deployment org). */
-  readonly audit?: (row: { action: string; workspace: string; principalId?: string; detail: Record<string, unknown> }) => Promise<void>;
+  readonly audit?: (row: { action: string; workspace: string; principalId?: string; detail: AuditDetail }) => Promise<void>;
 }
 
 /** Discord requires an EMPTY 204 body for both the PING and every event, within 3 seconds. */

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" } });
 }
 
 /**