@wirecat/cli-core 0.598.0 → 0.599.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ shape of this file.
 
 ## Unreleased
 
+## 0.599.0 — 07.11.2026
+
+### Added
+
+- **`store recover`** tells whether the store file is damaged: it reads every page and every search index, names the
+  damaged tables, and answers in plain words what happened, likely causes, how to look further, what is affected, that
+  the messengers', mail servers' and Drive's own data is not, and the commands to run. It changes nothing.
+  `storeRecoveryCheck` gives the same to a CLI with its own `store` command.
+- **`store recover run`** rebuilds a damaged store: it copies every readable row into a new file with the `sqlite3`
+  program (3.43 or newer; node:sqlite has no recovery API), rebuilds every search index, the mentions and the vector
+  index from the data, checks the result, and puts it in place of the store, keeping the damaged file beside it. It
+  refuses while a WireCat timer is scheduled or a process has the store open, and names them. The answer lists the
+  tables that lost rows, the rows that point at lost ones, and the mail sync that fetches lost mail again.
+  `storeRecoveryRun` and `storeRecoverCommand` give it to other CLIs.
+- **`doctor` checks the store's health**: the file header, its size and the schema's own pages, in milliseconds. A
+  damaged store is explained in the answer's `store.damage` (`explainDamage`: what, causes, investigate, impact,
+  external_unaffected, steps) and points at `store recover`, the whole-file check. `storeSummary` takes
+  `{ deep, command }`, and `DOCTOR_DEEP_OPTION` words a CLI's own `--deep`.
+
+### Fixed
+
+- **Opening the store a second time in one process no longer drops the locks of the connection already open.** The
+  open touched the existing file through its own descriptor, and on Linux closing any descriptor of a file releases
+  every lock the process holds on it, so another process could checkpoint and delete the write-ahead log under a
+  writer that went on writing into it. That can damage the store. The file is now created only when it is missing.
+
 ## 0.598.0 — 07.11.2026
 
 ### Added

package/dist/cli/index.d.ts

@@ -99,6 +99,7 @@ export { accountFileFor, profilesHere, rememberAccount } from "./messenger/accou
 export { terminalAsker } from "./messenger/ask.js";
 export type { CompletionOptions } from "./messenger/complete-command.js";
 export { type ConnectOptions, connectFor, type Messenger, type MessengerContext, messengerContext, type ProfileState, type ReadConnection, type StoredMessages, } from "./messenger/context.js";
+export { DOCTOR_DEEP_OPTION, damageNotes } from "./messenger/doctor-command.js";
 export { COMMAND_NEEDS } from "./messenger/lacks.js";
 export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from "./messenger/mcp-command.js";
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
@@ -131,5 +132,6 @@ export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, a
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, type SharedContractOverride, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { type StoreInfo, sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";
+export { type RecoveryCheck, type RecoveryRun, recoveryNotes, storeRecoverCommand, storeRecoveryCheck, storeRecoveryRun, } from "./store-recover.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
 export { restartServers, type UpgradeContext } from "./upgrade-command.js";

package/dist/cli/index.js

@@ -89,6 +89,7 @@ export { readMeetingSeriesInventory } from "./meeting-series-inventory-read.js";
 export { accountFileFor, profilesHere, rememberAccount } from "./messenger/accounts.js";
 export { terminalAsker } from "./messenger/ask.js";
 export { connectFor, messengerContext, } from "./messenger/context.js";
+export { DOCTOR_DEEP_OPTION, damageNotes } from "./messenger/doctor-command.js";
 export { COMMAND_NEEDS } from "./messenger/lacks.js";
 export { httpTokenFile, serverEntry } from "./messenger/mcp-command.js";
 export { messageItem } from "./messenger/message-items.js";
@@ -120,5 +121,6 @@ export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, a
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";
+export { recoveryNotes, storeRecoverCommand, storeRecoveryCheck, storeRecoveryRun, } from "./store-recover.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
 export { restartServers } from "./upgrade-command.js";

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

@@ -8,6 +8,9 @@ import { type Messenger } from "./context.js";
  * open — each is a field in the answer, never an exception.
  */
 export declare const doctorCommand: (messenger: Messenger) => Command;
+export declare const DOCTOR_DEEP_OPTION = "also read every page of the store and check every search index (about 30 s for 6 GB); without it, only the file header and schema";
+/** The plain-words account of a damaged store, under the answer. */
+export declare const damageNotes: (store: unknown) => string[];
 /** What the messenger asked this profile to wait for, still in force — what the next command would be refused. */
 export declare const floodState: (memory: FloodMemory) => {
     path: string;

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

@@ -49,10 +49,24 @@ export const doctorCommand = (messenger) => {
         renderAnswer(this, { ...output, ...(renderer ? { renderer } : {}) }, itemOf(report, { next: unchecked ? [nextStep("doctor.online", { args: { online: true } })] : [] }));
         for (const fix of fixes)
             (renderer ?? output.renderer).note(`to make it private: ${fix}`);
+        for (const line of damageNotes(report.store))
+            (renderer ?? output.renderer).note(line);
     });
     command.addCommand(reportCommand(messenger));
     return command;
 };
