@ardennguyen/zalo-agent-cli 2.5.1 → 2.5.4

package/src/core/friend-requests.js

@@ -0,0 +1,142 @@
+/**
+ * Friend requests, as the CLI's `friend` commands and the MCP tool `zalo_friend`
+ * both read them.
+ *
+ * Zalo has no "incoming requests" list of its own. Zalo Web shows them inside
+ * the recommendations feed: an item whose `recommType` is 2
+ * (`FriendRecommendationsType.ReceivedFriendRequest`) is a request someone
+ * sent us, with their message in `recommInfo.message`; type 1 is an ordinary
+ * suggestion. `friend recommendations` already labels them `[request]`.
+ *
+ * Nothing here talks to Zalo or writes zalo.db: these are pure reshapers of
+ * what the zca-js calls return, plus the error wording for the writes.
+ */
+
+/** zca-js FriendRecommendationsType.ReceivedFriendRequest. */
+export const RECEIVED_FRIEND_REQUEST = 2;
+
+/**
+ * The numeric error code in a zca-js error message such as "... (225)".
+ *
+ * @param {unknown} msg
+ * @returns {number|null}
+ */
+export function extractErrorCode(msg) {
+    const match = String(msg).match(/\((-?\d+)\)/);
+    return match ? Number(match[1]) : null;
+}
+
+/**
+ * What a failed friend request means, in words that say what to do next.
+ *
+ * @param {number|string|null|undefined} code - Zalo's error code
+ * @param {string} userId
+ * @returns {string|undefined} undefined for a code with no specific wording
+ */
+export function describeFriendAddError(code, userId) {
+    const map = {
+        225: `Already friends with ${userId}. Use "friend list" to verify.`,
+        215: `User ${userId} may have blocked you or is unreachable.`,
+        222: `User ${userId} already sent you a friend request. Use "friend accept ${userId}" instead.`,
+        "-1": `Invalid userId "${userId}". Use "friend find <phone>" to get the correct userId first.`,
+        // Names from Zalo Web's own error table (TOO_MANY_REQUESTS, FULL_FRIEND_REQUESTING, FULL_FRIEND).
+        221: "Zalo says too many requests were sent: wait a while before sending more.",
+        223: "Zalo says the pending friend-request list is full (223).",
+        224: "Zalo says the friend list is full (224).",
+    };
+    return map[String(code)];
+}
+
+/**
+ * An epoch timestamp as ISO text, whether Zalo gave seconds or milliseconds.
+ *
+ * Which unit a friend-request time carries has not been measured on a live
+ * account; anything below 1e11 cannot be a millisecond time of this century,
+ * so it is read as seconds.
+ *
+ * @param {unknown} ts
+ * @returns {string|null} null when it is not a usable time
+ */
+export function toIso(ts) {
+    const n = Number(ts);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return new Date(n < 1e11 ? n * 1000 : n).toISOString();
+}
+
+const name = (u) => u?.displayName || u?.zaloName || null;
+
+/**
+ * Requests we sent, from `getSentFriendRequest()` (an object keyed by userId).
+ *
+ * @param {Record<string, object>|null|undefined} res
+ * @returns {Array<{userId: string, displayName: string|null, message: string, requestedAt: string|null}>}
+ */
+export function sentRequestsFrom(res) {
+    return Object.entries(res && typeof res === "object" ? res : {}).map(([userId, r]) => ({
+        userId: String(r?.userId ?? userId),
+        displayName: name(r),
+        message: r?.fReqInfo?.message ?? "",
+        requestedAt: toIso(r?.fReqInfo?.time),
+    }));
+}
+
+/**
+ * Requests sent to us, from `getFriendRecommendations()`: the items of type
+ * "received friend request", newest first. Suggestions are left out.
+ *
+ * @param {{recommItems?: Array<{dataInfo?: object}>}|null|undefined} res
+ * @returns {Array<{userId: string, displayName: string|null, message: string, receivedAt: string|null, seen: boolean}>}
+ */
+export function receivedRequestsFrom(res) {
+    const items = Array.isArray(res?.recommItems) ? res.recommItems : [];
+    return items
+        .map((i) => i?.dataInfo)
+        .filter((d) => d && Number(d.recommType) === RECEIVED_FRIEND_REQUEST && d.userId)
+        .map((d) => ({
+            userId: String(d.userId),
+            displayName: name(d),
+            message: d.recommInfo?.message ?? "",
+            receivedAt: toIso(d.recommTime),
+            seen: Boolean(d.isSeenFriendReq),
+            _t: Number(d.recommTime) || 0,
+        }))
+        .sort((a, b) => b._t - a._t)
+        .map(({ _t, ...rest }) => rest);
+}
+
+/**
+ * The relationship with one user, from `getFriendRequestStatus()`.
+ * Zalo answers 0 or 1 for each flag; these are booleans.
+ *
+ * @param {{is_friend?: number, is_requested?: number, is_requesting?: number}|null|undefined} res
+ * @param {string} userId
+ * @returns {{userId: string, is_friend: boolean, is_requested: boolean, is_requesting: boolean}}
+ */
+export function friendStatusFrom(res, userId) {
+    return {
+        userId: String(userId),
+        is_friend: Boolean(res?.is_friend),
+        is_requested: Boolean(res?.is_requested),
+        is_requesting: Boolean(res?.is_requesting),
+    };
+}
+
+/**
+ * Friends, most recently active first, as the CLI lists them, capped.
+ *
+ * @param {Array<object>|null|undefined} list - `getAllFriends()`
+ * @param {number} limit
+ * @returns {{total: number, friends: Array<{userId: string, displayName: string|null, lastActionTime: number|null}>}}
+ */
+export function friendsFrom(list, limit) {
+    const all = Array.isArray(list) ? list : [];
+    const sorted = [...all].sort((a, b) => (b?.lastActionTime || 0) - (a?.lastActionTime || 0));
+    return {
+        total: all.length,
+        friends: sorted.slice(0, limit).map((f) => ({
+            userId: String(f.userId),
+            displayName: name(f),
+            lastActionTime: f.lastActionTime || null,
+        })),
+    };
+}

