@wirecat/cli-core 0.461.0 → 0.463.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ shape of this file.
 
 ## Unreleased
 
+## 0.463.0 — 27.10.2026
+
+### Changed — may break callers
+
+- **The MCP server is `mcp serve`; `mcp` alone only shows its commands**
+  ([WC-CMD-3](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-3--give-a-group-without-a-leaf-only-its-help-never-a-hidden-default-action)).
+  `mcpCommand` gives the `mcp` group with `serve`, `revoke`, `config`, `add`, `check` and `server`; `--http`, `--port`,
+  `--public-url` and `--permission` move from `mcp` to `mcp serve`, and `mcp --revoke` is now its own command,
+  `mcp revoke`, with no flag left behind. An agent is set up with
+  `claude mcp add <cli> -- <cli> <profile> mcp serve`. `bot mcp` is a group too, and the bot's server is
+  `bot mcp serve`. `serverEntry`, so `mcp config`, `mcp add`, `mcp check` and `bot mcp config`, writes `mcp serve`,
+  the server of every profile starts `<cli> <profile> mcp serve` for each, and `mcp server start` runs
+  `mcp serve --http`. There is no alias: an old client entry that runs `<cli> <profile> mcp` gets the group's help and
+  exits 2 — print it again with `mcp config` or `mcp add`.
+- **`mcpServerCommand` takes `--permission` only when asked.** `mcp server start` offered `--permission` to
+  every CLI and passed it to a server that might not take it; that server died before it listened and `start`
+  answered `provider_unavailable` with `retry.safe: true`, so an agent retried for ever. A CLI whose `mcp serve` takes
+  `--permission` passes `permission: true` (`mcpCommand` does); otherwise `start --permission` is refused as an unknown
+  option before anything starts. A `--permission` set on the CLI's root is still handed over. A server that stops
+  before it listens is now `retry.safe: false`. A CLI's own target names its server as `argv: [..., "mcp", "serve",
+  "--http"]` once its `mcp` is a group too.
+
+## 0.462.0 — 27.10.2026
+
+### Changed — may break callers
+
+- **`skill show`, `skill status` and `skill install` answer `--json` in the one-thing envelope**
+  ([WC-OUT-4](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/output.md#wc-out-4--answer-every-json-request-with-one-envelope-a-list-or-one-thing)),
+  `{ item, meta }`, and `--jsonl` as one item line and the end line, like every other command and as their declared
+  output schema already said; they printed the bare object. MCP tool answers change the same way. `commands --json`
+  does not change. A caller reads the old fields under `item`: the `install/windows.ps1` installers of tg-cli, max-cli
+  and whatsapp-cli read `$skill.written`, and tests in tg-cli (`src/archive.test.ts`), max-cli
+  (`src/commands/skill.test.ts`) and cli-template (`src/roots.test.ts`) read the bare shape.
+
+### Fixed
+
+- **An empty `messages` search no longer suggests `messages sync --all --background`.** `coverage.next` and the
+  `messages.sync` step now name one chat (`<cli> messages sync <chat>`: the selected chat, or the most active one
+  that was never fetched or is behind), and the search help says to offer it and run it only after the owner
+  approves. A sync downloads from the owner's account, so an agent must not start an unbounded one on its own.
+
 ## 0.461.0 — 27.10.2026
 
 ### Changed — may break callers

package/dist/cli/bot/mcp.js

@@ -12,8 +12,16 @@ import { botExamples } from "./examples.js";
 /** `bot mcp`, mounted only for a messenger that hands in its `run` on `BotMessenger.mcp`. */
 export const botMcpCommand = (bot) => {
     const { app } = bot;
-    const command = annotate(new Command("mcp"), { effects: REMOTE_WRITE, lifetime: "persistent", mcp: false })
-        .description(`serve this bot to an agent over MCP, on stdin and stdout — \`claude mcp add sales-bot -- ${app.command} sales bot mcp\``)
+    const command = annotate(new Command("mcp"), { effects: LOCAL_READ, mcp: false })
+        .description(`serve this bot to an agent over MCP and set it up — \`claude mcp add sales-bot -- ${app.command} sales bot mcp serve\``)
+        .summary("serve this bot to an agent over MCP, and set that up");
+    command.addCommand(annotate(new Command("serve"), {
+        effects: REMOTE_WRITE,
+        lifetime: "persistent",
+        mcp: false,
+        examples: botExamples(bot, "mcp serve"),
+    })
+        .description(`serve this bot to an agent over MCP, on stdin and stdout — \`claude mcp add sales-bot -- ${app.command} sales bot mcp serve\``)
         .summary("serve this bot to an agent over MCP, on stdin and stdout")
         .action(async function () {
         const context = botContext(this, bot);
@@ -35,7 +43,7 @@ export const botMcpCommand = (bot) => {
             ...(mcp.keyOf ? { keyOf: mcp.keyOf } : {}),
             ...(mcp.skill ? { skill: mcp.skill } : {}),
         }, context.streams.diagnostic);
-    });
+    }));
     command.addCommand(annotate(new Command("config"), { effects: LOCAL_READ, examples: botExamples(bot, "mcp config") })
         .description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")
         .summary("print the mcpServers entry for an MCP client; writes nothing")

package/dist/cli/guide.js

@@ -291,7 +291,7 @@ export const checkStep = (program, run) => {
     const beforeDashes = rest.slice(index, rest.includes("--") ? rest.indexOf("--") : undefined);
     if (help && beforeDashes.some((word) => word === help.long || word === help.short))
         return [];
-    // A group with an action of its own runs as typed: `mcp` serves, `mcp server start` is its child.
+    // A group with an action of its own runs as typed rather than asking for one of its children.
     const runsItself = at._actionHandler != null;
     if (at.commands.length > 0 && !runsItself)
         return [`needs one of: ${at.commands.map((one) => one.name()).join(", ")}`];

package/dist/cli/mcp-server-command.d.ts

@@ -10,7 +10,7 @@ export interface McpServerTarget {
     envPrefix: string;
     env: NodeJS.ProcessEnv;
     tokenFile: string;
-    /** The words after the CLI's own entry that run `mcp --http` in the foreground, before `--port`. */
+    /** The words after the CLI's own entry that run `mcp serve --http` in the foreground, before `--port`. */
     argv: string[];
     /** Added to the server's environment: the profile, for a CLI that reads it from there. */
     childEnv?: Record<string, string>;
@@ -19,17 +19,22 @@ export interface McpServerTarget {
 export interface McpServerOptions {
     /** How help shows the CLI before `mcp`: `tg personal`. */
     example: string;
-    /** The CLI's own `mcp --http` default, when it is not 8765. */
+    /** The CLI's own `mcp serve --http` default, when it is not 8765. */
     defaultPort?: number;
+    /**
+     * `start` takes `--permission` and hands it to the server: only for a CLI whose `mcp serve` takes it too,
+     * since a server that refuses the option dies before it listens.
+     */
+    permission?: boolean;
     target: (self: Command) => McpServerTarget;
     /** The CLI's own answer: the item in `--json`, else the lines. */
     answer: (self: Command, item: object, lines: string[]) => void;
     system?: (self: Command) => ServerSystem | undefined;
 }
 /**
- * `mcp --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
+ * `mcp serve --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
  * keeps a lock beside its token file (`state.ts`) with its port, address and login code, so status
  * survives the shell that started it, and `stop` ends only a process that carries this CLI's marker.
  * None of it is offered over MCP: status holds a live login code.
  */
-export declare const mcpServerCommand: ({ example, defaultPort, target, answer, system, }: McpServerOptions) => Command;
+export declare const mcpServerCommand: ({ example, defaultPort, permission, target, answer, system, }: McpServerOptions) => Command;

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

@@ -40,28 +40,29 @@ const clientLines = (clients) => clients.length === 0
             .join(", ")}.`,
     ];
 /**
- * `mcp --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
+ * `mcp serve --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
  * keeps a lock beside its token file (`state.ts`) with its port, address and login code, so status
  * survives the shell that started it, and `stop` ends only a process that carries this CLI's marker.
  * None of it is offered over MCP: status holds a live login code.
  */
-export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT, target, answer, system, }) => {
+export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT, permission = false, target, answer, system, }) => {
     const command = annotate(new Command("server"), { effects: LOCAL_READ, mcp: false })
         .summary("run the HTTP MCP server in the background")
-        .description("start, stop and check `mcp --http` in the background; status shows the login code for a browser app");
+        .description("start, stop and check `mcp serve --http` in the background; status shows the login code for a browser app");
     const machine = (self) => system?.(self) ?? thisMachine();
-    destroysNothing(annotate(command.command("start"), {
+    const start = destroysNothing(annotate(command.command("start"), {
         effects: LOCAL_WRITE,
         mcp: false,
         examples: [`${example} mcp server start --public-url https://laptop.example.ts.net`],
     }))
         .summary("start the HTTP MCP server in the background")
