@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/gateway/server-methods/nodes.js

@@ -1,36 +1,182 @@
-import { approveNodePairing, listNodePairing, rejectNodePairing, renamePairedNode, requestNodePairing, verifyNodeToken, } from "../../infra/node-pairing.js";
-import { listDevicePairing } from "../../infra/device-pairing.js";
-import { ErrorCodes, errorShape, validateNodeDescribeParams, validateNodeEventParams, validateNodeInvokeParams, validateNodeInvokeResultParams, validateNodeListParams, validateNodePairApproveParams, validateNodePairListParams, validateNodePairRejectParams, validateNodePairRequestParams, validateNodePairVerifyParams, validateNodeRenameParams, } from "../protocol/index.js";
-import { respondInvalidParams, respondUnavailableOnThrow, safeParseJson, uniqueSortedStrings, } from "./nodes.helpers.js";
 import { loadConfig } from "../../config/config.js";
+import { listDevicePairing } from "../../infra/device-pairing.js";
+import { approveNodePairing, listNodePairing, rejectNodePairing, renamePairedNode, requestNodePairing, verifyNodeToken, } from "../../infra/node-pairing.js";
+import { loadApnsRegistration, resolveApnsAuthConfigFromEnv, sendApnsAlert, sendApnsBackgroundWake, } from "../../infra/push-apns.js";
 import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
+import { sanitizeNodeInvokeParamsForForwarding } from "../node-invoke-sanitize.js";
+import { ErrorCodes, errorShape, validateNodeDescribeParams, validateNodeEventParams, validateNodeInvokeParams, validateNodeListParams, validateNodePairApproveParams, validateNodePairListParams, validateNodePairRejectParams, validateNodePairRequestParams, validateNodePairVerifyParams, validateNodeRenameParams, } from "../protocol/index.js";
+import { handleNodeInvokeResult } from "./nodes.handlers.invoke-result.js";
+import { respondInvalidParams, respondUnavailableOnNodeInvokeError, respondUnavailableOnThrow, safeParseJson, uniqueSortedStrings, } from "./nodes.helpers.js";
+const NODE_WAKE_RECONNECT_WAIT_MS = 3_000;
+const NODE_WAKE_RECONNECT_RETRY_WAIT_MS = 12_000;
+const NODE_WAKE_RECONNECT_POLL_MS = 150;
+const NODE_WAKE_THROTTLE_MS = 15_000;
+const NODE_WAKE_NUDGE_THROTTLE_MS = 10 * 60_000;
+const nodeWakeById = new Map();
+const nodeWakeNudgeById = new Map();
 function isNodeEntry(entry) {
-    if (entry.clientMode === "node")
+    if (entry.role === "node") {
         return true;
-    if (entry.role === "node")
-        return true;
-    if (Array.isArray(entry.roles) && entry.roles.includes("node"))
+    }
+    if (Array.isArray(entry.roles) && entry.roles.includes("node")) {
         return true;
+    }
     return false;
 }
