discoclaw 0.1.0

package/dist/discord.channel-context.test.js

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveDiscordChannelContext, validatePaContextModules, loadDiscordChannelContext, ensureIndexedDiscordChannelContext } from './discord/channel-context.js';
+describe('resolveDiscordChannelContext', () => {
+    it('returns no contextPath for unknown guild channels (strict mode can require indexing)', () => {
+        const ctx = {
+            contentDir: '/content',
+            indexPath: '/content/discord/DISCORD.md',
+            paContextFiles: ['/.context/pa.md'],
+            channelsDir: '/content/discord/channels',
+            byChannelId: new Map(),
+            dmContextPath: '/content/discord/channels/dm.md',
+        };
+        const res = resolveDiscordChannelContext({ ctx, isDm: false, channelId: '1', threadParentId: null });
+        expect(res.contextPath).toBeUndefined();
+    });
+    it('uses dm context for DMs', () => {
+        const ctx = {
+            contentDir: '/content',
+            indexPath: '/content/discord/DISCORD.md',
+            paContextFiles: ['/.context/pa.md'],
+            channelsDir: '/content/discord/channels',
+            byChannelId: new Map(),
+            dmContextPath: '/content/discord/channels/dm.md',
+        };
+        const res = resolveDiscordChannelContext({ ctx, isDm: true, channelId: 'dmchan', threadParentId: null });
+        expect(res.contextPath).toBe('/content/discord/channels/dm.md');
+    });
+});
+describe('validatePaContextModules', () => {
+    const tempDirs = [];
+    afterEach(async () => {
+        await Promise.all(tempDirs.map((d) => fs.rm(d, { recursive: true, force: true })));
+        tempDirs.length = 0;
+    });
+    it('throws when pa.md is missing', async () => {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'pa-validate-'));
+        tempDirs.push(dir);
+        // Create only pa-safety.md, omit pa.md.
+        await fs.writeFile(path.join(dir, 'pa-safety.md'), '# Safety', 'utf-8');
+        await expect(validatePaContextModules(dir)).rejects.toThrow(/pa\.md/);
+    });
+    it('throws when contextModulesDir does not exist', async () => {
+        await expect(validatePaContextModules('/nonexistent/path')).rejects.toThrow();
+    });
+    it('succeeds when all modules are present', async () => {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'pa-validate-'));
+        tempDirs.push(dir);
+        await fs.writeFile(path.join(dir, 'pa.md'), '# PA', 'utf-8');
+        await expect(validatePaContextModules(dir)).resolves.toBeUndefined();
+    });
+});
+describe('loadDiscordChannelContext', () => {
+    const tempDirs = [];
+    afterEach(async () => {
+        await Promise.all(tempDirs.map((d) => fs.rm(d, { recursive: true, force: true })));
+        tempDirs.length = 0;
+    });
+    it('populates paContextFiles with correct paths', async () => {
+        const contentDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ctx-load-'));
+        const contextModulesDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ctx-modules-'));
+        tempDirs.push(contentDir, contextModulesDir);
+        await fs.writeFile(path.join(contextModulesDir, 'pa.md'), '# PA', 'utf-8');
+        await fs.mkdir(path.join(contentDir, 'discord', 'channels'), { recursive: true });
+        const ctx = await loadDiscordChannelContext({ contentDir, contextModulesDir });
+        expect(ctx.paContextFiles).toHaveLength(1);
+        expect(ctx.paContextFiles[0]).toBe(path.join(contextModulesDir, 'pa.md'));
+    });
+});
+describe('channelContextTemplate regression', () => {
+    const tempDirs = [];
+    afterEach(async () => {
+        await Promise.all(tempDirs.map((d) => fs.rm(d, { recursive: true, force: true })));
+        tempDirs.length = 0;
+    });
+    it('new channel files do not contain Includes or ../base/', async () => {
+        const contentDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ctx-template-'));
+        const contextModulesDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ctx-modules-'));
+        tempDirs.push(contentDir, contextModulesDir);
+        await fs.writeFile(path.join(contextModulesDir, 'pa.md'), '# PA', 'utf-8');
+        await fs.writeFile(path.join(contextModulesDir, 'pa-safety.md'), '# Safety', 'utf-8');
+        await fs.mkdir(path.join(contentDir, 'discord', 'channels'), { recursive: true });
+        const ctx = await loadDiscordChannelContext({ contentDir, contextModulesDir });
+        const entry = await ensureIndexedDiscordChannelContext({
+            ctx,
+            channelId: '12345678901234567890',
+            channelName: 'test-channel',
+        });
+        const content = await fs.readFile(entry.contextPath, 'utf-8');
+        expect(content).not.toContain('Includes');
+        expect(content).not.toContain('../base/');
+    });
+});

