feat(teams): phase 9 — one voice channel per Team, granted by a role

TEAMS.md §7.3. Each qualifying Team gets a Discord voice channel of its own
and a role that opens it, kept in step by a reconciler that rides the Team
reconcile it already depends on.

Access is a per-Team ROLE, always. §7.3 designed per-member overwrites with
escalation to a role above ~90 members; the org lead settled on roles always
(2026-08-18), which deletes `voice_overwrite_max`, the escalation and the
`mode` column — and moves the ceiling. Overwrites are capped per channel, so
the old shape's limit was "how big can one Team be"; roles are capped per
guild at 250, so the new one is "how many Teams can have voice at all". That
is a limit an operator must be told about before they hit it, so the panel
reports it and the pass refuses the create rather than letting Discord do it.

Three things §7.3 named that this codebase does not have, all settled by
asking the operator because nothing in the data model can answer:

  - "the staff role" — there is no staff-role concept anywhere. Now a list of
    role ids the admin designates; empty is a normal answer, since guild
    administrators bypass overwrites and what is really missing is a way to
    let NON-admin staff in.
  - the parent category — §7.3 said the bot creates it and gave the id nowhere
    to live (`team_integrations.team_id` is NOT NULL). The bot creates it and
    the server stores the id in settings.
  - whether the bot can act at all — nothing has ever checked. The operator
    invites the bot by hand and no invite URL with a permission integer exists
    in the tree, so a deployment can be one unticked box from every call
    failing. A preflight is now a PRECONDITION to enabling (422), not a
    per-Team error discovered afterwards.

Two more, decided rather than asked:

  - the threshold counts every active member, not linked ones. §7.3 wrote
    `voice_min_linked_members`; the operator is judging whether a Team is real,
    and link state answers a different question.
  - hidden Teams are never provisioned. A channel name is a game-sourced string
    published outside the site, which is exactly §2.8's concern —
    reservedNames.js already names "and eventually a Discord channel name" as a
    surface it protects — so the screen that suppresses a Team's page suppresses
    its channel, and a Team that becomes hidden takes the grace window.

Turning voice OFF tears nothing down: the pass suspends in both directions and
the panel offers per-row removal. A checkbox must not delete structure in
somebody's guild.

Fixes a phase 8 defect that blocks this phase's own artifact: `npm run swagger`
has been unable to run on `edge` at all. `param('teamId').custom((v) => ... ||
/^[0-9]+$/.test(v))` makes swagger-autogen's parser run away — a regex literal
followed directly by `.test(`. Hoisted to a const, as modules.router.js
already does. Underneath it, `teams.router.js` sits exactly at that parser's
per-file limit: at twenty `teamsRouter.*` statements it dies, at nineteen it
generates, and one more statement of ANY shape tips it — an unannotated route
does, and so does a bare `use`. So the voice routes are their own router file
mounted from `admin/index.js`, and teams.router.js keeps its nineteen.

Also breaks a require cycle this phase would have introduced:
teamSync -> teamVoiceSync -> teams.model -> teamSync left `teams.model` holding
the reconciler's exports object as it stood mid-load — the empty one, since
`module.exports = {…}` replaces rather than fills. The symptom is not in the
new code: it is `teamSync.intervalSeconds is not a function` thrown out of
`syncStatus()`, the freshness banner on every public Team page.

Tests: 1160 server (+40), 53 bot (+21), 284 client (+21). Swagger, routes
manifest and guards regenerated; the guard shape of the four new routes is
byte-identical to the existing admin-only ones.

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

client/src/routes/admin/views/TeamVoice.jsx