-function normalizeNodeInvokeResultParams(params) {
-    if (!params || typeof params !== "object")
-        return params;
-    const raw = params;
-    const normalized = { ...raw };
-    if (normalized.payloadJSON === null) {
-        delete normalized.payloadJSON;
+async function delayMs(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function maybeWakeNodeWithApns(nodeId, opts) {
+    const state = nodeWakeById.get(nodeId) ?? { lastWakeAtMs: 0 };
+    nodeWakeById.set(nodeId, state);
+    if (state.inFlight) {
+        return await state.inFlight;
+    }
+    const now = Date.now();
+    const force = opts?.force === true;
+    if (!force && state.lastWakeAtMs > 0 && now - state.lastWakeAtMs < NODE_WAKE_THROTTLE_MS) {
+        return { available: true, throttled: true, path: "throttled", durationMs: 0 };
+    }
+    state.inFlight = (async () => {
+        const startedAtMs = Date.now();
+        const withDuration = (attempt) => ({
+            ...attempt,
+            durationMs: Math.max(0, Date.now() - startedAtMs),
+        });
+        try {
+            const registration = await loadApnsRegistration(nodeId);
+            if (!registration) {
+                return withDuration({ available: false, throttled: false, path: "no-registration" });
+            }
+            const auth = await resolveApnsAuthConfigFromEnv(process.env);
+            if (!auth.ok) {
+                return withDuration({
+                    available: false,
+                    throttled: false,
+                    path: "no-auth",
+                    apnsReason: auth.error,
+                });
+            }
+            state.lastWakeAtMs = Date.now();
+            const wakeResult = await sendApnsBackgroundWake({
+                auth: auth.value,
+                registration,
+                nodeId,
+                wakeReason: "node.invoke",
+            });
+            if (!wakeResult.ok) {
+                return withDuration({
+                    available: true,
+                    throttled: false,
+                    path: "send-error",
+                    apnsStatus: wakeResult.status,
+                    apnsReason: wakeResult.reason,
+                });
+            }
+            return withDuration({
+                available: true,
+                throttled: false,
+                path: "sent",
+                apnsStatus: wakeResult.status,
+                apnsReason: wakeResult.reason,
+            });
+        }
+        catch (err) {
+            // Best-effort wake only.
+            const message = err instanceof Error ? err.message : String(err);
+            if (state.lastWakeAtMs === 0) {
+                return withDuration({
+                    available: false,
+                    throttled: false,
+                    path: "send-error",
+                    apnsReason: message,
+                });
+            }
+            return withDuration({
+                available: true,
+                throttled: false,
+                path: "send-error",
+                apnsReason: message,
+            });
+        }
+    })();
+    try {
+        return await state.inFlight;
+    }
+    finally {
+        state.inFlight = undefined;
+    }
+}
+async function maybeSendNodeWakeNudge(nodeId) {
+    const startedAtMs = Date.now();
+    const withDuration = (attempt) => ({
+        ...attempt,
+        durationMs: Math.max(0, Date.now() - startedAtMs),
+    });
+    const lastNudgeAtMs = nodeWakeNudgeById.get(nodeId) ?? 0;
+    if (lastNudgeAtMs > 0 && Date.now() - lastNudgeAtMs < NODE_WAKE_NUDGE_THROTTLE_MS) {
+        return withDuration({ sent: false, throttled: true, reason: "throttled" });
+    }
+    const registration = await loadApnsRegistration(nodeId);
+    if (!registration) {
+        return withDuration({ sent: false, throttled: false, reason: "no-registration" });
+    }
+    const auth = await resolveApnsAuthConfigFromEnv(process.env);
+    if (!auth.ok) {
+        return withDuration({
+            sent: false,
+            throttled: false,
+            reason: "no-auth",
+            apnsReason: auth.error,
+        });
     }
-    else if (normalized.payloadJSON !== undefined && typeof normalized.payloadJSON !== "string") {
-        if (normalized.payload === undefined) {
-            normalized.payload = normalized.payloadJSON;
+    try {
+        const result = await sendApnsAlert({
+            auth: auth.value,
+            registration,
+            nodeId,
+            title: "Pool Bot needs a quick reopen",
+            body: "Tap to reopen Pool Bot and restore the node connection.",
+        });
+        if (!result.ok) {
+            return withDuration({
+                sent: false,
+                throttled: false,
+                reason: "apns-not-ok",
+                apnsStatus: result.status,
+                apnsReason: result.reason,
+            });
         }
-        delete normalized.payloadJSON;
+        nodeWakeNudgeById.set(nodeId, Date.now());
+        return withDuration({
+            sent: true,
+            throttled: false,
+            reason: "sent",
+            apnsStatus: result.status,
+            apnsReason: result.reason,
+        });
     }
-    if (normalized.error === null) {
-        delete normalized.error;
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return withDuration({
+            sent: false,
+            throttled: false,
+            reason: "send-error",
+            apnsReason: message,
+        });
+    }
+}
+async function waitForNodeReconnect(params) {
+    const timeoutMs = Math.max(250, params.timeoutMs ?? NODE_WAKE_RECONNECT_WAIT_MS);
+    const pollMs = Math.max(50, params.pollMs ?? NODE_WAKE_RECONNECT_POLL_MS);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (params.context.nodeRegistry.get(params.nodeId)) {
+            return true;
+        }
+        await delayMs(pollMs);
     }
-    return normalized;
+    return Boolean(params.context.nodeRegistry.get(params.nodeId));
 }
 export const nodeHandlers = {
     "node.pair.request": async ({ params, respond, context }) => {
@@ -227,14 +373,17 @@ export const nodeHandlers = {
                 };
             });
             nodes.sort((a, b) => {
-                if (a.connected !== b.connected)
+                if (a.connected !== b.connected) {
                     return a.connected ? -1 : 1;
+                }
                 const an = (a.displayName ?? a.nodeId).toLowerCase();
                 const bn = (b.displayName ?? b.nodeId).toLowerCase();
-                if (an < bn)
+                if (an < bn) {
                     return -1;
-                if (an > bn)
+                }
+                if (an > bn) {
                     return 1;
+                }
                 return a.nodeId.localeCompare(b.nodeId);
             });
             respond(true, { ts: Date.now(), nodes }, undefined);
@@ -287,7 +436,7 @@ export const nodeHandlers = {
             }, undefined);
         });
     },
