@leemour/max-cli 0.9.0 → 0.11.0

package/dist/client.js

@@ -1,16 +1,19 @@
 import { CliError } from "@leemour/cli-core";
 import { namesFrom, SETTING_FLAGS, toChat, toContact, toFolder, toGroupCard, toMessage, toProfile, toReactions, toSession, } from "./domain/map.js";
+import { heldWindows } from "./export.js";
 import { wireClient } from "./generated/client.generated.js";
 import { parseMarkdown } from "./markdown.js";
 import { asFirstWord } from "./profile.js";
 import { Connection, ProtocolError } from "./protocol/connection.js";
 import { asId } from "./protocol/frame.js";
 import { isId, pickChat, pickPerson } from "./resolve.js";
-import { countsIn, idsOf } from "./runs/events.js";
+import { countsIn, idsOf, maxErrorKey } from "./runs/events.js";
 import { LOGIN_CHATS, startSession } from "./session/handshake.js";
 import { tokenByQr } from "./session/login.js";
+import { loginPausedUntil, withLoginRefused, withoutLoginPause, } from "./session/store.js";
 import { WEB_USER_AGENT } from "./spec/identity.js";
 import { buildRequest, checkResponse } from "./spec/index.js";
+import { ASSET_TYPES } from "./spec/operations/assets.js";
 import { isImage, readUpload, uploadFile, uploadPhoto } from "./upload.js";
 /**
  * **The only thing above this line that knows MAX exists.** Commands speak the domain model; the
@@ -28,6 +31,7 @@ export class MaxClient {
     #store;
     #connection;
     #fullLogin;
+    #resume;
     #warn;
     #cache;
     #offline;
@@ -36,12 +40,14 @@ export class MaxClient {
     #invoke = ((operation, request) => this.#send(operation, request));
     #wire = wireClient(this.#invoke);
     #login;
+    #chatsCut = false;
     #previousCid = 0;
     #people;
     #merged;
-    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends, fullLogin = false, }) {
+    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends, fullLogin = false, resume, }) {
         this.#store = store;
         this.#fullLogin = fullLogin;
+        this.#resume = resume;
         this.#connection = connection ?? new Connection(timeoutMs === undefined ? {} : { timeoutMs });
         this.#warn = warn ?? ((message) => process.stderr.write(`${message}\n`));
         this.#cache = cache;
@@ -90,7 +96,11 @@ export class MaxClient {
             // The other devices are out from here on, whatever follows fails: the journal says so.
             done();
             const token = answer.token;
-            if (typeof token === "string" && token !== "") {
+            if (typeof token === "string" && token !== "" && this.#fromEnvironment()) {
+                this.#warnAbout("token_not_saved", "MAX gave this session a new token, and it was not saved: the one in use came from MAX_TOKEN — " +
+                    "if MAX_TOKEN stops working, log in again and set it anew");
+            }
+            else if (typeof token === "string" && token !== "") {
                 try {
                     this.#store.writeToken(token);
                 }
@@ -186,6 +196,12 @@ export class MaxClient {
             const cache = this.#cache;
             return { ...chat, members: chat.kind === "channel" || !cache ? null : cache.chats.members(chat.id) };
         },
+        /** The other person in a one-to-one chat, by the chat's participants; `undefined` for anything else. */
+        partner: async (chatId) => {
+            await this.#connectOnce();
+            const raw = asArray(this.#session().chats).find((chat) => asId(chat.id) === chatId);
+            return raw ? this.#partnerOf(raw) : undefined;
+        },
         /** What a link leads to, without joining it. */
         inspect: async (link) => {
             if (this.#offline)
@@ -209,13 +225,18 @@ export class MaxClient {
         markRead: async (chatId, messageId) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot mark a chat read");
-            this.#guard(chatId, "read", messageId);
+            this.#guard({ chatId, kind: "read" }, messageId);
             try {
                 await this.#connectOnce();
                 const upTo = messageId ?? (await this.#history(chatId, { from: Date.now(), backward: 1, forward: 0 })).at(-1)?.id;
                 if (!upTo)
                     throw new CliError("not_found", `chat ${chatId} has no messages to mark read`);
-                const answer = await this.#wire.chats.mark({ type: "READ_MESSAGE", chatId, messageId: upTo, mark: Date.now() });
+                // The web client's mark is the read message's own time, not the moment of reading: a later
+                // one would mark newer messages read too (captured 2026-09-25, `RES-10`).
+                const mark = timeOfMessageId(upTo);
+                if (mark === undefined)
+                    throw new CliError("validation_error", `"${upTo}" is not a message id`);
+                const answer = await this.#wire.chats.mark({ type: "READ_MESSAGE", chatId, messageId: upTo, mark });
                 this.#sends?.record({ chatId, kind: "read", outcome: "sent", messageId: upTo });
                 return { chatId, messageId: upTo, unread: typeof answer.unread === "number" ? answer.unread : null };
             }
@@ -235,20 +256,23 @@ export class MaxClient {
          * Not retried, unlike a message: a second attempt with a new `cid` is a second group, and
          * whether MAX deduplicates a creation by `cid` is not measured.
          */
-        create: (title, people = []) => this.#changeChat(null, "create", async () => {
+        create: async (title, people = []) => {
             const userIds = await this.#personIds(people);
-            const answer = await this.#wire.messages.send({
-                message: {
-                    cid: this.#nextCid(),
-                    attaches: [{ _type: "CONTROL", event: "new", chatType: "CHAT", title, userIds }],
-                },
-                notify: true,
-            });
-            const chat = toGroupCard(record(answer.chat) ?? {});
-            return { chatId: chat.id, result: chat, people: userIds.length };
-        }),
+            return this.#changeChat(null, "create", async () => {
+                const answer = await this.#wire.messages.send({
+                    message: {
+                        cid: this.#nextCid(),
+                        attaches: [{ _type: "CONTROL", event: "new", chatType: "CHAT", title, userIds }],
+                    },
+                    notify: true,
+                });
+                const chat = toGroupCard(record(answer.chat) ?? {});
+                return { chatId: chat.id, result: chat, people: userIds.length };
+            }, userIds);
+        },
         members: {
-            add: (reference, people, { history = true } = {}) => this.#updateMembers(reference, people, "members.add", { operation: "add", showHistory: history }),
+            /** No history unless asked (`NEED-272`): what was said before somebody joined is not theirs by default. */
+            add: (reference, people, { history = false } = {}) => this.#updateMembers(reference, people, "members.add", { operation: "add", showHistory: history }),
             remove: (reference, people) => this.#updateMembers(reference, people, "members.remove", { operation: "remove", cleanMsgPeriod: 0 }),
         },
         admins: {
@@ -483,7 +507,6 @@ export class MaxClient {
                 itemType: "DELAYED",
                 getChat: false,
                 getMessages: true,
-                interactive: false,
             });
             const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
             return asArray(answer.messages)
