@open-everywhere/provider-discord 0.1.0

package/agent/channels/discord-rest.ts

@@ -0,0 +1,85 @@
+// discord-rest — THE ONE place a Discord REST WRITE call leaves this host (OPE-1236).
+//
+// WHY THIS SEAM EXISTS. Every Discord write in the reply/message-ops path used to be a bare `fetch`
+// with no 429 handling. Discord answers a rate-limited call with HTTP 429, and it states the delay
+// TWICE: in the `Retry-After` header AND in a JSON `retry_after` body field (fractional seconds).
+// The body field is authoritative — Discord's own docs put the precise delay there — so the shared
+// header-only backoff would miss it. This funnel wraps every write call in the shared
+// `withRetryAfter` primitive and feeds it a body-precedence override, so a Discord write honours the
+// delay the vendor actually named. See `docs/extending/provider-rate-limits.md`.
+//
+// 🔴 WHAT THIS SEAM COVERS, EXACTLY. Every Discord WRITE in this package: the reply feature's write
+// seam (`discord-post.ts`), the ancillary message ops (`discord-message-ops.ts`), and — since
+// OPE-1311 — the GATEWAY's own five writes (`discord-gateway.ts`: the completion post-back, the
+// open-DM, the typing indicator, the reaction and the thread open). Every `fetch` in those three
+// files goes through here.
+//
+// It does NOT cover the four READ channels (`discord-read.ts`, `discord-backscroll.ts`,
+// `discord-directory.ts`, `discord-bot-name.ts`), which still hold their own raw `fetch`.
+// `discord-rest-seam-test.ts` § 3 holds that KNOWN-UNCOVERED inventory and reds when a NEW file grows
+// its own bare `fetch(` (a write that would bypass the seam) or a covered file regrows one, so the
+// gap cannot widen unnoticed.
+//
+// The gateway's writes are fail-silent, so they do not all take the shared policy: the two ephemeral
+// affordances (typing, the reaction) pass a tighter one, because both are awaited on the turn's own
+// latency path. `discord-gateway.ts`'s `AFFORDANCE_RETRY` carries that reasoning.
+//
+// The bot token is a SECRET — it rides only the caller's header, never through here, and no response
+// body ever reaches an error string. `operation` is the id-free vendor route SHAPE (e.g.
+// `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";
+
+/** The provider surface name on the NAMED rate-limit failure. */
+export const DISCORD_SURFACE = "discord";
+
+/** The subset of `fetch` this seam drives — injectable so a test scripts the 429 sequence. */
+export type DiscordFetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+/** Transport and retry seams. A test injects both; live code passes neither. */
+export interface DiscordFetchDeps {
+  readonly fetch?: DiscordFetchLike;
+  readonly retry?: RetryPolicy;
+}
+
+/**
+ * Read the honoured delay from a Discord 429 body, in milliseconds, or `undefined` when the body
+ * carries no usable `retry_after` (then the seam falls back to the header). Discord states
+ * `retry_after` in SECONDS — fractional, e.g. `0.75` — so this multiplies by 1000 rather than
+ * routing through the header parser, which reads integer seconds only.
+ *
+ * 🔴 NEVER THROWS, and reads a CLONE. The primitive cancels the original body right after this
+ * returns; reading the clone leaves the original intact for that cancel. A body that is missing,
+ * not JSON, or carries no numeric `retry_after` answers `undefined` — never a wrong delay.
+ */
+export async function discordBodyRetryAfterMs(res: Response): Promise<number | undefined> {
+  try {
+    const body = (await res.clone().json()) as { retry_after?: unknown } | null;
+    const seconds = body?.retry_after;
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0) return undefined;
+    return seconds * 1000;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Issue ONE Discord REST call with the shared 429 backoff, honouring the body's `retry_after` over
+ * the header. `operation` is the id-free route shape for the named failure. `deps.retry` lets a test
+ * inject a stub sleep/clock; live callers pass nothing.
+ *
+ * Returns the FIRST non-429 response untouched — the caller reads `res.ok`/`res.status`/`res.json()`
+ * exactly as it did before this seam existed. Throws `RateLimitExhaustedError` when a 429 outlasts
+ * the bounded attempts, and re-throws a transport error unretried (an unanswered write may have
+ * 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);
+  return withRetryAfter(send, {
+    surface: DISCORD_SURFACE,
+    operation,
+    retryAfterMs: (res) => discordBodyRetryAfterMs(res as Response),
+    ...deps.retry,
+  });
+}

