@ardennguyen/zalo-agent-cli 2.0.0 → 2.1.0

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

@@ -83,6 +83,7 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
 
     // 2. userId -> display name via getUserInfo (batched). Best-effort.
     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);
@@ -90,7 +91,8 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
             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.displayName || p.zaloName || "");
+                    if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
+                    if (p?.zaloName) zaloNames.set(uid, p.zaloName);
                 }
             }
         } catch (e) {
@@ -98,6 +100,7 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
         }
     }
 
-    for (const [gid, uid] of idToUser) out.set(gid, { id: uid, name: names.get(uid) || "" });
+    for (const [gid, uid] of idToUser)
+        out.set(gid, { id: uid, name: names.get(uid) || "", zaloName: zaloNames.get(uid) || "" });
     return out;
 }

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";
 
@@ -426,12 +430,19 @@ export class SyncV2 {
     /** 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 +462,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 +556,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 +846,7 @@ export class SyncV2 {
                         } catch {
                             continue;
                         }
-                        onObj(obj);
+                        await onObj(obj);
                     } catch {
                         /* skip bad chunk */
                     }
@@ -916,7 +956,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 +1086,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 +1141,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/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/index.js

@@ -59,8 +59,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-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,
@@ -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);
+            }
+        },
+    );
 }

package/src/mcp/sync-jobs.js

@@ -0,0 +1,82 @@
+/**
+ * Process-local tracking for explicitly requested MCP sync stages. The daemon
+ * owns this object, not an HTTP request's short-lived McpServer. The runners
+ * own all sync work; this module only tracks bounded progress and the result.
+ */
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+
+/**
+ * Create a bounded, account-local job tracker using the daemon's stage lock.
+ * Completed jobs are retained until displaced by ten newer jobs or restart.
+ * A requestId retry returns the same job while retained, without another tap.
+ * @param {{runners: object, lock: object}} deps - daemon runners and shared stage lock
+ * @returns {{start: Function, status: Function}}
+ */
+export function createSyncJobs({ runners, lock }) {
+    const jobs = new Map();
+    const snapshot = (job) => (job ? structuredClone(job) : null);
+
+    return {
+        start({ requestId, stage, ...params }) {
+            const existing = [...jobs.values()].find((job) => job.requestId === requestId);
+            if (existing) {
+                if (existing.stage !== stage || !isDeepStrictEqual(existing.params, params)) {
+                    throw new Error("requestId already names a different sync request; use a new requestId.");
+                }
+                return snapshot(existing);
+            }
+            if (!["messages", "reactions"].includes(stage) || typeof runners[stage] !== "function") {
+                throw new Error("Unsupported sync stage.");
+            }
+            const release = lock.tryAcquire(`mcp-sync:${stage}`);
+            if (!release)
+                throw new Error(`Sync/history is busy (${lock.current()?.stage}); check status and retry later.`);
+
+            const job = {
+                jobId: randomUUID(),
+                requestId,
+                stage,
+                params,
+                state: "running",
+                startedAt: Date.now(),
+                finishedAt: null,
+                phoneConfirmationRequired: stage === "messages",
+                events: [],
+            };
+            // The lock guarantees no other running job is evicted here.
+            while (jobs.size >= 10) jobs.delete(jobs.keys().next().value);
+            jobs.set(job.jobId, job);
+            const initial = snapshot(job);
+            Promise.resolve().then(async () => {
+                try {
+                    job.result = await runners[stage](params, (event) => {
+                        // Retain recent progress, never an unbounded event stream.
+                        job.events.push({
+                            at: Date.now(),
+                            phase: String(event.phase || "progress").slice(0, 80),
+                            detail: String(event.detail || "").slice(0, 1000),
+                        });
+                        if (job.events.length > 20) job.events.shift();
+                    });
+                    job.state = "completed";
+                } catch (error) {
+                    job.state = "failed";
+                    job.error = error?.message || String(error);
+                } finally {
+                    job.finishedAt = Date.now();
+                    release();
+                }
+            });
+            return initial;
+        },
+        status(jobId) {
+            if (jobId) {
+                const job = jobs.get(jobId);
+                if (!job) throw new Error("Unknown or expired sync job; jobs are lost when the daemon restarts.");
+                return snapshot(job);
+            }
+            return snapshot([...jobs.values()].at(-1)) || { state: "idle" };
+        },
+    };
+}

package/src/mcp/thread-name-cache.js

@@ -1,3 +1,5 @@
+import { readUserAliases, resolveCurrentUserNames } from "../core/current-user-names.js";
+
 /**
  * In-memory cache mapping threadId → {name, type, memberCount}.
  * Built on startup by fetching all groups + friends from Zalo API.
@@ -35,6 +37,7 @@ export class ThreadNameCache {
         const start = Date.now();
         let groupCount = 0;
         let friendCount = 0;
+        const friendProfiles = new Map();
 
         // Load groups: getAllGroups() → IDs → batched getGroupInfo()
         try {
@@ -63,12 +66,13 @@ export class ThreadNameCache {
             console.error("[thread-name-cache] getAllGroups failed:", e.message);
         }
 
-        // Load friends (DM threads)
+        // Load friends (DM threads), honoring the owner's aliases explicitly.
         try {
             const friends = await api.getAllFriends();
             const list = Array.isArray(friends) ? friends : [];
             for (const f of list) {
                 if (f.userId) {
+                    friendProfiles.set(String(f.userId), f);
                     this._cache.set(f.userId, {
                         name: f.displayName || f.zaloName || "?",
                         type: "dm",
@@ -80,6 +84,7 @@ export class ThreadNameCache {
             console.error("[thread-name-cache] getAllFriends failed:", e.message);
         }
 
+        await this.refreshUsers(api, friendProfiles);
         this._ready = true;
         const elapsed = Date.now() - start;
         console.error(`[thread-name-cache] Ready: ${groupCount} groups, ${friendCount} friends (${elapsed}ms)`);
@@ -94,6 +99,14 @@ export class ThreadNameCache {
         return this._cache.get(threadId) || null;
     }
 
+    /** Refresh current DM labels without modifying per-message names or group titles. */
+    async refreshUsers(api, profiles = new Map()) {
+        const ids = [...this._cache].filter(([, v]) => v.type === "dm").map(([id]) => id);
+        const aliases = await readUserAliases(api);
+        const names = await resolveCurrentUserNames(api, ids, { aliases, profiles });
+        for (const [id, current] of names) this.set(id, { name: current.name, type: "dm" });
+    }
+
     /**
      * Get thread name by ID. Returns null if not cached.
      * @param {string} threadId