@wirecat/cli-core 0.582.0 → 0.584.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.584.0 — 06.11.2026
+
+### Added
+
+- **`schedule list` gives an agent schedule's cost caps.** `max_cost_usd` is the cap on one run (`--max-cost`, null
+  when none) and `max_cost_per_day_usd` the daily cap in force, the schedule's `--max-cost-per-day` or the config's
+  (0 for none), so a screen can show `$0.84 of $5.00`; the text line says `today $0.84 of $5.00`.
+
+### Fixed
+
+- **`schedule list`'s output schema describes what it prints.** `spent_today_usd`, and the last run's `cost_usd`
+  and `skipped`, were printed but missing from the strict `scheduled_job` schema.
+
+## 0.583.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **`--compact` says a day once above its rows in a list in time order.** When a list's rows are sorted by time and
+  a day holds three rows on average, a `# YYYY-MM-DD` line opens each day and its rows print only `HH:MM`. A
+  1,000-message `messages list` drops from 43 % to 41 % of JSON's tokens (53 % to 52 % of its bytes). A reader that
+  parsed `MM-DD HH:MM` from such a row reads the day from the line above it. Searches and other unsorted lists are
+  unchanged.
+- **An item answer's compact sections share one span line.** The days and zone are printed once, as
+  `# <first>…<last> · <zone>` above the first section, not on every section's header (`projects status`,
+  `projects evidence`).
+- **`projects status` leaves out what the answer already says.** `item.window` is gone (it is `meta.window`). A
+  listed item drops `chat` when its `ref` is a message of that chat, drops `basis` when it is `store`, and a promise
+  drops `data.source`, which equals its `basis`. `who.name` and a chat row's `role` are left out instead of `null`.
+  The promise row of `--compact` prints `basis`. On the E7 fixture JSON goes from 3,998 to 3,676 bytes and compact
+  from 1,511 to 1,387.
+- **Every mail finding kind needs `reason`.** A fact, a memory and a new contact had none or an optional one; the
+  owner reads it beside each finding when he decides. A missing field is refused with its name, the finding and what
+  that kind needs (`finding.missing-field`, `details.fields`, `details.needs`). Batches staged before keep theirs.
+
+### Added
+
+- **`invoices` takes `number`.** `finance.invoices({ number })` lists the invoices whose printed number is exactly
+  that, as `orders.list({ number })` does for orders.
+- **`MAIL_FINDING_FIELDS` and `mailFindingFieldsHelp()`.** The fields each mail finding kind needs and takes, the
+  table the validator itself reads, so a host's `--help` lists them without drifting from the checks.
+
+### Fixed
+
+- **A `messages reset` that leaves the mark where it is still counts.** It adds to `resets`, so the holder's next
+  findings key is new, and says "mark unchanged … counted as a reset"; the answer gives `resets`. Before, it wrote
+  nothing, and a run after it was refused with `mail-findings.key-used`.
+- **`review --holder` gives no `mail-findings.add` step when it gives no emails.**
+- **A task finding's `due_at` refusals say what is needed.** A date without a time and timezone, `due_at` without
+  `due_evidence`, and `due_evidence` given as evidence objects each name the field and show the right form, such as
+  `"due_at":"2026-11-09T09:00:00Z","due_evidence":["<reference>"]`.
+
 ## 0.582.0 — 05.11.2026
 
 ### Added

package/dist/cli/compact.js

@@ -200,7 +200,9 @@ const cellOf = (item, column, clock) => {
             if (!parts)
                 return { text: clean(iso) };
             const day = parts.date.slice(5);
-            return { text: column.as === "day" ? day : `${day} ${parts.time}`, date: parts.date };
+            return column.as === "day"
+                ? { text: day, date: parts.date }
+                : { text: `${day} ${parts.time}`, date: parts.date, time: parts.time };
         }
         case "count":
             return typeof value === "number" && value !== 0
@@ -255,6 +257,22 @@ const sameEverywhere = (rows, index) => {
     const first = rows[0]?.cells[index]?.text;
     return first !== undefined && rows.every(({ cells }) => cells[index]?.text === first);
 };
