@wirecat/cli-core 0.529.0 → 0.531.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.531.0 — 01.11.2026
+
+### Added
+
+- **`topics create --emoji` and `topics edit --emoji`: a forum topic's icon.** The value is an emoji from the
+  messenger's topic icon set, which `topics icons list` shows; `topics edit --emoji none` removes the icon. An emoji
+  change is journaled as `topic-edit`. Adapters take it as `createTopic(…, { icon })` and `TopicChange.icon`
+  (`null` removes it), and list the set with the optional `TopicEditing.topicIcons()`; the `topic_icon` entity is the
+  list's item.
+- **`tasks.edit(id, { project })` moves a project task to another of the owner's projects.** It takes the next key
+  there; `id`, `ref` and `key` change, and the old key still finds the task through a `project` event in its
+  history. The source project's numbers are never reused. A subtask leaves its parent; a
+  task with subtasks is refused (`task.has-subtasks`, with their keys). The revision goes up.
+- **`tasks.edit(id, { type })` changes a project task's kind** among bug, feature and chore, as a `type` event, and
+  bumps the revision.
+- **A task names who added it**: `TaskDetails.createdBy` (`created_by` in the `task` and `task_card` entities),
+  `{ type, id, name, owner }`. `tasksService.add` takes an `author`, so a task found in a message by a named agent is
+  that agent's, not `agent`'s.
+- **Task comments**: `tasks.comment(id, text, by)` keeps a note about the task in its author's name; `tasks.comments`
+  lists them oldest first with `author`, `text` and `at`. A comment leaves the revision as it is.
+- **`tomorrow` in any time field of a list query** (`due:tomorrow`, `due:[today TO tomorrow]`), as the owner's next
+  calendar day: `listQuery` reads it before validating. `today` and `yesterday` already worked.
+- **`mailAccountKey(address)`** from `./mail`: the store key of a mail account, `{ provider: "email", account }` with
+  the address in lower case. **`positiveCount(flag)`** from `./cli`: the parser of a whole-number flag from 1 up.
+- **The shared `schedule` command lives in `src/cli/schedule/`**, not under the messenger commands. `scheduleCommandFor`
+  and `ScheduleHost` come from `./cli` as before; the old module path re-exports them. Each `schedule` command now
+  has examples and described arguments, and the example profile of the shared mail read commands is `personal`.
+
+### Fixed
+
+- **`schedule command` and `schedule agent` refuse a name that another profile already uses**, rather than replacing
+  its schedule and timer. Schedules of the same profile are still replaced. Existing timers keep their names.
+
+## 0.530.0 — 01.11.2026
+
+### Added
+
+- **`configCommand(app, config, { ownerOnly })`**: settings and permission keys an agent with `mcp.authority` still
+  cannot change over MCP, beside `mcp.*` and `bot.api` — for a mail CLI, the server hosts its password goes to, and
+  the key that lets an agent mail other people. A permission key there covers the keys under it.
+- **`safeName` from `./files`**: the file-name cleaner downloads use (no path, no leading dot, no control or direction
+  character; Windows' reserved names refused), for a CLI that saves a file someone else named.
+
 ## 0.529.0 — 01.11.2026
 
 ### Added

package/dist/cli/config-command.d.ts

@@ -6,8 +6,18 @@ import { type Configuration } from "./settings.js";
  * The settings in force and where each came from, and changing them. Printed whole: no field the
  * configuration accepts can hold a secret — the schema has nowhere to put one.
  */
-export declare const configCommand: (app: AppIdentity, config: Configuration, { permissionKey }?: {
+/**
+ * Settings and permission keys an agent with `mcp.authority` still may not change, beyond the ones that let it in:
+ * where the password goes (a server host), or a permission the app reads only from the owner's file.
+ */
+export interface OwnerOnlySettings {
+    settings?: readonly string[];
+    /** A key here covers the keys under it too: `messages.send.others` covers `messages.send.others.x`. */
+    permissions?: readonly string[];
+}
+export declare const configCommand: (app: AppIdentity, config: Configuration, { permissionKey, ownerOnly, }?: {
     permissionKey?: PermissionKeySource | undefined;
+    ownerOnly?: OwnerOnlySettings;
 }) => Command;
 /**
  * A key no command or write is checked against would be saved and do nothing (BUG-137) — whether it

package/dist/cli/config-command.js

@@ -10,11 +10,7 @@ import { knownBeside, knownPermissionKeys, unknownPermissionIssues, } from "./pe
 import { fromFile, NONE_NAMED } from "./settings.js";
 import { nextStep } from "./steps.js";
 import { changeStoreSetting, isStoreSetting, offersStoreSetting, storeSettings, storeSettingsOf, } from "./store-settings.js";
-/**
- * The settings in force and where each came from, and changing them. Printed whole: no field the
- * configuration accepts can hold a secret — the schema has nowhere to put one.
- */
-export const configCommand = (app, config, { permissionKey = config.permissions } = {}) => {
+export const configCommand = (app, config, { permissionKey = config.permissions, ownerOnly = {}, } = {}) => {
     const command = new Command("config").description("the settings in force, and where each one came from");
     // Only a messenger has bots, and with them the personal and bot sections of the file. Elsewhere the options stay
     // accepted, so a script that passes one still runs, but help, `commands --json` and MCP leave them out.
@@ -120,7 +116,7 @@ export const configCommand = (app, config, { permissionKey = config.permissions
                 throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${root ? setting : "--defaults"} changes other profiles`);
             }
             if (environmentOf(this).agent)
-                refuseGuardedKey(setting, action === "set" ? String(given) : undefined);
+                refuseGuardedKey(setting, action === "set" ? String(given) : undefined, ownerOnly);
             if (action === "set")
                 refuseUnknownKey(this, setting, String(given), permissionKey);
             const saved = config.changeSetting(settings.configPath, {
@@ -166,7 +162,11 @@ export const refuseUnknownKey = (command, setting, value, permissionKey) => {
  * profile, in the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off
  * (NEED-1662, NEED-1679).
  */
-const refuseGuardedKey = (setting, value) => {
+const refuseGuardedKey = (setting, value, ownerOnly) => {
+    if (ownerOnly.settings?.includes(setting))
+        throw new CliError("permission_error", `an agent cannot change ${setting} — the owner sets it in a terminal`, {
+            setting,
+        });
     const keys = setting.startsWith("permissions.")
         ? [setting.slice("permissions.".length)]
         : setting === "permissions"
@@ -174,11 +174,13 @@ const refuseGuardedKey = (setting, value) => {
                 ? ["mcp"]
                 : objectKeys(value)
             : [];
-    const guarded = keys.some((key) => key === BOT_API_KEY || key.startsWith(`${BOT_API_KEY}.`))
+    const under = (key, guarded) => key === guarded || key.startsWith(`${guarded}.`);
+    const listed = keys.flatMap((key) => (ownerOnly.permissions ?? []).filter((guarded) => under(key, guarded)));
+    const guarded = keys.some((key) => under(key, BOT_API_KEY))
         ? BOT_API_KEY
-        : keys.some((key) => key === "mcp" || key.startsWith("mcp."))
+        : keys.some((key) => under(key, "mcp"))
             ? AUTHORITY_KEY
-            : undefined;
+            : listed[0];
     if (!guarded)
         return;
     throw new CliError("permission_error", `an agent cannot change permissions.${guarded} — the owner sets it in a terminal`, { permission: guarded });

package/dist/cli/index.d.ts

@@ -97,7 +97,6 @@ export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from ".
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export type { ScheduleHost } from "./messenger/schedule-command.js";
 export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
@@ -108,12 +107,13 @@ export { storeSummary } from "./messenger/store-maintenance-command.js";
 export { type Saving, stored } from "./messenger/stored.js";
 export { dateOrNone } from "./messenger/tasks-command.js";
 export { MODEL_CATALOGUE_QUERY, type ModelCatalogueOptions } from "./model-catalogue-command.js";
-export { window, withPaging } from "./paging.js";
+export { positiveCount, window, withPaging } from "./paging.js";
 export { type CommandPermissions, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOptions, run } from "./program.js";
 export { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } from "./project-evidence.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
+export type { ScheduleHost } from "./schedule/schedule-command.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

@@ -97,7 +97,7 @@ export { storeSummary } from "./messenger/store-maintenance-command.js";
 export { stored } from "./messenger/stored.js";
 export { dateOrNone } from "./messenger/tasks-command.js";
 export { MODEL_CATALOGUE_QUERY } from "./model-catalogue-command.js";
-export { window, withPaging } from "./paging.js";
+export { positiveCount, window, withPaging } from "./paging.js";
 export { commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, run } from "./program.js";

package/dist/cli/list-query.d.ts

@@ -16,10 +16,6 @@ export declare const withQuery: (command: Command, registry: QueryRegistry) => C
 export declare const unfilteredQuery: (entity: string, schema: Parameters<typeof queryFieldsOf>[0]) => QueryRegistry;
 /** `tasks list`, as a query error names the command. */
 export declare const commandPath: (command: Command) => string;
-/**
- * The query as typed, validated against the list's fields, with each default whose field it does not name;
- * `undefined` when nothing narrows the list. A bare word is refused unless the list names a `defaultField` for it. CLI and MCP read a list's query through this one function.
- */
 export declare const listQuery: (text: string, registry: QueryRegistry, command: string, { defaultField }?: {
     defaultField?: string;
 }) => QueryAst | undefined;

package/dist/cli/list-query.js

@@ -39,9 +39,27 @@ export const commandPath = (command) => {
  * The query as typed, validated against the list's fields, with each default whose field it does not name;
  * `undefined` when nothing narrows the list. A bare word is refused unless the list names a `defaultField` for it. CLI and MCP read a list's query through this one function.
  */
+/**
+ * `tomorrow` in a time field as the owner's next calendar date: the query language knows `today` and `yesterday`
+ * only, and a due date is more often ahead than behind.
+ */
+const withTomorrow = (query, registry, zone = timezoneOf(), now = Date.now()) => {
+    const times = new Set(registry.fields.filter(({ type }) => type === "time").map(({ name }) => name));
+    const date = new Date(`${new Intl.DateTimeFormat("en-CA", { timeZone: zone }).format(now)}T00:00:00Z`);
+    date.setUTCDate(date.getUTCDate() + 1);
+    const tomorrow = date.toISOString().slice(0, 10);
+    const day = (value) => (value.toLowerCase() === "tomorrow" ? tomorrow : value);
+    const map = (node) => node.kind === "predicate"
+        ? times.has(node.field)
+            ? { ...node, value: day(node.value), ...(node.upper === undefined ? {} : { upper: day(node.upper) }) }
+            : node
+        : { ...node, clauses: node.clauses.map((clause) => ({ ...clause, node: map(clause.node) })) };
+    return { ...query, root: map(query.root) };
+};
 export const listQuery = (text, registry, command, { defaultField = "none" } = {}) => {
     const context = { command, guide: LIST_QUERY_GUIDE };
-    const typed = text.trim() === "" ? undefined : parseLucene(text, { defaultField, ...context });
+    const parsed = text.trim() === "" ? undefined : parseLucene(text, { defaultField, ...context });
+    const typed = parsed && withTomorrow(parsed, registry);
     if (typed)
         validateQuery(typed, registry, context);
     const named = typed ? fieldsNamed(typed) : new Set();

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

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import type { Id } from "../../domain/models.js";
-export { downloadMessage, type Saved, safeName, save } from "../../services/file-download.js";
+export { safeName } from "../../files/safe-name.js";
+export { downloadMessage, type Saved, save } from "../../services/file-download.js";
 import { type Messenger } from "./context.js";
 /** `messages download`: every file of one message, or with `--all` of a whole chat, never over a file already there. */
 export declare const downloadSubcommand: (messages: Command, messenger: Messenger) => Command;

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

@@ -7,7 +7,8 @@ import { NOT_FILES } from "../../domain/attachments.js";
 import { FETCHING, keyOf } from "../../services/archive.js";
 import { batchProgress, mergeBatches } from "../../services/batch.js";
 import { saveFiles } from "../../services/file-download.js";
-export { downloadMessage, safeName, save } from "../../services/file-download.js";
+export { safeName } from "../../files/safe-name.js";
+export { downloadMessage, save } from "../../services/file-download.js";
 import { parseDuration } from "../../domain/duration.js";
 import { OFFLINE } from "../../services/deps.js";
 import { patiently } from "../../services/patience.js";

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

@@ -1,21 +1,4 @@
-import { Command } from "commander";
-import { type AppIdentity } from "../../ports/app.js";
-import { type AnswerOutput } from "../envelope.js";
+import type { Command } from "commander";
 import { type Messenger } from "./context.js";
-/** What the schedule command needs of a CLI: who it is and, per command, where it prints and which profile runs. */
-export interface ScheduleHost {
-    app: AppIdentity;
-    context(command: Command, resolving?: {
-        needsProfile?: boolean;
-    }): AnswerOutput & {
-        env: NodeJS.ProcessEnv;
-        profile: string;
-    };
-}
-/**
- * Runs the CLI's own commands, or an agent, later or on a timer — through systemd (Linux), launchd
- * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
- * the rest, so what runs and with which variables is the same on all three.
- */
-export declare const scheduleCommandFor: ({ app, context: contextOf }: ScheduleHost) => Command;
+export { type ScheduleHost, scheduleCommandFor } from "../schedule/schedule-command.js";
 export declare const scheduleCommand: (messenger: Messenger) => Command;

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

@@ -1,235 +1,6 @@
-import { existsSync, rmSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { CliError, resolvePaths, writeSecurely } from "@wirecat/cli-base";
-import { annotate } from "@wirecat/cli-base/commands";
-import { Argument, Command, Option } from "commander";
-import { describeWhen, findProgram, lastRun, listSchedules, runSchedule, scheduleFile, scheduleName, timerFor, } from "../../background/schedules.js";
-import { thisMachine } from "../../background/system.js";
-import { locationVariables } from "../../background/units.js";
-import { parseDuration } from "../../domain/duration.js";
-import { readOnlyLockOf } from "../../ports/app.js";
-import { aheadOf } from "../../services/moment.js";
-import { storePath } from "../../store/path.js";
-import { environmentOf, setExitCode } from "../context.js";
-import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_WRITE } from "../effects.js";
-import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
-import { withQuery } from "../list-query.js";
-import { lineOf } from "../steps.js";
+import { scheduleCommandFor } from "../schedule/schedule-command.js";
 import { messengerContext } from "./context.js";
-import { SCHEDULES_QUERY, scheduleFilter } from "./list-result-queries.js";
-/** Each run of an agent is a paid model call that reads chats; keeping the store current is `serve`'s job. */
-const AGENT_MINIMUM_MINUTES = 60;
-const COMMAND_MINIMUM_MINUTES = 1;
-const HARNESSES = ["claude", "codex"];
-const whenOf = ({ every, at, atTime }, minimum) => {
-    if ([every ?? at, atTime].filter(Boolean).length !== 1) {
-        throw new CliError("validation_error", "say when: --every <30m|2h|1d>, --at HH:MM (daily), or --at-time <30m|2d|ISO time>");
-    }
-    if (atTime) {
-        const time = aheadOf(atTime, "--at-time");
-        if (time <= Date.now())
-            throw new CliError("validation_error", "--at-time is in the past");
-        return { once: new Date(time).toISOString() };
-    }
-    if (at) {
-        if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(at))
-            throw new CliError("validation_error", `--at takes HH:MM, not "${at}"`);
-        if (every && parseDuration(every, "--every") !== 86_400_000) {
-            throw new CliError("validation_error", "--at runs once a day; leave out --every, or use --every 1d");
-        }
-        return { daily: at };
-    }
-    const minutes = parseDuration(every ?? "", "--every") / 60_000;
-    if (!Number.isInteger(minutes) || minutes < minimum) {
-        throw new CliError("validation_error", `--every is at least ${minimum} minute${minimum === 1 ? "" : "s"} here, in whole minutes`);
-    }
-    return { every: minutes };
-};
-/** A schedule as answered: snake_case, but its environment keeps the variables' own names. */
-const scheduleAnswer = ({ environment, createdAt, ...schedule }, extra) => ({
-    ...snakeKeys(schedule),
-    environment,
-    created_at: createdAt,
-    ...snakeKeys(extra),
-});
-const withWhen = (command) => command
-    .option("--every <duration>", "repeat: 30m, 2h, 1d")
-    .option("--at <HH:MM>", "every day at this local time")
-    .option("--at-time <time>", "one run: 30m, 2d from now, or an ISO time; the schedule removes itself after it");
-/**
- * Runs the CLI's own commands, or an agent, later or on a timer — through systemd (Linux), launchd
- * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
- * the rest, so what runs and with which variables is the same on all three.
- */
-export const scheduleCommandFor = ({ app, context: contextOf }) => {
-    const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
-    const prepare = (self, resolving = {}) => {
-        const context = contextOf(self, resolving);
-        const system = environmentOf(self).system ?? thisMachine();
-        const state = resolvePaths({ appName: app.appName, prefix: app.envPrefix, env: context.env }).state;
-        const say = (value, lines) => renderAnswer(self, context, itemOf(value), () => lines.join("\n"));
-        const timer = () => timerFor(app, system, context.env);
-        // The command line refuses a schedule under the lock; a caller that gets here still passes the lock on.
-        const readOnly = readOnlyLockOf(app, context.env);
-        const environment = () => ({
-            [`${app.envPrefix}_PROFILE`]: context.profile,
-            ...locationVariables(app, context.env),
-            // The timer starts with almost no PATH; an agent runs `max` and its own tools by name.
-            ...(context.env.PATH ? { PATH: context.env.PATH } : {}),
-            ...(readOnly ? { [readOnly]: "1" } : {}),
-        });
-        const save = async (schedule) => {
-            const file = scheduleFile(state, schedule.name);
-            const replaced = existsSync(file);
-            writeSecurely(file, `${JSON.stringify(schedule, null, 2)}\n`, 0o600);
-            await timer().install(schedule, [...system.entry, "schedule", "exec", file]);
-            say(scheduleAnswer(schedule, { file, timer: timer().where(schedule.name), replaced }), [
-                `${replaced ? "Replaced" : "Added"} ${schedule.name}: ${describeWhen(schedule.when)}.`,
-                `It runs: ${schedule.kind === "agent" ? schedule.argv.join(" ") : `${app.command} ${schedule.argv.join(" ")}`}`,
-                `Output: ${join(dirname(file), "runs")} · now: ${lineOf(self, `schedule run ${schedule.name}`)} · stop: ${lineOf(self, `schedule remove ${schedule.name}`)}`,
-            ]);
-        };
-        return { context, system, state, say, timer, environment, save };
-    };
-    withWhen(grantsAuthority(annotate(command.command("command"), { effects: LOCAL_WRITE }))
-        .description(`run ${app.command} <args…> on a timer — reads save what they read, so this is how a chat's history fills the store`)
-        .argument("<name>", "lowercase letters, digits and dashes")
-        .argument("<args...>", `the ${app.command} command after its name, e.g. -- messages list <chat> --limit 50`)).action(async function (name, args) {
-        const { environment, save } = prepare(this);
-        if (args[0] === "schedule")
-            throw new CliError("validation_error", "a schedule cannot run schedule");
-        await save({
-            name: scheduleName(name),
-            kind: "command",
-            argv: args,
-            when: whenOf(this.opts(), COMMAND_MINIMUM_MINUTES),
-            environment: environment(),
-            createdAt: new Date().toISOString(),
-        });
-    });
-    withWhen(grantsAuthority(annotate(command.command("agent"), { effects: LOCAL_WRITE }))
-        .description(`start an agent (claude or codex) with a prompt on a timer; it runs with ${app.envPrefix}_READ_ONLY=1, so it reads and drafts and cannot send — its answer is kept and you are notified`)
-        .argument("<name>", "lowercase letters, digits and dashes")
-        .addArgument(new Argument("<harness>", "the agent to start").choices(HARNESSES))
-        .argument("<prompt>", `what to do, e.g. "run the daily follow-up review: ${app.command} skill show follow-ups"`)
-        .addOption(new Option("--max-cost <usd>", "claude only: stop a run that costs more than this, in US dollars").argParser(Number))).action(async function (name, harness, prompt) {
-        const { context, system, environment, save } = prepare(this);
-        const options = this.opts();
-        const program = findProgram(harness, context.env, system.platform);
-        if (!program)
-            throw new CliError("not_found", `${harness} is not on PATH`);
-        const paths = resolvePaths({ appName: app.appName, prefix: app.envPrefix, env: context.env });
-        const argv = harness === "claude"
-            ? [
-                program,
-                "-p",
-                prompt,
-                // The owner's own settings may let every tool run (bypassPermissions); here only the CLI may.
-                "--permission-mode",
-                "dontAsk",
-                "--allowedTools",
-                `Bash(${app.command}:*)`,
-                "--no-session-persistence",
-                ...(options.maxCost ? ["--max-budget-usd", String(options.maxCost)] : []),
-            ]
-            : [
-                program,
-                "exec",
-                "--skip-git-repo-check",
-                "--ephemeral",
-                "--sandbox",
-                "workspace-write",
-                // The CLI reaches the messenger and writes its store and state, and nothing else.
-                "-c",
-                "sandbox_workspace_write.network_access=true",
-                ...[dirname(storePath(context.env)), paths.state, paths.config, paths.cache].flatMap((dir) => [
-                    "--add-dir",
-                    dir,
-                ]),
-                prompt,
-            ];
-        await save({
-            name: scheduleName(name),
-            kind: "agent",
-            argv,
-            when: whenOf(options, AGENT_MINIMUM_MINUTES),
-            environment: environment(),
-            createdAt: new Date().toISOString(),
-        });
-    });
-    withQuery(annotate(command.command("list"), { effects: LOCAL_READ }), SCHEDULES_QUERY)
-        .description("the schedules, when they run and how their last run went")
-        .action(function (words) {
-        const filter = scheduleFilter(words);
-        const { context, state } = prepare(this);
-        const rows = listSchedules(state, filter).map((schedule) => ({
-            name: schedule.name,
-            kind: schedule.kind,
-            when: describeWhen(schedule.when),
-            last: lastRun(scheduleFile(state, schedule.name)) ?? null,
-        }));
-        const answer = listOf("schedule list", {
-            items: rows.map((row) => snakeKeys(row)),
-            limit: Math.max(1, rows.length),
-            has_more: false,
-        });
-        renderAnswer(this, context, answer, () => {
-            if (rows.length === 0) {
-                context.renderer.note(`no schedules — \`${lineOf(this, "schedule command|agent")}\` adds one`);
-                return "";
-            }
-            return rows
-                .map(({ name, kind, when, last }) => [
-                name,
-                kind,
-                when,
-                last
-                    ? `last ${last.at.slice(0, 16).replace("T", " ")} exit ${last.exitCode}` +
-                        (last.failures
-                            ? ` — failing since ${(last.failingSince ?? last.at).slice(0, 16).replace("T", " ")}, ` +
-                                `${last.failures} in a row${last.reason ? `: ${last.reason}` : ""} — ${last.output}`
-                            : "")
-                    : "not run yet",
-            ].join("  "))
-                .join("\n");
-        });
-    });
-    annotate(command.command("run"), { effects: REMOTE_WRITE })
-        .description("run a schedule now, as its timer would, and wait for it")
-        .argument("<name>")
-        .action(async function (name) {
-        const { context, system, state, say, timer } = prepare(this);
-        const last = await runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
-            timer: timer(),
-        });
-        say(snakeKeys({ name, ...last }), [`${name}: exit ${last.exitCode} — ${last.output}`]);
-        if (last.exitCode !== 0)
-            setExitCode(this, 1);
-    });
-    grantsAuthority(annotate(command.command("remove"), { effects: LOCAL_WRITE }))
-        .description("stop a schedule and remove its timer; its past output stays")
-        .argument("<name>")
-        .action(async function (name) {
-        const { state, say, timer } = prepare(this);
-        const file = scheduleFile(state, scheduleName(name));
-        if (!existsSync(file))
-            throw new CliError("not_found", `no schedule ${name} — \`${lineOf(this, "schedule list")}\``);
-        await timer().remove(name);
-        rmSync(file, { force: true });
-        say({ name, removed: true }, [`Removed ${name}.`]);
-    });
-    annotate(command.command("exec"), { effects: REMOTE_WRITE })
-        .description("what a timer runs, given the schedule's file; to run one by hand, use run")
-        .argument("<file>")
-        .action(async function (file) {
-        // A timer starts it with no profile named; the schedule's own environment carries the profile.
-        const { context, system, timer } = prepare(this, { needsProfile: false });
-        const last = await runSchedule(app, system, context.env, file, { timer: timer() });
-        if (last.exitCode !== 0)
-            setExitCode(this, 1);
-    });
-    return command;
-};
+export { scheduleCommandFor } from "../schedule/schedule-command.js";
 export const scheduleCommand = (messenger) => scheduleCommandFor({
     app: messenger.app,
     context: (command, resolving) => messengerContext(command, messenger, resolving),

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

@@ -1,12 +1,13 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
+import { topicIcon } from "../../entities/index.js";
 import { capability } from "../../ports/messenger.js";
 import { ownerOnlyOption, REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
-import { typedQuery, withQuery } from "../list-query.js";
+import { listQuery, typedQuery, unfilteredQuery, withQuery } from "../list-query.js";
 import { window, withPaging } from "../paging.js";
-import { lines, pageOf, topicAnswer } from "./chat-answers.js";
+import { lines, pageOf, topicAnswer, wholeList } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
 import { TOPICS_QUERY, topicTitle } from "./list-result-queries.js";
 const listed = (messenger) => async function (chat, value) {
@@ -47,6 +48,17 @@ export const topicsCommand = (messenger) => {
             const shown = await context.withServices((services) => services.topics.show(chat, topic));
             renderAnswer(this, context, itemOf(topicAnswer(shown)));
         });
+    const icons = new Command("icons").description("the emojis a forum topic can take as its icon");
+    topics.addCommand(icons);
+    icons.addCommand(withQuery(annotate(new Command("list"), {
+        effects: REMOTE_READ,
+        examples: [`${messenger.app.command} personal topics icons list`],
+    }).description("the emojis `--emoji` takes in topics create and topics edit"), TOPIC_ICONS_QUERY).action(async function (words) {
+        const context = messengerContext(this, messenger);
+        listQuery(typedQuery(words), TOPIC_ICONS_QUERY, "topics icons list");
+        const icons = await context.withServices((services) => services.topics.icons());
+        renderAnswer(this, context, wholeList("topics icons list", icons.map((emoji) => ({ emoji }))), lines(({ emoji }) => emoji));
+    }));
     annotate(topics.command("enable"), { effects: REMOTE_WRITE })
         .description("enable forum topics; only the owner, with an explicit upgrade for a basic group")
         .argument("<chat>", messenger.chatArgument)
@@ -61,22 +73,25 @@ export const topicsCommand = (messenger) => {
         .argument("<chat>", messenger.chatArgument)
         .argument("<title>", "the topic title, at most 128 UTF-8 bytes")
         .option("--operation-id <id>", "identify this creation attempt; an already sent or unknown id is refused")
+        .option("--emoji <emoji>", "the topic's icon, one of `topics icons list`")
         .action(async function (chat, title) {
         const context = messengerContext(this, messenger);
-        const created = await context.withServices((services) => services.topics.create(chat, title, { sendId: this.opts().operationId }));
+        const { operationId, emoji } = this.opts();
+        const created = await context.withServices((services) => services.topics.create(chat, title, { sendId: operationId, ...(emoji === undefined ? {} : { icon: emoji }) }));
         renderAnswer(this, context, itemOf(snakeKeys(created)));
     });
     annotate(topics.command("edit"), { effects: REMOTE_WRITE })
-        .description("rename, close or reopen a forum topic")
+        .description("rename, close, reopen or give an icon to a forum topic")
         .argument("<chat>", messenger.chatArgument)
         .argument("<topic>", "the topic id, from `topics list`")
         .option("--title <title>", "the new title, at most 128 UTF-8 bytes")
         .option("--closed <on|off>", "on closes the topic to new messages, off reopens it")
         .option("--pinned <on|off>", "on pins the topic at the top of the list, off unpins it")
         .option("--hidden <on|off>", "on hides the General topic from the topic list, off shows it")
+        .option("--emoji <emoji>", "the topic's icon, one of `topics icons list`; none removes it")
         .action(async function (chat, topic) {
         const context = messengerContext(this, messenger);
-        const { title, closed, pinned, hidden } = this.opts();
+        const { title, closed, pinned, hidden, emoji } = this.opts();
         const closes = onOff("--closed", closed);
         const pins = onOff("--pinned", pinned);
         const hides = onOff("--hidden", hidden);
@@ -85,6 +100,7 @@ export const topicsCommand = (messenger) => {
             ...(closes === undefined ? {} : { closed: closes }),
             ...(pins === undefined ? {} : { pinned: pins }),
             ...(hides === undefined ? {} : { hidden: hides }),
+            ...(emoji === undefined ? {} : { icon: emoji === "none" ? null : emoji }),
         }));
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     });
@@ -107,6 +123,7 @@ export const topicsCommand = (messenger) => {
     });
     return topics;
 };
+const TOPIC_ICONS_QUERY = unfilteredQuery("topic_icon", topicIcon);
 const onOff = (flag, value) => {
     if (value === undefined)
         return undefined;

package/dist/cli/schedule/schedule-command.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { type AppIdentity } from "../../ports/app.js";
+import { type AnswerOutput } from "../envelope.js";
+/** What the schedule command needs of a CLI: who it is and, per command, where it prints and which profile runs. */
+export interface ScheduleHost {
+    app: AppIdentity;
+    context(command: Command, resolving?: {
+        needsProfile?: boolean;
+    }): AnswerOutput & {
+        env: NodeJS.ProcessEnv;
+        profile: string;
+    };
+}
+/**
+ * Runs the CLI's own commands, or an agent, later or on a timer — through systemd (Linux), launchd
+ * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
+ * the rest, so what runs and with which variables is the same on all three.
+ */
+export declare const scheduleCommandFor: ({ app, context: contextOf }: ScheduleHost) => Command;