@wirecat/cli-core 0.545.0 → 0.547.0

package/dist/cli/entry.d.ts

@@ -58,3 +58,5 @@ export interface CliEntry {
  * output still flushes.
  */
 export declare const startCli: (entry: CliEntry) => Promise<void>;
+/** Opens `url` in the system browser, or in `browser` when given; resolves once the browser has started. */
+export declare const openBrowser: (url: string, browser?: string, io?: Pick<EntryIo, "platform" | "spawn">) => Promise<void>;

package/dist/cli/entry.js

@@ -88,7 +88,7 @@ export const startCli = async (entry) => {
             });
             return /^(y|yes)$/i.test(answer.trim());
         },
-        openBrowser: (url, browser) => openBrowser(io, url, browser),
+        openBrowser: (url, browser) => openBrowser(url, browser, io),
         outputClosed: () => closed,
     };
     let code;
@@ -138,7 +138,8 @@ const commanderExit = (error) => {
         return 0;
     return code === "commander.help" ? 2 : undefined;
 };
-const openBrowser = (io, url, browser) => {
+/** Opens `url` in the system browser, or in `browser` when given; resolves once the browser has started. */
+export const openBrowser = (url, browser, io = { platform: process.platform, spawn }) => {
     const [command, prefix] = browser !== undefined
         ? [browser, []]
         : io.platform === "darwin"

package/dist/cli/index.d.ts

@@ -39,6 +39,7 @@ export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";
 export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
 export { answerStdinOption, type Need, type SignInSteps, type SignInStepsOptions, signInSteps, } from "../terminal/sign-in-steps.js";
+export { liftOptionsAfterDashes } from "./after-dashes.js";
 export { type AgentPolicy, type AgentTask, type EvaluationResult, evaluateAgent, type Observation, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
 export { type AppDoctorOptions, appDoctorReport } from "./app-doctor-command.js";
@@ -67,7 +68,7 @@ export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
 export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
-export { type CliEntry, type EntryContext, type EntryIo, startCli } from "./entry.js";
+export { type CliEntry, type EntryContext, type EntryIo, openBrowser, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, setupAtStart, systemLanguage, } from "./first-run.js";

package/dist/cli/index.js

@@ -34,6 +34,7 @@ export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";
 export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
 export { answerStdinOption, signInSteps, } from "../terminal/sign-in-steps.js";
+export { liftOptionsAfterDashes } from "./after-dashes.js";
 export { evaluateAgent, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
 export { appDoctorReport } from "./app-doctor-command.js";
@@ -59,7 +60,7 @@ export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
 export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
-export { startCli } from "./entry.js";
+export { openBrowser, startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { askSetupQuestions, asksAtStart, setupAtStart, systemLanguage, } from "./first-run.js";

package/dist/cli/messenger/admin-commands.js

@@ -247,7 +247,11 @@ const requestsCommand = (messenger) => {
 };
 /** `chats create`, `join`, `leave`, `update` and `link`: the help text is max-cli's, the one both tools say (standard, help rule 2). */
 export const groupCommands = (messenger) => [
-    annotate(new Command("create"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
+    annotate(new Command("create"), {
+        output: { entity: "chat_group_change" },
+        effects: REMOTE_WRITE,
+        literal_after_dashes: true,
+    })
         .description("create a group or a channel; the people added are told")
         .argument("<title>", "the group's name")
         .argument("[person...]", "people to add: an id, or part of a name")

package/dist/cli/messenger/admin-contacts-command.js

@@ -30,7 +30,11 @@ export const contactWriteCommands = (messenger) => {
         const done = await context.withServices((services) => services.people[name](person));
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     }));
-    const rename = annotate(new Command("rename"), { effects: REMOTE_WRITE, output: { entity: "contact_update" } })
+    const rename = annotate(new Command("rename"), {
+        effects: REMOTE_WRITE,
+        output: { entity: "contact_update" },
+        literal_after_dashes: true,
+    })
         .summary("change a contact's name in the messenger address book")
         .description("rename the contact in the messenger address book; use contacts alias for a private local name")
         .argument("<person>", PERSON)

package/dist/cli/messenger/admin-folders-command.js

@@ -57,7 +57,11 @@ export const foldersCommand = (messenger) => {
         const found = await context.withServices((services) => services.folders.show(folder));
         renderAnswer(this, context, itemOf(folderAnswer(found)));
     }));
-    folders.addCommand(withRules(annotate(new Command("create"), { output: { entity: "chat_folder_change" }, effects: REMOTE_WRITE })
+    folders.addCommand(withRules(annotate(new Command("create"), {
+        output: { entity: "chat_folder_change" },
+        effects: REMOTE_WRITE,
+        literal_after_dashes: true,
+    })
         .description("create a chat folder")
         .argument("<title>", "the folder's name; the app may refuse a long one")
         .option("--chat <chat>", "a chat to put in it, by id or name; repeat it for more", collect), messenger, false).action(async function (title) {

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

@@ -20,6 +20,7 @@ const SHELLS = ["zsh", "bash", "fish", "powershell"];
  * exists — no store, no names — and nothing goes to stderr: a shell shows whatever it is given.
  */
 export const completeCommand = (messenger, config, options = {}) => annotate(new Command("complete"), {
+    literal_after_dashes: true,
     effects: LOCAL_READ,
     mcp: false,
     examples: [`${messenger.app.command} complete zsh`],

package/dist/cli/messenger/history-query.d.ts

@@ -9,14 +9,20 @@ export declare const historyQuery: (messenger: {
 }) => import("@wirecat/cli-base/query").QueryRegistry;
 declare const COMMENTS_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
 export { COMMENTS_QUERY };
-type Start = Pick<ListWindow, "before" | "beforeTime" | "after">;
+type Start = Pick<ListWindow, "before" | "beforeTime" | "after" | "until">;
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export declare const cursorOf: (start: Start, edge: {
     first?: string;
     last?: string;
 }) => string | undefined;
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export declare const historyWindow: (words: QueryWords, cursor: string | undefined, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => Omit<ListWindow, "limit">;
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export declare const resumeQuery: (words: QueryWords, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => string | undefined;

package/dist/cli/messenger/history-query.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
-import { dateEndpoint, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
-import { listQuery, nativeField, nativeTerms, typedQuery } from "../list-query.js";
+import { dateRange, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
+import { listQuery, nativeField, nativeTermLists, typedQuery } from "../list-query.js";
 /** What a chat's history can be read by: where it starts, and one topic. */
 export const HISTORY_QUERY = defineQuery({
     entity: "message",
@@ -36,52 +36,108 @@ const COMMENTS_QUERY = defineQuery({
 });
 export { COMMENTS_QUERY };
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export const cursorOf = (start, edge) => {
     const forward = start.after !== undefined;
     const id = forward ? edge.last : edge.first;
-    return id === undefined ? undefined : `${forward ? "after" : "before"}:${id}`;
+    if (id === undefined)
+        return undefined;
+    const end = forward && start.until !== undefined ? `~${start.until}` : "";
+    return `${forward ? "after" : "before"}:${id}${end}`;
 };
 const isId = (value) => value !== "" && !/[\s\p{Cc}]/u.test(value);
 const fromCursor = (cursor) => {
     const at = cursor.indexOf(":");
-    const [way, id] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const [way, rest] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const ended = way === "after" ? /^(.*)~(\d+)$/u.exec(rest) : null;
+    const id = ended ? ended[1] : rest;
     if (!isId(id) || (way !== "before" && way !== "after"))
         throw new CliError("validation_error", `--cursor takes what page.next gave, before:<id> or after:<id> — not "${cursor}"`);
-    return way === "before" ? { before: id } : { after: { id } };
+    if (way === "before")
+        return { before: id };
+    return { after: { id }, ...(ended ? { until: Number(ended[2]) } : {}) };
 };
-const startOf = (term, command) => {
+/** A term's lower and upper bound; a date's as moments in the zone, an exclusive end 1 ms inside. */
+const boundsOf = (term, command) => {
     const context = { command };
-    const older = term.value === "*" && term.upper !== undefined && term.upper !== "*";
-    const newer = term.value !== "*" && (term.upper === undefined || term.upper === "*");
-    if (older === newer)
-        queryError("query.unsupported-operator", term.span, `${term.field} takes one side: ${term.field}< or ${term.field}>`, context);
-    if (term.field === "id")
-        return older ? { before: term.upper } : { after: { id: term.value } };
-    const bound = older ? term.upper : term.value;
-    const inclusive = (older ? term.upper_inclusive : term.lower_inclusive) ?? true;
-    const { time } = dateEndpoint(bound, timezoneOf(), older ? "upper" : "lower", inclusive, term.span);
-    if (time === undefined)
-        queryError("query.invalid-date", term.span, `${bound} is not a time`, context);
-    return older ? { beforeTime: time } : { after: { time } };
+    const hasLower = term.value !== "*";
+    const hasUpper = term.upper !== undefined && term.upper !== "*";
+    const span = term.span;
+    if (term.field === "id") {
+        if (hasLower === hasUpper)
+            queryError("query.unsupported-operator", span, "id takes one side: id< or id>", context);
+        return hasLower
+            ? { lower: { start: { after: { id: term.value } }, span, date: false } }
+            : { upper: { start: { before: term.upper }, span, date: false } };
+    }
+    if (!hasLower && !hasUpper)
+        queryError("query.unsupported-operator", span, `${term.field} needs a start, an end or both`, context);
+    const range = dateRange(term.value, term.upper ?? "*", term.lower_inclusive ?? true, term.upper_inclusive ?? true, timezoneOf(), span);
+    if ((hasLower && range.lower === undefined) || (hasUpper && range.upper === undefined))
+        queryError("query.invalid-date", span, "that is not a time", context);
+    return {
+        // The messenger and the store read strictly after a start, so an inclusive one moves 1 ms back.
+        ...(range.lower === undefined
+            ? {}
+            : { lower: { start: { after: { time: range.lower - (range.lower_inclusive ? 1 : 0) } }, span, date: true } }),
+        ...(range.upper === undefined
+            ? {}
+            : { upper: { start: { until: range.upper - (range.upper_inclusive ? 0 : 1) }, span, date: true } }),
+    };
 };
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/**
+ * The window the query names. A start reads forward from it, oldest first, and stops at an end; an end alone reads
+ * back from it, newest page first.
+ */
+const windowOf = (terms, command) => {
+    const context = { command };
+    const lowers = [];
+    const uppers = [];
+    for (const term of terms) {
+        const { lower, upper } = boundsOf(term, command);
+        if (lower)
+            lowers.push(lower);
+        if (upper)
+            uppers.push(upper);
+    }
+    const [lower, extraLower] = lowers;
+    const [upper, extraUpper] = uppers;
+    if (extraLower)
+        queryError("query.unsupported-placement", extraLower.span, "the window has one start", context);
+    if (extraUpper)
+        queryError("query.unsupported-placement", extraUpper.span, "the window has one end", context);
+    if (lower && upper && !upper.date)
+        queryError("query.unsupported-placement", upper.span, "a window from a start ends at a date: date<…", context);
+    if (lower)
+        return { ...lower.start, ...upper?.start };
+    if (upper?.start.until !== undefined)
+        return { beforeTime: upper.start.until + 1 };
+    return upper?.start ?? {};
+};
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export const historyWindow = (words, cursor, command, registry = HISTORY_QUERY) => {
-    const terms = [...nativeTerms(listQuery(typedQuery(words), registry, command), command).values()];
-    const starts = terms
-        .filter((term) => term.field !== "topic" && term.field !== "starred")
-        .map((term) => startOf(term, command));
-    if (cursor !== undefined)
-        starts.push(fromCursor(cursor));
-    if (starts.length > 1)
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const bounds = [...(terms.get("date") ?? []), ...(terms.get("id") ?? [])];
+    const start = windowOf(bounds, command);
+    if (cursor !== undefined && bounds.length > 0)
         throw new CliError("validation_error", "the query and --cursor name two starting points; give one of them");
-    const topic = terms.find((term) => term.field === "topic")?.value;
-    const starred = terms.find((term) => term.field === "starred")?.value.toLowerCase();
+    const topic = terms.get("topic")?.[0]?.value;
+    const starred = terms.get("starred")?.[0]?.value.toLowerCase();
     return {
-        ...starts[0],
+        ...(cursor === undefined ? start : fromCursor(cursor)),
         ...(topic === undefined ? {} : { threadId: topic }),
         ...(starred === undefined ? {} : { starred: starred === "true" }),
     };
 };
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export const resumeQuery = (words, command, registry = HISTORY_QUERY) => {
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const kept = ["topic", "starred"].flatMap((field) => terms.get(field)?.map((term) => `${field}:${term.value}`) ?? []);
+    return kept.length > 0 ? kept.join(" ") : undefined;
+};

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

@@ -12,6 +12,7 @@ import { modelWith, spoken } from "../../speech/hearing.js";
 import { REMOTE_READ } from "../effects.js";
 import { itemOf, listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
+import { withOptionHints } from "../option-hints.js";
 import { positiveCount } from "../paging.js";
 import { syncCommand } from "./backfill-command.js";
 import { messengerContext } from "./context.js";
@@ -19,7 +20,7 @@ import { linksCommand } from "./conversations-command.js";
 import { downloadSubcommand } from "./download-command.js";
 import { heardItems, hearForCommand, hearingMissing, MODEL_OPTION, spokenItems, TRANSCRIBE_OPTION, } from "./hearing-command.js";
 import { historyLimitGaps } from "./history-gaps.js";
-import { cursorOf, historyQuery, historyWindow } from "./history-query.js";
+import { cursorOf, historyQuery, historyWindow, resumeQuery } from "./history-query.js";
 import { hideNever } from "./lacks.js";
 import { threadAnswer } from "./message-answers.js";
 import { messageItem, messageItems, viewOf } from "./message-items.js";
@@ -36,6 +37,8 @@ import { sendCommand } from "./messages-send-command.js";
 import { coverageGaps } from "./search-answers.js";
 import { threadOptions, threadRequest } from "./thread-options.js";
 import { transcribeSubcommand } from "./transcribe-command.js";
+const WINDOW_EXAMPLE = "date>=2026-10-01 date<2026-10-20";
+const TIME_FLAGS = ["--since", "--since-time", "--until", "--until-time", "--after-time", "--before-time"];
 /** `messages`: reading, and sending through the guard. A CLI may add its own subcommands. */
 export const messagesCommand = (messenger) => {
     const messages = new Command("messages").description("read and send messages");
@@ -51,8 +54,8 @@ export const messagesCommand = (messenger) => {
         .addHelpText("after", queryHelp(history))
         .argument("<chat>", messenger.chatArgument)
         .argument("[query...]", `${messenger.topics === false
-        ? "where to start: id<42, date>2026-10-01"
-        : "where to start and which topic: id<42, date>2026-10-01, topic:12"}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
+        ? `where to start or which window: id<42, ${WINDOW_EXAMPLE}`
+        : `where to start or which window, and which topic: id<42, ${WINDOW_EXAMPLE}, topic:12`}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it")
         .option(...TRANSCRIBE_OPTION)
@@ -73,6 +76,8 @@ export const messagesCommand = (messenger) => {
         const next = page.hasMore
             ? cursorOf(window, { first: page.items[0]?.id, last: page.items.at(-1)?.id })
             : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages list", history);
+        const queryArg = typed ? { query: typed } : {};
         // Offline, the store is the whole answer: say how much of the chat it holds. Online the messenger is read.
         const gaps = context.settings.offline
             ? await context.withStore(async (store, account) => {
@@ -88,18 +93,18 @@ export const messagesCommand = (messenger) => {
             has_more: page.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, ...queryArg },
             next: gaps.next,
             missing: [...hearingMissing(hearing, transcribe === true), ...gaps.missing],
             ...(gaps.missing.length > 0 ? { meta: { complete: false } } : {}),
         }), () => renderMessages(spokenItems(page.items, hearing), viewOf(context, messenger)));
     });
     annotate(list, { output: { entity: "message" }, query: history });
+    withOptionHints(list, Object.fromEntries(TIME_FLAGS.map((flag) => [flag, `messages list reads a window by its query: '${WINDOW_EXAMPLE}'`])));
     const readWindow = async (command, chat, message, window) => {
         const context = messengerContext(command, messenger);
-        const target = targetOf(messenger, chat, message);
         const { found, reader } = await context.withServices(async (services) => ({
-            found: await services.messages.around(isLocator(chat) ? chat : target.chat, isLocator(chat) ? undefined : target.message, window),
+            found: await services.messages.around(chat, message?.trim(), window),
             reader: await services.messages.reader(),
         }));
         const hearing = await hearForCommand(context, messenger, found, false);
@@ -156,9 +161,8 @@ export const messagesCommand = (messenger) => {
         const requested = threadRequest(this).thread;
         if (requested) {
             const context = messengerContext(this, messenger);
-            const target = targetOf(messenger, chat, message);
             const { found, reader } = await context.withServices(async (services) => ({
-                found: await services.messages.thread(isLocator(chat) ? chat : target.chat, isLocator(chat) ? undefined : target.message, { ...requested, before, after }),
+                found: await services.messages.thread(chat, message?.trim(), { ...requested, before, after }),
                 reader: await services.messages.reader(),
             }));
             if (found.fallback)
@@ -203,19 +207,4 @@ const count = (value) => {
         throw new CliError("validation_error", `"${value}" is not a count`);
     return parsed;
 };
-/** A chat and a message id, or one locator naming both — which must be this messenger's. */
-const targetOf = (messenger, chat, message) => {
-    if (isLocator(chat)) {
-        if (message !== undefined)
-            throw new CliError("validation_error", "a locator already names the message");
-        const locator = parseLocator(chat);
-        if (locator.provider !== messenger.provider) {
-            throw new CliError("validation_error", `that locator is a ${locator.provider} message, not ${messenger.provider}`);
-        }
-        return { chat: locator.chat, message: locator.message };
-    }
-    if (message === undefined)
-        throw new CliError("validation_error", "which message? give its id after the chat");
-    return { chat, message: message.trim() };
-};
 export { sendCommand } from "./messages-send-command.js";

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

@@ -7,7 +7,7 @@ import { listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
-import { COMMENTS_QUERY, cursorOf, historyWindow } from "./history-query.js";
+import { COMMENTS_QUERY, cursorOf, historyWindow, resumeQuery } from "./history-query.js";
 import { messageItems, viewOf } from "./message-items.js";
 export const commentsCommand = (messenger) => {
     const otherPosts = messenger.readsComments === true && messenger.channelComments === false;
@@ -42,13 +42,15 @@ export const commentsCommand = (messenger) => {
             reader: await services.messages.reader(),
         }));
         const next = found.hasMore ? cursorOf(window, { first: found.items[0]?.id }) : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages comments", COMMENTS_QUERY);
+        const queryArg = typed ? { query: typed } : {};
         renderAnswer(this, context, listOf("messages comments", {
             items: messageItems(found.items, reader),
             limit,
             has_more: found.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, post, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, post, ...queryArg },
         }), () => renderMessages(found.items, viewOf(context, messenger)));
     });
     return annotate(command, { output: { entity: "message" }, query: COMMENTS_QUERY });

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

@@ -9,6 +9,7 @@ import { HTML_HELP } from "./messages-send-command.js";
 import { readAll } from "./stdin.js";
 export const editCommand = (messenger) => {
     const edit = annotate(new Command("edit"), {
+        literal_after_dashes: true,
         examples: [`${messenger.app.command} personal messages edit "Book club" 101 "The meeting starts at 11."`],
         effects: REMOTE_WRITE,
         output: { entity: "message_write" },

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

@@ -6,6 +6,7 @@ import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
 /** `messages press` — one of a bot's callback buttons; the bot sees who pressed it. */
 export const pressCommand = (messenger) => annotate(new Command("press"), {
+    literal_after_dashes: true,
     effects: REMOTE_WRITE,
     examples: [`${messenger.app.command} personal messages press "Example Bot" 101 1`],
 })

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

@@ -20,6 +20,7 @@ const collect = (value, previous) => [...previous, value];
 const repeatable = (flags, description) => new Option(flags, description).argParser(collect).default([], "none");
 export const sendCommand = (messenger) => {
     const send = annotate(new Command("send"), {
+        literal_after_dashes: true,
         examples: [`${messenger.app.command} personal messages send "Book club" "The meeting starts at 10."`],
         effects: REMOTE_WRITE,
         output: { entity: messenger.drafts === true ? "message_send" : "message_write" },

package/dist/cli/messenger/observed.js

@@ -42,9 +42,9 @@ export const observed = (messenger, events) => {
     };
     const counted = async (operation, onItem, work, count) => {
         const counts = {};
-        await timed(operation, {}, () => work((item) => {
+        await timed(operation, {}, () => work((item, ...rest) => {
             count(item, counts);
-            return onItem(item);
+            return onItem(item, ...rest);
         }), () => ({ counts }));
     };
     const mint = messenger.newSendId;

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

@@ -110,6 +110,7 @@ export const pollsCommand = (messenger) => {
             renderAnswer(this, context, itemOf(snakeKeys(closed)));
         });
     const create = annotate(polls.command("create"), {
+        literal_after_dashes: true,
         output: { entity: "message_write" },
         effects: REMOTE_WRITE,
         examples: [`${messenger.app.command} personal polls create "Book club" "Which day?" Monday Tuesday`],

package/dist/cli/messenger/private-people-command.js

@@ -14,7 +14,11 @@ const NOTES_QUERY = unfilteredQuery("contact_note", contactNote);
 const everyNote = (command, items) => listOf(command, { items, limit: Math.max(1, items.length), has_more: false });
 export const privatePeopleCommands = (messenger) => {
     const alias = new Command("aliases").description("a private local display name in the selected account");
-    annotate(alias.command("set"), { effects: LOCAL_WRITE, output: { entity: "contact_alias" } })
+    annotate(alias.command("set"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "contact_alias" },
+        literal_after_dashes: true,
+    })
         .description("your own name for a person in this account; kept on this machine, never sent")
         .argument("<person>", "the person's id, reference or known name")
         .argument("<alias>", "the private name to use for this person")

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
+    error?: undefined;
     path: string;
     exists: boolean;
-    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/messenger/stored.js

@@ -1,9 +1,10 @@
 import { CliError } from "@wirecat/cli-base";
+import { chatReferenceOf, ensureAccount } from "../../domain/ref-arguments.js";
 import { capability, throughWrapper, } from "../../ports/messenger.js";
 import { foldName, isId, pickPerson } from "../../resolve.js";
 import { codeOf } from "../../sends/guarded.js";
 import { limitBatch } from "../../services/history-limits.js";
-import { chatIdIn } from "../../services/message-resolution.js";
+import { chatIdIn, profilesOnAccount } from "../../services/message-resolution.js";
 const REKEY_PACING = { lockMs: 50, pauseMs: 25 };
 /**
  * The adapter, with what each read answers written to the store. **A failed write never fails the
@@ -201,12 +202,12 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
                 pending?.delete(saving);
                 rekeysOnly.delete(saving);
             });
-            void onBatch(batch);
+            void onBatch(batch, saving);
             return saving;
         };
     };
     // A method not listed here saves nothing and passes through; a lane that should save adds its line.
-    return throughWrapper(messenger, {
+    const wrapped = throughWrapper(messenger, {
         ...(messenger.forumState
             ? {
                 forumState: async (chatId) => {
@@ -465,6 +466,58 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
             return sent;
         },
     });
+    const chatOf = async (typed) => {
+        const named = chatReferenceOf(typed, account.provider);
+        if (!named)
+            return typed;
+        let known;
+        try {
+            known = account.account;
+        }
+        catch { }
+        await ensureAccount(named, { account: known, ...(profile ? { profile: profile.name } : {}) }, async (other) => {
+            const opened = await store();
+            return opened && profilesOnAccount(opened, profile?.app, account.provider)(other);
+        });
+        return named.chat;
+    };
+    return withChatReferences(wrapped, chatOf);
+};
+/** The adapter methods whose first argument is a chat as typed: an id, a title, or a `chat:` or `msg:` reference. */
+const TYPED_CHAT = [
+    "resolve",
+    "chat",
+    "history",
+    "around",
+    "historyAfter",
+    "historyBefore",
+    "historyFrom",
+    "topics",
+    "topic",
+    "topicHistory",
+    "download",
+    "transcribe",
+    "scheduled",
+    "admins",
+    "chatEvents",
+    "leave",
+    "group",
+    "officialChatStats",
+];
+/**
+ * A reference is read here, not in each adapter: an adapter resolves a typed chat as an id or a title, and would take
+ * `chat:max/…` for a title. One of another account is refused before the messenger is asked.
+ */
+const withChatReferences = (adapter, chatOf) => {
+    const methods = adapter;
+    const own = Object.fromEntries(TYPED_CHAT.flatMap((name) => {
+        const method = methods[name];
+        if (typeof method !== "function")
+            return [];
+        const call = async (typed, ...rest) => method.call(adapter, await chatOf(typed), ...rest);
+        return [[name, call]];
+    }));
+    return throughWrapper(adapter, own);
 };
 /**
  * A write is saved under the chat the messenger answered, not the one typed: WhatsApp answers a re-keyed person's

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

@@ -68,7 +68,7 @@ export const topicsCommand = (messenger) => {
         const done = await context.withServices((services) => services.topics.enable(chat, { upgrade: this.opts().upgrade === true }));
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     });
-    annotate(topics.command("create"), { effects: REMOTE_WRITE })
+    annotate(topics.command("create"), { effects: REMOTE_WRITE, literal_after_dashes: true })
         .description("create a named topic in an existing forum; never enable or upgrade a group implicitly")
         .argument("<chat>", messenger.chatArgument)
         .argument("<title>", "the topic title, at most 128 UTF-8 bytes")

package/dist/cli/option-hints.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export declare const withOptionHints: (command: Command, hints: Readonly<Record<string, string>>) => Command;

package/dist/cli/option-hints.js

@@ -0,0 +1,15 @@
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export const withOptionHints = (command, hints) => {
+    const unknown = command;
+    const fallback = unknown.unknownOption.bind(command);
+    unknown.unknownOption = (flag) => {
+        const hint = hints[flag.split("=")[0]];
+        if (hint === undefined)
+            return fallback(flag);
+        return command.error(`unknown option '${flag}' — ${hint}`, { code: "commander.unknownOption" });
+    };
+    return command;
+};