@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/dist/gateway/server/ws-connection.js

@@ -1,15 +1,49 @@
 import { randomUUID } from "node:crypto";
 import { resolveCanvasHostUrl } from "../../infra/canvas-host-url.js";
-import { listSystemPresence, upsertPresence } from "../../infra/system-presence.js";
+import { removeRemoteNodeInfo } from "../../infra/skills-remote.js";
+import { upsertPresence } from "../../infra/system-presence.js";
+import { truncateUtf16Safe } from "../../utils.js";
 import { isWebchatClient } from "../../utils/message-channel.js";
 import { isLoopbackAddress } from "../net.js";
 import { getHandshakeTimeoutMs } from "../server-constants.js";
 import { formatError } from "../server-utils.js";
 import { logWs } from "../ws-log.js";
-import { getHealthVersion, getPresenceVersion, incrementPresenceVersion } from "./health-state.js";
+import { getHealthVersion, incrementPresenceVersion } from "./health-state.js";
+import { broadcastPresenceSnapshot } from "./presence-events.js";
 import { attachGatewayWsMessageHandler } from "./ws-connection/message-handler.js";
+const LOG_HEADER_MAX_LEN = 300;
+const LOG_HEADER_FORMAT_REGEX = /\p{Cf}/gu;
+function replaceControlChars(value) {
+    let cleaned = "";
+    for (const char of value) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint !== undefined &&
+            (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f))) {
+            cleaned += " ";
+            continue;
+        }
+        cleaned += char;
+    }
+    return cleaned;
+}
+const sanitizeLogValue = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const cleaned = replaceControlChars(value)
+        .replace(LOG_HEADER_FORMAT_REGEX, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned) {
+        return undefined;
+    }
+    if (cleaned.length <= LOG_HEADER_MAX_LEN) {
+        return cleaned;
+    }
+    return truncateUtf16Safe(cleaned, LOG_HEADER_MAX_LEN);
+};
 export function attachGatewayWsConnectionHandler(params) {
-    const { wss, clients, port, gatewayHost, canvasHostEnabled, canvasHostServerPort, resolvedAuth, gatewayMethods, events, logGateway, logHealth, logWsControl, extraHandlers, broadcast, buildRequestContext, } = params;
+    const { wss, clients, port, gatewayHost, canvasHostEnabled, canvasHostServerPort, resolvedAuth, rateLimiter, gatewayMethods, events, logGateway, logHealth, logWsControl, extraHandlers, broadcast, buildRequestContext, } = params;
     wss.on("connection", (socket, upgradeReq) => {
         let client = null;
         let closed = false;
@@ -40,8 +74,9 @@ export function attachGatewayWsConnectionHandler(params) {
         let lastFrameMethod;
         let lastFrameId;
         const setCloseCause = (cause, meta) => {
-            if (!closeCause)
+            if (!closeCause) {
                 closeCause = cause;
+            }
             if (meta && Object.keys(meta).length > 0) {
                 closeMeta = { ...closeMeta, ...meta };
             }
@@ -68,12 +103,14 @@ export function attachGatewayWsConnectionHandler(params) {
             payload: { nonce: connectNonce, ts: Date.now() },
         });
         const close = (code = 1000, reason) => {
-            if (closed)
+            if (closed) {
                 return;
+            }
             closed = true;
             clearTimeout(handshakeTimer);
-            if (client)
+            if (client) {
                 clients.delete(client);
+            }
             try {
                 socket.close(code, reason);
             }
@@ -88,6 +125,11 @@ export function attachGatewayWsConnectionHandler(params) {
         const isNoisySwiftPmHelperClose = (userAgent, remote) => Boolean(userAgent?.toLowerCase().includes("swiftpm-testing-helper") && isLoopbackAddress(remote));
         socket.once("close", (code, reason) => {
             const durationMs = Date.now() - openedAt;
+            const logForwardedFor = sanitizeLogValue(forwardedFor);
+            const logOrigin = sanitizeLogValue(requestOrigin);
+            const logHost = sanitizeLogValue(requestHost);
+            const logUserAgent = sanitizeLogValue(requestUserAgent);
+            const logReason = sanitizeLogValue(reason?.toString());
             const closeContext = {
                 cause: closeCause,
                 handshake: handshakeState,
@@ -95,43 +137,37 @@ export function attachGatewayWsConnectionHandler(params) {
                 lastFrameType,
                 lastFrameMethod,
                 lastFrameId,
-                host: requestHost,
-                origin: requestOrigin,
-                userAgent: requestUserAgent,
-                forwardedFor,
+                host: logHost,
+                origin: logOrigin,
+                userAgent: logUserAgent,
+                forwardedFor: logForwardedFor,
                 ...closeMeta,
             };
             if (!client) {
                 const logFn = isNoisySwiftPmHelperClose(requestUserAgent, remoteAddr)
                     ? logWsControl.debug
                     : logWsControl.warn;
-                logFn(`closed before connect conn=${connId} remote=${remoteAddr ?? "?"} fwd=${forwardedFor ?? "n/a"} origin=${requestOrigin ?? "n/a"} host=${requestHost ?? "n/a"} ua=${requestUserAgent ?? "n/a"} code=${code ?? "n/a"} reason=${reason?.toString() || "n/a"}`, closeContext);
+                logFn(`closed before connect conn=${connId} remote=${remoteAddr ?? "?"} fwd=${logForwardedFor || "n/a"} origin=${logOrigin || "n/a"} host=${logHost || "n/a"} ua=${logUserAgent || "n/a"} code=${code ?? "n/a"} reason=${logReason || "n/a"}`, closeContext);
             }
             if (client && isWebchatClient(client.connect.client)) {
-                logWsControl.info(`webchat disconnected code=${code} reason=${reason?.toString() || "n/a"} conn=${connId}`);
+                logWsControl.info(`webchat disconnected code=${code} reason=${logReason || "n/a"} conn=${connId}`);
             }
             if (client?.presenceKey) {
                 upsertPresence(client.presenceKey, { reason: "disconnect" });
-                incrementPresenceVersion();
-                broadcast("presence", { presence: listSystemPresence() }, {
-                    dropIfSlow: true,
-                    stateVersion: {
-                        presence: getPresenceVersion(),
-                        health: getHealthVersion(),
-                    },
-                });
+                broadcastPresenceSnapshot({ broadcast, incrementPresenceVersion, getHealthVersion });
             }
             if (client?.connect?.role === "node") {
                 const context = buildRequestContext();
                 const nodeId = context.nodeRegistry.unregister(connId);
                 if (nodeId) {
+                    removeRemoteNodeInfo(nodeId);
                     context.nodeUnsubscribeAll(nodeId);
                 }
             }
             logWs("out", "close", {
                 connId,
                 code,
-                reason: reason?.toString(),
+                reason: logReason,
                 durationMs,
                 cause: closeCause,
                 handshake: handshakeState,
@@ -165,6 +201,7 @@ export function attachGatewayWsConnectionHandler(params) {
             canvasHostUrl,
             connectNonce,
             resolvedAuth,
+            rateLimiter,
             gatewayMethods,
             events,
             extraHandlers,

package/dist/gateway/server-broadcast.js

@@ -1,5 +1,5 @@
 import { MAX_BUFFERED_BYTES } from "./server-constants.js";
-import { logWs, summarizeAgentEventForWsLog } from "./ws-log.js";
+import { logWs, shouldLogWs, summarizeAgentEventForWsLog } from "./ws-log.js";
 const ADMIN_SCOPE = "operator.admin";
 const APPROVALS_SCOPE = "operator.approvals";
 const PAIRING_SCOPE = "operator.pairing";
@@ -29,6 +29,9 @@ function hasEventScope(client, event) {
 export function createGatewayBroadcaster(params) {
     let seq = 0;
     const broadcastInternal = (event, payload, opts, targetConnIds) => {
+        if (params.clients.size === 0) {
+            return;
+        }
         const isTargeted = Boolean(targetConnIds);
         const eventSeq = isTargeted ? undefined : ++seq;
         const frame = JSON.stringify({
@@ -38,19 +41,21 @@ export function createGatewayBroadcaster(params) {
             seq: eventSeq,
             stateVersion: opts?.stateVersion,
         });
-        const logMeta = {
-            event,
-            seq: eventSeq ?? "targeted",
-            clients: params.clients.size,
-            targets: targetConnIds ? targetConnIds.size : undefined,
-            dropIfSlow: opts?.dropIfSlow,
-            presenceVersion: opts?.stateVersion?.presence,
-            healthVersion: opts?.stateVersion?.health,
-        };
-        if (event === "agent") {
-            Object.assign(logMeta, summarizeAgentEventForWsLog(payload));
+        if (shouldLogWs()) {
+            const logMeta = {
+                event,
+                seq: eventSeq ?? "targeted",
+                clients: params.clients.size,
+                targets: targetConnIds ? targetConnIds.size : undefined,
+                dropIfSlow: opts?.dropIfSlow,
+                presenceVersion: opts?.stateVersion?.presence,
+                healthVersion: opts?.stateVersion?.health,
+            };
+            if (event === "agent") {
+                Object.assign(logMeta, summarizeAgentEventForWsLog(payload));
+            }
+            logWs("out", "event", logMeta);
         }
-        logWs("out", "event", logMeta);
         for (const c of params.clients) {
             if (targetConnIds && !targetConnIds.has(c.connId)) {
                 continue;

package/dist/gateway/server-cron.js

@@ -1,22 +1,49 @@
 import { resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { loadConfig } from "../config/config.js";
-import { resolveAgentMainSessionKey } from "../config/sessions.js";
+import { canonicalizeMainSessionAlias, resolveAgentIdFromSessionKey, resolveAgentMainSessionKey, } from "../config/sessions.js";
+import { resolveStorePath } from "../config/sessions/paths.js";
 import { runCronIsolatedAgentTurn } from "../cron/isolated-agent.js";
 import { appendCronRunLog, resolveCronRunLogPath } from "../cron/run-log.js";
 import { CronService } from "../cron/service.js";
 import { resolveCronStorePath } from "../cron/store.js";
+import { normalizeHttpWebhookUrl } from "../cron/webhook-url.js";
+import { formatErrorMessage } from "../infra/errors.js";
 import { runHeartbeatOnce } from "../infra/heartbeat-runner.js";
 import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
+import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
+import { SsrFBlockedError } from "../infra/net/ssrf.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 import { getChildLogger } from "../logging.js";
-import { normalizeAgentId } from "../routing/session-key.js";
+import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
+const CRON_WEBHOOK_TIMEOUT_MS = 10_000;
+function redactWebhookUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return "<invalid-webhook-url>";
+    }
+}
+function resolveCronWebhookTarget(params) {
+    const mode = params.delivery?.mode?.trim().toLowerCase();
+    if (mode === "webhook") {
+        const url = normalizeHttpWebhookUrl(params.delivery?.to);
+        return url ? { url, source: "delivery" } : null;
+    }
+    if (params.legacyNotify) {
+        const legacyUrl = normalizeHttpWebhookUrl(params.legacyWebhook);
+        if (legacyUrl) {
+            return { url: legacyUrl, source: "legacy" };
+        }
+    }
+    return null;
+}
 export function buildGatewayCronService(params) {
     const cronLogger = getChildLogger({ module: "cron" });
     const storePath = resolveCronStorePath(params.cfg.cron?.store);
-    const cronEnabled = process.env.POOLBOT_SKIP_CRON !== "1" &&
-        process.env.CLAWDBOT_SKIP_CRON !== "1" &&
-        params.cfg.cron?.enabled !== false;
+    const cronEnabled = process.env.POOLBOT_SKIP_CRON !== "1" && params.cfg.cron?.enabled !== false;
     const resolveCronAgent = (requested) => {
         const runtimeConfig = loadConfig();
         const normalized = typeof requested === "string" && requested.trim() ? normalizeAgentId(requested) : undefined;
@@ -26,23 +53,89 @@ export function buildGatewayCronService(params) {
         const agentId = hasAgent ? normalized : resolveDefaultAgentId(runtimeConfig);
         return { agentId, cfg: runtimeConfig };
     };
+    const resolveCronSessionKey = (params) => {
+        const requested = params.requestedSessionKey?.trim();
+        if (!requested) {
+            return resolveAgentMainSessionKey({
+                cfg: params.runtimeConfig,
+                agentId: params.agentId,
+            });
+        }
+        const candidate = toAgentStoreSessionKey({
+            agentId: params.agentId,
+            requestKey: requested,
+            mainKey: params.runtimeConfig.session?.mainKey,
+        });
+        const canonical = canonicalizeMainSessionAlias({
+            cfg: params.runtimeConfig,
+            agentId: params.agentId,
+            sessionKey: candidate,
+        });
+        if (canonical !== "global") {
+            const sessionAgentId = resolveAgentIdFromSessionKey(canonical);
+            if (normalizeAgentId(sessionAgentId) !== normalizeAgentId(params.agentId)) {
+                return resolveAgentMainSessionKey({
+                    cfg: params.runtimeConfig,
+                    agentId: params.agentId,
+                });
+            }
+        }
+        return canonical;
+    };
+    const resolveCronWakeTarget = (opts) => {
+        const runtimeConfig = loadConfig();
+        const requestedAgentId = opts?.agentId ? resolveCronAgent(opts.agentId).agentId : undefined;
+        const derivedAgentId = requestedAgentId ??
+            (opts?.sessionKey
+                ? normalizeAgentId(resolveAgentIdFromSessionKey(opts.sessionKey))
+                : undefined);
+        const agentId = derivedAgentId || undefined;
+        const sessionKey = opts?.sessionKey && agentId
+            ? resolveCronSessionKey({
+                runtimeConfig,
+                agentId,
+                requestedSessionKey: opts.sessionKey,
+            })
+            : undefined;
+        return { runtimeConfig, agentId, sessionKey };
+    };
+    const defaultAgentId = resolveDefaultAgentId(params.cfg);
+    const resolveSessionStorePath = (agentId) => resolveStorePath(params.cfg.session?.store, {
+        agentId: agentId ?? defaultAgentId,
+    });
+    const sessionStorePath = resolveSessionStorePath(defaultAgentId);
+    const warnedLegacyWebhookJobs = new Set();
     const cron = new CronService({
         storePath,
         cronEnabled,
+        cronConfig: params.cfg.cron,
+        defaultAgentId,
+        resolveSessionStorePath,
+        sessionStorePath,
         enqueueSystemEvent: (text, opts) => {
             const { agentId, cfg: runtimeConfig } = resolveCronAgent(opts?.agentId);
-            const sessionKey = resolveAgentMainSessionKey({
-                cfg: runtimeConfig,
+            const sessionKey = resolveCronSessionKey({
+                runtimeConfig,
+                agentId,
+                requestedSessionKey: opts?.sessionKey,
+            });
+            enqueueSystemEvent(text, { sessionKey, contextKey: opts?.contextKey });
+        },
+        requestHeartbeatNow: (opts) => {
+            const { agentId, sessionKey } = resolveCronWakeTarget(opts);
+            requestHeartbeatNow({
+                reason: opts?.reason,
                 agentId,
+                sessionKey,
             });
-            enqueueSystemEvent(text, { sessionKey });
         },
-        requestHeartbeatNow,
         runHeartbeatOnce: async (opts) => {
-            const runtimeConfig = loadConfig();
+            const { runtimeConfig, agentId, sessionKey } = resolveCronWakeTarget(opts);
             return await runHeartbeatOnce({
                 cfg: runtimeConfig,
                 reason: opts?.reason,
+                agentId,
+                sessionKey,
                 deps: { ...params.deps, runtime: defaultRuntime },
             });
         },
@@ -62,6 +155,75 @@ export function buildGatewayCronService(params) {
         onEvent: (evt) => {
             params.broadcast("cron", evt, { dropIfSlow: true });
             if (evt.action === "finished") {
+                const webhookToken = params.cfg.cron?.webhookToken?.trim();
+                const legacyWebhook = params.cfg.cron?.webhook?.trim();
+                const job = cron.getJob(evt.jobId);
+                const legacyNotify = job?.notify === true;
+                const webhookTarget = resolveCronWebhookTarget({
+                    delivery: job?.delivery && typeof job.delivery.mode === "string"
+                        ? { mode: job.delivery.mode, to: job.delivery.to }
+                        : undefined,
+                    legacyNotify,
+                    legacyWebhook,
+                });
+                if (!webhookTarget && job?.delivery?.mode === "webhook") {
+                    cronLogger.warn({
+                        jobId: evt.jobId,
+                        deliveryTo: job.delivery.to,
+                    }, "cron: skipped webhook delivery, delivery.to must be a valid http(s) URL");
+                }
+                if (webhookTarget?.source === "legacy" && !warnedLegacyWebhookJobs.has(evt.jobId)) {
+                    warnedLegacyWebhookJobs.add(evt.jobId);
+                    cronLogger.warn({
+                        jobId: evt.jobId,
+                        legacyWebhook: redactWebhookUrl(webhookTarget.url),
+                    }, "cron: deprecated notify+cron.webhook fallback in use, migrate to delivery.mode=webhook with delivery.to");
+                }
+                if (webhookTarget && evt.summary) {
+                    const headers = {
+                        "Content-Type": "application/json",
+                    };
+                    if (webhookToken) {
+                        headers.Authorization = `Bearer ${webhookToken}`;
+                    }
+                    const abortController = new AbortController();
+                    const timeout = setTimeout(() => {
+                        abortController.abort();
+                    }, CRON_WEBHOOK_TIMEOUT_MS);
+                    void (async () => {
+                        try {
+                            const result = await fetchWithSsrFGuard({
+                                url: webhookTarget.url,
+                                init: {
+                                    method: "POST",
+                                    headers,
+                                    body: JSON.stringify(evt),
+                                    signal: abortController.signal,
+                                },
+                            });
+                            await result.release();
+                        }
+                        catch (err) {
+                            if (err instanceof SsrFBlockedError) {
+                                cronLogger.warn({
+                                    reason: formatErrorMessage(err),
+                                    jobId: evt.jobId,
+                                    webhookUrl: redactWebhookUrl(webhookTarget.url),
+                                }, "cron: webhook delivery blocked by SSRF guard");
+                            }
+                            else {
+                                cronLogger.warn({
+                                    err: formatErrorMessage(err),
+                                    jobId: evt.jobId,
+                                    webhookUrl: redactWebhookUrl(webhookTarget.url),
+                                }, "cron: webhook delivery failed");
+                            }
+                        }
+                        finally {
+                            clearTimeout(timeout);
+                        }
+                    })();
+                }
                 const logPath = resolveCronRunLogPath({
                     storePath,
                     jobId: evt.jobId,
@@ -73,9 +235,14 @@ export function buildGatewayCronService(params) {
                     status: evt.status,
                     error: evt.error,
                     summary: evt.summary,
+                    sessionId: evt.sessionId,
+                    sessionKey: evt.sessionKey,
                     runAtMs: evt.runAtMs,
                     durationMs: evt.durationMs,
                     nextRunAtMs: evt.nextRunAtMs,
+                    model: evt.model,
+                    provider: evt.provider,
+                    usage: evt.usage,
                 }).catch((err) => {
                     cronLogger.warn({ err: String(err), logPath }, "cron: run log append failed");
                 });

package/dist/gateway/server-methods/agent-job.js

@@ -1,7 +1,14 @@
 import { onAgentEvent } from "../../infra/agent-events.js";
 const AGENT_RUN_CACHE_TTL_MS = 10 * 60_000;
+/**
+ * Embedded runs can emit transient lifecycle `error` events while auth/model
+ * failover is still in progress. Give errors a short grace window so a
+ * subsequent `start` event can cancel premature terminal snapshots.
+ */
+const AGENT_RUN_ERROR_RETRY_GRACE_MS = 15_000;
 const agentRunCache = new Map();
 const agentRunStarts = new Map();
+const pendingAgentRunErrors = new Map();
 let agentRunListenerStarted = false;
 function pruneAgentRunCache(now = Date.now()) {
     for (const [runId, entry] of agentRunCache) {
@@ -14,37 +21,89 @@ function recordAgentRunSnapshot(entry) {
     pruneAgentRunCache(entry.ts);
     agentRunCache.set(entry.runId, entry);
 }
+function clearPendingAgentRunError(runId) {
+    const pending = pendingAgentRunErrors.get(runId);
+    if (!pending) {
+        return;
+    }
+    clearTimeout(pending.timer);
+    pendingAgentRunErrors.delete(runId);
+}
+function schedulePendingAgentRunError(snapshot) {
+    clearPendingAgentRunError(snapshot.runId);
+    const dueAt = Date.now() + AGENT_RUN_ERROR_RETRY_GRACE_MS;
+    const timer = setTimeout(() => {
+        const pending = pendingAgentRunErrors.get(snapshot.runId);
+        if (!pending) {
+            return;
+        }
+        pendingAgentRunErrors.delete(snapshot.runId);
+        recordAgentRunSnapshot(pending.snapshot);
+    }, AGENT_RUN_ERROR_RETRY_GRACE_MS);
+    timer.unref?.();
+    pendingAgentRunErrors.set(snapshot.runId, { snapshot, dueAt, timer });
+}
+function getPendingAgentRunError(runId) {
+    const pending = pendingAgentRunErrors.get(runId);
+    if (!pending) {
+        return undefined;
+    }
+    return {
+        snapshot: pending.snapshot,
+        dueAt: pending.dueAt,
+    };
+}
+function createSnapshotFromLifecycleEvent(params) {
+    const { runId, phase, data } = params;
+    const startedAt = typeof data?.startedAt === "number" ? data.startedAt : agentRunStarts.get(runId);
+    const endedAt = typeof data?.endedAt === "number" ? data.endedAt : undefined;
+    const error = typeof data?.error === "string" ? data.error : undefined;
+    return {
+        runId,
+        status: phase === "error" ? "error" : data?.aborted ? "timeout" : "ok",
+        startedAt,
+        endedAt,
+        error,
+        ts: Date.now(),
+    };
+}
 function ensureAgentRunListener() {
-    if (agentRunListenerStarted)
+    if (agentRunListenerStarted) {
         return;
+    }
     agentRunListenerStarted = true;
     onAgentEvent((evt) => {
-        if (!evt)
+        if (!evt) {
             return;
-        if (evt.stream !== "lifecycle")
+        }
+        if (evt.stream !== "lifecycle") {
             return;
+        }
         const phase = evt.data?.phase;
         if (phase === "start") {
             const startedAt = typeof evt.data?.startedAt === "number" ? evt.data.startedAt : undefined;
             agentRunStarts.set(evt.runId, startedAt ?? Date.now());
+            clearPendingAgentRunError(evt.runId);
+            // A new start means this run is active again (or retried). Drop stale
+            // terminal snapshots so waiters don't resolve from old state.
+            agentRunCache.delete(evt.runId);
             return;
         }
-        if (phase !== "end" && phase !== "error")
+        if (phase !== "end" && phase !== "error") {
             return;
-        const startedAt = typeof evt.data?.startedAt === "number"
-            ? evt.data.startedAt
-            : agentRunStarts.get(evt.runId);
-        const endedAt = typeof evt.data?.endedAt === "number" ? evt.data.endedAt : undefined;
-        const error = typeof evt.data?.error === "string" ? evt.data.error : undefined;
-        agentRunStarts.delete(evt.runId);
-        recordAgentRunSnapshot({
+        }
+        const snapshot = createSnapshotFromLifecycleEvent({
             runId: evt.runId,
-            status: phase === "error" ? "error" : "ok",
-            startedAt,
-            endedAt,
-            error,
-            ts: Date.now(),
+            phase,
+            data: evt.data,
         });
+        agentRunStarts.delete(evt.runId);
+        if (phase === "error") {
+            schedulePendingAgentRunError(snapshot);
+            return;
+        }
+        clearPendingAgentRunError(evt.runId);
+        recordAgentRunSnapshot(snapshot);
     });
 }
 function getCachedAgentRun(runId) {
@@ -55,50 +114,84 @@ export async function waitForAgentJob(params) {
     const { runId, timeoutMs } = params;
     ensureAgentRunListener();
     const cached = getCachedAgentRun(runId);
-    if (cached)
+    if (cached) {
         return cached;
-    if (timeoutMs <= 0)
+    }
+    if (timeoutMs <= 0) {
         return null;
+    }
     return await new Promise((resolve) => {
         let settled = false;
+        let pendingErrorTimer;
+        const clearPendingErrorTimer = () => {
+            if (!pendingErrorTimer) {
+                return;
+            }
+            clearTimeout(pendingErrorTimer);
+            pendingErrorTimer = undefined;
+        };
         const finish = (entry) => {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             clearTimeout(timer);
+            clearPendingErrorTimer();
             unsubscribe();
             resolve(entry);
         };
+        const scheduleErrorFinish = (snapshot, delayMs = AGENT_RUN_ERROR_RETRY_GRACE_MS) => {
+            clearPendingErrorTimer();
+            const effectiveDelay = Math.max(1, Math.min(Math.floor(delayMs), 2_147_483_647));
+            pendingErrorTimer = setTimeout(() => {
+                const latest = getCachedAgentRun(runId);
+                if (latest) {
+                    finish(latest);
+                    return;
+                }
+                recordAgentRunSnapshot(snapshot);
+                finish(snapshot);
+            }, effectiveDelay);
+            pendingErrorTimer.unref?.();
+        };
+        const pending = getPendingAgentRunError(runId);
+        if (pending) {
+            scheduleErrorFinish(pending.snapshot, pending.dueAt - Date.now());
+        }
         const unsubscribe = onAgentEvent((evt) => {
-            if (!evt || evt.stream !== "lifecycle")
+            if (!evt || evt.stream !== "lifecycle") {
                 return;
-            if (evt.runId !== runId)
+            }
+            if (evt.runId !== runId) {
                 return;
+            }
             const phase = evt.data?.phase;
-            if (phase !== "end" && phase !== "error")
+            if (phase === "start") {
+                clearPendingErrorTimer();
+                return;
+            }
+            if (phase !== "end" && phase !== "error") {
                 return;
-            const cached = getCachedAgentRun(runId);
-            if (cached) {
-                finish(cached);
+            }
+            const latest = getCachedAgentRun(runId);
+            if (latest) {
+                finish(latest);
                 return;
             }
-            const startedAt = typeof evt.data?.startedAt === "number"
-                ? evt.data.startedAt
-                : agentRunStarts.get(evt.runId);
-            const endedAt = typeof evt.data?.endedAt === "number" ? evt.data.endedAt : undefined;
-            const error = typeof evt.data?.error === "string" ? evt.data.error : undefined;
-            const snapshot = {
+            const snapshot = createSnapshotFromLifecycleEvent({
                 runId: evt.runId,
-                status: phase === "error" ? "error" : "ok",
-                startedAt,
-                endedAt,
-                error,
-                ts: Date.now(),
-            };
+                phase,
+                data: evt.data,
+            });
+            if (phase === "error") {
+                scheduleErrorFinish(snapshot);
+                return;
+            }
             recordAgentRunSnapshot(snapshot);
             finish(snapshot);
         });
-        const timer = setTimeout(() => finish(null), Math.max(1, timeoutMs));
+        const timerDelayMs = Math.max(1, Math.min(Math.floor(timeoutMs), 2_147_483_647));
+        const timer = setTimeout(() => finish(null), timerDelayMs);
     });
 }
 ensureAgentRunListener();