@ardennguyen/zalo-agent-cli 2.0.0 → 2.1.1

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

@@ -31,10 +31,14 @@ import {
     getPendingSyncGaps,
     resolveSyncGap,
     replaceLiveGroupEventPlaceholder,
+    getThreadType,
+    getRecentThreads,
 } from "../db.js";
 import { ensureAssets, loadCodecs } from "./assets.js";
 import { classifySyncMessage } from "./message-types.js";
 import { resolveNonFriendDms } from "./gid.js";
+import { createSenderResolver } from "./senders.js";
+import { readUserAliases, currentUserName, resolveCurrentUserNames } from "../current-user-names.js";
 import { startKeepAlive } from "./keepalive.js";
 import { attachLiveStore } from "../live-store.js";
 
@@ -415,23 +419,33 @@ export class SyncV2 {
     constructor(api, accountName) {
         this.api = api;
         this.accountName = accountName;
-        this.accountDir = resolve(
-            process.env.USERPROFILE || process.env.HOME || "",
-            ".zalo-agent-cli",
-            "accounts",
-            accountName,
-        );
+        const dataRoot =
+            process.env.ZALO_DATA_DIR ||
+            process.env.ZALO_DB_DIR ||
+            resolve(
+                process.env.ZALO_CONFIG_DIR ||
+                    resolve(process.env.USERPROFILE || process.env.HOME || "", ".zalo-agent-cli"),
+                "accounts",
+            );
+        this.accountDir = resolve(dataRoot, accountName);
     }
 
     /** Build opaque-globalId -> {id, name, type} from the friend + group lists. */
     async _buildThreadMap(log) {
         const map = new Map();
+        this.userAliases = await readUserAliases(this.api, log);
         try {
             const friends = await this.api.getAllFriends();
             const arr = Array.isArray(friends) ? friends : friends?.data || [];
             for (const f of arr)
                 if (f.globalId)
-                    map.set(f.globalId, { id: String(f.userId), name: f.displayName || f.zaloName || "", type: "dm" });
+                    map.set(f.globalId, {
+                        id: String(f.userId),
+                        name: currentUserName(f.userId, f, this.userAliases).name,
+                        zaloName: f.zaloName || "",
+                        snapshotName: f.zaloName || f.displayName || "",
+                        type: "dm",
+                    });
         } catch (e) {
             log(`friend list unavailable (${e.message}); DM names/ids may be missing`);
         }
@@ -451,6 +465,32 @@ export class SyncV2 {
         return map;
     }
 
+    /** Refresh already-cached titles even if this restore window has no messages for them. */
+    _refreshThreadNames(threadMap) {
+        for (const thread of threadMap.values()) {
+            if (getThreadType(thread.id) === thread.type) {
+                upsertThread({ threadId: thread.id, type: thread.type, name: thread.name, lastUpdate: 0 });
+            }
+        }
+    }
+
+    /** Refresh existing DM peers outside the requested message window, including non-friends. */
+    async _refreshDmNames(threadMap) {
+        const profiles = new Map(
+            [...threadMap.values()]
+                .filter((t) => t.type === "dm" && t.zaloName)
+                .map((t) => [t.id, { zaloName: t.zaloName }]),
+        );
+        const names = await resolveCurrentUserNames(
+            this.api,
+            getRecentThreads(-1, "dm").map((t) => String(t.threadId)),
+            { aliases: this.userAliases, profiles },
+        );
+        for (const [id, current] of names) {
+            upsertThread({ threadId: id, type: "dm", name: current.name, lastUpdate: 0 });
+        }
+    }
+
     _send590(listener, kind, syncId, ek, ik, req) {
         listener.sendWs(
             {
@@ -519,8 +559,11 @@ export class SyncV2 {
 
         onStatus({ phase: "contacts", detail: "reading friend/group lists for thread mapping" });
         const threadMap = await this._buildThreadMap(log);
+        const senders = createSenderResolver(this.api, threadMap, { log });
 
         initDb(resolve(this.accountDir, "zalo.db"));
+        this._refreshThreadNames(threadMap);
+        await this._refreshDmNames(threadMap);
 
         const L = this.api.listener;
         const sessions = new Map(); // syncId -> {kind, batches:[], statuses:[], done, err}
@@ -806,7 +849,7 @@ export class SyncV2 {
                         } catch {
                             continue;
                         }
-                        onObj(obj);
+                        await onObj(obj);
                     } catch {
                         /* skip bad chunk */
                     }
@@ -916,7 +959,15 @@ export class SyncV2 {
                 onStatus({ phase: "resolve", detail: `resolving ${unresolved.length} non-friend conversation(s)` });
                 try {
                     const extra = await resolveNonFriendDms(this.api, unresolved, log);
-                    for (const [gid, v] of extra) threadMap.set(gid, { id: v.id, name: v.name, type: "dm" });
+                    for (const [gid, v] of extra)
+                        threadMap.set(gid, {
+                            id: v.id,
+                            name: currentUserName(v.id, { zaloName: v.zaloName }, this.userAliases).name,
+                            zaloName: v.zaloName || "",
+                            snapshotName: v.name,
+                            type: "dm",
+                        });
+                    this._refreshThreadNames(threadMap);
                     onStatus({
                         phase: "resolve",
                         detail: `resolved ${extra.size}/${unresolved.length} via gid/decrypt`,
@@ -1038,7 +1089,10 @@ export class SyncV2 {
                     }
 
                     const before = messagesSaved;
-                    await eachChunkObj(sessions.get(m.sid), m.ek, M.SyncChunk, (obj) => {
+                    await eachChunkObj(sessions.get(m.sid), m.ek, M.SyncChunk, async (obj) => {
+                        // Network identity lookups must finish before opening
+                        // the synchronous SQLite transaction for this chunk.
+                        await senders.prepare((obj.partitionsList || []).flatMap((p) => p.messagesList || []));
                         // One transaction per decoded chunk rather than one per
                         // row: thousands of individual WAL commits is both slow
                         // and a long block on the event loop.
@@ -1090,8 +1144,8 @@ export class SyncV2 {
                                             // gMsgID.
                                             msgId: syncMsgId(msg),
                                             threadId,
-                                            senderId: String(msg.senderId || ""),
-                                            senderName: "",
+                                            senderId: senders.get(msg.senderId).id,
+                                            senderName: senders.get(msg.senderId).name,
                                             text: info.text,
                                             timestamp: Number(msg.timestamp) || 0,
                                             type: info.type,

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

@@ -482,9 +482,10 @@ export async function downloadSyncedMedia(opts = {}) {
         }
     }
 
-    // The MCP server honours a configured download dir; everything else files
-    // media under the account's own data dir.
-    const mediaRoot = mediaRootOpt ? resolve(mediaRootOpt) : resolve(accountDir, "media");
+    // Explicit mediaRootOpt or global ZALO_MEDIA_DIR (--media-dir) overrides the
+    // per-account default (<accountDir>/media).
+    const configuredRoot = mediaRootOpt || process.env.ZALO_MEDIA_DIR;
+    const mediaRoot = configuredRoot ? resolve(configuredRoot) : resolve(accountDir, "media");
 
     // Folders are ids, so without this the media tree is unreadable by a human.
     // Written before any download, so an interrupted run still leaves an index.

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

@@ -0,0 +1,61 @@
+import { resolveNonFriendDms } from "./gid.js";
+
+const NOISED_ID = /^[0-9A-V]{32}$/;
+
+/**
+ * Build a per-restore sender resolver. Only DM entries can seed user identities:
+ * a group's globalId identifies the conversation, never one of its senders.
+ * Unknown senders use the existing profile gid/decrypt + getUserInfo path.
+ * Failures leave the original ID intact and are attempted once per restore.
+ *
+ * @param {object} api - authenticated zca-js API
+ * @param {Map<string, {id: string, name: string, type: string}>} threadMap
+ * @param {object} [options]
+ * @param {Function} [options.resolveUsers] - batched global-ID resolver
+ * @param {Function} [options.log] - diagnostic sink (never stdout in MCP mode)
+ * @returns {{prepare: Function, get: Function}} chunk preparation and row lookup
+ */
+export function createSenderResolver(api, threadMap, { resolveUsers = resolveNonFriendDms, log = () => {} } = {}) {
+    const users = new Map();
+    const attempted = new Set();
+    for (const [gid, user] of threadMap) {
+        if (user.type === "dm")
+            users.set(gid, { id: String(user.id), name: user.snapshotName ?? user.zaloName ?? user.name ?? "" });
+    }
+
+    return {
+        async prepare(messages) {
+            // Conversation resolution may have added non-friend users since
+            // this resolver was constructed. Do not repeat those lookups.
+            for (const [gid, user] of threadMap) {
+                if (user.type === "dm")
+                    users.set(gid, {
+                        id: String(user.id),
+                        name: user.snapshotName ?? user.zaloName ?? user.name ?? "",
+                    });
+            }
+            const missing = [...new Set(messages.map((m) => String(m.senderId || "")))].filter(
+                (id) => NOISED_ID.test(id) && !users.has(id) && !attempted.has(id),
+            );
+            if (!missing.length) return;
+            for (const id of missing) attempted.add(id);
+            try {
+                const resolved = await resolveUsers(api, missing, log);
+                for (const id of missing) {
+                    const user = resolved.get(id);
+                    // Never treat a missing mapping, or another opaque ID, as
+                    // a canonical user. Keep unknown senders explicitly unknown.
+                    if (user && /^[1-9][0-9]*$/.test(String(user.id))) {
+                        users.set(id, { id: String(user.id), name: user.name || "" });
+                    }
+                }
+            } catch {
+                log("sender identity lookup failed; unresolved sender IDs are preserved");
+            }
+        },
+        get(senderId) {
+            const id = String(senderId || "");
+            return users.get(id) || { id, name: "" };
+        },
+    };
+}

package/src/core/sync.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import { resolve } from "path";
 import crypto from "crypto";
-import { CONFIG_DIR } from "./credentials.js";
+import { getAccountDir } from "./credentials.js";
 import {
     initDb,
     insertMessage,
@@ -19,7 +19,7 @@ const THREAD_TYPE_USER = 0;
 const THREAD_TYPE_GROUP = 1;
 
 function resolveAccountDir(accountName) {
-    return resolve(CONFIG_DIR, "accounts", accountName);
+    return resolve(getAccountDir(accountName));
 }
 
 /** Zalo Web's own client only ever seems to backfill about this far on a

package/src/index.js

@@ -31,6 +31,7 @@ import { registerMCPCommands } from "./commands/mcp.js";
 import { registerSyncCommands } from "./commands/sync.js";
 import { autoLogin } from "./core/zalo-client.js";
 import { getActive } from "./core/accounts.js";
+import { configureStoragePaths } from "./core/credentials.js";
 import { logoutNeedsSession } from "./core/logout.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
 import { applyCachedThreadType } from "./utils/thread-type.js";
@@ -46,10 +47,31 @@ program
     .description("CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments")
     .version(pkg.version)
     .option("--json", "Output results as JSON (machine-readable)")
+    .option("--env-file <path>", "Load environment variables from a .env file (env: ZALO_ENV_FILE)")
+    .option("--config-dir <dir>", "Config directory (default: ~/.zalo-agent-cli, env: ZALO_CONFIG_DIR)")
+    .option(
+        "--credentials-dir <dir>",
+        "Credentials directory (default: <config-dir>/credentials, env: ZALO_CREDENTIALS_DIR)",
+    )
+    .option(
+        "--data-dir <dir>",
+        "Per-account database and runtime directory (default: <config-dir>/accounts, env: ZALO_DATA_DIR)",
+    )
+    .option("--media-dir <dir>", "Downloaded media directory (default: <data-dir>/<ownId>/media, env: ZALO_MEDIA_DIR)")
+    .option("--oa-dir <dir>", "Official Account credentials directory (default: ~/.zalo-agent, env: ZALO_OA_DIR)")
     .hook("preAction", async (thisCommand, actionCommand) => {
+        const globalOpts = program.opts();
+        configureStoragePaths({
+            envFile: globalOpts.envFile,
+            configDir: globalOpts.configDir,
+            credentialsDir: globalOpts.credentialsDir,
+            dataDir: globalOpts.dataDir,
+            mediaDir: globalOpts.mediaDir,
+            oaDir: globalOpts.oaDir,
+        });
         const cmdName = thisCommand.args?.[0] || thisCommand.name();
         // Suppress zca-js internal logs in JSON mode to keep stdout clean for piping
-        if (program.opts().json || cmdName === "mcp") {
+        if (globalOpts.json || cmdName === "mcp") {
             // Suppress zca-js stdout logs: JSON mode needs clean output, MCP uses stdout as transport
             process.env.ZALO_JSON_MODE = "1";
         } else if (cmdName !== "oa") {
@@ -59,8 +81,9 @@ program
         }
         // Auto-login before any command that needs it (skip for login/account/oa
         // commands, and for a logout that will not call Zalo at all).
+        // Daemons authenticate their pinned identity after acquiring its lock.
         const skipAutoLogin =
-            ["login", "account", "help", "version", "update", "oa", "mcp"].includes(cmdName) ||
+            ["login", "account", "help", "version", "update", "oa", "mcp", "listen"].includes(cmdName) ||
             (cmdName === "logout" && !logoutNeedsSession(actionCommand.opts(), getActive()));
         if (!skipAutoLogin) {
             await autoLogin(program.opts().json);

package/src/mcp/mcp-config.js

@@ -6,7 +6,9 @@ import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { CONFIG_DIR } from "../core/credentials.js";
 
-const MCP_CONFIG_FILE = join(CONFIG_DIR, "mcp-config.json");
+function mcpConfigFile() {
+    return join(CONFIG_DIR, "mcp-config.json");
+}
 
 /** Default MCP config — sensible defaults for local development */
 export function getDefaultConfig() {
@@ -47,7 +49,7 @@ export function getDefaultConfig() {
 export function loadMCPConfig(configPath) {
     const defaults = getDefaultConfig();
     try {
-        const raw = readFileSync(configPath || MCP_CONFIG_FILE, "utf-8");
+        const raw = readFileSync(configPath || mcpConfigFile(), "utf-8");
         const saved = JSON.parse(raw);
         // Shallow merge: saved values override defaults
         return {
@@ -77,7 +79,7 @@ export function loadMCPConfig(configPath) {
  * @returns {{config: object, problem: string|null}}
  */
 export function readMCPConfig(configPath) {
-    const file = configPath || MCP_CONFIG_FILE;
+    const file = configPath || mcpConfigFile();
     let raw;
     try {
         raw = readFileSync(file, "utf-8");
@@ -99,7 +101,7 @@ export function readMCPConfig(configPath) {
  */
 export function saveMCPConfig(config) {
     mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(MCP_CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+    writeFileSync(mcpConfigFile(), JSON.stringify(config, null, 2), "utf-8");
 }
 
 /**

package/src/mcp/mcp-http-transport.js

@@ -17,7 +17,7 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8
 /**
  * Create HTTP MCP server with optional bearer token auth.
  * @param {Function} registerToolsFn - Registers tools on a McpServer instance
- * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir }
+ * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs }
  * @param {number} port
  * @param {string|null} authToken - Bearer token (null = no auth)
  * @returns {import("http").Server}
@@ -53,6 +53,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
                 deps.nameCache,
                 deps.accountDir,
                 deps.stageLock,
+                deps.syncJobs,
             );
 
             const transport = new StreamableHTTPServerTransport({

package/src/mcp/mcp-server.js

@@ -23,15 +23,16 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8
  * @param {import("./thread-name-cache.js").ThreadNameCache} [nameCache] - Thread name cache
  * @param {string} [accountDir] - account data dir, for cache reads and media paths
  * @param {object} [stageLock] - the daemon's one-stage-at-a-time lock (daemon-channel.js)
+ * @param {object} [syncJobs] - account-local sync tracker shared by all MCP requests
  * @returns {Promise<McpServer>}
  */
-export async function createMCPServer(api, buffer, filter, config, nameCache, accountDir, stageLock) {
+export async function createMCPServer(api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs) {
     const server = new McpServer({
         name: "zalo-agent",
         version: pkg.version,
     });
 
-    registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock);
+    registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs);
 
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/src/mcp/mcp-tools.js

@@ -1,8 +1,8 @@
 /**
  * MCP tool registrations for Zalo message access and sending.
- * Registers 12 tools: zalo_get_messages, zalo_get_history, zalo_send_message, zalo_list_threads,
+ * Registers 14 tools: zalo_get_messages, zalo_get_history, zalo_send_message, zalo_list_threads,
  * zalo_search_threads, zalo_mark_read, zalo_view_media, zalo_react, zalo_undo, zalo_get_group_members,
- * zalo_list_conversations, zalo_coverage.
+ * zalo_list_conversations, zalo_coverage, zalo_sync, zalo_sync_status.
  *
  * A tool that mirrors a CLI command calls the same code the command does (src/core/cached-message.js,
  * group-members.js, recent-conversations.js, src/utils/my-documents.js, urgency.js), so the two cannot
@@ -24,6 +24,7 @@ import { expandMentions, ALL_MENTION_UID } from "../utils/mentions.js";
 import { resolveSelfThread } from "../utils/my-documents.js";
 import { buildQuote, resolveQuoteSender } from "../utils/quote.js";
 import { urgencyLevel } from "../utils/urgency.js";
+import { resolveCurrentUserNames, withCurrentSenderNames } from "../core/current-user-names.js";
 
 /**
  * Resolve a thread's type the way the CLI does.
@@ -270,8 +271,9 @@ function cacheHistory(threadId, limit, before, nameCache) {
  * @param {string} [accountDir] - account data dir; media is fetched into <accountDir>/media
  * @param {ReturnType<import("../core/daemon-channel.js").createStageLock>} [stageLock] - the
  *   daemon's one-stage-at-a-time lock; a server-side history fetch takes it, as `listen`'s does
+ * @param {object} [syncJobs] - the daemon's account-local sync job tracker
  */
-export function registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock) {
+export function registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs) {
     const maxPerPoll = config.limits?.maxMessagesPerPoll ?? 20;
 
     // Several bots can share one listener, each with its own read cursor
@@ -297,7 +299,8 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                 "not marked read (see zalo_mark_read). Use 'since' cursor from previous response for incremental polling. " +
                 "Each message's `readOnZalo` says whether the account itself has already read it on Zalo -- the " +
                 "human, on the phone or Zalo Web -- and is null when the listener has not heard; zalo_mark_read " +
-                "does not change it.",
+                "does not change it. Use senderDisplayName for the current label (your alias, then Zalo profile name, " +
+                "then UID); senderDisplayNameSource reports alias/zalo/uid. senderName remains the historical snapshot.",
             inputSchema: z.object({
                 threadId: z.string().optional().describe("Thread ID to read from. Omit for all watched threads."),
                 since: z
@@ -322,6 +325,10 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                         if (info) msg.threadName = info.name;
                     }
                 }
+                const dmIds = result.messages
+                    .filter((m) => (nameCache?.get(m.threadId)?.type || buffer.getThreadType?.(m.threadId)) === "dm")
+                    .map((m) => m.threadId);
+                result.messages = await withCurrentSenderNames(api, result.messages, dmIds);
                 // Whether the human already read each one, from its
                 // conversation's read watermark (src/core/read-state.js).
                 const watermarks = new Map();
@@ -537,6 +544,10 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             try {
                 // Unread is per consumer: after what this consumer marked read.
                 const stats = buffer.getStats(buffer.readCursor(consumer));
+                const dmNames = await resolveCurrentUserNames(
+                    api,
+                    stats.filter((t) => buffer.getThreadType(t.threadId) === "dm").map((t) => t.threadId),
+                );
                 const reads = readStatesOf(
                     api,
                     stats.map((t) => String(t.threadId)),
@@ -548,7 +559,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                     return {
                         ...t,
                         threadType,
-                        name: cached?.name ?? null,
+                        name: dmNames.get(String(t.threadId))?.name ?? cached?.name ?? null,
                         ...(cached?.memberCount !== undefined && { memberCount: cached.memberCount }),
                         readState: describeReadState(reads.get(String(t.threadId))),
                     };
@@ -583,6 +594,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                 if (!nameCache?.ready) {
                     return err("Thread name cache not initialized yet. Try again shortly.");
                 }
+                await nameCache.refreshUsers?.(api);
                 const results = nameCache.search(query, type, limit);
                 return ok({ results, total: results.length });
             } catch (e) {
@@ -628,6 +640,8 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             title: "Get Zalo Message History",
             description:
                 "Fetch historical messages from a Zalo DM or group conversation. " +
+                "senderName preserves the historical snapshot; senderDisplayName resolves the current label by UID " +
+                "(your alias, then Zalo profile name, then UID), with senderDisplayNameSource alias/zalo/uid. " +
                 "Reads the local cache first (everything the listener and `zalo-agent sync` " +
                 "have stored, which can be the full history), and falls back to asking the Zalo server " +
                 "when the cache has nothing for the thread: a group's cloud-message store first, then the " +
@@ -670,7 +684,14 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                 // request on current accounts, while the cache holds whatever
                 // the listener saw and whatever a transfer sync restored.
                 const cached = cacheHistory(threadId, limit, before, nameCache);
-                if (cached) return ok(cached);
+                if (cached) {
+                    cached.messages = await withCurrentSenderNames(
+                        api,
+                        cached.messages,
+                        threadType === THREAD_USER ? [threadId] : [],
+                    );
+                    return ok(cached);
+                }
 
                 // Nothing cached: ask Zalo through the one shared fetch `listen`'s
                 // daemon uses for `msg history` (src/core/history-fetch.js): a
@@ -732,7 +753,11 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                     // Which Zalo path answered: a group's cloud-message store, or the socket stream.
                     via: fetched.source,
                     count: allMessages.length,
-                    messages: allMessages,
+                    messages: await withCurrentSenderNames(
+                        api,
+                        allMessages,
+                        threadType === THREAD_USER ? [threadId] : [],
+                    ),
                     cursor,
                     hasMore: Boolean(fetched.more) || (fetched.source === "socket" && allMessages.length >= limit),
                     filtered: fetched.filtered === true,
@@ -799,7 +824,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                         threadId: String(row?.threadId || buffered?.threadId || threadId || ""),
                         limit: 50,
                         concurrency: 2,
-                        mediaRoot: mediaConfig.downloadDir || undefined,
+                        mediaRoot: process.env.ZALO_MEDIA_DIR || mediaConfig.downloadDir || undefined,
                     });
                     localPath = getMessageById(messageId)?.localPath || null;
                     if (!localPath) {
@@ -1034,6 +1059,10 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
         async ({ type, limit }) => {
             try {
                 const threads = recentConversations(limit, type);
+                const dmNames = await resolveCurrentUserNames(
+                    api,
+                    threads.filter((t) => t.type !== "group").map((t) => String(t.threadId)),
+                );
                 const reads = readStatesOf(
                     api,
                     threads.map((t) => String(t.threadId)),
@@ -1045,7 +1074,11 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                         threadId: String(t.threadId),
                         type: isGroup ? "group" : "dm",
                         threadType: isGroup ? THREAD_GROUP : THREAD_USER,
-                        name: t.name || nameCache?.get(String(t.threadId))?.name || null,
+                        name:
+                            dmNames.get(String(t.threadId))?.name ||
+                            t.name ||
+                            nameCache?.get(String(t.threadId))?.name ||
+                            null,
                         lastActivity: ts,
                         lastActivityAt: ts ? new Date(ts).toISOString() : null,
                         readState: describeReadState(reads.get(String(t.threadId))),
@@ -1078,7 +1111,8 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                 "this account's connection to Zalo was down, so messages from them may be missing — with each " +
                 "gap's from/to and reason, counts the gaps already resolved, and names the `zalo-agent sync --from " +
                 "<date>` run that restores the pending ones from the owner's phone (it needs a tap on the phone, " +
-                "so a person runs it). Read-only: nothing is sent to Zalo.",
+                "so the owner must approve it). Use zalo_sync only when the owner asks to restore. " +
+                "Read-only: nothing is sent to Zalo.",
             inputSchema: z.object({}),
         },
         async () => {
@@ -1090,4 +1124,100 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             }
         },
     );
+
+    // An explicit start returns immediately; phone-backed restores can take minutes.
+    server.registerTool(
+        "zalo_sync",
+        {
+            title: "Request Zalo Sync",
+            description:
+                "Start a messages restore or reaction-backlog sync on this MCP account's existing socket. " +
+                "Only call when the owner explicitly requests sync; messages sends a confirmation to their phone. " +
+                "Returns a job immediately: poll zalo_sync_status every few seconds. Reuse requestId for retries. " +
+                "This updates the local cache, not Zalo messages. Messages restores all conversations in the window; " +
+                "it is not a per-thread sync. No media download, boards, cloud index or conversation-state sync.",
+            inputSchema: z
+                .object({
+                    requestId: z
+                        .string()
+                        .min(1)
+                        .max(64)
+                        .regex(/^[A-Za-z0-9._:-]+$/)
+                        .describe(
+                            "Unique request key; reuse the same key and arguments after a timeout to avoid duplicate sync.",
+                        ),
+                    stage: z.enum(["messages", "reactions"]).default("messages"),
+                    days: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(36500)
+                        .optional()
+                        .describe("Restore the last N days; omit both days and from for full phone history."),
+                    from: z
+                        .string()
+                        .regex(/^\d{4}-\d{2}-\d{2}$/)
+                        .refine((value) => {
+                            const time = Date.parse(value + "T00:00:00Z");
+                            return Number.isFinite(time) && new Date(time).toISOString().slice(0, 10) === value;
+                        }, "Use a valid YYYY-MM-DD date")
+                        .optional()
+                        .describe("Restore since this UTC date, e.g. the date from zalo_coverage."),
+                    waitMs: z
+                        .number()
+                        .int()
+                        .min(30000)
+                        .max(600000)
+                        .optional()
+                        .describe("Per-phase wait budget in milliseconds."),
+                    applyRemovals: z
+                        .boolean()
+                        .optional()
+                        .describe("Reactions only: apply observed removals; defaults to true."),
+                })
+                .strict()
+                .refine(
+                    (value) => !(value.days !== undefined && value.from !== undefined),
+                    "Choose days or from, not both",
+                )
+                .refine(
+                    (value) => value.stage !== "reactions" || (value.days === undefined && value.from === undefined),
+                    "Reactions sync has no date window",
+                )
+                .refine(
+                    (value) => value.stage !== "messages" || value.applyRemovals === undefined,
+                    "applyRemovals is reactions-only",
+                ),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        },
+        async (args) => {
+            try {
+                if (!syncJobs) throw new Error("Sync is unavailable in this server; restart with a compatible engine.");
+                return ok(syncJobs.start(args));
+            } catch (e) {
+                return err(e.message);
+            }
+        },
+    );
+
+    server.registerTool(
+        "zalo_sync_status",
+        {
+            title: "Zalo Sync Status",
+            description:
+                "Read sync progress and the final result without starting or repeating sync. Omit jobId for the latest " +
+                "job (or idle). Completed means the runner returned: inspect result.reason for partial/timeout/socket loss, " +
+                "not proof that all history was restored. Last ten jobs are kept in memory until daemon restart.",
+            inputSchema: z.object({ jobId: z.string().uuid().optional() }).strict(),
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        },
+        async ({ jobId }) => {
+            try {
+                if (!syncJobs) throw new Error("Sync is unavailable in this server; restart with a compatible engine.");
+                return ok(syncJobs.status(jobId));
+            } catch (e) {
+                return err(e.message);
+            }
+        },
+    );
 }