@@ -524,6 +547,52 @@ export class MaxClient {
             const messages = await this.#history(chatId, { from: before ?? Date.now(), backward: limit, forward: 0 });
             return { items: messages, hasMore: messages.length >= limit };
         },
+        /**
+         * **Fills a chat's history backwards into the cache, page by page**, the way web.max.ru pages
+         * it when scrolled up (`RES-9`, captured 2026-09-25): 30 back from the time of the oldest
+         * message loaded, so each page repeats one message, and a shorter page is the chat's start.
+         *
+         * Stretches the cache already read completely are stepped over, so a second run continues
+         * where the first stopped. It ends at `since`, at `last` messages held, at the chat's start, or
+         * after `maxPages` — and on the first error, with no retry: what the limit error of MAX looks
+         * like is unknown, so every error is treated as one. Reactions are not read.
+         */
+        backup: async (chatId, { since, last, maxPages, pause, onPage, }) => {
+            const cache = this.#cache;
+            if (!cache)
+                throw new CliError("not_found", "the local copy could not be opened, and a backup is kept there");
+            let cursor = Date.now();
+            let pages = 0;
+            for (;;) {
+                const held = heldWindows(cache.messages.ranges(chatId)).find((window) => window.from <= cursor && cursor <= window.to);
+                if (held)
+                    cursor = held.from;
+                if (held?.from === 0)
+                    return { pages, complete: true, reachedStart: true };
+                if (since !== undefined && cursor <= since)
+                    return { pages, complete: true, reachedStart: false };
+                if (last !== undefined && cache.messages.count(chatId, cursor) >= last) {
+                    return { pages, complete: true, reachedStart: false };
+                }
+                if (pages >= maxPages)
+                    return { pages, complete: false, reachedStart: false };
+                if (pages > 0)
+                    await pause();
+                const page = await this.#history(chatId, { from: cursor, backward: BACKUP_PAGE, forward: 0 }, { reactions: false });
+                pages += 1;
+                const oldest = page[0] ? Date.parse(page[0].timestamp) : cursor;
+                onPage?.({ number: pages, count: page.length, oldest: page[0]?.timestamp ?? null });
+                if (page.length < BACKUP_PAGE) {
+                    if (page.length > 0 || pages > 1)
+                        cache.messages.reachedStart(chatId, oldest);
+                    return { pages, complete: true, reachedStart: true };
+                }
+                if (oldest >= cursor) {
+                    throw new CliError("invalid_response", `MAX answered page ${pages} with nothing older than it was asked for`);
+                }
+                cursor = oldest;
+            }
+        },
         /**
          * **One message and a window either side of it**, oldest first, the one asked for marked
          * `anchor: true`.
@@ -631,20 +700,30 @@ export class MaxClient {
             if (options.at !== undefined && options.cid !== undefined) {
                 throw new CliError("validation_error", `--cid repeats an ambiguous send, which is not safe for a scheduled one — \`max messages scheduled ${chatId}\` shows whether it is queued`);
             }
+            // Read before the guard holds a place under the limit: a file that is refused sends nothing.
+            const files = await Promise.all((options.files ?? []).map(async (path) => ({
+                path,
+                bytes: await readUpload(path, { anyFile: options.anyFile === true }),
+                photo: isImage(path),
+            })));
+            // Measured 2026-09-24: photos share a message, but a file with anything beside it is refused `proto.payload`.
+            if (files.some((file) => !file.photo) && files.length > 1) {
+                throw new CliError("validation_error", "a file goes in a message of its own — photos can share one; send them apart");
+            }
             // Before connecting: a refused send never opens a socket when the chat was given as an id.
             try {
-                this.#sends?.check(chatId);
+                this.#sends?.check({
+                    chatId,
+                    kind: "message",
+                    ...(options.cid === undefined ? {} : { cid: options.cid }),
+                    ...(options.at === undefined ? {} : { scheduledFor: new Date(options.at).toISOString() }),
+                });
             }
             catch (error) {
                 this.#sends?.record({ chatId, outcome: "refused", errorCode: asCliError(error).code });
                 throw error;
             }
             const cid = options.cid ?? this.#nextCid();
-            const files = await Promise.all((options.files ?? []).map(async (path) => ({ path, bytes: await readUpload(path), photo: isImage(path) })));
-            // Measured 2026-09-24: photos share a message, but a file with anything beside it is refused `proto.payload`.
-            if (files.some((file) => !file.photo) && files.length > 1) {
-                throw new CliError("validation_error", "a file goes in a message of its own — photos can share one; send them apart");
-            }
             const attachments = files.map(({ bytes, photo }) => ({
                 kind: photo ? "photo" : "file",
                 bytes: bytes.length,
@@ -687,7 +766,7 @@ export class MaxClient {
         edit: async (chatId, messageId, text, { markdown = false } = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot edit");
-            this.#guard(chatId, "edit", messageId);
+            this.#guard({ chatId, kind: "edit" }, messageId);
             try {
                 await this.#connectOnce();
                 const lookup = { names: namesFrom(this.#session().contacts), ...viewer(this.#store) };
@@ -729,7 +808,7 @@ export class MaxClient {
         forward: async (fromChatId, messageId, toChatId, options = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot forward");
-            this.#guard(toChatId, "forward");
+            this.#guard({ chatId: toChatId, kind: "forward" });
             const cid = options.cid ?? this.#nextCid();
             try {
                 const sent = await this.#deliver(toChatId, "", cid, {
@@ -767,7 +846,7 @@ export class MaxClient {
                 throw new CliError("validation_error", `${messageIds.length} messages at once — at most ${DELETE_AT_ONCE} per call, so MAX sees deletions spread out`);
             }
             const count = messageIds.length;
-            this.#guard(chatId, "delete", undefined, count);
+            this.#guard({ chatId, kind: "delete", count });
             try {
                 await this.#connectOnce();
                 await this.#wire.messages.delete({ chatId, messageIds, forMe: !forEveryone });
@@ -798,7 +877,7 @@ export class MaxClient {
         pin: async (chatId, messageId, { notify = false } = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot pin");
-            this.#guard(chatId, "pin", messageId ?? undefined);
+            this.#guard({ chatId, kind: "pin", notify }, messageId ?? undefined);
             try {
                 await this.#connectOnce();
                 const known = asArray(this.#session().chats).find((raw) => asId(raw.id) === chatId);
@@ -806,11 +885,11 @@ export class MaxClient {
                     throw new CliError("validation_error", `chat ${chatId} is a personal chat — MAX pins only in groups and channels`);
                 }
                 await this.#wire.chats.update({ chatId, pinMessageId: messageId ?? "0", notifyPin: notify });
-                this.#sends?.record({ chatId, kind: "pin", outcome: "sent", ...(messageId ? { messageId } : {}) });
+                this.#sends?.record({ chatId, kind: "pin", notify, outcome: "sent", ...(messageId ? { messageId } : {}) });
                 return { chatId, pinned: messageId };
             }
             catch (error) {
-                this.#sends?.record({ chatId, kind: "pin", outcome: "failed", errorCode: asCliError(error).code });
+                this.#sends?.record({ chatId, kind: "pin", notify, outcome: "failed", errorCode: asCliError(error).code });
                 throw error;
             }
         },
@@ -876,7 +955,7 @@ export class MaxClient {
                 if (theirs.length > 0)
                     found.push({ id, title, kind, unreadCount, messages: theirs, more: count > limit });
             }
-            return { mode: "unread", chats: found, skipped, partial: !this.#cache && chats.length >= LOGIN_CHATS };
+            return { mode: "unread", chats: found, skipped, partial: !this.#cache && this.#chatsCut };
         },
         /**
          * Other people's messages in every chat that changed after `since`.
@@ -916,7 +995,7 @@ export class MaxClient {
                 until: new Date(until).toISOString(),
                 chats: found,
                 skipped,
-                partial: !this.#cache && chats.length >= LOGIN_CHATS && changed.length === chats.length,
+                partial: !this.#cache && this.#chatsCut && changed.length === chats.length,
             };
         },
     };
@@ -929,7 +1008,7 @@ export class MaxClient {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot react");
         try {
-            this.#sends?.check(chatId, "reaction");
+            this.#sends?.check({ chatId, kind: "reaction" });
         }
         catch (error) {
             this.#sends?.record({ chatId, kind: "reaction", outcome: "refused", errorCode: asCliError(error).code });
@@ -947,14 +1026,16 @@ export class MaxClient {
         }
     }
     /** Asks the send guard, and writes a refusal to the send journal before passing it on. */
