feat(commands): add 'rs gain' to grant the VIP audio gain boost

Admins can now run 'rs gain list|grant <vip>|revoke <vip>' from web chat or
Discord. Grant matches only against the verified list and revoke only
against current holders, so a nickname shared with an unverified visitor
reports not-found rather than resolving to someone ineligible. The action
joins the moderation set so lockdown narrows it to lockdown admins.

Also extracts the ceiling math into audioLevelsService/gainMath.js and
covers both it and the command with node:test suites.

Co-Authored-By: Claude <noreply@anthropic.com>

server/src/services/operatorCommandService/commands/gain.js

@@ -0,0 +1,87 @@
+// Operator Gain Command
+// Purpose: Handles the audio gain boost permission for VIPs.
+// Scope: Supports list, grant, and revoke subcommands; resolution stays VIP-only.
+const { mask, resolveIdentitySelector } = require('./resolvers');
+const { getCommandConfig } = require('../../operatorCommandService/config');
+
+function createGainCommand({
+  listVerifiedUsers,
+  listAudioGainBoostUsers,
+  grantAudioGainBoost,
+  revokeAudioGainBoost,
+  sanitizeMentions,
+  config,
+}) {
+  // Usage text comes from the same core prefix that both transports parse.
+  const { prefix: commandPrefix } = getCommandConfig(config);
+  const plain = { parse: [], repliedUser: false };
+
+  function usage(subcommand) {
+    return `Usage: \`${commandPrefix} gain ${subcommand} <nickname|userId|cookieUserId>\``;
+  }
+
+  /*
+    The boost is a VIP-only permission, so candidate matching runs against the
+    verified list rather than every known identity. A nickname that only belongs
+    to an unverified visitor therefore reports "not found" instead of resolving
+    to someone who cannot hold the flag anyway.
+  */
+  async function applyBoost(message, tokens, enabled) {
+    const selector = tokens.join(' ').trim();
+    if (!selector) {
+      return message.reply({ content: usage(enabled ? 'grant' : 'revoke'), allowedMentions: plain });
+    }
+    const candidates = enabled ? listVerifiedUsers() : listAudioGainBoostUsers();
+    const resolved = resolveIdentitySelector(selector, candidates, { includeId: false });
+    if (resolved.error) {
+      return message.reply({ content: sanitizeMentions(resolved.error), allowedMentions: plain });
+    }
+    const target = resolved.record.userId || resolved.record.id || resolved.record.cookieUserId;
+    try {
+      const actor = message.actor?.id || null;
+      const user = enabled ? grantAudioGainBoost(target, actor) : revokeAudioGainBoost(target, actor);
+      const verb = enabled ? 'Granted' : 'Revoked';
+      return message.reply({
+        content: sanitizeMentions(`${verb} audio gain boost for ${user.nickname || 'unknown'} (${mask(user.cookieUserId)}).`),
+        allowedMentions: plain,
+      });
+    } catch (err) {
+      return message.reply({
+        content: sanitizeMentions(`Failed to update audio gain boost: ${err.message}`),
+        allowedMentions: plain,
+      });
+    }
+  }
+
+  return async function handleGainCommand(message, tokens) {
+    if (!message.actor?.isAdmin) {
+      await message.reply({ content: 'Only admins can manage audio gain boosts.', allowedMentions: plain });
+      return;
+    }
+    const action = (tokens.shift() || 'list').toLowerCase();
+
+    if (action === 'list') {
+      const users = listAudioGainBoostUsers();
+      if (!users.length) {
+        return message.reply({ content: 'No users hold an audio gain boost.', allowedMentions: plain });
+      }
+      const lines = users.map((entry, idx) => (
+        `${idx + 1}. ${entry.nickname || 'unknown'} | ${entry.userId || entry.id} | ${mask(entry.cookieUserId)}`
+      ));
+      return message.reply({
+        content: sanitizeMentions(['Audio gain boost holders:', ...lines].join('\n').slice(0, 1900)),
+        allowedMentions: plain,
+      });
+    }
+
+    if (action === 'grant') return applyBoost(message, tokens, true);
+    if (action === 'revoke') return applyBoost(message, tokens, false);
+
+    return message.reply({
+      content: `Unknown gain command. Use \`${commandPrefix} gain list\`, \`${commandPrefix} gain grant <vip>\`, or \`${commandPrefix} gain revoke <vip>\`.`,
+      allowedMentions: plain,
+    });
+  };
+}
+
+module.exports = { createGainCommand };

