@wirecat/cli-core 0.567.0 → 0.568.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.568.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **`holderHasMail` is gone: `mailWaiting` checks and `advancePastSkipped` moves.** `holderHasMail` read like a
+  check but moved the holder's mark on every schedule tick. `mailWaiting(store, holder)` only reads: how many emails
+  past the holder's marks would reach it and when the oldest was stored, or `unmarked`. `advancePastSkipped(store,
+  holder)` moves the mark over the mail at its head the holder would only skip, and leaves it for the next check when
+  a sync holds the store. `ScheduleHost.newMail` now returns `MailWaiting`. A host calls `advancePastSkipped`, then
+  `mailWaiting`.
+- **A gated agent schedule waits for a batch of mail.** On its timer, `schedule agent --on-new-mail <holder>` starts
+  the agent once 10 emails wait for it or the oldest has waited 30 minutes; `--mail-wait <duration>` and
+  `--mail-batch <n>` change that per schedule, and a host's `ScheduleHost.limits` gives its config file's values
+  (`SCHEDULE_SETTINGS`, read with `scheduleLimitsOf`): flag, then config file, then default. `schedule run` by hand
+  still starts it for any mail. Its skipped answer names `why` instead of `holder`.
+- **An agent schedule stops for the day at a cost cap.** A claude run is asked for its JSON answer, so its cost
+  (`total_cost_usd`) is kept in `last.json` (`costUsd`) and summed per local day in `spend.json`; the report kept is
+  the answer's text. Once a day's runs cost `--max-cost-per-day` (default 5 US dollars, or the config file's; 0 for
+  none), no run starts until the next day; `last.json` says why under `skipped`, and `schedule list` shows the day's
+  spend and the skip.
+- **`messages acknowledge` moves only a holder the caller may move.** A run that `schedule agent --on-new-mail` started
+  gets `<PREFIX>_MAIL_HOLDER` and moves that holder's mark only; any other agent, or a run under the read-only lock,
+  is refused with `mail.holder-not-yours`; the owner moves any. A cursor past the newest stored email, or read in the
+  future, is refused with `mail.cursor-ahead`. A scheduled triage agent needs `--on-new-mail`.
+- **`review --holder` leaves out suspicious senders, and now keeps them on the mark.** Their
+  emails stay on the holder's mark and come in a later review once the sender's score is cleared, instead of being
+  passed for good. This was listed under Added in the release that brought it; it changes what an existing caller
+  reads.
+- **A mail findings citation of an email the store does not hold is `not_found`** with reason
+  `mail-findings.not-stored`, no longer `mail-findings.stale`, which told the agent to read the mailbox again. An email
+  deleted after the batch was staged still makes accepting it stale.
+- **`parseMailFindingsJson`, `parseMeetingFindingsJson` and `parseEvidenceFindingsJson` live in
+  `src/cli/findings-input.ts`;** the exports from `@wirecat/cli-core/cli` are unchanged. `findingText` and
+  `findingFields` are the checks themselves, not wrappers.
+
+### Fixed
+
+- **An accepted `new_contact` mail finding names the person.** Sync already names a sender's person from the From
+  display name, so accepting set nothing while the receipt said accepted; the owner's chosen name now replaces it.
+- **`mail review` offers at most two next steps.** It gave one `conversations show` step per cut thread, up to 50;
+  it now gives one, and names the other cut threads under `missing`.
+
 ## 0.567.0 — 05.11.2026
 
 ### Added

package/dist/background/schedules.d.ts

@@ -19,7 +19,27 @@ export interface Schedule {
     createdAt: string;
     /** A holder whose mark gates the run: it starts only when mail is stored past that mark. */
     onNewMail?: string;
+    /** Gated on mail: start once the oldest waiting email has waited this many minutes, or `mailBatch` emails wait. */
+    mailWaitMinutes?: number;
+    mailBatch?: number;
+    /** An agent's: no run starts for the rest of the local day once its runs cost this much, in US dollars. */
+    maxCostPerDay?: number;
 }
+/** What a gated agent waits for, and what a day of its runs may cost, when neither its flags nor the config say. */
+export declare const SCHEDULE_DEFAULTS: {
+    readonly mailWaitMinutes: 30;
+    readonly mailBatch: 10;
+    readonly maxCostPerDay: 5;
+};
+/** One local day's cost of a schedule's runs, as the harness reported it (`spend.json` beside the schedule). */
+export interface DaySpend {
+    /** The local date, YYYY-MM-DD. */
+    day: string;
+    usd: number;
+}
+export declare const localDay: (at: Date) => string;
+/** What the schedule's runs cost today; nothing before its first priced run of the day. */
+export declare const spentToday: (file: string, now?: Date) => number;
 /** Another CLI a scheduled agent may run by name, as the host declares it: `memo`'s agent runs `mail`. */
 export type AgentCli = Pick<AppIdentity, "command" | "appName" | "envPrefix">;
 export interface LastRun {
@@ -37,6 +57,13 @@ export interface LastRun {
     failingSince?: string;
     /** Failed runs in a row; absent once a run succeeds. */
     failures?: number;
+    /** What the run cost, as the harness reported it; absent when it reports none. */
+    costUsd?: number;
+    /** The last time the timer did not start it, and why; a run after it clears this. */
+    skipped?: {
+        at: string;
+        why: string;
+    };
 }
 /**
  * Why a failed run failed, from the error object the CLI printed last: its code and reason id. Never the
@@ -60,7 +87,10 @@ export declare const recordRun: (path: string, run: {
     traceId?: string;
     reason?: string;
     errorCode?: string;
+    costUsd?: number;
 }) => LastRun;
+/** Notes on the last run that the timer left this one out, keeping that run's result. */
+export declare const recordSkip: (file: string, why: string, at?: Date) => void;
 /**
  * One stderr line per failing background job, or nothing: `tg: scheduled digest failing since … (3 runs):
  * <reason> — tg schedule list`. A status the owner has to ask for is how a broken timer goes unnoticed.

package/dist/background/schedules.js

@@ -1,10 +1,54 @@
 import { spawn } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { CliError, errorCodes, writeSecurely } from "@wirecat/cli-base";
-import { readOnlyLockOf } from "../ports/app.js";
+import { mailHolderVariable, readOnlyLockOf } from "../ports/app.js";
 import { recordLogFor } from "../runs/record-log.js";
 import { childTrace } from "../runs/scope.js";
+/** What a gated agent waits for, and what a day of its runs may cost, when neither its flags nor the config say. */
+export const SCHEDULE_DEFAULTS = { mailWaitMinutes: 30, mailBatch: 10, maxCostPerDay: 5 };
+export const localDay = (at) => `${at.getFullYear()}-${String(at.getMonth() + 1).padStart(2, "0")}-${String(at.getDate()).padStart(2, "0")}`;
+const spendFile = (file) => join(file, "..", "spend.json");
+/** What the schedule's runs cost today; nothing before its first priced run of the day. */
+export const spentToday = (file, now = new Date()) => {
+    try {
+        const spend = JSON.parse(readFileSync(spendFile(file), "utf8"));
+        return spend.day === localDay(now) && typeof spend.usd === "number" ? spend.usd : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+const addSpend = (folder, usd, at) => {
+    const file = join(folder, "schedule.json");
+    const spend = { day: localDay(at), usd: spentToday(file, at) + usd };
+    writeFileSync(spendFile(file), `${JSON.stringify(spend)}\n`, { mode: 0o600 });
+};
+/**
+ * Claude reports a run's cost only in its JSON answer, so a scheduled claude run asks for it; the report kept is the
+ * answer's text. Codex reports none.
+ */
+const priced = (argv) => {
+    const [program = ""] = argv;
+    const claude = /^claude(\.exe|\.cmd)?$/i.test(basename(program));
+    return claude && argv.includes("-p") && !argv.includes("--output-format")
+        ? [...argv, "--output-format", "json"]
+        : argv;
+};
+const reportOf = (stdout) => {
+    try {
+        const answer = JSON.parse(stdout.toString("utf8"));
+        if (answer?.type !== "result")
+            return { text: stdout };
+        return {
+            text: typeof answer.result === "string" ? Buffer.from(answer.result) : stdout,
+            ...(typeof answer.total_cost_usd === "number" ? { costUsd: answer.total_cost_usd } : {}),
+        };
+    }
+    catch {
+        return { text: stdout };
+    }
+};
 const REASON_ID = /^[a-z0-9][a-z0-9.-]{0,79}$/;
 /**
  * Why a failed run failed, from the error object the CLI printed last: its code and reason id. Never the
@@ -52,6 +96,14 @@ export const recordRun = (path, run) => {
     writeSecurely(path, `${JSON.stringify(last, null, 2)}\n`, 0o600);
     return last;
 };
+/** Notes on the last run that the timer left this one out, keeping that run's result. */
+export const recordSkip = (file, why, at = new Date()) => {
+    const path = join(file, "..", "last.json");
+    const before = readRun(path);
+    if (!before)
+        return;
+    writeSecurely(path, `${JSON.stringify({ ...before, skipped: { at: at.toISOString(), why } }, null, 2)}\n`, 0o600);
+};
 const shortTime = (iso) => {
     const at = new Date(iso);
     const two = (n) => String(n).padStart(2, "0");
@@ -408,13 +460,14 @@ const attemptSchedule = async (app, system, env, schedule, folder, { now, signal
     const agent = schedule.kind === "agent";
     const output = join(runs, `${stamp}.${agent ? "md" : "log"}`);
     const errors = agent ? join(runs, `${stamp}.log`) : output;
-    const [program = "", ...args] = agent ? schedule.argv : [...system.entry, ...schedule.argv];
+    const [program = "", ...args] = agent ? priced(schedule.argv) : [...system.entry, ...schedule.argv];
     const trace = childTrace();
     const childEnv = {
         ...env,
         ...schedule.environment,
         TRACEPARENT: trace.traceparent,
         [`${app.envPrefix}_SCHEDULED`]: schedule.name,
+        ...(schedule.onNewMail ? { [mailHolderVariable(app)]: schedule.onNewMail } : {}),
         // A run started under the lock stays under it, whatever the schedule file says.
         ...(agent || readOnlyLockOf(app, env) ? { [`${app.envPrefix}_READ_ONLY`]: "1" } : {}),
         ...(agent
@@ -430,6 +483,7 @@ const attemptSchedule = async (app, system, env, schedule, folder, { now, signal
     const facts = { schedule: schedule.name, kind: schedule.kind };
     const began = now().getTime();
     log.info({ event: "schedule.start", ...facts });
+    let costUsd;
     const exitCode = await new Promise((resolve) => {
         const child = spawn(program, args, { env: childEnv, cwd: folder, stdio: ["ignore", "pipe", "pipe"] });
         const out = [];
@@ -454,24 +508,30 @@ const attemptSchedule = async (app, system, env, schedule, folder, { now, signal
             signal?.removeEventListener("abort", stop);
             if (kill)
                 clearTimeout(kill);
-            writeFileSync(output, Buffer.concat(agent ? out : [...out, ...err]), { mode: 0o600 });
+            const report = agent ? reportOf(Buffer.concat(out)) : { text: Buffer.concat([...out, ...err]) };
+            costUsd = report.costUsd;
+            writeFileSync(output, report.text, { mode: 0o600 });
             if (agent)
                 writeFileSync(errors, Buffer.concat(err), { mode: 0o600 });
             resolve(code ?? (killedBy === "SIGKILL" ? 137 : killedBy === "SIGTERM" ? 143 : 1));
         });
     });
     const ended = now();
+    if (costUsd !== undefined)
+        addSpend(folder, costUsd, ended);
     log[exitCode === 0 ? "info" : "error"]({
         event: "schedule.exit",
         ...facts,
         exitCode,
         durationMs: ended.getTime() - began,
+        ...(costUsd === undefined ? {} : { costUsd }),
     });
     return recordRun(join(folder, "last.json"), {
         at: ended.toISOString(),
         exitCode,
         output,
         traceId: trace.traceId,
+        ...(costUsd === undefined ? {} : { costUsd }),
         ...(exitCode === 0 ? {} : failureOf(readFileSync(errors, "utf8"), exitCode)),
     });
 };

package/dist/cli/index.d.ts

@@ -75,6 +75,7 @@ export { admittedUnderLock, changesAuthority, changesAuthorityAt, changesAuthori
 export { type CliEntry, type EntryContext, type EntryIo, openBrowser, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./findings-input.js";
 export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
@@ -87,7 +88,6 @@ export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists,
 export { MCP_HTTP_DEFAULT_PORT, type McpServerOptions, type McpServerTarget, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
-export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./meeting-findings-input.js";
 export { meetingPreparationAnswer } from "./meeting-preparation-answer.js";
 export { type MeetingPreparationReader, meetingPreparationInput, readMeetingPreparation, } from "./meeting-preparation-read.js";
 export { readMeetingProjectCandidates } from "./meeting-project-candidates-read.js";
@@ -120,7 +120,7 @@ export { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEv
 export { type ProjectStatusHints, type ProjectStatusItem, projectStatusAnswer, projectStatusRow, projectStatusSchema, projectStatusText, } from "./project-status.js";
 export { STATUS_ROWS, STATUS_SIGNAL_ROWS } from "./project-status-rows.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
-export type { ScheduleHost } from "./schedule/schedule-command.js";
+export { SCHEDULE_SETTINGS, type ScheduleHost, type ScheduleLimits, scheduleLimitsOf, } from "./schedule/schedule-command.js";
 export { type DeclaredSetting, type SettingRow, settingRows, withSettingDefaults } from "./setting-defaults.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, namedProfile, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
 export { type PermissionAnswer, readSetupAnswers, type SetupAnswers, setupPermissionCeiling } from "./setup-answers.js";

package/dist/cli/index.js

@@ -66,6 +66,7 @@ export { admittedUnderLock, changesAuthority, changesAuthorityAt, changesAuthori
 export { openBrowser, startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./findings-input.js";
 export { askSetupQuestions, asksAtStart, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
@@ -78,7 +79,6 @@ export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists,
 export { MCP_HTTP_DEFAULT_PORT, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
-export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./meeting-findings-input.js";
 export { meetingPreparationAnswer } from "./meeting-preparation-answer.js";
 export { meetingPreparationInput, readMeetingPreparation, } from "./meeting-preparation-read.js";
 export { readMeetingProjectCandidates } from "./meeting-project-candidates-read.js";
@@ -109,6 +109,7 @@ export { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWind
 export { projectStatusAnswer, projectStatusRow, projectStatusSchema, projectStatusText, } from "./project-status.js";
 export { STATUS_ROWS, STATUS_SIGNAL_ROWS } from "./project-status-rows.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
+export { SCHEDULE_SETTINGS, scheduleLimitsOf, } from "./schedule/schedule-command.js";
 export { settingRows, withSettingDefaults } from "./setting-defaults.js";
 export { count, first, flag, fromFile, NONE_NAMED, namedProfile, plain, settingsFor, } from "./settings.js";
 export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";

package/dist/cli/schedule/schedule-command.d.ts

@@ -1,7 +1,9 @@
 import { Command } from "commander";
-import { type AgentCli } from "../../background/schedules.js";
+import { type AgentCli, type Schedule } from "../../background/schedules.js";
+import { type MailWaiting } from "../../mail/marks.js";
 import { type AppIdentity } from "../../ports/app.js";
 import { type AnswerOutput } from "../envelope.js";
+import type { DeclaredSetting } from "../setting-defaults.js";
 export interface ScheduleHost {
     app: AppIdentity;
     context(command: Command, resolving?: {
@@ -11,19 +13,30 @@ export interface ScheduleHost {
         profile: string;
     };
     /**
-     * Whether mail is stored past the holder's mark (`holderHasMail`). Given, `schedule agent` takes `--on-new-mail`:
-     * the agent then runs only after a sync stored mail it has not processed.
+     * What mail waits past the holder's mark (`mailWaiting`). Given, `schedule agent` takes `--on-new-mail`: the agent
+     * then runs only once enough of it waits, or the oldest has waited long enough.
      */
-    newMail?: (command: Command, holder: string) => Promise<boolean>;
+    newMail?: (command: Command, holder: string) => Promise<MailWaiting>;
+    /** The config file's limits for agent schedules; a schedule's own flags win, `SCHEDULE_DEFAULTS` fill the rest. */
+    limits?: (command: Command) => ScheduleLimits;
     /**
      * Other CLIs the scheduled agent may run besides this one, each under its own `<PREFIX>_READ_ONLY`: memo's mail
      * triage runs `mail`. Claude may run them; codex may write their state, config and cache folders.
      */
     agentRuns?: readonly AgentCli[];
 }
+export type ScheduleLimits = Partial<Pick<Schedule, "mailWaitMinutes" | "mailBatch" | "maxCostPerDay">>;
+/** The agent-schedule limits a host with `newMail` writes into its config file's top level (WC-CMD-30). */
+export declare const SCHEDULE_SETTINGS: readonly DeclaredSetting[];
+/** `SCHEDULE_SETTINGS` as the config file gives them; a missing or unusable value is left to the default. */
+export declare const scheduleLimitsOf: (config: {
+    schedule_mail_wait?: unknown;
+    schedule_mail_batch?: unknown;
+    schedule_max_cost_per_day?: unknown;
+}) => ScheduleLimits;
 /**
  * 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
  * the rest, so what runs and with which variables is the same on all three.
  */
-export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, agentRuns }: ScheduleHost) => Command;
+export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, limits: configured, agentRuns, }: ScheduleHost) => Command;

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

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { CliError, resolvePaths, writeSecurely } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Argument, Command, Option } from "commander";
-import { describeWhen, findProgram, lastRun, listSchedules, readSchedule, runSchedule, scheduleFile, scheduleName, timerFor, } from "../../background/schedules.js";
+import { describeWhen, findProgram, lastRun, listSchedules, readSchedule, recordSkip, runSchedule, SCHEDULE_DEFAULTS, scheduleFile, scheduleName, spentToday, timerFor, } from "../../background/schedules.js";
 import { thisMachine } from "../../background/system.js";
 import { locationVariables } from "../../background/units.js";
 import { parseDuration } from "../../domain/duration.js";
@@ -76,12 +76,43 @@ const withWhen = (command) => command
 const promptExample = (app) => app.messenger === false
     ? `summarize what came in during the last day: ${app.command} personal search messages 'date>1d' --newest --limit 20`
     : `run the daily follow-up review: ${app.command} skill show follow-ups`;
+/** The agent-schedule limits a host with `newMail` writes into its config file's top level (WC-CMD-30). */
+export const SCHEDULE_SETTINGS = [
+    {
+        key: "schedule_mail_wait",
+        default: `${SCHEDULE_DEFAULTS.mailWaitMinutes}m`,
+        description: "an agent gated on new mail starts once the oldest waiting email has waited this long",
+    },
+    {
+        key: "schedule_mail_batch",
+        default: SCHEDULE_DEFAULTS.mailBatch,
+        description: "or once this many emails wait for it",
+    },
+    {
+        key: "schedule_max_cost_per_day",
+        default: SCHEDULE_DEFAULTS.maxCostPerDay,
+        description: "US dollars an agent schedule's runs may cost in a day before it waits for the next; 0 for no cap",
+    },
+];
+/** `SCHEDULE_SETTINGS` as the config file gives them; a missing or unusable value is left to the default. */
+export const scheduleLimitsOf = (config) => {
+    const { schedule_mail_wait: wait, schedule_mail_batch: batch, schedule_max_cost_per_day: cap } = config;
+    return {
+        ...(typeof wait === "string"
+            ? { mailWaitMinutes: Math.ceil(parseDuration(wait, "schedule_mail_wait") / 60_000) }
+            : {}),
+        ...(typeof batch === "number" && Number.isSafeInteger(batch) && batch >= 1 ? { mailBatch: batch } : {}),
+        ...(typeof cap === "number" && Number.isFinite(cap) && cap >= 0 ? { maxCostPerDay: cap } : {}),
+    };
+};
+const given = (limits) => Object.fromEntries(Object.entries(limits).filter(([, value]) => value !== undefined));
+const usd = (value) => `$${value.toFixed(2)}`;
 /**
  * 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
  * the rest, so what runs and with which variables is the same on all three.
  */
-export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns = [] }) => {
+export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: configured, agentRuns = [], }) => {
     const agentClis = [app, ...agentRuns];
     const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
     const prepare = (self, resolving = {}) => {
@@ -118,12 +149,44 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
         };
         return { context, system, state, say, timer, environment, save };
     };
-    /** A schedule gated on new mail waits while nothing is stored past its holder's mark. */
-    const waits = async (self, file) => {
-        const holder = existsSync(file) ? readSchedule(file).onNewMail : undefined;
-        if (holder === undefined || !newMail || (await newMail(self, holder)))
+    /**
+     * 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.
+     */
+    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,
+            }),
+        };
+        if (schedule.kind === "agent" && maxCostPerDay > 0) {
+            const spent = spentToday(file);
+            if (spent >= maxCostPerDay) {
+                const why = `today's runs cost ${usd(spent)}, the ${usd(maxCostPerDay)} a day allowed; it runs again tomorrow`;
+                recordSkip(file, why);
+                return why;
+            }
+        }
+        const holder = schedule.onNewMail;
+        if (holder === undefined || !newMail)
+            return undefined;
+        const waiting = await newMail(self, holder);
+        if (waiting.unmarked)
+            return undefined;
+        if (waiting.emails === 0)
+            return `no mail stored past ${holder}'s mark`;
+        const waited = waiting.oldestStoredAt === null ? 0 : Date.now() - waiting.oldestStoredAt;
+        if (!timed || waiting.emails >= mailBatch || waited >= mailWaitMinutes * 60_000)
             return undefined;
