discoclaw 0.1.0

package/dist/discord/shortterm-memory.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PermissionFlagsBits } from 'discord.js';
+import { KeyedQueue } from '../group-queue.js';
+export const CURRENT_VERSION = 1;
+export function emptyStore() {
+    return { version: CURRENT_VERSION, entries: [] };
+}
+function migrateStore(store) {
+    // Migration blocks run first, then the unknown-version guard.
+    // Future migrations follow the run-stats.ts pattern:
+    //   if ((store as any).version === 1) { /* transform fields */; store.version = 2; }
+    if (store.version !== CURRENT_VERSION) {
+        // Unrecognized (future) version — caller will create a fresh store.
+        return null;
+    }
+    return store;
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+function safeGuildUserId(guildUserId) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(guildUserId)) {
+        throw new Error(`Invalid guildUserId for short-term memory path: ${guildUserId}`);
+    }
+    return guildUserId;
+}
+export async function loadShortTermMemory(dir, guildUserId) {
+    const filePath = path.join(dir, `${safeGuildUserId(guildUserId)}.json`);
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            'version' in parsed &&
+            'entries' in parsed &&
+            Array.isArray(parsed.entries)) {
+            return migrateStore(parsed) ?? emptyStore();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveShortTermMemory(dir, guildUserId, store) {
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeGuildUserId(guildUserId)}.json`);
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    await fs.writeFile(tmp, JSON.stringify(store, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, filePath);
+}
+// ---------------------------------------------------------------------------
+// Write queue (per guild-user key)
+// ---------------------------------------------------------------------------
+const shortTermWriteQueue = new KeyedQueue();
+// ---------------------------------------------------------------------------
+// Core logic
+// ---------------------------------------------------------------------------
+export async function appendEntry(dir, guildUserId, entry, opts) {
+    await shortTermWriteQueue.run(guildUserId, async () => {
+        const store = (await loadShortTermMemory(dir, guildUserId)) ?? emptyStore();
+        store.entries.push(entry);
+        // Prune: remove expired entries and enforce cap.
+        const now = Date.now();
+        store.entries = store.entries
+            .filter((e) => now - e.timestamp < opts.maxAgeMs)
+            .slice(-opts.maxEntries);
+        await saveShortTermMemory(dir, guildUserId, store);
+    });
+}
+export function buildExcerptSummary(userMsg, botResponse, maxLen = 200) {
+    const userPart = userMsg.slice(0, Math.floor(maxLen / 2)).trim();
+    const botPart = botResponse.slice(0, Math.floor(maxLen / 2)).trim();
+    return `User: ${userPart} | Bot: ${botPart}`;
+}
+export function selectEntriesForInjection(store, maxChars, maxAgeMs) {
+    const now = Date.now();
+    const recent = store.entries
+        .filter((e) => now - e.timestamp < maxAgeMs)
+        .sort((a, b) => b.timestamp - a.timestamp);
+    const selected = [];
+    let chars = 0;
+    for (const entry of recent) {
+        const line = formatEntryLine(entry);
+        const sep = selected.length > 0 ? 1 : 0;
+        if (chars + sep + line.length > maxChars)
+            continue;
+        selected.push(entry);
+        chars += sep + line.length;
+    }
+    return selected;
+}
+function formatEntryLine(entry) {
+    const ago = formatTimeAgo(Date.now() - entry.timestamp);
+    return `- ${ago} in #${entry.channelName}: ${entry.summary}`;
+}
+function formatTimeAgo(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours} hr${hours > 1 ? 's' : ''} ago`;
+}
+export function formatShortTermSection(entries) {
+    return entries.map(formatEntryLine).join('\n');
+}
+// ---------------------------------------------------------------------------
+// Channel privacy check
+// ---------------------------------------------------------------------------
+export function isChannelPublic(channel, guild) {
+    // DMs have no guild — always skip.
+    if (!guild)
+        return false;
+    // Category / voice channels — skip.
+    const type = channel?.type;
+    if (type === undefined || type === null)
+        return false;
+    // Check if it's a thread (public or private) or forum post.
+    const isThread = typeof channel.isThread === 'function' ? channel.isThread() : false;
+    if (isThread) {
+        // Inherit parent channel visibility.
+        const parent = channel.parent;
+        if (!parent)
+            return false;
+        return checkEveryoneViewChannel(parent, guild);
+    }
+    return checkEveryoneViewChannel(channel, guild);
+}
+function checkEveryoneViewChannel(channel, guild) {
+    try {
+        const everyone = guild.roles.everyone;
+        if (!everyone)
+            return false;
+        const perms = channel.permissionsFor?.(everyone);
+        if (!perms)
+            return false;
+        return perms.has(PermissionFlagsBits.ViewChannel);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Prompt section builder
+// ---------------------------------------------------------------------------
+export async function buildShortTermMemorySection(opts) {
+    if (!opts.enabled)
+        return '';
+    if (!opts.guildId)
+        return '';
+    try {
+        const guildUserId = `${opts.guildId}-${opts.userId}`;
+        const store = await loadShortTermMemory(opts.shortTermDataDir, guildUserId);
+        if (!store)
+            return '';
+        const entries = selectEntriesForInjection(store, opts.maxChars, opts.maxAgeMs);
+        if (entries.length === 0)
+            return '';
+        return formatShortTermSection(entries);
+    }
+    catch (err) {
+        opts.log?.warn({ err, userId: opts.userId }, 'short-term memory load failed');
+        return '';
+    }
+}

package/dist/discord/shortterm-memory.test.js

@@ -0,0 +1,345 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { PermissionsBitField, PermissionFlagsBits } from 'discord.js';
+import { loadShortTermMemory, saveShortTermMemory, appendEntry, buildExcerptSummary, selectEntriesForInjection, isChannelPublic, formatShortTermSection, buildShortTermMemorySection, CURRENT_VERSION, } from './shortterm-memory.js';
+async function makeTmpDir() {
+    return fs.mkdtemp(path.join(os.tmpdir(), 'shortterm-memory-test-'));
+}
+function makeEntry(overrides = {}) {
+    return {
+        timestamp: Date.now(),
+        sessionKey: 'discord:guild:123:456',
+        channelName: 'general',
+        summary: 'User asked about APIs | Bot suggested REST',
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+describe('loadShortTermMemory', () => {
+    it('returns null for missing file', async () => {
+        const dir = await makeTmpDir();
+        expect(await loadShortTermMemory(dir, 'nonexistent')).toBeNull();
+    });
+    it('parses valid store', async () => {
+        const dir = await makeTmpDir();
+        const store = { version: 1, entries: [] };
+        await fs.writeFile(path.join(dir, 'guild1-user1.json'), JSON.stringify(store), 'utf8');
+        expect(await loadShortTermMemory(dir, 'guild1-user1')).toEqual(store);
+    });
+    it('returns null on malformed JSON', async () => {
+        const dir = await makeTmpDir();
+        await fs.writeFile(path.join(dir, 'bad.json'), '{nope', 'utf8');
+        expect(await loadShortTermMemory(dir, 'bad')).toBeNull();
+    });
+    it('rejects path traversal', async () => {
+        const dir = await makeTmpDir();
+        await expect(loadShortTermMemory(dir, '../evil')).rejects.toThrow(/Invalid guildUserId/);
+    });
+    it('returns store unchanged for version-1 store (migration no-op)', async () => {
+        const dir = await makeTmpDir();
+        const store = { version: 1, entries: [] };
+        await fs.writeFile(path.join(dir, 'guild1-user1.json'), JSON.stringify(store), 'utf8');
+        expect(await loadShortTermMemory(dir, 'guild1-user1')).toEqual(store);
+    });
+    it('returns empty store for unsupported version', async () => {
+        const dir = await makeTmpDir();
+        const store = { version: 99, entries: [] };
+        await fs.writeFile(path.join(dir, 'guild1-user1.json'), JSON.stringify(store), 'utf8');
+        expect(await loadShortTermMemory(dir, 'guild1-user1')).toMatchObject({ version: CURRENT_VERSION, entries: [] });
+    });
+    it('returns null for store with no version field', async () => {
+        const dir = await makeTmpDir();
+        const store = { entries: [] };
+        await fs.writeFile(path.join(dir, 'guild1-user1.json'), JSON.stringify(store), 'utf8');
+        expect(await loadShortTermMemory(dir, 'guild1-user1')).toBeNull();
+    });
+});
+describe('saveShortTermMemory — path traversal', () => {
+    it('rejects path traversal in guildUserId', async () => {
+        const dir = await makeTmpDir();
+        const store = { version: 1, entries: [] };
+        await expect(saveShortTermMemory(dir, '../evil', store)).rejects.toThrow(/Invalid guildUserId/);
+    });
+});
+describe('saveShortTermMemory', () => {
+    it('creates file and parent directory', async () => {
+        const dir = await makeTmpDir();
+        const nested = path.join(dir, 'sub');
+        const store = { version: 1, entries: [makeEntry()] };
+        await saveShortTermMemory(nested, 'guild1-user1', store);
+        const raw = await fs.readFile(path.join(nested, 'guild1-user1.json'), 'utf8');
+        expect(JSON.parse(raw)).toEqual(store);
+    });
+});
+// ---------------------------------------------------------------------------
+// appendEntry
+// ---------------------------------------------------------------------------
+describe('appendEntry', () => {
+    it('appends and prunes expired entries', async () => {
+        const dir = await makeTmpDir();
+        const guildUserId = 'g1-u1';
+        const maxAgeMs = 60_000; // 1 minute
+        // Add an old entry.
+        const old = {
+            version: 1,
+            entries: [makeEntry({ timestamp: Date.now() - 120_000, channelName: 'old' })],
+        };
+        await saveShortTermMemory(dir, guildUserId, old);
+        // Append a new entry.
+        await appendEntry(dir, guildUserId, makeEntry({ channelName: 'new' }), { maxEntries: 20, maxAgeMs });
+        const store = await loadShortTermMemory(dir, guildUserId);
+        expect(store.entries).toHaveLength(1);
+        expect(store.entries[0].channelName).toBe('new');
+    });
+    it('persists channelId when provided', async () => {
+        const dir = await makeTmpDir();
+        const guildUserId = 'g1-u1';
+        await appendEntry(dir, guildUserId, makeEntry({ channelId: 'ch123' }), {
+            maxEntries: 20,
+            maxAgeMs: 3600_000,
+        });
+        const store = await loadShortTermMemory(dir, guildUserId);
+        expect(store.entries[0].channelId).toBe('ch123');
+    });
+    it('enforces maxEntries cap', async () => {
+        const dir = await makeTmpDir();
+        const guildUserId = 'g1-u1';
+        for (let i = 0; i < 5; i++) {
+            await appendEntry(dir, guildUserId, makeEntry({ channelName: `ch${i}` }), {
+                maxEntries: 3,
+                maxAgeMs: 3600_000,
+            });
+        }
+        const store = await loadShortTermMemory(dir, guildUserId);
+        expect(store.entries).toHaveLength(3);
+        // Should keep the 3 most recent (ch2, ch3, ch4).
+        expect(store.entries[0].channelName).toBe('ch2');
+        expect(store.entries[2].channelName).toBe('ch4');
+    });
+});
+// ---------------------------------------------------------------------------
+// buildExcerptSummary
+// ---------------------------------------------------------------------------
+describe('buildExcerptSummary', () => {
+    it('truncates long messages', () => {
+        const long = 'x'.repeat(500);
+        const result = buildExcerptSummary(long, long, 100);
+        expect(result.length).toBeLessThan(200);
+        expect(result).toContain('User:');
+        expect(result).toContain('Bot:');
+    });
+    it('handles short messages', () => {
+        const result = buildExcerptSummary('hi', 'hello', 200);
+        expect(result).toBe('User: hi | Bot: hello');
+    });
+    it('handles empty strings', () => {
+        const result = buildExcerptSummary('', '', 200);
+        expect(result).toBe('User:  | Bot: ');
+    });
+});
+// ---------------------------------------------------------------------------
+// selectEntriesForInjection
+// ---------------------------------------------------------------------------
+describe('selectEntriesForInjection', () => {
+    it('filters by age and respects maxChars', () => {
+        const now = Date.now();
+        const store = {
+            version: 1,
+            entries: [
+                makeEntry({ timestamp: now - 1000, channelName: 'recent' }),
+                makeEntry({ timestamp: now - 7200_000, channelName: 'expired' }), // 2 hrs old
+            ],
+        };
+        const entries = selectEntriesForInjection(store, 10000, 3600_000); // 1hr max age
+        expect(entries).toHaveLength(1);
+        expect(entries[0].channelName).toBe('recent');
+    });
+    it('returns empty with maxChars = 0', () => {
+        const store = {
+            version: 1,
+            entries: [makeEntry()],
+        };
+        expect(selectEntriesForInjection(store, 0, 3600_000)).toHaveLength(0);
+    });
+    it('returns empty for store with no entries', () => {
+        const store = { version: 1, entries: [] };
+        expect(selectEntriesForInjection(store, 10000, 3600_000)).toEqual([]);
+    });
+    it('sorts by recency (newest first)', () => {
+        const now = Date.now();
+        const store = {
+            version: 1,
+            entries: [
+                makeEntry({ timestamp: now - 5000, channelName: 'older' }),
+                makeEntry({ timestamp: now - 1000, channelName: 'newer' }),
+            ],
+        };
+        const entries = selectEntriesForInjection(store, 10000, 3600_000);
+        expect(entries[0].channelName).toBe('newer');
+        expect(entries[1].channelName).toBe('older');
+    });
+    it('skips oversized newest entry and includes smaller older entries that fit', () => {
+        const now = Date.now();
+        const store = {
+            version: 1,
+            entries: [
+                makeEntry({
+                    timestamp: now - 1000,
+                    channelName: 'newer',
+                    summary: 'x'.repeat(600),
+                }),
+                makeEntry({
+                    timestamp: now - 2000,
+                    channelName: 'older',
+                    summary: 'small summary',
+                }),
+            ],
+        };
+        const entries = selectEntriesForInjection(store, 120, 3600_000);
+        expect(entries).toHaveLength(1);
+        expect(entries[0].channelName).toBe('older');
+    });
+});
+// ---------------------------------------------------------------------------
+// formatShortTermSection
+// ---------------------------------------------------------------------------
+describe('formatShortTermSection', () => {
+    it('formats entries as bullet list', () => {
+        const entries = [
+            makeEntry({ timestamp: Date.now() - 900_000, channelName: 'general', summary: 'Talked about APIs' }),
+        ];
+        const result = formatShortTermSection(entries);
+        expect(result).toContain('#general');
+        expect(result).toContain('Talked about APIs');
+        expect(result).toMatch(/\d+ min ago/);
+    });
+});
+// ---------------------------------------------------------------------------
+// isChannelPublic
+// ---------------------------------------------------------------------------
+describe('isChannelPublic', () => {
+    function makeGuild(everyonePerms) {
+        const everyone = {
+            id: 'everyone-role-id',
+        };
+        return {
+            roles: { everyone },
+        };
+    }
+    function makeTextChannel(permsForEveryone, opts) {
+        return {
+            type: 0, // GuildText
+            isThread: () => opts?.isThread ?? false,
+            parent: opts?.parent ?? null,
+            permissionsFor: (role) => new PermissionsBitField(permsForEveryone),
+        };
+    }
+    it('returns true for public channel (@everyone has ViewChannel)', () => {
+        const guild = makeGuild(PermissionFlagsBits.ViewChannel);
+        const channel = makeTextChannel(PermissionFlagsBits.ViewChannel);
+        expect(isChannelPublic(channel, guild)).toBe(true);
+    });
+    it('returns false for private channel (@everyone lacks ViewChannel)', () => {
+        const guild = makeGuild(0n);
+        const channel = makeTextChannel(0n);
+        expect(isChannelPublic(channel, guild)).toBe(false);
+    });
+    it('returns false for DMs (no guild)', () => {
+        expect(isChannelPublic({}, null)).toBe(false);
+    });
+    it('returns true for thread in public parent', () => {
+        const guild = makeGuild(PermissionFlagsBits.ViewChannel);
+        const parent = makeTextChannel(PermissionFlagsBits.ViewChannel);
+        const thread = {
+            type: 11, // PublicThread
+            isThread: () => true,
+            parent,
+            permissionsFor: () => new PermissionsBitField(0n),
+        };
+        expect(isChannelPublic(thread, guild)).toBe(true);
+    });
+    it('returns false for thread in private parent', () => {
+        const guild = makeGuild(0n);
+        const parent = makeTextChannel(0n);
+        const thread = {
+            type: 11, // PublicThread
+            isThread: () => true,
+            parent,
+        };
+        expect(isChannelPublic(thread, guild)).toBe(false);
+    });
+    it('returns false for thread with no parent', () => {
+        const guild = makeGuild(0n);
+        const thread = {
+            type: 11,
+            isThread: () => true,
+            parent: null,
+        };
+        expect(isChannelPublic(thread, guild)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// buildShortTermMemorySection
+// ---------------------------------------------------------------------------
+describe('buildShortTermMemorySection', () => {
+    it('returns empty when disabled', async () => {
+        const result = await buildShortTermMemorySection({
+            enabled: false,
+            shortTermDataDir: '/tmp',
+            guildId: 'g1',
+            userId: 'u1',
+            maxChars: 1000,
+            maxAgeMs: 3600_000,
+        });
+        expect(result).toBe('');
+    });
+    it('returns empty when guildId is empty', async () => {
+        const result = await buildShortTermMemorySection({
+            enabled: true,
+            shortTermDataDir: '/tmp',
+            guildId: '',
+            userId: 'u1',
+            maxChars: 1000,
+            maxAgeMs: 3600_000,
+        });
+        expect(result).toBe('');
+    });
+    it('returns formatted section when data exists', async () => {
+        const dir = await makeTmpDir();
+        const store = {
+            version: 1,
+            entries: [makeEntry({ timestamp: Date.now() - 60_000, channelName: 'dev' })],
+        };
+        await saveShortTermMemory(dir, 'g1-u1', store);
+        const result = await buildShortTermMemorySection({
+            enabled: true,
+            shortTermDataDir: dir,
+            guildId: 'g1',
+            userId: 'u1',
+            maxChars: 1000,
+            maxAgeMs: 3600_000,
+        });
+        expect(result).toContain('#dev');
+    });
+    it('returns empty when no entries within maxAge', async () => {
+        const dir = await makeTmpDir();
+        const store = {
+            version: 1,
+            entries: [makeEntry({ timestamp: Date.now() - 7200_000 })], // 2 hrs old
+        };
+        await saveShortTermMemory(dir, 'g1-u1', store);
+        const result = await buildShortTermMemorySection({
+            enabled: true,
+            shortTermDataDir: dir,
+            guildId: 'g1',
+            userId: 'u1',
+            maxChars: 1000,
+            maxAgeMs: 3600_000, // 1 hour
+        });
+        expect(result).toBe('');
+    });
+});

package/dist/discord/shutdown-context.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const FILENAME = 'shutdown-context.json';
+const VALID_REASONS = new Set(['restart-command', 'deploy', 'code-fix', 'unknown']);
+const MAX_FIELD_LENGTH = 500;
+// ---------------------------------------------------------------------------
+// Write (shutdown side)
+// ---------------------------------------------------------------------------
+/**
+ * Write shutdown context atomically (tmp + rename).
+ * If `skipIfExists` is true, preserves any richer context already written
+ * (e.g., by !restart before the SIGTERM handler fires).
+ */
+export async function writeShutdownContext(dataDir, ctx, opts) {
+    const filePath = path.join(dataDir, FILENAME);
+    if (opts?.skipIfExists) {
+        try {
+            await fs.access(filePath);
+            return; // File already exists — don't overwrite.
+        }
+        catch {
+            // File doesn't exist — proceed with write.
+        }
+    }
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    await fs.writeFile(tmpPath, JSON.stringify(ctx) + '\n', 'utf-8');
+    await fs.rename(tmpPath, filePath);
+}
+// ---------------------------------------------------------------------------
+// Read + clear (startup side)
+// ---------------------------------------------------------------------------
+/**
+ * Read and delete the shutdown context file. Returns startup classification.
+ * Pass `firstBoot: true` when the data directory was freshly created (no prior run)
+ * to avoid a false "crash" warning on first-ever boot.
+ */
+export async function readAndClearShutdownContext(dataDir, opts) {
+    const filePath = path.join(dataDir, FILENAME);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        // No file → crash unless this is the first-ever boot.
+        return { type: opts?.firstBoot ? 'first-boot' : 'crash' };
+    }
+    // Delete the file regardless of parse outcome.
+    try {
+        await fs.unlink(filePath);
+    }
+    catch {
+        // Best-effort deletion.
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Corrupted file → treat as crash.
+        return { type: 'crash' };
+    }
+    // Non-object JSON (null, string, array, number) → treat as crash.
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { type: 'crash' };
+    }
+    // Validate reason against known union; unknown/missing → graceful-unknown.
+    const reason = VALID_REASONS.has(parsed.reason) ? parsed.reason : 'unknown';
+    const ctx = {
+        reason,
+        timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : new Date().toISOString(),
+        message: typeof parsed.message === 'string' ? parsed.message.slice(0, MAX_FIELD_LENGTH) : undefined,
+        activeForge: typeof parsed.activeForge === 'string' ? parsed.activeForge.slice(0, MAX_FIELD_LENGTH) : undefined,
+        requestedBy: typeof parsed.requestedBy === 'string' ? parsed.requestedBy : undefined,
+    };
+    if (ctx.reason === 'unknown') {
+        return { type: 'graceful-unknown', shutdown: ctx };
+    }
+    return { type: 'intentional', shutdown: ctx };
+}
+// ---------------------------------------------------------------------------
+// Format for AI injection
+// ---------------------------------------------------------------------------
+/**
+ * Format startup context as a one-shot prompt injection string.
+ * Returns null if there's nothing meaningful to inject (shouldn't happen
+ * in practice, but defensive).
+ */
+export function formatStartupInjection(ctx) {
+    let line;
+    switch (ctx.type) {
+        case 'intentional': {
+            const reason = ctx.shutdown?.reason ?? 'restart-command';
+            const who = ctx.shutdown?.requestedBy
+                ? ` by <@${ctx.shutdown.requestedBy}>`
+                : '';
+            const msg = ctx.shutdown?.message
+                ? ` (${ctx.shutdown.message})`
+                : '';
+            const via = reason === 'restart-command' ? ' via !restart'
+                : reason === 'deploy' ? ' for a deploy'
+                    : reason === 'code-fix' ? ' to apply a code fix'
+                        : '';
+            line = `You were restarted${via}${who}${msg}.`;
+            break;
+        }
+        case 'graceful-unknown':
+            line = 'You were restarted (graceful shutdown, reason unknown — likely a manual systemctl restart).';
+            break;
+        case 'crash':
+            line = 'You appear to have crashed or been killed (no shutdown context found). Consider checking journalctl logs.';
+            break;
+        case 'first-boot':
+            return null; // Nothing to inject on first-ever boot.
+        default:
+            return null;
+    }
+    if (ctx.shutdown?.activeForge) {
+        line += ` A forge run was in progress: ${ctx.shutdown.activeForge}.`;
+    }
+    line += ' If the current thread\'s task is already resolved, don\'t announce it — just respond to the user.';
+    return line;
+}