package/dist/discord.fail-closed.test.js

@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMessageCreateHandler } from './discord.js';
+function makeQueue() {
+    return {
+        run: vi.fn(async (_key, fn) => fn()),
+    };
+}
+describe('Discord handler (fail closed)', () => {
+    it('does not respond when allowUserIds is empty', async () => {
+        const queue = makeQueue();
+        const handler = createMessageCreateHandler({
+            allowUserIds: new Set(),
+            runtime: { invoke: async function* () { yield { type: 'text_final', text: 'hi' }; } },
+            sessionManager: { getOrCreate: vi.fn(async () => 'sess') },
+            workspaceCwd: '/tmp',
+            projectCwd: '/tmp',
+            groupsDir: '/tmp',
+            useGroupDirCwd: false,
+            runtimeModel: 'opus',
+            runtimeTools: [],
+            runtimeTimeoutMs: 1000,
+            requireChannelContext: true,
+            autoIndexChannelContext: true,
+            autoJoinThreads: false,
+            useRuntimeSessions: true,
+            discordActionsEnabled: false,
+            discordActionsChannels: true,
+            discordActionsMessaging: false,
+            discordActionsGuild: false,
+            discordActionsModeration: false,
+            discordActionsPolls: false,
+            discordActionsTasks: false,
+            discordActionsBotProfile: false,
+            messageHistoryBudget: 0,
+            summaryEnabled: false,
+            summaryModel: 'haiku',
+            summaryMaxChars: 2000,
+            summaryEveryNTurns: 5,
+            summaryDataDir: '/tmp/summaries',
+            summaryToDurableEnabled: false,
+            shortTermMemoryEnabled: false,
+            shortTermDataDir: '/tmp/shortterm',
+            shortTermMaxEntries: 20,
+            shortTermMaxAgeMs: 21600000,
+            shortTermInjectMaxChars: 1000,
+            durableMemoryEnabled: false,
+            durableDataDir: '/tmp/durable',
+            durableInjectMaxChars: 2000,
+            durableMaxItems: 200,
+            memoryCommandsEnabled: false,
+            actionFollowupDepth: 0,
+            reactionHandlerEnabled: false,
+            reactionRemoveHandlerEnabled: false,
+            reactionMaxAgeMs: 86400000,
+            streamStallWarningMs: 0,
+            botDisplayName: 'TestBot',
+        }, queue);
+        const msg = {
+            author: { id: '123', bot: false },
+            guildId: 'guild',
+            channelId: 'chan',
+            channel: { send: vi.fn() },
+            content: 'hello',
+            reply: vi.fn(),
+        };
+        await handler(msg);
+        expect(msg.reply).not.toHaveBeenCalled();
+        expect(queue.run).not.toHaveBeenCalled();
+    });
+    it('does not respond in non-allowed guild channels when DISCORD_CHANNEL_IDS is set', async () => {
+        const queue = makeQueue();
+        const handler = createMessageCreateHandler({
+            allowUserIds: new Set(['123']),
+            allowChannelIds: new Set(['allowed']),
+            runtime: { invoke: async function* () { yield { type: 'text_final', text: 'hi' }; } },
+            sessionManager: { getOrCreate: vi.fn(async () => 'sess') },
+            workspaceCwd: '/tmp',
+            projectCwd: '/tmp',
+            groupsDir: '/tmp',
+            useGroupDirCwd: false,
+            runtimeModel: 'opus',
+            runtimeTools: [],
+            runtimeTimeoutMs: 1000,
+            requireChannelContext: true,
+            autoIndexChannelContext: true,
+            autoJoinThreads: false,
+            useRuntimeSessions: true,
+            discordActionsEnabled: false,
+            discordActionsChannels: true,
+            discordActionsMessaging: false,
+            discordActionsGuild: false,
+            discordActionsModeration: false,
+            discordActionsPolls: false,
+            discordActionsTasks: false,
+            discordActionsBotProfile: false,
+            messageHistoryBudget: 0,
+            summaryEnabled: false,
+            summaryModel: 'haiku',
+            summaryMaxChars: 2000,
+            summaryEveryNTurns: 5,
+            summaryDataDir: '/tmp/summaries',
+            summaryToDurableEnabled: false,
+            shortTermMemoryEnabled: false,
+            shortTermDataDir: '/tmp/shortterm',
+            shortTermMaxEntries: 20,
+            shortTermMaxAgeMs: 21600000,
+            shortTermInjectMaxChars: 1000,
+            durableMemoryEnabled: false,
+            durableDataDir: '/tmp/durable',
+            durableInjectMaxChars: 2000,
+            durableMaxItems: 200,
+            memoryCommandsEnabled: false,
+            actionFollowupDepth: 0,
+            reactionHandlerEnabled: false,
+            reactionRemoveHandlerEnabled: false,
+            reactionMaxAgeMs: 86400000,
+            streamStallWarningMs: 0,
+            botDisplayName: 'TestBot',
+        }, queue);
+        const msg = {
+            author: { id: '123', bot: false },
+            guildId: 'guild',
+            channelId: 'not-allowed',
+            channel: { send: vi.fn() },
+            content: 'hello',
+            reply: vi.fn(),
+        };
+        await handler(msg);
+        expect(msg.reply).not.toHaveBeenCalled();
+        expect(queue.run).not.toHaveBeenCalled();
+    });
+    it('does not send Message Content Intent hint in non-allowed guild channels', async () => {
+        const queue = makeQueue();
+        const handler = createMessageCreateHandler({
+            allowUserIds: new Set(['123']),
+            allowChannelIds: new Set(['allowed']),
+            runtime: { invoke: async function* () { yield { type: 'text_final', text: 'hi' }; } },
+            sessionManager: { getOrCreate: vi.fn(async () => 'sess') },
+            workspaceCwd: '/tmp',
+            projectCwd: '/tmp',
+            groupsDir: '/tmp',
+            useGroupDirCwd: false,
+            runtimeModel: 'opus',
+            runtimeTools: [],
+            runtimeTimeoutMs: 1000,
+            requireChannelContext: true,
+            autoIndexChannelContext: true,
+            autoJoinThreads: false,
+            useRuntimeSessions: true,
+            discordActionsEnabled: false,
+            discordActionsChannels: true,
+            discordActionsMessaging: false,
+            discordActionsGuild: false,
+            discordActionsModeration: false,
+            discordActionsPolls: false,
+            discordActionsTasks: false,
+            discordActionsBotProfile: false,
+            messageHistoryBudget: 0,
+            summaryEnabled: false,
+            summaryModel: 'haiku',
+            summaryMaxChars: 2000,
+            summaryEveryNTurns: 5,
+            summaryDataDir: '/tmp/summaries',
+            summaryToDurableEnabled: false,
+            shortTermMemoryEnabled: false,
+            shortTermDataDir: '/tmp/shortterm',
+            shortTermMaxEntries: 20,
+            shortTermMaxAgeMs: 21600000,
+            shortTermInjectMaxChars: 1000,
+            durableMemoryEnabled: false,
+            durableDataDir: '/tmp/durable',
+            durableInjectMaxChars: 2000,
+            durableMaxItems: 200,
+            memoryCommandsEnabled: false,
+            actionFollowupDepth: 0,
+            reactionHandlerEnabled: false,
+            reactionRemoveHandlerEnabled: false,
+            reactionMaxAgeMs: 86400000,
+            streamStallWarningMs: 0,
+            botDisplayName: 'TestBot',
+        }, queue);
+        const msg = {
+            author: { id: '123', bot: false },
+            guildId: 'guild',
+            channelId: 'not-allowed',
+            channel: { send: vi.fn() },
+            content: '',
+            attachments: { size: 0 },
+            stickers: { size: 0 },
+            embeds: [],
+            mentions: { has: vi.fn(() => true) },
+            client: { user: { id: 'bot-user' } },
+            reply: vi.fn(),
+        };
+        await handler(msg);
+        expect(msg.reply).not.toHaveBeenCalled();
+        expect(queue.run).not.toHaveBeenCalled();
+    });
+});

