@wirecat/cli-core 0.348.0 → 0.350.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ shape of this file.
 
 ## Unreleased
 
+## 0.350.0 — 19.10.2026
+
+### Added
+
+- **A messenger that pushes its history can be told the chats the store holds**: the optional
+  `PushedHistory.storedChats(ids)` gets every chat id of this account once as `feed` starts, in `serve` and `watch`.
+  whatsapp-cli uses it to re-key phone-form chats nothing names again, through `rekeys`. A reject is a
+  `stored_chats_failed` warning. The contract kit has a case for it, skipped without the method, and
+  `fakeAdapter(seed, { storedChats: true })`.
+- **`loginQr().show(link, scan)` says where to scan only once a code exists**: after the drawn code, or after
+  the `--qr-file` note. On a terminal too narrow to draw the code, only the hint to widen it or pass `--qr-file`
+  is shown. Before, the CLIs said "scan this code" first, so a narrow terminal asked to scan a code that was
+  never drawn. `scan` is optional and nothing changes without it: an adapter drops its own scan note before
+  `show()` and passes that text as `show(link, scan)` instead.
+
+### Fixed
+
+- **A `storedChats` hook that never finishes no longer says messages were not saved** at exit: after the 5 s wait
+  it is a `stored_chats_failed` warning that the hook was abandoned, since it only reads chat ids.
+
+## 0.349.0 — 19.10.2026
+
+### Added
+
+- **`gatherProjectEvidence` brings the mail and document index up to date before reading** through the new
+  optional `MessageStore.contextIndex` port (`ContextIndex.catchUp`), the same fills a mail search and the notes
+  search run. `index: "as-is"` skips it; the result's `index` says what happened. On a store just synced, new
+  mail and imported documents were missed before.
+- **The project key is a search lane of its own** (`project.key`, lane kind `key`), and an explicit window may
+  give `after` alone: `before` is `asOf`, frozen with the run.
+- **Each message hit of `gatherProjectEvidence` carries the messages next to it** (`around`, default 2 before and 2
+  after, at most 5) through the new `neighbours` port; `storedMessageNeighbours(store.messages)` builds it. They
+  are cited context, not matches, and their bytes count against `maxReadBytes`. A reply that names nothing was
+  out of reach of every search.
+- **The default read budget covers one full round**: one read per search × source × 90-day chunk when that is more
+  than 48 (at most 512), so `--source all` with several searches no longer stops before every search ran once.
+- **`ProjectFetchState`, `ProjectUnitState`, `ProjectIndexCatchUp` and `ContextIndex` are exported** from
+  `@wirecat/cli-core/services`, so a host can name the result type.
+
+### Changed — may break callers
+
+- **`feed` and a one-shot command's passive listen keep one operation name in their run records and warnings**:
+  `history.feed` for `feed`, `messages.listen` for `listen` and `history.listen` for `listenHistory`, as
+  `messages.watch` does for `watch`. Before, the run record said `adapter.feed`, `adapter.listen` or
+  `adapter.listenHistory`, so `runs --operation adapter.feed` and `adapter.listen` stop matching new runs.
+- **`parity.json` expects `--qr-file` on `session start` and `setup` in all three CLIs**: max has it since
+  max-cli#736, so the rows are `all` instead of planned for max.
+
 ## 0.348.0 — 19.10.2026
 
 ### Added

package/dist/cli/messenger/context.js

@@ -193,6 +193,7 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
     const pacer = new Pacer(pacePathFor(app, settings.profile, env), rate);
     const adapter = observed(flooded(connection, memory, { name: name ?? app.command, warn: renderer.warn, pacer }), events);
     const pending = new Set();
+    const announcing = new Set();
     const saving = self === null
         ? adapter
         : stored(adapter, {
@@ -202,6 +203,7 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
             warn: renderer.warn,
             events,
             pending,
+            announcing,
             ...(deletedWithoutChat ? { deletedWithoutChat } : {}),
             rekeyed: (from, to) => rekeyRecipients(app, settings.profile, env, renderer.warn, from, to),
             ...(history === "store" ? { namesFromStore: savedChatId ? { savedChatId } : {} } : {}),
@@ -226,10 +228,15 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
                         events({ event: "warning", code: "store_not_written", operation });
                         renderer.warn(`not saved to the local store: the messenger was still handing on ${what} at exit`);
                     });
