@wirecat/cli-core 0.555.0 → 0.557.0

package/CHANGELOG.md

@@ -7,10 +7,54 @@ shape of this file.
 
 ## Unreleased
 
+## 0.557.0 — 02.11.2026
+
+### Added
+
+- **Invoices and payments in the store (store version 45).** `store.finance` adds, lists and shows invoices with
+  their lines and payments, allocates a payment to invoices and sums what open invoices still owe per currency
+  (`openTotals`). Money is an integer in the currency's minor units (`CURRENCY_SCALES`, ISO 4217), passed and read as
+  decimal strings; an unknown currency is refused and nothing is converted. A total must equal its lines, and an
+  allocation never exceeds the payment or the invoice or crosses currencies; triggers back the code. The status
+  follows confirmed allocations; only the owner issues a draft or voids an invoice.
+- **An agent's or an import's invoice or payment is a proposal.** The owner's entry is confirmed at once; a bot's
+  waits as `invoice` or `payment` in `proposalRegistry`, and only the owner decides it. A pending payment's
+  allocations never count against an invoice, so they never block the owner's own. Confirming one counts them in the
+  same write, or is refused while other confirmed payments already cover the invoice; rejecting drops them.
+- **`invoice:<id>` and `payment:<id>` references,** with `refs.summaries` titles such as
+  `42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)`.
+
+### Fixed
+
+- **Mail `review` gives three examples**, as the command lint asks; `--waiting` stays in its help.
+
+## 0.556.0 — 02.11.2026
+
+### Added
+
+- **A processing mark per holder and mail account** (`src/mail/marks.ts`): `review --holder <name>` reads what is
+  stored past the holder's mark, by store order (`emails.id`), so mail stored late is not skipped; bulk mail, envelopes
+  and drafts are skipped and counted, partial mail held until whole. `messages acknowledge --holder <name> --cursor
+  <cursor>` moves the mark forward; a read-only scheduled run may run it. Kept in `sync_cursors` as
+  `consumer:<holder>`, no schema change. `readPastMark`, `acknowledgeMark`, `marksOf`, `markItem` and the
+  `mail_mark` entity are exported for `status`; `store.mail` gains `emailsAfter`, `newestEmailId`, `statesLike` and
+  `emailHits`.
+
 ## 0.555.0 — 02.11.2026
 
 ### Added
 
+- **Each chat keeps its own point of reading for tasks.** `review --new`, `inbox --new`, the messenger's read state
+  and other agents move their own points, so a message one of them showed could be skipped by the next task pass.
+  `tasks status` lists every chat that can hold tasks (not channels or Saved Messages) with how far it was read for
+  tasks, how many stored messages wait after that, and how many arrived late inside the stretch already read
+  (history fetched afterwards). `tasks review <chat>` gives the waiting messages, oldest first, with the chat's open
+  tasks, and moves nothing; `tasks acknowledge <chat> <message>` moves the point once the tasks are written, never
+  back. A chat never read starts 14 days back; `--since-time` reads a stretch again. The points live in
+  `store_settings`, so no migration; `SyncStore.taskAnalysisMarks`, `taskAnalysisMark` and `setTaskAnalysisMark`
+  read and write them. The follow-ups skill uses them. New permission key `tasks.acknowledge`.
+  A read again only updates and closes tasks: `tasks add` refuses a message the chat's point already passed
+  (`task.already-read`) unless given `--open-new`; a message that already has a task is returned as before.
 - **`review` for mail CLIs** (`mailReadCommands`): every stored email, both sides, in threads that changed since a
   point, in messenger `review`'s item shape plus `email` (people, labels, sender score and the marks `bulk`,
   `list_id`, `rule_id`); `--new` keeps a point per mailbox, `--unanswered [duration]` keeps threads whose newest email
@@ -21,6 +65,21 @@ shape of this file.
   `email` gains optional `bulk`, `list_id` and `rule_id`, and its `summary` view may carry `email`.
 - **`tasks agenda` over an email account fills `owed`, `waiting` and `stale`** from its threads, with the same rule
   of whose turn a thread is as mail `review`; before, they were empty and `stale` true.
