@wirecat/cli-core 0.550.0 → 0.552.0

package/CHANGELOG.md

@@ -7,6 +7,241 @@ shape of this file.
 
 ## Unreleased
 
+## 0.552.0 — 02.11.2026
+
+### Added
+
+- **`serve` reads back on start what arrived while nothing listened.** A provider's own catch-up drops a gap it
+  finds too long (Telegram's `differenceTooLong`, and `channelDifferenceTooLong` past 100 updates in a channel), so
+  30 seconds after connecting `serve` lists the chats once and reads each chat whose newest message is newer than the
+  newest one held from before it started back to that one; a chat never held, back to the newest message held
+  anywhere. At most 7 days back, 500 messages a chat and 5 minutes; an empty store is left to `messages sync --all`,
+  and a messenger that pushes its history (`history: "store"`) is skipped. The summary gains
+  `caught_up: { chats, fetched, failed, stopped }`; the log gains `start_sync`, `start_sync_chat_failed` and
+  `start_sync_failed`.
+- **A meeting transcript knows its language.** `transcriptInput` (provider fetches and imports) and local
+  transcription fill `language` instead of `null`: a one-language speech model gives its own (`gigaam-v3` and
+  `gigaam-v3-ctc` write Russian, `LocalSpeechRecognitionModel.language`), any other transcript is read from its
+  letters — Cyrillic is `ru` (`uk` when Ukrainian letters show), Latin is told apart by frequent words (`en`, `es`,
+  `de`, `fr`, `it`, `pt`), and a mixed, short or undecided one stays `null`. A meeting that is mostly Russian with a
+  few English lines is `ru`. `transcriptLanguage(texts)` is exported for providers that build their own transcripts.
+- **Meeting search hits say the transcript's language and where in it the line is**: `language`, `line` (from 1) and
+  `lines_total` on transcript hits of `search meetings` and `search all` ("line 161 of 192").
+- **`meetings repair`** previews filling what older builds left out of stored transcripts — their language, for
+  transcripts that have none; `--yes` stores it (`meeting_repair`, `MeetingStore.fillTranscriptLanguages`). Nothing is
+  written on a read.
+
+### Changed — may break callers
+
+- **A search that runs out of time fails with `timeout` and the reason `query.time-limit`**, no longer with
+  `validation_error`, `query.too-large` and `budget: "time"` or `"milliseconds"`. The message says the query is valid
+  and the time limit was reached. The details keep `budget: "time"` and `complete: false`, and add `limit_ms`. A caller
+  that told the person to change the query on `query.too-large` no longer does it for a slow search.
+- **`server install` runs `systemctl --user` (or `launchctl enable`)**, and fails where that does not work, after it
+  wrote the file. **Under launchd `server stop` only unloads the agent**: it starts again at the next login, as a
+  systemd unit does; `server uninstall` stops that. `Platform` (`@wirecat/cli-core/background`) drops `atLogin` and
+  requires `install` and `uninstall`; its `state` may answer `enabled`.
+
+### Fixed
+
+- **A search stops at its time limit even inside one long SQLite statement.** A statement runs to its end before any
+  timer can fire, so a search over a large store ran far past the limit: 66 s against a 2 s limit, and past a
+  command's `--timeout 60s`. Under Node the message search statements now carry a check of the limit on every row
+  (the SQL function `wc_time_limit`) and stop when it passes. Bun has no SQL functions; there the limit is still
+  checked only between statements.
+- **`server install` enables the unit, so serve starts with the owner's session after a reboot.** It wrote the unit
+  and never enabled it, and after a reboot nothing started. Under systemd it runs `systemctl --user enable` (still
+  `WantedBy=default.target`, so it also starts at boot under linger and over ssh); under launchd it clears a
+  `launchctl disable` and the agent no longer carries `Disabled`. Nothing starts now; `server start` does that.
+  A unit written with moved folders (a development checkout) is not enabled, so a branch build never starts at
+  login on the owner's keyring. `server uninstall` disables before it removes the file. `server status` answers
+  `starts_at_login` and `unit.enabled`. A unit installed before this needs `server install` once more.
+- **A timer that fires before the login unlocks the keyring tries again.** A daily or one-off schedule that catches up
+  at boot ran before the keyring was unlocked and failed for the day. `schedule exec` now runs it again when it fails
+  with reason `credentials.unreachable` (tg and max give it when a profile that has logged in here cannot read its
+  sign-in): a minute later, then up to 15 minutes apart, for up to 12 hours, and notifies once, with how it ended.
+  `schedule run` and repeating schedules do not wait. `runSchedule` takes `untilUnlocked` and `wait` for this.
+- **A sync whose reader goes away finishes its work.** A closed stdout or stderr (EPIPE) aborted every command, so a
+  desktop that closed the pipe ended an 18-minute `messages sync` with `write EPIPE`. A cooperative command (a sync)
+  and a command waiting in an `untilStopped()` phase (`schedule run`, `schedule exec`) now keep working, their later
+  output goes nowhere, and the run record says how they ended. Other commands still end with 0, as `| head` expects.
+
+## 0.551.0 — 02.11.2026
+
+### Added
+
+- **`messages sync` keeps to the history limits too**, for every messenger: it does not read a group above
+  `history_group_members_max` people and stops a chat at its window (`history_dialog_days`, `history_group_days`). The
+  answer says `limited` (`group_too_large`, `older_than_window`; `--all` counts both), the skip is recorded for
+  `store status` and the search answers' `missing.history_limits`, and `--full-history` reads past it. Live messages
+  are never dropped.
+- **`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`.
+- **`projects status <project>`: where a project stands, from the store alone, with no model call.** For each chat
+  confirmed as the project's or a child project's, in this profile's account: the last message, who replies next
+  (you, them, a member a message names, or nobody), open questions both ways, promises (stored tasks, promise facts,
+  and first person future words such as "пришлю" or "I'll send"), amounts with their direction and whether a later
+  message says paid, payment facts, how long each `--context-query` (words that all appear in one text) has been
+  quiet on their side, and how much of the chat the store holds. Open amounts are summed per direction and currency. Word matches are marked `basis: pattern`;
+  a message saying "paid" is `paid-mentioned`, never paid. At most two steps: sync the chat held in part, then read
+  the chat that needs you most. The other accounts' linked chats are named in `out_of_scope`. tg and max get it with
+  the `projects` group; `--compact` draws each signal with its own row.
+  - **For an app: `projectStatus(store, input)`, a list of signals in `STATUS_SIGNALS`.** A signal is one file with an
+    id, a version and `read`; one that throws is named in `failed` and the others still answer. Each built in signal
+    has its compact row in `STATUS_SIGNAL_ROWS`, also in `SHARED_ROWS`. `projectStatusAnswer` and `projectStatusText`
+    build the answer and the human form. `input.purposes` picks which chat purposes are read (`["work"]` until links
+    carry one). The `messages.list` step takes a `query`.
+- **`--compact`: one line per item for an agent, from the same answer `--json` prints.** `messages list <chat>
+  --compact` prints `#<id> · 10-01 09:12 · Анна · <text>` under one header line that names the shared ref prefix
+  (`ref: msg:max/500/-1001/<id>`), what every row has in common (the chat's title), the date span and the zone. Rows
+  from several chats keep their whole refs. Text stays on one line with control and direction characters made
+  visible, and is cut at 400 characters with `…(+N)`; `--full` keeps it whole. The paging, `missing`, the next steps
+  and an incomplete answer follow as `# more:`, `# missing:`, `# next:` and `# complete: false` lines on stdout, and
+  each command line in them carries `--compact` again. On 1 000 messages of one chat it is about 48 % of the JSON
+  bytes; the texts alone are 40 %. `--compact` with `--json`, `--json=…`, `--jsonl` or `--brief` fails with
+  `validation_error` (`output.conflict`); it never prompts, and exits with the code JSON would. MCP keeps JSON.
+  - **Every command that answers through `renderAnswer` gets it.** A command draws with its own row
+    (`answerEntity(cmd, name, schema, { row })`), its app's (`rows: { name: shape }` in the program definition,
+    which also draws an app entity listed inside one thing), the shared one in `SHARED_ROWS` (`message`,
+    `message.summary`, `message.hit`, `chat`), or the generic row: key, ref or id · title, name or path · state,
+    status or due date · text. A record or a list is never printed as a column's value. `RowShape` is data, and `compactText(body, shape,
+    options)` is pure, for an app that prints its own answers.
+  - What a command prints without `renderAnswer` stays JSON under `--compact`.
+- **`scanProjectLinks(store, { project, sources, since, write, scorers?, threshold?, limit?, purposes? })` and
+  `LinkScorer` (`@wirecat/cli-core/services`): memo proposes a project's chats, mail threads and people itself.**
+  Six scorers in `SCORERS` (`chat-title`, `alias-hits`, `member-chats`, `member-dialog`, `chat-senders`,
+  `mail-thread`) and the shared mail domain rule as `email-domain` in `PERSON_SCORERS`. Signals combine as
+  1 − Π(1 − w); at most 20 new proposals a run by the rule bot `memo-scan`, never confirmed by themselves. Each
+  carries `score` and `signals` (scorer, weight, why: ids and counts only). Linked and rejected pairs are skipped,
+  a pending one is updated in place; people are matched by identity only, never by name. `write: false` writes nothing.
+- **`knowledge.relationState(scope, { from, to, kind })`** says whether a link joins a pair, whether a proposal for it
+  was rejected, and which one is pending; `proposeRelation` takes `score` and `signals`.
+- **Payments are facts of type `payment`.** The amount (text, two decimals), ISO 4217 currency, direction (`to_us` or
+  `from_us`), counterparty ref or name, due date, state (`expected`, `paid`, `cancelled`) and item ride in
+  `metadata.payment`, read back as `Fact.payment`; no migration. A payment fact cites 1 to 8 references. Paid is a new
+  fact that supersedes the expected one, so the history stays. Only the owner accepts or rejects a payment:
+  `mayDecide` takes `ownerOnly`. `facts.list({ payment: { open, direction, state } })` filters them; `open` is
+  expected and still holding. `paymentTitle(fact)` reads "1 200 EUR to us from Ana, due 31.10 (expected)".
+  - **Agents stage payments as findings of kind `payment`** in `projects actions add`; confirming one writes and
+    accepts the fact, and a batch holding one is the owner's to decide. The inbox summarises each finding through
+    `FACT_SUMMARIES`, one row per kind. `projects status` lists payment facts with their title and adds the expected
+    ones to `money.open`, counting an ask the fact cites once.
+  - **For an app's `facts list`: `PAYMENT_QUERY_FIELDS` (`open:true`, `direction:to_us`, `state:paid`) and
+    `paymentFilterOf(terms)`.**
+
+### 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)`).
+- **cli-core now needs `@wirecat/cli-base` 0.75.0**, which holds the `--full-history` switch's name and the help
+  without `OR` for a list its provider filters. A CLI that pins cli-base bumps it to 0.75.0 together with cli-core.
+- **`FACT_TYPES` gains `payment`, and a `Finding` may be a `PaymentFinding`.** A caller that lists facts with a fixed
+  type list, or reads `finding.title` on every finding that is not a fact, narrows by `kind` first. A memo older than
+  this release refuses a payment fact in `facts list`; ship memo's bump the same day. `MEETING_FACT_TYPES` is gone:
+  `FACT_TYPES` is the one list.
+
+### Fixed
+
+- **`messages delete` with no message id refuses with `validation_error`** before it connects. An empty id (`""`
+  or a lone comma) used to reach the messenger as a deletion of nothing and answer success.
+- **An MCP read or write whose answer named a step only the person can take (`user_action`) failed as a bug.** The
+  router dropped next steps this server does not offer by their command, and such a step has none. It is kept now;
+  a command step this server does not offer is still dropped.
+- **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.
+- **`--brief` now cuts a messenger search hit.** It only knew mail's camelCase hits, so `search messages --brief` in
+  tg, max and wa printed every field; it now keeps `ref`, `chat_title`, `timestamp`, `sender_name`, `excerpt` and
+  `score`. The default and `--full` answers are unchanged. Commands that print through `outputFor` now honour
+  `--brief` and `--full` too, and refuse them together as the others do.
+- **An Outlook or Exchange feed's events are read, no longer skipped.** Those feeds name time zones the Windows way,
+  `TZID:W. Europe Standard Time`, and the iCalendar reader took only IANA names (`Europe/Berlin`), so `calendars add`
+  and `sync` skipped every timed event of such a feed and counted it under `skipped`. A Windows name is now read as
+  the IANA zone Unicode CLDR gives it worldwide (territory `001`), in DTSTART, DTEND, RECURRENCE-ID, and in the TZID of
+  RDATE and EXDATE, which are stored with the IANA name. The 142 names are a table generated from CLDR release-49
+  (`scripts/windows-zones.ts` regenerates it); no new dependency. A TZID that is neither, such as Outlook's
+  `(UTC+01:00) Amsterdam, Berlin, Bern`, is still skipped.
+- **A list whose provider filters it no longer says in `--help` that its query takes `OR`.** With
+  `@wirecat/cli-base` 0.74.0 → 0.75.0, its `Syntax:` line names only what it takes: `field:value` terms joined by AND,
+  and the phrase, `word*` and range forms where a field takes them. Every CLI picks this up at its next cli-core bump.
+- **The browser login page of `mcp serve --http` names what the app asks to reach and the right command.** It always
+  said "reach your messages through `<app> mcp --http`"; a CLI that is not a messenger now says what it serves (gcal:
+  "your Google Calendar"), and every CLI names `<app> mcp serve --http`. `HttpOptions` takes `reaches` for the
+  wording; unset, the page says "your `<app>` data".
+- **`store jobs list` says in its help and its MCP description that its query takes `OR`.** The list reads every job
+  file and takes the whole query language, but its registry said the source filters it (`native`).
+
 ## 0.550.0 — 02.11.2026
 
 ### Changed — may break callers

