@wirecat/cli-core 0.541.0 → 0.543.0

package/CHANGELOG.md

@@ -5,7 +5,45 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.543.0 — 02.11.2026
+
+### Added
+
+- **`events remind`: tell once about each event that starts soon, for cron or a timer to run every few minutes**,
+  as gcalcli's `remind` is run. It syncs first unless `--offline`, then takes the events that start within
+  `--due-within <duration>` (`10m` if not given, `1m` to `1d`) and take the owner's time: timed, not cancelled, not
+  declined, no focus time, out-of-office or working location. It prints each one, or, after `--`, runs the owner's
+  program once per event, with the event as JSON on its standard input and `<PREFIX>_EVENT=event:<id>` and
+  `<PREFIX>_PROFILE` in its environment. The program runs without a shell, and the event's text is never on its
+  command line: an invitation is a stranger's text. A program still running after 60 s is stopped.
+  - What was reminded is kept per profile in `<state>/checkpoints/<profile>/events-remind.json` (0600), one key per
+    event and start, so a moved meeting is reminded again. An event whose program failed is not kept, and the next
+    run tries it again; the answer is then `configuration_error` (`remind.hook-failed`). A lock keeps two runs from
+    reminding the same event. `--dry-run` runs, syncs and remembers nothing.
+  - A failed sync does not stop it: the answer says so in `meta.issues` and reminds from the store.
+  - The command needs the CLI's `writes` (`CalendarCommandDeps.writes`), whose settings it reads. It is never an MCP
+    tool.
+- **`EVENTS_REMIND_HOOK_KEY` (`events.remind.hook`), in `CALENDAR_WRITE_KEYS` and `CALENDAR_WRITE_DEFAULTS` as
+  `deny`.** Running a program is a big permission, and `ask` would not be enough: `--yes` answers `ask`, and anything
+  that can type a command can add it. The owner allows it with `config set permissions.events.remind.hook allow`.
+  Under `<PREFIX>_READ_ONLY` the program never runs, whatever the level.
+- **A pushed history batch tells its messenger whether it was saved.** `feed` and `listenHistory` take a
+  `HistoryBatchHandler`, `(batch) => void | Promise<boolean>`: the CLI's own handler resolves `true` once the batch is
+  in the local store and `false` when it could not be written, so an adapter can keep a batch it cannot get again
+  until it is stored. An adapter that ignores the answer works as before.
+
+### Changed — may break callers
+
+- **`@wirecat/cli-base` 0.73.0**, for the verb `remind`. The peer range is now `>=0.73.0 <0.74.0`.
+
+## 0.542.0 — 02.11.2026
+
+### Added
+
+- **`redirect: { kind: "loopback", host: "localhost" }` signs in through `http://localhost:<port>/callback`.** Microsoft
+  Entra ignores the port only for `localhost` redirect URIs, so a public-client app registered as
+  `http://localhost/callback` needs it. The listener then takes `127.0.0.1` and, when the host has IPv6, `::1`, because
+  the browser may resolve `localhost` to either. Without `host` nothing changes: Google and the rest keep `127.0.0.1`.
 
 ## 0.541.0 — 02.11.2026
 

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

@@ -157,6 +157,25 @@ export declare const calendarEvent: v.StrictObjectSchema<{
     }, undefined>, undefined>;
     readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;
+export declare const calendarReminder: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly event_series_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly description: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly starts_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 ends_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 timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly origin: v.PicklistSchema<["auto", "owner", "calendar"], undefined>;
+    readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly all_day: v.BooleanSchema<undefined>;
+    readonly source_deleted_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 deleted_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 created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly ref: v.StringSchema<undefined>;
+}, undefined>;
 /**
  * A hit of the stored search (with `--backend both`, `server` too when the provider also found it), or one the
  * provider's own search found and nothing stored.

package/dist/calendar/cli/answers.js

@@ -127,6 +127,9 @@ export const calendarEvent = v.strictObject({
     })),
     untrusted,
 });
+/** One event `events remind` told about: the event, its reference, and the fields a stranger wrote. */
+const { change: _change, changed_at: _changedAt, was: _was, overlapping: _overlapping, overlaps: _overlaps, ...listed } = event.entries;
+export const calendarReminder = v.strictObject({ ...listed, ref: text });
 const hitFields = {
     provider: nullableText,
     account: nullableText,
@@ -241,6 +244,7 @@ const ANSWERS = {
     "events show": { name: "calendar_event", schema: calendarEvent },
     "events prepare": { name: "calendar_event_preparation", schema: calendarEventPreparation },
     "events export": { name: "calendar_export", schema: calendarExport },
+    "events remind": { name: "calendar_reminder", schema: calendarReminder },
     "events import": { name: "calendar_import", schema: calendarImport },
     "events create": { name: "calendar_event_write", schema: calendarEventWrite },
     "events update": { name: "calendar_event_write", schema: calendarEventWrite },

package/dist/calendar/cli/index.js

@@ -20,6 +20,7 @@ import { bothSearchAnswer, serverSearchAnswer } from "../server-search.js";
 import { calendarStatus, syncCalendars } 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";
 const LOCAL_READ = { remote: "none", local: "read" };
 const LOCAL_WRITE = { remote: "none", local: "write" };
 const FETCH = { remote: "read", local: "write" };
@@ -300,6 +301,8 @@ const addCalendarCommandsDefinition = (program, deps) => {
         });
         print({ ...prepared, meta: { ...meta, ...window.meta, ...clockMeta(now(), zone()) } }, command);
     });
