openzca 0.1.21 → 0.1.24

package/dist/cli.js

@@ -5,6 +5,7 @@ import { createRequire } from "module";
 import { spawn as spawn2 } from "child_process";
 import fsSync from "fs";
 import fs4 from "fs/promises";
+import net from "net";
 import os3 from "os";
 import path4 from "path";
 import util from "util";
@@ -703,6 +704,531 @@ function output(value, asJson = false) {
 function asThreadType(groupFlag) {
   return groupFlag ? ThreadType.Group : ThreadType.User;
 }
+function parseBooleanFromEnv(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const normalized = raw.toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return fallback;
+}
+function normalizeCachedId(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(Math.trunc(value));
+  }
+  return null;
+}
+function collectIdsFromCacheEntries(entries, keys) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const row = entry;
+    for (const key of keys) {
+      const normalized = normalizeCachedId(row[key]);
+      if (normalized) {
+        ids.add(normalized);
+      }
+    }
+  }
+  return ids;
+}
+function getListenerOwnerLockPath(profile) {
+  return path4.join(getProfileDir(profile), "listener-owner.json");
+}
+function getListenIpcSocketPath(profile) {
+  if (process.platform === "win32") {
+    const safe = profile.replace(/[^A-Za-z0-9_-]/g, "_");
+    return `\\\\.\\pipe\\openzca-listen-${safe}`;
+  }
+  return path4.join(getProfileDir(profile), "listen.sock");
+}
+function parsePositiveIntFromUnknown(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value);
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+async function readListenerOwnerRecord(lockPath) {
+  try {
+    const raw = await fs4.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const pid = parsePositiveIntFromUnknown(parsed.pid);
+    if (!pid) return null;
+    return {
+      pid,
+      profile: String(parsed.profile ?? ""),
+      sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId : void 0,
+      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : ""
+    };
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function readActiveListenerOwner(profile) {
+  const lockPath = getListenerOwnerLockPath(profile);
+  const record = await readListenerOwnerRecord(lockPath);
+  if (!record) {
+    await fs4.rm(lockPath, { force: true });
+    return null;
+  }
+  if (!isProcessAlive(record.pid)) {
+    await fs4.rm(lockPath, { force: true });
+    return null;
+  }
+  return record;
+}
+async function acquireListenerOwnerLock(profile, sessionId, command) {
+  await ensureProfile(profile);
+  const lockPath = getListenerOwnerLockPath(profile);
+  const record = {
+    pid: process.pid,
+    profile,
+    sessionId,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await fs4.writeFile(lockPath, `${JSON.stringify(record, null, 2)}
+`, {
+        encoding: "utf8",
+        flag: "wx"
+      });
+      let released = false;
+      return {
+        lockPath,
+        release: async () => {
+          if (released) return;
+          released = true;
+          const current = await readListenerOwnerRecord(lockPath);
+          if (current && current.pid !== process.pid) return;
+          await fs4.rm(lockPath, { force: true });
+          writeDebugLine(
+            "listen.owner.released",
+            {
+              profile,
+              lockPath,
+              pid: process.pid
+            },
+            command
+          );
+        }
+      };
+    } catch (error) {
+      const code = error.code;
+      if (code !== "EEXIST") throw error;
+      const owner = await readActiveListenerOwner(profile);
+      if (owner) {
+        throw new Error(
+          `Another openzca listener already owns profile "${profile}" (pid ${owner.pid}).`
+        );
+      }
+      await fs4.rm(lockPath, { force: true });
+    }
+  }
+  throw new Error(`Unable to acquire listener ownership for profile "${profile}".`);
+}
+async function startListenerIpcServer(api, profile, sessionId, command) {
+  if (!parseBooleanFromEnv("OPENZCA_LISTEN_IPC", true)) {
+    writeDebugLine(
+      "listen.ipc.disabled",
+      {
+        profile
+      },
+      command
+    );
+    return null;
+  }
+  const socketPath = getListenIpcSocketPath(profile);
+  if (process.platform !== "win32") {
+    await fs4.rm(socketPath, { force: true });
+  }
+  const uploadTimeoutMs = parsePositiveIntFromEnv(
+    "OPENZCA_UPLOAD_IPC_HANDLER_TIMEOUT_MS",
+    parsePositiveIntFromEnv("OPENZCA_UPLOAD_TIMEOUT_MS", 12e4)
+  );
+  const server = net.createServer((socket) => {
+    socket.setEncoding("utf8");
+    let buffer = "";
+    let done = false;
+    const sendResponse = (response) => {
+      if (done) return;
+      done = true;
+      socket.end(`${JSON.stringify(response)}
+`);
+    };
+    const fail = (requestId, message) => {
+      sendResponse({
+        kind: "upload_result",
+        requestId,
+        ok: false,
+        error: message
+      });
+    };
+    const handleRequest = async (line) => {
+      if (done) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        fail("", "Invalid JSON request.");
+        return;
+      }
+      if (parsed.kind !== "upload") {
+        fail(parsed.requestId || "", "Unsupported IPC request kind.");
+        return;
+      }
+      if (parsed.profile !== profile) {
+        fail(parsed.requestId, "Profile mismatch.");
+        return;
+      }
+      if (!parsed.threadId || !Array.isArray(parsed.attachments) || parsed.attachments.length === 0) {
+        fail(parsed.requestId, "Invalid upload payload.");
+        return;
+      }
+      const threadType = parsed.threadType === "group" ? ThreadType.Group : ThreadType.User;
+      const requestTimeoutMs = parsePositiveIntFromUnknown(parsed.uploadTimeoutMs) ?? uploadTimeoutMs;
+      writeDebugLine(
+        "listen.ipc.upload.start",
+        {
+          profile,
+          sessionId,
+          requestId: parsed.requestId,
+          threadId: parsed.threadId,
+          threadType: parsed.threadType,
+          attachmentCount: parsed.attachments.length,
+          timeoutMs: requestTimeoutMs
+        },
+        command
+      );
+      try {
+        const response = await withTimeout(
+          api.sendMessage(
+            {
+              msg: "",
+              attachments: parsed.attachments
+            },
+            parsed.threadId,
+            threadType
+          ),
+          requestTimeoutMs,
+          `Timed out waiting ${requestTimeoutMs}ms for IPC upload completion.`
+        );
+        sendResponse({
+          kind: "upload_result",
+          requestId: parsed.requestId,
+          ok: true,
+          response
+        });
+        writeDebugLine(
+          "listen.ipc.upload.done",
+          {
+            profile,
+            sessionId,
+            requestId: parsed.requestId,
+            threadId: parsed.threadId,
+            threadType: parsed.threadType
+          },
+          command
+        );
+      } catch (error) {
+        fail(parsed.requestId, toErrorText(error));
+        writeDebugLine(
+          "listen.ipc.upload.error",
+          {
+            profile,
+            sessionId,
+            requestId: parsed.requestId,
+            threadId: parsed.threadId,
+            threadType: parsed.threadType,
+            message: toErrorText(error)
+          },
+          command
+        );
+      }
+    };
+    socket.on("data", (chunk) => {
+      if (done) return;
+      buffer += chunk;
+      if (buffer.length > 2e6) {
+        fail("", "IPC request too large.");
+        return;
+      }
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = "";
+      if (!line) {
+        fail("", "Empty IPC request.");
+        return;
+      }
+      void handleRequest(line);
+    });
+    socket.on("error", (error) => {
+      writeDebugLine(
+        "listen.ipc.socket_error",
+        {
+          profile,
+          sessionId,
+          message: toErrorText(error)
+        },
+        command
+      );
+    });
+  });
+  server.on("error", (error) => {
+    writeDebugLine(
+      "listen.ipc.server_error",
+      {
+        profile,
+        sessionId,
+        message: toErrorText(error)
+      },
+      command
+    );
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  writeDebugLine(
+    "listen.ipc.started",
+    {
+      profile,
+      sessionId,
+      socketPath
+    },
+    command
+  );
+  let closed = false;
+  return {
+    socketPath,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await new Promise((resolve) => {
+        server.close(() => resolve());
+      });
+      if (process.platform !== "win32") {
+        await fs4.rm(socketPath, { force: true });
+      }
+      writeDebugLine(
+        "listen.ipc.stopped",
+        {
+          profile,
+          sessionId,
+          socketPath
+        },
+        command
+      );
+    }
+  };
+}
+async function tryUploadViaListenerIpc(profile, threadId, threadType, attachments, command) {
+  if (!parseBooleanFromEnv("OPENZCA_UPLOAD_IPC", true)) {
+    return { handled: false, reason: "ipc_disabled" };
+  }
+  const socketPath = getListenIpcSocketPath(profile);
+  const requestId = `${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 10)}`;
+  const connectTimeoutMs = parsePositiveIntFromEnv("OPENZCA_UPLOAD_IPC_CONNECT_TIMEOUT_MS", 1e3);
+  const requestTimeoutMs = parsePositiveIntFromEnv(
+    "OPENZCA_UPLOAD_IPC_TIMEOUT_MS",
+    parsePositiveIntFromEnv("OPENZCA_UPLOAD_TIMEOUT_MS", 12e4) + 5e3
+  );
+  writeDebugLine(
+    "msg.upload.ipc.try",
+    {
+      profile,
+      threadId,
+      threadType: threadType === ThreadType.Group ? "group" : "user",
+      attachmentCount: attachments.length,
+      socketPath,
+      requestId,
+      connectTimeoutMs,
+      requestTimeoutMs
+    },
+    command
+  );
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let connected = false;
+    let settled = false;
+    let responseBuffer = "";
+    let requestSent = false;
+    const finish = (result, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(requestTimer);
+      if (!socket.destroyed) {
+        socket.destroy();
+      }
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(result ?? { handled: false, reason: "unknown" });
+    };
+    const connectTimer = setTimeout(() => {
+      finish(void 0, new Error(`Timed out waiting ${connectTimeoutMs}ms to connect upload IPC.`));
+    }, connectTimeoutMs);
+    const requestTimer = setTimeout(() => {
+      finish(void 0, new Error(`Timed out waiting ${requestTimeoutMs}ms for upload IPC response.`));
+    }, requestTimeoutMs);
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      connected = true;
+      clearTimeout(connectTimer);
+      const payload = {
+        kind: "upload",
+        requestId,
+        profile,
+        threadId,
+        threadType: threadType === ThreadType.Group ? "group" : "user",
+        attachments
+      };
+      socket.write(`${JSON.stringify(payload)}
+`);
+      requestSent = true;
+    });
+    socket.on("data", (chunk) => {
+      responseBuffer += chunk;
+      const newlineIndex = responseBuffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = responseBuffer.slice(0, newlineIndex).trim();
+      if (!line) {
+        finish(void 0, new Error("Upload IPC returned empty response."));
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        finish(void 0, new Error("Upload IPC returned invalid JSON."));
+        return;
+      }
+      if (parsed.kind !== "upload_result" || parsed.requestId !== requestId) {
+        finish(void 0, new Error("Upload IPC returned mismatched response."));
+        return;
+      }
+      if (!parsed.ok) {
+        finish(void 0, new Error(parsed.error || "Upload IPC failed."));
+        return;
+      }
+      finish({
+        handled: true,
+        response: parsed.response
+      });
+    });
+    socket.on("error", (error) => {
+      const code = error.code;
+      if (!connected && !requestSent && (code === "ENOENT" || code === "ECONNREFUSED")) {
+        finish({
+          handled: false,
+          reason: code.toLowerCase()
+        });
+        return;
+      }
+      finish(void 0, error);
+    });
+    socket.on("close", () => {
+      if (settled) return;
+      if (!connected && !requestSent) {
+        finish({
+          handled: false,
+          reason: "socket_closed_before_connect"
+        });
+        return;
+      }
+      finish(void 0, new Error("Upload IPC connection closed before response."));
+    });
+  });
+}
+async function resolveUploadThreadType(api, profile, threadId, groupFlag, command) {
+  if (groupFlag) {
+    return { type: ThreadType.Group, reason: "explicit_group_flag" };
+  }
+  const autoDetectEnabled = parseBooleanFromEnv("OPENZCA_UPLOAD_AUTO_THREAD_TYPE", true);
+  if (!autoDetectEnabled) {
+    return { type: ThreadType.User, reason: "auto_detect_disabled" };
+  }
+  try {
+    const cache = await readCache(profile);
+    const groupIds = collectIdsFromCacheEntries(cache.groups, ["groupId", "grid", "threadId", "id"]);
+    if (groupIds.has(threadId)) {
+      return { type: ThreadType.Group, reason: "cache_group_match" };
+    }
+    const friendIds = collectIdsFromCacheEntries(cache.friends, ["userId", "uid", "id", "threadId"]);
+    if (friendIds.has(threadId)) {
+      return { type: ThreadType.User, reason: "cache_friend_match" };
+    }
+  } catch (error) {
+    writeDebugLine(
+      "msg.upload.thread_type.cache_error",
+      {
+        profile,
+        threadId,
+        message: toErrorText(error)
+      },
+      command
+    );
+  }
+  const probeEnabled = parseBooleanFromEnv("OPENZCA_UPLOAD_GROUP_PROBE", true);
+  if (!probeEnabled) {
+    return { type: ThreadType.User, reason: "probe_disabled" };
+  }
+  const probeTimeoutMs = parsePositiveIntFromEnv("OPENZCA_UPLOAD_GROUP_PROBE_TIMEOUT_MS", 5e3);
+  try {
+    const groupInfo = await withTimeout(
+      api.getGroupInfo(threadId),
+      probeTimeoutMs,
+      `Timed out waiting ${probeTimeoutMs}ms while probing group thread type.`
+    );
+    if (groupInfo?.gridInfoMap?.[threadId]) {
+      return { type: ThreadType.Group, reason: "probe_group_match" };
+    }
+  } catch (error) {
+    writeDebugLine(
+      "msg.upload.thread_type.probe_error",
+      {
+        profile,
+        threadId,
+        message: toErrorText(error)
+      },
+      command
+    );
+  }
+  return { type: ThreadType.User, reason: "default_user" };
+}
 function parseReaction(input) {
   const normalized = input.trim();
   if (EMOJI_REACTION_MAP[normalized]) {
@@ -2334,18 +2860,28 @@ msg.command("edit <msgId> <cliMsgId> <threadId> <message>").option("-g, --group"
 msg.command("upload <arg1> [arg2]").option("-u, --url <url>", "File URL (repeatable)", collectValues, []).option("-g, --group", "Upload in group").description("Upload and send file(s)").action(
   wrapAction(
     async (arg1, arg2, opts, command) => {
-      const { api } = await requireApi(command);
+      const { api, profile } = await requireApi(command);
       const inputs = normalizeInputList(opts.url);
       const urlInputs = inputs.filter((entry) => isHttpUrl(entry));
       const localInputs = inputs.filter((entry) => !isHttpUrl(entry));
       const [threadId, file] = arg2 ? [arg2, arg1] : [arg1, void 0];
+      const threadResolution = await resolveUploadThreadType(
+        api,
+        profile,
+        threadId,
+        opts.group,
+        command
+      );
       const normalizedFile = file ? normalizeMediaInput(file) : void 0;
       const localFiles = [normalizedFile, ...localInputs].filter(Boolean);
       writeDebugLine(
         "msg.upload.inputs",
         {
           threadId,
-          isGroup: Boolean(opts.group),
+          explicitGroupFlag: Boolean(opts.group),
+          isGroup: threadResolution.type === ThreadType.Group,
+          threadType: threadResolution.type === ThreadType.Group ? "group" : "user",
+          threadTypeReason: threadResolution.reason,
           localFiles,
           urlInputs
         },
@@ -2360,6 +2896,43 @@ msg.command("upload <arg1> [arg2]").option("-u, --url <url>", "File URL (repeata
           );
         }
         await assertFilesExist(attachments);
+        const ipcResult = await tryUploadViaListenerIpc(
+          profile,
+          threadId,
+          threadResolution.type,
+          attachments,
+          command
+        );
+        if (ipcResult.handled) {
+          writeDebugLine(
+            "msg.upload.ipc.done",
+            {
+              threadId,
+              threadType: threadResolution.type === ThreadType.Group ? "group" : "user"
+            },
+            command
+          );
+          output(ipcResult.response, false);
+          return;
+        }
+        writeDebugLine(
+          "msg.upload.ipc.fallback",
+          {
+            threadId,
+            threadType: threadResolution.type === ThreadType.Group ? "group" : "user",
+            reason: ipcResult.reason
+          },
+          command
+        );
+        const enforceSingleOwner = parseBooleanFromEnv("OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER", true);
+        if (enforceSingleOwner) {
+          const owner = await readActiveListenerOwner(profile);
+          if (owner && owner.pid !== process.pid) {
+            throw new Error(
+              `Active listener owner detected for profile "${profile}" (pid ${owner.pid}), but upload IPC is unavailable. Restart \`openzca listen\` with latest version or set OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER=0 to allow fallback listener startup.`
+            );
+          }
+        }
         const response = await withUploadListener(
           api,
           command,
@@ -2369,7 +2942,7 @@ msg.command("upload <arg1> [arg2]").option("-u, --url <url>", "File URL (repeata
               attachments
             },
             threadId,
-            asThreadType(opts.group)
+            threadResolution.type
           )
         );
         output(response, false);
@@ -3022,6 +3595,14 @@ program.command("listen").description("Listen for real-time incoming messages").
       ) ?? 3e4;
       const lifecycleEventsEnabled = supervised && Boolean(opts.raw);
       const recycleEnabled = !supervised && Boolean(opts.keepAlive) && recycleMs > 0;
+      const keepAliveRestartDelayMs = parsePositiveIntFromEnv(
+        "OPENZCA_LISTEN_KEEPALIVE_RESTART_DELAY_MS",
+        2e3
+      );
+      const keepAliveRestartOnAnyClose = parseBooleanFromEnv(
+        "OPENZCA_LISTEN_KEEPALIVE_RESTART_ON_ANY_CLOSE",
+        false
+      );
       const recycleExitCode = 75;
       const includeReplyContext = parseToggleDefaultTrue(
         process.env.OPENZCA_LISTEN_INCLUDE_QUOTE_CONTEXT
@@ -3043,212 +3624,229 @@ program.command("listen").description("Listen for real-time incoming messages").
           })
         );
       };
-      console.log("Listening... Press Ctrl+C to stop.");
-      if (supervised && opts.keepAlive) {
-        console.error("Warning: --supervised ignores internal --keep-alive reconnect ownership.");
-      }
-      writeDebugLine(
-        "listen.start",
-        {
-          profile,
-          mediaDir: resolveInboundMediaDir(profile),
-          maxMediaBytes: parseMaxInboundMediaBytes(),
-          maxMediaFiles: parseMaxInboundMediaFiles(),
-          includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null,
-          keepAlive: Boolean(opts.keepAlive),
-          supervised,
-          lifecycleEventsEnabled,
-          heartbeatMs: lifecycleEventsEnabled ? heartbeatMs : void 0,
-          recycleMs: recycleEnabled ? recycleMs : void 0,
-          includeReplyContext,
-          downloadQuoteMedia,
-          sessionId
-        },
-        command
-      );
-      emitLifecycle("session_id");
-      async function emitWebhook(payload) {
-        if (!opts.webhook) return;
-        try {
-          const response = await fetch(opts.webhook, {
-            method: "POST",
-            headers: {
-              "content-type": "application/json"
+      const enforceSingleOwner = parseBooleanFromEnv("OPENZCA_LISTEN_ENFORCE_SINGLE_OWNER", true);
+      let ownerLock = null;
+      let ipcServer = null;
+      let ipcSocketPath;
+      let resourcesCleaned = false;
+      const cleanupListenResources = async () => {
+        if (resourcesCleaned) return;
+        resourcesCleaned = true;
+        if (ipcServer) {
+          await ipcServer.close();
+          ipcServer = null;
+        }
+        if (ownerLock) {
+          await ownerLock.release();
+          ownerLock = null;
+        }
+      };
+      const unregisterResourceCleanup = registerShutdownCallback(async () => {
+        await cleanupListenResources();
+      });
+      try {
+        if (enforceSingleOwner) {
+          ownerLock = await acquireListenerOwnerLock(profile, sessionId, command);
+          writeDebugLine(
+            "listen.owner.acquired",
+            {
+              profile,
+              lockPath: ownerLock.lockPath,
+              pid: process.pid,
+              sessionId
             },
-            body: JSON.stringify(payload)
-          });
-          if (!response.ok) {
-            console.error(`Webhook response: ${response.status}`);
-          }
-        } catch (error) {
-          console.error(
-            `Webhook failed: ${error instanceof Error ? error.message : String(error)}`
+            command
           );
         }
-      }
-      api.listener.on("connected", () => {
-        console.log("Connected to Zalo websocket.");
+        ipcServer = await startListenerIpcServer(api, profile, sessionId, command);
+        ipcSocketPath = ipcServer?.socketPath;
+        console.log("Listening... Press Ctrl+C to stop.");
+        if (supervised && opts.keepAlive) {
+          console.error("Warning: --supervised ignores internal --keep-alive reconnect ownership.");
+        }
         writeDebugLine(
-          "listen.connected",
+          "listen.start",
           {
             profile,
-            sessionId
+            mediaDir: resolveInboundMediaDir(profile),
+            maxMediaBytes: parseMaxInboundMediaBytes(),
+            maxMediaFiles: parseMaxInboundMediaFiles(),
+            includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null,
+            keepAlive: Boolean(opts.keepAlive),
+            keepAliveRestartDelayMs: Boolean(opts.keepAlive) ? keepAliveRestartDelayMs : void 0,
+            keepAliveRestartOnAnyClose: Boolean(opts.keepAlive) ? keepAliveRestartOnAnyClose : void 0,
+            supervised,
+            lifecycleEventsEnabled,
+            heartbeatMs: lifecycleEventsEnabled ? heartbeatMs : void 0,
+            recycleMs: recycleEnabled ? recycleMs : void 0,
+            includeReplyContext,
+            downloadQuoteMedia,
+            sessionId,
+            singleOwner: enforceSingleOwner,
+            ipcSocketPath
           },
           command
         );
-        emitLifecycle("connected");
-      });
-      api.listener.on("message", async (message) => {
-        const messageData = message.data;
-        const rawContent = messageData.content;
-        const msgType = getStringCandidate(messageData, ["msgType"]);
-        let quote = normalizeQuoteContext(messageData.quote);
-        const parsedContent = normalizeStructuredContent(rawContent);
-        const hasParsedStructuredContent = parsedContent !== rawContent;
-        const rawText = typeof rawContent === "string" ? rawContent : "";
-        const mediaKind = detectInboundMediaKind(msgType, parsedContent);
-        const maxMediaFiles = parseMaxInboundMediaFiles();
-        const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, parsedContent).slice(0, maxMediaFiles) : [];
-        const quoteRemoteMediaUrls = quote && downloadQuoteMedia && maxMediaFiles > 0 ? (quote.mediaUrls ?? []).slice(0, maxMediaFiles) : [];
-        writeDebugLine(
-          "listen.media.detected",
-          {
-            profile,
-            threadId: message.threadId,
-            msgType: msgType || void 0,
-            mediaKind,
-            hasParsedStructuredContent,
-            remoteMediaUrls,
-            hasQuote: Boolean(quote),
-            quoteOwnerId: quote?.ownerId,
-            quoteGlobalMsgId: quote?.globalMsgId,
-            quoteCliMsgId: quote?.cliMsgId,
-            quoteRemoteMediaUrls
-          },
-          command
-        );
-        const [mediaEntries, quoteMediaEntries] = await Promise.all([
-          mediaKind ? cacheRemoteMediaEntries({
-            profile,
-            urls: remoteMediaUrls,
-            kind: mediaKind,
-            command,
-            warningLabel: "inbound media",
-            debugErrorEvent: "listen.media.cache_error",
-            debugUrlKey: "mediaUrl"
-          }) : Promise.resolve([]),
-          cacheRemoteMediaEntries({
-            profile,
-            urls: quoteRemoteMediaUrls,
-            kind: "file",
-            command,
-            warningLabel: "quoted media",
-            debugErrorEvent: "listen.quote_media.cache_error",
-            debugUrlKey: "quoteMediaUrl"
-          })
-        ]);
-        const localEntries = mediaEntries.filter((entry) => Boolean(entry.mediaPath));
-        const mediaPaths = localEntries.map((entry) => entry.mediaPath);
-        const mediaUrls = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
-        const mediaTypes = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
-        const mediaPath = mediaPaths[0];
-        const mediaUrl = mediaUrls[0];
-        const mediaType = mediaTypes[0];
-        const quoteLocalEntries = quoteMediaEntries.filter((entry) => Boolean(entry.mediaPath));
-        const quoteMediaPaths = quoteLocalEntries.map((entry) => entry.mediaPath);
-        const quoteMediaUrls = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
-        const quoteMediaTypes = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
-        const quoteMediaPath = quoteMediaPaths[0];
-        const quoteMediaUrl = quoteMediaUrls[0];
-        const quoteMediaType = quoteMediaTypes[0];
-        if (quote) {
-          quote = {
-            ...quote,
-            mediaPath: quoteMediaPath,
-            mediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
-            mediaUrl: quoteMediaUrl,
-            mediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : quote.mediaUrls,
-            mediaType: quoteMediaType,
-            mediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0
-          };
-        }
-        const replyContextText = includeReplyContext && quote ? buildReplyContextText(quote) : "";
-        const replyMediaText = includeReplyContext && quoteMediaEntries.length > 0 ? buildReplyMediaAttachedText({ mediaEntries: quoteMediaEntries }) : "";
-        const caption = rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText.trim() : summarizeStructuredContent(msgType, parsedContent);
-        let processedText = mediaEntries.length ? buildMediaAttachedText({
-          mediaEntries,
-          fallbackKind: mediaKind,
-          caption
-        }) : rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText : summarizeStructuredContent(msgType, parsedContent);
-        if (!processedText.trim() && !replyContextText && !replyMediaText) return;
-        if (opts.prefix && processedText.trim().length > 0) {
-          if (!processedText.startsWith(opts.prefix)) return;
-          processedText = processedText.slice(opts.prefix.length).trimStart();
+        emitLifecycle("session_id");
+        let keepAliveRestartTimer = null;
+        async function emitWebhook(payload) {
+          if (!opts.webhook) return;
+          try {
+            const response = await fetch(opts.webhook, {
+              method: "POST",
+              headers: {
+                "content-type": "application/json"
+              },
+              body: JSON.stringify(payload)
+            });
+            if (!response.ok) {
+              console.error(`Webhook response: ${response.status}`);
+            }
+          } catch (error) {
+            console.error(
+              `Webhook failed: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
         }
-        if (replyMediaText) {
-          processedText = processedText.trim() ? `${processedText}
+        api.listener.on("connected", () => {
+          console.log("Connected to Zalo websocket.");
+          if (keepAliveRestartTimer) {
+            clearTimeout(keepAliveRestartTimer);
+            keepAliveRestartTimer = null;
+          }
+          writeDebugLine(
+            "listen.connected",
+            {
+              profile,
+              sessionId
+            },
+            command
+          );
+          emitLifecycle("connected");
+        });
+        api.listener.on("message", async (message) => {
+          const messageData = message.data;
+          const rawContent = messageData.content;
+          const msgType = getStringCandidate(messageData, ["msgType"]);
+          let quote = normalizeQuoteContext(messageData.quote);
+          const parsedContent = normalizeStructuredContent(rawContent);
+          const hasParsedStructuredContent = parsedContent !== rawContent;
+          const rawText = typeof rawContent === "string" ? rawContent : "";
+          const mediaKind = detectInboundMediaKind(msgType, parsedContent);
+          const maxMediaFiles = parseMaxInboundMediaFiles();
+          const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, parsedContent).slice(0, maxMediaFiles) : [];
+          const quoteRemoteMediaUrls = quote && downloadQuoteMedia && maxMediaFiles > 0 ? (quote.mediaUrls ?? []).slice(0, maxMediaFiles) : [];
+          writeDebugLine(
+            "listen.media.detected",
+            {
+              profile,
+              threadId: message.threadId,
+              msgType: msgType || void 0,
+              mediaKind,
+              hasParsedStructuredContent,
+              remoteMediaUrls,
+              hasQuote: Boolean(quote),
+              quoteOwnerId: quote?.ownerId,
+              quoteGlobalMsgId: quote?.globalMsgId,
+              quoteCliMsgId: quote?.cliMsgId,
+              quoteRemoteMediaUrls
+            },
+            command
+          );
+          const [mediaEntries, quoteMediaEntries] = await Promise.all([
+            mediaKind ? cacheRemoteMediaEntries({
+              profile,
+              urls: remoteMediaUrls,
+              kind: mediaKind,
+              command,
+              warningLabel: "inbound media",
+              debugErrorEvent: "listen.media.cache_error",
+              debugUrlKey: "mediaUrl"
+            }) : Promise.resolve([]),
+            cacheRemoteMediaEntries({
+              profile,
+              urls: quoteRemoteMediaUrls,
+              kind: "file",
+              command,
+              warningLabel: "quoted media",
+              debugErrorEvent: "listen.quote_media.cache_error",
+              debugUrlKey: "quoteMediaUrl"
+            })
+          ]);
+          const localEntries = mediaEntries.filter((entry) => Boolean(entry.mediaPath));
+          const mediaPaths = localEntries.map((entry) => entry.mediaPath);
+          const mediaUrls = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
+          const mediaTypes = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
+          const mediaPath = mediaPaths[0];
+          const mediaUrl = mediaUrls[0];
+          const mediaType = mediaTypes[0];
+          const quoteLocalEntries = quoteMediaEntries.filter((entry) => Boolean(entry.mediaPath));
+          const quoteMediaPaths = quoteLocalEntries.map((entry) => entry.mediaPath);
+          const quoteMediaUrls = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
+          const quoteMediaTypes = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
+          const quoteMediaPath = quoteMediaPaths[0];
+          const quoteMediaUrl = quoteMediaUrls[0];
+          const quoteMediaType = quoteMediaTypes[0];
+          if (quote) {
+            quote = {
+              ...quote,
+              mediaPath: quoteMediaPath,
+              mediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
+              mediaUrl: quoteMediaUrl,
+              mediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : quote.mediaUrls,
+              mediaType: quoteMediaType,
+              mediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0
+            };
+          }
+          const replyContextText = includeReplyContext && quote ? buildReplyContextText(quote) : "";
+          const replyMediaText = includeReplyContext && quoteMediaEntries.length > 0 ? buildReplyMediaAttachedText({ mediaEntries: quoteMediaEntries }) : "";
+          const caption = rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText.trim() : summarizeStructuredContent(msgType, parsedContent);
+          let processedText = mediaEntries.length ? buildMediaAttachedText({
+            mediaEntries,
+            fallbackKind: mediaKind,
+            caption
+          }) : rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText : summarizeStructuredContent(msgType, parsedContent);
+          if (!processedText.trim() && !replyContextText && !replyMediaText) return;
+          if (opts.prefix && processedText.trim().length > 0) {
+            if (!processedText.startsWith(opts.prefix)) return;
+            processedText = processedText.slice(opts.prefix.length).trimStart();
+          }
+          if (replyMediaText) {
+            processedText = processedText.trim() ? `${processedText}
 ${replyMediaText}` : replyMediaText;
-        }
-        if (replyContextText) {
-          processedText = processedText.trim() ? `${processedText}
+          }
+          if (replyContextText) {
+            processedText = processedText.trim() ? `${processedText}
 ${replyContextText}` : replyContextText;
-        }
-        const chatType = message.type === ThreadType.Group ? "group" : "user";
-        const senderId = getStringCandidate(messageData, ["uidFrom"]) || message.data.uidFrom;
-        const senderDisplayNameRaw = getStringCandidate(messageData, [
-          "dName",
-          "fromD",
-          "senderName",
-          "displayName"
-        ]);
-        const senderDisplayName = senderDisplayNameRaw || void 0;
-        const senderNameForMetadata = message.type === ThreadType.Group ? senderDisplayName : void 0;
-        const toId = getStringCandidate(messageData, ["idTo"]) || void 0;
-        const threadName = typeof messageData.threadName === "string" ? messageData.threadName : typeof messageData.tName === "string" ? messageData.tName : void 0;
-        const mentions = extractInboundMentions({
-          messageData,
-          parsedContent,
-          rawText
-        });
-        const mentionIds = mentions.map((item) => item.uid);
-        const timestamp = toEpochSeconds(message.data.ts);
-        const payload = {
-          threadId: message.threadId,
-          targetId: message.threadId,
-          conversationId: message.threadId,
-          msgId: message.data.msgId,
-          cliMsgId: message.data.cliMsgId,
-          content: processedText,
-          type: message.type,
-          timestamp,
-          msgType: msgType || void 0,
-          quote: quote ?? void 0,
-          quoteMediaPath,
-          quoteMediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
-          quoteMediaUrl,
-          quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
-          quoteMediaType,
-          quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
-          mediaPath,
-          mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
-          mediaUrl,
-          mediaUrls: mediaUrls.length > 0 ? mediaUrls : void 0,
-          mediaType,
-          mediaTypes: mediaTypes.length > 0 ? mediaTypes : void 0,
-          mediaKind: mediaKind ?? void 0,
-          mentions: mentions.length > 0 ? mentions : void 0,
-          mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
-          metadata: {
-            isGroup: message.type === ThreadType.Group,
-            chatType,
+          }
+          const chatType = message.type === ThreadType.Group ? "group" : "user";
+          const senderId = getStringCandidate(messageData, ["uidFrom"]) || message.data.uidFrom;
+          const senderDisplayNameRaw = getStringCandidate(messageData, [
+            "dName",
+            "fromD",
+            "senderName",
+            "displayName"
+          ]);
+          const senderDisplayName = senderDisplayNameRaw || void 0;
+          const senderNameForMetadata = message.type === ThreadType.Group ? senderDisplayName : void 0;
+          const toId = getStringCandidate(messageData, ["idTo"]) || void 0;
+          const threadName = typeof messageData.threadName === "string" ? messageData.threadName : typeof messageData.tName === "string" ? messageData.tName : void 0;
+          const mentions = extractInboundMentions({
+            messageData,
+            parsedContent,
+            rawText
+          });
+          const mentionIds = mentions.map((item) => item.uid);
+          const timestamp = toEpochSeconds(message.data.ts);
+          const payload = {
             threadId: message.threadId,
             targetId: message.threadId,
-            threadName,
-            senderName: senderNameForMetadata,
-            senderDisplayName,
-            senderId,
-            fromId: senderId,
-            toId,
+            conversationId: message.threadId,
+            msgId: message.data.msgId,
+            cliMsgId: message.data.cliMsgId,
+            content: processedText,
+            type: message.type,
+            timestamp,
             msgType: msgType || void 0,
             quote: quote ?? void 0,
             quoteMediaPath,
@@ -3257,7 +3855,6 @@ ${replyContextText}` : replyContextText;
             quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
             quoteMediaType,
             quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
-            timestamp,
             mediaPath,
             mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
             mediaUrl,
@@ -3267,147 +3864,222 @@ ${replyContextText}` : replyContextText;
             mediaKind: mediaKind ?? void 0,
             mentions: mentions.length > 0 ? mentions : void 0,
             mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
-            mentionCount: mentions.length > 0 ? mentions.length : void 0
-          },
-          // Backward-compatible convenience fields.
-          chatType,
-          senderId,
-          senderName: senderDisplayName,
-          senderDisplayName,
-          toId,
-          ts: message.data.ts
-        };
-        if (opts.raw) {
-          console.log(JSON.stringify(payload));
-        } else {
-          console.log(
-            `[${chatType}] ${payload.senderName || payload.senderId} -> ${payload.threadId}: ${payload.content}`
-          );
-        }
-        await emitWebhook(payload);
-        if (opts.echo && rawText.trim().length > 0) {
-          try {
-            await api.sendMessage(
-              { msg: processedText },
-              message.threadId,
-              message.type
-            );
-          } catch (error) {
-            console.error(
-              `Echo failed: ${error instanceof Error ? error.message : String(error)}`
+            metadata: {
+              isGroup: message.type === ThreadType.Group,
+              chatType,
+              threadId: message.threadId,
+              targetId: message.threadId,
+              threadName,
+              senderName: senderNameForMetadata,
+              senderDisplayName,
+              senderId,
+              fromId: senderId,
+              toId,
+              msgType: msgType || void 0,
+              quote: quote ?? void 0,
+              quoteMediaPath,
+              quoteMediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
+              quoteMediaUrl,
+              quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
+              quoteMediaType,
+              quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
+              timestamp,
+              mediaPath,
+              mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
+              mediaUrl,
+              mediaUrls: mediaUrls.length > 0 ? mediaUrls : void 0,
+              mediaType,
+              mediaTypes: mediaTypes.length > 0 ? mediaTypes : void 0,
+              mediaKind: mediaKind ?? void 0,
+              mentions: mentions.length > 0 ? mentions : void 0,
+              mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
+              mentionCount: mentions.length > 0 ? mentions.length : void 0
+            },
+            // Backward-compatible convenience fields.
+            chatType,
+            senderId,
+            senderName: senderDisplayName,
+            senderDisplayName,
+            toId,
+            ts: message.data.ts
+          };
+          if (opts.raw) {
+            console.log(JSON.stringify(payload));
+          } else {
+            console.log(
+              `[${chatType}] ${payload.senderName || payload.senderId} -> ${payload.threadId}: ${payload.content}`
             );
           }
-        }
-      });
-      api.listener.on("error", (error) => {
-        writeDebugLine(
-          "listen.error",
-          {
-            profile,
-            message: error instanceof Error ? error.message : String(error),
-            sessionId
-          },
-          command
-        );
-        emitLifecycle("error", {
-          message: error instanceof Error ? error.message : String(error)
-        });
-        console.error(
-          `Listener error: ${error instanceof Error ? error.message : String(error)}`
-        );
-      });
-      await new Promise((resolve) => {
-        let settled = false;
-        let recycleTimer = null;
-        let recycleForceExitTimer = null;
-        let heartbeatTimer = null;
-        let recyclePendingExit = false;
-        let unregisterShutdown = () => {
-        };
-        const finish = () => {
-          if (settled) return;
-          settled = true;
-          if (recycleTimer) {
-            clearTimeout(recycleTimer);
-            recycleTimer = null;
-          }
-          if (recycleForceExitTimer && !recyclePendingExit) {
-            clearTimeout(recycleForceExitTimer);
-            recycleForceExitTimer = null;
-          }
-          if (heartbeatTimer) {
-            clearInterval(heartbeatTimer);
-            heartbeatTimer = null;
+          await emitWebhook(payload);
+          if (opts.echo && rawText.trim().length > 0) {
+            try {
+              await api.sendMessage(
+                { msg: processedText },
+                message.threadId,
+                message.type
+              );
+            } catch (error) {
+              console.error(
+                `Echo failed: ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
           }
-          unregisterShutdown();
-          unregisterShutdown = () => {
-          };
-          resolve();
-        };
-        api.listener.on("closed", (code, reason) => {
-          console.log(`Listener closed (${code}) ${reason || ""}`);
+        });
+        api.listener.on("error", (error) => {
           writeDebugLine(
-            "listen.closed",
+            "listen.error",
             {
               profile,
-              code,
-              reason: reason || void 0,
+              message: error instanceof Error ? error.message : String(error),
               sessionId
             },
             command
           );
-          emitLifecycle("closed", {
-            code,
-            reason: reason || void 0
+          emitLifecycle("error", {
+            message: error instanceof Error ? error.message : String(error)
           });
-          if (!opts.keepAlive || supervised) {
-            finish();
-          }
+          console.error(
+            `Listener error: ${error instanceof Error ? error.message : String(error)}`
+          );
         });
-        const onSignal = () => {
-          try {
-            api.listener.stop();
-          } catch {
-          }
-          finish();
-        };
-        unregisterShutdown = registerShutdownCallback(onSignal);
-        if (lifecycleEventsEnabled && heartbeatMs > 0) {
-          heartbeatTimer = setInterval(() => {
-            emitLifecycle("heartbeat");
-          }, heartbeatMs);
-        }
-        if (recycleEnabled) {
-          recycleTimer = setTimeout(() => {
-            console.error(
-              `Listener recycle triggered after ${recycleMs}ms to prevent stale session.`
-            );
+        await new Promise((resolve) => {
+          let settled = false;
+          let recycleTimer = null;
+          let recycleForceExitTimer = null;
+          let heartbeatTimer = null;
+          let recyclePendingExit = false;
+          let unregisterShutdown = () => {
+          };
+          const finish = () => {
+            if (settled) return;
+            settled = true;
+            if (recycleTimer) {
+              clearTimeout(recycleTimer);
+              recycleTimer = null;
+            }
+            if (recycleForceExitTimer && !recyclePendingExit) {
+              clearTimeout(recycleForceExitTimer);
+              recycleForceExitTimer = null;
+            }
+            if (heartbeatTimer) {
+              clearInterval(heartbeatTimer);
+              heartbeatTimer = null;
+            }
+            if (keepAliveRestartTimer) {
+              clearTimeout(keepAliveRestartTimer);
+              keepAliveRestartTimer = null;
+            }
+            unregisterShutdown();
+            unregisterShutdown = () => {
+            };
+            resolve();
+          };
+          api.listener.on("closed", (code, reason) => {
+            console.log(`Listener closed (${code}) ${reason || ""}`);
             writeDebugLine(
-              "listen.recycle",
+              "listen.closed",
               {
                 profile,
-                recycleMs,
-                exitCode: recycleExitCode,
+                code,
+                reason: reason || void 0,
                 sessionId
               },
               command
             );
-            process.exitCode = recycleExitCode;
-            recyclePendingExit = true;
-            recycleForceExitTimer = setTimeout(() => {
-              recycleForceExitTimer = null;
-              process.exit(recycleExitCode);
-            }, 3e3);
-            recycleForceExitTimer.unref();
+            emitLifecycle("closed", {
+              code,
+              reason: reason || void 0
+            });
+            if (!opts.keepAlive || supervised) {
+              finish();
+              return;
+            }
+            const shouldRestart = keepAliveRestartOnAnyClose || code === 1e3 || code === 3e3;
+            if (!shouldRestart) return;
+            if (keepAliveRestartTimer) {
+              clearTimeout(keepAliveRestartTimer);
+            }
+            keepAliveRestartTimer = setTimeout(() => {
+              keepAliveRestartTimer = null;
+              writeDebugLine(
+                "listen.keepalive.restart",
+                {
+                  profile,
+                  code,
+                  reason: reason || void 0,
+                  delayMs: keepAliveRestartDelayMs,
+                  sessionId
+                },
+                command
+              );
+              try {
+                api.listener.start({ retryOnClose: true });
+              } catch (error) {
+                if (!isListenerAlreadyStarted(error)) {
+                  writeDebugLine(
+                    "listen.keepalive.restart_error",
+                    {
+                      profile,
+                      code,
+                      reason: reason || void 0,
+                      delayMs: keepAliveRestartDelayMs,
+                      message: toErrorText(error),
+                      sessionId
+                    },
+                    command
+                  );
+                }
+              }
+            }, keepAliveRestartDelayMs);
+          });
+          const onSignal = () => {
             try {
               api.listener.stop();
             } catch {
             }
             finish();
-          }, recycleMs);
-        }
-        api.listener.start({ retryOnClose: supervised ? false : Boolean(opts.keepAlive) });
-      });
+          };
+          unregisterShutdown = registerShutdownCallback(onSignal);
+          if (lifecycleEventsEnabled && heartbeatMs > 0) {
+            heartbeatTimer = setInterval(() => {
+              emitLifecycle("heartbeat");
+            }, heartbeatMs);
+          }
+          if (recycleEnabled) {
+            recycleTimer = setTimeout(() => {
+              console.error(
+                `Listener recycle triggered after ${recycleMs}ms to prevent stale session.`
+              );
+              writeDebugLine(
+                "listen.recycle",
+                {
+                  profile,
+                  recycleMs,
+                  exitCode: recycleExitCode,
+                  sessionId
+                },
+                command
+              );
+              process.exitCode = recycleExitCode;
+              recyclePendingExit = true;
+              recycleForceExitTimer = setTimeout(() => {
+                recycleForceExitTimer = null;
+                process.exit(recycleExitCode);
+              }, 3e3);
+              recycleForceExitTimer.unref();
+              try {
+                api.listener.stop();
+              } catch {
+              }
+              finish();
+            }, recycleMs);
+          }
+          api.listener.start({ retryOnClose: supervised ? false : Boolean(opts.keepAlive) });
+        });
+      } finally {
+        unregisterResourceCleanup();
+        await cleanupListenResources();
+      }
     }
   )
 );