-        .description("start `mcp --http` apart from this shell and answer once it listens, with its login code")
+        .description("start `mcp serve --http` apart from this shell and answer once it listens, with its login code")
         .option("--port <port>", `the local port (default ${defaultPort})`)
-        .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net or https://<name>.ts.net/tg")
-        .option("--permission <key=level>", "make a permission stricter for this server only; repeat for more keys", (value, previous = []) => [...previous, value])
-        .action(async function () {
-        // A CLI whose `mcp` takes the same flags reads them first, so they are looked up on both.
+        .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net or https://<name>.ts.net/tg");
+    if (permission)
+        start.option("--permission <key=level>", "make a permission stricter for this server only; repeat for more keys", (value, previous = []) => [...previous, value]);
+    start.action(async function () {
+        // A CLI with a root-wide `--permission` hands it over too, so the server is never looser than asked.
         const flags = this.optsWithGlobals();
         const one = target(this);
         const url = publicUrlOf(flags.publicUrl, {
@@ -102,15 +103,15 @@ export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT,
             }
             if (!alive(pid)) {
                 const last = readableLog(tail(log, 5)).trim();
-                throw new CliError("provider_unavailable", `mcp --http stopped before it listened${last ? `:\n${last}` : ""}`);
+                throw new CliError("provider_unavailable", `mcp serve --http stopped before it listened${last ? `:\n${last}` : ""}`, { retryable: false });
             }
             await sys.pause();
         }
-        throw new CliError("timeout", `mcp --http is running but not listening yet — \`${one.invocation} mcp server status\`; its log: ${log}`);
+        throw new CliError("timeout", `mcp serve --http is running but not listening yet — \`${one.invocation} mcp server status\`; its log: ${log}`);
     });
     destroysNothing(annotate(command.command("stop"), { effects: LOCAL_WRITE, mcp: false, examples: [`${example} mcp server stop`] }))
         .summary("stop the background HTTP MCP server")
-        .description("stop `mcp --http` — only one that `mcp server start` started")
+        .description("stop `mcp serve --http` — only one that `mcp server start` started")
         .action(async function () {
         const one = target(this);
         const lock = readHttpLock(httpLockFile(one.tokenFile));
@@ -121,14 +122,14 @@ export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT,
             return;
         }
         if (byOf(one, lock.pid) !== "server") {
-            throw new CliError("validation_error", `mcp --http for ${one.invocation} (PID ${lock.pid}) was not started by \`${one.invocation} mcp server start\` — stop it where it runs`);
+            throw new CliError("validation_error", `mcp serve --http for ${one.invocation} (PID ${lock.pid}) was not started by \`${one.invocation} mcp server start\` — stop it where it runs`);
         }
         process.kill(lock.pid, "SIGTERM");
         const sys = machine(this);
         for (let look = 0; look < LOOKS && alive(lock.pid); look++)
             await sys.pause();
         if (alive(lock.pid))
-            throw new CliError("timeout", `mcp --http (PID ${lock.pid}) has not stopped yet`);
+            throw new CliError("timeout", `mcp serve --http (PID ${lock.pid}) has not stopped yet`);
         answer(this, { profile: one.profile ?? null, stopped: true, pid: lock.pid }, [
             `Stopped serving ${one.invocation} over HTTP (PID ${lock.pid}).`,
         ]);
@@ -139,7 +140,7 @@ export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT,
         examples: [`${example} mcp server status --json`],
     })
         .summary("whether the HTTP MCP server runs, its login code and the apps logged in")
-        .description("whether `mcp --http` runs, on which port and address, the login code for a new browser app, and the apps logged in")
+        .description("whether `mcp serve --http` runs, on which port and address, the login code for a new browser app, and the apps logged in")
         .action(function () {
         const one = target(this);
         const lock = readHttpLock(httpLockFile(one.tokenFile));

package/dist/cli/messenger/mcp-command.d.ts

@@ -17,11 +17,10 @@ export interface McpFlags {
     http?: boolean;
     port?: string;
     publicUrl?: string;
-    revoke?: boolean;
 }
-/** The token file of `<tool> mcp --http` for every profile: no profile name can start with `_`. */
+/** The token file of `<tool> mcp serve --http` for every profile: no profile name can start with `_`. */
 export declare const ALL_PROFILES = "_all";
-/** Where `mcp --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
+/** Where `mcp serve --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
 export declare const httpTokenFile: (app: AppIdentity, profile: string, env: NodeJS.ProcessEnv) => string;
 export declare const mcpCommand: (messenger: Messenger) => Command;
 /**
@@ -44,7 +43,7 @@ export declare const redactTail: (text: string, home: string | undefined) => str
  * servers with a trimmed environment leaves it out (measured 2026-09-28). Credentials are never copied.
  */
 export declare const serverEntry: (app: AppIdentity, { profile, flags, execPath, scriptPath, env, }: {
-    /** Left out, the entry is `<tool> mcp`, the server of every profile. */
+    /** Left out, the entry is `<tool> mcp serve`, the server of every profile. */
     profile?: string;
     flags?: McpFlags;
     execPath: string;

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

@@ -19,31 +19,36 @@ import { nextStep } from "../steps.js";
 import { recalledAccount } from "./accounts.js";
 import { messengerContext } from "./context.js";
 const DEFAULT_PORT = MCP_HTTP_DEFAULT_PORT;
-/** The token file of `<tool> mcp --http` for every profile: no profile name can start with `_`. */
+/** The token file of `<tool> mcp serve --http` for every profile: no profile name can start with `_`. */
 export const ALL_PROFILES = "_all";
-/** Where `mcp --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
+/** Where `mcp serve --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
 export const httpTokenFile = (app, profile, env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "mcp-http", `${profile}.json`);
 const withFlags = (command) => command.option("--permission <key=level>", "make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys", (value, previous = []) => [...previous, value]);
 export const mcpCommand = (messenger) => {
     const { app } = messenger;
-    const command = withFlags(annotate(new Command("mcp"), { effects: REMOTE_WRITE, lifetime: "persistent", mcp: false })
+    const command = annotate(new Command("mcp"), { effects: LOCAL_READ, mcp: false })
+        .summary("serve this profile's commands to an AI agent, and set that up")
+        .description(`serve this profile to an agent over MCP and set it up — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp serve\``);
+    command.addCommand(withFlags(annotate(new Command("serve"), {
+        effects: REMOTE_WRITE,
+        lifetime: "persistent",
+        mcp: false,
+        examples: [
+            `${app.command} personal mcp serve`,
+            `${app.command} personal mcp serve --http --public-url https://laptop.example.ts.net`,
+        ],
+    })
         .summary("serve this profile's commands to an AI agent")
-        .description(`serve this profile to an agent over MCP, on stdin and stdout — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp\`; with no profile, \`${app.command} mcp\` serves every profile and each tool asks which`))
+        .description(`serve this profile to an agent over MCP, on stdin and stdout — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp serve\`; with no profile, \`${app.command} mcp serve\` serves every profile and each tool asks which`))
         .option("--http", "serve over HTTP on 127.0.0.1 for ChatGPT and Claude in the browser, behind your tunnel; the profile's permissions decide")
         .option("--port <port>", `the local port for --http (default ${DEFAULT_PORT})`)
         .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net or https://<name>.ts.net/tg")
-        .option("--revoke", "forget every login given to a browser app; each must log in again");
-    command.action(async function () {
+        .action(async function () {
         const flags = this.optsWithGlobals();
         const context = messengerContext(this, messenger, { needsProfile: false });
-        if (namedProfile(context.settings) === undefined)
+        const profile = namedProfile(context.settings);
+        if (profile === undefined)
             return serveEveryProfile(this, context, messenger, flags);
-        if (flags.revoke) {
-            const { revokeAll } = await import("../../mcp/http/oauth.js");
-            revokeAll(httpTokenFile(app, context.settings.profile, context.env));
-            renderAnswer(this, context, itemOf({ revoked: true, profile: context.settings.profile }));
-            return;
-        }
         if (flags.http) {
             const publicUrl = publicUrlOf(flags.publicUrl, {
                 missing: "--http",
@@ -51,7 +56,7 @@ export const mcpCommand = (messenger) => {
                 path: true,
             });
             const { serveOverHttpUntilStopped } = await import("../../mcp/server.js");
-            const tokenFile = httpTokenFile(app, context.settings.profile, context.env);
+            const tokenFile = httpTokenFile(app, profile, context.env);
             await serveOverHttpUntilStopped(this, context, messenger, {}, {
                 publicUrl,
                 port: portOf(flags.port, DEFAULT_PORT),
@@ -64,9 +69,24 @@ export const mcpCommand = (messenger) => {
         // Loaded here, not at the top: every other command would otherwise pay for the SDK.
         const { serveOverStdio } = await import("../../mcp/server.js");
         await serveOverStdio(this, context, messenger, {});
-    });
+    }));
+    command.addCommand(annotate(new Command("revoke"), {
+        effects: LOCAL_WRITE,
+        mcp: false,
+        examples: [`${app.command} personal mcp revoke`],
+    })
+        .summary("forget every login given to a browser app")
+        .description(`forget every login \`mcp serve --http\` gave a browser app, of this profile or, with no profile, of the server of every profile; each app must log in again`)
+        .action(async function () {
+        const context = messengerContext(this, messenger, { needsProfile: false });
+        const profile = namedProfile(context.settings);
+        const { revokeAll } = await import("../../mcp/http/oauth.js");
+        revokeAll(httpTokenFile(app, profile ?? ALL_PROFILES, context.env));
+        renderAnswer(this, context, itemOf({ revoked: true, profile: profile ?? null }));
+    }));
     command.addCommand(mcpServerCommand({
         example: `${app.command} personal`,
+        permission: true,
         target: (self) => {
             const { settings, env } = messengerContext(self, messenger, { needsProfile: false });
             if (namedProfile(settings) === undefined)
@@ -75,7 +95,7 @@ export const mcpCommand = (messenger) => {
                     envPrefix: app.envPrefix,
                     env,
                     tokenFile: httpTokenFile(app, ALL_PROFILES, env),
-                    argv: ["mcp", "--http"],
+                    argv: ["mcp", "serve", "--http"],
                     version: app.version,
                 };
             return {
@@ -84,7 +104,7 @@ export const mcpCommand = (messenger) => {
                 envPrefix: app.envPrefix,
                 env,
                 tokenFile: httpTokenFile(app, settings.profile, env),
-                argv: ["mcp", "--http"],
+                argv: ["mcp", "serve", "--http"],
                 childEnv: { [`${app.envPrefix}_PROFILE`]: settings.profile },
                 version: app.version,
             };
@@ -194,22 +214,17 @@ export const mcpCommand = (messenger) => {
     return command;
 };
 /**
- * `<tool> mcp` with no profile: every profile on this computer, each call in that profile's own `<tool> <profile> mcp`
+ * `<tool> mcp serve` with no profile: every profile on this computer, each call in that profile's own
+ * `<tool> <profile> mcp serve`
  * (`src/mcp/all-profiles.ts`). Nothing picks a profile: each tool takes one, and the agent is told to ask.
  */
 const serveEveryProfile = async (self, context, messenger, flags) => {
     const { app } = messenger;
     const { env } = context;
     const tokenFile = httpTokenFile(app, ALL_PROFILES, env);
-    if (flags.revoke) {
-        const { revokeAll } = await import("../../mcp/http/oauth.js");
-        revokeAll(tokenFile);
-        renderAnswer(self, context, itemOf({ revoked: true, profile: null }));
-        return;
-    }
     const profiles = () => messenger.resolveSettings(self.optsWithGlobals(), { env, needsProfile: false, readOnly: true }).profilesHere;
     if (profiles().length === 0)
-        throw new CliError("configuration_error", `no ${app.command} profile on this computer yet — set one up, then run \`${app.command} mcp\` again`);
+        throw new CliError("configuration_error", `no ${app.command} profile on this computer yet — set one up, then run \`${app.command} mcp serve\` again`);
     const given = environmentOf(self).mcp ?? {};
     const execPath = given.execPath ?? process.execPath;
     const scriptPath = given.scriptPath ?? realpathSync(process.argv[1] ?? "");
@@ -220,7 +235,7 @@ const serveEveryProfile = async (self, context, messenger, flags) => {
         version: app.version,
         name: messenger.name ?? app.command,
         profiles,
-        child: (profile) => ({ command: execPath, args: [scriptPath, profile, "mcp", ...tightened], env }),
+        child: (profile) => ({ command: execPath, args: [scriptPath, profile, "mcp", "serve", ...tightened], env }),
         instructions: instructions({
             command: app.command,
             name: messenger.name ?? app.command,
@@ -337,6 +352,7 @@ export const serverEntry = (app, { profile, flags = {}, execPath, scriptPath, en
             scriptPath,
             ...(profile === undefined ? [] : [profile]),
             "mcp",
+            "serve",
             ...(flags.permission ?? []).flatMap((entry) => ["--permission", entry]),
         ],
         ...(Object.keys(directories).length > 0 ? { env: directories } : {}),

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

@@ -43,9 +43,9 @@ export const messagesSearchCommand = (messenger) => {
         .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
         .addHelpText("after", SAVE_HELP)
         .addHelpText("after", `${syncsFirst(messenger)
-        ? `Search reads the local archive: a chat never fetched is not searched. Prepare it once with
-\`${messenger.app.command} messages sync --all --background\` (the last 90 days of every chat); the answer's
-coverage says what was searched and coverage.next what would improve it.`
+        ? `Search reads the local archive: a chat never fetched is not searched. The answer's coverage says what was
+searched and coverage.next names one chat that would improve it. A sync downloads from the owner's account, so
+offer \`${messenger.app.command} messages sync <chat>\` and run it only once the owner approves.`
         : `Search reads the local archive: what \`${messenger.app.command} serve\` has kept since the account was linked.
 Keep serve running so new messages are searchable.`} Notes are
 \`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; for mail,

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

@@ -72,12 +72,9 @@ export const coverageGaps = (found, shown) => {
     const stale = found.refreshed?.complete === false;
     if (!coverage?.next && !stale)
         return { next: [], missing: [] };
+    const chat = coverage?.chat ?? coverage?.attention[0]?.chatId;
     return {
-        next: [
-            nextStep("messages.sync", {
-                args: coverage?.chat === undefined ? { all: true, background: true } : { chat: coverage.chat },
-            }),
-        ],
+        next: chat === undefined ? [] : [nextStep("messages.sync", { args: { chat } })],
         missing: [
             {
                 field: "coverage",

package/dist/cli/skill-command.js

@@ -2,6 +2,7 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { skillCommand as sharedSkillCommand } from "@wirecat/cli-base/skill";
 import { environmentOf, outputFor } from "./context.js";
 import { grantsAuthority } from "./effects.js";
+import { printItem } from "./envelope.js";
 /**
  * `skill show` and `skill install`. `skill` is the CLI's own SKILL.md, shipped beside `dist/` in the
  * package and in a checkout alike, so the skill printed is always this version's.
@@ -9,7 +10,10 @@ import { grantsAuthority } from "./effects.js";
 export const skillCommand = (app, skill) => {
     const command = sharedSkillCommand(app, skill, (command) => {
         const { env } = environmentOf(command);
-        return { ...outputFor(command), ...(env ? { env } : {}) };
+        const output = outputFor(command);
+        // cli-base prints each answer bare; the envelope is cli-core's.
+        const renderer = { ...output.renderer, result: (value) => printItem(output, value) };
+        return { ...output, renderer, ...(env ? { env } : {}) };
     }, SHARED_SKILLS);
     // An installed skill is instructions every later agent follows.
     const install = command.commands.find((sub) => sub.name() === "install");

package/dist/kit/mcp-stdio.d.ts

@@ -19,8 +19,8 @@ export interface McpStdio {
     close: () => Promise<number>;
 }
 /**
- * A CLI's `mcp` driven over its stdin and stdout, through its own `run()`, with no process and no SDK:
- * `start` passes the two streams to `run(["<profile>", "mcp"], { ...yourOptions, ...streams })`. It has
+ * A CLI's `mcp serve` driven over its stdin and stdout, through its own `run()`, with no process and no SDK:
+ * `start` passes the two streams to `run(["<profile>", "mcp", "serve"], { ...yourOptions, ...streams })`. It has
  * already answered `initialize` when this resolves.
  */
 export declare const mcpOverStdio: (start: (streams: McpStdioStreams) => Promise<number>, { protocolVersion }?: {

package/dist/kit/mcp-stdio.js

@@ -8,8 +8,8 @@ const parsedOrText = (text) => {
     }
 };
 /**
- * A CLI's `mcp` driven over its stdin and stdout, through its own `run()`, with no process and no SDK:
- * `start` passes the two streams to `run(["<profile>", "mcp"], { ...yourOptions, ...streams })`. It has
+ * A CLI's `mcp serve` driven over its stdin and stdout, through its own `run()`, with no process and no SDK:
+ * `start` passes the two streams to `run(["<profile>", "mcp", "serve"], { ...yourOptions, ...streams })`. It has
  * already answered `initialize` when this resolves.
  */
 export const mcpOverStdio = async (start, { protocolVersion = "2025-06-18" } = {}) => {

package/dist/mcp/http/activity.d.ts

@@ -15,7 +15,7 @@ export declare const readActivity: (path: string) => Activity;
 export declare const calledTools: (body: unknown) => string[];
 /**
  * Keeps the activity file of one running server. A call is written at once, so status shows it while the owner
- * watches; other requests at most every two seconds. Its own file, not the token file: `mcp --revoke` rewrites that
+ * watches; other requests at most every two seconds. Its own file, not the token file: `mcp revoke` rewrites that
  * from another process.
  */
 export declare const activityRecorder: (path: string, now?: () => number) => {

package/dist/mcp/http/activity.js

@@ -30,7 +30,7 @@ export const calledTools = (body) => (Array.isArray(body) ? body : [body]).flatM
 });
 /**
  * Keeps the activity file of one running server. A call is written at once, so status shows it while the owner
- * watches; other requests at most every two seconds. Its own file, not the token file: `mcp --revoke` rewrites that
+ * watches; other requests at most every two seconds. Its own file, not the token file: `mcp revoke` rewrites that
  * from another process.
  */
 export const activityRecorder = (path, now = Date.now) => {

package/dist/mcp/http/oauth.js

@@ -132,7 +132,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
         while (stored.clients.length > MAX_CLIENTS) {
             const idle = stored.clients.findIndex((one) => !holding.has(one.id));
             if (idle === -1)
-                return oauthError("invalid_client_metadata", "too many logged-in apps — run mcp --revoke first");
+                return oauthError("invalid_client_metadata", "too many logged-in apps — run mcp revoke first");
             stored.clients.splice(idle, 1);
         }
         store.write(stored);

package/dist/services/messages-search.js

@@ -235,12 +235,9 @@ export const coverageOf = async (store, { scopeAccounts, selectedChat }, messeng
     const completeness = [];
     const stats = new Map();
     let inventoryComplete = scopeAccounts.length > 0;
-    let ownInventory = true;
     for (const selected of scopeAccounts) {
         if (!(await store.sync.syncState(selected, CHAT_LIST_KEY))) {
             inventoryComplete = false;
-            if (messenger.provider === undefined || selected.provider === messenger.provider)
-                ownInventory = false;
         }
         const chatIds = selectedChat
             ? selected.provider === selectedChat.account.provider && selected.account === selectedChat.account.account
@@ -274,15 +271,11 @@ export const coverageOf = async (store, { scopeAccounts, selectedChat }, messeng
     const behindCount = own.filter(behind).length;
     // A chat held back to a window stays partial for good, so only what a fetch would change is advised.
     const command = messenger.app?.command;
-    const next = command === undefined
+    // One named chat, never `--all`: a download is the owner's call and stays bounded to what they approve.
+    const syncChat = selectedChat ? (neverFetched || behindCount ? selectedChat : null) : (attention[0] ?? null);
+    const next = command === undefined || !syncChat || !syncsOneChat(messenger)
         ? null
-        : selectedChat
-            ? (neverFetched || behindCount) && syncsOneChat(messenger)
-                ? `${command} messages sync ${selectedChat.chatId}`
-                : null
-            : (neverFetched || behindCount || !ownInventory) && messenger.history !== "store"
-                ? `${command} messages sync --all --background`
-                : null;
+        : `${command} messages sync ${syncChat.chatId}`;
     const state = selectedChat && completeness.length > 0 && completeness.every(({ state }) => state === "complete")
         ? "complete"
         : completeness.some(({ state }) => state !== "unknown")

package/package.json

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

@@ -789,7 +789,7 @@
     },
     "--port": {
       "value": "<port>",
-      "meaning": "the local port behind the tunnel, for mcp --http or bot watch --public-url"
+      "meaning": "the local port behind the tunnel, for mcp serve --http or bot watch --public-url"
     },
     "--priority": {
       "value": "<n>",
@@ -804,7 +804,7 @@
     },
     "--public-url": {
       "value": "<url>",
-      "meaning": "the tunnel's https address: the browser apps reach mcp --http through it, a messenger delivers to bot watch"
+      "meaning": "the tunnel's https address: the browser apps reach mcp serve --http through it, a messenger delivers to bot watch"
     },
     "--question": {
       "meaning": "match only questions"
@@ -861,9 +861,6 @@
       "value": "<n>",
       "meaning": "the revision you read before editing"
     },
-    "--revoke": {
-      "meaning": "forget every login given to a browser app over --http"
-    },
     "--revote": {
       "meaning": "people may change their vote"
     },
@@ -1732,7 +1729,6 @@
     },
     "bot mcp": {
       "in": ["max", "tg"],
-      "options": {},
       "planned": {
         "wa": "whatsapp-cli: wa bot API, plans/2026-10-22-wa-bot-api"
       }
@@ -1744,6 +1740,13 @@
         "wa": "whatsapp-cli: wa bot API, plans/2026-10-22-wa-bot-api"
       }
     },
+    "bot mcp serve": {
+      "in": ["max", "tg"],
+      "options": {},
+      "planned": {
+        "wa": "whatsapp-cli: wa bot API, plans/2026-10-22-wa-bot-api"
+      }
+    },
     "bot me": {
       "in": ["max", "tg"],
       "planned": {
@@ -3138,22 +3141,7 @@
       }
     },
     "mcp": {
-      "in": "all",
-      "options": {
-        "--http": "all",
-        "--permission": "all",
-        "--port": "all",
-        "--public-url": "all",
-        "--revoke": "all",
-        "--yes": {
-          "in": [],
-          "planned": {
-            "max": "P7",
-            "tg": "P7",
-            "wa": "P7"
-          }
-        }
-      }
+      "in": "all"
     },
     "mcp add": {
       "in": "all",
@@ -3182,6 +3170,26 @@
         }
       }
     },
+    "mcp revoke": {
+      "in": "all"
+    },
+    "mcp serve": {
+      "in": "all",
+      "options": {
+        "--http": "all",
+        "--permission": "all",
+        "--port": "all",
+        "--public-url": "all",
+        "--yes": {
+          "in": [],
+          "planned": {
+            "max": "P7",
+            "tg": "P7",
+            "wa": "P7"
+          }
+        }
+      }
+    },
     "mcp server": {
       "in": "all"
     },