@wirecat/cli-core 0.539.0 → 0.541.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ shape of this file.
 
 ## Unreleased
 
+## 0.541.0 — 02.11.2026
+
+### Added
+
+- **`MailServerAccess.timeMs`**: a mailbox's own default for the server search's time bound, for a server whose
+  search is slow; `--server-time` still wins. `MailReads.serverTimeDefault` puts it in the `--server-time` help.
+- **`EmailFilter.externalIds`**: only these Message-IDs, for `emails`, `emailRefs` and `emailFacts`.
+
+### Fixed
+
+- **`schedule exec` and `schedule run` wait for their child as long as the child's own deadline allows**, instead of
+  answering `timeout` (exit 9) at 30 s while the child went on: a scheduled sync of more than 30 s failed every time
+  and kept writing after the answer. A signal or an explicit `--timeout` now stops the child (SIGTERM, then SIGKILL
+  after 10 s), and its exit code is the run's.
+- **A mail sync no longer loads every stored email of the account in each round**: it asks the store about the mail
+  the round listed. On 260,000 stored emails and a 4,900-message window (`bench/mail-sync-scale`), from 17.7 s and
+  1.1 GB peak memory to 0.3 s and 190 MB.
+- **A mail sync that is stopped while a listing is in flight writes nothing for it**, and reading attachments stops
+  at the stop.
+- **The mail server search keeps parsing and attachment reading inside its time bound**, ends that bound before the
+  command's deadline so it answers in part instead of timing out, and stops writing once the command is stopped. A
+  find larger than 5 MB is left on the server unread, and the answer says so (`search.server-too-large`).
+
+## 0.540.0 — 02.11.2026
+
+### Added
+
+- **`events export` without `--output` is a read over MCP and under the read-only lock.** It only prints the `.ics`
+  text, and MCP tools never offer `--output`. `writesFileOnlyWith(command, option)` marks a command whose only local
+  write is the file an owner-only option names: its effects stay a write (WC-CMD-17), `readsOverMcp` / `readsOverMcpAt`
+  count it as a read, and `<PREFIX>_READ_ONLY` refuses only a run that gives the option. Every MCP server now judges
+  `read` with `readsOverMcpAt`, which is `fetchesOnly` plus these; a CLI test that snapshots the catalogue with
+  `fetchesOnlyAt` should switch to it.
+- **An MCP list's `query` input names its fields.** It said "the fields are below", and no Fields section is sent
+  over MCP. It now reads cli-base's `queryDescription`: the fields, enum values, and which fields `-field:value`
+  leaves out. `events list`'s query declares `event_type` as `negatable` (cli-base), and `negatableOf(registry)`
+  gives `nativeTermLists` the same list, so the description and the filter cannot drift. `queryArgument` uses the
+  same sentence.
+- **`events list` and `events prepare` give `meta.now`, `meta.now_local` and `meta.timezone` (WC-TIME-7)**, from the
+  host's clock and zone, so an agent plans "tomorrow" from the real date.
+
+### Changed — may break callers
+
+- **cli-base 0.72.0.** `metaSchema` accepts `now` and `now_local`; a host that checks meta against an older cli-base's
+  strict schema drops the whole meta.
+
 ## 0.539.0 — 01.11.2026
 
 ### Added

package/dist/background/schedules.d.ts

@@ -102,7 +102,9 @@ export declare const findProgram: (name: string, env: NodeJS.ProcessEnv, platfor
  * the last result in `last.json`. An agent runs under `<PREFIX>_READ_ONLY`, so nothing it is talked
  * into can send. A one-off removes itself afterwards.
  */
-export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer }?: {
+export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, }?: {
     now?: () => Date;
     timer?: Timer;
+    signal?: AbortSignal;
+    killAfterMs?: number;
 }) => Promise<LastRun>;

package/dist/background/schedules.js

@@ -326,12 +326,14 @@ export const findProgram = (name, env, platform) => {
     return undefined;
 };
 const KEEP_RUNS = 30;
+/** How long a stopped child has to save and answer after SIGTERM before it is killed. */
+const KILL_AFTER_MS = 10_000;
 /**
  * One run: the command or the agent with the schedule's variables, its output kept beside the schedule,
  * the last result in `last.json`. An agent runs under `<PREFIX>_READ_ONLY`, so nothing it is talked
  * into can send. A one-off removes itself afterwards.
  */
-export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer } = {}) => {
+export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, } = {}) => {
     const schedule = readSchedule(file);
     const folder = join(file, "..");
     const runs = join(folder, "runs");
@@ -369,11 +371,24 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
             err.push(Buffer.from(String(error)));
             resolve(127);
         });
-        child.on("close", (code) => {
+        // The child keeps its own deadline; a stop of this run stops the child too, so nothing it does outlives the run.
+        let kill;
+        const stop = () => {
+            child.kill("SIGTERM");
+            kill = setTimeout(() => child.kill("SIGKILL"), killAfterMs);
+        };
+        if (signal?.aborted)
+            stop();
+        else
+            signal?.addEventListener("abort", stop, { once: true });
+        child.on("close", (code, killedBy) => {
+            signal?.removeEventListener("abort", stop);
+            if (kill)
+                clearTimeout(kill);
             writeFileSync(output, Buffer.concat(agent ? out : [...out, ...err]), { mode: 0o600 });
             if (agent)
                 writeFileSync(errors, Buffer.concat(err), { mode: 0o600 });
-            resolve(code ?? 1);
+            resolve(code ?? (killedBy === "SIGKILL" ? 137 : killedBy === "SIGTERM" ? 143 : 1));
         });
     });
     const ended = now();

