@wirecat/cli-core 0.555.0 → 0.556.0

package/dist/mail/cli/marks.js

@@ -0,0 +1,51 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import * as v from "valibot";
+import { answerEntity } from "../../cli/answer-entity.js";
+import { outputFor } from "../../cli/context.js";
+import { destroysNothing, LOCAL_WRITE } from "../../cli/effects.js";
+import { itemOf, renderAnswer } from "../../cli/envelope.js";
+import { acknowledgeMark } from "../marks.js";
+const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
+/** A holder's mark as `--json`, `mail status` and MCP show it. */
+export const mailMark = v.strictObject({
+    holder: v.string(),
+    through_id: v.number(),
+    through_received_at: v.nullable(v.string()),
+    held: v.number(),
+    read: v.number(),
+    skipped: v.strictObject({ bulk: v.number(), envelope: v.number(), partial: v.number(), draft: v.number() }),
+    updated_at: v.string(),
+});
+export const markItem = (mark) => ({
+    holder: mark.holder,
+    through_id: mark.throughId,
+    through_received_at: iso(mark.throughAt),
+    held: mark.held.length,
+    read: mark.read,
+    skipped: mark.skipped,
+    updated_at: iso(mark.updatedAt),
+});
+export const markText = (mark) => `${mark.holder}  through ${mark.throughId}${mark.throughAt === null ? "" : ` (${iso(mark.throughAt)})`}  ` +
+    `read ${mark.read}  held ${mark.held.length}  skipped bulk ${mark.skipped.bulk}, envelope ${mark.skipped.envelope}, ` +
+    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}  updated ${iso(mark.updatedAt)}\n`;
+/**
+ * `messages acknowledge`: a holder says it is done with what `review --holder` gave it, and its mark moves there. It
+ * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it.
+ */
+export const acknowledgeCommand = (mail) => answerEntity(destroysNothing(annotate(new Command("acknowledge"), {
+    effects: LOCAL_WRITE,
+    examples: [
+        `${mail.app.command} personal messages acknowledge --holder mail-triage --cursor 9123.1762090000000`,
+    ],
+})), "mail_mark", mailMark)
+    .summary("move a holder's processing mark to what it has read")
+    .description("record that a holder — an agent or a pipeline — processed the mail `review --holder` gave it, with the cursor " +
+    "that review gave; the mark only moves forward, and mail still partial waits for the next review")
+    .requiredOption("--holder <name>", "whose mark: lower-case letters, digits and dashes, such as mail-triage")
+    .requiredOption("--cursor <cursor>", "the cursor `review --holder` gave")
+    .action(async function () {
+    const { holder, cursor } = this.opts();
+    const mark = await mail.read(this, (store, mailbox) => acknowledgeMark(store, mailbox, holder, cursor));
+    renderAnswer(this, outputFor(this), itemOf(markItem(mark)), () => markText(mark));
+});

package/dist/mail/cli/review.js

@@ -16,6 +16,7 @@ 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;
@@ -30,6 +31,15 @@ export const MAIL_REVIEW_QUERY = defineQuery({
 });
 /** 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",
@@ -113,6 +123,62 @@ const reviewAnswer = (found, mailbox, fresh) => {
         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.
@@ -136,6 +202,8 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
     .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.
@@ -145,6 +213,8 @@ Mail newer than the last finished sync waits for the next review. Each reader ke
 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")

package/dist/mail/index.d.ts

@@ -6,6 +6,7 @@ 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";

package/dist/mail/index.js

@@ -6,6 +6,7 @@ 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";

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/sends/permissions.js

@@ -276,6 +276,7 @@ const NAMED_WRITE_KEYS = [
     "mentions.reject",
     "tags.add",
     "tags.remove",
+    "tasks.acknowledge",
     "tasks.add",
     "tasks.claim",
     "tasks.close",

package/dist/services/task-analysis.d.ts

@@ -0,0 +1,58 @@
+import type { ChatKind, Id, Message } from "../domain/models.js";
+import type { AccountKey, MessageStore, TaskAnalysisMark } from "../store/index.js";
+/** How many messages one read gives an agent: a page it can judge in one go. */
+export declare const ANALYSIS_PAGE = 100;
+export declare const ANALYSIS_PAGE_MAX = 1000;
+/** Where a chat never read for tasks starts, unless the caller names a time: older history is not new work. */
+export declare const defaultStart: (now: Date) => string;
+export interface ChatAnalysis {
+    chatId: Id;
+    title: string | null;
+    kind: ChatKind;
+    newestAt: string | null;
+    mark: TaskAnalysisMark | null;
+    /** Stored messages after the mark, or since the default start when the chat was never read for tasks. */
+    waiting: number;
+    /** Stored inside the read stretch after it was read: `--since <from>` reads the stretch again. */
+    late: number;
+}
+/**
+ * Every chat whose messages can hold the owner's tasks — not a channel or Saved Messages (owner, 2026-10-17) — with
+ * how far it was read for tasks and how much waits, newest chat first.
+ */
+export declare const taskAnalysisList: (store: MessageStore, account: AccountKey, now?: Date) => Promise<ChatAnalysis[]>;
+export interface UnanalysedPage {
+    mark: TaskAnalysisMark | null;
+    /** Where this read started: the mark, `since`, or the default start. */
+    from: string;
+    messages: Message[];
+    more: boolean;
+    late: number;
+}
+/**
+ * The stored messages of a chat not yet read for tasks, oldest first, from its mark; `since` reads from that time
+ * instead, to read a stretch again. Reading moves nothing: `acknowledgeTaskAnalysis` does, once the reader is done.
+ */
+export declare const unanalysedMessages: (store: MessageStore, account: AccountKey, chatId: Id, { limit, since, now }?: {
+    limit?: number;
+    since?: string;
+    now?: Date;
+}) => Promise<UnanalysedPage>;
+/**
+ * Records that the chat was read for tasks through `messageId`, from `since` when that read started there. The mark
+ * never moves back. A read that covered the whole stretch again also clears what arrived late inside it.
+ */
+export declare const acknowledgeTaskAnalysis: (store: MessageStore, account: AccountKey, chatId: Id, messageId: Id, { since, by, now }: {
+    since?: string;
+    by: string;
+    now?: Date;
+}) => Promise<{
+    mark: TaskAnalysisMark;
+    moved: boolean;
+}>;
+/**
+ * A read again of history the chat's task point already passed only updates and closes tasks (owner, 2026-11-03):
+ * a new task from such a message needs `--open-new`. A message that already has a task, or one after the point, is
+ * let through.
+ */
+export declare const refuseAlreadyRead: (store: MessageStore, account: AccountKey, source: string) => Promise<void>;

package/dist/services/task-analysis.js

@@ -0,0 +1,125 @@
+import { CliError } from "@wirecat/cli-base";
+import { isLocator, parseLocator } from "../domain/locator.js";
+import { FIRST_PASS_DAYS, RULES_IN, taskAccount } from "./task-rules.js";
+/** How many messages one read gives an agent: a page it can judge in one go. */
+export const ANALYSIS_PAGE = 100;
+export const ANALYSIS_PAGE_MAX = 1000;
+/** Where a chat never read for tasks starts, unless the caller names a time: older history is not new work. */
+export const defaultStart = (now) => new Date(now.getTime() - FIRST_PASS_DAYS * 86_400_000).toISOString();
+const after = (iso) => new Date(Date.parse(iso) + 1).toISOString();
+/** Messages saved or edited after the mark was last checked, sent inside the stretch it had read. */
+const lateOf = async (store, account, mark) => {
+    const { messages } = await store.messages.changes(account, mark.chatId, mark.checkedAt);
+    return messages.filter((one) => one.timestamp >= mark.from && one.timestamp <= mark.checkedThrough);
+};
+/**
+ * Every chat whose messages can hold the owner's tasks — not a channel or Saved Messages (owner, 2026-10-17) — with
+ * how far it was read for tasks and how much waits, newest chat first.
+ */
+export const taskAnalysisList = async (store, account, now = new Date()) => {
+    const marks = new Map((await store.sync.taskAnalysisMarks(account)).map((mark) => [mark.chatId, mark]));
+    const start = defaultStart(now);
+    const chats = [];
+    for (const chat of await store.chats.chatStats(account)) {
+        if (RULES_IN[chat.kind] === "none")
+            continue;
+        const mark = marks.get(chat.chatId) ?? null;
+        chats.push({
+            chatId: chat.chatId,
+            title: chat.title,
+            kind: chat.kind,
+            newestAt: chat.newestAt,
+            mark,
+            waiting: await store.messages.countMessages(account, chat.chatId, { since: mark ? after(mark.through) : start }),
+            late: mark ? (await lateOf(store, account, mark)).length : 0,
+        });
+    }
+    return chats.sort((a, b) => (b.newestAt ?? "").localeCompare(a.newestAt ?? ""));
+};
+/**
+ * The stored messages of a chat not yet read for tasks, oldest first, from its mark; `since` reads from that time
+ * instead, to read a stretch again. Reading moves nothing: `acknowledgeTaskAnalysis` does, once the reader is done.
+ */
+export const unanalysedMessages = async (store, account, chatId, { limit = ANALYSIS_PAGE, since, now = new Date() } = {}) => {
+    const mark = (await store.sync.taskAnalysisMark(account, chatId)) ?? null;
+    const from = since ?? mark?.through ?? defaultStart(now);
+    const byTime = { time: Date.parse(from) - (since === undefined && mark ? 0 : 1) };
+    const read = (start) => store.messages.messages(account, chatId, { limit, after: start });
+    let page;
+    if (since === undefined && mark) {
+        try {
+            page = await read({ id: mark.throughId });
+        }
+        catch (error) {
+            if (!(error instanceof CliError && error.code === "not_found"))
+                throw error;
+            page = await read(byTime);
+        }
+    }
+    else
+        page = await read(byTime);
+    return {
+        mark,
+        from,
+        messages: page.items,
+        more: page.hasMore,
+        late: mark ? (await lateOf(store, account, mark)).length : 0,
+    };
+};
+/**
+ * Records that the chat was read for tasks through `messageId`, from `since` when that read started there. The mark
+ * never moves back. A read that covered the whole stretch again also clears what arrived late inside it.
+ */
+export const acknowledgeTaskAnalysis = async (store, account, chatId, messageId, { since, by, now = new Date() }) => {
+    const message = await store.messages.message(account, messageId, { chatId });
+    if (!message)
+        throw new CliError("not_found", `message ${messageId} is not in the local copy of chat ${chatId}`);
+    const mark = await store.sync.taskAnalysisMark(account, chatId);
+    const start = since ?? mark?.from ?? defaultStart(now);
+    if (message.timestamp < start)
+        throw new CliError("validation_error", `message ${messageId} was sent before the read started (${start})`);
+    if (mark && message.timestamp < mark.from)
+        throw new CliError("validation_error", `message ${messageId} ends before the stretch already read (${mark.from}): read on to it, then acknowledge`);
+    const ahead = !mark || message.timestamp > mark.through || (since !== undefined && message.timestamp >= mark.through);
+    if (mark && !ahead && start >= mark.from)
+        return { mark, moved: false };
+    const reread = mark !== undefined && since !== undefined && since <= mark.from && ahead;
+    const checked = !mark || reread || (since === undefined && (await lateOf(store, account, mark)).length === 0);
+    const through = mark && !ahead ? mark : { through: message.timestamp, throughId: message.id };
+    const next = {
+        chatId,
+        from: mark && mark.from < start ? mark.from : start,
+        through: through.through,
+        throughId: through.throughId,
+        by,
+        checked,
+        checkedThrough: checked || !mark ? through.through : mark.checkedThrough,
+    };
+    await store.sync.setTaskAnalysisMark(account, next);
+    const saved = await store.sync.taskAnalysisMark(account, chatId);
+    if (!saved)
+        throw new Error(`the task analysis mark of chat ${chatId} was not saved`);
+    return { mark: saved, moved: true };
+};
+/**
+ * A read again of history the chat's task point already passed only updates and closes tasks (owner, 2026-11-03):
+ * a new task from such a message needs `--open-new`. A message that already has a task, or one after the point, is
+ * let through.
+ */
+export const refuseAlreadyRead = async (store, account, source) => {
+    if (!isLocator(source))
+        return;
+    const { provider, account: owner, chat, message } = parseLocator(source);
+    if (provider !== account.provider || owner !== account.account)
+        return;
+    const mark = await store.sync.taskAnalysisMark(account, chat);
+    if (!mark)
+        return;
+    const stored = await store.messages.message(account, message, { chatId: chat });
+    if (!stored || stored.timestamp > mark.through)
+        return;
+    if ((await store.tasks.findBySource(taskAccount(account), source)).length > 0)
+        return;
+    throw new CliError("validation_error", `${source} was already read for tasks (the point is at ${mark.through}): a read again only updates and closes ` +
+        "tasks; add --open-new to open a task from it anyway", { reason: "task.already-read" });
+};

package/dist/store/exports.d.ts

@@ -23,7 +23,7 @@ export { storeClients } from "./sqlite/clients.js";
 export { CHAT_LIST_KEY, type ChatCompleteness, fetchedKey, historyStartKey } from "./sqlite/completeness.js";
 export { CONVERSATION_COLUMNS } from "./sqlite/conversations.js";
 export type { CounterTarget } from "./sqlite/counters.js";
-export { type EmailMarks, MAIL_AGENDA_COLUMNS, type NewestEmail, type ThreadActivity, } from "./sqlite/email-activity.js";
+export { type EmailMarks, MAIL_AGENDA_COLUMNS, type MarkedEmail, type NewestEmail, type ThreadActivity, } from "./sqlite/email-activity.js";
 export { messageOfEmail, threadConversation } from "./sqlite/emails.js";
 export { orphanPointers } from "./sqlite/entity-types.js";
 export { involvementStoreOver } from "./sqlite/involvements.js";
@@ -61,5 +61,5 @@ export type { MatchPlace, ScoredHit } from "./sqlite/words.js";
 export type { TaskDetails } from "./sqlite/work-tasks.js";
 export type { SyncStore } from "./sync.js";
 export type { TagsStore } from "./tags.js";
-export type { AccountKey, AccountMessageFilter, AgentAnswer, BatchMessage, ChatActivity, ChatStats, ConversationBuild, ConversationHit, ConversationSummary, DeletionScope, Delta, IdentityRef, IngestedVia, LinkBatch, LinkedIdentity, LinkOptions, MessageFilter, PersonFacts, PersonRecord, PictureInput, Range, SenderChatStats, StoredAccount, StoredChatFilter, StoredHit, StoredLink, StoredReadiness, } from "./types.js";
+export type { AccountKey, AccountMessageFilter, AgentAnswer, BatchMessage, ChatActivity, ChatStats, ConversationBuild, ConversationHit, ConversationSummary, DeletionScope, Delta, IdentityRef, IngestedVia, LinkBatch, LinkedIdentity, LinkOptions, MessageFilter, PersonFacts, PersonRecord, PictureInput, Range, SenderChatStats, StoredAccount, StoredChatFilter, StoredHit, StoredLink, StoredReadiness, TaskAnalysisMark, TaskAnalysisMarkWrite, } from "./types.js";
 export type { AccountVectors, VectorsStore } from "./vectors.js";

package/dist/store/index.d.ts

@@ -71,4 +71,4 @@ export type { StoreTaskStore } from "./sqlite/tasks.js";
 export type { TagPreflight, VocabularyAlias, VocabularyAliasReceipt, VocabularyAudit, VocabularyAuditOptions, VocabularyCatalog, VocabularyEntry, VocabularyKind, VocabularyOptions, VocabularyResolution, VocabularyStore, VocabularyTarget, } from "./sqlite/vocabulary.js";
 export type { BoardCounts, BoardOptions, NewWorkTask, RevisionCheck, TaskAssignment, TaskDetails, TaskEvent, TaskFields, TaskMove, TaskMoved, TaskRole, TaskType, WorkTaskType, } from "./sqlite/work-tasks.js";
 export { TASK_EVENT_KINDS, TASK_ROLES } from "./sqlite/work-tasks.js";
-export { type AccountAccounts, type AccountAttachments, type AccountCounters, type AccountKey, type AccountMentions, type AccountMessageFilter, type AccountMessages, type AccountPeople, type AccountsStore, type AccountVectors, type AttachmentsStore, type AttachmentTextEntry, type AttachmentView, type ChatStats, type ChatsStore, type ConversationsStore, type CountersStore, type DeletionScope, type Delta, type FileAttachment, type IdentityRef, type IngestedVia, type LinkedIdentity, type LinkOptions, MENTION_QUERY, MENTION_STATUSES, type MentionsStore, type MessageFilter, type MessageStore, type MessagesStore, OTHER_SOURCES, openStore, type PeopleStore, type PersonFacts, type PersonRecord, type QueriesStore, type Range, type RankedEvidence, type RankedStoreFound, type RankedStoreRow, type RankingEvidenceItem, type RankingEvidenceRequest, type RankingRequest, type RosterStore, type SearchCommand, type SearchesStore, type SearchIndexStore, type SearchRecord, type StoredAccount, type StoredChatFilter, type StoredHit, type StoredSearch, type StoredTag, type StoreOptions, type SyncStore, type TagFilter, type TagsStore, type TagTarget, type TaskTagTarget, type TextOrigin, type VectorsStore, } from "./store.js";
+export { type AccountAccounts, type AccountAttachments, type AccountCounters, type AccountKey, type AccountMentions, type AccountMessageFilter, type AccountMessages, type AccountPeople, type AccountsStore, type AccountVectors, type AttachmentsStore, type AttachmentTextEntry, type AttachmentView, type ChatStats, type ChatsStore, type ConversationsStore, type CountersStore, type DeletionScope, type Delta, type FileAttachment, type IdentityRef, type IngestedVia, type LinkedIdentity, type LinkOptions, MENTION_QUERY, MENTION_STATUSES, type MentionsStore, type MessageFilter, type MessageStore, type MessagesStore, OTHER_SOURCES, openStore, type PeopleStore, type PersonFacts, type PersonRecord, type QueriesStore, type Range, type RankedEvidence, type RankedStoreFound, type RankedStoreRow, type RankingEvidenceItem, type RankingEvidenceRequest, type RankingRequest, type RosterStore, type SearchCommand, type SearchesStore, type SearchIndexStore, type SearchRecord, type StoredAccount, type StoredChatFilter, type StoredHit, type StoredSearch, type StoredTag, type StoreOptions, type SyncStore, type TagFilter, type TagsStore, type TagTarget, type TaskAnalysisMark, type TaskAnalysisMarkWrite, type TaskTagTarget, type TextOrigin, type VectorsStore, } from "./store.js";