@ardennguyen/zalo-agent-cli 2.5.4 → 2.5.6

package/.env.example

@@ -4,7 +4,7 @@
 # Recommended location: `~/.zalo-agent-cli/.env` (`<CONFIG_DIR>/.env`), or pass
 # `--env-file /path/to/.env` (`ZALO_ENV_FILE=/path/to/.env`).
 # Note: If you also use the `zalo-mcp` deployment wrapper, keep `zalo-mcp/.env`
-# for port settings (`ZALO_MCP_HTTP_PORT`, `ZALO_OA_WEBHOOK_PORT`) only, and put
+# for the port (`ZALO_MCP_HTTP_PORT`) only, and put
 # all storage paths and engine settings in `<CONFIG_DIR>/.env` so `zalo-mcp` and
 # `zalo-agent` share a single source of truth.
 # CLI flags and shell environment variables take precedence over `.env` values.
@@ -33,3 +33,25 @@
 # Protocol version announced to Zalo (default: 691; set 685 to roll back):
 # ZALO_API_VERSION=691
 
+# ----------------------------------------------------------------------------
+# MCP server / CRM backend (`zalo-agent mcp start`; all optional)
+# Ready-to-copy files for local, LAN, internet, CRM and many-account setups:
+# docs/configuration.md and docs/config-samples/. Every name below also takes a
+# per-account form, e.g. ZALO_MCP_HTTP_PORT_<ownId>, which beats the plain name.
+# Put secrets here (file mode 0600), never on the command line: a flag shows in `ps`.
+# ----------------------------------------------------------------------------
+# ZALO_MCP_HTTP_PORT=3847                 # serve HTTP instead of stdio
+# ZALO_MCP_HOST=127.0.0.1                 # bind address; never 0.0.0.0 without a token
+# ZALO_MCP_AUTH_TOKEN=                    # bearer token: openssl rand -hex 32
+# ZALO_WEBHOOK_URL=                       # POST each incoming message here
+# ZALO_WEBHOOK_SECRET=                    # signs it (X-Zalo-Signature: sha256=...)
+# ZALO_WEBHOOK_BATCH_SIZE=1               # events per POST (1-100); the webhook retries and survives restarts
+# ZALO_WEBHOOK_MAX_AGE=24h                # an undelivered event older than this is dead-lettered
+# ZALO_LOG_LEVEL=info                     # daemon.log: error | warn | info | debug (debug adds a line per request and message)
+# ZALO_LOG_FORMAT=text                    # or json (one object per line)
+# ZALO_LOG_MAX_SIZE=50m                   # rotate daemon.log at this size ...
+# ZALO_LOG_KEEP=3                         # ... keeping this many files
+# ZALO_START_JITTER=0                     # seconds: wait 0-N s before logging in (a fleet restarting together)
+# ZALO_LOGIN_SLOTS=0                      # at most N daemons on the machine logging in at once; 0 = no cap
+# ZALO_SEND_FORMAT=plain                  # markdown | plain: how text messages are sent (the MCP tool defaults to markdown)
+

package/README.md

