@open-everywhere/provider-discord 0.1.0

package/agent/approvals/discord-admin.ts

@@ -0,0 +1,227 @@
+// Discord guild STANDING via REST — admin ({@link isGuildAdminViaRest}) and plain membership
+// ({@link isGuildMemberViaRest}).
+//
+// ADMIN — for the two places a click/message payload
+// CANNOT answer "is this user an administrator of that guild":
+//   - an approval-card click in a DM (Discord DM interactions carry no `member`, so
+//     the payload leg in discord-flow.ts is structurally dead there — and the DM is
+//     the documented escape hatch for an over-budget channel, so it MUST be decidable)
+//   - the spend-cap admin bypass on the ambient gateway (a relay MESSAGE_CREATE has no
+//     computed permissions field)
+// In both cases the guild is known from OUR OWN data (a frozen scopeKey / a partition
+// surfaceKey), never from the untrusted payload.
+//
+// MEMBERSHIP — the approval clicker-floor gate (core access/native-admin.ts, OPE-303). Core's gate
+// used to end at `platform === "slack"` on the belief that "Discord has no per-user membership
+// machinery"; the member lookup below was already here, doing half the admin check's work, and its
+// 404 IS the not-a-member answer. Registered through core's `registerNativeMemberCheck` seam so the
+// vendor call stays in this bundle.
+//
+// FAIL-CLOSED throughout: both answer an AUTHORITY question, so any failure — no
+// token, unknown guild (including a DM-bucket "discord/<userId>" pseudo-workspace,
+// whose guild lookup 404s), missing member, network error, malformed body — is the
+// NEGATIVE verdict ("not an admin" / "not a member"), never a guess. The bot token is
+// a SECRET — header only, never logged.
+
+import { isGuildAdministrator } from "./discord-card.js";
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:discord-admin] ${msg}`);
+}
+
+/**
+ * The guild segment of a Discord scope/surface key — `discord/<guild>` or
+ * `discord/<guild>/<surface>` → `<guild>`; anything else (other platforms, malformed)
+ * → undefined. NOTE: a Discord DM binds workspace to the USER id (identity/binding.ts),
+ * so a DM-scoped key parses "successfully" here — the REST lookup then fails (it isn't
+ * a guild) and the check stays fail-closed. Pure.
+ */
+export function guildIdFromScopeKey(scopeKey: string): string | undefined {
+  const parts = scopeKey.split("/");
+  return parts[0] === "discord" && parts[1] ? parts[1] : undefined;
+}
+
+/** Injectable seams so the check is unit-tested without a live token or network. */
+export interface DiscordAdminDeps {
+  readonly fetchFn?: typeof fetch;
+  readonly token?: string;
+  readonly nowMs?: number;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+// Verdicts (positive AND negative) are cached briefly: the gateway bypass check can run
+// on every message in an over-budget engaged channel, and two REST calls per message is
+// silly for an answer that changes on role edits, not messages. 60s keeps a demotion
+// honest-enough while absorbing message bursts. In-process — a cold serverless instance
+// just pays the two calls once.
+const verdictCache = new Map<string, { verdict: boolean; at: number }>();
+const VERDICT_TTL_MS = 60_000;
+/** Membership verdicts cache separately from admin ones — same key space, different question, and
+ *  collapsing them would let "is a member" satisfy a caller that asked "is an admin". */
+const memberVerdictCache = new Map<string, { verdict: boolean; at: number }>();
+
+/**
+ * Is `userId` an administrator of `guildId`, per Discord itself? True when they OWN the
+ * guild (`guild.owner_id`) or hold any role whose permissions carry ADMINISTRATOR (the
+ * same bit test the click-payload leg uses — isGuildAdministrator). Two REST calls:
+ * `GET /guilds/{id}` (owner + the role table) and `GET /guilds/{id}/members/{userId}`
+ * (the user's role ids). NEVER throws; every failure is `false` (see the file header).
+ */
+export async function isGuildAdminViaRest(guildId: string, userId: string, deps: DiscordAdminDeps = {}): Promise<boolean> {
+  const token = deps.token ?? process.env.DISCORD_BOT_TOKEN;
+  if (!token || !guildId || !userId) return false;
+  const cacheKey = `${guildId}:${userId}`;
+  const now = deps.nowMs ?? Date.now();
+  const hit = verdictCache.get(cacheKey);
+  if (hit && now - hit.at < VERDICT_TTL_MS) return hit.verdict;
+
+  const doFetch = deps.fetchFn ?? fetch;
+  const headers = { authorization: `Bot ${token}` };
+  const verdict = await (async () => {
+    try {
+      const guildRes = await doFetch(`https://discord.com/api/v10/guilds/${guildId}`, { headers });
+      if (!guildRes.ok) {
+        log(`guild lookup failed (${guildRes.status}) for guild ${guildId} — treating as not-admin`);
+        return false;
+      }
+      const guild = (await guildRes.json()) as unknown;
+      if (!isObject(guild)) return false;
+      if (typeof guild["owner_id"] === "string" && guild["owner_id"] === userId) return true;
+      const roleTable = Array.isArray(guild["roles"]) ? (guild["roles"] as unknown[]) : [];
+
+      const memberRes = await doFetch(`https://discord.com/api/v10/guilds/${guildId}/members/${userId}`, { headers });
+      if (!memberRes.ok) {
+        // 404 = not a member at all — the common non-admin case, not notable.
+        if (memberRes.status !== 404) log(`member lookup failed (${memberRes.status}) for guild ${guildId} — treating as not-admin`);
+        return false;
+      }
+      const member = (await memberRes.json()) as unknown;
+      const memberRoleIds = new Set(
+        isObject(member) && Array.isArray(member["roles"]) ? (member["roles"] as unknown[]).filter((r): r is string => typeof r === "string") : [],
+      );
+      return roleTable.some(
+        (r) => isObject(r) && typeof r["id"] === "string" && memberRoleIds.has(r["id"]) && isGuildAdministrator(r["permissions"]),
+      );
+    } catch (err) {
+      log(`admin check error for guild ${guildId}: ${(err as Error)?.message ?? String(err)}`);
+      return false;
+    }
+  })();
+  verdictCache.set(cacheKey, { verdict, at: now });
+  return verdict;
+}
+
+/**
+ * Is `userId` a MEMBER of `guildId`, per Discord itself? ONE REST call —
+ * `GET /guilds/{id}/members/{userId}` — whose 404 is the platform's own "not a member" answer.
+ *
+ * WHY MEMBERSHIP IS THE HONEST CEILING HERE. Discord has no guest tier: a user is in the guild or
+ * they are not, and there is no `is_restricted` analogue to read. So this returns the strongest
+ * membership signal the platform HAS, which is what core's {@link NativeMemberCheck} contract asks
+ * for — every lesser standing (non-member, unknown user, DM pseudo-workspace) resolves false. The
+ * one refinement worth making is the BOT bit: a bot account in the guild is a member by Discord's
+ * reckoning and is not a person, and the gate this feeds decides whether an UNGATED memory deletion
+ * proceeds, so a bot reads false.
+ *
+ * FAIL-CLOSED throughout (see the file header): no token, a DM-bucket pseudo-guild, a network
+ * error, a malformed body — all "not a member", never a guess. NEVER throws.
+ */
+export async function isGuildMemberViaRest(guildId: string, userId: string, deps: DiscordAdminDeps = {}): Promise<boolean> {
+  const token = deps.token ?? process.env.DISCORD_BOT_TOKEN;
+  if (!token || !guildId || !userId) return false;
+  const cacheKey = `${guildId}:${userId}`;
+  const now = deps.nowMs ?? Date.now();
+  const hit = memberVerdictCache.get(cacheKey);
+  if (hit && now - hit.at < VERDICT_TTL_MS) return hit.verdict;
+
+  const doFetch = deps.fetchFn ?? fetch;
+  const verdict = await (async () => {
+    try {
+      const res = await doFetch(`https://discord.com/api/v10/guilds/${guildId}/members/${userId}`, { headers: { authorization: `Bot ${token}` } });
+      if (!res.ok) {
+        // 404 = not a member at all — the common negative case, not notable.
+        if (res.status !== 404) log(`member lookup failed (${res.status}) for guild ${guildId} — treating as not-a-member`);
+        return false;
+      }
+      const member = (await res.json()) as unknown;
+      if (!isObject(member)) return false;
+      const user = member["user"];
+      if (isObject(user) && user["bot"] === true) return false; // a bot is a guild member and not a person
+      // A present `user.id` is the proof the body describes the member we asked about; a 200 with a
+      // body we cannot read is an answer we did not get.
+      return isObject(user) && typeof user["id"] === "string" ? user["id"] === userId : false;
+    } catch (err) {
+      log(`member check error for guild ${guildId}: ${(err as Error)?.message ?? String(err)}`);
+      return false;
+    }
+  })();
+  memberVerdictCache.set(cacheKey, { verdict, at: now });
+  return verdict;
+}
+
+/** Role-evidence verdicts cache separately from the ADMIN/MEMBERSHIP boolean caches above — a
+ *  THIRD question (what roles, not "is a member" or "is an admin"), and a boolean cache cannot
+ *  represent "cannot check" without lying either way a boolean would. */
+const roleEvidenceCache = new Map<string, { roles: readonly string[]; at: number }>();
+
+/**
+ * What Discord ROLES does `userId` hold in `guildId`, right now? ONE REST call —
+ * `GET /guilds/{id}/members/{userId}` — read for its `roles` array (OPE-475, the backscroll
+ * author-trust register leg: {@link gradeDiscordContextLines} feeds this INTO
+ * `identity/author-trust.ts`'s `{ membership }` pattern, the same group-rung key shape the
+ * TRIGGER already builds from the relay's `member.roles`).
+ *
+ * 🔴 FAIL-OPEN, NOT FAIL-CLOSED — the opposite direction from {@link isGuildMemberViaRest} above,
+ * and deliberately so: that gate feeds an AUTHORITY question (does an ungated action proceed?),
+ * where "cannot check" safely reads as "no". This feeds a TAINT JOIN, where "cannot check" must
+ * NEVER read as "holds no roles" — that would be indistinguishable from a verified empty result
+ * and would silently over-mark every wake whose role fetch merely failed (network blip, rate
+ * limit, a token missing `GUILD_MEMBERS`). So the three outcomes are kept apart in the return type:
+ *   - a REAL (possibly empty) roles array — the request succeeded and the body was readable;
+ *   - `[]` on a verified 404 — Discord's own "not a member" answer, which honestly IS "holds no
+ *     roles", not a guess;
+ *   - `undefined` on anything else (no token, network error, non-404 non-2xx, an unreadable body)
+ *     — "cannot check", and the caller must skip the register query for that author entirely
+ *     rather than ever pass an unverified `[]`.
+ * NEVER throws.
+ */
+export async function discordAuthorRoles(guildId: string, userId: string, deps: DiscordAdminDeps = {}): Promise<readonly string[] | undefined> {
+  const token = deps.token ?? process.env.DISCORD_BOT_TOKEN;
+  if (!token || !guildId || !userId) return undefined; // cannot check — never a guess
+  const cacheKey = `${guildId}:${userId}`;
+  const now = deps.nowMs ?? Date.now();
+  const hit = roleEvidenceCache.get(cacheKey);
+  if (hit && now - hit.at < VERDICT_TTL_MS) return hit.roles;
+
+  const doFetch = deps.fetchFn ?? fetch;
+  try {
+    const res = await doFetch(`https://discord.com/api/v10/guilds/${guildId}/members/${userId}`, { headers: { authorization: `Bot ${token}` } });
+    if (res.status === 404) {
+      // Verified: this account holds no guild roles because it holds no guild membership. A REAL
+      // fact from a real answer, not the unverified `[]` this function exists to replace.
+      roleEvidenceCache.set(cacheKey, { roles: [], at: now });
+      return [];
+    }
+    if (!res.ok) {
+      log(`role lookup failed (${res.status}) for guild ${guildId} — skipping the register query (cannot check is not checked-and-empty)`);
+      return undefined; // cannot check — NEVER cached, NEVER guessed
+    }
+    const member = (await res.json()) as unknown;
+    const rolesField = isObject(member) ? member["roles"] : undefined;
+    if (!Array.isArray(rolesField)) return undefined; // unreadable body — skip, don't guess
+    const roles = rolesField.filter((r): r is string => typeof r === "string" && r.length > 0);
+    roleEvidenceCache.set(cacheKey, { roles, at: now });
+    return roles;
+  } catch (err) {
+    log(`role lookup error for guild ${guildId}: ${(err as Error)?.message ?? String(err)}`);
+    return undefined; // cannot check — never a guess
+  }
+}
+
+/** Reset the cached role-evidence verdicts (tests only). */
+export function _resetDiscordAuthorRolesCache(): void {
+  roleEvidenceCache.clear();
+}

