@ardennguyen/zalo-agent-cli 2.5.3 → 2.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ardennguyen/zalo-agent-cli",
-    "version": "2.5.3",
+    "version": "2.5.4",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {
@@ -77,6 +77,6 @@
     },
     "allowScripts": {
         "better-sqlite3@13.0.3": true,
-        "@ardennguyen/zalo-agent-cli@2.5.3": true
+        "@ardennguyen/zalo-agent-cli@2.5.4": true
     }
 }

package/src/commands/listen.js

@@ -21,6 +21,8 @@ import {
     spawnDaemonProcess,
 } from "../core/daemon-channel.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
+import { createSocketContext, startEventLoopMonitor } from "../core/daemon-log.js";
+import { setUserInfoLogger } from "../core/user-info.js";
 import { createSocketTap } from "../core/socket-tap.js";
 import { createSelfHeal } from "../core/self-heal.js";
 import { createReadStateSync, readStateEvent } from "../core/read-state.js";
@@ -521,6 +523,17 @@ export function registerListenCommand(program) {
             // and one raw reader on the socket for the fields zca-js drops.
             // Built once, like the receipter: they outlive every re-login.
             const stageLock = createStageLock();
+            // See mcp.js: stage progress, event-loop stalls and refused lookups belong in the log too.
+            const daemonLog = (m) => console.error(`[listen] ${m}`);
+            const loopMonitor = startEventLoopMonitor({
+                log: daemonLog,
+                context: () => {
+                    const held = stageLock.current();
+                    return held ? `the ${held.stage} stage was running` : "";
+                },
+            });
+            const socketContext = createSocketContext({ lock: stageLock, monitor: loopMonitor });
+            setUserInfoLogger(daemonLog);
             const socketTap = createSocketTap({ log: (line) => console.error(`[listen] ${line}`) });
             // Read state other devices report -- a conversation read on the
             // phone, an unread mark set or cleared there -- which zca-js
@@ -812,6 +825,7 @@ export function registerListenCommand(program) {
 
                 // --- Lifecycle events (MUST be on same listener for reconnect to work) ---
                 api.listener.on("connected", () => {
+                    socketContext.markUp();
                     if (reconnectCount > 0) {
                         info(`Reconnected (#${reconnectCount}, uptime: ${uptime()}, events: ${eventCount})`);
                     }
@@ -834,7 +848,7 @@ export function registerListenCommand(program) {
 
                 api.listener.on("disconnected", (code, _reason) => {
                     if (stopping) return;
-                    warning(`Disconnected (code: ${code}). Auto-retrying...`);
+                    warning(`Disconnected (code: ${code}). Auto-retrying... (${socketContext.describe()})`);
                     // First drop wins: a flapping socket that emits several
                     // `disconnected` before one `connected` is ONE outage, and the
                     // gap must span from the start of it.
@@ -854,7 +868,9 @@ export function registerListenCommand(program) {
                     reconnectCount++;
                     if (downSince === null) downSince = Date.now();
                     syncManager.markDisconnected();
-                    warning(`Connection closed (code: ${code}). Re-login in 5s... (uptime: ${uptime()})`);
+                    warning(
+                        `Connection closed (code: ${code}). Re-login in 5s... (uptime: ${uptime()}; ${socketContext.describe()})`,
+                    );
                     await new Promise((r) => setTimeout(r, 5000));
                     try {
                         clearSession();
@@ -975,6 +991,8 @@ export function registerListenCommand(program) {
                     runners: createSyncRunners({
                         getApi,
                         accountName: activeAcc.ownId,
+                        log: daemonLog,
+                        monitor: loopMonitor,
                         onSelfName: (name) => updateAccountName(activeAcc.ownId, name),
                     }),
                     // The self-heal's lock: a stage and a catch-up never share the socket.

package/src/commands/mcp.js

@@ -26,6 +26,8 @@ import {
 import { success, error, info, output } from "../utils/output.js";
 import { resolveWebhookSecret } from "../utils/secrets.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
+import { createSocketContext, startEventLoopMonitor } from "../core/daemon-log.js";
+import { setUserInfoLogger } from "../core/user-info.js";
 import { createSyncJobs } from "../mcp/sync-jobs.js";
 import { createSocketTap } from "../core/socket-tap.js";
 import { createSelfHeal } from "../core/self-heal.js";
@@ -462,9 +464,24 @@ export function registerMCPCommands(program) {
             // the server so the tools can hold it too.
             const onSelfName = (name) => updateAccountName(activeAcc.ownId, name);
             const stageLock = createStageLock();
+            // What daemon.log learns beyond one-line events: every stage's progress (the restore used to
+            // report only to the caller), the event loop's stalls (a blocked loop cannot answer the socket's
+            // pings, and a bare close 1006 says nothing else), and what Zalo said when a lookup was refused.
+            const daemonLog = (m) => console.error(`[mcp] ${m}`);
+            const loopMonitor = startEventLoopMonitor({
+                log: daemonLog,
+                context: () => {
+                    const held = stageLock.current();
+                    return held ? `the ${held.stage} stage was running` : "";
+                },
+            });
+            const socketContext = createSocketContext({ lock: stageLock, monitor: loopMonitor });
+            setUserInfoLogger(daemonLog);
             const syncRunners = createSyncRunners({
                 getApi,
                 accountName: activeAcc.ownId,
+                log: daemonLog,
+                monitor: loopMonitor,
                 onSelfName,
                 onMessagesRestored: () => {
                     for (const [tid, info] of getThreadNames()) {
@@ -790,6 +807,7 @@ export function registerMCPCommands(program) {
                 });
 
                 api.listener.on("connected", () => {
+                    socketContext.markUp();
                     if (reconnectCount > 0) {
                         console.error(`[mcp] Reconnected (#${reconnectCount})`);
                     }
@@ -798,7 +816,7 @@ export function registerMCPCommands(program) {
 
                 api.listener.on("disconnected", (code) => {
                     if (lifecycle.isStopping()) return;
-                    console.error(`[mcp] Disconnected (code: ${code}). Auto-retrying...`);
+                    console.error(`[mcp] Disconnected (code: ${code}). Auto-retrying... (${socketContext.describe()})`);
                     lifecycle.noteDown();
                 });
 
@@ -812,7 +830,7 @@ export function registerMCPCommands(program) {
                     }
                     reconnectCount++;
                     console.error(
-                        `[mcp] Connection closed (code: ${code}). Re-login in 5s... (reconnect #${reconnectCount})`,
+                        `[mcp] Connection closed (code: ${code}). Re-login in 5s... (reconnect #${reconnectCount}; ${socketContext.describe()})`,
                     );
                     await new Promise((r) => setTimeout(r, 5000));
                     try {

package/src/core/current-user-names.js

@@ -1,3 +1,8 @@
+import { runPacedBatches, userInfoLog } from "./user-info.js";
+
+/** The default `log`: silent unless a daemon registered a sink with `setUserInfoLogger`. */
+const NO_LOG = () => {};
+
 /**
  * Read the account's complete alias snapshot. Do not reuse a previous snapshot:
  * an absent entry means the owner removed that alias. Failed/partial reads do
@@ -57,23 +62,38 @@ export function currentUserName(uid, profile, aliases = new Map()) {
  * @param {object} [options]
  * @returns {Promise<Map<string, {name: string, source: string}>>} UID -> current label
  */
-export async function resolveCurrentUserNames(api, uids, { aliases, profiles = new Map(), log = () => {} } = {}) {
+export async function resolveCurrentUserNames(api, uids, { aliases, profiles = new Map(), log = NO_LOG } = {}) {
     const ids = [...new Set(uids.filter(Boolean).map(String))];
     if (!ids.length) return new Map();
     const aliasRequest = aliases ? Promise.resolve(aliases) : readUserAliases(api, log);
     const fresh = new Map(profiles);
     const missing = ids.filter((id) => /^[1-9][0-9]*$/.test(id) && !fresh.has(id));
-    for (let i = 0; i < missing.length; i += 100) {
-        try {
-            if (typeof api?.getUserInfo !== "function") break;
-            const result = await api.getUserInfo(missing.slice(i, i + 100));
+    // A live-API proxy throws on any property read while a session is re-logging in, so even the probe is guarded.
+    let canLookup = false;
+    try {
+        canLookup = typeof api?.getUserInfo === "function";
+    } catch {
+        /* session is reconnecting: fall back to aliases or UIDs */
+    }
+    if (missing.length && canLookup) {
+        // Paced, retried on a rate limit and stopped when Zalo keeps refusing; what Zalo said is logged.
+        const lookup = await runPacedBatches(missing, {
+            batchSize: 100,
+            label: "user-info",
+            log: log === NO_LOG ? undefined : log,
+            call: (batch) => api.getUserInfo(batch),
+        });
+        for (const result of lookup.results) {
             for (const bag of [result?.changed_profiles, result?.unchanged_profiles]) {
                 for (const [uid, profile] of Object.entries(bag || {})) {
                     if (profile) fresh.set(uid, profile);
                 }
             }
-        } catch {
-            log("current profiles unavailable; falling back to aliases or UIDs");
+        }
+        if (lookup.failed || lookup.skippedIds) {
+            (log === NO_LOG ? userInfoLog : log)(
+                "current profiles unavailable for some ids; falling back to aliases or UIDs",
+            );
         }
     }
     const ownedAliases = await aliasRequest;

package/src/core/daemon-log.js

@@ -0,0 +1,250 @@
+/**
+ * What a daemon writes to daemon.log while it works, beyond the one-line events.
+ *
+ * Run directly, `zalo-agent sync` prints every phase as it happens. Run by a
+ * daemon -- the same restore, started by `zalo-agent sync` over the loopback
+ * channel or by the MCP tool `zalo_sync` -- the progress went to the CLI that
+ * asked, or into a 20-event ring behind `zalo_sync_status`, and daemon.log got
+ * "running the messages stage" and, much later, "finished" or "failed: <one
+ * line>". When a 100,000-message restore died with close code 1006 or hit a
+ * lookup limit, the log held nothing that said what the restore was doing, how
+ * long it had been going, or whether the process had been too busy to answer
+ * the socket's pings.
+ *
+ * Three small pieces fix that, each taking its `log` as an argument so a
+ * daemon decides where lines go and tests can read them:
+ *
+ *   - createStageLogger: one stage's parameters, every progress phase with the
+ *     time since it started, a periodic "still running" line, and the result
+ *     or the failure with its code and cause.
+ *   - startEventLoopMonitor: a stall of the event loop, in seconds. The restore
+ *     decodes and stores on the same thread that answers the socket, and a
+ *     blocked loop is the one cause of a bare close 1006 that nothing else
+ *     records.
+ *   - createSocketContext: what to say about the socket when it closes -- how
+ *     long it was up, what stage was running, how bad the worst stall was.
+ */
+
+/** A stall shorter than this is not worth a line. */
+export const DEFAULT_STALL_WARN_MS = 3000;
+
+const seconds = (ms) => (ms / 1000).toFixed(1);
+
+/** `1h02m03s`, `4m05s` or `7s`. */
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h) return `${h}h${String(m).padStart(2, "0")}m${String(s).padStart(2, "0")}s`;
+    if (m) return `${m}m${String(s).padStart(2, "0")}s`;
+    return `${s}s`;
+}
+
+/**
+ * An error with everything that helps: its type, message, Zalo's code, the
+ * cause chain and the top of the stack.
+ *
+ * @param {unknown} e
+ * @returns {string}
+ */
+export function describeError(e) {
+    if (!e || typeof e !== "object") return String(e);
+    const parts = [`${e.name && e.name !== "Error" ? `${e.name}: ` : ""}${e.message ?? String(e)}`];
+    if (e.code !== undefined && e.code !== null) parts.push(`(code ${e.code})`);
+    let cause = e.cause;
+    for (let depth = 0; cause && depth < 3; depth++, cause = cause.cause) {
+        parts.push(
+            `<- ${cause.name && cause.name !== "Error" ? `${cause.name}: ` : ""}${cause.message ?? String(cause)}`,
+        );
+    }
+    const stack = String(e.stack || "")
+        .split("\n")
+        .slice(1, 4)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    return stack.length ? `${parts.join(" ")} [${stack.join(" | ")}]` : parts.join(" ");
+}
+
+/**
+ * Scalar fields of a result as `key=value`, for the "finished" line.
+ *
+ * @param {unknown} result
+ * @returns {string}
+ */
+export function summarizeResult(result) {
+    if (!result || typeof result !== "object") return result === undefined ? "" : String(result);
+    return Object.entries(result)
+        .filter(([, v]) => ["string", "number", "boolean"].includes(typeof v) && String(v).length <= 80)
+        .slice(0, 14)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(" ");
+}
+
+/**
+ * Start watching the event loop for stalls.
+ *
+ * @param {object} args
+ * @param {(message: string) => void} args.log
+ * @param {number} [args.warnMs] - stalls at least this long are logged
+ * @param {number} [args.intervalMs]
+ * @param {() => string} [args.context] - what to add to a stall line, e.g. the running stage
+ * @param {() => number} [args.now] - test seam
+ * @param {{setInterval: Function, clearInterval: Function}} [args.timers] - test seam
+ * @returns {{stop: () => void, takeMax: () => number, tick: () => void}} `takeMax` returns
+ *   the worst stall in ms since the last call and resets it; `tick` is exposed for tests
+ */
+export function startEventLoopMonitor({
+    log,
+    warnMs = DEFAULT_STALL_WARN_MS,
+    intervalMs = 1000,
+    context = () => "",
+    now = Date.now,
+    timers = { setInterval, clearInterval },
+}) {
+    let last = now();
+    let max = 0;
+    const tick = () => {
+        const t = now();
+        const stall = Math.max(0, t - last - intervalMs);
+        last = t;
+        if (stall > max) max = stall;
+        if (stall >= warnMs) {
+            const where = context();
+            log(
+                `event loop was blocked for ${seconds(stall)}s${where ? ` while ${where}` : ""}: ` +
+                    "socket pings and reads were not served in that time",
+            );
+        }
+    };
+    const id = timers.setInterval(tick, intervalMs);
+    id?.unref?.();
+    return {
+        tick,
+        stop: () => timers.clearInterval(id),
+        takeMax: () => {
+            const m = max;
+            max = 0;
+            return m;
+        },
+    };
+}
+
+/**
+ * Logging for one sync stage run.
+ *
+ * `live` events (a live message stored while the stage runs) can be one per
+ * message, so they are counted and summarized, not printed one by one.
+ *
+ * @param {object} args
+ * @param {string} args.stage - "messages", "reactions", "history"
+ * @param {(message: string) => void} args.log
+ * @param {number} [args.heartbeatMs] - how often a "still running" line is written
+ * @param {number} [args.liveFlushMs] - how often the live-event count is written
+ * @param {() => number} [args.now] - test seam
+ * @param {{setInterval: Function, clearInterval: Function}} [args.timers] - test seam
+ * @param {{takeMax: () => number}} [args.monitor] - event-loop monitor, for the worst stall per interval
+ * @returns {{start: (params?: object) => void, event: (e: object) => void,
+ *   finish: (result?: unknown) => void, fail: (error: unknown) => void, stop: () => void}}
+ */
+export function createStageLogger({
+    stage,
+    log,
+    heartbeatMs = 60000,
+    liveFlushMs = 30000,
+    now = Date.now,
+    timers = { setInterval, clearInterval },
+    monitor = null,
+}) {
+    const tag = `[sync:${stage}]`;
+    let startedAt = now();
+    let lastEventAt = startedAt;
+    let lastEvent = "";
+    let liveCount = 0;
+    let liveFlushedAt = startedAt;
+    let timer = null;
+
+    const elapsed = () => formatDuration(now() - startedAt);
+    const flushLive = () => {
+        if (!liveCount) return;
+        log(`${tag} +${elapsed()} stored ${liveCount} live event(s) while running`);
+        liveCount = 0;
+        liveFlushedAt = now();
+    };
+    const heartbeat = () => {
+        const quiet = now() - lastEventAt;
+        const stall = monitor?.takeMax?.() ?? 0;
+        log(
+            `${tag} still running: +${elapsed()}, last progress ${formatDuration(quiet)} ago` +
+                (lastEvent ? ` (${lastEvent})` : "") +
+                (stall >= 1000 ? `, worst event-loop stall ${seconds(stall)}s` : ""),
+        );
+    };
+
+    return {
+        start(params = {}) {
+            startedAt = now();
+            lastEventAt = startedAt;
+            liveFlushedAt = startedAt;
+            const shown = Object.entries(params || {})
+                .filter(([, v]) => v !== undefined && v !== null && typeof v !== "object")
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" ");
+            log(`${tag} started${shown ? ` (${shown})` : ""}`);
+            timer = timers.setInterval(heartbeat, heartbeatMs);
+            timer?.unref?.();
+        },
+        event(e) {
+            const phase = String(e?.phase ?? "progress");
+            lastEventAt = now();
+            if (phase === "live") {
+                liveCount++;
+                if (now() - liveFlushedAt >= liveFlushMs) flushLive();
+                return;
+            }
+            const detail = String(e?.detail ?? "");
+            lastEvent = `${phase}${detail ? `: ${detail.slice(0, 80)}` : ""}`;
+            log(`${tag} +${elapsed()} ${phase}${detail ? `: ${detail}` : ""}`);
+        },
+        finish(result) {
+            flushLive();
+            const summary = summarizeResult(result);
+            log(`${tag} finished in ${elapsed()}${summary ? `: ${summary}` : ""}`);
+        },
+        fail(error) {
+            flushLive();
+            log(`${tag} failed after ${elapsed()}: ${describeError(error)}`);
+        },
+        stop() {
+            if (timer) timers.clearInterval(timer);
+            timer = null;
+        },
+    };
+}
+
+/**
+ * What to say about the socket when it drops or closes.
+ *
+ * @param {object} args
+ * @param {{current: () => ({stage: string, startedAt: number}|null)}} [args.lock] - the daemon's stage lock
+ * @param {{takeMax: () => number}} [args.monitor] - event-loop monitor
+ * @param {() => number} [args.now] - test seam
+ * @returns {{markUp: () => void, describe: () => string}}
+ */
+export function createSocketContext({ lock = null, monitor = null, now = Date.now } = {}) {
+    let upSince = null;
+    return {
+        markUp() {
+            upSince = now();
+        },
+        describe() {
+            const parts = [];
+            parts.push(upSince === null ? "socket age unknown" : `socket was up ${formatDuration(now() - upSince)}`);
+            const held = lock?.current?.();
+            if (held) parts.push(`stage in progress: ${held.stage} for ${formatDuration(now() - held.startedAt)}`);
+            const stall = monitor?.takeMax?.() ?? 0;
+            if (stall >= 1000) parts.push(`worst event-loop stall since the last check ${seconds(stall)}s`);
+            return parts.join("; ");
+        },
+    };
+}

package/src/core/daemon-sync.js

@@ -30,6 +30,7 @@
 import { SyncV2 } from "./sync-v2/index.js";
 import { drainReactions, placeUnresolvedReactions } from "./sync-v2/reactions.js";
 import { fetchAndCacheHistory } from "./history-fetch.js";
+import { createStageLogger } from "./daemon-log.js";
 
 /**
  * True while the listener's socket is connecting or open.
@@ -47,6 +48,103 @@ function socketAlive(api) {
     return Boolean(ws) && ws.readyState <= 1;
 }
 
+/**
+ * Wait for the daemon's own recovery to put a live socket back.
+ *
+ * A stage that loses its socket must not open one itself: `listen` and `mcp`
+ * answer a close by logging in again and rebuilding the api, and a stage
+ * tearing the old socket down or starting a new one would race that. So this
+ * only WATCHES `getApi()` -- it never starts, stops or logs in anything -- and
+ * returns once the daemon's api has an OPEN socket that is not the one the
+ * stage lost.
+ *
+ * @param {object} args
+ * @param {() => object} args.getApi - the daemon's current api
+ * @param {object|null} args.lostWs - the socket object the stage was using
+ * @param {object|null} args.lostApi - the api object the stage was using
+ * @param {number} [args.timeoutMs]
+ * @param {number} [args.pollMs]
+ * @param {(message: string) => void} [args.log]
+ * @param {(ms: number) => Promise<void>} [args.sleep] - test seam
+ * @param {() => number} [args.now] - test seam
+ * @returns {Promise<{api: object}|null>} the api to continue on, or null when none came back in time
+ */
+export async function waitForDaemonSocket({
+    getApi,
+    lostWs,
+    lostApi,
+    timeoutMs = 120000,
+    pollMs = 500,
+    log = () => {},
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now = Date.now,
+}) {
+    const startedAt = now();
+    log(`the socket was lost mid-stage; waiting up to ${Math.round(timeoutMs / 1000)}s for the daemon to reconnect`);
+    for (;;) {
+        let api = null;
+        try {
+            api = getApi();
+        } catch {
+            /* the daemon is between sessions */
+        }
+        const ws = api?.listener?.ws;
+        if (ws && ws.readyState === 1 && (api !== lostApi || ws !== lostWs)) {
+            log(`the daemon reconnected after ${((now() - startedAt) / 1000).toFixed(1)}s; resuming the stage`);
+            return { api };
+        }
+        if (now() - startedAt >= timeoutMs) {
+            log(
+                `the daemon did not reconnect within ${Math.round(timeoutMs / 1000)}s; the stage ends with what it has`,
+            );
+            return null;
+        }
+        await sleep(pollMs);
+    }
+}
+
+/**
+ * Wrap each runner so it writes to the daemon's log.
+ *
+ * Here, rather than in the channel route or the MCP job tracker, because both
+ * of those call the same runners: the channel streams events to the CLI that
+ * asked and the job tracker keeps the last twenty, and neither wrote anything
+ * to daemon.log. Wrapping the runners covers `zalo-agent sync`, `msg history`
+ * and the `zalo_sync` tool alike.
+ *
+ * @param {Record<string, Function>} runners
+ * @param {{log: (message: string) => void, monitor: object|null}} deps
+ * @returns {Record<string, Function>}
+ */
+function traceRunners(runners, { log, monitor }) {
+    return Object.fromEntries(
+        Object.entries(runners).map(([stage, run]) => [
+            stage,
+            async (params = {}, onEvent = () => {}) => {
+                const trace = createStageLogger({ stage, log, monitor });
+                trace.start(params);
+                try {
+                    const result = await run(params, (event) => {
+                        try {
+                            trace.event(event);
+                        } catch {
+                            /* a logging problem never reaches the stage */
+                        }
+                        onEvent(event);
+                    });
+                    trace.finish(result);
+                    return result;
+                } catch (error) {
+                    trace.fail(error);
+                    throw error;
+                } finally {
+                    trace.stop();
+                }
+            },
+        ]),
+    );
+}
+
 /**
  * Build the stage runners for `startDaemonChannel({ runners })`.
  *
@@ -55,9 +153,20 @@ function socketAlive(api) {
  * @param {string} args.accountName - ownId; picks the account data dir
  * @param {(res: object) => void|Promise<void>} [args.onMessagesRestored] - optional hook after messages restore
  * @param {(name: string) => void|Promise<void>} [args.onSelfName] - optional hook when active account's profile name is refreshed
+ * @param {(message: string) => void} [args.log] - where each stage writes its parameters, every progress
+ *   phase, a periodic "still running" line and its result or failure (daemon.log); silent without it
+ * @param {{takeMax: () => number}} [args.monitor] - event-loop monitor; its worst stall is added to the
+ *   "still running" lines
  * @returns {Record<string, (params: object, onEvent: (e: object) => void) => Promise<object>>}
  */
-export function createSyncRunners({ getApi, accountName, onMessagesRestored, onSelfName }) {
+export function createSyncRunners({
+    getApi,
+    accountName,
+    onMessagesRestored,
+    onSelfName,
+    log = () => {},
+    monitor = null,
+}) {
     /** The live api, or a refusal the CLI can print. */
     const liveApi = (what) => {
         const api = getApi();
@@ -65,7 +174,7 @@ export function createSyncRunners({ getApi, accountName, onMessagesRestored, onS
         return api;
     };
 
-    return {
+    const runners = {
         /**
          * transfer-sync-v2 message restore (socket cmd 590/591).
          *
@@ -81,6 +190,8 @@ export function createSyncRunners({ getApi, accountName, onMessagesRestored, onS
          */
         async messages(params = {}, onEvent = () => {}) {
             const api = liveApi("restore");
+            // The api and socket the stage is on, kept current across reconnects.
+            let current = { api, ws: api.listener?.ws ?? null };
             const res = await new SyncV2(api, accountName).restore({
                 days: params.days ?? null,
                 from: params.from,
@@ -95,13 +206,31 @@ export function createSyncRunners({ getApi, accountName, onMessagesRestored, onS
                 // the server's own 180s interval, which is the entire width of
                 // the phone wait. So the restore keeps its own.
                 keepAlive: true,
-                // Deliberately NO `reconnect`. The CLI passes one because it
-                // owns the socket's lifecycle for the length of the run; here
-                // the daemon does, and it reconnects on its own terms --
-                // `listen`/`mcp` answer a close by re-logging-in and rebuilding
-                // the api. A stage tearing the socket down underneath that
-                // would race it. A socket lost mid-stage therefore ends as a
-                // partial restore and the daemon recovers the session.
+                // A `reconnect` that only WAITS. The CLI passes one that opens the
+                // socket itself, because it owns the socket's lifecycle for the
+                // length of the run; here the daemon does, and it reconnects on
+                // its own terms -- `listen`/`mcp` answer a close by re-logging-in
+                // and rebuilding the api, and a stage tearing the socket down or
+                // starting one would race that. So this never touches the
+                // listener: it watches `getApi()` until the daemon's recovery has
+                // an open socket, then hands that api back and the restore
+                // re-requests the batches that never arrived. Before this, any
+                // lost socket (close 1006, which Zalo does not offer to retry) ended
+                // a long restore as partial and the next one asked the phone again.
+                // A long restore on a busy account can lose its socket more than once, so a daemon allows
+                // three resumes (the CLI's default is one); `params.maxResumes` overrides.
+                maxResumes: Number.isInteger(params.maxResumes) ? params.maxResumes : 3,
+                reconnect: async () => {
+                    const back = await waitForDaemonSocket({
+                        getApi,
+                        lostWs: current.ws,
+                        lostApi: current.api,
+                        timeoutMs: Number(params.reconnectWaitMs) || undefined,
+                        log: (m) => log(`[sync:messages] ${m}`),
+                    });
+                    if (back) current = { api: back.api, ws: back.api.listener?.ws ?? null };
+                    return back;
+                },
                 onStatus: onEvent,
                 onSelfName,
             });
@@ -189,4 +318,6 @@ export function createSyncRunners({ getApi, accountName, onMessagesRestored, onS
             };
         },
     };
+
+    return traceRunners(runners, { log, monitor });
 }

package/src/core/sync-v2/gid.js

@@ -19,6 +19,7 @@
  */
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { runPacedBatches } from "../user-info.js";
 
 const require = createRequire(import.meta.url);
 
@@ -68,15 +69,13 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
         return out;
     }
     const idToUser = new Map();
-    for (let i = 0; i < globalIds.length; i += GID_BATCH) {
-        const batch = globalIds.slice(i, i + GID_BATCH);
-        let map;
-        try {
-            map = await gidDecrypt(batch);
-        } catch (e) {
-            log(`gid/decrypt batch failed (${e.message})`);
-            continue;
-        }
+    const decrypted = await runPacedBatches(globalIds, {
+        batchSize: GID_BATCH,
+        label: "gid/decrypt",
+        log,
+        call: (batch) => gidDecrypt(batch),
+    });
+    for (const map of decrypted.results) {
         for (const [gid, uid] of Object.entries(map || {})) if (uid) idToUser.set(gid, String(uid));
     }
     if (!idToUser.size) return out;
@@ -85,20 +84,21 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
     const names = new Map();
     const zaloNames = new Map();
     const uids = [...new Set([...idToUser.values()])];
-    for (let i = 0; i < uids.length; i += NAME_BATCH) {
-        const batch = uids.slice(i, i + NAME_BATCH);
-        try {
-            const info = await api.getUserInfo(batch);
-            for (const bag of [info?.changed_profiles, info?.unchanged_profiles]) {
-                for (const [uid, p] of Object.entries(bag || {})) {
-                    if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
-                    if (p?.zaloName) zaloNames.set(uid, p.zaloName);
-                }
+    const named = await runPacedBatches(uids, {
+        batchSize: NAME_BATCH,
+        label: "getUserInfo",
+        log,
+        call: (batch) => api.getUserInfo(batch),
+    });
+    for (const info of named.results) {
+        for (const bag of [info?.changed_profiles, info?.unchanged_profiles]) {
+            for (const [uid, p] of Object.entries(bag || {})) {
+                if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
+                if (p?.zaloName) zaloNames.set(uid, p.zaloName);
             }
-        } catch (e) {
-            log(`getUserInfo batch failed (${e.message}); some names may be blank`);
         }
     }
+    if (named.failed || named.skippedIds) log("some names may be blank (getUserInfo did not answer for every batch)");
 
     for (const [gid, uid] of idToUser)
         out.set(gid, { id: uid, name: names.get(uid) || "", zaloName: zaloNames.get(uid) || "" });

package/src/core/sync-v2/index.js

@@ -82,6 +82,18 @@ const DEFAULT_WAVE_SIZE = 4;
  * dying.
  */
 const MAX_RESUMES = 1;
+/** The most reconnects a caller may ask a single restore to attempt. */
+const MAX_RESUMES_CAP = 5;
+
+/**
+ * How many reconnects a restore may spend: the caller's `maxResumes` (a whole number, capped), else one.
+ *
+ * @param {unknown} requested
+ * @returns {number}
+ */
+export function resolveMaxResumes(requested) {
+    return Number.isInteger(requested) ? Math.min(MAX_RESUMES_CAP, Math.max(0, requested)) : MAX_RESUMES;
+}
 const DAY_MS = 24 * 60 * 60 * 1000;
 
 /**
@@ -277,6 +289,21 @@ export function resolveWaitBudget(budgetMs, fallbackMs) {
     return 30000;
 }
 
+/**
+ * The api a `reconnect` callback handed back, if it handed one.
+ *
+ * `true` means "the same listener is live again" (the CLI re-opens the socket on
+ * the api it already has). `{api}` means the caller recovered by building a new
+ * api, as a daemon does after logging in again, and the restore has to carry on
+ * over that api's listener instead.
+ *
+ * @param {unknown} back - what `opts.reconnect()` resolved
+ * @returns {object|null} the new api, or null when the old one is still the one
+ */
+export function reconnectedApi(back) {
+    return back && typeof back === "object" && back.api?.listener ? back.api : null;
+}
+
 /**
  * Which shards still have to go out, and whether a dropped socket is worth one
  * more reconnect.
@@ -481,17 +508,43 @@ export class SyncV2 {
         }
     }
 
-    /** Refresh existing DM peers outside the requested message window, including non-friends. */
-    async _refreshDmNames(threadMap) {
+    /**
+     * Refresh existing DM peers outside the requested message window, including non-friends.
+     *
+     * Every restore used to look up every non-friend DM peer in the cache: on a busy account that
+     * is thousands of ids, each restore, and Zalo answered with a limit. So the run asks for at most
+     * `maxLookups` of them (500 unless ZALO_SYNC_NAME_REFRESH_MAX says otherwise), peers whose
+     * cached title is missing or just their id first, because those are the ones a restore can
+     * actually improve. The rest keep the titles they have until a later restore reaches them.
+     *
+     * @param {Map<string, object>} threadMap
+     * @param {(message: string) => void} [log]
+     */
+    async _refreshDmNames(threadMap, log = () => {}) {
         const profiles = new Map(
             [...threadMap.values()]
                 .filter((t) => t.type === "dm" && t.zaloName)
                 .map((t) => [t.id, { zaloName: t.zaloName }]),
         );
+        const peers = getRecentThreads(-1, "dm");
+        const unknown = (t) => !t.name || String(t.name) === String(t.threadId);
+        const wanted = peers.filter((t) => !profiles.has(String(t.threadId)));
+        wanted.sort((a, b) => Number(unknown(b)) - Number(unknown(a)));
+        const envCap = Number.parseInt(process.env.ZALO_SYNC_NAME_REFRESH_MAX ?? "", 10);
+        const maxLookups = Number.isFinite(envCap) && envCap >= 0 ? envCap : 500;
+        const chosen = wanted.slice(0, maxLookups);
+        if (wanted.length) {
+            log(
+                `refreshing ${chosen.length} of ${wanted.length} non-friend DM peer name(s)` +
+                    (chosen.length < wanted.length
+                        ? ` (cap ${maxLookups}; the rest keep their cached titles until a later restore)`
+                        : ""),
+            );
+        }
         const names = await resolveCurrentUserNames(
             this.api,
-            getRecentThreads(-1, "dm").map((t) => String(t.threadId)),
-            { aliases: this.userAliases, profiles },
+            [...profiles.keys(), ...chosen.map((t) => String(t.threadId))],
+            { aliases: this.userAliases, profiles, log },
         );
         for (const [id, current] of names) {
             upsertThread({ threadId: id, type: "dm", name: current.name, lastUpdate: 0 });
@@ -561,9 +614,13 @@ export class SyncV2 {
      * @param {boolean} [opts.liveStore=true] false when the caller already taps live traffic
      * @param {number|false} [opts.keepAlive] heartbeat interval in ms, or false when the
      *   caller already pings this socket for the whole window it owns.
-     * @param {() => Promise<boolean>} [opts.reconnect] re-open the listener socket after a
-     *   drop and resolve true once it is live. Supplied by the caller because this class
+     * @param {number} [opts.maxResumes] reconnects this run may spend (default 1, at most 5); each one
+     *   that needs the phone's confirmation again costs the owner a tap.
+     * @param {() => Promise<boolean|{api: object}>} [opts.reconnect] re-open the listener socket
+     *   after a drop and resolve true once it is live. Supplied by the caller because this class
      *   never starts or stops the listener itself. Without it a dropped socket ends the run.
+     *   A caller that cannot reuse the old listener (a daemon, which re-logs-in and builds a new
+     *   api) resolves `{api}` instead: the restore carries on over that api's listener.
      * @returns {Promise<{conversations:number, messagesSaved:number, threadsMapped:number, threadsUnmapped:number, reason:string, days:number|null, from:number, confirmed:boolean, resumes:number, rePrompted:boolean}>}
      */
     async restore(opts = {}) {
@@ -586,10 +643,12 @@ export class SyncV2 {
 
         initDb(resolve(this.accountDir, "zalo.db"));
         this._refreshThreadNames(threadMap);
-        await this._refreshDmNames(threadMap);
+        await this._refreshDmNames(threadMap, log);
         await this._refreshSelfName(opts.onSelfName);
 
-        const L = this.api.listener;
+        // `let`: a daemon recovers a lost socket by logging in again, which builds a new api and a new
+        // listener, and `opts.reconnect` can hand that api back (see `reconnect` below).
+        let L = this.api.listener;
         const sessions = new Map(); // syncId -> {kind, batches:[], statuses:[], done, err}
         const onMsg = async (buf) => {
             if (!(buf instanceof Buffer) || buf.length < 4 || buf.readUInt16LE(1) !== 601) return;
@@ -734,7 +793,14 @@ export class SyncV2 {
             detachSocketTaps();
             let ok = false;
             try {
-                ok = Boolean(await opts.reconnect());
+                const back = await opts.reconnect();
+                ok = Boolean(back);
+                // A new api means a new listener: the old one's socket is gone for good.
+                const next = ok ? reconnectedApi(back) : null;
+                if (next) {
+                    this.api = next;
+                    L = next.listener;
+                }
             } catch (e) {
                 onStatus({ phase: "warn", detail: `reconnect failed: ${e?.message || e}` });
                 return false;
@@ -1072,7 +1138,7 @@ export class SyncV2 {
             // to reconnect -- this class never starts the listener itself.
             const schedule = createShardSchedule(shards.length, {
                 waveSize,
-                maxResumes: typeof opts.reconnect === "function" ? MAX_RESUMES : 0,
+                maxResumes: typeof opts.reconnect === "function" ? resolveMaxResumes(opts.maxResumes) : 0,
             });
 
             // ---- wave by wave: send, wait, decrypt, decode, store ----
@@ -1228,7 +1294,7 @@ export class SyncV2 {
                     runDeadline = Date.now() + shardBudget(schedule.remaining());
                     onStatus({
                         phase: "reconnect",
-                        detail: `reconnected — re-requesting the ${schedule.remaining()} batch(es) that never arrived (attempt ${schedule.resumes()} of ${MAX_RESUMES})`,
+                        detail: `reconnected — re-requesting the ${schedule.remaining()} batch(es) that never arrived (attempt ${schedule.resumes()} of ${resolveMaxResumes(opts.maxResumes)})`,
                     });
                     continue;
                 }

package/src/core/user-info.js

@@ -0,0 +1,170 @@
+/**
+ * Batched profile lookups that notice a rate limit instead of hammering through it.
+ *
+ * `getUserInfo` (names for user ids) and `/api/gid/decrypt` (opaque 1-1 ids to
+ * user ids) take at most 100 / 50 ids per request. A restore of a busy account
+ * (100,000 messages in 90 days, thousands of non-friend conversations) asks for
+ * thousands of ids, so it sends dozens of these requests back to back, and
+ * Zalo answers with a "limit reached" error. The old loops swallowed that
+ * error with a fixed message and went on to the next batch, so every remaining
+ * batch failed the same way, the real error text was never written anywhere,
+ * and the next restore started from zero again.
+ *
+ * This runs the batches one at a time with a short gap, retries a rate-limit
+ * answer with a growing wait, stops the whole lookup after a rate limit that
+ * persists (or after several failures in a row, whatever their text), and
+ * writes what Zalo actually said -- code and message -- through `log`. The
+ * callers keep their contract: a lookup that gives up leaves the names it did
+ * not get blank or as ids, and nothing here throws.
+ */
+
+/** Wait between two requests of one lookup. */
+export const DEFAULT_GAP_MS = 300;
+/** Waits before each retry of a rate-limited batch. */
+export const DEFAULT_BACKOFF_MS = Object.freeze([2000, 5000, 15000]);
+/** Consecutive failed batches (any error) after which the rest are not attempted. */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+
+/** What a rate-limit answer reads like. Zalo's wording was not captured, so this is deliberately loose. */
+const RATE_LIMIT_TEXT = /limit|giới hạn|too many|quá nhiều|frequen|tần suất|rate|throttl|try again later/i;
+/** Codes Zalo uses for "too many requests" elsewhere in this CLI (friend requests: 221). */
+const RATE_LIMIT_CODES = new Set([221, 429]);
+
+let sink = null;
+
+/**
+ * Where lookups write their diagnostics when the caller passes no `log`.
+ * Daemons point this at their log; one-shot commands leave it unset and stay quiet.
+ *
+ * @param {((message: string) => void)|null} fn
+ */
+export function setUserInfoLogger(fn) {
+    sink = typeof fn === "function" ? fn : null;
+}
+
+/**
+ * Write one diagnostic line to the registered sink, if any.
+ *
+ * @param {string} message
+ */
+export function userInfoLog(message) {
+    sink?.(message);
+}
+
+/**
+ * The error as Zalo reported it: its code and its message.
+ *
+ * @param {unknown} e
+ * @returns {string} e.g. `code 221: Quá giới hạn`, or just the message
+ */
+export function describeLookupError(e) {
+    const message = e?.message || String(e);
+    const code = e?.code ?? message.match(/\((-?\d+)\)\s*$/)?.[1];
+    return code !== undefined && code !== null && code !== "" ? `code ${code}: ${message}` : message;
+}
+
+/**
+ * Whether an error looks like Zalo refusing because too many lookups were made.
+ *
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export function isRateLimitError(e) {
+    if (RATE_LIMIT_CODES.has(Number(e?.code))) return true;
+    return RATE_LIMIT_TEXT.test(String(e?.message || e || ""));
+}
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const pacing = { gapMs: DEFAULT_GAP_MS, backoffMs: DEFAULT_BACKOFF_MS, sleep: realSleep };
+
+/**
+ * Override the module's pacing defaults (a test seam: the real gaps and back-offs are seconds).
+ *
+ * @param {{gapMs?: number, backoffMs?: readonly number[], sleep?: (ms: number) => Promise<void>}} [overrides]
+ *   call with nothing to restore the defaults
+ */
+export function configureUserInfo(overrides = {}) {
+    pacing.gapMs = overrides.gapMs ?? DEFAULT_GAP_MS;
+    pacing.backoffMs = overrides.backoffMs ?? DEFAULT_BACKOFF_MS;
+    pacing.sleep = overrides.sleep ?? realSleep;
+}
+
+/**
+ * Call `call(batch)` for each slice of `ids`, paced, retried and bounded.
+ *
+ * @template T
+ * @param {string[]} ids - already de-duplicated by the caller
+ * @param {object} opts
+ * @param {number} opts.batchSize - ids per request
+ * @param {(batch: string[]) => Promise<T>} opts.call - one request
+ * @param {string} [opts.label] - prefix for the log lines
+ * @param {(message: string) => void} [opts.log] - defaults to the daemon sink, else silent
+ * @param {number} [opts.gapMs] - wait between requests
+ * @param {readonly number[]} [opts.backoffMs] - waits before each retry of a rate-limited batch
+ * @param {number} [opts.maxConsecutiveFailures]
+ * @param {(ms: number) => Promise<void>} [opts.sleep] - test seam
+ * @returns {Promise<{results: T[], batches: number, failed: number, skippedIds: number,
+ *   stoppedBy: null|"rate-limit"|"repeated-failures", retries: number}>}
+ */
+export async function runPacedBatches(ids, opts) {
+    const {
+        batchSize,
+        call,
+        label = "user-info",
+        gapMs = pacing.gapMs,
+        backoffMs = pacing.backoffMs,
+        maxConsecutiveFailures = MAX_CONSECUTIVE_FAILURES,
+        sleep = pacing.sleep,
+    } = opts;
+    const log = typeof opts.log === "function" ? opts.log : (m) => sink?.(m);
+    const list = Array.isArray(ids) ? ids : [];
+    const total = Math.ceil(list.length / batchSize);
+    const out = { results: [], batches: total, failed: 0, skippedIds: 0, stoppedBy: null, retries: 0 };
+    let consecutive = 0;
+
+    for (let b = 0; b < total; b++) {
+        const batch = list.slice(b * batchSize, (b + 1) * batchSize);
+        if (b > 0 && gapMs > 0) await sleep(gapMs);
+        for (let attempt = 0; ; attempt++) {
+            try {
+                out.results.push(await call(batch));
+                consecutive = 0;
+                break;
+            } catch (e) {
+                const limited = isRateLimitError(e);
+                log(
+                    `${label}: batch ${b + 1}/${total} (${batch.length} id(s)) failed: ${describeLookupError(e)}` +
+                        (limited ? " [looks like a rate limit]" : ""),
+                );
+                if (limited && attempt < backoffMs.length) {
+                    out.retries++;
+                    log(`${label}: waiting ${backoffMs[attempt]}ms, then retrying batch ${b + 1}/${total}`);
+                    await sleep(backoffMs[attempt]);
+                    continue;
+                }
+                out.failed++;
+                consecutive++;
+                if (limited) out.stoppedBy = "rate-limit";
+                else if (consecutive >= maxConsecutiveFailures) out.stoppedBy = "repeated-failures";
+                break;
+            }
+        }
+        if (out.stoppedBy) {
+            out.skippedIds = list.length - (b + 1) * batchSize;
+            if (out.skippedIds < 0) out.skippedIds = 0;
+            log(
+                `${label}: stopped after batch ${b + 1}/${total} (${
+                    out.stoppedBy === "rate-limit"
+                        ? "Zalo is limiting these lookups"
+                        : `${consecutive} failed batches in a row`
+                }); ${out.skippedIds} id(s) in later batches were not looked up this time`,
+            );
+            break;
+        }
+    }
+    if (total > 1 && !out.stoppedBy && (out.failed || out.retries)) {
+        log(`${label}: finished ${total} batch(es), ${out.failed} failed, ${out.retries} retried`);
+    }
+    return out;
+}