pi-roundtable 0.31.8 → 0.32.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.32.1] - 2026-11-04
+
+- Release in lockstep with pi-roundtable-web 0.32.1 (optimistic mark-as-read, a Home button at the foot of the room drawer, Discord's -# subtext and line breaks in messages, the shared prompt's description in zh-TW, and the push device list centred); no core behavior changes.
+
+## [0.32.0] - 2026-11-03
+
+This is a minor release: `DiscordPoster` gains four required methods and `DiscordReason` three members, so an outside implementer of the poster or an exhaustive switch over the reasons must be updated.
+
+### Added
+
+- `discord.memberEvents` (default `false`) asks Discord for the privileged Server Members intent and reports each member that joins the server (the `MemberJoinedEvent` type, exported from the main entry) as the new plugin event `memberJoined({ surface: "discord", guildId, userId, bot })`. With it off no intent is added and no join is reported, so a deployment without the Developer Portal switch starts as before. `roundtable doctor` checks the Server Members intent when it is on and says where to turn it on; a login Discord refuses for it names the same switch.
+- `DISCORD.poster` reads and changes member roles: `memberRoles(guildId, userId)`, `addMemberRoles` and `removeMemberRoles(guildId, userId, roleIds, reason)`, and `ensureRole(guildId, name, reason)`. A change gives or takes only the roles named, with the required reason in the audit log, and refuses before giving any the @everyone role, a managed role, and a role at or above the bot's highest. `ensureRole` finds a role by exact name, makes one with no permissions when there is none, and never edits an existing one. `DiscordReason` gains `role_unassignable`, `unknown_role` and `not_member`; `fakeDiscordPoster()` models the same rules (`roles`, `botRoles`, `memberRoleIds`, `roleChanges`, each change a `FakeRoleChange`). `ROLE_LIMITS` (name, reason and per-call bounds), `GuildRole` and `MemberRoles` (the poster's member and role calls) are exported from `pi-roundtable/discord`.
+
 ## [0.31.8] - 2026-11-03
 
 - Release in lockstep with pi-roundtable-web 0.31.8 (the room drawer slides on from where the finger lets it go, without a frame shut); no core behavior changes.

package/README.md

@@ -246,6 +246,11 @@ When a conversation is started over in a server channel or thread, the assistant
 | text | `─── new conversation ───` | The divider's text |
 | `false` | | Post no divider |
 
+| `discord.memberEvents` | Default | What it is |
+| --- | --- | --- |
+| `false` | `false` | The bot asks Discord for no privileged intent beyond Message Content |
+| `true` | | Plugins hear each member that joins the server (`memberJoined`). Needs Server Members Intent switched on under Bot in the Developer Portal; `roundtable doctor` checks it |
+
 | `discord.formatting` | Default | What it is |
 | --- | --- | --- |
 | text | Markdown renders except tables | What the model is told, in English, about how a reply renders in Discord; appended to the system prompt of every turn that replies there |

package/docs/plugins.md

