@wirecat/cli-core 0.575.0 → 0.576.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ shape of this file.
 
 ## Unreleased
 
+## 0.576.0 — 05.11.2026
+
+### Added
+
+- **`review --holder` gives an agent the bulk mail that is not surely a newsletter.** Shops, banks and site forms put
+  List-Unsubscribe on orders, invoices and lead forms too, and the holder read left all of it out. Now
+  `newsletterSorter` scores each bulk email by words in its subject and first lines (Russian, English, Spanish), its
+  sender's address, an emoji or an unsubscribe link: a newsletter is left out and counted under `missing` as
+  `newsletter`; an order word in the subject, an order's or a request's number, or a reply keeps it. A kept email
+  comes after the other mail, as its subject and first lines, with `email.bulk: true` and `email.excerpt_only: true`;
+  `messages show <ref>` reads it whole. At most 30 excerpts a read; the read then ends early and the next gives the
+  rest. `mailWaiting` and `advancePastSkipped` count and stop at excerpts the same way. A host sets it from its config
+  file: `MAIL_BULK_SETTINGS` (`mail_bulk_excerpts`, `mail_bulk_excerpts_per_read`, `mail_bulk_excerpt_chars`,
+  `mail_bulk_newsletter_score`, `mail_bulk_newsletter_words`, `mail_bulk_newsletter_senders`, `mail_bulk_order_words`),
+  read by `bulkTriageOf` into `MailReads.bulkTriage`, and passed to `mailWaiting` and `advancePastSkipped` as their
+  new last argument; without it the defaults apply.
+
 ## 0.575.0 — 05.11.2026
 
 ### Added

package/dist/mail/cli/bulk-settings.d.ts

@@ -0,0 +1,6 @@
+import type { DeclaredSetting } from "../../cli/setting-defaults.js";
+import { type BulkTriage } from "../newsletter.js";
+/** The bulk-mail settings a host that mounts `review --holder` writes into its config file's top level (WC-CMD-30). */
+export declare const MAIL_BULK_SETTINGS: readonly DeclaredSetting[];
+/** `MAIL_BULK_SETTINGS` as the config file gives them; a missing or unusable value is left to the default. */
+export declare const bulkTriageOf: (config: Record<string, unknown>) => BulkTriage;

package/dist/mail/cli/bulk-settings.js

@@ -0,0 +1,65 @@
+import { BULK_TRIAGE_DEFAULTS, NEWSLETTER_DEFAULTS, NEWSLETTER_SENDERS, NEWSLETTER_WORDS, ORDER_WORDS, } from "../newsletter.js";
+const listed = (words) => words.join(", ");
+/** The bulk-mail settings a host that mounts `review --holder` writes into its config file's top level (WC-CMD-30). */
+export const MAIL_BULK_SETTINGS = [
+    {
+        key: "mail_bulk_excerpts",
+        default: BULK_TRIAGE_DEFAULTS.excerpts,
+        description: "review --holder gives an agent bulk mail that is not surely a newsletter as its subject and first lines; " +
+            "false leaves all bulk mail out",
+    },
+    {
+        key: "mail_bulk_excerpts_per_read",
+        default: BULK_TRIAGE_DEFAULTS.perRead,
+        description: "the most bulk excerpts one review --holder gives; the rest come with the next read",
+    },
+    {
+        key: "mail_bulk_excerpt_chars",
+        default: NEWSLETTER_DEFAULTS.excerptChars,
+        description: "how many characters of a bulk email's own text an excerpt shows",
+    },
+    {
+        key: "mail_bulk_newsletter_score",
+        default: NEWSLETTER_DEFAULTS.threshold,
+        description: "bulk mail scoring this or more is left out as a newsletter: a newsletter word counts 2 in the subject, 1 in " +
+            "the first lines, a newsletter's address 2, an emoji in the subject 1, an unsubscribe link at the top 1, " +
+            "an order word in the first lines -2",
+    },
+    {
+        key: "mail_bulk_newsletter_words",
+        default: listed(NEWSLETTER_WORDS),
+        description: "comma-separated words that say advertising; each matches at the start of a word, any case",
+    },
+    {
+        key: "mail_bulk_newsletter_senders",
+        default: listed(NEWSLETTER_SENDERS),
+        description: "comma-separated parts of a sender's address (news, digest) or domains (substack.com) of newsletters",
+    },
+    {
+        key: "mail_bulk_order_words",
+        default: listed(ORDER_WORDS),
+        description: "comma-separated words of orders, invoices and requests: one in the subject keeps a bulk email for the agent",
+    },
+];
+const wordsOf = (value) => typeof value === "string"
+    ? value
+        .split(",")
+        .map((word) => word.trim())
+        .filter(Boolean)
+    : undefined;
+const countOf = (value, least) => typeof value === "number" && Number.isSafeInteger(value) && value >= least ? value : undefined;
+/** `MAIL_BULK_SETTINGS` as the config file gives them; a missing or unusable value is left to the default. */
+export const bulkTriageOf = (config) => {
+    const { cues } = BULK_TRIAGE_DEFAULTS;
+    return {
+        excerpts: typeof config.mail_bulk_excerpts === "boolean" ? config.mail_bulk_excerpts : BULK_TRIAGE_DEFAULTS.excerpts,
+        perRead: countOf(config.mail_bulk_excerpts_per_read, 1) ?? BULK_TRIAGE_DEFAULTS.perRead,
+        cues: {
+            threshold: countOf(config.mail_bulk_newsletter_score, 1) ?? cues.threshold,
+            excerptChars: countOf(config.mail_bulk_excerpt_chars, 40) ?? cues.excerptChars,
+            newsletterWords: wordsOf(config.mail_bulk_newsletter_words) ?? cues.newsletterWords,
+            newsletterSenders: wordsOf(config.mail_bulk_newsletter_senders) ?? cues.newsletterSenders,
+            orderWords: wordsOf(config.mail_bulk_order_words) ?? cues.orderWords,
+        },
+    };
+};

