@wirecat/cli-core 0.551.0 → 0.552.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ 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

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/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/cli/context.d.ts

@@ -64,6 +64,8 @@ export interface BaseEnvironment {
      * message was handled, and nothing was sent" instead of on the next event or a sleep.
      */
     handled?: (event: MessageEvent) => void;
+    /** A test's hook into `serve`: how long it waits after connecting before its catch-up pass. */
+    startSyncDelayMs?: number;
     /** Set by an MCP server on a command it runs for an agent (`runCommandForAgent`). */
     agent?: AgentRun;
     /** Set by `run()`: the words it was given, which a run keeps as `record_input` says (`maskArgv`). */

package/dist/cli/meeting-preparation-answer.d.ts

@@ -309,6 +309,9 @@ export declare const meetingPreparationAnswer: (packet: MeetingPreparation) => i
                 id: string;
                 excerpt: string;
                 offset_ms: number | null;
+                language?: string | null | undefined;
+                line?: number | undefined;
+                lines_total?: number | undefined;
                 match?: "corrected" | "words" | undefined;
                 corrections?: {
                     from: string;

package/dist/cli/meeting-preparation-projects.d.ts

@@ -29,6 +29,9 @@ export declare const mapPreparationProjectEvidence: (section: NonNullable<Meetin
             id: string;
             excerpt: string;
             offset_ms: number | null;
+            language?: string | null | undefined;
+            line?: number | undefined;
+            lines_total?: number | undefined;
             match?: "corrected" | "words" | undefined;
             corrections?: {
                 from: string;

package/dist/cli/meeting-preparation-read.d.ts

@@ -338,6 +338,9 @@ export declare const readMeetingPreparation: (read: MeetingPreparationReader, in
                 id: string;
                 excerpt: string;
                 offset_ms: number | null;
+                language?: string | null | undefined;
+                line?: number | undefined;
+                lines_total?: number | undefined;
                 match?: "corrected" | "words" | undefined;
                 corrections?: {
                     from: string;

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

@@ -293,7 +293,14 @@ export const allHitItem = (item) => item.kind === "meeting"
         offset_ms: item.startMs,
         scope: item.scope,
         id: String(item.id),
-        ...(item.cueRef === undefined ? {} : { cue_ref: item.cueRef, sender_name: item.speakerName ?? null }),
+        ...(item.cueRef === undefined
+            ? {}
+            : {
+                cue_ref: item.cueRef,
+                sender_name: item.speakerName ?? null,
+                language: item.language ?? null,
+                ...(item.line === undefined ? {} : { line: item.line, lines_total: item.linesTotal }),
+            }),
         untrusted: ALL_HIT_UNTRUSTED.meeting,
     }
     : defined({

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

@@ -0,0 +1,43 @@
+import type { Chat } from "../../domain/models.js";
+import type { ServeNotice } from "./serve-notice.js";
+/** The provider's own catch-up lands first; this pass then finds most chats already current. */
+export declare const START_SYNC_DELAY_MS = 30000;
+export declare const START_SYNC_BUDGET_MS: number;
+/** A longer downtime is `messages sync --all`'s job, not a start's. */
+export declare const START_SYNC_WINDOW_MS: number;
+export declare const START_SYNC_PER_CHAT = 500;
+export interface StartSyncSummary {
+    chats: number;
+    fetched: number;
+    failed: number;
+    stopped: boolean;
+}
+export interface StartSync {
+    /** Runs the pass once, after the delay; a second call is ignored. */
+    start(): void;
+    /** Aborts the pass and waits for it, which stops before its next request. */
+    stop(): Promise<void>;
+    summary(): StartSyncSummary | undefined;
+}
+/**
+ * `serve`'s one pass on start over the chats that moved while nothing listened. A provider's own
+ * catch-up drops a gap it finds too long (Telegram's `differenceTooLong`, `channelDifferenceTooLong`
+ * past 100 updates), so each chat whose newest message is newer than the newest one held is read back
+ * to that one. A chat never held is read back to the newest message held anywhere, which is about when
+ * the last serve stopped. Bounded by a window, a per-chat limit and a time budget; an empty store is
+ * left to `messages sync --all`.
+ */
+export declare const startSync: ({ chats, newestHeld, fetch, note, warn, delayMs, budgetMs, windowMs, now, }: {
+    chats: (stop: AbortSignal) => Promise<Chat[]>;
+    /** The newest message held from before this serve started, epoch milliseconds. */
+    newestHeld: (chatId: string) => Promise<number | undefined>;
+    fetch: (chatId: string, sinceMs: number, stop: AbortSignal) => Promise<{
+        fetched: number;
+    }>;
+    note: (notice: ServeNotice) => void;
+    warn: (notice: ServeNotice) => void;
+    delayMs?: number;
+    budgetMs?: number;
+    windowMs?: number;
+    now?: () => number;
+}) => StartSync;

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

@@ -0,0 +1,90 @@
+import { failureKey } from "../../errors/failures.js";
+/** The provider's own catch-up lands first; this pass then finds most chats already current. */
+export const START_SYNC_DELAY_MS = 30_000;
+export const START_SYNC_BUDGET_MS = 5 * 60_000;
+/** A longer downtime is `messages sync --all`'s job, not a start's. */
+export const START_SYNC_WINDOW_MS = 7 * 86_400_000;
+export const START_SYNC_PER_CHAT = 500;
+/**
+ * `serve`'s one pass on start over the chats that moved while nothing listened. A provider's own
+ * catch-up drops a gap it finds too long (Telegram's `differenceTooLong`, `channelDifferenceTooLong`
+ * past 100 updates), so each chat whose newest message is newer than the newest one held is read back
+ * to that one. A chat never held is read back to the newest message held anywhere, which is about when
+ * the last serve stopped. Bounded by a window, a per-chat limit and a time budget; an empty store is
+ * left to `messages sync --all`.
+ */
+export const startSync = ({ chats, newestHeld, fetch, note, warn, delayMs = START_SYNC_DELAY_MS, budgetMs = START_SYNC_BUDGET_MS, windowMs = START_SYNC_WINDOW_MS, now = Date.now, }) => {
+    const controller = new AbortController();
+    let timer;
+    let pass = Promise.resolve();
+    let started = false;
+    let done;
+    const run = async () => {
+        const stop = AbortSignal.any([controller.signal, AbortSignal.timeout(budgetMs)]);
+        const floor = now() - windowMs;
+        const moved = [];
+        for (const chat of await chats(stop)) {
+            const lastAt = Date.parse(chat.lastMessageAt ?? "");
+            if (Number.isNaN(lastAt) || lastAt < floor)
+                continue;
+            moved.push({ chat, lastAt, held: await newestHeld(chat.id) });
+        }
+        const anywhere = moved.reduce((top, { held }) => (held === undefined ? top : Math.max(top, held)), -Infinity);
+        if (!Number.isFinite(anywhere))
+            return;
+        const behind = moved
+            .filter(({ lastAt, held }) => lastAt > (held ?? anywhere))
+            .sort((one, other) => other.lastAt - one.lastAt);
+        if (behind.length === 0)
+            return;
+        const summary = { chats: 0, fetched: 0, failed: 0, stopped: false };
+        done = summary;
+        for (const { chat, held } of behind) {
+            if (stop.aborted)
+                break;
+            try {
+                summary.fetched += (await fetch(chat.id, Math.max(held ?? anywhere, floor), stop)).fetched;
+                summary.chats += 1;
+            }
+            catch (error) {
+                if (stop.aborted)
+                    break;
+                summary.failed += 1;
+                const errorCode = failureKey(error);
+                warn({
+                    code: "start_sync_chat_failed",
+                    chatId: chat.id,
+                    errorCode,
+                    text: `what ${chat.id} received while serve was down was not fetched: ${errorCode}`,
+                });
+            }
+        }
+        summary.stopped = stop.aborted && summary.chats + summary.failed < behind.length;
+        note({
+            code: "start_sync",
+            text: `caught up ${summary.fetched} message(s) in ${summary.chats} chat(s) that moved while serve was down` +
+                (summary.stopped ? ` — stopped at the time limit, ${behind.length - summary.chats - summary.failed} left` : ""),
+        });
+    };
+    return {
+        start: () => {
+            if (started || controller.signal.aborted)
+                return;
+            started = true;
+            timer = setTimeout(() => {
+                pass = run().catch((error) => {
+                    if (controller.signal.aborted)
+                        return;
+                    const errorCode = failureKey(error);
+                    warn({ code: "start_sync_failed", errorCode, text: `the catch-up on start failed: ${errorCode}` });
+                });
+            }, delayMs);
+        },
+        stop: async () => {
+            controller.abort();
+            clearTimeout(timer);
+            await pass;
+        },
+        summary: () => done,
+    };
+};