@ardennguyen/zalo-agent-cli 2.5.1 → 2.5.4

package/src/core/daemon-channel.js

@@ -81,6 +81,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { maskSecretArgs } from "../utils/secrets.js";
 
 const CHANNEL_FILE = "daemon-channel.json";
 const LOCK_FILE = "daemon.lock";
@@ -291,6 +292,10 @@ function readJsonBody(req, reply) {
  * @param {() => void} [args.onStop] - graceful shutdown callback invoked by
  *   `POST /stop` so `--stop` runs the same teardown as `SIGINT` (stamping
  *   `markConnected`, flushing delivered receipts, releasing `daemon.lock`).
+ * @param {(params: object, signal: AbortSignal) => Promise<object>} [args.onWait] -
+ *   long-poll callback invoked by `POST /wait` (`zalo-agent mcp wait`).
+ * @param {(params: object) => Promise<object>} [args.onMarkRead] -
+ *   read-cursor callback invoked by `POST /mark-read` (`zalo-agent mcp mark-read`).
  * @returns {Promise<{port: number, stop: () => void}>}
  */
 export function startDaemonChannel({
@@ -300,6 +305,8 @@ export function startDaemonChannel({
     runners = {},
     lock = createStageLock(),
     onStop = null,
+    onWait = null,
+    onMarkRead = null,
 }) {
     const token = randomBytes(24).toString("hex");
 
@@ -416,6 +423,40 @@ export function startDaemonChannel({
         });
     };
 
+    /** Long-poll the MCP daemon's live message buffer (`zalo-agent mcp wait`). */
+    const serveWait = async (body, res, reply) => {
+        if (!tokenMatches(body.token, token)) return reply(403, { error: "bad token" });
+        if (typeof onWait !== "function") {
+            return reply(503, {
+                error: "this daemon does not have an MCP message buffer (run `zalo-agent mcp start` instead of `listen`)",
+            });
+        }
+        const ac = new AbortController();
+        res.on("close", () => ac.abort());
+        try {
+            const result = await onWait(body, ac.signal);
+            if (!res.writableEnded) reply(200, { ok: true, ...result });
+        } catch (e) {
+            if (!res.writableEnded) reply(200, { ok: false, error: e?.message || String(e) });
+        }
+    };
+
+    /** Advance one consumer's read cursor in the MCP daemon's buffer (`zalo-agent mcp mark-read`). */
+    const serveMarkRead = async (body, reply) => {
+        if (!tokenMatches(body.token, token)) return reply(403, { error: "bad token" });
+        if (typeof onMarkRead !== "function") {
+            return reply(503, {
+                error: "this daemon does not have an MCP message buffer (run `zalo-agent mcp start` instead of `listen`)",
+            });
+        }
+        try {
+            const result = await onMarkRead(body);
+            reply(200, { ok: true, ...result });
+        } catch (e) {
+            reply(200, { ok: false, error: e?.message || String(e) });
+        }
+    };
+
     const server = http.createServer(async (req, res) => {
         const reply = (code, body) => {
             res.writeHead(code, { "content-type": "application/json" });
@@ -424,11 +465,21 @@ export function startDaemonChannel({
         if (req.method !== "POST") return reply(404, { error: "not found" });
 
         const stage = SYNC_ROUTE.exec(req.url || "")?.[1];
-        if (req.url !== "/send-attachments" && req.url !== "/stop" && !stage) return reply(404, { error: "not found" });
+        if (
+            req.url !== "/send-attachments" &&
+            req.url !== "/stop" &&
+            req.url !== "/wait" &&
+            req.url !== "/mark-read" &&
+            !stage
+        ) {
+            return reply(404, { error: "not found" });
+        }
 
         const body = await readJsonBody(req, reply);
         if (!body) return; // already answered, or the request went away
         if (req.url === "/stop") return serveStop(body, reply);
+        if (req.url === "/wait") return serveWait(body, res, reply);
+        if (req.url === "/mark-read") return serveMarkRead(body, reply);
         return stage ? serveStage(stage, body, res, reply) : serveAttachments(body, reply);
     });
 
@@ -781,6 +832,143 @@ export function stopViaDaemon(accountDir, { timeoutMs = 3000 } = {}) {
     });
 }
 
+/**
+ * Long-poll the running MCP daemon's live message buffer (`zalo-agent mcp wait`),
+ * mirroring the `zalo_wait_for_message` MCP tool over the loopback channel.
+ *
+ * @param {string} accountDir
+ * @param {{threadId?: string|null, since?: number, timeoutSec?: number, consumer?: string}} [opts]
+ * @returns {Promise<{ok: boolean, status?: "message"|"timeout"|number, message?: object|null, cursor?: number, error?: string}|null>}
+ *   null when no daemon channel is published
+ */
+export function waitViaDaemon(accountDir, { threadId = null, since = undefined, timeoutSec = 55, consumer } = {}) {
+    const chan = getDaemonChannel(accountDir);
+    if (!chan) return Promise.resolve(null);
+
+    const clampedSec = Math.max(1, Math.min(300, Number(timeoutSec) || 55));
+    const payload = JSON.stringify({
+        token: chan.token,
+        ...(threadId ? { threadId: String(threadId) } : {}),
+        ...(typeof since === "number" && Number.isFinite(since) ? { since } : {}),
+        timeoutSec: clampedSec,
+        ...(consumer ? { consumer: String(consumer) } : {}),
+    });
+
+    return new Promise((resolve) => {
+        const r = http.request(
+            {
+                host: "127.0.0.1",
+                port: chan.port,
+                path: "/wait",
+                method: "POST",
+                headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) },
+                timeout: (clampedSec + 10) * 1000,
+                agent: false,
+            },
+            (res) => {
+                let raw = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (raw += c));
+                res.on("end", () => {
+                    let body = {};
+                    try {
+                        body = JSON.parse(raw);
+                    } catch {
+                        /* non-JSON response */
+                    }
+                    if (res.statusCode === 200 && body.ok) {
+                        resolve({
+                            ok: true,
+                            status: body.status,
+                            message: body.message ?? null,
+                            cursor: body.cursor,
+                        });
+                    } else {
+                        resolve({
+                            ok: false,
+                            status: res.statusCode,
+                            error: body.error || `HTTP ${res.statusCode}`,
+                        });
+                    }
+                });
+            },
+        );
+        r.on("timeout", () => {
+            r.destroy();
+            resolve({ ok: false, error: "timeout waiting for daemon response" });
+        });
+        r.on("error", (e) => resolve({ ok: false, error: e?.message || String(e) }));
+        r.end(payload);
+    });
+}
+
+/**
+ * Advance one consumer's read cursor in the running MCP daemon's live message
+ * buffer (`zalo-agent mcp mark-read`), mirroring the `zalo_mark_read` MCP tool.
+ *
+ * @param {string} accountDir
+ * @param {{cursor: number, consumer?: string}} opts
+ * @returns {Promise<{ok: boolean, marked?: number, readCursor?: number, consumer?: string, status?: number, error?: string}|null>}
+ *   null when no daemon channel is published
+ */
+export function markReadViaDaemon(accountDir, { cursor, consumer } = {}) {
+    const chan = getDaemonChannel(accountDir);
+    if (!chan) return Promise.resolve(null);
+
+    const payload = JSON.stringify({
+        token: chan.token,
+        cursor: Number(cursor),
+        ...(consumer ? { consumer: String(consumer) } : {}),
+    });
+
+    return new Promise((resolve) => {
+        const r = http.request(
+            {
+                host: "127.0.0.1",
+                port: chan.port,
+                path: "/mark-read",
+                method: "POST",
+                headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) },
+                timeout: 5000,
+                agent: false,
+            },
+            (res) => {
+                let raw = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (raw += c));
+                res.on("end", () => {
+                    let body = {};
+                    try {
+                        body = JSON.parse(raw);
+                    } catch {
+                        /* non-JSON response */
+                    }
+                    if (res.statusCode === 200 && body.ok) {
+                        resolve({
+                            ok: true,
+                            marked: body.marked ?? 0,
+                            readCursor: body.readCursor ?? Number(cursor),
+                            consumer: body.consumer || consumer || "default",
+                        });
+                    } else {
+                        resolve({
+                            ok: false,
+                            status: res.statusCode,
+                            error: body.error || `HTTP ${res.statusCode}`,
+                        });
+                    }
+                });
+            },
+        );
+        r.on("timeout", () => {
+            r.destroy();
+            resolve({ ok: false, error: "timeout waiting for daemon response" });
+        });
+        r.on("error", (e) => resolve({ ok: false, error: e?.message || String(e) }));
+        r.end(payload);
+    });
+}
+
 /**
  * Stop the running daemon for an account directory, preferring `POST /stop` so
  * the daemon runs its own graceful shutdown handler (`markConnected`, receipt
@@ -985,7 +1173,8 @@ export async function spawnDaemonProcess({ accountDir, args = process.argv.slice
     const filteredArgs = args.filter((a) => a !== "-d" && a !== "--daemon");
 
     const logFd = fs.openSync(logPath, "a", 0o600);
-    const header = `\n--- [${new Date().toISOString()}] starting daemon: ${filteredArgs.join(" ")} ---\n`;
+    // Never the secrets: --auth, --client-secret and --webhook-secret values are masked.
+    const header = `\n--- [${new Date().toISOString()}] starting daemon: ${maskSecretArgs(filteredArgs).join(" ")} ---\n`;
     fs.writeSync(logFd, header);
     let startOffset = 0;
     try {

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 });
 }