server/src/services/operatorCommandService/commands/gain.test.js

@@ -0,0 +1,125 @@
+// Operator Gain Command Tests
+// Purpose: Verifies the audio gain boost command stays admin-only and VIP-only.
+// Scope: Exercises command target resolution with in-memory identity doubles.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createGainCommand } = require('./gain');
+
+const VIPS = [
+  { userId: 'usr-vip', nickname: 'Croissant', cookieUserId: 'cookie-croissant' },
+  { userId: 'usr-other', nickname: 'Baguette', cookieUserId: 'cookie-baguette' },
+];
+
+function createHarness({ verified = VIPS, boosted = [], isAdmin = true } = {}) {
+  const calls = [];
+  const replies = [];
+  const handler = createGainCommand({
+    listVerifiedUsers: () => verified,
+    listAudioGainBoostUsers: () => boosted,
+    grantAudioGainBoost: (selector, actor) => {
+      calls.push({ action: 'grant', selector, actor });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    revokeAudioGainBoost: (selector, actor) => {
+      calls.push({ action: 'revoke', selector, actor });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    sanitizeMentions: (value) => value,
+    config: { commands: { prefix: 'rs' } },
+  });
+  const message = {
+    actor: { id: 'admin', isAdmin },
+    reply: async (payload) => {
+      replies.push(payload);
+      return payload;
+    },
+  };
+  return { handler, message, calls, replies };
+}
+
+test('non-admins cannot manage the boost', async () => {
+  const { handler, message, calls, replies } = createHarness({ isAdmin: false });
+
+  await handler(message, ['grant', 'Croissant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /Only admins/);
+});
+
+test('grant resolves a VIP nickname to its stable user id', async () => {
+  const { handler, message, calls } = createHarness();
+
+  await handler(message, ['grant', 'croissant']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-vip', actor: 'admin' }]);
+});
+
+test('grant refuses a nickname that belongs to no VIP', async () => {
+  const { handler, message, calls, replies } = createHarness({ verified: [] });
+
+  await handler(message, ['grant', 'Stranger']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /not found/i);
+});
+
+test('revoke only matches users who currently hold the boost', async () => {
+  const { handler, message, calls, replies } = createHarness({ boosted: [] });
+
+  await handler(message, ['revoke', 'Croissant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /not found/i);
+});
+
+test('revoke resolves against the boosted list', async () => {
+  const { handler, message, calls } = createHarness({ boosted: [VIPS[0]] });
+
+  await handler(message, ['revoke', 'Croissant']);
+
+  assert.deepEqual(calls, [{ action: 'revoke', selector: 'usr-vip', actor: 'admin' }]);
+});
+
+test('grant without a target prints usage instead of acting', async () => {
+  const { handler, message, calls, replies } = createHarness();
+
+  await handler(message, ['grant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /rs gain grant/);
+});
+
+test('list defaults when no subcommand is given', async () => {
+  const { handler, message, replies } = createHarness({ boosted: [VIPS[0]] });
+
+  await handler(message, []);
+
+  assert.match(replies[0].content, /Croissant/);
+  assert.match(replies[0].content, /usr-vip/);
+});
+
+test('list reports an empty holder set', async () => {
+  const { handler, message, replies } = createHarness({ boosted: [] });
+
+  await handler(message, ['list']);
+
+  assert.match(replies[0].content, /No users hold/);
+});
+
+test('a service rejection is surfaced instead of thrown', async () => {
+  const { handler, message, replies } = createHarness();
+  const failing = createGainCommand({
+    listVerifiedUsers: () => VIPS,
+    listAudioGainBoostUsers: () => [],
+    grantAudioGainBoost: () => {
+      throw new Error('Only verified VIPs can be granted an audio gain boost.');
+    },
+    revokeAudioGainBoost: () => null,
+    sanitizeMentions: (value) => value,
+    config: { commands: { prefix: 'rs' } },
+  });
+
+  await failing(message, ['grant', 'Croissant']);
+
+  assert.match(replies[0].content, /Only verified VIPs/);
+});

server/src/services/operatorCommandService/index.js

@@ -8,6 +8,7 @@ const { createReasonCommand } = require('./commands/reason');
 const { createGoalCommand } = require('./commands/goal');
 const { createVerifyCommand } = require('./commands/verify');
 const { createDeterCommand } = require('./commands/deter');
+const { createGainCommand } = require('./commands/gain');
 const { createLightsCommand } = require('./commands/lights');
 const { createKickCommand } = require('./commands/kick');
 const { createLiftCommand } = require('./commands/lift');
@@ -47,6 +48,7 @@ function createCommandHandlers(deps) {
   const handleGoalCommand = createGoalCommand(deps);
   const handleVerifyCommand = createVerifyCommand(deps);
   const handleDeterCommand = createDeterCommand(deps);
+  const handleGainCommand = createGainCommand(deps);
   const handleBridgeCommand = transportHandlers.bridge;
   const handleTimeStatusCommand = transportHandlers.timeStatus;
   const handleLightsCommand = createLightsCommand(deps);
@@ -97,7 +99,7 @@ function createCommandHandlers(deps) {
     // is included because its lock/unlock subcommands change room policy. Its
     // ordinary on/off/color actions are also intentionally restricted to a
     // lockdown admin while the entire server is in lockdown.
-    const moderationActions = new Set(['lock', 'unlock', 'mode', 'goal', 'reason', 'verify', 'deter', 'lights', 'kick', 'lift', 'neato']);
+    const moderationActions = new Set(['lock', 'unlock', 'mode', 'goal', 'reason', 'verify', 'deter', 'gain', 'lights', 'kick', 'lift', 'neato']);
     const isAccessModeCommand = commandDefinition?.permission === 'access-mode';
 
     // Feature commands are public activities while access is open or managed
@@ -153,6 +155,8 @@ function createCommandHandlers(deps) {
         return handleVerifyCommand(request, tokens);
       case 'deter':
         return handleDeterCommand(request, tokens);
+      case 'gain':
+        return handleGainCommand(request, tokens);
       default:
         return request.reply(formatHelp({ commandPrefix, timeStatusCommand, includeDiscord: request.transport === 'discord', isFeatureEnabled: deps.isFeatureEnabled }));
     }

server/src/services/operatorCommandService/registry.js

@@ -3,7 +3,7 @@
 // Scope: Supplies transport-neutral metadata; execution handlers remain focused on server operations.
 const CATEGORIES = {
   system: { title: 'System', names: ['help', 'status', 'replay', 'time-status'] },
-  admin: { title: 'Admin', names: ['lock', 'unlock', 'mode', 'reason', 'goal', 'kick', 'verify', 'deter'] },
+  admin: { title: 'Admin', names: ['lock', 'unlock', 'mode', 'reason', 'goal', 'kick', 'verify', 'deter', 'gain'] },
   features: { title: 'Features', names: ['lights', 'lift', 'neato'] },
   discord: { title: 'Discord', names: ['bridge'] },
 };
@@ -46,6 +46,17 @@ function buildCommandRegistry(prefix, timeCommand) {
       access: 'Lockdown admin',
       permission: 'lockdown-admin',
     },
+    gain: {
+      category: 'admin',
+      summary: 'Manage the VIP audio gain boost that raises a user\'s volume ceiling past the global gains.',
+      usage: [
+        `${prefix} gain list`,
+        `${prefix} gain grant <vip>`,
+        `${prefix} gain revoke <vip>`,
+      ],
+      access: 'Admin',
+      permission: 'admin',
+    },
     lift: { category: 'features', summary: 'Show or move the lift.', usage: [`${prefix} lift <status|up|down>`], access: 'Public unless server access is restricted', permission: 'access-mode', requiredFeature: 'lift', unavailableLabel: 'Lift' },
     neato: { category: 'features', summary: 'Show or control Neato.', usage: [`${prefix} neato <status|start|home|locate|clear-errors>`], access: 'Public unless server access is restricted', permission: 'access-mode', requiredFeature: 'neato', unavailableLabel: 'Neato' },
     bridge: { category: 'discord', summary: 'Configure this Discord server chat bridge.', usage: [`${prefix} bridge`, `${prefix} bridge here <global|private>`, `${prefix} bridge mode <global|private>`, `${prefix} bridge off`], access: 'Discord server manager' },