@wirecat/cli-core 0.561.0 → 0.563.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ shape of this file.
 
 ## Unreleased
 
+## 0.563.0 — 03.11.2026
+
+### Changed — may break callers
+
+- **Mail sync reads attachments up to 10 MB a file by default, and can skip them.** Until now every attachment was
+  read, whatever its size; at the next bump a file over 10 MB is no longer read into the index unless the caller
+  passes a policy. `MailSyncOptions.attachments` takes a `MailAttachmentPolicy` (`read`, `maxBytes`); left out it is
+  `DEFAULT_ATTACHMENT_POLICY`. A file the policy leaves is stored with its name, type and size but no text, with
+  `extractionError` `not-read` or `too-large` (`POLICY_SKIPS`), and the run's `attachments` log says the same.
+  Partial completion and `retryAttachments` follow it too.
+- **Moving a task to another project moves its subtasks with it.** `tasks.edit(id, { project })` on a task with
+  subtasks no longer refuses with `task.has-subtasks`; that reason is gone. Every subtask, all the way down, takes the
+  next key in the new project and keeps its parent, and its old key still finds it. The answer names them as
+  `movedSubtasks: [{ from, to }]`, old key and new; the field is left out when nothing moved with the task. A subtask
+  moved on its own still needs `parent: null` in the same edit (`task.is-subtask`).
+
+- **Owner-only proposals refuse an agent on every decide path.** `mayDecide` and `assertMayDecide` now read
+  the row's stored `kind`: a `mail_findings` or `meeting_findings` row is the owner's alone, whatever
+  `agent_decisions` says. The registry's `get` and `list` rows carry `ownerOnly` from their kind, and the generic
+  action kind marks a stored findings row too, so a host checking `assertMayDecide(await registry.get(id), …)` is
+  refused. `approveAsTask` and `proposedActions.approve` / `reject` refuse a mail findings batch as they refuse
+  meeting and evidence findings (`mail-findings.dedicated-review`), and the generic action kind no longer lists any
+  findings batch. Meeting findings were open to another agent with a reason before; now only the owner reviews them.
+
+### Added
+
+- **An answer over the output cap says what to run instead (WC-OUT-22).** The `output.too-large` failure now names up
+  to two reads, both safe to run unasked: the same command line with `--compact`, when the command declares a row and
+  was not compact already, and the same line with a `--limit` scaled down to fit. The lines are rebuilt from the
+  words the caller typed, never from the answer. The failure also carries `needed_bytes`.
+- **A JSON answer over 256 KiB adds one step to the compact form.** The answer is still printed whole. Nothing is
+  added when the answer already names two steps, over MCP, or for a command with no declared row.
+- **`search messages --chat` and `search all --chat` say how to search one chat:** `chat:<chat>` in the query.
+
+- **`readEmailWhole` reads one stored email again from its mail server, every attachment of it with no limit.** It
+  saves the new text on the email as a sync does, keeping its mailboxes, flags and rule, and answers each attachment's
+  bytes for the caller to save. Gmail's email is found by id, another server's at its stored place.
+  `store.mail.emailPlace(accountId, externalId)` gives an email's thread and stored places.
+- **`stats messages responses`**: how fast replies come in one-to-one chats, the owner's (`--who me`) or the other
+  side's (`--who others`): count, median, p90, mean and four time buckets, in total or `--by day` in `--timezone`.
+  Several messages in a row followed by one answer are one reply, timed from the first. Reads by index, so all time
+  works on a large store; the query after `--` takes `date:`, `chat:` and `kind:` only.
+- **`stats messages waiting`**: how many chats wait on the owner — a one-to-one chat whose newest message is a
+  question, or a group whose newest message mentions or replies to the owner — with the messages since the owner
+  last wrote, the oldest of them, and the split by kind. Muted or archived one-to-one chats are left out, as in
+  `inbox`.
+- **tg, max, wa, mail, gcal and drive's config file holds every shared setting with its default.** A first run now
+  writes all of them into `defaults`, not five; `config set` and `config unset` add the missing ones (but not the one
+  just unset); and the new `<cli> config migrate` fills an existing file. Your values, their order and unknown keys
+  stay; a file without `defaults` gets that section, and no other section is created. `config show` gives each of
+  these settings its `default` and `description`, and no longer creates the file when there is none. `settingsFor`
+  returns `declaredSettings` and `migrate(path)`; `extension.settings` declares a CLI's own (cli-base WC-CMD-30).
+  Settings with no single default (`timeout_ms`, `color`, `requests_per_minute`, the embedding model) and objects
+  (`permissions`, `models`) are left out.
+- **`MailReads.mount`: the steps a mail review hands on name where the host mounted it.** A host that mounts `review`
+  and `messages acknowledge` elsewhere passes their paths and the option naming the mailbox — memo passes
+  `review: "mail review"`, `conversation: null` (it mounts no thread read) and `mailbox: { option: "source", value }`
+  — and `next` names those paths and `--source email:<account>`. `mailReviewSteps(mount)` gives the definitions for
+  a host's step checks; a mail CLI leaves it out, and its step lines carry the profile as before.
+
+## 0.562.0 — 03.11.2026
+
+### Added
+
+- **A CLI can write each of its settings into its config file with the default, so the owner sees every setting
+  there.** A CLI declares its scalar settings as `DeclaredSetting` (`key`, `default`, `description`).
+  `withSettingDefaults(raw, declared)` returns the file with each missing setting added at its default. It keeps the
+  owner's values, their order and unknown keys. It does not create a section that is not there.
+  `settingRows(raw, declared)` gives `config show` each setting with its value, default, description and `from`
+  (`config file` or `default`). memo is the first user (cli-base WC-CMD-30).
+- **`KEEP_SUCCESSFUL_RUNS_FOR_DAYS` and `RUNS_SIZE_LIMIT_MB` are exported** beside `KEEP_RUNS_FOR_DAYS`. A host can
+  then name the run-record defaults it writes into its config file.
+
+### Fixed
+
+- **The shared `doctor` (`appDoctorCommand`) answers with the clock:** `meta.now`, `meta.now_local` and
+  `meta.timezone`, as a setup check should (WC-TIME-7). A CLI that kept its own doctor for this can use the shared one.
+
 ## 0.561.0 — 03.11.2026
 
 ### Changed — may break callers

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

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { CliError, configFilePath, resolvePaths } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
+import { timezoneOf } from "@wirecat/cli-base/query";
+import { clockMeta } from "@wirecat/cli-base/standards";
 import { isNewer, latestVersion } from "@wirecat/cli-base/update";
 import { Command } from "commander";
 import { envName, readOnlyLockOf } from "../ports/app.js";
