@wirecat/cli-core 0.545.0 → 0.547.0

package/CHANGELOG.md

@@ -7,6 +7,234 @@ 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
+
+- **`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`.
+
+### Changed — may break callers
+
+- **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)`).
+
+### 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.
+
 ## 0.545.0 — 02.11.2026
 
 ### Added

package/dist/calendar/busy.js

@@ -2,6 +2,7 @@ import { CliError } from "@wirecat/cli-base";
 import { dayBoundary, queryError, queryFieldsOf, zonedMoment, } from "@wirecat/cli-base/query";
 import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, typedQuery } from "../cli/list-query.js";
 import { calendarBusy } from "./cli/answers.js";
+import { isFeedCalendar } from "./feeds.js";
 import { calendarIn, plusDays, timeWindow } from "./reads.js";
 /** Google answers for 50 calendars at most (`calendarExpansionMax`, reference/freebusy/query). */
 const MOST = 50;
@@ -60,6 +61,8 @@ export const busyQuery = async (query, context) => {
                 to = timeWindow(node, zone, now).upper;
             else if (field === "calendar") {
                 const calendar = await calendarIn(context.store, context.accountId, node.value);
+                if (isFeedCalendar(calendar))
+                    throw new CliError("validation_error", `calendar ${calendar.id} is a feed, which the provider has no busy times for; read it with events list`, { reason: "busy.feed" });
                 if (!calendars.some(({ id }) => id === calendar.id))
                     calendars.push(calendar);
             }
@@ -76,7 +79,7 @@ export const busyQuery = async (query, context) => {
         throw new CliError("validation_error", "the window ends before it starts");
     const asked = calendars.length
         ? calendars
-        : (await context.store.calendars(context.accountId)).filter(({ synced, deletedAt }) => synced && !deletedAt);
+        : (await context.store.calendars(context.accountId)).filter((calendar) => calendar.synced && !calendar.deletedAt && !isFeedCalendar(calendar));
     if (asked.length === 0 && people.size === 0)
         throw new CliError("validation_error", "no calendar syncs yet; name one with calendar:<id>, or a person:<email>", {
             reason: "busy.no-calendars",

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

@@ -11,6 +11,31 @@ export declare const calendar: v.StrictObjectSchema<{
     readonly synced: v.BooleanSchema<undefined>;
     readonly seen_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>;
+/** `calendars add`: the feed's calendar, how many events the feed holds now, and the sync to run next. */
+export declare const calendarFeed: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly external_id: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly access_role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly primary: v.BooleanSchema<undefined>;
+    readonly synced: v.BooleanSchema<undefined>;
+    readonly seen_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 events: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly hint: v.StringSchema<undefined>;
+}, undefined>;
+/** `calendars remove`: the feed's calendar, no longer synced, and how many stored entries were marked deleted. */
+export declare const calendarFeedRemoval: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly external_id: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly access_role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly primary: v.BooleanSchema<undefined>;
+    readonly synced: v.BooleanSchema<undefined>;
+    readonly seen_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 removed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
 export declare const calendarBusy: v.StrictObjectSchema<{
     readonly start: 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 end: 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`">]>;
@@ -75,6 +100,12 @@ export declare const calendarSync: v.StrictObjectSchema<{
         readonly embedded: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
         readonly left: v.BooleanSchema<undefined>;
     }, undefined>, undefined>;