+const ordered = (dates) => dates.every((one, at) => at === 0 || one >= dates[at - 1]) ||
+    dates.every((one, at) => at === 0 || one <= dates[at - 1]);
+/**
+ * The column whose date is said once on a `# YYYY-MM-DD` line above its rows: a list in time order, such as a chat's
+ * messages. Only when days hold three rows on average: with fewer, the day lines cost more than they save.
+ */
+const dayColumn = (rows, shape, hoisted) => {
+    const index = shape.columns.findIndex((column, at) => column.as === "time" && !hoisted[at]);
+    if (index < 0)
+        return -1;
+    const dates = rows.map(({ cells }) => cells[index]?.date);
+    if (dates.some((one) => one === undefined))
+        return -1;
+    const days = dates;
+    return ordered(days) && new Set(days).size * 3 <= days.length ? index : -1;
+};
 const rowsOfItems = (items, shape, clock, chars) => {
     const dates = [];
     const rows = items.map((item) => {
@@ -277,17 +295,30 @@ const rowsOfItems = (items, shape, clock, chars) => {
             return [];
         return [`${sourceOf(item, column) ?? fieldsOfColumn(column.field)[0]}: ${rows[0]?.cells[index]?.text}`];
     });
-    const lines = rows.map(({ cells, text, item }) => {
+    const byDay = dayColumn(rows, shape, hoisted);
+    let shownDay;
+    const lines = rows.flatMap(({ cells, text, item }) => {
         const parts = cells.map((cell, index) => (hoisted[index] ? undefined : cell?.text));
+        const dayLine = [];
+        const cell = cells[byDay];
+        if (byDay >= 0 && cell?.date && cell.time) {
+            if (cell.date !== shownDay)
+                dayLine.push(`# ${cell.date}`);
+            shownDay = cell.date;
+            parts[byDay] = cell.time;
+        }
         const shortened = prefix ? clean(prefix) : undefined;
         if (shortened && parts[0]?.startsWith(shortened))
             parts[0] = `#${parts[0].slice(shortened.length)}`;
         const shown = [...parts, text].filter((part) => part !== undefined && part !== "");
-        return guarded(shown.length ? shown.join(" · ") : item ? blockLine(item, chars) : "");
+        return [...dayLine, guarded(shown.length ? shown.join(" · ") : item ? blockLine(item, chars) : "")];
     });
+    const header = [...(prefix ? [`ref: ${clean(prefix)}<id>`] : []), ...named];
+    return { header, lines, dates };
+};
+const spanOf = (dates, clock) => {
     const when = span(dates);
-    const header = [...(prefix ? [`ref: ${clean(prefix)}<id>`] : []), ...named, ...(when ? [when, clock.zone] : [])];
-    return { header, lines };
+    return when ? [when, clock.zone] : [];
 };
 const blockLine = (fields, chars) => blockOf(fields, chars).join("  ");
 /** A record as `field: value` lines; a nested record is indented under its field, a list of records counted. */
@@ -352,20 +383,26 @@ export const compactText = (body, shape, options, rowsOf = rowsOfEntity()) => {
     const chars = options.textChars ?? TEXT_CHARS;
     let lines = [];
     if ("items" in body) {
-        const { header, lines: rows } = rowsOfItems(body.items, shape, clock, chars);
-        lines = (header.length ? [`# ${header.join(" · ")}`] : []).concat(rows.length ? rows : ["# nothing found"]);
+        const { header, lines: rows, dates } = rowsOfItems(body.items, shape, clock, chars);
+        const head = [...header, ...spanOf(dates, clock)];
+        lines = (head.length ? [`# ${head.join(" · ")}`] : []).concat(rows.length ? rows : ["# nothing found"]);
     }
     else if (isFields(body.item)) {
         const sections = shape.sections ?? {};
         const rest = Object.fromEntries(Object.entries(body.item).filter(([name]) => !Object.hasOwn(sections, name) && !shape.hidden?.includes(name)));
         lines = blockOf(rest, chars, "", shape.whole).map(guarded);
+        let dates = [];
+        let drawn = [];
         for (const [name, entity] of Object.entries(sections)) {
             const list = body.item[name];
             if (!Array.isArray(list))
                 continue;
-            const { header, lines: rows } = rowsOfItems(list, rowsOf(entity), clock, chars);
-            lines = lines.concat([`# ${[`${clean(name)}: ${list.length}`, ...header].join(" · ")}`], rows);
+            const { header, lines: rows, dates: more } = rowsOfItems(list, rowsOf(entity), clock, chars);
+            dates = dates.concat(more);
+            drawn = drawn.concat([`# ${[`${clean(name)}: ${list.length}`, ...header].join(" · ")}`], rows);
         }
+        const when = spanOf(dates, clock);
+        lines = lines.concat(when.length ? [`# ${when.join(" · ")}`] : [], drawn);
     }
     else if (present(body.item))
         lines = [guarded(cut(clean(String(body.item)), chars))];

package/dist/cli/index.d.ts

@@ -6,6 +6,7 @@ export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { type AppErrors, failureContext } from "../errors/reasons.js";
+export { mailFindingFieldsHelp } from "../mail/findings.js";
 export { botInstructions } from "../mcp/bot/instructions.js";
 export type { BotServerOptions, RunBotCommand } from "../mcp/bot/server.js";
 export type { HttpOptions } from "../mcp/http/serve.js";

package/dist/cli/index.js

@@ -5,6 +5,7 @@ export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { failureContext } from "../errors/reasons.js";
+export { mailFindingFieldsHelp } from "../mail/findings.js";
 export { botInstructions } from "../mcp/bot/instructions.js";
 export { callMeetingPreparationTool, meetingPreparationTool } from "../mcp/meeting-preparation.js";
 export { callMeetingProjectCandidatesTool, meetingProjectCandidatesTool } from "../mcp/meeting-project-candidates.js";

package/dist/cli/project-status-rows.js

@@ -15,7 +15,7 @@ export const STATUS_SIGNAL_ROWS = {
         columns: [
             ...where,
             { field: "at", as: "day" },
-            { field: "data.source" },
+            { field: "basis" },
             { field: "data.side" },
             { field: "data.due", as: "day" },
             { field: "data.status" },

package/dist/cli/project-status.d.ts

@@ -27,10 +27,6 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
     readonly project: v.StringSchema<undefined>;
     readonly key: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly name: v.StringSchema<undefined>;
-    readonly window: v.StrictObjectSchema<{
-        readonly since: v.StringSchema<undefined>;
-        readonly until: v.StringSchema<undefined>;
-    }, undefined>;
     /** Each signal's version, so a saved answer says which rules made it. */
     readonly signals: v.RecordSchema<v.StringSchema<undefined>, v.NumberSchema<undefined>, undefined>;
     readonly money: v.ArraySchema<v.StrictObjectSchema<{
@@ -43,7 +39,7 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
         readonly chat: v.StringSchema<undefined>;
         readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly kind: v.StringSchema<undefined>;
-        readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly role: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly purpose: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly project: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly coverage: v.StringSchema<undefined>;
@@ -54,7 +50,7 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
             readonly at: v.StringSchema<undefined>;
             readonly who: v.StrictObjectSchema<{
                 readonly ref: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-                readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly owner: v.BooleanSchema<undefined>;
             }, undefined>;
         }, undefined>, undefined>;
@@ -100,10 +96,6 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
         project: string;
         key: string | null;
         name: string;
-        window: {
-            since: string;
-            until: string;
-        };
         signals: {
             [x: string]: number;
         };
@@ -117,7 +109,7 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
             chat: string;
             title: string | null;
             kind: string;
-            role: string | null;
+            role?: string | undefined;
             purpose?: string | undefined;
             project?: string | undefined;
             coverage: string;
@@ -128,7 +120,7 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
                 at: string;
                 who: {
                     ref?: string | undefined;
-                    name: string | null;
+                    name?: string | undefined;
                     owner: boolean;
                 };
             } | undefined;

package/dist/cli/project-status.js

@@ -13,21 +13,23 @@ const SECTIONS = {
 /** The `project_status` answer drawn by `--compact`: a row per chat, then each listed signal with its own row. */
 export const projectStatusRow = (signals) => ({
     columns: [],
-    hidden: ["project", "window", "purposes", "signals"],
+    hidden: ["project", "purposes", "signals"],
     sections: {
         ...SECTIONS,
         ...Object.fromEntries(signals.flatMap(({ id }) => (ON_CHAT_ROW.has(id) ? [] : [[listKey(id), `status.${id}`]]))),
     },
 });
-const who = v.strictObject({ ref: v.optional(v.string()), name: v.nullable(v.string()), owner: v.boolean() });
+const who = v.strictObject({ ref: v.optional(v.string()), name: v.optional(v.string()), owner: v.boolean() });
 const statusItem = v.looseObject({
     ref: v.nullable(v.string()),
-    chat: v.nullable(v.string()),
+    /** Left out when `ref` is a message of that chat. */
+    chat: v.optional(v.nullable(v.string())),
     at: v.nullable(v.string()),
     who: v.optional(who),
     /** Every ref the item cites, when it cites more than `ref`. */
     evidence: v.optional(v.array(v.string())),
-    basis: v.picklist(["store", "fact", "task", "pattern"]),
+    /** Left out for `store`, what most items are read from. */
+    basis: v.optional(v.picklist(["fact", "task", "pattern"])),
     data: v.record(v.string(), v.unknown()),
 });
 /** Where a project stands: per chat signals, open money, and what was left out. Empty lists are left out. */
@@ -35,7 +37,6 @@ export const projectStatusSchema = v.looseObject({
     project: v.string(),
     key: v.nullable(v.string()),
     name: v.string(),
-    window: v.strictObject({ since: v.string(), until: v.string() }),
     /** Each signal's version, so a saved answer says which rules made it. */
     signals: v.record(v.string(), v.number()),
     money: v.array(v.strictObject({ direction: v.string(), currency: v.nullable(v.string()), amount: v.string(), rows: v.number() })),
@@ -43,7 +44,7 @@ export const projectStatusSchema = v.looseObject({
         chat: v.string(),
         title: v.nullable(v.string()),
         kind: v.string(),
-        role: v.nullable(v.string()),
+        role: v.optional(v.string()),
         purpose: v.optional(v.string()),
         project: v.optional(v.string()),
         coverage: v.string(),
@@ -139,14 +140,33 @@ const missingOf = (found, hints) => {
         ...found.failed.map((one) => ({ field: `signal:${one.signal}`, why: one.why })),
     ];
 };
-const whoOf = (one) => one === null ? {} : { who: { ...(one.ref === null ? {} : { ref: one.ref }), name: one.name, owner: one.owner } };
-/** An item as listed: its first ref, every ref only when there are more. */
-const listed = ({ signal: _signal, who, evidence, ...one }) => ({
-    ...one,
-    ref: evidence[0]?.ref ?? one.chat,
-    ...whoOf(who),
-    ...(evidence.length > 1 ? { evidence: evidence.map((each) => each.ref) } : {}),
-});
+const whoOf = (one) => one === null
+    ? {}
+    : {
+        who: {
+            ...(one.ref === null ? {} : { ref: one.ref }),
+            ...(one.name === null ? {} : { name: one.name }),
+            owner: one.owner,
+        },
+    };
+const inChat = (ref, chat) => ref !== null && chat !== null && (ref === chat || ref.startsWith(`msg:${chat.slice("chat:".length)}/`));
+/**
+ * An item as listed: its first ref, every ref only when there are more. What the rest of the item already says is
+ * left out: the chat its message ref names, the `store` basis, and a promise's `source`, which is its basis.
+ */
+const listed = ({ signal: _signal, who, evidence, chat, basis, data, ...one }) => {
+    const ref = evidence[0]?.ref ?? chat;
+    const { source, ...rest } = data;
+    return {
+        ...(inChat(ref, chat) ? {} : { chat }),
+        ...one,
+        ...(basis === "store" ? {} : { basis }),
+        data: source === basis ? rest : data,
+        ref,
+        ...whoOf(who),
+        ...(evidence.length > 1 ? { evidence: evidence.map((each) => each.ref) } : {}),
+    };
+};
 /**
  * Low signal items, counted on their chat's row instead of listed: questions others ask in a group with no role (a
  * leads group's requests), promises found by words that others wrote in a group, and past the newest one per chat.
@@ -194,7 +214,7 @@ const chatRow = (found, hints, chat, unlisted) => {
         chat: chat.ref,
         title: chat.title,
         kind: chat.kind,
-        role: chat.role,
+        ...(chat.role === null ? {} : { role: chat.role }),
         ...(Array.isArray(found.purposes) && found.purposes.length === 1 ? {} : { purpose: chat.purpose }),
         ...(chat.project === found.project.ref ? {} : { project: chat.project }),
         coverage: chat.coverage.completeness.state,
@@ -225,7 +245,6 @@ export const projectStatusAnswer = (found, hints) => {
         project: found.project.ref,
         key: found.project.key,
         name: found.project.name,
-        window: found.window,
         signals: Object.fromEntries(found.signals.map(({ id, version }) => [id, version])),
         money: found.money.open,
         chats: found.chats.map((chat) => chatRow(found, hints, chat, [...unlisted].filter((one) => one.chat === chat.ref))),

package/dist/cli/schedule/schedule-command.js

@@ -138,6 +138,12 @@ export const scheduleLimitsOf = (config) => {
 const given = (limits) => Object.fromEntries(Object.entries(limits).filter(([, value]) => value !== undefined));
 const shown = (argv) => argv.map((arg) => (arg === "" ? '""' : arg)).join(" ");
 const usd = (value) => `$${value.toFixed(2)}`;
+/** The per-run cap an agent schedule was made with (`--max-cost`, passed to claude as --max-budget-usd), or null. */
+const runCapOf = (argv) => {
+    const at = argv.indexOf("--max-budget-usd");
+    const cap = at < 0 ? Number.NaN : Number(argv[at + 1]);
+    return Number.isFinite(cap) ? cap : null;
+};
 /**
  * Runs the CLI's own commands, or an agent, later or on a timer — through systemd (Linux), launchd
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
@@ -184,19 +190,21 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
      * Why a run does not start now, or nothing: an agent whose runs reached the day's cost cap waits for tomorrow, and
      * one gated on mail waits for mail past its holder's mark — on its timer, until enough of it waits.
      */
+    /** A schedule's own limits, else the config file's, else the defaults. */
+    const limitsOf = (self, schedule) => ({
+        ...SCHEDULE_DEFAULTS,
+        ...given(configured?.(self) ?? {}),
+        ...given({
+            mailWaitMinutes: schedule.mailWaitMinutes,
+            mailBatch: schedule.mailBatch,
+            maxCostPerDay: schedule.maxCostPerDay,
+        }),
+    });
     const waits = async (self, file, { timed }) => {
         if (!existsSync(file))
             return undefined;
         const schedule = readSchedule(file);
-        const { mailWaitMinutes, mailBatch, maxCostPerDay } = {
-            ...SCHEDULE_DEFAULTS,
-            ...given(configured?.(self) ?? {}),
-            ...given({
-                mailWaitMinutes: schedule.mailWaitMinutes,
-                mailBatch: schedule.mailBatch,
-                maxCostPerDay: schedule.maxCostPerDay,
-            }),
-        };
+        const { mailWaitMinutes, mailBatch, maxCostPerDay } = limitsOf(self, schedule);
         if (schedule.kind === "agent" && maxCostPerDay > 0) {
             const spent = spentToday(file);
             if (spent >= maxCostPerDay) {
@@ -342,7 +350,13 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
             kind: schedule.kind,
             when: describeWhen(schedule.when),
             last: lastRun(scheduleFile(state, schedule.name)) ?? null,
-            ...(schedule.kind === "agent" ? { spentTodayUsd: spentToday(scheduleFile(state, schedule.name)) } : {}),
+            ...(schedule.kind === "agent"
+                ? {
+                    spentTodayUsd: spentToday(scheduleFile(state, schedule.name)),
+                    maxCostUsd: runCapOf(schedule.argv),
+                    maxCostPerDayUsd: limitsOf(this, schedule).maxCostPerDay,
+                }
+                : {}),
         }));
         const answer = listOf("schedule list", {
             items: rows.map((row) => snakeKeys(row)),
@@ -355,7 +369,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
                 return "";
             }
             return rows
-                .map(({ name, kind, when, last, spentTodayUsd }) => [
+                .map(({ name, kind, when, last, spentTodayUsd, maxCostPerDayUsd }) => [
                 name,
                 kind,
                 when,
@@ -366,7 +380,9 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
                                 `${last.failures} in a row${last.reason ? `: ${last.reason}` : ""} — ${last.output}`
                             : "")
                     : "not run yet",
-                ...(spentTodayUsd ? [`today ${usd(spentTodayUsd)}`] : []),
+                ...(spentTodayUsd
+                    ? [`today ${usd(spentTodayUsd)}${maxCostPerDayUsd ? ` of ${usd(maxCostPerDayUsd)}` : ""}`]
+                    : []),
                 ...(last?.skipped
                     ? [`skipped ${last.skipped.at.slice(0, 16).replace("T", " ")}: ${last.skipped.why}`]
                     : []),

package/dist/entities/index.d.ts

@@ -3979,7 +3979,15 @@ export declare const ENTITIES: {
             readonly error_code: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly failing_since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly failures: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly cost_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly skipped: v.OptionalSchema<v.StrictObjectSchema<{
+                readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+                readonly why: v.StringSchema<undefined>;
+            }, undefined>, undefined>;
         }, undefined>, undefined>;
+        readonly spent_today_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly max_cost_usd: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly max_cost_per_day_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>;
     readonly call_record: v.StrictObjectSchema<{
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
@@ -5936,6 +5944,7 @@ export declare const ENTITIES: {
                 readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
                 readonly statement: v.StringSchema<undefined>;
+                readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, v.StrictObjectSchema<{
                 readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
                 readonly evidence: v.ArraySchema<v.StrictObjectSchema<{
@@ -5960,6 +5969,7 @@ export declare const ENTITIES: {
                 readonly body: v.StringSchema<undefined>;
                 readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly project: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, v.StrictObjectSchema<{
                 readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
                 readonly evidence: v.ArraySchema<v.StrictObjectSchema<{

package/dist/entities/list-results.d.ts

@@ -57,7 +57,19 @@ export declare const scheduledJob: v.StrictObjectSchema<{
         readonly error_code: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly failing_since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly failures: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly cost_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        /** The last time a run did not start, and why: the day's cost cap, or too little new mail. */
+        readonly skipped: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+            readonly why: v.StringSchema<undefined>;
+        }, undefined>, undefined>;
     }, undefined>, undefined>;
+    /** Agent schedules: what today's runs cost, in US dollars. */
+    readonly spent_today_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    /** Agent schedules: the cap on one run (`--max-cost`), null when none. */
+    readonly max_cost_usd: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    /** Agent schedules: the daily cap in force, the schedule's `--max-cost-per-day` or the config's; 0 for none. */
+    readonly max_cost_per_day_usd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
 }, undefined>;
 export declare const botTemplate: v.StrictObjectSchema<{
     readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/list-results.js

@@ -41,7 +41,16 @@ export const scheduledJob = v.strictObject({
         error_code: v.optional(text),
         failing_since: v.optional(time),
         failures: v.optional(v.number()),
+        cost_usd: v.optional(v.number()),
+        /** The last time a run did not start, and why: the day's cost cap, or too little new mail. */
+        skipped: v.optional(v.strictObject({ at: time, why: text })),
     })),
+    /** Agent schedules: what today's runs cost, in US dollars. */
+    spent_today_usd: v.optional(v.number()),
+    /** Agent schedules: the cap on one run (`--max-cost`), null when none. */
+    max_cost_usd: v.optional(v.nullable(v.number())),
+    /** Agent schedules: the daily cap in force, the schedule's `--max-cost-per-day` or the config's; 0 for none. */
+    max_cost_per_day_usd: v.optional(v.number()),
 });
 export const botTemplate = v.strictObject({
     name: v.nullable(text),

package/dist/entities/mail-findings.d.ts

@@ -41,6 +41,8 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
             readonly statement: v.StringSchema<undefined>;
+            /** Every new finding gives one; a batch staged before reason was needed on every kind has none. */
+            readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
             readonly evidence: v.ArraySchema<v.StrictObjectSchema<{
@@ -65,6 +67,7 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly body: v.StringSchema<undefined>;
             readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly project: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
             readonly evidence: v.ArraySchema<v.StrictObjectSchema<{

package/dist/entities/mail-findings.js

@@ -30,6 +30,8 @@ const finding = v.variant("kind", [
         subject: v.optional(reference),
         type: v.picklist(FACT_TYPES),
         statement: text,
+        /** Every new finding gives one; a batch staged before reason was needed on every kind has none. */
+        reason: v.optional(text),
     }),
     v.strictObject({
         ...base,
@@ -48,6 +50,7 @@ const finding = v.variant("kind", [
         body: text,
         subject: v.optional(reference),
         project: v.optional(reference),
+        reason: v.optional(text),
     }),
     v.strictObject({ ...base, kind: v.literal("link"), from: reference, to: reference, reason: text }),
     v.strictObject({ ...base, kind: v.literal("new_contact"), address: text, name: text, reason: v.optional(text) }),

package/dist/errors/reasons.js

@@ -65,6 +65,7 @@ const OTHERS = [
     validation("mail-findings.invalid", "a checked mail findings batch would be refused; details.problems names why, finding by finding"),
     validation("mail-findings.key-used", "the findings batch key was already used for different input"),
     validation("finding.unknown-field", "a finding has a field its kind does not take"),
+    validation("finding.missing-field", "a finding leaves out a field its kind needs"),
     validation("document.changed", "the document changed while it was read; nothing was saved"),
     ["document.not-imported", "not_found", "the document is not imported in this source account"],
     ["extraction.invalid-proposals", "invalid_response", "the model's memory proposals could not be used"],

package/dist/mail/cli/marks.js

@@ -78,6 +78,8 @@ const mailMarkReset = v.strictObject({
     bulk: v.number(),
     /** Emails between the two marks it skips again: drafts, envelopes, suspicious senders, partial mail. */
     skipped: v.number(),
+    /** How often the owner moved this mark back, this reset counted even when the mark stays: the findings key names it. */
+    resets: v.number(),
     /** Nothing moved: `--dry-run` only counts. */
     dry_run: v.boolean(),
 });
@@ -102,7 +104,8 @@ export const resetMarkCommand = (mail) => answerEntity(annotate(new Command("res
     .summary("move a holder's processing mark back, so it reads that mail again (owner only)")
     .description("the owner moves a holder's mark back past the mail received since --since-time, or past the last --last " +
     "emails it was given; its next reviews give that mail again. The answer says how many emails it reads " +
-    "again. An agent cannot: a holder only moves its own mark forward, with `messages acknowledge`")
+    "again. Every reset counts, even one that leaves the mark where it is, so the holder's next findings key " +
+    "is new. An agent cannot: a holder only moves its own mark forward, with `messages acknowledge`")
     .requiredOption("--holder <name>", "whose mark: lower-case letters, digits and dashes, such as mail-triage")
     .option("--since-time <time>", "read again what was received since this ISO 8601 time, or 2d ago")
     .option("--last <n>", "read again the last n emails the holder was given", wholeNumber)
@@ -125,12 +128,15 @@ export const resetMarkCommand = (mail) => answerEntity(annotate(new Command("res
         again: reset.again,
         bulk: reset.bulk,
         skipped: reset.skipped,
+        resets: reset.mark.resets,
         dry_run: reset.dry,
     };
     renderAnswer(this, outputFor(this), itemOf(item), () => {
         const mark = reset.mark.throughId === reset.fromId
-            ? `the mark stays at ${reset.fromId}`
-            : `the mark ${reset.dry ? "would move" : "moved"} from ${reset.fromId} to ${reset.mark.throughId}`;
+            ? `mark unchanged at ${reset.fromId}, ${reset.dry ? "would be counted" : "counted"} as a reset ` +
+                `(resets ${reset.mark.resets}): the next run gets a new findings key`
+            : `the mark ${reset.dry ? "would move" : "moved"} from ${reset.fromId} to ${reset.mark.throughId} ` +
+                `(resets ${reset.mark.resets})`;
         return (`${holder} ${reset.dry ? "would read" : "reads"} ${reset.again} emails again, and ${reset.bulk} bulk ` +
             `ones as excerpts unless they are newsletters; ${reset.skipped} are skipped again; ${mark}\n`);
     });

package/dist/mail/cli/review.js

@@ -208,7 +208,7 @@ 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);
-    const stage = read.findingsKey === undefined ? [] : step("mail-findings.add", { key: read.findingsKey });
+    const stage = read.findingsKey === undefined || emails.length === 0 ? [] : step("mail-findings.add", { key: read.findingsKey });
     answer.next = [
         ...stage,
         ...step("mail-messages.acknowledge", { holder, cursor: read.cursor }),
@@ -233,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}; findings key ${read.findingsKey}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
+            ? `${holder}: past ${read.mark.throughId}${emails.length ? `; 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

@@ -11,7 +11,10 @@ interface Cited {
     evidence: FindingEvidence[];
 }
 export type MailTaskFinding = TaskFinding;
-export type MailFactFinding = FactFinding;
+/** The owner reads `reason` beside every finding when he decides it, so every kind gives one. */
+export type MailFactFinding = FactFinding & {
+    reason: string;
+};
 export interface MailTaskUpdateFinding extends Cited {
     kind: "task_update";
     task: string;
@@ -27,6 +30,7 @@ export interface MailMemoryFinding extends Cited {
     body: string;
     subject?: string;
     project?: string;
+    reason: string;
 }
 /** Address → person, person → organization, or thread → project. */
 export interface MailLinkFinding extends Cited {
@@ -39,7 +43,7 @@ export interface MailNewContactFinding extends Cited {
     kind: "new_contact";
     address: string;
     name: string;
-    reason?: string;
+    reason: string;
 }
 /** An invoice the mail carries; accepting it records the invoice through `store.finance`, confirmed. */
 export interface MailInvoiceFinding extends Cited {
@@ -139,6 +143,56 @@ export interface MailFindingsInput {
     extractor: string;
     findings: MailFinding[];
 }
+/**
+ * What each kind takes besides `id`, `kind` and `evidence`, in the order the validator reads them: `needs` it refuses
+ * without, `may` it takes. `--help`, `details.allowed` and `details.needs` all read this table, so they cannot drift
+ * from the checks. Some fields go together (due_at with due_evidence) or replace each other (counterparty or
+ * counterparty_name); the check of each kind says which.
+ */
+export declare const MAIL_FINDING_FIELDS: {
+    readonly task: {
+        readonly needs: readonly ["type", "title", "reason", "commitment"];
+        readonly may: readonly ["project", "dueAt", "dueEvidence", "assignee", "assigneeEvidence", "externalId", "sourceUrl"];
+    };
+    readonly task_update: {
+        readonly needs: readonly ["task", "change", "reason"];
+        readonly may: readonly ["dueAt", "detail"];
+    };
+    readonly fact: {
+        readonly needs: readonly ["type", "statement", "reason"];
+        readonly may: readonly ["subject", "project"];
+    };
+    readonly memory: {
+        readonly needs: readonly ["memoryKind", "scope", "body", "reason"];
+        readonly may: readonly ["subject", "project"];
+    };
+    readonly link: {
+        readonly needs: readonly ["from", "to", "reason"];
+        readonly may: readonly [];
+    };
+    readonly new_contact: {
+        readonly needs: readonly ["address", "name", "reason"];
+        readonly may: readonly [];
+    };
+    readonly invoice: {
+        readonly needs: readonly ["direction", "currency", "lines", "reason"];
+        readonly may: readonly ["counterparty", "counterpartyName", "counterpartyEmail", "total", "number", "issueDate", "dueDate", "project"];
+    };
+    readonly payment: {
+        readonly needs: readonly ["direction", "amount", "currency", "date", "reason"];
+        readonly may: readonly ["payer", "payerName", "payerEmail", "payee", "payeeName", "payeeEmail", "reference", "allocations", "project"];
+    };
+    readonly order: {
+        readonly needs: readonly ["purpose", "supplierName", "reason"];
+        readonly may: readonly ["customer", "customerName", "customerEmail", "supplier", "number", "total", "currency", "status", "orderDate", "fulfilledDate", "invoice", "payment", "project", "sourceUrl"];
+    };
+    readonly order_update: {
+        readonly needs: readonly ["supplierName", "number", "status", "reason"];
+        readonly may: readonly ["date"];
+    };
+};
+/** One line per kind, `kind: needed fields; optional ones`, for `mail findings add --help`. */
+export declare const mailFindingFieldsHelp: () => string;
 export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
 /** Why one finding, or the batch when `finding` is null, would be refused. */
 export interface MailFindingProblem {

package/dist/mail/findings.js

@@ -5,7 +5,7 @@ import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
 import { formatLocator, parseLocator } from "../domain/locator.js";
 import { ORDER_PURPOSES, ORDER_STATUSES } from "../domain/orders.js";
 import { parseReference } from "../domain/references.js";
-import { findingFields, findingHash, findingId, findingText, meetingTimestamp, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
+import { findingFields, findingHash, findingId, findingNeeds, findingText, meetingTimestamp, snakeCase, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
 export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
 /** At most this many findings in one run's batch, and per sender in it. */
 export const MAIL_FINDINGS_PER_RUN = 30;
@@ -30,6 +30,90 @@ const RULES = {
     anySubject: true,
     inboxTasks: true,
 };
+/**
+ * What each kind takes besides `id`, `kind` and `evidence`, in the order the validator reads them: `needs` it refuses
+ * without, `may` it takes. `--help`, `details.allowed` and `details.needs` all read this table, so they cannot drift
+ * from the checks. Some fields go together (due_at with due_evidence) or replace each other (counterparty or
+ * counterparty_name); the check of each kind says which.
+ */
+export const MAIL_FINDING_FIELDS = {
+    task: {
+        needs: ["type", "title", "reason", "commitment"],
+        may: ["project", "dueAt", "dueEvidence", "assignee", "assigneeEvidence", "externalId", "sourceUrl"],
+    },
+    task_update: { needs: ["task", "change", "reason"], may: ["dueAt", "detail"] },
+    fact: { needs: ["type", "statement", "reason"], may: ["subject", "project"] },
+    memory: { needs: ["memoryKind", "scope", "body", "reason"], may: ["subject", "project"] },
+    link: { needs: ["from", "to", "reason"], may: [] },
+    new_contact: { needs: ["address", "name", "reason"], may: [] },
+    invoice: {
+        needs: ["direction", "currency", "lines", "reason"],
+        may: [
+            "counterparty",
+            "counterpartyName",
+            "counterpartyEmail",
+            "total",
+            "number",
+            "issueDate",
+            "dueDate",
+            "project",
+        ],
+    },
+    payment: {
+        needs: ["direction", "amount", "currency", "date", "reason"],
+        may: [
+            "payer",
+            "payerName",
+            "payerEmail",
+            "payee",
+            "payeeName",
+            "payeeEmail",
+            "reference",
+            "allocations",
+            "project",
+        ],
+    },
+    order: {
+        needs: ["purpose", "supplierName", "reason"],
+        may: [
+            "customer",
+            "customerName",
+            "customerEmail",
+            "supplier",
+            "number",
+            "total",
+            "currency",
+            "status",
+            "orderDate",
+            "fulfilledDate",
+            "invoice",
+            "payment",
+            "project",
+            "sourceUrl",
+        ],
+    },
+    order_update: { needs: ["supplierName", "number", "status", "reason"], may: ["date"] },
+};
+const MAIL_FINDING_KINDS = Object.keys(MAIL_FINDING_FIELDS);
+/** The fixed values a field takes, shown in `--help` beside it; the checks read the same lists. */
+const VALUES = {
+    task: { type: ["bug", "feature", "chore"], commitment: ["explicit", "inferred"] },
+    task_update: { change: ["close", "due", "detail"] },
+    memory: { memoryKind: MEMORY_KINDS, scope: MEMORY_SCOPES },
+    invoice: { direction: INVOICE_DIRECTIONS },
+    payment: { direction: MONEY_DIRECTIONS },
+    order: { purpose: ORDER_PURPOSES, status: ORDER_STATUSES },
+    order_update: { status: ORDER_STATUSES },
+};
+/** One line per kind, `kind: needed fields; optional ones`, for `mail findings add --help`. */
+export const mailFindingFieldsHelp = () => MAIL_FINDING_KINDS.map((kind) => {
+    const { needs, may } = MAIL_FINDING_FIELDS[kind];
+    const named = (field) => {
+        const values = VALUES[kind]?.[field];
+        return values ? `${snakeCase(field)} ${values.join("|")}` : snakeCase(field);
+    };
+    return `  ${kind}: ${needs.map(named).join(", ")}${may.length ? `; optional ${may.map(named).join(", ")}` : ""}`;
+}).join("\n");
 const typeOf = (reference) => {
     try {
         const parsed = parseReference(reference);
@@ -60,23 +144,18 @@ const optional = (key, value, read) => (value === undefined ? {} : { [key]: read
 const one = (raw, ids) => {
     if (!raw || typeof raw !== "object")
         return invalid("a finding is an object");
-    if (raw.kind === "fact")
-        return validateFinding(raw, RULES, ids);
+    if (!MAIL_FINDING_KINDS.includes(raw.kind))
+        return invalid(`a mail finding is a ${MAIL_FINDING_KINDS.join(", ")}`);
+    const { needs, may } = MAIL_FINDING_FIELDS[raw.kind];
+    findingFields(raw, ["id", "kind", ...needs, ...may, "evidence"], RULES.singular);
+    findingNeeds(raw, needs, RULES.singular);
+    if (raw.kind === "fact") {
+        const { reason, ...fact } = raw;
+        return { ...validateFinding(fact, RULES, ids), reason: findingText(reason, 2000) };
+    }
     if (raw.kind === "task") {
         const { externalId, sourceUrl, ...task } = raw;
-        let checked;
-        try {
-            checked = validateFinding(task, RULES, ids);
-        }
-        catch (error) {
-            if (!isCliError(error) || error.details.reason !== "finding.unknown-field")
-                throw error;
-            const allowed = [...error.details.allowed, "external_id", "source_url"];
-            throw new CliError("validation_error", error.message.replace(/; it takes .*$/, `; it takes ${allowed.join(", ")}`), {
-                ...error.details,
-                allowed,
-            });
-        }
+        const checked = validateFinding(task, RULES, ids);
         return {
             ...checked,
             ...optional("externalId", externalId, (value) => {
@@ -112,7 +191,6 @@ const one = (raw, ids) => {
     };
     switch (raw.kind) {
         case "task_update": {
-            findingFields(raw, ["id", "kind", "task", "change", "dueAt", "detail", "reason", "evidence"], RULES.singular);
             const task = reference(raw.task, /^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/, "a task update's task");
             const change = raw.change;
             if (change !== "close" && change !== "due" && change !== "detail")
@@ -135,7 +213,6 @@ const one = (raw, ids) => {
             };
         }
         case "memory": {
-            findingFields(raw, ["id", "kind", "memoryKind", "scope", "body", "subject", "project", "evidence"], RULES.singular);
             if (!MEMORY_KINDS.includes(raw.memoryKind))
                 return invalid(`a memory's memory_kind is ${MEMORY_KINDS.join(", ")}`);
             if (!MEMORY_SCOPES.includes(raw.scope))
@@ -152,11 +229,11 @@ const one = (raw, ids) => {
                     ? {}
                     : { subject: reference(raw.subject, /^(person|organization|project):[1-9]\d*$/, "a memory's subject") }),
                 ...(raw.project === undefined ? {} : { project: reference(raw.project, /^project:[1-9]\d*$/, "a project") }),
+                reason: findingText(raw.reason, 2000),
                 evidence,
             };
         }
         case "link": {
-            findingFields(raw, ["id", "kind", "from", "to", "reason", "evidence"], RULES.singular);
             const from = findingText(raw.from, 400);
             const to = findingText(raw.to, 80);
             const wanted = LINKS[typeOf(from) ?? ""];
@@ -165,7 +242,6 @@ const one = (raw, ids) => {
             return { id, kind: "link", from, to, reason: findingText(raw.reason, 2000), evidence };
         }
         case "new_contact": {
-            findingFields(raw, ["id", "kind", "address", "name", "reason", "evidence"], RULES.singular);
             const address = findingText(raw.address, 320).toLowerCase();
             if (!ADDRESS.test(address))
                 return invalid("a new contact's address is an email address");
@@ -174,28 +250,11 @@ const one = (raw, ids) => {
                 kind: "new_contact",
                 address,
                 name: findingText(raw.name, 200),
-                ...(raw.reason === undefined ? {} : { reason: findingText(raw.reason, 2000) }),
+                reason: findingText(raw.reason, 2000),
                 evidence,
             };
         }
         case "invoice": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "direction",
-                "counterparty",
-                "counterpartyName",
-                "counterpartyEmail",
-                "currency",
-                "lines",
-                "total",
-                "number",
-                "issueDate",
-                "dueDate",
-                "project",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             if (!Array.isArray(raw.lines) || raw.lines.length < 1 || raw.lines.length > 50)
                 return invalid("an invoice finding has 1–50 lines");
             const lines = raw.lines.map((line) => {
@@ -229,25 +288,6 @@ const one = (raw, ids) => {
             };
         }
         case "payment": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "direction",
-                "payer",
-                "payerName",
-                "payerEmail",
-                "payee",
-                "payeeName",
-                "payeeEmail",
-                "amount",
-                "currency",
-                "date",
-                "reference",
-                "allocations",
-                "project",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             let allocations;
             if (raw.allocations !== undefined) {
                 if (!Array.isArray(raw.allocations) || raw.allocations.length < 1 || raw.allocations.length > 8)
@@ -280,28 +320,6 @@ const one = (raw, ids) => {
             };
         }
         case "order": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "purpose",
-                "customer",
-                "customerName",
-                "customerEmail",
-                "supplier",
-                "supplierName",
-                "number",
-                "total",
-                "currency",
-                "status",
-                "orderDate",
-                "fulfilledDate",
-                "invoice",
-                "payment",
-                "project",
-                "sourceUrl",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             return {
                 id,
                 kind: "order",
@@ -324,7 +342,6 @@ const one = (raw, ids) => {
             };
         }
         case "order_update": {
-            findingFields(raw, ["id", "kind", "supplierName", "number", "status", "date", "reason", "evidence"], RULES.singular);
             const status = oneOf(raw.status, ORDER_STATUSES, "an order update's status");
             if (raw.date !== undefined && status !== "delivered")
                 return invalid("only a delivered order update gives date");
@@ -340,7 +357,7 @@ const one = (raw, ids) => {
             };
         }
         default:
-            return invalid("a mail finding is a task, task_update, fact, memory, link, new_contact, invoice, payment, order or order_update");
+            return invalid(`a mail finding is a ${MAIL_FINDING_KINDS.join(", ")}`);
     }
 };
 /**

package/dist/mail/index.d.ts

@@ -3,7 +3,7 @@ export { mailAccountKey } from "./account-key.js";
 export { DEFAULT_ATTACHMENT_POLICY, type MailAttachmentPolicy, POLICY_SKIPS } from "./attachments.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
-export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
+export { MAIL_FINDING_FIELDS, MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFieldsHelp, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";

package/dist/mail/index.js

@@ -3,7 +3,7 @@ export { mailAccountKey } from "./account-key.js";
 export { DEFAULT_ATTACHMENT_POLICY, POLICY_SKIPS } from "./attachments.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
-export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
+export { MAIL_FINDING_FIELDS, MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFieldsHelp, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";

package/dist/mail/marks.js

@@ -398,13 +398,12 @@ export const rewindMark = async (store, mailbox, holder, to, { now = Date.now(),
         skipped: count((said) => said !== "read" && said !== "held" && said !== "bulk"),
         dry,
     };
-    if (through >= mark.throughId)
-        return { mark, ...answer };
-    const [last] = through > 0 ? await store.mail.emailsBefore(account.id, through + 1, 1) : [];
-    const at = last?.id === through ? last.at : null;
+    // A reset that lands where the mark already is still counts: the owner asked for a fresh findings key.
+    const stays = through >= mark.throughId;
+    const [last] = !stays && through > 0 ? await store.mail.emailsBefore(account.id, through + 1, 1) : [];
     const next = {
-        throughId: through,
-        throughAt: at,
+        throughId: stays ? mark.throughId : through,
+        throughAt: stays ? mark.throughAt : last?.id === through ? last.at : null,
         held: mark.held.filter((id) => id <= through),
         suspicious: mark.suspicious.filter((id) => id <= through),
         read: mark.read,

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

@@ -65,6 +65,7 @@ export interface FindingsReceipt {
 }
 export declare const findingText: (value: unknown, limit: number) => string;
 export declare const findingHash: (value: unknown) => string;
+export declare const snakeCase: (key: string) => string;
 /**
  * Refuses a field `allowed` does not list, naming it, the finding it is in and what that kind takes: an agent fixes
  * the batch from the message alone. `of` is the finding a nested object (an invoice line) belongs to.
@@ -73,6 +74,8 @@ export declare const findingFields: (value: object, allowed: string[], noun: str
     id?: unknown;
     kind?: unknown;
 }) => void;
+/** Refuses a finding that leaves out a field `needed` lists, naming each one missing and all it needs. */
+export declare const findingNeeds: (value: Record<string, unknown>, needed: readonly string[], noun: string) => void;
 /** What differs between findings kinds: their wording and what one cited reference must look like. */
 export interface FindingsRules {
     /** "meeting findings" */
@@ -96,7 +99,7 @@ export declare const findingId: (raw: unknown, ids: Set<string>) => string;
 /** One fact, payment or task finding, its ID added to `ids`. */
 export declare const validateFinding: (finding: Finding, rules: FindingsRules, ids: Set<string>) => Finding;
 /** A date's or assignee's support: references the finding's own evidence cites. */
-export declare const support: (value: unknown, evidence: readonly FindingEvidence[]) => string[];
+export declare const support: (value: unknown, evidence: readonly FindingEvidence[], field: string) => string[];
 /** A batch's envelope — schema version, key, extractor — around 1–`most` findings each `one` checks. */
 export declare const validateBatch: <F>(input: {
     schemaVersion: 1;

package/dist/meetings/findings-rules.js

@@ -12,7 +12,15 @@ export const findingText = (value, limit) => {
     return value.trim();
 };
 export const findingHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+export const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+const findingWhere = (of) => {
+    const id = typeof of.id === "string" ? of.id : null;
+    const kind = typeof of.kind === "string" ? of.kind : null;
+    return {
+        where: id || kind ? ` in ${[id, kind && `(${kind})`].filter(Boolean).join(" ")}` : "",
+        named: { ...(id ? { finding: id } : {}), ...(kind ? { kind } : {}) },
+    };
+};
 /**
  * Refuses a field `allowed` does not list, naming it, the finding it is in and what that kind takes: an agent fixes
  * the batch from the message alone. `of` is the finding a nested object (an invoice line) belongs to.
@@ -23,16 +31,18 @@ export const findingFields = (value, allowed, noun, of = value) => {
         return;
     const fields = unknown.map(snakeCase);
     const takes = allowed.map(snakeCase);
-    const id = typeof of.id === "string" ? of.id : null;
-    const kind = typeof of.kind === "string" ? of.kind : null;
-    const where = id || kind ? ` in ${[id, kind && `(${kind})`].filter(Boolean).join(" ")}` : "";
-    throw new CliError("validation_error", `unknown ${noun} field${fields.length > 1 ? "s" : ""} ${fields.join(", ")}${where}; it takes ${takes.join(", ")}`, {
-        reason: "finding.unknown-field",
-        fields,
-        allowed: takes,
-        ...(id ? { finding: id } : {}),
-        ...(kind ? { kind } : {}),
-    });
+    const { where, named } = findingWhere(of);
+    throw new CliError("validation_error", `unknown ${noun} field${fields.length > 1 ? "s" : ""} ${fields.join(", ")}${where}; it takes ${takes.join(", ")}`, { reason: "finding.unknown-field", fields, allowed: takes, ...named });
+};
+/** Refuses a finding that leaves out a field `needed` lists, naming each one missing and all it needs. */
+export const findingNeeds = (value, needed, noun) => {
+    const missing = needed.filter((key) => value[key] === undefined);
+    if (!missing.length)
+        return;
+    const fields = missing.map(snakeCase);
+    const needs = needed.map(snakeCase);
+    const { where, named } = findingWhere(value);
+    throw new CliError("validation_error", `missing ${noun} field${fields.length > 1 ? "s" : ""} ${fields.join(", ")}${where}; it needs ${needs.join(", ")}`, { reason: "finding.missing-field", fields, needs, ...named });
 };
 const SUBJECT = /^(person|organization|project):[1-9]\d*$|^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
 /** A finding's cited evidence: 1–8 distinct references in `rules`' form, each with a 64-hex fingerprint. */
@@ -130,9 +140,12 @@ export const validateFinding = (finding, rules, ids) => {
         return invalid("a task finding type is bug, chore or feature");
     if (!["explicit", "inferred"].includes(finding.commitment))
         return invalid("task commitment must be explicit or inferred");
-    if ((finding.dueAt === undefined) !== (finding.dueEvidence === undefined) ||
-        (finding.assignee === undefined) !== (finding.assigneeEvidence === undefined))
-        return invalid("optional dates and assignees require their supporting evidence");
+    if ((finding.dueAt === undefined) !== (finding.dueEvidence === undefined))
+        return invalid(`due_at comes with due_evidence: the ${rules.cited} references of this finding's evidence that give the date, ` +
+            `as a list of strings such as ["<reference>"]`);
+    if ((finding.assignee === undefined) !== (finding.assigneeEvidence === undefined))
+        return invalid(`assignee comes with assignee_evidence: the ${rules.cited} references of this finding's evidence that name ` +
+            `them, as a list of strings such as ["<reference>"]`);
     if (finding.assignee !== undefined &&
         (typeof finding.assignee !== "string" || !/^person:[1-9]\d*$/.test(finding.assignee)))
         return invalid("an assignee must be a person reference");
@@ -146,21 +159,25 @@ export const validateFinding = (finding, rules, ids) => {
         ...(finding.dueAt === undefined
             ? {}
             : {
-                dueAt: meetingTimestamp(finding.dueAt, "finding due date"),
-                dueEvidence: support(finding.dueEvidence, evidence),
+                dueAt: meetingTimestamp(finding.dueAt, "a task's due_at"),
+                dueEvidence: support(finding.dueEvidence, evidence, "due_evidence"),
             }),
         ...(finding.assignee === undefined
             ? {}
-            : { assignee: finding.assignee, assigneeEvidence: support(finding.assigneeEvidence, evidence) }),
+            : {
+                assignee: finding.assignee,
+                assigneeEvidence: support(finding.assigneeEvidence, evidence, "assignee_evidence"),
+            }),
     };
 };
 /** A date's or assignee's support: references the finding's own evidence cites. */
-export const support = (value, evidence) => {
+export const support = (value, evidence, field) => {
     if (!Array.isArray(value) ||
         value.length < 1 ||
         value.length > 8 ||
         value.some((ref) => typeof ref !== "string" || !evidence.some((item) => item.reference === ref)))
-        return invalid("date and assignee support must cite the finding's evidence");
+        return invalid(`${field} lists 1–8 references this finding's evidence cites, as plain strings such as ["<reference>"], ` +
+            "not evidence objects");
     return [...new Set(value)].sort();
 };
 /** A batch's envelope — schema version, key, extractor — around 1–`most` findings each `one` checks. */

package/dist/meetings/index.d.ts

@@ -9,7 +9,7 @@ export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, type MeetingExport, type MeetingExportFormat, type MeetingExportOptions, serializeVtt, } from "./export.js";
 export { type FindingEvidence, type FindingOutcome, findingHash, MEETING_FINDINGS_KIND, type MeetingFactFinding, type MeetingFinding, type MeetingFindingsInput, type MeetingFindingsReceipt, type MeetingTaskFinding, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
-export { type FactFinding, type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFields, findingFingerprint, findingId, findingText, type PaymentFinding, type TaskFinding, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
+export { type FactFinding, type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFields, findingFingerprint, findingId, findingNeeds, findingText, type PaymentFinding, snakeCase, type TaskFinding, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { type ImportFile, importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, type MeetingIssue, type MeetingItem, type MeetingOwner, meeting, meetingIssuesOf, meetingItem, } from "./item.js";

package/dist/meetings/index.js

@@ -6,7 +6,7 @@ export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, serializeVtt, } from "./export.js";
 export { findingHash, MEETING_FINDINGS_KIND, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
-export { findingFields, findingFingerprint, findingId, findingText, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
+export { findingFields, findingFingerprint, findingId, findingNeeds, findingText, snakeCase, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, meeting, meetingIssuesOf, meetingItem, } from "./item.js";

package/dist/meetings/timestamp.js

@@ -3,7 +3,7 @@ export const meetingTimestamp = (value, name) => {
     if (typeof value !== "string" ||
         !/^\d{4}-\d{2}-\d{2}T.+(?:Z|[+-]\d{2}:\d{2})$/i.test(value) ||
         !Number.isFinite(Date.parse(value)))
-        throw new CliError("validation_error", `${name} must be an ISO timestamp with a timezone`);
+        throw new CliError("validation_error", `${name} must be an ISO timestamp with a timezone, such as 2026-11-09T09:00:00Z`);
     const date = value.slice(0, 10);
     const instant = Date.parse(`${date}T00:00:00Z`);
     if (!Number.isFinite(instant) || new Date(instant).toISOString().slice(0, 10) !== date)

package/dist/store/sqlite/finance.d.ts

@@ -159,6 +159,8 @@ export interface FinanceStore {
         /** Issued or partly paid. */
         open?: boolean;
         counterparty?: string;
+        /** The number printed on it, exactly. */
+        number?: string;
     }): Promise<Invoice[]>;
     /** The owner sends a draft: its status then follows its allocations. */
     issueInvoice(reference: string, by: Author): Promise<InvoiceDetail>;

package/dist/store/sqlite/finance.js

@@ -402,10 +402,10 @@ export const financeOperationsOver = (context) => {
             return database
                 .prepare(`${INVOICES} WHERE i.deleted_at IS NULL AND (? IS NULL OR i.direction = ?) AND (? IS NULL OR i.status = ?) ` +
                 "AND (? IS NULL OR i.review = ?) AND (? IS NULL OR i.project_id = ?) " +
-                "AND (? IS NULL OR (i.counterparty_type = ? AND i.counterparty_id = ?)) " +
+                "AND (? IS NULL OR (i.counterparty_type = ? AND i.counterparty_id = ?)) AND (? IS NULL OR i.number = ?) " +
                 `${filter.open ? "AND i.status IN ('issued', 'partly_paid') " : ""}AND ${by.sql} ` +
                 "ORDER BY i.created_at DESC, i.id DESC LIMIT ?")
-                .all(filter.direction ?? null, filter.direction ?? null, status, status, review, review, project, project, counterparty?.type ?? null, counterparty?.type ?? null, counterparty?.id ?? null, ...by.params, limitOf(filter.limit))
+                .all(filter.direction ?? null, filter.direction ?? null, status, status, review, review, project, project, counterparty?.type ?? null, counterparty?.type ?? null, counterparty?.id ?? null, filter.number ?? null, filter.number ?? null, ...by.params, limitOf(filter.limit))
                 .map(invoiceOf);
         },
         issueInvoice: (reference, by) => {

package/package.json

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