package/README.md

@@ -172,7 +172,7 @@ run a read, run a write — so an agent's context does not fill with a hundred t
 over HTTP on 127.0.0.1 behind the owner's tunnel, with a one-owner OAuth login.
 
 `serve` keeps the store current, one process per profile by a lock file; `server install` adds a systemd user unit
-or a launchd agent.
+or a launchd agent that starts at every login.
 
 ### Every write behind a guard
 

package/THIRD_PARTY_NOTICES

@@ -758,3 +758,44 @@ Licensed under SIL Open Font License 1.1; see dist/charts/fonts/OFL.txt and SOUR
 
 PNG rasterization uses @resvg/resvg-js under MPL-2.0. Its original sources are
 available at https://github.com/thx/resvg-js/tree/v2.6.2.
+
+Windows time zone names mapped to IANA zones (dist/calendar/windows-zones.generated.js), generated from
+Unicode CLDR release-49, common/supplemental/windowsZones.xml (https://github.com/unicode-org/cldr).
+
+Copyright © 2001–2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.
+
+SPDX-License-Identifier: Unicode-3.0

package/dist/background/schedules.d.ts

@@ -97,14 +97,25 @@ export declare const timerFor: (app: AppIdentity, system: ServerSystem, env: Nod
 export declare const notify: (system: ServerSystem, env: NodeJS.ProcessEnv, title: string, body: string) => Promise<boolean>;
 /** Finds a program on PATH, as the timer will not have the shell's PATH to find it by. */
 export declare const findProgram: (name: string, env: NodeJS.ProcessEnv, platform: NodeJS.Platform) => string | undefined;
+/**
+ * The reason tg and max give when a profile that has logged in here cannot read its sign-in: the keyring is
+ * locked or out of reach, which a later try fixes and a new login does not.
+ */
+export declare const CREDENTIALS_UNREACHABLE = "credentials.unreachable";
 /**
  * One run: the command or the agent with the schedule's variables, its output kept beside the schedule,
  * the last result in `last.json`. An agent runs under `<PREFIX>_READ_ONLY`, so nothing it is talked
  * into can send. A one-off removes itself afterwards.
+ *
+ * `untilUnlocked` is for the timer's run: a timer that catches up at boot runs before the login unlocks the
+ * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
+ * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, }?: {
+export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, untilUnlocked, wait, }?: {
     now?: () => Date;
     timer?: Timer;
     signal?: AbortSignal;
     killAfterMs?: number;
+    untilUnlocked?: boolean;
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }) => Promise<LastRun>;

package/dist/background/schedules.js

@@ -328,16 +328,79 @@ export const findProgram = (name, env, platform) => {
 const KEEP_RUNS = 30;
 /** How long a stopped child has to save and answer after SIGTERM before it is killed. */
 const KILL_AFTER_MS = 10_000;
+/**
+ * The reason tg and max give when a profile that has logged in here cannot read its sign-in: the keyring is
+ * locked or out of reach, which a later try fixes and a new login does not.
+ */
+export const CREDENTIALS_UNREACHABLE = "credentials.unreachable";
+const LOCKED_FIRST_WAIT_MS = 60_000;
+const LOCKED_LONGEST_WAIT_MS = 15 * 60_000;
+/** A night's catch-up waits for the morning's login; past that the run fails as it is. */
+const LOCKED_GIVE_UP_MS = 12 * 60 * 60_000;
+const lockedOut = (last) => last.reason?.endsWith(`(${CREDENTIALS_UNREACHABLE})`) === true;
+const pause = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
 /**
  * One run: the command or the agent with the schedule's variables, its output kept beside the schedule,
  * the last result in `last.json`. An agent runs under `<PREFIX>_READ_ONLY`, so nothing it is talked
  * into can send. A one-off removes itself afterwards.
+ *
+ * `untilUnlocked` is for the timer's run: a timer that catches up at boot runs before the login unlocks the
+ * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
+ * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, } = {}) => {
+export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, untilUnlocked = false, wait = pause, } = {}) => {
     const schedule = readSchedule(file);
     const folder = join(file, "..");
     const runs = join(folder, "runs");
     mkdirSync(runs, { recursive: true, mode: 0o700 });
+    const agent = schedule.kind === "agent";
+    const retries = untilUnlocked && !("every" in schedule.when);
+    const firstAt = now().getTime();
+    let last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs });
+    for (let delay = LOCKED_FIRST_WAIT_MS; retries && lockedOut(last) && !signal?.aborted && now().getTime() - firstAt + delay <= LOCKED_GIVE_UP_MS; delay = Math.min(delay * 2, LOCKED_LONGEST_WAIT_MS)) {
+        await wait(delay, signal);
+        if (signal?.aborted)
+            break;
+        last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs });
+    }
+    const { exitCode, output } = last;
+    const errors = agent ? output.replace(/\.md$/, ".log") : output;
+    if (agent && exitCode === 0)
+        copyFileSync(output, join(folder, "latest.md"));
+    const stampOf = (file) => file.split(".")[0] ?? file;
+    const kept = new Set([...new Set(readdirSync(runs).map(stampOf))].sort().slice(-KEEP_RUNS));
+    for (const file of readdirSync(runs))
+        if (!kept.has(stampOf(file)))
+            rmSync(join(runs, file), { force: true });
+    const title = `${app.command} ${schedule.name}`;
+    if (agent && exitCode === 0) {
+        const first = readFileSync(output, "utf8")
+            .split("\n")
+            .find((line) => line.trim()) ?? "report ready";
+        await notify(system, env, title, `${first.trim().slice(0, 180)}\n${join(folder, "latest.md")}`);
+    }
+    else if (exitCode !== 0) {
+        await notify(system, env, title, `failed (exit ${exitCode}) — ${errors}`);
+    }
+    if ("once" in schedule.when) {
+        await timer?.remove(schedule.name);
+        rmSync(file, { force: true });
+    }
+    return last;
+};
+/** One run of the schedule's command or agent: its output in `runs/`, its result in `last.json`. */
+const attemptSchedule = async (app, system, env, schedule, folder, { now, signal, killAfterMs }) => {
+    const runs = join(folder, "runs");
     const stamp = now()
         .toISOString()
         .replaceAll(":", "-")
@@ -398,33 +461,11 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
         exitCode,
         durationMs: ended.getTime() - began,
     });
-    const last = recordRun(join(folder, "last.json"), {
+    return recordRun(join(folder, "last.json"), {
         at: ended.toISOString(),
         exitCode,
         output,
         traceId: trace.traceId,
         ...(exitCode === 0 ? {} : failureOf(readFileSync(errors, "utf8"), exitCode)),
     });
-    if (agent && exitCode === 0)
-        copyFileSync(output, join(folder, "latest.md"));
-    const stampOf = (file) => file.split(".")[0] ?? file;
-    const kept = new Set([...new Set(readdirSync(runs).map(stampOf))].sort().slice(-KEEP_RUNS));
-    for (const file of readdirSync(runs))
-        if (!kept.has(stampOf(file)))
-            rmSync(join(runs, file), { force: true });
-    const title = `${app.command} ${schedule.name}`;
-    if (agent && exitCode === 0) {
-        const first = readFileSync(output, "utf8")
-            .split("\n")
-            .find((line) => line.trim()) ?? "report ready";
-        await notify(system, env, title, `${first.trim().slice(0, 180)}\n${join(folder, "latest.md")}`);
-    }
-    else if (exitCode !== 0) {
-        await notify(system, env, title, `failed (exit ${exitCode}) — ${errors}`);
-    }
-    if ("once" in schedule.when) {
-        await timer?.remove(schedule.name);
-        rmSync(file, { force: true });
-    }
-    return last;
 };

package/dist/background/units.d.ts

@@ -33,21 +33,28 @@ export interface Platform {
     text: (unit: Unit, app: AppIdentity) => string;
     start: (unit: Unit) => string[][];
     stop: (unit: Unit) => string[][];
-    state: (unit: Unit) => Promise<{
-        loaded: boolean;
-        active: boolean;
-        pid?: number;
-        detail?: string;
-        exitCode?: number;
-    }>;
+    state: (unit: Unit) => Promise<UnitState>;
     logs: (unit: Unit, lines: number) => Promise<string>;
     /** What must exist before the unit first runs. */
     prepare?: (unit: Unit) => void;
-    /** How to have it start at every login too. */
-    atLogin: (unit: Unit) => string;
+    /** Run once the file is written: the unit starts with every login from then on, and nothing starts now. */
+    install: (unit: Unit) => string[][];
+    /** Run before the file is removed: it no longer starts at login. */
+    uninstall: (unit: Unit) => string[][];
+}
+export interface UnitState {
+    loaded: boolean;
+    active: boolean;
+    /** It starts with the owner's session: at login, or at boot when systemd keeps the user's services (linger). */
+    enabled?: boolean;
+    pid?: number;
+    detail?: string;
+    exitCode?: number;
 }
 export declare const systemd: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv) => Platform;
 export declare const launchd: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv) => Platform;