-    #guard(chatId, kind, messageId, count) {
+    #guard(request, messageId) {
+        const { chatId, kind, notify } = request;
         try {
-            this.#sends?.check(chatId, kind, undefined, count);
+            this.#sends?.check(request);
         }
         catch (error) {
             this.#sends?.record({
                 chatId,
-                kind,
+                ...(kind ? { kind } : {}),
+                ...(notify === undefined ? {} : { notify }),
                 outcome: "refused",
                 ...(messageId ? { messageId } : {}),
                 errorCode: asCliError(error).code,
@@ -973,7 +1054,6 @@ export class MaxClient {
             forward: 0,
             backward: 1,
             getMessages: true,
-            interactive: false,
         });
         const found = asArray(answer.messages)
             .map((raw) => record(raw) ?? {})
@@ -1035,11 +1115,65 @@ export class MaxClient {
             await this.#connectOnce();
             await this.#wire.session.ping({ interactive: false });
         },
+        /**
+         * What a hidden web tab reports once, 20 s after it opened: the chat list, shown at `at`.
+         * `sessionId` is when the tab's connection began, and it survives the tab's reconnects.
+         */
+        /**
+         * **The reads a web tab sends after every login** (`MAX-52`, recorded 2026-09-25), in its order
+         * and all at once, as it sends them: folders, banners, call history, then the four asset sets.
+         * Each carries the sync value its previous answer returned — 0 the first time — and the answers
+         * are kept only for those. `max serve` alone sends them; a one-shot command never did.
+         */
+        readLikeTab: async (sync) => {
+            await this.#connectOnce();
+            const folders = this.#wire.folders.list({ folderSync: sync.folders });
+            const banners = this.#wire.banners.list({ bannersSync: 0 });
+            const calls = this.#wire.calls.history({ callHistorySync: sync.calls });
+            const assets = ASSET_TYPES.map((type) => this.#wire.assets.update({ type, sync: sync.assets[type] ?? 0 }));
+            const [folderAnswer, , callAnswer, answers] = await Promise.all([folders, banners, calls, Promise.all(assets)]);
+            return {
+                folders: numberOr(folderAnswer.folderSync, sync.folders),
+                calls: numberOr(callAnswer.callHistorySync, sync.calls),
+                assets: Object.fromEntries(ASSET_TYPES.map((type, at) => [type, numberOr(answers[at]?.sync, sync.assets[type] ?? 0)])),
+            };
+        },
+        chatListShown: async ({ at, sessionId }) => {
+            const viewerId = this.#store.readState().viewerId;
+            if (!viewerId)
+                return;
+            await this.#connectOnce();
+            await this.#wire.session.log({
+                events: [
+                    {
+                        type: "NAV",
+                        userId: viewerId,
+                        time: at,
+                        sessionId,
+                        event: "GO",
+                        params: { action_id: 1, screen_to: 150, prev_time: 0, source_id: viewerId },
+                    },
+                ],
+            });
+        },
         /**
          * The login this connection holds, kept current from what MAX pushes — `max serve` hands it to
          * a command as that command's own login.
          */
         snapshot: () => this.#session(),
