@wirecat/cli-core 0.402.0 → 0.404.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ shape of this file.
 
 ## Unreleased
 
+## 0.404.0 — 24.10.2026
+
+### Added
+
+- **`setupPermissionCeiling(env)` and `CEILING_KEY`** let a tool that keeps its own permission levels (zm, drive, memo) honour the shared first-run "read only" answer: add the ceiling to its levels under `CEILING_KEY`, and `levelFor` caps every key.
+
+## 0.403.0 — 24.10.2026
+
+### Added
+
+- **`setupAtStart` runs the shared first-run questions for a tool with its own program** (zm, memo, drive): it asks only a person at a terminal, and the command runs whatever happens to the questions.
+
+- **The first command at a terminal asks three questions once for every WireCat tool.** Which languages you write and speak (English and the system's language ticked on a new store; a store in use keeps its own, so Enter changes nothing), which other WireCat tools to install (installed ones are marked), and whether commands and agents may only read. The answers sit in the `setup` section of `~/.config/WireCat/config.json`; "read only" caps every profile of every tool, over MCP too. Agents, pipes, `--json`, `--no-input` and `CI` are never asked. `askSetupQuestions` lets a tool's `setup` ask them again.
+
 ## 0.402.0 — 24.10.2026
 
 ### Changed — may break callers
@@ -17,6 +31,12 @@ shape of this file.
 
 - **Voice-note search no longer turns an English word into another real English word.** A word in a transcript widens to the spellings speech recognition garbles only past a dictionary of its language: Russian as before, and now English and Spanish, following the store's word-form languages (`search_stemmers`). Before, «cost» also found «cast». A Latin word with no dictionary for its language, and English and Spanish number words, no longer widen.
 
+### Added
+
+- **`watchMirrors` keeps folder mirrors in step.** One cycle per local save (after a quiet period, and only when the
+  files differ from the last sync), per remote change the CLI reports, per periodic local check and per full run;
+  each cycle syncs only the mirrors that need it, and a failed one is retried at the next poll.
+
 ## 0.401.0 — 24.10.2026
 
 ### Changed — may break callers

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

@@ -0,0 +1,68 @@
+import { type Installer } from "@wirecat/cli-base/update";
+import { type Question } from "./setup-answers.js";
+/** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
+export declare const LANGUAGES: readonly [{
+    readonly name: "russian";
+    readonly code: "ru";
+    readonly label: "Russian";
+    readonly script: "cyrillic";
+}, {
+    readonly name: "english";
+    readonly code: "en";
+    readonly label: "English";
+    readonly script: "latin";
+}, {
+    readonly name: "spanish";
+    readonly code: "es";
+    readonly label: "Spanish";
+    readonly script: "latin";
+}];
+export interface FirstRunIo {
+    ask: (prompt: string) => Promise<string>;
+    say: (text: string) => void;
+}
+export interface FirstRun {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    io: FirstRunIo;
+    /** Every question, as `setup` asks them; otherwise only those no WireCat tool asked yet. */
+    all?: boolean;
+    /** Where tools are looked for and how one is installed; injected by tests. */
+    installed?: (command: string) => boolean;
+    installer?: Installer;
+    install?: (argv: string[]) => boolean;
+}
+/**
+ * Only a person at a terminal is asked. An agent in a real terminal passes every terminal check and would wait on
+ * the question forever; a process locked read-only must write nothing, and every answer writes something.
+ */
+export declare const asksAtStart: (start: {
+    headless: boolean;
+    terminal: boolean;
+    env: NodeJS.ProcessEnv;
+    readOnlyLock: string | undefined;
+    path: readonly string[];
+}) => boolean;
+/** The system's language, as the first locale variable set names it: `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`. */
+export declare const systemLanguage: (env: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * The questions every WireCat tool shares, asked once for all of them: the answers go to the shared config
+ * file, the languages to the store. Only this, at a terminal, writes the permission answer.
+ */
+export declare const askSetupQuestions: (run: FirstRun) => Promise<Question[]>;
+/**
+ * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
+ * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
+ * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ */
+export declare const setupAtStart: (start: {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    path: readonly string[];
+    headless: boolean;
+    readOnlyLock?: string | undefined;
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    terminal?: boolean;
+}) => Promise<void>;

package/dist/cli/first-run.js

@@ -0,0 +1,224 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { installerOf, updateCommand } from "@wirecat/cli-base/update";
+import { DEFAULT_STEMMERS } from "../search/stem.js";
+import { openCache } from "../store/open.js";
+import { storePath } from "../store/path.js";
+import { sharedConfigPath } from "../store/shared-config.js";
+import { openStore } from "../store/store.js";
+import { readSecret } from "../terminal/prompt.js";
+import { WIRECAT_TOOLS } from "./help/first-screen.js";
+import { buildStems } from "./messenger/store-maintenance-command.js";
+import { QUESTIONS, readSetupAnswers, unanswered, writeSetupAnswers, } from "./setup-answers.js";
+/** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
+export const LANGUAGES = [
+    { name: "russian", code: "ru", label: "Russian", script: "cyrillic" },
+    { name: "english", code: "en", label: "English", script: "latin" },
+    { name: "spanish", code: "es", label: "Spanish", script: "latin" },
+];
+/** Commands that run without first-run questions: they serve agents, help, or open the store themselves. */
+const SKIPPED = new Set(["help", "guide", "completion", "mcp", "serve", "server", "update", "store"]);
+/**
+ * Only a person at a terminal is asked. An agent in a real terminal passes every terminal check and would wait on
+ * the question forever; a process locked read-only must write nothing, and every answer writes something.
+ */
+export const asksAtStart = (start) => !start.headless &&
+    start.terminal &&
+    !start.env.AI_AGENT &&
+    !start.env.CLAUDECODE &&
+    start.readOnlyLock === undefined &&
+    !SKIPPED.has(start.path[0] ?? "");
+/** The system's language, as the first locale variable set names it: `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`. */
+export const systemLanguage = (env) => {
+    const named = [env.LC_ALL, env.LC_MESSAGES, env.LANG, ...(env.LANGUAGE ?? "").split(":")]
+        .map((value) => value?.trim())
+        .find((value) => value && value !== "C" && value !== "POSIX" && !value.startsWith("C."));
+    return (named ?? Intl.DateTimeFormat().resolvedOptions().locale).slice(0, 2).toLowerCase();
+};
+const stemmersOf = (languages) => {
+    const latin = LANGUAGES.filter(({ name, script }) => script === "latin" && languages.includes(name));
+    return {
+        cyrillic: languages.includes("russian") ? "russian" : "none",
+        latin: latin.length ? latin.map(({ name }) => name).join(",") : "none",
+    };
+};
+const languagesOf = (stemmers) => LANGUAGES.filter(({ name }) => stemmers.cyrillic === name || stemmers.latin.split(",").includes(name)).map(({ name }) => name);
+/** Numbers from a list, as `1,3` or `1 3`; Enter keeps `chosen`. A wrong answer is asked again, then left as it was. */
+const choose = async (io, prompt, count, chosen) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = (await io.ask(prompt)).trim();
+        if (!answer)
+            return chosen;
+        if (/^(none|-)$/i.test(answer))
+            return [];
+        const numbers = answer
+            .split(/[\s,]+/)
+            .filter(Boolean)
+            .map(Number);
+        if (numbers.every((number) => Number.isInteger(number) && number >= 1 && number <= count))
+            return [...new Set(numbers)].sort((a, b) => a - b);
+        io.say(`Choose numbers from 1 to ${count}, separated by commas.`);
+    }
+    return chosen;
+};
+const yes = async (io, prompt) => /^y(es)?$/i.test((await io.ask(prompt)).trim());
+const onPath = (command, env) => {
+    const names = process.platform === "win32" ? [".cmd", ".exe", ""].map((ending) => command + ending) : [command];
+    return (env.PATH ?? env.Path ?? "").split(delimiter).some((folder) => names.some((name) => {
+        try {
+            accessSync(join(folder, name), process.platform === "win32" ? constants.F_OK : constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+};
+/** With the installer that installed this tool, its output on stderr so stdout stays data. */
+const installWith = (argv) => spawnSync(argv[0], argv.slice(1), { stdio: ["inherit", 2, 2] }).status === 0;
+const installerHere = () => {
+    try {
+        return installerOf(realpathSync(process.argv[1] ?? ""));
+    }
+    catch {
+        return "unknown";
+    }
+};
+const askLanguages = async ({ command, env, io }) => {
+    const store = await openStore({ env });
+    let rebuild = false;
+    try {
+        const saved = (await store.searchIndex.stemmers()) ?? undefined;
+        // A store already in use keeps the languages it was built with, so Enter changes nothing (RISK-1612).
+        const inUse = saved !== undefined || (await store.accounts.accounts()).length > 0;
+        const system = systemLanguage(env);
+        const ticked = inUse
+            ? languagesOf(saved ?? DEFAULT_STEMMERS)
+            : LANGUAGES.filter(({ code }) => code === "en" || code === system).map(({ name }) => name);
+        const numbers = ticked.map((name) => LANGUAGES.findIndex((one) => one.name === name) + 1);
+        io.say("Languages you write and speak — search finds every form of their words, and spellings speech mangles:");
+        LANGUAGES.forEach(({ name, label }, at) => {
+            io.say(`  ${at + 1}. ${label}${ticked.includes(name) ? " ✓" : ""}`);
+        });
+        const chosen = await choose(io, `Numbers (${numbers.join(",")}): `, LANGUAGES.length, numbers);
+        const next = stemmersOf(chosen.map((number) => LANGUAGES[number - 1].name));
+        const before = saved ?? DEFAULT_STEMMERS;
+        if (inUse && before.cyrillic === next.cyrillic && before.latin === next.latin)
+            return;
+        // Word search refuses until stems built by the old choice are rebuilt, so the change and the rebuild go together.
+        if (inUse &&
+            !(await yes(io, "Rebuild the word forms of every stored message now? Word search waits for it; a large store takes minutes. [y/N] "))) {
+            io.say(`Languages kept as they were; \`${command} setup\` asks again.`);
+            return;
+        }
+        await store.searchIndex.saveStemmers(next);
+        rebuild = inUse;
+    }
+    finally {
+        await store.close();
+    }
+    if (!rebuild)
+        return;
+    const database = await openCache(storePath(env));
+    try {
+        buildStems(database, (note) => io.say(`  ${note}`), { force: true });
+    }
+    finally {
+        database.close();
+    }
+};
+const askTools = async (run) => {
+    const { command, env, io } = run;
+    const installed = run.installed ?? ((name) => onPath(name, env));
+    const others = WIRECAT_TOOLS.filter((tool) => tool.command !== command);
+    const missing = others.filter((tool) => !installed(tool.command));
+    io.say("Other WireCat tools — they share this store, so one search finds everything:");
+    for (const tool of others) {
+        const at = missing.indexOf(tool);
+        io.say(`  ${at < 0 ? "✓ " : `${at + 1}.`} ${tool.command} — ${tool.does}`);
+    }
+    if (!missing.length)
+        return;
+    const chosen = await choose(io, "Numbers to install (none): ", missing.length, []);
+    const installer = run.installer ?? installerHere();
+    for (const number of chosen) {
+        const tool = missing[number - 1];
+        const argv = updateCommand(installer, tool.package);
+        if (!argv) {
+            io.say(`Install ${tool.command} with \`npm install -g ${tool.package}\`.`);
+            continue;
+        }
+        io.say(`Installing ${tool.command}: ${argv.join(" ")}`);
+        if (!(run.install ?? installWith)(argv))
+            io.say(`${tool.command} was not installed; run \`${argv.join(" ")}\`.`);
+    }
+};
+const PERMISSION_CHOICES = [
+    { answer: "readonly", text: "read only — search and read; nothing sends or changes, bots and agents included" },
+    { answer: "allow", text: "as now — each profile's own permissions" },
+];
+const askPermissions = async ({ io }, answers) => {
+    const now = answers.permissions ?? "allow";
+    const current = Math.max(1, PERMISSION_CHOICES.findIndex(({ answer }) => answer === now) + 1);
+    io.say("What may commands and agents do, in every WireCat tool?");
+    PERMISSION_CHOICES.forEach(({ text }, at) => {
+        io.say(`  ${at + 1}. ${text}`);
+    });
+    const [chosen = current] = await choose(io, `Number (${current}): `, PERMISSION_CHOICES.length, [current]);
+    return PERMISSION_CHOICES[chosen - 1].answer;
+};
+/** A section another tool wrote wrongly is asked again and written over, rather than stopping the command. */
+const answersAt = (path) => {
+    try {
+        return readSetupAnswers(path);
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * The questions every WireCat tool shares, asked once for all of them: the answers go to the shared config
+ * file, the languages to the store. Only this, at a terminal, writes the permission answer.
+ */
+export const askSetupQuestions = async (run) => {
+    const path = sharedConfigPath(storePath(run.env), run.env);
+    const answers = answersAt(path);
+    const asking = run.all ? [...QUESTIONS] : unanswered(answers);
+    for (const question of asking) {
+        run.io.say("");
+        if (question === "languages") {
+            await askLanguages(run);
+            writeSetupAnswers(path, { languages: true });
+        }
+        else if (question === "tools") {
+            await askTools(run);
+            writeSetupAnswers(path, { tools: true });
+        }
+        else
+            writeSetupAnswers(path, { permissions: await askPermissions(run, answers) });
+    }
+    return asking;
+};
+/**
+ * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
+ * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
+ * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ */
+export const setupAtStart = async (start) => {
+    const input = start.input ?? process.stdin;
+    const terminal = start.terminal ?? (input.isTTY === true && process.stderr.isTTY === true);
+    if (!asksAtStart({ ...start, terminal, readOnlyLock: start.readOnlyLock }))
+        return;
+    await askSetupQuestions({
+        command: start.command,
+        env: start.env,
+        all: start.path[0] === "setup",
+        io: {
+            ask: (prompt) => readSecret(prompt, { input, echo: true }),
+            say: (text) => process.stderr.write(`${text}\n`),
+        },
+    }).catch((error) => {
+        process.stderr.write(`setup questions skipped: ${error instanceof Error ? error.message : String(error)} — \`${start.command} setup\` asks them again\n`);
+    });
+};

package/dist/cli/help/first-screen.d.ts

@@ -17,6 +17,8 @@ export interface FirstScreen {
 }
 interface Tool {
     command: string;
+    /** The npm package `setup` installs it from. */
+    package: string;
     shown?: string;
     does: string;
 }

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

@@ -7,12 +7,37 @@ import { commandAt } from "../steps.js";
 import { EXAMPLE_PROFILE, installCommandHelp } from "./command-help.js";
 /** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
 export const WIRECAT_TOOLS = [
-    { command: "tg", does: "Telegram in the same local store: search, review and tasks offline" },
-    { command: "max", does: "MAX in the same local store: search, review and tasks offline" },
-    { command: "wa", does: "WhatsApp in the same local store: search, review and tasks offline" },
-    { command: "zm", does: "Zoom meetings: transcripts and summaries, searchable with your messages" },
-    { command: "drive", does: "Google Drive and Docs as local text, searchable with your messages" },
-    { command: "memo", shown: "memo context <person>", does: "one person across messengers, mail, notes and meetings" },
+    {
+        command: "tg",
+        package: "@wirecat/tg-cli",
+        does: "Telegram in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "max",
+        package: "@wirecat/max-cli",
+        does: "MAX in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "wa",
+        package: "@wirecat/whatsapp-cli",
+        does: "WhatsApp in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "zm",
+        package: "@wirecat/zoom-cli",
+        does: "Zoom meetings: transcripts and summaries, searchable with your messages",
+    },
+    {
+        command: "drive",
+        package: "@wirecat/drive-cli",
+        does: "Google Drive and Docs as local text, searchable with your messages",
+    },
+    {
+        command: "memo",
+        package: "@wirecat/cli-memo",
+        shown: "memo context <person>",
+        does: "one person across messengers, mail, notes and meetings",
+    },
 ];
 const WIDTH = 100;
 const widest = (texts) => texts.reduce((most, text) => Math.max(most, text.length), 0);

package/dist/cli/index.d.ts

@@ -56,6 +56,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, changesAuthorityAt, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, 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, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
@@ -128,6 +129,7 @@ export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOpt
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, 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";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";

package/dist/cli/index.js

@@ -51,6 +51,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, changesAuthorityAt, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { askSetupQuestions, asksAtStart, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, guideCommand, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
@@ -123,6 +124,7 @@ export { createProgram, run } from "./program.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { count, first, flag, fromFile, NONE_NAMED, plain, settingsFor, } from "./settings.js";
+export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";

package/dist/cli/messenger/context.js

@@ -1,9 +1,9 @@
 import { CliError } from "@wirecat/cli-base";
 import { servingProfiles } from "../../background/lock.js";
 import { FloodMemory, floodPathFor } from "../../sends/flood.js";
-import { guardFor } from "../../sends/guard.js";
+import { ceilingRefusal, guardFor } from "../../sends/guard.js";
 import { DEFAULT_PACE, Pacer, pacePathFor } from "../../sends/pace.js";
-import { assertStatsPermissionsCurrent, levelFor, readKeysForCommand, } from "../../sends/permissions.js";
+import { assertStatsPermissionsCurrent, CEILING_KEY, levelFor, readKeysForCommand, } from "../../sends/permissions.js";
 import { RecipientList, recipientsPathFor } from "../../sends/recipients.js";
 import { OFFLINE, servicesFor } from "../../services/index.js";
 import { openStore } from "../../store/store.js";
@@ -338,6 +338,8 @@ export const refuseLocalWrite = (context, command, permission) => {
     const { level, key } = levelFor(settings.permissions, permission);
     if (level === "allow" || (level === "ask" && context.agent))
         return;
+    if (key === CEILING_KEY)
+        throw ceilingRefusal(permission, command);
     throw new CliError(level === "ask" ? "confirmation_required" : "permission_error", `profile ${settings.profile} does not let ${permission} write (permissions.${key} is ${level}, from the ` +
         `${settings.permissionSources[key ?? ""] ?? "default"}); to allow it: ` +
         `${command} ${settings.profile} config set permissions.${permission} allow`, { permission });

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

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+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<{
@@ -19,3 +20,12 @@ export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
     error: string;
 }>;
 export declare const storeMaintenanceCommands: (messenger: Messenger) => Command[];
+/**
+ * Stems what is left, after rebuilding stems made by other stemmer choices than the store's setting —
+ * only here and in `store reindex`, never in a search's quick fill.
+ */
+export declare const buildStems: (database: CacheDatabase, note: (text: string) => void, { force }?: {
+    force?: boolean | undefined;
+}) => {
+    stemmed: number;
+};

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

@@ -409,7 +409,7 @@ const buildWordIndex = (database, note) => {
  * Stems what is left, after rebuilding stems made by other stemmer choices than the store's setting —
  * only here and in `store reindex`, never in a search's quick fill.
  */
-const buildStems = (database, note, { force = false } = {}) => {
+export const buildStems = (database, note, { force = false } = {}) => {
     const before = stemsState(database);
     if (!before)
         return { stemmed: 0 };

package/dist/cli/permission-keys.js

@@ -1,4 +1,4 @@
-import { keyForCommand, WRITE_KEYS } from "../sends/permissions.js";
+import { CEILING_KEY, keyForCommand, WRITE_KEYS } from "../sends/permissions.js";
 const pathOf = (command) => {
     const words = [];
     for (let at = command; at?.parent; at = at.parent)
@@ -39,4 +39,4 @@ export const knownBeside = (key, known) => {
         .filter((one) => one.split(".").length === depth && (parent === "" || one.startsWith(`${parent}.`)))
         .sort();
 };
-export const unknownPermissionKeys = (levels, known) => Object.keys(levels).filter((key) => !known.has(key));
+export const unknownPermissionKeys = (levels, known) => Object.keys(levels).filter((key) => key !== CEILING_KEY && !known.has(key));

package/dist/cli/program.js

@@ -19,6 +19,7 @@ import { refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, STORE_CHANGE_REFUSAL, } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
 import { byteCount, DEFAULT_COMMAND_MS, DEFAULT_OUTPUT_BYTES, execution } from "./execution.js";
+import { setupAtStart } from "./first-run.js";
 import { installHelp } from "./help/first-screen.js";
 import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
@@ -237,6 +238,16 @@ const runOnce = async (argv, definition, options) => {
             action.setOptionValue("dryRun", true);
         const path = commandPathOf(action);
         const lock = readOnlyLockOf(definition.app, commandEnv);
+        const input = options.stdin ?? process.stdin;
+        await setupAtStart({
+            command,
+            env: commandEnv,
+            path,
+            headless,
+            readOnlyLock: lock,
+            input,
+            terminal: !options.streams && input.isTTY === true && process.stderr.isTTY === true,
+        });
         if (lock && isLogin(action) && !flags.dryRun)
             throw readOnlyRefusal(lock, "log in or out");
         if (lock && isStoreChange(action) && !flags.dryRun)

package/dist/cli/settings.js

@@ -4,15 +4,28 @@ import * as v from "valibot";
 import { AI_ENTRIES, resolveAISettings } from "../analysis/settings.js";
 import { parseDuration } from "../domain/duration.js";
 import { envName, readOnlyLockOf } from "../ports/app.js";
-import { assertOverridesTighten, LEVELS, layerPermissions, permissionOverrides, RESOURCES, } from "../sends/permissions.js";
+import { assertOverridesTighten, CEILING_KEY, LEVELS, layerPermissions, permissionOverrides, RESOURCES, } from "../sends/permissions.js";
+import { storePath } from "../store/path.js";
+import { sharedConfigPath } from "../store/shared-config.js";
 import { loadSnakeCaseConfig } from "./config-keys.js";
 import { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 import { profilesHere } from "./messenger/accounts.js";
 import { usableProfileName } from "./profile.js";
+import { permissionCeiling } from "./setup-answers.js";
 const DEFAULT_LIMIT = DEFAULT_CONFIG.defaults.limit;
 const DEFAULT_KEEP_RUNS_FOR_DAYS = DEFAULT_CONFIG.defaults.keep_runs_for_days;
 /** On by default: a limit that is off protects nobody from a loop. */
 const DEFAULT_SENDS_PER_HOUR = DEFAULT_CONFIG.defaults.sends_per_hour;
+/** The first-run answer caps every profile; a config file cannot name its key, so only `setup` writes it. */
+const withCeiling = (permissions, env) => {
+    const ceiling = permissionCeiling(sharedConfigPath(storePath(env), env));
+    return ceiling
+        ? {
+            levels: { ...permissions.levels, [CEILING_KEY]: ceiling },
+            sources: { ...permissions.sources, [CEILING_KEY]: "setup answer" },
+        }
+        : permissions;
+};
 export const plain = (rule) => (issue) => `${rule}, not ${issue.received}`;
 const wholeNumber = plain("has to be a whole number, 1 or more");
 export const count = v.pipe(v.number(wholeNumber), v.integer(wholeNumber), v.minValue(1, wholeNumber));
@@ -221,7 +234,7 @@ export const settingsFor = (app, extension = {}) => {
         ]);
         const overrides = permissionOverrides(flags.permission);
         assertOverridesTighten(overrides, layerPermissions(fileLayers).levels);
-        const permissions = layerPermissions([["flag", overrides], ...fileLayers]);
+        const permissions = withCeiling(layerPermissions([["flag", overrides], ...fileLayers]), env);
         const updateCheck = first([
             [
                 extension.sourcePaths ? "config file: defaults" : "config defaults",

package/dist/cli/setup-answers.d.ts

@@ -0,0 +1,26 @@
+import type { Level } from "../sends/permissions.js";
+/** "allow" leaves every profile as its own configuration says. */
+export declare const PERMISSION_ANSWERS: readonly ["readonly", "ask", "allow"];
+export type PermissionAnswer = (typeof PERMISSION_ANSWERS)[number];
+/**
+ * The first-run answers every WireCat CLI shares. Languages live in the store (`search_stemmers`), so only the
+ * fact that they were asked is kept here.
+ */
+export interface SetupAnswers {
+    languages?: true;
+    tools?: true;
+    permissions?: PermissionAnswer;
+}
+export declare const QUESTIONS: readonly ["languages", "tools", "permissions"];
+export type Question = (typeof QUESTIONS)[number];
+export declare const readSetupAnswers: (path: string) => SetupAnswers;
+export declare const unanswered: (answers: SetupAnswers) => Question[];
+/** A section written wrongly is replaced; a file that is not JSON at all still refuses, naming itself. */
+export declare const writeSetupAnswers: (path: string, answers: SetupAnswers) => void;
+/**
+ * The level no command of any WireCat tool goes above, or `undefined` when the owner chose to leave them as they
+ * are. A file that cannot be read keeps everything read-only: reads still work, and `setup` writes it again.
+ */
+export declare const permissionCeiling: (path: string) => Level | undefined;
+/** `permissionCeiling` of this machine's shared config, for a tool that keeps its own levels: add it as `CEILING_KEY`. */
+export declare const setupPermissionCeiling: (env?: NodeJS.ProcessEnv) => Level | undefined;

package/dist/cli/setup-answers.js

@@ -0,0 +1,50 @@
+import { CliError } from "@wirecat/cli-base";
+import { storePath } from "../store/path.js";
+import { readSharedSection, sharedConfigPath, writeSharedSection } from "../store/shared-config.js";
+/** "allow" leaves every profile as its own configuration says. */
+export const PERMISSION_ANSWERS = ["readonly", "ask", "allow"];
+export const QUESTIONS = ["languages", "tools", "permissions"];
+const SECTION = "setup";
+export const readSetupAnswers = (path) => {
+    const section = readSharedSection(path, SECTION);
+    if (section === undefined)
+        return {};
+    const answers = section;
+    if (section === null ||
+        typeof section !== "object" ||
+        Array.isArray(section) ||
+        (answers.languages !== undefined && answers.languages !== true) ||
+        (answers.tools !== undefined && answers.tools !== true) ||
+        (answers.permissions !== undefined && !PERMISSION_ANSWERS.includes(answers.permissions)))
+        throw new CliError("configuration_error", `${path}: ${SECTION} holds what setup asked — languages: true, tools: true, permissions: ${PERMISSION_ANSWERS.join(" | ")}`);
+    return answers;
+};
+export const unanswered = (answers) => QUESTIONS.filter((question) => answers[question] === undefined);
+/** A section written wrongly is replaced; a file that is not JSON at all still refuses, naming itself. */
+export const writeSetupAnswers = (path, answers) => {
+    let kept = {};
+    try {
+        kept = readSetupAnswers(path);
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || !error.message.includes(`${SECTION} holds`))
+            throw error;
+    }
+    writeSharedSection(path, SECTION, { ...kept, ...answers });
+};
+/**
+ * The level no command of any WireCat tool goes above, or `undefined` when the owner chose to leave them as they
+ * are. A file that cannot be read keeps everything read-only: reads still work, and `setup` writes it again.
+ */
+export const permissionCeiling = (path) => {
+    let answer;
+    try {
+        answer = readSetupAnswers(path).permissions;
+    }
+    catch {
+        return "readonly";
+    }
+    return answer === "allow" ? undefined : answer;
+};
+/** `permissionCeiling` of this machine's shared config, for a tool that keeps its own levels: add it as `CEILING_KEY`. */
+export const setupPermissionCeiling = (env = process.env) => permissionCeiling(sharedConfigPath(storePath(env), env));

package/dist/documents/index.d.ts

@@ -3,6 +3,7 @@ export { type Complete, extractMemories } from "../services/documents/extraction
 export { documentIngestion, type IngestionOptions } from "../services/documents/ingestion.js";
 export { type DocumentKnowledge, documentKnowledge } from "../services/documents/knowledge.js";
 export { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.js";
+export { type MirrorTrigger, type MirrorWatchEvent, type MirrorWatchOptions, watchMirrors, } from "../services/documents/mirror-watch.js";
 export { conflictReport, fileMirrorState, type Mirror, type MirrorSyncOptions, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export type { SyncOptions } from "../services/documents/ports.js";
 export { extractDocumentMemories, type ImportedSource, type ProposalOptions } from "../services/documents/proposals.js";

package/dist/documents/index.js

@@ -3,6 +3,7 @@ export { extractMemories } from "../services/documents/extraction.js";
 export { documentIngestion } from "../services/documents/ingestion.js";
 export { documentKnowledge } from "../services/documents/knowledge.js";
 export { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.js";
+export { watchMirrors, } from "../services/documents/mirror-watch.js";
 export { conflictReport, fileMirrorState, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export { extractDocumentMemories } from "../services/documents/proposals.js";
 export { planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";

package/dist/sends/guard.d.ts

@@ -71,6 +71,8 @@ export interface SendGuardOptions {
     now?: () => Date;
 }
 /** A write the profile's level refuses, worded alike by the guard and by the check before connecting. */
+/** A write the first-run answer stops, whatever the profile allows. */
+export declare const ceilingRefusal: (key: PermissionKey, command: string) => CliError;
 export declare const levelRefusal: (refused: {
     profile: string;
     command: string;

package/dist/sends/guard.js

@@ -3,7 +3,7 @@ import { CliError } from "@wirecat/cli-base";
 import { MESSENGER_CHANGE_REFUSAL, readOnlyRefusal } from "../ports/app.js";
 import { FloodMemory, floodPathFor, holdEnd } from "./flood.js";
 import { SendJournal, sendsPathFor, } from "./journal.js";
-import { keyForWrite, levelFor, skipFlagFor } from "./permissions.js";
+import { CEILING_KEY, keyForWrite, levelFor, skipFlagFor } from "./permissions.js";
 import { RecipientList, recipientsPathFor } from "./recipients.js";
 const HOUR_MS = 60 * 60 * 1000;
 /**
@@ -51,8 +51,13 @@ const weightOf = ({ kind = "message", action, count, people }) => kind === "dele
 /** A scheduled message counts in the hour the provider sends it. */
 const timeOf = (entry) => Date.parse(entry.scheduledFor ?? entry.at);
 /** A write the profile's level refuses, worded alike by the guard and by the check before connecting. */
-export const levelRefusal = (refused, fix = `${refused.command} ${refused.profile} config set permissions.${refused.key} allow`) => new CliError("permission_error", `profile ${refused.profile} does not let ${refused.key} write (permissions.${refused.named} is ${refused.level}, ` +
-    `from the ${refused.permissionSources[refused.named ?? ""] ?? "default"}); to allow it: ${fix}`, { permission: refused.key });
+/** A write the first-run answer stops, whatever the profile allows. */
+export const ceilingRefusal = (key, command) => new CliError("permission_error", `${key} is not allowed: setup's answer keeps every WireCat tool read-only; ` +
+    `the owner changes it at a terminal with \`${command} setup\``, { permission: key });
+export const levelRefusal = (refused, fix = `${refused.command} ${refused.profile} config set permissions.${refused.key} allow`) => refused.named === CEILING_KEY
+    ? ceilingRefusal(refused.key, refused.command)
+    : new CliError("permission_error", `profile ${refused.profile} does not let ${refused.key} write (permissions.${refused.named} is ${refused.level}, ` +
+        `from the ${refused.permissionSources[refused.named ?? ""] ?? "default"}); to allow it: ${fix}`, { permission: refused.key });
 /**
  * These stop a model that was talked into sending by a message it read. They do **not** stop an
  * agent that edits the configuration itself — that needs a boundary outside this process

package/dist/sends/index.d.ts

@@ -3,7 +3,7 @@ export { type FloodDeadline, FloodMemory, type FloodState, FROZEN_HOLD_MS, flood
 export { type Asker, type GuardRequest, guardFor, type SendGuard, type SendGuardOptions, sendGuard, sharedJournal, } from "./guard.js";
 export { currentOperation, guardedWrite, type Operated } from "./guarded.js";
 export { type AccountAction, type ChatAction, type SendEntry, SendJournal, type SendKind, type SendOutcome, sendsPathFor, } from "./journal.js";
-export { assertStatsPermissionsCurrent, DEFAULT_PERMISSIONS, keyForCommand, keyForWrite, LEVELS, type Level, layerPermissions, levelFor, PERMISSIONS, type Permission, type PermissionKey, permissionFor, permissionOverrides, readKeysForCommand, skipFlagFor, WRITE_KEYS, } from "./permissions.js";
+export { assertStatsPermissionsCurrent, CEILING_KEY, DEFAULT_PERMISSIONS, keyForCommand, keyForWrite, LEVELS, type Level, layerPermissions, levelFor, PERMISSIONS, type Permission, type PermissionKey, permissionFor, permissionOverrides, readKeysForCommand, skipFlagFor, WRITE_KEYS, } from "./permissions.js";
 export { type Recipient, RecipientList, recipientsPathFor } from "./recipients.js";
 export { newOperationId, newSendId } from "./send-id.js";
 export { MAX_BUFFERED_UPLOAD_BYTES, readUpload, refusedPlace, uploadBlob, uploadBytes, uploadSize, } from "./upload.js";

package/dist/sends/index.js

@@ -2,7 +2,7 @@ export { FloodMemory, FROZEN_HOLD_MS, floodPathFor, LIMITED_HOLD_MS, } from "./f
 export { guardFor, sendGuard, sharedJournal, } from "./guard.js";
 export { currentOperation, guardedWrite } from "./guarded.js";
 export { SendJournal, sendsPathFor, } from "./journal.js";
-export { assertStatsPermissionsCurrent, DEFAULT_PERMISSIONS, keyForCommand, keyForWrite, LEVELS, layerPermissions, levelFor, PERMISSIONS, permissionFor, permissionOverrides, readKeysForCommand, skipFlagFor, WRITE_KEYS, } from "./permissions.js";
+export { assertStatsPermissionsCurrent, CEILING_KEY, DEFAULT_PERMISSIONS, keyForCommand, keyForWrite, LEVELS, layerPermissions, levelFor, PERMISSIONS, permissionFor, permissionOverrides, readKeysForCommand, skipFlagFor, WRITE_KEYS, } from "./permissions.js";
 export { RecipientList, recipientsPathFor } from "./recipients.js";
 export { newOperationId, newSendId } from "./send-id.js";
 export { MAX_BUFFERED_UPLOAD_BYTES, readUpload, refusedPlace, uploadBlob, uploadBytes, uploadSize, } from "./upload.js";

package/dist/sends/permissions.d.ts

@@ -43,6 +43,11 @@ export declare const layerPermissions: (layers: readonly [string, Readonly<Recor
     levels: Record<string, "allow" | "ask" | "deny" | "readonly">;
     sources: Record<string, string>;
 };
+/**
+ * The owner's first-run answer, held among a profile's levels: no key of any profile goes above it. Only `setup`
+ * at a terminal writes it, so an agent cannot lift it with `config set`.
+ */
+export declare const CEILING_KEY = "*";
 /**
  * The most specific key the owner set wins. A built-in default (`DEFAULT_PERMISSIONS`) only ever
  * tightens: against a broader key of the owner's, the stricter of the two holds — so

package/dist/sends/permissions.js

@@ -207,6 +207,11 @@ export const layerPermissions = (layers) => {
     }
     return { levels, sources };
 };
+/**
+ * The owner's first-run answer, held among a profile's levels: no key of any profile goes above it. Only `setup`
+ * at a terminal writes it, so an agent cannot lift it with `config set`.
+ */
+export const CEILING_KEY = "*";
 const ALLOWED = { level: "allow", key: null };
 const ORDER = { deny: 0, readonly: 1, ask: 2, allow: 3 };
 const nearest = (levels, key) => {
@@ -230,9 +235,14 @@ const FORMER_KEYS = { "chats.unmute": "chats.mute" };
  * A path nothing names is allowed.
  */
 export const levelFor = (permissions, key, defaults = DEFAULT_PERMISSIONS) => {
+    const found = profileLevel(permissions, key, defaults);
+    const ceiling = permissions[CEILING_KEY];
+    return ceiling && ORDER[ceiling] < ORDER[found.level] ? { level: ceiling, key: CEILING_KEY } : found;
+};
+const profileLevel = (permissions, key, defaults) => {
     const former = FORMER_KEYS[key];
     if (former !== undefined && permissions[key] === undefined)
-        return levelFor(permissions, former, defaults);
+        return profileLevel(permissions, former, defaults);
     const own = nearest(permissions, key);
     const builtIn = nearest(defaults, key);
     if (!builtIn || (own && own.depth >= builtIn.depth))

package/dist/services/documents/mirror-watch.d.ts

@@ -0,0 +1,39 @@
+import { CliError } from "@wirecat/cli-base";
+import type { PushStatePort } from "../../documents/push-model.js";
+import { type Mirror } from "./mirrors.js";
+/** What started a cycle: the first run, a local save, a remote change, the periodic local check, or a full run. */
+export type MirrorTrigger = "start" | "local" | "remote" | "check" | "full";
+export type MirrorWatchEvent<T> = {
+    triggers: MirrorTrigger[];
+    mirrors: string[];
+    result: T;
+} | {
+    triggers: MirrorTrigger[];
+    mirrors: string[];
+    error: CliError;
+};
+export interface MirrorWatchOptions<S> {
+    mirrors: Mirror[];
+    signal: AbortSignal;
+    kindOf(path: string): string | undefined;
+    stateOf(mirror: Mirror): PushStatePort<S>;
+    /** Ids of the mirrors whose remote files changed since the last call, or `all` when the provider cannot tell. */
+    remoteChanges?(signal: AbortSignal): Promise<string[] | "all">;
+    pollMs?: number;
+    quietMs?: number;
+    /** How often local files are compared with the state, for file events the system dropped. */
+    checkMs?: number;
+    /** How often every mirror is synced whatever the triggers said, for remote changes the provider listed late. */
+    fullMs?: number;
+    watchFolder?(root: string, changed: () => void): () => void;
+    sleep?(milliseconds: number, signal: AbortSignal): Promise<void>;
+    now?(): number;
+}
+/**
+ * Keeps mirrors in sync until `signal` aborts: a cycle at start, then one for each mirror whose files were saved
+ * (after `quietMs` without another save), whose remote files changed, or whose files differ from the state at the
+ * periodic check; every mirror at each full run. A local trigger syncs only when the files differ from the state, so
+ * the files a pull writes do not start another cycle. A failed cycle is reported and its mirrors tried again at the
+ * next poll; the watch goes on.
+ */
+export declare function watchMirrors<S, T>(sync: (mirrors: Mirror[], signal: AbortSignal) => Promise<T>, options: MirrorWatchOptions<S>): AsyncGenerator<MirrorWatchEvent<T>, void, void>;

package/dist/services/documents/mirror-watch.js

@@ -0,0 +1,155 @@
+import { watch } from "node:fs";
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { mirrorStatus } from "./mirrors.js";
+import { skippedName } from "./push.js";
+const sleep = (milliseconds, signal) => new Promise((resolve) => {
+    const finish = () => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", finish);
+        resolve();
+    };
+    const timer = setTimeout(finish, milliseconds);
+    signal.addEventListener("abort", finish, { once: true });
+});
+const watchFolder = (root, changed) => {
+    try {
+        const watcher = watch(root, { recursive: true }, (_event, name) => {
+            if (name === null || !name.split(/[\\/]/).some(skippedName))
+                changed();
+        });
+        // A lost watcher only delays a sync until the periodic check; it never stops the watch.
+        watcher.on("error", () => watcher.close());
+        return () => watcher.close();
+    }
+    catch {
+        return () => { };
+    }
+};
+const failure = (error) => isCliError(error) ? error : new CliError("provider_error", "the sync cycle failed");
+/**
+ * Keeps mirrors in sync until `signal` aborts: a cycle at start, then one for each mirror whose files were saved
+ * (after `quietMs` without another save), whose remote files changed, or whose files differ from the state at the
+ * periodic check; every mirror at each full run. A local trigger syncs only when the files differ from the state, so
+ * the files a pull writes do not start another cycle. A failed cycle is reported and its mirrors tried again at the
+ * next poll; the watch goes on.
+ */
+export async function* watchMirrors(sync, options) {
+    const { mirrors, signal } = options;
+    const pollMs = options.pollMs ?? 60_000;
+    const quietMs = options.quietMs ?? 2_000;
+    const checkMs = options.checkMs ?? 300_000;
+    const fullMs = options.fullMs ?? 1_800_000;
+    const now = options.now ?? Date.now;
+    const wait = options.sleep ?? sleep;
+    const byId = new Map(mirrors.map((mirror) => [mirror.id, mirror]));
+    const saved = new Map();
+    const retry = new Set();
+    let wake = new AbortController();
+    const closers = mirrors.map((mirror) => (options.watchFolder ?? watchFolder)(mirror.path, () => {
+        saved.set(mirror.id, now());
+        wake.abort();
+    }));
+    const differs = async (ids) => {
+        const chosen = [...ids].flatMap((id) => byId.get(id) ?? []);
+        try {
+            const items = await mirrorStatus(chosen, options.kindOf, options.stateOf);
+            return items.filter((item) => item.create.length || item.update.length).map((item) => item.id);
+        }
+        catch {
+            // An unreadable folder is for the sync to report.
+            return chosen.map((mirror) => mirror.id);
+        }
+    };
+    const run = async (triggers, ids) => {
+        const chosen = mirrors.filter((mirror) => ids.has(mirror.id));
+        const names = chosen.map((mirror) => mirror.id);
+        try {
+            return { triggers, mirrors: names, result: await sync(chosen, signal) };
+        }
+        catch (error) {
+            for (const id of names)
+                retry.add(id);
+            return { triggers, mirrors: names, error: failure(error) };
+        }
+    };
+    try {
+        if (signal.aborted)
+            return;
+        const first = await run(["start"], new Set(byId.keys()));
+        // A cycle cut short by the stop is the stop, not a failure.
+        if (signal.aborted && "error" in first)
+            return;
+        yield first;
+        let nextPoll = now() + pollMs;
+        let nextCheck = now() + checkMs;
+        let nextFull = now() + fullMs;
+        while (!signal.aborted) {
+            let due = Math.min(nextPoll, nextCheck, nextFull);
+            for (const at of saved.values())
+                due = Math.min(due, at + quietMs);
+            const until = due - now();
+            if (until > 0) {
+                await wait(until, AbortSignal.any([signal, wake.signal]));
+                if (wake.signal.aborted)
+                    wake = new AbortController();
+                if (signal.aborted)
+                    return;
+                continue;
+            }
+            const at = now();
+            const triggers = [];
+            const ids = new Set();
+            const add = (trigger, found) => {
+                const before = ids.size;
+                for (const id of found)
+                    ids.add(id);
+                if (ids.size > before && !triggers.includes(trigger))
+                    triggers.push(trigger);
+            };
+            if (at >= nextFull) {
+                add("full", byId.keys());
+                nextFull = at + fullMs;
+                nextCheck = at + checkMs;
+                nextPoll = at + pollMs;
+                saved.clear();
+                retry.clear();
+            }
+            else {
+                const settled = [...saved].filter(([, saveAt]) => saveAt + quietMs <= at).map(([id]) => id);
+                for (const id of settled)
+                    saved.delete(id);
+                if (settled.length)
+                    add("local", await differs(settled));
+                if (at >= nextCheck) {
+                    add("check", await differs(byId.keys()));
+                    nextCheck = at + checkMs;
+                }
+                if (at >= nextPoll) {
+                    nextPoll = at + pollMs;
+                    add("remote", retry);
+                    retry.clear();
+                    if (options.remoteChanges)
+                        try {
+                            const changed = await options.remoteChanges(signal);
+                            add("remote", changed === "all" ? byId.keys() : changed.filter((id) => byId.has(id)));
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                return;
+                            yield { triggers: ["remote"], mirrors: [], error: failure(error) };
+                        }
+                }
+            }
+            if (signal.aborted || !ids.size)
+                continue;
+            const event = await run(triggers, ids);
+            if (signal.aborted && "error" in event)
+                return;
+            yield event;
+        }
+    }
+    finally {
+        for (const close of closers)
+            close();
+    }
+}

package/dist/services/documents/push.d.ts

@@ -60,6 +60,8 @@ export interface PushResult {
     };
     stopped?: true;
 }
+/** Hidden files, `node_modules` and editor leftovers: never mirrored, and never a reason to sync. */
+export declare const skippedName: (name: string) => boolean;
 /** Files under `root` the target pushes. Hidden files, editor leftovers and symbolic links are never followed. */
 export declare const scanLocal: (root: string, kindOf: (path: string) => string | undefined, maxFiles?: number) => Promise<{
     files: LocalDocument[];

package/dist/services/documents/push.js

@@ -4,6 +4,8 @@ import { chmod, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, posix } from "node:path";
 import { CliError, isCliError } from "@wirecat/cli-base";
 const SKIPPED = /^(\.|node_modules$|~\$)|(~|\.swp|\.tmp)$/;
+/** Hidden files, `node_modules` and editor leftovers: never mirrored, and never a reason to sync. */
+export const skippedName = (name) => SKIPPED.test(name);
 const hashFile = (path) => new Promise((done, fail) => {
     const hash = createHash("sha256");
     createReadStream(path)

package/dist/store/shared-config.d.ts

@@ -12,6 +12,10 @@ export declare const readTaskCategoryEdits: (path: string) => TaskCategoryEdits
 export declare const applyTaskCategoryEdits: (base: readonly TaskCategory[], edits: TaskCategoryEdits, path: string) => readonly TaskCategory[];
 /** The edits that turn the default list into `list`, for moving a list an older build saved in the store. */
 export declare const editsFrom: (list: readonly TaskCategory[]) => TaskCategoryEdits;
+/** One section of the file, or `undefined` when the file or the section is missing. */
+export declare const readSharedSection: (path: string, section: string) => unknown;
+/** Writes one section (or drops it, with `undefined`), keeping every other key of the file. */
+export declare const writeSharedSection: (path: string, section: string, value: unknown) => void;
 /** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
 export declare const writeTaskCategoryEdits: (path: string, edits: TaskCategoryEdits | undefined) => void;
 /** Read again only when the file changed: a sync asks for the list once per message. */

package/dist/store/shared-config.js

@@ -39,7 +39,7 @@ const readJson = (path) => {
 };
 /** The `task_categories` section, or `undefined` when the file or the section is missing. */
 export const readTaskCategoryEdits = (path) => {
-    const section = readJson(path)?.[SECTION];
+    const section = readSharedSection(path, SECTION);
     if (section === undefined)
         return undefined;
     if (section === null || typeof section !== "object" || Array.isArray(section))
@@ -77,18 +77,22 @@ export const editsFrom = (list) => {
     }
     return edits;
 };
-/** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
-export const writeTaskCategoryEdits = (path, edits) => {
+/** One section of the file, or `undefined` when the file or the section is missing. */
+export const readSharedSection = (path, section) => readJson(path)?.[section];
+/** Writes one section (or drops it, with `undefined`), keeping every other key of the file. */
+export const writeSharedSection = (path, section, value) => {
     const file = readJson(path) ?? {};
-    if (edits === undefined || Object.keys(edits).length === 0)
-        delete file[SECTION];
+    if (value === undefined)
+        delete file[section];
     else
-        file[SECTION] = edits;
+        file[section] = value;
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${process.pid}.tmp`;
     writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
     renameSync(temporary, path);
 };
+/** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
+export const writeTaskCategoryEdits = (path, edits) => writeSharedSection(path, SECTION, edits === undefined || Object.keys(edits).length === 0 ? undefined : edits);
 /** Read again only when the file changed: a sync asks for the list once per message. */
 export const taskCategoriesReader = (path) => {
     let seen;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.402.0",
+  "version": "0.404.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",