@@ -0,0 +1,256 @@
+import { useCallback, useEffect, useState } from 'react'
+import { api } from '../../../api/client.js'
+import {
+  stateLabel, enableBlockedReason, roleHeadroom, removalCountdown,
+  parseStaffRoles, formatStaffRoles, statusSummary,
+} from '../../../lib/teamVoice.js'
+
+// Team voice channels (TEAMS.md §7.3, phase 9).
+//
+// Named for the Team concern and placed under Teams beside the notification
+// bridge, for the reason that panel gives: phase 10 replaces "Discord" with
+// whatever the capability registry declares, and what should change then is what
+// fills this panel rather than where an operator goes to find it.
+//
+// **The preflight is the first thing on the page, not a diagnostic.** §7.3
+// assumed the bot could manage channels and roles; nothing in this project has
+// ever checked, because the operator invites the bot by hand and no invite URL
+// with a permission integer exists anywhere in the tree. An operator whose bot
+// lacks Manage Roles otherwise has a screen full of controls that cannot work,
+// and finds out one Team at a time from a column of identical errors.
+
+export default function TeamVoice() {
+  const [config, setConfig] = useState(null)
+  const [draft, setDraft] = useState(null)
+  const [error, setError] = useState('')
+  const [notice, setNotice] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  const load = useCallback(async () => {
+    setError('')
+    try {
+      const cfg = await api.admin.teamVoice()
+      setConfig(cfg)
+      setDraft({
+        enabled: cfg.settings.enabled,
+        minMembers: cfg.settings.minMembers,
+        graceDays: cfg.settings.graceDays,
+        staffRoles: formatStaffRoles(cfg.settings.staffRoles),
+      })
+    } catch (err) {
+      // A moderator never reaches this panel — the admin nav does not render it —
+      // so a 403 means the role changed underneath an open tab.
+      setError(err.status === 403
+        ? 'Only an admin can configure Team voice channels.'
+        : (err.message || 'Could not load the voice configuration.'))
+    }
+  }, [])
+
+  useEffect(() => { load() }, [load])
+
+  if (!config || !draft) {
+    return (
+      <section style={{ marginTop: 34, maxWidth: 760 }}>
+        <h2 className="display" style={{ fontSize: '1.05rem', marginBottom: 4 }}>Voice channels</h2>
+        {error && <p className="sans" style={{ color: '#e08b77', fontSize: '0.82rem' }}>{error}</p>}
+      </section>
+    )
+  }
+
+  const blocked = enableBlockedReason(config.preflight)
+  const headroom = roleHeadroom(config.preflight)
+
+  async function save() {
+    const { roles, invalid } = parseStaffRoles(draft.staffRoles)
+    if (invalid.length > 0) {
+      setError(`Not a role id: ${invalid.join(', ')}. Copy role ids from Discord with Developer Mode on.`)
+      return
+    }
+    setBusy(true)
+    setError('')
+    setNotice('')
+    try {
+      await api.admin.saveTeamVoice({
+        enabled: draft.enabled,
+        minMembers: Number(draft.minMembers),
+        graceDays: Number(draft.graceDays),
+        staffRoles: roles,
+      })
+      setNotice('Saved.')
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not save.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function runPass() {
+    setBusy(true)
+    setError('')
+    setNotice('')
+    try {
+      const result = await api.admin.teamVoicePass()
+      // A pass that refused says why, and that is the useful answer far more often
+      // than a count is — "stale projection" and "synced 0" look identical in a
+      // summary and mean completely different things.
+      setNotice(result.ran
+        ? `Synced ${result.synced}, created ${result.created}, scheduled ${result.scheduled}, removed ${result.removed}, failed ${result.failed}.`
+        : `Nothing was done: ${result.reason}`)
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not run a pass.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function remove(row) {
+    setBusy(true)
+    setError('')
+    try {
+      await api.admin.removeTeamVoice(row.teamId)
+      setNotice('Removed.')
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not remove.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <section style={{ marginTop: 34, maxWidth: 760 }}>
+      <h2 className="display" style={{ fontSize: '1.05rem', marginBottom: 4 }}>Voice channels</h2>
+      <p className="sans dim" style={{ fontSize: '0.78rem', margin: '0 0 14px' }}>
+        Give each Team a {config.platform} voice channel of its own. Access is granted with a role per
+        Team, so members of a Team can see and join their channel and nobody else can. Members need a
+        linked {config.platform} account and must be in the guild.
+      </p>
+
+      {blocked && (
+        <p className="sans" style={{ color: '#e0b877', fontSize: '0.82rem' }}>
+          {blocked} Voice channels cannot be switched on until that is fixed.
+        </p>
+      )}
+
+      {headroom && (
+        <p className="sans dim" style={{ fontSize: '0.78rem' }}>
+          {headroom.used} of {headroom.cap} {config.platform} roles used in this guild
+          {headroom.exhausted
+            ? ' — no room for another Team.'
+            : headroom.tight
+              ? ` — room for about ${headroom.free} more Teams.`
+              : '.'}
+        </p>
+      )}
+
+      {error && <p className="sans" style={{ color: '#e08b77', fontSize: '0.82rem' }}>{error}</p>}
+      {notice && <p className="sans" style={{ color: '#8fbf7a', fontSize: '0.82rem' }}>{notice}</p>}
+
+      <p className="sans" style={{ fontSize: '0.8rem' }}>{statusSummary(config.settings, config.rows)}</p>
+
+      <div style={{ marginTop: 14, borderTop: '1px solid rgba(255,255,255,0.12)', paddingTop: 16 }}>
+        <label className="sans" style={{ display: 'block', marginBottom: 12, fontSize: '0.82rem' }}>
+          <input
+            type="checkbox"
+            checked={draft.enabled}
+            disabled={busy || (!!blocked && !draft.enabled)}
+            onChange={(e) => setDraft({ ...draft, enabled: e.target.checked })}
+          />
+          {' '}Provision voice channels for Teams
+        </label>
+
+        <label style={{ display: 'block', marginBottom: 12 }}>
+          <span className="field-label">Minimum members</span>
+          <input
+            className="input"
+            type="number"
+            min="1"
+            max="10000"
+            value={draft.minMembers}
+            disabled={busy}
+            onChange={(e) => setDraft({ ...draft, minMembers: e.target.value })}
+          />
+          <span className="sans dim" style={{ display: 'block', fontSize: '0.74rem' }}>
+            Every active member counts, whether or not they have linked an account.
+          </span>
+        </label>
+
+        <label style={{ display: 'block', marginBottom: 12 }}>
+          <span className="field-label">Grace window (days)</span>
+          <input
+            className="input"
+            type="number"
+            min="0"
+            max="90"
+            value={draft.graceDays}
+            disabled={busy}
+            onChange={(e) => setDraft({ ...draft, graceDays: e.target.value })}
+          />
+          <span className="sans dim" style={{ display: 'block', fontSize: '0.74rem' }}>
+            How long a Team keeps its channel after it stops qualifying. A Team that recovers inside the
+            window keeps the same channel; zero removes it on the next pass.
+          </span>
+        </label>
+
+        <label style={{ display: 'block', marginBottom: 12 }}>
+          <span className="field-label">Staff roles</span>
+          <input
+            className="input"
+            type="text"
+            value={draft.staffRoles}
+            disabled={busy}
+            placeholder="role id, role id"
+            onChange={(e) => setDraft({ ...draft, staffRoles: e.target.value })}
+          />
+          <span className="sans dim" style={{ display: 'block', fontSize: '0.74rem' }}>
+            Roles that can see and join every Team’s channel. Guild administrators already can, so this
+            is for staff who are not administrators. Leave empty if there are none.
+          </span>
+        </label>
+
+        <button type="button" className="btn" disabled={busy} onClick={save}>Save</button>
+        <button type="button" className="btn-ghost" disabled={busy} onClick={runPass}>Sync now</button>
+      </div>
+
+      {config.rows.length > 0 && (
+        <table className="table" style={{ marginTop: 18 }}>
+          <thead>
+            <tr><th>Team</th><th>Members</th><th>Channel</th><th>State</th><th /></tr>
+          </thead>
+          <tbody>
+            {config.rows.map((row) => (
+              <tr key={row.teamId}>
+                <td>{row.teamName}</td>
+                <td className="sans" style={{ fontSize: '0.76rem' }}>{row.memberCount}</td>
+                <td className="sans" style={{ fontSize: '0.76rem' }}>
+                  {row.channelRef || <span className="dim">none</span>}
+                </td>
+                <td className="sans" style={{ fontSize: '0.76rem' }}>
+                  {stateLabel(row.state)}
+                  {removalCountdown(row) && (
+                    <span className="dim" style={{ display: 'block' }}>{removalCountdown(row)}</span>
+                  )}
+                  {row.lastError && (
+                    <span style={{ display: 'block', color: '#e08b77' }}>{row.lastError}</span>
+                  )}
+                </td>
+                <td>
+                  <button type="button" className="btn-ghost" disabled={busy} onClick={() => remove(row)}>Remove</button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+
+      {config.lastPass && config.lastPass.at && (
+        <p className="sans dim" style={{ fontSize: '0.74rem', marginTop: 10 }}>
+          Last pass {new Date(config.lastPass.at).toLocaleString()}
+          {config.lastPass.ran ? '' : ` — nothing was done: ${config.lastPass.reason}`}
+        </p>
+      )}
+    </section>
+  )
+}

client/src/routes/admin/views/TeamsAdmin.jsx

@@ -7,6 +7,7 @@ import {
 import { useAuth } from '../../../contexts/AuthContext.jsx'
 import { api } from '../../../api/client.js'
 import TeamIntegrations from './TeamIntegrations.jsx'
+import TeamVoice from './TeamVoice.jsx'
 
 // Admin → Teams (docs/website/TEAMS.md §2.4, §2.8, §2.9).
 //
@@ -346,6 +347,7 @@ export default function TeamsAdmin() {
           be a panel every action in fails 403 — the role gate is the server's, and
           this is only how the screen agrees with it. */}
       {role === 'admin' && <TeamIntegrations />}
+      {role === 'admin' && <TeamVoice />}
 
       <SyncPanel sync={data} syncState={data.syncState} onResync={resync} busy={busy} />
       <ReviewQueue rows={review} role={role} onAct={act} busy={busy} />