@@ -28,7 +28,7 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > clawhub install zalo-agent          # OpenClaw (từ ClawHub registry)
 > cp -r skill/ ~/.claude/skills/zalo-agent/   # Claude Code
 > ```
-> 17 nhóm lệnh · 212 lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
+> 18 nhóm lệnh · 222 lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
 > Xem [skill/SKILL.md](skill/SKILL.md) · [Tham chiếu lệnh đầy đủ](skill/references/command-reference.md) · [Eval scenarios](skill/evals/)
 
 > [!NOTE]
@@ -138,13 +138,15 @@ Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-
 
 - Đăng nhập QR qua HTTP server tự động (browser + terminal), báo ngay khi bị **từ chối trên điện thoại** thay vì treo tới hết 60s
 - Đ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; chạy **nhiều tài khoản live đồng thời** (mỗi tài khoản một tiến trình `mcp start` hoặc `listen` kèm `--account <ID>`, và truyền `--account <ID>` / `ZALO_ACCOUNT` trên mọi lệnh CLI mà không ghi đè `accounts.json`)
-- **212 lệnh** phủ hết tính năng Zalo cá nhân
+- **222 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/HTTPS + OAuth 2.0) — 25 tools cho Claude Code, Gemini và các MCP client: đọc, chờ tin nhắn đến (`zalo_wait_for_message`), gửi (văn bản, link preview, danh thiếp, vào My Documents, đánh dấu Quan trọng/Khẩn cấp), tìm kiếm tin nhắn trong cache, tra cứu người dùng, gắn/gỡ nhãn hội thoại (`zalo_label`), xem bạn bè và xử lý lời mời kết bạn (`zalo_friend`), xem thông tin nhóm, tạo nhóm, thêm/xóa thành viên và rời nhóm (`zalo_group`), thả cảm xúc, thu hồi, chuyển tiếp, xóa tin, nhắc hẹn, ghi chú/ghim tin, bình chọn, 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>/` (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
+- Lắng nghe real-time với webhook & lưu JSONL local. Webhook **bền vững**: mỗi sự kiện ghi xuống đĩa rồi mới gửi, đúng thứ tự, thử lại khi bên nhận hỏng, sống sót qua khởi động lại (`mcp webhook status`)
+- **Vận hành nhiều tài khoản**: `/health`, `/ready`, `/status` và `/metrics` (Prometheus), `fleet status|start|restart|generate`, mức log + xoay vòng `daemon.log`, `ZALO_START_JITTER` / `ZALO_LOGIN_SLOTS` — xem `docs/deployment.vi.md` §4.7–4.8
+- Tin nhắn **Markdown** được chuyển thành định dạng thật của Zalo (đậm, nghiêng, gạch đầu dòng, tiêu đề) — `zalo_send_message` mặc định, `msg send --markdown`
 - `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ộ
 - Output `--json` cho mọi lệnh — scripting & AI agents
 - Credentials lưu cục bộ với quyền 0600
@@ -197,7 +199,7 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > clawhub install zalo-agent                    # OpenClaw (from ClawHub registry)
 > cp -r skill/ ~/.claude/skills/zalo-agent/     # Claude Code
 > ```
-> 17 command groups · 212 commands · listen mode + webhook · 55+ VN banks · multi-account + proxy
+> 18 command groups · 222 commands · listen mode + webhook · 55+ VN banks · multi-account + proxy
 > See [skill/SKILL.md](skill/SKILL.md) · [Full command reference](skill/references/command-reference.md) · [Eval scenarios](skill/evals/)
 
 > [!NOTE]
@@ -271,13 +273,15 @@ See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/
 
 - QR login over an auto-started HTTP server (browser + terminal), reporting a **decline on the phone** immediately instead of hanging until the 60s timeout
 - Multi-account with a dedicated proxy (1:1) and a per-account device fingerprint; run **multiple live accounts simultaneously** (one `mcp start` or `listen` process per account with `--account <ID>`, plus `--account <ID>` / `ZALO_ACCOUNT` on any CLI command without mutating `accounts.json`)
-- **212 commands** covering the personal-account Zalo surface
+- **222 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/HTTPS + OAuth 2.0) — 25 tools for Claude Code, Gemini and other MCP clients: read, wait for incoming messages (`zalo_wait_for_message`), send (text, local file/image attachments, link previews, contact cards, to My Documents too, marked Important/Urgent), search cached messages, look up users, manage conversation labels (`zalo_label`), list friends and handle friend requests (`zalo_friend`), inspect, create and manage groups and leave them (`zalo_group`), react, recall, forward, delete, reminders, group notes/pins, group polls, 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>/` (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
+- Real-time listener with webhook forwarding and local JSONL archival. The webhook is **durable**: each event is written to disk first, then delivered in order, retried while the receiver is down, and kept across restarts (`mcp webhook status`)
+- **Running many accounts**: `/health`, `/ready`, `/status` and `/metrics` (Prometheus), `fleet status|start|restart|generate`, log levels and `daemon.log` rotation, `ZALO_START_JITTER` / `ZALO_LOGIN_SLOTS` — see `docs/deployment.md` §4.7–4.8
+- **Markdown** messages become real Zalo formatting (bold, italic, bullets, headings): the default in `zalo_send_message`, `msg send --markdown` on the CLI
 - `logout` performs a real **server-side** session invalidation; `logout --purge` / `account remove` wipe all local data
 - `--json` output on every command — scripting and AI agents
 - Credentials stored locally with 0600 permissions

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ardennguyen/zalo-agent-cli",
-    "version": "2.5.4",
+    "version": "2.5.6",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {

package/src/commands/fleet.js

@@ -0,0 +1,439 @@
+/**
+ * `zalo-agent fleet ...` — run many accounts on one machine.
+ *
+ * One account is one daemon process with its own port, token and lock, so a hundred accounts are a hundred
+ * of them. These commands do what an operator would otherwise script by hand: keep a port table, show every
+ * daemon's health in one table, start and restart them in shuffled batches so they do not all log in at
+ * once, and write the systemd unit, env files and proxy config that supervise them. See src/core/fleet.js.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { parseAccountId } from "../core/daemon-account.js";
+import { listAccounts } from "../core/accounts.js";
+import { getAccountDir } from "../core/credentials.js";
+import { getDaemonStatus, spawnDaemonProcess, statusViaDaemon, stopDaemon } from "../core/daemon-channel.js";
+import {
+    DEFAULT_BASE_PORT,
+    FleetError,
+    assignPorts,
+    classifyAccount,
+    generateFleetFiles,
+    loadPortTable,
+    needsRestart,
+    planBatches,
+    renderStatusTable,
+} from "../core/fleet.js";
+import { envForAccount } from "../mcp/mcp-config.js";
+import { error, info, output, success, warning } from "../utils/output.js";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Run `fn` over `items`, at most `limit` at a time, keeping the order of the results. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    await Promise.all(
+        Array.from({ length: Math.min(limit, items.length) }, async () => {
+            while (next < items.length) {
+                const i = next++;
+                out[i] = await fn(items[i], i);
+            }
+        }),
+    );
+    return out;
+}
+
+/** @param {string} label @param {string} value @param {number} min @param {number} max */
+function intOption(label, value, min, max) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < min || n > max) {
+        error(`Invalid ${label} "${value}": must be a whole number from ${min} to ${max}.`);
+        process.exit(1);
+    }
+    return n;
+}
+
+/**
+ * The accounts a command acts on: the ones named, else every registered one.
+ * @param {string[]} ids
+ * @returns {Array<{ ownId: string, name: string }>}
+ */
+function pickAccounts(ids) {
+    const all = listAccounts();
+    if (!all.length) {
+        error("No accounts are registered. Log in first: zalo-agent login");
+        process.exit(1);
+    }
+    if (!ids.length) return all;
+    const chosen = [];
+    for (const raw of ids) {
+        let id;
+        try {
+            id = parseAccountId(raw);
+        } catch (e) {
+            error(e.message);
+            process.exit(1);
+        }
+        const acc = all.find((a) => a.ownId === id);
+        if (!acc) {
+            error(`Account ${id} is not registered. List them with: zalo-agent account list`);
+            process.exit(1);
+        }
+        chosen.push(acc);
+    }
+    return chosen;
+}
+
+/** The port table, with every given account in it. */
+function portsFor(accounts, basePort) {
+    try {
+        return assignPorts(
+            accounts.map((a) => a.ownId),
+            { basePort },
+        ).ports;
+    } catch (e) {
+        if (e instanceof FleetError) {
+            error(e.message);
+            process.exit(1);
+        }
+        throw e;
+    }
+}
+
+/** The ports already assigned, without assigning any (status must not write). */
+function readPorts() {
+    try {
+        return loadPortTable().ports;
+    } catch (e) {
+        if (e instanceof FleetError) {
+            error(e.message);
+            process.exit(1);
+        }
+        throw e;
+    }
+}
+
+/**
+ * What every account's daemon is doing right now, asked over each one's loopback channel (no port or token needed).
+ * @param {Array<{ ownId: string, name: string }>} accounts
+ * @param {Record<string, number>} ports
+ * @param {number} downForSec
+ */
+async function collect(accounts, ports, downForSec) {
+    return mapLimit(accounts, 16, async (acc) => {
+        const accountDir = getAccountDir(acc.ownId);
+        const daemon = getDaemonStatus(accountDir);
+        const reply = daemon.running ? await statusViaDaemon(accountDir) : null;
+        const health = reply?.ok ? reply.health : null;
+        return {
+            accountId: acc.ownId,
+            name: acc.name,
+            port: ports[acc.ownId] ?? null,
+            state: classifyAccount({ running: daemon.running, health }, { downForSec }),
+            daemon: { running: daemon.running, pid: daemon.pid },
+            health,
+        };
+    });
+}
+
+/** `<dir>/<ownId>.env` as extra environment for that account's daemon, if the file exists. */
+function envFromDir(dir, ownId) {
+    if (!dir) return {};
+    const file = join(dir, `${ownId}.env`);
+    if (!existsSync(file)) return {};
+    try {
+        return parseEnv(readFileSync(file, "utf8"));
+    } catch (e) {
+        error(`Cannot read ${file}: ${e.message}`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Start daemons in shuffled batches, a pause between batches.
+ *
+ * @param {Array<{ ownId: string, kind: "mcp"|"listen", port: number }>} targets
+ * @param {{ batch: number, staggerSec: number, envDir: string|null, dryRun: boolean, log: (m: string) => void }} o
+ * @returns {Promise<Array<{ accountId: string, ok: boolean, detail: string }>>}
+ */
+async function startInBatches(targets, { batch, staggerSec, envDir, dryRun, log }) {
+    const batches = planBatches(targets, { size: batch });
+    const results = [];
+    for (let b = 0; b < batches.length; b++) {
+        log(`batch ${b + 1}/${batches.length}: ${batches[b].map((t) => t.ownId).join(", ")}`);
+        const done = await Promise.all(
+            batches[b].map(async (t) => {
+                if (dryRun)
+                    return {
+                        accountId: t.ownId,
+                        ok: true,
+                        detail: `would start (${t.kind}${t.kind === "mcp" ? `, port ${t.port}` : ""})`,
+                    };
+                const env = envFromDir(envDir, t.ownId);
+                if (t.kind === "mcp" && !envForAccount("ZALO_MCP_AUTH_TOKEN", t.ownId, { ...process.env, ...env })) {
+                    warning(
+                        `Account ${t.ownId} has no ZALO_MCP_AUTH_TOKEN: its port will serve anyone who can reach it.`,
+                    );
+                }
+                const args =
+                    t.kind === "listen"
+                        ? [process.argv[1], "listen", "--account", t.ownId]
+                        : [process.argv[1], "mcp", "start", "--account", t.ownId, "--http", String(t.port)];
+                const spawned = await spawnDaemonProcess({ accountDir: getAccountDir(t.ownId), args, env });
+                if (spawned.ok) {
+                    return {
+                        accountId: t.ownId,
+                        ok: true,
+                        detail: `started (pid ${spawned.pid}${t.kind === "mcp" ? `, port ${t.port}` : ""})`,
+                    };
+                }
+                return {
+                    accountId: t.ownId,
+                    ok: Boolean(spawned.alreadyRunning),
+                    detail: spawned.alreadyRunning
+                        ? `already running (pid ${spawned.pid})`
+                        : `failed: ${spawned.error} (log: ${spawned.logPath})`,
+                };
+            }),
+        );
+        results.push(...done);
+        if (b < batches.length - 1 && !dryRun && staggerSec > 0) {
+            log(`waiting ${staggerSec}s before the next batch`);
+            await sleep(staggerSec * 1000);
+        }
+    }
+    return results;
+}
+
+/**
+ * @param {object} program - Commander root
+ */
+export function registerFleetCommands(program) {
+    const fleet = program
+        .command("fleet")
+        .description(
+            "Run many accounts on one machine: port table, one status table, batched start/restart, supervisor files",
+        );
+
+    const json = () => program.opts().json;
+
+    fleet
+        .command("ports")
+        .description(
+            "Show the port each account's daemon uses, assigning one to any account that has none (kept in fleet.json)",
+        )
+        .option(
+            "--base <port>",
+            `First port of a new table (default ${DEFAULT_BASE_PORT}); ignored once ports are assigned`,
+        )
+        .action((opts) => {
+            const base = opts.base === undefined ? undefined : intOption("--base", opts.base, 1, 65535);
+            const accounts = listAccounts();
+            if (!accounts.length) {
+                error("No accounts are registered. Log in first: zalo-agent login");
+                process.exit(1);
+            }
+            const ports = portsFor(accounts, base);
+            const rows = accounts.map((a) => ({ accountId: a.ownId, name: a.name, port: ports[a.ownId] }));
+            output({ ports: rows }, json(), () => {
+                for (const r of rows) info(`${r.accountId}  ${String(r.port).padEnd(5)}  ${r.name || ""}`);
+            });
+        });
+
+    fleet
+        .command("status [accounts...]")
+        .description(
+            "One table for every account: daemon, socket, last event, webhook backlog, gaps, memory, and a state",
+        )
+        .option("--check", "Exit 1 unless every account is ok or degraded (for monitoring scripts)")
+        .option(
+            "--down-for <seconds>",
+            "How long a socket may be down before the account counts as `down` (default 180)",
+            "180",
+        )
+        .action(async (ids, opts) => {
+            const downFor = intOption("--down-for", opts.downFor, 0, 86400);
+            const accounts = pickAccounts(ids);
+            const rows = await collect(accounts, readPorts(), downFor);
+            const summary = {};
+            for (const r of rows) summary[r.state] = (summary[r.state] ?? 0) + 1;
+            output({ accounts: rows, summary }, json(), () => {
+                for (const line of renderStatusTable(rows)) console.log(line);
+                console.log();
+                info(
+                    Object.entries(summary)
+                        .map(([s, n]) => `${n} ${s}`)
+                        .join(", "),
+                );
+            });
+            if (opts.check && rows.some((r) => !["ok", "degraded"].includes(r.state))) process.exit(1);
+        });
+
+    fleet
+        .command("start [accounts...]")
+        .description("Start the daemons that are not running, in shuffled batches with a pause between them")
+        .option("--listen", "Start `listen` daemons (webhook only, no HTTP port) instead of MCP servers")
+        .option("--batch <n>", "Accounts started at once (default 5)", "5")
+        .option("--stagger <seconds>", "Pause between batches (default 15)", "15")
+        .option("--env-dir <dir>", "Read <dir>/<ownId>.env into each daemon's environment (its token, port, webhook)")
+        .option("--dry-run", "Print the plan and start nothing")
+        .action(async (ids, opts) => {
+            const batch = intOption("--batch", opts.batch, 1, 100);
+            const staggerSec = intOption("--stagger", opts.stagger, 0, 3600);
+            const accounts = pickAccounts(ids);
+            const ports = portsFor(accounts);
+            const targets = accounts
+                .filter((a) => !getDaemonStatus(getAccountDir(a.ownId)).running)
+                .map((a) => ({ ownId: a.ownId, kind: opts.listen ? "listen" : "mcp", port: ports[a.ownId] }));
+            const skipped = accounts.length - targets.length;
+            const log = (m) => (json() ? console.error(`  ● ${m}`) : info(m));
+            if (skipped) log(`${skipped} account(s) already have a daemon running and are left alone`);
+            const results = await startInBatches(targets, {
+                batch,
+                staggerSec,
+                envDir: opts.envDir ?? null,
+                dryRun: Boolean(opts.dryRun),
+                log,
+            });
+            output({ started: results, alreadyRunning: skipped, dryRun: Boolean(opts.dryRun) }, json(), () => {
+                for (const r of results) (r.ok ? success : error)(`${r.accountId}: ${r.detail}`);
+                if (!results.length) info("Nothing to start.");
+            });
+            if (results.some((r) => !r.ok)) process.exit(1);
+        });
+
+    fleet
+        .command("stop [accounts...]")
+        .description(
+            "Stop the daemons of these accounts (all of them if none are named), each with its graceful shutdown",
+        )
+        .action(async (ids) => {
+            const accounts = pickAccounts(ids);
+            const results = await mapLimit(accounts, 8, async (a) => {
+                const res = await stopDaemon(getAccountDir(a.ownId));
+                return { accountId: a.ownId, stopped: res.stopped, graceful: res.graceful, pid: res.pid };
+            });
+            output({ stopped: results }, json(), () => {
+                for (const r of results) {
+                    if (r.stopped) success(`${r.accountId}: stopped (pid ${r.pid}${r.graceful ? "" : ", forced"})`);
+                    else info(`${r.accountId}: no daemon was running`);
+                }
+            });
+        });
+
+    fleet
+        .command("restart [accounts...]")
+        .description(
+            "Stop and start daemons in batches; name accounts, or use --unhealthy (down or unresponsive) or --all",
+        )
+        .option(
+            "--unhealthy",
+            "Only the accounts whose daemon is down or not answering (not a backlog: a restart does not fix a receiver)",
+        )
+        .option("--all", "Every account")
+        .option("--down-for <seconds>", "How long a socket may be down before it counts as `down` (default 180)", "180")
+        .option(
+            "--listen",
+            "Start `listen` daemons for accounts whose kind cannot be told (a daemon that does not answer)",
+        )
+        .option("--batch <n>", "Accounts restarted at once (default 5)", "5")
+        .option("--stagger <seconds>", "Pause between batches (default 15)", "15")
+        .option("--env-dir <dir>", "Read <dir>/<ownId>.env into each daemon's environment")
+        .option("--dry-run", "Print the plan and change nothing")
+        .action(async (ids, opts) => {
+            if (!ids.length && !opts.unhealthy && !opts.all) {
+                error(
+                    "Name the accounts to restart, or pass --unhealthy or --all (a bare `fleet restart` restarts nothing).",
+                );
+                process.exit(1);
+            }
+            const batch = intOption("--batch", opts.batch, 1, 100);
+            const staggerSec = intOption("--stagger", opts.stagger, 0, 3600);
+            const downFor = intOption("--down-for", opts.downFor, 0, 86400);
+            const accounts = pickAccounts(ids);
+            const ports = portsFor(accounts);
+            const rows = await collect(accounts, ports, downFor);
+            const chosen = opts.unhealthy && !ids.length ? rows.filter((r) => needsRestart(r.state)) : rows;
+            const log = (m) => (json() ? console.error(`  ● ${m}`) : info(m));
+            if (!chosen.length) {
+                output({ restarted: [], considered: rows.length }, json(), () =>
+                    info("Every account is serving: nothing to restart."),
+                );
+                return;
+            }
+            log(
+                `restarting ${chosen.length} of ${rows.length} account(s): ${chosen.map((r) => `${r.accountId} (${r.state})`).join(", ")}`,
+            );
+            if (!opts.dryRun) {
+                await mapLimit(chosen, 8, (r) => stopDaemon(getAccountDir(r.accountId)));
+            }
+            const targets = chosen.map((r) => ({
+                ownId: r.accountId,
+                kind: r.health?.kind ?? (opts.listen ? "listen" : "mcp"),
+                port: ports[r.accountId],
+            }));
+            const results = await startInBatches(targets, {
+                batch,
+                staggerSec,
+                envDir: opts.envDir ?? null,
+                dryRun: Boolean(opts.dryRun),
+                log,
+            });
+            output({ restarted: results, dryRun: Boolean(opts.dryRun) }, json(), () => {
+                for (const r of results) (r.ok ? success : error)(`${r.accountId}: ${r.detail}`);
+            });
+            if (results.some((r) => !r.ok)) process.exit(1);
+        });
+
+    fleet
+        .command("generate")
+        .description(
+            "Write the systemd unit, per-account env files (with generated tokens), the port table and, optionally, a Caddyfile",
+        )
+        .requiredOption("--out <dir>", "Directory to write into")
+        .option("--base-port <port>", `First port of a new table (default ${DEFAULT_BASE_PORT})`)
+        .option("--user <name>", "Unix user the units run as (default zalo)")
+        .option("--home <dir>", "That user's home directory (default /home/zalo)")
+        .option("--bin <path>", "Path of the zalo-agent binary (default /usr/bin/zalo-agent)")
+        .option("--domain <host>", "Also write a Caddyfile that serves every account under https://<host>/a/<ownId>/")
+        .option("--force", "Overwrite files that already exist (account env files keep their token)")
+        .option("--rotate-tokens", "Give every account a new token, replacing the ones in existing env files")
+        .action((opts) => {
+            const base = opts.basePort === undefined ? undefined : intOption("--base-port", opts.basePort, 1, 65535);
+            const accounts = listAccounts();
+            if (!accounts.length) {
+                error("No accounts are registered. Log in first: zalo-agent login");
+                process.exit(1);
+            }
+            const ports = portsFor(accounts, base);
+            const paths = Object.fromEntries(
+                Object.entries({ user: opts.user, home: opts.home, bin: opts.bin }).filter(([, v]) => v !== undefined),
+            );
+            const result = generateFleetFiles({
+                outDir: opts.out,
+                accounts: accounts.map((a) => ({ ownId: a.ownId, port: ports[a.ownId] })),
+                paths,
+                domain: opts.domain ?? null,
+                force: Boolean(opts.force),
+                rotateTokens: Boolean(opts.rotateTokens),
+            });
+            output({ outDir: opts.out, accounts: accounts.length, ...result }, json(), () => {
+                success(`${result.written.length} file(s) written to ${opts.out} for ${accounts.length} account(s)`);
+                for (const f of result.written) info(`wrote  ${f}`);
+                for (const f of result.kept)
+                    info(`kept   ${f} (already there; --force overwrites, --rotate-tokens renews tokens)`);
+                info("Tokens are in accounts/<id>.env (mode 600) and are not printed here.");
+                info(
+                    `Install: sudo install -d /etc/zalo-mcp/accounts && sudo install -m 600 ${opts.out}/common.env /etc/zalo-mcp/ && sudo install -m 600 ${opts.out}/accounts/*.env /etc/zalo-mcp/accounts/`,
+                );
+                info(
+                    `Then:    sudo install -m 644 ${opts.out}/zalo-mcp@.service /etc/systemd/system/ && sudo systemctl daemon-reload`,
+                );
+                info(
+                    "Start:   systemctl enable --now zalo-mcp@<ownId>   (or: zalo-agent fleet start --env-dir /etc/zalo-mcp/accounts)",
+                );
+            });
+        });
+}