+        /**
+         * What the next login on a new connection sends to pick up where this one is (`MAX-51`):
+         * `undefined` when this login lacks what that needs, and the next one is then a full login.
+         */
+        resumeFrom: () => {
+            const login = this.#login;
+            const configHash = record(login?.config)?.hash;
+            if (!login || typeof login.time !== "number" || typeof configHash !== "string")
+                return undefined;
+            const chats = asArray(login.chats).map((chat) => record(chat) ?? {});
+            const chatsSync = Math.max(0, ...chats.map(eventTime));
+            return { login: { lastLogin: login.time, chatsSync, configHash }, chats };
+        },
         /**
          * Keeps the snapshot current from one push. **`false` means it can no longer be trusted** and
          * the server stops handing it out until it has logged in again. What web.max.ru does with each
@@ -1082,6 +1216,9 @@ export class MaxClient {
                 const at = chats.findIndex((candidate) => asId(candidate.id) === id);
                 if (at >= 0)
                     chats[at] = changed;
+                // Past this, a new login rebuilds the list rather than pushes growing it without end.
+                else if (chats.length >= LIVE_CHATS)
+                    return false;
                 else
                     chats.push(changed);
                 this.#session().chats = chats;
@@ -1101,17 +1238,47 @@ export class MaxClient {
          */
         message: async (opcode, payload) => {
             const raw = record(payload.message);
+            if (opcode !== NEW_MESSAGE || !raw || raw.status !== undefined)
+                return undefined;
+            return this.#messageHit(payload);
+        },
+        /** An edit, a deletion or a reaction pushed by MAX, or `undefined` for anything else. */
+        change: async (opcode, payload) => {
             const chatId = asId(payload.chatId);
-            if (opcode !== NEW_MESSAGE || !raw || chatId === undefined)
+            if (chatId === undefined)
                 return undefined;
-            const session = this.#session();
-            const [message] = await this.#nameSenders([
-                toMessage(raw, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) }),
-            ]);
-            const chat = (await this.chats.list()).items.find((candidate) => candidate.id === chatId);
-            return message && { ...message, chatTitle: chat?.title ?? null };
+            const raw = record(payload.message);
+            if (opcode === NEW_MESSAGE && raw?.status === "EDITED") {
+                const message = await this.#messageHit(payload);
+                return message && { event: "edit", message };
+            }
+            const messageId = asId(opcode === NEW_MESSAGE ? raw?.id : payload.messageId);
+            if (messageId === undefined)
+                return undefined;
+            if (opcode === NEW_MESSAGE && raw?.status === "REMOVED") {
+                return { event: "delete", chatId, chatTitle: await this.#chatTitle(chatId), messageId };
+            }
+            if (opcode === REACTIONS_CHANGED) {
+                const reactions = toReactions(payload);
+                return { event: "reaction", chatId, chatTitle: await this.#chatTitle(chatId), messageId, reactions };
+            }
+            return undefined;
         },
     };