+    if (deps.writes)
+        addRemind(events, deps.writes, { deps, now, zone, print, example });
     const searches = annotate(program.command("search").description("find stored things by text: events"), {
         effects: GROUP,
     });

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

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+import type { CalendarWrites } from "../writes.js";
+import type { CalendarCommandDeps } from "./index.js";
+interface RemindHelpers {
+    deps: CalendarCommandDeps;
+    now: () => number;
+    zone: () => string;
+    print: (value: unknown, command: Command) => void;
+    example: (command: Command, ...lines: string[]) => Command;
+}
+export declare const addRemind: (events: Command, writes: CalendarWrites, { deps, now, zone, print, example }: RemindHelpers) => void;
+export {};

package/dist/calendar/cli/remind.js

@@ -0,0 +1,115 @@
+import { CliError, resolvePaths } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { clockMeta } from "@wirecat/cli-base/standards";
+import { runBudgetOf } from "../../cli/context.js";
+import { destroysNothing, FETCH } from "../../cli/effects.js";
+import { terminalAsker } from "../../cli/messenger/ask.js";
+import { parseDuration } from "../../domain/duration.js";
+import { readOnlyRefusal } from "../../ports/app.js";
+import { levelRefusal } from "../../sends/guard.js";
+import { DEFAULT_PERMISSIONS, levelFor } from "../../sends/permissions.js";
+import { dueEvents, openReminders, reminderItem, remindersPath, runHook } from "../remind.js";
+import { syncCalendars } from "../sync.js";
+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 }))
+        .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")
+        .argument("[program...]", "after --: the program to run for each event, and its own arguments; no shell. Needs events.remind.hook " +
+        "allowed"), "events remind --due-within 10m", "events remind --due-within 15m -- /home/me/bin/meeting-reminder")
+        .option("--due-within <duration>", "the events that start within this long from now, 1m to 1d", "10m")
+        .option("--dry-run", "say what it would remind; run nothing, sync nothing, remember nothing");
+    remind.action(async (program, opts, command) => {
+        const within = parseDuration(opts.dueWithin, "--due-within");
+        if (within < REMIND_MIN_MS || within > REMIND_MAX_MS)
+            throw new CliError("validation_error", "--due-within takes 1m to 1d", { reason: "remind.window" });
+        const settings = writes.settings();
+        const env = writes.env ?? process.env;
+        const hook = program.length > 0;
+        const defaults = { ...DEFAULT_PERMISSIONS, ...CALENDAR_WRITE_DEFAULTS, ...settings.permissionDefaults };
+        const { level, key: named } = levelFor(settings.permissions, EVENTS_REMIND_HOOK_KEY, defaults);
+        if (hook && !opts.dryRun) {
+            if (settings.readOnlyLock)
+                throw readOnlyRefusal(settings.readOnlyLock, "run a program for a reminder");
+            if (level === "deny" || level === "readonly")
+                throw levelRefusal({
+                    profile: settings.profile,
+                    command: writes.app.command,
+                    key: EVENTS_REMIND_HOOK_KEY,
+                    level,
+                    named,
+                    permissionSources: settings.permissionSources,
+                });
+        }
+        const at = now();
+        const issues = [];
+        const accountName = `${deps.account.provider}:${deps.account.account}`;
+        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 {
+                const report = await syncCalendars(deps.source, deps.store, {
+                    accountId: deps.accountId,
+                    now: at,
+                    budget: runBudgetOf(command),
+                    ...(deps.expand ? { expand: deps.expand } : {}),
+                });
+                if (report.synced.some((one) => one.error !== undefined))
+                    issues.push({ code: "provider_error", reason: "sync.partial", source: accountName });
+            }
+            catch (error) {
+                issues.push({
+                    code: error instanceof CliError ? error.code : "provider_error",
+                    reason: "sync.failed",
+                    source: accountName,
+                });
+            }
+        }
+        const window = { from: at, to: at + within };
+        const path = remindersPath(resolvePaths({ appName: writes.app.appName, prefix: writes.app.envPrefix, env }).state, settings.profile);
+        const reminders = opts.dryRun ? undefined : openReminders(path, at);
+        try {
+            const due = await dueEvents(deps.store, deps.accountId, window, reminders?.reminded ?? {});
+            if (hook && !opts.dryRun && due.length > 0 && level === "ask")
+                await terminalAsker(command)(EVENTS_REMIND_HOOK_KEY, { chatId: null, count: due.length });
+            const items = [];
+            const failed = [];
+            for (const details of due) {
+                const item = reminderItem(details);
+                if (hook && !opts.dryRun) {
+                    const exitCode = await runHook(program, `${JSON.stringify(item)}\n`, {
+                        ...env,
+                        [`${writes.app.envPrefix}_PROFILE`]: settings.profile,
+                        [`${writes.app.envPrefix}_EVENT`]: item.ref,
+                    });
+                    if (exitCode !== 0) {
+                        failed.push({ ref: item.ref, exit_code: exitCode });
+                        continue;
+                    }
+                }
+                reminders?.remember(details);
+                items.push(item);
+            }
+            if (failed.length)
+                throw new CliError("configuration_error", `${program[0]} failed for ${failed.length} of ${due.length} events ` +
+                    `(${failed.map((one) => `${one.ref}: exit ${one.exit_code}`).join(", ")}); the next run tries them again`, { reason: "remind.hook-failed", reminded: items.map(({ ref }) => ref), failed, retryable: true });
+            print({
+                items,
+                page: 1,
+                limit: Math.max(1, items.length),
+                hasMore: false,
+                meta: {
+                    complete: issues.length === 0,
+                    ...(issues.length ? { issues } : {}),
+                    window: { since: new Date(window.from).toISOString(), until: new Date(window.to).toISOString() },
+                    ...clockMeta(at, zone()),
+                },
+            }, command);
+        }
+        finally {
+            reminders?.close();
+        }
+    });
+};