-    "node.invoke": async ({ params, respond, context }) => {
+    "node.invoke": async ({ params, respond, context, client, req }) => {
         if (!validateNodeInvokeParams(params)) {
             respondInvalidParams({
                 respond,
@@ -303,13 +452,69 @@ export const nodeHandlers = {
             respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId and command required"));
             return;
         }
+        if (command === "system.execApprovals.get" || command === "system.execApprovals.set") {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "node.invoke does not allow system.execApprovals.*; use exec.approvals.node.*", { details: { command } }));
+            return;
+        }
         await respondUnavailableOnThrow(respond, async () => {
-            const nodeSession = context.nodeRegistry.get(nodeId);
+            let nodeSession = context.nodeRegistry.get(nodeId);
             if (!nodeSession) {
-                respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "node not connected", {
-                    details: { code: "NOT_CONNECTED" },
-                }));
-                return;
+                const wakeReqId = req.id;
+                const wakeFlowStartedAtMs = Date.now();
+                context.logGateway.info(`node wake start node=${nodeId} req=${wakeReqId} command=${command}`);
+                const wake = await maybeWakeNodeWithApns(nodeId);
+                context.logGateway.info(`node wake stage=wake1 node=${nodeId} req=${wakeReqId} ` +
+                    `available=${wake.available} throttled=${wake.throttled} ` +
+                    `path=${wake.path} durationMs=${wake.durationMs} ` +
+                    `apnsStatus=${wake.apnsStatus ?? -1} apnsReason=${wake.apnsReason ?? "-"}`);
+                if (wake.available) {
+                    const waitStartedAtMs = Date.now();
+                    const waitTimeoutMs = NODE_WAKE_RECONNECT_WAIT_MS;
+                    const reconnected = await waitForNodeReconnect({
+                        nodeId,
+                        context,
+                        timeoutMs: waitTimeoutMs,
+                    });
+                    const waitDurationMs = Math.max(0, Date.now() - waitStartedAtMs);
+                    context.logGateway.info(`node wake stage=wait1 node=${nodeId} req=${wakeReqId} ` +
+                        `reconnected=${reconnected} timeoutMs=${waitTimeoutMs} durationMs=${waitDurationMs}`);
+                }
+                nodeSession = context.nodeRegistry.get(nodeId);
+                if (!nodeSession && wake.available) {
+                    const retryWake = await maybeWakeNodeWithApns(nodeId, { force: true });
+                    context.logGateway.info(`node wake stage=wake2 node=${nodeId} req=${wakeReqId} force=true ` +
+                        `available=${retryWake.available} throttled=${retryWake.throttled} ` +
+                        `path=${retryWake.path} durationMs=${retryWake.durationMs} ` +
+                        `apnsStatus=${retryWake.apnsStatus ?? -1} apnsReason=${retryWake.apnsReason ?? "-"}`);
+                    if (retryWake.available) {
+                        const waitStartedAtMs = Date.now();
+                        const waitTimeoutMs = NODE_WAKE_RECONNECT_RETRY_WAIT_MS;
+                        const reconnected = await waitForNodeReconnect({
+                            nodeId,
+                            context,
+                            timeoutMs: waitTimeoutMs,
+                        });
+                        const waitDurationMs = Math.max(0, Date.now() - waitStartedAtMs);
+                        context.logGateway.info(`node wake stage=wait2 node=${nodeId} req=${wakeReqId} ` +
+                            `reconnected=${reconnected} timeoutMs=${waitTimeoutMs} durationMs=${waitDurationMs}`);
+                    }
+                    nodeSession = context.nodeRegistry.get(nodeId);
+                }
+                if (!nodeSession) {
+                    const totalDurationMs = Math.max(0, Date.now() - wakeFlowStartedAtMs);
+                    const nudge = await maybeSendNodeWakeNudge(nodeId);
+                    context.logGateway.info(`node wake nudge node=${nodeId} req=${wakeReqId} sent=${nudge.sent} ` +
+                        `throttled=${nudge.throttled} reason=${nudge.reason} durationMs=${nudge.durationMs} ` +
+                        `apnsStatus=${nudge.apnsStatus ?? -1} apnsReason=${nudge.apnsReason ?? "-"}`);
+                    context.logGateway.warn(`node wake done node=${nodeId} req=${wakeReqId} connected=false ` +
+                        `reason=not_connected totalMs=${totalDurationMs}`);
+                    respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "node not connected", {
+                        details: { code: "NOT_CONNECTED" },
+                    }));
+                    return;
+                }
+                const totalDurationMs = Math.max(0, Date.now() - wakeFlowStartedAtMs);
+                context.logGateway.info(`node wake done node=${nodeId} req=${wakeReqId} connected=true totalMs=${totalDurationMs}`);
             }
             const cfg = loadConfig();
             const allowlist = resolveNodeCommandAllowlist(cfg, nodeSession);
@@ -324,17 +529,26 @@ export const nodeHandlers = {
                 }));
                 return;
             }