package/src/core/friend-search.js

@@ -0,0 +1,41 @@
+/**
+ * Friend search, as `friend search` reads it.
+ *
+ * A friend can be known by three names: the profile name Zalo shows
+ * (`displayName`), the name they gave themselves (`zaloName`), and the alias
+ * the account owner set for them. The alias lives in a separate list
+ * (`getAliasList`), so `getAllFriends` alone never contains it, and a search
+ * on the first two names cannot find a friend the owner saved as "Arden AI".
+ * `zalo_search_threads` already honors aliases through the thread-name cache;
+ * this gives the CLI the same reach.
+ *
+ * Pure: nothing here talks to Zalo.
+ */
+
+/**
+ * The friends whose display name, Zalo name or alias contains `query`
+ * (case-insensitive substring, as before).
+ *
+ * Each match is a copy of the friend with an `alias` field added when the
+ * owner has set one, so callers can show why it matched.
+ *
+ * @param {object[]} friends - `getAllFriends` entries
+ * @param {Map<string, string>} aliases - uid → the owner's alias for that friend
+ * @param {string} query
+ * @returns {object[]}
+ */
+export function searchFriends(friends, aliases, query) {
+    const q = String(query).toLowerCase();
+    const hit = (s) =>
+        String(s || "")
+            .toLowerCase()
+            .includes(q);
+    const matches = [];
+    for (const f of Array.isArray(friends) ? friends : []) {
+        const alias = aliases?.get(String(f.userId)) ?? "";
+        if (hit(f.displayName) || hit(f.zaloName) || hit(alias)) {
+            matches.push(alias ? { ...f, alias } : f);
+        }
+    }
+    return matches;
+}

package/src/core/group-admin.js