package/dist/discord.health-command.integration.test.js

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMessageCreateHandler } from './discord.js';
+import { MetricsRegistry } from './observability/metrics.js';
+function makeQueue() {
+    return {
+        run: vi.fn(async (_key, fn) => fn()),
+        size: vi.fn(() => 0),
+    };
+}
+function makeMsg(content, authorId = '123') {
+    return {
+        author: { id: authorId, bot: false, displayName: 'User', username: 'user' },
+        guildId: 'guild',
+        channelId: 'chan',
+        channel: { send: vi.fn(async () => ({})), isThread: () => false, name: 'general' },
+        content,
+        reply: vi.fn(async (_opts) => ({ edit: vi.fn(async () => { }) })),
+        id: 'msg1',
+    };
+}
+function baseParams(metrics, overrides = {}) {
+    return {
+        allowUserIds: new Set(['123']),
+        botDisplayName: 'TestBot',
+        runtime: { invoke: vi.fn(async function* () { yield { type: 'text_final', text: 'ok' }; }) },
+        sessionManager: { getOrCreate: vi.fn(async () => 'sess') },
+        workspaceCwd: '/tmp',
+        projectCwd: '/tmp',
+        groupsDir: '/tmp',
+        useGroupDirCwd: false,
+        runtimeModel: 'opus',
+        runtimeTools: ['Read', 'Edit'],
+        runtimeTimeoutMs: 1000,
+        requireChannelContext: false,
+        autoIndexChannelContext: false,
+        autoJoinThreads: false,
+        useRuntimeSessions: true,
+        discordActionsEnabled: false,
+        discordActionsChannels: true,
+        discordActionsMessaging: false,
+        discordActionsGuild: false,
+        discordActionsModeration: false,
+        discordActionsPolls: false,
+        discordActionsTasks: false,
+        discordActionsBotProfile: false,
+        messageHistoryBudget: 0,
+        summaryEnabled: false,
+        summaryModel: 'haiku',
+        summaryMaxChars: 2000,
+        summaryEveryNTurns: 5,
+        summaryDataDir: '/tmp/summaries',
+        summaryToDurableEnabled: false,
+        shortTermMemoryEnabled: false,
+        shortTermDataDir: '/tmp/shortterm',
+        shortTermMaxEntries: 20,
+        shortTermMaxAgeMs: 21600000,
+        shortTermInjectMaxChars: 1000,
+        durableMemoryEnabled: false,
+        durableDataDir: '/tmp/durable',
+        durableInjectMaxChars: 2000,
+        durableMaxItems: 200,
+        memoryCommandsEnabled: false,
+        actionFollowupDepth: 0,
+        reactionHandlerEnabled: false,
+        reactionRemoveHandlerEnabled: false,
+        reactionMaxAgeMs: 86400000,
+        streamStallWarningMs: 0,
+        healthCommandsEnabled: true,
+        healthVerboseAllowlist: new Set(),
+        healthConfigSnapshot: {
+            runtimeModel: 'opus',
+            runtimeTimeoutMs: 1000,
+            runtimeTools: ['Read', 'Edit'],
+            useRuntimeSessions: true,
+            toolAwareStreaming: false,
+            maxConcurrentInvocations: 0,
+            discordActionsEnabled: false,
+            summaryEnabled: false,
+            durableMemoryEnabled: false,
+            messageHistoryBudget: 0,
+            reactionHandlerEnabled: false,
+            reactionRemoveHandlerEnabled: false,
+            cronEnabled: false,
+            tasksEnabled: false,
+            tasksActive: false,
+            tasksSyncFailureRetryEnabled: true,
+            tasksSyncFailureRetryDelayMs: 30000,
+            tasksSyncDeferredRetryDelayMs: 30000,
+            requireChannelContext: false,
+            autoIndexChannelContext: false,
+        },
+        metrics,
+        ...overrides,
+    };
+}
+describe('health command integration', () => {
+    it('handles !health without invoking runtime', async () => {
+        const metrics = new MetricsRegistry();
+        const queue = makeQueue();
+        const params = baseParams(metrics);
+        const handler = createMessageCreateHandler(params, queue);
+        const msg = makeMsg('!health');
+        await handler(msg);
+        expect(msg.reply).toHaveBeenCalledOnce();
+        expect(params.runtime.invoke).not.toHaveBeenCalled();
+        const payload = msg.reply.mock.calls[0]?.[0];
+        expect(payload).toBeTruthy();
+        expect(payload.content).toContain('TestBot Health');
+    });
+    it('falls back to basic for !health verbose when user is not in verbose allowlist', async () => {
+        const metrics = new MetricsRegistry();
+        const queue = makeQueue();
+        const params = baseParams(metrics, {
+            healthVerboseAllowlist: new Set(['999']),
+        });
+        const handler = createMessageCreateHandler(params, queue);
+        const msg = makeMsg('!health verbose', '123');
+        await handler(msg);
+        const payload = msg.reply.mock.calls[0]?.[0];
+        expect(payload).toBeTruthy();
+        expect(payload.content).not.toContain('Config (safe)');
+    });
+    it('handles !health tools with live effective tools output', async () => {
+        const metrics = new MetricsRegistry();
+        const queue = makeQueue();
+        const params = baseParams(metrics, {
+            runtimeTools: ['Read', 'Edit', 'WebSearch'],
+        });
+        const handler = createMessageCreateHandler(params, queue);
+        const msg = makeMsg('!health tools');
+        await handler(msg);
+        expect(msg.reply).toHaveBeenCalledOnce();
+        expect(params.runtime.invoke).not.toHaveBeenCalled();
+        const payload = msg.reply.mock.calls[0]?.[0];
+        expect(payload).toBeTruthy();
+        expect(payload.content).toContain('TestBot Tools');
+        expect(payload.content).toContain('Permission tier: env');
+        expect(payload.content).toContain('Effective tools: Read, Edit, WebSearch');
+    });
+});

