@wirecat/cli-core 0.540.0 → 0.541.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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

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/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/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.540.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",