@@ -0,0 +1,116 @@
+/**
+ * Group administration, as the MCP tool `zalo_group` reads Zalo's answers.
+ *
+ * Pure reshapers: nothing here talks to Zalo or writes zalo.db. Members are
+ * listed by `src/core/group-members.js`; this file covers what that one does
+ * not: a group's own details, and the outcome of creating a group or changing
+ * its membership.
+ */
+import { toIso } from "./friend-requests.js";
+
+/**
+ * Zalo's error codes for leaving a group the account is not in. 167 ("Không thể rời nhóm") was measured on a live
+ * account by leaving a group a second time; 166 is the code zca-js documents on `leaveGroup` for the same situation
+ * and has not been seen.
+ */
+export const NOT_A_MEMBER_CODES = Object.freeze([166, 167]);
+
+/** Zalo's code ("Nhóm không có thành viên.") for removing someone who is not in the group, measured live. */
+export const REMOVE_NOT_IN_GROUP = 165;
+
+/** `zalo_group` actions that cannot be undone from the tool, and so ask for `confirm: true`. */
+export const CONFIRMED_ACTIONS = Object.freeze(["leave", "remove_member"]);
+
+/**
+ * Whether `zalo_group` asks for `confirm: true` before an irreversible action.
+ *
+ * The check is a parameter, never a prompt: an automatic or headless caller
+ * either sends `confirm: true` or switches the check off, and nothing waits for
+ * a person. `ZALO_MCP_GROUP_CONFIRM` (`0`/`false`/`off`/`no` to disable,
+ * `1`/`true`/`on`/`yes` to enable) wins over `groupConfirm` in mcp-config.json,
+ * so a backend deployment can turn it off without editing the file. On by
+ * default; anything unrecognized leaves it on.
+ *
+ * @param {object} [sources]
+ * @param {{groupConfirm?: unknown}|null} [sources.config] - the loaded MCP config
+ * @param {NodeJS.ProcessEnv} [sources.env] - environment, process.env by default
+ * @returns {boolean}
+ */
+export function groupConfirmRequired({ config, env = process.env } = {}) {
+    const fromEnv = String(env?.ZALO_MCP_GROUP_CONFIRM ?? "")
+        .trim()
+        .toLowerCase();
+    if (["0", "false", "off", "no"].includes(fromEnv)) return false;
+    if (["1", "true", "on", "yes"].includes(fromEnv)) return true;
+    return config?.groupConfirm !== false;
+}
+
+/**
+ * The details of one group out of `getGroupInfo`'s answer.
+ *
+ * Zalo answers `getGroupInfo([id])` with `gridInfoMap` keyed by group id; a
+ * group the account is not in is simply absent. The member list is left out
+ * on purpose (`zalo_get_group_members` owns it, with names); only its size is
+ * reported.
+ *
+ * @param {object|null|undefined} result - what `api.getGroupInfo([groupId])` returned
+ * @param {string} groupId
+ * @returns {object|null} null when Zalo's answer does not include the group
+ */
+export function groupInfoFrom(result, groupId) {
+    const g = result?.gridInfoMap?.[groupId];
+    if (!g) return null;
+    return {
+        groupId: String(g.groupId ?? groupId),
+        name: g.name ?? null,
+        description: g.desc || null,
+        type: g.type ?? null,
+        creatorId: g.creatorId ?? null,
+        adminIds: Array.isArray(g.adminIds) ? g.adminIds.map(String) : [],
+        totalMember: g.totalMember ?? null,
+        maxMember: g.maxMember ?? null,
+        createdAt: toIso(g.createdTime),
+        avatar: g.fullAvt || g.avt || null,
+        visibility: g.visibility ?? null,
+        pendingApproval: Array.isArray(g.pendingApprove?.uids) ? g.pendingApprove.uids.length : 0,
+        settings: g.setting ?? null,
+    };
+}
+
+/**
+ * The outcome of `createGroup`.
+ *
+ * zca-js spells the success list `sucessMembers`; both spellings are read so a
+ * fixed typo upstream does not empty it. Zalo's list includes the account that
+ * created the group (measured live: asking for one member returns two ids), so
+ * `added` keeps only the members that were asked for.
+ *
+ * @param {object|null|undefined} result
+ * @param {string[]} requested - the member ids that were asked for
+ * @returns {{groupId: string|null, added: string[], failed: string[]}}
+ */
+export function createdGroupFrom(result, requested) {
+    const failed = (result?.errorMembers ?? []).map(String);
+    const given = result?.sucessMembers ?? result?.successMembers;
+    const added = Array.isArray(given)
+        ? given.map(String).filter((id) => requested.includes(id))
+        : requested.filter((id) => !failed.includes(id));
+    return { groupId: result?.groupId ? String(result.groupId) : null, added, failed };
+}
+
+/**
+ * The outcome of `addUserToGroup` / `removeUserFromGroup`: which of the
+ * requested members Zalo refused, and why.
+ *
+ * `error_data` (add only) maps an error code to the ids it applies to.
+ *
+ * @param {object|null|undefined} result
+ * @param {string[]} requested - the member ids that were asked for
+ * @returns {{done: string[], failed: string[], errorData: Record<string, string[]>|null}}
+ */
+export function memberChangeFrom(result, requested) {
+    const failed = (result?.errorMembers ?? []).map(String);
+    const data = result?.error_data;
+    const errorData = data && typeof data === "object" && Object.keys(data).length > 0 ? data : null;
+    return { done: requested.filter((id) => !failed.includes(id)), failed, errorData };
+}

