@wirecat/cli-core 0.413.0 → 0.415.0

package/CHANGELOG.md

@@ -5,7 +5,33 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.415.0 — 25.10.2026
+
+### Added
+
+- **`movedCommandError(program, args)` from `/cli`** answers a renamed or moved command path with the pointer `run` gives ("`drive models text download` is not here — use `models download`"), for a CLI that parses without `run`. drive is the one today.
+- **The store records which CLIs open it, so an upgrade that locks some out names them** (available from cli-core 0.415.0). `openStore({ command, version })` saves each CLI's command, version, cli-core version and the newest store schema it speaks in `store_settings` (`clients`). A migration that raises the store's minimum prints one line to stderr naming each recorded CLI it locks out and the command to run (`memo upgrade`); a CLI refused by a newer store now says `run \`<its command> upgrade\`` and which CLI moved the store. The messenger context, the MCP server and `store migrate` pass the CLI's version already; other CLIs pass `version` to `openStore`.
+
+### Changed — may break callers
+
+- **cli-core needs cli-base 0.53.** The peer range is now `>=0.53.0 <0.54.0`, so a CLI moves its cli-base pin to 0.53.0 together with this release. cli-base 0.53.0 makes the command lint require a query declaration on every handwritten list (`WC-CMD-20`); its runtime API is unchanged.
+
+## 0.414.0 — 25.10.2026
+
+### Added
+
+- `AppIdentity.contentLanguages`: ISO 639-1 codes of the languages a CLI's content is in. On a new store the first run pre-ticks the ones search can stem in place of English and the system's language; the person still confirms the shared choice. Unset, nothing changes.
+- Export `publicUrlOf` and `portOf` through `/mcp`, so non-messenger consumers reuse the same HTTP listener option validation as the messenger commands.
+- **A contact saved with an address joins the mail contact of that exact address.** `savePeople` takes an optional
+  `email`; the provider's contact and the mail contact become one person (`same-email`), whichever is saved first.
+  A name never joins anyone, and two identities the owner unlinked stay apart.
+- **The first screen of `tg --help`, `max --help` and `wa --help` points at `account list`.** A row under "Start here" names `<tool> account list`, which lists every profile on this computer without a profile in front, so a reader who does not know their profile names finds them. A tool without `account list` shows no row.
+
+### Fixed
+
+- Generated MCP commands accept a positional argument or its same-named flag alternative once. A single `text` input no longer emits both the argument and `--text`, which made Memo note creation fail. Positional requiredness is retained.
+- Public listener origins refuse embedded credentials before startup diagnostics can expose them.
+- **"Returns" lists the fields of commands whose output has several shapes.** A command's help and the generated `docs/commands.md` showed `message send — ; every field: …` with no fields for every output declared as a union (`message_send`, `store_info`, `chat_group_change` and others; 41 lines in tg-cli's page). The line now lists the fields of every shape, required first, as for any other output.
 
 ## 0.413.0 — 25.10.2026
 

package/dist/cli/entry.js