package/dist/calendar/index.d.ts

@@ -3,5 +3,5 @@ export { type IcsEvent, type IcsSkip, readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export type { BusyTimes, CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, FreeBusyRequest, SearchPage, SyncWindow, } from "./source.js";
 export { type CalendarCursor, type CalendarSyncOptions, type CalendarSyncReport, type CalendarSyncResult, calendarStatus, calendarSyncWindow, type PendingRound, parseCalendarCursor, syncCalendars, } from "./sync.js";
-export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, type CalendarWrite, type CalendarWriter, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, type EventDraft, type EventPatch, type EventResponse, type FollowingScope, type WriteScope, } from "./writer.js";
+export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, type CalendarWrite, type CalendarWriter, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, EVENTS_REMIND_HOOK_KEY, type EventDraft, type EventPatch, type EventResponse, type FollowingScope, type WriteScope, } from "./writer.js";
 export type { CalendarWrites } from "./writes.js";

package/dist/calendar/index.js

@@ -1,4 +1,4 @@
 export { readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export { calendarStatus, calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";
-export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, } from "./writer.js";
+export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, EVENTS_REMIND_HOOK_KEY, } from "./writer.js";

package/dist/calendar/prepare.d.ts

@@ -7,6 +7,11 @@ export declare const PREPARE_MESSAGES = 5;
 /** Attendees past this many are listed without their messages: a meeting of fifty would not fit any budget. */
 export declare const PREPARE_PEOPLE = 10;
 export declare const PREPARE_BYTES: number;
