discoclaw 0.1.0

package/dist/health/credential-check.test.js

@@ -0,0 +1,401 @@
+import { describe, expect, it, vi } from 'vitest';
+import { checkDiscordToken, checkOpenAiKey, checkOpenRouterKey, formatCredentialReport, runCredentialChecks, } from './credential-check.js';
+// Helpers ------------------------------------------------------------------
+function mockFetch(status, body = '') {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(body, { status })));
+}
+function mockFetchError(message) {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error(message)));
+}
+function makeReport(results) {
+    const criticalFailures = results
+        .filter((r) => r.status === 'fail' && r.name === 'discord-token')
+        .map((r) => r.name);
+    const allOk = results.every((r) => r.status === 'ok' || r.status === 'skip');
+    return { results, criticalFailures, allOk };
+}
+// checkDiscordToken --------------------------------------------------------
+describe('checkDiscordToken', () => {
+    it('returns ok for a 200 response', async () => {
+        mockFetch(200, '{"id":"123","username":"TestBot","bot":true}');
+        const result = await checkDiscordToken('valid-token');
+        expect(result.name).toBe('discord-token');
+        expect(result.status).toBe('ok');
+        expect(result.message).toBeUndefined();
+    });
+    it('returns fail with 401 message for unauthorized', async () => {
+        mockFetch(401, '{"message":"401: Unauthorized","code":0}');
+        const result = await checkDiscordToken('bad-token');
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('401');
+    });
+    it('returns fail for an unexpected HTTP status', async () => {
+        mockFetch(503);
+        const result = await checkDiscordToken('token');
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('503');
+    });
+    it('returns fail on network error without throwing', async () => {
+        mockFetchError('ECONNREFUSED');
+        const result = await checkDiscordToken('token');
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('network error');
+        expect(result.message).toContain('ECONNREFUSED');
+    });
+    it('sends request to the correct Discord API endpoint with Bot prefix', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkDiscordToken('my-token');
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://discord.com/api/v10/users/@me');
+        expect(init.headers['Authorization']).toBe('Bot my-token');
+    });
+});
+// checkOpenAiKey -----------------------------------------------------------
+describe('checkOpenAiKey', () => {
+    it('returns skip when no API key is provided', async () => {
+        const result = await checkOpenAiKey({});
+        expect(result.name).toBe('openai-key');
+        expect(result.status).toBe('skip');
+    });
+    it('returns skip for an empty string key', async () => {
+        const result = await checkOpenAiKey({ apiKey: '' });
+        expect(result.status).toBe('skip');
+    });
+    it('returns ok for a 200 response', async () => {
+        mockFetch(200, '{"object":"list","data":[]}');
+        const result = await checkOpenAiKey({ apiKey: 'sk-valid' });
+        expect(result.name).toBe('openai-key');
+        expect(result.status).toBe('ok');
+        expect(result.message).toBeUndefined();
+    });
+    it('returns fail with 401 message for an invalid key', async () => {
+        mockFetch(401, '{"error":{"message":"Incorrect API key"}}');
+        const result = await checkOpenAiKey({ apiKey: 'sk-bad' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('401');
+    });
+    it('returns fail with 403 message for a key lacking permissions', async () => {
+        mockFetch(403, '{"error":{"message":"Forbidden"}}');
+        const result = await checkOpenAiKey({ apiKey: 'sk-no-perms' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('403');
+    });
+    it('returns fail for an unexpected HTTP status', async () => {
+        mockFetch(429, '{"error":{"message":"Rate limit exceeded"}}');
+        const result = await checkOpenAiKey({ apiKey: 'sk-test' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('429');
+    });
+    it('returns fail on network error without throwing', async () => {
+        mockFetchError('connect ETIMEDOUT');
+        const result = await checkOpenAiKey({ apiKey: 'sk-test' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('network error');
+        expect(result.message).toContain('ETIMEDOUT');
+    });
+    it('uses the default OpenAI base URL when none is provided', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenAiKey({ apiKey: 'sk-test' });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://api.openai.com/v1/models');
+    });
+    it('uses a custom base URL when provided', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenAiKey({ apiKey: 'sk-test', baseUrl: 'https://my.proxy.example.com/v1' });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://my.proxy.example.com/v1/models');
+    });
+    it('strips a trailing slash from the custom base URL', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenAiKey({ apiKey: 'sk-test', baseUrl: 'https://my.proxy.example.com/v1/' });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://my.proxy.example.com/v1/models');
+    });
+    it('sends the correct Bearer Authorization header', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenAiKey({ apiKey: 'sk-my-key' });
+        const [, init] = fetchSpy.mock.calls[0];
+        expect(init.headers['Authorization']).toBe('Bearer sk-my-key');
+    });
+    it('does not call fetch when no key is provided', async () => {
+        const fetchSpy = vi.fn();
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenAiKey({});
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+});
+// checkOpenRouterKey -------------------------------------------------------
+describe('checkOpenRouterKey', () => {
+    it('returns skip when no API key is provided', async () => {
+        const result = await checkOpenRouterKey({});
+        expect(result.name).toBe('openrouter-key');
+        expect(result.status).toBe('skip');
+    });
+    it('returns skip for an empty string key', async () => {
+        const result = await checkOpenRouterKey({ apiKey: '' });
+        expect(result.status).toBe('skip');
+    });
+    it('returns ok for a 200 response', async () => {
+        mockFetch(200, '{"object":"list","data":[]}');
+        const result = await checkOpenRouterKey({ apiKey: 'sk-or-valid' });
+        expect(result.name).toBe('openrouter-key');
+        expect(result.status).toBe('ok');
+        expect(result.message).toBeUndefined();
+    });
+    it('returns fail with 401 message for an invalid key', async () => {
+        mockFetch(401, '{"error":{"message":"Invalid API key"}}');
+        const result = await checkOpenRouterKey({ apiKey: 'sk-or-bad' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('401');
+    });
+    it('returns fail with 403 message for a key lacking permissions', async () => {
+        mockFetch(403, '{"error":{"message":"Forbidden"}}');
+        const result = await checkOpenRouterKey({ apiKey: 'sk-or-no-perms' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('403');
+    });
+    it('returns fail for an unexpected HTTP status', async () => {
+        mockFetch(429, '{"error":{"message":"Rate limit exceeded"}}');
+        const result = await checkOpenRouterKey({ apiKey: 'sk-or-test' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('429');
+    });
+    it('returns fail on network error without throwing', async () => {
+        mockFetchError('connect ETIMEDOUT');
+        const result = await checkOpenRouterKey({ apiKey: 'sk-or-test' });
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('network error');
+        expect(result.message).toContain('ETIMEDOUT');
+    });
+    it('uses the default OpenRouter base URL when none is provided', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenRouterKey({ apiKey: 'sk-or-test' });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://openrouter.ai/api/v1/models');
+    });
+    it('uses a custom base URL when provided', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenRouterKey({ apiKey: 'sk-or-test', baseUrl: 'https://my.proxy.example.com/v1' });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://my.proxy.example.com/v1/models');
+    });
+    it('strips a trailing slash from the custom base URL', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenRouterKey({
+            apiKey: 'sk-or-test',
+            baseUrl: 'https://my.proxy.example.com/v1/',
+        });
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://my.proxy.example.com/v1/models');
+    });
+    it('sends the correct Bearer Authorization header', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenRouterKey({ apiKey: 'sk-or-my-key' });
+        const [, init] = fetchSpy.mock.calls[0];
+        expect(init.headers['Authorization']).toBe('Bearer sk-or-my-key');
+    });
+    it('does not call fetch when no key is provided', async () => {
+        const fetchSpy = vi.fn();
+        vi.stubGlobal('fetch', fetchSpy);
+        await checkOpenRouterKey({});
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+});
+// runCredentialChecks ------------------------------------------------------
+describe('runCredentialChecks', () => {
+    it('returns four results (one per check)', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('{}', { status: 200 })));
+        const report = await runCredentialChecks({ token: 'valid-token', openaiApiKey: 'sk-valid' });
+        expect(report.results).toHaveLength(4);
+        expect(report.results.map((r) => r.name)).toEqual([
+            'discord-token',
+            'openai-key',
+            'workspace-path',
+            'status-channel',
+        ]);
+    });
+    it('sets allOk=true when all configured checks pass', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('{}', { status: 200 })));
+        const report = await runCredentialChecks({ token: 'valid-token', openaiApiKey: 'sk-valid' });
+        expect(report.allOk).toBe(true);
+        expect(report.criticalFailures).toHaveLength(0);
+    });
+    it('sets allOk=true when the optional OpenAI key is not provided (skip counts as ok)', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('{}', { status: 200 })));
+        const report = await runCredentialChecks({ token: 'valid-token' });
+        expect(report.allOk).toBe(true);
+        expect(report.results.find((r) => r.name === 'openai-key')?.status).toBe('skip');
+    });
+    it('sets allOk=false and lists discord-token in criticalFailures when it fails', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('{}', { status: 401 })));
+        const report = await runCredentialChecks({ token: 'bad-token' });
+        expect(report.allOk).toBe(false);
+        expect(report.criticalFailures).toContain('discord-token');
+    });
+    it('sets allOk=false but no criticalFailures when only openai-key fails', async () => {
+        vi.stubGlobal('fetch', vi.fn()
+            .mockResolvedValueOnce(new Response('{}', { status: 200 })) // discord: ok
+            .mockResolvedValueOnce(new Response('{}', { status: 401 })));
+        const report = await runCredentialChecks({ token: 'valid-token', openaiApiKey: 'sk-bad' });
+        expect(report.allOk).toBe(false);
+        expect(report.criticalFailures).toHaveLength(0);
+    });
+    it('runs all checks concurrently (both fetch calls are made)', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await runCredentialChecks({ token: 'token', openaiApiKey: 'sk-key' });
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+    it('passes openaiBaseUrl through to checkOpenAiKey', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await runCredentialChecks({
+            token: 'token',
+            openaiApiKey: 'sk-key',
+            openaiBaseUrl: 'https://custom.example.com/v1',
+        });
+        const openAiCall = fetchSpy.mock.calls.find((args) => typeof args[0] === 'string' && args[0].includes('custom.example.com'));
+        expect(openAiCall).toBeDefined();
+    });
+    it('omits openai-key result when openai is not in activeProviders (key present)', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openaiApiKey: 'sk-stale',
+            activeProviders: new Set(['claude']),
+        });
+        expect(report.results.find((r) => r.name === 'openai-key')).toBeUndefined();
+        // fetch should only be called once (for discord)
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+    it('runs the openai-key check when openai is in activeProviders', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openaiApiKey: 'sk-valid',
+            activeProviders: new Set(['openai']),
+        });
+        const openaiResult = report.results.find((r) => r.name === 'openai-key');
+        expect(openaiResult).toBeDefined();
+        expect(openaiResult?.status).toBe('ok');
+    });
+    it('preserves current behavior (runs openai check) when activeProviders is omitted', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openaiApiKey: 'sk-valid',
+        });
+        const openaiResult = report.results.find((r) => r.name === 'openai-key');
+        expect(openaiResult).toBeDefined();
+        expect(openaiResult?.status).toBe('ok');
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+    it('omits openrouter-key result when openrouter is not in activeProviders (key present)', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openrouterApiKey: 'sk-or-stale',
+            activeProviders: new Set(['claude']),
+        });
+        expect(report.results.find((r) => r.name === 'openrouter-key')).toBeUndefined();
+        // fetch should only be called once (for discord)
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+    it('runs the openrouter-key check when openrouter is in activeProviders', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openrouterApiKey: 'sk-or-valid',
+            activeProviders: new Set(['openrouter']),
+        });
+        const openrouterResult = report.results.find((r) => r.name === 'openrouter-key');
+        expect(openrouterResult).toBeDefined();
+        expect(openrouterResult?.status).toBe('ok');
+    });
+    it('runs both openai and openrouter checks concurrently when both are in activeProviders', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        const report = await runCredentialChecks({
+            token: 'valid-token',
+            openaiApiKey: 'sk-valid',
+            openrouterApiKey: 'sk-or-valid',
+            activeProviders: new Set(['openai', 'openrouter']),
+        });
+        expect(report.results.find((r) => r.name === 'openai-key')).toBeDefined();
+        expect(report.results.find((r) => r.name === 'openrouter-key')).toBeDefined();
+        // discord + openai + openrouter = 3 fetch calls
+        expect(fetchSpy).toHaveBeenCalledTimes(3);
+    });
+    it('passes openrouterBaseUrl through to checkOpenRouterKey', async () => {
+        const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchSpy);
+        await runCredentialChecks({
+            token: 'token',
+            openrouterApiKey: 'sk-or-key',
+            openrouterBaseUrl: 'https://custom-or.example.com/v1',
+            activeProviders: new Set(['openrouter']),
+        });
+        const openRouterCall = fetchSpy.mock.calls.find((args) => typeof args[0] === 'string' && args[0].includes('custom-or.example.com'));
+        expect(openRouterCall).toBeDefined();
+    });
+});
+// formatCredentialReport ---------------------------------------------------
+describe('formatCredentialReport', () => {
+    it('formats a single ok result', () => {
+        const report = makeReport([{ name: 'discord-token', status: 'ok' }]);
+        expect(formatCredentialReport(report)).toBe('discord-token: ok');
+    });
+    it('formats a single skip result', () => {
+        const report = makeReport([{ name: 'openai-key', status: 'skip' }]);
+        expect(formatCredentialReport(report)).toBe('openai-key: skip');
+    });
+    it('formats a fail result with uppercase FAIL tag', () => {
+        const report = makeReport([
+            { name: 'discord-token', status: 'fail', message: 'invalid or revoked token (401)' },
+        ]);
+        const out = formatCredentialReport(report);
+        expect(out).toContain('FAIL');
+        expect(out).toContain('discord-token');
+    });
+    it('includes the message in parentheses for a fail result', () => {
+        const report = makeReport([
+            { name: 'discord-token', status: 'fail', message: 'network error: ECONNREFUSED' },
+        ]);
+        expect(formatCredentialReport(report)).toContain('(network error: ECONNREFUSED)');
+    });
+    it('omits parentheses when there is no message', () => {
+        const report = makeReport([{ name: 'discord-token', status: 'ok' }]);
+        expect(formatCredentialReport(report)).toBe('discord-token: ok');
+    });
+    it('joins multiple results with ", "', () => {
+        const report = makeReport([
+            { name: 'discord-token', status: 'ok' },
+            { name: 'openai-key', status: 'skip' },
+        ]);
+        const out = formatCredentialReport(report);
+        expect(out).toBe('discord-token: ok, openai-key: skip');
+    });
+    it('formats a mixed ok/fail report correctly', () => {
+        const report = makeReport([
+            { name: 'discord-token', status: 'ok' },
+            { name: 'openai-key', status: 'fail', message: 'invalid or expired key (401)' },
+        ]);
+        const out = formatCredentialReport(report);
+        expect(out).toContain('discord-token: ok');
+        expect(out).toContain('openai-key: FAIL (invalid or expired key (401))');
+    });
+});