+    /** Each feed's events as read, and how many it could not take (`syncWithFeeds`). */
+    readonly feeds: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+        readonly calendar_id: v.NumberSchema<undefined>;
+        readonly events: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly skipped: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>, undefined>;
 }, undefined>;
 export declare const calendarSyncProgress: v.StrictObjectSchema<{
     readonly calendar_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;

package/dist/calendar/cli/answers.js

@@ -19,6 +19,10 @@ export const calendar = v.strictObject({
     synced: v.boolean(),
     seen_at: nullableTime,
 });
+/** `calendars add`: the feed's calendar, how many events the feed holds now, and the sync to run next. */
+export const calendarFeed = v.strictObject({ ...calendar.entries, events: count, hint: text });
+/** `calendars remove`: the feed's calendar, no longer synced, and how many stored entries were marked deleted. */
+export const calendarFeedRemoval = v.strictObject({ ...calendar.entries, removed: count });
 const busyRow = v.strictObject({
     /** One of the account's calendars, by its id; or `person`, by the address asked. */
     calendar: v.optional(id),
@@ -68,6 +72,8 @@ export const calendarSync = v.strictObject({
     hint: v.optional(text),
     /** What `sync --embed` embedded: `embedEvents`' answer. */
     embeddings: v.optional(v.strictObject({ model: text, embedded: count, left: v.boolean() })),
+    /** Each feed's events as read, and how many it could not take (`syncWithFeeds`). */
+    feeds: v.optional(v.array(v.strictObject({ calendar_id: v.number(), events: count, skipped: count }))),
 });
 export const calendarSyncProgress = v.strictObject({
     calendar_id: id,
@@ -237,6 +243,8 @@ const ANSWERS = {
     "calendars list": { name: "calendar", schema: calendar },
     "calendars sync": { name: "calendar", schema: calendar },
     "calendars unsync": { name: "calendar", schema: calendar },
+    "calendars add": { name: "calendar_feed", schema: calendarFeed },
+    "calendars remove": { name: "calendar_feed_removal", schema: calendarFeedRemoval },
     "calendars busy": { name: "calendar_busy", schema: calendarBusy },
     sync: { name: "calendar_sync", schema: calendarSync },
     "store status": { name: "calendar_sync_progress", schema: calendarSyncProgress },

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

@@ -1,6 +1,7 @@
 import { type Command } from "commander";
 import type { EventStore } from "../../meetings/index.js";
 import type { AccountKey, MessageStore } from "../../store/store.js";
+import { type CalendarFeeds } from "../feeds.js";
 import type { CalendarExpander, CalendarSource } from "../source.js";
 import { type CalendarWrites } from "../writes.js";
 export interface CalendarCommandDeps {
@@ -27,6 +28,11 @@ export interface CalendarCommandDeps {
     serverSearch?: boolean;
     /** For a source with `expands: "local"`. */
     expand?: CalendarExpander;
+    /**
+     * The iCalendar feeds the profile follows, as read-only calendars of its account: mounts `calendars add|remove`,
+     * and `sync` and `calendars list` read them after the provider. Read only once a profile is open.
+     */
+    feeds?: CalendarFeeds;
     /** After `sync --embed`: embeds new events for search by meaning (`embedEvents`), as drive's `sync --embed`. */
     embed?: (max: number) => Promise<{
         model: string;

package/dist/calendar/cli/index.js

@@ -5,19 +5,21 @@ import { clockMeta } from "@wirecat/cli-base/standards";
 import { Argument, InvalidArgumentError, Option } from "commander";
 import { environmentOf, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
-import { ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
+import { changesStore, ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
 import { queryTerms, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
+import { secretInput } from "../../runs/run-context.js";
 import { searchEvents } from "../../services/events-search.js";
 import { dateWindow } from "../../services/moment.js";
 import { linkPeople } from "../../services/people.js";
 import { BUSY_QUERY, BUSY_QUERY_NOTE, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
+import { isFeedCalendar, syncWithFeeds } from "../feeds.js";
 import { eventPreparation, nextMeeting, PREPARE_MESSAGES } from "../prepare.js";
 import { accountsMeta, CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, EVENTS_QUERY, EVENTS_QUERY_NOTE, EXPORT_MAX, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, eventsIcs, peopleAnswer, resolveAnswer, reviewsAnswer, sourceAccounts, weekFilter, } from "../reads.js";
 import { REPEAT_HELP } from "../recurrence.js";
 import { bothSearchAnswer, serverSearchAnswer } from "../server-search.js";
-import { calendarStatus, syncCalendars } from "../sync.js";
+import { calendarStatus } from "../sync.js";
 import { createEvent, createEventFromText, deleteEvent, EVENT_RESPONSES, IMPORT_MAX, importEvents, moveEvent, respondToEvent, updateEvent, } from "../writes.js";
 import { CALENDARS_QUERY, declareCalendarAnswers, PEOPLE_QUERY } from "./answers.js";
 import { addRemind } from "./remind.js";
@@ -28,6 +30,8 @@ const REMOTE_READ = { remote: "read", local: "none" };
 const LOCAL_OR_REMOTE_READ = { remote: "read", local: "read" };
 const REMOTE_WRITE = { remote: "write", local: "write" };
 const GROUP = { remote: "none", local: "none" };
+/** Every time a store can hold, for marking all of a calendar's entries at once. */
+const EVERYWHERE = { from: -8.64e15, to: 8.64e15 };
 /** How many pieces one `sync --embed` embeds, as drive's. */
 const EMBED_MAX = 600;
 // A list's marker goes on each item: a host's list envelope is strict and `--jsonl` prints only the items.
@@ -95,7 +99,8 @@ const addCalendarCommandsDefinition = (program, deps) => {
     const calendars = annotate(program.command("calendars").description("the account's calendars"), { effects: GROUP });
     withQuery(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json", "calendars list synced:true"), CALENDARS_QUERY).action(async (words, _opts, command) => {
         const terms = [...queryTerms(words, CALENDARS_QUERY, "calendars list")];
-        const listed = await deps.store.saveCalendars(deps.accountId, await source().calendars(), now());
+        const found = [...(await source().calendars()), ...((await deps.feeds?.source.calendars()) ?? [])];
+        const listed = await deps.store.saveCalendars(deps.accountId, found, now());
         const items = listed
             .map(calendarItem)
             .filter((item) => terms.every(([field, value]) => String(item[field]) === value));
@@ -112,6 +117,40 @@ const addCalendarCommandsDefinition = (program, deps) => {
             await deps.store.setCalendarSynced(calendar.id, synced, now());
             print(calendarItem({ ...calendar, synced }), command);
         });
+    if (deps.feeds) {
+        const feeds = () => deps.feeds;
+        example(
+        // A fetch, but also a new secret and a new address every later sync reads: the read-only lock refuses it.
+        changesStore(annotate(calendars.command("add"), { effects: FETCH, offline: false, mcp: false }))
+            .description("follow an iCalendar feed, such as a holiday calendar or a published .ics address, as a read-only calendar " +
+            "of this profile; sync reads it again each time. The address is kept as a secret and never printed")
+            .summary("follow an iCalendar feed as a read-only calendar")
+            .addArgument(secretInput(new Argument("<url>", "the feed's https://, http:// or webcal:// address")))
+            .option("--title <title>", "the calendar's title; the feed's own name if not given"), "calendars add webcal://example.com/holidays.ics --title Holidays").action(async (url, opts, command) => {
+            if (command.optsWithGlobals().offline)
+                throw new CliError("permission_error", "calendars add reads the feed; leave out --offline");
+            const { calendar, events } = await feeds().add(url, opts.title === undefined ? {} : { title: opts.title });
+            const [saved] = await deps.store.saveCalendars(deps.accountId, [calendar], now());
+            print({
+                ...calendarItem(saved),
+                events,
+                hint: `run ${lineOf(command, "sync")} to store its events`,
+            }, command);
+        });
+        example(annotate(calendars.command("remove"), { effects: LOCAL_WRITE, mcp: false })
+            .description("stop following a feed calendars add added: its address is forgotten and its stored events go")
+            .argument("<calendar>", "the feed calendar's id, its ics: id, or its title"), "calendars remove 7").action(async (reference, _opts, command) => {
+            const calendar = await calendarIn(deps.store, deps.accountId, reference);
+            if (!isFeedCalendar(calendar))
+                throw new CliError("validation_error", `calendar ${calendar.id} is not a feed; calendars remove takes only feeds`, {
+                    reason: "feed.not-a-feed",
+                });
+            await feeds().remove(calendar.externalId);
+            await deps.store.setCalendarSynced(calendar.id, false, now());
+            const removed = await deps.store.markUnseen(calendar.id, now() + 1, EVERYWHERE, now());
+            print({ ...calendarItem({ ...calendar, synced: false }), removed }, command);
+        });
+    }
     if (deps.freeBusy)
         example(withQuery(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false }).description("when calendars and people are taken, asked of the provider and not stored; with --duration-minutes, " +
             "the free stretches they share"), BUSY_QUERY).addHelpText("after", BUSY_QUERY_NOTE), "calendars busy person:ana@example.com --json", "calendars busy start>=2026-11-02 end<=2026-11-06 person:ana@example.com --duration-minutes 30 " +
@@ -146,7 +185,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
         if (command.optsWithGlobals().full)
             throw new CliError("validation_error", "sync starts over with --rescan; --full only widens output");
         const { signal } = environmentOf(command);
-        const report = await syncCalendars(source(), deps.store, {
+        const report = await syncWithFeeds(source(), deps.feeds, deps.store, {
             accountId: deps.accountId,
             now: now(),
             budget: runBudgetOf(command, opts.maxPages),

package/dist/calendar/cli/remind.js

@@ -14,7 +14,7 @@ import { CALENDAR_WRITE_DEFAULTS, EVENTS_REMIND_HOOK_KEY } from "../writer.js";
 const REMIND_MIN_MS = 60_000;
 const REMIND_MAX_MS = 86_400_000;
 export const addRemind = (events, writes, { deps, now, zone, print, example }) => {
-    const remind = example(destroysNothing(annotate(events.command("remind"), { effects: FETCH, mcp: false }))
+    const remind = example(destroysNothing(annotate(events.command("remind"), { effects: FETCH, mcp: false, literal_after_dashes: true }))
         .description("tell once about each event that starts within --due-within: print it, or run your program for it with the " +
         "event as JSON on its standard input; for cron or a timer every few minutes, syncing first unless --offline")
         .summary("tell once about each event that starts soon, for a timer to run")
@@ -50,6 +50,7 @@ export const addRemind = (events, writes, { deps, now, zone, print, example }) =
         if (!opts.dryRun && deps.source && !command.optsWithGlobals().offline) {
             // A reminder from what the store already holds beats none: a failed sync is said in meta and the run goes on.
             try {
+                // Feeds wait for `sync`: a timer runs this every few minutes, and a feed's server is not Google.
                 const report = await syncCalendars(deps.source, deps.store, {
                     accountId: deps.accountId,
                     now: at,

package/dist/calendar/expand.d.ts

@@ -0,0 +1,17 @@
+import type { EntryInput } from "../meetings/index.js";
+import type { SyncWindow } from "./source.js";
+/**
+ * A wall-clock time in `zone` as epoch ms. A time a clock change skips is read with the offset before the change, so it
+ * lands after it, and a repeated one takes its first moment (RFC 5545 §3.3.5): a slot is moved, never dropped.
+ */
+export declare const localMoment: (date: string, time: string, zone: string) => number;
+/** Why a series cannot be expanded here, or `null` when it can. */
+export declare const unexpandable: (recurrence: readonly string[] | null | undefined) => string | null;
+/**
+ * The slots of a series inside the window, as occurrences: its RRULE, plus RDATE, less EXDATE, which come back
+ * `cancelled` so a stored slot is cancelled. Times repeat in the series' own zone, so a weekly 10:00 stays 10:00
+ * across a clock change. An override (an iCalendar RECURRENCE-ID) takes the place of the slot it names.
+ */
+export declare const expandSeries: (series: EntryInput, window: SyncWindow, overrides?: readonly (EntryInput & {
+    originalStartsAt: number;
+})[]) => EntryInput[];