@wirecat/cli-core 0.382.0 → 0.384.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.384.0 — 22.10.2026
+
+### Added
+
+- **More commands say how they read a typed date** (WC-TIME-3, WC-TIME-5): `meta.window` gives the UTC bounds they
+  used, and `meta.timezone` names the zone a value without its own zone was read in. Now: `moderate` (the bot's and
+  the admin's), the bot's `store fetch`, `store export`, `messages sync`, `stats chats show`, `contacts context`,
+  `search conversations`, `replies test` (its 7-day default window too), `runs search`, `stats chats retention`, the
+  administrator reports (`stats messages unanswered`, `stats contacts responses`, `stats chats newcomers`,
+  `stats messages discussion`), `search meetings` (also in `meetings batch`; over MCP only the window, since it takes
+  epoch times), and a `time:` or `date:` term in `chats events`, `chats members history`, `inbox` and `review`.
+  `search conversations` now reads a date alone in its `--timezone` when one is given. A host of `search meetings`
+  passes `meetingSearchMeta(options)` to `meetingHitsList` to report the same.
+
+## 0.383.0 — 22.10.2026
+
+### Added
+
+- **`readSpreadsheet(bytes, "xlsx" | "ods")` from `@wirecat/cli-core/documents`** returns a workbook's cells per
+  worksheet (values as displayed), the same reader text extraction uses, so a provider can mirror a workbook's tabs.
+- **Push local files into a provider as native documents (`@wirecat/cli-core/documents`).** `pushDocuments` mirrors
+  a local folder one way through a provider's `DocumentTarget`: new files are created, changed files updated, and
+  unchanged files skipped by content hash with no remote call. Before a create it saves a pending origin key, so a
+  crash after the provider wrote finds the file (`findByOrigin`) instead of creating a duplicate. The provider's
+  `prepare` compares the remote with the last push before writing; a remote copy changed since then is a conflict
+  unless `force`, and only the `write` step passes the guard. A local delete is reported as an
+  orphan and nothing is ever deleted remotely. `planPush` is the pure plan behind `dryRun`; `scanLocal` skips hidden
+  files, editor leftovers and symbolic links. Every write passes through the caller's `guard` with its own operation
+  id. For documents with structure, `markdownBlocks` (async, its parser loaded on first use) parses Markdown (CommonMark and GFM tables, task lists,
+  strikethrough) into `Block`s a provider writes natively, `diffBlocks` gives the edits that leave unchanged blocks
+  in place, and `reconcileBlocks` lets a checklist tick change on either side without a conflict. See
+  [documents](docs/dev/DOCUMENTS.md#push-local-files-to-a-provider).
+
 ## 0.382.0 — 22.10.2026
 
 ### Added

package/dist/attachments/documents.d.ts

@@ -1,6 +1,9 @@
 import type { Extraction, FileHint } from "../readers/types.js";
+import { type Sheet } from "./sheets.js";
 export type DocumentKind = "odt" | "ods" | "odp" | "xlsx" | "pptx" | "epub";
 export declare const documentKind: (hint: FileHint) => DocumentKind | undefined;
 /** v2 for spreadsheets: rows under their header instead of one line per cell, so older text is read again. */
 export declare const documentExtractor: (kind: DocumentKind) => string;
+/** The cells of an XLSX or ODS workbook, one `Sheet` per worksheet in workbook order, values as displayed. */
+export declare const readSpreadsheet: (bytes: Uint8Array, kind: "xlsx" | "ods", signal?: AbortSignal) => Promise<Sheet[]>;
 export declare const readDocument: (bytes: Uint8Array, kind: DocumentKind, signal?: AbortSignal) => Promise<Extraction>;

package/dist/attachments/documents.js

@@ -393,6 +393,23 @@ const readBook = (archive, output) => {
         visit(bodies[0]);
     }
 };
+/** The cells of an XLSX or ODS workbook, one `Sheet` per worksheet in workbook order, values as displayed. */
+export const readSpreadsheet = async (bytes, kind, signal) => {
+    try {
+        const archive = await readContainer(bytes, signal);
+        const sheets = kind === "xlsx" ? readSheet(archive) : readOdf(archive, kind, new Output());
+        if (!sheets)
+            throw new Error("wrong_format");
+        return sheets;
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("validation_error", `the ${kind.toUpperCase()} workbook could not be read`, {
+            reason: "spreadsheet.unreadable",
+        });
+    }
+};
 export const readDocument = async (bytes, kind, signal) => {
     const extractor = documentExtractor(kind);
     try {

package/dist/cli/bot/moderation.js

@@ -7,7 +7,7 @@ import { defaultRules, ModerationRules, moderationPathFor, RULE_KEYS } from "../
 import { moderateWith } from "../../moderation/run.js";
 import { guardedWrite } from "../../sends/guarded.js";
 import { newOperationId } from "../../sends/send-id.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { environmentOf } from "../context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, ownerOnlyOption, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -155,6 +155,7 @@ export const botModerateCommand = (bot) => annotate(new Command("moderate"), { e
     // An in-process caller's answer counts under --json too: it is not a terminal that could wait for ever.
     const given = environmentOf(this).answer;
     const ask = async (question) => (given ? await given(question) : await answerOf(this, question));
+    const window = dateWindow(options.sinceTime === undefined ? {} : { sinceTime: options.sinceTime });
     await context.run(async (events) => {
         const adapter = await context.authenticated({ events });
         const botId = await botIdOf(context, adapter);
@@ -169,7 +170,7 @@ export const botModerateCommand = (bot) => annotate(new Command("moderate"), { e
             commandFor: (group, finding) => finding.action === "delete"
                 ? `${context.words} messages delete ${group} ${finding.messageId} --allow-dangerous`
                 : `${context.words} chats members remove ${group} ${finding.personId}`,
-            ...(options.sinceTime === undefined ? {} : { since: momentOf(options.sinceTime, "--since-time") }),
+            ...(window.since === undefined ? {} : { since: window.since }),
             dryRun: options.dryRun === true,
             allowDangerous: options.allowDangerous === true,
             maxActions,
@@ -188,7 +189,7 @@ export const botModerateCommand = (bot) => annotate(new Command("moderate"), { e
                 ...(row.reason ? { why: row.reason } : {}),
             })));
         else
-            renderAnswer(this, context, itemOf({ chat_id: chatId, rows: snakeKeys(rows) }));
+            renderAnswer(this, context, itemOf({ chat_id: chatId, rows: snakeKeys(rows) }, { meta: window.meta }));
         for (const note of notes)
             context.renderer.note(note);
     });

package/dist/cli/bot/store.js

@@ -3,9 +3,9 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { parseDuration } from "../../domain/duration.js";
 import { fetchInto } from "../../services/archive.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { FETCH } from "../effects.js";
-import { renderItem } from "../messenger/chat-answers.js";
+import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { stopOnSignal } from "../messenger/patience.js";
 import { botContext, online } from "./context.js";
 import { botCan, botIdOf } from "./messages.js";
@@ -37,7 +37,8 @@ export const botStoreCommand = (bot, fetching) => {
             throw new CliError("validation_error", "give --since-time or --last, not both: how far back the fetch goes");
         }
         const pauseMs = parseDuration(options.pause, "--pause");
-        const sinceMs = options.sinceTime === undefined ? undefined : momentOf(options.sinceTime, "--since-time");
+        const bounds = dateWindow(options.sinceTime === undefined ? {} : { sinceTime: options.sinceTime });
+        const sinceMs = bounds.since;
         const context = online(botContext(this, bot), this);
         const ref = context.chatRef(chat);
         const stop = stopOnSignal(this);
@@ -73,7 +74,7 @@ export const botStoreCommand = (bot, fetching) => {
                         stop: stop.signal,
                         onPage: () => { },
                     }));
-                    renderItem(this, context, result);
+                    renderAnswer(this, context, itemOf(snakeKeys(result), { meta: bounds.meta }));
                 }
                 finally {
                     await adapter.close();

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

@@ -44,10 +44,20 @@ export declare const nativeTerms: (ast: QueryAst | undefined, command: string) =
  * as validation already accepts them. A range or wildcard is refused rather than read as a value.
  */
 export declare const queryTerms: (words: QueryWords, registry: QueryRegistry, command: string) => Map<string, string>;
-/** A `time` term as epoch ms bounds: `time>=7d`, `time:[2026-10-01 TO 2026-10-07]`, `time:today`. */
+/**
+ * A `time` term as epoch ms bounds: `time>=7d`, `time:[2026-10-01 TO 2026-10-07]`, `time:today`, and the `meta`
+ * an answer reports them by: the zone calendar words and bare dates were read in, and the bounds in UTC.
+ */
 export declare const timeBounds: (term: Predicate | undefined, zone?: string) => {
     since?: number;
     until?: number;
+    meta?: {
+        timezone: string;
+        window: {
+            since?: string;
+            until?: string;
+        };
+    };
 };
 /** A text term as the plain words a provider searches by: `name:ana`, `name:"Ana K"`, `name:*ana*`. */
 export declare const searchText: (term: Predicate | undefined) => string | undefined;

package/dist/cli/list-query.js

@@ -130,7 +130,10 @@ export const queryTerms = (words, registry, command) => {
     }
     return terms;
 };
-/** A `time` term as epoch ms bounds: `time>=7d`, `time:[2026-10-01 TO 2026-10-07]`, `time:today`. */
+/**
+ * A `time` term as epoch ms bounds: `time>=7d`, `time:[2026-10-01 TO 2026-10-07]`, `time:today`, and the `meta`
+ * an answer reports them by: the zone calendar words and bare dates were read in, and the bounds in UTC.
+ */
 export const timeBounds = (term, zone = timezoneOf()) => {
     if (!term)
         return {};
@@ -139,6 +142,13 @@ export const timeBounds = (term, zone = timezoneOf()) => {
     return {
         ...(range.lower === undefined ? {} : { since: range.lower }),
         ...(range.upper === undefined ? {} : { until: range.upper }),
+        meta: {
+            timezone: zone,
+            window: {
+                ...(range.lower === undefined ? {} : { since: new Date(range.lower).toISOString() }),
+                ...(range.upper === undefined ? {} : { until: new Date(range.upper).toISOString() }),
+            },
+        },
     };
 };
 /** A text term as the plain words a provider searches by: `name:ana`, `name:"Ana K"`, `name:*ana*`. */

package/dist/cli/meeting-batch.js

@@ -2,7 +2,7 @@ import { BATCH_LIMITS, CliError, prepareBatch, runBatch, } from "@wirecat/cli-ba
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command, Option } from "commander";
 import { failureContext } from "../errors/reasons.js";
-import { createMeetingPassageCommand, createMeetingSearchCommand, meetingHitSearchRequest, meetingPassageRequest, meetingSearchArguments, } from "../meetings/cli/index.js";
+import { createMeetingPassageCommand, createMeetingSearchCommand, meetingHitSearchRequest, meetingPassageRequest, meetingSearchArguments, meetingSearchMeta, } from "../meetings/cli/index.js";
 import { meetingHitsList, parseMeetingReference, } from "../meetings/index.js";
 import { formatMeetingEvidenceText, formatMeetingPassage } from "../services/meeting-passage-format.js";
 import { itemOf, listOf } from "./envelope.js";
@@ -48,6 +48,7 @@ const handlers = (reader, meta) => {
                             ...meetingHitsList(found, request.limit ?? 100, "search meetings", meetingSearchArguments(query, flags)),
                             meta: {
                                 ...meta(),
+                                ...meetingSearchMeta(flags),
                                 complete,
                                 ...(!complete ? { issues: [{ code: "invalid_response", source: "meeting-index" }] } : {}),
                             },

package/dist/cli/messenger/admin-moderation-command.js

@@ -3,7 +3,7 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { describe, MAX_ACTIONS } from "../../moderation/check.js";
 import { RULE_KEYS } from "../../moderation/rules.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { answerOf } from "./ask.js";
@@ -57,8 +57,9 @@ export const moderateCommand = (messenger) => annotate(new Command("moderate"),
     if (!Number.isInteger(maxActions) || maxActions < 0) {
         throw new CliError("validation_error", `--max-actions takes a whole number — got ${String(options.maxActions)}`);
     }
+    const window = dateWindow(options.sinceTime === undefined ? {} : { sinceTime: options.sinceTime });
     const { chatId, rows, notes } = await context.withServices((services) => services.moderation.moderate(chat, {
-        ...(options.sinceTime === undefined ? {} : { since: momentOf(options.sinceTime, "--since-time") }),
+        ...(window.since === undefined ? {} : { since: window.since }),
         dryRun: options.dryRun === true,
         allowDangerous: options.allowDangerous === true,
         maxActions,
@@ -69,7 +70,7 @@ export const moderateCommand = (messenger) => annotate(new Command("moderate"),
             return /^\s*y(es)?\s*$/i.test(answer);
         },
     }));
-    renderAnswer(this, context, itemOf(snakeKeys({ chatId, rows })), () => rows
+    renderAnswer(this, context, itemOf(snakeKeys({ chatId, rows }), { meta: window.meta }), () => rows
         .map((row) => [row.kind, row.personName ?? row.personId, row.rule, row.action, row.outcome, row.reason ?? ""]
         .join("  ")
         .trimEnd())

package/dist/cli/messenger/archive-commands.js

@@ -9,7 +9,7 @@ import { renderMessages } from "../../render/messages.js";
 import { seal } from "../../sealed.js";
 import { CHAT_KINDS } from "../../services/chats.js";
 import { kindsOf } from "../../services/inbox.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { jobsCommand } from "./backfill-command.js";
@@ -185,7 +185,8 @@ const exportCommand = (messenger) => destroysNothing(annotate(new Command("expor
     }
     const password = encrypt ? await passwordOf(this, { twice: true }) : undefined;
     const chat = chats[0];
-    const from = since === undefined ? undefined : new Date(momentOf(since, "--since-time")).toISOString();
+    const window = dateWindow(since === undefined ? {} : { sinceTime: since });
+    const from = window.since === undefined ? undefined : new Date(window.since).toISOString();
     const { account, title, messages } = await context.withServices((services) => services.archive.export(chat, from === undefined ? {} : { since: from }));
     if (output !== undefined) {
         const path = resolve(output);
@@ -210,7 +211,7 @@ const exportCommand = (messenger) => destroysNothing(annotate(new Command("expor
             format: format ?? "jsonl",
             count: messages.length,
             ...(password === undefined ? {} : { encrypted: true }),
-        }));
+        }, { meta: window.meta }));
         return;
     }
     if (format === "markdown")
@@ -223,6 +224,7 @@ const exportCommand = (messenger) => destroysNothing(annotate(new Command("expor
             items: messageItems(messages, account),
             limit: Math.max(1, messages.length),
             has_more: false,
+            meta: window.meta,
         }));
     else
         context.streams.data(renderMessages(messages, {

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

@@ -9,7 +9,7 @@ import { isCliFailure } from "../../errors/failures.js";
 import { envName } from "../../ports/app.js";
 import { FETCHING } from "../../services/archive.js";
 import { JOBS_QUERY, jobItems } from "../../services/job-query.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { validateCatchUpBounds } from "../../services/search-catchup.js";
 import { applyTaskRulesSinceLastPass } from "../../services/task-rules.js";
 import { environmentOf } from "../context.js";
@@ -72,8 +72,9 @@ export const syncCommand = (messenger) => {
         }
         const limit = sizes.limit ?? fetching.maxPages * fetching.page;
         const pauseMs = parseDuration(pause, "--pause");
-        const window = since ?? (all && last === undefined ? ALL_SINCE : undefined);
-        const sinceMs = window === undefined ? undefined : momentOf(window, "--since-time");
+        const from = since ?? (all && last === undefined ? ALL_SINCE : undefined);
+        const window = dateWindow(from === undefined ? {} : { sinceTime: from });
+        const sinceMs = window.since;
         const context = messengerContext(this, messenger);
         const prepare = catchUp ?? context.settings.searchCatchUp ?? false;
         const preparation = {
@@ -123,7 +124,10 @@ export const syncCommand = (messenger) => {
                 pageSize,
                 ...(last === undefined ? {} : { last }),
             });
-            renderAnswer(this, context, itemOf(snakeKeys(started), { next: [nextStep("store.job", { args: { job: started.job } })] }));
+            renderAnswer(this, context, itemOf(snakeKeys(started), {
+                next: [nextStep("store.job", { args: { job: started.job } })],
+                meta: window.meta,
+            }));
             return;
         }
         const jobs = jobsDir(messenger.app, context.env);
@@ -164,6 +168,7 @@ export const syncCommand = (messenger) => {
                         : []),
                     ...(toReview > 0 ? [nextStep("mentions.review", { args: { new: true }, values: { shown } })] : []),
                 ],
+                meta: window.meta,
             }));
             if (tasks?.held)
                 context.renderer.note(`the first sync left ${tasks.held} possible task(s) in ${tasks.heldChats ?? 0} chat(s) unopened ` +

package/dist/cli/messenger/catch-up-answers.d.ts

@@ -1,3 +1,4 @@
+import type { Meta } from "@wirecat/cli-base/standards";
 import type { Inbox, Review } from "../../domain/models.js";
 import { type Hearing } from "../../speech/hearing.js";
 import type { AccountKey } from "../../store/store.js";
@@ -10,8 +11,9 @@ export declare const REVIEW_QUERY: import("@wirecat/cli-base/query").QueryRegist
 export declare const catchUpQuery: (words: QueryWords, registry: typeof INBOX_QUERY, command: string) => {
     since?: number;
     chat?: string;
+    meta?: Partial<Meta>;
 };
-export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, reader: AccountKey, transcribe: boolean) => import("../envelope.js").ListBody<{
+export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, reader: AccountKey, transcribe: boolean, meta?: Partial<Meta>) => import("../envelope.js").ListBody<{
     ref: string;
     chat_id: string;
     chat_title: string | null | undefined;
@@ -51,10 +53,11 @@ export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, r
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
  * Saved points (`--new`) carry this themselves, and an `--unanswered` look is not a review to continue.
  */
-export declare const reviewAnswer: (found: Review, hearing: Hearing | undefined, reader: AccountKey, { transcribe, fresh, chat }: {
+export declare const reviewAnswer: (found: Review, hearing: Hearing | undefined, reader: AccountKey, { transcribe, fresh, chat, meta }: {
     transcribe: boolean;
     fresh: boolean;
     chat?: string;
+    meta?: Partial<Meta>;
 }) => import("../envelope.js").ListBody<{
     ref: string;
     chat_id: string;

package/dist/cli/messenger/catch-up-answers.js

@@ -17,13 +17,17 @@ export const REVIEW_QUERY = defineQuery({
 export const catchUpQuery = (words, registry, command) => {
     const terms = nativeTerms(listQuery(typedQuery(words), registry, command), command);
     const term = terms.get("date");
-    const { since, until } = timeBounds(term);
+    const { since, until, meta } = timeBounds(term);
     if (term && (until !== undefined || since === undefined))
         queryError("query.unsupported-operator", term.span, `${command} reads from a point on: date>2h, not an end`, {
             command,
         });
     const chat = terms.get("chat")?.value;
-    return { ...(since === undefined ? {} : { since }), ...(chat === undefined ? {} : { chat }) };
+    return {
+        ...(since === undefined ? {} : { since }),
+        ...(chat === undefined ? {} : { chat }),
+        ...(meta === undefined ? {} : { meta }),
+    };
 };
 const summaryOf = (message, reader) => {
     const { ref, chat_id, chat_title, timestamp, sender_name, outgoing, text, transcript, attachments } = messageItem(message, reader);
@@ -44,7 +48,7 @@ const nameOf = (chat) => chat.title ?? chat.id;
  * What every catch-up answer shares: the messages, oldest first, each naming its chat; what was left out as
  * `missing`; and a chat cut short as a `messages.list` step, after the steps the command puts first.
  */
-const catchUpList = (command, found, hearing, reader, { transcribe, first = [] }) => {
+const catchUpList = (command, found, hearing, reader, { transcribe, first = [], meta = {} }) => {
     const read = found.chats
         .flatMap((chat) => heard(chat.messages, hearing).map((message) => ({ ...message, chatTitle: chat.title })))
         .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
@@ -73,16 +77,16 @@ const catchUpList = (command, found, hearing, reader, { transcribe, first = [] }
         has_more: false,
         next: [...first, ...cut.map((chat) => nextStep("messages.list", { args: { chat: chat.id } }))],
         missing,
-        ...(found.partial ? { meta: { truncated: true } } : {}),
+        meta: { ...meta, ...(found.partial ? { truncated: true } : {}) },
     });
 };
-export const inboxAnswer = (inbox, hearing, reader, transcribe) => catchUpList("inbox", inbox, hearing, reader, { transcribe });
+export const inboxAnswer = (inbox, hearing, reader, transcribe, meta = {}) => catchUpList("inbox", inbox, hearing, reader, { transcribe, meta });
 const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 /**
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
  * Saved points (`--new`) carry this themselves, and an `--unanswered` look is not a review to continue.
  */
-export const reviewAnswer = (found, hearing, reader, { transcribe, fresh, chat }) => {
+export const reviewAnswer = (found, hearing, reader, { transcribe, fresh, chat, meta }) => {
     const continues = !fresh && found.unanswered === undefined;
     const query = [
         `date>${quoted(found.complete ? found.until : found.since)}`,
@@ -91,5 +95,6 @@ export const reviewAnswer = (found, hearing, reader, { transcribe, fresh, chat }
     return catchUpList("review", found, hearing, reader, {
         transcribe,
         first: continues ? [nextStep("review.next", { args: { query: query.join(" ") } })] : [],
+        ...(meta === undefined ? {} : { meta }),
     });
 };

package/dist/cli/messenger/chat-lists.js

@@ -18,9 +18,11 @@ export const chatsList = async (services, query, paging) => {
 };
 export const chatEvents = async (services, chat, query) => {
     const terms = nativeTerms(listQuery(typedQuery(query), EVENTS_QUERY, "chats events"), "chats events");
-    const { since } = timeBounds(terms.get("time"));
+    const { since, meta } = timeBounds(terms.get("time"));
     const found = await services.chats.events(chat, since === undefined ? {} : { since });
-    return wholeList("chats events", found.events.map((one) => chatEventAnswer(found.chatId, one)), found.more ? { meta: { truncated: true } } : {});
+    return wholeList("chats events", found.events.map((one) => chatEventAnswer(found.chatId, one)), {
+        meta: { ...meta, ...(found.more ? { truncated: true } : {}) },
+    });
 };
 export const membersList = async (services, chat, paging) => {
     const { limit, page, all } = paging;
@@ -33,11 +35,14 @@ export const membersList = async (services, chat, paging) => {
 };
 export const membersHistory = async (services, chat, query) => {
     const terms = nativeTerms(listQuery(typedQuery(query), HISTORY_QUERY, "chats members history"), "chats members history");
-    const { since } = timeBounds(terms.get("time"));
+    const { since, meta } = timeBounds(terms.get("time"));
     const found = await services.chats.memberHistory(chat, since === undefined ? {} : { since });
-    return wholeList("chats members history", found.events.map((one) => memberEventAnswer(found.chatId, one)), found.events.length === 0
-        ? { next: [nextStep("chats.members-fetch", { args: { chat: found.chatId, track: true } })] }
-        : {});
+    return wholeList("chats members history", found.events.map((one) => memberEventAnswer(found.chatId, one)), {
+        ...(found.events.length === 0
+            ? { next: [nextStep("chats.members-fetch", { args: { chat: found.chatId, track: true } })] }
+            : {}),
+        ...(meta ? { meta } : {}),
+    });
 };
 export const membersAudit = async (services, chat, query, options) => {
     const minScore = scoreFloor(listQuery(typedQuery(query), AUDIT_QUERY, "chats members audit"));

package/dist/cli/messenger/chats-stats-command.js

@@ -2,7 +2,7 @@ import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { EVENTS_DAYS } from "../../services/chats.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { messengerContext } from "./context.js";
@@ -19,13 +19,13 @@ export const statsCommand = (messenger) => annotate(new Command("show"), { effec
     const context = messengerContext(this, messenger);
     const { sinceTime, by, timezone } = this.opts();
     refuseJsonl(context.format);
+    const window = dateWindow({
+        ...(sinceTime === undefined ? {} : { sinceTime }),
+        ...(timezone === undefined ? {} : { zone: timezone }),
+    });
     const { stats, account } = await context.withServices(async (services) => ({
         stats: await services.chats.stats(chat, {
-            ...(sinceTime === undefined
-                ? {}
-                : {
-                    since: momentOf(sinceTime, "--since-time", Date.now(), timezone === undefined ? {} : { zone: timezone }),
-                }),
+            ...(window.since === undefined ? {} : { since: window.since }),
             ...(by ? { by } : {}),
             ...(timezone === undefined ? {} : { timezone }),
         }),
@@ -37,7 +37,7 @@ export const statsCommand = (messenger) => annotate(new Command("show"), { effec
         context.renderer.note("the messenger stopped reading joins and leaves before the period's start — those are lower bounds");
     if (!stats.members && !stats.membersUnrecorded)
         context.renderer.note("joins and leaves were not asked of the messenger");
-    renderAnswer(this, context, chatStatsAnswer(stats, account), () => view(stats));
+    renderAnswer(this, context, chatStatsAnswer(stats, account, window.meta), () => view(stats));
 });
 const view = (stats) => {
     const { questions, members } = stats;

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

@@ -4,7 +4,7 @@ import { Command } from "commander";
 import { REGISTRIES, registriesCover } from "../../botcheck/registries.js";
 import { levelFor } from "../../sends/permissions.js";
 import { phoneOf } from "../../services/index.js";
-import { dateWindow, momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { maskedAccount } from "../../services/people.js";
 import { CHAT_MESSAGES, CONTEXT_BYTES, CONTEXT_MESSAGES } from "../../services/person-context.js";
 import { SCOPES, TIMELINE_ITEMS } from "../../services/person-timeline.js";
@@ -119,10 +119,11 @@ export const contactsCommand = (messenger) => {
             }));
             return;
         }
+        const window = dateWindow(sinceTime === undefined ? {} : { sinceTime });
         const found = await context.withServices((services) => services.people.context(person, {
             messages: limit ?? CONTEXT_MESSAGES,
             bytes: CONTEXT_BYTES,
-            ...(sinceTime === undefined ? {} : { since: momentOf(sinceTime, "--since-time") }),
+            ...(window.since === undefined ? {} : { since: window.since }),
         }));
         const { hasMore, ...rest } = found;
         renderAnswer(this, context, itemOf(snakeKeys(rest), {
@@ -131,7 +132,7 @@ export const contactsCommand = (messenger) => {
                     .filter((chat) => chat.provider === messenger.provider)
                     .map((chat) => nextStep("messages.sync", { args: { chat: chat.chatId } }))
                 : [],
-            ...(hasMore ? { meta: { truncated: true } } : {}),
+            meta: { ...window.meta, ...(hasMore ? { truncated: true } : {}) },
         }));
         if (hasMore)
             context.renderer.note("cut at --limit; a larger one shows more");

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

@@ -1,4 +1,4 @@
-import type { Missing, NextStep } from "@wirecat/cli-base/standards";
+import type { Meta, Missing, NextStep } from "@wirecat/cli-base/standards";
 import type { Message } from "../../domain/models.js";
 import { type MessengerTraits } from "../../ports/traits.js";
 import type { ChatReadiness, FoundConversations, Refreshed } from "../../services/embeddings.js";
@@ -11,7 +11,7 @@ export declare const readinessGaps: ({ meaning, model, readiness, refreshed, cov
     missing: Missing[];
 };
 /** `search conversations` and `conversations related`, CLI and MCP alike. */
-export declare const foundConversations: (command: string, found: Readiness & Pick<FoundConversations, "hits" | "accounts">, limit: number, messenger: Syncing, chat?: string) => import("../envelope.js").ListBody<unknown>;
+export declare const foundConversations: (command: string, found: Readiness & Pick<FoundConversations, "hits" | "accounts">, limit: number, messenger: Syncing, chat?: string, meta?: Partial<Meta>) => import("../envelope.js").ListBody<unknown>;
 /** `conversations status`: each built chat with the model it was measured by; group chats never built are missing. */
 export declare const readinessList: ({ model, chats, unbuiltGroups, }: {
     model: string;

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

@@ -53,12 +53,15 @@ export const readinessGaps = ({ meaning, model, readiness, refreshed, coverage }
     return { next, missing };
 };
 /** `search conversations` and `conversations related`, CLI and MCP alike. */
-export const foundConversations = (command, found, limit, messenger, chat) => listOf(command, {
+export const foundConversations = (command, found, limit, messenger, chat, meta = {}) => listOf(command, {
     items: found.hits.map((hit) => snakeKeys(hit)),
     limit,
     has_more: false,
     ...readinessGaps(found, messenger, chat),
-    ...(found.accounts ? { meta: { accounts: found.accounts.map((one) => `${one.provider}:${one.account}`) } } : {}),
+    meta: {
+        ...meta,
+        ...(found.accounts ? { accounts: found.accounts.map((one) => `${one.provider}:${one.account}`) } : {}),
+    },
 });
 /** `conversations status`: each built chat with the model it was measured by; group chats never built are missing. */
 export const readinessList = ({ model, chats, unbuiltGroups, }) => listOf("conversations status", {

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

@@ -9,7 +9,7 @@ import { renderMessages } from "../../render/messages.js";
 import { BATCH_SIZE, CONVERSATION_QUERY } from "../../services/conversations.js";
 import { REFRESH_BOUNDS, } from "../../services/embeddings.js";
 import { servicesFor, storedDeps } from "../../services/index.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { analysisChoice } from "../analysis-choice.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "../effects.js";
 import { embeddingChoice, refuseRemoteQuery } from "../embedding-choice.js";
@@ -531,6 +531,10 @@ export const conversationsSearchCommand = (messenger) => syncOptions(boundOption
         refuseLocalWrite(context, messenger.app.command, EMBED_KEY);
     }
     const { limit } = context.settings;
+    const window = dateWindow({
+        ...(since === undefined ? {} : { sinceTime: since }),
+        ...(options.timezone === undefined ? {} : { zone: options.timezone }),
+    });
     const { found, refreshed } = await context.withServices(async (services) => {
         const syncing = syncRequest(this, context);
         const found = await services.embeddings.search(query, {
@@ -551,14 +555,14 @@ export const conversationsSearchCommand = (messenger) => syncOptions(boundOption
             ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
             ...(chat === undefined ? {} : { chat }),
             model,
-            ...(since === undefined ? {} : { since: new Date(momentOf(since, "--since-time")).toISOString() }),
+            ...(window.since === undefined ? {} : { since: new Date(window.since).toISOString() }),
         });
         return { found, refreshed: found.prepared };
     });
     if (refreshed)
         for (const note of leftNotes(refreshed, rootOf(this)))
             context.renderer.note(note);
-    renderAnswer(this, context, foundConversations("search conversations", found, limit, messenger, chat), () => found.hits.map((hit) => `${hitLine(hit)}\n`).join(""));
+    renderAnswer(this, context, foundConversations("search conversations", found, limit, messenger, chat, window.meta), () => found.hits.map((hit) => `${hitLine(hit)}\n`).join(""));
     if (found.hits.length === 0 && context.format === "pretty")
         context.renderer.note(found.meaning === "unavailable"
             ? "nothing matches in words"

package/dist/cli/messenger/inbox.js

@@ -51,7 +51,7 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     const { app } = messenger;
     const { settings, renderer, format, env } = context;
     const kinds = kind === undefined ? undefined : kindsOf(kind);
-    const { since } = catchUpQuery(query, INBOX_QUERY, "inbox");
+    const { since, meta } = catchUpQuery(query, INBOX_QUERY, "inbox");
     if (fresh && since !== undefined)
         throw new CliError("validation_error", "--new keeps its own point — not with a date in the query");
     const saved = fresh && since === undefined
@@ -83,7 +83,7 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
         renderer.note(`marked ${marked.length} chat(s) read up to the newest message shown`);
     if (inbox.partial && format === "pretty")
         renderer.warn(PARTIAL_NOTE);
-    const answer = inboxAnswer(inbox, hearing, reader, transcribe === true);
+    const answer = inboxAnswer(inbox, hearing, reader, transcribe === true, meta);
     renderAnswer(this, context, answer, () => {
         if (answer.items.length === 0) {
             renderer.note(inbox.mode === "unread" ? "nothing unread" : `nothing new since ${inbox.since}`);

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

@@ -6,7 +6,7 @@ import { replyRenderer } from "../../replies/rendering.js";
 import { audienceWarnings, readReplies, repliesPathFor } from "../../replies/rules.js";
 import { paused, readRepliesState, repliesStatePathFor, writeRepliesState } from "../../replies/state.js";
 import { levelFor } from "../../sends/permissions.js";
-import { momentOf } from "../../services/moment.js";
+import { dateWindow } from "../../services/moment.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
@@ -37,7 +37,8 @@ export const repliesCommand = (messenger) => {
             throw new CliError("validation_error", "--ai calls a model and cannot be combined with --offline");
         if (ai && levelFor(settings.permissions, "messages.list").level === "deny")
             throw new CliError("permission_error", "this profile denies reading messages — no stored data was sent to a reply model");
-        const since = momentOf(sinceTime ?? `${DRY_RUN_DAYS}d`, "--since-time");
+        const window = dateWindow({ sinceTime: sinceTime ?? `${DRY_RUN_DAYS}d` });
+        const since = window.since;
         const path = repliesPathFor(messenger.app, settings.profile, env);
         const { rules, audience } = readReplies(path, messenger.provider);
         if (rules.length === 0) {
@@ -81,7 +82,7 @@ export const repliesCommand = (messenger) => {
                 .sort(([, a], [, b]) => b - a)
                 .map(([why, count]) => `  passed over ${count}: ${why}`),
         ]);
-        renderAnswer(this, context, itemOf(answer), () => `${lines.join("\n")}\n`);
+        renderAnswer(this, context, itemOf(answer, { meta: window.meta }), () => `${lines.join("\n")}\n`);
     });
     const switched = (on) => async function () {
         const context = messengerContext(this, messenger);