package/agent/approvals/discord-card.ts

@@ -0,0 +1,248 @@
+// Pure Discord renderers + codecs for the admin approval card — the Discord sibling of
+// card.ts (Slack Block Kit). PURE by design, same doctrine: no I/O, no Discord client,
+// nothing async — the card is a CODE-RENDERED VIEW of the FROZEN args, never model text,
+// and purity keeps it trivially unit-testable (discord-approvals-test.ts) without a live
+// bot. The I/O half (REST poster + click handler) lives in discord-flow.ts.
+//
+// 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.)
+//   - 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.
+//   - Buttons are stripped by REPLACING the message via an interaction response (type 7,
+//     UPDATE_MESSAGE), so the decided card here renders with `components: []`.
+//
+// THREE renders live here, and only the first two are a card: the PENDING card (Approve/Reject), the
+// DECIDED card (no buttons), and the JUDGE-LIFT NOTICE (OPE-1103) — a review surface for an action
+// that already ran, carrying the one "This should not have run" button and never a decision one.
+
+import type { PendingActionRow } from "@open-everywhere/core/agent/adapter-api.js";
+import { grantButtonLabel, sessionGrantKind } from "@open-everywhere/core/agent/adapter-api.js";
+
+/**
+ * Every approval button custom_id this feature owns starts with this. Deliberately distinct
+ * from BOTH the Slack action_id prefix ("oe_approval:" — a different wire format, keeping
+ * grep unambiguous about which surface a log line came from) and Eve's own Discord HITL
+ * prefixes ("eve_input:" / "eve_input_freeform:") — the Discord front route classifies
+ * "ours vs. forward to Eve" on exactly this prefix (channels/discord-front.ts).
+ */
+export const OE_DISCORD_APPROVAL_PREFIX = "oe-approval:";
+
+/** Discord's hard cap on a component custom_id. https://discord.com/developers/docs/interactions/message-components */
+export const DISCORD_CUSTOM_ID_MAX = 100;
+
+// Discord component/button wire constants (stable public API integers). Defined locally —
+// eve exports DISCORD_COMPONENT_TYPE but importing it would make this pure leaf depend on
+// eve's channel module for two integers; card.ts makes the same leaf-over-import call for
+// the Slack prefix.
+const COMPONENT_ACTION_ROW = 1;
+const COMPONENT_BUTTON = 2;
+const BUTTON_STYLE_SECONDARY = 2; // grey — Approve for session (the grantable-kind middle button, OPE-53/OPE-11)
+const BUTTON_STYLE_SUCCESS = 3; // green — Approve (Slack's `style: "primary"` analogue)
+const BUTTON_STYLE_DANGER = 4; //  red — Reject  (Slack's `style: "danger"` analogue)
+
+/** One Discord message component. Loosely typed on purpose — same spirit as card.ts's
+ *  SlackBlock: Discord's schema is large and this file only emits two well-known shapes. */
+export interface DiscordComponent {
+  readonly type: number;
+  readonly [key: string]: unknown;
+}
+
+/** A rendered Discord card: Markdown `content` + the components row (empty once decided). */
+export interface DiscordCardMessage {
+  readonly content: string;
+  readonly components: readonly DiscordComponent[];
+}
+
+/**
+ * Every verb a Discord approval button can carry. A SUBSET of core's `ApprovalDecision` by
+ * construction, not a copy of it: core also parses verbs no Discord button renders. `contradict`
+ * (OPE-965/OPE-1103) is the judge-lift notice's one button — it decides nothing, it records an
+ * overrule of a verdict whose action has already run.
+ */
+export type DiscordApprovalDecision = "approve" | "reject" | "approve_session" | "contradict";
+
+/** The closed verb set as a VALUE — one list, so build and parse cannot drift into a button nothing
+ *  can decode (discord-approvals-test.ts pins the round trip for every entry). */
+const DISCORD_APPROVAL_DECISIONS: readonly DiscordApprovalDecision[] = ["approve", "reject", "approve_session", "contradict"];
+
+/**
+ * Build one approval button custom_id: `oe-approval:{id}:{verb}:{org}`. The id is
+ * our own randomUUID (never contains ":"), the verb is a closed set, and the org rides LAST
+ * so it may contain anything (parse peels the two fixed-shape segments off the front).
+ * Throws when the result would exceed Discord's 100-char cap — a propose-time fail-loud:
+ * the poster (discord-flow.ts) catches it, the post fails, and requestApproval marks the
+ * pending expired rather than leaving an unclickable card.
+ *
+ * `contradict` is 5 chars SHORTER than `approve_session`, so it can never be the verb that first
+ * trips the cap — an org that fits a grantable kind's card fits this notice's button too.
+ */
+export function buildDiscordApprovalCustomId(row: PendingActionRow, decision: DiscordApprovalDecision): string {
+  const customId = `${OE_DISCORD_APPROVAL_PREFIX}${row.id}:${decision}:${row.org}`;
+  if (customId.length > DISCORD_CUSTOM_ID_MAX) {
+    throw new Error(
+      `approval custom_id would be ${customId.length} chars (Discord caps at ${DISCORD_CUSTOM_ID_MAX}) — org "${row.org}" is too long to ride a Discord button`,
+    );
+  }
+  return customId;
+}
+
+/**
+ * Parse an `oe-approval:{id}:{decision}:{org}` custom_id. Returns null for anything else —
+ * including a well-formed-looking id with a garbage decision segment — so callers can treat
+ * "not parseable" as "not ours" without a second check (mirrors flow.ts's parseApprovalAction;
+ * an unparseable-but-prefixed id forwards to Eve, whose HITL decoder no-ops it harmlessly).
+ */
+export function parseDiscordApprovalCustomId(customId: string): { id: string; decision: DiscordApprovalDecision; org: string } | null {
+  if (!customId.startsWith(OE_DISCORD_APPROVAL_PREFIX)) return null;
+  const rest = customId.slice(OE_DISCORD_APPROVAL_PREFIX.length);
+  const first = rest.indexOf(":");
+  if (first <= 0) return null; // no id segment
+  const second = rest.indexOf(":", first + 1);
+  if (second < 0) return null; // no org segment
+  const id = rest.slice(0, first);
+  const decision = rest.slice(first + 1, second);
+  const org = rest.slice(second + 1);
+  // "approve_session" (OPE-53) and "contradict" (OPE-1103) are both ADDITIVE — old custom_ids still
+  // parse (the id never contains ":"), and a card minted before either verb existed still decodes.
+  if (!DISCORD_APPROVAL_DECISIONS.includes(decision as DiscordApprovalDecision) || org.length === 0) return null;
+  return { id, decision: decision as DiscordApprovalDecision, org };
+}
+
+/** The shared card body: header + summary + provenance. `<@id>` is Discord's user-mention
+ *  syntax too, so the requester line reads identically to the Slack card. */
+function cardBody(row: PendingActionRow, summaryLines: readonly string[], footer: string): string {
+  return [`**Approval requested: ${row.kind}**`, ...summaryLines, footer].join("\n");
+}
+
+/**
+ * The card for a still-pending action: summary + "requested by / expires" + Approve/Reject
+ * buttons carrying the pending id + org in their custom_ids (see the file header for why
+ * the org rides the custom_id on Discord). Mirrors card.ts's pendingCardBlocks.
+ */
+export function pendingDiscordCard(row: PendingActionRow, summaryLines: readonly string[]): DiscordCardMessage {
+  const content = cardBody(row, summaryLines, `-# Requested by <@${row.requestedBy}> · expires ${row.expiresAt}`);
+  const buttons: DiscordComponent[] = [
+    {
+      type: COMPONENT_BUTTON,
+      style: BUTTON_STYLE_SUCCESS,
+      label: "Approve",
+      custom_id: buildDiscordApprovalCustomId(row, "approve"),
+    },
+  ];
+  // OPE-53: a session-grantable row gets the middle "Approve for session" button — publish this one
+  // AND skip the card for the rest of THIS proposing session. sessionGrantKind() (core
+  // approvals/session-grant.ts) is the ONE predicate, and it grants for `pr.open` ALONE — every
+  // other kind returns null and stays two-button per-call. Mirrors card.ts's Slack
+  // pendingCardBlocks so the two surfaces agree on the third button.
+  if (sessionGrantKind(row) !== null) {
+    buttons.push({
+      type: COMPONENT_BUTTON,
+      style: BUTTON_STYLE_SECONDARY,
+      // OPE-152: the label comes from core, so Slack and Discord can never disagree about whether
+      // the click grants for this session or standing-for-this-routine (a fire's card).
+      label: grantButtonLabel(row),
+      custom_id: buildDiscordApprovalCustomId(row, "approve_session"),
+    });
+  }
+  buttons.push({
+    type: COMPONENT_BUTTON,
+    style: BUTTON_STYLE_DANGER,
+    label: "Reject",
+    custom_id: buildDiscordApprovalCustomId(row, "reject"),
+  });
+  return { content, components: [{ type: COMPONENT_ACTION_ROW, components: buttons }] };
+}
+
+/**
+ * THE JUDGE-LIFT NOTICE (OPE-965 on Slack, OPE-1103 here) — the Discord sibling of card.ts's
+ * `judgeLiftNoticeBlocks`, and the room's only trace of an action NOBODY was asked about.
+ *
+ * WHY IT EXISTS. When the armed judge lifts a gated verb, the approver chain executes the frozen
+ * args and posts no card — that is the whole point of the lift. The wedge row and the
+ * `approval.judge.verdict` row still land, but the ROOM sees nothing. This notice is that trace, and
+ * its single button is the answer: "This should not have run" writes the
+ * `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.
+ *
+ * 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.
+ */
+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}`;
+  return {
+    content: [`**Ran without asking: ${row.kind}**`, ...summaryLines, context].join("\n"),
+    components: [
+      {
+        type: COMPONENT_ACTION_ROW,
+        components: [
+          {
+            type: COMPONENT_BUTTON,
+            style: BUTTON_STYLE_DANGER,
+            label: "This should not have run",
+            custom_id: buildDiscordApprovalCustomId(row, "contradict"),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * 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).
+ */
+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: [] };
+}
+
+/** Discord's ADMINISTRATOR permission bit (0x8). https://discord.com/developers/docs/topics/permissions */
+const ADMINISTRATOR_BIT = 1n << 3n;
+
+/**
+ * Does a Discord interaction's `member.permissions` bitfield carry ADMINISTRATOR? The field
+ * is a STRINGIFIED integer (Discord serializes the 64-bit+ field as a decimal string).
+ * FAIL-CLOSED on anything else: missing, empty, non-numeric, or non-string input is "not an
+ * admin", never a guess — this is an approver check on untrusted wire JSON.
+ */
+export function isGuildAdministrator(permissions: unknown): boolean {
+  if (typeof permissions !== "string" || !/^\d+$/.test(permissions)) return false;
+  try {
+    return (BigInt(permissions) & ADMINISTRATOR_BIT) === ADMINISTRATOR_BIT;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is a pending action's FROZEN scopeKey inside this guild (`discord/{guild}` or
+ * `discord/{guild}/…`)? Segment-exact — "discord/G11/…" is NOT within guild "G1". This is
+ * the fence on the Discord-native approver path: a guild ADMINISTRATOR is authority over
+ * their own server's scopes, not over rows a proposer aimed at some other workspace via an
+ * explicit scopeKey override — those still need the config-as-code roster (clickerMayDecide).
+ */
+export function scopeWithinGuild(scopeKey: string, guildId: string | undefined): boolean {
+  if (!guildId) return false;
+  return scopeKey === `discord/${guildId}` || scopeKey.startsWith(`discord/${guildId}/`);
+}