@wirecat/cli-core 0.567.0 → 0.569.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.569.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **A claude agent schedule runs on Sonnet and starts lean.** `schedule agent` takes `--model <model>` (an alias such
+  as `sonnet` or `opus`, a model id, or `""` for the harness's own default). Without it, a claude schedule runs on
+  `sonnet` and a codex schedule on codex's own default; a host's config file may change either
+  (`schedule_model_claude`, `schedule_model_codex` in `SCHEDULE_SETTINGS`): flag, then config file, then default.
+  A new claude schedule also starts with `--tools Bash --strict-mcp-config --disable-slash-commands
+  --setting-sources ""`: none of the owner's MCP servers, skills, settings or CLAUDE.md, while `--permission-mode
+  dontAsk` and `--allowedTools` still hold. A "say ok" run measured $0.152 and 37,925 input tokens before, $0.019 and
+  4,740 after. `schedule_lean_start: false` keeps the owner's setup. Both are read when the schedule is added; an
+  existing schedule keeps its argv until it is added again. `ScheduleLimits` gains `models` and `leanStart`.
+
+## 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,11 @@
 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";
+declare const HARNESSES: readonly ["claude", "codex"];
+type Harness = (typeof HARNESSES)[number];
 export interface ScheduleHost {
     app: AppIdentity;
     context(command: Command, resolving?: {
@@ -11,19 +15,37 @@ 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 settings for agent schedules; a schedule's own flags win, the 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"> & {
+    models: Partial<Record<Harness, string>>;
+    leanStart: boolean;
+}>;
+/** The agent-schedule settings 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;
+    schedule_model_claude?: unknown;
+    schedule_model_codex?: unknown;
+    schedule_lean_start?: 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;
+export {};

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";
@@ -23,6 +23,15 @@ const AGENT_MINIMUM_MINUTES = 60;
 const GATED_AGENT_MINIMUM_MINUTES = 5;
 const COMMAND_MINIMUM_MINUTES = 1;
 const HARNESSES = ["claude", "codex"];
+/** A mid-tier model by default; codex has no alias of that tier, so it takes its own default. Empty: the harness's own. */
+const AGENT_MODELS = { claude: "sonnet", codex: "" };
+/** An alias or a model id; a leading dash would read as the harness's next flag. */
+const isModel = (model) => /^([A-Za-z0-9][\w.:/@[\]-]*)?$/.test(model);
+/**
+ * Claude starts without the owner's MCP servers, skills, settings and CLAUDE.md: a run reads its instructions
+ * through the CLI, and the rest was most of its starting context. Auth, `--permission-mode` and `--allowedTools` hold.
+ */
+const LEAN_CLAUDE = ["--tools", "Bash", "--strict-mcp-config", "--disable-slash-commands", "--setting-sources", ""];
 const whenOf = ({ every, at, atTime }, minimum) => {
     if ([every ?? at, atTime].filter(Boolean).length !== 1) {
         throw new CliError("validation_error", "say when: --every <30m|2h|1d>, --at HH:MM (daily), or --at-time <30m|2d|ISO time>");
@@ -76,12 +85,65 @@ 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 settings 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",
+    },
+    {
+        key: "schedule_model_claude",
+        default: AGENT_MODELS.claude,
+        description: "the model a new claude agent schedule runs on, unless --model names one; empty for claude's own default",
+    },
+    {
+        key: "schedule_model_codex",
+        default: AGENT_MODELS.codex,
+        description: "the model a new codex agent schedule runs on, unless --model names one; empty for codex's own default",
+    },
+    {
+        key: "schedule_lean_start",
+        default: true,
+        description: "a new claude agent schedule starts without your MCP servers, skills, settings and CLAUDE.md; false loads them",
+    },
+];
+/** `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;
+    const models = Object.fromEntries(HARNESSES.flatMap((harness) => {
+        const model = config[`schedule_model_${harness}`];
+        return typeof model === "string" && isModel(model.trim()) ? [[harness, model.trim()]] : [];
+    }));
+    return {
+        ...(Object.keys(models).length ? { models } : {}),
+        ...(typeof config.schedule_lean_start === "boolean" ? { leanStart: config.schedule_lean_start } : {}),
+        ...(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 shown = (argv) => argv.map((arg) => (arg === "" ? '""' : arg)).join(" ");
+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 = {}) => {
@@ -112,18 +174,50 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
             await timer().install(schedule, [...system.entry, "schedule", "exec", file]);
             say(scheduleAnswer(schedule, { file, timer: timer().where(schedule.name), replaced }), [
                 `${replaced ? "Replaced" : "Added"} ${schedule.name}: ${describeWhen(schedule.when)}.`,
-                `It runs: ${schedule.kind === "agent" ? schedule.argv.join(" ") : `${app.command} ${schedule.argv.join(" ")}`}`,
+                `It runs: ${schedule.kind === "agent" ? shown(schedule.argv) : `${app.command} ${shown(schedule.argv)}`}`,
                 `Output: ${join(dirname(file), "runs")} · now: ${lineOf(self, `schedule run ${schedule.name}`)} · stop: ${lineOf(self, `schedule remove ${schedule.name}`)}`,
             ]);
         };
         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,
@@ -153,17 +247,33 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
         examples: [
             `${app.command} personal schedule agent review claude "review what came in overnight and draft replies" --at 08:30`,
             `${app.command} personal schedule agent triage codex "list what needs an answer today" --every 2h --max-cost 1`,
+            `${app.command} personal schedule agent weekly claude "review the week's open threads" --at 09:00 --model opus`,
         ],
     }))
         .description(`start an agent (claude or codex) with a prompt on a timer; it runs with ${agentClis.map((one) => `${one.envPrefix}_READ_ONLY=1`).join(" and ")}, so it reads and drafts and cannot send — its answer is kept and you are notified`)
         .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) {
+        .option("--model <model>", `the model it runs on: an alias such as sonnet, or a model id; "" for the harness's default (default sonnet for claude, codex's own for codex, or the config file's)`)
+        .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);
+        if (options.model !== undefined && !isModel(options.model))
+            throw new CliError("validation_error", `--model takes an alias such as sonnet or a model id, not "${options.model}"`);
+        const settings = configured?.(this) ?? {};
+        const model = options.model ?? settings.models?.[harness] ?? AGENT_MODELS[harness];
+        const modelFlag = model ? ["--model", model] : [];
         const program = findProgram(harness, context.env, system.platform);
         if (!program)
             throw new CliError("not_found", `${harness} is not on PATH`);
@@ -182,6 +292,8 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
                 "--allowedTools",
                 ...agentClis.map((one) => `Bash(${one.command}:*)`),
                 "--no-session-persistence",
+                ...modelFlag,
+                ...((settings.leanStart ?? true) ? LEAN_CLAUDE : []),
                 ...(options.maxCost ? ["--max-budget-usd", String(options.maxCost)] : []),
             ]
             : [
@@ -194,6 +306,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentRuns
                 // The CLIs reach their provider and write the store and their own state, and nothing else.
                 "-c",
                 "sandbox_workspace_write.network_access=true",
+                ...modelFlag,
                 ...[dirname(storePath(context.env)), ...folders].flatMap((dir) => ["--add-dir", dir]),
                 prompt,
             ];
@@ -205,12 +318,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 +342,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 +355,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 +366,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 +382,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 +418,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");