+    async #messageHit(payload) {
+        const raw = record(payload.message);
+        const chatId = asId(payload.chatId);
+        if (!raw || chatId === undefined)
+            return undefined;
+        const session = this.#session();
+        const [message] = await this.#nameSenders([
+            toMessage(raw, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) }),
+        ]);
+        return message && { ...message, chatTitle: await this.#chatTitle(chatId) };
+    }
+    async #chatTitle(chatId) {
+        return (await this.chats.list()).items.find((candidate) => candidate.id === chatId)?.title ?? null;
+    }
     /**
      * Opens the connection and logs in with the stored token, or with one offered for trial.
      *
@@ -1124,11 +1291,21 @@ export class MaxClient {
     async connect({ token: candidate } = {}) {
         const token = candidate ?? this.#store.readToken();
         if (!token) {
+            const profile = this.#store.profile;
+            // cli-core swallows a keyring that will not open, so the state file is the only witness: a
+            // profile that has logged in lost its keyring, not its session, and another login would
+            // register one more device for nothing (MAX-50, measured from cron 2026-09-25).
+            if (this.#store.hasLoggedIn()) {
+                throw new CliError("authentication_error", `no token found for profile "${profile}", although it has logged in on this machine — ` +
+                    `the keyring is probably out of reach (cron, ssh: set XDG_RUNTIME_DIR); ` +
+                    `\`max ${asFirstWord(profile)}doctor\` shows it. Log in again only if the token was removed`);
+            }
             // The fix has to carry the profile, or it logs the wrong one in: a name nobody has logged
             // in under is the ordinary shape of this failure now that the first word is the profile.
-            throw new CliError("authentication_error", `no session for profile "${this.#store.profile}" — run \`max ${asFirstWord(this.#store.profile)}session start\``);
+            throw new CliError("authentication_error", `no session for profile "${profile}" — run \`max ${asFirstWord(profile)}session start\``);
         }
         const state = this.#store.readState();
+        refuseWhilePaused(state);
         const sync = this.#fullLogin ? undefined : this.#cache?.syncMarker();
         try {
             await this.#connection.open();
@@ -1136,10 +1313,17 @@ export class MaxClient {
                 token,
                 deviceId: state.deviceId,
                 ...(sync === undefined ? {} : { sync }),
+                ...(this.#resume ? { resume: this.#resume.login } : {}),
             });
         }
         catch (error) {
-            throw asCliError(error);
+            const failure = asCliError(error);
+            if (failure.code !== "rate_limited")
+                throw failure;
+            const paused = withLoginRefused(state);
+            this.#store.writeState(paused);
+            throw new CliError("rate_limited", `${failure.message} — this profile will not log in again before ${paused.loginPausedUntil}; ` +
+                "logging in sooner is what keeps an account locked");
         }
         const viewerId = toProfile(record(this.#login.profile) ?? {}).id;
         // **Before `writeState`**, so a login we are about to refuse does not count itself or move
@@ -1151,14 +1335,59 @@ export class MaxClient {
                 `run \`max ${asFirstWord(this.#store.profile)}session end\` first if you meant to switch`);
         }
         this.#store.writeState({
-            ...state,
+            ...withoutLoginPause(state),
             ...(viewerId ? { viewerId } : {}),
             logins: state.logins + 1,
             lastLoginAt: new Date().toISOString(),
         });
         this.#keepRotatedToken(token);
+        // `max serve` hands this login to any process that asks its socket; none of them needs the token.
+        const { token: _, ...withoutToken } = this.#login;
+        this.#login = withoutToken;
+        if (this.#resume)
+            this.#mergeChanged(this.#resume.chats);
+        else
+            await this.#readRestOfChats();
         this.#mergeLogin(viewerId);
     }
+    /**
+     * A login with `chatsSync` answers only the chats that changed since it (measured 2026-09-20), so
+     * they go over the list the previous connection held: same id replaced, the rest kept, newest first.
+     */
+    #mergeChanged(before) {
+        const session = this.#session();
+        const changed = asArray(session.chats);
+        const ids = new Set(changed.map((chat) => asId(record(chat)?.id)));
+        const kept = before.filter((chat) => !ids.has(asId(chat.id)));
+        session.chats = [...changed, ...kept].sort((a, b) => eventTime(b) - eventTime(a));
+    }
+    /**
+     * **The chats LOGIN left out, as the web tab reads them:** one `CHATS_LIST` from the last-activity
+     * time of the oldest chat it sent, 2.3 s after the login answer (capture 2026-09-25). Measured the
+     * same day: that answers exactly the chats after it, and one answer held 26. Only one request,
+     * because the tab sends only one — `#chatsCut` says when that may not have been all.
+     *
+     * A refusal leaves the login's chats as they were: a shorter list beats a failed command.
+     */
+    async #readRestOfChats() {
+        this.#chatsCut = false;
+        const session = this.#session();
+        const chats = asArray(session.chats);
+        const marker = record(chats.at(-1))?.lastEventTime;
+        if (chats.length < LOGIN_CHATS || (typeof marker !== "number" && typeof marker !== "bigint"))
+            return;
+        try {
+            const answer = await this.#wire.chats.list({ marker: Number(marker) });
+            const known = new Set(chats.map((chat) => asId(record(chat)?.id)));
+            const rest = asArray(answer.chats).filter((chat) => !known.has(asId(record(chat)?.id)));
+            session.chats = [...chats, ...rest];
+            this.#chatsCut = rest.length >= CHATS_PAGE_SEEN;
+        }
+        catch (error) {
+            this.#chatsCut = true;
+            this.#warnAbout("chats_partial", `only the newest ${chats.length} chats were read: ${reasonOf(error)}`);
+        }
+    }
     /**
      * **MAX offers a replacement for a credential that has aged, and until 2026-09-22 we threw it
      * away** — measured, `pnpm probe:token`. Presenting a token pasted months earlier answers with a
@@ -1184,11 +1413,15 @@ export class MaxClient {
         const rotated = this.#session().token;
         if (typeof rotated !== "string" || rotated === "" || rotated === sent)
             return;
+        if (this.#fromEnvironment()) {
+            this.#warnAbout("token_not_saved", "MAX refreshed the session; the fresh token was not saved, because the one in use came from MAX_TOKEN");
+            return;
+        }
         try {
             this.#store.writeToken(rotated);
         }
         catch (error) {
-            this.#warn(`the refreshed session could not be saved, so the previous one is still in use: ${reasonOf(error)}`);
+            this.#warnAbout("token_not_saved", `the refreshed session could not be saved, so the previous one is still in use: ${reasonOf(error)}`);
         }
     }
     /**
@@ -1234,7 +1467,7 @@ export class MaxClient {
             });
         }
         catch (error) {
-            this.#warn(`the local record did not take this login, so nothing was kept from it: ${reasonOf(error)}`);
+            this.#warnAbout("cache_not_written", `the local record did not take this login, so nothing was kept from it: ${reasonOf(error)}`);
         }
     }
     /** One page of contacts out of the store — the same query online and offline. */