package/src/core/group-invite.js

@@ -0,0 +1,53 @@
+/**
+ * A pending group invitation's details (`group invite-info`).
+ *
+ * zca-js's `getGroupInviteBoxInfo` reads `data.groupInfo.topic.params` without
+ * checking that the group has a topic. Most groups have no pinned message, so
+ * for them Zalo's answer carries no `topic` and zca-js throws "Cannot read
+ * properties of undefined (reading 'params')" after Zalo had answered fine.
+ * This makes the same request (GET {group}/api/group/inv-box/inv-info) on
+ * zca-js's own session envelope, and unpacks the topic's JSON-in-JSON params
+ * only when there is a topic.
+ */
+import { customCall, getWithParams } from "./zca-custom.js";
+
+/**
+ * Parse a topic's `params`, which Zalo sends as a JSON string whose `extra`
+ * field is itself a JSON string. Anything that does not parse is left as it came.
+ *
+ * @param {object} topic
+ * @returns {object} the same topic, with `params` unpacked when it could be
+ */
+export function unpackTopic(topic) {
+    if (!topic || typeof topic.params !== "string") return topic;
+    try {
+        const params = JSON.parse(topic.params);
+        if (typeof params?.extra === "string") {
+            try {
+                params.extra = JSON.parse(params.extra);
+            } catch {
+                /* keep the string */
+            }
+        }
+        return { ...topic, params };
+    } catch {
+        return topic;
+    }
+}
+
+/**
+ * @param {object} api - logged-in zca-js api
+ * @param {{groupId: string, mpage?: number, mcount?: number}} payload
+ * @returns {Promise<object>} Zalo's `data`: groupInfo, inviterInfo, grCreatorInfo, expiredTs, type
+ */
+export async function getInviteBoxInfo(api, { groupId, mpage = 1, mcount = 10 }) {
+    return customCall(api, async (_ctx, utils) => {
+        const data = await getWithParams(utils, `${api.zpwServiceMap.group[0]}/api/group/inv-box/inv-info`, {
+            grId: groupId,
+            mcount,
+            mpage,
+        });
+        if (data?.groupInfo?.topic) data.groupInfo.topic = unpackTopic(data.groupInfo.topic);
+        return data;
+    });
+}

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

@@ -19,6 +19,7 @@
  */
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { runPacedBatches } from "../user-info.js";
 
 const require = createRequire(import.meta.url);
 
@@ -68,15 +69,13 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
         return out;
     }
     const idToUser = new Map();