package/dist/health/startup-healing.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs/promises';
+/**
+ * Scenario 2: Remove stale cron run-stats records for threads that no longer exist.
+ *
+ * Iterates all records in the persistent stats store. For each record, attempts
+ * to fetch the Discord thread. If the thread is gone (null return or Discord
+ * error code 10003 / HTTP 404), removes the record via `statsStore.removeByThreadId()`
+ * and logs a structured warning.
+ *
+ * Non-404 errors (network failures, rate-limits, etc.) are treated as transient:
+ * the record is preserved and a fetch-error warning is logged instead.
+ *
+ * All remove-path errors are caught and logged (fail-open) to prevent healing
+ * from becoming a startup crash path.
+ */
+export async function healStaleCronRecords(statsStore, client, log) {
+    const jobs = Object.values(statsStore.getStore().jobs);
+    for (const record of jobs) {
+        const { cronId, threadId } = record;
+        let threadGone = false;
+        try {
+            const channel = await client.channels.fetch(threadId);
+            if (channel === null || channel === undefined) {
+                threadGone = true;
+            }
+        }
+        catch (err) {
+            // Treat Discord "Unknown Channel" (code 10003) or HTTP 404 as definitely gone.
+            // Any other error is treated as transient — skip to avoid purging live records.
+            const code = err?.code;
+            const status = err?.status ?? err?.httpStatus;
+            if (code === 10003 || status === 404) {
+                threadGone = true;
+            }
+            else {
+                log?.warn({ cronId, threadId, err: err instanceof Error ? err.message : String(err) }, 'startup:heal:cron fetch error — skipping record');
+                continue;
+            }
+        }
+        if (!threadGone)
+            continue;
+        try {
+            await statsStore.removeByThreadId(threadId);
+            log?.warn({ cronId, threadId }, 'startup:heal:cron removed stale stats record for deleted thread');
+        }
+        catch (err) {
+            log?.warn({ cronId, threadId, err: err instanceof Error ? err.message : String(err) }, 'startup:heal:cron failed to remove stale stats record — continuing');
+        }
+    }
+}
+/**
+ * Scenario 3: Surface stale task thread references for deleted Discord threads.
+ *
+ * Iterates non-closed tasks with an `external_ref` of the form `discord:<threadId>`.
+ * If the thread no longer exists (null return or Discord 10003/404), logs a structured
+ * warning. Does NOT modify `external_ref` — the next task sync run may recreate the
+ * thread and re-link it.
+ *
+ * Non-404 errors are logged as a separate fetch-error warning and skipped.
+ * Never throws; all errors are caught and logged.
+ */
+export async function healStaleTaskThreadRefs(store, client, log) {
+    const tasks = store.list(); // excludes closed tasks by default
+    for (const task of tasks) {
+        const ref = task.external_ref;
+        if (!ref?.startsWith('discord:'))
+            continue;
+        const threadId = ref.slice('discord:'.length);
+        if (!threadId)
+            continue;
+        try {
+            const channel = await client.channels.fetch(threadId);
+            if (channel === null || channel === undefined) {
+                log?.warn({ taskId: task.id, threadId }, 'startup:heal:task thread no longer exists (external_ref retained for next sync)');
+            }
+        }
+        catch (err) {
+            const code = err?.code;
+            const status = err?.status ?? err?.httpStatus;
+            if (code === 10003 || status === 404) {
+                log?.warn({ taskId: task.id, threadId }, 'startup:heal:task thread no longer exists (external_ref retained for next sync)');
+            }
+            else {
+                log?.warn({ taskId: task.id, threadId, err: err instanceof Error ? err.message : String(err) }, 'startup:heal:task thread fetch error — skipping');
+            }
+        }
+    }
+}
+/**
+ * Scenario 4: Back up and remove corrupted JSON store files before they are loaded.
+ *
+ * For each `{ path, label }` entry: reads the file, attempts `JSON.parse`, and
+ * on failure copies the corrupted file to `<path>.corrupt.<ISO-timestamp>` then
+ * removes the original. Downstream loaders all handle missing files gracefully,
+ * so the net effect is a safe reset.
+ *
+ * - ENOENT (file not found) is not corruption — those entries are silently skipped.
+ * - Unreadable files (non-ENOENT) are warned and skipped.
+ * - Backup/remove failures are logged and skipped (fail-open).
+ */
+export async function healCorruptedJsonStores(paths, log) {
+    for (const { path: filePath, label } of paths) {
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue; // Not corruption.
+            log?.warn({ label, path: filePath, err: err instanceof Error ? err.message : String(err) }, 'startup:heal:json unreadable — skipping');
+            continue;
+        }
+        try {
+            JSON.parse(raw);
+            // Valid JSON — nothing to do.
+        }
+        catch (parseErr) {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const backupPath = `${filePath}.corrupt.${timestamp}`;
+            try {
+                await fs.copyFile(filePath, backupPath);
+                await fs.unlink(filePath);
+                log?.warn({
+                    label,
+                    path: filePath,
+                    backupPath,
+                    parseError: parseErr instanceof Error ? parseErr.message : String(parseErr),
+                }, 'startup:heal:json corrupted — backed up and removed');
+            }
+            catch (fsErr) {
+                log?.warn({
+                    label,
+                    path: filePath,
+                    err: fsErr instanceof Error ? fsErr.message : String(fsErr),
+                }, 'startup:heal:json backup/remove failed — leaving file in place');
+            }
+        }
+    }
+}