+- **`config repair` mends a settings file whose JSON is broken only in its syntax**, without AI or network (the file
+  may hold keys). It fixes a byte-order mark, `//` and `/* */` comments, trailing commas, a missing comma between
+  entries on separate lines, unquoted keys, single-quoted text, and closing brackets missing at the end. Every value,
+  permissions included, stays as written, in the file's key order. The old file is kept beside it as
+  `config.json.bak-<time>` in its old mode, and the new one is written atomically at 0600. It refuses damage with
+  more than one reading (two entries on one line, a key twice, a bare word as a value, a file that stops after a
+  closing bracket or inside a value, text that is not JSON or not text) with `configuration_error` and the line and
+  column, and changes nothing. It prints the line and kind of each fix, never a value; `--dry-run` writes nothing.
+  `--json` gives `file`, `found`, `repaired`, `dry_run`, `changes` (`{ line, kind }`), `backup`, and for a file that
+  needs nothing `reason` (`nothing to repair`, `no settings file`); a refusal is the error reason `config.unrepairable`
+  with `details.file`, `details.line` and `details.column`.
+  It changes what a later run may do, so the read-only lock refuses it and an MCP server runs it only with
+  `mcp.authority`; an agent's shell may not repair a file cut off before its end. `repairConfigText` exports it.
+- **`doctor` offers `<tool> config repair` as the `fix` of an `invalid_json` issue** when the repair would succeed, so
+  the desktop can show a Repair button; a command refused on such a file names it too.
 
 ### Fixed
 

package/dist/cli/config-command.js

@@ -1,13 +1,17 @@
-import { CliError, pathsAreOverridden } from "@wirecat/cli-base";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { CliError, pathsAreOverridden, writeSecurely } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command, Option } from "commander";
 import { envName } from "../ports/app.js";
 import { agentOf } from "../runs/run-context.js";
 import { AUTHORITY_KEY, BOT_API_KEY, LEVELS, levelFor } from "../sends/permissions.js";
+import { fixVerb } from "./config-issues.js";
+import { REPAIR_WORDS, repairConfigText } from "./config-repair.js";
 import { baseContext, environmentOf } from "./context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "./effects.js";
 import { itemOf, renderAnswer } from "./envelope.js";
 import { knownBeside, knownPermissionKeys, unknownPermissionIssues, } from "./permission-keys.js";
+import { profileFree } from "./profile.js";
 import { fromFile, NONE_NAMED } from "./settings.js";
 import { nextStep } from "./steps.js";
 import { changeStoreSetting, isStoreSetting, offersStoreSetting, storeSettings, storeSettingsOf, } from "./store-settings.js";
@@ -51,7 +55,7 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             ...(settings.configIssues ?? []),
             ...unknownPermissionIssues(this, settings, app.command, permissionKey),
         ])
