@wirecat/cli-core 0.554.0 → 0.556.0

package/dist/mail/cli/review.js

@@ -0,0 +1,274 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { defineQuery } from "@wirecat/cli-base/query";
+import { defineSteps, stepOf } from "@wirecat/cli-base/standards";
+import { Command } from "commander";
+import { environmentOf, outputFor } from "../../cli/context.js";
+import { LOCAL_READ } from "../../cli/effects.js";
+import { listOf, renderAnswer } from "../../cli/envelope.js";
+import { listQuery, nativeField, nativeTerms, queryHelp, typedQuery } from "../../cli/list-query.js";
+import { pointsOf } from "../../cli/messenger/catch-up.js";
+import { catchUpQuery, summaryOf } from "../../cli/messenger/catch-up-answers.js";
+import { messageItem } from "../../cli/messenger/message-items.js";
+import { checkPoints } from "../../cli/messenger/points.js";
+import { unansweredHours } from "../../cli/messenger/review.js";
+import { parseDuration } from "../../domain/duration.js";
+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 { hitText } from "../read.js";
+import { OWED_DAYS, REVIEW_THREADS, reviewMail } from "../review.js";
+const DAY = 86_400_000;
+/** Where a mail review starts: a time only; one thread is `conversations show`. */
+export const MAIL_REVIEW_QUERY = defineQuery({
+    entity: "message",
+    backend: "native",
+    fields: [
+        nativeField({ name: "date", type: "time", operators: ["range"], example: "date>2h" }),
+        nativeField({ name: "bulk", type: "kw", operators: ["term"], example: "bulk:false" }),
+    ],
+});
+/** The mail review's steps; a host lists them beside its own so its step checks know them. */
+export const MAIL_REVIEW_STEPS = defineSteps([
+    {
+        id: "mail-messages.acknowledge",
+        command: "messages acknowledge",
+        args: [
+            { name: "holder", required: true },
+            { name: "cursor", required: true },
+        ],
+        why: "once these are processed, this moves the holder's mark past them",
+    },
+    {
+        id: "mail-review.next",
+        command: "review",
+        args: [{ name: "query", required: true }],
+        why: "the next review starts where this one ended",
+    },
+    {
+        id: "mail-conversations.show",
+        command: "conversations show",
+        args: [{ name: "conversation", required: true }],
+        why: "only the newest emails of the thread were read here; this reads it whole",
+    },
+]);
+const step = (id) => MAIL_REVIEW_STEPS.find((one) => one.id === id);
+const waitingHours = (value) => value === true ? AGENDA_DEFAULTS.waiting / 3_600_000 : parseDuration(String(value), "--waiting") / 3_600_000;
+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 said = [
+        marks?.bulk ? "bulk" : "",
+        marks?.listId ? `list ${marks.listId}` : "",
+        marks?.ruleId ? `rule ${marks.ruleId}` : "",
+    ];
+    const shown = said.filter(Boolean).join(" · ");
+    return shown ? `\n  [${shown}]` : "";
+};
+const reviewAnswer = (found, mailbox, fresh) => {
+    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));
+    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;
+    const missing = [
+        ...(cut.length > 0
+            ? [
+                {
+                    field: "items",
+                    why: `only the newest emails of ${cut.length} thread(s)`,
+                    step: "mail-conversations.show",
+                },
+            ]
+            : []),
+        ...(found.skipped.length > 0
+            ? [
+                {
+                    field: "items",
+                    why: `skipped ${found.skipped.length} threads — more than ${REVIEW_THREADS} at once; the next review reads them`,
+                },
+            ]
+            : []),
+        ...(found.quiet > 0
+            ? [{ field: "items", why: `bulk:false left out ${found.quiet} threads of mail sent to many, lists or envelopes` }]
+            : []),
+    ];
+    const next = [
+        ...(!fresh && !turns
+            ? [
+                stepOf(step("mail-review.next"), {
+                    args: { query: `date>${quoted(found.complete ? found.until : found.since)}` },
+                }),
+            ]
+            : []),
+        ...cut.map((chat) => stepOf(step("mail-conversations.show"), { args: { conversation: ref(chat.id) } })),
+    ];
+    return listOf("review", {
+        items: read.map((message) => ({
+            ...summaryOf(message, mailbox),
+            email: {
+                ...messageItem(message, mailbox).email,
+                bulk: message.marks?.bulk ?? false,
+                list_id: message.marks?.listId ?? null,
+                rule_id: message.marks?.ruleId ?? null,
+            },
+        })),
+        limit: Math.max(1, read.length),
+        has_more: false,
+        next,
+        missing,
+        meta: found.complete ? {} : { complete: false },
+    });
+};
+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 { 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();
+        return { read, mailbox, marks };
+    });
+    const chats = new Map();
+    for (const email of read.emails) {
+        const chat = chats.get(email.chatId) ?? {
+            id: email.chatId,
+            title: email.chatTitle,
+            kind: "dialog",
+            messages: [],
+            more: false,
+        };
+        const mark = marks.get(email.id);
+        chat.messages.push(mark ? { ...email, marks: mark } : email);
+        chats.set(email.chatId, chat);
+    }
+    const now = new Date().toISOString();
+    const found = {
+        since: read.mark?.throughAt ? new Date(read.mark.throughAt).toISOString() : now,
+        until: now,
+        complete: !read.more,
+        chats: [...chats.values()],
+        skipped: [],
+        partial: false,
+        quiet: 0,
+    };
+    const answer = reviewAnswer(found, mailbox, true);
+    const skipped = Object.entries(read.skipped).filter(([, count]) => count > 0);
+    answer.next = [
+        stepOf(step("mail-messages.acknowledge"), { args: { holder, cursor: read.cursor } }),
+        ...(answer.next ?? []),
+    ];
+    answer.missing = [
+        ...(answer.missing ?? []),
+        ...(read.held > 0 ? [{ field: "items", why: `${read.held} partial emails held until they are whole` }] : []),
+        ...(skipped.length
+            ? [{ field: "items", why: `left out: ${skipped.map(([reason, count]) => `${count} ${reason}`).join(", ")}` }]
+            : []),
+    ];
+    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 read.emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id))}\n`).join("");
+    });
+};
+/**
+ * `review` over the stored mail of the profile's mailbox, with tg's words: what is new, what the owner owes, what
+ * waits for an answer. It reads the store only and opens no task.
+ */
+export const mailReviewCommand = (mail) => annotate(new Command("review"), {
+    examples: [
+        `${mail.app.command} personal review "date>2h"`,
+        `${mail.app.command} personal review --new`,
+        `${mail.app.command} personal review --unanswered 1d`,
+        `${mail.app.command} personal review --waiting 7d`,
+    ],
+    effects: LOCAL_READ,
+    partial: true,
+    output: { entity: "message", view: "summary" },
+    query: MAIL_REVIEW_QUERY,
+})
+    .summary("threads with new mail, mail you owe an answer, mail waiting for one")
+    .description("every stored email, yours too, in threads that changed since a point — for reviewing who owes what. " +
+    "It reads what sync stored, so it asks the mail server nothing")
+    .addHelpText("after", queryHelp(MAIL_REVIEW_QUERY))
+    .argument("[query...]", `where the last review ended: date>2h; ${REVIEW_DAYS} days ago if no date`)
+    .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 and partial mail left out; `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.
+Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score.
+bulk:false leaves out threads whose newest email is mail sent to many, a list's or recorded by an envelope rule.
+Mail newer than the last finished sync waits for the next review. Each reader keeps its own --new point: you,
+an agent over MCP, and each scheduled run.`)
+    .action(async function (query) {
+    const options = this.opts();
+    if (options.holder !== undefined)
+        return holderReview(this, mail, options.holder, query);
+    const { since: from, meta } = catchUpQuery(query, MAIL_REVIEW_QUERY, "review");
+    const bulk = nativeTerms(listQuery(typedQuery(query), MAIL_REVIEW_QUERY, "review"), "review").get("bulk")?.value;
+    if (bulk !== undefined && bulk !== "false")
+        throw new CliError("validation_error", `bulk: takes false — leave it out to see all mail, not "${bulk}"`);
+    const turns = options.unanswered !== undefined || options.waiting !== undefined;
+    if (options.new && (from !== undefined || turns))
+        throw new CliError("validation_error", "--new keeps its own point — not with a date, --unanswered or --waiting");
+    const unanswered = options.unanswered === undefined ? undefined : unansweredHours(options.unanswered);
+    const waiting = options.waiting === undefined ? undefined : waitingHours(options.waiting);
+    const env = environmentOf(this).env ?? process.env;
+    const now = Date.now();
+    const { found, mailbox, saved } = await mail.read(this, async (store, mailbox) => {
+        const saved = options.new
+            ? checkPoints(mail.app, {
+                command: pointsOf(this, "review", mail.app),
+                profile: pointsName(mailbox),
+                env,
+                firstLookMs: REVIEW_DAYS * DAY,
+            })
+            : undefined;
+        const since = from ?? saved?.first ?? (turns ? now - OWED_DAYS * DAY : reviewStart(now));
+        const found = await reviewMail(store, mailbox, {
+            since,
+            now,
+            ...(saved ? { points: saved.chats } : {}),
+            ...(bulk === "false" ? { noBulk: true } : {}),
+            ...(unanswered === undefined ? {} : { unansweredAfterHours: unanswered }),
+            ...(waiting === undefined ? {} : { waitingAfterHours: waiting }),
+        });
+        return { found, mailbox, saved };
+    });
+    const output = outputFor(this);
+    const answer = reviewAnswer(found, mailbox, saved !== undefined);
+    if (meta)
+        answer.meta = { ...meta, ...answer.meta };
+    renderAnswer(this, output, answer, () => {
+        const read = found.chats.flatMap((chat) => chat.messages);
+        if (found.unanswered || found.waiting)
+            output.renderer.note(`${[
+                found.unanswered ? `owed for ${found.unanswered.olderThanHours}h or more` : "",
+                found.waiting ? `waiting ${found.waiting.olderThanHours}h or more` : "",
+            ]
+                .filter(Boolean)
+                .join(", ")}, threads active from ${found.since}`);
+        else
+            output.renderer.note(`from ${found.since} to ${found.until}${found.complete ? "" : ", incomplete"}`);
+        if (found.quiet > 0)
+            output.renderer.note(`bulk:false left out ${found.quiet} threads`);
+        if (read.length === 0)
+            output.renderer.note("nothing new in the stored mail");
+        return read
+            .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+            .map((hit) => `${hitText(hit)}${markText(hit.marks)}\n`)
+            .join("");
+    });
+    saved?.save(found.checked ?? {}, found.complete ? { through: found.until } : {});
+});

package/dist/mail/index.d.ts

@@ -6,6 +6,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, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.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";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
@@ -13,6 +15,7 @@ export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST
 export { type MailFolderProgress, mailProgress } from "./progress.js";
 export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, type MailSearch, type ShownMail, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { type FileStamp, FULL_PASS_MS, MBOX_RESUME, type MboxPoint, mergeRanges, parsePoint, type Ranges, type ResumePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
+export { isBulk, type MailReview, type MailReviewOptions, OWED_DAYS, REVIEW_THREADS, reviewMail } from "./review.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { type MailRuleSet, storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./rule-tags.js";

package/dist/mail/index.js

@@ -6,6 +6,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, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
+export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
@@ -13,6 +15,7 @@ export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
 export { mailProgress } from "./progress.js";
 export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
+export { isBulk, OWED_DAYS, REVIEW_THREADS, reviewMail } from "./review.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags } from "./rule-tags.js";

package/dist/mail/marks.d.ts

@@ -0,0 +1,56 @@
+import type { AccountKey, MessageStore, StoredHit } from "../store/store.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";
+/**
+ * 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
+ * was read, is still after the mark. Partial emails are held until they are whole.
+ */
+export interface MailMark {
+    holder: string;
+    throughId: number;
+    /** ms: when the email at `throughId` was received; for display. */
+    throughAt: number | null;
+    held: number[];
+    read: number;
+    skipped: Record<SkipReason, number>;
+    /** ms. */
+    updatedAt: number;
+}
+export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder: string) => Promise<MailMark | undefined>;
+/** Every holder's mark on the mailbox, by name. */
+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;
+export interface MarkRead {
+    /** The emails for the holder, oldest first; bulk, envelopes, drafts and partial mail left out. */
+    emails: StoredHit[];
+    /** What `acknowledge --cursor` takes once the holder is done with these. */
+    cursor: string;
+    /** More is stored after this batch: read again after acknowledging. */
+    more: boolean;
+    held: number;
+    skipped: Record<SkipReason, number>;
+    /** `undefined` before the holder's first acknowledge: it starts from the mail stored now. */
+    mark: MailMark | undefined;
+}
+/**
+ * What the holder has not processed: the emails stored after its mark, and the held ones that are whole now. Reads
+ * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
+ * empty and gives the cursor of the newest stored email.
+ */
+export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, { now, limit }?: {
+    now?: number;
+    limit?: number;
+}) => Promise<MarkRead>;
+/**
+ * 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>;

package/dist/mail/marks.js

@@ -0,0 +1,178 @@
+import { CliError } from "@wirecat/cli-base";
+/** 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. */
+export const MARK_BATCH = 200;
+/** A partial email waits this long to be stored whole, then is skipped. */
+export const HOLD_PARTIAL_MS = 7 * 86_400_000;
+/** Held emails kept on one mark at most; past it the oldest are skipped as partial. */
+const MOST_HELD = 500;
+const PREFIX = "consumer:";
+const noneSkipped = () => ({ bulk: 0, envelope: 0, partial: 0, draft: 0 });
+const keyOf = (holder) => {
+    if (!HOLDER.test(holder))
+        throw new CliError("validation_error", `a holder is lower-case letters, digits and dashes, not "${holder}"`);
+    return `${PREFIX}${holder}`;
+};
+const parsed = (holder, value, at) => {
+    try {
+        const saved = JSON.parse(value);
+        if (typeof saved.throughId !== "number")
+            return undefined;
+        return {
+            holder,
+            throughId: saved.throughId,
+            throughAt: saved.throughAt ?? null,
+            held: Array.isArray(saved.held) ? saved.held.filter((id) => typeof id === "number") : [],
+            read: saved.read ?? 0,
+            skipped: { ...noneSkipped(), ...saved.skipped },
+            updatedAt: at,
+        };
+    }
+    catch {
+        return undefined;
+    }
+};
+const accountOf = async (store, mailbox) => store.accounts.storedAccount(mailbox).catch((error) => {
+    if (error instanceof CliError && error.code === "not_found")
+        return undefined;
+    throw error;
+});
+export const markOf = async (store, mailbox, holder) => {
+    const saved = await store.sync.syncState(mailbox, keyOf(holder));
+    return saved ? parsed(holder, saved.value, Date.parse(saved.at)) : undefined;
+};
+/** Every holder's mark on the mailbox, by name. */
+export const marksOf = async (store, mailbox) => {
+    const account = await accountOf(store, mailbox);
+    if (!account)
+        return [];
+    return (await store.mail.statesLike(account.id, PREFIX))
+        .flatMap(({ key, value, at }) => parsed(key.slice(PREFIX.length), value, at) ?? [])
+        .sort((a, b) => a.holder.localeCompare(b.holder));
+};
+/** Why an email is not for the holder, or `held` while it is partial and young, or `read`. */
+const verdict = (email, now) => {
+    if (email.draft)
+        return "draft";
+    if (email.envelope)
+        return "envelope";
+    if (email.bulk)
+        return "bulk";
+    if (email.partial)
+        return now - email.storedAt < HOLD_PARTIAL_MS ? "held" : "partial";
+    return "read";
+};
+/** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
+export const cursorOf = (throughId, readAt) => `${throughId}.${readAt}`;
+const parseCursor = (cursor) => {
+    const match = /^(\d+)\.(\d+)$/.exec(cursor.trim());
+    if (!match)
+        throw new CliError("validation_error", `--cursor takes the cursor review gave, such as 9123.1762090000000`);
+    return { throughId: Number(match[1]), readAt: Number(match[2]) };
+};
+/**
+ * What the holder has not processed: the emails stored after its mark, and the held ones that are whole now. Reads
+ * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
+ * empty and gives the cursor of the newest stored email.
+ */
+export const readPastMark = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH } = {}) => {
+    const mark = await markOf(store, mailbox, holder);
+    const account = await accountOf(store, mailbox);
+    const empty = { emails: [], more: false, held: 0, skipped: noneSkipped(), mark };
+    if (!account)
+        return { ...empty, cursor: cursorOf(0, now) };
+    if (!mark)
+        return { ...empty, cursor: cursorOf(await store.mail.newestEmailId(account.id), now) };
+    const found = await store.mail.emailsAfter(account.id, mark.throughId, limit + 1, mark.held);
+    // Mail a running sync stored is read once that sync ended: it files bulk mail only at its end.
+    const settled = await store.sync.syncState(mailbox, "mail_coverage");
+    const settledAt = settled ? Date.parse(settled.at) : Number.POSITIVE_INFINITY;
+    const after = found.filter((email) => email.id > mark.throughId);
+    const unsettled = after.findIndex((email) => email.storedAt > settledAt);
+    const fresh = unsettled === -1 ? after : after.slice(0, unsettled);
+    const batch = fresh.slice(0, limit);
+    const examined = [...found.filter((email) => email.id <= mark.throughId), ...batch];
+    const skipped = noneSkipped();
+    const wanted = [];
+    let held = 0;
+    for (const email of examined) {
+        const said = verdict(email, now);
+        if (said === "read")
+            wanted.push(email.id);
+        else if (said === "held")
+            held += 1;
+        else if (email.id > mark.throughId)
+            skipped[said] += 1;
+    }
+    const emails = await store.mail.emailHits(wanted.sort((a, b) => a - b));
+    return {
+        emails,
+        cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
+        more: after.length > batch.length,
+        held,
+        skipped,
+        mark,
+    };
+};
+/**
+ * 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 const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date.now()) => {
+    const key = keyOf(holder);
+    const { throughId, readAt } = parseCursor(cursor);
+    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);
+    const from = mark?.throughId ?? throughId;
+    if (throughId < from)
+        throw new CliError("validation_error", `${holder} is already past ${throughId}: its mark is at ${from}`);
+    const examined = [];
+    let after = from;
+    const held = new Set(mark?.held ?? []);
+    const again = await store.mail.emailsAfter(account.id, Number.MAX_SAFE_INTEGER, 0, [...held]);
+    examined.push(...again);
+    while (after < throughId) {
+        const page = (await store.mail.emailsAfter(account.id, after, MARK_BATCH)).filter((one) => one.id <= throughId);
+        if (page.length === 0)
+            break;
+        examined.push(...page);
+        after = page.at(-1)?.id ?? throughId;
+    }
+    const skipped = { ...(mark?.skipped ?? noneSkipped()) };
+    let read = mark?.read ?? 0;
+    const keep = [];
+    const live = new Set(again.map((one) => one.id));
+    for (const id of held)
+        if (!live.has(id))
+            held.delete(id);
+    for (const email of examined) {
+        const said = verdict(email, readAt);
+        const wasHeld = held.has(email.id);
+        if (said === "held" || (said === "read" && email.changedAt > readAt) || (wasHeld && email.changedAt > readAt)) {
+            if (email.partial && now - email.storedAt >= HOLD_PARTIAL_MS)
+                skipped.partial += 1;
+            else
+                keep.push(email.id);
+        }
+        else if (said === "read")
+            read += wasHeld || email.id > from ? 1 : 0;
+        else if (!wasHeld || said === "partial")
+            skipped[said] += 1;
+    }
+    const kept = [...new Set(keep)].sort((a, b) => a - b);
+    skipped.partial += Math.max(0, kept.length - MOST_HELD);
+    const through = examined.filter((one) => one.id <= throughId).at(-1);
+    const next = {
+        throughId,
+        throughAt: through?.id === throughId ? through.at : (mark?.throughAt ?? null),
+        held: kept.slice(-MOST_HELD),
+        read,
+        skipped,
+    };
+    await store.sync.setSyncState(mailbox, key, JSON.stringify(next));
+    return { holder, ...next, updatedAt: now };
+};

package/dist/mail/owed.d.ts

@@ -0,0 +1,11 @@
+import type { NewestEmail } from "../store/store.js";
+/** Whose turn a thread is: the owner owes an answer, waits for one, or neither. */
+export type MailTurn = "owed" | "waiting" | null;
+/**
+ * **The one place that says what the owner owes in mail** (`review --unanswered`, `--waiting`, `tasks agenda`).
+ * Owed: the newest email came in and names the owner in To or Cc. Mail sent to many, lists and envelopes count too
+ * (the owner's ruling: look at all mail); each item carries its marks instead, for the reader to sort. No question
+ * detection. Waiting: the owner wrote last. Mail answered from another client counts, since its copy in Sent or All
+ * Mail is synced.
+ */
+export declare const mailTurn: (newest: NewestEmail | null) => MailTurn;

package/dist/mail/owed.js

@@ -0,0 +1,14 @@
+/**
+ * **The one place that says what the owner owes in mail** (`review --unanswered`, `--waiting`, `tasks agenda`).
+ * Owed: the newest email came in and names the owner in To or Cc. Mail sent to many, lists and envelopes count too
+ * (the owner's ruling: look at all mail); each item carries its marks instead, for the reader to sort. No question
+ * detection. Waiting: the owner wrote last. Mail answered from another client counts, since its copy in Sent or All
+ * Mail is synced.
+ */
+export const mailTurn = (newest) => {
+    if (newest === null)
+        return null;
+    if (newest.outgoing)
+        return "waiting";
+    return newest.addressed ? "owed" : null;
+};

package/dist/mail/review.d.ts

@@ -0,0 +1,37 @@
+import { type Review, type ReviewChat } from "../domain/models.js";
+import type { AccountKey, EmailMarks, MessageStore, NewestEmail, StoredHit } from "../store/store.js";
+/** Every thread is a local read; this many keep one answer readable, and the rest wait in `skipped`. */
+export declare const REVIEW_THREADS = 50;
+/** Without a date, `--unanswered` and `--waiting` look as far back as `tasks agenda` does. */
+export declare const OWED_DAYS = 30;
+export interface MailReviewOptions {
+    /** ms: where a thread with no point of its own starts. */
+    since: number;
+    /** A thread's own start, by its external id. */
+    points?: ReadonlyMap<string, number>;
+    /** Leave out threads whose newest email is mail sent to many, a list's or an envelope (`bulk:false`). */
+    noBulk?: boolean;
+    /** Only threads the owner owes an answer for at least this many hours (`mailTurn`). */
+    unansweredAfterHours?: number;
+    /** Only threads where the owner wrote last and nobody answered for at least this many hours. */
+    waitingAfterHours?: number;
+    now?: number;
+}
+/** A review of mail: each thread a chat, each email a stored hit with its locator. */
+export type MailHit = StoredHit & {
+    marks?: EmailMarks;
+};
+export interface MailReview extends Review {
+    chats: (Omit<ReviewChat, "messages"> & {
+        messages: MailHit[];
+    })[];
+}
+/** Mail sent to many, a list's, or recorded by an envelope rule without its text. */
+export declare const isBulk: (email: NewestEmail) => boolean;
+/**
+ * **Every email, both sides, in each thread that changed since a point** — `review` over the store's mail, in
+ * messenger review's shape: a thread is a chat, an email a message. Reads the store alone, so it costs the mail
+ * server nothing; it opens no task (the owner reviews mail tasks first). Cut where sync proved the mailbox
+ * (`syncedThrough`), so the next review starting at `until` misses nothing sync had stored by then.
+ */
+export declare const reviewMail: (store: MessageStore, mailbox: AccountKey, options: MailReviewOptions) => Promise<MailReview>;