@wirecat/cli-core 0.575.0 → 0.577.0

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/findings.d.ts

@@ -99,6 +99,8 @@ export interface MailOrderFinding extends Cited {
     invoice?: string;
     payment?: string;
     project?: string;
+    /** The order's page at the shop, http or https. */
+    sourceUrl?: string;
     reason: string;
 }
 /** A later mail about a stored order, found by its shop and number: shipped, delivered, cancelled, returned. */

package/dist/mail/findings.js

@@ -1,4 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
+import { EXTERNAL_ID_CHARS, externalIdOf, SOURCE_URL_CHARS, sourceUrlOf } from "../domain/external-links.js";
 import { INVOICE_DIRECTIONS, MONEY_DIRECTIONS } from "../domain/finance.js";
 import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
 import { formatLocator, parseLocator } from "../domain/locator.js";
@@ -59,8 +60,19 @@ const optional = (key, value, read) => (value === undefined ? {} : { [key]: read
 const one = (raw, ids) => {
     if (!raw || typeof raw !== "object")
         return invalid("a finding is an object");
-    if (raw.kind === "task" || raw.kind === "fact")
+    if (raw.kind === "fact")
         return validateFinding(raw, RULES, ids);
+    if (raw.kind === "task") {
+        const { externalId, sourceUrl, ...task } = raw;
+        return {
+            ...validateFinding(task, RULES, ids),
+            ...optional("externalId", externalId, (value) => {
+                const { provider, id } = externalIdOf(findingText(value, EXTERNAL_ID_CHARS + 40));
+                return `${provider}:${id}`;
+            }),
+            ...optional("sourceUrl", sourceUrl, (value) => sourceUrlOf(findingText(value, SOURCE_URL_CHARS))),
+        };
+    }
     const id = findingId(raw.id, ids);
     const evidence = validEvidence(raw.evidence, RULES);
     const reference = (value, pattern, what) => {
@@ -247,6 +259,7 @@ const one = (raw, ids) => {
                 "invoice",
                 "payment",
                 "project",
+                "sourceUrl",
                 "reason",
                 "evidence",
             ], RULES.singular);
@@ -266,6 +279,7 @@ const one = (raw, ids) => {
                 ...optional("invoice", raw.invoice, (value) => reference(value, INVOICE, "an order's invoice")),
                 ...optional("payment", raw.payment, (value) => reference(value, PAYMENT, "an order's payment")),
                 ...optional("project", raw.project, (value) => reference(value, PROJECT, "a project")),
+                ...optional("sourceUrl", raw.sourceUrl, (value) => sourceUrlOf(findingText(value, SOURCE_URL_CHARS), "order.source-url")),
                 reason: findingText(raw.reason, 2000),
                 evidence,
             };

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, type MarkRewind, mailWaiting, markOf, marksOf, type RewoundMark, readPastMark, rewindMark, 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

@@ -9,7 +9,8 @@ export { dropMissing, tooManyGone } from "./gone.js";
 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 { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, mailWaiting, markOf, marksOf, readPastMark, rewindMark, } 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,20 +72,49 @@ 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.
  * The same cursor twice changes nothing more.
  */
 export declare const acknowledgeMark: (store: MessageStore, mailbox: AccountKey, holder: string, cursor: string, now?: number) => Promise<MailMark>;
+/** Where the owner moves a holder's mark back to: the emails received since a time, or the last n it was given. */
+export type MarkRewind = {
+    since: number;
+} | {
+    last: number;
+};
+export interface RewoundMark {
+    mark: MailMark;
+    /** Where the mark was before. */
+    fromId: number;
+    /** The emails between the new mark and the old one the holder reads whole again. */
+    again: number;
+    /** Bulk emails between them: excerpts again, unless they are surely newsletters. */
+    bulk: number;
+    /** Emails between them the holder skips again: drafts, envelopes, suspicious senders, partial mail. */
+    skipped: number;
+    /** The mark is moved only when not dry. */
+    dry: boolean;
+}
+/**
+ * Moves the holder's mark back, so its next reviews give it that mail again: past every email received since
+ * `since`, or past the last `last` emails it was given. The owner's alone: a holder only ever moves its own mark
+ * forward. The id is the store's insert order, so an older email stored after the earliest one picked is read again too;
+ * the answer counts them all.
+ */
+export declare const rewindMark: (store: MessageStore, mailbox: AccountKey, holder: string, to: MarkRewind, { now, dry }?: {
+    now?: number;
+    dry?: boolean;
+}) => Promise<RewoundMark>;

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 {
@@ -260,3 +316,89 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
     await store.sync.setSyncState(mailbox, key, JSON.stringify(next));
     return { holder, ...next, updatedAt: now };
 };
+/**
+ * Moves the holder's mark back, so its next reviews give it that mail again: past every email received since
+ * `since`, or past the last `last` emails it was given. The owner's alone: a holder only ever moves its own mark
+ * forward. The id is the store's insert order, so an older email stored after the earliest one picked is read again too;
+ * the answer counts them all.
+ */
+export const rewindMark = async (store, mailbox, holder, to, { now = Date.now(), dry = false } = {}) => {
+    const key = keyOf(holder);
+    const account = await accountOf(store, mailbox);
+    if (!account)
+        throw new CliError("not_found", `no mail of ${mailbox.account} is stored`);
+    const mark = await markOf(store, mailbox, holder);
+    if (!mark)
+        throw new CliError("not_found", `${holder} has no mark in ${mailbox.account}: its first review starts it`, {
+            reason: "mail.no-mark",
+        });
+    if ("last" in to && (!Number.isSafeInteger(to.last) || to.last < 1))
+        throw new CliError("validation_error", "--last takes a whole number of emails, 1 or more");
+    if ("since" in to && !Number.isFinite(to.since))
+        throw new CliError("validation_error", "--since-time takes a time");
+    const given = (email) => {
+        const said = verdict(email, now);
+        return said === "read" || said === "held" || said === "bulk";
+    };
+    const between = [];
+    let through = mark.throughId;
+    let before = mark.throughId + 1;
+    for (let counted = 0;;) {
+        const page = await store.mail.emailsBefore(account.id, before, MARK_BATCH);
+        if (page.length === 0) {
+            if ("last" in to && between.length > 0)
+                through = 0;
+            break;
+        }
+        let done = false;
+        for (const email of page) {
+            if ("last" in to) {
+                between.push(email);
+                if (given(email))
+                    counted += 1;
+                if (counted === to.last) {
+                    through = email.id - 1;
+                    done = true;
+                    break;
+                }
+            }
+            else {
+                // An email is stored after it arrives, so once stored before the time, none further back arrived after it.
+                if (email.storedAt < to.since - CLOCK_SLACK_MS) {
+                    done = true;
+                    break;
+                }
+                between.push(email);
+                if ((email.at ?? email.storedAt) >= to.since)
+                    through = email.id - 1;
+            }
+        }
+        if (done)
+            break;
+        before = page.at(-1)?.id ?? 0;
+    }
+    const moved = between.filter((email) => email.id > through);
+    const count = (pick) => moved.filter((email) => pick(verdict(email, now))).length;
+    const answer = {
+        fromId: mark.throughId,
+        again: count((said) => said === "read" || said === "held"),
+        bulk: count((said) => said === "bulk"),
+        skipped: count((said) => said !== "read" && said !== "held" && said !== "bulk"),
+        dry,
+    };
+    if (through >= mark.throughId)
+        return { mark, ...answer };
+    const [last] = through > 0 ? await store.mail.emailsBefore(account.id, through + 1, 1) : [];
+    const at = last?.id === through ? last.at : null;
+    const next = {
+        throughId: through,
+        throughAt: at,
+        held: mark.held.filter((id) => id <= through),
+        suspicious: mark.suspicious.filter((id) => id <= through),
+        read: mark.read,
+        skipped: mark.skipped,
+    };
+    if (!dry)
+        await store.sync.setSyncState(mailbox, key, JSON.stringify(next));
+    return { mark: { holder, ...next, updatedAt: dry ? mark.updatedAt : now }, ...answer };
+};

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;