@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/dist/src/update-journal.js

@@ -0,0 +1,267 @@
+/**
+ * Durable journal of MAX updates: accepted webhook updates survive a gateway
+ * restart or crash, and completion tombstones reject a redelivered update
+ * across restarts (webhook and polling).
+ *
+ * Why a plugin-owned journal: the SDK's durable ingress
+ * (createChannelIngressMonitor over runtime.state.openChannelIngressQueue) is
+ * refused to plugins that are neither bundled nor trusted official installs
+ * (PluginTrustRefusalError), and this plugin is neither. The journal follows
+ * the same contract: append before the webhook ack, one row per event,
+ * completion tombstones for replay dedupe, bounded retention.
+ *
+ * Layout: <stateDir>/max/inbox-<account>/ (0700)
+ *   u-<seq>.json    one pending update (0600), deleted once handled
+ *   completed.json  dedupe keys of handled updates with their completion time
+ *
+ * Update bodies are conversation content: they never reach the log.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readJsonFileWithFallback, writeJsonFileAtomically } from 'openclaw/plugin-sdk/json-store';
+import { resolveStateDir } from 'openclaw/plugin-sdk/state-paths';
+/** How long a handled update's key rejects a redelivery (MAX retries within 8 h). */
+export const MAX_JOURNAL_COMPLETED_TTL_MS = 24 * 60 * 60 * 1000;
+/** Most dedupe keys kept; the oldest go first. */
+export const MAX_JOURNAL_COMPLETED_MAX_ENTRIES = 5000;
+/** Unknown files (e.g. a temp file of a write cut by a crash) older than this are removed. */
+const STRAY_FILE_MIN_AGE_MS = 60_000;
+const ENTRY_FILE = /^u-(\d{13}-\d{6})\.json$/;
+const COMPLETED_FILE = 'completed.json';
+export function resolveMaxJournalDir(accountId) {
+    const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return path.join(resolveStateDir(), 'max', `inbox-${safeId}`);
+}
+/** One journal per directory in a process: overlapping account tasks share ownership. */
+const openJournals = new Map();
+/**
+ * Open (or reuse) the journal of an account. Rejects when the directory cannot
+ * be created or written; callers then fall back to the in-memory queue.
+ */
+export async function openMaxUpdateJournal(options) {
+    const dir = options.dir ?? resolveMaxJournalDir(options.accountId);
+    const existing = openJournals.get(dir);
+    if (existing) {
+        if (options.warn)
+            existing.warn = options.warn;
+        return existing;
+    }
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700);
+    await fs.access(dir, fs.constants.W_OK);
+    const journal = new MaxUpdateJournal(dir, options);
+    await journal.loadCompleted();
+    const raced = openJournals.get(dir);
+    if (raced)
+        return raced;
+    openJournals.set(dir, journal);
+    return journal;
+}
+export class MaxUpdateJournal {
+    dir;
+    warn;
+    now;
+    completedTtlMs;
+    completedMaxEntries;
+    /** Dedupe key → completion time, oldest first. */
+    completed = new Map();
+    /** Entries this process holds (queued or dispatching): recovery skips them. */
+    owned = new Set();
+    /** Keys of entries still on disk. */
+    pendingKeys = new Set();
+    lastSeqMs = 0;
+    seqCounter = 0;
+    scheduledWrite;
+    lastWrite = Promise.resolve();
+    constructor(dir, options) {
+        this.dir = dir;
+        this.warn = options.warn;
+        this.now = options.now ?? Date.now;
+        this.completedTtlMs = options.completedTtlMs ?? MAX_JOURNAL_COMPLETED_TTL_MS;
+        this.completedMaxEntries = options.completedMaxEntries ?? MAX_JOURNAL_COMPLETED_MAX_ENTRIES;
+    }
+    /** @internal */
+    async loadCompleted() {
+        const file = path.join(this.dir, COMPLETED_FILE);
+        const { value, exists } = await readJsonFileWithFallback(file, null);
+        const keys = value && typeof value === 'object' ? value.keys : undefined;
+        if (!keys || typeof keys !== 'object' || Array.isArray(keys)) {
+            if (exists)
+                this.warn?.(`MAX journal ${this.dir}: unreadable ${COMPLETED_FILE}, starting empty`);
+            return;
+        }
+        const entries = Object.entries(keys)
+            .filter((entry) => typeof entry[1] === 'number')
+            .sort((a, b) => a[1] - b[1]);
+        for (const [key, at] of entries)
+            this.completed.set(key, at);
+        this.pruneCompleted();
+    }
+    /** True when the key belongs to a pending update or was handled within the TTL. */
+    isDuplicate(key) {
+        return this.pendingKeys.has(key) || this.hasCompleted(key);
+    }
+    hasCompleted(key) {
+        const at = this.completed.get(key);
+        return at !== undefined && this.now() - at < this.completedTtlMs;
+    }
+    /** Durably record an accepted update; resolves once it is on disk. */
+    async append(update, key) {
+        const receivedAt = this.now();
+        const entry = {
+            v: 1,
+            seq: this.nextSeq(receivedAt),
+            receivedAt,
+            ...(key ? { key } : {}),
+            update,
+        };
+        // Owned before the file exists, so a concurrent recovery never takes it.
+        this.owned.add(entry.seq);
+        if (key)
+            this.pendingKeys.add(key);
+        try {
+            await writeJsonFileAtomically(this.entryPath(entry.seq), entry);
+        }
+        catch (err) {
+            this.owned.delete(entry.seq);
+            if (key)
+                this.pendingKeys.delete(key);
+            await fs.rm(this.entryPath(entry.seq), { force: true }).catch(() => undefined);
+            throw err;
+        }
+        return entry;
+    }
+    /**
+     * Entries on disk that this process does not hold (left by an earlier
+     * process), oldest first. They become owned. Unreadable entries are deleted
+     * and counted.
+     */
+    async readPending() {
+        const names = await fs.readdir(this.dir);
+        const entries = [];
+        let unreadable = 0;
+        for (const name of names.sort()) {
+            const match = ENTRY_FILE.exec(name);
+            if (!match) {
+                await this.removeStray(name);
+                continue;
+            }
+            const seq = match[1];
+            if (this.owned.has(seq))
+                continue;
+            const file = this.entryPath(seq);
+            const { value } = await readJsonFileWithFallback(file, null);
+            if (!isJournalEntry(value, seq)) {
+                unreadable += 1;
+                await fs.rm(file, { force: true }).catch(() => undefined);
+                continue;
+            }
+            this.owned.add(seq);
+            if (value.key)
+                this.pendingKeys.add(value.key);
+            entries.push(value);
+        }
+        return { entries, unreadable };
+    }
+    /**
+     * The update was handled (or deliberately skipped): remember its key, then
+     * delete the entry. A failed tombstone write is logged, the entry is still
+     * deleted — replaying a handled update on every start would be worse.
+     */
+    async complete(entry) {
+        if (entry.key)
+            await this.remember(entry.key);
+        try {
+            await fs.rm(this.entryPath(entry.seq), { force: true });
+        }
+        catch (err) {
+            this.warn?.(`MAX journal: could not delete handled entry ${entry.seq}: ${errorCode(err)}`);
+        }
+        this.owned.delete(entry.seq);
+        if (entry.key)
+            this.pendingKeys.delete(entry.key);
+    }
+    /** Stop holding an entry without handling it: the next recovery takes it. */
+    release(entry) {
+        this.owned.delete(entry.seq);
+    }
+    /** Record a handled update's key (polling uses this without an entry). */
+    async remember(key) {
+        this.completed.delete(key);
+        this.completed.set(key, this.now());
+        this.pruneCompleted();
+        try {
+            await this.saveCompleted();
+        }
+        catch (err) {
+            this.warn?.(`MAX journal: could not save ${COMPLETED_FILE}: ${errorCode(err)}`);
+        }
+    }
+    pruneCompleted() {
+        const cutoff = this.now() - this.completedTtlMs;
+        for (const [key, at] of this.completed) {
+            if (at > cutoff && this.completed.size <= this.completedMaxEntries)
+                break;
+            this.completed.delete(key);
+        }
+    }
+    /** Coalesced, serialized writes: a caller resolves once a write with its change is done. */
+    saveCompleted() {
+        if (this.scheduledWrite)
+            return this.scheduledWrite;
+        const write = this.lastWrite
+            .catch(() => undefined)
+            .then(async () => {
+            this.scheduledWrite = undefined;
+            const file = { v: 1, keys: Object.fromEntries(this.completed) };
+            await writeJsonFileAtomically(path.join(this.dir, COMPLETED_FILE), file);
+        });
+        this.scheduledWrite = write;
+        this.lastWrite = write;
+        return write;
+    }
+    async removeStray(name) {
+        if (name === COMPLETED_FILE)
+            return;
+        const file = path.join(this.dir, name);
+        try {
+            const stat = await fs.lstat(file);
+            if (stat.isFile() && this.now() - stat.mtimeMs > STRAY_FILE_MIN_AGE_MS) {
+                await fs.rm(file, { force: true });
+            }
+        }
+        catch {
+            // Gone meanwhile or not ours to judge: leave it.
+        }
+    }
+    nextSeq(at) {
+        const ms = Math.max(at, this.lastSeqMs);
+        this.seqCounter = ms === this.lastSeqMs ? this.seqCounter + 1 : 0;
+        this.lastSeqMs = ms;
+        return `${String(ms).padStart(13, '0')}-${String(this.seqCounter).padStart(6, '0')}`;
+    }
+    entryPath(seq) {
+        return path.join(this.dir, `u-${seq}.json`);
+    }
+}
+function isJournalEntry(value, seq) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return (entry.v === 1 &&
+        entry.seq === seq &&
+        typeof entry.receivedAt === 'number' &&
+        (entry.key === undefined || typeof entry.key === 'string') &&
+        !!entry.update &&
+        typeof entry.update === 'object' &&
+        typeof entry.update.update_type === 'string');
+}
+/** Error code only: messages of fs errors carry paths, never needed in logs here. */
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : String(err);
+}
+/** @internal test helper: forget cached journals. */
+export function resetMaxUpdateJournalsForTest() {
+    openJournals.clear();
+}

