@wirecat/cli-core 0.492.0 → 0.493.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ shape of this file.
 
 ## Unreleased
 
+## 0.493.0 — 31.10.2026
+
+### Added
+
+- **`chatCoverage(store, account, chatIds)` says what the store holds of each chat.** Per chat, in the order asked:
+  `completeness` (`complete`, `partial` or `unknown`, up to date, gaps, start reached, last fetch) and `held` (messages,
+  oldest, newest), never text. It reads only the chats named, so a store of thousands of chats costs what the ids cost.
+  `coverageGaps` also takes a list of these rows and answers `missing` (`field: "history"`) and `next`: for the first
+  incomplete chat, `messages sync <chat> --since-time <start of the window>` when the answer has a window, then
+  `messages sync <chat>`. The step `messages.sync` takes `since_time`.
+- **`messages list --offline` says when the store holds only part of the chat.** A chat that is `partial` or was never
+  fetched gives `meta.complete: false`, exit code 0, `missing` and `next`, as an offline read of 262 of 777 messages
+  must not pass for the whole chat. Online reads are unchanged.
+- **`tasks agenda` says how much of each listed chat the store holds.** Each row of `owed`, `waiting` and `unsynced` has
+  `completeness` and `held`; a chat held only in part is marked `[partial]` or `[never fetched]` in the text, with one
+  line above the lists. The answer then has `meta.complete: false`, `missing` and `next` (bounded sync over the
+  `--within` window, then the whole chat).
+- **`search all` names the chat to sync** when the store holds the chats its messages were searched in only in part:
+  `missing` (`field: "coverage"`) and `next`, from the same coverage `search messages` reports. `SearchAllFound` gains
+  `coverage`.
+
+### Changed — may break callers
+
+- **`tasks agenda --json` rows gain `completeness` and `held`**, and the answer may carry `meta.complete: false` with
+  `missing` and `next`; a caller that stops on anything but `meta.complete: true` now sees a store that holds chats in
+  part as incomplete. `tasks agenda` is declared `partial`, so the exit code stays 0. `AgendaChat` gains `coverage`
+  and `Agenda` gains `since`.
+- **`search messages`, `search mail` and `search all` answer `meta.complete: false` when a chat searched is partial or
+  never fetched**, where they kept `true` and put the gap only in `missing` and `next`. Exit code stays 0 (the commands
+  are declared `partial`). A caller that read `meta.complete` as "no source failed" must read `missing` for the reason.
+- **`messages list --offline --json` may carry `meta.complete: false`, `missing` and `next`** for a chat held in part.
+  `messages list` is declared `partial`: the exit code stays 0.
+
 ## 0.492.0 — 31.10.2026
 
 ### Added

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

@@ -5,7 +5,9 @@ import { isLocator, parseLocator } from "../../domain/locator.js";
 import { SAVE_HELP } from "../../meetings/index.js";
 import { renderMessages } from "../../render/messages.js";
 import { renderThreadLinks } from "../../render/thread-context.js";
+import { chatCoverage } from "../../services/chat-coverage.js";
 import { readMail } from "../../services/mail-search.js";
+import { storedChatId } from "../../services/message-resolution.js";
 import { modelWith, spoken } from "../../speech/hearing.js";
 import { REMOTE_READ } from "../effects.js";
 import { itemOf, listOf, renderAnswer } from "../envelope.js";
@@ -30,6 +32,7 @@ import { pinCommand, starCommands, unpinCommand } from "./messages-pin-command.j
 import { pressCommand } from "./messages-press-command.js";
 import { scheduledCommand } from "./messages-scheduled-command.js";
 import { sendCommand } from "./messages-send-command.js";
+import { coverageGaps } from "./search-answers.js";
 import { threadOptions, threadRequest } from "./thread-options.js";
 import { transcribeSubcommand } from "./transcribe-command.js";
 /** `messages`: reading, and sending through the guard. A CLI may add its own subcommands. */
