@wirecat/cli-core 0.580.0 → 0.581.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.581.0 — 05.11.2026
+
+### Added
+
+- **`review --holder` gives the findings key.** A host that mounts its findings command (`MailMount.findings`)
+  gets a `mail-findings.add` step with `key` before the acknowledge step, so an agent copies the key instead of
+  building it from the cursor. The text answer names it too.
+
+### Fixed
+
+- **A run after `messages reset` can stage its findings.** The reset counts on the mark (`resets`), and the findings
+  key of a mark moved back is `<holder>:<through_id>-r<resets>`, such as `mail-triage:277352-r1`. The runs after a
+  reset reached the through id of a batch staged before it and were refused (`mail-findings.key-used`), so their
+  mark stayed. Keys of marks never moved back keep their shape, and the same review still gives the same key, so
+  a retry of one run stages nothing twice.
+
 ## 0.580.0 — 05.11.2026
 
 ### Added

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

@@ -15,6 +15,8 @@ export interface MailMount {
     acknowledge?: string;
     /** `null`: the host mounts no thread read, so a review offers none. */
     conversation?: string | null;
+    /** The host's command that stages a findings batch with `--key`; `review --holder` then gives that key as a step. */
+    findings?: string;
     /** In snake_case, as a step names it: memo's `source`, with `email:<account>`. */
     mailbox?: {
         option: string;

package/dist/mail/cli/review.js

@@ -1,7 +1,7 @@
 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 { defineSteps, MAX_NEXT_STEPS, stepOf, } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
 import { environmentOf, outputFor } from "../../cli/context.js";
 import { LOCAL_READ } from "../../cli/effects.js";
@@ -36,7 +36,18 @@ export const MAIL_REVIEW_QUERY = defineQuery({
 /** The mail review's steps where a host mounted them; a host lists them beside its own so its step checks know them. */
 export const mailReviewSteps = (mount = {}) => {
     const mailbox = mount.mailbox ? [{ name: mount.mailbox.option, required: true }] : [];
+    const findings = mount.findings
+        ? [
+            {
+                id: "mail-findings.add",
+                command: mount.findings,
+                args: [{ name: "key", required: true }, ...mailbox],
+                why: "stage what these emails ask under this key, before acknowledging them",
+            },
+        ]
+        : [];
     return defineSteps([
+        ...findings,
         {
             id: "mail-messages.acknowledge",
             command: mount.acknowledge ?? "messages acknowledge",
@@ -197,7 +208,12 @@ const holderReview = async (command, mail, holder, query) => {
     const step = stepsFor(mail.mount, mailbox);
     const answer = reviewAnswer(found, mailbox, true, step);
     const skipped = Object.entries(read.skipped).filter(([, count]) => count > 0);
-    answer.next = [...step("mail-messages.acknowledge", { holder, cursor: read.cursor }), ...(answer.next ?? [])];
+    const stage = read.findingsKey === undefined ? [] : step("mail-findings.add", { key: read.findingsKey });
+    answer.next = [
+        ...stage,
+        ...step("mail-messages.acknowledge", { holder, cursor: read.cursor }),
+        ...(answer.next ?? []),
+    ].slice(0, MAX_NEXT_STEPS);
     answer.missing = [
         ...(answer.missing ?? []),
         ...(read.held > 0 ? [{ field: "items", why: `${read.held} partial emails held until they are whole` }] : []),
@@ -217,7 +233,7 @@ const holderReview = async (command, mail, holder, query) => {
     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}: past ${read.mark.throughId}; findings key ${read.findingsKey}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
         return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`).join("");
     });

package/dist/mail/findings.d.ts

@@ -131,7 +131,10 @@ export interface MailOrderUpdateFinding extends Cited {
 export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding | MailInvoiceFinding | MailPaymentFinding | MailOrderFinding | MailOrderUpdateFinding;
 export interface MailFindingsInput {
     schemaVersion: 1;
-    /** `<holder>:<through_id>`: one batch per run of a holder over the mail it was given. */
+    /**
+     * `<holder>:<through_id>`, with `-r<resets>` after the owner moved the mark back: one batch per run of a holder over
+     * the mail it was given. `review --holder` gives it.
+     */
     key: string;
     extractor: string;
     findings: MailFinding[];

package/dist/mail/findings.js

@@ -347,8 +347,9 @@ const one = (raw, ids) => {
  * The shape of a mail findings batch: 1–30 findings, each citing 1–8 `msg:email/…` references with fingerprints.
  * What needs the store — the fingerprints, partial mail, the per-sender cap, the targets — the store checks.
  */
-const KEY = /^[a-z0-9][a-z0-9-]{0,39}:[1-9]\d*$/;
-const KEY_SHAPE = "a mail findings key is <holder>:<through_id>, such as mail-triage:9123456";
+const KEY = /^[a-z0-9][a-z0-9-]{0,39}:[1-9]\d*(-r[1-9]\d*)?$/;
+const KEY_SHAPE = "a mail findings key is the one `review --holder` gave: <holder>:<through_id>, and -r<resets> after a reset, " +
+    "such as mail-triage:9123456 or mail-triage:9123456-r1";
 export const validateMailFindings = (input) => {
     const batch = validateBatch(input, RULES, MAIL_FINDINGS_PER_RUN, one);
     if (!KEY.test(batch.key))

package/dist/mail/marks.d.ts

@@ -22,6 +22,8 @@ export interface MailMark {
     suspicious: number[];
     read: number;
     skipped: Record<SkipReason, number>;
+    /** How often the owner moved the mark back: a findings key names it, so a run after a reset never reuses one. */
+    resets: number;
     /** ms. */
     updatedAt: number;
 }
@@ -30,6 +32,12 @@ export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder:
 export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Promise<MailMark[]>;
 /** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
 export declare const cursorOf: (throughId: number, readAt: number) => string;
+/**
+ * The findings key of one run: `<holder>:<through_id>`, and `-r<resets>` once the owner moved the mark back, so the
+ * runs after a reset never reach a key a batch staged before it holds. The same review gives the same key: a retry
+ * of one run stages nothing twice.
+ */
+export declare const findingsKeyOf: (holder: string, throughId: number, resets: number) => string;
 /** A bulk email that is not surely a newsletter: the holder gets its subject and first lines only. */
 export interface BulkExcerpt {
     email: StoredHit;
@@ -45,6 +53,8 @@ export interface MarkRead {
     excerpts: BulkExcerpt[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
+    /** The key a findings batch over these emails takes; `undefined` while nothing is stored to read. */
+    findingsKey: string | undefined;
     /** More is stored after this batch: read again after acknowledging. */
     more: boolean;
     held: number;

package/dist/mail/marks.js

@@ -39,6 +39,7 @@ const parsed = (holder, value, at) => {
             suspicious: Array.isArray(saved.suspicious) ? saved.suspicious.filter((id) => typeof id === "number") : [],
             read: saved.read ?? 0,
             skipped: { ...noneSkipped(), ...saved.skipped },
+            resets: typeof saved.resets === "number" ? saved.resets : 0,
             updatedAt: at,
         };
     }
@@ -80,6 +81,12 @@ const verdict = (email, now) => {
 };
 /** 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}`;
+/**
+ * The findings key of one run: `<holder>:<through_id>`, and `-r<resets>` once the owner moved the mark back, so the
+ * runs after a reset never reach a key a batch staged before it holds. The same review gives the same key: a retry
+ * of one run stages nothing twice.
+ */
+export const findingsKeyOf = (holder, throughId, resets) => `${holder}:${throughId}${resets > 0 ? `-r${resets}` : ""}`;
 const parseCursor = (cursor) => {
     const match = /^(\d+)\.(\d+)$/.exec(cursor.trim());
     if (!match)
@@ -140,10 +147,14 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
         skipped: noneSkipped(),
         mark: saved,
     };
+    const keyed = (throughId) => ({
+        cursor: cursorOf(throughId, now),
+        findingsKey: throughId > 0 ? findingsKeyOf(holder, throughId, saved?.resets ?? 0) : undefined,
+    });
     if (!account)
-        return { ...empty, cursor: cursorOf(0, now) };
+        return { ...empty, ...keyed(0) };
     if (!saved)
-        return { ...empty, cursor: cursorOf(await store.mail.newestEmailId(account.id), now) };
+        return { ...empty, ...keyed(await store.mail.newestEmailId(account.id)) };
     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.
@@ -179,7 +190,7 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
         wanted: wanted.sort((a, b) => a - b),
         sorted: new Map([...sorted].filter(([, one]) => one.verdict === "excerpt")),
         oldestStoredAt,
-        cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
+        ...keyed(batch.at(-1)?.id ?? mark.throughId),
         more: newer.length > batch.length,
         held,
         skipped,
@@ -312,6 +323,7 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
         suspicious: [...new Set(suspicious)].sort((a, b) => a - b).slice(-MOST_HELD),
         read,
         skipped,
+        resets: mark?.resets ?? 0,
     };
     await store.sync.setSyncState(mailbox, key, JSON.stringify(next));
     return { holder, ...next, updatedAt: now };
@@ -397,6 +409,7 @@ export const rewindMark = async (store, mailbox, holder, to, { now = Date.now(),
         suspicious: mark.suspicious.filter((id) => id <= through),
         read: mark.read,
         skipped: mark.skipped,
+        resets: mark.resets + 1,
     };
     if (!dry)
         await store.sync.setSyncState(mailbox, key, JSON.stringify(next));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.580.0",
+  "version": "0.581.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",