@wirecat/cli-core 0.567.0 → 0.569.0

package/dist/errors/reasons.js

@@ -58,6 +58,7 @@ const OTHERS = [
     validation("meeting-findings.dedicated-review", "review meeting findings through the dedicated findings command"),
     validation("evidence-findings.stale", "evidence findings changed since they were read; stage a new batch"),
     validation("mail-findings.stale", "mail findings cite mail that changed since it was read; stage a new batch"),
+    ["mail-findings.not-stored", "not_found", "a mail finding cites an email the store does not hold"],
     validation("mail-findings.partial", "a cited email is not stored whole yet; cite it once it is"),
     validation("evidence-findings.dedicated-review", "review evidence findings through the dedicated findings command"),
     validation("mail-findings.dedicated-review", "review mail findings through the dedicated findings command"),
@@ -66,6 +67,8 @@ const OTHERS = [
     ["extraction.invalid-proposals", "invalid_response", "the model's memory proposals could not be used"],
     validation("extraction.text-too-long", "the text is too long for memory extraction"),
     validation("file.locked", "another process holds the file's lock"),
+    validation("mail.cursor-ahead", "an acknowledge cursor is past the newest stored email"),
+    ["mail.holder-not-yours", "permission_error", "a run moves only the mark of the holder its schedule names"],
     ["mail.source-failed", "provider_error", "the mail server refused or did not complete a request"],
     ["mail.search-refused", "provider_error", "the mail server refused to search a folder"],
     [

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

@@ -22,6 +22,7 @@ export declare const markItem: (mark: MailMark) => v.InferOutput<typeof mailMark
 export declare const markText: (mark: MailMark) => string;
 /**
  * `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.
+ * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it — for the holder its
+ * schedule names only: an email that talks its reader into acknowledging would otherwise silence another pipeline.
  */
 export declare const acknowledgeCommand: (mail: MailReads) => Command;

package/dist/mail/cli/marks.js

@@ -1,10 +1,13 @@
+import { CliError } from "@wirecat/cli-base";
 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 { actorOf } from "../../cli/author.js";
+import { environmentOf, outputFor } from "../../cli/context.js";
 import { LOCAL_WRITE, proposesOnly } from "../../cli/effects.js";
 import { itemOf, renderAnswer } from "../../cli/envelope.js";
+import { mailHolderVariable, readOnlyLockOf } from "../../ports/app.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. */
@@ -38,7 +41,8 @@ export const markText = (mark) => `${mark.holder}  through ${mark.throughId}${ma
     `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.
+ * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it — for the holder its
+ * schedule names only: an email that talks its reader into acknowledging would otherwise silence another pipeline.
  */
 export const acknowledgeCommand = (mail) => answerEntity(proposesOnly(annotate(new Command("acknowledge"), {
     effects: LOCAL_WRITE,
@@ -53,6 +57,13 @@ export const acknowledgeCommand = (mail) => answerEntity(proposesOnly(annotate(n
     .requiredOption("--cursor <cursor>", "the cursor `review --holder` gave")
     .action(async function () {
     const { holder, cursor } = this.opts();
+    const env = environmentOf(this).env ?? process.env;
+    const named = env[mailHolderVariable(mail.app)]?.trim();
+    const owner = actorOf(this) === "owner" && !readOnlyLockOf(mail.app, env);
+    if (named ? named !== holder : !owner)
+        throw new CliError("permission_error", named
+            ? `this run moves only ${named}'s mark, not ${holder}'s`
+            : `an agent moves only the mark of the holder its schedule names (schedule agent --on-new-mail ${holder}); the owner moves any`, { reason: "mail.holder-not-yours" });
     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

@@ -90,14 +90,16 @@ const reviewAnswer = (found, mailbox, fresh, step) => {
     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 wholeThreads = cut.flatMap((chat) => step("mail-conversations.show", { conversation: ref(chat.id) }));
+    const [first, ...rest] = cut.map((chat) => ref(chat.id));
+    const wholeThread = first === undefined ? [] : step("mail-conversations.show", { conversation: first });
     const missing = [
-        ...(cut.length > 0
+        ...(first !== undefined
             ? [
                 {
                     field: "items",
-                    why: `only the newest emails of ${cut.length} thread(s)`,
-                    ...(wholeThreads.length ? { step: "mail-conversations.show" } : {}),
+                    why: `only the newest emails of ${cut.length} thread(s)` +
+                        (rest.length ? `; read the others whole the same way: ${rest.join(", ")}` : ""),
+                    ...(wholeThread.length ? { step: "mail-conversations.show" } : {}),
                 },
             ]
             : []),
@@ -117,7 +119,7 @@ const reviewAnswer = (found, mailbox, fresh, step) => {
         ...(!fresh && !turns
             ? step("mail-review.next", { query: `date>${quoted(found.complete ? found.until : found.since)}` })
             : []),
-        ...wholeThreads,
+        ...wholeThread,
     ];
     return listOf("review", {
         items: read.map((message) => ({

package/dist/mail/index.d.ts

@@ -9,7 +9,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, holderHasMail, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.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 { 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,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, holderHasMail, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
+export { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, mailWaiting, 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

@@ -17,6 +17,8 @@ export interface MailMark {
     /** ms: when the email at `throughId` was received; for display. */
     throughAt: number | null;
     held: number[];
+    /** Emails skipped while their sender looked suspicious; offered again once the sender's score is cleared. */
+    suspicious: number[];
     read: number;
     skipped: Record<SkipReason, number>;
     /** ms. */
@@ -48,13 +50,27 @@ export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, ho
     now?: number;
     limit?: number;
 }) => 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 {
+    /** No mark yet in some mailbox: the holder's first run sets it. */
+    unmarked: boolean;
+    emails: number;
+    /** ms. */
+    oldestStoredAt: number | null;
+}
+/**
+ * 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.
+ */
+export declare const mailWaiting: (store: MessageStore, holder: string, now?: number) => Promise<MailWaiting>;
 /**
- * Whether the holder has mail to read in any stored mailbox — what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Mail that is only skipped (bulk, envelopes, drafts,
- * suspicious senders) moves the holder's mark here, as the agent would have acknowledged it, or it would wait
- * forever behind the mark. A holder with no mark yet has mail to read: its first run sets the mark.
+ * 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
+ * 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 holderHasMail: (store: MessageStore, holder: string, now?: number) => Promise<boolean>;
+export declare const advancePastSkipped: (store: MessageStore, holder: string, now?: number) => Promise<void>;
 /**
  * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
  * still partial, or changed after the read (it may have become whole since), is held and comes with the next read.

package/dist/mail/marks.js

@@ -1,12 +1,15 @@
 import { CliError } from "@wirecat/cli-base";
+import { isBusy } from "../store/sqlite/transaction.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. */
 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. */
+/** Held, or suspicious, emails kept on one mark at most; past it the oldest are dropped. */
 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 keyOf = (holder) => {
@@ -24,6 +27,7 @@ const parsed = (holder, value, at) => {
             throughId: saved.throughId,
             throughAt: saved.throughAt ?? null,
             held: Array.isArray(saved.held) ? saved.held.filter((id) => typeof id === "number") : [],
+            suspicious: Array.isArray(saved.suspicious) ? saved.suspicious.filter((id) => typeof id === "number") : [],
             read: saved.read ?? 0,
             skipped: { ...noneSkipped(), ...saved.skipped },
             updatedAt: at,
@@ -79,34 +83,38 @@ const parseCursor = (cursor) => {
  * empty and gives the cursor of the newest stored email.
  */
 export const readPastMark = async (store, mailbox, holder, options = {}) => {
-    const { wanted, ...read } = await examine(store, mailbox, holder, options);
+    const { wanted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
     return { emails: await store.mail.emailHits(wanted), ...read };
 };
 /** `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 }) => {
-    const mark = await markOf(store, mailbox, holder);
+const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH, after }) => {
+    const saved = await markOf(store, mailbox, holder);
     const account = await accountOf(store, mailbox);
-    const empty = { wanted: [], more: false, held: 0, skipped: noneSkipped(), mark };
+    const empty = { wanted: [], oldestStoredAt: null, more: false, held: 0, skipped: noneSkipped(), mark: saved };
     if (!account)
         return { ...empty, cursor: cursorOf(0, now) };
-    if (!mark)
+    if (!saved)
         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);
+    const mark = after === undefined ? saved : { ...saved, throughId: after, held: [], suspicious: [] };
+    const found = await store.mail.emailsAfter(account.id, mark.throughId, limit + 1, [...mark.held, ...mark.suspicious]);
     // 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 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 examined = [...found.filter((email) => email.id <= mark.throughId), ...batch];
     const skipped = noneSkipped();
     const wanted = [];
+    let oldestStoredAt = null;
     let held = 0;
     for (const email of examined) {
         const said = verdict(email, now);
-        if (said === "read")
+        if (said === "read") {
             wanted.push(email.id);
+            oldestStoredAt = Math.min(oldestStoredAt ?? email.storedAt, email.storedAt);
+        }
         else if (said === "held")
             held += 1;
         else if (email.id > mark.throughId)
@@ -114,35 +122,68 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     }
     return {
         wanted: wanted.sort((a, b) => a - b),
+        oldestStoredAt,
         cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
-        more: after.length > batch.length,
+        more: newer.length > batch.length,
         held,
         skipped,
-        mark,
+        mark: saved,
     };
 };
 /**
- * Whether the holder has mail to read in any stored mailbox — what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Mail that is only skipped (bulk, envelopes, drafts,
- * suspicious senders) moves the holder's mark here, as the agent would have acknowledged it, or it would wait
- * forever behind the mark. A holder with no mark yet has mail to read: its first run sets the 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.
+ */
+export const mailWaiting = async (store, holder, now = Date.now()) => {
+    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 }) });
+            if (!read.mark) {
+                waiting.unmarked = true;
+                break;
+            }
+            waiting.emails += read.wanted.length;
+            if (read.oldestStoredAt !== null)
+                waiting.oldestStoredAt = Math.min(waiting.oldestStoredAt ?? read.oldestStoredAt, read.oldestStoredAt);
+            const through = Number(read.cursor.split(".")[0]);
+            if (!read.more || through === (after ?? read.mark.throughId))
+                break;
+            after = through;
+        }
+    }
+    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
+ * 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 holderHasMail = async (store, holder, now = Date.now()) => {
+export const advancePastSkipped = async (store, holder, now = Date.now()) => {
     for (const mailbox of await store.accounts.accounts()) {
         if (mailbox.provider !== "email")
             continue;
         for (;;) {
             const read = await examine(store, mailbox, holder, { now });
-            if (!read.mark || read.wanted.length > 0)
-                return true;
-            if (read.cursor === cursorOf(read.mark.throughId, now))
+            if (!read.mark || read.wanted.length > 0 || read.cursor === cursorOf(read.mark.throughId, now))
                 break;
-            await acknowledgeMark(store, mailbox, holder, read.cursor, now);
+            try {
+                await acknowledgeMark(store, mailbox, holder, read.cursor, now);
+            }
+            catch (error) {
+                if (isBusy(error))
+                    return;
+                throw error;
+            }
             if (!read.more)
                 break;
         }
     }
-    return false;
 };
 /**
  * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
@@ -155,6 +196,11 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
     const account = await accountOf(store, mailbox);
     if (!account)
         throw new CliError("not_found", `no mail of ${mailbox.account} is stored`);
+    const newest = await store.mail.newestEmailId(account.id);
+    if (throughId > newest || readAt > now + CLOCK_SLACK_MS)
+        throw new CliError("validation_error", `--cursor ${cursor} is past the newest stored email; acknowledge a cursor review gave`, {
+            reason: "mail.cursor-ahead",
+        });
     const mark = await markOf(store, mailbox, holder);
     const from = mark?.throughId ?? throughId;
     if (throughId < from)
@@ -162,7 +208,8 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
     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]);
+    const doubted = new Set(mark?.suspicious ?? []);
+    const again = await store.mail.emailsAfter(account.id, Number.MAX_SAFE_INTEGER, 0, [...held, ...doubted]);
     examined.push(...again);
     while (after < throughId) {
         const page = (await store.mail.emailsAfter(account.id, after, MARK_BATCH)).filter((one) => one.id <= throughId);
@@ -174,6 +221,7 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
     const skipped = { ...(mark?.skipped ?? noneSkipped()) };
     let read = mark?.read ?? 0;
     const keep = [];
+    const suspicious = [];
     const live = new Set(again.map((one) => one.id));
     for (const id of held)
         if (!live.has(id))
@@ -181,6 +229,7 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
     for (const email of examined) {
         const said = verdict(email, readAt);
         const wasHeld = held.has(email.id);
+        const wasDoubted = doubted.has(email.id) && !wasHeld;
         if (said === "held" || (said === "read" && email.changedAt > readAt) || (wasHeld && email.changedAt > readAt)) {
             if (email.partial && now - email.storedAt >= HOLD_PARTIAL_MS)
                 skipped.partial += 1;
@@ -188,8 +237,13 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
                 keep.push(email.id);
         }
         else if (said === "read")
-            read += wasHeld || email.id > from ? 1 : 0;
-        else if (!wasHeld || said === "partial")
+            read += wasHeld || wasDoubted || email.id > from ? 1 : 0;
+        else if (said === "suspicious") {
+            suspicious.push(email.id);
+            if (!wasDoubted && !wasHeld)
+                skipped.suspicious += 1;
+        }
+        else if (!wasDoubted && (!wasHeld || said === "partial"))
             skipped[said] += 1;
     }
     const kept = [...new Set(keep)].sort((a, b) => a - b);
@@ -199,6 +253,7 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
         throughId,
         throughAt: through?.id === throughId ? through.at : (mark?.throughAt ?? null),
         held: kept.slice(-MOST_HELD),
+        suspicious: [...new Set(suspicious)].sort((a, b) => a - b).slice(-MOST_HELD),
         read,
         skipped,
     };

package/dist/meetings/findings-rules.d.ts

@@ -59,7 +59,9 @@ export interface FindingsReceipt {
     accepted: string[];
     items: FindingOutcome[];
 }
+export declare const findingText: (value: unknown, limit: number) => string;
 export declare const findingHash: (value: unknown) => string;
+export declare const findingFields: (value: object, allowed: string[], noun: string) => void;
 /** What differs between findings kinds: their wording and what one cited reference must look like. */
 export interface FindingsRules {
     /** "meeting findings" */
@@ -97,7 +99,5 @@ export declare const validateBatch: <F>(input: {
     findings: F[];
 };
 export declare const validateFindings: (input: FindingsInput, rules: FindingsRules) => FindingsInput;
-export declare const findingText: (value: unknown, limit: number) => string;
-export declare const findingFields: (value: object, allowed: string[], noun: string) => void;
 export declare const findingFingerprint: ({ id: _id, ...finding }: Finding) => string;
 export {};

package/dist/meetings/findings-rules.js

@@ -6,13 +6,13 @@ const TASK_TYPES = ["bug", "feature", "chore"];
 const invalid = (message) => {
     throw new CliError("validation_error", message);
 };
-const text = (value, limit) => {
+export const findingText = (value, limit) => {
     if (typeof value !== "string" || !value.trim() || value.includes("\0") || value.length > limit)
         return invalid(`finding text must contain 1–${limit} characters without NUL`);
     return value.trim();
 };
 export const findingHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const fields = (value, allowed, noun) => {
+export const findingFields = (value, allowed, noun) => {
     if (Object.keys(value).some((key) => !allowed.includes(key)))
         invalid(`unknown ${noun} field`);
 };
@@ -25,7 +25,7 @@ export const validEvidence = (raw, rules) => {
         .map((item) => {
         if (!item || typeof item !== "object")
             return invalid("finding evidence is a reference and fingerprint");
-        fields(item, ["reference", "fingerprint"], rules.singular);
+        findingFields(item, ["reference", "fingerprint"], rules.singular);
         if (typeof item.reference !== "string" || typeof item.fingerprint !== "string")
             return invalid("evidence requires a reference and fingerprint");
         const reference = rules.reference(item.reference);
@@ -51,10 +51,10 @@ export const validateFinding = (finding, rules, ids) => {
     if (!finding || typeof finding !== "object")
         return invalid("a finding is an object");
     const id = findingId(finding.id, ids);
-    const project = finding.project === undefined && rules.anySubject ? undefined : text(finding.project, 64);
+    const project = finding.project === undefined && rules.anySubject ? undefined : findingText(finding.project, 64);
     if (project !== undefined && !/^project:[1-9]\d*$/.test(project))
         return invalid("a finding names a project reference");
-    if (finding.subject !== undefined && (!rules.anySubject || !SUBJECT.test(text(finding.subject, 80))))
+    if (finding.subject !== undefined && (!rules.anySubject || !SUBJECT.test(findingText(finding.subject, 80))))
         return invalid("a finding's subject is a person:, organization:, task: or project: reference");
     if (finding.kind === "task" && project === undefined && !rules.inboxTasks)
         return invalid("a task finding names the project the task goes in");
@@ -66,15 +66,15 @@ export const validateFinding = (finding, rules, ids) => {
         evidence,
     };
     if (finding.kind === "fact") {
-        fields(finding, ["id", "project", "subject", "evidence", "kind", "type", "statement"], rules.singular);
+        findingFields(finding, ["id", "project", "subject", "evidence", "kind", "type", "statement"], rules.singular);
         if (finding.type === "payment")
             return invalid("a payment is a finding of kind payment; money is a payments row, not a fact");
         if (!FACT_TYPES.includes(finding.type))
             return invalid("unknown fact finding type");
-        return { ...base, kind: "fact", type: finding.type, statement: text(finding.statement, 2000) };
+        return { ...base, kind: "fact", type: finding.type, statement: findingText(finding.statement, 2000) };
     }
     if (finding.kind === "payment" && rules.payments) {
-        fields(finding, ["id", "project", "subject", "evidence", "kind", "statement", "payment", "supersedes"], rules.singular);
+        findingFields(finding, ["id", "project", "subject", "evidence", "kind", "statement", "payment", "supersedes"], rules.singular);
         if (finding.supersedes !== undefined && !/^invoice:[1-9]\d*$/.test(String(finding.supersedes)))
             return invalid("a payment finding supersedes an invoice: reference, the expected payment it settles or voids");
         const payment = validatePayment(finding.payment);
@@ -87,14 +87,14 @@ export const validateFinding = (finding, rules, ids) => {
         return {
             ...base,
             kind: "payment",
-            ...(finding.statement === undefined ? {} : { statement: text(finding.statement, 2000) }),
+            ...(finding.statement === undefined ? {} : { statement: findingText(finding.statement, 2000) }),
             payment,
             ...(finding.supersedes === undefined ? {} : { supersedes: finding.supersedes }),
         };
     }
     if (finding.kind !== "task")
         return invalid(`a finding is a fact${rules.payments ? ", payment" : ""} or task`);
-    fields(finding, [
+    findingFields(finding, [
         "id",
         "project",
         "evidence",
@@ -122,8 +122,8 @@ export const validateFinding = (finding, rules, ids) => {
         ...base,
         kind: "task",
         type: finding.type,
-        title: text(finding.title, 300),
-        reason: text(finding.reason, 2000),
+        title: findingText(finding.title, 300),
+        reason: findingText(finding.reason, 2000),
         commitment: finding.commitment,
         ...(finding.dueAt === undefined
             ? {}
@@ -149,20 +149,18 @@ export const support = (value, evidence) => {
 export const validateBatch = (input, rules, most, one) => {
     if (!input || typeof input !== "object" || Buffer.byteLength(JSON.stringify(input), "utf8") > 65536)
         return invalid(`${rules.plural} take at most 65536 UTF-8 bytes`);
-    fields(input, ["schemaVersion", "key", "extractor", "findings"], rules.singular);
+    findingFields(input, ["schemaVersion", "key", "extractor", "findings"], rules.singular);
     if (input.schemaVersion !== 1 ||
         !Array.isArray(input.findings) ||
         input.findings.length < 1 ||
         input.findings.length > most)
         return invalid(`schemaVersion 1 takes 1–${most} ${rules.plural}`);
-    const key = text(input.key, 64);
+    const key = findingText(input.key, 64);
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/.test(key))
         return invalid("a findings key uses letters, digits, dot, colon, underscore or hyphen");
     const ids = new Set();
     const findings = input.findings.map((finding) => one(finding, ids));
-    return { schemaVersion: 1, key, extractor: text(input.extractor, 200), findings };
+    return { schemaVersion: 1, key, extractor: findingText(input.extractor, 200), findings };
 };
 export const validateFindings = (input, rules) => validateBatch(input, rules, 16, (finding, ids) => validateFinding(finding, rules, ids));
-export const findingText = (value, limit) => text(value, limit);
-export const findingFields = (value, allowed, noun) => fields(value, allowed, noun);
 export const findingFingerprint = ({ id: _id, ...finding }) => findingHash(finding);

package/dist/ports/app.d.ts

@@ -38,6 +38,8 @@ export interface AppIdentity {
 export declare const envName: (app: AppIdentity, name: string) => string;
 /** The variable that locks this process read-only, when it is set to anything but "0". */
 export declare const readOnlyLockOf: (app: AppIdentity, env: NodeJS.ProcessEnv) => string | undefined;
+/** The holder a scheduled run was started for (`schedule agent --on-new-mail`): the only mark that run may move. */
+export declare const mailHolderVariable: (app: AppIdentity) => string;
 export declare const MESSENGER_CHANGE_REFUSAL = "send, react, change chats or change the account";
 /** The one wording for a write `<PREFIX>_READ_ONLY` stops: `what` finishes "it cannot …". */
 export declare const readOnlyRefusal: (lock: string, what: string) => CliError;

package/dist/ports/app.js

@@ -6,6 +6,8 @@ export const readOnlyLockOf = (app, env) => {
     const value = env[name];
     return value === undefined || value.trim() === "" || value === "0" ? undefined : name;
 };
+/** The holder a scheduled run was started for (`schedule agent --on-new-mail`): the only mark that run may move. */
+export const mailHolderVariable = (app) => envName(app, "MAIL_HOLDER");
 export const MESSENGER_CHANGE_REFUSAL = "send, react, change chats or change the account";
 /** The one wording for a write `<PREFIX>_READ_ONLY` stops: `what` finishes "it cannot …". */
 export const readOnlyRefusal = (lock, what) => new CliError("permission_error", `this process is read-only (${lock}) — it cannot ${what}`);

package/dist/services/proposals/kinds/mail-findings.d.ts

@@ -1,8 +1,9 @@
 import { type MessageStore } from "../../../store/index.js";
 import type { ProposalKind } from "../types.js";
 /**
- * What an agent read in new mail, one batch per mailbox and run. Only the owner decides it (NEED-2187): an agent's
- * confirmation is refused whatever `agent_decisions` says. Confirming accepts the parts named, or every finding not
+ * What an agent read in new mail, one batch per mailbox and run. Only the owner decides it — mail is text a stranger
+ * wrote, so an agent that read it must not also approve what it made of it: an agent's confirmation is refused
+ * whatever `agent_decisions` says. Confirming accepts the parts named, or every finding not
  * rejected before; the rest are rejected.
  */
 export declare const mailFindingsKind: (store: Pick<MessageStore, "mailFindings" | "proposedActions">) => ProposalKind;

package/dist/services/proposals/kinds/mail-findings.js

@@ -44,8 +44,9 @@ const rowOf = (batch, createdAt) => {
     };
 };
 /**
- * What an agent read in new mail, one batch per mailbox and run. Only the owner decides it (NEED-2187): an agent's
- * confirmation is refused whatever `agent_decisions` says. Confirming accepts the parts named, or every finding not
+ * What an agent read in new mail, one batch per mailbox and run. Only the owner decides it — mail is text a stranger
+ * wrote, so an agent that read it must not also approve what it made of it: an agent's confirmation is refused
+ * whatever `agent_decisions` says. Confirming accepts the parts named, or every finding not
  * rejected before; the rest are rejected.
  */
 export const mailFindingsKind = (store) => {

package/dist/store/sqlite/mail-findings.js

@@ -82,9 +82,10 @@ export const mailFindingsStoreOver = (context) => {
     };
     /**
      * Reads each cited email once: it must be stored, whole, and hash to the fingerprint given. Every finding cites
-     * mail of the batch's own mailbox, and no sender other than the owner is behind more than five findings.
+     * mail of the batch's own mailbox, and no sender other than the owner is behind more than five findings. An email
+     * gone by the time the owner decides changed since it was read; one never stored was never read.
      */
-    const cite = (findings, account) => {
+    const cite = (findings, account, deciding = false) => {
         const read = new Map();
         const perSender = new Map();
         let bytes = 0;
@@ -96,8 +97,12 @@ export const mailFindingsStoreOver = (context) => {
                 if (!row) {
                     const at = parseLocator(reference);
                     row = database.prepare(EMAIL).get(at.account, at.chat, at.message);
-                    if (!row)
+                    if (!row && deciding)
                         return stale();
+                    if (!row)
+                        throw new CliError("not_found", `no stored email ${reference}; cite only mail a review gave`, {
+                            reason: "mail-findings.not-stored",
+                        });
                     bytes += Buffer.byteLength(String(row.body)) + Buffer.byteLength(String(row.subject ?? ""));
                     if (bytes > TEXT_BUDGET)
                         return invalid(`finding evidence exceeds the ${TEXT_BUDGET}-byte stored text budget`);
@@ -227,9 +232,7 @@ export const mailFindingsStoreOver = (context) => {
             }
             case "new_contact": {
                 const person = Number(identityOfAddress(finding.address)?.person_id);
-                database
-                    .prepare("UPDATE persons SET name = ?, updated_at = ? WHERE id = ? AND name IS NULL")
-                    .run(finding.name, now(), person);
+                database.prepare("UPDATE persons SET name = ?, updated_at = ? WHERE id = ?").run(finding.name, now(), person);
                 return `person:${person}`;
             }
         }
@@ -303,7 +306,7 @@ export const mailFindingsStoreOver = (context) => {
             // accepted findings' own mail unchanged.
             const chosen = batch.input.findings.filter((finding) => accepted.includes(finding.id));
             if (chosen.length)
-                cite(chosen, account);
+                cite(chosen, account, true);
             if (proposal.proposedBy.type !== "bot" || !proposal.proposedBy.name)
                 return invalid("a findings author must be an agent");
             const agent = {

package/package.json

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