package/dist/src/webhook-queue.js

@@ -11,6 +11,8 @@
  * admitted like the polling loop's. Every dispatch therefore has to start
  * from the consumer (`consume()`), never from `push()`.
  */
+import { isMaxGatewayDrainingError, waitForMaxDrainRetry } from './gateway-drain.js';
+import { runWithMaxTurnAdoption } from './turn-adoption.js';
 /** Updates handled at once across chats; one chat is always sequential. */
 export const MAX_WEBHOOK_CHAT_CONCURRENCY = 4;
 /** Accepted-but-unprocessed updates kept per account before new ones are dropped. */
@@ -19,6 +21,40 @@ export const MAX_WEBHOOK_PENDING_LIMIT = 5000;
 export const MAX_WEBHOOK_STOP_GRACE_MS = 3000;
 /** How long a restarted consumer waits for its predecessor's in-flight dispatches. */
 export const MAX_WEBHOOK_HANDOVER_WAIT_MS = 60_000;
+/** Default age past which updates the bot would answer are skipped (maxEventAgeMinutes). */
+export const MAX_EVENT_MAX_AGE_MINUTES = 60;
+/** Updates a late answer would confuse; registry updates (bot_added, …) are always handled. */
+const AGE_FENCED_UPDATE_TYPES = new Set([
+    'message_created',
+    'message_edited',
+    'message_callback',
+    'bot_started',
+]);
+/** maxEventAgeMinutes in ms; 0 (or less) turns the age fence off. */
+export function resolveMaxEventMaxAgeMs(minutes) {
+    const value = minutes ?? MAX_EVENT_MAX_AGE_MINUTES;
+    return value > 0 ? value * 60_000 : 0;
+}
+/**
+ * Age of an update the bot would answer, when it is past `maxAgeMs`: MAX's
+ * event time, else when it was received. Undefined when fresh or not fenced.
+ */
+export function staleMaxUpdateAgeMs(update, maxAgeMs, now, receivedAt) {
+    if (maxAgeMs <= 0 || !AGE_FENCED_UPDATE_TYPES.has(update.update_type))
+        return undefined;
+    const at = typeof update.timestamp === 'number' ? update.timestamp : receivedAt;
+    if (at === undefined)
+        return undefined;
+    const age = now - at;
+    return age > maxAgeMs ? age : undefined;
+}
+/** The queue could not take an update: the route answers non-200 so MAX redelivers. */
+export class MaxWebhookQueueRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MaxWebhookQueueRejectedError';
+    }
+}
 /** Serialization lane: the chat an update belongs to. */
 export function maxWebhookUpdateLane(update) {
     return String(update.message?.recipient?.chat_id ?? update.chat_id ?? 'global');
@@ -32,7 +68,10 @@ const handovers = new Map();
 /** Open queues per account: a stopping task hands leftovers to an overlapping successor. */
 const openQueues = new Map();
 export function createMaxWebhookUpdateQueue(params) {
-    const { accountId } = params;
+    const { accountId, journal } = params;
+    const overflow = params.overflow ?? 'reject';
+    const maxAgeMs = params.maxAgeMs ?? 0;
+    const now = params.now ?? Date.now;
     const concurrency = Math.max(1, params.concurrency ?? MAX_WEBHOOK_CHAT_CONCURRENCY);
     const pendingLimit = params.pendingLimit ?? MAX_WEBHOOK_PENDING_LIMIT;
     const stopGraceMs = params.stopGraceMs ?? MAX_WEBHOOK_STOP_GRACE_MS;
@@ -44,38 +83,88 @@ export function createMaxWebhookUpdateQueue(params) {
     let pending = inbox.length;
     let closed = false;
     let wake;
-    let warn;
-    const push = (update) => {
+    let warn = params.onWarn;
+    const enqueue = (item) => {
         if (closed) {
             // Route still selected this target while the task was stopping.
             const successor = [...siblings].at(-1);
             if (successor)
-                return successor(update);
+                return successor(item);
             const handover = handovers.get(accountId);
             if (handover)
-                handover.updates.push(update);
+                handover.updates.push(item);
             else
-                handovers.set(accountId, { updates: [update], settled: Promise.resolve() });
-            return;
-        }
-        if (pending >= pendingLimit) {
-            warn?.(`[${accountId}] MAX webhook queue full (${pendingLimit}); dropping ${update.update_type}`);
+                handovers.set(accountId, { updates: [item], settled: Promise.resolve() });
             return;
         }
         pending += 1;
-        inbox.push(update);
+        inbox.push(item);
         wake?.();
     };
     const siblings = openQueues.get(accountId) ?? new Set();
-    siblings.add(push);
+    siblings.add(enqueue);
     openQueues.set(accountId, siblings);
+    const push = (update) => {
+        if (!closed && pending >= pendingLimit) {
+            warn?.(`[${accountId}] MAX webhook queue full (${pendingLimit}); dropping ${update.update_type}`);
+            return;
+        }
+        enqueue({ update });
+    };
+    const admit = async (update, dedupeKey) => {
+        const staleMs = staleMaxUpdateAgeMs(update, maxAgeMs, now());
+        if (staleMs !== undefined) {
+            warn?.(`[${accountId}] MAX webhook: ${update.update_type} from ${Math.round(staleMs / 60_000)} min ago skipped (older than maxEventAgeMinutes)`);
+            return 'stale';
+        }
+        if (journal && dedupeKey && journal.isDuplicate(dedupeKey))
+            return 'duplicate';
+        if (!closed && pending >= pendingLimit) {
+            if (overflow === 'reject') {
+                throw new MaxWebhookQueueRejectedError(`MAX webhook queue full (${pendingLimit} pending); ${update.update_type} refused for redelivery`);
+            }
+            warn?.(`[${accountId}] MAX webhook queue full (${pendingLimit}); dropping ${update.update_type}`);
+            return 'dropped';
+        }
+        const entry = journal ? await journal.append(update, dedupeKey) : undefined;
+        enqueue({ update, entry });
+        return 'queued';
+    };
+    const recover = async () => {
+        if (!journal)
+            return { recovered: 0, stale: 0, unreadable: 0 };
+        const { entries, unreadable } = await journal.readPending();
+        const recovered = [];
+        let stale = 0;
+        for (const entry of entries) {
+            if (staleMaxUpdateAgeMs(entry.update, maxAgeMs, now(), entry.receivedAt) !== undefined) {
+                stale += 1;
+                await journal.complete(entry);
+                continue;
+            }
+            recovered.push({ update: entry.update, entry });
+        }
+        if (recovered.length > 0) {
+            if (closed) {
+                for (const item of recovered)
+                    enqueue(item);
+            }
+            else {
+                // An earlier process accepted these before anything queued here.
+                inbox.unshift(...recovered);
+                pending += recovered.length;
+                wake?.();
+            }
+        }
+        return { recovered: recovered.length, stale, unreadable };
+    };
     /** Stop accepting and pass undispatched updates (lanes first, then inbox) on. */
     const close = (fromLanes, settled) => {
         if (closed)
             return;
         closed = true;
         wake = undefined;
-        siblings.delete(push);
+        siblings.delete(enqueue);
         if (siblings.size === 0 && openQueues.get(accountId) === siblings) {
             openQueues.delete(accountId);
         }
@@ -87,8 +176,8 @@ export function createMaxWebhookUpdateQueue(params) {
         const successor = [...siblings].at(-1);
         if (successor) {
             // A newer task of this account is already consuming: queue there.
-            for (const update of leftover)
-                successor(update);
+            for (const item of leftover)
+                successor(item);
             warn?.(`[${accountId}] MAX webhook stopped with ${leftover.length} update(s) not dispatched; moved to the running successor`);
             return;
         }
@@ -96,37 +185,73 @@ export function createMaxWebhookUpdateQueue(params) {
         handovers.set(accountId, { updates: [...leftover, ...late], settled });
         warn?.(`[${accountId}] MAX webhook stopped with ${leftover.length} update(s) not dispatched; handed over to the next start`);
     };
-    const consume = async ({ dispatch, abortSignal, onError, onWarn, }) => {
-        warn = onWarn;
+    const consume = async ({ dispatch, abortSignal, onError, onWarn, onInfo, }) => {
+        if (onWarn)
+            warn = onWarn;
         const lanes = new Map();
         const ready = [];
         const active = new Set();
         const inflight = new Set();
-        const route = (update) => {
-            const lane = maxWebhookUpdateLane(update);
+        const route = (item) => {
+            const lane = maxWebhookUpdateLane(item.update);
             const queued = lanes.get(lane);
             if (queued)
-                queued.push(update);
+                queued.push(item);
             else
-                lanes.set(lane, [update]);
+                lanes.set(lane, [item]);
             if (!active.has(lane) && !ready.includes(lane))
                 ready.push(lane);
         };
+        /** Back to the head of its lane, ahead of the chat's later updates; after the stop, passed on. */
+        const requeueFirst = (lane, item) => {
+            if (closed)
+                return enqueue(item);
+            pending += 1;
+            const queued = lanes.get(lane);
+            if (queued)
+                queued.unshift(item);
+            else
+                lanes.set(lane, [item]);
+        };
         const runLane = async (lane) => {
             try {
                 for (;;) {
                     if (abortSignal.aborted)
                         return;
-                    const update = lanes.get(lane)?.shift();
-                    if (!update)
+                    const item = lanes.get(lane)?.shift();
+                    if (!item)
                         return;
                     pending -= 1;
+                    const { entry } = item;
+                    let completion;
+                    // At core's turn adoption (core then owns crash recovery) or when the
+                    // dispatch returns, whichever is first. A failed turn is not replayed.
+                    const complete = () => (completion ??= entry && journal ? journal.complete(entry) : Promise.resolve());
                     try {
-                        await dispatch(update);
+                        await (entry
+                            ? runWithMaxTurnAdoption(complete, () => dispatch(item.update))
+                            : dispatch(item.update));
+                        if (item.refusals) {
+                            onInfo?.(`[${accountId}] MAX webhook: ${item.update.update_type} accepted after ${item.refusals} refusal(s) of the draining gateway`);
+                        }
                     }
                     catch (err) {
-                        onError(err, update);
+                        // Refused by the draining gateway before core adopted the turn: the
+                        // turn never started. The update stays at the head of its chat and
+                        // is retried after a pause; a stop meanwhile hands it over with the
+                        // leftovers and its journal row stays on disk for the next process.
+                        if (entry && !completion && isMaxGatewayDrainingError(err)) {
+                            item.refusals = (item.refusals ?? 0) + 1;
+                            if (item.refusals === 1) {
+                                warn?.(`[${accountId}] MAX webhook: the gateway is draining and refused ${item.update.update_type}; kept queued, retried until accepted or the channel stops (then after the restart)`);
+                            }
+                            requeueFirst(lane, item);
+                            await waitForMaxDrainRetry(item.refusals, abortSignal);
+                            continue;
+                        }
+                        onError(err, item.update);
                     }
+                    await complete();
                 }
             }
             finally {
@@ -183,7 +308,7 @@ export function createMaxWebhookUpdateQueue(params) {
             await waitAtMost(settled, stopGraceMs);
         }
     };
-    return { push, consume, close: () => close([], Promise.resolve()) };
+    return { admit, push, recover, consume, close: () => close([], Promise.resolve()) };
 }
 /** Resolves when `promise` settles, `ms` elapse or `signal` aborts — whichever is first. */
 async function waitAtMost(promise, ms, signal) {

package/dist/src/webhook-runner.js

@@ -8,8 +8,9 @@ import { channelReadyPatch } from 'openclaw/plugin-sdk/gateway-runtime';
 import { readSecretFile } from './accounts.js';
 import { dispatchUpdate } from './dispatch.js';
 import { MAX_SUBSCRIBED_UPDATE_TYPES, } from './monitor-types.js';
-import { registerMaxWebhookRoute, registerMaxWebhookTarget, resolveMaxWebhookPath, subscribeMaxWebhook, } from './webhook.js';
-import { createMaxWebhookUpdateQueue } from './webhook-queue.js';
+import { openMaxUpdateJournal } from './update-journal.js';
+import { maxUpdateDedupeKey, registerMaxWebhookRoute, registerMaxWebhookTarget, resolveMaxWebhookPath, subscribeMaxWebhook, } from './webhook.js';
+import { createMaxWebhookUpdateQueue, resolveMaxEventMaxAgeMs } from './webhook-queue.js';
 /** MAX secret format (SubscriptionRequestBody.secret): 5–256 of [A-Za-z0-9_-]. */
 const MAX_WEBHOOK_SECRET_PATTERN = /^[\w-]{5,256}$/;
 /**
@@ -26,6 +27,10 @@ export async function resolveMaxWebhookSecret(account, state) {
         }
         return secret;
     };
+    // A webhookSecret SecretRef that did not resolve never falls back to the
+    // file or a generated secret.
+    if (account.secretErrors?.webhookSecret)
+        throw new Error(account.secretErrors.webhookSecret);
     const configured = account.config.webhookSecret?.trim();
     if (configured)
         return validate(configured, 'webhookSecret');
@@ -151,19 +156,43 @@ export async function startMaxWebhook(opts) {
         lastTransportActivityAt: null,
     });
     // MAX requires HTTP 200 within 30s while agent runs regularly take minutes.
-    // The route handler acks and only enqueues; this account task dispatches
-    // (see webhook-queue.ts: dispatching from the request context fails with
-    // GatewayDrainingError once the request's work admission is released).
-    const queue = createMaxWebhookUpdateQueue({ accountId: account.accountId });
-    const onUpdate = (update) => {
+    // The route handler records and enqueues before the ack; this account task
+    // dispatches (see webhook-queue.ts: dispatching from the request context
+    // fails with GatewayDrainingError once the request's work admission is
+    // released).
+    const journal = await openWebhookJournal(opts);
+    const queueConfig = account.config.webhookQueue;
+    const queue = createMaxWebhookUpdateQueue({
+        accountId: account.accountId,
+        journal,
+        pendingLimit: queueConfig?.maxPending,
+        overflow: queueConfig?.overflow,
+        maxAgeMs: resolveMaxEventMaxAgeMs(account.config.maxEventAgeMinutes),
+        onWarn: (message) => log?.warn(message),
+    });
+    if (journal) {
+        // Before the route exists: what an earlier process accepted goes first.
+        try {
+            const { recovered, stale, unreadable } = await queue.recover();
+            if (recovered + stale + unreadable > 0) {
+                log?.warn(`[${account.accountId}] MAX webhook queue: ${recovered} update(s) accepted before the restart queued again, ${stale} stale skipped (maxEventAgeMinutes), ${unreadable} unreadable dropped`);
+            }
+        }
+        catch (err) {
+            log?.error(`[${account.accountId}] MAX webhook queue recovery failed: ${String(err)}`);
+        }
+    }
+    const onUpdate = async (update) => {
         const at = Date.now();
         statusSink?.(channelReadyPatch({
             lastConnectedAt: at,
             lastEventAt: at,
             mode: 'webhook',
         }));
-        queue.push(update);
-        return Promise.resolve();
+        const result = await queue.admit(update, maxUpdateDedupeKey(update));
+        if (result === 'duplicate') {
+            log?.debug?.(`[${account.accountId}] MAX webhook: duplicate ${update.update_type} skipped`);
+        }
     };
     const target = {
         account,
@@ -216,6 +245,7 @@ export async function startMaxWebhook(opts) {
         abortSignal,
         onError: (err, update) => log?.error(`[${account.accountId}] Webhook update dispatch failed (${update.update_type}): ${String(err)}`),
         onWarn: (message) => log?.warn(message),
+        onInfo: (message) => log?.info(message),
     });
     stopSubscriptionWatch();
     // The subscription is kept on purpose: a restart or config reload must not
@@ -227,6 +257,28 @@ export async function startMaxWebhook(opts) {
     statusSink?.({ mode: 'webhook', connected: false });
     log?.info(`[${account.accountId}] MAX webhook mode stopped (subscription kept)`);
 }
+/**
+ * The account's durable webhook journal, or undefined for the in-memory queue
+ * (webhookQueue.mode "memory", or the state directory is not writable).
+ */
+async function openWebhookJournal(opts) {
+    const { account, log } = opts;
+    if (account.config.webhookQueue?.mode === 'memory') {
+        log?.info(`[${account.accountId}] MAX webhook queue in memory (webhookQueue.mode "memory"): updates acknowledged but not yet handled are lost on restart`);
+        return undefined;
+    }
+    try {
+        return await openMaxUpdateJournal({
+            accountId: account.accountId,
+            warn: (message) => log?.warn(`[${account.accountId}] ${message}`),
+        });
+    }
+    catch (err) {
+        const code = err?.code;
+        log?.warn(`[${account.accountId}] MAX webhook durable queue unavailable (${typeof code === 'string' ? code : String(err)}); using the in-memory queue — updates acknowledged but not yet handled are lost on restart`);
+        return undefined;
+    }
+}
 /** MAX webhook secret: 5–256 chars of [A-Za-z0-9-]. */
 function generateWebhookSecret() {
     return randomBytes(24).toString('base64url').replace(/_/g, '-');