@@ -61,6 +61,7 @@ export const startCli = async (entry) => {
         atStart: (command) => setupAtStart({
             command: entry.app.command,
             env: io.env,
+            contentLanguages: entry.app.contentLanguages,
             path: commandPathOf(command),
             headless: headless(command),
             readOnlyLock: readOnlyLockOf(entry.app, io.env),

package/dist/cli/first-run.d.ts

@@ -25,6 +25,8 @@ export interface FirstRun {
     command: string;
     env: NodeJS.ProcessEnv;
     io: FirstRunIo;
+    /** `AppIdentity.contentLanguages`: ticked on a new store in place of English and the system's language. */
+    contentLanguages?: readonly string[] | undefined;
     /** Every question, as `setup` asks them; otherwise only those no WireCat tool asked yet. */
     all?: boolean;
     /** Where tools are looked for and how one is installed; injected by tests. */
@@ -58,6 +60,7 @@ export declare const askSetupQuestions: (run: FirstRun) => Promise<Question[]>;
 export declare const setupAtStart: (start: {
     command: string;
     env: NodeJS.ProcessEnv;
+    contentLanguages?: readonly string[] | undefined;
     path: readonly string[];
     headless: boolean;
     readOnlyLock?: string | undefined;

package/dist/cli/first-run.js

@@ -85,17 +85,19 @@ const installerHere = () => {
         return "unknown";
     }
 };
-const askLanguages = async ({ command, env, io }) => {
+const suggested = (env, contentLanguages) => {
+    const own = LANGUAGES.filter(({ code }) => contentLanguages?.includes(code));
+    const system = systemLanguage(env);
+    return (own.length ? own : LANGUAGES.filter(({ code }) => code === "en" || code === system)).map(({ name }) => name);
+};
+const askLanguages = async ({ command, env, io, contentLanguages }) => {
     const store = await openStore({ env });
     let rebuild = false;
     try {
         const saved = (await store.searchIndex.stemmers()) ?? undefined;
         // A store already in use keeps the languages it was built with, so Enter changes nothing (RISK-1612).
         const inUse = saved !== undefined || (await store.accounts.accounts()).length > 0;
-        const system = systemLanguage(env);
-        const ticked = inUse
-            ? languagesOf(saved ?? DEFAULT_STEMMERS)
-            : LANGUAGES.filter(({ code }) => code === "en" || code === system).map(({ name }) => name);
+        const ticked = inUse ? languagesOf(saved ?? DEFAULT_STEMMERS) : suggested(env, contentLanguages);
         const numbers = ticked.map((name) => LANGUAGES.findIndex((one) => one.name === name) + 1);
         io.say("Languages you write and speak — search finds every form of their words, and spellings speech mangles:");
         LANGUAGES.forEach(({ name, label }, at) => {
@@ -213,6 +215,7 @@ export const setupAtStart = async (start) => {
     await askSetupQuestions({
         command: start.command,
         env: start.env,
+        contentLanguages: start.contentLanguages,
         all: start.path[0] === "setup",
         io: {
             ask: (prompt) => readSecret(prompt, { input, echo: true }),

package/dist/cli/help/command-help.js

@@ -100,16 +100,19 @@ const call = (command) => [
     ...commandPathOf(command),
     ...command.registeredArguments.map((one) => (one.required ? `<${one.name()}>` : `[${one.name()}]`)),
 ].join(" ");
+const fieldsOf = (schema) => {
+    const variants = schema.anyOf;
+    if (variants)
+        return variants.flatMap(fieldsOf);
+    const required = schema.required ?? [];
+    return [...required, ...Object.keys(schema.properties ?? {})];
+};
 const returnsOf = (command) => {
     const output = metaOf(command).output;
     const { item, coverage } = outputOf(command);
     if (!output || coverage !== "declared-entity")
         return short(command.summary() || command.description()) || "not declared";
-    const required = item.required ?? [];
-    const fields = [
-        ...required,
-        ...Object.keys(item.properties ?? {}).filter((name) => !required.includes(name)),
-    ];
+    const fields = [...new Set(fieldsOf(item))];
     const noun = (output.view ? `${output.entity} ${output.view}` : output.entity).replaceAll("_", " ");
     const more = fields.length > 8 ? `, and ${fields.length - 8} more` : "";
     const root = rootOf(command);

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

@@ -64,6 +64,9 @@ const pointers = (program, cli, start, profile) => {
     ].filter((row) => row !== undefined);
     const rows = [
         ...(start ? [["Start here:", start, profile ? "(any profile name works)" : ""]] : []),
+        ...(has("account list")
+            ? [["", `${cli} account list`, "your profiles and their logged-in accounts"]]
+            : []),
         ...next.map(([command = "", does = ""], at) => [at === 0 ? "Next:" : "", command, does]),
         ...(has("skill show") ? [["For agents:", `${cli} skill show`, "rules and the discovery loop"]] : []),
     ];

package/dist/cli/index.d.ts

@@ -96,6 +96,7 @@ export type { Running, ServerOptions, ServerProcess, ServerSystem } from "./mess
 export { storeSummary } from "./messenger/store-maintenance-command.js";
 export { type Saving, stored } from "./messenger/stored.js";
 export { MODEL_CATALOGUE_QUERY, type ModelCatalogueOptions } from "./model-catalogue-command.js";
+export { movedCommandError } from "./moved.js";
 export { window, withPaging } from "./paging.js";
 export { knownBeside, knownPermissionKeys, type PermissionKeyOf, unknownPermissionKeys } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, refuseCommandName, rootOf, usableProfileName } from "./profile.js";

package/dist/cli/index.js

@@ -87,6 +87,7 @@ export { STEMS_EVERY_MS, STEMS_SLICE_MS, stemFills } from "./messenger/serve-ste
 export { storeSummary } from "./messenger/store-maintenance-command.js";
 export { stored } from "./messenger/stored.js";
 export { MODEL_CATALOGUE_QUERY } from "./model-catalogue-command.js";
+export { movedCommandError } from "./moved.js";
 export { window, withPaging } from "./paging.js";
 export { knownBeside, knownPermissionKeys, unknownPermissionKeys } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, refuseCommandName, rootOf, usableProfileName } from "./profile.js";

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

@@ -47,7 +47,7 @@ export interface LazyStore {
     open: () => Promise<MessageStore>;
     close: () => Promise<void>;
 }
-export declare const lazyStore: (env: NodeJS.ProcessEnv, command: string) => LazyStore;
+export declare const lazyStore: (env: NodeJS.ProcessEnv, command: string, version?: string) => LazyStore;
 export declare const storedMessages: (provider: Provider, store: () => Promise<MessageStore>, account: () => Id | null | undefined) => StoredMessages;
 /** What one messenger CLI hands the shared commands. Everything else about it stays in its own code. */
 export interface Messenger extends ServiceMessenger {

package/dist/cli/messenger/context.js

@@ -17,11 +17,11 @@ import { flooded } from "./flooded.js";
 import { refuseLacking } from "./lacks.js";
 import { observed } from "./observed.js";
 import { stored } from "./stored.js";
-export const lazyStore = (env, command) => {
+export const lazyStore = (env, command, version) => {
     let opened;
     return {
         open: () => {
-            opened ??= openStore({ env, command });
+            opened ??= openStore({ env, command, ...(version ? { version } : {}) });
             return opened;
         },
         close: async () => {
@@ -195,7 +195,7 @@ const waitsOf = (command) => {
  * 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, unreadCounts, }, { settings, env, renderer }, events, store = lazyStore(env, app.command), { listen: watching = false, closeWaitMs = SAVES_WAIT_MS, rekeyPacing, } = {}) => {
+export const connected = (connection, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, unreadCounts, }, { settings, env, renderer }, events, store = lazyStore(env, app.command, app.version), { listen: watching = false, closeWaitMs = SAVES_WAIT_MS, rekeyPacing, } = {}) => {
     const self = connection.self();
     if (self !== null)
         rememberAccount(app, settings.profile, self, env);
@@ -268,7 +268,7 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
 };
 /** `connectFor` and then `connected`, over one store handle: what the reads save and what the adapter looks up. */
 export const connectedFor = async (command, messenger, base, options) => {
-    const store = lazyStore(base.env, messenger.app.command);
+    const store = lazyStore(base.env, messenger.app.command, messenger.app.version);
     let connection;
     try {
         connection = await connectFor(command, messenger, base, {
@@ -392,7 +392,7 @@ export const messengerContext = (command, messenger, resolving = {}) => {
         }, { unbounded: options.listen === true }),
         withStore: (work, { name } = {}) => base.run(async () => {
             const account = accountFor();
-            const store = await openStore({ env: base.env, command: app.command });
+            const store = await openStore({ env: base.env, command: app.command, version: app.version });
             try {
                 return await work(store, account);
             }
@@ -406,7 +406,7 @@ export const messengerContext = (command, messenger, resolving = {}) => {
             let warned;
             let released;
             const releaseConnection = () => (released ??= held?.close() ?? Promise.resolve());
-            const openOnce = () => (store ??= openStore({ env: base.env, command: app.command }));
+            const openOnce = () => (store ??= openStore({ env: base.env, command: app.command, version: app.version }));
             const deps = {
                 messenger,
                 profile,

package/dist/cli/messenger/store-maintenance-command.js

@@ -375,7 +375,7 @@ const migrateCommand = (messenger) => annotate(new Command("migrate"), { output:
     }
     const answer = await reading(path, (database) => {
         const from = schemaOf(database).version;
-        migrate(database, { command: messenger.app.command });
+        migrate(database, { command: messenger.app.command, version: messenger.app.version });
         const { normalized, indexed, terms } = buildWordIndex(database, (note) => renderer.note(note));
         const stemmed = buildStems(database, (note) => renderer.note(note));
         const notes = buildNoteIndex(database, (note) => renderer.note(note));

package/dist/cli/moved.d.ts

@@ -1,3 +1,5 @@
+import { CliError } from "@wirecat/cli-base";
+import type { Command } from "commander";
 /**
  * Commands a source tool no longer has, each with the memo command that does the job
  * (docs/dev/TOOL-BOUNDARIES.md). The CLI and the MCP server answer with the pointer instead of
@@ -12,3 +14,5 @@ export declare const RENAMED_COMMANDS: Readonly<Record<string, string>>;
 export declare const movedPointer: (path: string) => string | undefined;
 /** The longest moved path the words start with, unless the program still has it. */
 export declare const movedPath: (words: readonly string[], has: (path: string) => boolean) => string | undefined;
+/** The pointer for a moved or renamed path in `args`, for a CLI that parses without `run`. */
+export declare const movedCommandError: (program: Command, args: readonly string[]) => CliError | undefined;

package/dist/cli/moved.js

@@ -1,3 +1,5 @@
+import { CliError } from "@wirecat/cli-base";
+import { commandAt } from "./steps.js";
 /**
  * Commands a source tool no longer has, each with the memo command that does the job
  * (docs/dev/TOOL-BOUNDARIES.md). The CLI and the MCP server answer with the pointer instead of
@@ -54,3 +56,17 @@ export const movedPath = (words, has) => [...Object.keys(MOVED_TO_MEMO), ...Obje
     .filter((path) => path.split(" ").every((word, at) => words[at] === word))
     .sort((a, b) => b.length - a.length)
     .find((path) => !has(path));
+const mountedOrArgument = (program, path) => {
+    const words = path.split(" ");
+    return words.some((_, at) => {
+        const command = commandAt(program, words.slice(0, at + 1).join(" "));
+        return command !== undefined && (at === words.length - 1 || command.commands.length === 0);
+    });
+};
+/** The pointer for a moved or renamed path in `args`, for a CLI that parses without `run`. */
+export const movedCommandError = (program, args) => {
+    const moved = movedPath(args.filter((word) => !word.startsWith("-")), (path) => mountedOrArgument(program, path));
+    return moved === undefined
+        ? undefined
+        : new CliError("validation_error", `\`${program.name()} ${moved}\` is not here — ${movedPointer(moved)}`);
+};

package/dist/cli/program.js

@@ -25,7 +25,7 @@ import { installHelp } from "./help/first-screen.js";
 import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
-import { movedPath, movedPointer } from "./moved.js";
+import { movedCommandError } from "./moved.js";
 import { PreviewComplete, preview } from "./preview.js";
 import { commandWords, liftProfile, PROFILE_FREE, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
@@ -267,6 +267,7 @@ const runOnce = async (argv, definition, options) => {
         await setupAtStart({
             command,
             env: commandEnv,
+            contentLanguages: definition.app.contentLanguages,
             path,
             headless,
             readOnlyLock: lock,
@@ -420,10 +421,8 @@ const runOnce = async (argv, definition, options) => {
         const settled = await settleFailure(failure, { definition, program, rest, profile, options });
         return report(streams, reporting, failed(definition, program, rest, failure, settled, debug));
     }
-    const words = rest.filter((word) => !word.startsWith("-"));
-    const moved = movedPath(words, (path) => mountedOrArgument(program, path));
-    if (moved !== undefined) {
-        const failure = new CliError("validation_error", `\`${command} ${moved}\` is not here — ${movedPointer(moved)}`);
+    const failure = movedCommandError(program, rest);
+    if (failure !== undefined) {
         const settled = await settleFailure(failure, { definition, program, rest, profile, options });
         return report(streams, reporting, failed(definition, program, rest, failure, settled, debug));
     }
@@ -590,13 +589,6 @@ const keepFailure = async (failure, { definition, program, rest, profile, option
     }).catch(() => { });
 };
 /** Mounted, or reached through a command that takes no subcommand, where the rest of the path is its argument. */
-const mountedOrArgument = (program, path) => {
-    const words = path.split(" ");
-    return words.some((_, at) => {
-        const command = commandAt(program, words.slice(0, at + 1).join(" "));
-        return command !== undefined && (at === words.length - 1 || command.commands.length === 0);
-    });
-};
 /** `messages list` from `messages list 111 --limit 5`: the words that name commands, up to the first that does not. */
 const commandPath = (program, rest) => {
     const words = [];

package/dist/http/public-url.js

@@ -14,6 +14,8 @@ export const publicUrlOf = (given, { missing, reaches }) => {
     catch {
         throw new CliError("validation_error", `--public-url is not an address: ${EXAMPLE}`);
     }
+    if (url.username || url.password)
+        throw new CliError("validation_error", "--public-url must not contain login credentials");
     const local = url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname);
     if (url.protocol !== "https:" && !local)
         throw new CliError("validation_error", `--public-url must be https — ${reaches} through it`);

package/dist/mcp/agent.js

@@ -111,7 +111,10 @@ const fieldsOf = (info, { omit = [], offline = false, stdin }) => {
         const long = longOf(option);
         if (!long || option.mcp === false)
             continue;
-        fields.push(optionField(option, long, longs.has(`--no-${long.slice(2)}`)));
+        const field = optionField(option, long, longs.has(`--no-${long.slice(2)}`));
+        // A positional and its flag alternative share one MCP input; emitting both supplies the value twice.
+        if (!fields.some((existing) => existing.name === field.name))
+            fields.push(field);
     }
     if (offline && info.effects?.remote === "read" && info.offline !== false)
         fields.push(OFFLINE);

package/dist/mcp/index.d.ts

@@ -1,3 +1,4 @@
+export { portOf, publicUrlOf } from "../http/public-url.js";
 export { type AgentAnswer, type AgentContext, type AgentProgram, type AgentTool, type CatalogueOptions, type CommandAvailability, runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { type BotServerOptions, createBotServer, type RunBotCommand } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";

package/dist/mcp/index.js

@@ -1,4 +1,5 @@
 // Apart from the `cli` entry, so a CLI loads the MCP SDK and zod only when it serves MCP.
+export { portOf, publicUrlOf } from "../http/public-url.js";
 export { runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { createBotServer } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";

package/dist/mcp/server.js

@@ -176,7 +176,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         }),
     });
     const skill = messenger.skill ? skillResource(app, messenger.skill) : undefined;
-    const log = agentLog(() => openStore({ env: context.env, command: app.command }));
+    const log = agentLog(() => openStore({ env: context.env, command: app.command, version: app.version }));
     const audit = async (call) => {
         if (!recalledAccount(app, provider, settings.profile, context.env))
             return;

package/dist/ports/app.d.ts

@@ -14,6 +14,11 @@ export interface AppIdentity {
     issues?: string;
     /** The language of the transcript a person reads: its day headings and the word for "you". `ru-RU` when unset. */
     locale?: string;
+    /**
+     * ISO 639-1 codes of the languages its content is mostly in (`["ru"]`). The first run pre-ticks the ones search
+     * can stem in place of English and the system's language; the person still confirms, since the choice is shared.
+     */
+    contentLanguages?: readonly string[];
     /** Error reasons and detail keys of its own — max's `max_code`, tg's `migrated_chat_id` — kept in every error it prints. */
     errors?: AppErrors;
 }

package/dist/store/migrations.d.ts

@@ -24,9 +24,11 @@ export declare const MIGRATIONS: Migration[];
  * that fails names `store reset` when the app has one: without it the owner is stuck until a build that can migrate
  * the file. An app without that command (drive) passes no `command`, and the advice names none.
  */
-export declare const migrate: (database: CacheDatabase, { migrations, now, command, ownTable, }?: {
+export declare const migrate: (database: CacheDatabase, { migrations, now, command, version, ownTable, }?: {
     migrations?: Migration[];
     now?: () => number;
     command?: string;
+    /** The CLI's own version: with `command`, it is recorded so a later upgrade can name who it locks out. */
+    version?: string;
     ownTable?: string | null;
-}) => void;
+}) => string | undefined;

package/dist/store/migrations.js

@@ -1,4 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
+import { lockedOutNotice, recordClient, refusalAdvice, storeClients } from "./sqlite/clients.js";
 import { generatedMigrations } from "./sqlite/manifest.js";
 /**
  * Every migration is generated by drizzle-kit and numbered in `sqlite/manifest.ts`. Version 1 creates the whole
@@ -36,7 +37,7 @@ const fileState = (database) => {
  * that fails names `store reset` when the app has one: without it the owner is stuck until a build that can migrate
  * the file. An app without that command (drive) passes no `command`, and the advice names none.
  */
-export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, command, ownTable = OWN_TABLE, } = {}) => {
+export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, command, version, ownTable = OWN_TABLE, } = {}) => {
     const ours = latest(migrations);
     database.exec("BEGIN IMMEDIATE");
     try {
@@ -48,8 +49,18 @@ export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, com
         }
         if (file.version > ours && file.minCompatible > ours) {
             throw new CliError("configuration_error", `the message store was written by a newer version (schema ${file.version}, needs at least ` +
-                `${file.minCompatible}; this one speaks ${ours}) — upgrade this tool`);
+                `${file.minCompatible}; this one speaks ${ours}) — ${refusalAdvice(storeClients(database), command, file.version)}`);
         }
+        const raisedTo = migrations
+            .filter((migration) => migration.version > file.version)
+            .reduce((highest, { minCompatible }) => Math.max(highest, minCompatible), file.minCompatible);
+        const notice = file.version > 0 && raisedTo > file.minCompatible
+            ? lockedOutNotice(storeClients(database), {
+                ...(command ? { command } : {}),
+                schema: ours,
+                minCompatible: raisedTo,
+            })
+            : undefined;
         for (const migration of migrations) {
             if (migration.version <= file.version)
                 continue;
@@ -60,7 +71,10 @@ export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, com
                 .prepare("INSERT INTO schema_migrations (version, min_compatible, applied_at) VALUES (?, ?, ?)")
                 .run(migration.version, migration.minCompatible, now());
         }
+        if (command && version)
+            recordClient(database, { command, version, speaks: ours }, now());
         database.exec("COMMIT");
+        return notice;
     }
     catch (error) {
         database.exec("ROLLBACK");

package/dist/store/people.js

@@ -12,8 +12,11 @@ export const accountPeopleOver = (context) => {
     return {
         savePeople: async (key, people) => write(database, () => {
             const accountKey = accountPk(key);
-            for (const person of people)
+            for (const person of people) {
                 identityPk(accountKey, key.provider, person.id, person.name, person);
+                if (person.email)
+                    personLinks.joinByAddress(context, { provider: key.provider, id: person.id }, person.email, key.provider);
+            }
         }),
         contacts: async (key, options) => {
             const accountKey = findAccountPk(key);

package/dist/store/sqlite/clients.d.ts

@@ -0,0 +1,26 @@
+import type { CacheDatabase } from "../driver.js";
+export declare const CLIENTS_SETTING = "clients";
+/** A CLI that opened the store for writing: what it is and the newest store schema it speaks. */
+export interface StoreClient {
+    command: string;
+    version: string;
+    core: string;
+    speaks: number;
+    seenAt: number;
+}
+/** Readable from any schema: `store_settings` is in the initial migration. */
+export declare const storeClients: (database: CacheDatabase) => StoreClient[];
+/** Writes only when the CLI's version, cli-core or schema changed, or a day passed: every run calls it. */
+export declare const recordClient: (database: CacheDatabase, { command, version, speaks }: {
+    command: string;
+    version: string;
+    speaks: number;
+}, now: number) => void;
+/** The sentence an upgrade that raised the store's minimum prints: who can no longer open it, and what to run. */
+export declare const lockedOutNotice: (clients: readonly StoreClient[], { command, schema, minCompatible }: {
+    command?: string;
+    schema: number;
+    minCompatible: number;
+}) => string | undefined;
+/** Added to a refusal: this tool's own command, and the CLI that moved the store, so the owner knows what to run. */
+export declare const refusalAdvice: (clients: readonly StoreClient[], command: string | undefined, schema: number) => string;

package/dist/store/sqlite/clients.js

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+export const CLIENTS_SETTING = "clients";
+const coreVersion = (() => {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8"));
+        return typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
+const clientOf = (value) => {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const { command, version, core, speaks, seenAt } = value;
+    return typeof command === "string" &&
+        typeof version === "string" &&
+        typeof core === "string" &&
+        Number.isSafeInteger(speaks) &&
+        Number.isSafeInteger(seenAt)
+        ? { command, version, core, speaks: speaks, seenAt: seenAt }
+        : undefined;
+};
+// A store built from a test's own migrations may have no settings table.
+const hasSettings = (database) => database.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'store_settings'").get() !== undefined;
+/** Readable from any schema: `store_settings` is in the initial migration. */
+export const storeClients = (database) => {
+    if (!hasSettings(database))
+        return [];
+    const row = database.prepare("SELECT value FROM store_settings WHERE key = ?").get(CLIENTS_SETTING);
+    if (!row)
+        return [];
+    try {
+        const value = JSON.parse(String(row.value));
+        return Array.isArray(value) ? value.flatMap((one) => clientOf(one) ?? []) : [];
+    }
+    catch {
+        return [];
+    }
+};
+/** Writes only when the CLI's version, cli-core or schema changed, or a day passed: every run calls it. */
+export const recordClient = (database, { command, version, speaks }, now) => {
+    if (!hasSettings(database))
+        return;
+    const stored = storeClients(database);
+    const same = stored.find((one) => one.command === command);
+    if (same &&
+        same.version === version &&
+        same.core === coreVersion &&
+        same.speaks === speaks &&
+        now - same.seenAt < 86_400_000)
+        return;
+    const entry = { command, version, core: coreVersion, speaks, seenAt: now };
+    database
+        .prepare("INSERT OR REPLACE INTO store_settings (key, value, at) VALUES (?, ?, ?)")
+        .run(CLIENTS_SETTING, JSON.stringify([...stored.filter((one) => one.command !== command), entry]), now);
+};
+const upgradeOf = (clients) => clients.map(({ command }) => `\`${command} upgrade\``).join(", ");
+/** The sentence an upgrade that raised the store's minimum prints: who can no longer open it, and what to run. */
+export const lockedOutNotice = (clients, { command, schema, minCompatible }) => {
+    const others = clients.filter((one) => one.command !== command);
+    const behind = others.filter(({ speaks }) => speaks < minCompatible);
+    const named = behind.map(({ command, version }) => `${command} ${version}`).join(", ");
+    if (behind.length)
+        return `the store moved to schema ${schema}; ${named} can no longer open it until upgraded — run ${upgradeOf(behind)}`;
+    // A CLI that has not opened the store since clients were recorded is unknown here, but may still be behind.
+    if (!others.length)
+        return (`the store moved to schema ${schema}; every other WireCat CLI that uses it needs a version that speaks it — ` +
+            "run `<cli> upgrade` for each");
+    return undefined;
+};
+/** Added to a refusal: this tool's own command, and the CLI that moved the store, so the owner knows what to run. */
+export const refusalAdvice = (clients, command, schema) => {
+    const mover = clients
+        .filter(({ speaks, command: other }) => speaks >= schema && other !== command)
+        .sort((a, b) => b.seenAt - a.seenAt)[0];
+    const own = command ? `run \`${command} upgrade\`` : "upgrade this tool";
+    return mover ? `${own} (${mover.command} ${mover.version} moved the store to schema ${schema})` : own;
+};

package/dist/store/sqlite/open-store.d.ts

@@ -7,6 +7,10 @@ export interface StoreOptions {
     now?: () => number;
     /** The CLI's own name, for the advice a failed migration gives. */
     command?: string;
+    /** The CLI's own version: with `command`, recorded in the store so an upgrade can name the CLIs it locks out. */
+    version?: string;
+    /** Where the notice of an upgrade that locks other CLIs out goes; stderr, since stdout may carry JSON or MCP. */
+    warn?: (line: string) => void;
 }
 export declare const BACKFILL_ON_OPEN = 5000;
-export declare const openStoreContext: ({ path, env, now, command, readOnly, }?: StoreOptions) => Promise<StoreContext>;
+export declare const openStoreContext: ({ path, env, now, command, version, warn, readOnly, }?: StoreOptions) => Promise<StoreContext>;

package/dist/store/sqlite/open-store.js

@@ -28,7 +28,7 @@ const createWritable = (file) => {
         throw new CliError("permission_error", "the message store cannot be written from here; run where it is writable, or set MESSAGING_STORE", { reason: "store.not-writable" });
     }
 };
-export const openStoreContext = async ({ path, env, now = Date.now, command, readOnly = false, } = {}) => {
+export const openStoreContext = async ({ path, env, now = Date.now, command, version, warn = (line) => process.stderr.write(`${line}\n`), readOnly = false, } = {}) => {
     if (typeof readOnly !== "boolean")
         throw new CliError("validation_error", "readOnly must be a boolean");
     await storeCapable();
@@ -43,9 +43,11 @@ export const openStoreContext = async ({ path, env, now = Date.now, command, rea
     const database = opened.database;
     try {
         if (readOnly)
-            assertReadCompatible(database);
+            assertReadCompatible(database, command);
         else {
-            migrate(database, { now, command });
+            const notice = migrate(database, { now, command, ...(version ? { version } : {}) });
+            if (notice)
+                warn(notice);
             fillFolded(database);
             const pending = pendingNormalization(database);
             if (pending > 0 && pending <= BACKFILL_ON_OPEN)

package/dist/store/sqlite/person-links.d.ts

@@ -14,6 +14,12 @@ export declare const linkIdentityToPerson: (context: StoreContext, identityPk: n
 export declare const linkIdentities: (context: StoreContext, person: IdentityRef, other: IdentityRef, options: LinkOptions) => PersonRecord;
 /** Moves every identity of `from` to `to`, as `linkIdentities` does once it has found both people. */
 export declare const mergePerson: (context: StoreContext, from: number, to: number, options: LinkOptions) => void;
+/**
+ * Joins the identity to the person of the mail contact with this exact address, making that contact when mail has
+ * not seen it yet, so whichever import comes second lands on one person. The contact is seen by no account, so it is
+ * no one's mail correspondent. An owner's unlink wins: two identities the owner separated stay apart.
+ */
+export declare const joinByAddress: (context: StoreContext, ref: IdentityRef, address: string, by: string) => void;
 /** Gives the identity a person of its own again; the ones left keep theirs. */
 export declare const unlinkIdentity: (context: StoreContext, ref: IdentityRef, options: LinkOptions) => PersonRecord;
 /** Messages that name the person: by id where the messenger said so, or by `@username` in the text. */

package/dist/store/sqlite/person-links.js

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { and, eq, inArray, isNull, sql } from "./drizzle/core.js";
+import { identityOf } from "./identities.js";
 import { resolvePersonLinks } from "./person-resolution.js";
 import { accountIdentities, accounts, chats, identities, identityLinkEvents, identityLinks, messages, persons, } from "./schema.js";
 import { hitsWhere } from "./search.js";
@@ -135,6 +136,32 @@ export const mergePerson = (context, from, to, options) => {
     for (const { identityPk } of together)
         move(context, identityPk, from, to, options);
 };
+/** The owner once moved one of the two identities away from a person the other belonged to. */
+const separatedByOwner = ({ database }, one, other) => database
+    .prepare(`SELECT 1 FROM identity_link_events moved
+       JOIN identity_link_events held ON held.to_person_id = moved.from_person_id
+       WHERE moved.author = 'owner' AND ((moved.identity_id = ? AND held.identity_id = ?)
+         OR (moved.identity_id = ? AND held.identity_id = ?))
+       LIMIT 1`)
+    .get(one, other, other, one) !== undefined;
+/**
+ * Joins the identity to the person of the mail contact with this exact address, making that contact when mail has
+ * not seen it yet, so whichever import comes second lands on one person. The contact is seen by no account, so it is
+ * no one's mail correspondent. An owner's unlink wins: two identities the owner separated stay apart.
+ */
+export const joinByAddress = (context, ref, address, by) => {
+    const key = address.trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+$/.test(key) || ref.provider === "email")
+        return;
+    const found = required(context, ref);
+    if (!identityRow(context, { provider: "email", id: key }))
+        identityOf(context, "email", key, null);
+    const contact = required(context, { provider: "email", id: key });
+    if (contact.personPk === found.personPk || separatedByOwner(context, found.pk, contact.pk))
+        return;
+    mergePerson(context, found.personPk, contact.personPk, { method: "same-email", by });
+    resolvePersonLinks(context.database, recordOf(context, contact.personPk).identities.flatMap(({ name, username }) => [name, username]));
+};
 /** Gives the identity a person of its own again; the ones left keep theirs. */
 export const unlinkIdentity = (context, ref, options) => {
     const found = required(context, ref);

package/dist/store/sqlite/read-compatibility.d.ts

@@ -1,2 +1,2 @@
 import type { CacheDatabase } from "../driver.js";
-export declare const assertReadCompatible: (database: CacheDatabase) => void;
+export declare const assertReadCompatible: (database: CacheDatabase, command?: string) => void;

package/dist/store/sqlite/read-compatibility.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { MIGRATIONS } from "../migrations.js";
-export const assertReadCompatible = (database) => {
+import { refusalAdvice, storeClients } from "./clients.js";
+export const assertReadCompatible = (database, command) => {
     const ours = MIGRATIONS.at(-1)?.version ?? 0;
     if (!database.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_migrations'").get())
         throw new CliError("configuration_error", "The store has no schema history; initialize it explicitly before a read-only open");
@@ -17,5 +18,5 @@ export const assertReadCompatible = (database) => {
     if (version < ours)
         throw new CliError("configuration_error", `The store needs schema ${ours} maintenance before a read-only open (found ${version})`);
     if (minCompatible > ours)
-        throw new CliError("configuration_error", `The store requires schema ${minCompatible}, but this tool supports ${ours}; upgrade this tool`);
+        throw new CliError("configuration_error", `The store requires schema ${minCompatible}, but this tool supports ${ours}; ${refusalAdvice(storeClients(database), command, version)}`);
 };

package/dist/store/types.d.ts

@@ -32,6 +32,8 @@ export interface PersonFacts {
     username?: string | null;
     isBot?: boolean | null;
     description?: string | null;
+    /** An address the provider shows for them: they become one person with the mail contact of that exact address. */
+    email?: string | null;
 }
 /** One identity in one messenger, by the messenger's own id. `provider` is any string: `email` is one. */
 export interface IdentityRef {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.413.0",
+  "version": "0.415.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",
@@ -213,7 +213,7 @@
     "@types/node": "^22.20.4",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.2",
-    "@wirecat/cli-base": "0.51.0",
+    "@wirecat/cli-base": "0.53.0",
     "commander": "15.0.0",
     "cspell": "10.3.6",
     "drizzle-kit": "1.0.0-rc.4",
@@ -233,7 +233,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.51.0 <0.52.0",
+    "@wirecat/cli-base": ">=0.53.0 <0.54.0",
     "commander": ">=15"
   },
   "bin": {