@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/account-state.js

@@ -0,0 +1,167 @@
+/**
+ * `account_state`: one word for where an account stands, said once per change, the same from every place that shows
+ * it (the webhook, the MCP buffer, `/status`, `fleet status`, the fleet controller's SSE).
+ *
+ *   stopped        no process for the account (the controller says this one: a daemon cannot)
+ *   idle           the daemon runs and its socket is parked (on-demand presence): it wakes on demand
+ *   connecting     a socket is being opened (a start, a wake, a drop being retried)
+ *   connected      the socket is up
+ *   kicked         another session took the account (said just before exit 3)
+ *   yielded        on-demand: another session of the same login took the socket; the daemon stays up and refuses
+ *                  every request (YIELDED) until the user confirms `presence resume`
+ *   login_needed   Zalo refused the session (while the daemon logs in again)
+ *   signed_out     Zalo keeps refusing the saved login (another browser took the web login): the daemon stays up and
+ *                  refuses every request (SIGNED_OUT) until the account is added again by QR
+ *   maintenance    Zalo is in maintenance; the daemon waits for it
+ *
+ * Events carry ids only, never a name: `{event: "account_state", accountId, state, previous, at, detail}`.
+ */
+
+/** Every account state. */
+export const ACCOUNT_STATES = Object.freeze([
+    "stopped",
+    "idle",
+    "connecting",
+    "connected",
+    "kicked",
+    "yielded",
+    "login_needed",
+    "signed_out",
+    "maintenance",
+]);
+
+/** A supervisor state (src/zalo/socket.js) as an account state, or null when it says nothing new. */
+const FROM_SUPERVISOR = Object.freeze({
+    connecting: "connecting",
+    retrying: "connecting",
+    offline: "connecting",
+    connected: "connected",
+    kicked: "kicked",
+    "session-invalid": "login_needed",
+    maintenance: "maintenance",
+});
+
+/** A daemon's health socket state (src/core/daemon-health.js) as an account state. */
+const FROM_HEALTH = Object.freeze({
+    starting: "connecting",
+    connecting: "connecting",
+    down: "connecting",
+    up: "connected",
+    idle: "idle",
+    kicked: "kicked",
+    relogin: "login_needed",
+    yielded: "yielded",
+    "signed-out": "signed_out",
+    maintenance: "maintenance",
+    stopping: "stopped",
+});
+
+/**
+ * The account state a daemon's health snapshot says (for the fleet controller and `fleet status`).
+ *
+ * @param {{socket?: {state?: string}}|null} health - null when no daemon answered
+ * @param {{running?: boolean}} [o]
+ * @returns {string}
+ */
+export function accountStateOfHealth(health, { running = true } = {}) {
+    if (!running) return "stopped";
+    return FROM_HEALTH[health?.socket?.state] ?? "connecting";
+}
+
+/**
+ * One daemon's tracker: feed it what happens, it says each change once.
+ *
+ * @param {object} args
+ * @param {string} args.accountId
+ * @param {(event: object) => void} args.emit - the webhook, the MCP buffer, the log
+ * @param {() => number} [args.now]
+ * @param {() => object} [args.detail] - extra detail every event carries (e.g. `{presence: "on-demand"}`)
+ * @returns {{noteSocketState: (s: string) => void, note: (state: string, detail?: object) => boolean,
+ *   current: () => {state: string|null, since: string|null}}}
+ */
+export function createAccountStateTracker({ accountId, emit, now = Date.now, detail = () => ({}) }) {
+    let state = null;
+    let since = null;
+    const note = (next, extra = {}) => {
+        if (!ACCOUNT_STATES.includes(next) || next === state) return false;
+        const previous = state;
+        state = next;
+        since = now();
+        const event = {
+            event: "account_state",
+            accountId: String(accountId),
+            state: next,
+            previous,
+            at: new Date(since).toISOString(),
+            detail: { ...detail(), ...extra },
+        };
+        try {
+            emit(event);
+        } catch {
+            /* a failing receiver never takes the daemon down */
+        }
+        return true;
+    };
+    return {
+        /** A supervisor state; `stopped` (a park or a shutdown) says nothing here. */
+        noteSocketState(s) {
+            const mapped = FROM_SUPERVISOR[s];
+            if (mapped) note(mapped);
+        },
+        note,
+        current: () => ({ state, since: since === null ? null : new Date(since).toISOString() }),
+    };
+}
+
+/**
+ * Which `account_state` events go into the MCP buffer that `zalo_wait_for_message` and `mcp wait` read. A park, and
+ * the wake that ends it, are on-demand presence doing its job: they still reach the webhook, the log and `/status`,
+ * but in the buffer every wait on a parked account was answered by the `connecting -> connected` of the wake it caused
+ * itself, before the catch-up had delivered a single message. A drop, a kick, a yield, a sign-out, and a wake that
+ * fails (`login_needed`) still go in.
+ *
+ * @returns {(event: {state: string}) => boolean} true: push this one
+ */
+export function createBufferStateFilter() {
+    let waking = false; // since a park, until the wake reaches connected or fails
+    return (event) => {
+        const routine =
+            event.state === "idle" || (waking && (event.state === "connecting" || event.state === "connected"));
+        if (event.state === "idle") waking = true;
+        else if (event.state !== "connecting") waking = false;
+        return !routine;
+    };
+}
+
+/**
+ * One `account_state` event as the MCP buffer carries it (a system event, as `storage_quota`).
+ *
+ * @param {object} e
+ * @returns {object}
+ */
+export function accountStateSystemEvent(e) {
+    const rest = { ...e };
+    delete rest.event;
+    return { type: "account_state", ...rest, text: describeAccountState(e) };
+}
+
+/**
+ * One line for a person.
+ *
+ * @param {{accountId: string, state: string, previous?: string|null, detail?: object}} e
+ * @returns {string}
+ */
+export function describeAccountState(e) {
+    const why = e.detail?.exitCode ? ` (exit ${e.detail.exitCode})` : e.detail?.reason ? ` (${e.detail.reason})` : "";
+    const advice = ACCOUNT_STATE_ADVICE[e.state] ? `. ${ACCOUNT_STATE_ADVICE[e.state]}` : "";
+    return `account ${e.accountId}: ${e.previous ?? "start"} -> ${e.state}${why}${advice}`;
+}
+
+/** What a person does about the two states nothing recovers from on its own. */
+export const ACCOUNT_STATE_ADVICE = Object.freeze({
+    yielded:
+        "Another session of this login holds the account; close it, then confirm with `zalo-agent presence resume " +
+        "--yes` (or the admin API / MCP). Requests are refused until then",
+    signed_out:
+        "Another browser or device took the web login; add the account again by QR. Requests are refused until then",
+});

