mercury-agent 0.8.12 → 0.9.1

package/docs/authoring-profiles.md

@@ -136,6 +136,14 @@ the extension's `SKILL.md` or the profile's `AGENTS.md`.
 - **`member_permissions` is exhaustive.** List every permission a member may
   hold, including the capability name (e.g. `rooms`). Anything not listed —
   including raw capabilities like `gws` — is unavailable to members.
+  One back-compat exception: a list that mentions neither `media.receive` nor
+  `media.send` gets both appended at load time (media exchange predates these
+  permissions, so their absence carries no revocation intent). To restrict
+  media for members, list at least one of them explicitly — a list mentioning
+  either is taken verbatim. `media.purge` does not count as an opt-out.
+  Known limitation: denying *both* media permissions cannot be expressed in a
+  profile list (mentioning one grants it; mentioning neither appends both) —
+  use a per-space override (`mrctl permissions set member …`) for a full deny.
 - **Authorization = permission named after the capability.** The broker route
   requires the caller to hold the `<name>` permission; the same grant gates both
   the `mrctl capability <name> …` CLI and the route. Keep capability name =

package/docs/media/overview.md

@@ -48,6 +48,15 @@ interface MessageAttachment {
 | `MERCURY_MEDIA_ENABLED` | `true` | Enable/disable media downloads |
 | `MERCURY_MEDIA_MAX_SIZE_MB` | `10` | Max file size to download (MB) |
 
+## Permission Gating
+
+The pipeline is gated per caller role, per space by two built-in permissions (both granted to `member` by default — see [permissions.md](../permissions.md)):
+
+- **`media.receive`** — when the caller's role lacks it, incoming files are deleted from `inbox/` before the container runs and dropped from the stored message. The message text still goes through, and the agent receives a system note that files arrived but were blocked. Covers all media types including voice notes (revoking it disables voice transcription for that role).
+- **`media.send`** — when the caller's role lacks it, files produced during that caller's turn are not delivered; the reply carries a one-line notice. The files stay in `outbox/` (TTL cleanup applies).
+
+`admin` and `system` callers (scheduled tasks) are exempt. Gating is per-caller-turn: in a shared group, a blocked member's turns are gated while an admin's turns deliver files normally. Bridges still download media before routing — the write is transient; the gate deletes it before the message is saved or any agent code runs.
+
 ## Storage
 
 ### Ingress (inbox/)

package/docs/permissions.md

@@ -28,7 +28,7 @@ Message arrives
 |------|---------------------|-------------|
 | `system` | All | Internal system caller (scheduler, etc.) — not assignable |
 | `admin` | All | Full control over the space |
-| `member` | `prompt`, `prefs.get` | Can chat and read space preferences (default for new users) |
+| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send` | Can chat, read space preferences, and exchange files (default for new users) |
 
 Custom roles can be created by assigning permissions to any role name.
 
@@ -56,6 +56,19 @@ Custom roles can be created by assigning permissions to any role name.
 | `spaces.list` | View all spaces |
 | `spaces.rename` | Rename a space and link/unlink conversations |
 | `spaces.delete` | Delete current space and all related DB data |
+| `media.receive` | Incoming attachments are saved to `inbox/` and shown to the agent |
+| `media.send` | Outbox files produced on this caller's turn are delivered back to the chat |
+
+### Media permissions
+
+`media.receive` and `media.send` gate the media pipeline per caller role, per space. Both are granted to `member` by default, so behavior is unchanged unless an operator revokes them (e.g. `mrctl permissions set member prompt,prefs.get` — omitting the media names revokes them in that space).
+
+Denials are never silent:
+
+- **Blocked receive** — the caller's inbox files are deleted from disk before the container runs and dropped from the stored message; the message text still goes through, and the agent is told via a system note that files arrived but were blocked. `media.receive` covers all media types, including voice notes — revoking it also disables voice-message transcription for that role.
+- **Blocked send** — files produced during that caller's turn are not delivered; the reply carries a one-line notice. The files remain in `outbox/` for admin retrieval until TTL cleanup removes them.
+
+`admin` and `system` callers (scheduled tasks) are always exempt — the gates never fire for them. Lists that predate these permissions (profile manifests, stored per-space overrides, operator `defaultMemberPermissions` configs) get both names appended automatically for backwards compatibility; a list that mentions either name is taken verbatim (`media.purge` predates the pair and does not count as an opt-out).
 
 ## Mutes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.8.12",
+  "version": "0.9.1",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -93,7 +93,7 @@
     "commander": "^14.0.3",
     "cron-parser": "^5.5.0",
     "discord.js": "^14.26.3",
-    "hono": "^4.12.25",
+    "hono": "^4.12.34",
     "qrcode-terminal": "^0.12.0",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"

package/resources/templates/mercury.example.yaml

@@ -87,6 +87,13 @@
 #   default_system_prompt: ""                   # seeded into auto-created user spaces
 #   default_member_permissions: "prompt,prefs.get"  # restrict users to chat only
 
+# ─── System messages ────────────────────────────────────────────────────────
+# Deployment-wide default language for Mercury-generated system messages
+# (rate-limit denials, error messages, permission denials). Overridable
+# per-space from the dashboard or chat: mrctl config set messages.locale he
+# messages:
+#   locale: en                    # en | he
+
 # ─── Extension config defaults ──────────────────────────────────────────────
 # Deployment-wide defaults for extension config keys, applied to every space
 # (incl. auto-created DM spaces) unless overridden per-space or in the

package/src/agent/user-error-messages.ts

@@ -1,3 +1,8 @@
+import {
+  formatSystemMessage,
+  type MessageLocale,
+} from "../core/system-messages.js";
+
 export type UserErrorCategory =
   | "auth"
   | "key-limit"
@@ -28,50 +33,19 @@ export function classifyUserError(errorText: string): UserErrorCategory {
   return "generic";
 }
 
-const MESSAGES: Record<UserErrorCategory, { platform: string; byok: string }> =
-  {
-    "key-limit": {
-      platform: "I've reached my usage limit for now. Please try again later.",
-      byok: "Your API key has hit its spending limit. Check your provider's key settings to increase it.",
-    },
-    "rate-limit": {
-      platform:
-        "I'm handling too many requests right now — please try again in a moment.",
-      byok: "Your API key is being rate-limited. Try again in a moment.",
-    },
-    auth: {
-      platform:
-        "Something went wrong on my end. This has been logged and the admin will be notified.",
-      byok: "Your API key appears to be invalid or expired. Please update it.",
-    },
-    credits: {
-      platform: "I've reached my usage limit for now. Please try again later.",
-      byok: "Your API provider account has insufficient credits. Add credits to continue.",
-    },
-    "server-error": {
-      platform:
-        "The AI service is temporarily unavailable. Please try again in a few minutes.",
-      byok: "The AI service is temporarily unavailable. Please try again in a few minutes.",
-    },
-    generic: {
-      platform:
-        "Something went wrong processing your request. Please try again.",
-      byok: "Something went wrong processing your request. Please try again, or check your API key and provider status.",
-    },
-  };
-
 export function friendlyErrorMessage(
   category: UserErrorCategory,
   mode: "platform" | "byok",
   consoleUrl?: string,
+  locale: MessageLocale = "en",
 ): string {
-  let message = MESSAGES[category][mode];
+  let message = formatSystemMessage(locale, `err_${category}_${mode}`);
   const base = consoleUrl?.replace(/\/+$/, "");
   if (base && mode === "platform") {
     if (category === "key-limit" || category === "credits") {
-      message += `\n\nUpgrade your plan: ${base}/dashboard/billing`;
+      message += `\n\n${formatSystemMessage(locale, "err_upgrade_suffix", { url: base })}`;
     } else if (category === "auth") {
-      return `Your Anthropic session has expired. Please reconnect: ${base}/dashboard/model`;
+      return formatSystemMessage(locale, "err_session_expired", { url: base });
     }
   }
   return message;

package/src/config-file.ts

@@ -166,6 +166,13 @@ const mercuryFileSchema = z
       .strip()
       .optional(),
 
+    messages: z
+      .object({
+        locale: z.enum(["en", "he"]).optional(),
+      })
+      .strip()
+      .optional(),
+
     dm_auto_space: z
       .object({
         enabled: z.boolean().optional(),
@@ -211,6 +218,7 @@ const KNOWN_TOP_KEYS = new Set([
   "telegram",
   "media",
   "permissions",
+  "messages",
   "dm_auto_space",
   "extensions",
 ]);
@@ -254,6 +262,7 @@ const KNOWN_SECTION_KEYS: Record<string, Set<string>> = {
   telegram: new Set(["format_enabled"]),
   media: new Set(["enabled", "max_size_mb"]),
   permissions: new Set(["admins"]),
+  messages: new Set(["locale"]),
   dm_auto_space: new Set([
     "enabled",
     "admin_ids",
@@ -407,6 +416,8 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
 
   if (f.permissions?.admins != null) o.admins = f.permissions.admins;
 
+  if (f.messages?.locale != null) o.messagesLocale = f.messages.locale;
+
   if (f.dm_auto_space?.enabled != null) {
     o.dmAutoSpaceEnabled = f.dm_auto_space.enabled;
   }
@@ -484,6 +495,7 @@ const CAMEL_TO_ENV: Record<string, string> = {
   mediaEnabled: "MERCURY_MEDIA_ENABLED",
   mediaMaxSizeMb: "MERCURY_MEDIA_MAX_SIZE_MB",
   admins: "MERCURY_ADMINS",
+  messagesLocale: "MERCURY_MESSAGES_LOCALE",
   profile: "MERCURY_PROFILE",
   apiSecret: "MERCURY_API_SECRET",
   callerTokenKey: "MERCURY_CALLER_TOKEN_KEY",

package/src/config.ts

@@ -221,6 +221,14 @@ const schema = z.object({
   // ─── Permissions ────────────────────────────────────────────────────
   admins: z.string().default(""),
 
+  // ─── System Messages ────────────────────────────────────────────────
+  /**
+   * Deployment-wide default locale for host-generated system messages
+   * (rate-limit denials, error messages, permission denials). Overridable
+   * per-space via the `messages.locale` space config key. Env: MERCURY_MESSAGES_LOCALE.
+   */
+  messagesLocale: z.enum(["en", "he"]).default("en"),
+
   // ─── Applicative Profile ────────────────────────────────────────────
   /**
    * Name of the active applicative profile (informational at runtime; the

package/src/core/conversation.ts

@@ -1,6 +1,7 @@
 import { logger } from "../logger.js";
 import type { Db } from "../storage/db.js";
 import type { Conversation } from "../types.js";
+import { withMediaBackCompat } from "./permissions.js";
 
 export interface ConversationResolution {
   conversation: Conversation;
@@ -159,11 +160,17 @@ export function resolveConversation(
   seedSpaceConfigIfAbsent(db, spaceId, "context.mode", "context");
   seedSpaceConfigIfAbsent(db, spaceId, "debounce.idle_timeout_ms", "2000");
   if (autoSpace.defaultMemberPermissions) {
+    // Seed-time back-compat: an operator config authored before the media
+    // permissions existed must not deny media in newly auto-created spaces
+    // while migrated older spaces allow it. A list mentioning either media
+    // transfer name is an explicit choice and is seeded verbatim.
     seedSpaceConfigIfAbsent(
       db,
       spaceId,
       "role.member.permissions",
-      autoSpace.defaultMemberPermissions,
+      withMediaBackCompat(
+        autoSpace.defaultMemberPermissions.split(",").map((s) => s.trim()),
+      ).join(","),
     );
   }
   if (autoSpace.defaultSystemPrompt) {

package/src/core/media-gate.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../logger.js";
+import type { EgressFile, MessageAttachment } from "../types.js";
+
+/**
+ * Enforcement helpers for the `media.receive` / `media.send` permissions.
+ *
+ * Pure with respect to permission resolution: callers decide whether the
+ * caller's role holds the permission and only invoke these on denial. Denials
+ * are never silent — the receive gate tells the agent via a prompt note, the
+ * send gate tells the user via a reply notice, and both log at WARN.
+ */
+
+export interface IncomingMediaGateResult {
+  /** Attachments to persist/prompt with — undefined when blocked. */
+  attachments: MessageAttachment[] | undefined;
+  /** System note to append to the agent prompt, or null when nothing was blocked. */
+  promptNote: string | null;
+}
+
+/**
+ * Apply a `media.receive` denial: delete the caller's inbox files from disk
+ * (before the container mounts the workspace) and drop the attachments from
+ * the message.
+ *
+ * Deletion is workspace-scoped: only paths resolving inside
+ * `<workspacePath>/inbox/` are deleted; anything else is logged and skipped.
+ * FS errors are logged and the attachment is still dropped — the inbox TTL
+ * cleanup is the backstop.
+ */
+export function gateIncomingMedia(opts: {
+  workspacePath: string;
+  spaceId: string;
+  callerRole: string;
+  attachments: MessageAttachment[] | undefined;
+  hadIncomingAttachments: boolean;
+}): IncomingMediaGateResult {
+  const { workspacePath, spaceId, callerRole, attachments } = opts;
+  const count = attachments?.length ?? 0;
+
+  if (count === 0 && !opts.hadIncomingAttachments) {
+    return { attachments, promptNote: null };
+  }
+
+  const inboxRoot = path.resolve(workspacePath, "inbox");
+  for (const att of attachments ?? []) {
+    const resolved = path.resolve(workspacePath, att.path);
+    // Strictly inside inbox/ — the inbox root itself is never a deletion target.
+    if (!resolved.startsWith(inboxRoot + path.sep)) {
+      logger.warn(
+        "media.receive gate: attachment path outside workspace inbox, not deleting",
+        { spaceId, path: att.path },
+      );
+      continue;
+    }
+    try {
+      fs.rmSync(resolved, { force: true });
+    } catch (error) {
+      logger.warn("media.receive gate: failed to delete inbox file", {
+        spaceId,
+        path: att.path,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  logger.warn("Blocked incoming media (role lacks media.receive)", {
+    spaceId,
+    callerRole,
+    count,
+  });
+
+  // count === 0 means the platform reported attachments but nothing was
+  // persisted upstream (media disabled, size limit, download failure) — don't
+  // attribute that solely to the permission.
+  const promptNote =
+    count > 0
+      ? `[system] The user sent ${count} ${count === 1 ? "file" : "files"} with this message, but file receiving is disabled ` +
+        `for their role, so the ${count === 1 ? "file was" : "files were"} not kept and cannot be read. ` +
+        `If relevant, let the user know that sending files is not available to them.`
+      : `[system] The user attempted to send one or more files with this message, but they were not received ` +
+        `(file receiving is disabled for their role, or the files could not be downloaded). ` +
+        `If relevant, let the user know that sending files is not available to them.`;
+  return { attachments: undefined, promptNote };
+}
+
+export interface OutgoingMediaGateResult {
+  /** Files to deliver — empty when blocked. */
+  files: EgressFile[];
+  /** Reply text, with a withhold notice appended when files were blocked. */
+  reply: string;
+}
+
+/**
+ * Apply a `media.send` denial: withhold this turn's outbox files and append a
+ * one-line notice to the reply. Files stay in `outbox/` for admin retrieval;
+ * the outbox TTL cleanup removes them later.
+ */
+export function gateOutgoingMedia(opts: {
+  spaceId: string;
+  callerRole: string;
+  files: EgressFile[];
+  reply: string;
+}): OutgoingMediaGateResult {
+  const { spaceId, callerRole, files, reply } = opts;
+  if (files.length === 0) return { files, reply };
+
+  logger.warn("Withheld outgoing media (role lacks media.send)", {
+    spaceId,
+    callerRole,
+    count: files.length,
+  });
+
+  const noun = files.length === 1 ? "file was" : "files were";
+  const notice = `(${files.length} generated ${noun} not delivered because file delivery is disabled for your role.)`;
+  return {
+    files: [],
+    reply: reply ? `${reply}\n\n${notice}` : notice,
+  };
+}

package/src/core/permissions.ts

@@ -1,3 +1,4 @@
+import { logger } from "../logger.js";
 import type { Db } from "../storage/db.js";
 import { matchesConfiguredId } from "./global-admin.js";
 
@@ -29,6 +30,10 @@ const BUILT_IN_PERMISSIONS = new Set([
   "spaces.delete",
   /** Purge inbox/outbox media files. */
   "media.purge",
+  /** Incoming attachments are saved to inbox/ and shown to the agent. */
+  "media.receive",
+  /** Outbox files produced on this caller's turn are delivered back. */
+  "media.send",
   /** Host Text-to-Speech (/api/tts); admin-only by default. */
   "tts.synthesize",
   /** Mute/unmute users and list mutes; admin-only by default. */
@@ -103,6 +108,23 @@ export function setActiveProfileMemberPermissions(
   activeProfileMemberPermissions = permissions;
 }
 
+/**
+ * Back-compat for permission lists authored before `media.receive` /
+ * `media.send` existed: media exchange used to be ungated, so a list that
+ * doesn't mention either name carries no revocation intent — append both to
+ * preserve behavior. A list mentioning either one has decided explicitly and
+ * is returned verbatim. `media.purge` predates this feature and is NOT an
+ * opt-out signal.
+ */
+export function withMediaBackCompat(permissions: string[]): string[] {
+  const mentionsMediaTransfer = permissions.some((p) => {
+    const t = p.trim();
+    return t === "media.receive" || t === "media.send";
+  });
+  if (mentionsMediaTransfer) return permissions;
+  return [...permissions, "media.receive", "media.send"];
+}
+
 /** Parse a permission list into a validated set (drops unknown names). */
 function toPermissionSet(list: string[]): Set<string> {
   return new Set(list.map((s) => s.trim()).filter((s) => isValidPermission(s)));
@@ -118,6 +140,36 @@ function toPermissionSet(list: string[]): Set<string> {
  */
 export const seededSpaces = new Set<string>();
 
+/**
+ * (space, caller) pairs whose config-admin re-promotion was already logged —
+ * once per process, not per message (resolveRole runs on every message).
+ * Exported for test isolation (tests should clear this in beforeEach).
+ */
+export const warnedRepromotions = new Set<string>();
+
+/**
+ * A stored non-admin role was overridden back to admin because the caller is
+ * listed in config.admins. The override is deliberate (config admins are
+ * always admins), but it must be visible: an operator's explicit demotion
+ * otherwise silently doesn't hold. Deduped once per (space, caller) per
+ * process.
+ */
+function warnConfigAdminRepromotion(
+  spaceId: string,
+  callerId: string,
+  source: "re-seed" | "self-heal",
+): void {
+  // NUL separator: caller ids contain ":" (e.g. "whatsapp:..."), so a ":"
+  // join could collide distinct (space, caller) pairs.
+  const key = `${spaceId}\u0000${callerId}`;
+  if (warnedRepromotions.has(key)) return;
+  warnedRepromotions.add(key);
+  logger.warn(
+    "Config admin re-promoted: stored role overridden — remove from config.admins to demote",
+    { spaceId, callerId, source },
+  );
+}
+
 // ---------------------------------------------------------------------------
 // System callers
 // ---------------------------------------------------------------------------
@@ -137,14 +189,19 @@ export function isSystemCaller(callerId: string): boolean {
 // ---------------------------------------------------------------------------
 
 /** Built-in defaults for the member role */
-const DEFAULT_MEMBER_PERMISSIONS = new Set(["prompt", "prefs.get"]);
+const DEFAULT_MEMBER_PERMISSIONS = new Set([
+  "prompt",
+  "prefs.get",
+  "media.receive",
+  "media.send",
+]);
 
 /**
  * Compute the default permission set for a role, merging built-in defaults
  * with extension-registered defaults.
  *
  * - `admin` and `system` get all permissions (built-in + extension)
- * - `member` gets `prompt`, `prefs.get`, plus any extension permissions that list "member" in defaultRoles
+ * - `member` gets `prompt`, `prefs.get`, `media.receive`, `media.send`, plus any extension permissions that list "member" in defaultRoles
  * - Other roles get extension permissions that list them in defaultRoles
  */
 function getDefaultPermissions(role: string): Set<string> {
@@ -226,13 +283,19 @@ export function resolveRole(
   if (isSystemCaller(platformUserId)) return "system";
 
   if (seededAdmins.length > 0 && !seededSpaces.has(spaceId)) {
-    db.seedAdmins(spaceId, seededAdmins);
+    for (const id of db.seedAdmins(spaceId, seededAdmins)) {
+      warnConfigAdminRepromotion(spaceId, id, "re-seed");
+    }
     seededSpaces.add(spaceId);
   }
 
+  // Read before upsertMember, which inserts a fresh "member" row on first
+  // contact — a null here distinguishes "never seen" from "operator demoted".
+  const storedRole = db.getRole(spaceId, platformUserId);
+
   db.upsertMember(spaceId, platformUserId, displayName);
 
-  const role = db.getRole(spaceId, platformUserId) ?? "member";
+  const role = storedRole ?? "member";
 
   // Seeded rows are keyed by the raw config string, which may differ from the
   // canonical caller id (format looseness, WhatsApp LID vs phone JID). When the
@@ -243,6 +306,11 @@ export function resolveRole(
     role === "member" &&
     matchesConfiguredId(platformUserId, seededAdmins, db)
   ) {
+    // Warn only when a member row pre-existed (a stored demotion being
+    // overridden) — a first-contact self-heal has nothing to override.
+    if (storedRole === "member") {
+      warnConfigAdminRepromotion(spaceId, platformUserId, "self-heal");
+    }
     db.setRole(spaceId, platformUserId, "admin", "seed");
     return "admin";
   }

package/src/core/profiles.ts

@@ -12,6 +12,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
+import { withMediaBackCompat } from "./permissions.js";
 
 // ─── Profile Schema ───────────────────────────────────────────────────────
 
@@ -208,7 +209,13 @@ export function loadActiveProfile(dataDir: string): ActiveProfile | null {
     const raw = JSON.parse(readFileSync(file, "utf-8"));
     return {
       name: raw.name,
-      memberPermissions: raw.memberPermissions ?? null,
+      // Load-time back-compat: profile manifests authored before the media
+      // permissions existed must keep member media working. Applied here (not
+      // at persist time) so already-deployed active-profile.json files are
+      // covered on every startup.
+      memberPermissions: Array.isArray(raw.memberPermissions)
+        ? withMediaBackCompat(raw.memberPermissions)
+        : null,
       profilePrompt: raw.profilePrompt ?? raw.systemPrompt ?? null,
     };
   } catch {

package/src/core/router.ts

@@ -3,6 +3,11 @@ import type { Db } from "../storage/db.js";
 import type { MessageAttachment } from "../types.js";
 import { SLASH_COMMANDS } from "./commands.js";
 import { hasPermission, resolveRole } from "./permissions.js";
+import {
+  formatSystemMessage,
+  type MessageLocale,
+  resolveLocale,
+} from "./system-messages.js";
 import { loadTriggerConfig, matchTrigger } from "./trigger.js";
 
 export type RouteResult =
@@ -125,6 +130,7 @@ export function routeInput(input: {
         input.callerId,
         input.isDM,
         seededAdmins,
+        resolveLocale(input.db, input.config, input.spaceId),
         verb,
         arg,
       );
@@ -134,14 +140,24 @@ export function routeInput(input: {
   // Check for commands after trigger (e.g. "@Pi stop", "Pi compact")
   const cmdWord = prompt.toLowerCase().trim();
   if (cmdWord in CHAT_COMMANDS) {
-    return gateCommand(input.db, input.spaceId, cmdWord, role, input.callerId);
+    return gateCommand(
+      input.db,
+      input.spaceId,
+      cmdWord,
+      role,
+      input.callerId,
+      resolveLocale(input.db, input.config, input.spaceId),
+    );
   }
 
   // Check prompt permission
   if (!hasPermission(input.db, input.spaceId, role, "prompt")) {
     return {
       type: "denied",
-      reason: "You don't have permission to use the agent in this group.",
+      reason: formatSystemMessage(
+        resolveLocale(input.db, input.config, input.spaceId),
+        "no_permission_prompt",
+      ),
     };
   }
 
@@ -163,6 +179,7 @@ function gateSlashCommand(
   callerId: string,
   isDM: boolean,
   seededAdmins: string[],
+  locale: MessageLocale,
   verb?: string,
   arg?: string,
 ): RouteResult {
@@ -170,7 +187,7 @@ function gateSlashCommand(
     if (!seededAdmins.includes(callerId)) {
       return {
         type: "denied",
-        reason: `You don't have permission to use '/${command}'.`,
+        reason: formatSystemMessage(locale, "no_permission_slash", { command }),
       };
     }
     return { type: "command", command, verb, arg, callerId, role };
