discoclaw 0.1.0

package/dist/discord/summarizer.test.js

@@ -0,0 +1,245 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { loadSummary, saveSummary, generateSummary } from './summarizer.js';
+async function makeTmpDir() {
+    return fs.mkdtemp(path.join(os.tmpdir(), 'summarizer-test-'));
+}
+describe('loadSummary', () => {
+    it('returns null for missing file', async () => {
+        const dir = await makeTmpDir();
+        const result = await loadSummary(dir, 'nonexistent-session');
+        expect(result).toBeNull();
+    });
+    it('parses valid JSON file', async () => {
+        const dir = await makeTmpDir();
+        const data = { summary: 'test summary', updatedAt: 1000 };
+        await fs.writeFile(path.join(dir, 'test-session.json'), JSON.stringify(data), 'utf8');
+        const result = await loadSummary(dir, 'test-session');
+        expect(result).toEqual(data);
+    });
+    it('returns null on malformed JSON', async () => {
+        const dir = await makeTmpDir();
+        await fs.writeFile(path.join(dir, 'bad.json'), '{not json!!!', 'utf8');
+        const result = await loadSummary(dir, 'bad');
+        expect(result).toBeNull();
+    });
+    it('returns null when JSON lacks summary field', async () => {
+        const dir = await makeTmpDir();
+        await fs.writeFile(path.join(dir, 'no-summary.json'), '{"updatedAt":1}', 'utf8');
+        const result = await loadSummary(dir, 'no-summary');
+        expect(result).toBeNull();
+    });
+    it('returns turnsSinceUpdate when present in JSON', async () => {
+        const dir = await makeTmpDir();
+        const data = { summary: 'ctx', updatedAt: 1, turnsSinceUpdate: 3 };
+        await fs.writeFile(path.join(dir, 'with-turns.json'), JSON.stringify(data), 'utf8');
+        const result = await loadSummary(dir, 'with-turns');
+        expect(result).toEqual(data);
+        expect(result.turnsSinceUpdate).toBe(3);
+    });
+    it('loads old files without turnsSinceUpdate (backward compat)', async () => {
+        const dir = await makeTmpDir();
+        await fs.writeFile(path.join(dir, 'old-format.json'), JSON.stringify({ summary: 'old', updatedAt: 100 }), 'utf8');
+        const result = await loadSummary(dir, 'old-format');
+        expect(result).toEqual({ summary: 'old', updatedAt: 100 });
+        expect(result.turnsSinceUpdate).toBeUndefined();
+    });
+});
+describe('saveSummary', () => {
+    it('creates file with correct content', async () => {
+        const dir = await makeTmpDir();
+        const data = { summary: 'saved summary', updatedAt: 2000 };
+        await saveSummary(dir, 'save-test', data);
+        const raw = await fs.readFile(path.join(dir, 'save-test.json'), 'utf8');
+        expect(JSON.parse(raw)).toEqual(data);
+    });
+    it('overwrites existing file', async () => {
+        const dir = await makeTmpDir();
+        await saveSummary(dir, 'overwrite', { summary: 'old', updatedAt: 1 });
+        await saveSummary(dir, 'overwrite', { summary: 'new', updatedAt: 2 });
+        const raw = await fs.readFile(path.join(dir, 'overwrite.json'), 'utf8');
+        expect(JSON.parse(raw).summary).toBe('new');
+    });
+    it('persists turnsSinceUpdate field', async () => {
+        const dir = await makeTmpDir();
+        await saveSummary(dir, 'turns-persist', { summary: 's', updatedAt: 1, turnsSinceUpdate: 0 });
+        const raw = await fs.readFile(path.join(dir, 'turns-persist.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        expect(parsed.turnsSinceUpdate).toBe(0);
+    });
+    it('creates parent directory if missing', async () => {
+        const dir = await makeTmpDir();
+        const nested = path.join(dir, 'a', 'b', 'c');
+        await saveSummary(nested, 'nested', { summary: 'deep', updatedAt: 3 });
+        const raw = await fs.readFile(path.join(nested, 'nested.json'), 'utf8');
+        expect(JSON.parse(raw).summary).toBe('deep');
+    });
+});
+describe('generateSummary', () => {
+    const baseOpts = {
+        previousSummary: null,
+        recentExchange: '[User]: hello\n[Bot]: hi there',
+        model: 'haiku',
+        cwd: '/tmp',
+        maxChars: 2000,
+        timeoutMs: 30_000,
+    };
+    it('collects text_final into summary string', async () => {
+        const runtime = {
+            invoke: vi.fn(async function* () {
+                yield { type: 'text_delta', text: 'partial ' };
+                yield { type: 'text_final', text: 'User greeted the bot.' };
+            }),
+        };
+        const result = await generateSummary(runtime, baseOpts);
+        expect(result).toBe('User greeted the bot.');
+    });
+    it('collects text_delta when no text_final', async () => {
+        const runtime = {
+            invoke: vi.fn(async function* () {
+                yield { type: 'text_delta', text: 'User ' };
+                yield { type: 'text_delta', text: 'greeted the bot.' };
+            }),
+        };
+        const result = await generateSummary(runtime, baseOpts);
+        expect(result).toBe('User greeted the bot.');
+    });
+    it('returns previous summary on runtime error event', async () => {
+        const runtime = {
+            invoke: vi.fn(async function* () {
+                yield { type: 'error', message: 'timeout' };
+            }),
+        };
+        const result = await generateSummary(runtime, {
+            ...baseOpts,
+            previousSummary: 'existing summary',
+        });
+        expect(result).toBe('existing summary');
+    });
+    it('returns empty string on error when no previous summary', async () => {
+        const runtime = {
+            invoke: vi.fn(async function* () {
+                yield { type: 'error', message: 'timeout' };
+            }),
+        };
+        const result = await generateSummary(runtime, baseOpts);
+        expect(result).toBe('');
+    });
+    it('returns previous summary when runtime throws', async () => {
+        const runtime = {
+            invoke: vi.fn(async function* () {
+                throw new Error('network failure');
+            }),
+        };
+        const result = await generateSummary(runtime, {
+            ...baseOpts,
+            previousSummary: 'kept summary',
+        });
+        expect(result).toBe('kept summary');
+    });
+    it('passes correct prompt with previous summary', async () => {
+        let seenPrompt = '';
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenPrompt = p.prompt;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, {
+            ...baseOpts,
+            previousSummary: 'old context',
+        });
+        expect(seenPrompt).toContain('Current summary:\nold context');
+        expect(seenPrompt).toContain('[User]: hello');
+    });
+    it('passes empty tools array to runtime', async () => {
+        let seenTools;
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenTools = p.tools;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, baseOpts);
+        expect(seenTools).toEqual([]);
+    });
+    it('includes task status context section in prompt when provided', async () => {
+        let seenPrompt = '';
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenPrompt = p.prompt;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, {
+            ...baseOpts,
+            taskStatusContext: 't-001: open, "Fix login bug"',
+        });
+        expect(seenPrompt).toContain('Current task statuses:');
+        expect(seenPrompt).toContain('t-001: open, "Fix login bug"');
+    });
+    it('includes recently-closed tasks in task status context prompt', async () => {
+        let seenPrompt = '';
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenPrompt = p.prompt;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, {
+            ...baseOpts,
+            taskStatusContext: 't-002: in_progress, "Refactor auth"\nRecently closed:\nt-001: closed, "Fix login bug"',
+        });
+        expect(seenPrompt).toContain('Recently closed:');
+        expect(seenPrompt).toContain('t-001: closed, "Fix login bug"');
+        expect(seenPrompt).toContain('t-002: in_progress, "Refactor auth"');
+    });
+    it('prompt rule mentions recently closed tasks when taskStatusContext is provided', async () => {
+        let seenPrompt = '';
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenPrompt = p.prompt;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, {
+            ...baseOpts,
+            taskStatusContext: 'No active tasks.\nRecently closed:\nt-003: closed, "Deploy pipeline"',
+        });
+        expect(seenPrompt).toContain('Recently closed');
+        expect(seenPrompt).toContain('stale open');
+    });
+    it('omits task status rule and section when taskStatusContext is not provided', async () => {
+        let seenPrompt = '';
+        const runtime = {
+            invoke: vi.fn(async function* (p) {
+                seenPrompt = p.prompt;
+                yield { type: 'text_final', text: 'ok' };
+            }),
+        };
+        await generateSummary(runtime, baseOpts);
+        expect(seenPrompt).not.toContain('Current task statuses:');
+        expect(seenPrompt).not.toContain('Recently closed');
+    });
+});
+describe('safe session key', () => {
+    it('uses filesystem-safe characters', async () => {
+        const dir = await makeTmpDir();
+        // Session key with special chars like discord:dm:<userId>
+        await saveSummary(dir, 'discord:dm:12345', { summary: 'dm summary', updatedAt: 1 });
+        // The file should exist with colons preserved (they're allowed by the regex)
+        const files = await fs.readdir(dir);
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('discord:dm:12345.json');
+        expect(files[0]).toMatch(/^[a-zA-Z0-9:_.-]+$/);
+    });
+    it('replaces unsafe characters with hyphens', async () => {
+        const dir = await makeTmpDir();
+        await saveSummary(dir, 'has spaces/and/slashes!', { summary: 'x', updatedAt: 1 });
+        const files = await fs.readdir(dir);
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('has-spaces-and-slashes-.json');
+    });
+});

