@ardennguyen/zalo-agent-cli 2.0.0 → 2.1.0

package/README.md

@@ -7,6 +7,8 @@
 Công cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR, Official Account API v3.0, và MCP server cho AI agent.
 Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 
+[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
 **[Tiếng Việt](#bắt-đầu-nhanh)** | **[English](#english)**
 
 > [!WARNING]
@@ -47,7 +49,9 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > zalo-agent mcp start                                  # stdio (local Claude Code)
 > zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 12 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage`
+> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+
+[Sync qua MCP và điều kiện phát hành](docs/mcp-sync.vi.md).
 > Auto-reconnect · thread filter · noise reduction · tự tải media · thông báo qua nhóm Zalo
 > Xem [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
@@ -119,7 +123,7 @@ Tất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https:
 | `label` | 2 | Nhãn hội thoại | [Nhãn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%A3n) |
 | `catalog` | 9 | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/ardennguyen/zalo-agent-cli/wiki/zBusiness) |
 | `listen` | 1 | Lắng nghe real-time, webhook, JSONL, ghi vào cache cục bộ | [Lắng nghe](https://github.com/ardennguyen/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |
-| `mcp` | 1 | MCP server (stdio/HTTP) — 12 tools cho AI agent | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server-(VN)) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools cho AI agent | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server-(VN)) |
 | **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, bài viết, cửa hàng, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account-(VN))** |
 
 Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/ardennguyen/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/ardennguyen/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Bộ nhớ đệm & Đồng bộ](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BB%99-Nh%E1%BB%9B-%C4%90%E1%BB%87m-&-%C4%90%E1%BB%93ng-B%E1%BB%99) · [Bảo mật](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A3o-M%E1%BA%ADt)
@@ -132,7 +136,7 @@ Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-
 - Đa tài khoản với proxy riêng biệt (1:1), device fingerprint riêng cho từng tài khoản
 - **190 lệnh** phủ hết tính năng Zalo cá nhân
 - **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, follower, tag, bài viết, cửa hàng, webhook listener, multi-OA
-- **MCP server** (stdio + HTTP) — 12 tools cho Claude Code và các MCP client: đọc, gửi (kể cả vào My Documents, đánh dấu Quan trọng/Khẩn cấp), thả cảm xúc, thu hồi tin, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
+- **MCP server** (stdio + HTTP) — 14 tools cho Claude Code và các MCP client: đọc, gửi (kể cả vào My Documents, đánh dấu Quan trọng/Khẩn cấp), thả cảm xúc, thu hồi tin, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
 - **Bộ nhớ đệm cục bộ (SQLite)** — `listen` ghi mọi tin nhắn vào `zalo.db`, `msg history` đọc từ cache, `sync` (hoặc `sync-mobile`) khôi phục toàn bộ lịch sử từ điện thoại vào `zalo.db` (giải mã transfer-sync-v2; xác nhận một lần trên điện thoại), mặc định lấy **toàn bộ** lịch sử (không còn mốc chặn 2024-01-01); thêm `--days <n>` hoặc `--from <YYYY-MM-DD>` nếu chỉ cần một khoảng. Dọn dẹp: `sync-media --prune <days|all>` giải phóng dung lượng nhưng giữ nguyên nội dung tin nhắn, `--prune-orphans` nhắm vào hội thoại tài khoản không còn, và `conv forget` xoá hẳn bản sao cục bộ của một hội thoại — không cái nào gửi gì tới Zalo. Luồng đồng bộ chỉ mang **liên kết** media chứ không mang file, nên sau khi lưu tin nhắn, `sync-mobile` **tự động tải media về** (thêm `--messages-only` nếu chỉ muốn tin nhắn); `sync-media` chạy lại/tiếp tục bước tải này, không cần xác nhận trên điện thoại. Ghi chú, tin ghim, bình chọn và nhắc hẹn nằm ngoài luồng tin nhắn — dùng `sync-boards`
 - Tự động tải media (ảnh/audio/video) — một downloader duy nhất cho `listen`, `msg history`, `mcp start` và các lệnh sync, lưu vào `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (MCP server có thể ghi đè bằng `media.downloadDir`)
 - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
@@ -159,6 +163,16 @@ Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-
 | [AGENTS.md](AGENTS.md) | Quy tắc dự án cho AI coding agent |
 | [Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki) | Tài liệu công khai, song ngữ EN + VN |
 
+## Giấy phép
+
+zalo-agent-cli © 2026 Arden Nguyen Duc Huy được cấp phép theo [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Xem [LICENSE](LICENSE) và [NOTICE](NOTICE). Điều khoản đầy đủ và cảnh báo rủi ro nằm trong [DISCLAIMER.md](DISCLAIMER.md).
+
+- **Miễn phí cho mục đích phi thương mại**: cá nhân, học thuật, nghiên cứu. **Không cấp phép cho mục đích thương mại** — ví dụ dùng trong sản phẩm thương mại, để cung cấp dịch vụ có thu phí, hoặc trong hoạt động kinh doanh của một công ty. Muốn xin giấy phép thương mại, hãy [mở một issue](https://github.com/ardennguyen/zalo-agent-cli/issues).
+- **Ghi công**: khi chia sẻ dự án này hoặc một phần của nó (nguyên bản hay đã sửa đổi, kể cả bên trong dự án khác), hãy ghi công theo mẫu trong [NOTICE](NOTICE), nêu rõ bạn có sửa đổi hay không, và dẫn link giấy phép.
+- **Chia sẻ tương tự (ShareAlike)**: bản sửa đổi được chia sẻ phải dùng CC BY-NC-SA 4.0 (hoặc phiên bản mới hơn, hoặc giấy phép tương thích do Creative Commons liệt kê).
+- Các phần dẫn xuất từ phần mềm MIT — [zalo-agent-cli của PhucMPham](https://github.com/PhucMPham/zalo-agent-cli) và bản vá của [zca-js](https://github.com/RFS-ADRENO/zca-js) được đóng gói kèm — vẫn thuộc giấy phép MIT; xem [NOTICE](NOTICE).
+- Các phiên bản phát hành trước thay đổi này (2.0.0 trở về trước) được phát hành theo giấy phép MIT và giữ nguyên các điều khoản đó.
+
 ---
 
 ## English
@@ -199,7 +213,9 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > zalo-agent mcp start                                  # stdio (local Claude Code)
 > zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 12 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage`
+> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+
+[MCP sync and release prerequisites](docs/mcp-sync.md).
 > Auto-reconnect · thread filter · noise reduction · media auto-download · Zalo-group notifications
 > See [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
@@ -237,7 +253,7 @@ Full docs: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)** · [Fu
 | `label` | 2 | Conversation labels | [Labels](https://github.com/ardennguyen/zalo-agent-cli/wiki/Labels) |
 | `catalog` | 9 | zBusiness catalogs & products | [Catalog](https://github.com/ardennguyen/zalo-agent-cli/wiki/Catalog) |
 | `listen` | 1 | Real-time listener, webhook, JSONL, local cache writes | [Listener](https://github.com/ardennguyen/zalo-agent-cli/wiki/Listener) |
-| `mcp` | 1 | MCP server (stdio/HTTP) — 12 tools for AI agents | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools for AI agents | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server) |
 | **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, tags, articles, store, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |
 
 See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/Multi-Account-&-Proxy) · [VPS Setup](https://github.com/ardennguyen/zalo-agent-cli/wiki/VPS-Setup) · [Bank Card & QR Payments](https://github.com/ardennguyen/zalo-agent-cli/wiki/Bank-Card-&-QR-Payments) · [Local Cache & Sync](https://github.com/ardennguyen/zalo-agent-cli/wiki/Local-Cache-&-Sync) · [Security](https://github.com/ardennguyen/zalo-agent-cli/wiki/Security)
@@ -248,7 +264,7 @@ See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/
 - Multi-account with a dedicated proxy (1:1) and a per-account device fingerprint
 - **190 commands** covering the personal-account Zalo surface
 - **Zalo Official Account (OA) API v3.0** — OAuth login, messaging, followers, tags, articles, store, webhook listener, multi-OA
-- **MCP server** (stdio + HTTP) — 12 tools for Claude Code and other MCP clients: read, send (to My Documents too, marked Important/Urgent), react, recall, list a group's members, list recent conversations, and check how complete the cache is
+- **MCP server** (stdio + HTTP) — 14 tools for Claude Code and other MCP clients: read, send (to My Documents too, marked Important/Urgent), react, recall, list a group's members, list recent conversations, and check how complete the cache is
 - **Local SQLite cache** — `listen` writes every message to `zalo.db`, `msg history` reads from it, and `sync` (or `sync-mobile`) restores full history from the phone into `zalo.db` (transfer-sync-v2 decrypt; one confirmation on the phone), defaulting to **all** history (the old 2024-01-01 floor is gone), with `--days <n>` or `--from <YYYY-MM-DD>` to narrow it. Housekeeping: `sync-media --prune <days|all>` reclaims disk while keeping message text, `--prune-orphans` targets conversations the account no longer has, and `conv forget` removes a conversation's local copy entirely — none of which contact Zalo. The sync stream carries media **links**, not files, so a `sync-mobile` run **downloads its attachments automatically** once the messages are stored (`--messages-only` skips it); `sync-media` re-runs or resumes that fetch on its own, with no phone confirmation. Notes, pinned messages, polls and reminders live outside the message stream — `sync-boards` fetches those
 - Automatic media download — one downloader shared by `listen`, `msg history`, `mcp start` and the sync commands, saving to `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (the MCP server can override the root with `media.downloadDir`)
 - Bank cards (55+ VN banks) and VietQR payment images
@@ -279,4 +295,10 @@ See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/
 
 ## License
 
-[MIT](LICENSE) · See [DISCLAIMER.md](DISCLAIMER.md) for full terms.
+zalo-agent-cli © 2026 Arden Nguyen Duc Huy is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). See [LICENSE](LICENSE) and [NOTICE](NOTICE). See [DISCLAIMER.md](DISCLAIMER.md) for full terms and risk warnings.
+
+- **Free for non-commercial use** (personal, academic, research). **Commercial use is not licensed** — for example in a commercial product, to provide paid services, or in a company's business operations. To request a commercial license, [open an issue](https://github.com/ardennguyen/zalo-agent-cli/issues).
+- **Credit required:** if you share this project or any part of it, as-is or modified (including inside another project), credit it as shown in [NOTICE](NOTICE), say whether you made changes, and link to the license.
+- **ShareAlike:** shared modifications must be released under CC BY-NC-SA 4.0 (or a later version, or a compatible license listed by Creative Commons).
+- Portions derived from MIT-licensed software — [zalo-agent-cli by PhucMPham](https://github.com/PhucMPham/zalo-agent-cli) and the patched [zca-js](https://github.com/RFS-ADRENO/zca-js) shipped inside the package — remain under the MIT License; see [NOTICE](NOTICE).
+- Versions published before this change (2.0.0 and earlier) were released under the MIT License and keep those terms.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ardennguyen/zalo-agent-cli",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {
@@ -10,6 +10,7 @@
     "files": [
         "DISCLAIMER.md",
         "LICENSE",
+        "NOTICE",
         "patches/",
         "src/"
     ],
@@ -45,7 +46,7 @@
         "url": "https://github.com/ardennguyen/zalo-agent-cli"
     },
     "author": "ardennguyen",
-    "license": "MIT",
+    "license": "CC-BY-NC-SA-4.0",
     "publishConfig": {
         "access": "public"
     },
@@ -76,6 +77,6 @@
     },
     "allowScripts": {
         "better-sqlite3@13.0.3": true,
-        "@ardennguyen/zalo-agent-cli@2.0.0": true
+        "@ardennguyen/zalo-agent-cli@2.0.1": true
     }
 }

package/src/commands/listen.js

@@ -5,9 +5,9 @@
 
 import { appendFileSync, mkdirSync, existsSync } from "fs";
 import { resolve, join } from "path";
-import { getApi, autoLogin, clearSession } from "../core/zalo-client.js";
+import { getApi, clearSession } from "../core/zalo-client.js";
 import { success, error, info, warning } from "../utils/output.js";
-import { getActive } from "../core/accounts.js";
+import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
 import { CONFIG_DIR } from "../core/credentials.js";
 import { acquireLock, releaseLock } from "../core/lock.js";
 import { createStageLock, startDaemonChannel } from "../core/daemon-channel.js";
@@ -55,6 +55,11 @@ const CLOSE_DUPLICATE = 3000;
 export function registerListenCommand(program) {
     program
         .command("listen")
+        .option(
+            "--account <id>",
+            "Pin this daemon to an exact registered account ID (default: active at startup)",
+            parseAccountId,
+        )
         .description(
             "Listen for all Zalo events (messages, friend requests, group events) via one WebSocket. Auto-reconnect enabled.",
         )
@@ -77,9 +82,11 @@ export function registerListenCommand(program) {
             "Do not pull what a dropped socket missed from Zalo's offline queue on reconnect (the default does, as Zalo Web does, on this socket and with no phone tap)",
         )
         .action(async (opts) => {
-            const activeAcc = getActive();
-            if (!activeAcc) {
-                error("No active account. Please login first.");
+            let activeAcc;
+            try {
+                activeAcc = selectDaemonAccount(opts.account);
+            } catch (e) {
+                error(e.message);
                 process.exit(1);
             }
             const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
@@ -104,6 +111,13 @@ export function registerListenCommand(program) {
                     console.error(`[listen] Failed to release lock: ${e.message}`);
                 }
             };
+            try {
+                await loginDaemonAccount(activeAcc);
+            } catch (e) {
+                releaseLock(accountDir);
+                error(`Pinned account login failed: ${e.message}`);
+                process.exit(1);
+            }
             try {
                 initDb(join(accountDir, "zalo.db"));
                 info(`Local database initialized at ${accountDir}/zalo.db`);
@@ -703,7 +717,7 @@ export function registerListenCommand(program) {
                     await new Promise((r) => setTimeout(r, 5000));
                     try {
                         clearSession();
-                        await autoLogin(jsonMode);
+                        await loginDaemonAccount(activeAcc);
                         info("Re-login successful. Restarting listener...");
                         // Attach ALL handlers to the NEW api (including lifecycle),
                         // and repoint the SyncManager at it so its bookkeeping
@@ -717,7 +731,7 @@ export function registerListenCommand(program) {
                         await new Promise((r) => setTimeout(r, 30000));
                         try {
                             clearSession();
-                            await autoLogin(jsonMode);
+                            await loginDaemonAccount(activeAcc);
                             const retryApi = getApi();
                             syncManager.api = retryApi;
                             attachAllHandlers(retryApi);

package/src/commands/mcp.js

@@ -6,13 +6,14 @@
  */
 
 import { join } from "path";
-import { getApi, autoLogin, clearSession } from "../core/zalo-client.js";
+import { getApi, clearSession } from "../core/zalo-client.js";
 import { liveApi } from "../core/live-api.js";
-import { getActive } from "../core/accounts.js";
+import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
 import { CONFIG_DIR } from "../core/credentials.js";
 import { acquireLock, releaseLock } from "../core/lock.js";
 import { createStageLock, startDaemonChannel } from "../core/daemon-channel.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
+import { createSyncJobs } from "../mcp/sync-jobs.js";
 import { createSocketTap } from "../core/socket-tap.js";
 import { createSelfHeal } from "../core/self-heal.js";
 import { createReadStateSync } from "../core/read-state.js";
@@ -93,6 +94,11 @@ export function registerMCPCommands(program) {
     const mcp = program.command("mcp").description("MCP server for AI agent integration");
 
     mcp.command("start")
+        .option(
+            "--account <id>",
+            "Pin this server to an exact registered account ID (default: active at startup)",
+            parseAccountId,
+        )
         .description("Start MCP server (stdio or HTTP transport)")
         .option("--config <path>", "Config file path (default: ~/.zalo-agent-cli/mcp-config.json)")
         .option("--http <port>", "Use HTTP transport on specified port (default: stdio)")
@@ -134,18 +140,12 @@ export function registerMCPCommands(program) {
                 process.exit(1);
             }
 
-            // Perform login explicitly here — preAction hook skips "mcp"
-            // Pass jsonMode=true to suppress info() output — stdout is the MCP transport channel
+            // Select once; acquire the selected account's lock before authentication.
+            let activeAcc;
             try {
-                await autoLogin(true);
+                activeAcc = selectDaemonAccount(opts.account);
             } catch (e) {
-                console.error("[mcp] Auto-login failed:", e.message);
-                process.exit(1);
-            }
-
-            const activeAcc = getActive();
-            if (!activeAcc) {
-                console.error("[mcp] No active account. Run `zalo-agent login` first.");
+                console.error("[mcp] Account selection failed:", e.message);
                 process.exit(1);
             }
             const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
@@ -182,6 +182,13 @@ export function registerMCPCommands(program) {
                 }
             };
 
+            try {
+                await loginDaemonAccount(activeAcc);
+            } catch (e) {
+                dropLock();
+                console.error("[mcp] Pinned account login failed:", e.message);
+                process.exit(1);
+            }
             try {
                 initDb(join(accountDir, "zalo.db"));
                 console.error(`[mcp] Local cache: ${join(accountDir, "zalo.db")}`);
@@ -211,6 +218,8 @@ export function registerMCPCommands(program) {
             // self-heal catch-up and the tools' own history fetch. Created before
             // the server so the tools can hold it too.
             const stageLock = createStageLock();
+            const syncRunners = createSyncRunners({ getApi, accountName: activeAcc.ownId });
+            const syncJobs = createSyncJobs({ runners: syncRunners, lock: stageLock });
 
             // What the tools and the notifier call. Not getApi()'s object:
             // a re-login after a dropped connection replaces it, and they
@@ -231,7 +240,16 @@ export function registerMCPCommands(program) {
                         process.exit(1);
                     }
                     const host = opts.host || "127.0.0.1";
-                    const deps = { api: sessionApi, buffer, filter, config, nameCache, accountDir, stageLock };
+                    const deps = {
+                        api: sessionApi,
+                        buffer,
+                        filter,
+                        config,
+                        nameCache,
+                        accountDir,
+                        stageLock,
+                        syncJobs,
+                    };
                     const authToken = opts.auth?.trim() || null;
                     httpServer = createHTTPServer(registerTools, deps, port, authToken, host);
                     console.error(`[mcp] HTTP server started on port ${port}`);
@@ -242,7 +260,16 @@ export function registerMCPCommands(program) {
                         );
                     }
                 } else {
-                    await createMCPServer(sessionApi, buffer, filter, config, nameCache, accountDir, stageLock);
+                    await createMCPServer(
+                        sessionApi,
+                        buffer,
+                        filter,
+                        config,
+                        nameCache,
+                        accountDir,
+                        stageLock,
+                        syncJobs,
+                    );
                 }
             } catch (e) {
                 dropLock();
@@ -471,7 +498,7 @@ export function registerMCPCommands(program) {
                     await new Promise((r) => setTimeout(r, 5000));
                     try {
                         clearSession();
-                        await autoLogin(true);
+                        await loginDaemonAccount(activeAcc);
                         console.error("[mcp] Re-login successful. Restarting listener...");
                         const newApi = getApi();
                         attachListenerHandlers(newApi);
@@ -481,7 +508,7 @@ export function registerMCPCommands(program) {
                         await new Promise((r) => setTimeout(r, 30000));
                         try {
                             clearSession();
-                            await autoLogin(true);
+                            await loginDaemonAccount(activeAcc);
                             const retryApi = getApi();
                             attachListenerHandlers(retryApi);
                             retryApi.listener.start({ retryOnClose: true });
@@ -518,7 +545,7 @@ export function registerMCPCommands(program) {
                         getApi,
                         accountDir,
                         onLog: (m) => console.error(`[mcp] ${m}`),
-                        runners: createSyncRunners({ getApi, accountName: activeAcc.ownId }),
+                        runners: syncRunners,
                         // The self-heal's lock: a stage and a catch-up never share the socket.
                         lock: stageLock,
                     });

package/src/commands/msg.js

@@ -7,6 +7,7 @@ import { existsSync } from "node:fs";
 import { resolve, join } from "path";
 import { InvalidArgumentError } from "commander";
 import { getApi, getOwnId } from "../core/zalo-client.js";
+import { withCurrentSenderNames } from "../core/current-user-names.js";
 import { success, error, info, output, warning } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
 import { getActive } from "../core/accounts.js";
@@ -1556,16 +1557,20 @@ export function registerMsgCommands(program) {
                         } catch {
                             /* showing history must not fail because media did */
                         }
-                        const messages = localMsgs.map((m) => ({
-                            msgId: m.msgId,
-                            threadId: m.threadId,
-                            senderId: m.senderId,
-                            senderName: m.senderName,
-                            text: m.text,
-                            timestamp: m.timestamp,
-                            type: m.type,
-                            localPath: m.localPath,
-                        }));
+                        const messages = await withCurrentSenderNames(
+                            api,
+                            localMsgs.map((m) => ({
+                                msgId: m.msgId,
+                                threadId: m.threadId,
+                                senderId: m.senderId,
+                                senderName: m.senderName,
+                                text: m.text,
+                                timestamp: m.timestamp,
+                                type: m.type,
+                                localPath: m.localPath,
+                            })),
+                            threadType === 0 ? [threadId] : [],
+                        );
 
                         output(
                             {
@@ -1580,7 +1585,7 @@ export function registerMsgCommands(program) {
                                 success(`${messages.length} message(s) from ${threadId} (Local Cache)`);
                                 for (const m of messages) {
                                     const date = m.timestamp ? new Date(m.timestamp).toLocaleString() : "?";
-                                    const name = m.senderName || m.senderId || "?";
+                                    const name = m.senderDisplayName || m.senderId || "?";
                                     const mediaInfo = m.localPath ? ` [Media: ${m.localPath}]` : "";
                                     console.log(`  [${date}] ${name}: ${(m.text || "").slice(0, 200)}${mediaInfo}`);
                                 }
@@ -1707,11 +1712,15 @@ export function registerMsgCommands(program) {
                 const result = mergedArray.slice(0, limit);
 
                 // Format final output
-                const cleanResult = result.map((m) => {
-                    const r = { ...m };
-                    delete r.raw_data;
-                    return r;
-                });
+                const cleanResult = await withCurrentSenderNames(
+                    api,
+                    result.map((m) => {
+                        const r = { ...m };
+                        delete r.raw_data;
+                        return r;
+                    }),
+                    threadType === 0 ? [threadId] : [],
+                );
 
                 output(
                     {
@@ -1728,7 +1737,7 @@ export function registerMsgCommands(program) {
                         success(`${cleanResult.length} message(s) from ${threadId}`);
                         for (const m of cleanResult) {
                             const date = m.timestamp ? new Date(m.timestamp).toLocaleString() : "?";
-                            const name = m.senderName || m.senderId || "?";
+                            const name = m.senderDisplayName || m.senderId || "?";
                             const mediaInfo = m.localPath ? ` [Media: ${m.localPath}]` : "";
                             console.log(`  [${date}] ${name}: ${(m.text || "").slice(0, 200)}${mediaInfo}`);
                         }

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

@@ -0,0 +1,104 @@
+/**
+ * Read the account's complete alias snapshot. Do not reuse a previous snapshot:
+ * an absent entry means the owner removed that alias. Failed/partial reads do
+ * not pretend an old alias is current. Diagnostics never include identities.
+ * @param {object} api - current authenticated API
+ * @param {Function} [log] - diagnostic sink
+ * @returns {Promise<Map<string, string>>} UID -> account-owned alias
+ */
+export async function readUserAliases(api, log = () => {}) {
+    const aliases = new Map();
+    try {
+        if (typeof api?.getAliasList !== "function") return aliases;
+        for (let page = 1; page <= 1000; page++) {
+            const result = await api.getAliasList(100, page);
+            if (!Array.isArray(result?.items)) throw new Error("invalid alias page");
+            let added = 0;
+            for (const item of result.items) {
+                if (item.userId && typeof item.alias === "string" && item.alias.trim()) {
+                    const uid = String(item.userId);
+                    if (!aliases.has(uid)) added++;
+                    aliases.set(uid, item.alias);
+                }
+            }
+            if (result.items.length < 100) return aliases;
+            if (!added) throw new Error("alias pagination did not advance");
+        }
+        throw new Error("alias pagination limit reached");
+    } catch {
+        log("current aliases unavailable; falling back to profile names or UIDs");
+        return new Map();
+    }
+}
+
+/**
+ * Select a current label independently of any per-message historical name.
+ * @param {string} uid - canonical user ID
+ * @param {object} [profile] - fresh Zalo profile
+ * @param {Map<string, string>} [aliases] - account-owned aliases
+ * @returns {{name: string, source: string}} label and provenance
+ */
+export function currentUserName(uid, profile, aliases = new Map()) {
+    const id = String(uid || "");
+    const alias = aliases.get(id);
+    if (alias) return { name: alias, source: "alias" };
+    // displayName can itself be an alias. Only zaloName establishes the
+    // profile-name fallback independently of the owner's alias snapshot.
+    const name = profile?.zaloName;
+    return name ? { name, source: "zalo" } : { name: id, source: "uid" };
+}
+
+/**
+ * Resolve current names in batches, with no cross-request/account name cache.
+ * Failures degrade to UID, never to a historical senderName. Profiles can be
+ * supplied by a fresh friend-list response to avoid fetching them twice.
+ * @param {object} api - current authenticated API
+ * @param {string[]} uids - IDs to display
+ * @param {object} [options]
+ * @returns {Promise<Map<string, {name: string, source: string}>>} UID -> current label
+ */
+export async function resolveCurrentUserNames(api, uids, { aliases, profiles = new Map(), log = () => {} } = {}) {
+    const ids = [...new Set(uids.filter(Boolean).map(String))];
+    if (!ids.length) return new Map();
+    const aliasRequest = aliases ? Promise.resolve(aliases) : readUserAliases(api, log);
+    const fresh = new Map(profiles);
+    const missing = ids.filter((id) => /^[1-9][0-9]*$/.test(id) && !fresh.has(id));
+    for (let i = 0; i < missing.length; i += 100) {
+        try {
+            if (typeof api?.getUserInfo !== "function") break;
+            const result = await api.getUserInfo(missing.slice(i, i + 100));
+            for (const bag of [result?.changed_profiles, result?.unchanged_profiles]) {
+                for (const [uid, profile] of Object.entries(bag || {})) {
+                    if (profile) fresh.set(uid, profile);
+                }
+            }
+        } catch {
+            log("current profiles unavailable; falling back to aliases or UIDs");
+        }
+    }
+    const ownedAliases = await aliasRequest;
+    return new Map(ids.map((id) => [id, currentUserName(id, fresh.get(id), ownedAliases)]));
+}
+
+/**
+ * Decorate copied messages with current labels; senderName stays historical.
+ * DM titles use the peer's UID, including for an outgoing message from self.
+ * @param {object} api - current authenticated API
+ * @param {object[]} messages - cached or live rows
+ * @param {string[]} [dmThreadIds] - known DM peer IDs, never group IDs
+ * @returns {Promise<object[]>} detached display rows
+ */
+export async function withCurrentSenderNames(api, messages, dmThreadIds = []) {
+    const peers = new Set(dmThreadIds.map(String));
+    const names = await resolveCurrentUserNames(api, [...messages.map((m) => m.senderId), ...peers]);
+    return messages.map((m) => {
+        const sender = names.get(String(m.senderId)) || { name: null, source: "uid" };
+        const peer = peers.has(String(m.threadId)) && names.get(String(m.threadId));
+        return {
+            ...m,
+            senderDisplayName: sender.name,
+            senderDisplayNameSource: sender.source,
+            ...(peer && { threadName: peer.name }),
+        };
+    });
+}

package/src/core/daemon-account.js

@@ -0,0 +1,61 @@
+import { InvalidArgumentError } from "commander";
+import { getActive, getAccount } from "./accounts.js";
+import { loadCredentials } from "./credentials.js";
+import { loginWithCredentials, clearSession } from "./zalo-client.js";
+
+/** Validate a full numeric account ID without number coercion, names, or prefix matching. */
+export function parseAccountId(value) {
+    if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value)) {
+        throw new InvalidArgumentError("--account requires a full numeric account ID, not a name or partial ID");
+    }
+    return value;
+}
+
+/**
+ * Snapshot one daemon's account at startup without changing the shared registry.
+ * Even an implicit active-account selection stays pinned for this process.
+ * @param {string} [id] - exact registered account ID, never a display name
+ * @param {object} [deps] - offline-test collaborators
+ * @returns {Readonly<object>} frozen account identity and proxy configuration
+ */
+export function selectDaemonAccount(id, { active = getActive, lookup = getAccount } = {}) {
+    const selected = id === undefined ? active() : lookup(parseAccountId(id));
+    if (!selected) {
+        throw new Error(
+            id === undefined
+                ? "No active account. Please login first. You can also pass --account <ID>."
+                : "Account ID is not registered. Use `zalo-agent account list` to find the full ID.",
+        );
+    }
+    const ownId = parseAccountId(selected.ownId);
+    if (id !== undefined && ownId !== id) throw new Error("Account lookup returned a different ID; refusing to start");
+    return Object.freeze({ ...selected, ownId });
+}
+
+/**
+ * Authenticate only the daemon's pinned account, including after a disconnect.
+ * Never consult the active registry or retain a session for a different user.
+ * The caller must hold this account's daemon lock before invoking this function.
+ * @param {object} account - selectDaemonAccount() snapshot
+ * @param {object} [deps] - offline-test collaborators
+ * @returns {Promise<object>} authenticated API/ownId result
+ */
+export async function loginDaemonAccount(
+    account,
+    { read = loadCredentials, login = loginWithCredentials, reset = clearSession } = {},
+) {
+    const id = parseAccountId(account.ownId);
+    reset();
+    const credentials = read(id);
+    if (!credentials) throw new Error("No saved credentials for the pinned account. Log in to that account first.");
+    try {
+        const session = await login(credentials, account.proxy || null);
+        if (String(session?.ownId || "") !== id) {
+            throw new Error("Authenticated account does not match the pinned ID; refusing to attach its listener");
+        }
+        return session;
+    } catch (e) {
+        reset();
+        throw e;
+    }
+}

package/src/core/daemon-sync.js

@@ -69,8 +69,8 @@ export function createSyncRunners({ getApi, accountName }) {
          *
          * Still prompts the owner's phone exactly once — routing through the
          * daemon removes the second WebSocket, not the confirmation. The
-         * daemon never calls this on its own; only a `zalo-agent sync` the
-         * owner typed reaches it.
+         * daemon never calls this on its own; an explicit CLI sync or MCP
+         * sync request authorized by the owner reaches it.
          *
          * @param {{days?: number|null, from?: string|number, waitMs?: number,
          *   shardSize?: number, waveSize?: number}} params

package/src/core/db.js

@@ -446,10 +446,25 @@ export function runInTransaction(fn) {
 export function insertMessage(msg) {
     if (!db) throw new Error("Database not initialized");
 
+    // A replay may resolve an opaque sender from an older sync. Never let an
+    // unresolved replay replace a canonical live UID, or a different numeric
+    // sender overwrite an already established identity.
+    const canResolveSender = `(
+      COALESCE(messages.senderId, '') = '' OR
+      (messages.senderId GLOB '*[^0-9]*' AND
+       excluded.senderId <> '' AND excluded.senderId <> '0' AND
+       excluded.senderId NOT GLOB '*[^0-9]*')
+    )`;
     const stmt = db.prepare(`
     INSERT INTO messages (msgId, threadId, senderId, senderName, text, timestamp, type, raw_data, localPath, has_attachment, msgStatus)
     VALUES (@msgId, @threadId, @senderId, @senderName, @text, @timestamp, @type, @raw_data, @localPath, @has_attachment, @msgStatus)
     ON CONFLICT(msgId) DO UPDATE SET
+      senderId = CASE WHEN ${canResolveSender} THEN excluded.senderId ELSE messages.senderId END,
+      senderName = CASE
+        WHEN COALESCE(messages.senderName, '') = '' AND
+             (messages.senderId = excluded.senderId OR ${canResolveSender})
+        THEN COALESCE(NULLIF(excluded.senderName, ''), messages.senderName)
+        ELSE messages.senderName END,
       -- A removal is terminal. Once a row is a tombstone, a later write of the
       -- same msgId -- a re-sync, a history replay, a backfill -- must not bring
       -- the message back or replace the tombstone's record of HOW it was