@@ -1270,7 +1503,10 @@ export class MaxClient {
      * no login, and is over before a socket would have finished its handshake. `connect()` stays
      * public for the one command that must reach MAX to mean anything — starting a session.
      */
-    /** `interactive: false` and never `CHAT_MARK`: reading history must not mark anything read (§19). */
+    /**
+     * Never `CHAT_MARK`: reading history must not mark anything read (§19). Without `interactive`, as
+     * the web client asks — measured 2026-09-25 on a channel with 8 unread: reading moved nothing.
+     */
     async #history(chatId, window, { reactions = true } = {}) {
         await this.#connectOnce();
         const session = this.#session();
@@ -1278,9 +1514,6 @@ export class MaxClient {
             chatId,
             ...window,
             getMessages: true,
-            // The web client leaves this out. What MAX assumes when it is missing was not measured on a
-            // chat with unread messages, and a guess wrong here marks the owner's chats read.
-            interactive: false,
         });
         const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
         const messages = await this.#nameSenders(asArray(answer.messages).map((raw) => toMessage(raw, chatId, lookup)));
@@ -1300,7 +1533,7 @@ export class MaxClient {
             });
         }
         catch (error) {
-            this.#warn(`reactions are not shown: they could not be read (${reasonOf(error)})`);
+            this.#warnAbout("reactions_unread", `reactions are not shown: they could not be read (${reasonOf(error)})`);
             return messages;
         }
     }