package/src/core/account-status.js

@@ -0,0 +1,355 @@
+/**
+ * The account's plans in one read-only report: which zBusiness package it holds, which zCloud plan, how much of the
+ * quota is used, what each plan allows, and what this machine's zCloud index holds.
+ *
+ * Every field comes from a call Zalo's own clients make, none of it from a guess:
+ *
+ *  - `me-v2` (`fetchAccountInfo`): `bizPkg` (the zBusiness package: id, names, expiry) and `isEnterpriseAccount`.
+ *  - the login settings already in memory: `features.ba_config.ba_pkg_config`, the server's table of limits per package
+ *    (`<feature>.config.<limit>.{<package id>: value}`, `<feature>.enable.{<package id>: 0|1}`). It is read, never copied
+ *    here: the numbers belong to the server and change.
+ *  - zCloud `v2/usage` and `cloud-settings` (every account answers them) and, on a paid plan only, `cloudinfopcweb`
+ *    (the subscription: gateway, status, size, dates).
+ *
+ * The plan numbers are the client's own (`usage.plan`): -1 free, 0 paid, 100 grace period (30 days after expiry, the
+ * data is deleted when it ends), 69 free after the grace period. A number the client does not know counts as paid
+ * there, and is reported as `unknown` here with the number.
+ *
+ * What it never prints: the cloud viewer key and its cipher key, the key-backup details (only the provider names), the
+ * transaction and product ids of the subscription, the price. Read-only: no write, no socket, no state.
+ */
+import { getCloudSettings, getCloudSubscription, getCloudUsage, summarizeCloudQuota } from "../zalo/zcloud.js";
+import { describeStorage } from "./storage-quota.js";
+
+const DAY_MS = 86_400_000;
+const GIB = 1024 ** 3;
+
+/** The zCloud plan states: usage.plan -> state. */
+const STATE = { [-1]: "free", 0: "paid", 69: "after-grace", 100: "grace" };
+
+/** The billing gateways seen: only Zalo's own is known by number. */
+const GATEWAY = { 3: "Zalo" };
+
+/**
+ * What a zCloud plan number means.
+ *
+ * @param {number|null} planCode - `usage.plan`
+ * @returns {"free"|"paid"|"grace"|"after-grace"|"unknown"}
+ */
+export function zcloudState(planCode) {
+    if (planCode === null || planCode === undefined) return "unknown";
+    return STATE[planCode] ?? "unknown";
+}
+
+/**
+ * The tier name of a paid zCloud plan, from its size. The sizes and names are Zalo's
+ * (Mini 10 GB, Standard 100 GB, Family 500 GB, Advanced 1 TB); the pairing of an account's size with a name is ours.
+ *
+ * @param {number|null} totalBytes
+ * @returns {string|null}
+ */
+export function zcloudTierName(totalBytes) {
+    if (!Number.isFinite(totalBytes)) return null;
+    const gib = Math.round(totalBytes / GIB);
+    return { 10: "zCloud Mini", 100: "zCloud Standard", 500: "zCloud Family", 1024: "zCloud Advanced" }[gib] ?? null;
+}
+
+/**
+ * Whole days from `now` to a time in epoch milliseconds; negative once it has passed. Null for no time.
+ *
+ * @param {number|null|undefined} ms
+ * @param {number} now
+ * @returns {number|null}
+ */
+export function daysUntil(ms, now) {
+    const t = Number(ms);
+    return Number.isFinite(t) && t > 0 ? Math.floor((t - now) / DAY_MS) : null;
+}
+
+const isoOrNull = (ms) => {
+    const t = Number(ms);
+    return Number.isFinite(t) && t > 0 ? new Date(t).toISOString() : null;
+};
+
+/**
+ * The limits of one zBusiness package, read from the server's table.
+ *
+ * @param {object|undefined} table - `features.ba_config.ba_pkg_config`
+ * @param {number} pkgId
+ * @returns {Record<string, Record<string, unknown>>} feature -> `{enabled, <limit>: value, ...}`
+ */
+export function resolveBizLimits(table, pkgId) {
+    const out = {};
+    if (!table || typeof table !== "object") return out;
+    const at = (byPkg) => (byPkg && typeof byPkg === "object" ? byPkg[String(pkgId)] : undefined);
+    for (const [feature, def] of Object.entries(table)) {
+        if (!def || typeof def !== "object") continue;
+        const row = {};
+        const enabled = at(def.enable);
+        if (enabled !== undefined) row.enabled = Boolean(Number(enabled));
+        for (const [limit, byPkg] of Object.entries(def.config ?? {})) {
+            const v = at(byPkg);
+            if (v !== undefined) row[limit] = v;
+        }
+        if (Object.keys(row).length) out[feature] = row;
+    }
+    return out;
+}
+
+/**
+ * The subscription, reduced: no transaction ids, no product ids, no price.
+ *
+ * @param {object|null|undefined} reply - `cloudinfopcweb` answer
+ * @param {number} now
+ * @returns {object|null}
+ */
+export function summarizeSubscription(reply, now) {
+    const s = reply?.subscription_info;
+    if (!s || typeof s !== "object") return null;
+    const total = Number.isFinite(Number(s.total_cloud)) ? Number(s.total_cloud) : null;
+    const gw = Number.isFinite(Number(s.subscription_gw)) ? Number(s.subscription_gw) : null;
+    return {
+        tier: zcloudTierName(total),
+        tierInferred: true,
+        totalBytes: total,
+        durationMonths: Number.isFinite(Number(s.duration_months)) ? Number(s.duration_months) : null,
+        gateway: gw === null ? null : (GATEWAY[gw] ?? `unknown(${gw})`),
+        status: Number.isFinite(Number(s.status)) ? Number(s.status) : null,
+        autoRenew: s.cancelled_renew === undefined ? null : !s.cancelled_renew,
+        subscribedAt: isoOrNull(s.subscription_time),
+        expiresAt: isoOrNull(s.expire_time),
+        daysLeft: daysUntil(s.expire_time, now),
+    };
+}
+
+/** What an error says, for the report's problem list: a message, never key material. */
+const reasonOf = (e) =>
+    `${e?.code !== undefined && e?.code !== null ? `[${e.code}] ` : ""}${String(e?.message ?? e).slice(0, 160)}`;
+
+/**
+ * Read the account's plans.
+ *
+ * @param {object} api - the logged-in api (`fetchAccountInfo`, `getContext`)
+ * @param {object} [opts]
+ * @param {string} [opts.ownId]
+ * @param {number} [opts.now]
+ * @param {() => ({items: number, bytes: number}|null)} [opts.localIndex] - what this machine's zCloud index holds
+ * @param {object} [opts.read] - replaces the network calls (tests): `profile`, `usage`, `settings`, `subscription`
+ * @returns {Promise<object>} the report; a call that failed is named in `problems` and its part is null
+ */
+export async function readAccountStatus(
+    api,
+    { ownId = null, now = Date.now(), localIndex = () => null, read = {}, storage = null } = {},
+) {
+    const rd = {
+        profile: () => api.fetchAccountInfo(),
+        usage: () => getCloudUsage(api),
+        settings: () => getCloudSettings(api),
+        subscription: () => getCloudSubscription(api),
+        ...read,
+    };
+    const problems = [];
+    const sources = [];
+    const attempt = async (source, fn) => {
+        try {
+            const v = await fn();
+            sources.push(source);
+            return v ?? null;
+        } catch (e) {
+            problems.push({ source, reason: reasonOf(e) });
+            return null;
+        }
+    };
+
+    const account = await attempt("me-v2", rd.profile);
+    const profile = account?.profile ?? account ?? {};
+    const features = (() => {
+        try {
+            const ctx = api.getContext?.();
+            return ctx?.settings?.features ?? ctx?.loginInfo?.settings?.features ?? {};
+        } catch {
+            return {};
+        }
+    })();
+
+    // ---- zBusiness: the package on the profile, the limits from the server's table
+    const biz = profile.bizPkg ?? null;
+    const pkgId = Number.isFinite(Number(biz?.pkgId)) ? Number(biz.pkgId) : null;
+    const zbusiness =
+        pkgId === null
+            ? null
+            : {
+                  pkgId,
+                  active: pkgId !== 0,
+                  name: biz.pkgName?.EN ?? biz.pkgName?.VI ?? null,
+                  label: biz.label?.EN ?? biz.label?.VI ?? null,
+                  expiresAt: isoOrNull(biz.expired),
+                  daysLeft: daysUntil(biz.expired, now),
+                  expired: Number(biz.expired) > 0 ? Number(biz.expired) < now : null,
+                  limits: resolveBizLimits(features.ba_config?.ba_pkg_config, pkgId),
+              };
+
+    // ---- zCloud: usage and settings answer for every account; the subscription only for a paid plan
+    const usage = await attempt("zcld.v2/usage", rd.usage);
+    const settings = await attempt("zcld.cloud-settings", rd.settings);
+    let zcloud = null;
+    if (usage) {
+        const q = summarizeCloudQuota(usage, settings ?? {});
+        const state = zcloudState(q.planCode);
+        const paid = state === "paid" || state === "grace" || state === "unknown";
+        const subscription = paid
+            ? summarizeSubscription(await attempt("zcld.cloudinfopcweb", rd.subscription), now)
+            : null;
+        const keyBackup = Object.entries(settings?.key_export ?? {})
+            .filter(([, v]) => v && typeof v === "object" && Object.keys(v).length)
+            .map(([provider]) => provider);
+        const local = localIndex();
+        const cloudMedia = Number(usage.service_usage?.cloud_media);
+        zcloud = {
+            state,
+            plan: { code: q.planCode, name: q.plan },
+            subscription,
+            usage: {
+                usedBytes: q.usageBytes,
+                quotaBytes: q.quotaBytes,
+                freeBytes: q.freeBytes,
+                percent: q.quotaBytes ? Math.round((q.usageBytes / q.quotaBytes) * 1000) / 10 : null,
+                overQuota: q.overQuota,
+                byService: {
+                    cloudMedia: usage.service_usage?.cloud_media ?? null,
+                    myCloud: usage.service_usage?.my_cloud ?? null,
+                    messageBackup: usage.service_usage?.message_backup ?? null,
+                },
+            },
+            limits: {
+                perFileRaw: { cloudMedia: q.perFileLimitRaw, myCloud: q.myCloudPerFileLimitRaw, unit: "undefined" },
+                offloadEnabled: settings ? Boolean(Number(settings.enable_offload)) : null,
+                communityStored: settings ? Boolean(Number(settings.enable_community)) : null,
+            },
+            optIn: q.optIn,
+            keyBackup,
+            localIndex: local
+                ? {
+                      items: local.items,
+                      bytes: local.bytes,
+                      deltaVsServerBytes: Number.isFinite(cloudMedia) ? cloudMedia - local.bytes : null,
+                  }
+                : null,
+        };
+    }
+
+    return {
+        ownId,
+        name: profile.displayName ?? profile.zaloName ?? null,
+        checkedAt: new Date(now).toISOString(),
+        sources,
+        problems,
+        zbusiness,
+        enterprise:
+            profile.isEnterpriseAccount === undefined
+                ? null
+                : { isEnterprise: Boolean(Number(profile.isEnterpriseAccount)) },
+        zcloud,
+        // This machine's own storage of the account (src/core/storage-quota.js): usage, quota and retention.
+        storage: localStorage(ownId, storage),
+    };
+}
+
+/** The account's local storage, or null when it has no folder here or it cannot be read. */
+function localStorage(ownId, given) {
+    if (given) return given;
+    if (!ownId) return null;
+    try {
+        return describeStorage(String(ownId));
+    } catch {
+        return null;
+    }
+}
+
+const fmtBytes = (n) => {
+    if (n === null || n === undefined) return "?";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let v = Number(n);
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+};
+const fmtDay = (iso) => (iso ? iso.slice(0, 10) : "?");
+
+/**
+ * The report as lines for a person.
+ *
+ * @param {Awaited<ReturnType<typeof readAccountStatus>>} s
+ * @returns {string[]}
+ */
+export function describeAccountStatus(s) {
+    const out = [];
+    const b = s.zbusiness;
+    if (!b) out.push("zBusiness: not read.");
+    else if (!b.active) out.push("zBusiness: no package (package 0).");
+    else {
+        const when = b.expired
+            ? `expired ${fmtDay(b.expiresAt)}`
+            : `expires ${fmtDay(b.expiresAt)}${b.daysLeft !== null ? ` (${b.daysLeft} days)` : ""}`;
+        out.push(`zBusiness: ${b.name ?? `package ${b.pkgId}`} (package ${b.pkgId}), ${when}.`);
+    }
+    if (s.enterprise?.isEnterprise) out.push("Enterprise account: yes.");
+    const z = s.zcloud;
+    if (!z) out.push("zCloud: not read.");
+    else {
+        const u = z.usage;
+        if (z.state === "free") {
+            out.push("zCloud: free plan (no subscription).");
+        } else {
+            const tier = z.subscription?.tier ?? null;
+            const label = {
+                paid: "paid plan",
+                grace: "grace period (the data is deleted 30 days after the plan ended)",
+                "after-grace": "free, after the grace period",
+                unknown: `plan ${z.plan.code}`,
+            }[z.state];
+            out.push(`zCloud: ${tier ? `${tier}, ` : ""}${label}.`);
+            if (z.subscription) {
+                const sub = z.subscription;
+                out.push(
+                    `  Subscription: ${sub.durationMonths ?? "?"} months through ${sub.gateway ?? "?"}, ` +
+                        `${sub.autoRenew === null ? "" : sub.autoRenew ? "renews automatically, " : "will not renew, "}` +
+                        `expires ${fmtDay(sub.expiresAt)}${sub.daysLeft !== null ? ` (${sub.daysLeft} days)` : ""}.`,
+                );
+            }
+        }
+        out.push(
+            `  Used ${fmtBytes(u.usedBytes)} of ${fmtBytes(u.quotaBytes)}${u.percent !== null ? ` (${u.percent}%)` : ""}` +
+                `${u.overQuota ? ", OVER the quota" : ""}: media ${fmtBytes(u.byService.cloudMedia)}, My Cloud ${fmtBytes(u.byService.myCloud)}, text message backup ${fmtBytes(u.byService.messageBackup)}.`,
+        );
+        const on = Object.entries(z.optIn ?? {})
+            .filter(([, v]) => v)
+            .map(([k]) => k);
+        out.push(
+            `  Backs up: ${on.length ? on.join(", ") : "nothing"}. Key backup: ${z.keyBackup.length ? z.keyBackup.join(", ") : "none"}.`,
+        );
+        if (z.localIndex) {
+            out.push(
+                `  This machine's index: ${z.localIndex.items} item(s), ${fmtBytes(z.localIndex.bytes)}` +
+                    `${z.localIndex.deltaVsServerBytes === null ? "" : ` (the server counts ${fmtBytes(Math.abs(z.localIndex.deltaVsServerBytes))} ${z.localIndex.deltaVsServerBytes >= 0 ? "more" : "less"} in media)`}.`,
+            );
+        }
+    }
+    const st = s.storage;
+    if (st) {
+        const q = st.quota;
+        out.push(
+            `This machine: ${fmtBytes(st.usage.total)} (database ${fmtBytes(st.usage.db)}, media ${fmtBytes(st.usage.media)}, ` +
+                `outbox ${fmtBytes(st.usage.outbox)})` +
+                (q.accountLimit
+                    ? ` of ${fmtBytes(q.accountLimit)}${q.level ? `, ${q.level}` : ""}${q.purgeAt ? `, purge at ${fmtDay(q.purgeAt)}` : ""}`
+                    : ", no limit") +
+                `; retention: messages ${st.retention.messages}, media ${st.retention.media}.`,
+        );
+    }
+    for (const p of s.problems) out.push(`Could not read ${p.source}: ${p.reason}`);
+    return out;
+}