+            const forwardedParams = sanitizeNodeInvokeParamsForForwarding({
+                command,
+                rawParams: p.params,
+                client,
+                execApprovalManager: context.execApprovalManager,
+            });
+            if (!forwardedParams.ok) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, forwardedParams.message, {
+                    details: forwardedParams.details ?? null,
+                }));
+                return;
+            }
             const res = await context.nodeRegistry.invoke({
                 nodeId,
                 command,
-                params: p.params,
+                params: forwardedParams.params,
                 timeoutMs: p.timeoutMs,
                 idempotencyKey: p.idempotencyKey,
             });
-            if (!res.ok) {
-                respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-                    details: { nodeError: res.error ?? null },
-                }));
+            if (!respondUnavailableOnNodeInvokeError(respond, res)) {
                 return;
             }
             const payload = res.payloadJSON ? safeParseJson(res.payloadJSON) : res.payload;
@@ -347,39 +561,7 @@ export const nodeHandlers = {
             }, undefined);
         });
     },
-    "node.invoke.result": async ({ params, respond, context, client }) => {
-        const normalizedParams = normalizeNodeInvokeResultParams(params);
-        if (!validateNodeInvokeResultParams(normalizedParams)) {
-            respondInvalidParams({
-                respond,
-                method: "node.invoke.result",
-                validator: validateNodeInvokeResultParams,
-            });
-            return;
-        }
-        const p = normalizedParams;
-        const callerNodeId = client?.connect?.device?.id ?? client?.connect?.client?.id;
-        if (callerNodeId && callerNodeId !== p.nodeId) {
-            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId mismatch"));
-            return;
-        }
-        const ok = context.nodeRegistry.handleInvokeResult({
-            id: p.id,
-            nodeId: p.nodeId,
-            ok: p.ok,
-            payload: p.payload,
-            payloadJSON: p.payloadJSON ?? null,
-            error: p.error ?? null,
-        });
-        if (!ok) {
-            // Late-arriving results (after invoke timeout) are expected and harmless.
-            // Return success instead of error to reduce log noise; client can discard.
-            context.logGateway.debug(`late invoke result ignored: id=${p.id} node=${p.nodeId}`);
-            respond(true, { ok: true, ignored: true }, undefined);
-            return;
-        }
-        respond(true, { ok: true }, undefined);
-    },
+    "node.invoke.result": handleNodeInvokeResult,
     "node.event": async ({ params, respond, context, client }) => {
         if (!validateNodeEventParams(params)) {
             respondInvalidParams({

package/dist/gateway/server-methods/push.js

@@ -0,0 +1,53 @@
+import { loadApnsRegistration, normalizeApnsEnvironment, resolveApnsAuthConfigFromEnv, sendApnsAlert, } from "../../infra/push-apns.js";
+import { ErrorCodes, errorShape, validatePushTestParams } from "../protocol/index.js";
+import { respondInvalidParams, respondUnavailableOnThrow } from "./nodes.helpers.js";
+function normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export const pushHandlers = {
+    "push.test": async ({ params, respond }) => {
+        if (!validatePushTestParams(params)) {
+            respondInvalidParams({
+                respond,
+                method: "push.test",
+                validator: validatePushTestParams,
+            });
+            return;
+        }
+        const nodeId = String(params.nodeId ?? "").trim();
+        if (!nodeId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId required"));
+            return;
+        }
+        const title = normalizeOptionalString(params.title) ?? "Pool Bot";
+        const body = normalizeOptionalString(params.body) ?? `Push test for node ${nodeId}`;
+        await respondUnavailableOnThrow(respond, async () => {
+            const registration = await loadApnsRegistration(nodeId);
+            if (!registration) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `node ${nodeId} has no APNs registration (connect iOS node first)`));
+                return;
+            }
+            const auth = await resolveApnsAuthConfigFromEnv(process.env);
+            if (!auth.ok) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, auth.error));
+                return;
+            }
+            const overrideEnvironment = normalizeApnsEnvironment(params.environment);
+            const result = await sendApnsAlert({
+                auth: auth.value,
+                registration: {
+                    ...registration,
+                    environment: overrideEnvironment ?? registration.environment,
+                },
+                nodeId,
+                title,
+                body,
+            });
+            respond(true, result, undefined);
+        });
+    },
+};

