@wirecat/cli-core 0.597.0 → 0.599.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ 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
+
+- **`runScopeCases`** (`@wirecat/cli-core/testing`): cases that each remote command of a program runs inside
+  cli-core's run, so `--record` keeps a run named after it, and that `--timeout` ends it when the service never
+  answers. A command beside the run answers under the process run and fails. `neverAnswers` is the `fetch` for the
+  silent run.
+- **`inCommandRun(command, body)`** (`@wirecat/cli-core/cli`): runs `body` inside cli-core's run with the settings of
+  the app `run()` was given, which `run()` now hands every command (`environment.resolveSettings`).
+
+### Changed — may break callers
+
+- **`addMeetingCommands` takes `inRun`**, which `meetings sync` runs inside: pass `inCommandRun` from
+  `@wirecat/cli-core/cli`. The meetings module cannot reach cli-core's run itself.
+
+### Fixed
+
+- **The shared CRM, calendar and meetings commands run inside cli-core's run.** `sync` and the deal and lead writes
+  from `addCrmCommands`, every command from `addCalendarCommands`, and `meetings sync` answered under the process
+  run: `--record` kept no run, and `runs show` could not find the id they answered. A CLI that wrapped them in a run
+  of its own can drop that.
+- **An MCP server's `--permission` levels refuse a messenger write before it connects.** The early refusal of a change
+  on the messenger read the command's flags only, so `mcp serve --permission messages.send=deny` let the command
+  connect and left the refusal to the send guard. It now merges the server's levels as `baseContext` does.
+  `withAgentLevels(command, flags)` (`@wirecat/cli-core/cli`) is that merge, for a CLI's own resolver.
+- **An app's `mcp serve` over stdio ends when it was stopped before it listened.** `serveAppOverStdio` waited only
+  for an abort event, which a signal that had already fired never sends, so the server hung with stdin open.
+
 ## 0.597.0 — 07.11.2026
 
 ### Added

package/dist/calendar/cli/index.js

@@ -3,7 +3,7 @@ import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
 import { timezoneOf } from "@wirecat/cli-base/query";
 import { clockMeta } from "@wirecat/cli-base/standards";
 import { Argument, InvalidArgumentError, Option } from "commander";