package/dist/discord.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs/promises';
+import { ActivityType, Client, GatewayIntentBits, Partials } from 'discord.js';
+import { KeyedQueue } from './group-queue.js';
+import { ACTIVITY_TYPE_MAP } from './discord/actions-bot-profile.js';
+import { createStatusPoster } from './discord/status-channel.js';
+import { ensureSystemScaffold, selectBootstrapGuild } from './discord/system-bootstrap.js';
+import { createReactionAddHandler, createReactionRemoveHandler } from './discord/reaction-handler.js';
+import { createMessageCreateHandler } from './discord/message-coordinator.js';
+export { createMessageCreateHandler };
+export { ensureGroupDir, groupDirNameFromSessionKey, splitDiscord, truncateCodeBlocks, renderDiscordTail, renderActivityTail, formatBoldLabel, thinkingLabel, selectStreamingOutput, formatElapsed, } from './discord/message-coordinator.js';
+// ---------------------------------------------------------------------------
+// Shared forge/plan state — delegated to forge-plan-registry.ts
+// ---------------------------------------------------------------------------
+import { getActiveForgeId as registryGetActiveForgeId } from './discord/forge-plan-registry.js';
+/** Returns the active forge plan ID if a forge is running, undefined otherwise. */
+export function getActiveForgeId() {
+    return registryGetActiveForgeId();
+}
+export async function setBotNickname(guild, nickname, log) {
+    try {
+        let me = guild.members?.me;
+        if (!me) {
+            try {
+                me = await guild.members.fetchMe();
+            }
+            catch {
+                log?.warn({ guildId: guild.id }, 'discord:nickname could not fetch bot member');
+                return;
+            }
+        }
+        // Skip if nickname already matches.
+        if (me.nickname === nickname)
+            return;
+        // Skip if no nickname is set and the username already matches.
+        if (me.nickname == null && me.user?.username === nickname)
+            return;
+        await me.setNickname(nickname, 'Automatic nickname from bot identity');
+        log?.info({ guildId: guild.id, nickname }, 'discord:nickname set');
+    }
+    catch (err) {
+        if (err?.code === 50013) {
+            log?.warn({ guildId: guild.id }, 'discord:nickname Missing Permissions — cannot set nickname');
+        }
+        else {
+            log?.warn({ err, guildId: guild.id }, 'discord:nickname failed to set');
+        }
+    }
+}
+function resolveStatusChannel(client, nameOrId, statusOpts) {
+    // Try by ID first, then by name across all guilds.
+    const byId = client.channels.cache.get(nameOrId);
+    if (byId?.isTextBased() && !byId.isDMBased())
+        return createStatusPoster(byId, statusOpts);
+    for (const guild of client.guilds.cache.values()) {
+        const ch = guild.channels.cache.find((c) => c.isTextBased() && c.name === nameOrId);
+        if (ch && ch.isTextBased())
+            return createStatusPoster(ch, statusOpts);
+    }
+    return null;
+}
+async function resolveStatusChannelById(client, channelId, statusOpts) {
+    const cached = client.channels.cache.get(channelId);
+    const ch = cached ?? await client.channels.fetch(channelId).catch(() => null);
+    if (ch?.isTextBased() && !ch.isDMBased())
+        return createStatusPoster(ch, statusOpts);
+    return null;
+}
+export async function startDiscordBot(params) {
+    const client = new Client({
+        intents: [
+            GatewayIntentBits.Guilds,
+            GatewayIntentBits.GuildMessages,
+            GatewayIntentBits.MessageContent,
+            GatewayIntentBits.DirectMessages,
+            ...((params.reactionHandlerEnabled || params.reactionRemoveHandlerEnabled) ? [GatewayIntentBits.GuildMessageReactions] : []),
+        ],
+        partials: [
+            Partials.Channel,
+            ...((params.reactionHandlerEnabled || params.reactionRemoveHandlerEnabled) ? [Partials.Message, Partials.Reaction, Partials.User] : []),
+        ],
+    });
+    // Mutable ref: handler captures this at registration time, but dereferences
+    // .current at call time so we can set it after the ready event.
+    const statusRef = { current: null };
+    const queue = new KeyedQueue();
+    client.on('messageCreate', createMessageCreateHandler(params, queue, statusRef));
+    if (params.reactionHandlerEnabled) {
+        client.on('messageReactionAdd', createReactionAddHandler(params, queue, statusRef));
+    }
+    if (params.reactionRemoveHandlerEnabled) {
+        client.on('messageReactionRemove', createReactionRemoveHandler(params, queue, statusRef));
+    }
+    if (params.autoJoinThreads) {
+        client.on('threadCreate', async (thread) => {
+            const joinable = typeof thread?.joinable === 'boolean' ? thread.joinable : true;
+            const joined = typeof thread?.joined === 'boolean' ? thread.joined : false;
+            if (!joinable || joined || typeof thread?.join !== 'function')
+                return;
+            try {
+                await thread.join();
+                params.log?.info({ threadId: String(thread.id ?? ''), parentId: String(thread.parentId ?? '') }, 'discord:thread joined (threadCreate)');
+            }
+            catch (err) {
+                params.log?.warn({ err, threadId: String(thread?.id ?? '') }, 'discord:thread failed to join (threadCreate)');
+            }
+        });
+    }
+    client.on('guildCreate', async (guild) => {
+        await setBotNickname(guild, params.botDisplayName, params.log);
+    });
+    await client.login(params.token);
+    // Wait for cache to be ready before resolving the status channel.
+    await new Promise((resolve) => {
+        if (client.isReady()) {
+            resolve();
+        }
+        else {
+            client.once('ready', () => resolve());
+        }
+    });
+    // Ensure "System" category scaffold (status/crons/tasks) in a single target guild.
+    let system = null;
+    try {
+        const guild = selectBootstrapGuild(client, params.guildId, params.log);
+        if (guild) {
+            system = await ensureSystemScaffold({ guild, ensureTasks: Boolean(params.bootstrapEnsureTasksForum), botDisplayName: params.botDisplayName, existingCronsId: params.existingCronsId, existingTasksId: params.existingTasksId }, params.log);
+        }
+    }
+    catch (err) {
+        params.log?.warn({ err }, 'system-bootstrap: failed; continuing without scaffold');
+        system = null;
+    }
+    // Set bot nickname in all guilds.
+    for (const guild of client.guilds.cache.values()) {
+        await setBotNickname(guild, params.botDisplayName, params.log);
+    }
+    // Set bot presence (status + activity) on startup.
+    if (params.botStatus || params.botActivity) {
+        try {
+            const presenceData = {};
+            if (params.botStatus) {
+                presenceData.status = params.botStatus;
+            }
+            if (params.botActivity) {
+                const typeName = params.botActivityType ?? 'Playing';
+                const typeNum = ACTIVITY_TYPE_MAP[typeName] ?? ActivityType.Playing;
+                if (typeName === 'Custom') {
+                    presenceData.activities = [{ name: 'Custom Status', type: ActivityType.Custom, state: params.botActivity }];
+                }
+                else {
+                    presenceData.activities = [{ name: params.botActivity, type: typeNum }];
+                }
+            }
+            client.user.setPresence(presenceData);
+            params.log?.info({ status: params.botStatus, activity: params.botActivity, activityType: params.botActivityType }, 'discord:presence set');
+        }
+        catch (err) {
+            params.log?.warn({ err }, 'discord:presence failed to set');
+        }
+    }
+    // Set bot avatar on startup (rate-limited — applied once).
+    if (params.botAvatar) {
+        try {
+            if (params.botAvatar.startsWith('http://') || params.botAvatar.startsWith('https://')) {
+                await client.user.setAvatar(params.botAvatar);
+            }
+            else {
+                const buf = await fs.readFile(params.botAvatar);
+                await client.user.setAvatar(buf);
+            }
+            params.log?.info({ avatar: params.botAvatar }, 'discord:avatar set');
+        }
+        catch (err) {
+            params.log?.warn({ err, avatar: params.botAvatar }, 'discord:avatar failed to set');
+        }
+    }
+    if (params.statusChannel) {
+        statusRef.current = resolveStatusChannel(client, params.statusChannel, { botDisplayName: params.botDisplayName, log: params.log });
+        if (!statusRef.current) {
+            params.log?.error({ statusChannel: params.statusChannel }, 'status-channel: channel not found, status posting disabled');
+        }
+    }
+    else if (system?.statusChannelId) {
+        statusRef.current = await resolveStatusChannelById(client, system.statusChannelId, { botDisplayName: params.botDisplayName, log: params.log });
+        if (!statusRef.current) {
+            params.log?.error({ statusChannelId: system.statusChannelId }, 'status-channel: bootstrapped channel not found, status posting disabled');
+        }
+    }
+    return { client, status: statusRef.current, system };
+}