@wirecat/cli-core 0.347.0 → 0.349.0

package/CHANGELOG.md

@@ -7,6 +7,88 @@ shape of this file.
 
 ## Unreleased
 
+## 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
+
+- **A next step in `--json` output and in an error carries `line`, the whole command with the profile**:
+  `"line": "max personal mcp config"` beside `"command": "mcp config"`. A copied `command` alone failed with "name a
+  profile". MCP answers leave it out; `command` is unchanged.
+- **`searchAll(…, { app, hintCommand })`**: the tool a missing-model hint names, apart from `app.command`. memo passes
+  tg's identity for `group:` lists but has no `models` command; `hintCommand: null` names the tools that have one
+  (tg, max or wa) instead of `tg models text download`. `searchAllIncludingMeetings` and `searchAllWithMeetings`
+  take it too (`SearchAllMessenger`).
+- **`commandsText(program, describeProgram(program), scope?)` from `./cli`**: the `<tool> commands` text list by
+  section, for a tool that builds its own commander program and keeps its own `commands` command (zm, drive, memo).
+  cli-core's groups land in their section on such a program too; before, only `createProgram` put them there.
+- **A messenger whose history is in the store can save the history pushed during any command, not only `serve`
+  and `watch`.** `PassiveUpdates` may now also have `listenHistory(onBatch, signal)`, optional even in an adapter
+  typed as `PassiveUpdates`: it hands on the same `HistoryBatch`es as `feed`, re-keys included, from a connection that
+  does not watch, without connecting. A one-shot command and an MCP session then save them through `feed`'s own
+  code, and `close` stops it with `listen` (both within 5 s in all) before it waits for the saves. Without it, a
+  WhatsApp history push that came during such a command was acknowledged and then lost. An adapter without it
+  behaves as before. Its run record is an `adapter.listenHistory` request whose response counts `batches` and each
+  part's items (`rekeys`, `chats`, `messages`, …); a failure is a `listen_failed` warning for `history.listen`. The
+  contract kit checks it as it checks `listen` when the adapter has it, `OPTIONAL_METHODS` lists it, and
+  `fakeAdapter(seed, { listenHistory: true })` has it.
+
+### Changed — may break callers
+
+- **Peer `@wirecat/cli-base` is `>=0.47.0 <0.48.0`** (was `>=0.45.0 <0.47.0`): 0.47.0 is the first whose strict
+  `nextStepSchema` accepts `line`, so a tool on an older cli-base would refuse cli-core's own answers in its schema
+  checks. Bump cli-base with cli-core.
+- **Saving a chat keeps a `title`, `unreadCount`, `lastMessageAt` or `participantsCount` the update leaves out**, the
+  rule #1596 set for `providerMetadata` keys and `parentChatId`: left out keeps the stored value, `null` stores none,
+  a value replaces it. So a push that knows only part of a chat, such as WhatsApp's notice that a group left its
+  community, sends `{ id, kind, parentChatId: null }` and no longer erases the rest. `saveChats`, `Delta.chats` and
+  `HistoryBatch.chats` take the new `ChatUpdate` type, a `Chat` with those four fields optional; a full `Chat` still
+  fits, and every adapter today sends all four, so none has to change. To clear a field, send `null`, never leave it
+  out. Code that reads `HistoryBatch.chats` or `Delta.chats` now sees the four fields as possibly absent.
+
+### Fixed
+
+- **The first screen names only the option topics the tool has.** `help options` was described as "output, offline,
+  timeouts, dry run" on every program; a tool with its own program and none of `--json`, `--offline`, `--timeout`,
+  `--dry-run` (memo, zm, drive) now reads "the options every command takes", and one with some names those.
+- **A guide step may ask for help.** `checkGuide` refused `chat messages list --help` and `-h` ("no option --help")
+  and `chat messages --help` ("needs one of: …"); a step with the help flag now only needs its command path to exist.
+- **A command's own help settings survive the `<profile>` usage line.** `createProgram` replaced each command's help
+  configuration when it set the usage line, so tg's `setup --help` lost its "Global Options" block
+  (`showGlobalOptions`). It now adds the usage line to what the command set.
+- **Hints in errors and notes name the profile**: "the store is behind this build — `max personal store migrate`"
+  instead of `max store migrate`, which fails with "name a profile" when copied. Covers about 30 hints (store, runs,
+  schedules, sync, models, conversations, serve, MCP's photo and transcribe tools). `typedCommand(tool, words)`
+  (run scope) and `lineOf(command, words)` build them; a run's scope now carries its `profile`. Consumers' tests
+  that match these messages change on bump.
+
 ## 0.347.0 — 18.10.2026
 
 ### Added

package/dist/cli/bot/copy.d.ts

@@ -9,7 +9,7 @@ import type { BotEvent } from "./port.js";
 export declare const botCopy: (provider: Provider) => {
     accountOf: (botId: string) => AccountKey;
     keep: (botId: string, messages: readonly Message[], via: IngestedVia, warn: (message: string) => void, senders?: readonly PersonFacts[]) => Promise<boolean>;
-    /** Only a chat the messenger has just described in full: the store replaces a title it is not given. */
+    /** Only a chat the messenger has just described in full: the store takes its title and counts as given. */
     keepChat: (botId: string, chat: Chat, warn: (message: string) => void) => Promise<void>;
     /** Messages the bot deleted, kept as tombstones: reads and search stop returning them. */
     forget: (botId: string, chatId: string, messageIds: string[], warn: (message: string) => void) => Promise<boolean>;

package/dist/cli/bot/copy.js

@@ -57,7 +57,7 @@ export const botCopy = (provider) => {
                     await store.people.savePeople(accountOf(botId), [...senders]);
             }, warn);
         },