-            renderer.warn(`${issue.what}, so it is left out${issue.fix ? ` — \`${issue.fix}\` removes it` : ""}`);
+            renderer.warn(`${issue.what}, so it is left out${issue.fix ? ` — \`${issue.fix}\` ${fixVerb(issue)}s it` : ""}`);
         if (overridden) {
             renderer.note(`${envName(app, "CONFIG_DIR")}, ${envName(app, "STATE_DIR")} or ${envName(app, "CACHE_DIR")} is set — ` +
                 "a session is still read from the usual keyring entry, but a sign-in made with them is kept apart, in a " +
@@ -140,8 +144,66 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             }));
         });
     }
+    command.addCommand(repairCommand(app, config));
     return command;
 };
+/**
+ * Mends JSON syntax with one reading and keeps every value (NEED-2178): no network, no AI, since the file may hold
+ * keys. Anything else is refused with nothing changed.
+ */
+const repairCommand = (app, config) => profileFree(grantsAuthority(annotate(new Command("repair"), {
+    effects: LOCAL_WRITE,
+    examples: [`${app.command} config repair`, `${app.command} config repair --dry-run`],
+}), { unless: "dryRun" }))
+    .summary("fix the settings file's JSON syntax, keeping every value")
+    .description("fix broken JSON syntax in the settings file — comments, a missing or extra comma, unquoted keys, single " +
+    "quotes, missing closing brackets at the end — keeping every value, with a backup beside it; refuses " +
+    "anything with more than one reading and changes nothing then")
+    .option("--dry-run", "say what it would fix, and change nothing")
+    .action(function () {
+    const dryRun = this.opts().dryRun === true;
+    const context = baseContext(this, (flags, options) => config.resolveSettings(flags, { ...options, readOnly: true, needsProfile: false, withIssues: true }));
+    const { settings, renderer, env } = context;
+    const file = settings.configPath;
+    // The desktop reads these names (wirecat-desktop#83).
+    const answer = (fields) => renderAnswer(this, context, itemOf({ file, found: existsSync(file), dry_run: dryRun, changes: [], backup: null, ...fields }));
+    if (!existsSync(file)) {
+        answer({ repaired: false, reason: "no settings file" });
+        return;
+    }
+    const bytes = readFileSync(file);
+    const result = repairConfigText(bytes.toString("utf8"));
+    if (result.state === "valid") {
+        answer({ repaired: false, reason: "nothing to repair" });
+        return;
+    }
+    if (result.state === "refused")
+        throw new CliError("configuration_error", `${file}: cannot repair it safely — ${result.why}, at line ${result.line}, column ${result.column}; ` +
+            "nothing was changed, so fix that part by hand", { reason: "config.unrepairable", file, line: result.line, column: result.column });
+    const cut = result.fixes.some((one) => one.kind === "missing_closer");
+    // What came after the cut may have been a deny; only the owner decides the shorter file is what they meant.
+    if (cut && !dryRun && (environmentOf(this).agent || agentOf(env)))
+        throw new CliError("permission_error", `${file} stops before its end, and a setting after the cut may be lost — the owner repairs it in a terminal`);
+    let backup = null;
+    if (!dryRun) {
+        backup = backupPathFor(file);
+        writeSecurely(backup, bytes, statSync(file).mode & 0o777);
+        writeSecurely(file, result.text, 0o600);
+    }
+    answer({ repaired: !dryRun, changes: result.fixes, backup });
+    for (const one of result.fixes)
+        renderer.note(`line ${one.line}: ${dryRun ? "would fix" : "fixed"} ${REPAIR_WORDS[one.kind]}`);
+    if (backup)
+        renderer.note(`the old file is kept as ${backup}`);
+});
+/** Beside the file, so the owner finds it; a second repair in the same millisecond never replaces the first. */
+const backupPathFor = (file) => {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let path = `${file}.bak-${stamp}`;
+    for (let n = 2; existsSync(path); n++)
+        path = `${file}.bak-${stamp}-${n}`;
+    return path;
+};
 /**
  * A key no command or write is checked against would be saved and do nothing (BUG-137) — whether it
  * comes as `permissions.<key>` or inside a whole `permissions` object.

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

@@ -63,6 +63,8 @@ export declare const withoutSetting: (raw: unknown, setting: string) => {
 };
 /** The public shape: where in the file is the loader's own business. */
 export declare const publicIssue: ({ at: _, ...issue }: LocatedIssue) => ConfigIssue;
+/** What an issue's `fix` does to it: `config repair` mends the file, `config unset` removes the setting. */
+export declare const fixVerb: (issue: ConfigIssue) => string;
 /**
  * One line for a command that refuses to run on the file: the first problem, how to fix it, and how many more.
  * `doctor` is the command that lists them all, as the reader types it.

package/dist/cli/config-issues.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import * as v from "valibot";
+import { repairConfigText } from "./config-repair.js";
 const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const SECTIONS = ["personal", "bot"];
 const SHELL_SAFE = /^[A-Za-z0-9_.:@-]*$/;
@@ -295,6 +296,8 @@ export const withoutPath = (raw, at) => {
 export const withoutSetting = (raw, setting) => withoutPath(raw, settingPathOf(setting));
 /** The public shape: where in the file is the loader's own business. */
 export const publicIssue = ({ at: _, ...issue }) => issue;
+/** What an issue's `fix` does to it: `config repair` mends the file, `config unset` removes the setting. */
+export const fixVerb = (issue) => (issue.kind === "invalid_json" ? "repair" : "remove");
 /**
  * One line for a command that refuses to run on the file: the first problem, how to fix it, and how many more.
  * `doctor` is the command that lists them all, as the reader types it.
@@ -305,7 +308,7 @@ export const issueMessage = (issues, doctor = "doctor") => {
         return "";
     const more = issues.length - 1;
     return (`${first.file}: ${first.what}` +
-        (first.fix ? ` — remove it with \`${first.fix}\`` : "") +
+        (first.fix ? ` — ${fixVerb(first)} it with \`${first.fix}\`` : "") +
         (more === 0 ? "" : ` (and ${more} more problem${more === 1 ? "" : "s"} — \`${doctor}\` lists them all)`));
 };
 /**
@@ -316,8 +319,13 @@ export const issueMessage = (issues, doctor = "doctor") => {
  */
 export const checkConfigText = (text, { file, tool, schema, knownPermissions, }) => {
     const parsed = parseConfigText(text, file);
-    if ("issue" in parsed)
-        return { issues: [publicIssue(parsed.issue)], config: undefined };
+    if ("issue" in parsed) {
+        const issue = publicIssue(parsed.issue);
+        // Offered only where it would work, so the desktop never shows a Repair button that fails.
+        if (repairConfigText(text).state === "repaired")
+            issue.fix = `${tool} config repair`;
+        return { issues: [issue], config: undefined };
+    }
     // valibot reads a list as an object, so `[]` would pass for `{}`.
     if (!isNode(parsed.raw))
         return { issues: [wholeFile(file, "the file must hold a JSON object")], config: undefined };

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

@@ -0,0 +1,26 @@
+/**
+ * Repairs a settings file whose JSON is broken only in its syntax, without AI and without guessing (NEED-2178): a
+ * file can hold keys and tokens, so it never leaves the machine. A damage with one reading is fixed; anything else
+ * is refused, and the caller changes nothing.
+ */
+export type RepairKind = "byte_order_mark" | "comment" | "trailing_comma" | "missing_comma" | "unquoted_key" | "single_quotes" | "missing_closer";
+/** Where and what, never the text: a value may be a secret. */
+export interface RepairFix {
+    line: number;
+    kind: RepairKind;
+}
+export type RepairResult = {
+    state: "valid";
+} | {
+    state: "repaired";
+    text: string;
+    fixes: RepairFix[];
+} | {
+    state: "refused";
+    line: number;
+    column: number;
+    why: string;
+};
+/** What each fix mends, as a person reads it. */
+export declare const REPAIR_WORDS: Record<RepairKind, string>;
+export declare const repairConfigText: (text: string) => RepairResult;

package/dist/cli/config-repair.js

@@ -0,0 +1,252 @@
+/**
+ * Repairs a settings file whose JSON is broken only in its syntax, without AI and without guessing (NEED-2178): a
+ * file can hold keys and tokens, so it never leaves the machine. A damage with one reading is fixed; anything else
+ * is refused, and the caller changes nothing.
+ */
+/** What each fix mends, as a person reads it. */
+export const REPAIR_WORDS = {
+    byte_order_mark: "an invisible byte-order mark at the start",
+    comment: "a comment, which JSON does not allow",
+    trailing_comma: "a comma before a closing bracket",
+    missing_comma: "a missing comma",
+    unquoted_key: "a key without double quotes",
+    single_quotes: "text in single quotes",
+    missing_closer: "the file stops before its closing brackets — whatever followed this line was already lost",
+};
+class GiveUp {
+    at;
+    why;
+    constructor(at, why) {
+        this.at = at;
+        this.why = why;
+    }
+}
+const NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/;
+const LITERAL = /^(true|false|null)/;
+const KEY = /^[A-Za-z_$][\w$.-]*/;
+const ENDS_VALUE = /^[\s,\]}/]?$/;
+export const repairConfigText = (text) => {
+    try {
+        JSON.parse(text);
+        return { state: "valid" };
+    }
+    catch { }
+    const fixes = [];
+    const lineAt = (offset) => text.slice(0, offset).split("\n").length;
+    const fix = (kind, offset) => fixes.push({ kind, line: lineAt(offset) });
+    const giveUp = (why, offset = at) => {
+        throw new GiveUp(offset, why);
+    };
+    let at = 0;
+    let truncated = false;
+    let last = "open";
+    let lastEnd = 0;
+    // A nested value() moves it, which TypeScript's narrowing inside the loop cannot see.
+    const previous = () => last;
+    const skip = () => {
+        for (;;) {
+            while (/\s/.test(text[at] ?? ""))
+                at++;
+            if (text.startsWith("//", at)) {
+                fix("comment", at);
+                while (at < text.length && text[at] !== "\n")
+                    at++;
+            }
+            else if (text.startsWith("/*", at)) {
+                const end = text.indexOf("*/", at + 2);
+                if (end < 0)
+                    giveUp("a /* comment is never closed");
+                fix("comment", at);
+                at = end + 2;
+            }
+            else
+                return;
+        }
+    };
+    const string = () => {
+        const quote = text[at];
+        const start = at;
+        if (quote === "'")
+            fix("single_quotes", at);
+        at++;
+        let body = "";
+        for (;;) {
+            if (at >= text.length)
+                giveUp("the file stops inside a quoted text", start);
+            const char = text[at];
+            if (char === quote)
+                break;
+            if (text.charCodeAt(at) < 0x20)
+                giveUp("a line break inside a quoted text");
+            if (char === "\\") {
+                const next = text[at + 1] ?? "";
+                if (quote === "'" && next === "'")
+                    body += "'";
+                else if (/^["\\/bfnrt]$/.test(next))
+                    body += `\\${next}`;
+                else if (next === "u" && /^[0-9a-fA-F]{4}$/.test(text.slice(at + 2, at + 6))) {
+                    body += text.slice(at, at + 6);
+                    at += 4;
+                }
+                else
+                    giveUp("an escape JSON has no meaning for");
+                at += 2;
+                continue;
+            }
+            body += char === '"' ? '\\"' : char;
+            at++;
+        }
+        at++;
+        return JSON.parse(`"${body}"`);
+    };
+    const key = () => {
+        const char = text[at] ?? "";
+        if (char === '"' || char === "'")
+            return string();
+        const word = KEY.exec(text.slice(at))?.[0];
+        if (!word)
+            return giveUp("something other than a key where a key should be");
+        fix("unquoted_key", at);
+        at += word.length;
+        return word;
+    };
+    const scalar = () => {
+        const char = text[at] ?? "";
+        if (char === '"' || char === "'")
+            return { json: JSON.stringify(string()) };
+        const word = (NUMBER.exec(text.slice(at)) ?? LITERAL.exec(text.slice(at)))?.[0];
+        if (!word || !ENDS_VALUE.test(text[at + word.length] ?? ""))
+            return giveUp("a value that is not JSON — text needs quotes, and only true, false and null go without");
+        // A number the file stops on may be the start of a longer one.
+        if (at + word.length === text.length && NUMBER.test(word))
+            giveUp("the file stops inside a number");
+        at += word.length;
+        return { json: word };
+    };
+    /** Members of an object or items of a list, with every syntax fix that has one reading. */
+    const members = (close, one) => {
+        const out = [];
+        at++;
+        last = "open";
+        let comma = -1;
+        for (;;) {
+            skip();
+            if (truncated)
+                return out;
+            if (at >= text.length) {
+                if (previous() === "close")
+                    giveUp("the file stops after a closing bracket, so which brackets are missing has two readings");
+                if (previous() === "comma")
+                    fix("trailing_comma", comma);
+                fix("missing_closer", text.length);
+                truncated = true;
+                return out;
+            }
+            const char = text[at];
+            if (char === close) {
+                if (previous() === "comma")
+                    fix("trailing_comma", comma);
+                at++;
+                last = "close";
+                return out;
+            }
+            if (char === "}" || char === "]")
+                giveUp(`a ${char} where ${close} should close`);
+            if (char === ",") {
+                if (previous() !== "value" && previous() !== "close")
+                    giveUp("a comma with nothing before it");
+                comma = at;
+                at++;
+                last = "comma";
+                continue;
+            }
+            if (previous() === "value" || previous() === "close") {
+                if (lineAt(at) === lineAt(lastEnd))
+                    giveUp("two entries on one line with no comma between them");
+                fix("missing_comma", lastEnd);
+            }
+            out.push(one());
+        }
+    };
+    const value = () => {
+        const char = text[at] ?? "";
+        let node;
+        if (char === "{") {
+            const seen = new Set();
+            node = {
+                object: members("}", () => {
+                    const start = at;
+                    const name = key();
+                    // JSON.parse keeps the last of two, which could lift a deny written first.
+                    if (seen.has(name))
+                        giveUp("a key appears twice in one object", start);
+                    seen.add(name);
+                    skip();
+                    if (at >= text.length)
+                        giveUp("the file stops after a key, before its value");
+                    if (text[at] !== ":")
+                        giveUp("a key with no colon after it");
+                    at++;
+                    skip();
+                    if (at >= text.length)
+                        giveUp("the file stops after a key, before its value");
+                    return [name, value()];
+                }),
+            };
+        }
+        else if (char === "[") {
+            node = {
+                array: members("]", () => {
+                    return value();
+                }),
+            };
+        }
+        else
+            node = scalar();
+        if (!truncated) {
+            last = "json" in node ? "value" : "close";
+            lastEnd = at;
+        }
+        return node;
+    };
+    try {
+        if (text.includes("\u0000") || text.includes(String.fromCharCode(0xfffd)))
+            giveUp("the file is not text", 0);
+        if (text.charCodeAt(0) === 0xfeff) {
+            fix("byte_order_mark", 0);
+            at = 1;
+        }
+        skip();
+        if (text[at] !== "{")
+            giveUp(at >= text.length ? "the file is empty" : "the file does not start with {");
+        const root = value();
+        skip();
+        if (at < text.length)
+            giveUp("more text after the closing }");
+        const repaired = `${serialise(root, "")}\n`;
+        JSON.parse(repaired);
+        return { state: "repaired", text: repaired, fixes };
+    }
+    catch (error) {
+        if (!(error instanceof GiveUp))
+            throw error;
+        const before = text.slice(0, error.at).split("\n");
+        return {
+            state: "refused",
+            line: before.length,
+            column: (before.at(-1)?.length ?? 0) + 1,
+            why: error.why,
+        };
+    }
+};
+/** `JSON.stringify(value, null, 2)` as `saveConfigFile` writes it, but in the file's own key order and numbers. */
+const serialise = (node, indent) => {
+    if ("json" in node)
+        return node.json;
+    const inner = `${indent}  `;
+    const parts = "object" in node
+        ? node.object.map(([name, item]) => `${inner}${JSON.stringify(name)}: ${serialise(item, inner)}`)
+        : node.array.map((item) => `${inner}${serialise(item, inner)}`);
+    const [open, close] = "object" in node ? ["{", "}"] : ["[", "]"];
+    return parts.length === 0 ? `${open}${close}` : `${open}\n${parts.join(",\n")}\n${indent}${close}`;
+};

package/dist/cli/messenger/tasks-analysis-command.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+import { type Messenger } from "./context.js";
+/**
+ * Each chat's own point of reading for tasks (`../../services/task-analysis.ts`): how far it was read, what waits, and
+ * the step that moves it. Apart from `inbox --new`, `review --new` and the messenger's read state, which other
+ * readers move.
+ */
+export declare const analysisCommands: (tasks: Command, messenger: Messenger) => void;