package/dist/mail/cli/index.d.ts

@@ -1,7 +1,9 @@
 import { Command } from "commander";
+import type { BulkTriage } from "../../mail/newsletter.js";
 import { type MailServerAccess } from "../../mail/server-search.js";
 import type { AppIdentity } from "../../ports/app.js";
 import { type AccountKey, type MessageStore } from "../../store/store.js";
+export { bulkTriageOf, MAIL_BULK_SETTINGS } from "./bulk-settings.js";
 export { mailMark, markItem, markText } from "./marks.js";
 export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS, mailReviewSteps } from "./review.js";
 /**
@@ -37,6 +39,8 @@ export interface MailReads {
      * With it, `messages show` reads an email whose attachment a sync's policy left unread before it answers.
      */
     whole?: (command: Command, store: MessageStore, mailbox: AccountKey, emailId: string) => Promise<void>;
+    /** How `review --holder` treats bulk mail, from the host's config file (`MAIL_BULK_SETTINGS`); defaults without it. */
+    bulkTriage?: (command: Command) => BulkTriage;
 }
 export declare const THREAD_QUERY: {
     readonly entity: "mail_thread";

package/dist/mail/cli/index.js

@@ -21,6 +21,7 @@ import { sourceKey } from "../../services/server-search.js";
 import { queryFilter, THREAD_COLUMNS } from "../../store/store.js";
 import { acknowledgeCommand } from "./marks.js";
 import { mailReviewCommand } from "./review.js";
+export { bulkTriageOf, MAIL_BULK_SETTINGS } from "./bulk-settings.js";
 export { mailMark, markItem, markText } from "./marks.js";
 export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS, mailReviewSteps } from "./review.js";
 /** A locked or broken store must fail the command, not read as "nothing stored yet". */

package/dist/mail/cli/review.js

@@ -19,6 +19,7 @@ import { formatReference } from "../../domain/references.js";
 import { AGENDA_DEFAULTS } from "../../services/agenda.js";
 import { REVIEW_DAYS, reviewStart } from "../../services/inbox.js";
 import { readPastMark } from "../marks.js";
+import { BULK_TRIAGE_DEFAULTS } from "../newsletter.js";
 import { hitText } from "../read.js";
 import { OWED_DAYS, REVIEW_THREADS, reviewMail } from "../review.js";
 const DAY = 86_400_000;
@@ -74,9 +75,10 @@ const waitingHours = (value) => value === true ? AGENDA_DEFAULTS.waiting / 3_600
 const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 /** A file name for the mailbox's points: they describe the mailbox, whichever profile reads it. */
 const pointsName = (mailbox) => encodeURIComponent(mailbox.account);
