mercury-agent 0.8.12 → 0.9.0

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.0",
   "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

@@ -29,6 +29,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 +107,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)));
@@ -137,14 +158,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> {

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/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 {

package/src/core/runtime.ts

@@ -30,11 +30,17 @@ import {
   DirectSendError,
   resolveRecipientSpaceId,
 } from "./direct-send.js";
+import { gateIncomingMedia, gateOutgoingMedia } from "./media-gate.js";
 import { hasPermission, resolveRole } from "./permissions.js";
 import { getActiveProfilePrompt } from "./profiles.js";
 import { RateLimiter } from "./rate-limiter.js";
 import { type RouteResult, routeInput } from "./router.js";
 import { SpaceQueue } from "./space-queue.js";
+import {
+  confirmWords,
+  formatSystemMessage,
+  resolveLocale,
+} from "./system-messages.js";
 import { TaskScheduler } from "./task-scheduler.js";
 
 export type InputSource = "cli" | "scheduler" | "chat-sdk";
@@ -204,6 +210,8 @@ export class MercuryCoreRuntime {
     const sensitiveName = this.getActiveSensitiveConnectionName();
     if (!sensitiveName) return { action: "proceed" };
 
+    const locale = resolveLocale(this.db, this.config, spaceId);
+
     const allowed = this.db.getSpaceConfig(
       spaceId,
       "security.sensitive_connections_allowed",
@@ -211,7 +219,9 @@ export class MercuryCoreRuntime {
     if (allowed !== "true") {
       return {
         action: "block",
-        reason: `⛔ Sensitive integrations (${sensitiveName}) are disabled for this group space. A space admin must enable them first with: mrctl config set security.sensitive_connections_allowed true`,
+        reason: formatSystemMessage(locale, "sensitive_disabled", {
+          name: sensitiveName,
+        }),
       };
     }
 
@@ -223,16 +233,20 @@ export class MercuryCoreRuntime {
       const ageMs = Date.now() - new Date(pendingAt).getTime();
       const expired = Number.isNaN(ageMs) || ageMs > 5 * 60 * 1000;
       const text = prompt.trim().toLowerCase();
+      const words = confirmWords(locale);
 
-      if (expired || text === "no") {
+      if (expired || words.no.includes(text)) {
         this.db.deleteSpaceConfig(spaceId, "security.pending_sensitive_prompt");
         this.db.deleteSpaceConfig(spaceId, "security.pending_sensitive_at");
         if (expired) {
           // Treat next message as fresh — fall through to new warning below
         } else {
-          return { action: "block", reason: "Cancelled." };
+          return {
+            action: "block",
+            reason: formatSystemMessage(locale, "sensitive_cancelled"),
+          };
         }
-      } else if (text === "yes") {
+      } else if (words.yes.includes(text)) {
         const storedPrompt = this.db.getSpaceConfig(
           spaceId,
           "security.pending_sensitive_prompt",
@@ -261,7 +275,9 @@ export class MercuryCoreRuntime {
     );
     return {
       action: "block",
-      reason: `⚠️ This response may contain data from ${sensitiveName} and will be visible to all members of this group. Reply *yes* to proceed or *no* to cancel.`,
+      reason: formatSystemMessage(locale, "sensitive_confirm", {
+        name: sensitiveName,
+      }),
     };
   }
 
@@ -541,7 +557,11 @@ export class MercuryCoreRuntime {
               const hoursLeft = Math.ceil(msUntilReset / 3_600_000);
               return {
                 type: "denied",
-                reason: `You've used ${daily.count}/${roleLimit} messages today. Resets in ${hoursLeft}h.`,
+                reason: formatSystemMessage(
+                  resolveLocale(this.db, this.config, message.spaceId),
+                  "rate_limit_daily",
+                  { count: daily.count, limit: roleLimit, hours: hoursLeft },
+                ),
               };
             }
           }
@@ -560,7 +580,10 @@ export class MercuryCoreRuntime {
       ) {
         return {
           type: "denied",
-          reason: "Rate limit exceeded. Try again shortly.",
+          reason: formatSystemMessage(
+            resolveLocale(this.db, this.config, message.spaceId),
+            "rate_limit_burst",
+          ),
         };
       }
     }
@@ -598,8 +621,10 @@ export class MercuryCoreRuntime {
     ) {
       return {
         type: "denied",
-        reason:
-          "Could not use your attachment (media disabled, over the size limit, or download failed). Check MERCURY_MEDIA_ENABLED and logs.",
+        reason: formatSystemMessage(
+          resolveLocale(this.db, this.config, message.spaceId),
+          "attachment_failed",
+        ),
       };
     }
 
@@ -626,20 +651,31 @@ export class MercuryCoreRuntime {
           replyToPlatformMessageId: message.replyToPlatformMessageId,
           platformMessageId: message.platformMessageId,
         },
-        { isReplyToBot: route.isReplyToBot, isDM: route.isDM },
+        {
+          isReplyToBot: route.isReplyToBot,
+          isDM: route.isDM,
+          hadIncomingAttachments: message.hadIncomingAttachments ?? false,
+        },
       );
       return { ...route, result };
     } catch (error) {
       if (error instanceof ContainerError) {
+        const locale = resolveLocale(this.db, this.config, message.spaceId);
         switch (error.reason) {
           case "aborted":
-            return { type: "denied", reason: "Stopped current run." };
+            return {
+              type: "denied",
+              reason: formatSystemMessage(locale, "run_stopped"),
+            };
           case "timeout":
-            return { type: "denied", reason: "Container timed out." };
+            return {
+              type: "denied",
+              reason: formatSystemMessage(locale, "container_timeout"),
+            };
           case "oom":
             return {
               type: "denied",
-              reason: "Container was killed (possibly out of memory).",
+              reason: formatSystemMessage(locale, "container_oom"),
             };
           case "no-credentials": {
             // Host refused to start the container (no model credential).
@@ -651,6 +687,7 @@ export class MercuryCoreRuntime {
               "auth",
               this.config.apiKeyMode,
               this.config.consoleUrl,
+              locale,
             );
             return { type: "denied", reason };
           }
@@ -664,6 +701,7 @@ export class MercuryCoreRuntime {
               category,
               this.config.apiKeyMode,
               this.config.consoleUrl,
+              locale,
             );
             return { type: "denied", reason };
           }
@@ -1211,7 +1249,7 @@ export class MercuryCoreRuntime {
   private async executePrompt(
     spaceId: string,
     prompt: string,
-    _source: InputSource,
+    source: InputSource,
     callerId: string,
     attachments?: MessageAttachment[],
     authorName?: string,
@@ -1221,7 +1259,11 @@ export class MercuryCoreRuntime {
       replyToPlatformMessageId?: string;
       platformMessageId?: string;
     },
-    replyFlags?: { isReplyToBot: boolean; isDM: boolean },
+    replyFlags?: {
+      isReplyToBot: boolean;
+      isDM: boolean;
+      hadIncomingAttachments?: boolean;
+    },
   ): Promise<ContainerResult> {
     this.db.ensureSpace(spaceId);
 
@@ -1259,8 +1301,10 @@ export class MercuryCoreRuntime {
             };
             if (!quotaData.allowed) {
               return {
-                reply:
-                  "You've reached your daily message limit. Upgrade your plan at the Mercury Console to continue chatting.",
+                reply: formatSystemMessage(
+                  resolveLocale(this.db, this.config, spaceId),
+                  "platform_quota_exceeded",
+                ),
                 files: [],
               };
             }
@@ -1342,6 +1386,50 @@ export class MercuryCoreRuntime {
       }
       // ────────────────────────────────────────────────────────────────────
 
+      // ── Media permission gates (media.receive / media.send) ─────────────
+      // Role resolved once here for both gates. Scheduled tasks are exempt by
+      // source (task delivery must keep working regardless of member
+      // settings); admin and system callers are exempt by rule.
+      const mediaRole =
+        source === "scheduler"
+          ? "system"
+          : resolveRole(
+              this.db,
+              spaceId,
+              callerId,
+              this.config.admins
+                ? this.config.admins
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : [],
+            );
+      const mediaExempt = mediaRole === "admin" || mediaRole === "system";
+
+      // Receive gate — enforced before hooks, the user-message save, and the
+      // container start, so denied files are deleted from disk before any
+      // agent code can reach them (the container mounts the workspace).
+      let effectiveAttachments = attachments;
+      if (
+        !mediaExempt &&
+        !hasPermission(this.db, spaceId, mediaRole, "media.receive")
+      ) {
+        const gated = gateIncomingMedia({
+          workspacePath: workspace,
+          spaceId,
+          callerRole: mediaRole,
+          attachments,
+          hadIncomingAttachments: replyFlags?.hadIncomingAttachments ?? false,
+        });
+        effectiveAttachments = gated.attachments;
+        if (gated.promptNote) {
+          finalPrompt = [finalPrompt, gated.promptNote]
+            .filter(Boolean)
+            .join("\n\n");
+        }
+      }
+      // ────────────────────────────────────────────────────────────────────
+
       // Emit workspace_init hook (extensions should be idempotent)
       if (this.hooks && this.extensionCtx) {
         await this.hooks.emit(
@@ -1361,7 +1449,7 @@ export class MercuryCoreRuntime {
             callerId,
             workspace,
             containerWorkspace,
-            attachments,
+            attachments: effectiveAttachments,
           },
           this.extensionCtx,
         );
@@ -1486,7 +1574,7 @@ export class MercuryCoreRuntime {
         spaceId,
         "user",
         finalPrompt,
-        attachments,
+        effectiveAttachments,
         userReplyToId,
       );
 
@@ -1602,7 +1690,7 @@ export class MercuryCoreRuntime {
           callerId,
           callerRole,
           authorName,
-          attachments,
+          attachments: effectiveAttachments,
           preferences,
           extraEnv,
           claimedEnvSources: this.extensionRegistry?.getClaimedEnvSources(),
@@ -1645,6 +1733,26 @@ export class MercuryCoreRuntime {
         }
       }
 
+      // ── Media send gate ──────────────────────────────────────────────────
+      // Applied before the assistant message is stored so the withhold notice
+      // is part of the recorded reply. Withheld files stay in outbox/ for
+      // admin retrieval; TTL cleanup removes them later.
+      if (
+        !mediaExempt &&
+        containerResult.files.length > 0 &&
+        !hasPermission(this.db, spaceId, mediaRole, "media.send")
+      ) {
+        const gated = gateOutgoingMedia({
+          spaceId,
+          callerRole: mediaRole,
+          files: containerResult.files,
+          reply: containerResult.reply,
+        });
+        containerResult.files = gated.files;
+        containerResult.reply = gated.reply;
+      }
+      // ────────────────────────────────────────────────────────────────────
+
       const assistantMessageId = this.db.addMessage(
         spaceId,
         "assistant",

package/src/core/system-messages.ts

@@ -0,0 +1,226 @@
+/**
+ * Locale-keyed string table for host-generated system messages.
+ *
+ * These messages (rate-limit denials, container failures, permission denials,
+ * the sensitive-connection guard, provider-error messages) are produced
+ * deterministically on the host before any LLM runs, so system-prompt language
+ * instructions never touch them. This table lets a deployment or a single
+ * space switch them to another locale via the `messages.locale` config key.
+ *
+ * Resolution chain: per-space → `@global` → `config.messagesLocale` → `"en"`.
+ * The `en` strings are byte-identical to the original literals — tests and
+ * downstream matching depend on them.
+ */
+
+import type { AppConfig } from "../config.js";
+import { GLOBAL_CONFIG_SPACE_ID } from "../extensions/config-registry.js";
+import type { Db } from "../storage/db.js";
+
+export type MessageLocale = "en" | "he";
+
+export const MESSAGE_LOCALES: readonly MessageLocale[] = ["en", "he"];
+
+export type SystemMessageKey =
+  | "rate_limit_burst"
+  | "rate_limit_daily"
+  | "attachment_failed"
+  | "run_stopped"
+  | "container_timeout"
+  | "container_oom"
+  | "no_permission_prompt"
+  | "no_permission_slash"
+  | "slash_admin_only"
+  | "no_permission_command"
+  | "sensitive_disabled"
+  | "sensitive_confirm"
+  | "sensitive_cancelled"
+  | "platform_quota_exceeded"
+  // Provider-error messages (user-error-messages.ts), keyed category × mode
+  | "err_key-limit_platform"
+  | "err_key-limit_byok"
+  | "err_rate-limit_platform"
+  | "err_rate-limit_byok"
+  | "err_auth_platform"
+  | "err_auth_byok"
+  | "err_credits_platform"
+  | "err_credits_byok"
+  | "err_server-error_platform"
+  | "err_server-error_byok"
+  | "err_generic_platform"
+  | "err_generic_byok"
+  | "err_upgrade_suffix"
+  | "err_session_expired";
+
+export const SYSTEM_MESSAGES: Record<
+  MessageLocale,
+  Record<SystemMessageKey, string>
+> = {
+  en: {
+    rate_limit_burst: "Rate limit exceeded. Try again shortly.",
+    rate_limit_daily:
+      "You've used {count}/{limit} messages today. Resets in {hours}h.",
+    attachment_failed:
+      "Could not use your attachment (media disabled, over the size limit, or download failed). Check MERCURY_MEDIA_ENABLED and logs.",
+    run_stopped: "Stopped current run.",
+    container_timeout: "Container timed out.",
+    container_oom: "Container was killed (possibly out of memory).",
+    no_permission_prompt:
+      "You don't have permission to use the agent in this group.",
+    no_permission_slash: "You don't have permission to use '/{command}'.",
+    slash_admin_only: "Slash commands are only available to admins in groups.",
+    no_permission_command: "You don't have permission to use '{command}'.",
+    sensitive_disabled:
+      "⛔ Sensitive integrations ({name}) are disabled for this group space. A space admin must enable them first with: mrctl config set security.sensitive_connections_allowed true",
+    sensitive_confirm:
+      "⚠️ This response may contain data from {name} and will be visible to all members of this group. Reply *yes* to proceed or *no* to cancel.",
+    sensitive_cancelled: "Cancelled.",
+    platform_quota_exceeded:
+      "You've reached your daily message limit. Upgrade your plan at the Mercury Console to continue chatting.",
+    "err_key-limit_platform":
+      "I've reached my usage limit for now. Please try again later.",
+    "err_key-limit_byok":
+      "Your API key has hit its spending limit. Check your provider's key settings to increase it.",
+    "err_rate-limit_platform":
+      "I'm handling too many requests right now — please try again in a moment.",
+    "err_rate-limit_byok":
+      "Your API key is being rate-limited. Try again in a moment.",
+    err_auth_platform:
+      "Something went wrong on my end. This has been logged and the admin will be notified.",
+    err_auth_byok:
+      "Your API key appears to be invalid or expired. Please update it.",
+    err_credits_platform:
+      "I've reached my usage limit for now. Please try again later.",
+    err_credits_byok:
+      "Your API provider account has insufficient credits. Add credits to continue.",
+    "err_server-error_platform":
+      "The AI service is temporarily unavailable. Please try again in a few minutes.",
+    "err_server-error_byok":
+      "The AI service is temporarily unavailable. Please try again in a few minutes.",
+    err_generic_platform:
+      "Something went wrong processing your request. Please try again.",
+    err_generic_byok:
+      "Something went wrong processing your request. Please try again, or check your API key and provider status.",
+    err_upgrade_suffix: "Upgrade your plan: {url}/dashboard/billing",
+    err_session_expired:
+      "Your Anthropic session has expired. Please reconnect: {url}/dashboard/model",
+  },
+  he: {
+    rate_limit_burst: "חריגה ממגבלת הקצב. נסו שוב בעוד רגע.",
+    rate_limit_daily:
+      "נוצלו {count}/{limit} הודעות היום. המכסה מתאפסת בעוד {hours} שעות.",
+    attachment_failed:
+      "לא ניתן היה להשתמש בקובץ המצורף (מדיה מושבתת, חריגה ממגבלת הגודל, או שההורדה נכשלה). בדקו את MERCURY_MEDIA_ENABLED ואת הלוגים.",
+    run_stopped: "הריצה הנוכחית הופסקה.",
+    container_timeout: "זמן הריצה של הקונטיינר פג.",
+    container_oom: "הקונטיינר הופסק (ייתכן שבשל מחסור בזיכרון).",
+    no_permission_prompt: "אין לכם הרשאה להשתמש בסוכן בקבוצה זו.",
+    no_permission_slash: "אין לכם הרשאה להשתמש ב-'/{command}'.",
+    slash_admin_only: "פקודות סלאש זמינות רק למנהלים בקבוצות.",
+    no_permission_command: "אין לכם הרשאה להשתמש ב-'{command}'.",
+    sensitive_disabled:
+      "⛔ אינטגרציות רגישות ({name}) מושבתות במרחב הקבוצתי הזה. מנהל המרחב צריך להפעיל אותן תחילה באמצעות: mrctl config set security.sensitive_connections_allowed true",
+    sensitive_confirm:
+      "⚠️ התשובה עשויה להכיל מידע מ-{name} ותהיה גלויה לכל חברי הקבוצה. השיבו *כן* כדי להמשיך או *לא* כדי לבטל.",
+    sensitive_cancelled: "בוטל.",
+    platform_quota_exceeded:
+      "הגעתם למגבלת ההודעות היומית. שדרגו את התוכנית ב-Mercury Console כדי להמשיך בשיחה.",
+    "err_key-limit_platform":
+      "הגעתי למגבלת השימוש שלי לעת עתה. נסו שוב מאוחר יותר.",
+    "err_key-limit_byok":
+      "מפתח ה-API שלכם הגיע למגבלת ההוצאה שלו. בדקו את הגדרות המפתח אצל הספק כדי להגדיל אותה.",
+    "err_rate-limit_platform":
+      "אני מטפל בבקשות רבות מדי כרגע — נסו שוב בעוד רגע.",
+    "err_rate-limit_byok": "מפתח ה-API שלכם מוגבל בקצב. נסו שוב בעוד רגע.",
+    err_auth_platform: "משהו השתבש אצלי. האירוע נרשם והמנהל יקבל התראה.",
+    err_auth_byok: "נראה שמפתח ה-API שלכם אינו תקין או שפג תוקפו. עדכנו אותו.",
+    err_credits_platform:
+      "הגעתי למגבלת השימוש שלי לעת עתה. נסו שוב מאוחר יותר.",
+    err_credits_byok:
+      "בחשבון ספק ה-API שלכם אין מספיק קרדיטים. הוסיפו קרדיטים כדי להמשיך.",
+    "err_server-error_platform":
+      "שירות ה-AI אינו זמין זמנית. נסו שוב בעוד כמה דקות.",
+    "err_server-error_byok":
+      "שירות ה-AI אינו זמין זמנית. נסו שוב בעוד כמה דקות.",
+    err_generic_platform: "משהו השתבש בעיבוד הבקשה. נסו שוב.",
+    err_generic_byok:
+      "משהו השתבש בעיבוד הבקשה. נסו שוב, או בדקו את מפתח ה-API ואת סטטוס הספק.",
+    err_upgrade_suffix: "שדרגו את התוכנית: {url}/dashboard/billing",
+    err_session_expired:
+      "החיבור ל-Anthropic פג תוקף. התחברו מחדש: {url}/dashboard/model",
+  },
+};
+
+/**
+ * Words accepted as confirmation replies by the sensitive-connection guard,
+ * per locale. English `yes`/`no` are ALWAYS accepted, in every locale —
+ * switching a space's locale must never break an in-flight or muscle-memory
+ * English confirmation. Matching is done against a lowercased, trimmed reply.
+ * Record-typed so adding a locale without confirm words is a compile error.
+ */
+const CONFIRM_WORDS: Record<MessageLocale, { yes: string[]; no: string[] }> = {
+  en: { yes: ["yes"], no: ["no"] },
+  he: { yes: ["yes", "כן"], no: ["no", "לא"] },
+};
+
+export function confirmWords(locale: MessageLocale): {
+  yes: string[];
+  no: string[];
+} {
+  return CONFIRM_WORDS[isMessageLocale(locale) ? locale : "en"];
+}
+
+function isMessageLocale(v: unknown): v is MessageLocale {
+  return v === "en" || v === "he";
+}
+
+/**
+ * Format a system message for a locale, substituting `{name}` placeholders.
+ * Unknown locale falls back to `en`; unknown key falls back to the `en` table,
+ * then to the key itself (never throws).
+ */
+export function formatSystemMessage(
+  locale: MessageLocale,
+  key: SystemMessageKey,
+  params?: Record<string, string | number>,
+): string {
+  const table = SYSTEM_MESSAGES[isMessageLocale(locale) ? locale : "en"];
+  const template =
+    (table as Record<string, string>)[key] ??
+    (SYSTEM_MESSAGES.en as Record<string, string>)[key] ??
+    key;
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match,
+  );
+}
+
+/**
+ * Resolve the effective message locale for a space:
+ * per-space → `@global` → `config.messagesLocale` → `"en"`.
+ *
+ * Never throws and never returns an unknown locale — any invalid stored value
+ * (e.g. DB edited out-of-band) is treated as unset and degrades to the next
+ * link in the chain. Pass `spaceId: null` when no space context exists (very
+ * early ingress failures); the per-space link is skipped.
+ */
+export function resolveLocale(
+  db: Db,
+  config: Pick<AppConfig, "messagesLocale">,
+  spaceId: string | null,
+): MessageLocale {
+  try {
+    if (spaceId) {
+      const spaceValue = db.getSpaceConfig(spaceId, "messages.locale");
+      if (isMessageLocale(spaceValue)) return spaceValue;
+    }
+    const globalValue = db.getSpaceConfig(
+      GLOBAL_CONFIG_SPACE_ID,
+      "messages.locale",
+    );
+    if (isMessageLocale(globalValue)) return globalValue;
+  } catch {
+    // DB unavailable — fall through to config/default
+  }
+  if (isMessageLocale(config.messagesLocale)) return config.messagesLocale;
+  return "en";
+}

package/src/storage/db.ts

@@ -14,6 +14,43 @@ import type {
   TokenUsage,
 } from "../types.js";
 
+// `bun:sqlite` caches prepared statements per Database, capped at
+// Database.MAX_QUERY_CACHE_SIZE (default 20). When a 21st distinct statement is
+// prepared the least-recently-used one is evicted WITHOUT being finalized, so
+// sqlite3_close() returns SQLITE_BUSY. Bun's close() swallows that, leaving the
+// OS handles for state.db / -wal / -shm open. On Windows the next rmdir fails
+// with EBUSY; on POSIX the unlink succeeds anyway, which is why this is
+// invisible on Linux CI.
+//
+// This file issues ~114 distinct statements, so eviction is constant. Raising
+// the cap above that count means nothing is ever evicted and every statement is
+// finalized by close(). The set is bounded — statements are static SQL except
+// listConversations' filter combinations, which are themselves bounded — so
+// this does not grow without limit. Roughly a few KB per statement.
+//
+// Bun reads the cap on each cache insert rather than snapshotting it when a
+// Database is constructed (verified), so import order does not matter. It is
+// nonetheless a process-global: this changes the cap for every bun:sqlite
+// consumer in the process, not just Db. Today db.ts is the only importer.
+//
+// If db.ts ever grows past this many distinct statements the failure returns
+// silently, so keep generous headroom — tests/db.test.ts gates that.
+// Found because deleteSpace's ~12 statements in one call pushed a fresh
+// per-test Db past the cap, and the temp dir then refused to delete.
+//
+// The cast is required because the static exists at runtime but is missing from
+// bun-types. Read the property BEFORE assigning: writing through the cast would
+// happily create the property on an object that never had it, so a post-hoc
+// read cannot distinguish "Bun has this knob and we set it" from "Bun dropped
+// the knob and we invented a dead property." Only this pre-read can, and a test
+// asserts it — otherwise a future Bun rename silently restores the leak, and
+// the EBUSY symptom is Windows-only so Linux CI would stay green.
+const sqliteStatic = Database as unknown as { MAX_QUERY_CACHE_SIZE: number };
+export const SQLITE_QUERY_CACHE_STATIC_EXISTS =
+  typeof sqliteStatic.MAX_QUERY_CACHE_SIZE === "number";
+export const SQLITE_QUERY_CACHE_SIZE = 500;
+sqliteStatic.MAX_QUERY_CACHE_SIZE = SQLITE_QUERY_CACHE_SIZE;
+
 type SpaceRow = {
   id: string;
   name: string;
@@ -232,6 +269,47 @@ export class Db {
     this.ensureSpaceRolesDisplayNameColumn();
     this.ensureTasksTimezoneColumn();
     this.ensureTasksNameColumn();
+    this.migrateMediaPermissionRows();
+  }
+
+  /**
+   * One-time migration for the introduction of `media.receive` / `media.send`.
+   *
+   * Media exchange was ungated before these permissions existed, so a stored
+   * `role.<name>.permissions` row written pre-upgrade carries no revocation
+   * intent for them — append both to preserve behavior. Rows mentioning either
+   * name are left verbatim (`media.purge` predates the pair and is not an
+   * opt-out signal). `updated_by` is intentionally preserved so dm-auto-space
+   * seeded rows keep yielding to an active profile. Version-gated via a
+   * project_config guard key: after this runs once, stored lists are literal
+   * and revocation via `permissions set` sticks.
+   */
+  private migrateMediaPermissionRows(): void {
+    const guardKey = "migration.media_role_permissions";
+    if (this.getProjectConfig(guardKey) !== null) return;
+
+    const rows = this.db
+      .query(
+        "SELECT space_id, key, value FROM space_config WHERE key LIKE 'role.%.permissions'",
+      )
+      .all() as { space_id: string; key: string; value: string }[];
+
+    const update = this.db.query(
+      "UPDATE space_config SET value = ?, updated_at = ? WHERE space_id = ? AND key = ?",
+    );
+    for (const row of rows) {
+      const entries = row.value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (entries.some((e) => e === "media.receive" || e === "media.send")) {
+        continue;
+      }
+      const next = [...entries, "media.receive", "media.send"].join(",");
+      update.run(next, Date.now(), row.space_id, row.key);
+    }
+
+    this.setProjectConfig(guardKey, "1", "migration");
   }
 
   private ensureMessagesRunMetaColumn(): void {