package/dist/gateway/server-methods/sessions.js

@@ -6,8 +6,10 @@ import { stopSubagentsForRequester } from "../../auto-reply/reply/abort.js";
 import { clearSessionQueues } from "../../auto-reply/reply/queue.js";
 import { loadConfig } from "../../config/config.js";
 import { loadSessionStore, snapshotSessionOrigin, resolveMainSessionKey, updateSessionStore, } from "../../config/sessions.js";
+import { unbindThreadBindingsBySessionKey } from "../../discord/monitor/thread-bindings.js";
 import { createInternalHookEvent, triggerInternalHook } from "../../hooks/internal-hooks.js";
-import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-key.js";
+import { getGlobalHookRunner } from "../../plugins/hook-runner-global.js";
+import { isSubagentSessionKey, normalizeAgentId, parseAgentSessionKey, } from "../../routing/session-key.js";
 import { ErrorCodes, errorShape, validateSessionsCompactParams, validateSessionsDeleteParams, validateSessionsListParams, validateSessionsPatchParams, validateSessionsPreviewParams, validateSessionsResetParams, validateSessionsResolveParams, } from "../protocol/index.js";
 import { archiveFileOnDisk, archiveSessionTranscripts, listSessionsFromStore, loadCombinedSessionStoreForGateway, loadSessionEntry, pruneLegacyStoreKeys, readSessionPreviewItemsFromTranscript, resolveGatewaySessionStoreTarget, resolveSessionModelRef, resolveSessionTranscriptCandidates, } from "../session-utils.js";
 import { applySessionsPatchToStore } from "../sessions-patch.js";
@@ -33,6 +35,13 @@ function resolveGatewaySessionTargetFromKey(key) {
     const target = resolveGatewaySessionStoreTarget({ cfg, key });
     return { cfg, target, storePath: target.storePath };
 }