-        /** Only a chat the messenger has just described in full: the store replaces a title it is not given. */
+        /** Only a chat the messenger has just described in full: the store takes its title and counts as given. */
         keepChat: async (botId, chat, warn) => {
             if (CHAT_ID.test(chat.id))
                 await quietly((store) => store.chats.saveChats(accountOf(botId), [chat]), warn);

package/dist/cli/embedding-choice.js

@@ -4,6 +4,7 @@ import { embeddingKeys, endpointKeyName } from "../embeddings/keys.js";
 import { DEFAULT_TEXT_MODEL } from "../embeddings/models.js";
 import { isLocal, remoteModel } from "../embeddings/remote.js";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
+import { typedCommand } from "../runs/scope.js";
 /** A local model id, or a remote model with its key from `models text key set`. */
 export const embeddingChoice = ({ model, provider, baseUrl, dims, concurrency }, app, settings, env, { needKey = true, keyring } = {}) => {
     const flagsChooseProvider = (provider !== undefined && provider !== (settings.embeddingProvider ?? "local")) ||
@@ -30,7 +31,7 @@ export const embeddingChoice = ({ model, provider, baseUrl, dims, concurrency },
     const keyName = baseUrl === undefined ? "openai" : endpointKeyName(baseUrl);
     const key = embeddingKeys(app, env, keyring).read(keyName)?.key;
     if (!key && needKey && baseUrl === undefined) {
-        throw new CliError("authentication_error", `no OpenAI key — \`${app.command} models text key set openai\`, or OPENAI_API_KEY`);
+        throw new CliError("authentication_error", `no OpenAI key — \`${typedCommand(app.command, "models text key set openai")}\`, or OPENAI_API_KEY`);
     }
     return { remote, ...(key ? { apiKey: key } : {}), ...(concurrency ? { concurrency } : {}) };
 };

package/dist/cli/envelope.d.ts

@@ -44,6 +44,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly step: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>;
         readonly command: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         readonly args: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
+        readonly line: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
         readonly why: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         readonly safe_to_auto_execute: v.BooleanSchema<undefined>;
     }, undefined>, v.StrictObjectSchema<{
@@ -58,6 +59,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         args: {
             [x: string]: unknown;
         };
+        line?: string | undefined;
         why: string;
         safe_to_auto_execute: boolean;
     } | {
@@ -90,6 +92,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly step: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>;
         readonly command: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         readonly args: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
+        readonly line: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
         readonly why: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         readonly safe_to_auto_execute: v.BooleanSchema<undefined>;
     }, undefined>, v.StrictObjectSchema<{
@@ -104,6 +107,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         args: {
             [x: string]: unknown;
         };
+        line?: string | undefined;
         why: string;
         safe_to_auto_execute: boolean;
     } | {

package/dist/cli/envelope.js

@@ -3,9 +3,9 @@ import { metaOf } from "@wirecat/cli-base/commands";
 import { itemEnvelopeSchema, jsonlOf, listEnvelopeSchema, MAX_NEXT_STEPS, } from "@wirecat/cli-base/standards";
 import * as v from "valibot";
 import { currentRun } from "../runs/scope.js";
-import { setExitCode } from "./context.js";
+import { environmentOf, setExitCode } from "./context.js";
 import { withoutProviderRefs } from "./provider-refs.js";
-import { nextStep, rootOf, runnable, stepLine, withSafety } from "./steps.js";
+import { nextStep, rootOf, runnable, stepLine, withLines, withSafety } from "./steps.js";
 /** Every answer: a list or one thing, with items of `item` — any value where the command declares no entity. */
 export const answerSchema = (item = v.unknown()) => v.union([listEnvelopeSchema(item), itemEnvelopeSchema(item)]);
 const capped = (steps) => (steps.length > 0 ? { next: steps.slice(0, MAX_NEXT_STEPS) } : {});
@@ -131,7 +131,8 @@ export const renderAnswer = (command, { renderer, format, streams }, body, view)
     if (!isBody(body))
         refuse(body);
     const root = rootOf(command);
-    const next = runnable(root, body.next);
+    const runnableSteps = runnable(root, body.next);
+    const next = environmentOf(command).agent ? runnableSteps : withLines(root, runnableSteps);
     const kept = withoutProviderRefs({ ...body, ...(next.length > 0 ? { next } : {}) });
     if (next.length === 0)
         delete kept.next;

package/dist/cli/guide.js

@@ -211,6 +211,10 @@ export const checkStep = (program, run) => {
     }
     if (at === program)
         return [`no command "${rest[0] ?? ""}" — steps leave out the profile`];
+    const help = at._getHelpOption();
+    const beforeDashes = rest.slice(index, rest.includes("--") ? rest.indexOf("--") : undefined);
+    if (help && beforeDashes.some((word) => word === help.long || word === help.short))
+        return [];
     if (at.commands.length > 0)
         return [`needs one of: ${at.commands.map((one) => one.name()).join(", ")}`];
     for (const command of chain)

package/dist/cli/help/first-screen.js

@@ -17,13 +17,25 @@ export const WIRECAT_TOOLS = [
 const WIDTH = 100;
 const widest = (texts) => texts.reduce((most, text) => Math.max(most, text.length), 0);
 const block = (title, rows, column) => rows.length === 0 ? [] : ["", `${title}:`, ...rows.map(([left, right]) => `  ${left.padEnd(column)}${right}`)];
+const TOPICS = [
+    ["--json", "output"],
+    ["--offline", "offline"],
+    ["--timeout", "timeouts"],
+    ["--dry-run", "dry run"],
+];
+/** Only the topics this program has options for: memo has no --offline. */
+const optionTopics = (program) => {
+    const longs = new Set(program.options.map((option) => option.long));
+    const topics = TOPICS.filter(([long]) => longs.has(long)).map(([, topic]) => topic);
+    return topics.length > 0 ? topics.join(", ") : "the options every command takes";
+};
 /** Only commands the tool has: `guide` and `setup` are not in every tool. */
 const pointers = (program, cli, start, profile) => {
     const has = (path) => commandAt(program, path) !== undefined;
     const next = [
         has("commands") ? [`${cli} commands`, "every command, by section"] : undefined,
         has("guide") ? [`${cli} guide`, "scenarios: command sequences for common tasks"] : undefined,
-        [`${cli} help options`, "output, offline, timeouts, dry run"],
+        [`${cli} help options`, optionTopics(program)],
     ].filter((row) => row !== undefined);
     const rows = [
         ...(start ? [["Start here:", start, profile ? "(any profile name works)" : ""]] : []),

package/dist/cli/help/sections.d.ts

@@ -13,7 +13,8 @@ export type HelpSection = Exclude<keyof typeof SECTIONS, "other">;
  * fields of `commands --json`, which must not change.
  */
 export declare const inSection: <T extends Command>(command: T, section: HelpSection) => T;
-/** The nearest section on the command or above it; `other` when none is set. */
+/**
+ * The nearest section on the command or above it, then cli-core's own for a top-level group of that name; `other`
+ * when neither is set. Looked up when listed, so a tool with its own program needs no install step.
+ */
 export declare const sectionOf: (command: Command) => keyof typeof SECTIONS;
-/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
-export declare const sectionCoreGroups: (program: Command) => void;

package/dist/cli/help/sections.js

@@ -15,10 +15,13 @@ export const inSection = (command, section) => {
     sections.set(command, section);
     return command;
 };
-/** The nearest section on the command or above it; `other` when none is set. */
+/**
+ * The nearest section on the command or above it, then cli-core's own for a top-level group of that name; `other`
+ * when neither is set. Looked up when listed, so a tool with its own program needs no install step.
+ */
 export const sectionOf = (command) => {
     for (let at = command; at; at = at.parent) {
-        const section = sections.get(at);
+        const section = sections.get(at) ?? (at.parent && !at.parent.parent ? CORE_SECTIONS[at.name()] : undefined);
         if (section)
             return section;
     }
@@ -67,11 +70,3 @@ const CORE_SECTIONS = {
     store: "setup",
     upgrade: "setup",
 };
-/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
-export const sectionCoreGroups = (program) => {
-    for (const command of program.commands) {
-        const section = CORE_SECTIONS[command.name()];
-        if (section && !sections.has(command))
-            inSection(command, section);
-    }
-};

package/dist/cli/index.d.ts

@@ -58,6 +58,7 @@ export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer,
 export { withAbort } from "./execution.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, type Scenario, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
+export { commandsText } from "./help/commands-text.js";
 export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
 export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";

package/dist/cli/index.js

@@ -53,6 +53,7 @@ export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, m
 export { withAbort } from "./execution.js";
 export { checkGuide, checkStep, guideCommand, loadScenarios, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
+export { commandsText } from "./help/commands-text.js";
 export { firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
 export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";

package/dist/cli/messenger/backfill-command.js

@@ -17,7 +17,7 @@ import { destroysNothing, FETCH, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { listQuery, pagedList, pageOf, typedQuery, withQuery } from "../list-query.js";
 import { withPaging } from "../paging.js";
-import { nextStep } from "../steps.js";
+import { lineOf, nextStep } from "../steps.js";
 import { finishJob, jobDetails, jobStarted, jobsDir, listJobs, readJob, removeJob, saveJob, spawnDetached, stateOf, tracedJob, updateJob, } from "./backfill-jobs.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { reviewPoint } from "./mention-points.js";
@@ -60,7 +60,7 @@ export const syncCommand = (messenger) => {
             throw new CliError("validation_error", "--dry-run prices one chat; not with --all");
         if (all && messenger.history === "store") {
             throw new CliError("validation_error", `--all walks the messenger's chat list, and ${messenger.name ?? messenger.app.command} pushes its chats ` +
-                `instead — keep \`${messenger.app.command} serve\` running${messenger.historyOnDemand ? ", or name one chat" : ""}`);
+                `instead — keep \`${lineOf(this, "serve")}\` running${messenger.historyOnDemand ? ", or name one chat" : ""}`);
         }
         if (since !== undefined && last !== undefined) {
             throw new CliError("validation_error", "give --since-time or --last, not both: how far back the fetch goes");
@@ -91,7 +91,7 @@ export const syncCommand = (messenger) => {
             const answer = await context.withServices((services) => services.archive.estimate(named, { limit, pageSize, pauseMs }));
             renderAnswer(this, context, itemOf(snakeKeys(answer)));
             if (answer.missing === null) {
-                context.renderer.note(`nothing held of this chat to measure by — \`${messenger.app.command} messages sync ${chat} --limit ${pageSize}\` gives the estimate something to go on`);
+                context.renderer.note(`nothing held of this chat to measure by — \`${lineOf(this, `messages sync ${chat} --limit ${pageSize}`)}\` gives the estimate something to go on`);
             }
             else if (answer.missing > 0)
                 context.renderer.note("an estimate: provider waits (FloodWait) come on top");
@@ -167,10 +167,10 @@ export const syncCommand = (messenger) => {
             }));
             if (tasks?.held)
                 context.renderer.note(`the first sync left ${tasks.held} possible task(s) in ${tasks.heldChats ?? 0} chat(s) unopened ` +
-                    `(config task_first_pass_per_chat) — ask the owner, then \`${messenger.app.command} tasks scan <chat>\``);
+                    `(config task_first_pass_per_chat) — ask the owner, then \`${lineOf(this, "tasks scan <chat>")}\``);
             if (toReview > 0)
                 context.renderer.note(`${shown} mention${toReview === 1 ? "" : "s"} found since the last review — ` +
-                    `\`${messenger.app.command} mentions list --new\``);
+                    `\`${lineOf(this, "mentions list --new")}\``);
         }
         catch (error) {
             if (jobId) {
@@ -327,7 +327,7 @@ const launchJob = (command, context, messenger, { chat, argv, limit, pageSize, l
     const dir = jobsDir(app, context.env);
     const running = listJobs(dir).find((job) => job.profile === context.profile && job.chat === chat && stateOf(job) === "running");
     if (running) {
-        throw new CliError("validation_error", `job ${running.id} is already fetching ${chat} (PID ${running.pid}) — \`${app.command} store jobs show ${running.id}\``);
+        throw new CliError("validation_error", `job ${running.id} is already fetching ${chat} (PID ${running.pid}) — \`${app.command} ${context.profile} store jobs show ${running.id}\``);
     }
     const now = new Date();
     const id = `${now.toISOString().replace(/[-:]/g, "").slice(0, 15)}-${randomBytes(3).toString("hex")}`;

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

@@ -230,9 +230,9 @@ export interface MessengerContext extends BaseContext {
  * the reads answer saved to the store. `close` closes the connection and the store it opened. One
  * function, so a command and an MCP tool call save and record exactly alike.
  *
- * A `history: "store"` messenger with `listen` saves what arrives for as long as a connection that does not
- * `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again. A
- * connection opened with `listen: true` is left to its `watch`, which saves the same events.
+ * A `history: "store"` messenger with `listen` or `listenHistory` saves what arrives for as long as a connection that
+ * does not `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again.
+ * A connection opened with `listen: true` is left to its `watch` and `feed`, which save the same.
  */
 export declare const connected: (connection: MessengerAdapter, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, }: Pick<Messenger, "app" | "provider" | "name" | "deletedWithoutChat" | "pace" | "history" | "savedChatId">, { settings, env, renderer }: Pick<BaseContext, "settings" | "env" | "renderer">, events: EventSink, store?: LazyStore, { listen: watching }?: Pick<ConnectOptions, "listen">) => {
     adapter: MessengerAdapter;

package/dist/cli/messenger/context.js

@@ -114,24 +114,24 @@ const settled = async (pending, ms) => {
     }
 };
 /**
- * Runs the adapter's `listen` until `stop`, which answers whether it ended in time. A listen that fails warns and
+ * Runs one passive listen until `stop`, which answers whether it ended in time. A listen that fails warns and
  * never fails the command; one that fails once the connection is `closing` is the close, not news. It still listens
  * while the connection closes, so what arrives then is saved too.
  */
-const listened = (adapter, events, warn) => {
-    if (!adapter.listen)
-        return undefined;
+const listened = ({ run, operation, what }, events, warn) => {
     const abort = new AbortController();
     let closing = false;
     const ended = Promise.resolve()
-        .then(() => adapter.listen?.(() => { }, abort.signal))
+        .then(() => run(abort.signal))
         .catch((error) => {
         if (closing)
             return;
-        events({ event: "warning", code: "listen_failed", operation: "messages.listen" });
-        warn(`messages arriving during this command are not saved: ${error instanceof Error ? error.message : String(error)}`);
+        events({ event: "warning", code: "listen_failed", operation });
+        warn(`${what} arriving during this command are not saved: ${error instanceof Error ? error.message : String(error)}`);
     });
     return {
+        operation,
+        what,
         closing: () => {
             closing = true;
         },
@@ -141,6 +141,27 @@ const listened = (adapter, events, warn) => {
         },
     };
 };
+/** The passive listens a connection of a `history: "store"` messenger runs: the ones its adapter has. */
+const passivesOf = (adapter) => [
+    ...(adapter.listen
+        ? [
+            {
+                run: (signal) => adapter.listen?.(() => { }, signal),
+                operation: "messages.listen",
+                what: "messages",
+            },
+        ]
+        : []),
+    ...(adapter.listenHistory
+        ? [
+            {
+                run: (signal) => adapter.listenHistory?.(() => { }, signal),
+                operation: "history.listen",
+                what: "history batches",
+            },
+        ]
+        : []),
+];
 /** A list that cannot be read stays as it is, which refuses every send: the warning says why. */
 const rekeyRecipients = async (app, profile, env, warn, from, to) => {
     try {
@@ -155,9 +176,9 @@ const rekeyRecipients = async (app, profile, env, warn, from, to) => {
  * the reads answer saved to the store. `close` closes the connection and the store it opened. One
  * function, so a command and an MCP tool call save and record exactly alike.
  *
- * A `history: "store"` messenger with `listen` saves what arrives for as long as a connection that does not
- * `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again. A
- * connection opened with `listen: true` is left to its `watch`, which saves the same events.
+ * A `history: "store"` messenger with `listen` or `listenHistory` saves what arrives for as long as a connection that
+ * does not `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again.
+ * A connection opened with `listen: true` is left to its `watch` and `feed`, which save the same.
  */
 export const connected = (connection, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, }, { settings, env, renderer }, events, store = lazyStore(env, app.command), { listen: watching = false } = {}) => {
     const self = connection.self();
@@ -185,20 +206,26 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
             rekeyed: (from, to) => rekeyRecipients(app, settings.profile, env, renderer.warn, from, to),
             ...(history === "store" ? { namesFromStore: savedChatId ? { savedChatId } : {} } : {}),
         });
-    const passive = history === "store" && self !== null && !watching ? listened(saving, events, renderer.warn) : undefined;
+    const passives = history === "store" && self !== null && !watching
+        ? passivesOf(saving).map((passive) => listened(passive, events, renderer.warn))
+        : [];
     return {
         adapter: saving,
         close: async () => {
-            passive?.closing();
+            for (const passive of passives)
+                passive.closing();
             try {
                 await connection.close();
             }
             finally {
                 try {
-                    if (passive && !(await passive.stop())) {
-                        events({ event: "warning", code: "store_not_written", operation: "messages.listen" });
-                        renderer.warn("not saved to the local store: the messenger was still handing on messages at exit");
-                    }
+                    const ended = await Promise.all(passives.map((passive) => passive.stop()));
+                    passives.forEach(({ operation, what }, at) => {
+                        if (ended[at])
+                            return;
+                        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))) {
                         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");
@@ -252,7 +279,7 @@ const warnUnserved = async (messenger, profile, { env, renderer }, store) => {
     const newest = (await store.chats.chatStats(account))
         .map((one) => one.newestAt)
         .reduce((latest, at) => (at !== null && (latest === null || at > latest) ? at : latest), null);
-    renderer.warn(`no \`${messenger.app.command} serve\` keeps profile "${profile}" up to date — ` +
+    renderer.warn(`no \`${messenger.app.command} ${profile} serve\` keeps profile "${profile}" up to date — ` +
         (newest === null ? "the local store holds no messages yet" : `the newest stored message is from ${newest}`));
 };
 /** The words of a command below the program, `["messages", "list"]` — the profile word is not one of them. */

package/dist/cli/messenger/doctor-command.js

@@ -11,7 +11,7 @@ import { storePath } from "../../store/path.js";
 import { baseContext, environmentOf, outputFor } from "../context.js";
 import { destroysNothing, LOCAL_WRITE, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
-import { nextStep } from "../steps.js";
+import { lineOf, nextStep } from "../steps.js";
 import { recalledAccount } from "./accounts.js";
 import { messengerContext } from "./context.js";
 import { privateFiles, withSqliteSidecars } from "./private-files.js";
@@ -61,7 +61,7 @@ const reportCommand = (messenger) => {
         .description("what a problem report holds; writes nothing")
         .action(function () {
         const output = outputFor(this);
-        const create = `${app.command} doctor report create`;
+        const create = lineOf(this, "doctor report create");
         renderAnswer(this, output, itemOf({ includes: INCLUDES, excludes: EXCLUDES, ...(app.issues ? { send_to: app.issues } : {}) }, { next: [nextStep("doctor.report-create", { args: {} })] }), () => [
             `A problem report is one file for the author of ${app.command}.`,
             "",
@@ -71,7 +71,7 @@ const reportCommand = (messenger) => {
             `It never holds: ${EXCLUDES.join(", ")}.`,
             "",
             `Create one:          ${create}`,
-            `About a given run:   ${create} --run <id>   (ids: ${app.command} runs list)`,
+            `About a given run:   ${create} --run <id>   (ids: ${lineOf(this, "runs list")})`,
         ].join("\n"));
     });
     destroysNothing(annotate(report.command("create"), { effects: LOCAL_WRITE }))

package/dist/cli/messenger/flooded.js

@@ -5,7 +5,7 @@ import { providerErrorKey } from "../../runs/events.js";
 import { holdEnd } from "../../sends/flood.js";
 const LONG_LIVED = new Set(["self", "newSendId", "close", "formatMarkdown", "formatHtml"]);
 /** 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"]);
+const LISTENING = new Set(["watch", "feed", "listen", "listenHistory"]);
 const BLOCKING = new Set(["frozen", "limited", "banned"]);
 /** Shorter waits for the pace pass unannounced; a person at a terminal would not notice them. */
 const ANNOUNCE_WAIT_MS = 5_000;

package/dist/cli/messenger/mcp-command.js

@@ -216,7 +216,7 @@ const VERSION_MANAGER = /[\\/](\.nvm|nvm|\.fnm|fnm|fnm_multishells|\.volta|volta
 export const serverEntry = (app, { profile, flags = {}, execPath, scriptPath, env, }) => {
     if (installerOf(scriptPath) === "npx") {
         throw new CliError("validation_error", `this ${app.command} runs from npx's cache, which gets cleared, and the path would stop working — ` +
-            `install it globally, then run \`${app.command} mcp config\` again`);
+            `install it globally, then run \`${app.command} ${profile} mcp config\` again`);
     }
     const names = [
         ...["CONFIG_DIR", "STATE_DIR", "CACHE_DIR"].map((name) => envName(app, name)),

package/dist/cli/messenger/messages-delete-command.js

@@ -5,6 +5,7 @@ import { DELETE_AT_ONCE } from "../../services/index.js";
 import { environmentOf } from "../context.js";
 import { ownerOnlyOption, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { lineOf } from "../steps.js";
 import { messengerContext } from "./context.js";
 /**
  * The guard asks first at the default level, `ask`; `--allow-dangerous` is the yes. For everyone only
@@ -20,7 +21,7 @@ export const deleteCommand = (messenger) => annotate(new Command("delete"), { ef
     const everyone = this.opts().forEveryone === true;
     if (environmentOf(this).agent && (everyone || messenger.deleteForMe === false))
         throw new CliError("permission_error", `${everyone ? "" : `${messenger.name ?? messenger.provider} deletes only for everyone, and `}an agent never ` +
-            `deletes for everyone — the owner can run \`${messenger.app.command} messages delete --for-everyone\``, { permission: "messages.delete", sent: false });
+            `deletes for everyone — the owner can run \`${lineOf(this, "messages delete --for-everyone")}\``, { permission: "messages.delete", sent: false });
     const context = messengerContext(this, messenger);
     const deleted = await context.withServices((services) => services.messages.delete({
         chat,

package/dist/cli/messenger/observed.js

@@ -32,15 +32,15 @@ export const observed = (messenger, events) => {
             throw error;
         }
     };
-    const counted = async (operation, onEvent, work) => {
+    const counted = async (operation, onItem, work, count) => {
         const counts = {};
-        await timed(operation, {}, () => work((event) => {
-            counts[event.event] = (counts[event.event] ?? 0) + 1;
-            onEvent(event);
+        await timed(operation, {}, () => work((item) => {
+            count(item, counts);
+            onItem(item);
         }), () => ({ counts }));
     };
     const mint = messenger.newSendId;
-    const { chats, history, contact, around, watch, listen } = 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(),
@@ -84,15 +84,32 @@ export const observed = (messenger, events) => {
         }, () => messenger.send(chatId, text, options), (sent) => ({ ids: { message_id: sent.message.id } })),
         ...(watch
             ? {
-                watch: (onEvent, signal, onReady) => counted("messages.watch", onEvent, (counting) => watch.call(messenger, counting, signal, onReady)),
+                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)),
+                listen: (onEvent, signal) => counted("messages.listen", onEvent, (counting) => listen.call(messenger, counting, signal), byEvent),
+            }
+            : {}),
+        ...(listenHistory
+            ? {
+                listenHistory: (onBatch, signal) => counted("history.listen", onBatch, (counting) => listenHistory.call(messenger, counting, signal), byPart),
             }
             : {}),
         logout: () => timed("session.logout", {}, () => messenger.logout()),
         close: () => messenger.close(),
     }, (name, call) => (...args) => timed(`adapter.${name}`, {}, () => call(...args)));
 };
+const byEvent = (event, counts) => {
+    counts[event.event] = (counts[event.event] ?? 0) + 1;
+};
+const byPart = (batch, counts) => {
+    counts.batches = (counts.batches ?? 0) + 1;
+    for (const [part, items] of Object.entries(batch))
+        if (Array.isArray(items) && items.length > 0)
+            counts[part] = (counts[part] ?? 0) + items.length;
+};

package/dist/cli/messenger/schedule-command.js

@@ -13,6 +13,7 @@ import { storePath } from "../../store/path.js";
 import { environmentOf, setExitCode } from "../context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { lineOf } from "../steps.js";
 import { messengerContext } from "./context.js";
 /** Each run of an agent is a paid model call that reads chats; keeping the store current is `serve`'s job. */
 const AGENT_MINIMUM_MINUTES = 60;
@@ -84,7 +85,7 @@ export const scheduleCommand = (messenger) => {
             say(scheduleAnswer(schedule, { file, timer: timer().where(schedule.name), replaced }), [
                 `${replaced ? "Replaced" : "Added"} ${schedule.name}: ${describeWhen(schedule.when)}.`,
                 `It runs: ${schedule.kind === "agent" ? schedule.argv.join(" ") : `${app.command} ${schedule.argv.join(" ")}`}`,
-                `Output: ${join(dirname(file), "runs")} · now: ${app.command} schedule run ${schedule.name} · stop: ${app.command} schedule remove ${schedule.name}`,
+                `Output: ${join(dirname(file), "runs")} · now: ${lineOf(self, `schedule run ${schedule.name}`)} · stop: ${lineOf(self, `schedule remove ${schedule.name}`)}`,
             ]);
         };
         return { context, system, state, say, timer, environment, save };
@@ -172,7 +173,7 @@ export const scheduleCommand = (messenger) => {
         });
         renderAnswer(this, context, answer, () => {
             if (rows.length === 0) {
-                context.renderer.note(`no schedules — \`${app.command} schedule command|agent\` adds one`);
+                context.renderer.note(`no schedules — \`${lineOf(this, "schedule command|agent")}\` adds one`);
                 return "";
             }
             return rows
@@ -210,7 +211,7 @@ export const scheduleCommand = (messenger) => {
         const { state, say, timer } = prepare(this);
         const file = scheduleFile(state, scheduleName(name));
         if (!existsSync(file))
-            throw new CliError("not_found", `no schedule ${name} — \`${app.command} schedule list\``);
+            throw new CliError("not_found", `no schedule ${name} — \`${lineOf(this, "schedule list")}\``);
         await timer().remove(name);
         rmSync(file, { force: true });
         say({ name, removed: true }, [`Removed ${name}.`]);