+/**
+ * An event that takes the owner's time: timed, not cancelled, not declined by the owner, and an ordinary event (no
+ * focus time, out-of-office or working location).
+ */
+export declare const ownsTime: (details: EventDetails) => boolean;
 /** The account's next meeting that has not started yet, by the rule of `isMeeting`. */
 export declare const nextMeeting: (store: EventStore, accountId: number, now: number) => Promise<EventDetails>;
 export interface PreparationOptions {

package/dist/calendar/prepare.js

@@ -16,19 +16,19 @@ const NEXT_PAGE = 50;
 const nameOf = ({ provider, account }) => `${provider}:${account}`;
 const size = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
 /**
- * What makes an event the next meeting: timed, not cancelled, not declined by the owner, an ordinary event (no focus
- * time, out-of-office or working location), and someone other than the owner and the rooms invited.
+ * An event that takes the owner's time: timed, not cancelled, not declined by the owner, and an ordinary event (no
+ * focus time, out-of-office or working location).
  */
-const isMeeting = (details) => {
+export const ownsTime = (details) => {
     if (details.event.allDay || details.event.status === "cancelled")
         return false;
     const live = details.entries.filter((entry) => entry.deletedAt === null && entry.status !== "cancelled");
     if (!live.length || live.every((entry) => entry.ownResponse === "declined"))
         return false;
-    if (live.every((entry) => entry.eventType !== null && entry.eventType !== "default"))
-        return false;
-    return details.participants.some((one) => !one.self && !one.resource);
+    return !live.every((entry) => entry.eventType !== null && entry.eventType !== "default");
 };
+/** The next meeting: an event that takes the owner's time, with someone other than the owner and the rooms invited. */
+const isMeeting = (details) => ownsTime(details) && details.participants.some((one) => !one.self && !one.resource);
 /** The account's next meeting that has not started yet, by the rule of `isMeeting`. */
 export const nextMeeting = async (store, accountId, now) => {
     for (let offset = 0; offset < NEXT_SCAN; offset += NEXT_PAGE) {

package/dist/calendar/remind.d.ts

@@ -0,0 +1,51 @@
+import { type EventDetails, type EventStore } from "../meetings/index.js";
+/** A program that has not finished by then is stopped, so a stuck one does not hold the next run's lock. */
+export declare const HOOK_TIMEOUT_MS = 60000;
+export type Reminded = Record<string, string>;
+export declare const remindersPath: (state: string, profile: string) => string;
+/** Events that take the owner's time and start in the window, earliest first, and are not yet reminded. */
+export declare const dueEvents: (store: EventStore, accountId: number, window: {
+    from: number;
+    to: number;
+}, reminded: Reminded) => Promise<EventDetails[]>;
+export declare const reminderItem: (details: EventDetails) => {
+    id: string;
+    event_series_id: string | null;
+    title: string | null;
+    description: string | null;
+    location: string | null;
+    starts_at: string | null;
+    ends_at: string | null;
+    timezone: string | null;
+    origin: "auto" | "calendar" | "owner";
+    status: string | null;
+    all_day: boolean;
+    source_deleted_at: string | null;
+    deleted_at: string | null;
+    created_at: string;
+    updated_at: string;
+    change?: "cancelled" | "moved" | "new" | undefined;
+    changed_at?: string | null | undefined;
+    was?: {
+        starts_at: string | null;
+        ends_at: string | null;
+    } | undefined;
+    overlapping?: boolean | undefined;
+    overlaps?: string[] | undefined;
+    ref: string;
+    untrusted: string[];
+};
+/**
+ * Runs the owner's program with the reminder as JSON on its standard input, never through a shell: the event's text
+ * is a stranger's, and only the program's own argv, typed by the owner, is on its command line.
+ */
+export declare const runHook: (argv: readonly string[], input: string, env: NodeJS.ProcessEnv, timeoutMs?: number) => Promise<number>;
+/**
+ * What was reminded, and the lock that keeps two runs from reminding the same event at once. `remember` keeps a day
+ * of past starts and forgets older ones.
+ */
+export declare const openReminders: (path: string, now: number) => {
+    reminded: Reminded;
+    remember: (details: EventDetails) => void;
+    close: () => void;
+};

package/dist/calendar/remind.js

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import { CliError } from "@wirecat/cli-base";
+import { checkpointPath, readCheckpoint, saveCheckpoint } from "../background/checkpoints.js";
+import { releaseLock, takeLock } from "../background/lock.js";
+import { eventItem } from "../meetings/index.js";
+import { ownsTime } from "./prepare.js";
+import { eventOf } from "./reads.js";
+const DAY = 86_400_000;
+/** More would be a calendar that is not the owner's own; the rest wait for the next run. */
+const REMIND_MAX = 50;
+/** A program that has not finished by then is stopped, so a stuck one does not hold the next run's lock. */
+export const HOOK_TIMEOUT_MS = 60_000;
+const KILL_AFTER_MS = 5_000;
+const UNTRUSTED = ["title", "description", "location"];
+/** One key per event and start: a meeting moved to another time is reminded again. */
+const keyOf = (details) => `${details.event.id}@${new Date(details.event.startsAt ?? 0).toISOString()}`;
+export const remindersPath = (state, profile) => checkpointPath(state, profile, "events-remind");
+/** Events that take the owner's time and start in the window, earliest first, and are not yet reminded. */
+export const dueEvents = async (store, accountId, window, reminded) => {
+    const due = [];
+    for (const one of await store.events({ accountId, startsFrom: window.from, to: window.to, limit: REMIND_MAX })) {
+        const details = await eventOf(store, accountId, one.id).catch(() => undefined);
+        if (details && ownsTime(details) && reminded[keyOf(details)] === undefined)
+            due.push(details);
+    }
+    return due;
+};
+export const reminderItem = (details) => ({
+    ...eventItem(details.event),
+    ref: `event:${details.event.id}`,
+    untrusted: UNTRUSTED,
+});
+/**
+ * Runs the owner's program with the reminder as JSON on its standard input, never through a shell: the event's text
+ * is a stranger's, and only the program's own argv, typed by the owner, is on its command line.
+ */
+export const runHook = (argv, input, env, timeoutMs = HOOK_TIMEOUT_MS) => new Promise((resolve) => {
+    const [program = "", ...args] = argv;
+    const child = spawn(program, args, { env, shell: false, stdio: ["pipe", "ignore", "inherit"], windowsHide: true });
+    let kill;
+    const stop = setTimeout(() => {
+        child.kill("SIGTERM");
+        kill = setTimeout(() => child.kill("SIGKILL"), KILL_AFTER_MS);
+    }, timeoutMs);
+    const done = (code) => {
+        clearTimeout(stop);
+        if (kill)
+            clearTimeout(kill);
+        resolve(code);
+    };
+    child.on("error", () => done(127));
+    child.on("close", (code, signal) => done(code ?? (signal === "SIGKILL" ? 137 : 143)));
+    // A program that reads nothing closes its end first; that is its choice, not a failure.
+    child.stdin.on("error", () => { });
+    child.stdin.end(input);
+});
+/**
+ * What was reminded, and the lock that keeps two runs from reminding the same event at once. `remember` keeps a day
+ * of past starts and forgets older ones.
+ */
+export const openReminders = (path, now) => {
+    const lock = `${path}.lock`;
+    const held = takeLock(lock, { pid: process.pid, startedAt: new Date(now).toISOString() });
+    if (held)
+        throw new CliError("validation_error", `another events remind is running (pid ${held.pid}); this run did nothing`, {
+            reason: "remind.running",
+            retryable: true,
+        });
+    const reminded = { ...readCheckpoint(path)?.cursor };
+    return {
+        reminded,
+        remember: (details) => {
+            reminded[keyOf(details)] = new Date(now).toISOString();
+            const kept = Object.fromEntries(Object.entries(reminded).filter(([key]) => Date.parse(key.slice(key.indexOf("@") + 1)) >= now - DAY));
+            saveCheckpoint(path, { cursor: kept, done: Object.keys(kept).length }, new Date(now));
+        },
+        close: () => releaseLock(lock),
+    };
+};

package/dist/calendar/writer.d.ts

@@ -93,6 +93,8 @@ export type CalendarWrite = "create" | "quick-add" | "import" | "update" | "dele
 /** Mailing the other attendees: an agent may write to the calendar and still not to people (WC-PERM-14's spirit). */
 export declare const EVENTS_NOTIFY_KEY: PermissionKey;
 export declare const EVENTS_DELETE_SERIES_KEY: PermissionKey;
+/** `events remind -- <program>`: runs a program of the owner's on this machine, so it waits for the owner's allow. */
+export declare const EVENTS_REMIND_HOOK_KEY: PermissionKey;
 /** The keys the calendar writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
 export declare const CALENDAR_WRITE_KEYS: readonly PermissionKey[];
 /**

package/dist/calendar/writer.js

@@ -2,8 +2,14 @@ import { CliError } from "@wirecat/cli-base";
 /** Mailing the other attendees: an agent may write to the calendar and still not to people (WC-PERM-14's spirit). */
 export const EVENTS_NOTIFY_KEY = "events.notify";
 export const EVENTS_DELETE_SERIES_KEY = "events.delete.series";
+/** `events remind -- <program>`: runs a program of the owner's on this machine, so it waits for the owner's allow. */
+export const EVENTS_REMIND_HOOK_KEY = "events.remind.hook";
 /** The keys the calendar writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
-export const CALENDAR_WRITE_KEYS = [EVENTS_NOTIFY_KEY, EVENTS_DELETE_SERIES_KEY];
+export const CALENDAR_WRITE_KEYS = [
+    EVENTS_NOTIFY_KEY,
+    EVENTS_DELETE_SERIES_KEY,
+    EVENTS_REMIND_HOOK_KEY,
+];
 /**
  * Built in, and only ever tightening (WC-PERM-7). A change that is easy to undo goes ahead, as tg's and drive's writes
  * do; a deletion asks; a whole series is not deleted, and nobody is mailed.
@@ -18,6 +24,8 @@ export const CALENDAR_WRITE_DEFAULTS = {
     "events.delete": "ask",
     [EVENTS_DELETE_SERIES_KEY]: "deny",
     [EVENTS_NOTIFY_KEY]: "deny",
+    // Not ask: `--yes` answers ask, and anything that can type a gcal command can add it.
+    [EVENTS_REMIND_HOOK_KEY]: "deny",
 };
 /** What an adapter throws when the provider refused a write because the entry's `etag` is old (HTTP 412). */
 export const calendarConflict = (message = "the event changed at the provider since the last sync") => new CliError("validation_error", `${message}; sync and try again`, { reason: "event.conflict" });

package/dist/cli/index.d.ts

@@ -14,7 +14,7 @@ export { registerLinkConversationsPrompt } from "../mcp/prompts.js";
 export { agentBody, agentJson, agentResult, UNTRUSTED, UNTRUSTED_INSTRUCTION, UNTRUSTED_NEUTRAL } from "../mcp/text.js";
 export { MEETING_RESULT_ENTITIES } from "../meetings/index.js";
 export { type AppIdentity, envName, readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
-export type { AccountEditing, AccountHealth, AccountRecords, AccountSettings, AccountStanding, AccountTools, After, BotChats, ChannelComments, ChatDeletion, ChatFolders, ChatReading, ContactBook, Download, ForumControl, ForumState, GroupAdmin, GroupModeration, HistoryBatch, HistoryChatEvent, HistoryReaction, HistoryStar, HistoryVote, InviteLinks, JoinRequests, LiveUpdates, MessageButtons, MessageEditing, MessageMedia, MessagePermalinks, MessagePins, MessagePolls, MessageReactions, MessageSearch, MessageStars, MessengerAdapter, MessengerCore, NewPoll, OfficialStats, PassiveUpdates, PersonProfiles, ProfileChange, ProfilePhotos, PushedHistory, ReadState, RemoteFile, ScheduledMessages, SenderIdentities, SenderSearch, SendOptions, Sent, ServerQuery, ServerReads, ThreadAddressing, TopicEditing, TopicHistory, TopicReadState, Transcript, } from "../ports/messenger.js";
+export type { AccountEditing, AccountHealth, AccountRecords, AccountSettings, AccountStanding, AccountTools, After, BotChats, ChannelComments, ChatDeletion, ChatFolders, ChatReading, ContactBook, Download, ForumControl, ForumState, GroupAdmin, GroupModeration, HistoryBatch, HistoryBatchHandler, HistoryChatEvent, HistoryReaction, HistoryStar, HistoryVote, InviteLinks, JoinRequests, LiveUpdates, MessageButtons, MessageEditing, MessageMedia, MessagePermalinks, MessagePins, MessagePolls, MessageReactions, MessageSearch, MessageStars, MessengerAdapter, MessengerCore, NewPoll, OfficialStats, PassiveUpdates, PersonProfiles, ProfileChange, ProfilePhotos, PushedHistory, ReadState, RemoteFile, ScheduledMessages, SenderIdentities, SenderSearch, SendOptions, Sent, ServerQuery, ServerReads, ThreadAddressing, TopicEditing, TopicHistory, TopicReadState, Transcript, } from "../ports/messenger.js";
 export type { Fetching, MediaOption, MessengerTraits } from "../ports/traits.js";
 export { senderFacts } from "../replies/dry-run.js";
 export { type ReplyRender, replyRenderer } from "../replies/rendering.js";

package/dist/cli/messenger/observed.js

@@ -44,7 +44,7 @@ export const observed = (messenger, events) => {
         const counts = {};
         await timed(operation, {}, () => work((item) => {
             count(item, counts);
-            onItem(item);
+            return onItem(item);
         }), () => ({ counts }));
     };
     const mint = messenger.newSendId;

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/messenger/stored.d.ts

@@ -10,7 +10,7 @@ export interface Saving {
     warn: Warn;
     events: EventSink;
     /** Saves still writing, for the closer to wait on: `watch` does not hold the next event for one. */
-    pending?: Set<Promise<void>>;
+    pending?: Set<Promise<unknown>>;
     /** `storedChats` calls still running, apart from `pending`: one abandoned at exit leaves nothing unsaved. */
     announcing?: Set<Promise<void>>;
     deletedWithoutChat?: DeletionScope;

package/dist/cli/messenger/stored.js

@@ -1,5 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
-import { capability, throughWrapper } from "../../ports/messenger.js";
+import { capability, throughWrapper, } from "../../ports/messenger.js";
 import { foldName, isId, pickPerson } from "../../resolve.js";
 import { codeOf } from "../../sends/guarded.js";
 import { chatIdIn } from "../../services/message-resolution.js";
@@ -25,8 +25,9 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
     const attempt = async (operation, write) => {
         try {
             const opened = await store();
-            if (opened)
-                await write(opened);
+            if (!opened)
+                return false;
+            await write(opened);
             // After the write, so saves keep their order; a convenience for naming this account from another app.
             if (opened && !recorded && profile) {
                 recorded = true;
@@ -34,9 +35,11 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
                     .then(() => opened.accounts.saveProfile(profile.app, profile.name, account))
                     .catch(() => { });
             }
+            return true;
         }
         catch (error) {
             notWritten(operation, error);
+            return false;
         }
     };
     const save = (operation, writing) => {
@@ -152,7 +155,7 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
             // A refused re-key leaves its chat split, never the others or the batch's history unsaved.
             const saving = previous.then(async () => {
                 await saveRekeys(rekeys, round);
-                await attempt(operation, (opened) => fill(opened, account, batch));
+                return attempt(operation, (opened) => fill(opened, account, batch));
             });
             previous = saving;
             pending?.add(saving);
@@ -162,7 +165,8 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
                 pending?.delete(saving);
                 rekeysOnly.delete(saving);
             });
-            onBatch(batch);
+            void onBatch(batch);
+            return saving;
         };
     };
     // A method not listed here saves nothing and passes through; a lane that should save adds its line.

package/dist/errors/reasons.js

@@ -57,6 +57,14 @@ const OTHERS = [
     ["sync.partial", "provider_error", "some calendars did not sync; the next sync retries them"],
     validation("event.conflict", "the event changed at the provider since the last sync; sync and try again"),
     validation("event.notify-required", "the event has other attendees; say whether to notify them"),
+    validation("remind.window", "--due-within is outside 1m to 1d"),
+    validation("remind.running", "another events remind is running; this run did nothing"),
+    [
+        "remind.hook-failed",
+        "configuration_error",
+        "the reminder program failed for some events; the next run retries them",
+    ],
+    ["sync.failed", "provider_error", "the sync failed; the answer comes from what the store already holds"],
     validation("event.repeat-invalid", "the repeat rule is outside the RFC 5545 subset the calendars take"),
     validation("event.repeat-kind", "the series' rule holds a date or a time of the kind the event is leaving"),
     validation("event.repeat-split", "the series cannot be split at this occurrence, or was split there already"),

package/dist/meetings/mcp/index.d.ts

@@ -38,6 +38,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -53,11 +54,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -75,11 +76,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -101,7 +102,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -188,6 +188,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -203,11 +204,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -225,11 +226,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -251,7 +252,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -338,6 +338,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -353,11 +354,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -375,11 +376,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -401,7 +402,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -488,6 +488,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -503,11 +504,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -525,11 +526,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -551,7 +552,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -638,6 +638,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -653,11 +654,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -675,11 +676,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -701,7 +702,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;

package/dist/oauth/authorize.js

@@ -46,7 +46,7 @@ export const authorize = async (options) => {
         else
             fail(new CliError("authentication_error", `${provider.name} sign-in was declined`, { reason: "oauth.declined" }));
     };
-    const server = createServer((request, response) => {
+    const handler = (request, response) => {
         let url;
         try {
             url = new URL(request.url ?? "/", "http://127.0.0.1");
@@ -69,7 +69,11 @@ export const authorize = async (options) => {
         }
         response.end("Sign-in received; you can close this tab");
         settle(url.searchParams);
-    });
+    };
+    const server = createServer(handler);
+    const localhost = provider.redirect.kind === "loopback" && provider.redirect.host === "localhost";
+    // `localhost` may resolve to ::1 in the browser; the IPv6 listener is best effort, as some hosts have no IPv6.
+    const server6 = localhost ? createServer(handler) : undefined;
     const onAbort = () => fail(cancelled());
     options.signal?.addEventListener("abort", onAbort, { once: true });
     const timer = setTimeout(() => fail(new CliError("timeout", `${provider.name} sign-in timed out`, { reason: "oauth.timeout" })), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
@@ -81,10 +85,19 @@ export const authorize = async (options) => {
         const address = server.address();
         if (!address || typeof address === "string")
             throw new CliError("configuration_error", "could not start the local sign-in listener");
+        if (server6) {
+            server6.on("error", () => { });
+            await new Promise((resolve) => {
+                server6.once("error", () => resolve());
+                server6.listen(address.port, "::1", () => resolve());
+            });
+        }
         const random = randomBytes(32).toString("base64url");
         const relay = provider.redirect.kind === "relay";
         state = relay ? `${address.port}.${random}` : random;
-        const redirectUri = provider.redirect.kind === "relay" ? provider.redirect.url : `http://127.0.0.1:${address.port}/callback`;
+        const redirectUri = provider.redirect.kind === "relay"
+            ? provider.redirect.url
+            : `http://${localhost ? "localhost" : "127.0.0.1"}:${address.port}/callback`;
         const url = new URL(provider.authorizeUrl);
         for (const [key, value] of Object.entries({
             ...provider.authorizeParams,
@@ -124,7 +137,10 @@ export const authorize = async (options) => {
         clearTimeout(timer);
         options.signal?.removeEventListener("abort", onAbort);
         paste.abort();
-        server.closeAllConnections();
-        await new Promise((resolve) => server.close(() => resolve()));
+        for (const each of server6 ? [server, server6] : [server]) {
+            each.closeAllConnections();
+            if (each.listening)
+                await new Promise((resolve) => each.close(() => resolve()));
+        }
     }
 };

package/dist/oauth/provider.d.ts

@@ -39,11 +39,13 @@ export interface OAuthProvider {
     revokeUrl?: string;
     client: OAuthClient;
     /**
-     * `loopback` sends the browser to `http://127.0.0.1:<port>/callback`. `relay` sends it to a fixed page that
+     * `loopback` sends the browser to `http://127.0.0.1:<port>/callback`, or to `http://localhost:<port>/callback` with
+     * `host: "localhost"` (the listener then takes `127.0.0.1` and `::1`). `relay` sends it to a fixed page that
      * forwards to the loopback port, which it reads from `state` (`<port>.<random>`).
      */
     redirect: {
         kind: "loopback";
+        host?: "localhost";
     } | {
         kind: "relay";
         url: string;

package/dist/ports/messenger.d.ts

@@ -348,7 +348,7 @@ export interface PassiveUpdates {
      * has it saved by a command that never feeds. Optional within the group, so an adapter typed as having
      * `PassiveUpdates` before it existed still is one.
      */
-    listenHistory?(onBatch: (batch: HistoryBatch) => void, signal: AbortSignal): Promise<void>;
+    listenHistory?(onBatch: HistoryBatchHandler, signal: AbortSignal): Promise<void>;
 }
 /** One voter's vote in the poll message `messageId` of `chatId` carries, as `PollVoteEvent` has it. */
 export interface HistoryVote {
@@ -398,10 +398,16 @@ export interface HistoryBatch {
     }[];
     events?: HistoryChatEvent[];
 }
+/**
+ * Takes one pushed batch. The CLI's own handler resolves `true` once the batch is in the local store and `false` when it
+ * could not be written, so a messenger that pushes history once can keep a batch until it is saved; a handler that
+ * stores nothing returns nothing.
+ */
+export type HistoryBatchHandler = (batch: HistoryBatch) => void | Promise<boolean>;
 /** For a messenger that pushes its history to the client instead of answering for it (`Messenger.history: "store"`). */
 export interface PushedHistory {
     /** Chats, people and past messages as the messenger pushes them, until `signal` aborts. */
-    feed(onBatch: (batch: HistoryBatch) => void, signal: AbortSignal): Promise<void>;
+    feed(onBatch: HistoryBatchHandler, signal: AbortSignal): Promise<void>;
     /**
      * Every chat id the store holds for this account, handed over once as `feed` starts, so a chat nothing names again
      * can still be re-keyed through a later batch's `rekeys`. `recipients`, when given, are ids the profile's recipient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.541.0",
+  "version": "0.543.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -251,7 +251,7 @@
     "@types/node": "^22.20.5",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "@wirecat/cli-base": "0.72.0",
+    "@wirecat/cli-base": "0.73.0",
     "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
     "commander": "15.0.0",
     "cspell": "10.4.0",
@@ -271,7 +271,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.72.0 <0.73.0",
+    "@wirecat/cli-base": ">=0.73.0 <0.74.0",
     "commander": ">=15"
   },
   "bin": {