@wirecat/cli-core 0.546.0 → 0.547.0

package/CHANGELOG.md

@@ -7,6 +7,158 @@ shape of this file.
 
 ## Unreleased
 
+## 0.547.0 — 02.11.2026
+
+### Added
+
+- **A server's refused SEARCH fails that folder, not the run, and proves nothing.** A mail source throws
+  `mail.search-refused` (`SEARCH_REFUSED`, `searchRefused`) when the server answers SEARCH with NO or BAD. `syncMail`
+  reads the other folders, answers `state: "partial"` with `refusedFolders`, and for the refused folder marks no mail
+  deleted, changes no membership, moves no resume point and leaves `mail_coverage` as it was. Before, a mail source that
+  read the refusal as "nothing found" made the folder look empty.
+- **Server search reads big mail text-first, and the next sync completes it.** A candidate is read up to
+  `SERVER_BOUNDS.textBytes` (256 KiB, `fetchRaw(items, { bytes })`); one cut short is stored with its text and no
+  attachments, marked `metadata.partial`, and `meta.issues` says `search.server-partial`. `syncMail` then reads up to
+  100 partial emails whole and clears the mark (`partial: { completed, left }`; `completePartial: false` skips it).
+  `MailStore.partialEmails` lists them. No store migration: the mark is a JSON key older builds ignore.
+- **`readClientFile` (from `@wirecat/cli-core/oauth`) reads a user's own Google Desktop OAuth client file** (the
+  `{ "installed": { client_id, client_secret } }` JSON from Google's console). It refuses a file other users can read
+  (`sign-in.client-file-open`) and a file of the wrong shape (`sign-in.client-file-invalid`), and never puts the file's
+  contents in an error. gcal, drive and mail each kept a copy of this reader.
+- **`openBrowser(url, browser?)` is exported from `@wirecat/cli-core/cli`**, so a CLI that does not start through
+  `startCli` opens the sign-in page the same way: `open`, `rundll32` or `xdg-open`, or the named browser.
+- **iCalendar feeds as read-only calendars.** With `deps.feeds` (`icsFeeds`), `calendars add <url> [--title]` follows a
+  public holiday calendar, a sports schedule or a published `.ics` address, and `calendars remove <calendar>` stops.
+  `sync` reads each feed after the provider (`syncWithFeeds`), so its events show in `events list`,
+  `search events`, `overlapping:` and `events remind`. Repeating events are expanded here (`expandSeries`: RRULE in
+  the event's own zone, RDATE, EXDATE and overrides). The address is a secret input, kept by the CLI and never
+  printed; a fetch follows redirects only to https and stops at 10 MB and 30 s. `readIcs` takes
+  `{ overrides: true }` and returns the calendar's `name`. See `docs/dev/CALENDARS.md`, "Feeds".
+- **History limits for pushed history, per profile.** A messenger whose history is pushed (`history: "store"`,
+  WhatsApp) saves one-to-one chats back `history_dialog_days` (1095 by default), groups of more than two people back
+  `history_group_days` (365) and nothing of a group above `history_group_members_max` people (50); at most 1095 days.
+  The chat row stays, so the chat is still listed. Live messages, `messages sync` and what the store already holds are
+  never dropped. `messages sync <chat> --full-history` fetches a chat and keeps its pushed history in full from then on
+  (`history_included` in the answer). `ChatsStore` gains `historySkips`, `historyShapes`, `recordHistorySkips` and
+  `setHistoryIncluded`; `Saving` takes `historyLimits`.
+- **Helpers for reading money and questions in a chat, for the project status work.** `amountsOf(text)` returns
+  every amount in a text, in order (`amountOf` is its first). `MONEY_REQUEST`, `MONEY_DONE` and `PROMISE` word lists
+  (ru, en, es) with `moneyClassesOf(text)` say which a text uses. `questions(messages, { asker: "owner" })` lists the
+  owner's own questions and whether anyone but the owner answered them, by a reply or by speaking next; the default,
+  `"others"`, is what it did before. `linkedChatsOf` is exported, now with each link's `role`, and so is
+  `AGENDA_DEFAULTS`, the silence `tasks agenda` waits before it lists a chat.
+- **A command's own history handler learns whether each batch reached the store**: `HistoryBatchHandler` takes
+  `saved`, a promise of the same `true` or `false` the messenger gets, so a link can count only what was kept.
+- **Every messenger command that takes a chat or a message also takes the reference other WireCat CLIs print**:
+  `chat:<provider>/<account>/<chat>` wherever a chat is named (`messages list chat:max/34871122/63488582`, bot
+  commands too), and `msg:<provider>/<account>/<chat>/<message>` wherever a chat or a message is, online and offline. A person lookup takes `contact:<provider>/<id>`. A reference of another
+  account is refused, naming the account it belongs to and the profiles of this CLI the store saw on it; it never
+  switches account. One of another messenger is refused with the command that opens it (`open it with tg <profile>
+  messages list chat:telegram/…`), and another kind (`document:413` given as a chat) with what the argument takes.
+- **`event:<id>` and `meeting:<account>/<meeting>[/<transcript>[/<cue>]]` parse with `parseReference`** and
+  `canonicalReference`, as every other kind: `event:N` was printed by the calendar and person answers and could not be
+  read back. The kinds are one table, `REF_KINDS`; `looksLikeReference(text)` tells a reference from a title such as
+  `Note: plan`. Reference errors carry a reason: `ref.malformed`, `ref.unknown-kind` (with the kind meant:
+  `"doc:413" … did you mean document:413?`), `ref.wrong-kind`, `ref.wrong-provider`, `ref.wrong-account`.
+- **`messages list` reads a window bounded on both sides, offline too.** The query takes a start and an end,
+  `'date>=2026-10-01 date<2026-10-20'` or `'date:[2026-10-01 TO 2026-10-19]'`, and `id>` with `date<`. A start reads
+  forward, oldest first, and stops at the end; an end alone reads back from it, newest page first, as before.
+  `--offline` and a messenger whose history is read from the store (WhatsApp) now answer both ways from the store
+  instead of refusing. A forward cursor carries the end, `after:<id>~<epoch ms>`, so the next page stops at the same
+  place. `--since`, `--since-time`, `--until`, `--until-time`, `--after-time` and `--before-time` on `messages list`
+  fail with the query form to type instead. The store's `messages()` window takes `after` (a message or a moment)
+  and `until`.
+- **One proposal inbox behind one check: `proposalRegistry(store, policy)`, `ProposalKind`, `parseProposalIds`
+  (`@wirecat/cli-core/services`) and `mayDecide` (`@wirecat/cli-core/store`).** The registry lists every pending
+  proposal newest first across kinds (`relationship`, `key_document`, `fact`, `memory`, `findings` for evidence
+  findings, and `action` for every other stored proposal), and decides many ids at once, each on its own: the answer
+  lists `decided` and `refused`, and one refusal never undoes the others. A new kind registers itself with its id
+  `prefix` or the `stored` proposal kinds it owns; nothing else changes. `parseProposalIds` reads
+  `17070-17079,fact:500-502,17080/f2` and refuses a range across prefixes. Unconfirmed agent and rule links show as
+  `link:<id>` (relationships) and `key:<id>` (key documents) until the store moves them.
+- **`knowledge.proposeRelation(scope, input, by)`**: an agent's or a rule's relationship is a stored `relationship`
+  proposal for the owner, not a link; the same pending pair returns the proposal already held. Removing a link to a
+  project, or rejecting any suggested link, leaves a rejected `relationship` proposal, so a later scan can skip it.
+- **`proposedActions.list({ kinds, except, project, proposedBy })`**, `proposedBy` on `facts.list` and
+  `memories.list`, `order: "created"` on `facts.list`, and the bot's `kind` (`agent` or `rule`) on the author of a
+  proposed action, a fact, a memory and an evidence findings batch; bots may have the kind `rule`, and an `Author` may
+  name it.
+- **`knowledge.decideLinkProposal(id, decision)`** decides a stored `relationship` or `key_document` proposal, and
+  **`knowledge.decideSuggestedLink(id, decision)`** an older unconfirmed link, each in one transaction: the link and
+  the decision land together or not at all. A decision's `reason` is kept: on a rejected proposal as its result, on a
+  fact in `metadata.decision`, on an evidence findings receipt.
+
+### Changed — may break callers
+
+- **`SERVER_BOUNDS.maxMessageBytes`, `ServerSearched.tooLarge` and `search.server-too-large` are gone**: a big
+  candidate is no longer left on the server; see `textBytes`, `ServerSearched.partial` and `search.server-partial`.
+- **An option after `--` is read as the option.** `messages sync -- -100 --json` now syncs `-100` and answers in JSON;
+  it failed with "too many arguments". After `--`, a word that is exactly one of the command's options, its own or a
+  global one (`--json`, `--limit 5`, `--json=id`), moves in front of `--`; every other word stays a positional. A
+  negative id needs no `--` at all. Commands that take free text keep every word after `--` literal: `messages send` and
+  `edit` (also the bot's), `polls create`, `topics create`, `chats create`, `chats folders create`, `contacts rename`,
+  `contacts aliases set`, `messages press`, `bot commands set`, `schedule command`, `events remind`, `complete`, and the
+  notes templates. Mark such a command with `annotate(command, { literal_after_dashes: true })`; MCP calls are never
+  lifted. A script that passed the literal word `--json` as a positional of another command now gets the option instead.
+- **A write to a calendar the account may only read refuses before anything is asked or journaled**
+  (`calendar.read-only`): create, quick add, import, update, delete, respond and move, for a feed and for a provider's
+  `reader` or `free-busy` calendar alike. Before, only the target of a move was checked; the provider refused the rest.
+  `calendars busy` and `search --backend server` leave feed calendars out.
+- **A locator of another account or messenger is refused with a new text and a reason.** `messages show`, `context`,
+  `link` and `download` said "that locator belongs to another account; select its profile first" or "…belongs to
+  another messenger"; they now say `<ref> belongs to account <id>; profile <name> is account <id>` (`ref.wrong-account`)
+  or `<ref> is a <messenger> message; open it with …` (`ref.wrong-provider`). A script matching the old text matches
+  the reason instead.
+- **A text of the form `<kind>:<no spaces>` given as a chat is read as a reference**, so a chat titled `note:plan` is
+  no longer found by that title; give its id or a part of the title.
+- The provider seeds of `telegram`, `max` and `whatsapp` name their CLI (`command: tg`, `max`, `wa`), which a
+  provider clash message now shows (`telegram (messages, from tg)`).
+- **Every decide method takes who decides, a `Decider`** (`"owner"` or `{ bot, model?, reason }`):
+  `facts.accept(ref, by)`, `facts.reject(ref, by)`, `memories.confirm(ref, by)`, `knowledge.confirmRelation(scope, id,
+  by)`, `knowledge.removeRelation(scope, id, by)`, `proposedActions.approve(id, by, result?)`,
+  `proposedActions.reject(id, by)`, `approveAsTask(store, id, by)`, and `by` is now required in
+  `evidenceFindings.review` and `meetingFindings.review`. `DocumentKnowledge.fact` and `.memory` take `by` for a
+  `confirm`, and `memories.markStale(ref, by)` and `.memory(…, "stale", by)` take it too: marking an agent's memory
+  stale is how it is turned down. `knowledge.relate` needs `by`: the owner's relationship is a link, an agent's is a
+  `relationship` proposal it returns instead. `notes.addLink` refuses any confirmed link without `by: "owner"`, so an
+  agent writes `confirmed: false` (the task service now does). `notes.removeLink(id, by)`, `facts.reverse(ref, by)`,
+  `facts.remove(ref, by)` and `memories.remove(ref, by)` take who removes; the document port's `addMemory` needs
+  `author`, `addFact` and `addLink` need `by`, with no owner default. `proposalRegistry(store)` takes no policy: the
+  host sets it once with `openStore({ decisions })`, and `store.decisionPolicy` is what the registry and every store
+  check read. A host passes the owner only when the owner runs the command, and
+  the agent's bot and reason otherwise.
+  An agent's confirmation of a relationship is recorded in the link's provenance, and of a fact or proposal as its
+  decider.
+
+### Fixed
+
+- **A sum written in groups of three read as the wrong amount: `50 000 ₽` was `0` and `4 300 ₽` was `300`**, because
+  only the last group was read. Groups after a space, a no-break or thin space, a dot or a comma (`50 000`,
+  `1.200 €`, `$1,200`) are one number now, a decimal part after them is kept (`5 000.50 ₽`), and amounts keep two
+  decimals instead of a whole number (`15.5 eur` was 16). This is the amount the duplicate check compares between
+  two tasks, so a reminder worded with a grouped sum is no longer compared on the wrong figure.
+- **`page.next` of `messages list` and `messages comments` runs as written.** It repeated the query's `id`/`date`
+  bound beside `--cursor`, which the command refuses as two starting points; it now keeps only `topic:` and
+  `starred:`.
+- **An inclusive start keeps a message sent exactly at it.** `messages list 'date>=2026-10-01'` skipped a message
+  sent at the first millisecond of the day, and `date<="…"` one sent at that moment.
+
+### Security
+
+- **An agent can no longer decide its own proposal.** Before, `facts.accept`/`reject`,
+  `memories.confirm`, `knowledge.confirmRelation`, `proposedActions.approve`/`reject`, `approveAsTask` and both
+  findings reviews never asked who decided, so over MCP an agent could confirm what it had proposed itself. Every one
+  of them, and the registry, now runs `mayDecide`: the owner always may; an agent needs a reason
+  (`proposal.reason-required`), is refused its own bot's proposal (`proposal.own`), a rule scorer's proposal and one
+  that names no author (`proposal.owner-only`), and every decision when the host turns agent decisions off
+  (`proposals.agent-decisions-off`). An agent can no longer add a memory already `confirmed`, mark its own memory
+  stale, write a confirmed project link itself, or remove a link. A link records only free-text provenance, which
+  anyone can write, so only the owner decides an unconfirmed link or removes a link; the rejected record a removal
+  leaves names who removed it. Findings an agent accepted for the owner record that agent, not the owner. Only the
+  owner removes or reverses an accepted fact or another bot's memory; an agent withdraws only its own row while it is
+  proposed. Turning agent decisions off now holds for every store method, not only the registry, and a bot is the
+  same bot whatever its letter case (`Claude-Code` is `claude-code`).
+
 ## 0.546.0 — 02.11.2026
 
 ### Added

package/dist/cli/messenger/history-query.d.ts

@@ -9,14 +9,20 @@ export declare const historyQuery: (messenger: {
 }) => import("@wirecat/cli-base/query").QueryRegistry;
 declare const COMMENTS_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
 export { COMMENTS_QUERY };
-type Start = Pick<ListWindow, "before" | "beforeTime" | "after">;
+type Start = Pick<ListWindow, "before" | "beforeTime" | "after" | "until">;
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export declare const cursorOf: (start: Start, edge: {
     first?: string;
     last?: string;
 }) => string | undefined;
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export declare const historyWindow: (words: QueryWords, cursor: string | undefined, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => Omit<ListWindow, "limit">;
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export declare const resumeQuery: (words: QueryWords, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => string | undefined;

package/dist/cli/messenger/history-query.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
-import { dateEndpoint, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
-import { listQuery, nativeField, nativeTerms, typedQuery } from "../list-query.js";
+import { dateRange, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
+import { listQuery, nativeField, nativeTermLists, typedQuery } from "../list-query.js";
 /** What a chat's history can be read by: where it starts, and one topic. */
 export const HISTORY_QUERY = defineQuery({
     entity: "message",
@@ -36,52 +36,108 @@ const COMMENTS_QUERY = defineQuery({
 });
 export { COMMENTS_QUERY };
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export const cursorOf = (start, edge) => {
     const forward = start.after !== undefined;
     const id = forward ? edge.last : edge.first;
-    return id === undefined ? undefined : `${forward ? "after" : "before"}:${id}`;
+    if (id === undefined)
+        return undefined;
+    const end = forward && start.until !== undefined ? `~${start.until}` : "";
+    return `${forward ? "after" : "before"}:${id}${end}`;
 };
 const isId = (value) => value !== "" && !/[\s\p{Cc}]/u.test(value);
 const fromCursor = (cursor) => {
     const at = cursor.indexOf(":");
-    const [way, id] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const [way, rest] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const ended = way === "after" ? /^(.*)~(\d+)$/u.exec(rest) : null;
+    const id = ended ? ended[1] : rest;
     if (!isId(id) || (way !== "before" && way !== "after"))
         throw new CliError("validation_error", `--cursor takes what page.next gave, before:<id> or after:<id> — not "${cursor}"`);
-    return way === "before" ? { before: id } : { after: { id } };
+    if (way === "before")
+        return { before: id };
+    return { after: { id }, ...(ended ? { until: Number(ended[2]) } : {}) };
 };
-const startOf = (term, command) => {
+/** A term's lower and upper bound; a date's as moments in the zone, an exclusive end 1 ms inside. */
+const boundsOf = (term, command) => {
     const context = { command };
-    const older = term.value === "*" && term.upper !== undefined && term.upper !== "*";
-    const newer = term.value !== "*" && (term.upper === undefined || term.upper === "*");
-    if (older === newer)
-        queryError("query.unsupported-operator", term.span, `${term.field} takes one side: ${term.field}< or ${term.field}>`, context);
-    if (term.field === "id")
-        return older ? { before: term.upper } : { after: { id: term.value } };
-    const bound = older ? term.upper : term.value;
-    const inclusive = (older ? term.upper_inclusive : term.lower_inclusive) ?? true;
-    const { time } = dateEndpoint(bound, timezoneOf(), older ? "upper" : "lower", inclusive, term.span);
-    if (time === undefined)
-        queryError("query.invalid-date", term.span, `${bound} is not a time`, context);
-    return older ? { beforeTime: time } : { after: { time } };
+    const hasLower = term.value !== "*";
+    const hasUpper = term.upper !== undefined && term.upper !== "*";
+    const span = term.span;
+    if (term.field === "id") {
+        if (hasLower === hasUpper)
+            queryError("query.unsupported-operator", span, "id takes one side: id< or id>", context);
+        return hasLower
+            ? { lower: { start: { after: { id: term.value } }, span, date: false } }
+            : { upper: { start: { before: term.upper }, span, date: false } };
+    }
+    if (!hasLower && !hasUpper)
+        queryError("query.unsupported-operator", span, `${term.field} needs a start, an end or both`, context);
+    const range = dateRange(term.value, term.upper ?? "*", term.lower_inclusive ?? true, term.upper_inclusive ?? true, timezoneOf(), span);
+    if ((hasLower && range.lower === undefined) || (hasUpper && range.upper === undefined))
+        queryError("query.invalid-date", span, "that is not a time", context);
+    return {
+        // The messenger and the store read strictly after a start, so an inclusive one moves 1 ms back.
+        ...(range.lower === undefined
+            ? {}
+            : { lower: { start: { after: { time: range.lower - (range.lower_inclusive ? 1 : 0) } }, span, date: true } }),
+        ...(range.upper === undefined
+            ? {}
+            : { upper: { start: { until: range.upper - (range.upper_inclusive ? 0 : 1) }, span, date: true } }),
+    };
 };
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/**
+ * The window the query names. A start reads forward from it, oldest first, and stops at an end; an end alone reads
+ * back from it, newest page first.
+ */
+const windowOf = (terms, command) => {
+    const context = { command };
+    const lowers = [];
+    const uppers = [];
+    for (const term of terms) {
+        const { lower, upper } = boundsOf(term, command);
+        if (lower)
+            lowers.push(lower);
+        if (upper)
+            uppers.push(upper);
+    }
+    const [lower, extraLower] = lowers;
+    const [upper, extraUpper] = uppers;
+    if (extraLower)
+        queryError("query.unsupported-placement", extraLower.span, "the window has one start", context);
+    if (extraUpper)
+        queryError("query.unsupported-placement", extraUpper.span, "the window has one end", context);
+    if (lower && upper && !upper.date)
+        queryError("query.unsupported-placement", upper.span, "a window from a start ends at a date: date<…", context);
+    if (lower)
+        return { ...lower.start, ...upper?.start };
+    if (upper?.start.until !== undefined)
+        return { beforeTime: upper.start.until + 1 };
+    return upper?.start ?? {};
+};
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export const historyWindow = (words, cursor, command, registry = HISTORY_QUERY) => {
-    const terms = [...nativeTerms(listQuery(typedQuery(words), registry, command), command).values()];
-    const starts = terms
-        .filter((term) => term.field !== "topic" && term.field !== "starred")
-        .map((term) => startOf(term, command));
-    if (cursor !== undefined)
-        starts.push(fromCursor(cursor));
-    if (starts.length > 1)
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const bounds = [...(terms.get("date") ?? []), ...(terms.get("id") ?? [])];
+    const start = windowOf(bounds, command);
+    if (cursor !== undefined && bounds.length > 0)
         throw new CliError("validation_error", "the query and --cursor name two starting points; give one of them");
-    const topic = terms.find((term) => term.field === "topic")?.value;
-    const starred = terms.find((term) => term.field === "starred")?.value.toLowerCase();
+    const topic = terms.get("topic")?.[0]?.value;
+    const starred = terms.get("starred")?.[0]?.value.toLowerCase();
     return {
-        ...starts[0],
+        ...(cursor === undefined ? start : fromCursor(cursor)),
         ...(topic === undefined ? {} : { threadId: topic }),
         ...(starred === undefined ? {} : { starred: starred === "true" }),
     };
 };
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export const resumeQuery = (words, command, registry = HISTORY_QUERY) => {
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const kept = ["topic", "starred"].flatMap((field) => terms.get(field)?.map((term) => `${field}:${term.value}`) ?? []);
+    return kept.length > 0 ? kept.join(" ") : undefined;
+};

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

@@ -12,6 +12,7 @@ import { modelWith, spoken } from "../../speech/hearing.js";
 import { REMOTE_READ } from "../effects.js";
 import { itemOf, listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
+import { withOptionHints } from "../option-hints.js";
 import { positiveCount } from "../paging.js";
 import { syncCommand } from "./backfill-command.js";
 import { messengerContext } from "./context.js";
@@ -19,7 +20,7 @@ import { linksCommand } from "./conversations-command.js";
 import { downloadSubcommand } from "./download-command.js";
 import { heardItems, hearForCommand, hearingMissing, MODEL_OPTION, spokenItems, TRANSCRIBE_OPTION, } from "./hearing-command.js";
 import { historyLimitGaps } from "./history-gaps.js";
-import { cursorOf, historyQuery, historyWindow } from "./history-query.js";
+import { cursorOf, historyQuery, historyWindow, resumeQuery } from "./history-query.js";
 import { hideNever } from "./lacks.js";
 import { threadAnswer } from "./message-answers.js";
 import { messageItem, messageItems, viewOf } from "./message-items.js";
@@ -36,6 +37,8 @@ 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";
+const WINDOW_EXAMPLE = "date>=2026-10-01 date<2026-10-20";
+const TIME_FLAGS = ["--since", "--since-time", "--until", "--until-time", "--after-time", "--before-time"];
 /** `messages`: reading, and sending through the guard. A CLI may add its own subcommands. */
 export const messagesCommand = (messenger) => {
     const messages = new Command("messages").description("read and send messages");
@@ -51,8 +54,8 @@ export const messagesCommand = (messenger) => {
         .addHelpText("after", queryHelp(history))
         .argument("<chat>", messenger.chatArgument)
         .argument("[query...]", `${messenger.topics === false
-        ? "where to start: id<42, date>2026-10-01"
-        : "where to start and which topic: id<42, date>2026-10-01, topic:12"}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
+        ? `where to start or which window: id<42, ${WINDOW_EXAMPLE}`
+        : `where to start or which window, and which topic: id<42, ${WINDOW_EXAMPLE}, topic:12`}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it")
         .option(...TRANSCRIBE_OPTION)
@@ -73,6 +76,8 @@ export const messagesCommand = (messenger) => {
         const next = page.hasMore
             ? cursorOf(window, { first: page.items[0]?.id, last: page.items.at(-1)?.id })
             : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages list", history);
+        const queryArg = typed ? { query: typed } : {};
         // 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
             ? await context.withStore(async (store, account) => {
@@ -88,13 +93,14 @@ export const messagesCommand = (messenger) => {
             has_more: page.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, ...queryArg },
             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 });
+    withOptionHints(list, Object.fromEntries(TIME_FLAGS.map((flag) => [flag, `messages list reads a window by its query: '${WINDOW_EXAMPLE}'`])));
     const readWindow = async (command, chat, message, window) => {
         const context = messengerContext(command, messenger);
         const { found, reader } = await context.withServices(async (services) => ({

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

@@ -7,7 +7,7 @@ import { listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
-import { COMMENTS_QUERY, cursorOf, historyWindow } from "./history-query.js";
+import { COMMENTS_QUERY, cursorOf, historyWindow, resumeQuery } from "./history-query.js";
 import { messageItems, viewOf } from "./message-items.js";
 export const commentsCommand = (messenger) => {
     const otherPosts = messenger.readsComments === true && messenger.channelComments === false;
@@ -42,13 +42,15 @@ export const commentsCommand = (messenger) => {
             reader: await services.messages.reader(),
         }));
         const next = found.hasMore ? cursorOf(window, { first: found.items[0]?.id }) : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages comments", COMMENTS_QUERY);
+        const queryArg = typed ? { query: typed } : {};
         renderAnswer(this, context, listOf("messages comments", {
             items: messageItems(found.items, reader),
             limit,
             has_more: found.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, post, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, post, ...queryArg },
         }), () => renderMessages(found.items, viewOf(context, messenger)));
     });
     return annotate(command, { output: { entity: "message" }, query: COMMENTS_QUERY });

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
+    error?: undefined;
     path: string;
     exists: boolean;
-    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/option-hints.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export declare const withOptionHints: (command: Command, hints: Readonly<Record<string, string>>) => Command;

package/dist/cli/option-hints.js

@@ -0,0 +1,15 @@
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export const withOptionHints = (command, hints) => {
+    const unknown = command;
+    const fallback = unknown.unknownOption.bind(command);
+    unknown.unknownOption = (flag) => {
+        const hint = hints[flag.split("=")[0]];
+        if (hint === undefined)
+            return fallback(flag);
+        return command.error(`unknown option '${flag}' — ${hint}`, { code: "commander.unknownOption" });
+    };
+    return command;
+};

package/dist/errors/reasons.js

@@ -110,7 +110,11 @@ const OTHERS = [
     ["search.server-failed", "provider_unavailable", "the server did not answer a search"],
     ["search.server-timeout", "timeout", "the server did not answer within --server-time"],
     ["search.server-capped", "outcome_unknown", "the server found more than one search reads, or a branch was not sent"],
-    ["search.server-too-large", "outcome_unknown", "a message the server found is too large to download during a search"],
+    [
+        "search.server-partial",
+        "outcome_unknown",
+        "a message the server found was stored without its attachments; the next sync reads it whole",
+    ],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
     [
@@ -145,6 +149,14 @@ const OTHERS = [
     validation("name.taken", "the name is already used"),
     validation("period.ambiguous", "the period can be read more than one way"),
     validation("proposal.wrong-state", "the proposal is not in a state that allows this"),
+    validation("proposal.reason-required", "an agent deciding for the owner gives a reason"),
+    validation("proposal.decider-required", "a decision names who decides: the owner or an agent with a reason"),
+    validation("proposal.ids", "the proposal ids cannot be read"),
+    ["proposal.own", "permission_error", "an agent never decides its own proposal"],
+    ["proposal.owner-only", "permission_error", "only the owner decides this proposal"],
+    ["proposals.agent-decisions-off", "permission_error", "agent decisions are turned off; the owner decides"],
+    ["proposal.unknown-kind", "not_found", "no registered proposal kind holds this id"],
+    validation("relationship.exists", "a confirmed relationship already links them"),
     validation("ranking.invalid", "the ranking is not valid"),
     validation("ref.malformed", "the reference has a known kind but not its shape"),
     validation("ref.unknown-kind", "the text names no kind of reference"),

package/dist/mail/cli/index.js

@@ -74,11 +74,11 @@ const serverIssues = (server) => {
         ...FAILED[reason],
         source: "server",
     }));
-    const tooLarge = server.tooLarge
-        ? [{ code: "outcome_unknown", reason: "search.server-too-large", source: "server" }]
+    const partial = server.partial
+        ? [{ code: "outcome_unknown", reason: "search.server-partial", source: "server" }]
         : [];
-    return failed.length || tooLarge.length
-        ? [...failed, ...tooLarge]
+    return failed.length || partial.length
+        ? [...failed, ...partial]
         : [{ code: "outcome_unknown", reason: "search.server-capped", source: "server" }];
 };
 const searchCommand = (mail) => {

package/dist/mail/index.d.ts

@@ -7,6 +7,7 @@ export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHead
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
+export { PARTIAL, type PartialOutcome } from "./partial.js";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST_RULE } from "./probe.js";
 export { type MailFolderProgress, mailProgress } from "./progress.js";
@@ -21,5 +22,6 @@ export { DEMOTE_AT, type DomainAges, demotedSenders, type LookupResult, SCORE_VE
 export { type MailCriteria, mailCriteriaOf, narrows } from "./server-query.js";
 export { type MailServerAccess, type MailServerRequest, searchMailServer } from "./server-search.js";
 export type { Listed, MailSource, Quick, Searched } from "./source.js";
+export { SEARCH_REFUSED, searchRefused } from "./source.js";
 export { listedOf, type StoredMail } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, type MailAccount, type MailIndexed, type MailSyncOptions, type MailSyncResult, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/index.js

@@ -7,6 +7,7 @@ export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
+export { PARTIAL } from "./partial.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
 export { mailProgress } from "./progress.js";
@@ -20,5 +21,6 @@ export { FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, scoreGroup, WEIGHT
 export { DEMOTE_AT, demotedSenders, SCORE_VERSION, scoreSenders, } from "./sender-scores.js";
 export { mailCriteriaOf, narrows } from "./server-query.js";
 export { searchMailServer } from "./server-search.js";
+export { SEARCH_REFUSED, searchRefused } from "./source.js";
 export { listedOf } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/partial.d.ts

@@ -0,0 +1,34 @@
+import type { BudgetStop } from "../background/budget.js";
+import type { LoadEngine } from "../readers/types.js";
+import type { MessageStore } from "../store/index.js";
+import type { MailSource } from "./source.js";
+/** The `emails.metadata` key of an email stored from its first bytes: `{ bytes }` read of its `size`. */
+export declare const PARTIAL = "partial";
+/** How many partial emails one sync reads whole at most; the rest wait for the next run. */
+export declare const PARTIAL_PER_RUN = 100;
+export interface PartialOutcome {
+    /** Read whole this run, the mark cleared. */
+    completed: number;
+    /** Still partial after this run. */
+    left: number;
+}
+/**
+ * Reads whole the emails a server search stored from their first bytes, so the archive holds their attachments too.
+ * Sync never reads stored mail again, so without this step a partial email would stay partial. Gmail's are found by
+ * their id; elsewhere at a stored location, trusted only when the bytes read there carry the stored id.
+ */
+export declare const completePartial: ({ store, source, accountId, address, folders, maxBodyChars, maxAttachmentChars, loadEngine, now, take, signal, }: {
+    store: MessageStore;
+    source: MailSource;
+    accountId: number;
+    address: string;
+    /** Where Gmail's are looked for by id; asked only when a partial email is there to read. */
+    folders: () => Promise<readonly string[]>;
+    maxBodyChars: number;
+    maxAttachmentChars: number;
+    loadEngine: LoadEngine;
+    now: number;
+    /** A budgeted run's next request, or why there is none. */
+    take?: () => BudgetStop | null;
+    signal?: AbortSignal;
+}) => Promise<PartialOutcome>;