-import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
+import { environmentOf, inCommandRun, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { changesStore, ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
 import { renderAnswer } from "../../cli/envelope.js";
@@ -77,17 +77,10 @@ const addCalendarCommandsDefinition = (program, options) => {
         renderAnswer(command, output, body, view ?? ((shown) => localTimesView(shown, zone(), output.color)));
     };
     /** Opens the profile for `work` and closes it before the answer prints, also when `work` fails. */
-    const within = async (command, work, view) => {
+    const within = (command, work, view) => inCommandRun(command, async () => {
         const run = await options.open(command, { readOnly: readsOnly(command) });
-        let body;
-        try {
-            body = await work(run);
-        }
-        finally {
-            await run.close?.();
-        }
-        answer(command, body, view);
-    };
+        answer(command, await work(run).finally(() => run.close?.()), view);
+    });
     const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} personal ${line}`) });
     const calendars = annotate(program.command("calendars").description("the account's calendars"), { effects: GROUP });
     withQuery(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json", "calendars list synced:true"), CALENDARS_QUERY).action(async (words, _opts, command) => {

package/dist/cli/context.d.ts

@@ -34,6 +34,8 @@ export interface BaseEnvironment {
     answer?: (question: string) => Promise<string | null> | string | null;
     /** Set by `run()`; a command's run is recorded only when it is known whose run it is. */
     app?: AppIdentity;
+    /** Set by `run()`: the app's own, so a shared command group opens its run with the app's settings. */
+    resolveSettings?: (flags: GlobalFlags, options?: ResolveOptions) => Settings;
     /** Set by `run()` from `process.platform` unless a test hands one in: the OS a command's paths and units are for. */
     platform?: NodeJS.Platform;
     /** The local speech recognizer in place of the downloaded model; tests hand one in. */
@@ -120,6 +122,10 @@ export declare const runBudgetOf: (command: Command, requests?: number) => RunBu
 export declare const setExitCode: (command: Command, code: number) => void;
 export declare const provide: (program: Command, environment: BaseEnvironment) => void;
 export declare const environmentOf: <E extends BaseEnvironment = BaseEnvironment>(command: Command) => E;
+/** The command's flags with an MCP server's `--permission` levels first: they reach a run on its agent, never in argv. */
+export declare const withAgentLevels: <F extends {
+    permission?: string[];
+}>(command: Command, flags: F) => F;
 /**
  * The input and output `readSecret` uses for this command: the run's own, so a prompt goes where the run's other
  * output goes and a test that captures it sees it. `readSecret(prompt, { ...secretInputOf(this), echo: true })`.
@@ -166,4 +172,10 @@ export interface BaseContext {
 type Resolve = (flags: GlobalFlags, options?: ResolveOptions) => Settings;
 /** Everything a command needs that no messenger decides, resolved once. */
 export declare const baseContext: (command: Command, resolveSettings: Resolve) => BaseContext;
+/**
+ * A shared group's command inside cli-core's run, with the settings of the app `run()` was given: recorded, and ended
+ * by `--timeout` (WC-LIFE-5, WC-LIFE-15). The group's own opener still decides whether it needs a profile. A program
+ * parsed without `run()` has no run to open, so `body` just runs.
+ */
+export declare const inCommandRun: <T>(command: Command, body: (events: EventSink) => Promise<T>) => Promise<T>;
 export {};

package/dist/cli/context.js

@@ -37,6 +37,11 @@ export const provide = (program, environment) => {
     environments.set(program, environment);
 };
 export const environmentOf = (command) => (environments.get(rootOf(command)) ?? {});
+/** The command's flags with an MCP server's `--permission` levels first: they reach a run on its agent, never in argv. */
+export const withAgentLevels = (command, flags) => {
+    const overrides = environmentOf(command).agent?.overrides ?? [];
+    return overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags;
+};
 /**
  * The input and output `readSecret` uses for this command: the run's own, so a prompt goes where the run's other
  * output goes and a test that captures it sees it. `readSecret(prompt, { ...secretInputOf(this), echo: true })`.
@@ -70,9 +75,7 @@ export const outputFor = (command) => {
 export const baseContext = (command, resolveSettings) => {
     const environment = environmentOf(command);
     const env = environment.env ?? process.env;
-    const flags = command.optsWithGlobals();
-    const overrides = environment.agent?.overrides ?? [];
-    const settings = resolveSettings(overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags, { env });
+    const settings = resolveSettings(withAgentLevels(command, command.optsWithGlobals()), { env });
     const { renderer, format, color, streams, compact, full } = resolveOutput({
         ...settings,
         env,
@@ -141,6 +144,17 @@ export const baseContext = (command, resolveSettings) => {
         },
     };
 };
+/**
+ * A shared group's command inside cli-core's run, with the settings of the app `run()` was given: recorded, and ended
+ * by `--timeout` (WC-LIFE-5, WC-LIFE-15). The group's own opener still decides whether it needs a profile. A program
+ * parsed without `run()` has no run to open, so `body` just runs.
+ */
+export const inCommandRun = (command, body) => {
+    const { resolveSettings } = environmentOf(command);
+    if (!resolveSettings)
+        return body(() => { });
+    return baseContext(command, (flags, options) => resolveSettings(flags, { ...options, needsProfile: false })).run(body);
+};
 /** `messages send` — the words that name commands, never the arguments: those can be a message. */
 const commandPath = (command) => {
     const words = [];

package/dist/cli/contract-templates.js

@@ -41,6 +41,7 @@ export const sharedCommandTemplate = (app, name) => {
                 },
                 accountId: 0,
                 write: unavailable,
+                inRun: unavailable,
             });
             const meetings = root.commands.find((command) => command.name() === "meetings");
             if (!meetings)

package/dist/cli/early-refusal.js

@@ -7,7 +7,7 @@ import { SendJournal, sendsPathFor } from "../sends/journal.js";
 import { CEILING_KEY, keyForCommand, levelFor, writeOfKey } from "../sends/permissions.js";
 import { newOperationId } from "../sends/send-id.js";
 import { commandPathOf } from "./command-contract.js";
-import { environmentOf } from "./context.js";
+import { withAgentLevels } from "./context.js";
 import { changesMessenger } from "./effects.js";
 import { refuseUnknownPermissionKeys } from "./permission-keys.js";
 import { NONE_NAMED, settingsFor } from "./settings.js";
@@ -33,7 +33,7 @@ export const refuseWriteBeforeConnecting = (action, { app, env, dryRun, resolve
     const key = keyForCommand(path);
     if (!key)
         return;
-    const settings = (resolve ?? settingsFor(app).resolveSettings)(action.optsWithGlobals(), {
+    const settings = (resolve ?? settingsFor(app).resolveSettings)(withAgentLevels(action, action.optsWithGlobals()), {
         env,
         needsProfile: false,
         readOnly: true,
@@ -91,9 +91,11 @@ export const refuseByCommandPermissions = (action, permissions, { app, env, dryR
     const preview = dryRun && app.messenger === false;
     if (lock && effects?.remote === "write" && !preview)
         throw readOnlyRefusal(lock, `run ${commandPathOf(action).join(" ")}`);
-    const flags = action.optsWithGlobals();
-    const overrides = environmentOf(action).agent?.overrides ?? [];
-    const settings = resolve(overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags, { env, needsProfile: false, readOnly: true });
+    const settings = resolve(withAgentLevels(action, action.optsWithGlobals()), {
+        env,
+        needsProfile: false,
+        readOnly: true,
+    });
     refuseUnknownPermissionKeys(action, settings, app.command, permissions);
     if (dryRun || settings.sources?.profile === NONE_NAMED)
         return;

package/dist/cli/index.d.ts

@@ -66,7 +66,7 @@ export { type CompactOptions, compactText, entityRows, GENERIC_ROW, type RowColu
 export { refuseUnknownKey } from "./config-command.js";
 export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
-export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, outputFor, provide, runBudgetOf, secretInputOf, } from "./context.js";
+export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, inCommandRun, outputFor, provide, runBudgetOf, secretInputOf, withAgentLevels, } from "./context.js";
 export { addContractInfo, type ContractEvidenceOptions, contractEvidence } from "./contract-evidence.js";
 export { sharedCommandTemplate } from "./contract-templates.js";
 export { type Closeable, withDeadline } from "./deadline.js";
@@ -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

@@ -57,7 +57,7 @@ export { compactText, entityRows, GENERIC_ROW, rowShapeOf, rowsOfEntity, SHARED_
 export { refuseUnknownKey } from "./config-command.js";
 export { checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
-export { baseContext, environmentOf, outputFor, provide, runBudgetOf, secretInputOf, } from "./context.js";
+export { baseContext, environmentOf, inCommandRun, outputFor, provide, runBudgetOf, secretInputOf, withAgentLevels, } from "./context.js";
 export { addContractInfo, contractEvidence } from "./contract-evidence.js";
 export { sharedCommandTemplate } from "./contract-templates.js";
 export { withDeadline } from "./deadline.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/program.js

@@ -228,6 +228,9 @@ const runOnce = async (argv, definition, options) => {
         commandSignal: control.signal,
         trackCloseable: control.trackCloseable,
         app: definition.app,
+        // `settingsFor`'s, which every CLI passes; the definition's type is looser only so a test can stub it.
+        resolveSettings: (definition.configuration ?? settingsFor(definition.app))
+            .resolveSettings,
         ...(definition.rows ? { rows: definition.rows } : {}),
         platform: options.platform ?? process.platform,
         exit,

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;