package/dist/calendar/cli/index.js

@@ -1,10 +1,11 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate, sharedCommand } from "@wirecat/cli-base/commands";
 import { timezoneOf } from "@wirecat/cli-base/query";
+import { clockMeta } from "@wirecat/cli-base/standards";
 import { Argument, InvalidArgumentError, Option } from "commander";
 import { environmentOf, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
-import { ownerOnlyOption } from "../../cli/effects.js";
+import { ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
 import { queryTerms, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
@@ -235,7 +236,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
         });
         print({
             ...eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }, opts.page), EVENT_ITEM_UNTRUSTED),
-            meta: await accountsMeta(deps.store, accounts, skipped, now()),
+            meta: { ...(await accountsMeta(deps.store, accounts, skipped, now())), ...clockMeta(now(), zone()) },
         }, command);
     });
     const exporter = example(withQuery(annotate(events.command("export"), { effects: deps.writeFile ? LOCAL_WRITE : LOCAL_READ }).description(`write stored events as iCalendar (.ics), at most ${EXPORT_MAX}: one with id:<id>, or those the query ` +
@@ -247,7 +248,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
         : ["events export id:42", "events export starts_at:[2026-11-02 TO 2026-11-09} NOT event_type:birthday"]));
     // Not over MCP: an agent would choose where on the owner's disk to write. It gets the text in the answer.
     if (deps.writeFile)
-        exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent"));
+        writesFileOnlyWith(exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent")), "output");
     exporter.action(async (words, opts, command) => {
         const filter = await eventsFilter(words, {
             store: deps.store,
@@ -297,7 +298,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
             ...(opts.limit === undefined ? {} : { limit: opts.limit }),
             ...(window.since === undefined ? {} : { since: window.since }),
         });
-        print({ ...prepared, meta: { ...meta, ...window.meta } }, command);
+        print({ ...prepared, meta: { ...meta, ...window.meta, ...clockMeta(now(), zone()) } }, command);
     });
     const searches = annotate(program.command("search").description("find stored things by text: events"), {
         effects: GROUP,

package/dist/calendar/mcp/index.js

@@ -30,7 +30,8 @@ export const calendarTools = [
         name: "events_list",
         description: "stored events, earliest first; `query` takes field terms joined by AND: starts_at (>=, <, or " +
             "[a TO b}), ends_at>=, changed_at>= (events new, moved or cancelled since, each with change and was), " +
-            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>; a date in the zone given, " +
+            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>, event_type:<kind>, and " +
+            "-event_type:<kind> to leave one kind out; a date in the zone given, " +
             "UTC when absent; without starts_at or ends_at, from today on",
         properties: {
             account_id: integer,

package/dist/calendar/prepare.d.ts

@@ -126,6 +126,8 @@ export declare const eventPreparation: (details: EventDetails, options: Preparat
         }[] | undefined;
         truncated?: boolean | undefined;
         timezone?: string | undefined;
+        now?: string | undefined;
+        now_local?: string | undefined;
         window?: {
             since?: string | undefined;
             until?: string | undefined;

package/dist/calendar/reads.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { dateRange, dayBoundary, queryError, queryFieldsOf, } from "@wirecat/cli-base/query";
-import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, typedQuery } from "../cli/list-query.js";
+import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, negatableOf, typedQuery, } from "../cli/list-query.js";
 import { event, eventChange, eventItem, listed, } from "../meetings/index.js";
 import { entriesOfList, fitting } from "../search/account-list.js";
 import { listContextOf } from "../services/search-kind.js";
@@ -92,6 +92,7 @@ export const EVENTS_QUERY = {
     backend: "native",
     fields: queryFieldsOf(event, {
         native: ["id", "starts_at", "ends_at", "changed_at", "overlapping", "calendar", "person", "event_type"],
+        negatable: ["event_type"],
         relations: {
             event_type: {
                 type: "enum",
@@ -156,7 +157,7 @@ export const eventsFilter = async (query, context) => {
     const { zone, now } = context;
     const span = (text) => ({ start: 0, end: text.length });
     const day = (date) => dayBoundary(date, zone, false, span(date));
-    const terms = nativeTermLists(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST, [], ["event_type"]);
+    const terms = nativeTermLists(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST, [], negatableOf(EVENTS_QUERY));
     const kinds = (nodes = []) => nodes.map(({ value }) => value.toLowerCase());
     const excluded = kinds(terms.get("-event_type"));
     if (excluded.length)

package/dist/cli/bot/mcp.js

@@ -3,7 +3,7 @@ import { CliError } from "@wirecat/cli-base";
 import { annotate, describeProgram } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { environmentOf } from "../context.js";
-import { changesAuthorityAt, fetchesOnlyAt, LOCAL_READ, REMOTE_WRITE } from "../effects.js";
+import { changesAuthorityAt, LOCAL_READ, REMOTE_WRITE, readsOverMcpAt } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
 import { serverEntry } from "../messenger/mcp-command.js";
 import { nextStep, rootOf } from "../steps.js";
@@ -37,7 +37,7 @@ export const botMcpCommand = (bot) => {
             bot,
             program: { run, commands: describeProgram(rootOf(this)) },
             authority: changesAuthorityAt(rootOf(this)),
-            fetchOnly: fetchesOnlyAt(rootOf(this)),
+            fetchOnly: readsOverMcpAt(rootOf(this)),
             settings: context.settings,
             levels: () => bot.resolveSettings(this.optsWithGlobals(), { env: context.env, kind: "bot" }).permissions,
             env: context.env,

package/dist/cli/effects.d.ts

@@ -50,6 +50,20 @@ export declare const changesStore: <T extends Command>(command: T) => T;
 export declare const fetchesOnly: (command: Command) => boolean;
 /** `fetchesOnly` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
 export declare const fetchesOnlyAt: (root: Command) => (path: readonly string[]) => boolean;
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export declare const writesFileOnlyWith: <T extends Command>(command: T, option: string) => T;
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export declare const readsOverMcp: (command: Command) => boolean;
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export declare const readsOverMcpAt: (root: Command) => (path: readonly string[]) => boolean;
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)

package/dist/cli/effects.js

@@ -1,4 +1,4 @@
-import { annotate, annotateOption, metaOf, stepTargets } from "@wirecat/cli-base/commands";
+import { annotate, annotateOption, metaOf, optionMetaOf, stepTargets, } from "@wirecat/cli-base/commands";
 import { Option } from "commander";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { keyForCommand } from "../sends/permissions.js";
@@ -93,6 +93,36 @@ export const fetchesOnlyAt = (root) => (path) => {
         at = at?.commands.find((one) => one.name() === word);
     return at !== undefined && fetchesOnly(at);
 };
+const FILE_OPTION = new WeakMap();
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export const writesFileOnlyWith = (command, option) => {
+    const flag = command.options.find((one) => one.attributeName() === option);
+    if (!flag || optionMetaOf(flag).mcp !== false)
+        throw new Error(`${command.name()}: writesFileOnlyWith needs --${option} added first, as an owner-only option`);
+    FILE_OPTION.set(command, option);
+    return command;
+};
+const writesFileNow = (command) => {
+    const option = FILE_OPTION.get(command);
+    return option === undefined || command.opts()[option] !== undefined;
+};
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export const readsOverMcp = (command) => fetchesOnly(command) || FILE_OPTION.has(command);
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export const readsOverMcpAt = (root) => (path) => {
+    let at = root;
+    for (const word of path)
+        at = at?.commands.find((one) => one.name() === word);
+    return at !== undefined && readsOverMcp(at);
+};
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)
@@ -103,7 +133,8 @@ export const isStoreChange = (command) => {
     return ((effects?.remote === "none" || STORE_WRITES.has(command)) &&
         effects?.local === "write" &&
         !KEPT_UNDER_LOCK.has(command) &&
-        !changesAuthority(command));
+        !changesAuthority(command) &&
+        writesFileNow(command));
 };
 export const STORE_CHANGE_REFUSAL = "change the message store";
 /** ` --dry-run` where the program has it, so an example of a command that calls a provider calls nothing. */

package/dist/cli/envelope.d.ts

@@ -95,6 +95,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
@@ -148,6 +150,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;

package/dist/cli/index.d.ts

@@ -66,7 +66,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { type CliEntry, type EntryContext, type EntryIo, 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";
@@ -78,7 +78,7 @@ export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIREC
 export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 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";

package/dist/cli/index.js

@@ -58,7 +58,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { 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";
@@ -70,7 +70,7 @@ export { firstScreen, installHelp, WIRECAT_TOOLS } from "./help/first-screen.js"
 export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 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";

package/dist/cli/list-query.d.ts

@@ -4,6 +4,8 @@ import * as v from "valibot";
 import { type ListBody, type ListInput } from "./envelope.js";
 import type { Settings } from "./settings.js";
 export declare const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export declare const QUERY_ARGUMENT = "field:value terms that narrow the list \u2014 the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -31,7 +33,9 @@ export declare const pageOf: ({ limit, page, all }: Pick<Settings, "limit" | "pa
 /** A page-numbered list's answer; under `--all` its limit is what it holds. */
 export declare const pagedList: <T>(command: string, { limit, page, all }: Pick<Settings, "limit" | "page" | "all">, { items, has_more, ...rest }: Omit<ListInput<T>, "limit" | "page" | "cursor">) => ListBody<T>;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, "field:value terms; this list filters by none yet, so any term is refused" | `field:value terms joined by AND that narrow the list; fields: ${string}; e.g. ${string}` | `field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <); fields: ${string}; e.g. ${string}`>]>, undefined>;
+export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, string>]>, undefined>;
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export declare const negatableOf: (registry: QueryRegistry) => string[];
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.

package/dist/cli/list-query.js

@@ -1,9 +1,11 @@
 import { annotate } from "@wirecat/cli-base/commands";
-import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
+import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryDescription, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
 import * as v from "valibot";
 import { queryWordsAfterOptions } from "../meetings/cli/index.js";
 import { listOf } from "./envelope.js";
 export const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export const QUERY_ARGUMENT = "field:value terms that narrow the list — the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -12,9 +14,7 @@ export const withQuery = (command, registry) => {
     const query = defineQuery(registry);
     annotate(command, { query, output: { entity: registry.entity } });
     const shown = askable(query);
-    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0
-        ? "field:value terms that narrow the list — the fields are below"
-        : "field:value terms; this list filters by none yet");
+    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0 ? QUERY_ARGUMENT : "field:value terms; this list filters by none yet");
     if (shown.length > 0)
         command.addHelpText("after", `\n${fieldsHelp({ ...query, fields: shown }, LIST_QUERY_GUIDE)}`);
     return command;
@@ -97,14 +97,11 @@ export const pagedList = (command, { limit, page, all }, { items, has_more, ...r
 /** The fields a list can be narrowed by: a provider list only those its source answers. */
 const askable = (registry) => registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export const queryArgument = (registry) => {
-    const fields = askable(registry);
-    return v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(fields.length === 0
-        ? "field:value terms; this list filters by none yet, so any term is refused"
-        : `${registry.backend === "native"
-            ? "field:value terms joined by AND that narrow the list"
-            : "field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <)"}; fields: ${fields.map((field) => field.name).join(", ")}; e.g. ${fields[0]?.example ?? ""}`)));
-};
+export const queryArgument = (registry) => v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(queryDescription(registry))));
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export const negatableOf = (registry) => askable(registry)
+    .filter((field) => field.negatable)
+    .map((field) => field.name);
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.

package/dist/cli/messenger/search-backend-options.d.ts

@@ -2,7 +2,7 @@ import type { Command } from "commander";
 import type { Backend, ServerOptions, ServerSearched } from "../../services/server-search.js";
 import type { Messenger, MessengerContext } from "./context.js";
 /** `--backend` and `--server-time`, for any search whose source has a server that searches: `where` names it. */
-export declare const serverSearchOptions: (command: Command, where: string) => Command;
+export declare const serverSearchOptions: (command: Command, where: string, defaultTime?: string) => Command;
 /** Mounted only where the messenger's server can search messages. */
 export declare const backendOptions: (command: Command, messenger: Messenger) => Command;
 export declare const backendRequest: (command: Command) => {

package/dist/cli/messenger/search-backend-options.js

@@ -6,9 +6,9 @@ const backendOf = (value) => {
     return value;
 };
 /** `--backend` and `--server-time`, for any search whose source has a server that searches: `where` names it. */
-export const serverSearchOptions = (command, where) => command
+export const serverSearchOptions = (command, where, defaultTime = "5s") => command
     .option("--backend <archive|server|both>", `where to search: the local archive, ${where}, or both`, backendOf)
-    .option("--server-time <duration>", "stop waiting for the server after this long (default: 5s)");
+    .option("--server-time <duration>", `stop waiting for the server after this long (default: ${defaultTime})`);
 /** Mounted only where the messenger's server can search messages. */
 export const backendOptions = (command, messenger) => messenger.serverSearch
     ? serverSearchOptions(command, "the messenger's server (default: both; message discovery uses archive only)")

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

@@ -45,6 +45,19 @@ const whenOf = ({ every, at, atTime }, minimum) => {
     return { every: minutes };
 };
 /** A schedule as answered: snake_case, but its environment keeps the variables' own names. */
+/**
+ * A run waits for its child, which keeps its own deadline (a sync's is 15 minutes): the wait has none of its own, or the
+ * run answered `timeout` at 30 s while the child went on. A signal or an explicit --timeout stops the child.
+ */
+const untilChildEnds = async (command, wait) => {
+    const environment = environmentOf(command);
+    try {
+        return await wait(environment.untilStopped?.());
+    }
+    finally {
+        environment.endUntilStopped?.();
+    }
+};
 const scheduleAnswer = ({ environment, createdAt, ...schedule }, extra) => ({
     ...snakeKeys(schedule),
     environment,
@@ -222,9 +235,10 @@ export const scheduleCommandFor = ({ app, context: contextOf }) => {
         .argument("<name>", "the schedule's name, as `schedule list` shows it")
         .action(async function (name) {
         const { context, system, state, say, timer } = prepare(this);
-        const last = await runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
+        const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
             timer: timer(),
-        });
+            ...(signal ? { signal } : {}),
+        }));
         say(snakeKeys({ name, ...last }), [`${name}: exit ${last.exitCode} — ${last.output}`]);
         if (last.exitCode !== 0)
             setExitCode(this, 1);
@@ -253,7 +267,7 @@ export const scheduleCommandFor = ({ app, context: contextOf }) => {
         .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 });
-        const last = await runSchedule(app, system, context.env, file, { timer: timer() });
+        const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, file, { timer: timer(), ...(signal ? { signal } : {}) }));
         if (last.exitCode !== 0)
             setExitCode(this, 1);
     });

package/dist/errors/reasons.js

@@ -89,6 +89,7 @@ const OTHERS = [
     ["search.server-failed", "provider_unavailable", "the server did not answer a search"],
     ["search.server-timeout", "timeout", "the server did not answer within --server-time"],
     ["search.server-capped", "outcome_unknown", "the server found more than one search reads, or a branch was not sent"],
+    ["search.server-too-large", "outcome_unknown", "a message the server found is too large to download during a search"],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
     [

package/dist/mail/attachments.d.ts

@@ -8,8 +8,9 @@ export declare const FETCH_CHUNK = 50;
 export declare const addressOf: ({ email, name }: Address) => EmailAddress;
 export type AttachmentLog = NonNullable<MailSyncResult["attachments"]>;
 /** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
-export declare const readAttachments: (mail: ParsedMail, messageId: string, { loadEngine, maxAttachmentChars, at }: {
+export declare const readAttachments: (mail: ParsedMail, messageId: string, { loadEngine, maxAttachmentChars, at, signal, }: {
     loadEngine: LoadEngine;
     maxAttachmentChars: number;
     at: number;
+    signal?: AbortSignal;
 }, log: AttachmentLog) => Promise<AttachmentInput[]>;

package/dist/mail/attachments.js

@@ -4,12 +4,14 @@ export const MAX_ATTACHMENT_CHARS = 200_000;
 export const FETCH_CHUNK = 50;
 export const addressOf = ({ email, name }) => ({ address: email, name });
 /** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
-export const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at }, log) => {
+export const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at, signal, }, log) => {
     const files = [];
     for (const [position, part] of mail.attachments.entries()) {
+        if (signal?.aborted)
+            throw signal.reason;
         const extraction = part.bytes === null
             ? { status: "unavailable" }
-            : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine);
+            : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine, signal);
         log.push({ message: messageId, part: part.id, status: extraction.status });
         const extracted = extraction.status === "extracted" ? extraction : undefined;
         files.push({

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

@@ -12,6 +12,8 @@ export interface MailReads {
     read: <T>(command: Command, work: (store: MessageStore, mailbox: AccountKey) => Promise<T>) => Promise<T>;
     /** The mailbox's server, for `search messages --backend`; without it the search reads the store only. */
     server?: (command: Command) => MailServerAccess;
+    /** How `--server-time` help states its default when a provider's own differs (`MailServerAccess.timeMs`). */
+    serverTimeDefault?: string;
 }
 export declare const THREAD_QUERY: {
     readonly entity: "mail_thread";

package/dist/mail/cli/index.js

@@ -4,7 +4,7 @@ import { queryFieldsOf } from "@wirecat/cli-base/query";
 import { Command, InvalidArgumentError } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
-import { outputFor } from "../../cli/context.js";
+import { environmentOf, outputFor } from "../../cli/context.js";
 import { LOCAL_READ, REMOTE_READ } from "../../cli/effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
 import { listQuery, typedQuery, withQuery } from "../../cli/list-query.js";
@@ -74,8 +74,11 @@ const serverIssues = (server) => {
         ...FAILED[reason],
         source: "server",
     }));
-    return failed.length
-        ? failed
+    const tooLarge = server.tooLarge
+        ? [{ code: "outcome_unknown", reason: "search.server-too-large", source: "server" }]
+        : [];
+    return failed.length || tooLarge.length
+        ? [...failed, ...tooLarge]
         : [{ code: "outcome_unknown", reason: "search.server-capped", source: "server" }];
 };
 const searchCommand = (mail) => {
@@ -114,19 +117,23 @@ found_in says archive, server (new from the server) or both; meta.complete is fa
         : ""}
 Search guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md`);
     if (mail.server)
-        serverSearchOptions(leaf, "the mail server (default: both)");
+        serverSearchOptions(leaf, "the mail server (default: both)", mail.serverTimeDefault);
     leaf.action(async function (words) {
         const options = this.opts();
         const limit = options.limit ?? DEFAULT_LIMIT;
         const page = options.page ?? 1;
         const query = words.join(" ");
         const { backend, server: bounds } = mail.server ? backendRequest(this) : {};
+        const { signal, deadline: deadlineOf } = environmentOf(this);
+        const deadline = deadlineOf?.();
         const found = await mail.read(this, async (store, mailbox) => {
             const step = mail.server
                 ? await searchMailServer(store, mailbox, mail.server(this), {
                     text: query,
                     ...(backend === undefined ? {} : { backend }),
                     ...(bounds?.timeMs === undefined ? {} : { timeMs: bounds.timeMs }),
+                    ...(signal ? { signal } : {}),
+                    ...(deadline ? { deadline } : {}),
                     ...(options.exact ? { exact: true } : {}),
                     ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
                 })

package/dist/mail/server-search.d.ts

@@ -1,3 +1,4 @@
+import { type Deadline } from "../background/budget.js";
 import { type Level, type PermissionKey } from "../sends/permissions.js";
 import { type Backend, type ServerStep } from "../services/server-search.js";
 import type { AccountKey, MessageStore } from "../store/index.js";
@@ -15,6 +16,8 @@ export interface MailServerAccess {
         folders: string[];
         close?: () => Promise<void>;
     }>;
+    /** This mailbox's own default for the time bound, for a server whose search is slow; `--server-time` wins. */
+    timeMs?: number;
 }
 export interface MailServerRequest {
     text: string;
@@ -23,6 +26,8 @@ export interface MailServerRequest {
     backend?: Backend;
     timeMs?: number;
     signal?: AbortSignal;
+    /** The command's deadline: the time bound ends before it, so the search answers in part instead of timing out. */
+    deadline?: Deadline;
 }
 /**
  * Asks the mailbox's server for candidates and saves the new ones, so the strict query that runs next on the store

package/dist/mail/server-search.js

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { importEngine } from "../attachments/extract.js";
+import { deadlineMargin } from "../background/budget.js";
 import { levelFor } from "../sends/permissions.js";
 import { DEFAULT_BACKEND, SERVER_BOUNDS, SERVER_SEARCH_KEY, sourceKey, } from "../services/server-search.js";
 import { MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
@@ -38,9 +39,13 @@ export const searchMailServer = async (store, mailbox, access, request) => {
     if (backend === "archive")
         return undefined;
     const quiet = request.backend === undefined;
-    const timeMs = request.timeMs ?? SERVER_BOUNDS.timeMs;
-    if (!Number.isSafeInteger(timeMs) || timeMs < 1 || timeMs > 60_000)
+    const asked = request.timeMs ?? access.timeMs ?? SERVER_BOUNDS.timeMs;
+    if (!Number.isSafeInteger(asked) || asked < 1 || asked > 60_000)
         throw new CliError("validation_error", "the server time takes a whole number of milliseconds from 1 to 60000");
+    const { deadline } = request;
+    const timeMs = deadline
+        ? Math.max(1, Math.min(asked, deadline.endsAt - Date.now() - deadlineMargin(deadline)))
+        : asked;
     const report = { backend, skipped: null, calls: 0, returned: 0, new: 0, failed: [], complete: true };
     const sources = new Map();
     const skip = (reason) => {
@@ -77,10 +82,13 @@ export const searchMailServer = async (store, mailbox, access, request) => {
     const fresh = [];
     let rules = [];
     const ruled = new Map();
-    let raws;
+    const inputs = [];
+    const saved = [];
     let opening;
     let openFailure;
     let unsupported = false;
+    const controller = new AbortController();
+    const stop = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
     // Opening lists the folders, a call to the server, so it runs inside the time bound too.
     const run = async () => {
         opening = access.open();
@@ -138,15 +146,63 @@ export const searchMailServer = async (store, mailbox, access, request) => {
             sources.set(sourceKey(item.threadId, item.messageId), held ? "both" : "server");
             if (held)
                 continue;
+            // A big message would hold the connection and the parser past the bound; sync reads it whole later.
+            if ((item.size ?? 0) > SERVER_BOUNDS.maxMessageBytes) {
+                report.tooLarge = (report.tooLarge ?? 0) + 1;
+                report.complete = false;
+                sources.delete(sourceKey(item.threadId, item.messageId));
+                continue;
+            }
             fresh.push(item);
             ruled.set(item, { ruleId: rule?.id ?? null, tags: tagsOf(rules, facts(item)) });
         }
-        if (fresh.length)
-            raws = await source.fetchRaw(fresh);
+        const raws = fresh.length && open ? await source.fetchRaw(fresh) : [];
+        // Parsing and reading attachments stay inside the bound: after it, nothing more is read or kept.
+        const now = Date.now();
+        for (const [index, item] of fresh.entries()) {
+            if (!open)
+                return;
+            const raw = raws[index];
+            try {
+                if (raw === undefined || raw instanceof Error)
+                    throw raw ?? new Error("not read");
+                const mail = await parseMail(raw);
+                const files = await readAttachments(mail, item.messageId, { loadEngine: importEngine, maxAttachmentChars: MAX_ATTACHMENT_CHARS, at: now, signal: stop }, []);
+                if (!open)
+                    return;
+                const folder = item.folder;
+                const validity = validities.get(item);
+                inputs.push({
+                    accountId,
+                    externalId: item.threadId,
+                    now,
+                    emails: [
+                        {
+                            ...parsedEmail(mail, item, mailHeadersOf(raw), mailbox.account),
+                            mailboxes: [
+                                { externalId: folder, name: folder, kind: null },
+                                ...(item.labels ?? []).map((name) => ({ externalId: `label:${name}`, name, kind: "label" })),
+                                ...(item.headers?.bulk ? [bulkBox] : []),
+                            ],
+                            ...(validity === undefined
+                                ? {}
+                                : { locations: [{ folder, uidvalidity: validity, uid: Number(item.uid) }] }),
+                            ...(item.seen === undefined ? {} : { read: item.seen }),
+                            ...(item.flagged === undefined ? {} : { flagged: item.flagged }),
+                            mailRuleId: ruled.get(item)?.ruleId ?? null,
+                            attachments: files,
+                        },
+                    ],
+                });
+                saved.push(item);
+            }
+            catch {
+                sources.delete(sourceKey(item.threadId, item.messageId));
+                report.complete = false;
+            }
+        }
     };
-    const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeMs);
-    const stop = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
     const bound = new Promise((resolve) => {
         if (stop.aborted)
             resolve(BOUND);
@@ -169,56 +225,18 @@ export const searchMailServer = async (store, mailbox, access, request) => {
     const ended = outcome === BOUND || outcome === "done" ? "time_or_abort_bound" : outcome;
     for (const call of pending)
         fail(call, ended);
-    if (outcome !== "done" || (fresh.length > 0 && raws === undefined)) {
+    if (outcome !== "done") {
         // What was found but not read in time is the archive's to answer: none of it is claimed as the server's.
         if (pending.size === 0)
             fail(null, ended);
+        const kept = new Set(saved);
         for (const item of fresh)
-            sources.delete(sourceKey(item.threadId, item.messageId));
-        report.returned = sources.size;
-        return { report, sources };
-    }
-    const now = Date.now();
-    const inputs = [];
-    const saved = [];
-    for (const [index, item] of fresh.entries()) {
-        const raw = raws?.[index];
-        try {
-            if (raw === undefined || raw instanceof Error)
-                throw raw ?? new Error("not read");
-            const mail = await parseMail(raw);
-            const files = await readAttachments(mail, item.messageId, { loadEngine: importEngine, maxAttachmentChars: MAX_ATTACHMENT_CHARS, at: now }, []);
-            const folder = item.folder;
-            const validity = validities.get(item);
-            inputs.push({
-                accountId,
-                externalId: item.threadId,
-                now,
-                emails: [
-                    {
-                        ...parsedEmail(mail, item, mailHeadersOf(raw), mailbox.account),
-                        mailboxes: [
-                            { externalId: folder, name: folder, kind: null },
-                            ...(item.labels ?? []).map((name) => ({ externalId: `label:${name}`, name, kind: "label" })),
-                            ...(item.headers?.bulk ? [bulkBox] : []),
-                        ],
-                        ...(validity === undefined
-                            ? {}
-                            : { locations: [{ folder, uidvalidity: validity, uid: Number(item.uid) }] }),
-                        ...(item.seen === undefined ? {} : { read: item.seen }),
-                        ...(item.flagged === undefined ? {} : { flagged: item.flagged }),
-                        mailRuleId: ruled.get(item)?.ruleId ?? null,
-                        attachments: files,
-                    },
-                ],
-            });
-            saved.push(item);
-        }
-        catch {
-            sources.delete(sourceKey(item.threadId, item.messageId));
-            report.complete = false;
-        }
+            if (!kept.has(item))
+                sources.delete(sourceKey(item.threadId, item.messageId));
     }
+    // The command's own deadline or a cancel ended it: its runner has answered, so nothing more is written.
+    if (request.signal?.aborted)
+        throw request.signal.reason;
     if (inputs.length)
         await store.mail.saveThreads(inputs);
     // Sync never reads mail whose place it knows again, so a rule's tags go on here or never.

package/dist/mail/sync.js

@@ -195,13 +195,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     /** A quick folder's stored mail as it was before this run changed anything, with the UID of each. */
     const folderMail = new Map();
     const refreshed = new Map();
-    let holding;
-    const holdsMail = async (folder) => {
-        holding ??= new Set((await store.mail.emailRefs({ accountId })).flatMap(({ mailboxes }) => mailboxes
-            .filter(({ kind }) => kind !== "label" && kind !== ENVELOPE && kind !== BULK)
-            .map((box) => box.externalId)));
-        return holding.has(folder);
-    };
+    const holdsMail = async (folder) => (await store.mail.emails({ accountId, mailbox: folder, limit: 1 })).length > 0;
     for (const folder of folders) {
         if (mboxPoint !== undefined)
             break;
@@ -339,6 +333,9 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         for (const item of found)
             collected.push(item);
     }
+    // A listing that came back after the stop writes nothing: the command has answered, and the next run lists again.
+    if (signal?.aborted)
+        throw signal.reason;
     const listed = [...new Map(collected.map((item) => [item.messageId, item])).values()].sort((a, b) => b.receivedAt.localeCompare(a.receivedAt));
     const present = new Set(listed.map(({ messageId }) => messageId));
     const factsFor = factsOf(listed, rules, ages);
@@ -449,7 +446,11 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     const pending = [];
     // IMAP lists what exists now, so a mail marked deleted that it lists again is saved again, which brings it back.
     // An archive is old: what it holds that IMAP proved deleted stays deleted.
-    const refs = await store.mail.emailRefs({ accountId, includeDeleted: snapshot });
+    const refs = await store.mail.emailRefs({
+        accountId,
+        includeDeleted: snapshot,
+        externalIds: listed.map(({ messageId }) => messageId),
+    });
     const known = new Set(refs.map(({ externalId }) => externalId));
     const enveloped = new Map(refs.flatMap(({ externalId, mailboxes }) => {
         const boxes = mailboxes.filter(({ kind }) => kind === ENVELOPE).map((box) => box.externalId);
@@ -712,7 +713,11 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
             }
             plan?.unreadable.delete(item.messageId);
             const header = mailHeadersOf(raws[index]);
-            const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt }, attachments);
+            // A stop between attachments ends the chunk; what the earlier slices saved stays.
+            const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt, ...(signal ? { signal } : {}) }, attachments).catch(async (error) => {
+                await stopIfAborted();
+                throw error;
+            });
             const input = {
                 accountId,
                 externalId: item.threadId,

package/dist/mcp/agent.js

@@ -1,11 +1,13 @@
 import { Readable } from "node:stream";
 import { CliError, captureStreams, errorObjectOf } from "@wirecat/cli-base";
 import { flatten, } from "@wirecat/cli-base/commands";
+import { queryDescription } from "@wirecat/cli-base/query";
 import { writes } from "@wirecat/cli-base/standards";
 import { VOCABULARY } from "@wirecat/cli-base/standards/tables";
 import * as v from "valibot";
 import { commandAvailability } from "../cli/command-availability.js";
 import { changesMessenger } from "../cli/effects.js";
+import { QUERY_ARGUMENT } from "../cli/list-query.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
 import { newRunId } from "../runs/run.js";
 import { enclosingTraceId, inRun, traceOf } from "../runs/scope.js";
@@ -78,10 +80,17 @@ const optionField = (option, long, negated) => {
         },
     };
 };
-const argumentField = (argument) => {
+/** A list's query names its fields here: the help's Fields section, which its description points to, is not sent. */
+const argumentField = (argument, query) => {
+    const own = argument.description || argument.name;
+    const about = query && argument.name === "query"
+        ? own === QUERY_ARGUMENT
+            ? queryDescription(query)
+            : `${own}; ${queryDescription(query)}`
+        : own;
     const one = argument.choices
         ? v.pipe(v.picklist(argument.choices), v.description(argument.description))
-        : text(argument.description || argument.name);
+        : text(about);
     return {
         name: snake(argument.name),
         required: argument.required,
@@ -109,7 +118,7 @@ const stdinField = ({ name, description, json }) => ({
     argv: () => [],
 });
 const fieldsOf = (info, { omit = [], offline = false, stdin }) => {
-    const fields = info.arguments.map(argumentField);
+    const fields = info.arguments.map((argument) => argumentField(argument, info.query));
     const read = stdin?.(info.path);
     if (read)
         fields.push(stdinField(read));

package/dist/mcp/app-server.js

@@ -4,7 +4,7 @@ import { CliError, mcpErrorResult } from "@wirecat/cli-base";
 import { describeProgram } from "@wirecat/cli-base/commands";
 import { skillResource } from "@wirecat/cli-base/skill";
 import { environmentOf } from "../cli/context.js";
-import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, judgedTargets, readsOverMcpAt } from "../cli/effects.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { rootOf } from "../cli/steps.js";
 import { mcpUrlOf } from "../http/public-url.js";
@@ -46,7 +46,7 @@ export const createAppServer = (command, context, options) => {
         currentLevels: levels,
         readOnly: readOnly(),
         authority,
-        fetchOnly: fetchesOnlyAt(root),
+        fetchOnly: readsOverMcpAt(root),
         permissions: options.permissions,
     });
     const availability = (one) => () => {

package/dist/mcp/server.js

@@ -8,7 +8,7 @@ import * as v from "valibot";
 import { findCommand } from "../cli/command-contract.js";
 import { environmentOf } from "../cli/context.js";
 import { refuseWriteBeforeConnecting } from "../cli/early-refusal.js";
-import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, judgedTargets, readsOverMcpAt } from "../cli/effects.js";
 import { itemOf } from "../cli/envelope.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { recalledAccount } from "../cli/messenger/accounts.js";
@@ -127,7 +127,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         readOnly: readOnlyLockOf(app, context.env) !== undefined,
         keyOf,
         authority,
-        fetchOnly: fetchesOnlyAt(root),
+        fetchOnly: readsOverMcpAt(root),
         offline: true,
         stdin,
     }).map((one) => "sync_first" in one.input.entries && !syncAllowed(one.path)

package/dist/services/server-search.d.ts

@@ -2,10 +2,12 @@ import type { Id } from "../domain/models.js";
 import type { ServiceDeps } from "./deps.js";
 import type { SearchQuery } from "./messages.js";
 export declare const SERVER_SEARCH_KEY = "messages.server-search";
+/** `maxMessageBytes`: a candidate larger than this is not downloaded; a sync reads it, and the answer says so. */
 export declare const SERVER_BOUNDS: {
     timeMs: number;
     perCall: number;
     maxCalls: number;
+    maxMessageBytes: number;
 };
 export declare const DEFAULT_BACKEND = "both";
 export type Backend = "archive" | "server" | "both";
@@ -24,6 +26,8 @@ export interface ServerSearched {
         chat: string | null;
         reason: "rate_limited" | "search_failed" | "time_or_abort_bound";
     }[];
+    /** Candidates larger than `SERVER_BOUNDS.maxMessageBytes`, left on the server unread. */
+    tooLarge?: number;
     complete: boolean;
 }
 export type HitSource = "archive" | "server" | "both";

package/dist/services/server-search.js

@@ -2,7 +2,8 @@ import { CliError } from "@wirecat/cli-base";
 import { capability } from "../ports/messenger.js";
 import { prepareLucene } from "./messages-search.js";
 export const SERVER_SEARCH_KEY = "messages.server-search";
-export const SERVER_BOUNDS = { timeMs: 5_000, perCall: 100, maxCalls: 3 };
+/** `maxMessageBytes`: a candidate larger than this is not downloaded; a sync reads it, and the answer says so. */
+export const SERVER_BOUNDS = { timeMs: 5_000, perCall: 100, maxCalls: 3, maxMessageBytes: 5_000_000 };
 export const DEFAULT_BACKEND = "both";
 export const sourceKey = (chatId, id) => JSON.stringify([chatId, id]);
 const merge = (one, other) => {

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

@@ -161,6 +161,8 @@ export interface EmailFilter extends MailFilter {
     until?: number;
     /** Only emails with an attachment whose text extraction failed with one of these errors. */
     attachmentErrors?: string[];
+    /** Only these Message-IDs: a sync asks about what it listed, not about the whole account. */
+    externalIds?: readonly string[];
 }
 export interface EmailRef {
     externalId: string;

package/dist/store/sqlite/emails.js

@@ -313,6 +313,8 @@ const emailWhere = (filter) => {
     if (filter.attachmentErrors !== undefined)
         add(`e.id IN (SELECT attachable_id FROM attachments WHERE attachable_type = 'email'
          AND extraction_error IN (${filter.attachmentErrors.map(() => "?").join(",") || "NULL"}))`, ...filter.attachmentErrors);
+    if (filter.externalIds !== undefined)
+        add("e.external_id IN (SELECT value FROM json_each(?))", JSON.stringify(filter.externalIds));
     return [where.join(" AND "), params];
 };
 /** An email as a message of its thread, the shape mail had when it was stored as messages. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.539.0",
+  "version": "0.541.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",
@@ -251,7 +251,7 @@
     "@types/node": "^22.20.5",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "@wirecat/cli-base": "0.71.0",
+    "@wirecat/cli-base": "0.72.0",
     "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
     "commander": "15.0.0",
     "cspell": "10.4.0",
@@ -271,7 +271,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.71.0 <0.72.0",
+    "@wirecat/cli-base": ">=0.72.0 <0.73.0",
     "commander": ">=15"
   },
   "bin": {