package/agent/channels/discord.ts

@@ -0,0 +1,244 @@
+// The Discord surface. Wires Discord's HTTP Interactions (slash commands) → an
+// OpenEverywhere session, and — the point of the "Discord-binding" slice — populates the
+// session auth context with the REAL Discord identity (guild/channel/user ids + the
+// channel type) so the identity seam (agent/identity/binding.ts) resolves the actual
+// workspace (the guild/server — the org boundary), surface (the channel), mode
+// (channel/dm/mpim), and visibility (fail-closed private) instead of OE_* env
+// stand-ins. Everything downstream — memory partition, access resolver, routine
+// dispatch — then keys off real Discord identity with no further change.
+//
+// Eve's Discord channel is interaction-based, not message-based: there is no
+// app_mention / message event, only `onCommand(ctx, interaction)` for an explicitly
+// invoked slash command. A slash command is already a bot-directed act — you can't
+// invoke the app without targeting it — so it is the natural analogue of Slack's
+// mention-gating: every onCommand is, by construction, "mentioned". We accept both
+// DMs and guild commands and still drop bot-authored invocations, then override
+// onCommand only to attach OUR richer auth via buildDiscordAuth (the eve default
+// derives a thinner, guild-scoped auth). Kept MINIMAL for launch — identity binding +
+// dispatch only; no status-UX / onboarding extras (cf. slack.ts).
+//
+// Credentials: omitted here, so eve falls back to DISCORD_PUBLIC_KEY /
+// DISCORD_APPLICATION_ID / DISCORD_BOT_TOKEN (see .env.example). Swap the credential
+// broker later without touching identity. Capturing the channel type / guild presence is a
+// RAW-fact job; the security-critical interpretation (fail-closed to private) lives in
+// the binding (discordVisibility).
+//
+// FRONTED (see discord-front.ts): the wrapped eve channel sits on an internal route; the
+// public Interactions Endpoint URL is our front, which answers `oe-approval:` approval-card
+// button clicks (admin approvals — approvals/discord-flow.ts) and forwards everything else
+// (PING, slash commands, eve's own HITL clicks) here unchanged. Same option-(c) pattern as
+// the Slack channel (slack-front.ts) and for the same reason: eve exposes no onComponent hook.
+//
+// A THIRD, separate URL (see discord-events.ts) carries Discord's app-level WEBHOOK EVENTS —
+// APPLICATION_AUTHORIZED / APPLICATION_DEAUTHORIZED, i.e. install/uninstall — into the audit
+// trail. Configured on the developer portal's Webhooks page, not the Interactions one.
+
+import {
+  discordChannel,
+  type DiscordContext,
+  type DiscordCommandInteraction,
+} from "eve/channels/discord";
+import { buildDiscordAuth, threadParentFromRawChannel, discordMemberPendingFromRaw, type OpenEverywhereDiscordAuth } from "./discord-identity.js";
+import {
+  finalMessageActionForTurn,
+  NO_REPLY_SENTINEL_REASON,
+  auditNoReplySentinelObserved,
+  isBareStop,
+  consumeRepliedThisTurn,
+  dropClosingProse,
+  resolvePartition,
+  authPrincipalId,
+  type ChatAuditPartition,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { frontDiscordChannel, INTERNAL_DISCORD_ROUTE } from "./discord-front.js";
+import { withDiscordEventsRoute } from "./discord-events.js";
+
+// The audit partition for a terminal event, rebuilt from the LIVE session state the same
+// way slack.ts rebuilds its own (the completion handler has no auth context): guild →
+// workspace, channel → surface, via the REAL identity seam so rows land exactly where the
+// dispatch partition did. Null on an unidentifiable state (no channel id) — the caller
+// then skips the row (fail-soft; auditing must never fail or post into the turn).
+function auditPartitionForState(state: { channelId: string | null; guildId: string | null }): ChatAuditPartition | null {
+  if (!state.channelId) return null;
+  try {
+    return resolvePartition({
+      channel: { kind: "discord" },
+      session: { auth: { current: buildDiscordAuth({ userId: "", guildId: state.guildId ?? undefined, channelId: state.channelId }) } },
+    });
+  } catch {
+    return null;
+  }
+}
+
+// Read the Discord numeric channel `type` from the raw interaction payload. The parsed
+// interaction exposes ids (channel/guild/user) but not the channel kind, which lives in
+// the payload's `channel` object. Used only to tell a DM (1) / group DM (3) from a guild
+// text channel or thread; absent → the binding falls back to guild-presence for mode and
+// fails closed on visibility. Defensive: the payload is Discord's raw JSON.
+function channelTypeFromRaw(raw: Record<string, unknown>): string | undefined {
+  const ch = raw["channel"];
+  if (ch && typeof ch === "object") {
+    const t = (ch as Record<string, unknown>)["type"];
+    if (typeof t === "number") return String(t);
+  }
+  return undefined;
+}
+
+// Attach OUR richer Discord auth: raw guild/channel/user ids + the channel type (and,
+// for a THREAD, its parent channel id — the raw payload's channel partial carries
+// `parent_id`, so the thread→parent domain/spend grain of item 22 is FREE here, no REST
+// lookup like the gateway's message path needs), which the binding then interprets into
+// workspace/surface/mode/visibility. Drops invocations by another bot — we never act on
+// a bot's command.
+function authFromInteraction(interaction: DiscordCommandInteraction): OpenEverywhereDiscordAuth | null {
+  if (interaction.user.isBot) return null; // bot actor — drop
+  return buildDiscordAuth({
+    userId: interaction.user.id,
+    guildId: interaction.guildId,
+    channelId: interaction.channelId,
+    channelType: channelTypeFromRaw(interaction.raw),
+    parentChannelId: threadParentFromRawChannel(interaction.raw),
+    // Guest/unverified detection (OPE-60): the interaction payload carries the guild `member`
+    // object (incl. `member.pending`) for FREE — no privileged intent, no REST call. A pending
+    // member hasn't cleared membership screening → the binding demotes trust to external.
+    memberPending: discordMemberPendingFromRaw(interaction.raw),
+  });
+}
+
+const discordInteractionChannel = discordChannel({
+  // Internal mount — the public URL is the approval-click front (frontDiscordChannel below).
+  route: INTERNAL_DISCORD_ROUTE,
+  // 🔴 QUEUE, NEVER STEER (OPE-412) — eve's default `steer` cancels the turn in flight when a
+  // message arrives. Same reasoning as the Slack channel; see slack.ts for the full note.
+  turnPolicy: "queue",
+  onCommand: async (ctx: DiscordContext, interaction: DiscordCommandInteraction) => {
+    const auth = authFromInteraction(interaction);
+    if (auth === null) return null; // bot author / unactionable → ack without dispatch
+    try {
+      await ctx.discord.startTyping();
+    } catch {
+      /* typing indicator is best-effort */
+    }
+    return { auth };
+  },
+  events: {
+    // Authoring this handler REPLACES eve's Discord default for "turn.started" (verified in
+    // node_modules/eve/dist/.../discord/defaults.js: `async "turn.started"(e,t,n){await
+    // t.discord.startTyping()}`), so we replicate that default body verbatim first, matching the
+    // discipline channels/slack.ts's own turn.started comment documents.
+    //
+    // OPE-645: REPLY PRINCIPAL snapshot — the same T1.4 pattern channels/slack.ts,
+    // channels/teams.ts and discord-gateway.ts each use for their own: message.completed
+    // has no live auth ctx (eve rewrites session.auth.current on every delivery, and this channel
+    // runs `turnPolicy: "queue"`, so a later queued delivery can overwrite it before this turn's
+    // own message.completed fires), but turn.started does. authPrincipalId(ctx) is the exact read
+    // bindFrom(ctx).principalId falls back to for an ordinary human turn (identity/binding.ts) —
+    // snapshotting it here means the DROP row this handler writes since OPE-2006 names the same
+    // person the turn's egress.policy rows already do. It is no longer a `reply.post` row: nothing
+    // posts here.
+    "turn.started": async (_data, channel, ctx) => {
+      // Snapshot FIRST — the attribution must not depend on the typing call succeeding (the
+      // same discipline the Slack sibling states for its supervisor target snapshot).
+      (channel.state as unknown as Record<string, unknown>).oeReplyPrincipalId = authPrincipalId(ctx);
+      await channel.discord.startTyping();
+    },
+    // Override the reply-posting handler for ONE addition: a fired `watch` routine
+    // ends its turn with the silence sentinel when the watched state is unchanged
+    // (routines/watch.ts) — swallow it, never post it. Mirrors the Slack override
+    // (channels/slack.ts) and the Teams one, via the shared, unit-tested
+    // finalMessageAction() decision. Everything else matches eve's Discord default
+    // (tool-calls and empty final messages post nothing). Only routine fires teach
+    // the sentinel on this surface; slash-command replies are unaffected.
+    "message.completed": async (data, channel, ctx) => {
+      const sessionId = ctx?.session?.id; // stamped into the terminal audit rows → joins to the transcript
+      // OPE-1647: the TURN ID, so the stand-down silence mark (channels/stand-down-silence.ts) can
+      // prove it belongs to THIS turn. Same extraction idiom this file already uses for the §POSTED
+      // consume below.
+      // 🔴 SINCE OPE-2006 IT SERVES THE SILENCE DECISION ALONE. It is read once here and handed to
+      // `finalMessageActionForTurn`, whose `consumeStandDownSilenceThisTurn(turnId)` is its only
+      // reader on this path. There is no reply audit below to stamp it onto: this surface DROPS its
+      // closing prose, so the durable latch that guarded the old post has no door left to shut here.
+      const turnId = (ctx as unknown as { session?: { turn?: { id?: string } } })?.session?.turn?.id;
+      const action = finalMessageActionForTurn(data.finishReason, data.message, turnId);
+      // An interim tool-call step, not the turn's end — don't consume the reply signal here:
+      // the tool this step is about to run may be the `reply` call itself (mirrors slack.ts).
+      if (action.kind === "buffer-tool-status") return;
+      // Terminal decision — read-and-reset the reply-tool signal once, on every terminal
+      // branch (post OR silent), so it never bleeds into the next turn (same contract as
+      // slack.ts's reactedThisTurn/repliedThisTurn consume). TURN-ID KEYED (OPE-805): only THIS
+      // turn's own mark answers true — see reply-signal.ts's header.
+      const repliedThisTurn = consumeRepliedThisTurn((ctx as unknown as { session?: { turn?: { id?: string } } })?.session?.turn?.id);
+      if (action.kind !== "post") {
+        // Only log a genuinely JUDGED silence (the NO_REPLY sentinel, or the no_reply
+        // tool) — an ordinary empty completion (nothing to say, no judgment made) isn't
+        // worth a log line.
+        if (action.kind === "silent" && action.reason !== "empty final message") {
+          console.log(`[open-everywhere:discord] judged silence (${action.reason}) — nothing posted (channel ${channel.state.channelId ?? "?"})`);
+        }
+        // ACTIONS-ONLY posture (audit-wedge build plan §1c, 2026-07-14): a judged silence is not
+        // an audited action — the transcript answers "why did it stay quiet?", not the audit log.
+        // The console line above stays; the bare-stop WARN below stays (an anomaly, not a silence).
+        //
+        // ONE exception (OPE-890): the model ended the turn on the bare NO_REPLY sentinel — the
+        // TOOL route already carries an always-on `reply.no_reply_observed` row (tools/no_reply.ts,
+        // OPE-649); this is the sentinel route's twin, same action name, best-effort. Reached only
+        // for a genuine bare-sentinel turn — finalMessageActionForTurn already resolves the tool
+        // route to its own `no_reply tool: …` reason, so a tool-called turn never lands here.
+        if (action.kind === "silent" && action.reason === NO_REPLY_SENTINEL_REASON) {
+          const p = auditPartitionForState(channel.state);
+          if (p) await auditNoReplySentinelObserved(p, sessionId).catch(() => undefined);
+        }
+        // Bare-stop enforcement (see slack-events.ts's isBareStop header for the full
+        // rationale — DETECT-AND-LOG, not a hard gate). `react` is Slack-only (no
+        // Discord equivalent wired), but the reply-tool family (reply-signal.ts) IS armed
+        // here, so a `reply`-then-silent turn must not be mis-flagged. The bare stop is
+        // ALSO covered by the discord.no_reply row above (reason "empty final message").
+        if (action.kind === "silent" && isBareStop(action, repliedThisTurn)) {
+          console.warn(
+            `[open-everywhere:discord] BARE STOP — turn ended with no reply and no no_reply (channel ${channel.state.channelId ?? "?"}) — this usually means a judgment call went missing, not that one was made.`,
+          );
+        }
+        return;
+      }
+      // 🔴 THE CLOSING PROSE IS DROPPED, NOT POSTED (OPE-2006). This branch used to route the
+      // terminal reply through `postTerminalProse`, with a raw `channel.discord.post` fallback for an
+      // unidentifiable state. Both are gone: the `reply` tool is the only channel a seat's words
+      // leave by, so a turn that ended in prose and never called `reply` has said nothing here. The
+      // row is the record — no re-send, no queue, no host-side re-post.
+      // WHAT TELLS THE MODEL is the seat prompt: Discord declares `closingProseDropped`, so a
+      // conversational seat here reads the `reply-only` delivery arm, whose copy states that the
+      // turn-final text is discarded — inside its persona when the token is supervisor-shaped, and
+      // through the `delivery` slot when it is not (instructions/access.ts `renderDeliverySlot`).
+      {
+        const p = auditPartitionForState(channel.state);
+        if (p) {
+          await dropClosingProse({
+            row: {
+              org: p.org,
+              platform: p.platform,
+              workspace: p.workspace,
+              surface: p.surface,
+              principalId: (channel.state as unknown as Record<string, unknown>).oeReplyPrincipalId as string | undefined,
+            },
+            chars: action.text.length,
+            ...(sessionId ? { sessionId } : {}),
+            anchor: { channelId: channel.state.channelId ?? null },
+            log: (m) => console.warn(`[open-everywhere:discord] ${m} (channel ${channel.state.channelId ?? "?"})`),
+          });
+        } else {
+          // No resolvable partition, so there is no row to file it under — the drop still happens and
+          // the log line is the whole record, the same honest degradation the silence branches above
+          // take on an unidentifiable state.
+          console.warn(
+            `[open-everywhere:discord] closing prose DROPPED (${action.text.length}c) — nothing posted, and no partition to audit it under (channel ${channel.state.channelId ?? "?"})`,
+          );
+        }
+      }
+    },
+  },
+});
+
+// FRONTED (interactions) + the app-level WEBHOOK EVENTS route (discord-events.ts): a separate,
+// additive URL that audits APPLICATION_AUTHORIZED / APPLICATION_DEAUTHORIZED so install/uninstall
+// is observable. Observability only — it gates nothing and never reaches a session.
+export default withDiscordEventsRoute(frontDiscordChannel(discordInteractionChannel));

package/agent/commands/discord-command-sync.ts

@@ -0,0 +1,285 @@
+// THE DISCORD HALF of the surface-command reconcile plane (OPE-1687) — the deployment registers its
+// own "/oe" command instead of waiting for an operator to run a CLI.
+//
+// WHAT IT DOES, ONCE PER PROCESS START: read the commands Discord holds for this application at each
+// declared guild, project both sides onto the fields this deployment actually declares, and write
+// ONLY when they differ. No difference ⇒ no write, so a warm deployment's steady-state cost is one
+// vendor read per cold start.
+//
+// 🔴 THE WRITE IS ADDITIVE — `POST …/commands`, NEVER the bulk `PUT`. Discord's bulk PUT is a full
+// OVERWRITE of every command at that scope, which is the right contract for the operator CLI
+// (`scripts/register-discord-commands.ts`, run deliberately, documented as destructive) and the wrong
+// one for an unattended boot. `docs/deploy/surfaces/discord.md` tells operators to register their own
+// `/ask` command by hand at this same scope; a boot-time PUT of our one-command array would delete it
+// silently on the next cold start. The per-command POST creates-or-updates by NAME and leaves every
+// other command at the scope untouched, so this plane can only ever add or correct "/oe".
+//
+// 🔴 THE DIFF IS A PROJECTION, NOT A DEEP EQUAL. Discord's GET returns fields nobody declared — `id`,
+// `application_id`, `version`, `guild_id`, `default_member_permissions`, `nsfw`, localisation maps —
+// and omits `required` where it is false. A deep equal against the declared body would therefore
+// differ EVERY time and turn "write only on a difference" into a write on every cold start. Both
+// sides go through the same `projectCommand`, which keeps exactly the fields
+// `buildOeDiscordCommandDefinition` sets and fills `required` with its Discord default.
+//
+// NEVER THROWS, AND NEVER BLOCKS BOOT FOR LONG. Every failure — no credential, a refused request, a
+// timeout, malformed JSON — answers with an outcome the boot plane logs. A bot token never reaches an
+// outcome's `detail`, and neither does a response body: a 401 says "401", not what Discord wrote back.
+// The latency bound is two constants below, and both are load-bearing rather than tuning: no 429
+// backoff at all, and one budget for the whole reconcile whatever the guild count.
+//
+// 🔴 ANY PROCESS THAT STARTS WITH BOTH CREDENTIALS WRITES TO THE DECLARED GUILD. The credential pair
+// is the only gate, so a local `eve dev`/`eve start` run with the deployment's own `DISCORD_BOT_TOKEN`
+// registers THAT CHECKOUT's command shape into the declared guild — see the warning in
+// `agent/commands/discord-commands.ts`.
+
+import type { RetryPolicy, SurfaceCommandOutcome, SurfaceCommandScope } from "@open-everywhere/core/agent/adapter-api.js";
+import { discordFetch, type DiscordFetchLike } from "../channels/discord-rest.js";
+import { buildOeDiscordCommandDefinition } from "./discord-commands.js";
+
+/**
+ * 🔴 NO 429 BACKOFF AT ALL — the reconcile sits on the FIRST REQUEST's latency path.
+ *
+ * `withRetryAfter`'s defaults allow up to four attempts, a 30 s single wait and a 60 s total
+ * (`packages/core/agent/channels/rate-limit-retry.ts`), and its own header says a latency-critical
+ * caller must pass a tighter policy. A boot on a lambda is the strictest such caller there is: the
+ * cold start it rides is usually a Discord INTERACTION, which must be acknowledged inside 3 seconds.
+ * A 429 answered with `retry_after: 60` would otherwise sleep 30 s inside the boot's own top-level
+ * await, blow that ack, and possibly time the invocation out. So a rate-limited Discord is a plain
+ * failure here — the next cold start reads again, and the command list is stale meanwhile, which is
+ * the state it was already in.
+ *
+ * The same reasoning is why `discord-gateway.ts` gives its two ephemeral affordances `AFFORDANCE_RETRY`.
+ */
+const BOOT_RETRY: RetryPolicy = { maxAttempts: 1 };
+
+/** How long ONE Discord call may take. `AbortSignal.timeout` bounds a call, never a backoff sleep —
+ *  that is what {@link BOOT_RETRY} removes. */
+const CALL_TIMEOUT_MS = 1_500;
+
+/**
+ * The ceiling on the WHOLE reconcile, across every declared guild and both of each guild's calls.
+ * Without it the worst case multiplies by declared guild, and "bounded" would depend on how many
+ * rooms an operator listed. A guild the budget cannot reach reports `failed` and is read again on the
+ * next cold start.
+ */
+const RECONCILE_BUDGET_MS = 2_000;
+
+const API_BASE = "https://discord.com/api/v10";
+
+/** The projected shape both sides are compared in — exactly the fields this deployment declares. */
+export interface ProjectedOption {
+  readonly name: string;
+  readonly description: string;
+  readonly type: number;
+  readonly required: boolean;
+  readonly min_value?: number;
+  readonly max_value?: number;
+  readonly options: readonly ProjectedOption[];
+}
+
+export interface ProjectedCommand {
+  readonly name: string;
+  readonly type: number;
+  readonly description: string;
+  readonly options: readonly ProjectedOption[];
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+function numOrUndefined(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function projectOptions(raw: unknown): readonly ProjectedOption[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ProjectedOption[] = [];
+  for (const entry of raw) {
+    if (!isObject(entry)) continue;
+    const min = numOrUndefined(entry["min_value"]);
+    const max = numOrUndefined(entry["max_value"]);
+    out.push({
+      name: str(entry["name"]),
+      description: str(entry["description"]),
+      type: numOrUndefined(entry["type"]) ?? 0,
+      // Discord OMITS `required` when it is false, so the default is part of the projection. Without
+      // it every optional option reads as a difference and the reconcile writes on every cold start.
+      required: entry["required"] === true,
+      ...(min === undefined ? {} : { min_value: min }),
+      ...(max === undefined ? {} : { max_value: max }),
+      options: projectOptions(entry["options"]),
+    });
+  }
+  return out;
+}
+
+/**
+ * Project one ApplicationCommand — declared or vendor-held — onto the fields this deployment sets.
+ * Returns undefined for anything that is not an object with a name, which is what a malformed or
+ * unexpected list entry looks like.
+ *
+ * OPTION ORDER IS PART OF THE PROJECTION. Discord renders a command's options in the order they were
+ * registered, so a reordered list is a real user-visible difference and must be written. Discord
+ * returns them in the registered order, so a steady state never reorders on its own.
+ */
+export function projectCommand(raw: unknown): ProjectedCommand | undefined {
+  if (!isObject(raw)) return undefined;
+  const name = str(raw["name"]);
+  if (name.length === 0) return undefined;
+  return {
+    name,
+    // Discord's own default for `type` is 1 (CHAT_INPUT); the declaration sets it explicitly.
+    type: numOrUndefined(raw["type"]) ?? 1,
+    description: str(raw["description"]),
+    options: projectOptions(raw["options"]),
+  };
+}
+
+/** A stable string for one projected command, so two projections compare as text. */
+function canonical(command: ProjectedCommand): string {
+  const opt = (o: ProjectedOption): unknown => [o.name, o.description, o.type, o.required, o.min_value ?? null, o.max_value ?? null, o.options.map(opt)];
+  return JSON.stringify([command.name, command.type, command.description, command.options.map(opt)]);
+}
+
+export interface DiscordCommandDrift {
+  /** Does Discord need a write for this command? */
+  readonly changed: boolean;
+  /** Why — one id-free line for the boot log. */
+  readonly reason: string;
+}
+
+/**
+ * Compare the command this deployment DECLARES against the list Discord HOLDS at one scope.
+ *
+ * `held` is the raw array Discord's GET returned. Only the entry whose name matches the declared
+ * command is considered: every other command at that scope belongs to someone else and this plane
+ * neither reads nor writes it.
+ */
+export function discordCommandDrift(declared: unknown, held: unknown): DiscordCommandDrift {
+  const want = projectCommand(declared);
+  if (want === undefined) {
+    // A declaration this file cannot project is a code defect, not a vendor state. Refusing to write
+    // is the safe half: a bad body would replace a working command with a broken one.
+    return { changed: false, reason: "the declared command has no name — nothing was compared and nothing will be written" };
+  }
+  const list = Array.isArray(held) ? held : [];
+  const mine = list.map((entry) => projectCommand(entry)).find((entry) => entry !== undefined && entry.name === want.name);
+  if (mine === undefined) {
+    return { changed: true, reason: `"/${want.name}" is not registered at this scope` };
+  }
+  if (canonical(mine) !== canonical(want)) {
+    return { changed: true, reason: `"/${want.name}" is registered with a different shape` };
+  }
+  return { changed: false, reason: `"/${want.name}" already matches what this deployment declares` };
+}
+
+export interface DiscordCommandSyncDeps {
+  readonly fetch?: DiscordFetchLike;
+  /** Overrides the env reads. Live boot passes neither; a test passes both. */
+  readonly applicationId?: string;
+  readonly botToken?: string;
+  /** The ceiling on ONE call. Defaults to {@link CALL_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+  /** The ceiling on the WHOLE reconcile. Defaults to {@link RECONCILE_BUDGET_MS}. */
+  readonly budgetMs?: number;
+}
+
+interface ScopeResult {
+  readonly status: "unchanged" | "updated" | "failed";
+  readonly detail: string;
+}
+
+/** Read + compare + (only on a difference) write, for ONE guild. Never throws. `msLeft` is what is
+ *  left of the whole reconcile's budget, so no single guild can spend more than the rest of them. */
+async function reconcileOneGuild(
+  guildId: string,
+  applicationId: string,
+  botToken: string,
+  deps: DiscordCommandSyncDeps,
+  msLeft: () => number,
+): Promise<ScopeResult> {
+  const declared = buildOeDiscordCommandDefinition();
+  const url = `${API_BASE}/applications/${applicationId}/guilds/${guildId}/commands`;
+  const headers = { authorization: `Bot ${botToken}`, "content-type": "application/json" };
+  const cap = deps.timeoutMs ?? CALL_TIMEOUT_MS;
+  const fetchDeps = { ...(deps.fetch ? { fetch: deps.fetch } : {}), retry: BOOT_RETRY };
+  /** This call's own ceiling: the per-call cap, or whatever is left of the reconcile's budget. */
+  const nextTimeout = (): number => Math.min(cap, msLeft());
+
+  if (nextTimeout() <= 0) {
+    return { status: "failed", detail: `guild ${guildId}: the boot budget was already spent on an earlier guild — read again on the next start` };
+  }
+
+  let held: unknown;
+  try {
+    const res = await discordFetch("GET /applications/{id}/guilds/{id}/commands", url, { method: "GET", headers, signal: AbortSignal.timeout(nextTimeout()) }, fetchDeps);
+    if (!res.ok) return { status: "failed", detail: `guild ${guildId}: the command list read returned ${res.status}` };
+    held = await res.json();
+  } catch (err) {
+    return { status: "failed", detail: `guild ${guildId}: the command list read failed (${err instanceof Error ? err.name : "error"})` };
+  }
+
+  const drift = discordCommandDrift(declared, held);
+  if (!drift.changed) return { status: "unchanged", detail: `guild ${guildId}: ${drift.reason}` };
+
+  if (nextTimeout() <= 0) {
+    return { status: "failed", detail: `guild ${guildId}: ${drift.reason}, and the boot budget was spent before the write — retried on the next start` };
+  }
+
+  try {
+    // CREATE-OR-UPDATE BY NAME. Discord treats a POST naming an existing command as an update of
+    // that command, and touches nothing else at the scope — see the header on why the bulk PUT is
+    // wrong here.
+    const res = await discordFetch(
+      "POST /applications/{id}/guilds/{id}/commands",
+      url,
+      { method: "POST", headers, body: JSON.stringify(declared), signal: AbortSignal.timeout(nextTimeout()) },
+      fetchDeps,
+    );
+    if (!res.ok) return { status: "failed", detail: `guild ${guildId}: ${drift.reason}, and the write returned ${res.status}` };
+    return { status: "updated", detail: `guild ${guildId}: ${drift.reason} — registered` };
+  } catch (err) {
+    return { status: "failed", detail: `guild ${guildId}: ${drift.reason}, and the write failed (${err instanceof Error ? err.name : "error"})` };
+  }
+}
+
+/**
+ * THE RECONCILER the discord bundle registers with core's command plane.
+ *
+ * Runs at boot, so it is gated on BOTH deployment credentials being present: `DISCORD_APPLICATION_ID`
+ * says which app this is and `DISCORD_BOT_TOKEN` authenticates the call. Either missing ⇒ `skipped`,
+ * which is the correct reading of a deployment that carries the bundle but no Discord app — and it is
+ * also what keeps every offline test tier network-free, since no test publishes an application id.
+ *
+ * 🔴 THESE TWO STAY ENV. They are the credential pair this deployment speaks as, which is exactly the
+ * `secret`/`identity` half of the config-as-code line. The GUILD ids do not: they are tracked literals
+ * in `agent/commands/discord-commands.ts` and arrive here as the declared scope.
+ */
+export async function reconcileDiscordCommands(scope: SurfaceCommandScope, deps: DiscordCommandSyncDeps = {}): Promise<SurfaceCommandOutcome> {
+  const applicationId = deps.applicationId ?? process.env.DISCORD_APPLICATION_ID;
+  const botToken = deps.botToken ?? process.env.DISCORD_BOT_TOKEN;
+  if (!applicationId || !botToken) {
+    return {
+      status: "skipped",
+      detail: "DISCORD_APPLICATION_ID and DISCORD_BOT_TOKEN must both be set for this deployment to register its own commands.",
+    };
+  }
+
+  const deadline = Date.now() + (deps.budgetMs ?? RECONCILE_BUDGET_MS);
+  const msLeft = (): number => deadline - Date.now();
+  const results: ScopeResult[] = [];
+  for (const guildId of scope.scopes) {
+    results.push(await reconcileOneGuild(guildId, applicationId, botToken, deps, msLeft));
+  }
+  const detail = results.map((r) => r.detail).join("; ");
+  // A failure on ANY guild is the outcome, even when another guild succeeded: the boot log must not
+  // read green while one room is still missing the command.
+  if (results.some((r) => r.status === "failed")) return { status: "failed", detail };
+  if (results.some((r) => r.status === "updated")) return { status: "updated", detail };
+  return { status: "unchanged", detail };
+}