package/src/core/accounts.js

@@ -3,7 +3,7 @@
  * Maps each account to its own proxy (1:1) and tracks active account.
  *
  * A fleet of daemons and the `account` / `login` commands share this one file, so it is written the
- * way a shared file must be (src/utils/atomic-file.js):
+ * way a shared file must be (src/zalo/kernel/atomic-file.js):
  *  - every change is read-modify-write under a lock file (`accounts.json.lock`), so two writers no
  *    longer lose each other's change;
  *  - every write is a temp file renamed over the target, so a reader never sees a half-written
@@ -18,7 +18,8 @@ import { readFileSync, existsSync, mkdirSync, rmSync, renameSync } from "fs";
 import { join } from "path";
 import { CONFIG_DIR, getAccountDir, deleteCredentials } from "./credentials.js";
 import { checkLock } from "./lock.js";
-import { sleepSync, sweepStaleTemps, withFileLock, writeFileAtomic } from "../utils/atomic-file.js";
+import { prepareAccountForget } from "./keystore/index.js";
+import { sleepSync, sweepStaleTemps, withFileLock, writeFileAtomic } from "../zalo/kernel/atomic-file.js";
 
 function accountsFile() {
     return join(CONFIG_DIR, "accounts.json");
@@ -278,10 +279,13 @@ export function removeAccount(ownId) {
     const accounts = load();
     if (!accounts.some((a) => a.ownId === ownId)) return { removed: false };
 
+    // A provider's item outside the folder (a keychain entry) goes with the account; read the keyring before the wipe.
+    const forgetKeys = prepareAccountForget(ownId);
     const { wiped, skippedLocked } = wipeAccountDir(ownId);
     if (skippedLocked) {
         return { removed: false, skippedLocked };
     }
+    if (wiped) forgetKeys();
 
     mutate((current) => {
         const filtered = current.filter((a) => a.ownId !== ownId);
@@ -303,9 +307,12 @@ export function removeAccount(ownId) {
  *
  * @param {string|null|undefined} ownId
  * @param {string|null|undefined} name
+ * @param {{ lockTimeoutMs?: number }} [opts] - how long to wait for the registry's lock before giving up on this
+ *   cosmetic refresh (3 s: a daemon calls this from event handlers); a test that is about lost writes, not about
+ *   timing, waits longer
  * @returns {boolean} true when an existing account's name was changed
  */
-export function updateAccountName(ownId, name) {
+export function updateAccountName(ownId, name, { lockTimeoutMs = 3000 } = {}) {
     const id = ownId ? String(ownId).trim() : "";
     const trimmed = typeof name === "string" ? name.trim() : "";
     if (!id || !trimmed) return false;
@@ -324,7 +331,7 @@ export function updateAccountName(ownId, name) {
             },
             // Daemons call this from event handlers: a busy registry costs a missed cosmetic refresh,
             // not seconds of a blocked event loop.
-            { timeoutMs: 3000 },
+            { timeoutMs: lockTimeoutMs },
         );
     } catch (e) {
         // A cached display name is not worth a daemon: say so and carry on.