-        return holder;
+        return (`${waiting.emails} email(s) wait past ${holder}'s mark; it starts at ${mailBatch}, ` +
+            `or once the oldest has waited ${mailWaitMinutes}m`);
     };
     withWhen(grantsAuthority(annotate(command.command("command"), {
         literal_after_dashes: true,
@@ -159,11 +222,20 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
         .argument("<name>", "lowercase letters, digits and dashes")
         .addArgument(new Argument("<harness>", "the agent to start").choices(HARNESSES))
         .argument("<prompt>", `what to do, e.g. "${promptExample(app)}"`)
-        .addOption(new Option("--max-cost <usd>", "claude only: stop a run that costs more than this, in US dollars").argParser(Number))).action(async function (name, harness, prompt) {
+        .addOption(new Option("--max-cost <usd>", "claude only: stop a run that costs more than this, in US dollars").argParser(Number))
+        .addOption(new Option("--max-cost-per-day <usd>", `claude only: start no run for the rest of the day once its runs cost this much, in US dollars; 0 for no cap (default ${SCHEDULE_DEFAULTS.maxCostPerDay}, or the config file's)`).argParser(Number))).action(async function (name, harness, prompt) {
         const { context, system, environment, save } = prepare(this);
         const options = this.opts();
         if (options.onNewMail !== undefined && !HOLDER.test(options.onNewMail))
             throw new CliError("validation_error", `--on-new-mail takes a holder: lower-case letters, digits and dashes`);
+        if ((options.mailWait !== undefined || options.mailBatch !== undefined) && options.onNewMail === undefined)
+            throw new CliError("validation_error", "--mail-wait and --mail-batch shape a run gated by --on-new-mail");
+        if (options.maxCostPerDay !== undefined && !(Number.isFinite(options.maxCostPerDay) && options.maxCostPerDay >= 0))
+            throw new CliError("validation_error", "--max-cost-per-day takes US dollars, 0 or more");
+        const mailBatch = options.mailBatch === undefined ? undefined : Number(options.mailBatch);
+        if (mailBatch !== undefined && !(Number.isSafeInteger(mailBatch) && mailBatch >= 1))
+            throw new CliError("validation_error", "--mail-batch takes a count of emails, 1 or more");
+        const mailWaitMinutes = options.mailWait === undefined ? undefined : Math.ceil(parseDuration(options.mailWait, "--mail-wait") / 60_000);
         const program = findProgram(harness, context.env, system.platform);
         if (!program)
             throw new CliError("not_found", `${harness} is not on PATH`);
@@ -205,12 +277,17 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
             environment: environment(),
             createdAt: new Date().toISOString(),
             ...(options.onNewMail ? { onNewMail: options.onNewMail } : {}),
+            ...(mailWaitMinutes === undefined ? {} : { mailWaitMinutes }),
+            ...(mailBatch === undefined ? {} : { mailBatch }),
+            ...(options.maxCostPerDay === undefined ? {} : { maxCostPerDay: options.maxCostPerDay }),
         });
     });
     if (newMail)
         command.commands
             .find((one) => one.name() === "agent")
-            ?.option("--on-new-mail <holder>", `run only when mail is stored past this holder's mark — after a sync brought new mail; may check every ${GATED_AGENT_MINIMUM_MINUTES}m`);
+            ?.option("--on-new-mail <holder>", `run only when mail is stored past this holder's mark — after a sync brought new mail; may check every ${GATED_AGENT_MINIMUM_MINUTES}m`)
+            .option("--mail-wait <duration>", `with --on-new-mail: start once the oldest waiting email has waited this long (default ${SCHEDULE_DEFAULTS.mailWaitMinutes}m, or the config file's)`)
+            .option("--mail-batch <n>", `with --on-new-mail: or once this many emails wait (default ${SCHEDULE_DEFAULTS.mailBatch}, or the config file's)`);
     withQuery(annotate(command.command("list"), {
         effects: LOCAL_READ,
         examples: [`${app.command} personal schedule list`, `${app.command} personal schedule list kind:agent`],
@@ -224,6 +301,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
             kind: schedule.kind,
             when: describeWhen(schedule.when),
             last: lastRun(scheduleFile(state, schedule.name)) ?? null,
+            ...(schedule.kind === "agent" ? { spentTodayUsd: spentToday(scheduleFile(state, schedule.name)) } : {}),
         }));
         const answer = listOf("schedule list", {
             items: rows.map((row) => snakeKeys(row)),
@@ -236,7 +314,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
                 return "";
             }
             return rows
-                .map(({ name, kind, when, last }) => [
+                .map(({ name, kind, when, last, spentTodayUsd }) => [
                 name,
                 kind,
                 when,
@@ -247,6 +325,10 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
                                 `${last.failures} in a row${last.reason ? `: ${last.reason}` : ""} — ${last.output}`
                             : "")
                     : "not run yet",
+                ...(spentTodayUsd ? [`today ${usd(spentTodayUsd)}`] : []),
+                ...(last?.skipped
+                    ? [`skipped ${last.skipped.at.slice(0, 16).replace("T", " ")}: ${last.skipped.why}`]
+                    : []),
             ].join("  "))
                 .join("\n");
         });
@@ -259,9 +341,9 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
         .argument("<name>", "the schedule's name, as `schedule list` shows it")
         .action(async function (name) {
         const { context, system, state, say, timer } = prepare(this);
-        const holder = await waits(this, scheduleFile(state, scheduleName(name)));
-        if (holder !== undefined)
-            return say({ name, skipped: true, holder }, [`${name}: skipped — no mail stored past ${holder}'s mark`]);
+        const why = await waits(this, scheduleFile(state, scheduleName(name)), { timed: false });
+        if (why !== undefined)
+            return say({ name, skipped: true, why }, [`${name}: skipped — ${why}`]);
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
             timer: timer(),
             agentRuns,
@@ -295,7 +377,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
         .action(async function (file) {
         // A timer starts it with no profile named; the schedule's own environment carries the profile.
         const { context, system, timer } = prepare(this, { needsProfile: false });
-        if ((await waits(this, file)) !== undefined)
+        if ((await waits(this, file, { timed: true })) !== undefined)
             return;
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, file, {
             timer: timer(),

package/dist/cli/settings.js

@@ -247,7 +247,7 @@ export const settingsFor = (app, extension = {}) => {
     const declaredSettings = [...SHARED_SETTINGS, ...(extension.settings ?? [])]
         .filter(({ key, default: value }) => allSettings.includes(key) && v.safeParse(readSchema, { defaults: { [key]: value } }).success)
         .map((setting) => ({ ...setting, key: `defaults.${setting.key}` }));
-    // `defaults` needs no field of its own, so it is the one section created: every key then shows (RISK-2125).
+    // `defaults` needs no field of its own, so it is the one section created: every key then shows.
     const withDefaults = (raw, except = []) => withSettingDefaults(isScope(raw) && !Object.hasOwn(raw, "defaults") ? { ...raw, defaults: {} } : raw, declaredSettings.filter(({ key }) => !except.includes(key)));
     const PROFILE = envName(app, "PROFILE");
     const PROFILE_LOCK = envName(app, "PROFILE_LOCK");

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.568.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",

package/parity.json

@@ -565,6 +565,10 @@
       "value": "<usd>",
       "meaning": "stop an agent's run that costs more than this, in US dollars"
     },
+    "--max-cost-per-day": {
+      "value": "<usd>",
+      "meaning": "start no agent run for the rest of the day once its runs cost this much, in US dollars"
+    },
     "--max-gaps": {
       "value": "<n>",
       "meaning": "maximum interior coverage gaps repaired in this run"
@@ -3962,6 +3966,12 @@
           "planned": {
             "wa": "wa backlog: mount the shared schedule command"
           }
+        },
+        "--max-cost-per-day": {
+          "in": ["max", "tg"],
+          "planned": {
+            "wa": "wa backlog: mount the shared schedule command"
+          }
         }
       }
     },