-                    if (!(await settled(pending, SAVES_WAIT_MS))) {
+                    await settled(new Set([...pending, ...announcing]), SAVES_WAIT_MS);
+                    if (pending.size > 0) {
                         events({ event: "warning", code: "store_not_written", operation: "close" });
                         renderer.warn("not saved to the local store: the last messages were still being written at exit");
                     }
+                    if (announcing.size > 0) {
+                        events({ event: "warning", code: "stored_chats_failed", operation: "close" });
+                        renderer.warn("the messenger's stored-chats hook did not finish and was abandoned at exit; nothing is lost");
+                    }
                 }
                 finally {
                     await store.close();

package/dist/cli/messenger/flooded.js

@@ -3,7 +3,7 @@ import { isCliFailure } from "../../errors/failures.js";
 import { throughWrapper } from "../../ports/messenger.js";
 import { providerErrorKey } from "../../runs/events.js";
 import { holdEnd } from "../../sends/flood.js";
-const LONG_LIVED = new Set(["self", "newSendId", "close", "formatMarkdown", "formatHtml"]);
+const LONG_LIVED = new Set(["self", "newSendId", "close", "formatMarkdown", "formatHtml", "storedChats"]);
 /** Neither held nor paced, as they listen for as long as the run does; what ends them is still remembered. */
 const LISTENING = new Set(["watch", "feed", "listen", "listenHistory"]);
 const BLOCKING = new Set(["frozen", "limited", "banned"]);

package/dist/cli/messenger/observed.js

@@ -40,7 +40,7 @@ export const observed = (messenger, events) => {
         }), () => ({ counts }));
     };
     const mint = messenger.newSendId;