@@ -1335,6 +1335,7 @@ export const library = definePlugin({
 | `turnProgress(event)` | A turn run through `context.turns` wrote text or ran a tool, between its start and its end: `event` is the turn's fields and `progress`, a `TurnProgress` (see the surface's `progress` below); a runtime without live progress reports none |
 | `changed()` | The team changed: an agent or group was created, edited, arranged, archived, or started over |
 | `action(event)` | A plugin reported something a person did through its surface with `context.events.action?.(...)`: `event` is `{ kind, actor, principalId, channel?, ok, at }`, with `kind` in the reporting plugin's own words (a support inbox says `"assign"`, `"reply"` or `"close"`), `actor` the `Speaker.id`, and `channel` a `ChannelKey` or a `page:<name>`. It carries no content. The core reports none itself; a plugin hears the others' |
+| `memberJoined(event)` | Someone joined the Discord server: `event` is `{ surface: "discord", guildId, userId, bot }`. Reported only when the host's `discord.memberEvents` is on, which asks Discord for the privileged Server Members intent; otherwise never. A plugin that needs it says so in its own setup notes. Read the member's roles and give or take roles with `DISCORD.poster` ([Member roles](#member-roles)) |
 | `shutdown(left)` | The shutdown drain ended, before any service stops; `left` lists the work it gave up on |
 
 The host logs errors thrown by a handler and continues running the others.
@@ -2911,7 +2912,7 @@ await poster.edit(channelId, posted.messageId, { content: "Hello again" }, ["rel
 await poster.remove(channelId, posted.messageId, ["relay"]);
 ```
 
-What it covers: webhook posts under names you choose (`post`, `edit`, `remove`, `webhookIds`, `setAvatar`, `onWebhookMade`), cards posted through such a webhook (`postCard`, `editWebhookCard`), the bot's own messages and cards (`say`, `sayCard`, `editCard`, `deleteAsBot`), direct messages (`sendDirect`), pins, reading (`message`, `recentMessages`, `botUserId`, `channelGuild`, `canView`, `memberName`), text channels (`createTextChannel`, `textChannels`, `deleteChannel`, `renameChannel`, `channelKind`), threads (`startThread`, `setThreadArchived`, `threadState`, `threadCloser`) and forums (`forumTags`, `setForumTags`, `createForumPost`, `setPostTags`).
+What it covers: webhook posts under names you choose (`post`, `edit`, `remove`, `webhookIds`, `setAvatar`, `onWebhookMade`), cards posted through such a webhook (`postCard`, `editWebhookCard`), the bot's own messages and cards (`say`, `sayCard`, `editCard`, `deleteAsBot`), direct messages (`sendDirect`), pins, reading (`message`, `recentMessages`, `botUserId`, `channelGuild`, `canView`, `memberName`), member roles (`memberRoles`, `addMemberRoles`, `removeMemberRoles`, `ensureRole`), text channels (`createTextChannel`, `textChannels`, `deleteChannel`, `renameChannel`, `channelKind`), threads (`startThread`, `setThreadArchived`, `threadState`, `threadCloser`) and forums (`forumTags`, `setForumTags`, `createForumPost`, `setPostTags`).
 Use `DISCORD.connection.channelInfo(channelId)` to read what a channel is called now: it comes from the gateway's cache.
 
 The rules the poster keeps, so a plugin does not rediscover them:
@@ -2945,7 +2946,8 @@ await poster.postCard(channelId, {
 - **Forums.** `forumTags(forumId)` lists a forum's tags (`{ id, name, moderated, emoji? | emojiId? }`). `setForumTags(forumId, tags)` replaces the whole set (Manage Channels), because Discord only takes it whole: a tag sent with its `id` is kept and may be renamed, one without is made, one left out is deleted, so add a tag with `setForumTags(id, [...(await forumTags(id)), { name: "new" }])`. A forum holds at most 20 tags, a name 1 to 20 characters, a tag has a Unicode `emoji` or a custom `emojiId`, not both. A forum call on a channel that is no forum is `invalid` with `not_forum`. Making a forum channel is not in the poster.
 - **Forum posts.** `createForumPost(forumId, { name, card | content, appliedTags?, autoArchive?, mentions? })` returns `{ threadId, messageId }`. Discord takes a post and its first message in one request, so the first message is part of the call: a card (Components V2, or a preview card) or plain text (`mentions` names the users it may ping, as `say`'s). A post's first message has the thread's own id, so `messageId` equals `threadId`; `editCard(threadId, messageId, card)` edits a card first message, `pin`, `say` and `sayCard` take the thread id as a channel's. `appliedTags` is at most five ids the forum offers (a tag it does not offer is `rejected`); `autoArchive` is 60, 1,440, 4,320 or 10,080 minutes, a week by default. `setPostTags(threadId, tagIds)` replaces a post's tags (none clears them); a thread that is not a forum post is `invalid` with `not_forum`. `forbidden` without Create Posts. A forum takes posts, not messages: `say`, `sayCard` and a webhook `post` into the forum's own id are `rejected`. **An archived post.** A post nobody writes in archives itself (a week by default), and Discord refuses every edit of an archived thread (400, code 50083). `setPostTags` and `renameChannel` therefore send `archived: false` in the same request, which opens the post again; `editCard(threadId, threadId, card)` on a post's first message opens an archived post and sends the edit again. `editCard` on any other message of an archived thread is `rejected`: call `setThreadArchived(threadId, false)` first (`say` and `sayCard` already wake an archived thread). A locked post stays `forbidden` without Manage Threads. Scheduled events and moving channels between categories are not in the poster.
 - **Threads.** `startThread` makes a public thread on a message that archives itself after a week and wakes on the next post. The bot needs no Manage Threads to archive or open a thread it started; a locked thread needs it to open again (`forbidden`). `threadCloser` reads the guild's audit log (View Audit Log, else `forbidden`): a person's id, the bot, or `unknown` for Discord's own auto-archive. An archive counts only if its entry is within two minutes of the thread's `archive_timestamp`. It reads the newest 50 `THREAD_UPDATE` entries, so on a busy guild an old close may have left the log and read as `unknown`.
-- **Errors.** Every failure is a `DiscordPosterError` with a `kind`: `invalid` (refused before sending), `channel_gone`, `message_gone`, `forbidden` (a missing permission), `rejected` (Discord refused; asking again fails again) and `unavailable` (Discord or the network failed, or a rate limit held the call; `retryable`). `reason` says more for a full category (`category_full`), a channel that is no category (`not_category`), a channel that is no forum or a thread that is no forum post (`not_forum`) and one in no guild (`wrong_guild`). A webhook deleted by hand is found or made again once. A person who takes no direct messages is the answer `"closed"`, and a user who is not a member is `false` from `canView` and `undefined` from `memberName`, not failures. A message never holds a URL, a webhook token or the bot token.
+- **Member roles.** <a id="member-roles"></a>`memberRoles(guildId, userId)` lists the ids of the roles a member holds (not @everyone's), or `undefined` for someone who is not a member. `addMemberRoles(guildId, userId, roleIds, reason)` and `removeMemberRoles(...)` give or take exactly the roles named, one by one, and never send or touch the member's other roles; a role the member already holds (or lacks) is left as it is. `reason` is required: 1 to 512 characters, shown in the guild's audit log. A call takes 1 to 20 role ids, and all are checked before the first is given; after that the call is not atomic: a Discord failure (a 5xx, a timeout) may leave the earlier roles of the call changed, the error names the role that failed, and since each change is idempotent you retry the whole call. The poster refuses, giving none: the @everyone role (`invalid`), a managed role (an integration's or a bot's) and a role at or above the bot's highest role (`forbidden`, both with `reason: "role_unassignable"`), and a role the guild does not have (`rejected`, `unknown_role`); a user who is not a member is `rejected` with `not_member`. Manage Roles is needed, else `forbidden`. `ensureRole(guildId, name, reason)` returns the id of the guild's role of that exact name (1 to 100 characters; not @everyone's or a managed one; with several, the oldest) and makes one with no permissions, no colour, not shown apart and not mentionable when there is none. It never edits a role that exists, and two calls for the same name at the same time make one role within one process (separate processes do not coordinate and may make two). A role that already exists is returned even when it sits at or above the bot's highest role; the next `addMemberRoles` for it then refuses with `role_unassignable`, so move the bot's role above it. A role it makes sits just above @everyone, so the bot can give it at once. Joins are reported by the [`memberJoined` event](#events-hear-what-the-core-does) when `discord.memberEvents` is on; reading and changing roles needs no intent.
+- **Errors.** Every failure is a `DiscordPosterError` with a `kind`: `invalid` (refused before sending), `channel_gone`, `message_gone`, `forbidden` (a missing permission), `rejected` (Discord refused; asking again fails again) and `unavailable` (Discord or the network failed, or a rate limit held the call; `retryable`). `reason` says more for a full category (`category_full`), a channel that is no category (`not_category`), a channel that is no forum or a thread that is no forum post (`not_forum`), one in no guild (`wrong_guild`), a role the bot may not give or take (`role_unassignable`), a role the guild does not have (`unknown_role`) and a user who is not in the guild (`not_member`). A webhook deleted by hand is found or made again once. A person who takes no direct messages is the answer `"closed"`, and a user who is not a member is `false` from `canView` and `undefined` from `memberName`, not failures. A message never holds a URL, a webhook token or the bot token.
 
 `DISCORD_LIMITS` (frozen) holds the limits the poster checks: 2,000 characters a post, 80 for a username, 10 files and 10 MiB a post, 1 MiB for an avatar, 20 mentions, 250 pins, 100 characters for a channel name, 3,800 characters of card text, 256 for the title of a preview card, 5 card buttons and 25 menu choices, 20 forum tags, 20 characters for a tag name and 5 tags on a post.
 
@@ -4551,6 +4553,7 @@ Import from the entries listed below; source area files are internal.
 | `MAX_ATTACHMENT_BYTES` | `pi-roundtable` | value |
 | `MODES` | `pi-roundtable` | value |
 | `MEMORY_KINDS` | `pi-roundtable` | value |
+| `MemberJoinedEvent` | `pi-roundtable` | type |
 | `Memory` | `pi-roundtable` | type |
 | `MemoryError` | `pi-roundtable` | value |
 | `MemoryKind` | `pi-roundtable` | type |
@@ -4784,6 +4787,7 @@ Import from the entries listed below; source area files are internal.
 | `fakePrechecks` | `pi-roundtable/testing` | value |
 | `FakePrecheck` | `pi-roundtable/testing` | type |
 | `FakePrecheckAnswer` | `pi-roundtable/testing` | type |
+| `FakeRoleChange` | `pi-roundtable/testing` | type |
 | `fakeScriptRunner` | `pi-roundtable/testing` | value |
 | `FakeScriptAnswer` | `pi-roundtable/testing` | type |
 | `FakeScriptRunner` | `pi-roundtable/testing` | type |
@@ -4994,6 +4998,9 @@ Import from the entries listed below; source area files are internal.
 | `DiscordConnection` | `pi-roundtable/discord` | type |
 | `DiscordServices` | `pi-roundtable/discord` | type |
 | `DISCORD_LIMITS` | `pi-roundtable/discord` | value |
+| `ROLE_LIMITS` | `pi-roundtable/discord` | value |
+| `GuildRole` | `pi-roundtable/discord` | type |
+| `MemberRoles` | `pi-roundtable/discord` | type |
 | `DiscordPosterError` | `pi-roundtable/discord` | value |
 | `CardButton` | `pi-roundtable/discord` | type |
 | `CardLink` | `pi-roundtable/discord` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.31.8",
+	"version": "0.32.1",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/cli/checks/discord.ts

@@ -10,6 +10,8 @@ import { fail, ok, type Result, skipped } from "../report.ts";
 
 const PORTAL = "https://discord.com/developers/applications";
 const MESSAGE_CONTENT_FLAGS = (1 << 18) | (1 << 19);
+/** The application flags for the Server Members intent, granted or limited. */
+const GUILD_MEMBERS_FLAGS = (1 << 14) | (1 << 15);
 
 const object = (value: unknown): Record<string, unknown> =>
 	typeof value === "object" && value !== null
@@ -61,6 +63,12 @@ export class Discord {
 		return this.#api;
 	}
 
+	/** Whether the configuration asks for member joins (`discord.memberEvents`), which needs the Server Members intent. */
+	async wantsMemberEvents(): Promise<boolean> {
+		const raw = await this.#project.raw();
+		return raw.ok && object(object(raw.value).discord).memberEvents === true;
+	}
+
 	/** Who the token belongs to. */
 	bot(): Promise<Step<Bot>> {
 		this.#bot ??= this.#identify();
@@ -129,7 +137,10 @@ export async function checkGuild(
 	);
 }
 
-/** The Message Content intent is switched on, without which the agents cannot read the channels. */
+/**
+ * The Message Content intent is switched on, without which the agents cannot read the channels,
+ * and, when `discord.memberEvents` is on, the Server Members intent too.
+ */
 export async function checkIntents(discord: Discord): Promise<Result> {
 	const bot = await discord.bot();
 	if (!bot.ok) return skipped("the token check failed");
@@ -148,7 +159,14 @@ export async function checkIntents(discord: Discord): Promise<Result> {
 			"the Message Content intent is off.",
 			`Turn on Message Content Intent under Bot in ${PORTAL}, save, and run the check again.`,
 		);
-	return ok("the Message Content intent is on");
+	if (!(await discord.wantsMemberEvents()))
+		return ok("the Message Content intent is on");
+	if ((flags & GUILD_MEMBERS_FLAGS) === 0)
+		return fail(
+			"the Server Members intent is off, and discord.memberEvents asks for it.",
+			`Turn on Server Members Intent under Bot in ${PORTAL}, save, and run the check again, or set discord.memberEvents to false.`,
+		);
+	return ok("the Message Content and Server Members intents are on");
 }
 
 /** The entry channel exists in the guild and the bot may do in it what the agents do; skipped when the agent server is off, which has no entry channel. */

package/src/core/builtin/discord.ts

@@ -82,6 +82,12 @@ export interface DiscordOptions {
 	peerBots?: PeerBotsConfig;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: a short English divider. */
 	freshMarker?: string | false;
+	/**
+	 * Asks Discord for the privileged Server Members intent and reports each member that joins as
+	 * the `memberJoined` event. Needs the intent switched on under Bot in the Developer Portal, or
+	 * the connection is refused. Default: off.
+	 */
+	memberEvents?: boolean;
 	/** What the model is told about how replies render in Discord; `false` tells it nothing. Default: Markdown renders, except tables. */
 	formatting?: string | false;
 	/**
@@ -120,7 +126,7 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				collection.compose(ownerRootCommand(options.rootCommand)),
 			);
 		},
-		setup: async ({ conversations, services, logger }) => {
+		setup: async ({ conversations, services, logger, events }) => {
 			const identity = services.find(IDENTITY);
 			// A host that keeps no copy texts on disk drops what an earlier run left.
 			if (options.cardCopies === false)
@@ -174,8 +180,12 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				...(options.formatting === undefined
 					? {}
 					: { formatting: options.formatting }),
+				...(options.memberEvents ? { memberEvents: true } : {}),
 			});
 			surface = connected;
+			// Joins come only with the Server Members intent, which `memberEvents` asks for.
+			if (options.memberEvents)
+				connected.onMemberJoined((event) => events.memberJoined?.(event));
 			// Every owner may use the owner's commands, by the identity service; the primary owner always.
 			const guard = commandGuard({
 				ownerId: options.ownerId,

package/src/core/config/adapters.ts

@@ -66,6 +66,13 @@ export interface DiscordConfig {
 	 * never in a direct message. Default `─── new conversation ───`; `false` posts none.
 	 */
 	freshMarker?: string | false;
+	/**
+	 * Asks Discord for the privileged Server Members intent, so plugins hear each member that
+	 * joins the server as the `memberJoined` event. Turn on Server Members Intent under Bot in
+	 * the Developer Portal first: with it off there, the connection is refused, and `roundtable
+	 * doctor` says so. Default `false`, which needs no portal change.
+	 */
+	memberEvents?: boolean;
 	/**
 	 * What the model is told, English, about how a reply renders in Discord, appended to the system
 	 * prompt of every turn that replies there, after the persona. The default says Markdown
@@ -113,6 +120,7 @@ export interface ResolvedDiscord {
 	channelContext: NonNullable<DiscordConfig["channelContext"]>;
 	peerBots?: PeerBotsConfig;
 	freshMarker?: string | false;
+	memberEvents: boolean;
 	formatting?: string | false;
 	cardGraceSeconds: number;
 	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
@@ -148,6 +156,7 @@ export function resolvedDiscord(
 		...(discord.freshMarker === undefined
 			? {}
 			: { freshMarker: discord.freshMarker }),
+		memberEvents: discord.memberEvents ?? false,
 		...(discord.formatting === undefined
 			? {}
 			: { formatting: discord.formatting }),
@@ -195,6 +204,7 @@ export const discordShape = shape({
 	channelContext: optional(orOff(channelContextShape)),
 	peerBots: optional(peerBotsShape),
 	freshMarker: optional(orOff(text)),
+	memberEvents: optional(bool),
 	formatting: optional(orOff(text)),
 	cardGraceSeconds: optional(integer(1, 86_400)),
 	cardCopies: optional(

package/src/core/define-roundtable.ts

@@ -165,6 +165,7 @@ function discordAssembly(
 			...(discord.formatting === undefined
 				? {}
 				: { formatting: discord.formatting }),
+			...(discord.memberEvents ? { memberEvents: true } : {}),
 			cardGraceMs: discord.cardGraceSeconds * 1_000,
 			cardCopies: discord.cardCopies,
 		}),

package/src/core/discord/channel-info.ts

@@ -0,0 +1,38 @@
+import { ChannelType, type Client, DiscordAPIError } from "discord.js";
+import type { ChannelInfo } from "./connection.ts";
+
+/** Discord's error code for a channel that does not exist or cannot be seen. */
+const UNKNOWN_CHANNEL = 10003;
+
+/**
+ * What a channel is called, for the web app's lists: undefined when Discord no longer knows
+ * it; throws while the connection is not ready or Discord cannot be reached.
+ */
+export async function channelInfoOf(
+	client: Client,
+	channelId: string,
+): Promise<ChannelInfo | undefined> {
+	if (!client.isReady()) throw new Error("Discord is not connected");
+	const channel = await client.channels
+		.fetch(channelId)
+		.catch((error: unknown) => {
+			if (error instanceof DiscordAPIError && error.code === UNKNOWN_CHANNEL)
+				return null;
+			throw error;
+		});
+	if (!channel) return undefined;
+	if (channel.isDMBased())
+		return {
+			kind: "dm",
+			name:
+				channel.type === ChannelType.DM
+					? (channel.recipient?.username ?? "")
+					: (channel.name ?? ""),
+		};
+	return {
+		kind: "guild",
+		name: channel.name,
+		guild: channel.guild.name,
+		guildId: channel.guild.id,
+	};
+}

package/src/core/discord/discord-surface.ts

@@ -1,8 +1,6 @@
 import {
 	AttachmentBuilder,
-	ChannelType,
 	Client,
-	DiscordAPIError,
 	Events,
 	GatewayIntentBits,
 	type Interaction,
@@ -27,6 +25,7 @@ import type {
 } from "../domain/conversation.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { OwnerNotifier } from "../domain/ports.ts";
+import type { MemberJoinedEvent } from "../event-types.ts";
 import { messages } from "../i18n/index.ts";
 import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
@@ -39,6 +38,7 @@ import {
 	contextSourceOf,
 } from "./channel-context.ts";
 import { discordChannelExecutor } from "./channel-executor.ts";
+import { channelInfoOf } from "./channel-info.ts";
 import type { ChannelExecutor } from "./channel-operations.ts";
 import type { ComposedCommands } from "./compose-commands.ts";
 import type { ChannelInfo, DiscordConnection } from "./connection.ts";
@@ -47,15 +47,17 @@ import { DISCORD_FORMATTING, pickFormatting } from "./formatting.ts";
 import { DEFAULT_FRESH_MARKER, postFreshMarker } from "./fresh-marker.ts";
 import { lateAnswerMessage } from "./inbound-message.ts";
 import type { IntercomTexts } from "./intercom-cards.ts";
+import {
+	explainIntents,
+	listenForJoins,
+	memberIntents,
+} from "./member-events.ts";
 import { listenForMessages, reportChanges } from "./message-changes.ts";
 import type { CardChannel, LateTurn } from "./owner-cards.ts";
 import { DiscordOwnerOps } from "./owner-discord.ts";
 import { showStopPanel } from "./stop-button.ts";
 
 const PREFIX = "discord:";
-/** Discord's error code for a channel that does not exist or cannot be seen. */
-const UNKNOWN_CHANNEL = 10003;
-
 const TYPING_REFRESH_MS = 8_000;
 
 export interface DiscordSurfaceOptions {
@@ -69,6 +71,8 @@ export interface DiscordSurfaceOptions {
 	logger: Logger;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: `DEFAULT_FRESH_MARKER`. */
 	freshMarker?: string | false;
+	/** Asks Discord for the privileged Server Members intent, so `onMemberJoined` hears joins. Default: off. */
+	memberEvents?: boolean;
 	/** What the model is told about how replies render here; `false` tells it nothing. Default: `DISCORD_FORMATTING`. */
 	formatting?: string | false;
 	/** Where the agents' message cards keep their whole texts for the open button; without it a card posts as text. */
@@ -101,22 +105,24 @@ export class DiscordSurface
 		close: (threadId) => this.threadHost().close(threadId),
 	});
 	readonly #options: DiscordSurfaceOptions;
-	readonly #client = new Client({
-		intents: [
-			GatewayIntentBits.Guilds,
-			GatewayIntentBits.GuildMessages,
-			GatewayIntentBits.DirectMessages,
-			GatewayIntentBits.MessageContent,
-		],
-		partials: [Partials.Channel, Partials.Message],
-		allowedMentions: { parse: [] },
-	});
+	readonly #client: Client;
 
 	#interactions: ComposedCommands = { commands: [], modules: [] };
 	#onMessage: ((message: InboundMessage) => void) | undefined;
 
 	constructor(options: DiscordSurfaceOptions) {
 		this.#options = options;
+		this.#client = new Client({
+			intents: [
+				GatewayIntentBits.Guilds,
+				GatewayIntentBits.GuildMessages,
+				GatewayIntentBits.DirectMessages,
+				GatewayIntentBits.MessageContent,
+				...memberIntents(options.memberEvents),
+			],
+			partials: [Partials.Channel, Partials.Message],
+			allowedMentions: { parse: [] },
+		});
 		this.formatting = pickFormatting(options.formatting, DISCORD_FORMATTING);
 		// REST works before the gateway logs in; `login` sets the same token again.
 		this.#client.rest.setToken(options.token);
@@ -174,34 +180,9 @@ export class DiscordSurface
 		return new DiscordDashboard(this.#client, guildId, this.#options.logger);
 	}
 
-	/**
-	 * What a channel is called, for the web app's lists: undefined when Discord no longer knows
-	 * it; throws while the connection is not ready or Discord cannot be reached.
-	 */
-	async channelInfo(channelId: string): Promise<ChannelInfo | undefined> {
-		if (!this.#client.isReady()) throw new Error("Discord is not connected");
-		const channel = await this.#client.channels
-			.fetch(channelId)
-			.catch((error: unknown) => {
-				if (error instanceof DiscordAPIError && error.code === UNKNOWN_CHANNEL)
-					return null;
-				throw error;
-			});
-		if (!channel) return undefined;
-		if (channel.isDMBased())
-			return {
-				kind: "dm",
-				name:
-					channel.type === ChannelType.DM
-						? (channel.recipient?.username ?? "")
-						: (channel.name ?? ""),
-			};
-		return {
-			kind: "guild",
-			name: channel.name,
-			guild: channel.guild.name,
-			guildId: channel.guild.id,
-		};
+	/** See `DiscordConnection.channelInfo`. */
+	channelInfo(channelId: string): Promise<ChannelInfo | undefined> {
+		return channelInfoOf(this.#client, channelId);
 	}
 
 	/**
@@ -232,6 +213,11 @@ export class DiscordSurface
 		this.#client.on(Events.ChannelDelete, (channel) => handler(channel.id));
 	}
 
+	/** Reports members that join a server; register before start. Hears none unless `memberEvents` is on. */
+	onMemberJoined(handler: (event: MemberJoinedEvent) => void): void {
+		listenForJoins(this.#client, handler, this.#options.logger);
+	}
+
 	/** The approval and question cards in a Discord channel, for those the scope names. */
 	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
 		return this.#options.prompts(channel, scope);
@@ -289,7 +275,9 @@ export class DiscordSurface
 		const ready = new Promise<void>((resolve) =>
 			this.#client.once(Events.ClientReady, () => resolve()),
 		);
-		await this.#client.login(token);
+		await this.#client.login(token).catch((error: unknown) => {
+			throw explainIntents(error, this.#options.memberEvents);
+		});
 		await ready;
 		const { commands } = this.#interactions;
 		await this.#client.application?.commands.set(commands);

package/src/core/discord/member-events.ts

@@ -0,0 +1,44 @@
+import { type Client, Events, GatewayIntentBits } from "discord.js";
+import type { MemberJoinedEvent } from "../event-types.ts";
+import type { Logger } from "../log.ts";
+
+/** The privileged Server Members intent, asked for only when the host turns `discord.memberEvents` on. */
+export function memberIntents(
+	enabled: boolean | undefined,
+): GatewayIntentBits[] {
+	return enabled ? [GatewayIntentBits.GuildMembers] : [];
+}
+
+/** Reports each member that joins a server to `handler`; one that throws is logged and never stops the next. */
+export function listenForJoins(
+	client: Client,
+	handler: (event: MemberJoinedEvent) => void,
+	logger: Logger,
+): void {
+	client.on(Events.GuildMemberAdd, (member) => {
+		try {
+			handler({
+				surface: "discord",
+				guildId: member.guild.id,
+				userId: member.id,
+				bot: member.user.bot,
+			});
+		} catch (error) {
+			logger.error({ err: error }, "member join handler failed");
+		}
+	});
+}
+
+/** The error a failed login throws, with the portal switch named when Discord refused the Server Members intent. */
+export function explainIntents(
+	error: unknown,
+	enabled: boolean | undefined,
+): Error {
+	const failed = error instanceof Error ? error : new Error(String(error));
+	if (enabled && /disallowed intents/i.test(failed.message))
+		return new Error(
+			"Discord refused the Server Members intent that discord.memberEvents asks for. Turn on Server Members Intent under Bot in https://discord.com/developers/applications, save, and start again, or set discord.memberEvents to false.",
+			{ cause: failed },
+		);
+	return failed;
+}

package/src/core/discord/poster/poster-errors.ts

@@ -11,13 +11,17 @@ export type DiscordFailure =
 
 /**
  * More about why Discord refused, where its code alone does not say: a category that is full (a
- * 400 with a form-body error), a channel that is no category or forum, and one in no right guild.
+ * 400 with a form-body error), a channel that is no category or forum, one in no right guild, and
+ * a role that cannot be given or taken.
  */
 export type DiscordReason =
 	| "category_full"
 	| "not_category"
 	| "not_forum" // a forum call on a channel that is no forum, or a post call on a thread that is no forum post
-	| "wrong_guild";
+	| "wrong_guild"
+	| "role_unassignable" // a role the bot may not give or take: @everyone's, a managed one, or one at or above its own highest
+	| "unknown_role" // the guild has no such role
+	| "not_member"; // the user is not in the guild
 
 /**
  * A failed Discord call. The message names the operation and Discord's own reason, never a URL,

package/src/core/discord/poster/poster-roles.ts

@@ -0,0 +1,167 @@
+import { checkSnowflake } from "./poster-checks.ts";
+import { DiscordPosterError, invalid } from "./poster-errors.ts";
+
+/** What the poster keeps of Discord's limits on roles and audit-log reasons. */
+export const ROLE_LIMITS = Object.freeze({
+	/** The longest name Discord gives a role. */
+	nameChars: 100,
+	/** The longest audit-log reason Discord keeps. */
+	reasonChars: 512,
+	/** The most roles one `addMemberRoles` or `removeMemberRoles` call takes. */
+	perCall: 20,
+} as const);
+
+/** A role of a guild, as the poster reasons about whether it may be given. */
+export interface GuildRole {
+	id: string;
+	name: string;
+	/** Discord's order: a higher number sits higher, and @everyone is 0. */
+	position: number;
+	/** Made and kept by an integration or a bot, so it cannot be given by hand. */
+	managed: boolean;
+}
+
+/**
+ * The member and role calls of `DiscordPoster`. The poster only ever touches the roles a call
+ * names: it adds or removes them one by one, and never sends a member's whole role list.
+ */
+export interface MemberRoles {
+	/**
+	 * The ids of the roles a member holds, as Discord lists them (the @everyone role is not among
+	 * them); `undefined` for someone who is not a member of the guild.
+	 */
+	memberRoles(guildId: string, userId: string): Promise<string[] | undefined>;
+	/**
+	 * Gives a member these roles (Manage Roles), with `reason` in the guild's audit log (1 to 512
+	 * characters, else `invalid`; so are no role, more than 20, or an id that is no Discord id). All
+	 * are checked before any is given, and a role the member holds is left as it is. Refused, and
+	 * nothing given, for a role the bot may not hand out: the @everyone role (`invalid`), a managed
+	 * role, and one at or above the bot's highest role (`forbidden`, both with `role_unassignable`);
+	 * a role the guild does not have is `rejected` with `unknown_role`, and a user who is not a
+	 * member `rejected` with `not_member`.
+	 *
+	 * Not atomic: the checks run first, but a Discord failure after them (a 5xx, a timeout, a lost
+	 * permission) may leave the earlier roles of the call changed; the error names the role that
+	 * failed. Each change is idempotent, so retry the whole call and it converges.
+	 */
+	addMemberRoles(
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): Promise<void>;
+	/** Takes these roles from a member, under the same rules as `addMemberRoles`; a role the member lacks is left alone. */
+	removeMemberRoles(
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): Promise<void>;
+	/**
+	 * The id of the guild's role of that name (1 to 100 characters, exact match, not @everyone's
+	 * or a managed role), made with no permissions and no colour when there is none (Manage Roles,
+	 * `reason` in the audit log). A role that exists is never edited: its permissions, colour and
+	 * position stay as they are. With several of the name, the oldest. Calls for the same name run
+	 * one after another in this process, so two of them make one role; separate processes do not
+	 * coordinate and may make two. A role that exists may sit at or above the bot's highest role (or
+	 * be one the bot cannot hand out): it is returned all the same, and the next `addMemberRoles`
+	 * refuses it with `role_unassignable`.
+	 */
+	ensureRole(guildId: string, name: string, reason: string): Promise<string>;
+}
+
+/** An audit-log reason: 1 to 512 characters. */
+export function checkAuditReason(reason: string): string {
+	const trimmed = reason.trim();
+	if (trimmed === "") throw invalid("a role change needs an audit-log reason");
+	if ([...trimmed].length > ROLE_LIMITS.reasonChars)
+		throw invalid(
+			`an audit-log reason is at most ${ROLE_LIMITS.reasonChars} characters`,
+		);
+	return trimmed;
+}
+
+/** A role's name: 1 to 100 characters, and not one that reads as a mention of everyone. */
+export function checkRoleName(name: string): string {
+	const trimmed = name.trim();
+	if (trimmed === "" || [...trimmed].length > ROLE_LIMITS.nameChars)
+		throw invalid(`a role name is 1 to ${ROLE_LIMITS.nameChars} characters`);
+	if (/^@(everyone|here)$/i.test(trimmed))
+		throw invalid("a role cannot be named @everyone or @here");
+	return trimmed;
+}
+
+/** The roles a call names: at least one and at most 20, each a Discord id, each once. */
+export function checkRoleIds(roleIds: readonly string[]): string[] {
+	const wanted = [...new Set(roleIds)];
+	if (wanted.length === 0) throw invalid("name at least one role");
+	if (wanted.length > ROLE_LIMITS.perCall)
+		throw invalid(`a call takes at most ${ROLE_LIMITS.perCall} roles`);
+	return wanted.map((id) => checkSnowflake("a role", id));
+}
+
+/**
+ * Refuses, before anything is sent, a role the bot may not give or take: the @everyone role, a
+ * managed role, and a role at or above the bot's highest. The bot's own roles and the guild's
+ * come from Discord, so the answer is the one Discord would give, in words that name the cause.
+ */
+export function refuseUnassignable(
+	guildId: string,
+	roles: readonly GuildRole[],
+	botRoleIds: readonly string[],
+	wanted: readonly string[],
+): void {
+	const byId = new Map(roles.map((role) => [role.id, role]));
+	const top = Math.max(
+		0,
+		...botRoleIds.map((id) => byId.get(id)?.position ?? 0),
+	);
+	for (const id of wanted) {
+		if (id === guildId)
+			throw new DiscordPosterError(
+				"invalid",
+				"the @everyone role cannot be given or taken",
+				{ reason: "role_unassignable" },
+			);
+		const role = byId.get(id);
+		if (!role)
+			throw new DiscordPosterError("rejected", `the guild has no role ${id}`, {
+				reason: "unknown_role",
+			});
+		if (role.managed)
+			throw new DiscordPosterError(
+				"forbidden",
+				`the role ${id} is managed by an integration and cannot be given by hand`,
+				{ reason: "role_unassignable" },
+			);
+		if (role.position >= top)
+			throw new DiscordPosterError(
+				"forbidden",
+				`the role ${id} is at or above the bot's highest role`,
+				{ reason: "role_unassignable" },
+			);
+	}
+}
+
+/** The guild's role of that name that may be found by `ensureRole`: the oldest unmanaged one. */
+export function roleNamed(
+	guildId: string,
+	roles: readonly GuildRole[],
+	name: string,
+): GuildRole | undefined {
+	let found: GuildRole | undefined;
+	for (const role of roles) {
+		if (role.name !== name || role.managed || role.id === guildId) continue;
+		if (!found || BigInt(role.id) < BigInt(found.id)) found = role;
+	}
+	return found;
+}
+
+/** What `addMemberRoles` and `removeMemberRoles` throw for a user who is not in the guild. */
+export function notMember(): DiscordPosterError {
+	return new DiscordPosterError(
+		"rejected",
+		"that user is not a member of the guild",
+		{ reason: "not_member", discordCode: 10007, status: 404 },
+	);
+}

package/src/core/discord/poster/poster.ts

@@ -5,11 +5,15 @@
  * (from `pi-roundtable/testing`) stands in for it in tests, and no test reaches Discord.
  */
 
+import type { MemberRoles } from "./poster-roles.ts";
+
 export type {
 	DiscordFailure,
 	DiscordReason,
 } from "./poster-errors.ts";
 export { DiscordPosterError } from "./poster-errors.ts";
+export type { GuildRole, MemberRoles } from "./poster-roles.ts";
+export { ROLE_LIMITS } from "./poster-roles.ts";
 
 /** A file sent with a post. */
 export interface PosterFile {
@@ -297,7 +301,7 @@ export const DISCORD_LIMITS = Object.freeze({
 	postTags: 5,
 } as const);
 
-export interface DiscordPoster {
+export interface DiscordPoster extends MemberRoles {
 	// Webhook posts
 
 	/** Posts through the channel's webhook of that name, found or made on first use. */

package/src/core/discord/poster/rest-poster-core.ts

@@ -11,6 +11,8 @@ export interface RestOptions {
 	auth?: boolean;
 	/** Gives up on the request when it fires (a call that discord.js would otherwise hold for a rate limit). */
 	signal?: AbortSignal;
+	/** The audit-log reason of a change to a guild; discord.js sends it as `X-Audit-Log-Reason`. */
+	reason?: string;
 }
 
 /** The part of discord.js' `REST` the poster calls, so a test can answer without a network. */

package/src/core/discord/poster/rest-poster-roles.ts

@@ -0,0 +1,150 @@
+import { RESTJSONErrorCodes, Routes } from "discord.js";
+import { checkSnowflake } from "./poster-checks.ts";
+import { DiscordPosterError, failure, isCode } from "./poster-errors.ts";
+import {
+	checkAuditReason,
+	checkRoleIds,
+	checkRoleName,
+	type GuildRole,
+	type MemberRoles,
+	notMember,
+	refuseUnassignable,
+	roleNamed,
+} from "./poster-roles.ts";
+import { object, type RestCore, text } from "./rest-poster-core.ts";
+
+/** The poster's member and role calls. */
+export function roleOperations(core: RestCore): MemberRoles {
+	const { rest } = core;
+
+	const guildRoles = async (guildId: string): Promise<GuildRole[]> => {
+		const listed = await rest
+			.get(Routes.guildRoles(guildId))
+			.catch((error: unknown) => {
+				throw failure("listing the guild's roles", error);
+			});
+		return (Array.isArray(listed) ? listed : []).flatMap((entry) => {
+			const role = object(entry);
+			const id = text(role.id);
+			return id
+				? [
+						{
+							id,
+							name: text(role.name) ?? "",
+							position: typeof role.position === "number" ? role.position : 0,
+							managed: role.managed === true,
+						},
+					]
+				: [];
+		});
+	};
+
+	/** The ids of a member's roles; undefined for someone who is not in the guild. */
+	const rolesOf = async (
+		guildId: string,
+		userId: string,
+	): Promise<string[] | undefined> => {
+		let member: Record<string, unknown>;
+		try {
+			member = object(await rest.get(Routes.guildMember(guildId, userId)));
+		} catch (error) {
+			if (isCode(error, RESTJSONErrorCodes.UnknownMember)) return undefined;
+			throw failure("reading a guild member", error);
+		}
+		return Array.isArray(member.roles)
+			? member.roles.filter((id): id is string => typeof id === "string")
+			: [];
+	};
+
+	const change = async (
+		verb: "add" | "remove",
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): Promise<void> => {
+		checkSnowflake("a guild", guildId);
+		checkSnowflake("a user", userId);
+		const wanted = checkRoleIds(roleIds);
+		const why = checkAuditReason(reason);
+		// Everything is checked before the first role is given, so a refusal gives none; a Discord
+		// failure after that leaves the earlier roles changed, and the error names the one that failed.
+		const botRoles = await rolesOf(guildId, await core.bot());
+		if (!botRoles)
+			throw new DiscordPosterError(
+				"forbidden",
+				"the bot is not a member of that guild",
+			);
+		refuseUnassignable(guildId, await guildRoles(guildId), botRoles, wanted);
+		for (const roleId of wanted) {
+			const route = Routes.guildMemberRole(guildId, userId, roleId);
+			try {
+				if (verb === "add") await rest.put(route, { reason: why });
+				else await rest.delete(route, { reason: why });
+			} catch (error) {
+				if (isCode(error, RESTJSONErrorCodes.UnknownMember)) throw notMember();
+				throw failure(
+					verb === "add"
+						? `giving a member the role ${roleId}`
+						: `taking the role ${roleId} from a member`,
+					error,
+				);
+			}
+		}
+	};
+
+	const making = new Map<string, Promise<string>>();
+	const ensure = async (
+		guildId: string,
+		name: string,
+		reason: string,
+	): Promise<string> => {
+		const found = roleNamed(guildId, await guildRoles(guildId), name);
+		if (found) return found.id;
+		// No permissions, no colour, not shown apart and not pingable: a marker, nothing more.
+		const made = object(
+			await rest
+				.post(Routes.guildRoles(guildId), {
+					body: {
+						name,
+						permissions: "0",
+						hoist: false,
+						mentionable: false,
+					},
+					reason,
+				})
+				.catch((error: unknown) => {
+					throw failure("making a role", error);
+				}),
+		);
+		const id = text(made.id);
+		if (!id) throw new DiscordPosterError("rejected", "Discord made no role");
+		return id;
+	};
+
+	return {
+		async memberRoles(guildId, userId) {
+			checkSnowflake("a guild", guildId);
+			checkSnowflake("a user", userId);
+			return rolesOf(guildId, userId);
+		},
+		addMemberRoles: (guildId, userId, roleIds, reason) =>
+			change("add", guildId, userId, roleIds, reason),
+		removeMemberRoles: (guildId, userId, roleIds, reason) =>
+			change("remove", guildId, userId, roleIds, reason),
+		async ensureRole(guildId, name, reason) {
+			checkSnowflake("a guild", guildId);
+			const wanted = checkRoleName(name);
+			const why = checkAuditReason(reason);
+			const slot = `${guildId}:${wanted}`;
+			let pending = making.get(slot);
+			if (!pending) {
+				pending = ensure(guildId, wanted, why).finally(() =>
+					making.delete(slot),
+				);
+				making.set(slot, pending);
+			}
+			return pending;
+		},
+	};
+}

package/src/core/discord/poster/rest-poster.ts

@@ -21,6 +21,7 @@ import {
 import { forumOperations } from "./rest-poster-forum.ts";
 import { guildOperations } from "./rest-poster-guild.ts";
 import { readOperations } from "./rest-poster-read.ts";
+import { roleOperations } from "./rest-poster-roles.ts";
 
 export type { DiscordRest, RestOptions } from "./rest-poster-core.ts";
 export { restOf } from "./rest-poster-core.ts";
@@ -247,6 +248,7 @@ export function restPoster(
 	return {
 		...guild,
 		...forumOperations(core),
+		...roleOperations(core),
 		async post(channelId, post) {
 			checkSnowflake("a channel", channelId);
 			const { webhook: name, body, files } = checkedPost(post);

package/src/core/event-types.ts

@@ -0,0 +1,27 @@
+import type { ChannelKey } from "./sessions.ts";
+
+/** One thing a person did through a plugin's surface, as a handler hears of it. */
+export interface ActionEvent {
+	/** What was done, in the reporting plugin's words, such as "assign" or "close". */
+	kind: string;
+	/** The `Speaker.id` of who did it. */
+	actor: string;
+	principalId: string;
+	/** The conversation or page it concerns, when there is one. */
+	channel?: ChannelKey | `page:${string}`;
+	/** Whether it worked. */
+	ok: boolean;
+	at: Date;
+}
+
+/** Someone joined a server of a chat network, as a handler hears of it. */
+export interface MemberJoinedEvent {
+	/** The chat network the server is on. */
+	surface: "discord";
+	/** The server's id. */
+	guildId: string;
+	/** The id of whoever joined. */
+	userId: string;
+	/** Whether the one who joined is a bot. */
+	bot: boolean;
+}

package/src/core/events.ts

@@ -53,5 +53,6 @@ export class EventBus {
 		turnProgress: (event) => void this.deliver("turnProgress", event),
 		changed: () => void this.deliver("changed"),
 		action: (event) => void this.deliver("action", event),
+		memberJoined: (event) => void this.deliver("memberJoined", event),
 	};
 }

package/src/core/plugin.ts

@@ -18,6 +18,7 @@ import type { Migration } from "./db/migrations.ts";
 import type { ToolContribution } from "./define.ts";
 import type { TurnProgress } from "./domain/progress.ts";
 import { PluginError } from "./errors.ts";
+import type { ActionEvent, MemberJoinedEvent } from "./event-types.ts";
 import type { HoldCheck, HoldRule } from "./holds.ts";
 import type { HttpRoute, ListenerAddress } from "./http/listeners.ts";
 import type { Locale } from "./i18n/index.ts";
@@ -37,6 +38,8 @@ import type {
 import type { Speaker, Tier } from "./speakers.ts";
 import type { ToolTiers } from "./tool-tiers.ts";
 
+export type { ActionEvent, MemberJoinedEvent };
+
 /** A long-lived part of a plugin. Services start in registration order and stop in reverse, so one registered earlier outlives those after it. */
 export interface Service {
 	name: string;
@@ -113,24 +116,15 @@ export interface EventHandlers {
 	 * the kind, who did it and whether it worked, never the content.
 	 */
 	action?(event: ActionEvent): Promise<void> | void;
+	/**
+	 * Someone joined the Discord server. Reported only when the host's `discord.memberEvents` is
+	 * on, which asks Discord for the privileged Server Members intent; otherwise never.
+	 */
+	memberJoined?(event: MemberJoinedEvent): Promise<void> | void;
 	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
 	shutdown?(left: readonly string[]): Promise<void> | void;
 }
 
-/** One thing a person did through a plugin's surface, as a handler hears of it. */
-export interface ActionEvent {
-	/** What was done, in the reporting plugin's words, such as "assign" or "close". */
-	kind: string;
-	/** The `Speaker.id` of who did it. */
-	actor: string;
-	principalId: string;
-	/** The conversation or page it concerns, when there is one. */
-	channel?: ChannelKey | `page:${string}`;
-	/** Whether it worked. */
-	ok: boolean;
-	at: Date;
-}
-
 /** What the core reports to the plugins' handlers. */
 export interface EventSink {
 	turnStarted(turn: TurnEvent): void;
@@ -140,6 +134,8 @@ export interface EventSink {
 	changed(): void;
 	/** Optional, as `turnProgress` is: a sink of your own written before it still fits. */
 	action?(event: ActionEvent): void;
+	/** Optional, as `action` is. */
+	memberJoined?(event: MemberJoinedEvent): void;
 }
 
 /** What a prompt section is built for: one agent's turn. */

package/src/core/testing/fake-poster-roles.ts

@@ -0,0 +1,155 @@
+import { checkSnowflake } from "../discord/poster/poster-checks.ts";
+import { DiscordPosterError } from "../discord/poster/poster-errors.ts";
+import {
+	checkAuditReason,
+	checkRoleIds,
+	checkRoleName,
+	type GuildRole,
+	notMember,
+	refuseUnassignable,
+	roleNamed,
+} from "../discord/poster/poster-roles.ts";
+import { FakePosterReads } from "./fake-poster-reads.ts";
+
+/** One change of a role or of a member's roles, as the fake's audit log holds it. */
+export interface FakeRoleChange {
+	action: "add" | "remove" | "create";
+	guildId: string;
+	roleId: string;
+	/** The member, for an `add` or a `remove`. */
+	userId?: string;
+	reason: string;
+}
+
+/** The fake's member and role calls, on top of its channel, thread, forum and read calls. */
+export abstract class FakePosterRoles extends FakePosterReads {
+	/** The guild's roles by id, @everyone's left out; `ensureRole` makes more. A test sets them up here. */
+	readonly roles = new Map<string, GuildRole>();
+	/** The ids of the roles the bot holds; the bot may give only roles below its highest. */
+	botRoles: string[] = [];
+	/**
+	 * The ids of the roles each member holds, by user id. A user is a member when `memberNames`
+	 * or this map lists them (and `nonMembers` does not).
+	 */
+	readonly memberRoleIds = new Map<string, string[]>();
+	/** Every change of roles, in order, with its audit-log reason. */
+	readonly roleChanges: FakeRoleChange[] = [];
+	protected nextRole = 5_000_000_000_000_000_000n;
+
+	protected constructor(idOffset: bigint, now: () => number) {
+		super(idOffset, now);
+		this.nextRole += idOffset;
+	}
+
+	#held(guildId: string, userId: string): string[] | undefined {
+		if (guildId !== this.guildId || this.nonMembers.has(userId))
+			return undefined;
+		const held = this.memberRoleIds.get(userId);
+		if (!(held || this.memberNames.has(userId))) return undefined;
+		return [...(held ?? [])];
+	}
+
+	async memberRoles(
+		guildId: string,
+		userId: string,
+	): Promise<string[] | undefined> {
+		checkSnowflake("a guild", guildId);
+		checkSnowflake("a user", userId);
+		this.sent("memberRoles");
+		return this.#held(guildId, userId);
+	}
+
+	async addMemberRoles(
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): Promise<void> {
+		this.#change("add", guildId, userId, roleIds, reason);
+	}
+
+	async removeMemberRoles(
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): Promise<void> {
+		this.#change("remove", guildId, userId, roleIds, reason);
+	}
+
+	#change(
+		action: "add" | "remove",
+		guildId: string,
+		userId: string,
+		roleIds: readonly string[],
+		reason: string,
+	): void {
+		checkSnowflake("a guild", guildId);
+		checkSnowflake("a user", userId);
+		const wanted = checkRoleIds(roleIds);
+		const why = checkAuditReason(reason);
+		this.sent(action === "add" ? "addMemberRoles" : "removeMemberRoles");
+		if (guildId !== this.guildId)
+			throw new DiscordPosterError(
+				"forbidden",
+				"the bot is not a member of that guild",
+			);
+		refuseUnassignable(
+			guildId,
+			[...this.roles.values()],
+			this.botRoles,
+			wanted,
+		);
+		const held = this.#held(guildId, userId);
+		if (!held) throw notMember();
+		let next = held;
+		for (const roleId of wanted) {
+			next =
+				action === "add"
+					? next.includes(roleId)
+						? next
+						: [...next, roleId]
+					: next.filter((id) => id !== roleId);
+			this.roleChanges.push({
+				action,
+				guildId,
+				roleId,
+				userId,
+				reason: why,
+			});
+		}
+		this.memberRoleIds.set(userId, next);
+	}
+
+	async ensureRole(
+		guildId: string,
+		name: string,
+		reason: string,
+	): Promise<string> {
+		checkSnowflake("a guild", guildId);
+		const wanted = checkRoleName(name);
+		const why = checkAuditReason(reason);
+		this.sent("ensureRole");
+		if (guildId !== this.guildId)
+			throw new DiscordPosterError(
+				"forbidden",
+				"the bot is not a member of that guild",
+			);
+		const found = roleNamed(guildId, [...this.roles.values()], wanted);
+		if (found) return found.id;
+		// Discord puts a new role just above @everyone and moves the others up.
+		for (const [id, role] of this.roles)
+			if (role.position >= 1)
+				this.roles.set(id, { ...role, position: role.position + 1 });
+		this.nextRole += 1n;
+		const id = this.nextRole.toString();
+		this.roles.set(id, { id, name: wanted, position: 1, managed: false });
+		this.roleChanges.push({
+			action: "create",
+			guildId,
+			roleId: id,
+			reason: why,
+		});
+		return id;
+	}
+}

package/src/core/testing/fake-poster.ts

@@ -1,6 +1,7 @@
 import type {
 	DiscordCard,
 	DiscordPoster,
+	GuildRole,
 	PostedMessage,
 } from "../discord/poster/poster.ts";
 import {
@@ -21,7 +22,7 @@ import type {
 	FakePosterChannel,
 	FakePosterMessage,
 } from "./fake-poster-guild.ts";
-import { FakePosterReads } from "./fake-poster-reads.ts";
+import { FakePosterRoles, type FakeRoleChange } from "./fake-poster-roles.ts";
 
 export type { FakeForum } from "./fake-poster-forum.ts";
 export type {
@@ -29,6 +30,7 @@ export type {
 	FakePosterMessage,
 } from "./fake-poster-guild.ts";
 export { cardText } from "./fake-poster-guild.ts";
+export type { FakeRoleChange } from "./fake-poster-roles.ts";
 
 function blobOf(file: { data: Uint8Array; contentType?: string }) {
 	return {
@@ -77,6 +79,14 @@ export interface FakeDiscordPoster extends DiscordPoster {
 	readonly requests: number;
 	/** Makes the next call of `operation` throw `error`. */
 	failNext(operation: keyof DiscordPoster, error: DiscordPosterError): void;
+	/** The guild's roles by id, @everyone's left out; `ensureRole` makes more. Set them up here. */
+	readonly roles: Map<string, GuildRole>;
+	/** The ids of the roles the bot holds; it may give only roles below its highest. */
+	botRoles: string[];
+	/** The ids of the roles each member holds, by user id; a user is a member when `memberNames` or this lists them. */
+	readonly memberRoleIds: Map<string, string[]>;
+	/** Every change of roles, in order, with its audit-log reason. */
+	readonly roleChanges: FakeRoleChange[];
 	/** The channel's messages that still exist, oldest first. */
 	messagesIn(channelId: string): FakePosterMessage[];
 	/** A person writes in the channel (not through a webhook); the message's id. */
@@ -114,7 +124,7 @@ export interface FakeDiscordPoster extends DiscordPoster {
  * the next call or to refuse direct messages from a person. The same scenarios run against it and
  * against the real poster over an emulated Discord, so the two answer alike.
  */
-class FakePosterImpl extends FakePosterReads implements FakeDiscordPoster {
+class FakePosterImpl extends FakePosterRoles implements FakeDiscordPoster {
 	readonly #webhooks = new Map<string, string>();
 	readonly #madeListeners = new Set<
 		(channelId: string, webhook: string) => Promise<void>

package/src/discord/index.ts

@@ -95,6 +95,8 @@ export type {
 	ForumPostCreated,
 	ForumTag,
 	ForumTagInput,
+	GuildRole,
+	MemberRoles,
 	PostedMessage,
 	PosterFile,
 	RecentMessage,
@@ -107,6 +109,7 @@ export type {
 export {
 	DISCORD_LIMITS,
 	DiscordPosterError,
+	ROLE_LIMITS,
 } from "../core/discord/poster/poster.ts";
 export type { OwnerOperations } from "../core/modules/discord-admin/discord-admin.ts";
 export { DISCORD_ADMIN_TOOLS } from "../core/modules/discord-admin/discord-admin.ts";

package/src/index.ts

@@ -351,6 +351,7 @@ export type {
 	EventSink,
 	HostEnv,
 	LinkedSessions,
+	MemberJoinedEvent,
 	Persona,
 	PluginContext,
 	PluginIdentity,

package/src/testing.ts

@@ -106,6 +106,7 @@ export type {
 	FakeForum,
 	FakePosterChannel,
 	FakePosterMessage,
+	FakeRoleChange,
 } from "./core/testing/fake-poster.ts";
 export { fakeDiscordPoster } from "./core/testing/fake-poster.ts";
 export type { TestLocale } from "./core/testing/locale.ts";