@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/discord/monitor/provider.lifecycle.js

@@ -0,0 +1,100 @@
+import { danger } from "../../globals.js";
+import { attachDiscordGatewayLogging } from "../gateway-logging.js";
+import { getDiscordGatewayEmitter, waitForDiscordGatewayStop } from "../monitor.gateway.js";
+import { registerGateway, unregisterGateway } from "./gateway-registry.js";
+export async function runDiscordGatewayLifecycle(params) {
+    const gateway = params.client.getPlugin("gateway");
+    if (gateway) {
+        registerGateway(params.accountId, gateway);
+    }
+    const gatewayEmitter = getDiscordGatewayEmitter(gateway);
+    const stopGatewayLogging = attachDiscordGatewayLogging({
+        emitter: gatewayEmitter,
+        runtime: params.runtime,
+    });
+    const onAbort = () => {
+        if (!gateway) {
+            return;
+        }
+        gatewayEmitter?.once("error", () => { });
+        gateway.options.reconnect = { maxAttempts: 0 };
+        gateway.disconnect();
+    };
+    if (params.abortSignal?.aborted) {
+        onAbort();
+    }
+    else {
+        params.abortSignal?.addEventListener("abort", onAbort, { once: true });
+    }
+    const HELLO_TIMEOUT_MS = 30000;
+    let helloTimeoutId;
+    const onGatewayDebug = (msg) => {
+        const message = String(msg);
+        if (!message.includes("WebSocket connection opened")) {
+            return;
+        }
+        if (helloTimeoutId) {
+            clearTimeout(helloTimeoutId);
+        }
+        helloTimeoutId = setTimeout(() => {
+            if (!gateway?.isConnected) {
+                params.runtime.log?.(danger(`connection stalled: no HELLO received within ${HELLO_TIMEOUT_MS}ms, forcing reconnect`));
+                gateway?.disconnect();
+                gateway?.connect(false);
+            }
+            helloTimeoutId = undefined;
+        }, HELLO_TIMEOUT_MS);
+    };
+    gatewayEmitter?.on("debug", onGatewayDebug);
+    let sawDisallowedIntents = false;
+    try {
+        if (params.execApprovalsHandler) {
+            await params.execApprovalsHandler.start();
+        }
+        await waitForDiscordGatewayStop({
+            gateway: gateway
+                ? {
+                    emitter: gatewayEmitter,
+                    disconnect: () => gateway.disconnect(),
+                }
+                : undefined,
+            abortSignal: params.abortSignal,
+            onGatewayError: (err) => {
+                if (params.isDisallowedIntentsError(err)) {
+                    sawDisallowedIntents = true;
+                    params.runtime.error?.(danger("discord: gateway closed with code 4014 (missing privileged gateway intents). Enable the required intents in the Discord Developer Portal or disable them in config."));
+                    return;
+                }
+                params.runtime.error?.(danger(`discord gateway error: ${String(err)}`));
+            },
+            shouldStopOnError: (err) => {
+                const message = String(err);
+                return (message.includes("Max reconnect attempts") ||
+                    message.includes("Fatal Gateway error") ||
+                    params.isDisallowedIntentsError(err));
+            },
+        });
+    }
+    catch (err) {
+        if (!sawDisallowedIntents && !params.isDisallowedIntentsError(err)) {
+            throw err;
+        }
+    }
+    finally {
+        unregisterGateway(params.accountId);
+        stopGatewayLogging();
+        if (helloTimeoutId) {
+            clearTimeout(helloTimeoutId);
+        }
+        gatewayEmitter?.removeListener("debug", onGatewayDebug);
+        params.abortSignal?.removeEventListener("abort", onAbort);
+        if (params.voiceManager) {
+            await params.voiceManager.destroy();
+            params.voiceManagerRef.current = null;
+        }
+        if (params.execApprovalsHandler) {
+            await params.execApprovalsHandler.stop();
+        }
+        params.threadBindings.stop();
+    }
+}

package/dist/discord/monitor/reply-delivery.js

@@ -1,8 +1,104 @@
+import { resolveAgentAvatar } from "../../agents/identity-avatar.js";
+import { loadConfig } from "../../config/config.js";
 import { convertMarkdownTables } from "../../markdown/tables.js";
 import { chunkDiscordTextWithMode } from "../chunk.js";