+function rejectWebchatSessionMutation(params) {
+    if (!params.client?.connect || !params.isWebchatConnect(params.client.connect)) {
+        return false;
+    }
+    params.respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `webchat clients cannot ${params.action} sessions; use chat.send for session-scoped updates`));
+    return true;
+}
 function migrateAndPruneSessionStoreKey(params) {
     const target = resolveGatewaySessionStoreTarget({
         cfg: params.cfg,
@@ -65,6 +74,31 @@ function archiveSessionTranscriptsForSession(params) {
         reason: params.reason,
     });
 }
+async function emitSessionUnboundLifecycleEvent(params) {
+    const targetKind = isSubagentSessionKey(params.targetSessionKey) ? "subagent" : "acp";
+    unbindThreadBindingsBySessionKey({
+        targetSessionKey: params.targetSessionKey,
+        targetKind,
+        reason: params.reason,
+        sendFarewell: true,
+    });
+    if (params.emitHooks === false) {
+        return;
+    }
+    const hookRunner = getGlobalHookRunner();
+    if (!hookRunner?.hasHooks("subagent_ended")) {
+        return;
+    }
+    await hookRunner.runSubagentEnded({
+        targetSessionKey: params.targetSessionKey,
+        targetKind,
+        reason: params.reason,
+        sendFarewell: true,
+        outcome: params.reason === "session-reset" ? "reset" : "deleted",
+    }, {
+        childSessionKey: params.targetSessionKey,
+    });
+}
 async function ensureSessionRuntimeCleanup(params) {
     const queueKeys = new Set(params.target.storeKeys);
     queueKeys.add(params.target.canonicalKey);
@@ -161,7 +195,7 @@ export const sessionsHandlers = {
         }
         respond(true, { ok: true, key: resolved.key }, undefined);
     },
-    "sessions.patch": async ({ params, respond, context }) => {
+    "sessions.patch": async ({ params, respond, context, client, isWebchatConnect }) => {
         if (!assertValidParams(params, validateSessionsPatchParams, "sessions.patch", respond)) {
             return;
         }
@@ -170,6 +204,9 @@ export const sessionsHandlers = {
         if (!key) {
             return;
         }
+        if (rejectWebchatSessionMutation({ action: "patch", client, isWebchatConnect, respond })) {
+            return;
+        }
         const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
         const applied = await updateSessionStore(storePath, async (store) => {
             const { primaryKey } = migrateAndPruneSessionStoreKey({ cfg, key, store });
@@ -211,6 +248,7 @@ export const sessionsHandlers = {
         }
         const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
         const { entry } = loadSessionEntry(key);
+        const hadExistingEntry = Boolean(entry);
         const commandReason = p.reason === "new" ? "new" : "reset";
         const hookEvent = createInternalHookEvent("command", commandReason, target.canonicalKey ?? key, {
             sessionEntry: entry,
@@ -267,9 +305,15 @@ export const sessionsHandlers = {
             agentId: target.agentId,
             reason: "reset",
         });
+        if (hadExistingEntry) {
+            await emitSessionUnboundLifecycleEvent({
+                targetSessionKey: target.canonicalKey ?? key,
+                reason: "session-reset",
+            });
+        }
         respond(true, { ok: true, key: target.canonicalKey, entry: next }, undefined);
     },
-    "sessions.delete": async ({ params, respond }) => {
+    "sessions.delete": async ({ params, respond, client, isWebchatConnect }) => {
         if (!assertValidParams(params, validateSessionsDeleteParams, "sessions.delete", respond)) {
             return;
         }
@@ -278,6 +322,9 @@ export const sessionsHandlers = {
         if (!key) {
             return;
         }
+        if (rejectWebchatSessionMutation({ action: "delete", client, isWebchatConnect, respond })) {
+            return;
+        }
         const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
         const mainKey = resolveMainSessionKey(cfg);
         if (target.canonicalKey === mainKey) {
@@ -287,19 +334,20 @@ export const sessionsHandlers = {
         const deleteTranscript = typeof p.deleteTranscript === "boolean" ? p.deleteTranscript : true;
         const { entry } = loadSessionEntry(key);
         const sessionId = entry?.sessionId;
-        const existed = Boolean(entry);
         const cleanupError = await ensureSessionRuntimeCleanup({ cfg, key, target, sessionId });
         if (cleanupError) {
             respond(false, undefined, cleanupError);
             return;
         }
-        await updateSessionStore(storePath, (store) => {
+        const deleted = await updateSessionStore(storePath, (store) => {
             const { primaryKey } = migrateAndPruneSessionStoreKey({ cfg, key, store });
-            if (store[primaryKey]) {
+            const hadEntry = Boolean(store[primaryKey]);
+            if (hadEntry) {
                 delete store[primaryKey];
             }
+            return hadEntry;
         });
-        const archived = deleteTranscript
+        const archived = deleted && deleteTranscript
             ? archiveSessionTranscriptsForSession({
                 sessionId,
                 storePath,
@@ -308,7 +356,15 @@ export const sessionsHandlers = {
                 reason: "deleted",
             })
             : [];
-        respond(true, { ok: true, key: target.canonicalKey, deleted: existed, archived }, undefined);
+        if (deleted) {
+            const emitLifecycleHooks = p.emitLifecycleHooks !== false;
+            await emitSessionUnboundLifecycleEvent({
+                targetSessionKey: target.canonicalKey ?? key,
+                reason: "session-delete",
+                emitHooks: emitLifecycleHooks,
+            });
+        }
+        respond(true, { ok: true, key: target.canonicalKey, deleted, archived }, undefined);
     },
     "sessions.compact": async ({ params, respond }) => {
         if (!assertValidParams(params, validateSessionsCompactParams, "sessions.compact", respond)) {