@ardennguyen/zalo-agent-cli 2.5.5 → 2.5.7

package/src/core/fleet.js

@@ -0,0 +1,255 @@
+/**
+ * Running many accounts on one machine: which port each gets, which are healthy, and the files that
+ * supervise them.
+ *
+ * One account is one process (AGENTS.md section 13), so hundreds of accounts are hundreds of daemons, each
+ * with a port, a token and a systemd unit. Until this module the only tooling was the template unit in the
+ * docs: the operator kept the port table by hand, found a dead account by probing each one, and a whole
+ * fleet restarting at once was the heaviest moment of its life. `zalo-agent fleet ...` (src/commands/fleet.js)
+ * is built on these.
+ *
+ *  - The port table (`fleet.json` in the config directory) gives each account a stable port. It is
+ *    assigned once and never reshuffled, so adding an account never moves another one's port.
+ *  - {@link classifyAccount} turns a daemon's health snapshot into one word, the one `fleet status` shows
+ *    and `fleet restart --unhealthy` acts on.
+ *  - {@link planBatches} orders a start-up: shuffled, in groups, so accounts that were set up together do
+ *    not all log in together.
+ *  - {@link generateFleetFiles} writes the systemd unit, env files with generated tokens, and a proxy.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR } from "./credentials.js";
+import { withFileLock, writeFileAtomic } from "../utils/atomic-file.js";
+import { COMMON_ENV_TEMPLATE, renderAccountEnv, renderCaddyfile, renderUnit } from "./fleet-templates.js";
+
+export const DEFAULT_BASE_PORT = 3900;
+
+/** The fleet's port table could not be read or used. Nothing was changed. */
+export class FleetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FleetError";
+    }
+}
+
+/** @returns {string} */
+export function fleetFile() {
+    return join(CONFIG_DIR, "fleet.json");
+}
+
+/**
+ * @returns {{ basePort: number, ports: Record<string, number> }}
+ * @throws {FleetError} when the file exists but is not a usable table
+ */
+export function loadPortTable() {
+    const file = fleetFile();
+    if (!existsSync(file)) return { basePort: DEFAULT_BASE_PORT, ports: {} };
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, "utf8"));
+    } catch (e) {
+        throw new FleetError(
+            `${file} exists but cannot be read (${e.message}). It was left untouched; fix or remove it.`,
+        );
+    }
+    const ports = data?.ports;
+    if (!ports || typeof ports !== "object" || Array.isArray(ports)) {
+        throw new FleetError(`${file} has no "ports" table. It was left untouched; fix or remove it.`);
+    }
+    for (const [id, p] of Object.entries(ports)) {
+        if (!Number.isInteger(p) || p < 1 || p > 65535) {
+            throw new FleetError(
+                `${file}: account ${id} has port ${JSON.stringify(p)}, which is not a port. It was left untouched.`,
+            );
+        }
+    }
+    return { basePort: Number.isInteger(data.basePort) ? data.basePort : DEFAULT_BASE_PORT, ports };
+}
+
+/**
+ * Give every account in `ownIds` a port, keeping the ones it already has.
+ *
+ * A new account takes the lowest port at or above the base that no account holds, so a port freed by a
+ * removed account is reused and an existing assignment never moves. The table is changed under a lock and
+ * written atomically, as the registry is.
+ *
+ * @param {string[]} ownIds
+ * @param {{ basePort?: number }} [options] - Only used while the table is still empty
+ * @returns {{ basePort: number, ports: Record<string, number>, added: string[] }}
+ */
+export function assignPorts(ownIds, { basePort } = {}) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    return withFileLock(`${fleetFile()}.lock`, () => {
+        const table = loadPortTable();
+        const hasAny = Object.keys(table.ports).length > 0;
+        const base = !hasAny && Number.isInteger(basePort) ? basePort : table.basePort;
+        if (base < 1 || base > 65535) throw new FleetError(`base port ${base} is not a port`);
+        const taken = new Set(Object.values(table.ports));
+        const added = [];
+        for (const id of [...ownIds].sort()) {
+            if (table.ports[id] !== undefined) continue;
+            let p = base;
+            while (taken.has(p)) p++;
+            if (p > 65535) throw new FleetError("no free port left above the base port");
+            table.ports[id] = p;
+            taken.add(p);
+            added.push(id);
+        }
+        if (added.length || !existsSync(fleetFile())) {
+            writeFileAtomic(fleetFile(), JSON.stringify({ version: 1, basePort: base, ports: table.ports }, null, 2), {
+                mode: 0o644,
+            });
+        }
+        return { basePort: base, ports: table.ports, added };
+    });
+}
+
+/** The states `fleet status` reports, worst last. */
+export const STATES = Object.freeze(["ok", "degraded", "starting", "down", "unresponsive", "stopped"]);
+
+/**
+ * One word for an account.
+ *
+ *  - `stopped`: no daemon runs for it
+ *  - `unresponsive`: a daemon runs (its lock is held) but does not answer on its loopback channel
+ *  - `down`: it answers, and its Zalo socket has been down at least `downForSec`
+ *  - `starting`: it answers, and its socket is not up yet (or has not been down long enough to count)
+ *  - `degraded`: the socket is up but it has warnings (a webhook backlog, dead letters, open gaps)
+ *  - `ok`
+ *
+ * @param {{ running: boolean, health: object|null }} a - `health` is null when the daemon did not answer
+ * @param {{ downForSec?: number }} [o]
+ * @returns {"ok"|"degraded"|"starting"|"down"|"unresponsive"|"stopped"}
+ */
+export function classifyAccount({ running, health }, { downForSec = 180 } = {}) {
+    if (!running) return "stopped";
+    if (!health) return "unresponsive";
+    const socket = health.socket ?? {};
+    if (socket.state === "down" && (socket.forSec ?? 0) >= downForSec) return "down";
+    if (socket.state !== "up") return "starting";
+    return health.warnings?.length ? "degraded" : "ok";
+}
+
+/** True for the states a restart can help: the account is not serving. */
+export const needsRestart = (state) => state === "down" || state === "unresponsive";
+
+/**
+ * Split accounts into start-up batches: shuffled first, so accounts set up together do not log in together.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {{ size?: number, random?: () => number }} [o]
+ * @returns {T[][]}
+ */
+export function planBatches(items, { size = 5, random = Math.random } = {}) {
+    const n = Math.max(1, Math.floor(size) || 1);
+    const shuffled = [...items];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    const batches = [];
+    for (let i = 0; i < shuffled.length; i += n) batches.push(shuffled.slice(i, i + n));
+    return batches;
+}
+
+/** @param {number|null|undefined} sec */
+function age(sec) {
+    if (sec === null || sec === undefined) return "-";
+    if (sec < 90) return `${sec}s`;
+    if (sec < 5400) return `${Math.round(sec / 60)}m`;
+    if (sec < 172800) return `${(sec / 3600).toFixed(1)}h`;
+    return `${Math.round(sec / 86400)}d`;
+}
+
+/**
+ * The table `fleet status` prints, one row per account.
+ *
+ * @param {Array<{ accountId: string, name?: string, port?: number|null, state: string, daemon: {running: boolean, pid: number|null}, health: object|null }>} rows
+ * @returns {string[]} Lines
+ */
+export function renderStatusTable(rows) {
+    const header = ["ACCOUNT", "NAME", "PORT", "STATE", "PID", "SOCKET", "LAST EVENT", "WEBHOOK", "GAPS", "MEM"];
+    const body = rows.map((r) => {
+        const h = r.health;
+        const w = h?.webhook;
+        return [
+            r.accountId,
+            (r.name || "").slice(0, 20),
+            r.port ?? "-",
+            r.state,
+            r.daemon.running ? (r.daemon.pid ?? "?") : "-",
+            h ? `${h.socket.state} ${age(h.socket.forSec)}` : "-",
+            h ? age(h.events.lastEventAgeSec) : "-",
+            w ? `${w.pending}q ${w.dead}d` : h ? "off" : "-",
+            h ? h.coverage.pendingGaps : "-",
+            h ? `${Math.round(h.process.rssBytes / 1048576)}M` : "-",
+        ].map(String);
+    });
+    const widths = header.map((c, i) => Math.max(c.length, ...body.map((r) => r[i].length)));
+    const line = (cells) =>
+        cells
+            .map((c, i) => c.padEnd(widths[i]))
+            .join("  ")
+            .trimEnd();
+    return [line(header), ...body.map(line)];
+}
+
+/**
+ * Write the files that supervise a fleet: the systemd unit, env files (with a generated bearer token per
+ * account), the port table, and optionally a Caddyfile. An existing file is never overwritten unless `force`;
+ * an existing account env file keeps its token even then unless `rotateTokens`.
+ *
+ * @param {object} args
+ * @param {string} args.outDir
+ * @param {Array<{ ownId: string, port: number }>} args.accounts
+ * @param {{ user?: string, home?: string, bin?: string, mediaDir?: string, etcDir?: string }} [args.paths] -
+ *   for the unit
+ * @param {string|null} [args.domain] - Also write a Caddyfile for this hostname
+ * @param {boolean} [args.force]
+ * @param {boolean} [args.rotateTokens]
+ * @param {() => string} [args.makeToken]
+ * @returns {{ written: string[], kept: string[] }} Paths relative to outDir. Tokens are never returned.
+ */
+export function generateFleetFiles({
+    outDir,
+    accounts,
+    paths = {},
+    domain = null,
+    force = false,
+    rotateTokens = false,
+    makeToken = () => randomBytes(32).toString("hex"),
+}) {
+    const written = [];
+    const kept = [];
+    const put = (rel, text, { secret = false, overwrite = force } = {}) => {
+        const file = join(outDir, rel);
+        if (existsSync(file) && !overwrite) {
+            kept.push(rel);
+            return false;
+        }
+        writeFileAtomic(file, text, { mode: secret ? 0o600 : 0o644 });
+        written.push(rel);
+        return true;
+    };
+
+    put("zalo-mcp@.service", renderUnit(paths));
+    put("common.env", COMMON_ENV_TEMPLATE, { secret: true });
+    for (const { ownId, port } of accounts) {
+        const rel = join("accounts", `${ownId}.env`);
+        const file = join(outDir, rel);
+        // Never replace a token that is already in use just because the file is being regenerated.
+        if (existsSync(file) && !rotateTokens) {
+            kept.push(rel);
+            continue;
+        }
+        put(rel, renderAccountEnv({ ownId, port, token: makeToken() }), { secret: true, overwrite: true });
+    }
+    put("ports.json", JSON.stringify(Object.fromEntries(accounts.map((a) => [a.ownId, a.port])), null, 2) + "\n", {
+        overwrite: true,
+    });
+    if (domain) put("Caddyfile", renderCaddyfile({ domain, accounts }));
+    return { written, kept };
+}