+/** `launchctl print-disabled` lists overrides as `"label" => disabled` (older macOS: `=> true`); none is enabled. */
+export declare const launchdEnabled: (listing: string, label: string) => boolean;
 /**
  * serve's log lines for a person: a log record as `time severity body`, anything else — a line from an
  * older serve, the summary it prints on stop — as it is. A journal's own prefix is kept.

package/dist/background/units.js

@@ -61,9 +61,16 @@ export const systemd = (app, system, env) => {
             ...(unit.noRestartOn?.length ? [`RestartPreventExitStatus=${unit.noRestartOn.join(" ")}`] : []),
             "",
             "[Install]",
+            // Not graphical-session.target: a desktop without systemd's session targets, or a machine reached only
+            // over ssh, would never start it. A keyring still locked at boot ends serve with a code that restarts.
             "WantedBy=default.target",
             "",
         ].join("\n"),
+        install: (unit) => [
+            ["systemctl", "--user", "daemon-reload"],
+            ["systemctl", "--user", "enable", unit.name],
+        ],
+        uninstall: (unit) => [["systemctl", "--user", "disable", unit.name]],
         start: (unit) => [
             ["systemctl", "--user", "daemon-reload"],
             ["systemctl", "--user", "start", unit.name],
@@ -87,6 +94,8 @@ export const systemd = (app, system, env) => {
                 "ExecMainCode",
                 "-p",
                 "ExecMainStatus",
+                "-p",
+                "UnitFileState",
             ], env);
             const fields = Object.fromEntries(ran.stdout
                 .split("\n")
@@ -98,13 +107,13 @@ export const systemd = (app, system, env) => {
             return {
                 loaded: fields.LoadState === "loaded",
                 active: fields.ActiveState === "active",
+                ...(fields.UnitFileState ? { enabled: fields.UnitFileState === "enabled" } : {}),
                 ...(pid > 0 ? { pid } : {}),
                 ...(exitCode > 0 ? { exitCode } : {}),
                 ...(fields.ActiveState ? { detail: `${fields.ActiveState} (${fields.SubState})` } : {}),
             };
         },
         logs: (unit, lines) => checked(["journalctl", "--user", "-u", unit.name, "-n", String(lines), "--no-pager"]),
-        atLogin: (unit) => `at every login too: systemctl --user enable ${unit.name.replace(/\.service$/, "")}`,
     };
 };
 const xml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
@@ -130,8 +139,6 @@ export const launchd = (app, system, env) => {
             "  <dict>",
             ...Object.entries(unit.environment).map(([name, value]) => `    <key>${xml(name)}</key><string>${xml(value)}</string>`),
             "  </dict>",
-            // launchd loads every agent here at login; disabled, it waits for `server start` to enable it.
-            "  <key>Disabled</key><true/>",
             // biome-ignore lint/security/noSecrets: launchd plist template, not a key
             "  <key>RunAtLoad</key><true/>",
             ...(unit.noRestartOn?.length ? [] : ["  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>"]),
@@ -142,25 +149,27 @@ export const launchd = (app, system, env) => {
             "</plist>",
             "",
         ].join("\n"),
-        // RunAtLoad makes loading the agent the start; `enable` overrides the file's Disabled until `disable`.
+        // launchd loads every agent in the folder at login, RunAtLoad starts it; `enable` clears a `disable` left by
+        // an older stop or uninstall, which would outrank the file.
+        install: (unit) => [["launchctl", "enable", `${domain}/${unit.name}`]],
+        uninstall: (unit) => [["launchctl", "disable", `${domain}/${unit.name}`]],
         start: (unit) => [
             ["launchctl", "enable", `${domain}/${unit.name}`],
             ["launchctl", "bootstrap", domain, unit.path],
         ],
-        stop: (unit) => [
-            ["launchctl", "bootout", `${domain}/${unit.name}`],
-            ["launchctl", "disable", `${domain}/${unit.name}`],
-        ],
+        stop: (unit) => [["launchctl", "bootout", `${domain}/${unit.name}`]],
         state: async (unit) => {
+            const enabled = launchdEnabled((await system.run(["launchctl", "print-disabled", domain], env)).stdout, unit.name);
             const ran = await system.run(["launchctl", "print", `${domain}/${unit.name}`], env);
             if (ran.code !== 0)
-                return { loaded: false, active: false };
+                return { loaded: false, active: false, enabled };
             const state = /^\s*state = (.+)$/m.exec(ran.stdout)?.[1]?.trim();
             const pid = Number(/^\s*pid = (\d+)$/m.exec(ran.stdout)?.[1]);
             const exitCode = Number(/^\s*last exit code = (\d+)/m.exec(ran.stdout)?.[1]);
             return {
                 loaded: true,
                 active: state === "running",
+                enabled,
                 ...(pid > 0 ? { pid } : {}),
                 ...(exitCode > 0 ? { exitCode } : {}),
                 ...(state ? { detail: state } : {}),
@@ -172,9 +181,14 @@ export const launchd = (app, system, env) => {
                 mkdirSync(dirname(unit.logPath), { recursive: true, mode: 0o700 });
         },
         logs: async (unit, lines) => tail(unit.logPath, lines),
-        atLogin: (unit) => `from then on it also starts at every login, until \`${app.command} ${unit.profile} server stop\``,
     };
 };
+/** `launchctl print-disabled` lists overrides as `"label" => disabled` (older macOS: `=> true`); none is enabled. */
+export const launchdEnabled = (listing, label) => {
+    const quoted = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const value = new RegExp(`"${quoted}"\\s*=>\\s*(\\w+)`).exec(listing)?.[1];
+    return value !== "disabled" && value !== "true";
+};
 /**
  * serve's log lines for a person: a log record as `time severity body`, anything else — a line from an
  * older serve, the summary it prints on stop — as it is. A journal's own prefix is kept.
@@ -207,9 +221,10 @@ export const noUnits = (app, system) => {
         text: refuse,
         start: refuse,
         stop: refuse,
+        install: refuse,
+        uninstall: refuse,
         state: async () => ({ loaded: false, active: false }),
         logs: async () => "",
-        atLogin: () => "",
     };
 };
 export const platformFor = (app, system, env) => {

package/dist/calendar/ics.d.ts

@@ -2,7 +2,7 @@ import type { EntryStatus, EntryTransparency, ParticipantResponse } from "../mee
 /**
  * The part of iCalendar (RFC 5545, https://www.rfc-editor.org/rfc/rfc5545) the calendar commands read and write: one
  * VCALENDAR of VEVENTs, with no VTIMEZONE. Times are written in UTC; a time read with a TZID keeps that zone's name,
- * which the provider takes as it is.
+ * which the provider takes as it is. A Windows zone name, as Outlook and Exchange write it, is read as its IANA zone.
  */
 export interface IcsEvent {
     uid: string;

package/dist/calendar/ics.js

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { zonedMoment } from "@wirecat/cli-base/query";
+import { WINDOWS_ZONES } from "./windows-zones.generated.js";
 const CRLF = "\r\n";
 const LINE_OCTETS = 75;
 const escapeText = (text) => text
@@ -129,6 +130,8 @@ const contentLine = (line) => {
 const unescapeText = (text) => text.replace(/\\([\\;,nN])/gu, (_match, char) => (char === "n" || char === "N" ? "\n" : char));
 const DATE = /^(\d{4})(\d{2})(\d{2})$/u;
 const DATE_TIME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z?)$/u;
+/** `W. Europe Standard Time` → `Europe/Berlin`, CLDR's zone for the name worldwide; any other TZID as written. */
+const ianaZone = (tzid) => (Object.hasOwn(WINDOWS_ZONES, tzid) ? WINDOWS_ZONES[tzid] : tzid);
 /** A DATE or DATE-TIME: UTC with `Z`, in its TZID, or floating, read in `zone`. */
 const momentOf = (line, zone) => {
     const value = line.value.trim();
@@ -146,7 +149,7 @@ const momentOf = (line, zone) => {
     if (utc)
         return { at: Date.parse(`${local}Z`), zone: "UTC" };
     const named = line.params.TZID;
-    const where = named ?? zone;
+    const where = named === undefined ? zone : ianaZone(named);
     try {
         return { at: zonedMoment(local, where, { start: 0, end: local.length }), zone: where };
     }
@@ -231,7 +234,7 @@ const eventOf = (lines, zone, overrides = false) => {
     const recurrence = lines
         .filter(({ name }) => ["RRULE", "RDATE", "EXDATE"].includes(name))
         .map(({ name, params, value }) => {
-        const kept = Object.entries(params).map(([key, param]) => `;${key}=${paramValue(param)}`);
+        const kept = Object.entries(params).map(([key, param]) => `;${key}=${paramValue(key === "TZID" ? ianaZone(param) : param)}`);
         return `${name}${kept.join("")}:${value.trim()}`;
     });
     if (recurrence.length)