@@ -149,7 +151,7 @@ export const appDoctorCommand = (app, configuration, options = {}) => profileFre
         ? await onlineCheck(app, env, environment.fetch ?? fetch, options)
         : undefined;
     const output = outputFor(this);
-    renderAnswer(this, output, itemOf({ ...report, ...local.fields, ...(online ? { online } : {}) }));
+    renderAnswer(this, output, itemOf({ ...report, ...local.fields, ...(online ? { online } : {}) }, { meta: clockMeta(Date.now(), timezoneOf()) }));
     for (const fix of fixes)
         output.renderer.note(`to make it private: ${fix}`);
     for (const note of local.notes)

package/dist/cli/config-command.js

@@ -30,6 +30,7 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
         const bot = this.opts().bot === true;
         const context = baseContext(this, (flags, options) => config.resolveSettings(flags, {
             ...options,
+            readOnly: true,
             needsProfile: false,
             withIssues: true,
             ...(bot ? { kind: "bot" } : {}),
@@ -48,7 +49,13 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             paths_overridden: overridden,
             settings: [...config.allSettings, "command_timeout_ms"]
                 .filter((setting) => bot || setting !== "read_other_bots")
-                .map((setting) => sourced(settings, setting)),
+                .map((setting) => {
+                const declared = config.declaredSettings.find(({ key }) => key === `defaults.${setting}`);
+                return {
+                    ...sourced(settings, setting),
+                    ...(declared ? { default: declared.default, description: declared.description } : {}),
+                };
+            }),
             store_settings: await storeSettings(env),
         }));
         for (const issue of [
@@ -144,9 +151,19 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             }));
         });
     }
+    command.addCommand(migrateCommand(app, config));
     command.addCommand(repairCommand(app, config));
     return command;
 };