@@ -40,6 +43,7 @@ export const messagesCommand = (messenger) => {
     const list = annotate(messages.command("list"), {
         examples: [`${messenger.app.command} personal messages list "Book club" --limit 20`],
         effects: REMOTE_READ,
+        partial: true,
     })
         .description("a chat's messages, oldest to newest")
         .addHelpText("after", SAVE_HELP)
@@ -68,6 +72,12 @@ export const messagesCommand = (messenger) => {
         const next = page.hasMore
             ? cursorOf(window, { first: page.items[0]?.id, last: page.items.at(-1)?.id })
             : undefined;
+        // Offline, the store is the whole answer: say how much of the chat it holds. Online the messenger is read.
+        const gaps = context.settings.offline
+            ? coverageGaps(await context.withStore(async (store, account) => chatCoverage(store, account, [
+                await storedChatId(messenger, chat, store, account, { includeLeft: true }),
+            ])))
+            : { next: [], missing: [] };
         renderAnswer(this, context, listOf("messages list", {
             items: messageItems(heardItems(page.items, hearing), reader),
             limit,
@@ -75,7 +85,9 @@ export const messagesCommand = (messenger) => {
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
             args: { chat, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
-            missing: hearingMissing(hearing, transcribe === true),
+            next: gaps.next,
+            missing: [...hearingMissing(hearing, transcribe === true), ...gaps.missing],
+            ...(gaps.missing.length > 0 ? { meta: { complete: false } } : {}),
         }), () => renderMessages(spokenItems(page.items, hearing), viewOf(context, messenger)));
     });
     annotate(list, { output: { entity: "message" }, query: history });

package/dist/cli/messenger/search-answers.d.ts

@@ -1,6 +1,7 @@
 import type { Missing, NextStep } from "@wirecat/cli-base/standards";
 import type { InferOutput } from "valibot";
 import type { ENTITIES } from "../../entities/index.js";
+import type { ChatCoverage } from "../../services/chat-coverage.js";
 import type { FoundMessage, SearchFound } from "../../services/messages.js";
 import type { MeaningSkipped } from "../../services/messages-discovery.js";
 import type { FoundNote, NotesFoundOf } from "../../services/notes-search.js";
@@ -16,8 +17,11 @@ export type HitItem = InferOutput<(typeof ENTITIES)["hit"]>;
 /** The page a `--page` asks for, as the offset the search services take. */
 export declare const offsetOf: (page: number | undefined, limit: number) => number | undefined;
 export declare const messageHitItem: (hit: FoundMessage, query?: string) => MessageHitItem;
-/** What the archive lacked for this answer, and the step that would fill it. */
-export declare const coverageGaps: (found: Pick<SearchFound, "coverage" | "refreshed">, shown: number) => {
+/**
+ * What the archive lacked for this answer, and the step that would fill it. From a search's coverage, or from the
+ * chats an answer is about (`since` is the start of the window it was asked for).
+ */
+export declare const coverageGaps: (found: Pick<SearchFound, "coverage" | "refreshed"> | ChatCoverage[], shown?: number, since?: string) => {
     next: NextStep[];
     missing: Missing[];
 };

package/dist/cli/messenger/search-answers.js

@@ -88,15 +88,49 @@ export const messageHitItem = (hit, query = "") => {
 };
 const accountName = ({ provider, account }) => `${provider}:${account}`;
 /** A source left out is an issue by its code; the sentence saying why goes to a person as a note, never here. */
-const metaOf = (accounts, skipped = []) => ({
+const metaOf = (accounts, skipped = [], heldInPart = false) => ({
     accounts: accounts.map(accountName),
-    complete: skipped.length === 0,
+    complete: skipped.length === 0 && !heldInPart,
     ...(skipped.length
         ? { issues: skipped.map(({ source, resource, code }) => ({ code, source: source ?? resource ?? "" })) }
         : {}),
 });
-/** What the archive lacked for this answer, and the step that would fill it. */
-export const coverageGaps = (found, shown) => {
+const day = (at) => at?.slice(0, 10) ?? "no date";
+/**
+ * The steps for chats the store holds only in part. Bounded first, when the answer's window is known, then the whole
+ * chat; both name the first chat only, because a download is the owner's call. Counts and dates only, never text.
+ */
+const chatGaps = (rows, since) => {
+    const open = rows.filter(({ completeness }) => completeness.state !== "complete");
+    const [first] = open;
+    if (!first)
+        return { next: [], missing: [] };
+    const held = first.completeness.state === "unknown" ? "never fetched" : `held from ${day(first.held.oldestAt)} only`;
+    const steps = (args, why) => ({
+        ...nextStep("messages.sync", { args: { chat: first.chatId, ...args } }),
+        why,
+    });
+    return {
+        next: [
+            ...(since === undefined ? [] : [steps({ since_time: since }, `${held}; this reads back to ${day(since)}`)]),
+            steps({}, "reads the chat back to its first message; a big group can take minutes"),
+        ],
+        missing: [
+            {
+                field: "history",
+                why: `${open.length} of ${rows.length} chats hold only part of their history; the first is ${held}`,
+                step: "messages.sync",
+            },
+        ],
+    };
+};
+/**
+ * What the archive lacked for this answer, and the step that would fill it. From a search's coverage, or from the
+ * chats an answer is about (`since` is the start of the window it was asked for).
+ */
+export const coverageGaps = (found, shown = 0, since) => {
+    if (Array.isArray(found))
+        return chatGaps(found, since);
     const coverage = found.coverage;
     const stale = found.refreshed?.complete === false;
     if (!coverage?.next && !stale)
@@ -203,7 +237,7 @@ export const messagesAnswer = (command, found, { limit, page, again }, query = "
         page: page ?? 1,
         ...(again ? { args: again } : {}),
         ...gapsOf(found),
-        meta: metaOf(accounts, found.skipped),
+        meta: metaOf(accounts, found.skipped, coverageGaps(found).missing.length > 0),
     });
 };
 /**
@@ -272,6 +306,7 @@ export const allAnswer = (command, found, { limit, page, again }, exact = false)
     const scan = found.meetings?.complete === false ? found.meetings : undefined;
     const notes = meaningGap(found.notes?.meaningSkipped, exact);
     const messages = messageMeaningGap(found.messages?.meaningSkipped, "found_by");
+    const archive = coverageGaps({ coverage: found.coverage }, found.items.length);
     return listOf(command, {
         items: found.items.map(allHitItem),
         limit,
@@ -290,6 +325,7 @@ export const allAnswer = (command, found, { limit, page, again }, exact = false)
                 : []),
             ...notes.next,
             ...messages.next.filter((step) => !notes.next.some((asked) => JSON.stringify(asked) === JSON.stringify(step))),
+            ...archive.next,
         ],
         missing: [
             ...(scan
@@ -303,7 +339,8 @@ export const allAnswer = (command, found, { limit, page, again }, exact = false)
                 : []),
             ...notes.missing,
             ...messages.missing,
+            ...archive.missing,
         ],
-        meta: metaOf(found.accounts, found.skipped),
+        meta: metaOf(found.accounts, found.skipped, archive.missing.length > 0),
     });
 };

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

@@ -15,6 +15,7 @@ import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { listQuery, pagedList, pageOf, queryTerms, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
+import { coverageGaps } from "./search-answers.js";
 import { refuseJsonl, taskStatsAnswer } from "./stats-answers.js";
 const line = ({ id, key, state, kind, group, createdAt, message, note }) => [
     key ?? id.slice(0, 8),
@@ -50,10 +51,16 @@ const applyText = (pass, yes, tool) => yes
         ...pass.tasks.map((task) => `  ${task.kind.padEnd(8)} ${(task.category ?? "—").padEnd(13)} ${task.source}`),
         ...(pass.tasks.length > 0 ? [`  ${tool} tasks scan ${pass.chat} --yes opens them`] : []),
     ].join("\n");
+const agendaChats = (agenda) => [...agenda.unsynced, ...agenda.owed, ...agenda.waiting];
+const agendaGaps = (agenda) => coverageGaps(agendaChats(agenda).map(({ coverage }) => coverage), 0, agenda.since);
+const STATE_MARK = { complete: "", partial: "  [partial]", unknown: "  [never fetched]" };
 const agendaText = (agenda) => {
     const chat = (one) => `  ${when(one.lastMessageAt)}  ${one.title ?? one.chatId}  ${one.lastMessage ?? one.chatId}` +
-        (one.openTasks.length > 0 ? `  (${one.openTasks.length} open)` : "");
+        (one.openTasks.length > 0 ? `  (${one.openTasks.length} open)` : "") +
+        STATE_MARK[one.coverage.completeness.state];
+    const [history] = agendaGaps(agenda).missing;
     return [
+        ...(history ? [`${history.why}: sync before trusting what is listed`] : []),
         ...(agenda.stale
             ? [`the store saved nothing since ${when(agenda.storedAt)}: sync before trusting quiet chats`]
             : []),
@@ -356,7 +363,11 @@ export const tasksCommand = (messenger) => {
         const unmerged = await context.withServices((services) => services.tasks.unmerge(dup, writerOf(this)));
         renderAnswer(this, context, itemOf(snakeKeys(unmerged)), () => `${card(unmerged.task)}\n`);
     });
-    withQuery(annotate(tasks.command("agenda"), { effects: LOCAL_READ, examples: [`${tool} personal tasks agenda`] })
+    withQuery(annotate(tasks.command("agenda"), {
+        effects: LOCAL_READ,
+        partial: true,
+        examples: [`${tool} personal tasks agenda`],
+    })
         .summary("what needs a look today: tasks due, chats you owe or wait on, what you are owed")
         .description("what needs a look today, from the local store and without message text: tasks overdue, due or to check, " +
         "chats where you owe an answer, chats where you wait for one, open tasks someone else does"), AGENDA_QUERY)
@@ -377,7 +388,8 @@ export const tasksCommand = (messenger) => {
             ...(query ? { query } : {}),
             holder: holderOf(this),
         }));
-        renderAnswer(this, context, itemOf(agendaItem(agenda)), () => `${agendaText(agenda)}\n`);
+        const { next, missing } = agendaGaps(agenda);
+        renderAnswer(this, context, itemOf(agendaItem(agenda), { next, missing, ...(missing.length > 0 ? { meta: { complete: false } } : {}) }), () => `${agendaText(agenda)}\n`);
     });
     annotate(tasks.command("categories"), {
         output: { entity: "task_categories" },

package/dist/cli/steps.js

@@ -14,6 +14,7 @@ export const STEPS = defineSteps([
         args: [
             { name: "chat", required: false },
             { name: "all", required: false },
+            { name: "since_time", required: false },
             { name: "background", required: false },
         ],
         why: "the local copy is missing messages; syncing brings them in",

package/dist/entities/agenda.d.ts

@@ -42,6 +42,20 @@ export declare const agenda: v.StrictObjectSchema<{
         readonly last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
         /** Open tasks whose source is in this chat. */
         readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        /** `unknown` means nothing ever fetched the chat's history; `partial` that the store holds only part of it. */
+        readonly completeness: v.StrictObjectSchema<{
+            readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+            readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly gaps: v.BooleanSchema<undefined>;
+            readonly reaches_start: v.BooleanSchema<undefined>;
+            readonly fetched_at: v.NullableSchema<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>;
+        }, undefined>;
+        /** What the store holds of the chat: the count and the span, never the text. */
+        readonly held: v.StrictObjectSchema<{
+            readonly messages: v.NumberSchema<undefined>;
+            readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+        }, undefined>;
     }, undefined>, undefined>;
     /** The owner wrote last, and nobody answered. */
     readonly waiting: v.ArraySchema<v.StrictObjectSchema<{
@@ -55,6 +69,20 @@ export declare const agenda: v.StrictObjectSchema<{
         readonly last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
         /** Open tasks whose source is in this chat. */
         readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        /** `unknown` means nothing ever fetched the chat's history; `partial` that the store holds only part of it. */
+        readonly completeness: v.StrictObjectSchema<{
+            readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+            readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly gaps: v.BooleanSchema<undefined>;
+            readonly reaches_start: v.BooleanSchema<undefined>;
+            readonly fetched_at: v.NullableSchema<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>;
+        }, undefined>;
+        /** What the store holds of the chat: the count and the span, never the text. */
+        readonly held: v.StrictObjectSchema<{
+            readonly messages: v.NumberSchema<undefined>;
+            readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+        }, undefined>;
     }, undefined>, undefined>;
     /** The chat list says these moved and their newest message is not stored: read them first. */
     readonly unsynced: v.ArraySchema<v.StrictObjectSchema<{
@@ -68,6 +96,20 @@ export declare const agenda: v.StrictObjectSchema<{
         readonly last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
         /** Open tasks whose source is in this chat. */
         readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        /** `unknown` means nothing ever fetched the chat's history; `partial` that the store holds only part of it. */
+        readonly completeness: v.StrictObjectSchema<{
+            readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+            readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly gaps: v.BooleanSchema<undefined>;
+            readonly reaches_start: v.BooleanSchema<undefined>;
+            readonly fetched_at: v.NullableSchema<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>;
+        }, undefined>;
+        /** What the store holds of the chat: the count and the span, never the text. */
+        readonly held: v.StrictObjectSchema<{
+            readonly messages: v.NumberSchema<undefined>;
+            readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+        }, undefined>;
     }, undefined>, undefined>;
     /** Open tasks someone else does: what they owe the owner, oldest first. */
     readonly assigned: v.ArraySchema<v.StrictObjectSchema<{

package/dist/entities/agenda.js

@@ -13,6 +13,16 @@ const agendaChat = v.strictObject({
     last_from_owner: v.nullable(v.boolean()),
     /** Open tasks whose source is in this chat. */
     open_tasks: v.array(id),
+    /** `unknown` means nothing ever fetched the chat's history; `partial` that the store holds only part of it. */
+    completeness: v.strictObject({
+        state: v.picklist(["complete", "partial", "unknown"]),
+        up_to_date: v.nullable(v.boolean()),
+        gaps: v.boolean(),
+        reaches_start: v.boolean(),
+        fetched_at: v.nullable(time),
+    }),
+    /** What the store holds of the chat: the count and the span, never the text. */
+    held: v.strictObject({ messages: v.number(), oldest_at: v.nullable(time), newest_at: v.nullable(time) }),
 });
 /** What needs a look today, from the store alone and without one message's text. */
 export const agenda = v.strictObject({

package/dist/entities/index.d.ts

@@ -9614,6 +9614,18 @@ export declare const ENTITIES: {
             readonly last_message_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 last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
             readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+            readonly completeness: v.StrictObjectSchema<{
+                readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+                readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+                readonly gaps: v.BooleanSchema<undefined>;
+                readonly reaches_start: v.BooleanSchema<undefined>;
+                readonly fetched_at: v.NullableSchema<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>;
+            }, undefined>;
+            readonly held: v.StrictObjectSchema<{
+                readonly messages: v.NumberSchema<undefined>;
+                readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+            }, undefined>;
         }, undefined>, undefined>;
         readonly waiting: v.ArraySchema<v.StrictObjectSchema<{
             readonly chat: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -9623,6 +9635,18 @@ export declare const ENTITIES: {
             readonly last_message_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 last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
             readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+            readonly completeness: v.StrictObjectSchema<{
+                readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+                readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+                readonly gaps: v.BooleanSchema<undefined>;
+                readonly reaches_start: v.BooleanSchema<undefined>;
+                readonly fetched_at: v.NullableSchema<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>;
+            }, undefined>;
+            readonly held: v.StrictObjectSchema<{
+                readonly messages: v.NumberSchema<undefined>;
+                readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+            }, undefined>;
         }, undefined>, undefined>;
         readonly unsynced: v.ArraySchema<v.StrictObjectSchema<{
             readonly chat: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -9632,6 +9656,18 @@ export declare const ENTITIES: {
             readonly last_message_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 last_from_owner: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
             readonly open_tasks: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+            readonly completeness: v.StrictObjectSchema<{
+                readonly state: v.PicklistSchema<["complete", "partial", "unknown"], undefined>;
+                readonly up_to_date: v.NullableSchema<v.BooleanSchema<undefined>, undefined>;
+                readonly gaps: v.BooleanSchema<undefined>;
+                readonly reaches_start: v.BooleanSchema<undefined>;
+                readonly fetched_at: v.NullableSchema<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>;
+            }, undefined>;
+            readonly held: v.StrictObjectSchema<{
+                readonly messages: v.NumberSchema<undefined>;
+                readonly oldest_at: v.NullableSchema<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 newest_at: v.NullableSchema<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>;
+            }, undefined>;
         }, undefined>, undefined>;
         readonly assigned: v.ArraySchema<v.StrictObjectSchema<{
             readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;

package/dist/services/agenda.d.ts

@@ -2,6 +2,7 @@ import { type QueryAst } from "@wirecat/cli-base/query";
 import type * as v from "valibot";
 import { agenda } from "../entities/agenda.js";
 import { type ChatActivity, type TaskDetails } from "../store/store.js";
+import { type ChatCoverage } from "./chat-coverage.js";
 import type { ServiceDeps } from "./deps.js";
 export interface AgendaOptions {
     /** ms: a task due within this is listed. */
@@ -33,6 +34,8 @@ export interface AgendaAssigned extends Pick<TaskDetails, "id" | "key" | "title"
     assignees: string[];
 }
 export interface AgendaChat extends Omit<ChatActivity, "lastMessageId"> {
+    /** How much of the chat's history the store holds: a chat held from last week alone is not a quiet chat. */
+    coverage: ChatCoverage;
     /** The newest message, as a locator to read around; never its text. `null` while it is not stored. */
     lastMessage: string | null;
     /** Open tasks whose source is in this chat. */
@@ -45,6 +48,8 @@ export interface AgendaChat extends Omit<ChatActivity, "lastMessageId"> {
  */
 export interface Agenda {
     at: string;
+    /** The start of the window the chats were read for (`within`). */
+    since: string;
     account: string;
     storedAt: string | null;
     stale: boolean;

package/dist/services/agenda.js

@@ -3,6 +3,7 @@ import { formatLocator, isLocator, parseLocator } from "../domain/locator.js";
 import { formatReference } from "../domain/references.js";
 import { agenda } from "../entities/agenda.js";
 import { AGENDA_COLUMNS, inboxKey, queryFilter, } from "../store/store.js";
+import { chatCoverage } from "./chat-coverage.js";
 import { CHAT_KINDS } from "./chats.js";
 import { taskAccount } from "./task-rules.js";
 import { taskTagFilters } from "./task-tag-filters.js";
@@ -102,21 +103,29 @@ export const agendaService = (deps, now = Date.now) => ({
                 }),
             openTasks: open.filter((task) => chatOf(task.source) === chat.chatId).map((task) => task.id),
         }));
+        const silentFor = (chat) => at - Date.parse(chat.lastMessageAt);
+        const shown = {
+            owed: chats.filter((chat) => chat.lastFromOwner === false && silentFor(chat) >= unanswered),
+            waiting: chats.filter((chat) => chat.lastFromOwner === true && silentFor(chat) >= waiting),
+            unsynced: chats.filter((chat) => chat.lastMessage === null),
+        };
+        const covered = new Map((await chatCoverage(store, account, Object.values(shown).flatMap((list) => list.map(({ chatId }) => chatId)))).map((one) => [one.chatId, one]));
+        const withCoverage = (list) => list.map((chat) => ({ ...chat, coverage: covered.get(chat.chatId) }));
         const inList = new Set((await store.tasks.categories()).map(({ name }) => name));
         const unlisted = new Map();
         for (const { category } of open)
             if (category && !inList.has(category))
                 unlisted.set(category, (unlisted.get(category) ?? 0) + 1);
-        const silentFor = (chat) => at - Date.parse(chat.lastMessageAt);
         return {
             at: new Date(at).toISOString(),
+            since: new Date(at - within).toISOString(),
             account: taskAccount(account),
             storedAt: activity.storedAt,
             stale: activity.storedAt === null || at - Date.parse(activity.storedAt) > DAY,
             tasks,
-            owed: chats.filter((chat) => chat.lastFromOwner === false && silentFor(chat) >= unanswered),
-            waiting: chats.filter((chat) => chat.lastFromOwner === true && silentFor(chat) >= waiting),
-            unsynced: chats.filter((chat) => chat.lastMessage === null),
+            owed: withCoverage(shown.owed),
+            waiting: withCoverage(shown.waiting),
+            unsynced: withCoverage(shown.unsynced),
             assigned,
             unlistedCategories: [...unlisted].sort().map(([name, openTasks]) => ({ name, openTasks })),
         };
@@ -208,6 +217,18 @@ export const agendaItem = (shown) => {
         last_message_at: one.lastMessageAt,
         last_from_owner: one.lastFromOwner,
         open_tasks: one.openTasks,
+        completeness: {
+            state: one.coverage.completeness.state,
+            up_to_date: one.coverage.completeness.upToDate,
+            gaps: one.coverage.completeness.gaps,
+            reaches_start: one.coverage.completeness.reachesStart,
+            fetched_at: one.coverage.completeness.fetchedAt,
+        },
+        held: {
+            messages: one.coverage.held.messages,
+            oldest_at: one.coverage.held.oldestAt,
+            newest_at: one.coverage.held.newestAt,
+        },
     });
     return {
         at: shown.at,

package/dist/services/chat-coverage.d.ts

@@ -0,0 +1,19 @@
+import type { Id } from "../domain/models.js";
+import type { AccountKey, ChatCompleteness, MessageStore } from "../store/store.js";
+/** What the store holds of one chat, and how far that goes: never message text. */
+export interface ChatCoverage {
+    chatId: Id;
+    /** `null` while the store holds no message of the chat: titles come with the stats. */
+    title: string | null;
+    completeness: ChatCompleteness;
+    held: {
+        messages: number;
+        oldestAt: string | null;
+        newestAt: string | null;
+    };
+}
+/**
+ * Per chat, in the order asked: `chatCompleteness` with the span `chatStats` holds. Stats are read one chat at a time,
+ * because the account-wide read groups every message of every chat. A chat the store has no row for is `unknown`.
+ */
+export declare const chatCoverage: (store: Pick<MessageStore, "chats">, account: AccountKey, chatIds: Id[]) => Promise<ChatCoverage[]>;

package/dist/services/chat-coverage.js

@@ -0,0 +1,27 @@
+/**
+ * Per chat, in the order asked: `chatCompleteness` with the span `chatStats` holds. Stats are read one chat at a time,
+ * because the account-wide read groups every message of every chat. A chat the store has no row for is `unknown`.
+ */
+export const chatCoverage = async (store, account, chatIds) => {
+    const ids = [...new Set(chatIds)];
+    if (ids.length === 0)
+        return [];
+    const found = new Map((await store.chats.chatCompleteness(account, ids)).map((one) => [one.chatId, one]));
+    return Promise.all(ids.map(async (chatId) => {
+        const [stats] = await store.chats.chatStats(account, chatId);
+        const completeness = found.get(chatId) ?? {
+            chatId,
+            state: "unknown",
+            upToDate: null,
+            gaps: false,
+            reachesStart: false,
+            fetchedAt: null,
+        };
+        return {
+            chatId,
+            title: stats?.title ?? null,
+            completeness,
+            held: { messages: stats?.messages ?? 0, oldestAt: stats?.oldestAt ?? null, newestAt: stats?.newestAt ?? null },
+        };
+    }));
+};

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

@@ -4,6 +4,7 @@ import type { MessengerTraits } from "../ports/traits.js";
 import type { AccountKey, MessageStore } from "../store/store.js";
 import type { SearchFound, SearchQuery } from "./messages.js";
 import { type MeaningLane, type MeaningSkipped } from "./messages-discovery.js";
+import type { SearchCoverage } from "./messages-search.js";
 import type { Backend, ServerOptions, ServerSearched } from "./server-search.js";
 export declare const RESOURCES_SEARCHED: readonly ["messages", "mail", "notes", "events"];
 export type SearchedResource = (typeof RESOURCES_SEARCHED)[number];
@@ -77,6 +78,8 @@ export interface SearchAllFound {
     };
     /** The messenger's server step for messages, as `search messages` reports it. */
     server?: ServerSearched;
+    /** What the store held of the chats the messages were searched in; absent when messages were not searched. */
+    coverage?: SearchCoverage;
 }
 export interface SearchAllRequest {
     text: string;

package/dist/services/search-all.js

@@ -53,6 +53,7 @@ export const searchAll = async (store, account, request, messenger = {}, searchM
     let events;
     let messagesBy;
     let server;
+    let coverage;
     const messagesOf = async (kind) => {
         const given = request.scope?.[kind];
         const query = {
@@ -76,6 +77,8 @@ export const searchAll = async (store, account, request, messenger = {}, searchM
         const found = kind === "messages" ? await searchMessages(query) : await searchStore(store, account, query, messenger);
         if (found.server)
             server = found.server;
+        if (kind === "messages" && found.coverage)
+            coverage = found.coverage;
         hasMore ||= found.hasMore;
         const read = found.coverage?.accounts ??
             given ??
@@ -243,5 +246,6 @@ export const searchAll = async (store, account, request, messenger = {}, searchM
         ...(events === undefined ? {} : { events }),
         ...(messagesBy === undefined ? {} : { messages: messagesBy }),
         ...(server === undefined ? {} : { server }),
+        ...(coverage === undefined ? {} : { coverage }),
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.492.0",
+  "version": "0.493.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",