@ardennguyen/zalo-agent-cli 2.0.0 → 2.1.1

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,9 +136,9 @@ 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`)
+- 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>/` (hoặc tách riêng credentials, database `zalo.db`, media và OA sang các ổ đĩa/mount khác nhau qua `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / biến môi trường `ZALO_*_DIR` trong `~/.zalo-agent-cli/.env`; nếu dùng kèm `zalo-mcp`, chỉ nên giữ cấu hình PORT trong `zalo-mcp/.env` và đặt toàn bộ đường dẫn lưu trữ vào `<CONFIG_DIR>/.env`)
 - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
 - Lắng nghe real-time với webhook & lưu JSONL local
 - `logout` hủy phiên **phía server** thật sự; `logout --purge` / `account remove` xóa sạch dữ liệu cục bộ
@@ -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,9 +264,9 @@ 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`)
+- 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>/` (or separate credentials, `zalo.db`, media, and OA credentials onto independent volumes/mounts via `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / `ZALO_*_DIR` in `~/.zalo-agent-cli/.env`; when using `zalo-mcp`, keep `zalo-mcp/.env` for PORT settings only and place all storage/engine settings in `<CONFIG_DIR>/.env`)
 - Bank cards (55+ VN banks) and VietQR payment images
 - Real-time listener with webhook forwarding and local JSONL archival
 - `logout` performs a real **server-side** session invalidation; `logout --purge` / `account remove` wipe all local data
@@ -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.1",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {
@@ -8,8 +8,10 @@
     },
     "main": "./src/index.js",
     "files": [
+        ".env.example",
         "DISCLAIMER.md",
         "LICENSE",
+        "NOTICE",
         "patches/",
         "src/"
     ],
@@ -45,7 +47,7 @@
         "url": "https://github.com/ardennguyen/zalo-agent-cli"
     },
     "author": "ardennguyen",
-    "license": "MIT",
+    "license": "CC-BY-NC-SA-4.0",
     "publishConfig": {
         "access": "public"
     },
@@ -61,7 +63,6 @@
         "google-protobuf": "^3.21.4",
         "https-proxy-agent": "^9.1.0",
         "image-size": "^2.0.4",
-        "node-fetch": "^3.3.2",
         "undici": "^8.5.0",
         "zca-js": "2.2.0",
         "zod": "^4.4.3"
@@ -76,6 +77,6 @@
     },
     "allowScripts": {
         "better-sqlite3@13.0.3": true,
-        "@ardennguyen/zalo-agent-cli@2.0.0": true
+        "@ardennguyen/zalo-agent-cli@2.1.1": true
     }
 }

package/src/commands/conv.js

@@ -3,12 +3,11 @@
  * mute, unmute, read, unread, delete.
  */
 
-import { join } from "path";
 import { MuteAction } from "zca-js";
 import { getApi } from "../core/zalo-client.js";
 import { success, error, info, output, warning } from "../utils/output.js";
 import { getActive } from "../core/accounts.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDbPath } from "../core/credentials.js";
 import { initDb, getMessages, getReadStates, markThreadGone, getOrphanThreads, forgetThread } from "../core/db.js";
 import { recentConversations } from "../core/recent-conversations.js";
 import { describeReadState, readStateLabel } from "../core/read-state.js";
