diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md index e17a089b..773cc28a 100644 --- a/docs/architecture-invariants.md +++ b/docs/architecture-invariants.md @@ -1549,3 +1549,15 @@ updates `lastSubmitAt` just like any other Enter. - **Files.** Received files come only from Discord's HTTPS hosts into `/.codeman-discord/` (bounded probe, refused if a symlink, self-ignoring). A sent file's real path must lie inside the tab's folder; both the folder and the file are probed with the bounded probe first. - **The whole last message.** A finished turn or an error posts the CLI's whole last message, not the screen: `WebServer.lastResponseFor` is the response viewer's reader (the body of `GET /api/sessions/:id/last-response`, registered on the route context by `registerSessionRoutes`), so the source is the same per-CLI transcript, or the pane split into turns where a CLI keeps none; a dialog and a shell keep the screen tail (its composer row and the status lines under it cut, never a `❯ 1.` option row). The read is bounded to 4 s and any failure or empty read falls back to the screen. It is split into at most 8 posts of 1,900 characters, a cut code fence closed and reopened, and Markdown tables become aligned code blocks (the separator test strips whitespace first: a regex over a run of spaces is quadratic, and the text is steerable by whatever the agent read). The repeat check is keyed on the text plus the turn it came from (the transcript stamp, else the last submit) and is recorded only after the first post succeeds, so a failed post is sent again and a later turn ending on the same words is not dropped. Only some CLIs raise a turn end (`/api/hook-event`: Claude's `stop` and `idle_prompt`, DeepSeek's `stop`), so the others reach this path through errors, a blocked respawn or a crash loop. - **Cost guards.** The alert tail is a function called only once a post will happen (no tmux exec while off), and `discord-notify` is a per-session token bucket (6 a minute, `429 RATE_LIMITED`). + + +### Discord reply replay metadata + +`discord-reply-dedupe.json` is a private 0600 data-directory file containing at most +2,048 reply IDs and timestamps retained for seven days. An allowed reply is claimed +by message ID before attachments or terminal input. Store failures log once and fall +back to memory; they never cost a reply. An unreadable or unsafe file is never +overwritten, and reads retry later. Readable but invalid ID-only content warns and +heals on the next write. Recovery keeps older disk rows before newer outage claims +so bounded eviction drops the oldest IDs first. Ambiguous terminal input is never +replayed automatically. diff --git a/docs/discord-bridge.md b/docs/discord-bridge.md index 7fb3669a..14598b57 100644 --- a/docs/discord-bridge.md +++ b/docs/discord-bridge.md @@ -145,7 +145,7 @@ including after a restart. The file contains IDs and timestamps only, with mode This is best-effort replay protection, not an exactly-once guarantee. A full disk, unreadable file, or invalid metadata logs one content-free warning and falls back to in-memory checks. -Reads and writes retry on later replies; a restart during a metadata outage can lose those +Readable but invalid ID metadata is replaced on the next write. Files that could not be read are left untouched. Reads and writes retry on later replies; a restart during a metadata outage can lose those checks. At capacity the oldest entries are evicted, so capacity never blocks new replies. Notifications retain their existing delivery and retry behavior; this store never suppresses an outbound alert or replays terminal input. diff --git a/src/discord-bridge.ts b/src/discord-bridge.ts index 6fe14629..c1948f88 100644 --- a/src/discord-bridge.ts +++ b/src/discord-bridge.ts @@ -4,7 +4,10 @@ * Split like webhook-notify.ts, so the parts that matter are testable without a network: * - pure: `sanitiseReply`, `threadNameFor`, `buildPost`, `discordConfigProblem`, `maskToken` * - store: `~/.codeman/discord.json` (bot token, 0600 via tmp+rename) and - * `~/.codeman/discord-bridge.json` (sessionId -> threadId, not secret) + * `~/.codeman/discord-bridge.json` (sessionId -> threadId, not secret) and + * `~/.codeman/discord-reply-dedupe.json` (bounded reply IDs/timestamps, private). + * Allowed replies are claimed before attachments or typing; store failures never cost a reply. + * An unreadable file is never overwritten; invalid readable ID metadata can heal. * - IO: `DiscordApi` (REST, injected fetch), `DiscordGateway` (inbound WebSocket, injected * socket factory) and `DiscordBridge` (the rules that tie them to sessions) * diff --git a/src/discord-reply-dedupe.ts b/src/discord-reply-dedupe.ts index 2c71497d..29cba04a 100644 --- a/src/discord-reply-dedupe.ts +++ b/src/discord-reply-dedupe.ts @@ -1,4 +1,4 @@ -/** Best-effort replay protection. A metadata-store failure must never block a person's reply. */ +/** @fileoverview Best-effort replay protection. A metadata-store failure must never block a person's reply. */ import fs from 'node:fs/promises'; import { join } from 'node:path'; import { randomUUID } from 'node:crypto'; @@ -8,13 +8,14 @@ const RETENTION_MS = 7 * 24 * 60 * 60_000; export class DiscordReplyDedupe { private seen = new Map(); private loaded = false; + private dirty = false; private warned = false; private chain: Promise = Promise.resolve(); constructor( private readonly dir: string, private readonly now: () => number = Date.now, private readonly warn: () => void = () => - console.warn('Discord reply metadata unavailable; using in-memory deduplication') + console.warn('Discord reply metadata unavailable (discord-reply-dedupe.json); using in-memory deduplication') ) {} claim(guild: string, channel: string, message: string): Promise { const run = this.chain.then(() => this.take(guild, channel, message)); @@ -26,46 +27,59 @@ export class DiscordReplyDedupe { if (![guild, channel, message].every((id) => /^\d{15,25}$/.test(id))) return true; const path = join(this.dir, 'discord-reply-dedupe.json'); const cutoff = this.now() - RETENTION_MS; - try { - if (!this.loaded) { - try { - const st = await fs.lstat(path); - if (!st.isFile() || st.isSymbolicLink() || st.size > 512 * 1024) throw new Error('Unsafe metadata'); - const rows: unknown = JSON.parse(await fs.readFile(path, 'utf8')); - if (!Array.isArray(rows) || rows.length > LIMIT) throw new Error('Invalid metadata'); - const recovered = new Map(); - for (const row of rows) { - if (!Array.isArray(row) || !/^\d{15,25}:\d{15,25}:\d{15,25}$/.test(row[0]) || !Number.isFinite(row[1])) - throw new Error('Invalid metadata'); - if (row[1] >= cutoff) recovered.set(row[0], row[1]); - } - for (const [key, at] of recovered) if (!this.seen.has(key)) this.seen.set(key, at); - } catch (err) { - if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err; + if (!this.loaded) { + let contentRead = false; + try { + const st = await fs.lstat(path); + if (!st.isFile() || st.isSymbolicLink() || st.size > 512 * 1024) + throw Object.assign(new Error('Unsafe metadata'), { code: 'EINVAL' }); + const text = await fs.readFile(path, 'utf8'); + contentRead = true; + const rows: unknown = JSON.parse(text); + if (!Array.isArray(rows) || rows.length > LIMIT) throw new Error('Invalid metadata'); + const recovered = new Map(); + for (const row of rows) { + if (!Array.isArray(row) || !/^\d{15,25}:\d{15,25}:\d{15,25}$/.test(row[0]) || !Number.isFinite(row[1])) + throw new Error('Invalid metadata'); + if (row[1] >= cutoff) recovered.set(row[0], row[1]); } + // Older disk rows precede newer claims made while reads were unavailable. + this.seen = new Map([...recovered, ...this.seen]); this.loaded = true; + } catch (err) { + if ((err as NodeJS.ErrnoException).code === 'ENOENT') this.loaded = true; + else { + this.report(); + // Invalid content is recoverable ID-only metadata; unreadable/unsafe files stay untouched. + if (contentRead && !(err as NodeJS.ErrnoException).code) { + this.loaded = true; + this.dirty = true; + } + } } - } catch { - this.report(); // Retry the read on the next reply; never memoize a failed load. } for (const [key, at] of this.seen) if (at < cutoff) this.seen.delete(key); const key = `${guild}:${channel}:${message}`; - if (this.seen.has(key)) return false; - this.seen.set(key, this.now()); // Before awaiting IO or typing, including during an outage. + const fresh = !this.seen.has(key); + if (fresh) { + this.seen.set(key, this.now()); + this.dirty = true; + } // Before awaiting IO or typing, including during an outage. while (this.seen.size > LIMIT) this.seen.delete(this.seen.keys().next().value!); - if (!this.loaded) return true; // Do not overwrite a journal we could not read. + if (!this.loaded || !this.dirty) return fresh; // Do not overwrite a journal we could not read. const tmp = `${path}.${randomUUID()}.tmp`; try { await fs.mkdir(this.dir, { recursive: true }); await fs.writeFile(tmp, JSON.stringify([...this.seen]), { mode: 0o600, flag: 'wx' }); await fs.rename(tmp, path); this.warned = false; + this.dirty = false; } catch { this.report(); } finally { await fs.rm(tmp, { force: true }).catch(() => undefined); } - return true; + return fresh; } private report(): void { if (!this.warned) this.warn(); diff --git a/test/discord-reply-dedupe.test.ts b/test/discord-reply-dedupe.test.ts index fbf6793a..46b180bd 100644 --- a/test/discord-reply-dedupe.test.ts +++ b/test/discord-reply-dedupe.test.ts @@ -71,3 +71,53 @@ it('evicts old records rather than refusing replies at capacity', async () => { expect(await new DiscordReplyDedupe(dir).claim(guild, channel, message)).toBe(true); expect(JSON.parse(await readFile(join(dir, 'discord-reply-dedupe.json'), 'utf8'))).toHaveLength(2048); }); + +it.each(['{', '{}', '[null]'])( + 'heals readable invalid metadata %s and keeps the claim across restart', + async (invalid) => { + const path = join(dir, 'discord-reply-dedupe.json'); + await writeFile(path, invalid); + const warn = vi.fn(), + store = new DiscordReplyDedupe(dir, Date.now, warn); + expect(await store.claim(guild, channel, message)).toBe(true); + expect(await new DiscordReplyDedupe(dir).claim(guild, channel, message)).toBe(false); + expect(warn).toHaveBeenCalledTimes(1); + } +); + +it('retains newer outage claims when disk recovery reaches capacity, without overwriting an unread file', async () => { + const path = join(dir, 'discord-reply-dedupe.json'); + const rows = Array.from({ length: 2048 }, (_, i) => [ + `${guild}:${channel}:${100000000000000000n + BigInt(i)}`, + Date.now(), + ]); + const original = JSON.stringify(rows); + await writeFile(path, original); + const warn = vi.fn(), + store = new DiscordReplyDedupe(dir, Date.now, warn); + const read = vi + .spyOn(fs, 'readFile') + .mockRejectedValueOnce(Object.assign(new Error('descriptor limit'), { code: 'EMFILE' })); + expect(await store.claim(guild, channel, message)).toBe(true); + read.mockRestore(); + expect(await readFile(path, 'utf8')).toBe(original); + expect(await store.claim(guild, channel, '444444444444444444')).toBe(true); + expect(await new DiscordReplyDedupe(dir).claim(guild, channel, message)).toBe(false); + const saved = JSON.parse(await readFile(path, 'utf8')); + expect(saved).toHaveLength(2048); + expect(saved.some((row: [string, number]) => row[0] === rows[0][0])).toBe(false); +}); + +it('heals an over-cap readable store rather than remaining memory-only until manual deletion', async () => { + const path = join(dir, 'discord-reply-dedupe.json'); + await writeFile( + path, + JSON.stringify( + Array.from({ length: 2049 }, (_, i) => [`${guild}:${channel}:${100000000000000000n + BigInt(i)}`, Date.now()]) + ) + ); + const warn = vi.fn(); + expect(await new DiscordReplyDedupe(dir, Date.now, warn).claim(guild, channel, message)).toBe(true); + expect(await new DiscordReplyDedupe(dir).claim(guild, channel, message)).toBe(false); + expect(warn).toHaveBeenCalledTimes(1); +});