-    for (let i = 0; i < globalIds.length; i += GID_BATCH) {
-        const batch = globalIds.slice(i, i + GID_BATCH);
-        let map;
-        try {
-            map = await gidDecrypt(batch);
-        } catch (e) {
-            log(`gid/decrypt batch failed (${e.message})`);
-            continue;
-        }
+    const decrypted = await runPacedBatches(globalIds, {
+        batchSize: GID_BATCH,
+        label: "gid/decrypt",
+        log,
+        call: (batch) => gidDecrypt(batch),
+    });
+    for (const map of decrypted.results) {
         for (const [gid, uid] of Object.entries(map || {})) if (uid) idToUser.set(gid, String(uid));
     }
     if (!idToUser.size) return out;
@@ -85,20 +84,21 @@ export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
     const names = new Map();
     const zaloNames = new Map();
     const uids = [...new Set([...idToUser.values()])];
-    for (let i = 0; i < uids.length; i += NAME_BATCH) {
-        const batch = uids.slice(i, i + NAME_BATCH);
-        try {
-            const info = await api.getUserInfo(batch);
-            for (const bag of [info?.changed_profiles, info?.unchanged_profiles]) {
-                for (const [uid, p] of Object.entries(bag || {})) {
-                    if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
-                    if (p?.zaloName) zaloNames.set(uid, p.zaloName);
-                }
+    const named = await runPacedBatches(uids, {
+        batchSize: NAME_BATCH,
+        label: "getUserInfo",
+        log,
+        call: (batch) => api.getUserInfo(batch),
+    });
+    for (const info of named.results) {
+        for (const bag of [info?.changed_profiles, info?.unchanged_profiles]) {
+            for (const [uid, p] of Object.entries(bag || {})) {
+                if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
+                if (p?.zaloName) zaloNames.set(uid, p.zaloName);
             }
-        } catch (e) {
-            log(`getUserInfo batch failed (${e.message}); some names may be blank`);
         }
     }
+    if (named.failed || named.skippedIds) log("some names may be blank (getUserInfo did not answer for every batch)");
 
     for (const [gid, uid] of idToUser)
         out.set(gid, { id: uid, name: names.get(uid) || "", zaloName: zaloNames.get(uid) || "" });

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

@@ -82,6 +82,18 @@ const DEFAULT_WAVE_SIZE = 4;
  * dying.
  */
 const MAX_RESUMES = 1;
+/** The most reconnects a caller may ask a single restore to attempt. */
+const MAX_RESUMES_CAP = 5;
+
+/**
+ * How many reconnects a restore may spend: the caller's `maxResumes` (a whole number, capped), else one.
+ *
+ * @param {unknown} requested
+ * @returns {number}
+ */
+export function resolveMaxResumes(requested) {
+    return Number.isInteger(requested) ? Math.min(MAX_RESUMES_CAP, Math.max(0, requested)) : MAX_RESUMES;
+}
 const DAY_MS = 24 * 60 * 60 * 1000;
 
 /**
@@ -277,6 +289,21 @@ export function resolveWaitBudget(budgetMs, fallbackMs) {
     return 30000;
 }
 
+/**
+ * The api a `reconnect` callback handed back, if it handed one.
+ *
+ * `true` means "the same listener is live again" (the CLI re-opens the socket on
+ * the api it already has). `{api}` means the caller recovered by building a new
+ * api, as a daemon does after logging in again, and the restore has to carry on
+ * over that api's listener instead.
+ *
+ * @param {unknown} back - what `opts.reconnect()` resolved
+ * @returns {object|null} the new api, or null when the old one is still the one
+ */
+export function reconnectedApi(back) {
+    return back && typeof back === "object" && back.api?.listener ? back.api : null;
+}
+
 /**
  * Which shards still have to go out, and whether a dropped socket is worth one
  * more reconnect.
@@ -481,17 +508,43 @@ export class SyncV2 {
         }
     }
 
-    /** Refresh existing DM peers outside the requested message window, including non-friends. */
-    async _refreshDmNames(threadMap) {
+    /**
+     * Refresh existing DM peers outside the requested message window, including non-friends.
+     *
+     * Every restore used to look up every non-friend DM peer in the cache: on a busy account that
+     * is thousands of ids, each restore, and Zalo answered with a limit. So the run asks for at most
+     * `maxLookups` of them (500 unless ZALO_SYNC_NAME_REFRESH_MAX says otherwise), peers whose
+     * cached title is missing or just their id first, because those are the ones a restore can
+     * actually improve. The rest keep the titles they have until a later restore reaches them.
+     *
+     * @param {Map<string, object>} threadMap
+     * @param {(message: string) => void} [log]
+     */
+    async _refreshDmNames(threadMap, log = () => {}) {
         const profiles = new Map(
             [...threadMap.values()]
                 .filter((t) => t.type === "dm" && t.zaloName)
                 .map((t) => [t.id, { zaloName: t.zaloName }]),
         );
+        const peers = getRecentThreads(-1, "dm");
+        const unknown = (t) => !t.name || String(t.name) === String(t.threadId);
+        const wanted = peers.filter((t) => !profiles.has(String(t.threadId)));
+        wanted.sort((a, b) => Number(unknown(b)) - Number(unknown(a)));
+        const envCap = Number.parseInt(process.env.ZALO_SYNC_NAME_REFRESH_MAX ?? "", 10);
+        const maxLookups = Number.isFinite(envCap) && envCap >= 0 ? envCap : 500;
+        const chosen = wanted.slice(0, maxLookups);
+        if (wanted.length) {
+            log(
+                `refreshing ${chosen.length} of ${wanted.length} non-friend DM peer name(s)` +
+                    (chosen.length < wanted.length
+                        ? ` (cap ${maxLookups}; the rest keep their cached titles until a later restore)`
+                        : ""),
+            );
+        }
         const names = await resolveCurrentUserNames(
             this.api,
-            getRecentThreads(-1, "dm").map((t) => String(t.threadId)),
-            { aliases: this.userAliases, profiles },
+            [...profiles.keys(), ...chosen.map((t) => String(t.threadId))],
+            { aliases: this.userAliases, profiles, log },
         );
         for (const [id, current] of names) {
             upsertThread({ threadId: id, type: "dm", name: current.name, lastUpdate: 0 });
@@ -561,9 +614,13 @@ export class SyncV2 {
      * @param {boolean} [opts.liveStore=true] false when the caller already taps live traffic
      * @param {number|false} [opts.keepAlive] heartbeat interval in ms, or false when the
      *   caller already pings this socket for the whole window it owns.
-     * @param {() => Promise<boolean>} [opts.reconnect] re-open the listener socket after a
-     *   drop and resolve true once it is live. Supplied by the caller because this class
+     * @param {number} [opts.maxResumes] reconnects this run may spend (default 1, at most 5); each one
+     *   that needs the phone's confirmation again costs the owner a tap.
+     * @param {() => Promise<boolean|{api: object}>} [opts.reconnect] re-open the listener socket
+     *   after a drop and resolve true once it is live. Supplied by the caller because this class
      *   never starts or stops the listener itself. Without it a dropped socket ends the run.
+     *   A caller that cannot reuse the old listener (a daemon, which re-logs-in and builds a new
+     *   api) resolves `{api}` instead: the restore carries on over that api's listener.
      * @returns {Promise<{conversations:number, messagesSaved:number, threadsMapped:number, threadsUnmapped:number, reason:string, days:number|null, from:number, confirmed:boolean, resumes:number, rePrompted:boolean}>}
      */
     async restore(opts = {}) {
@@ -586,10 +643,12 @@ export class SyncV2 {
 
         initDb(resolve(this.accountDir, "zalo.db"));
         this._refreshThreadNames(threadMap);
-        await this._refreshDmNames(threadMap);
+        await this._refreshDmNames(threadMap, log);
         await this._refreshSelfName(opts.onSelfName);
 
-        const L = this.api.listener;
+        // `let`: a daemon recovers a lost socket by logging in again, which builds a new api and a new
+        // listener, and `opts.reconnect` can hand that api back (see `reconnect` below).
+        let L = this.api.listener;
         const sessions = new Map(); // syncId -> {kind, batches:[], statuses:[], done, err}
         const onMsg = async (buf) => {
             if (!(buf instanceof Buffer) || buf.length < 4 || buf.readUInt16LE(1) !== 601) return;
@@ -734,7 +793,14 @@ export class SyncV2 {
             detachSocketTaps();
             let ok = false;
             try {
-                ok = Boolean(await opts.reconnect());
+                const back = await opts.reconnect();
+                ok = Boolean(back);
+                // A new api means a new listener: the old one's socket is gone for good.
+                const next = ok ? reconnectedApi(back) : null;
+                if (next) {
+                    this.api = next;
+                    L = next.listener;
+                }
             } catch (e) {
                 onStatus({ phase: "warn", detail: `reconnect failed: ${e?.message || e}` });
                 return false;
@@ -1072,7 +1138,7 @@ export class SyncV2 {
             // to reconnect -- this class never starts the listener itself.
             const schedule = createShardSchedule(shards.length, {
                 waveSize,
-                maxResumes: typeof opts.reconnect === "function" ? MAX_RESUMES : 0,
+                maxResumes: typeof opts.reconnect === "function" ? resolveMaxResumes(opts.maxResumes) : 0,
             });
 
             // ---- wave by wave: send, wait, decrypt, decode, store ----
@@ -1228,7 +1294,7 @@ export class SyncV2 {
                     runDeadline = Date.now() + shardBudget(schedule.remaining());
                     onStatus({
                         phase: "reconnect",
-                        detail: `reconnected — re-requesting the ${schedule.remaining()} batch(es) that never arrived (attempt ${schedule.resumes()} of ${MAX_RESUMES})`,
+                        detail: `reconnected — re-requesting the ${schedule.remaining()} batch(es) that never arrived (attempt ${schedule.resumes()} of ${resolveMaxResumes(opts.maxResumes)})`,
                     });
                     continue;
                 }