+export const DOCTOR_DEEP_OPTION = "also read every page of the store and check every search index (about 30 s for 6 GB); without it, only the file header and schema";
+/** The shared doctor stays quick; `store recover` is its deep check, and a CLI may add `--deep` to its own doctor. */
+const summaryOptions = (command, app) => ({
+    deep: command.opts().deep === true,
+    command: app,
+});
+/** The plain-words account of a damaged store, under the answer. */
+export const damageNotes = (store) => {
+    const damage = store
+        ?.damage;
+    return damage ? [damage.what, damage.external_unaffected, ...damage.steps.map((step) => `next: ${step}`)] : [];
+};
 const INCLUDES = [
     "the version, the runtime and the operating system",
     "what `doctor` answers: paths with the home folder shown as ~, the store's schema and counts, the messenger's own checks",
@@ -149,7 +163,7 @@ const diagnose = async (command, messenger) => {
                 cli,
                 config: { path, found: existsSync(path), issues: [] },
                 settings: { error: messageOf(error) },
-                store: snakeKeys(await storeSummary(env)),
+                store: snakeKeys(await storeSummary(env, summaryOptions(command, app.command))),
                 runs: { directory: runsDirFor(app, env), kept: listRuns(runsDirFor(app, env)).length },
                 files: filesReport(files),
             },
@@ -174,7 +188,7 @@ const diagnose = async (command, messenger) => {
                 cli,
                 profile: null,
                 config,
-                store: snakeKeys(await storeSummary(env)),
+                store: snakeKeys(await storeSummary(env, summaryOptions(command, app.command))),
                 readers: engineStates(),
                 runs: { directory: runsDirFor(app, env), kept: listRuns(runsDirFor(app, env)).length },
                 files: filesReport(files),
@@ -210,7 +224,7 @@ const diagnose = async (command, messenger) => {
             account: { remembered: account?.account ?? null },
             // A session file on disk says nothing about whether the messenger still accepts it.
             login: { state: "not checked" },
-            store: snakeKeys(await storeSummary(env)),
+            store: snakeKeys(await storeSummary(env, summaryOptions(command, app.command))),
             readers: engineStates(),
             sends: sendsState(new SendJournal(sendsPathFor(app, profile, env))),
             flood: floodState(new FloodMemory(flood)),

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

@@ -1,12 +1,27 @@
 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<{
+/**
+ * `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. `health` is the quick
+ * check unless `deep`; `damage` says in plain words what a failed one means and what to run.
+ */
+export declare const storeSummary: (env: NodeJS.ProcessEnv, { deep, command }?: {
+    deep?: boolean;
+    command?: string;
+}) => Promise<{
     path: string;
     exists: boolean;
-    error?: undefined;
 } | {
+    health: {
+        checked: "deep" | "quick";
+        covers: string;
+        ok: boolean;
+        ms: number;
+        problems?: number | undefined;
+        damagedTables?: import("../../store/health.js").DamagedTable[] | undefined;
+        damagedSearchIndexes?: string[] | undefined;
+    };
+    damage?: import("../../store/damage.js").DamageExplanation | undefined;
     path: string;
     exists: boolean;
     schema: number;
@@ -15,6 +30,16 @@ export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
     chats?: number | undefined;
     messages?: number | undefined;
 } | {
+    health: {
+        checked: "deep" | "quick";
+        covers: string;
+        ok: boolean;
+        ms: number;
+        problems?: number | undefined;
+        damagedTables?: import("../../store/health.js").DamagedTable[] | undefined;
+        damagedSearchIndexes?: string[] | undefined;
+    };
+    damage?: import("../../store/damage.js").DamageExplanation | undefined;
     path: string;
     exists: boolean;
     error: string;

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

@@ -8,6 +8,8 @@ import { RULES_VERSION } from "../../conversations/link.js";
 import { syncsOneChat } from "../../ports/traits.js";
 import { isSealed, sealFile, unsealFile } from "../../sealed.js";
 import { fileSchemaOf, SPEAKS, writableBy } from "../../store/compatibility.js";
+import { explainDamage } from "../../store/damage.js";
+import { QUICK_HEALTH_CHECKS, storeHealth } from "../../store/health.js";
 import { migrate } from "../../store/migrations.js";
 import { openCache } from "../../store/open.js";
 import { storePath } from "../../store/path.js";
@@ -18,6 +20,7 @@ import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { lineOf, nextStep } from "../steps.js";
 import { storeInfoCommand } from "../store-info.js";
+import { storeRecoverCommand } from "../store-recover.js";
 import { answerOf } from "./ask.js";
 import { ENCRYPT_OPTION, passwordOf } from "./password.js";
 import { servingProfiles } from "./serve-command.js";
@@ -55,11 +58,28 @@ const readingOnly = async (path, read) => {
         database.close();
     }
 };
-/** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
-export const storeSummary = async (env) => {
+/**
+ * `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. `health` is the quick
+ * check unless `deep`; `damage` says in plain words what a failed one means and what to run.
+ */
+export const storeSummary = async (env, { deep = false, command } = {}) => {
     const path = storePath(env);
     if (!existsSync(path))
         return { path, exists: false };
+    const checked = await storeHealth(path, { deep });
+    const health = {
+        checked: checked.checked,
+        covers: deep ? "every page and every search index" : QUICK_HEALTH_CHECKS,
+        ok: checked.ok,
+        ms: checked.ms,
+        ...(checked.problems ? { problems: checked.problems } : {}),
+        ...(checked.damagedTables?.length ? { damagedTables: checked.damagedTables } : {}),
+        ...(checked.searchIndexes?.some((index) => !index.ok)
+            ? { damagedSearchIndexes: checked.searchIndexes.filter((index) => !index.ok).map((index) => index.name) }
+            : {}),
+    };
+    const damage = command ? explainDamage(checked, command) : null;
+    const healthOf = { health, ...(damage ? { damage } : {}) };
     try {
         return await reading(path, (database) => {
             const { version, writable } = schemaOf(database);
@@ -70,11 +90,12 @@ export const storeSummary = async (env) => {
                 speaks: SPEAKS,
                 writable,
                 ...(version > 0 ? { chats: count(database, "chats"), messages: count(database, "messages") } : {}),
+                ...healthOf,
             };
         });
     }
     catch (error) {
-        return { path, exists: true, error: messageOf(error) };
+        return { path, exists: true, error: messageOf(error), ...healthOf };
     }
 };
 /** A maintenance answer: one item, snake_case, its hints as steps where a registered one fits. */
@@ -91,6 +112,7 @@ export const storeMaintenanceCommands = (messenger) => [
     resetCommand(messenger),
     copiesCommand(),
     storeTablesCommand(messenger),
+    storeRecoverCommand({ command: messenger.app.command, version: messenger.app.version }),
 ];
 /** Renaming tables under a running `serve` would pull them from under its statements. */
 const refuseWhileServing = (command, messenger) => {

package/dist/cli/store-info.d.ts

@@ -9,4 +9,7 @@ export type StoreInfo = v.InferOutput<typeof storeInfoEntity>;
 export declare const storeInfo: (env: NodeJS.ProcessEnv) => Promise<StoreInfo>;
 export declare const storeInfoCommand: () => Command;
 /** `store info` for a tool with no `store` command of its own. */
-export declare const sharedStoreCommand: () => Command;
+export declare const sharedStoreCommand: (app?: {
+    command: string;
+    version?: string;
+}) => Command;

package/dist/cli/store-info.js

@@ -7,6 +7,7 @@ import { fileFacts, openSqlite, pendingNormalization, rowCounts, searchIndexStat
 import { environmentOf, outputFor } from "./context.js";
 import { LOCAL_READ } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
+import { storeRecoverCommand } from "./store-recover.js";
 /** Before version 6 the column does not exist, and a file behind this build is not migrated here. */
 const pendingIfKnown = (database) => database.prepare("SELECT 1 FROM pragma_table_info('messages') WHERE name = 'normalized_text'").get()
     ? pendingNormalization(database)
@@ -67,6 +68,9 @@ export const storeInfoCommand = () => annotate(new Command("info"), { output: {
     renderAnswer(this, outputFor(this), itemOf(answer));
 });
 /** `store info` for a tool with no `store` command of its own. */
-export const sharedStoreCommand = () => annotate(new Command("store"), { effects: LOCAL_READ })
-    .description("the shared local store every WireCat tool reads")
-    .addCommand(storeInfoCommand());
+export const sharedStoreCommand = (app) => {
+    const store = annotate(new Command("store"), { effects: LOCAL_READ })
+        .description("the shared local store every WireCat tool reads")
+        .addCommand(storeInfoCommand());
+    return app ? store.addCommand(storeRecoverCommand(app)) : store;
+};

package/dist/cli/store-recover.d.ts

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import { type DamageExplanation } from "../store/damage.js";
+import { type RecoverOptions, type Recovery } from "../store/recover.js";
+export interface RecoveryCheck {
+    path: string;
+    exists: boolean;
+    ok: boolean;
+    seconds?: number;
+    problems?: number;
+    damagedTables?: {
+        table: string | null;
+        problems: number;
+        sample: string;
+    }[];
+    damagedSearchIndexes?: {
+        name: string;
+        error?: string;
+    }[];
+    rows?: Record<string, number | null>;
+    explanation?: DamageExplanation | null;
+    inUse?: {
+        pid: number;
+        name: string;
+    }[] | null;
+    timers?: string[] | null;
+    sqlite3?: {
+        version: string | null;
+        usable: boolean;
+    };
+    /** The commands to run, in order. */
+    next: string[];
+}
+/** `store recover`: what is wrong with the store and what to run, reading every page; changes nothing. */
+export declare const storeRecoveryCheck: (env: NodeJS.ProcessEnv, command: string) => Promise<RecoveryCheck>;
+export type RecoveryRun = Omit<Recovery, "health" | "copyErrors"> & {
+    /** `sqlite3` reported these while copying; most are rows that broke a constraint and were skipped. */
+    copyErrors: number;
+    checkedOk: boolean;
+    /** The commands that fetch again what was lost, then the timers to start. */
+    next: string[];
+};
+/** `store recover run`: refuses while a WireCat timer is scheduled, so none writes to the file being replaced. */
+export declare const storeRecoveryRun: (env: NodeJS.ProcessEnv, { command, version, note, timers: scheduled, copy, }: {
+    command: string;
+    version?: string;
+    note?: (text: string) => void;
+    timers?: () => string[] | undefined;
+    copy?: RecoverOptions["copy"];
+}) => Promise<RecoveryRun>;
+/** The lines a person reads under the answer; the JSON carries the same in its fields. */
+export declare const recoveryNotes: (answer: RecoveryCheck | RecoveryRun) => string[];
+/** `store recover` and `store recover run`, for a CLI whose commands run on cli-core's context. */
+export declare const storeRecoverCommand: ({ command, version }: {
+    command: string;
+    version?: string;
+}) => Command;

package/dist/cli/store-recover.js

@@ -0,0 +1,153 @@
+import { existsSync } from "node:fs";
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { explainDamage } from "../store/damage.js";
+import { storeHealth } from "../store/health.js";
+import { storePath } from "../store/path.js";
+import { activeTimers, recoverStore, sqlite3Program, storeHolders, tableRows, } from "../store/recover.js";
+import { openSqlite } from "../store/store.js";
+import { environmentOf, outputFor } from "./context.js";
+import { LOCAL_READ, LOCAL_WRITE } from "./effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
+/** The tables whose counts say what the store holds; every other table is in `store info`. */
+const COUNTED = [
+    "accounts",
+    "chats",
+    "messages",
+    "attachments",
+    "emails",
+    "documents",
+    "notes",
+    "meetings",
+    "chunks",
+    "embeddings",
+    "mentions",
+];
+const stopTimers = (timers) => `systemctl --user stop ${timers.join(" ")}`;
+/** `store recover`: what is wrong with the store and what to run, reading every page; changes nothing. */
+export const storeRecoveryCheck = async (env, command) => {
+    const path = storePath(env);
+    if (!existsSync(path))
+        return { path, exists: false, ok: true, next: [] };
+    const health = await storeHealth(path, { deep: true });
+    let rows = {};
+    try {
+        const { database } = await openSqlite(path, { readOnly: true });
+        try {
+            const all = tableRows(database);
+            rows = Object.fromEntries(COUNTED.filter((table) => table in all).map((table) => [table, all[table] ?? null]));
+        }
+        finally {
+            database.close();
+        }
+    }
+    catch { }
+    const explanation = explainDamage(health, command);
+    const inUse = storeHolders(path) ?? null;
+    const timers = activeTimers() ?? null;
+    const sqlite3 = sqlite3Program();
+    const next = health.ok
+        ? []
+        : [
+            ...(timers?.length ? [stopTimers(timers)] : []),
+            ...(inUse ?? []).map(({ pid, name }) => `stop ${name} (process ${pid}): it has the store open`),
+            ...(sqlite3.usable ? [] : ["install sqlite3 3.43 or newer (apt install sqlite3, brew install sqlite)"]),
+            `${command} store recover run`,
+        ];
+    return {
+        path,
+        exists: true,
+        ok: health.ok,
+        seconds: Math.round(health.ms / 100) / 10,
+        problems: health.problems ?? 0,
+        damagedTables: health.damagedTables ?? [],
+        damagedSearchIndexes: (health.searchIndexes ?? [])
+            .filter((index) => !index.ok)
+            .map(({ name, error }) => ({ name, ...(error ? { error } : {}) })),
+        rows,
+        explanation,
+        inUse,
+        timers,
+        sqlite3: { version: sqlite3.version, usable: sqlite3.usable },
+        next,
+    };
+};
+/** `store recover run`: refuses while a WireCat timer is scheduled, so none writes to the file being replaced. */
+export const storeRecoveryRun = async (env, { command, version, note, timers: scheduled = activeTimers, copy, }) => {
+    const timers = scheduled() ?? [];
+    if (timers.length > 0)
+        throw new CliError("validation_error", `stop the timers first, they open the store: ${stopTimers(timers)}`, {
+            reason: "store.in-use",
+        });
+    const recovery = await recoverStore({
+        path: storePath(env),
+        command,
+        ...(version ? { version } : {}),
+        ...(note ? { note } : {}),
+        ...(copy ? { copy } : {}),
+    });
+    const mail = recovery.mailToFetch.map(({ account, emails }) => `mail <profile of ${account}> sync --rescan   # ${emails} emails`);
+    const lostMail = recovery.lost.some(({ table }) => table === "emails") && mail.length === 0
+        ? ["mail <profile> sync --rescan   # each mail profile"]
+        : [];
+    const { health, copyErrors, ...kept } = recovery;
+    return {
+        ...kept,
+        copyErrors: copyErrors.length,
+        checkedOk: health.ok,
+        next: [...mail, ...lostMail, "systemctl --user start <the timers stopped before>"],
+    };
+};
+/** The lines a person reads under the answer; the JSON carries the same in its fields. */
+export const recoveryNotes = (answer) => {
+    if ("keptAt" in answer) {
+        const lost = answer.lost.map(({ table, before, read, kept }) => `${table}: ${kept} kept of ${before ?? "an uncountable number"}${read > kept ? `, ${read - kept} read but unusable` : ""}`);
+        return [
+            `recovered in ${answer.seconds.total} s; the damaged file is kept at ${answer.keptAt}`,
+            ...(lost.length ? lost : ["no table lost a row"]),
+            ...answer.dangling.map(({ table, parent, rows }) => `${rows} rows of ${table} point at ${parent} rows the store does not hold`),
+            ...answer.next.map((line) => `next: ${line}`),
+        ];
+    }
+    if (!answer.exists)
+        return ["no store yet"];
+    if (answer.ok)
+        return [`the store is healthy (checked every page and search index in ${answer.seconds} s)`];
+    const why = answer.explanation;
+    return [
+        ...(why ? [why.what, ...why.impact, why.externalUnaffected] : []),
+        ...answer.next.map((line) => `next: ${line}`),
+    ];
+};
+/** `store recover` and `store recover run`, for a CLI whose commands run on cli-core's context. */
+export const storeRecoverCommand = ({ command, version }) => {
+    const recover = annotate(new Command("recover"), { effects: LOCAL_READ, examples: [`${command} store recover`] })
+        .summary("what is damaged in the store and how to recover it")
+        .description("check every page and search index of the store, say what is damaged, what it means and the commands that recover it; changes nothing")
+        .action(async function () {
+        const output = outputFor(this);
+        const answer = await storeRecoveryCheck(environmentOf(this).env ?? process.env, command);
+        renderAnswer(this, output, itemOf(snakeKeys(answer)));
+        if (output.format === "pretty")
+            for (const line of recoveryNotes(answer))
+                output.renderer.note(line);
+    });
+    recover.addCommand(annotate(new Command("run"), { effects: LOCAL_WRITE, examples: [`${command} store recover run`] })
+        .summary("rebuild a damaged store from every row it can read")
+        .description("copy every readable row into a new file with the sqlite3 program, rebuild the search indexes, mentions and vector index, " +
+        "check it, and put it in place of the store; the damaged file is kept beside it. Refuses while a WireCat timer or process has the store")
+        .action(async function () {
+        const output = outputFor(this);
+        const answer = await storeRecoveryRun(environmentOf(this).env ?? process.env, {
+            command,
+            ...(version ? { version } : {}),
+            note: (text) => output.renderer.note(text),
+        });
+        renderAnswer(this, output, itemOf(snakeKeys(answer)));
+        if (output.format === "pretty")
+            for (const line of recoveryNotes(answer))
+                output.renderer.note(line);
+    }));
+    return recover;
+};

package/dist/errors/reasons.js

@@ -156,6 +156,14 @@ const OTHERS = [
     ],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
+    validation("store.in-use", "a process or a scheduled timer has the store open; stop it, then recover the store"),
+    [
+        "store.sqlite3-missing",
+        "configuration_error",
+        "recovering the store needs the sqlite3 program, 3.43 or newer, with its .recover command",
+    ],
+    validation("store.recovery-failed", "the recovered store did not pass its check, so the store was left as it was"),
+    validation("store.changed-during-recovery", "the store was written to during the recovery, so it was left as it was"),
     [
         "store.vector-extension-missing",
         "configuration_error",

package/dist/store/damage.d.ts

@@ -0,0 +1,19 @@
+import type { StoreHealth } from "./health.js";
+/**
+ * What a damaged store means, in the owner's words: one structure the CLIs render and the desktop app can show as it
+ * is. Built from a health check only, so it never reads the damaged file again.
+ */
+export interface DamageExplanation {
+    what: string;
+    causes: string[];
+    investigate: string[];
+    impact: string[];
+    externalUnaffected: string;
+    steps: string[];
+}
+/**
+ * Tables a recovery rebuilds from the others: search indexes, the vector index, what the indexing finds, and the
+ * vectors, which a search by meaning computes again for any text that has none.
+ */
+export declare const isDerivedTable: (table: string, searchIndexes: readonly string[]) => boolean;
+export declare const explainDamage: (health: StoreHealth, command: string) => DamageExplanation | null;

package/dist/store/damage.js

@@ -0,0 +1,58 @@
+const DERIVED = new Set(["mentions", "involvements", "embeddings"]);
+const named = (tables) => tables.length <= 5 ? tables.join(", ") : `${tables.slice(0, 5).join(", ")} and ${tables.length - 5} more`;
+/**
+ * Tables a recovery rebuilds from the others: search indexes, the vector index, what the indexing finds, and the
+ * vectors, which a search by meaning computes again for any text that has none.
+ */
+export const isDerivedTable = (table, searchIndexes) => DERIVED.has(table) ||
+    table.startsWith("vector_index_") ||
+    searchIndexes.some((index) => table === index || table.startsWith(`${index}_`));
+const WIRECAT_UNITS = ["memo-*", "mail-*", "tg-*", "max-*", "wirecat-*"];
+export const explainDamage = (health, command) => {
+    if (health.ok)
+        return null;
+    const indexNames = (health.searchIndexes ?? []).map((index) => index.name);
+    const badIndexes = (health.searchIndexes ?? []).filter((index) => !index.ok).map((index) => index.name);
+    const tables = (health.damagedTables ?? []).map((one) => one.table).filter((table) => table !== null);
+    const sources = tables.filter((table) => !isDerivedTable(table, indexNames));
+    const derived = [...new Set([...tables.filter((table) => isDerivedTable(table, indexNames)), ...badIndexes])];
+    const unopened = health.error !== undefined;
+    const what = unopened
+        ? `the store file cannot be opened: ${health.error}`
+        : health.checked === "quick"
+            ? "the store file's header or schema is damaged"
+            : `the store file is damaged: ${health.problems ?? 0} problems` +
+                (sources.length ? ` in the data of ${named(sources)}` : "") +
+                (derived.length ? `${sources.length ? ", and" : " in"} the search data of ${named(derived)}` : "");
+    const impact = [
+        ...(sources.length
+            ? [`some rows of ${named(sources)} cannot be read; a recovery keeps every row it can read and names the rest`]
+            : []),
+        ...(derived.length
+            ? [`searches may miss results or fail; ${named(derived)} hold nothing that is not elsewhere, and are rebuilt`]
+            : []),
+        "reads that do not touch a damaged page work; a write that touches one fails until the store is recovered",
+    ];
+    return {
+        what,
+        causes: [
+            "the computer lost power or crashed, or the disk filled up, while a tool was writing",
+            "the file was copied, restored or synced while a tool had it open, or it sits in a synced or network folder",
+            "a fault of the disk itself",
+        ],
+        investigate: [
+            `journalctl --user ${WIRECAT_UNITS.map((unit) => `-u '${unit}'`).join(" ")} --since -14d | grep -i -e malformed -e corrupt -e 'disk full'`,
+            "journalctl -k --since -14d | grep -i -e 'I/O error' -e nvme -e ata",
+            `df -h ${health.path.replace(/\/[^/]*$/, "")}`,
+            ...(health.checked === "quick" ? [`${command} store recover`] : []),
+        ],
+        impact,
+        externalUnaffected: "only this computer's copy is damaged: Telegram, MAX, the mail servers and Google Drive keep their own data, " +
+            "so whatever is lost here can be fetched again by a sync",
+        steps: [
+            "stop every timer and server of the WireCat tools; `store recover run` lists the ones still running",
+            `${command} store recover run`,
+            "run the fetch commands it prints, then start the timers again",
+        ],
+    };
+};

package/dist/store/health.d.ts

@@ -0,0 +1,50 @@
+import type { CacheDatabase } from "./driver.js";
+/** One table's share of what `PRAGMA quick_check` found; `table` is null for pages no table claims. */
+export interface DamagedTable {
+    table: string | null;
+    problems: number;
+    /** The first line SQLite gave for it: page and cell numbers, never row content. */
+    sample: string;
+}
+export interface SearchIndexHealth {
+    name: string;
+    ok: boolean;
+    error?: string;
+}
+export interface StoreHealth {
+    path: string;
+    /** `quick`: the file header and the schema only, in milliseconds. `deep`: every page and every search index. */
+    checked: "quick" | "deep";
+    ok: boolean;
+    error?: string;
+    file?: {
+        bytes: number;
+        pages: number;
+        pageSize: number;
+        freePages: number;
+    };
+    damagedTables?: DamagedTable[];
+    /** Lines `quick_check` gave in all, capped at `QUICK_CHECK_LIMIT`. */
+    problems?: number;
+    searchIndexes?: SearchIndexHealth[];
+    ms: number;
+}
+export declare const QUICK_CHECK_LIMIT = 10000;
+/** What `doctor` checks by default, said where it answers. */
+export declare const QUICK_HEALTH_CHECKS = "the file header, its size against its page count, and the schema's own pages";
+export declare const fts5Tables: (database: CacheDatabase) => {
+    name: string;
+    sql: string;
+    external: boolean;
+}[];
+/** Groups the lines by the table whose tree they name: `Tree <root page> …` or `NULL value in <table>.<column>`. */
+export declare const damagedTables: (database: CacheDatabase, lines: string[]) => DamagedTable[];
+/** `rank = 0` checks the index's own structure, the only check a contentless index has; it writes nothing. */
+export declare const searchIndexHealth: (database: CacheDatabase) => SearchIndexHealth[];
+/**
+ * The store's health without changing it. `quick` takes milliseconds at any size; `deep` reads every page
+ * (about 30 s for 6 GB) and checks every search index, under a transaction it rolls back.
+ */
+export declare const storeHealth: (path: string, { deep }?: {
+    deep?: boolean;
+}) => Promise<StoreHealth>;