+const migrateCommand = (app, config) => profileFree(grantsAuthority(annotate(new Command("migrate"), { effects: LOCAL_WRITE, examples: [`${app.command} config migrate`] })))
+    .description("write each setting the file lacks at its default, keeping yours")
+    .action(function () {
+    const context = baseContext(this, (flags, options) => config.resolveSettings(flags, { ...options, needsProfile: false, withIssues: true }));
+    const file = context.settings.configPath;
+    const added = config.migrate(file);
+    renderAnswer(this, context, itemOf({ config_file: file, added }));
+    context.renderer.note(added.length > 0 ? `added ${added.join(", ")} to ${file}` : `${file} already has every setting`);
+});
 /**
  * Mends JSON syntax with one reading and keeps every value (NEED-2178): no network, no AI, since the file may hold
  * keys. Anything else is refused with nothing changed.

package/dist/cli/envelope.js

@@ -5,6 +5,7 @@ import * as v from "valibot";
 import { currentRun } from "../runs/scope.js";
 import { compactText, entityRows, rowShapeOf, rowsOfEntity, TEXT_CHARS } from "./compact.js";
 import { environmentOf, setExitCode } from "./context.js";
+import { largeAnswerSteps, SOFT_OUTPUT_BYTES } from "./output-budget.js";
 import { withoutProviderRefs } from "./provider-refs.js";
 import { nextStep, rootOf, runnable, stepLine, withLines, withSafety } from "./steps.js";
 /** Every answer: a list or one thing, with items of `item` — any value where the command declares no entity. */
@@ -131,6 +132,16 @@ export const sealed = (value) => {
 };
 /** The steps a compact answer prints, each rerunning in the compact form the caller chose. */
 const compactSteps = (root, steps) => steps.map((step) => step.kind === "command" ? { ...step, line: `${step.line ?? stepLine(root, step)} ${COMPACT_FLAG}` } : step);
+/** A JSON answer past the soft budget, printed whole, with one more step: the same read in the compact form. */
+const withLargeAnswerStep = (command, body) => {
+    if ((body.next?.length ?? 0) >= MAX_NEXT_STEPS)
+        return body;
+    const added = largeAnswerSteps(command);
+    if (added.length === 0 || Buffer.byteLength(JSON.stringify(body)) <= SOFT_OUTPUT_BYTES)
+        return body;
+    const root = rootOf(command);
+    return { ...body, next: [...(body.next ?? []), ...withLines(root, runnable(root, added))] };
+};
 /** An answer as JSON lines: one line per item, then the end line. One thing is a list of one that has no more. */
 const linesOf = (body) => jsonlOf("items" in body ? body : { items: [body.item], page: { mode: "page", limit: 1, has_more: false }, meta: body.meta });
 /** An answer as JSON-lines records, for a writer that streams objects: one per item, then the end record. */