-    const { chats, history, contact, around, watch, listen, listenHistory } = messenger;
+    const { chats, history, contact, around, watch, feed, listen, listenHistory } = messenger;
     // A method not listed here is timed under its own name, with no ids until a line here names them.
     return throughWrapper(messenger, {
         self: () => messenger.self(),
@@ -87,14 +87,17 @@ export const observed = (messenger, events) => {
                 watch: (onEvent, signal, onReady) => counted("messages.watch", onEvent, (counting) => watch.call(messenger, counting, signal, onReady), byEvent),
             }
             : {}),
+        ...(feed
+            ? { feed: (onBatch, signal) => timed("history.feed", {}, () => feed.call(messenger, onBatch, signal)) }
+            : {}),
         ...(listen
             ? {
-                listen: (onEvent, signal) => counted("adapter.listen", onEvent, (counting) => listen.call(messenger, counting, signal), byEvent),
+                listen: (onEvent, signal) => counted("messages.listen", onEvent, (counting) => listen.call(messenger, counting, signal), byEvent),
             }
             : {}),
         ...(listenHistory
             ? {
-                listenHistory: (onBatch, signal) => counted("adapter.listenHistory", onBatch, (counting) => listenHistory.call(messenger, counting, signal), byPart),
+                listenHistory: (onBatch, signal) => counted("history.listen", onBatch, (counting) => listenHistory.call(messenger, counting, signal), byPart),
             }
             : {}),
         logout: () => timed("session.logout", {}, () => messenger.logout()),

package/dist/cli/messenger/serve-relay.js

@@ -10,6 +10,7 @@ import { environmentOf } from "../context.js";
 export const lentConnection = (connection, watchers) => throughWrapper(connection, {
     close: async () => { },
     feed: undefined,
+    storedChats: undefined,
     listen: undefined,
     listenHistory: undefined,
     ...(connection.watch && watchers

package/dist/cli/messenger/stored.d.ts

@@ -11,6 +11,8 @@ export interface Saving {
     events: EventSink;
     /** Saves still writing, for the closer to wait on: `watch` does not hold the next event for one. */
     pending?: Set<Promise<void>>;
+    /** `storedChats` calls still running, apart from `pending`: one abandoned at exit leaves nothing unsaved. */
+    announcing?: Set<Promise<void>>;
     deletedWithoutChat?: DeletionScope;
     /** The app command and profile running, recorded with the first save so another app can name this account. */
     profile?: {
@@ -33,4 +35,4 @@ export interface Saving {
  * would erase what `chats list` stored. Nor are `chat` and `contact`: a card's member list is not
  * known to be whole, and `saveMembers` replaces the list.
  */
-export declare const stored: (messenger: MessengerAdapter, { account, store, warn, events, pending, deletedWithoutChat, profile, rekeyed, namesFromStore }: Saving) => MessengerAdapter;
+export declare const stored: (messenger: MessengerAdapter, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, namesFromStore }: Saving) => MessengerAdapter;

package/dist/cli/messenger/stored.js

@@ -11,7 +11,7 @@ import { chatIdIn } from "../../services/message-resolution.js";
  * would erase what `chats list` stored. Nor are `chat` and `contact`: a card's member list is not
  * known to be whole, and `saveMembers` replaces the list.
  */
-export const stored = (messenger, { account, store, warn, events, pending, deletedWithoutChat, profile, rekeyed, namesFromStore }) => {
+export const stored = (messenger, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, namesFromStore }) => {
     let warned = false;
     let recorded = profile === undefined;
     const attempt = async (operation, write) => {
@@ -243,7 +243,14 @@ export const stored = (messenger, { account, store, warn, events, pending, delet
             : {}),
         ...(messenger.feed
             ? {
-                feed: (onBatch, signal) => messenger.feed?.(saveBatches("history.feed", onBatch), signal) ?? Promise.resolve(),
+                feed: (onBatch, signal) => {
+                    if (messenger.storedChats) {
+                        const announced = announceStoredChats(messenger, store, account, events, warn);
+                        announcing?.add(announced);
+                        void announced.finally(() => announcing?.delete(announced));
+                    }
+                    return messenger.feed?.(saveBatches("history.feed", onBatch), signal) ?? Promise.resolve();
+                },
             }
             : {}),
         ...(messenger.listenHistory
@@ -348,6 +355,19 @@ const personIn = (people, reference) => {
         throw error;
     }
 };
+const announceStoredChats = async (messenger, store, account, events, warn) => {
+    try {
+        const opened = await store();
+        if (!opened)
+            return;
+        const ids = (await opened.forAccount(account).chats.chats({})).items.map((chat) => chat.id);
+        await messenger.storedChats?.(ids);
+    }
+    catch (error) {
+        events({ event: "warning", code: "stored_chats_failed", operation: "history.stored_chats" });
+        warn(`the messenger was not told the stored chats: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
 /** Read once when `watch` starts: a store read per event would let a later event overtake an earlier one. */
 const rememberTitles = async (store, account, titles) => {
     try {

package/dist/context/evidence.d.ts

@@ -53,6 +53,16 @@ export interface ContextEvidencePage {
 export interface ContextEvidenceReader {
     read(request: ContextEvidenceRequest): Promise<ContextEvidencePage>;
 }
+/** Brings the word index of stored mail and imported documents up to date, so the reads that follow find new text. */
+export interface ContextIndex {
+    catchUp(request: {
+        kinds: readonly ContextSource["kind"][];
+        signal?: AbortSignal;
+    }): Promise<{
+        mail: number;
+        documents: number;
+    }>;
+}
 export declare const contextCursorScope: (request: Pick<ContextEvidenceRequest, "source" | "query" | "after" | "before">) => string;
 export declare const contextSource: (value: ContextSource) => ContextSource;
 export declare const contextEvidenceRequest: (input: ContextEvidenceRequest) => {

package/dist/kit/contract.d.ts

@@ -22,7 +22,7 @@ export interface ContractOptions {
     history?: "server" | "store";
 }
 /** Every method of the optional groups, which `capability` hands over or refuses. */
-export declare const OPTIONAL_METHODS: readonly ["fetchCounters", "chats", "history", "around", "contact", "historyAfter", "historyBefore", "topics", "inspect", "edit", "forward", "delete", "pin", "unpin", "star", "react", "markRead", "markTopicRead", "poll", "vote", "closePoll", "createPoll", "watch", "listen", "listenHistory", "feed", "download", "transcribe", "scheduled", "members", "admins", "chatEvents", "sessions", "lookup", "addressBook", "people", "createGroup", "join", "leave", "group", "updateGroup", "resetInviteLink", "addMembers", "removeMembers", "addAdmin", "removeAdmin", "folders", "createFolder", "updateFolder", "deleteFolder", "addContact", "removeContact", "block", "unblock", "renameContact", "importContacts", "updateProfile", "endOtherSessions"];
+export declare const OPTIONAL_METHODS: readonly ["fetchCounters", "chats", "history", "around", "contact", "historyAfter", "historyBefore", "topics", "inspect", "edit", "forward", "delete", "pin", "unpin", "star", "react", "markRead", "markTopicRead", "poll", "vote", "closePoll", "createPoll", "watch", "listen", "listenHistory", "feed", "storedChats", "download", "transcribe", "scheduled", "members", "admins", "chatEvents", "sessions", "lookup", "addressBook", "people", "createGroup", "join", "leave", "group", "updateGroup", "resetInviteLink", "addMembers", "removeMembers", "addAdmin", "removeAdmin", "folders", "createFolder", "updateFolder", "deleteFolder", "addContact", "removeContact", "block", "unblock", "renameContact", "importContacts", "updateProfile", "endOtherSessions"];
 /**
  * The port's promises as cases any test runner can run: each connects through `connect`, checks
  * with `node:assert/strict` and closes the adapter. None needs a live service.

package/dist/kit/contract.js

@@ -31,6 +31,7 @@ export const OPTIONAL_METHODS = [
     "listen",
     "listenHistory",
     "feed",
+    "storedChats",
     "download",
     "transcribe",
     "scheduled",
@@ -486,6 +487,17 @@ export const contractCases = ({ connect, ids = wordIds, orderBy = "id", waitMs =
                 },
                 "the fake pushes the seed's history once connected, as `fakeAdapter(seed, { feed: true })` does",
             ],
+            [
+                "storedChats takes no ids, and ids it does not know, without rejecting",
+                async (adapter, seed) => {
+                    const skipped = lacking(adapter, "storedChats");
+                    if (skipped)
+                        return skipped;
+                    await within(Promise.resolve(adapter.storedChats?.([])), "storedChats did not resolve for no ids", waitMs);
+                    const ids = [...seed.chats.map((chat) => chat.id), unknownChat];
+                    await within(Promise.resolve(adapter.storedChats?.(ids)), "storedChats did not resolve for the ids", waitMs);
+                },
+            ],
         ]),
         {
             name: "self() is null before a login",

package/dist/kit/fake.d.ts

@@ -6,4 +6,5 @@ export declare const fakeAdapter: (seed?: Seed, options?: {
     feed?: boolean;
     listen?: boolean;
     listenHistory?: boolean;
+    storedChats?: boolean;
 }) => FakeAdapter;

package/dist/kit/fake.js

@@ -29,7 +29,8 @@ const missing = (what) => new CliError("not_found", `the fake adapter has no ${w
  * With `{ feed: true }` it also pushes its history, as a messenger with `history: "store"` does:
  * the chats and people in one batch, then each chat's messages in a batch of their own.
  * With `{ listen: true }` it also has `listen`, which hands on what `watch` does, and with `{ listenHistory: true }`
- * `listenHistory`, which hands on what `feed` does.
+ * `listenHistory`, which hands on what `feed` does. With `{ storedChats: true }` it takes the stored chat ids and
+ * does nothing with them.
  */
 const withRules = (folder, { emoji, include, skip, exclude, pin }) => {
     if (emoji !== undefined)
@@ -337,6 +338,7 @@ export const fakeAdapter = (seed = contractSeed(), options = {}) => {
             : {}),
         ...(options.feed ? { feed: pushHistory } : {}),
         ...(options.listenHistory ? { listenHistory: pushHistory } : {}),
+        ...(options.storedChats ? { storedChats: async () => { } } : {}),
         download: async (reference, messageId) => {
             const message = messageOf(chatOf(reference).id, messageId);
             return {

package/dist/ports/messenger.d.ts

@@ -365,6 +365,11 @@ export interface HistoryBatch {
 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>;
+    /**
+     * 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`. A reject is a warning; `feed` goes on.
+     */
+    storedChats?(ids: readonly Id[]): void | Promise<void>;
 }
 /** A message's files and its speech, fetched from the messenger. */
 export interface MessageMedia {

package/dist/services/context-evidence.d.ts

@@ -5,5 +5,5 @@ export interface ScopedContextEvidenceReader extends ContextEvidenceReader {
     usage(): ContextReadUsage;
 }
 export declare const createContextEvidenceReader: (port: ContextEvidenceReader, allowed: readonly ContextSource[], limits?: ContextReadLimits) => ScopedContextEvidenceReader;
-export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextSource, } from "../context/evidence.js";
+export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextIndex, ContextSource, } from "../context/evidence.js";
 export type { ContextReadLimits, ContextReadUsage } from "../context/read-budget.js";

package/dist/services/index.d.ts

@@ -1,10 +1,12 @@
 import { type BotCheckService } from "../botcheck/service.js";
-export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextReadLimits, ContextReadUsage, ContextSource, ScopedContextEvidenceReader, } from "./context-evidence.js";
+export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextIndex, ContextReadLimits, ContextReadUsage, ContextSource, ScopedContextEvidenceReader, } from "./context-evidence.js";
 export { createContextEvidenceReader } from "./context-evidence.js";
 export { type DownloadedModel, downloadImageModel, downloadTextModel, type ModelDownloadOptions, } from "./model-downloads.js";
-export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectSourceFetcher, } from "./project-gathering.js";
+export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } from "./project-gathering.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
-export type { ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, } from "./project-gathering-request.js";
+export type { ProjectNeighbour, ProjectNeighbourReader } from "./project-gathering-around.js";
+export { storedMessageNeighbours } from "./project-gathering-around.js";
+export type { ProjectFetchState, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectUnitState, } from "./project-gathering-request.js";
 import { type AccountService } from "./account.js";
 import { type AdminService } from "./admin.js";
 import { type AdminStatisticsService } from "./admin-statistics.js";

package/dist/services/index.js

@@ -2,6 +2,7 @@ import { botCheckService } from "../botcheck/service.js";
 export { createContextEvidenceReader } from "./context-evidence.js";
 export { downloadImageModel, downloadTextModel, } from "./model-downloads.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
+export { storedMessageNeighbours } from "./project-gathering-around.js";
 import { accountService } from "./account.js";
 import { adminService } from "./admin.js";
 import { adminStatisticsService } from "./admin-statistics.js";

package/dist/services/project-gathering-around.d.ts

@@ -0,0 +1,37 @@
+import type { MessagesStore } from "../store/messages.js";
+export interface ProjectNeighbour {
+    ref: string;
+    at: number;
+    sender: string | null;
+    text: string;
+    found: boolean;
+}
+/** The stored messages next to a hit in its chat, oldest first, without the hit itself. */
+export interface ProjectNeighbourReader {
+    around(ref: string, window: {
+        before: number;
+        after: number;
+    }): Promise<{
+        ref: string;
+        at: number;
+        sender: string | null;
+        text: string;
+    }[]>;
+}
+export declare const storedMessageNeighbours: (messages: Pick<MessagesStore, "around">) => ProjectNeighbourReader;
+/**
+ * Neighbours are context for reading a hit, not matches: they never join `items`, and their text counts against
+ * the run's read bytes.
+ */
+export declare const attachNeighbours: (items: {
+    ref: string;
+    kind: string;
+    around?: ProjectNeighbour[] | null;
+    aroundIssue?: string | null;
+}[], reader: ProjectNeighbourReader | undefined, window: {
+    before: number;
+    after: number;
+}, budget: {
+    remaining: () => number;
+    charge: (bytes: number) => void;
+}, known: (ref: string) => boolean, signal?: AbortSignal) => Promise<void>;

package/dist/services/project-gathering-around.js

@@ -0,0 +1,57 @@
+import { CliError } from "@wirecat/cli-base";
+import { formatLocator, parseLocator } from "../domain/locator.js";
+import { excerpt } from "./excerpt.js";
+export const storedMessageNeighbours = (messages) => ({
+    async around(ref, window) {
+        const at = parseLocator(ref);
+        const rows = await messages.around({ provider: at.provider, account: at.account }, at.chat, at.message, window);
+        return rows
+            .filter((row) => !row.anchor)
+            .map((row) => ({
+            ref: formatLocator({ ...at, message: row.id }),
+            at: Date.parse(row.timestamp),
+            sender: row.senderName,
+            text: row.text ?? "",
+        }));
+    },
+});
+/**
+ * Neighbours are context for reading a hit, not matches: they never join `items`, and their text counts against
+ * the run's read bytes.
+ */
+export const attachNeighbours = async (items, reader, window, budget, known, signal) => {
+    if (!reader || window.before + window.after === 0)
+        return;
+    for (const item of items) {
+        if (item.kind !== "message")
+            continue;
+        if (budget.remaining() <= 0) {
+            item.around = null;
+            item.aroundIssue = "read-bytes";
+            continue;
+        }
+        signal?.throwIfAborted();
+        try {
+            const rows = await reader.around(item.ref, window);
+            const around = [];
+            for (const row of rows.slice(0, window.before + window.after)) {
+                const text = excerpt(row.text, "", 200);
+                const bytes = Buffer.byteLength(text);
+                if (bytes > budget.remaining()) {
+                    item.aroundIssue = "read-bytes";
+                    break;
+                }
+                budget.charge(bytes);
+                around.push({ ...row, text, found: known(row.ref) });
+            }
+            item.around = around;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (!(error instanceof CliError))
+                throw error;
+            item.around = null;
+            item.aroundIssue = error.code;
+        }
+    }
+};

package/dist/services/project-gathering-request.d.ts

@@ -2,6 +2,7 @@ import { type ContextSource } from "../context/evidence.js";
 export interface ProjectGatheringRequest {
     project: {
         name: string;
+        key?: string;
         background?: string;
         aliases?: string[];
     };
@@ -17,6 +18,11 @@ export interface ProjectGatheringRequest {
     before?: number;
     asOf?: number;
     fetch?: "none" | "before-read";
+    index?: "update" | "as-is";
+    around?: {
+        before: number;
+        after: number;
+    };
     budgets?: ProjectGatheringBudgets;
     runKey?: string;
     checkpoint?: string;
@@ -29,7 +35,7 @@ export interface ProjectGatheringBudgets {
     maxElapsedMs?: number;
     maxItems?: number;
 }
-export type ProjectLaneKind = "project" | "alias" | "keyword" | "person";
+export type ProjectLaneKind = "project" | "key" | "alias" | "keyword" | "person";
 export interface ProjectLane {
     id: string;
     kinds: ProjectLaneKind[];
@@ -73,6 +79,7 @@ export declare const CONTEXT_CHUNK_DAYS = 90;
 export declare const projectGatheringRequest: (input: ProjectGatheringRequest, now: number) => {
     project: {
         name: string;
+        key: string | null;
         background: string | null;
         aliases: string[];
     };
@@ -91,6 +98,11 @@ export declare const projectGatheringRequest: (input: ProjectGatheringRequest, n
         asOf: number;
     };
     fetch: "before-read" | "none";
+    index: "as-is" | "update";
+    around: {
+        before: number;
+        after: number;
+    };
     budgets: Required<ProjectGatheringBudgets>;
     fingerprint: string;
     runKey: string;

package/dist/services/project-gathering-request.js

@@ -55,6 +55,8 @@ export const projectGatheringRequest = (input, now) => {
         "before",
         "asOf",
         "fetch",
+        "index",
+        "around",
         "budgets",
         "runKey",
         "checkpoint",
@@ -62,9 +64,10 @@ export const projectGatheringRequest = (input, now) => {
     ], "");
     if (!input.project || typeof input.project !== "object")
         fail("project needs a name", "project");
-    known(input.project, ["name", "background", "aliases"], "project.");
+    known(input.project, ["name", "key", "background", "aliases"], "project.");
     const project = {
         name: text(input.project.name, "project.name", 512),
+        key: input.project.key === undefined ? null : text(input.project.key, "project.key", 64),
         background: input.project.background === undefined ? null : text(input.project.background, "project.background", 8192),
         aliases: list(input.project.aliases, "project.aliases", LIMITS.lanes).map((a, i) => text(a, `project.aliases.${i}`, 512)),
     };
@@ -104,6 +107,8 @@ export const projectGatheringRequest = (input, now) => {
             found.people.push(person);
     };
     lane("project", laneQuery(project.name, "project.name"));
+    if (project.key)
+        lane("key", laneQuery(project.key, "project.key"));
     for (const [i, a] of project.aliases.entries())
         lane("alias", laneQuery(a, `project.aliases.${i}`));
     for (const k of keywords)
@@ -113,19 +118,30 @@ export const projectGatheringRequest = (input, now) => {
     if (lanes.length > LIMITS.lanes)
         fail(`at most ${LIMITS.lanes} distinct search lanes`, "keywords");
     const fetch = input.fetch ?? "none";
+    const index = input.index ?? "update";
+    if (index !== "update" && index !== "as-is")
+        fail("index must be update or as-is", "index");
+    if (input.around !== undefined && (!input.around || typeof input.around !== "object"))
+        fail("around needs before and after", "around");
+    if (input.around)
+        known(input.around, ["before", "after"], "around.");
+    const around = {
+        before: whole(input.around?.before ?? 2, "around.before", 0, 5),
+        after: whole(input.around?.after ?? 2, "around.after", 0, 5),
+    };
     if (fetch !== "none" && fetch !== "before-read")
         fail("fetch must be none or before-read", "fetch");
     const explicit = input.after !== undefined || input.before !== undefined;
     if (explicit && input.lookbackDays !== undefined)
         fail("give lookbackDays or after/before, not both", "lookbackDays");
-    if (explicit && (input.after === undefined || input.before === undefined))
-        fail("an explicit window needs both after and before", input.after === undefined ? "after" : "before");
+    if (explicit && input.after === undefined)
+        fail("an explicit window needs after; before defaults to asOf", "after");
     const asOf = input.asOf === undefined ? null : whole(input.asOf, "asOf", 1, MAX_TIME);
     const lookbackDays = explicit ? null : whole(input.lookbackDays ?? 60, "lookbackDays", 1, LIMITS.lookbackDays);
     const window = explicit
         ? (() => {
             const after = whole(input.after, "after", 0, MAX_TIME);
-            const before = whole(input.before, "before", after + 1, MAX_TIME);
+            const before = whole(input.before ?? asOf ?? now, "before", after + 1, MAX_TIME);
             if (before - after > LIMITS.lookbackDays * DAY)
                 fail(`window must not exceed ${LIMITS.lookbackDays} days`, "after");
             return { after, before, asOf: asOf ?? before };
@@ -150,7 +166,7 @@ export const projectGatheringRequest = (input, now) => {
         sources.map(contextSourceKey),
         input.scope,
         lookbackDays,
-        explicit ? [window.after, window.before] : null,
+        explicit ? [window.after, input.before ?? null] : null,
         asOf,
         fetch,
     ]))
@@ -168,6 +184,8 @@ export const projectGatheringRequest = (input, now) => {
         lookbackDays,
         window,
         fetch,
+        index,
+        around,
         budgets,
         fingerprint,
         runKey,

package/dist/services/project-gathering.d.ts

@@ -1,4 +1,5 @@
-import type { ContextEvidenceItem, ContextEvidenceReader, ContextSource } from "../context/evidence.js";
+import type { ContextEvidenceItem, ContextEvidenceReader, ContextIndex, ContextSource } from "../context/evidence.js";
+import { type ProjectNeighbour, type ProjectNeighbourReader } from "./project-gathering-around.js";
 import { type ProjectFetchState, type ProjectGatheringRequest, type ProjectLane } from "./project-gathering-request.js";
 /** A connector's history fetch into the store; the store reads that follow find what it saved. */
 export interface ProjectSourceFetcher {
@@ -15,8 +16,16 @@ export interface ProjectSourceFetcher {
 export interface ProjectGatheringPorts {
     evidence: ContextEvidenceReader;
     fetcher?: ProjectSourceFetcher;
+    index?: ContextIndex;
+    neighbours?: ProjectNeighbourReader;
     now?: () => number;
 }
+export interface ProjectIndexCatchUp {
+    state: "updated" | "as-is" | "unavailable" | "failed";
+    mail: number;
+    documents: number;
+    code: string | null;
+}
 export interface ProjectEvidenceItem extends Omit<ContextEvidenceItem, "text"> {
     kind: ContextSource["kind"];
     source: number;
@@ -24,6 +33,8 @@ export interface ProjectEvidenceItem extends Omit<ContextEvidenceItem, "text"> {
     textTruncated: boolean;
     lanes: string[];
     context: "project" | "person-only";
+    around?: ProjectNeighbour[] | null;
+    aroundIssue?: string | null;
 }
 export type ProjectGatheringStop = "reads" | "read-bytes" | "elapsed" | "items" | null;
 export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, request: ProjectGatheringRequest) => Promise<{
@@ -33,6 +44,7 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
     resumed: boolean;
     project: {
         name: string;
+        key: string | null;
         background: string | null;
         aliases: string[];
     };
@@ -55,6 +67,7 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
         code: string | null;
         source: number;
     }[];
+    index: ProjectIndexCatchUp;
     units: {
         lane: string;
         source: number;
@@ -72,6 +85,7 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
     usage: {
         reads: number;
         readBytes: number;
+        aroundBytes: number;
         items: number;
         elapsedMs: number;
     };

package/dist/services/project-gathering.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { createContextEvidenceReader } from "./context-evidence.js";
 import { excerpt } from "./excerpt.js";
+import { attachNeighbours } from "./project-gathering-around.js";
 import { decodeCheckpoint, encodeCheckpoint, projectGatheringRequest, projectUnits, seenKey, } from "./project-gathering-request.js";
 const terminal = new Set(["done", "unavailable", "failed"]);
 export const gatherProjectEvidence = async (ports, request) => {
@@ -12,6 +13,9 @@ export const gatherProjectEvidence = async (ports, request) => {
     const previous = plan.checkpoint === undefined ? null : decodeCheckpoint(plan.checkpoint, plan);
     const window = previous ?? plan.window;
     const units = projectUnits(plan, window);
+    // A default that cannot finish one round would leave whole searches or sources unread; an explicit one is kept.
+    if (request.budgets?.maxReads === undefined)
+        plan.budgets.maxReads = Math.min(512, Math.max(48, units.length));
     if (previous && (previous.units.length !== units.length || previous.fetched.length !== plan.sources.length))
         throw new CliError("validation_error", "invalid project gathering checkpoint", { param: "checkpoint" });
     const progress = previous?.units.map((u) => ({ ...u })) ??
@@ -43,7 +47,27 @@ export const gatherProjectEvidence = async (ports, request) => {
                 fetched[index] = { state: "failed", history: null, code: error.code };
             }
         }
-    const usage = { reads: 0, readBytes: 0, items: 0 };
+    const indexed = { state: "as-is", mail: 0, documents: 0, code: null };
+    const kinds = [...new Set(plan.sources.map((source) => source.kind))].filter((kind) => kind !== "message");
+    if (plan.index === "update" && kinds.length) {
+        signal?.throwIfAborted();
+        if (!ports.index || typeof ports.index.catchUp !== "function")
+            indexed.state = "unavailable";
+        else
+            try {
+                const done = await ports.index.catchUp({ kinds, signal });
+                if (!Number.isSafeInteger(done?.mail) || !Number.isSafeInteger(done?.documents))
+                    throw new CliError("invalid_response", "index catch-up returned invalid counts");
+                Object.assign(indexed, { state: "updated", mail: done.mail, documents: done.documents });
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                if (!(error instanceof CliError))
+                    throw error;
+                Object.assign(indexed, { state: "failed", code: error.code });
+            }
+    }
+    const usage = { reads: 0, readBytes: 0, aroundBytes: 0, items: 0 };
     const items = [];
     const byRef = new Map();
     const matchedAgain = new Map();
@@ -145,6 +169,12 @@ export const gatherProjectEvidence = async (ports, request) => {
             }
         }
     }
+    await attachNeighbours(items, ports.neighbours, plan.around, {
+        remaining: () => plan.budgets.maxReadBytes - usage.readBytes - usage.aroundBytes,
+        charge: (bytes) => {
+            usage.aroundBytes += bytes;
+        },
+    }, (ref) => byRef.has(ref) || seen.has(seenKey(ref)), signal);
     const totals = {
         reads: (previous?.totals.reads ?? 0) + usage.reads,
         readBytes: (previous?.totals.readBytes ?? 0) + usage.readBytes,
@@ -181,6 +211,7 @@ export const gatherProjectEvidence = async (ports, request) => {
         scope: { origin: plan.scope, sources: plan.sources },
         lanes: plan.lanes,
         fetch: fetched.map((f, index) => ({ source: index, ...f })),
+        index: indexed,
         units: units.map((unit, index) => ({
             lane: unit.lane.id,
             source: unit.sourceIndex,

package/dist/store/sqlite/context-evidence.d.ts

@@ -1,4 +1,7 @@
-import { type ContextEvidenceReader } from "../../context/evidence.js";
+import { type ContextEvidenceReader, type ContextIndex } from "../../context/evidence.js";
+import type { Stemmer, Stemmers } from "../../search/stem.js";
 import type { StoreContext } from "./open.js";
 /** No index fills, model loads or record hydration outside the read transaction. */
 export declare const contextEvidenceOver: ({ database }: Pick<StoreContext, "database">) => ContextEvidenceReader;
+/** The same fills a mail search and the notes search run before reading; a message is indexed when it is saved. */
+export declare const contextIndexOver: ({ database }: Pick<StoreContext, "database">, stemmerFor: (stemmers: Stemmers) => Stemmer) => ContextIndex;

package/dist/store/sqlite/context-evidence.js

@@ -3,6 +3,8 @@ import { contextCursorScope, contextEvidenceRequest, } from "../../context/evide
 import { formatLocator } from "../../domain/locator.js";
 import { NORMALIZER_VERSION, normalize } from "../normalize.js";
 import { contextDocumentTime, contextDocumentTimeKind, contextDocumentUrl } from "./context-document-source.js";
+import { drainEmailIndex } from "./email-index.js";
+import { drainNoteIndex } from "./note-index.js";
 import { read } from "./transaction.js";
 const corpora = {
     message: {
@@ -163,3 +165,13 @@ export const contextEvidenceOver = ({ database }) => ({
         });
     },
 });
+/** The same fills a mail search and the notes search run before reading; a message is indexed when it is saved. */
+export const contextIndexOver = ({ database }, stemmerFor) => ({
+    async catchUp({ kinds, signal }) {
+        signal?.throwIfAborted();
+        const mail = kinds.includes("mail") ? drainEmailIndex(database, stemmerFor) : 0;
+        signal?.throwIfAborted();
+        const documents = kinds.includes("document") ? drainNoteIndex(database, stemmerFor) : 0;
+        return { mail, documents };
+    },
+});

package/dist/store/store.d.ts

@@ -1,4 +1,4 @@
-import type { ContextEvidenceReader } from "../context/evidence.js";
+import type { ContextEvidenceReader, ContextIndex } from "../context/evidence.js";
 import { type AccountStore } from "./account-store.js";
 import { type AccountsStore } from "./accounts.js";
 import { type AttachmentsStore } from "./attachments.js";
@@ -34,6 +34,7 @@ import type { AccountKey } from "./types.js";
 import { type VectorsStore } from "./vectors.js";
 export interface MessageStore {
     readonly contextEvidence?: ContextEvidenceReader;
+    readonly contextIndex?: ContextIndex;
     /** Accounts, account groups and which account each app profile is. */
     readonly accounts: AccountsStore;
     /** One account's chats: the list, what left, what is complete, their metadata. */

package/dist/store/store.js

@@ -16,7 +16,7 @@ import { agentActionsStoreOver } from "./sqlite/agent-actions.js";
 import * as attachmentTexts from "./sqlite/attachment-texts.js";
 import { botUpdateStoreOver } from "./sqlite/bot-updates.js";
 import { catalogStoreOver } from "./sqlite/catalog.js";
-import { contextEvidenceOver } from "./sqlite/context-evidence.js";
+import { contextEvidenceOver, contextIndexOver } from "./sqlite/context-evidence.js";
 import { mailStoreOver } from "./sqlite/emails.js";
 import { factsStoreOver } from "./sqlite/facts.js";
 import { involvementStoreOver } from "./sqlite/involvements.js";
@@ -81,6 +81,7 @@ const storeOver = (context) => {
         mentions: areaOf(() => accountMentionsOver(context), (keyed) => mentionsStoreOver(context, keyed)),
     };
     const contextEvidence = once(() => contextEvidenceOver(context));
+    const contextIndex = once(() => contextIndexOver(context, stemmerFor));
     const searches = once(() => searchesStoreOver(context));
     const queries = once(() => queriesStoreOver(context, stemmerFor));
     const searchIndex = once(() => searchIndexStoreOver(context));
@@ -101,6 +102,9 @@ const storeOver = (context) => {
         get contextEvidence() {
             return contextEvidence();
         },
+        get contextIndex() {
+            return contextIndex();
+        },
         meetingVectors: meetingVectorsOver(context),
         get accounts() {
             return areas.accounts().whole;

package/dist/terminal/login-qr.d.ts

@@ -19,8 +19,11 @@ export interface LoginQrOptions {
 }
 export interface LoginQr {
     readonly path: string | undefined;
-    /** Never throws for a code that does not fit: the messengers call it from inside their own event loops. */
-    show: (link: string) => void;
+    /**
+     * `scan` says where to scan; it follows the code, and is not said when the terminal is too narrow to draw one.
+     * Never throws for a code that does not fit: the messengers call it from inside their own event loops.
+     */
+    show: (link: string, scan?: string) => void;
     /** The image logs the account in while it is valid; call this in `finally`. */
     close: () => void;
 }

package/dist/terminal/login-qr.js

@@ -17,11 +17,13 @@ export const loginQr = ({ qrFile, diagnostic, note, indent: pad = 0, columns = (
     let written = false;
     return {
         path,
-        show: (link) => {
+        show: (link, scan) => {
             if (path) {
                 writeSecurely(path, qrPng(link), 0o600);
                 written = true;
                 note(`the QR code is in ${path} — it is replaced when the code renews`);
+                if (scan)
+                    note(scan);
                 return;
             }
             const drawn = terminalQr(link);
@@ -33,6 +35,8 @@ export const loginQr = ({ qrFile, diagnostic, note, indent: pad = 0, columns = (
                 return;
             }
             diagnostic(`\n${indent(drawn.text, pad + MARGIN)}`);
+            if (scan)
+                note(scan);
         },
         close: () => {
             if (!path || !written)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.348.0",
+  "version": "0.350.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",

package/parity.json

@@ -4053,12 +4053,7 @@
           "in": ["tg"],
           "reason": "Telegram asks each client for its own app from my.telegram.org; MAX has no such step; WhatsApp has no application registration"
         },
-        "--qr-file": {
-          "in": ["tg", "wa"],
-          "planned": {
-            "max": "max-cli#736, on the cli-core release that exports loginQr"
-          }
-        },
+        "--qr-file": "all",
         "--sms": {
           "in": ["tg"],
           "reason": "asks Telegram to resend its login code by SMS; MAX has no such choice; WhatsApp links a device by QR or pairing code, never by an SMS code"
@@ -4074,12 +4069,7 @@
           "reason": "Telegram requires an application from my.telegram.org; MAX has no application registration step; WhatsApp has no application registration"
         },
         "--method": "all",
-        "--qr-file": {
-          "in": ["tg", "wa"],
-          "planned": {
-            "max": "max-cli#736, on the cli-core release that exports loginQr"
-          }
-        }
+        "--qr-file": "all"
       }
     },
     "skill": {