package/dist/discord/system-bootstrap.js

@@ -0,0 +1,396 @@
+import fs from 'node:fs/promises';
+import { ChannelType } from 'discord.js';
+import { stripCountSuffix } from './forum-count-sync.js';
+function norm(s) {
+    return (s ?? '').trim().toLowerCase();
+}
+function isCountSuffixOnly(currentName, canonicalName) {
+    return norm(currentName) !== norm(canonicalName) &&
+        norm(stripCountSuffix(currentName)) === norm(canonicalName);
+}
+export function isSnowflake(s) {
+    return /^\d{8,}$/.test((s ?? '').trim());
+}
+export function selectBootstrapGuild(client, guildIdFromEnv, log) {
+    const gid = (guildIdFromEnv ?? '').trim();
+    if (gid) {
+        const g = client.guilds.cache.get(gid) ?? null;
+        if (!g)
+            log?.warn({ guildId: gid }, 'system-bootstrap: guild not found; skipping');
+        return g;
+    }
+    const guilds = [...client.guilds.cache.values()];
+    if (guilds.length === 1)
+        return guilds[0] ?? null;
+    log?.warn({ guildCount: guilds.length }, 'system-bootstrap: multiple guilds (or none) and DISCORD_GUILD_ID not set; skipping');
+    return null;
+}
+async function tryFetchChannel(guild, id) {
+    const trimmed = (id ?? '').trim();
+    if (!trimmed || !isSnowflake(trimmed))
+        return null;
+    try {
+        const fetched = await guild.channels.fetch(trimmed);
+        return fetched ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function findByNameAndType(guild, name, type) {
+    const want = norm(name);
+    // Pass 1: exact name match.
+    const exact = guild.channels.cache.find((c) => c.type === type && norm(c.name) === want);
+    if (exact)
+        return exact;
+    // Pass 2: match after stripping count suffix (defense-in-depth).
+    const stripped = guild.channels.cache.find((c) => c.type === type && norm(stripCountSuffix(c.name)) === want);
+    return stripped ?? null;
+}
+function findAnyByName(guild, name) {
+    const want = norm(name);
+    const out = [];
+    for (const c of guild.channels.cache.values()) {
+        if (norm(c?.name ?? '') === want)
+            out.push(c);
+    }
+    return out;
+}
+async function moveUnderCategory(ch, parentCategoryId, log) {
+    const current = String(ch?.parentId ?? '');
+    if (current === parentCategoryId)
+        return false;
+    try {
+        if (typeof ch.setParent === 'function') {
+            await ch.setParent(parentCategoryId);
+        }
+        else if (typeof ch.edit === 'function') {
+            await ch.edit({ parent: parentCategoryId });
+        }
+        else {
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        log?.warn({ err, channelId: ch?.id, name: ch?.name }, 'system-bootstrap: failed to move channel');
+        return false;
+    }
+}
+export async function ensureSystemCategory(guild, log) {
+    const existing = findByNameAndType(guild, 'System', ChannelType.GuildCategory);
+    if (existing)
+        return existing;
+    try {
+        const created = await guild.channels.create({
+            name: 'System',
+            type: ChannelType.GuildCategory,
+        });
+        return created;
+    }
+    catch (err) {
+        log?.warn({ err }, 'system-bootstrap: failed to create System category');
+        return null;
+    }
+}
+async function ensureChild(guild, parentCategoryId, spec, log, existingId) {
+    // ID-first lookup when configured.
+    if (existingId && isSnowflake(existingId)) {
+        const byId = guild.channels.cache.get(existingId) ?? await tryFetchChannel(guild, existingId);
+        if (byId) {
+            if (byId.type !== spec.type) {
+                log?.error({ existingId, name: spec.name, expected: ChannelType[spec.type], actual: ChannelType[byId.type] }, 'system-bootstrap: configured ID has wrong channel type');
+                return { created: false, moved: false }; // fail closed — no ID returned
+            }
+            const moved = await moveUnderCategory(byId, parentCategoryId, log);
+            // Reconcile name if it differs from canonical (e.g. count-sync stacking).
+            const currentName = String(byId.name ?? '');
+            if (norm(currentName) !== norm(spec.name)) {
+                if (isCountSuffixOnly(currentName, spec.name)) {
+                    log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: skipping name reconciliation (count suffix only)');
+                }
+                else {
+                    try {
+                        await byId.edit({ name: spec.name });
+                        log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: reconciled name');
+                    }
+                    catch (err) {
+                        log?.warn({ err, name: spec.name, was: currentName }, 'system-bootstrap: failed to reconcile name');
+                    }
+                }
+            }
+            // Reconcile topic if it differs from expected.
+            if (spec.topic && byId.topic !== spec.topic) {
+                try {
+                    await byId.edit({ topic: spec.topic });
+                    log?.info({ name: spec.name }, 'system-bootstrap: reconciled topic');
+                }
+                catch (err) {
+                    log?.warn({ err, name: spec.name }, 'system-bootstrap: failed to reconcile topic');
+                }
+            }
+            return { id: String(byId.id ?? ''), created: false, moved };
+        }
+        // ID not found — stale config or deleted channel. Fall through to name-based lookup / creation.
+        log?.warn({ existingId, name: spec.name }, 'system-bootstrap: configured channel ID not found in guild, falling back to name lookup');
+    }
+    const exact = findByNameAndType(guild, spec.name, spec.type);
+    if (exact) {
+        const moved = await moveUnderCategory(exact, parentCategoryId, log);
+        // Reconcile name if it differs from canonical (e.g. found via stripped count suffix).
+        const currentName = String(exact.name ?? '');
+        if (norm(currentName) !== norm(spec.name)) {
+            if (isCountSuffixOnly(currentName, spec.name)) {
+                log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: skipping name reconciliation (count suffix only)');
+            }
+            else {
+                try {
+                    await exact.edit({ name: spec.name });
+                    log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: reconciled name');
+                }
+                catch (err) {
+                    log?.warn({ err, name: spec.name, was: currentName }, 'system-bootstrap: failed to reconcile name');
+                }
+            }
+        }
+        // Reconcile topic if it differs from expected.
+        if (spec.topic && exact.topic !== spec.topic) {
+            try {
+                await exact.edit({ topic: spec.topic });
+                log?.info({ name: spec.name }, 'system-bootstrap: reconciled topic');
+            }
+            catch (err) {
+                log?.warn({ err, name: spec.name }, 'system-bootstrap: failed to reconcile topic');
+            }
+        }
+        return { id: String(exact.id ?? ''), created: false, moved };
+    }
+    // Legacy name lookup — find by old names and reconcile to canonical.
+    if (spec.legacyNames) {
+        for (const legacyName of spec.legacyNames) {
+            const legacy = findByNameAndType(guild, legacyName, spec.type);
+            if (legacy) {
+                const moved = await moveUnderCategory(legacy, parentCategoryId, log);
+                const currentName = String(legacy.name ?? '');
+                if (norm(currentName) !== norm(spec.name)) {
+                    if (isCountSuffixOnly(currentName, spec.name)) {
+                        log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: skipping name reconciliation (count suffix only)');
+                    }
+                    else {
+                        try {
+                            await legacy.edit({ name: spec.name });
+                            log?.info({ name: spec.name, was: currentName }, 'system-bootstrap: reconciled name');
+                        }
+                        catch (err) {
+                            log?.warn({ err, name: spec.name, was: currentName }, 'system-bootstrap: failed to reconcile name');
+                        }
+                    }
+                }
+                if (spec.topic && legacy.topic !== spec.topic) {
+                    try {
+                        await legacy.edit({ topic: spec.topic });
+                        log?.info({ name: spec.name }, 'system-bootstrap: reconciled topic');
+                    }
+                    catch (err) {
+                        log?.warn({ err, name: spec.name }, 'system-bootstrap: failed to reconcile topic');
+                    }
+                }
+                return { id: String(legacy.id ?? ''), created: false, moved };
+            }
+        }
+    }
+    const nameClash = findAnyByName(guild, spec.name).filter((c) => c.type !== spec.type);
+    if (nameClash.length > 0) {
+        log?.warn({ name: spec.name, wantType: ChannelType[spec.type], foundTypes: nameClash.map((c) => ChannelType[c.type] ?? String(c.type)) }, 'system-bootstrap: name exists with different type; skipping creation');
+        return { created: false, moved: false };
+    }
+    try {
+        const created = await guild.channels.create({
+            name: spec.name,
+            type: spec.type,
+            parent: parentCategoryId,
+            topic: spec.topic,
+        });
+        return { id: String(created?.id ?? ''), created: true, moved: false };
+    }
+    catch (err) {
+        log?.warn({ err, name: spec.name, type: ChannelType[spec.type] }, 'system-bootstrap: failed to create channel');
+        return { created: false, moved: false };
+    }
+}
+export async function ensureSystemScaffold(params, log) {
+    const { guild, ensureTasks } = params;
+    const system = await ensureSystemCategory(guild, log);
+    if (!system)
+        return null;
+    const created = [];
+    const moved = [];
+    const status = await ensureChild(guild, system.id, { name: 'status', type: ChannelType.GuildText, topic: `${params.botDisplayName ?? 'Discoclaw'} status (online/offline/errors).` }, log);
+    if (status.created)
+        created.push('status');
+    if (status.moved)
+        moved.push('status');
+    const crons = await ensureChild(guild, system.id, { name: 'automations', type: ChannelType.GuildForum, topic: 'Automations are managed by the bot. Use bot commands to create scheduled tasks. Do not create threads manually — they will be archived.', legacyNames: ['agents'] }, log, params.existingCronsId);
+    if (crons.created)
+        created.push('automations');
+    if (crons.moved)
+        moved.push('automations');
+    let tasks = null;
+    if (ensureTasks) {
+        tasks = await ensureChild(guild, system.id, { name: 'tasks', type: ChannelType.GuildForum, topic: 'Tasks are managed by the bot. Use task commands or actions to create tasks. Do not create threads manually — they will be archived.' }, log, params.existingTasksId);
+        if (tasks.created)
+            created.push('tasks');
+        if (tasks.moved)
+            moved.push('tasks');
+        // Bootstrap status tags on the tasks forum.
+        if (tasks.id && params.tasksTagMapPath) {
+            try {
+                await ensureForumTags(guild, tasks.id, params.tasksTagMapPath, { log });
+            }
+            catch (err) {
+                log?.warn({ err, forumId: tasks.id }, 'system-bootstrap: tasks forum tag bootstrap failed');
+            }
+        }
+    }
+    if (created.length > 0 || moved.length > 0) {
+        log?.info({
+            guildId: guild.id,
+            systemCategoryId: system.id,
+            created,
+            moved,
+        }, 'system-bootstrap:ensured');
+    }
+    const result = {
+        guildId: guild.id,
+        systemCategoryId: system.id,
+    };
+    if (status.id)
+        result.statusChannelId = status.id;
+    if (crons.id)
+        result.cronsForumId = crons.id;
+    if (tasks?.id)
+        result.tasksForumId = tasks.id;
+    return result;
+}
+const STATUS_PRIORITY = ['open', 'in_progress', 'blocked', 'closed'];
+const STATUS_TAG_NAMES = new Set(STATUS_PRIORITY);
+/**
+ * Ensure a forum channel has tags matching a tag-map file.
+ * Creates missing tags on the Discord forum and writes their IDs back to the
+ * **dataDir** tag-map file (never mutates repo files).
+ *
+ * Returns the number of tags created.
+ */
+export async function ensureForumTags(guild, forumId, tagMapPath, options) {
+    const log = options?.log;
+    const seedPath = options?.seedPath;
+    let tagMap;
+    try {
+        const raw = await fs.readFile(tagMapPath, 'utf8');
+        tagMap = JSON.parse(raw);
+    }
+    catch {
+        return 0;
+    }
+    // Key-merge: if a seed file is provided, merge any new keys from the seed
+    // into the data-dir tag map (existing keys are preserved).
+    if (seedPath) {
+        try {
+            const seedRaw = await fs.readFile(seedPath, 'utf8');
+            const seedMap = JSON.parse(seedRaw);
+            let merged = 0;
+            for (const key of Object.keys(seedMap)) {
+                if (!(key in tagMap)) {
+                    tagMap[key] = '';
+                    merged++;
+                }
+            }
+            if (merged > 0) {
+                log?.info({ seedPath, merged }, 'system-bootstrap: merged new keys from seed tag map');
+            }
+        }
+        catch {
+            // Seed file missing or invalid — continue with existing tag map.
+        }
+    }
+    const forum = guild.channels.cache.get(forumId);
+    if (!forum || forum.type !== ChannelType.GuildForum)
+        return 0;
+    const forumChannel = forum;
+    // Build lookup structures for existing forum tags.
+    const existingTags = forumChannel.availableTags ?? [];
+    const existingById = new Map(existingTags.map((t) => [t.id, t]));
+    const existingNames = new Set(existingTags.map((t) => t.name.toLowerCase()));
+    // Stale-ID reconciliation: validate entries that have non-empty IDs.
+    // If the ID doesn't exist on the forum, or maps to a different tag name, clear it.
+    let staleCleared = 0;
+    for (const [name, id] of Object.entries(tagMap)) {
+        if (!id)
+            continue;
+        const forumTag = existingById.get(id);
+        if (!forumTag || forumTag.name.toLowerCase() !== name.toLowerCase()) {
+            log?.warn({ tagName: name, staleId: id, forumTagName: forumTag?.name }, 'system-bootstrap: clearing stale/swapped tag ID');
+            tagMap[name] = '';
+            staleCleared++;
+        }
+    }
+    // Identify tags that need to be created.
+    const toCreate = [];
+    let backfilled = 0;
+    for (const [name, id] of Object.entries(tagMap)) {
+        if (id)
+            continue; // Already has a validated Discord tag ID.
+        if (existingNames.has(name.toLowerCase())) {
+            // Tag exists on the forum but not in our map — backfill the ID.
+            const existing = existingTags.find((t) => t.name.toLowerCase() === name.toLowerCase());
+            if (existing && existing.id) {
+                tagMap[name] = existing.id;
+                backfilled++;
+            }
+            continue;
+        }
+        toCreate.push(name);
+    }
+    if (toCreate.length === 0 && backfilled === 0 && staleCleared === 0) {
+        // Nothing to create, nothing changed.
+        return 0;
+    }
+    // Discord forums allow max 20 tags.
+    const maxNew = Math.max(0, 20 - existingTags.length);
+    // Status-first prioritization: ensure status tags get slots before content tags,
+    // in deterministic lifecycle-priority order (open > in_progress > blocked > closed).
+    const statusFirst = STATUS_PRIORITY.filter((n) => toCreate.includes(n));
+    const contentRest = toCreate.filter((n) => !STATUS_TAG_NAMES.has(n));
+    const prioritized = [...statusFirst, ...contentRest];
+    const creating = prioritized.slice(0, maxNew);
+    if (creating.length > 0) {
+        try {
+            const newTags = [
+                ...existingTags.map((t) => ({ id: t.id, name: t.name, moderated: t.moderated, emoji: t.emoji })),
+                ...creating.map((name) => ({ name })),
+            ];
+            await forumChannel.edit({ availableTags: newTags });
+            // Re-fetch to get the created tag IDs.
+            const updated = guild.channels.cache.get(forumId);
+            const updatedTags = updated?.availableTags ?? [];
+            for (const name of creating) {
+                const created = updatedTags.find((t) => t.name.toLowerCase() === name.toLowerCase());
+                if (created)
+                    tagMap[name] = created.id;
+            }
+        }
+        catch (err) {
+            log?.warn({ err, forumId, tagCount: creating.length }, 'system-bootstrap: failed to create forum tags');
+            return 0;
+        }
+    }
+    // Write the updated tag map back to the dataDir file.
+    try {
+        await fs.writeFile(tagMapPath, JSON.stringify(tagMap, null, 2) + '\n', 'utf8');
+    }
+    catch (err) {
+        log?.warn({ err, tagMapPath }, 'system-bootstrap: failed to write tag map');
+    }
+    log?.info({ forumId, tagsCreated: creating.length }, 'system-bootstrap: forum tags ensured');
+    return creating.length;
+}