package/src/core/log-sink.js

@@ -0,0 +1,311 @@
+/**
+ * What a daemon's log does between a line being written and it reaching `daemon.log`: a level filter,
+ * a timestamp (or JSON), and size-based rotation.
+ *
+ * `daemon.log` used to be everything `mcp start` / `listen` print, forever: one line per HTTP request
+ * (with the caller's address and user agent), one per message (with its text), no timestamps, and a file
+ * that only ever grew. A fleet of daemons turns that into disk pressure and a log pipeline full of noise,
+ * and the message lines put private text in a file whose job is to say what the daemon is doing.
+ *
+ *   - Levels `error` < `warn` < `info` < `debug`, default `info`. A line is `debug` when it starts with
+ *     {@link DEBUG_MARK}: the per-request and per-message lines. Every other line is classified by its
+ *     wording ({@link classifyLine}), because the daemons write free text through console.error from a
+ *     hundred places and this changes none of them.
+ *   - Text lines get an ISO timestamp; `ZALO_LOG_FORMAT=json` writes one JSON object per line instead.
+ *   - The file is rotated by size: `daemon.log` -> `daemon.log.1` -> ... -> `daemon.log.<keep>`, the
+ *     oldest dropped.
+ *
+ * Settings: `ZALO_LOG_LEVEL`, `ZALO_LOG_FORMAT`, `ZALO_LOG_MAX_SIZE`, `ZALO_LOG_KEEP`, each with an
+ * `_<ownId>` form that wins, and `--log-level` on both daemons.
+ */
+
+import fs from "node:fs";
+
+export const LOG_LEVELS = Object.freeze(["error", "warn", "info", "debug"]);
+export const LOG_FORMATS = Object.freeze(["text", "json"]);
+
+/** A line that begins with this is a `debug` line: per request, per message. */
+export const DEBUG_MARK = "[debug] ";
+
+export const DEFAULT_LOG_LEVEL = "info";
+export const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_KEEP = 3;
+/** Below this a rotation would run every few lines. */
+export const MIN_MAX_BYTES = 4 * 1024;
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+const rank = (level) => LOG_LEVELS.indexOf(level);
+
+/**
+ * The level of one log line, by its wording. Not exact, and not meant to be: it decides which lines a
+ * `warn` or `error` setting keeps, and a missed one is one the daemon wrote as plain text.
+ *
+ * @param {string} line
+ * @returns {"error"|"warn"|"info"|"debug"}
+ */
+export function classifyLine(line) {
+    if (line.startsWith(DEBUG_MARK)) return "debug";
+    const text = line.replace(ANSI, "");
+    if (/WARNING|⚠|\bwarn(ing)?\b/i.test(text)) return "warn";
+    if (
+        /\b(fail(ed|ure|s)?|error|exception|fatal|refus(ed|ing)|cannot|could not|unable|exited|crash(ed)?)\b|✗|✖|ECONN|EADDR|EPERM|EACCES/i.test(
+            text,
+        )
+    ) {
+        return "error";
+    }
+    return "info";
+}
+
+/**
+ * Parse `20m`, `500k`, `1g` or a plain byte count.
+ * @param {string|number|null|undefined} value
+ * @returns {number|null} Bytes, or null when it is not a size
+ */
+export function parseSize(value) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([kmg]?)b?\s*$/i.exec(String(value ?? ""));
+    if (!m) return null;
+    const mult = { "": 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3 }[m[2].toLowerCase()];
+    return Math.floor(Number(m[1]) * mult);
+}
+
+/**
+ * The logging settings of one daemon: flag, then `NAME_<ownId>`, then `NAME`, then the defaults. A value
+ * that cannot be used is reported and replaced by the default, so a typo is not mistaken for a setting.
+ *
+ * @param {object} args
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @param {string|null} [args.ownId]
+ * @param {string|null} [args.levelFlag] - `--log-level`
+ * @returns {{ level: string, format: string, maxBytes: number, keep: number, warnings: string[], explicit: boolean }}
+ *   `explicit` is true when anything was asked for, so a foreground run knows to filter its stderr at all
+ */
+export function resolveLogSettings({ env = process.env, ownId = null, levelFlag = null } = {}) {
+    const warnings = [];
+    const pick = (name) => {
+        const scoped = ownId ? env[`${name}_${ownId}`] : undefined;
+        const v = typeof scoped === "string" && scoped.trim() ? scoped : env[name];
+        return typeof v === "string" && v.trim() ? v.trim() : null;
+    };
+
+    const rawLevel = levelFlag?.trim() || pick("ZALO_LOG_LEVEL");
+    let level = DEFAULT_LOG_LEVEL;
+    if (rawLevel) {
+        if (LOG_LEVELS.includes(rawLevel.toLowerCase())) level = rawLevel.toLowerCase();
+        else
+            warnings.push(`log level "${rawLevel}" is not one of ${LOG_LEVELS.join(", ")}; using ${DEFAULT_LOG_LEVEL}`);
+    }
+
+    const rawFormat = pick("ZALO_LOG_FORMAT");
+    let format = "text";
+    if (rawFormat) {
+        if (LOG_FORMATS.includes(rawFormat.toLowerCase())) format = rawFormat.toLowerCase();
+        else warnings.push(`log format "${rawFormat}" is not one of ${LOG_FORMATS.join(", ")}; using text`);
+    }
+
+    const rawSize = pick("ZALO_LOG_MAX_SIZE");
+    let maxBytes = DEFAULT_MAX_BYTES;
+    if (rawSize) {
+        const n = parseSize(rawSize);
+        if (n !== null && n >= MIN_MAX_BYTES) maxBytes = n;
+        else warnings.push(`log max size "${rawSize}" is not a size of at least 4k (e.g. 20m, 1g); using 50m`);
+    }
+
+    const rawKeep = pick("ZALO_LOG_KEEP");
+    let keep = DEFAULT_KEEP;
+    if (rawKeep) {
+        const n = Number(rawKeep);
+        if (Number.isInteger(n) && n >= 0 && n <= 50) keep = n;
+        else warnings.push(`log keep "${rawKeep}" is not a whole number from 0 to 50; using ${DEFAULT_KEEP}`);
+    }
+
+    const explicit = Boolean(levelFlag || pick("ZALO_LOG_LEVEL") || pick("ZALO_LOG_FORMAT"));
+    return { level, format, maxBytes, keep, warnings, explicit };
+}
+
+/**
+ * One log line, as it is written.
+ *
+ * @param {object} args
+ * @param {string} args.line - Without its newline
+ * @param {string} args.level - The line's level
+ * @param {"text"|"json"} args.format
+ * @param {Date} args.at
+ * @param {string|null} [args.accountId]
+ * @returns {string} Without a newline
+ */
+export function formatLine({ line, level, format, at, accountId = null }) {
+    if (format === "json") {
+        const plain = line.replace(ANSI, "");
+        const msg = plain.startsWith(DEBUG_MARK) ? plain.slice(DEBUG_MARK.length) : plain;
+        return JSON.stringify({
+            ts: at.toISOString(),
+            level,
+            ...(accountId ? { account: accountId } : {}),
+            msg: msg.trimEnd(),
+        });
+    }
+    return `${at.toISOString()} ${line}`;
+}
+
+/**
+ * A log file that rotates by size.
+ *
+ * @param {object} args
+ * @param {string} args.file
+ * @param {number} args.maxBytes
+ * @param {number} args.keep - How many rotated files to keep (0: just start over)
+ * @param {typeof fs} [args.fsImpl] - Test seam
+ * @param {() => Date} [args.now]
+ * @returns {{ write: (text: string) => void, rotate: () => boolean, close: () => void, size: () => number }}
+ */
+export function createRotatingFile({ file, maxBytes, keep, fsImpl = fs, now = () => new Date() }) {
+    let fd = null;
+    let size = 0;
+    let rotateAt = maxBytes;
+
+    const open = () => {
+        fd = fsImpl.openSync(file, "a", 0o600);
+        try {
+            size = fsImpl.fstatSync(fd).size;
+        } catch {
+            size = 0;
+        }
+    };
+
+    function rotate() {
+        try {
+            if (fd !== null) fsImpl.closeSync(fd);
+        } catch {
+            /* closing a handle that is already gone */
+        }
+        fd = null;
+        try {
+            if (keep > 0) {
+                for (let i = keep - 1; i >= 1; i--) {
+                    try {
+                        fsImpl.renameSync(`${file}.${i}`, `${file}.${i + 1}`);
+                    } catch (e) {
+                        if (e.code !== "ENOENT") throw e;
+                    }
+                }
+                fsImpl.renameSync(file, `${file}.1`);
+            } else {
+                fsImpl.unlinkSync(file);
+            }
+            open();
+            rotateAt = maxBytes;
+            const header = `--- [${now().toISOString()}] log rotated: the previous ${keep > 0 ? "file is daemon.log.1" : "log was discarded"} ---\n`;
+            fsImpl.writeSync(fd, header);
+            size += Buffer.byteLength(header);
+            return true;
+        } catch {
+            // Windows refuses to rename a file another process (a tail, an editor) has open. Carry on
+            // appending to the same file and look again after another megabyte.
+            try {
+                open();
+            } catch {
+                fd = null;
+            }
+            rotateAt = size + 1024 * 1024;
+            return false;
+        }
+    }
+
+    return {
+        write(text) {
+            try {
+                if (fd === null) open();
+                const buf = Buffer.from(text, "utf8");
+                fsImpl.writeSync(fd, buf);
+                size += buf.length;
+                if (maxBytes > 0 && size >= rotateAt) rotate();
+            } catch {
+                /* logging must never take the daemon down */
+            }
+        },
+        rotate,
+        close() {
+            try {
+                if (fd !== null) fsImpl.closeSync(fd);
+            } catch {
+                /* already closed */
+            }
+            fd = null;
+        },
+        size: () => size,
+    };
+}
+
+/**
+ * The line-oriented filter in front of a file (or any `write(text)`).
+ *
+ * Chunks are not lines: a write can hold three lines or half of one. Complete lines are classified,
+ * filtered and formatted; a partial line waits for its newline, and is flushed after a moment so it never
+ * sits unwritten. A continuation (an indented line, such as a stack frame) takes the level of the line
+ * before it, so an error's stack is kept or dropped with it.
+ *
+ * @param {object} args
+ * @param {(text: string) => void} args.write
+ * @param {string} [args.level]
+ * @param {"text"|"json"} [args.format]
+ * @param {string|null} [args.accountId]
+ * @param {() => Date} [args.now]
+ * @param {number} [args.flushMs]
+ * @returns {{ write: (chunk: string|Buffer) => void, flush: () => void, setLevel: (l: string) => void, setFormat: (f: string) => void, level: () => string }}
+ */
+export function createLogSink({
+    write,
+    level = DEFAULT_LOG_LEVEL,
+    format = "text",
+    accountId = null,
+    now = () => new Date(),
+    flushMs = 250,
+}) {
+    let threshold = rank(level) >= 0 ? level : DEFAULT_LOG_LEVEL;
+    let fmt = format;
+    let partial = "";
+    let lastLevel = "info";
+    let timer = null;
+
+    const emit = (line) => {
+        const continuation = /^\s+\S/.test(line) && !line.startsWith(DEBUG_MARK);
+        const lineLevel = continuation ? lastLevel : classifyLine(line);
+        lastLevel = lineLevel;
+        if (rank(lineLevel) > rank(threshold)) return;
+        write(`${formatLine({ line, level: lineLevel, format: fmt, at: now(), accountId })}\n`);
+    };
+
+    const flush = () => {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        if (partial) {
+            const p = partial;
+            partial = "";
+            emit(p);
+        }
+    };
+
+    return {
+        write(chunk) {
+            const text = partial + (Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+            const lines = text.split(/\r?\n/);
+            partial = lines.pop() ?? "";
+            for (const line of lines) if (line.length) emit(line);
+            if (timer) clearTimeout(timer);
+            timer = null;
+            if (partial) {
+                timer = setTimeout(flush, flushMs);
+                timer.unref?.();
+            }
+        },
+        flush,
+        setLevel(l) {
+            if (rank(l) >= 0) threshold = l;
+        },
+        setFormat(f) {
+            if (LOG_FORMATS.includes(f)) fmt = f;
+        },
+        level: () => threshold,
+    };
+}

package/src/core/oa-client.js

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { withFileLock, writeFileAtomic } from "../utils/atomic-file.js";
 
 const V3_BASE = "https://openapi.zalo.me/v3.0/oa";
 const V2_BASE = "https://openapi.zalo.me/v2.0/oa";
@@ -36,12 +37,15 @@ const TOKEN_URL = "https://oauth.zaloapp.com/v4/oa/access_token";
 export function saveOACreds(data, oaId = "default") {
     ensureDir();
     const credsFile = getOACredsFile();
-    let creds = {};
-    if (fs.existsSync(credsFile)) {
-        creds = JSON.parse(fs.readFileSync(credsFile, "utf8"));
-    }
-    creds[oaId] = { ...creds[oaId], ...data, updatedAt: new Date().toISOString() };
-    fs.writeFileSync(credsFile, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    // One file holds every OA: read-modify-write under a lock, replaced atomically.
+    withFileLock(`${credsFile}.lock`, () => {
+        let creds = {};
+        if (fs.existsSync(credsFile)) {
+            creds = JSON.parse(fs.readFileSync(credsFile, "utf8"));
+        }
+        creds[oaId] = { ...creds[oaId], ...data, updatedAt: new Date().toISOString() };
+        writeFileAtomic(credsFile, JSON.stringify(creds, null, 2));
+    });
 }
 
 /** Save OA access token to disk (backward compat). */