-const markText = (marks) => {
+const markText = (marks, excerptOnly = false) => {
     const said = [
-        marks?.bulk ? "bulk" : "",
+        marks?.bulk || excerptOnly ? "bulk" : "",
+        excerptOnly ? "excerpt only" : "",
         marks?.listId ? `list ${marks.listId}` : "",
         marks?.ruleId ? `rule ${marks.ruleId}` : "",
     ];
@@ -84,9 +86,11 @@ const markText = (marks) => {
     return shown ? `\n  [${shown}]` : "";
 };
 const reviewAnswer = (found, mailbox, fresh, step) => {
+    // Excerpts come after the mail written to the owner, so an agent with a budget reads that first.
     const read = found.chats
         .flatMap((chat) => chat.messages.map((message) => ({ ...message, chatTitle: chat.title })))
-        .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+        .sort((a, b) => Number(a.excerptOnly ?? false) - Number(b.excerptOnly ?? false) ||
+        Date.parse(a.timestamp) - Date.parse(b.timestamp));
     const cut = found.chats.filter((chat) => chat.more);
     const ref = (thread) => formatReference({ type: "chat", ...mailbox, chat: thread });
     const turns = found.unanswered !== undefined || found.waiting !== undefined;
@@ -126,7 +130,8 @@ const reviewAnswer = (found, mailbox, fresh, step) => {
             ...summaryOf(message, mailbox),
             email: {
                 ...messageItem(message, mailbox).email,
-                bulk: message.marks?.bulk ?? false,
+                bulk: (message.marks?.bulk ?? false) || message.excerptOnly === true,
+                ...(message.excerptOnly ? { excerpt_only: true } : {}),
                 list_id: message.marks?.listId ?? null,
                 rule_id: message.marks?.ruleId ?? null,
                 ...(message.marks
@@ -150,16 +155,22 @@ const holderReview = async (command, mail, holder, query) => {
     const { unanswered, waiting } = command.opts();
     if (typedQuery(query).trim() || unanswered !== undefined || waiting !== undefined)
         throw new CliError("validation_error", "--holder reads past its own mark — not with a query, --unanswered or --waiting");
+    const triage = mail.bulkTriage?.(command) ?? BULK_TRIAGE_DEFAULTS;
     const { read, mailbox, marks } = await mail.read(command, async (store, mailbox) => {
-        const read = await readPastMark(store, mailbox, holder);
-        const account = read.emails.length ? await store.accounts.storedAccount(mailbox) : undefined;
-        const marks = account
-            ? await store.mail.emailMarks(account.id, read.emails.map((one) => one.id))
-            : new Map();
+        const read = await readPastMark(store, mailbox, holder, { triage });
+        const ids = [...read.emails, ...read.excerpts.map(({ email }) => email)].map((one) => one.id);
+        const account = ids.length ? await store.accounts.storedAccount(mailbox) : undefined;
+        const marks = account ? await store.mail.emailMarks(account.id, ids) : new Map();
         return { read, mailbox, marks };
     });
     // An agent reads this: earlier mail and signatures stay out of its text; the fingerprint is over the stored body.
-    const emails = read.emails.map((email) => ({ ...email, text: mailOwnText(email.text) }));
+    const emails = [
+        ...read.emails.map((email) => ({ ...email, text: mailOwnText(email.text) })),
+        ...read.excerpts.map(({ email, excerpt }) => {
+            const subject = email.email?.subject;
+            return { ...email, text: subject ? `${subject}\n\n${excerpt}` : excerpt, excerptOnly: true };
+        }),
+    ];
     const chats = new Map();
     for (const email of emails) {
         const chat = chats.get(email.chatId) ?? {
@@ -193,13 +204,22 @@ const holderReview = async (command, mail, holder, query) => {
         ...(skipped.length
             ? [{ field: "items", why: `left out: ${skipped.map(([reason, count]) => `${count} ${reason}`).join(", ")}` }]
             : []),
+        ...(read.excerpts.length
+            ? [
+                {
+                    field: "items",
+                    why: `${read.excerpts.length} bulk emails (excerpt_only) as their subject and first lines: ` +
+                        "read one whole with `messages show <ref>` when it is an order, an invoice or a request",
+                },
+            ]
+            : []),
     ];
     const output = outputFor(command);
     renderAnswer(command, output, answer, () => {
         output.renderer.note(read.mark
             ? `${holder}: past ${read.mark.throughId}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
-        return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id))}\n`).join("");
+        return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`).join("");
     });
 };
 /**
@@ -225,8 +245,9 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
     .option("--unanswered [duration]", "only threads whose newest email came to you, in To or Cc, with no answer for this long — 4h, 1d; 24h if not given")
     .option("--waiting [duration]", "only threads where you wrote last and nobody answered for this long — 3d; 7d if not given")
     .option("--holder <name>", "read for this holder — an agent or a pipeline — what is stored past its processing mark, by store order; " +
-    "bulk, envelopes, drafts, suspicious senders and partial mail left out; each text without quoted earlier mail " +
-    "or the signature; `messages acknowledge` moves the mark")
+    "newsletters, envelopes, drafts, suspicious senders and partial mail left out; other bulk mail after the rest, " +
+    "as its subject and first lines (excerpt_only); each text without quoted earlier mail or the signature; " +
+    "`messages acknowledge` moves the mark")
     .option("--new", "what changed since the last `review --new` of this mailbox, a point per thread — for scheduled runs")
     .addHelpText("after", `
 Without a date, --unanswered and --waiting look at threads active in the last ${OWED_DAYS} days.

package/dist/mail/index.d.ts

@@ -9,7 +9,8 @@ export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
-export { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MailWaiting, type MarkRead, mailWaiting, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { acknowledgeMark, advancePastSkipped, type BulkExcerpt, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MailWaiting, type MarkRead, mailWaiting, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { BULK_TRIAGE_DEFAULTS, type BulkSorted, type BulkTriage, excerptOf, NEWSLETTER_DEFAULTS, NEWSLETTER_SENDERS, NEWSLETTER_WORDS, type NewsletterCues, newsletterSorter, ORDER_WORDS, } from "./newsletter.js";
 export { type MailTurn, mailTurn } from "./owed.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PARTIAL, type PartialOutcome } from "./partial.js";

package/dist/mail/index.js

@@ -10,6 +10,7 @@ export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, mailWaiting, markOf, marksOf, readPastMark, } from "./marks.js";
+export { BULK_TRIAGE_DEFAULTS, excerptOf, NEWSLETTER_DEFAULTS, NEWSLETTER_SENDERS, NEWSLETTER_WORDS, newsletterSorter, ORDER_WORDS, } from "./newsletter.js";
 export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";

package/dist/mail/marks.d.ts

@@ -1,11 +1,12 @@
 import type { AccountKey, MessageStore, StoredHit } from "../store/store.js";
+import { type BulkTriage } from "./newsletter.js";
 /** A holder's name: what `--holder` takes and the mark's key ends with. */
 export declare const HOLDER: RegExp;
 /** At most this many emails are read past the mark in one go; the rest come with the next read. */
 export declare const MARK_BATCH = 200;
 /** A partial email waits this long to be stored whole, then is skipped. */
 export declare const HOLD_PARTIAL_MS: number;
-export type SkipReason = "bulk" | "envelope" | "partial" | "draft" | "suspicious";
+export type SkipReason = "bulk" | "newsletter" | "envelope" | "partial" | "draft" | "suspicious";
 /**
  * How far one holder — an agent, a pipeline — has processed an account's mail, in the shared store (`sync_cursors`,
  * key `consumer:<holder>`). It counts by the store's insert order (`emails.id`), so mail stored late, older than what
@@ -29,9 +30,19 @@ export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder:
 export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Promise<MailMark[]>;
 /** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
 export declare const cursorOf: (throughId: number, readAt: number) => string;
+/** A bulk email that is not surely a newsletter: the holder gets its subject and first lines only. */
+export interface BulkExcerpt {
+    email: StoredHit;
+    /** The first lines of its own text, without the subject. */
+    excerpt: string;
+    /** What kept it, or the newsletter signs too few to leave it out. */
+    cues: string[];
+}
 export interface MarkRead {
     /** The emails for the holder, oldest first; bulk, envelopes, drafts, suspicious senders and partial mail left out. */
     emails: StoredHit[];
+    /** Bulk mail past the mark that is not surely a newsletter, oldest first; none when the triage gives no excerpts. */
+    excerpts: BulkExcerpt[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
     /** More is stored after this batch: read again after acknowledging. */
@@ -49,6 +60,7 @@ export interface MarkRead {
 export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, options?: {
     now?: number;
     limit?: number;
+    triage?: BulkTriage;
 }) => Promise<MarkRead>;
 /** Mail past a holder's marks that would reach it: how many emails, and when the oldest of them was stored. */
 export interface MailWaiting {
@@ -60,17 +72,17 @@ export interface MailWaiting {
 }
 /**
  * What waits for the holder in every stored mailbox, read only: what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Bulk, envelopes, drafts, suspicious senders and partial mail
- * do not count.
+ * agent, so a run with nothing new costs no model call. Newsletters, envelopes, drafts, suspicious senders and partial
+ * mail do not count; other bulk mail counts as the excerpt the holder gets, unless the triage gives none.
  */
-export declare const mailWaiting: (store: MessageStore, holder: string, now?: number) => Promise<MailWaiting>;
+export declare const mailWaiting: (store: MessageStore, holder: string, now?: number, triage?: BulkTriage) => Promise<MailWaiting>;
 /**
- * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — bulk,
- * envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
+ * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — newsletters,
+ * bulk mail the triage gives no excerpt of, envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
  * does not read it all again. Suspicious senders' emails stay on the mark to be offered again. It stops at the first
  * email the holder reads. A store busy with a sync is left alone: the next check moves it.
  */
-export declare const advancePastSkipped: (store: MessageStore, holder: string, now?: number) => Promise<void>;
+export declare const advancePastSkipped: (store: MessageStore, holder: string, now?: number, triage?: BulkTriage) => Promise<void>;
 /**
  * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
  * still partial, or changed after the read (it may have become whole since), is held and comes with the next read.

package/dist/mail/marks.js

@@ -1,5 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
+import { mailOwnText } from "../conversations/mail-text.js";
 import { isBusy } from "../store/sqlite/transaction.js";
+import { BULK_TRIAGE_DEFAULTS, newsletterSorter } from "./newsletter.js";
 /** A holder's name: what `--holder` takes and the mark's key ends with. */
 export const HOLDER = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** At most this many emails are read past the mark in one go; the rest come with the next read. */
@@ -11,7 +13,14 @@ const MOST_HELD = 500;
 /** A cursor read at most this far in the future is a clock apart, not a forgery. */
 const CLOCK_SLACK_MS = 60_000;
 const PREFIX = "consumer:";
-const noneSkipped = () => ({ bulk: 0, envelope: 0, partial: 0, draft: 0, suspicious: 0 });
+const noneSkipped = () => ({
+    bulk: 0,
+    newsletter: 0,
+    envelope: 0,
+    partial: 0,
+    draft: 0,
+    suspicious: 0,
+});
 const keyOf = (holder) => {
     if (!HOLDER.test(holder))
         throw new CliError("validation_error", `a holder is lower-case letters, digits and dashes, not "${holder}"`);
@@ -83,14 +92,54 @@ const parseCursor = (cursor) => {
  * empty and gives the cursor of the newest stored email.
  */
 export const readPastMark = async (store, mailbox, holder, options = {}) => {
-    const { wanted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
-    return { emails: await store.mail.emailHits(wanted), ...read };
+    const { wanted, sorted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
+    const excerpts = wanted.flatMap((id) => {
+        const one = sorted.get(id);
+        return one ? [{ email: one.email, excerpt: one.excerpt, cues: one.cues }] : [];
+    });
+    const emails = await store.mail.emailHits(wanted.filter((id) => !sorted.has(id)));
+    return { emails, excerpts, ...read };
+};
+/**
+ * The batch's bulk emails a holder might read, sorted by `newsletterSorter`, and where the batch ends so it holds at
+ * most `perRead` excerpts. Drafts, envelopes, suspicious senders and partial mail keep their own verdicts.
+ */
+const sortBulk = async (store, batch, triage) => {
+    const sorted = new Map();
+    if (!triage.excerpts)
+        return { sorted, end: batch.length };
+    const sort = newsletterSorter(triage.cues);
+    let excerpts = 0;
+    for (const [index, marked] of batch.entries()) {
+        if (!marked.bulk || marked.draft || marked.envelope || marked.demoted || marked.partial)
+            continue;
+        const [email] = await store.mail.emailHits([marked.id]);
+        if (!email)
+            continue;
+        const subject = email.email?.subject ?? null;
+        const body = subject && email.text.startsWith(`${subject}\n\n`) ? email.text.slice(subject.length + 2) : email.text;
+        const one = sort({ subject, text: mailOwnText(body), from: email.email?.from?.address ?? null });
+        if (one.verdict === "excerpt" && excerpts === triage.perRead)
+            return { sorted, end: index };
+        if (one.verdict === "excerpt")
+            excerpts += 1;
+        sorted.set(marked.id, { ...one, email });
+    }
+    return { sorted, end: batch.length };
 };
-/** `readPastMark` without the emails' text: the store ids it would read, by their verdicts. */
-const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH, after }) => {
+/** `readPastMark` before it reads the emails: the store ids it would read by their verdicts, and the bulk sorted. */
+const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH, after, triage = BULK_TRIAGE_DEFAULTS, }) => {
     const saved = await markOf(store, mailbox, holder);
     const account = await accountOf(store, mailbox);
-    const empty = { wanted: [], oldestStoredAt: null, more: false, held: 0, skipped: noneSkipped(), mark: saved };
+    const empty = {
+        wanted: [],
+        sorted: new Map(),
+        oldestStoredAt: null,
+        more: false,
+        held: 0,
+        skipped: noneSkipped(),
+        mark: saved,
+    };
     if (!account)
         return { ...empty, cursor: cursorOf(0, now) };
     if (!saved)
@@ -103,7 +152,8 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     const newer = found.filter((email) => email.id > mark.throughId);
     const unsettled = newer.findIndex((email) => email.storedAt > settledAt);
     const fresh = unsettled === -1 ? newer : newer.slice(0, unsettled);
-    const batch = fresh.slice(0, limit);
+    const { sorted, end } = await sortBulk(store, fresh.slice(0, limit), triage);
+    const batch = fresh.slice(0, end);
     const examined = [...found.filter((email) => email.id <= mark.throughId), ...batch];
     const skipped = noneSkipped();
     const wanted = [];
@@ -111,7 +161,12 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     let held = 0;
     for (const email of examined) {
         const said = verdict(email, now);
-        if (said === "read") {
+        const bulk = sorted.get(email.id);
+        if (bulk?.verdict === "newsletter") {
+            if (email.id > mark.throughId)
+                skipped.newsletter += 1;
+        }
+        else if (said === "read" || bulk) {
             wanted.push(email.id);
             oldestStoredAt = Math.min(oldestStoredAt ?? email.storedAt, email.storedAt);
         }
@@ -122,6 +177,7 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     }
     return {
         wanted: wanted.sort((a, b) => a - b),
+        sorted: new Map([...sorted].filter(([, one]) => one.verdict === "excerpt")),
         oldestStoredAt,
         cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
         more: newer.length > batch.length,
@@ -132,17 +188,17 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
 };
 /**
  * What waits for the holder in every stored mailbox, read only: what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Bulk, envelopes, drafts, suspicious senders and partial mail
- * do not count.
+ * agent, so a run with nothing new costs no model call. Newsletters, envelopes, drafts, suspicious senders and partial
+ * mail do not count; other bulk mail counts as the excerpt the holder gets, unless the triage gives none.
  */
-export const mailWaiting = async (store, holder, now = Date.now()) => {
+export const mailWaiting = async (store, holder, now = Date.now(), triage = BULK_TRIAGE_DEFAULTS) => {
     const waiting = { unmarked: false, emails: 0, oldestStoredAt: null };
     for (const mailbox of await store.accounts.accounts()) {
         if (mailbox.provider !== "email")
             continue;
         let after;
         for (;;) {
-            const read = await examine(store, mailbox, holder, { now, ...(after === undefined ? {} : { after }) });
+            const read = await examine(store, mailbox, holder, { now, triage, ...(after === undefined ? {} : { after }) });
             if (!read.mark) {
                 waiting.unmarked = true;
                 break;
@@ -159,17 +215,17 @@ export const mailWaiting = async (store, holder, now = Date.now()) => {
     return waiting;
 };
 /**
- * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — bulk,
- * envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
+ * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — newsletters,
+ * bulk mail the triage gives no excerpt of, envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
  * does not read it all again. Suspicious senders' emails stay on the mark to be offered again. It stops at the first
  * email the holder reads. A store busy with a sync is left alone: the next check moves it.
  */
-export const advancePastSkipped = async (store, holder, now = Date.now()) => {
+export const advancePastSkipped = async (store, holder, now = Date.now(), triage = BULK_TRIAGE_DEFAULTS) => {
     for (const mailbox of await store.accounts.accounts()) {
         if (mailbox.provider !== "email")
             continue;
         for (;;) {
-            const read = await examine(store, mailbox, holder, { now });
+            const read = await examine(store, mailbox, holder, { now, triage });
             if (!read.mark || read.wanted.length > 0 || read.cursor === cursorOf(read.mark.throughId, now))
                 break;
             try {

package/dist/mail/newsletter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Mail sent to many is often an order, an invoice or a site's lead form that carries List-Unsubscribe. This tells a
+ * newsletter from it by words in the subject and the first lines, so a holder can leave out only what is surely a
+ * newsletter and give the rest to its agent as an excerpt. No model: it runs on every read past a mark.
+ */
+/** Words that say "advertising"; each matches at the start of a word, any case. */
+export declare const NEWSLETTER_WORDS: readonly ["скидк", "акци", "распродаж", "вебинар", "рассылк", "промокод", "спецпредложени", "дайджест", "новинк", "подборк", "кешбэк", "кэшбэк", "только сегодня", "успейте", "чёрная пятница", "черная пятница", "выгодн", "newsletter", "unsubscribe", "% off", "sale", "discount", "webinar", "digest", "weekly", "promo", "deal", "limited time", "free shipping", "new arrivals", "black friday", "cyber monday", "coupon", "save up to", "last chance", "don't miss", "descuento", "oferta", "rebaja", "boletín", "seminario web", "novedades", "promoción", "no te pierdas", "últimos días"];
+/** Parts of a sender's address that say "a newsletter": `news@…`, `newsletter.example.com`, `….substack.com`. */
+export declare const NEWSLETTER_SENDERS: readonly ["news", "newsletter", "newsletters", "digest", "weekly", "promo", "marketing", "offers", "deals", "sale", "substack.com"];
+/** Words that say "this is about something of yours"; one of them keeps the email for the agent. */
+export declare const ORDER_WORDS: readonly ["заказ", "счёт", "счет на", "счета", "оплат", "квитанци", "кассовый чек", "электронный чек", "заявк", "форма", "доставк", "трек", "договор", "подтвержд", "код подтверждения", "код для входа", "пароль", "order", "invoice", "receipt", "payment", "shipped", "delivery", "tracking", "booking", "reservation", "confirm", "your account", "verification", "password", "refund", "statement", "pedido", "factura", "recibo", "pago", "envío", "reserva", "confirmación", "contraseña"];
+export interface NewsletterCues {
+    newsletterWords: readonly string[];
+    newsletterSenders: readonly string[];
+    orderWords: readonly string[];
+    /** The score from which an email is surely a newsletter and left out. */
+    threshold: number;
+    /** How much of the email's own text is read, and shown as the excerpt. */
+    excerptChars: number;
+}
+export declare const NEWSLETTER_DEFAULTS: NewsletterCues;
+export interface BulkSorted {
+    /** `newsletter` is left out; `excerpt` goes to the agent as the subject and the first lines. */
+    verdict: "newsletter" | "excerpt";
+    score: number;
+    /** What decided it: the newsletter signs, or what kept the email. */
+    cues: string[];
+    excerpt: string;
+}
+/** The first lines of an email's own text, at most `chars`, cut at a word. */
+export declare const excerptOf: (text: string, chars: number) => string;
+/**
+ * Built once per read, so the word lists compile once. A reply, an order word in the subject or an order's number
+ * keeps the email. Otherwise a newsletter word counts 2 in the subject and 1 in the first lines, a newsletter's
+ * address 2, an emoji in the subject and a browser or unsubscribe link at the top 1 each, and each order word in
+ * the first lines takes 2 off. Measured 2026-11-05 on 30 days of the owner's bulk mail: 99 of 100 sampled
+ * newsletter verdicts were newsletters, and about half of the newsletters were found.
+ */
+export declare const newsletterSorter: (cues?: NewsletterCues) => ({ subject, text, from }: {
+    subject: string | null;
+    text: string;
+    from: string | null;
+}) => BulkSorted;
+/** How a holder's read treats bulk mail. */
+export interface BulkTriage {
+    /** `false` leaves every bulk email out, newsletter or not. */
+    excerpts: boolean;
+    /** At most this many excerpts in one read; the read ends before the next one, which comes with the next read. */
+    perRead: number;
+    cues: NewsletterCues;
+}
+export declare const BULK_TRIAGE_DEFAULTS: BulkTriage;

package/dist/mail/newsletter.js

@@ -0,0 +1,189 @@
+/**
+ * Mail sent to many is often an order, an invoice or a site's lead form that carries List-Unsubscribe. This tells a
+ * newsletter from it by words in the subject and the first lines, so a holder can leave out only what is surely a
+ * newsletter and give the rest to its agent as an excerpt. No model: it runs on every read past a mark.
+ */
+/** Words that say "advertising"; each matches at the start of a word, any case. */
+export const NEWSLETTER_WORDS = [
+    "скидк",
+    "акци",
+    "распродаж",
+    "вебинар",
+    "рассылк",
+    "промокод",
+    "спецпредложени",
+    "дайджест",
+    "новинк",
+    "подборк",
+    "кешбэк",
+    "кэшбэк",
+    "только сегодня",
+    "успейте",
+    "чёрная пятница",
+    "черная пятница",
+    "выгодн",
+    "newsletter",
+    "unsubscribe",
+    "% off",
+    "sale",
+    "discount",
+    "webinar",
+    "digest",
+    "weekly",
+    "promo",
+    "deal",
+    "limited time",
+    "free shipping",
+    "new arrivals",
+    "black friday",
+    "cyber monday",
+    "coupon",
+    "save up to",
+    "last chance",
+    "don't miss",
+    "descuento",
+    "oferta",
+    "rebaja",
+    "boletín",
+    "seminario web",
+    "novedades",
+    "promoción",
+    "no te pierdas",
+    "últimos días",
+];
+/** Parts of a sender's address that say "a newsletter": `news@…`, `newsletter.example.com`, `….substack.com`. */
+export const NEWSLETTER_SENDERS = [
+    "news",
+    "newsletter",
+    "newsletters",
+    "digest",
+    "weekly",
+    "promo",
+    "marketing",
+    "offers",
+    "deals",
+    "sale",
+    "substack.com",
+];
+/** Words that say "this is about something of yours"; one of them keeps the email for the agent. */
+export const ORDER_WORDS = [
+    "заказ",
+    "счёт",
+    "счет на",
+    "счета",
+    "оплат",
+    "квитанци",
+    "кассовый чек",
+    "электронный чек",
+    "заявк",
+    "форма",
+    "доставк",
+    "трек",
+    "договор",
+    "подтвержд",
+    "код подтверждения",
+    "код для входа",
+    "пароль",
+    "order",
+    "invoice",
+    "receipt",
+    "payment",
+    "shipped",
+    "delivery",
+    "tracking",
+    "booking",
+    "reservation",
+    "confirm",
+    "your account",
+    "verification",
+    "password",
+    "refund",
+    "statement",
+    "pedido",
+    "factura",
+    "recibo",
+    "pago",
+    "envío",
+    "reserva",
+    "confirmación",
+    "contraseña",
+];
+/** A number an order, an invoice or a request is known by, after the word that names it. */
+const REFERENCE_NUMBER = /(?<![\p{L}])(?:заказ|заявк|сч[её]т|квитанци|order|invoice|ticket|pedido|factura)\p{L}*\s*(?:№|#|n[o°]\.?)?\s?\d{3,}/iu;
+/** The top of a newsletter: a link to read it in a browser, or to leave the list. */
+const NEWSLETTER_TOP = /в браузере|веб-верси|view (?:it |this email )?(?:in|on) (?:your |a )?browser|unsubscribe|отписаться|darse de baja|ver en (?:el )?navegador/iu;
+const PICTOGRAPH = /\p{Extended_Pictographic}/u;
+/** A reply or a forward is a conversation, whatever it says. */
+const REPLY = /^\s*(?:re|fw|fwd|aw|wg|ответ|отв|rv|res)\s*(?:\[\d+\])?\s*:/iu;
+export const NEWSLETTER_DEFAULTS = {
+    newsletterWords: NEWSLETTER_WORDS,
+    newsletterSenders: NEWSLETTER_SENDERS,
+    orderWords: ORDER_WORDS,
+    threshold: 2,
+    excerptChars: 400,
+};
+const escaped = (word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const matcherOf = (words) => {
+    const list = words.map((word) => word.trim().toLowerCase()).filter(Boolean);
+    if (list.length === 0)
+        return () => [];
+    const pattern = new RegExp(`(?<![\\p{L}\\p{N}])(?:${list.map(escaped).join("|")})`, "giu");
+    return (text) => [...new Set([...text.toLowerCase().matchAll(pattern)].map(([found]) => found))];
+};
+/** The first lines of an email's own text, at most `chars`, cut at a word. */
+export const excerptOf = (text, chars) => {
+    const flat = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join("\n");
+    if (flat.length <= chars)
+        return flat;
+    const cut = flat.slice(0, chars);
+    const space = cut.search(/\s\S*$/);
+    return `${space > chars / 2 ? cut.slice(0, space) : cut}…`;
+};
+/**
+ * Built once per read, so the word lists compile once. A reply, an order word in the subject or an order's number
+ * keeps the email. Otherwise a newsletter word counts 2 in the subject and 1 in the first lines, a newsletter's
+ * address 2, an emoji in the subject and a browser or unsubscribe link at the top 1 each, and each order word in
+ * the first lines takes 2 off. Measured 2026-11-05 on 30 days of the owner's bulk mail: 99 of 100 sampled
+ * newsletter verdicts were newsletters, and about half of the newsletters were found.
+ */
+export const newsletterSorter = (cues = NEWSLETTER_DEFAULTS) => {
+    const advertising = matcherOf(cues.newsletterWords);
+    const ordered = matcherOf(cues.orderWords);
+    const senders = cues.newsletterSenders.map((part) => part.trim().toLowerCase()).filter(Boolean);
+    const fromNewsletter = (address) => {
+        const domain = address.split("@")[1] ?? "";
+        const parts = new Set(address.split(/[.@_+-]/));
+        return senders.some((one) => (one.includes(".") ? domain === one || domain.endsWith(`.${one}`) : parts.has(one)));
+    };
+    return ({ subject, text, from }) => {
+        const excerpt = excerptOf(text, cues.excerptChars);
+        const title = subject ?? "";
+        const number = REFERENCE_NUMBER.exec(`${title}\n${excerpt}`);
+        const kept = [...(REPLY.test(title) ? ["a reply"] : []), ...ordered(title), ...(number ? [number[0]] : [])];
+        if (kept.length > 0)
+            return { verdict: "excerpt", score: 0, cues: kept, excerpt };
+        const inTitle = advertising(title);
+        const signs = [
+            ...inTitle.map((word) => [word, 2]),
+            ...advertising(excerpt)
+                .filter((word) => !inTitle.includes(word))
+                .map((word) => [word, 1]),
+            ...(PICTOGRAPH.test(title) ? [["an emoji in the subject", 1]] : []),
+            ...(NEWSLETTER_TOP.test(excerpt) ? [["a browser or unsubscribe link", 1]] : []),
+            ...(fromNewsletter((from ?? "").toLowerCase()) ? [["a newsletter's address", 2]] : []),
+            ...ordered(excerpt).map((word) => [`-${word}`, -2]),
+        ];
+        const score = signs.reduce((sum, [, weight]) => sum + weight, 0);
+        return {
+            verdict: score >= cues.threshold ? "newsletter" : "excerpt",
+            score,
+            cues: signs.map(([cue]) => cue),
+            excerpt,
+        };
+    };
+};
+export const BULK_TRIAGE_DEFAULTS = { excerpts: true, perRead: 30, cues: NEWSLETTER_DEFAULTS };

package/dist/mail/review.d.ts

@@ -18,8 +18,10 @@ export interface MailReviewOptions {
     now?: number;
 }
 /** A review of mail: each thread a chat, each email a stored hit with its locator. */
+/** `excerptOnly`: a bulk email a holder gets as its subject and first lines, its `text` cut to them. */
 export type MailHit = StoredHit & {
     marks?: EmailMarks;
+    excerptOnly?: true;
 };
 export interface MailReview extends Review {
     chats: (Omit<ReviewChat, "messages"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.575.0",
+  "version": "0.576.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",