@@ -1332,7 +1565,7 @@ export class MaxClient {
             }
         }
         catch (error) {
-            this.#warn(`some senders are shown by id: their names could not be looked up (${reasonOf(error)})`);
+            this.#warnAbout("names_unread", `some senders are shown by id: their names could not be looked up (${reasonOf(error)})`);
         }
         if (fetched.length > 0)
             this.#cache?.people.upsert(fetched, "info");
@@ -1397,6 +1630,7 @@ export class MaxClient {
                 durationMs: Math.round(performance.now() - started),
                 outcome: "error",
                 errorCode: failure.code,
+                ...(typeof failure.details.maxError === "string" ? { maxError: failure.details.maxError } : {}),
             });
             throw failure;
         }
@@ -1412,9 +1646,23 @@ export class MaxClient {
         });
         const note = checkResponse(operation, answer);
         if (note)
-            this.#warn(note);
+            this.#warnAbout("response_shape", note, { operation: operation.name, detail: note });
         return answer;
     }
+    /** The sentence to the person, and only the code to the log (`WarningEvent`). */
+    /** A token from `MAX_TOKEN` belongs to whoever set it: nothing MAX hands back replaces what is stored. */
+    #fromEnvironment() {
+        try {
+            return this.#store.tokenSource() === "environment";
+        }
+        catch {
+            return false;
+        }
+    }
+    #warnAbout(code, message, extra = {}) {
+        this.#warn(message);
+        this.#emit({ event: "warning", code, ...extra });
+    }
     /** A diagnostic that breaks the command it was describing is worse than no diagnostic. */
     #emit(event) {
         try {
@@ -1472,11 +1720,11 @@ export class MaxClient {
      * Every change to a chat, guarded and journalled as a send is. Never retried: none of these is
      * measured to be safe to repeat, and a repeated `create` is a second group.
      */
-    async #changeChat(chatId, action, act) {
+    async #changeChat(chatId, action, act, personIds) {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot change a chat");
         try {
-            this.#sends?.check(chatId, "chat", action);
+            this.#sends?.check({ chatId, kind: "chat", action, ...(personIds ? { personIds } : {}) });
         }
         catch (error) {
             this.#sends?.record({ chatId, kind: "chat", action, outcome: "refused", errorCode: asCliError(error).code });
@@ -1508,8 +1756,8 @@ export class MaxClient {
     }
     async #updateMembers(reference, people, action, change) {
         const chatId = await this.chats.resolve(reference);
+        const userIds = await this.#personIds(people);
         return this.#changeChat(chatId, action, async () => {
-            const userIds = await this.#personIds(people);
             const answer = await this.#wire.chats.updateMembers({ chatId, userIds, ...change });
             const chat = record(answer.chat);
             return {
@@ -1517,7 +1765,7 @@ export class MaxClient {
                 people: userIds.length,
                 result: { chatId, action, people: userIds, chat: chat ? toGroupCard(chat) : null },
             };
-        });
+        }, action === "members.add" ? userIds : undefined);
     }
     /** An id goes as given; a name is looked up in the store, and an ambiguous one is refused. */
     async #personIds(references) {