@@ -151,9 +162,10 @@ export const renderAnswer = (command, { renderer, format, streams, compact, full
     const kept = withoutProviderRefs({ ...body, ...(next.length > 0 ? { next } : {}) });
     if (next.length === 0)
         delete kept.next;
-    const whole = sealed(kept);
+    const sealedBody = sealed(kept);
     const environment = environmentOf(command);
     const drawn = compact && !environment.agent;
+    const whole = format === "json" && !drawn && !environment.agent ? withLargeAnswerStep(command, sealedBody) : sealedBody;
     if (drawn) {
         const lined = whole.next ? { ...whole, next: compactSteps(root, whole.next) } : whole;
         const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

package/dist/cli/execution.js

@@ -116,6 +116,7 @@ export const execution = (streams, { timeoutMs, fields, maxOutputBytes = DEFAULT
                         reason: "output.too-large",
                         max_bytes: maxOutputBytes,
                         emitted_bytes: bytes,
+                        needed_bytes: bytes + size,
                         partial_output: bytes > 0,
                     });
                 bytes += size;

package/dist/cli/index.d.ts

@@ -26,7 +26,7 @@ export { type CacheEvent, type DiagnosticEvent, type EventSink, providerErrorKey
 export { CORE_LOG_EVENTS } from "../runs/log-events.js";
 export { openProviderLog, PROVIDER_LOG_BYTES, type ProviderWarnings, providerLogPathFor, providerWarnings, writeProviderWarning, } from "../runs/provider-log.js";
 export { crashOf, type Recording, type RecordingOptions, recorded, startRecording, wasSettled, } from "../runs/recording.js";
-export { findRun, KEEP_RUNS_FOR_DAYS, listRuns, pruneRuns, type RunContext, type RunMetadata, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
+export { findRun, KEEP_RUNS_FOR_DAYS, KEEP_SUCCESSFUL_RUNS_FOR_DAYS, listRuns, pruneRuns, RUNS_SIZE_LIMIT_MB, type RunContext, type RunMetadata, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
 export { runContextOf, secretInput } from "../runs/run-context.js";
 export { type Attempt, currentAttempt, currentRun, inRun, type RunScope, runEvent, useAsProcessRun, withAttempt, } from "../runs/scope.js";
 export { LANGUAGES } from "../search/languages.js";
@@ -119,6 +119,7 @@ export { type ProjectStatusHints, type ProjectStatusItem, projectStatusAnswer, p
 export { STATUS_ROWS, STATUS_SIGNAL_ROWS } from "./project-status-rows.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export type { ScheduleHost } from "./schedule/schedule-command.js";
+export { type DeclaredSetting, type SettingRow, settingRows, withSettingDefaults } from "./setting-defaults.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, namedProfile, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
 export { type PermissionAnswer, readSetupAnswers, type SetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";

package/dist/cli/index.js

@@ -22,7 +22,7 @@ export { providerErrorKey, renderEvent, } from "../runs/events.js";
 export { CORE_LOG_EVENTS } from "../runs/log-events.js";
 export { openProviderLog, PROVIDER_LOG_BYTES, providerLogPathFor, providerWarnings, writeProviderWarning, } from "../runs/provider-log.js";
 export { crashOf, recorded, startRecording, wasSettled, } from "../runs/recording.js";
-export { findRun, KEEP_RUNS_FOR_DAYS, listRuns, pruneRuns, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
+export { findRun, KEEP_RUNS_FOR_DAYS, KEEP_SUCCESSFUL_RUNS_FOR_DAYS, listRuns, pruneRuns, RUNS_SIZE_LIMIT_MB, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
 export { runContextOf, secretInput } from "../runs/run-context.js";
 export { currentAttempt, currentRun, inRun, runEvent, useAsProcessRun, withAttempt, } from "../runs/scope.js";
 export { LANGUAGES } from "../search/languages.js";
@@ -108,6 +108,7 @@ export { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWind
 export { projectStatusAnswer, projectStatusRow, projectStatusSchema, projectStatusText, } from "./project-status.js";
 export { STATUS_ROWS, STATUS_SIGNAL_ROWS } from "./project-status-rows.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
+export { settingRows, withSettingDefaults } from "./setting-defaults.js";
 export { count, first, flag, fromFile, NONE_NAMED, namedProfile, plain, settingsFor, } from "./settings.js";
 export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";

package/dist/cli/messenger/reply-stats-command.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const replyResponsesCommand: (messenger: Messenger) => Command;
+export declare const replyWaitingCommand: (messenger: Messenger) => Command;

package/dist/cli/messenger/reply-stats-command.js

@@ -0,0 +1,57 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command, Option } from "commander";
+import { LOCAL_READ } from "../effects.js";
+import { renderAnswer } from "../envelope.js";
+import { messengerContext } from "./context.js";
+import { refuseJsonl, responsesAnswer, waitingAnswer } from "./stats-answers.js";
+const QUERY = "date:, chat: and kind: terms, AND-ed — date>=30d, date:[60d TO 30d]; none reads all time";
+const GUIDE = "Guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/rankings.md#reply-times-and-chats-waiting-on-you";
+const minutes = (ms) => (ms === null ? "—" : `${Math.round(ms / 60_000)} min`);
+export const replyResponsesCommand = (messenger) => annotate(new Command("responses"), { effects: LOCAL_READ, output: { entity: "response_times" } })
+    .summary("how fast replies come in one-to-one chats: median, p90, mean and buckets")
+    .description("how long the owner took to answer (--who me), or the other side took to answer the owner (--who others), in " +
+    "one-to-one chats — the local store only. Several messages in a row followed by one answer count as one " +
+    "reply, timed from the first unanswered message; the day of a row is the day of the reply")
+    .argument("[query...]", QUERY)
+    .addOption(new Option("--who <side>", "whose replies: the owner's or the other side's").choices(["me", "others"]))
+    .addOption(new Option("--by <group>", "one row per calendar day of the reply, or none").choices(["day", "total"]))
+    .option("--timezone <zone>", "the IANA timezone for calendar days and date: bounds")
+    .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all")
+    .addHelpText("after", GUIDE)
+    .action(async function (words) {
+    const context = messengerContext(this, messenger);
+    refuseJsonl(context.format);
+    const { who, by, timezone, source } = this.opts();
+    const found = await context.withServices((services) => services.replyStats.responses({
+        who: who ?? "me",
+        by: by ?? "total",
+        ...(words.length ? { text: words.join(" ") } : {}),
+        ...(timezone === undefined ? {} : { timezone }),
+        ...(source === undefined ? {} : { source }),
+    }));
+    renderAnswer(this, context, responsesAnswer(found), () => [
+        `${found.replies} replies · median ${minutes(found.medianMs)} · p90 ${minutes(found.p90Ms)} · mean ${minutes(found.meanMs)}`,
+        ...found.rows.map((row) => `${row.key}  ${row.replies} replies · median ${minutes(row.medianMs)}`),
+        "",
+    ].join("\n"));
+});
+export const replyWaitingCommand = (messenger) => annotate(new Command("waiting"), { effects: LOCAL_READ, output: { entity: "waiting_chats" } })
+    .summary("chats whose newest message asks the owner something")
+    .description("how many chats wait on the owner — the local store only: a one-to-one chat whose newest message is a " +
+    "question, or a group whose newest message mentions the owner or replies to them. Muted or archived " +
+    "one-to-one chats are left out, as inbox leaves them out; date: bounds the newest message's time")
+    .argument("[query...]", QUERY)
+    .option("--timezone <zone>", "the IANA timezone for date: bounds")
+    .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all")
+    .addHelpText("after", GUIDE)
+    .action(async function (words) {
+    const context = messengerContext(this, messenger);
+    refuseJsonl(context.format);
+    const { timezone, source } = this.opts();
+    const found = await context.withServices((services) => services.replyStats.waiting({
+        ...(words.length ? { text: words.join(" ") } : {}),
+        ...(timezone === undefined ? {} : { timezone }),
+        ...(source === undefined ? {} : { source }),
+    }));
+    renderAnswer(this, context, waitingAnswer(found), () => `${found.chats} chats wait on you (${found.byKind.private} one-to-one, ${found.byKind.group} groups) · ${found.messages} messages${found.oldestAt ? ` · oldest ${found.oldestAt}` : ""}\n`);
+});

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

@@ -5,6 +5,7 @@ import { SAVE_HELP } from "../../meetings/index.js";
 import { searchNotesOf } from "../../services/notes-search.js";
 import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
+import { withOptionHints } from "../option-hints.js";
 import { positiveCount } from "../paging.js";
 import { runsSearchCommand } from "../runs/search-command.js";
 import { commandAt } from "../steps.js";
@@ -193,5 +194,12 @@ export const searchCommand = (messenger, { topics = false } = {}) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal search ${path} ${args}`] });
     }
+    for (const path of ["all", "messages"]) {
+        const command = commandAt(search, path);
+        if (command)
+            withOptionHints(command, {
+                "--chat": `search in one chat with chat:<chat> in the query: search ${path} 'chat:<chat> words'`,
+            });
+    }
     return search;
 };

package/dist/cli/messenger/stats-answers.d.ts

@@ -8,6 +8,7 @@ import type { AdminEvidenceFound, AdminFound } from "../../services/admin-statis
 import type { ChatStats } from "../../services/chat-stats.js";
 import type { MessageStats } from "../../services/messages-search.js";
 import type { RankingFound } from "../../services/rankings.js";
+import type { ReplyTimes, Waiting } from "../../services/reply-stats.js";
 import type { RetentionService } from "../../services/retention.js";
 import type { AccountKey, RankedEvidence } from "../../store/store.js";
 import type { GroupStats } from "../../tasks/index.js";
@@ -72,4 +73,6 @@ export declare const chatStatsAnswer: (stats: ChatStats, account: AccountKey, me
 export declare const MEMBERS_UNRECORDED = "joins and leaves are not recorded for this chat yet, so they are not counted";
 /** `stats tasks show`, CLI and MCP alike. */
 export declare const taskStatsAnswer: (rows: GroupStats[], account: AccountKey) => ItemBody<Of<"task_stats">>;
+export declare const responsesAnswer: (found: ReplyTimes) => ItemBody<Of<"response_times">>;
+export declare const waitingAnswer: (found: Waiting) => ItemBody<Of<"waiting_chats">>;
 export {};

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

@@ -420,3 +420,21 @@ export const taskStatsAnswer = (rows, account) => itemOf({
         median_close_ms: row.medianCloseMs ?? null,
     })),
 });
+const replyFigures = (one) => ({
+    replies: one.replies,
+    median_ms: one.medianMs,
+    p90_ms: one.p90Ms,
+    mean_ms: one.meanMs,
+});
+export const responsesAnswer = (found) => itemOf({
+    who: found.who,
+    ...replyFigures(found),
+    buckets: {
+        under_5m: found.buckets.under5m,
+        under_1h: found.buckets.under1h,
+        under_1d: found.buckets.under1d,
+        over_1d: found.buckets.over1d,
+    },
+    rows: found.rows.map((row) => ({ key: row.key, ...replyFigures(row) })),
+});
+export const waitingAnswer = (found) => itemOf({ chats: found.chats, messages: found.messages, oldest_at: found.oldestAt, by_kind: found.byKind });

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

@@ -20,6 +20,7 @@ import { countersCommand } from "./counters-command.js";
 import { messagesStatsCommand } from "./messages-stats-command.js";
 import { officialStatsCommand } from "./official-stats-command.js";
 import { rankingEvidenceCommand, rankingsTopCommand } from "./rankings-command.js";
+import { replyResponsesCommand, replyWaitingCommand } from "./reply-stats-command.js";
 import { retentionCommand } from "./retention-command.js";
 import { chartAnswer, refuseJsonl } from "./stats-answers.js";
 import { tasksStatsCommand } from "./tasks-command.js";
@@ -31,6 +32,8 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         .addCommand(countersCommand(messenger))
         .addCommand(adminStatisticsCommand(messenger, "unanswered"))
         .addCommand(adminStatisticsCommand(messenger, "discussion"))
+        .addCommand(replyResponsesCommand(messenger))
+        .addCommand(replyWaitingCommand(messenger))
         .addCommand(rankingsTopCommand(messenger, "messages"))
         .addCommand(rankingEvidenceCommand(messenger, "messages")));
     stats.addCommand(new Command("contacts")
@@ -96,10 +99,12 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         "messages counters sync": '--chat "Book club" --dry-run',
         "messages counters show": '--chat "Book club" --limit 10',
         "messages discussion": 'chat:"Book club"',
+        "messages responses": "--who me --by day --timezone Europe/Madrid -- date>=30d",
         "messages evidence": '"$message" --selection "$selection" --component reactions',
         "messages show": '--chat "Book club" --by day',
         "messages top": 'chat:"Book club" --limit 10',
         "messages unanswered": 'chat:"Project room"',
+        "messages waiting": "kind:private",
         "tasks show": '--chat "Project room"',
     };
     for (const [path, args] of Object.entries(examples)) {

package/dist/cli/output-budget.d.ts

@@ -0,0 +1,26 @@
+import type { NextStep } from "@wirecat/cli-base/standards";
+import type { Command } from "commander";
+/** About a third of a 200k-token context at ~3 bytes per token (inferred, not measured). */
+export declare const SOFT_OUTPUT_BYTES: number;
+/** The same read in a form that fits the cap: one line per item, then a `--limit` scaled down to fit (WC-OUT-22). */
+export declare const tooLargeSteps: (command: Command, { maxBytes, neededBytes }: {
+    maxBytes: number;
+    neededBytes: number;
+}) => ({
+    kind: "command";
+    step: string;
+    command: string;
+    args: {
+        [x: string]: unknown;
+    };
+    line?: string | undefined;
+    why: string;
+    safe_to_auto_execute: boolean;
+} | {
+    kind: "user_action";
+    step: string;
+    why: string;
+    safe_to_auto_execute: false;
+})[];
+/** The step a large JSON answer adds: the same read, one line per item. */
+export declare const largeAnswerSteps: (command: Command) => NextStep[];

package/dist/cli/output-budget.js

@@ -0,0 +1,73 @@
+import { entityRows, GENERIC_ROW, rowShapeOf } from "./compact.js";
+import { environmentOf } from "./context.js";
+import { rootOf } from "./steps.js";
+/** About a third of a 200k-token context at ~3 bytes per token (inferred, not measured). */
+export const SOFT_OUTPUT_BYTES = 256 * 1024;
+const CARRIED = ["json", "compact", "offline", "timeout", "full", "brief", "maxOutputBytes"];
+const NOT_WITH_COMPACT = new Set(["json", "brief"]);
+const snake = (name) => name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+const typed = (command, key) => command.getOptionValueSource(key) === "cli";
+/**
+ * The words the caller typed, as step arguments: never a default, never text an answer carried (WC-OUT-9). A
+ * `--no-x` flag and `--json=<fields>` have no form a step can carry, so a line holding one gets no step.
+ */
+const typedArgs = (command) => {
+    const root = rootOf(command);
+    if (root.getOptionValue("fields") !== undefined)
+        return undefined;
+    if (command.options.some((option) => option.negate && typed(command, option.attributeName())))
+        return undefined;
+    const positional = command.registeredArguments.flatMap((argument, index) => {
+        const value = command.processedArgs[index];
+        const word = Array.isArray(value) ? value.join(" ") : value;
+        return word === undefined || word === "" ? [] : [[argument.name(), word]];
+    });
+    const own = command.options
+        .map((option) => option.attributeName())
+        .filter((key) => typed(command, key))
+        .map((key) => [snake(key), command.getOptionValue(key)]);
+    const global = CARRIED.filter((key) => typed(root, key)).map((key) => [snake(key), root.getOptionValue(key)]);
+    return Object.fromEntries([...positional, ...own, ...global]);
+};
+const declaresRow = (command) => {
+    const { rows } = environmentOf(command);
+    return rowShapeOf(command, rows && entityRows(rows)) !== GENERIC_ROW;
+};
+const pathOf = (command) => {
+    const words = [];
+    for (let at = command; at.parent; at = at.parent)
+        words.unshift(at.name());
+    return words.join(" ");
+};
+const step = (command, id, args, why) => ({
+    kind: "command",
+    step: id,
+    command: pathOf(command),
+    args,
+    why,
+    safe_to_auto_execute: true,
+});
+const compactStep = (command, args, why) => rootOf(command).getOptionValue("compact") === true || !declaresRow(command)
+    ? []
+    : [
+        step(command, "output.compact", { ...Object.fromEntries(Object.entries(args).filter(([key]) => !NOT_WITH_COMPACT.has(key))), compact: true }, why),
+    ];
+/** The same read in a form that fits the cap: one line per item, then a `--limit` scaled down to fit (WC-OUT-22). */
+export const tooLargeSteps = (command, { maxBytes, neededBytes }) => {
+    const args = typedArgs(command);
+    if (!args)
+        return [];
+    const limit = Number(command.getOptionValue("limit"));
+    const fits = Math.floor(((limit * maxBytes) / neededBytes) * 0.9);
+    return [
+        ...compactStep(command, args, "the answer is over the output cap as JSON; one line per item keeps every ref"),
+        ...(Number.isSafeInteger(limit) && fits >= 1 && fits < limit
+            ? [step(command, "output.limit", { ...args, limit: fits }, `about ${fits} items fit under the output cap`)]
+            : []),
+    ];
+};
+/** The step a large JSON answer adds: the same read, one line per item. */
+export const largeAnswerSteps = (command) => {
+    const args = typedArgs(command);
+    return args ? compactStep(command, args, "the answer is large as JSON; one line per item keeps every ref") : [];
+};

package/dist/cli/program.js

@@ -29,6 +29,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 { tooLargeSteps } from "./output-budget.js";
 import { PreviewComplete, preview } from "./preview.js";
 import { commandWords, isProfileName, liftProfile, sampleCommand, takesProfile, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
@@ -705,6 +706,15 @@ const commandPath = (program, rest) => {
     }
     return words.join(" ");
 };
+const budgetSteps = (program, path, failure) => {
+    const command = path ? commandAt(program, path) : undefined;
+    if (!command || !(failure instanceof CliError) || failure.details?.reason !== "output.too-large")
+        return [];
+    const { max_bytes: maxBytes, needed_bytes: neededBytes } = failure.details;
+    return typeof maxBytes === "number" && typeof neededBytes === "number"
+        ? tooLargeSteps(command, { maxBytes, neededBytes })
+        : [];
+};
 const failed = ({ app }, program, rest, error, settled, debug) => {
     const path = commandPath(program, program.args.length > 0 ? program.args : rest);
     const told = error instanceof NoProfileHere && !commandAt(program, "setup") ? error.withoutSetup(path) : error;
@@ -718,7 +728,10 @@ const failed = ({ app }, program, rest, error, settled, debug) => {
         ...(effects ? { effects } : {}),
     });
     const { next: _named, ...said } = built.error;
-    const steps = failureSteps(program, built.error);
+    const steps = failureSteps(program, {
+        ...built.error,
+        next: [...(built.error.next ?? []), ...budgetSteps(program, path, failure)],
+    });
     const object = { ...built, error: { ...said, ...(steps.length > 0 ? { next: steps } : {}) } };
     showInputFields(object, (path && commandAt(program, path)) || program);
     const command = path || app.command;

package/dist/cli/setting-defaults.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A scalar setting a CLI writes into its config file with its default, so the owner finds and edits it there without
+ * reading the docs (WC-CMD-30). Never declare a secret: `config show` prints every declared value.
+ */
+export interface DeclaredSetting {
+    /** The dotted path in the file. A nested setting is written only where its section already exists. */
+    key: string;
+    default: string | number | boolean;
+    description: string;
+}
+export interface SettingRow {
+    setting: string;
+    value: unknown;
+    default: string | number | boolean;
+    from: "config file" | "default";
+    description: string;
+}
+/**
+ * The file with every declared setting it lacks, at its default. What the owner wrote stays as written, in its order,
+ * unknown keys included; a section that is not there is not created, since it may need fields no default can give.
+ */
+export declare const withSettingDefaults: (raw: unknown, declared: readonly DeclaredSetting[]) => {
+    config: unknown;
+    added: string[];
+};
+/** Every declared setting with what holds and whether the file says it, for `config show`. */
+export declare const settingRows: (raw: unknown, declared: readonly DeclaredSetting[]) => SettingRow[];

package/dist/cli/setting-defaults.js

@@ -0,0 +1,36 @@
+const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parentOf = (config, key) => {
+    const path = key.split(".");
+    const leaf = path.pop();
+    return { node: path.reduce((node, part) => (isNode(node) ? node[part] : undefined), config), leaf };
+};
+/**
+ * The file with every declared setting it lacks, at its default. What the owner wrote stays as written, in its order,
+ * unknown keys included; a section that is not there is not created, since it may need fields no default can give.
+ */
+export const withSettingDefaults = (raw, declared) => {
+    if (raw !== undefined && !isNode(raw))
+        return { config: raw, added: [] };
+    const config = raw === undefined ? {} : structuredClone(raw);
+    const added = [];
+    for (const setting of declared) {
+        const { node, leaf } = parentOf(config, setting.key);
+        if (!isNode(node) || Object.hasOwn(node, leaf))
+            continue;
+        node[leaf] = setting.default;
+        added.push(setting.key);
+    }
+    return { config, added };
+};
+/** Every declared setting with what holds and whether the file says it, for `config show`. */
+export const settingRows = (raw, declared) => declared.map((setting) => {
+    const { node, leaf } = isNode(raw) ? parentOf(raw, setting.key) : { node: undefined, leaf: "" };
+    const written = isNode(node) && Object.hasOwn(node, leaf);
+    return {
+        setting: setting.key,
+        value: written ? node[leaf] : setting.default,
+        default: setting.default,
+        from: written ? "config file" : "default",
+        description: setting.description,
+    };
+});

package/dist/cli/settings.d.ts

@@ -7,6 +7,7 @@ import { type Level, type PermissionKey } from "../sends/permissions.js";
 import { type HistoryLimits } from "../services/history-limits.js";
 import { type ConfigIssue } from "./config-issues.js";
 import type { CommandPermissions } from "./permission-keys.js";
+import { type DeclaredSetting } from "./setting-defaults.js";
 export declare const plain: (rule: string) => (issue: v.BaseIssue<unknown>) => string;
 export declare const count: v.SchemaWithPipe<readonly [v.NumberSchema<(issue: v.BaseIssue<unknown>) => string>, v.IntegerAction<number, (issue: v.BaseIssue<unknown>) => string>, v.MinValueAction<number, 1, (issue: v.BaseIssue<unknown>) => string>]>;
 export declare const flag: v.BooleanSchema<(issue: v.BaseIssue<unknown>) => string>;
@@ -32,6 +33,8 @@ export interface SettingsExtension<T extends object = Record<never, never>> {
     profile?: v.ObjectEntries;
     /** For the whole program only, never per profile. */
     defaults?: v.ObjectEntries;
+    /** Its own scalar settings, written into the file's `defaults` beside the shared ones (WC-CMD-30). */
+    settings?: readonly DeclaredSetting[];
     /** Profiles this messenger keeps in files of its own, beyond the config file and the remembered accounts. */
     profiles?: (env: NodeJS.ProcessEnv) => string[];
     /**
@@ -229,6 +232,8 @@ export declare const settingsFor: <T extends object = Record<never, never>>(app:
         kind?: ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: v.StrictObjectSchema<{