-import { sendMessageDiscord, sendVoiceMessageDiscord } from "../send.js";
+import { sendMessageDiscord, sendVoiceMessageDiscord, sendWebhookMessageDiscord } from "../send.js";
+function resolveTargetChannelId(target) {
+    if (!target.startsWith("channel:")) {
+        return undefined;
+    }
+    const channelId = target.slice("channel:".length).trim();
+    return channelId || undefined;
+}
+function resolveBoundThreadBinding(params) {
+    const sessionKey = params.sessionKey?.trim();
+    if (!params.threadBindings || !sessionKey) {
+        return undefined;
+    }
+    const bindings = params.threadBindings.listBySessionKey(sessionKey);
+    if (bindings.length === 0) {
+        return undefined;
+    }
+    const targetChannelId = resolveTargetChannelId(params.target);
+    if (!targetChannelId) {
+        return undefined;
+    }
+    return bindings.find((entry) => entry.threadId === targetChannelId);
+}
+function resolveBindingPersona(binding) {
+    if (!binding) {
+        return {};
+    }
+    const baseLabel = binding.label?.trim() || binding.agentId;
+    const username = (`🤖 ${baseLabel}`.trim() || "🤖 agent").slice(0, 80);
+    let avatarUrl;
+    try {
+        const avatar = resolveAgentAvatar(loadConfig(), binding.agentId);
+        if (avatar.kind === "remote") {
+            avatarUrl = avatar.url;
+        }
+    }
+    catch {
+        avatarUrl = undefined;
+    }
+    return { username, avatarUrl };
+}
+async function sendDiscordChunkWithFallback(params) {
+    const text = params.text.trim();
+    if (!text) {
+        return;
+    }
+    const binding = params.binding;
+    if (binding?.webhookId && binding?.webhookToken) {
+        try {
+            await sendWebhookMessageDiscord(text, {
+                webhookId: binding.webhookId,
+                webhookToken: binding.webhookToken,
+                accountId: binding.accountId,
+                threadId: binding.threadId,
+                replyTo: params.replyTo,
+                username: params.username,
+                avatarUrl: params.avatarUrl,
+            });
+            return;
+        }
+        catch {
+            // Fall through to the standard bot sender path.
+        }
+    }
+    await sendMessageDiscord(params.target, text, {
+        token: params.token,
+        rest: params.rest,
+        accountId: params.accountId,
+        replyTo: params.replyTo,
+    });
+}
 export async function deliverDiscordReply(params) {
     const chunkLimit = Math.min(params.textLimit, 2000);
+    const replyTo = params.replyToId?.trim() || undefined;
+    const replyToMode = params.replyToMode ?? "all";
+    // replyToMode=first should only apply to the first physical send.
+    const replyOnce = replyToMode === "first";
+    let replyUsed = false;
+    const resolveReplyTo = () => {
+        if (!replyTo) {
+            return undefined;
+        }
+        if (!replyOnce) {
+            return replyTo;
+        }
+        if (replyUsed) {
+            return undefined;
+        }
+        replyUsed = true;
+        return replyTo;
+    };
+    const binding = resolveBoundThreadBinding({
+        threadBindings: params.threadBindings,
+        sessionKey: params.sessionKey,
+        target: params.target,
+    });
+    const persona = resolveBindingPersona(binding);
     for (const payload of params.replies) {
         const mediaList = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
         const rawText = payload.text ?? "";
@@ -11,7 +107,6 @@ export async function deliverDiscordReply(params) {
         if (!text && mediaList.length === 0) {
             continue;
         }
-        const replyTo = params.replyToId?.trim() || undefined;
         if (mediaList.length === 0) {
             const mode = params.chunkMode ?? "length";
             const chunks = chunkDiscordTextWithMode(text, {
@@ -23,15 +118,20 @@ export async function deliverDiscordReply(params) {
                 chunks.push(text);
             }
             for (const chunk of chunks) {
-                const trimmed = chunk.trim();
-                if (!trimmed) {
+                if (!chunk.trim()) {
                     continue;
                 }
-                await sendMessageDiscord(params.target, trimmed, {
+                const replyTo = resolveReplyTo();
+                await sendDiscordChunkWithFallback({
+                    target: params.target,
+                    text: chunk,
                     token: params.token,
                     rest: params.rest,
                     accountId: params.accountId,
                     replyTo,
+                    binding,
+                    username: persona.username,
+                    avatarUrl: persona.avatarUrl,
                 });
             }
             continue;
@@ -40,25 +140,30 @@ export async function deliverDiscordReply(params) {
         if (!firstMedia) {
             continue;
         }
-        // Voice message path: audioAsVoice flag routes through sendVoiceMessageDiscord
+        // Voice message path: audioAsVoice flag routes through sendVoiceMessageDiscord.
         if (payload.audioAsVoice) {
+            const replyTo = resolveReplyTo();
             await sendVoiceMessageDiscord(params.target, firstMedia, {
                 token: params.token,
                 rest: params.rest,
                 accountId: params.accountId,
                 replyTo,
             });
-            // Voice messages cannot include text; send remaining text separately if present
-            if (text.trim()) {
-                await sendMessageDiscord(params.target, text, {
-                    token: params.token,
-                    rest: params.rest,
-                    accountId: params.accountId,
-                    replyTo,
-                });
-            }
-            // Additional media items are sent as regular attachments (voice is single-file only)
+            // Voice messages cannot include text; send remaining text separately if present.
+            await sendDiscordChunkWithFallback({
+                target: params.target,
+                text,
+                token: params.token,
+                rest: params.rest,
+                accountId: params.accountId,
+                replyTo: resolveReplyTo(),
+                binding,
+                username: persona.username,
+                avatarUrl: persona.avatarUrl,
+            });
+            // Additional media items are sent as regular attachments (voice is single-file only).
             for (const extra of mediaList.slice(1)) {
+                const replyTo = resolveReplyTo();
                 await sendMessageDiscord(params.target, "", {
                     token: params.token,
                     rest: params.rest,
@@ -69,6 +174,7 @@ export async function deliverDiscordReply(params) {
             }
             continue;
         }
+        const replyTo = resolveReplyTo();
         await sendMessageDiscord(params.target, text, {
             token: params.token,
             rest: params.rest,
@@ -77,6 +183,7 @@ export async function deliverDiscordReply(params) {
             replyTo,
         });
         for (const extra of mediaList.slice(1)) {
+            const replyTo = resolveReplyTo();
             await sendMessageDiscord(params.target, "", {
                 token: params.token,
                 rest: params.rest,

package/dist/discord/monitor/thread-bindings.discord-api.js

@@ -0,0 +1,215 @@
+import { ChannelType, Routes } from "discord-api-types/v10";
+import { logVerbose } from "../../globals.js";
+import { createDiscordRestClient } from "../client.js";
+import { sendMessageDiscord, sendWebhookMessageDiscord } from "../send.js";
+import { createThreadDiscord } from "../send.messages.js";
+import { summarizeBindingPersona } from "./thread-bindings.messages.js";
+import { BINDINGS_BY_THREAD_ID, REUSABLE_WEBHOOKS_BY_ACCOUNT_CHANNEL, rememberReusableWebhook, toReusableWebhookKey, } from "./thread-bindings.state.js";
+import { DISCORD_UNKNOWN_CHANNEL_ERROR_CODE, } from "./thread-bindings.types.js";
+function buildThreadTarget(threadId) {
+    return `channel:${threadId}`;
+}
+export function isThreadArchived(raw) {
+    if (!raw || typeof raw !== "object") {
+        return false;
+    }
+    const asRecord = raw;
+    if (asRecord.archived === true) {
+        return true;
+    }
+    if (asRecord.thread_metadata?.archived === true) {
+        return true;
+    }
+    if (asRecord.threadMetadata?.archived === true) {
+        return true;
+    }
+    return false;
+}
+function isThreadChannelType(type) {
+    return (type === ChannelType.PublicThread ||
+        type === ChannelType.PrivateThread ||
+        type === ChannelType.AnnouncementThread);
+}
+export function summarizeDiscordError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "string") {
+        return err;
+    }
+    if (typeof err === "number" ||
+        typeof err === "boolean" ||
+        typeof err === "bigint" ||
+        typeof err === "symbol") {
+        return String(err);
+    }
+    return "error";
+}
+function extractNumericDiscordErrorValue(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        return Number(value);
+    }
+    return undefined;
+}
+function extractDiscordErrorStatus(err) {
+    if (!err || typeof err !== "object") {
+        return undefined;
+    }
+    const candidate = err;
+    return (extractNumericDiscordErrorValue(candidate.status) ??
+        extractNumericDiscordErrorValue(candidate.statusCode) ??
+        extractNumericDiscordErrorValue(candidate.response?.status));
+}
+function extractDiscordErrorCode(err) {
+    if (!err || typeof err !== "object") {
+        return undefined;
+    }
+    const candidate = err;
+    return (extractNumericDiscordErrorValue(candidate.code) ??
+        extractNumericDiscordErrorValue(candidate.rawError?.code) ??
+        extractNumericDiscordErrorValue(candidate.body?.code) ??
+        extractNumericDiscordErrorValue(candidate.response?.body?.code) ??
+        extractNumericDiscordErrorValue(candidate.response?.data?.code));
+}
+export function isDiscordThreadGoneError(err) {
+    const code = extractDiscordErrorCode(err);
+    if (code === DISCORD_UNKNOWN_CHANNEL_ERROR_CODE) {
+        return true;
+    }
+    const status = extractDiscordErrorStatus(err);
+    // 404: deleted/unknown channel. 403: bot no longer has access.
+    return status === 404 || status === 403;
+}
+export async function maybeSendBindingMessage(params) {
+    const text = params.text.trim();
+    if (!text) {
+        return;
+    }
+    const record = params.record;
+    if (params.preferWebhook !== false && record.webhookId && record.webhookToken) {
+        try {
+            await sendWebhookMessageDiscord(text, {
+                webhookId: record.webhookId,
+                webhookToken: record.webhookToken,
+                accountId: record.accountId,
+                threadId: record.threadId,
+                username: summarizeBindingPersona(record),
+            });
+            return;
+        }
+        catch (err) {
+            logVerbose(`discord thread binding webhook send failed: ${summarizeDiscordError(err)}`);
+        }
+    }
+    try {
+        await sendMessageDiscord(buildThreadTarget(record.threadId), text, {
+            accountId: record.accountId,
+        });
+    }
+    catch (err) {
+        logVerbose(`discord thread binding fallback send failed: ${summarizeDiscordError(err)}`);
+    }
+}
+export async function createWebhookForChannel(params) {
+    try {
+        const rest = createDiscordRestClient({
+            accountId: params.accountId,
+            token: params.token,
+        }).rest;
+        const created = (await rest.post(Routes.channelWebhooks(params.channelId), {
+            body: {
+                name: "Pool Bot Agents",
+            },
+        }));
+        const webhookId = typeof created?.id === "string" ? created.id.trim() : "";
+        const webhookToken = typeof created?.token === "string" ? created.token.trim() : "";
+        if (!webhookId || !webhookToken) {
+            return {};
+        }
+        return { webhookId, webhookToken };
+    }
+    catch (err) {
+        logVerbose(`discord thread binding webhook create failed for ${params.channelId}: ${summarizeDiscordError(err)}`);
+        return {};
+    }
+}
+export function findReusableWebhook(params) {
+    const reusableKey = toReusableWebhookKey({
+        accountId: params.accountId,
+        channelId: params.channelId,
+    });
+    const cached = REUSABLE_WEBHOOKS_BY_ACCOUNT_CHANNEL.get(reusableKey);
+    if (cached) {
+        return {
+            webhookId: cached.webhookId,
+            webhookToken: cached.webhookToken,
+        };
+    }
+    for (const record of BINDINGS_BY_THREAD_ID.values()) {
+        if (record.accountId !== params.accountId) {
+            continue;
+        }
+        if (record.channelId !== params.channelId) {
+            continue;
+        }
+        if (!record.webhookId || !record.webhookToken) {
+            continue;
+        }
+        rememberReusableWebhook(record);
+        return {
+            webhookId: record.webhookId,
+            webhookToken: record.webhookToken,
+        };
+    }
+    return {};
+}
+export async function resolveChannelIdForBinding(params) {
+    const explicit = params.channelId?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    try {
+        const rest = createDiscordRestClient({
+            accountId: params.accountId,
+            token: params.token,
+        }).rest;
+        const channel = (await rest.get(Routes.channel(params.threadId)));
+        const channelId = typeof channel?.id === "string" ? channel.id.trim() : "";
+        const type = channel?.type;
+        const parentId = typeof channel?.parent_id === "string"
+            ? channel.parent_id.trim()
+            : typeof channel?.parentId === "string"
+                ? channel.parentId.trim()
+                : "";
+        // Only thread channels should resolve to their parent channel.
+        // Non-thread channels (text/forum/media) must keep their own ID.
+        if (parentId && isThreadChannelType(type)) {
+            return parentId;
+        }
+        return channelId || null;
+    }
+    catch (err) {
+        logVerbose(`discord thread binding channel resolve failed for ${params.threadId}: ${summarizeDiscordError(err)}`);
+        return null;
+    }
+}
+export async function createThreadForBinding(params) {
+    try {
+        const created = (await createThreadDiscord(params.channelId, {
+            name: params.threadName,
+            autoArchiveMinutes: 60,
+        }, {
+            accountId: params.accountId,
+            token: params.token,
+        }));
+        const createdId = typeof created?.id === "string" ? created.id.trim() : "";
+        return createdId || null;
+    }
+    catch (err) {
+        logVerbose(`discord thread binding auto-thread create failed for ${params.channelId}: ${summarizeDiscordError(err)}`);
+        return null;
+    }
+}

package/dist/discord/monitor/thread-bindings.js

@@ -0,0 +1,4 @@
+export { formatThreadBindingTtlLabel, resolveThreadBindingIntroText, resolveThreadBindingThreadName, } from "./thread-bindings.messages.js";
+export { isRecentlyUnboundThreadWebhookMessage } from "./thread-bindings.state.js";
+export { autoBindSpawnedDiscordSubagent, listThreadBindingsBySessionKey, listThreadBindingsForAccount, setThreadBindingTtlBySessionKey, unbindThreadBindingsBySessionKey, } from "./thread-bindings.lifecycle.js";
+export { __testing, createNoopThreadBindingManager, createThreadBindingManager, getThreadBindingManager, } from "./thread-bindings.manager.js";

package/dist/discord/monitor/thread-bindings.lifecycle.js

@@ -0,0 +1,177 @@
+import { normalizeAccountId } from "../../routing/session-key.js";
+import { parseDiscordTarget } from "../targets.js";
+import { resolveChannelIdForBinding } from "./thread-bindings.discord-api.js";
+import { getThreadBindingManager } from "./thread-bindings.manager.js";
+import { resolveThreadBindingIntroText, resolveThreadBindingThreadName, } from "./thread-bindings.messages.js";
+import { BINDINGS_BY_THREAD_ID, MANAGERS_BY_ACCOUNT_ID, ensureBindingsLoaded, getThreadBindingToken, normalizeThreadBindingTtlMs, normalizeThreadId, rememberRecentUnboundWebhookEcho, removeBindingRecord, resolveBindingIdsForSession, saveBindingsToDisk, setBindingRecord, shouldPersistBindingMutations, } from "./thread-bindings.state.js";
+export function listThreadBindingsForAccount(accountId) {
+    const manager = getThreadBindingManager(accountId);
+    if (!manager) {
+        return [];
+    }
+    return manager.listBindings();
+}
+export function listThreadBindingsBySessionKey(params) {
+    ensureBindingsLoaded();
+    const targetSessionKey = params.targetSessionKey.trim();
+    if (!targetSessionKey) {
+        return [];
+    }
+    const accountId = params.accountId ? normalizeAccountId(params.accountId) : undefined;
+    const ids = resolveBindingIdsForSession({
+        targetSessionKey,
+        accountId,
+        targetKind: params.targetKind,
+    });
+    return ids
+        .map((bindingKey) => BINDINGS_BY_THREAD_ID.get(bindingKey))
+        .filter((entry) => Boolean(entry));
+}
+export async function autoBindSpawnedDiscordSubagent(params) {
+    const channel = params.channel?.trim().toLowerCase();
+    if (channel !== "discord") {
+        return null;
+    }
+    const manager = getThreadBindingManager(params.accountId);
+    if (!manager) {
+        return null;
+    }
+    const managerToken = getThreadBindingToken(manager.accountId);
+    const requesterThreadId = normalizeThreadId(params.threadId);
+    let channelId = "";
+    if (requesterThreadId) {
+        const existing = manager.getByThreadId(requesterThreadId);
+        if (existing?.channelId?.trim()) {
+            channelId = existing.channelId.trim();
+        }
+        else {
+            channelId =
+                (await resolveChannelIdForBinding({
+                    accountId: manager.accountId,
+                    token: managerToken,
+                    threadId: requesterThreadId,
+                })) ?? "";
+        }
+    }
+    if (!channelId) {
+        const to = params.to?.trim() || "";
+        if (!to) {
+            return null;
+        }
+        try {
+            const target = parseDiscordTarget(to, { defaultKind: "channel" });
+            if (!target || target.kind !== "channel") {
+                return null;
+            }
+            channelId =
+                (await resolveChannelIdForBinding({
+                    accountId: manager.accountId,
+                    token: managerToken,
+                    threadId: target.id,
+                })) ?? "";
+        }
+        catch {
+            return null;
+        }
+    }
+    return await manager.bindTarget({
+        threadId: undefined,
+        channelId,
+        createThread: true,
+        threadName: resolveThreadBindingThreadName({
+            agentId: params.agentId,
+            label: params.label,
+        }),
+        targetKind: "subagent",
+        targetSessionKey: params.childSessionKey,
+        agentId: params.agentId,
+        label: params.label,
+        boundBy: params.boundBy ?? "system",
+        introText: resolveThreadBindingIntroText({
+            agentId: params.agentId,
+            label: params.label,
+            sessionTtlMs: manager.getSessionTtlMs(),
+        }),
+    });
+}
+export function unbindThreadBindingsBySessionKey(params) {
+    ensureBindingsLoaded();
+    const targetSessionKey = params.targetSessionKey.trim();
+    if (!targetSessionKey) {
+        return [];
+    }
+    const accountId = params.accountId ? normalizeAccountId(params.accountId) : undefined;
+    const ids = resolveBindingIdsForSession({
+        targetSessionKey,
+        accountId,
+        targetKind: params.targetKind,
+    });
+    if (ids.length === 0) {
+        return [];
+    }
+    const removed = [];
+    for (const bindingKey of ids) {
+        const record = BINDINGS_BY_THREAD_ID.get(bindingKey);
+        if (!record) {
+            continue;
+        }
+        const manager = MANAGERS_BY_ACCOUNT_ID.get(record.accountId);
+        if (manager) {
+            const unbound = manager.unbindThread({
+                threadId: record.threadId,
+                reason: params.reason,
+                sendFarewell: params.sendFarewell,
+                farewellText: params.farewellText,
+            });
+            if (unbound) {
+                removed.push(unbound);
+            }
+            continue;
+        }
+        const unbound = removeBindingRecord(bindingKey);
+        if (unbound) {
+            rememberRecentUnboundWebhookEcho(unbound);
+            removed.push(unbound);
+        }
+    }
+    if (removed.length > 0 && shouldPersistBindingMutations()) {
+        saveBindingsToDisk({ force: true });
+    }
+    return removed;
+}
+export function setThreadBindingTtlBySessionKey(params) {
+    ensureBindingsLoaded();
+    const targetSessionKey = params.targetSessionKey.trim();
+    if (!targetSessionKey) {
+        return [];
+    }
+    const accountId = params.accountId ? normalizeAccountId(params.accountId) : undefined;
+    const ids = resolveBindingIdsForSession({
+        targetSessionKey,
+        accountId,
+    });
+    if (ids.length === 0) {
+        return [];
+    }
+    const ttlMs = normalizeThreadBindingTtlMs(params.ttlMs);
+    const now = Date.now();
+    const expiresAt = ttlMs > 0 ? now + ttlMs : 0;
+    const updated = [];
+    for (const bindingKey of ids) {
+        const existing = BINDINGS_BY_THREAD_ID.get(bindingKey);
+        if (!existing) {
+            continue;
+        }
+        const nextRecord = {
+            ...existing,
+            boundAt: now,
+            expiresAt,
+        };
+        setBindingRecord(nextRecord);
+        updated.push(nextRecord);
+    }
+    if (updated.length > 0 && shouldPersistBindingMutations()) {
+        saveBindingsToDisk({ force: true });
+    }
+    return updated;
+}