@wirecat/cli-core 0.506.0 → 0.508.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ shape of this file.
 
 ## Unreleased
 
+## 0.508.0 — 31.10.2026
+
+### Added
+
+- **`events list --page <n>`: the next page of stored events.** `events list` said `hasMore` and had no way to read on;
+  it now takes `--page` from 1 with `--limit` events a page (100), and the answer's `page` is the number shown, so a
+  host's `listOf` can offer `page.next` (WC-OUT-5). `eventsAnswer` takes the page as a third argument.
+- **`search events --backend both`** asks the store and the provider's own search together, where `--backend` is
+  offered (`deps.serverSearch`). The stored hits come first in the stored search's order, `found_by` gaining
+  `server` on each the provider also found; then the hits only the provider found, earliest first. One page, with no
+  `next_offset`; `has_more` when either side has more. It refuses `--offline`, `--cursor` and `--newest` as
+  `--backend server` does, and takes `--exact` for the stored side. `calendar_search_hit` allows `server` in a stored
+  hit's `found_by`. An occurrence the store keeps under another id than the provider's search names shows twice.
+
+### Changed — may break callers
+
+- **`events create --id` and `events update --following --id` are now `--operation-id`** (WC-CMD-10, WC-OUT-10): the
+  value is the `operation_id` the answer and an `outcome_unknown` already name. `--id` is refused as an unknown
+  option; errors name `--operation-id`. The calendar MCP tools keep their `id` argument.
+- **`search events` no longer refuses `--backend both`** with `search.one-backend`; see Added.
+
+### Fixed
+
+- **`search events --cursor` help** said "a page's next_offset", a key the answer a host prints does not have; it now
+  says to go on from where the last page stopped, as `page.next` gives it.
+
+- **A budgeted `syncMail` waits out a locked store.** When another process (memo's scheduled sync) holds the store's
+  write lock past its 5 s busy timeout, the sync used to fail with `database is locked`; it now waits 2 s, 4 s, ... (at
+  most 5 times, each a request of the budget) and reads the round again. When the budget has no room the run ends as
+  `partial`. `options.wait` lets a test skip the pause.
+- **A bot token, a bot's named secret or an AI provider's key the owner sets again goes back to the keyring.** After
+  one keyring failure such a secret stayed in the private file for good, as cli-base 0.68.0 keeps a plain write where
+  the secret is. `BotTokenStore.write`, `writeSecret` and `embeddingKeys().write` now write with `{ signIn: true }`:
+  the keyring is tried and, once it takes the secret, the file copy is removed (WC-SECR-4). `writeKeyring` was
+  keyring-only already; the CAS key is only read here.
+
+## 0.507.0 — 31.10.2026
+
+### Added
+
+- **`messages sync --json` prints its progress on stderr**, for a window to draw a bar instead of an endless one
+  (WireCat Desktop). One JSON line each, counts only — never a chat's id or title:
+  `{"event":"progress","step":"sync","chats":3,"chats_done":1,"fetched":250}`. With `--all`, one once the chat list
+  is read (`chats_done` 0), then one after each chat, those passed as already current included; for one chat, one per
+  page with `chats` and `chats_done` `null`. At most about two a second; the first and last of `--all` always come.
+  Only in machine output (`--json`, `--jsonl`, or stdout not a terminal) and not in a `--background` job's log;
+  stdout still carries the one answer. Archive services take an optional `onChat` for the same counts.
+
+### Changed — may break callers
+
+- **Needs `@wirecat/cli-base` 0.68.0** (peer range `>=0.68.0 <0.69.0`). cli-base's `Credentials` in `auto` now reads
+  a sign-in the private file holds before the keyring and keeps its refreshes there (WC-SECR-4).
+
+### Fixed
+
+- **A new OAuth sign-in moves a file sign-in back to the keyring.** `TokenStorage.write` takes `{ signIn: true }`, and
+  the keeper's `signIn` and `save` pass it: the keyring is tried again and, once it takes the sign-in, the file copy
+  is removed. A refresh stays where the sign-in is, so a locked keyring is not tried for it on every refresh.
+
 ## 0.506.0 — 31.10.2026
 
 ### Added

package/dist/calendar/cli/answers.d.ts

@@ -156,7 +156,10 @@ export declare const calendarEvent: v.StrictObjectSchema<{
     }, undefined>, undefined>;
     readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;
-/** A hit of the stored search, or with `--backend server` one the provider's own search found and nothing stored. */
+/**
+ * A hit of the stored search (with `--backend both`, `server` too when the provider also found it), or one the
+ * provider's own search found and nothing stored.
+ */
 export declare const calendarSearchHit: v.UnionSchema<[v.StrictObjectSchema<{
     readonly provider: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly account: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -172,7 +175,7 @@ export declare const calendarSearchHit: v.UnionSchema<[v.StrictObjectSchema<{
     readonly excerpt: v.StringSchema<undefined>;
     readonly occurrences: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
     readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
-    readonly found_by: v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>;
+    readonly found_by: v.ArraySchema<v.PicklistSchema<["words", "meaning", "server"], undefined>, undefined>;
 }, undefined>, v.StrictObjectSchema<{
     readonly provider: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly account: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/calendar/cli/answers.js

@@ -138,7 +138,10 @@ const hitFields = {
     url: v.optional(text),
     untrusted,
 };
-/** A hit of the stored search, or with `--backend server` one the provider's own search found and nothing stored. */
+/**
+ * A hit of the stored search (with `--backend both`, `server` too when the provider also found it), or one the
+ * provider's own search found and nothing stored.
+ */
 export const calendarSearchHit = v.union([
     v.strictObject({
         ...hitFields,
@@ -146,7 +149,7 @@ export const calendarSearchHit = v.union([
         excerpt: text,
         occurrences: count,
         updated_at: time,
-        found_by: v.array(v.picklist(["words", "meaning"])),
+        found_by: v.array(v.picklist(["words", "meaning", "server"])),
     }),
     v.strictObject({
         ...hitFields,

package/dist/calendar/cli/index.js

@@ -12,7 +12,7 @@ import { linkPeople } from "../../services/people.js";
 import { BUSY_QUERY, BUSY_QUERY_NOTE, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
 import { CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, EVENTS_QUERY, EVENTS_QUERY_NOTE, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, resolveAnswer, reviewsAnswer, weekFilter, } from "../reads.js";
 import { REPEAT_HELP } from "../recurrence.js";
-import { serverSearchAnswer } from "../server-search.js";
+import { bothSearchAnswer, serverSearchAnswer } from "../server-search.js";
 import { calendarStatus, syncCalendars } from "../sync.js";
 import { createEvent, deleteEvent, EVENT_RESPONSES, moveEvent, respondToEvent, updateEvent, } from "../writes.js";
 import { CALENDARS_QUERY, declareCalendarAnswers, PEOPLE_QUERY } from "./answers.js";
@@ -201,8 +201,9 @@ const addCalendarCommandsDefinition = (program, deps) => {
         }), command);
     });
     const events = annotate(program.command("events").description("the account's stored events"), { effects: GROUP });
-    example(withQuery(annotate(events.command("list"), { effects: LOCAL_READ }).description("list stored events, earliest first"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), "events list starts_at>=2026-11-02 starts_at<2026-11-07 --json", "events list ends_at>=today person:ana@example.com")
-        .option("--limit <n>", "events at most, 1–1000", integer, 100)
+    example(withQuery(annotate(events.command("list"), { effects: LOCAL_READ }).description("list stored events, earliest first"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), "events list starts_at>=2026-11-02 starts_at<2026-11-07 --json", "events list ends_at>=today person:ana@example.com", "events list starts_at>=2026-11-02 --limit 50 --page 2")
+        .option("--limit <n>", "events per page, 1–1000", integer, 100)
+        .option("--page <n>", "which page, starting at 1", integer, 1)
         .action(async (words, opts, command) => {
         const filter = await eventsFilter(words, {
             store: deps.store,
@@ -211,7 +212,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
             now: now(),
             personOf: personId,
         });
-        print(eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }), EVENT_ITEM_UNTRUSTED), command);
+        print(eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }, opts.page), EVENT_ITEM_UNTRUSTED), command);
     });
     example(annotate(events.command("show"), { effects: LOCAL_READ })
         .description("one event: its calendar copies, attendees with their person, Drive files and history")
@@ -225,49 +226,59 @@ const addCalendarCommandsDefinition = (program, deps) => {
     const search = example(annotate(searches.command("events"), { effects: deps.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
         .description(deps.serverSearch
         ? "find stored events by words, and by meaning when its model is downloaded; with --backend server, ask " +
-            "the provider instead"
+            "the provider instead, with --backend both, both"
         : "find stored events by words, and by meaning when its model is downloaded")
-        .argument("<query...>", "what to find in titles, descriptions, places and attendees"), "search events roadmap planning --json", ...(deps.serverSearch ? ["search events --backend server quarterly review"] : []))
+        .argument("<query...>", "what to find in titles, descriptions, places and attendees"), "search events roadmap planning --json", ...(deps.serverSearch
+        ? ["search events --backend server quarterly review", "search events --backend both quarterly review"]
+        : []))
         .option("--limit <n>", "events per page", integer, 20)
-        .option("--cursor <cursor>", "continue from a page's next_offset", (text) => (text === "0" ? 0 : integer(text)), 0)
+        .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it", (text) => (text === "0" ? 0 : integer(text)), 0)
         .option("--exact", "every word as written, no word stems")
         .option("--newest", "latest start first instead of best first");
     if (deps.serverSearch)
         search.addOption(new Option("--backend <archive|server|both>", "where to search: archive, the local store, or server, the provider's own search over the synced calendars, " +
-            "earliest first")
+            "earliest first; both gives the store's hits, each the provider also found marked server, then the " +
+            "provider's other hits, one page with no cursor")
             .choices(["archive", "server", "both"])
             .default("archive"));
     search.action(async (words, opts, command) => {
-        if (opts.backend === "both")
-            throw new CliError("validation_error", "search events --backend both is not offered: the store's search and the provider's rank and page events " +
-                "differently, so one merged list would have no single order or next page; run --backend archive and " +
-                "--backend server", { reason: "search.one-backend" });
-        if (opts.backend === "server") {
+        const archived = () => searchEvents(messages("search"), words.join(" "), {
+            accounts: [deps.account],
+            limit: opts.limit,
+            offset: opts.cursor,
+            timezone: zone(),
+            command: program.name(),
+            ...(opts.exact ? { exact: true } : {}),
+            ...(opts.newest ? { newest: true } : {}),
+        });
+        if (opts.backend === "server" || opts.backend === "both") {
+            const flag = `search events --backend ${opts.backend}`;
             if (command.optsWithGlobals().offline)
-                throw new CliError("permission_error", "search events --backend server asks the provider; leave out --offline", {
+                throw new CliError("permission_error", `${flag} asks the provider; leave out --offline`, {
                     reason: "search.offline",
                 });
-            if (opts.exact || opts.cursor || opts.newest)
-                throw new CliError("validation_error", "search events --backend server takes neither --exact, --cursor nor --newest: the provider ranks and pages it", { reason: "search.server-options" });
-            const found = await serverSearchAnswer(source(), deps.store, {
+            if (opts.backend === "server" && opts.exact)
+                throw new CliError("validation_error", `${flag} takes no --exact: the provider matches words its own way`, {
+                    reason: "search.server-options",
+                });
+            if (opts.cursor || opts.newest)
+                throw new CliError("validation_error", `${flag} takes neither --cursor nor --newest: the provider ranks and pages its own hits`, { reason: "search.server-options" });
+            const served = await serverSearchAnswer(source(), deps.store, {
                 accountId: deps.accountId,
                 account: deps.account,
                 query: words.join(" "),
                 limit: opts.limit,
             });
-            print({ ...found, untrusted: SERVER_SEARCH_UNTRUSTED }, command);
+            if (opts.backend === "server")
+                print({ ...served, untrusted: SERVER_SEARCH_UNTRUSTED }, command);
+            else
+                print({
+                    ...(await bothSearchAnswer(deps.store, deps.accountId, await archived(), served, opts.limit)),
+                    untrusted: SEARCH_UNTRUSTED,
+                }, command);
             return;
         }
-        const found = await searchEvents(messages("search"), words.join(" "), {
-            accounts: [deps.account],
-            limit: opts.limit,
-            offset: opts.cursor,
-            timezone: zone(),
-            command: program.name(),
-            ...(opts.exact ? { exact: true } : {}),
-            ...(opts.newest ? { newest: true } : {}),
-        });
-        print({ ...found, untrusted: SEARCH_UNTRUSTED }, command);
+        print({ ...(await archived()), untrusted: SEARCH_UNTRUSTED }, command);
     });
     if (deps.writes)
         addEventWrites(events, deps.writes, { deps, now, zone, print, example });
@@ -322,7 +333,7 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
         zone: zone(),
         names: {
             notify: "--notify or --no-notify",
-            id: "--id",
+            id: "--operation-id",
             calendar: "--calendar",
             series: "--series",
             following: "--following",
@@ -362,10 +373,10 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
         .option("--calendar <id>", "the calendar, when the event is on more than one of the account's");
     example(notify(fields(write("create"), false)
         .description("add an event to a calendar; with --repeat, one that repeats")
-        .argument("<calendar>", "the calendar's id, or the provider's id")).option("--id <id>", "the id a create that ended in outcome_unknown named: a retry finds that event"), "events create 3 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T11:00", "events create 3 --title 'Example review' --start-date 2026-11-03 --end-date 2026-11-03 " +
+        .argument("<calendar>", "the calendar's id, or the provider's id")).option("--operation-id <id>", "the operation_id a create that ended in outcome_unknown named: a retry finds that event"), "events create 3 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T11:00", "events create 3 --title 'Example review' --start-date 2026-11-03 --end-date 2026-11-03 " +
         "--attendee ana@example.com --no-notify", "events create 3 --title 'Example standup' --start-time 2026-11-02T09:30 --end-time 2026-11-02T09:45 " +
         "--repeat 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12'").action(async (calendar, opts, command) => {
-        const { notify: choice, id, ...rest } = opts;
+        const { notify: choice, operationId: id, ...rest } = opts;
         printWritten(await createEvent(context(command), calendar, fieldsOf(rest), {
             ...(choice === undefined ? {} : { notify: choice }),
             ...(id === undefined ? {} : { id }),
@@ -377,8 +388,8 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
         .option("--series", "change the whole repeating event, not only this occurrence")
         .option("--following", "change this occurrence and every later one: the repeating event ends before it and a new one starts " +
         "with the change")
-        .option("--id <id>", "with --following, the id an outcome_unknown named: a retry finds that new series")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify", "events update event:42 --series --repeat 'FREQ=WEEKLY;BYDAY=TU;UNTIL=20261231T230000Z' --no-notify", "events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify").action(async (reference, opts, command) => {
-        const { calendar: _calendar, series: _series, following: _following, notify: _notify, id, ...rest } = opts;
+        .option("--operation-id <id>", "with --following, the operation_id an outcome_unknown named: a retry finds that new series")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify", "events update event:42 --series --repeat 'FREQ=WEEKLY;BYDAY=TU;UNTIL=20261231T230000Z' --no-notify", "events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify").action(async (reference, opts, command) => {
+        const { calendar: _calendar, series: _series, following: _following, notify: _notify, operationId: id, ...rest } = opts;
         printWritten(await updateEvent(context(command), reference, fieldsOf(rest), {
             ...choicesOf(opts),
             ...(id === undefined ? {} : { id }),

package/dist/calendar/reads.d.ts

@@ -182,7 +182,8 @@ export declare const resolveAnswer: (store: EventStore, accountId: number, revie
     status: "apart" | "linked" | "open";
     chosen: string | null;
 }>;
-export declare const eventsAnswer: (store: EventStore, filter: EventFilter | null) => Promise<{
+/** One page of the events, from 1: `filter.limit` events each. */
+export declare const eventsAnswer: (store: EventStore, filter: EventFilter | null, number?: number) => Promise<{
     limit: number;
     hasMore: boolean;
     items: {

package/dist/calendar/reads.js

@@ -331,10 +331,11 @@ const overlapsOf = async (store, rows, filter) => {
             other.endsAt > event.startsAt),
     ]));
 };
-export const eventsAnswer = async (store, filter) => {
+/** One page of the events, from 1: `filter.limit` events each. */
+export const eventsAnswer = async (store, filter, number = 1) => {
     if (filter === null)
         return listed([]);
-    const { rows, limit, hasMore } = await page(store, filter);
+    const { rows, limit, hasMore } = await page(store, { ...filter, offset: (number - 1) * (filter.limit ?? 100) });
     const changes = filter.changedSince === undefined ? null : await changesOf(store, rows, filter, filter.changedSince);
     const overlaps = filter.overlapping ? await overlapsOf(store, rows, filter) : null;
     return listed(rows.map((event) => {
@@ -350,5 +351,5 @@ export const eventsAnswer = async (store, filter) => {
                 : {}),
             ...(overlaps ? { overlaps: (overlaps.get(event.id) ?? []).map(({ id }) => `event:${id}`) } : {}),
         };
-    }), { limit, hasMore });
+    }), { limit, hasMore, page: number });
 };

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

@@ -1,4 +1,5 @@
 import type { EventStore } from "../meetings/index.js";
+import type { EventsFound, FoundEvent } from "../services/events-search.js";
 import type { AccountKey } from "../store/store.js";
 import type { CalendarSource } from "./source.js";
 /**
@@ -29,3 +30,33 @@ export declare const serverSearchAnswer: (source: CalendarSource, store: EventSt
     }[];
     has_more: boolean;
 }>;
+type FoundBy = FoundEvent["found_by"][number] | "server";
+type ServerFound = Awaited<ReturnType<typeof serverSearchAnswer>>;
+/**
+ * `--backend both`: the stored search's hits in its own order, each one the provider also found marked `server`, then
+ * what only the provider found, earliest first. One page and no cursor: the two sides rank and page differently.
+ * A provider hit is matched by its stored copy, so an occurrence the store keeps under another id shows twice.
+ */
+export declare const bothSearchAnswer: (store: EventStore, accountId: number, archived: EventsFound, served: ServerFound, limit: number) => Promise<{
+    query: string;
+    by: "both";
+    meaning_skipped?: string | undefined;
+    hits: ({
+        provider: string;
+        account: string;
+        calendar: string;
+        external_id: string;
+        title: string | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        all_day: boolean;
+        status: "confirmed" | "tentative";
+        location: string | null;
+        url?: string | undefined;
+        found_by: "server"[];
+    } | (Omit<FoundEvent, "found_by"> & {
+        found_by: FoundBy[];
+    }))[];
+    has_more: boolean;
+}>;
+export {};

package/dist/calendar/server-search.js

@@ -39,3 +39,31 @@ export const serverSearchAnswer = async (source, store, { accountId, account, qu
     hits.sort((a, b) => (a.starts_at ?? "").localeCompare(b.starts_at ?? ""));
     return { query, by: "server", hits: hits.slice(0, limit), has_more: more || hits.length > limit };
 };
+/**
+ * `--backend both`: the stored search's hits in its own order, each one the provider also found marked `server`, then
+ * what only the provider found, earliest first. One page and no cursor: the two sides rank and page differently.
+ * A provider hit is matched by its stored copy, so an occurrence the store keeps under another id shows twice.
+ */
+export const bothSearchAnswer = async (store, accountId, archived, served, limit) => {
+    const calendars = new Map((await store.calendars(accountId)).map((calendar) => [calendar.externalId, calendar]));
+    const hits = archived.hits.map((hit) => ({ ...hit }));
+    const byRef = new Map(hits.map((hit) => [hit.ref, hit]));
+    const onlyServer = [];
+    for (const hit of served.hits) {
+        const calendar = calendars.get(hit.calendar);
+        const entry = calendar ? await store.entry(calendar.id, hit.external_id) : null;
+        const held = entry?.eventId == null ? undefined : byRef.get(`event:${entry.eventId}`);
+        if (held)
+            held.found_by = [...held.found_by, "server"];
+        else
+            onlyServer.push(hit);
+    }
+    const merged = [...hits, ...onlyServer];
+    return {
+        query: archived.query,
+        by: "both",
+        ...(archived.meaning_skipped === undefined ? {} : { meaning_skipped: archived.meaning_skipped }),
+        hits: merged.slice(0, limit),
+        has_more: archived.has_more || served.has_more || merged.length > limit,
+    };
+};

package/dist/cli/bot/token.js

@@ -40,7 +40,7 @@ export class BotTokenStore {
         return stored ? { token: stored.secret, source: stored.source } : undefined;
     }
     write(token) {
-        return this.#credentials.write(this.#account, token);
+        return this.#credentials.write(this.#account, token, { signIn: true });
     }
     readKeyring() {
         const stored = this.readStored();
@@ -69,7 +69,7 @@ export class BotTokenStore {
         return this.#secretOf(name).read(`${this.#account}:${name}`);
     }
     writeSecret(name, secret) {
-        return this.#secretOf(name).write(`${this.#account}:${name}`, secret);
+        return this.#secretOf(name).write(`${this.#account}:${name}`, secret, { signIn: true });
     }
     removeSecret(name) {
         return this.#secretOf(name).remove(`${this.#account}:${name}`);

package/dist/cli/messenger/backfill-command.js

@@ -12,6 +12,7 @@ import { JOBS_QUERY, jobItems } from "../../services/job-query.js";
 import { dateWindow } from "../../services/moment.js";
 import { validateCatchUpBounds } from "../../services/search-catchup.js";
 import { applyTaskRulesSinceLastPass } from "../../services/task-rules.js";
+import { stepLines } from "../../terminal/step-lines.js";
 import { environmentOf } from "../context.js";
 import { destroysNothing, FETCH, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -41,7 +42,8 @@ export const syncCommand = (messenger) => {
         cooperative: true,
     })
         .summary("fetch and save a chat's message history")
-        .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat")
+        .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat; " +
+        'with --json, stderr carries progress lines: {"event":"progress","step":"sync","chats","chats_done","fetched"}, counts only')
         .argument("[chat]", messenger.chatArgument)
         .option("--all", `every chat, most recently active first — what search needs; the last ${ALL_SINCE} unless --since-time or --last`)
         .option("--limit <n>", `at most this many messages in this run, per chat with --all; ${fetching.maxPages * fetching.page} if not given`, wholeNumber)
@@ -139,6 +141,8 @@ export const syncCommand = (messenger) => {
         const jobs = jobsDir(messenger.app, context.env);
         const jobId = context.env[envName(messenger.app, "BACKFILL_JOB")];
         const stop = stopOnSignal(this);
+        // A background job keeps its log as it was; its progress is the job file.
+        const progress = syncProgress(stepLines(context.streams.diagnostic, !jobId && context.format !== "pretty"));
         try {
             const options = {
                 limit,
@@ -149,10 +153,13 @@ export const syncCommand = (messenger) => {
                 ...(last === undefined ? {} : { last }),
                 note: context.renderer.note,
                 stop: stop.signal,
-                onPage: (progress) => {
+                onPage: (page) => {
                     if (jobId)
-                        updateJob(jobs, jobId, { progress: { ...progress, at: new Date().toISOString() } });
+                        updateJob(jobs, jobId, { progress: { ...page, at: new Date().toISOString() } });
+                    if (chat !== undefined)
+                        progress({ chats: null, chats_done: null, fetched: page.fetched });
                 },
+                onChat: ({ chats, done, fetched }) => progress({ chats, chats_done: done, fetched }, done === 0 || done === chats),
             };
             const result = await context.withServices((services) => chat === undefined ? services.archive.fetchAll(options) : services.archive.fetch(chat, options));
             if (jobId)
@@ -197,6 +204,22 @@ export const syncCommand = (messenger) => {
         }
     });
 };
+/** At most this often a progress line, so a run of fast pages or of chats already current does not flood the window. */
+const PROGRESS_EVERY_MS = 500;
+/**
+ * `messages sync`'s progress for a window to draw a bar by: counts only, because the lines reach a desktop app and
+ * its logs — never a chat's id or title. `always` keeps the first and the last line of `--all` through the throttle.
+ */
+const syncProgress = (emit) => {
+    let last = Number.NEGATIVE_INFINITY;
+    return (counts, always = false) => {
+        const now = Date.now();
+        if (!always && now - last < PROGRESS_EVERY_MS)
+            return;
+        last = now;
+        emit({ event: "progress", step: "sync", ...counts });
+    };
+};
 /**
  * What the sync stored, through the task rules (owner, 2026-10-14). A failure is noted, never the sync's failure:
  * the messages are already kept, and the next sync's pass starts from the same stop point.

package/dist/embeddings/keys.js

@@ -33,7 +33,7 @@ export const embeddingKeys = (app, env = process.env, keyring) => {
                 : undefined;
             return shared ? { key: shared, source: "env" } : undefined;
         },
-        write: (provider, key) => credentials(provider).write(account(provider), key),
+        write: (provider, key) => credentials(provider).write(account(provider), key, { signIn: true }),
         remove: (provider) => credentials(provider).remove(account(provider)),
     };
 };

package/dist/mail/sync.d.ts

@@ -101,5 +101,7 @@ export interface MailSyncOptions {
      * is tried once more at the end of the run and, if it still fails, left for the next one. `max` defaults to no limit.
      */
     budget?: RunBudget;
+    /** Pauses before a round is read again after the store was locked; tests pass one that does not wait. */
+    wait?: (ms: number) => Promise<void>;
 }
 export declare const syncMail: (source: MailSource, store: MessageStore, options: MailSyncOptions) => Promise<MailSyncResult>;

package/dist/mail/sync.js

@@ -1,6 +1,7 @@
 import { setTimeout } from "node:timers/promises";
 import { CliError } from "@wirecat/cli-base";
 import { importEngine } from "../attachments/extract.js";
+import { isBusy } from "../store/sqlite/transaction.js";
 import { addressOf, FETCH_CHUNK, MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
 import { BULK, bulkBox } from "./bulk.js";
 import { factsOf } from "./facts.js";
@@ -26,6 +27,8 @@ const RESUME_FROM = 5_000;
 export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
 export { RETRYABLE_ATTACHMENTS } from "./retry.js";
 const LIST_SLICE = 200;
+const STORE_BUSY_TRIES = 5;
+const STORE_BUSY_WAIT_MS = 2_000;
 export const syncMail = async (source, store, options) => {
     const { budget, index } = options;
     if (budget === undefined || options.retryAttachments || options.account.mode === "mbox")
@@ -45,14 +48,31 @@ export const syncMail = async (source, store, options) => {
         asked: 0,
     };
     const rounds = [];
+    let busyWaits = 0;
     const goOn = async () => {
         for (;;) {
             plan.asked = 0;
             plan.remaining = 0;
+            const triedBefore = plan.tried.size;
             try {
                 rounds.push(await syncRound(source, store, { ...options, index: undefined, max: options.max ?? Number.POSITIVE_INFINITY }, plan));
             }
             catch (error) {
+                // Another process (memo's scheduled sync) held the store's write lock past its busy timeout. The slices this
+                // run committed stay; the round's messages are asked for again after a pause, while the budget has room.
+                if (isBusy(error) && busyWaits < STORE_BUSY_TRIES && !options.signal?.aborted) {
+                    busyWaits++;
+                    for (const key of [...plan.tried].slice(triedBefore))
+                        plan.tried.delete(key);
+                    const stop = budget.take();
+                    if (stop === null) {
+                        await (options.wait ?? setTimeout)(STORE_BUSY_WAIT_MS * busyWaits);
+                        continue;
+                    }
+                    plan.stopped = stop;
+                    plan.remaining = Math.max(plan.remaining, 1);
+                    return;
+                }
                 // A request cut at the deadline, or failed after the budget was spent, is the run's end, not its failure: what
                 // earlier rounds saved is kept and the next run goes on. While the budget has room the error is real.
                 const transient = error instanceof CliError && (error.code === "timeout" || error.code === "network_error");

package/dist/meetings/reads.d.ts

@@ -13,6 +13,7 @@ export declare const meetingShow: (store: MeetingStore, id: number, accountId?:
 export declare const listed: <T>(items: T[], page?: {
     limit: number;
     hasMore: boolean;
+    page?: number;
 }) => {
     limit: number;
     hasMore: boolean;

package/dist/oauth/keeper.js

@@ -137,13 +137,13 @@ export const tokenKeeper = (options) => {
             const extra = (await accept?.(received)) ?? undefined;
             await locked(async () => {
                 forget();
-                storage.write({ tokens: received, client, ...(extra ? { extra } : {}) });
+                storage.write({ tokens: received, client, ...(extra ? { extra } : {}) }, { signIn: true });
             });
             return { scopes: received.scopes };
         },
         save: (saved, extra) => locked(async () => {
             forget();
-            storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) });
+            storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) }, { signIn: true });
         }),
         signOut: ({ revoke = false } = {}) => locked(async () => {
             forget();

package/dist/oauth/storage.d.ts

@@ -1,4 +1,4 @@
-import { type CredentialSource, type CredentialsOptions } from "@wirecat/cli-base";
+import { type CredentialSource, type CredentialsOptions, type WriteOptions } from "@wirecat/cli-base";
 import type { OAuthClient, TokenSet } from "./provider.js";
 export interface StoredTokens {
     tokens: TokenSet;
@@ -29,7 +29,8 @@ export interface TokenStorage {
     /** Throws when the entry cannot be saved, so a sign-in fails before the browser, not after consent. */
     probe(): void;
     read(): StoredTokens | undefined;
-    write(input: Omit<EncodeInput, "previous">): void;
+    /** `signIn` moves an entry the file holds back to the keyring when it takes it (WC-SECR-4); a refresh leaves it. */
+    write(input: Omit<EncodeInput, "previous">, options?: WriteOptions): void;
     remove(): CredentialSource[];
 }
 export declare const oauthAccount: (providerId: string, profile: string) => string;

package/dist/oauth/storage.js

@@ -162,9 +162,9 @@ export const credentialStorage = (options) => {
             throw keyringFailure(error);
         }
     };
-    const save = (value) => {
+    const save = (value, writeOptions) => {
         try {
-            credentials.write(account, value);
+            credentials.write(account, value, writeOptions);
         }
         catch (error) {
             throw keyringFailure(error, value);
@@ -195,7 +195,7 @@ export const credentialStorage = (options) => {
             const value = current();
             return value === undefined ? undefined : codec.decode(value);
         },
-        write: (input) => save(codec.encode({ ...input, previous: raw(account) })),
+        write: (input, writeOptions) => save(codec.encode({ ...input, previous: raw(account) }), writeOptions),
         remove: () => {
             try {
                 return credentials.remove(account);

package/dist/services/archive.d.ts

@@ -39,6 +39,12 @@ export interface FetchOptions {
         chatId: string;
         oldest: number;
     }) => void;
+    /** `fetchAll` only: once the chat list is read, then after each chat, current or not; counts across every chat. */
+    onChat?: (progress: {
+        chats: number;
+        done: number;
+        fetched: number;
+    }) => void;
 }
 /** A type, not an interface: a job keeps it as a plain record. */
 export type Fetched = {

package/dist/services/archive.js

@@ -148,6 +148,8 @@ export const archiveService = (deps) => {
                 ...options,
                 catchUp: catchingUp ? (options.catchUp ?? {}) : false,
             });
+            const finished = () => options.onChat?.({ chats: chats.length, done: answer.items.length, fetched: answer.fetched });
+            finished();
             for (const chat of chats) {
                 if (options.stop.aborted || batch.stopped) {
                     answer.stopped = true;
@@ -155,6 +157,7 @@ export const archiveService = (deps) => {
                 }
                 if (await upToDate(chat)) {
                     answer.items.push({ chat: chat.id, title: chat.title, fetched: 0, complete: true, current: true });
+                    finished();
                     continue;
                 }
                 try {
@@ -183,6 +186,7 @@ export const archiveService = (deps) => {
                     const issue = batch.fail(chat.id, "history", error);
                     answer.items.push({ chat: chat.id, title: chat.title, fetched: 0, complete: false, error: issue.code, issue });
                 }
+                finished();
             }
             if (batch.failed > 0)
                 answer.batch = batch.result();

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

@@ -1,4 +1,5 @@
 import type { CacheDatabase } from "../driver.js";
+export declare const isBusy: (error: unknown) => boolean;
 /**
  * One write transaction. The outermost takes the write lock at once (`BEGIN IMMEDIATE`): a deferred one that
  * reads first fails with SQLITE_BUSY when another process writes in between, and tg, max, memo and zm share

package/dist/store/sqlite/transaction.js

@@ -3,7 +3,7 @@ import { drainMentions } from "./mention-drain.js";
 import { drainStems, stemmerCache } from "./stems.js";
 const SQLITE_BUSY = 5;
 const pause = new Int32Array(new SharedArrayBuffer(4));
-const isBusy = (error) => {
+export const isBusy = (error) => {
     const { errcode, errno } = (error ?? {});
     const code = errcode ?? errno;
     return typeof code === "number" && (code & 0xff) === SQLITE_BUSY;

package/dist/terminal/sign-in-steps.js

@@ -2,6 +2,7 @@ import { StringDecoder } from "node:string_decoder";
 import { CliError } from "@wirecat/cli-base";
 import { Option } from "commander";
 import { MAX_SECRET_INPUT } from "../cli/input-policy.js";
+import { stepLines } from "./step-lines.js";
 /**
  * Opt-in, because a read nobody answers hangs: an agent running `session start` in a shell must get the refusal it
  * gets today, and only a caller that holds stdin open and answers each `needs` line (WireCat Desktop) passes it.
@@ -10,10 +11,7 @@ export const answerStdinOption = () => new Option("--answer-stdin", "with --json
 export const signInSteps = ({ diagnostic, json, answers, input = process.stdin }) => {
     if (answers && !json)
         throw new CliError("validation_error", "--answer-stdin needs --json");
-    const emit = (event) => {
-        if (json)
-            diagnostic(JSON.stringify(event));
-    };
+    const emit = stepLines(diagnostic, json);
     const next = answers ? lineReader(input) : undefined;
     return {
         json,

package/dist/terminal/step-lines.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Machine-readable step lines: one JSON object per line on the diagnostic stream, only in `--json` / `--jsonl`, so
+ * stdout keeps its single answer and a person at a terminal sees nothing new. Sign-in and `messages sync` share it.
+ */
+export declare const stepLines: (diagnostic: (line: string) => void, json: boolean) => (event: Record<string, unknown> & {
+    event: string;
+}) => void;

package/dist/terminal/step-lines.js

@@ -0,0 +1,8 @@
+/**
+ * Machine-readable step lines: one JSON object per line on the diagnostic stream, only in `--json` / `--jsonl`, so
+ * stdout keeps its single answer and a person at a terminal sees nothing new. Sign-in and `messages sync` share it.
+ */
+export const stepLines = (diagnostic, json) => (event) => {
+    if (json)
+        diagnostic(JSON.stringify(event));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.506.0",
+  "version": "0.508.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",
@@ -247,7 +247,7 @@
     "@types/node": "^22.20.5",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "@wirecat/cli-base": "0.67.0",
+    "@wirecat/cli-base": "0.68.0",
     "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
     "commander": "15.0.0",
     "cspell": "10.4.0",
@@ -267,7 +267,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.67.0 <0.68.0",
+    "@wirecat/cli-base": ">=0.68.0 <0.69.0",
     "commander": ">=15"
   },
   "bin": {