@@ -41,7 +40,7 @@ async function newestMessageAnchor(api, threadId, type) {
     try {
         const activeAcc = getActive();
         if (activeAcc) {
-            initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+            initDb(getAccountDbPath(activeAcc.ownId));
             cacheOpen = true;
         }
     } catch {
@@ -231,8 +230,7 @@ export function registerConvCommands(program, deps = {}) {
             }
 
             try {
-                const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
-                initDb(join(accountDir, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 // `-n` is documented as "max results per type", and the live
                 // path below honors that (up to `limit` friends AND up to
                 // `limit` groups). The cache path used to apply `limit`
@@ -524,7 +522,7 @@ export function registerConvCommands(program, deps = {}) {
 
             let result;
             try {
-                initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 const rows = getMessages(String(threadId), SEEN_ANCHOR_SCAN_DEPTH);
                 result = await markConversationRead(zaloApi(), { threadId, type, ownId: activeAcc.ownId, rows });
             } catch (e) {
@@ -749,8 +747,7 @@ export function registerConvCommands(program, deps = {}) {
                 error("Give a threadId, or --orphans to forget every conversation the account no longer has.");
                 process.exit(1);
             }
-            const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
-            initDb(join(accountDir, "zalo.db"));
+            initDb(getAccountDbPath(activeAcc.ownId));
 
             const targets = opts.orphans
                 ? getOrphanThreads().map((t) => ({ threadId: String(t.threadId), name: t.name, ...t }))

package/src/commands/listen.js

@@ -5,10 +5,10 @@
 
 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 { CONFIG_DIR } from "../core/credentials.js";
+import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
+import { getAccountDir } 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";
@@ -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,12 +82,14 @@ 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);
+            const accountDir = getAccountDir(activeAcc.ownId);
             if (!acquireLock(accountDir)) {
                 error(`Another listen daemon is already running for account ${activeAcc.ownId}.`);
                 process.exit(1);
@@ -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 { CONFIG_DIR } from "../core/credentials.js";
+import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
+import { getAccountDir, MEDIA_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,21 +140,15 @@ 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);
+                console.error("[mcp] Account selection failed:", e.message);
                 process.exit(1);
             }
-
-            const activeAcc = getActive();
-            if (!activeAcc) {
-                console.error("[mcp] No active account. Run `zalo-agent login` first.");
-                process.exit(1);
-            }
-            const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+            const accountDir = getAccountDir(activeAcc.ownId);
 
             // This server now opens the account's WebSocket *and* writes to
             // zalo.db, which is exactly what the `listen` daemon does. Zalo
@@ -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();
@@ -358,7 +385,7 @@ export function registerMCPCommands(program) {
                     threadId,
                     limit: 5,
                     concurrency: 2,
-                    mediaRoot: config.media?.downloadDir || undefined,
+                    mediaRoot: MEDIA_DIR || config.media?.downloadDir || undefined,
                 }).catch((e) => console.error(`[mcp] media download failed: ${e.message}`));
             }
 
@@ -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,10 +7,11 @@ 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";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDir, getAccountDbPath } from "../core/credentials.js";
 import { initDb, getMessages, getMessageById, getDisplayName, getThreadType } from "../core/db.js";
 import { sendViaDaemon, getDaemonChannel, getSyncChannel, syncViaDaemon } from "../core/daemon-channel.js";
 import { fetchAndCacheHistory } from "../core/history-fetch.js";
@@ -46,7 +47,7 @@ function openAccountDb() {
     try {
         const acc = getActive();
         if (!acc) return false;
-        initDb(join(CONFIG_DIR, "accounts", acc.ownId, "zalo.db"));
+        initDb(getAccountDbPath(acc.ownId));
         return true;
     } catch {
         return false;
@@ -446,7 +447,7 @@ async function sendAttachments(api, absPaths, threadId, type, opts) {
     if (needsListener) {
         const acc = getActive();
         if (acc) {
-            const viaDaemon = await sendViaDaemon(join(CONFIG_DIR, "accounts", acc.ownId), {
+            const viaDaemon = await sendViaDaemon(getAccountDir(acc.ownId), {
                 paths: absPaths,
                 threadId,
                 type,
@@ -1210,7 +1211,7 @@ export function registerMsgCommands(program) {
 
             let row;
             try {
-                initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 row = getMessageById(msgId);
             } catch (e) {
                 error(
@@ -1529,7 +1530,7 @@ export function registerMsgCommands(program) {
             let dbActive = false;
 
             try {
-                const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+                const accountDir = getAccountDir(activeAcc.ownId);
                 initDb(join(accountDir, "zalo.db"));
                 dbActive = true;
 
@@ -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}`);
                                 }
@@ -1620,7 +1625,7 @@ export function registerMsgCommands(program) {
                 // session the scan needs and is the one db writer (AGENTS.md
                 // §13). With a daemon up that is the daemon, and this command
                 // only displays what it returns.
-                const daemonDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+                const daemonDir = getAccountDir(activeAcc.ownId);
                 const daemon = getDaemonChannel(daemonDir);
                 let fetched = null;
                 let handledByDaemon = false;
@@ -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}`);
                         }