@@ -1604,7 +1852,7 @@ export class MaxClient {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot change the account");
         try {
-            this.#sends?.check(null, "account", action);
+            this.#sends?.check({ chatId: null, kind: "account", action });
         }
         catch (error) {
             this.#sends?.record({
@@ -1692,6 +1940,8 @@ export const ADMIN_RIGHTS = {
     delete: 1024,
 };
 /** PyMax asks for this many; paging join requests is not known. */
+/** The most chats `max serve` holds from pushes before it logs in again instead. */
+const LIVE_CHATS = 10_000;
 const JOIN_REQUESTS = 100;
 /**
  * A private link goes as `join/<token>`, whatever came before it, as PyMax sends it and as
@@ -1736,6 +1986,8 @@ const checkedQuery = (query) => {
  * names itself rather than as a wrong answer.
  */
 const CONTACT_INFO_BATCH = 100;
+/** The most chats one `CHATS_LIST` answer was seen to hold (26, 2026-09-25). A page that full may have been cut. */
+const CHATS_PAGE_SEEN = 26;
 /**
  * When a message was sent, read from its id: **`id >> 16` is the send time in milliseconds**, the
  * low 16 bits a counter. Measured 2026-09-22 on three messages across two days, exact every time.
@@ -1753,10 +2005,20 @@ export const timeOfMessageId = (id) => {
  * account rarely has that many chats change between two checks, and the rest are named, not lost.
  */
 const INBOX_CHATS = 20;
+export const FIRST_TAB_SYNC = { folders: 0, calls: 0, assets: {} };
+const numberOr = (value, fallback) => (typeof value === "number" ? value : fallback);
+const eventTime = (chat) => {
+    const time = record(chat)?.lastEventTime;
+    return typeof time === "number" ? time : 0;
+};
+/** Reactions on a message changed; PyMax calls it `NOTIF_MSG_REACTIONS_CHANGED` (tab recording 2026-09-25). */
+const REACTIONS_CHANGED = 155;
 /** MAX pushes this when a message arrives in any chat. PyMax calls it `NOTIF_MESSAGE`. */
 const NEW_MESSAGE = 128;
 /** Bounded so that deleting a long history is many spread-out calls, never one sweep (`MAX-47`). */
 export const DELETE_AT_ONCE = 10;
+/** What web.max.ru asks for per page when history is scrolled up (`RES-9`). */
+export const BACKUP_PAGE = 30;
 /** Read up to a point — by us on another device, or by somebody else. */
 const READ_MARK = 130;
 /** A chat changed; MAX sends it whole. */
@@ -1838,17 +2100,38 @@ const asCliError = (error) => {
     if (error instanceof CliError)
         return error;
     if (error instanceof ProtocolError) {
-        const text = error.message.toLowerCase();
-        if (text.includes("token") || text.includes("auth")) {
-            return new CliError("authentication_error", `${error.message} — the session may have expired; run \`max session start\``);
-        }
-        return new CliError("provider_error", error.message, { operation: String(error.opcode) });
+        const key = maxErrorKey(record(error.payload)?.error);
+        const refused = asRefusal(error);
+        return key === undefined
+            ? refused
+            : new CliError(refused.code, refused.message, { ...refused.details, maxError: key });
     }
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("did not answer"))
         return new CliError("timeout", message);
     return new CliError("network_error", message);
 };
+const asRefusal = (error) => {
+    const text = error.message.toLowerCase();
+    // First: "too many auth attempts" is a limit, not a bad token. The words are claims —
+    // `error.limit.violate` from PyMax #106, `rate_limit_exceeded` from GREEN-API — never measured here.
+    if (LIMIT_WORDS.some((words) => text.includes(words))) {
+        return new CliError("rate_limited", error.message, { operation: String(error.opcode) });
+    }
+    if (text.includes("token") || text.includes("auth")) {
+        return new CliError("authentication_error", `${error.message} — the session may have expired; run \`max session start\``);
+    }
+    return new CliError("provider_error", error.message, { operation: String(error.opcode) });
+};
+const LIMIT_WORDS = ["limit.violate", "rate_limit", "rate limit", "too many", "слишком много"];
+/** Before any request: a login inside the pause is one more attempt MAX counts (`MAX-38`). */
+export const refuseWhilePaused = (state) => {
+    const until = loginPausedUntil(state);
+    if (until === undefined)
+        return;
+    throw new CliError("rate_limited", `MAX refused this profile's last login for too many attempts; it will not try again before ${until} — ` +
+        "logging in sooner is what keeps an account locked");
+};
 const ownNames = (profile) => {
     const contact = record(profile.contact) ?? profile;
     const names = asArray(contact.names);
@@ -1872,10 +2155,15 @@ export const wirePhone = (typed) => {
     return `+${digits}`;
 };
 /** 21 characters were refused as too long and 15 were taken (measured 2026-09-24); MAX draws the line. */
+/** Measured 2026-09-25 (`MAX-57`, ASCII): 20 characters taken, 21 refused with `folder.validation.title.too-long`. */
+const FOLDER_TITLE_MAX = 20;
 const folderTitle = (title) => {
     const trimmed = title.trim();
     if (trimmed === "")
         throw new CliError("validation_error", "a folder needs a title");
+    if ([...trimmed].length > FOLDER_TITLE_MAX) {
+        throw new CliError("validation_error", `a folder title is at most ${FOLDER_TITLE_MAX} characters in MAX`);
+    }
     return trimmed;
 };
 const pickFolder = (reference, folders) => {