@@ -178,13 +195,13 @@ function gateSlashCommand(
   if (!isDM && role !== "admin" && role !== "system") {
     return {
       type: "denied",
-      reason: "Slash commands are only available to admins in groups.",
+      reason: formatSystemMessage(locale, "slash_admin_only"),
     };
   }
   if (!hasPermission(db, spaceId, role, "prompt")) {
     return {
       type: "denied",
-      reason: `You don't have permission to use '/${command}'.`,
+      reason: formatSystemMessage(locale, "no_permission_slash", { command }),
     };
   }
   return { type: "command", command, verb, arg, callerId, role };
@@ -196,6 +213,7 @@ function gateCommand(
   command: string,
   role: string,
   callerId: string,
+  locale: MessageLocale,
 ): RouteResult {
   const permission = CHAT_COMMANDS[command];
   if (!permission) return { type: "ignore" };
@@ -203,7 +221,7 @@ function gateCommand(
   if (!hasPermission(db, spaceId, role, permission)) {
     return {
       type: "denied",
-      reason: `You don't have permission to use '${command}'.`,
+      reason: formatSystemMessage(locale, "no_permission_command", { command }),
     };
   }
 

package/src/core/routes/chat.ts

@@ -147,7 +147,14 @@ export function createChatRoute(core: MercuryCoreRuntime): Hono {
     }
 
     if (authenticated) {
-      core.db.seedAdmins(spaceId, [callerId]);
+      // Fires at most once per actual override: after the re-promotion the
+      // row is admin again, so later requests return an empty list.
+      for (const id of core.db.seedAdmins(spaceId, [callerId])) {
+        logger.warn(
+          "Authenticated chat caller re-promoted: stored role overridden",
+          { spaceId, callerId: id },
+        );
+      }
     }
 
     const ingress: IngressMessage = {

package/src/core/routes/config-builtin.ts

@@ -14,6 +14,7 @@ export const BUILTIN_CONFIG_KEYS = new Set([
   "rate_limit.member",
   "rate_limit.admin",
   "debounce.idle_timeout_ms",
+  "messages.locale",
 ]);
 
 /**
@@ -49,6 +50,8 @@ export const BUILTIN_CONFIG_DESCRIPTIONS: Record<string, string> = {
     "Daily message cap for admins in this space. Overrides global rate_limit_daily_admin. Integer ≥ 1, or 0 for unlimited.",
   "debounce.idle_timeout_ms":
     "Milliseconds to wait for additional messages before processing a batch. 0 disables debounce. Platform default: 2000 for WhatsApp/Telegram, 0 for others.",
+  "messages.locale":
+    "Language for Mercury-generated system messages (rate limits, errors, denials) in this space: 'en' or 'he'. Unset falls back to the deployment default.",
 };
 
 const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
@@ -112,6 +115,10 @@ const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
       ? null
       : "Invalid debounce.idle_timeout_ms value. Must be an integer between 0 and 10000";
   },
+  "messages.locale": (v) =>
+    ["en", "he"].includes(v)
+      ? null
+      : "Invalid messages.locale value. Valid: en, he",
 };
 
 export function isBuiltinConfigKey(key: string): boolean {